saboteur 0.4.0 → 0.5.0

data/lib/saboteur/mutation_source/endpoint_replacement.rb

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "base"
+
+module Saboteur
+  module MutationSource
+    # Swaps the selected end of an explicitly received collection.
+    # Only message bytes change; arguments, receiver and block stay intact.
+    class EndpointReplacement < Base
+      REPLACEMENTS = { first: "last", last: "first" }.freeze
+      SCOPE_NODES = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+
+      # Base inherits Object's empty initializer; there is no parent state to set.
+      def initialize(arid: []) # rubocop:disable Lint/MissingSuper
+        @arid = arid.map { |pattern| Regexp.new(pattern) }
+      end
+
+      def name
+        "endpoint_replacement"
+      end
+
+      def mutations_for(subject)
+        found = []
+        visit(subject.node.body, subject, found)
+        found
+      end
+
+      private
+
+      def visit(node, subject, found)
+        return if node.nil? || SCOPE_NODES.any? { |scope| node.is_a?(scope) }
+
+        if node.is_a?(Prism::StatementsNode)
+          node.body.each { |statement| visit(statement, subject, found) unless arid?(statement) }
+          return
+        end
+
+        replace_endpoint(node, subject, found) if node.is_a?(Prism::CallNode)
+        node.compact_child_nodes.each { |child| visit(child, subject, found) }
+      end
+
+      def replace_endpoint(node, subject, found)
+        replacement = REPLACEMENTS[node.name]
+        return unless replacement && node.receiver
+        return if node.block
+        return unless node.arguments.nil?
+
+        location = node.message_loc
+        edit = Edit.new(file: subject.file, start_byte: location.start_offset,
+                        end_byte: location.end_offset, replacement: replacement)
+        found << Mutation.new(subject_id: subject.id, operator: name, edits: [edit], source: name)
+      end
+
+      def arid?(node)
+        @arid.any? { |pattern| pattern.match?(node.slice) }
+      end
+    end
+  end
+end

data/lib/saboteur/mutation_source/hazard_guard.rb

