saboteur 0.3.0 → 0.5.0

data/lib/saboteur/cli.rb

@@ -6,9 +6,17 @@ require_relative "../saboteur"
 require_relative "doctor"
 require_relative "help"
 require_relative "reporter/replay"
+require_relative "baseline/command"
+require_relative "cli/exit_status"
+require_relative "preview"
+require_relative "cli/run_reporting"
 
 module Saboteur
   class CLI
+    include Baseline::Command
+    include ExitStatus
+    include RunReporting
+
     USAGE = "Usage: saboteur run [SOURCE...] [--test TEST...] [--threshold PERCENT] [--since REF] " \
             "[--subject 'Klass#meth'] [--timeout-factor N] [--jobs N] [--seed N] [--id DIGEST]
 " \
@@ -18,7 +26,6 @@ module Saboteur
     EXIT_SURVIVORS = 1
     EXIT_USAGE = 2
     EXIT_TOOL = 3
-
     class UsageError < ConfigError; end
 
     attr_reader :options
@@ -28,14 +35,17 @@ module Saboteur
       @out = out
       @err = err
       @options = {}
+      @format = "agent" if agent_requested?
     end
 
     def call
       case @argv.shift
-      when "run" then help_requested? ? show_help("run") : run
+      when "run" then run_command
+      when "baseline" then baseline
       when "doctor" then help_requested? ? show_help("doctor") : doctor
       when "version", "--version" then @out.puts(VERSION) || EXIT_OK
       when "help" then show_help(@argv.shift)
+      when "agent-skill" then @out.print(AgentSkill::TEXT) || EXIT_OK
       when "--help", "-h" then show_help(nil)
       else usage_error
       end
@@ -53,25 +63,34 @@ module Saboteur
         define_selection_options(opts)
         define_explicit_file_options(opts)
         define_execution_options(opts)
+        define_matrix_option(opts)
         define_output_options(opts)
       end
     end
 
     # Each command's own option lines, as printed under OPTIONS in `saboteur help`.
     def option_lines
-      { "run" => parser.summarize, "doctor" => doctor_parser.summarize }
+      { "run" => parser.summarize, "doctor" => doctor_parser.summarize, "baseline" => baseline_parser.summarize }
     end
 
     def doctor_parser
       OptionParser.new do |opts|
-        opts.banner = "Usage: saboteur doctor [--config PATH] [--seed N]"
-        opts.on("--config PATH", "Config file (default .saboteur.yml)") { |value| set(:config, value) }
+        opts.banner = "Usage: saboteur doctor [--config PATH] [--seed N] [--suite] [--test PATH]"
+        opts.on("--config PATH", "Config file (default config/saboteur.rb)") { |value| set(:config, value) }
         opts.on("--seed N", Integer, "Seed for the two baseline runs (default 1)") { |value| set(:seed, value) }
+        opts.on("--suite", "Also run the unchanged suite twice (slow on a large suite)") { set(:suite, true) }
+        opts.on("--test PATH", "Spec file or directory for the suite runs; repeatable. Implies --suite") do |value|
+          (options[:tests] ||= []) << value
+        end
       end
     end
 
     private
 
+    def run_command
+      help_requested? ? show_help("run") : run
+    end
+
     def help_requested?
       @argv.intersect?(%w[--help -h])
     end
@@ -88,35 +107,82 @@ module Saboteur
     def usage_error(message = nil)
       @err.puts(message) if message
       @err.puts(USAGE)
-      EXIT_USAGE
+      agent_failure(message || USAGE, EXIT_USAGE)
+    end
+
+    def agent?
+      @format == "agent"
+    end
+
+    # Found before parsing, so any error, even a bad option that comes first, still
+    # answers an agent with JSON.
+    def agent_requested?
+      @argv.include?("--agent") || @argv.include?("--format=agent") ||
+        @argv.each_cons(2).any? { |flag, value| flag == "--format" && value == "agent" }
+    end
+
+    # In agent mode the failure is also on stdout, where the agent reads its answer.
+    def agent_failure(message, exit_code)
+      @out.print(Reporter::Agent.render(Reporter::Agent.failure(message, exit_code))) if agent?
+      exit_code
     end
 
     def run
       parser.parse!(@argv)
       use_explicit_sources
+      validate_run_options
+      warn_dirty_tree
+
+      return preview if options[:list_operators] || options[:dry_run]
 
