saboteur 0.11.0 → 0.11.2

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)
@@ -159,9 +169,9 @@ module Saboteur
     MAX_ERROR_FRACTION = 0.5
 
     attr_reader :results, :subjects, :wall_time, :invalid_mutations, :warnings, :live_announced, :root, :seed,
-                :skipped_subjects,
+                :skipped_subjects, :since,
                 :generation_events, :omissions, :run_evidence, :hazard_suppressions, :early_stop, :inline_suppressions,
-                :operator_policy, :discovery_failures, :memory, :shard, :test_command, :referenced
+                :operator_policy, :discovery_failures, :memory, :shard, :test_command, :referenced, :reuse_label
 
     # REVIEW: diff mode; the terminal then shows one survivor per line.
     # seed: the random seed every test run started from (nil when unknown).
@@ -170,7 +180,7 @@ module Saboteur
                    seed: nil, skipped_subjects: {}, diff_scope: nil, generation_events: [], omissions: [],
                    run_evidence: nil, hazard_suppressions: 0, early_stop: nil, matrix: false, inline_suppressions: [],
                    operator_policy: nil, discovery_failures: [], memory: nil, shard: nil,
-                   test_command: nil, referenced: {})
+                   test_command: nil, referenced: {}, reuse_label: nil, since: nil)
       @results = results
       @subjects = subjects
       @wall_time = wall_time
@@ -182,15 +192,12 @@ module Saboteur
       @seed = seed
       @skipped_subjects = skipped_subjects
       @diff_scope = diff_scope
-      @generation_events = generation_events.dup.freeze
-      @omissions = omissions.dup.freeze
+      take_frozen_copies(generation_events, omissions, inline_suppressions, discovery_failures)
       @run_evidence = run_evidence
       @hazard_suppressions = hazard_suppressions
       @early_stop = early_stop
       @matrix = matrix
-      @inline_suppressions = inline_suppressions.dup.freeze
       @operator_policy = operator_policy
-      @discovery_failures = discovery_failures.dup.freeze
       # Per-worker and supervisor peak RSS in MB, when the platform measured
       # it (#202); nil elsewhere, so JSON reports omit the section.
       @memory = memory.dup.freeze
@@ -198,9 +205,14 @@ module Saboteur
       # The external command of a --test-command run, nil for in-process
       # runs. Its presence means survivors carry no coverage map (#641).
       @test_command = test_command
+      # The --since ref of a diff run, nil for a whole-project run. The
+      # expand hint and the HTML report echo it, so the scope survives the
+      # run that produced them.
+      @since = since
       # file => specs, for files whose specs were chosen by constant reference
       # or require instead of by name (zero-setup selection).
       @referenced = referenced
+      @reuse_label = reuse_label
     end
 
     # A --matrix run: every covering test ran per mutant.
@@ -208,8 +220,16 @@ module Saboteur
       @matrix
     end
 
+    # The skipped subjects the live selection notice did not already name.
+    def unannounced_skips
+      skipped_subjects.reject do |subject, reason|
+        prefix = Text.display_safe_lines("#{subject.id} (#{subject.location(root)}): skipped (#{reason})")
+        live_announced.any? { |line| line.start_with?(prefix) }
+      end
+    end
+
     # True when the run was scoped to a diff (--since): the expand command
-    # echoes that scope.
+    # echoes that scope's ref.
     def diff?
       !@diff_scope.nil?
     end
@@ -288,5 +308,16 @@ module Saboteur
       timed = executed.reject(&:reused?).filter_map(&:runtime)
       timed.empty? ? nil : timed.sum / timed.size
     end
+
+    # The run lists arrive from builders that may reuse them; the report
+    # keeps its own frozen copies.
+    private
+
+    def take_frozen_copies(generation_events, omissions, inline_suppressions, discovery_failures)
+      @generation_events = generation_events.dup.freeze
+      @omissions = omissions.dup.freeze
+      @inline_suppressions = inline_suppressions.dup.freeze
+      @discovery_failures = discovery_failures.dup.freeze
+    end
   end
 end

data/lib/saboteur/selection/git_diff.rb

@@ -15,6 +15,9 @@ module Saboteur
       NO_FILE = "/dev/null" # rubocop:disable Style/FileNull -- literal in git diff output
       HUNK = /\A@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/
 
