textlintの導入方法や使い方を確認してみた

CX事業本部Delivery部のアベシです。

こちらの記事では自然言語用リンターのtextlintの導入方法やルールの適応方法に調べてみましたので紹介します。
また、huskyと連携させてコミット前にチェックさせる方法も試しましたので併せて紹介したいと思います。

はじめに

ドキュメントを用意する場合、書いた後に文章の体裁やタイポの添削をご自分でされると思うのですが、私の場合どうしても抜け漏れが発生してしまうのが最近の悩みでした。
結果として体裁の整っていない文章をPRに出してしまったり、ブログに投稿してしまったり、やらかしてました。

こういった事を防ぎたいと思って相談したところ先輩に紹介してもらったのがtextlintです。
textlintはインストールしたルールに従って文章をチェックしてくれます。
こちらのリポジトリにも有るルールをそれぞれnpmインストールして追加できます。
デフォルトではMarkdownとtextファイルのチェックが可能です。 公式ページはこちら⇣

AWSサービス名のタイポ

冒頭で述べたやらかしの他にAWSのサービスのタイポも良くやってしまうことの一つでした。
弊社のブログのような外部公開する媒体では特に気をつけなきゃと思って探したところ、弊社の有志が専用のチェックルールtextlint-rule-aws-service-nameを作ってくれてました。
下のリンク先のブログで紹介しています。

今回はこちらも導入してAWSサービス名のチェックができるようにしてみます。

検証環境

以下の環境で検証しました。

textlintの導入

今回どのプロジェクトでも任意で使えるようにしたかったので、textlintをグローバルインストールする形で導入してみました。

textlintのインストール

インストールコマンドは以下です。

$ npm i -g textlint

ルールプリセットのインストール

次にルールのプリセットをインストールします。 今回は技術書向けのルールがまとまっているプリセットのtextlint-rule-preset-ja-technical-writingをインストールします。
インストールコマンドは以下です。

$ npm i -g textlint-rule-preset-ja-technical-writing

ルールの適応方法

インストールしたルールの適応方法は以下の２通りあります。

1. textlintコマンドにオプションで使いたいルールを指定する。
2. .textlintrc.jsonにルールを記載する。

1.の場合

コマンドにオプションを付けて実行する場合のコマンドは以下となります。

$ textlint --preset <プリセット名> <ファイルのパス>

// 使用例
$ textlint --preset ja-technical-writing ./sample-file/sample1.md
//結果
2:6   error  弱い表現: "思います" が使われています。  ja-technical-writing/ja-no-weak-phrase
5:14  error  文末が"。"で終わっていません。           ja-technical-writing/ja-no-mixed-period

2.の場合

今回は2.の.textlintrc.jsonにルールを記載する方法を使っていきます。
こちらの方法ではプリセットの一部のルールを適応させない、といったカスタマイズが可能です。
設定するには.textlintrc.jsonの作成が必要です。
以下のtextlintコマンドで作成されます。
グローバルインストールの場合は、ホームディレクトリに移動してから実行します。

$ cd ~
$ textlint -init

作成された.textlintrc.jsonを以下のように編集するとインストールしたプリセットtextlint-rule-preset-ja-technical-writingの全てのルールを使ってチェックされます。

~/.textlintrc.json

{
  "plugins": {},
  "filters": {},
  "rules": {
    "preset-ja-technical-writing": true
  }
}

リンターの実行

2.の.textlintrc.jsonにルールを書く場合は以下の手順でドキュメントのチェックを実行できます。
こちらではtextlintコマンドの後にファイルのパスのみ付ける事で実行が可能となります。

$ textlint  <ファイルのパス>

// 使用例
$ textlint ./sample-file/sample1.md
//結果
2:6   error  弱い表現: "思います" が使われています。  ja-technical-writing/ja-no-weak-phrase
5:14  error  文末が"。"で終わっていません。           ja-technical-writing/ja-no-mixed-period

プロジェクトのディレクト内に複数のドキュメントが有る場合はワイルドカードを使用してディレクトリ内の全てのドキュメントに対してチェックを走らすことができます。

// プロジェクトのルートディレクトで以下のコマンド実行
$ textlint *

//結果
textlint *

