mutineer 1.1.0 → 1.3.0

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

@@ -99,7 +99,7 @@ module Mutineer
     # @param source_file [String] original source file path.
     # @return [Object] whatever `load` returns.
     def self.apply_whole_file(mutated, source_file)
-      Tempfile.create(["mutineer_mutant", ".rb"], File.dirname(source_file)) do |f|
+      Tempfile.create(["mutineer_mutant", ".rb"], File.dirname(File.expand_path(source_file))) do |f|
         f.write(mutated)
         f.flush
         load f.path
@@ -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/mutator_registry.rb

@@ -15,6 +15,8 @@ require_relative "mutators/safe_navigation"
 require_relative "mutators/range_literal"
 require_relative "mutators/negation_removal"
 require_relative "mutators/chain_link"
+require_relative "mutators/operand_removal"
+require_relative "mutators/array_literal"
 
 module Mutineer
   # Maps operator names to operator classes.
@@ -41,7 +43,9 @@ module Mutineer
       "safe_navigation"    => Mutators::SafeNavigation,
       "range"              => Mutators::RangeLiteral,
       "negation_removal"   => Mutators::NegationRemoval,
-      "chain_link"         => Mutators::ChainLink
+      "chain_link"         => Mutators::ChainLink,
+      "operand_removal"    => Mutators::OperandRemoval,
+      "array_literal"      => Mutators::ArrayLiteral
     }.freeze
 
     # The default Tier-1 operator set.
@@ -49,7 +53,7 @@ module Mutineer
     # Tier-2 operators that remain opt-in.
     TIER2_NAMES   = %w[return_nil literal_mutation condition_negation string_literal regex collection_method
                        safe_navigation range negation_removal
-                       chain_link].freeze
+                       chain_link operand_removal array_literal].freeze
 
     # Short human-readable descriptions for each operator.
     DESCRIPTIONS = {
@@ -67,7 +71,9 @@ module Mutineer
       "safe_navigation"    => "&. -> .",
       "range"              => ".. <-> ...",
       "negation_removal"   => "!x, not x -> x",
-      "chain_link"         => "drop one call from a chain: a.b.c -> a.c"
+      "chain_link"         => "drop one call from a chain: a.b.c -> a.c",
+      "operand_removal"    => "a && b -> a, b",
+      "array_literal"      => "[a, b] -> []"
     }.freeze
 
     # Resolves operator names to classes.

data/lib/mutineer/mutators/array_literal.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Array-literal mutator (Tier-2).
+    #
+    # Replaces a non-empty array literal with an empty one, one mutation per
+    # literal: `[a, b]` and `%i[a b]` become `[]`. The mutant survives when no
+    # test checks the contents of the array.
+    class ArrayLiteral < Base
+      # Visits array nodes and emits array-literal mutations.
+      #
+      # @param node [Prism::ArrayNode] array node to inspect.
+      # @return [void]
+      def visit_array_node(node)
+        emit(node)
+        super # nested arrays each get their own mutation
+      end
+
+      # Skips a nested method definition. The project finds it as a subject of
+      # its own, so a visit here counts its arrays twice.
+      #
+      # @param node [Prism::DefNode] nested definition node.
+      # @return [void]
+      def visit_def_node(node); end
+
+      private
+
+      # Emits a mutation for a non-empty array with brackets.
+      #
+      # The operator skips an implicit array (`x = 1, 2`), because it has no
+      # brackets. It also skips an array that holds a heredoc, because the
+      # heredoc body stays behind as code.
+      #
+      # @param node [Prism::ArrayNode] array node to inspect.
+      # @return [void]
+      def emit(node)
+        return if node.opening_loc.nil? || node.elements.empty? || heredoc?(node)
+
+        @mutations << Mutation.new(
+          start_offset: node.location.start_offset,
+          end_offset: node.location.end_offset,
+          replacement: "[]",
+          operator: :array_literal
+        )
+      end
+    end
+  end
+end

data/lib/mutineer/mutators/base.rb

@@ -26,6 +26,21 @@ module Mutineer
         subject.def_node.body&.accept(self)
         @mutations
       end
+
+      private
+
+      # Returns whether a node is, or contains, a heredoc.
+      #
+      # A heredoc's body lies outside its node's byte range. A mutation that
+      # deletes the node leaves the body behind as code, so the mutant
+      # always raises.
+      #
+      # @param node [Prism::Node] node to inspect.
+      # @return [Boolean] true when a heredoc is inside the node.
+      def heredoc?(node)
+        (node.respond_to?(:heredoc?) && node.heredoc?) ||
+          node.compact_child_nodes.any? { |child| heredoc?(child) }
+      end
     end
   end
 end