-      arguments = { err: @err }
-      arguments[:digest] = options[:id] if options[:id]
-      report = Engine.new(config, **arguments).call
-      @err.puts
-      Reporter::Terminal.new(@out).call(report)
-      Reporter::Replay.new(@out).call(report) if options[:id]
-      write_json(report)
-      write_html(report)
-      exit_code(report)
+      execute_run
     rescue ConfigError => e
       @err.puts("saboteur: #{e.message}")
-      EXIT_USAGE
+      agent_failure(e.message, EXIT_USAGE)
     rescue Error => e
       @err.puts("saboteur: #{e.message}")
-      EXIT_TOOL
+      agent_failure(e.message, EXIT_TOOL)
+    end
+
+    # Mutants run your code, and a mutant of code that writes or deletes files
+    # can change the tree. Say so up front when uncommitted work is at stake.
+    def warn_dirty_tree
+      WorkingTree.new(config.root, ignored: config.output_paths).state.warning&.then { |text| @err.puts(text) }
+    end
+
+    # Usage errors found before the target boots.
+    def validate_run_options
+      reject_threshold_with_agent_format
+      Selection::GitDiff.verify_ref!(config["since"], root: config.root) if config["since"]
+    end
+
+    # Agent mode has one strict meaning for exit 0, so a score threshold cannot also decide it.
+    def reject_threshold_with_agent_format
+      return unless agent? && (config["threshold"] || gates.any?)
+
+      raise UsageError, "#{config['threshold'] ? '--threshold' : '--max-* gates'} cannot be combined with --agent"
+    end
+
+    # One line naming the reports written, paths relative to the root when
+    # they sit under it (a blank line before it, as the old JSON line had).
+    def announce_reports(reports)
+      written = reports.select { |path, _label| path }
+      return if written.empty?
+
+      root = File.join(File.realpath(config.root), "")
+      names = written.map do |path, label|
+        shown = File.expand_path(path).delete_prefix(root)
+        "#{shown} (#{label})"
+      end
+      @out.puts "\nReports: #{names.join(', ')}"
     end
 
     def doctor
       doctor_parser.parse!(@argv)
       raise UsageError, "unexpected arguments: #{@argv.join(' ')}" if @argv.any?
 
-      Doctor.new(config, out: @out).call
+      options[:tests]&.each { |test| require_existing_test(test) }
+      Doctor.new(config, out: @out, suite: options[:suite] || options.key?(:tests)).call
       EXIT_OK
     rescue ConfigError => e
       @err.puts("saboteur: #{e.message}")
@@ -126,67 +192,68 @@ module Saboteur
       EXIT_TOOL
     end
 
-    def write_json(report)
-      path = config.path("json_report")
-      return unless path
-
-      Reporter::Stryker.new(path).call(report)
-      @out.puts "\nJSON report: #{path}"
+    # Agent mode: stdout carries exactly one JSON payload. The target's own output (boot
+    # files, hooks, spec loading, child processes) goes to stderr while the engine runs.
+    # Descriptor 1 points at stderr for the block, so Kernel#puts, system and forked
+    # children cannot write into the JSON on stdout.
+    def stdout_on_stderr
+      saved = $stdout.dup
+      $stdout.reopen($stderr)
+      yield
+    ensure
+      $stdout.reopen(saved) if saved
+      saved&.close
     end
 
-    def write_html(report)
-      path = config.path("html_report")
-      return unless path
-
-      Reporter::Html.new(path).call(report)
-      @out.puts "HTML report: #{path}"
+    def agent_provenance(report, tree, engine)
+      Reporter::Agent::Provenance.new(
+        ref: config["since"], seed: report.seed, head: tree.head, working_tree: tree.label,
+        changed_files: tree.changed_files, mode: agent_mode, json_report: config.path("json_report"),
+        subjects: Array(config["subjects"]), tests: Array(engine.guessed_tests || options[:tests]),
+        sources: @sources || [],
+        config_path: options[:config], digest: options[:id], cache: config["cache"],
+        incremental: config["incremental"], settings: options.slice(*Reporter::Agent::Commands::SETTING_FLAGS.keys)
+      )
     end
 
