saboteur 0.8.1 → 0.9.0

data/lib/saboteur/engine/subject_selection.rb

@@ -134,7 +134,8 @@ module Saboteur
             else
               @diagnostics.record_discovery_failure(file, reason: "invalid_file_syntax")
               parsed.errors.first(1).each do |message|
-                @diagnostics.warn("#{file.delete_prefix("#{@root}/")} does not parse: #{message}")
+                @diagnostics.warn("fix the syntax in #{Text.display_safe(file.delete_prefix("#{@root}/"))}: " \
+                                  "does not parse (#{Text.display_safe(message)})")
               end
             end
           end
@@ -179,7 +180,7 @@ module Saboteur
         macro = attribute_macro_for(pattern)
         return "--subject #{pattern} is defined by #{macro} and has no body to mutate" if macro
 
-        "--subject #{pattern} matches no subject (patterns are names like " \
+        "fix the --subject pattern \"#{pattern}\": it matches no subject (patterns are names like " \
           "Klass, Klass#meth or Klass.meth, not globs)"
       end
 
@@ -266,12 +267,13 @@ module Saboteur
         return subjects if reasons.empty?
 
         constant_warned_files << canonical
-        path = file.delete_prefix("#{@root}/")
+        path = Text.display_safe(file.delete_prefix("#{@root}/"))
         listed = reasons.first(2).join(", ")
-        @diagnostics.warn("--since: constant subject(s) in #{path} are not mutated: the file runs code at " \
-                          "load (#{listed}) that every constant mutant would run again, and saboteur " \
-                          "cannot vet what re-running it does. List the constant in c.whole_file to " \
-                          "replay the file anyway, or move the literal into its own file. " \
+        listed += ", and #{reasons.size - 2} more" if reasons.size > 2
+        @diagnostics.warn("#{path}: list the constant in c.whole_file to replay it anyway, or move the " \
+                          "literal into its own file\n  --since: constant subject(s) in this file are not " \
+                          "mutated: it runs code at load (#{listed}) that every constant mutant would run " \
+                          "again, and saboteur cannot vet what re-running it does. " \
                           "#{whole_file_id_hint(rest)}")
         opted_in
       end
@@ -303,15 +305,15 @@ module Saboteur
         @config["whole_file"].each do |pattern|
           next if subjects.any? { |subject| File.fnmatch?(pattern.to_s, subject.id) }
 
-          @diagnostics.warn("--since: whole_file pattern \"#{pattern}\" matches no discovered " \
-                            "subject in this run; subject ids look like RULES, A::B::C or A::B#m")
+          @diagnostics.warn("fix the whole_file entry \"#{Text.display_safe(pattern.to_s)}\": it matches no " \
+                            "discovered subject in this run (subject ids look like RULES, A::B::C or A::B#m)")
         end
       end
 
       def warn_unsupported_constant(found)
-        path = found.file.delete_prefix("#{@root}/")
-        @diagnostics.warn("--since: changed constant #{found.id} in #{path} is not mutated: #{found.reason}. " \
-                          "Only hash and array literal entries are mutated.")
+        path = Text.display_safe(found.file.delete_prefix("#{@root}/"))
+        @diagnostics.warn("--since: changed constant #{found.id} in #{path} is not mutated\n  " \
+                          "#{found.reason}; only hash and array literal entries are mutated")
       end
 
       # The tests that can observe a constant mutant are the ones covering a
@@ -330,9 +332,9 @@ module Saboteur
           subject.consumer_defs = reads.transform_values(&:defs)
           if subject.consumer_lines.empty? && reads.any? { |_file, r| r.load.any? }
             path = subject.file.delete_prefix("#{@root}/")
-            @diagnostics.warn("--since: changed constant #{subject.id} in #{path} is not mutated: its only " \
-                              "reads capture the value at load time in another file, so no test can " \
-                              "observe a change to it.")
+            @diagnostics.warn("--since: changed constant #{subject.id} in #{path} is not mutated\n  " \
+                              "its only reads capture the value at load time in another file, so no test " \
+                              "can observe a change to it")
             next
           end
           subject
@@ -395,11 +397,10 @@ module Saboteur
         unmatched = (@changed_lines.keys.select { |file| file.end_with?(".rb") } & included) - matched
         return if unmatched.empty?
 
-        names = unmatched.first(5).map { |file| file.delete_prefix("#{@root}/") }.join(", ")
-        more = unmatched.size > 5 ? ", ..." : ""
+        names = Text.name_list(unmatched.map { |file| file.delete_prefix("#{@root}/") })
         note = constant_note(unmatched)
         @diagnostics.warn("--since: #{unmatched.size} changed Ruby file(s) have no subjects covering " \
-                          "the changed lines, so nothing is mutated from them: #{names}#{more}. " \
+                          "the changed lines, so nothing is mutated from them: #{names}\n  " \
                           "#{subjectless_hint(unmatched)}#{note}")
       end
 
@@ -410,7 +411,7 @@ module Saboteur
         constants = unmatched.count { |file| constant_warned_files.include?(file) }
         return "" if constants.zero?
 
-        " #{constants} of these #{constants == 1 ? 'file has' : 'files have'} changes inside " \
+        "\n  #{constants} of these #{constants == 1 ? 'file has' : 'files have'} changes inside " \
           "a constant literal that is not mutated (the constant warnings above name them)."
       end
 
@@ -423,9 +424,8 @@ module Saboteur
         embedded = unmatched.select { |file| changed_lines_inside_heredoc?(file) }
         return "The file may not parse, or every change may sit outside a method." if embedded.empty?
 
-        names = embedded.first(5).map { |file| file.delete_prefix("#{@root}/") }.join(", ")
-        more = embedded.size > 5 ? ", ..." : ""
-        "In #{names}#{more} the changed lines are code embedded in a string (a heredoc, often the " \
+        names = Text.name_list(embedded.map { |file| file.delete_prefix("#{@root}/") })
+        "In #{names}, the changed lines are code embedded in a string (a heredoc, often the " \
           "argument to class_eval/module_eval or a template constant); methods defined by evaluating " \
           "strings are not mutation subjects, so this run cannot see that behavior."
       end
@@ -443,12 +443,11 @@ module Saboteur
         hits = excluded_territory & (@changed_lines.keys + untracked)
         return if hits.empty?
 
-        names = hits.sort.first(5).map { |file| file.delete_prefix("#{@root}/") }.join(", ")
-        more = hits.size > 5 ? ", ..." : ""
-        @diagnostics.warn("--since: #{hits.size} changed Ruby file(s) are covered by c.include but removed by " \
-                          "c.exclude, so nothing is mutated from them: #{names}#{more}. Narrow or remove the " \
-                          "c.exclude entry, or pass the file as a positional source operand (configured " \
-                          "excludes are then ignored).")
+        names = Text.name_list(hits.sort.map { |file| file.delete_prefix("#{@root}/") })
+        @diagnostics.warn("narrow or remove the c.exclude entry, or pass the file as a positional source " \
+                          "operand: #{hits.size} changed Ruby file(s) are covered by c.include but removed " \
+                          "by c.exclude\n  --since: nothing is mutated from them: #{names} (configured " \
+                          "excludes are then ignored)")
       end
 
       # Ruby files an include pattern and an exclude pattern both match,
@@ -473,10 +472,9 @@ module Saboteur
         end
         return subjects if dropped.empty?
 
-        names = dropped.first(5).map(&:id).join(", ")
-        more = dropped.size > 5 ? ", ..." : ""
+        names = Text.name_list(dropped)
         @diagnostics.inform("#{dropped.size} subject(s) skipped: intentionally untested in " \
-                            "config/saboteur_custom_map.rb: #{names}#{more}")
+                            "config/saboteur_custom_map.rb: #{names}")
         kept
       end
 
@@ -501,19 +499,17 @@ module Saboteur
       def report_deleted(deleted)
         return if deleted.empty?
 
-        names = deleted.first(5).map(&:id).join(", ")
-        more = deleted.size > 5 ? ", ..." : ""
+        names = Text.name_list(deleted)
         verb = deleted.one? ? "subject was" : "subjects were"
-        @diagnostics.inform("#{deleted.size} changed #{verb} deleted, nothing to mutate: #{names}#{more}")
+        @diagnostics.inform("#{deleted.size} changed #{verb} deleted, nothing to mutate: #{names}")
       end
 
       def report_unchanged_syntax(subjects)
         return if subjects.empty?
 
-        names = subjects.first(5).map(&:id).join(", ")
-        more = subjects.size > 5 ? ", ..." : ""
+        names = Text.name_list(subjects)
         @diagnostics.inform("#{subjects.size} changed subject(s) differ only in comments or formatting, " \
-                            "so they are skipped: #{names}#{more}")
+                            "so they are skipped: #{names}")
       end
 
       def canonical_path(file)

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

@@ -57,9 +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, :no_suite) do
+                           :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, **fields)
+                       no_suite: nil, without_map_entry: [], referenced: {}, crowded: {}, **fields)
           super
         end
 
@@ -74,10 +75,16 @@ module Saboteur
           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
@@ -85,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
@@ -117,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. " \
@@ -140,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
 
@@ -248,20 +264,35 @@ 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: [], 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,
@@ -269,6 +300,13 @@ module Saboteur
                    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
       # root: the diff touched source, but none of it lands inside include.
       # A changed spec is a test, not hidden source; a spec-only diff keeps
@@ -314,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
@@ -458,7 +516,9 @@ 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)) }
         return [conventional] if conventional
@@ -471,8 +531,9 @@ module Saboteur
       # 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?(/[*?\[{]/)
@@ -484,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

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.
@@ -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,7 +274,8 @@ 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)
@@ -309,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)
@@ -366,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
@@ -428,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
 
@@ -441,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"
@@ -451,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