mutineer 0.11.4 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85591c1b61bcdc3c8a1d39b5b657f667bf7de9039d61e05ab3e5691692f555f0
-  data.tar.gz: 76acdc054e82d9ea10dee4a63bcbb5f0f86db37dd585323f734991f413f21e61
+  metadata.gz: a96e7bad1e1cf8d106957e770418e6a1854c677943114b9bc45421c4e06da7f2
+  data.tar.gz: c404d87071f3d270566e368ac70153f1e87c940eb170b220b972fb1b28b29889
 SHA512:
-  metadata.gz: b5855d2e0a9d4e226fe0ad2034cc4d08f4b5ac5e2d34df9e92f97b9d344ea5a50c4df01bbdcb0973dc66e8ccde717baab8842935fa07a4cad1238f77b9bebf42
-  data.tar.gz: 3a5c57795de651128a3d3597b2f1776fd32ff76aeaea4edf14037a1ec32e13e72e54c38a56ef8c209f3ee1d6afc0ffbb5fd47153967803c841e64d989d80a047
+  metadata.gz: 15417ab5322c43c537953eaa438c18a9a89794f199a9c4666f031daf60f55f6c3ffabcb2e69e15b7ffd030e48b6f2d5d3ab41ee01ccfe9d52dd6c9ee22b4971c
+  data.tar.gz: 1e68e920b3aa610ea1715c16e48e89060e8eba2b2511aafb3c7db0c44e21f8fac077529173befd9acf3afbe2962829cf4534dce371a2f6262628dd507f37469b

data/CHANGELOG.md