@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module MutationSource
+    # Suppresses mutants that would run a destructive call with altered
+    # inputs. A mutant is only kept when every edit is provably safe: either
+    # the subject holds no hazardous call, or the edit removes every
+    # hazardous call in the method AND its replacement introduces no new one
+    # (checked by parsing the replacement, never by substring match). Edits
+    # strictly inside a call, edits elsewhere in a method that contains a
+    # call, and edits whose replacement re-includes a hazard (for example
+    # removing a negation in front of `system(...)`, or swapping
+    # `rm_rf("build")` for `rm_rf(".")`) all leave a destructive call
+    # running with altered inputs and are suppressed (issue #102).
+    class HazardGuard
+      # "<Receiver>.<name>" for calls with a receiver, the bare name for
+      # Kernel-style calls. Bare FileUtils operations are listed too, so an
+      # `include FileUtils` does not disarm the guard. Any method on Open3,
+      # any rmtree, and backticks/%x literals are always hazardous. Replace
+      # or extend via c.hazard; run them anyway with --allow-hazardous.
+      DEFAULT_HAZARD = [
+        "FileUtils.rm", "FileUtils.rm_r", "FileUtils.rm_rf", "FileUtils.rm_f",
+        "FileUtils.remove_dir", "FileUtils.remove_entry", "FileUtils.remove_entry_secure",
+        "rm", "rm_r", "rm_rf", "rm_f", "remove_dir", "remove_entry", "remove_entry_secure",
+        "File.delete", "File.unlink",
+        "Dir.rmdir", "Dir.delete", "Dir.unlink",
+        "IO.popen",
+        "Process.spawn", "Process.exec",
+        "system", "exec", "spawn", "`"
+      ].freeze
+
+      OPEN3 = /\A(::)?Open3\z/
+      ALWAYS_NAMES = %w[rmtree].freeze
+      KERNEL_RECEIVERS = %w[Kernel Process].freeze
+
+      def initialize(patterns = DEFAULT_HAZARD)
+        @tags = Set.new(patterns.map { |pattern| pattern.to_s.sub(/\A::/, "") })
+      end
+
+      def name
+        "hazard_guard"
+      end
+
+      # candidates: [[mutation, mutated_text]]. Returns [kept, suppressed].
+      def partition(candidates, subject)
+        spans = hazard_spans(subject.node)
+        return [candidates, []] if spans.empty?
+
+        candidates.partition { |mutation, _| safe?(mutation, spans) }
+      end
+
+      private
+
+      # Byte spans of hazardous calls in the node tree, with the source slice
+      # of each. Inner calls are covered by the outer span, so the walk does
+      # not descend into a hazardous call.
+      def hazard_spans(root)
+        spans = []
+        stack = [root]
+        until stack.empty?
+          node = stack.pop
+          if hazardous?(node)
+            spans << [node.location.start_offset, node.location.end_offset, node.slice]
+            next
+          end
+          stack.concat(node.compact_child_nodes)
+        end
+        spans
+      end
+
+      def hazardous?(node)
+        case node
+        when Prism::XStringNode, Prism::InterpolatedXStringNode then true
+        when Prism::CallNode then hazardous_call?(node)
+        else false
+        end
+      end
+
+      def hazardous_call?(node)
+        name = node.name.to_s
+        receiver = node.receiver&.slice&.sub(/\A::/, "")
+        return true if OPEN3.match?(receiver.to_s)
+        return true if ALWAYS_NAMES.include?(name)
+
+        tag = receiver ? "#{receiver}.#{name}" : name
+        return true if @tags.include?(tag)
+        # Kernel.system / Kernel.spawn / Process.spawn: the explicit-receiver
+        # spelling of a bare process spawn is the same hazard.
+        return true if KERNEL_RECEIVERS.include?(receiver) && @tags.include?(name)
+
+        piped_open?(node, name, receiver)
+      end
+
+      # Kernel#open with a "| command" argument spawns a process.
+      def piped_open?(node, name, receiver)
+        return false unless name == "open" && (receiver.nil? || receiver == "Kernel")
+
+        first = node.arguments&.arguments&.first
+        case first
+        when Prism::StringNode then first.unescaped.start_with?("|")
+        when Prism::InterpolatedStringNode
+          part = first.parts.first
+          part.is_a?(Prism::StringNode) && part.unescaped.start_with?("|")
+        else false
+        end
+      end
+
+      # A mutation is safe only while no hazardous call survives it: every
+      # edit must destroy every span (cover it wholly with a hazard-free
+      # replacement). Anything less - touching a call, or editing other
+      # code in a method that still holds a call - keeps the call running
+      # with altered inputs, so the mutant is suppressed.
+      def safe?(mutation, spans)
+        mutation.edits.all? { |edit| destroys_all?(edit, spans) }
+      end
+
+      def destroys_all?(edit, spans)
+        spans.all? do |start_byte, end_byte, _slice|
+          edit.start_byte <= start_byte && edit.end_byte >= end_byte
+        end && replacement_clean?(edit.replacement)
+      end
+
+      # The replacement itself, parsed as code. A replacement that parses
+      # and contains no hazardous call cannot run one; anything else -
+      # a hazard in the new text, or text that does not parse on its own -
+      # is treated as hazardous.
+      def replacement_clean?(replacement)
+        result = Prism.parse(replacement.to_s)
+        return false unless result.success?
+
+        hazard_spans(result.value).empty?
+      end
+    end
+  end
+end

data/lib/saboteur/mutation_source/operator_assignment.rb

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Saboteur
+  module MutationSource
+    # Changes the arithmetic operation, without changing the assignment target.
+    class OperatorAssignment < Base
+      REPLACEMENTS = { :+ => "-=", :- => "+=", :* => "/=", :/ => "*=" }.freeze
+      WRITE_NODES = [Prism::LocalVariableOperatorWriteNode, Prism::InstanceVariableOperatorWriteNode,
+                     Prism::ClassVariableOperatorWriteNode, Prism::GlobalVariableOperatorWriteNode,
+                     Prism::ConstantOperatorWriteNode, Prism::ConstantPathOperatorWriteNode,
+                     Prism::CallOperatorWriteNode, Prism::IndexOperatorWriteNode].freeze
+      SCOPE_NODES = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+
+      def initialize(arid: []) # rubocop:disable Lint/MissingSuper
+        @arid = arid.map { |pattern| Regexp.new(pattern) }
+      end
+
+      def name
+        "operator_assignment"
+      end
+
+      def mutations_for(subject)
+        found = []
+        visit(subject.node.body, subject, found)
+        found
+      end
+
+      private
+
+      def visit(node, subject, found)
+        return if node.nil? || SCOPE_NODES.any? { |scope| node.is_a?(scope) }
+        return if @arid.any? { |pattern| pattern.match?(node.slice) }
+
+        replace(node, subject, found) if WRITE_NODES.any? { |type| node.is_a?(type) }
+        node.compact_child_nodes.each { |child| visit(child, subject, found) }
+      end
+
+      def replace(node, subject, found)
+        replacement = REPLACEMENTS[node.binary_operator]
+        return unless replacement
+
+        location = node.binary_operator_loc
+        edit = Edit.new(file: subject.file, start_byte: location.start_offset,
+                        end_byte: location.end_offset, replacement: replacement)
+        found << Mutation.new(subject_id: subject.id, operator: name, edits: [edit], source: name)
+      end
+    end
+  end
+end

