saboteur 0.8.0 → 0.9.0

data/lib/saboteur/engine/suite_partition.rb

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # Splits a suite's spec files into disjoint parts for parallel coverage
+    # builds (#741). The sorted list is dealt round-robin, the rule
+    # script/rspec-shard uses without weights, so every file lands in exactly
+    # one part and the split depends only on the file list, never on load or
+    # discovery order. A part that would be empty is not returned.
+    class SuitePartition
+      def self.parts(files, total)
+        raise ArgumentError, "parts must be at least 1, got #{total}" if total < 1
+
+        sorted = files.uniq.sort
+        dealt = Array.new([total, sorted.size].min) { [] }
+        sorted.each_with_index { |file, position| dealt[position % dealt.size] << file }
+        dealt
+      end
+    end
+  end
+end

data/lib/saboteur/engine/test_guess.rb

@@ -16,6 +16,38 @@ module Saboteur
     # subject need a guessed spec; without --since, every included file with
     # a mutation subject needs one. A file that needs a spec and has none
     # stops the run before boot.
+    # A project with no *_spec.rb anywhere under its root has no RSpec suite
+    # at all: a per-file stop would print one line per
+    # source file and bury the real problem (#606, sibling of the
+    # missing-rspec-core refusal #542). The stop is one line naming it, with
+    # a Minitest pointer when test/ exists; --verbose keeps the per-file list.
+    module NoSuiteStop
+      MINITEST = "no RSpec suite found - saboteur needs RSpec; " \
+                 "this project appears to use Minitest (test/), see docs/minitest.md"
+      PLAIN = "no RSpec suite found - saboteur needs RSpec; no spec file exists to run, see docs/minitest.md"
+
+      module_function
+
+      # nil when the run should not claim a missing suite: a --subject run
+      # already names its expected spec, nothing is unmatched, or a suite
+      # exists. The suite can live outside spec/ - rspec_args can point
+      # RSpec at another default path - so look under the whole root;
+      # claiming "no spec file exists" for such a project is false and
+      # drops the --test/--all remedy (#606). :minitest or :plain otherwise.
+      def layout(root, unmatched, subject_run)
+        return if subject_run || unmatched.empty?
+
+        return unless Dir.glob(File.join(root, "**", "*_spec.rb")).empty?
+
+        File.directory?(File.join(root, "test")) ? :minitest : :plain
+      end
+
+      def message(layout, pairs:, verbose: false)
+        line = layout == :minitest ? MINITEST : PLAIN
+        verbose ? "#{line} Files without a guessed spec: #{pairs.join(', ')}." : line
+      end
+    end
+
     class TestGuess
       # hints: unmatched file -> its conventional spec path (which does
       # not exist; that is why the file is unmatched), for the stop-before-boot
@@ -25,8 +57,10 @@ module Saboteur
       # in specs; skipped_specs: spec files the diff touches that cannot run,
       # each with the reason.
       Result = Data.define(:specs, :unmatched, :subjectless, :changed, :hints, :changed_specs,
-                           :skipped_specs, :out_of_scope, :excluded, :near) do
-        def initialize(changed_specs: [], skipped_specs: {}, out_of_scope: [], excluded: [], near: {}, **fields)
+                           :skipped_specs, :out_of_scope, :excluded, :near, :no_suite, :without_map_entry,
+                           :referenced, :crowded) do
+        def initialize(changed_specs: [], skipped_specs: {}, out_of_scope: [], excluded: [], near: {},
+                       no_suite: nil, without_map_entry: [], referenced: {}, crowded: {}, **fields)
           super
         end
 
@@ -35,12 +69,22 @@ module Saboteur
         # command, which could carry a hostile ref or a wrong source scope.
         # When the diff deleted the expected spec or added others, it says
         # so: a renamed spec is the usual cause.
-        def unmatched_message
+        def unmatched_message(verbose: false)
+          if no_suite
+            return NoSuiteStop.message(no_suite, pairs: unmatched.map { |f| pair_description(f) }, verbose: verbose)
+          end
+
           pairs = unmatched.map { |file| pair_description(file) }