-    def exit_code(report)
-      executed = report.executed
-      return EXIT_TOOL if executed.any? && executed.all? { |result| result.status == :error }
+    def agent_mode
+      return "replay" if options[:id]
+      return "diff" if config["since"]
 
-      return EXIT_TOOL if incomplete_under_threshold?(report)
-
-      failed_quality_gate?(report) ? EXIT_SURVIVORS : EXIT_OK
+      @sources&.any? ? "files" : "full"
     end
 
-    # With --threshold the score decides; without it any unignored survivor does.
-    def failed_quality_gate?(report)
-      threshold = config["threshold"]
-      return report.unignored_survivors.any? if threshold.nil?
-
-      score = report.score
-      return missing_score_reported? if score.nil?
-
-      score * 100 < threshold
-    end
+    # Writes the JSON report and returns its path, or nil when none is configured.
+    def write_json(report, cause)
+      path = config.path("json_report")
+      return unless path
 
-    # A gate that cannot measure a score must not pass: CI would go green
-    # on a run that tested nothing.
-    def missing_score_reported?
-      @err.puts("saboteur: no mutant was tested, so there is no score to compare with --threshold")
-      true
+      Reporter::Stryker.new(path).call(report, exit_cause: cause)
+      path
     end
 
-    # Errors and resource limits are outside the score. With a threshold they
-    # make the run incomplete, so the score alone cannot pass it.
-    def incomplete_under_threshold?(report)
-      return false if config["threshold"].nil?
+    def write_html(report)
+      path = config.path("html_report")
+      return unless path
 
-      count = report.counts.values_at(:error, :resource_limit).sum
-      @err.puts("saboteur: #{count} mutant(s) errored or hit a resource limit, so the score is incomplete") if
-        count.positive?
-      count.positive?
+      Reporter::Html.new(path).call(report)
+      path
     end
 
     # Positional arguments name the files (or directories) to mutate. They
     # replace the configured include and exclude patterns. Each must exist,
     # so a typo is an error and not a run over zero subjects.
     def use_explicit_sources
-      raise UsageError, "--test needs at least one source file" if options[:tests] && @argv.empty?
-      return if @argv.empty?
+      if @argv.empty?
+        raise UsageError, "--test needs at least one source file" if options[:tests] && !config["since"]
 
+        # With --since the changed files are the sources, so --test may
+        # stand alone; the files must still exist.
+        options[:tests]&.each { |test| require_existing_test(test) }
+        return
+      end
+
+      @sources = @argv.dup
       options[:include] = @argv.map { |source| source_pattern(source) }
       options[:exclude] = []
       options[:tests]&.each { |test| require_existing_test(test) }
@@ -212,10 +279,25 @@ module Saboteur
     end
 
     def overrides
-      options.except(:config, :id)
+      options.except(:config, :id, :suite, :list_operators, :dry_run)
+    end
+
+    def preview
+      raise UsageError, "--dry-run and --list-operators print text, not --agent JSON" if agent?
+      raise UsageError, "--id replays one mutant: not with --dry-run or --list-operators" if options[:id]
+
+      return MutationSource::OperatorRegistry.list(@out) || EXIT_OK if options[:list_operators]
+
+      Preview.new(config, out: @out, err: @err).call
+      EXIT_OK
     end
 
     def define_selection_options(opts)
+      opts.on("--operators NAMES", Array, "Choose operator names or tiers (core, extended, all)") do |v|
+        set(:operators, v)
+      end
+      opts.on("--list-operators", "List operator names, descriptions and tiers") { set(:list_operators, true) }
+      opts.on("--dry-run", "Preview mutants without boot, tests, forks or report writes") { set(:dry_run, true) }
       opts.on("--id DIGEST", "Replay exactly one current mutant by its full digest") { |v| set(:id, v) }
       opts.on("--since REF", "Only mutate subjects changed since git REF") { |v| options[:since] = v }
       opts.on("--subject EXPR", "Klass#meth, Klass.meth or a namespace; repeatable") { |v| add_subject(v) }
@@ -227,16 +309,41 @@ module Saboteur
       opts.on("--seed N", Integer, "Seed for Ruby's random numbers in every test run (default 1)") do |v|
         set(:seed, v)
       end
