mutineer 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b48ca68bd77d82bd83917312fe4bc2377954403e0a63c99702c9059b9dde07b
-  data.tar.gz: 0c11eaa74d07db731902b2fe70313f71b17eded8a59f10e5652b86985c11641c
+  metadata.gz: e7b8a623ac7db818d33df11a7ca32e26a67db7f156061027f018debeb17ced2f
+  data.tar.gz: 5957fb6e57cb5a5149822818f773f3e8d3da271bce7bb0cfc4d0a8640764aa40
 SHA512:
-  metadata.gz: 23505720f25f34b80bde51fb0a900c16a40295966ec8bd14713d22eca03ea0058a69d83b3f701672adee6a20b10f342f09d8b561d974f2a8f23d12a82ba22e46
-  data.tar.gz: cb2b659574bf1454ef265e3723b2c906485589696316cb63d9fb81d7696e04867e9fec73ee36b8d67063c7d941f4165fd35c922cc47cbc19466ec839ff8cbc2c
+  metadata.gz: 1de2a131774b7b587abbc8ca91a57da333688cb2fdb937defa002d661426137decf8b86fbde1a2d176a5525f8cb7d9a8b6a2bebc353960729704b3e8d2473213
+  data.tar.gz: '094d062c4c8458fda7061a575681f13022131b2b9078e5731bcbbfa300ac67b86e53691e4d9e104cc06e50832b66bd3dd32433c1bdf420e74b75a7b7748b4916'

data/CHANGELOG.md

@@ -6,6 +6,71 @@ 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
@@ -546,6 +611,7 @@ 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

data/README.md

@@ -214,11 +214,59 @@ Some mutants are equivalent (behaviour-identical) and survive forever — keepin
 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`). Put a reason after `--`: `# mutineer:disable-line comparison -- the test checks only 20`.
-- **Config:** a `.mutineer.yml` `ignore:` list of stable mutant ids. Each survivor's
+- **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
@@ -228,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.
@@ -267,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
@@ -722,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.
     #
@@ -907,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)
-
-      abs.delete_prefix(prefix)
-    end
+    # @return [String] relative path, or an absolute path when outside the root.
+    def relativize(path) = ProjectPath.relative(path, @project_root)
 
-    # 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

data/lib/mutineer/daemon_backend.rb

@@ -43,9 +43,10 @@ module Mutineer
     #
     # @param config [Mutineer::Config] run configuration (daemon set).
     # @param operator_classes [Array<Class>] resolved operators.
-    # @return [Array(Mutineer::AggregateResult, Hash<String,String>)] aggregate and source map.
+    # @return [Array(Mutineer::AggregateResult, Hash<String,String>, Hash)] aggregate,
+    #   source map, and the {Runner.collect_jobs} extras.
     def self.execute(config, operator_classes)
-      jobs, ignored_results, source_map = Runner.collect_jobs(config, operator_classes)
+      jobs, ignored_results, source_map, extras = Runner.collect_jobs(config, operator_classes)
       jobs = Runner.filter_since(jobs, source_map, config) if config.since
       abs_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
 
@@ -58,7 +59,7 @@ module Mutineer
         # tool-side. A file a hard-killed run left in app/models breaks the app's own
         # Zeitwerk boot, not just Mutineer's next run.
         Runner.sweep_orphans(Runner.source_dirs(config), DAEMON_TEMP_GLOB)
-        return [AggregateResult.new(ignored_results), source_map]
+        return [AggregateResult.new(ignored_results), source_map, extras]
       end
 
       # Build the coverage map once (app-side). nil when the build fails: runners
@@ -84,7 +85,7 @@ module Mutineer
           run_serial(jobs, config, abs_tests, coverage_map, source_map)
         end
 
-      [AggregateResult.new(results + ignored_results), source_map]
+      [AggregateResult.new(results + ignored_results), source_map, extras]
     end
 
     # Build the coverage map via a short-lived daemon (boots the app once, captures

data/lib/mutineer/isolation.rb

@@ -132,7 +132,7 @@ module Mutineer
       # namespace constants resolve exactly as the reload strategy would. A
       # bare redefinition on the owner would collapse Module.nesting to [owner]
       # and raise NameError on such constants (C2 scope-collapse).
