@mutineerjs/mutineer 0.1.0

package/dist/runner/adapters/vitest.js

@@ -0,0 +1,267 @@
+/**
+ * Vitest Test Runner Adapter
+ *
+ * Implements the TestRunnerAdapter interface for Vitest.
+ * Handles baseline test runs, mutant execution via worker pool,
+ * and coverage configuration detection.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { VitestPool } from '../pool/index.js';
+const require = createRequire(import.meta.url);
+/**
+ * Resolve the Vitest CLI entry point.
+ */
+function resolveVitestPath() {
+    try {
+        return require.resolve('vitest/vitest.mjs');
+    }
+    catch {
+        const pkgJson = require.resolve('vitest/package.json');
+        return path.join(path.dirname(pkgJson), 'vitest.mjs');
+    }
+}
+/**
+ * Strip mutineer-specific CLI args that shouldn't be passed to Vitest.
+ */
+function stripMutineerArgs(args) {
+    const out = [];
+    const consumeNext = new Set([
+        '--concurrency',
+        '--progress',
+        '--min-kill-percent',
+        '--config',
+        '-c',
+        '--coverage-file',
+    ]);
+    const dropExact = new Set([
+        '-m',
+        '--mutate',
+        '--changed',
+        '--changed-with-deps',
+        '--only-covered-lines',
+        '--per-test-coverage',
+        '--perTestCoverage',
+    ]);
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (dropExact.has(a))
+            continue;
+        if (consumeNext.has(a)) {
+            i++;
+            continue;
+        }
+        if (a.startsWith('--min-kill-percent='))
+            continue;
+        if (a.startsWith('--config=') || a.startsWith('-c='))
+            continue;
+        out.push(a);
+    }
+    return out;
+}
+/**
+ * Ensure the Vitest config arg is included if specified.
+ */
+function ensureConfigArg(args, vitestConfig, cwd) {
+    if (!vitestConfig)
+        return args;
+    if (args.some((a) => a === '--config' || a === '-c' || a.startsWith('--config=') || a.startsWith('-c='))) {
+        return args;
+    }
+    const resolved = cwd ? path.resolve(cwd, vitestConfig) : vitestConfig;
+    return [...args, '--config', resolved];
+}
+/**
+ * Build Vitest CLI arguments for the given mode.
+ */
+function buildVitestArgs(args, mode) {
+    const result = [...args];
+    if (!result.includes('run') && !result.includes('--run'))
+        result.unshift('run');
+    if (!result.some((a) => a.startsWith('--watch')))
+        result.push('--watch=false');
+    if (!result.some((a) => a.startsWith('--passWithNoTests')))
+        result.push('--passWithNoTests');
+    if (mode === 'baseline-with-coverage') {
+        if (!result.some((a) => a.startsWith('--coverage'))) {
+            result.push('--coverage.enabled=true', '--coverage.reporter=json');
+        }
+        if (!result.some((a) => a.startsWith('--coverage.perTest='))) {
+            result.push('--coverage.perTest=true');
+        }
+    }
+    return result;
+}
+/**
+ * Vitest adapter implementation.
+ */
+export class VitestAdapter {
+    constructor(options) {
+        this.name = 'vitest';
+        this.pool = null;
+        this.baseArgs = [];
+        this.options = options;
+        this.vitestPath = resolveVitestPath();
+        // Prepare base args by stripping mutineer-specific flags
+        const stripped = stripMutineerArgs(options.cliArgs);
+        this.baseArgs = ensureConfigArg(stripped, options.config.vitestConfig, options.cwd);
+    }
+    async init(concurrencyOverride) {
+        const workerCount = Math.max(1, concurrencyOverride ?? this.options.concurrency);
+        this.pool = new VitestPool({
+            cwd: this.options.cwd,
+            concurrency: workerCount,
+            vitestConfig: this.options.config.vitestConfig,
+            timeoutMs: this.options.timeoutMs,
+            debug: this.options.debug,
+        });
+        await this.pool.init();
+    }
+    async runBaseline(tests, options) {
+        const mode = options.collectCoverage ? 'baseline-with-coverage' : 'baseline';
+        const args = buildVitestArgs(this.baseArgs, mode);
+        return new Promise((resolve) => {
+            const env = { ...process.env };
+            env.VITEST_WATCH = 'false';
+            if (!env.CI)
+                env.CI = '1';
+            const child = spawn(process.execPath, [this.vitestPath, ...args, ...tests], {
+                cwd: this.options.cwd,
+                stdio: ['ignore', 'inherit', 'inherit'],
+                env,
+            });
+            child.on('error', (err) => {
+                if (this.options.debug)
+                    console.error('Failed to spawn vitest process', err);
+                resolve(false);
+            });
+            child.on('exit', (code) => {
+                resolve(code === 0);
+            });
+        });
+    }
+    async runMutant(mutant, tests) {
+        if (!this.pool) {
+            throw new Error('VitestAdapter not initialized. Call init() first.');
+        }
+        try {
+            const result = await this.pool.run(mutant, [...tests]);
+            if (result.error === 'timeout') {
+                return {
+                    status: 'timeout',
+                    durationMs: result.durationMs,
+                    error: result.error,
+                };
+            }
+            if (result.error) {
+                return {
+                    status: 'error',
+                    durationMs: result.durationMs,
+                    error: result.error,
+                };
+            }
+            return {
+                status: result.killed ? 'killed' : 'escaped',
+                durationMs: result.durationMs,
+                error: result.error,
+            };
+        }
+        catch (err) {
+            return {
+                status: 'error',
+                durationMs: 0,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    async shutdown() {
+        if (this.pool) {
+            await this.pool.shutdown();
+            this.pool = null;
+        }
+    }
+    hasCoverageProvider() {
+        try {
+            require.resolve('@vitest/coverage-v8/package.json', { paths: [this.options.cwd] });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async detectCoverageConfig() {
+        const configPath = this.options.config.vitestConfig;
+        if (!configPath) {
+            return { perTestEnabled: false, coverageEnabled: false };
+        }
+        try {
+            const abs = path.isAbsolute(configPath) ? configPath : path.join(this.options.cwd, configPath);
+            const content = await fs.readFile(abs, 'utf8');
+            const perTestEnabled = /perTest\s*:\s*true/.test(content);
+            let coverageEnabled = false;
+            if (!/coverage\s*\.\s*enabled\s*:\s*false/.test(content) && !/coverage\s*:\s*false/.test(content)) {
+                coverageEnabled = /coverage\s*:/.test(content);
+            }
+            return { perTestEnabled, coverageEnabled };
+        }
+        catch {
+            return { perTestEnabled: false, coverageEnabled: false };
+        }
+    }
+}
+/**
+ * Check if coverage is requested via CLI args.
+ */
+export function isCoverageRequestedInArgs(args) {
+    let requested = false;
+    let disabled = false;
+    const isFalsey = (v) => typeof v === 'string' && /^(false|0|off)$/i.test(v);
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--no-coverage') {
+            disabled = true;
+            continue;
+        }
+        if (arg === '--coverage') {
+            requested = true;
+            continue;
+        }
+        if (arg === '--coverage.enabled') {
+            const next = args[i + 1];
+            if (isFalsey(next))
+                disabled = true;
+            else
+                requested = true;
+            continue;
+        }
+        if (arg.startsWith('--coverage.enabled=')) {
+            const val = arg.slice('--coverage.enabled='.length);
+            if (isFalsey(val))
+                disabled = true;
+            else
+                requested = true;
+            continue;
+        }
+        if (arg.startsWith('--coverage=')) {
+            const val = arg.slice('--coverage='.length);
+            if (isFalsey(val))
+                disabled = true;
+            else
+                requested = true;
+            continue;
+        }
+        if (arg.startsWith('--coverage.')) {
+            requested = true;
+            continue;
+        }
+    }
+    return requested && !disabled;
+}
+/**
+ * Factory function for creating VitestAdapter instances.
+ */
+export function createVitestAdapter(options) {
+    return new VitestAdapter(options);
+}

package/dist/runner/args.d.ts

@@ -0,0 +1,50 @@
+/**
+ * CLI Argument Parsing
+ *
+ * Pure functions for parsing command-line arguments.
+ * Easy to test without side effects.
+ */
+import type { MutineerConfig } from '../types/config.js';
+/**
+ * Parsed CLI options for mutation testing.
+ */
+export interface ParsedCliOptions {
+    readonly configPath: string | undefined;
+    readonly wantsChanged: boolean;
+    readonly wantsChangedWithDeps: boolean;
+    readonly wantsOnlyCoveredLines: boolean;
+    readonly wantsPerTestCoverage: boolean;
+    readonly coverageFilePath: string | undefined;
+    readonly concurrency: number;
+    readonly progressMode: 'bar' | 'list' | 'quiet';
+    readonly minKillPercent: number | undefined;
+    readonly runner: 'vitest' | 'jest';
+}
+/**
+ * Parse a numeric CLI flag value.
+ */
+export declare function parseFlagNumber(raw: string, flag: string): number;
+/**
+ * Read a numeric flag from CLI args.
+ */
+export declare function readNumberFlag(args: readonly string[], flag: string): number | undefined;
+/**
+ * Read a string flag from CLI args.
+ */
+export declare function readStringFlag(args: readonly string[], flag: string, alias?: string): string | undefined;
+/**
+ * Validate a percentage value (0-100).
+ */
+export declare function validatePercent(value: number | undefined, source: string): number | undefined;
+/**
+ * Parse concurrency from CLI args or use default.
+ */
+export declare function parseConcurrency(args: readonly string[]): number;
+/**
+ * Parse progress mode from CLI args.
+ */
+export declare function parseProgressMode(args: readonly string[]): 'bar' | 'list' | 'quiet';
+/**
+ * Parse all CLI options.
+ */
+export declare function parseCliOptions(args: readonly string[], cfg: MutineerConfig): ParsedCliOptions;

package/dist/runner/args.js

@@ -0,0 +1,123 @@
+/**
+ * CLI Argument Parsing
+ *
+ * Pure functions for parsing command-line arguments.
+ * Easy to test without side effects.
+ */
+import os from 'node:os';
+/**
+ * Parse a numeric CLI flag value.
+ */
+export function parseFlagNumber(raw, flag) {
+    const num = Number(raw);
+    if (!Number.isFinite(num)) {
+        throw new Error(`Invalid value for ${flag}: ${raw}`);
+    }
+    return num;
+}
+/**
+ * Read a numeric flag from CLI args.
+ */
+export function readNumberFlag(args, flag) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === flag) {
+            const value = args[i + 1];
+            if (value === undefined)
+                throw new Error(`Expected a numeric value after ${flag}`);
+            return parseFlagNumber(value, flag);
+        }
+        if (arg.startsWith(`${flag}=`)) {
+            const value = arg.slice(flag.length + 1);
+            return parseFlagNumber(value, flag);
+        }
+    }
+    return undefined;
+}
+/**
+ * Read a string flag from CLI args.
+ */
+export function readStringFlag(args, flag, alias) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === flag || (alias && arg === alias)) {
+            const value = args[i + 1];
+            if (value === undefined) {
+                throw new Error(`Expected a value after ${arg}`);
+            }
+            return value;
+        }
+        if (arg.startsWith(`${flag}=`)) {
+            return arg.slice(flag.length + 1);
+        }
+        if (alias && arg.startsWith(`${alias}=`)) {
+            return arg.slice(alias.length + 1);
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate a percentage value (0-100).
+ */
+export function validatePercent(value, source) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isFinite(value)) {
+        throw new Error(`Invalid ${source}: expected a number between 0 and 100`);
+    }
+    if (value < 0 || value > 100) {
+        throw new Error(`Invalid ${source}: expected value between 0 and 100 (received ${value})`);
+    }
+    return value;
+}
+/**
+ * Parse concurrency from CLI args or use default.
+ */
+export function parseConcurrency(args) {
+    const concIdx = args.indexOf('--concurrency');
+    const userConc = concIdx >= 0 ? Math.max(1, parseInt(args[concIdx + 1] || '', 10) || 0) : 0;
+    const defaultConc = Math.max(1, os.cpus().length - 1);
+    return userConc || defaultConc;
+}
+/**
+ * Parse progress mode from CLI args.
+ */
+export function parseProgressMode(args) {
+    const progIdx = args.indexOf('--progress');
+    const modeArg = progIdx >= 0 ? args[progIdx + 1] || 'bar' : 'bar';
+    return modeArg === 'list' ? 'list' : modeArg === 'quiet' ? 'quiet' : 'bar';
+}
+/**
+ * Parse all CLI options.
+ */
+export function parseCliOptions(args, cfg) {
+    const configPath = readStringFlag(args, '--config', '-c');
+    const wantsChanged = args.includes('--changed');
+    const wantsChangedWithDeps = args.includes('--changed-with-deps');
+    const wantsOnlyCoveredLines = args.includes('--only-covered-lines') || cfg.onlyCoveredLines === true;
+    const wantsPerTestCoverage = args.includes('--per-test-coverage') || cfg.perTestCoverage === true;
+    const coverageFilePath = readStringFlag(args, '--coverage-file') ?? cfg.coverageFile;
+    const concurrency = parseConcurrency(args);
+    const progressMode = parseProgressMode(args);
+    const runnerFlag = readStringFlag(args, '--runner');
+    const runner = runnerFlag === 'jest' || runnerFlag === 'vitest'
+        ? runnerFlag
+        : cfg.runner === 'jest'
+            ? 'jest'
+            : 'vitest';
+    const cliKillPercent = validatePercent(readNumberFlag(args, '--min-kill-percent'), '--min-kill-percent');
+    const configKillPercent = validatePercent(cfg.minKillPercent, 'mutineer.config minKillPercent');
+    const minKillPercent = cliKillPercent ?? configKillPercent;
+    return {
+        configPath,
+        wantsChanged,
+        wantsChangedWithDeps,
+        wantsOnlyCoveredLines,
+        wantsPerTestCoverage,
+        coverageFilePath,
+        concurrency,
+        progressMode,
+        minKillPercent,
+        runner,
+    };
+}

