mutineer 1.4.0 → 1.5.0

data/lib/mutineer/minitest_integration/outer_reporter.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Mutineer
+  class MinitestIntegration
+    # Finds the outer reporter of a Minitest run, for the hooks that act only on
+    # the run's own results. A test can build a reporter of its own and record
+    # on it, or start a nested run, so the first reporter the run hands to its
+    # suites is the one that counts. Child-process only, like
+    # MinitestIntegration.
+    #
+    # A client module extends {Client}, registers here, and sets its armed pid.
+    # The hook then gives the outer reporter to each client armed in this
+    # process. Minitest 5 and 6 need different hook points; an unknown shape
+    # gets no hook.
+    module OuterReporter
+      # Prepended on the `Minitest` singleton class for Minitest 6.
+      module Hook6
+        # Hands the outer reporter to the armed clients. Only the first call
+        # counts, because a test can call this method with its own reporter.
+        #
+        # @param reporter [Minitest::CompositeReporter] the outer reporter.
+        # @param options [Hash] the Minitest options.
+        # @return [Object] whatever Minitest returns.
+        def run_all_suites(reporter, options)
+          OuterReporter.seen(reporter)
+          super
+        end
+      end
+
+      # Prepended on the `Minitest` singleton class for Minitest 5.
+      module Hook5
+        # The Minitest 5 form of Hook6#run_all_suites.
+        #
+        # @param reporter [Minitest::CompositeReporter] the outer reporter.
+        # @param options [Hash] the Minitest options.
+        # @return [Object] whatever Minitest returns.
+        def __run(reporter, options)
+          OuterReporter.seen(reporter)
+          super
+        end
+      end
+
+      # The per-process state a client keeps. Forked workers inherit it, and
+      # the pid keeps them from acting on it.
+      module Client
+        # The pid of the armed process.
+        #
+        # @return [Integer, nil]
+        attr_accessor :armed_pid
+
+        # The outer reporter of the armed run.
+        #
+        # @return [Minitest::CompositeReporter, nil]
+        attr_accessor :armed_reporter
+
+        # True when the client is armed in this process.
+        #
+        # @return [Boolean]
+        def armed_here?
+          armed_pid == Process.pid
+        end
+
+        # True when `reporter` is the outer reporter of the run armed in this
+        # process.
+        #
+        # @param reporter [Minitest::CompositeReporter] the recording reporter.
+        # @return [Boolean]
+        def outer_reporter?(reporter)
+          armed_here? && reporter.equal?(armed_reporter)
+        end
+      end
+
+      class << self
+        # The registered clients, in registration order.
+        #
+        # @return [Array<Module>]
+        def clients
+          @clients ||= []
+        end
+
+        # Registers a client once.
+        #
+        # @param client [Module] a module that extends {Client}.
+        # @return [void]
+        def register(client)
+          clients << client unless clients.include?(client)
+        end
+
+        # Gives `reporter` to every client armed in this process that has no
+        # outer reporter yet.
+        #
+        # @param reporter [Minitest::CompositeReporter] a reporter a run uses.
+        # @return [void]
+        def seen(reporter)
+          clients.each do |client|
+            client.armed_reporter ||= reporter if client.armed_here?
+          end
+        end
+
+        # The outer-reporter hook for the loaded Minitest.
+        #
+        # @return [Module, nil] {Hook6}, {Hook5}, or nil for an unknown shape.
+        def hook_for_loaded_minitest
+          runnable = ::Minitest::Runnable
+          if ::Minitest.respond_to?(:run_all_suites) && runnable.respond_to?(:run_suite)
+            Hook6
+          elsif ::Minitest.respond_to?(:__run) && runnable.respond_to?(:run_one_method)
+            Hook5
+          end
+        end
+
+        # Prepends `mod` on `target` once. A copy on a superclass does not
+        # count, because it comes after the own methods of `target`.
+        #
+        # @param target [Module] the class or singleton class.
+        # @param mod [Module] the module to prepend.
+        # @return [void]
+        def prepend_once(target, mod)
+          return if target.ancestors.take_while { |a| !a.equal?(target) }.include?(mod)
+
+          target.prepend(mod)
+        end
+      end
+    end
+  end
+end