data/lib/saboteur/mutation_source/operator_registry.rb

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module MutationSource
+    # Public names used by selection, help and inline suppression validation.
+    module OperatorRegistry
+      DESCRIPTIONS = {
+        "operator_assignment" => "Swap arithmetic compound assignments",
+        "condition_negation" => "Negate if, unless and ternary predicates",
+        "range" => "Swap inclusive and exclusive bounded ranges",
+        "body_nil" => "Replace the method body with nil",
+        "body_true" => "Replace a predicate body with true",
+        "body_false" => "Replace a predicate body with false",
+        "body_raise" => "Replace the method body with raise",
+        "comparison" => "Change a comparison or replace its result",
+        "arithmetic" => "Swap an arithmetic operator",
+        "boolean_logic" => "Change a boolean connector",
+        "condition_true" => "Force a condition true",
+        "condition_false" => "Force a condition false",
+        "negation_removal" => "Remove a logical negation",
+        "literal_number" => "Change a numeric literal",
+        "or_assign" => "Replace ||= with assignment",
+        "safe_navigation" => "Replace safe navigation with a regular call",
+        "statement_removal" => "Replace a statement with nil",
+        "filter_replacement" => "Swap select and reject",
+        "literal_string" => "Empty a string literal",
+        "literal_boolean" => "Swap a boolean literal",
+        "argument_removal" => "Remove a call argument",
+        "pair_removal" => "Remove a hash pair",
+        "endpoint_replacement" => "Swap explicit no-argument first and last",
+        "chain_removal" => "Remove one call from a method chain"
+      }.freeze
+      EXTENDED = %w[range operator_assignment condition_negation].freeze
+      TIERS = { "core" => (DESCRIPTIONS.keys - EXTENDED).freeze, "extended" => EXTENDED,
+                "all" => DESCRIPTIONS.keys.freeze }.freeze
+
+      def self.list(out)
+        DESCRIPTIONS.each do |name, description|
+          out.puts("#{name}  #{EXTENDED.include?(name) ? 'extended' : 'core'}  #{description}")
+        end
+        nil
+      end
+
+      def self.resolve(names)
+        return TIERS.fetch("core") if names.empty?
+
+        unknown = names - DESCRIPTIONS.keys - TIERS.keys
+        unless unknown.empty?
+          raise ConfigError, "unknown operators: #{unknown.join(', ')}. Valid names: " \
+                             "#{(DESCRIPTIONS.keys + TIERS.keys).join(', ')}"
+        end
+        names.flat_map { |name| TIERS.fetch(name) { [name] } }.uniq
+      end
+    end
+  end
+end

data/lib/saboteur/mutation_source/range_replacement.rb

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Saboteur
+  module MutationSource
+    # Changes whether a range includes its upper endpoint.
+    class RangeReplacement < Base
+      SCOPE_NODES = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+
+      def initialize(arid: []) # rubocop:disable Lint/MissingSuper
+        @arid = arid.map { |pattern| Regexp.new(pattern) }
+      end
+
+      def name
+        "range"
+      end
+
+      def mutations_for(subject)
+        found = []
+        visit(subject.node.body, subject, found)
+        found
+      end
+
+      private
+
+      def visit(node, subject, found)
+        return if node.nil? || SCOPE_NODES.any? { |scope| node.is_a?(scope) }
+        return if @arid.any? { |pattern| pattern.match?(node.slice) }
+
+        if node.is_a?(Prism::RangeNode) && node.left && node.right
+          location = node.operator_loc
+          replacement = location.slice == ".." ? "..." : ".."
+          edit = Edit.new(file: subject.file, start_byte: location.start_offset,
+                          end_byte: location.end_offset, replacement: replacement)
+          found << Mutation.new(subject_id: subject.id, operator: name, edits: [edit], source: name)
+        end
+        node.compact_child_nodes.each { |child| visit(child, subject, found) }
+      end
+    end
+  end
+end

