textlint

textlintで特定のルールのエラーを無視する

textlintにはさまざまなルールがありますが、特定の行や場所においてはルールを無効化したい場合があります。

例えば、asciidwango/js-primer: JavaScriptの入門書という書籍では、表記揺れを防止するためにtextlint-rule-prhというルールを使っています。

この書籍では、匿名関数無名関数の表記揺れを防止するために匿名関数統一する辞書が入っています。
しかし、どちらもよく使われる単語なので、「この書籍では無名関数の事を匿名関数と呼ぶ」という言及が必要です。

このように関数式では、名前を持たない関数を変数に代入できます。
このような名前を持たない関数を匿名関数(または無名関数)と呼びます。
https://asciidwango.github.io/js-primer/basic/function-declaration/より

この時、この部分だけはtextlint-rule-prhを無効化する必要があります。

textlintではそのような無効化を扱うフィルタールールという種類のルールが用意されています。

フィルタールールの一種としてコメントで指定範囲を無効化できるtextlint-filter-rule-commentsがあります。
このフィルタールールを有効化した場合は次のようにコメント(MarkdownならHTMLコメント)で特定のルールを無効化できます。

<!-- textlint-disable prh -->

このように関数式では、名前を持たない関数を変数に代入できます。
このような名前を持たない関数を**匿名関数**(または無名関数)と呼びます。

<!-- textlint-enable prh -->

導入方法は通常のルールと殆ど同じでnpmでインストールします。

npm install textlint-filter-rule-comments

そしてfiltersのフィールドにtextlint-filter-rule-commentsを追加するだけです。

{
    "filters": {
        "comments": true
    }
}

類似するフィルタールールとして指定文字列やパターンを無視できるtextlint-filter-rule-whitelistがあります。
こちらは文章全体で無視したいパターンなどを書けます。

{
    "filters": {
        "whitelist": {
            "allow": [
                "ignored-word",
                "/\\d+/",
                "/^===/m"
            ]
        }
    }
}

たとえば、js-primerだとコードをブラウザ上で実行できるコンソールモードのマクロとして{{book.console}}という特殊な文字列が自動で展開されるようになっています。
しかし、Markdown的にはただの文字列であるためなんらかのルールに引っかかる可能性があります。
そのため、"/{{[a-zA-Z.]*?}}/"というパターンを文書全体で無視しています。
ルールのオプションに無視リストを指定できる場合はそちらを優先した方が無意味な無効化が減って良いと思います。

textlintではフィルタールールもユーザーが作れるようになっています。
詳しくは次のドキュメントを参照すると良いですが、shouldIgnoreというメソッドを使う以外は基本的に通常のルールの作り方と同じです。

textlintがASTベースでチェックするのは誤検知を防止する目的が大きいので、すべての文章に万能なルールはないという前提にしています。そのため、すべてのルールはプラグインであり、フィルタールールもプラグインとなっています。

textlintのコアロジックだけを取り出した@textlint/kernelというコアモジュールがあるので、その上に便利な(最初から何でも入ってる)層を作ることもできます。

まとめ

textlintでは、フィルタールールを使うことで指定した範囲のエラーを無効化できる。