data/lib/mutineer/minitest_integration/stop_at_first_failure.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "outer_reporter"
+
 module Mutineer
   class MinitestIntegration
     # Stops a Minitest run at the first failing test: one failure already
@@ -10,8 +12,11 @@ module Mutineer
     # remaining tests and classes then return before they start.
     #
     # Minitest 5 and 6 need different hook points. An unknown shape installs
-    # no hook, and the run is a full run.
+    # no hook, and the run is a full run. The outer reporter comes from
+    # {OuterReporter}, shared with {KillRecorder}.
     module StopAtFirstFailure
+      extend OuterReporter::Client
+
       # Prepended on `Minitest::CompositeReporter`.
       module RecordFailure
         # Records the result, then sets the stop flag on a failure or an
@@ -23,40 +28,12 @@ module Mutineer
         def record(result)
           super
           return if result.passed? || result.skipped?
-          return unless equal?(StopAtFirstFailure.armed_reporter)
-          return unless StopAtFirstFailure.armed_here?
+          return unless StopAtFirstFailure.outer_reporter?(self)
 
           StopAtFirstFailure.stopped = true
         end
       end
 
-      # Prepended on the `Minitest` singleton class for Minitest 6.
-      module OuterReporter6
-        # Keeps the outer reporter. Only the first call counts, because a test
-        # can call this method with its own reporter.
-        #
-        # @param reporter [Minitest::CompositeReporter] the outer reporter.
-        # @param options [Hash] the Minitest options.
-        # @return [Object] whatever Minitest returns.
-        def run_all_suites(reporter, options)
-          StopAtFirstFailure.armed_reporter ||= reporter if StopAtFirstFailure.armed_here?
-          super
-        end
-      end
-
-      # Prepended on the `Minitest` singleton class for Minitest 5.
-      module OuterReporter5
-        # The Minitest 5 form of OuterReporter6#run_all_suites.
-        #
-        # @param reporter [Minitest::CompositeReporter] the outer reporter.
-        # @param options [Hash] the Minitest options.
-        # @return [Object] whatever Minitest returns.
-        def __run(reporter, options)
-          StopAtFirstFailure.armed_reporter ||= reporter if StopAtFirstFailure.armed_here?
-          super
-        end
-      end
-
       # Prepended on the singleton class of each test class for Minitest 6.
       module SkipAfterStop6
         # Skips the test class after a stop.
@@ -110,17 +87,6 @@ module Mutineer
       end
 
       class << self
-        # The pid of the armed process. Forked workers inherit the other
-        # state, and the pid keeps them from acting on it.
-        #
-        # @return [Integer, nil]
-        attr_accessor :armed_pid
-
-        # The outer reporter of the armed run.
-        #
-        # @return [Minitest::CompositeReporter, nil]
-        attr_accessor :armed_reporter
-
         # True after the outer reporter records a failure or an error.
         #
         # @return [Boolean, nil]
@@ -135,9 +101,10 @@ module Mutineer
           outer, skip = hooks_for_loaded_minitest
           return false unless outer
 
-          prepend_once(::Minitest::CompositeReporter, RecordFailure)
-          prepend_once(::Minitest.singleton_class, outer)
-          runnables.each { |klass| prepend_once(klass.singleton_class, skip) }
+          OuterReporter.prepend_once(::Minitest::CompositeReporter, RecordFailure)
+          OuterReporter.prepend_once(::Minitest.singleton_class, outer)
+          runnables.each { |klass| OuterReporter.prepend_once(klass.singleton_class, skip) }
+          OuterReporter.register(self)
           self.armed_pid = Process.pid
           self.armed_reporter = nil
           self.stopped = false
@@ -153,13 +120,6 @@ module Mutineer
           self.stopped = false
         end
 
-        # True when the run is armed in this process.
-        #
-        # @return [Boolean]
-        def armed_here?
-          armed_pid == Process.pid
-        end
-
         # True when the armed run in this process has stopped.
         #
         # @return [Boolean]
