@primer/stylelint-diff-filter

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:

1. Files whose path is included in the diff
2. 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:

1. The name of one of stylelint's built-in formatters: string (the default), compact, json, or verbose
2. 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 to git diff, which defaults to STYLELINT_DIFF_BASE or master.
• diff is the git diff output to parse, which defaults to STYLELINT_DIFF or the output of git diff -U1 <base>.
• formatter is the path or name of the stylelint formatter with which to format the filtered results, and defaults to STYLELINT_DIFF_FORMATTER or string (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

License

MIT © GitHub