@mutineerjs/mutineer 0.1.0

package/dist/runner/vitest/pool.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Vitest Worker Pool
+ *
+ * Manages a pool of persistent Vitest worker processes that can run
+ * multiple mutations without restarting, providing significant speedup
+ * over the per-spawn approach.
+ *
+ * Each worker:
+ * - Starts Vitest in watch mode via programmatic API
+ * - Receives mutations via stdin (JSON)
+ * - Uses dynamic redirect loader to swap module at runtime
+ * - Returns results via stdout (JSON)
+ */
+import { EventEmitter } from 'node:events';
+import type { MutantPayload, MutantRunResult, MutantRunSummary } from '../../types/mutant.js';
+declare class VitestWorker extends EventEmitter {
+    private readonly cwd;
+    private readonly vitestConfig?;
+    readonly id: string;
+    private process;
+    private rl;
+    private pendingTask;
+    private ready;
+    private shuttingDown;
+    constructor(id: string, cwd: string, vitestConfig?: string | undefined);
+    start(): Promise<void>;
+    private handleMessage;
+    private handleExit;
+    isReady(): boolean;
+    isBusy(): boolean;
+    run(mutant: MutantPayload, tests: string[], timeoutMs?: number): Promise<MutantRunSummary>;
+    shutdown(): Promise<void>;
+    kill(): void;
+}
+export interface VitestPoolOptions {
+    cwd: string;
+    concurrency: number;
+    vitestConfig?: string;
+    timeoutMs?: number;
+    createWorker?: (id: string, opts: {
+        cwd: string;
+        vitestConfig?: string;
+    }) => VitestWorker;
+}
+export declare class VitestPool {
+    private workers;
+    private availableWorkers;
+    private waitingTasks;
+    private readonly options;
+    private initialized;
+    private shuttingDown;
+    constructor(options: VitestPoolOptions);
+    init(): Promise<void>;
+    private handleWorkerExit;
+    private acquireWorker;
+    private releaseWorker;
+    run(mutant: MutantPayload, tests: string[]): Promise<MutantRunSummary>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Run a single mutation using the pool.
+ * Convenience function for integration with orchestrator.
+ */
+export declare function runWithPool(pool: VitestPool, mutant: MutantPayload, tests: readonly string[]): Promise<MutantRunResult>;
+export type { MutantPayload, MutantRunResult, MutantRunSummary, } from '../../types/mutant.js';

package/dist/runner/vitest/pool.js

@@ -0,0 +1,376 @@
+/**
+ * Vitest Worker Pool
+ *
+ * Manages a pool of persistent Vitest worker processes that can run
+ * multiple mutations without restarting, providing significant speedup
+ * over the per-spawn approach.
+ *
+ * Each worker:
+ * - Starts Vitest in watch mode via programmatic API
+ * - Receives mutations via stdin (JSON)
+ * - Uses dynamic redirect loader to swap module at runtime
+ * - Returns results via stdout (JSON)
+ */
+import { spawn } from 'node:child_process';
+import * as path from 'node:path';
+import * as readline from 'node:readline';
+import * as fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { EventEmitter } from 'node:events';
+import { createLogger, DEBUG } from '../../utils/logger.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const workerLog = createLogger('VitestWorker');
+const poolLog = createLogger('VitestPool');
+class VitestWorker extends EventEmitter {
+    constructor(id, cwd, vitestConfig) {
+        super();
+        this.cwd = cwd;
+        this.vitestConfig = vitestConfig;
+        this.process = null;
+        this.rl = null;
+        this.pendingTask = null;
+        this.ready = false;
+        this.shuttingDown = false;
+        this.id = id;
+    }
+    async start() {
+        const workerJs = path.join(__dirname, 'worker.js');
+        const workerMts = path.join(__dirname, 'worker.mjs');
+        const workerTs = path.join(__dirname, 'worker.mts');
+        const workerScript = fs.existsSync(workerJs)
+            ? workerJs
+            : fs.existsSync(workerMts)
+                ? workerMts
+                : workerTs;
+        const loaderJs = path.join(__dirname, 'redirect-loader.js');
+        const loaderMjs = path.join(__dirname, 'redirect-loader.mjs');
+        const loaderTs = path.join(__dirname, 'redirect-loader.ts');
+        const loaderScript = fs.existsSync(loaderJs)
+            ? loaderJs
+            : fs.existsSync(loaderMjs)
+                ? loaderMjs
+                : loaderTs;
+        const env = {
+            ...process.env,
+            MUTINEER_WORKER_ID: this.id,
+            MUTINEER_CWD: this.cwd,
+            ...(this.vitestConfig
+                ? { MUTINEER_VITEST_CONFIG: this.vitestConfig }
+                : {}),
+            ...(DEBUG ? { MUTINEER_DEBUG: '1' } : {}),
+        };
+        workerLog.debug(`[${this.id}] Starting worker process`);
+        this.process = spawn(process.execPath, [
+            '--experimental-strip-types',
+            '--experimental-transform-types',
+            '--no-warnings',
+            '--import',
+            loaderScript,
+            workerScript,
+        ], {
+            cwd: this.cwd,
+            env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Handle stderr (debug/error output)
+        this.process.stderr?.on('data', (data) => {
+            if (DEBUG) {
+                process.stderr.write(`[worker-${this.id}] ${data}`);
+            }
+        });
+        // Set up line reader for stdout (JSON messages)
+        this.rl = readline.createInterface({
+            input: this.process.stdout,
+            terminal: false,
+        });
+        this.rl.on('line', (line) => this.handleMessage(line));
+        this.process.on('error', (err) => {
+            workerLog.debug(`[${this.id}] Process error: ${err.message}`);
+            this.handleExit(1);
+        });
+        this.process.on('exit', (code) => {
+            workerLog.debug(`[${this.id}] Process exited with code ${code}`);
+            this.handleExit(code ?? 1);
+        });
+        // Wait for ready signal
+        await new Promise((resolve, reject) => {
+            const timeoutMs = 120_000; // allow more time for Vitest init (coverage, large projects)
+            const timeout = setTimeout(() => {
+                reject(new Error(`Worker ${this.id} did not become ready in time (${timeoutMs}ms)`));
+            }, timeoutMs);
+            this.once('ready', () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+            this.once('error', (err) => {
+                clearTimeout(timeout);
+                reject(err);
+            });
+        });
+    }
+    handleMessage(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        // Only attempt to parse JSON lines; ignore any other stdout noise
+        if (!trimmed.startsWith('{')) {
+            workerLog.debug(`[${this.id}] Non-JSON stdout: ${trimmed}`);
+            return;
+        }
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            workerLog.debug(`[${this.id}] Invalid JSON from worker: ${line}`);
+            return;
+        }
+        if (msg.type === 'ready') {
+            this.ready = true;
+            this.emit('ready');
+            return;
+        }
+        if (msg.type === 'result') {
+            if (this.pendingTask) {
+                const { resolve, timeoutHandle } = this.pendingTask;
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                this.pendingTask = null;
+                resolve({
+                    killed: msg.killed ?? true,
+                    durationMs: msg.durationMs ?? 0,
+                    error: msg.error,
+                });
+            }
+            return;
+        }
+        if (msg.type === 'shutdown') {
+            this.emit('shutdown');
+            return;
+        }
+    }
+    handleExit(code) {
+        this.ready = false;
+        if (this.pendingTask && !this.shuttingDown) {
+            const { reject, timeoutHandle } = this.pendingTask;
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            this.pendingTask = null;
+            reject(new Error(`Worker exited unexpectedly with code ${code}`));
+        }
+        this.emit('exit', code);
+    }
+    isReady() {
+        return this.ready && this.process !== null && !this.shuttingDown;
+    }
+    isBusy() {
+        return this.pendingTask !== null;
+    }
+    async run(mutant, tests, timeoutMs = 10_000) {
+        if (!this.isReady()) {
+            throw new Error(`Worker ${this.id} is not ready`);
+        }
+        if (this.isBusy()) {
+            throw new Error(`Worker ${this.id} is busy`);
+        }
+        return new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                if (this.pendingTask) {
+                    this.pendingTask = null;
+                    // Kill and restart the worker on timeout
+                    this.kill();
+                    resolve({ killed: true, durationMs: timeoutMs, error: 'timeout' });
+                }
+            }, timeoutMs);
+            this.pendingTask = { resolve, reject, timeoutHandle };
+            const request = JSON.stringify({ type: 'run', mutant, tests });
+            this.process.stdin.write(request + '\n');
+        });
+    }
+    async shutdown() {
+        if (!this.process || this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                this.kill();
+                resolve();
+            }, 5000);
+            this.once('shutdown', () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+            this.process.stdin.write(JSON.stringify({ type: 'shutdown' }) + '\n');
+        });
+    }
+    kill() {
+        if (this.process) {
+            try {
+                this.process.kill('SIGKILL');
+            }
+            catch {
+                // Ignore
+            }
+            this.process = null;
+        }
+        this.ready = false;
+    }
+}
+export class VitestPool {
+    constructor(options) {
+        this.workers = [];
+        this.availableWorkers = [];
+        this.waitingTasks = [];
+        this.initialized = false;
+        this.shuttingDown = false;
+        this.options = {
+            cwd: options.cwd,
+            concurrency: options.concurrency,
+            vitestConfig: options.vitestConfig,
+            timeoutMs: options.timeoutMs ?? 10_000,
+            createWorker: options.createWorker,
+        };
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        poolLog.debug(`Initializing pool with ${this.options.concurrency} workers`);
+        const startPromises = [];
+        for (let i = 0; i < this.options.concurrency; i++) {
+            const worker = this.options.createWorker?.(`w${i}`, {
+                cwd: this.options.cwd,
+                vitestConfig: this.options.vitestConfig,
+            }) ??
+                new VitestWorker(`w${i}`, this.options.cwd, this.options.vitestConfig);
+            worker.on('exit', () => {
+                if (!this.shuttingDown) {
+                    this.handleWorkerExit(worker);
+                }
+            });
+            this.workers.push(worker);
+            startPromises.push(worker.start().then(() => {
+                this.availableWorkers.push(worker);
+                poolLog.debug(`Worker ${worker.id} ready`);
+            }));
+        }
+        await Promise.all(startPromises);
+        this.initialized = true;
+        poolLog.debug('Pool initialized');
+    }
+    handleWorkerExit(worker) {
+        // Remove from available list
+        const availIdx = this.availableWorkers.indexOf(worker);
+        if (availIdx >= 0) {
+            this.availableWorkers.splice(availIdx, 1);
+        }
+        // Try to restart the worker
+        poolLog.debug(`Worker ${worker.id} exited, attempting restart`);
+        const newWorker = this.options.createWorker?.(worker.id, {
+            cwd: this.options.cwd,
+            vitestConfig: this.options.vitestConfig,
+        }) ??
+            new VitestWorker(worker.id, this.options.cwd, this.options.vitestConfig);
+        const idx = this.workers.indexOf(worker);
+        if (idx >= 0) {
+            this.workers[idx] = newWorker;
+        }
+        newWorker.on('exit', () => {
+            if (!this.shuttingDown) {
+                this.handleWorkerExit(newWorker);
+            }
+        });
+        newWorker
+            .start()
+            .then(() => {
+            this.releaseWorker(newWorker);
+            poolLog.debug(`Worker ${newWorker.id} restarted`);
+        })
+            .catch((err) => {
+            poolLog.debug(`Failed to restart worker ${newWorker.id}: ${err}`);
+        });
+    }
+    async acquireWorker() {
+        // Try to get an available worker
+        const worker = this.availableWorkers.shift();
+        if (worker) {
+            return worker;
+        }
+        // Wait for one to become available
+        return new Promise((resolve) => {
+            this.waitingTasks.push(resolve);
+        });
+    }
+    releaseWorker(worker) {
+        // If someone is waiting, give them the worker directly
+        const waiting = this.waitingTasks.shift();
+        if (waiting) {
+            waiting(worker);
+            return;
+        }
+        // Otherwise return to the pool
+        if (worker.isReady()) {
+            this.availableWorkers.push(worker);
+        }
+    }
+    async run(mutant, tests) {
+        if (!this.initialized) {
+            throw new Error('Pool not initialized. Call init() first.');
+        }
+        if (this.shuttingDown) {
+            throw new Error('Pool is shutting down');
+        }
+        const worker = await this.acquireWorker();
+        try {
+            const result = await worker.run(mutant, tests, this.options.timeoutMs);
+            return result;
+        }
+        finally {
+            this.releaseWorker(worker);
+        }
+    }
+    async shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        poolLog.debug('Shutting down pool');
+        await Promise.all(this.workers.map((w) => w.shutdown()));
+        this.workers = [];
+        this.availableWorkers = [];
+        this.initialized = false;
+        poolLog.debug('Pool shut down');
+    }
+}
+/**
+ * Run a single mutation using the pool.
+ * Convenience function for integration with orchestrator.
+ */
+export async function runWithPool(pool, mutant, tests) {
+    try {
+        const result = await pool.run(mutant, [...tests]);
+        if (result.error === 'timeout') {
+            return {
+                status: 'timeout',
+                durationMs: result.durationMs,
+                error: result.error,
+            };
+        }
+        if (result.error && !result.killed) {
+            return {
+                status: 'error',
+                durationMs: result.durationMs,
+                error: result.error,
+            };
+        }
+        return {
+            status: result.killed ? 'killed' : 'escaped',
+            durationMs: result.durationMs,
+        };
+    }
+    catch (err) {
+        return {
+            status: 'error',
+            durationMs: 0,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}

package/dist/runner/vitest/redirect-loader.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Dynamic ESM loader for persistent Vitest workers.
+ *
+ * Reads redirect targets from globalThis.__mutineer_redirect__ on each resolution
+ * so workers can swap files without restarting.
+ *
+ * NOTE: This loader must be self-contained and cannot import from the shared module
+ * because it runs in a special Node.js context before module resolution happens.
+ */
+declare global {
+    var __mutineer_redirect__: {
+        from: string | null;
+        to: string | null;
+    } | undefined;
+}
+export declare function initialize(data: {
+    debug?: boolean;
+} | undefined): void;
+export declare function resolve(specifier: string, context: {
+    parentURL?: string;
+}, nextResolve: (specifier: string, context: {
+    parentURL?: string;
+}) => Promise<{
+    url: string;
+    shortCircuit?: boolean;
+} | null>): Promise<{
+    url: string;
+    shortCircuit?: boolean;
+} | null>;
+export declare function load(url: string, context: unknown, nextLoad: (u: string, c: unknown) => Promise<unknown>): Promise<unknown>;

package/dist/runner/vitest/redirect-loader.js

@@ -0,0 +1,123 @@
+/**
+ * Dynamic ESM loader for persistent Vitest workers.
+ *
+ * Reads redirect targets from globalThis.__mutineer_redirect__ on each resolution
+ * so workers can swap files without restarting.
+ *
+ * NOTE: This loader must be self-contained and cannot import from the shared module
+ * because it runs in a special Node.js context before module resolution happens.
+ */
+import { register, builtinModules } from 'node:module';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import path from 'node:path';
+import fs from 'node:fs';
+// Register this file as the loader hooks module
+register(import.meta.url, {
+    parentURL: import.meta.url,
+    data: { debug: process.env.MUTINEER_DEBUG === '1' },
+});
+let DEBUG = process.env.MUTINEER_DEBUG === '1';
+export function initialize(data) {
+    if (data?.debug !== undefined) {
+        DEBUG = data.debug;
+    }
+}
+/**
+ * Try to resolve a .js import to a .ts or .tsx file (TypeScript ESM convention)
+ */
+function tryResolveTsExtension(specifier, parentURL) {
+    if (!specifier.endsWith('.js') || !specifier.startsWith('.')) {
+        return null;
+    }
+    let parentPath;
+    try {
+        parentPath = fileURLToPath(parentURL ?? '');
+    }
+    catch {
+        return null;
+    }
+    const parentDir = path.dirname(parentPath);
+    // If the parent is in a __mutineer__ directory, also try the parent's parent
+    const dirsToTry = [parentDir];
+    if (path.basename(parentDir) === '__mutineer__') {
+        dirsToTry.push(path.dirname(parentDir));
+    }
+    const tsSpecifier = specifier.slice(0, -3) + '.ts';
+    const tsxSpecifier = specifier.slice(0, -3) + '.tsx';
+    for (const dir of dirsToTry) {
+        const tsPath = path.resolve(dir, tsSpecifier);
+        if (fs.existsSync(tsPath)) {
+            return pathToFileURL(tsPath).href;
+        }
+        const tsxPath = path.resolve(dir, tsxSpecifier);
+        if (fs.existsSync(tsxPath)) {
+            return pathToFileURL(tsxPath).href;
+        }
+    }
+    return null;
+}
+/**
+ * Get redirect config with URL conversion for ESM loader.
+ * Self-contained implementation (cannot use shared module in loader context).
+ */
+function getRedirect() {
+    const redirect = globalThis.__mutineer_redirect__;
+    if (!redirect?.from || !redirect?.to) {
+        return null;
+    }
+    return {
+        from: path.resolve(redirect.from),
+        fromUrl: pathToFileURL(path.resolve(redirect.from)).href,
+        to: redirect.to,
+    };
+}
+export async function resolve(specifier, context, nextResolve) {
+    const redirect = getRedirect();
+    const isBuiltin = specifier.startsWith('node:') || builtinModules.includes(specifier);
+    const isNodeModulesSpec = specifier.includes('node_modules');
+    const shouldLog = DEBUG && !isBuiltin && !isNodeModulesSpec;
+    if (shouldLog) {
+        console.error(`[pool-loader] resolve: ${specifier}`);
+        if (redirect) {
+            console.error(`[pool-loader] active redirect: ${redirect.from} -> ${redirect.to}`);
+        }
+    }
+    // Try to resolve .js -> .ts for TypeScript ESM imports
+    const tsResolved = tryResolveTsExtension(specifier, context.parentURL);
+    if (tsResolved) {
+        if (shouldLog)
+            console.error(`[pool-loader] .js -> .ts: ${specifier} -> ${tsResolved}`);
+        // Check if this is our redirect target
+        if (redirect && tsResolved === redirect.fromUrl) {
+            if (DEBUG)
+                console.error(`[pool-loader] REDIRECTING ${tsResolved} -> ${pathToFileURL(redirect.to).href}`);
+            return {
+                url: pathToFileURL(redirect.to).href,
+                shortCircuit: true,
+            };
+        }
+        return {
+            url: tsResolved,
+            shortCircuit: true,
+        };
+    }
+    const resolved = await nextResolve(specifier, context);
+    const resolvedInNodeModules = resolved?.url?.includes('/node_modules/');
+    const resolvedBuiltin = resolved?.url?.startsWith('node:');
+    if (shouldLog && resolved && !resolvedInNodeModules && !resolvedBuiltin)
+        console.error(`[pool-loader] resolved ${specifier} to ${resolved.url}`);
+    // Check if this resolves to our redirect target
+    if (redirect && resolved?.url === redirect.fromUrl) {
+        if (DEBUG)
+            console.error(`[pool-loader] REDIRECTING ${resolved.url} -> ${pathToFileURL(redirect.to).href}`);
+        return {
+            ...resolved,
+            url: pathToFileURL(redirect.to).href,
+            shortCircuit: true,
+        };
+    }
+    return resolved;
+}
+export async function load(url, context, nextLoad) {
+    return nextLoad(url, context);
+}

package/dist/runner/vitest/worker-runtime.d.ts

@@ -0,0 +1,16 @@
+import type { MutantPayload } from '../types.js';
+import type { MutantRunSummary } from '../../types/mutant.js';
+export interface VitestWorkerRuntimeOptions {
+    workerId: string;
+    cwd: string;
+    vitestConfigPath?: string;
+}
+export declare class VitestWorkerRuntime {
+    private readonly options;
+    private vitest;
+    constructor(options: VitestWorkerRuntimeOptions);
+    init(): Promise<void>;
+    shutdown(): Promise<void>;
+    run(mutant: MutantPayload, tests: string[]): Promise<MutantRunSummary>;
+}
+export declare function createVitestWorkerRuntime(options: VitestWorkerRuntimeOptions): VitestWorkerRuntime;