パッケージの多い大きなモノレポで、コードを直してテストする

## 直す前に、パッケージとエントリーポイントの場所を調べる - ワークスペースの構成、配布パッケージ、ネイティブコンポーネント、テストスイート、サンプル、文書、保守スクリプトを特定する。 - 主要パッケージのソースツリー、コンパイル済み成果物、コマンドライン用エントリーポイント、サーバー用エントリーポイント、ビルド用エントリーポイントの場所を確認する。 - 動作を変える前に関連するエントリーポイントをたどり、ファイル名だけから所有範囲を推測しない。 - 階層下のファイルを編集する前に、リポジトリのルートから対象ディレクトリまでに適用されるすべての `README.md` を読む。 - 生成済み成果物と依存関係ディレクトリは、検索専用の証拠として扱う。生成ファイルを直接編集せず、そのソースまたは生成処理を変更する。 ## ビルドの成果物を最新にし、一部だけか全体かのビルドを選ぶ - ブランチを切り替えた後や状態が不確かなワークスペースを初期化した後は、完全なブートストラップビルドを実行し、依存パッケージの成果物を最新にする。 - ソースや統合テストを反復的に扱う場合、すでに実行中でなければ編集前に対象パッケージのウォッチビルドを開始する。 - 文書だけの変更、読み取り専用の調査、CIだけの分析ではウォッチモードを省略できるが、その理由を記録する。 - 変更が1つのパッケージ内に収まる場合は対象パッケージだけをビルドする。複数パッケージにまたがる場合やネイティブコードを変える場合は完全なビルドを使う。 - 型エラーについて同等の証拠が得られる場合は、完全なビルドより専用の型チェックを優先する。 - タスク完了後、自分が開始したウォッチプロセスを停止する。 ## 開発か本番かのモードに合うテストを選ぶ - 開発時または本番時の動作と、対象のバンドラーまたはランタイム実装に正確に一致するテストコマンドを選ぶ。 - 統合テストを実行する前に影響するソースを再ビルドする。古いコンパイル済み成果物では結果が無効になる。 - まず最も範囲の狭い関連テストファイルまたは名前パターンを実行し、失敗内容や変更の影響範囲が必要とする場合だけ範囲を広げる。 - CIと同じコマンド、モード、機能フラグ、環境変数名で再現する。わずかなモード差でも解決結果やスナップショットが変わり得る。 - パッケージ解決、バンドル、起動、ブラウザー動作が検証対象に含まれる場合、都合のよい単体テストで統合テストを代用しない。 - 機能フラグによって動作が暗黙に有効になる場合、従来の専用スイートだけに頼らず、そのフラグを指定した通常スイートをテストする。 ## 決まった時間ではなく、条件がそろうまで待つテストを書く - フィクスチャとハーネス設定がローカル規約に従うよう、非対話型引数を含めてリポジトリのテスト生成ツールを使う。 - 固定時間のスリープより、アサーションを伴う条件ベースの再試行ヘルパーを優先する。固定待機は遅いうえに競合が起きやすいままになる。 - 非推奨のポーリングヘルパーは、サポート対象の再試行・アサーション方式に置き換える。 - テストが実際のプロジェクトに近く保守しやすくなるよう、大きなインラインファイルマップより実体のあるフィクスチャディレクトリを優先する。 - モード固有のテストでは、ハーネスが遅延起動を必要とする場合、サーバーを手動起動する前にモードガードを実行する。 - プリフェッチとナビゲーションの状態をテストの同期境界内で制御し、キャッシュ済み状態を復元して制御不能な処理を引き起こす履歴操作を避ける。 ## テストとビルドの結果を保存し、同じ実行をくり返さない - テストまたはビルドの完全な結果を一度だけ保存し、異なるフィルターで同じスイートを再実行せず、保存結果を検索して要約する。 - 約500行を超えるファイルでは、まず関連シンボルを検索し、その周辺範囲だけを読む。 - 生成ディレクトリの検索は生成された動作の確認に必要な場合だけにし、主要なソースとして閲覧しない。 - 次のビルドを実行する前に関連する編集をまとめ、現在の仮説を証明できる最速のチェックを使う。 - 1回の調査中はリモートの状態応答をキャッシュし、繰り返し取得せず、保存した応答を複数の観点から分析する。 - 失敗時の正確な結果、コマンド、モード、環境を次の診断手順の証拠として保つ。 ## CIの失敗を同じ条件で再現し、レビューより先に直す - リポジトリに状態分析ツールがある場合はそれを使い、現在のブランチと明示された変更リクエストのどちらを調べているか特定する。 - 証拠から別の順序が必要と判断できる場合を除き、ブロッキング失敗にはビルド、フォーマットまたはlint、型、テストの順で対処する。 - 反証されるまで失敗を実在するものとして扱う。既知の不安定動作は調査の背景情報であり、失敗を無視する許可ではない。 - 特に異なるバンドラーやランタイム経路がある場合、同じCIモードと環境フラグで再現する。 - モジュール解決またはビルドグラフの失敗では、実際のパッケージグラフが使われる通常のモード固有統合コマンドを実行する。 - CI失敗とレビューコメントを分け、まず実行を妨げる証拠を解消し、再現した内容を簡潔に記録して残す。 ## 機能フラグを、ビルドとランタイムの両方につなぐ - ユーザーがバンドルするコードで新しい機能フラグを使う場合、その公開型、検証スキーマ、ビルド時の注入箇所へ追加する。 - プリコンパイル済みのランタイムコードがそのフラグを使う場合、関連する各サーバーまたはワーカー経路にもランタイム値を接続する。 - ユーザーコード向けのビルド時注入が、プリコンパイル済みランタイムの内部も制御するとは仮定しない。 - 条件付きモジュール読み込みをコンパイル時の `if` / `else` 分岐内に置き、デッドコード除去によって到達不能な依存関係を取り除けるようにする。 - 制限付きランタイムでは、未対応のプラットフォーム用インポートを保護するフラグを `false` に固定する。 - ランタイム固有のインポートは指定されたエントリーモジュールに置き、必要な動作をそのモジュールの公開ファサードから提供する。 - 稼働中の開発サーバーとデバッグビルドを区別するには専用のランタイムシグナルを使う。一般的な環境ラベルは両方を表す場合がある。 - 標準外の受信リクエストヘッダーを新たに追加する場合、エントリー層で取り除くか認証する場合を除き、必ずセキュリティレビューの対象として示す。 ## シークレットをログに出さず、認証に失敗したら止まる - 文書化されたテストモード用フラグでない限り、環境変数の値は機密情報として扱う。 - 認証用トークン、キー、Cookie、シークレット値を、共有ログ、レビュー文、サンプルに記載・貼り付け・コミットしてはならない。 - 値を直接埋め込まずにCIの変数名とモードを一致させる。必要なシークレットがない場合は停止し、承認された経路で提供を求める。 - セットアップの説明ではプレースホルダーを使い、ローカルのシークレットファイルは決してコミットしない。 - 署名エージェント、キープロバイダー、ハードウェアで保護された資格情報を利用できずソース管理の認証に失敗した場合は停止し、ユーザーにロック解除を依頼する。 - 明示的な承認がなければ、リモートのプロトコルやアドレスを変えたり、失敗した操作を繰り返したり、別の認証回避策を試したりしない。 ## 変更リクエストやコメントを書く前に、権限を確かめる - リモートの変更リクエスト、issue、ディスカッション、コメントを作成または編集する前に、コントリビューション元が内部ブランチか外部フォークかを確認する。 - ユーザーに代わって書き込む前に、リポジトリのコントリビューションポリシーとユーザーの権限を確認する。 - 権限が不十分な場合は、メンテナーを装ったり、リモートへ内容全文を掲載したりしない。技術的事実を提示し、ユーザーが書いた文章をレビューし、ユーザー自身が管理する提出経路を案内する。 - 文書化された例外は、その条件を確認した後に限り、狭い範囲で適用する。 - 新しく作成した変更リクエストは、ユーザーがレビュー準備完了を明示的に決定しない限りドラフト状態に保つ。 - リモートへの書き込みには明示的な範囲指定が必要であり、ローカルでの分析や再現から掲載の許可を推定してはならない。 ## 作業を小さく分け、1つずつ確かめてから進む - 大きなタスクを、成果を個別に確認できる小さな手順へ分割する。 - 各手順のリスクに合う方法、すなわち確認、フォーマット、lint、型、単体テスト、統合テスト、ビルド、または実行時観察で検証してから次へ進む。 - 正しい検証方法が明確でない場合は、その手順の完了を主張する前に確認する。 - コミット前に、変更したファイルへリポジトリのコミットフックと同じフォーマッターおよびリンター設定を適用する。 - 最終diffを確認し、関連のない編集、生成時の雑音、機密情報、テストや文書の不足がないか調べる。 - 変更した動作を裏づける証拠を明示せずに完了を報告しない。 ## 古いネイティブバイナリやスナップショットのずれを見つける - ソースマップの検索には明示的なランタイムフラグが必要な場合があり、ソースパスはコンパイラによって異なり得るため、既知のパス形式をテストする。 - テストと本番のスタックトレースを比較する際は、現在の作業ディレクトリを考慮する。 - ブランチ変更後に動作がソースと矛盾する場合は古いネイティブバイナリを疑い、承認されたブートストラップ経路で依存関係が管理する成果物を更新する。 - 内部コンパイラエラーでは、影響を受けた増分コンパイルキャッシュだけを削除し、エスカレーションする前に1回だけ再試行する。 - ネイティブ言語のコードには公式フォーマッターを使い、厳密に範囲を限定したインラインテストモジュール内を除いてリポジトリルート基準のインポートを優先する。 - スナップショットの結果はフラグやランタイム実装によって変わり得るため、対象CIジョブと正確に同じ環境でのみスナップショットを更新する。 - 文書のコードブロックでは編集後に表示行を数え直し、すべての強調表示が意図した文を指していることを確認する。