oxmutate 0.0.0 → 1.0.0

package/dist/scheduler.js

@@ -0,0 +1,170 @@
+/**
+ * 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';
+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;
+    }
+    catch {
+        return undefined;
+    }
+}
+class Server {
+    child;
+    ready;
+    stderr = '';
+    onMessage;
+    onExit;
+    exited = false;
+    constructor(configFile, cwd, execArgv) {
+        this.child = fork(childJs, [configFile], { cwd, stdio: ['ignore', 'ignore', 'pipe', 'ipc'], execArgv });
+        this.child.stderr?.on('data', (d) => (this.stderr = (this.stderr + d.toString()).slice(-STDERR_TAIL)));
+        this.ready = new Promise((resolve) => {
+            const first = (m) => {
+                if (m.type === 'ready') {
+                    this.child.off('message', first);
+                    resolve(true);
+                }
+            };
+            this.child.on('message', first);
+            this.child.once('exit', () => resolve(false));
+        });
+        this.child.on('message', (m) => this.onMessage?.(m));
+        this.child.once('exit', (code) => {
+            this.exited = true;
+            this.onExit?.(code);
+        });
+    }
+    run(unit, budget) {
+        writeFileSync(unit.progress, '');
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (o) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearInterval(timer);
+                this.onMessage = undefined;
+                this.onExit = undefined;
+                resolve(o);
+            };
+            const timer = setInterval(() => {
+                let line = '';
+                try {
+                    line = readFileSync(unit.progress, 'utf8').trim();
+                }
+                catch {
+                    return;
+                }
+                if (!line)
+                    return;
+                const [id = '', since = '0'] = line.split(' ');
+                if (Date.now() - Number(since) > budget(id)) {
+                    this.child.kill('SIGKILL');
+                    finish({ killedFor: id, stderr: this.stderr });
+                }
+            }, WATCHDOG_POLL_MS);
+            this.onMessage = (m) => {
+                if (m.type === 'done')
+                    finish({ stderr: this.stderr });
+            };
+            this.onExit = () => finish({ crashed: true, crashedFor: inFlight(unit.progress), stderr: this.stderr });
+            if (this.exited)
+                finish({ crashed: true, stderr: this.stderr });
+            else
+                this.child.send({ type: 'run', unit });
+        });
+    }
+    close() {
+        if (this.exited)
+            return;
+        this.child.send({ type: 'close' });
+        setTimeout(() => this.child.kill('SIGKILL'), CLOSE_GRACE_MS).unref();
+    }
+}
+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 spawn = () => {
+        stats.spawned++;
+        return new Server(configFile, config.root, config.nodeArgs ?? []);
+    };
+    const servers = Array.from({ length: size }, spawn);
+    let spare = spawn();
+    const replacement = () => {
+        const next = spare ?? spawn();
+        spare = spawn();
+        return next;
+    };
+    return {
+        stats,
+        async drain(units, budget, after) {
+            const queue = [...units];
+            let busy = 0;
+            const waiters = [];
+            const signal = () => {
+                for (const w of waiters.splice(0))
+                    w();
+            };
+            await Promise.all(servers.map(async (_, slot) => {
+                for (;;) {
+                    const unit = queue.shift();
+                    if (!unit) {
+                        if (busy === 0) {
+                            signal();
+                            return;
+                        }
+                        await new Promise((r) => waiters.push(r));
+                        continue;
+                    }
+                    busy++;
+                    let server = servers[slot];
+                    if (!(await server.ready)) {
+                        server = replacement();
+                        servers[slot] = server;
+                        await server.ready;
+                    }
+                    const outcome = await server.run(unit, (id) => budget(unit, id));
+                    if (outcome.killedFor)
+                        stats.killed++;
+                    if (outcome.crashed)
+                        stats.crashed++;
+                    if (outcome.killedFor || outcome.crashed) {
+                        servers[slot] = replacement();
+                    }
+                    const more = after(unit, outcome);
+                    queue.unshift(...more);
+                    busy--;
+                    signal();
+                }
+            }));
+        },
+        close() {
+            for (const s of servers)
+                s.close();
+            spare?.close();
+            spare = undefined;
+        },
+    };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/spec-oracle.d.ts

@@ -0,0 +1,69 @@
+export interface SpecOracle {
+    name: string;
+    backend: 'quint' | 'itf';
+    /** `quint`: the model file, relative to the project root. */
+    model?: string | undefined;
+    /** `quint`: traces to generate (default 100), steps per trace (default 20), and a seed. */
+    traces?: number | undefined;
+    maxSteps?: number | undefined;
+    seed?: string | undefined;
+    /** `quint`: how to run it (default the version burgee's models.yml pins, through npx). */
+    quint?: string | undefined;
+    /** `itf`: the directory of traces, relative to the project root. */
+    dir?: string | undefined;
+    /** The replay test files (globs, relative to the root): their tests are this oracle's. */
+    replay: string[];
+    /** The source files the model describes (globs): the denominator of F1, F3 and F6. */
+    files: string[];
+}
+/** The oracle's traces on disk: generated into `work` for `quint`, the given directory for `itf`. */
+export declare function tracesFor(oracle: SpecOracle, root: string, work: string): Promise<string>;
+interface Located {
+    id: string;
+    file: string;
+    line: number;
+    mutatorName: string;
+    replacement: string;
+}
+/** One oracle's F metrics (metrics.md §6), over the mutants in the files its model describes. */
+export interface SpecSummary {
+    name: string;
+    backend: SpecOracle['backend'];
+    traces: number;
+    /** Mutants in the modelled files that are scored (not ignored). */
+    modelled: number;
+    /** F6: share of those a replay test reaches. */
+    mappingCoverage: number;
+    /** F1: share of those the spec kills. */
+    specKillShare: number;
+    /** F2: the spec kills them, the tests do not — each a missing test, with the trace that found it. */
+    testSpecGap: (Located & {
+        trace: string;
+    })[];
+    /** F3: neither kills them — gaps in the model itself, or equivalent mutants. */
+    specEscapes: Located[];
+    /** F4: median ms of one replay execution with a mutant armed. */
+    msPerSpecExecution: number;
+}
+export interface SpecMutant extends Located {
+    status: string;
+    specCoveredBy?: string[] | undefined;
+    spec?: {
+        oracle: string;
+        status: string;
+        killedBy?: string[] | undefined;
+    } | undefined;
+}
+export interface SpecInput {
+    oracle: SpecOracle;
+    /** Repository-relative paths of the files the model describes. */
+    modelledFiles: Set<string>;
+    traces: number;
+    mutants: SpecMutant[];
+    /** A replay test's name (it names the trace) from its id. */
+    testName: (id: string) => string;
+    /** Each replay execution's ms, mutant armed. */
+    specMs: number[];
+}
+export declare function summarizeSpec({ oracle, modelledFiles, traces, mutants, testName, specMs }: SpecInput): SpecSummary;
+export {};

