saboteur 0.8.0 → 0.9.0

data/lib/saboteur/cli.rb

@@ -8,6 +8,7 @@ require_relative "doctor"
 require_relative "help"
 require_relative "reporter/replay"
 require_relative "baseline/command"
+require_relative "cli/error_cause"
 require_relative "cli/exit_status"
 require_relative "preview"
 require_relative "cli/run_reporting"
@@ -19,6 +20,20 @@ require_relative "cli/selection_options"
 require_relative "cli/presets"
 require_relative "cli/help_options"
 require_relative "cli/history_command"
+require_relative "cli/execution_options"
+require_relative "cli/matrix_option"
+require_relative "cli/output_options"
+require_relative "cli/explicit_file_options"
+require_relative "cli/doctor_command"
+require_relative "cli/agent_provenance"
+require_relative "cli/preview_command"
+require_relative "cli/help_command"
+require_relative "cli/run_validation"
+require_relative "cli/explicit_sources"
+require_relative "cli/run_output"
+require_relative "cli/dirty_tree_notice"
+require_relative "cli/run_command"
+require_relative "cli/failure_output"
 
 module Saboteur
   class CLI
@@ -32,7 +47,21 @@ module Saboteur
     include SelectionOptions
     include Presets
     include HistoryCommand
+    include ExecutionOptions
+    include MatrixOption
+    include OutputOptions
+    include ExplicitFileOptions
+    include DoctorCommand
+    include AgentProvenance
     include HelpOptions
+    include PreviewCommand
+    include HelpCommand
+    include RunValidation
+    include ExplicitSources
+    include RunOutput
+    include DirtyTreeNotice
+    include RunCommand
+    include FailureOutput
 
     USAGE = "Usage: saboteur run [SOURCE...] [--test TEST...] [--all] [--threshold PERCENT] [--since REF] " \
             "[--subject 'Klass#meth'] [--timeout-factor N] [--jobs N] [--seed N] [--id DIGEST]
@@ -96,319 +125,14 @@ module Saboteur
       end
     end
 
-    def doctor_parser
-      OptionParser.new do |opts|
-        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
-
-    def doctor_command = help_requested? ? show_help("doctor") : doctor
-
     def history_entry(command) = help_requested? ? show_help(command) : history_command(command)
 
-    def help_requested? = @argv.intersect?(%w[--help -h])
-
-    def show_help(command_name)
-      help = Help.new(option_lines: option_lines)
-      text = command_name ? help.command(command_name) : help.overview
-      return @out.puts(text) || EXIT_OK if text
-
-      @err.puts("unknown command: #{command_name}. Commands: #{help.command_names.join(', ')}")
-      EXIT_USAGE
-    end
-
-    def usage_error(message = nil)
-      @err.puts(message) if message
-      @err.puts(USAGE)
-      agent_failure(message || USAGE, EXIT_USAGE)
-    end
-
-    def agent? = @format == "agent"
-
     def agent_requested? = self.class.agent_requested?(@argv)
 
