mjolnir-qa 0.5.36 → 0.5.37

package/CHANGELOG.md

@@ -9,6 +9,12 @@ Rule behavior changes (new rules, FP-rate changes against the corpus,
 severity changes) are first-class entries here — rule IDs are immutable
 once shipped, so this file is the record of what changed between versions.
 
+## [0.5.37] — 2026-09-08
+
+### Changes since 0
+
+- P5: mutation evidence reader — Stryker/mutmut, E1→E2 derivation, report-only (#67)
+
 ## [0.5.36] — 2026-09-08
 
 ### Changes since 0

package/dist/cli.d.mts

@@ -141,6 +141,17 @@ interface Finding {
    * stamped with the corroboration pass. Additive within schemaVersion 1.
    */
   trustLevel?: TrustLevel;
+  /**
+   * Mutation evidence (master plan P5, plan 1788853205786): what a
+   * mutation-testing report says about the code this finding points at.
+   * PROVENANCE, not proof — a survived mutant is code the suite would
+   * not notice changing; matching findings consolidate E1→E2 BY
+   * DERIVATION (documented in docs/RULE-LIFECYCLE.md), and trustLevel
+   * never rises from mutation evidence alone (nothing ran). Absent
+   * means no mutation report was available or nothing matched — never
+   * fabricated. Additive within schemaVersion 1.
+   */
+  mutationEvidence?: MutationEvidence | undefined;
   /** Repo-relative path with forward slashes, regardless of OS. */
   file: string;
   /** 1-based. */
@@ -169,6 +180,34 @@ interface Finding {
    */
   fixGroupId?: string;
 }
+/**
+ * Mutation evidence (master plan P5, plan 1788853205786 — flag 6,
+ * decision 8): provenance from a mutation-testing report
+ * (`mjolnir mutation <report>`), stamped on matching findings.
+ *
+ * PROVENANCE IS NOT TRUTH: a survived mutant is code the suite would
+ * not notice changing — evidence FOR a nearby finding, never a claim
+ * the finding is "proven real". The E1→E2 consolidation is BY
+ * DERIVATION and lives in src/mutation/derive.ts (documented in
+ * docs/RULE-LIFECYCLE.md + the machine-contract docs). trustLevel never
+ * rises from mutation evidence alone: nothing ran.
+ */
+interface MutationEvidence {
+  /** Which mutation tool produced the report. */
+  source: "stryker" | "mutmut";
+  /** How many survived mutants matched this finding. */
+  matchedMutants: number;
+  /** The mutator names of the matched mutants (deduped, sorted). */
+  mutators: string[];
+  /**
+   * "line" = the mutant's span contains the finding's position
+   * (Stryker evidence); "file" = file-level match only (mutmut —
+   * its JUnit report carries no per-mutant lines — or an unplaceable
+   * Stryker span). Same prefer-claiming-less rule as the runtime
+   * corroboration's granularity fallback.
+   */
+  granularity: "line" | "file";
+}
 interface DimensionScore {
   category: RuleCategory;
   score: number;
@@ -744,7 +783,7 @@ declare const runScan: typeof runScan$1, buildUniversalRules: typeof buildUniver
  * `scripts/sync-sarif-version.cjs` on release and guarded by
  * `tests/version-consistency.spec.ts` locally.
  */
-declare const CLI_VERSION = "0.5.36";
+declare const CLI_VERSION = "0.5.37";
 /** A usage-error detail: the offending token, when one exists. */
 interface UsageErrorDetail {
   /** The unknown flag or rejected value (e.g. `--nope`, `loud`). */
@@ -815,6 +854,19 @@ declare function runTriageCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): number;
+/** Testable `mutation` handler (master plan P5, plan 1788853205786).
+ * Reads a mutation report (Stryker JSON / mutmut junitxml), renders the
+ * survived-mutant leaderboard, and — with `--scan <path>` — re-scans the
+ * target, stamps matching findings with `mutationEvidence` (E1→E2 by
+ * derivation) and renders the stamped findings. NEVER spawns mutation
+ * tools: it reads reports the user already produced. Exit 2 when
+ * nothing in the report is recognized — honest no-evidence, not an
+ * error. Exit 0 in every other case: the reader is report-only, never a
+ * gate. */
+declare function runMutationCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): Promise<number>;
 /** Testable `badge` handler (Tier 1 #5). */
 declare function runBadgeCommand(argv: string[], io?: {
   out: Output;
@@ -891,4 +943,4 @@ declare function runHelpCommand(argv: string[], io?: {
 }): number;
 declare function isEntryPoint(): boolean;
 //#endregion
-export { CLI_VERSION, type CliArgs, EVIDENCE_OVERRIDES, KNOWN_RULE_IDS, OVERLAP_META_BY_RULE_ID, type Output, SUITE_INVALIDATING_RULE_IDS, type ScanHooks, UsageErrorDetail, buildUniversalRules, discoverRuntimeReport, err, exitForFindings, fallbackWorkspace, internalErrorMessage, isEntryPoint, isValidFindingRecord, levenshtein, main, nearestFlags, out, parseArgs, pathMatchesGlob, runBadgeCommand, runBaselineCommand, runCiInstall, runCreateRuleCommand, runDebtCommand, runDiffCommand, runDoctorCommand, runDoctorPlaywright, runExplainCommand, runFixCommand, runForensicsCommand, runHandoverCommand, runHelpCommand, runImpactCommand, runInitCommand, runPrCommentCommand, runPwReportCommand, runRulesCommand, runScan, runScanCommand, runStatsCommand, runSuppressions, runTriageCommand, usageErrorMessage };
+export { CLI_VERSION, type CliArgs, EVIDENCE_OVERRIDES, KNOWN_RULE_IDS, OVERLAP_META_BY_RULE_ID, type Output, SUITE_INVALIDATING_RULE_IDS, type ScanHooks, UsageErrorDetail, buildUniversalRules, discoverRuntimeReport, err, exitForFindings, fallbackWorkspace, internalErrorMessage, isEntryPoint, isValidFindingRecord, levenshtein, main, nearestFlags, out, parseArgs, pathMatchesGlob, runBadgeCommand, runBaselineCommand, runCiInstall, runCreateRuleCommand, runDebtCommand, runDiffCommand, runDoctorCommand, runDoctorPlaywright, runExplainCommand, runFixCommand, runForensicsCommand, runHandoverCommand, runHelpCommand, runImpactCommand, runInitCommand, runMutationCommand, runPrCommentCommand, runPwReportCommand, runRulesCommand, runScan, runScanCommand, runStatsCommand, runSuppressions, runTriageCommand, usageErrorMessage };

package/dist/cli.mjs

@@ -11178,19 +11178,19 @@ function parseJestJson(json) {
 }
 //#endregion
 //#region src/forensics/parse-junit.ts
-const MAX_INPUT = 20971520;
-function decodeEntities(s) {
+const MAX_INPUT$1 = 20971520;
+function decodeEntities$1(s) {
 	return s.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", "\"").replaceAll("&apos;", "'").replaceAll("&#39;", "'").replaceAll("&amp;", "&");
 }
 function attr(tag, name) {
 	const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 	const m = new RegExp(`(?:^|\\s)${escaped}\\s*=\\s*"([^"]*)"`, "i").exec(tag);
-	if (m?.[1] !== void 0) return decodeEntities(m[1]);
+	if (m?.[1] !== void 0) return decodeEntities$1(m[1]);
 	const m2 = new RegExp(`(?:^|\\s)${escaped}\\s*=\\s*'([^']*)'`, "i").exec(tag);
-	return m2?.[1] !== void 0 ? decodeEntities(m2[1]) : void 0;
+	return m2?.[1] !== void 0 ? decodeEntities$1(m2[1]) : void 0;
 }
 function parseJunitXml(xml) {
-	if (xml.length > MAX_INPUT) return [];
+	if (xml.length > MAX_INPUT$1) return [];
 	const out = [];
 	const startRe = /<testcase\b/gi;
 	const closeRe = /<\/testcase\s*>/gi;
@@ -11345,7 +11345,7 @@ function parseVitestJson(json) {
 *
 * Writes FLAKY.md next to the scan target unless --no-flaky-md.
 */
-const MAX_FILES = 500;
+const MAX_FILES$1 = 500;
 function runForensics(target, options = {}) {
 	const records = [];
 	let source = "playwright-json";
@@ -11369,7 +11369,7 @@ function runForensics(target, options = {}) {
 	else {
 		let count = 0;
 		for (const full of listFiles(target)) {
-			if (++count > MAX_FILES) break;
+			if (++count > MAX_FILES$1) break;
 			try {
 				const parsed = parseFile(full, readFileSync(full, "utf8"));
 				if (parsed.records.length === 0) continue;
@@ -11437,7 +11437,7 @@ function parseFile(path, text) {
 function listFiles(dir) {
 	const out = [];
 	const walk = (d, depth) => {
-		if (depth > 4 || out.length > MAX_FILES) return;
+		if (depth > 4 || out.length > MAX_FILES$1) return;
 		let entries;
 		try {
 			entries = readdirSync(d, { withFileTypes: true });
@@ -13464,7 +13464,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.36",
+			version: "0.5.37",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -16314,6 +16314,220 @@ function renderTriageMd(report) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/mutation/parse-stryker.ts
+const MAX_FILES = 5e3;
+const MAX_MUTANTS_PER_FILE = 2e4;
+/** Sniff: does this parsed JSON look like a Stryker mutation report? */
+function looksLikeStrykerJson(json) {
+	if (!json || typeof json !== "object") return false;
+	return typeof json.files === "object" && json.files !== null;
+}
+function parseStrykerJson(json) {
+	if (!json || typeof json !== "object") return {
+		tool: "stryker",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+	const files = json.files;
+	if (!files || typeof files !== "object") return {
+		tool: "stryker",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+	const survived = [];
+	let noCoverage = 0;
+	let killed = 0;
+	const entries = Object.entries(files).slice(0, MAX_FILES);
+	for (const [rawPath, file] of entries) {
+		if (!file || typeof file !== "object") continue;
+		const mutants = Array.isArray(file.mutants) ? file.mutants : [];
+		const path = rawPath.replaceAll("\\", "/");
+		for (const m of mutants.slice(0, MAX_MUTANTS_PER_FILE)) {
+			if (!m || typeof m !== "object") continue;
+			if (m.status === "Survived") {
+				const startLine = toOneBased(m.location?.start?.line);
+				const endLine = toOneBased(m.location?.end?.line);
+				if (startLine === void 0) continue;
+				survived.push({
+					file: path,
+					mutator: typeof m.mutatorName === "string" ? m.mutatorName : "unknown",
+					startLine,
+					endLine: endLine !== void 0 ? Math.max(startLine, endLine) : startLine
+				});
+			} else if (m.status === "NoCoverage") noCoverage++;
+			else if (m.status === "Killed" || m.status === "Timeout") killed++;
+		}
+	}
+	return {
+		tool: "stryker",
+		survived,
+		noCoverage,
+		killed
+	};
+}
+function toOneBased(line) {
+	return typeof line === "number" && line >= 0 ? line + 1 : void 0;
+}
+//#endregion
+//#region src/mutation/parse-mutmut.ts
+const MAX_INPUT = 20971520;
+/** Sniff: does this XML look like mutmut's junit output? */
+function looksLikeMutmutXml(xml) {
+	return xml.length <= MAX_INPUT && /mutmut/i.test(xml.slice(0, 4e3));
+}
+function decodeEntities(s) {
+	return s.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", "\"").replaceAll("&apos;", "'").replaceAll("&#39;", "'").replaceAll("&amp;", "&");
+}
+/**
+* The file for a testcase: mutmut 2.x writes
+* `classname="tests.test_auth-mutmut0::x_mutmut_1"`-style classes whose
+* FIRST dot-separated segment before `-mutmut` is the module path;
+* mutmut 3.x writes the path directly in `classname`. Both are
+* normalized here to a repo-relative path with `.py` intact.
+*/
+function fileFromClassname(classname) {
+	const decoded = decodeEntities(classname);
+	const cut = decoded.indexOf("-mutmut");
+	const candidate = (cut !== -1 ? decoded.slice(0, cut) : decoded).trim();
+	if (candidate.length === 0) return null;
+	return candidate.replaceAll(".", "/") + ".py";
+}
+function parseMutmutXml(xml) {
+	if (xml.length > MAX_INPUT) return {
+		tool: "mutmut",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+	const survived = [];
+	let noCoverage = 0;
+	let killed = 0;
+	const startRe = /<testcase\b/gi;
+	const closeRe = /<\/testcase\s*>/gi;
+	let start;
+	while ((start = startRe.exec(xml)) !== null) {
+		const gt = xml.indexOf(">", start.index);
+		if (gt === -1) break;
+		const attrs = xml.slice(start.index + 9, gt);
+		let inner;
+		if (attrs.endsWith("/")) {
+			inner = "";
+			startRe.lastIndex = gt + 1;
+		} else {
+			closeRe.lastIndex = gt + 1;
+			const close = closeRe.exec(xml);
+			if (close === null) break;
+			inner = xml.slice(gt + 1, close.index);
+			startRe.lastIndex = close.index + close[0].length;
+		}
+		const classname = /(?:^|\s)classname\s*=\s*"([^"]*)"/i.exec(attrs)?.[1] ?? "";
+		if (/<skipped\b/i.test(inner)) {
+			noCoverage++;
+			continue;
+		}
+		const killedMutant = /<(?:failure|error)\b/i.test(inner);
+		const verdict = {
+			file: fileFromClassname(classname),
+			survived: !killedMutant
+		};
+		if (killedMutant) killed++;
+		else if (verdict.file !== null) survived.push({
+			file: verdict.file,
+			mutator: "mutmut",
+			startLine: 1,
+			endLine: Number.MAX_SAFE_INTEGER
+		});
+		else noCoverage++;
+	}
+	return {
+		tool: "mutmut",
+		survived,
+		noCoverage,
+		killed
+	};
+}
+//#endregion
+//#region src/mutation/derive.ts
+/**
+* Stamp mutation evidence onto findings (mutates in place, the same
+* contract as stampEvidenceLevels). Returns the stamp stats.
+*/
+function stampMutationEvidence(findings, report) {
+	const byFile = /* @__PURE__ */ new Map();
+	for (const m of report.survived) {
+		const list = byFile.get(m.file) ?? [];
+		list.push(m);
+		byFile.set(m.file, list);
+	}
+	let stamped = 0;
+	let derived = 0;
+	for (const f of findings) {
+		const mutants = byFile.get(f.file);
+		if (!mutants || mutants.length === 0) continue;
+		let matched = mutants.filter((m) => f.line >= m.startLine && f.line <= m.endLine);
+		let granularity = "line";
+		if (matched.length === 0) {
+			matched = mutants;
+			granularity = "file";
+		}
+		f.mutationEvidence = {
+			source: report.tool,
+			matchedMutants: matched.length,
+			mutators: [...new Set(matched.map((m) => m.mutator))].sort(),
+			granularity
+		};
+		stamped++;
+		if (f.evidenceLevel === "E1") {
+			f.evidenceLevel = "E2";
+			derived++;
+		}
+	}
+	return {
+		stamped,
+		derived
+	};
+}
+/**
+* Survived-mutant leaderboard: most-mutated files first. The summary's
+* honesty headline: files here are code the suite demonstrably does not
+* constrain — regardless of what any static tool found.
+*/
+function survivedLeaderboard(report, top = 25) {
+	const byFile = /* @__PURE__ */ new Map();
+	for (const m of report.survived) {
+		const list = byFile.get(m.file) ?? [];
+		list.push(m);
+		byFile.set(m.file, list);
+	}
+	return [...byFile.entries()].map(([file, mutants]) => ({
+		file,
+		survived: mutants.length,
+		mutators: [...new Set(mutants.map((m) => m.mutator))].sort()
+	})).sort((a, b) => b.survived - a.survived).slice(0, top);
+}
+function renderMutationSummary(report) {
+	const lines = [];
+	lines.push(`MUTATION EVIDENCE — ${report.tool}`);
+	lines.push("");
+	lines.push(`${report.survived.length} survived · ${report.killed} killed · ${report.noCoverage} no-coverage`);
+	lines.push("");
+	const top = survivedLeaderboard(report);
+	if (top.length === 0) {
+		lines.push("No survived mutants — every executed mutant was killed.");
+		lines.push("");
+		lines.push("Interpretation: the suite constrains the code the mutation run reached. This is evidence about THOSE mutants only — untested surfaces are the no-coverage column, and no-coverage is not survived.");
+		return lines.join("\n");
+	}
+	lines.push("Files the suite does not constrain (most survived first):");
+	lines.push("");
+	for (const row of top) lines.push(`  ${row.survived}× ${row.file} [${row.mutators.join(", ")}]`);
+	lines.push("");
+	lines.push("A survived mutant is not a bug — it is code the suite would not notice changing. Findings near these lines were consolidated E1→E2 by derivation (see docs/RULE-LIFECYCLE.md).");
+	return lines.join("\n");
+}
+//#endregion
 //#region src/commands/badge.ts
 /**
 * `mjolnir badge` — evidentiary shields.io endpoint JSON (Tier 1 #5).
@@ -16422,6 +16636,12 @@ const HELP_ENTRIES = [
 		usage: "mjolnir triage <test-results-dir-or-report-file> [--no-md]",
 		examples: ["mjolnir triage test-results --no-md"]
 	},
+	{
+		verb: "mutation",
+		summary: "mutation-evidence reader: survived-mutant leaderboard + E1→E2 derivation",
+		usage: "mjolnir mutation <mutation-report> [--scan .]",
+		examples: ["mjolnir mutation reports/mutation-report.json", "mjolnir mutation reports/… --scan ."]
+	},
 	{
 		verb: "pw-report",
 		summary: "Playwright run summary (counts, true flakes, slowest tests)",
@@ -16704,6 +16924,10 @@ const GROUPS = [
 			"doctor:playwright"
 		]
 	},
+	{
+		title: "Mutation evidence",
+		verbs: ["mutation"]
+	},
 	{
 		title: "Maintenance",
 		verbs: [
@@ -19022,7 +19246,7 @@ const { runScan, buildUniversalRules, fallbackWorkspace, pathMatchesGlob, isVali
 * `scripts/sync-sarif-version.cjs` on release and guarded by
 * `tests/version-consistency.spec.ts` locally.
 */
-const CLI_VERSION = "0.5.36";
+const CLI_VERSION = "0.5.37";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",
@@ -19508,6 +19732,97 @@ function runTriageCommand(argv, io = {
 		return 20;
 	}
 }
+/**
+* Sniff + parse a mutation report: Stryker JSON, mutmut junitxml, else
+* an empty report (the caller renders the honest "nothing recognized").
+*/
+function ingestMutationReport(text) {
+	const trimmed = text.trimStart();
+	if (trimmed.startsWith("<?xml") || trimmed.startsWith("<testsuite")) return parseMutmutXml(text);
+	try {
+		const json = JSON.parse(text);
+		if (looksLikeStrykerJson(json)) return parseStrykerJson(json);
+	} catch {}
+	if (looksLikeMutmutXml(text)) return parseMutmutXml(text);
+	return {
+		tool: "stryker",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+}
+/** Testable `mutation` handler (master plan P5, plan 1788853205786).
+* Reads a mutation report (Stryker JSON / mutmut junitxml), renders the
+* survived-mutant leaderboard, and — with `--scan <path>` — re-scans the
+* target, stamps matching findings with `mutationEvidence` (E1→E2 by
+* derivation) and renders the stamped findings. NEVER spawns mutation
+* tools: it reads reports the user already produced. Exit 2 when
+* nothing in the report is recognized — honest no-evidence, not an
+* error. Exit 0 in every other case: the reader is report-only, never a
+* gate. */
+async function runMutationCommand(argv, io = {
+	out,
+	err
+}) {
+	const targetArg = argv.find((a) => !a.startsWith("-"));
+	if (!targetArg) {
+		io.err("Usage: mjolnir mutation <mutation-report> [--scan <path>]");
+		return 10;
+	}
+	const scanIdx = argv.indexOf("--scan");
+	const scanArg = scanIdx !== -1 ? argv[scanIdx + 1] : void 0;
+	if (scanIdx !== -1 && (!scanArg || scanArg.startsWith("-"))) {
+		io.err("--scan requires a path argument");
+		return 10;
+	}
+	let report;
+	try {
+		const path = resolve(targetArg);
+		if (!existsSync(path)) {
+			io.err(`No such file: ${path}`);
+			return 2;
+		}
+		report = ingestMutationReport(readFileSync(path, "utf8"));
+		if (report.survived.length === 0 && report.killed === 0 && report.noCoverage === 0) {
+			io.err("No mutants recognized. Expected a Stryker JSON report (mutation-report.json) or a mutmut junitxml report.");
+			return 2;
+		}
+	} catch (err) {
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
+		return 20;
+	}
+	io.out(renderMutationSummary(report));
+	if (scanArg === void 0) return 0;
+	try {
+		const scanPath = resolve(scanArg);
+		const invalid = validateScanTarget(scanPath, io.err);
+		if (invalid !== null) return invalid;
+		const result = await runScan({
+			target: scanPath,
+			json: true,
+			verbose: true,
+			maxDurationMs: 12e4,
+			scopeChanged: false,
+			format: "json"
+		});
+		const stats = stampMutationEvidence(result.findings, report);
+		io.out("");
+		if (stats.stamped === 0) io.out("No findings intersect the survived-mutant surface — nothing to derive.");
+		else {
+			io.out(`${stats.stamped} finding(s) carry mutationEvidence (${stats.derived} consolidated E1→E2 by derivation — docs/RULE-LIFECYCLE.md):`);
+			for (const f of result.findings) {
+				if (!f.mutationEvidence) continue;
+				io.out(`  ${f.ruleId} ${f.file}:${f.line} — ${f.evidenceLevel} · ${f.mutationEvidence.matchedMutants} mutant(s) @ ${f.mutationEvidence.granularity} granularity`);
+			}
+			io.out("");
+			io.out("Machine form: re-run with --json — mutationEvidence rides the findings additively.");
+		}
+		return 0;
+	} catch (err) {
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
+		return 20;
+	}
+}
 /** Testable `badge` handler (Tier 1 #5). */
 async function runBadgeCommand(argv, io = {
 	out,
@@ -19886,6 +20201,7 @@ async function main(argv = process$1.argv.slice(2), io = {
 	if (argv[0] === "suppressions") return runSuppressions();
 	if (argv[0] === "forensics") return runForensicsCommand(argv.slice(1));
 	if (argv[0] === "triage") return runTriageCommand(argv.slice(1));
+	if (argv[0] === "mutation") return runMutationCommand(argv.slice(1), io);
 	if (argv[0] === "badge") return runBadgeCommand(argv.slice(1));
 	if (argv[0] === "debt") return runDebtCommand(argv.slice(1));
 	if (argv[0] === "impact") return runImpactCommand(argv.slice(1));
@@ -19962,4 +20278,4 @@ function isEntryPoint() {
 }
 if (isEntryPoint()) process$1.exitCode = await main();
 //#endregion
-export { CLI_VERSION, EVIDENCE_OVERRIDES, KNOWN_RULE_IDS, OVERLAP_META_BY_RULE_ID, SUITE_INVALIDATING_RULE_IDS, buildUniversalRules, discoverRuntimeReport, err, exitForFindings, fallbackWorkspace, internalErrorMessage, isEntryPoint, isValidFindingRecord, levenshtein, main, nearestFlags, out, parseArgs, pathMatchesGlob, runBadgeCommand, runBaselineCommand, runCiInstall, runCreateRuleCommand, runDebtCommand, runDiffCommand, runDoctorCommand, runDoctorPlaywright, runExplainCommand, runFixCommand, runForensicsCommand, runHandoverCommand, runHelpCommand, runImpactCommand, runInitCommand, runPrCommentCommand, runPwReportCommand, runRulesCommand, runScan, runScanCommand, runStatsCommand, runSuppressions, runTriageCommand, usageErrorMessage };
+export { CLI_VERSION, EVIDENCE_OVERRIDES, KNOWN_RULE_IDS, OVERLAP_META_BY_RULE_ID, SUITE_INVALIDATING_RULE_IDS, buildUniversalRules, discoverRuntimeReport, err, exitForFindings, fallbackWorkspace, internalErrorMessage, isEntryPoint, isValidFindingRecord, levenshtein, main, nearestFlags, out, parseArgs, pathMatchesGlob, runBadgeCommand, runBaselineCommand, runCiInstall, runCreateRuleCommand, runDebtCommand, runDiffCommand, runDoctorCommand, runDoctorPlaywright, runExplainCommand, runFixCommand, runForensicsCommand, runHandoverCommand, runHelpCommand, runImpactCommand, runInitCommand, runMutationCommand, runPrCommentCommand, runPwReportCommand, runRulesCommand, runScan, runScanCommand, runStatsCommand, runSuppressions, runTriageCommand, usageErrorMessage };

package/dist/mcp/stdio.mjs

@@ -11177,19 +11177,19 @@ function parseJestJson(json) {
 }
 //#endregion
 //#region src/forensics/parse-junit.ts
-const MAX_INPUT = 20971520;
-function decodeEntities(s) {
+const MAX_INPUT$1 = 20971520;
+function decodeEntities$1(s) {
 	return s.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", "\"").replaceAll("&apos;", "'").replaceAll("&#39;", "'").replaceAll("&amp;", "&");
 }
 function attr(tag, name) {
 	const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 	const m = new RegExp(`(?:^|\\s)${escaped}\\s*=\\s*"([^"]*)"`, "i").exec(tag);
-	if (m?.[1] !== void 0) return decodeEntities(m[1]);
+	if (m?.[1] !== void 0) return decodeEntities$1(m[1]);
 	const m2 = new RegExp(`(?:^|\\s)${escaped}\\s*=\\s*'([^']*)'`, "i").exec(tag);
-	return m2?.[1] !== void 0 ? decodeEntities(m2[1]) : void 0;
+	return m2?.[1] !== void 0 ? decodeEntities$1(m2[1]) : void 0;
 }
 function parseJunitXml(xml) {
-	if (xml.length > MAX_INPUT) return [];
+	if (xml.length > MAX_INPUT$1) return [];
 	const out = [];
 	const startRe = /<testcase\b/gi;
 	const closeRe = /<\/testcase\s*>/gi;
@@ -11344,7 +11344,7 @@ function parseVitestJson(json) {
 *
 * Writes FLAKY.md next to the scan target unless --no-flaky-md.
 */
-const MAX_FILES = 500;
+const MAX_FILES$1 = 500;
 function runForensics(target, options = {}) {
 	const records = [];
 	let source = "playwright-json";
@@ -11368,7 +11368,7 @@ function runForensics(target, options = {}) {
 	else {
 		let count = 0;
 		for (const full of listFiles(target)) {
-			if (++count > MAX_FILES) break;
+			if (++count > MAX_FILES$1) break;
 			try {
 				const parsed = parseFile(full, readFileSync(full, "utf8"));
 				if (parsed.records.length === 0) continue;
@@ -11436,7 +11436,7 @@ function parseFile(path, text) {
 function listFiles(dir) {
 	const out = [];
 	const walk = (d, depth) => {
-		if (depth > 4 || out.length > MAX_FILES) return;
+		if (depth > 4 || out.length > MAX_FILES$1) return;
 		let entries;
 		try {
 			entries = readdirSync(d, { withFileTypes: true });
@@ -13463,7 +13463,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.36",
+			version: "0.5.37",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -15411,6 +15411,220 @@ function renderTriageMd(report) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/mutation/parse-stryker.ts
+const MAX_FILES = 5e3;
+const MAX_MUTANTS_PER_FILE = 2e4;
+/** Sniff: does this parsed JSON look like a Stryker mutation report? */
+function looksLikeStrykerJson(json) {
+	if (!json || typeof json !== "object") return false;
+	return typeof json.files === "object" && json.files !== null;
+}
+function parseStrykerJson(json) {
+	if (!json || typeof json !== "object") return {
+		tool: "stryker",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+	const files = json.files;
+	if (!files || typeof files !== "object") return {
+		tool: "stryker",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+	const survived = [];
+	let noCoverage = 0;
+	let killed = 0;
+	const entries = Object.entries(files).slice(0, MAX_FILES);
+	for (const [rawPath, file] of entries) {
+		if (!file || typeof file !== "object") continue;
+		const mutants = Array.isArray(file.mutants) ? file.mutants : [];
+		const path = rawPath.replaceAll("\\", "/");
+		for (const m of mutants.slice(0, MAX_MUTANTS_PER_FILE)) {
+			if (!m || typeof m !== "object") continue;
+			if (m.status === "Survived") {
+				const startLine = toOneBased(m.location?.start?.line);
+				const endLine = toOneBased(m.location?.end?.line);
+				if (startLine === void 0) continue;
+				survived.push({
+					file: path,
+					mutator: typeof m.mutatorName === "string" ? m.mutatorName : "unknown",
+					startLine,
+					endLine: endLine !== void 0 ? Math.max(startLine, endLine) : startLine
+				});
+			} else if (m.status === "NoCoverage") noCoverage++;
+			else if (m.status === "Killed" || m.status === "Timeout") killed++;
+		}
+	}
+	return {
+		tool: "stryker",
+		survived,
+		noCoverage,
+		killed
+	};
+}
+function toOneBased(line) {
+	return typeof line === "number" && line >= 0 ? line + 1 : void 0;
+}
+//#endregion
+//#region src/mutation/parse-mutmut.ts
+const MAX_INPUT = 20971520;
+/** Sniff: does this XML look like mutmut's junit output? */
+function looksLikeMutmutXml(xml) {
+	return xml.length <= MAX_INPUT && /mutmut/i.test(xml.slice(0, 4e3));
+}
+function decodeEntities(s) {
+	return s.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", "\"").replaceAll("&apos;", "'").replaceAll("&#39;", "'").replaceAll("&amp;", "&");
+}
+/**
+* The file for a testcase: mutmut 2.x writes
+* `classname="tests.test_auth-mutmut0::x_mutmut_1"`-style classes whose
+* FIRST dot-separated segment before `-mutmut` is the module path;
+* mutmut 3.x writes the path directly in `classname`. Both are
+* normalized here to a repo-relative path with `.py` intact.
+*/
+function fileFromClassname(classname) {
+	const decoded = decodeEntities(classname);
+	const cut = decoded.indexOf("-mutmut");
+	const candidate = (cut !== -1 ? decoded.slice(0, cut) : decoded).trim();
+	if (candidate.length === 0) return null;
+	return candidate.replaceAll(".", "/") + ".py";
+}
+function parseMutmutXml(xml) {
+	if (xml.length > MAX_INPUT) return {
+		tool: "mutmut",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+	const survived = [];
+	let noCoverage = 0;
+	let killed = 0;
+	const startRe = /<testcase\b/gi;
+	const closeRe = /<\/testcase\s*>/gi;
+	let start;
+	while ((start = startRe.exec(xml)) !== null) {
+		const gt = xml.indexOf(">", start.index);
+		if (gt === -1) break;
+		const attrs = xml.slice(start.index + 9, gt);
+		let inner;
+		if (attrs.endsWith("/")) {
+			inner = "";
+			startRe.lastIndex = gt + 1;
+		} else {
+			closeRe.lastIndex = gt + 1;
+			const close = closeRe.exec(xml);
+			if (close === null) break;
+			inner = xml.slice(gt + 1, close.index);
+			startRe.lastIndex = close.index + close[0].length;
+		}
+		const classname = /(?:^|\s)classname\s*=\s*"([^"]*)"/i.exec(attrs)?.[1] ?? "";
+		if (/<skipped\b/i.test(inner)) {
+			noCoverage++;
+			continue;
+		}
+		const killedMutant = /<(?:failure|error)\b/i.test(inner);
+		const verdict = {
+			file: fileFromClassname(classname),
+			survived: !killedMutant
+		};
+		if (killedMutant) killed++;
+		else if (verdict.file !== null) survived.push({
+			file: verdict.file,
+			mutator: "mutmut",
+			startLine: 1,
+			endLine: Number.MAX_SAFE_INTEGER
+		});
+		else noCoverage++;
+	}
+	return {
+		tool: "mutmut",
+		survived,
+		noCoverage,
+		killed
+	};
+}
+//#endregion
+//#region src/mutation/derive.ts
+/**
+* Stamp mutation evidence onto findings (mutates in place, the same
+* contract as stampEvidenceLevels). Returns the stamp stats.
+*/
+function stampMutationEvidence(findings, report) {
+	const byFile = /* @__PURE__ */ new Map();
+	for (const m of report.survived) {
+		const list = byFile.get(m.file) ?? [];
+		list.push(m);
+		byFile.set(m.file, list);
+	}
+	let stamped = 0;
+	let derived = 0;
+	for (const f of findings) {
+		const mutants = byFile.get(f.file);
+		if (!mutants || mutants.length === 0) continue;
+		let matched = mutants.filter((m) => f.line >= m.startLine && f.line <= m.endLine);
+		let granularity = "line";
+		if (matched.length === 0) {
+			matched = mutants;
+			granularity = "file";
+		}
+		f.mutationEvidence = {
+			source: report.tool,
+			matchedMutants: matched.length,
+			mutators: [...new Set(matched.map((m) => m.mutator))].sort(),
+			granularity
+		};
+		stamped++;
+		if (f.evidenceLevel === "E1") {
+			f.evidenceLevel = "E2";
+			derived++;
+		}
+	}
+	return {
+		stamped,
+		derived
+	};
+}
+/**
+* Survived-mutant leaderboard: most-mutated files first. The summary's
+* honesty headline: files here are code the suite demonstrably does not
+* constrain — regardless of what any static tool found.
+*/
+function survivedLeaderboard(report, top = 25) {
+	const byFile = /* @__PURE__ */ new Map();
+	for (const m of report.survived) {
+		const list = byFile.get(m.file) ?? [];
+		list.push(m);
+		byFile.set(m.file, list);
+	}
+	return [...byFile.entries()].map(([file, mutants]) => ({
+		file,
+		survived: mutants.length,
+		mutators: [...new Set(mutants.map((m) => m.mutator))].sort()
+	})).sort((a, b) => b.survived - a.survived).slice(0, top);
+}
+function renderMutationSummary(report) {
+	const lines = [];
+	lines.push(`MUTATION EVIDENCE — ${report.tool}`);
+	lines.push("");
+	lines.push(`${report.survived.length} survived · ${report.killed} killed · ${report.noCoverage} no-coverage`);
+	lines.push("");
+	const top = survivedLeaderboard(report);
+	if (top.length === 0) {
+		lines.push("No survived mutants — every executed mutant was killed.");
+		lines.push("");
+		lines.push("Interpretation: the suite constrains the code the mutation run reached. This is evidence about THOSE mutants only — untested surfaces are the no-coverage column, and no-coverage is not survived.");
+		return lines.join("\n");
+	}
+	lines.push("Files the suite does not constrain (most survived first):");
+	lines.push("");
+	for (const row of top) lines.push(`  ${row.survived}× ${row.file} [${row.mutators.join(", ")}]`);
+	lines.push("");
+	lines.push("A survived mutant is not a bug — it is code the suite would not notice changing. Findings near these lines were consolidated E1→E2 by derivation (see docs/RULE-LIFECYCLE.md).");
+	return lines.join("\n");
+}
+//#endregion
 //#region src/lib/fs-atomic.ts
 /**
 * Atomic file writes (audit S9).
@@ -15613,6 +15827,12 @@ const HELP_ENTRIES = [
 		usage: "mjolnir triage <test-results-dir-or-report-file> [--no-md]",
 		examples: ["mjolnir triage test-results --no-md"]
 	},
+	{
+		verb: "mutation",
+		summary: "mutation-evidence reader: survived-mutant leaderboard + E1→E2 derivation",
+		usage: "mjolnir mutation <mutation-report> [--scan .]",
+		examples: ["mjolnir mutation reports/mutation-report.json", "mjolnir mutation reports/… --scan ."]
+	},
 	{
 		verb: "pw-report",
 		summary: "Playwright run summary (counts, true flakes, slowest tests)",
@@ -15895,6 +16115,10 @@ const GROUPS = [
 			"doctor:playwright"
 		]
 	},
+	{
+		title: "Mutation evidence",
+		verbs: ["mutation"]
+	},
 	{
 		title: "Maintenance",
 		verbs: [
@@ -18658,7 +18882,7 @@ const { runScan, buildUniversalRules, fallbackWorkspace, pathMatchesGlob, isVali
 * `scripts/sync-sarif-version.cjs` on release and guarded by
 * `tests/version-consistency.spec.ts` locally.
 */
-const CLI_VERSION = "0.5.36";
+const CLI_VERSION = "0.5.37";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",
@@ -19144,6 +19368,97 @@ function runTriageCommand(argv, io = {
 		return 20;
 	}
 }
+/**
+* Sniff + parse a mutation report: Stryker JSON, mutmut junitxml, else
+* an empty report (the caller renders the honest "nothing recognized").
+*/
+function ingestMutationReport(text) {
+	const trimmed = text.trimStart();
+	if (trimmed.startsWith("<?xml") || trimmed.startsWith("<testsuite")) return parseMutmutXml(text);
+	try {
+		const json = JSON.parse(text);
+		if (looksLikeStrykerJson(json)) return parseStrykerJson(json);
+	} catch {}
+	if (looksLikeMutmutXml(text)) return parseMutmutXml(text);
+	return {
+		tool: "stryker",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+}
+/** Testable `mutation` handler (master plan P5, plan 1788853205786).
+* Reads a mutation report (Stryker JSON / mutmut junitxml), renders the
+* survived-mutant leaderboard, and — with `--scan <path>` — re-scans the
+* target, stamps matching findings with `mutationEvidence` (E1→E2 by
+* derivation) and renders the stamped findings. NEVER spawns mutation
+* tools: it reads reports the user already produced. Exit 2 when
+* nothing in the report is recognized — honest no-evidence, not an
+* error. Exit 0 in every other case: the reader is report-only, never a
+* gate. */
+async function runMutationCommand(argv, io = {
+	out,
+	err
+}) {
+	const targetArg = argv.find((a) => !a.startsWith("-"));
+	if (!targetArg) {
+		io.err("Usage: mjolnir mutation <mutation-report> [--scan <path>]");
+		return 10;
+	}
+	const scanIdx = argv.indexOf("--scan");
+	const scanArg = scanIdx !== -1 ? argv[scanIdx + 1] : void 0;
+	if (scanIdx !== -1 && (!scanArg || scanArg.startsWith("-"))) {
+		io.err("--scan requires a path argument");
+		return 10;
+	}
+	let report;
+	try {
+		const path = resolve(targetArg);
+		if (!existsSync(path)) {
+			io.err(`No such file: ${path}`);
+			return 2;
+		}
+		report = ingestMutationReport(readFileSync(path, "utf8"));
+		if (report.survived.length === 0 && report.killed === 0 && report.noCoverage === 0) {
+			io.err("No mutants recognized. Expected a Stryker JSON report (mutation-report.json) or a mutmut junitxml report.");
+			return 2;
+		}
+	} catch (err) {
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
+		return 20;
+	}
+	io.out(renderMutationSummary(report));
+	if (scanArg === void 0) return 0;
+	try {
+		const scanPath = resolve(scanArg);
+		const invalid = validateScanTarget(scanPath, io.err);
+		if (invalid !== null) return invalid;
+		const result = await runScan({
+			target: scanPath,
+			json: true,
+			verbose: true,
+			maxDurationMs: 12e4,
+			scopeChanged: false,
+			format: "json"
+		});
+		const stats = stampMutationEvidence(result.findings, report);
+		io.out("");
+		if (stats.stamped === 0) io.out("No findings intersect the survived-mutant surface — nothing to derive.");
+		else {
+			io.out(`${stats.stamped} finding(s) carry mutationEvidence (${stats.derived} consolidated E1→E2 by derivation — docs/RULE-LIFECYCLE.md):`);
+			for (const f of result.findings) {
+				if (!f.mutationEvidence) continue;
+				io.out(`  ${f.ruleId} ${f.file}:${f.line} — ${f.evidenceLevel} · ${f.mutationEvidence.matchedMutants} mutant(s) @ ${f.mutationEvidence.granularity} granularity`);
+			}
+			io.out("");
+			io.out("Machine form: re-run with --json — mutationEvidence rides the findings additively.");
+		}
+		return 0;
+	} catch (err) {
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
+		return 20;
+	}
+}
 /** Testable `badge` handler (Tier 1 #5). */
 async function runBadgeCommand(argv, io = {
 	out,
@@ -19522,6 +19837,7 @@ async function main(argv = process$1.argv.slice(2), io = {
 	if (argv[0] === "suppressions") return runSuppressions();
 	if (argv[0] === "forensics") return runForensicsCommand(argv.slice(1));
 	if (argv[0] === "triage") return runTriageCommand(argv.slice(1));
+	if (argv[0] === "mutation") return runMutationCommand(argv.slice(1), io);
 	if (argv[0] === "badge") return runBadgeCommand(argv.slice(1));
 	if (argv[0] === "debt") return runDebtCommand(argv.slice(1));
 	if (argv[0] === "impact") return runImpactCommand(argv.slice(1));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mjolnir-qa",
-  "version": "0.5.36",
+  "version": "0.5.37",
   "description": "Mjölnir — the Verification Trust Engine for QA. Audits test suites and CI pipelines, reports a worthiness score and prioritized findings.",
   "type": "module",
   "engines": {