153 lines
7.8 KiB
Python
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"
|