saboteur 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e61c3755190680c12faf62b3a0bcad5f74750da7ff3e3716736e8b9aa733c46
-  data.tar.gz: 85dc6bbddcc174034da44607b55c5c438c883bc5e0c5954a68d8115abb4b5984
+  metadata.gz: e9537980fed0394bdadcbd64d8e637e55cfb42925b5673d2ee30e6f0b18bb13e
+  data.tar.gz: a628132a21155e240bc856c99707f46323f280929344048be98a746fa74d1c9b
 SHA512:
-  metadata.gz: eceece31e29ceb03758b67aaa4ecfddcf1f6ca1f864358706fabcb8c9fed1f725da5548cd4f810684ac85250651f234b182452dd0525309711b616b997bf8026
-  data.tar.gz: f62d86ac983b24a550ba5696372fee7f9883be0103e823997f5fdd64c7150b42a8d88aae38881cd65ecd3b2141b39c22c9b7513552506a6499dddceb30128a69
+  metadata.gz: c96be31b305e173850739c426f5343fb6a24b416cb5f923b30cfea4a8764fb0c9dd3eeeb5dc8b00af132e16267e8e4135ea84d2d5669b38e35433323e94c072c
+  data.tar.gz: 9763cf728f40ad70a714665bc4cdf09ce0a9d516d7da9101bb137f60cdb378a5715d321d8b71d725ac635736b167a9ce6ec3b8c5e99632ef1f204cea49ad3e94

data/CHANGELOG.md