-      keywords = nesting_keywords(subject.namespace)
+      keywords = nesting_keywords(subject.lexical_namespace)
       prefix   = keywords.map { |kw, name| "#{kw} #{name}" }.join("\n")
       prefix  += "\n" unless prefix.empty?
 
@@ -188,13 +188,18 @@ module Mutineer
     # Foo], so an unqualified constant defined only in Foo would resolve under
     # redefine but not reload — a strategy disagreement.
     #
+    # A root-anchored element (`::Top`, #145) resolves from Object and keeps its
+    # `::` in the wrapper, so `module Outer; class ::Top` rebuilds nesting
+    # [Top, Outer] exactly as the source does.
+    #
     # @api private
-    # @param namespace [Array<String>] namespace components.
+    # @param namespace [Array<String>] class/module chain as written.
     # @return [Array<[String, String]>] wrapper keywords and names.
     def self.nesting_keywords(namespace)
       mod = Object
       namespace.map do |name|
-        mod = mod.const_get(name) # const_get resolves a compact "Foo::Bar" too
+        # const_get resolves a compact "Foo::Bar" too
+        mod = name.start_with?("::") ? Object.const_get(name.delete_prefix("::")) : mod.const_get(name)
         [mod.is_a?(Class) ? "class" : "module", name]
       end
     end

data/lib/mutineer/mutant_id.rb

@@ -3,16 +3,18 @@
 require "digest"
 
 module Mutineer
-  # Content-based stable id for a mutant — NOT byte offsets. Pure function, reused
+  # Content-based id for a mutant — NOT byte offsets. Pure function, reused
   # by the Runner (matching the ignore list), the Reporter (emitting a copy-
   # pasteable id per survivor), and #13 baseline gating (diffing id-sets run to
   # run). `digest` is stdlib, so zero new deps.
   #
-  # Offset-free by design: keyed on the subject's qualified_name (a method, not a
-  # byte position) + operator + the normalized mutated token + an occurrence
-  # ordinal among same-(operator, token) twins WITHIN the subject. So it survives
-  # any edit outside the subject method — where raw start/end offsets shift on
-  # every edit earlier in the file and would silently stop matching.
+  # Offset-free by design: keyed on the subject's project-relative file path +
+  # qualified_name (a method, not a byte position) + operator + the normalized
+  # mutated token + an occurrence ordinal among same-(operator, token) twins
+  # WITHIN the subject + (only when positive) the subject's ordinal among
+  # same-named subjects in its file. So it survives any edit outside the subject method,
+  # where raw start/end offsets shift on every edit earlier in the file and
+  # would silently stop matching. Moving or renaming the file changes the id.
   module MutantId
     module_function
 
@@ -20,6 +22,9 @@ module Mutineer
     #
     # NUL-joined so token delimiters (`||=`, spaces, `::`, `#`) can never collide
     # with the separator; `SHA256[0,12]` gives a fixed-length, copy-pasteable key.
+    # The file path is part of the key, so the same qualified name in two files
+    # (an owner-less `def`, or a class reopened elsewhere) cannot collide. `path`
+    # is required so no caller can get the colliding legacy id by accident.
     #
     # @param subject [Mutineer::Subject] the subject (method) the mutant lives in;
     #   its `qualified_name` anchors the id to a method rather than a byte position.
@@ -27,12 +32,17 @@ module Mutineer
     # @param source [String] the full, unmutated source the mutation indexes into.
     # @param occurrence [Integer] 0-based ordinal among twins sharing the same
     #   (operator, token) within the subject, disambiguating otherwise-identical mutants.
+    # @param path [String] the subject's file, normalized with {ProjectPath.relative}
+    #   against the project root (an absolute real path when outside the root).
+    # @param subject_ordinal [Integer] 0-based ordinal among subjects in the same
+    #   file sharing this qualified name (two owner-less `def index` in two DSL
+    #   blocks). Hashed only when positive, so a subject whose name is unique in
+    #   its file keeps the id it had without it.
     # @return [String] a 12-character hex id, stable across edits outside the subject.
