lint-rule-development

Lint ルールの開発

crates/biome_analyze/CONTRIBUTING.md に記載されている現在のアナライザーアーキテクチャに従ってください。ガイド全体を最初から読み込むのではなく、ルールに関係するセクションだけを読んでください。

ワークフロー

1. 同じ言語とグループに属し、クエリやアクションが似ている現在のルールを2つか3つ探します。
2. アナライザーの動作を追加する際は、対応する lint ルールまたはアシストのスキャフォールディングを生成します。
3. シグナルを出すかどうかの判断に必要な、最小限のクエリと状態を実装します。
4. 診断を追加し、安全な場合はアクションも追加します。
5. 有効な入力と無効な入力に絞ったフィクスチャを追加し、スナップショットを確認します。
6. 必要なアナライザーのコード生成と、最小限のテストを実行します。

スキャフォールディング用コマンド：

just new-js-lintrule useMyRule
just new-css-lintrule useMyRule
just new-json-lintrule useMyRule
just new-graphql-lintrule useMyRule

新しい lint ルールは nursery から始めます。nursery のルールには通常の機能バージョニングが適用されないため、main を対象とするパッチ変更として扱います。リリース用エントリーには changeset を読み込みます。

新しいアシストには、言語に対応する new-*-assistrule レシピを使用します。例：

just new-js-assistrule useMyAction
just new-json-assistrule useMyAction

ジェネレーターはアシストを src/assist/source/ の下に配置します。アシストは lint グループや nursery ポリシーを使用しません。新しいアシストはユーザー向けの機能であり、通常は next を対象とするマイナー changeset が必要です。既存のアシストのバグ修正には、通常のバグ修正ポリシーが適用されます。アシストのスキャフォールディングに対応する言語は justfile で確認してください。

クエリと状態

ルールの判定に必要な情報を得られる、最も低コストのクエリを選択してください。

• 構文に局所的なチェックには Ast<Node> を使用します。
• バインディング、参照、スコープ、グローバルが必要な場合は Semantic<Node> を使用します。
• 事実が特定のサービスに属する場合に限り、サービスクエリを使用します。
• 構文とセマンティックモデルでは判定できない場合に限り、型推論を使用します。

ほとんどのルールで必要なのは、これらのうち1つだけです。独自の Visitor を持つカスタム Queryable を使うのは、ツリー全体の走査中に状態を保持するルールの場合です。

利用可能な API については、アナライザーガイドのクエリとサービスのセクションを正としてください。

run() はシグナルを出すかどうかを判定します。候補となる各ノードで実行されないよう、アクションのみの処理は action() に記述してください。

State では、レンジ、構文ノード、トークン、コンパクトな列挙型を優先してください。構文テキストから構築した String、Box<str>、コレクションは、不要なアロケーションを示していることがよくあります。ソーステキストを所有する前に syntax-text-handling を読み込んでください。

run() で部分木を走査したりトークンをスキャンしたりする前、および visited_kinds の実装が必須であるカスタム Visitor を書く前に、syntax-text-handling を読み込んでください。

グローバル識別子に一致するルールでは、その参照がローカルのシャドーイングではなくグローバルに解決されることを確認してください。対象となるノードユニオンとフレームワーク固有の構文ファミリーは、すべて網羅してください。

診断

すべての診断で、次の3つの問いにそれぞれ答えてください。

1. どのような条件が見つかりましたか？
2. なぜ問題なのですか？
3. ユーザーは何をすべきですか？

メッセージは最初の問いに答えます。アドバイスは2つ目の問いに答え、アクションがない場合は3つ目の問いにも答えます。自動修正がある場合は、コードアクションとそのラベルが通常、3つ目の問いに答えます。

メッセージの構成、マークアップ、詳細、アドバイス、カテゴリ、単独の Diagnostic 型については、diagnostics-development を読み込んでください。ルールの実装でそのガイダンスを重複させないでください。

アクション

変更処理は action() で構築します。到達可能な入力のいずれも動作が変わらない場合に限り、FixKind::Safe を設定してください。ルールが証明できない前提に安全性が依存する場合は、Unsafe を使用してください。

アクションの適用時に、次のことをテストしてください。

• 有効な構文が生成されること。
• コメントとトリビアが保持されること。
• 同じルールが再度発火しないこと。
• 安全な修正ではセマンティクスが保持されること。
• run() が受け入れるすべての構文バリアントに対応すること。

API の例として、同じ変更パターンを使用している既存のルールを参照してください。

オプション

オプションを追加するのは、実際に意味のあるモードや、確立された競合する設定を扱う場合に限ります。推測に基づく柔軟性は追加しないでください。

正解となる情報源として、crates/biome_rule_options/src/ にあるルールの生成済みファイルまたは既存のファイルを使用してください。現在の derive、マージ動作、設定例、rustdoc の要件については、アナライザーガイドの ルールオプション、マージ、オプションのドキュメント化の各セクションに従ってください。

次の統合ポイントを確認してください。

• ルールの type Options。
• オプションが存在しない場合、デフォルトで動作が維持されること。
• 拡張設定がオプションの型の契約に従ってマージされること。
• 各動作を網羅する options.json を含むフィクスチャディレクトリ。
• ルールの rustdoc で各オプションのデフォルトを明記し、使用例を示していること。
• just gen-rules と just gen-configuration によって登録情報と設定が更新されること。

ソースとなる ESLint ルールに biome migrate eslint で維持すべきオプションがある場合は、eslint-migrate-options を読み込んでください。

ルールのドキュメント

declare_lint_rule! と declare_assist_rule! 内の rustdoc は、内部 API ドキュメントではなく、エンドユーザー向けのウェブサイトコンテンツです。

• 動作の概要を1行で記述します。
• 報告対象のパターンに問題がある理由を説明します。
• ### Invalid の例を ### Valid の例より先に記載します。
• 現在のルールチェックの構文に従って例にマークを付けます。
• 各オプションについて、デフォルトを明記し、設定方法と適用例を示します。
• 検証を回避するためだけに ignore を使用しないでください。

例を作成する前に、近隣ルールのドキュメントとアナライザーガイドを確認してください。

テストと生成

フィクスチャの命名、期待値コメント、.jsonc のケース、スナップショットのレビュー、不要ファイルの削除については、testing-codegen を読み込んでください。

通常、対象を絞ったコマンドは次のとおりです。

just test-lintrule useMyRule
just gen-rules
just gen-configuration

AGENTS.md の要件に従って、just f と just l を実行してください。

レビューチェックリスト

• クエリの範囲が必要以上に広くないこと。
• グローバルとシャドーイングがセマンティックモデルを通じて処理されること。
• State が不要なソーステキストの所有を避けていること。
• アクションのみの処理は action() まで遅延されていること。
• 安全な修正がセマンティクスを維持していること。
• デフォルトで既存の動作が維持されること。
• 有効、無効、オプション、抑制、修正のケースで、変更した分岐が網羅されていること。
• 必要な生成済み成果物が含まれていること。
• ユーザー向け診断と rustdoc で、実装方法ではなく動作を説明していること。

参考資料

• アナライザーガイド：crates/biome_analyze/CONTRIBUTING.md
• ルールの実装：crates/biome_*_analyze/src/lint/
• ルールオプション：crates/biome_rule_options/src/
• テストフィクスチャ：crates/biome_*_analyze/tests/specs/