@mutineerjs/mutineer 0.1.0

package/dist/runner/shared/redirect-state.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared redirect state management for mutation testing.
+ *
+ * This module provides a centralized way to manage the redirect configuration
+ * that tells test runners to load mutant code instead of the original source.
+ *
+ * Both Jest and Vitest adapters use this to coordinate file redirection during
+ * test execution.
+ */
+declare global {
+    var __mutineer_redirect__: {
+        from: string | null;
+        to: string | null;
+    } | undefined;
+}
+/**
+ * Configuration for redirecting file imports/requires.
+ */
+export interface RedirectConfig {
+    /** Absolute path to the original source file */
+    readonly from: string;
+    /** Absolute path to the mutant file */
+    readonly to: string;
+}
+/**
+ * Initialize the global redirect state.
+ * Must be called once at module load time.
+ */
+export declare function initializeRedirectState(): void;
+/**
+ * Set the active redirect configuration.
+ *
+ * @param config - The redirect configuration
+ */
+export declare function setRedirect(config: RedirectConfig): void;
+/**
+ * Get the current redirect configuration.
+ *
+ * @returns The redirect config if one is active, null otherwise
+ */
+export declare function getRedirect(): RedirectConfig | null;
+/**
+ * Clear the redirect configuration.
+ */
+export declare function clearRedirect(): void;

package/dist/runner/shared/redirect-state.js

@@ -0,0 +1,50 @@
+/**
+ * Shared redirect state management for mutation testing.
+ *
+ * This module provides a centralized way to manage the redirect configuration
+ * that tells test runners to load mutant code instead of the original source.
+ *
+ * Both Jest and Vitest adapters use this to coordinate file redirection during
+ * test execution.
+ */
+/**
+ * Initialize the global redirect state.
+ * Must be called once at module load time.
+ */
+export function initializeRedirectState() {
+    globalThis.__mutineer_redirect__ = { from: null, to: null };
+}
+/**
+ * Set the active redirect configuration.
+ *
+ * @param config - The redirect configuration
+ */
+export function setRedirect(config) {
+    globalThis.__mutineer_redirect__ = {
+        from: config.from,
+        to: config.to,
+    };
+}
+/**
+ * Get the current redirect configuration.
+ *
+ * @returns The redirect config if one is active, null otherwise
+ */
+export function getRedirect() {
+    const redirect = globalThis.__mutineer_redirect__;
+    if (!redirect?.from || !redirect?.to) {
+        return null;
+    }
+    return {
+        from: redirect.from,
+        to: redirect.to,
+    };
+}
+/**
+ * Clear the redirect configuration.
+ */
+export function clearRedirect() {
+    globalThis.__mutineer_redirect__ = { from: null, to: null };
+}
+// Initialize on module load
+initializeRedirectState();

package/dist/runner/shared-module-redirect.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared module redirection utilities for both Jest and Vitest runners.
+ *
+ * This module provides common functionality for intercepting module resolution
+ * and redirecting imports to mutated versions of source files.
+ */
+export interface MutantRedirect {
+    from: string | null;
+    to: string | null;
+}
+declare global {
+    var __mutineer_redirect__: MutantRedirect | undefined;
+}
+/**
+ * Get the path where a mutant should be written.
+ * Mutants are stored in __mutineer__/ subdirectories alongside source files.
+ *
+ * @param originalFile - The original source file path
+ * @param mutantId - The mutation ID
+ * @returns Path to the mutant file in __mutineer__/ directory
+ */
+export declare function getMutantFilePath(originalFile: string, mutantId: string): string;
+/**
+ * Get the current redirect configuration from globalThis.
+ * Used by both Jest and Vitest to check if a module should be redirected.
+ *
+ * @returns Object with normalized from/to paths, or null if no redirect is active
+ */
+export declare function getActiveRedirect(): {
+    from: string;
+    to: string;
+} | null;
+/**
+ * Initialize the global redirect state.
+ * Should be called once when the runtime starts.
+ */
+export declare function initializeRedirect(): void;
+/**
+ * Set a redirect for module resolution.
+ *
+ * @param originalFile - The original source file (absolute path)
+ * @param mutantPath - The mutant file path
+ */
+export declare function setRedirect(originalFile: string, mutantPath: string): void;
+/**
+ * Clear the current redirect.
+ */
+export declare function clearRedirect(): void;
+/**
+ * Check if a given file path matches the current redirect source.
+ * Handles path normalization and extension matching.
+ *
+ * @param filePath - The file path to check
+ * @returns true if this file should be redirected
+ */
+export declare function shouldRedirectPath(filePath: string): boolean;