-      opts.on("--config PATH", "Config file (default .saboteur.yml)") { |v| set(:config, v) }
+      opts.on("--config PATH", "Config file (default config/saboteur.rb)") { |v| set(:config, v) }
       opts.on("--integration NAME", "Test adapter (rspec)") { |v| set(:integration, v) }
       opts.on("--reeval STRATEGY", Execution::Reevaluator::STRATEGIES, "class_eval or nesting") { |v| set(:reeval, v) }
       opts.on("--no-cache", "Rebuild the coverage map") { set(:cache, false) }
+      opts.on("--allow-hazardous", "Also run mutants inside destructive calls (rm_rf, system, ...)") do
+        set(:allow_hazardous, true)
+      end
+      opts.on("--fail-fast", "Stop after the first subject with a survivor (needs --jobs 1)") { set(:fail_fast, true) }
       opts.on("--incremental", "Reuse earlier verdicts whose inputs did not change") { set(:incremental, true) }
+      opts.on("--allow-focus", "Run even when a focus filter (fit, fdescribe, :focus) narrows the suite") do
+        set(:allow_focus, true)
+      end
+      opts.on("--[no-]guess-tests", "With --since: run only the specs named after the changed files " \
+                                    "(lib/a.rb -> spec/a_spec.rb); the whole suite if any has none") do |v|
+        set(:guess_tests, v)
+      end
+    end
+
+    def define_matrix_option(opts)
+      opts.on("--matrix", "Run every covering test per mutant and list blind and redundant tests") do
+        set(:matrix, true)
+      end
     end
 
     def define_output_options(opts)
+      opts.on("--score-history PATH", "Append score history JSONL (opt-in)") { |v| set(:score_history, v) }
       opts.on("--json PATH", "Stryker JSON report path") { |v| set(:json_report, v) }
       opts.on("--html PATH", "Self-contained HTML report path") { |v| set(:html_report, v) }
+      opts.on("--format FORMAT", %w[text agent], "text (default) or agent: one bounded JSON summary on stdout, " \
+                                                 "strict exit codes") { |v| @format = v }
+      opts.on("--agent", "Same as --format agent") { @format = "agent" }
+      opts.on("--verbose", "Text report: also print score split, timings and kill causes") { @verbose = true }
+      opts.on("--[no-]color", "Colour the text report (default: on for a terminal unless NO_COLOR is set)") do |v|
+        @color = v ? :always : :never
+      end
     end
 
     def define_explicit_file_options(opts)
@@ -246,6 +353,7 @@ module Saboteur
       opts.on("--threshold PERCENT", Float, "Exit 1 when the score is below PERCENT (0-100)") do |v|
         set(:threshold, v)
       end
+      Gates.define_options(opts) { |key, value| set(key, value) }
     end
 
     def add_subject(expr)

data/lib/saboteur/config.rb

@@ -1,13 +1,20 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
-require "yaml"
 require_relative "mutation_source/builtin"
+require_relative "mutation_source/operator_registry"
+require_relative "mutation_source/hazard_guard"
 
 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",
@@ -15,6 +22,11 @@ module Saboteur
       "include" => ["lib/**/*.rb"],
       "exclude" => [],
       "arid" => MutationSource::Builtin::DEFAULT_ARID,
+      "whole_file" => [],
+      "hazard" => MutationSource::HazardGuard::DEFAULT_HAZARD,
+      "allow_hazardous" => false,
+      "sandbox" => true, # true, false, or "strict": strict refuses to run without full Landlock
+      "sandbox_writable" => [],
       "timeout_factor" => 3.0,
       "timeout_min" => 5.0,
       "baseline_timeout" => 300.0,
@@ -23,45 +35,58 @@ module Saboteur
       "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"],
+      "operators" => [],
       "hooks" => [],
       "rails" => false,
       "reeval" => "nesting",
       "cache_dir" => ".saboteur",
       "json_report" => ".saboteur/report.json",
       "html_report" => ".saboteur/report.html",
+      "score_history" => nil,
       "rspec_args" => [],
       "subjects" => [],
       "since" => nil,
       "cache" => true,
       "incremental" => false,
+      "allow_focus" => false,
+      "fail_fast" => false,
+      "guess_tests" => false,
+      "matrix" => false,
       "seed" => 1,
       "tests" => [],
-      "threshold" => nil
+      "fingerprint_extra" => [],
+      "threshold" => nil,
+      "max_timeouts" => nil,
+      "max_errors" => nil
     }.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
     THRESHOLD_RANGE = (0.0..100.0)
 
