mutineer 0.7.0 → 0.9.0

data/lib/mutineer/subject.rb

@@ -1,17 +1,21 @@
 # frozen_string_literal: true
 
 module Mutineer
-  # One discoverable method: its location, namespace context, and the live
-  # Prism::DefNode mutators walk. Struct (not Data) because def_node is a live
-  # AST node — value-equality would be hollow, so we don't promise it.
+  # One discoverable method and its AST node.
+  #
+  # Location, namespace context, and the live Prism::DefNode are kept together
+  # because mutators walk the def node directly.
   Subject = Struct.new(:file, :namespace, :name, :singleton, :def_node, keyword_init: true) do
-    # e.g. "Billing::Invoice#total", "Billing::Invoice.build".
-    # Top-level (empty namespace) -> "#name" (no :: prefix).
+    # Returns the fully-qualified subject name.
+    #
+    # @return [String] namespaced method name like `Billing::Invoice#total`.
     def qualified_name
       namespace.join("::") + (singleton ? "." : "#") + name.to_s
     end
 
-    # nil for empty methods (def empty; end).
+    # Returns the body location for the subject, if any.
+    #
+    # @return [Prism::Location, nil] body location or nil for empty methods.
     def body_loc
       def_node.body&.location
     end

data/lib/mutineer/test_runners/minitest.rb

@@ -4,11 +4,12 @@ require_relative "../minitest_integration"
 
 module Mutineer
   module TestRunners
-    # Uniform wrapper over the existing MinitestIntegration impl so the runner
-    # selection (TestRunners.for) has one method shape across frameworks.
-    # MinitestIntegration stays the implementation — all its behaviour (autorun
-    # neutralisation, Runnable.reset, load, Minitest.run -> 0/1) is preserved.
+    # Thin wrapper around the shared Minitest integration runner.
     module Minitest
+      # Runs the given Minitest files.
+      #
+      # @param test_files [String, Array<String>] one file or many files.
+      # @return [Integer] 0 on success, 1 on failure.
       def self.run(test_files) = MinitestIntegration.run(test_files)
     end
   end

data/lib/mutineer/test_runners/rspec.rb

@@ -8,31 +8,21 @@ module Mutineer
   class FrameworkUnavailable < StandardError; end
 
   module TestRunners
-    # Child-process-only RSpec runner, mirroring MinitestIntegration's contract:
-    # run the given spec files and return 0 (all passed) / 1 (any failure).
+    # Child-process-only RSpec runner.
     #
-    # rspec-core is required LAZILY here, never at load time, so Mutineer keeps
-    # zero runtime gem deps; a missing rspec raises a clear Mutineer error.
-    #
-    # No `rescue` around the run itself: Isolation.run's fork block is the single
-    # exception boundary (any exception there -> exit 2), keeping the 0/1 contract.
+    # Mirrors MinitestIntegration's contract: run the given spec files and
+    # return 0 (all passed) or 1 (any failure).
     module RSpec
-      # `spec_files` is one path or an Array of paths (coverage selection passes
-      # the covering subset). All are loaded+run in a single RSpec invocation.
+      # Runs the given RSpec files.
+      #
+      # @param spec_files [String, Array<String>] one file or many files.
+      # @return [Integer] 0 on success, 1 on failure.
       def self.run(spec_files)
         require_rspec!
 
-        # rspec/autorun (if a spec_helper required it) installs an at_exit run;
-        # neutralise it like Minitest.autorun so it never double-fires.
         ::RSpec::Core::Runner.disable_autorun!
-
-        # Drop any RSpec world/configuration inherited across runs in one process
-        # (e.g. successive forks of a booted parent) so examples never accumulate.
         ::RSpec.reset
 
-        # Silence RSpec's formatter output (and any stray puts/deprecations) so it
-        # never pollutes Mutineer's report streams. The formatter writes to the
-        # passed IO; $stdout/$stderr are redirected to catch everything else.
         sink = StringIO.new
         orig_out = $stdout
         orig_err = $stderr
@@ -48,6 +38,9 @@ module Mutineer
         status.zero? ? 0 : 1
       end
 
+      # Requires rspec-core from the project under test.
+      #
+      # @api private
       def self.require_rspec!
         require "rspec/core"
       rescue LoadError

data/lib/mutineer/test_runners.rb

