mutineer 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae2c0b5167b5070a3afc7834ffa6d4d012267b070dd6b73f3d95affa3752c4c0
-  data.tar.gz: 22a328c5b5446d8c937288763d5ab050869b49b58c0bee715c3ec9dbb54005fd
+  metadata.gz: a8687c96cedac16e86197f3639803487657512509c45a1969449eb95b3c4b65c
+  data.tar.gz: 59588c405f16476b984fefbda003299f8373687cacd40c4569ea72edb866d0a9
 SHA512:
-  metadata.gz: 858c634ce049e4a55ee2c94151a11df0b620edb19630d53719bf94cf6efa9212a4bd6d55c67607a1447ff42fed7804293ae3ec8c28b703b6478f2324aa5593b9
-  data.tar.gz: 2c47217873142ba8dbdffe1adbeb3772532925a951a2d52f058ca4b5e26732877019299de6a98c5c68ad89a5d9c6f8513b06ac424806fe7258e4ef1a7e305a27
+  metadata.gz: edf0bff64186f9719f4de85a0672e7b6614d161aa02b87b63600ebdb2e82e744ef706fd0db29a990d159be3ed422a35b9e3fd7d505595ca585e483fe9ababce1
+  data.tar.gz: 1e41589e16979a227b9a479504574d939ff5f91077535723e1b3cfc87e53fa20475e1ba1c09dce910b9644bc002f631ac5001d60737a98a9940ab06ea7dbb023

data/CHANGELOG.md

