saboteur 0.7.0 → 0.8.1

data/lib/saboteur/engine/coverage_store.rb

@@ -15,7 +15,8 @@ module Saboteur
       LOCKFILES = %w[Gemfile.lock gems.locked].freeze
       LOG = "coverage-build.log"
 
-      def initialize(config:, integration:, hooks:, supervisor:, diagnostics:, load_lines: {}, timeout_cap: nil)
+      def initialize(config:, integration:, hooks:, supervisor:, diagnostics:, load_lines: {}, load_methods: {},
+                     timeout_cap: nil)
         @config = config
         @integration = integration
         @hooks = hooks
@@ -23,7 +24,9 @@ module Saboteur
         @diagnostics = diagnostics
         @timeout_cap = timeout_cap
         @load_lines = load_lines
+        @load_methods = load_methods
         @root = File.realpath(config.root)
+        @root_prefixes = Selection::CoverageMap.root_prefixes(config.root)
       end
 
       # True when fetch would reuse the cached map instead of running the
@@ -37,10 +40,11 @@ module Saboteur
 
       def fetch(files)
         path = cache_path(files)
+        preloaded = LoadCoverage.preloaded_uninstrumented(files)
         cached = cached_map(files)
-        return refuse_empty_map(cached, files) if cached
+        return refuse_empty_map(cached.with_preloaded(preloaded), files, preloaded) if cached
 
-        map = refuse_empty_map(build(files), files)
+        map = refuse_empty_map(build(files).with_preloaded(preloaded), files, preloaded)
         map.save(path)
         File.write(File.join(@config.path("cache_dir"), "preview.json"),
                    JSON.generate(path: path, fingerprint: RunFingerprint.new(config: @config).snapshot.digest))
@@ -49,6 +53,21 @@ module Saboteur
 
       private
 
+      def write_map(writer, recorder, build_seconds)
+        writer.write(recorder.result(build_seconds: build_seconds, loaded_files: loaded_project_files).to_json)
+        writer.close
+      end
+
+      # Every project source this child loaded, even a lazy require outside the
+      # include list that the recorder drops: --incremental must watch it, or a
+      # change there keeps stale verdicts (#353).
+      def loaded_project_files
+        $LOADED_FEATURES.filter_map do |file|
+          path = Text.utf8_strict(Selection::CoverageMap.canonical(file))
+          path if path.end_with?(".rb") && @root_prefixes.any? { |prefix| path.start_with?(prefix) }
+        end
+      end
+
       def cache_path(files)
         File.join(@config.path("cache_dir"), "coverage-#{cache_key(files)}.json")
       end
@@ -122,13 +141,16 @@ module Saboteur
       # The parent's load lines merge into the freshly built map: the forked
       # build child cannot inherit the parent's Coverage counters.
       def with_parent_load_lines(map)
-        @load_lines.empty? ? map : map.with_load_lines(@load_lines)
+        @load_lines.empty? && @load_methods.empty? ? map : map.with_load_lines(@load_lines, @load_methods)
       end
 
       # A whole-suite build that records nothing - no line hit and no method
-      # call - in any included file fails the run (exit 3): usually no test
-      # in the suite exercises these files, or the setup hid the app from
-      # Coverage (Bootsnap's compile cache is the default Rails case). An
+      # call - in any included file fails the run (exit 3). The recorder's map
+      # also holds the suite's spec files, so the check is per included file,
+      # not whole-map: a suite that tests nothing here still records its own
+      # spec code. Usually no test in the suite exercises these files, or
+      # the setup hid the app from Coverage (Bootsnap's compile cache is the
+      # default Rails case). An
       # all-endless-def file records method calls only and passes. Either way
       # a run on a truly empty map would test nothing, and exit 0 would lie.
       # With explicit tests (--test) an empty map is a legitimate outcome
@@ -136,9 +158,20 @@ module Saboteur
       # these sources, so the map passes with a warning. Applies to a cached
       # map too, so a map cached before this check cannot keep a run green,
       # and the guard runs before saving, so an empty map is never cached.
