run-parity

プルリクエストのパリティを実行する

プルリクエストのベースとヘッドを、同じリポジトリのコミットに対して実行します。決定論的な改行区切り JSON（NDJSON）成果物を書き出し、比較します。

実行を準備する

VERCEL_TEAM_ID（または VERCEL_ORG_ID）と VERCEL_PROJECT_ID を指定した VERCEL_OIDC_TOKEN または VERCEL_TOKEN、認証済みの gh、およびプッシュ済みのプルリクエストのヘッドが必要です。許可なく変更をプッシュしないでください。このリポジトリでは ni と nr を使用してください。

プルリクエストを解決します。

gh pr view <pr-number-or-url> \
  --json number,url,baseRefOid,headRefOid,headRepository,headRepositoryOwner

プルリクエスト URL からベースリポジトリを特定します。headRepositoryOwner.login と headRepository.name からヘッドリポジトリを特定します。ブランチ名ではなく、返されたコミットハッシュを使用してください。

tmp/parity-pr-<number>-<head-short-sha> を作成し、実行後も保持してください。評価の前に ni を実行します。

両方のリビジョンを実行する

packages/evals から実行します。デフォルトのコーパスには、ランキング上位 2,000 件のリポジトリが含まれ、初期並列数は 200 です。Vercel Sandbox への過剰な負荷を避けるため、サンドボックスの作成数は 20 に制限されています。評価器はリソースをクリーンアップし、失敗したプロジェクトを並列数 50、続いて 10 で再試行します。

nr --silent eval \
  --react-doctor-repository <base-repository-url> \
  --react-doctor-ref <baseRefOid> \
  > <absolute-run-directory>/baseline.ndjson

nr --silent eval \
  --repositories <absolute-run-directory>/baseline.ndjson \
  --react-doctor-repository <head-repository-url> \
  --react-doctor-ref <headRefOid> \
  > <absolute-run-directory>/candidate.ndjson

成功したベースラインは、完全に一致する React Doctor のコミット、コーパスマニフェストのハッシュ、評価器のスキーマ、ルールセット／設定のハッシュに対してのみキャッシュしてください。キャッシュ済みのベースラインも、再利用前にストリーミングバリデーターを通過する必要があります。複数のプルリクエストで、この不変のベースラインを共有できますが、候補ヘッドや差分を組み合わせてはいけません。

評価器は各レコードに、正確な検出器のコミット、リビジョンごとのルール／設定ハッシュ、評価器のソースハッシュを記録します。スタンプのない古い実行結果はキャッシュしないでください。通常の入力バリデーターを通過した後、隣接するプロベナンスファイルを作成します。

node .agents/skills/run-parity/scripts/baseline-cache-provenance.mjs create \
  --baseline <baseline.ndjson> \
  --corpus-manifest <corpus-manifest.json> \
  --base-commit <full-base-commit> \
  --repository <react-doctor-repository-url> \
  --evaluator-source-hash <packages-evals-source-hash> \
  --config-contract revision-local-rule-config-v1 \
  --rule-set-hash <stamped-full-ruleset-hash>

期待される評価器ハッシュは、packages/evals から nr --silent source-hash を実行して取得します。再利用する前に毎回、同じコマンドを verify とともに実行してください。検証では、未加工の NDJSON バイトストリームを読み込み、フルベースラインの ruleKeys: [] を必須とし、各レコードの生成元を確認し、ピン留めされた正確なコーパスのプロジェクトセットがマニフェストと一致することを独立して検証します。不一致があればキャッシュミスとして扱います。

キャッシュヒット時は、ベースを Vercel Sandbox で実行しないでください。検証済みのキャッシュ済みベースラインに対して、上記の通常の候補のみのコマンドを実行し、--paired-* オプションは渡さないでください。

キャッシュミスの場合、または必須のフル対スコープのシャドウ実行の場合は、同じ Vercel サンドボックスで両方の検出器を評価します。

nr --silent eval \
  --repositories <corpus-manifest-or-validated-input> \
  --paired-baseline-output <absolute-new-baseline-path> \
  --paired-base-react-doctor-repository <base-repository-url> \
  --paired-base-react-doctor-ref <base-or-full-shadow-commit> \
  --paired-base-rule <treatment-plugin/rule> \
  --react-doctor-repository <treatment-repository-url> \
  --react-doctor-ref <treatment-commit> \
  --paired-execution sequential \
  --rule <treatment-plugin/rule> \
  > <absolute-run-directory>/candidate.ndjson

