saboteur 0.2.0 → 0.4.0

data/lib/saboteur/config.rb

@@ -1,13 +1,18 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
-require "yaml"
 require_relative "mutation_source/builtin"
 
 module Saboteur
-  # Settings from .saboteur.yml, overridden by CLI flags.
+  # Settings from config/saboteur.rb, overridden by CLI flags.
   class Config
-    FILE = ".saboteur.yml"
+    FILE = "config/saboteur.rb"
+
+    # Died with the YAML port: a leftover file means settings are
+    # silently ignored, which could turn off a threshold. Fail loud.
+    LEGACY_FILE = ".saboteur.yml"
+    LEGACY_IGNORE_FILE = ".saboteur-ignore.yml"
+    IGNORE_FILE = "config/saboteur_ignore.rb"
 
     DEFAULTS = {
       "integration" => "rspec",
@@ -21,41 +26,52 @@ module Saboteur
       "coverage_timeout" => 3600.0,
       "max_memory_mb" => 2048,
       "max_processes" => 64,
+      "max_mutants_per_method" => 100,
       "jobs" => 1,
-      "ignore_file" => ".saboteur-ignore.yml",
+      "ignore_file" => "config/saboteur_ignore.rb",
+      "custom_map" => "config/saboteur_custom_map.rb",
       "sources" => ["builtin"],
       "hooks" => [],
       "rails" => false,
       "reeval" => "nesting",
       "cache_dir" => ".saboteur",
       "json_report" => ".saboteur/report.json",
+      "html_report" => ".saboteur/report.html",
       "rspec_args" => [],
       "subjects" => [],
       "since" => nil,
       "cache" => true,
       "incremental" => false,
-      "seed" => 1
+      "seed" => 1,
+      "tests" => [],
+      "fingerprint_extra" => [],
+      "threshold" => nil
     }.freeze
 
-    INTEGER_KEYS = %w[jobs max_memory_mb max_processes seed].freeze
+    INTEGER_KEYS = %w[jobs max_memory_mb max_processes max_mutants_per_method seed].freeze
     FLOAT_KEYS = %w[timeout_factor timeout_min baseline_timeout coverage_timeout].freeze
-    LIST_KEYS = %w[require include exclude arid sources hooks rspec_args subjects].freeze
+    THRESHOLD_RANGE = (0.0..100.0)
+
+    LIST_KEYS = %w[require include exclude arid sources hooks rspec_args subjects tests
+                   fingerprint_extra].freeze
 
     attr_reader :root
 
     def self.load(root: Dir.pwd, path: nil, overrides: {})
       path ||= File.join(root, FILE)
-      from_file = File.file?(path) ? parse(path) : {}
-      new(from_file.merge(stringify(overrides)), root: root)
-    end
-
-    def self.parse(path)
-      data = YAML.safe_load_file(path) || {}
-      raise ConfigError, "#{path}: expected a mapping at the top level" unless data.is_a?(Hash)
+      legacy = File.join(root, LEGACY_FILE)
+      if File.file?(legacy)
+        raise ConfigError,
+              "saboteur no longer reads #{LEGACY_FILE}; move its settings to #{FILE} (see README)."
+      end
+      legacy_ignore = File.join(root, LEGACY_IGNORE_FILE)
+      if File.file?(legacy_ignore)
+        raise ConfigError,
+              "saboteur no longer reads #{LEGACY_IGNORE_FILE}; move its entries to #{IGNORE_FILE} (see README)."
+      end
 
-      data
-    rescue Psych::SyntaxError => e
-      raise ConfigError, "#{path}: #{e.message}"
+      from_file = File.file?(path) ? ConfigFile.load(path) : {}
+      new(from_file.merge(stringify(overrides)), root: root)
     end
 
     def self.stringify(hash)
@@ -70,6 +86,7 @@ module Saboteur
       @values = DEFAULTS.merge(values)
       coerce!
       validate!
+      validate_report_paths!
     end
 
     def [](key)
@@ -111,19 +128,46 @@ module Saboteur
       INTEGER_KEYS.each { |key| @values[key] = Integer(@values[key]) }
       FLOAT_KEYS.each { |key| @values[key] = Float(@values[key]) }
       LIST_KEYS.each { |key| @values[key] = Array(@values[key]).map(&:to_s) }
