io.github.CloudCorpRecords/matrixshrink

matrixshrink

A CI matrix grows one combination at a time — a new operating system here, a new runtime version there — and nobody ever takes one out, because nobody can say which ones are safe to drop. matrixshrink answers that from evidence. You supply the combinations in the matrix and the recorded run history — which combo each run exercised, whether it passed or failed, and the coverage keys it exercised (test files, feature ids, whatever you track) — and matrixshrink reports the combos that can go:

• Redundant — a combo is redundant when every one of its runs passed and its coverage is fully exercised by the combos that stay. The scan is greedy and deterministic: eligible combos are visited in ascending id order, and a combo once flagged stops counting as coverage for the combos scanned after it. So of two combos with identical coverage, the alphabetically-first is flagged and the second stays — one of them has to remain to hold the coverage. An always-passing combo that exercised no coverage at all is redundant: the empty set is covered by anything, including nothing.
• Failing — a combo with even one failed run is never redundant. A failure is evidence the combo catches something, so it is always kept, it is listed in failing, and its coverage still counts toward covering other combos.
• No runs — a combo with no recorded runs is listed in no_runs and is never flagged. There is no evidence either way, and matrixshrink does not guess.

The report carries each redundant combo with its full coverage (the union across its runs, sorted), the ids kept, the ids failing, the ids with no runs, and the totals of combos and runs supplied.

Validation is strict: a missing or duplicate combo id, a run naming a combo that was not supplied, an outcome other than "pass" or "fail", a non-string dimension value or coverage key, and any other malformed field are errors that name the offending path (for example runs[2].combo references unknown combination "node22-linux") and produce no partial report. The computation is pure and local: no network, no configuration, no files read beyond the input you pass in.

CLI

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

args.json contains the full arguments object:

{
  "combos": [
    { "id": "linux-node20", "dimensions": { "os": "linux", "node": "20" } },
    { "id": "linux-node18", "dimensions": { "os": "linux", "node": "18" } },
    { "id": "mac-node20", "dimensions": { "os": "macos", "node": "20" } }
  ],
  "runs": [
    { "combo": "linux-node20", "outcome": "pass", "covered": ["unit", "integration", "e2e"] },
    { "combo": "linux-node18", "outcome": "pass", "covered": ["unit"] },
    { "combo": "mac-node20", "outcome": "fail", "covered": ["unit", "integration"] }
  ]
}

dimensions is optional per combo (default {}) and covered is optional per run (default []). The report is printed as JSON:

{
  "redundant": [{ "id": "linux-node18", "covered": ["unit"] }],
  "kept": ["linux-node20", "mac-node20"],
  "failing": ["mac-node20"],
  "no_runs": [],
  "total_combos": 3,
  "total_runs": 3
}

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

npx -y @reneturcios/matrixshrink mcp

MCP client config:

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

Tools

• find_redundant_combos — Find redundant CI matrix combinations from run history and coverage overlap.

  • combos (array, required, at least one) — combinations as {id, dimensions?} objects; id is unique across the set and each dimensions value is a string
  • runs (array, required, at least one) — recorded runs as {combo, outcome, covered?} objects; combo names a supplied combination and outcome is "pass" or "fail"

  Returns {redundant, kept, failing, no_runs, total_combos, total_runs}.

Docker

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

Development

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