npm package: @primer/stylelint-diff-filter
Description: Filter stylelint reports by files changed in git
Author: GitHub, Inc.
Latest version: 1.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](#diffs).
Specifically, only the results that satisfy the following tests will be passed
through to the configured [formatter](#stylelint_diff_formatter):

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

```sh
stylelint --custom-formatter=@primer/stylelint-diff-filter
```

If you use it this way, you'll likely want to [configure it](#configuration).

### Diffs
Without any [configuration](#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:

```sh
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:

```bash
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:

```sh
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`](#stylelint_diff_base) or `master`.
* `diff` is the `git diff` output to parse, which defaults to
  [`STYLELINT_DIFF`](#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`](#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:

```js
// 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:

```sh
npx stylelint --custom-formatter=path/to/reporter.js
```


## License

[MIT](./LICENSE) &copy; [GitHub](https://github.com/)

[stylelint formatter]: https://stylelint.io/developer-guide/formatters
[built-in formatters]: https://stylelint.io/developer-guide/formatters#stylelintformatters
[what-the-diff]: https://github.com/kuychaco/what-the-diff
[check annotations]: https://github.blog/2018-12-14-introducing-check-runs-and-annotations/