cachemiss

cachemiss

CI を高速化するはずのキャッシュが、なぜこの実行ではミスしたのでしょうか？ cachemiss は、ワークフローに記載されたキャッシュキーのテンプレートと、各実行で実際に起きたことを受け取り、避けられなかったミスと、原因を説明できないミスを判定します。

• ハッシュ対象の入力 — テンプレート内の hashFiles('...') / hashFiles("...") セグメントから抽出した glob パターン。出現順に並べ、重複は除きます
• 結果の件数 — 完全一致したヒット、復元キーにフォールバックした部分一致、完全なミスのそれぞれの実行回数と、ヒット率（全実行に対するヒットの割合を小数第4位まで丸めた値）
• ヒットしなかった実行ごとの原因 — 部分一致の実行は exact_key_miss_restore_hit、変更ファイルがハッシュ対象の入力に該当するミスは hashed_input_changed（該当ファイルを一覧表示）、それ以外は unexplained_miss です
• 原因別の集計 — 原因ごとの件数を頻度の高い順に並べます（同数の場合はアルファベット順）。この集計をもとに、レポートの most_common_cause と全体の diagnosis が決まります。すべてヒットした履歴の診断結果は cache_healthy となり、最も多い原因は null です
• 変更されたハッシュ対象ファイル — ミスした実行で変更された、ハッシュ対象の入力の重複を除いた一覧です。どのロックファイルやマニフェストが繰り返しキャッシュを無効化しているのかをすぐに確認できます

glob の照合には、次の3つのルールが適用されます。ファイル名がパターンと完全に一致する場合、そのファイルはパターンに一致します。パターンが **/ で始まる場合、ファイル名がパターンの残りの部分と一致するか、/ と残りの部分で終わるときに一致します。パターンに * が含まれる場合は、/ で分割したセグメントごとに照合し、* はちょうど1つのセグメントに一致します。また、セグメント数も一致する必要があります。大文字と小文字は区別されます。

すべての処理は、指定された入力をもとにローカルで行われます。ネットワーク通信、ログのスクレイピング、設定は不要です。無効な入力（空のキーのテンプレート、結果のない実行、hit / partial / miss 以外の結果、文字列以外の変更ファイル）は、該当するパスを示すエラーとして拒否され、部分的なレポートは生成されません。

CLI

npx @reneturcios/cachemiss analyze --input args.json
npx @reneturcios/cachemiss --version

args.json には、引数オブジェクト全体を指定します。

{
  "key_template": "${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}",
  "runs": [
    { "run_id": "run-201", "outcome": "hit" },
    {
      "run_id": "run-202",
      "outcome": "miss",
      "changed_files": ["apps/web/package-lock.json", "src/index.ts"]
    },
    { "run_id": "run-203", "outcome": "partial" }
  ],
  "restore_keys": ["linux-node-"]
}

changed_files は実行ごとに省略でき、restore_keys は全体で省略できます（省略しない場合はレポートにもそのまま記載されます）。レポートは JSON として出力されます。

終了コード：成功時は 0、実行時エラー（読み取り不可または無効な入力ファイル、無効な入力を含む）時は 1、使用方法のエラー時は 2 です。

MCP サーバー

npx -y @reneturcios/cachemiss mcp

MCP クライアントの設定：

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

ツール

• analyze_cache_miss — キーのテンプレートと実行ごとの結果をもとに、CI キャッシュのミスを診断します。

  • key_template（文字列、必須、空でない）— ワークフローに記載されたキャッシュキー
  • runs（配列、必須、1件以上）— {run_id, outcome, changed_files?} オブジェクト形式の実行データ。outcome は hit、partial、miss のいずれかです
  • restore_keys（文字列の配列、任意）— ワークフローで設定された復元キーのプレフィックス

  {run_count, hits, partials, misses, hit_rate, hashed_inputs, restore_keys, cause_counts, misses_detail, changed_hashed_files, most_common_cause, diagnosis} を返します。

Docker

docker run -i ghcr.io/cloudcorprecords/cachemiss
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/cachemiss analyze --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios