mutineer 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ca70f2affdf60ddda53d3d38e23ddff4ba6cae27cd789501c7fe3060975f146
-  data.tar.gz: 94a9968fe182655e6d566e9edfc43f1f2e15b050c7690f8905e7be9f7d710b61
+  metadata.gz: e7b8a623ac7db818d33df11a7ca32e26a67db7f156061027f018debeb17ced2f
+  data.tar.gz: 5957fb6e57cb5a5149822818f773f3e8d3da271bce7bb0cfc4d0a8640764aa40
 SHA512:
-  metadata.gz: 8da96d70db7af241cda4ca44ecbe84522b0c0b68427a46c05e3178723c2eada7d957677c8b2cc7d2853d9593cba546c194f342862058dffdba55d03e8ef27021
-  data.tar.gz: 50481e9ca34d07530878f6ff0f25f192ab63c3200376a1a1ea5665341955a00c6bf2f9e7a4429d6cd8fd8d2119c4316c4c993741f219897f57ab493ca6c428b1
+  metadata.gz: 1de2a131774b7b587abbc8ca91a57da333688cb2fdb937defa002d661426137decf8b86fbde1a2d176a5525f8cb7d9a8b6a2bebc353960729704b3e8d2473213
+  data.tar.gz: '094d062c4c8458fda7061a575681f13022131b2b9078e5731bcbbfa300ac67b86e53691e4d9e104cc06e50832b66bd3dd32433c1bdf420e74b75a7b7748b4916'

data/CHANGELOG.md