@@ -174,25 +134,11 @@ module Mutineer
         # @return [Array(Module, Module), nil] the outer reporter hook and the
         #   skip hook, or nil for an unknown shape.
         def hooks_for_loaded_minitest
-          runnable = ::Minitest::Runnable
-          if ::Minitest.respond_to?(:run_all_suites) && runnable.respond_to?(:run_suite)
-            [OuterReporter6, SkipAfterStop6]
-          elsif ::Minitest.respond_to?(:__run) && runnable.respond_to?(:run_one_method)
-            [OuterReporter5, SkipAfterStop5]
+          outer = OuterReporter.hook_for_loaded_minitest
+          if outer.equal?(OuterReporter::Hook6) then [outer, SkipAfterStop6]
+          elsif outer.equal?(OuterReporter::Hook5) then [outer, SkipAfterStop5]
           end
         end
-
-        # Prepends `mod` on `target` once. A copy on a superclass does not
-        # count, because it comes after the own methods of `target`.
-        #
-        # @param target [Module] the class or singleton class.
-        # @param mod [Module] the module to prepend.
-        # @return [void]
-        def prepend_once(target, mod)
-          return if target.ancestors.take_while { |a| !a.equal?(target) }.include?(mod)
-
-          target.prepend(mod)
-        end
       end
     end
   end

data/lib/mutineer/minitest_integration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "minitest_integration/stop_at_first_failure"
+require_relative "minitest_integration/kill_recorder"
 
 module Mutineer
   # Child-process-only: loads a test file in the current process and runs it
@@ -16,9 +17,11 @@ module Mutineer
   # boundary for unexpected errors. Swallowing those here would create a
   # second exit-2 path and break this method's 0/1 return contract.
   class MinitestIntegration
-    # The seed of a run that stops at the first failure, unless `SEED` is set.
-    # With the stop, the test order can decide `killed` vs `timeout`; a fixed
-    # order keeps the verdict stable for a `--baseline` gate.
+    # The seed of a mutant run (one that stops at the first failure, or a
+    # `--matrix` run that records every test), unless `SEED` is set. With the
+    # stop, the test order can decide `killed` vs `timeout`; a fixed order keeps
+    # the verdict stable for a `--baseline` gate. A matrix run uses the same
+    # order, so its first failure comes at the same point as the stop's.
     STOP_AT_FIRST_FAILURE_SEED = 1
 
     # Tested via runner_test.rb, not in isolation — a direct unit test
@@ -31,8 +34,15 @@ module Mutineer
     # @param test_files [String, Array<String>] one file or many files.
     # @param stop_at_first_failure [Boolean] end the run at the first failing
     #   test. Only the mutant path passes true.
+    # @param record_to [IO, nil] a `--matrix` run: send each test's outcome to
+    #   this channel (see {KillRecorder}) and run every test.
     # @return [Integer] 0 on success, 1 on failure.
-    def self.run(test_files, stop_at_first_failure: false)
+    # @raise [ArgumentError] when both options are given: a matrix run never stops.
+    def self.run(test_files, stop_at_first_failure: false, record_to: nil)
+      if stop_at_first_failure && record_to
+        raise ArgumentError, "stop_at_first_failure and record_to cannot be combined: a matrix run runs every test"
+      end
+
       begin
         require "minitest"
       rescue LoadError
@@ -54,20 +64,27 @@ module Mutineer
       Minitest::Runnable.reset
       Array(test_files).each { |f| load f }
 
