saboteur 0.12.2 → 0.12.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce718289117e022594f50dfb13bfaf3feacf03f99dc1a5b73c7c2463581d24f2
-  data.tar.gz: f99866dbeacb50607ac66ee9f15582b49b1596b318cba1598afdb7bac89a9133
+  metadata.gz: 19bac537a82f6aa32ade9a7a1955cd793793d5a95b026dc56274c7c97560cfa6
+  data.tar.gz: 40086d139cbb82e418c9b7de5aa31b2aedd19eeb61ae238ba01f80c0e3f0d5b4
 SHA512:
-  metadata.gz: 2ef5f5dc4d8d441d35558569bd5649bc4d7bbece07bde9172bd6d660a8d54e0274cc02b36f2968f4e129080cc3ccc3c5bdb3a091c0fbe55341a67d53bf967540
-  data.tar.gz: 9f6d1c79c63abc5d314f79f699bb9ccfa9de5bdb2a8c7d4240d311854774c4eb4c3c40950234f206bb62872008b5525181bd20b13325b080f680ebc4227ad6e5
+  metadata.gz: 1dda55357cc1866e39f052b3b69424e6dde81ec551b695822e35e58a5ec65fe00b0e795b650338c12e2a2869e4a046f3a6e0839742e86bb3bd7ae52db809e124
+  data.tar.gz: f094725207c45c6b5c73d848790f2a6d8a91e849dcd281eabf616c6de414fbf6f9f9f589c7a15c0d6e15c72d1e21971be4a2edc19802691bc2c508b965fe99e9

data/CHANGELOG.md