package/dist/spec-oracle.js

@@ -0,0 +1,68 @@
+/**
+ * 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')];
+    if (oracle.seed)
+        args.push('--seed', oracle.seed);
+    const r = await spawn(command, args, { cwd: root, runtime: ambientRuntime() });
+    if (!r.ok)
+        throw new Error(`spec oracle ${oracle.name}: quint run exited ${String(r.code)}: ${(r.stderr || r.stdout).trim().slice(-OUTPUT_TAIL)}. fix: run the same quint command by hand on ${oracle.model ?? '(no model)'}`);
+    return dir;
+}
+const PERCENT = 100;
+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);
+    return sorted.length ? (sorted[Math.floor(sorted.length / 2)] ?? 0) : 0;
+};
+const testsMiss = (m) => m.status === 'Survived' || m.status === 'NoCoverage';
+export function summarizeSpec({ oracle, modelledFiles, traces, mutants, testName, specMs }) {
+    const here = mutants.filter((m) => modelledFiles.has(m.file) && m.status !== 'Ignored');
+    const reached = here.filter((m) => m.specCoveredBy?.length);
+    const killed = here.filter((m) => m.spec?.status === 'Killed');
+    return {
+        name: oracle.name,
+        backend: oracle.backend,
+        traces,
+        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.d.ts

@@ -0,0 +1,21 @@
+/** JSON map of oracle name → directory of `*.itf.json` traces, set by oxmutate for its servers. */
+export declare const SPEC_TRACES_ENV = "OXMUTATE_SPEC_TRACES";
+export interface Step {
+    /** The model action that produced this state (`mbt::actionTaken`); `init` for the first. */
+    action: string;
+    /** The nondeterministic choices the action made (`mbt::nondetPicks`), `None` as undefined. */
+    picks: Record<string, unknown>;
+    /** The model's variables after the action, ITF values decoded. */
+    state: Record<string, unknown>;
+}
+export interface Trace {
+    /** The trace file's name, which the report quotes as the counterexample. */
+    name: string;
+    steps: Step[];
+}
+/** One ITF value, decoded as in a trace file. */
+export declare const decode: (v: unknown) => unknown;
+/** One ITF file as steps. */
+export declare function readTrace(file: string): Trace;
+/** The traces oxmutate generated for this oracle, in file order; none outside an oxmutate run. */
+export declare function loadTraces(oracle: string): Trace[];

package/dist/spec.js