@@ -4,9 +4,16 @@ require_relative "test_runners/minitest"
 require_relative "test_runners/rspec"
 
 module Mutineer
-  # Picks the test-framework runner. Each runner responds to `.run(files) -> 0/1`
-  # (0 = all passed, 1 = any failure) and is called only inside a forked child.
+  # Picks the test-framework runner.
+  #
+  # Each runner responds to `.run(files) -> 0/1` (0 = all passed, 1 = any
+  # failure) and is called only inside a forked child.
   module TestRunners
+    # Returns the runner module for a framework name.
+    #
+    # @param framework [String, nil] framework name or nil.
+    # @return [Module] `Mutineer::TestRunners::Minitest` or `::RSpec`.
+    # @raise [Mutineer::ConfigError] when the framework is unknown.
     def self.for(framework)
       case framework
       when "rspec" then RSpec

data/lib/mutineer/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Mutineer
-  VERSION = "0.7.0"
+  # Current Mutineer release version.
+  VERSION = "0.9.0"
 end

data/lib/mutineer/worker_pool.rb

@@ -3,29 +3,47 @@
 require_relative "result"
 
 module Mutineer
-  # Fixed-size fork pool (KTD1/KTD2). `run` forks up to `size` children at once;
-  # each child runs the block on one work item, marshals its Result to a private
-  # pipe, and exits. The parent reaps any finished child with Process.wait2(-1),
-  # opening exactly one slot per reap, then refills. Results are returned in the
-  # SAME ORDER as `items` regardless of finish order, so verdicts are identical to
-  # a serial run (R4) and downstream output is stable.
+  # Fixed-size fork pool (KTD1/KTD2). `run` forks up to `size` children at
+  # once; each child runs the block on one work item, marshals its Result to a
+  # private pipe, and exits. The parent reaps any finished child with
+  # Process.wait2(-1), opening exactly one slot per reap, then refills.
+  # Results are returned in the SAME ORDER as `items` regardless of finish
+  # order, so verdicts are identical to a serial run (R4) and downstream output
+  # is stable.
   #
   # The block is run inside the child via `yield(*items[i])`; whatever it
-  # returns (a Result) is the marshaled payload. Per-mutant timeout is handled one
-  # level down by Isolation (KTD2) — the pool adds no separate wall clock.
+  # returns (a Result) is the marshaled payload. Per-mutant timeout is handled
+  # one level down by Isolation (KTD2) — the pool adds no separate wall clock.
   class WorkerPool
+    # Builds a pool.
+    #
+    # @param size [Integer] desired pool size.
     def initialize(size)
       @size = [size.to_i, 1].max
     end
 
-    def run(items)
-      results = Array.new(items.size)
-      queue   = (0...items.size).to_a
-      running = {} # pid => [index, read_io]
+    # Runs the work items through the pool.
+    #
+    # @param items [Array<Array>] work items.
+    # @param stop_when [Proc, nil] called with each collected Result; when it
+    #   returns truthy, no further items are scheduled and the run drains and
+    #   returns early (#21 --fail-fast). Unscheduled slots stay nil.
+    # @yieldparam item [Array] one work item.
+    # @return [Array<Mutineer::Result>] results in input order (nil for any item
+    #   left unscheduled by an early stop).
+    def run(items, stop_when: nil)
+      results  = Array.new(items.size)
+      queue    = (0...items.size).to_a
+      running  = {} # pid => [index, read_io, buffer]
+      stopping = false
 
       until queue.empty? && running.empty?
-        fill(items, queue, running) { |*args| yield(*args) }
-        reap(results, running)
+        fill(items, queue, running) { |*args| yield(*args) } unless stopping
+        result = reap(results, running)
+        if !stopping && stop_when && result && stop_when.call(result)
+          stopping = true
+          queue.clear # schedule no more; let in-flight workers drain
+        end
       end
 
       results
@@ -33,17 +51,19 @@ module Mutineer
 
     private
 
+    # R1: the child must ALWAYS hard-exit. If yield raises, marshal an error
+    # Result and exit! in `ensure` — otherwise the child unwinds normally and
+    # our Minitest at_exit autorun re-runs the parent suite inside the worker,
+    # losing the real error.
     def fill(items, queue, running)
       while running.size < @size && !queue.empty?
         idx = queue.shift
         rd, wr = IO.pipe