+      @values["threshold"] = Float(@values["threshold"]) unless @values["threshold"].nil?
     rescue ArgumentError, TypeError => e
       raise ConfigError, "invalid config value: #{e.message}"
     end
 
+    def validate_mutant_limit!
+      raise ConfigError, "max_mutants_per_method must be > 0" unless self["max_mutants_per_method"].positive?
+    end
+
+    def validate_report_paths!
+      json = path("json_report")
+      return unless json && json == path("html_report")
+
+      raise ConfigError, "json_report and html_report both point to #{json}; give each report its own path"
+    end
+
+    def validate_threshold!
+      threshold = self["threshold"]
+      return if threshold.nil? || THRESHOLD_RANGE.cover?(threshold)
+
+      raise ConfigError, "threshold must be between 0 and 100"
+    end
+
+    def validate_reeval!
+      raise ConfigError, "reeval must be one of: #{Execution::Reevaluator::STRATEGIES.join(', ')}" unless
+        Execution::Reevaluator::STRATEGIES.include?(self["reeval"].to_s)
+    end
+
     def validate!
       raise ConfigError, "jobs must be >= 1" if self["jobs"] < 1
+
+      validate_mutant_limit!
+      validate_threshold!
       raise ConfigError, "seed must be >= 0" if self["seed"].negative?
       raise ConfigError, "max_memory_mb must be > 0" unless self["max_memory_mb"].positive?
       raise ConfigError, "max_processes must be > 0" unless self["max_processes"].positive?
       raise ConfigError, "timeout_factor must be > 0" unless self["timeout_factor"].positive?
       raise ConfigError, "timeout_min must be > 0" unless self["timeout_min"].positive?
-      raise ConfigError, "reeval must be one of: #{Execution::Reevaluator::STRATEGIES.join(', ')}" unless
-        Execution::Reevaluator::STRATEGIES.include?(self["reeval"].to_s)
+
+      validate_reeval!
 
       self["arid"].each { |pattern| Regexp.new(pattern) }
     rescue RegexpError => e
@@ -131,3 +175,5 @@ module Saboteur
     end
   end
 end
+
+require_relative "config_file"

data/lib/saboteur/config_file.rb

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "did_you_mean"
+
+module Saboteur
+  # Loads config/saboteur.rb: a plain Ruby file of `Saboteur.configure`
+  # blocks assigning settings on a strict object. It runs before the app
+  # boots, so it cannot reference app constants - plain Ruby and ENV only.
+  module ConfigFile
+    # The assignment target. One setter per Config key; anything else is an
+    # unknown setting. Records the line of each assignment so validation
+    # errors can point at it.
+    class Settings
+      def initialize
+        @values = {}
+        @lines = {}
+      end
+
+      attr_reader :values, :lines
+
+      Config::DEFAULTS.each_key do |key|
+        define_method("#{key}=") do |value|
+          @values[key] = value
+          @lines[key] = caller_locations(1, 1).first.lineno
+        end
+      end
+
+      Config::INTEGER_KEYS.each do |key|
+        define_method("#{key}=") do |value|
+          unless value.is_a?(Integer)
+            line = caller_locations(1, 1).first.lineno
+            raise ConfigError, "#{line}: #{key} must be an Integer, got #{value.inspect}"
+          end
+          @values[key] = value
+          @lines[key] = caller_locations(1, 1).first.lineno
+        end
+      end
+    end
+
+    module_function
+
+    # The collector is process-global on purpose: the config file calls the
+    # top-level Saboteur.configure, which must reach the load in progress.
+    # Loads are therefore serialized - never load two config files at once.
+    def load(path)
+      @settings = Settings.new
+      Kernel.load(path)
+      @settings.values
+    rescue ConfigError => e
+      raise ConfigError, "#{path}:#{e.message}"
+    rescue NoMethodError => e
+      raise ConfigError, unknown_setting_message(path, e) if e.receiver.is_a?(Settings) && e.name.to_s.end_with?("=")
+
+      # A typo'd method call, not a setting: same treatment as a bare
+      # constant, or the raw NoMethodError points at our internals.
+      raise ConfigError, name_error_message(path, e)
+    rescue SyntaxError, LoadError => e
+      raise ConfigError, "#{path}: #{e.message.lines.first.to_s.chomp}"
+    rescue NameError => e
+      raise ConfigError, name_error_message(path, e)
+    ensure
+      @settings = nil
+    end
+
+    def unknown_setting_message(path, error)
+      key = error.name.to_s.delete_suffix("=")
+      suggestion = DidYouMean::SpellChecker.new(dictionary: Config::DEFAULTS.keys).correct(key).first
+      hint = suggestion ? " (did you mean #{suggestion.inspect}?)" : ""
+      line = error.backtrace_locations.find { |loc| loc.path == path }&.lineno
+      "#{path}:#{line}: unknown setting #{key.inspect}#{hint}. " \
+        "Valid settings: #{Config::DEFAULTS.keys.join(', ')}"
+    end
+
+    def name_error_message(path, error)
+      line = error.backtrace_locations&.find { |loc| loc.path == path }&.lineno
+      "#{path}:#{line}: #{error.message.lines.first.to_s.chomp} " \
+        "- this file loads before the app boots; use plain Ruby or ENV"
+    end
+
+    private_class_method :unknown_setting_message, :name_error_message
+
+    # The Settings block Saboteur.configure hands to the file being loaded.
+    def current_settings
+      @settings
+    end
+  end
+
+  # Entry point used by config/saboteur.rb.
+  def self.configure
+    settings = ConfigFile.current_settings
+    raise "Saboteur.configure is only valid while config/saboteur.rb loads" unless settings
+
+    yield settings
+    settings
+  end
+end