-      def refuse_empty_map(map, files)
-        return map if files.empty? || !map.empty?
-
+      def refuse_empty_map(map, files, preloaded)
+        return map if files.empty? || !map.empty_for?(files)
+
+        # A file loaded before the executable's Coverage.start can never be
+        # instrumented, so emptiness there is a setup defect, not untested
+        # code: name it apart from the generic no-coverage refusal.
+        preloaded_empty = preloaded & files.map { |file| Selection::CoverageMap.canonical(file) }
+        if preloaded_empty.any?
+          message = preloaded_message(preloaded_empty)
+          raise Error, message if @config["tests"].empty?
+
+          @diagnostics.warn(message)
+          return map
+        end
         if @config["tests"].empty?
           raise Error, "Coverage recorded nothing in #{files.size} included files during a whole-suite " \
                        "build. No test in the suite may exercise these files, or the setup hid the app " \
@@ -149,6 +182,16 @@ module Saboteur
         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 " \
+          "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 " \
+          "files; a gemspec should require only its version file."
+      end
+
       # Bootsnap is named only when it is loaded: blaming a library the app
       # does not use sends the reader to the wrong place.
       def bootsnap_note
@@ -175,7 +218,10 @@ module Saboteur
         $stderr.reopen($stdout)
         @hooks.run(:after_fork)
         started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        recorder = Selection::Recorder.new(files)
+        # 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.start
         Kernel.srand(@config["seed"])
         passed = @integration.run_all(recorder)
@@ -183,9 +229,7 @@ module Saboteur
           raise Error, "the unchanged suite failed while building coverage. Fix the suite, then run again " \
                        "with seed #{@config['seed']}."
         end
