@mutineerjs/mutineer 0.4.0 → 0.5.1

package/dist/core/__tests__/variant-utils.spec.js

@@ -1,5 +1,5 @@
-import { describe, it, expect } from 'vitest';
-import { generateMutationVariants, getFilteredRegistry } from '../variant-utils.js';
+import { describe, it, expect, vi } from 'vitest';
+import { generateMutationVariants, getFilteredRegistry, } from '../variant-utils.js';
 function makeMutator(name, mutations) {
     return {
         name,
@@ -72,6 +72,28 @@ describe('generateMutationVariants', () => {
         const result = generateMutationVariants([mutator], 'code', {});
         expect(result).toHaveLength(2);
     });
+    it('calls applyWithContext instead of apply when available', () => {
+        const applyWithContext = vi
+            .fn()
+            .mockReturnValue([{ code: 'ctx_result', line: 1, col: 0 }]);
+        const mutator = {
+            name: 'm',
+            description: 'm',
+            apply: () => [{ code: 'apply_result', line: 1, col: 0 }],
+            applyWithContext,
+        };
+        const result = generateMutationVariants([mutator], 'const x = 1');
+        expect(applyWithContext).toHaveBeenCalledOnce();
+        expect(result[0].code).toBe('ctx_result');
+    });
+    it('falls back to apply when applyWithContext is absent', () => {
+        const apply = vi
+            .fn()
+            .mockReturnValue([{ code: 'apply_result', line: 1, col: 0 }]);
+        const mutator = { name: 'm', description: 'm', apply };
+        generateMutationVariants([mutator], 'const x = 1');
+        expect(apply).toHaveBeenCalledOnce();
+    });
 });
 describe('getFilteredRegistry', () => {
     it('returns the full registry when no filters', () => {

package/dist/core/sfc.js

@@ -1,5 +1,6 @@
 import MagicString from 'magic-string';
 import { getFilteredRegistry } from './variant-utils.js';
+import { buildParseContext } from '../mutators/utils.js';
 /**
  * Generate all possible mutations for a Vue SFC `<script setup>` block.
  * @param filename - The path to the Vue file (used by the parser for error reporting)
@@ -26,12 +27,16 @@ export async function mutateVueSfcScriptSetup(filename, code, include, exclude,
     const registry = getFilteredRegistry(include, exclude);
     const variants = [];
     const seenOutputs = new Set();
+    const ctx = buildParseContext(originalBlock);
     for (const mutator of registry) {
         // Early termination if limit reached
         if (max !== undefined && variants.length >= max) {
             break;
         }
-        for (const mutation of mutator.apply(originalBlock)) {
+        const blockMutations = mutator.applyWithContext
+            ? mutator.applyWithContext(originalBlock, ctx)
+            : mutator.apply(originalBlock);
+        for (const mutation of blockMutations) {
             const ms = new MagicString(code);
             ms.overwrite(startOffset, endOffset, mutation.code);
             const mutatedOutput = ms.toString();

package/dist/core/variant-utils.js

@@ -1,4 +1,5 @@
 import { getRegistry } from '../mutators/registry.js';
+import { buildParseContext } from '../mutators/utils.js';
 /**
  * Generate mutations from a registry of mutators, deduplicating the output.
  * Supports early termination when max limit is reached.
@@ -17,12 +18,16 @@ export function generateMutationVariants(registry, code, opts = {}) {
     }
     const variants = [];
     const seen = new Set();
+    const ctx = buildParseContext(code);
     for (const mutator of registry) {
         // Early termination if limit reached
         if (max !== undefined && variants.length >= max) {
             break;
         }
-        for (const mutation of mutator.apply(code)) {
+        const mutations = mutator.applyWithContext
+            ? mutator.applyWithContext(code, ctx)
+            : mutator.apply(code);
+        for (const mutation of mutations) {
             // Skip unchanged code and duplicates in a single check
             if (!seen.has(mutation.code)) {
                 seen.add(mutation.code);

package/dist/mutators/__tests__/operator.spec.js

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { relaxLE, relaxGE, tightenLT, tightenGT, andToOr, orToAnd, nullishToOr, flipEQ, flipNEQ, flipStrictEQ, flipStrictNEQ, addToSub, subToAdd, mulToDiv, divToMul, modToMul, powerToMul, } from '../operator.js';
+import { buildParseContext } from '../utils.js';
 // ---------------------------------------------------------------------------
 // Shared behaviour (tested once; all mutators use the same factory)
 // ---------------------------------------------------------------------------
@@ -37,6 +38,21 @@ describe('operator mutator shared behaviour', () => {
     });
 });
 // ---------------------------------------------------------------------------
+// applyWithContext (shared behaviour)
+// ---------------------------------------------------------------------------
+describe('operator mutator applyWithContext', () => {
+    it('produces same results as apply', () => {
+        const src = `const ok = a && b && c`;
+        const ctx = buildParseContext(src);
+        expect(andToOr.applyWithContext(src, ctx)).toEqual(andToOr.apply(src));
+    });
+    it('respects disable comments via pre-built context', () => {
+        const src = `// mutineer-disable-next-line\nconst ok = a && b`;
+        const ctx = buildParseContext(src);
+        expect(andToOr.applyWithContext(src, ctx)).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
 // Boundary mutators
 // ---------------------------------------------------------------------------
 describe('relaxLE', () => {

package/dist/mutators/__tests__/return-value.spec.js

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { returnToNull, returnToUndefined, returnFlipBool, returnZero, returnEmptyStr, returnEmptyArr, } from '../return-value.js';
+import { buildParseContext } from '../utils.js';
 // ---------------------------------------------------------------------------
 // returnToNull
 // ---------------------------------------------------------------------------
@@ -237,3 +238,39 @@ describe('returnEmptyArr', () => {
         expect(results).toHaveLength(0);
     });
 });
+// ---------------------------------------------------------------------------
+// applyWithContext (shared behaviour)
+// ---------------------------------------------------------------------------
+describe('return-value mutator applyWithContext', () => {
+    it('produces same results as apply', () => {
+        const src = `function f() { return x }`;
+        const ctx = buildParseContext(src);
+        expect(returnToNull.applyWithContext(src, ctx)).toEqual(returnToNull.apply(src));
+    });
+    it('respects disable comments via pre-built context', () => {
+        const src = `function f() {\n  // mutineer-disable-next-line\n  return x\n}`;
+        const ctx = buildParseContext(src);
+        expect(returnToNull.applyWithContext(src, ctx)).toHaveLength(0);
+    });
+    it('all return mutators produce same results via applyWithContext as apply', () => {
+        const src = `
+function f(x) {
+  if (x) return true
+  if (x > 0) return 42
+  if (x < 0) return 'hello'
+  return [1, 2]
+}
+`;
+        const ctx = buildParseContext(src);
+        for (const mutator of [
+            returnToNull,
+            returnToUndefined,
+            returnFlipBool,
+            returnZero,
+            returnEmptyStr,
+            returnEmptyArr,
+        ]) {
+            expect(mutator.applyWithContext(src, ctx)).toEqual(mutator.apply(src));
+        }
+    });
+});

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { collectOperatorTargets, buildIgnoreLines, parseSource, } from '../utils.js';
+import { collectOperatorTargets, collectOperatorTargetsFromContext, collectAllTargets, buildIgnoreLines, buildParseContext, parseSource, } from '../utils.js';
 // ---------------------------------------------------------------------------
 // buildIgnoreLines
 // ---------------------------------------------------------------------------
@@ -65,7 +65,86 @@ describe('parseSource', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// collectOperatorTargets
+// buildParseContext
+// ---------------------------------------------------------------------------
+describe('buildParseContext', () => {
+    it('returns an object with ast, tokens, ignoreLines, and preCollected', () => {
+        const ctx = buildParseContext(`const x = a && b`);
+        expect(ctx.ast.type).toBe('File');
+        expect(Array.isArray(ctx.tokens)).toBe(true);
+        expect(ctx.ignoreLines).toBeInstanceOf(Set);
+        expect(ctx.preCollected).toBeDefined();
+        expect(ctx.preCollected.operatorTargets).toBeInstanceOf(Map);
+        expect(Array.isArray(ctx.preCollected.returnStatements)).toBe(true);
+    });
+    it('populates ignoreLines from disable comments', () => {
+        const src = `// mutineer-disable-next-line\nconst x = a && b`;
+        const ctx = buildParseContext(src);
+        expect(ctx.ignoreLines.has(2)).toBe(true);
+    });
+    it('preCollected.operatorTargets groups targets by operator', () => {
+        const src = `const x = a && b || c && d`;
+        const ctx = buildParseContext(src);
+        expect(ctx.preCollected.operatorTargets.get('&&')).toHaveLength(2);
+        expect(ctx.preCollected.operatorTargets.get('||')).toHaveLength(1);
+    });
+    it('preCollected.returnStatements captures return arguments', () => {
+        const src = `function f() { return x }\nfunction g() { return y }`;
+        const ctx = buildParseContext(src);
+        expect(ctx.preCollected.returnStatements).toHaveLength(2);
+    });
+});
+// ---------------------------------------------------------------------------
+// collectAllTargets
+// ---------------------------------------------------------------------------
+describe('collectAllTargets', () => {
+    it('collects operator targets grouped by operator', () => {
+        const src = `const x = a && b || c`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        expect(result.operatorTargets.get('&&')).toHaveLength(1);
+        expect(result.operatorTargets.get('||')).toHaveLength(1);
+    });
+    it('collects return statement info', () => {
+        const src = `function f() { return 42 }`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        expect(result.returnStatements).toHaveLength(1);
+        const info = result.returnStatements[0];
+        expect(info.line).toBe(1);
+        expect(typeof info.col).toBe('number');
+        expect(typeof info.argStart).toBe('number');
+        expect(typeof info.argEnd).toBe('number');
+        expect(info.argNode).toBeDefined();
+    });
+    it('skips operators on ignored lines', () => {
+        const src = `// mutineer-disable-next-line\nconst x = a && b`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        expect(result.operatorTargets.get('&&') ?? []).toHaveLength(0);
+    });
+    it('skips return statements on ignored lines', () => {
+        const src = `function f() {\n  // mutineer-disable-next-line\n  return x\n}`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        expect(result.returnStatements).toHaveLength(0);
+    });
+    it('skips bare return with no argument', () => {
+        const src = `function f() { return }`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        expect(result.returnStatements).toHaveLength(0);
+    });
+    it('matches collectOperatorTargetsFromContext for &&', () => {
+        const src = `const x = a && b && c`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        const fromCtx = collectOperatorTargetsFromContext(src, ctx, '&&');
+        expect(result.operatorTargets.get('&&')).toEqual(fromCtx);
+    });
+});
+// ---------------------------------------------------------------------------
+// collectOperatorTargets / collectOperatorTargetsFromContext
 // ---------------------------------------------------------------------------
 describe('collectOperatorTargets', () => {
     it('honors mutineer disable comments', () => {
@@ -80,3 +159,18 @@ const d = e && f
         expect(lines).toEqual([5]);
     });
 });
+describe('collectOperatorTargetsFromContext', () => {
+    it('returns same results as collectOperatorTargets', () => {
+        const src = `const ok = a && b && c`;
+        const ctx = buildParseContext(src);
+        const fromCtx = collectOperatorTargetsFromContext(src, ctx, '&&');
+        const fromSrc = collectOperatorTargets(src, '&&');
+        expect(fromCtx).toEqual(fromSrc);
+    });
+    it('honors disable comments via pre-built context', () => {
+        const src = `// mutineer-disable-next-line\nconst x = a && b`;
+        const ctx = buildParseContext(src);
+        const targets = collectOperatorTargetsFromContext(src, ctx, '&&');
+        expect(targets).toHaveLength(0);
+    });
+});

package/dist/mutators/operator.js

@@ -15,15 +15,21 @@ import { collectOperatorTargets } from './utils.js';
  * @param toOp - The operator to replace it with (e.g., '||')
  */
 function makeOperatorMutator(name, description, fromOp, toOp) {
+    function targetsToOutputs(src, targets) {
+        return targets.map((target) => ({
+            line: target.line,
+            col: target.col1,
+            code: src.slice(0, target.start) + toOp + src.slice(target.end),
+        }));
+    }
     return {
         name,
         description,
         apply(src) {
-            return collectOperatorTargets(src, fromOp).map((target) => ({
-                line: target.line,
-                col: target.col1,
-                code: src.slice(0, target.start) + toOp + src.slice(target.end),
-            }));
+            return targetsToOutputs(src, collectOperatorTargets(src, fromOp));
+        },
+        applyWithContext(src, ctx) {
+            return targetsToOutputs(src, ctx.preCollected.operatorTargets.get(fromOp) ?? []);
         },
     };
 }

package/dist/mutators/return-value.js

@@ -20,6 +20,32 @@ import { traverse, getVisualColumn, parseSource, buildIgnoreLines, } from './uti
  * @param description - Human-readable description shown in reports
  * @param replacer - Returns the replacement source text, or null to skip
  */
+function collectReturnMutations(src, ast, ignoreLines, replacer) {
+    const outputs = [];
+    traverse(ast, {
+        ReturnStatement(path) {
+            const node = path.node;
+            if (!node.argument)
+                return; // bare return; — nothing to replace
+            const line = node.loc?.start.line;
+            if (line === undefined)
+                return;
+            if (ignoreLines.has(line))
+                return;
+            const replacement = replacer(node.argument);
+            if (replacement === null)
+                return;
+            const argStart = node.argument.start;
+            const argEnd = node.argument.end;
+            if (argStart == null || argEnd == null)
+                return;
+            const col = getVisualColumn(src, node.start ?? 0);
+            const code = src.slice(0, argStart) + replacement + src.slice(argEnd);
+            outputs.push({ line, col, code });
+        },
+    });
+    return outputs;
+}
 function makeReturnMutator(name, description, replacer) {
     return {
         name,
@@ -28,29 +54,17 @@ function makeReturnMutator(name, description, replacer) {
             const ast = parseSource(src);
             const fileAst = ast;
             const ignoreLines = buildIgnoreLines(fileAst.comments ?? []);
+            return collectReturnMutations(src, ast, ignoreLines, replacer);
+        },
+        applyWithContext(src, ctx) {
             const outputs = [];
-            traverse(ast, {
-                ReturnStatement(path) {
-                    const node = path.node;
-                    if (!node.argument)
-                        return; // bare return; — nothing to replace
-                    const line = node.loc?.start.line;
-                    if (line === undefined)
-                        return;
-                    if (ignoreLines.has(line))
-                        return;
-                    const replacement = replacer(node.argument);
-                    if (replacement === null)
-                        return;
-                    const argStart = node.argument.start;
-                    const argEnd = node.argument.end;
-                    if (argStart == null || argEnd == null)
-                        return;
-                    const col = getVisualColumn(src, node.start ?? 0);
-                    const code = src.slice(0, argStart) + replacement + src.slice(argEnd);
-                    outputs.push({ line, col, code });
-                },
-            });
+            for (const info of ctx.preCollected.returnStatements) {
+                const replacement = replacer(info.argNode);
+                if (replacement === null)
+                    continue;
+                const code = src.slice(0, info.argStart) + replacement + src.slice(info.argEnd);
+                outputs.push({ line: info.line, col: info.col, code });
+            }
             return outputs;
         },
     };

package/dist/mutators/types.d.ts

@@ -4,6 +4,7 @@
  * Defines the interface that all mutators must implement and the output format
  * for mutations. This allows for different mutator implementations to be plugged in.
  */
+export type { ParseContext } from './utils.js';
 /**
  * Output of a single mutation, including location info and mutated code.
  */
@@ -20,6 +21,7 @@ export interface ASTMutator {
     readonly name: string;
     readonly description: string;
     apply(src: string): readonly MutationOutput[];
+    applyWithContext?(src: string, ctx: import('./utils.js').ParseContext): readonly MutationOutput[];
 }
 /**
  * Union type for different mutator kinds.

package/dist/mutators/utils.d.ts

@@ -46,6 +46,73 @@ export declare function parseSource(src: string): import("@babel/parser").ParseR
  * Type guard to check if a node is a BinaryExpression or LogicalExpression.
  */
 export declare function isBinaryOrLogical(node: t.Node): node is t.BinaryExpression | t.LogicalExpression;
+/**
+ * Internal token-like interface for AST token analysis.
+ */
+export interface TokenLike {
+    readonly value?: string;
+    readonly start: number;
+    readonly end: number;
+    readonly loc: {
+        readonly start: {
+            readonly line: number;
+            readonly column: number;
+        };
+        readonly end: {
+            readonly line: number;
+            readonly column: number;
+        };
+    };
+}
+/**
+ * Location info for a single return statement argument, pre-collected
+ * during a single AST traversal so return-value mutators need no traversal.
+ */
+export interface ReturnStatementInfo {
+    readonly line: number;
+    readonly col: number;
+    readonly argStart: number;
+    readonly argEnd: number;
+    readonly argNode: t.Expression;
+}
+/**
+ * All mutation targets pre-collected in a single traversal.
+ */
+export interface PreCollected {
+    readonly operatorTargets: Map<string, OperatorTarget[]>;
+    readonly returnStatements: ReturnStatementInfo[];
+}
+/**
+ * Pre-parsed context for a source file.
+ * Allows sharing a single Babel parse across all mutators.
+ */
+export interface ParseContext {
+    readonly ast: t.File & {
+        tokens?: TokenLike[];
+        comments?: t.Comment[];
+    };
+    readonly tokens: readonly TokenLike[];
+    readonly ignoreLines: Set<number>;
+    readonly preCollected: PreCollected;
+}
+/**
+ * Single traversal that collects all operator targets and return statements.
+ * Eliminates per-mutator traversals when using ParseContext.
+ */
+export declare function collectAllTargets(src: string, ast: t.File & {
+    tokens?: TokenLike[];
+    comments?: t.Comment[];
+}, tokens: readonly TokenLike[], ignoreLines: Set<number>): PreCollected;
+/**
+ * Parse a source file once and build a reusable ParseContext.
+ * Pass this to mutators' applyWithContext to avoid redundant parses.
+ */
+export declare function buildParseContext(src: string): ParseContext;
+/**
+ * Collect operator targets from a pre-built ParseContext.
+ * Avoids re-parsing; use when processing multiple operators on the same source.
+ */
+export declare function collectOperatorTargetsFromContext(src: string, ctx: ParseContext, opValue: string): OperatorTarget[];
 /**
  * Collect the operator tokens for a given operator and return their exact locations.
  * Uses AST traversal to find BinaryExpression/LogicalExpression nodes, then maps them

package/dist/mutators/utils.js

@@ -122,21 +122,86 @@ export function isBinaryOrLogical(node) {
     return node.type === 'BinaryExpression' || node.type === 'LogicalExpression';
 }
 /**
- * Collect the operator tokens for a given operator and return their exact locations.
- * Uses AST traversal to find BinaryExpression/LogicalExpression nodes, then maps them
- * to token positions for accurate column reporting.
- *
- * @param src - The source code
- * @param opValue - The operator to search for (e.g., '&&', '<=')
- * @returns Array of target locations for the operator
+ * Single traversal that collects all operator targets and return statements.
+ * Eliminates per-mutator traversals when using ParseContext.
  */
-export function collectOperatorTargets(src, opValue) {
+export function collectAllTargets(src, ast, tokens, ignoreLines) {
+    const operatorTargets = new Map();
+    const returnStatements = [];
+    function handleBinaryOrLogical(n) {
+        const nodeStart = n.start ?? 0;
+        const nodeEnd = n.end ?? 0;
+        const opValue = n.operator;
+        const tok = tokens.find((tk) => tk.start >= nodeStart && tk.end <= nodeEnd && tk.value === opValue);
+        if (tok) {
+            const line = tok.loc.start.line;
+            if (ignoreLines.has(line))
+                return;
+            const visualCol = getVisualColumn(src, tok.start);
+            let arr = operatorTargets.get(opValue);
+            if (!arr) {
+                arr = [];
+                operatorTargets.set(opValue, arr);
+            }
+            arr.push({
+                start: tok.start,
+                end: tok.end,
+                line,
+                col1: visualCol,
+                op: opValue,
+            });
+        }
+    }
+    traverse(ast, {
+        BinaryExpression(p) {
+            handleBinaryOrLogical(p.node);
+        },
+        LogicalExpression(p) {
+            handleBinaryOrLogical(p.node);
+        },
+        ReturnStatement(p) {
+            const node = p.node;
+            if (!node.argument)
+                return;
+            const line = node.loc?.start.line;
+            if (line === undefined)
+                return;
+            if (ignoreLines.has(line))
+                return;
+            const argStart = node.argument.start;
+            const argEnd = node.argument.end;
+            if (argStart == null || argEnd == null)
+                return;
+            const col = getVisualColumn(src, node.start ?? 0);
+            returnStatements.push({
+                line,
+                col,
+                argStart,
+                argEnd,
+                argNode: node.argument,
+            });
+        },
+    });
+    return { operatorTargets, returnStatements };
+}
+/**
+ * Parse a source file once and build a reusable ParseContext.
+ * Pass this to mutators' applyWithContext to avoid redundant parses.
+ */
+export function buildParseContext(src) {
     const ast = parseSource(src);
-    const fileAst = ast;
-    const tokens = fileAst.tokens ?? [];
-    const comments = fileAst.comments ?? [];
+    const tokens = ast.tokens ?? [];
+    const ignoreLines = buildIgnoreLines(ast.comments ?? []);
+    const preCollected = collectAllTargets(src, ast, tokens, ignoreLines);
+    return { ast, tokens, ignoreLines, preCollected };
+}
+/**
+ * Collect operator targets from a pre-built ParseContext.
+ * Avoids re-parsing; use when processing multiple operators on the same source.
+ */
+export function collectOperatorTargetsFromContext(src, ctx, opValue) {
+    const { ast, tokens, ignoreLines } = ctx;
     const out = [];
-    const ignoreLines = buildIgnoreLines(comments);
     traverse(ast, {
         enter(p) {
             if (!isBinaryOrLogical(p.node))
@@ -144,12 +209,10 @@ export function collectOperatorTargets(src, opValue) {
             const n = p.node;
             if (n.operator !== opValue)
                 return;
-            // Find the exact operator token inside the node span
             const nodeStart = n.start ?? 0;
             const nodeEnd = n.end ?? 0;
             const tok = tokens.find((tk) => tk.start >= nodeStart && tk.end <= nodeEnd && tk.value === opValue);
             if (tok) {
-                // Convert Babel's character-based column to a visual column for accurate reporting
                 const line = tok.loc.start.line;
                 if (ignoreLines.has(line))
                     return;
@@ -158,7 +221,7 @@ export function collectOperatorTargets(src, opValue) {
                     start: tok.start,
                     end: tok.end,
                     line,
-                    col1: visualCol, // convert to 1-based
+                    col1: visualCol,
                     op: opValue,
                 });
             }
@@ -166,3 +229,15 @@ export function collectOperatorTargets(src, opValue) {
     });
     return out;
 }
+/**
+ * Collect the operator tokens for a given operator and return their exact locations.
+ * Uses AST traversal to find BinaryExpression/LogicalExpression nodes, then maps them
+ * to token positions for accurate column reporting.
+ *
+ * @param src - The source code
+ * @param opValue - The operator to search for (e.g., '&&', '<=')
+ * @returns Array of target locations for the operator
+ */
+export function collectOperatorTargets(src, opValue) {
+    return collectOperatorTargetsFromContext(src, buildParseContext(src), opValue);
+}

package/dist/runner/__tests__/discover.spec.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -34,7 +34,86 @@ vi.mock('vite', async () => {
         }),
     };
 });
+describe('createViteResolver Vue plugin gating', () => {
+    let warnSpy;
+    beforeEach(() => {
+        warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('does not warn about @vitejs/plugin-vue when no .vue files exist', async () => {
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-discover-novue-'));
+        const srcDir = path.join(tmpDir, 'src');
+        await fs.mkdir(srcDir, { recursive: true });
+        await fs.writeFile(path.join(srcDir, 'a.ts'), 'export const a = 1\n', 'utf8');
+        const importLine = ['im', 'port { a } from "./a"'].join('');
+        await fs.writeFile(path.join(srcDir, 'a.test.ts'), `${importLine}\n`, 'utf8');
+        try {
+            await autoDiscoverTargetsAndTests(tmpDir, {
+                testPatterns: ['**/*.test.ts'],
+            });
+            const pluginVueWarnings = warnSpy.mock.calls.filter((args) => String(args[0]).includes('plugin-vue'));
+            expect(pluginVueWarnings).toHaveLength(0);
+        }
+        finally {
+            await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    it('warns when .vue files exist but @vitejs/plugin-vue fails to load', async () => {
+        vi.doMock('@vitejs/plugin-vue', () => {
+            throw new Error('Cannot find module @vitejs/plugin-vue');
+        });
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-discover-vue-'));
+        const srcDir = path.join(tmpDir, 'src');
+        await fs.mkdir(srcDir, { recursive: true });
+        await fs.writeFile(path.join(srcDir, 'Comp.vue'), '<template><div/></template>\n', 'utf8');
+        await fs.writeFile(path.join(srcDir, 'a.ts'), 'export const a = 1\n', 'utf8');
+        const importLine = ['im', 'port { a } from "./a"'].join('');
+        await fs.writeFile(path.join(srcDir, 'a.test.ts'), `${importLine}\n`, 'utf8');
+        try {
+            await autoDiscoverTargetsAndTests(tmpDir, {
+                testPatterns: ['**/*.test.ts'],
+                extensions: ['.vue', '.ts'],
+            });
+            const pluginVueWarnings = warnSpy.mock.calls.filter((args) => String(args[0]).includes('plugin-vue'));
+            expect(pluginVueWarnings.length).toBeGreaterThan(0);
+        }
+        finally {
+            vi.doUnmock('@vitejs/plugin-vue');
+            await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
 describe('autoDiscoverTargetsAndTests', () => {
+    it('directTestMap only includes direct importers', async () => {
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-discover-direct-'));
+        const srcDir = path.join(tmpDir, 'src');
+        const moduleX = path.join(srcDir, 'x.ts');
+        const moduleY = path.join(srcDir, 'y.ts');
+        const testFile = path.join(srcDir, 'a.test.ts');
+        await fs.mkdir(srcDir, { recursive: true });
+        await fs.writeFile(moduleY, 'export const y = 2\n', 'utf8');
+        const importY = ['im', 'port { y } from "./y"'].join('');
+        await fs.writeFile(moduleX, `${importY}\nexport const x = 1\n`, 'utf8');
+        const importX = ['im', 'port { x } from "./x"'].join('');
+        await fs.writeFile(testFile, `${importX}\nconsole.log(x)\n`, 'utf8');
+        try {
+            const { directTestMap } = await autoDiscoverTargetsAndTests(tmpDir, {
+                testPatterns: ['**/*.test.ts'],
+            });
+            const testAbs = normalizePath(testFile);
+            const xAbs = normalizePath(moduleX);
+            const yAbs = normalizePath(moduleY);
+            // x is directly imported by the test
+            expect(directTestMap.get(xAbs)?.has(testAbs)).toBe(true);
+            // y is only transitively imported (x -> y), not directly by the test
+            expect(directTestMap.get(yAbs)?.has(testAbs)).toBeFalsy();
+        }
+        finally {
+            await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
     it('ignores test files when collecting mutate targets', async () => {
         const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-discover-'));
         const srcDir = path.join(tmpDir, 'src');

package/dist/runner/__tests__/pool-executor.spec.js

@@ -286,6 +286,130 @@ describe('executePool', () => {
         expect(cache['missing-file-key'].status).toBe('escaped');
         expect(cache['missing-file-key'].originalSnippet).toBeUndefined();
     });
+    it('escaped mutant stores coveringTests', async () => {
+        const tmpFile = path.join(tmpDir, 'covering.ts');
+        await fs.writeFile(tmpFile, 'const x = a + b\n');
+        const adapter = makeAdapter({
+            runMutant: vi
+                .fn()
+                .mockResolvedValue({ status: 'escaped', durationMs: 1 }),
+        });
+        const cache = {};
+        const tests = ['/tests/foo.spec.ts', '/tests/bar.spec.ts'];
+        const task = makeTask({
+            key: 'covering-key',
+            tests,
+            v: {
+                id: 'covering.ts#0',
+                name: 'flipArith',
+                file: tmpFile,
+                code: 'const x = a - b\n',
+                line: 1,
+                col: 10,
+                tests,
+            },
+        });
+        await executePool({
+            tasks: [task],
+            adapter,
+            cache,
+            concurrency: 1,
+            progressMode: 'list',
+            cwd: tmpDir,
+        });
+        expect(cache['covering-key'].coveringTests).toEqual(tests);
+    });
+    it('escaped mutant uses directTests for coveringTests when available', async () => {
+        const tmpFile = path.join(tmpDir, 'direct-covering.ts');
+        await fs.writeFile(tmpFile, 'const x = a + b\n');
+        const adapter = makeAdapter({
+            runMutant: vi
+                .fn()
+                .mockResolvedValue({ status: 'escaped', durationMs: 1 }),
+        });
+        const cache = {};
+        const directTests = ['/direct.spec.ts'];
+        const allTests = ['/direct.spec.ts', '/transitive.spec.ts'];
+        const task = makeTask({
+            key: 'direct-covering-key',
+            tests: allTests,
+            directTests,
+            v: {
+                id: 'direct-covering.ts#0',
+                name: 'flipArith',
+                file: tmpFile,
+                code: 'const x = a - b\n',
+                line: 1,
+                col: 10,
+                tests: allTests,
+            },
+        });
+        await executePool({
+            tasks: [task],
+            adapter,
+            cache,
+            concurrency: 1,
+            progressMode: 'list',
+            cwd: tmpDir,
+        });
+        expect(cache['direct-covering-key'].coveringTests).toEqual(directTests);
+    });
+    it('killed mutant does not store coveringTests', async () => {
+        const adapter = makeAdapter({
+            runMutant: vi.fn().mockResolvedValue({ status: 'killed', durationMs: 1 }),
+        });
+        const cache = {};
+        const task = makeTask({ key: 'killed-covering-key' });
+        await executePool({
+            tasks: [task],
+            adapter,
+            cache,
+            concurrency: 1,
+            progressMode: 'list',
+            cwd: tmpDir,
+        });
+        expect(cache['killed-covering-key'].coveringTests).toBeUndefined();
+    });
+    it('correctly stores snippets for multiple escaped mutants from the same file', async () => {
+        const tmpFile = path.join(tmpDir, 'shared.ts');
+        await fs.writeFile(tmpFile, 'const x = a + b\n');
+        const adapter = makeAdapter({
+            runMutant: vi
+                .fn()
+                .mockResolvedValue({ status: 'escaped', durationMs: 1 }),
+        });
+        const cache = {};
+        const makeFileTask = (key, mutated) => makeTask({
+            key,
+            v: {
+                id: `shared.ts#${key}`,
+                name: 'flipArith',
+                file: tmpFile,
+                code: mutated,
+                line: 1,
+                col: 10,
+                tests: ['/tests/file.test.ts'],
+            },
+        });
+        await executePool({
+            tasks: [
+                makeFileTask('cache-key-1', 'const x = a - b\n'),
+                makeFileTask('cache-key-2', 'const x = a * b\n'),
+                makeFileTask('cache-key-3', 'const x = a / b\n'),
+            ],
+            adapter,
+            cache,
+            concurrency: 1,
+            progressMode: 'list',
+            cwd: tmpDir,
+        });
+        expect(cache['cache-key-1'].originalSnippet).toBe('const x = a + b');
+        expect(cache['cache-key-1'].mutatedSnippet).toBe('const x = a - b');
+        expect(cache['cache-key-2'].originalSnippet).toBe('const x = a + b');
+        expect(cache['cache-key-2'].mutatedSnippet).toBe('const x = a * b');
+        expect(cache['cache-key-3'].originalSnippet).toBe('const x = a + b');
+        expect(cache['cache-key-3'].mutatedSnippet).toBe('const x = a / b');
+    });
     it('handles adapter errors gracefully and still shuts down', async () => {
         const adapter = makeAdapter({
             runMutant: vi.fn().mockRejectedValue(new Error('adapter failure')),

package/dist/runner/__tests__/tasks.spec.js

@@ -80,6 +80,20 @@ describe('prepareTasks', () => {
         const tasks = prepareTasks([v], null);
         expect(tasks[0].tests).toHaveLength(2);
     });
+    it('populates directTests from directTestMap', () => {
+        const v = makeVariant({ file: '/src/file.ts', tests: ['/tests/a.test.ts'] });
+        const directTestMap = new Map([
+            ['/src/file.ts', new Set(['/tests/direct.test.ts'])],
+        ]);
+        const tasks = prepareTasks([v], null, directTestMap);
+        expect(tasks[0].directTests).toEqual(['/tests/direct.test.ts']);
+    });
+    it('directTests absent when not in directTestMap', () => {
+        const v = makeVariant({ file: '/src/file.ts', tests: ['/tests/a.test.ts'] });
+        const directTestMap = new Map();
+        const tasks = prepareTasks([v], null, directTestMap);
+        expect(tasks[0].directTests).toBeUndefined();
+    });
     it('handles multiple variants', () => {
         const variants = [
             makeVariant({ id: 'file.ts#0', code: 'code1' }),

package/dist/runner/discover.d.ts

@@ -3,5 +3,6 @@ export type TestMap = Map<string, Set<string>>;
 export interface DiscoveryResult {
     readonly targets: MutateTarget[];
     readonly testMap: TestMap;
+    readonly directTestMap: TestMap;
 }
 export declare function autoDiscoverTargetsAndTests(root: string, cfg: MutineerConfig): Promise<DiscoveryResult>;

package/dist/runner/discover.js

@@ -84,15 +84,24 @@ async function createViteResolver(rootAbs, exts) {
     // Load Vue plugin if needed
     let plugins = [];
     if (exts.has('.vue')) {
-        try {
-            const mod = await import(
-            /* @vite-ignore */ '@vitejs/plugin-vue');
-            const vue = mod.default ?? mod;
-            plugins = typeof vue === 'function' ? [vue()] : [];
-        }
-        catch (err) {
-            const detail = err instanceof Error ? err.message : String(err);
-            log.warn(`Unable to load @vitejs/plugin-vue; Vue SFC imports may fail to resolve (${detail})`);
+        const vueFiles = await fg(['**/*.vue'], {
+            cwd: rootAbs,
+            onlyFiles: true,
+            ignore: ['**/node_modules/**'],
+            deep: 5,
+        });
+        if (vueFiles.length > 0) {
+            try {
+                const mod = await import(
+                /* @vite-ignore */ '@vitejs/plugin-vue');
+                const vue = mod.default ?? mod;
+                plugins =
+                    typeof vue === 'function' ? [vue()] : [];
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                log.warn(`Unable to load @vitejs/plugin-vue; Vue SFC imports may fail to resolve (${detail})`);
+            }
         }
     }
     const quietLogger = {
@@ -208,12 +217,13 @@ export async function autoDiscoverTargetsAndTests(root, cfg) {
         ignore,
     });
     if (!tests.length)
-        return { targets: [], testMap: new Map() };
+        return { targets: [], testMap: new Map(), directTestMap: new Map() };
     const testSet = new Set(tests.map((t) => normalizePath(t)));
     // 2) Create resolver (Vite if available, otherwise Node-based fallback)
     const { resolve, cleanup } = await createResolver(rootAbs, exts);
     const targets = new Map();
     const testMap = new Map();
+    const directTestMap = new Map();
     const contentCache = new Map();
     const resolveCache = new Map(); // key: importer\0spec -> resolved id
     async function crawl(absFile, depth, seen, currentTestAbs) {
@@ -242,6 +252,11 @@ export async function autoDiscoverTargetsAndTests(root, cfg) {
             if (!testMap.has(key))
                 testMap.set(key, new Set());
             testMap.get(key).add(currentTestAbs);
+            if (depth === 0) {
+                if (!directTestMap.has(key))
+                    directTestMap.set(key, new Set());
+                directTestMap.get(key).add(currentTestAbs);
+            }
         }
         // read file content to find further imports (works for .vue too; imports are inside <script>)
         let code = contentCache.get(absFile);
@@ -274,12 +289,12 @@ export async function autoDiscoverTargetsAndTests(root, cfg) {
         }
     }
     try {
-        for (const testAbs of tests) {
+        await Promise.all(tests.map(async (testAbs) => {
             const seen = new Set();
             // prime with the test's own direct imports
             const code = safeRead(testAbs);
             if (!code)
-                continue;
+                return;
             const firstHop = [];
             for (const spec of extractImportSpecs(code)) {
                 if (!spec)
@@ -296,8 +311,8 @@ export async function autoDiscoverTargetsAndTests(root, cfg) {
             for (const abs of firstHop) {
                 await crawl(abs, 0, seen, testAbs);
             }
-        }
-        return { targets: Array.from(targets.values()), testMap };
+        }));
+        return { targets: Array.from(targets.values()), testMap, directTestMap };
     }
     finally {
         await cleanup();

package/dist/runner/orchestrator.js

@@ -68,7 +68,7 @@ export async function runOrchestrator(cliArgs, cwd) {
     // 4. Discover targets and tests
     const cache = await readMutantCache(cwd);
     const discovered = await autoDiscoverTargetsAndTests(cwd, cfg);
-    const testMap = discovered.testMap;
+    const { testMap, directTestMap } = discovered;
     const targets = cfg.targets?.length
         ? [...cfg.targets]
         : (cfg.autoDiscover ?? true)
@@ -122,7 +122,7 @@ export async function runOrchestrator(cliArgs, cwd) {
         return;
     }
     // 8. Prepare tasks and execute via worker pool
-    const tasks = prepareTasks(variants, updatedCoverage.perTestCoverage);
+    const tasks = prepareTasks(variants, updatedCoverage.perTestCoverage, directTestMap);
     await executePool({
         tasks,
         adapter,

package/dist/runner/pool-executor.js

@@ -64,9 +64,10 @@ export async function executePool(opts) {
     const poolDurationMs = Date.now() - poolStart;
     log.info(`\u2713 Worker pool ready (${poolDurationMs}ms)`);
     progress.start();
+    const fileCache = new Map();
     let nextIdx = 0;
     async function processTask(task) {
-        const { v, tests, key } = task;
+        const { v, tests, key, directTests } = task;
         log.debug('Cache ' + JSON.stringify(cache));
         const cached = cache[key];
         if (cached) {
@@ -98,7 +99,12 @@ export async function executePool(opts) {
         let mutatedSnippet;
         if (status === 'escaped') {
             try {
-                const originalLines = fs.readFileSync(v.file, 'utf8').split('\n');
+                let fileContent = fileCache.get(v.file);
+                if (fileContent === undefined) {
+                    fileContent = fs.readFileSync(v.file, 'utf8');
+                    fileCache.set(v.file, fileContent);
+                }
+                const originalLines = fileContent.split('\n');
                 const mutatedLines = v.code.split('\n');
                 const lineIdx = v.line - 1;
                 const orig = originalLines[lineIdx]?.trim();
@@ -119,6 +125,10 @@ export async function executePool(opts) {
             col: v.col,
             mutator: v.name,
             ...(originalSnippet !== undefined && { originalSnippet, mutatedSnippet }),
+            ...(status === 'escaped' &&
+                (directTests ?? tests).length > 0 && {
+                coveringTests: directTests ?? tests,
+            }),
         };
         progress.update(status);
     }

package/dist/runner/tasks.d.ts

@@ -1,12 +1,14 @@
 import type { Variant } from '../types/mutant.js';
 import type { PerTestCoverageMap } from '../utils/coverage.js';
+import type { TestMap } from './discover.js';
 export interface MutantTask {
     v: Variant;
     tests: string[];
     key: string;
+    directTests?: readonly string[];
 }
 /**
  * Prepare mutant tasks from variants by pruning tests via per-test coverage,
  * sorting tests deterministically, and computing cache keys.
  */
-export declare function prepareTasks(variants: readonly Variant[], perTestCoverage: PerTestCoverageMap | null): MutantTask[];
+export declare function prepareTasks(variants: readonly Variant[], perTestCoverage: PerTestCoverageMap | null, directTestMap?: TestMap): MutantTask[];

package/dist/runner/tasks.js

@@ -1,12 +1,13 @@
 import { filterTestsByCoverage } from './variants.js';
 import { hash, keyForTests } from './cache.js';
 import { createLogger } from '../utils/logger.js';
+import { normalizePath } from '../utils/normalizePath.js';
 const log = createLogger('tasks');
 /**
  * Prepare mutant tasks from variants by pruning tests via per-test coverage,
  * sorting tests deterministically, and computing cache keys.
  */
-export function prepareTasks(variants, perTestCoverage) {
+export function prepareTasks(variants, perTestCoverage, directTestMap) {
     return variants.map((v) => {
         let tests = Array.from(v.tests);
         if (perTestCoverage && tests.length) {
@@ -20,6 +21,13 @@ export function prepareTasks(variants, perTestCoverage) {
         const testSig = hash(keyForTests(tests));
         const codeSig = hash(v.code);
         const key = `${testSig}:${codeSig}`;
-        return { v, tests, key };
+        const direct = directTestMap?.get(normalizePath(v.file));
+        return {
+            v,
+            tests,
+            key,
+            ...(direct &&
+                direct.size > 0 && { directTests: Array.from(direct).sort() }),
+        };
     });
 }

package/dist/types/mutant.d.ts

@@ -27,6 +27,7 @@ export interface MutantCacheEntry extends MutantLocation {
     readonly mutator: string;
     readonly originalSnippet?: string;
     readonly mutatedSnippet?: string;
+    readonly coveringTests?: readonly string[];
 }
 export interface MutantResult extends MutantCacheEntry {
     readonly id: string;

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

@@ -71,6 +71,32 @@ describe('summary', () => {
         expect(lines.some((l) => l.trimStart().startsWith('+ '))).toBe(false);
         logSpy.mockRestore();
     });
+    it('prints covering test path for escaped mutant', () => {
+        const cache = {
+            a: makeEntry({
+                status: 'escaped',
+                coveringTests: ['/abs/foo.spec.ts'],
+            }),
+        };
+        const summary = computeSummary(cache);
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        printSummary(summary, cache);
+        const lines = logSpy.mock.calls.map((c) => stripAnsi(c.join(' ')));
+        expect(lines.some((l) => l.includes('↳'))).toBe(true);
+        expect(lines.some((l) => l.includes('foo.spec.ts'))).toBe(true);
+        logSpy.mockRestore();
+    });
+    it('does not print covering tests when array is absent', () => {
+        const cache = {
+            a: makeEntry({ status: 'escaped' }),
+        };
+        const summary = computeSummary(cache);
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        printSummary(summary, cache);
+        const lines = logSpy.mock.calls.map((c) => stripAnsi(c.join(' ')));
+        expect(lines.some((l) => l.includes('↳'))).toBe(false);
+        logSpy.mockRestore();
+    });
     it('summarise returns summary and prints', () => {
         const cache = { a: makeEntry({ status: 'killed' }) };
         const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });

package/dist/utils/summary.js

@@ -81,6 +81,15 @@ export function printSummary(summary, cache, durationMs) {
                 console.log('    ' + chalk.red('- ' + entry.originalSnippet));
                 console.log('    ' + chalk.green('+ ' + entry.mutatedSnippet));
             }
+            if (entry.coveringTests?.length) {
+                const shown = entry.coveringTests.slice(0, 2);
+                for (const t of shown) {
+                    console.log('    ' + chalk.dim('↳ ' + path.relative(cwd, t)));
+                }
+                if (entry.coveringTests.length > 2) {
+                    console.log('    ' + chalk.dim(`  +${entry.coveringTests.length - 2} more`));
+                }
+            }
         }
     }
     if (entriesByStatus.skipped.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutineerjs/mutineer",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "A fast, targeted mutation testing framework for JavaScript and TypeScript",
   "type": "module",
   "private": false,