-          changed = changed_specs.any? ? " Specs the diff adds or changes: #{changed_specs.join(', ')}." : ""
+          changed = changed_specs.any? ? " Specs the diff adds or changes: #{names(changed_specs)}." : ""
+          # The map is the documented escape hatch for layouts the
+          # convention cannot guess - named only for files no entry covers;
+          # a file whose own entry broke heard that in the warning (#640).
+          mapped = without_map_entry.any? &&
+                   " If the layout defeats the naming convention, map #{names(without_map_entry)} by hand in " \
+                   "config/saboteur_custom_map.rb: no entry covers it."
           "no spec found for #{pairs.join(', ')}, so nothing ran.#{changed} Re-run the same command with " \
             "one --test per existing spec path, or append --all to use the whole suite without " \
-            "changing the source scope."
+            "changing the source scope.#{mapped}"
         end
 
         private
@@ -48,22 +92,31 @@ module Saboteur
         def pair_description(file)
           expected = hints.fetch(file)
           gone = skipped_specs[expected] == DELETED ? ", deleted in the diff" : ""
-          found = near.fetch(file, []).any? ? "; found: #{near.fetch(file).join(', ')}" : ""
-          "#{file} (expected #{expected}#{gone}#{found})"
+          found = near.fetch(file, []).any? ? "; found: #{names(near.fetch(file))}" : ""
+          crowd = (count = crowded[file]) ? "; #{ReferenceSpecs.crowd_note(count)}" : ""
+          "#{Text.display_safe(file)} (expected #{Text.display_safe(expected)}#{gone}#{found}#{crowd})"
         end
 
+        # Repo-controlled names reach CI logs, so each is escaped before it
+        # joins a message (#834): a file name may hold a newline.
+        def names(list) = list.map { |name| Text.display_safe(name) }.join(", ")
+
         public
 
+        # The files that had no spec by name and got the specs that read
+        # their constants instead (#725 replaces the guess once a map exists).
+        def referenced_message = ReferenceSpecs.note(referenced)
+
         # The spec files the diff touched that do not run, with the reasons.
         def skipped_message
-          named = skipped_specs.map { |path, reason| "#{path} (#{reason})" }
+          named = skipped_specs.map { |path, reason| "#{Text.display_safe(path)} (#{reason})" }
           "inferred specs: not running spec files changed in the diff: #{named.join(', ')}"
         end
 
         # Why the subjectless files needed no spec.
         def subjectless_message(since:)
           detail = since ? "no changed mutation subjects" : "no mutation subjects"
-          "inferred specs: no spec is required for #{subjectless.join(', ')}: they have #{detail}"
+          "inferred specs: no spec is required for #{names(subjectless)}: they have #{detail}"
         end
 
         # The per-file warning when the run proceeds with the mapped
@@ -80,7 +133,7 @@ module Saboteur
         # scope hid. Append-only recovery, like unmatched_message: extend include, or
         # name the specs with --test.
         def out_of_scope_message
-          named = out_of_scope.first(10).join(", ")
+          named = names(out_of_scope.first(10))
           more = out_of_scope.size - 10
           named += " and #{more} more" if more.positive?
           "no changed source file lies inside the include scope, so nothing ran. " \
@@ -103,7 +156,7 @@ module Saboteur
 
         # Why the custom-map-excluded files needed no spec (#369).
         def excluded_message
-          "inferred specs: no spec is required for #{excluded.join(', ')}: " \
+          "inferred specs: no spec is required for #{names(excluded)}: " \
             "intentionally untested in config/saboteur_custom_map.rb"
         end
 
@@ -148,7 +201,9 @@ module Saboteur
       def call_for(files, patterns = [])
         files = effective_subject_files(files, patterns) if @config["since"]
         guesses = files.to_h { |file| [file, guess_for(file)] }
-        result(guesses, [], files.size)
+        # A --subject run already knows its suite: the stop names the one
+        # expected spec, never the no-suite line (#606 is the full-run flood).
+        result(guesses, [], files.size, subject_run: true)
       end
 
       # specs: existing spec files (relative paths) guessed for the files in
@@ -209,24 +264,47 @@ module Saboteur
         end
       end
 
+      # The specs the diff itself adds or changes, when a --since run has
+      # any guesses to join them with; empty otherwise.
+      def diff_specs(inferred, guesses)
+        @config["since"] && guesses.any? ? specs_in_diff(inferred) : { run: [], skipped: {} }
+      end
+
+      # Unmatched files no map entry even tries to cover: the stop points
+      # those at the map (#640); a file whose own entry broke already heard
+      # about it in the guess-time warning.
+      def without_map_entry(unmatched)
+        unmatched.select { |file| @custom_map.specs_for(file).nil? }
+      end
+
       # Changed specs join only a run that mutates something: with no file
       # in scope there is nothing for them to kill.