data/lib/saboteur/preview.rb

@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "engine"
+
+module Saboteur
+  # Source-only planning. Never boots the host or executes its test suite.
+  class Preview
+    def initialize(config, out:, err:)
+      @config = config
+      @out = out
+      @diagnostics = Engine::Diagnostics.new(err)
+    end
+
+    def call
+      selection = Engine::SubjectSelection.new(@config, @diagnostics)
+      subjects = selection.select(@config.included_files)
+      scope = selection.changed_lines && Engine::DiffScope.new(selection.changed_lines)
+      guard = MutationSource::HazardGuard.new(@config["hazard"]) unless @config["allow_hazardous"]
+      candidates = Engine::Candidates.new(Engine::Candidates.build_sources(@config), @diagnostics, hazard_guard: guard)
+      lists = subjects.map { |subject| planned(subject, candidates, scope) }
+      inline_suppressions
+      incomplete = @diagnostics.discovery_failures.size
+      @out.puts("Total: #{lists.sum(&:size)} mutants; #{@diagnostics.omissions.sum(&:count)} " \
+                "dropped by max_mutants_per_method#{incomplete_note(incomplete)}")
+      incomplete.zero? ? estimate(subjects, lists) : @out.puts("no estimate: source discovery was incomplete")
+      @diagnostics.warnings.each { |warning| @out.puts("warning: #{warning}") }
+      nil
+    end
+
+    private
+
+    # Candidate filtering precedes diff restriction and the per-method cap.
+    # Name that scope rather than implying these rows were executed or scored.
+    def inline_suppressions
+      entries = @diagnostics.inline_suppressions
+      return if entries.empty?
+
+      @out.puts("Inline suppressions: #{entries.size} candidates in selected methods " \
+                "(before diff restriction and per-method cap; outside the planned total)")
+      entries.each do |entry|
+        path = entry[:file].delete_prefix("#{@config.root}/")
+        @out.puts("  #{path}:#{entry[:line]} #{entry[:subject]} #{entry[:operator]} " \
+                  "#{entry[:digest]}: #{entry[:reason]}")
+      end
+    end
+
+    def incomplete_note(count)
+      return "" if count.zero?
+
+      " - INCOMPLETE: #{count} file(s) could not be parsed, so this total is not authoritative"
+    end
+
+    def estimate(subjects, lists)
+      map = cached_map
+      return @out.puts("no estimate: run once to build the coverage map") unless map
+
+      seconds = work_seconds(map, subjects, lists)
+      return @out.puts("no estimate: cached test durations are incomplete") unless seconds
+
+      @out.puts("Estimated baseline covering-test work: #{seconds.round(2)} s (cached original-test durations " \
+                "times planned mutants; not a bound on mutant runtime; excludes boot and forks)")
+    end
+
+    # Cached data is untrusted input: every duration must be a non-negative
+    # number, the total must stay finite (JSON text such as 1e999 parses to
+    # Infinity), and anything that fails while reading it, such as a string or
+    # null, is no estimate. Source generation has already finished, so this
+    # cannot hide its errors.
+    def work_seconds(map, subjects, lists)
+      return unless map.durations.values.all? { |seconds| seconds >= 0 }
+
+      total = subjects.zip(lists).sum do |subject, list|
+        # nil when a covering test has no recorded duration: the rescue below.
+        map.recorded_runtime(map.tests_for(subject)) * list.size
+      end
+      total if total.finite?
+    rescue StandardError
+      nil
+    end
+
+    # Any receipt that is not exactly a current, readable pointer to a
+    # coverage map means "no estimate", never an exception.
+    def cached_map
+      path = File.join(@config.path("cache_dir"), "preview.json")
+      receipt = JSON.parse(File.read(path))
+      return unless receipt["fingerprint"] == Engine::RunFingerprint.new(config: @config).snapshot.digest
+
+      Selection::CoverageMap.load(receipt["path"])
+    rescue StandardError
+      # An unreadable receipt or a map of the wrong shape (IndexError, TypeError, ...) is no estimate.
+      nil
+    end
+
+    def planned(subject, candidates, scope)
+      list = candidates.for(subject)
+      list = scope.restrict(subject, list) if scope
+      limit = @config["max_mutants_per_method"]
+      @diagnostics.record_omission(subject, count: list.size - limit, limit: limit) if list.size > limit
+      list = list.first(limit)
+      path = subject.file.delete_prefix("#{@config.root}/")
+      @out.puts("#{path}:#{subject.start_line} #{subject.id}  #{list.size} mutants")
+      list
+    end
+  end
+end