package/dist/runner/cache.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cache Management Module
+ *
+ * Pure functions for managing mutation testing cache.
+ * Handles reading, writing, and decoding cache entries.
+ */
+import type { MutantCacheEntry } from '../types/mutant.js';
+/**
+ * Clear the cache file at the start of a run.
+ */
+export declare function clearCacheOnStart(cwd: string): Promise<void>;
+/**
+ * Save cache atomically using a temp file + rename.
+ */
+export declare function saveCacheAtomic(cwd: string, cache: Record<string, MutantCacheEntry>): Promise<void>;
+/**
+ * Decode a cache key into its component parts.
+ * Cache keys have the format: testSig:codeSig:file:line,col:mutator
+ */
+export declare function decodeCacheKey(key: string): {
+    file: string;
+    line: number;
+    col: number;
+    mutator: string;
+};
+/**
+ * Create a deterministic key for a set of test files.
+ */
+export declare function keyForTests(tests: readonly string[]): string;
+/**
+ * Create a short hash of a string (12 hex chars).
+ */
+export declare function hash(s: string): string;
+/**
+ * Read the mutant cache from disk.
+ * Normalizes both old (string status) and new (object) formats.
+ */
+export declare function readMutantCache(cwd: string): Promise<Record<string, MutantCacheEntry>>;

