oxmutate 1.5.0 → 2.0.0

package/README.md

@@ -20,7 +20,7 @@
   <a href="https://www.npmjs.com/package/oxmutate?activeTab=code"><img src="https://img.shields.io/npm/unpacked-size/oxmutate?style=flat-square" alt="Unpacked size of the latest oxmutate release on npm" /></a>
   <a href="https://github.com/ofri-peretz/burgee/blob/main/packages/oxmutate/package.json"><img src="https://img.shields.io/badge/dependencies-2%20in%20family%2C%200%20outside-0a6b47?style=flat-square" alt="Two dependencies, all in the burgee family (bellpull, burgee), none outside it" /></a>
   <a href="https://github.com/ofri-peretz/burgee/blob/main/packages/oxmutate/package.json"><img src="https://img.shields.io/badge/types-included-blue?style=flat-square" alt="TypeScript types included for every entry point" /></a>
-  <a href="https://github.com/ofri-peretz/burgee/blob/main/packages/oxmutate/package.json"><img src="https://img.shields.io/badge/Node.js-20.19%2B%20%7C%2022.13%2B-green?style=flat-square" alt="Node.js 20.19+ or 22.13+" /></a>
+  <a href="https://github.com/ofri-peretz/burgee/blob/main/packages/oxmutate/package.json"><img src="https://img.shields.io/badge/Node.js-22.13%2B-green?style=flat-square" alt="Node.js 22.13+" /></a>
   <a href="https://github.com/ofri-peretz/burgee/blob/main/packages/oxmutate/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" alt="License: MIT" /></a>
   <a href="https://www.npmjs.com/package/oxmutate#provenance"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.npmjs.org%2Foxmutate%2Flatest&query=%24.dist.attestations.provenance~&label=npm&style=flat-square&color=0a6b47" alt="npm provenance of the latest release, read live from its registry attestation" /></a>
 </p>
@@ -335,7 +335,7 @@ The `oxmutate` bin is that API, declared once on burgee.
 
 ## Requirements
 
-Node 20.19 or later on the 20 line, or 22.13 or later. Vitest 4.1 or later in the project, for the
+Node 22.13 or later. Vitest 4.1 or later in the project, for the
 default runner. macOS (arm64, x64), Linux (glibc x64 and arm64, musl x64) or Windows (x64).
 
 ## Where it sits

package/dist/coordinator.d.ts

