mutationdiff

Overview ¶

Command mutationdiff compares two mutation reports and names every new unsettled mutation.

`.github/workflows/mutation.yml` runs it on a schedule. Epic 15 (#89) owns the sweep, and #93 built this command. `docs/specs/features/15-mutation-sweep.md` holds FR-mutation-17 through FR-mutation-20.

The one defect this command exists to avoid ¶

**This command counts a verdict from the verdict of each mutation, and never from a total.** #91 measured the reason on 2026-08-14. `fileReport` at `internal/report/report.go:178` of `gremlins` v0.6.0 sets `mutants_total` to the sum of the lived, the killed and the not-viable mutations alone. It reported 716 where the swept path holds 882. **A detector that reads a total therefore misses every `TIMED OUT` mutation and every `NOT COVERED` mutation**, and a new `TIMED OUT` mutation would open no issue.

So this command reads the per-mutation rows of a report, and it reads no count row.

Two modes, and one baseline rule ¶

The workflow needs the swept path of the baseline before it sweeps, and it needs the comparison after. Each mode prints `key=value` lines, which a step appends to `$GITHUB_OUTPUT`.

mutationdiff -dir docs/mutation_reports
  baseline=docs/mutation_reports/2026-08-14-internal-parser.md
  swept-path=./internal/parser

mutationdiff -baseline <report> -current <report> -body <path>
  new-lived=3

**The current sweep reads the swept path of the baseline, and never a path this file names.** A sweep of a wider path would report every mutation of every package the baseline never measured as new.