mutineer 0.6.2 → 0.8.0

data/lib/mutineer/config.rb

@@ -24,12 +24,14 @@ module Mutineer
     :sources, :tests, :operators, :threshold, :only, :dry_run,
     :cache_dir, :project_root, :load_paths,
     :jobs, :format, :output, :strategy, :require_paths,
-    :boot, :rails, :since, :framework,
+    :boot, :rails, :since, :framework, :verbose, :ignore,
+    :baseline, :baseline_epsilon,
     keyword_init: true
   ) do
+    # Config file name.
     CONFIG_FILE = ".mutineer.yml"
     # Keys accepted in .mutineer.yml (R7). `require` maps to the :require_paths field.
-    KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework].freeze
+    KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework verbose ignore baseline].freeze
 
     def initialize(**kwargs)
       super
@@ -45,6 +47,9 @@ module Mutineer
       self.strategy      ||= "reload"
       self.require_paths ||= []
       self.rails         = false if rails.nil?
+      self.verbose       = false if verbose.nil?
+      self.ignore        ||= []
+      self.baseline_epsilon ||= 0.0
     end
 
     # Walk from `start` toward `home`, returning the first .mutineer.yml path found
@@ -124,16 +129,30 @@ module Mutineer
 
     # Pick rspec when a MAJORITY of the given test files end with _spec.rb;
     # otherwise minitest. Empty/ambiguous -> minitest (the safe default).
+    # Detects the test framework from the file list.
+    #
+    # @param tests [Array<String>] test file paths.
+    # @return [String] `"rspec"` or `"minitest"`.
     def self.detect_framework(tests)
       tests = Array(tests)
       specs = tests.count { |t| t.to_s.end_with?("_spec.rb") }
       specs > tests.length / 2.0 ? "rspec" : "minitest"
     end
 
+    # Maps a config key to its Struct field.
+    #
+    # @param known_key [String] config key.
+    # @return [Symbol] struct field name.
     def self.field_for(known_key)
       known_key == "require" ? :require_paths : known_key.to_sym
     end
 
+    # Coerces a config value to its target type.
+    #
+    # @param known_key [String] config key.
+    # @param value [Object] raw YAML value.
+    # @param file_name [String] config file name for warnings.
+    # @return [Object] coerced value.
     def self.coerce(known_key, value, file_name)
       case known_key
       when "operators" then filter_operators(Array(value).map(&:to_s), file_name)
@@ -143,6 +162,9 @@ module Mutineer
       when "boot"      then value.to_s
       when "framework" then value.to_s
       when "rails"     then value == true || value.to_s == "true"
+      when "verbose"   then value == true || value.to_s == "true"
+      when "ignore"    then Array(value).map(&:to_s)
+      when "baseline"  then value.to_s
       else value
       end
     end
@@ -150,6 +172,12 @@ module Mutineer
     # Drop (with a warning) operator names the registry doesn't know (R7).
     # Referenced lazily so config.rb carries no load-order dependency on the
     # registry; by the time a config is parsed at runtime, it is loaded.
+    # Filters out unknown operator names.
+    #
+    # @api private
+    # @param names [Array<String>] operator names.
+    # @param file_name [String] config file name for warnings.
+    # @return [Array<String>] known operator names.
     def self.filter_operators(names, file_name)
       known = MutatorRegistry::ALL.keys
       names.select do |n|

data/lib/mutineer/coverage_map.rb

@@ -6,6 +6,7 @@ require "digest"
 require "fileutils"
 require "rbconfig"
 require "coverage"
+require "set"
 require_relative "minitest_integration"
 require_relative "test_runners"
 
@@ -25,7 +26,7 @@ module Mutineer
     def initialize(source_paths:, test_paths:, cache_dir: ".mutineer",
                    load_paths: ["lib"], project_root: Dir.pwd,
                    capture_timeout: DEFAULT_CAPTURE_TIMEOUT, boot_path: nil,
-                   framework: "minitest")
+                   framework: "minitest", verbose: false)
       @source_paths = Array(source_paths)
       @test_paths   = Array(test_paths)
       @cache_dir    = cache_dir
