mutineer 0.7.0 → 0.9.0

data/lib/mutineer/project.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "prism"
+require "set"
 require_relative "parser"
 require_relative "subject"
 
@@ -8,12 +9,17 @@ module Mutineer
   # Subject discovery: parse each path and walk its AST for method definitions,
   # tracking the enclosing class/module namespace.
   class Project
-    # Returns Array<Subject>. `only` filters by qualified name (string equality).
+    # Discovers subjects from source paths.
+    #
+    # @param paths [Array<String>] source file paths.
+    # @param only [String, nil] optional qualified-name filter.
+    # @return [Array<Mutineer::Subject>] discovered subjects.
     def self.discover(paths, only: nil)
       subjects = Array(paths).flat_map do |path|
         result = Parser.parse_file(path)
         visitor = SubjectVisitor.new(path)
         visitor.visit(result.value)
+        visitor.promote_module_functions!
         visitor.subjects
       end
       only ? subjects.select { |s| s.qualified_name == only } : subjects
@@ -24,31 +30,87 @@ module Mutineer
     class SubjectVisitor < Prism::Visitor
       attr_reader :subjects
 
+      # Builds a subject visitor.
+      #
+      # @param file [String] source file path being visited.
       def initialize(file)
         @file = file
         @namespace_stack = []
         @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`
         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).
+      #
+      # @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) }
+      end
+
+      # Visits class nodes and tracks namespace nesting.
+      #
+      # @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
       end
 
+      # Visits module nodes and tracks namespace nesting.
+      #
+      # @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
       end
 
+      # Track `module_function` so its methods are recorded as singletons (#20) —
+      # the called form is the singleton method on the module object. Bareword
+      # `module_function` flips all SUBSEQUENT defs in this body; the argument
+      # forms (`:sym`, `def`) name methods promoted after the walk.
+      #
+      # @param node [Prism::CallNode] call node.
+      # @return [void]
+      def visit_call_node(node)
+        if node.name == :module_function && node.receiver.nil?
+          args = node.arguments&.arguments || []
+          if args.empty?
+            @module_function_active = true
+          else
+            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)
+            end
+          end
+        end
+        super
+      end
+
       # Methods inside `class << self` are class methods of the enclosing
       # namespace, but their def nodes have no receiver — track the singleton
       # context so they're recorded as singleton (so redefine targets the
       # singleton_class, not instances). `class << some_other_obj` can't be
       # represented against the namespace, so its defs are skipped (not recursed).
+      #
+      # @param node [Prism::SingletonClassNode] singleton-class node.
+      # @return [void]
       def visit_singleton_class_node(node)
         return unless node.expression.is_a?(Prism::SelfNode)
 
@@ -57,12 +119,16 @@ module Mutineer
         @singleton_depth -= 1
       end
 
+      # Records a discovered method definition.
+      #
+      # @param node [Prism::DefNode] method definition node.
+      # @return [void]
       def visit_def_node(node)
         @subjects << Subject.new(
           file: @file,
           namespace: @namespace_stack.dup,
           name: node.name,
-          singleton: !node.receiver.nil? || @singleton_depth.positive?,
+          singleton: !node.receiver.nil? || @singleton_depth.positive? || @module_function_active,
           def_node: node
         )
         super
@@ -70,6 +136,11 @@ module Mutineer
 
       private
 
+      # Extracts a constant name from a Prism constant node.
+      #
+      # @api private
+      # @param node [Prism::Node] constant node.
+      # @return [String, nil] constant name.
       def extract_constant_name(node)
         case node
         when Prism::ConstantReadNode

data/lib/mutineer/reporter.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "stringio"
+require "cgi"
 require_relative "mutation"
 
 module Mutineer
@@ -25,6 +26,8 @@ module Mutineer
       rendered =
         if format == "json"
           json_report(baseline)
+        elsif format == "html"
+          html_report
         else
           sio = StringIO.new
           human_report(sio, err, threshold)
@@ -41,6 +44,12 @@ module Mutineer
       end
     end
 
+    # Renders the human report.
+    #
+    # @param out [IO] output stream.
+    # @param err [IO] error stream.
+    # @param threshold [Float] score threshold.
+    # @return [void]
     def human_report(out, err, threshold)
       if @agg.total.zero?
         err.puts "No mutations generated — verify target files contain in-scope " \
@@ -75,6 +84,11 @@ module Mutineer
     # Canonical machine-readable schema (KTD7). survivors/no_coverage are sorted
     # by (file, line, operator) so output is byte-stable regardless of --jobs
     # worker finish order (R22).
+    # Renders the JSON report.
+    #
+    # @api private
+    # @param baseline [Mutineer::Baseline::Delta, nil] baseline delta.
+    # @return [String] JSON text.
     def json_report(baseline = nil)
       killed = @agg.killed_count
       survived = @agg.survived_count
@@ -117,6 +131,117 @@ module Mutineer
       "#{JSON.generate(doc)}\n"
     end
 
+    # #23: one self-contained HTML file (inline CSS, no external assets) — the
+    # overall score + summary counts, a per-source table, and every surviving
+    # mutant with its stable id and diff. All source/diff/identifier text is
+    # HTML-escaped (CGI.escapeHTML) so a `<`/`>` in source can never break the
+    # markup. Reuses survivor_json/per_source_json so one run yields one set of
+    # facts regardless of --format.
+    def html_report
+      score = @agg.mutation_score
+      survivors = @agg.surviving_mutants.map { |r| survivor_json(r) }
+                      .sort_by { |h| [h[:file], h[:line], h[:operator]] }
+      per_source = @agg.by_source.map { |file, agg| per_source_json(file, agg) }
+                       .sort_by { |h| h[:file] }
+
+      <<~HTML
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <title>Mutineer Mutation Report</title>
+        <style>
+          body { font-family: -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif;
+                 margin: 2rem; color: #1b1b1b; background: #fafafa; }
+          h1 { margin: 0 0 .25rem; }
+          .score { font-size: 2.5rem; font-weight: 700; }
+          .counts { color: #444; margin: .5rem 0 1.5rem; }
+          .counts span { display: inline-block; margin-right: 1rem; white-space: nowrap; }
+          table { border-collapse: collapse; width: 100%; margin-bottom: 2rem; background: #fff; }
+          th, td { border: 1px solid #ddd; padding: .4rem .6rem; text-align: left; }
+          th { background: #f0f0f0; }
+          td.num { text-align: right; font-variant-numeric: tabular-nums; }
+          .survivor { background: #fff; border: 1px solid #ddd; border-radius: 4px;
+                      padding: .75rem 1rem; margin-bottom: 1rem; }
+          .survivor h3 { margin: 0 0 .25rem; font-size: 1rem; }
+          .meta { color: #555; font-size: .85rem; margin-bottom: .5rem; }
+          .id { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+          pre.diff { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+                     background: #f6f8fa; padding: .5rem .75rem; overflow-x: auto;
+                     margin: 0; border-radius: 4px; }
+          .diff .add { color: #116329; }
+          .diff .del { color: #82071e; }
+        </style>
+        </head>
+        <body>
+        <h1>Mutineer — Mutation Report</h1>
+        <div class="score">Score: #{score.nil? ? 'N/A' : "#{score}%"}</div>
+        #{summary_html}
+        #{per_source_html(per_source)}
+        #{survivors_html(survivors)}
+        </body>
+        </html>
+      HTML
+    end
+
+    # The summary counts block for the HTML header.
+    def summary_html
+      counts = {
+        "total" => @agg.total, "killed" => @agg.killed_count,
+        "survived" => @agg.survived_count, "no_coverage" => @agg.no_coverage_count,
+        "uncapturable" => @agg.uncapturable_count, "ignored" => @agg.ignored_count,
+        "skipped" => @agg.skipped_invalid_count,
+        "errored" => @agg.errored_count + @agg.timeout_count
+      }
+      spans = counts.map { |k, v| "<span><strong>#{v}</strong> #{esc(k)}</span>" }.join("\n  ")
+      "<div class=\"counts\">\n  #{spans}\n</div>"
+    end
+
+    # The per-source breakdown table.
+    def per_source_html(per_source)
+      return "" if per_source.empty?
+
+      rows = per_source.map do |h|
+        score = h[:score].nil? ? "N/A" : "#{h[:score]}%"
+        "<tr><td>#{esc(h[:file])}</td><td class=\"num\">#{score}</td>" \
+          "<td class=\"num\">#{h[:killed]}</td><td class=\"num\">#{h[:survived]}</td>" \
+          "<td class=\"num\">#{h[:no_coverage]}</td></tr>"
+      end.join("\n  ")
+      <<~HTML.chomp
+        <h2>Per-source</h2>
+        <table>
+        <tr><th>File</th><th>Score</th><th>Killed</th><th>Survived</th><th>No coverage</th></tr>
+          #{rows}
+        </table>
+      HTML
+    end
+
+    # The surviving-mutants list, each with subject, location, operator, stable
+    # id, and a colorized diff. All text is HTML-escaped.
+    def survivors_html(survivors)
+      return "<h2>Surviving Mutants</h2>\n<p>None — every covered mutant was killed.</p>" if survivors.empty?
+
+      cards = survivors.map do |s|
+        diff_lines = s[:diff].each_line.map do |line|
+          cls = line.start_with?("+") ? "add" : (line.start_with?("-") ? "del" : nil)
+          text = esc(line.chomp)
+          cls ? "<span class=\"#{cls}\">#{text}</span>" : text
+        end.join("\n")
+        <<~CARD.chomp
+          <div class="survivor">
+          <h3>#{esc(s[:subject])}</h3>
+          <div class="meta">#{esc(s[:file])}:#{s[:line]} &middot; #{esc(s[:operator])} &middot; <span class="id">#{esc(s[:id])}</span></div>
+          <pre class="diff">#{diff_lines}</pre>
+          </div>
+        CARD
+      end.join("\n")
+      "<h2>Surviving Mutants</h2>\n#{cards}"
+    end
+
+    # HTML-escapes any text destined for the document (stdlib CGI).
+    def esc(text) = CGI.escapeHTML(text.to_s)
+
     # #13: the same delta facts the human report prints, for dashboards. new_survivors
     # reuse the ignored_json shape (subject/file/line/operator/token/id) and sort
     # byte-stably so output doesn't depend on --jobs finish order.
@@ -135,6 +260,12 @@ module Mutineer
       }
     end
 
+    # Builds per-source JSON.
+    #
+    # @api private
+    # @param file [String] source file path.
+    # @param agg [Mutineer::AggregateResult] source aggregate.
+    # @return [Hash] per-source JSON object.
     def per_source_json(file, agg)
       {
         file: file, total: agg.total,
@@ -143,6 +274,11 @@ module Mutineer
       }
     end
 
+    # Builds survivor JSON.
+    #
+    # @api private
+    # @param result [Mutineer::Result] survivor result.
+    # @return [Hash] survivor JSON object.
     def survivor_json(result)
       m = result.mutation
       file = result.subject.file
@@ -198,6 +334,11 @@ module Mutineer
       [start_line, original_block, mutated_block, token]
     end
 
+    # Builds no-coverage JSON.
+    #
+    # @api private
+    # @param result [Mutineer::Result] result object.
+    # @return [Hash] no-coverage JSON object.
     def no_coverage_json(result)
       m = result.mutation
       file = result.subject.file
@@ -209,6 +350,10 @@ module Mutineer
       }
     end
 
+    # Writes the summary block.
+    #
+    # @param out [IO] output stream.
+    # @return [void]
     def summary(out)
       out.puts "Summary"
       out.puts "-------"
@@ -222,6 +367,11 @@ module Mutineer
       out.puts format("Ignored:      %-6d  (equivalent, suppressed)", @agg.ignored_count)
     end
 
+    # Writes the score line.
+    #
+    # @param out [IO] output stream.
+    # @param err [IO] error stream.
+    # @return [void]
     def score_line(out, err)
       score = @agg.mutation_score
       excluded = "#{@agg.no_coverage_count} no-coverage, #{@agg.uncapturable_count} uncapturable, " \
@@ -239,6 +389,10 @@ module Mutineer
     # #11: one line per source after the global summary, so a multi-source run
     # shows which file is weak. Omitted for a single-source run — the global
     # summary already says everything (ponytail: no redundant one-line block).
+    # Writes the per-source breakdown.
+    #
+    # @param out [IO] output stream.
+    # @return [void]
     def per_source(out)
       sources = @agg.by_source
       return if sources.size <= 1
@@ -274,6 +428,10 @@ module Mutineer
       out.puts(delta.regressed ? "REGRESSION vs baseline" : "OK: no regression vs baseline")
     end
 
+    # Writes the survivors block.
+    #
+    # @param out [IO] output stream.
+    # @return [void]
     def survivors(out)
       mutants = @agg.surviving_mutants
       return if mutants.empty?
@@ -288,6 +446,12 @@ module Mutineer
       end
     end
 
+    # Writes one survivor entry.
+    #
+    # @param out [IO] output stream.
+    # @param file [String] source file path.
+    # @param result [Mutineer::Result] survivor result.
+    # @return [void]
     def survivor(out, file, result)
       m = result.mutation
       source = @source_map[file] || File.read(file)
@@ -299,6 +463,11 @@ module Mutineer
       mutated_block.each_line  { |l| out.puts "  + #{l.chomp}" }
     end
 
+    # Writes the final verdict line.
+    #
+    # @param out [IO] output stream.
+    # @param threshold [Float] score threshold.
+    # @return [void]
     def verdict(out, threshold)
       score = @agg.mutation_score
       return if score.nil?

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)
 
@@ -124,13 +127,17 @@ module Mutineer
       results =
         begin
           framework = config.framework
-          bare = WorkerPool.new(config.jobs).run(jobs) do |subject, mutation|
+          # #21: --fail-fast stops scheduling new mutants after the first survivor;
+          # in-flight workers drain, unscheduled jobs stay nil (dropped below).
+          stop_when = config.fail_fast ? ->(r) { r.survived? } : nil
+          bare = WorkerPool.new(config.jobs).run(jobs, stop_when: stop_when) do |subject, mutation|
             run(mutation, source_file: subject.file, coverage_map: coverage_map,
                 subject: subject, strategy: strategy, rails: config.rails, framework: framework)
           end
           # The bare Results carry only status (Subjects hold live AST nodes that
           # do not marshal); reattach subject+mutation+id in the parent, in order.
-          bare.each_with_index.map { |r, i| r.with(subject: jobs[i][0], mutation: jobs[i][1], id: jobs[i][2]) }
+          # filter_map drops nils for jobs --fail-fast left unscheduled.
+          bare.each_with_index.filter_map { |r, i| r&.with(subject: jobs[i][0], mutation: jobs[i][1], id: jobs[i][2]) }
         ensure
           sweep_orphans(source_dirs)
         end
@@ -215,6 +222,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 +235,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 +280,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)