@mutineerjs/mutineer 0.6.0 → 0.7.0

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/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,7 +38,7 @@ 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,
@@ -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]
@@ -104,7 +105,8 @@ export async function runOrchestrator(cliArgs, cwd) {
         }
     }
     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)
@@ -137,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,
@@ -145,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

@@ -122,6 +122,21 @@ describe('Vitest adapter', () => {
         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');
@@ -140,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/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;
@@ -196,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/types/config.d.ts

@@ -40,4 +40,6 @@ export interface MutineerConfig {
     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(() => { });

package/dist/utils/summary.d.ts

@@ -9,4 +9,22 @@ export interface Summary {
 }
 export declare function computeSummary(cache: Readonly<Record<string, MutantCacheEntry>>): Summary;
 export declare function printSummary(summary: Summary, cache?: Readonly<Record<string, MutantCacheEntry>>, durationMs?: number): void;
+export interface JsonMutant {
+    readonly file: string;
+    readonly line: number;
+    readonly col: number;
+    readonly mutator: string;
+    readonly status: string;
+    readonly originalSnippet?: string;
+    readonly mutatedSnippet?: string;
+    readonly coveringTests?: readonly string[];
+}
+export interface JsonReport {
+    readonly schemaVersion: 1;
+    readonly timestamp: string;
+    readonly durationMs?: number;
+    readonly summary: Summary;
+    readonly mutants: JsonMutant[];
+}
+export declare function buildJsonReport(summary: Summary, cache: Readonly<Record<string, MutantCacheEntry>>, durationMs?: number): JsonReport;
 export declare function summarise(cache: Readonly<Record<string, MutantCacheEntry>>): Summary;

package/dist/utils/summary.js

@@ -115,6 +115,31 @@ export function printSummary(summary, cache, durationMs) {
     }
     console.log(chalk.dim(SEPARATOR) + '\n');
 }
+export function buildJsonReport(summary, cache, durationMs) {
+    const mutants = Object.values(cache).map((entry) => ({
+        file: entry.file,
+        line: entry.line,
+        col: entry.col,
+        mutator: entry.mutator,
+        status: entry.status,
+        ...(entry.originalSnippet !== undefined && {
+            originalSnippet: entry.originalSnippet,
+        }),
+        ...(entry.mutatedSnippet !== undefined && {
+            mutatedSnippet: entry.mutatedSnippet,
+        }),
+        ...(entry.coveringTests !== undefined && {
+            coveringTests: entry.coveringTests,
+        }),
+    }));
+    return {
+        schemaVersion: 1,
+        timestamp: new Date().toISOString(),
+        ...(durationMs !== undefined && { durationMs }),
+        summary,
+        mutants,
+    };
+}
 export function summarise(cache) {
     const s = computeSummary(cache);
     printSummary(s, cache);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutineerjs/mutineer",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A fast, targeted mutation testing framework for JavaScript and TypeScript",
   "type": "module",
   "private": false,
@@ -98,6 +98,7 @@
     }
   },
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.15",
     "@commitlint/cli": "^20.4.3",
     "@commitlint/config-conventional": "^20.4.3",
     "@types/babel__traverse": "^7.28.0",