@@ -6,6 +6,34 @@ All notable changes are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.12.1] - 2026-10-22
+
+### Changed
+
+- `--quiet` now stays quiet from startup: the start header, baseline
+  line, inference detail and progress bar no longer print. A `--since`
+  diff that selects no mutants exits 0 with a plain "nothing to gate"
+  note instead of failing a score threshold, and `--ignore-empty` is a
+  deprecated no-op. A diff with suppressed, omitted or undiscovered
+  mutants, or with an unverifiable scope, still gates (#1268, #1142,
+  #1149).
+- `saboteur survivors` lists survivors ranked by default, matching
+  `run`, and owns its own command surface and help (#1269, #1150).
+
+### Fixed
+
+- An error-dominated run no longer prints a bare score: the terminal
+  closing line and the HTML report headline and summary say `n/a`, like
+  the terminal headline already did (#1275, #1271, #1276, #1272).
+
+### Tests
+
+- New end-to-end pins for per-path score gates, the `Score: n/a`
+  headline, the README get-started flow, parallel coverage parts and
+  the trace recorder, survivor triage labels, kills split by cause and
+  a docs-only `--since` diff under a threshold (#1270, #1273, #1278,
+  #1279, #1280, #1281, #1277, #1159, #1158).
+
 ## [0.12.0] - 2026-10-22
 
 ### Added

data/lib/saboteur/cli/exit_status.rb

@@ -15,7 +15,7 @@ module Saboteur
       def exit_code(report)
         return EXIT_BUDGET if budget_exhausted?(report)
 
-        return EXIT_OK if ignore_empty_diff?(report)
+        return EXIT_OK if empty_clean_diff?(report)
 
         return EXIT_TOOL if untested_partial?(report)
 
@@ -29,14 +29,18 @@ module Saboteur
         gates.failed?(report, @err, record_cause: !quality_failed) || quality_failed ? EXIT_SURVIVORS : EXIT_OK
       end
 
-      # --ignore-empty: a --since diff that selected no mutants exits 0 with
-      # a note; suppressed, omitted or undiscovered mutants still gate.
-      def ignore_empty_diff?(report)
-        return false unless config["ignore_empty"] && config["since"] && report.results.empty?
+      # A --since diff that selected no mutants exits 0 with a plain note,
+      # with or without --ignore-empty: a docs-only change has no score, so a
+      # threshold must not fail it (#1142). Suppressed, omitted or
+      # undiscovered mutants still gate - the selection must be honestly
+      # empty, not just empty-handed.
+      def empty_clean_diff?(report)
+        return false unless config["since"] && report.results.empty?
+        return false if unverifiable_scope?(report)
         return false unless report.omissions.empty? && report.inline_suppressions.empty? &&
                             report.discovery_failures.empty?
 
-        @err.puts("saboteur: no mutants in the diff - nothing to gate (--ignore-empty)")
+        @err.puts("saboteur: no mutants in the diff - nothing to gate")
         true
       end
 

data/lib/saboteur/cli/run_reporting.rb

@@ -81,7 +81,7 @@ module Saboteur
 
         # Text mode only: the engine prints a per-subject marks line when
         # --verbose is on (#262); --agent output stays as it is.
-        engine = Engine.new(config, **arguments, verbose: @verbose || false)
+        engine = Engine.new(config, **arguments, verbose: @verbose || false, quiet: @quiet || false)
         text_run(engine.call, engine)
       end
 

data/lib/saboteur/cli/selection_options.rb

@@ -22,8 +22,9 @@ module Saboteur
         opts.on("--id DIGEST", "Replay exactly one current mutant by its full digest") { |v| set(:id, v) }
         opts.on("--shard K/N", "Run one of N deterministic candidate shards (for example 1/4)") { |v| set(:shard, v) }
         opts.on("--since REF", "Only mutate subjects changed since git REF") { |v| options[:since] = v }
-        opts.on("--ignore-empty", "A --since diff that selects no mutants exits 0 with a note instead of " \
-                                  "failing a score gate") { set(:ignore_empty, true) }
+        opts.on("--ignore-empty", "Deprecated no-op: the no-mutant diff case always exits 0 (#1142)") do
+          set(:ignore_empty, true)
+        end
         flaky_desc = "Confirm a fresh verdict (survivors, decisive) with one reordered rerun"
         opts.on("--flaky-check MODE", %w[off survivors decisive], flaky_desc) { |v| set(:flaky_check, v) }
         opts.on("--subject EXPR", "Klass#meth, Klass.meth or a namespace; repeatable") { |v| add_subject(v) }

data/lib/saboteur/cli/survivors_command.rb

@@ -2,8 +2,10 @@
 # frozen_string_literal: true
 
 require "json"
+require "stringio"
 
 require_relative "../survivor_guidance"
+require_relative "../reporter/palette"
 require_relative "../reporter/survivor_hints"
 
 module Saboteur
@@ -17,6 +19,11 @@ module Saboteur
       # Where `saboteur run` writes the JSON report unless configured otherwise.
       DEFAULT_REPORT = Config::DEFAULTS["json_report"]
 
+      # survivors owns its usage line (#1150): the report path is optional
+      # because the run always writes the same default.
+      SURVIVORS_USAGE = "Usage: saboteur survivors [options] [REPORT] - REPORT defaults to " \
+                        ".saboteur/report.json"
+
       private
 
       def survivors_command
@@ -27,28 +34,50 @@ module Saboteur
       end
 
       def survivors_command_inner
-        parser = OptionParser.new do |opts|
-          opts.on("--ranked", "Review-priority order: the report's ranked findings first")
-          opts.on("--file SUBSTR", "Only survivors whose path contains SUBSTR")
-          opts.on("--operator NAME", "Only survivors of operator NAME")
-          opts.on("--triage LABEL", "Only survivors classified LABEL (for example boundary)")
-          opts.on("--show DIGEST", "Diff, replay command and ignore template for one survivor")
-        end
         options = {}
-        args = parser.parse!(@argv, into: options)
+        parser = survivors_parser(options)
+        args = parse_survivors_args(parser, options)
+        if options[:help]
+          @out.puts(parser)
+          return EXIT_OK
+        end
         path = args.shift || DEFAULT_REPORT
-        raise UsageError, "unexpected arguments: #{args.join(' ')}" if args.any?
+        raise UsageError, "unexpected arguments: #{args.join(' ')}\n#{parser}" if args.any?
 
         report = load_survivor_report(path)
-        browser = SurvivorsBrowser.new(report)
+        browser = SurvivorsBrowser.new(report, palette: Reporter::Palette.for(@out, mode: options.fetch(:color, :auto)))
         if options[:show]
           @out.puts(browser.show(options[:show]))
         else
-          @out.puts(browser.list(**options.slice(:ranked, :file, :operator, :triage)))
+          @out.puts(browser.list(**options.slice(:file, :operator, :triage)))
         end
         EXIT_OK
       end
 
+      # The same colour flags as run (#1150), plus the browser filters.
+      def survivors_parser(options)
+        OptionParser.new do |opts|
+          opts.banner = SURVIVORS_USAGE
+          opts.on("--ranked", "Review-priority order (the default): the terminal report's ordering")
+          opts.on("--file SUBSTR", "Only survivors whose path contains SUBSTR")
+          opts.on("--operator NAME", "Only survivors of operator NAME")
+          opts.on("--triage LABEL", "Only survivors classified LABEL (for example boundary)")
+          opts.on("--show DIGEST", "Diff, replay command and ignore template for one survivor")
+          opts.on("--color [MODE]", %w[always never auto],
+                  "Colour the output: always, never, or auto when MODE is omitted") do |mode|
+            options[:color] = (mode || :always).to_sym
+          end
+          opts.on("--no-color", "Alias for --color=never") { options[:color] = :never }
+          opts.on("--help", "Show this help") { options[:help] = true }
+        end
+      end
+
+      def parse_survivors_args(parser, options)
+        parser.parse!(@argv, into: options)
+      rescue OptionParser::ParseError => e
+        raise UsageError, "#{e.message}\n#{parser}"
+      end
+
       def load_survivor_report(path)
         unless File.file?(path)
           hint = path == DEFAULT_REPORT ? "; run saboteur first, or pass a report path" : ""
@@ -64,14 +93,21 @@ module Saboteur
     # Reads the report's files section (the complete mutant list), not the
     # capped findings, so survivors beyond the findings limit still list.
     class SurvivorsBrowser
-      def initialize(report)
+      # Sibling digests named on a collapse line; the rest are a count - the
+      # same shape the terminal report's collapse uses (#1150).
+      SIBLING_DIGEST_CAP = 3
+
+      def initialize(report, palette: Reporter::Palette.for(StringIO.new))
         @report = report
         @findings = report.dig("saboteur", "findings") || {}
+        @palette = palette
       end
 
-      def list(ranked: false, file: nil, operator: nil, triage: nil)
-        survivors = filtered(file, operator, triage)
-        survivors = ranked_order(survivors) if ranked
+      # One ordering everywhere (#1150): the terminal report's ranked order
+      # is the default, exactly as the findings carry it; --ranked stays
+      # accepted for compatibility.
+      def list(file: nil, operator: nil, triage: nil, **)
+        survivors = ranked_order(filtered(file, operator, triage))
         return "no survivors#{filters_note(file, operator, triage)}" if survivors.empty?
 
         [header(survivors.size, file, operator, triage), *rows(survivors)]
@@ -160,19 +196,32 @@ module Saboteur
       def header(size, file, operator, triage)
         text = "#{size} survivor#{'s' unless size == 1}#{filters_note(file, operator, triage)}"
         truncated = @findings["survivorsTruncated"].to_i
-        return text unless truncated.positive?
-
-        "#{text} (the report's ranked findings name only the first #{@findings['limit'] || 10})"
+        if truncated.positive?
+          text = "#{text} (the report's ranked findings name only the first #{@findings['limit'] || 10})"
+        end
+        @palette.paint(:head, text)
       end
 
+      # The terminal collapse: sibling mutants on one statement fold into the
+      # first row, which names up to SIBLING_DIGEST_CAP of their digests.
       def rows(survivors)
-        survivors.each_with_index.map do |s, i|
-          format("%3<i>d. %<path>s:%<line>d  %-28<operator>s %<digest>s  %<classification>s",
-                 i: i + 1, path: s[:path], line: s[:line], operator: s[:operator], digest: s[:digest],
-                 classification: s[:classification] || "-")
+        survivors.group_by { |s| [s[:path], s[:line]] }.values.each_with_index.map do |group, i|
+          first, *siblings = group
+          format("%3<i>d. %<path>s:%<line>d  %-28<operator>s %<digest>s  %<classification>s%<suffix>s",
+                 i: i + 1, path: first[:path], line: first[:line], operator: first[:operator],
+                 digest: first[:digest], classification: first[:classification] || "-",
+                 suffix: siblings_suffix(siblings))
         end
       end
 
+      def siblings_suffix(siblings)
+        return "" if siblings.empty?
+
+        named = siblings.first(SIBLING_DIGEST_CAP).map { |s| s[:digest] }.join(", ")
+        rest = siblings.size - SIBLING_DIGEST_CAP
+        "  (+#{siblings.size} here: #{named}#{", +#{rest} more" if rest.positive?})"
+      end
+
       def ignore_entry(survivor, subject)
         block = if subject
                   SurvivorGuidance.ignore_block(survivor[:digest], subject)
@@ -192,12 +241,17 @@ module Saboteur
                 subject: m["subject"], covered: m["coveredBy"] || [], source: entry["source"] }
             end
           end
-          survivors.sort_by { |s| [s[:path], s[:line], s[:digest]] }
+          survivors
         end
       end
 
+      # Ranked order straight from the report: the uncapped findings "order"
+      # list first, with the capped findings as the fallback for older
+      # reports; anything unknown trails in file order.
       def ranked_order(survivors)
-        rank = @findings.fetch("survivors", []).each_with_index.to_h { |f, i| [f["digest"], i] }
+        order = @findings["order"] ||
+                (@findings.fetch("survivors", []) + @findings.fetch("accepted", [])).map { |f| f["digest"] }
+        rank = order.each_with_index.to_h
         survivors.sort_by { |s| [rank[s[:digest]] || Float::INFINITY, -s[:covered].size, s[:path], s[:line], s[:digest]] }
       end
 

data/lib/saboteur/engine/diagnostics.rb

@@ -17,6 +17,12 @@ module Saboteur
       # be watched: the heartbeat then adds the count, the percentage and an
       # estimate of the time left to its elapsed-time line.
       class ProgressHeartbeat
+        # --quiet substitute: responds to the supervisor's calls, prints nothing.
+        NULL = Object.new.tap do |noop|
+          def noop.watch(*) = self
+          def noop.tick = nil
+        end
+
         COUNT = %r{(\d+)/([1-9]\d*) examples finished}
         TAIL_BYTES = 4096
 
@@ -91,9 +97,10 @@ module Saboteur
       attr_reader :warnings, :live_announced, :invalid_mutations, :generation_events, :omissions, :discovery_failures,
                   :hazard_suppressions, :inline_suppressions, :verbose, :quiet_start
 
-      def initialize(err, verbose: false, palette: nil, quiet_start: true)
+      def initialize(err, verbose: false, palette: nil, quiet_start: true, quiet: false)
         @err = err
         @verbose = verbose
+        @quiet = quiet
         @quiet_start = quiet_start
         @palette = palette || Reporter::Palette.for(err)
         @warnings = []
@@ -183,7 +190,7 @@ module Saboteur
       # Chatter the default view folds into the quiet-start lines;
       # --verbose prints it byte-for-byte as before.
       def detail(message)
-        inform(message) if @verbose || !@quiet_start
+        inform(message) if !@quiet && (@verbose || !@quiet_start)
       end
 
       # A selection explanation the default view carries as one dim
@@ -199,7 +206,7 @@ module Saboteur
       # The quiet start: three lines, then progress. --verbose keeps
       # today's chatter instead and never prints these.
       def quiet_start_header(scope:, seed:, operators:)
-        return if @verbose || !@quiet_start
+        return if @quiet || @verbose || !@quiet_start
 
         dot = @palette.glyph(:middot)
         line = "saboteur #{Saboteur::VERSION} #{dot} #{scope} #{dot} seed #{seed} #{dot} " \
@@ -208,7 +215,7 @@ module Saboteur
       end
 
       def quiet_baseline(passes:, elapsed:, tests:, cached:)
-        return if @verbose || !@quiet_start
+        return if @quiet || @verbose || !@quiet_start
 
         check = @palette.paint(:pass, @palette.glyph(:check))
         suffix = cached ? " (cached)" : ""
@@ -219,7 +226,7 @@ module Saboteur
       end
 
       def quiet_inference(spec_count)
-        return if spec_count.nil? || @verbose || !@quiet_start
+        return if spec_count.nil? || @quiet || @verbose || !@quiet_start
 
         files = spec_count == 1 ? "spec file" : "spec files"
         @err.puts(@palette.paint(:dim, "spec inference: #{spec_count} #{files} (details: --verbose)"))
@@ -252,6 +259,10 @@ module Saboteur
       # fork time. Prints "<label>: N s elapsed" about every interval
       # seconds, so a long phase does not look stuck.
       def progress_heartbeat(label, interval: 30)
+        # --quiet: the contract is findings, score and verdict - no elapsed
+        # chatter; the heartbeat's ticks become no-ops.
+        return ProgressHeartbeat::NULL if @quiet
+
         ProgressHeartbeat.new(self, label, interval: interval)
       end
 
@@ -261,6 +272,8 @@ module Saboteur
       # The count lives in one file the workers inherit, so every worker adds
       # to the same number.
       def start_progress(total)
+        return if @quiet
+
         @progress_total = total
         @progress_started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         @progress_file = Tempfile.new("saboteur-progress")
@@ -271,6 +284,8 @@ module Saboteur
       end
 
       def progress(result)
+        return if @quiet
+
         mark = MARKS.fetch(result.status, "?")
         return plain_progress(painted_mark(mark)) unless @progress_file
 

data/lib/saboteur/engine.rb

@@ -46,10 +46,11 @@ module Saboteur
     attr_reader :guessed_tests
 
     def initialize(config, err: $stderr, digest: nil, capture_evidence: false, evidence_files: [], verbose: false,
-                   palette: nil, quiet_start: true)
+                   palette: nil, quiet_start: true, quiet: false)
       @config = config
       @hooks = Hooks.new
-      @diagnostics = Diagnostics.new(err, verbose: verbose, palette: palette, quiet_start: quiet_start)
+      @diagnostics = Diagnostics.new(err, verbose: verbose, palette: palette, quiet_start: quiet_start,
+                                          quiet: quiet)
       @completed_baseline_passes = 0
       @baseline_elapsed = 0.0
       @root = File.realpath(config.root)

data/lib/saboteur/help.rb

@@ -140,15 +140,15 @@ module Saboteur
         name: "survivors",
         summary: "Browse a report's survivors in the terminal, read-only",
         description: "Reads the Stryker JSON report without booting the project or rerunning tests. " \
-                     "Lists every survivor with rank, file, line, operator, digest and triage label; " \
-                     "filters with --file, --operator and --triage; --ranked uses the report's ranked " \
-                     "findings order. --show DIGEST prints the diff, the exact replay command and an " \
-                     "ignore-file entry template for that mutant. It never edits the ignore file.",
+                     "Lists every survivor with rank, file, line, operator, digest and triage label, " \
+                     "in the report's ranked findings order; filters with --file, --operator and " \
+                     "--triage; --ranked is kept for compatibility. --show DIGEST prints the diff, " \
+                     "the exact replay command and an ignore-file entry template for that mutant. " \
+                     "It never edits the ignore file.",
         takes_options: false,
         exit_codes: { 0 => "Survivors listed or shown (including none).",
                       2 => "Missing, malformed or unreadable report; bad arguments." },
         examples: [["List survivors from the last run", "saboteur survivors .saboteur/report.json"],
-                   ["Review-priority order", "saboteur survivors .saboteur/report.json --ranked"],
                    ["Diff, replay command and ignore template for one mutant",
                     "saboteur survivors .saboteur/report.json --show 1a2b3c4d5e6f7a8b"]]
       ),

data/lib/saboteur/reporter/findings.rb

@@ -12,6 +12,8 @@ module Saboteur
     # Survivors accepted on the ignore list are listed apart, with their
     # reason. The full, unbounded mutant data stays in the report's files
     # section; survivorsTruncated says how many more findings live only there.
+    # The uncapped ranked digest list lets offline readers (the survivors
+    # command) print the terminal's ordering without recomputing it (#1150).
     module Findings
       VERSION = 1
 
@@ -30,7 +32,8 @@ module Saboteur
             survivors: listed(report, live),
             survivorsTruncated: truncated(live),
             accepted: listed(report, accepted),
-            acceptedTruncated: truncated(accepted)
+            acceptedTruncated: truncated(accepted),
+            order: full_order(report, live, accepted)
           }
         end
 
