@primer/stylelint-diff-filter v1.0.0

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