# 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を無効にしてフォーマッターとして維持する方針にした。

```mermaid
flowchart LR
  subgraph Before["移行前"]
    B1["Biome<br/>lint・フォーマット"]
    E1["ESLint<br/>自作ルール3本"]
    D1["dependency-cruiser<br/>層の制約・循環"]
  end
  subgraph After["移行後"]
    O["oxlint<br/>標準ルール・JSプラグイン<br/>no-restricted-imports<br/>import/no-cycle"]
    B2["Biome<br/>フォーマット・importのソート"]
  end
  E1 --> O
  D1 --> O
  B1 -->|lint| O
  B1 -->|フォーマット| B2
```

## 前提となるoxlintの仕組み

### JSプラグイン

JSプラグインはJavaScriptで実装したルールをoxlintに追加する仕組みである。
oxlint本体のルールはRustで実装されているが、JSプラグインのルールはNode.js上で実行される。
APIは [ESLint v9以降のプラグインと互換](https://oxc.rs/docs/guide/usage/linter/js-plugins.html) で、ESLint用に実装したルールの多くは変更なしで動作する。
公式ドキュメントはこの機能をalpha版と位置づけている。

### createOnce

`createOnce`は、ルールのvisitor関数をプロセスで1回だけ生成する、oxlint独自のAPIである。
ESLintの`create`はファイルごとに実行されるので、ファイル単位の状態は`create`の中の変数で保持できる。
`createOnce`の場合、ファイル単位の状態は [`before`フックで初期化する](https://oxc.rs/docs/guide/usage/linter/writing-js-plugins.html#alternative-api) 。

`@oxlint/plugins`の`eslintCompatPlugin`でプラグインをラップすると、ESLintからも同じプラグインを利用できる。

## ESLintのローカルルールをJSプラグインへ移植する

### typescript-eslintのユーティリティへの依存を削除する

移行前のルールは`@typescript-eslint/utils`の`RuleCreator`で定義し、ASTのノードの種類を`AST_NODE_TYPES`の定数と比較していた。

```ts
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`を指定する。

```ts
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`の値になる。

```ts
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 },
})
```

```json
{
  "jsPlugins": ["./oxlint-plugins/dist/index.js"],
  "rules": { "local/no-duplicate-brand-literals": "error" }
}
```

`create`で定義したルールも、`jsPlugins`に指定すれば動作する。
`createOnce`への変更は、[公式ドキュメント](https://oxc.rs/docs/guide/usage/linter/writing-js-plugins.html#why-is-the-alternative-api-faster) がこのAPIを、oxlintの今後の高速化の対象として案内していることが理由である。

### 複数のファイルにわたる状態はモジュールスコープで保持する

3本のうち1本は異なるファイルの間で、zodの`.brand<"X">()`の型引数の文字列の重複を判定する。
ファイルの間での比較のため、文字列とその位置をモジュールスコープの`Map`に蓄積している。
oxlintでもこの`Map`はファイルの間で共有され、別々のファイルにある同じ文字列の2件目を報告できた。

同一ファイル内の重複を除外する集合は、ファイルごとに初期化する必要がある。
`createOnce`では`before`で初期化する。

```ts
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`は [すべてのファイルで実行されるとは限らない](https://oxc.rs/docs/guide/usage/linter/writing-js-plugins.html#before-hook) 。
visitorの対象のノードがないファイルでは、`before`も含めてルールの実行が省略される場合がある。
このルールは`CallExpression`のvisitorの中でのみ集合を参照するので、省略されても結果は同一である。
ファイルごとに必ず実行する処理は、`Program`のvisitorに記述する。

### 型情報が必要なルールは移植できない

JSプラグインのルールでは [型情報を利用できない](https://oxc.rs/docs/guide/usage/linter/js-plugins.html#api-support) 。
型チェッカーを取得するための`context.sourceCode.parserServices`は、空のオブジェクトになっている。
移行した3本は型注釈の構文のみを判定するルールで、`parserServices`を参照していなかったので、この制約の影響はなかった。
typescript-eslintの`parserServices`で型を参照する自作のルールは、JSプラグインへの移植の対象外である。
oxlintの [型情報を利用するlint](https://oxc.rs/docs/guide/usage/linter/type-aware.html) は、typescript-eslint由来の組み込みのルールを実行する仕組みで、自作のJSプラグインに型情報を提供する機能ではない。

### ルールのテスト

複数のファイルにわたるルールのテストは、oxlintを子プロセスとして実行し、`--format json`の出力の診断を確認する形にした。
oxlintは`oxlint/plugins-dev`で [ESLint互換の`RuleTester`](https://oxc.rs/docs/guide/usage/linter/writing-js-plugins.html#writing-tests-for-custom-rules) も提供している。
`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を禁止するルールである。
[対象](https://oxc.rs/docs/guide/usage/linter/rules/eslint/no-restricted-imports.html) は静的な`import`で、`require()`は対象外である。
dependency-cruiserのルールの依存元は`overrides`の`files`、依存先は`patterns`の`group`に記述する。

```json
{
  "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行目のみになる。

```ts
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`](https://oxc.rs/docs/guide/usage/linter/rules/import/no-cycle.html#ignoretypes) で、片方が`import type`の循環は報告しない。

```ts
// 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`である。

```json
{ "rules": { "import/no-cycle": ["error", { "ignoreTypes": false }] } }
```

### 有効にするルールを明示する

oxlintは設定がない状態でも [`correctness`のカテゴリーのルールを有効にする](https://oxc.rs/docs/guide/usage/linter/config.html#enable-groups-of-rules-with-categories) 。
移行の前後でのチェック内容の変化を防止するため、カテゴリーはすべて無効にし、Biomeで有効だったルールに相当するものと、移行したルールのみを`rules`に指定した。

```json
{
  "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`の実行前にプラグインをビルドするスクリプトを追加した。

```json
{
  "scripts": {
    "build:oxlint-plugins": "tsc -p oxlint-plugins/tsconfig.json",
    "prelint": "pnpm run build:oxlint-plugins",
    "lint": "oxlint"
  }
}
```