data/lib/saboteur/reporter/agent_commands.rb

@@ -40,12 +40,18 @@ module Saboteur
             command.bytesize <= MAX_BYTES ? command : nil
           end
 
+          # An explicit scope is frozen: --no-guess-tests keeps a config-file
+          # guess_tests from conflicting with the --test list.
+          def test_words(tests)
+            tests.empty? ? [] : ["--no-guess-tests", *tests.flat_map { |test| ["--test", test] }]
+          end
+
           def selection(provenance, replay: false)
             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) }
-            provenance.tests.each { |test| words.push("--test", test) }
+            words.push(*test_words(provenance.tests))
             SETTING_FLAGS.each do |key, flag|
               words.push(flag, provenance.settings[key].to_s) if provenance.settings.key?(key)
             end

data/lib/saboteur/reporter/agent_incomplete.rb

@@ -7,24 +7,47 @@ module Saboteur
       # What makes a verdict cover less than the whole selection. Each reason has a
       # stable code, a count and a plain meaning.
       module Incomplete
+        NO_COVERAGE = "no coverage"
+
         class << self
           def reasons(report)
             reasons = []
             add(reasons, "no_coverage", skipped_for_coverage(report), "subjects or mutants had no covering test")
+            load_only = report.counts[:ran_at_load] + report.skipped_subjects.values.count do |reason|
+              reason == Selection::CoverageMap::RAN_AT_LOAD
+            end
+            add(reasons, "unsupported", unsupported_subjects(report),
+                "subjects were skipped as unsupported (for example defined inside a block); no mutant was judged")
+            add(reasons, "ran_at_load", load_only, "code ran only at load; no mutant was judged")
+            add(reasons, "unreachable", report.counts[:unreachable], "tests did not call the replacement definition")
             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, "fail_fast", report.early_stop&.unreached&.size.to_i,
+                "selected subjects did not run because --fail-fast stopped the run")
+            inline_scope(reasons, report)
             reasons
           end
 
           private
 
+          def inline_scope(reasons, report)
+            add(reasons, "inline_suppressed", report.inline_suppressions.size,
+                "candidates were suppressed by inline directives; see the full report audit")
+          end
+
           def add(reasons, code, count, meaning)
             reasons << { reason: code, count: count, meaning: meaning } if count.positive?
           end
 
           def skipped_for_coverage(report)
-            report.skipped_subjects.size + report.counts[:skipped]
+            report.skipped_subjects.values.count(NO_COVERAGE) + report.counts[:skipped]
+          end
+
+          def unsupported_subjects(report)
+            report.skipped_subjects.values.count do |reason|
+              reason != NO_COVERAGE && reason != Selection::CoverageMap::RAN_AT_LOAD
+            end
           end
 
           def omitted_by_cap(report)

data/lib/saboteur/reporter/agent_summary.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require_relative "findings"
+require_relative "survivor_hints"
 require_relative "agent_incomplete"
 require_relative "agent_clipping"
 
@@ -26,7 +27,7 @@ module Saboteur
               scoreDefinition: "(killed + timeout) / (killed + survived + timeout); null when nothing was tested",
               incomplete: incomplete, timeoutCountedAsDetected: report.counts[:timeout],
               findings: findings(report, shown, snippet_limit),
-              warnings: warnings(report),
+              warnings: report.warnings.first(WARNING_LIMIT).map { |warning| warning.to_s[0, WARNING_LENGTH] },
               next: next_steps(report, provenance)
             }
           end