@@ -6,6 +6,119 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-09-29
+
+### Changed
+- **Mutant ids now include the project-relative file path** (#126). Before, two
+  mutants with the same method name, operator and token in different files got
+  the same id. That happened with a top-level `def` or block in two files, and
+  with a class reopened in another file. One `ignore:` entry then suppressed
+  both mutants, and `--baseline` could hide a new survivor behind an old one.
+  - Every survivor id changes once in this release. This affects any external
+    tool that tracks survivors by id.
+  - Moving or renaming a file now changes its ids.
+  - Ids follow the project root: the directory mutineer runs from, or the
+    Action's `working-directory`. A run from a different root gives different ids.
+    mutineer finds `.mutineer.yml` by walking up, so a run from a subdirectory
+    prints one `[mutineer]` warning that the loaded ignore ids will not match.
+  - A source outside the project root uses its absolute path, so its ids differ
+    between machines.
+  - Two methods with the same qualified name in one file (for example two
+    top-level `def index` in two DSL blocks) now get different ids. The second
+    and later ones hash their position among those methods; the first keeps its
+    id.
+- **The JSON report marks its id format** (schema `1.4`, additive).
+  `summary.id_format` is `2` for ids that include the file path.
+  `summary.legacy_id_matches` counts old-format `ignore:` entries (`ignore`) and
+  survivors matched only through an old-format baseline id (`baseline`). The
+  GitHub Action shows one warning annotation when either count is not zero.
+
+### Deprecated
+- **Old-format ids in `ignore:` and in baselines.** Matching on them is removed
+  in 2.0. Replace each old `ignore:` entry with the new ids from the warning
+  (only the intended ones when it over-matched several mutants).
+  Regenerate a baseline (`--format json`) only after every gate that reads it
+  runs this version or later (the Action's `version:` pin, your CI
+  `Gemfile.lock`). An older version treats every new-format survivor as new.
+
+### Fixed
+- **`module_function :name` and `module_function def name` promote only
+  their own module's methods** — a class or module in the same file with a
+  method of the same name kept an instance method in Ruby, but mutineer
+  named it as a class method. `--strategy redefine` then mutated a method the
+  tests never call, so a killable mutant falsely survived, and
+  `--only Class#name` selected nothing (#98). The affected methods now get
+  their correct names, so their mutant ids change: regenerate any ignore
+  entries or baseline survivors that pointed at them.
+- **A root-anchored reopening names the top-level constant** — a
+  `module ::Root` or `class ::Solo` written inside another module now gives
+  `Root` and `Solo`, not `Outer::Root` and `Outer::Solo`. This applies to every
+  method in such a body, with or without `module_function`, so their mutant
+  ids change too. `--strategy redefine` rebuilds such a body's scope as
+  written (`module Outer` then `class ::Solo`), so a constant from `Outer`
+  still resolves in the mutated method, as it does under `reload`. Before,
+  the method raised NameError in the test, which counted as a false kill
+  (#145).
+- **Old-format ids keep working, with a warning** (#126). An old-format
+  `ignore:` entry still suppresses the mutants it matched before. The run prints
+  one `[mutineer]` warning per entry with each new id, its file and its method.
+  When the entry matched several mutants (in different files, or same-named
+  methods in one file), the warning says it
+  over-matched and to keep only the ids for the mutant you meant to ignore. A
+  `--baseline` file without `summary.id_format` matches on new ids, or on old
+  ids from the same file, so no survivor reads as new or fixed only because its
+  id changed. A stored file outside the project root (a baseline written on
+  another machine) matches on the old id alone. The run prints one
+  `[mutineer]` warning to regenerate the baseline.
+
+## [1.2.0] - 2026-09-28
+
+### Added
+- **Operand-removal operator** (Tier-2, opt-in via `--operators`):
+  `operand_removal` replaces `a && b` with `(a)` and with `(b)`, and does the
+  same for `||`, `and` and `or`. The mutant survives when no test needs the
+  operand that the mutant removes. The operator never keeps a jump operand
+  (`return`, `break`, `next`, `redo`, `retry`) alone, because a jump does not
+  parse in a value context. It never removes an operand that holds a heredoc,
+  because the heredoc body stays behind as code. It skips nested method
+  definitions, because mutineer mutates each one as its own method.
+- **Array-literal operator** (Tier-2, opt-in via `--operators`):
+  `array_literal` replaces a non-empty array literal, such as `[a, b]` or
+  `%i[a b]`, with `[]`. The mutant survives when no test checks the contents
+  of the array. The operator skips an implicit array (`x = 1, 2`), an array
+  that holds a heredoc, and nested method definitions.
+- **Sources also pair with Minitest's `test/**/test_*.rb` files** — after the
+  `_test.rb` forms, so existing projects pair as before. `lib/helper.rb` does
+  not pair with the `test/test_helper.rb` support file. A failed capture of a
+  `test_<name>.rb` file now marks `<name>.rb` uncapturable, as `<name>_test.rb`
+  does (#120). Without `framework:` set, a source with `spec/<name>_spec.rb`
+  and `test/test_<name>.rb` but no `<name>_test.rb` now pairs with the
+  Minitest file, as the "Minitest first" order says.
+
+### Fixed
+- **`reload` loads the mutant by an absolute path** — a relative source path
+  gave the mutant relative backtrace paths, so code that checks its own frames
+  by absolute path failed for every mutant, a false kill (#123).
+- **`require "test_helper"` works without `RUBYOPT`** — a standalone run puts
+  `lib`, then each test file's `test_helper.rb` directory, on the load path,
+  as boot mode and `rake test` do. A run where no test records coverage because
+  captures failed now exits 1 instead of reporting N/A (#119).
+- **A disable-line marker warns about an operator it does not know** — a
+  reason written without `--` became part of the operator name, so the marker
+  suppressed nothing and said nothing (#124). A marker followed only by spaces
+  or commas, such as `disable-line  -- why`, now disables the whole line.
+- **Coverage capture and the clean check run each source once** — they read
+  sources with `load`, so a test's own `require` ran them again: a `Struct`
+  superclass raised `superclass mismatch`, and load-time code ran twice (#122).
+  A mutant of such a class still errors under `--strategy reload`, which loads
+  the mutated file again; `--strategy redefine` runs it.
+  Code that guards itself to run once (`unless defined?(X)`) can now show as
+  covered, so its mutants run where they were `no_coverage` before.
+- **A red unmutated suite now shows why it failed** — in a standalone run, the
+  Minitest summary or RSpec output of the failing test, with its failure
+  message, goes to stderr before the "not green" error. A passing run prints
+  nothing extra. Boot mode (`--rails`, `--boot`) is unchanged (#121).
+
 ## [1.1.0] - 2026-09-28
 
 ### Added
@@ -498,6 +611,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.3.0]: https://github.com/davidteren/mutineer/releases/tag/v1.3.0
+[1.2.0]: https://github.com/davidteren/mutineer/releases/tag/v1.2.0
 [1.1.0]: https://github.com/davidteren/mutineer/releases/tag/v1.1.0
 [1.0.2]: https://github.com/davidteren/mutineer/releases/tag/v1.0.2
 [1.0.1]: https://github.com/davidteren/mutineer/releases/tag/v1.0.1

data/README.md

@@ -84,7 +84,8 @@ Run `mutineer --list-operators` to see them. Default (Tier 1): `arithmetic`,
 `comparison`, `boolean_connector`, `boolean_literal`, `statement_removal`.
 Available but off by default (Tier 2, enable via `--operators`): `return_nil`,
 `literal_mutation`, `condition_negation`, `string_literal`, `regex`,
-`collection_method`, `safe_navigation`, `range`, `negation_removal`, `chain_link`.
+`collection_method`, `safe_navigation`, `range`, `negation_removal`, `chain_link`,
+`operand_removal`, `array_literal`.
 
 ## Rails apps
 
@@ -212,12 +213,60 @@ Tradeoffs — this path is correct but not free:
 Some mutants are equivalent (behaviour-identical) and survive forever — keeping a
 file off 100%. Suppress them so the score and `--threshold` gate stay meaningful:
 
-- **Inline:** `some_line # mutineer:disable-line` (or scope it: `# mutineer:disable-line comparison`).
-- **Config:** a `.mutineer.yml` `ignore:` list of stable mutant ids. Each survivor's
+- **Inline:** `some_line # mutineer:disable-line` (or scope it: `# mutineer:disable-line comparison`). Put a reason after `--`: `# mutineer:disable-line comparison -- the test checks only 20`.
+- **Config:** a `.mutineer.yml` `ignore:` list of mutant ids. Each survivor's
   `id` is printed in the JSON report, so copy it straight into `ignore:`.
 
 Suppressed mutants are excluded from the score (so 100% becomes reachable).
 
+## Mutant ids
+
+A mutant id is 12 hex characters. It hashes the file path (relative to the
+project root), the method's qualified name, the operator, the mutated code, and
+the mutant's position among identical mutants in that method. When one file has
+two methods with the same qualified name (for example two top-level `def index`
+in two DSL blocks), the second and later ones also hash their position among
+those methods, so their ids differ. The first one's id does not change. An edit
+outside the method does not change the id. Moving or renaming the file,
+renaming the method or its class, or adding an identical mutant earlier in the
+method does. Adding a method with the same name earlier in the same file also
+does.
+
+- The project root is the directory mutineer runs from (in the Action, the
+  `working-directory`). Run from the same root to get the same ids.
+- A source outside the project root uses its absolute path, so its ids differ
+  between machines.
+
+**Migrating from ids without the file path.** Before 1.3, ids did not include
+the file path, so two files could share an id (#126). Old-format ids keep
+working until 2.0, with a warning:
+
+- **`ignore:`** An old entry still suppresses its mutants. The run prints the
+  new ids for each old entry, each with its file and method. When it names one
+  mutant, replace the entry with that id. When it names several (in different
+  files, or same-named methods in one file), the old entry over-matched: it also
+  hid mutants you did not mean to ignore. The warning says so. Keep only the ids for the mutant you meant to
+  ignore, not all of them. The list covers only the sources and operators in
+  that run, so run over every source with every operator set you use (for
+  example your Tier-2 `--operators`) for the full list.
+- **`--baseline`** An old baseline still matches: a survivor matches a stored
+  one with the same old id in the same file. A stored file that is an absolute
+  path outside the project root (a baseline written on another machine)
+  matches on the old id alone. The run tells you to
+  regenerate it. Regenerate it with `--format json`, but only after every gate
+  that reads it runs 1.3 or later (the Action's `version:` pin, your CI
+  `Gemfile.lock`). An older version treats every new-format survivor as new.
+
+The JSON report's `summary.id_format` is `2` for the new format.
+`summary.legacy_id_matches.ignore` counts the old-format ignore entries a run
+matched, and `summary.legacy_id_matches.baseline` counts the survivors matched
+only through an old baseline id.
+
+Ids are relative to the directory you run mutineer from. mutineer finds
+`.mutineer.yml` by walking up. When the file it loads is in a parent directory
+(other than your home directory), it warns that the ignore ids will not match
+and tells you which directory to run from.
+
 ## CI gating
 
 Store a JSON run as a baseline, then fail the build only when a PR makes things
@@ -227,7 +276,7 @@ worse:
 mutineer run app/ --baseline .mutineer/baseline.json   # exit 1 on NEW survivors or a score drop
 ```
 
-`--baseline` reports which survivors are new (by stable id) and any score drop. It
+`--baseline` reports which survivors are new (by [mutant id](#mutant-ids)) and any score drop. It
 combines with `--threshold` (the worse of the two sets the exit code). Pass a
 directory (or several sources) to audit a whole layer in one boot — tests are
 auto-paired by convention and the report breaks down per source.
@@ -266,7 +315,7 @@ the format.
 
 ## For AI agents & pipelines
 
-Mutineer is built for programmatic use — versioned JSON, stable mutant ids,
+Mutineer is built for programmatic use — versioned JSON, [mutant ids](#mutant-ids) that survive unrelated edits,
 structured exit codes, and diff-scoped runs. See:
 
 - **AI agents & CI recipes** — the agent inner-loop and CI-gate recipes (and how

data/lib/mutineer/baseline.rb

@@ -1,18 +1,20 @@
 # frozen_string_literal: true
 
 require "json"
+require "set"
 require_relative "config" # for Mutineer::ConfigError
+require_relative "project_path"
 
 module Mutineer
   # CI baseline/delta gating. A baseline is a prior
   # `mutineer run --format json` document (no bespoke format to version).
-  # Diff the current run against it by the stable survivor id: a NEW survivor
+  # Diff the current run against it by survivor id: a NEW survivor
   # (id present now, absent in the baseline) OR a score drop is a regression the
   # CLI turns into exit 1. Pure data, stdlib `json` only, no fork, no Rails, so
   # it is testable in isolation from a canned JSON + a hand-built AggregateResult.
   class Baseline
     # The verdict of diffing a current run against the baseline.
-    #   new_survivors   - current Result objects whose stable id is absent from
+    #   new_survivors   - current Result objects whose id is absent from
     #                     the baseline (the regressions to name).
     #   fixed_survivors - baseline survivor hashes absent from the current run
     #                     (informational, never gates). Empty when either side
@@ -26,8 +28,18 @@ module Mutineer
     #                     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.
+    #   legacy_matches  - current survivors found in an old-format baseline
+    #                     (no `summary.id_format`) only through their old-format
+    #                     id (#126). Non-zero means the baseline should be
+    #                     regenerated; the CLI warns. Always 0 for a new-format
+    #                     baseline.
     Delta = Data.define(:new_survivors, :fixed_survivors,
-                        :score_before, :score_after, :score_drop, :score_comparable, :regressed)
+                        :score_before, :score_after, :score_drop, :score_comparable, :regressed,
+                        :legacy_matches) do
+      # @param legacy_matches [Integer] survivors matched only through an old-format id.
+      # @return [void]
+      def initialize(legacy_matches: 0, **) = super
+    end
 
     # 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,
@@ -73,35 +85,74 @@ module Mutineer
       # 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
+      # nil for a report written before ids included the file path (#126).
+      @id_format = doc.dig("summary", "id_format")
     end
 
-    # Diff a current AggregateResult against this baseline by stable survivor id.
+    # Diff a current AggregateResult against this baseline by 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
+    # regressions. A scoped diff keeps the new-survivor gate (ids compare
     # fine across scopes) and still reports both scores, but never sets
     # score_drop.
     #
+    # `id_map` maps each current new-format id to its old-format id (#126). A
+    # baseline without `summary.id_format` stores old-format ids, so a current
+    # survivor matches if its new OR old id is stored, and a stored id seen under
+    # either form is not fixed. Matches made only through the old id are counted
+    # on Delta#legacy_matches. The old id has no file path, so an old-id match
+    # must also come from the same file (the stored survivor's `file`, normalized
+    # against `project_root`): an equal old id from another file is a different
+    # mutant and stays new. A stored `file` that is absolute and outside
+    # `project_root` (a baseline written on another machine) can never equal a
+    # current file, so that survivor matches on its old id alone, as before #126.
+    #
     # @param aggregate [Mutineer::AggregateResult] current results.
     # @param epsilon [Float] score-drop tolerance.
     # @param scoped [Boolean] current run was diff-scoped (`--since`).
+    # @param id_map [Hash{String => String}] current new id => old-format id.
+    # @param project_root [String] root that survivor `file` paths resolve against.
     # @return [Mutineer::Baseline::Delta] delta summary.
-    def diff(aggregate, epsilon: 0.0, scoped: false)
+    def diff(aggregate, epsilon: 0.0, scoped: false, id_map: {}, project_root: Dir.pwd)
       current = aggregate.surviving_mutants
-      current_ids = current.map(&:id)
-      baseline_ids = @survivors.map { |h| h["id"] }
+      baseline_ids = @survivors.map { |h| h["id"] }.to_set
+      # A new-format baseline never matches on old ids.
+      legacy = @id_format.nil? ? id_map : {}
+      file_key = ->(path) { path && ProjectPath.relative(path, project_root) }
+      # [old id, file] for each stored survivor: an old id alone is ambiguous.
+      baseline_pairs = @survivors.map { |h| [h["id"], file_key.call(h["file"])] }.to_set
+      # Old ids stored with a file from another machine: matched on the id alone.
+      foreign = @survivors.select { |h| foreign_file?(h["file"], file_key) }.to_set
+      foreign_ids = foreign.map { |h| h["id"] }.to_set
+      legacy_pair = ->(r) { [legacy[r.id], file_key.call(r.subject&.file)] }
 
-      new_survivors = current.reject { |r| baseline_ids.include?(r.id) }
+      new_survivors = []
+      legacy_matches = 0
+      current.each do |r|
+        next if baseline_ids.include?(r.id)
+
+        if legacy[r.id] && (baseline_pairs.include?(legacy_pair.call(r)) || foreign_ids.include?(legacy[r.id]))
+          legacy_matches += 1
+        else
+          new_survivors << r
+        end
+      end
+      current_ids = current.map(&:id).to_set
+      current_pairs = current.select { |r| legacy[r.id] }.map { |r| legacy_pair.call(r) }.to_set
+      current_legacy_ids = current.filter_map { |r| legacy[r.id] }.to_set
       # 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"]) }
+                @survivors.reject do |h|
+                  current_ids.include?(h["id"]) || current_pairs.include?([h["id"], file_key.call(h["file"])]) ||
+                    (foreign.include?(h) && current_legacy_ids.include?(h["id"]))
+                end
               end
 
       current_score = aggregate.mutation_score
@@ -116,7 +167,19 @@ module Mutineer
       Delta.new(new_survivors: new_survivors, fixed_survivors: fixed,
                 score_before: @score, score_after: current_score,
                 score_drop: score_drop, score_comparable: comparable,
-                regressed: !new_survivors.empty? || score_drop)
+                regressed: !new_survivors.empty? || score_drop, legacy_matches: legacy_matches)
+    end
+
+    private
+
+    # True when a stored survivor's `file` is absolute and still absolute after
+    # normalizing against the project root, so it lies outside this checkout.
+    #
+    # @param file [String, nil] the stored survivor's `file`.
+    # @param file_key [Proc] normalizes a path against the project root.
+    # @return [Boolean] whether the file can never equal a current file.
+    def foreign_file?(file, file_key)
+      !file.nil? && File.absolute_path?(file) && File.absolute_path?(file_key.call(file))
     end
   end
 end

data/lib/mutineer/cli.rb

@@ -162,6 +162,7 @@ module Mutineer
 
       case argv.first
       when "run"
+        warn_config_root_mismatch(file_path, config.project_root) if file_path
         # A directory source expands to its **/*.rb files; literal files pass
         # through. Test inference (when --test is omitted) happens in validate!.
         config.sources = Pairing.expand_sources(argv[1..], project_root: config.project_root)
@@ -469,7 +470,8 @@ module Mutineer
         exit 2
       end
 
-      aggregate, source_map = Runner.execute(config)
+      aggregate, source_map, extras = Runner.execute(config)
+      warn_legacy_ignore_matches(extras[:legacy_ignore_matches])
       reporter = Reporter.new(aggregate, source_map)
 
       # Diff the current run against the baseline (preflighted above) by the
@@ -479,12 +481,18 @@ module Mutineer
       # 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?)
+                                                               scoped: !config.since.nil?,
+                                                               id_map: extras[:id_map],
+                                                               project_root: config.project_root)
               end
+      warn_legacy_baseline if delta&.legacy_matches&.positive?
 
+      # ignore counts old-format entries (one warning each), not the ids they matched.
+      legacy_id_matches = { ignore: extras[:legacy_ignore_matches].size,
+                            baseline: delta ? delta.legacy_matches : 0 }
       reporter.report(out: $stdout, err: $stderr, threshold: config.threshold,
                       format: config.format, output: config.output, baseline: delta,
-                      scoped: !config.since.nil?)
+                      scoped: !config.since.nil?, legacy_id_matches: legacy_id_matches)
 
       # 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
@@ -523,6 +531,64 @@ module Mutineer
         "enable with --operators <list>."
     end
 
+    # Warns once when the loaded .mutineer.yml sits outside the run directory
+    # (#126). Mutant ids hash each file's path relative to the run directory,
+    # but the config is found by walking up, so a run from a subdirectory loads
+    # the same ignore list while its ids no longer match. A config in the home
+    # directory is a personal default, not a project root, so it never warns.
+    #
+    # @param file_path [String] the .mutineer.yml that was loaded.
+    # @param project_root [String] the run directory ids are relative to.
+    # @return [void]
+    def self.warn_config_root_mismatch(file_path, project_root)
+      config_dir = ProjectPath.root_real(File.dirname(file_path))
+      return if config_dir == ProjectPath.root_real(project_root)
+      return if config_dir == ProjectPath.root_real(Dir.home)
+
+      warn "[mutineer] loaded #{file_path}, but mutant ids are relative to the run directory " \
+           "#{project_root}, not to #{config_dir}. Ignore ids and baselines written from " \
+           "#{config_dir} will not match this run. Run mutineer from #{config_dir}."
+    end
+
+    # Warns once per old-format `ignore:` entry (#126), naming each new id it
+    # matched with that mutant's file and subject. mutineer cannot tell a full
+    # run from a narrowed one, so the text always says the list covers only this
+    # run's mutants. An entry that matched more than one distinct mutant (in
+    # other files, or same-named methods in one file) over-matched: the old id
+    # could not tell them apart, so replacing it with every new id would keep
+    # suppressing the mutants it hid by accident.
+    #
+    # @param matches [Hash{String => Array<Hash{Symbol => String}>}] old-format
+    #   entry => one `{id:, file:, subject:}` hash per matched mutant.
+    # @return [void]
+    def self.warn_legacy_ignore_matches(matches)
+      matches.each do |old, hits|
+        listed = hits.map { |h| "#{h[:id]} (#{h[:file]}, #{h[:subject]})" }.join(", ")
+        advice = if hits.map { |h| h[:id] }.uniq.size > 1
+                   "#{old} over-matched: the old format could not tell these mutants apart. " \
+                     "Replace #{old} and keep only the ids for the mutant you meant to ignore, not all of them."
+                 else
+                   "Replace #{old} with the new ids in your ignore list."
+                 end
+        warn "[mutineer] ignore entry #{old} uses the old id format, which did not include the " \
+             "file path. It matched these new ids: #{listed}. This list covers only mutants in " \
+             "this run's sources and operators; a run over every source gives the complete " \
+             "replacement. #{advice}"
+      end
+    end
+
+    # Warns once that the --baseline file stores old-format ids (#126), so the
+    # diff fell back to matching on them. Called only when a survivor matched
+    # through an old id alone.
+    #
+    # @return [void]
+    def self.warn_legacy_baseline
+      warn "[mutineer] the baseline uses the old id format, which did not include the file " \
+           "path, so survivors were matched on their old ids and files. Regenerate the baseline " \
+           "(run with --format json and save the output), but only after every gate that reads " \
+           "it runs this mutineer version or later."
+    end
+
     # Runs dry-run mode. Reuses Runner.collect_jobs (+ filter_since) so the
     # candidate list cannot drift from a real run's job selection.
     #
@@ -530,7 +596,8 @@ module Mutineer
     # @return [void]
     def self.dry_run(config)
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
-      jobs, ignored_results, source_map = Runner.collect_jobs(config, operator_classes)
+      jobs, ignored_results, source_map, extras = Runner.collect_jobs(config, operator_classes)
+      warn_legacy_ignore_matches(extras[:legacy_ignore_matches])
       # Narrow jobs and ignored the same way so the summary matches the printed list.
       if config.since
         jobs = Runner.filter_since(jobs, source_map, config)

data/lib/mutineer/coverage_map.rb

@@ -9,6 +9,7 @@ require "set"
 require_relative "minitest_integration"
 require_relative "test_runners"
 require_relative "child_stdout"
+require_relative "project_path"
 
 module Mutineer
   # Maps `(source_file, line) -> [test_files]` so each mutant runs only against
@@ -96,7 +97,7 @@ module Mutineer
     # Is this source file's empty coverage the result of an *errored* capture
     # rather than a genuine coverage gap? True iff some capture failed this run
     # AND this file got zero coverage from any successful capture AND a failed
-    # test file maps to it by the standard _test/_spec naming convention. Derived
+    # test file maps to it by the _test/_spec/test_ naming convention. Derived
     # purely from already-persisted state (@map keys + @failed_test_files); no
     # rerun, no new cached field, no digest change.
     #
@@ -142,10 +143,17 @@ module Mutineer
       @map.keys.map { |k| k.rpartition(":").first }.to_set
     end
 
-    # Basenames of failed test files with a trailing _test/_spec (and .rb) stripped,
-    # i.e. the source basenames they would have covered by convention.
+    # Basenames of the sources that failed test files pair with by convention:
+    # a trailing _test/_spec is stripped first, as pairing tries that form first.
     def failed_test_targets
-      @failed_test_files.map { |t| File.basename(t, ".rb").sub(/_(test|spec)\z/, "") }.to_set
+      @failed_test_files.map do |t|
+        name = File.basename(t, ".rb")
+        case name
+        when /_(test|spec)\z/ then name.sub(/_(test|spec)\z/, "")
+        when "test_helper" then name # Minitest's support file pairs with no source
+        else name.delete_prefix("test_")
+        end
+      end.to_set
     end
 
     # Shared cache dance for both build paths: hit the digest-keyed cache, else
@@ -577,11 +585,17 @@ module Mutineer
       loads = Array(test_paths).map { |t| "load #{absolute(t).inspect}" }.join("\n")
       <<~RUBY
         require "minitest"
+        require "stringio"
         def Minitest.autorun; end
+        _report = StringIO.new
+        Minitest.define_singleton_method(:plugin_mutineer_report_init) { |options| reporter << Minitest::SummaryReporter.new(_report, options) }
+        Minitest.extensions << "mutineer_report"
         $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
-        #{abs_source_paths.inspect}.each { |f| load f }
+        #{abs_source_paths.inspect}.each { |f| require f }
         #{loads}
-        exit(Minitest.run([]) ? 0 : 1)
+        _passed = Minitest.run([])
+        $stderr.write(_report.string) unless _passed
+        exit(_passed ? 0 : 1)
       RUBY
     end
 
@@ -601,9 +615,10 @@ module Mutineer
         end
         RSpec::Core::Runner.disable_autorun!
         $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
-        #{abs_source_paths.inspect}.each { |f| load f }
+        #{abs_source_paths.inspect}.each { |f| require f }
         _sink = StringIO.new
         status = RSpec::Core::Runner.run(["--no-color", #{specs}], _sink, _sink)
+        $stderr.write(_sink.string) unless status.zero?
         exit(status.zero? ? 0 : 1)
       RUBY
     end
@@ -628,12 +643,17 @@ module Mutineer
         require "coverage"
         require "json"
         require "minitest"
+        require "stringio"
         def Minitest.autorun; end
+        _report = StringIO.new
+        Minitest.define_singleton_method(:plugin_mutineer_report_init) { |options| reporter << Minitest::SummaryReporter.new(_report, options) }
+        Minitest.extensions << "mutineer_report"
         Coverage.start(lines: true)
         $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
-        #{abs_source_paths.inspect}.each { |f| load f }
+        #{abs_source_paths.inspect}.each { |f| require f }
         load #{absolute(test_path).inspect}
         _passed = Minitest.run([])
+        $stderr.write(_report.string) unless _passed
         _result.puts JSON.generate("passed" => _passed == true, "coverage" => Coverage.result,
                                     "loaded_files" => #{loaded_files_expression})
         _result.close
@@ -641,7 +661,7 @@ module Mutineer
     end
 
     # Same coverage-JSON contract as the minitest path, but driven by RSpec:
-    # require rspec/core lazily, load the sources under Coverage, then run the
+    # require rspec/core lazily, require the sources under Coverage, then run the
     # one spec via RSpec::Core::Runner. The JSON goes to the result channel (see
     # {#spawn_script}), so spec output cannot corrupt it. A missing rspec makes
     # the script exit non-zero -> capture() records a skipped (incomplete-map)
@@ -661,9 +681,10 @@ module Mutineer
         RSpec::Core::Runner.disable_autorun!
         Coverage.start(lines: true)
         $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
-        #{abs_source_paths.inspect}.each { |f| load f }
+        #{abs_source_paths.inspect}.each { |f| require f }
         _sink = StringIO.new
         _status = RSpec::Core::Runner.run(["--no-color", #{absolute(test_path).inspect}], _sink, _sink)
+        $stderr.write(_sink.string) unless _status.zero?
         _result.puts JSON.generate("passed" => _status.zero?, "coverage" => Coverage.result,
                                     "loaded_files" => #{loaded_files_expression})
         _result.close
@@ -702,11 +723,7 @@ module Mutineer
     #
     # @api private
     # @return [String] realpath of the project root when it exists.
-    def project_root_real
-      File.realpath(File.expand_path(@project_root))
-    rescue Errno::ENOENT
-      File.expand_path(@project_root)
-    end
+    def project_root_real = ProjectPath.root_real(@project_root)
 
     # Project-local `.rb` files loaded in this process at capture time.
     #
@@ -887,38 +904,18 @@ module Mutineer
     # @return [Array<String>] absolute load paths.
     def abs_load_paths   = @load_paths.map { |p| absolute(p) }
 
-    # Relativizes a path against the project root.
+    # Relativizes a path against the project root (see {ProjectPath.relative}).
     #
     # @api private
     # @param path [String] path to relativize.
-    # @return [String] relative path.
-    def relativize(path)
-      abs = path.start_with?("/") ? path : absolute(path)
-      abs = realpath_if_exists(abs)
-      root = project_root_real
-      prefix = root.end_with?("/") ? root : "#{root}/"
-      return abs unless abs.start_with?(prefix)
+    # @return [String] relative path, or an absolute path when outside the root.
+    def relativize(path) = ProjectPath.relative(path, @project_root)
 
-      abs.delete_prefix(prefix)
-    end
-
-    # Expands a path relative to the project root.
+    # Expands a path relative to the project root (see {ProjectPath.absolute}).
     #
     # @api private
     # @param path [String] path to expand.
     # @return [String] absolute path.
-    def absolute(path)
-      raw = File.absolute_path?(path) ? path : File.expand_path(path, @project_root)
-      realpath_if_exists(raw)
-    end
-
-    # Real path when the file exists, otherwise `path` unchanged.
-    #
-    # @api private
-    # @param path [String] absolute or relative path.
-    # @return [String]
-    def realpath_if_exists(path)
-      File.exist?(path) ? File.realpath(path) : path
-    end
+    def absolute(path) = ProjectPath.absolute(path, @project_root)
   end
 end