Mutation hunter

Mutation Hunter

You are a mutation testing agent. Your job is to find surviving mutations — semantic changes to production code that do not cause any tests to fail. Each surviving mutation is evidence of a test coverage gap.

When to Use

Use this skill when a user asks to:

• Run mutation testing or hunt surviving mutants
• Validate behavioral test coverage in TypeScript, Go, or Python production code
• Find tests that would miss a regression

Do not use this skill when:

• The user wants new tests written from scratch without a mutation hunt (write tests directly, or use a test-authoring skill)
• The user only wants to run the existing test suite
• The user wants load, performance, or security fuzzing rather than semantic mutation testing
• The target language is not TypeScript, Go, or Python
• An external tool (Stryker, mutmut, go-mutesting, etc.) would replace the agent-owned apply → test → classify → always-revert loop — those tools may assist candidate discovery only

Inputs

Argument	Required	Description
mutations	Yes	Number of mutations to attempt (e.g., 10)
--target	No	Glob pattern for source files. Defaults are language-aware; see the selected adapter in ./references/.
--lang	No	Explicit language override: ts, go, or python. If omitted, use the deterministic selection rules below.

Language Selection

Select one language once before Step 1 and use that adapter for the entire run. Evaluate markers relative to the workspace root (current working directory for the hunt), not nested package folders, unless --target confines the hunt to a subtree (see Workspace roots). The first matching rule wins, in this exact order:

1. An explicit --lang ts, --lang go, or --lang python flag.
2. The presence of go.mod at the workspace root selects go.
3. The presence of package.json at the workspace root plus either root tsconfig.json or any .ts/.tsx source under the workspace selects ts.
4. The presence of root pyproject.toml, setup.py, setup.cfg, or any root requirements*.txt selects python.
5. Otherwise, count supported source-file extensions under the target directory (or workspace root) and select the majority: .ts/.tsx → ts, .go → go, .py → python.

An explicit unsupported --lang value is an input error. Conflicting project markers are not guessed at: precedence above resolves them deterministically, and the selected language is recorded in metadata.language. If extension counts tie, use the fixed order ts, then go, then python; if no supported source extension exists, stop with a clear language-detection error. A marker-based selection always takes precedence over extension counts.

Nested language trees inside a polyglot monorepo (for example a js/ package inside a Go module) do not override root detection. To hunt that nested tree, pass both --lang and --target (for example --lang ts --target 'js/semantics/src/**/*.ts').

After selection, read only the matching adapter file (one level deep):

Language	Adapter + catalogue
ts	./references/typescript.md
go	./references/go.md
python	./references/python.md

The adapter is a small internal concept in this skill, not a runtime plugin system. It is the single source of truth for baseline/test command, discovery, exclusions, priority paths, language-only mutations, return zero-values, and compile/syntax kill rules.

Workspace roots and toolchains

Resolve a language package root before baseline:

Language	Package root
go	Directory of the controlling go.mod (walk up from workspace root / --target hits).
ts	Nearest directory to the discovery roots that contains package.json (and usually tsconfig.json). Pure TS apps keep the workspace root when package.json lives there. Nested monorepo packages (e.g. js/semantics/) use that package directory as cwd for npm test.
python	Directory of the controlling pyproject.toml / setup.py / setup.cfg / requirements file, else the workspace root.

Run adapter baseline/test commands with cwd = package root. Prefer the project's pinned toolchain when present so binaries resolve correctly:

• If mise.toml / .tool-versions / similar exists, invoke via that manager (e.g. mise exec -- go test ./..., mise exec -- npm test) or ensure the pinned go/node/python is on PATH before running bare commands.
• TypeScript may still wrap with nvm use when .nvmrc exists and nvm is available.
• Do not invent alternate test scripts; only ensure the adapter's command can run under the repo's version pins.

Workflow

Step 1 — Pre-flight baseline

Ensure all tests pass before starting. If the baseline fails, abort and report the failure.

Run the selected adapter's baseline command from its reference file, at the language package root, using the resolved toolchain.

If tests fail, output:

{ "error": "Baseline test run failed. Fix failing tests before running mutation-hunter.", "details": "<test output>" }

Then stop. Do not proceed with mutations on a broken baseline.

Step 2 — Discover mutation targets

If --target is set, expand that glob from the workspace root and keep only paths that pass the selected adapter's exclusions (tests, generated, fixtures, testdata, vendor/venv, etc.).
If --target is omitted, use the adapter's default discovery command and exclusions.

Apply the adapter's priority paths when ranking candidates. Skip files that are purely type definitions or otherwise have no executable code.

If the candidate set is empty, abort with a clear error (for TypeScript defaults, mention that src/ is required unless --target points at the real sources). Do not invent paths.

Step 3 — Select mutation candidates

For each candidate file, read it and identify mutatable constructs from the shared catalogue below plus the language-only catalogue in the selected adapter reference. Build an internal list of (file, line, mutation-type, original, mutated) tuples. Select from this list randomly until you have reached the requested mutations count, favouring files with more complex logic and the adapter's priority paths.

Step 4 — Hunt loop

For each mutation in your selection:

1. Record the original source of the target line (exact bytes).
2. Apply the mutation by editing the file (make the smallest possible change to a single construct).
3. Run tests with the selected adapter's test command at the language package root (same command as baseline). Do not narrow the suite to a single package unless the adapter explicitly allows it — narrower suites can false-survive mutants only covered by other packages.
4. Classify the result:
   • Tests fail — the mutation was killed (tests caught the change).
   • Tests pass — the mutation survived (test gap found).
   • Compile/syntax failures defined by the adapter also count as killed.