/Users/*********/product_practice/textlint-test/sample-files/sample1.md
  2:6   error  弱い表現: "思います" が使われています。  ja-technical-writing/ja-no-weak-phrase
  5:14  error  文末が"。"で終わっていません。           ja-technical-writing/ja-no-mixed-period

/Users/*********/product_practice/textlint-test/sample2.md
  2:6   error  弱い表現: "思います" が使われています。  ja-technical-writing/ja-no-weak-phrase
  5:14  error  文末が"。"で終わっていません。           ja-technical-writing/ja-no-mixed-period

✖ 4 problems (4 errors, 0 warnings)

ルールのカスタマイズ

.textlintrc.jsonファイルのプリセット名の値にルール名のプロパティを記載します。
その値にfalseを指定する事でプリセットに含まれる特定のルールのみ適用させない、ということが可能です。
ここでは先程の実行で該当したja-no-weak-phraseというルールを除外してみます。

~/.textlintrc.json

{
  "plugins": {},
  "filters": {},
  "rules": {
    "preset-ja-technical-writing": {
      "ja-no-weak-phrase": false
    }
  }
}

こちらでもう一度textlintを実行した結果が以下となります。

$ textlint ./sample-file/sample1.md

/Users/*********/Documents/blog/write_vs-code/textlint/sample-file/sample1.md
  5:14  error  文末が"。"で終わっていません。  ja-technical-writing/ja-no-mixed-period

✖ 1 problem (1 error, 0 warnings)

先程、ルールを除外する前に指摘されたerror 弱い表現: "思います" が使われています。が消えています。

AWSサービス名をチェックするルールを追加

冒頭で紹介したtextlint-rule-aws-service-nameを導入してみたいと思います。
まずは以下のコマンドでグローバルインストールします。

npm i -g textlint-rule-aws-service-name

.textlintrc.jsonに追加します

~/.textlintrc.json

{
  "plugins": {},
  "filters": {},
  "rules": {
    "preset-ja-technical-writing": {
      "ja-no-weak-phrase": false
    },
    "aws-service-name":true
  }
}

テスト用に以下のファイルを作りました。正しいサービス名称はStepとFunctionsの間にスペースが入ります。

./sample-file/wrong-aws-name.md

StepFunctions

結果

$ textlint ./sample-file/wrong-aws-name.md

/Users/**********/Documents/blog/write_vs-code/textlint/sample-file/wrong-aws-name.md
  1:1  ✓ error  StepFunctions => Step Functions  aws-service-name

✖ 1 problem (1 error, 0 warnings)
✓ 1 fixable problem.
Try to run: $ textlint --fix [file]

1:1 ✓ error StepFunctions => Step Functions aws-service-nameといった感じでちゃんと指摘されました。

✓ 1 fixable problem.という記述があります。これはtextlintコマンドを使って修正可能であることを意味しています。

警告を受けた項目の修正

チェックの結果✓ 1 fixable problem.となった項目は以下のコマンドで修正可能です。

$ textlint --fix <ファイルパス>

先程のAWSの名前を修正してみます。

$ textlint --fix ./sample-file/wrong-aws-name.md

結果

t$ extlint --fix sample-file/wrong-aws-name.md

/Users/**********/Documents/blog/write_vs-code/textlint/sample-file/wrong-aws-name.md
  1:1  ✔   StepFunctions => Step Functions  aws-service-name

✔ Fixed 1 problem

ファイル内の名称が自動的に修正されました　。

./sample-file/wrong-aws-name.md

Step Functions

huskyと組み合わせる

huskyを使うとコミットをトリガーにして指定したコマンドを走らすことができます。
コマンドが失敗する場合はコミットが失敗するようになります。
この機能を利用してコミットのタイミングでtextlintを実行して、チェックにひっかかったらコミットを失敗させるようにしてみました。
huskyについては下のブログで紹介しましたので、参考にしていただければと思います。

以下のコマンドでプロジェクトにhuskyを導入します。

$ npx husky-init && npm install

作成された.husky/pre-commitにtextlintの実行コマンドを記載します。

.husky/pre-commit

.husky/pre-commit

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

textlint * // ここにtextlintの実行コマンドを追加します。

対象のmarkdownファイルを修正してコミットすると、以下のエラーが出て期待通りコミットが失敗してくれました。

以上