saboteur 0.11.0 → 0.11.2

data/lib/saboteur/engine/scheduler.rb

@@ -77,6 +77,28 @@ module Saboteur
         deadline(recorded * slowdown)
       end
 
+      # Survivor confirmation (#1063) drives the runner and the coverage map
+      # from outside after the run.
+      attr_reader :runner, :map
+
+      # The eval prefix a post-run confirmation run needs for this subject
+      # (#1063): the same wrapper detection load_problem applies, reduced to
+      # the sorbet sig prefix a survivor could have run with.
+      def confirmation_prefix(subject)
+        return nil unless @verify_loaded
+        return nil if @reevaluator.whole_file?(subject)
+
+        owner = @reevaluator.resolve_owner(subject)
+        target = subject.singleton ? owner.singleton_class : owner
+        method = own_method(target, subject.name)
+        return nil unless method
+
+        file, = method.source_location
+        Execution::Wrapper.around(method, file) == :sorbet ? subject.sig_source : nil
+      rescue Error
+        nil
+      end
+
       private
 
       # Verdicts that did not hold up are warned about once per subject;
@@ -232,26 +254,6 @@ module Saboteur
         result
       end
 
-      attr_reader :runner, :map
-
-      # The eval prefix a post-run confirmation run needs for this subject
-      # (#1063): the same wrapper detection load_problem applies, reduced to
-      # the sorbet sig prefix a survivor could have run with.
-      def confirmation_prefix(subject)
-        return nil unless @verify_loaded
-        return nil if @reevaluator.whole_file?(subject)
-
-        owner = @reevaluator.resolve_owner(subject)
-        target = subject.singleton ? owner.singleton_class : owner
-        method = own_method(target, subject.name)
-        return nil unless method
-
-        file, = method.source_location
-        Execution::Wrapper.around(method, file) == :sorbet ? subject.sig_source : nil
-      rescue Error
-        nil
-      end
-
       # The tests that ran the edited code (a coarse edit spans the whole
       # body, so it gets every test of the method), prior killers first, then
       # fastest-first.
@@ -350,7 +352,7 @@ module Saboteur
       def flaky_message(outcome, rerun)
         decisive = (outcome.failed_ids | rerun.failed_ids).first(3)
         named = decisive.empty? ? "" : " (decisive tests: #{decisive.join(', ')})"
-        "flaky verdict: first #{outcome.status}, then #{rerun.status} on a reordered confirmation " \
+        "#{MutantResult::FLAKY_PREFIX}: first #{outcome.status}, then #{rerun.status} on a reordered confirmation " \
           "run#{named} - the mutant is unverified, not #{outcome.status}"
       end
 

data/lib/saboteur/engine/selection_announcement.rb

@@ -11,12 +11,13 @@ module Saboteur
       private
 
       # A --since diff with no changed source file (a spec-only or docs-only
-      # change) yields zero subjects, so the suite never runs: say there is
-      # nothing to test rather than promise a whole-suite run that does not
-      # happen (#607).
+      # change) yields zero subjects, so the suite never runs: say why no
+      # spec was inferred rather than promise a whole-suite run that does not
+      # happen (#607). The conclusion itself is stated once, by the
+      # "--since <ref>: nothing to test - <reason>" outcome line (#1232).
       def selection_message(guess)
         if guess.changed.zero? && config["since"]
-          "inferred specs: no changed source file to infer a spec for, so there is nothing to test"
+          "inferred specs: no changed source file to infer a spec for"
         elsif guess.changed.zero?
           "inferred specs: no source file to infer a spec for, so the whole suite runs"
         elsif guess.specs.empty?

data/lib/saboteur/engine/subject_selection.rb

@@ -82,7 +82,7 @@ module Saboteur
                    "the resolved range has no changes"
                  elsif !@raw_changed_files.intersect?(@files)
                    "#{count} changed file#{'s' unless count == 1}, none in mutation scope " \
-                     "(docs-only, excluded, or non-Ruby)"
+                     "(specs, docs, excluded, or non-Ruby files)"
                  else
                    "no subject covers the changed lines (layout-only edits, deletions, " \
                      "or intentionally untested code)"
@@ -169,6 +169,11 @@ module Saboteur
           return missed.map { |pattern| missed_pattern_message(pattern) }.join("; ")
         end
 