+      LOCAL_BRANCH_CAP = 5
+      BASE_NAMES = %w[main master trunk develop].freeze
+
       module_function
 
       # Fails before any boot work when REF is not a commit here, as a usage
@@ -38,12 +41,22 @@ module Saboteur
         message = "--since #{ref}: not a commit in this repository " \
                   "(check the name; a shallow checkout may need a deeper fetch)"
         branch = default_branch(root)
-        return message unless branch
+        return "#{message}#{local_branches_hint(root)}" unless branch
 
         "#{message}; this repository's default branch is '#{branch}' - " \
           "pass it explicitly: saboteur pr #{branch}"
       end
 
+      # A local-only repo has no origin/HEAD to name: list the branches it
+      # does have, so a bare `saboteur pr` (default main) points at a real one.
+      def local_branches_hint(root)
+        out, _, ok = Open3.capture3("git", "for-each-ref", "--format=%(refname:short)", "refs/heads", chdir: root)
+        branches = ok.success? ? likely_bases(out.split("\n")).first(LOCAL_BRANCH_CAP) : []
+        return "" if branches.empty?
+
+        "; local branches: #{branches.join(', ')} - pass one explicitly: saboteur pr #{branches.first}"
+      end
+
       # The default branch origin publishes, without the remote name, or nil
       # when origin has no HEAD (a local-only clone keeps the plain hint).
       def default_branch(root)
@@ -54,6 +67,11 @@ module Saboteur
         branch.empty? ? nil : branch
       end
 
+      # Conventional base names first, so the suggested example is a base.
+      def likely_bases(branches)
+        branches.sort_by { |name| [BASE_NAMES.index(name) || BASE_NAMES.size, name] }
+      end
+
       def merge_base(ref, root:)
         git(root, "merge-base", ref, "HEAD").strip
       end

data/lib/saboteur/survivor_guidance.rb

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  # One wording for the two survivor follow-ups a user copies: replaying
+  # one mutant and accepting one in the ignore file. The run screen (Next
+  # steps) and `saboteur survivors --show` share these strings so the two
+  # surfaces never drift (#1167).
+  module SurvivorGuidance
+    REPLAY_CAVEAT = "(add this run's own --config, --since, --subject, --test and source options)"
+    IGNORE_INTRO = "accept an equivalent one: add to your ignore file " \
+                   "(c.ignore_file, default #{Config::IGNORE_FILE}):".freeze
+    REASON_PLACEHOLDER = "why it is equivalent"
+
+    module_function
+
+    def replay_command(digest, seed: nil)
+      "saboteur run --id #{digest}#{" --seed #{seed}" if seed}"
+    end
+
+    # One line, paste-ready. todo names what the user must still fill in
+    # (a capped report omits the subject for some digests).
+    def ignore_entry(digest, subject_id, todo: nil)
+      entry = %(i.mutation "#{digest}", subject: "#{subject_id}", reason: "#{REASON_PLACEHOLDER}")
+      todo ? "#{entry} # TODO: #{todo}" : entry
+    end
+
+    # The entry wrapped so it pastes into the ignore file as-is (#1194).
+    def ignore_block(digest, subject_id, todo: nil)
+      "Saboteur.ignore do |i|\n  #{ignore_entry(digest, subject_id, todo: todo)}\nend"
+    end
+  end
+end

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.0"
+  VERSION = "0.11.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: saboteur
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.11.2
 platform: ruby
 authors:
 - Vamsi Pavan Mahesh Gunturu
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -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
@@ -232,8 +236,10 @@ files:
 - lib/saboteur/reporter/kill_causes.rb
 - lib/saboteur/reporter/mutation_text.rb
 - lib/saboteur/reporter/next_steps.rb
+- lib/saboteur/reporter/notice.rb
 - lib/saboteur/reporter/palette.rb
 - lib/saboteur/reporter/replay.rb
+- lib/saboteur/reporter/reuse_note.rb
 - lib/saboteur/reporter/review_comments.rb
 - lib/saboteur/reporter/safe_out.rb
 - lib/saboteur/reporter/score_history.rb
@@ -245,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
@@ -258,6 +265,7 @@ files:
 - lib/saboteur/selection/untracked_changes.rb
 - lib/saboteur/subject.rb
 - lib/saboteur/subject_finder.rb
+- lib/saboteur/survivor_guidance.rb
 - lib/saboteur/text.rb
 - lib/saboteur/version.rb
 - lib/saboteur/working_tree.rb