@mutineerjs/mutineer 0.5.1 → 0.6.0

package/README.md

@@ -19,10 +19,10 @@ Built for **Vitest** with first-class **Jest** support. Other test runners can b
 
 1. **Baseline** -- runs your test suite to make sure everything passes before mutating
 2. **Mutate** -- applies AST-safe operator replacements to your source files (not your tests)
-3. **Test** -- re-runs only the tests that import the mutated file, using a fast file-swap mechanism
+3. **Test** -- re-runs only the tests that import the mutated file, using temp files in `__mutineer__` dirs loaded via Vite plugin / Jest resolver
 4. **Report** -- prints a summary with kill rate, escaped mutants, and per-file breakdowns
 
-Mutations are applied using Babel AST analysis, so operators inside strings and comments are never touched. Mutated code is injected at runtime via Vite plugins (Vitest) or custom resolvers (Jest) -- no files on disk are modified.
+Mutations are applied using Babel AST analysis, so operators inside strings and comments are never touched. Mutated code is written to a temporary `__mutineer__` directory next to each source file, then loaded at runtime via Vite plugins (Vitest) or custom resolvers (Jest).
 
 ## Supported Mutations (WIP)
 
@@ -164,6 +164,46 @@ export default defineMutineerConfig({
 | `testPatterns`      | `string[]`           | Globs for test file discovery                    |
 | `extensions`        | `string[]`           | File extensions to consider                      |
 
+## Recommended Workflow
+
+Large repos can generate thousands of mutations. These strategies keep runs fast and incremental.
+
+### 1. PR-scoped runs (CI) — `--changed-with-deps`
+
+Run only on files changed in the branch plus their direct dependents:
+
+```bash
+mutineer run --changed-with-deps
+```
+
+- Tune the dependency graph depth with `dependencyDepth` in config (default: `1`)
+- Add `--per-test-coverage` to only run tests that cover the mutated line
+- Recommended `package.json` script:
+
+```json
+"mutineer:ci": "mutineer run --changed-with-deps --per-test-coverage"
+```
+
+### 2. Split configs by domain
+
+Create a `mutineer.config.ts` per domain and run selectively:
+
+```bash
+mutineer run -c src/api/mutineer.config.ts
+```
+
+Each config sets its own `source` glob and `minKillPercent`. Good for monorepos or large modular projects — domains can also be parallelized in CI.
+
+### 3. Combine filters to reduce scope
+
+- `--only-covered-lines` — skips lines not covered by any test (requires a coverage file)
+- `maxMutantsPerFile` — caps mutations per file as a safety valve
+- Combine for maximum focus:
+
+```bash
+mutineer run --changed-with-deps --only-covered-lines --per-test-coverage
+```
+
 ## File Support
 
 - TypeScript and JavaScript modules (`.ts`, `.js`, `.tsx`, `.jsx`)

package/dist/bin/__tests__/mutineer.spec.d.ts

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

package/dist/bin/__tests__/mutineer.spec.js

@@ -0,0 +1,43 @@
+import { createRequire } from 'node:module';
+import { describe, it, expect } from 'vitest';
+import { HELP_TEXT, getVersion } from '../mutineer.js';
+describe('HELP_TEXT', () => {
+    const flags = [
+        '--config',
+        '-c',
+        '--concurrency',
+        '--runner',
+        '--progress',
+        '--changed',
+        '--changed-with-deps',
+        '--only-covered-lines',
+        '--per-test-coverage',
+        '--coverage-file',
+        '--min-kill-percent',
+        '--help',
+        '-h',
+        '--version',
+        '-V',
+    ];
+    it.each(flags)('includes %s', (flag) => {
+        expect(HELP_TEXT).toContain(flag);
+    });
+    it('includes all three commands', () => {
+        expect(HELP_TEXT).toContain('init');
+        expect(HELP_TEXT).toContain('run');
+        expect(HELP_TEXT).toContain('clean');
+    });
+    it('--changed-with-deps description mentions local dependencies', () => {
+        expect(HELP_TEXT).toContain('local dependencies');
+    });
+});
+describe('getVersion()', () => {
+    it('returns a semver string', () => {
+        expect(getVersion()).toMatch(/^\d+\.\d+\.\d+/);
+    });
+    it('matches package.json version', () => {
+        const require = createRequire(import.meta.url);
+        const pkg = require('../../../package.json');
+        expect(getVersion()).toBe(pkg.version);
+    });
+});

package/dist/bin/mutineer.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export {};
+export declare const HELP_TEXT = "Usage: mutineer <command> [options]\n\nCommands:\n  init       Create a mutineer.config.ts template\n  run        Run mutation testing\n  clean      Remove __mutineer__ temp directories\n\nOptions (run):\n  --config, -c <path>       Config file path\n  --concurrency <n>         Worker count (default: CPU count - 1)\n  --runner <vitest|jest>    Test runner (default: vitest)\n  --progress <bar|list|quiet>  Progress display (default: bar)\n  --changed                 Mutate only git-changed files\n  --changed-with-deps       Mutate changed files + their local dependencies\n  --only-covered-lines      Mutate only lines covered by tests\n  --per-test-coverage       Collect per-test coverage data\n  --coverage-file <path>    Path to coverage JSON\n  --min-kill-percent <n>    Minimum kill % threshold (0\u2013100)\n  --timeout <ms>            Per-mutant test timeout in ms (default: 30000)\n\n  --help, -h                Show this help\n  --version, -V             Show version\n";
+export declare function getVersion(): string;

package/dist/bin/mutineer.js

@@ -1,12 +1,41 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { runOrchestrator } from '../runner/orchestrator.js';
 import { cleanupMutineerDirs } from '../runner/cleanup.js';
 // Constants
 const RUN_COMMAND = 'run';
 const CLEAN_COMMAND = 'clean';
 const INIT_COMMAND = 'init';
+export const HELP_TEXT = `\
+Usage: mutineer <command> [options]
+
+Commands:
+  init       Create a mutineer.config.ts template
+  run        Run mutation testing
+  clean      Remove __mutineer__ temp directories
+
+Options (run):
+  --config, -c <path>       Config file path
+  --concurrency <n>         Worker count (default: CPU count - 1)
+  --runner <vitest|jest>    Test runner (default: vitest)
+  --progress <bar|list|quiet>  Progress display (default: bar)
+  --changed                 Mutate only git-changed files
+  --changed-with-deps       Mutate changed files + their local dependencies
+  --only-covered-lines      Mutate only lines covered by tests
+  --per-test-coverage       Collect per-test coverage data
+  --coverage-file <path>    Path to coverage JSON
+  --min-kill-percent <n>    Minimum kill % threshold (0–100)
+  --timeout <ms>            Per-mutant test timeout in ms (default: 30000)
+
+  --help, -h                Show this help
+  --version, -V             Show version
+`;
+export function getVersion() {
+    const require = createRequire(import.meta.url);
+    return require('../../package.json').version;
+}
 const CONFIG_TEMPLATE = `\
 import { defineMutineerConfig } from 'mutineer'
 
@@ -19,7 +48,19 @@ export default defineMutineerConfig({
  */
 async function main() {
     const args = process.argv.slice(2);
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(HELP_TEXT);
+        process.exit(0);
+    }
+    if (args[0] === '--version' || args[0] === '-V') {
+        console.log(getVersion());
+        process.exit(0);
+    }
     if (args[0] === RUN_COMMAND) {
+        if (args.includes('--help') || args.includes('-h')) {
+            process.stdout.write(HELP_TEXT);
+            process.exit(0);
+        }
         await runOrchestrator(args.slice(1), process.cwd());
     }
     else if (args[0] === INIT_COMMAND) {

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__/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/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,
     };
 }

package/dist/runner/changed.js

@@ -1,7 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import fs from 'node:fs';
-import { createRequire } from 'node:module';
 import { normalizePath } from '../utils/normalizePath.js';
 import { createLogger } from '../utils/logger.js';
 const log = createLogger('changed');
@@ -50,52 +49,25 @@ function resolveLocalDependencies(file, cwd, seen = new Set(), maxDepth = 1, cur
             const dep = match[1];
             if (!dep.startsWith('.'))
                 continue;
-            try {
-                const require = createRequire(file);
-                let resolvedPath;
-                // Try direct resolution first
-                try {
-                    resolvedPath = require.resolve(dep);
-                }
-                catch {
-                    // Try different extensions if direct resolution fails
-                    for (const ext of SUPPORTED_EXTENSIONS) {
-                        try {
-                            // Try replacing existing extension
-                            resolvedPath = require.resolve(dep.replace(/\.(js|ts|vue)$/, ext));
-                            break;
-                        }
-                        catch {
-                            try {
-                                // Try adding extension
-                                resolvedPath = require.resolve(dep + ext);
-                                break;
-                            }
-                            catch {
-                                continue;
-                            }
-                        }
-                    }
-                }
-                if (!resolvedPath) {
-                    log.warn(`Could not resolve path for dependency ${dep} in ${file}`);
+            const dir = path.dirname(file);
+            const base = dep.replace(/\.(js|ts|mjs|cjs|vue)$/, '');
+            const candidates = [dep, ...SUPPORTED_EXTENSIONS.map((ext) => base + ext)];
+            let resolvedPath;
+            for (const candidate of candidates) {
+                const abs = normalizePath(path.resolve(dir, candidate));
+                if (abs.includes('node_modules') || !abs.startsWith(cwd))
                     continue;
+                if (fs.existsSync(abs)) {
+                    resolvedPath = abs;
+                    break;
                 }
-                // Skip anything outside the repo/cwd, node_modules, tests, or missing
-                if (!resolvedPath.startsWith(cwd) ||
-                    resolvedPath.includes('node_modules'))
-                    continue;
-                if (TEST_FILE_PATTERN.test(resolvedPath))
-                    continue;
-                if (!fs.existsSync(resolvedPath))
-                    continue;
-                deps.push(normalizePath(resolvedPath));
-                deps.push(...resolveLocalDependencies(resolvedPath, cwd, seen, maxDepth, currentDepth + 1));
             }
-            catch (err) {
-                log.warn(`Failed to resolve dependency ${dep} in ${file}: ${err}`);
+            if (!resolvedPath)
                 continue;
-            }
+            if (TEST_FILE_PATTERN.test(resolvedPath))
+                continue;
+            deps.push(resolvedPath);
+            deps.push(...resolveLocalDependencies(resolvedPath, cwd, seen, maxDepth, currentDepth + 1));
         }
     }
     return [...new Set(deps)];

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/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.js

@@ -43,7 +43,7 @@ export async function runOrchestrator(cliArgs, cwd) {
     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,
     });
@@ -88,6 +88,21 @@ 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.');
         return;

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

@@ -103,6 +103,25 @@ 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('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');

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

@@ -96,6 +96,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;
 }

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,6 @@ export interface MutineerConfig {
      * Requires Vitest coverage with perTest support.
      */
     readonly perTestCoverage?: boolean;
+    /** Per-mutant test timeout in milliseconds (default: 30000) */
+    readonly timeout?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutineerjs/mutineer",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "A fast, targeted mutation testing framework for JavaScript and TypeScript",
   "type": "module",
   "private": false,