saboteur 0.11.1 → 0.11.2

data/lib/saboteur/reporter/survivor_list.rb

@@ -19,6 +19,11 @@ module Saboteur
     # --all-mutants gives every survivor its own block. Accepted
     # (ignored) survivors get one quoted dim line each, never a block.
     class SurvivorList
+      # Default when a caller never wires the whole-suite lookup (unit pins,
+      # other renderers): keep the historical bare covered-by line. Terminal
+      # always passes the kwarg - nil there means the lookup ran and found
+      # no cached whole-suite map (review C1).
+      NO_WHOLE_SUITE_LOOKUP = Object.new
       # Rendered rows in the method fence, elision markers included.
       FENCE_CAP = 10
 
@@ -28,11 +33,14 @@ module Saboteur
       # Sibling digests named on the collapse line; the rest are a count.
       SIBLING_DIGEST_CAP = 3
 
-      def initialize(out, palette, all_mutants: false, classifier: SurvivorClassification)
+      def initialize(out, palette, all_mutants: false, classifier: SurvivorClassification,
+                     whole_suite_map: NO_WHOLE_SUITE_LOOKUP, run_map: nil)
         @out = out
         @palette = palette
         @all_mutants = all_mutants
         @classifier = classifier
+        @whole_suite_map = whole_suite_map
+        @run_map = run_map
       end
 
       # Survivors in report (ranked) order; accepted ones trail as dim lines.
@@ -41,7 +49,8 @@ module Saboteur
 
         live, accepted = survivors.partition(&:unignored_survivor?)
         @out.puts @palette.paint(:head, "Survivors (#{live.size}) - changes your tests did not catch")
-        groups(live).each_with_index { |group, index| block(report, group, index + 1, live.size) }
+        block_list = groups(live)
+        block_list.each_with_index { |group, index| block(report, group, index + 1, block_list.size) }
         accepted_section(report, accepted)
         hinted = live.select { |result| hint_for(result) }
         @out.puts "\n#{@palette.paint(:dim, SurvivorHints::CAVEAT)}" if hinted.any?
@@ -72,9 +81,12 @@ module Saboteur
         siblings(report, group)
       end
 
+      # The count names blocks, the unit the leading ordinal uses: grouped
+      # siblings read "#3 of 14 blocks", never blocks against mutants (#1147).
       def label_suffix(result, rank, total)
         label = @classifier.label(result)
-        parts = [("coarse" if result.mutation.coarse), label, "##{rank} of #{total}"].compact
+        unit = total == 1 ? "block" : "blocks"
+        parts = [("coarse" if result.mutation.coarse), label, "##{rank} of #{total} #{unit}"].compact
         reason = SurvivorHints.label_reason(label)
         "[#{parts.join(" \u00B7 ")}#{": #{reason}" if reason}]"
       end
@@ -178,8 +190,38 @@ module Saboteur
 
       # The covering tests are a group union (#502): the first names where an
       # assertion would pin the change, the count says the rest also passed.
+      #
+      # The list comes from the run's own map, which a scoped run narrows to
+      # the specs it loaded. The cached whole-suite map (when one exists)
+      # tells the rest of the story (review C1): a covering spec the run never
+      # loaded is named as not run here, and a spec pinning the mutant's exact
+      # line marks the block as likely covered elsewhere, instead of reading
+      # as a bare finding. With no whole-suite map, say so rather than
+      # implying the list is complete. A whole-project run's own map IS the
+      # whole-suite map, so its line is unchanged.
       def covered(group)
         tests = group.flat_map(&:covered_by).uniq
+        return legacy_covered(group, tests) if @whole_suite_map.equal?(NO_WHOLE_SUITE_LOOKUP)
+
+        whole = @whole_suite_map&.tests_for(group.first.subject)
+        if whole.nil?
+          @out.puts @palette.paint(:dim, "  covering tests unknown - run a full coverage build")
+          return
+        end
+
+        run_known = @run_map ? @run_map.tests_for(group.first.subject) : tests
+        not_run = whole - run_known
+        return legacy_covered(group, tests) if not_run.empty?
+
+        @out.puts "  covered by #{whole.size} #{whole.one? ? 'spec' : 'specs'}, " \
+                  "incl. #{not_run.first} (not run here)"
+        exact = exact_line_tests(group.first) - run_known
+        return if exact.empty?
+
+        @out.puts @palette.paint(:dim, "  likely covered elsewhere: #{exact.first} pins this line (not run here)")
+      end
+
+      def legacy_covered(group, tests)
         return if tests.empty?
 
         first = group.find { |result| result.covered_by.include?(tests.first) }