ベースラインの出力パスは排他的に作成され、既存の成果物を上書きすることはありません。ペア実行のサンドボックスでは、各対象リポジトリを一度だけ取得して単一のオブジェクトストアに格納し、その後、分離されたベース／処理対象の対象ワークツリーを、分離された検出器のインストール、設定ファイル、レポートパスとともにスキャンします。両方の処理が成功した場合にのみプロジェクトのペアが出力されるため、再試行によっていずれかの出力に不完全な成功ペアが残ることはありません。ペアの書き込みには単一ライターキューを使用し、どちらかのシンクで失敗した場合はベースラインをロールバックします。ペア評価の実行がゼロ以外の終了コードを返した場合、両方の出力成果物は無効となり、再利用できません。コンパレーターやキャッシュには渡さず、破棄してください。

パフォーマンス比較では、同じ --paired-base-rule と --rule の値を使用するか、フルルール比較を行う場合は両方を省略してください。フル対スコープのシャドウ実行は、有効な診断エビデンスではありますが、パフォーマンスエビデンスではありません。 ペアのサンドボックスは、CPU コア 4 個、メモリ 8 GiB、ディスク 20 GiB を要求します。--paired-execution auto がデフォルトであり、サンドボックスに少なくとも 4 つの CPU コアがある場合にのみスキャンを並列で実行します。制御された逐次ベンチマークと以下のパフォーマンス比較には --paired-execution sequential を使用してください。auto または parallel は、タイミングの証拠が破棄される診断専用のパリティにのみ使用してください。ペア評価はデフォルトで 50 サンドボックスであり、これは 4 コアサンドボックスで観測された容量上限を下回ります。Vercel Sandbox の割り当てが異なる範囲をサポートする場合にのみ --concurrency を渡してください。 両モードは、同じ厳格な試行期限と正確な評価ラベルのクリーンアップを共有します。各ペアスキャンには 5 分間のコマンド上限があるため、少数のスタックしたサンドボックスが試行予算全体を消費することはありません。通常の評価器は既存のタイムアウトを維持します。

同一の不変ベースとコーパスを持つ複数のプルリクエストには、繰り返し可能なマトリックス処理記述子を使用してください。まず正確なコーパス ID と評価器ハッシュを取得します:

cd packages/evals
nr --silent matrix-corpus-identity <absolute-corpus-manifest-path>
nr --silent source-hash

各記述子は、この正確な形式の不変 JSON ファイルです:

{
  "schemaVersion": 1,
  "id": "pr-1234",
  "artifactDirectory": "/absolute/path/pr-1234",
  "reactDoctorRepository": "https://github.com/millionco/react-doctor.git",
  "reactDoctorCommit": "<40-character-head-commit>",
  "impactManifestPath": "/absolute/path/pr-1234-impact.json",
  "impactManifestSha256": "<sha256>",
  "group": {
    "baseReactDoctorRepository": "https://github.com/millionco/react-doctor.git",
    "baseReactDoctorCommit": "<40-character-base-commit>",
    "baseFullRuleSetHash": "<full-base-rule-set-sha256>",
    "baseArtifactPath": "/absolute/path/base-union-scoped.ndjson",
    "baselineOutputPath": "/absolute/cache/full-baseline.ndjson",
    "baselineProvenancePath": "/absolute/cache/full-baseline.provenance.json",
    "corpusManifestPath": "/absolute/path/corpus.json",
    "corpusManifestSha256": "<matrix-corpus-identity manifestSha256>",
    "corpusProjectSetSha256": "<matrix-corpus-identity projectSetSha256>",
    "evaluatorSourceHash": "<source-hash>",
    "configContract": "revision-local-rule-config-v1",
    "scanContract": "react-doctor-json-full-v1",
    "reportContract": "react-doctor-complete-report-v1",
    "projectRootPolicy": "manifest-root-dir-v1"
  }
}

参照される impact manifest は find-impacted-rules.mjs の正確な出力でなければならず、そのハッシュ、ベースコミット、ヘッドコミット、モード、および候補ルールキーが再検証されます。Vercel Sandbox が開始する前に、マトリックスランナーは固定されたベースコミットとヘッドコミットを取得し、現在のジェネレーターを再実行し、バイト単位で同一の manifest 出力を要求します。繰り返される各記述子は、完全に同じ group オブジェクト、一意の安全な id、および別個のアーティファクトディレクトリを持たなければなりません。

nr --silent eval \
  --matrix-treatment /absolute/path/pr-1234.json \
  --matrix-treatment /absolute/path/pr-1235.json \
  --matrix-wave-width 2

