mutineer 0.6.2 → 0.8.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

@@ -21,13 +21,14 @@ module Mutineer
     # Single entry point (R20/R21). Branches on `format` ("human" | "json") and
     # routes the rendered report to `output` (a file, with a stderr confirmation)
     # or to `out`. Diagnostics always go to `err`.
-    def report(out: $stdout, err: $stderr, threshold: 0.0, format: "human", output: nil)
+    def report(out: $stdout, err: $stderr, threshold: 0.0, format: "human", output: nil, baseline: nil)
       rendered =
         if format == "json"
-          json_report
+          json_report(baseline)
         else
           sio = StringIO.new
           human_report(sio, err, threshold)
+          baseline_section(sio, baseline) if baseline
           sio.string
         end
 
@@ -40,6 +41,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 " \
@@ -53,6 +60,7 @@ module Mutineer
       summary(out)
       out.puts
       score_line(out, err)
+      per_source(out)
 
       survivors(out)
       verdict(out, threshold) if threshold && threshold.positive?
@@ -73,7 +81,12 @@ 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).
-    def json_report
+    # 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
       # C8: null (not 0.0) on an empty denominator, matching the nil-vs-0.0
@@ -82,27 +95,81 @@ module Mutineer
       score = @agg.mutation_score
 
       doc = {
-        schema_version: "1.0",
+        schema_version: "1.1",
         summary: {
           total: @agg.total, killed: killed, survived: survived,
           no_coverage: @agg.no_coverage_count,
+          uncapturable: @agg.uncapturable_count,
           skipped_invalid: @agg.skipped_invalid_count,
           errored: @agg.errored_count, timeout: @agg.timeout_count,
+          ignored: @agg.ignored_count,
           score: score
         },
         survivors: @agg.surviving_mutants.map { |r| survivor_json(r) }
                        .sort_by { |h| [h[:file], h[:line], h[:operator]] },
         no_coverage: @agg.results.select(&:no_coverage?).map { |r| no_coverage_json(r) }
-                         .sort_by { |h| [h[:file], h[:line]] }
+                         .sort_by { |h| [h[:file], h[:line]] },
+        # #9: same shape as no_coverage; additive key.
+        uncapturable: @agg.results.select(&:uncapturable?).map { |r| no_coverage_json(r) }
+                          .sort_by { |h| [h[:file], h[:line]] },
+        # #10: equivalent mutants the user suppressed — emitted with their stable
+        # id so the user can audit what is silenced (and copy ids for survivors
+        # they want to add). Excluded from the score; never in `survivors`.
+        ignored: @agg.results.select(&:ignored?).map { |r| ignored_json(r) }
+                     .sort_by { |h| [h[:file], h[:line], h[:operator]] },
+        # #11: per-source breakdown (additive; #13 consumes it). Sorted by file so
+        # output is byte-stable. Reuses AggregateResult via by_source.
+        per_source: @agg.by_source.map { |file, agg| per_source_json(file, agg) }
+                        .sort_by { |h| h[:file] }
       }
+      # #13: additive baseline-delta block, present only with --baseline. Existing
+      # consumers ignore the extra key; schema_version stays 1.1.
+      doc[:baseline] = baseline_json(baseline) if baseline
       "#{JSON.generate(doc)}\n"
     end
 
+    # #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.
+    def baseline_json(delta)
+      {
+        regressed: delta.regressed,
+        score_before: delta.score_before,
+        score_after: delta.score_after,
+        score_dropped: delta.score_drop,
+        new_survivors: delta.new_survivors.map { |r| ignored_json(r) }
+                            .sort_by { |h| [h[:file], h[:line], h[:operator]] },
+        fixed_survivors: delta.fixed_survivors.map do |h|
+          { subject: h["subject"], file: h["file"], line: h["line"],
+            operator: h["operator"], id: h["id"] }
+        end.sort_by { |h| [h[:file].to_s, h[:line].to_i, h[:operator].to_s] }
+      }
+    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,
+        killed: agg.killed_count, survived: agg.survived_count,
+        no_coverage: agg.no_coverage_count, score: agg.mutation_score
+      }
+    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
       source = @source_map[file] || File.read(file)
-      start_line, original_block, mutated_block, = diff_for(m, source)
+      start_line, original_block, mutated_block, token = diff_for(m, source)
       minus = original_block.each_line.map { |l| "-#{l.chomp}" }.join("\n")
       plus  = mutated_block.each_line.map { |l| "+#{l.chomp}" }.join("\n")
       {
@@ -110,10 +177,30 @@ module Mutineer
         file: file,
         line: start_line,
         operator: m.operator.to_s,
+        # #10: the stable, copy-pasteable id (next to the human-readable token) so a
+        # user can paste it straight into .mutineer.yml `ignore:`.
+        id: result.id,
+        token: token,
         diff: "--- a/#{file}\n+++ b/#{file}\n@@ -#{start_line} +#{start_line} @@\n#{minus}\n#{plus}\n"
       }
     end
 
+    # An entry under the JSON `ignored:` key — what the user already suppressed.
+    def ignored_json(result)
+      m = result.mutation
+      file = result.subject.file
+      source = @source_map[file] || File.read(file)
+      start_line, _orig, _mut, token = diff_for(m, source)
+      {
+        subject: result.subject.qualified_name,
+        file: file,
+        line: start_line,
+        operator: m.operator.to_s,
+        token: token,
+        id: result.id
+      }
+    end
+
     # Builds a line-aligned diff for a mutation whose byte range may span several
     # lines (e.g. statement-removal of a multi-line statement). Returns the
     # mutation's 1-based start line, the full original line-block it touches, the