@@ -188,6 +230,14 @@ module Saboteur
         @out.puts @palette.paint(:dim, "  #{line}") if line
       end
 
+      # Tests pinning the mutant's exact edit lines in the whole-suite map,
+      # on the same line basis the scheduler used to select the run's tests:
+      # the strongest "already pinned elsewhere" evidence a map can give.
+      def exact_line_tests(result)
+        lines = result.mutation.edits.flat_map { |edit| result.subject.coverage_lines_for(edit) }.uniq
+        @whole_suite_map.tests_for_edit(result.subject, lines)
+      end
+
       # The verdict names what this run did: executed is nil when the run
       # did not record which tests ran, so only the bare verdict is safe.
       def more_covered_line(group, tests)

data/lib/saboteur/reporter/terminal.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require_relative "safe_out"
+require_relative "wording"
 require_relative "baseline_tail"
 require_relative "next_steps"
 require_relative "kill_causes"
@@ -27,17 +28,19 @@ module Saboteur
       def initialize(out, verbose: false, quiet: false, color: :auto, overrides: nil,
                      replay_command: nil, all_mutants: false, exit_code: nil,
                      threshold: nil, previous_score: nil, baseline_gate: nil,
-                     scope: "whole project", html_report: nil, baseline: nil, coverage: nil, mutant_phase: nil)
+                     scope: "whole project", baseline: nil, coverage: nil, mutant_phase: nil,
+                     whole_suite_map: SurvivorList::NO_WHOLE_SUITE_LOOKUP, run_map: nil)
         @out = SafeOut.new(out)
         @all_mutants = all_mutants
         @verbose = verbose
         @quiet = quiet
-        # Clean-screen context: scope and report path from the CLI; PR4a plumbs the phase stats.
+        # Clean-screen context: scope from the CLI; PR4a plumbs the phase stats.
         @scope = scope
-        @html_report = html_report
         @baseline = baseline
         @coverage = coverage
         @mutant_phase = mutant_phase
+        @whole_suite_map = whole_suite_map
+        @run_map = run_map
         @palette = Palette.for(out, mode: color, overrides: overrides)
         @score_table = ScoreTable.new(@out, @palette)
         @next_steps = NextSteps.new(@out, @palette, replay_command: replay_command)
@@ -143,9 +146,9 @@ module Saboteur
       # numbers so "4 mutants" is not read as the whole plan (#582).
       def mutant_counts(report)
         planned = report.early_stop&.planned_mutants
-        return "#{report.results.size} mutants" unless planned && planned > report.results.size
+        return Text.counted(report.results.size, "mutant") unless planned && planned > report.results.size
 
-        "#{planned} mutants selected, #{report.results.size} attempted"
+        "#{Text.counted(planned, 'mutant')} selected, #{report.results.size} attempted"
       end
 
       def summary(report)
@@ -153,7 +156,7 @@ module Saboteur
         return clean_screen(report) if !@baseline_gate && clean_run?(report)
 
         seed = report.seed && ", seed #{report.seed} (repeat with --seed #{report.seed})"
-        tally = "saboteur #{VERSION}: #{report.subjects.size} subjects, #{mutant_counts(report)}, " \
+        tally = "saboteur #{VERSION}: #{Text.counted(report.subjects.size, 'subject')}, #{mutant_counts(report)}, " \
                 "wall #{format('%.2f', report.wall_time)} s#{seed}"
         @out.puts @palette.paint(:dim, tally)
         @out.puts report.shard.line if report.shard
@@ -185,9 +188,11 @@ module Saboteur
         total = @palette.paint(:dim, "#{middot} #{format('%.1f', report.wall_time)}s total")
         @out.puts "#{@palette.paint(:pass, win)} #{total}"
         untested = untested_subjects(report)
