mutineer 0.7.0 → 0.8.0

data/lib/mutineer/result.rb

@@ -8,90 +8,154 @@ module Mutineer
   #   timeout      — the parent SIGKILLed a child that overran its wall clock.
   #   skipped      — the mutated source failed to re-parse (invalid); no fork.
   #   no_coverage  — no test exercises the mutated line; not run, not scored.
-  #   uncapturable — the line's would-be covering test errored during capture (#9),
-  #                  so coverage was lost. Excluded from the denominator exactly
-  #                  like no_coverage, but reported separately: it signals a broken
-  #                  harness (a test that failed to run), not a genuine coverage gap.
-  #   ignored      — a known-equivalent mutant the user suppressed (#10), via an
-  #                  inline `# mutineer:disable-line` comment or a `.mutineer.yml`
-  #                  `ignore:` id. A pre-fork classification (never run); excluded
-  #                  from the denominator so a strong file can reach 100%.
+  #   uncapturable — the line's would-be covering test errored during capture
+  #                  (#9), so coverage was lost. Excluded from the
+  #                  denominator exactly like no_coverage, but reported
+  #                  separately: it signals a broken harness (a test that
+  #                  failed to run), not a genuine coverage gap.
+  #   ignored      — a known-equivalent mutant the user suppressed (#10), via
+  #                  an inline `# mutineer:disable-line` comment or a
+  #                  `.mutineer.yml` `ignore:` id. A pre-fork classification
+  #                  (never run); excluded from the denominator so a strong
+  #                  file can reach 100%.
   #
   # `error` and `skipped` are deliberately distinct: skipped is a pre-fork
   # validity failure (counted separately by the reporter), error is a runtime
   # crash. Never conflate them via `details` string parsing. `no_coverage` and
-  # `uncapturable` are pre-fork selection results (M3/#9): both excluded from the
-  # score denominator.
+  # `uncapturable` are pre-fork selection results (M3/#9): both excluded from
+  # the score denominator.
   #
-  # `subject`, `mutation`, and `id` are nil when the Result is built by Isolation/
-  # Runner (which only know the outcome); the orchestrator attaches them afterwards
-  # via `result.with(subject:, mutation:, id:)` so the Reporter can render survivor
-  # diffs and emit the stable id. `id` is the content-based MutantId (#10).
+  # `subject`, `mutation`, and `id` are nil when the Result is built by
+  # Isolation/Runner (which only know the outcome); the orchestrator attaches
+  # them afterwards via `result.with(subject:, mutation:, id:)` so the Reporter
+  # can render survivor diffs and emit the stable id. `id` is the content-based
+  # MutantId (#10).
   Result = Data.define(:status, :details, :subject, :mutation, :id) do
-    def self.killed               = new(status: :killed, details: nil, subject: nil, mutation: nil, id: nil)
-    def self.survived             = new(status: :survived, details: nil, subject: nil, mutation: nil, id: nil)
+    # Builds a killed result.
+    #
+    # @return [Mutineer::Result] killed result.
+    def self.killed = new(status: :killed, details: nil, subject: nil, mutation: nil, id: nil)
+
+    # Builds a survived result.
+    #
+    # @return [Mutineer::Result] survived result.
+    def self.survived = new(status: :survived, details: nil, subject: nil, mutation: nil, id: nil)
+
+    # Builds an error result.
+    #
+    # @param details [String, nil] error details.
+    # @return [Mutineer::Result] error result.
     def self.error(details = nil) = new(status: :error, details: details, subject: nil, mutation: nil, id: nil)
-    def self.timeout              = new(status: :timeout, details: nil, subject: nil, mutation: nil, id: nil)
+
+    # Builds a timeout result.
+    #
+    # @return [Mutineer::Result] timeout result.
+    def self.timeout = new(status: :timeout, details: nil, subject: nil, mutation: nil, id: nil)
+
+    # Builds a skipped result.
+    #
+    # @param details [String, nil] skip details.
+    # @return [Mutineer::Result] skipped result.
     def self.skipped(details = nil) = new(status: :skipped, details: details, subject: nil, mutation: nil, id: nil)
