oxmutate 1.1.0 → 1.2.1

package/dist/runtime.js

@@ -1,24 +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

package/dist/scheduler.js

@@ -1,25 +1,13 @@
-/**
- * The server pool and its work-stealing queue.
- *
- * A server is a child process holding one warm Vitest (`child.ts`). Work is a queue of units;
- * an idle server takes the next one. A unit whose mutant runs away is killed with its server,
- * its unfinished part is split and put back at the front of the queue for the other servers,
- * and a spare server, already warm, takes the dead one's place. One unlucky test file can no
- * longer serialize a run behind its runaways (es-toolkit, 2026-10-26: 12 runaways in one static
- * shard set the whole mutation phase at 42.9 s while the other shards finished in 8 s).
- */
 import { fork } from 'node:child_process';
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { beatFile, classifyStall, CPU_WINDOW_MS, cpuShare, readBeat } from './heartbeat.js';
+import { env, stderr } from './runtime.js';
 const childJs = fileURLToPath(new URL('./child.js', import.meta.url));
-/** The tail of a server's stderr kept for an error message. */
 const STDERR_TAIL = 4000;
-/** How often the watchdog reads a running unit's progress line. */
 const WATCHDOG_POLL_MS = 50;
-/** How long a server asked to close gets before it is killed (it gives itself the same). */
 const CLOSE_GRACE_MS = 2000;