@@ -44,6 +47,12 @@ module Saboteur
           [results.size - LIMIT, 0].max
         end
 
+        # Every survivor digest in terminal order: live ranked first, then
+        # accepted - uncapped, unlike the findings lists themselves.
+        def full_order(report, live, accepted)
+          (ordered(report, live) + ordered(report, accepted)).map(&:digest)
+        end
+
         def ordered(report, results)
           SurvivorRanking.ordered(report, results)
         end

data/lib/saboteur/reporter/html.rb

@@ -151,6 +151,8 @@ module Saboteur
       # the same contract as the terminal headline.
       def headline(report)
         breakdown = report.score_breakdown
+        return error_dominated_headline(report) if report.majority_errored?
+
         text = "<p><strong>Covered mutation score: #{score_text(report.score)}</strong>"
         if breakdown.tested.positive?
           text << " (#{breakdown.detected}/#{breakdown.tested} #{Wording.detected_word(breakdown)}, tested subjects)"
@@ -195,12 +197,21 @@ module Saboteur
         "#{Text.counted(report.subjects.size, 'subject')}, #{Text.counted(report.results.size, 'mutant')}"
       end
 
+      # An error-dominated run shows no bare score, like the terminal headline
+      # (#557, #1272): the share covers only the few mutants that were scored.
+      def error_dominated_headline(report)
+        breakdown = report.score_breakdown
+        "<p><strong>Covered mutation score: n/a</strong> (#{breakdown.tested} of #{report.executed.size} " \
+          "mutants scored, #{score_text(breakdown.value)} of scored) - most executed mutants errored, " \
+          "so the run tested almost nothing</p>"
+      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>
+          <p><strong>Covered mutation score: #{score_text(report.majority_errored? ? nil : report.score)}</strong>
           (#{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

data/lib/saboteur/reporter/terminal.rb

@@ -332,7 +332,8 @@ module Saboteur
         parts = state_parts(report)
         parts << "no mutants" if parts.empty?
         line = "saboteur: #{parts.join(', ')} in #{duration(report.wall_time)}"
-        line += " - score #{painted_score(report.score)}"
+        # The headline withholds the score on an error-dominated run (#557); so does this line (#1271).
+        line += " - score #{painted_score(report.majority_errored? ? nil : report.score)}"
         line += " (threshold #{format('%g', @threshold)})" if @threshold
         @out.puts line
       end

data/lib/saboteur/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: saboteur
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
 - Vamsi Pavan Mahesh Gunturu