+        if @config["since"]
+          return "--subject #{missed.join(', ')} matches no subject in the --since #{@config['since']} " \
+                 "diff scope (the scope limits the search to changed files; drop --since or pass --all)"
+        end
+
         "--subject #{missed.join(', ')} matches no subject (patterns are names like " \
           "Klass, Klass#meth or Klass.meth, not globs)"
       end
@@ -180,6 +185,11 @@ module Saboteur
         macro = attribute_macro_for(pattern)
         return "--subject #{pattern} is defined by #{macro} and has no body to mutate" if macro
 
+        if @config["since"]
+          return "--subject #{pattern} matches no subject in the --since #{@config['since']} diff scope " \
+                 "(the scope limits the search to changed files)"
+        end
+
         "fix the --subject pattern \"#{pattern}\": it matches no subject (patterns are names like " \
           "Klass, Klass#meth or Klass.meth, not globs)"
       end

data/lib/saboteur/engine/survivor_confirmation.rb

@@ -44,7 +44,7 @@ module Saboteur
         return unconfirmed(result, "the --max-duration budget is spent") if @budget_exceeded.call
 
         tests = unrun_covering_tests(result)
-        return result if tests.empty?
+        return unconfirmed(result, "no covering tests") if tests.empty?
 
         outcome = run_confirmation(result, tests)
         @remaining -= outcome.runtime || 0

data/lib/saboteur/engine/test_guess.rb

@@ -81,7 +81,7 @@ module Saboteur
           # a file whose own entry broke heard that in the warning (#640).
           mapped = without_map_entry.any? &&
                    " If the layout defeats the naming convention, map #{names(without_map_entry)} by hand in " \
-                   "config/saboteur_custom_map.rb: no entry covers it."
+                   "config/saboteur_custom_map.rb (no entry covers it yet)."
           "no spec found for #{pairs.join(', ')}, so nothing ran.#{changed} Re-run the same command with " \
             "one --test per existing spec path, or append --all to use the whole suite without " \
             "changing the source scope.#{mapped}"

data/lib/saboteur/engine/thread_warnings.rb

@@ -17,10 +17,12 @@ module Saboteur
       # fork_mode, whose default is :both, i.e. attach (RUBY_DEBUG_FORK_MODE;
       # ruby/debug's config.rb and SESSION.activate on_fork: true in
       # session.rb).
+      REAPER = "AR Pool Reaper"
+
       KNOWN_FORK_THREADS = {
-        "AR Pool Reaper" => "ActiveRecord's connection-pool reaper: expected harmless when children " \
-                            "reconnect the database after fork (rails mode does) - it only maintains " \
-                            "the parent's pool",
+        REAPER => "ActiveRecord's connection-pool reaper: expected harmless when children " \
+                  "reconnect the database after fork (rails mode does) - it only maintains " \
+                  "the parent's pool",
         "DEBUGGER__::SESSION@server" => "the debug gem's remote-console server: what it does in " \
                                         "children depends on RUBY_DEBUG_FORK_MODE - with parent no " \
                                         "debugger runs in children; with child or both (the gem's " \
@@ -30,8 +32,11 @@ module Saboteur
                                         "RUBY_DEBUG_OPEN or require \"debug\" without :open"
       }.freeze
 
-      def self.warn(diagnostics)
+      # In rails mode the children reconnect the database, so the pool
+      # reaper is not worth a warning on every run (#1229).
+      def self.warn(diagnostics, rails: false)
         others = Thread.list - [Thread.current]
+        others = others.reject { |thread| thread.name == REAPER } if rails
         return if others.empty?
 
         unknown = false

data/lib/saboteur/engine.rb

@@ -4,6 +4,7 @@
 require "fileutils"
 require "json"
 require_relative "replay"
+require_relative "text"
 require_relative "mutation_source/hazard_guard"
 require_relative "baseline/run_evidence"
 require_relative "engine/early_stop_recording"
@@ -30,6 +31,11 @@ module Saboteur
     include GatedRun
     include SelectionAnnouncement
 