@@ -6,6 +6,23 @@ All notable changes are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.12.3] - 2026-10-22
+
+### Added
+
+- Survivors are labeled `input_gap` or `assertion_gap` from the value the
+  mutated expression actually produced (side-effect-free sites only).
+  `input_gap` means the tests never gave the expression an input where its
+  value differs, or no test reached it. `assertion_gap` means the value
+  changed and the tests still passed. The JSON report gains `valueDiffed`
+  and `gapKind` fields (#1290, #1305, #1306, #1307).
+
+### Changed
+
+- The cache stores the observed value with each verdict (cache format 2),
+  so cached results from before this release are rebuilt once on the next
+  run (#1290, #1307).
+
 ## [0.12.2] - 2026-10-22
 
 ### Added

data/README.md

@@ -80,8 +80,10 @@ tree refuses with exit 2 and points at the generator. Engine gem with
   assertion, 1 by a crash`), and an error-dominated run prints
   `Score: n/a` instead of a number you would misread.
 - 🔍 **Survivors you can act on.** Survivors group per statement with a
-  triage label (`likely_equivalent`, `arid`, `tool_limit`, `input_gap` when no test
-  ran the mutant, or a gap kind) and their
+  triage label (`likely_equivalent`, `arid`, `tool_limit`, `input_gap` (the tests
+  never gave the mutated expression an input where its value differs, or no
+  test reached it), `assertion_gap` (the value changed and the tests still
+  passed), or a gap kind) and their
   covering tests - split into the tests that ran against the mutant and
   the ones that never did. `saboteur survivors` browses them read-only:
   one digest shows the full diff and the exact replay command.

data/lib/saboteur/cli/survivors_command.rb

@@ -138,7 +138,7 @@ module Saboteur
       def detail_lines(survivor, finding)
         [
           "#{survivor[:path]}:#{survivor[:line]}  #{survivor[:operator]}  #{survivor[:digest]}",
-          *classification_line(survivor[:classification]),
+          *classification_line(survivor[:classification], survivor[:gap_kind]),
           "",
           "- #{finding['original'] || original_line(survivor)}",
           "+ #{finding['replacement'] || survivor[:replacement]}",
@@ -149,10 +149,10 @@ module Saboteur
       end
 
       # The same wording the terminal survivor block uses (#1183).
-      def classification_line(label)
+      def classification_line(label, kind = nil)
         return [] unless label
 
-        reason = Reporter::SurvivorHints.label_reason(label)
+        reason = Reporter::SurvivorHints.label_reason(label, kind: kind)
         ["classification: #{label}#{" - #{reason}" if reason}"]
       end
 
@@ -241,7 +241,8 @@ module Saboteur
             entry.fetch("mutants", []).select { |m| m["status"] == "Survived" }.map do |m|
               { path: path, line: m.dig("location", "start", "line").to_i, operator: m["mutatorName"],
                 digest: m["id"], replacement: m["replacement"], classification: m["classification"],
-                subject: m["subject"], covered: m["coveredBy"] || [], source: entry["source"] }
+                gap_kind: m["gapKind"], subject: m["subject"], covered: m["coveredBy"] || [],
+                source: entry["source"] }
             end
           end
           survivors

data/lib/saboteur/engine/result_cache.rb

@@ -26,7 +26,9 @@ module Saboteur
     # every source file is watched instead: reuse turns conservative, never
     # stale.
     class ResultCache
-      FORMAT = 1
+      # 2: entries carry value_differed (#1290); a version 1 file is dropped so
+      # no cached survivor reads as "never differed" without having been observed.
+      FORMAT = 2
       MAX_BYTES = 64 * 1024 * 1024
       STORED = %i[killed survived timeout].freeze
       LOCKFILES = %w[Gemfile.lock gems.locked].freeze
@@ -62,13 +64,13 @@ module Saboteur
       end
 
       # The stored verdict as a hash (status, reason, killed_by, kill_cause,
-      # runtime), or nil when it may no longer hold.
+      # runtime, value_differed), or nil when it may no longer hold.
       def lookup(subject, mutation, tests)
         entry = @entries[key(subject, mutation)]
         return nil unless entry && entry["fingerprint"] == fingerprint(subject, tests)
 
         { status: entry["status"].to_sym, reason: entry["reason"], killed_by: entry["killed_by"],
-          kill_cause: entry["kill_cause"], runtime: entry["runtime"] }
+          kill_cause: entry["kill_cause"], runtime: entry["runtime"], value_differed: entry["value_differed"] }
       end
 
       def record(result)
@@ -77,7 +79,7 @@ module Saboteur
         @entries[key(result.subject, result.mutation)] = {
           "fingerprint" => fingerprint(result.subject, result.covered_by), "status" => result.status.to_s,
           "reason" => result.reason, "killed_by" => result.killed_by, "kill_cause" => result.kill_cause,
-          "runtime" => result.runtime
+          "runtime" => result.runtime, "value_differed" => result.value_differed
         }
         checkpoint if @clock.call - @last_saved >= @save_interval
       end
@@ -154,7 +156,8 @@ module Saboteur
       def typed?(entry)
         STORED.map(&:to_s).include?(entry["status"]) && (entry["runtime"].nil? || entry["runtime"].is_a?(Numeric)) &&
           %w[reason kill_cause].all? { |key| entry[key].nil? || entry[key].is_a?(String) } &&
-          entry["killed_by"].is_a?(Array) && entry["killed_by"].all?(String)
+          entry["killed_by"].is_a?(Array) && entry["killed_by"].all?(String) &&
+          [nil, true, false].include?(entry["value_differed"])
       end
 
       def key(subject, mutation)

data/lib/saboteur/engine/scheduler.rb

@@ -235,7 +235,8 @@ module Saboteur
 
         MutantResult.new(subject: plan.subject, mutation: mutation, status: hit[:status], mutated_source: text,
                          reason: hit[:reason], runtime: hit[:runtime], killed_by: hit[:killed_by],
-                         covered_by: tests, kill_cause: hit[:kill_cause], reused: true)
+                         covered_by: tests, kill_cause: hit[:kill_cause], reused: true,
+                         value_differed: hit[:value_differed])
       end
 
       def execute(plan, mutation, text)
@@ -247,7 +248,7 @@ module Saboteur
         result = MutantResult.new(subject: plan.subject, mutation: mutation, status: outcome.status,
                                   mutated_source: text, reason: outcome.message, runtime: outcome.runtime,
                                   killed_by: outcome.failed_ids, covered_by: tests, kill_cause: outcome.kill_cause,
-                                  executed: outcome.executed_ids)
+                                  executed: outcome.executed_ids, value_differed: outcome.value_differed)
         outcome.failed_ids.each { |id| plan.killers[id] += 1 }
         note_leftovers(plan.subject, "#{mutation.operator} #{result.digest}", outcome)
         @diagnostics.progress(result)

data/lib/saboteur/execution/runner.rb

@@ -18,10 +18,13 @@ module Saboteur
       # else the class of the error it died with (a crash, not a check).
       # executed_ids: the tests the child reports it ran; empty when it could
       # not say (a test called exit).
+      # value_differed: whether the mutated expression ever produced a value
+      # different from the original (SiteProbe); nil when the site is not
+      # probeable, never ran, or the run did not survive (#1290).
       Outcome = Data.define(:status, :runtime, :failed_ids, :message, :leftover_pids, :kill_cause,
-                            :executed_ids) do
+                            :executed_ids, :value_differed) do
         def initialize(status:, runtime:, failed_ids: [], message: nil, leftover_pids: [], kill_cause: nil,
-                       executed_ids: [])
+                       executed_ids: [], value_differed: nil)
           super
         end
       end
@@ -98,6 +101,7 @@ module Saboteur
       def run(subject:, text:, test_ids:, timeout:, mutation: nil, eval_prefix: nil)
         @hooks.run(:before_fork, mutation)
         @sequence = @sequence.to_i + 1
+        text = SiteProbe.text(subject, mutation, text) || text if mutation
         job = Job.new(subject:, text:, test_ids:, timeout:, mutation:, eval_prefix:,
                       log_path: File.join(@log_dir, "child-#{Process.pid}-#{@sequence}.log"))
         log_file = open_log(job)
@@ -132,6 +136,7 @@ module Saboteur
         # Before the evaluation: a whole-file subject runs the file's own
         # top-level code there, and it must see the run's random numbers.
         Kernel.srand(@seed)
+        SiteProbe.reset
         evaluate_mutant(writer, job)
         stale = stale_captures(job)
         Protocol.emit(writer, "captures", site: stale.first, stale: stale.size) if stale.any?
@@ -170,7 +175,8 @@ module Saboteur
           Protocol.emit(writer, "error", message: "around_mutant hook did not run the tests")
         else
           called = flags[:replacement_called]
-          Protocol.emit(writer, "result", **with_crash_detail(result, started_at), replacement_called: called)
+          Protocol.emit(writer, "result", **with_crash_detail(result, started_at), replacement_called: called,
+                                                                                   value_differed: SiteProbe.differed)
           # A reload after the mutant already ran (an after-hook restore)
           # is no reason to doubt the verdict; only a never-invoked mutant
           # can have been hidden by the overwrite.
@@ -394,7 +400,8 @@ module Saboteur
           return mismatch(runtime, "executed #{executed.size} of #{test_ids.size} requested tests")
         end
 
-        Outcome.new(status: :survived, runtime: runtime, executed_ids: executed)
+        Outcome.new(status: :survived, runtime: runtime, executed_ids: executed,
+                    value_differed: result["value_differed"])
       end
 
       def killed_outcome(result, runtime, failed, executed, verbose_failure)

data/lib/saboteur/execution/site_probe.rb

@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+
+module Saboteur
+  module Execution
+    # Records, in the mutant's child, whether the mutated expression produced
+    # a different value from the original one (#1290). The mutated site is
+    # wrapped as (observe((mutated), [operands]) { original }). The mutated
+    # expression runs exactly once and first, as it does unwrapped, so the
+    # suite sees the same calls and the same verdict. The original runs
+    # only when every operand is a core immutable (Integer, Float, Rational,
+    # Symbol, nil, true, false, a frozen String), so only built-in operators
+    # execute; with any other operand the site is not probed and reports
+    # nil. Only side-effect-free site shapes are wrapped at all (literals,
+    # local and instance variable reads, arithmetic and comparison on
+    # those).
+    module SiteProbe
+      OPERATORS = %i[+ - * / % ** < <= > >= == != <=> & | ^ ! -@ +@ ~].freeze
+      LEAVES = [Prism::IntegerNode, Prism::FloatNode, Prism::RationalNode, Prism::SymbolNode, Prism::NilNode,
+                Prism::TrueNode, Prism::FalseNode, Prism::LocalVariableReadNode,
+                Prism::InstanceVariableReadNode].freeze
+
+      @hits = 0
+      @differed = false
+      @comparable = true
+
+      class << self
+        # The def text with the mutated site wrapped, or nil when the site
+        # cannot be probed safely. mutated_text is what the run would
+        # evaluate unwrapped; the wrap is only offered when it is exactly
+        # the source with the mutation's edits applied.
+        def text(subject, mutation, mutated_text)
+          return nil unless subject.respond_to?(:whole_file_only?) && mutation.respond_to?(:edits)
+          return nil if subject.whole_file_only? || mutation.edits.size != 1
+
+          source = subject.source
+          return nil unless subject.apply(mutation.edits) == mutated_text
+
+          edit = mutation.edits.first
+          range = (edit.start_byte - subject.start_byte)...(edit.end_byte - subject.start_byte)
+          wrap(source.b, range, edit.replacement.b)&.force_encoding(Encoding::UTF_8)
+        rescue StandardError
+          nil # a probe must never turn a mutant run into an error
+        end
+
+        def reset
+          @hits = 0
+          @differed = false
+          @comparable = true
+        end
+
+        # nil: the site never ran, or its values could not be compared.
+        def differed
+          return nil if @hits.zero? || !@comparable
+
+          @differed
+        end
+
+        def observe(mutated, operands, &)
+          compare(mutated, &) if operands.all? { |operand| immutable?(operand) }
+          mutated
+        end
+
+        private
+
+        def immutable?(value)
+          case value
+          when Integer, Float, Rational, Symbol, nil, true, false then true
+          when String then value.frozen?
+          else false
+          end
+        end
+
+        def compare(mutated)
+          original = yield
+          @hits += 1
+          @differed ||= original != mutated
+        rescue StandardError
+          @comparable = false
+        end
+
+        def wrap(source, range, replacement)
+          top = site(Prism.parse(source).value, range)
+          # A bare edited literal differs from itself by construction: no signal.
+          return nil if top.nil? || LEAVES.any? { |leaf| top.is_a?(leaf) }
+
+          from = top.location.start_offset
+          to = top.location.end_offset
+          original = source.byteslice(from...to)
+          mutated = original.byteslice(0, range.begin - from) + replacement + original.byteslice((range.end - from)..)
+          return nil if (original + mutated).include?("\n")
+
+          source.byteslice(0, from) + probe(top, original, mutated) + source.byteslice(to..)
+        end
+
+        def probe(top, original, mutated)
+          reads = []
+          collect_reads(top, reads)
+          operands = reads.uniq.join(", ")
+          "(::Saboteur::Execution::SiteProbe.observe((#{mutated}), [#{operands}]) { #{original} })".b
+        end
+
+        def collect_reads(node, reads)
+          reads << node.slice if node.is_a?(Prism::LocalVariableReadNode) || node.is_a?(Prism::InstanceVariableReadNode)
+          node.compact_child_nodes.each { |child| collect_reads(child, reads) }
+        end
+
+        # The outermost pure expression around the edit, climbing while the
+        # parent is pure too.
+        def site(root, range)
+          path = path_to(root, range).grep_v(Prism::ArgumentsNode)
+          index = path.rindex { |node| pure?(node) }
+          return nil unless index
+
+          index -= 1 while index.positive? && climbable?(path[index - 1])
+          path[index]
+        end
+
+        def climbable?(node)
+          (node.is_a?(Prism::CallNode) || node.is_a?(Prism::ParenthesesNode)) && pure?(node)
+        end
+
+        def path_to(node, range)
+          path = [node]
+          loop do
+            child = node.compact_child_nodes.find do |c|
+              c.location.start_offset <= range.begin && range.end <= c.location.end_offset
+            end
+            return path unless child
+
+            path << child
+            node = child
+          end
+        end
+
+        def pure?(node)
+          case node
+          when *LEAVES then true
+          when Prism::ParenthesesNode then pure_parentheses?(node)
+          when Prism::CallNode then pure_call?(node)
+          else false
+          end
+        end
+
+        def pure_parentheses?(node)
+          body = node.body
+          body.is_a?(Prism::StatementsNode) && body.body.size == 1 && pure?(body.body.first)
+        end
+
+        def pure_call?(node)
+          return false unless OPERATORS.include?(node.name) && node.block.nil? && node.receiver
+
+          pure?(node.receiver) && Array(node.arguments&.arguments).size <= 1 &&
+            Array(node.arguments&.arguments).all? { |arg| pure?(arg) }
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/findings.rb

@@ -71,7 +71,8 @@ module Saboteur
             edits: entries,
             coarse: result.mutation.coarse,
             # Why the survivor is worth a look, as a label only (#192).
-            classification: SurvivorClassification.label(result)
+            classification: SurvivorClassification.label(result),
+            gapKind: SurvivorClassification.kind(result)
           }.compact
           entry = with_changed_lines(report, result, entry)
           result.ignored ? entry.merge(reason: result.ignored) : entry

data/lib/saboteur/reporter/gap_kinds.rb

@@ -74,6 +74,18 @@ module Saboteur
         "result unchecked" => "the covering specs pass without pinning this result"
       }.freeze
 
+      # What an observed label (input_gap/assertion_gap, #1290) replaces
+      # the kind with, and the advice the kind gave: kept in the reason.
+      OBSERVED = %w[input_gap assertion_gap].freeze
+      ADVICE = {
+        "boundary" => "exercise both sides of this boundary",
+        "branch" => "exercise both branches",
+        "effect" => "assert the effect of this statement",
+        "number" => "no test depends on this exact number",
+        "error path" => "exercise the error path",
+        "result unchecked" => "assert this result"
+      }.freeze
+
       module_function
 
       def kind(operator, comparison_edit: false)

data/lib/saboteur/reporter/review_comments.rb

@@ -32,7 +32,10 @@ module Saboteur
       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,
-                                    "input_gap" => "No test reaches this line. Exercise it with a varied input.").freeze
+                                    "input_gap" => "No test input makes this change differ. " \
+                                                   "Exercise it with a varied input.",
+                                    "assertion_gap" => "A test reaches this line, the value changes, and it still " \
+                                                       "passes. Add an assertion that pins this behaviour.").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/stryker.rb

@@ -139,9 +139,14 @@ module Saboteur
           # Why the survivor is worth a look, as a label only: scores and
           # the exit code never change (#192).
           classification: SurvivorClassification.label(result),
+          # Additive (#1290): the gap kind an observed label replaced.
+          gapKind: SurvivorClassification.kind(result),
           # Additive (#1286): confirmed, killed_by_confirmation or unconfirmed.
           # An unconfirmed survivor reports Ignored: outside the score.
           confirmation: result.confirmation_state,
+          # Additive (#1290): whether the mutated expression ever produced a
+          # different value from the original; absent when not probed.
+          valueDiffered: result.value_differed,
           creditedTest: result.credited_test&.then { |name| test_ids.fetch(name) },
           killedBy: result.killed_by.map { |name| test_ids.fetch(name) }.then { |ids| ids.empty? ? nil : ids },
           coveredBy: result.covered_by.map { |name| test_ids.fetch(name) }.then { |ids| ids.empty? ? nil : ids },

data/lib/saboteur/reporter/survivor_classification.rb

@@ -29,11 +29,14 @@ module Saboteur
     #     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.
-    #   input_gap    - no real test covered the mutant at all, so the input
-    #     never varied (D6). Coarse mutants stay unlabeled: their planned
-    #     coverage is a method-level guess, not an observation. The
-    #     deterministic version (the runner records the mutated value
-    #     actually differing) is #1064 follow-up.
+    #   input_gap    - the tests never gave the mutated expression an input
+    #     where its value differs (the runner recorded it, #1290), or no
+    #     real test covered the mutant at all (D6). Coarse mutants stay
+    #     unlabeled: their planned coverage is a method-level guess.
+    #   assertion_gap - the mutated expression produced a different value
+    #     while the covering tests ran, and they still passed: a test
+    #     reaches the code and no assertion pins it (#1290). Only side-effect
+    #     free sites are observed; an unprobed site keeps its gap kind.
     #   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
@@ -41,7 +44,10 @@ module Saboteur
     #
     # A survivor with no matching signal stays unlabeled.
     module SurvivorClassification
-      LABELS = %w[likely_equivalent arid tool_limit input_gap].concat(GapKinds::KINDS).freeze
+      LABELS = %w[likely_equivalent arid tool_limit input_gap assertion_gap].concat(GapKinds::KINDS).freeze
+      # assertion_gap decides a statement's label ahead of every gap kind: the
+      # value changed and the tests passed.
+      GROUP_ORDER = (["assertion_gap"] + GapKinds::PRECEDENCE).freeze
 
       class << self
         def label(result, arid: MutationSource::Builtin::DEFAULT_ARID)
@@ -49,6 +55,9 @@ module Saboteur
           return "likely_equivalent" if equivalent?(result)
           return "arid" if arid?(result, arid)
           return "tool_limit" if tool_limited?(result)
+
+          observed = observed_gap(result)
+          return observed if observed
           return gap_kind(result) if possible_test_gap?(result)
           return "input_gap" unless result.mutation.coarse
 
@@ -67,7 +76,21 @@ module Saboteur
         # subsumes a missing branch, boundary or effect check on it.
         def group_label(results)
           labels = results.map { |result| label(result) }.compact
-          GapKinds::PRECEDENCE.find { |kind| labels.include?(kind) } || labels.first
+          GROUP_ORDER.find { |kind| labels.include?(kind) } || labels.first
+        end
+
+        # The gap kind an observed label (input_gap/assertion_gap) replaced:
+        # what the edit shape says is unchecked. nil unless the observation
+        # decided the label, so a plain kind label stays its own kind.
+        def kind(result)
+          return nil unless GapKinds::OBSERVED.include?(observed_gap(result)) && possible_test_gap?(result)
+
+          gap_kind(result)
+        end
+
+        def group_kind(results)
+          kinds = results.map { |result| kind(result) }.compact
+          GapKinds::PRECEDENCE.find { |kind| kinds.include?(kind) }
         end
 
         private
@@ -91,6 +114,15 @@ 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 the gap kind (#305).
+        # The runner's observation (#1290): the mutated expression never gave
+        # a different value (input_gap), or gave one and the tests passed
+        # (assertion_gap). nil when the site was not probed.
+        def observed_gap(result)
+          return nil if result.mutation.coarse || result.value_differed.nil?
+
+          result.value_differed ? "assertion_gap" : "input_gap"
+        end
+
         def tool_limited?(result)
           result.covered_by.any? && result.covered_by.all? { |id| id == Execution::ExternalRunner::PSEUDO_TEST }
         end

data/lib/saboteur/reporter/survivor_hints.rb

@@ -48,9 +48,8 @@ module Saboteur
       UNEQUAL_CASE = [%w[< >], %w[<= >=]].map(&:to_set).freeze
 
       # Labels that never get a hint: a generated assertion on an equivalent
-      # mutant is the worst kind of hint noise. The assertion_gap/input_gap
-      # split (#1064) narrows this further; until it lands, every other
-      # label keeps the operator hint unchanged.
+      # mutant is the worst kind of hint noise. Every other label, including
+      # input_gap and assertion_gap, keeps the operator hint.
       NO_HINT_LABELS = %w[likely_equivalent].freeze
 
       # One deterministic template sentence per operator: what the change
@@ -91,13 +90,14 @@ module Saboteur
 
       # The deterministic per-label reason printed next to a survivor's rank.
       # Labels come from SurvivorClassification; they are heuristics, not
-      # diagnoses. #1064 lands the assertion_gap label: add its reason here
-      # and its gate in NO_HINT_LABELS when it does.
+      # diagnoses. input_gap and assertion_gap keep the operator hint: it is
+      # the right place to look in both cases (#1290).
       LABEL_REASONS = {
         "likely_equivalent" => "compiles to the same instructions as the original",
         "arid" => "every edited line matches an arid pattern",
         "tool_limit" => "the tool could not observe this mutant faithfully",
-        "input_gap" => "no test reached this mutant, so its input never varied"
+        "input_gap" => "no test input made this mutation change the value, so its input never varied",
+        "assertion_gap" => "a test ran this mutant, the value changed, and no assertion noticed"
       }.merge(GapKinds::REASONS).freeze
 
       module_function
@@ -114,9 +114,13 @@ module Saboteur
         WHY_IT_MATTERS.fetch(operator, WHY_FALLBACK)
       end
 
-      # The per-label reason sentence; nil when the label has none.
-      def label_reason(label)
-        LABEL_REASONS[label]
+      # The per-label reason sentence; nil when the label has none. An
+      # observed label (input_gap/assertion_gap) keeps the advice of the gap
+      # kind it replaced, so the kind is not lost behind the observation.
+      def label_reason(label, kind: nil)
+        reason = LABEL_REASONS[label]
+        advice = GapKinds::ADVICE[kind]
+        advice && GapKinds::OBSERVED.include?(label) ? "#{reason}; #{advice}" : reason
       end
 
       def for(operator, coarse: false)

data/lib/saboteur/reporter/survivor_list.rb

@@ -78,7 +78,7 @@ module Saboteur
         path = relative(first.subject.file, report.root)
         @out.puts "\n#{@palette.paint(:head, "#{rank}. #{path}:#{line}")} #{first.subject.id} " \
                   "#{@palette.paint(:dim, label_suffix(group, rank, total))}".rstrip
-        reason = SurvivorHints.label_reason(@classifier.group_label(group))
+        reason = SurvivorHints.label_reason(@classifier.group_label(group), kind: @classifier.group_kind(group))
         @out.puts "  #{@palette.paint(:dim, reason)}" if reason
         fence(first, line)
         @out.puts "  #{@palette.paint(:dim, "why it matters: #{why(first.mutation.operator)}")}"

data/lib/saboteur/result.rb

@@ -35,9 +35,13 @@ module Saboteur
     # status keeps its meaning either way.
     attr_reader :confirmation
 
+    # Whether the mutated expression ever produced a value different from the
+    # original one while the covering tests ran; nil when not probed (#1290).
+    attr_reader :value_differed
+
     def initialize(subject:, mutation:, status:, mutated_source:, reason: nil, runtime: nil, killed_by: [],
                    covered_by: [], kill_cause: nil, reused: false, rejected_kill: false, executed: nil,
-                   confirmation: nil)
+                   confirmation: nil, value_differed: nil)
       raise ArgumentError, "unknown status #{status.inspect}" unless STATUSES.include?(status)
 
       @subject = subject
@@ -53,6 +57,7 @@ module Saboteur
       @rejected_kill = rejected_kill
       @reused = reused
       @confirmation = confirmation
+      @value_differed = value_differed
       @ignored = nil
       # triage_state/triage_reason stay unset until the ignore list writes
       # them: the accessors read as nil before that, and there is no
@@ -69,7 +74,7 @@ module Saboteur
       MutantResult.new(subject: subject, mutation: mutation, status: status, mutated_source: mutated_source,
                        reason: reason, runtime: runtime, killed_by: killed_by, covered_by: covered_by,
                        kill_cause: kill_cause, reused: reused?, rejected_kill: rejected_kill?,
-                       executed: executed, confirmation: confirmation)
+                       executed: executed, confirmation: confirmation, value_differed: value_differed)
     end
 
     # The reason a --flaky-check disagreement starts with: unverified, but

data/lib/saboteur/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Saboteur
-  VERSION = "0.12.2"
+  VERSION = "0.12.3"
 end

data/lib/saboteur.rb

@@ -70,6 +70,7 @@ require_relative "saboteur/execution/marker_sweep"
 require_relative "saboteur/execution/supervisor"
 require_relative "saboteur/execution/reevaluator"
 require_relative "saboteur/execution/wrapper"
+require_relative "saboteur/execution/site_probe"
 require_relative "saboteur/execution/runner"
 require_relative "saboteur/execution/bundle_gemfile_pin"
 require_relative "saboteur/execution/gemfile_path_sources"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: saboteur
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.12.3
 platform: ruby
 authors:
 - Vamsi Pavan Mahesh Gunturu
@@ -164,6 +164,7 @@ files:
 - lib/saboteur/execution/runner.rb
 - lib/saboteur/execution/sandbox.rb
 - lib/saboteur/execution/seatbelt.rb
+- lib/saboteur/execution/site_probe.rb
 - lib/saboteur/execution/stale_captures.rb
 - lib/saboteur/execution/supervisor.rb
 - lib/saboteur/execution/supervisor_batch.rb