-        build_seconds = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
-        writer.write(recorder.result(build_seconds: build_seconds).to_json)
-        writer.close
+        write_map(writer, recorder, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
       rescue Exception => e # rubocop:disable Lint/RescueException
         writer.write(JSON.generate(error: "#{e.class}: #{e.message}"))
         exit!(1)

data/lib/saboteur/engine/defined_order_prefix.rb

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # The examples an order-dependent spec file needs, in the order RSpec
+    # defines them: for each file with a covering example, every example from
+    # the start of the file through its last covering example. Later examples
+    # cannot change earlier ones, so this is the smallest run that keeps
+    # whatever state the earlier examples leave behind.
+    class DefinedOrderPrefix
+      ID_PATTERN = /\A(?<file>.*)\[(?<path>[\d:]+)\]\z/
+
+      # every_test: all example ids the map knows, in any order.
+      def initialize(every_test)
+        @every_test = every_test
+      end
+
+      # The prefix for the covering examples; nil when it adds nothing to
+      # what already ran (an id that is not an RSpec id included).
+      def for(covering)
+        parsed = covering.map { |id| parse(id) }
+        return nil if parsed.any?(&:nil?)
+
+        prefix = parsed.group_by(&:first).flat_map { |file, entries| file_prefix(file, entries.map(&:last).max) }
+        prefix == covering ? nil : prefix
+      end
+
+      private
+
+      def file_prefix(file, last_position)
+        in_file = @every_test.filter_map { |id| (entry = parse(id)) && entry.first == file ? entry : nil }
+        through = in_file.select { |entry| (entry.last <=> last_position) <= 0 }.sort_by(&:last)
+        through.map { |entry| "#{file}[#{entry.last.join(':')}]" }
+      end
+
+      def parse(id)
+        match = ID_PATTERN.match(id)
+        match && [match[:file], match[:path].split(":").map(&:to_i)]
+      end
+    end
+  end
+end

data/lib/saboteur/engine/diagnostics.rb

@@ -74,7 +74,7 @@ module Saboteur
       DiscoveryFailure = Data.define(:file, :reason)
 
       attr_reader :warnings, :invalid_mutations, :generation_events, :omissions, :discovery_failures,
-                  :hazard_suppressions, :inline_suppressions
+                  :hazard_suppressions, :inline_suppressions, :verbose
 
       def initialize(err, verbose: false)
         @err = err
@@ -86,12 +86,30 @@ module Saboteur
         @discovery_failures = []
         @hazard_suppressions = 0
         @inline_suppressions = []
+        @erb_template_skips = []
+        @erb_template_note_emitted = false
       end
 
       def warn(message)
         @warnings << message
       end
 
+      # ERB generator templates (Rails generators carry `.rb` files with ERB
+      # interpolation, conventionally under `lib/generators/**/templates/`)
+      # can never parse as plain Ruby, so they can never hold mutation
+      # subjects (#372). One summarized note per run replaces the per-file
+      # parse warning every discovery pass used to print; a real syntax
+      # error in a plain Ruby file still warns per file.
+      def record_erb_template_skip(file, root:)
+        relative = file.to_s.delete_prefix("#{root}/")
+        @erb_template_skips << relative.freeze unless @erb_template_skips.include?(relative)
+        return if @erb_template_note_emitted
+
+        @erb_template_note_emitted = true
+        warn("skipping ERB template files that cannot parse as Ruby " \
+             "(for example #{relative}); templates are not mutation subjects")
+      end
+
       def count_invalid_mutation
         @invalid_mutations += 1
       end

data/lib/saboteur/engine/distribution.rb

@@ -15,6 +15,16 @@ module Saboteur
       # whose fresh kills the spent budget left unchecked (#296).
       attr_reader :unreached, :truncated, :unverified
 
+      # The run's peak-memory record for the JSON report (#202): each
+      # worker's kernel peak RSS and the supervisor's own, nil when the
+      # platform measured neither so the report omits the section. No total:
+      # fork copy-on-write makes per-process RSS non-additive.
+      def memory_report
+        workers = (@pool&.worker_peaks || {}).sort.map { |number, mb| { worker: number, peakMb: mb } }
+        supervisor = Execution::PeakMemory.peak_mb
+        workers.empty? && supervisor.nil? ? nil : { workers: workers, supervisorPeakMb: supervisor }.compact
+      end
+
       # stop_after: nil, or a callable that gets one subject's results and
       # returns true to stop before the next subject (--fail-fast). It only
       # works on one process: parallel workers have already started the

data/lib/saboteur/engine/early_stop_recording.rb

@@ -10,12 +10,13 @@ module Saboteur
       private
 
       # The subjects a stop left unrun or mid-way: the verdict covers less than the selection.
-      def record_early_stop(distribution)
+      def record_early_stop(distribution, planned_mutants: nil)
         return if distribution.unreached.empty? && distribution.truncated.empty? && distribution.unverified.empty?
 
         truncated = distribution.truncated.map { |subject, omitted| { subject: subject.id, omitted: omitted } }
         @early_stop = EarlyStop.new(reason: stop_reason(distribution), unreached: distribution.unreached.map(&:id),
-                                    truncated: truncated, unverified: distribution.unverified.map(&:id))
+                                    truncated: truncated, unverified: distribution.unverified.map(&:id),
+                                    planned_mutants: planned_mutants)
       end
 
       # Mid-subject omissions and skipped checks are budget work: only a

data/lib/saboteur/engine/gated_run.rb

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # A threshold or mutant-count gate judges the score, so a path that
+    # narrows what the score covers (a partially mapped --since run, #370)
+    # must keep its hard stop instead of green-lighting the change.
+    module GatedRun
+      private
+
+      def gated?
+        config["threshold"] || Gates.new(config).any?
+      end
+
+      # Reports the guess's skipped and subjectless files, then stops or
+      # warns on unmapped files per the gate (#370).
+      def report_unmapped(guess)
+        @diagnostics.inform(guess.subjectless_message(since: config["since"])) if guess.subjectless.any?
+        inform_skipped_specs(guess)
+        stop_or_warn_unmapped(guess)
+      end
+
+      # A --since run with a partial mapping runs the mapped subset with a
+      # loud warning per unmapped file (#370); a full run, a zero guess and
+      # a gated run keep the hard stop.
+      def stop_or_warn_unmapped(guess)
+        return if guess.unmatched.empty?
+        if !config["since"] || guess.specs.empty? || gated?
+          raise ConfigError, guess.unmatched_message(verbose: @diagnostics.verbose)
+        end
+
+        guess.unmatched.each { |file| @diagnostics.announce(guess.unmatched_warning(file)) }
+      end
+    end
+  end
+end

