本文へスキップ

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

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

flowchart LR subgraph Before["移行前"] B1["Biome
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"
  }
}

この記事に出てくる用語

用語集の一覧へ

関連事例

  • データ分析支援

    事例:過去実績を提案に活用する分析の仕組み

    広告代理店との取り組みです。同社は過去実績の示唆を次の提案へ反映し、結果をどのように予測したか、その背景まで提案先のクライアントへ説明できるようになりました。KDOT は案ごとの見込みと判断材料を比較できる仕組みを業務アプリとして実装しました。さらに業務アプリの中核となる処理ロジックと機械学習モデルについて、特許手続きを担う弁理士が技術の新規性や工夫を検討するための資料を作成しました。その後この発明には特許が付与されました。

  • プロダクト / Web システム開発 / プロダクトマネジメント(PdM)支援

    事例:工場向け電力見える化製品の開発

    製造業向けにソフトウェア製品を提供する企業との取り組みです。同社は工場の電力を見える化する機能を製品に追加したいと考えていましたが、社内の開発者だけでは手も知見も不足していました。電力計の接続から、データを工場の判断に活用できる形にするところまでを開発支援会社の KDOT に一括で委託し、同社は着手から約 4 か月でこの機能を製品に追加して工場へ販売できるようになりました。納品後の約 9 か月は KDOT が運用を担い、支援が終了した現在は同社が自ら運用を継続しています。

お問い合わせ・ご相談

システム開発、データ活用、プロダクトづくりのことならお気軽にご相談ください。要件が固まる前の整理や、お見積もりだけのご依頼も承ります。