Files
claude-config/bin/mutate_changes/main.py
T

153 lines
7.8 KiB
Python

"""Mutation-test the lines a branch adds or changes, and print each mutant its tests don't kill.
usage: mutate-changes [--base <ref>] [--prefix <shell text>] [--jobs <n>]
Run it in a checkout, under ~/.claude/bin/run-heavy. It diffs the working tree's tracked files against the merge base of HEAD and
--base, by default the default branch: origin's as last fetched, else main or master. It picks the tool by each changed file's
extension, and leaves out test files: test_*.py, *_test.py, conftest.py, *.test.* and *.spec.*, and any file under a tests/, test/
or __tests__/ folder.
- .py: mutmut 3, in a scratch copy of the nearest folder above the file that holds a setup.cfg or a pyproject.toml, else of the
checkout's top. It mutates each function or method a changed line falls in, and counts the mutants on changed lines. The
folder's setup.cfg settings stay, but source_paths and also_copy are set, and pytest leaves out each test that fails without a
mutant; the report names their files. mutmut sees only the code a test runs in its own process, so a mutant that only a child
process reaches, such as a tool a test starts, shows as `no tests`. A pyproject.toml with a [tool.mutmut] section fails the run.
- .rs: cargo-mutants, as `cargo mutants --in-diff`, in the checkout's top.
- .cjs, .cts, .js, .jsx, .mjs, .mts, .ts, .tsx: Stryker, as `npx --no --package=@stryker-mutator/core stryker run --mutate` on the
changed lines, in the nearest folder above the file that holds a package.json. A file with no package.json above it isn't
mutated. npx runs the project's own @stryker-mutator/core, else one an earlier npx run cached, and installs none.
- .php: Infection, as `vendor/bin/infection --git-diff-lines`, in the checkout's top.
--prefix is shell text that runs each tool: sh runs `<prefix> "$@"` in the tool's folder, which $PWD names, with the tool's command
as "$@". For example, 'uvx --from "mutmut>=3,<4"'. Without --prefix, the command runs as it is. A container must mount $PWD and
run there, as 'docker compose -f "$(git rev-parse --show-toplevel)/compose.yaml" run --rm -v "$PWD:$PWD" -w "$PWD" app' does. "$1"
is the command's first word, mutmut, cargo, npx or vendor/bin/infection, so a prefix can pick what to run per tool:
'case "$1" in mutmut) set -- uvx --from "mutmut>=3,<4" "$@";; esac;'.
--jobs sets how many tests each tool runs at once, 4 by default: one heavy slot's CPUs. Under run-heavy, a container that sets
neither memory limit gets the slot's share, in MiB in RUN_HEAVY_MEMORY; set --jobs so that that many test runs fit in it.
It prints:
- for mutmut, per folder, a line with the mutant count, then a line per mutant on a changed line that is not killed, as
`<path>:<line>: <status>: <the line as mutated>`, or `<path>: <status>: <name>, on a line mutate-changes cannot find`;
- for cargo-mutants, a line with the mutant count, then a line per mutant it missed or that timed out, as
`<path>:<line>:<column>: <outcome>: <mutation>`;
- for Stryker and Infection, a line naming the folder the tool ran in, then the tool's own report;
- a line naming the changed JavaScript and TypeScript files with no package.json above them;
- a line naming the changed files in a language no tool covers, then one naming the changed test files, none of which it mutates;
- last, the wall time.
Exit 1, saying why, on an unknown or repeated argument, an option without its value, or a --jobs that is no whole number from 1.
Exit 1 too when git fails, a file cannot be read or copied, a tool cannot start, or a tool fails before it reports. Stryker and
Infection also exit nonzero on a mutation score below a threshold the project sets, which fails the run as well and prints their
whole report.
"""
import functools
import os
import sys
import time
import typing
from mutate_changes.changed_lines import added_lines, not_mutated, tool_for
from machine_load.slots import CPUS_PER_SLOT
from git_cli.git_repo import default_ref, Git, top
from failure import Failure
from git_cli import git_repo
from mutate_changes.in_diff_tools import run_cargo_mutants, run_infection, run_stryker
from mutate_changes.mutmut_tool import run_mutmut
from mutate_changes.tool_process import run_tool
USAGE = "usage: mutate-changes [--base <ref>] [--prefix <shell text>] [--jobs <n>]"
# A panel of three readers, seated as the README's audience, picked the command's name and these options on 2026-11-11.
OPTIONS = ("--base", "--jobs", "--prefix")
def main(argv: list[str], env: typing.Mapping[str, str]) -> int:
"""Runs mutate-changes with the arguments argv; git and each tool run in the environment env."""
if argv in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
given = options(argv)
if isinstance(given, Failure):
print(f"{given.reason}; {USAGE}", file=sys.stderr)
return 1
started = time.monotonic()
report = mutate(given, env)
if isinstance(report, Failure):
print(report.reason, file=sys.stderr)
return 1
print("\n".join([*report, f"mutate-changes took {took(time.monotonic() - started)}."]))
return 0
def options(argv: list[str]) -> dict[str, str] | Failure:
given: dict[str, str] = {}
rest = list(argv)
while rest:
name, equals, value = rest.pop(0).partition("=")
if name not in OPTIONS or name in given:
return Failure(f"unknown or repeated argument {name}")
if not equals and not rest:
return Failure(f"{name} needs a value")
given[name] = value if equals else rest.pop(0)
if not given.get("--jobs", "1").isdecimal() or int(given.get("--jobs", "1")) < 1:
return Failure(f"--jobs takes a whole number from 1, not {given['--jobs']}")
return given
def mutate(given: dict[str, str], env: typing.Mapping[str, str]) -> list[str] | Failure:
"""Each tool's report on the lines the branch adds, then the lines naming the changed files no tool mutates."""
git = functools.partial(git_repo.git, env=env)
checkout = top(git)
if isinstance(checkout, Failure):
return checkout
base = given.get("--base") or default_ref(cwd=checkout, run=git)
if isinstance(base, Failure):
return base
found = git("merge-base", base, "HEAD", cwd=checkout)
if isinstance(found, Failure):
return found
merge_base = found.strip()
names = git("diff", "--name-only", "-z", "--diff-filter=d", merge_base, cwd=checkout)
if isinstance(names, Failure):
return names
paths = list(filter(None, names.split("\0")))
changed = changed_by_tool(checkout, merge_base, paths, git)
if isinstance(changed, Failure):
return changed
jobs = int(given.get("--jobs", CPUS_PER_SLOT))
run = functools.partial(run_tool, prefix=given.get("--prefix"), env=env, killpg=os.killpg)
report = [] if changed else ["No tool ran: the branch adds no line to a file that a tool mutates."]
for tool, files in sorted(changed.items()):
if tool == "cargo-mutants":
lines = run_cargo_mutants(checkout, merge_base, sorted(files), run, git, jobs)
elif tool == "infection":
lines = run_infection(checkout, merge_base, run, jobs)
elif tool == "stryker":
lines = run_stryker(checkout, files, run, jobs)
else:
lines = run_mutmut(checkout, files, run, git, jobs)
if isinstance(lines, Failure):
return lines
report.extend(lines)
return [*report, *not_mutated(paths)]
def changed_by_tool(checkout: str, merge_base: str, paths: list[str], git: Git) -> dict[str, dict[str, frozenset[int]]] | Failure:
"""Each tool's files among paths, by path from the checkout's top, with the lines the working tree adds since merge_base."""
changed: dict[str, dict[str, frozenset[int]]] = {}
for path in paths:
if (tool := tool_for(path)) is None:
continue
diff = git("diff", "-U0", "--no-color", "--no-ext-diff", "--no-textconv", merge_base, "--", path, cwd=checkout, errors="replace")
if isinstance(diff, Failure):
return diff
if lines := added_lines(diff):
changed.setdefault(tool, {})[path] = lines
return changed
def took(seconds: float) -> str:
whole = round(seconds)
return f"{whole // 60} min {whole % 60} s" if whole >= 60 else f"{whole} s"