linting-alignment

リンティングの整合

整合では、リポジトリのポリシーを最優先します。実際のプロジェクト上の制約を引き続き守るローカルルールを維持しつつ、現在の上流の動作に可能な限り近づけます。設定は、見慣れたパッケージ名の一覧ではなく、実行可能な所有関係のグラフとして扱います。

依頼から許可されたモードを判断します。

• レビュー — 調査して報告し、作業ツリーは変更しません。
• 整合 — 調査し、対象を絞って変更し、検証します。ツールチェーンの更新、修正、移行、設定をユーザーが求めている場合は、これをデフォルトとします。
• 公開 — 整合したうえで、ユーザーがその範囲を明示的に依頼した場合に限り、コミット、プッシュ、またはレビューを開始します。

1. リポジトリの権限を確認する

リポジトリのルート、現在のブランチ、作業ツリーの状態、および適用対象となるルートとスコープ別のエージェント指示を確認します。対象範囲に適用される、コードスタイル、コントリビューション、依存関係、生成ファイル、検証に関するリポジトリのガイダンスを読みます。

ツールを実行する前に、既存のユーザー変更を特定します。慣例に頼らず、リポジトリ内の根拠から、パッケージマネージャー、ワークスペース構成、サポート対象ランタイム、ベースブランチ、公開依頼の範囲を導き出します。

完了条件： 適用されるポリシー、検証のエントリーポイント、ブランチの境界、変更前から存在するすべての未コミットファイルを特定していること。

2. 所有関係のグラフを構築する

実行可能な関係をたどり、リンティングの対象範囲を洗い出します。

• パッケージマニフェスト、ロックファイル、ワークスペース宣言、ルートまたはパッケージのスクリプト。
• ルートおよびネストされたリンター、フォーマッター、アナライザー、無視設定、エディター、フック、CI の設定。
• インポート、extends、スプレッド、プラグイン宣言、CLI 呼び出し、生成ファイル、パッケージの peer または optional dependencies。
• ファーストパーティーソース内のインライン無効化設定とフォーマッターの無視設定。

見つかった各ノードについて、その役割と所有者を記録します。オーケストレーターまたはプリセット、リンター、フォーマッター、ネイティブプラグイン、ランタイム読み込みプラグイン、単体アナライザー、型認識型の補助ツール、スコープ別設定、または実行コンシューマーのいずれかを特定します。インストール済みパッケージまたは公開ソース内のインポートをたどり、有効なプリセット、プラグインの構成、設定の所有者が判明するまで確認します。パッケージの対象範囲はこのグラフから導きます。見慣れたツール名だけでは、そのパッケージやルールが有効である証拠にはなりません。

実行レーンを次の4つに分けます。

1. コアレーン — フォーマッターとリンターのコマンド。
2. プラグインレーン — リンターが実行するネイティブまたはランタイム読み込みルール。
3. アナライザーレーン — プラグインの対象範囲を超えるプロジェクトスキャンを行う、単体の静的解析 CLI。
4. 型認識レーン — セマンティックルール、コンパイラ診断、およびそれらのプロジェクトグラフ依存関係。

グラフに Ultracite、Oxlint、Oxfmt、またはそれらの統合が含まれる場合、設定が冗長だと分類する前に、references/ultracite-oxc-ownership.md を最後まで読みます。React Doctor またはその統合が含まれる場合、アナライザーとプラグインのレーンを比較する前に、references/react-doctor-ownership.md を最後まで読みます。

完了条件： 設定されたすべてのコマンドについて、設定とインポートをたどってインストール済みの所有者まで確認できていること。すべてのネストされたスコープと実行レーンを把握し、重複または競合するツールと、意図的に併用するレーンを区別できていること。

3. 比較可能なベースラインを確立する

調整のための編集に入る前に、対象範囲に含まれる有効な各レーンを実行できる、リポジトリで承認された最小限の読み取り専用コマンドを実行します。正確なコマンド、バージョン、終了コード、診断の件数またはカテゴリ、代表的な有効設定を記録します。どの設定とルールが有効かを証明できる場合は、ツールの設定出力、ルール一覧、デバッグ、ファイル一覧などのコマンドを優先します。

