@fairfox/polly 0.80.0 → 0.81.0

package/dist/tools/mutate/src/cli.js

@@ -0,0 +1,743 @@
+#!/usr/bin/env bun
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// tools/mutate/src/args.ts
+var KNOWN_VERBS = new Set(["run", "report", "decisions", "verify", "init", "help"]);
+var VALUE_FLAGS = new Set(["--config", "--report", "--decisions", "--db"]);
+function parseMutateArgs(argv) {
+  const positionals = [];
+  const flags = new Map;
+  const bools = new Set;
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === undefined)
+      break;
+    if (VALUE_FLAGS.has(a)) {
+      flags.set(a, argv[i + 1] ?? "");
+      i += 2;
+    } else {
+      if (a.startsWith("-"))
+        bools.add(a);
+      else
+        positionals.push(a);
+      i += 1;
+    }
+  }
+  const verbRaw = positionals[0];
+  const help = bools.has("--help") || bools.has("-h") || verbRaw === "help";
+  const verb = verbRaw === undefined ? "run" : KNOWN_VERBS.has(verbRaw) ? verbRaw : verbRaw;
+  return {
+    verb,
+    rest: positionals.slice(1),
+    config: flags.get("--config"),
+    report: flags.get("--report"),
+    decisions: flags.get("--decisions"),
+    db: flags.get("--db"),
+    noReport: bools.has("--no-report"),
+    run: bools.has("--run"),
+    force: bools.has("--force"),
+    help
+  };
+}
+
+// tools/mutate/src/config.ts
+import { resolve as resolve2 } from "node:path";
+
+// tools/test/src/coverage-policy/mutate-targets.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Glob } from "bun";
+async function findStrykerConfigs(root) {
+  const found = [];
+  const single = join(root, "stryker.conf.json");
+  if (existsSync(single))
+    found.push(single);
+  const glob = new Glob("stryker/*.{json,conf.json}");
+  for await (const rel of glob.scan({ cwd: root, onlyFiles: true })) {
+    found.push(join(root, rel));
+  }
+  return found.sort();
+}
+function isGlob(pattern) {
+  return pattern.includes("*") || pattern.includes("?") || pattern.includes("[");
+}
+async function resolvesToFile(pattern, cwd) {
+  if (pattern.startsWith("!"))
+    return true;
+  if (!isGlob(pattern))
+    return existsSync(resolve(cwd, pattern));
+  const glob = new Glob(pattern);
+  for await (const _ of glob.scan({ cwd, onlyFiles: true }))
+    return true;
+  return false;
+}
+async function checkField(configPath, field, patterns, cwd) {
+  const issues = [];
+  for (const pattern of patterns ?? []) {
+    if (!await resolvesToFile(pattern, cwd)) {
+      issues.push({ config: configPath, field, pattern });
+    }
+  }
+  return issues;
+}
+async function validateMutateTargets(root) {
+  const configs = await findStrykerConfigs(root);
+  const issues = [];
+  for (const configPath of configs) {
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    const testFiles = config.testFiles ?? config.bun?.testFiles;
+    issues.push(...await checkField(configPath, "mutate", config.mutate, root));
+    issues.push(...await checkField(configPath, "testFiles", testFiles, root));
+  }
+  return { configs, issues };
+}
+
+// tools/mutate/src/config.ts
+var DEFAULT_REPORT = "reports/mutation/mutation.json";
+var DEFAULT_DECISIONS = ".polly/test-debt/decisions.jsonl";
+async function resolveMutateConfig(cwd, args) {
+  let strykerConfigPath = null;
+  if (args.config) {
+    strykerConfigPath = resolve2(cwd, args.config);
+  } else {
+    const found = await findStrykerConfigs(cwd);
+    strykerConfigPath = found[0] ?? null;
+  }
+  return {
+    cwd,
+    strykerConfigPath,
+    reportPath: resolve2(cwd, args.report ?? DEFAULT_REPORT),
+    dbPath: args.db ? resolve2(cwd, args.db) : ":memory:",
+    decisionsPath: resolve2(cwd, args.decisions ?? DEFAULT_DECISIONS)
+  };
+}
+
+// tools/mutate/src/decisions.ts
+import { createHash } from "node:crypto";
+
+// tools/mutate/src/ingest.ts
+import { Database } from "bun:sqlite";
+function buildDb(report, dbPath = ":memory:") {
+  const db = new Database(dbPath);
+  db.exec("PRAGMA journal_mode = WAL;");
+  db.exec(`
+		DROP TABLE IF EXISTS kills;
+		DROP TABLE IF EXISTS covers;
+		DROP TABLE IF EXISTS mutants;
+		DROP TABLE IF EXISTS tests;
+		CREATE TABLE tests (
+			id TEXT PRIMARY KEY,
+			file TEXT NOT NULL,
+			name TEXT NOT NULL,
+			line INTEGER
+		);
+		CREATE TABLE mutants (
+			id TEXT PRIMARY KEY,
+			mutator TEXT NOT NULL,
+			file TEXT NOT NULL,
+			line INTEGER,
+			status TEXT NOT NULL
+		);
+		-- the kill matrix: (mutant, test) where test detects mutant
+		CREATE TABLE kills (
+			mutant_id TEXT NOT NULL REFERENCES mutants(id),
+			test_id TEXT NOT NULL REFERENCES tests(id),
+			PRIMARY KEY (mutant_id, test_id)
+		);
+		-- coverage matrix (populated only when the runner reports coveredBy)
+		CREATE TABLE covers (
+			mutant_id TEXT NOT NULL REFERENCES mutants(id),
+			test_id TEXT NOT NULL REFERENCES tests(id),
+			PRIMARY KEY (mutant_id, test_id)
+		);
+		CREATE INDEX idx_kills_test ON kills(test_id);
+		CREATE INDEX idx_kills_mutant ON kills(mutant_id);
+	`);
+  const insTest = db.prepare("INSERT OR IGNORE INTO tests (id, file, name, line) VALUES (?, ?, ?, ?)");
+  const insMut = db.prepare("INSERT INTO mutants (id, mutator, file, line, status) VALUES (?, ?, ?, ?, ?)");
+  const insKill = db.prepare("INSERT OR IGNORE INTO kills (mutant_id, test_id) VALUES (?, ?)");
+  const insCover = db.prepare("INSERT OR IGNORE INTO covers (mutant_id, test_id) VALUES (?, ?)");
+  const ingest = db.transaction(() => {
+    for (const [file, tf] of Object.entries(report.testFiles ?? {})) {
+      for (const t of tf.tests) {
+        insTest.run(t.id, file || "(unknown)", t.name, t.location?.start.line ?? null);
+      }
+    }
+    for (const [file, f] of Object.entries(report.files)) {
+      for (const m of f.mutants) {
+        insMut.run(m.id, m.mutatorName, file, m.location.start.line, m.status);
+        for (const tid of m.killedBy ?? [])
+          insKill.run(m.id, tid);
+        for (const tid of m.coveredBy ?? [])
+          insCover.run(m.id, tid);
+      }
+    }
+  });
+  ingest();
+  return db;
+}
+function queryAll(db, sql) {
+  return db.query(sql).all();
+}
+function queryGet(db, sql) {
+  return db.query(sql).get();
+}
+async function loadMutationReport(path) {
+  return await Bun.file(path).json();
+}
+if (false) {}
+
+// tools/mutate/src/decisions.ts
+var DEFAULT_LOG = ".polly/test-debt/decisions.jsonl";
+var VERDICTS = ["keep", "prune", "rewrite", "investigate"];
+function normalizeSource(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/[^\n]*/g, "$1").replace(/\s+/g, " ").trim();
+}
+async function fileHash(file) {
+  const f = Bun.file(file);
+  if (!await f.exists())
+    return null;
+  return createHash("sha256").update(normalizeSource(await f.text())).digest("hex").slice(0, 16);
+}
+function fileSignals(db) {
+  const rows = queryAll(db, `
+			WITH file_kill AS (SELECT DISTINCT t.file file, k.mutant_id mid FROM kills k JOIN tests t ON t.id=k.test_id),
+			     owner AS (SELECT mid, count(DISTINCT file) nf FROM file_kill GROUP BY mid)
+			SELECT fk.file file, count(DISTINCT fk.mid) kills,
+			       sum(CASE WHEN o.nf=1 THEN 1 ELSE 0 END) unique_kills
+			FROM file_kill fk JOIN owner o ON o.mid=fk.mid GROUP BY fk.file`);
+  const m = new Map;
+  for (const r of rows)
+    m.set(r.file, {
+      kills: r.kills,
+      uniqueKills: r.unique_kills,
+      subsumed: r.kills > 0 && r.unique_kills === 0
+    });
+  return m;
+}
+async function loadDecisions(logPath) {
+  const m = new Map;
+  const f = Bun.file(logPath);
+  if (!await f.exists())
+    return m;
+  for (const line of (await f.text()).split(`
+`)) {
+    const t = line.trim();
+    if (!t)
+      continue;
+    const d = JSON.parse(t);
+    m.set(d.file, d);
+  }
+  return m;
+}
+function staleReason(d, currentHash, current) {
+  if (!current)
+    return "file no longer kills any mutant (renamed/deleted/refactored?)";
+  if (d.hash !== currentHash)
+    return "test file changed since the decision";
+  if (d.signal.subsumed !== current.subsumed)
+    return `subsumption flipped (${d.signal.subsumed} → ${current.subsumed})`;
+  if (d.signal.uniqueKills > 0 !== current.uniqueKills > 0)
+    return `unique-kill status changed (${d.signal.uniqueKills} → ${current.uniqueKills})`;
+  return null;
+}
+async function status(db, logPath = DEFAULT_LOG) {
+  const signals = fileSignals(db);
+  const decisions = await loadDecisions(logPath);
+  const needsReview = [];
+  const stale = [];
+  const settled = [];
+  for (const [file, sig] of [...signals].sort((a, b) => b[1].kills - a[1].kills)) {
+    const d = decisions.get(file);
+    if (!d) {
+      if (sig.subsumed)
+        needsReview.push(`  ${file}  (${sig.kills} kills, 0 unique)`);
+      continue;
+    }
+    const reason = staleReason(d, await fileHash(file), sig);
+    if (reason)
+      stale.push(`  ${file}  [${d.verdict}] — ${reason}`);
+    else
+      settled.push(`  ${file}  [${d.verdict}] ${d.rationale ? `— ${d.rationale}` : ""}`);
+  }
+  for (const [file, d] of decisions) {
+    if (!signals.has(file))
+      stale.push(`  ${file}  [${d.verdict}] — file no longer in matrix`);
+  }
+  const out = [];
+  out.push(`NEEDS REVIEW  (subsumed files with no decision — ${needsReview.length})`);
+  out.push(needsReview.length ? needsReview.join(`
+`) : "  none");
+  out.push(`
+STALE  (decision's basis drifted — re-review — ${stale.length})`);
+  out.push(stale.length ? stale.join(`
+`) : "  none");
+  out.push(`
+SETTLED  (fresh decisions, suppressed from action list — ${settled.length})`);
+  out.push(settled.length ? settled.join(`
+`) : "  none");
+  return out.join(`
+`);
+}
+async function decide(file, verdict, rationale, db, logPath = DEFAULT_LOG) {
+  if (!VERDICTS.includes(verdict)) {
+    console.log(`✗ verdict must be one of: ${VERDICTS.join(", ")}`);
+    process.exit(1);
+  }
+  const sig = fileSignals(db).get(file);
+  if (!sig) {
+    console.log(`✗ ${file} is not a test file that kills any mutant in the current matrix`);
+    process.exit(1);
+  }
+  const decided = new Date().toISOString().slice(0, 10);
+  const record = {
+    file,
+    verdict,
+    rationale,
+    signal: sig,
+    hash: await fileHash(file),
+    decided
+  };
+  await Bun.write(logPath, (await Bun.file(logPath).exists() ? await Bun.file(logPath).text() : "") + JSON.stringify(record) + `
+`);
+  console.log(`✓ recorded: ${file} [${verdict}]${rationale ? ` — ${rationale}` : ""}`);
+}
+if (false) {}
+
+// tools/mutate/src/init.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { join as join2, relative } from "node:path";
+function resolvePluginRef(projectDir) {
+  const resolved = Bun.resolveSync("@fairfox/polly/stryker", projectDir);
+  const hoisted = resolved.includes("/node_modules/") && !resolved.includes("/.bun/");
+  return hoisted ? "@fairfox/polly/stryker" : relative(projectDir, resolved);
+}
+function detectMutate(projectDir) {
+  if (existsSync2(join2(projectDir, "src"))) {
+    return ["src/**/*.ts", "!src/**/*.test.ts", "!src/**/*.d.ts"];
+  }
+  return ["**/*.ts", "!**/*.test.ts", "!**/*.d.ts", "!node_modules/**", "!dist/**"];
+}
+function detectTestGlob(projectDir) {
+  for (const d of ["tests", "test"]) {
+    if (existsSync2(join2(projectDir, d)))
+      return `${d}/**/*.test.ts`;
+  }
+  return "**/*.test.ts";
+}
+async function initConfig(projectDir, opts = {}) {
+  const configPath = join2(projectDir, "stryker.conf.json");
+  const warnings = [];
+  let pluginRef;
+  try {
+    pluginRef = resolvePluginRef(projectDir);
+  } catch {
+    throw new Error("Cannot resolve @fairfox/polly from here. Run `polly mutate init` in a project that depends on @fairfox/polly.");
+  }
+  const mutate = detectMutate(projectDir);
+  const testGlob = detectTestGlob(projectDir);
+  if (!existsSync2(join2(projectDir, "src"))) {
+    warnings.push("no src/ directory — adjust the `mutate` globs to point at your source");
+  }
+  if (!existsSync2(join2(projectDir, "tests")) && !existsSync2(join2(projectDir, "test"))) {
+    warnings.push(`no tests/ directory — using "${testGlob}"; adjust bun.testFiles if needed`);
+  }
+  if (existsSync2(configPath) && !opts.force) {
+    return { configPath, created: false, pluginRef, mutate, testGlob, warnings };
+  }
+  const config = {
+    testRunner: "bun",
+    bun: { testFiles: [testGlob], timeout: 30000 },
+    plugins: ["stryker-mutator-bun-runner", pluginRef],
+    ignorers: ["polly-verify"],
+    coverageAnalysis: "all",
+    disableBail: true,
+    reporters: ["json", "clear-text"],
+    mutate,
+    thresholds: { high: 90, low: 70, break: null },
+    ignorePatterns: [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/.git/**",
+      "**/.stryker-tmp/**",
+      "**/reports/**"
+    ],
+    timeoutMS: 60000,
+    concurrency: 4
+  };
+  await Bun.write(configPath, `${JSON.stringify(config, null, 2)}
+`);
+  return { configPath, created: true, pluginRef, mutate, testGlob, warnings };
+}
+
+// tools/mutate/src/run.ts
+import { resolve as resolve3 } from "node:path";
+
+// tools/mutate/src/report.ts
+function greedyCover(units, universe) {
+  const remaining = new Set(universe);
+  const chosen = [];
+  const pool = new Map([...units].map(([k, v]) => [k, new Set(v)]));
+  while (remaining.size > 0) {
+    let best = null;
+    let bestGain = 0;
+    for (const [unit, set] of pool) {
+      let gain = 0;
+      for (const m of set)
+        if (remaining.has(m))
+          gain++;
+      if (gain > bestGain) {
+        bestGain = gain;
+        best = unit;
+      }
+    }
+    if (best === null || bestGain === 0)
+      break;
+    chosen.push(best);
+    for (const m of pool.get(best) ?? [])
+      remaining.delete(m);
+    pool.delete(best);
+  }
+  return chosen;
+}
+function report(db, opts = {}) {
+  const matrixComplete = opts.matrixComplete ?? true;
+  const out = [];
+  const p = (s = "") => out.push(s);
+  const tot = queryGet(db, "SELECT count(*) n, sum(status='Killed') killed, sum(status='Survived') survived, sum(status='Timeout') timeout, sum(status='NoCoverage') nocov FROM mutants") ?? { n: 0, killed: 0, survived: 0, timeout: 0, nocov: 0 };
+  const nTests = queryGet(db, "SELECT count(*) n FROM tests")?.n ?? 0;
+  const detected = tot.killed + tot.timeout;
+  const score = (detected / (tot.n - tot.nocov || 1) * 100).toFixed(1);
+  p(`MUTATION  score ${score}%   ${tot.killed} killed · ${tot.timeout} timeout · ${tot.survived} survived · ${tot.nocov} no-coverage   (${tot.n} mutants, ${nTests} tests)`);
+  if (matrixComplete) {
+    const mult = queryAll(db, `
+			SELECT CASE WHEN c=1 THEN '1' WHEN c=2 THEN '2' WHEN c BETWEEN 3 AND 5 THEN '3-5' ELSE '6+' END bucket, count(*) n
+			FROM (SELECT mutant_id, count(*) c FROM kills GROUP BY mutant_id)
+			GROUP BY bucket ORDER BY min(c)`);
+    p(`
+KILL MULTIPLICITY  (killers per killed mutant — higher = more redundancy slack)`);
+    for (const r of mult)
+      p(`  killed by ${String(r.bucket).padStart(3)} test(s): ${r.n}`);
+    const universe = new Set(queryAll(db, "SELECT DISTINCT mutant_id FROM kills").map((r) => r.mutant_id));
+    const byTest = new Map;
+    for (const r of queryAll(db, "SELECT test_id, mutant_id FROM kills")) {
+      const set = byTest.get(r.test_id) ?? new Set;
+      byTest.set(r.test_id, set);
+      set.add(r.mutant_id);
+    }
+    const byFile = new Map;
+    for (const r of queryAll(db, "SELECT t.file file, k.mutant_id mid FROM kills k JOIN tests t ON t.id=k.test_id")) {
+      const set = byFile.get(r.file) ?? new Set;
+      byFile.set(r.file, set);
+      set.add(r.mid);
+    }
+    const caseCover = greedyCover(byTest, universe);
+    const fileCover = greedyCover(byFile, universe);
+    p(`
+REDUNDANCY RATIO  (tests that kill something ÷ minimal covering set)`);
+    p(`  case level: ${byTest.size} killing tests → ${caseCover.length} needed   (${(byTest.size / Math.max(1, caseCover.length)).toFixed(2)}×, ~${byTest.size - caseCover.length} prunable)`);
+    p(`  file level: ${byFile.size} killing files → ${fileCover.length} needed   (${(byFile.size / Math.max(1, fileCover.length)).toFixed(2)}×, ~${byFile.size - fileCover.length} prunable)`);
+    const subsumedFiles = queryAll(db, `
+			WITH file_kill AS (SELECT DISTINCT t.file file, k.mutant_id mid FROM kills k JOIN tests t ON t.id=k.test_id),
+			     owner AS (SELECT mid, count(DISTINCT file) nf, min(file) only_file FROM file_kill GROUP BY mid)
+			SELECT fk.file, count(DISTINCT fk.mid) kills,
+			       sum(CASE WHEN o.nf=1 THEN 1 ELSE 0 END) unique_kills
+			FROM file_kill fk JOIN owner o ON o.mid=fk.mid
+			GROUP BY fk.file HAVING unique_kills=0 ORDER BY kills DESC`);
+    p(`
+SUBSUMED FILES  (file-level identity — safe-to-review deletion candidates)`);
+    if (subsumedFiles.length === 0)
+      p(`  none — every test file kills at least one mutant no other file catches`);
+    for (const r of subsumedFiles)
+      p(`  ${r.file}  (${r.kills} kills, 0 unique)`);
+    const subsumedCases = queryAll(db, `
+			WITH mk AS (SELECT mutant_id, count(*) c FROM kills GROUP BY mutant_id),
+			     tk AS (SELECT test_id, count(*) total, sum(CASE WHEN mk.c=1 THEN 1 ELSE 0 END) uniq
+			            FROM kills JOIN mk USING(mutant_id) GROUP BY test_id)
+			SELECT t.file, t.name, tk.total FROM tk JOIN tests t ON t.id=tk.test_id
+			WHERE tk.total>0 AND tk.uniq=0 ORDER BY t.file, tk.total DESC`);
+    const byFileCases = new Map;
+    for (const r of subsumedCases) {
+      const rows = byFileCases.get(r.file) ?? [];
+      byFileCases.set(r.file, rows);
+      rows.push(r);
+    }
+    p(`
+SUBSUMED CASES  (${subsumedCases.length} individual tests whose every kill is caught elsewhere)`);
+    for (const [file, rows] of byFileCases) {
+      p(`  ${file}`);
+      for (const r of rows)
+        p(`      “${r.name}” (${r.total} kills, 0 unique)`);
+    }
+  } else {
+    p(`
+⚠ KILL MATRIX INCOMPLETE — redundancy/subsumption analysis suppressed.`);
+    p(`  Every mutant has at most one recorded killer, so "which tests are redundant"`);
+    p(`  cannot be derived. This needs the no-bail patched Bun runner (not shipped with`);
+    p(`  @fairfox/polly). Run 'polly mutate verify' to diagnose. Score/gaps/theatre below still hold.`);
+  }
+  const srcFile = queryGet(db, "SELECT file FROM mutants LIMIT 1")?.file;
+  const gaps = queryAll(db, "SELECT line, mutator, count(*) n FROM mutants WHERE status='NoCoverage' GROUP BY line, mutator ORDER BY line");
+  const gapTotal = gaps.reduce((a, r) => a + r.n, 0);
+  p(`
+GAPS  (NoCoverage — no test executes this code: ${gapTotal})`);
+  if (gapTotal === 0)
+    p(`  none — every mutable location is reached by some test`);
+  for (const r of gaps)
+    p(`  ${srcFile}:${r.line}  ${r.mutator}${r.n > 1 ? ` ×${r.n}` : ""}`);
+  const theatre = queryAll(db, "SELECT line, mutator, count(*) n FROM mutants WHERE status='Survived' GROUP BY line, mutator ORDER BY line");
+  const theatreTotal = theatre.reduce((a, r) => a + r.n, 0);
+  p(`
+THEATRE  (Survived — code is covered but no test detects the mutation: ${theatreTotal})`);
+  if (theatreTotal === 0)
+    p(`  none`);
+  for (const r of theatre)
+    p(`  ${srcFile}:${r.line}  ${r.mutator}${r.n > 1 ? ` ×${r.n}` : ""}`);
+  return out.join(`
+`);
+}
+if (false) {}
+
+// tools/mutate/src/verify-matrix.ts
+var DEFAULT_REPORT2 = "reports/mutation/mutation.json";
+function isMatrixComplete(report2) {
+  const mutants = Object.values(report2.files).flatMap((f) => f.mutants);
+  if (mutants.length === 0)
+    return false;
+  const killed = mutants.filter((m) => m.status === "Killed");
+  const multiKiller = killed.some((m) => (m.killedBy ?? []).length > 1);
+  const noCov = mutants.filter((m) => m.status === "NoCoverage").length;
+  const coverageCollected = noCov < mutants.length;
+  return multiKiller && coverageCollected;
+}
+async function verifyMatrix(opts = {}) {
+  const reportPath = opts.reportPath ?? DEFAULT_REPORT2;
+  if (opts.run) {
+    console.log("Running mutation pass (this can take many minutes for a large mutate set)...");
+    const cmd = [
+      "bunx",
+      "stryker",
+      "run",
+      ...opts.strykerConfig ? ["--configFile", opts.strykerConfig] : []
+    ];
+    const proc = Bun.spawn(cmd, { stdout: "inherit", stderr: "inherit" });
+    const code = await proc.exited;
+    if (code !== 0) {
+      return { ok: false, checks: [{ name: "stryker run", ok: false, detail: `exited ${code}` }] };
+    }
+  }
+  if (!await Bun.file(reportPath).exists()) {
+    return {
+      ok: false,
+      checks: [
+        {
+          name: "report exists",
+          ok: false,
+          detail: `no report at ${reportPath}. Run with --run, or 'bun run mutation' first.`
+        }
+      ]
+    };
+  }
+  const report2 = await loadMutationReport(reportPath);
+  const checks = [];
+  const add = (name, ok, detail) => checks.push({ name, ok, detail });
+  add("schema version present", !!report2.schemaVersion, `schemaVersion=${report2.schemaVersion}`);
+  const tfKeys = Object.keys(report2.testFiles ?? {});
+  const realPaths = tfKeys.filter((k) => k && k !== "(unknown)");
+  add("testFiles keyed by real paths", realPaths.length > 0 && !tfKeys.includes(""), `${realPaths.length} file(s): ${realPaths.slice(0, 2).join(", ")}${realPaths.length > 2 ? "…" : ""}`);
+  const testIds = new Set(Object.values(report2.testFiles ?? {}).flatMap((tf) => tf.tests.map((t) => t.id)));
+  const mutants = Object.values(report2.files).flatMap((f) => f.mutants);
+  const killed = mutants.filter((m) => m.status === "Killed");
+  const danglingKb = killed.filter((m) => (m.killedBy ?? []).some((id) => !testIds.has(id)));
+  add("every killedBy id resolves to a test", danglingKb.length === 0, `${danglingKb.length} dangling`);
+  const withKb = killed.filter((m) => (m.killedBy ?? []).length > 0);
+  const multi = killed.filter((m) => (m.killedBy ?? []).length > 1);
+  add("killed mutants carry killedBy", killed.length > 0 && withKb.length === killed.length, `${withKb.length}/${killed.length}`);
+  add("matrix is complete (no-bail): >1 killer exists", multi.length > 0, `${multi.length} mutant(s) killed by >1 test — collapses to 0 if bail re-engages`);
+  const noCov = mutants.filter((m) => m.status === "NoCoverage").length;
+  add("coverage collected (not all NoCoverage)", noCov < mutants.length, `${noCov}/${mutants.length} NoCoverage — all-NoCoverage means the coverage dump broke`);
+  return { ok: checks.every((c) => c.ok), checks };
+}
+if (false) {}
+
+// tools/mutate/src/run.ts
+async function runStryker(cfg) {
+  const autoDiscoverable = cfg.strykerConfigPath === resolve3(cfg.cwd, "stryker.conf.json");
+  const configFlag = cfg.strykerConfigPath && !autoDiscoverable ? ["--configFile", cfg.strykerConfigPath] : [];
+  const proc = Bun.spawn(["bunx", "stryker", "run", ...configFlag], {
+    cwd: cfg.cwd,
+    stdout: "inherit",
+    stderr: "inherit",
+    stdin: "inherit",
+    env: process.env
+  });
+  return await proc.exited;
+}
+async function reportFromFile(cfg) {
+  if (!await Bun.file(cfg.reportPath).exists()) {
+    throw new Error(`no mutation report at ${cfg.reportPath}. Run 'polly mutate run' (or 'bun run mutation') first, or pass --report <path>.`);
+  }
+  const mreport = await loadMutationReport(cfg.reportPath);
+  const db = buildDb(mreport, cfg.dbPath);
+  try {
+    return report(db, { matrixComplete: isMatrixComplete(mreport) });
+  } finally {
+    db.close();
+  }
+}
+async function presetAdvisory(cfg) {
+  if (!cfg.strykerConfigPath?.endsWith(".json"))
+    return null;
+  try {
+    const conf = await Bun.file(cfg.strykerConfigPath).json();
+    if ((conf.plugins ?? []).includes("@fairfox/polly/stryker"))
+      return null;
+    return "Tip: spread pollyStrykerPreset (from @fairfox/polly/stryker) into your Stryker config — " + "verify primitives (requires/ensures/…) are runtime no-ops and their mutants always survive, " + "dragging the score down with noise. See polly#143.";
+  } catch {
+    return null;
+  }
+}
+
+// tools/mutate/src/cli.ts
+var HELP = `polly mutate — mutation testing + useless-test detection
+
+Usage:
+  polly mutate init [--force]        Scaffold a stryker.conf.json for this project
+  polly mutate [run]                 Run Stryker, then print the useless-test report
+  polly mutate report                Print the report from an existing mutation.json
+  polly mutate decisions             Review verdicts: needs-review / stale / settled
+  polly mutate decisions decide <file> <keep|prune|rewrite|investigate> "<rationale>"
+  polly mutate verify [--run]        Assert the kill-matrix contract (exit 1 on drift)
+  polly mutate help                  Show this help
+
+Flags:
+  --config <path>     Stryker config (default: auto-discovered)
+  --report <path>     mutation report JSON (default: reports/mutation/mutation.json)
+  --decisions <path>  verdict log (default: .polly/test-debt/decisions.jsonl)
+  --db <path>         intermediate SQLite (default: in-memory)
+  --no-report         'run' only — skip the analysis
+  -h, --help
+
+The redundancy/subsumption sections need a COMPLETE kill matrix (the no-bail
+patched Bun runner). Without it the report degrades to score + gaps + theatre;
+'polly mutate verify' diagnoses the matrix.`;
+async function openDb(reportPath, dbPath) {
+  if (!await Bun.file(reportPath).exists()) {
+    console.log(`no mutation report at ${reportPath}. Run 'polly mutate run' first, or pass --report <path>.`);
+    return null;
+  }
+  return buildDb(await loadMutationReport(reportPath), dbPath);
+}
+async function main() {
+  const args = parseMutateArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(HELP);
+    return 0;
+  }
+  const cwd = process.cwd();
+  const cfg = await resolveMutateConfig(cwd, args);
+  switch (args.verb) {
+    case "init": {
+      const result = await initConfig(cwd, { force: args.force });
+      if (!result.created) {
+        console.log(`stryker.conf.json already exists at ${result.configPath}. Re-run with --force to overwrite.`);
+        return 1;
+      }
+      console.log(`✓ wrote ${result.configPath}`);
+      console.log(`  plugin:    ${result.pluginRef}`);
+      console.log(`  mutate:    ${result.mutate.join(", ")}`);
+      console.log(`  testFiles: ${result.testGlob}`);
+      for (const w of result.warnings)
+        console.log(`  ⚠ ${w}`);
+      console.log(`
+Next: polly mutate run`);
+      return 0;
+    }
+    case "run": {
+      const tip = await presetAdvisory(cfg);
+      if (tip)
+        console.log(`${tip}
+`);
+      const code = await runStryker(cfg);
+      if (code !== 0)
+        return code;
+      if (args.noReport)
+        return 0;
+      console.log(`
+${await reportFromFile(cfg)}`);
+      return 0;
+    }
+    case "report": {
+      console.log(await reportFromFile(cfg));
+      return 0;
+    }
+    case "decisions": {
+      const db = await openDb(cfg.reportPath, cfg.dbPath);
+      if (!db)
+        return 1;
+      try {
+        if (args.rest[0] === "decide") {
+          const [, file, verdict, ...r] = args.rest;
+          if (!file || !verdict) {
+            console.log('usage: polly mutate decisions decide <file> <keep|prune|rewrite|investigate> "<rationale>"');
+            return 1;
+          }
+          await decide(file, verdict, r.join(" ").replace(/^"|"$/g, ""), db, cfg.decisionsPath);
+        } else {
+          console.log(await status(db, cfg.decisionsPath));
+        }
+      } finally {
+        db.close();
+      }
+      return 0;
+    }
+    case "verify": {
+      const result = await verifyMatrix({
+        reportPath: cfg.reportPath,
+        run: args.run,
+        strykerConfig: cfg.strykerConfigPath ?? undefined
+      });
+      console.log(`
+Kill-matrix contract:`);
+      for (const c of result.checks)
+        console.log(`  ${c.ok ? "✓" : "✗"} ${c.name}  (${c.detail})`);
+      if (!result.ok) {
+        console.log(`
+✗ Contract broken. The pinned pair has drifted — re-check Bun version and that the patch applies (bun install).`);
+        return 1;
+      }
+      console.log(`
+✓ Kill-matrix contract holds.`);
+      return 0;
+    }
+    default:
+      console.log(`Unknown subcommand: ${args.verb}
+`);
+      console.log(HELP);
+      return 1;
+  }
+}
+main().then((code) => process.exit(code)).catch((err) => {
+  console.log(`
+❌ ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});
+
+//# debugId=768AC36DADFC60B164756E2164756E21