mutineer 1.2.0 → 1.4.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

@@ -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

@@ -17,6 +17,8 @@ require_relative "mutators/negation_removal"
 require_relative "mutators/chain_link"
 require_relative "mutators/operand_removal"
 require_relative "mutators/array_literal"
+require_relative "mutators/condition_forcing"
+require_relative "mutators/operator_assignment"
 
 module Mutineer
   # Maps operator names to operator classes.
@@ -45,7 +47,10 @@ module Mutineer
       "negation_removal"   => Mutators::NegationRemoval,
       "chain_link"         => Mutators::ChainLink,
       "operand_removal"    => Mutators::OperandRemoval,
-      "array_literal"      => Mutators::ArrayLiteral
+      "array_literal"      => Mutators::ArrayLiteral,
+      "condition_true"     => Mutators::ConditionTrue,
+      "condition_false"    => Mutators::ConditionFalse,
+      "operator_assignment" => Mutators::OperatorAssignment
     }.freeze
 
     # The default Tier-1 operator set.
@@ -53,7 +58,8 @@ 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 operand_removal array_literal].freeze
+                       chain_link operand_removal array_literal
+                       condition_true condition_false operator_assignment].freeze
 
     # Short human-readable descriptions for each operator.
     DESCRIPTIONS = {
@@ -73,7 +79,10 @@ module Mutineer
       "negation_removal"   => "!x, not x -> x",
       "chain_link"         => "drop one call from a chain: a.b.c -> a.c",
       "operand_removal"    => "a && b -> a, b",
-      "array_literal"      => "[a, b] -> []"
+      "array_literal"      => "[a, b] -> []",
+      "condition_true"     => "if/elsif/unless/ternary/modifier/case-in guard condition -> true",
+      "condition_false"    => "if/elsif/unless/ternary/modifier/case-in guard condition -> false",
+      "operator_assignment" => "+= <-> -=, *= <-> /=, %= -> *=, **= -> *= (not ||=, &&=)"
     }.freeze
 
     # Resolves operator names to classes.

data/lib/mutineer/mutators/condition_forcing.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Shared base of the condition-forcing mutators (Tier-2).
+    #
+    # Replaces the condition of an `if`, `elsif`, `unless`, ternary, modifier
+    # guard (`x if y`) or `case`/`in` guard with a literal, so its branch always
+    # runs or never runs. {ConditionTrue} forces `true` and {ConditionFalse}
+    # forces `false`; one mutation per condition each.
+    #
+    # A condition that is already `true`, `false` or `nil`, even in
+    # parentheses, is left alone: forcing it changes nothing or repeats the
+    # `boolean_literal` flip. This holds even when `boolean_literal` does not run.
+    # A condition that holds a heredoc is left alone too: the heredoc body lies
+    # outside the condition, so it would stay behind as code. A condition that
+    # assigns a variable keeps its code and only its value is forced.
+    #
+    # The never-runs side of an else-less conditional can be the same program
+    # as the `nil` that `statement_removal` or `return_nil` puts in place of the
+    # whole conditional. It is still made: dropping it would make the mutants
+    # of one operator depend on which other operators run, and on what the user
+    # suppressed for them. The two then get the same verdict.
+    #
+    # `condition_negation` wraps the condition in `!( ... )`, which neither
+    # forced value is.
+    class ConditionForcing < Base
+      # Condition nodes that `boolean_literal` already mutates.
+      LITERALS = [Prism::TrueNode, Prism::FalseNode, Prism::NilNode].freeze
+
+      # Visits if nodes: `if`, `elsif`, a ternary, a modifier `if` and an
+      # `in ... if` guard.
+      #
+      # @param node [Prism::IfNode] node to inspect.
+      # @return [void]
+      def visit_if_node(node)
+        force(node)
+        super
+      end
+
+      # Visits unless nodes: `unless`, a modifier `unless` and an
+      # `in ... unless` guard.
+      #
+      # @param node [Prism::UnlessNode] node to inspect.
+      # @return [void]
+      def visit_unless_node(node)
+        force(node)
+        super
+      end
+
+      # Nested method definitions are discovered as their own subjects; do not
+      # recurse into them (prevents double-counting their conditions).
+      #
+      # @param node [Prism::DefNode] nested definition node.
+      # @return [void]
+      def visit_def_node(node); end
+
+      private
+
+      # Emits the forced condition unless the condition is a literal or holds a
+      # heredoc, whose body would stay behind as code.
+      #
+      # @param node [Prism::IfNode, Prism::UnlessNode] the conditional.
+      # @return [void]
+      def force(node)
+        predicate = node.predicate
+        return if LITERALS.include?(unwrap(predicate).class) || heredoc?(predicate)
+
+        loc = predicate.location
+        @mutations << Mutation.new(
+          start_offset: loc.start_offset,
+          end_offset: loc.end_offset,
+          replacement: replacement(predicate),
+          operator: self.class::OPERATOR
+        )
+      end
+
+      # Returns the forced value for the condition, always in parentheses, so it
+      # cannot fuse with a keyword or a `?` next to it: `x if@a` becomes
+      # `x if(true)` and `@a?1:2` becomes `(true)?1:2`. A condition that assigns
+      # a variable keeps its code, so later reads still see the variable:
+      # `(m = x; true)`.
+      #
+      # @param predicate [Prism::Node] the condition.
+      # @return [String] the replacement source.
+      def replacement(predicate)
+        value = self.class::VALUE.to_s
+        writes?(predicate) ? "(#{predicate.slice}; #{value})" : "(#{value})"
+      end
+
+      # Returns whether the node writes a variable or constant anywhere inside
+      # it: a local, instance, class or global variable, or a constant, in a
+      # plain, compound, multiple or pattern write, or a named regex capture.
+      #
+      # @param node [Prism::Node] the node to inspect.
+      # @return [Boolean] true when a write or target node is inside.
+      def writes?(node)
+        return true if node.type.name.end_with?("_write_node", "_target_node")
+
+        node.compact_child_nodes.any? { |child| writes?(child) }
+      end
+
+      # Returns the node inside parentheses that hold exactly one expression,
+      # so `(true)` and `((true))` read as `true`.
+      #
+      # @param node [Prism::Node] the condition.
+      # @return [Prism::Node] the innermost wrapped node, or `node` itself.
+      def unwrap(node)
+        body = node.body if node.is_a?(Prism::ParenthesesNode)
+        body = body.body.first if body.is_a?(Prism::StatementsNode) && body.body.size == 1
+        body && !body.is_a?(Prism::StatementsNode) ? unwrap(body) : node
+      end
+    end
+
+    # Condition-forcing mutator: the condition becomes `true` (Tier-2).
+    #
+    # An `if` branch always runs; an `unless` branch never runs. The mutant
+    # survives when no test runs the code with the condition false (for an
+    # `if`) or true (for an `unless`) and checks what changes.
+    class ConditionTrue < ConditionForcing
+      # The literal the condition is replaced with.
+      VALUE = true
+      # The operator name mutations carry.
+      OPERATOR = :condition_true
+    end
+
+    # Condition-forcing mutator: the condition becomes `false` (Tier-2).
+    #
+    # An `if` branch never runs; an `unless` branch always runs. The mutant
+    # survives when no test needs the branch the condition guards (for an
+    # `if`) or skips it (for an `unless`).
+    class ConditionFalse < ConditionForcing
+      # The literal the condition is replaced with.
+      VALUE = false
+      # The operator name mutations carry.
+      OPERATOR = :condition_false
+    end
+  end
+end

