@mutineerjs/mutineer 0.5.0 → 0.6.0

package/dist/mutators/utils.js

@@ -122,21 +122,86 @@ export function isBinaryOrLogical(node) {
     return node.type === 'BinaryExpression' || node.type === 'LogicalExpression';
 }
 /**
- * Collect the operator tokens for a given operator and return their exact locations.
- * Uses AST traversal to find BinaryExpression/LogicalExpression nodes, then maps them
- * to token positions for accurate column reporting.
- *
- * @param src - The source code
- * @param opValue - The operator to search for (e.g., '&&', '<=')
- * @returns Array of target locations for the operator
+ * Single traversal that collects all operator targets and return statements.
+ * Eliminates per-mutator traversals when using ParseContext.
  */
-export function collectOperatorTargets(src, opValue) {
+export function collectAllTargets(src, ast, tokens, ignoreLines) {
+    const operatorTargets = new Map();
+    const returnStatements = [];
+    function handleBinaryOrLogical(n) {
+        const nodeStart = n.start ?? 0;
+        const nodeEnd = n.end ?? 0;
+        const opValue = n.operator;
+        const tok = tokens.find((tk) => tk.start >= nodeStart && tk.end <= nodeEnd && tk.value === opValue);
+        if (tok) {
+            const line = tok.loc.start.line;
+            if (ignoreLines.has(line))
+                return;
+            const visualCol = getVisualColumn(src, tok.start);
+            let arr = operatorTargets.get(opValue);
+            if (!arr) {
+                arr = [];
+                operatorTargets.set(opValue, arr);
+            }
+            arr.push({
+                start: tok.start,
+                end: tok.end,
+                line,
+                col1: visualCol,
+                op: opValue,
+            });
+        }
+    }
+    traverse(ast, {
+        BinaryExpression(p) {
+            handleBinaryOrLogical(p.node);
+        },
+        LogicalExpression(p) {
+            handleBinaryOrLogical(p.node);
+        },
+        ReturnStatement(p) {
+            const node = p.node;
+            if (!node.argument)
+                return;
+            const line = node.loc?.start.line;
+            if (line === undefined)
+                return;
+            if (ignoreLines.has(line))
+                return;
+            const argStart = node.argument.start;
+            const argEnd = node.argument.end;
+            if (argStart == null || argEnd == null)
+                return;
+            const col = getVisualColumn(src, node.start ?? 0);
+            returnStatements.push({
+                line,
+                col,
+                argStart,
+                argEnd,
+                argNode: node.argument,
+            });
+        },
+    });
+    return { operatorTargets, returnStatements };
+}
+/**
+ * Parse a source file once and build a reusable ParseContext.
+ * Pass this to mutators' applyWithContext to avoid redundant parses.
+ */
+export function buildParseContext(src) {
     const ast = parseSource(src);
-    const fileAst = ast;
-    const tokens = fileAst.tokens ?? [];
-    const comments = fileAst.comments ?? [];
+    const tokens = ast.tokens ?? [];
+    const ignoreLines = buildIgnoreLines(ast.comments ?? []);
+    const preCollected = collectAllTargets(src, ast, tokens, ignoreLines);
+    return { ast, tokens, ignoreLines, preCollected };
+}
+/**
+ * Collect operator targets from a pre-built ParseContext.
+ * Avoids re-parsing; use when processing multiple operators on the same source.
+ */
+export function collectOperatorTargetsFromContext(src, ctx, opValue) {
+    const { ast, tokens, ignoreLines } = ctx;
     const out = [];
-    const ignoreLines = buildIgnoreLines(comments);
     traverse(ast, {
         enter(p) {
             if (!isBinaryOrLogical(p.node))
@@ -144,12 +209,10 @@ export function collectOperatorTargets(src, opValue) {
             const n = p.node;
             if (n.operator !== opValue)
                 return;
-            // Find the exact operator token inside the node span
             const nodeStart = n.start ?? 0;
             const nodeEnd = n.end ?? 0;
             const tok = tokens.find((tk) => tk.start >= nodeStart && tk.end <= nodeEnd && tk.value === opValue);
             if (tok) {
-                // Convert Babel's character-based column to a visual column for accurate reporting
                 const line = tok.loc.start.line;
                 if (ignoreLines.has(line))
                     return;
@@ -158,7 +221,7 @@ export function collectOperatorTargets(src, opValue) {
                     start: tok.start,
                     end: tok.end,
                     line,
-                    col1: visualCol, // convert to 1-based
+                    col1: visualCol,
                     op: opValue,
                 });
             }
@@ -166,3 +229,15 @@ export function collectOperatorTargets(src, opValue) {
     });
     return out;
 }
+/**
+ * Collect the operator tokens for a given operator and return their exact locations.
+ * Uses AST traversal to find BinaryExpression/LogicalExpression nodes, then maps them
+ * to token positions for accurate column reporting.
+ *
+ * @param src - The source code
+ * @param opValue - The operator to search for (e.g., '&&', '<=')
+ * @returns Array of target locations for the operator
+ */
+export function collectOperatorTargets(src, opValue) {
+    return collectOperatorTargetsFromContext(src, buildParseContext(src), opValue);
+}

package/dist/runner/__tests__/args.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseFlagNumber, readNumberFlag, readStringFlag, validatePercent, parseConcurrency, parseProgressMode, parseCliOptions, extractConfigPath, } from '../args.js';
+import { parseFlagNumber, readNumberFlag, readStringFlag, validatePercent, validatePositiveMs, parseConcurrency, parseProgressMode, parseCliOptions, extractConfigPath, } from '../args.js';
 describe('parseFlagNumber', () => {
     it('parses valid integers', () => {
         expect(parseFlagNumber('42', '--flag')).toBe(42);
@@ -202,6 +202,50 @@ describe('parseCliOptions', () => {
     it('rejects invalid --min-kill-percent', () => {
         expect(() => parseCliOptions(['--min-kill-percent', '150'], emptyCfg)).toThrow('expected value between 0 and 100');
     });
+    it('parses --timeout flag', () => {
+        const opts = parseCliOptions(['--timeout', '5000'], emptyCfg);
+        expect(opts.timeout).toBe(5000);
+    });
+    it('parses --timeout with = syntax', () => {
+        const opts = parseCliOptions(['--timeout=5000'], emptyCfg);
+        expect(opts.timeout).toBe(5000);
+    });
+    it('returns undefined timeout when flag absent', () => {
+        const opts = parseCliOptions([], emptyCfg);
+        expect(opts.timeout).toBeUndefined();
+    });
+    it('config timeout does not affect opts.timeout (resolved in orchestrator)', () => {
+        const opts = parseCliOptions([], { timeout: 10000 });
+        expect(opts.timeout).toBeUndefined();
+    });
+    it('rejects --timeout 0', () => {
+        expect(() => parseCliOptions(['--timeout', '0'], emptyCfg)).toThrow('expected a positive number');
+    });
+    it('rejects --timeout -1', () => {
+        expect(() => parseCliOptions(['--timeout', '-1'], emptyCfg)).toThrow('expected a positive number');
+    });
+    it('rejects --timeout abc', () => {
+        expect(() => parseCliOptions(['--timeout', 'abc'], emptyCfg)).toThrow('Invalid value for --timeout: abc');
+    });
+});
+describe('validatePositiveMs', () => {
+    it('returns undefined for undefined', () => {
+        expect(validatePositiveMs(undefined, 'test')).toBeUndefined();
+    });
+    it('returns the value for a positive number', () => {
+        expect(validatePositiveMs(5000, '--timeout')).toBe(5000);
+        expect(validatePositiveMs(1, '--timeout')).toBe(1);
+    });
+    it('throws for zero', () => {
+        expect(() => validatePositiveMs(0, '--timeout')).toThrow('Invalid --timeout: expected a positive number (received 0)');
+    });
+    it('throws for negative values', () => {
+        expect(() => validatePositiveMs(-1, '--timeout')).toThrow('Invalid --timeout: expected a positive number (received -1)');
+    });
+    it('throws for non-finite values', () => {
+        expect(() => validatePositiveMs(Infinity, '--timeout')).toThrow('Invalid --timeout: expected a positive number');
+        expect(() => validatePositiveMs(NaN, '--timeout')).toThrow('Invalid --timeout: expected a positive number');
+    });
 });
 describe('extractConfigPath', () => {
     it('extracts --config with separate value', () => {

package/dist/runner/__tests__/changed.spec.js

@@ -145,11 +145,94 @@ describe('listChangedFiles', () => {
             }
             return { status: 0, stdout: '' };
         });
-        // File with imports - the import resolution will fail (no real files)
-        // but it exercises the parsing code paths
         readFileSyncMock.mockReturnValue('import { bar } from "./bar"\nexport { baz } from "./baz"\nconst x = require("./qux")');
+        existsSyncMock.mockImplementation((p) => {
+            // Changed file and .ts variants of deps exist
+            return [
+                '/repo/src/foo.ts',
+                '/repo/src/bar.ts',
+                '/repo/src/baz.ts',
+                '/repo/src/qux.ts',
+            ].includes(p);
+        });
         const result = listChangedFiles('/repo', { includeDeps: true });
         expect(result).toContain('/repo/src/foo.ts');
+        expect(result).toContain('/repo/src/bar.ts');
+        expect(result).toContain('/repo/src/baz.ts');
+        expect(result).toContain('/repo/src/qux.ts');
+    });
+    it('resolves dep with .ts extension when imported without extension', () => {
+        spawnSyncMock.mockImplementation((_cmd, args) => {
+            if (args.includes('--show-toplevel'))
+                return { status: 0, stdout: '/repo\n' };
+            if (args.includes('main...HEAD'))
+                return { status: 0, stdout: 'src/foo.ts\0' };
+            return { status: 0, stdout: '' };
+        });
+        readFileSyncMock.mockReturnValue('import { x } from "./utils"');
+        existsSyncMock.mockImplementation((p) => {
+            return ['/repo/src/foo.ts', '/repo/src/utils.ts'].includes(p);
+        });
+        const result = listChangedFiles('/repo', { includeDeps: true });
+        expect(result).toContain('/repo/src/utils.ts');
+    });
+    it('excludes deps outside cwd', () => {
+        spawnSyncMock.mockImplementation((_cmd, args) => {
+            if (args.includes('--show-toplevel'))
+                return { status: 0, stdout: '/repo\n' };
+            if (args.includes('main...HEAD'))
+                return { status: 0, stdout: 'src/foo.ts\0' };
+            return { status: 0, stdout: '' };
+        });
+        readFileSyncMock.mockReturnValue('import { x } from "../../outside/dep"');
+        existsSyncMock.mockImplementation((p) => {
+            return ['/repo/src/foo.ts', '/outside/dep.ts'].includes(p);
+        });
+        const result = listChangedFiles('/repo', { includeDeps: true });
+        expect(result).not.toContain('/outside/dep.ts');
+        expect(result).toHaveLength(1);
+    });
+    it('excludes deps inside node_modules', () => {
+        spawnSyncMock.mockImplementation((_cmd, args) => {
+            if (args.includes('--show-toplevel'))
+                return { status: 0, stdout: '/repo\n' };
+            if (args.includes('main...HEAD'))
+                return { status: 0, stdout: 'src/foo.ts\0' };
+            return { status: 0, stdout: '' };
+        });
+        readFileSyncMock.mockReturnValue('import { x } from "./node_modules/pkg/index"');
+        existsSyncMock.mockImplementation((p) => {
+            return p === '/repo/src/foo.ts' || p.includes('node_modules');
+        });
+        const result = listChangedFiles('/repo', { includeDeps: true });
+        expect(result.some((p) => p.includes('node_modules'))).toBe(false);
+    });
+    it('resolves direct dep but not transitive dep at maxDepth=1', () => {
+        spawnSyncMock.mockImplementation((_cmd, args) => {
+            if (args.includes('--show-toplevel'))
+                return { status: 0, stdout: '/repo\n' };
+            if (args.includes('main...HEAD'))
+                return { status: 0, stdout: 'src/foo.ts\0' };
+            return { status: 0, stdout: '' };
+        });
+        readFileSyncMock.mockImplementation((p) => {
+            if (p === '/repo/src/foo.ts')
+                return 'import { x } from "./bar"';
+            if (p === '/repo/src/bar.ts')
+                return 'import { y } from "./baz"';
+            return '';
+        });
+        existsSyncMock.mockImplementation((p) => {
+            return [
+                '/repo/src/foo.ts',
+                '/repo/src/bar.ts',
+                '/repo/src/baz.ts',
+            ].includes(p);
+        });
+        const result = listChangedFiles('/repo', { includeDeps: true, maxDepth: 1 });
+        expect(result).toContain('/repo/src/foo.ts');
+        expect(result).toContain('/repo/src/bar.ts');
+        expect(result).not.toContain('/repo/src/baz.ts');
     });
     it('skips non-local imports in dependency resolution', () => {
         spawnSyncMock.mockImplementation((_cmd, args) => {

package/dist/runner/__tests__/config.spec.js

@@ -52,20 +52,9 @@ describe('loadMutineerConfig', () => {
         await fs.writeFile(configFile, '??? not valid javascript ???');
         await expect(loadMutineerConfig(tmpDir)).rejects.toThrow(/Failed to load config from/);
     });
-    // BUG: Two bugs compound here:
-    // 1. validateConfig uses `&&` instead of `||`: `typeof config !== 'object' && config === null`
-    //    Since typeof null === 'object', this condition is always false, so null passes validation.
-    // 2. loadModule uses `||` instead of `??`: `mod.default || mod`
-    //    When default export is null (falsy), it falls back to the module namespace object.
-    // Together: null configs pass validation AND get returned as the module namespace.
-    it('BUG: null config passes validation due to && vs || logic error', async () => {
+    it('throws when config exports null', async () => {
         const configFile = path.join(tmpDir, 'mutineer.config.mjs');
         await fs.writeFile(configFile, 'export default null');
-        // This SHOULD throw but doesn't because of the validateConfig bug.
-        // Additionally, loadModule returns { default: null } instead of null
-        // because it uses || (which treats null as falsy) instead of ??
-        const config = await loadMutineerConfig(tmpDir);
-        // Bug: returns the module namespace object instead of throwing
-        expect(config).toHaveProperty('default', null);
+        await expect(loadMutineerConfig(tmpDir)).rejects.toThrow('does not export a valid configuration object');
     });
 });

package/dist/runner/__tests__/coverage-resolver.spec.js

@@ -15,6 +15,7 @@ function makeOpts(overrides = {}) {
         progressMode: 'bar',
         minKillPercent: undefined,
         runner: 'vitest',
+        timeout: undefined,
         ...overrides,
     };
 }
@@ -62,7 +63,9 @@ describe('resolveCoverageConfig', () => {
     });
     it('sets exitCode when onlyCoveredLines is set but no coverage provider', async () => {
         const opts = makeOpts({ wantsOnlyCoveredLines: true });
-        const adapter = makeAdapter({ hasCoverageProvider: vi.fn().mockReturnValue(false) });
+        const adapter = makeAdapter({
+            hasCoverageProvider: vi.fn().mockReturnValue(false),
+        });
         await resolveCoverageConfig(opts, {}, adapter, []);
         expect(process.exitCode).toBe(1);
     });
@@ -129,7 +132,9 @@ describe('loadCoverageAfterBaseline', () => {
         const coverageJson = {
             '/src/foo.ts': {
                 path: '/src/foo.ts',
-                statementMap: { '0': { start: { line: 1, column: 0 }, end: { line: 1, column: 10 } } },
+                statementMap: {
+                    '0': { start: { line: 1, column: 0 }, end: { line: 1, column: 10 } },
+                },
                 s: { '0': 1 },
             },
         };

package/dist/runner/__tests__/discover.spec.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -34,6 +34,57 @@ vi.mock('vite', async () => {
         }),
     };
 });
+describe('createViteResolver Vue plugin gating', () => {
+    let warnSpy;
+    beforeEach(() => {
+        warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('does not warn about @vitejs/plugin-vue when no .vue files exist', async () => {
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-discover-novue-'));
+        const srcDir = path.join(tmpDir, 'src');
+        await fs.mkdir(srcDir, { recursive: true });
+        await fs.writeFile(path.join(srcDir, 'a.ts'), 'export const a = 1\n', 'utf8');
+        const importLine = ['im', 'port { a } from "./a"'].join('');
+        await fs.writeFile(path.join(srcDir, 'a.test.ts'), `${importLine}\n`, 'utf8');
+        try {
+            await autoDiscoverTargetsAndTests(tmpDir, {
+                testPatterns: ['**/*.test.ts'],
+            });
+            const pluginVueWarnings = warnSpy.mock.calls.filter((args) => String(args[0]).includes('plugin-vue'));
+            expect(pluginVueWarnings).toHaveLength(0);
+        }
+        finally {
+            await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    it('warns when .vue files exist but @vitejs/plugin-vue fails to load', async () => {
+        vi.doMock('@vitejs/plugin-vue', () => {
+            throw new Error('Cannot find module @vitejs/plugin-vue');
+        });
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-discover-vue-'));
+        const srcDir = path.join(tmpDir, 'src');
+        await fs.mkdir(srcDir, { recursive: true });
+        await fs.writeFile(path.join(srcDir, 'Comp.vue'), '<template><div/></template>\n', 'utf8');
+        await fs.writeFile(path.join(srcDir, 'a.ts'), 'export const a = 1\n', 'utf8');
+        const importLine = ['im', 'port { a } from "./a"'].join('');
+        await fs.writeFile(path.join(srcDir, 'a.test.ts'), `${importLine}\n`, 'utf8');
+        try {
+            await autoDiscoverTargetsAndTests(tmpDir, {
+                testPatterns: ['**/*.test.ts'],
+                extensions: ['.vue', '.ts'],
+            });
+            const pluginVueWarnings = warnSpy.mock.calls.filter((args) => String(args[0]).includes('plugin-vue'));
+            expect(pluginVueWarnings.length).toBeGreaterThan(0);
+        }
+        finally {
+            vi.doUnmock('@vitejs/plugin-vue');
+            await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
 describe('autoDiscoverTargetsAndTests', () => {
     it('directTestMap only includes direct importers', async () => {
         const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-discover-direct-'));

package/dist/runner/__tests__/orchestrator.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runner/__tests__/orchestrator.spec.js

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+// Mock all heavy dependencies before importing orchestrator
+vi.mock('../config.js', () => ({
+    loadMutineerConfig: vi.fn(),
+}));
+vi.mock('../cache.js', () => ({
+    clearCacheOnStart: vi.fn().mockResolvedValue(undefined),
+    readMutantCache: vi.fn().mockResolvedValue({}),
+}));
+vi.mock('../vitest/index.js', () => ({
+    createVitestAdapter: vi.fn(),
+}));
+vi.mock('../jest/index.js', () => ({
+    createJestAdapter: vi.fn(),
+}));
+vi.mock('../coverage-resolver.js', () => ({
+    resolveCoverageConfig: vi.fn().mockResolvedValue({
+        enableCoverageForBaseline: false,
+        wantsPerTestCoverage: false,
+        coverageData: null,
+    }),
+    loadCoverageAfterBaseline: vi.fn().mockResolvedValue({
+        coverageData: null,
+        perTestCoverage: null,
+    }),
+}));
+vi.mock('../discover.js', () => ({
+    autoDiscoverTargetsAndTests: vi.fn().mockResolvedValue({
+        targets: [],
+        testMap: new Map(),
+        directTestMap: new Map(),
+    }),
+}));
+vi.mock('../changed.js', () => ({
+    listChangedFiles: vi.fn().mockReturnValue([]),
+}));
+import { runOrchestrator } from '../orchestrator.js';
+import { loadMutineerConfig } from '../config.js';
+import { createVitestAdapter } from '../vitest/index.js';
+import { autoDiscoverTargetsAndTests } from '../discover.js';
+import { listChangedFiles } from '../changed.js';
+const mockAdapter = {
+    name: 'vitest',
+    init: vi.fn().mockResolvedValue(undefined),
+    runBaseline: vi.fn().mockResolvedValue(true),
+    runMutant: vi.fn().mockResolvedValue({ status: 'killed', durationMs: 10 }),
+    shutdown: vi.fn().mockResolvedValue(undefined),
+    hasCoverageProvider: vi.fn().mockReturnValue(false),
+    detectCoverageConfig: vi
+        .fn()
+        .mockResolvedValue({ perTestEnabled: false, coverageEnabled: false }),
+};
+beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(createVitestAdapter).mockReturnValue(mockAdapter);
+});
+describe('runOrchestrator --changed-with-deps diagnostic', () => {
+    it('logs uncovered targets when wantsChangedWithDeps is true', async () => {
+        const cfg = {};
+        vi.mocked(loadMutineerConfig).mockResolvedValue(cfg);
+        const depFile = '/cwd/src/dep.ts';
+        vi.mocked(listChangedFiles).mockReturnValue([depFile]);
+        vi.mocked(autoDiscoverTargetsAndTests).mockResolvedValue({
+            targets: [depFile],
+            testMap: new Map(), // dep has no covering tests
+            directTestMap: new Map(),
+        });
+        const consoleSpy = vi.spyOn(console, 'log');
+        await runOrchestrator(['--changed-with-deps'], '/cwd');
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('1 target(s) from --changed-with-deps have no covering tests and will be skipped'));
+    });
+    it('does not log when all changed-with-deps targets have covering tests', async () => {
+        const cfg = {};
+        vi.mocked(loadMutineerConfig).mockResolvedValue(cfg);
+        const depFile = '/cwd/src/dep.ts';
+        const testFile = '/cwd/src/__tests__/dep.spec.ts';
+        vi.mocked(listChangedFiles).mockReturnValue([depFile]);
+        vi.mocked(autoDiscoverTargetsAndTests).mockResolvedValue({
+            targets: [depFile],
+            testMap: new Map([[depFile, new Set([testFile])]]),
+            directTestMap: new Map(),
+        });
+        vi.mocked(mockAdapter.runBaseline).mockResolvedValue(true);
+        const consoleSpy = vi.spyOn(console, 'log');
+        await runOrchestrator(['--changed-with-deps'], '/cwd');
+        const diagnosticCalls = consoleSpy.mock.calls.filter(([msg]) => typeof msg === 'string' && msg.includes('have no covering tests'));
+        expect(diagnosticCalls).toHaveLength(0);
+    });
+    it('does not log diagnostic when wantsChangedWithDeps is false', async () => {
+        const cfg = {};
+        vi.mocked(loadMutineerConfig).mockResolvedValue(cfg);
+        const depFile = '/cwd/src/dep.ts';
+        vi.mocked(autoDiscoverTargetsAndTests).mockResolvedValue({
+            targets: [depFile],
+            testMap: new Map(),
+            directTestMap: new Map(),
+        });
+        const consoleSpy = vi.spyOn(console, 'log');
+        await runOrchestrator([], '/cwd');
+        const diagnosticCalls = consoleSpy.mock.calls.filter(([msg]) => typeof msg === 'string' && msg.includes('have no covering tests'));
+        expect(diagnosticCalls).toHaveLength(0);
+    });
+});
+describe('runOrchestrator timeout precedence', () => {
+    it('uses CLI --timeout when provided', async () => {
+        const cfg = {};
+        vi.mocked(loadMutineerConfig).mockResolvedValue(cfg);
+        await runOrchestrator(['--timeout', '5000'], '/cwd');
+        expect(createVitestAdapter).toHaveBeenCalledWith(expect.objectContaining({ timeoutMs: 5000 }));
+    });
+    it('uses config timeout when CLI flag is absent', async () => {
+        const cfg = { timeout: 10000 };
+        vi.mocked(loadMutineerConfig).mockResolvedValue(cfg);
+        await runOrchestrator([], '/cwd');
+        expect(createVitestAdapter).toHaveBeenCalledWith(expect.objectContaining({ timeoutMs: 10000 }));
+    });
+    it('CLI --timeout takes precedence over config timeout', async () => {
+        const cfg = { timeout: 10000 };
+        vi.mocked(loadMutineerConfig).mockResolvedValue(cfg);
+        await runOrchestrator(['--timeout', '2000'], '/cwd');
+        expect(createVitestAdapter).toHaveBeenCalledWith(expect.objectContaining({ timeoutMs: 2000 }));
+    });
+    it('falls back to MUTANT_TIMEOUT_MS default when neither CLI nor config timeout set', async () => {
+        const cfg = {};
+        vi.mocked(loadMutineerConfig).mockResolvedValue(cfg);
+        await runOrchestrator([], '/cwd');
+        expect(createVitestAdapter).toHaveBeenCalledWith(expect.objectContaining({ timeoutMs: 30_000 }));
+    });
+    it('env var MUTINEER_MUTANT_TIMEOUT_MS affects default when no CLI/config timeout', async () => {
+        const cfg = {};
+        vi.mocked(loadMutineerConfig).mockResolvedValue(cfg);
+        const orig = process.env.MUTINEER_MUTANT_TIMEOUT_MS;
+        // env var is read at module load time, so we can only verify the default
+        // is used when no cli/config override is present
+        process.env.MUTINEER_MUTANT_TIMEOUT_MS = orig;
+        await runOrchestrator([], '/cwd');
+        const call = vi.mocked(createVitestAdapter).mock.calls[0][0];
+        expect(call.timeoutMs).toBeGreaterThan(0);
+        expect(Number.isFinite(call.timeoutMs)).toBe(true);
+    });
+});

package/dist/runner/__tests__/pool-executor.spec.js

@@ -370,6 +370,46 @@ describe('executePool', () => {
         });
         expect(cache['killed-covering-key'].coveringTests).toBeUndefined();
     });
+    it('correctly stores snippets for multiple escaped mutants from the same file', async () => {
+        const tmpFile = path.join(tmpDir, 'shared.ts');
+        await fs.writeFile(tmpFile, 'const x = a + b\n');
+        const adapter = makeAdapter({
+            runMutant: vi
+                .fn()
+                .mockResolvedValue({ status: 'escaped', durationMs: 1 }),
+        });
+        const cache = {};
+        const makeFileTask = (key, mutated) => makeTask({
+            key,
+            v: {
+                id: `shared.ts#${key}`,
+                name: 'flipArith',
+                file: tmpFile,
+                code: mutated,
+                line: 1,
+                col: 10,
+                tests: ['/tests/file.test.ts'],
+            },
+        });
+        await executePool({
+            tasks: [
+                makeFileTask('cache-key-1', 'const x = a - b\n'),
+                makeFileTask('cache-key-2', 'const x = a * b\n'),
+                makeFileTask('cache-key-3', 'const x = a / b\n'),
+            ],
+            adapter,
+            cache,
+            concurrency: 1,
+            progressMode: 'list',
+            cwd: tmpDir,
+        });
+        expect(cache['cache-key-1'].originalSnippet).toBe('const x = a + b');
+        expect(cache['cache-key-1'].mutatedSnippet).toBe('const x = a - b');
+        expect(cache['cache-key-2'].originalSnippet).toBe('const x = a + b');
+        expect(cache['cache-key-2'].mutatedSnippet).toBe('const x = a * b');
+        expect(cache['cache-key-3'].originalSnippet).toBe('const x = a + b');
+        expect(cache['cache-key-3'].mutatedSnippet).toBe('const x = a / b');
+    });
     it('handles adapter errors gracefully and still shuts down', async () => {
         const adapter = makeAdapter({
             runMutant: vi.fn().mockRejectedValue(new Error('adapter failure')),

package/dist/runner/args.d.ts

@@ -19,6 +19,7 @@ export interface ParsedCliOptions {
     readonly progressMode: 'bar' | 'list' | 'quiet';
     readonly minKillPercent: number | undefined;
     readonly runner: 'vitest' | 'jest';
+    readonly timeout: number | undefined;
 }
 /**
  * Parse a numeric CLI flag value.
@@ -36,6 +37,10 @@ export declare function readStringFlag(args: readonly string[], flag: string, al
  * Validate a percentage value (0-100).
  */
 export declare function validatePercent(value: number | undefined, source: string): number | undefined;
+/**
+ * Validate a timeout value (must be a positive finite number).
+ */
+export declare function validatePositiveMs(value: number | undefined, source: string): number | undefined;
 /**
  * Parse concurrency from CLI args or use default.
  */

package/dist/runner/args.js

@@ -70,6 +70,17 @@ export function validatePercent(value, source) {
     }
     return value;
 }
+/**
+ * Validate a timeout value (must be a positive finite number).
+ */
+export function validatePositiveMs(value, source) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`Invalid ${source}: expected a positive number (received ${value})`);
+    }
+    return value;
+}
 /**
  * Parse concurrency from CLI args or use default.
  */
@@ -115,6 +126,7 @@ export function parseCliOptions(args, cfg) {
     const cliKillPercent = validatePercent(readNumberFlag(args, '--min-kill-percent'), '--min-kill-percent');
     const configKillPercent = validatePercent(cfg.minKillPercent, 'mutineer.config minKillPercent');
     const minKillPercent = cliKillPercent ?? configKillPercent;
+    const timeout = validatePositiveMs(readNumberFlag(args, '--timeout'), '--timeout');
     return {
         configPath,
         wantsChanged,
@@ -126,5 +138,6 @@ export function parseCliOptions(args, cfg) {
         progressMode,
         minKillPercent,
         runner,
+        timeout,
     };
 }