# cachemiss

The cache was supposed to make CI fast, so why did that run
miss? cachemiss takes the cache key template exactly as it
appears in your workflow, together with what actually
happened on each run, and works out which misses were
inevitable and which ones nobody can explain:

- **Hashed inputs** — the glob patterns pulled out of the
  template's `hashFiles('...')` / `hashFiles("...")`
  segments, in order of appearance, duplicates removed
- **Outcome counts** — how many runs hit exactly, fell back
  to a restore key, or missed outright, plus the hit rate
  (hits over total runs, rounded to four decimal places)
- **A cause per non-hit run** — a partial run is
  `exact_key_miss_restore_hit`; a miss whose changed files
  touch a hashed input is `hashed_input_changed`, with the
  matching files listed; anything else is
  `unexplained_miss`
- **Cause tallies** — counts per cause, most frequent first
  (ties broken alphabetically), feeding the report's
  `most_common_cause` and overall `diagnosis`; an all-hit
  history diagnoses as `cache_healthy` with a null most
  common cause
- **Changed hashed files** — the sorted union of every
  hashed input that changed on a miss run, so you can see
  at a glance which lockfile or manifest keeps busting the
  cache

Glob matching follows three rules: a file matches a pattern
when it equals the pattern exactly; when a pattern starts
with `**/`, a file matches when it is the remainder of the
pattern or ends with `/` plus that remainder; and a pattern
containing `*` matches segment by segment (splitting on
`/`), where `*` covers exactly one segment and segment
counts must be equal. Matching is case-sensitive.

Everything is computed locally from the inputs you supply:
no network, no log scraping, no configuration. Invalid
input — an empty key template, a run without an outcome, an
outcome outside `hit` / `partial` / `miss`, a non-string
changed file — is rejected with an error naming the
offending path, and no partial report is produced.

## CLI

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

`args.json` contains the full arguments object:

```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` is optional per run, and `restore_keys` is
optional overall (it is echoed into the report). The report
is printed as JSON.

Exit codes: `0` on success, `1` on a runtime error
(including an unreadable or invalid input file, or invalid
input), `2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/cachemiss mcp
```

MCP client config:

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

### Tools

- `analyze_cache_miss` — Diagnose CI cache misses from a
  key template and per-run outcomes.
  - `key_template` (string, required, non-empty) — the
    cache key as written in the workflow
  - `runs` (array, required, at least one) — runs as
    `{run_id, outcome, changed_files?}` objects, where
    `outcome` is one of `hit`, `partial`, `miss`
  - `restore_keys` (array of strings, optional) — the
    restore-key prefixes configured in the workflow

  Returns `{run_count, hits, partials, misses, hit_rate,
  hashed_inputs, restore_keys, cause_counts, misses_detail,
  changed_hashed_files, most_common_cause, diagnosis}`.

## Docker

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

## Development

```bash
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
```

## License

MIT — Copyright (c) 2026 Rene Turcios