+        rd.binmode # #19: Marshal output is binary — keep the pipe byte-exact
+        wr.binmode
         begin
           pid = fork do
             rd.close
-            # R1: the child must ALWAYS hard-exit. If yield raises, marshal an
-            # error Result and exit! in `ensure` — otherwise the child unwinds
-            # normally and our Minitest at_exit autorun re-runs the parent suite
-            # inside the worker, losing the real error.
             payload =
               begin
                 yield(*items[idx])
@@ -74,13 +94,13 @@ module Mutineer
       end
     end
 
-    # Drain pipes with IO.select and reap a child only on EOF (#4). The old code
-    # reaped first and read after — but a child whose payload exceeds the OS pipe
-    # buffer (~64KB) blocks on `write` before it can exit, so it was never reaped
-    # and the pool deadlocked. Reading concurrently keeps the pipe drained so the
-    # child can finish and exit; EOF means it closed its write end (done writing).
-    # We waitpid only OUR known pids (R6: never wait2(-1), which would steal the
-    # host suite's children).
+    # Drain pipes with IO.select and reap a child only on EOF (#4). The old
+    # code reaped first and read after — but a child whose payload exceeds the
+    # OS pipe buffer (~64KB) blocks on `write` before it can exit, so it was
+    # never reaped and the pool deadlocked. Reading concurrently keeps the
+    # pipe drained so the child can finish and exit; EOF means it closed its
+    # write end (done writing). We waitpid only OUR known pids (R6: never
+    # wait2(-1), which would steal the host suite's children).
     def reap(results, running)
       return if running.empty?
 
@@ -96,19 +116,21 @@ module Mutineer
             rd.close
             Process.waitpid(pid) # reap the now-finished child (no zombie)
             running.delete(pid)
-            results[idx] = decode(buf)
-            return
+            # Return the collected Result so the caller's stop_when (#21) can see it.
+            return results[idx] = decode(buf)
           end
           buf << chunk
         end
       end
     end
 
+    # R6: a partial/garbage Marshal stream (dead worker) must not crash the
+    # pool — degrade to an error Result.
+    # @param data [String] marshaled payload.
+    # @return [Mutineer::Result] decoded result or error result.
     def decode(data)
       return Result.error("worker produced no result") if data.empty?
 
-      # R6: a partial/garbage Marshal stream (dead worker) must not crash the
-      # pool — degrade to an error Result.
       Marshal.load(data)
     rescue StandardError => e
       Result.error("worker result unreadable: #{e.class}: #{e.message}")

data/lib/mutineer.rb

@@ -22,6 +22,9 @@ require_relative "mutineer/mutators/statement_removal"
 require_relative "mutineer/mutators/return_nil"
 require_relative "mutineer/mutators/literal_mutation"
 require_relative "mutineer/mutators/condition_negation"
+require_relative "mutineer/mutators/string_literal"
+require_relative "mutineer/mutators/regex_literal"
+require_relative "mutineer/mutators/collection_method"
 require_relative "mutineer/mutator_registry"
 require_relative "mutineer/worker_pool"
 require_relative "mutineer/runner"
@@ -29,5 +32,6 @@ require_relative "mutineer/reporter"
 require_relative "mutineer/baseline"
 require_relative "mutineer/cli"
 
+# Mutineer is the top-level namespace for the mutation-testing library.
 module Mutineer
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutineer
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - David Teren
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: Mutineer mutates your source one change at a time and runs your Minitest
   suite against each mutant to find tests that don't actually test anything. Prism-based,
   fork-isolated, zero runtime dependencies.
@@ -66,11 +80,14 @@ files:
 - lib/mutineer/mutators/base.rb
 - lib/mutineer/mutators/boolean_connector.rb
 - lib/mutineer/mutators/boolean_literal.rb
+- lib/mutineer/mutators/collection_method.rb
 - lib/mutineer/mutators/comparison.rb
 - lib/mutineer/mutators/condition_negation.rb
 - lib/mutineer/mutators/literal_mutation.rb
+- lib/mutineer/mutators/regex_literal.rb
 - lib/mutineer/mutators/return_nil.rb
 - lib/mutineer/mutators/statement_removal.rb
+- lib/mutineer/mutators/string_literal.rb
 - lib/mutineer/pairing.rb
 - lib/mutineer/parser.rb
 - lib/mutineer/project.rb