package/dist/runner/shared-module-redirect.js

@@ -0,0 +1,84 @@
+/**
+ * Shared module redirection utilities for both Jest and Vitest runners.
+ *
+ * This module provides common functionality for intercepting module resolution
+ * and redirecting imports to mutated versions of source files.
+ */
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+/**
+ * Get the path where a mutant should be written.
+ * Mutants are stored in __mutineer__/ subdirectories alongside source files.
+ *
+ * @param originalFile - The original source file path
+ * @param mutantId - The mutation ID
+ * @returns Path to the mutant file in __mutineer__/ directory
+ */
+export function getMutantFilePath(originalFile, mutantId) {
+    const dir = path.dirname(originalFile);
+    const ext = path.extname(originalFile);
+    const basename = path.basename(originalFile, ext);
+    const mutineerDir = path.join(dir, '__mutineer__');
+    if (!fs.existsSync(mutineerDir)) {
+        fs.mkdirSync(mutineerDir, { recursive: true });
+    }
+    const idMatch = mutantId.match(/#(\d+)$/);
+    const suffix = idMatch ? idMatch[1] : mutantId.replace(/[^a-zA-Z0-9]/g, '_').slice(0, 20);
+    return path.join(mutineerDir, `${basename}_${suffix}${ext}`);
+}
+/**
+ * Get the current redirect configuration from globalThis.
+ * Used by both Jest and Vitest to check if a module should be redirected.
+ *
+ * @returns Object with normalized from/to paths, or null if no redirect is active
+ */
+export function getActiveRedirect() {
+    const redirect = globalThis.__mutineer_redirect__;
+    if (!redirect?.from || !redirect?.to) {
+        return null;
+    }
+    return {
+        from: path.resolve(redirect.from),
+        to: redirect.to,
+    };
+}
+/**
+ * Initialize the global redirect state.
+ * Should be called once when the runtime starts.
+ */
+export function initializeRedirect() {
+    globalThis.__mutineer_redirect__ = { from: null, to: null };
+}
+/**
+ * Set a redirect for module resolution.
+ *
+ * @param originalFile - The original source file (absolute path)
+ * @param mutantPath - The mutant file path
+ */
+export function setRedirect(originalFile, mutantPath) {
+    globalThis.__mutineer_redirect__ = {
+        from: path.resolve(originalFile),
+        to: mutantPath,
+    };
+}
+/**
+ * Clear the current redirect.
+ */
+export function clearRedirect() {
+    globalThis.__mutineer_redirect__ = { from: null, to: null };
+}
+/**
+ * Check if a given file path matches the current redirect source.
+ * Handles path normalization and extension matching.
+ *
+ * @param filePath - The file path to check
+ * @returns true if this file should be redirected
+ */
+export function shouldRedirectPath(filePath) {
+    const redirect = getActiveRedirect();
+    if (!redirect) {
+        return false;
+    }
+    const normalized = path.resolve(filePath);
+    return normalized === redirect.from;
+}

package/dist/runner/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Test Runner Adapter Interface
+ *
+ * This module defines the interface that all test runner adapters must implement.
+ * Adapters abstract test runner-specific details (Vitest, Jest, etc.) from the
+ * mutation testing orchestrator.
+ */
+import type { MutineerConfig } from '../types/config.js';
+import type { MutantPayload, MutantRunResult } from '../types/mutant.js';
+/**
+ * Options for initializing a test runner adapter.
+ */
+export interface TestRunnerAdapterOptions {
+    readonly cwd: string;
+    readonly concurrency: number;
+    readonly timeoutMs: number;
+    readonly config: MutineerConfig;
+    readonly cliArgs: string[];
+}
+/**
+ * Coverage-related configuration detected from the test runner.
+ */
+export interface CoverageConfig {
+    /** Whether per-test coverage is enabled in the config */
+    readonly perTestEnabled: boolean;
+    /** Whether coverage is enabled in the config */
+    readonly coverageEnabled: boolean;
+}
+/**
+ * Interface that all test runner adapters must implement.
+ *
+ * A test runner adapter handles:
+ * - Running baseline tests before mutation testing
+ * - Running mutant tests (with code substitution)
+ * - Managing worker pools for parallel execution
+ * - Detecting coverage configuration
+ */
+export interface TestRunnerAdapter {
+    /**
+     * The name of the test runner (e.g., 'vitest', 'jest').
+     */
+    readonly name: string;
+    /**
+     * Initialize the adapter (start worker pools, etc.).
+     * Must be called before running tests.
+     */
+    init(concurrencyOverride?: number): Promise<void>;
+    /**
+     * Run baseline tests to ensure they pass before mutation testing.
+     * @param tests - Array of test file paths to run
+     * @param options - Options for the baseline run
+     * @returns true if all tests pass, false otherwise
+     */
+    runBaseline(tests: readonly string[], options: BaselineOptions): Promise<boolean>;
+    /**
+     * Run a single mutant against its associated tests.
+     * @param mutant - The mutation to test
+     * @param tests - Array of test file paths to run
+     * @returns Result indicating if the mutant was killed, escaped, or errored
+     */
+    runMutant(mutant: MutantPayload, tests: readonly string[]): Promise<MutantRunResult>;
+    /**
+     * Shutdown the adapter (stop worker pools, cleanup, etc.).
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Check if the coverage provider is installed.
+     */
+    hasCoverageProvider(): boolean;
+    /**
+     * Detect coverage configuration from the test runner config.
+     */
+    detectCoverageConfig(): Promise<CoverageConfig>;
+}
+/**
+ * Options for running baseline tests.
+ */
+export interface BaselineOptions {
+    /** Whether to collect coverage during baseline run */
+    readonly collectCoverage: boolean;
+    /** Whether to collect per-test coverage */
+    readonly perTestCoverage: boolean;
+}
+/**
+ * Factory function type for creating test runner adapters.
+ */
+export type TestRunnerAdapterFactory = (options: TestRunnerAdapterOptions) => TestRunnerAdapter;
+export type { MutantPayload, MutantRunResult, MutantRunStatus, } from '../types/mutant.js';

package/dist/runner/types.js

@@ -0,0 +1,8 @@
+/**
+ * Test Runner Adapter Interface
+ *
+ * This module defines the interface that all test runner adapters must implement.
+ * Adapters abstract test runner-specific details (Vitest, Jest, etc.) from the
+ * mutation testing orchestrator.
+ */
+export {};

package/dist/runner/variants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Variant Enumeration Module
+ *
+ * Functions for enumerating mutation variants from source files.
+ * Handles both regular modules and Vue SFC files.
+ */
+import type { MutateTarget } from '../types/config.js';
+import type { MutantPayload } from '../types/mutant.js';
+/**
+ * Get file path from target (handles both string and object forms).
+ */
+export declare function getTargetFile(t: MutateTarget): string;
+/**
+ * Enumerate all mutation variants for a single target file.
+ */
+export declare function enumerateVariantsForTarget(root: string, t: MutateTarget, include?: readonly string[], exclude?: readonly string[], max?: number): Promise<MutantPayload[]>;
+/**
+ * Filter tests to only those that cover a specific line in a file.
+ */
+export declare function filterTestsByCoverage(perTest: Map<string, Map<string, Set<number>>>, tests: readonly string[], filePath: string, line: number): string[];
+export type { Variant } from '../types/mutant.js';

package/dist/runner/variants.js

@@ -0,0 +1,66 @@
+/**
+ * Variant Enumeration Module
+ *
+ * Functions for enumerating mutation variants from source files.
+ * Handles both regular modules and Vue SFC files.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { mutateVueSfcScriptSetup } from '../core/sfc.js';
+import { mutateModuleSource } from '../core/module.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('variants');
+/**
+ * Get file path from target (handles both string and object forms).
+ */
+export function getTargetFile(t) {
+    return typeof t === 'string' ? t : t.file;
+}
+/**
+ * Enumerate all mutation variants for a single target file.
+ */
+export async function enumerateVariantsForTarget(root, t, include, exclude, max) {
+    // Normalize target: string → { file: string }, object → as-is
+    const file = typeof t === 'string' ? t : t.file;
+    const explicitKind = typeof t === 'string' ? undefined : t.kind;
+    const abs = path.isAbsolute(file) ? file : path.join(root, file);
+    const includeArr = include ? [...include] : undefined;
+    const excludeArr = exclude ? [...exclude] : undefined;
+    try {
+        const code = await fs.readFile(abs, 'utf8');
+        // Auto-detect kind from file extension if not specified
+        const kind = explicitKind ?? (abs.endsWith('.vue') ? 'vue:script-setup' : 'module');
+        const list = kind === 'vue:script-setup'
+            ? mutateVueSfcScriptSetup(abs, code, includeArr, excludeArr, max)
+            : mutateModuleSource(code, includeArr, excludeArr, max);
+        return list.map((v, i) => ({
+            id: `${path.basename(abs)}#${i}`,
+            name: v.name,
+            file: abs,
+            code: v.code,
+            line: v.line,
+            col: v.col,
+        }));
+    }
+    catch (err) {
+        const detail = typeof err === 'object' && err !== null && 'stack' in err
+            ? err.stack
+            : err;
+        log.debug(`Failed to enumerate variants for ${abs}:`, detail);
+        return [];
+    }
+}
+/**
+ * Filter tests to only those that cover a specific line in a file.
+ */
+export function filterTestsByCoverage(perTest, tests, filePath, line) {
+    return tests.filter((testPath) => {
+        const filesCovered = perTest.get(testPath);
+        if (!filesCovered)
+            return true;
+        const lines = filesCovered.get(filePath);
+        if (!lines)
+            return true;
+        return lines.has(line);
+    });
+}

package/dist/runner/vitest/__tests__/adapter.spec.d.ts

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

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

@@ -0,0 +1,131 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import { createVitestAdapter, isCoverageRequestedInArgs } from '../adapter.js';
+// Mock VitestPool to avoid spinning processes
+var poolInstance = null;
+var poolCtorOpts = null;
+vi.mock('../pool.js', () => {
+    class MockPool {
+        constructor(opts) {
+            this.init = vi.fn();
+            this.run = vi.fn();
+            this.shutdown = vi.fn();
+            poolCtorOpts = opts;
+            poolInstance = this;
+        }
+    }
+    return { VitestPool: MockPool };
+});
+// Mock spawn for baseline runs
+var spawnMock;
+vi.mock('node:child_process', async () => {
+    const actual = await vi.importActual('node:child_process');
+    spawnMock = vi.fn();
+    return { ...actual, spawn: spawnMock };
+});
+function makeAdapter(opts = {}) {
+    return createVitestAdapter({
+        cwd: opts.cwd ?? process.cwd(),
+        concurrency: opts.concurrency ?? 2,
+        timeoutMs: opts.timeoutMs ?? 1000,
+        config: opts.config ?? { vitestConfig: undefined },
+        cliArgs: opts.cliArgs ?? ['--changed'],
+    });
+}
+describe('Vitest adapter', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('initializes pool with override concurrency', async () => {
+        const adapter = makeAdapter();
+        await adapter.init(5);
+        expect(poolInstance?.init).toHaveBeenCalledTimes(1);
+        expect(poolCtorOpts.concurrency).toBe(5);
+    });
+    it('maps pool result to mutant status', async () => {
+        poolInstance = null;
+        poolCtorOpts = null;
+        const adapter = makeAdapter();
+        await adapter.init();
+        poolInstance.run.mockResolvedValueOnce({ killed: true, durationMs: 10 });
+        const res = await adapter.runMutant({ id: '1', name: 'm', file: 'f', code: 'c', line: 1, col: 1 }, ['t']);
+        expect(res).toEqual({ status: 'killed', durationMs: 10, error: undefined });
+    });
+    it('maps pool timeout errors to timeout status', async () => {
+        const adapter = makeAdapter();
+        await adapter.init();
+        poolInstance.run.mockResolvedValueOnce({
+            killed: true,
+            durationMs: 15,
+            error: 'timeout',
+        });
+        const res = await adapter.runMutant({ id: '1', name: 'm', file: 'f', code: 'c', line: 1, col: 1 }, ['t']);
+        expect(res).toEqual({ status: 'timeout', durationMs: 15, error: 'timeout' });
+    });
+    it('maps pool errors to error status', async () => {
+        const adapter = makeAdapter();
+        await adapter.init();
+        poolInstance.run.mockResolvedValueOnce({
+            killed: true,
+            durationMs: 12,
+            error: 'crash',
+        });
+        const res = await adapter.runMutant({ id: '1', name: 'm', file: 'f', code: 'c', line: 1, col: 1 }, ['t']);
+        expect(res).toEqual({ status: 'error', durationMs: 12, error: 'crash' });
+    });
+    it('returns error status on pool throw', async () => {
+        const adapter = makeAdapter();
+        await adapter.init();
+        poolInstance.run.mockRejectedValueOnce(new Error('boom'));
+        const res = await adapter.runMutant({ id: '1', name: 'm', file: 'f', code: 'c', line: 1, col: 1 }, ['t']);
+        expect(res.status).toBe('error');
+    });
+    it('includes coverage args for baseline when requested', async () => {
+        const adapter = makeAdapter({ cliArgs: [] });
+        spawnMock.mockImplementationOnce(() => ({
+            on: (evt, cb) => {
+                if (evt === 'exit')
+                    cb(0);
+            },
+        }));
+        const ok = await adapter.runBaseline(['test-a'], {
+            collectCoverage: true,
+            perTestCoverage: true,
+        });
+        expect(ok).toBe(true);
+        const call = spawnMock.mock.calls[0];
+        const args = call[1];
+        expect(args.join(' ')).toContain('--coverage.enabled=true');
+        expect(args.join(' ')).toContain('--coverage.perTest=true');
+    });
+    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');
+        await fs.writeFile(cfgPath, 'export default { coverage: { enabled: true }, test: { coverage: { perTest: true } } }');
+        try {
+            const adapter = makeAdapter({
+                cwd: tmp,
+                config: { vitestConfig: 'vitest.config.ts' },
+            });
+            const coverage = await adapter.detectCoverageConfig();
+            expect(coverage.coverageEnabled).toBe(true);
+            expect(coverage.perTestEnabled).toBe(true);
+        }
+        finally {
+            await fs.rm(tmp, { recursive: true, force: true });
+        }
+    });
+});
+describe('isCoverageRequestedInArgs', () => {
+    it('detects enabled coverage flags', () => {
+        expect(isCoverageRequestedInArgs(['--coverage'])).toBe(true);
+        expect(isCoverageRequestedInArgs(['--coverage.enabled=true'])).toBe(true);
+        expect(isCoverageRequestedInArgs(['--coverage.enabled=false'])).toBe(false);
+        expect(isCoverageRequestedInArgs(['--no-coverage'])).toBe(false);
+    });
+});

