saboteur 0.7.0 → 0.8.0

data/lib/saboteur/engine/boot.rb

@@ -10,6 +10,10 @@ module Saboteur
       # A test suite that (perhaps only under a mutant) starts a saboteur run
       # would otherwise run saboteur inside a saboteur child, recursively.
       def self.refuse_recursion!
+        if ENV[Execution::ExternalRunner::CHILD_MARKER]
+          raise Error, "refusing to start: this process runs inside a saboteur external test command " \
+                       "(#{Execution::ExternalRunner::CHILD_MARKER} is set); a nested run could race its tree"
+        end
         return unless ENV[Execution::Supervisor::CHILD_ENV]
 
         raise Error, "refusing to start: this process is a saboteur child " \

data/lib/saboteur/engine/candidate_selection.rb

@@ -22,6 +22,10 @@ module Saboteur
         reason = subject.skip_reason || (skip_reason_for(subject) if @map.tests_for(subject).empty?)
         if reason
           @skipped_subjects[subject] = reason
+          # In a scoped run every subject is part of the change under
+          # review, so a skip is said up front, not only in the end-of-run
+          # summary (#574).
+          @diagnostics.announce(skip_announcement(subject, reason)) if scope
           return @selected[subject] = []
         end
 
@@ -44,6 +48,21 @@ module Saboteur
 
       private
 
+      # A scoped no-coverage skip names the specs the run loaded: coverage
+      # living in a sibling spec file is otherwise invisible, and the false
+      # read is "untestable" when the truth is "not loaded" (#636). Names
+      # at most five, like the other selection notes.
+      def skip_announcement(subject, reason)
+        line = "#{subject.id}: skipped (#{reason}); its change is not verified by this run"
+        return line unless reason == "no coverage"
+
+        loaded = @map.tests.map { |id| id.split("[").first.delete_prefix("./") }.uniq.sort
+        more = loaded.size > 5 ? ", ..." : ""
+        names = loaded.empty? ? "none" : loaded.first(5).join(", ")
+        "#{line} - loaded specs: #{names}#{more}; " \
+          "other spec files may cover it, pass --test to load them"
+      end
+
       # Load-only code is not "no coverage": it ran, just never inside a
       # test, and no forked test can re-run it (see CoverageMap::RAN_AT_LOAD).
       def skip_reason_for(subject)

data/lib/saboteur/engine/candidates.rb

@@ -10,6 +10,25 @@ module Saboteur
     # a subject into runnable candidates: applied, re-parsed, de-duplicated,
     # coarse first. Returns [[mutation, mutated_text]].
     class Candidates
+      # The generator for constant hash/array literal subjects (#306); the
+      # method operators walk a def body a constant does not have.
+      def self.build(config, diagnostics, hazard_guard:)
+        new(build_sources(config), diagnostics, hazard_guard: hazard_guard,
+                                                constant_source: build_constant_source(config))
+      end
+
+      # Constants are generated by the builtin operator family, so a
+      # config that drops "builtin" from c.sources drops constant mutation
+      # too: the configured sources are the boundary for every subject
+      # kind (#319). Custom sources never see constants.
+      def self.build_constant_source(config)
+        return nil unless config["sources"].include?("builtin")
+
+        MutationSource::ConstantLiterals.new(operators: config["operators"],
+                                             exclude_operators: config["exclude_operators"],
+                                             arid: config["arid"])
+      end
+
       def self.build_sources(config)
         root = File.realpath(config.root)
         config["sources"].map do |entry|
@@ -19,15 +38,26 @@ module Saboteur
           end
 
           file, const = entry.split(":", 2)
-          raise ConfigError, "mutation source #{entry.inspect} must be builtin or path.rb:ClassName" unless const
+          unless const
+            if entry.include?("*")
+              raise ConfigError, "mutation source #{entry.inspect} looks like a source glob; " \
+                                 "did you mean c.include? c.sources registers custom operator sources " \
+                                 "(builtin or path.rb:ClassName)"
+            end
+            raise ConfigError, "mutation source #{entry.inspect} must be builtin or path.rb:ClassName"
+          end
 
           require File.expand_path(file, root)
           Object.const_get(const).new
         end
       end
 
-      def initialize(sources, diagnostics, hazard_guard: nil, bytecode: BytecodeEquivalence.new)
+      # constant_source: the generator for ConstantSubject instances; nil
+      # leaves constants with no candidates (a safe empty list).
+      def initialize(sources, diagnostics, hazard_guard: nil, bytecode: BytecodeEquivalence.new,
+                     constant_source: nil)
         @sources = sources
+        @constant_source = constant_source
         @diagnostics = diagnostics
         @hazard_guard = hazard_guard
         @bytecode = bytecode
@@ -40,7 +70,7 @@ module Saboteur
         end
 
         seen = Set[subject.source]
-        list = @sources.flat_map { |source| proposals(source, subject) }.filter_map do |mutation|
+        list = sources_for(subject).flat_map { |source| proposals(source, subject) }.filter_map do |mutation|
           candidate(subject, mutation, seen)
         end
         list = suppress_inline(list, subject)
@@ -50,6 +80,15 @@ module Saboteur
 
       private
 
+      # Constant literals have their own generator; external custom sources
+      # implement the def-subject contract and never see constants (#306).
+      def sources_for(subject)
+        return @sources unless subject.is_a?(ConstantSubject)
+        return [] unless @constant_source
+
+        [@constant_source]
+      end
+
       def suppress_inline(list, subject)
         directives = InlineSuppression.new(subject.file, subject.file_source)
         list.reject do |mutation, _text|
@@ -95,6 +134,7 @@ module Saboteur
         seen << text
         unless parses?(text)
           @diagnostics.count_invalid_mutation
+          @diagnostics.warn("#{subject.id}: dropped #{mutation.operator} mutation (did not parse)")
           return record_drop(subject, mutation, "invalid_syntax")
         end
 

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
@@ -49,6 +52,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 +140,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
@@ -137,7 +158,7 @@ module Saboteur
       # 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?
+        return map if files.empty? || !map.empty_for?(files)
 
         if @config["tests"].empty?
           raise Error, "Coverage recorded nothing in #{files.size} included files during a whole-suite " \
@@ -175,7 +196,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 +207,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

@@ -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,35 @@
+# 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?
+        raise ConfigError, guess.unmatched_message if !config["since"] || guess.specs.empty? || gated?
+
+        guess.unmatched.each { |file| @diagnostics.announce(guess.unmatched_warning(file)) }
+      end
+    end
+  end
+end

data/lib/saboteur/engine/load_coverage.rb

@@ -0,0 +1,45 @@
+# 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
+
+      # 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,107 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+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)")
+        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