data/lib/saboteur/engine/load_coverage.rb

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "coverage"
+
+module Saboteur
+  class Engine
+    # The boot's coverage snapshot, read in the parent because a forked
+    # child does not inherit Coverage counters: the lines and the def
+    # calls that ran while the app and spec files loaded. The executable
+    # counts from its first line, so this snapshot holds the whole boot.
+    # The lines tell ran-at-load mutants apart from uncovered ones; the
+    # def calls name def-time macros whose only caller ran here, so their
+    # mutants read as ran at load instead of surviving on the pristine
+    # closure (#409).
+    module LoadCoverage
+      # Returns [load_lines, load_methods]: file => line numbers for each.
+      def self.capture(files)
+        return [{}, {}] unless Coverage.state == :suspended
+
+        wanted = files.to_set { |file| Selection::CoverageMap.canonical(file) }
+        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)
+          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?
+        end
+      end
+
+      # Include-listed files that are already loaded yet carry no coverage
+      # instrumentation: something required them before the executable's
+      # Coverage.start (a gemspec requiring the library while bundler/setup
+      # evaluates it, or RUBYOPT -r), so no test can ever be attributed to
+      # them. Read in the parent, where the snapshot still reflects the boot.
+      def self.preloaded_uninstrumented(files, loaded: $LOADED_FEATURES)
+        return [] unless Coverage.state == :suspended
+
+        instrumented = CoverageReads.result(stop: false, clear: false)
+                                    .each_key
+                                    .to_set { |path| Selection::CoverageMap.canonical(path) }
+        loaded_set = loaded.to_set { |path| Selection::CoverageMap.canonical(path) }
+        files.map { |file| Selection::CoverageMap.canonical(file) }
+             .uniq
+             .reject { |file| instrumented.include?(file) }
+             .select { |file| loaded_set.include?(file) }
+      end
+
+      # 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? } }
+      end
+    end
+  end
+end

data/lib/saboteur/engine/out_of_scope_guard.rb

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # The --since stop whose changed source files all sit outside the
+    # include scope (#483), kept apart from the guess flow it guards.
+    module OutOfScopeGuard
+      private
+
+      # Every changed source file sits outside the include scope (#483): the
+      # whole-suite fallback would run the slowest possible suite against
+      # zero subjects, so stop and name what the scope hid.
+      def refuse_out_of_scope_changes(guess)
+        return unless guess.changed.zero? && guess.out_of_scope.any?
+
+        raise ConfigError, guess.out_of_scope_message
+      end
+    end
+  end
+end

