@mutineerjs/mutineer 0.7.0 → 0.8.0

package/dist/runner/__tests__/ts-checker.spec.js

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest';
+import path from 'node:path';
+import { resolveTypescriptEnabled, resolveTsconfigPath, checkTypes, } from '../ts-checker.js';
+// Directory with a real tsconfig.json (the project root, 3 levels up from __tests__)
+const CWD_WITH_TSCONFIG = path.resolve(import.meta.dirname, '../../../');
+// A temp-like directory unlikely to have tsconfig.json
+const CWD_WITHOUT_TSCONFIG = '/tmp';
+function makeVariant(overrides = {}) {
+    return {
+        id: 'foo.ts#0',
+        name: 'flipEQ',
+        file: '/nonexistent/foo.ts',
+        code: 'const x: number = 1',
+        line: 1,
+        col: 0,
+        tests: [],
+        ...overrides,
+    };
+}
+describe('resolveTsconfigPath', () => {
+    it('returns undefined for boolean true', () => {
+        expect(resolveTsconfigPath({ typescript: true })).toBeUndefined();
+    });
+    it('returns undefined for boolean false', () => {
+        expect(resolveTsconfigPath({ typescript: false })).toBeUndefined();
+    });
+    it('returns tsconfig path from object config', () => {
+        expect(resolveTsconfigPath({ typescript: { tsconfig: './tsconfig.app.json' } })).toBe('./tsconfig.app.json');
+    });
+    it('returns undefined when object config has no tsconfig property', () => {
+        expect(resolveTsconfigPath({ typescript: {} })).toBeUndefined();
+    });
+    it('returns undefined when no typescript config key', () => {
+        expect(resolveTsconfigPath({})).toBeUndefined();
+    });
+});
+describe('resolveTypescriptEnabled', () => {
+    it('CLI false overrides everything', () => {
+        expect(resolveTypescriptEnabled(false, { typescript: true }, CWD_WITH_TSCONFIG)).toBe(false);
+    });
+    it('CLI true overrides everything', () => {
+        expect(resolveTypescriptEnabled(true, { typescript: false }, CWD_WITH_TSCONFIG)).toBe(true);
+    });
+    it('config false disables checking', () => {
+        expect(resolveTypescriptEnabled(undefined, { typescript: false }, CWD_WITH_TSCONFIG)).toBe(false);
+    });
+    it('config true enables checking', () => {
+        expect(resolveTypescriptEnabled(undefined, { typescript: true }, CWD_WITHOUT_TSCONFIG)).toBe(true);
+    });
+    it('config object enables checking', () => {
+        expect(resolveTypescriptEnabled(undefined, { typescript: { tsconfig: './tsconfig.json' } }, CWD_WITHOUT_TSCONFIG)).toBe(true);
+    });
+    it('auto-detects: enabled when tsconfig.json is present in cwd', () => {
+        // The project root has a tsconfig.json
+        expect(resolveTypescriptEnabled(undefined, {}, CWD_WITH_TSCONFIG)).toBe(true);
+    });
+    it('auto-detects: disabled when no tsconfig.json in cwd', () => {
+        // /tmp should not have a tsconfig.json
+        expect(resolveTypescriptEnabled(undefined, {}, CWD_WITHOUT_TSCONFIG)).toBe(false);
+    });
+});
+describe('checkTypes', () => {
+    it('returns empty set for empty variants array', async () => {
+        const result = await checkTypes([], undefined, CWD_WITHOUT_TSCONFIG);
+        expect(result.size).toBe(0);
+    });
+    it('does not flag valid TypeScript code', async () => {
+        const variant = makeVariant({
+            id: 'valid.ts#0',
+            file: '/nonexistent/valid.ts',
+            code: 'const x: number = 42; export default x',
+        });
+        const result = await checkTypes([variant], undefined, CWD_WITHOUT_TSCONFIG);
+        expect(result.has('valid.ts#0')).toBe(false);
+    }, 15000);
+    it('flags TypeScript type mismatch as compile error', async () => {
+        const variant = makeVariant({
+            id: 'bad.ts#0',
+            file: '/nonexistent/bad.ts',
+            code: 'const x: number = "this is not a number"',
+        });
+        const result = await checkTypes([variant], undefined, CWD_WITHOUT_TSCONFIG);
+        expect(result.has('bad.ts#0')).toBe(true);
+    }, 15000);
+    it('checks multiple variants for same file independently', async () => {
+        const valid = makeVariant({
+            id: 'multi.ts#0',
+            file: '/nonexistent/multi.ts',
+            code: 'const x: number = 1',
+        });
+        const invalid = makeVariant({
+            id: 'multi.ts#1',
+            file: '/nonexistent/multi.ts',
+            code: 'const x: number = "bad"',
+        });
+        const result = await checkTypes([valid, invalid], undefined, CWD_WITHOUT_TSCONFIG);
+        expect(result.has('multi.ts#0')).toBe(false);
+        expect(result.has('multi.ts#1')).toBe(true);
+    }, 15000);
+    it('checks variants from different files independently', async () => {
+        const validA = makeVariant({
+            id: 'a.ts#0',
+            file: '/nonexistent/a.ts',
+            code: 'const x: number = 1',
+        });
+        const invalidB = makeVariant({
+            id: 'b.ts#0',
+            file: '/nonexistent/b.ts',
+            code: 'const y: string = 999',
+        });
+        const result = await checkTypes([validA, invalidB], undefined, CWD_WITHOUT_TSCONFIG);
+        expect(result.has('a.ts#0')).toBe(false);
+        expect(result.has('b.ts#0')).toBe(true);
+    }, 15000);
+});