-    def for(subject, mutation, source, occurrence = 0)
-      Digest::SHA256.hexdigest(
-        [subject.qualified_name, mutation.operator,
-         normalized_token(mutation, source), occurrence].join("\x00")
-      )[0, 12]
+    def for(subject, mutation, source, occurrence = 0, path:, subject_ordinal: 0)
+      parts = [path, subject.qualified_name, mutation.operator, normalized_token(mutation, source), occurrence]
+      parts << subject_ordinal if subject_ordinal.positive?
+      digest(parts)
     end
 
     # Computes ids for a subject's full mutation list, in input order, assigning
@@ -42,17 +52,66 @@ module Mutineer
     # @param subject [Mutineer::Subject] the subject the mutations belong to.
     # @param source [String] the full, unmutated source for token normalization.
     # @param mutations [Array<Mutineer::Mutation>] the subject's mutations, in order.
+    # @param path [String] the subject's normalized file path (see {.for}).
+    # @param subject_ordinal [Integer] the subject's ordinal among same-named
+    #   subjects in its file (see {.for}).
     # @return [Array<String>] one 12-character id per mutation, positionally aligned.
-    def for_subject(subject, source, mutations)
+    def for_subject(subject, source, mutations, path:, subject_ordinal: 0)
+      with_occurrences(mutations, source) do |m, occ|
+        self.for(subject, m, source, occ, path: path, subject_ordinal: subject_ordinal)
+      end
+    end
+
+    # The pre-1.3 id: the {.for} formula without the path, so it collides across
+    # files. Kept only to match ignore entries and baselines stored in the old
+    # format; removed in 2.0.
+    #
+    # @param subject [Mutineer::Subject] the subject (method) the mutant lives in.
+    # @param mutation [Mutineer::Mutation] the atomic edit whose operator is hashed.
+    # @param source [String] the full, unmutated source the mutation indexes into.
+    # @param occurrence [Integer] 0-based ordinal among same-(operator, token) twins.
+    # @return [String] a 12-character hex id in the old format.
+    def legacy_for(subject, mutation, source, occurrence = 0)
+      digest([subject.qualified_name, mutation.operator,
+              normalized_token(mutation, source), occurrence])
+    end
+
+    # {.for_subject} for the pre-1.3 id format (see {.legacy_for}).
+    #
+    # @param subject [Mutineer::Subject] the subject the mutations belong to.
+    # @param source [String] the full, unmutated source for token normalization.
+    # @param mutations [Array<Mutineer::Mutation>] the subject's mutations, in order.
+    # @return [Array<String>] one old-format id per mutation, positionally aligned.
+    def legacy_for_subject(subject, source, mutations)
+      with_occurrences(mutations, source) { |m, occ| legacy_for(subject, m, source, occ) }
+    end
+
+    # Maps each mutation to the block's result, passing its 0-based occurrence
+    # among earlier mutations with the same (operator, token).
+    #
+    # @param mutations [Array<Mutineer::Mutation>] the subject's mutations, in order.
+    # @param source [String] the full, unmutated source for token normalization.
+    # @yieldparam mutation [Mutineer::Mutation] the current mutation.
+    # @yieldparam occurrence [Integer] its ordinal among same-(operator, token) twins.
+    # @return [Array] the block's results, positionally aligned.
+    def with_occurrences(mutations, source)
       seen = Hash.new(0)
       mutations.map do |m|
         key = [m.operator, normalized_token(m, source)]
         occ = seen[key]
         seen[key] += 1
-        self.for(subject, m, source, occ)
+        yield m, occ
       end
     end
 
+    # NUL-joins the id parts and returns the first 12 hex chars of their SHA256.
+    #
+    # @param parts [Array] the values that make up the id.
+    # @return [String] a 12-character hex id.
+    def digest(parts)
+      Digest::SHA256.hexdigest(parts.join("\x00"))[0, 12]
+    end
+
     # Extracts the exact code being mutated, whitespace-collapsed — the same
     # normalization the Reporter's `diff_for` uses for its token label.
     #

data/lib/mutineer/project.rb

@@ -36,23 +36,26 @@ module Mutineer
       def initialize(file)
         @file = file
         @namespace_stack = []
+        @lexical_stack = [] # class/module names as written, `::X` kept (#145)
         @subjects = []
         @singleton_depth = 0
         @module_function_active = false # bareword `module_function` seen in this module body
