oxmutate 1.2.0 → 1.2.2

package/dist/coordinator.js

@@ -1,14 +1,3 @@
-/**
- * One mutation run, end to end:
- *
- *   instrument (native, parallel) → dry run ×2 (coverage, timings, nondeterministic tests)
- *   → incremental reuse → plan → warm units on a work-stealing server pool, under a watchdog
- *   → isolated re-runs (static mutants, canary-flagged files, unfinished work, flaky verdicts)
- *   → verdicts
- *
- * Every decision that can make a verdict wrong is guarded and counted in `stats`, so a run says
- * what it had to correct, not just what it concluded.
- */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -37,22 +26,12 @@ function readRecords(file) {
         .map((l) => JSON.parse(l));
 }
 const sha = (s) => createHash('sha256').update(s).digest('hex').slice(0, 16);
-/**
- * Work units of at most this many (mutant, test) executions: small enough to steal, large enough
- * that each unit's fresh worker, which imports the test file's whole graph, is paid for few units.
- * At 120, module loading was most of the CPU on burgee/controlroom (React/Ink in every worker); 400
- * cut units 172 -> 93 and wall 44 -> 39 s (paratext 39 -> 35 s), and 1000 gained nothing more
- * (2026-10-30). Smaller stays better for a pollution restart, which re-runs the rest of a unit.
- */
 const UNIT_PAIRS = 400;
-/** How many times its isolated budget a busy stop gets on its re-run. */
 const RERUN_SLACK = 3;
 const MS_PER_MINUTE = 60_000;
 const PERCENT = 100;
-/** Every test that reaches a mutant: the score's, then a spec oracle's replay tests. */
 const allCovering = (m) => [...m.coveredBy, ...(m.specCoveredBy ?? [])];
 const percent = (n, of) => (of ? (PERCENT * n) / of : PERCENT);
