oxmutate 2.5.0 → 2.6.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { defineCommand, defineProgram, ExitCode } from 'burgee';
-import { loadOptions } from './config.js';
+import { DEFAULT_IDLE_TIMEOUT_MS, loadOptions } from './config.js';
 import { InstrumentFault, run } from './coordinator.js';
 import { frozenOracle } from './frozen.js';
 import { parseShard } from './lanes.js';
@@ -56,8 +56,15 @@ function staticOverridesFrom(o) {
         overrides.staticReaders = 'on';
     return overrides;
 }
+function workerOverridesFrom(o) {
+    const warm = o['coldWorkers'] !== true;
+    const idle = typeof o['workerIdleTimeout'] === 'number' && o['workerIdleTimeout'] >= 0 ? Math.floor(o['workerIdleTimeout']) : undefined;
+    if (warm && idle === undefined)
+        return {};
+    return { workers: { warm, idleTimeoutMs: idle ?? DEFAULT_IDLE_TIMEOUT_MS } };
+}
 function overridesFrom(o, root) {
-    const overrides = { ...staticOverridesFrom(o) };
+    const overrides = { ...staticOverridesFrom(o), ...workerOverridesFrom(o) };
     if (typeof o['since'] === 'string')
         overrides.since = o['since'];
     if (typeof o['frozenOracle'] === 'string')
@@ -104,6 +111,8 @@ const runCommand = defineCommand({
         ignoreStatic: { type: 'boolean', description: 'skip static mutants (module-level code): faster, and the score leaves them out' },
         staticGroup: { type: 'number', description: 'arm this many static mutants together in a file that is not their first (default 1; a heuristic, audited)' },
         staticBudget: { type: 'number', description: 'the most the static phase may take, ms; static mutants still undecided then are left out of the score' },
+        coldWorkers: { type: 'boolean', description: 'a fresh Vitest server per unit, closed after it: slower, the least memory held' },
+        workerIdleTimeout: { type: 'number', description: 'close a server idle this long, ms (default 30000; 0 keeps them all until the run ends)' },
         staticReaders: { type: 'boolean', description: 'run each static mutant only in the test files that read its value (a heuristic, audited)' },
         reportStaticReaders: { type: 'boolean', description: 'one more dry run that reports how many tests static mutants would need if each ran only where its value is read; changes no verdict' },
         incremental: { type: 'boolean', description: 'reuse verdicts whose source and covering tests did not change' },

package/dist/config.d.ts

@@ -6,6 +6,8 @@ export interface Thresholds {
     /** Fail the run (exit 1) below this score. `null`: never fail on score. */
     break: number | null;
 }
+/** By default a server idle this long is closed: past a phase's tail, short of a phase's gaps. */
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 30000;
 /** Why a static mutant is Ignored when `static.budgetMs` ran out before it was decided; the summary counts them by it. */
 export declare const STATIC_BUDGET_REASON = "static mutant (static budget spent)";
 /** Why a static mutant is Ignored under `ignoreStatic`; the summary counts them by it. */
@@ -15,6 +17,16 @@ export interface Options {
     mutate: string[];
     vitestConfig?: string | undefined;
     concurrency: number;
+    /**
+     * How long Vitest servers live. `resources.warmWorkers: true` (default) keeps each one's Vitest
+     * between units; `false` starts one per unit and closes it after: slower, the least memory held.
+     * `resources.workerIdleTimeout` (ms, default 30,000): a server with no unit for this long is
+     * closed, and a new one starts if work comes later; 0 keeps every server until the run ends.
+     */
+    workers: {
+        warm: boolean;
+        idleTimeoutMs: number;
+    };
     timeoutMS: number;
     timeoutFactor: number;
     thresholds: Thresholds;

package/dist/config.js

@@ -3,6 +3,12 @@ import { availableParallelism } from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { resolveEsm } from './resolve.js';
+export const DEFAULT_IDLE_TIMEOUT_MS = 30_000;
+function workersOf(resources) {
+    const r = (typeof resources === 'object' && resources !== null ? resources : {});
+    const ms = Math.floor(Number(r.workerIdleTimeout ?? DEFAULT_IDLE_TIMEOUT_MS));
+    return { warm: r.warmWorkers !== false, idleTimeoutMs: ms >= 0 ? ms : DEFAULT_IDLE_TIMEOUT_MS };
+}
 function staticGroupOf(group) {
     const asked = Math.floor(Number(group));
     return asked >= 2 ? asked : 1;
@@ -46,7 +52,7 @@ const DEFAULT_TIMEOUT_FACTOR = 1.5;
 const DEFAULT_THRESHOLD_HIGH = 80;
 const DEFAULT_THRESHOLD_LOW = 60;
 const DEFAULT_DRY_RUN_MINUTES = 5;
-const USED = new Set(['mutate', 'vitest', 'concurrency', 'timeoutMS', 'timeoutFactor', 'thresholds', 'ignoreStatic', 'static', 'reporters', 'jsonReporter', 'htmlReporter', 'incremental', 'incrementalFile', '$schema', 'mutator', 'dryRunOnly', 'dryRunTimeoutMinutes', 'buildCommand', 'testRunnerNodeArgs', 'allowEmpty', 'warnings', 'testRunner', 'commandRunner', 'checkers', 'tsconfigFile']);
+const USED = new Set(['mutate', 'vitest', 'concurrency', 'resources', 'timeoutMS', 'timeoutFactor', 'thresholds', 'ignoreStatic', 'static', 'reporters', 'jsonReporter', 'htmlReporter', 'incremental', 'incrementalFile', '$schema', 'mutator', 'dryRunOnly', 'dryRunTimeoutMinutes', 'buildCommand', 'testRunnerNodeArgs', 'allowEmpty', 'warnings', 'testRunner', 'commandRunner', 'checkers', 'tsconfigFile']);
 async function loadFile(file) {
     if (file.endsWith('.json')) {
         return JSON.parse(readFileSync(file, 'utf8'));
@@ -107,6 +113,7 @@ export async function loadOptions(root, overrides = {}, configFile) {
         mutate,
         vitestConfig: vitest.configFile ? path.resolve(root, vitest.configFile) : undefined,
         concurrency: Number(raw['concurrency'] ?? Math.max(1, Math.min(MAX_DEFAULT_CONCURRENCY, availableParallelism() - 1))),
+        workers: workersOf(raw['resources']),
         timeoutMS: Number(raw['timeoutMS'] ?? DEFAULT_TIMEOUT_MS),
         timeoutFactor: Number(raw['timeoutFactor'] ?? DEFAULT_TIMEOUT_FACTOR),
         thresholds: { high: thresholds.high ?? DEFAULT_THRESHOLD_HIGH, low: thresholds.low ?? DEFAULT_THRESHOLD_LOW, break: thresholds.break ?? null },

package/dist/coordinator.d.ts

@@ -104,6 +104,8 @@ export interface RunStats {
     flakyMutants: number;
     units: number;
     serversSpawned: number;
+    /** Servers closed for sitting idle past `resources.workerIdleTimeout`: memory given back before the run ended. */
+    serversReleased: number;
     /** Mutants whose Timeout their worker called itself, the wait able to end by nothing (quiescence.ts): no watchdog wait, no respawn. */
     deadlocks: number;
 }

package/dist/coordinator.js

@@ -98,7 +98,7 @@ export async function run(options) {
     const work = mkdtempSync(path.join(tmpdir(), 'oxmutate-'));
     const stats = {
         files: 0, mutants: 0, instrumentMs: 0, dryRunMs: 0, mutationMs: 0, staticMs: 0, staticRecollections: 0, staticGroupRuns: 0, staticGroupSplits: 0, staticAuditSampled: 0, staticAuditDisagreed: 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, diskWritePaths: [], auditSampled: 0, auditDisagreed: 0, survivorsOverturned: 0, timeoutsOverturned: 0, compileErrors: 0, isolatedRuns: 0, reused: 0, flakyTests: 0, flakyMutants: 0, units: 0, serversSpawned: 0,
+        watchdogKills: 0, idleStalls: 0, deadlocks: 0, crashes: 0, canaryFiles: 0, pollutionRestarts: 0, diskWrites: 0, diskWritePaths: [], auditSampled: 0, auditDisagreed: 0, survivorsOverturned: 0, timeoutsOverturned: 0, compileErrors: 0, isolatedRuns: 0, reused: 0, flakyTests: 0, flakyMutants: 0, units: 0, serversSpawned: 0, serversReleased: 0,
     };
     let unitSeq = 0;
     const fileFor = (kind, ext) => path.join(work, `${kind}-${String(unitSeq++)}.${ext}`);
@@ -188,7 +188,7 @@ export async function run(options) {
             traceDirs[oracle.name] = await tracesFor(oracle, root, work);
         if (options.specOracles.length)
             env[SPEC_TRACES_ENV] = JSON.stringify(traceDirs);
-        const dryPool = createPool({ root, vitestConfig: options.vitestConfig, workers: options.concurrency, instrumentedMap: mapFile, nodeArgs: options.testRunnerNodeArgs }, 1, work, 'dry');
+        const dryPool = createPool({ root, vitestConfig: options.vitestConfig, workers: options.concurrency, instrumentedMap: mapFile, nodeArgs: options.testRunnerNodeArgs }, 1, { workDir: work, tag: 'dry', lifecycle: options.workers });
         pools.push(dryPool);
         const dryRun = async (trackReads = false) => {
             const unit = { mode: 'dry', files: [], results: fileFor('dry', 'jsonl'), progress: fileFor('dry', 'progress'), ...(trackReads && { trackReads: true }) };
@@ -449,7 +449,7 @@ export async function run(options) {
         };
         const runaways = new Set();
         const crashedIds = new Set();
-        const pool = createPool({ root, vitestConfig: options.vitestConfig, workers: 1, instrumentedMap: mapFile, nodeArgs: options.testRunnerNodeArgs, inlineDeps: true }, options.concurrency, work, 'mutant');
+        const pool = createPool({ root, vitestConfig: options.vitestConfig, workers: 1, instrumentedMap: mapFile, nodeArgs: options.testRunnerNodeArgs, inlineDeps: true }, options.concurrency, { workDir: work, tag: 'mutant', lifecycle: options.workers });
         pools.push(pool);
         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) => {
@@ -904,6 +904,7 @@ export async function run(options) {
             return summarizeSpec({ oracle, modelledFiles: new Set(matchFiles(root, oracle.files)), traces, mutants: located, testName: (t) => testInfo.get(t)?.name ?? t, specMs: ms });
         });
         stats.serversSpawned = pools.reduce((s, p) => s + p.stats.spawned, 0);
+        stats.serversReleased = pools.reduce((s, p) => s + p.stats.released, 0);
         stats.wallMs = performance.now() - wall0;
         return {
             root,

package/dist/quiescence.js

@@ -126,7 +126,7 @@ export function takeFloor() {
 export function confirmStep(o) {
     if (!o.quiet)
         return { quietSince: undefined };
-    const since = o.quietSince ?? o.now - o.span;
+    const since = o.quietSince ?? Math.max(o.now - o.span, o.start ?? -Infinity);
     const open = o.now - since;
     return open >= o.confirmMs ? { quietSince: since, deadlockMs: open } : { quietSince: since };
 }
@@ -156,7 +156,7 @@ export function watch() {
         };
         if (env['OXMUTATE_DEBUG_QUIET'])
             stderr.write(`quiet? ${JSON.stringify(reading)} res=${JSON.stringify([...resources()])} floor=${JSON.stringify([...floor])}\n`);
-        const next = confirmStep({ quietSince, quiet: quiet(reading), now, span, confirmMs: armed.confirmMs });
+        const next = confirmStep({ quietSince, quiet: quiet(reading), now, span, confirmMs: armed.confirmMs, start: armed.start });
         quietSince = next.quietSince;
         if (next.deadlockMs !== undefined) {
             const { reject } = armed;
@@ -172,7 +172,7 @@ export function watch() {
                 return pending;
             const deadlock = new Promise((_, reject) => {
                 quietSince = undefined;
-                armed = { reject, confirmMs: Math.max(MIN_CONFIRM_MS, confirmMs) };
+                armed = { reject, confirmMs: Math.max(MIN_CONFIRM_MS, confirmMs), start: realNow() };
             });
             try {
                 return await Promise.race([pending, deadlock]);

package/dist/reports.js

@@ -140,6 +140,8 @@ function whereItWent(r) {
     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`);
     lines.push(...staticLine(r));
+    if (s.serversReleased > 0)
+        lines.push(`  servers: ${String(s.serversSpawned)} started, ${String(s.serversReleased)} closed for sitting idle (resources.workerIdleTimeout)`);
     const sr = s.staticReaders;
     if (sr && sr.mutants > 0) {
         const ratio = sr.readerTests > 0 ? `, ${(sr.loaderTests / sr.readerTests).toFixed(1)}x fewer` : '';

package/dist/scheduler.js

@@ -107,16 +107,40 @@ class Server {
         setTimeout(() => this.child.kill('SIGKILL'), CLOSE_GRACE_MS).unref();
     }
 }
-export function createPool(config, size, workDir, tag) {
+const IDLE_CHECK_MS = 1000;
+export function createPool(config, size, place) {
+    const { workDir, tag } = place;
+    const lifecycle = place.lifecycle ?? { warm: true, idleTimeoutMs: 0 };
     const configFile = path.join(workDir, `server-${tag}.json`);
     writeFileSync(configFile, JSON.stringify(config));
-    const stats = { spawned: 0, killed: 0, idle: 0, crashed: 0 };
+    const stats = { spawned: 0, killed: 0, idle: 0, crashed: 0, released: 0 };
     const spawn = () => {
         stats.spawned++;
         return new Server(configFile, config.root, config.nodeArgs ?? [], workDir);
     };
-    const servers = Array.from({ length: size }, spawn);
-    let spare = spawn();
+    const servers = Array.from({ length: size }, () => (lifecycle.warm ? spawn() : undefined));
+    let spare = lifecycle.warm ? spawn() : undefined;
+    const idleSince = servers.map(() => performance.now());
+    let spareSince = performance.now();
+    const sweep = lifecycle.idleTimeoutMs > 0
+        ? setInterval(() => {
+            const now = performance.now();
+            for (const [slot, server] of servers.entries()) {
+                const since = idleSince[slot];
+                if (server && since !== undefined && now - since >= lifecycle.idleTimeoutMs) {
+                    server.close();
+                    servers.fill(undefined, slot, slot + 1);
+                    stats.released++;
+                }
+            }
+            if (spare && now - spareSince >= lifecycle.idleTimeoutMs) {
+                spare.close();
+                spare = undefined;
+                stats.released++;
+            }
+        }, IDLE_CHECK_MS)
+        : undefined;
+    sweep?.unref();
     const tally = (outcome) => {
         if (outcome.killedFor)
             stats.killed++;
@@ -127,9 +151,31 @@ export function createPool(config, size, workDir, tag) {
     };
     const replacement = () => {
         const next = spare ?? spawn();
-        spare = spawn();
+        spare = lifecycle.warm ? spawn() : undefined;
+        spareSince = performance.now();
         return next;
     };
+    const serverFor = async (slot) => {
+        idleSince.fill(undefined, slot, slot + 1);
+        let server = servers[slot] ?? spawn();
+        if (!(await server.ready)) {
+            server = replacement();
+            await server.ready;
+        }
+        servers.fill(server, slot, slot + 1);
+        return server;
+    };
+    const settle = (slot, server, outcome) => {
+        const lost = Boolean(outcome.killedFor ?? outcome.crashed);
+        if (!lifecycle.warm) {
+            if (!lost)
+                server.close();
+            servers.fill(undefined, slot, slot + 1);
+        }
+        else if (lost)
+            servers.fill(replacement(), slot, slot + 1);
+        idleSince.fill(performance.now(), slot, slot + 1);
+    };
     return {
         stats,
         async drain(units, budget, after, prepare) {
@@ -158,17 +204,10 @@ export function createPool(config, size, workDir, tag) {
                         continue;
                     }
                     busy++;
-                    let server = servers[slot];
-                    if (!(await server.ready)) {
-                        server = replacement();
-                        servers[slot] = server;
-                        await server.ready;
-                    }
+                    const server = await serverFor(slot);
                     const outcome = await server.run(unit, (id) => budget(unit, id));
                     tally(outcome);
-                    if (outcome.killedFor || outcome.crashed) {
-                        servers[slot] = replacement();
-                    }
+                    settle(slot, server, outcome);
                     const more = await after(unit, outcome);
                     queue.unshift(...more);
                     busy--;
@@ -177,8 +216,10 @@ export function createPool(config, size, workDir, tag) {
             }));
         },
         close() {
+            if (sweep)
+                clearInterval(sweep);
             for (const s of servers)
-                s.close();
+                s?.close();
             spare?.close();
             spare = undefined;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxmutate",
-  "version": "2.5.0",
+  "version": "2.6.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>",