-      def result(guesses, subjectless, changed, out_of_scope: [])
+      def result(guesses, subjectless, changed, out_of_scope: [], subject_run: false)
         unmatched = guesses.select { |_, specs| specs.nil? }.keys
         excluded = guesses.select { |_, specs| specs == :excluded }.keys.sort
         inferred = guesses.values.grep(Array).flatten
-        diff = @config["since"] && guesses.any? ? specs_in_diff(inferred) : { run: [], skipped: {} }
+        diff = diff_specs(inferred, guesses)
         unmatched -= covered_by_changed_specs(unmatched, diff[:run])
-        Result.new(specs: (inferred + diff[:run]).uniq.sort,
+        unmatched, referenced = split_referenced(unmatched)
+        Result.new(specs: (inferred + diff[:run] + referenced.values.flatten).uniq.sort,
+                   referenced: referenced,
                    unmatched: unmatched,
+                   without_map_entry: without_map_entry(unmatched),
                    subjectless: subjectless,
                    changed: changed,
-                   hints: unmatched.to_h { |file| [file, expected_spec(file, diff[:skipped])] },
-                   near: unmatched.to_h { |file| [file, nearby_specs(file)] },
+                   **stop_details(unmatched, diff[:skipped]),
                    changed_specs: diff[:run],
                    skipped_specs: diff[:skipped],
                    out_of_scope: out_of_scope,
-                   excluded: excluded)
+                   excluded: excluded,
+                   no_suite: NoSuiteStop.layout(@root, unmatched, subject_run))
+      end
+
+      # What the stop names for each unmatched file: the spec it expected and
+      # the same-named specs elsewhere.
+      def stop_details(unmatched, skipped)
+        { hints: unmatched.to_h { |file| [file, expected_spec(file, skipped)] },
+          near: unmatched.to_h { |file| [file, nearby_specs(file)] }, crowded: @crowded }
       end
 
       # Changed Ruby files the include scope hides (#483), relative to the
@@ -274,6 +352,26 @@ module Saboteur
         end
       end
 
+      # Cold start, no map: the specs that read a constant an unmatched file
+      # defines (#538 matching). Only files that would stop the run today; a
+      # same-basename spec elsewhere means the user has a spec in mind and
+      # the choice is ambiguous: that stop stays, it names the candidates (#658).
+      def split_referenced(unmatched)
+        referenced = reference_specs(unmatched)
+        [unmatched - referenced.keys, referenced]
+      end
+
+      def reference_specs(unmatched)
+        @crowded = {}
+        unmatched = unmatched.select { |file| nearby_specs(file).empty? }
+        return {} if unmatched.empty? || suite_files.nil?
+
+        specs = suite_files.select { |path| spec?(path) }
+        found = ReferenceSpecs.new(@root, method(:defined_constants)).call(unmatched, specs)
+        @crowded = found.crowded
+        found.chosen
+      end
+
       # The constants a file defines: owners of its def subjects
       # ("JWT::Claims::DecodeVerifier" from "...#call") and its constant
       # literal subjects. Shaped for ConstantReads, which matches a bare
@@ -303,13 +401,17 @@ module Saboteur
       # --test without hunting (#370). Bounded; computed only for
       # unmatched files, which are about to stop or warn.
       def nearby_specs(file)
-        # The basename is data, not a pattern: [, ], {, }, ?, * and \ are
-        # glob metacharacters and must be escaped to match literally.
-        basename = File.basename(file, ".rb").gsub(/[\[\]{}?*\\]/) { |char| "\\#{char}" }
+        basename = escape_glob(File.basename(file, ".rb"))
         Dir.glob("spec/**/#{basename}_spec.rb", base: @root)
            .select { |path| File.file?(File.join(@root, path)) }.sort.first(3)
       end
 
+      # A path segment is data, not a pattern: [, ], {, }, ?, * and \ are
+      # glob metacharacters and must be escaped to match literally.
+      def escape_glob(segment)
+        segment.gsub(/[\[\]{}?*\\]/) { |char| "\\#{char}" }
+      end
+
       # lstat, not stat: a symlink can point anywhere, including a spec of
       # another application or a fixture the suite excludes.
       def unrunnable_reason(path)
