Document data extraction

README.md

@@ -269,4 +269,37 @@ Use `elm-review suppress --help` to start using this, and read more about the
 the feature.
 
 Note that to avoid uncommitted suppression files in your project's main branch, it is recommended to use
-`elm-review suppress --check-after-tests` at the end of your test suite.
+`elm-review suppress --check-after-tests` at the end of your test suite.
+
+
+## Extract information
+
+`elm-review` has quite a nice way of traversing the files of a project and collecting data, especially when things
+aren't as simple as grepping or applying a regex on the code.
+
+While the tool is mainly designed around reporting issues, you can also use it to extract information from
+the codebase. You can use this to gain insight into your codebase, or provide information to other tools to enable
+powerful integrations.
+
+To make use of this feature, run `elm-review --extract --report=json` with a configuration containing a rule that uses
+[`Rule.withDataExtractor`](https://package.elm-lang.org/packages/jfmengels/elm-review/2.9.2/Review-Rule#withDataExtractor)
+
+The result for a rule will be stored under `<json>.extracts.<YourRuleName>`. To access it, you can then pipe the result
+into either a `Node.js` script, a tool that expects JSON, or [`jq`](https://stedolan.github.io/jq/) as in the example below.
+
+```bash
+elm-review --extract --report=json |
+    jq -r '.extracts["YourRuleName"]'
+
+# or to be slightly faster
+elm-review --extract --report=json --rules YourRuleName |
+    jq -r '.extracts["YourRuleName"]'
+```
+
+Combine the above out with `--watch` for fast feedback when editing your code!
+
+```bash
+elm-review --report=json --extract
+```
+
+and by reading the value at `<output>.extracts["YourRuleName"]` in the output.

src/Review/Rule.elm

@@ -21,8 +21,8 @@ module Review.Rule exposing
     , Error, error, errorWithFix, ModuleKey, errorForModule, errorForModuleWithFix, ElmJsonKey, errorForElmJson, errorForElmJsonWithFix, ReadmeKey, errorForReadme, errorForReadmeWithFix
     , globalError, configurationError
     , ReviewError, errorRuleName, errorMessage, errorDetails, errorRange, errorFixes, errorFilePath, errorTarget
-    , withDataExtractor, preventExtract
     , ignoreErrorsForDirectories, ignoreErrorsForFiles, filterErrorsForFiles
+    , withDataExtractor, preventExtract
     , reviewV3, reviewV2, review, ProjectData, ruleName, ruleProvidesFixes, getConfigurationError
     , Required, Forbidden
     )
@@ -247,11 +247,6 @@ first, as they are in practice a simpler version of project rules.
 @docs ReviewError, errorRuleName, errorMessage, errorDetails, errorRange, errorFixes, errorFilePath, errorTarget
 
 
-## Extract information
-
-@docs withDataExtractor, preventExtract
-
-
 ## Configuring exceptions
 
 There are situations where you don't want review rules to report errors:
@@ -273,6 +268,20 @@ reason or seemingly inappropriately.
 @docs ignoreErrorsForDirectories, ignoreErrorsForFiles, filterErrorsForFiles
 
 
+## Extract information
+
+As you might have seen so far, `elm-review` has quite a nice way of traversing the files of a project and collecting data.
+
+While you have only seen the tool be used to report errors, you can also use it to extract information from
+the codebase. You can use this to gain insight into your codebase, or provide information to other tools to enable
+powerful integrations.
+
+You can read more about how to use this in [_Extract information_ in the README](./#extract-information), and you can
+find the tools to extract data below.
+
+@docs withDataExtractor, preventExtract
+
+
 # Running rules
 
 @docs reviewV3, reviewV2, review, ProjectData, ruleName, ruleProvidesFixes, getConfigurationError
@@ -1932,7 +1941,35 @@ type Extract
     = Extract Encode.Value
 
 
-{-| Extract data from `elm-review`.
+{-| Extract arbitrary data from the codebase, which can be accessed by running
+
+```bash
+elm-review --report=json --extract
+```
+
+and by reading the value at `<output>.extracts["YourRuleName"]` in the output.
+
+    import Json.Encode
+    import Review.Rule as Rule exposing (Rule)
+
+    rule : Rule
+    rule =
+        Rule.newProjectRuleSchema "Some.Rule.Name" initialContext
+            -- visitors to collect information...
+            |> Rule.withDataExtractor dataExtractor
+            |> Rule.fromProjectRuleSchema
+
+    dataExtractor : ProjectContext -> Encode.Value
+    dataExtractor projectContext =
+        Json.Encode.list
+            (\thing ->
+                Json.Encode.object
+                    [ ( "name", Json.Encode.string thing.name )
+                    , ( "value", Json.Encode.int thing.value )
+                    ]
+            )
+            projectContext.things
+
 -}
 withDataExtractor :
     (projectContext -> Encode.Value)
@@ -3289,14 +3326,12 @@ type Error scope
 Use this if the rule extracts data and an issue is discovered that would make the extraction
 output incorrect data.
 
-    error : Error {}
-    error =
-        Rule.error
-            { message = "..."
-            , details = [ "..." ]
-            }
-            (Node.range node)
-            |> Rule.preventExtract
+    Rule.error
+        { message = "..."
+        , details = [ "..." ]
+        }
+        (Node.range node)
+        |> Rule.preventExtract
 
 -}
 preventExtract : Error a -> Error a