-    def self.no_coverage          = new(status: :no_coverage, details: nil, subject: nil, mutation: nil, id: nil)
-    def self.uncapturable         = new(status: :uncapturable, details: nil, subject: nil, mutation: nil, id: nil)
-    def self.ignored              = new(status: :ignored, details: nil, subject: nil, mutation: nil, id: nil)
 
+    # Builds a no_coverage result.
+    #
+    # @return [Mutineer::Result] no-coverage result.
+    def self.no_coverage = new(status: :no_coverage, details: nil, subject: nil, mutation: nil, id: nil)
+
+    # Builds an uncapturable result.
+    #
+    # @return [Mutineer::Result] uncapturable result.
+    def self.uncapturable = new(status: :uncapturable, details: nil, subject: nil, mutation: nil, id: nil)
+
+    # Builds an ignored result.
+    #
+    # @return [Mutineer::Result] ignored result.
+    def self.ignored = new(status: :ignored, details: nil, subject: nil, mutation: nil, id: nil)
+
+    # @return [Boolean] true when the status is killed.
     def killed?       = status == :killed
+    # @return [Boolean] true when the status is survived.
     def survived?     = status == :survived
+    # @return [Boolean] true when the status is error.
     def error?        = status == :error
+    # @return [Boolean] true when the status is timeout.
     def timeout?      = status == :timeout
+    # @return [Boolean] true when the status is skipped.
     def skipped?      = status == :skipped
+    # @return [Boolean] true when the status is no_coverage.
     def no_coverage?  = status == :no_coverage
+    # @return [Boolean] true when the status is uncapturable.
     def uncapturable? = status == :uncapturable
+    # @return [Boolean] true when the status is ignored.
     def ignored?      = status == :ignored
+
   end
 
   # Aggregates a flat list of Results into counts, the mutation score, and the
   # surviving-mutant list. The score denominator is killed + survived ONLY
-  # (KTD-4): no-coverage, uncapturable, skipped (invalid), errored, timeout, and
-  # ignored (#10 equivalent-mutant suppression) are each excluded and surfaced
-  # separately — so suppressing every survivor reaches 100%. An empty denominator yields a nil score
-  # (rendered "N/A"), never 0.0 — distinguishing "no testable mutants" from
-  # "0% killed".
+  # (KTD-4): no-coverage, uncapturable, skipped (invalid), errored, timeout,
+  # and ignored (#10 equivalent-mutant suppression) are each excluded and
+  # surfaced separately — so suppressing every survivor reaches 100%. An empty
+  # denominator yields a nil score (rendered "N/A"), never 0.0 —
+  # distinguishing "no testable mutants" from "0% killed".
   class AggregateResult
     attr_reader :results
 
+    # Builds an aggregate from results.
+    #
+    # @param results [Array<Mutineer::Result>] classified results.
     def initialize(results)
       @results = results
       @by_status = results.group_by(&:status)
     end
 
+    # @return [Integer] killed count.
     def killed_count          = count(:killed)
+    # @return [Integer] survived count.
     def survived_count        = count(:survived)
+    # @return [Integer] no-coverage count.
     def no_coverage_count     = count(:no_coverage)
+    # @return [Integer] uncapturable count.
     def uncapturable_count    = count(:uncapturable)
+    # @return [Integer] skipped-invalid count.
     def skipped_invalid_count = count(:skipped)
+    # @return [Integer] errored count.
     def errored_count         = count(:error)
+    # @return [Integer] timeout count.
     def timeout_count         = count(:timeout)
+    # @return [Integer] ignored count.
     def ignored_count         = count(:ignored)
 
     # Every generated, classified mutation. NOT the score denominator.
+    #
+    # @return [Integer] total result count.
     def total = @results.size
 
     # The score denominator (also shown to the reader).
+    #
+    # @return [Integer] killed plus survived.
     def covered_count = killed_count + survived_count
 