@@ -414,18 +516,24 @@ module Saboteur
       def guess_for(file)
         mapped = @custom_map.specs_for(file)
         return :excluded if mapped == :excluded
-        return expand_mapped(file, mapped) if mapped
+
+        expanded = mapped && expand_mapped(file, mapped)
+        return expanded if expanded
 
         conventional = candidates_for(file).find { |path| File.file?(File.join(@root, path)) }
-        conventional && [conventional]
+        return [conventional] if conventional
+
+        unique = unique_suffix_spec(file)
+        unique && [unique]
       end
 
       # A mapped spec can be a glob (expanded against the root) or a regexp
       # backreference filled at match time, and neither is validated to
       # exist when the map loads. Only specs that exist run; the literal
       # glob string never reaches RSpec. When the winning entry's specs all
-      # vanish the mapping is broken: stop naming it rather than silently
-      # guessing on and running the wrong specs (#369).
+      # vanish the entry is stale or mistyped: warn and fall through to the
+      # naming convention (and, failing that, to the usual stop guidance),
+      # instead of dying with a ConfigError and hiding the way out (#640).
       def expand_mapped(file, specs)
         expanded = specs.flat_map do |spec|
           if spec.match?(/[*?\[{]/)
@@ -437,7 +545,10 @@ module Saboteur
         expanded = expanded.select { |path| File.file?(File.join(@root, path)) }
         return expanded unless expanded.empty?
 
-        raise ConfigError, "custom map entry for #{file} names spec(s) #{specs.join(', ')}, which match no file"
+        shown = specs.first(5).map { |spec| Text.display_safe(spec) }.join(", ")
+        shown += ", and #{specs.size - 5} more" if specs.size > 5
+        @diagnostics&.warn("fix the custom map entry for #{Text.display_safe(file)}: spec(s) #{shown} match no file")
+        nil
       end
 
       # Candidate specs for a source file, most specific first: the nearest
@@ -464,14 +575,31 @@ module Saboteur
 
       # Layouts that mirror less of the source path, after every mirrored
       # guess (#394): a spec/unit/ prefix (shoulda-matchers mirrors below
-      # it, #393), the basename at the spec root (pundit), and both
-      # together (aasm, #370). Weaker guesses come last: the first
-      # candidate that exists wins. A file outside the source roots
-      # keeps its literal guess only: dropping directories from a path
-      # the roots never anchored would guess any same-named spec.
+      # it, #393), directories dropped between the gem namespace and the
+      # file (rubocop-ast tests lib/rubocop/ast/node/block_node.rb in
+      # spec/rubocop/ast/block_node_spec.rb, #586), the basename at the
+      # spec root (pundit), and both together (aasm, #370). Weaker
+      # guesses come last: the first candidate that exists wins. A file
+      # outside the source roots keeps its literal guess only: dropping
+      # directories from a path the roots never anchored would guess any
+      # same-named spec.
       def layout_variants(names)
         flat = names.map { |name| name.split("/").last }.uniq
-        (names + names.map { |name| "unit/#{name}" } + flat + flat.map { |name| "unit/#{name}" }).uniq
+        (names + names.map { |name| "unit/#{name}" } + flattened_below_namespace(names) + flat +
+          flat.map { |name| "unit/#{name}" }).uniq
+      end
+
+      # Every way to drop mid directories from a name, fewest dropped
+      # first: each guess keeps at least the leading namespace segment
+      # and the basename, so it stays anchored on the gem namespace and
+      # more specific than the bare basename flatten (#586).
+      def flattened_below_namespace(names)
+        names.flat_map do |name|
+          segments = name.split("/")
+          (segments.size - 2).downto(1).map do |keep|
+            (segments.first(keep) + [segments.last]).join("/")
+          end
+        end.uniq
       end
 
       # Rails tests controllers as request specs: spec/requests/users_spec.rb
@@ -483,6 +611,32 @@ module Saboteur
         ["requests/#{path}", "requests/#{path.delete_suffix('_controller')}"].uniq
       end
 
+      # The last-resort guess when no named candidate exists (#600): a
+      # spec tree can strip directories the convention keeps - aasm tests
+      # lib/aasm/core/invokers/proc_invoker.rb in
+      # spec/unit/invokers/proc_invoker_spec.rb, dropping the aasm and
+      # core segments. The one anchor such a layout keeps is the file's
+      # parent directory and basename, so a spec under the spec root
+      # ending in that suffix is the guess - but only a unique one: a
+      # second match makes the layout ambiguous, and guessing would run
+      # the wrong specs, a false verdict worse than the stop, whose
+      # near-miss hint names the candidates. Only files under a source
+      # root with a real parent directory qualify: a bare basename can
+      # collide anywhere, so it stays a near-miss hint.
+      def unique_suffix_spec(file)
+        pack = pack_of(file)
+        stem = file.delete_prefix("#{pack}/").delete_suffix(".rb")
+        root_segment, _, name = stem.partition("/")
+        return nil unless SOURCE_ROOTS.include?(root_segment) && name.include?("/")
+
+        suffix = name.split("/").last(2).map { |segment| escape_glob(segment) }.join("/")
+        spec_root = pack ? "#{pack}/spec" : "spec"
+        matches = Dir.glob(File.join(@root, spec_root, "**", "#{suffix}_spec.rb"))
+                     .select { |path| File.file?(path) }
+                     .map { |path| path.delete_prefix("#{@root}/") }.sort
+        matches.one? ? matches.first : nil
+      end
+
       # The nearest ancestor directory holding a package.yml (a packwerk
       # pack), relative to the root. The root itself is not a pack here:
       # Pathname#ascend stops above "." for these relative paths.

data/lib/saboteur/engine/unchanged_syntax.rb

@@ -45,8 +45,16 @@ module Saboteur
         files.flat_map do |file|
           next [] unless file.end_with?(".rb") && File.file?(file)
 
-          current_ids = unique_by_id(File.read(file), file).keys
-          base_subjects(file).values.reject { |subject| current_ids.include?(subject.id) }
+          # The diff reaches files outside the mutation scope (fixtures,
+          # scripts): an in-scope file nested too deeply already refused
+          # the run at subject finding, so a DeepSourceError here can only
+          # come from a file the run never mutates. Skip it (#719, #730).
+          begin
+            current_ids = unique_by_id(File.read(file), file).keys
+            base_subjects(file).values.reject { |subject| current_ids.include?(subject.id) }
+          rescue DeepSourceError
+            []
+          end
         end
       end
 

data/lib/saboteur/engine.rb

@@ -16,6 +16,7 @@ require_relative "engine/thread_warnings"
 
 require_relative "engine/pipelines"
 require_relative "engine/shard"
+require_relative "engine/suite_partition"
 
 module Saboteur
   # A single-use instance runs one pipeline: boot the target, select subjects, fetch the
@@ -44,7 +45,7 @@ module Saboteur
       @root = File.realpath(config.root)
       @skipped_subjects = {}
       @replay = Replay.new(digest: digest) if digest
-      if capture_evidence && (digest || config["since"] || config["incremental"] || config["shard"])
+      if capture_evidence && (digest || config["since"] || config["incremental"] || config["resume"] || config["shard"])
         raise ConfigError,
               "baseline evidence requires fresh whole-scope execution: no since, replay, shard or incremental"
       end
@@ -76,9 +77,19 @@ module Saboteur
     def preflight!
       Boot.refuse_recursion!
       refuse_fail_fast_evidence
+      verify_resume_directory
     end
 
-    def warn_custom_map = @diagnostics.warnings.concat(custom_map_warnings(load_custom_map))
+    # An unusable --resume directory fails before the expensive phases (#471).
+    def verify_resume_directory
+      return if @replay || !config["resume"]
+
+      ResumeManifest.new(directory: config.path("resume"), identity: Digest::SHA256.hexdigest(verdict_inputs)).verify!
+    rescue ResumeManifest::Mismatch => e
+      raise ConfigError, e.message
+    end
+
+    def warn_custom_map = @diagnostics.add_warnings(custom_map_warnings(load_custom_map))
 
     # Stale entries and duplicate literals never fail a run; they warn so the
     # map does not rot silently. doctor fails on stale keys.
@@ -136,7 +147,7 @@ module Saboteur
       return if guess.changed.zero?
 
       inform_skipped_specs(guess)
-      raise ConfigError, guess.unmatched_message if guess.unmatched.any?
+      raise ConfigError, guess.unmatched_message(verbose: @diagnostics.verbose) if guess.unmatched.any?
 
       @diagnostics.inform(guess.excluded_message) if guess.excluded.any?
       # Every file in scope intentionally untested: mutate nothing. An
@@ -152,13 +163,15 @@ module Saboteur
     def build_report(results, subjects, scope, started)
       Report.new(results: results, subjects: subjects, wall_time: monotonic - started, root: @root,
                  invalid_mutations: @diagnostics.invalid_mutations, warnings: @diagnostics.warnings,
+                 live_announced: @diagnostics.live_announced,
                  review: !scope.nil?, seed: config["seed"], skipped_subjects: @skipped_subjects,
                  diff_scope: scope, generation_events: @diagnostics.generation_events,
                  omissions: @diagnostics.omissions, run_evidence: complete_evidence(results, subjects),
                  hazard_suppressions: @diagnostics.hazard_suppressions, early_stop: @early_stop,
                  matrix: config["matrix"], inline_suppressions: @diagnostics.inline_suppressions,
                  operator_policy: config.operator_policy, discovery_failures: @diagnostics.discovery_failures,
-                 shard: @shard, memory: @memory_report)
+                 test_command: config["test_command"],
+                 shard: @shard, memory: @memory_report, referenced: @guessed_referenced || {})
     end
 
     def complete_evidence(results, subjects)
@@ -261,14 +274,16 @@ module Saboteur
     def coverage_store(integration, load_lines, load_methods = {})
       CoverageStore.new(config: config, integration: integration, hooks: hooks, load_lines:, load_methods:,
                         supervisor: supervisor(memory_factor: 4), diagnostics: @diagnostics,
-                        timeout_cap: method(:budget_capped_timeout))
+                        timeout_cap: method(:budget_capped_timeout),
+                        parts: config["coverage_parts"])
     end
 
     def check_baseline(integration, full_passes)
       guard = BaselineGuard.new(config: config, integration: integration, hooks: hooks,
                                 supervisor: supervisor(memory_factor: 4), diagnostics: @diagnostics,
                                 full_passes: full_passes, timeout_cap: method(:budget_capped_timeout),
-                                between_passes: config["max_duration"] ? method(:budget_exceeded?) : nil)
+                                between_passes: config["max_duration"] ? method(:budget_exceeded?) : nil,
+                                run_started: @run_started)
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       guard.call
       @baseline_elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