比較条件を統一します。変更の前後で、同じ作業ツリー、環境、対象、フラグを使用してください。ツールチェーンの変更がすでに作業ツリーに存在する場合は、固定された Git の時点から、分離された一時的な作業ツリー、または同等に比較可能な別の成果物を使って変更前のベースラインを構築します。既存の CI を利用できるのは、リビジョン、コマンド、環境が一致する場合に限ります。ベースラインを取得できない場合は、その旨をギャップとして明記します。比較なしに、診断をリグレッションと呼んではいけません。

ベースラインコマンドが失敗した場合は、その失敗を依頼された変更から切り分けます。ベースラインは証拠であり、無関係なソースを修正する許可ではありません。

完了条件： 有効なすべてのレーンについて、再現可能な変更前の状態、または正確な比較ギャップが記録されており、同じ調査コマンドを変更後にも実行できる状態になっていること。

4. 所有レイヤーを確認する

現行バージョンの設定をレビューする場合は、インストール済みのプリセットとパッケージのソースを調べます。アップグレードや移行の場合は、変更された依存関係グラフのノードごとに、主要なリリースノート、移行ガイド、パッケージマニフェスト、公式ドキュメントも調べます。リポジトリで指定されたドキュメントサービスがある場合は、それを使用します。

ローカルでの影響を変え得る事実を確認します。プリセットの構成、ルールのデフォルト、同梱プラグインと外部プラグインの区別、ピア要件、設定のマージと検出のセマンティクス、無視の動作、修正の動作、型情報を利用するための要件、サポート対象のファイル形式、安定性の保証です。

アップストリームの変更を、それぞれ採用、変更なし、保留、分割、後続対応に分類し、証拠を示します。semver に準拠したリリースでも、診断やフォーマット出力が追加されることがあります。そのため、リリースの分類をベースラインの代わりにしてはいけません。

完了条件： 現在有効な動作が実証され、対象範囲内のアップストリーム変更すべてについて、証拠に基づく対応方針が決まっていること。

5. ローカルの調整内容を判断する

ローカルのプリセットレイヤー、ルールの上書き、プラグイン、ネストされた設定、除外パターン、抑制、重複したコマンド、デフォルト以外のフォーマッターオプションをすべて、維持、削除、範囲を狭める、ソースを修正、移行、保留のいずれかに分類します。

変更が直接正当化されるのは、現在の証拠による場合に限ります。具体的には、上流での対応が確認できている、診断が現在も発生している、解決経路が壊れている、実行が競合している、依存関係が古くなっている、スコープが無効である、またはリポジトリのポリシーが明示的に変更された場合です。ドメイン上の安全性、フレームワークの動作、生成コードの境界、互換性、パフォーマンス、または意図的な移行時の基準を引き続き定めている差異は維持します。

ルールが正しく、修正のほうが例外より小さい場合は、ソースの修正を優先します。コードが意図的に異なる場合は、有効な例外のうち最も狭いものを優先します。プラグインのレーンでは対応できない作業を CLI がカバーする場合は、独立したアナライザーを維持します。型情報を利用するチェックは、その実行時要件とプロジェクトグラフ要件を保った場合に限り維持します。

それぞれのソース修正について、選択済みか候補かを問わず、変更するファイル数、その修正をフォーマッター、自動修正、コードモッド、手編集のどれで行うか、また他のルールで新たに検出される問題を記録します。バグ検出ではなく一貫性の確保を目的とするスタイルのみのデフォルトは、修正対象のファイル数がそのツールのベースラインでのチェック対象ファイル数の10分の1を超える場合、依頼でそのデフォルトが指定されていなければ保留とします。上流のデフォルト全般を求める依頼は、特定のデフォルトを指定したことにはなりません。

除外パターンは、フックやエディターが明示的に渡すファイルリストを含め、すべての実行で別の仕組みがそのパスを除外する場合、またはそこにあるファイルが、後からツールが書き込むファイルも含め、チェックに合格する場合に削除します。変更ファイルがゼロ件のプローブで確認できるのは現在のツリーだけです。その後、Changesets、リリースツール、コードジェネレーターがファイルを書き込むことがあります。

**完了条件：**スコープ内で変更または維持するデフォルト以外の選択肢すべてについて、根拠、担当者、レーン、記録済みの処置が揃っていること。また、スコープ内で上流のデフォルトと異なるルールまたはフォーマッターオプションすべてについて、対象ファイル数と、その修正によって他のルールで新たに検出される問題が記録されていること。