data/lib/saboteur/engine/pipelines.rb

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "../execution/test_command_shape"
+
+module Saboteur
+  class Engine
+    # The two run pipelines: in-process (boot, coverage, workers) and the
+    # --test-command external mode (#140).
+    module Pipelines
+      # The in-process pipeline: boot the target, mutate under coverage, and
+      # clean the workers up however the run ends.
+      def run_pipeline(ignore_list, started)
+        return call_external(ignore_list, started) if external_command?
+
+        boot = Boot.new(config, hooks)
+        begin
+          integration, files, load_lines, load_methods = boot_target(boot)
+          @rails = boot.rails
+          subjects, scope = select_subjects(files, test_files: integration.test_files)
+          results = if subjects.empty?
+                      []
+                    else
+                      mutate(subjects, files, integration, scope, ignore_list,
+                             load_lines:, load_methods:)
+                    end
+          @diagnostics.warnings.concat(ignore_list.apply(results, unscoped_digests: @unscoped_digests))
+          build_report(results, subjects, scope, started)
+        ensure
+          # Cleanup runs however the call ends - a partway boot failure, no
+          # subjects, no runnable work - so a host embedding Engine never
+          # holds worker copies until process exit. Idempotent; the Rails
+          # profile's at_exit handler stays the fallback for abrupt exit.
+          begin
+            @coverage_guard&.resume # an embedded host gets its coverage back (#254)
+          ensure
+            safely_cleanup_workers(boot.rails)
+          end
+        end
+      end
+
+      # The --test-command pipeline (#140): no boot, no coverage, no
+      # baseline - every mutant runs the command on the mutated tree,
+      # serially, with no sandbox. The command is arbitrary user code.
+      def call_external(ignore_list, started)
+        @diagnostics.inform("external test command: #{config['test_command']} " \
+                            "(serial, no coverage, unsandboxed, mutants applied in a disposable copy)")
+        if Execution::TestCommandShape.multi_file_ruby?(config["test_command"])
+          @diagnostics.warn("the test command hands several test files to one ruby: ruby executes only " \
+                            "the first, so the rest never run and their mutants silently survive (#611) - " \
+                            "use the framework's multi-file form (bin/rails test f1 f2, rspec f1 f2) or a " \
+                            "shell loop (for f in ...; do ruby \"$f\" || exit 1; done)")
+        end
+        files = config.included_files
+        subjects, scope = select_subjects(files)
+        results = subjects.empty? ? [] : mutate_external(subjects, scope, ignore_list)
+        @diagnostics.warnings.concat(ignore_list.apply(results, unscoped_digests: @unscoped_digests))
+        build_report(results, subjects, scope, started)
+      end
+
+      def mutate_external(subjects, scope, ignore_list)
+        runner = external_runner
+        # One neutral run before any mutant exists: a command that fails on
+        # the unchanged tree can never claim kills (#305). It answers to the
+        # run budget with an ABSOLUTE deadline, admitted after the tree copy:
+        # a budget already spent is a budget stop, not a command error.
+        begin
+          runner.preflight!(deadline: preflight_deadline, budget_deadline: budget_deadline)
+        rescue BudgetPhaseTimeout => e
+          return budget_phase_stop(e, subjects)
+        end
+        map = Selection::ExternalTestMap.new
+        scheduler = Scheduler.new(config:, runner:, map:,
+                                  reevaluator: Execution::Reevaluator.new(config["reeval"],
+                                                                          whole_file: config["whole_file"]),
+                                  diagnostics: @diagnostics, deadline: budget_deadline, verify_loaded: false)
+        lists = candidate_lists(subjects, scope, map)
+        work = subjects.zip(lists).reject { |_, list| list.empty? }
+        return [] if work.empty?
+
+        runnable_subjects, runnable_lists = work.transpose
+        begin
+          warn_unless_mutants_visible(runner, runnable_subjects.first)
+        rescue BudgetPhaseTimeout => e
+          return budget_phase_stop(e, subjects)
+        end
+        run_candidates(runnable_subjects, runnable_lists, scheduler, nil, ignore_list)
+      ensure
+        runner.close
+      end
+
+      # Warn loudly when the command cannot see mutants at all: an
+      # anchored or never-loaded file reads as 100 % survivors (#441).
+      def warn_unless_mutants_visible(runner, subject)
+        warning = runner.visibility_check(subject: subject, deadline: preflight_deadline,
+                                          budget_deadline: budget_deadline)
+        @diagnostics.warn(warning) if warning
+      end
+
+      def external_command? = !config["test_command"].to_s.empty?
+
+      # The preflight's absolute monotonic deadline: its own
+      # baseline_timeout slice, or the run budget's end, whichever is
+      # sooner. Absolute, so the tree copy before admission cannot eat the
+      # budget while the command still gets a full timeout (#305 Architect).
+      def preflight_deadline
+        own = Process.clock_gettime(Process::CLOCK_MONOTONIC) + config["baseline_timeout"]
+        deadline = budget_deadline
+        deadline ? [own, deadline].min : own
+      end
+
+      def external_runner = Execution::ExternalRunner.new(command: config["test_command"], root: @root)
+    end
+  end
+end