@@ -34,6 +35,7 @@ module Mutineer
       @capture_timeout = capture_timeout
       @boot_path    = boot_path
       @framework    = framework || "minitest"
+      @verbose      = verbose
       @map          = {}
       @failed_test_files = []
       @phase_a_ran  = false
@@ -64,8 +66,40 @@ module Mutineer
       @map["#{relativize(file)}:#{line}"] || []
     end
 
+    # #9: is this source file's empty coverage the result of an *errored* capture
+    # rather than a genuine coverage gap? True iff (KTD-2) some capture failed this
+    # run AND this file got zero coverage from any successful capture AND a failed
+    # test file maps to it by the standard _test/_spec naming convention. Derived
+    # purely from already-persisted state (@map keys + @failed_test_files); no rerun,
+    # no new cached field, no digest change.
+    #
+    # ponytail: file-level, convention-based attribution. A line covered only by a
+    # failed test in an otherwise-covered file stays no_coverage (condition 2), and
+    # a source with no naming-convention test match is never tainted. Upgrade path:
+    # persist per-file coverage per successful run and diff against the failed set,
+    # or record test->source targets explicitly. Not needed for the #8/#9 cases.
+    def uncapturable_source?(file)
+      return false if @failed_test_files.empty?
+
+      rel = relativize(absolute(file))
+      return false if covered_source_files.include?(rel)
+
+      failed_test_targets.include?(File.basename(rel, ".rb"))
+    end
+
     private
 
+    # Source rel-paths that received coverage from any successful capture.
+    def covered_source_files
+      @map.keys.map { |k| k.rpartition(":").first }.to_set
+    end
+
+    # Basenames of failed test files with a trailing _test/_spec (and .rb) stripped,
+    # i.e. the source basenames they would have covered by convention.
+    def failed_test_targets
+      @failed_test_files.map { |t| File.basename(t, ".rb").sub(/_(test|spec)\z/, "") }.to_set
+    end
+
     # Shared cache dance for both build paths: hit the digest-keyed cache, else
     # yield to populate @map and persist it.
     def cached_or
@@ -83,6 +117,9 @@ module Mutineer
       self
     end
 
+    # Runs standalone Phase A coverage capture.
+    #
+    # @api private
     def run_phase_a
       @phase_a_ran = true
       @map = {}
@@ -108,10 +145,16 @@ module Mutineer
       abs_sources = abs_source_paths
 
       @test_paths.each do |test_path|
-        coverage = fork_capture(absolute(test_path), abs_sources, rails)
-        next fail_test(test_path, "fork capture produced no result") unless coverage
-
-        record(coverage, test_path)
+        # Tri-state payload (KTD-1): Hash = coverage, String = error diagnostic
+        # from the child, nil = pipe gone / empty.
+        # ponytail/#9: this String diagnostic is what #9 turns into an :uncapturable status.
+        case (coverage = fork_capture(absolute(test_path), abs_sources, rails))
+        when Hash   then record(coverage, test_path)
+        when String
+          fail_test(test_path, @verbose ? "fork capture failed: #{coverage}" :
+            "fork capture produced no result (re-run with --verbose for the error)")
+        else fail_test(test_path, "fork capture produced no result")
+        end
       end
     end
 
@@ -120,6 +163,11 @@ module Mutineer
     # fork + Marshal-over-pipe + hard-exit! discipline as WorkerPool/Isolation.
     def fork_capture(abs_test, abs_sources, rails)
       rd, wr = IO.pipe
+      # #19: Marshal output is binary — an un-binmoded pipe can raise
+      # Encoding::UndefinedConversionError on write, which the child's rescue then
+      # swallows, losing the real error and yielding a bare "no result".
+      rd.binmode
+      wr.binmode
       pid = fork do
         rd.close
         payload =
