saboteur 0.11.1 → 0.11.2

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
-      duplicate_warnings + 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
@@ -159,6 +160,25 @@ module Saboteur
              .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)"

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

data/lib/saboteur/reporter/agent_commands.rb

@@ -45,14 +45,30 @@ module Saboteur
 
           # Replay one survivor by digest in the same selection. capped: false
           # skips the protocol byte cap, for callers that print to a terminal.
-          def replay(provenance, digest, capped: true)
-            words = ["saboteur", "run", "--id", digest, *selection(provenance, replay: true), "--seed",
-                     provenance.seed.to_s]
+          # report: narrows the replay to the mutant's covering spec files
+          # instead of the run's full inferred list (#1148).
+          def replay(provenance, digest, capped: true, report: nil)
+            words = ["saboteur", "run", "--id", digest,
+                     *selection(provenance, replay: true, tests: report && covering_files(report, digest)),
+                     "--seed", provenance.seed.to_s]
             finish(words, provenance, capped: capped)
           end
 
           private
 
+          # A replay needs only the specs that cover the mutant, not every
+          # inferred file (#1148): covered_by holds RSpec ids like
+          # "./spec/fee_spec.rb[1:2]", so strip the example suffix. nil when
+          # the survivor has no covering ids - then the whole selection
+          # stays, since dropping it would widen the replay to inference.
+          def covering_files(report, digest)
+            result = report.results.find { |entry| entry.digest == digest }
+            return unless result
+
+            files = result.covered_by.filter_map { |id| id[%r{\A\.?/?(.+?\.rb)\[}, 1] }.uniq
+            files unless files.empty?
+          end
+
           def finish(words, provenance, capped: true)
             words += ["--", *provenance.sources] unless provenance.sources.empty?
             command = Shellwords.join(words)
@@ -93,13 +109,14 @@ module Saboteur
 
           # Whole-suite scope is a bare --all, only when no tests resolved;
           # --all never combines with --test.
-          def selection(provenance, replay: false)
+          def selection(provenance, replay: false, tests: nil)
+            tests ||= provenance.tests
             words = []
             words.push("--config", provenance.config_path) if provenance.config_path
             words.push("--since", provenance.ref) if provenance.ref
             provenance.subjects.each { |subject| words.push("--subject", subject) }
-            words << "--all" if provenance.settings[:all] && provenance.tests.empty?
-            words.push(*test_words(provenance.tests))
+            words << "--all" if provenance.settings[:all] && tests.empty?
+            words.push(*test_words(tests))
             words.concat(setting_words(provenance, replay: replay))
             words.concat(mode_words(provenance))
             words.push("--id", provenance.digest) if provenance.digest && !replay

data/lib/saboteur/reporter/agent_incomplete.rb

@@ -40,8 +40,7 @@ module Saboteur
             add(reasons, "mutant_cap", omitted_by_cap(report), "mutants omitted by max_mutants_per_method")
             add(reasons, "errors", report.counts[:error], "mutants errored; their verdict did not hold up")
             add(reasons, "resource_limit", report.counts[:resource_limit], "mutants hit the memory or process cap")
-            add(reasons, "unverified", report.counts[:unverified],
-                "mutants the --max-duration budget left unverified; their kills are not confirmed")
+            unverified_reasons(reasons, report)
             discovery_failures(reasons, report)
             early_stop_reason(reasons, report)
             inline_scope(reasons, report)
@@ -70,6 +69,14 @@ module Saboteur
                 "included untracked files could not be read; their subjects were not covered")
           end
 
+          def unverified_reasons(reasons, report)
+            flaky = report.results.count(&:flaky?)
+            add(reasons, "unverified", report.counts[:unverified] - flaky,
+                "mutants the --max-duration budget left unverified; their kills are not confirmed")
+            add(reasons, "flaky", flaky,
+                "mutants gave a different verdict on the --flaky-check reordered rerun; they are unverified")
+          end
+
           def early_stop_reason(reasons, report)
             stop = report.early_stop
             return unless stop

data/lib/saboteur/reporter/agent_summary.rb

@@ -123,7 +123,8 @@ module Saboteur
             steps = {}
             add_command(steps, :rerun, Commands.rerun(provenance))
             first = Findings.build(report)[:survivors].first
-            add_command(steps, :replay, Commands.replay(provenance, first[:digest])) if first
+            # report: narrows the replay to covering specs, as on the run screen (#1148).
+            add_command(steps, :replay, Commands.replay(provenance, first[:digest], report: report)) if first
             steps[:fullReport] = provenance.json_report if short_path?(provenance.json_report)
             steps
           end