@@ -6,6 +6,95 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-09-18
+
+### Added
+- **RubyGems `documentation_uri`**: the published gem now points at the docs
+  site (`https://davidteren.github.io/mutineer/`) so gem-page discovery
+  reaches the Pages docs (#90).
+
+### Fixed
+- **A red unmutated suite can no longer pass a mutation gate** — coverage
+  capture now keeps the original Minitest/RSpec result, and a failing clean run
+  aborts with the existing smoke-check error (exit 1) instead of scoring those
+  assertion failures as killed mutants. A warm coverage cache re-checks the
+  current suite and cannot bypass this (#96).
+- **Concurrent external runs no longer restore each other's source files** —
+  swap and orphan recovery share one exclusive OS lock per source, acquired
+  before reading or healing. A live owner's mutant and backup stay intact; a
+  dead owner's backup still restores the original bytes (#99).
+- **Coverage cache now invalidates when a required test helper changes** —
+  a successful map records fingerprints of project-local loaded Ruby files,
+  old cache entries without that data rebuild, and a helper-only edit no
+  longer hides a new survivor behind a stale 100% score (#97).
+- **Release version calculation ignores floating major tags** — `release-pr.yml`
+  selects the newest complete `vMAJOR.MINOR.PATCH` ancestor and validates the
+  next version before writing files, so a later `v1` tag can no longer produce
+  `v1..1` (#95).
+
+## [1.0.0] - 2026-09-08
+
+The GitHub Action's PR default changes in this release, which is why it is a
+new major: workflows pinned to `davidteren/mutineer@v0` keep the old full-scan
+behavior; upgrading to `@v1` opts into diff-scoped PR runs (details under
+Changed).
+
+### Added
+- **The Action reports where CI readers look**: with the default JSON format it
+  writes a score/pass-fail table (plus the baseline delta, when `baseline` is
+  set) to the job step summary, and emits one `file=…,line=…` annotation per
+  surviving mutant (up to 50; the summary lists the first 20, the full set
+  stays in the JSON report) so results land on the PR diff instead of only in a
+  collapsed log group — `error` level when the gate failed, `warning` when it
+  passed. When `output` is unset the JSON report is routed to a temp file and
+  still printed to the log, and the `report` output now exposes the report
+  path in both cases so a later step can consume the JSON without scraping
+  the log (#86).
+- **Progress during the run**: every backend prints `[mutineer] N/M mutants
+  (P%)` to stderr at each 10% step, so a long run is never silent between
+  config resolution and the report. Stdout stays byte-exact for `--format json`
+  and `--output`. `WorkerPool#run` gains an optional `on_result:` callback for
+  this (called in the parent per reaped result) (#86).
+
+### Changed
+- **PR runs scope themselves in the GitHub Action**: on `pull_request` events
+  the `since` input now defaults to the PR base, so the action grades just the
+  diff out of the box. **Migration note (the reason for the major bump)**: a
+  PR gate that previously full-scanned now scores only the PR's changed lines,
+  so `threshold` applies to fewer mutants. Stay on `@v0` to keep the old
+  default, or pass `since: none` on `@v1` for full scans. Workflows that
+  already pass a non-empty `since` are unchanged (an explicit empty string is
+  indistinguishable from unset and picks up the new default). A PR with no
+  changed source lines (docs- or test-only) scores zero mutants and passes the
+  scoped gate vacuously; keep a full-scan baseline refresh on main as the
+  backstop. With `use-bundler: true` the caller's Gemfile picks the gem, and
+  the new default needs mutineer >= 1.0.0 (the action enforces the floor with
+  a clear error). The action scopes to the PR's exact base commit from the
+  event payload (immune to the
+  base branch advancing mid-job), falling back to a fresh fetch of the base
+  branch tip; when neither can be resolved it warns and runs without an
+  action-provided `--since` (a `.mutineer.yml` `since:` key, if any, still
+  applies). The default deliberately does NOT fire on `pull_request_target`:
+  checkout there defaults to the base branch, so auto-scoping would diff the
+  base against itself and green the gate on an empty run (#86).
+- **`--baseline` on a diff-scoped run gates on new survivors only**: a
+  `--since` run's score covers only the changed-line mutants, a different
+  denominator from a full-run baseline, so comparing the two scores
+  manufactured false regressions (a 3/4-mutant PR at 75% "dropped" from a
+  92% whole-repo baseline with zero new survivors). With `--since`, the
+  score-drop half of the baseline gate is skipped; new-survivor detection by
+  stable id (and the reported before/after scores) are unchanged. The JSON
+  report records the scope in a new additive `summary.scoped` key
+  (`schema_version` 1.3), and the `baseline` block records `score_comparable`
+  so a consumer knows when not to render the two scores as a comparison
+  (`fixed_survivors` is likewise empty under a scoped side: an out-of-scope
+  survivor was never re-tested, so absence does not mean fixed). The reverse
+  direction is a hard guard: a scoped report is refused as a baseline (exit 2
+  with a regenerate hint), because survivors outside its diff would all read
+  as new regressions. A new `--no-since` flag disables diff scoping explicitly: a
+  typed no beats a `.mutineer.yml` `since:` key, and the action's
+  `since: none` passes it through (#86).
+
 ## [0.11.4] - 2026-07-29
 
 ### Fixed
@@ -318,6 +407,8 @@ Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[1.0.1]: https://github.com/davidteren/mutineer/releases/tag/v1.0.1
+[1.0.0]: https://github.com/davidteren/mutineer/releases/tag/v1.0.0
 [0.11.4]: https://github.com/davidteren/mutineer/releases/tag/v0.11.4
 [0.11.3]: https://github.com/davidteren/mutineer/releases/tag/v0.11.3
 [0.11.2]: https://github.com/davidteren/mutineer/releases/tag/v0.11.2

data/README.md

@@ -51,7 +51,8 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 | `--only NAME` | Restrict to one fully-qualified subject, e.g. `Calculator#add` |
 | `--framework NAME` | `minitest` (default) or `rspec`; auto-detected as rspec when most `--test` files end in `_spec.rb` |
 | `--since REF` | Only mutate lines changed since git `REF` (e.g. `origin/main`) — ideal for PR CI |
-| `--baseline FILE` | Compare against a prior `--format json` run; exit 1 on new survivors / score drop (see [CI](#ci-gating)) |
+| `--no-since` | Disable diff scoping; a typed no beats a `.mutineer.yml` `since:` key |
+| `--baseline FILE` | Compare against a prior `--format json` run; exit 1 on new survivors / score drop (score drop is skipped under `--since`, whose score covers a different denominator; see [CI](#ci-gating)) |
 | `--baseline-epsilon FLOAT` | Score-drop tolerance for `--baseline` (default: 0) |
 | `--jobs N` | Parallel worker count (default: processor count; `1` under `--rails`) |
 | `--verbose` | Surface the real error when a fork capture fails (alias `--debug`) |
@@ -233,17 +234,32 @@ This repo ships a composite action (`action.yml`) that wraps the CLI for CI:
 
 ```yaml
 - uses: actions/checkout@v4
-  with: { fetch-depth: 0 }        # --since needs full history
 - uses: ruby/setup-ruby@v1
   with: { ruby-version: "3.4", bundler-cache: true }
-- uses: davidteren/mutineer@v0
+- uses: davidteren/mutineer@v1
   with:
     sources: app/
-    since: origin/${{ github.base_ref }}
     baseline: .mutineer/baseline.json
     threshold: "90"
 ```
 
+**Default change:** on `pull_request` events (not `pull_request_target`) the
+action scopes the run to the PR's changed lines, diffing against the PR's exact
+base commit (fetched by the action itself when the checkout is shallow; falls
+back to the base branch tip). Pass `since: none` for a full scan, or an
+explicit `since:` ref (which needs `fetch-depth: 0` on checkout).
+
+With the default JSON format the action also:
+
+- writes a score summary to the job's step summary;
+- annotates surviving mutants on the PR diff, up to 50 (`error` level when the
+  gate failed, `warning` when it passed);
+- exposes the report path via the `report` output for later steps (with
+  `format: human`/`html` this needs the `output` input).
+
+The CLI prints a progress line to the log at every 10% of the run, whatever
+the format.
+
 ## For AI agents & pipelines
 
 Mutineer is built for programmatic use — versioned JSON, stable mutant ids,

data/lib/mutineer/baseline.rb

@@ -15,12 +15,19 @@ module Mutineer
     #   new_survivors   - current Result objects whose stable id is absent from
     #                     the baseline (the regressions to name).
     #   fixed_survivors - baseline survivor hashes absent from the current run
-    #                     (informational, never gates).
+    #                     (informational, never gates). Empty when either side
+    #                     is diff-scoped: an out-of-scope baseline survivor was
+    #                     never re-tested, so absence does not mean fixed.
     #   score_drop      - current score < baseline score - epsilon. nil on
-    #                     either side skips the check (see #diff).
+    #                     either side skips the check, and a diff-scoped run
+    #                     (`scoped: true`) never sets it (see #diff).
+    #   score_comparable - the two scores share a denominator (neither side was
+    #                     diff-scoped and both are non-nil), so a consumer may
+    #                     render them side by side. False means the score-drop
+    #                     check was skipped, not that it passed.
     #   regressed       - any new survivors OR a score drop.
     Delta = Data.define(:new_survivors, :fixed_survivors,
-                        :score_before, :score_after, :score_drop, :regressed)
+                        :score_before, :score_after, :score_drop, :score_comparable, :regressed)
 
     # Load a prior --format json run. Raises ConfigError (NOT exit: a data class
     # must never kill the host) on a missing/unreadable file, unparseable JSON,
@@ -35,6 +42,15 @@ module Mutineer
       unless doc.is_a?(Hash) && doc["schema_version"] && doc["survivors"].is_a?(Array)
         raise ConfigError, "not a Mutineer JSON report: #{path}"
       end
+      # A diff-scoped report covers only that diff's mutants: used as a
+      # baseline, every survivor outside the original diff would read as a NEW
+      # regression, and its score shares no denominator with any other run.
+      # Refuse loudly (exit 2 via the CLI) rather than gate unreliably.
+      if doc.dig("summary", "scoped") == true
+        raise ConfigError, "#{path} was written by a --since run and covers only that diff's " \
+                           "mutants; regenerate the baseline from a full run " \
+                           "(use --no-since if .mutineer.yml sets since:)"
+      end
 
       new(doc)
     rescue JSON::ParserError => e
@@ -45,39 +61,61 @@ module Mutineer
 
     # Builds a baseline from a JSON document.
     #
-    # The baseline retains the survivor document and score from the JSON report.
+    # The baseline retains the survivor document, score, and scope marker from
+    # the JSON report. A report whose `summary.scoped` is true came from a
+    # `--since` run: its score covers only changed-line mutants, so later diffs
+    # must not compare a full-run score against it.
     #
     # @param doc [Hash] parsed JSON document.
     def initialize(doc)
       @survivors = doc["survivors"] || []
       @score = doc.dig("summary", "score")
+      # Strict literal true only: a malformed value (say the STRING "false" in a
+      # hand-edited baseline) must not silently disable the score-drop gate.
+      @scoped = doc.dig("summary", "scoped") == true
     end
 
     # Diff a current AggregateResult against this baseline by stable survivor id.
     # `epsilon` tolerates float jitter on the score (default 0.0 = any drop
     # gates).
     #
+    # `scoped: true` marks the current run as diff-scoped (`--since`): its score
+    # is computed over only the changed-line mutants, a different denominator
+    # from a full-run baseline, so comparing the two scores manufactures false
+    # regressions. A scoped diff keeps the new-survivor gate (stable ids compare
+    # fine across scopes) and still reports both scores, but never sets
+    # score_drop.
+    #
     # @param aggregate [Mutineer::AggregateResult] current results.
     # @param epsilon [Float] score-drop tolerance.
+    # @param scoped [Boolean] current run was diff-scoped (`--since`).
     # @return [Mutineer::Baseline::Delta] delta summary.
-    def diff(aggregate, epsilon: 0.0)
+    def diff(aggregate, epsilon: 0.0, scoped: false)
       current = aggregate.surviving_mutants
       current_ids = current.map(&:id)
       baseline_ids = @survivors.map { |h| h["id"] }
 
       new_survivors = current.reject { |r| baseline_ids.include?(r.id) }
-      fixed = @survivors.reject { |h| current_ids.include?(h["id"]) }
+      # Under a diff-scoped side an out-of-scope baseline survivor was never
+      # re-tested, so reporting it "fixed" would be false: empty is honest.
+      fixed = if scoped || @scoped
+                []
+              else
+                @survivors.reject { |h| current_ids.include?(h["id"]) }
+              end
 
       current_score = aggregate.mutation_score
       # nil-score discipline (mirrors Reporter#exit_code): a score absent on
       # either side cannot be compared. Skip the drop check, keep the new-
-      # survivor check.
-      score_drop = !@score.nil? && !current_score.nil? &&
-                   current_score < @score - epsilon
+      # survivor check. Same when EITHER side is diff-scoped (the current run
+      # via `scoped:`, or the stored baseline via its `summary.scoped` marker):
+      # the denominators differ, so the scores are not comparable.
+      comparable = !scoped && !@scoped && !@score.nil? && !current_score.nil?
+      score_drop = comparable && current_score < @score - epsilon
 
       Delta.new(new_survivors: new_survivors, fixed_survivors: fixed,
                 score_before: @score, score_after: current_score,
-                score_drop: score_drop,
+                score_drop: score_drop, score_comparable: comparable,
                 regressed: !new_survivors.empty? || score_drop)
     end
   end

data/lib/mutineer/changed_lines.rb

@@ -57,16 +57,24 @@ module Mutineer
 
     # Returns the stdout of `git -C <root> diff --unified=0 <ref> -- <file>`.
     #
+    # A failure is warned, never silent: an empty result means "no changed
+    # lines", which under `--since` removes every mutant for the file — a green
+    # gate must not be manufactured by a broken diff without a trace.
+    #
     # @param ref [String] git ref to diff against.
     # @param abs_file [String] absolute path of the file being diffed.
     # @param project_root [String] repository root for `git -C`.
-    # @return [String] diff text, or `""` on failure.
+    # @return [String] diff text, or `""` on failure (after a stderr warning).
     def git_diff(ref, abs_file, project_root)
       out, _err, status = Open3.capture3(
         "git", "-C", project_root, "diff", "--unified=0", ref, "--", abs_file
       )
-      status.success? ? out : ""
-    rescue StandardError
+      return out if status.success?
+
+      warn "[mutineer] git diff failed for #{abs_file}; its lines will not be mutated (--since)"
+      ""
+    rescue StandardError => e
+      warn "[mutineer] git diff failed for #{abs_file} (#{e.class}); its lines will not be mutated (--since)"
       ""
     end
   end

data/lib/mutineer/cli.rb

@@ -41,6 +41,7 @@ module Mutineer
         --baseline-epsilon FLOAT  Score-drop tolerance for --baseline (default: 0)
         --only NAME          Restrict to one fully-qualified subject
         --since REF          Only mutate lines changed since git REF (e.g. origin/main)
+        --no-since           Disable diff scoping (a typed no beats a .mutineer.yml since:)
         --jobs N             Parallel worker count (default: processor count)
         --strategy NAME      reload (whole-file) or redefine (surgical); default: reload
         --framework NAME     minitest or rspec (default: auto-detect from --test names)
@@ -96,6 +97,9 @@ module Mutineer
         o.on("--fail-fast") { opts[:fail_fast] = true; explicit << :fail_fast }
         o.on("--only NAME") { |v| opts[:only] = v; explicit << :only }
         o.on("--since REF") { |v| opts[:since] = v; explicit << :since }
+        # A typed "no" must beat a .mutineer.yml `since:` key (CLI-over-config
+        # precedence): marking :since explicit with a nil value blocks the fill.
+        o.on("--no-since") { opts[:since] = nil; explicit << :since }
         o.on("--test FILE") { |v| (opts[:tests] ||= []) << v }
         o.on("--operators LIST") { |v| opts[:operators] = v.split(",").map(&:strip); explicit << :operators }
         o.on("--threshold FLOAT") do |v|
@@ -214,6 +218,11 @@ module Mutineer
       # environment, not weak tests. Runtime error (exit 1), not usage (exit 2).
       warn "mutineer: #{e.message}"
       exit 1
+    rescue Mutineer::ConcurrentRunError => e
+      # Another process owns a source file. Runtime error (exit 1), not a
+      # backtrace: the working tree is still the other run's responsibility.
+      warn "mutineer: #{e.message}"
+      exit 1
     rescue Mutineer::DaemonBootError => e
       # The daemon is gone for good, so the run ended rather than scoring the rest
       # against it. A deliberate stop deserves a message, not a raw backtrace.
@@ -465,11 +474,17 @@ module Mutineer
 
       # Diff the current run against the baseline (preflighted above) by the
       # stable survivor id. The delta is rendered inline (human section / additive
-      # json block) and gates exit independently of --threshold.
-      delta = (Baseline.load(config.baseline).diff(aggregate, epsilon: config.baseline_epsilon) if config.baseline)
+      # json block) and gates exit independently of --threshold. A --since run is
+      # scoped: its score covers a different denominator than a full-run baseline,
+      # so only the new-survivor half of the gate applies (see Baseline#diff).
+      delta = if config.baseline
+                Baseline.load(config.baseline).diff(aggregate, epsilon: config.baseline_epsilon,
+                                                               scoped: !config.since.nil?)
+              end
 
       reporter.report(out: $stdout, err: $stderr, threshold: config.threshold,
-                      format: config.format, output: config.output, baseline: delta)
+                      format: config.format, output: config.output, baseline: delta,
+                      scoped: !config.since.nil?)
 
       # Warn (stderr, so it never pollutes json/html) that an external run's score
       # is not comparable to an in-process run: no coverage narrowing (uncovered

data/lib/mutineer/config.rb

@@ -182,6 +182,11 @@ module Mutineer
       when "ignore"    then Array(value).map(&:to_s)
       when "baseline"  then value.to_s
       when "test_command" then value.to_s
+      when "since"
+        # false / empty normalize to nil ("no scoping"), so every consumer's
+        # nil-check (runner scoping, the report's scoped marker) agrees. A
+        # false left raw would skip scoping but still mark the report scoped.
+        value == false || value.to_s.empty? ? nil : value.to_s
       else value
       end
     end