+    # Confirmation only guards a partial coverage map, so it is silent unless
+    # the user opted into partial_coverage = use (#1228).
+    CONFIRMATION_SKIPPED = "survivor confirmation skipped: partial_coverage = use applies only to a cached " \
+                           "whole-suite run (no --test, one coverage part)"
+
     # Everything besides sources and tests that can change a verdict.
     VERDICT_INPUTS = %w[integration require rspec_args rails reeval sources operators exclude_operators arid
                         timeout_factor timeout_min
@@ -51,7 +57,7 @@ module Saboteur
       @replay = Replay.new(digest: digest) if digest
       if capture_evidence && (digest || config["since"] || config["incremental"] || config["resume"] || config["shard"])
         raise ConfigError,
-              "baseline evidence requires fresh whole-scope execution: no since, replay, shard or incremental"
+              "baseline evidence requires fresh whole-scope execution: no since, replay, shard, resume or incremental"
       end
 
       @capture_evidence = capture_evidence
@@ -111,6 +117,24 @@ module Saboteur
       warnings + map.duplicate_keys(path).map { |key| "duplicate custom map key #{key}: Ruby keeps the last" }
     end
 
+    # The map this run selected tests from: survivor presentation compares
+    # it against the cached whole-suite map (review C1).
+    def run_coverage_map
+      @coverage_store&.fetched_map
+    end
+
+    # The cached whole-suite map on this tree, for survivor presentation
+    # in scoped runs; nil when caching is off or no full build ran (review C1).
+    def whole_suite_coverage_map
+      @coverage_store&.whole_suite_map
+    end
+
+    # False when caching is off, where no coverage build can ever leave a
+    # whole-suite map to consult, so advising one would be wrong (review C1).
+    def whole_suite_map_lookup?
+      config["cache"] ? true : false
+    end
+
     private
 
     # Inferred test selection, the default since 0.7.0: scope the run to the
@@ -174,7 +198,7 @@ module Saboteur
                  hazard_suppressions: @diagnostics.hazard_suppressions, early_stop: @early_stop,
                  matrix: config["matrix"], inline_suppressions: @diagnostics.inline_suppressions,
                  operator_policy: config.operator_policy, discovery_failures: @diagnostics.discovery_failures,
-                 test_command: config["test_command"],
+                 test_command: config["test_command"], reuse_label: reuse_label, since: config["since"],
                  shard: @shard, memory: @memory_report, referenced: @guessed_referenced || {})
     end
 
@@ -240,7 +264,11 @@ module Saboteur
     end
 
     def confirm_survivors(results, scheduler, cache, ignore_list)
-      return results unless CoveragePartial.use?(config, config["coverage_parts"])
+      unless CoveragePartial.use?(config, config["coverage_parts"])
+        live = results.any? { |result| result.survived? && !ignore_list.accepts?(result) }
+        @diagnostics.inform(CONFIRMATION_SKIPPED) if live && config["partial_coverage"] == "use"
+        return results
+      end
 
       SurvivorConfirmation.new(config: config, map: scheduler.map, scheduler: scheduler, diagnostics: @diagnostics,
                                budget_exceeded: method(:budget_exceeded?), cache: cache)
@@ -303,16 +331,27 @@ module Saboteur
                                     tests: map.tests.size, cached: @map_cached)
         @diagnostics.quiet_inference(@quiet_spec_count)
       else
-        @diagnostics.inform("#{subjects.size} subjects, #{map.tests.size} tests in coverage map")
+        @diagnostics.inform("#{Text.counted(subjects.size, 'subject')}, " \
+                            "#{Text.counted(map.tests.size, 'test')} in coverage map")
       end
-      ThreadWarnings.warn(@diagnostics)
+      ThreadWarnings.warn(@diagnostics, rails: config["rails"])
+    end
+
+    # This run's map is the whole-suite map only when nothing scoped it:
+    # no --since, no subjects, and tests either unset or inferred over every
+    # included file (never an explicit --test list) (review C1).
+    def whole_suite_run?
+      config["since"].nil? && config["subjects"].empty? &&
+        (config["tests"].empty? || !@guessed_tests.nil?)
     end
 
     def coverage_store(integration, load_lines, load_methods = {})
-      CoverageStore.new(config: config, integration: integration, hooks: hooks, load_lines:, load_methods:,
-                        supervisor: supervisor(memory_factor: 4), diagnostics: @diagnostics,
-                        timeout_cap: method(:budget_capped_timeout),
-                        parts: config["coverage_parts"])
+      @coverage_store ||=
+        CoverageStore.new(config: config, integration: integration, hooks: hooks, load_lines:, load_methods:,
+                          whole_suite_run: whole_suite_run?,
+                          supervisor: supervisor(memory_factor: 4), diagnostics: @diagnostics,
+                          timeout_cap: method(:budget_capped_timeout),
+                          parts: config["coverage_parts"])
     end
 
     def check_baseline(integration, full_passes)