data/lib/saboteur/engine/result_cache.rb

@@ -15,25 +15,36 @@ module Saboteur
     # same: the method's source, the whole file the method lives in (so a
     # constant or helper changed elsewhere in that file is seen), the mutant,
     # the set of covering tests, the content of those tests' files, the
-    # lockfile, the run's inputs (config, saboteur version). Only killed, survived
-    # and timeout are stored;
+    # lockfile, the run's inputs (config, saboteur version), and every source
+    # file a covering test touched (a method it calls, a constant defined
+    # elsewhere - #197). Only killed, survived and timeout are stored;
     # errors and skips always run again.
     #
-    # Known hole, the reason this is opt-in: a change in another file that
-    # this method uses (a method it calls, a constant defined elsewhere) is
-    # not seen, so a stored verdict may be stale after it.
+    # When the dependency set is unknown - no coverage map, or an empty one -
+    # every source file is watched instead: reuse turns conservative, never
+    # stale.
     class ResultCache
       FORMAT = 1
       STORED = %i[killed survived timeout].freeze
       LOCKFILES = %w[Gemfile.lock gems.locked].freeze
+      # Dependency declarations themselves, so the no-lockfile library
+      # shape (bundler's own convention: libraries gitignore the lockfile)
+      # still invalidates on a dependency edit (#408).
+      MANIFESTS = %w[Gemfile gems.rb].freeze
+
+      SOURCE_EXCLUDES = %w[.git vendor node_modules].freeze
 
       # suite_digest: SuiteFiles#digest, so an edit to a spec helper or
       # support file invalidates every verdict.
-      def initialize(path:, root:, inputs:, suite_digest: "")
+      def initialize(path:, root:, inputs:, suite_digest: "", coverage: nil, fallback_files: [])
         @path = path
         @root = root
         @inputs = inputs
         @suite_digest = suite_digest
+        # Engine always passes the built map; a missing one behaves as an
+        # empty one, which watches every fallback and child-loaded source (#197).
+        @coverage = coverage || Selection::CoverageMap.new(lines: {}, tests: [])
+        @fallback_files = fallback_files.map { |file| File.expand_path(file, root) }.sort
         @entries = load
         @file_digests = {}
       end
@@ -65,6 +76,16 @@ module Saboteur
 
       private
 
+      # The current project source files, relative and sorted. A file added
+      # after the map was built changes the set and invalidates every stored
+      # verdict, whether or not any watched file references it yet.
+      def source_set
+        @source_set ||= Dir.glob("**/*.rb", base: @root)
+                           .reject { |rel| SOURCE_EXCLUDES.include?(rel.split("/").first) }
+                           .sort
+                           .join("\0")
+      end
+
       def load
         data = JSON.parse(Text.utf8_strict(File.read(@path)))
         data["format"] == FORMAT ? data["entries"] : {}
@@ -78,12 +99,33 @@ module Saboteur
 
       def fingerprint(subject, tests)
         digest = Digest::SHA256.new
-        digest << VERSION << "\0" << @inputs << "\0" << @suite_digest << "\0" << subject.source << "\0"
+        digest << [VERSION, @inputs, @suite_digest, source_set, subject.source].join("\0") << "\0"
         # A hex digest has a fixed width, so it needs no separator after it.
         digest << Digest::SHA256.hexdigest(subject.file_source)
+        digest_tests(digest, tests)
+        hash_dependency_inputs(digest)
+        digest.hexdigest
+      end
+
+      def digest_tests(digest, tests)
         tests.sort.each { |test| digest << test << "\0" << file_digest(test_file(test)) << "\0" }
+        dependencies(tests).each { |dep| digest << dep << "\0" << file_digest(dep) << "\0" }
         LOCKFILES.each { |name| digest << file_digest(File.join(@root, name)) << "\0" }
