oxmutate 1.2.0 → 1.2.2

package/dist/lanes.js

@@ -1,17 +1,7 @@
-/**
- * The CI lanes' selection rules: which mutants a run owns.
- *
- * - `since <ref>` (the PR lane): mutants on lines the change added or modified, from
- *   `git diff -U0 <ref>`, working tree included, so a local run and CI select the same set.
- * - `shard i/n` (a CI matrix): a mutant belongs to shard `fnv(id) mod n`, so a shard's share
- *   does not move when unrelated code changes, and the shards partition the run exactly.
- */
 import { ambientRuntime, run } from 'bellpull';
 const NEW_FILE = '+++ ';
-/** FNV-1a 32-bit parameters. */
 const FNV_OFFSET = 0x811c9dc5;
 const FNV_PRIME = 0x01000193;
-/** Added or changed line ranges per repository-relative path, new side. */
 export async function changedLines(root, base) {
     const diff = await run('git', ['diff', '-U0', '--no-color', '--no-ext-diff', base, '--'], { cwd: root, runtime: ambientRuntime() });
     if (!diff.ok)
@@ -33,23 +23,17 @@ export function parseDiff(diff) {
         const start = Number(hunk[1]);
         const count = hunk[2] === undefined ? 1 : Number(hunk[2]);
         if (count === 0)
-            continue; // a pure deletion adds no line to mutate
-        // Stryker disable next-line OptionalChaining: the get after a set always finds the list; `?.` is only for the type
+            continue;
         (out.get(file) ?? out.set(file, []).get(file))?.push([start, start + count - 1]);
     }
     return out;
 }
 export function touches(ranges, file, startLine, endLine) {
-    // Stryker disable next-line ArrayDeclaration: a string element destructures to letters, and a number compared with a letter is false, as with no ranges
     return (ranges.get(file) ?? []).some(([a, b]) => startLine <= b && endLine >= a);
 }
