saboteur 0.8.1 → 0.9.0

data/lib/saboteur/engine/coverage_store.rb

@@ -11,13 +11,29 @@ module Saboteur
     # unchanged, otherwise built by running the whole suite once in a
     # supervised child and saved.
     class CoverageStore
-      CACHE_INPUTS = %w[integration require rspec_args rails tests].freeze
+      include CoverageShadow
+      include CoveragePartial
+      include CoverageParts
+
+      CACHE_INPUTS = %w[integration require rspec_args rails tests coverage_recorder].freeze
       LOCKFILES = %w[Gemfile.lock gems.locked].freeze
       LOG = "coverage-build.log"
+      # RSpec rewrites this on every run (example_status_persistence_file_path),
+      # so hashing it would make every second run look edited.
+      GENERATED_OUTPUT = "spec/examples.txt"
+      # A snapshot entry that is never a file, so a snapshot holding it is never
+      # reused partially. It stands for a test file outside the project root,
+      # whose own inputs the snapshot cannot see.
+      OUTSIDE_TESTS = "(test file outside the project root)"
+      # What a failed child's log shows in the error: its last lines, bounded.
+      TAIL_LINES = 60
+      TAIL_BYTES = 65_536
+      TAIL_LINE_WIDTH = 300
 
       def initialize(config:, integration:, hooks:, supervisor:, diagnostics:, load_lines: {}, load_methods: {},
-                     timeout_cap: nil)
+                     timeout_cap: nil, parts: 1)
         @config = config
+        @parts = parts
         @integration = integration
         @hooks = hooks
         @supervisor = supervisor
@@ -44,8 +60,14 @@ module Saboteur
         cached = cached_map(files)
         return refuse_empty_map(cached.with_preloaded(preloaded), files, preloaded) if cached
 
-        map = refuse_empty_map(build(files).with_preloaded(preloaded), files, preloaded)
+        note = miss_note(files)
+        @diagnostics.inform(note.message(scoped: !@config["tests"].empty?)) if @config["cache"]
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        map = fresh_map(files, note, preloaded)
+        build_seconds = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
         map.save(path)
+        shadow(files, map, note, build_seconds) if shadow?
+        note.save
         File.write(File.join(@config.path("cache_dir"), "preview.json"),
                    JSON.generate(path: path, fingerprint: RunFingerprint.new(config: @config).snapshot.digest))
         map
@@ -53,6 +75,12 @@ module Saboteur
 
       private
 
+      # The partial map when it is on and safe, else the full build.
+      def fresh_map(files, note, preloaded)
+        (partial_map(files, note, preloaded) if partial_use?) ||
+          refuse_empty_map(build(files).with_preloaded(preloaded), files, preloaded)
+      end
+
       def write_map(writer, recorder, build_seconds)
         writer.write(recorder.result(build_seconds: build_seconds, loaded_files: loaded_project_files).to_json)
         writer.close
@@ -79,9 +107,63 @@ module Saboteur
       end
 
       def cache_key(files)