@@ -133,6 +220,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
@@ -144,6 +236,10 @@ module Mutineer
       }
     end
 
+    # Writes the summary block.
+    #
+    # @param out [IO] output stream.
+    # @return [void]
     def summary(out)
       out.puts "Summary"
       out.puts "-------"
@@ -151,12 +247,23 @@ module Mutineer
       out.puts format("Survived:     %-6d  No coverage:   %d", @agg.survived_count, @agg.no_coverage_count)
       out.puts format("Skipped:      %-6d  Errored:       %d", @agg.skipped_invalid_count,
                       @agg.errored_count + @agg.timeout_count)
+      # #9: a broken harness, not a coverage gap — report it distinctly from No coverage.
+      out.puts format("Uncapturable: %-6d  (tests failed to run)", @agg.uncapturable_count)
+      # #10: equivalent mutants the user suppressed; excluded from the denominator.
+      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.skipped_invalid_count} skipped, " \
-                 "#{@agg.errored_count + @agg.timeout_count} errored excluded"
+      excluded = "#{@agg.no_coverage_count} no-coverage, #{@agg.uncapturable_count} uncapturable, " \
+                 "#{@agg.skipped_invalid_count} skipped, " \
+                 "#{@agg.errored_count + @agg.timeout_count} errored, " \
+                 "#{@agg.ignored_count} ignored excluded"
       if score.nil?
         out.puts "Mutation score: N/A  (no covered mutants)"
         err.puts "[mutineer] no covered mutations; mutation score is N/A and the threshold check is skipped."
@@ -165,6 +272,52 @@ module Mutineer
       end
     end
 
+    # #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
+
+      out.puts
+      out.puts "Per-source"
+      out.puts "----------"
+      sources.sort.each do |file, agg|
+        score = agg.mutation_score
+        out.puts format("%s  %s  (%d killed / %d survived / %d no-cov)",
+                        file, score.nil? ? "N/A" : "#{score}%",
+                        agg.killed_count, agg.survived_count, agg.no_coverage_count)
+      end
+    end
+
+    # #13: the --baseline delta, appended after the normal report. Names every NEW
+    # survivor (subject (file:line) operator) and the score delta when it dropped,
+    # then a one-line REGRESSION/OK verdict so CI logs show which gate fired.
+    def baseline_section(out, delta)
+      out.puts
+      out.puts "Baseline comparison"
+      out.puts "-------------------"
+      out.puts "killed #{@agg.killed_count}, #{delta.new_survivors.size} new survivors vs baseline"
+      delta.new_survivors
+           .sort_by { |r| [r.subject.file, r.mutation.start_offset] }
+           .each do |r|
+        file = r.subject.file
+        source = @source_map[file] || File.read(file)
+        line, = diff_for(r.mutation, source)
+        out.puts "  + #{r.subject.qualified_name} (#{file}:#{line}) #{r.mutation.operator}"
+      end
+      out.puts "score dropped #{delta.score_before}% -> #{delta.score_after}%" if delta.score_drop
+      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?
@@ -179,6 +332,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)
@@ -190,6 +349,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

@@ -1,77 +1,173 @@
 # frozen_string_literal: true
 
 module Mutineer
-  # Immutable outcome of running one mutant. Six distinct states:
-  #   killed      — a test failed/errored, so the mutation was caught.
-  #   survived    — every test passed, so the mutation went undetected.
-  #   error       — the child crashed (unhandled exception): exit status 2.
-  #   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.
+  # Immutable outcome of running one mutant. Seven distinct states:
+  #   killed       — a test failed/errored, so the mutation was caught.
+  #   survived     — every test passed, so the mutation went undetected.
+  #   error        — the child crashed (unhandled exception): exit status 2.
+  #   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%.
   #
   # `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` is a
-  # pre-fork selection result (M3): excluded from the score denominator.
+  # 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.
   #
-  # `subject` and `mutation` 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:)` so the Reporter can render survivor diffs.
-  Result = Data.define(:status, :details, :subject, :mutation) do
-    def self.killed               = new(status: :killed, details: nil, subject: nil, mutation: nil)
-    def self.survived             = new(status: :survived, details: nil, subject: nil, mutation: nil)
-    def self.error(details = nil) = new(status: :error, details: details, subject: nil, mutation: nil)
-    def self.timeout              = new(status: :timeout, details: nil, subject: nil, mutation: nil)
-    def self.skipped(details = nil) = new(status: :skipped, details: details, subject: nil, mutation: nil)
-    def self.no_coverage          = new(status: :no_coverage, details: nil, subject: nil, mutation: nil)
-
-    def killed?      = status == :killed
-    def survived?    = status == :survived
-    def error?       = status == :error
-    def timeout?     = status == :timeout
-    def skipped?     = status == :skipped
-    def no_coverage? = status == :no_coverage
+  # `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
+    # 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)
+
+    # 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)
+
+    # 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, skipped (invalid), errored, and timeout are each
-  # excluded and surfaced separately. 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) 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 }
+              .transform_values { |rs| AggregateResult.new(rs) }
+    end
+
     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