JSON report schema reference

mutineer run --format json emits a single JSON object (one line, newline-terminated) describing the whole run. It is the machine-readable contract for tooling — CI gates, dashboards, and AI coding agents.

Output is deterministic: arrays are sorted by (file, line, operator) regardless of --jobs worker finish order, so two runs of the same inputs produce byte-identical output.

Versioning contract

The top-level schema_version (a string, e.g. "1.2") follows these rules:

• Additive changes (new keys on existing objects, new top-level keys) bump the minor version (1.0 → 1.1). Existing keys keep their meaning. Consumers MUST ignore unknown keys.
• Breaking changes (renaming/removing a key, changing a value's type or meaning) bump the major version (1.x → 2.0).

Top-level shape

{
  "schema_version": "1.2",
  "summary":      { /* run totals, see below */ },
  "survivors":    [ /* mutants the suite failed to catch — the actionable gaps */ ],
  "no_coverage":  [ /* mutants on lines no test exercises */ ],
  "uncapturable": [ /* mutants whose would-be test errored during coverage capture */ ],
  "no_verdict":   [ /* attempted mutants that produced no verdict: errored, timeout, uncapturable */ ],
  "ignored":      [ /* mutants the user suppressed (equivalent mutants) */ ],
  "per_source":   [ /* per-file roll-up */ ],
  "baseline":     { /* present ONLY with --baseline: the delta vs a prior run */ }
}

summary (object)

survivors[] (array of object)

Each surviving mutant — the records an agent or reviewer acts on:

no_coverage[] and uncapturable[] (array of object)

Both use the lean shape { subject, file, line }. no_coverage is a genuine coverage gap; uncapturable means the test that should cover the line errored while capturing coverage (fix the harness, not the test).

no_verdict[] (array of object)

Every mutant that was attempted and produced no verdict: { subject, file, line, id, status, details }. status is "error", "timeout" or "uncapturable", and its length equals summary.no_verdict. details carries the cause for "error"; it is null for the other two, where the status is the whole story.

A failure before the mutant could be forked has no subject, so subject, file, line and id are null on that entry — id is therefore not a reliable join key here, unlike in survivors[]. These mutants are excluded from the score's denominator, so a broken harness raises the score rather than lowering it; that is why --threshold gates on completeness as well.

ignored[] (array of object)

Suppressed (equivalent) mutants, so you can audit what's silenced: { subject, file, line, operator, token, id }.

per_source[] (array of object)

Per-file roll-up: { file, total, killed, survived, no_coverage, score } (score is float | null as above).

baseline (object, only with --baseline)

The delta versus the prior --format json report, matched by stable id:

Exit codes

--threshold and --baseline are independent gates OR'd together (the worse code wins); usage errors (2) always win. This lets a pipeline distinguish "tests too weak" (1) from "you invoked me wrong" (2).