data/lib/saboteur/reporter/gap_kinds.rb

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    # The gap-kind vocabulary (D2): which sort of check a survivor suggests
+    # is missing, as a LABEL ONLY (#192) - a heuristic from the operator and
+    # the edit shape, never a diagnosis, and never a score input.
+    module GapKinds
+      KINDS = %w[boundary branch effect number] + ["error path", "result unchecked"].freeze
+
+      # Operator -> gap kind, every built-in operator exactly once except
+      # operand_replacement, whose kind depends on the replaced expression
+      # (a comparison loses its boundary; anything else is a plain result).
+      # Anything missing here - a new operator before its row lands - is
+      # the honest fallback: result unchecked.
+      BY_OPERATOR = {
+        "comparison" => "boundary",
+        "range" => "boundary",
+        "endpoint_replacement" => "boundary",
+        "condition_negation" => "branch",
+        "condition_true" => "branch",
+        "condition_false" => "branch",
+        "boolean_logic" => "branch",
+        "negation_removal" => "branch",
+        "when_removal" => "branch",
+        "safe_navigation" => "branch",
+        "filter_replacement" => "branch",
+        "statement_removal" => "effect",
+        "element_removal" => "effect",
+        "argument_removal" => "effect",
+        "pair_removal" => "effect",
+        "chain_removal" => "effect",
+        "copy_replacement" => "effect",
+        "literal_number" => "number",
+        "arithmetic" => "number",
+        "unary_removal" => "number",
+        "operator_assignment" => "number",
+        "rescue_removal" => "error path",
+        "ensure_removal" => "error path",
+        "body_raise" => "error path",
+        "body_nil" => "result unchecked",
+        "body_true" => "result unchecked",
+        "body_false" => "result unchecked",
+        "literal_string" => "result unchecked",
+        "literal_boolean" => "result unchecked",
+        "or_assign" => "result unchecked",
+        "and_assign" => "result unchecked",
+        "argument_swap" => "result unchecked",
+        "method_swap" => "result unchecked",
+        "interpolation_removal" => "result unchecked",
+        "jump_value" => "result unchecked",
+        "regex_replacement" => "result unchecked"
+      }.freeze
+
+      # The one operator whose kind comes from the edit shape, not the name.
+      SHAPE_DECIDED = %w[operand_replacement].freeze
+
+      FALLBACK = "result unchecked"
+
+      # The deterministic per-kind reason printed next to a survivor's rank.
+      REASONS = {
+        "boundary" => "the covering specs pass without pinning this boundary",
+        "branch" => "the covering specs pass without pinning this branch",
+        "effect" => "the covering specs pass without pinning this effect",
+        "number" => "the covering specs pass without pinning this number",
+        "error path" => "the covering specs pass without pinning this error path",
+        "result unchecked" => "the covering specs pass without pinning this result"
+      }.freeze
+
+      module_function
+
+      def kind(operator, comparison_edit: false)
+        return comparison_edit ? "boundary" : FALLBACK if SHAPE_DECIDED.include?(operator)
+
+        BY_OPERATOR.fetch(operator, FALLBACK)
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/html.rb

@@ -6,6 +6,7 @@ require "fileutils"
 
 require_relative "../survivor_guidance"
 require_relative "survivor_classification"
+require_relative "wording"
 
 module Saboteur
   module Reporter
@@ -151,11 +152,13 @@ module Saboteur
       def headline(report)
         breakdown = report.score_breakdown
         text = "<p><strong>Covered mutation score: #{score_text(report.score)}</strong>"
-        text << " (#{breakdown.detected}/#{breakdown.tested} killed, tested subjects)" if breakdown.tested.positive?
+        if breakdown.tested.positive?
+          text << " (#{breakdown.detected}/#{breakdown.tested} #{Wording.detected_word(breakdown)}, tested subjects)"
+        end
         untested = report.skipped_subjects.count { |_, reason| reason == ScoreTable::NO_COVERAGE }
         if untested.positive?
           noun = untested == 1 ? "subject" : "subjects"
-          text << " - #{untested} #{noun} not scored - no tests exist"
+          text << " - #{untested} #{noun} not scored - #{Wording.no_execution(untested)}"
         end
         "#{text}</p>"
       end
@@ -187,13 +190,18 @@ module Saboteur
           "the score covers those changes, not the whole project.</p>"
       end
 
+      # "1 subject, 2 mutants": each count pluralizes on its own (C9).
+      def counts_note(report)
+        "#{Text.counted(report.subjects.size, 'subject')}, #{Text.counted(report.results.size, 'mutant')}"
+      end
+
       def summary(report, data)
         seed = data.dig(:config, :seed)
         seed_note = seed ? ", seed #{seed}" : ""
         counts = data[:files].values.flat_map { |entry| entry[:mutants] }.map { |mutant| mutant[:status] }.tally
         <<~HTML
           <p><strong>Covered mutation score: #{score_text(report.score)}</strong>