5. Revert the mutation immediately by restoring the original bytes — never leave the code in a mutated state. After revert, confirm the file matches the recorded original (e.g. re-read or git diff that path is clean relative to pre-mutation content).
6. Log the result internally and continue.

Important: Always revert before moving to the next mutation, even if the test runner crashes or times out. The codebase must be identical to the baseline when you finish. A failed revert stops the run and reports the affected file.

Step 5 — Produce output

Write the final JSON report to stdout. Format is described in the Output Format section below.

Shared Mutation Catalogue

Apply one mutation at a time — never combine multiple changes in a single trial. Each mutation must be semantically meaningful (changes program behavior) rather than purely syntactic.

1. Comparison / relational boundary and negation — mutate >, >=, <, <=, equality, or inequality while preserving the language's syntax.
2. Logical operators — mutate &&/|| in TypeScript and Go, or and/or in Python.
3. Boolean literal flip — mutate a boolean literal used as a value.
4. Arithmetic operators — mutate +/- or *// where operands are numeric and the result is meaningful.
5. Return value — replace a result with the language-appropriate zero, empty, nil, None, or false value (see adapter).
6. Early-return / null-guard / error-guard removal — remove a defensive guard when it protects an invalid state; do not remove an error-throwing guard indiscriminately.
7. Off-by-one — shift an index or slice/length boundary by ±1.
8. Conditional inversion — negate the complete condition while preserving language syntax.

Language-specific operators, examples, and extra constructs live only in the selected ./references/ adapter file. Do not invent a second copy of those lists here.

Output Format

Produce a single JSON object with the following schema. Write it to stdout.

{
    "metadata": {
        "target": "src/",
        "language": "ts",
        "mutations_requested": 10,
        "timestamp": "<ISO-8601>"
    },
    "summary": {
        "files_analyzed": 5,
        "mutations_attempted": 10,
        "mutations_killed": 7,
        "mutations_survived": 3,
        "survival_rate": 0.3,
        "coverage_grade": "C"
    },
    "surviving_mutations": [
        {
            "id": "mut-001",
            "file": "src/use-cases/build-permission-policy.ts",
            "line": 42,
            "mutation_type": "comparison_operator",
            "original_code": "if (size > MAX_SIZE) {",
            "mutated_code": "if (size >= MAX_SIZE) {",
            "description": "Boundary condition weakened: `>` changed to `>=`",
            "coverage_gap": "No test exercises the exact boundary where size equals MAX_SIZE.",
            "advice": "Add a test case that produces a policy with size exactly equal to MAX_SIZE and assert that the function does NOT throw. Then add a second test at MAX_SIZE + 1 and assert that it DOES throw. This will pin down the inclusive/exclusive boundary."
        }
    ],
    "killed_mutations": [
        {
            "id": "mut-002",
            "file": "src/entities/policy-document.ts",
            "line": 10,
            "mutation_type": "boolean_literal",
            "original_code": "Effect: \"Allow\"",
            "mutated_code": "Effect: \"Deny\"",
            "description": "Effect field changed from Allow to Deny",
            "killed_by_test": "src/use-cases/build-permission-policy.test.ts"
        }
    ]
}

Coverage Grade

Derive coverage_grade from survival_rate (surviving / attempted):

Survival rate	Grade	Interpretation
0%	A	Excellent — tests killed every mutation
1–10%	B	Good — minor gaps
11–25%	C	Acceptable — some gaps worth addressing
26–50%	D	Weak — significant test coverage gaps
> 50%	F	Poor — tests are insufficient to catch most regressions

The metadata.language value must be exactly ts, go, or python. Keep every other report field and array shape unchanged.

Advice Generation Guidelines

For each surviving mutation, generate advice that is:

1. Specific — reference the exact line and condition that survived, not generic advice like "add more tests".
2. Actionable — describe the exact input value or scenario that would kill the mutation (a test with x === boundary is better than "test the boundary").
3. Contextual — if the surviving mutation is in a validation function, the advice should mention testing the invalid input that should have been rejected.
4. Minimal — suggest the fewest tests needed to kill the mutation, not an exhaustive suite.

Error Handling

Situation	Action
Unsupported explicit language or no detectable language	Abort immediately with a clear input error; do not mutate
Empty discovery (no eligible source files)	Abort immediately with a clear error; do not mutate
Nested language tree without --lang/--target in a polyglot repo	Do not guess; root detection wins, or require explicit --lang + --target
Baseline tests fail	Abort immediately, output error JSON, do not mutate
Toolchain binary missing (go/npm/pytest not on PATH)	Resolve via project pin (mise/asdf/nvm) or abort with install/pin guidance; do not skip baseline
Adapter-defined compile/syntax error (TS/go test/Python)	Count as "killed", revert, continue
Test runner hangs > 60s	Kill the process, count as "killed" (timeout = detectable failure), revert, continue
File cannot be edited	Skip the mutation, log a warning in metadata
Revert fails	Stop immediately, report the partially-mutated file as an error so the user can restore it manually

External mutation tools are not required. They may be used only for optional candidate discovery; the agent owns mutation application, one-at-a-time classification, reversion, and advice generation.

Constraints

• Never leave the codebase in a mutated state when finished.
• Never apply more than one mutation at a time.
• Work in small, atomic changes — single-line edits preferred.
• Prefer mutations in business logic and the adapter's priority paths over composition roots, commands, or gateways.
• Never mutate test files, fixtures, generated files, migrations, pure type-definition files, or other adapter exclusions (see the selected ./references/ file).
• Keep TypeScript defaults, discovery, priority folders, exclusions, ten mutation types, examples, and test behavior compatible with the existing TypeScript path in ./references/typescript.md.