@mutineerjs/mutineer 0.6.0 → 0.8.0

package/dist/types/config.d.ts

@@ -40,4 +40,20 @@ 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';
+    /**
+     * Enable TypeScript type checking to pre-filter mutants that produce compile errors.
+     * true = enable (requires tsconfig.json), false = disable,
+     * object = enable with optional custom tsconfig path.
+     * Defaults to auto-detect (enabled if tsconfig.json found in cwd).
+     */
+    readonly typescript?: boolean | {
+        readonly tsconfig?: string;
+    };
+    /**
+     * Filter mutations to a specific Vitest workspace project.
+     * Requires a vitest.config.ts with test.projects configured.
+     */
+    readonly vitestProject?: string | readonly string[];
 }

package/dist/types/mutant.d.ts

@@ -4,7 +4,7 @@
  * Centralises the shapes used across the runner and adapters so we
  * don't duplicate unions or object shapes in multiple modules.
  */
-export type MutantStatus = 'killed' | 'escaped' | 'skipped' | 'error' | 'timeout';
+export type MutantStatus = 'killed' | 'escaped' | 'skipped' | 'error' | 'timeout' | 'compile-error';
 export type MutantRunStatus = MutantStatus;
 export interface MutantLocation {
     readonly file: string;
@@ -17,7 +17,10 @@ export interface MutantDescriptor extends MutantLocation {
     readonly code: string;
 }
 /** Payload passed to workers/pools for execution. */
-export type MutantPayload = MutantDescriptor;
+export interface MutantPayload extends MutantDescriptor {
+    /** When true, this mutant must use the legacy redirect path instead of the schema path. */
+    readonly isFallback?: boolean;
+}
 /** Variant with attached test files. */
 export interface Variant extends MutantDescriptor {
     readonly tests: readonly string[];

package/dist/utils/CompileErrors.d.ts

@@ -0,0 +1,7 @@
+import type { MutantCacheEntry } from '../types/mutant.js';
+interface Props {
+    entries: MutantCacheEntry[];
+    cwd: string;
+}
+export declare function CompileErrors({ entries, cwd }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/utils/CompileErrors.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import path from 'node:path';
+import { Box, Text, useInput, useApp } from 'ink';
+import { useState, useEffect } from 'react';
+export function CompileErrors({ entries, cwd }) {
+    const { exit } = useApp();
+    const [expanded, setExpanded] = useState(false);
+    useEffect(() => {
+        if (expanded)
+            exit();
+    }, [expanded, exit]);
+    useInput((input, key) => {
+        if (input === 'e') {
+            setExpanded(true);
+        }
+        else if (key.return || input === 'q') {
+            exit();
+        }
+    });
+    if (expanded) {
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Compile Error Mutants (type-filtered):" }), entries.map((entry, i) => (_jsxs(Text, { dimColor: true, children: ['  \u2022 ', path.relative(cwd, entry.file), "@", entry.line, ",", entry.col, '  ', entry.mutator] }, i)))] }));
+    }
+    return (_jsxs(Box, { gap: 2, children: [_jsxs(Text, { dimColor: true, children: ["Compile Error Mutants (type-filtered): ", entries.length] }), _jsx(Text, { dimColor: true, children: "e expand  return skip" })] }));
+}

package/dist/utils/__tests__/CompileErrors.spec.d.ts

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

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

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+const mockExit = vi.fn();
+const mockSetExpanded = vi.fn();
+let inputHandler;
+let effectCallback;
+vi.mock('ink', () => ({
+    Box: ({ children }) => children,
+    Text: ({ children }) => children,
+    useInput: vi.fn((fn) => {
+        inputHandler = fn;
+    }),
+    useApp: () => ({ exit: mockExit }),
+}));
+vi.mock('react', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        useState: vi.fn((init) => [init, mockSetExpanded]),
+        useEffect: vi.fn((fn) => {
+            effectCallback = fn;
+        }),
+    };
+});
+import { CompileErrors } from '../CompileErrors.js';
+import { useState } from 'react';
+const entries = [
+    {
+        status: 'compile-error',
+        file: '/cwd/src/foo.ts',
+        line: 10,
+        col: 5,
+        mutator: 'returnToNull',
+    },
+    {
+        status: 'compile-error',
+        file: '/cwd/src/bar.ts',
+        line: 20,
+        col: 3,
+        mutator: 'returnFlipBool',
+    },
+];
+describe('CompileErrors', () => {
+    beforeEach(() => {
+        mockExit.mockClear();
+        mockSetExpanded.mockClear();
+        inputHandler = undefined;
+        effectCallback = undefined;
+        vi.mocked(useState).mockImplementation(((init) => [
+            init,
+            mockSetExpanded,
+        ]));
+    });
+    it('registers a useInput handler on render', () => {
+        CompileErrors({ entries, cwd: '/cwd' });
+        expect(inputHandler).toBeDefined();
+    });
+    it('calls setExpanded(true) when "e" is pressed', () => {
+        CompileErrors({ entries, cwd: '/cwd' });
+        inputHandler('e', { return: false });
+        expect(mockSetExpanded).toHaveBeenCalledWith(true);
+    });
+    it('calls exit() when return is pressed', () => {
+        CompileErrors({ entries, cwd: '/cwd' });
+        inputHandler('', { return: true });
+        expect(mockExit).toHaveBeenCalled();
+    });
+    it('calls exit() when "q" is pressed', () => {
+        CompileErrors({ entries, cwd: '/cwd' });
+        inputHandler('q', { return: false });
+        expect(mockExit).toHaveBeenCalled();
+    });
+    it('does not call exit() or setExpanded for other keys', () => {
+        CompileErrors({ entries, cwd: '/cwd' });
+        inputHandler('x', { return: false });
+        expect(mockExit).not.toHaveBeenCalled();
+        expect(mockSetExpanded).not.toHaveBeenCalled();
+    });
+    it('registers a useEffect handler on render', () => {
+        CompileErrors({ entries, cwd: '/cwd' });
+        expect(effectCallback).toBeDefined();
+    });
+    it('useEffect calls exit() when expanded is true', () => {
+        vi.mocked(useState).mockReturnValueOnce([
+            true,
+            mockSetExpanded,
+        ]);
+        CompileErrors({ entries, cwd: '/cwd' });
+        effectCallback();
+        expect(mockExit).toHaveBeenCalled();
+    });
+    it('useEffect does not call exit() when expanded is false', () => {
+        CompileErrors({ entries, cwd: '/cwd' });
+        effectCallback();
+        expect(mockExit).not.toHaveBeenCalled();
+    });
+});

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) {
@@ -18,13 +18,16 @@ describe('summary', () => {
             a: makeEntry({ status: 'killed' }),
             b: makeEntry({ status: 'escaped' }),
             c: makeEntry({ status: 'skipped' }),
+            d: makeEntry({ status: 'timeout' }),
         };
         const s = computeSummary(cache);
         expect(s).toEqual({
-            total: 3,
+            total: 4,
             killed: 1,
             escaped: 1,
             skipped: 1,
+            timeouts: 1,
+            compileErrors: 0,
             evaluated: 2,
             killRate: 50,
         });
@@ -43,6 +46,40 @@ describe('summary', () => {
         expect(lines.some((l) => l.includes('Duration: 1.50s'))).toBe(true);
         logSpy.mockRestore();
     });
+    it('prints Timed Out Mutants section when timeouts exist', () => {
+        const cache = {
+            a: makeEntry({ status: 'timeout', file: '/tmp/a.ts', mutator: 'flip' }),
+        };
+        const summary = computeSummary(cache);
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        printSummary(summary, cache);
+        const lines = logSpy.mock.calls.map((c) => stripAnsi(c.join(' ')));
+        expect(lines.some((l) => l.includes('Timed Out Mutants'))).toBe(true);
+        logSpy.mockRestore();
+    });
+    it('shows Timeouts count in stat line when timeouts > 0', () => {
+        const cache = {
+            a: makeEntry({ status: 'timeout', file: '/tmp/a.ts' }),
+            b: makeEntry({ status: 'killed', file: '/tmp/b.ts' }),
+        };
+        const summary = computeSummary(cache);
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        printSummary(summary, cache);
+        const lines = logSpy.mock.calls.map((c) => stripAnsi(c.join(' ')));
+        expect(lines.some((l) => l.includes('Timeouts: 1'))).toBe(true);
+        logSpy.mockRestore();
+    });
+    it('shows Timeouts: 0 in stat line when timeouts is zero', () => {
+        const cache = {
+            a: makeEntry({ status: 'killed', file: '/tmp/a.ts' }),
+        };
+        const summary = computeSummary(cache);
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        printSummary(summary, cache);
+        const lines = logSpy.mock.calls.map((c) => stripAnsi(c.join(' ')));
+        expect(lines.some((l) => l.includes('Timeouts: 0'))).toBe(true);
+        logSpy.mockRestore();
+    });
     it('prints diff lines for escaped mutant with snippets', () => {
         const cache = {
             a: makeEntry({
@@ -97,6 +134,93 @@ 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('prints compile error mutants section by default', () => {
+        const cache = {
+            a: makeEntry({
+                status: 'compile-error',
+                file: '/tmp/a.ts',
+                mutator: 'returnToNull',
+            }),
+        };
+        const summary = computeSummary(cache);
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        printSummary(summary, cache);
+        const lines = logSpy.mock.calls.map((c) => stripAnsi(c.join(' ')));
+        expect(lines.some((l) => l.includes('Compile Error Mutants'))).toBe(true);
+        logSpy.mockRestore();
+    });
+    it('skips compile error section when skipCompileErrors is true', () => {
+        const cache = {
+            a: makeEntry({
+                status: 'compile-error',
+                file: '/tmp/a.ts',
+                mutator: 'returnToNull',
+            }),
+        };
+        const summary = computeSummary(cache);
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        printSummary(summary, cache, undefined, { skipCompileErrors: true });
+        const lines = logSpy.mock.calls.map((c) => stripAnsi(c.join(' ')));
+        expect(lines.some((l) => l.includes('Compile Error Mutants'))).toBe(false);
+        logSpy.mockRestore();
+    });
+    it('shows compile error section when skipCompileErrors is false', () => {
+        const cache = {
+            a: makeEntry({
+                status: 'compile-error',
+                file: '/tmp/a.ts',
+                mutator: 'returnToNull',
+            }),
+        };
+        const summary = computeSummary(cache);
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        printSummary(summary, cache, undefined, { skipCompileErrors: false });
+        const lines = logSpy.mock.calls.map((c) => stripAnsi(c.join(' ')));
+        expect(lines.some((l) => l.includes('Compile Error Mutants'))).toBe(true);
+        logSpy.mockRestore();
+    });
     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

@@ -4,9 +4,31 @@ export interface Summary {
     readonly killed: number;
     readonly escaped: number;
     readonly skipped: number;
+    readonly timeouts: number;
+    readonly compileErrors: number;
     readonly evaluated: number;
     readonly killRate: number;
 }
 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 declare function printSummary(summary: Summary, cache?: Readonly<Record<string, MutantCacheEntry>>, durationMs?: number, opts?: {
+    skipCompileErrors?: boolean;
+}): 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

@@ -6,18 +6,33 @@ export function computeSummary(cache) {
     let killed = 0;
     let escaped = 0;
     let skipped = 0;
+    let timeouts = 0;
+    let compileErrors = 0;
     for (const entry of allEntries) {
         if (entry.status === 'killed')
             killed++;
         else if (entry.status === 'escaped')
             escaped++;
+        else if (entry.status === 'compile-error')
+            compileErrors++;
+        else if (entry.status === 'timeout')
+            timeouts++;
         else
             skipped++;
     }
     const evaluated = killed + escaped;
     const total = allEntries.length;
     const killRate = evaluated === 0 ? 0 : (killed / evaluated) * 100;
-    return { total, killed, escaped, skipped, evaluated, killRate };
+    return {
+        total,
+        killed,
+        escaped,
+        skipped,
+        timeouts,
+        compileErrors,
+        evaluated,
+        killRate,
+    };
 }
 function formatDuration(ms) {
     if (ms < 1000)
@@ -29,7 +44,7 @@ function formatDuration(ms) {
     const remainingSeconds = seconds % 60;
     return `${minutes}m ${remainingSeconds.toFixed(1)}s`;
 }
-export function printSummary(summary, cache, durationMs) {
+export function printSummary(summary, cache, durationMs, opts) {
     console.log('\n' + chalk.dim(SEPARATOR));
     console.log(chalk.bold(' Mutineer Test Suite Summary'));
     console.log(chalk.dim(SEPARATOR));
@@ -57,6 +72,8 @@ export function printSummary(summary, cache, durationMs) {
     const entriesByStatus = {
         killed: [],
         escaped: [],
+        compileErrors: [],
+        timeouts: [],
         skipped: [],
     };
     for (const entry of allEntries) {
@@ -64,6 +81,10 @@ export function printSummary(summary, cache, durationMs) {
             entriesByStatus.killed.push(entry);
         else if (entry.status === 'escaped')
             entriesByStatus.escaped.push(entry);
+        else if (entry.status === 'compile-error')
+            entriesByStatus.compileErrors.push(entry);
+        else if (entry.status === 'timeout')
+            entriesByStatus.timeouts.push(entry);
         else
             entriesByStatus.skipped.push(entry);
     }
@@ -92,13 +113,27 @@ export function printSummary(summary, cache, durationMs) {
             }
         }
     }
+    if (entriesByStatus.compileErrors.length && !opts?.skipCompileErrors) {
+        console.log('\n' + chalk.dim('Compile Error Mutants (type-filtered):'));
+        for (const entry of entriesByStatus.compileErrors)
+            console.log('  ' + formatRow(entry));
+    }
+    if (entriesByStatus.timeouts.length) {
+        console.log('\n' + chalk.yellow.bold('Timed Out Mutants:'));
+        for (const entry of entriesByStatus.timeouts)
+            console.log('  ' + formatRow(entry));
+    }
     if (entriesByStatus.skipped.length) {
         console.log('\n' + chalk.dim('Skipped Mutants:'));
         for (const entry of entriesByStatus.skipped)
             console.log('  ' + formatRow(entry));
     }
     console.log('\n' + chalk.dim(SEPARATOR));
-    console.log(`Total: ${summary.total} \u2014 ${chalk.green(`Killed: ${summary.killed}`)}, ${chalk.red(`Escaped: ${summary.escaped}`)}, ${chalk.dim(`Skipped: ${summary.skipped}`)}`);
+    const compileErrorStr = summary.compileErrors > 0
+        ? `, ${chalk.dim(`Compile Errors: ${summary.compileErrors}`)}`
+        : '';
+    const timeoutStr = `, ${chalk.yellow(`Timeouts: ${summary.timeouts}`)}`;
+    console.log(`Total: ${summary.total} \u2014 ${chalk.green(`Killed: ${summary.killed}`)}, ${chalk.red(`Escaped: ${summary.escaped}`)}, ${chalk.dim(`Skipped: ${summary.skipped}`)}${timeoutStr}${compileErrorStr}`);
     if (summary.evaluated === 0) {
         console.log(`Kill rate: ${chalk.dim('0.00% (no mutants executed)')}`);
     }
@@ -115,6 +150,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.8.0",
   "description": "A fast, targeted mutation testing framework for JavaScript and TypeScript",
   "type": "module",
   "private": false,
@@ -105,6 +105,7 @@
     "@types/react": "^19.2.14",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "^8.47.0",
+    "@vitest/coverage-v8": "^4.0.15",
     "eslint": "^10.0.3",
     "husky": "^9.1.7",
     "jsdom": "^28.1.0",