-          (#{report.subjects.size} subjects, #{report.results.size} mutants, #{format('%.1f', report.wall_time)}s#{seed_note})</p>
+          (#{counts_note(report)}, #{format('%.1f', report.wall_time)}s#{seed_note})</p>
           <p class="note">Covered mutation score = #{SCORE_FORMULA}. NoCoverage, errors, resource limits and skipped
           mutants are not counted. Survivors accepted on the ignore list stay in the denominator. It covers only the subjects of this run, not the whole project. A tool that reads the
           Stryker JSON may show a different score, because the schema counts NoCoverage as undetected.</p>
@@ -310,7 +318,10 @@ module Saboteur
 
       def file_section(file, entry, names, results, report, survivor_count:, open_file:)
         open = open_file ? " open" : ""
-        ordered = entry[:mutants].sort_by { |mutant| position_key(mutant) }
+        # Attention rows (survivors, timeouts, errors) come first, so a big
+        # file's survivors are not buried between killed rows; position
+        # order holds within each group (#1233).
+        ordered = entry[:mutants].sort_by { |mutant| [attention_rank(mutant), *position_key(mutant)] }
         rows = ordered.map { |mutant| mutant_row(mutant, names, results[[file, mutant[:id]]], report) }
         "<details class=\"file\"#{open}><summary>#{escape(file)} " \
           "(#{entry[:mutants].size} mutants#{survivors_note(survivor_count, open_file)})</summary>\n" \
@@ -330,6 +341,10 @@ module Saboteur
         open_file || survivor_count.zero? ? "" : ", #{survivor_count} survivor#{'s' unless survivor_count == 1}"
       end
 
+      def attention_rank(mutant)
+        ATTENTION_STATUSES.include?(mutant[:status]) ? 0 : 1
+      end
+
       def position_key(mutant)
         start = mutant[:location][:start]
         [start[:line], start[:column], mutant[:id]]

data/lib/saboteur/reporter/review_comments.rb

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "gap_kinds"
+
 module Saboteur
   module Reporter
     # Pull-request review comments for surviving mutants (#246): decides what
@@ -25,11 +27,10 @@ module Saboteur
       # Labels whose survivors are probably noise: never worth a comment.
       QUIET = %w[likely_equivalent arid].freeze
 
-      HINTS = {
-        "missing_test" => "A test reaches this line and still passes with the change. " \
-                          "Add an assertion that pins this behaviour.",
-        "tool_limit" => "Saboteur could not observe this mutant faithfully. Check it by hand."
-      }.freeze
+      GAP_HINT = "A test reaches this line and still passes with the change. " \
+                 "Add an assertion that pins this behaviour."
+      TOOL_LIMIT_HINT = "Saboteur could not observe this mutant faithfully. Check it by hand."
+      HINTS = GapKinds::KINDS.to_h { |label| [label, GAP_HINT] }.merge("tool_limit" => TOOL_LIMIT_HINT).freeze
       DEFAULT_HINT = "No test fails with this change. Check whether a test should pin it."
 
       Plan = Struct.new(:post, :delete, :summary, keyword_init: true)

data/lib/saboteur/reporter/score_table.rb

@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "wording"
 require_relative "../score"
 
 module Saboteur
@@ -62,7 +63,7 @@ module Saboteur
           detected: breakdown.detected, tested: breakdown.tested, untested: untested }
       end
 
-      # "cart.rb  100.0% (2/2) · n/a - 2 subjects have no tests: ...": the
+      # "cart.rb  100.0% (2/2) · n/a - 2 subjects - no test executes them: ...": the
       # tested score and the untested count stand next to each other; a
       # file with nothing tested gets no percentage at all.
       def line(row, width)
@@ -74,18 +75,18 @@ module Saboteur
         note ? "#{base} #{@palette.glyph(:middot)} #{note}" : base
       end
 
-      # "n/a - 2 subjects have no tests: Cart#total, Cart#biggest": names
-      # the subjects the score cannot speak for, capped so a long list does
-      # not swallow the row; the Not scored block lists them all.
+      # "n/a - 2 subjects - no test executes them: Cart#total, Cart#biggest":
+      # names the subjects the score cannot speak for, capped so a long
+      # list does not swallow the row; the Not scored block lists them all.
+      # Wording owns the claim (#1145): a stubbed-away subject has tests,
+      # they just never execute it.
       def untested_note(untested)
         return if untested.empty?
 
         names = untested.map(&:id)
         shown = names.first(MAX_UNTESTED_NAMES)
         shown << "+#{names.size - MAX_UNTESTED_NAMES} more" if names.size > MAX_UNTESTED_NAMES
-        count = untested.size
-        @palette.paint(:warn, "n/a - #{count} subject#{'s' unless count == 1} " \
-                              "#{count == 1 ? 'has' : 'have'} no tests: #{shown.join(', ')}")
+        @palette.paint(:warn, "n/a - #{Wording.untested_note(untested.size)}: #{shown.join(', ')}")
       end
     end
   end

data/lib/saboteur/reporter/survivor_classification.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require_relative "../engine/bytecode_equivalence"
+require_relative "gap_kinds"
 require_relative "../execution/external_runner"
 require_relative "../mutation_source/builtin"
 
@@ -21,11 +22,14 @@ module Saboteur
     #   arid         - every line an edit touches matches an arid pattern
     #     (logging and friends, #111/#187). The builtin hint list decides;
     #     a configured arid policy does not change the label.
-    #   missing_test - a test covered the line and passed, which MAY mean
-    #     the suite reaches the code without pinning this behaviour. The
-    #     covering list is only the PLANNED coverage: whole-body (coarse)
-    #     mutants carry method-level guesses, so they never get this
-    #     label, and neither does anything without real coverage.
+    #   A gap kind (boundary, branch, effect, number, error path, or the
+    #     result unchecked fallback) - a test covered the line and passed,
+    #     which MAY mean the suite reaches the code without pinning this
+    #     behaviour; the kind names WHAT sort of check is missing, from the
+    #     operator and the edit shape only. The covering list is only the
+    #     PLANNED coverage: whole-body (coarse) mutants carry method-level
+    #     guesses, so they never get a gap kind, and neither does anything
+    #     without real coverage.
     #   tool_limit   - survivors saboteur could not observe faithfully: an
     #     external-runner run records only the pseudo-test id, never real
     #     coverage (#1071). A re-eval refusal records no signal on the
@@ -33,7 +37,7 @@ module Saboteur
     #
     # A survivor with no matching signal stays unlabeled.
     module SurvivorClassification
-      LABELS = %w[likely_equivalent arid missing_test tool_limit].freeze
+      LABELS = %w[likely_equivalent arid tool_limit].concat(GapKinds::KINDS).freeze
 
       class << self
         def label(result, arid: MutationSource::Builtin::DEFAULT_ARID)
@@ -41,7 +45,7 @@ module Saboteur
           return "likely_equivalent" if equivalent?(result)
           return "arid" if arid?(result, arid)
           return "tool_limit" if tool_limited?(result)
-          return "missing_test" if possible_test_gap?(result)
+          return gap_kind(result) if possible_test_gap?(result)
 
           nil
         end
@@ -66,11 +70,25 @@ module Saboteur
 
         # An external runner reports one pseudo id for every mutant and no
         # coverage map, so a survivor there was never observed against real
-        # tests. Pseudo id next to a real id keeps missing_test (#305).
+        # tests. Pseudo id next to a real id keeps the gap kind (#305).
         def tool_limited?(result)
           result.covered_by.any? && result.covered_by.all? { |id| id == Execution::ExternalRunner::PSEUDO_TEST }
         end
 
+        # The gap kind says which sort of check the survivor suggests:
+        # the operator decides for almost everything; operand_replacement
+        # looks at the replaced expression (comparison -> boundary).
+        def gap_kind(result)
+          GapKinds.kind(result.mutation.operator, comparison_edit: comparison_edit?(result))
+        end
+
+        def comparison_edit?(result)
+          result.mutation.edits.any? do |edit|
+            result.subject.file_source.byteslice(edit.start_byte...edit.end_byte)
+                  &.match?(/<=>|<=|>=|==|!=|===|<|>/)
+          end
+        end
+
         # covered_by is a PLANNED covering list, not a verdict about what
         # the suite asserts: coarse (whole-body) mutants carry method-level
         # guesses, and a --test-command run records only the pseudo-test id

data/lib/saboteur/reporter/survivor_hints.rb

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "gap_kinds"
+
 module Saboteur
   module Reporter
     # Suggests a check that might kill a surviving mutant, by operator. It does
@@ -94,9 +96,8 @@ module Saboteur
       LABEL_REASONS = {
         "likely_equivalent" => "compiles to the same instructions as the original",
         "arid" => "every edited line matches an arid pattern",
-        "missing_test" => "the covering specs pass without pinning this change",
         "tool_limit" => "the tool could not observe this mutant faithfully"
-      }.freeze
+      }.merge(GapKinds::REASONS).freeze
 
       module_function