-/** The mutant a unit's progress file says is running, if any. */
 function inFlight(progress) {
     try {
         return readFileSync(progress, 'utf8').trim().split(' ')[0] || undefined;
@@ -28,15 +16,20 @@ function inFlight(progress) {
         return undefined;
     }
 }
+const PERCENT = 100;
+const CPU_SAMPLES_KEPT = 8;
 class Server {
     child;
     ready;
     stderr = '';
+    beat;
+    cpu = [];
     onMessage;
     onExit;
     exited = false;
-    constructor(configFile, cwd, execArgv) {
+    constructor(configFile, cwd, execArgv, workDir) {
         this.child = fork(childJs, [configFile], { cwd, stdio: ['ignore', 'ignore', 'pipe', 'ipc'], execArgv });
+        this.beat = beatFile(workDir, this.child.pid);
         this.child.stderr?.on('data', (d) => (this.stderr = (this.stderr + d.toString()).slice(-STDERR_TAIL)));
         this.ready = new Promise((resolve) => {
             const first = (m) => {
@@ -48,7 +41,15 @@ class Server {
             this.child.on('message', first);
             this.child.once('exit', () => resolve(false));
         });
-        this.child.on('message', (m) => this.onMessage?.(m));
+        this.child.on('message', (m) => {
+            if (m.type === 'cpu') {
+                this.cpu.push({ at: m.at ?? 0, us: m.us ?? 0 });
+                if (this.cpu.length > CPU_SAMPLES_KEPT)
+                    this.cpu.shift();
+                return;
+            }
+            this.onMessage?.(m);
+        });
         this.child.once('exit', (code) => {
             this.exited = true;
             this.onExit?.(code);
@@ -78,9 +79,17 @@ class Server {
                 if (!line)
                     return;
                 const [id = '', since = '0'] = line.split(' ');
-                if (Date.now() - Number(since) > budget(id)) {
+                const now = Date.now();
+                if (now - Number(since) > budget(id)) {
+                    const beat = readBeat(this.beat, now);
+                    const share = cpuShare(this.cpu, now);
+                    const stall = classifyStall({ beat, cpuShare: share });
+                    if (env['OXMUTATE_DEBUG_WATCHDOG']) {
+                        const cpu = share === undefined ? '?' : `${String(Math.round(share * PERCENT))}%`;
+                        stderr.write(`oxmutate watchdog: stop ${id} after ${String(now - Number(since))} ms; ${stall}; beat ${Number.isFinite(beat.age) ? `${String(beat.age)} ms ago` : 'never'}${beat.inTest ? ' in a test' : ''}; cpu ${cpu} over ${String(CPU_WINDOW_MS)} ms\n`);
+                    }
                     this.child.kill('SIGKILL');
-                    finish({ killedFor: id, stderr: this.stderr });
+                    finish({ killedFor: id, stall, stderr: this.stderr });
                 }
             }, WATCHDOG_POLL_MS);
             this.onMessage = (m) => {
@@ -104,13 +113,21 @@ class Server {
 export function createPool(config, size, workDir, tag) {
     const configFile = path.join(workDir, `server-${tag}.json`);
     writeFileSync(configFile, JSON.stringify(config));
-    const stats = { spawned: 0, killed: 0, crashed: 0 };
+    const stats = { spawned: 0, killed: 0, idle: 0, crashed: 0 };
     const spawn = () => {
         stats.spawned++;
-        return new Server(configFile, config.root, config.nodeArgs ?? []);
+        return new Server(configFile, config.root, config.nodeArgs ?? [], workDir);
     };
     const servers = Array.from({ length: size }, spawn);
     let spare = spawn();
+    const tally = (outcome) => {
+        if (outcome.killedFor)
+            stats.killed++;
+        if (outcome.stall === 'idle')
+            stats.idle++;
+        if (outcome.crashed)
+            stats.crashed++;
+    };
     const replacement = () => {
         const next = spare ?? spawn();
         spare = spawn();
@@ -126,7 +143,6 @@ export function createPool(config, size, workDir, tag) {
                 for (const w of waiters.splice(0))
                     w();
             };
-            /** The next unit `prepare` keeps, or undefined when the queue is empty. */
             const take = () => {
                 for (let unit = queue.shift(); unit; unit = queue.shift())
                     if (!prepare || prepare(unit))
@@ -152,10 +168,7 @@ export function createPool(config, size, workDir, tag) {
                         await server.ready;
                     }
                     const outcome = await server.run(unit, (id) => budget(unit, id));
-                    if (outcome.killedFor)
-                        stats.killed++;
-                    if (outcome.crashed)
-                        stats.crashed++;
+                    tally(outcome);
                     if (outcome.killedFor || outcome.crashed) {
                         servers[slot] = replacement();
                     }
@@ -174,4 +187,3 @@ export function createPool(config, size, workDir, tag) {
         },
     };
 }
-//# sourceMappingURL=scheduler.js.map

package/dist/spec-oracle.js

@@ -1,35 +1,15 @@
-/**
- * Spec oracles (roadmap M3.5): a formal model's traces, replayed against the code with each mutant
- * armed, as a second and independent verdict beside the tests.
- *
- * The contract is the trace, not the method. A backend's only job is to leave `*.itf.json` files
- * (the Informal Trace Format) in a directory:
- *
- *   - `quint`: `quint run --mbt` simulates the model and writes the traces, with each step's action
- *     and nondeterministic picks, so a replay test knows what to call.
- *   - `itf`: a directory some other tool already filled (Apalache writes ITF too; so can a
- *     property-based generator). This is also how a test pins its traces.
- *
- * The project's replay tests (spec.ts) turn a trace into calls and assertions. Which mutants a
- * replay kills is reported per oracle as the F metrics of metrics.md: spec-kill share (F1), the
- * test-spec gap (F2: the spec kills, the tests miss, with the trace that did it), spec escapes
- * (F3), spec cost per mutant (F4) and mapping coverage (F6).
- */
 import { mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { ambientRuntime, run as spawn } from 'bellpull';
 const DEFAULT_TRACES = 100;
 const DEFAULT_STEPS = 20;
 const DEFAULT_QUINT = 'npx -y @informalsystems/quint@0.33.0';
-/** How much of a failing quint run's output the error keeps. */
 const OUTPUT_TAIL = 1000;
-/** The oracle's traces on disk: generated into `work` for `quint`, the given directory for `itf`. */
 export async function tracesFor(oracle, root, work) {
     if (oracle.backend === 'itf')
         return path.resolve(root, oracle.dir ?? '');
     const dir = path.join(work, `spec-${oracle.name}`);
     mkdirSync(dir, { recursive: true });
-    // Stryker disable next-line StringLiteral: split always returns at least one element, so the default is never taken; it is there for the type
     const [command = '', ...prefix] = (oracle.quint ?? DEFAULT_QUINT).split(/\s+/);
     const n = String(oracle.traces ?? DEFAULT_TRACES);
     const args = [...prefix, 'run', path.resolve(root, oracle.model ?? ''), '--mbt', '--n-traces', n, '--max-samples', n, '--max-steps', String(oracle.maxSteps ?? DEFAULT_STEPS), '--out-itf', path.join(dir, 't{seq}.itf.json')];
@@ -45,7 +25,6 @@ const share = (n, of) => (of ? (PERCENT * n) / of : 0);
 const located = ({ id, file, line, mutatorName, replacement }) => ({ id, file, line, mutatorName, replacement });
 const median = (xs) => {
     const sorted = [...xs].sort((a, b) => a - b);
-    // Stryker disable next-line NumericLiteral: guarded by `sorted.length`, so the fallback never runs
     return sorted.length ? (sorted[Math.floor(sorted.length / 2)] ?? 0) : 0;
 };
 const testsMiss = (m) => m.status === 'Survived' || m.status === 'NoCoverage';
@@ -60,10 +39,8 @@ export function summarizeSpec({ oracle, modelledFiles, traces, mutants, testName
         modelled: here.length,
         mappingCoverage: share(reached.length, here.length),
         specKillShare: share(killed.length, here.length),
-        // Stryker disable next-line OptionalChaining: every mutant in `killed` has spec.status Killed, so spec is defined; `?.` is only for the type
         testSpecGap: killed.filter(testsMiss).map((m) => ({ ...located(m), trace: testName(m.spec?.killedBy?.[0] ?? '') })),
         specEscapes: here.filter((m) => testsMiss(m) && m.spec?.status !== 'Killed').map(located),
         msPerSpecExecution: median(specMs),
     };
 }
-//# sourceMappingURL=spec-oracle.js.map

package/dist/spec.js

@@ -1,31 +1,8 @@
-/**
- * `oxmutate/spec`: what a replay test imports to drive the code under test through a formal
- * model's traces.
- *
- * A spec oracle (spec-oracle.ts) asks a backend for traces of a model: Quint's `quint run --mbt`,
- * or a directory of ITF files any tool wrote (Apalache emits the same format). A replay test,
- * written once per modelled component, takes each trace, performs each step's action on the real
- * code, and asserts the model's state. Under oxmutate those tests run with each mutant armed, on a
- * verdict track of their own: a mutant a replay test catches is `killedBySpec`, whatever the
- * ordinary tests say about it.
- *
- *   import { loadTraces } from 'oxmutate/spec';
- *   const traces = loadTraces('save-restore');
- *   it.skipIf(traces.length === 0).each(traces)('replays $name', (trace) => { … });
- *
- * Outside an oxmutate run there are no traces, so the replay tests skip.
- */
 import { readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { env } from './runtime.js';
-/** JSON map of oracle name → directory of `*.itf.json` traces, set by oxmutate for its servers. */
 export const SPEC_TRACES_ENV = 'OXMUTATE_SPEC_TRACES';
 const META = new Set(['#meta', 'mbt::actionTaken', 'mbt::nondetPicks']);
-/**
- * ITF values as plain JavaScript: `#bigint` as a number (a bigint past 2^53), `#set` and `#tup`
- * as arrays, `#map` as a Map. A `JSON.parse` reviver, so it runs bottom-up with no recursion of
- * its own: children are already decoded when their parent is.
- */
 function revive(_key, v) {
     if (!v || typeof v !== 'object' || Array.isArray(v))
         return v;
@@ -42,7 +19,6 @@ function revive(_key, v) {
         return new Map(o['#map']);
     return v;
 }
-/** One ITF value, decoded as in a trace file. */
 export const decode = (v) => JSON.parse(JSON.stringify(v), revive);
 const pick = (v) => {
     if (!v || typeof v !== 'object' || !('tag' in v))
@@ -50,9 +26,7 @@ const pick = (v) => {
     const variant = v;
     return variant.tag === 'Some' ? variant.value : undefined;
 };
-/** One ITF file as steps. */
 export function readTrace(file) {
-    // Stryker disable next-line StringLiteral: without an encoding readFileSync returns a Buffer, which JSON.parse reads as UTF-8 text all the same
     const itf = JSON.parse(readFileSync(file, 'utf8'), revive);
     const steps = itf.states.map((s) => ({
         action: String(s['mbt::actionTaken'] ?? ''),
@@ -61,7 +35,6 @@ export function readTrace(file) {
     }));
     return { name: path.basename(file), steps };
 }
-/** The traces oxmutate generated for this oracle, in file order; none outside an oxmutate run. */
 export function loadTraces(oracle) {
     const dirs = env[SPEC_TRACES_ENV] ? JSON.parse(env[SPEC_TRACES_ENV]) : {};
     const dir = dirs[oracle];
@@ -72,4 +45,3 @@ export function loadTraces(oracle) {
         .sort((a, b) => a.localeCompare(b, 'en', { numeric: true }))
         .map((f) => readTrace(path.join(dir, f)));
 }
-//# sourceMappingURL=spec.js.map

package/dist/vite-plugin.js

@@ -1,7 +1,3 @@
-/**
- * Serves instrumented sources to Vitest from memory, in place of the files on disk. No sandbox
- * copy: the project is run where it is, and only the mutated files' contents differ.
- */
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 export function instrumentedSources(mapPath) {
@@ -15,4 +11,3 @@ export function instrumentedSources(mapPath) {
         },
     };
 }
-//# sourceMappingURL=vite-plugin.js.map

package/dist/vite.js

@@ -1,3 +1 @@
-/** Types a `mutate` block written apart from `defineConfig` (in a shared file, say); returns it unchanged. */
 export const defineMutate = (config) => config;
-//# sourceMappingURL=vite.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxmutate",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Mutation testing for JavaScript and TypeScript on the oxc engine, run warm inside the project's own Vitest, with CI lanes, SARIF and an agent surface. No dependency outside the burgee family. A Stryker migration path.",
   "license": "MIT",
   "repository": {
@@ -64,7 +64,7 @@
     "!dist/**/*.test.*"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node ../../scripts/declaration-reach.mts --prune",
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/strip-comments.mjs dist && node ../../scripts/declaration-reach.mts --prune",
     "build:native": "cd native && cargo build --release --features napi --lib && node ../scripts/copy-binding.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run && vitest run --config compat/vitest.config.ts",