package/dist/runner/cache.js

@@ -0,0 +1,118 @@
+/**
+ * Cache Management Module
+ *
+ * Pure functions for managing mutation testing cache.
+ * Handles reading, writing, and decoding cache entries.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+const CACHE_FILENAME = '.mutate-cache.json';
+/**
+ * Clear the cache file at the start of a run.
+ */
+export async function clearCacheOnStart(cwd) {
+    const p = path.join(cwd, CACHE_FILENAME);
+    try {
+        await fs.unlink(p);
+    }
+    catch {
+        // Ignore if file doesn't exist
+    }
+}
+/**
+ * Save cache atomically using a temp file + rename.
+ */
+export async function saveCacheAtomic(cwd, cache) {
+    const p = path.join(cwd, CACHE_FILENAME);
+    const tmp = p + '.tmp';
+    const json = JSON.stringify(cache, null, 2);
+    await fs.writeFile(tmp, json, 'utf8');
+    await fs.rename(tmp, p);
+}
+/**
+ * Decode a cache key into its component parts.
+ * Cache keys have the format: testSig:codeSig:file:line,col:mutator
+ */
+export function decodeCacheKey(key) {
+    let file = key;
+    let line = 0;
+    let col = 0;
+    let mutator = 'unknown';
+    try {
+        const lastColon = key.lastIndexOf(':');
+        if (lastColon === -1)
+            return { file, line, col, mutator };
+        mutator = key.slice(lastColon + 1);
+        let rest = key.slice(0, lastColon);
+        const positionColon = rest.lastIndexOf(':');
+        if (positionColon === -1)
+            return { file, line, col, mutator };
+        const posRaw = rest.slice(positionColon + 1);
+        rest = rest.slice(0, positionColon);
+        const [lineStr, colStr] = posRaw.split(',');
+        const maybeLine = parseInt(lineStr, 10);
+        const maybeCol = parseInt(colStr, 10);
+        if (Number.isFinite(maybeLine))
+            line = maybeLine;
+        if (Number.isFinite(maybeCol))
+            col = maybeCol;
+        const firstColon = rest.indexOf(':');
+        if (firstColon === -1)
+            return { file, line, col, mutator };
+        const restAfterFirst = rest.slice(firstColon + 1);
+        const secondColon = restAfterFirst.indexOf(':');
+        if (secondColon === -1)
+            return { file, line, col, mutator };
+        file = restAfterFirst.slice(secondColon + 1) || file;
+    }
+    catch {
+        // fall through and return best-effort data
+    }
+    return { file, line, col, mutator };
+}
+/**
+ * Create a deterministic key for a set of test files.
+ */
+export function keyForTests(tests) {
+    return JSON.stringify([...tests].sort());
+}
+/**
+ * Create a short hash of a string (12 hex chars).
+ */
+export function hash(s) {
+    return crypto.createHash('sha1').update(s).digest('hex').slice(0, 12);
+}
+/**
+ * Read the mutant cache from disk.
+ * Normalizes both old (string status) and new (object) formats.
+ */
+export async function readMutantCache(cwd) {
+    const p = path.join(cwd, CACHE_FILENAME);
+    try {
+        const data = await fs.readFile(p, 'utf8');
+        const raw = JSON.parse(data);
+        const normalised = {};
+        for (const [key, value] of Object.entries(raw)) {
+            const decoded = decodeCacheKey(key);
+            if (typeof value === 'string') {
+                normalised[key] = { ...decoded, status: value };
+                continue;
+            }
+            if (value && typeof value === 'object' && 'status' in value) {
+                const entry = value;
+                const status = entry.status ?? 'skipped';
+                const file = entry.file ?? decoded.file;
+                const line = entry.line ?? decoded.line;
+                const col = entry.col ?? decoded.col;
+                const mutator = entry.mutator ?? decoded.mutator;
+                normalised[key] = { status, file, line, col, mutator };
+                continue;
+            }
+        }
+        return normalised;
+    }
+    catch {
+        return {};
+    }
+}

package/dist/runner/changed.d.ts

@@ -0,0 +1,22 @@
+export interface ChangedFilesOptions {
+    includeDeps?: boolean;
+    baseRef?: string;
+    quiet?: boolean;
+    /** Max depth for dependency resolution (default: 1, meaning direct imports only) */
+    maxDepth?: number;
+}
+/**
+ * List all changed files in a Git repository.
+ *
+ * Returns files that are:
+ * - Committed but not yet in baseRef (compared to baseRef...HEAD)
+ * - Modified but not yet committed (compared to HEAD)
+ * - Untracked but not ignored
+ *
+ * When includeDeps is true, also includes local dependencies of changed files.
+ *
+ * @param cwd - Working directory (will search for repo root if needed)
+ * @param options - Configuration options
+ * @returns Array of absolute paths to changed files
+ */
+export declare function listChangedFiles(cwd: string, options?: ChangedFilesOptions): string[];