-    # 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)
-      reject_test_selection_conflicts
-      use_explicit_sources
-      validate_run_options
-      warn_dirty_tree
-
-      config.deprecation_warnings.each { |warning| @err.puts("saboteur: #{warning}") }
-
-      return preview if options[:list_operators] || options[:dry_run]
-
-      refuse_empty_source_set
-      refuse_empty_since_range
-      execute_run
-    rescue ConfigError => e
-      @err.puts("saboteur: #{e.message}")
-      agent_failure(e.message, EXIT_USAGE)
-    rescue Error => e
-      @err.puts("saboteur: #{e.message}")
-      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.
-    # The scope the warning names is the configured one: positional source
-    # operands narrow the run after the warning, so the include/exclude they
-    # imply stay out of its config (#309, #503 review).
-    def warn_dirty_tree
-      warning = @sources ? Config.load(path: options[:config], overrides: overrides.except(:include, :exclude)) : config
-      DirtyTreeWarning.for(warning, config_path: options[:config])&.then { |text| @err.puts(text) }
-    end
-
-    # Contradictory selection flags are a usage error before any file or
-    # repository check: --test wins over inference by precedence, but only
-    # one of them may be named. Config-file combinations are not errors:
-    # --test wins there, so generated commands stay valid over any config.
-    def reject_test_selection_conflicts
-      raise UsageError, "--all cannot be combined with --test" if options[:all] && options[:tests]&.any?
-
-      reject_test_command_conflicts
-      raise UsageError, "--all cannot be combined with --guess-tests" if options[:all] && options[:guess_tests]
-      return unless options[:guess_tests] && options[:tests]&.any?
-
-      raise UsageError, "--guess-tests cannot be combined with --test"
-    end
-
-    # --test-command replaces the whole in-process test machinery: test
-    # selection, coverage, parallelism and the sandbox do not apply.
-    def reject_test_command_conflicts
-      return unless options[:test_command]
-
-      # options[:tests] is nil or a non-empty list, so truthiness is the check.
-      raise UsageError, "--test-command cannot be combined with --test" if options[:tests]
-      raise UsageError, "--test-command cannot be combined with --incremental" if options[:incremental]
-    end
-
-    # Usage errors found before the target boots.
-    def validate_run_options
-      reject_format_conflicts
-      validate_shard_options
-      Selection::GitDiff.verify_ref!(config["since"], root: config.root) if config["since"]
-    end
-
-    # Agent mode allows no score gates (one strict exit 0); the json inventory is --dry-run planning only.
-    def reject_format_conflicts
-      if agent? && (config["threshold"] || gates.any?)
-        raise UsageError, "#{config['threshold'] ? '--threshold' : gates.agent_option_name} " \
-                          "cannot be combined with --agent"
-      end
-      return unless @format == "json" && !options[:dry_run]
-
-      raise UsageError, "--format json is the --dry-run mutant inventory; a run summary is --format 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)
-      return if (written = reports.select { |path, _label| path }).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?
-
-      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}")
-      EXIT_USAGE
-    rescue Error => e
-      @err.puts("saboteur: #{e.message}")
-      EXIT_TOOL
-    end
-
-    # 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 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 || config["tests"]),
-        sources: @sources || [],
-        config_path: options[:config], digest: options[:id], cache: config["cache"],
-        incremental: config["incremental"], settings: agent_settings, typed_settings: typed_settings
-      )
-    end
-
-    # The settings keys typed on the command line: a typed empty operator
-    # list may clear a config value, so the generated commands keep it.
-    def typed_settings = options.keys & Reporter::Agent::Commands::SETTING_FLAGS.keys
-
-    # A whole-suite run records its scope as --all, so the generated rerun
-    # and replay commands do not default back to inference (which can exit
-    # 2 in a project with a spec-less source file).
-    def agent_settings
-      settings = options.slice(*Reporter::Agent::Commands::SETTING_FLAGS.keys)
-                        .merge(operators: config["operators"], exclude_operators: config["exclude_operators"])
-      # The effective mode: named tests win over a configured whole-suite
-      # selection by precedence, so all is recorded only when no tests
-      # resolved - otherwise the follow-up commands would carry both --all
-      # and --test, which the CLI rejects.
-      settings[:all] = true if (config["all"] || config["test_selection"] == "all") && config["tests"].empty?
-      # CLI-only switches that change candidate availability or boot, so a
-      # printed rerun/replay must keep them (config-file settings like
-      # arid/hazard patterns, whole-file, require, rspec_args and rails ride
-      # along through --config or the default config path).
-      settings[:allow_hazardous] = true if options[:allow_hazardous]
-      settings[:allow_focus] = true if options[:allow_focus]
-      # An explicit false (--no-max-duration-ok over a config true) is a
-      # setting too: dropping it would silently re-enable the config value.
-      settings[:max_duration_ok] = options[:max_duration_ok] unless options[:max_duration_ok].nil?
-      settings
-    end
-
-    def agent_mode
-      return "replay" if options[:id]
-      return "diff" if config["since"]
-
-      @sources&.any? ? "files" : "full"
-    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
-      Selection::SourceScope.verify_no_specs!(@argv)
-      options[:tests]&.each { |test| require_existing_test(test) }
-      # --test may stand alone: the configured include (or the --since
-      # diff) names the sources. The files must still exist.
-      return if @argv.empty?
-
-      @sources = @argv.dup
-      options[:include] = @argv.map { |source| source_pattern(source) }
-      options[:exclude] = []
-    end
-
-    def source_pattern(source)
-      return "#{glob_escape(source.chomp('/'))}/**/*.rb" if File.directory?(source)
-      raise UsageError, "source is not a Ruby file: #{source}" if File.file?(source) && !source.end_with?(".rb")
-      raise UsageError, "source file not found: #{source}" unless File.file?(source)
-
-      glob_escape(source)
-    end
-
-    # include is a list of glob patterns; a named file must match only itself.
-    def glob_escape(path)
-      path.gsub(/[\\*?\[\]{}]/) { |character| "\\#{character}" }
-    end
-
-    # A test may carry an example selector: spec/a_spec.rb:12 or spec/a_spec.rb[1:2].
-    def require_existing_test(test)
-      path = test.sub(/(:\d+|\[[\d:,]+\])+\z/, "")
-      raise UsageError, "test file not found: #{test}" unless File.exist?(path)
-    end
-
     def overrides = options.except(:config, :id, :suite, :list_operators, :dry_run)
 
