@primer/stylelint-diff-filter
v1.0.0
Published
Filter stylelint reports by files changed in git
Downloads
333
Readme
stylelint-diff-filter
This is a stylelint formatter that filters reports so that they only include warnings occurring on files and lines in a related git diff. Specifically, only the results that satisfy the following tests will be passed through to the configured formatter:
- Files whose path is included in the diff
- Warnings on lines included in the diff
The primary use case of this module is a log parser that automatically converts predictably formatted error messages into check annotations on GitHub.
Install
npm install -D @primer/stylelint-diff-filter
Usage
You can use this reporter via the stylelint
CLI with:
stylelint --custom-formatter=@primer/stylelint-diff-filter
If you use it this way, you'll likely want to configure it.
Diffs
Without any configuration, stylelint-diff-filter
obtains
a diff by shelling out to git diff -U1 <ref>
, where the <ref>
default is
master
. The -U1
flag tells git to only output one line of "context" rather
than the default three, which should be slightly faster to process.
The diff output is parsed with what-the-diff into an array of objects that represent diffs for individual files that may or may not have been renamed, each of which has one or more "hunks" that reference a start line number, line count, and one or more lines of diff text output.
Configuration
[Stylelint formatters] can't be configured via stylelint configuration files.
Rather than implementing its own customization system,
stylelint-diff-filter
offers configuration via the following environment
variables:
STYLELINT_DIFF
If provided, specifies the git diff
output to parse instead of calling
git diff -U1 <base>
internally. This can be helpful in large codebases where
you only want to parse the diff of the directory containing CSS files:
lint_path=app/assets/stylesheets
export STYLELINT_DIFF=$(git diff -U1 master -- $lint_path)
npx stylelint --custom-formatter=@primer/stylelint-diff-filter $lint_path
STYLELINT_DIFF_BASE
This allows you to specify a git ref against which to diff in the git diff -U1
<ref>
call (assuming STYLELINT_DIFF
is unset). The default is master
. For
example:
export STYLELINT_DIFF_BASE=release-1.0.0
npx stylelint --custom-formatter=@primer/stylelint-diff-filter
####STYLELINT_DIFF_FORMATTER
Specifies which stylelint formatter to call with the filtered results. This
can take a couple of different forms:
- The name of one of stylelint's built-in formatters:
string
(the default),compact
,json
, orverbose
- The path or name of a node module to
require()
.
For example, to use the JSON formatter:
export STYLELINT_DIFF_FORMATTER=json
stylelint --custom-formatter=@primer/stylelint-diff-filter --quiet > errors.json
API
The main export of @primer/stylelint-diff-filter
is a function that takes a
result and an optional object of options:
cwd
is the current working directory, which is used to strip prefixes from filenames in the diff to match what stylelint reports.base
is the ref against which togit diff
, which defaults toSTYLELINT_DIFF_BASE
ormaster
.diff
is thegit diff
output to parse, which defaults toSTYLELINT_DIFF
or the output ofgit diff -U1 <base>
.formatter
is the path or name of the stylelint formatter with which to format the filtered results, and defaults toSTYLELINT_DIFF_FORMATTER
orstring
(stylelint's own default).
Example
You may find it simpler to provide your own custom formatter that calls
@primer/stylelint-diff-filter
itself:
// reporter.js
const diff = require('@primer/stylelint-diff-filter')
const myAwesomeFormatter = require('./path/to/awesome-formatter')
module.exports = results => diff(results, {
formatter: myAwesomeFormatter
})
...which you would then use with:
npx stylelint --custom-formatter=path/to/reporter.js