@mutineerjs/mutineer 0.5.1 → 0.7.0

package/dist/runner/cleanup.js

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 /**
  * Clean up all __mutineer__ temp directories created during mutation testing.
  */
-export async function cleanupMutineerDirs(cwd) {
+export async function cleanupMutineerDirs(cwd, opts = {}) {
     const glob = await import('fast-glob');
     const dirs = await glob.default('**/__mutineer__', {
         cwd,
@@ -18,4 +18,21 @@ export async function cleanupMutineerDirs(cwd) {
             // Ignore cleanup errors
         }
     }
+    if (opts.includeCacheFiles) {
+        // Remove cache files (new name + legacy .mutate-cache* for migration)
+        const cacheFiles = await glob.default([
+            '.mutineer-cache*.json',
+            '.mutineer-cache*.json.tmp',
+            '.mutate-cache*.json',
+            '.mutate-cache*.json.tmp',
+        ], { cwd, absolute: true });
+        for (const f of cacheFiles) {
+            try {
+                await fs.unlink(f);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+    }
 }

package/dist/runner/config.js

@@ -19,7 +19,7 @@ const log = createLogger('config');
 async function loadModule(filePath) {
     const moduleUrl = pathToFileURL(filePath).href;
     const mod = await import(moduleUrl);
-    return mod.default ?? mod;
+    return 'default' in mod ? mod.default : mod;
 }
 /**
  * Validate that the loaded configuration has the expected shape.

package/dist/runner/coverage-resolver.js

@@ -15,7 +15,7 @@ export async function resolveCoverageConfig(opts, cfg, adapter, cliArgs) {
         ? true
         : coveragePreference === false
             ? false
-            : isCoverageRequestedInArgs([...cliArgs]) || coverageConfig.coverageEnabled;
+            : isCoverageRequestedInArgs([...cliArgs]);
     // Load pre-existing coverage data if provided
     let coverageData = null;
     if (opts.coverageFilePath) {

package/dist/runner/discover.d.ts

@@ -5,4 +5,4 @@ export interface DiscoveryResult {
     readonly testMap: TestMap;
     readonly directTestMap: TestMap;
 }
-export declare function autoDiscoverTargetsAndTests(root: string, cfg: MutineerConfig): Promise<DiscoveryResult>;
+export declare function autoDiscoverTargetsAndTests(root: string, cfg: MutineerConfig, onProgress?: (msg: string) => void): Promise<DiscoveryResult>;

package/dist/runner/discover.js

@@ -200,7 +200,7 @@ async function createResolver(rootAbs, exts) {
         return createNodeResolver();
     }
 }
-export async function autoDiscoverTargetsAndTests(root, cfg) {
+export async function autoDiscoverTargetsAndTests(root, cfg, onProgress) {
     const rootAbs = path.resolve(root);
     const sourceRoots = toArray(cfg.source ?? 'src').map((s) => path.resolve(rootAbs, s));
     const exts = new Set(toArray(cfg.extensions ?? EXT_DEFAULT));
@@ -219,6 +219,7 @@ export async function autoDiscoverTargetsAndTests(root, cfg) {
     if (!tests.length)
         return { targets: [], testMap: new Map(), directTestMap: new Map() };
     const testSet = new Set(tests.map((t) => normalizePath(t)));
+    onProgress?.(`Found ${tests.length} test file(s), resolving imports...`);
     // 2) Create resolver (Vite if available, otherwise Node-based fallback)
     const { resolve, cleanup } = await createResolver(rootAbs, exts);
     const targets = new Map();
@@ -226,6 +227,7 @@ export async function autoDiscoverTargetsAndTests(root, cfg) {
     const directTestMap = new Map();
     const contentCache = new Map();
     const resolveCache = new Map(); // key: importer\0spec -> resolved id
+    const childrenCache = new Map(); // key: normalized file -> resolved child abs paths
     async function crawl(absFile, depth, seen, currentTestAbs) {
         if (depth > MAX_CRAWL_DEPTH)
             return; // sane guard for huge graphs
@@ -266,27 +268,34 @@ export async function autoDiscoverTargetsAndTests(root, cfg) {
         }
         if (!code)
             return;
-        // find import specs and resolve relative to absFile
-        for (const spec of extractImportSpecs(code)) {
-            if (!spec)
-                continue;
-            const cacheKey = `${absFile}\0${spec}`;
-            let resolved = resolveCache.get(cacheKey);
-            if (!resolved) {
-                resolved = await resolve(spec, absFile);
-                resolveCache.set(cacheKey, resolved);
+        // find import specs and resolve relative to absFile, memoized per file
+        let children = childrenCache.get(key);
+        if (children === undefined) {
+            const resolved = [];
+            for (const spec of extractImportSpecs(code)) {
+                if (!spec)
+                    continue;
+                const cacheKey = `${absFile}\0${spec}`;
+                let resolvedId = resolveCache.get(cacheKey);
+                if (!resolvedId) {
+                    resolvedId = await resolve(spec, absFile);
+                    resolveCache.set(cacheKey, resolvedId);
+                }
+                // vite ids could be URLs; ensure we turn into absolute disk path when possible
+                const next = path.isAbsolute(resolvedId)
+                    ? resolvedId
+                    : normalizePath(path.resolve(rootAbs, resolvedId));
+                // skip node_modules and virtual ids
+                if (next.includes('/node_modules/'))
+                    continue;
+                if (!path.isAbsolute(next))
+                    continue;
+                resolved.push(next);
             }
-            // vite ids could be URLs; ensure we turn into absolute disk path when possible
-            const next = path.isAbsolute(resolved)
-                ? resolved
-                : normalizePath(path.resolve(rootAbs, resolved));
-            // skip node_modules and virtual ids
-            if (next.includes('/node_modules/'))
-                continue;
-            if (!path.isAbsolute(next))
-                continue;
-            await crawl(next, depth + 1, seen, currentTestAbs);
+            childrenCache.set(key, resolved);
+            children = resolved;
         }
+        await Promise.all(children.map((next) => crawl(next, depth + 1, seen, currentTestAbs)));
     }
     try {
         await Promise.all(tests.map(async (testAbs) => {
@@ -312,6 +321,7 @@ export async function autoDiscoverTargetsAndTests(root, cfg) {
                 await crawl(abs, 0, seen, testAbs);
             }
         }));
+        onProgress?.(`Discovery complete: ${targets.size} source file(s), ${tests.length} test file(s)`);
         return { targets: Array.from(targets.values()), testMap, directTestMap };
     }
     finally {

package/dist/runner/jest/__tests__/pool.spec.js

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
+import { EventEmitter } from 'node:events';
 import { JestPool, runWithJestPool } from '../pool.js';
 // We'll use the createWorker option to inject mock workers instead of forking processes
 function makeMockWorker(id) {
@@ -110,6 +111,46 @@ describe('JestPool', () => {
         // After shutdown, initialised is set to false, so "not initialised" check fires first
         await expect(pool.run(dummyMutant, ['test.ts'])).rejects.toThrow('Pool not initialised');
     });
+    it('does not give a dead worker to a waiting task after timeout', async () => {
+        let callCount = 0;
+        const allWorkers = [];
+        const pool = new JestPool({
+            cwd: '/tmp',
+            concurrency: 1,
+            createWorker: (id) => {
+                callCount++;
+                const workerNum = callCount;
+                const worker = new EventEmitter();
+                worker.id = id;
+                worker._ready = true;
+                worker.start = vi.fn().mockResolvedValue(undefined);
+                worker.isReady = vi.fn(() => worker._ready);
+                worker.isBusy = vi.fn().mockReturnValue(false);
+                worker.run = vi.fn().mockImplementation(async () => {
+                    if (workerNum === 1) {
+                        worker._ready = false;
+                        Promise.resolve().then(() => worker.emit('exit'));
+                        return { killed: false, durationMs: 5000, error: 'timeout' };
+                    }
+                    return { killed: true, durationMs: 42 };
+                });
+                worker.shutdown = vi.fn().mockResolvedValue(undefined);
+                worker.kill = vi.fn();
+                allWorkers.push(worker);
+                return worker;
+            },
+        });
+        await pool.init();
+        const [result1, result2] = await Promise.all([
+            pool.run(dummyMutant, ['a.spec.ts']),
+            pool.run({ ...dummyMutant, id: 'test#2' }, ['b.spec.ts']),
+        ]);
+        expect(result1).toMatchObject({ error: 'timeout' });
+        expect(result2).toMatchObject({ killed: true });
+        expect(allWorkers).toHaveLength(2);
+        expect(allWorkers[1].run).toHaveBeenCalled();
+        await pool.shutdown();
+    });
     it('does not double-shutdown', async () => {
         const workers = [];
         const pool = new JestPool({

package/dist/runner/jest/pool.js

@@ -239,14 +239,14 @@ export class JestPool {
         });
     }
     releaseWorker(worker) {
+        if (!worker.isReady())
+            return;
         const waiting = this.waitingTasks.shift();
         if (waiting) {
             waiting(worker);
             return;
         }
-        if (worker.isReady()) {
-            this.availableWorkers.push(worker);
-        }
+        this.availableWorkers.push(worker);
     }
     async run(mutant, tests) {
         if (!this.initialised) {

package/dist/runner/orchestrator.d.ts

@@ -9,5 +9,6 @@
  * 5. Execute mutants via worker pool
  * 6. Report results
  */
+export declare function parseMutantTimeoutMs(raw: string | undefined): number;
 export { readMutantCache } from './cache.js';
 export declare function runOrchestrator(cliArgs: string[], cwd: string): Promise<void>;

package/dist/runner/orchestrator.js

@@ -26,11 +26,11 @@ import { prepareTasks } from './tasks.js';
 import { executePool } from './pool-executor.js';
 const log = createLogger('orchestrator');
 // Per-mutant test timeout (ms). Can be overridden with env MUTINEER_MUTANT_TIMEOUT_MS
-const MUTANT_TIMEOUT_MS = (() => {
-    const raw = process.env.MUTINEER_MUTANT_TIMEOUT_MS;
+export function parseMutantTimeoutMs(raw) {
     const n = raw ? Number(raw) : NaN;
     return Number.isFinite(n) && n > 0 ? n : 30_000;
-})();
+}
+const MUTANT_TIMEOUT_MS = parseMutantTimeoutMs(process.env.MUTINEER_MUTANT_TIMEOUT_MS);
 // Re-export readMutantCache for external use
 export { readMutantCache } from './cache.js';
 export async function runOrchestrator(cliArgs, cwd) {
@@ -38,12 +38,12 @@ export async function runOrchestrator(cliArgs, cwd) {
     const cfgPath = extractConfigPath(cliArgs);
     const cfg = await loadMutineerConfig(cwd, cfgPath);
     const opts = parseCliOptions(cliArgs, cfg);
-    await clearCacheOnStart(cwd);
+    await clearCacheOnStart(cwd, opts.shard);
     // Create test runner adapter
     const adapter = (opts.runner === 'jest' ? createJestAdapter : createVitestAdapter)({
         cwd,
         concurrency: opts.concurrency,
-        timeoutMs: MUTANT_TIMEOUT_MS,
+        timeoutMs: opts.timeout ?? cfg.timeout ?? MUTANT_TIMEOUT_MS,
         config: cfg,
         cliArgs,
     });
@@ -66,8 +66,9 @@ export async function runOrchestrator(cliArgs, cwd) {
         }))
         : null;
     // 4. Discover targets and tests
-    const cache = await readMutantCache(cwd);
-    const discovered = await autoDiscoverTargetsAndTests(cwd, cfg);
+    const cache = await readMutantCache(cwd, opts.shard);
+    log.info('Discovering tests...');
+    const discovered = await autoDiscoverTargetsAndTests(cwd, cfg, (msg) => log.info(msg));
     const { testMap, directTestMap } = discovered;
     const targets = cfg.targets?.length
         ? [...cfg.targets]
@@ -88,8 +89,24 @@ export async function runOrchestrator(cliArgs, cwd) {
         }
     }
     const baselineTests = Array.from(allTestFiles);
+    if (opts.wantsChangedWithDeps) {
+        let uncoveredCount = 0;
+        for (const target of targets) {
+            const absFile = normalizePath(path.isAbsolute(getTargetFile(target))
+                ? getTargetFile(target)
+                : path.join(cwd, getTargetFile(target)));
+            if (changedAbs?.has(absFile) &&
+                !testMap.get(normalizePath(absFile))?.size) {
+                uncoveredCount++;
+            }
+        }
+        if (uncoveredCount > 0) {
+            log.info(`${uncoveredCount} target(s) from --changed-with-deps have no covering tests and will be skipped`);
+        }
+    }
     if (!baselineTests.length) {
-        log.info('No tests found for targets. Exiting.');
+        log.error('No tests found for the selected targets. Ensure your source files are covered by at least one test file.');
+        process.exitCode = 1;
         return;
     }
     // 5. Run baseline tests (with coverage if needed for filtering)
@@ -122,7 +139,17 @@ export async function runOrchestrator(cliArgs, cwd) {
         return;
     }
     // 8. Prepare tasks and execute via worker pool
-    const tasks = prepareTasks(variants, updatedCoverage.perTestCoverage, directTestMap);
+    let tasks = prepareTasks(variants, updatedCoverage.perTestCoverage, directTestMap);
+    // Apply shard filter if requested
+    if (opts.shard) {
+        const { index, total } = opts.shard;
+        tasks = tasks.filter((_, i) => i % total === index - 1);
+        log.info(`Shard ${index}/${total}: running ${tasks.length} mutant(s)`);
+        if (tasks.length === 0) {
+            log.info('No mutants assigned to this shard. Exiting.');
+            return;
+        }
+    }
     await executePool({
         tasks,
         adapter,
@@ -130,6 +157,8 @@ export async function runOrchestrator(cliArgs, cwd) {
         concurrency: opts.concurrency,
         progressMode: opts.progressMode,
         minKillPercent: opts.minKillPercent,
+        reportFormat: opts.reportFormat,
         cwd,
+        shard: opts.shard,
     });
 }

package/dist/runner/pool-executor.d.ts

@@ -8,7 +8,12 @@ export interface PoolExecutionOptions {
     concurrency: number;
     progressMode: 'bar' | 'list' | 'quiet';
     minKillPercent?: number;
+    reportFormat?: 'text' | 'json';
     cwd: string;
+    shard?: {
+        index: number;
+        total: number;
+    };
 }
 /**
  * Execute all mutant tasks through the worker pool.

package/dist/runner/pool-executor.js

@@ -1,8 +1,9 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import { render } from 'ink';
 import { createElement } from 'react';
 import { Progress } from '../utils/progress.js';
-import { computeSummary, printSummary } from '../utils/summary.js';
+import { computeSummary, printSummary, buildJsonReport, } from '../utils/summary.js';
 import { saveCacheAtomic } from './cache.js';
 import { cleanupMutineerDirs } from './cleanup.js';
 import { PoolSpinner } from '../utils/PoolSpinner.js';
@@ -29,7 +30,18 @@ export async function executePool(opts) {
         const durationMs = Date.now() - mutationStartTime;
         progress.finish();
         const summary = computeSummary(cache);
-        printSummary(summary, cache, durationMs);
+        if (opts.reportFormat === 'json') {
+            const report = buildJsonReport(summary, cache, durationMs);
+            const shardSuffix = opts.shard
+                ? `-shard-${opts.shard.index}-of-${opts.shard.total}`
+                : '';
+            const outPath = path.join(opts.cwd, `mutineer-report${shardSuffix}.json`);
+            fs.writeFileSync(outPath, JSON.stringify(report, null, 2));
+            log.info(`JSON report written to ${path.relative(process.cwd(), outPath)}`);
+        }
+        else {
+            printSummary(summary, cache, durationMs);
+        }
         if (opts.minKillPercent !== undefined) {
             const killRateString = summary.killRate.toFixed(2);
             const thresholdString = opts.minKillPercent.toFixed(2);
@@ -68,7 +80,6 @@ export async function executePool(opts) {
     let nextIdx = 0;
     async function processTask(task) {
         const { v, tests, key, directTests } = task;
-        log.debug('Cache ' + JSON.stringify(cache));
         const cached = cache[key];
         if (cached) {
             progress.update(cached.status);
@@ -159,7 +170,7 @@ export async function executePool(opts) {
         for (let i = 0; i < workerCount; i++)
             workers.push(worker());
         await Promise.all(workers);
-        await saveCacheAtomic(cwd, cache);
+        await saveCacheAtomic(cwd, cache, opts.shard);
     }
     finally {
         process.removeAllListeners('SIGINT');

package/dist/runner/vitest/__tests__/adapter.spec.js

@@ -103,6 +103,40 @@ describe('Vitest adapter', () => {
         expect(args.join(' ')).toContain('--coverage.enabled=true');
         expect(args.join(' ')).toContain('--coverage.perTest=true');
     });
+    it('disables coverage thresholds in baseline-with-coverage to prevent threshold failures', async () => {
+        const adapter = makeAdapter({ cliArgs: [] });
+        spawnMock.mockImplementationOnce(() => ({
+            on: (evt, cb) => {
+                if (evt === 'exit')
+                    cb(0);
+            },
+        }));
+        await adapter.runBaseline(['test-a'], {
+            collectCoverage: true,
+            perTestCoverage: false,
+        });
+        const args = spawnMock.mock.calls[0][1];
+        const argStr = args.join(' ');
+        expect(argStr).toContain('--coverage.thresholds.lines=0');
+        expect(argStr).toContain('--coverage.thresholds.functions=0');
+        expect(argStr).toContain('--coverage.thresholds.branches=0');
+        expect(argStr).toContain('--coverage.thresholds.statements=0');
+    });
+    it('strips --shard= flag from vitest args', async () => {
+        const adapter = makeAdapter({ cliArgs: ['--shard=1/4'] });
+        spawnMock.mockImplementationOnce(() => ({
+            on: (evt, cb) => {
+                if (evt === 'exit')
+                    cb(0);
+            },
+        }));
+        await adapter.runBaseline(['test-a'], {
+            collectCoverage: false,
+            perTestCoverage: false,
+        });
+        const args = spawnMock.mock.calls[0][1];
+        expect(args.join(' ')).not.toContain('--shard');
+    });
     it('detects coverage config from vitest config file', async () => {
         const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-vitest-'));
         const cfgPath = path.join(tmp, 'vitest.config.ts');
@@ -121,6 +155,32 @@ describe('Vitest adapter', () => {
         }
     });
 });
+describe('hasCoverageProvider', () => {
+    it('returns true when @vitest/coverage-v8 is resolvable', () => {
+        const adapter = makeAdapter({ cwd: process.cwd() });
+        // coverage-v8 is installed as a devDependency, so this must resolve
+        expect(adapter.hasCoverageProvider()).toBe(true);
+    });
+    it('returns false when neither provider is resolvable', () => {
+        const adapter = makeAdapter({ cwd: '/tmp' });
+        expect(adapter.hasCoverageProvider()).toBe(false);
+    });
+    it('returns true when @vitest/coverage-istanbul is resolvable', () => {
+        const adapter = makeAdapter({ cwd: process.cwd() });
+        const origResolve = require.resolve;
+        const resolveStub = vi
+            .spyOn(require, 'resolve')
+            .mockImplementation((id, opts) => {
+            if (String(id).includes('coverage-v8'))
+                throw new Error('not found');
+            if (String(id).includes('coverage-istanbul'))
+                return '/fake/path';
+            return origResolve(id, opts);
+        });
+        expect(adapter.hasCoverageProvider()).toBe(true);
+        resolveStub.mockRestore();
+    });
+});
 describe('isCoverageRequestedInArgs', () => {
     it('detects enabled coverage flags', () => {
         expect(isCoverageRequestedInArgs(['--coverage'])).toBe(true);

package/dist/runner/vitest/__tests__/pool.spec.js

@@ -88,6 +88,63 @@ describe('VitestPool', () => {
         expect(result).toEqual({ status: 'escaped', durationMs: 7 });
         expect(mockPool.run).toHaveBeenCalledWith(mutant, ['bar.spec.ts']);
     });
+    it('does not give a dead worker to a waiting task after timeout', async () => {
+        let callCount = 0;
+        const allWorkers = [];
+        const pool = new VitestPool({
+            cwd: process.cwd(),
+            concurrency: 1,
+            timeoutMs: 5000,
+            createWorker: (id) => {
+                callCount++;
+                const workerNum = callCount;
+                const worker = new EventEmitter();
+                worker.id = id;
+                worker._ready = true;
+                worker.start = vi.fn().mockResolvedValue(undefined);
+                worker.isReady = vi.fn(() => worker._ready);
+                worker.isBusy = vi.fn().mockReturnValue(false);
+                worker.run = vi.fn().mockImplementation(async () => {
+                    if (workerNum === 1) {
+                        worker._ready = false;
+                        Promise.resolve().then(() => worker.emit('exit'));
+                        return { killed: false, durationMs: 5000, error: 'timeout' };
+                    }
+                    return { killed: true, durationMs: 42 };
+                });
+                worker.shutdown = vi.fn().mockResolvedValue(undefined);
+                worker.kill = vi.fn();
+                allWorkers.push(worker);
+                return worker;
+            },
+        });
+        await pool.init();
+        const mutant1 = {
+            id: '1',
+            name: 'm1',
+            file: 'a.ts',
+            code: 'x',
+            line: 1,
+            col: 1,
+        };
+        const mutant2 = {
+            id: '2',
+            name: 'm2',
+            file: 'b.ts',
+            code: 'y',
+            line: 1,
+            col: 1,
+        };
+        const [result1, result2] = await Promise.all([
+            pool.run(mutant1, ['a.spec.ts']),
+            pool.run(mutant2, ['b.spec.ts']),
+        ]);
+        expect(result1).toMatchObject({ error: 'timeout' });
+        expect(result2).toMatchObject({ killed: true });
+        expect(allWorkers).toHaveLength(2);
+        expect(allWorkers[1].run).toHaveBeenCalled();
+        await pool.shutdown();
+    });
     it('maps runWithPool errors to error status', async () => {
         const mockPool = {
             run: vi.fn().mockRejectedValue(new Error('boom')),

package/dist/runner/vitest/adapter.js

@@ -37,6 +37,7 @@ function stripMutineerArgs(args) {
         '--config',
         '-c',
         '--coverage-file',
+        '--shard',
     ]);
     const dropExact = new Set([
         '-m',
@@ -59,6 +60,8 @@ function stripMutineerArgs(args) {
             continue;
         if (a.startsWith('--config=') || a.startsWith('-c='))
             continue;
+        if (a.startsWith('--shard='))
+            continue;
         out.push(a);
     }
     return out;
@@ -96,6 +99,9 @@ function buildVitestArgs(args, mode) {
         if (!result.some((a) => a.startsWith('--coverage.perTest='))) {
             result.push('--coverage.perTest=true');
         }
+        // Disable coverage thresholds so baseline doesn't fail when a broader
+        // test set (e.g. from --changed-with-deps) lowers aggregate coverage
+        result.push('--coverage.thresholds.lines=0', '--coverage.thresholds.functions=0', '--coverage.thresholds.branches=0', '--coverage.thresholds.statements=0');
     }
     return result;
 }
@@ -193,15 +199,16 @@ export class VitestAdapter {
         }
     }
     hasCoverageProvider() {
-        try {
-            require.resolve('@vitest/coverage-v8/package.json', {
-                paths: [this.options.cwd],
-            });
-            return true;
-        }
-        catch {
-            return false;
-        }
+        const packages = ['@vitest/coverage-v8', '@vitest/coverage-istanbul'];
+        return packages.some((pkg) => {
+            try {
+                require.resolve(`${pkg}/package.json`, { paths: [this.options.cwd] });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
     }
     async detectCoverageConfig() {
         const configPath = this.options.config.vitestConfig;

package/dist/runner/vitest/pool.js

@@ -301,6 +301,8 @@ export class VitestPool {
         });
     }
     releaseWorker(worker) {
+        if (!worker.isReady())
+            return;
         // If someone is waiting, give them the worker directly
         const waiting = this.waitingTasks.shift();
         if (waiting) {
@@ -308,9 +310,7 @@ export class VitestPool {
             return;
         }
         // Otherwise return to the pool
-        if (worker.isReady()) {
-            this.availableWorkers.push(worker);
-        }
+        this.availableWorkers.push(worker);
     }
     async run(mutant, tests) {
         if (!this.initialised) {

package/dist/types/config.d.ts

@@ -38,4 +38,8 @@ export interface MutineerConfig {
      * Requires Vitest coverage with perTest support.
      */
     readonly perTestCoverage?: boolean;
+    /** Per-mutant test timeout in milliseconds (default: 30000) */
+    readonly timeout?: number;
+    /** Output report format: 'text' (default) or 'json' (writes mutineer-report.json) */
+    readonly report?: 'text' | 'json';
 }

package/dist/utils/__tests__/summary.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { computeSummary, printSummary, summarise } from '../summary.js';
+import { computeSummary, printSummary, summarise, buildJsonReport, } from '../summary.js';
 /** Strip ANSI escape codes for clean text assertions */
 const stripAnsi = (s) => s.replace(/\x1B\[[0-9;]*m/g, '');
 function makeEntry(overrides) {
@@ -97,6 +97,48 @@ describe('summary', () => {
         expect(lines.some((l) => l.includes('↳'))).toBe(false);
         logSpy.mockRestore();
     });
+    it('buildJsonReport includes schemaVersion, timestamp, summary, and mutants', () => {
+        const cache = {
+            a: makeEntry({ status: 'killed', file: '/tmp/a.ts', mutator: 'flip' }),
+            b: makeEntry({ status: 'escaped', file: '/tmp/b.ts', mutator: 'wrap' }),
+        };
+        const summary = computeSummary(cache);
+        const report = buildJsonReport(summary, cache, 1000);
+        expect(report.schemaVersion).toBe(1);
+        expect(typeof report.timestamp).toBe('string');
+        expect(report.durationMs).toBe(1000);
+        expect(report.summary).toEqual(summary);
+        expect(report.mutants).toHaveLength(2);
+    });
+    it('buildJsonReport mutant entries have required fields', () => {
+        const cache = {
+            a: makeEntry({
+                status: 'escaped',
+                file: '/tmp/a.ts',
+                mutator: 'flip',
+                originalSnippet: 'a === b',
+                mutatedSnippet: 'a !== b',
+                coveringTests: ['/tmp/a.spec.ts'],
+            }),
+        };
+        const summary = computeSummary(cache);
+        const report = buildJsonReport(summary, cache);
+        const mutant = report.mutants[0];
+        expect(mutant.file).toBe('/tmp/a.ts');
+        expect(mutant.status).toBe('escaped');
+        expect(mutant.mutator).toBe('flip');
+        expect(mutant.originalSnippet).toBe('a === b');
+        expect(mutant.mutatedSnippet).toBe('a !== b');
+        expect(mutant.coveringTests).toEqual(['/tmp/a.spec.ts']);
+    });
+    it('buildJsonReport omits optional fields when absent', () => {
+        const cache = { a: makeEntry({ status: 'killed' }) };
+        const summary = computeSummary(cache);
+        const report = buildJsonReport(summary, cache);
+        expect('durationMs' in report).toBe(false);
+        expect('originalSnippet' in report.mutants[0]).toBe(false);
+        expect('coveringTests' in report.mutants[0]).toBe(false);
+    });
     it('summarise returns summary and prints', () => {
         const cache = { a: makeEntry({ status: 'killed' }) };
         const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });