matrixshrink

matrixshrink

CI 矩阵每次都会多出一个组合——这里新增一个操作系统，那里新增一个运行时版本——但从来没人会删掉它们，因为没人能说清哪些可以安全移除。matrixshrink 根据证据给出答案。你提供矩阵中的组合和记录的运行历史——每次运行测试了哪个组合、是通过还是失败，以及测试了哪些覆盖键（测试文件、功能 ID，或你跟踪的其他内容）——matrixshrink 就会报告可以移除的组合：

• 冗余 — 如果某个组合的所有运行都通过，且它的覆盖内容已由保留的组合完全覆盖，那么它就是冗余的。扫描采用贪心且确定性的方式：按 ID 升序检查符合条件的组合，某个组合一旦被标记，其覆盖内容便不再计入后续组合。因此，如果两个组合的覆盖内容相同，按字母顺序靠前的组合会被标记，后一个则会保留——必须至少保留其中一个才能覆盖这些内容。始终通过且没有任何覆盖内容的组合也是冗余的：空集可以被任何集合覆盖，包括空集。
• 失败 — 只要有一次运行失败，该组合就永远不会被视为冗余。失败说明该组合能捕获某些问题，因此始终会保留，并列在 failing 中；其覆盖内容也仍会计入对其他组合的覆盖。
• 没有运行记录 — 没有记录运行的组合会列在 no_runs 中，且不会被标记。没有任何证据可作判断，matrixshrink 不会猜测。

报告会列出每个冗余组合及其完整覆盖内容（合并该组合所有运行的覆盖内容并排序）、保留的 ID、失败的 ID、没有运行记录的 ID，以及所提供的组合和运行总数。

验证非常严格：缺失或重复的组合 ID、运行中引用未提供的组合、不是 "pass" 或 "fail" 的结果、非字符串的维度值或覆盖键，以及其他任何格式错误的字段，都会报错并指出出错路径（例如 runs[2].combo references unknown combination "node22-linux"），且不会生成部分报告。计算是纯本地的：不访问网络、不需要配置，也不会读取你提供的输入之外的任何文件。

CLI

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

args.json 包含完整的参数对象：

{
  "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 对每个组合都是可选的（默认为 {}），covered 对每次运行都是可选的（默认为 []）。报告以 JSON 格式打印：

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

退出代码：成功时为 0，运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/matrixshrink mcp

MCP 客户端配置：

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

工具

• find_redundant_combos — 根据运行历史和覆盖重叠，查找冗余的 CI 矩阵组合。

  • combos（数组，必需，至少一个）— 组合列表，每项为 {id, dimensions?} 对象；id 在集合中必须唯一，且每个 dimensions 值都必须是字符串
  • runs（数组，必需，至少一个）— 记录的运行列表，每项为 {combo, outcome, covered?} 对象；combo 指定一个已提供的组合，outcome 为 "pass" 或 "fail"

  返回 {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

开发

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 — 版权所有 (c) 2026 Rene Turcios