-/** FNV-1a 32 over the stable id: the shard a mutant belongs to. */
 export function shardOf(id, count) {
     let h = FNV_OFFSET;
-    // Ids are hex (`native/src/stable_id.rs`), so a code point is a code unit and the shards are
-    // the ones `charCodeAt` gave.
     for (let i = 0; i < id.length; i++) {
-        // Stryker disable next-line NumericLiteral: `i < id.length`, so codePointAt never returns undefined here
         h ^= id.codePointAt(i) ?? 0;
         h = Math.imul(h, FNV_PRIME) >>> 0;
     }
@@ -59,30 +43,18 @@ export function parseShard(value) {
     const m = /^(\d+)\/(\d+)$/.exec(value);
     const index = Number(m?.[1]);
     const count = Number(m?.[2]);
-    // `count < 1` needs no check of its own: with 1 <= index <= count it cannot hold.
     if (!m || index < 1 || index > count)
         throw new Error(`--shard must be i/n with 1 <= i <= n, got "${value}"`);
     return { index: index - 1, count };
 }
-/**
- * The range end of Stryker's pattern (`mutate-pattern-constants.js`): `<glob>:<line>[:<col>]-<line>[:<col>]`.
- * Only the suffix is matched; the glob is what comes before it. Stryker's lazy `^(.*?):` glob group
- * backtracks polynomially (CodeQL js/polynomial-redos), and the leftmost match is the same split.
- */
 const RANGE = /:(\d+)(?::(\d+))?-(\d+)(?::(\d+))?$/;
-/** A `mutate` entry split into its glob and, when it names one, its range. */
 export function parseMutateSpec(spec) {
     const m = RANGE.exec(spec);
     if (!m)
         return { glob: spec };
-    // Stryker disable next-line StringLiteral: Number('') is 0 as Number('0') is
     const [, startLine, startColumn = '0', endLine, endColumn = String(Number.MAX_SAFE_INTEGER)] = m;
     return { glob: spec.slice(0, m.index), range: { start: { line: Number(startLine), column: Number(startColumn) }, end: { line: Number(endLine), column: Number(endColumn) } } };
 }
-/**
- * Is the mutant wholly inside the range, as Stryker decides it (`locationIncluded`)? The mutant's
- * columns are the report's, 1-based with the end exclusive; the range's are Stryker's, 0-based.
- */
 export function withinRange(range, start, end) {
     const from = start.column - 1;
     const to = end.column - 1;
@@ -90,4 +62,3 @@ export function withinRange(range, start, end) {
     const endIn = range.end.line > end.line || (range.end.line === end.line && range.end.column >= to);
     return startIn && endIn;
 }
-//# sourceMappingURL=lanes.js.map

package/dist/native.js

@@ -1,16 +1,9 @@
-/**
- * The native core (`native/`, Rust on oxc), loaded for this platform. It ships as one prebuilt
- * `.node` per platform (PRINCIPLES rule 9, `native-engine`): 0.1 bundles all six in the tarball as
- * `binding/oxmutate.<tag>.node` (`platform.ts` names the tag); development builds
- * `binding/oxmutate.<platform>-<arch>.node`; the `oxmutate-<tag>` platform package comes last.
- */
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { bindingNames, platformPackage } from './platform.js';
 const here = path.dirname(fileURLToPath(import.meta.url));
 const target = `${process.platform}-${process.arch}`;
-/** This machine, as `platform.ts` reads it: glibc's runtime version from `process.report` (absent on musl). */
 function machine() {
     const glibc = process.platform === 'linux' ? process.report?.getReport()?.header?.glibcVersionRuntime : undefined;
     return { platform: process.platform, arch: process.arch, glibc };
@@ -20,13 +13,8 @@ export function native() {
     if (binding)
         return binding;
     const self = machine();
-    // `binding/` beside `dist/` (published) or `src/` (development), then one level up.
     const candidates = [path.join(here, '..', 'binding'), path.join(here, '..', '..', 'binding')].flatMap((dir) => bindingNames(self).map((name) => path.join(dir, name)));
     try {
-        // `process.dlopen` loads a native addon straight from its path, the way `require` does it
-        // underneath. Since 0.1 the six release cores ship inside the tarball as
-        // `binding/oxmutate.<tag>.node`; the platform package (its `main`, `oxmutate.node`) is last,
-        // for when those publish.
         const file = candidates.find((c) => existsSync(c)) ?? fileURLToPath(import.meta.resolve(platformPackage(self)));
         const addon = { exports: {} };
         process.dlopen(addon, file);
@@ -37,4 +25,3 @@ export function native() {
     }
     return binding;
 }
-//# sourceMappingURL=native.js.map

package/dist/platform.js

@@ -1,10 +1,3 @@
-/**
- * Which native core a machine needs, as napi-rs names it: `<platform>-<arch>[-gnu|-musl|-msvc]`.
- * The tag names the bundled core (`binding/oxmutate.<tag>.node`), the platform package
- * (`oxmutate-<tag>`, `npm/<tag>`) and the release matrix leg, so all three agree by construction.
- * Pure: the machine is passed in, so every branch is testable on any one machine.
- */
-/** `darwin-arm64`, `linux-x64-gnu`, `linux-x64-musl`, `win32-x64-msvc`, … */
 export function platformTag({ platform, arch, glibc }) {
     if (platform === 'win32')
         return `win32-${arch}-msvc`;
@@ -12,16 +5,9 @@ export function platformTag({ platform, arch, glibc }) {
         return `linux-${arch}-${glibc ? 'gnu' : 'musl'}`;
     return `${platform}-${arch}`;
 }
-/** The npm package that carries the tag's core once the platform packages publish. */
 export function platformPackage(machine) {
     return `oxmutate-${platformTag(machine)}`;
 }
-/**
- * The files to try, in order, under each `binding/` directory: the bundled release core for this
- * tag, then the development build `scripts/copy-binding.mjs` writes (`<platform>-<arch>`, which is
- * the same name on macOS).
- */
 export function bindingNames(machine) {
     return [...new Set([`oxmutate.${platformTag(machine)}.node`, `oxmutate.${machine.platform}-${machine.arch}.node`])];
 }
-//# sourceMappingURL=platform.js.map

package/dist/progress.js

@@ -1,11 +1,4 @@
-/**
- * Stryker's `progress` reporters, one implementation: the phase, its own count and the time so
- * far, on stderr. On a terminal the line rewrites itself every second (`progress`); anywhere else,
- * or with `progress-append-only` (Stryker's `ci` alias), a new line every few seconds, so a CI log
- * shows the run moving without a carriage-return mess. Off unless a progress reporter is named.
- */
 const REPORTERS = new Set(['progress', 'progress-append-only', 'ci', 'dots']);
-// Stryker disable next-line NumericLiteral: a repaint interval; no test can see 1,000 ms against 1,001
 const TTY_EVERY_MS = 1000;
 const APPEND_EVERY_MS = 10_000;
 const MS_PER_S = 1000;
@@ -13,7 +6,6 @@ export function startProgress(reporters, out, now = () => performance.now()) {
     const enabled = reporters.some((r) => REPORTERS.has(r));
     const rewrite = Boolean(out.isTTY) && reporters.includes('progress');
     const start = now();
-    // Stryker disable next-line StringLiteral: line() runs only after phase() has set the name, so the initial value is never printed
     let name = '';
     let detail;
     let timer;
@@ -38,4 +30,3 @@ export function startProgress(reporters, out, now = () => performance.now()) {
         },
     };
 }
-//# sourceMappingURL=progress.js.map

package/dist/reports.js

@@ -1,21 +1,11 @@
-/**
- * The three readers of a run: Stryker's JSON report (dashboards, the HTML elements, burgee's
- * ratchet), SARIF 2.1.0 (code scanning annotates the pull request), and a terminal summary that
- * ends with what to do next.
- */
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-/** The package's own version, read from its manifest so `--version` and the reports never drift from it. */
-// Stryker disable next-line StringLiteral: with no encoding readFileSync returns a Buffer, which JSON.parse reads as the same UTF-8 text
 export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-/** A replacement longer than this is cut, in the SARIF message and in the terminal list. */
 const REPLACEMENT_WIDTH = 60;
 const ELLIPSIS = '...';
 const MS_PER_S = 1000;
-/** Survivors the terminal summary lists before it says how many it left out. */
 const DEFAULT_SURVIVORS_SHOWN = 10;
-/** `mutation-testing-report-schema` 2, the format Stryker writes (`jsonReporter`). */
 export function strykerReport(r) {
     const files = {};
     for (const [file, source] of Object.entries(r.sources)) {
@@ -41,9 +31,7 @@ export function strykerReport(r) {
     }
     const testFiles = new Map();
     for (const t of r.tests) {
-        // Forward slashes on every OS, as Stryker's report keys its files.
         const file = path.relative(r.root, t.file).split(path.sep).join('/');
-        // Stryker disable next-line OptionalChaining: the get after a set always finds the entry; `?.` is only for the type
         (testFiles.get(file) ?? testFiles.set(file, { tests: [] }).get(file))?.tests.push({ id: t.id, name: t.name });
     }
     return {
@@ -56,7 +44,6 @@ export function strykerReport(r) {
         'x-oxmutate': { stats: r.stats, score: r.score, unusedConfig: r.options.unused, frozenOracle: r.frozen, specOracles: r.spec },
     };
 }
-/** SARIF 2.1.0: one result per surviving or uncovered mutant, fingerprinted by stable id. */
 export function sarifReport(r) {
     const reported = r.mutants.filter((m) => m.status === 'Survived' || m.status === 'NoCoverage');
     const rules = [...new Set(reported.map((m) => m.mutatorName))].sort();
@@ -105,7 +92,6 @@ export function describe(m) {
         return `No test reaches this code: changing it to \`${change}\` (${m.mutatorName}) would go unnoticed. fix: add a test that executes ${m.file}:${String(m.start.line)}.`;
     return `${String(m.coveredBy.length)} test(s) run this code, and all still pass when it becomes \`${change}\` (${m.mutatorName}). fix: assert the behaviour this line decides.`;
 }
-/** What the run had to correct, one phrase per kind of correction that happened. */
 function corrections(s) {
     return [
         s.watchdogKills && `${String(s.watchdogKills)} runaway(s) stopped`,
@@ -118,11 +104,9 @@ function corrections(s) {
         s.crashes && `${String(s.crashes)} worker crash(es)`,
     ].filter((c) => Boolean(c));
 }
-/** One line per spec oracle: its F metrics (metrics.md §6). */
 function specLines(r) {
     return (r.spec ?? []).map((o) => `  spec ${o.name} (${o.backend}, ${String(o.traces)} traces): kills ${o.specKillShare.toFixed(1)}% of ${String(o.modelled)} modelled mutants, reaches ${o.mappingCoverage.toFixed(1)}%; ${String(o.testSpecGap.length)} test-spec gap(s), ${String(o.specEscapes.length)} escape(s)`);
 }
-/** The frozen oracle's line, when the change edited tests. */
 function frozenLine(r) {
     const f = r.frozen;
     if (!f?.changedTests.length)
@@ -130,7 +114,6 @@ function frozenLine(r) {
     const sign = f.delta >= 0 ? '+' : '';
     return [`  frozen oracle vs ${f.base}: ${f.headScore.toFixed(2)}% with the change's tests, ${f.baseScore.toFixed(2)}% with the base's (${sign}${f.delta.toFixed(2)}), ${String(f.weakened.length)} mutant(s) the change stopped detecting`];
 }
-/** The terminal summary: the score, what to look at first, what the run corrected. */
 export function textSummary(r, opts = {}) {
     const count = (s) => r.mutants.filter((m) => m.status === s).length;
     const s = r.stats;
@@ -161,29 +144,19 @@ export function textSummary(r, opts = {}) {
         lines.push('', `Config keys not used: ${r.options.unused.map((u) => u.key).join(', ')} (see the JSON report for why)`);
     return `${lines.join('\n')}\n`;
 }
-/** The web component Stryker's HTML report renders with, at the version Stryker 10.0.0 ships. */
 const ELEMENTS = 'mutation-testing-elements/dist/mutation-test-elements.js';
 const ELEMENTS_CDN = 'https://cdn.jsdelivr.net/npm/mutation-testing-elements@3.8.4/dist/mutation-test-elements.js';
-/** sha384 of that file, the same bytes as the npm tarball's (both measured 2026-10-27). */
 const ELEMENTS_SRI = 'sha384-xebNisAYQHHbrYIm991U9KOZ96oO+vRACR8kd+zHzWkU3pcRuigrsI7XS2tj3rqq';
-/**
- * Stryker's HTML report: the JSON report rendered by `mutation-testing-elements`. The component is
- * inlined from the project's own install when it has one (Stryker brings it), so the page works
- * offline as Stryker's does; otherwise the page loads that exact version from a CDN. oxmutate does
- * not depend on it.
- */
 export function htmlReport(r) {
     let script;
     try {
         const elements = createRequire(path.join(r.root, 'package.json')).resolve(ELEMENTS);
-        // Stryker disable next-line StringLiteral: without an encoding readFileSync returns a Buffer, which the template turns into the same UTF-8 text
         const component = readFileSync(elements, 'utf8');
         script = `<script>${component}</script>`;
     }
     catch {
         script = `<script src="${ELEMENTS_CDN}" integrity="${ELEMENTS_SRI}" crossorigin="anonymous"></script>`;
     }
-    // `<` as \u003c: still the same JSON, and no `</script>` inside a source file can end the tag.
     const report = JSON.stringify(strykerReport(r)).replaceAll('<', '\\u003c');
     return `<!DOCTYPE html>
 <html>
@@ -222,4 +195,3 @@ export function writeReports(r) {
         write(r.options.htmlReport, htmlReport(r));
     return written;
 }
-//# sourceMappingURL=reports.js.map

package/dist/resolve.js

@@ -1,8 +1,3 @@
-/**
- * Resolve a bare specifier the way `import` would, from the project under test (not from this
- * package). `createRequire().resolve` follows the `require` condition and lands on Vitest's
- * CommonJS entry, which Vitest refuses to load; this follows `import`, then `default`.
- */
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
@@ -10,7 +5,6 @@ import { pathToFileURL } from 'node:url';
 function pick(entry) {
     if (typeof entry === 'string')
         return entry;
-    // Stryker disable next-line ConditionalExpression: a number or boolean entry has no condition properties, so the loop below returns undefined too
     if (!entry || typeof entry !== 'object')
         return undefined;
     for (const condition of ['import', 'node', 'default']) {
@@ -26,9 +20,6 @@ export function resolveEsm(specifier, fromDir) {
     const subpath = `.${specifier.slice(name.length)}`;
     const req = createRequire(path.join(fromDir, 'package.json'));
     const pkgJson = req.resolve(`${name}/package.json`);
-    // A string `exports` exports no `./package.json`, so the resolve above has already thrown: here
-    // `exports` is a map or absent.
-    // Stryker disable next-line StringLiteral: without an encoding readFileSync returns a Buffer, which JSON.parse reads as UTF-8 text all the same
     const pkg = JSON.parse(readFileSync(pkgJson, 'utf8'));
     const exportsMap = pkg.exports;
     let target;
@@ -40,4 +31,3 @@ export function resolveEsm(specifier, fromDir) {
         throw new Error(`oxmutate: cannot resolve ${specifier} from ${fromDir}`);
     return pathToFileURL(path.join(path.dirname(pkgJson), target)).href;
 }
-//# sourceMappingURL=resolve.js.map

package/dist/runner.js

@@ -1,39 +1,10 @@
-/**
- * oxmutate's Vitest runner: loaded by Vitest (`test.runner`) inside its own worker, so hooks,
- * `expect`, `vi`, `vi.mock` and the environment stay Vitest's.
- *
- * Three modes, set by the coordinator through the environment (`OXMUTATE_MODE`):
- *
- * - `dry`: run the suite unmutated once, recording which tests reach which mutant (the
- *   instrumented code counts hits into the namespace while `currentTestId` is set).
- * - `mutant`: for each test, re-invoke the test's own function once per covering mutant with
- *   the switch flipped, each invocation bracketed by the suite's `beforeEach`/`afterEach` and the
- *   runner's own per-try reset (the mechanism Vitest uses for retries, so snapshot counters
- *   start over). Then run the test once more, unmutated: that run is what Vitest reports, and a
- *   failure there means an earlier mutant polluted shared state (the canary).
- * - `isolated`: one mutant was armed before import (static mutants and canary re-runs). Run
- *   normally; any failed test kills it.
- * - `static`: a batch of static mutants decided in this live worker (staticwarm.qnt). Before the file
- *   runs, each mutant is armed, the module registry is reset and the file is collected again, so
- *   its tests close over modules evaluated under the mutant; they run with their hooks, then an
- *   unarmed re-collection must pass. A file whose own collection touches globals, or a mutant that
- *   leaves a trace, sends the rest of the batch back to the fresh-worker path (`static-fallback`).
- *
- * Before each mutant the runner writes a progress line synchronously, so the coordinator can
- * attribute and kill a worker stuck in a synchronous loop that the hit counter cannot break.
- */
 import { appendFileSync, readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { BEAT_ENV, markTest, startHeartbeat } from './heartbeat.js';
+import { BEAT_ENV, markTest, realNow, startHeartbeat } from './heartbeat.js';
 import { resolveEsm } from './resolve.js';
 import { ACTIVE_MUTANT_ENV, FILE_KEY, NAMESPACE, cwd, env } from './runtime.js';
-/**
- * The project's own Vitest, never the one beside this file: two Vitest instances in one worker
- * disagree about the current test, the snapshot state and `expect`.
- */
 const fromProject = async (specifier, dir = cwd()) => import(resolveEsm(specifier, dir));
-/** The family's refusal shape for a missing optional peer (as `controlroom/ink`'s): a code and a fix. */
 export class PeerMissingError extends Error {
     code = 'E_PEER_MISSING';
     fix = "npm install vitest — oxmutate runs the project's own Vitest, so the project brings it";
@@ -46,7 +17,6 @@ const missing = (cause) => {
     const code = cause?.code;
     return code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND';
 };
-/** Vitest 5 exports `TestRunner` from `vitest`; Vitest 4 from `vitest/runners` + `@vitest/runner`. */
 async function loadBase() {
     const vitest = (await fromProject('vitest').catch((cause) => {
         if (missing(cause))
@@ -66,39 +36,27 @@ const { Base, statics } = await loadBase();
 const mode = env['OXMUTATE_MODE'] ?? 'dry';
 const resultsPath = env['OXMUTATE_RESULTS'];
 const progressPath = env['OXMUTATE_PROGRESS'];
-startHeartbeat(env[BEAT_ENV]); // the watchdog tells a wait from a loop by it (heartbeat.ts)
+startHeartbeat(env[BEAT_ENV]);
 const ns = (globalThis[NAMESPACE] ??= {});
 ns.mutantCoverage ??= { static: {}, perTest: {} };
 const plan = mode === 'mutant' && env['OXMUTATE_PLAN'] ? JSON.parse(readFileSync(env['OXMUTATE_PLAN'], 'utf8')) : { tests: {}, hitLimits: {}, skip: [] };
 const decided = new Set(plan.skip);
-/** The replay tests' own bail: a mutant the tests killed is still replayed, and the reverse. */
 const specTests = new Set(plan.specTests ?? []);
 const decidedBySpec = new Set();
-/** `isolated`: when set, only these tests run (the mutant's covering tests); the rest pass untouched. */
 const only = mode === 'isolated' && env['OXMUTATE_ONLY_TESTS'] ? new Set(JSON.parse(env['OXMUTATE_ONLY_TESTS'])) : undefined;
-/** `static`: the static mutants this file run decides in the live worker. */
 const staticIds = mode === 'static' && env['OXMUTATE_STATIC'] ? JSON.parse(env['OXMUTATE_STATIC']) : [];
-/** `static`: each mutant's hit-count limit. */
 const staticLimits = mode === 'static' && env['OXMUTATE_HIT_LIMITS'] ? JSON.parse(env['OXMUTATE_HIT_LIMITS']) : {};
-// `isolated`: the mutant is armed from process start, so its hit counter is too. A loop it causes
-// stops at the limit, as in warm runs, instead of holding the worker until the watchdog's budget:
-// on oxmutate's own suite 17 runaways left the isolated phase idle 140 of 186 s (2026-10-30).
 if (mode === 'isolated' && env['OXMUTATE_HIT_LIMIT']) {
     ns.hitCount = 0;
     ns.hitLimit = Number(env['OXMUTATE_HIT_LIMIT']);
 }
-/** Did the armed mutant's switch pass its limit, i.e. was this run stopped as a runaway? */
 const ranAway = () => ns.hitCount !== undefined && ns.hitLimit !== undefined && ns.hitCount > ns.hitLimit;
-// ── `static` mode: what a registry reset does not reset ─────────────────────────────────────────
-/** Built-ins a module may patch in place; their own methods are compared by identity. */
 const PROTOTYPES = {
     Object: Object.prototype, Array: Array.prototype, String: String.prototype, Number: Number.prototype,
     Boolean: Boolean.prototype, Function: Function.prototype, Promise: Promise.prototype, Map: Map.prototype,
     Set: Set.prototype, RegExp: RegExp.prototype, Date: Date.prototype, Error: Error.prototype,
 };
-/** Keys Vitest and oxmutate own: they change by design while a file runs. */
 const OWN_GLOBAL = /^(__vitest|__oxmutate__$|__VITEST|__vite)/;
-/** globalThis, process.env and the built-in prototypes, as a map a later look can be compared with. */
 function snapshot() {
     const out = new Map();
     const g = globalThis;
@@ -116,30 +74,20 @@ function snapshot() {
     }
     return out;
 }
-/** How many differing keys a `static-fallback` record names. */
 const DIFF_KEYS = 8;
-/** The keys whose presence or value differs between two snapshots (the first few, for a report). */
 const snapshotDiff = (a, b) => [...new Set([...a.keys(), ...b.keys()])].filter((k) => !(a.has(k) && b.has(k) && Object.is(a.get(k), b.get(k)))).slice(0, DIFF_KEYS);
 const sameSnapshot = (a, b) => snapshotDiff(a, b).length === 0;
-/** The state before this worker evaluated the test file: the baseline every later look compares with. */
 let pristine;
-/** Set when a mutant left state behind; the rest of this context runs no mutants. */
 let polluted = false;
-/** `static` mode: the most mutants decided between two unarmed re-collections (staticwarm.qnt `grouped`). */
 const STATIC_CANARY_MAX = 4;
-/** Mutants between canaries; doubles while the canary stays clean, back to 1 when it fails. */
 let canaryEvery = 1;
 const MAX_CANARY_EVERY = 8;
-/** How much of a test's error a `polluted` record keeps, and of a file's collection error. */
 const POLLUTION_ERROR_CHARS = 300;
 const FILE_ERROR_CHARS = 500;
 function emit(record) {
     if (resultsPath)
         appendFileSync(resultsPath, `${JSON.stringify(record)}\n`);
 }
-// The suites whose hooks wrap `test`, outermost first. Vitest 5 leaves a top-level `describe`'s
-// `suite` unset and keeps file-level hooks on `test.file`, so the walk adds the file itself: without
-// it a file-level `beforeEach` reset never re-ran between mutants and every canary read as pollution.
 function chain(test) {
     const suites = [];
     for (let s = test.suite; s; s = s.suite)
@@ -169,11 +117,6 @@ async function afterEach(test, context, cleanups) {
         await cleanup();
 }
 const isHitLimit = (e) => e instanceof Error && /Hit count limit/.test(e.message);
-/**
- * Runs a file collected outside Vitest's own run (`static` mode): each suite's beforeAll/afterAll,
- * each test with its beforeEach/afterEach chain, stopping at the first failure, which is all a
- * mutant's verdict needs.
- */
 async function runCollected(file, runnable) {
     const failed = [];
     let error;
@@ -219,7 +162,7 @@ async function runCollected(file, runnable) {
         await runSuite(file);
     }
     catch (e) {
-        failed.push(file.id); // a hook threw: the file failed under the mutant, as Stryker scores it
+        failed.push(file.id);
         note(file, e);
     }
     return { failed, ran, ...(error !== undefined && { error }) };
@@ -231,11 +174,6 @@ function fullName(t) {
     return parts.join(' > ');
 }
 export default class OxmutateRunner extends Base {
-    /**
-     * Import-time hits (static mutants) are attributed to the test file being collected, so a static
-     * mutant is later re-run against the files that load its module, not the whole suite (Stryker
-     * re-runs everything for each one).
-     */
     onCollectStart(file) {
         if (mode === 'dry')
             ns.currentTestId = `${FILE_KEY}${file.filepath ?? file.file?.filepath ?? ''}`;
@@ -253,7 +191,6 @@ export default class OxmutateRunner extends Base {
         if (mode !== 'mutant') {
             if (only && !only.has(test.id))
                 return;
-            // Only a wait inside a test body can be an idle stall; collection at low CPU is a slow machine.
             markTest(true);
             try {
                 await fn();
@@ -264,8 +201,6 @@ export default class OxmutateRunner extends Base {
             return;
         }
         const context = test.context;
-        // Once a mutant has polluted this context, no further verdict from it can be trusted: the
-        // rest of the unit is left unrun, and the coordinator re-queues it into a fresh context.
         const spec = specTests.has(test.id);
         const done = spec ? decidedBySpec : decided;
         const ids = polluted ? [] : (plan.tests[test.id] ?? []).filter((id) => !done.has(id));
@@ -283,8 +218,6 @@ export default class OxmutateRunner extends Base {
             await teardown();
             await setup();
         };
-        // Mutants run since the last clean canary. The first of them started from a clean state, so its
-        // verdict stands whatever the next canary says; the rest are suspects if it fails.
         let unchecked = [];
         const canary = async () => {
             if (!unchecked.length)
@@ -303,11 +236,6 @@ export default class OxmutateRunner extends Base {
                 return false;
             }
         };
-        // The mutant is armed through the test's own `beforeEach`, as Stryker arms it: the dry run credits
-        // code a hook runs to the test, so a mutant in a fixture builder or a seed is planned here, and with
-        // the hooks run unarmed it always survived, to be killed later by an isolated run that costs a
-        // fresh process (58 of 400 on a Mongo-backed suite, 2026-10-29). The previous run's `afterEach`
-        // runs first, unarmed: its cleanup belongs to that run.
         const runArmed = async (id) => {
             await teardown();
             const t0 = performance.now();
@@ -333,13 +261,8 @@ export default class OxmutateRunner extends Base {
             if (done.has(id))
                 continue;
             if (progressPath)
-                writeFileSync(progressPath, `${id} ${String(Date.now())}\n`);
+                writeFileSync(progressPath, `${id} ${String(realNow())}\n`);
             let { status, ms } = await runArmed(id);
-            // A kill that follows unchecked runs may be one of their leftovers, which this run's own cleanup
-            // (a `finally`) then wipes, so the batch canary would pass and vouch for a wrong kill. Survivors
-            // are confirmed in isolation later; kills are checked here: a failing canary is pollution as
-            // usual (this verdict goes back with the unit), a passing one leaves the state clean to decide
-            // the mutant again from (.sdlc/intents/oxmutate/canary.qnt).
             if (status !== 'Survived' && unchecked.length > 0) {
                 if (!(await canary()))
                     break;
@@ -349,10 +272,6 @@ export default class OxmutateRunner extends Base {
                 done.add(id);
             emit({ type: 'mutant', id, test: test.id, status, ms, ...(spec ? { spec: true } : {}) });
             unchecked.push(id);
-            // The canary: the same test, unmutated, must still pass. If it fails, a mutant left state
-            // behind (a cache, a registry, a fixture) that would decide the next verdicts. Run after every
-            // mutant at first, then every 2, 4, 8 while it stays clean: pollution is rare per test, and the
-            // canary was half of all executions (burgee/paratext, 2026-10-27).
             if (unchecked.length >= canaryEvery && !(await canary()))
                 break;
         }
@@ -370,11 +289,6 @@ export default class OxmutateRunner extends Base {
                 await cleanup();
         }
     }
-    /**
-     * The baseline is taken as the test file itself is imported (`source: 'collect'`), after setup
-     * files: those run before every collection, re-collections included, and write the same values
-     * each time (the family's colour setup sets TERM, COLORTERM and NO_COLOR), so they are not leaks.
-     */
     importFile(filepath, source) {
         if (mode === 'static' && source === 'collect' && !pristine)
             pristine = snapshot();
@@ -385,18 +299,8 @@ export default class OxmutateRunner extends Base {
             await this.decideStatic(suite);
         return super.onBeforeRunSuite?.(suite);
     }
-    /**
-     * `static` mode (.sdlc/intents/oxmutate/staticwarm.qnt). Re-evaluating the project's modules in
-     * this worker costs ~0.5 ms where a fresh worker per (mutant, file) cost ~80 ms (burgee/paratext,
-     * 2026-10-30). What a registry reset leaves behind is guarded three ways: the file's own unarmed
-     * collection must leave globalThis, process.env and the built-in prototypes as they were; so must
-     * each mutant; and an unarmed re-collection after each mutant must pass. Anything else hands the
-     * rest of the batch back to the fresh-worker path.
-     */
     async decideStatic(suite) {
         const filepath = suite.filepath;
-        // The tests this run will execute, after Vitest's own filters (a name pattern, `.only`, `.skip`):
-        // a re-collected file has the same test ids, and runs exactly these.
         const runnable = new Set();
         const visit = (t) => {
             if (t.type === 'test' && t.mode === 'run')
@@ -416,13 +320,11 @@ export default class OxmutateRunner extends Base {
         if (atCollect.length)
             return fallback('the file changed globals while it was collected', atCollect);
         const vitest = (await fromProject('vitest'));
-        // `collectTests` is exported for Vitest's browser runner from an internal subpath: if a Vitest
-        // moves or drops it, the import fails and the fresh-worker path decides, as on Vitest 4.
         const browser = (await fromProject('vitest/internal/browser').catch(() => ({})));
         const { collectTests } = browser;
         const { vi } = vitest;
         if (!collectTests || !vi)
-            return fallback('this Vitest has no public collect'); // Vitest 4: the fresh path decides
+            return fallback('this Vitest has no public collect');
         const evaluate = async (armed) => {
             ns.activeMutant = armed;
             ns.hitCount = armed ? 0 : undefined;
@@ -439,12 +341,6 @@ export default class OxmutateRunner extends Base {
                 ns.hitLimit = undefined;
             }
         };
-        // Verdicts since the last clean unarmed re-collection are held, not emitted: the re-collection runs
-        // after the first mutant, then after every 2, then every STATIC_CANARY_MAX while it stays clean, and
-        // one that fails sends every held mutant back with the rest. Each mutant's own snapshot diff still
-        // runs at once. The re-collection runs the file's tests unarmed, and after every mutant it was half
-        // of the live static phase, 6,713 s of compat-oracle's 11,193 s weekly run (sc8-profile.md,
-        // staticwarm.qnt `grouped`).
         let held = [];
         let every = 1;
         const back = (reason, keys = []) => {
@@ -455,7 +351,7 @@ export default class OxmutateRunner extends Base {
         while (rest.length) {
             const id = rest.shift();
             if (progressPath)
-                writeFileSync(progressPath, `${id} ${String(Date.now())}\n`);
+                writeFileSync(progressPath, `${id} ${String(realNow())}\n`);
             held.push({ id, verdict: await evaluate(id) });
             const left = snapshotDiff(before, snapshot());
             if (left.length)
@@ -478,7 +374,6 @@ export default class OxmutateRunner extends Base {
             writeFileSync(progressPath, '');
         vi.resetModules();
     }
-    /** Reset per-try state (snapshot counters, assertion counts) the way Vitest does for a retry. */
     async retryReset(test, attempt) {
         await super.onBeforeTryTask?.(test, { retry: attempt, repeats: 0 });
     }
@@ -495,7 +390,6 @@ export default class OxmutateRunner extends Base {
             for (const f of files) {
                 const filepath = (f.file?.filepath ?? f.filepath);
                 visit(f, filepath);
-                // A file that fails to collect has no failing test to show for it: report the file.
                 const result = f.result;
                 if (result?.state === 'fail' && !f.tasks?.length)
                     fileErrors.push({ file: filepath, error: (result.errors?.[0]?.message ?? 'failed to collect').slice(0, FILE_ERROR_CHARS) });
@@ -515,8 +409,6 @@ export default class OxmutateRunner extends Base {
             };
             for (const f of files) {
                 visit(f);
-                // A file that failed with no failing test (it threw at import, or in a hook) failed under
-                // the mutant: a kill, as Stryker scores it. Its id stands in for the test that failed.
                 if (f.result?.state === 'fail' && !failed.length)
                     failed.push(f.id);
             }
@@ -526,4 +418,3 @@ export default class OxmutateRunner extends Base {
         return super.onAfterRunFiles?.(files);
     }
 }
-//# sourceMappingURL=runner.js.map

package/dist/runtime.js

@@ -1,25 +1,9 @@
-/**
- * The contract between instrumented code and the runner. The native core emits calls to
- * `oxmAct(id)` and `oxmCov(...ids)` that read and write this namespace on `globalThis`
- * (`native/src/instrument.rs`, `NAMESPACE`). Changing a field here without changing the emitter
- * breaks every instrumented file.
- */
 export const NAMESPACE = '__oxmutate__';
-/**
- * Coverage key prefix for hits that happen while a test file is being collected (imports): the
- * runner writes `file:<path>` keys, and the coordinator reads them back as static mutants' loaders.
- */
 export const FILE_KEY = 'file:';
-/** Arms one mutant from process start, for static mutants and isolated re-runs. */
 export const ACTIVE_MUTANT_ENV = '__OXMUTATE_ACTIVE_MUTANT__';
-// ── The process seam ────────────────────────────────────────────────────────────────────────────
-// The one file in the package that names the process (burgee's `process-reference-lock.test.ts`):
-// the coordinator, the servers, the runner and the CLI read it here, so a test can see every
-// place the package touches it. `env` is the live object: a write here is a write to the process.
 export const env = process.env;
 export const argv = process.argv;
 export const pid = process.pid;
 export const cwd = () => process.cwd();
 export const stderr = process.stderr;
 export const exit = (code) => process.exit(code);
-//# sourceMappingURL=runtime.js.map