@@ -0,0 +1,75 @@
+/**
+ * `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;
+    const o = v;
+    if ('#bigint' in o) {
+        const n = BigInt(String(o['#bigint']));
+        return n <= BigInt(Number.MAX_SAFE_INTEGER) && n >= BigInt(Number.MIN_SAFE_INTEGER) ? Number(n) : n;
+    }
+    if ('#set' in o)
+        return o['#set'];
+    if ('#tup' in o)
+        return o['#tup'];
+    if ('#map' in o)
+        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))
+        return 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'] ?? ''),
+        picks: Object.fromEntries(Object.entries((s['mbt::nondetPicks'] ?? {})).map(([n, p]) => [n, pick(p)])),
+        state: Object.fromEntries(Object.entries(s).filter(([k]) => !META.has(k))),
+    }));
+    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];
+    if (!dir)
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith('.itf.json'))
+        .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

@@ -0,0 +1,18 @@
+/**
+ * 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) {
+    const map = new Map(Object.entries(JSON.parse(readFileSync(mapPath, 'utf8'))).map(([k, v]) => [path.resolve(k), v]));
+    return {
+        name: 'oxmutate:instrumented-sources',
+        enforce: 'pre',
+        load(id) {
+            const file = id.split('?')[0] ?? id;
+            return map.get(path.resolve(file));
+        },
+    };
+}
+//# sourceMappingURL=vite-plugin.js.map

package/dist/vite.d.ts

@@ -0,0 +1,16 @@
+/** `oxmutate/vite`: the `mutate` block on Vite's config type, so `vite.config.ts` holds it beside `test` (`/// <reference types="oxmutate/vite" />`). */
+import type { UserConfig } from 'vite';
+import type { MutateConfig } from './config.js';
+declare module 'vite' {
+    interface UserConfig {
+        /** oxmutate's settings: read by `oxmutate run` from this file when no oxmutate.config.* exists. */
+        mutate?: MutateConfig;
+    }
+}
+/** A Vite config with oxmutate's block: what `defineConfig` accepts once this module is referenced. */
+export type MutateViteConfig = UserConfig & {
+    mutate?: MutateConfig;
+};
+export type { MutateConfig };
+/** Types a `mutate` block written apart from `defineConfig` (in a shared file, say); returns it unchanged. */
+export declare const defineMutate: (config: MutateConfig) => MutateConfig;

package/dist/vite.js

@@ -0,0 +1,3 @@
+/** 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,10 +1,85 @@
 {
   "name": "oxmutate",
-  "version": "0.0.0",
-  "description": "Mutation testing on the oxc engine. In development; this release reserves the name. Community project, not affiliated with the oxc project.",
-  "keywords": ["mutation-testing", "oxc", "vitest", "stryker-alternative"],
-  "author": "Ofri Peretz",
+  "version": "1.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",
-  "main": "index.js",
-  "files": ["index.js", "README.md"]
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ofri-peretz/burgee.git",
+    "directory": "packages/oxmutate"
+  },
+  "bugs": {
+    "url": "https://github.com/ofri-peretz/burgee/issues"
+  },
+  "homepage": "https://oxmutate.interlace.tools",
+  "type": "module",
+  "private": false,
+  "engines": {
+    "node": "^20.19.0 || >=22.13.0"
+  },
+  "bin": {
+    "oxmutate": "./dist/bin.js"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./runner": {
+      "types": "./dist/runner.d.ts",
+      "import": "./dist/runner.js",
+      "default": "./dist/runner.js"
+    },
+    "./spec": {
+      "types": "./dist/spec.d.ts",
+      "import": "./dist/spec.js",
+      "default": "./dist/spec.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js",
+      "default": "./dist/vite.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "runner": ["./dist/runner.d.ts"],
+      "spec": ["./dist/spec.d.ts"],
+      "vite": ["./dist/vite.d.ts"]
+    }
+  },
+  "files": [
+    "dist",
+    "binding/oxmutate.*.node",
+    "!dist/**/*.map",
+    "!dist/**/*.test.*"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && 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",
+    "test:native": "cd native && cargo test --release",
+    "lint": "eslint src",
+    "coverage": "vitest run --coverage.enabled"
+  },
+  "dependencies": {
+    "bellpull": "*",
+    "burgee": "*"
+  },
+  "peerDependencies": {
+    "vitest": ">=4.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^5.0.1"
+  },
+  "//optionalDependencies": "Written at publish time by the release job (scripts/sync-platform-versions.mjs --publish): the public oxmutate-<platform> packages under npm/, at this version; none while they are private, as in 0.1, which ships all six cores in binding/ instead. Never committed: npm ci refuses a lockfile that cannot record an optional dependency npm does not serve (EUSAGE). See RELEASING.md.",
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  }
 }

package/index.js

@@ -1 +0,0 @@
-throw new Error('oxmutate is in development and has no release yet. Follow the README for status.');