@mutineerjs/mutineer 0.1.0

package/dist/utils/coverage.d.ts

@@ -0,0 +1,57 @@
+export interface CoverageData {
+    /** Set of covered lines per file (absolute path -> Set of line numbers) */
+    coveredLines: Map<string, Set<number>>;
+}
+/** Per-test coverage map: test file -> file path -> covered lines */
+export type PerTestCoverageMap = Map<string, Map<string, Set<number>>>;
+/**
+ * Load and parse Istanbul-format coverage JSON file.
+ * Supports both coverage-final.json (from Istanbul) and Vitest's coverage output.
+ *
+ * @param coverageFile - Path to the coverage JSON file
+ * @param cwd - Current working directory for resolving relative paths
+ * @returns Parsed coverage data with covered lines per file
+ */
+export declare function loadCoverageData(coverageFile: string, cwd: string): Promise<CoverageData>;
+/**
+ * Check if a specific line in a file is covered by tests.
+ *
+ * @param coverage - Coverage data from loadCoverageData
+ * @param filePath - Absolute path to the file
+ * @param line - Line number to check (1-indexed)
+ * @returns true if the line is covered, false otherwise
+ */
+export declare function isLineCovered(coverage: CoverageData, filePath: string, line: number): boolean;
+/**
+ * Get coverage statistics for a file.
+ *
+ * @param coverage - Coverage data from loadCoverageData
+ * @param filePath - Absolute path to the file
+ * @returns Object with covered line count and set of covered lines, or null if file not in coverage
+ */
+export declare function getFileCoverageStats(coverage: CoverageData, filePath: string): {
+    count: number;
+    lines: Set<number>;
+} | null;
+/**
+ * Best-effort loader for per-test coverage data.
+ * Expects a JSON file with a shape like:
+ * {
+ *   "tests": {
+ *     "/abs/path/to/test.spec.ts": {
+ *       "files": {
+ *         "/abs/path/to/src/file.ts": { "lines": [1,2,3] }
+ *       }
+ *     }
+ *   }
+ * }
+ * or a simplified shape:
+ * {
+ *   "/abs/path/to/test.spec.ts": {
+ *     "/abs/path/to/src/file.ts": [1,2,3]
+ *   }
+ * }
+ *
+ * Returns a map: testFile -> (filePath -> covered lines).
+ */
+export declare function loadPerTestCoverageData(reportsDir: string, cwd: string): Promise<PerTestCoverageMap | null>;

package/dist/utils/coverage.js