data/lib/saboteur/custom_map.rb

@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  # Explicit source-file -> spec-file mapping from config/saboteur_custom_map.rb:
+  #
+  #   SABOTEUR_CUSTOM_MAP = {
+  #     "app/services/tax_sync.rb" => ["spec/services/tax_sync_spec.rb"],
+  #     "app/services/**/*.rb"     => ["spec/services/**/*_spec.rb"],
+  #     %r{\Aapp/jobs/(.*)\.rb\z}  => ['spec/jobs/\1_spec.rb'],
+  #     "app/generated/**/*.rb"    => [], # intentionally untested
+  #   }.freeze
+  #
+  # The file loads before the app boots, so it must be plain Ruby.
+  class CustomMap
+    CONSTANT = :SABOTEUR_CUSTOM_MAP
+
+    Entry = Data.define(:key, :specs)
+
+    attr_reader :entries, :root
+
+    def self.load(path, root: Dir.pwd)
+      return new([], root: root) unless path && File.file?(path)
+
+      Object.send(:remove_const, CONSTANT) if Object.const_defined?(CONSTANT)
+      Kernel.load(path)
+      unless Object.const_defined?(CONSTANT)
+        raise ConfigError, "#{path}: expected it to define #{CONSTANT} = { ... }.freeze"
+      end
+
+      data = Object.const_get(CONSTANT)
+      raise ConfigError, "#{path}: #{CONSTANT} must be a Hash, got #{data.class}" unless data.is_a?(Hash)
+
+      new(data.map { |key, specs| validate_entry(path, root, key, specs) }, root: root)
+    rescue SyntaxError, LoadError => e
+      raise ConfigError, "#{path}: #{e.message.lines.first.to_s.chomp}"
+    rescue NameError => e
+      raise ConfigError, name_error_message(path, e)
+    ensure
+      Object.send(:remove_const, CONSTANT) if Object.const_defined?(CONSTANT)
+    end
+
+    def self.name_error_message(path, error)
+      line = error.backtrace_locations&.find { |loc| loc.path == path }&.lineno
+      "#{path}:#{line}: #{error.message.lines.first.to_s.chomp} " \
+        "- this file loads before the app boots; use plain Ruby or ENV"
+    end
+
+    def self.validate_entry(path, root, key, specs)
+      unless key.is_a?(String) || key.is_a?(Regexp)
+        raise ConfigError, "#{path}: key #{key.inspect} must be a String path, glob, or Regexp"
+      end
+      unless specs.is_a?(Array)
+        raise ConfigError, "#{path}: #{key.inspect} maps to #{specs.inspect}; wrap spec paths in an array"
+      end
+
+      specs.each { |spec| validate_spec(path, root, key, spec) }
+      Entry.new(key: key, specs: specs)
+    end
+
+    def self.validate_spec(path, root, key, spec)
+      unless spec.is_a?(String)
+        raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}; spec paths must be Strings"
+      end
+      return if key.is_a?(Regexp) && spec.match?(/\\\d/) # backreference filled in at match time
+
+      expanded = File.expand_path(spec, root)
+      unless expanded.start_with?("#{root}/")
+        raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}, which is outside the project root"
+      end
+      return if Dir.glob(expanded).any?
+
+      raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}, which matches no file"
+    end
+
+    private_class_method :validate_entry, :validate_spec
+
+    def initialize(entries, root: Dir.pwd)
+      @entries = entries
+      @root = root
+    end
+
+    def empty?
+      @entries.empty?
+    end
+
+    # Spec paths for a source file, nil when no entry matches, :excluded when
+    # the winning entry maps to an empty array (intentionally untested).
+    def specs_for(file)
+      exact = @entries.find { |entry| entry.key == file }
+      return resolve(exact, nil) if exact
+
+      glob = glob_entry(file)
+      return resolve(glob, nil) if glob
+
+      regexp_specs(file)
+    end
+
+    # String keys (exact or glob) that match nothing under the root.
+    def stale_keys
+      @entries.select { |entry| entry.key.is_a?(String) }
+              .reject { |entry| Dir.glob(File.join(@root, entry.key)).any? }
+              .map(&:key)
+    end
+
+    # Literal String keys written twice (Ruby silently keeps the last).
+    # Detection is line-based and only sees double-quoted one-line keys;
+    # single-quoted, multi-line or %q keys that repeat go unreported.
+    def duplicate_keys(path)
+      seen = Hash.new(0)
+      File.readlines(path).each do |line|
+        seen[::Regexp.last_match(1)] += 1 if line =~ /^\s*"(.+?)"\s*=>/
+      end
+      seen.select { |_, count| count > 1 }.keys
+    end
+
+    def self.glob?(pattern, file)
+      File.fnmatch?(pattern, file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+    end
+
+    private
+
+    def glob_entry(file)
+      globs = @entries.select { |entry| entry.key.is_a?(String) && self.class.glob?(entry.key, file) }
+      return nil if globs.empty?
+
+      best = globs.group_by { |entry| specificity(entry.key) }.max_by { |score, _| score }.last
+      if best.size > 1
+        raise ConfigError,
+              "custom map keys #{best.map { |e| e.key.inspect }.join(' and ')} both match #{file} " \
+              "with equal specificity; make one more specific"
+      end
+      best.first
+    end
+
+    def regexp_specs(file)
+      matches = @entries.filter_map do |entry|
+        next unless entry.key.is_a?(Regexp)
+
+        match = entry.key.match(file)
+        [entry, match] if match
+      end
+      return nil if matches.empty?
+      # Exclusion is unanimous: a file is intentionally untested only when
+      # every matching regexp entry maps to an empty array. One mapped entry
+      # is enough to keep the file tested; unmapped entries add nothing.
+      return :excluded if matches.all? { |entry, _| entry.specs.empty? }
+
+      matches.reject { |entry, _| entry.specs.empty? }
+             .flat_map { |entry, match| resolve(entry, match) }
+    end
+
+    def specificity(key)
+      key.count("^*?[]{}\\")
+    end
+
+    def resolve(entry, match)
+      return :excluded if entry.specs.empty?
+
+      specs = entry.specs
+      if match
+        # A backreference to a group that did not participate expands to "";
+        # that is never a real spec path, so drop it here rather than letting
+        # a junk entry reach the run.
+        specs = specs.map { |spec| spec.gsub(/\\(\d+)/) { match[::Regexp.last_match(1).to_i].to_s } }.reject(&:empty?)
+      end
+      specs
+    end
+  end
+end

data/lib/saboteur/doctor.rb

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "coverage"
+require_relative "baseline_health"
+
+module Saboteur
+  # Reports the current environment and runs baseline checks, never mutations.
+  class Doctor
+    def initialize(config, out: $stdout)
+      @config = config
+      @out = out
+    end
+
+    def call
+      Engine::Boot.refuse_recursion!
+      check_runtime
+      check_coverage
+      check_boot_files
+      check_custom_map
+      hooks = Hooks.new
+      integration = boot_target(hooks)
+      @out.puts "Integration: #{@config['integration']} (loaded)"
+      @out.puts "Rails: #{@config['rails'] ? 'enabled' : 'disabled'}"
+      @out.puts "SimpleCov: #{defined?(::SimpleCov) ? 'present; start suppressed for this process' : 'not loaded'}"
+      check_coverage
+      tests = BaselineHealth.new(@config, integration: integration, hooks: hooks).call
+      @out.puts "Baseline: #{tests.size} tests passed twice in the same order with seed #{@config['seed']}"
+      @out.puts "Healthy in these two runs. This does not prove the suite is free of flaky tests."
+      true
+    end
+
+    private
+
+    def boot_target(hooks)
+      Engine::Boot.new(@config, hooks).load_target
+    rescue LoadError, SyntaxError, SystemExit, StandardError => e
+      raise Error, "target boot failed: #{e.class}: #{e.message}; check require files, hooks and rspec_args"
+    end
+
+    def check_runtime
+      @out.puts "Ruby: #{RUBY_DESCRIPTION}"
+      unless Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.3") && Process.respond_to?(:fork)
+        raise Error, "doctor needs Ruby 3.3+ with fork; use supported Ruby on Linux or macOS"
+      end
+      return if @config["integration"] == "rspec"
+
+      raise ConfigError,
+            "doctor supports the rspec integration; set integration: rspec"
+    end
+
+    def check_coverage
+      state = Coverage.state
+      @out.puts "Coverage: #{state}"
+      return if Coverage.supported?(:lines) && state == :suspended
+
+      raise Error, "Coverage must be suspended with line support before boot; use the saboteur executable, " \
+                   "disable SimpleCov and remove other Coverage.start calls"
+    end
+
+    def check_custom_map
+      path = @config.path("custom_map")
+      map = CustomMap.load(path, root: @config.root)
+      return @out.puts("Custom map: none (optional)") if map.empty?
+
+      duplicates = map.duplicate_keys(path)
+      if duplicates.any?
+        @out.puts "Warning: custom map keys written twice, Ruby keeps the last: #{duplicates.join(', ')}"
+      end
+      stale = map.stale_keys
+      raise ConfigError, "#{path}: stale keys matching no file: #{stale.join(', ')}" if stale.any?
+
+      @out.puts "Custom map: #{map.entries.size} entries (loaded)"
+    end
+
+    def check_boot_files
+      %w[require hooks].each do |key|
+        @config[key].each do |file|
+          path = File.expand_path(file, @config.root)
+          raise ConfigError, "#{key} file missing: #{file}; fix config/saboteur.rb" unless File.file?(path)
+
+          @out.puts "#{key}: #{file} (found)"
+        end
+      end
+      @config.unmatched_patterns.each { |pattern| @out.puts "Warning: #{pattern} matches no file" }
+    end
+  end
+end

data/lib/saboteur/engine/baseline_guard.rb

@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Saboteur
+  class Engine
+    # Two fresh children check the unchanged suite before any cached verdict
+    # or mutation source is used. This catches observed instability, not all
+    # possible flaky behaviour.
+    class BaselineGuard
+      def initialize(config:, integration:, hooks:, supervisor:, diagnostics:)
+        @config = config
+        @integration = integration
+        @hooks = hooks
+        @supervisor = supervisor
+        @diagnostics = diagnostics
+      end
+
+      def call
+        expected = @integration.all_tests.map(&:id)
+        raise Error, "baseline has no tests. Check rspec_args and the suite filters before running saboteur again." if
+          expected.empty?
+
+        @diagnostics.inform("checking the unchanged suite twice (seed #{@config['seed']})")
+        previous = nil
+        2.times do |index|
+          number = index + 1
+          data = check(number)
+          unless data["passed"] && data["failed"].empty?
+            refuse(number,
+                   "the suite failed: #{Array(data['failed']).join(', ')}")
+          end
+          executed = data["executed"]
+          refuse(number, "executed tests do not match the loaded suite") unless
+            executed.sort == expected.sort
+          refuse(number, "test order changed between baseline checks") if previous && executed != previous
+          previous = executed
+        end
+        nil
+      end
+
+      private
+
+      def check(number)
+        Execution::ForkReadiness.prepare_heap
+        heartbeat = @diagnostics.progress_heartbeat("baseline check #{number}")
+        result = @supervisor.run(timeout: @config["coverage_timeout"], on_tick: heartbeat.method(:tick)) do |writer|
+          record(writer, number)
+        end
+        refuse(number, "the suite stopped: #{result.stopped_by} (#{result.detail})") if result.stopped_by
+        # Before the payload checks: a child killed by a signal (the OOM
+        # killer, say) writes nothing, and the signal is the explanation.
+        if result.exit_status.is_a?(Process::Status) && !result.exit_status.success?
+          refuse(number, unsuccessful_exit(result.exit_status))
+        end
+        refuse(number, "the child did not report a result") if result.payload.empty?
+        refuse(number, "the suite left child processes behind") if result.leftover_pids.any?
+        parse_result(number, result.payload)
+      end
+
+      # A signaled child (the OOM killer, say) can leave an empty log,
+      # which reads like a suite failure; name the signal and hint the
+      # likely cause instead.
+      def unsuccessful_exit(status)
+        return "the child exited with status #{status.exitstatus}" unless status.signaled?
+
+        signal = "SIG#{Signal.signame(status.termsig)}"
+        hint = signal == "SIGKILL" ? " - possible OOM, check memory" : ""
+        "the child was killed by #{signal}#{hint}"
+      end
+
+      def parse_result(number, payload)
+        data = JSON.parse(payload)
+        refuse(number, "the child reported an invalid result") unless data.is_a?(Hash)
+        refuse(number, data["error"]) if data["error"]
+        refuse(number, "the child reported invalid test results") unless valid_result?(data)
+        data
+      rescue JSON::ParserError
+        refuse(number, "the child reported invalid JSON")
+      end
+
+      def valid_result?(data)
+        [true, false].include?(data["passed"]) && data["failed"].is_a?(Array) &&
+          data["executed"].is_a?(Array) && data["executed"].all?(String)
+      end
+
+      def record(writer, number)
+        path = log_path(number)
+        FileUtils.mkdir_p(File.dirname(path))
+        $stdout.reopen(path, "w")
+        $stdout.sync = true
+        $stderr.reopen($stdout)
+        @hooks.run(:after_fork)
+        Kernel.srand(@config["seed"])
+        result = @integration.run_baseline(seed: @config["seed"])
+        writer.write(JSON.generate(passed: result.passed, failed: result.failed_ids, executed: result.executed_ids))
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        writer.write(JSON.generate(error: "#{e.class}: #{e.message}"))
+      ensure
+        writer.close
+      end
+
+      def log_path(number)
+        File.join(@config.path("cache_dir"), "baseline-#{number}.log")
+      end
+
+      def refuse(number, reason)
+        raise Error, "baseline check #{number} failed at seed #{@config['seed']}: #{reason}. " \
+                     "See the log at #{log_path(number)}. Fix the suite or its setup, then run saboteur again " \
+                     "with the same seed. No mutants were started."
+      end
+    end
+  end
+end

data/lib/saboteur/engine/boot.rb

@@ -62,6 +62,7 @@ module Saboteur
         @rails = rails = Frameworks::Rails.new(@config, @hooks) if @config["rails"]
         rails&.before_boot
         @hooks.run(:before_boot)
+        add_spec_to_load_path if @config["rails"]
         @config["require"].each { |file| require File.expand_path(file, @root) }
         integration = Integration.fetch(@config["integration"]).new(@config)
         integration.setup
@@ -72,6 +73,14 @@ module Saboteur
 
       private
 
+      # rspec puts spec/ on the load path, so a boot file under spec/ (a
+      # dummy app's rails_helper, say) can require its siblings. Match
+      # that, or the same require list fails to load.
+      def add_spec_to_load_path
+        path = File.join(@root, "spec")
+        $LOAD_PATH.unshift(path) unless $LOAD_PATH.include?(path)
+      end
+
       def load_hooks
         Saboteur.current_hooks = @hooks
         @config["hooks"].each { |file| load File.expand_path(file, @root) }

data/lib/saboteur/engine/candidate_selection.rb

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # Selects a bounded list for each covered subject before workers fork.
+    # Subject skips are not mutants and do not enter the mutation score.
+    class CandidateSelection
+      attr_reader :skipped_subjects
+
+      def initialize(candidates:, map:, limit:, diagnostics:)
+        @candidates = candidates
+        @map = map
+        @limit = limit
+        @diagnostics = diagnostics
+        @skipped_subjects = {}
+      end
+
+      def for(subject, scope: nil)
+        if @map.tests_for(subject).empty?
+          @skipped_subjects[subject] = "no coverage"
+          return []
+        end
+
+        list = @candidates.for(subject)
+        list = scope.restrict(subject, list) if scope
+        omitted = list.size - @limit
+        if omitted.positive?
+          @diagnostics.warn("#{subject.id}: omitted #{omitted} mutant(s) above max_mutants_per_method (#{@limit})")
+        end
+        list.first(@limit)
+      end
+    end
+  end
+end