golens-mutant

README

golens-mutant

mutant is a Go CLI that orchestrates mutation testing — or any file-mutation-based test runner — across a workspace of libs and packages. It is completely agnostic to the underlying tool: every command it executes is defined as a template in a YAML config file.

It schedules work around your machine's live CPU and memory headroom, isolates every package in a cached sandbox, kills or retries runaway steps, persists per-file results as they complete, and can resume an interrupted session exactly where it stopped.

Install

go install github.com/GoLens-Project/golens-mutant/cmd/mutant@latest

Prebuilt binaries for linux/darwin/windows (amd64 + arm64) are attached to each release.

Quick start

# 1. Generate a fully documented example config
mutant --generate-config-example config.yaml

# 2. Edit it: point target_roots at your workspace, wire your mutation
#    tool into mutation.commands, map files to their tests.

# 3. Run
mutant --config config.yaml

The run prints a progress bar on stderr, notices for resource events (worker scale-down, package aborts), and a human-readable summary at the end:

Mutation run finished in 4m12s
  files:    128
  killed:   97
  survived: 22
  other:    4 timeout, 5 skipped
  mutation score: 81.5%
  libs/core                                  64 files, score 84.3%
  libs/ui                                    64 files, score 78.7%

How it works

1. Discovery — walks the configured target roots; every directory containing the package marker (pubspec.yaml by default) becomes a package, its files filtered through include/exclude globs and mapped to test selectors.
2. Resource guard — a monitor samples CPU (instant usage, or normalized load average) and free RAM. New work only starts while both are within your thresholds; work already in flight always finishes.
3. Scheduling — each work unit is one file mutation. Worker slots claim a package's sandbox exclusively, restore the target file pristine, run the command chain, classify the outcome, then observe a cooldown before taking more work. Ramp-up is gradual (or calculated), and sustained memory pressure scales worker capacity down — with recovery once resources free up.
4. Sandbox cache — the first slot to reach a package bootstraps it (source sync + your dependency command); later slots reuse the prepared copy.
5. Reports — every completed file is persisted immediately (JSON files, or SQLite) with raw command logs kept verbatim, so an interrupted run resumes with at most one file lost.

Command templates

Macros interpolated at execution time:

Macro	Expands to
{file}	package-relative path of the mutated file
{abs_file}	absolute path of the file inside its sandbox
{tests}	test selectors from the mutation.tests mapping
{target_dir}	absolute path of the package's sandbox
{package}	package name (e.g. libs/core)

Results are classified from the command outcome: ordered stdout/stderr regex rules first, then an exit-code map (single codes or ranges like "2-5"), defaulting to 0 → survived, anything else → killed. Timeouts and per-process memory-budget kills are classified automatically.

Resuming

Resume is on by default. Per-file results are written after every completed file; re-running the same config skips everything already recorded:

mutant --config config.yaml   # interrupted…
mutant --config config.yaml   # …picks up where it stopped

Disable with resume: {enabled: false}.

Development

make test        # full suite with the race detector
make cover       # coverage with a per-function report (coverage.txt)
make cover-html  # coverage as an HTML report in the browser
make ci          # fmt + vet + test, the same checks CI runs
make smoke       # build the CLI and run it against a toy workspace
make install     # go install ./cmd/mutant into GOBIN

Releases are automated: fix: commits bump the patch version, feat: commits the minor version, and feat!: / BREAKING CHANGE the major version, tagged and published by the release workflow on every push to master.