mutineer 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae2c0b5167b5070a3afc7834ffa6d4d012267b070dd6b73f3d95affa3752c4c0
-  data.tar.gz: 22a328c5b5446d8c937288763d5ab050869b49b58c0bee715c3ec9dbb54005fd
+  metadata.gz: bfadc70b171d8778c8afa95021c2989ad33ab2880200a22886fec274e358efcc
+  data.tar.gz: f6f6c91f6e5fffc0a2d05d93b0981df165d6d5b2df1e1434949c7dea1c0f70a6
 SHA512:
-  metadata.gz: 858c634ce049e4a55ee2c94151a11df0b620edb19630d53719bf94cf6efa9212a4bd6d55c67607a1447ff42fed7804293ae3ec8c28b703b6478f2324aa5593b9
-  data.tar.gz: 2c47217873142ba8dbdffe1adbeb3772532925a951a2d52f058ca4b5e26732877019299de6a98c5c68ad89a5d9c6f8513b06ac424806fe7258e4ef1a7e305a27
+  metadata.gz: 01de0a56c54a7b85fd98d92831681a258a4420b3e5b3d34ce932811259a776764c888aae13a8975632c66851798f9b4a53f343864518fd8fe608e7dddff20e07
+  data.tar.gz: 63c802e363a3f87a8ecd43a5bf726d2ce23af2aadf890b87b7ad6616076e9f2461876c0af5faa70c83caf93027fd9e8754bf6866c5ab25e7d2a51bd51f9f3d4c

