saboteur 0.3.0 → 0.4.0

data/lib/saboteur/agent_skill.rb

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  # The instructions for an AI coding agent, printed by `saboteur agent-skill`.
+  # Paste them into AGENTS.md or CLAUDE.md. docs/agent-skill.md carries the same
+  # block; a spec keeps the two equal.
+  module AgentSkill
+    TEXT = <<~MARKDOWN
+      ## Mutation testing with saboteur
+
+      After you change covered Ruby behavior or its specs, and RSpec is green, run saboteur
+      on your diff before you say the work is done:
+
+      ```
+      saboteur run --agent --since origin/main
+      ```
+
+      Read the JSON on stdout. `status` is `complete`, `partial` or `not_applicable`.
+      The exit code is strict: 0 means complete and clean, 1 means a survivor needs
+      review, 2 means a bad command or config, 3 means the run was incomplete or failed.
+
+      When a mutant survives:
+
+      1. Pick one live survivor from `findings.shown`.
+      2. Add the smallest test that checks the observable behavior the mutant changed.
+      3. Replay it with the command in `next.replay` (it uses the recorded seed) and
+         confirm the mutant is now killed.
+      4. Run the diff again. Repeat until the exit code is 0.
+
+      Rules:
+
+      - Report `partial` and `not_applicable` results as they are. Say what had no
+        coverage or was capped; do not call an incomplete run clean.
+      - Never change production behavior only to kill a mutant.
+      - Never add survivors to the ignore list yourself. Ask the owner.
+      - Run `saboteur help` for every command, option and exit code.
+    MARKDOWN
+  end
+end

data/lib/saboteur/cli.rb

@@ -18,7 +18,6 @@ module Saboteur
     EXIT_SURVIVORS = 1
     EXIT_USAGE = 2
     EXIT_TOOL = 3
-
     class UsageError < ConfigError; end
 
     attr_reader :options
@@ -28,6 +27,7 @@ module Saboteur
       @out = out
       @err = err
       @options = {}
+      @format = "agent" if agent_requested?
     end
 
     def call
@@ -36,6 +36,7 @@ module Saboteur
       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
@@ -65,7 +66,7 @@ module Saboteur
     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.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) }
       end
     end
@@ -88,28 +89,61 @@ 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
+      reject_threshold_with_agent_format
 
       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)
+      agent? ? agent_run(arguments) : text_run(Engine.new(config, **arguments).call)
     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
+
+    # 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"]
+
+      raise UsageError, "--threshold cannot be combined with --agent: agent mode exits 0 only for a complete, clean run"
+    end
+
+    def text_run(report)
+      @err.puts
+      Reporter::Terminal.new(@out).call(report)
+      Reporter::Replay.new(@out).call(report) if options[:id]
+      code = exit_code(report)
+      # The JSON carries the exit cause an outer harness trusts, so it is
+      # the completion evidence for the whole run: write it only after
+      # every other fallible reporting stage, or a late failure would
+      # leave a fresh, misleading report behind.
+      write_html(report)
+      write_json(report, exit_cause(report, code))
+      code
     end
 
     def doctor
@@ -126,31 +160,115 @@ module Saboteur
       EXIT_TOOL
     end
 