@@ -308,15 +323,18 @@ module Saboteur
 
     def result_cache(map = nil, files = [])
       return nil if @replay
-      return nil unless config["incremental"]
+      return nil unless config["incremental"] || config["resume"]
 
-      inputs = JSON.generate(VERDICT_INPUTS.to_h { |key| [key, config[key]] }
-                                            .merge("operator_policy" => config.operator_policy))
-      ResultCache.new(path: File.join(config.path("cache_dir"), "results.json"), root: @root, inputs: inputs,
+      directory = config.path("resume") || config.path("cache_dir")
+      ResultCache.new(path: File.join(directory, "results.json"), root: @root, inputs: verdict_inputs,
                       suite_digest: SuiteFiles.new(config).digest,
                       coverage: map, fallback_files: source_files(files))
     end
 
+    def verdict_inputs
+      JSON.generate(VERDICT_INPUTS.to_h { |key| [key, config[key]] }.merge("operator_policy" => config.operator_policy))
+    end
+
     # A cleanup failure must never mask the run's own outcome - not even
     # one cleanup_workers did not anticipate.
     def safely_cleanup_workers(rails)
@@ -365,7 +383,8 @@ module Saboteur
 
       candidates = Candidates.build(config, @diagnostics, hazard_guard: hazard_guard)
       selection = CandidateSelection.new(candidates: candidates, map: map,
-                                         limit: config["max_mutants_per_method"], diagnostics: @diagnostics)
+                                         limit: config["max_mutants_per_method"], diagnostics: @diagnostics,
+                                         root: @root)
       lists = subjects.map { |subject| selection.for(subject, scope: scope) }
       @shard = Engine::Shard.parse(config["shard"]) if config["shard"]
       lists = @shard.select(subjects, lists) if @shard