-        @module_function_names = []     # names from `module_function :a, :b` / `module_function def`
+        @module_function_names = []     # [namespace, name] from `module_function :a` / `module_function def` (#98)
         super()
       end
 
       # Promote `module_function :name` / `module_function def name` subjects to
       # singleton after the full walk — the naming call may appear before or after
-      # the def, so it can't be decided at visit_def_node time (#20).
+      # the def, so it can't be decided at visit_def_node time (#20). Only methods
+      # of the module that made the call are promoted (#98); namespaces compare
+      # joined, since `module A::B` and nested `module A; module B` differ as arrays.
       #
       # @return [void]
       def promote_module_functions!
         return if @module_function_names.empty?
 
-        names = @module_function_names.to_set
-        @subjects.each { |s| s.singleton = true if names.include?(s.name) }
+        named = @module_function_names.to_set
+        @subjects.each { |s| s.singleton = true if named.include?([s.namespace.join("::"), s.name]) }
       end
 
       # Visits class nodes and tracks namespace nesting.
@@ -60,12 +63,7 @@ module Mutineer
       # @param node [Prism::ClassNode] class node.
       # @return [void]
       def visit_class_node(node)
-        @namespace_stack.push(extract_constant_name(node.constant_path))
-        saved = @module_function_active
-        @module_function_active = false # module_function state does not cross a class boundary
-        super
-        @module_function_active = saved
-        @namespace_stack.pop
+        with_namespace(node.constant_path) { super }
       end
 
       # Visits module nodes and tracks namespace nesting.
@@ -73,12 +71,7 @@ module Mutineer
       # @param node [Prism::ModuleNode] module node.
       # @return [void]
       def visit_module_node(node)
-        @namespace_stack.push(extract_constant_name(node.constant_path))
-        saved = @module_function_active
-        @module_function_active = false # each module body starts without module_function active
-        super
-        @module_function_active = saved
-        @namespace_stack.pop
+        with_namespace(node.constant_path) { super }
       end
 
       # Track `module_function` so its methods are recorded as singletons (#20) —
@@ -94,9 +87,10 @@ module Mutineer
           if args.empty?
             @module_function_active = true
           else
+            namespace = @namespace_stack.join("::")
             args.each do |arg|
-              @module_function_names << arg.value.to_sym if arg.is_a?(Prism::SymbolNode)
-              @module_function_names << arg.name if arg.is_a?(Prism::DefNode)
+              @module_function_names << [namespace, arg.value.to_sym] if arg.is_a?(Prism::SymbolNode)
+              @module_function_names << [namespace, arg.name] if arg.is_a?(Prism::DefNode)
             end
           end
         end