-        inputs = JSON.generate(CACHE_INPUTS.to_h { |key| [key, @config[key]] })
-        all = files + @integration.test_files + SuiteFiles.new(@config).files + lockfiles
-        Selection::CoverageMap.cache_key(files: all.uniq, extra: inputs)
+        Selection::CoverageMap.cache_key(files: key_files(files), extra: key_inputs)
+      end
+
+      def key_inputs
+        JSON.generate(CACHE_INPUTS.to_h { |key| [key, @config[key]] })
+      end
+
+      def recorder_class
+        @config["coverage_recorder"] == "trace" ? Selection::TraceRecorder : Selection::Recorder
+      end
+
+      def key_files(files)
+        (files + @integration.test_files + SuiteFiles.new(@config).files + lockfiles).uniq
+      end
+
+      def miss_note(files)
+        CoverageMissNote.new(cache_dir: @config.path("cache_dir"), root: @root, files: snapshot_files(files),
+                             settings: key_inputs, map_key: cache_key(files), seed: @config["seed"],
+                             clean: ->(path) { plain_line(Text.utf8(path.to_s)) })
+      end
+
+      # What the inputs snapshot hashes: the cache key's files plus every file
+      # under spec/ and under the suite's own test directories, fixtures and
+      # config included, except the generated spec/examples.txt. A partial
+      # rebuild (#46) must see a change to anything a test can read, not only
+      # to what the key covers. Symlinks and other special entries are listed
+      # but never read (see CoverageInputsSnapshot.file_digest). The cache dir
+      # is left out so the pair never hashes itself.
+      def snapshot_files(files)
+        cache = File.join(File.expand_path(@config.path("cache_dir")), "")
+        dirs, outside = test_dirs
+        tree = dirs.flat_map do |dir|
+          Dir.glob("**/*", File::FNM_DOTMATCH, base: File.join(@root, dir)).map { |name| File.join(@root, dir, name) }
+        end
+        generated = File.join(@root, GENERATED_OUTPUT)
+        tree = tree.reject do |file|
+          file == generated || real_directory?(file) || File.expand_path(file).start_with?(cache)
+        end
+        marker = outside ? [OUTSIDE_TESTS] : []
+        [key_files(files), tree, marker].flatten.sort
+      end
+
+      # spec/ always, plus the first directory of every configured test file
+      # (a suite under test/ or elsewhere keeps its fixtures beside it), and
+      # whether a test file lies outside the project root. Both sides are
+      # compared as real paths, so a symlinked root still matches.
+      def test_dirs
+        prefix = "#{Selection::CoverageMap.canonical(@root)}/"
+        inside, outside = @integration.test_files.map { |file| Selection::CoverageMap.canonical(file) }
+                                      .partition { |file| file.start_with?(prefix) }
+        [["spec"] + inside.map { |file| file.delete_prefix(prefix).split("/").first }, !outside.empty?]
+      end
+
+      def real_directory?(file)
+        File.lstat(file).directory?
+      rescue SystemCallError
+        true
       end
 
       def lockfiles
@@ -100,6 +182,9 @@ module Saboteur
                        "Run through the saboteur executable and disable SimpleCov for the run."
         end
 
+        parts = usage_checked { suite_parts }
+        return build_parts(files, parts) if parts.size > 1
+
         scope = @config["tests"].empty? ? "the whole suite" : "the selected specs"
         @diagnostics.inform("building coverage map (runs #{scope} once)")
         # The suite child forked next inherits this heap; pack it first, to
@@ -114,13 +199,136 @@ module Saboteur
         map_from(result, admitted)
       end
 