-    def preview
-      raise UsageError, "--dry-run and --list-operators print text, not --agent JSON; use --format json" if agent?
-      raise UsageError, "--id replays one mutant: not with --dry-run or --list-operators" if options[:id]
-
-      if options[:list_operators]
-        MutationSource::OperatorRegistry.list(@out, names: config["operators"], excluded: config["exclude_operators"])
-        return EXIT_OK
-      end
-
-      Preview.new(config, out: @out, err: @err, format: @format).call
-      EXIT_OK
-    end
-
-    def define_execution_options(opts)
-      opts.on("--timeout-factor N", Float, "Multiple of baseline runtime (default 3)") { |v| set(:timeout_factor, v) }
-      opts.on("--jobs N", Integer, "Concurrent workers (default 1)") { |v| set(:jobs, v) }
-      add_run_budget_options(opts)
-      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("--all", "Run the whole configured test suite instead of inferring the specs named after the " \
-                       "mutated files") { set(:all, true) }
-      opts.on("--test-command CMD", "Run CMD per mutant in the project root; exit 0 means the mutant survived. " \
-                                    "For apps that cannot load in this Ruby; much slower, serial, no coverage") do |v|
-        set(:test_command, v)
-      end
-      opts.on("--[no-]guess-tests", "Deprecated alias: inferred specs are already the default; " \
-                                    "--no-guess-tests warns and is ignored - use --all for the whole suite") 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 json], "text, agent or json (--dry-run inventory)") { |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;",
-              "a crash prints its backtrace") { @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)
-      opts.on("--test PATH", "Spec file or directory to run; repeatable. Replaces the configured spec paths") do |v|
-        (options[:tests] ||= []) << v
-      end
-      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) = (options[:subjects] ||= []) << expr
 
     def set(key, value) = (options[key] = value)

data/lib/saboteur/config.rb

@@ -18,6 +18,10 @@ module Saboteur
     LEGACY_IGNORE_FILE = ".saboteur-ignore.yml"
     IGNORE_FILE = "config/saboteur_ignore.rb"
 
+    # Settings that say where saboteur writes, never what it mutates: left
+    # out of the run fingerprint, baseline evidence and score-history scope.
+    OUTPUT_KEYS = %w[cache_dir json_report html_report score_history resume].freeze
+
     DEFAULTS = {
       "integration" => "rspec",
       "require" => [],
@@ -69,7 +73,15 @@ module Saboteur
       "subjects" => [],
       "since" => nil,
       "cache" => true,
+      # Experimental (#46): "shadow" also builds a partial coverage map after a
+      # cache miss and compares it with the full map, which the run still uses.
+      # "use" uses the partial map when it is safe and builds the full map otherwise.
+      "partial_coverage" => "off",
+      # coverage (default) reads Coverage around every test; trace gets lines and
+      # methods from a TracePoint and reads branches once per spec file (#725).
+      "coverage_recorder" => "coverage",
       "incremental" => false,
+      "resume" => nil,
       "shard" => nil,
       "allow_focus" => false,
       "fail_fast" => false,
@@ -79,6 +91,8 @@ module Saboteur
       "matrix" => false,
       "seed" => 1,
       "baseline_passes" => 2,
+      # Parallel children for the coverage-map build (#741); 1 keeps the single child.
+      "coverage_parts" => 1,
       "max_duration" => nil,
       "max_duration_ok" => false,
       "tests" => [],
@@ -86,11 +100,16 @@ module Saboteur
       "fingerprint_extra" => [],
       "threshold" => nil,
       "max_timeouts" => nil,
-      "max_errors" => nil
+      "max_errors" => nil,
+      # --verbose also lands here, so boot-time output filters (the rspec
+      # load-error report, #608) can keep their raw text behind the flag.
+      "verbose" => false
     }.freeze
 
-    INTEGER_KEYS = %w[jobs max_memory_mb max_processes max_mutants_per_method seed baseline_passes].freeze
+    INTEGER_KEYS = %w[jobs max_memory_mb max_processes max_mutants_per_method seed baseline_passes
+                      coverage_parts].freeze
     FLOAT_KEYS = %w[timeout_factor timeout_min baseline_timeout coverage_timeout].freeze