@@ -127,6 +121,7 @@ module Mutineer
         @subjects << Subject.new(
           file: @file,
           namespace: @namespace_stack.dup,
+          lexical: @lexical_stack.dup,
           name: node.name,
           singleton: !node.receiver.nil? || @singleton_depth.positive? || @module_function_active,
           def_node: node
@@ -136,6 +131,40 @@ module Mutineer
 
       private
 
+      # Runs the block with `path` pushed as the current namespace. A
+      # root-anchored path (`module ::X` / `class ::X`) names the top-level X,
+      # not X nested in the enclosing scope, so the namespace restarts there.
+      # Bareword `module_function` state does not cross a class or module
+      # boundary: each body starts without it, and the outer state returns after.
+      #
+      # @param path [Prism::Node] the class/module constant path.
+      # @yield the class or module body visit.
+      # @return [void]
+      def with_namespace(path)
+        saved_stack = @namespace_stack
+        saved_lexical = @lexical_stack
+        saved_active = @module_function_active
+        name = extract_constant_name(path)
+        root = root_anchored?(path)
+        @namespace_stack = root ? [name] : saved_stack + [name]
+        @lexical_stack = saved_lexical + [root ? "::#{name}" : name]
+        @module_function_active = false
+        yield
+      ensure
+        @namespace_stack = saved_stack
+        @lexical_stack = saved_lexical
+        @module_function_active = saved_active
+      end
+
+      # True when a constant path starts with `::` (e.g. `::X` or `::A::B`).
+      #
+      # @param node [Prism::Node] constant path node.
+      # @return [Boolean]
+      def root_anchored?(node)
+        node = node.parent while node.is_a?(Prism::ConstantPathNode) && node.parent
+        node.is_a?(Prism::ConstantPathNode)
+      end
+
       # Extracts a constant name from a Prism constant node.
       #
       # @api private

data/lib/mutineer/project_path.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # Realpath-based path normalization against a project root. Shared by the
+  # coverage cache (map keys) and mutant ids (the path hashed into each id), so
+  # `lib/x.rb`, `./lib/x.rb`, an absolute path and a path through a symlinked
+  # root all resolve to the same key. Realpaths on both sides also absorb the
+  # macOS `/var` vs `/private/var` alias.
+  module ProjectPath
+    module_function
+
+    # Path of `path` relative to the real project root. A path outside the root
+    # comes back as its absolute real path.
+    #
+    # @param path [String] relative (to `root`) or absolute path.
+    # @param root [String] project root.
+    # @return [String] root-relative path, or an absolute path when outside `root`.
+    def relative(path, root)
+      abs = absolute(path, root)
+      real_root = root_real(root)
+      prefix = real_root.end_with?("/") ? real_root : "#{real_root}/"
+      return abs unless abs.start_with?(prefix)
+
+      abs.delete_prefix(prefix)
+    end
+
+    # Expands `path` against `root`, resolved to its real path when it exists.
+    #
+    # @param path [String] relative (to `root`) or absolute path.
+    # @param root [String] project root.
+    # @return [String] absolute path.
+    def absolute(path, root)
+      # Join, don't expand: File.expand_path collapses `..` textually, before any
+      # symlink is followed, so `link/../x.rb` would name the wrong file. The file
+      # system resolves `..` physically in File.realpath.
+      # A leading `~` names the home directory (as File.expand_path reads it), so
+      # expand it rather than joining it under the root.
+      raw = if File.absolute_path?(path) then path
+            elsif path.start_with?("~") then File.expand_path(path)
+            else File.join(File.expand_path(root), path)
+            end
+      File.exist?(raw) ? File.realpath(raw) : File.expand_path(raw)
+    end
+
+    # Canonical project root (`/var` vs `/private/var`). Any file system error
+    # (missing, unreadable, a symlink loop) falls back to the expanded path, so
+    # a caller such as the CLI's run-root warning never crashes on it.
+    #
+    # @param root [String] project root.
+    # @return [String] realpath of the root when it exists, else its expanded path.
+    def root_real(root)
+      File.realpath(File.expand_path(root))
+    rescue SystemCallError
+      File.expand_path(root)
+    end
+  end
+end

data/lib/mutineer/reporter.rb

@@ -35,11 +35,13 @@ module Mutineer
     # or to `out`. Diagnostics always go to `err`. `scoped` marks a diff-scoped
     # (`--since`) run; the JSON report records it so a consumer (or a later
     # `--baseline` load) knows the score covers only the changed-line mutants.
+    # `legacy_id_matches` (`{ignore:, baseline:}`) counts stored ids still in the
+    # old format (#126); only the JSON report records it (`summary.legacy_id_matches`).
     def report(out: $stdout, err: $stderr, threshold: 0.0, format: "human", output: nil,
-               baseline: nil, scoped: false)
+               baseline: nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 })
       rendered =
         if format == "json"
-          json_report(baseline, scoped: scoped)
+          json_report(baseline, scoped: scoped, legacy_id_matches: legacy_id_matches)
         elsif format == "html"
           html_report
         else
@@ -131,8 +133,11 @@ module Mutineer
     # @param baseline [Mutineer::Baseline::Delta, nil] baseline delta.
     # @param scoped [Boolean] the run was diff-scoped (`--since`), so its score
     #   covers only the changed-line mutants (additive `summary.scoped` key).
+    # @param legacy_id_matches [Hash{Symbol => Integer}] `{ignore:, baseline:}`:
+    #   old-format ignore entries that matched, and survivors matched in an
+    #   old-format baseline only through their old id (#126).
     # @return [String] JSON text.
-    def json_report(baseline = nil, scoped: false)
+    def json_report(baseline = nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 })
       killed = @agg.killed_count
       survived = @agg.survived_count
       # null (not 0.0) on an empty denominator, matching the nil-vs-0.0
