README
unified-diff
unified plugin to ignore unrelated messages. Currently works in PRs on Travis and GitHub Actions.
When working with natural language, having tools that check cumbersome tasks can be very useful (think alex or retext plugins). However, natural language isn’t as strict as code. Integrating natural language checking in a CI often doesn’t work well due to false positives. It’s possible to add a long list of exceptions, but this soon becomes unmanageable.
This plugin solves that problem, when in CIs, by ignoring any messages on unchanged lines. When run outside supported CIs this plugin doesn’t do anything.
Install
This package is ESM only:
Node 12+ is needed to use it and it must be import
ed instead of require
d.
npm:
npm install unified-diff
Use
Say we have this readme.md
.
Note the an an
.
This is an an example.
Then, someone creates a PR which adds the following diff:
diff --git a/readme.md b/readme.md
index 360b225..5a96b86 100644
--- a/readme.md
+++ b/readme.md
@@ -1 +1,3 @@
This is an an example.
+
+Some more more text. A error.
We have some natural language checking in lint.js
:
import {toVFile} from 'to-vfile'
import {reporter} from 'vfile-reporter'
import {unified} from 'unified'
import unifiedDiff from 'unified-diff'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import remarkRetext from 'remark-retext'
import retextEnglish from 'retext-english'
import retextRepeatedWords from 'retext-repeated-words'
import retextIndefiniteArticle from 'retext-indefinite-article'
toVFile.read('readme.md').then((file) => {
unified()
.use(remarkParse)
.use(
remarkRetext,
unified()
.use(retextEnglish)
.use(retextRepeatedWords)
.use(retextIndefiniteArticle)
)
.use(remarkStringify)
.use(unifiedDiff)
.process(file)
.then((file) => {
console.error(reporter(file))
process.exit(file.messages.length > 0 ? 1 : 0)
})
})
lint.js
is hooked up to run on Travis in .travis.yml
like so:
# ...
script:
- npm test
- node lint.js
# ...
(or in an equivalent GH Actions workflow file)
When run in CI, we’ll see the following printed on stderr(4).
Note that an an
on L1 is not included because it’s unrelated to this PR.
readme.md
3:6-3:15 warning Expected `more` once, not twice retext-repeated-words retext-repeated-words
3:22-3:23 warning Use `An` before `error`, not `A` retext-indefinite-article retext-indefinite-article
⚠ 2 warnings
As there are messages, the build exits with 1
, thus failing CI.
The user sees this and amends the PR to the following:
diff --git a/readme.md b/readme.md
index 360b225..5a96b86 100644
--- a/readme.md
+++ b/readme.md
@@ -1 +1,3 @@
This is an an example.
+
+Some more text. An error.
This time our lint task exits successfully, even though L1 would normally emit an error, but it’s unrelated to the PR.
API
This package exports a plugin as the default export.
unified().use(diff)
Ignore messages emitted by plugins before diff
for lines that did not change.
There are no options.
If there’s a TRAVIS_COMMIT_RANGE
, GITHUB_BASE_REF
and GITHUB_HEAD_REF
, or
GITHUB_SHA
environment variable, then this plugin runs, otherwise it does
nothing.
To do
- Add support for other CIs (ping if you want to work on this)
- Add non-CI support (I’m not yet sure how though)
PRs welcome!
Contribute
See contributing.md
in unifiedjs/.github
for ways
to get started.
See support.md
for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.