@@ -132,8 +180,10 @@ module Mutineer
             Coverage.result(stop: false)
                     .select { |f, _| abs_sources.include?(f) }
                     .transform_values { |v| v.is_a?(Hash) ? v[:lines] : v }
-          rescue Exception # rubocop:disable Lint/RescueException
-            nil
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            # KTD-1: stringify (an arbitrary Exception may not marshal); the parent
+            # surfaces this under --verbose. A String marshals safely over the pipe.
+            "#{e.class}: #{e.message}#{e.backtrace&.first ? " @ #{e.backtrace.first}" : ''}"
           end
         begin
           wr.write(Marshal.dump(payload))
@@ -147,12 +197,30 @@ module Mutineer
       wr.close
       data = rd.read
       rd.close
-      Process.waitpid(pid)
-      return nil if data.empty?
+      _, status = Process.waitpid2(pid)
+      # #19: an empty pipe means the child died before writing (e.g. a hard crash,
+      # OOM, or a signal from the test's own subprocess handling). Report HOW it
+      # died (exit status / signal) as a diagnostic string so --verbose has
+      # something actionable instead of a silent "no result".
+      return "child wrote no result (#{describe_status(status)})" if data.empty?
 
       Marshal.load(data)
-    rescue StandardError
-      nil
+    rescue StandardError => e
+      "parent could not read capture result: #{e.class}: #{e.message}"
+    end
+
+    # Human description of a child Process::Status for capture diagnostics.
+    #
+    # @api private
+    # @param status [Process::Status] the reaped child status.
+    # @return [String] e.g. "killed by signal 9 (SIGKILL)" or "exit status 1".
+    def describe_status(status)
+      if status.signaled?
+        sig = status.termsig
+        "killed by signal #{sig}#{Signal.signame(sig) ? " (SIG#{Signal.signame(sig)})" : ''}"
+      else
+        "exit status #{status.exitstatus.inspect}"
+      end
     end
 
     # Spawns a fresh `ruby` reading an inline script from stdin. A fork would
@@ -183,6 +251,12 @@ module Mutineer
       fail_test(test_path, "invalid coverage output: #{e.message}")
     end
 
+    # Records a failed coverage capture.
+    #
+    # @api private
+    # @param test_path [String] test file path.
+    # @param reason [String] failure reason.
+    # @return [void]
     def fail_test(test_path, reason)
       rel = relativize(test_path)
       @failed_test_files << rel
@@ -190,10 +264,20 @@ module Mutineer
       nil
     end
 
+    # Builds the framework-specific subprocess script.
+    #
+    # @api private
+    # @param test_path [String] test file path.
+    # @return [String] Ruby script text.
     def subprocess_script(test_path)
       @framework == "rspec" ? rspec_subprocess_script(test_path) : minitest_subprocess_script(test_path)
     end
 
+    # Builds the minitest subprocess script.
+    #
+    # @api private
+    # @param test_path [String] test file path.
+    # @return [String] Ruby script text.
     def minitest_subprocess_script(test_path)
       <<~RUBY
         require "coverage"
@@ -280,6 +364,13 @@ module Mutineer
       File.exist?(absolute(@boot_path)) ? @boot_path : "#{@boot_path}.rb"
     end
 
+    # Groups a digest with its role and paths.
+    #
+    # @api private
+    # @param digest [String] digest string.
+    # @param role [String] digest role.
+    # @param paths [Array<String>] paths in the digest group.
+    # @return [Array(String, String, Array<String>)] grouped digest data.
     def digest_group(digest, role, paths)
       paths.sort.each do |p|
         content = File.read(absolute(p))
@@ -305,8 +396,16 @@ module Mutineer
       end
     end
 
+    # Returns the cache path.
+    #
+    # @api private
+    # @return [String] cache file path.
     def cache_path = File.join(@cache_dir, "coverage.json")
 
+    # Reads the coverage cache.
+    #
+    # @api private
+    # @return [Hash, nil] cached payload.
     def read_cache
       return nil unless File.exist?(cache_path)
 
@@ -315,6 +414,10 @@ module Mutineer
       nil # corrupt cache — rebuild from scratch
     end
 
+    # Saves the coverage cache.
+    #
+    # @api private
+    # @return [void]
     def save
       FileUtils.mkdir_p(@cache_dir)
       data = { "digest" => @digest, "failed_test_files" => @failed_test_files, "map" => @map }
@@ -323,20 +426,41 @@ module Mutineer
       File.rename(tmp, cache_path) # atomic swap
     end
 
+    # Warns when coverage capture was incomplete.
+    #
+    # @api private
+    # @return [void]
     def warn_incomplete
       warn "[mutineer] cached coverage map may be incomplete; these test files " \
            "failed to contribute: #{@failed_test_files.join(', ')}"
     end
 
+    # Returns absolute source paths.
+    #
+    # @return [Array<String>] absolute source paths.
     def abs_source_paths = @source_paths.map { |p| absolute(p) }
+
+    # Returns absolute load paths.
+    #
+    # @return [Array<String>] absolute load paths.
     def abs_load_paths   = @load_paths.map { |p| absolute(p) }
 
+    # Relativizes a path against the project root.
+    #
+    # @api private
+    # @param path [String] path to relativize.
+    # @return [String] relative path.
     def relativize(path)
       return path unless path.start_with?("/")
 
       path.delete_prefix("#{@project_root}/")
     end
 
+    # Expands a path relative to the project root.
+    #
+    # @api private
+    # @param path [String] path to expand.
+    # @return [String] absolute path.
     def absolute(path)
       File.absolute_path?(path) ? path : File.expand_path(path, @project_root)
     end

data/lib/mutineer/isolation.rb

@@ -10,20 +10,25 @@ module Mutineer
   # exit status into a Result.
   #
   # Exit-status contract (the block's return value, or an explicit exit, is the
-  # child's status): 0 => survived, 1 => killed, 2 => error. Timeout is detected
-  # by the parent's monitor flag, not by status.signaled? (which is true for ANY
-  # signal death, e.g. SIGSEGV — it cannot tell our SIGKILL apart from the OS's).
+  # child's status): 0 => survived, 1 => killed, 2 => error. Timeout is
+  # detected by the parent's monitor flag, not by status.signaled? (which is
+  # true for ANY signal death, e.g. SIGSEGV — it cannot tell our SIGKILL apart
+  # from the OS's).
   #
-  # mutineer: the reload strategy this enables (whole-file `load`) re-executes the
-  # entire file — any top-level code runs again. Acceptable for POROs; document
-  # if users hit issues with initializers/callbacks. Alternative: the redefine
-  # strategy (surgical single-method redefinition).
+  # mutineer: the reload strategy this enables (whole-file `load`) re-executes
+  # the entire file — any top-level code runs again. Acceptable for POROs;
+  # document if users hit issues with initializers/callbacks. Alternative: the
+  # redefine strategy (surgical single-method redefinition).
   class Isolation
     DEFAULT_TIMEOUT = 10 # seconds
 
     # Runs the block in a forked child. The block's return value (an Integer
     # exit code) or any explicit `exit` is honoured; an unhandled exception
     # becomes exit 2 with the cause written to STDERR.
+    #
+    # @param timeout [Integer] timeout in seconds.
+    # @yieldreturn [Integer] child exit status.
+    # @return [Mutineer::Result] result from the child process.
     def self.run(timeout: DEFAULT_TIMEOUT)
       pid = fork do
         code = 0
@@ -43,11 +48,12 @@ module Mutineer
         exit!(code)
       end
 
-      # Single-threaded deadline poll (R2): we are the ONLY caller of waitpid on
-      # this pid, so we never reap-then-kill. We SIGKILL only after WNOHANG shows
-      # the child is still alive past the deadline — so the kill can never hit a
-      # reaped/recycled pid. Timeout is a parent-side fact (deadline reached), not
-      # status.signaled? (which is true for ANY signal death, e.g. SIGSEGV).
+      # Single-threaded deadline poll (R2): we are the ONLY caller of waitpid
+      # on this pid, so we never reap-then-kill. We SIGKILL only after WNOHANG
+      # shows the child is still alive past the deadline — so the kill can
+      # never hit a reaped/recycled pid. Timeout is a parent-side fact
+      # (deadline reached), not status.signaled? (which is true for ANY signal
+      # death, e.g. SIGSEGV).
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
       loop do
         reaped, status = Process.waitpid2(pid, Process::WNOHANG)
@@ -63,13 +69,19 @@ module Mutineer
     end
 
     # Strategy 7a (default): write the whole mutated file and `load` it, which
-    # reopens its classes and redefines every method in place. Re-runs file-level
-    # side effects. Child-only — mutates the loaded program.
+    # reopens its classes and redefines every method in place. Re-runs file-
+    # level side effects. Child-only — mutates the loaded program.
     #
     # The tempfile is created in the ORIGINAL file's directory, not the system
-    # temp dir, so any `require_relative` in the mutated source resolves against
-    # its real neighbours (e.g. a mutator's `require_relative "base"`). Writing it
-    # elsewhere makes those requires resolve to the temp dir and raise LoadError.
+    # temp dir, so any `require_relative` in the mutated source resolves
+    # against its real neighbours (e.g. a mutator's `require_relative
+    # "base"`). Writing it elsewhere makes those requires resolve to the temp
+    # dir and raise LoadError.
+    #
+    # @api private
+    # @param mutated [String] mutated source text.
+    # @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|
         f.write(mutated)
@@ -78,47 +90,69 @@ module Mutineer
       end
     end
 
-    # Redefine strategy: extract just the enclosing DefNode, apply the mutation to
-    # that snippet, wrap it in its real namespace, and `load` only that one method
-    # back into the running process. No file-level side effects re-run. Child-only.
+    # Redefine strategy: extract just the enclosing DefNode, apply the mutation
+    # to that snippet, wrap it in its real namespace, and `load` only that one
+    # method back into the running process. No file-level side effects re-run.
+    # Child-only.
     #
     # The snippet keeps its own `def self.x` for singletons, so the namespace
     # wrapper redefines instance and singleton methods correctly without any
     # special-casing.
+    #
+    # @api private
+    # @param mutation [Mutineer::Mutation] mutation to apply.
+    # @param subject [Mutineer::Subject] subject being mutated.
+    # @param source [String] full source text.
+    # @return [Object] whatever `load` returns.
     def self.apply_surgical(mutation, subject, source)
       loc = subject.def_node.location
       def_start = loc.start_offset
-      # Byte slicing (C1): Prism offsets are byte offsets.
       snippet = source.byteslice(def_start...loc.end_offset)
       rel_s = mutation.start_offset - def_start
       rel_e = mutation.end_offset - def_start
       mutated_def = snippet.byteslice(0...rel_s) + mutation.replacement + snippet.byteslice(rel_e..)
 
       # Rebuild the FULL namespace nesting textually so unqualified enclosing-
-      # 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).
+      # 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)
       prefix   = keywords.map { |kw, name| "#{kw} #{name}" }.join("\n")
       prefix  += "\n" unless prefix.empty?
-      wrapped  = "#{prefix}#{mutated_def}#{"\nend" * keywords.size}"
 
-      # A snippet that fails to reparse must NOT silently fall through to running
-      # the ORIGINAL method (C2 false-survived). Raise -> the fork block aborts
-      # before any test runs -> Result.error, never a bogus `survived`.
+      # #20: a singleton method whose def has NO `self.` receiver (the
+      # `class << self` and `module_function` forms) would, as a bare `def foo`
+      # inside `module Owner`, redefine the INSTANCE method — but the call
+      # (`Owner.foo`) dispatches to the singleton, so the mutant never runs and
+      # falsely survives. Re-open the singleton class so the redefinition lands on
+      # the same method the test calls. `def self.foo` already carries its
+      # receiver, so it is left as-is (wrapping it would mis-target).
+      inner =
+        if subject.singleton && subject.def_node.receiver.nil?
+          "class << self\n#{mutated_def}\nend"
+        else
+          mutated_def
+        end
+      wrapped = "#{prefix}#{inner}#{"\nend" * keywords.size}"
+
+      # A snippet that fails to reparse must NOT silently fall through to
+      # running the ORIGINAL method (C2 false-survived). Raise -> the fork
+      # block aborts before any test runs -> Result.error, never a bogus
+      # `survived`.
       raise "surgical snippet failed to reparse" if Parser.parse_string(wrapped).errors.any?
 
-      # Preserve original visibility — class/module bodies define methods public,
-      # but 7a's `load` would re-apply the file's private/protected (C2).
+      # Preserve original visibility — class/module bodies define methods
+      # public, but 7a's `load` would re-apply the file's private/protected
+      # (C2).
       owner  = subject.namespace.empty? ? Object : Object.const_get(subject.namespace.join("::"))
       target = subject.singleton ? owner.singleton_class : owner
       vis    = method_visibility(target, subject.name)
 
-      # Write the wrapped snippet to a tempfile and `load` it: `load` runs it at
-      # top level, so the textual class/module wrappers rebuild Module.nesting
-      # identically, with no dynamic string execution for scanners to flag. The
-      # input is the project's OWN source (the enclosing method, textually
-      # mutated), loaded only in this forked child.
+      # Write the wrapped snippet to a tempfile and `load` it: `load` runs it
+      # at top level, so the textual class/module wrappers rebuild
+      # Module.nesting identically, with no dynamic string execution for
+      # scanners to flag. The input is the project's OWN source (the enclosing
+      # method, textually mutated), loaded only in this forked child.
       Tempfile.create(["mutineer_surgical", ".rb"]) do |f|
         f.write(wrapped)
         f.flush
@@ -132,11 +166,15 @@ module Mutineer
     # keyword (reopening a class with `module` — or vice versa — raises
     # TypeError), so the textual wrapper matches the real definitions.
     #
-    # #5: a compact element like "Foo::Bar" stays a SINGLE wrapper `class Foo::Bar`
-    # (nesting [Foo::Bar]), matching how a whole-file load (reload) sees it.
-    # Splitting it into `module Foo; class Bar` gave nesting [Foo::Bar, Foo], so an
-    # unqualified constant defined only in Foo would resolve under redefine but not
-    # reload — a strategy disagreement.
+    # #5: a compact element like "Foo::Bar" stays a SINGLE wrapper `class Foo::
+    # Bar` (nesting [Foo::Bar]), matching how a whole-file load (reload) sees
+    # it. Splitting it into `module Foo; class Bar` gave nesting [Foo::Bar,
+    # Foo], so an unqualified constant defined only in Foo would resolve under
+    # redefine but not reload — a strategy disagreement.
+    #
+    # @api private
+    # @param namespace [Array<String>] namespace components.
+    # @return [Array<[String, String]>] wrapper keywords and names.
     def self.nesting_keywords(namespace)
       mod = Object
       namespace.map do |name|
@@ -145,6 +183,12 @@ module Mutineer
       end
     end
 
+    # Returns the visibility for a method name.
+    #
+    # @api private
+    # @param mod [Module] module or class being inspected.
+    # @param name [Symbol] method name.
+    # @return [Symbol, nil] `:public`, `:protected`, `:private`, or nil.
     def self.method_visibility(mod, name)
       return :private   if mod.private_method_defined?(name)
       return :protected if mod.protected_method_defined?(name)
@@ -153,6 +197,11 @@ module Mutineer
       nil
     end
 
+    # Decodes a child status into a Result.
+    #
+    # @api private
+    # @param status [Process::Status] child exit status.
+    # @return [Mutineer::Result] decoded result.
     def self.decode(status)
       case status.exitstatus
       when 0 then Result.survived

data/lib/mutineer/minitest_integration.rb

@@ -11,18 +11,19 @@ module Mutineer
   # (autorun, runnables) that only makes sense in a throwaway forked child.
   #
   # No `rescue` here: Isolation.run's fork block is the single exception
-  # boundary (any exception there becomes exit 2). Adding a rescue would create
-  # a second exit-2 path and break this method's 0/1 return contract.
+  # boundary (any exception there becomes exit 2). Adding a rescue would
+  # create a second exit-2 path and break this method's 0/1 return contract.
   class MinitestIntegration
     # ponytail: tested via runner_test.rb (U6), not in isolation — a direct
     # unit test would require forking and duplicate isolation_test's coverage.
     #
-    # `test_files` is one path or an Array of paths (M3 coverage selection passes
-    # the covering subset); each is loaded before the single Minitest.run.
+    # `test_files` is one path or an Array of paths (M3 coverage selection
+    # passes the covering subset); each is loaded before the single
+    # Minitest.run.
+    #
+    # @param test_files [String, Array<String>] one file or many files.
+    # @return [Integer] 0 on success, 1 on failure.
     def self.run(test_files)
-      # minitest is required LAZILY (never at load time) so Mutineer keeps zero
-      # runtime gem deps and loads fine in an rspec-only project; a missing
-      # minitest raises a clear Mutineer error rather than a LoadError backtrace.
       begin
         require "minitest"
       rescue LoadError
@@ -31,6 +32,10 @@ module Mutineer
               "or use --framework rspec"
       end
 
+      # minitest is required LAZILY (never at load time) so Mutineer keeps
+      # zero runtime gem deps and loads fine in an rspec-only project; a missing
+      # minitest raises a clear Mutineer error rather than a LoadError backtrace.
+
       # Neutralise autorun so a test file's `require "minitest/autorun"`
       # registers no at_exit hook.
       def Minitest.autorun; end # rubocop:disable Lint/NestedMethodDefinition
@@ -38,11 +43,10 @@ module Mutineer
       # Drop runnables inherited from the parent suite (this is the child's
       # private copy — the parent is unaffected) so only the target test runs.
       Minitest::Runnable.reset
-
       Array(test_files).each { |f| load f }
 
-      # Silence the child's test output; the parent only cares about pass/fail.
       orig = $stdout
+      # Silence the child's test output; the parent only cares about pass/fail.
       $stdout = StringIO.new
       passed = Minitest.run([])
       $stdout = orig

data/lib/mutineer/mutant_id.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Mutineer
+  # Content-based stable 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.
+  module MutantId
+    module_function
+
+    # Computes the stable id for a single mutant.
+    #
+    # NUL-joined so token delimiters (`||=`, spaces, `::`, `#`) can never collide
+    # with the separator; SHA256[0,12] gives a fixed-length, copy-pasteable key.
+    #
+    # @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.
+    # @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 twins sharing the same
+    #   (operator, token) within the subject, disambiguating otherwise-identical mutants.
+    # @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]
+    end
+
+    # Computes ids for a subject's full mutation list, in input order, assigning
+    # each its 0-based occurrence among twins sharing the same (operator, token).
+    # This is what disambiguates `a + b + c`'s two `+` mutants without an offset.
+    #
+    # @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 12-character id per mutation, positionally aligned.
+    def for_subject(subject, source, mutations)
+      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)
+      end
+    end
+
+    # Extracts the exact code being mutated, whitespace-collapsed — the same
+    # normalization the Reporter's `diff_for` uses for its token label.
+    #
+    # @param mutation [Mutineer::Mutation] supplies the byte range to slice.
+    # @param source [String] the source to byteslice (byte offsets, never char).
+    # @return [String] the mutated token with runs of whitespace collapsed to one space.
+    def normalized_token(mutation, source)
+      source.byteslice(mutation.start_offset...mutation.end_offset).gsub(/\s+/, " ").strip
+    end
+  end
+end