+    STRING_KEYS = %w[test_selection partial_coverage coverage_recorder].freeze
     NILABLE_FLOAT_KEYS = %w[threshold max_duration].freeze
     THRESHOLD_RANGE = (0.0..100.0)
 
@@ -212,10 +231,29 @@ module Saboteur
     # 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) }
+      OUTPUT_KEYS.filter_map { |key| path(key) }
+                 .select { |file| file.start_with?(prefix) }
+                 .map { |file| file.delete_prefix(prefix) }
+    end
+
+    # Tool-owned paths, relative to the root, that never count as
+    # working-tree changes (#638): the run's output, plus an in-repo
+    # BUNDLE_GEMFILE sidecar and its lock - the documented trial setup
+    # should not read as a dirty tree. Path-exact, never a glob, so a
+    # real untracked Gemfile.lock still counts.
+    def ignored_tree_paths(gemfile: ENV.fetch("BUNDLE_GEMFILE", nil))
+      prefix = File.join(File.realpath(root), "")
+      sidecar = gemfile && File.expand_path(gemfile, prefix)
+      begin
+        sidecar &&= File.join(File.realpath(File.dirname(sidecar)), File.basename(sidecar))
+      rescue SystemCallError
+        # The sidecar's directory does not exist; keep the expanded spelling.
+      end
+      paths = output_paths
+      if sidecar&.start_with?(prefix) && sidecar != File.join(prefix, "Gemfile")
+        paths.concat([sidecar, DirtyTreeWarning.lockfile_for(sidecar)].map { |file| file.delete_prefix(prefix) })
+      end
+      paths
     end
 
     private
@@ -236,11 +274,28 @@ module Saboteur
       FLOAT_KEYS.each { |key| @values[key] = Float(@values[key]) }
       LIST_KEYS.each { |key| @values[key] = Array(@values[key]).map(&:to_s) }
       NILABLE_FLOAT_KEYS.each { |key| @values[key] = Float(@values[key]) unless @values[key].nil? }
-      @values["test_selection"] = @values["test_selection"].to_s
+      STRING_KEYS.each { |key| @values[key] = @values[key].to_s }
     rescue ArgumentError, TypeError => e
       raise ConfigError, "invalid config value: #{e.message}"
     end
 
+    def validate_partial_coverage!
+      return if %w[off shadow use].include?(self["partial_coverage"])
+
+      raise ConfigError, "partial_coverage must be one of: off, shadow, use"
+    end
+
+    def validate_coverage_settings!
+      validate_partial_coverage!
+      validate_coverage_recorder!
+    end
+
+    def validate_coverage_recorder!
+      return if %w[coverage trace].include?(self["coverage_recorder"])
+
+      raise ConfigError, "coverage_recorder must be one of: coverage, trace"
+    end
+
     def validate_mutant_limit!
       raise ConfigError, "max_mutants_per_method must be > 0" unless self["max_mutants_per_method"].positive?
     end
@@ -249,6 +304,7 @@ module Saboteur
     def validate_baseline!
       raise ConfigError, "seed must be >= 0" if self["seed"].negative?
       raise ConfigError, "baseline_passes must be >= 1" if self["baseline_passes"] < 1
+      raise ConfigError, "coverage_parts must be >= 1" if self["coverage_parts"] < 1
       raise ConfigError, "max_duration must be > 0" if self["max_duration"] && !self["max_duration"].positive?
     end
 
@@ -267,6 +323,7 @@ module Saboteur
     def validate_modes!
       validate_fail_fast!
       validate_matrix!
+      validate_resume!
       validate_test_selection!
       validate_gates!
       validate_score_gates!
@@ -324,6 +381,17 @@ module Saboteur
       raise ConfigError, "matrix cannot be combined with incremental: reused verdicts list only the first killer"
     end
 
+    # --resume DIR keeps verdicts in DIR for a later run (#471); it reuses
+    # them the way --incremental does, so the same limits apply.
+    def validate_resume!
+      resume = self["resume"]
+      return if resume.nil?
+      raise ConfigError, "resume must be a non-blank directory path" unless resume.is_a?(String) && !resume.strip.empty?
+      return unless self["matrix"] || !self["test_command"].to_s.empty?
+
+      raise ConfigError, "resume cannot be combined with matrix or test_command: reused verdicts are not valid there"
+    end
+
     def validate_threshold!
       threshold = self["threshold"]
       return if threshold.nil? || THRESHOLD_RANGE.cover?(threshold)
