saboteur 0.4.0 → 0.6.0

data/lib/saboteur/mutation_source/chain_removal.rb

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "base"
+
+module Saboteur
+  module MutationSource
+    # Drops one link from the middle of a method chain: a.b.c becomes a.c.
+    # The first receiver and the last call stay, so the result is still a call
+    # on the original object.
+    class ChainRemoval < Base
+      BOUNDARIES = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+      # Links this operator leaves alone by design. They hand back their receiver or a
+      # copy of it (tap after running a block), so dropping one changes mutability,
+      # copying or a block's side effects. Tests can observe those, but they are other
+      # contracts than "a step in the query chain went missing", and removing them
+      # mostly yields noise, so they are out of scope here.
+      IDENTITY_CALLS = %w[freeze dup clone itself tap].freeze
+
+      # Targets of a write: `a.b.c = 1`, `a.b.c += 1`, `a.b[0] ||= 1`. The whole receiver chain
+      # is the thing being assigned to, so no link of it is dropped.
+      WRITE_NODES = [Prism::CallOperatorWriteNode, Prism::CallOrWriteNode, Prism::CallAndWriteNode,
+                     Prism::IndexOperatorWriteNode, Prism::IndexOrWriteNode, Prism::IndexAndWriteNode].freeze
+
+      def initialize(arid: []) # rubocop:disable Lint/MissingSuper
+        @arid = arid.map { |pattern| Regexp.new(pattern) }
+      end
+
+      def name
+        "chain_removal"
+      end
+
+      def mutations_for(subject)
+        found = []
+        visit(subject.node.body, subject, found)
+        found
+      end
+
+      private
+
+      def visit(node, subject, found)
+        return if node.nil? || BOUNDARIES.any? { |type| node.is_a?(type) }
+
+        if node.is_a?(Prism::StatementsNode)
+          node.body.each { |child| visit(child, subject, found) unless @arid.any? { |p| p.match?(child.slice) } }
+          return
+        end
+        remove_link(node, subject, found) if node.is_a?(Prism::CallNode)
+        children(node).each { |child| visit(child, subject, found) }
+      end
+
+      # Everything under the node except the receiver chain of a write target.
+      def children(node)
+        return node.compact_child_nodes unless write_target?(node)
+
+        node.compact_child_nodes.reject { |child| child.equal?(node.receiver) }
+      end
+
+      def write_target?(node)
+        WRITE_NODES.any? { |type| node.is_a?(type) } || (node.is_a?(Prism::CallNode) && node.attribute_write?)
+      end
+
+      def remove_link(call, subject, found)
+        link = call.receiver
+        return unless call.call_operator_loc && !call.attribute_write? && removable?(link)
+
+        edit = Edit.new(file: subject.file, start_byte: link.receiver.end_offset,
+                        end_byte: link.end_offset, replacement: "")
+        found << Mutation.new(subject_id: subject.id, operator: name, edits: [edit], source: name)
+      end
+
+      # A dotted call with a method name (a dot always has a receiver).
+      def removable?(link)
+        link.is_a?(Prism::CallNode) && link.call_operator_loc && link.message_loc &&
+          !IDENTITY_CALLS.include?(link.name.to_s)
+      end
+    end
+  end
+end