検証済みの完全なキャッシュヒットは、ベースを Vercel Sandbox の外に保ちます。そうでない場合、マトリックスは、いずれかの処理が完全なパリティを要求するときは 1 つの完全なベースを、またはインクリメンタルなルールスコープの 1 つのソート済みユニオンをスキャンします。1 つのターゲットベアクローンが、分離されたレーンワークツリーに供給されます。デフォルトの 2 レーンウェーブは、サンドボックスあたり 4 つの CPU コアと 8 GiB を使用します。ランナーは 400 CPU の範囲内で並行性を導出し、サンドボックス作成を 20 に保ちます。再試行は成功した (lane, project) の結果を保持し、失敗した作業のみを 50、10、次に 2 の並行性で再試行します。各処理は、その候補 NDJSON、正確なコーパス manifest、記述子、impact manifest、ルール、ハッシュ、カウント、および来歴とともにアトミックに公開されます。ベースが欠落している場合、成功した処理を独立したマージ判断を行うのではなくブロック済みとしてマークします。

公開された各処理ディレクトリは、自己完結した証拠として扱ってください。比較の前に、そのステータス、正規の相対パス、プロデューサーのバインディング、バイト長、ハッシュ、正確なレコード数、完全なレポート、およびコーパスプロジェクトタプルを検証してください。来歴から共有キャッシュまたはスコープ付きベースのソースパスを決してたどらないでください:

node .agents/skills/run-parity/scripts/verify-matrix-artifact.mjs \
  <treatment-artifact-directory>

# Incremental treatment
node .agents/skills/run-parity/scripts/compare-parity.mjs \
  --rules <treatment-artifact-directory>/rules.json \
  <treatment-artifact-directory>/base.ndjson \
  <treatment-artifact-directory>/candidate.ndjson \
  > <treatment-artifact-directory>/parity.json

# Full treatment
node .agents/skills/run-parity/scripts/compare-parity.mjs \
  <treatment-artifact-directory>/base.ndjson \
  <treatment-artifact-directory>/candidate.ndjson \
  > <treatment-artifact-directory>/parity.json

ルールのみのプルリクエストでは、候補実行の前に保守的な impact manifest を構築します:

node .agents/skills/run-parity/scripts/find-impacted-rules.mjs \
  <repository-root> <base-ref> <head-ref> <impact.json>

manifest が "mode": "incremental" を報告する場合にのみインクリメンタルモードを使用してください。その candidateRuleKeys には、既知の診断相互作用クロージャがすでに含まれています。それらのキーを変更せずに rules JSON に書き込み、それぞれを繰り返し可能な候補引数として渡します:

nr --silent eval \
  --repositories <validated-baseline-or-corpus-manifest> \
  --react-doctor-repository <head-repository-url> \
  --react-doctor-ref <headRefOid> \
  --rule <plugin/rule> \
  > <absolute-run-directory>/candidate-scoped.ndjson

評価器は、選択されなかったすべてのリビジョンローカルルールに off をスタンプします。スコープにセキュリティスキャンルールが含まれていない場合は、そのツリー全体のパスもスキップします。セキュリティスキャンルールの変更、グローバルな runner/config/report/registry の変更、削除または名前変更されたルール ID、未解決のランタイムエッジ、解析失敗、およびその他の不確実な依存関係サーフェスは、完全なパリティにフォールバックします。マップされたルール境界を最初に越えることなくホストモジュールに到達するプラグインユーティリティも、完全なパリティにフォールバックします。ランタイムルールの影響がない manifest は完全モードを使用します。空のインクリメンタルルールスコープを決して構築しないでください。

すべての実行は、厳格な外側のタイムアウトを維持します。短い評価器予算は、試行が開始されたときに残り時間の 25% で集約再試行リザーブを上限とし、スナップショットビルドが最初の試行期限全体を消費するのではなく、少なくとも 75% をアクティブな作業のために残します。 ベースラインには、解決済みのリポジトリハッシュが記録されます。ベースラインを候補コーパスとして再利用することで、実行間にデフォルトブランチが移動するのを防げます。

候補の実行前に、すべてのベースラインレコードをストリーム検証してください。これにより、ピン留めされていないリポジトリ、評価エラー、不正なレポート、不完全なプロジェクトを、NDJSON コーパスをメモリに読み込まずに除外できます：

jq -e -n \
  -f <repository-root>/.agents/skills/run-parity/scripts/validate-parity-input.jq \
  <absolute-run-directory>/baseline.ndjson >/dev/null

ベースラインコマンドがゼロ以外の終了コードを返すか、チェックに失敗した場合は、失敗したレコードを調査して中止してください。候補の実行では、ピン留めされていない評価 NDJSON は拒否されます。

両方のコマンドが終了コード 0 を返し、完了率 100% を報告することを必須としてください。そうでない場合は、失敗したプロジェクトを報告して比較を中止してください。

結果を比較する

リポジトリのルートから実行します：

node .agents/skills/run-parity/scripts/compare-parity.mjs \
  <run-directory>/baseline.ndjson \
  <run-directory>/candidate.ndjson \
  > <run-directory>/parity.json

node .agents/skills/run-parity/scripts/compare-parity-performance.mjs \
  <run-directory>/baseline.ndjson \
  <run-directory>/candidate.ndjson \
  > <run-directory>/performance-parity.json

