ESLintのローカルルールとdependency-cruiserからoxlintへの移行記録

サマリ
- 自作のルールのためだけにESLintを維持し、層の依存関係をdependency-cruiserでチェックしていたので、Biomeを含めて、lintを担うツールが3種類あった
- ESLintの自作ルール、Biomeのlintルール、dependency-cruiserのチェックをoxlintに集約した
- Biomeはフォーマッターとimportのソートの用途に限定した
- CIのステップと設定ファイルも、それぞれ1つに集約した
- ESLintのローカルルール3本は、oxlintのJSプラグインへ大きな変更なしに移植できた
- typescript-eslintのユーティリティへの依存を削除し、ASTのノードの種類は文字列で判定する
- 複数のファイルにわたる状態を保持するルールでは、ファイル単位の状態をbeforeフックで初期化する
- JSプラグインでは型情報が必要なルールを実行できない
- dependency-cruiserの層の制約はno-restricted-imports、循環依存の検出はimport/no-cycleで代替した
- no-restricted-importsはimportの文字列をパターンと比較するので、pathエイリアスのパターンは相対パスのimportに一致しない
- import/no-cycleはデフォルトで、型のみのimportによる循環を報告しない
背景
TypeScriptのバックエンドで、次の3種類のツールがそれぞれ別のステップで実行されていた。
| ツール | 担当していたチェック |
|---|---|
| Biome | 一般的なlintルール、フォーマット、importのソート |
| ESLint | 自作のルール3本(型注釈の規約) |
| dependency-cruiser | 層の間の依存の方向、循環依存、未解決のimport、参照元のないファイル |
ESLintは自作のルールの実行専用だった。
それでもパーサーの依存関係と、ルールをビルドする手順を保守する必要があった。
lintの設定は3か所に分散し、CIのステップも3つあった。
この3種類をoxlintの1つの設定ファイルに統合し、Biomeはlinterを無効にしてフォーマッターとして維持する方針にした。
lint・フォーマット"] E1["ESLint
自作ルール3本"] D1["dependency-cruiser
層の制約・循環"] end subgraph After["移行後"] O["oxlint
標準ルール・JSプラグイン
no-restricted-imports
import/no-cycle"] B2["Biome
フォーマット・importのソート"] end E1 --> O D1 --> O B1 -->|lint| O B1 -->|フォーマット| B2
前提となるoxlintの仕組み
JSプラグイン
JSプラグインはJavaScriptで実装したルールをoxlintに追加する仕組みである。
oxlint本体のルールはRustで実装されているが、JSプラグインのルールはNode.js上で実行される。
APIは ESLint v9以降のプラグインと互換 で、ESLint用に実装したルールの多くは変更なしで動作する。
公式ドキュメントはこの機能をalpha版と位置づけている。
createOnce
createOnceは、ルールのvisitor関数をプロセスで1回だけ生成する、oxlint独自のAPIである。
ESLintのcreateはファイルごとに実行されるので、ファイル単位の状態はcreateの中の変数で保持できる。
createOnceの場合、ファイル単位の状態は beforeフックで初期化する 。
@oxlint/pluginsのeslintCompatPluginでプラグインをラップすると、ESLintからも同じプラグインを利用できる。
ESLintのローカルルールをJSプラグインへ移植する
typescript-eslintのユーティリティへの依存を削除する
移行前のルールは@typescript-eslint/utilsのRuleCreatorで定義し、ASTのノードの種類をAST_NODE_TYPESの定数と比較していた。
import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/types"
import { ESLintUtils } from "@typescript-eslint/utils"
const rule = ESLintUtils.RuleCreator.withoutDocs({
meta: { /* 省略 */ },
create: (context) => ({
CallExpression(node: TSESTree.CallExpression) {
if (
node.callee.type === AST_NODE_TYPES.MemberExpression &&
node.callee.property.type === AST_NODE_TYPES.Identifier &&
node.callee.property.name === "brand"
) {
// ...
}
},
}),
defaultOptions: [],
})
oxlintのJSプラグインでも、TypeScriptのASTのノードは同一のtypeの名前で提供されるので、判定は文字列の比較に変更した。
ルールの型には@oxlint/pluginsのRuleを指定する。
import type { Rule } from "@oxlint/plugins"
const rule: Rule = {
meta: { /* 省略 */ },
createOnce(context) {
return {
CallExpression(node) {
const callee = node.callee
if (callee.type !== "MemberExpression") return
if (callee.property.type !== "Identifier" || callee.property.name !== "brand") return
// ...
},
}
},
}
プラグイン本体はeslintCompatPluginでラップし、ビルド後のファイルのパスを.oxlintrc.jsonのjsPluginsに指定する。
ルール名のプレフィックスはプラグインのmeta.nameの値になる。
import { eslintCompatPlugin } from "@oxlint/plugins"
import noDuplicateBrandLiterals from "./rules/no-duplicate-brand-literals.js"
export default eslintCompatPlugin({
meta: { name: "local" },
rules: { "no-duplicate-brand-literals": noDuplicateBrandLiterals },
})
{
"jsPlugins": ["./oxlint-plugins/dist/index.js"],
"rules": { "local/no-duplicate-brand-literals": "error" }
}
createで定義したルールも、jsPluginsに指定すれば動作する。
createOnceへの変更は、公式ドキュメント がこのAPIを、oxlintの今後の高速化の対象として案内していることが理由である。
複数のファイルにわたる状態はモジュールスコープで保持する
3本のうち1本は異なるファイルの間で、zodの.brand<"X">()の型引数の文字列の重複を判定する。
ファイルの間での比較のため、文字列とその位置をモジュールスコープのMapに蓄積している。
oxlintでもこのMapはファイルの間で共有され、別々のファイルにある同じ文字列の2件目を報告できた。
同一ファイル内の重複を除外する集合は、ファイルごとに初期化する必要がある。
createOnceではbeforeで初期化する。
const registry = new Map<string, string[]>() // ファイルの間で共有する
const rule: Rule = {
meta: { /* 省略 */ },
createOnce(context) {
const seenInThisFile = new Set<string>()
return {
before() {
seenInThisFile.clear() // ファイルごとに初期化する
},
CallExpression(node) {
// brand の文字列を取得し、seenInThisFile と registry に登録する
// registry に別のファイルの記録があれば context.report する
},
}
},
}
beforeは すべてのファイルで実行されるとは限らない 。
visitorの対象のノードがないファイルでは、beforeも含めてルールの実行が省略される場合がある。
このルールはCallExpressionのvisitorの中でのみ集合を参照するので、省略されても結果は同一である。
ファイルごとに必ず実行する処理は、Programのvisitorに記述する。
型情報が必要なルールは移植できない
JSプラグインのルールでは 型情報を利用できない 。
型チェッカーを取得するためのcontext.sourceCode.parserServicesは、空のオブジェクトになっている。
移行した3本は型注釈の構文のみを判定するルールで、parserServicesを参照していなかったので、この制約の影響はなかった。
typescript-eslintのparserServicesで型を参照する自作のルールは、JSプラグインへの移植の対象外である。
oxlintの 型情報を利用するlint は、typescript-eslint由来の組み込みのルールを実行する仕組みで、自作のJSプラグインに型情報を提供する機能ではない。
ルールのテスト
複数のファイルにわたるルールのテストは、oxlintを子プロセスとして実行し、--format jsonの出力の診断を確認する形にした。
oxlintはoxlint/plugins-devで ESLint互換のRuleTester も提供している。
RuleTesterの入力は1件ずつのコードなので、複数のファイルにわたるルールのテストには不向きである。
dependency-cruiserのルールを標準ルールで代替する
| dependency-cruiserのルール | 移行先 |
|---|---|
| 層の間の依存の方向(domainからinfraへの依存の禁止など) | no-restricted-importsをディレクトリごとのoverridesに記述 |
| 本番のコードからテストのコードへの依存の禁止 | 同上 |
| 循環依存 | import/no-cycle |
| 解決できないimport | 移行しない。型チェックの対象のファイルでは、tscが値や型のimportの未解決をエラーにする(副作用のみのimport "./x.js"はnoUncheckedSideEffectImportsが必要) |
| 参照元のないファイル | 移行しない。既存のknipの未使用ファイルの検出の対象とする |
層の制約はディレクトリごとのoverridesに記述する
no-restricted-importsは、指定したimportを禁止するルールである。
対象 は静的なimportで、require()は対象外である。
dependency-cruiserのルールの依存元はoverridesのfiles、依存先はpatternsのgroupに記述する。
{
"overrides": [
{
"files": ["src/domain/**/*.ts"],
"rules": {
"eslint/no-restricted-imports": [
"error",
{
"patterns": [
{ "group": ["@src/infra/**"], "message": "domain layer must not import from infra layer" }
]
}
]
}
}
]
}
dependency-cruiserはimportをファイルのパスに解決してから比較する。
no-restricted-importsは、importの文字列そのものをgroupのパターンと比較する。
そのため上の設定のようにgroupがpathエイリアスの"@src/infra/**"のみの場合、src/domainのファイルの次のimportのうち、報告の対象は1行目のみになる。
import { x } from "@src/infra/x.js" // 報告される
import { y } from "../infra/y.js" // 報告されない
相対パスのimportも禁止する場合は、groupのパターンに"**/infra/**"などを追加する。
循環依存はimport/no-cycleで検出する
import/no-cycleは、importの連鎖が元のファイルに到達する循環を報告するルールである。
ignoreTypesのデフォルト値はtrue で、片方がimport typeの循環は報告しない。
// src/domain/a.ts
import type { B } from "../application/b.js"
export type A = { b?: B }
// src/application/b.ts
import type { A } from "../domain/a.js"
export type B = { a?: A }
この2ファイルの循環はdependency-cruiserではtsPreCompilationDeps: trueの設定で報告され、import/no-cycleではデフォルトの設定で報告されない。
型のみの循環は実行時のimportの順序の問題の原因にならないので、移行ではデフォルトの設定を維持した。
型の循環も禁止する場合の設定はignoreTypes: falseである。
{ "rules": { "import/no-cycle": ["error", { "ignoreTypes": false }] } }
有効にするルールを明示する
oxlintは設定がない状態でも correctnessのカテゴリーのルールを有効にする 。
移行の前後でのチェック内容の変化を防止するため、カテゴリーはすべて無効にし、Biomeで有効だったルールに相当するものと、移行したルールのみをrulesに指定した。
{
"plugins": ["eslint", "typescript", "unicorn", "import", "oxc"],
"categories": {
"correctness": "off",
"suspicious": "off",
"perf": "off",
"style": "off",
"pedantic": "off",
"nursery": "off",
"restriction": "off"
},
"rules": {
"eslint/eqeqeq": ["error", "smart"],
"typescript/no-explicit-any": "error"
}
}
移行後の運用
JSプラグインはalpha版で、APIはバージョンごとに変更される可能性がある。
そのためoxlintと@oxlint/pluginsは同一のバージョンに固定した。
自作のルールはTypeScriptで実装し、ビルド後のファイルをoxlintが参照する構成なので、lintの実行前にプラグインをビルドするスクリプトを追加した。
{
"scripts": {
"build:oxlint-plugins": "tsc -p oxlint-plugins/tsconfig.json",
"prelint": "pnpm run build:oxlint-plugins",
"lint": "oxlint"
}
}