data/lib/saboteur/mutation_source/condition_negation.rb

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Saboteur
+  module MutationSource
+    # Negates the predicate, retaining its evaluation and branch structure.
+    class ConditionNegation < 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
+        "condition_negation"
+      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) }
+
+        negate(node.predicate, subject, found) if node.is_a?(Prism::IfNode) || node.is_a?(Prism::UnlessNode)
+        node.compact_child_nodes.each { |child| visit(child, subject, found) }
+      end
+
+      def negate(predicate, subject, found)
+        # Existing true/false and negation-removal operators own these cases.
+        if predicate.is_a?(Prism::TrueNode) || predicate.is_a?(Prism::FalseNode) || predicate.is_a?(Prism::NilNode)
+          return
+        end
+        return if predicate.is_a?(Prism::CallNode) && predicate.name == :!
+
+        location = predicate.location
+        edit = Edit.new(file: subject.file, start_byte: location.start_offset,
+                        end_byte: location.end_offset, replacement: "!(#{predicate.slice})")
+        found << Mutation.new(subject_id: subject.id, operator: name, edits: [edit], source: name)
+      end
+    end
+  end
+end

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_examples.rb

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module MutationSource
+    module OperatorExamples
+      EXAMPLES = {
+        "body_nil" => "def value = 1 -> def value = nil",
+        "body_true" => "def ok? = false -> def ok? = true",
+        "body_false" => "def ok? = true -> def ok? = false",
+        "body_raise" => "def value = 1 -> def value; raise; end",
+        "comparison" => "a < b -> a <= b",
+        "arithmetic" => "a + b -> a - b",
+        "boolean_logic" => "a && b -> a",
+        "condition_true" => "if x -> if true",
+        "condition_false" => "if x -> if false",
+        "negation_removal" => "!x -> x",
+        "literal_number" => "1 -> 0",
+        "or_assign" => "x ||= 1 -> x = 1",
+        "safe_navigation" => "x&.name -> x.name",
+        "statement_removal" => "check; value -> nil; value",
+        "filter_replacement" => "xs.select { |x| x } -> xs.reject { |x| x }",
+        "literal_string" => "\"hello\" -> \"\"",
+        "literal_boolean" => "true -> false",
+        "argument_removal" => "send(a, b) -> send(a)",
+        "pair_removal" => "{a: 1, b: 2} -> {b: 2}",
+        "endpoint_replacement" => "xs.first -> xs.last",
+        "chain_removal" => "x.first.to_s -> x.to_s",
+        "range" => "1..3 -> 1...3",
+        "operator_assignment" => "x += 1 -> x -= 1",
+        "condition_negation" => "x ? a : b -> !(x) ? a : b"
+      }.freeze
+    end
+  end
+end

data/lib/saboteur/mutation_source/operator_registry.rb

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "did_you_mean"
+require_relative "operator_examples"
+
+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
+      POLICY_VERSION = 2
+      TIERS = { "all" => DESCRIPTIONS.keys.freeze }.freeze
+
+      def self.list(out, names: [], excluded: [])
+        active = select(names, excluded)
+        DESCRIPTIONS.each do |name, description|
+          out.puts("#{name}  #{active.include?(name) ? 'on' : 'off'}  #{description}  #{OperatorExamples::EXAMPLES.fetch(name)}")
+        end
+        nil
+      end
+
+      def self.policy(names, excluded)
+        { "version" => POLICY_VERSION, "selected" => names, "excluded" => excluded,
+          "effective" => select(names, excluded) }
+      end
+
+      # Exclusion wins over explicit selection; empty exclusions remove nothing.
+      def self.select(names, excluded)
+        selected = resolve(names)
+        excluded.empty? ? selected : selected - resolve(excluded)
+      end
+
+      def self.suggestion(name)
+        matches = DidYouMean::SpellChecker.new(dictionary: DESCRIPTIONS.keys).correct(name)
+        matches.empty? ? "" : "Did you mean #{matches.first}?"
+      end
+
+      def self.resolve(names)
+        return TIERS.fetch("all") if names.empty?
+
+        legacy = names & %w[core extended]
+        unless legacy.empty?
+          raise ConfigError, "operator tiers #{legacy.join(', ')} were removed: use concrete names or all; " \
+                             "for the old core set exclude range,operator_assignment,condition_negation"
+        end
+        unknown = names - DESCRIPTIONS.keys - TIERS.keys
+        unless unknown.empty?
+          raise ConfigError, "unknown operators: #{unknown.join(', ')}. Valid names: " \
+                             "#{(DESCRIPTIONS.keys + TIERS.keys).join(', ')}. " \
+                             "#{suggestion(unknown.first)} See --list-operators."
+        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,115 @@
+# 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
+      announce_operators
+      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")
+      print_warnings
+      nil
+    end
+
+    private
+
+    def print_warnings
+      @diagnostics.warnings.each { |warning| @out.puts("warning: #{warning}") }
+    end
+
+    def announce_operators
+      @out.puts("Operators: #{@config.operator_policy['effective'].join(', ')}")
+    end
+
+    # 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