-    LIST_KEYS = %w[require include exclude arid sources hooks rspec_args subjects tests].freeze
+    LIST_KEYS = %w[require include exclude arid hazard sources hooks rspec_args subjects tests
+                   fingerprint_extra sandbox_writable operators whole_file].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)
@@ -96,7 +121,7 @@ module Saboteur
       matched = self["include"].flat_map { |pattern| Dir.glob(pattern, base: root) }
       excluded = self["exclude"].flat_map { |pattern| Dir.glob(pattern, base: root) }
       (matched - excluded).select { |file| file.end_with?(".rb") }
-                          .map { |file| File.realpath(File.join(root, file)) }.uniq.sort
+                          .map { |file| File.realpath(File.expand_path(file, root)) }.uniq.sort
     end
 
     # Patterns that match no file. A pattern goes stale when files move;
@@ -112,6 +137,15 @@ module Saboteur
       value && File.expand_path(value, root)
     end
 
+    # Paths of saboteur's own output, relative to the root, that do not count as source changes.
+    def output_paths
+      prefix = File.join(File.realpath(root), "")
+      %w[cache_dir json_report html_report score_history].filter_map { |key| path(key) }
+                                                         .map { |file| File.expand_path(file) }
+                                                         .select { |file| file.start_with?(prefix) }
+                                                         .map { |file| file.delete_prefix(prefix) }
+    end
+
     private
 
     def coerce!
@@ -129,9 +163,39 @@ module Saboteur
 
     def validate_report_paths!
       json = path("json_report")
-      return unless json && json == path("html_report")
+      if json && json == path("html_report")
+        raise ConfigError, "json_report and html_report both point to #{json}; give each report its own path"
+      end
+
+      paths = %w[json_report html_report score_history].filter_map { |key| path(key) }
+      return if paths.uniq.size == paths.size
+
+      raise ConfigError, "json_report, html_report and score_history must have distinct paths"
+    end
+
+    def validate_modes!
+      validate_fail_fast!
+      validate_matrix!
+      validate_guess_tests!
+      validate_gates!
+    end
+
+    def validate_gates!
+      Gates::SETTINGS.each_key { |key| Gates.limit(self[key], key) }
+    end
+
+    def validate_fail_fast!
+      return unless self["fail_fast"] && self["jobs"] > 1
+
+      raise ConfigError, "fail_fast needs jobs 1: parallel workers have already started the other subjects"
+    end
+
+    # A reused verdict was computed by a run that stopped at the first
+    # failing test, so it lists too few killers for a matrix.
+    def validate_matrix!
+      return unless self["matrix"] && self["incremental"]
 
-      raise ConfigError, "json_report and html_report both point to #{json}; give each report its own path"
+      raise ConfigError, "matrix cannot be combined with incremental: reused verdicts list only the first killer"
     end
 
     def validate_threshold!
@@ -141,6 +205,13 @@ module Saboteur
       raise ConfigError, "threshold must be between 0 and 100"
     end
 
+    def validate_guess_tests!
+      return unless self["guess_tests"]
+
+      raise ConfigError, "guess_tests needs since" unless self["since"]
+      raise ConfigError, "guess_tests cannot be combined with tests" if self["tests"].any?
+    end
+
     def validate_reeval!
       raise ConfigError, "reeval must be one of: #{Execution::Reevaluator::STRATEGIES.join(', ')}" unless
         Execution::Reevaluator::STRATEGIES.include?(self["reeval"].to_s)
@@ -148,9 +219,13 @@ module Saboteur
 
     def validate!
       raise ConfigError, "jobs must be >= 1" if self["jobs"] < 1
+      unless [true, false, "strict"].include?(self["sandbox"])
+        raise ConfigError, 'sandbox must be true, false, or "strict"'
+      end
 
       validate_mutant_limit!
       validate_threshold!
+      validate_modes!
       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?
@@ -158,6 +233,11 @@ module Saboteur
       raise ConfigError, "timeout_min must be > 0" unless self["timeout_min"].positive?
 
       validate_reeval!
+      validate_operator_config!
+    end
+
+    def validate_operator_config!
+      MutationSource::OperatorRegistry.resolve(self["operators"])
 
       self["arid"].each { |pattern| Regexp.new(pattern) }
     rescue RegexpError => e
@@ -165,3 +245,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