data/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.8.0] - 2026-06-30
+
+### Fixed
+- **Singleton methods are now mutated** (#20) — `class << self` and
+  `module_function` methods were discovered but applied to the instance scope, so
+  the mutant never ran on the singleton the caller dispatches to; every such
+  mutant falsely survived and the file read a false 0%. `module_function` methods
+  are now discovered as singletons, and the redefine strategy re-opens
+  `class << self` so the mutation lands on the called method. (Scores for
+  singleton-heavy files will rise to their true values.)
+- **Fork-capture failures are diagnosable** (#19, part 1) — capture/worker pipes
+  are `binmode` (a binary Marshal payload could otherwise be lost to an encoding
+  error and swallowed), and a child that dies without writing now reports how it
+  died (exit status / signal) instead of a silent "produced no result". `--verbose`
+  always surfaces a real reason now. (The residual write-heavy capture failure
+  on some real Rails suites remains under investigation — now diagnosable.)
+
+## [0.7.1] - 2026-06-30
+
+### Added
+- **GitHub Action** (`action.yml`, composite) wrapping the CLI for CI — gate a PR
+  on new survivors / score drop with `sources`, `since`, `baseline`, `threshold`,
+  etc. Inputs are passed via `env` (no `${{ }}` interpolation into the run script)
+  for command-injection safety.
+- Docs site (GitHub Pages) with Open Graph / Twitter Card share image; YARD doc
+  comments across the library.
+
 ## [0.7.0] - 2026-06-30
 
 Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
@@ -129,6 +156,8 @@ Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[0.8.0]: https://github.com/davidteren/mutineer/releases/tag/v0.8.0
+[0.7.1]: https://github.com/davidteren/mutineer/releases/tag/v0.7.1
 [0.7.0]: https://github.com/davidteren/mutineer/releases/tag/v0.7.0
 [0.6.2]: https://github.com/davidteren/mutineer/releases/tag/v0.6.2
 [0.6.1]: https://github.com/davidteren/mutineer/releases/tag/v0.6.1

data/README.md

@@ -1,6 +1,8 @@
 # Mutineer
 
-[![Socket Badge](https://badge.socket.dev/rubygems/package/mutineer/0.7.0?platform=ruby)](https://socket.dev/rubygems/package/mutineer/overview/0.7.0?platform=ruby)
+[![Gem Version](https://img.shields.io/gem/v/mutineer?logo=rubygems&color=e23b3b)](https://rubygems.org/gems/mutineer)
+[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Mutineer%20Ruby-2da44e?logo=githubactions&logoColor=white)](https://github.com/marketplace/actions/mutineer-ruby)
+[![Socket Badge](https://badge.socket.dev/rubygems/package/mutineer/0.7.1?platform=ruby)](https://socket.dev/rubygems/package/mutineer/overview/0.7.1?platform=ruby)
 
 A clean-room mutation-testing tool for Ruby. Mutineer mutates your source one
 change at a time, runs your test suite (Minitest or RSpec) against each mutant, and reports the
@@ -124,6 +126,37 @@ combines with `--threshold` (the worse of the two sets the exit code). Pass a
 directory (or several sources) to audit a whole layer in one boot — tests are
 auto-paired by convention and the report breaks down per source.
 
+### GitHub Action
+
+This repo ships a composite action (`action.yml`) that wraps the CLI for CI:
+
+```yaml
+- uses: actions/checkout@v4
+  with: { fetch-depth: 0 }        # --since needs full history
+- uses: ruby/setup-ruby@v1
+  with: { ruby-version: "3.4", bundler-cache: true }
+- uses: davidteren/mutineer@v0
+  with:
+    sources: app/
+    since: origin/${{ github.base_ref }}
+    baseline: .mutineer/baseline.json
+    threshold: "90"
+```
+
+## For AI agents & pipelines
+
+Mutineer is built for programmatic use — versioned JSON, stable mutant ids,
+structured exit codes, and diff-scoped runs. See:
+
+- **AI agents & CI recipes** — the agent inner-loop and CI-gate recipes (and how
+  to avoid infinite loops on equivalent mutants):
+  [rendered](https://davidteren.github.io/mutineer/agentic-coding.html) ·
+  [source](docs/agentic-coding.md)
+- **JSON schema reference** — the `--format json` schema and its versioning
+  contract:
+  [rendered](https://davidteren.github.io/mutineer/json-schema.html) ·
+  [source](docs/json-schema.md)
+
 ## Configuration
 
 Mutineer reads an optional `.mutineer.yml` from the project root (nearest one,

data/lib/mutineer/baseline.rb

@@ -5,20 +5,21 @@ require_relative "config" # for Mutineer::ConfigError
 
 module Mutineer
   # #13: CI baseline/delta gating. A baseline is literally a prior
-  # `mutineer run --format json` document (KTD-1) — no bespoke format to version.
-  # We diff the current run against it by the #10 stable survivor id (KTD-2): a
-  # NEW survivor (id present now, absent in the baseline) OR a score drop is a
-  # regression the CLI turns into exit 1. Pure data — stdlib `json` only, no fork,
-  # no Rails — so it's testable in isolation from a canned JSON + a hand-built
-  # AggregateResult.
+  # `mutineer run --format json` document (KTD-1) — no bespoke format to
+  # version.
+  # We diff the current run against it by the #10 stable survivor id (KTD-2):
+  # a NEW survivor (id present now, absent in the baseline) OR a score drop is
+  # a regression the CLI turns into exit 1. Pure data — stdlib `json` only, no
+  # fork, no Rails — so it's testable in isolation from a canned JSON + a hand-
+  # built AggregateResult.
   class Baseline
     # The verdict of diffing a current run against the baseline.
-    #   new_survivors   — current Result objects whose stable id is absent from the
-    #                     baseline (the regressions to name).
+    #   new_survivors   — current Result objects whose stable id is absent from
+    #                     the baseline (the regressions to name).
     #   fixed_survivors — baseline survivor hashes absent from the current run
     #                     (informational, never gates).
-    #   score_drop      — current score < baseline score - epsilon. nil on either
-    #                     side skips the check (see #diff).
+    #   score_drop      — current score < baseline score - epsilon. nil on
+    #                     either side skips the check (see #diff).
     #   regressed       — any new survivors OR a score drop.
     Delta = Data.define(:new_survivors, :fixed_survivors,
                         :score_before, :score_after, :score_drop, :regressed)
@@ -27,6 +28,10 @@ module Mutineer
     # class must never kill the host) on a missing/unreadable file, unparseable
     # JSON, or a doc that isn't a baseline shape, so the CLI maps it to exit 2
     # (usage) like every other bad-path flag.
+    #
+    # @param path [String] baseline JSON file path.
+    # @return [Mutineer::Baseline] baseline object.
+    # @raise [Mutineer::ConfigError] when the file is missing or invalid.
     def self.load(path)
       doc = JSON.parse(File.read(path))
       unless doc.is_a?(Hash) && doc["schema_version"] && doc["survivors"].is_a?(Array)
@@ -40,13 +45,23 @@ module Mutineer
 
     attr_reader :score
 
+    # Builds a baseline from a JSON document.
+    #
+    # The baseline retains the survivor document and score from the JSON report.
+    #
+    # @param doc [Hash] parsed JSON document.
     def initialize(doc)
       @survivors = doc["survivors"] || []
       @score = doc.dig("summary", "score")
     end
 
     # Diff a current AggregateResult against this baseline by stable survivor id.
-    # `epsilon` tolerates float jitter on the score (default 0.0 = any drop gates).
+    # `epsilon` tolerates float jitter on the score (default 0.0 = any drop
+    # gates).
+    #
+    # @param aggregate [Mutineer::AggregateResult] current results.
+    # @param epsilon [Float] score-drop tolerance.
+    # @return [Mutineer::Baseline::Delta] delta summary.
     def diff(aggregate, epsilon: 0.0)
       current = aggregate.surviving_mutants
       current_ids = current.map(&:id)
@@ -56,8 +71,9 @@ module Mutineer
       fixed = @survivors.reject { |h| current_ids.include?(h["id"]) }
 
       current_score = aggregate.mutation_score
-      # nil-score discipline (mirrors Reporter#exit_code): a score absent on either
-      # side can't be compared — skip the drop check, keep the new-survivor check.
+      # nil-score discipline (mirrors Reporter#exit_code): a score absent on
+      # either side can't be compared — skip the drop check, keep the new-
+      # survivor check.
       score_drop = !@score.nil? && !current_score.nil? &&
                    current_score < @score - epsilon
 

data/lib/mutineer/changed_lines.rb

@@ -4,23 +4,30 @@ require "set"
 require "open3"
 
 module Mutineer
-  # Maps each source file to the set of NEW-side line numbers that changed since a
-  # given git ref, by parsing `git diff --unified=0`. Used to restrict mutations
-  # to only the diff (issue #2): on a PR you care whether the changed code is
-  # tested, so mutating just those lines is fast and actionable.
+  # Maps each source file to the set of NEW-side line numbers changed since a
+  # git ref.
   #
-  # git is an external tool, not a gem dependency — shelling out is fine. The pure
+  # By parsing `git diff --unified=0`, this restricts mutations to only the
+  # diff (issue #2): on a PR you care whether the changed code is tested, so
+  # mutating just those lines is fast and actionable.
+  #
+  # git is an external tool, not a gem dependency — shelling out is fine. The
   # `parse` carries the logic; `git_diff` is injectable so it stays testable
   # without invoking git.
   module ChangedLines
+    # Matches unified-diff hunks and captures the new-file start/count.
     HUNK = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/
 
     module_function
 
-    # Parse `git diff --unified=0` output into the set of NEW-side line numbers
-    # added/modified. With --unified=0 each hunk's `+c,d` block is exactly the
-    # changed lines: c..c+d-1. `d` absent means 1 line; `d == 0` is a pure
-    # deletion and contributes nothing.
+    # Parses unified diff text into the set of NEW-side line numbers.
+    #
+    # With `--unified=0` each hunk's `+c,d` block is exactly the changed lines:
+    # `c..c+d-1`. `d` absent means 1 line; `d == 0` is a pure deletion and
+    # contributes nothing.
+    #
+    # @param diff_text [String] raw `git diff --unified=0` output.
+    # @return [Set<Integer>] changed line numbers on the new side.
     def parse(diff_text)
       lines = Set.new
       diff_text.each_line do |row|
@@ -34,8 +41,13 @@ module Mutineer
       lines
     end
 
-    # { absolute_file_path => Set<Integer> } of changed new-side lines per file.
-    # `runner` is injected so tests can supply canned diff text per file.
+    # Builds a per-file map of changed new-side lines.
+    #
+    # @param ref [String] git ref to diff against.
+    # @param files [Array<String>] source files to inspect.
+    # @param project_root [String] repository root for `git -C`.
+    # @param runner [#call] injectable diff producer.
+    # @return [Hash<String, Set<Integer>>] absolute file path to changed lines.
     def for(ref:, files:, project_root:, runner: method(:git_diff))
       files.each_with_object({}) do |file, acc|
         abs = File.expand_path(file, project_root)
@@ -43,7 +55,12 @@ module Mutineer
       end
     end
 
-    # stdout of `git -C <root> diff --unified=0 <ref> -- <file>`, "" on failure.
+    # Returns the stdout of `git -C <root> diff --unified=0 <ref> -- <file>`.
+    #
+    # @param ref [String] git ref to diff against.
+    # @param abs_file [String] absolute path of the file being diffed.
+    # @param project_root [String] repository root for `git -C`.
+    # @return [String] diff text, or `""` on failure.
     def git_diff(ref, abs_file, project_root)
       out, _err, status = Open3.capture3(
         "git", "-C", project_root, "diff", "--unified=0", ref, "--", abs_file

data/lib/mutineer/cli.rb

@@ -24,6 +24,7 @@ module Mutineer
   #   2  usage / flag error (unknown subcommand, invalid flag, unknown operator,
   #      out-of-range threshold)
   class CLI
+    # Command-line usage banner.
     BANNER = <<~USAGE
       Usage: mutineer [options] <command> [args]
 
@@ -63,6 +64,10 @@ module Mutineer
     # Deprecated internal strategy names, mapped to their canonical equivalents.
     STRATEGY_ALIASES = { "7a" => "reload", "7b" => "redefine" }.freeze
 
+    # Parses arguments, executes the command, and exits.
+    #
+    # @param argv [Array<String>] raw command-line arguments.
+    # @return [void]
     def self.start(argv)
       opts = {}            # symbol => value, the CLI-provided Config fields
       explicit = Set.new   # precedence keys the user typed (KTD3)
@@ -140,6 +145,9 @@ module Mutineer
       end
     end
 
+    # Lists available operators.
+    #
+    # @return [void]
     def self.list_operators
       MutatorRegistry::ALL.each_key do |name|
         state = MutatorRegistry.default?(name) ? "default" : "disabled"
@@ -148,6 +156,11 @@ module Mutineer
       end
     end
 
+    # Runs the requested command after validation.
+    #
+    # @param config [Mutineer::Config] run configuration.
+    # @param explicit [Set<Symbol>] explicit CLI fields.
+    # @return [void]
     def self.run(config, explicit = Set.new)
       if config.sources.empty?
         warn "mutineer: run requires at least one source file"
@@ -177,6 +190,12 @@ module Mutineer
 
     # Flag validation: every flag/usage failure exits 2 (C7), consistent with the
     # taxonomy above — CI can tell "mistyped flag" from "tests too weak."
+    # Validates the run configuration.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @param explicit [Set<Symbol>] explicit CLI fields.
+    # @return [void]
     def self.validate!(config, explicit = Set.new)
       unless (0.0..100.0).cover?(config.threshold)
         warn "mutineer: --threshold must be between 0 and 100"
@@ -231,6 +250,11 @@ module Mutineer
 
     # --since needs a real git repo and a resolvable ref; either failure is a
     # usage error (exit 2) so CI sees "bad invocation," not "tests too weak."
+    # Validates the --since ref.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
     def self.validate_since!(config)
       _out, _err, status = Open3.capture3(
         "git", "-C", config.project_root, "rev-parse", "--verify", "--quiet",
@@ -252,6 +276,11 @@ module Mutineer
     # R5: validate path existence up front so a typo is a clean usage error (exit
     # 2), not an Errno::ENOENT backtrace from deep in the run. Flag checks run
     # first so a bad flag still reports the flag, not the missing file.
+    # Validates source and test paths.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
     def self.validate_paths!(config)
       missing = (config.sources + config.tests)
                 .reject { |p| File.exist?(File.expand_path(p, config.project_root)) }
@@ -268,6 +297,12 @@ module Mutineer
     # the dedicated --boot/--rails-requires-test check reports it; otherwise exit 2
     # with a usage message. The framework is re-detected from the inferred set
     # unless it was set explicitly (a spec-only project loads/reports as rspec).
+    # Auto-pairs sources and tests when --test is absent.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @param explicit [Set<Symbol>] explicit CLI fields.
+    # @return [void]
     def self.autopair!(config, explicit)
       return unless config.tests.empty?
 
@@ -293,6 +328,11 @@ module Mutineer
     # mirroring --output/--since preflight, so CI sees "bad invocation," not a
     # backtrace mid-run. Validating up front = attempting the load (it raises
     # ConfigError/SystemCallError; the actual diff reloads in execute).
+    # Preflights a baseline file.
+    #
+    # @api private
+    # @param path [String] baseline file path.
+    # @return [void]
     def self.preflight_baseline!(path)
       Baseline.load(path)
     rescue Mutineer::ConfigError, SystemCallError => e
@@ -300,6 +340,11 @@ module Mutineer
       exit 2
     end
 
+    # Preflights an output path.
+    #
+    # @api private
+    # @param path [String] output file path.
+    # @return [void]
     def self.preflight_output!(path)
       dir = File.dirname(File.expand_path(path))
       return if File.directory?(dir) && File.writable?(dir)
@@ -309,6 +354,10 @@ module Mutineer
       exit 2
     end
 
+    # Executes the run command.
+    #
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
     def self.execute(config)
       if config.tests.empty?
         warn "mutineer: run requires at least one --test file (or use --dry-run)"
@@ -340,6 +389,10 @@ module Mutineer
 
     # The tier-2 operators not in the active set, as a one-line hint (or nil when
     # they're all already enabled). `active` nil means the default (Tier-1) set.
+    # Builds a Tier-2 operator hint.
+    #
+    # @param active [Array<String>, nil] active operator names.
+    # @return [String, nil] hint text or nil.
     def self.tier2_hint(active)
       active ||= MutatorRegistry::DEFAULT_NAMES
       unused = MutatorRegistry::TIER2_NAMES - active
@@ -349,6 +402,10 @@ module Mutineer
         "enable with --operators <list>."
     end
 
+    # Runs dry-run mode.
+    #
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
     def self.dry_run(config)
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
       sources = {}

data/lib/mutineer/config.rb

@@ -28,6 +28,7 @@ module Mutineer
     :baseline, :baseline_epsilon,
     keyword_init: true
   ) do
+    # Config file name.
     CONFIG_FILE = ".mutineer.yml"
     # Keys accepted in .mutineer.yml (R7). `require` maps to the :require_paths field.
     KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework verbose ignore baseline].freeze
@@ -128,16 +129,30 @@ module Mutineer
 
     # Pick rspec when a MAJORITY of the given test files end with _spec.rb;
     # otherwise minitest. Empty/ambiguous -> minitest (the safe default).
+    # Detects the test framework from the file list.
+    #
+    # @param tests [Array<String>] test file paths.
+    # @return [String] `"rspec"` or `"minitest"`.
     def self.detect_framework(tests)
       tests = Array(tests)
       specs = tests.count { |t| t.to_s.end_with?("_spec.rb") }
       specs > tests.length / 2.0 ? "rspec" : "minitest"
     end
 
+    # Maps a config key to its Struct field.
+    #
+    # @param known_key [String] config key.
+    # @return [Symbol] struct field name.
     def self.field_for(known_key)
       known_key == "require" ? :require_paths : known_key.to_sym
     end
 
+    # Coerces a config value to its target type.
+    #
+    # @param known_key [String] config key.
+    # @param value [Object] raw YAML value.
+    # @param file_name [String] config file name for warnings.
+    # @return [Object] coerced value.
     def self.coerce(known_key, value, file_name)
       case known_key
       when "operators" then filter_operators(Array(value).map(&:to_s), file_name)
@@ -157,6 +172,12 @@ module Mutineer
     # Drop (with a warning) operator names the registry doesn't know (R7).
     # Referenced lazily so config.rb carries no load-order dependency on the
     # registry; by the time a config is parsed at runtime, it is loaded.
+    # Filters out unknown operator names.
+    #
+    # @api private
+    # @param names [Array<String>] operator names.
+    # @param file_name [String] config file name for warnings.
+    # @return [Array<String>] known operator names.
     def self.filter_operators(names, file_name)
       known = MutatorRegistry::ALL.keys
       names.select do |n|

data/lib/mutineer/coverage_map.rb

@@ -117,6 +117,9 @@ module Mutineer
       self
     end
 
+    # Runs standalone Phase A coverage capture.
+    #
+    # @api private
     def run_phase_a
       @phase_a_ran = true
       @map = {}
@@ -160,6 +163,11 @@ module Mutineer
     # fork + Marshal-over-pipe + hard-exit! discipline as WorkerPool/Isolation.
     def fork_capture(abs_test, abs_sources, rails)
       rd, wr = IO.pipe
+      # #19: Marshal output is binary — an un-binmoded pipe can raise
+      # Encoding::UndefinedConversionError on write, which the child's rescue then
+      # swallows, losing the real error and yielding a bare "no result".
+      rd.binmode
+      wr.binmode
       pid = fork do
         rd.close
         payload =
@@ -189,12 +197,30 @@ module Mutineer
       wr.close
       data = rd.read
       rd.close
-      Process.waitpid(pid)
-      return nil if data.empty?
+      _, status = Process.waitpid2(pid)
+      # #19: an empty pipe means the child died before writing (e.g. a hard crash,
+      # OOM, or a signal from the test's own subprocess handling). Report HOW it
+      # died (exit status / signal) as a diagnostic string so --verbose has
+      # something actionable instead of a silent "no result".
+      return "child wrote no result (#{describe_status(status)})" if data.empty?
 
       Marshal.load(data)
-    rescue StandardError
-      nil
+    rescue StandardError => e
+      "parent could not read capture result: #{e.class}: #{e.message}"
+    end
+
+    # Human description of a child Process::Status for capture diagnostics.
+    #
+    # @api private
+    # @param status [Process::Status] the reaped child status.
+    # @return [String] e.g. "killed by signal 9 (SIGKILL)" or "exit status 1".
+    def describe_status(status)
+      if status.signaled?
+        sig = status.termsig
+        "killed by signal #{sig}#{Signal.signame(sig) ? " (SIG#{Signal.signame(sig)})" : ''}"
+      else
+        "exit status #{status.exitstatus.inspect}"
+      end
     end
 
     # Spawns a fresh `ruby` reading an inline script from stdin. A fork would
@@ -225,6 +251,12 @@ module Mutineer
       fail_test(test_path, "invalid coverage output: #{e.message}")
     end
 
+    # Records a failed coverage capture.
+    #
+    # @api private
+    # @param test_path [String] test file path.
+    # @param reason [String] failure reason.
+    # @return [void]
     def fail_test(test_path, reason)
       rel = relativize(test_path)
       @failed_test_files << rel
@@ -232,10 +264,20 @@ module Mutineer
       nil
     end
 
+    # Builds the framework-specific subprocess script.
+    #
+    # @api private
+    # @param test_path [String] test file path.
+    # @return [String] Ruby script text.
     def subprocess_script(test_path)
       @framework == "rspec" ? rspec_subprocess_script(test_path) : minitest_subprocess_script(test_path)
     end
 
+    # Builds the minitest subprocess script.
+    #
+    # @api private
+    # @param test_path [String] test file path.
+    # @return [String] Ruby script text.
     def minitest_subprocess_script(test_path)
       <<~RUBY
         require "coverage"
@@ -322,6 +364,13 @@ module Mutineer
       File.exist?(absolute(@boot_path)) ? @boot_path : "#{@boot_path}.rb"
     end
 
+    # Groups a digest with its role and paths.
+    #
+    # @api private
+    # @param digest [String] digest string.
+    # @param role [String] digest role.
+    # @param paths [Array<String>] paths in the digest group.
+    # @return [Array(String, String, Array<String>)] grouped digest data.
     def digest_group(digest, role, paths)
       paths.sort.each do |p|
         content = File.read(absolute(p))
@@ -347,8 +396,16 @@ module Mutineer
       end
     end
 
+    # Returns the cache path.
+    #
+    # @api private
+    # @return [String] cache file path.
     def cache_path = File.join(@cache_dir, "coverage.json")
 
+    # Reads the coverage cache.
+    #
+    # @api private
+    # @return [Hash, nil] cached payload.
     def read_cache
       return nil unless File.exist?(cache_path)
 
@@ -357,6 +414,10 @@ module Mutineer
       nil # corrupt cache — rebuild from scratch
     end
 
+    # Saves the coverage cache.
+    #
+    # @api private
+    # @return [void]
     def save
       FileUtils.mkdir_p(@cache_dir)
       data = { "digest" => @digest, "failed_test_files" => @failed_test_files, "map" => @map }
@@ -365,20 +426,41 @@ module Mutineer
       File.rename(tmp, cache_path) # atomic swap
     end
 
+    # Warns when coverage capture was incomplete.
+    #
+    # @api private
+    # @return [void]
     def warn_incomplete
       warn "[mutineer] cached coverage map may be incomplete; these test files " \
            "failed to contribute: #{@failed_test_files.join(', ')}"
     end
 
+    # Returns absolute source paths.
+    #
+    # @return [Array<String>] absolute source paths.
     def abs_source_paths = @source_paths.map { |p| absolute(p) }
+
+    # Returns absolute load paths.
+    #
+    # @return [Array<String>] absolute load paths.
     def abs_load_paths   = @load_paths.map { |p| absolute(p) }
 
+    # Relativizes a path against the project root.
+    #
+    # @api private
+    # @param path [String] path to relativize.
+    # @return [String] relative path.
     def relativize(path)
       return path unless path.start_with?("/")
 
       path.delete_prefix("#{@project_root}/")
     end
 
+    # Expands a path relative to the project root.
+    #
+    # @api private
+    # @param path [String] path to expand.
+    # @return [String] absolute path.
     def absolute(path)
       File.absolute_path?(path) ? path : File.expand_path(path, @project_root)
     end