@@ -373,6 +441,7 @@ module Saboteur
         raise ConfigError, "flaky_check must be one of: off, survivors, decisive"
       end
 
+      validate_coverage_settings!
       validate_mutant_limit!
       validate_threshold!
       validate_modes!

data/lib/saboteur/config_file.rb

@@ -9,29 +9,34 @@ module Saboteur
   # 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.
+    # unknown setting.
     class Settings
       def initialize
         @values = {}
-        @lines = {}
       end
 
-      attr_reader :values, :lines
+      attr_reader :values
 
-      Config::DEFAULTS.each_key do |key|
+      (Config::DEFAULTS.keys - ["integration"]).each do |key|
         define_method("#{key}=") do |value|
           @values[key] = value
-          @lines[key] = caller_locations(1, 1).first.lineno
         end
       end
 
+      def integration=(value)
+        line = caller_locations(1, 1).fetch(0).lineno
+        unless value.is_a?(String)
+          raise ConfigError, "#{line}: integration must be a String, got #{value.inspect}; use \"rspec\""
+        end
+
+        @values["integration"] = value
+      end
+
       # Repeatable per-path score gates (#473), the one setting that takes
       # arguments: c.score_gate "app/payments/**/*", min_score: 95. Values
       # are validated later, on the effective Config.
       def score_gate(pattern, min_score:)
         (@values["score_gates"] ||= []) << { "pattern" => pattern, "min_score" => min_score }
-        @lines["score_gates"] = caller_locations(1, 1).first.lineno
       end
 
       Config::INTEGER_KEYS.each do |key|
@@ -41,7 +46,6 @@ module Saboteur
             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

data/lib/saboteur/constant_subject_finder.rb

@@ -3,6 +3,7 @@
 
 require "prism"
 require_relative "subject"
+require_relative "deep_source"
 require_relative "constant_subject"
 
 module Saboteur
@@ -47,6 +48,8 @@ module Saboteur
       result = Prism.parse(source)
       return Parsed.new(subjects: [], unsupported: [], errors: result.errors.map(&:message)) if result.failure?
 
+      DeepSource.check!(result.value, file)
+
       ctx = { file: file, source: source, frozen: frozen_literals?(result) }
       out = { subjects: [], unsupported: [], ambiguous: [] }
       walk(result.value, [], out, **ctx)

data/lib/saboteur/custom_map.rb

@@ -64,15 +64,27 @@ module Saboteur
       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
 
+      numbered = key.is_a?(Regexp) && spec.match?(/\\\d/)
+      named = key.is_a?(Regexp) && spec.match?(/%[-0-9]*[<{][^>}]+[>}]|\\k</)
+      # Existence is deliberately not checked here: a stale or mistyped
+      # entry warns at guess time and the naming convention takes over,
+      # instead of the whole run dying at boot on one bad line (#640).
+      # The root check comes first: no template, backreference or named,
+      # may skip it (#712).
       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?
+      if numbered && named
+        raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}; " \
+                           'regex map specs support \1 backreferences only'
+      end
+      return if numbered # backreference filled in at match time
+      return unless named
 
-      raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}, which matches no file"
+      raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}; " \
+                         'regex map specs support \1 backreferences only'
     end
 
     private_class_method :validate_entry, :validate_spec
@@ -149,14 +161,14 @@ module Saboteur
       return :excluded if matches.all? { |entry, _| entry.specs.empty? }
 
       matches.reject { |entry, _| entry.specs.empty? }
-             .flat_map { |entry, match| resolve(entry, match) }
+             .flat_map { |entry, match| resolve(entry, match, file) }
     end
 
     def specificity(key)
       key.count("^*?[]{}\\")
     end
 
-    def resolve(entry, match)
+    def resolve(entry, match, file = nil)
       return :excluded if entry.specs.empty?
 
       specs = entry.specs
@@ -165,6 +177,13 @@ module Saboteur
         # 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?)
+        # A capture can carry "../" segments the template check never saw:
+        # refuse a filled spec that escapes the root (#712).
+        escaped = specs.reject { |spec| File.expand_path(spec, @root).start_with?("#{@root}/") }
+        if escaped.any?
+          raise ConfigError,
+                "#{entry.key.inspect} maps #{file} to #{escaped.first.inspect}, which is outside the project root"
+        end
       end
       specs
     end