@@ -45,6 +45,19 @@ export interface RunStats {
     isolatedMs: number;
     wallMs: number;
     testExecutions: number;
+    /** Warm units, send to outcome, summed over servers: what `mutationMs` is in server time. */
+    warmUnitMs: number;
+    /** Of `warmUnitMs`, the time inside armed test runs. The rest is starting workers, collecting files, canaries and hooks. */
+    warmArmedMs: number;
+    /** Isolated runs by what sent the mutant there: the parts of `isolatedRuns`. */
+    isolatedByCause: {
+        static: number;
+        stopped: number;
+        unfinished: number;
+        rerun: number;
+        confirm: number;
+        flaky: number;
+    };
     watchdogKills: number;
     /** Of `watchdogKills`, the stops whose worker was idle, waiting (heartbeat.ts). In an isolated run each is a Timeout as it stands. */
     idleStalls: number;

package/dist/coordinator.js

@@ -73,7 +73,7 @@ export async function run(options) {
     const { root } = options;
     const work = mkdtempSync(path.join(tmpdir(), 'oxmutate-'));
     const stats = {
-        files: 0, mutants: 0, instrumentMs: 0, dryRunMs: 0, mutationMs: 0, staticMs: 0, staticRecollections: 0, isolatedMs: 0, wallMs: 0, testExecutions: 0,
+        files: 0, mutants: 0, instrumentMs: 0, dryRunMs: 0, mutationMs: 0, staticMs: 0, staticRecollections: 0, isolatedMs: 0, wallMs: 0, testExecutions: 0, warmUnitMs: 0, warmArmedMs: 0, isolatedByCause: { static: 0, stopped: 0, unfinished: 0, rerun: 0, confirm: 0, flaky: 0 },
         watchdogKills: 0, idleStalls: 0, deadlocks: 0, crashes: 0, canaryFiles: 0, pollutionRestarts: 0, diskWrites: 0, auditSampled: 0, auditDisagreed: 0, survivorsOverturned: 0, timeoutsOverturned: 0, compileErrors: 0, isolatedRuns: 0, reused: 0, flakyTests: 0, flakyMutants: 0, units: 0, serversSpawned: 0,
     };
     let unitSeq = 0;
@@ -189,6 +189,9 @@ export async function run(options) {
             if (fileErrors.length) {
                 throw new InstrumentFault(`${String(fileErrors.length)} test file(s) failed to load during the dry run, so their tests would be missing from every verdict: ${fileErrors.slice(0, 3).map((e) => `${path.relative(root, e.file)}: ${e.error}`).join('; ')}`);
             }
+            const unhandled = recs.reduce((n, r) => n + (r.unhandled ?? 0), 0);
+            if (unhandled > 0)
+                throw new InstrumentFault(`the suite raised ${String(unhandled)} unhandled error(s) with no mutant active, so no verdict can be trusted. fix: make \`vitest run\` pass with no "Unhandled Errors" first`);
             return { tests: recs.flatMap((r) => r.tests ?? []), perTest, static: stat, runOnce: recs.flatMap((r) => r.runOnce ?? []), modules: Object.assign({}, ...recs.map((r) => r.modules ?? {})) };
         };
         progress.phase('dry run');
@@ -412,6 +415,7 @@ export async function run(options) {
         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 = async (unit, outcome) => {
             inFlight.delete(unit.results);
+            stats.warmUnitMs += outcome.ms ?? 0;
             const wrote = await diskWrittenDuring(unit);
             if (wrote)
                 return wrote;
@@ -484,6 +488,7 @@ export async function run(options) {
             if (r.type === 'mutant' && r.id)
                 (byMutant.get(r.id) ?? byMutant.set(r.id, []).get(r.id))?.push(r);
         stats.testExecutions = records.filter((r) => r.type === 'mutant').length;
+        stats.warmArmedMs = records.reduce((sum, r) => sum + (r.type === 'mutant' ? (r.ms ?? 0) : 0), 0);
         stats.canaryFiles = new Set(records.filter((r) => r.type === 'polluted' && r.file).map((r) => r.file ?? '')).size;
         const isolatedQueue = [];
         for (const m of toRun) {
@@ -496,6 +501,7 @@ export async function run(options) {
                 continue;
             }
             else if (runaways.has(m.id)) {
+                stats.isolatedByCause.stopped++;
                 isolatedQueue.push(m);
             }
             else if (crashedIds.has(m.id)) {
@@ -514,6 +520,7 @@ export async function run(options) {
                 m.testsCompleted = recs.length;
             }
             else {
+                stats.isolatedByCause.unfinished++;
                 isolatedQueue.push(m);
             }
         }
@@ -674,11 +681,13 @@ export async function run(options) {
         const s0 = performance.now();
         const staticBack = env['OXMUTATE_ISOLATE_STATIC'] ? staticMutants : await decideStaticLive(staticMutants);
         stats.staticMs = performance.now() - s0;
+        stats.isolatedByCause.static = staticBack.length;
         isolatedQueue.push(...staticBack);
         progress.phase(`isolated runs (static mutants and stragglers: ${String(isolatedQueue.length)})`);
         const i0 = performance.now();
         const first = await runIsolated(isolatedQueue);
         const stopped = isolatedQueue.filter((m) => first.get(m.id)?.status === 'Timeout' && !first.get(m.id)?.idle);
+        stats.isolatedByCause.rerun += stopped.length;
         const again = await runIsolated(stopped, RERUN_SLACK);
         for (const m of stopped) {
             const v = again.get(m.id);
@@ -698,8 +707,10 @@ export async function run(options) {
             }
         }
         const survivors = toRun.filter((m) => m.status === 'Survived' && new Set(m.coveredBy).size > 1);
+        stats.isolatedByCause.confirm += survivors.length;
         const confirmed = await runIsolated(survivors);
         const stoppedHere = survivors.filter((m) => confirmed.get(m.id)?.status === 'Timeout' && !confirmed.get(m.id)?.idle);
+        stats.isolatedByCause.rerun += stoppedHere.length;
         const recheck = await runIsolated(stoppedHere, RERUN_SLACK);
         for (const m of stoppedHere) {
             const v = recheck.get(m.id);
@@ -732,6 +743,7 @@ export async function run(options) {
         const flakyCandidates = toRun.filter((m) => m.coveredBy.some((t) => flakyTests.has(t)));
         const seen = new Map(flakyCandidates.map((m) => [m.id, new Set([m.status === 'Timeout' ? 'Killed' : m.status])]));
         for (let n = 1; n <= options.flakyReruns && flakyCandidates.length; n++) {
+            stats.isolatedByCause.flaky += flakyCandidates.length;
             const again = await runIsolated(flakyCandidates);
             for (const m of flakyCandidates) {
                 const v = again.get(m.id);

package/dist/reports.d.ts

@@ -6,7 +6,6 @@ export declare function strykerReport(r: RunResult): object;
 /** SARIF 2.1.0: one result per surviving or uncovered mutant, fingerprinted by stable id. */
 export declare function sarifReport(r: RunResult): object;
 export declare function describe(m: MutantResult): string;
-/** The terminal summary: the score, what to look at first, what the run corrected. */
 export declare function textSummary(r: RunResult, opts?: {
     survivors?: number;
 }): string;

package/dist/reports.js

@@ -116,6 +116,16 @@ 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`];
 }
+function whereItWent(s) {
+    const lines = [];
+    if (s.warmUnitMs > 0)
+        lines.push(`  warm servers ran ${(s.warmUnitMs / MS_PER_S).toFixed(1)} s, ${(s.warmArmedMs / MS_PER_S).toFixed(1)} s of it inside test runs`);
+    const c = s.isolatedByCause;
+    const causes = [`static ${String(c.static)}`, `stopped ${String(c.stopped)}`, `unfinished ${String(c.unfinished)}`, `re-run ${String(c.rerun)}`, `survivors confirmed ${String(c.confirm)}`, `flaky ${String(c.flaky)}`];
+    if (s.isolatedRuns > 0)
+        lines.push(`  isolated runs: ${causes.join(' · ')}`);
+    return lines;
+}
 export function textSummary(r, opts = {}) {
     const count = (s) => r.mutants.filter((m) => m.status === s).length;
     const s = r.stats;
@@ -132,6 +142,7 @@ export function textSummary(r, opts = {}) {
     const corrected = corrections(s);
     if (corrected.length)
         lines.push(`  corrected: ${corrected.join(' · ')}`);
+    lines.push(...whereItWent(s));
     lines.push(...frozenLine(r));
     lines.push(...specLines(r));
     const survivors = r.mutants.filter((m) => m.status === 'Survived' || m.status === 'NoCoverage');

package/dist/runner.d.ts

@@ -95,6 +95,6 @@ export default class OxmutateRunner extends OxmutateRunner_base {
     private collectCopies;
     /** Reset per-try state (snapshot counters, assertion counts) the way Vitest does for a retry. */
     private retryReset;
-    onAfterRunFiles(files: AnyTask[]): unknown;
+    onAfterRunFiles(files: AnyTask[]): Promise<unknown>;
 }
 export {};

package/dist/runner.js

@@ -1,4 +1,4 @@
-import { appendFileSync, readFileSync, writeFileSync } from 'node:fs';
+import { closeSync, openSync, readFileSync, writeSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { availableParallelism, loadavg } from 'node:os';
 import path from 'node:path';
@@ -53,6 +53,11 @@ if (mode === 'isolated' && env['OXMUTATE_HIT_LIMIT']) {
     ns.hitLimit = Number(env['OXMUTATE_HIT_LIMIT']);
 }
 const ranAway = () => ns.hitCount !== undefined && ns.hitLimit !== undefined && ns.hitCount > ns.hitLimit;
+let unhandled = 0;
+process.on('unhandledRejection', () => void unhandled++);
+process.on('uncaughtException', () => void unhandled++);
+const realSetImmediate = globalThis.setImmediate;
+const settle = () => new Promise((resolve) => realSetImmediate(resolve));
 const deadlocks = mode === 'dry' ? undefined : watch();
 let deadlocked = false;
 let tornDown = false;
@@ -122,7 +127,7 @@ function takeCopy(test) {
 }
 const dryModules = new Map();
 const PROBE_ID = '__oxmutate_probe__';
-async function probe(test, fn) {
+async function probe(test, fn, reset) {
     const file = test.file?.filepath;
     const scope = test.suite?.id ?? file;
     if (!file || !scope || probed.has(scope) || runOnce.has(file))
@@ -130,6 +135,7 @@ async function probe(test, fn) {
     probed.add(scope);
     await afterEach(test, test.context, []);
     const cleanups = await beforeEach(test, test.context);
+    await reset();
     ns.currentTestId = PROBE_ID;
     try {
         await fn();
@@ -147,9 +153,31 @@ async function probe(test, fn) {
 }
 const POLLUTION_ERROR_CHARS = 300;
 const FILE_ERROR_CHARS = 500;
+let resultsFd;
+let progressFd;
+let markLength = 0;
 function emit(record) {
-    if (resultsPath)
-        appendFileSync(resultsPath, `${JSON.stringify(record)}\n`);
+    if (!resultsPath)
+        return;
+    resultsFd ??= openSync(resultsPath, 'a');
+    writeSync(resultsFd, `${JSON.stringify(record)}\n`);
+}
+function mark(text) {
+    if (!progressPath)
+        return;
+    progressFd ??= openSync(progressPath, 'w');
+    const padded = text.trimEnd().padEnd(markLength);
+    markLength = padded.length;
+    if (padded)
+        writeSync(progressFd, padded, 0);
+}
+function closeFiles() {
+    for (const fd of [resultsFd, progressFd])
+        if (fd !== undefined)
+            closeSync(fd);
+    resultsFd = undefined;
+    progressFd = undefined;
+    markLength = 0;
 }
 function chain(test) {
     const suites = [];
@@ -271,7 +299,7 @@ export default class OxmutateRunner extends Base {
             try {
                 await guarded(test.id, fn);
                 if (mode === 'dry')
-                    await probe(test, fn);
+                    await probe(test, fn, () => this.retryReset(test, 1));
             }
             catch (e) {
                 if (isDeadlock(e))
@@ -359,9 +387,13 @@ export default class OxmutateRunner extends Base {
             ns.hitLimit = plan.hitLimits[id] ?? Number.MAX_SAFE_INTEGER;
             let status = 'Survived';
             let deadlock = false;
+            const before = unhandled;
             try {
                 await setup();
                 await guarded(current.id, run);
+                await settle();
+                if (unhandled > before)
+                    status = 'Killed';
             }
             catch (e) {
                 deadlock = isDeadlock(e);
@@ -377,8 +409,7 @@ export default class OxmutateRunner extends Base {
         for (const id of ids) {
             if (done.has(id))
                 continue;
-            if (progressPath)
-                writeFileSync(progressPath, `${id} ${String(realNow())}\n`);
+            mark(`${id} ${String(realNow())}\n`);
             let { status, ms, deadlock } = await runArmed(id);
             if (status === 'Polluted')
                 break;
@@ -402,14 +433,13 @@ export default class OxmutateRunner extends Base {
                 break;
         }
         if (tornDown) {
-            if (progressPath)
-                writeFileSync(progressPath, '');
+            mark('');
             return;
         }
         if (!polluted)
             await canary();
-        if (progressPath && ids.length)
-            writeFileSync(progressPath, '');
+        if (ids.length)
+            mark('');
         if (attempt > 0)
             await fresh();
         try {
@@ -474,10 +504,14 @@ export default class OxmutateRunner extends Base {
             ns.hitCount = armed ? 0 : undefined;
             ns.hitLimit = armed ? (staticLimits[armed] ?? Number.MAX_SAFE_INTEGER) : undefined;
             deadlocked = false;
+            const before = unhandled;
             try {
                 vi.resetModules();
                 const [file] = await collectTests([filepath], this);
                 const result = file ? await runCollected(file, runnable) : { failed: [filepath], ran: 0 };
+                await settle();
+                if (unhandled > before && result.failed.length === 0)
+                    result.failed.push(filepath);
                 return { ...result, timeout: ranAway() || deadlocked, ...(deadlocked ? { deadlock: true } : {}) };
             }
             finally {
@@ -495,8 +529,7 @@ export default class OxmutateRunner extends Base {
         };
         while (rest.length) {
             const id = rest.shift();
-            if (progressPath)
-                writeFileSync(progressPath, `${id} ${String(realNow())}\n`);
+            mark(`${id} ${String(realNow())}\n`);
             held.push({ id, verdict: await evaluate(id) });
             if (held.at(-1)?.verdict.deadlock)
                 return back('torn down: a deadlocked run is still pending in this worker');
@@ -517,8 +550,7 @@ export default class OxmutateRunner extends Base {
             held = [];
             every = Math.min(STATIC_CANARY_MAX, every * 2);
         }
-        if (progressPath)
-            writeFileSync(progressPath, '');
+        mark('');
         vi.resetModules();
     }
     async onBeforeRunTask(test) {
@@ -562,7 +594,8 @@ export default class OxmutateRunner extends Base {
     async retryReset(test, attempt) {
         await super.onBeforeTryTask?.(test, { retry: attempt, repeats: 0 });
     }
-    onAfterRunFiles(files) {
+    async onAfterRunFiles(files) {
+        await settle();
         if (mode === 'dry') {
             const tests = [];
             const visit = (t, file) => {
@@ -579,7 +612,7 @@ export default class OxmutateRunner extends Base {
                 if (result?.state === 'fail' && !f.tasks?.length)
                     fileErrors.push({ file: filepath, error: (result.errors?.[0]?.message ?? 'failed to collect').slice(0, FILE_ERROR_CHARS) });
             }
-            emit({ type: 'dry', tests, coverage: ns.mutantCoverage, fileErrors, runOnce: [...runOnce], modules: Object.fromEntries(dryModules) });
+            emit({ type: 'dry', tests, coverage: ns.mutantCoverage, fileErrors, runOnce: [...runOnce], modules: Object.fromEntries(dryModules), unhandled });
         }
         else if (mode === 'isolated') {
             const failed = [];
@@ -597,9 +630,13 @@ export default class OxmutateRunner extends Base {
                 if (f.result?.state === 'fail' && !failed.length)
                     failed.push(f.id);
             }
+            const [first] = files;
+            if (unhandled > 0 && !failed.length && first)
+                failed.push(first.id);
             const timeout = ranAway() || deadlocked;
             emit({ type: 'isolated', id: env[ACTIVE_MUTANT_ENV] ?? ns.activeMutant, killed: failed.length > 0 && !timeout, failed, ran, ...(timeout && { timeout }), ...(deadlocked && { deadlock: true }) });
         }
+        closeFiles();
         return super.onAfterRunFiles?.(files);
     }
 }

package/dist/scheduler.js

@@ -1,5 +1,5 @@
 import { fork } from 'node:child_process';
-import { readFileSync, writeFileSync } from 'node:fs';
+import { closeSync, openSync, readFileSync, readSync, 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';
@@ -8,6 +8,7 @@ const childJs = fileURLToPath(new URL('./child.js', import.meta.url));
 const STDERR_TAIL = 4000;
 const WATCHDOG_POLL_MS = 50;
 const CLOSE_GRACE_MS = 2000;
+const PROGRESS_BYTES = 256;
 function inFlight(progress) {
     try {
         return readFileSync(progress, 'utf8').trim().split(' ')[0] || undefined;
@@ -56,7 +57,9 @@ class Server {
         });
     }
     run(unit, budget) {
-        writeFileSync(unit.progress, '');
+        const progress = openSync(unit.progress, 'w+');
+        const mark = Buffer.alloc(PROGRESS_BYTES);
+        const sent = performance.now();
         return new Promise((resolve) => {
             let settled = false;
             const finish = (o) => {
@@ -64,18 +67,13 @@ class Server {
                     return;
                 settled = true;
                 clearInterval(timer);
+                closeSync(progress);
                 this.onMessage = undefined;
                 this.onExit = undefined;
-                resolve(o);
+                resolve({ ...o, ms: performance.now() - sent });
             };
             const timer = setInterval(() => {
-                let line = '';
-                try {
-                    line = readFileSync(unit.progress, 'utf8').trim();
-                }
-                catch {
-                    return;
-                }
+                const line = mark.toString('utf8', 0, readSync(progress, mark, 0, PROGRESS_BYTES, 0)).trim();
                 if (!line)
                     return;
                 const [id = '', since = '0'] = line.split(' ');

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "oxmutate",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "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",
+  "author": "Ofri Peretz <ofriperetzdev@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ofri-peretz/burgee.git",
@@ -14,8 +15,13 @@
   "homepage": "https://oxmutate.interlace.tools",
   "type": "module",
   "private": false,
+  "sideEffects": [
+    "./dist/bin.js",
+    "./dist/child.js",
+    "./dist/runner.js"
+  ],
   "engines": {
-    "node": "^20.19.0 || >=22.13.0"
+    "node": ">=22.13.0"
   },
   "bin": {
     "oxmutate": "./dist/bin.js"
@@ -57,6 +63,24 @@
       ]
     }
   },
+  "keywords": [
+    "mutation-testing",
+    "mutation",
+    "mutation-score",
+    "stryker",
+    "vitest",
+    "oxc",
+    "test-quality",
+    "sarif",
+    "typescript",
+    "javascript",
+    "ci",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "files": [
     "dist",
     "binding/oxmutate.*.node",
@@ -75,8 +99,8 @@
     "compat:mutation": "vitest run --config compat/vitest.config.ts"
   },
   "dependencies": {
-    "bellpull": "^1.0.10",
-    "burgee": "^1.9.2"
+    "bellpull": "^2.0.0",
+    "burgee": "^2.0.0"
   },
   "peerDependencies": {
     "vitest": ">=4.1.0"