textlint 10.0.0をリリースしました。

変更点

textlint 10.0.0の主な変更点です。

🆕 Features

@textlint/ast-node-typesがTxtNodeの型定義を持つように

@textlint/ast-node-typesという内部的に使ってるものがtextlintのパーサが作るTxtNodeの型定義を持つようになりました。#358

textlintのASTを扱いたいTypeScriptユーザーはこれを利用できるので、textlint pluginを作りたいとかしたい人は便利かもしれません。

詳しくはTxtNodeのドキュメントを見てください

textlintがTypeScriptで扱えるように #248

以前の9.0.0のリリースでtextlintのコアエンジンである@textlint/kernelをTypeScript化しました。

今回の10.0.0で@textlint/kernelとtextlint(CLIも含む)がどちらもTypeScript化しました。 これによりTypeScriptからtextlintが扱いやすくなりました。

// Types
import {
    TextlintResult,
    TextlintFixResult,
    TextlintFixCommand,
    TextlintMessage,
    // Kernel rule/filter/plugin format
    TextlintKernelRule,
    TextlintKernelFilterRule,
    TextlintKernelPlugin,
    // Notes: Following interface will be separated module in the future.
    // textlint rule interface
    TextlintRuleCreator,
    TextlintRuleOptions,
    // textlint filter rule interface
    TextlintFilterRuleCreator,
    TextlintFilterRuleOptions,
    // textlint plugin interface
    TextlintPluginCreator,
    TextlintPluginOptions,
    TextlintPluginProcessor,
    TextlintPluginProcessorConstructor
} from "@textlint/kernel";

また、まだちょっとPublic APIの型定義が曖昧になっている(大抵はJSDocが正しい)ので、以下のIssueでPublic APIに対するテストの変換を行っています。 本体のソースコードはTypeScript化されていますが、テストコードはまだJavaScriptのままであるため、そこを徐々に変換していく予定です。(この変換する際に型がおかしいなら一緒に直す必要がある)

Reactのインフラ整備でもPublic APIに対するテスト重要性が語られていますが、まさにこういう移行時にはPublic APIへのテストを良くしていくと安定性が向上する感じです。

Behind the Scenes: Improving the Repository Infrastructure - React Blog

一緒に手伝ってくれる人は、いつでも募集しているのでTypeScript周りを改善したい人は上のIssueを見てみてください。(個人的には@textlint/kernelのPublic APIのテストがまだ足りていない印象です)

🔥 Breaking Change

10.0.0なのでいくつか破壊的な変更がありますが、textlintをCLIとして使う一般的なユーザーには殆ど影響はほぼありません。 主にtextlintをrequire("textlint")のようにモジュールとして使っている人は影響があるかもれません。

textlint: Export as ES module #337 #344

CommonJSとして出力していたものが、ES Modulesとして出力するように変更されました。

Before

module.exports = {
  textlint,
  TextLintEngine,
}

After

export { 
  textlint,
  TextLintEngine
}

これによってimportの仕方によっては影響があるかもしれません。 以前からnamed importしていた人には影響がないと思います。

次のような形で利用できます。

import { textlint } from "textlint"

or

const textlint = require("textlint").textlint

Stop to export unused name #344

次の使われてない値をexportしないようにしました。

  • TextLintNodeType
  • TextLintMessageSeverityLevel
  • TextLintMessageType
    • Use @textlint/ast-node-types insteadof it

📝 Documentaion

Improve Contributing Guide.

Issues/PR: #380 #379 #355 #352 #353 #341 by @Leko and @0x6b

Contributing Guideが色々と改善されました。 textlintにコミットしてみたいという人は、ここを読むとどうやってテストするかや直す場所に見つけ方などが分かります。

次の記事などにも書いていますが、textlintのコントビュートは歓迎です。 1つのテストを追加/変換、typoの修正、ドキュメントの追加、機能の追加/修正など色々とできることはあります。

簡単で手が出しやすいIssueにはgood first issueというラベルを付けているので、まずはそこから見てみると良いかもしれません。

♻️ Polish

Monorepo #270

@Lekoさんによって、次のモジュールはtextlintのmonorepoに追加されました。

  • textlint-formatter #359
  • textlint-ast-test #357
  • txt-ast-traverse #356
  • textlint-fixer-formatter #347

textlint-plugin-htmlをmonorepoに入れるべきかという議論があり、まだこれだけimportできていません。 主に自分がhtmlでチェックする対象を持っていないため、コアメンテナがいない状態でmonorepoに入れるのは良くないためです。 もし、textlintのHTMLプラグインに興味があり、もっと良くしていきたいという人は次のIssueに見てください。 コアにメンテをできる人がいるならばmonorepoに取り入れて改善するべきだと思います。

🎉 New Contributors

  • @Leko – リファクタリングやバグ修正、monorepo化などを手伝ってくれました
  • @0x6b - Contributing Guideの改善などを手伝ってくれました

何度も書いてますがコントビュートはいつでも歓迎です。

例えばルールを書くのもコントビュートの一種です。 textlintではtextlint-rule/organization(ルール全般)やtextlint-ja/textlint-ja(日本語に特化したルール)を扱うOrganizationがあります。 人依存よりもメンテナンス性が上る可能性があるので、Organizationにルールを置きたい場合は何かしらの方法でmentionしてください。

  • 上記のリポジトリにIssueを立てるか
  • Gitterでmentionする Gitter
  • Twitterで@azu_reや#textlintなどに書き込む

その他

英語圏でも使われるようになってきたので、英語系のルールも増えてきています。

またtextlintのラッパーで設定なしでdocslintというツールも登場しました。 ESLintのXOやstandardに近いかな?

⏭️ Next

ロジックを扱う@textlint/kernelやtextlintなどがTypeScript化できたことでモジュールとして扱いやすくなる基盤ができてきていると思います。

そのため、次にやるのはtextlintのもう一つの本体であるルールの改善をやっていきます。 最近、Google Developer Documentation Style Guideのtextlintルールであるtextlint-rule-preset-googleを作っていますが、文章を真面目に扱うと”センテンス”や”セクション”といった構造的な文脈を扱うのは避けられません。

次のキャピタライズを扱うルールは、ちゃんとセンテンスを扱えないことからくるバグがあります。

textlintのASTであるTxtASTではParagraphやLinkと行ったNodeはありますが、意味論的なSentenceやSectionといった概念はありません。 これらは言語によって扱いが異なり、言語に依存するものごとはtextlintのコアには含めることができないためです。(HTMLの<section>要素のようなものはマークアップにアレばいいけどそれがない場合は言語やコンテキストで推測するしかない)

この辺はRedPenだとSectionという概念を持っていたりするように、なんとなくのルールは大体あるような気がしています。

この辺のギャップからくるルールの書きにくさを解消するため、コアが持つUtilityライブラリを整備していく予定です。適当に文字列に変換してから”Sentence”などいった塊を作るとASTに比べて情報が欠落してしまって問題があるという経験則があるため、ASTレベルのUtilを拡充していく形です。

主にSection、Sentence、CSTをどうにかしていきたいです。

次のIssueに詳細があるので興味がある人は見てください。 また、合わせてtextlintルールのテストライブラリであるtextlint-testerも改善していきたいと思います。