-        @out.puts "  #{@palette.paint(:warn, untested_win_note(untested))}" if untested.any?
+        @out.puts "  #{@palette.paint(:warn, Wording.untested_win_note(untested))}" if untested.any?
         ReuseNote.new(@out).print(report)
-        clean_reports_line
+        # The footer owns the report paths (#1187); the clean screen's own
+        # hint is the follow-up run a whole-project win suggests.
+        @out.puts "  #{@palette.paint(:dim, 'next: saboteur run --since origin/main')}" if @scope == "whole project"
       end
 
       # The phase lines and the progress-dots line print only when their data
@@ -209,19 +214,6 @@ module Saboteur
         "#{report.counts[:killed]}/#{report.executed.size} mutants killed"
       end
 
-      def untested_win_note(untested)
-        ids = untested.map(&:id).join(", ")
-        "#{untested.size} subject#{'s' unless untested.one?} not scored - no tests exist: #{ids}"
-      end
-
-      def clean_reports_line
-        return unless @html_report
-
-        line = "reports: #{@html_report}"
-        line += " #{middot} next: saboteur run --since origin/main" if @scope == "whole project"
-        @out.puts "  #{@palette.paint(:dim, line)}"
-      end
-
       def hazard_suppressions(report)
         return unless report.hazard_suppressions.positive?
 
@@ -250,22 +242,26 @@ module Saboteur
         end
 
         line = "Score: #{painted_score(breakdown.value)}#{headline_context(breakdown.value)}"
-        line << if breakdown.tested.zero?
-                  " - nothing tested"
-                else
-                  " (#{breakdown.detected}/#{breakdown.tested} killed, tested subjects)"
-                end
+        line << score_parenthetical(breakdown)
         if @verbose && breakdown.tested.positive?
           line << "#{score_split(breakdown)} (killed+timeout)/(killed+survived+timeout); " \
                   "errors, resource limits and skips excluded"
         end
         if untested.any?
           line << "  #{@palette.paint(:warn, "#{untested.size} subject#{'s' unless untested.one?} " \
-                                             'not scored - no tests exist')}"
+                                             "not scored - #{Wording.no_execution(untested.size)}")}"
         end
         @out.puts line
       end
 
+      # The share of tested mutants the run detected: "killed" alone would
+      # count timeouts too, so Wording names both when one is in the number.
+      def score_parenthetical(breakdown)
+        return " - nothing tested" if breakdown.tested.zero?
+
+        " (#{breakdown.detected}/#{breakdown.tested} #{Wording.detected_word(breakdown)}, tested subjects)"
+      end
+
       # What the score is judged against and where it came from: the
       # threshold it must meet, and the last score the history recorded.
       def headline_context(value)
@@ -307,7 +303,7 @@ module Saboteur
         return if untested.empty?
 
         @out.puts
-        @out.puts @palette.paint(:warn, "Not scored - no tests exist (treat these as your biggest gaps):")
+        @out.puts @palette.paint(:warn, "Not scored - no test executes these (treat these as your biggest gaps):")
         entries = untested.map { |subject| "#{subject.id} (#{subject.location(report.root)})" }
         line = "  #{@palette.paint(:warn, '!')} #{entries.first(MAX_NOT_SCORED).join(" #{middot} ")}"
         line << " #{middot} ... #{entries.size - MAX_NOT_SCORED} more" if entries.size > MAX_NOT_SCORED
@@ -597,7 +593,9 @@ module Saboteur
       end
 
       def survivors(report)
-        SurvivorList.new(@out, @palette, all_mutants: @all_mutants).call(report, ranked_survivors(report))
+        SurvivorList.new(@out, @palette, all_mutants: @all_mutants,
+                                         whole_suite_map: @whole_suite_map, run_map: @run_map)
+                    .call(report, ranked_survivors(report))
         @out.puts unless report.survivors.empty?
       end
 