package/dist/runner/args.d.ts

@@ -25,6 +25,11 @@ export interface ParsedCliOptions {
         index: number;
         total: number;
     } | undefined;
+    /** undefined = use config/auto-detect, true = force enable, false = force disable */
+    readonly typescriptCheck: boolean | undefined;
+    /** Vitest workspace project name(s) to filter mutations to */
+    readonly vitestProject: string | undefined;
+    readonly skipBaseline: boolean;
 }
 /**
  * Parse a numeric CLI flag value.

package/dist/runner/args.js

@@ -152,6 +152,13 @@ export function parseCliOptions(args, cfg) {
     const reportFlag = readStringFlag(args, '--report');
     const reportFormat = reportFlag === 'json' || cfg.report === 'json' ? 'json' : 'text';
     const shard = parseShardOption(args);
+    const typescriptCheck = args.includes('--typescript')
+        ? true
+        : args.includes('--no-typescript')
+            ? false
+            : undefined;
+    const vitestProject = readStringFlag(args, '--vitest-project');
+    const skipBaseline = args.includes('--skip-baseline');
     return {
         configPath,
         wantsChanged,
@@ -166,5 +173,8 @@ export function parseCliOptions(args, cfg) {
         timeout,
         reportFormat,
         shard,
+        typescriptCheck,
+        vitestProject,
+        skipBaseline,
     };
 }

package/dist/runner/cleanup.js

@@ -4,7 +4,7 @@ import fs from 'node:fs/promises';
  */
 export async function cleanupMutineerDirs(cwd, opts = {}) {
     const glob = await import('fast-glob');
-    const dirs = await glob.default('**/__mutineer__', {
+    const dirs = await glob.default(['__mutineer__', '**/__mutineer__'], {
         cwd,
         onlyDirectories: true,
         absolute: true,

package/dist/runner/orchestrator.js

@@ -10,8 +10,12 @@
  * 6. Report results
  */
 import path from 'node:path';
+import fs from 'node:fs';
 import os from 'node:os';
+import { render } from 'ink';
+import { createElement } from 'react';
 import { normalizePath } from '../utils/normalizePath.js';
+import { PoolSpinner } from '../utils/PoolSpinner.js';
 import { autoDiscoverTargetsAndTests } from './discover.js';
 import { listChangedFiles } from './changed.js';
 import { loadMutineerConfig } from './config.js';
@@ -21,9 +25,12 @@ import { createLogger } from '../utils/logger.js';
 import { extractConfigPath, parseCliOptions } from './args.js';
 import { clearCacheOnStart, readMutantCache } from './cache.js';
 import { getTargetFile, enumerateAllVariants } from './variants.js';
+import { generateSchema } from '../core/schemata.js';
+import { getSchemaFilePath } from './shared/mutant-paths.js';
 import { resolveCoverageConfig, loadCoverageAfterBaseline, } from './coverage-resolver.js';
 import { prepareTasks } from './tasks.js';
 import { executePool } from './pool-executor.js';
+import { checkTypes, resolveTypescriptEnabled, resolveTsconfigPath, } from './ts-checker.js';
 const log = createLogger('orchestrator');
 // Per-mutant test timeout (ms). Can be overridden with env MUTINEER_MUTANT_TIMEOUT_MS
 export function parseMutantTimeoutMs(raw) {
@@ -40,12 +47,15 @@ export async function runOrchestrator(cliArgs, cwd) {
     const opts = parseCliOptions(cliArgs, cfg);
     await clearCacheOnStart(cwd, opts.shard);
     // Create test runner adapter
+    const vitestProject = opts.vitestProject ??
+        (typeof cfg.vitestProject === 'string' ? cfg.vitestProject : undefined);
     const adapter = (opts.runner === 'jest' ? createJestAdapter : createVitestAdapter)({
         cwd,
         concurrency: opts.concurrency,
         timeoutMs: opts.timeout ?? cfg.timeout ?? MUTANT_TIMEOUT_MS,
         config: cfg,
         cliArgs,
+        vitestProject,
     });
     // 2. Resolve coverage configuration
     const coverage = await resolveCoverageConfig(opts, cfg, adapter, cliArgs);
@@ -110,20 +120,25 @@ export async function runOrchestrator(cliArgs, cwd) {
         return;
     }
     // 5. Run baseline tests (with coverage if needed for filtering)
-    log.info(`Running ${baselineTests.length} baseline tests${coverage.enableCoverageForBaseline ? ' (collecting coverage)' : ''}\u2026`);
-    const baselineOk = await adapter.runBaseline(baselineTests, {
-        collectCoverage: coverage.enableCoverageForBaseline,
-        perTestCoverage: coverage.wantsPerTestCoverage,
-    });
-    if (!baselineOk) {
-        process.exitCode = 1;
-        return;
+    if (opts.skipBaseline) {
+        log.info('Skipping baseline tests (--skip-baseline)');
+    }
+    else {
+        log.info(`Running ${baselineTests.length} baseline tests${coverage.enableCoverageForBaseline ? ' (collecting coverage)' : ''}\u2026`);
+        const baselineOk = await adapter.runBaseline(baselineTests, {
+            collectCoverage: coverage.enableCoverageForBaseline,
+            perTestCoverage: coverage.wantsPerTestCoverage,
+        });
+        if (!baselineOk) {
+            process.exitCode = 1;
+            return;
+        }
+        log.info('\u2713 Baseline tests complete');
     }
-    log.info('\u2713 Baseline tests complete');
     // 6. Load coverage from baseline if we generated it
     const updatedCoverage = await loadCoverageAfterBaseline(coverage, cwd);
     // 7. Enumerate mutation variants
-    const variants = await enumerateAllVariants({
+    let variants = await enumerateAllVariants({
         cwd,
         targets,
         testMap,
@@ -138,18 +153,83 @@ export async function runOrchestrator(cliArgs, cwd) {
         log.info(msg);
         return;
     }
-    // 8. Prepare tasks and execute via worker pool
-    let tasks = prepareTasks(variants, updatedCoverage.perTestCoverage, directTestMap);
-    // Apply shard filter if requested
+    // Apply shard filter before type-checking so each shard only processes its own mutants
     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.');
+        variants = variants.filter((_, i) => i % total === index - 1);
+        log.info(`Shard ${index}/${total}: scoped to ${variants.length} variant(s)`);
+        if (!variants.length) {
+            log.info('No mutants in this shard. Exiting.');
             return;
         }
     }
+    // TypeScript pre-filtering (filter mutants that produce compile errors)
+    const tsEnabled = resolveTypescriptEnabled(opts.typescriptCheck, cfg, cwd);
+    let runnableVariants = variants;
+    if (tsEnabled) {
+        // Only return-value mutants change the expression type — operator mutants
+        // (equality, arithmetic, logical, etc.) always preserve the type.
+        const returnValueVariants = variants.filter((v) => v.name.startsWith('return'));
+        log.info(`Running TypeScript type checks on ${returnValueVariants.length} return-value mutant(s)...`);
+        const tsconfig = resolveTsconfigPath(cfg);
+        let tsSpinner = null;
+        if (process.stderr.isTTY) {
+            tsSpinner = render(createElement(PoolSpinner, {
+                message: `Type checking ${returnValueVariants.length} return-value mutant(s)...`,
+            }), { stdout: process.stderr, stderr: process.stderr });
+        }
+        let compileErrorIds;
+        try {
+            compileErrorIds = await checkTypes(returnValueVariants, tsconfig, cwd);
+        }
+        finally {
+            tsSpinner?.unmount();
+        }
+        if (compileErrorIds.size > 0) {
+            log.info(`\u2713 TypeScript: filtered ${compileErrorIds.size} mutant(s) with compile errors`);
+            runnableVariants = variants.filter((v) => !compileErrorIds.has(v.id));
+            // Pre-populate cache for compile-error mutants so they appear in summary
+            const compileErrorVariants = variants.filter((v) => compileErrorIds.has(v.id));
+            const compileErrorTasks = prepareTasks(compileErrorVariants, updatedCoverage.perTestCoverage, directTestMap);
+            for (const task of compileErrorTasks) {
+                cache[task.key] = {
+                    status: 'compile-error',
+                    file: task.v.file,
+                    line: task.v.line,
+                    col: task.v.col,
+                    mutator: task.v.name,
+                };
+            }
+        }
+    }
+    // 9. Generate schema files for each source file
+    const fallbackIds = new Set();
+    const variantsByFile = new Map();
+    for (const v of runnableVariants) {
+        const arr = variantsByFile.get(v.file) ?? [];
+        arr.push(v);
+        variantsByFile.set(v.file, arr);
+    }
+    const results = await Promise.all([...variantsByFile.entries()].map(async ([file, fileVariants]) => {
+        try {
+            const originalCode = await fs.promises.readFile(file, 'utf8');
+            const schemaPath = getSchemaFilePath(file);
+            await fs.promises.mkdir(path.dirname(schemaPath), { recursive: true });
+            const { schemaCode, fallbackIds: fileFallbacks } = generateSchema(originalCode, fileVariants);
+            await fs.promises.writeFile(schemaPath, schemaCode, 'utf8');
+            return fileFallbacks;
+        }
+        catch {
+            return new Set(fileVariants.map((v) => v.id));
+        }
+    }));
+    for (const ids of results) {
+        for (const id of ids)
+            fallbackIds.add(id);
+    }
+    log.debug(`Schema: ${runnableVariants.length - fallbackIds.size} embedded, ${fallbackIds.size} fallback`);
+    // 10. Prepare tasks and execute via worker pool
+    let tasks = prepareTasks(runnableVariants, updatedCoverage.perTestCoverage, directTestMap);
     await executePool({
         tasks,
         adapter,
@@ -160,5 +240,6 @@ export async function runOrchestrator(cliArgs, cwd) {
         reportFormat: opts.reportFormat,
         cwd,
         shard: opts.shard,
+        fallbackIds,
     });
 }

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

@@ -14,6 +14,8 @@ export interface PoolExecutionOptions {
         index: number;
         total: number;
     };
+    /** IDs of variants that must use the legacy redirect path (overlapping diff ranges). */
+    fallbackIds?: Set<string>;
 }
 /**
  * Execute all mutant tasks through the worker pool.

package/dist/runner/pool-executor.js

@@ -7,6 +7,7 @@ import { computeSummary, printSummary, buildJsonReport, } from '../utils/summary
 import { saveCacheAtomic } from './cache.js';
 import { cleanupMutineerDirs } from './cleanup.js';
 import { PoolSpinner } from '../utils/PoolSpinner.js';
+import { CompileErrors } from '../utils/CompileErrors.js';
 import { createLogger } from '../utils/logger.js';
 const log = createLogger('pool-executor');
 /**
@@ -23,7 +24,7 @@ export async function executePool(opts) {
     const mutationStartTime = Date.now();
     // Ensure we only finish once
     let finished = false;
-    const finishOnce = () => {
+    const finishOnce = async (interactive = true) => {
         if (finished)
             return;
         finished = true;
@@ -40,7 +41,15 @@ export async function executePool(opts) {
             log.info(`JSON report written to ${path.relative(process.cwd(), outPath)}`);
         }
         else {
-            printSummary(summary, cache, durationMs);
+            const compileErrorEntries = Object.values(cache).filter((e) => e.status === 'compile-error');
+            const useInteractive = interactive && process.stdout.isTTY && compileErrorEntries.length > 0;
+            printSummary(summary, cache, durationMs, {
+                skipCompileErrors: useInteractive,
+            });
+            if (useInteractive) {
+                const { waitUntilExit } = render(createElement(CompileErrors, { entries: compileErrorEntries, cwd }));
+                await waitUntilExit();
+            }
         }
         if (opts.minKillPercent !== undefined) {
             const killRateString = summary.killRate.toFixed(2);
@@ -80,6 +89,7 @@ export async function executePool(opts) {
     let nextIdx = 0;
     async function processTask(task) {
         const { v, tests, key, directTests } = task;
+        const { fallbackIds } = opts;
         const cached = cache[key];
         if (cached) {
             progress.update(cached.status);
@@ -104,6 +114,7 @@ export async function executePool(opts) {
             code: v.code,
             line: v.line,
             col: v.col,
+            isFallback: !fallbackIds || fallbackIds.has(v.id),
         }, tests);
         const status = result.status;
         let originalSnippet;
@@ -159,7 +170,7 @@ export async function executePool(opts) {
             return;
         signalCleanedUp = true;
         log.info(`\nReceived ${signal}, cleaning up...`);
-        finishOnce();
+        await finishOnce(false);
         await adapter.shutdown();
         await cleanupMutineerDirs(cwd);
         process.exit(1);
@@ -176,7 +187,7 @@ export async function executePool(opts) {
         process.removeAllListeners('SIGINT');
         process.removeAllListeners('SIGTERM');
         if (!signalCleanedUp) {
-            finishOnce();
+            await finishOnce();
             await adapter.shutdown();
             await cleanupMutineerDirs(cwd);
         }

package/dist/runner/shared/__tests__/mutant-paths.spec.js

@@ -2,7 +2,7 @@ import { describe, it, expect, afterEach } from 'vitest';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { getMutantFilePath } from '../mutant-paths.js';
+import { getMutantFilePath, getSchemaFilePath, getActiveIdFilePath, } from '../mutant-paths.js';
 let createdDirs = [];
 afterEach(() => {
     // Clean up any __mutineer__ directories we created
@@ -64,3 +64,32 @@ describe('getMutantFilePath', () => {
         expect(result).toBe(path.join(mutineerDir, 'foo_1.ts'));
     });
 });
+describe('getSchemaFilePath', () => {
+    it('returns path with _schema suffix and correct extension', () => {
+        const result = getSchemaFilePath('/src/foo.ts');
+        expect(result).toBe('/src/__mutineer__/foo_schema.ts');
+    });
+    it('preserves the original extension', () => {
+        const result = getSchemaFilePath('/src/component.vue');
+        expect(result).toBe('/src/__mutineer__/component_schema.vue');
+    });
+    it('does not create the __mutineer__ directory', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mutineer-schema-'));
+        createdDirs.push(tmpDir);
+        const srcFile = path.join(tmpDir, 'bar.ts');
+        const mutineerDir = path.join(tmpDir, '__mutineer__');
+        getSchemaFilePath(srcFile);
+        expect(fs.existsSync(mutineerDir)).toBe(false);
+    });
+});
+describe('getActiveIdFilePath', () => {
+    it('returns path under cwd/__mutineer__ keyed by workerId', () => {
+        const result = getActiveIdFilePath('w0', '/project');
+        expect(result).toBe('/project/__mutineer__/active_id_w0.txt');
+    });
+    it('produces distinct paths for different worker IDs', () => {
+        const a = getActiveIdFilePath('w0', '/cwd');
+        const b = getActiveIdFilePath('w1', '/cwd');
+        expect(a).not.toBe(b);
+    });
+});

package/dist/runner/shared/index.d.ts

@@ -4,6 +4,6 @@
  * This module provides common functionality used by both Jest and Vitest adapters,
  * including mutant file path generation and redirect state management.
  */
-export { getMutantFilePath } from './mutant-paths.js';
+export { getMutantFilePath, getSchemaFilePath, getActiveIdFilePath, } from './mutant-paths.js';
 export { setRedirect, getRedirect, clearRedirect, initialiseRedirectState, } from './redirect-state.js';
 export type { RedirectConfig } from './redirect-state.js';

package/dist/runner/shared/index.js

@@ -4,5 +4,5 @@
  * This module provides common functionality used by both Jest and Vitest adapters,
  * including mutant file path generation and redirect state management.
  */
-export { getMutantFilePath } from './mutant-paths.js';
+export { getMutantFilePath, getSchemaFilePath, getActiveIdFilePath, } from './mutant-paths.js';
 export { setRedirect, getRedirect, clearRedirect, initialiseRedirectState, } from './redirect-state.js';

package/dist/runner/shared/mutant-paths.d.ts

@@ -1,6 +1,23 @@
 /**
  * Shared utilities for managing mutant file paths.
  */
+/**
+ * Generate a file path for the schema file in the __mutineer__ directory.
+ * The schema file embeds all mutation variants for a source file.
+ *
+ * @param originalFile - Path to the original source file
+ * @returns Path where the schema file should be written (dir may not exist)
+ */
+export declare function getSchemaFilePath(originalFile: string): string;
+/**
+ * Generate the path for a worker's active-mutant-ID file.
+ * Each worker writes the active mutant ID here so test forks can read it.
+ *
+ * @param workerId - Unique worker identifier
+ * @param cwd - Project working directory
+ * @returns Absolute path for the active ID file
+ */
+export declare function getActiveIdFilePath(workerId: string, cwd: string): string;
 /**
  * Generate a file path for a mutant file in the __mutineer__ directory.
  *

package/dist/runner/shared/mutant-paths.js

@@ -3,6 +3,30 @@
  */
 import path from 'node:path';
 import fs from 'node:fs';
+/**
+ * Generate a file path for the schema file in the __mutineer__ directory.
+ * The schema file embeds all mutation variants for a source file.
+ *
+ * @param originalFile - Path to the original source file
+ * @returns Path where the schema file should be written (dir may not exist)
+ */
+export function getSchemaFilePath(originalFile) {
+    const dir = path.dirname(originalFile);
+    const ext = path.extname(originalFile);
+    const basename = path.basename(originalFile, ext);
+    return path.join(dir, '__mutineer__', `${basename}_schema${ext}`);
+}
+/**
+ * Generate the path for a worker's active-mutant-ID file.
+ * Each worker writes the active mutant ID here so test forks can read it.
+ *
+ * @param workerId - Unique worker identifier
+ * @param cwd - Project working directory
+ * @returns Absolute path for the active ID file
+ */
+export function getActiveIdFilePath(workerId, cwd) {
+    return path.join(cwd, '__mutineer__', `active_id_${workerId}.txt`);
+}
 /**
  * Generate a file path for a mutant file in the __mutineer__ directory.
  *

package/dist/runner/ts-checker-worker.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Worker thread entry point for parallel TypeScript type checking.
+ * Receives one file group, runs baseline + per-variant diagnose, posts results.
+ */
+export {};

package/dist/runner/ts-checker-worker.js

@@ -0,0 +1,66 @@
+/**
+ * Worker thread entry point for parallel TypeScript type checking.
+ * Receives one file group, runs baseline + per-variant diagnose, posts results.
+ */
+import { workerData, parentPort } from 'worker_threads';
+import ts from 'typescript';
+import path from 'node:path';
+import fs from 'node:fs';
+/** Stable fingerprint for a diagnostic. */
+function diagnosticKey(d) {
+    return `${d.code}:${d.start ?? -1}`;
+}
+/** Create a compiler host that serves `code` for `targetPath`. */
+function makeHost(options, targetPath, code) {
+    const host = ts.createCompilerHost(options);
+    const orig = host.getSourceFile.bind(host);
+    host.getSourceFile = (fileName, langOrOpts) => {
+        if (path.resolve(fileName) === targetPath) {
+            return ts.createSourceFile(fileName, code, langOrOpts);
+        }
+        return orig(fileName, langOrOpts);
+    };
+    return host;
+}
+/** Run semantic diagnostics for `code` in `targetPath`. */
+function diagnose(options, targetPath, code, oldProgram) {
+    const host = makeHost(options, targetPath, code);
+    const program = ts.createProgram({
+        rootNames: [targetPath],
+        options,
+        host,
+        oldProgram,
+    });
+    const sourceFile = program.getSourceFile(targetPath) ??
+        program.getSourceFile(path.relative(process.cwd(), targetPath));
+    if (!sourceFile) {
+        return { program, keys: new Set() };
+    }
+    const keys = new Set(program.getSemanticDiagnostics(sourceFile).map(diagnosticKey));
+    return { program, keys };
+}
+const { options, filePath, variants } = workerData;
+const resolvedPath = path.resolve(filePath);
+let originalCode = '';
+try {
+    originalCode = fs.readFileSync(resolvedPath, 'utf8');
+}
+catch {
+    // empty baseline — all mutant errors count as new
+}
+const { program: baseProgram, keys: baselineKeys } = diagnose(options, resolvedPath, originalCode, undefined);
+let prevProgram = baseProgram;
+const compileErrorIds = [];
+for (const variant of variants) {
+    const { program: mutProgram, keys: mutantKeys } = diagnose(options, resolvedPath, variant.code, prevProgram);
+    prevProgram = mutProgram;
+    let newErrors = 0;
+    for (const key of mutantKeys) {
+        if (!baselineKeys.has(key))
+            newErrors++;
+    }
+    if (newErrors > 0) {
+        compileErrorIds.push(variant.id);
+    }
+}
+parentPort.postMessage({ compileErrorIds });

package/dist/runner/ts-checker.d.ts

@@ -0,0 +1,36 @@
+/**
+ * TypeScript Type Checker for Mutants
+ *
+ * Pre-filters mutants that produce TypeScript compile errors before running
+ * them against tests. This avoids running mutations that would be trivially
+ * detected by the type system, saving significant test execution time.
+ *
+ * Strategy: noLib + noResolve (zero I/O) + baseline comparison
+ * -  noLib: true      → don't load lib.d.ts (huge, causes hangs)
+ * -  noResolve: true  → don't follow user imports (avoids loading project files)
+ * -  Baseline check   → type-check original file first; only flag mutants that
+ *                       introduce NEW errors not present in the original. This
+ *                       eliminates false positives from missing lib/import types.
+ */
+import ts from 'typescript';
+import type { MutineerConfig } from '../types/config.js';
+import type { Variant } from '../types/mutant.js';
+/**
+ * Run type checks for one file group synchronously. Used both by the sync
+ * fallback (test/dev environments) and by the worker thread.
+ */
+export declare function checkFileSync(options: ts.CompilerOptions, filePath: string, fileVariants: readonly Variant[]): string[];
+/**
+ * Check TypeScript types for mutated variants.
+ * Returns a Set of variant IDs that introduce NEW compile errors vs the original.
+ */
+export declare function checkTypes(variants: readonly Variant[], tsconfig: string | undefined, cwd: string): Promise<Set<string>>;
+/**
+ * Determine whether TypeScript type checking should run for this invocation.
+ * Precedence: CLI flag > config field > auto-detect (tsconfig.json presence).
+ */
+export declare function resolveTypescriptEnabled(cliFlag: boolean | undefined, config: MutineerConfig, cwd: string): boolean;
+/**
+ * Extract the tsconfig path from the MutineerConfig typescript option.
+ */
+export declare function resolveTsconfigPath(config: MutineerConfig): string | undefined;