-        digest.hexdigest
+      end
+
+      # Files a change in which can flip the verdict (#197): every source
+      # file a covering test touched, from the run's coverage map, plus the
+      # loaded sources the map never observed (#344, #353).
+      def dependencies(tests)
+        (@coverage.files_for(tests) | @coverage.boot_files | unobserved_files).sort
+      end
+
+      # Loaded sources the map never observed (no line, method, or load
+      # evidence): coverage cannot say whether they matter, so a change in
+      # any of them must invalidate (#344).
+      def unobserved_files
+        @unobserved_files ||=
+          (@fallback_files | @coverage.loaded_files).select { |file| @coverage.empty_for?([file]) }
       end
 
       # RSpec ids name their file: "./spec/a_spec.rb[1:2]".
@@ -91,6 +133,21 @@ module Saboteur
         File.expand_path(test[/\A(.+?\.rb)(?:\[|:|\z)/, 1] || test, @root)
       end
 
+      def hash_dependency_inputs(digest)
+        dependency_files.each { |path| digest << path.delete_prefix("#{@root}/") << "\0" << file_digest(path) << "\0" }
+      end
+
+      # Manifests and gemspecs anywhere below the root, since a monorepo
+      # sub-gem carries its own dependency declarations (#561); keyed
+      # root-relative so same-named sub-gem files cannot collide. Vendored
+      # installs and dependencies' own checkouts hold gemspecs the project
+      # does not declare, so the scan mirrors RunFingerprint's exclusions.
+      def dependency_files
+        @dependency_files ||= Dir[File.join(@root, "**", "{#{MANIFESTS.join(',')},*.gemspec}")].reject do |path|
+          path.delete_prefix("#{@root}/").split("/").any? { |part| RunFingerprint::EXCLUDED_DIRECTORIES.include?(part) }
+        end
+      end
+
       def file_digest(path)
         @file_digests[path] ||= File.file?(path) ? Digest::SHA256.file(path).hexdigest : "missing"
       end

data/lib/saboteur/engine/run_budget.rb

@@ -35,12 +35,42 @@ module Saboteur
 
       # Absolute monotonic deadline shared with the schedulers (forked
       # workers inherit it): a subject's remaining mutants stop once it
-      # passes, so the overshoot after a spent budget stays under one
-      # mutant deadline.
+      # passes. New mutation work never overshoots more than the fork in
+      # flight; a subject the deadline cut mid-list still confirms the
+      # kills it already measured (#588), and those checks and retries
+      # fork uncapped - the overshoot is bounded by the subject's
+      # distinct killing sequences times their full timeout.
       def budget_deadline
         config["max_duration"] && (@run_started + config["max_duration"])
       end
 
+      # Once the baselines are timed, a cold coverage build is the last
+      # unpriced phase before the mutants: it costs about one more full pass
+      # and keeps nothing when the budget cuts it off, so a resume starts it
+      # from zero again. Refuse up front when the remaining budget cannot
+      # cover that pass, naming the shortfall and the remedies (#427).
+      def refuse_unaffordable_coverage_build(store, files, baseline_elapsed = @baseline_elapsed,
+                                             completed_passes = @completed_baseline_passes)
+        return unless config["max_duration"]
+        return if store.reusable?(files)
+        return if completed_passes.to_i.zero?
+
+        per_pass = baseline_elapsed / completed_passes
+        remaining = config["max_duration"] - (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @run_started)
+        # A spent budget is the existing stop path's news, and an untimed
+        # (zero-second) baseline carries no estimate to project from.
+        return if remaining <= 0 || per_pass <= 0
+        return if remaining >= per_pass
+
+        needed = per_pass - remaining
+        raise BudgetPhaseTimeout,
+              "the --max-duration budget cannot cover the coverage map build: baseline passes took about " \
+              "#{per_pass.round}s each, only #{remaining.round(1)}s remain, and a cold build needs about one " \
+              "more full pass and keeps nothing when it is cut off. Re-run with --max-duration about " \
+              "#{needed.round}s higher, fewer --baseline-passes, or once without --max-duration so the " \
+              "coverage cache is built for later --incremental runs"
+      end
+
       # Boot and baselines can spend the budget by themselves: stop before
       # an expensive cold coverage build and mark every selected subject
       # unrun.