@@ -368,6 +407,15 @@ module Saboteur
                       coverage: map, fallback_files: source_files(files))
     end
 
+    # Which reuse mechanism is on, named as the flag the user typed, so the
+    # terminal's reuse note never cites a flag that was not passed. A replay
+    # runs one mutant fresh by design; it does not reuse, so it gets no label.
+    def reuse_label
+      return nil if @replay
+
+      config["incremental"] ? "--incremental" : ("--resume" if config["resume"])
+    end
+
     def verdict_inputs
       JSON.generate(VERDICT_INPUTS.to_h { |key| [key, config[key]] }.merge("operator_policy" => config.operator_policy))
     end

data/lib/saboteur/execution/fiddle_loader.rb

@@ -24,11 +24,38 @@ module Saboteur
       # free. A LoadError means the sandbox layers cannot work: REFUSE -
       # the error propagates, it is never downgraded to a warning.
       def self.require_fiddle!(with_import: false)
-        require "fiddle"
-        require "fiddle/import" if with_import
+        quietly do
+          require "fiddle"
+          require "fiddle/import" if with_import
+        end
       rescue LoadError
         raise Error, MESSAGE
       end
+
+      # Ruby 3.4 prints "fiddle was loaded from the standard library, but
+      # will no longer be part of the default gems" on this require when the
+      # Gemfile does not name it. The notice is about the user's Gemfile, not
+      # a saboteur fault, and Ruby 4.0 refuses the load outright (MESSAGE
+      # says why), so only that one notice is dropped, only during this
+      # require (#1226).
+      NOTICE = "fiddle was loaded from the standard library"
+
+      module NoticeFilter
+        def warn(message, **)
+          return if Thread.current[:saboteur_fiddle_require] && message.include?(NOTICE)
+
+          super
+        end
+      end
+      Warning.singleton_class.prepend(NoticeFilter)
+
+      def self.quietly
+        previous = Thread.current[:saboteur_fiddle_require]
+        Thread.current[:saboteur_fiddle_require] = true
+        yield
+      ensure
+        Thread.current[:saboteur_fiddle_require] = previous
+      end
     end
   end
 end

data/lib/saboteur/help.rb

@@ -121,7 +121,8 @@ module Saboteur
                      "accept verifies current inputs and publishes it. No scores or execution are suppressed. " \
                      "With --epsilon POINTS, check also fails when the score drops more than POINTS percentage " \
                      "points below the accepted baseline's score. " \
-                     "Only whole or subject scope; no diff, replay, incremental reuse or score threshold.",
+                     "Only whole or subject scope; no diff, replay, shard, resume, incremental reuse or " \
+                     "score threshold.",
         takes_options: true,
         exit_codes: { 0 => "Clean check, proposal written or accepted.",
                       1 => "New, changed or unmatched survivors, or a score drop beyond --epsilon.",
@@ -151,6 +152,17 @@ module Saboteur
                    ["Diff, replay command and ignore template for one mutant",
                     "saboteur survivors .saboteur/report.json --show 1a2b3c4d5e6f7a8b"]]
       ),