-    # killed / (killed + survived) as a rounded percentage, or nil when nothing
-    # was testable.
+    # Computes the mutation score.
+    #
+    # @return [Float, nil] score percentage or nil when nothing was testable.
     def mutation_score
       return nil if covered_count.zero?
 
       (killed_count.to_f / covered_count * 100).round(1)
     end
 
+    # Returns the surviving mutants.
+    #
+    # @return [Array<Mutineer::Result>] surviving results.
     def surviving_mutants = @results.select(&:survived?)
 
-    # #11: split into { source_file => AggregateResult } so the Reporter (per-source
-    # breakdown) and #13 (per-source roll-up / baseline diff) share one shape with
-    # all the score/count methods. After Runner.execute every result carries a
-    # subject, so the grouping is total; bare results (no subject, only in unit
-    # tests) are skipped so file keys stay sortable strings.
+    # #11: split into { source_file => AggregateResult } so the Reporter
+    # (per-source breakdown) and #13 (per-source roll-up / baseline diff) can
+    # reuse the same aggregate math.
+    #
+    # @return [Hash<String, Mutineer::AggregateResult>] source-file groups.
     def by_source
       @results.select { |r| r.subject }
               .group_by { |r| r.subject.file }
@@ -100,6 +164,10 @@ module Mutineer
 
     private
 
+    # Counts results for a status.
+    #
+    # @param status [Symbol] result status.
+    # @return [Integer] count for that status.
     def count(status) = (@by_status[status] || []).size
   end
 end

data/lib/mutineer/runner.rb

@@ -32,6 +32,9 @@ module Mutineer
     # The parent process `require`s each source file so its classes exist; forked
     # children inherit them, so a covering test file's own require_relative of the
     # source is a no-op and does not clobber the mutated `load` (spec §7).
+    #
+    # @param config [Mutineer::Config] run configuration.
+    # @return [Array(Mutineer::AggregateResult, Hash<String, String>)] aggregate and source map.
     def self.execute(config)
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
 
@@ -215,6 +218,11 @@ module Mutineer
       warn "[mutineer] RAILS_ENV was unset; defaulting to 'test' for --rails."
     end
 
+    # Removes stale mutant tempfiles from the given directories.
+    #
+    # @api private
+    # @param dirs [Array<String>] directories to sweep.
+    # @return [void]
     def self.sweep_orphans(dirs)
       dirs.each do |dir|
         Dir.glob(File.join(dir, "mutineer_mutant*.rb")).each do |f|
@@ -223,6 +231,17 @@ module Mutineer
       end
     end
 
+    # Runs a single mutation through isolation.
+    #
+    # @param mutation [Mutineer::Mutation] mutation to run.
+    # @param source_file [String] source file path.
+    # @param coverage_map [Mutineer::CoverageMap, nil] coverage map.
+    # @param subject [Mutineer::Subject, nil] subject for surgical strategy.
+    # @param strategy [String] mutation strategy.
+    # @param timeout [Integer] child timeout in seconds.
+    # @param rails [Boolean] whether Rails reconnect handling is enabled.
+    # @param framework [String] test framework name.
+    # @return [Mutineer::Result] mutant result.
     def self.run(mutation, source_file:, coverage_map: nil, subject: nil, strategy: "reload",
                  timeout: Isolation::DEFAULT_TIMEOUT, rails: false, framework: "minitest")
       source  = File.read(source_file)
@@ -257,6 +276,10 @@ module Mutineer
       end
     end
 
+    # Reconnects ActiveRecord in a forked child when available.
+    #
+    # @api private
+    # @return [void]
     def self.reconnect_active_record
       return unless defined?(ActiveRecord::Base)
 

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.8.0"
 end

data/lib/mutineer/worker_pool.rb

@@ -3,21 +3,30 @@
 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
 
+    # Runs the work items through the pool.
+    #
+    # @param items [Array<Array>] work items.
+    # @yieldparam item [Array] one work item.
+    # @return [Array<Mutineer::Result>] results in input order.
     def run(items)
       results = Array.new(items.size)
       queue   = (0...items.size).to_a
@@ -33,17 +42,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 +85,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?
 
@@ -104,11 +115,13 @@ module Mutineer
       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

@@ -29,5 +29,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.8.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.