-      def map_from(result, admitted = @config["coverage_timeout"])
+      # The spec files dealt into @parts disjoint parts; one part (the
+      # default, or a suite with fewer files than parts) keeps the single
+      # child build (#741).
+      def suite_parts
+        return [] unless @parts > 1
+
+        Engine::SuitePartition.parts(@integration.test_files, @parts)
+      end
+
+      # The same suite pass as build, run as several children at once, each
+      # over its own spec files. Fails loudly unless the parts hold exactly
+      # the suite's examples before the run and the combined map holds
+      # exactly its tests after it, and refuses a part that recorded no test.
+      def build_parts(files, parts)
+        total, counts = usage_checked { check_parts_cover_suite(parts) }
+        saved = saved_parts(files, parts.size, counts)
+        todo = saved.each_index.select { |index| saved[index].nil? }
+        @diagnostics.inform(parts_note(parts.size, todo.size))
+        built = todo.empty? ? [] : run_parts(files, parts, todo)
+        todo.zip(built) { |index, map| saved[index] = map }
+        map = combine_saved(saved, total, files, parts.size)
+        forget_parts(files, parts.size)
+        map
+      end
+
+      # Parts that cannot be combined are dropped, not kept: a bad saved
+      # part would otherwise fail every later run the same way.
+      def combine_saved(maps, total, files, count)
+        combine_parts(maps, total)
+      rescue ArgumentError => e
+        forget_parts(files, count)
+        raise Error, "the saved coverage parts do not combine (#{e.message}); they were removed, run again"
+      end
+
+      def parts_note(count, missing)
+        return "building coverage map (reusing all #{count} saved parts)" if missing.zero?
+
+        reused = count - missing
+        suffix = reused.zero? ? "" : ", reusing #{reused} saved"
+        "building coverage map (runs the suite once, in #{count} parallel parts#{suffix})"
+      end
+
+      # Runs only the parts in todo, as several children at once.
+      def run_parts(files, parts, todo)
+        Execution::ForkReadiness.prepare_heap
+        heartbeat = @diagnostics.progress_heartbeat("building coverage map")
+        admitted = build_timeout
+        results = @supervisor.run_many(todo.size, timeout: admitted, on_tick: heartbeat.method(:tick),
+                                                  label: "coverage child died during the map build") do |writer, slot|
+          index = todo[slot]
+          own_test_env(index)
+          record(writer, files, only: parts[index], log: part_log_path(index))
+        end
+        part_maps(results, admitted, parts.size, files, todo)
+      end
+
+      # Every part that failed is reported, each with its own output, so one
+      # run shows all the failures instead of the first. A budget stop still
+      # raises at once: it says nothing about the suite. A part that did
+      # finish is saved either way, so the work is not lost (#427).
+      def part_maps(results, admitted, count, files, todo)
+        failures = []
+        budget_stop = nil
+        maps = results.each_with_index.map do |result, slot|
+          index = todo[slot]
+          map_from(result, admitted, log: part_log_path(index)).tap { |map| save_part(map, files, index, count) }
+        rescue BudgetPhaseTimeout => e
+          budget_stop = e
+          nil
+        rescue Error => e
+          failures << "part #{index + 1} of #{count}: #{e.message}"
+          nil
+        end
+        raise budget_stop if budget_stop
+        raise Error, failures.join("\n") unless failures.empty?
+
+        maps.each_with_index { |map, slot| part_map(map, todo[slot], count) }
+      end
+
+      # A part child gets its own TEST_ENV_NUMBER, as a WorkerPool worker
+      # does, so suites that key databases, ports or tmp dirs on it do not
+      # collide between parts (part 0 keeps the empty value).
+      def own_test_env(index)
+        ENV["TEST_ENV_NUMBER"] = index.zero? ? "" : (index + 1).to_s
+      end
+
+      # A bad file list is the caller's mistake: a usage error, not a crash.
+      def usage_checked
+        yield
+      rescue ArgumentError => e
+        raise ConfigError, e.message
+      end
+
+      def check_parts_cover_suite(parts)
+        total = @integration.example_count
+        counts = parts.map { |part| @integration.example_count(files: part) }
+        return [total, counts] if counts.sum == total
+
+        raise Error, "the coverage parts hold #{counts.sum} examples but the suite has #{total}; " \
+                     "refusing to build a map from a partition that does not cover the suite"
+      end
+
+      def part_map(map, index, total)
+        return map unless map.tests.empty?
+
+        raise Error, "coverage part #{index + 1} of #{total} recorded no tests; refusing to build a partial map"
+      end
+
+      def combine_parts(maps, total)
+        map = Selection::CoverageMap.combine(maps)
+        return map if map.tests.size == total
+
+        raise Error, "the combined coverage map holds #{map.tests.size} tests but the suite has #{total}; " \
+                     "refusing to use a partial map"
+      end
+
+      def part_log_path(index)
+        File.join(@config.path("cache_dir"), "coverage-build-#{index + 1}.log")
+      end
+
+      def map_from(result, admitted = @config["coverage_timeout"], log: log_path)
         raise_budget_stop(admitted) if budget_stopped?(result, admitted)
         raise Error, "coverage map build stopped: #{result.detail}" if result.stopped_by
-        raise Error, "coverage map build failed: #{died(result.exit_status)}" if result.payload.empty?
+        if result.payload.empty?
+          raise Error,
+                "coverage map build failed: #{died(result.exit_status, log)}#{output_tail(log)}"
+        end
 
         data = JSON.parse(result.payload)
-        raise Error, "coverage map build failed: #{data['error']}" if data["error"]
+        raise Error, "coverage map build failed: #{child_error(data['error'])}#{output_tail(log)}" if data["error"]
 
         with_parent_load_lines(Selection::CoverageMap.from_json(result.payload))
       end
@@ -177,15 +385,15 @@ module Saboteur
                        "build. No test in the suite may exercise these files, or the setup hid the app " \
                        "from Coverage#{bootsnap_note}. Run `saboteur doctor`."
         end