@@ -34,7 +35,7 @@ module Saboteur
           private
 
           def status_of(report, incomplete)
-            return "not_applicable" if report.results.empty? && report.skipped_subjects.empty?
+            return "not_applicable" if report.results.empty? && incomplete.empty?
 
             incomplete.empty? ? "complete" : "partial"
           end
@@ -87,7 +88,8 @@ module Saboteur
             {
               survivors: live, shown: shown_findings(all[:survivors], shown, snippet_limit),
               omitted: live - [shown, all[:survivors].size].min,
-              accepted: report.survivors.size - live, ordering: all[:ordering]
+              accepted: report.survivors.size - live, ordering: all[:ordering],
+              hintCaveat: SurvivorHints::CAVEAT
             }
           end
 
@@ -97,11 +99,15 @@ module Saboteur
                      .merge(path: clip_value(finding[:path], 200), subject: clip_value(finding[:subject], 200),
                             original: clip(finding[:original], snippet_limit),
                             replacement: clip(finding[:replacement], snippet_limit))
+                     .merge(finding_hints(finding))
             end
           end
 
-          def warnings(report)
-            report.warnings.first(WARNING_LIMIT).map { |warning| warning.to_s[0, WARNING_LENGTH] }
+          def finding_hints(finding)
+            structured = SurvivorHints.structured(operator: finding[:operator], original: finding[:original],
+                                                  replacement: finding[:replacement], coarse: finding[:coarse])
+            { hint: SurvivorHints.for(finding[:operator], coarse: finding[:coarse]) }.compact
+                                                                                     .merge(testHint: structured)
           end
 
           def next_steps(report, provenance)

data/lib/saboteur/reporter/findings.rb

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "survivor_ranking"
+
 module Saboteur
   module Reporter
     # Findings for a code-review surface such as the saboteur GitHub Action:
@@ -15,12 +17,7 @@ module Saboteur
       # GitHub shows at most 10 annotations of one kind per step.
       LIMIT = 10
 
-      # Published ordering, coarse survivors first: a surviving coarse mutant
-      # replaced the whole method body, which hints that no test pins the
-      # method's behavior - though it can also be a re-evaluation limit or an
-      # equivalent mutant, so this is a heuristic, not a guarantee. Ties break
-      # by file, line and digest, so one report always reads the same way.
-      ORDERING = "coarse survivors first, then file, line and digest"
+      ORDERING = SurvivorRanking::ORDERING
 
       class << self
         def build(report)
@@ -46,20 +43,8 @@ module Saboteur
           [results.size - LIMIT, 0].max
         end
 
-        # partition keeps the coarse group ahead; inside a group the key is
-        # total (no two mutants share a digest), so the order is stable.
         def ordered(report, results)
-          results.partition { |result| result.mutation.coarse }
-                 .map { |group| group.sort_by { |result| tie_break(report, result) } }
-                 .flatten
-        end
-
-        def tie_break(report, result)
-          [path(report, result), first_line(result), result.digest]
-        end
-
-        def first_line(result)
-          result.subject.line_of(result.mutation.edits.map(&:start_byte).min)
+          SurvivorRanking.ordered(report, results)
         end
 
         def finding(report, result)

data/lib/saboteur/reporter/history_paths.rb

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    # Refuses linked or non-regular history/report destinations before writes.
+    module HistoryPaths
+      module_function
+
+      def validate(paths)
+        paths = paths.compact.map { |path| File.expand_path(path) }
+        identities = paths.map do |path|
+          reject_links(path)
+          next unless File.exist?(path)
+
+          stat = File.stat(path)
+          raise Error, "score history/report destination must be a regular file" unless stat.file?
+
+          [stat.dev, stat.ino]
+        end.compact
+        raise Error, "score history/report destinations alias the same file" unless identities.uniq == identities
+      rescue SystemCallError => e
+        raise Error, "score history/report paths cannot be verified: #{e.message}"
+      end
+
+      def reject_links(path)
+        loop do
+          raise Error, "score history/report paths must not contain symlinks" if File.symlink?(path)
+
+          parent = File.dirname(path)
+          break if parent == path
+
+          path = parent
+        end
+      end
+    end
+  end
+end