@mutineerjs/mutineer 0.2.3 → 0.3.2

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

@@ -0,0 +1,239 @@
+import { describe, it, expect } from 'vitest';
+import { returnToNull, returnToUndefined, returnFlipBool, returnZero, returnEmptyStr, returnEmptyArr, } from '../return-value.js';
+// ---------------------------------------------------------------------------
+// returnToNull
+// ---------------------------------------------------------------------------
+describe('returnToNull', () => {
+    it('replaces an identifier return with null', () => {
+        const src = `function f() { return x }`;
+        const [mutation] = returnToNull.apply(src);
+        expect(mutation.code).toBe(`function f() { return null }`);
+    });
+    it('replaces a function call return with null', () => {
+        const src = `function f() { return getValue() }`;
+        const [mutation] = returnToNull.apply(src);
+        expect(mutation.code).toBe(`function f() { return null }`);
+    });
+    it('replaces a numeric literal return with null', () => {
+        const src = `function f() { return 42 }`;
+        const [mutation] = returnToNull.apply(src);
+        expect(mutation.code).toBe(`function f() { return null }`);
+    });
+    it('replaces an object expression return with null', () => {
+        const src = `function f() { return { a: 1 } }`;
+        const [mutation] = returnToNull.apply(src);
+        expect(mutation.code).toBe(`function f() { return null }`);
+    });
+    it('does not mutate bare return;', () => {
+        const src = `function f() { return }`;
+        const results = returnToNull.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('does not mutate return null', () => {
+        const src = `function f() { return null }`;
+        const results = returnToNull.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('produces one mutation per matching return statement', () => {
+        const src = `
+function f() {
+  if (x) return a
+  return b
+}
+`;
+        const results = returnToNull.apply(src);
+        expect(results).toHaveLength(2);
+        expect(results[0].code).toContain('return null');
+        expect(results[1].code).toContain('return null');
+    });
+    it('reports the correct line for the return statement', () => {
+        const src = `function f() {\n  return x\n}`;
+        const [mutation] = returnToNull.apply(src);
+        expect(mutation.line).toBe(2);
+    });
+    it('respects mutineer-disable-next-line', () => {
+        const src = `
+function f() {
+  // mutineer-disable-next-line
+  return x
+  return y
+}
+`;
+        const results = returnToNull.apply(src);
+        expect(results).toHaveLength(1);
+        expect(results[0].code).toContain('return null');
+    });
+    it('respects mutineer-disable-line', () => {
+        const src = `
+function f() {
+  return x // mutineer-disable-line
+  return y
+}
+`;
+        const results = returnToNull.apply(src);
+        expect(results).toHaveLength(1);
+    });
+});
+// ---------------------------------------------------------------------------
+// returnToUndefined
+// ---------------------------------------------------------------------------
+describe('returnToUndefined', () => {
+    it('replaces an identifier return with undefined', () => {
+        const src = `function f() { return x }`;
+        const [mutation] = returnToUndefined.apply(src);
+        expect(mutation.code).toBe(`function f() { return undefined }`);
+    });
+    it('replaces a function call return with undefined', () => {
+        const src = `function f() { return getValue() }`;
+        const [mutation] = returnToUndefined.apply(src);
+        expect(mutation.code).toBe(`function f() { return undefined }`);
+    });
+    it('replaces null with undefined', () => {
+        const src = `function f() { return null }`;
+        const [mutation] = returnToUndefined.apply(src);
+        expect(mutation.code).toBe(`function f() { return undefined }`);
+    });
+    it('does not mutate bare return;', () => {
+        const src = `function f() { return }`;
+        const results = returnToUndefined.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('does not mutate return undefined', () => {
+        const src = `function f() { return undefined }`;
+        const results = returnToUndefined.apply(src);
+        expect(results).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// returnFlipBool
+// ---------------------------------------------------------------------------
+describe('returnFlipBool', () => {
+    it('flips return true to return false', () => {
+        const src = `function f() { return true }`;
+        const [mutation] = returnFlipBool.apply(src);
+        expect(mutation.code).toBe(`function f() { return false }`);
+    });
+    it('flips return false to return true', () => {
+        const src = `function f() { return false }`;
+        const [mutation] = returnFlipBool.apply(src);
+        expect(mutation.code).toBe(`function f() { return true }`);
+    });
+    it('does not mutate non-boolean returns', () => {
+        const src = `function f() { return x }`;
+        const results = returnFlipBool.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('does not mutate bare return;', () => {
+        const src = `function f() { return }`;
+        const results = returnFlipBool.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('handles multiple boolean returns independently', () => {
+        const src = `
+function f(x) {
+  if (x) return true
+  return false
+}
+`;
+        const results = returnFlipBool.apply(src);
+        expect(results).toHaveLength(2);
+        expect(results[0].code).toContain('return false');
+        expect(results[1].code).toContain('return true');
+    });
+});
+// ---------------------------------------------------------------------------
+// returnZero
+// ---------------------------------------------------------------------------
+describe('returnZero', () => {
+    it('replaces a positive integer return with 0', () => {
+        const src = `function f() { return 42 }`;
+        const [mutation] = returnZero.apply(src);
+        expect(mutation.code).toBe(`function f() { return 0 }`);
+    });
+    it('replaces a negative number return with 0', () => {
+        const src = `function f() { return -1 }`;
+        // -1 is a UnaryExpression, not a NumericLiteral — should produce no output
+        const results = returnZero.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('replaces a float return with 0', () => {
+        const src = `function f() { return 3.14 }`;
+        const [mutation] = returnZero.apply(src);
+        expect(mutation.code).toBe(`function f() { return 0 }`);
+    });
+    it('does not mutate return 0', () => {
+        const src = `function f() { return 0 }`;
+        const results = returnZero.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('does not mutate non-numeric returns', () => {
+        const src = `function f() { return x }`;
+        const results = returnZero.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('does not mutate bare return;', () => {
+        const src = `function f() { return }`;
+        const results = returnZero.apply(src);
+        expect(results).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// returnEmptyStr
+// ---------------------------------------------------------------------------
+describe('returnEmptyStr', () => {
+    it("replaces a non-empty string return with ''", () => {
+        const src = `function f() { return 'hello' }`;
+        const [mutation] = returnEmptyStr.apply(src);
+        expect(mutation.code).toBe(`function f() { return '' }`);
+    });
+    it('replaces a double-quoted string return', () => {
+        const src = `function f() { return "world" }`;
+        const [mutation] = returnEmptyStr.apply(src);
+        expect(mutation.code).toBe(`function f() { return '' }`);
+    });
+    it("does not mutate return ''", () => {
+        const src = `function f() { return '' }`;
+        const results = returnEmptyStr.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('does not mutate non-string returns', () => {
+        const src = `function f() { return x }`;
+        const results = returnEmptyStr.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('does not mutate bare return;', () => {
+        const src = `function f() { return }`;
+        const results = returnEmptyStr.apply(src);
+        expect(results).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// returnEmptyArr
+// ---------------------------------------------------------------------------
+describe('returnEmptyArr', () => {
+    it('replaces a non-empty array return with []', () => {
+        const src = `function f() { return [1, 2, 3] }`;
+        const [mutation] = returnEmptyArr.apply(src);
+        expect(mutation.code).toBe(`function f() { return [] }`);
+    });
+    it('replaces a single-element array return with []', () => {
+        const src = `function f() { return [x] }`;
+        const [mutation] = returnEmptyArr.apply(src);
+        expect(mutation.code).toBe(`function f() { return [] }`);
+    });
+    it('does not mutate return []', () => {
+        const src = `function f() { return [] }`;
+        const results = returnEmptyArr.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('does not mutate non-array returns', () => {
+        const src = `function f() { return x }`;
+        const results = returnEmptyArr.apply(src);
+        expect(results).toHaveLength(0);
+    });
+    it('does not mutate bare return;', () => {
+        const src = `function f() { return }`;
+        const results = returnEmptyArr.apply(src);
+        expect(results).toHaveLength(0);
+    });
+});

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

@@ -1,5 +1,72 @@
 import { describe, it, expect } from 'vitest';
-import { collectOperatorTargets } from '../utils.js';
+import { collectOperatorTargets, buildIgnoreLines, parseSource, } from '../utils.js';
+// ---------------------------------------------------------------------------
+// buildIgnoreLines
+// ---------------------------------------------------------------------------
+describe('buildIgnoreLines', () => {
+    function comment(text, startLine, endLine = startLine) {
+        return {
+            type: 'CommentLine',
+            value: ` ${text}`,
+            start: 0,
+            end: 0,
+            loc: {
+                start: { line: startLine, column: 0, index: 0 },
+                end: { line: endLine, column: 0, index: 0 },
+            },
+        };
+    }
+    it('ignores the line after mutineer-disable-next-line', () => {
+        // The text also contains 'mutineer-disable' as a substring, so the
+        // comment line itself is ignored in addition to the following line.
+        const lines = buildIgnoreLines([comment('mutineer-disable-next-line', 3)]);
+        expect(lines.has(4)).toBe(true);
+        expect(lines.has(3)).toBe(true);
+        expect(lines.has(5)).toBe(false);
+    });
+    it('ignores the comment line itself for mutineer-disable-line', () => {
+        const lines = buildIgnoreLines([comment('mutineer-disable-line', 5)]);
+        expect(lines.has(5)).toBe(true);
+        expect(lines.has(6)).toBe(false);
+    });
+    it('ignores all lines spanned by a mutineer-disable block comment', () => {
+        const lines = buildIgnoreLines([comment('mutineer-disable', 2, 4)]);
+        expect(lines.has(2)).toBe(true);
+        expect(lines.has(3)).toBe(true);
+        expect(lines.has(4)).toBe(true);
+        expect(lines.has(1)).toBe(false);
+        expect(lines.has(5)).toBe(false);
+    });
+    it('ignores comments without loc', () => {
+        const c = {
+            ...comment('mutineer-disable-next-line', 1),
+            loc: undefined,
+        };
+        expect(() => buildIgnoreLines([c])).not.toThrow();
+    });
+    it('returns an empty set when there are no disable comments', () => {
+        const lines = buildIgnoreLines([comment('just a normal comment', 1)]);
+        expect(lines.size).toBe(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// parseSource
+// ---------------------------------------------------------------------------
+describe('parseSource', () => {
+    it('parses valid TypeScript source without throwing', () => {
+        expect(() => parseSource(`const x: number = 1`)).not.toThrow();
+    });
+    it('parses JSX without throwing', () => {
+        expect(() => parseSource(`const el = <div />`)).not.toThrow();
+    });
+    it('returns a File node', () => {
+        const ast = parseSource(`const x = 1`);
+        expect(ast.type).toBe('File');
+    });
+});
+// ---------------------------------------------------------------------------
+// collectOperatorTargets
+// ---------------------------------------------------------------------------
 describe('collectOperatorTargets', () => {
     it('honors mutineer disable comments', () => {
         const src = `// mutineer-disable-next-line

package/dist/mutators/operator.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Operator mutators.
+ *
+ * Each mutator finds every occurrence of a specific binary/logical operator
+ * using AST traversal and produces a mutated source string with that operator
+ * replaced by its counterpart.
+ */
+import type { ASTMutator } from './types.js';
+export declare const relaxLE: ASTMutator;
+export declare const relaxGE: ASTMutator;
+export declare const tightenLT: ASTMutator;
+export declare const tightenGT: ASTMutator;
+export declare const andToOr: ASTMutator;
+export declare const orToAnd: ASTMutator;
+export declare const nullishToOr: ASTMutator;
+export declare const flipEQ: ASTMutator;
+export declare const flipNEQ: ASTMutator;
+export declare const flipStrictEQ: ASTMutator;
+export declare const flipStrictNEQ: ASTMutator;
+export declare const addToSub: ASTMutator;
+export declare const subToAdd: ASTMutator;
+export declare const mulToDiv: ASTMutator;
+export declare const divToMul: ASTMutator;
+export declare const modToMul: ASTMutator;
+export declare const powerToMul: ASTMutator;

package/dist/mutators/operator.js

@@ -0,0 +1,50 @@
+/**
+ * Operator mutators.
+ *
+ * Each mutator finds every occurrence of a specific binary/logical operator
+ * using AST traversal and produces a mutated source string with that operator
+ * replaced by its counterpart.
+ */
+import { collectOperatorTargets } from './utils.js';
+/**
+ * Factory to build an operator mutator using AST traversal and token analysis.
+ *
+ * @param name - Mutator name used in the registry and config include/exclude
+ * @param description - Human-readable description shown in reports
+ * @param fromOp - The operator to find (e.g., '&&')
+ * @param toOp - The operator to replace it with (e.g., '||')
+ */
+function makeOperatorMutator(name, description, fromOp, toOp) {
+    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),
+            }));
+        },
+    };
+}
+/* === Boundary mutators === */
+export const relaxLE = makeOperatorMutator('relaxLE', "Change '<=' to '<' (relax boundary)", '<=', '<');
+export const relaxGE = makeOperatorMutator('relaxGE', "Change '>=' to '>' (relax boundary)", '>=', '>');
+export const tightenLT = makeOperatorMutator('tightenLT', "Change '<' to '<=' (tighten boundary)", '<', '<=');
+export const tightenGT = makeOperatorMutator('tightenGT', "Change '>' to '>=' (tighten boundary)", '>', '>=');
+/* === Logical mutators === */
+export const andToOr = makeOperatorMutator('andToOr', "Change '&&' to '||'", '&&', '||');
+export const orToAnd = makeOperatorMutator('orToAnd', "Change '||' to '&&'", '||', '&&');
+export const nullishToOr = makeOperatorMutator('nullishToOr', "Change '??' to '||'", '??', '||');
+/* === Equality mutators === */
+export const flipEQ = makeOperatorMutator('flipEQ', "Change '==' to '!='", '==', '!=');
+export const flipNEQ = makeOperatorMutator('flipNEQ', "Change '!=' to '=='", '!=', '==');
+export const flipStrictEQ = makeOperatorMutator('flipStrictEQ', "Change '===' to '!=='", '===', '!==');
+export const flipStrictNEQ = makeOperatorMutator('flipStrictNEQ', "Change '!==' to '==='", '!==', '===');
+/* === Arithmetic mutators === */
+export const addToSub = makeOperatorMutator('addToSub', "Change '+' to '-'", '+', '-');
+export const subToAdd = makeOperatorMutator('subToAdd', "Change '-' to '+'", '-', '+');
+export const mulToDiv = makeOperatorMutator('mulToDiv', "Change '*' to '/'", '*', '/');
+export const divToMul = makeOperatorMutator('divToMul', "Change '/' to '*'", '/', '*');
+export const modToMul = makeOperatorMutator('modToMul', "Change '%' to '*'", '%', '*');
+export const powerToMul = makeOperatorMutator('powerToMul', "Change '**' to '*'", '**', '*');

package/dist/mutators/registry.d.ts

@@ -1,37 +1,15 @@
 /**
- * Mutator registry and factory.
+ * Mutator registry.
  *
- * Provides functions to create operator mutators and retrieve registered mutators
- * with optional include/exclude filtering.
+ * Aggregates all mutators and exposes `getRegistry` for filtered access.
  */
 import type { ASTMutator } from './types.js';
-export declare const relaxLE: ASTMutator;
-export declare const relaxGE: ASTMutator;
-export declare const tightenLT: ASTMutator;
-export declare const tightenGT: ASTMutator;
-export declare const andToOr: ASTMutator;
-export declare const orToAnd: ASTMutator;
-export declare const nullishToOr: ASTMutator;
-export declare const flipEQ: ASTMutator;
-export declare const flipNEQ: ASTMutator;
-export declare const flipStrictEQ: ASTMutator;
-export declare const flipStrictNEQ: ASTMutator;
-export declare const addToSub: ASTMutator;
-export declare const subToAdd: ASTMutator;
-export declare const mulToDiv: ASTMutator;
-export declare const divToMul: ASTMutator;
-export declare const modToMul: ASTMutator;
-export declare const powerToMul: ASTMutator;
 /**
- * Get a filtered registry of mutators based on include/exclude options.
+ * Get a filtered list of mutators.
  *
- * If include list provided, only those mutators are returned.
- * If exclude list provided, those mutators are filtered out.
- * Include list takes precedence over exclude list.
- *
- * @param include - Optional list of mutator names to include
- * @param exclude - Optional list of mutator names to exclude
- * @returns Filtered array of mutators
+ * If `include` is provided, only those mutators are returned.
+ * If `exclude` is provided, those mutators are removed.
+ * `include` takes precedence over `exclude`.
  */
 export declare function getRegistry(include?: readonly string[], exclude?: readonly string[]): ASTMutator[];
 export type { ASTMutator, AnyMutator, MutationOutput } from './types.js';

package/dist/mutators/registry.js

@@ -1,62 +1,10 @@
 /**
- * Mutator registry and factory.
+ * Mutator registry.
  *
- * Provides functions to create operator mutators and retrieve registered mutators
- * with optional include/exclude filtering.
- */
-import { collectOperatorTargets } from './utils.js';
-/**
- * Factory to build an operator mutator using AST traversal and token analysis.
- * Creates a reusable mutator that finds and replaces a specific operator throughout the code.
- *
- * @param name - Name of the mutator (e.g., 'andToOr')
- * @param description - Human-readable description
- * @param fromOp - The operator to find (e.g., '&&')
- * @param toOp - The operator to replace it with (e.g., '||')
- * @returns An ASTMutator that applies this transformation
- */
-function makeOperatorMutator(name, description, fromOp, toOp) {
-    return {
-        name,
-        description,
-        apply(src) {
-            // 1) Collect exact operator token locations from matching nodes
-            const targets = collectOperatorTargets(src, fromOp);
-            // 2) For each occurrence, produce a mutated version of the programme
-            const outputs = [];
-            for (const target of targets) {
-                const code = src.slice(0, target.start) + toOp + src.slice(target.end);
-                outputs.push({
-                    line: target.line,
-                    col: target.col1,
-                    code,
-                });
-            }
-            return outputs;
-        },
-    };
-}
-/* === Concrete mutators (AST-safe) === */
-export const relaxLE = makeOperatorMutator('relaxLE', "Change '<=' to '<' (relax boundary)", '<=', '<');
-export const relaxGE = makeOperatorMutator('relaxGE', "Change '>=' to '>' (relax boundary)", '>=', '>');
-export const tightenLT = makeOperatorMutator('tightenLT', "Change '<' to '<=' (tighten boundary)", '<', '<=');
-export const tightenGT = makeOperatorMutator('tightenGT', "Change '>' to '>=' (tighten boundary)", '>', '>=');
-export const andToOr = makeOperatorMutator('andToOr', "Change '&&' to '||' in boolean expressions", '&&', '||');
-export const orToAnd = makeOperatorMutator('orToAnd', "Change '||' to '&&' in boolean expressions", '||', '&&');
-export const nullishToOr = makeOperatorMutator('nullishToOr', "Change '??' to '||' to prefer boolean fallback", '??', '||');
-export const flipEQ = makeOperatorMutator('flipEQ', "Change '==' to '!='", '==', '!=');
-export const flipNEQ = makeOperatorMutator('flipNEQ', "Change '!=' to '=='", '!=', '==');
-export const flipStrictEQ = makeOperatorMutator('flipStrictEQ', "Change '===' to '!=='", '===', '!==');
-export const flipStrictNEQ = makeOperatorMutator('flipStrictNEQ', "Change '!==' to '==='", '!==', '===');
-export const addToSub = makeOperatorMutator('addToSub', "Change '+' to '-' in arithmetic expressions", '+', '-');
-export const subToAdd = makeOperatorMutator('subToAdd', "Change '-' to '+' in arithmetic expressions", '-', '+');
-export const mulToDiv = makeOperatorMutator('mulToDiv', "Change '*' to '/' in arithmetic expressions", '*', '/');
-export const divToMul = makeOperatorMutator('divToMul', "Change '/' to '*' in arithmetic expressions", '/', '*');
-export const modToMul = makeOperatorMutator('modToMul', "Change '%' to '*' in arithmetic expressions", '%', '*');
-export const powerToMul = makeOperatorMutator('powerToMul', "Change '**' to '*' in arithmetic expressions", '**', '*');
-/**
- * All registered mutators in order of precedence.
+ * Aggregates all mutators and exposes `getRegistry` for filtered access.
  */
+import { relaxLE, relaxGE, tightenLT, tightenGT, andToOr, orToAnd, nullishToOr, flipEQ, flipNEQ, flipStrictEQ, flipStrictNEQ, addToSub, subToAdd, mulToDiv, divToMul, modToMul, powerToMul, } from './operator.js';
+import { returnToNull, returnToUndefined, returnFlipBool, returnZero, returnEmptyStr, returnEmptyArr, } from './return-value.js';
 const ALL = [
     relaxLE,
     relaxGE,
@@ -75,25 +23,25 @@ const ALL = [
     divToMul,
     modToMul,
     powerToMul,
+    returnToNull,
+    returnToUndefined,
+    returnFlipBool,
+    returnZero,
+    returnEmptyStr,
+    returnEmptyArr,
 ];
 /**
- * Get a filtered registry of mutators based on include/exclude options.
- *
- * If include list provided, only those mutators are returned.
- * If exclude list provided, those mutators are filtered out.
- * Include list takes precedence over exclude list.
+ * Get a filtered list of mutators.
  *
- * @param include - Optional list of mutator names to include
- * @param exclude - Optional list of mutator names to exclude
- * @returns Filtered array of mutators
+ * If `include` is provided, only those mutators are returned.
+ * If `exclude` is provided, those mutators are removed.
+ * `include` takes precedence over `exclude`.
  */
 export function getRegistry(include, exclude) {
     let list = ALL;
-    // If include list provided, filter to only those mutators
     if (include?.length) {
         list = list.filter((m) => include.includes(m.name));
     }
-    // If exclude list provided, remove those mutators
     if (exclude?.length) {
         list = list.filter((m) => !exclude.includes(m.name));
     }

package/dist/mutators/return-value.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Return value mutators.
+ *
+ * These mutators target `return` statements and replace the returned expression
+ * with a simpler or opposite value. They catch a different class of test gap
+ * from operator mutators: they reveal when callers never check what a function
+ * returns (e.g. no null-check, no assertion on the return value).
+ */
+import type { ASTMutator } from './types.js';
+/**
+ * Replace any non-null return value with `null`.
+ * Reveals callers that never check for null returns.
+ */
+export declare const returnToNull: ASTMutator;
+/**
+ * Replace any non-undefined return value with `undefined`.
+ * Reveals callers that never guard against undefined returns.
+ */
+export declare const returnToUndefined: ASTMutator;
+/**
+ * Flip `return true` ↔ `return false`.
+ * Catches missing assertions on boolean-returning functions.
+ */
+export declare const returnFlipBool: ASTMutator;
+/**
+ * Replace a non-zero numeric return with `0`.
+ * Catches callers that never check the numeric return value.
+ */
+export declare const returnZero: ASTMutator;
+/**
+ * Replace a non-empty string return with `''`.
+ * Catches callers that never check the string return value.
+ */
+export declare const returnEmptyStr: ASTMutator;
+/**
+ * Replace an array expression return with `[]`.
+ * Catches callers that never check for an empty array.
+ */
+export declare const returnEmptyArr: ASTMutator;