mutate

Overview ¶

Command mutate breaks the conditional guards in a package one at a time and reports which ones no test notices.

A guard whose "never fires" mutant leaves the suite green is a guard nothing proves refuses anything. A guard whose "always fires" mutant leaves the suite green is a guard nothing proves permits anything, the shape that lets a too-tight gate ship. Both are reported as SURVIVED.

go run ./cmd/mutate ./sqlite/                       # whole package
go run ./cmd/mutate -file engine.go ./sqlite/       # one file
go run ./cmd/mutate -line 2520 -file engine.go ./sqlite/

Before any mutation the unmutated suite is run once: an already-red package would otherwise report every mutant as caught and exit 0 claiming perfect coverage. A mutant that fails to compile is reported as BROKEN, never as caught; a build failure prints its own `FAIL` line, so that classification has to be tested for explicitly rather than assumed. A mutation that does not change the file, or does not reach disk, is a hard error rather than any verdict at all.

It writes into real source files, so it holds a per-package lock (concurrent runs otherwise read each other's mutants as their baseline and can restore one as the original), bounds every test run with -timeout (an infinite-loop mutant would otherwise hang until killed), and restores every file on SIGINT/SIGTERM (a deferred restore does not run on a signal, and Ctrl-C on a slow run is the ordinary way this ends).

This is a developer tool and a targeted CI gate, not a blanket one: every mutant costs a full test run of the package.

Run on itself, this package reports survivors in main()'s own flag parsing, filtering, and output formatting. That is accurate and deliberate: those branches are exercised by using the tool, and covering them would mean spawning the binary from a test for no real gain. The logic that can lie, namely the verdict classification, the write-and-verify step, restore, and the mutation core in guardmut, is tested, and guardmut is mutation-clean. A clean run of `make mutate PKG=./cmd/mutate/guardmut/` is the claim being made; it is not a claim about the CLI wiring.