-      args = []
-      if stop_at_first_failure && StopAtFirstFailure.arm!(Minitest::Runnable.runnables)
-        # Pin the seed only when the stop is armed; an unknown Minitest shape
-        # gets the normal full, randomly ordered run.
-        args = ["--seed", STOP_AT_FIRST_FAILURE_SEED.to_s] unless ENV["SEED"]
-      end
+      armed =
+        if record_to
+          KillRecorder.arm!(record_to, Minitest::Runnable.runnables)
+        elsif stop_at_first_failure
+          StopAtFirstFailure.arm!(Minitest::Runnable.runnables)
+        end
+      # Pin the seed only when a hook is armed; an unknown Minitest shape gets
+      # the normal full, randomly ordered run.
+      args = armed && !ENV["SEED"] ? ["--seed", STOP_AT_FIRST_FAILURE_SEED.to_s] : []
       # No silencing here: the fork boundary that calls this method has already
       # pointed stdout at File::NULL (see ChildStdout).
       passed = Minitest.run(args)
+      # Reached only when the suite returned: a test that exits the process
+      # skips it, and the parent then keeps the row incomplete.
+      KillRecorder.finish! if record_to
 
       # A plugin can replace the summary reporter, so a stop decides by itself.
       passed && !StopAtFirstFailure.stopped_here? ? 0 : 1
     ensure
       StopAtFirstFailure.disarm!
+      KillRecorder.disarm!
     end
   end
 end

data/lib/mutineer/mutant_id.rb

@@ -12,9 +12,9 @@ module Mutineer
   # 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.
+  # same-named subjects in its file. Unrelated edits that only shift byte offsets
+  # can preserve the id. File moves, renames, project-root changes, and changes to
+  # repeated-name or repeated-mutation order can change it.
   module MutantId
     module_function
 
@@ -38,7 +38,8 @@ module Mutineer
     #   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.
+    # @return [String] a 12-character hex id, stable while its keyed identity and
+    #   occurrence order stay unchanged.
     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?

data/lib/mutineer/mutators/array_literal.rb

@@ -19,13 +19,6 @@ module Mutineer
         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.

data/lib/mutineer/mutators/base.rb

@@ -11,9 +11,6 @@ module Mutineer
     # Subclasses override `visit_*` methods to push `Mutation` objects onto
     # `@mutations`. Visiting only `def_node.body` is the body-only enforcement:
     # the def signature line is never touched.
-    #
-    # ponytail: one implementor in M1; Base earns its keep at M4 when
-    # comparison/boolean operators land and share this contract.
     class Base < Prism::Visitor
       # Walks the subject body and collects mutations.
       #
@@ -23,12 +20,74 @@ module Mutineer
       def mutations_for(subject, source)
         @source = source
         @mutations = []
-        subject.def_node.body&.accept(self)
+        @body = subject.def_node.body
+        @body&.accept(self)
+        drop_dangling_heredocs
         @mutations
       end
 
+      # Skips a nested method definition. The project finds it as a subject of
+      # its own, so a visit here counts its mutations twice. Inside
+      # `class << obj`, the project finds no subject, so the visit continues.
+      #
+      # @param node [Prism::DefNode] nested definition node.
+      # @return [void]
+      def visit_def_node(node)
+        super if @in_undiscovered
+      end
+
+      # Tracks a `class << obj` whose `obj` is not `self`. The project does not
+      # recurse into it, so its defs are no subjects (see
+      # `Project::SubjectVisitor#visit_singleton_class_node`).
+      #
+      # @param node [Prism::SingletonClassNode] singleton-class node.
+      # @return [void]
+      def visit_singleton_class_node(node)
+        return super if node.expression.is_a?(Prism::SelfNode)
+
+        outer, @in_undiscovered = @in_undiscovered, true
+        super
+        @in_undiscovered = outer
+      end
+
       private
 
