@sackville-mcp/mutate 0.0.1-alpha.0

package/dist/index.mjs

@@ -0,0 +1,793 @@
+import { parse, stringify } from "smol-toml";
+import { execFile } from "node:child_process";
+import { cpSync, existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+//#region src/config.ts
+/**
+* Diff-scoping config EMITTERS for the Python mutation tools (ADR 0010 addendum 2). These turn a
+* selected-file scope into a per-run tool config, PINNED to the slice-0 captures of the installed
+* cosmic-ray 8.4.6 / mutmut 3.5.0 (see `test/fixtures/README.md`) — never doc-derived guesses:
+*
+* - cosmic-ray scopes via a `module-path` FILE LIST (Fork A — verified 8.4.6 accepts a list); its
+*   `excluded-modules` SUBTRACTS from the scope via exact path AND fnmatch glob, so an inherited
+*   exclusion that matches a selected file is reconciled (stripped), never copied blind (blocker #3).
+* - mutmut scopes via `paths_to_mutate` (Fork B was WRONG — 3.5.0 has NO `only_mutate`/`source_paths`;
+*   `paths_to_mutate` + `do_not_mutate` are the real keys, Fork F). Scoping a subset breaks the
+*   baseline unless the rest of the source tree is `also_copy`'d so unscoped tests still import; an
+*   inherited `do_not_mutate` glob matching a selected file is stripped (blocker #3, mutmut form).
+*
+* Both emitters are PURE (TOML in → TOML out via `smol-toml`). They reduce SPURIOUS inconclusives by
+* reconciling exclusions up front; the load-bearing under-scope guarantee is the POST-SPAWN
+* {@link reconcileScope} guard in the runner, which folds any genuinely-unmutated selected file to
+* inconclusive regardless of why (absence-is-never-a-pass).
+*/
+/** Thrown when a scoped config cannot be safely synthesized (empty scope, missing base table, etc.). */
+var ScopeEmitError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ScopeEmitError";
+	}
+};
+/** Normalize a path to a comparable repo-relative POSIX form (backslashes → `/`, drop a leading `./`). */
+function normalizePath$1(p) {
+	return p.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/** Dedupe + normalize + sort, the canonical scope form used everywhere. */
+function canonicalize(paths) {
+	return [...new Set(paths.map(normalizePath$1))].sort();
+}
+/**
+* Translate a Python `fnmatch` pattern to an anchored RegExp. Mirrors `fnmatch.translate`: a star →
+* `.*` (crosses `/`, unlike shell glob — so a `star + /strutil.py` glob matches `pkg/strutil.py`),
+* `?` → any one char, `[seq]`/`[!seq]` → char class, everything else escaped. This is the matcher
+* cosmic-ray's `excluded-modules` and mutmut's `do_not_mutate` both use (the latter via
+* `fnmatch.fnmatch` in `Config.should_ignore_for_mutation`).
+*/
+function fnmatchToRegExp(pattern) {
+	let re = "";
+	let i = 0;
+	const n = pattern.length;
+	while (i < n) {
+		const c = pattern[i++];
+		if (c === "*") re += ".*";
+		else if (c === "?") re += ".";
+		else if (c === "[") {
+			let j = i;
+			if (j < n && (pattern[j] === "!" || pattern[j] === "]")) j++;
+			while (j < n && pattern[j] !== "]") j++;
+			if (j >= n) re += "\\[";
+			else {
+				let stuff = pattern.slice(i, j).replace(/\\/g, "\\\\");
+				i = j + 1;
+				if (stuff.startsWith("!")) stuff = `^${stuff.slice(1)}`;
+				else if (stuff.startsWith("^")) stuff = `\\${stuff}`;
+				re += `[${stuff}]`;
+			}
+		} else re += (c ?? "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	}
+	return new RegExp(`^(?:${re})$`, "s");
+}
+/** True if an exclusion entry (exact path or fnmatch glob) matches any of the selected files. */
+function exclusionCollides(entry, selected) {
+	const norm = normalizePath$1(entry);
+	if (selected.includes(norm)) return true;
+	const re = fnmatchToRegExp(norm);
+	return selected.some((f) => re.test(f));
+}
+/**
+* The operator's declared source tree, read from a cosmic-ray base config's `module-path` (a single
+* string or a list). Used as the default `ownedRoots` to confine the diff scope (Fork C): a changed
+* `.py` outside this tree is `unmatched` (report-gap), never silently scoped. Pure.
+*/
+function cosmicModulePathRoots(baseToml) {
+	const cr = parse(baseToml)["cosmic-ray"];
+	if (!cr || typeof cr !== "object") return [];
+	const mp = cr["module-path"];
+	if (typeof mp === "string") return [normalizePath$1(mp)];
+	if (Array.isArray(mp)) return mp.map((x) => normalizePath$1(String(x)));
+	return [];
+}
+/**
+* Synthesize a per-run cosmic-ray config from a base config + the selected files. Overrides
+* `module-path` to the canonical selected FILE LIST and reconciles `excluded-modules`: any entry
+* (exact or fnmatch glob) that matches a selected file is stripped (it would otherwise silently
+* subtract that file — blocker #3); non-colliding entries are preserved. All other keys/tables
+* (`timeout`, `test-command`, `[cosmic-ray.distributor]`, …) are preserved verbatim. Pure.
+*/
+function synthesizeScopedCosmicRayConfig(baseToml, selectedFiles) {
+	const selected = canonicalize(selectedFiles);
+	if (selected.length === 0) throw new ScopeEmitError("cannot synthesize a scoped cosmic-ray config for an empty selection");
+	const data = parse(baseToml);
+	const cr = data["cosmic-ray"];
+	if (cr === void 0 || typeof cr !== "object") throw new ScopeEmitError("base config has no [cosmic-ray] table");
+	const table = cr;
+	table["module-path"] = selected;
+	const strippedExclusions = [];
+	table["excluded-modules"] = (Array.isArray(table["excluded-modules"]) ? table["excluded-modules"].map(String) : []).filter((entry) => {
+		if (exclusionCollides(entry, selected)) {
+			strippedExclusions.push(entry);
+			return false;
+		}
+		return true;
+	});
+	return {
+		toml: stringify(data),
+		modulePath: selected,
+		strippedExclusions
+	};
+}
+/** The `[tool.mutmut]` table of a pyproject (empty when absent / unparseable-as-table). */
+function mutmutTable(basePyproject) {
+	if (!basePyproject.trim()) return {};
+	const tool = parse(basePyproject).tool;
+	if (!tool || typeof tool !== "object") return {};
+	const m = tool.mutmut;
+	return m && typeof m === "object" ? m : {};
+}
+/** The operator's `[tool.mutmut] paths_to_mutate` — the default `ownedRoots` for a scoped mutmut run. */
+function mutmutPathsToMutate(basePyproject) {
+	const v = mutmutTable(basePyproject).paths_to_mutate;
+	return Array.isArray(v) ? v.map((x) => normalizePath$1(String(x))) : [];
+}
+/** The operator's inherited `[tool.mutmut] do_not_mutate` globs (reconciled against the scope). */
+function mutmutDoNotMutate(basePyproject) {
+	const v = mutmutTable(basePyproject).do_not_mutate;
+	return Array.isArray(v) ? v.map(String) : [];
+}
+/**
+* Plan a scoped mutmut run. `paths_to_mutate` = the selected files; `also_copy` = every other source
+* file in `allSourceFiles` (so a test importing an unscoped sibling module still resolves in mutmut's
+* `mutants/` sandbox — verified necessary in slice 0). An inherited `do_not_mutate` glob that matches
+* a selected file is stripped (it would otherwise exclude a file we deliberately scoped). Pure given
+* `allSourceFiles` (the runner derives it by walking the owned roots).
+*/
+function planMutmutScope(selectedFiles, allSourceFiles, inheritedDoNotMutate = []) {
+	const pathsToMutate = canonicalize(selectedFiles);
+	if (pathsToMutate.length === 0) throw new ScopeEmitError("cannot plan a scoped mutmut run for an empty selection");
+	const scope = new Set(pathsToMutate);
+	const alsoCopy = canonicalize(allSourceFiles).filter((f) => !scope.has(f));
+	const strippedDoNotMutate = [];
+	return {
+		pathsToMutate,
+		alsoCopy,
+		doNotMutate: inheritedDoNotMutate.filter((entry) => {
+			if (exclusionCollides(entry, pathsToMutate)) {
+				strippedDoNotMutate.push(entry);
+				return false;
+			}
+			return true;
+		}),
+		strippedDoNotMutate
+	};
+}
+/**
+* Render a `pyproject.toml` for a scoped mutmut run: merge the {@link MutmutScopePlan}'s
+* `paths_to_mutate`/`also_copy` (+ reconciled `do_not_mutate`) into the base pyproject's
+* `[tool.mutmut]` table (Fork F: only slice-0-verified keys), preserving every other section and any
+* other verified `[tool.mutmut]` key the operator set (e.g. `pytest_add_cli_args`). An empty
+* `do_not_mutate` is omitted entirely. Pure.
+*/
+function synthesizeScopedMutmutPyproject(basePyproject, plan) {
+	const data = basePyproject.trim() ? parse(basePyproject) : {};
+	const tool = data.tool && typeof data.tool === "object" ? data.tool : {};
+	const mutmut = tool.mutmut && typeof tool.mutmut === "object" ? tool.mutmut : {};
+	mutmut.paths_to_mutate = plan.pathsToMutate;
+	mutmut.also_copy = plan.alsoCopy;
+	if (plan.doNotMutate.length > 0) mutmut.do_not_mutate = plan.doNotMutate;
+	else delete mutmut.do_not_mutate;
+	tool.mutmut = mutmut;
+	data.tool = tool;
+	return stringify(data);
+}
+//#endregion
+//#region src/cosmic-ray.ts
+/** worker_outcome (other than `normal`) → status. `normal` defers to test_outcome. */
+const WORKER_STATUS = {
+	no_test: "NoCoverage",
+	skipped: "Ignored",
+	exception: "RuntimeError",
+	abnormal: "RuntimeError",
+	timeout: "Timeout"
+};
+/** test_outcome (when worker_outcome === 'normal') → status. */
+const TEST_STATUS = {
+	killed: "Killed",
+	survived: "Survived",
+	incompetent: "RuntimeError"
+};
+function statusOf(result) {
+	if (result === null) return "Pending";
+	const worker = result.worker_outcome;
+	if (worker === "normal") return TEST_STATUS[result.test_outcome ?? ""] ?? "Pending";
+	return worker !== void 0 && WORKER_STATUS[worker] || "Pending";
+}
+function lineColOf(pos) {
+	if (Array.isArray(pos)) return {
+		line: pos[0],
+		column: pos[1]
+	};
+	if (pos && typeof pos.line === "number") return {
+		line: pos.line,
+		column: pos.column
+	};
+}
+/** Parse `cosmic-ray dump <session.sqlite>` JSON-lines into a mutation-testing-elements report. Pure. */
+function parseCosmicRayDump(jsonl) {
+	const files = {};
+	let index = 0;
+	for (const raw of jsonl.split(/\r?\n/)) {
+		const line = raw.trim();
+		if (!line) continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		const [workItem, workResult] = parsed;
+		const mutation = workItem?.mutations?.[0];
+		const path = mutation?.module_path;
+		if (!path) continue;
+		const status = statusOf(workResult ?? null);
+		const loc = lineColOf(mutation.start_pos);
+		const mutant = {
+			id: `${path}:${index}`,
+			mutatorName: mutation.operator_name ?? "unknown",
+			status
+		};
+		if (loc) mutant.location = { start: loc };
+		const entry = files[path] ?? {
+			language: "python",
+			mutants: []
+		};
+		entry.mutants.push(mutant);
+		files[path] = entry;
+		index++;
+	}
+	return { files };
+}
+//#endregion
+//#region src/mutmut.ts
+const MUTMUT_STATUS = {
+	killed: "Killed",
+	survived: "Survived",
+	"no tests": "NoCoverage",
+	timeout: "Timeout",
+	suspicious: "Survived",
+	skipped: "Ignored",
+	segfault: "RuntimeError"
+};
+/** The module portion of a mutmut mutant name (`pkg.mod.x_fn__mutmut_3` → `pkg.mod`). */
+function moduleOf(name) {
+	const m = /^(.*)\.x_.+__mutmut_\d+$/.exec(name);
+	if (m?.[1]) return m[1];
+	const dot = name.lastIndexOf(".");
+	return dot > 0 ? name.slice(0, dot) : name;
+}
+/** Parse `mutmut results --all true` text into a mutation-testing-elements report. Pure. */
+function parseMutmutResults(text) {
+	const files = {};
+	for (const raw of text.split(/\r?\n/)) {
+		const line = raw.trim();
+		if (!line) continue;
+		const idx = line.indexOf(":");
+		if (idx === -1) continue;
+		const name = line.slice(0, idx).trim();
+		if (!name) continue;
+		const status = MUTMUT_STATUS[line.slice(idx + 1).trim().toLowerCase()] ?? "Pending";
+		const file = moduleOf(name);
+		const entry = files[file] ?? { mutants: [] };
+		entry.mutants.push({
+			id: name,
+			mutatorName: name,
+			status
+		});
+		files[file] = entry;
+	}
+	return { files };
+}
+//#endregion
+//#region src/scope.ts
+/** Normalize a path to a comparable repo-relative POSIX form (backslashes → `/`, drop a leading `./`). */
+function normalizePath(p) {
+	return p.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/**
+* Derive the mutation scope from the changed files. A changed file is selected only when it is a
+* `.py` file, lives under one of the operator's `ownedRoots`, AND exists on disk (`exists`,
+* injected — FS by default in the runner, faked in tests, mirroring `selectPytestScope`'s
+* `testExists`). A `.py` file that is out-of-tree or non-existent (deleted/renamed/typo) is
+* `unmatched`, never scoped. Non-`.py` files are irrelevant to mutation and dropped. Pure given
+* `exists`. Whole-project fallback is NOT decided here — it is the caller's (`mutateFiles ===
+* undefined`) or the cosmic-ray emitter's (`no-scope` on the base config) concern.
+*/
+function selectMutationScope(mutateFiles, ownedRoots, exists) {
+	const roots = ownedRoots.map(normalizePath);
+	const underRoot = (p) => roots.some((r) => p === r || p.startsWith(`${r}/`));
+	const files = /* @__PURE__ */ new Set();
+	const unmatched = /* @__PURE__ */ new Set();
+	for (const raw of mutateFiles) {
+		const p = normalizePath(raw);
+		if (!p.endsWith(".py")) continue;
+		if (!underRoot(p) || !exists(p)) {
+			unmatched.add(p);
+			continue;
+		}
+		files.add(p);
+	}
+	return {
+		files: [...files].sort(),
+		unmatched: [...unmatched].sort()
+	};
+}
+/**
+* Post-spawn partial-under-scope guard. Given the files the run was SELECTED to mutate and the
+* tool's {@link MutationSummary} (whose `files[]` carries a per-file record for every file the
+* tool SAW — even one it found no mutants in), determine which selected files were genuinely
+* mutated and which the tool never saw at all. A selected file present in the summary with zero
+* mutants is SEEN-BUT-EMPTY (benign — no mutable code); a selected file ABSENT from the summary
+* was never mutated (the partial-scope sentinel) and goes in `missing`. Paths are normalized on
+* both sides before comparison. Pure.
+*/
+function reconcileScope(selected, summary) {
+	const seen = new Set(summary.files.map((f) => normalizePath(f.path)));
+	const mutated = new Set(summary.files.filter((f) => f.metrics.totalMutants > 0).map((f) => normalizePath(f.path)));
+	const sel = [...new Set(selected.map(normalizePath))].sort();
+	return {
+		mutatedFiles: sel.filter((p) => mutated.has(p)),
+		missing: sel.filter((p) => !seen.has(p))
+	};
+}
+/**
+* Convert a Python source PATH to its dotted module form (`pkg/calc.py` → `pkg.calc`,
+* `pkg/__init__.py` → `pkg`). The package-relative prefix is unknown here, so this is the FULL
+* relative-path dotted form; {@link reconcileMutmutScope} matches it against mutmut's module names
+* by suffix to tolerate src-layout projects.
+*/
+function pyPathToModule(path) {
+	let p = normalizePath(path).replace(/\.py$/, "");
+	if (p.endsWith("/__init__")) p = p.slice(0, -9);
+	return p.replace(/\//g, ".");
+}
+/**
+* The mutmut-specific post-spawn guard. Unlike cosmic-ray, mutmut's {@link MutationSummary} is keyed
+* by DOTTED MODULE (`pkg.calc`), not path, AND it emits NO record for a scoped file that produced
+* zero mutants (slice 0: seen-but-empty is INDISTINGUISHABLE from never-seen — Fork B2). So this is
+* deliberately CONSERVATIVE: a selected file is "mutated" only if some module with ≥1 mutant matches
+* its dotted form (equal, or a suffix either way — tolerating flat AND src layouts); every other
+* selected file is `missing` (⇒ the runner throws inconclusive). Some false-inconclusives, ZERO
+* false-passes (absence-is-never-a-pass). Pure.
+*/
+function reconcileMutmutScope(selectedPaths, summary) {
+	const mutatedModules = summary.files.filter((f) => f.metrics.totalMutants > 0).map((f) => normalizePath(f.path));
+	const matches = (mod, sel) => mod === sel || mod.endsWith(`.${sel}`) || sel.endsWith(`.${mod}`);
+	const sel = [...new Set(selectedPaths.map(normalizePath))].sort();
+	const mutatedFiles = [];
+	const missing = [];
+	for (const path of sel) {
+		const mod = pyPathToModule(path);
+		if (mutatedModules.some((m) => matches(m, mod))) mutatedFiles.push(path);
+		else missing.push(path);
+	}
+	return {
+		mutatedFiles,
+		missing
+	};
+}
+//#endregion
+//#region src/summarize.ts
+const ZERO = {
+	killed: 0,
+	survived: 0,
+	timeout: 0,
+	noCoverage: 0,
+	compileErrors: 0,
+	runtimeErrors: 0,
+	ignored: 0,
+	pending: 0
+};
+function tally(mutants) {
+	const c = { ...ZERO };
+	for (const m of mutants) switch (m.status) {
+		case "Killed":
+			c.killed++;
+			break;
+		case "Survived":
+			c.survived++;
+			break;
+		case "Timeout":
+			c.timeout++;
+			break;
+		case "NoCoverage":
+			c.noCoverage++;
+			break;
+		case "CompileError":
+			c.compileErrors++;
+			break;
+		case "RuntimeError":
+			c.runtimeErrors++;
+			break;
+		case "Ignored":
+			c.ignored++;
+			break;
+		case "Pending":
+			c.pending++;
+			break;
+	}
+	return c;
+}
+function metricsFrom(c) {
+	const detected = c.killed + c.timeout;
+	const undetected = c.survived + c.noCoverage;
+	const covered = detected + c.survived;
+	const valid = detected + undetected;
+	const invalid = c.compileErrors + c.runtimeErrors;
+	return {
+		counts: c,
+		detected,
+		undetected,
+		covered,
+		valid,
+		invalid,
+		totalMutants: valid + invalid + c.ignored + c.pending,
+		mutationScore: valid > 0 ? detected / valid * 100 : null,
+		mutationScoreBasedOnCoveredCode: covered > 0 ? detected / covered * 100 : null
+	};
+}
+function sumCounts(a, b) {
+	return {
+		killed: a.killed + b.killed,
+		survived: a.survived + b.survived,
+		timeout: a.timeout + b.timeout,
+		noCoverage: a.noCoverage + b.noCoverage,
+		compileErrors: a.compileErrors + b.compileErrors,
+		runtimeErrors: a.runtimeErrors + b.runtimeErrors,
+		ignored: a.ignored + b.ignored,
+		pending: a.pending + b.pending
+	};
+}
+/** Summarize a Stryker mutation report into aggregate + per-file metrics and the survivor list. Pure. */
+function summarizeMutation(report) {
+	const files = [];
+	const survivors = [];
+	let total = { ...ZERO };
+	for (const path of Object.keys(report.files).sort()) {
+		const file = report.files[path];
+		if (!file) continue;
+		const counts = tally(file.mutants);
+		total = sumCounts(total, counts);
+		files.push({
+			path,
+			metrics: metricsFrom(counts)
+		});
+		for (const m of file.mutants) if (m.status === "Survived" || m.status === "NoCoverage") survivors.push({
+			file: path,
+			mutatorName: m.mutatorName,
+			status: m.status,
+			line: m.location?.start.line ?? 0
+		});
+	}
+	survivors.sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line);
+	return {
+		metrics: metricsFrom(total),
+		files,
+		survivors
+	};
+}
+//#endregion
+//#region src/run.ts
+/**
+* The gated, diff-scoped mutation run — the live half of `@sackville-mcp/mutate`. It **spawns**
+* Stryker (`stryker run`, an injected subprocess like flake's `vitest` and coverage's
+* `vitest related`), then reads the JSON report Stryker writes and feeds it to the pure
+* {@link summarizeMutation}.
+*
+* Per ADR 0010 (+ its 2026-06-01 spike update):
+* 1. **It runs code** — and a mutation run is *expensive* (the suite re-runs per mutant) —
+*    so it sits behind the house paired deny-by-default operator gate (`allowRun` +
+*    `allowedRoots` allowlist, load-bearing on its own, + a wall-clock cap). All
+*    operator-set; no caller input self-authorizes.
+* 2. **Stryker is NOT a dependency of this package.** A real mutation run is slow and
+*    non-deterministic, so it never runs in `pnpm gate`. The `stryker` invocation is the
+*    injected {@link MutationRunner} (the bin spawns the operator's local Stryker); the
+*    engine owns the gate, argv, report plumbing, and summary, and is unit-tested with a
+*    fake runner.
+* 3. **Diff-scoped.** `mutateFiles` (the changed source files) become Stryker's `--mutate`
+*    glob list, and `--incremental` reuses Stryker's cache — so a change mutates only what
+*    it touched, not the whole tree.
+*/
+/** The zero-mutant summary returned by a pre-spawn noop (folds to no-signal ⇒ inconclusive). */
+function emptyMutationSummary() {
+	return summarizeMutation({ files: {} });
+}
+/** Read a file, or undefined if it is absent (a missing base config is not an error). */
+function readFileIfExists(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
+}
+/** Directories never copied into the mutmut sandbox (heavy / irrelevant / the sticky mutants cache). */
+const SANDBOX_EXCLUDE = /(?:^|\/)(?:node_modules|\.git|\.venv|venv|__pycache__|mutants|\.mutmut-cache|dist|\.tox)(?:\/|$)/;
+/** Recursively list the `.py` files under each owned root, repo-relative (FS default for runMutmut). */
+function defaultListSources(ownedRoots, projectRoot) {
+	const out = [];
+	for (const root of ownedRoots) {
+		const abs = join(projectRoot, root);
+		let entries;
+		try {
+			entries = readdirSync(abs, { recursive: true });
+		} catch {
+			continue;
+		}
+		for (const rel of entries) {
+			const p = rel.replace(/\\/g, "/");
+			if (p.endsWith(".py") && !SANDBOX_EXCLUDE.test(p)) out.push(`${root}/${p}`.replace(/\/+/g, "/"));
+		}
+	}
+	return out;
+}
+/** Copy a project into a fresh sandbox dir, excluding heavy dirs + the sticky `mutants/` cache. */
+function copyProjectInto(from, to) {
+	cpSync(from, to, {
+		recursive: true,
+		filter: (src) => !SANDBOX_EXCLUDE.test(src.slice(from.length).replace(/\\/g, "/"))
+	});
+}
+/** Thrown when the paired operator gate denies a run. */
+var MutateGateError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "MutateGateError";
+		this[Symbol.for("sackville.gate-denial")] = true;
+	}
+};
+/** Stryker's default JSON-report location, relative to the project root. */
+function defaultReportPath(projectRoot) {
+	return join(projectRoot, "reports", "mutation", "mutation.json");
+}
+/** Build the `stryker run` argv: JSON reporter, optional diff scope + incremental cache. */
+function runArgv(input) {
+	const argv = [
+		"run",
+		"--reporters",
+		"json"
+	];
+	if (input.mutateFiles && input.mutateFiles.length > 0) argv.push("--mutate", input.mutateFiles.join(","));
+	if (input.incremental) argv.push("--incremental");
+	return argv;
+}
+/** Spawn a local command as a subprocess, surfacing its exit code (never rejecting on non-zero). */
+function spawnMutationRunner(command) {
+	return (argv, opts) => new Promise((res) => {
+		execFile(command, argv, {
+			cwd: opts.cwd,
+			timeout: opts.timeoutMs,
+			maxBuffer: 64 * 1024 * 1024
+		}, (err, stdout, stderr) => {
+			res({
+				exitCode: err && typeof err.code === "number" ? err.code : err ? 1 : 0,
+				stdout: String(stdout),
+				stderr: String(stderr)
+			});
+		});
+	});
+}
+/** Default live runner: spawn the local `stryker` as a subprocess (used by the bin, not the gate). */
+const defaultStrykerRunner = spawnMutationRunner("stryker");
+/** Default live runner: spawn the local `mutmut` as a subprocess (used by the bin, not the gate). */
+const defaultMutmutRunner = spawnMutationRunner("mutmut");
+/** Default live runner: spawn the local `cosmic-ray` as a subprocess (used by the bin, not the gate). */
+const defaultCosmicRayRunner = spawnMutationRunner("cosmic-ray");
+function assertAllowed(config) {
+	if (!config.allowRun) throw new MutateGateError("mutation runs are not enabled (the operator must set allowRun)");
+	const root = resolve(config.projectRoot);
+	if (!config.allowedRoots.map((r) => resolve(r)).includes(root)) throw new MutateGateError(`project root ${config.projectRoot} is not in the operator allowlist`);
+}
+/**
+* Run mutation testing behind the operator gate and summarize the report. The actual
+* `stryker` invocation is the injected `runner` (default {@link defaultStrykerRunner}); the
+* JSON report is read from `deps.reportPath` (default: Stryker's
+* `<projectRoot>/reports/mutation/mutation.json`).
+*/
+async function runMutation(config, input, deps = {}) {
+	assertAllowed(config);
+	const runner = deps.runner ?? defaultStrykerRunner;
+	const reportPath = deps.reportPath ?? defaultReportPath(config.projectRoot);
+	const { exitCode } = await runner(runArgv(input), {
+		cwd: config.projectRoot,
+		timeoutMs: config.timeoutMs
+	});
+	let report;
+	try {
+		report = JSON.parse(readFileSync(reportPath, "utf8"));
+	} catch {
+		throw new Error(`mutation run did not produce a JSON report at ${reportPath} (exit code ${exitCode}); ensure the project enables the Stryker \`json\` reporter`);
+	}
+	return {
+		ran: true,
+		exitCode,
+		scopedFiles: input.mutateFiles ?? [],
+		tool: "stryker",
+		reportPath,
+		summary: summarizeMutation(report)
+	};
+}
+/**
+* Transport-completeness guard for the Python tools, mirroring the capture/HAR guards: a run that
+* produced NO mutants (an empty/failed session), or a cosmic-ray session with unexecuted/ambiguous
+* (`Pending`) mutants, is INCONCLUSIVE — it must never be reported as a clean pass
+* (absence-is-never-a-pass). Throws so the caller (verify) folds it to inconclusive.
+*/
+function assertComplete(tool, summary) {
+	if (summary.metrics.totalMutants === 0) throw new Error(`${tool} produced no mutants — inconclusive (never a clean pass)`);
+	if (summary.metrics.counts.pending > 0) throw new Error(`${tool} session is incomplete: ${summary.metrics.counts.pending} unexecuted/ambiguous mutant(s) — inconclusive`);
+}
+/**
+* mutmut sibling of {@link runMutation} (ADR 0010 addendum, the lightweight Python option). Spawns
+* `mutmut run` (mutate + test; a non-zero exit just means survivors exist, not an error) then reads
+* `mutmut results --all true` from STDOUT and feeds the pure {@link parseMutmutResults}. No report
+* file. (Diff-scoping is staged — mutmut 3.x scopes via its own config, not a clean CLI file list.)
+*/
+async function runMutmut(config, input, deps = {}) {
+	assertAllowed(config);
+	const runner = deps.runner ?? defaultMutmutRunner;
+	if (input.mutateFiles === void 0) {
+		const opts = {
+			cwd: config.projectRoot,
+			timeoutMs: config.timeoutMs
+		};
+		await runner(["run"], opts);
+		const { exitCode, stdout } = await runner([
+			"results",
+			"--all",
+			"true"
+		], opts);
+		const summary = summarizeMutation(parseMutmutResults(stdout));
+		assertComplete("mutmut", summary);
+		return {
+			ran: true,
+			exitCode,
+			scopedFiles: [],
+			tool: "mutmut",
+			summary
+		};
+	}
+	const pyprojectPath = input.configPath ?? "pyproject.toml";
+	const basePyproject = readFileIfExists(join(config.projectRoot, pyprojectPath)) ?? "";
+	const ownedRoots = input.ownedRoots ?? mutmutPathsToMutate(basePyproject);
+	const exists = deps.exists ?? ((p) => existsSync(join(config.projectRoot, p)));
+	const { files, unmatched } = selectMutationScope(input.mutateFiles, ownedRoots, exists);
+	const unmatchedOut = unmatched.length > 0 ? unmatched : void 0;
+	if (files.length === 0) return {
+		ran: false,
+		exitCode: 0,
+		scopedFiles: [],
+		tool: "mutmut",
+		summary: emptyMutationSummary(),
+		scopeEmpty: true,
+		unmatched: unmatchedOut,
+		requestedFiles: []
+	};
+	const scopedPyproject = synthesizeScopedMutmutPyproject(basePyproject, planMutmutScope(files, (deps.listSourceFiles ?? defaultListSources)(ownedRoots, config.projectRoot), mutmutDoNotMutate(basePyproject)));
+	const sandbox = deps.sandboxDir ?? mkdtempSync(join(tmpdir(), "sackville-mutmut-"));
+	copyProjectInto(config.projectRoot, sandbox);
+	writeFileSync(join(sandbox, "pyproject.toml"), scopedPyproject);
+	const opts = {
+		cwd: sandbox,
+		timeoutMs: config.timeoutMs
+	};
+	await runner(["run"], opts);
+	const { exitCode, stdout } = await runner([
+		"results",
+		"--all",
+		"true"
+	], opts);
+	const summary = summarizeMutation(parseMutmutResults(stdout));
+	assertComplete("mutmut", summary);
+	const { mutatedFiles, missing } = reconcileMutmutScope(files, summary);
+	if (missing.length > 0) throw new Error(`mutmut under-scoped: ${missing.join(", ")} selected but produced no mutants — inconclusive`);
+	return {
+		ran: true,
+		exitCode,
+		scopedFiles: mutatedFiles,
+		tool: "mutmut",
+		summary,
+		requestedFiles: files,
+		unmatched: unmatchedOut
+	};
+}
+/**
+* cosmic-ray sibling of {@link runMutation} (ADR 0010 addendum, the PRIMARY Python tool — its dump
+* carries real file:line:operator, so survivors are actionable). Drives the three-step workflow
+* against an operator-authored config (`input.configPath`, default `cosmic-ray.toml` — it carries
+* the project's test-command + module scope) over a throwaway session DB: `init` → `exec` → `dump`,
+* reading the `dump` JSON-lines from STDOUT and feeding the pure {@link parseCosmicRayDump}. The
+* {@link assertComplete} guard makes an empty or partially-executed session inconclusive, never a
+* clean pass. (Diff-scoping by synthesizing the per-run config from `mutateFiles` is staged.)
+*/
+async function runCosmicRay(config, input, deps = {}) {
+	assertAllowed(config);
+	const runner = deps.runner ?? defaultCosmicRayRunner;
+	const opts = {
+		cwd: config.projectRoot,
+		timeoutMs: config.timeoutMs
+	};
+	const configPath = input.configPath ?? "cosmic-ray.toml";
+	const session = join(deps.sessionDir ?? mkdtempSync(join(tmpdir(), "sackville-mutate-")), "session.sqlite");
+	if (input.mutateFiles === void 0) {
+		await runner([
+			"init",
+			configPath,
+			session
+		], opts);
+		const exec = await runner([
+			"exec",
+			configPath,
+			session
+		], opts);
+		const { stdout } = await runner(["dump", session], opts);
+		const summary = summarizeMutation(parseCosmicRayDump(stdout));
+		assertComplete("cosmic-ray", summary);
+		return {
+			ran: true,
+			exitCode: exec.exitCode,
+			scopedFiles: [],
+			tool: "cosmic-ray",
+			summary
+		};
+	}
+	const baseToml = readFileSync(join(config.projectRoot, configPath), "utf8");
+	const ownedRoots = input.ownedRoots ?? cosmicModulePathRoots(baseToml);
+	const exists = deps.exists ?? ((p) => existsSync(join(config.projectRoot, p)));
+	const { files, unmatched } = selectMutationScope(input.mutateFiles, ownedRoots, exists);
+	const unmatchedOut = unmatched.length > 0 ? unmatched : void 0;
+	if (files.length === 0) return {
+		ran: false,
+		exitCode: 0,
+		scopedFiles: [],
+		tool: "cosmic-ray",
+		summary: emptyMutationSummary(),
+		scopeEmpty: true,
+		unmatched: unmatchedOut,
+		requestedFiles: []
+	};
+	const scoped = synthesizeScopedCosmicRayConfig(baseToml, files);
+	const scopedName = deps.scopedConfigName ?? ".sackville-cosmic.toml";
+	const scopedAbs = join(config.projectRoot, scopedName);
+	writeFileSync(scopedAbs, scoped.toml);
+	try {
+		await runner([
+			"init",
+			scopedName,
+			session
+		], opts);
+		const exec = await runner([
+			"exec",
+			scopedName,
+			session
+		], opts);
+		const { stdout } = await runner(["dump", session], opts);
+		const summary = summarizeMutation(parseCosmicRayDump(stdout));
+		assertComplete("cosmic-ray", summary);
+		const { mutatedFiles, missing } = reconcileScope(files, summary);
+		if (missing.length > 0) throw new Error(`cosmic-ray under-scoped: ${missing.join(", ")} selected but never mutated — inconclusive`);
+		return {
+			ran: true,
+			exitCode: exec.exitCode,
+			scopedFiles: mutatedFiles,
+			tool: "cosmic-ray",
+			summary,
+			requestedFiles: files,
+			unmatched: unmatchedOut
+		};
+	} finally {
+		rmSync(scopedAbs, { force: true });
+	}
+}
+//#endregion
+export { MutateGateError, ScopeEmitError, cosmicModulePathRoots, defaultCosmicRayRunner, defaultMutmutRunner, defaultStrykerRunner, mutmutDoNotMutate, mutmutPathsToMutate, parseCosmicRayDump, parseMutmutResults, planMutmutScope, pyPathToModule, reconcileMutmutScope, reconcileScope, runCosmicRay, runMutation, runMutmut, selectMutationScope, summarizeMutation, synthesizeScopedCosmicRayConfig, synthesizeScopedMutmutPyproject };
+
+//# sourceMappingURL=index.mjs.map