6. プローブしてから適用する

所有関係のつながりまたはルールグループを一度に1つだけプローブし、その都度、対象を絞ったベースラインコマンドを再実行します。インストールを共有したりシンボリックリンクしたりするプローブはユーザーのインストールを書き換える可能性があるため、移行やジェネレーターの実験は、独自の依存関係をインストールした一時的なワークツリーまたは破棄可能なコピーで実行します。却下したプローブはユーザーのワークツリーに残しません。

Review モードでは、すべてのプローブを読み取り専用にし、ワークツリーに変更を加えずに、適用せず比較と報告まで進めます。

現在のソースまたはレビュー済みのドライランによってカスタム設定が保持されると確認できるまでは、セットアップコマンドと初期化コマンドをジェネレーターとして扱います。再生成によってリポジトリ所有のポリシーが置き換えられる場合は、薄いエントリー設定を直接編集するか、ジェネレーターのレビュー済み差分を選択的に適用します。

設定を簡素化する前に、マージと検出の動作を確認します。プリセットが除外設定を引き継がない場合は、除外設定の明示的な伝播を維持します。最も近いネスト設定がルート設定を置き換えてしまう場合は、親設定の明示的な拡張を維持するか追加します。ネスト設定の検出を無効にするフラグと、宣言元の設定を基準に解決されるパスも考慮します。

Align モードまたは Publish モードでは、ステップ5で決定した処置のみを適用します。ポリシーが変更された場合に限りポリシー文書を更新し、リリースノートの記録はレビューまたは変更記録に残します。

**完了条件：**ワークツリーに選択した変更だけが含まれ、変更したグラフの各つながりが解決され、却下した実験と付随的なフォーマッターによる変更が残っていないこと。

7. 比較して検証する

同じ対象範囲と環境で、ベースラインのプローブを完全に同じ条件で再実行します。実効設定、終了ステータス、診断、フォーマット出力、関連するランタイムコストをレーンごとに比較します。それぞれの差異について、要求された変更または確認済みの上流変更のどちらに起因するかを説明します。

Review モードでは、リポジトリで承認された読み取り専用チェックのみを使用し、変更を伴う可能性のあるゲートはスキップしたものとして記録します。Align モードまたは Publish モードでは、リポジトリで必須のフォーマッター、リンター、型チェック、テスト、総合検証の各ゲートを実行します。Git が利用できる場合は、その後に git diff --check を実行します。最終差分をレビューし、次の点を確認します。

• 各依存関係が、実際に存在するグラフのエッジで必要とされている。
• 各設定と除外設定が、意図したスコープに適用されている。
• プラグイン、アナライザー、型情報を利用するレーンを、互いの代替として扱っていない。
• 既存のベースラインの失敗が、アラインメントとは切り分けられている。

アラインメントが原因で生じたリグレッションは、修正、保留、または分割します。関係のないクリーンアップに変更範囲を広げず、具体的なブロッカーを記録します。

**完了条件：**変更前と変更後を比較でき、すべての差異が説明され、必須ゲートに合格するか具体的なブロッカーが示され、最終差分が承認された範囲に一致していること。

8. 指定された境界で報告する

まず結果を示します。所有関係のグラフ、直接的に正当化される変更、ベースラインとの比較、検証結果、保留または延期した作業、ソースや比較に関する不足を要約します。上流のデフォルト設定から維持した差異はすべて、その理由とともに列挙します。ルールまたはフォーマッターのオプションについては、該当するファイル数と、その修正によって他のルールで明らかになる問題も記載します。延期した各デフォルト設定について、判断はユーザーに委ねることを明記します。

Review モードでは、ワークツリーに変更がないことを確認します。Align モードでは、公開前に停止します。Publish モードでは、リポジトリのガイダンスに従い、明示的に要求された境界まで、検証済みのアラインメント対象ファイルのみを公開し、レビューの説明に差異の一覧を記載します。保留中のホスト側チェックは、失敗とは分けて報告します。

**完了条件：**ユーザーが、ツールチェーンの所有元、ローカルの各差異を変更または維持した理由、判断待ちのデフォルト設定、ベースラインと比較した変更後の状態、正確な公開状況を把握できること。