@@ -427,6 +446,9 @@ module Saboteur
 
     def suspend_coverage(files)
       (@coverage_guard = CoverageGuard.new(@diagnostics)).suspend
+      # Coverage stops counting here, so the call tracer stops with it
+      # instead of crediting the calls the engine itself makes afterwards.
+      MethodCalls.booted&.pause
       LoadCoverage.capture(files)
     end
 
@@ -440,8 +462,18 @@ require_relative "engine/boot"
 require_relative "engine/subject_selection"
 require_relative "engine/unchanged_syntax"
 require_relative "engine/suite_files"
+require_relative "engine/reference_specs"
 require_relative "engine/test_guess"
 require_relative "engine/sandbox_policy"
+require_relative "engine/coverage_inputs_snapshot"
+require_relative "engine/partial_invalidation"
+require_relative "engine/partial_merge"
+require_relative "engine/shadow_comparison"
+require_relative "engine/shadow_run"
+require_relative "engine/coverage_shadow"
+require_relative "engine/coverage_partial"
+require_relative "engine/coverage_parts"
+require_relative "engine/coverage_miss_note"
 require_relative "engine/coverage_store"
 require_relative "engine/baseline_guard"
 require_relative "engine/unscoped_suite_warning"
@@ -450,6 +482,7 @@ require_relative "engine/candidates"
 require_relative "engine/candidate_selection"
 require_relative "engine/diff_scope"
 require_relative "engine/result_cache"
