cidiff

cidiff

これらの CI の失敗のうち、実際にあなたが対応すべきものはどれですか？

12 個のチェックに失敗している赤い PR でも、本当の問題は通常 1 つです。残りはベースブランチでもすでに失敗しているか、デプロイプレビューサービスのものか、メンテナーによるワークフロー実行の承認を待っているものです。現在は、それを確認するために、PR 上とベース上で各チェックを 1 回ずつクリックして、目視で比較する必要があります。

cidiff はその比較を自動で行います。PR のヘッドコミットとベースコミットのチェック実行およびコミットステータスを読み取り、すべてのチェックを分類します。

category	meaning
introduced	ベースでは成功し、ヘッドでは失敗しています。この PR で修正すべきものです
pre-existing	ヘッドとベースの両方で、同じチェック名のチェックが失敗しています
external	ホスト型またはデプロイ先のサービス（Vercel、Netlify、Cloudflare など。チェック名で判定）、またはメンテナーの承認を待っているチェック（action_required）です
fixed	ベースでは失敗し、ヘッドでは成功しているか、ヘッドでほかのチェックが実行された際に消えています
passing	ヘッドで成功しています
indeterminate	失敗していますが、どちらかを証明するのに十分なベースの証拠がありません
pending	ヘッドの実行がまだ完了していません

新たに発生した失敗がある場合は終了コード 1、ない場合は 0 を返すため、CI ゲートやメンテナーのトリアージスクリプトにそのまま組み込めます。

誠実さを守るルール

cidiff は Greenlight 内の CI トリアージから切り出されました。そこでは 46 件のオープン PR にまたがる 89 件の失敗チェックを一度に分類し、新たに発生した失敗が 0 件であることを確認しました。この数値を正しく導くには、推測を避ける必要があります。

• ベースの証拠がなければ、判定ではなく indeterminate とします。 ベースの実行がないヘッドの失敗チェックは、どちらの方向についても証明されていないものとして報告されます。
• ベースでの失敗を「修正済み」とするのは、ヘッドで実際にチェックが実行された場合だけです。 実際のフォーク PR（usebruno/bruno #9569）で初日に試したとき、この落とし穴が明らかになりました。PR のチェック スイートは action_required のまま、メンテナーによるワークフロー承認を待っていたため、ヘッドコミットにはチェック実行が 1 件もありませんでした。単純な差分比較では、ベースでの失敗はすべて修正済み、ベースでの成功はすべて成功と報告されます。cidiff はヘッドが空であることを検出し、チェック スイートを読み取って、「このヘッドでは CI が実行されていないため、これらの失敗はまだ分類できません」と警告で明確に伝えます。
• 従来のコミットステータスも証拠として扱います。 Snyk、CodeRabbit、古い CI システムは、チェック実行 API ではなく Statuses API を通じて結果を報告します。cidiff は両方を統合し、名前が重複する場合は実際のチェック実行を優先します。
• 外部要因によるブロックは最初に分類します。 Vercel のプレビュー失敗はテストの失敗ではなく、メンテナーの承認が必要なチェックもコードの失敗ではありません。どちらもベースとの比較より先に external として報告されます。
• 不安定な証拠は原因の断定には使いません。 同じコミット上の同じチェックについて、完了した実行の結果が食い違う（同じコードで一方は成功、もう一方は失敗する）場合、そのチェックは不安定です。不安定な側の単一の結果に依存する比較判定（introduced、pre-existing、fixed）は保留され、実行回数を記録したうえで indeterminate として報告され、レポートでは flaky とフラグ付けされます。最新の結果が成功なら、成功の判定は維持され、フラグが付けられます。テキストレポートでは、不安定なチェックが [FLAKY] 行に表示されます。

使い方

CLI

# Classify a PR's checks against its base
npx @reneturcios/cidiff pr usebruno/bruno 9569

# Machine readable output
npx @reneturcios/cidiff pr owner/repo 123 --json

# Compare two commits directly
npx @reneturcios/cidiff runs owner/repo --head <sha> --base <sha>

出力例（上記のフォーク PR のケースでの実際の出力）：

cidiff usebruno/bruno PR #9569: 0 introduced, 0 pre-existing, 0 external, 0 fixed, 6 indeterminate, 0 pending, 2 passing
  [WARNING] No check runs on head commit 885c6fafed1e (only 2 commit status(es)). The workflow system has produced no evidence to diff against; base check failures below are indeterminate, not fixed.
  [WARNING] 3 check suite(s) on the head commit are action_required: CI is waiting on maintainer approval to run (typical for fork PRs). The failures cannot be classified until CI actually runs.
  [INDETERMINATE] Unit Tests (Linux): Failing on base, and the head commit has no check runs, so there is nothing to compare. CI may not have run on the head yet
  [PASSING] CodeRabbit, security/snyk (Bruno)
Verdict: no introduced failures. Any failing checks are pre-existing, external, or unproven either way (indeterminate).

既知の制限を明記します。ベースとの比較には、PR のベースコミット（PR オブジェクトに保存されたベースブランチの先端）について記録されたチェックの証拠が使われ、チェックは名前の完全一致で照合されます。名前を変更したチェックは、削除と追加の両方として扱われます。どちらの制限も隠されず、出力で確認できます。

認証済みの GitHub API レート制限を利用するには、GITHUB_TOKEN を設定してください。パブリックリポジトリでは、ほかの認証情報は必要ありません。

MCP サーバー

MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "cidiff": {
      "command": "npx",
      "args": ["-y", "@reneturcios/cidiff", "mcp"]
    }
  }
}

ツール：

• diff_pr_ci：リポジトリと PR 番号を指定し、分類済みレポート全体を JSON で返します。
• diff_ci_runs：リポジトリとヘッドおよびベースの SHA を指定し、PR を使わずに同じ分類を行います。

Docker

docker run -i ghcr.io/cloudcorprecords/cidiff mcp
docker run --rm ghcr.io/cloudcorprecords/cidiff pr owner/repo 123

ツールキット

cidiff は、同じ作者が開発する、用途を絞った小規模な開発者ツール群の第1ウェーブ第2パッケージです。すべて同じ方法で構築されており、1つのバイナリで CLI と MCP サーバーを提供し、証拠に基づく決定論的なチェックを行い、答えを捏造しません。姉妹プロジェクトの shipcheck は完成したリリースを検証し、逆に cidiff 自身のリリースも検証します。

• greenlight：オープンソースへの貢献に向けた事前チェック。このイシューは本当に取り込める状態ですか？
• shipcheck：リリースの検証。git tag、リリース、npm、MCP Registry、GHCR が一致していなければ、NO-GO です。
• prwatch：オープン中の PR に関する注意レポート。今すぐ対応が必要なのはどれですか？
• claimcheck：フォーク上の古い主張の状態と、保留中の修正。
• gatefile：見えにくい貢献の条件を抽出し、機械可読な contribution-gates.json にまとめます。
• pkgverdict：npm パッケージのインストール前判定。GO、RISKY、FAKE、または MISSING。

開発

npm install
npm run build
npm test   # 31 tests, classification logic runs on fixtures, no network

ライセンス

MIT