package/dist/runner/vitest/__tests__/plugin.spec.d.ts

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

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

@@ -0,0 +1,65 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { poolMutineerPlugin } from '../plugin.js';
+function getLoadFn() {
+    const plugin = poolMutineerPlugin();
+    if (Array.isArray(plugin)) {
+        return plugin[0]?.load;
+    }
+    if (plugin && typeof plugin === 'object' && 'load' in plugin) {
+        return plugin.load;
+    }
+    return undefined;
+}
+describe('poolMutineerPlugin', () => {
+    afterEach(() => {
+        ;
+        globalThis.__mutineer_redirect__ = undefined;
+    });
+    it('returns null when no redirect is configured', () => {
+        const load = getLoadFn();
+        const result = load?.('/some/file.ts');
+        expect(result).toBeNull();
+    });
+    it('returns the mutated file when the id matches the redirect target', async () => {
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-pool-plugin-'));
+        const fromPath = path.join(tmpDir, 'source.ts');
+        const mutatedPath = path.join(tmpDir, 'mutated.ts');
+        await fs.writeFile(fromPath, 'export const original = true\n', 'utf8');
+        await fs.writeFile(mutatedPath, 'export const mutated = true\n', 'utf8');
+        try {
+            ;
+            globalThis.__mutineer_redirect__ = {
+                from: fromPath,
+                to: mutatedPath,
+            };
+            const load = getLoadFn();
+            const result = load?.(fromPath);
+            expect(result).toBe('export const mutated = true\n');
+        }
+        finally {
+            await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    it('ignores modules that do not match the redirect', async () => {
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-pool-plugin-'));
+        const fromPath = path.join(tmpDir, 'source.ts');
+        const mutatedPath = path.join(tmpDir, 'mutated.ts');
+        await fs.writeFile(mutatedPath, 'export const mutated = true\n', 'utf8');
+        try {
+            ;
+            globalThis.__mutineer_redirect__ = {
+                from: fromPath,
+                to: mutatedPath,
+            };
+            const load = getLoadFn();
+            const result = load?.(path.join(tmpDir, 'other.ts?import'));
+            expect(result).toBeNull();
+        }
+        finally {
+            await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/runner/vitest/__tests__/pool.spec.d.ts

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