リンターを oxlint と同じ形に分ける

  • y8
  • oxlint
  • リンター
  • 設計

リンターには、ファイルを解析してルールを実行するエンジンと、ルールそのものがある。両者の境目をどこに引くかは好みの問題に見える。だが、自作の Markdown リンター y8 では、その境目は計測と OS ごとのビルドの手間という2つで決まった。できあがった形は oxlint と同じである。エンジンとネイティブでなければならないものは組み込みプラグインとして1つのバイナリに入れ、ルールは y8-presets という TypeScript のパッケージ1つにまとめる。

エンジンの中のルール

最初、README.md、AGENTS.md、SKILL.md 向けのルールは y8 のパッケージそのものに入っていた。そのため y8 は、リンターであると同時に、それらのファイルがどうあるべきかという1人の意見でもあった。パーサーだけが欲しい人も、両方を入れたうえで意見のほうを切る必要があった。

分け方の手本は、自作の別のリンターにあった。oxlint-plugin-decision は仕組みだけを提供する oxlint のプラグインで、oxlint-plugin-decision-presets は出来合いの設定を持つ別のパッケージである。y8 も同じ関係にした。エンジンのパッケージはパース、ルールの実行、設定、CLI、プラグイン API を持ち、ルールは別のパッケージへ移す。

パースは1回

分け方を考える途中で、ルールのパッケージごとにネイティブのアドオンを持たせる案が出た。markdownlint 互換のルール、agnix、日本語の処理をそれぞれ別のアドオンにすると、同じファイルをアドオンの数だけパースし直すことになる。別々にパースすると同じテキストが違う形に読まれることがあり、そうなるとルールが指す位置とエンジンのノードが食い違う。

結局、エンジンが1回だけパースし、ルールはその木を受け取る形にした。ただし木を境界の向こうへ渡すのはただではない。最初の実装は木を JSON にしており、TypeScript 側がエンジンの約12倍の時間を使っていた。木をコピーせずに1本のバッファで渡すようにして、724ファイルで1,057 ms が544 ms になった。この変更は別の記事にまとめた。

oxlint の2種類のプラグイン

oxlint にはプラグインが2種類ある。unicorn や react のようなプラグインは Rust で書かれて oxlint のバイナリに組み込まれ、名前を書くだけで有効になる。JS プラグインは ESLint 互換の API で書き、JavaScript で動く1。JS 側には代償がある。vuejs/core のリポジトリで oxlint は48 ms で終わるが、単純な JS プラグインを1つ足すと236 ms になった2。

速さだけを見れば、ルールはすべて Rust で書くべきだろう。だが決め手は、誰がバイナリをビルドするかだった。Rust のルールは、リンターが動く OS と CPU の組み合わせごとにコンパイルし、組み合わせごとに別のパッケージとして公開しなければならない。TypeScript のルールは Node.js が動く所ならどこでも動く。1人で書き、頻繁に直すルールでは OS ごとのビルドの手間のほうが重いので、y8 のルールは TypeScript を基本にした。

agnix を動かす前の計測

エンジンにはネイティブのコードがまだ2つ残っていた。エージェントの設定ファイルを検査する agnix と、日本語の形態素解析器である。どちらも WebAssembly にすれば OS ごとのビルドは要らなくなる。決める前に、両方を1スレッドで計測した。

処理ネイティブWebAssembly
agnix約265 ms約715 ms
日本語の形態素解析400〜525 ms370〜650 ms
Markdown の組み込みルール105〜150 ms230〜350 ms
モジュールの読み込み無し約160 ms

agnix は WebAssembly にすると3倍近く遅くなり、モジュールの読み込みだけで毎回約160 ms が加わる。一方、エンジンはもともと OS ごとにビルドしているので、agnix をネイティブのまま残してもビルドの手間は増えない。agnix は oxlint の Rust プラグインと同じ形でバイナリに残した。エンジンには組み込みプラグインのための共通の仕組みを1つ用意し、agnix はそこに登録される。agnix の指摘は agnix/<rule> という名前の普通の診断として返る。

プリセットは1パッケージ

ルールをエンジンから出した後に残ったのは、ルールをどう配るかである。観点ごとにパッケージを分ければ、使う人は要るものだけを入れられる。その代わり、パッケージごとに名前とバージョンと公開の手間が要る。これらのルールは1人の作者が出す公式のプリセットなので、@r_masseater/y8-presets という1つのパッケージにまとめた。

パッケージの中では観点ごとに別のプリセットにした。README.md、AGENTS.md、SKILL.md、文書に共通の検査、Markdown のスタイル、エージェントの設定の6つである。y8 の設定には oxlint と同じく extends を足したので、プロジェクトは使うプリセットを並べ、自分の設定を最後に書く。

export default defineConfig({
  y8: { extends: [readme(), agentsMd({ sections: [["Commands"], ["Rules"]] })] },
});

この形の境目は、どれも好みではなく数字かビルドの手間から引いた。ネイティブのコードはもともとバイナリをビルドする所に置き、ルールはバイナリの要らない TypeScript に置く。どちらにするか迷うものは、計測するまで決めない。

出典

  1. JS Plugins ↩

  2. Oxlint JS Plugins Preview ↩