+      # Drops a mutation that deletes a heredoc opener and leaves its body.
+      #
+      # The body sits past the opener's node. Replacing the opener with text
+      # that does not contain it turns the body into Ruby, which parses and
+      # then raises. A replacement that still contains the opener keeps the
+      # body attached, so that mutation stays.
+      #
+      # @return [void]
+      def drop_dangling_heredocs
+        @mutations.reject! { |mutation| dangling_heredoc?(mutation) }
+      end
+
+      # Returns whether the mutation removes a heredoc opener whose body hangs
+      # past the replaced range.
+      #
+      # @param mutation [Mutineer::Mutation] candidate edit.
+      # @param node [Prism::Node, nil] subtree to search. Defaults to the body.
+      # @return [Boolean] true when the edit would leave a heredoc body behind.
+      def dangling_heredoc?(mutation, node = @body)
+        return false if node.nil? || !node.is_a?(Prism::Node)
+
+        if node.respond_to?(:heredoc?) && node.heredoc? && node.respond_to?(:opening_loc)
+          opening = node.opening_loc
+          if opening && opening.start_offset >= mutation.start_offset && opening.start_offset < mutation.end_offset
+            closing = node.respond_to?(:closing_loc) ? node.closing_loc : nil
+            hangs = closing.nil? || closing.end_offset > mutation.end_offset
+            if hangs
+              opener = @source.byteslice(opening.start_offset, opening.end_offset - opening.start_offset)
+              return true if opener.empty? || !mutation.replacement.include?(opener)
+            end
+          end
+        end
+
+        node.compact_child_nodes.any? { |child| dangling_heredoc?(mutation, child) }
+      end
+
       # Returns whether a node is, or contains, a heredoc.
       #
       # A heredoc's body lies outside its node's byte range. A mutation that

data/lib/mutineer/mutators/chain_link.rb

@@ -88,13 +88,6 @@ module Mutineer
         super
       end
 
-      # Nested method definitions are discovered as their own subjects; do not
-      # recurse into them (prevents double-counting their chains).
-      #
-      # @param node [Prism::DefNode] nested definition node.
-      # @return [void]
-      def visit_def_node(node); end
-
       private
 
       # Walks a final call's receiver chain, recording each link so it is not

data/lib/mutineer/mutators/collection_method.rb

@@ -12,7 +12,7 @@ module Mutineer
       # Method-name swaps. All targets are core-Ruby Enumerable/Array methods so
       # the mutant exercises real behaviour rather than always raising.
       #
-      # ponytail: include? -> exclude? was specced but skipped — exclude? is not
+      # include? -> exclude? is left out: exclude? is not
       # core Ruby, so that mutant would always NoMethodError (a weak mutant).
       REPLACEMENTS = {
         map: "each", each: "map",

data/lib/mutineer/mutators/condition_forcing.rb

@@ -50,13 +50,6 @@ module Mutineer
         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

data/lib/mutineer/mutators/operand_removal.rb

@@ -33,13 +33,6 @@ module Mutineer
         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

data/lib/mutineer/mutators/operator_assignment.rb

@@ -90,13 +90,6 @@ module Mutineer
         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.

data/lib/mutineer/mutators/return_nil.rb

@@ -16,11 +16,12 @@ module Mutineer
       def mutations_for(subject, source)
         @source = source
         @mutations = []
-        body = subject.def_node.body
-        if body
-          body.accept(self)       # rule 1 (explicit return nodes in this body)
-          final_expression_nil(body) # rule 2 (method's final expression)
+        @body = subject.def_node.body
+        if @body
+          @body.accept(self)       # rule 1 (explicit return nodes in this body)
+          final_expression_nil(@body) # rule 2 (method's final expression)
         end
+        drop_dangling_heredocs
         @mutations
       end
 
@@ -39,13 +40,6 @@ module Mutineer
         super
       end
 
-      # Nested method definitions are discovered as their own subjects; do not
-      # recurse into them (prevents double-counting their statements).
-      #
-      # @param node [Prism::DefNode] nested definition node.
-      # @return [void]
-      def visit_def_node(node); end
-
       private
 
       # Mutates a method's final expression to nil when eligible.

data/lib/mutineer/mutators/string_literal.rb

@@ -15,7 +15,7 @@ module Mutineer
       # @param node [Prism::StringNode] node to inspect.
       # @return [void]
       def visit_string_node(node)
-        # ponytail: only plain "..." / '...' quotes. opening is nil for
+        # Only plain "..." / '...' quotes. opening is nil for
         # interpolation parts and %w[] elements; heredocs/%-literals use a
         # different opening token. Skipping them keeps mutants re-parseable.
         if %w[" '].include?(node.opening)