@@ -141,7 +146,7 @@ module Mutineer
       score = @agg.mutation_score
 
       doc = {
-        schema_version: "1.3",
+        schema_version: "1.4",
         summary: {
           total: @agg.total, killed: killed, survived: survived,
           no_coverage: @agg.no_coverage_count,
@@ -155,7 +160,15 @@ module Mutineer
           # Additive: true when the run was diff-scoped (--since). The score then
           # covers only the changed-line mutants, so it is not comparable to a
           # full-run score; Baseline#diff reads this to skip the score-drop gate.
-          scoped: scoped
+          scoped: scoped,
+          # Additive (1.4, #126): ids hash the project-relative file path. A
+          # baseline without this key stores old-format ids; Baseline#diff then
+          # also matches on old ids.
+          id_format: 2,
+          # Additive (1.4, #126): stored ids still in the old format. `ignore` is
+          # the number of old-format ignore entries that matched; `baseline` the
+          # survivors matched in the baseline only through their old id.
+          legacy_id_matches: legacy_id_matches
         },
         survivors: @agg.surviving_mutants.map { |r| survivor_json(r) }
                        .sort_by { |h| [h[:file], h[:line], h[:operator]] },

data/lib/mutineer/result.rb

@@ -28,8 +28,8 @@ module Mutineer
   # `subject`, `mutation`, and `id` are nil when the Result is built by
   # Isolation/Runner (which only know the outcome); the orchestrator attaches
   # them afterwards via `result.with(subject:, mutation:, id:)` so the Reporter
-  # can render survivor diffs and emit the stable id. `id` is the content-based
-  # MutantId.
+  # can render survivor diffs and emit the id. `id` is the content-based
+  # MutantId (it includes the project-relative file path).
   Result = Data.define(:status, :details, :subject, :mutation, :id) do
     # Builds a killed result.
     #

data/lib/mutineer/runner.rb

@@ -13,6 +13,7 @@ require_relative "mutator_registry"
 require_relative "worker_pool"
 require_relative "progress"
 require_relative "mutant_id"
+require_relative "project_path"
 require_relative "file_swap"
 require_relative "external_backend"
 require_relative "daemon_backend"
@@ -31,15 +32,18 @@ module Mutineer
   class Runner
     # Full orchestration: resolve operators, discover subjects, build the
     # coverage map, run every mutation, and aggregate. Returns
-    # [AggregateResult, source_map]. The CLI then reports + applies the exit code;
-    # the integration test asserts directly on the AggregateResult.
+    # [AggregateResult, source_map, extras], where extras is the hash
+    # {.collect_jobs} returns (`:legacy_ignore_matches`, `:id_map`), unchanged.
+    # The CLI then reports + applies the exit code; the integration test asserts
+    # directly on the AggregateResult.
     #
     # The parent process `require`s each source file so its classes exist; forked
     # children inherit them, so a covering test file's own require_relative of the
     # source is a no-op and does not clobber the mutated `load` (spec §7).
     #
     # @param config [Mutineer::Config] run configuration.
-    # @return [Array(Mutineer::AggregateResult, Hash<String, String>)] aggregate and source map.
+    # @return [Array(Mutineer::AggregateResult, Hash<String, String>, Hash)] aggregate,
+    #   source map, and run extras.
     def self.execute(config)
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
 
@@ -109,7 +113,7 @@ module Mutineer
       abort_if_unclean!(coverage_map)
 
       # Collect every (subject, mutation) up front so the pool can fan them out.
-      jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
+      jobs, ignored_results, source_map, extras = collect_jobs(config, operator_classes)
 
       jobs = filter_since(jobs, source_map, config) if config.since
 
@@ -144,40 +148,75 @@ module Mutineer
           sweep_orphans(dirs)
         end
 
-      [AggregateResult.new(results + ignored_results), source_map]
+      [AggregateResult.new(results + ignored_results), source_map, extras]
     end
 
     # Collect every (subject, mutation, id) up front so a backend can run them.
     # A mutant the user marked known-equivalent (inline disable-line comment or
     # .mutineer.yml ignore id) is classified :ignored here and NEVER run. It is
     # removed from the killed+survived denominator so a strong file reaches 100%.
-    # The stable id is computed per subject (occurrence needs the full list) and
-    # carried on every job so the parent can reattach it after the run. Shared by
-    # the in-process, external, and daemon backends so job selection can never drift.
+    # The id is computed per subject (occurrence needs the full list), keyed on
+    # the file path relative to config.project_root, and carried on every job so
+    # the parent can reattach it after the run. Shared by the in-process,
+    # external, and daemon backends so job selection can never drift.
     #
-    # @return [Array(Array, Array<Result>, Hash<String,String>)] jobs, ignored, source_map.
+    # Each mutant also gets its old-format id ({MutantId.legacy_for}), so an ignore
+    # entry stored before ids carried the path still suppresses it. Prints nothing:
+    # the extras hash returns, as data, `legacy_ignore_matches` (each old-format
+    # ignore entry that matched a mutant through its old-format id => one
+    # `{id:, file:, subject:}` hash per matched mutant, in collection order: its
+    # new id, its project-relative file and its subject's qualified name;
+    # recorded even when a new id is also listed, since the old entry still
+    # over-matches other files) and `id_map` (every new id => its old-format id).
+    #
+    # Subjects sharing a qualified name in one file (two owner-less `def index`
+    # in two DSL blocks) get a per-file ordinal in discovery order, so their ids
+    # differ; the first one's ordinal is 0 and leaves its id unchanged.
+    #
+    # @param config [Mutineer::Config] run configuration.
+    # @param operator_classes [Array<Class>] resolved operators.
+    # @return [Array(Array, Array<Result>, Hash<String,String>, Hash{Symbol => Hash})]
+    #   jobs, ignored, source_map, and extras (`:legacy_ignore_matches`, `:id_map`).
     def self.collect_jobs(config, operator_classes)
       source_map = {}
       disabled_map = {}
+      id_paths = {}
+      # [file, qualified_name] => { declaration offset => ordinal }: keyed by the
+      # declaration, so the same file discovered twice (two path spellings) reuses
+      # its ordinal instead of minting a second id for the same mutant.
+      name_decls = Hash.new { |h, k| h[k] = {} }
       ignore_set = config.ignore.to_set
       jobs = []
       ignored_results = []
+      legacy_ignore_matches = {}
+      id_map = {}
       Project.discover(config.sources, only: config.only).each do |subject|
         source = (source_map[subject.file] ||= File.read(subject.file))
         disabled = (disabled_map[subject.file] ||= suppress_map(source, subject.file))
         mutations = operator_classes.flat_map { |klass| klass.new.mutations_for(subject, source) }
-        ids = MutantId.for_subject(subject, source, mutations)
+        id_path = (id_paths[subject.file] ||= ProjectPath.relative(subject.file, config.project_root))
+        decls = name_decls[[id_path, subject.qualified_name]]
+        ordinal = (decls[subject.def_node.location.start_offset] ||= decls.size)
+        ids = MutantId.for_subject(subject, source, mutations, path: id_path, subject_ordinal: ordinal)
+        legacy_ids = MutantId.legacy_for_subject(subject, source, mutations)
         mutations.each_with_index do |mutation, i|
           id = ids[i]
+          legacy = legacy_ids[i]
+          id_map[id] = legacy
+          # An old entry still over-matches other files even when the new id is
+          # listed too, so every old-entry match is reported for migration.
+          if ignore_set.include?(legacy)
+            (legacy_ignore_matches[legacy] ||= []) << { id: id, file: id_path, subject: subject.qualified_name }
+          end
           line = source.byteslice(0, mutation.start_offset).count("\n") + 1
-          if suppressed?(mutation.operator, line, id, disabled, ignore_set)
+          if suppressed?(mutation.operator, line, [id, legacy], disabled, ignore_set)
             ignored_results << Result.ignored.with(subject: subject, mutation: mutation, id: id)
           else
             jobs << [subject, mutation, id]
           end
         end
       end
-      [jobs, ignored_results, source_map]
+      [jobs, ignored_results, source_map, { legacy_ignore_matches: legacy_ignore_matches, id_map: id_map }]
     end
 
     # External backend orchestration. Runs each mutant's whole-file mutation on
@@ -189,7 +228,8 @@ module Mutineer
     #
     # @param config [Mutineer::Config] run configuration (test_command set).
     # @param operator_classes [Array<Class>] resolved operators.
-    # @return [Array(Mutineer::AggregateResult, Hash<String,String>)] aggregate and source map.
+    # @return [Array(Mutineer::AggregateResult, Hash<String,String>, Hash)] aggregate,
+    #   source map, and the {.collect_jobs} extras.
     def self.execute_external(config, operator_classes)
       abs_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
       sources   = config.sources.map { |s| FileSwap.canonical_path(File.expand_path(s, config.project_root)) }
@@ -205,12 +245,12 @@ module Mutineer
         # source. Heal first, then discover jobs from the clean tree.
         FileSwap.restore_orphans(dirs)
 
-        jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
+        jobs, ignored_results, source_map, extras = collect_jobs(config, operator_classes)
         jobs = filter_since(jobs, source_map, config) if config.since
 
         # Nothing to mutate: return before the smoke check, which runs the whole
         # --test set to calibrate a timeout no mutant would use (#76).
-        next [AggregateResult.new(ignored_results), source_map] if jobs.empty?
+        next [AggregateResult.new(ignored_results), source_map, extras] if jobs.empty?
 
         # Calibrate the per-mutant timeout from the clean run (a real suite far
         # outlasts the 10s in-process fork budget), and abort if it is not green.
@@ -234,7 +274,7 @@ module Mutineer
           FileSwap.restore_orphans(dirs)
         end
 
-        [AggregateResult.new(results + ignored_results), source_map]
+        [AggregateResult.new(results + ignored_results), source_map, extras]
       end
     end
 
@@ -331,10 +371,14 @@ module Mutineer
     end
 
     # True when this mutant is suppressed: its line bears a disable-line marker
-    # (bare, or scoped to its operator), OR its stable id is in the config ignore
-    # list. Checked at job-build time so a suppressed mutant is never forked.
-    def self.suppressed?(operator, line, id, disabled, ignore_set)
-      return true if ignore_set.include?(id)
+    # (bare, or scoped to its operator), OR its new or old-format id is in the
+    # config ignore list. Checked at job-build time so a suppressed mutant is
+    # never forked.
+    #
+    # @param ids [Array<String>, String] the mutant's new id and its old-format
+    #   id, or a single id (the pre-#126 call shape).
+    def self.suppressed?(operator, line, ids, disabled, ignore_set)
+      return true if Array(ids).any? { |id| ignore_set.include?(id) }
 
       case (entry = disabled[line])
       when :all then true

data/lib/mutineer/subject.rb

@@ -4,8 +4,11 @@ module Mutineer
   # One discoverable method and its AST node.
   #
   # Location, namespace context, and the live Prism::DefNode are kept together
-  # because mutators walk the def node directly.
-  Subject = Struct.new(:file, :namespace, :name, :singleton, :def_node, keyword_init: true) do
+  # because mutators walk the def node directly. `namespace` names the owner
+  # (`module ::X` inside `Outer` owns into `X`); `lexical` is the class/module
+  # chain as written (`["Outer", "::X"]`), which the redefine strategy needs to
+  # rebuild the same Module.nesting as a whole-file reload (#145).
+  Subject = Struct.new(:file, :namespace, :name, :singleton, :def_node, :lexical, keyword_init: true) do
     # Returns the fully-qualified subject name.
     #
     # @return [String] namespaced method name like `Billing::Invoice#total`.
@@ -13,6 +16,14 @@ module Mutineer
       namespace.join("::") + (singleton ? "." : "#") + name.to_s
     end
 
+    # Class/module chain as written in the source, for textual wrappers. Falls
+    # back to `namespace` for subjects built without one.
+    #
+    # @return [Array<String>] names; a root-anchored element keeps its `::`.
+    def lexical_namespace
+      lexical || namespace
+    end
+
     # Returns the body location for the subject, if any.
     #
     # @return [Prism::Location, nil] body location or nil for empty methods.

data/lib/mutineer/version.rb

@@ -2,5 +2,5 @@
 
 module Mutineer
   # Current Mutineer release version.
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutineer
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - David Teren
@@ -91,6 +91,7 @@ files:
 - lib/mutineer/parser.rb
 - lib/mutineer/progress.rb
 - lib/mutineer/project.rb
+- lib/mutineer/project_path.rb
 - lib/mutineer/rails_worker_db.rb
 - lib/mutineer/reporter.rb
 - lib/mutineer/result.rb