data/lib/mutineer/mutators/operand_removal.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Operand-removal mutator (Tier-2).
+    #
+    # Replaces a boolean expression with one of its operands, two mutations
+    # per `&&`, `||`, `and` or `or`: `a && b` becomes `(a)` and `(b)`. The
+    # parentheses keep the precedence of `and` and `or`. A surviving mutant
+    # shows that no test needs the operand that was removed.
+    class OperandRemoval < Base
+      # Node types for jumps. A jump in a value context does not parse, so
+      # the operator never keeps a jump alone.
+      JUMPS = [Prism::ReturnNode, Prism::BreakNode, Prism::NextNode, Prism::RedoNode, Prism::RetryNode].freeze
+
+      # Visits `and` nodes.
+      #
+      # @param node [Prism::AndNode] node to inspect.
+      # @return [void]
+      def visit_and_node(node)
+        emit(node)
+        super # nested connectors (a && b && c) each get their own mutations
+      end
+
+      # Visits `or` nodes.
+      #
+      # @param node [Prism::OrNode] node to inspect.
+      # @return [void]
+      def visit_or_node(node)
+        emit(node)
+        super
+      end
+
+      # Skips a nested method definition. The project finds it as a subject of
+      # its own, so a visit here counts its connectors twice.
+      #
+      # @param node [Prism::DefNode] nested definition node.
+      # @return [void]
+      def visit_def_node(node); end
+
+      private
+
+      # Emits one mutation that keeps the left operand, then one that keeps
+      # the right operand. The order is fixed, because the two mutants share
+      # a token and their occurrence ordinals tell them apart.
+      #
+      # @param node [Prism::AndNode, Prism::OrNode] connector node.
+      # @return [void]
+      def emit(node)
+        [[node.left, node.right], [node.right, node.left]].each do |kept, removed|
+          next if JUMPS.any? { |type| kept.is_a?(type) } || heredoc?(removed)
+
+          @mutations << Mutation.new(
+            start_offset: node.location.start_offset,
+            end_offset: node.location.end_offset,
+            replacement: "(#{kept.slice})",
+            operator: :operand_removal
+          )
+        end
+      end
+    end
+  end
+end

data/lib/mutineer/pairing.rb

@@ -5,9 +5,9 @@ module Mutineer
   # no Rails, no class loading, no process. Two jobs:
   #   * expand_sources — a directory argument becomes its sorted **/*.rb files.
   #   * infer_test     — a source's test file by convention (app/ and lib/
-  #                     sources map to test/.../_test.rb or spec/.../_spec.rb),
-  #                     preserving namespaced subdirectories. First EXISTING
-  #                     candidate wins.
+  #                     sources map to test/.../_test.rb, test/.../test_*.rb
+  #                     or spec/.../_spec.rb), preserving namespaced
+  #                     subdirectories. First EXISTING candidate wins.
   #
   # Independently unit-testable: every method is pure in/out over the
   # filesystem, so the pairing contract is exercised with plain fixtures, no
@@ -68,8 +68,8 @@ module Mutineer
       end
     end
 
-    # Ordered candidate test paths. lib/ sources also get test/lib/... and
-    # spec/lib/... (Rails apps put lib tests under either layout).
+    # Ordered candidate test paths: _test.rb, then Minitest's test_*.rb, then
+    # _spec.rb. lib/ sources also get the test/lib/... and spec/lib/... layouts.
     #
     # @param base [String] logical source path without extension.
     # @param lib [Boolean] whether the source originated from lib/.
@@ -78,6 +78,11 @@ module Mutineer
     def candidates(base, lib, prefer)
       minitest = ["test/#{base}_test.rb"]
       minitest << "test/lib/#{base}_test.rb" if lib
+      unless File.basename(base) == "helper" # test/test_helper.rb is Minitest's support file, not a test
+        prefixed = base.sub(%r{[^/]+\z}) { |name| "test_#{name}" }
+        minitest << "test/#{prefixed}.rb"
+        minitest << "test/lib/#{prefixed}.rb" if lib
+      end
       rspec = ["spec/#{base}_spec.rb"]
       rspec << "spec/lib/#{base}_spec.rb" if lib
       prefer == "rspec" ? rspec + minitest : minitest + rspec

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.
     #