-    def write_json(report)
+    # 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.
+    def agent_run(arguments)
+      tree = WorkingTree.new(config.root, ignored: output_paths).state
+      report = stdout_on_stderr { Engine.new(config, **arguments).call }
+      payload = Reporter::Agent.call(report, agent_provenance(report, tree))
+      rendered = Reporter::Agent.render(payload)
+      # Same publish order as text_run: the JSON is the completion
+      # evidence, so it is written only after every other fallible stage,
+      # including the agent payload itself.
+      write_html(report, announce: false)
+      write_json(report, agent_exit_cause(report, payload), announce: false)
+      @out.print(rendered)
+      Reporter::Agent.exit_code(payload)
+    end
+
+    # Paths of saboteur's own output, relative to the root, that do not count as source changes.
+    def output_paths
+      root = File.join(File.realpath(config.root), "")
+      %w[cache_dir json_report html_report].filter_map { |key| config.path(key) }
+                                           .map { |path| File.expand_path(path) }
+                                           .select { |path| path.start_with?(root) }
+                                           .map { |path| path.delete_prefix(root) }
+    end
+
+    # 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 agent_provenance(report, tree)
+      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(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 agent_mode
+      return "replay" if options[:id]
+      return "diff" if config["since"]
+
+      @sources&.any? ? "files" : "full"
+    end
+
+    def write_json(report, cause, announce: true)
       path = config.path("json_report")
       return unless path
 
-      Reporter::Stryker.new(path).call(report)
-      @out.puts "\nJSON report: #{path}"
+      Reporter::Stryker.new(path).call(report, exit_cause: cause)
+      @out.puts "\nJSON report: #{path}" if announce
     end
 
-    def write_html(report)
+    def write_html(report, announce: true)
       path = config.path("html_report")
       return unless path
 
       Reporter::Html.new(path).call(report)
-      @out.puts "HTML report: #{path}"
+      @out.puts "HTML report: #{path}" if announce
     end
 
     def exit_code(report)
-      executed = report.executed
-      return EXIT_TOOL if executed.any? && executed.all? { |result| result.status == :error }
+      return EXIT_TOOL if mostly_errored?(report)
 
       return EXIT_TOOL if incomplete_under_threshold?(report)
 
       failed_quality_gate?(report) ? EXIT_SURVIVORS : EXIT_OK
     end
 
+    def mostly_errored?(report)
+      return false unless report.majority_errored?
+
+      executed = report.executed
+      errors = executed.count { |result| result.status == :error }
+      @err.puts("saboteur: #{errors} of #{executed.size} mutants errored, so the run tested almost nothing; " \
+                "fix the errors and run again")
+      true
+    end
+
+    # Agent mode: the recorded cause is the payload's own verdict, so the
+    # JSON and the process exit classify the run the same way. An
+    # incomplete run that mostly errored keeps its distinct cause, so the
+    # harness rule means the same thing in both modes.
+    def agent_exit_cause(report, payload)
+      case payload[:verdict]
+      when "clean" then "ok"
+      when "survivors" then "survivors"
+      else report.majority_errored? ? "errorMajority" : "incomplete"
+      end
+    end
+
+    # Why the run exits the way it does, recorded in the JSON report so an
+    # outer harness can tell "most mutants errored" from the other exit 3s.
+    def exit_cause(report, code)
+      case code
+      when EXIT_OK then "ok"
+      when EXIT_SURVIVORS then config["threshold"].nil? ? "survivors" : "belowThreshold"
+      else report.majority_errored? ? "errorMajority" : "incompleteUnderThreshold"
+      end
+    end
+
     # With --threshold the score decides; without it any unignored survivor does.
     def failed_quality_gate?(report)
       threshold = config["threshold"]
@@ -184,9 +302,16 @@ module Saboteur
     # 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) }
@@ -227,7 +352,7 @@ 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) }
@@ -237,6 +362,9 @@ module Saboteur
     def define_output_options(opts)
       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" }
     end
 
     def define_explicit_file_options(opts)

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",
@@ -23,7 +28,8 @@ 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"],
       "hooks" => [],
       "rails" => false,
@@ -38,6 +44,7 @@ module Saboteur
       "incremental" => false,
       "seed" => 1,
       "tests" => [],
+      "fingerprint_extra" => [],
       "threshold" => nil
     }.freeze
 
@@ -45,23 +52,26 @@ module Saboteur
     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 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)
@@ -165,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

@@ -17,6 +17,7 @@ module Saboteur
       check_runtime
       check_coverage
       check_boot_files
+      check_custom_map
       hooks = Hooks.new
       integration = boot_target(hooks)
       @out.puts "Integration: #{@config['integration']} (loaded)"
@@ -57,11 +58,26 @@ module Saboteur
                    "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 .saboteur.yml" unless File.file?(path)
+          raise ConfigError, "#{key} file missing: #{file}; fix config/saboteur.rb" unless File.file?(path)
 
           @out.puts "#{key}: #{file} (found)"
         end