mirror of
https://github.com/jfmengels/elm-review.git
synced 2024-08-17 12:00:29 +03:00
Document data extraction
This commit is contained in:
parent
b2c2e896ba
commit
c3a068bafb
35
README.md
35
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.
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user