-/** Stryker's score: detected over everything valid and not ignored; `covered` leaves out no-coverage. */
 function scoreOf(mutants) {
     const scored = mutants.filter((m) => !['Ignored', 'CompileError', 'RuntimeError'].includes(m.status));
     const detected = scored.filter((m) => m.status === 'Killed' || m.status === 'Timeout').length;
@@ -73,8 +52,6 @@ export async function run(options) {
     const progress = startProgress(options.reporters, stderr);
     try {
         progress.phase('instrumenting');
-        // ── 1. Instrument ─────────────────────────────────────────────────────────────────────────
-        // Stryker's `file:line-line` entries select files by their glob and mutants by their range.
         const specs = options.mutate.map(parseMutateSpec);
         const files = matchFiles(root, specs.map((x) => x.glob));
         const rangesFor = (file) => {
@@ -127,16 +104,13 @@ export async function run(options) {
         stats.files = files.length;
         stats.mutants = mutants.length;
         const mapFile = path.join(work, 'instrumented.json');
-        // The frozen oracle's base-ref test files ride along in the same map (frozen.ts).
         writeFileSync(mapFile, JSON.stringify({ ...codeMap, ...options.testOverrides }));
-        // ── 1b. The build, once, before anything runs (Stryker's `buildCommand`) ─────────────────
         if (options.buildCommand) {
             const [command = '', ...args] = options.buildCommand.trim().split(/\s+/);
             const built = await spawn(command, args, { cwd: root, runtime: ambientRuntime() });
             if (!built.ok)
                 throw new InstrumentFault(`buildCommand \`${options.buildCommand}\` exited ${String(built.code)}: ${(built.stderr || built.stdout).trim().slice(-1500)}. fix: make the build pass on its own first`);
         }
-        // ── 1c. The command runner: any test command, one process per mutant (command-runner.ts) ──
         if (options.commandRunner) {
             const m0 = performance.now();
             try {
@@ -151,8 +125,6 @@ export async function run(options) {
             stats.wallMs = performance.now() - wall0;
             return { root, options, sources, mutants, tests: [], stats, score: scoreOf(mutants) };
         }
-        // ── 2. Dry run, twice (the second only to find nondeterministic tests) ────────────────────
-        // Spec oracles' traces, generated once; servers inherit where they are (spec.ts reads it).
         const traceDirs = {};
         for (const oracle of options.specOracles)
             traceDirs[oracle.name] = await tracesFor(oracle, root, work);
@@ -198,8 +170,6 @@ export async function run(options) {
             throw new InstrumentFault(`${String(failing.length)} test(s) fail with no mutant active, so no verdict can be trusted: ${failing.slice(0, 5).map((t) => t.name).join('; ')}. fix: make the suite pass first`);
         if (dry.tests.length === 0 && !options.allowEmpty)
             throw new InstrumentFault('the dry run ran no tests. fix: check the Vitest config the run used, or set allowEmpty');
-        // The second dry run only finds nondeterministic tests, which matter at step 7: it runs beside
-        // the warm phase instead of before it (6 s of a 107 s burgee/controlroom run, 2026-10-27).
         const findFlakyTests = async () => {
             const flaky = new Set();
             if (options.flakyReruns > 0) {
@@ -216,11 +186,10 @@ export async function run(options) {
             return flaky;
         };
         const flakyCheck = findFlakyTests();
-        flakyCheck.catch(() => undefined); // awaited at step 7; a run that fails first must not also reject unhandled
+        flakyCheck.catch(() => undefined);
         const testInfo = new Map(dry.tests.map((t) => [t.id, t]));
         const coveringTests = new Map();
         const hits = new Map();
-        /** Static mutant → the test files whose collection (imports, beforeAll) reached it. */
         const staticFiles = new Map();
         for (const [testId, perMutant] of Object.entries(dry.perTest)) {
             if (testId.startsWith(FILE_KEY)) {
@@ -239,8 +208,6 @@ export async function run(options) {
             }
         }
         const staticIds = new Set([...Object.keys(dry.static), ...staticFiles.keys()]);
-        // A spec oracle's replay tests, by test id → oracle name. They are not tests of the score:
-        // their kills are reported as the spec's, on a track of their own.
         const specOf = new Map();
         for (const oracle of options.specOracles) {
             const replay = new Set(matchFiles(root, oracle.replay).map((f) => path.join(root, f)));
@@ -277,7 +244,6 @@ export async function run(options) {
             const tests = dry.tests.map(({ id, file, name, ms }) => ({ id, file, name, ms }));
             return { root, options, sources, mutants, tests, stats, score: { detected: 0, undetected: 0, total: 0, mutationScore: 0, covered: 0 }, dryRunOnly: true };
         }
-        // ── 3. Incremental reuse ──────────────────────────────────────────────────────────────────
         const fileHashes = new Map();
         const fileHash = (abs) => {
             let h = fileHashes.get(abs);
@@ -301,21 +267,12 @@ export async function run(options) {
                 stats.reused++;
             }
         }
-        // ── 4. Warm units on the server pool ──────────────────────────────────────────────────────
-        // Static mutants, hybrids included, never run warm: a module evaluated without the mutant
-        // cannot stand in for one evaluated with it. Tried 2026-10-27: warm kills of hybrids gave 3
-        // false kills on burgee/paratext (an import-time registration the tests then read).
         const toRun = mutants.filter((m) => !m.reused && m.status !== 'Ignored' && !m.static && allCovering(m).length > 0);
         const byId = new Map(mutants.map((m) => [m.id, m]));
-        /** The switch-taken count past which a run is a runaway: 100x what the dry run saw, at least 1000. */
         const hitLimitOf = (id) => Math.max(1000, (hits.get(id) ?? 1) * 100);
         const hitLimits = Object.fromEntries(toRun.map((m) => [m.id, hitLimitOf(m.id)]));
         const maxTestMs = (id) => { const m = byId.get(id); return Math.max(0, ...(m ? allCovering(m) : []).map((t) => testInfo.get(t)?.ms ?? 0)); };
-        // The watchdog is for runaways, which loop in fast code; a slow test under a loaded machine is
-        // not one. 3x the covering test's dry-run time, not Stryker's 1.5x: at 1.5x, subprocess-heavy
-        // burgee/paratext tests were stopped as false timeouts (2026-10-27).
         const warmBudget = (id) => options.timeoutMS + Math.max(options.timeoutFactor, 3) * maxTestMs(id) + 250;
-        // Files a mutant's covering tests live in, cheapest first (by the covering tests' time there).
         const fileOrder = new Map();
         for (const m of toRun) {
             const cost = new Map();
@@ -335,7 +292,6 @@ export async function run(options) {
             stats.units++;
             return unit;
         };
-        /** Split a file's plan into units of about UNIT_PAIRS executions, by mutant. */
         const unitsFor = (file, plan) => {
             const ids = [...new Set(Object.values(plan).flat())];
             const pairs = Object.values(plan).reduce((sum, l) => sum + l.length, 0);
@@ -345,7 +301,6 @@ export async function run(options) {
                 return makeUnit(file, Object.fromEntries(Object.entries(plan).map(([t, l]) => [t, l.filter((id) => mine.has(id))]).filter(([, l]) => l.length > 0)));
             });
         };
-        /** Units for these mutants, each planned only in the files `pick` selects for it. */
         const unitsForRound = (mutantsHere, pick) => {
             const perFile = new Map();
             for (const m of mutantsHere) {
@@ -363,22 +318,16 @@ export async function run(options) {
                 }
             }
             const units = [...perFile].flatMap(([file, tests]) => unitsFor(file, Object.fromEntries(tests)));
-            // Sizing and ordering units by dry-run time instead of pair count (longest first) was tried:
-            // 30% more units and ~10% more CPU on burgee/controlroom, and no wall-clock gain that this
-            // machine's load (average 21 to 76 across the A/B) could show (2026-10-27).
             const weight = (u) => Object.values(planUnits.get(u.results)?.plan ?? {}).reduce((sum, l) => sum + l.length, 0);
             return units.sort((a, b) => weight(b) - weight(a));
         };
         const records = [];
         const runaways = new Set();
         const crashedIds = new Set();
-        // Dependencies inlined here too, so the static phase (5b) reuses these servers instead of starting its own.
         const pool = createPool({ root, vitestConfig: options.vitestConfig, workers: 1, instrumentedMap: mapFile, nodeArgs: options.testRunnerNodeArgs, inlineDeps: true }, options.concurrency, work, 'mutant');
         pools.push(pool);
-        /** Mutants decided on one verdict track: the tests', or a spec oracle's replay tests'. */
         const killedSoFar = (spec) => new Set([...runaways, ...crashedIds, ...records.filter((r) => r.type === 'mutant' && r.status !== 'Survived' && Boolean(r.spec) === spec).map((r) => r.id ?? '')]);
         const afterUnit = (unit, outcome) => {
-            // Verdicts a failed canary cannot vouch for are dropped; their pairs are re-queued below.
             const raw = readRecords(unit.results);
             const suspect = new Set(raw.filter((r) => r.type === 'polluted').flatMap((r) => (r.suspects ?? []).map((id) => `${id}|${r.test ?? ''}`)));
             const recs = raw.filter((r) => !(r.type === 'mutant' && suspect.has(`${r.id ?? ''}|${r.test ?? ''}`)));
@@ -393,7 +342,6 @@ export async function run(options) {
                 runaways.add(outcome.killedFor);
             else if (bad)
                 crashedIds.add(bad);
-            // The rest of the unit: pairs not yet run, mutants not yet decided, into a fresh context.
             const ran = new Set(recs.filter((r) => r.type === 'mutant').map((r) => `${r.id ?? ''}|${r.test ?? ''}`));
             const decided = { tests: killedSoFar(false), spec: killedSoFar(true) };
             const { file, plan, depth } = planUnits.get(unit.results);
@@ -406,8 +354,6 @@ export async function run(options) {
             }
             if (Object.keys(rest).length === 0)
                 return [];
-            // A unit that made no progress, or that keeps being polluted, is left to the isolated
-            // re-run rather than retried for ever.
             if (ran.size === 0 || depth >= 40) {
                 for (const id of new Set(Object.values(rest).flat()))
                     unfinished.add(id);
@@ -423,13 +369,6 @@ export async function run(options) {
         const killedCount = () => `${String(killedSoFar(false).size)} of ${String(toRun.length)} mutants killed so far`;
         progress.phase('warm runs', killedCount);
         const m0 = performance.now();
-        // One round, every covering file at once. A two-round plan (cheapest file first, survivors
-        // to the rest) cut executions 23% on burgee/paratext but took 2.9x longer: the second round
-        // waits for the first to drain, and the expensive files then run as a tail (2026-10-27).
-        // Kills are filtered out at dispatch, not when a unit is built: most units wait in the queue while
-        // others run, and a mutant another unit has killed (vouched for by its canary) needs no more of its
-        // covering tests. 1,022 of 6,550 warm executions on burgee/paratext ran after the mutant's kill
-        // (2026-10-30). Verdicts are unchanged: a Killed mutant needs no other pair (dispatch.qnt).
         const beforeUnit = (unit) => {
             const entry = planUnits.get(unit.results);
             if (!entry)
@@ -450,7 +389,6 @@ export async function run(options) {
         };
         await pool.drain(unitsForRound(toRun, (m) => fileOrder.get(m.id) ?? []), (_, id) => warmBudget(id), afterUnit, beforeUnit);
         stats.mutationMs = performance.now() - m0;
-        // ── 5. Verdicts from the warm run ─────────────────────────────────────────────────────────
         const byMutant = new Map();
         for (const r of records)
             if (r.type === 'mutant' && r.id)
@@ -465,10 +403,10 @@ export async function run(options) {
             if (m.specCoveredBy)
                 m.spec = specVerdict(m, all.filter((r) => r.spec));
             if (m.coveredBy.length === 0 && !runaways.has(m.id) && !crashedIds.has(m.id)) {
-                continue; // reached only by a spec oracle: no test covers it, and its status says so
+                continue;
             }
             else if (runaways.has(m.id)) {
-                isolatedQueue.push(m); // a watchdog stop is confirmed before it is reported (6, below)
+                isolatedQueue.push(m);
             }
             else if (crashedIds.has(m.id)) {
                 m.status = 'RuntimeError';
@@ -484,22 +422,15 @@ export async function run(options) {
                 m.testsCompleted = recs.length;
             }
             else {
-                isolatedQueue.push(m); // unfinished: a crash left work undone
+                isolatedQueue.push(m);
             }
         }
         const staticMutants = mutants.filter((m) => m.static && m.status !== 'Ignored' && !m.reused);
-        // ── 6. Isolated re-runs: the switch armed before import, Vitest run normally ──────────────
         const allTestFiles = [...new Set(dry.tests.map((t) => t.file))];
-        // A static mutant needs the files that load it (plus any whose tests reach it); only a hit
-        // with no file to attribute it to (a setup file outside collection) falls back to all files.
         const fileCost = new Map();
         for (const t of dry.tests)
             fileCost.set(t.file, (fileCost.get(t.file) ?? 0) + t.ms);
         const byCost = (files) => [...files].sort((a, b) => (fileCost.get(a) ?? 0) - (fileCost.get(b) ?? 0));
-        // Test file -> source file -> how many of that source's mutants its tests reach. A static mutant
-        // rarely has covering tests of its own, so its loaders were tried cheapest first, and the cheapest
-        // seldom tests the module: on burgee/controlroom each tabs.ts static mutant ran 75 tests in two
-        // files where Stryker needed 37 (2026-10-30). The file that exercises the module goes first.
         const affinity = new Map();
         for (const mm of mutants) {
             for (const t of mm.coveredBy) {
@@ -518,35 +449,20 @@ export async function run(options) {
             const loaders = staticFiles.get(m.id);
             if (!loaders || m.id in dry.static)
                 return byCost(allTestFiles);
-            // Files whose tests reach the mutant first: they kill it. Ordering all loaders by cost alone
-            // ran a file that only imports it first, and 288 of 349 isolated kills on burgee/paratext
-            // came from a later file (2026-10-27).
             const covering = byCost([...new Set(tests)]);
             return [...covering, ...byAffinity(m.file, [...loaders].filter((f) => !covering.includes(f)))];
         };
         const isolatedBudget = (id) => {
             const m = byId.get(id);
             const fs = m ? filesFor(m) : allTestFiles;
-            // A non-static mutant's isolated run executes only its covering tests (`tests` below), so they
-            // are its budget; every test of its files made a hang wait 30-40 s on oxmutate's own suite,
-            // where its covering tests take a fraction of that (2026-10-30). A static mutant runs them all.
             const covering = new Set(m && !m.static ? m.coveredBy : []);
             const ms = dry.tests.filter((t) => fs.includes(t.file) && (covering.size === 0 || covering.has(t.id))).reduce((sum, t) => sum + t.ms, 0);
             return 1500 + options.timeoutMS + options.timeoutFactor * ms * 2;
         };
-        // A non-static mutant runs only its covering tests, armed across all of them in file order:
-        // Stryker's semantics, so cross-test effects still show (a no-op reset() lets state pile up
-        // for the next covering test). A static mutant runs every test of its files, because an
-        // import-time change reaches tests that never execute the mutated line.
-        /**
-         * Static mutants decided in live workers, one unit per (test file, batch of its static mutants),
-         * on a pool that inlines dependencies. Returns the mutants this path could not decide.
-         */
         const decideStaticLive = async (items) => {
             if (items.length === 0)
                 return [];
             const STATIC_BATCH = 25;
-            /** Units of up to STATIC_BATCH mutants per test file, for the files each mutant gets this round. */
             const unitsFor = (filesOf) => {
                 const byFile = new Map();
                 for (const m of items)
@@ -558,9 +474,8 @@ export async function run(options) {
                 })));
             };
             const killed = new Map();
-            /** Decided by the hit-count limit: a runaway, Timeout like a warm one. */
             const timedOut = new Set();
-            const passed = new Map(); // mutant -> files that ran it clean
+            const passed = new Map();
             const back = new Set();
             const ran = new Map();
             const staticPool = pool;
@@ -584,7 +499,6 @@ export async function run(options) {
                     else
                         (passed.get(r.id) ?? passed.set(r.id, new Set()).get(r.id))?.add(file);
                 }
-                // A stop or a crash leaves the rest of the batch undecided: the fresh-worker path decides it.
                 if (outcome.killedFor || outcome.crashed)
                     for (const id of unit.staticIds ?? [])
                         if (!decided.has(id))
@@ -595,13 +509,8 @@ export async function run(options) {
                 unit.staticIds = (unit.staticIds ?? []).filter((id) => !killed.has(id) && !back.has(id));
                 return unit.staticIds.length > 0;
             };
-            // Two rounds: each mutant first in the file most likely to kill it (filesFor puts the files whose
-            // tests reach it first, cheapest first), then its other files only if it survived. In one round
-            // every loading file ran a mutant at once, and a kill in one did not spare the others: 41 tests a
-            // static kill on burgee/controlroom against Stryker's 33.6 (2026-10-30).
             const open = (m) => !killed.has(m.id) && !back.has(m.id);
             const rounds = [(m) => filesFor(m).slice(0, 1), (m) => (open(m) ? filesFor(m).slice(1) : [])];
-            // the mutant's run and the unarmed canary after it
             for (const round of rounds)
                 await staticPool.drain(unitsFor(round), (_, id) => 2 * isolatedBudget(id), afterStatic, keepUndecided);
             const undecided = [];
@@ -626,9 +535,6 @@ export async function run(options) {
             if (items.length === 0)
                 return verdicts;
             const mk = (batch) => ({ mode: 'isolated', files: [], results: fileFor('iso', 'jsonl'), progress: fileFor('iso', 'progress'), batch: batch.map((m) => ({ id: m.id, files: filesFor(m), tests: m.static ? undefined : m.coveredBy, hitLimit: hitLimitOf(m.id) })) });
-            // Packed by estimated cost, heaviest first into the lightest bin, and the heaviest bins run
-            // first. Equal mutant counts left one unit at 8.4 s while the others finished in under 3 s on
-            // burgee/controlroom (2026-10-30): a mutant's cost is its files' dry-run time, not one.
             const cost = (m) => isolatedBudget(m.id);
             const bins = Array.from({ length: Math.min(items.length, options.concurrency * 2) }, () => ({ load: 0, batch: [] }));
             for (const m of [...items].sort((x, y) => cost(y) - cost(x))) {
@@ -639,7 +545,6 @@ export async function run(options) {
             const units = bins.sort((x, y) => y.load - x.load).map((b) => mk(b.batch));
             stats.isolatedRuns += items.length;
             await pool.drain(units, (_, id) => slack * isolatedBudget(id), (unit, outcome) => {
-                // Vitest reports per test file: a mutant is killed if any of its files failed.
                 for (const rec of readRecords(unit.results)) {
                     if (rec.type !== 'isolated' || !rec.id)
                         continue;
@@ -667,11 +572,6 @@ export async function run(options) {
                     verdicts.set(m.id, { status: 'RuntimeError' });
             return verdicts;
         };
-        // ── 5b. Static mutants in live workers (.sdlc/intents/oxmutate/staticwarm.qnt) ─────────────
-        // A fresh worker per (static mutant, file) cost ~80 ms of start-up around tests that take a few
-        // ms: 29 of 35 s on burgee/paratext (2026-10-30). A live worker re-evaluates the project's modules
-        // per mutant instead; whatever it cannot vouch for comes back here for the fresh-worker path.
-        // OXMUTATE_ISOLATE_STATIC=1 sends every static mutant down the fresh-worker path, as before.
         const s0 = performance.now();
         const staticBack = env['OXMUTATE_ISOLATE_STATIC'] ? staticMutants : await decideStaticLive(staticMutants);
         stats.staticMs = performance.now() - s0;
@@ -679,13 +579,6 @@ export async function run(options) {
         progress.phase(`isolated runs (static mutants and stragglers: ${String(isolatedQueue.length)})`);
         const i0 = performance.now();
         const first = await runIsolated(isolatedQueue);
-        // A watchdog stop on a loaded machine is a slow test, not a runaway: 31 of them on one
-        // burgee/paratext run while the load average sat at 40, all Survived for Stryker (2026-10-27).
-        // Each stop gets one more run with 3x the budget; only one that is stopped again is a Timeout.
-        // An idle stop is not re-run: its worker was waiting with its event loop turning and no CPU spent,
-        // on something the mutant never lets happen, which no budget cures; it is a Timeout as Stryker
-        // scores it. Re-run at 3x, 375 of them on caique's 10-31 run "finished" only because Vitest's 30 s
-        // test timeout failed the test (D-20261101-idle-stall-is-timeout, stall.qnt).
         const stopped = isolatedQueue.filter((m) => first.get(m.id)?.status === 'Timeout' && !first.get(m.id)?.idle);
         const again = await runIsolated(stopped, RERUN_SLACK);
         for (const m of stopped) {
@@ -705,20 +598,8 @@ export async function run(options) {
                     m.statusReason = v.idle ? 'its test waited past the budget with the worker idle: a hang, not a slow test' : 'stopped by the watchdog twice, the second time with 3x the budget';
             }
         }
-        // ── 6b. Confirm survivors under whole-file semantics ──────────────────────────────────────
-        // The warm runner arms a mutant for one test at a time, so a mutant whose effect only shows
-        // across tests (a `reset()` in beforeEach made a no-op, so state piles up for the next test)
-        // survives warm and is killed when armed for the whole file, the way Stryker runs it (burgee/
-        // paratext plugin.ts, 2026-10-27). Survivors are what a person acts on, so each one is
-        // re-run once with the mutant armed across its covering files before it is reported.
-        // A survivor with one covering test is not re-run: confirmation runs only covering tests, so there
-        // is no later test for its leftover state to reach, and the warm run already armed that test
-        // through its hooks from clean state (.sdlc/intents/oxmutate/confirm.qnt).
         const survivors = toRun.filter((m) => m.status === 'Survived' && new Set(m.coveredBy).size > 1);
         const confirmed = await runIsolated(survivors);
-        // A timeout here is a watchdog stop like any other, and a loaded machine makes them: two
-        // closeout survivors were reported killed this way while a docs build shared the machine
-        // (2026-10-27). The same rule as section 6: one more run at 3x the budget before believing it.
         const stoppedHere = survivors.filter((m) => confirmed.get(m.id)?.status === 'Timeout' && !confirmed.get(m.id)?.idle);
         const recheck = await runIsolated(stoppedHere, RERUN_SLACK);
         for (const m of stoppedHere) {
@@ -735,10 +616,8 @@ export async function run(options) {
                 stats.survivorsOverturned++;
             }
         }
-        // ── 6c. Survivors that do not type-check are CompileErrors (checker.ts) ────────────────────
         if (options.typeCheck) {
             progress.phase('type-checking survivors');
-            // Every undetected mutant is one somebody would act on: survivors and the uncovered.
             const survived = mutants.filter((m) => m.status === 'Survived' || m.status === 'NoCoverage');
             const refused = await checkSurvivors({ root, tsconfig: options.tsconfigFile, command: options.typeChecker, concurrency: options.concurrency }, survived).catch((error) => {
                 throw new InstrumentFault(error instanceof Error ? error.message : String(error));
@@ -749,7 +628,6 @@ export async function run(options) {
                 stats.compileErrors++;
             }
         }
-        // ── 7. Flaky verdicts: re-run mutants whose covering tests are nondeterministic ───────────
         const flakyTests = await flakyCheck;
         stats.flakyTests = flakyTests.size;
         const flakyCandidates = toRun.filter((m) => m.coveredBy.some((t) => flakyTests.has(t)));
@@ -774,7 +652,6 @@ export async function run(options) {
         stats.watchdogKills = pool.stats.killed;
         stats.idleStalls = pool.stats.idle;
         stats.crashes = pool.stats.crashed;
-        // ── 8. Score, cache, result ───────────────────────────────────────────────────────────────
         if (options.incremental) {
             mkdirSync(path.dirname(options.incrementalFile), { recursive: true });
             const next = { ...cache };
@@ -814,4 +691,3 @@ export async function run(options) {
             rmSync(work, { recursive: true, force: true });
     }
 }
-//# sourceMappingURL=coordinator.js.map

package/dist/directives.js

@@ -1,20 +1,6 @@
-/**
- * Stryker's range directives: a `disable` comment naming mutators (or `all`) and a reason turns them
- * off from the next line on, until a `restore` comment naming them (either spelled with `Stryker` or
- * `oxmutate`). The `next-line` form is config.ts's `disables`. Before this, oxmutate read only the
- * `next-line` form and graded every mutant inside a range as if no directive were there: 116 such
- * mutants in compat-oracle's `hosts.ts` alone (.sdlc/intents/oxmutate/sc8-profile.md).
- *
- * Read by line, as written. Stryker reads a directive only as the leading comment of the next AST
- * node, so a `restore` that closes an object (`// Stryker restore all` above its `}`) is invisible to
- * it, and its `disable` then runs to the end of the file. oxmutate does not reproduce that: the
- * directive means what it says.
- */
 const HEAD = /\/\/\s*(?:Stryker|oxmutate)\s+(disable|restore)\s+(\S.*)/i;
-/** `all`, or a comma list of mutator names. */
 const LIST = /^(?:all|\w+(?:\s*,\s*\w+)*)$/i;
 const covers = (r, mutator) => r.mutators === 'all' || r.mutators.includes(mutator);
-/** The range directives of a file. A `disable` without a reason is an error, as `next-line`'s is. */
 export function rangeDisables(source, file) {
     const rules = [];
     const errors = [];
@@ -22,7 +8,6 @@ export function rangeDisables(source, file) {
         const m = HEAD.exec(text);
         if (!m)
             return;
-        // `next-line` is not a list (the hyphen), so that form is left to config.ts here too.
         const body = m[2];
         const colon = body.indexOf(':');
         const list = (colon === -1 ? body : body.slice(0, colon)).trim();
@@ -41,7 +26,6 @@ export function rangeDisables(source, file) {
         errors,
         reasonFor(line, mutator) {
             const name = mutator.toLowerCase();
-            // The latest directive before the line that names this mutator decides it.
             for (let k = rules.length - 1; k >= 0; k--) {
                 const r = rules[k];
                 if (r.line >= line || !covers(r, name))
@@ -52,4 +36,3 @@ export function rangeDisables(source, file) {
         },
     };
 }
-//# sourceMappingURL=directives.js.map

package/dist/files.js

@@ -1,21 +1,13 @@
-/**
- * The files to mutate, from Stryker-style globs (`src/**\/*.ts`, `!src/**\/*.test.ts`, `{a,b}`).
- * No dependency: a glob is translated to one regular expression, and the walk skips the
- * directories a project never mutates.
- */
 import { readdirSync } from 'node:fs';
 import path from 'node:path';
 const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.turbo', '.oxmutate', '.stryker-tmp', 'reports']);
 const escapeRegExp = (s) => s.replace(/[.+^$()|[\]\\]/g, '\\$&');
-/** Translate one glob (without a leading `!`) into an anchored regular expression. */
 export function globToRegExp(glob) {
     let re = '';
-    // Stryker disable next-line EqualityOperator: one step past the end reads charAt(length), an empty string, which appends nothing
     for (let i = 0; i < glob.length; i++) {
         const c = glob.charAt(i);
         if (c === '*') {
             if (glob[i + 1] === '*') {
-                // `**/` matches zero or more directories; a bare `**` matches anything.
                 if (glob[i + 2] === '/') {
                     re += '(?:.*/)?';
                     i += 2;
@@ -40,7 +32,6 @@ export function globToRegExp(glob) {
     }
     return new RegExp(`^${re}$`);
 }
-/** Repository-relative paths (forward slashes) of files matching the include and exclude globs. */
 export function matchFiles(root, patterns) {
     const include = patterns.filter((p) => !p.startsWith('!')).map(globToRegExp);
     const exclude = patterns.filter((p) => p.startsWith('!')).map((p) => globToRegExp(p.slice(1)));
@@ -59,4 +50,3 @@ export function matchFiles(root, patterns) {
     walk('');
     return out.sort();
 }
-//# sourceMappingURL=files.js.map

package/dist/frozen.js

@@ -1,22 +1,8 @@
-/**
- * The frozen oracle (spec R14): a change that edits tests is also scored against the base ref's
- * tests. The code under test is the same in both runs, so the mutants and their ids are the same;
- * only the test files differ. A mutant the base tests detect and the changed tests do not is a test
- * the change weakened, which is how a patch that "makes the check pass" by editing the check shows
- * up (the reward-hacking concern in the intent, written as a CI result).
- *
- * The base tests are served to Vitest from memory, the way instrumented sources are: nothing in
- * the working tree is touched.
- */
 import path from 'node:path';
 import { ambientRuntime, run as spawn } from 'bellpull';
 import { run } from './coordinator.js';
 const detected = (m) => m?.status === 'Killed' || m?.status === 'Timeout';
 const undetected = (m) => m?.status === 'Survived' || m?.status === 'NoCoverage';
-/**
- * A test file the change added has no base version. It is served as one skipped test, so the base
- * run has the file (Vitest finds it on disk) and none of its tests.
- */
 const ABSENT_AT_BASE = "import { it } from 'vitest';\nit.skip('absent at the base ref (oxmutate frozen oracle)', () => {});\n";
 async function git(root, args) {
     const r = await spawn('git', args, { cwd: root, runtime: ambientRuntime() });
@@ -44,4 +30,3 @@ export async function frozenOracle(head, base) {
         .map((m) => ({ id: m.id, file: m.file, line: m.start.line, mutatorName: m.mutatorName, replacement: m.replacement }));
     return result;
 }
-//# sourceMappingURL=frozen.js.map

package/dist/heartbeat.js

@@ -1,65 +1,25 @@
-/**
- * The watchdog's evidence for the difference between a mutant that loops and one that hangs
- * (.sdlc/intents/oxmutate/stall.qnt, D-20261101-idle-stall-is-timeout).
- *
- * Two readings, both taken when a run passes its budget:
- *
- * - **The beat.** The test worker writes the time to its server's beat file every HEARTBEAT_MS
- *   from a real interval timer. The beat keeps coming only while the worker's event loop turns. A
- *   synchronous loop stops it, and so does a microtask loop.
- * - **The CPU.** The server reports its process's CPU time (every thread, the worker included)
- *   every CPU_SAMPLE_MS. Over the last CPU_WINDOW_MS, a loop burns about a core.
- *
- * A run whose worker is inside a test body, with a fresh beat and under IDLE_CPU of a core, is
- * **idle**: the test waits on something the mutant never lets happen (a prompt awaiting a
- * keypress). Anything else is **busy**, including a worker still collecting its file: on a loaded
- * machine a short budget can run out while modules load, at low CPU, and that is a slow machine. On a caique
- * subset 18 of 19 stops read 0–2% CPU with a live beat, and the one loop read 72%
- * (sc8-profile.md). An idle stop is a Timeout as it stands, the way Stryker scores it. A busy stop
- * may be a slow test on a loaded machine, so it keeps its re-run at 3x.
- *
- * The beat file is the server's, named by its pid and set in its environment when it starts, so
- * every worker it ever runs inherits it: a path set per unit could reach a worker that started
- * under an earlier unit, and on caique two stops read a beat that never came.
- */
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-/** How often the worker writes its beat. */
 export const HEARTBEAT_MS = 250;
-/** A beat older than this means the worker's event loop is not turning: a loop, not a wait. */
 export const STALE_MS = 1000;
-/** How often a server reports its CPU time. */
 export const CPU_SAMPLE_MS = 250;
-/** The window a stop's CPU share is measured over. */
 export const CPU_WINDOW_MS = 1000;
-/** The shortest span of samples a CPU share is read from; less, and the stop counts as busy. */
 export const MIN_CPU_SPAN_MS = 500;
-/** Under this share of one core, with a fresh beat, a stopped run is idle. Measured: idle 0–2%, a loop 72–108%. */
 export const IDLE_CPU = 0.25;
-/** The environment variable that hands a server's beat file to its test workers. */
 export const BEAT_ENV = 'OXMUTATE_BEAT';
-/** A server's beat file, in the run's work directory. */
 export const beatFile = (workDir, pid) => path.join(workDir, `beat-${String(pid)}`);
-// Captured when this module is evaluated, before any test file can install fake timers: a faked
-// clock would write a frozen time, and the watchdog would read a live worker as a stale one.
 const { setInterval: realSetInterval, clearInterval: realClearInterval } = globalThis;
-const realNow = Date.now.bind(Date);
-/** The beat this thread runs: one at a time, whatever re-evaluates this module. */
-// Stryker disable next-line StringLiteral: any key names one registry symbol on every evaluation of this module, which is all the key is for
+export const realNow = Date.now.bind(Date);
 const BEAT_KEY = Symbol.for('oxmutate.heartbeat');
-/** Whether a test body is running in this worker (the runner marks it); the beat carries it. */
 let inTest = false;
-/** Mark a test body as running, or done. Only a wait inside a test body can be an idle stall. */
 export function markTest(running) {
     inTest = running;
 }
-/** Start this worker's beat into `file`. Does nothing when no beat file is set. */
 export function startHeartbeat(file) {
     if (!file)
         return;
     const holder = globalThis;
     realClearInterval(holder[BEAT_KEY]);
-    /** One beat; false once the run's directory is gone: the run is over, and nothing reads the beat. */
     const beat = () => {
         try {
             writeFileSync(file, inTest ? `${String(realNow())} test` : String(realNow()));
@@ -74,10 +34,8 @@ export function startHeartbeat(file) {
         if (!beat())
             realClearInterval(holder[BEAT_KEY]);
     }, HEARTBEAT_MS);
-    // Stryker disable next-line CallExpression: unref only lets a process exit while its beat runs; Vitest ends its workers regardless, so no verdict depends on it
     holder[BEAT_KEY].unref();
 }
-/** The last beat of this server's workers. */
 export function readBeat(file, now = Date.now()) {
     let text;
     try {
@@ -91,21 +49,14 @@ export function readBeat(file, now = Date.now()) {
     return { age: Number.isFinite(at) && at > 0 ? now - at : Number.POSITIVE_INFINITY, inTest: where === 'test' };
 }
 const US_PER_MS = 1000;
-/**
- * The share of one core a server used over the last CPU_WINDOW_MS before `now`, from its samples
- * (oldest first). Undefined when the samples span less than MIN_CPU_SPAN_MS of that window.
- */
 export function cpuShare(samples, now) {
     const recent = samples.filter((s) => s.at >= now - CPU_WINDOW_MS && s.at <= now);
     const first = recent[0];
     const last = recent.at(-1);
-    // Stryker disable next-line LogicalOperator: the first and the last sample are both there or both missing, so `&&` reads the same
     if (!first || !last || last.at - first.at < MIN_CPU_SPAN_MS)
         return undefined;
     return (last.us - first.us) / US_PER_MS / (last.at - first.at);
 }
-/** A stopped run is idle when its worker waits inside a test body, its event loop turning, and its server burns almost no CPU. */
 export function classifyStall(o) {
     return o.beat.inTest && o.beat.age < STALE_MS && (o.cpuShare ?? IDLE_CPU) < IDLE_CPU ? 'idle' : 'busy';
 }
-//# sourceMappingURL=heartbeat.js.map

package/dist/index.js

@@ -1,9 +1,5 @@
-/**
- * oxmutate's programmatic API. The CLI (`oxmutate run`) is this, declared on burgee.
- */
 export { loadOptions } from './config.js';
 export { InstrumentFault, run } from './coordinator.js';
 export { changedLines, parseShard, shardOf } from './lanes.js';
 export { native } from './native.js';
 export { sarifReport, strykerReport, textSummary, VERSION } from './reports.js';
-//# sourceMappingURL=index.js.map