+      Command.new(
+        name: "explain",
+        summary: "Explain one mutation operator: definition, example and kill guidance",
+        description: "Prints what one operator does, a before/after example of the mutation, the test " \
+                     "shapes that let it survive, and the assertion that kills it. Covers every operator " \
+                     "the registry can emit.",
+        takes_options: false,
+        exit_codes: { 0 => "Explanation printed.",
+                      2 => "Unknown or missing operator name; the valid names are listed." },
+        examples: [["Why did this mutant survive?", "saboteur explain operand_replacement"]]
+      ),
       Command.new(
         name: "badge",
         summary: "Print a shields.io endpoint badge over the opt-in score history",

data/lib/saboteur/ignore_list.rb

@@ -125,7 +125,7 @@ module Saboteur
     # unscoped_digests (subject id => every digest generated before a diff
     # scope cut) keeps a scoped run from calling a scoped-out entry stale
     # (#284).
-    def apply(results, unscoped_digests: nil)
+    def apply(results, subjects: nil, unscoped_digests: nil, full_run: false)
       seen = {}
       results.each do |result|
         key = [result.subject.id, result.digest]
@@ -139,7 +139,8 @@ module Saboteur
         result.triage_reason = entry.reason
         result.ignored = entry.reason if entry.state != "todo"
       end
-      stale_warnings(results, seen, unscoped_digests)
+      duplicate_warnings + stale_warnings(results, seen, unscoped_digests) +
+        missing_subject_warnings(results, subjects, full_run: full_run)
     end
 
     private
@@ -148,7 +149,39 @@ module Saboteur
       examined = results.to_set { |result| result.subject.id }
       entries.select { |entry| examined.include?(entry.subject) && !seen[[entry.subject, entry.mutation]] }
              .reject { |entry| unscoped_digests&.fetch(entry.subject, nil)&.include?(entry.mutation) }
-             .map { |entry| "stale ignore entry #{entry.subject} #{entry.mutation}: no such mutation" }
+             .map { |entry| stale_message(entry) }
+    end
+
+    # Entries naming the same (subject, mutation) more than once: the index
+    # keeps the last one, which is invisible otherwise (#1207).
+    def duplicate_warnings
+      entries.group_by { |entry| [entry.subject, entry.mutation] }
+             .reject { |_, group| group.one? }
+             .map { |(subject, mutation), _| "duplicate ignore entry #{subject} #{mutation}: the last entry wins" }
+    end
+
+    # A full run examines every in-scope subject, so an entry whose subject
+    # never appears points at code that was renamed or removed - say so, but
+    # only then: a scoped (--since/--subject) run cannot tell "renamed" from
+    # "not in this diff" (#1206). The run's subject list is the source of
+    # truth when given: an examined subject with no results (uncovered, or
+    # nothing mutable left) is not missing.
+    def missing_subject_warnings(results, subjects, full_run:)
+      return [] unless full_run
+
+      examined = (subjects || results).to_set { |item| item.respond_to?(:id) ? item.id : item.subject.id }
+      entries.reject { |entry| examined.include?(entry.subject) }
+             .map { |entry| missing_subject_message(entry) }
+    end
+
+    def missing_subject_message(entry)
+      "stale ignore entry #{entry.subject} #{entry.mutation}: subject not found " \
+        "(renamed, removed, or its file is excluded?) - remove the entry or fix the subject name"
+    end
+
+    def stale_message(entry)
+      "stale ignore entry #{entry.subject} #{entry.mutation}: no such mutation " \
+        "- remove the entry or refresh its digest (saboteur survivors --show)"
     end
   end
 end

data/lib/saboteur/install.rb

@@ -32,6 +32,9 @@ module Saboteur
       end
     RUBY
 
+    BASE_CLASSES = %w[app/models/application_record.rb app/controllers/application_controller.rb
+                      app/jobs/application_job.rb app/mailers/application_mailer.rb].freeze
+
     BIN = <<~RUBY
       #!/usr/bin/env ruby
       # frozen_string_literal: true
@@ -64,19 +67,31 @@ module Saboteur
 
     # Returns the list of Results (:created, :overwritten, :skipped, :appended, :unchanged).
     def call
-      [write("config/saboteur.rb", CONFIG), write("bin/saboteur", BIN, mode: 0o755), gitignore]
+      [write("config/saboteur.rb", config_text), write("bin/saboteur", BIN, mode: 0o755), gitignore]
     end
 
-    # Printed after install; the Gemfile is never edited.
+    RUN_HINT = "Next: bin/saboteur doctor, then bin/saboteur run --since origin/main " \
+               "(keep SimpleCov off for the run)."
+
+    # Printed after install; the Gemfile is never edited. The run pointer is
+    # always due: the Gemfile block only when the gem is missing.
     def gemfile_hint
       gemfile = File.join(@root, "Gemfile")
-      return nil if File.file?(gemfile) && Text.utf8(File.read(gemfile)).match?(/^\s*gem\s+["']saboteur["']/)
+      return RUN_HINT if File.file?(gemfile) && Text.utf8(File.read(gemfile)).match?(/^\s*gem\s+["']saboteur["']/)
 
       GEMFILE_HINT
     end
 
     private
 
+    # CONFIG without the base-class excludes this app does not have: a
+    # minimal Rails app has no ApplicationJob or ApplicationMailer, and an
+    # exclude that matches no file makes doctor and every run warn.
+    def config_text
+      BASE_CLASSES.reject { |path| File.exist?(File.join(@root, path)) }
+                  .reduce(CONFIG) { |text, path| text.sub(%(    "#{path}",\n), "") }
+    end
+
     # Never writes or chmods through a symlink: not the file itself, and not a
     # symlinked directory above it (bin -> elsewhere). Without force the file is
     # skipped; with force the link is removed and replaced by a real file or

data/lib/saboteur/mutation_source/builtin.rb

@@ -13,6 +13,7 @@ require_relative "pair_removal"
 require_relative "element_removal"
 require_relative "endpoint_replacement"
 require_relative "operator_registry"
+require_relative "operator_explain"
 require_relative "range_replacement"
 require_relative "operator_assignment"
 require_relative "condition_negation"

data/lib/saboteur/mutation_source/operator_explain.rb

@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "operator_examples"
+require_relative "operator_registry"
+
+module Saboteur
+  module MutationSource
+    # Curated text behind `saboteur explain NAME`. The definition and the
+    # example stay shared with --list-operators (one wording source); the
+    # survival and kill hints below are the only text owned here. Every
+    # registry operator needs an entry: the coverage spec fails the build
+    # when one ships without it.
+    module OperatorExplain
+      Entry = Data.define(:name, :definition, :example, :survives, :kill)
+
+      GUIDANCE = {
+        "body_nil" => {
+          survives: "the method is called for side effects and no test asserts the return value.",
+          kill: "an assertion on the exact return value, or on a caller behaviour that depends on it."
+        },
+        "body_true" => {
+          survives: "tests never check the predicate outcome, or only take the path true already forces.",
+          kill: "an example whose input makes the predicate false, asserting that path is taken."
+        },
+        "body_false" => {
+          survives: "tests never check the predicate outcome, or only take the path false already forces.",
+          kill: "an example whose input makes the predicate true, asserting that path is taken."
+        },
+        "body_raise" => {
+          survives: "tests stub or skip the method, or wrap the call in a broad rescue.",
+          kill: "any test that calls the method and lets it complete; the raise fails that example."
+        },
+        "comparison" => {
+          survives: "tests never use values at the boundary the change moves, such as equal values for < vs <=.",
+          kill: "a boundary example: the equal case, or the two values just either side of the operator."
+        },
+        "arithmetic" => {
+          survives: "tests assert the result loosely (type, presence, sign) instead of its exact value.",
+          kill: "an assertion on the exact computed value with operands where the two operators differ."
+        },
+        "boolean_logic" => {
+          survives: "tests never exercise the dropped operand deciding the outcome on its own.",
+          kill: "one example per operand where that operand alone flips the result, asserting each outcome."
+        },
+        "condition_true" => {
+          survives: "tests only exercise the branch the forced condition takes.",
+          kill: "an example with a falsy input, asserting the else branch still runs."
+        },
+        "condition_false" => {
+          survives: "tests only exercise the branch the forced condition takes.",
+          kill: "an example with a truthy input, asserting the then branch still runs."
+        },
+        "negation_removal" => {
+          survives: "tests assert loosely, or never cover the input the negation inverts.",
+          kill: "assert the behaviour for both a truthy and a falsy input through the public API."
+        },
+        "literal_number" => {
+          survives: "the literal flows into nothing a test asserts, or every fixture value works for both.",
+          kill: "an assertion on the exact value the literal feeds (a total, a limit, an index)."
+        },
+        "or_assign" => {
+          survives: "tests only cover the nil or false case, where both forms assign.",
+          kill: "an example where the variable is already truthy and must keep its value."
+        },
+        "and_assign" => {
+          survives: "tests only cover the truthy case, where both forms assign.",
+          kill: "an example where the variable is falsy and must stay untouched."
+        },
+        "safe_navigation" => {
+          survives: "the receiver is never nil in any covering test.",
+          kill: "an example with a nil receiver asserting nil comes back instead of NoMethodError."
+        },
+        "statement_removal" => {
+          survives: "the removed statement's effect is never observed: an unasserted side effect or return.",
+          kill: "assert the side effect (a spy, a state change) or the value the statement produced."
+        },
+        "copy_replacement" => {
+          survives: "tests never mutate the returned object, so the aliasing goes unnoticed.",
+          kill: "mutate what the method returns and assert the original is unchanged (or assert a copy)."
+        },
+        "filter_replacement" => {
+          survives: "tests assert loosely, or the fixture collection is empty or all one kind.",
+          kill: "assert the exact surviving elements of a mixed collection, in order."
+        },
+        "literal_string" => {
+          survives: "no test asserts the string's content, only that something was returned.",
+          kill: "an exact string equality assertion on the value that carries the literal."
+        },
+        "literal_boolean" => {
+          survives: "the boolean is never asserted, or both values pass the covering assertions.",
+          kill: "an example whose expected behaviour flips with the boolean."
+        },
+        "argument_swap" => {
+          survives: "tests use equal or interchangeable arguments, or assert the result loosely.",
+          kill: "asymmetric arguments with an assertion on the exact result order."
+        },
+        "argument_removal" => {
+          survives: "the removed argument changes nothing the covering tests observe.",
+          kill: "a case where that argument changes the result, asserted exactly."
+        },
+        "pair_removal" => {
+          survives: "tests never read the removed key, directly or through a consumer.",
+          kill: "assert the value stored under the removed key, or the whole hash."
+        },
+        "element_removal" => {
+          survives: "tests never exercise the removed element of the array.",
+          kill: "an example per element whose behaviour changes when that element is missing."
+        },
+        "endpoint_replacement" => {
+          survives: "fixture collections have one element, or the wrong end is never asserted.",
+          kill: "a multi-element collection with an assertion on exactly which end comes back."
+        },
+        "chain_removal" => {
+          survives: "in every tested case the skipped call returns an equivalent value.",
+          kill: "a case where the removed call changes the value, asserted exactly."
+        },
+        "range" => {
+          survives: "tests never use the endpoint the exclusive range drops.",
+          kill: "an example whose input is the boundary value, asserting it is included."
+        },
+        "operator_assignment" => {
+          survives: "tests check the variable changed, not its exact new value.",
+          kill: "assert the exact value after the assignment, where += and -= disagree."
+        },
+        "condition_negation" => {
+          survives: "tests only cover the side of the predicate the negation keeps.",
+          kill: "assert both branches with inputs on each side of the predicate."
+        },
+        "method_swap" => {
+          survives: "tests assert loosely, or min and max coincide in every fixture.",
+          kill: "a fixture where the two methods differ, asserting the exact expected one."
+        },
+        "operand_replacement" => {
+          survives: "tests assert the result loosely (present, positive, non-nil) or never exercise " \
+                    "the removed operand.",
+          kill: "an assertion on the exact value through the public API, with inputs where the " \
+                "removed operand changes the result."
+        },
+        "interpolation_removal" => {
+          survives: "no test asserts the full interpolated content of the string.",
+          kill: "an exact string assertion with a known value in the interpolation."
+        },
+        "jump_value" => {
+          survives: "callers ignore the returned value, or tests never take that return path.",
+          kill: "an example that takes the early return and asserts the exact value it hands back."
+        },
+        "rescue_removal" => {
+          survives: "tests never raise the error the handler rescues.",
+          kill: "an example raising that error, asserting the handler's fallback behaviour."
+        },
+        "ensure_removal" => {
+          survives: "the cleanup's effect is never observed on the tested paths.",
+          kill: "assert the cleanup ran (resource released, flag reset), including on the error path."
+        },
+        "when_removal" => {
+          survives: "tests never hit the removed branch of the case.",
+          kill: "one example per when branch, asserting its exact outcome."
+        },
+        "unary_removal" => {
+          survives: "fixtures use zero or symmetric values, or tests assert loosely.",
+          kill: "an assertion on the exact signed or complemented value with a non-trivial input."
+        },
+        "regex_replacement" => {
+          survives: "every test input matches under both the original and the loosened regex.",
+          kill: "an input the anchor or quantifier excludes, asserting it is rejected."
+        }
+      }.freeze
+
+      # nil for an unknown name; the command turns that into the exit-2 error.
+      def self.for(name)
+        return unless OperatorRegistry::DESCRIPTIONS.key?(name)
+
+        guidance = GUIDANCE.fetch(name)
+        Entry.new(name:, definition: OperatorRegistry::DESCRIPTIONS.fetch(name),
+                  example: OperatorExamples::EXAMPLES.fetch(name),
+                  survives: guidance.fetch(:survives), kill: guidance.fetch(:kill))
+      end
+    end
+  end
+end