textlintはJavaScriptで自由にルールを追加することができる仕組みになっています。

しかし、普段JavaScriptをあんまり使ってない人にはBabelを使ったコード変換やMochaを使ったテストの設定など、ルールを書き始めるまでの環境づくりの方が大変です。

そのような環境設定をコマンド一発で作れて、textlintルールを作り始めることができるツールを作りました。

使い方

create-textlint-ruleを npm(Node.jsのパッケージマネージャ)でインストールするだけです。 Node.js(推奨はver6以上)をインストールすれば npm コマンドが自動で入っています。

$ npm install -g create-textlint-rule

create-textlint-ruleをインストールするとcreate-textlint-ruleコマンドが利用できます。

$ create-textlint-rule --help

  Create textlint rule with no configuration

  Usage
    $ create-textlint-rule rule-name

  Options
    --help  Show help
    --yarn  Use yarn for installing
    --yes   Pass --yes all for install process

  Examples
    $ create-textlint-rule awesome-rule

textlintのルールプロジェクトを作る

found-bugという”bug”をテキストから見つけるルールプロジェクトを作ってみます。

次のように、引数にルール名を渡すだけで、textlint-rule-found-bugというディレクトリにtextlintのルールが作成されます。

$ create-textlint-rule found-bug

実際のログは次のような感じで、一部対話的にルールの簡単なdescriptionなどを入力しますが、基本的にはEnterでいいはずです。

$ create-textlint-rule found-bug
Cloning into 'textlint-rule-found-bug'...
remote: Counting objects: 9, done.
remote: Compressing objects: 100% (7/7), done.
remote: Total 9 (delta 0), reused 4 (delta 0), pack-reused 0
Unpacking objects: 100% (9/9), done.
cd /Users/azu/.ghq/github.com/azu/own/textlint-rule-found-bug
Initialized empty Git repository in /Users/azu/.ghq/github.com/azu/own/textlint-rule-found-bug/.git/
Input information about your textlint rule
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help json` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg> --save` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
name: (textlint-rule-found-bug)
version: (1.0.0)
description: This textlint rule found bugs.
git repository:
license: (MIT)
About to write to /Users/azu/.ghq/github.com/azu/own/textlint-rule-found-bug/package.json:

{
  "version": "1.0.0",
  "keywords": [
    "textlint",
    "rule"
  ],
  "main": "lib/index.js",
  "files": [
    "lib/",
    "src/"
  ],
  "scripts": {
    "test": "textlint-scripts test",
    "build": "textlint-scripts build",
    "prepublish": "npm run --if-present build"
  },
  "devDependencies": {
    "textlint-scripts": "^1.2.2"
  },
  "name": "textlint-rule-found-bug",
  "description": "This textlint rule found bugs.",
  "directories": {
    "test": "test"
  },
  "author": "azu",
  "license": "MIT"
}


Is this ok? (yes)
Wait... Installing npm packages for development
Setup your README!
Generated README.md
✔ Complete: Let's create textlint rule

作成したtextlint-rule-found-bugディレクトリには、次のようなファイルが作られています。

textlint-rule-found-bug/
├── README.md
├── lib
│   ├── index.js
│   └── index.js.map
├── node_modules
├── package.json
├── src
│   └── index.js
└── test
    └── index-test.js

基本的にはsrc/index.jsにルールのコードを書いていき、test/index-test.jsにルールのテストを書きます。

lib/はnpmで公開するコードが置かれる場所なので、デフォルトでは.gitignoreされているためいじる必要はありません。

Build

次のコマンドを叩くことで、src/以下にあるES2015+で書かれたコードをBabelを使って変換しlib/以下においてくれます。

npm run build

Test

次のコマンドを叩くことで、test/以下にあるtextlint-testerとMochaを使ったテストを動かします。

テストコードの書き方はtextlint-testerを参照してください。

npm test

ルールの開発

などのドキュメントがあります。

また、textlintはASTを元にルールを書くため、次のASTビューアを見ながら構造を知ると書きやすくなります。

簡単な方法として既存のルールからやりたい事と近いものを見つけて、それをパクるのが近道だと思います。

100以上のルールがあり、自分が書いたものはcreate-textlint-ruleで作った構造とほぼ同じなので、コード部分に集中すれば問題ないはずです。

publish

ルールの公開は基本的にはnpmに公開します。 pacakge.jsonのversionを上げたりgit tagを貼るなどはnpm-versionを使うと簡単です。 semverなバージョンを上げたら、npm-publishコマンドで公開すれば完了です。

npm version patch
# npm version minor
# npm version major
npm publish

これで、npmに公開されたtextlint-rule-found-bugが、npmでインストールすることができます。

npm install textlint-rule-found-bug

後は、.textlintrcに設定して使えばいいだけです。

作ったルールの使い方も実はcreate-textlint-ruleが自動的にREADME.mdに書いてくれています。

## Usage

Via `.textlintrc`(Recommended)

```json
{
    "rules": {
        "found-bug": true
    }
}
```

Via CLI

```
textlint --rule found-bug README.md
```

作ったルールはWikiに追加してみましょう。

Tips

create-textlint-ruleを使い、作ったプロジェクト内で、textlintにルールを読み込ませて確認する方法。

プロジェクトをビルドして、textlintの--rulesdirで直接ルールを読み込んで使えば、publishせずに確認できます。

$ npm run build
$ $(npm bin)/textlint --rulesdir ./lib/ README.md
# $(npm bin) は ./node_modules/.bin と同じなので次でもOK
$ ./node_modules/.bin/textlint --rulesdir ./lib/ README.md

もしくは、ローカルで作ったプロジェクトをnpm installすることでも、publishせずに確認できます。

# 試したいプロジェクトで、textlint-rule-found-bugへのローカルパスを指定
$ npm install /path/to/textlint-rule-found-bug

おわりに

create-textlint-ruleとtextlint-scriptsを使うことで、面倒な環境はある程度簡単に作れるようになっています。

面白いtextlintのルールを自作して文章を改善の助けになればと思います。