data/lib/mutineer/mutators/operator_assignment.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Operator-assignment mutator (Tier-2).
+    #
+    # Swaps the operator of a compound assignment, one mutation per
+    # occurrence: `t += x` -> `t -= x`. Prism parses `t += x` as its own
+    # node, not as a CallNode, so the arithmetic mutator never sees it.
+    #
+    # The mapping is the same as for arithmetic. Other compound operators
+    # (`||=`, `&&=`, `|=`, `<<=` and the rest) are not changed.
+    class OperatorAssignment < Base
+      # Token replacements for compound arithmetic operators.
+      REPLACEMENTS = {
+        :+ => "-=", :- => "+=", :* => "/=", :/ => "*=", :% => "*=", :** => "*="
+      }.freeze
+
+      # Visits `t += x`.
+      #
+      # @param node [Prism::LocalVariableOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_local_variable_operator_write_node(node)
+        emit(node)
+        super # the value can hold its own compound assignment
+      end
+
+      # Visits `@t += x`.
+      #
+      # @param node [Prism::InstanceVariableOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_instance_variable_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `@@t += x`.
+      #
+      # @param node [Prism::ClassVariableOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_class_variable_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `$t += x`.
+      #
+      # @param node [Prism::GlobalVariableOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_global_variable_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `T += x`.
+      #
+      # @param node [Prism::ConstantOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_constant_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `A::T += x` and `::T += x`.
+      #
+      # @param node [Prism::ConstantPathOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_constant_path_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `a.b += x` and `a&.b += x`.
+      #
+      # @param node [Prism::CallOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_call_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `a[i] += x`.
+      #
+      # @param node [Prism::IndexOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_index_operator_write_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 compound assignments twice.
+      #
+      # @param node [Prism::DefNode] nested definition node.
+      # @return [void]
+      def visit_def_node(node); end
+
+      private
+
+      # Emits a mutation when the node's operator has a replacement.
+      #
+      # @param node [Prism::Node] a node with `binary_operator` and `binary_operator_loc`.
+      # @return [void]
+      def emit(node)
+        replacement = REPLACEMENTS[node.binary_operator]
+        return unless replacement
+
+        loc = node.binary_operator_loc
+        @mutations << Mutation.new(
+          start_offset: loc.start_offset,
+          end_offset: loc.end_offset,
+          replacement: replacement,
+          operator: :operator_assignment
+        )
+      end
+    end
+  end
+end

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