+require_relative "engine/resume_manifest"
 require_relative "engine/defined_order_prefix"
 require_relative "engine/verdict_check"
 require_relative "engine/scheduler"

data/lib/saboteur/environment_hints.rb

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  # Environment hints for runs started the wrong way (#598, #609). Detected
+  # from files, never from error text; advisory only - nothing refuses.
+  module EnvironmentHints
+    module_function
+
+    # One line per detected problem, each a full sentence for the channel it
+    # lands in (boot warning, doctor line, or load-failure appendix).
+    def all(root, bundler_loaded: !defined?(Bundler).nil?, env: ENV)
+      [bundler(root, bundler_loaded: bundler_loaded), appraisal(root, env: env)].compact
+    rescue StandardError
+      # An advisory hint must never stop a run (Pod 1 security review).
+      []
+    end
+
+    # #598: a lockfile but no Bundler means gems resolve to whatever is
+    # installed, not the lockfile's versions.
+    def bundler(root, bundler_loaded: !defined?(Bundler).nil?)
+      return nil unless File.file?(File.join(root, "Gemfile.lock"))
+      return nil if bundler_loaded
+
+      "Gemfile.lock found but Bundler is not loaded: gems resolve to whatever is installed, not the " \
+        "lockfile's versions - run `bundle exec saboteur run`"
+    end
+
+    # #609: an Appraisal project run without BUNDLE_GEMFILE pointing into
+    # gemfiles/ loads the wrong (or no) dependency set.
+    def appraisal(root, env: ENV)
+      appraisals = File.file?(File.join(root, "Appraisals"))
+      gemfiles = Dir.glob(File.join(root, "gemfiles", "*.gemfile"))
+      return nil unless appraisals || gemfiles.any?
+
+      setting = env["BUNDLE_GEMFILE"].to_s
+      under = !setting.empty? &&
+              File.expand_path(setting, root).start_with?("#{File.join(File.expand_path(root), 'gemfiles')}/")
+      return nil if under
+
+      found = (appraisals ? ["Appraisals"] : []) +
+              gemfiles.map { |f| sanitize(f.sub("#{File.expand_path(root)}/", "")) }
+      where = setting.empty? ? "is not set" : "points outside gemfiles/ (#{sanitize(setting)})"
+      "Appraisal gemfiles found (#{Text.name_list(found)}) but BUNDLE_GEMFILE #{where}: run " \
+        "`BUNDLE_GEMFILE=gemfiles/<name>.gemfile bundle exec saboteur run` or " \
+        "`bundle exec appraisal <name> saboteur run`"
+    end
+
+    # A cloned repo can name gemfiles with terminal control characters (Pod 1
+    # security review): escape them before they reach the terminal.
+    def sanitize(text)
+      text.scrub("?").gsub(/[\x00-\x1f\x7f\u0080-\u009f]/) { |c| format("\\x%02x", c.ord) }
+    end
+  end
+end