-        @diagnostics.warn("Coverage recorded nothing in #{files.size} included files; " \
+        @diagnostics.warn("name the specs that exercise them in --test, or drop --test to run the whole suite\n  " \
+                          "Coverage recorded nothing in #{files.size} included files; " \
                           "the selected specs may not exercise them.")
         map
       end
 
       def preloaded_message(files)
-        names = files.first(5).map { |file| file.delete_prefix("#{@root}/") }
-        more = files.size > 5 ? ", ..." : ""
-        "#{names.join(', ')}#{more} loaded before saboteur started coverage (a require ran before the " \
+        names = Text.name_list(files.map { |file| file.delete_prefix("#{@root}/") })
+        "#{names} loaded before saboteur started coverage (a require ran before the " \
           "executable's Coverage.start - commonly the gemspec requiring the library while bundler/setup " \
           "evaluates it, or RUBYOPT -r), so no test can ever cover #{files.size > 1 ? 'them' : 'it'}. " \
           "Let the test suite load these " \
@@ -198,11 +406,56 @@ module Saboteur
         " (Bootsnap's compile cache is the default Rails case)" if defined?(::Bootsnap)
       end
 
-      def died(status)
+      def died(status, log)
         how = if status&.signaled? then "was killed by signal #{Signal.signame(status.termsig)}"
               else "exited with status #{status&.exitstatus}"
               end
-        "the suite #{how} before reporting; its output is in #{log_path.delete_prefix("#{@root}/")}"
+        "the suite #{how} before reporting; its output is in #{log.delete_prefix("#{@root}/")}"
+      end
+
+      # The end of a failed child's log, where rspec prints its failures, so a
+      # CI run shows why without the cache directory. The suite's own output
+      # and nothing else. Every line is cleaned by plain_line and starts with
+      # "| ", so it is never the start of a workflow command.
+      def output_tail(log)
+        size = File.size(log)
+        cut = size > TAIL_BYTES
+        text = File.open(log) do |file|
+          file.seek(size - TAIL_BYTES) if cut
+          file.read
+        end
+        lines = Text.utf8(text).lines
+        lines.shift if cut
+        lines = lines.last(TAIL_LINES).map { |line| tail_line(line) }
+        return "" if lines.empty?
+
+        "\n  the last #{lines.size} lines of #{log.delete_prefix("#{@root}/")}:\n#{lines.join("\n")}"
+      rescue SystemCallError
+        ""
+      end
+
+      def tail_line(line)
+        "| #{plain_line(line)}"
+      end
+
+      # One line of a child's text, safe to print: colors stripped, control
+      # characters escaped, cut to a readable width, and the two things
+      # GitHub Actions reads as a workflow command broken where they stand: a
+      # "::" that starts the line after any leading whitespace (the runner
+      # trims all Unicode spaces first) and a "##[" anywhere in it. Other
+      # colons and brackets, as in "Saboteur::Error", are left alone.
+      def plain_line(line)
+        text = Text.display_safe(line.chomp.gsub(/\e\[[0-9;]*[A-Za-z]/, ""))
+        text.size > TAIL_LINE_WIDTH ? "#{text[0, TAIL_LINE_WIDTH]}..." : text
+      end
+
+      # The error a child wrote into its report. It is the child's text, which
+      # can carry anything the suite printed or raised, so it gets the log's
+      # treatment: the first line follows the message, every later line starts
+      # with "| ", and plain_line has cleaned them all.
+      def child_error(error)
+        first, *rest = Text.utf8(error.to_s).lines
+        [plain_line(first.to_s), *rest.first(TAIL_LINES).map { |line| tail_line(line) }].join("\n")
       end
 
       def log_path
@@ -211,9 +464,9 @@ module Saboteur
 
       # Runs in the supervised child. The suite's output goes to a log, so a
       # child that dies without reporting can still be diagnosed.
-      def record(writer, files)
-        FileUtils.mkdir_p(File.dirname(log_path))
-        $stdout.reopen(log_path, "w")
+      def record(writer, files, only: nil, log: log_path, seed: @config["seed"])
+        FileUtils.mkdir_p(File.dirname(log))
+        $stdout.reopen(log, "w")
         $stdout.sync = true
         $stderr.reopen($stdout)
         @hooks.run(:after_fork)
@@ -221,13 +474,13 @@ module Saboteur
         # The suite's own files are recorded too: a spec can read a
         # constant directly, and without its line hits no test maps to the
         # read (#319).
-        recorder = Selection::Recorder.new(files + @integration.test_files)
+        recorder = recorder_class.new(files + @integration.test_files)
         recorder.start
-        Kernel.srand(@config["seed"])
-        passed = @integration.run_all(recorder)
+        Kernel.srand(seed)
+        passed = only ? @integration.run_all(recorder, files: only, seed: seed) : @integration.run_all(recorder)
         if passed == false
           raise Error, "the unchanged suite failed while building coverage. Fix the suite, then run again " \
-                       "with seed #{@config['seed']}."
+                       "with seed #{seed}."
         end
         write_map(writer, recorder, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
       rescue Exception => e # rubocop:disable Lint/RescueException

data/lib/saboteur/engine/diagnostics.rb

@@ -73,7 +73,7 @@ module Saboteur
       Omission = Data.define(:subject, :count, :limit)
       DiscoveryFailure = Data.define(:file, :reason)
 
-      attr_reader :warnings, :invalid_mutations, :generation_events, :omissions, :discovery_failures,
+      attr_reader :warnings, :live_announced, :invalid_mutations, :generation_events, :omissions, :discovery_failures,
                   :hazard_suppressions, :inline_suppressions, :verbose
 
       def initialize(err, verbose: false)
@@ -82,6 +82,7 @@ module Saboteur
         @warnings = []
         @invalid_mutations = 0
         @generation_events = []
+        @live_announced = []
         @omissions = []
         @discovery_failures = []
         @hazard_suppressions = 0
@@ -90,8 +91,19 @@ module Saboteur
         @erb_template_note_emitted = false
       end
 
+      # Every warning passes through here once: repository-controlled text
+      # (file names, patterns, thread names, error text) cannot start a CI
+      # workflow command on a line of its own, whichever site built it
+      # (#834). Already escaped text is unchanged.
       def warn(message)
-        @warnings << message
+        @warnings << Text.display_safe_lines(message)
+      end
+
+      # Warnings built elsewhere (the ignore file's, the custom map's, a
+      # child's): each goes through #warn, so none skips the escaping.
+      def add_warnings(messages)
+        messages.each { |message| warn(message) }
+        nil
       end
 
       # ERB generator templates (Rails generators carry `.rb` files with ERB
@@ -148,7 +160,7 @@ module Saboteur
       end
 
       def inform(message)
-        @err.puts("saboteur: #{message}")
+        @err.puts("saboteur: #{Text.display_safe_lines(message)}")
       end
 
       # --verbose: one line per finished subject with its result marks, so a
@@ -162,10 +174,15 @@ module Saboteur
         inform("#{subject.id}  #{marks}")
       end
 
-      # A message that is both a report warning and a stderr note.
+      # A message that is both a report warning and a stderr note. The
+      # terminal does not reprint it at the end of the run (#605), but it
+      # stays in report.warnings: JSON, HTML and agent consumers discard
+      # stderr and must still see it.
       def announce(message)
-        warn(message)
-        inform(message)
+        safe = Text.display_safe_lines(message)
+        warn(safe)
+        inform(safe)
+        @live_announced << safe
       end
 
       # A heartbeat for a long phase: the supervisor's wait loop calls tick

data/lib/saboteur/engine/distribution.rb

@@ -192,11 +192,11 @@ module Saboteur
 
       def rebuild(row, subject, list)
         if row["error"]
-          @diagnostics.warn("#{subject.id}: #{row['error']}")
+          @diagnostics.warn("#{subject.id}: its mutants are reported as errors\n  #{row['error']}")
           return failed(row["error"], subject, list)
         end
 
-        @diagnostics.warnings.concat(row["warnings"])
+        @diagnostics.add_warnings(row["warnings"])
         decode(row, subject, list).each { |result| @cache&.record(result) unless result.reused? }
       end
 

data/lib/saboteur/engine/gated_run.rb

@@ -18,6 +18,7 @@ module Saboteur
       def report_unmapped(guess)
         @diagnostics.inform(guess.subjectless_message(since: config["since"])) if guess.subjectless.any?
         inform_skipped_specs(guess)
+        @diagnostics.announce(guess.referenced_message) if guess.referenced.any?
         stop_or_warn_unmapped(guess)
       end
 

data/lib/saboteur/engine/load_coverage.rb

@@ -19,16 +19,36 @@ module Saboteur
         return [{}, {}] unless Coverage.state == :suspended
 
         wanted = files.to_set { |file| Selection::CoverageMap.canonical(file) }
+        calls = boot_calls(wanted)
         CoverageReads.result(stop: false, clear: false)
                      .each_with_object([{}, {}]) do |(path, data), (lines_h, methods_h)|
           file = Selection::CoverageMap.canonical(path)
           next unless wanted.include?(file)
 
-          lines = data[:lines].each_with_index.filter_map { |count, index| index + 1 if count&.positive? }
-          lines -= uncalled_shared_lines(data)
+          called = calls.fetch(file, Set.new)
+          lines = ran_lines(file, data, called)
           lines_h[file] = lines unless lines.empty?
-          defs = data.fetch(:methods, {}).filter_map { |(_owner, _name, first, *), count| first if count.positive? }
-          methods_h[file] = defs.uniq.sort unless defs.empty?
+          defs = called.map(&:first).uniq.sort
+          methods_h[file] = defs unless defs.empty?
+        end
+      end
+
+      def self.ran_lines(file, data, called)
+        lines = data[:lines].each_with_index.filter_map { |count, index| index + 1 if count&.positive? }
+        lines - uncalled_shared_lines(file, called)
+      end
+
+      # The def calls the executable's tracer saw while the app loaded,
+      # file => Set of [line, name]. Coverage's methods report is off (its
+      # per-read cost is what made the coverage map slow, #655).
+      def self.boot_calls(wanted)
+        tracer = MethodCalls.booted
+        return {} unless tracer
+
+        tracer.disable
+        tracer.drain.each_with_object({}) do |(path, hits), by_file|
+          file = Selection::CoverageMap.canonical(path)
+          (by_file[file] ||= Set.new).merge(hits) if wanted.include?(file)
         end
       end
 
@@ -53,10 +73,36 @@ module Saboteur
       # A one-line or endless definition executes its def line even when its
       # body is never called. If any sibling on that physical line is uncalled,
       # discard its ambiguous line evidence rather than crediting every body.
-      def self.uncalled_shared_lines(data)
-        shared = data.fetch(:methods, {}).select { |(_owner, _name, first, _column, last, *), _| first == last }
-        calls = shared.group_by { |(_owner, _name, first, *), _count| first }
-        calls.filter_map { |line, entries| line if entries.any? { |_key, count| count.zero? } }
+      def self.uncalled_shared_lines(file, called)
+        defs = one_line_defs(file)
+        defs.group_by(&:first).filter_map do |line, entries|
+          line if entries.any? { |entry| !called.include?(entry) }
+        end
+      end
+
+      DEFINERS = %i[define_method define_singleton_method].freeze
+
+      # [line, name] for every def, or define_method with a block, that starts
+      # and ends on one physical line. Coverage's methods report lists both.
+      def self.one_line_defs(file)
+        found = []
+        walk = lambda do |node|
+          name = definition_name(node)
+          found << [node.location.start_line, name] if name && node.location.start_line == node.location.end_line
+          node.compact_child_nodes.each(&walk)
+        end
+        walk.call(Prism.parse_file(file).value)
+        found
+      rescue SystemCallError
+        []
+      end
+
+      def self.definition_name(node)
+        return node.name if node.is_a?(Prism::DefNode)
+        return unless node.is_a?(Prism::CallNode) && DEFINERS.include?(node.name) && node.block.is_a?(Prism::BlockNode)
+
+        first = Array(node.arguments&.arguments).first
+        first.unescaped.to_sym if first.is_a?(Prism::SymbolNode)
       end
     end
   end

data/lib/saboteur/engine/partial_invalidation.rb

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # Which spec files a partial coverage rebuild would have to rerun, or
+    # :full when the whole map must be rebuilt (#46, step 2). Pure: it reads
+    # two inputs snapshots and a coverage map and touches nothing else.
+    #
+    # An allowlist, not a blocklist. Coverage never records a test reading a
+    # fixture, a YAML file, an ENV value or a template, so no changed file
+    # can be proven harmless by absence. Only two kinds of change may take
+    # the partial path: a spec file of the suite, and an included source
+    # file with recorded coverage evidence that did not run while the app
+    # loaded. Every other change, and every added or removed file, is :full,
+    # as is a change of root, settings, runtime or snapshot format.
+    #
+    # The stale files come back in the order the map's full run used, so a
+    # rerun keeps the relative order that run had.
+    class PartialInvalidation
+      FULL = :full
+      # Placeholder, to be fitted from measurements; not configuration.
+      THRESHOLD = 0.5
+      SAME = %w[format root runtime settings].freeze
+
+      # included: relative paths of the included source files.
+      # spec_files: relative paths of the suite's spec files.
+      # status_file: whether RSpec picks examples from its generated status
+      # file (--only-failures, --next-failure), which no snapshot covers.
+      # RSpec ids name their file: "./spec/a_spec.rb[1:2]" is spec/a_spec.rb.
+      def self.spec_of(id)
+        id.split("[").first.delete_prefix("./")
+      end
+
+      def initialize(map:, root:, included:, spec_files:, status_file: false)
+        @status_file = status_file
+        @map = map
+        @root = Selection::CoverageMap.canonical(root)
+        @included = included
+        @spec_files = spec_files
+      end
+
+      def stale_specs(base, current)
+        return FULL if @status_file
+        return FULL unless SAME.all? { |key| base[key] == current[key] }
+
+        changed = changed_files([base, current].map { |snapshot| snapshot["files"] })
+        return FULL unless changed
+
+        stale = changed.each_with_object([]) do |file, specs|
+          found = specs_for(file)
+          return FULL unless found
+
+          specs.concat(found)
+        end
+        ordered(stale.uniq).then { |specs| heavy?(specs) ? FULL : specs }
+      end
+
+      # The part of the recorded spec time these files hold, 0 when none was recorded.
+      def share(specs)
+        total = weights.values.sum
+        total.zero? ? 0.0 : specs.sum { |file| weights.fetch(file, 0) }.fdiv(total)
+      end
+
+      private
+
+      # nil when a file was added, removed or unreadable on either side.
+      def changed_files(snapshots)
+        before, after = snapshots
+        return nil unless before.keys.sort == after.keys.sort
+        return nil if (before.values + after.values).include?(false)
+
+        before.keys.reject { |file| before[file] == after[file] }
+      end
+
+      def specs_for(file)
+        return [file] if @spec_files.include?(file)
+        return nil unless @included.include?(file) && evidence?(File.join(@root, file))
+
+        touching(File.join(@root, file)).then { |specs| specs if specs.all? { |spec| @spec_files.include?(spec) } }
+      end
+
+      def evidence?(path)
+        [@map.lines, @map.methods].any? { |hits| (hits[path] || {}).values.any?(&:any?) } &&
+          [@map.load_lines, @map.load_methods].none? { |hits| hits[path]&.any? } &&
+          !@map.preloaded?(path)
+      end
+
+      def touching(path)
+        ids = [@map.lines, @map.methods].flat_map { |hits| (hits[path] || {}).values.flatten }
+        ids.map { |id| spec_of(id) }.uniq
+      end
+
+      def spec_of(id)
+        self.class.spec_of(id)
+      end
+
+      def ordered(stale)
+        run_order = @map.tests.map { |id| spec_of(id) }.uniq
+        run_order.select { |file| stale.include?(file) } + (stale - run_order).sort
+      end
+
+      # Stale share of the recorded time, by spec file, never above THRESHOLD.
+      def heavy?(specs)
+        total = weights.values.sum
+        total.zero? || share(specs) > THRESHOLD
+      end
+
+      def weights
+        @map.tests.group_by { |id| spec_of(id) }
+            .transform_values { |ids| ids.sum { |id| @map.durations.fetch(id, 0) } }
+      end
+    end
+  end
+end