data/lib/saboteur/reporter/wording.rb

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    # One wording for the score parenthetical and the not-scored note, so
+    # the terminal screen and the HTML page never drift (#1145, #1146).
+    module Wording
+      module_function
+
+      # detected counts timeouts, the tally does not: name both when a
+      # timeout is in the number, or "killed" means two things in adjacent
+      # lines (#1146).
+      def detected_word(breakdown)
+        breakdown.timeouts.positive? ? "killed or timed out" : "killed"
+      end
+
+      # A subject with no coverage may have tests that stub it away: the
+      # honest claim is about execution, not existence (#1145).
+      def no_execution(untested_count)
+        untested_count == 1 ? "no test executes it" : "no test executes them"
+      end
+
+      # The score table's per-file note fragment: count, subject noun and
+      # the execution claim in one shape (#1145).
+      def untested_note(count)
+        "#{count} subject#{'s' unless count == 1} - #{no_execution(count)}"
+      end
+
+      # The clean screen's one-line note for subjects no run scored.
+      def untested_win_note(untested)
+        ids = untested.map(&:id).join(", ")
+        "#{untested.size} subject#{'s' unless untested.one?} not scored - #{no_execution(untested.size)}: #{ids}"
+      end
+    end
+  end
+end

data/lib/saboteur/result.rb

@@ -72,6 +72,16 @@ module Saboteur
                        executed: executed, confirmation: confirmation)
     end
 
+    # The reason a --flaky-check disagreement starts with: unverified, but
+    # not because a budget ran out (#1167).
+    FLAKY_PREFIX = "flaky verdict"
+
+    def self.flaky_reason?(reason) = reason.to_s.start_with?(FLAKY_PREFIX)
+
+    # Unverified because the reordered confirmation run disagreed, not
+    # because --max-duration cut the check short.
+    def flaky? = status == :unverified && self.class.flaky_reason?(reason)
+
     # The same mutant, marked unverified: the budget ran out before its
     # verdict could be checked, so it must not count as detected (#296).
     def as_unverified(reason)

data/lib/saboteur/text.rb

@@ -11,6 +11,12 @@ module Saboteur
   module Text
     module_function
 
+    # "1 subject" / "2 subjects": the count with the noun in the right
+    # number (review C9). An irregular plural passes explicitly.
+    def counted(count, singular, plural = "#{singular}s")
+      "#{count} #{count == 1 ? singular : plural}"
+    end
+
     # A list for a warning or note: the first five items, then "and N more".
     # One rule for every message that names files, subjects or specs (#332).
     # Items are repo-controlled text, so each is display_safe (#834).

data/lib/saboteur/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: saboteur
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.11.2
 platform: ruby
 authors:
 - Vamsi Pavan Mahesh Gunturu
@@ -68,9 +68,11 @@ files:
 - lib/saboteur/cli/error_cause.rb
 - lib/saboteur/cli/execution_options.rb
 - lib/saboteur/cli/exit_status.rb
+- lib/saboteur/cli/explain_command.rb
 - lib/saboteur/cli/explicit_file_options.rb
 - lib/saboteur/cli/explicit_sources.rb
 - lib/saboteur/cli/failure_output.rb
+- lib/saboteur/cli/flaky_exit.rb
 - lib/saboteur/cli/help_command.rb
 - lib/saboteur/cli/help_options.rb
 - lib/saboteur/cli/history_command.rb
@@ -203,6 +205,7 @@ files:
 - lib/saboteur/mutation_source/operand_replacement.rb
 - lib/saboteur/mutation_source/operator_assignment.rb
 - lib/saboteur/mutation_source/operator_examples.rb
+- lib/saboteur/mutation_source/operator_explain.rb
 - lib/saboteur/mutation_source/operator_registry.rb
 - lib/saboteur/mutation_source/operator_visit.rb
 - lib/saboteur/mutation_source/pair_removal.rb
@@ -224,6 +227,7 @@ files:
 - lib/saboteur/reporter/baseline_tail.rb
 - lib/saboteur/reporter/diff.rb
 - lib/saboteur/reporter/findings.rb
+- lib/saboteur/reporter/gap_kinds.rb
 - lib/saboteur/reporter/history_paths.rb
 - lib/saboteur/reporter/history_policy.rb
 - lib/saboteur/reporter/history_reader.rb
@@ -247,6 +251,7 @@ files:
 - lib/saboteur/reporter/survivor_ranking.rb
 - lib/saboteur/reporter/terminal.rb
 - lib/saboteur/reporter/test_matrix.rb
+- lib/saboteur/reporter/wording.rb
 - lib/saboteur/result.rb
 - lib/saboteur/score.rb
 - lib/saboteur/selection/coverage_map.rb