@@ -4,6 +4,52 @@ 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.9.0] - 2026-06-30
+
+### Added
+- **`--fail-fast`** (#21) — stop at the first surviving mutant; in-flight workers
+  drain, the rest are skipped. Fast red signal for PR gates.
+- **`--format html`** (#23) — a single self-contained HTML report (inline CSS, no
+  external assets) with the score, per-source table, and a card per survivor
+  (subject, file:line, operator, stable id, diff).
+- **String, regex, and collection-method operators** (#24, Tier-2, opt-in via
+  `--operators`): `string_literal`, `regex`, `collection_method`
+  (`map`↔`each`, `all?`↔`any?`, `first`↔`last`, `min`↔`max`, `select`↔`reject`).
+
+### Changed
+- **`--dry-run` now honors suppression** (#22) — inline `# mutineer:disable-line`
+  and `.mutineer.yml` `ignore:` entries are omitted from the preview and counted
+  as "ignored (suppressed)", matching a real run.
+
+## [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.)
+- **Write-heavy Rails tests are capturable again** (#19) — capture/worker pipes
+  are `binmode`: a binary Marshal payload over a text-mode pipe could raise an
+  encoding error the child then swallowed → empty pipe → false `:uncapturable`.
+  That was the root cause of the residual write-heavy failures too. A child that
+  dies without writing now also reports how it died (exit status / signal), and
+  `--verbose` always surfaces a real reason. Verified on a real Rails app: all 6
+  previously-uncapturable interactors (incl. caxlsx + Google-client) now capture
+  with real scores, 0 uncapturable.
+
+## [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 +175,9 @@ 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.9.0]: https://github.com/davidteren/mutineer/releases/tag/v0.9.0
+[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](https://img.shields.io/badge/Socket-security%20report-0a66c2?logo=socket&logoColor=white)](https://socket.dev/rubygems/package/mutineer)
 
 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
@@ -54,9 +56,10 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 | `--jobs N` | Parallel worker count (default: processor count; `1` under `--rails`) |
 | `--verbose` | Surface the real error when a fork capture fails (alias `--debug`) |
 | `--strategy NAME` | Mutation application: `reload` whole-file (default) or `redefine` surgical (`7a`/`7b` accepted as deprecated aliases) |
-| `--format human\|json` | Report format (default: human) |
+| `--format human\|json\|html` | Report format (default: human; `html` is a self-contained file) |
 | `--output FILE` | Write the report to FILE instead of stdout |
-| `--dry-run` | List candidate mutations without executing |
+| `--dry-run` | List candidate mutations without executing (honors suppression) |
+| `--fail-fast` | Stop at the first surviving mutant |
 | `--list-operators` | List available operators (default vs optional) and exit |
 | `--version`, `--help` | Print version / usage and exit |
 
@@ -73,7 +76,8 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 Run `mutineer --list-operators` to see them. Default (Tier 1): `arithmetic`,
 `comparison`, `boolean_connector`, `boolean_literal`, `statement_removal`.
 Available but off by default (Tier 2, enable via `--operators`): `return_nil`,
-`literal_mutation`, `condition_negation`.
+`literal_mutation`, `condition_negation`, `string_literal`, `regex`,
+`collection_method`.
 
 ## Rails apps
 
@@ -124,6 +128,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]
 
@@ -46,9 +47,10 @@ module Mutineer
         --boot FILE          Require FILE once in the parent to boot the app env, then
                              fork per mutant (Rails apps; requires --test)
         --rails              Sugar for --boot config/environment --strategy redefine
-        --format human|json  Report format (default: human)
+        --format human|json|html  Report format (default: human)
         --output FILE        Write the report to FILE instead of stdout
         --dry-run            List mutations without executing
+        --fail-fast          Stop at the first surviving mutant
         --verbose            Surface the real error when a fork capture fails (alias: --debug)
 
       Options:
@@ -63,6 +65,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)
@@ -80,6 +86,7 @@ module Mutineer
         end
         o.on("--list-operators") { show_operators = true }
         o.on("--dry-run") { opts[:dry_run] = true }
+        o.on("--fail-fast") { opts[:fail_fast] = true }
         o.on("--only NAME") { |v| opts[:only] = v; explicit << :only }
         o.on("--since REF") { |v| opts[:since] = v; explicit << :since }
         o.on("--test FILE") { |v| (opts[:tests] ||= []) << v }
@@ -140,6 +147,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 +158,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 +192,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"
@@ -190,8 +211,8 @@ module Mutineer
       end
       config.jobs = jobs
 
-      unless %w[human json].include?(config.format)
-        warn %(mutineer: unknown format "#{config.format}". Expected: human, json)
+      unless %w[human json html].include?(config.format)
+        warn %(mutineer: unknown format "#{config.format}". Expected: human, json, html)
         exit 2
       end
 
@@ -231,6 +252,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 +278,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 +299,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 +330,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 +342,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 +356,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)"
@@ -328,7 +379,7 @@ module Mutineer
 
       # #14: nudge toward the opt-in tier-2 operators (human report only — never
       # pollute JSON output).
-      if config.format != "json" && (hint = tier2_hint(config.operators))
+      if !%w[json html].include?(config.format) && (hint = tier2_hint(config.operators))
         puts hint
       end
 
@@ -340,6 +391,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,11 +404,17 @@ 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 = {}
       per_operator = Hash.new(0)
       skipped = 0
+      ignored = 0
+      ignore_set = config.ignore.to_set
 
       # --since narrows the preview to changed lines too, so `--dry-run --since`
       # shows exactly what a real `--since` run would mutate.
@@ -364,29 +425,36 @@ module Mutineer
 
       Project.discover(config.sources, only: config.only).each do |subject|
         source = (sources[subject.file] ||= Parser.parse_file(subject.file).source.source)
-        operator_classes.each do |klass|
-          klass.new.mutations_for(subject, source).each do |mutation|
-            unless mutation.valid?(source)
-              skipped += 1
-              next
-            end
-            if changed
-              line = source.byteslice(0, mutation.start_offset).count("\n") + 1
-              next unless changed[File.expand_path(subject.file, config.project_root)]&.include?(line)
-            end
-            per_operator[mutation.operator] += 1
-            original = source.byteslice(mutation.start_offset...mutation.end_offset)
-            line = source.byteslice(0, mutation.start_offset).count("\n") + 1
-            puts "[#{mutation.operator}] #{subject.qualified_name}  " \
-                 "#{subject.file}:#{line}  `#{original}` -> `#{mutation.replacement}`"
+        # #22: honor suppression so the preview matches what a real run mutates.
+        # Mirror execute's per-subject shape (ids need the full mutation list).
+        disabled = Runner.suppress_map(source)
+        mutations = operator_classes.flat_map { |klass| klass.new.mutations_for(subject, source) }
+        ids = MutantId.for_subject(subject, source, mutations)
+        mutations.each_with_index do |mutation, i|
+          unless mutation.valid?(source)
+            skipped += 1
+            next
           end
+          line = source.byteslice(0, mutation.start_offset).count("\n") + 1
+          next if changed && !changed[File.expand_path(subject.file, config.project_root)]&.include?(line)
+
+          if Runner.suppressed?(mutation.operator, line, ids[i], disabled, ignore_set)
+            ignored += 1
+            next
+          end
+
+          per_operator[mutation.operator] += 1
+          original = source.byteslice(mutation.start_offset...mutation.end_offset)
+          puts "[#{mutation.operator}] #{subject.qualified_name}  " \
+               "#{subject.file}:#{line}  `#{original}` -> `#{mutation.replacement}`"
         end
       end
 
       total = per_operator.values.sum
       breakdown = per_operator.map { |op, n| "#{op}: #{n}" }.join(", ")
       summary = breakdown.empty? ? "" : "#{breakdown} — "
-      puts "#{summary}#{total} mutations (dry run, not executed); #{skipped} skipped (invalid)"
+      puts "#{summary}#{total} mutations (dry run, not executed); " \
+           "#{skipped} skipped (invalid); #{ignored} ignored (suppressed)"
       exit 0
     end
   end

data/lib/mutineer/config.rb

@@ -25,12 +25,13 @@ module Mutineer
     :cache_dir, :project_root, :load_paths,
     :jobs, :format, :output, :strategy, :require_paths,
     :boot, :rails, :since, :framework, :verbose, :ignore,
-    :baseline, :baseline_epsilon,
+    :baseline, :baseline_epsilon, :fail_fast,
     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
+    KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework verbose ignore baseline fail_fast].freeze
 
     def initialize(**kwargs)
       super
@@ -49,6 +50,7 @@ module Mutineer
       self.verbose       = false if verbose.nil?
       self.ignore        ||= []
       self.baseline_epsilon ||= 0.0
+      self.fail_fast     = false if fail_fast.nil?
     end
 
     # Walk from `start` toward `home`, returning the first .mutineer.yml path found
@@ -128,16 +130,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 +173,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|