終了コードを解釈します：

• 0：診断結果が一致
• 1：比較は成功しましたが、診断に変更あり
• 2：入力が不完全または無効

評価器は、不完全なレポートを成功として記録せず、再試行します。比較器は両方の入力を再度検証し、いずれかの側に評価エラー、不正なレポート、完了マーカーの欠落、または部分的なレガシーレポートが含まれている場合、無効な入力を示すステータスで終了します。レガシーと v3 のレポートスキーマにまたがって診断をレポート相対の識別子に正規化するため、重複するワークスペーススキャンでカウントが水増しされたり、スキーマのアップグレードが診断の変化として現れたりすることはありません。

比較器は両方の NDJSON 入力をストリーム処理し、ベースラインレコードをシステムの一時ディレクトリにステージングして、大きな詳細配列を逐次書き込みます。変更された診断エントリは、決定的にソートする間だけ保持されます。そのため、一時ディスクと出力の容量は実行サイズに比例するよう確保してください。

パフォーマンス比較器では、完全な v3 レポート、同一のプロジェクト対象範囲、ルール範囲、設定コントラクト、評価器ソースが必要です。ベースと候補で同じ Vercel Sandbox サンドボックスを共有し、CPU を奪い合わないよう、対になった逐次評価でのみ実行してください。終了コード 0 は実行時間がノイズを許容する固定しきい値内だったことを示し、1 はプロジェクトまたは全体で重大な回帰があったことを示し、2 は証拠が無効であることを示します。ベースのスキャンが 1 秒未満のプロジェクトは無視し、個別のプロジェクトについては 50% 以上かつ 2 秒遅くなった場合にのみフラグを立てます。また、コーパス全体の回帰については、対象となるプロジェクトが 10 件以上、比率が 20%、追加の合計遅延が 10 秒以上の場合にのみフラグを立てます。原因を特定する前に、出力された測定値を確認してください。マトリックスレーンは並行して実行され、診断用の証拠として扱います。マトリックスのアーティファクトをパフォーマンス比較器に入力しないでください。

終了コードが 1 の場合は、変更を分類する前に、影響を受けたソースの場所を確認してください。

スコープを限定して比較する場合は、完全なベースラインを同じルールと常時適用の不変条件の範囲に絞り込みます：

node .agents/skills/run-parity/scripts/compare-parity.mjs \
  --rules <rules.json> \
  <baseline.ndjson> \
  <candidate-scoped.ndjson> \
  > <run-directory>/parity-scoped.json

スコープ外の任意の候補診断はスコープ付き比較器で拒否され、プロジェクト、フレームワーク、解析対象ファイルの対象範囲が完全に一致していることが必要です。また、重複数を維持し、正規化されたプライマリパスと関連パスを含むすべての意味的な診断フィールドを比較します。

同じベースラインまたは候補を複数回比較する場合は、コンパクトな Merkle インデックスを作成してください：

node .agents/skills/run-parity/scripts/build-parity-index.mjs \
  --rules <rules.json> <baseline.ndjson> \
  > <baseline.index.json>

node .agents/skills/run-parity/scripts/build-parity-index.mjs \
  --candidate --rules <rules.json> <candidate-scoped.ndjson> \
  > <candidate.index.json>

node .agents/skills/run-parity/scripts/compare-parity-indexes.mjs \
  <baseline.index.json> <candidate.index.json> \
  > <index-diff.json>

実行全体のルートが一致すれば、直ちに終了します。一致しない場合は、ルールのハッシュを確認し、その後プロジェクトのバケットを確認します。空のプロジェクト／ルールバケットは明示的に扱われ、スコープまたは対象範囲のメタデータに差異があれば、安全側に倒して失敗します。

インクリメンタル版の同等性を必須ゲートにするのに十分なシャドー履歴が蓄積されるまでは、同一のヘッド／コーパス／並行実行ポリシーで候補全体を 1 回実行し、そのルールでフィルターした出力がスコープ付き候補と完全に一致することを必須としてください。実測した経過時間とプロジェクトの遅延を報告し、サンプルから速度向上を推定しないでください。

比較器の変更は、リポジトリのルートから検証してください：

node --test .agents/skills/run-parity/scripts/compare-parity.test.mjs
node --test .agents/skills/run-parity/scripts/compare-parity-performance.test.mjs
node --test .agents/skills/run-parity/scripts/find-impacted-rules.test.mjs
node --test .agents/skills/run-parity/scripts/parity-index.test.mjs
node --test .agents/skills/run-parity/scripts/validate-parity-input.test.mjs

結果を報告する

プルリクエストの URL、コミットハッシュ、比較およびスキップしたプロジェクト数、診断の合計数、追加数と削除数、ルールごとの最大差分、アーティファクトのパスを報告してください。