@@ -0,0 +1,204 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Load and parse Istanbul-format coverage JSON file.
+ * Supports both coverage-final.json (from Istanbul) and Vitest's coverage output.
+ *
+ * @param coverageFile - Path to the coverage JSON file
+ * @param cwd - Current working directory for resolving relative paths
+ * @returns Parsed coverage data with covered lines per file
+ */
+export async function loadCoverageData(coverageFile, cwd) {
+    const absPath = path.isAbsolute(coverageFile)
+        ? coverageFile
+        : path.join(cwd, coverageFile);
+    let raw;
+    try {
+        raw = await fs.readFile(absPath, 'utf8');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to read coverage file "${absPath}": ${msg}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to parse coverage file "${absPath}" as JSON: ${msg}`);
+    }
+    const coveredLines = new Map();
+    for (const [filePath, fileCoverage] of Object.entries(data)) {
+        if (!fileCoverage.statementMap || !fileCoverage.s) {
+            continue;
+        }
+        const lines = new Set();
+        // Extract lines that have been executed (hit count > 0)
+        for (const [stmtId, hitCount] of Object.entries(fileCoverage.s)) {
+            if (hitCount > 0) {
+                const stmt = fileCoverage.statementMap[stmtId];
+                if (stmt) {
+                    // Add all lines covered by this statement
+                    for (let line = stmt.start.line; line <= stmt.end.line; line++) {
+                        lines.add(line);
+                    }
+                }
+            }
+        }
+        if (lines.size > 0) {
+            // Normalize the file path to absolute
+            const absFilePath = path.isAbsolute(filePath)
+                ? filePath
+                : path.join(cwd, filePath);
+            coveredLines.set(absFilePath, lines);
+        }
+    }
+    return { coveredLines };
+}
+/**
+ * Check if a specific line in a file is covered by tests.
+ *
+ * @param coverage - Coverage data from loadCoverageData
+ * @param filePath - Absolute path to the file
+ * @param line - Line number to check (1-indexed)
+ * @returns true if the line is covered, false otherwise
+ */
+export function isLineCovered(coverage, filePath, line) {
+    const fileLines = coverage.coveredLines.get(filePath);
+    if (!fileLines) {
+        return false;
+    }
+    return fileLines.has(line);
+}
+/**
+ * Get coverage statistics for a file.
+ *
+ * @param coverage - Coverage data from loadCoverageData
+ * @param filePath - Absolute path to the file
+ * @returns Object with covered line count and set of covered lines, or null if file not in coverage
+ */
+export function getFileCoverageStats(coverage, filePath) {
+    const fileLines = coverage.coveredLines.get(filePath);
+    if (!fileLines) {
+        return null;
+    }
+    return { count: fileLines.size, lines: fileLines };
+}
+/**
+ * Best-effort loader for per-test coverage data.
+ * Expects a JSON file with a shape like:
+ * {
+ *   "tests": {
+ *     "/abs/path/to/test.spec.ts": {
+ *       "files": {
+ *         "/abs/path/to/src/file.ts": { "lines": [1,2,3] }
+ *       }
+ *     }
+ *   }
+ * }
+ * or a simplified shape:
+ * {
+ *   "/abs/path/to/test.spec.ts": {
+ *     "/abs/path/to/src/file.ts": [1,2,3]
+ *   }
+ * }
+ *
+ * Returns a map: testFile -> (filePath -> covered lines).
+ */
+export async function loadPerTestCoverageData(reportsDir, cwd) {
+    const base = path.isAbsolute(reportsDir)
+        ? reportsDir
+        : path.join(cwd, reportsDir);
+    const candidates = [
+        path.join(base, 'per-test-coverage.json'),
+        path.join(base, 'coverage-per-test.json'),
+        path.join(base, 'coverage-final.json'), // fallback if someone writes per-test into the main file
+    ];
+    const map = new Map();
+    let loaded = false;
+    for (const file of candidates) {
+        try {
+            const raw = await fs.readFile(file, 'utf8');
+            const data = JSON.parse(raw);
+            ingestPerTestJson(data, map);
+            loaded = map.size > 0;
+            if (loaded)
+                break;
+        }
+        catch {
+            // ignore missing/unreadable candidates
+        }
+    }
+    if (!loaded) {
+        // Try scanning coverage/tmp for per-test artifacts
+        try {
+            const tmpDir = path.join(base, 'tmp');
+            const entries = await fs.readdir(tmpDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile() || !entry.name.endsWith('.json'))
+                    continue;
+                const p = path.join(tmpDir, entry.name);
+                try {
+                    const raw = await fs.readFile(p, 'utf8');
+                    const data = JSON.parse(raw);
+                    ingestPerTestJson(data, map);
+                }
+                catch {
+                    continue;
+                }
+            }
+            loaded = map.size > 0;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return loaded ? map : null;
+}
+function ingestPerTestJson(json, out) {
+    if (!json || typeof json !== 'object')
+        return;
+    // If wrapped under "tests"
+    if ('tests' in json && json.tests && typeof json.tests === 'object') {
+        ingestTestsObject(json.tests, out);
+        return;
+    }
+    // Otherwise treat top-level as tests map
+    ingestTestsObject(json, out);
+}
+function ingestTestsObject(testsObj, out) {
+    if (!testsObj || typeof testsObj !== 'object')
+        return;
+    for (const [testPath, value] of Object.entries(testsObj)) {
+        if (!value || typeof value !== 'object')
+            continue;
+        // Format A: { files: { "/file": { lines: [] } } }
+        if ('files' in value && value.files && typeof value.files === 'object') {
+            const files = value.files;
+            const fileMap = ensureTestEntry(out, testPath);
+            for (const [filePath, detail] of Object.entries(files)) {
+                if (detail &&
+                    typeof detail === 'object' &&
+                    'lines' in detail &&
+                    Array.isArray(detail.lines)) {
+                    fileMap.set(filePath, new Set(detail.lines));
+                }
+            }
+            continue;
+        }
+        // Format B: { "/file": [lines] }
+        const fileMap = ensureTestEntry(out, testPath);
+        for (const [filePath, lines] of Object.entries(value)) {
+            if (Array.isArray(lines)) {
+                fileMap.set(filePath, new Set(lines.filter((n) => Number.isFinite(n))));
+            }
+        }
+    }
+}
+function ensureTestEntry(map, testPath) {
+    if (!map.has(testPath)) {
+        map.set(testPath, new Map());
+    }
+    return map.get(testPath);
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,8 @@
+export declare const DEBUG: boolean;
+export interface Logger {
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+export declare function createLogger(tag: string): Logger;

package/dist/utils/logger.js

@@ -0,0 +1,18 @@
+export const DEBUG = process.env.MUTINEER_DEBUG === '1';
+export function createLogger(tag) {
+    return {
+        debug(msg, ...args) {
+            if (DEBUG)
+                console.error(`[${tag}] ${msg}`, ...args);
+        },
+        info(msg, ...args) {
+            console.log(msg, ...args);
+        },
+        warn(msg, ...args) {
+            console.warn(msg, ...args);
+        },
+        error(msg, ...args) {
+            console.error(msg, ...args);
+        },
+    };
+}

package/dist/utils/progress.d.ts

@@ -0,0 +1,25 @@
+import type { MutantStatus } from '../types/mutant.js';
+export type ProgressMode = 'bar' | 'list';
+export interface ProgressOptions {
+    readonly mode?: ProgressMode;
+    readonly stream?: 'stdout' | 'stderr';
+}
+export declare class Progress {
+    private total;
+    private done;
+    private killed;
+    private escaped;
+    private skipped;
+    private errors;
+    private timeouts;
+    private readonly mode;
+    private readonly useTTY;
+    private readonly stream;
+    private started;
+    private finished;
+    constructor(total: number, opts?: ProgressOptions);
+    start(): void;
+    update(status: MutantStatus): void;
+    finish(): void;
+    private writeBar;
+}

package/dist/utils/progress.js

@@ -0,0 +1,90 @@
+import chalk from 'chalk';
+export class Progress {
+    constructor(total, opts = {}) {
+        this.done = 0;
+        this.killed = 0;
+        this.escaped = 0;
+        this.skipped = 0;
+        this.errors = 0;
+        this.timeouts = 0;
+        this.started = false;
+        this.finished = false;
+        this.total = Math.max(0, total);
+        this.mode = opts.mode ?? 'bar';
+        this.stream = opts.stream === 'stdout' ? process.stdout : process.stderr;
+        this.useTTY = Boolean(this.stream.isTTY) && this.mode === 'bar';
+    }
+    start() {
+        if (this.started || this.finished)
+            return;
+        this.started = true;
+        if (this.useTTY) {
+            this.stream.write('\x1b[?25l'); // hide cursor
+            this.writeBar();
+        }
+        else {
+            console.log(`mutineer: running ${this.total} mutants`);
+        }
+    }
+    update(status) {
+        if (!this.started || this.finished)
+            return;
+        this.done++;
+        if (status === 'killed')
+            this.killed++;
+        else if (status === 'escaped')
+            this.escaped++;
+        else if (status === 'error')
+            this.errors++;
+        else if (status === 'timeout')
+            this.timeouts++;
+        else
+            this.skipped++;
+        if (this.useTTY) {
+            this.writeBar();
+        }
+        else {
+            console.log(`mutant ${this.done}/${this.total} ${status}`);
+        }
+    }
+    finish() {
+        if (!this.started || this.finished)
+            return;
+        this.finished = true;
+        if (this.useTTY) {
+            this.stream.write('\r\x1b[2K'); // clear the bar line
+            this.stream.write('\x1b[?25h'); // show cursor
+        }
+        console.log(`mutineer: killed=${this.killed} escaped=${this.escaped} ` +
+            `errors=${this.errors} timeouts=${this.timeouts} skipped=${this.skipped}`);
+    }
+    writeBar() {
+        const cols = this.stream.columns || 80;
+        const ratio = this.total === 0 ? 1 : Math.min(this.done / this.total, 1);
+        const pct = Math.round(ratio * 100);
+        // Calculate visible widths to ensure the line fits in one terminal row
+        const prefix = `mutants ${this.done}/${this.total} [`;
+        const suffix = `] ${pct}% `;
+        const stats = `killed=${this.killed} ` +
+            `escaped=${this.escaped} ` +
+            `errors=${this.errors} ` +
+            `timeouts=${this.timeouts} ` +
+            `skipped=${this.skipped}`;
+        const barWidth = Math.max(10, cols - prefix.length - suffix.length - stats.length - 1);
+        const filled = Math.round(ratio * barWidth);
+        const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(barWidth - filled);
+        const line = prefix +
+            bar +
+            suffix +
+            chalk.green(`killed=${this.killed}`) +
+            ' ' +
+            chalk.red(`escaped=${this.escaped}`) +
+            ' ' +
+            chalk.yellow(`errors=${this.errors}`) +
+            ' ' +
+            chalk.yellow(`timeouts=${this.timeouts}`) +
+            ' ' +
+            chalk.dim(`skipped=${this.skipped}`);
+        this.stream.write('\r\x1b[2K' + line);
+    }
+}

package/dist/utils/summary.d.ts

@@ -0,0 +1,12 @@
+import type { MutantCacheEntry } from '../types/mutant.js';
+export interface Summary {
+    readonly total: number;
+    readonly killed: number;
+    readonly escaped: number;
+    readonly skipped: 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 summarise(cache: Readonly<Record<string, MutantCacheEntry>>): Summary;

package/dist/utils/summary.js

@@ -0,0 +1,107 @@
+import path from 'node:path';
+import chalk from 'chalk';
+const SEPARATOR = '\u2500'.repeat(45);
+export function computeSummary(cache) {
+    const allEntries = Object.values(cache);
+    let killed = 0;
+    let escaped = 0;
+    let skipped = 0;
+    for (const entry of allEntries) {
+        if (entry.status === 'killed')
+            killed++;
+        else if (entry.status === 'escaped')
+            escaped++;
+        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 };
+}
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const seconds = ms / 1000;
+    if (seconds < 60)
+        return `${seconds.toFixed(2)}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m ${remainingSeconds.toFixed(1)}s`;
+}
+export function printSummary(summary, cache, durationMs) {
+    console.log('\n' + chalk.dim(SEPARATOR));
+    console.log(chalk.bold(' Mutineer Test Suite Summary'));
+    console.log(chalk.dim(SEPARATOR));
+    if (summary.total === 0) {
+        console.log('\nNo mutants found');
+        console.log('\n' + chalk.dim(SEPARATOR) + '\n');
+        return;
+    }
+    const cwd = process.cwd();
+    const allEntries = cache ? Object.values(cache) : [];
+    const relativePaths = allEntries.map((e) => path.relative(cwd, e.file));
+    const maxPathLen = Math.min(Math.max(...relativePaths.map((p) => p.length), 0), 40) || 25;
+    const maxMutatorLen = Math.min(Math.max(...allEntries.map((e) => e.mutator.length), 0), 20) || 10;
+    function formatRow(entry) {
+        const relativePath = path.relative(cwd, entry.file);
+        const location = `${relativePath}@${entry.line},${entry.col}`;
+        if (entry.status === 'killed') {
+            return `${chalk.green('\u2713')} ${location.padEnd(maxPathLen)} ${chalk.dim(entry.mutator.padEnd(maxMutatorLen))}`;
+        }
+        if (entry.status === 'escaped') {
+            return `${chalk.red('\u2A2F')} ${location.padEnd(maxPathLen)} ${chalk.dim(entry.mutator.padEnd(maxMutatorLen))}`;
+        }
+        return `${chalk.dim('\u2022')} ${chalk.dim(location.padEnd(maxPathLen))} ${chalk.dim(entry.mutator.padEnd(maxMutatorLen))}`;
+    }
+    const entriesByStatus = {
+        killed: [],
+        escaped: [],
+        skipped: [],
+    };
+    for (const entry of allEntries) {
+        if (entry.status === 'killed')
+            entriesByStatus.killed.push(entry);
+        else if (entry.status === 'escaped')
+            entriesByStatus.escaped.push(entry);
+        else
+            entriesByStatus.skipped.push(entry);
+    }
+    if (entriesByStatus.killed.length) {
+        console.log('\n' + chalk.green.bold('Killed Mutants:'));
+        for (const entry of entriesByStatus.killed)
+            console.log('  ' + formatRow(entry));
+    }
+    if (entriesByStatus.escaped.length) {
+        console.log('\n' + chalk.red.bold('Escaped Mutants:'));
+        for (const entry of entriesByStatus.escaped)
+            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}`)}`);
+    if (summary.evaluated === 0) {
+        console.log(`Kill rate: ${chalk.dim('0.00% (no mutants executed)')}`);
+    }
+    else {
+        const rateColor = summary.killRate >= 80
+            ? chalk.green
+            : summary.killRate >= 50
+                ? chalk.yellow
+                : chalk.red;
+        console.log(`Kill rate: ${rateColor(summary.killRate.toFixed(2) + '%')} (${summary.killed}/${summary.evaluated})`);
+    }
+    if (durationMs !== undefined) {
+        console.log(`Duration: ${chalk.cyan(formatDuration(durationMs))}`);
+    }
+    console.log(chalk.dim(SEPARATOR) + '\n');
+}
+export function summarise(cache) {
+    const s = computeSummary(cache);
+    printSummary(s, cache);
+    return s;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@mutineerjs/mutineer",
+  "version": "v0.1.0",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "mutineer": "./dist/bin/mutineer.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -w",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest --run --coverage",
+    "lint": "eslint --config ./eslint.config.cjs --ext .ts,.js src/",
+    "mutate": "MUTINEER_DEBUG=0 tsx src/bin/mutineer.ts --config mutineer.config.ts"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "ink": "^5.2.1",
+    "ink-spinner": "^5.0.0",
+    "magic-string": "^0.30.9",
+    "react": "^18.3.1",
+    "tsx": "^4.20.6"
+  },
+  "peerDependencies": {
+    "@vue/compiler-sfc": ">=3.4.0",
+    "esbuild": "^0.25.10"
+  },
+  "devDependencies": {
+    "@babel/parser": "^7.28.4",
+    "@babel/traverse": "^7.28.4",
+    "@babel/types": "^7.28.4",
+    "@types/babel__traverse": "^7.28.0",
+    "@types/node": "^24.7.0",
+    "@types/react": "^19.2.14",
+    "@typescript-eslint/eslint-plugin": "^8.47.0",
+    "@typescript-eslint/parser": "^8.47.0",
+    "@vitejs/plugin-vue": "^5.1.4",
+    "@vitest/coverage-v8": "^4.0.15",
+    "eslint": "^9.39.1",
+    "fast-glob": "^3.3.3",
+    "jsdom": "^27.0.0",
+    "typescript": "^5.5.4",
+    "vite": "^6.3.6",
+    "vue": "^3.5.12"
+  }
+}