saboteur 0.7.0 → 0.8.1

data/lib/saboteur/constant_reads.rb

@@ -0,0 +1,182 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "text"
+
+module Saboteur
+  # The lines where a constant is read, per file: the tests covering those
+  # lines are the ones that can observe a change to the constant's value
+  # (issue #306).
+  #
+  # Matching is lexical and honest about its edges. A bare `RULES` matches
+  # when its scope is the constant's owner or nested under it (constant
+  # lookup climbs lexical scopes) or the constant is top-level; a
+  # `Shop::RULES` path matches by its full spelling. A scope that writes its
+  # own `RULES` shadows the outer constant: reads under it resolve to the
+  # inner one and do not count. Reads reached through a superclass,
+  # `const_get`, or a compact `class Shop::Item` scope are not resolved: a
+  # constant only read that way finds no consumer here, and the run reports
+  # it as ran-at-load instead of guessing.
+  #
+  # Runtime reads (inside a def body) observe the constant when the mutant
+  # runs; load-time reads outside the constant's own file do not: the other
+  # file was loaded once with the original value and re-evaluating the
+  # constant's file does not run it again, so a read like
+  # `COPY = A::RULES` there keeps the original (#319). A capture inside a
+  # boot-time block (`1.times { COPY = A::RULES }`) is treated the same:
+  # statement-level blocks run while the file loads. That is a heuristic -
+  # a block passed to a deferring call (at_exit, define_method) runs later,
+  # but treating it as load-time errs toward dropping a constant rather
+  # than reporting a mutant nobody can observe.
+  module ConstantReads
+    Reads = Data.define(:runtime, :load, :defs)
+
+    module_function
+
+    # { "/abs/file.rb" => Reads } for the files that read the constant.
+    # runtime: def-body and block lines - a block runs when its caller runs
+    # it (an `it` block during the example), and line coverage decides
+    # whether any test reached it. load: top-level or class-body statement
+    # lines (observable only in the constant's own file, which the mutant
+    # re-evaluates). defs: the start line of each def a runtime read sits
+    # in, for the method-call counter fallback (endless defs have no line
+    # coverage). Only files whose text mentions the name are parsed.
+    def across(files, constant)
+      mention = /\b#{Regexp.escape(constant.name.to_s)}\b/
+      files.each_with_object({}) do |file, hits|
+        source = File.binread(file)
+        next unless mentions?(source, mention)
+
+        reads = reads_in(source, constant)
+        hits[file] = reads unless reads.runtime.empty? && reads.load.empty?
+      end
+    end
+
+    # The lines a mutant of the constant can be observed through: runtime
+    # reads everywhere, load reads in the constant's own file only.
+    def observable_lines(reads_by_file, constant)
+      reads_by_file.each_with_object({}) do |(file, reads), hits|
+        lines = reads.runtime.dup
+        lines.concat(reads.load) if file == constant.file
+        hits[file] = lines.uniq.sort unless lines.empty?
+      end
+    end
+
+    def mentions?(source, mention)
+      Text.utf8_identity(source).match?(mention)
+    rescue Encoding::CompatibilityError, ArgumentError
+      false
+    end
+
+    def reads_in(source, constant)
+      result = Prism.parse(source)
+      return Reads.new([], [], []) if result.failure?
+
+      out = { runtime: [], load: [], defs: [] }
+      walk(result.value, [], constant, out, in_def: nil, in_block: false, shadowed: nil)
+      Reads.new(out[:runtime].uniq.sort, out[:load].uniq.sort, out[:defs].uniq.sort)
+    end
+
+    def walk(node, nesting, constant, out, in_def:, in_block:, shadowed:, capture: false)
+      return if node.nil?
+
+      case node
+      when Prism::DefNode
+        walk(node.body, nesting, constant, out, in_def: node.location.start_line, in_block: false,
+                                                shadowed: shadowed)
+      when Prism::BlockNode, Prism::LambdaNode
+        walk(node.body, nesting, constant, out, in_def: in_def, in_block: true, capture: capture,
+                                                shadowed: shadowed)
+      when Prism::ConstantWriteNode, Prism::ConstantPathWriteNode
+        # A capture (`COPY = <expr>`): the value reads the constant once,
+        # when the write runs. Walk the value flagged as a capture so a
+        # boot-time block write (`1.times { COPY = A::RULES }`) lands in
+        # load, not runtime (#319).
+        walk(node.value, nesting, constant, out, in_def: in_def, in_block: in_block, capture: true,
+                                                 shadowed: shadowed)
+      when Prism::ConstantReadNode
+        record(node, out, in_def, in_block, capture) if !shadowed && bare_match?(node, nesting, constant)
+      when Prism::ConstantPathNode
+        # `Shop::RULES` holds no ConstantReadNode for RULES, only for Shop;
+        # match the path's full spelling.
+        record(node, out, in_def, in_block, capture) if node.slice.delete_prefix("::") == constant.id
+        walk_children(node, nesting, constant, out, in_def: in_def, in_block: in_block, capture: capture,
+                                                    shadowed: shadowed)
+      when Prism::ModuleNode, Prism::ClassNode, Prism::SingletonClassNode
+        walk_scope(node, nesting, constant, out, shadowed)
+      else
+        walk_children(node, nesting, constant, out, in_def: in_def, in_block: in_block, capture: capture,
+                                                    shadowed: shadowed)
+      end
+    end
+
+    # `class << self` joins the nesting as "<attached>.singleton_class",
+    # matching how ConstantSubjectFinder names that owner (#380); a non-self
+    # receiver or a top-level singleton has no static name and adds nothing.
+    # The shadow carries the path of the scope that set it. Entering the
+    # constant's owner scope lifts a shadow set outside it: the owner's
+    # own definition is lexically closer there (#395). A shadow set
+    # inside the owner subtree still binds below the nested scope that
+    # wrote the constant.
+    def walk_scope(node, nesting, constant, out, shadowed)
+      inner = scope_nesting(node, nesting)
+      path = inner.join("::")
+      scopes = [constant.owner.to_s]
+      shadowed = nil if shadowed && scopes.any? { |scope| path == scope || path.start_with?("#{scope}::") } &&
+                        scopes.none? { |scope| shadowed == scope || shadowed.start_with?("#{scope}::") }
+      shadowed = path if shadowed.nil? && path != scopes.first && writes_constant?(node.body, constant.name)
+      walk(node.body, inner, constant, out, in_def: nil, in_block: false, shadowed: shadowed)
+    end
+
+    def scope_nesting(node, nesting)
+      return nesting + [node.constant_path.slice.delete_prefix("::")] unless node.is_a?(Prism::SingletonClassNode)
+      return nesting unless node.expression.is_a?(Prism::SelfNode) && nesting.any?
+
+      nesting[0...-1] + ["#{nesting.last}.singleton_class"]
+    end
+
+    def walk_children(node, nesting, constant, out, in_def:, in_block:, capture:, shadowed:)
+      node.compact_child_nodes.each do |child|
+        walk(child, nesting, constant, out, in_def: in_def, in_block: in_block, capture: capture,
+                                            shadowed: shadowed)
+      end
+    end
+
+    def record(node, out, in_def, in_block, capture)
+      line = node.location.start_line
+      if in_def
+        out[:runtime] << line
+        out[:defs] << in_def
+      elsif in_block && !capture
+        out[:runtime] << line
+      else
+        # A bare statement read, or a capture in a boot-time block: both
+        # resolved while the file loaded, with the original value.
+        out[:load] << line
+      end
+    end
+
+    # A bare `RULES` reads this constant when the read's scope is the
+    # constant's owner (or its singleton scope, whose ancestry reaches the
+    # attached class) or nested under either, or it is top-level (#380).
+    def bare_match?(node, nesting, constant)
+      return false unless node.name == constant.name
+      return true if constant.owner.nil?
+
+      path = nesting.join("::")
+      [constant.owner, "#{constant.owner}.singleton_class"].any? do |scope|
+        path == scope || path.start_with?("#{scope}::")
+      end
+    end
+
+    # True when the scope body assigns the constant name at its own level
+    # (not inside a nested def or scope).
+    def writes_constant?(body, name)
+      statements = body&.body || []
+      statements.any? do |statement|
+        statement.is_a?(Prism::ConstantWriteNode) && statement.name == name
+      end
+    end
+  end
+end

data/lib/saboteur/constant_subject.rb

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "subject"
+
+module Saboteur
+  # A constant assigned a hash or array literal, as a mutation subject
+  # (issue #306): `RULES = { ... }` or `TAGS = [ ... ]`, with an optional
+  # trailing `.freeze`. Only --since selection creates these (see
+  # Engine::SubjectSelection), and the diff scope narrows their mutants to
+  # the entries the diff changed.
+  #
+  # A constant is not a method, so the surgical def re-evaluation does not
+  # apply: mutants run by re-evaluating the whole file with the mutated
+  # assignment spliced in (Execution::Reevaluator#eval_whole_file, which
+  # silences the "already initialized constant" warning). Re-evaluation
+  # replaces the constant's object; code that reads the constant at test
+  # time sees the mutant, while anything that copied the old object at load
+  # time keeps it. consumer_lines names the reads a test can cover; the
+  # coverage map turns them into the mutant's tests.
+  class ConstantSubject < Subject
+    attr_reader :literal_node
+    # { "/abs/file.rb" => [lines reading the constant] } across the include
+    # set, filled in after selection (the finder sees one file at a time).
+    attr_accessor :consumer_lines
+    # { "/abs/file.rb" => [def start lines] }: the def each runtime read
+    # sits in, for the method-call counter fallback (endless defs have no
+    # line coverage).
+    attr_accessor :consumer_defs
+
+    def initialize(name:, owner:, file:, node:, literal_node:, file_source:, nesting:, frozen_literals:,
+                   consumer_lines: {}, consumer_defs: {})
+      super(name:, owner:, singleton: false, sclass: false, file:, node:, file_source:, nesting:,
+            frozen_literals:, sig_span: nil)
+      @literal_node = literal_node
+      @consumer_lines = consumer_lines
+      @consumer_defs = consumer_defs
+    end
+
+    # "Shop::RULES", or "RULES" at the top level. The :: separator keeps a
+    # constant's id apart from the Klass#method and Klass.method spellings.
+    def id
+      owner ? "#{owner}::#{name}" : name.to_s
+    end
+
+    # There is no method body to redefine: constants always take the
+    # whole-file evaluation path.
+    def whole_file_only?
+      true
+    end
+
+    # The assignment runs while the file loads, so its lines carry the load
+    # evidence; the reads of the constant in this file are the lines tests
+    # can cover.
+    def coverage_lines
+      ((start_line..end_line).to_a + Array(consumer_lines[file])).uniq
+    end
+
+    # Every edit sits inside the literal and is observable wherever the
+    # constant is read, so the assignment's own lines are the evidence that
+    # the edit ran (they execute at load, never inside a test).
+    def coverage_lines_for(_edit)
+      (start_line..end_line).to_a
+    end
+
+    def recovers?
+      false
+    end
+  end
+end

data/lib/saboteur/constant_subject_finder.rb

@@ -0,0 +1,281 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "subject"
+require_relative "constant_subject"
+
+module Saboteur
+  # Finds constant assignments of hash and array literals - `RULES = { ... }`,
+  # `TAGS = [ ... ]`, with a trailing `.freeze` or a similar argument-free,
+  # block-free call - as mutation subjects for --since runs (issue #306).
+  #
+  # Unsupported forms are reported with a reason, never silently skipped: a
+  # namespaced target (`A::RULES = ...`), a conditional write
+  # (`RULES ||= ...`), and a non-literal value (a method call with
+  # arguments, another constant). Class factories (`Point = Data.define(...)`)
+  # are scopes, not data: they are reported neither way, and a constant
+  # inside the factory's block binds on the enclosing lexical scope, never
+  # on the class the factory builds (#352, mirroring SubjectFinder).
+  # Constants inside any other block are found but marked skipped, like
+  # SubjectFinder's defs, so the report names them.
+  class ConstantSubjectFinder
+    Parsed = Data.define(:subjects, :unsupported, :errors)
+
+    # A constant assignment saboteur cannot mutate, with the reason why.
+    Unsupported = Data.define(:name, :owner, :file, :node, :reason) do
+      def id
+        owner ? "#{owner}::#{name}" : name.to_s
+      end
+
+      def overlaps_lines?(lines)
+        first = node.location.start_line
+        last = node.location.end_line
+        if lines.is_a?(Range)
+          lines.begin <= last && first <= lines.end
+        else
+          lines.any? { |line| line.between?(first, last) }
+        end
+      end
+    end
+
+    CLASS_FACTORIES = SubjectFinder::CLASS_FACTORIES
+
+    # source: the text to parse when it is not the file on disk (the file as
+    # it was at an earlier commit).
+    def call(file, source: File.binread(file))
+      result = Prism.parse(source)
+      return Parsed.new(subjects: [], unsupported: [], errors: result.errors.map(&:message)) if result.failure?
+
+      ctx = { file: file, source: source, frozen: frozen_literals?(result) }
+      out = { subjects: [], unsupported: [], ambiguous: [] }
+      walk(result.value, [], out, **ctx)
+      reject_duplicates(out, **ctx)
+      demote_ambiguous(out, **ctx)
+      Parsed.new(subjects: out[:subjects], unsupported: out[:unsupported], errors: [])
+    end
+
+    private
+
+    # More than one write of the same constant in one file: re-evaluating
+    # the file runs them all, the later one always wins, and a mutant of
+    # any earlier literal is never observed. EVERY write counts - a guarded
+    # or non-literal second write (`RULES = {a: 1}; RULES = build_rules`)
+    # overwrites the first just the same (#319).
+    def reject_duplicates(out, **ctx)
+      writes = Hash.new(0)
+      (out[:subjects] + out[:unsupported]).each { |entry| writes[entry.id] += 1 }
+      duplicates = out[:subjects].select { |subject| writes[subject.id] > 1 }
+      return if duplicates.empty?
+
+      out[:subjects] -= duplicates
+      duplicates.each do |subject|
+        out[:unsupported] << Unsupported.new(name: subject.name, owner: subject.owner, file: ctx[:file],
+                                             node: subject.node,
+                                             reason: "assigned more than once in this file")
+      end
+    end
+
+    def frozen_literals?(result)
+      result.magic_comments.any? do |comment|
+        comment.key.tr("-", "_").casecmp?("frozen_string_literal") && comment.value.casecmp?("true")
+      end
+    end
+
+    def walk(node, nesting, out, **ctx)
+      return if node.nil?
+
+      case node
+      when Prism::BlockNode, Prism::LambdaNode
+        walk(node.body, nesting, out, **ctx, in_block: true)
+      when Prism::ConstantWriteNode
+        constant_assignment(node, nesting, out, **ctx)
+      when Prism::IfNode, Prism::UnlessNode
+        walk_conditional(node, nesting, out, **ctx)
+      when Prism::ConstantOrWriteNode, Prism::ConstantAndWriteNode
+        record_unsupported(out, node, nesting, "a conditional assignment (#{node.operator_loc.slice})", **ctx)
+        walk_children(node, nesting, out, **ctx)
+      when Prism::ConstantPathWriteNode, Prism::ConstantPathOrWriteNode, Prism::ConstantPathAndWriteNode
+        record_unsupported(out, node, nesting, "a namespaced target (#{node.target.slice})", **ctx)
+        walk_children(node, nesting, out, **ctx)
+      # A keyword class or module re-enters the lexical scope: its constants
+      # are ordinary subjects even inside a block, and factory scopes never
+      # join their paths (#352).
+      when Prism::ModuleNode, Prism::ClassNode
+        kind = node.is_a?(Prism::ModuleNode) ? :module : :class
+        scope = Scope.new(kind: kind, path: node.constant_path.slice)
+        walk(node.body, lexical_nesting(nesting) + [scope], out, **ctx, in_block: false)
+      when Prism::SingletonClassNode
+        walk_singleton_class(node, nesting, out, **ctx)
+      else
+        walk_children(node, nesting, out, **ctx)
+      end
+    end
+
+    # A write under a condition may never run: mutating its literal cannot
+    # change the constant when the guard skips the write (#319).
+    def walk_conditional(node, nesting, out, **ctx)
+      walk(node.predicate, nesting, out, **ctx)
+      walk(node.statements, nesting, out, **ctx, guarded: true)
+      walk(node.respond_to?(:subsequent) ? node.subsequent : node.else_clause, nesting, out, **ctx,
+           guarded: true)
+    end
+
+    def walk_children(node, nesting, out, **ctx)
+      node.compact_child_nodes.each { |child| walk(child, nesting, out, **ctx) }
+    end
+
+    # `class << self` opens the attached class's singleton scope: constants
+    # assigned there bind on the singleton class, so the scope joins the
+    # nesting and owner_path renders it "<attached>.singleton_class" (#380,
+    # mirroring SubjectFinder). Unlike a keyword class, `class << self`
+    # does not reset in_block: a block's runtime self is unknowable at
+    # parse time (an `included do` block runs with the including class as
+    # self), so its constants stay conservatively skipped inside a block.
+    # A non-self receiver, a nested singleton class or the top level has no
+    # statically nameable singleton: the enclosing nesting stays.
+    def walk_singleton_class(node, nesting, out, **ctx)
+      unless node.expression.is_a?(Prism::SelfNode) && nesting.any? && !nesting.last.sclass?
+        return walk_children(node, nesting, out, **ctx)
+      end
+
+      walk(node.body, nesting + [Scope.new(kind: :sclass, path: "self")], out, **ctx)
+    end
+
+    def constant_assignment(node, nesting, out, **ctx)
+      return walk_factory(node, nesting, out, **ctx) if factory_scope?(node)
+
+      literal = literal_value(node.value)
+      reason = unsupported_reason(node, literal, **ctx)
+      if reason
+        record_unsupported(out, node, nesting, reason, **ctx)
+        walk_children(node, nesting, out, **ctx)
+        return
+      end
+
+      subject = ConstantSubject.new(name: node.name, owner: owner_path(nesting), file: ctx[:file], node: node,
+                                    literal_node: literal, file_source: ctx[:source], nesting: nesting,
+                                    frozen_literals: ctx[:frozen])
+      subject.skip_reason = "defined inside a block" if ctx[:in_block]
+      out[:subjects] << subject
+      # Another constant can hide in the literal's values (`MAP = { x: (Y = []) }`).
+      walk_children(node, nesting, out, **ctx)
+    end
+
+    # `Point = Data.define(:x) do ... end`: the receiver and arguments stay
+    # in the enclosing scope. The block's body is walked directly, not as a
+    # block, and the factory opens no lexical constant scope: a constant
+    # inside the block binds on the enclosing lexical scope and is an
+    # ordinary subject (#352, mirroring SubjectFinder).
+    def walk_factory(node, nesting, out, **ctx)
+      call = node.value
+      (call.compact_child_nodes - [call.block]).each { |child| walk(child, nesting, out, **ctx) }
+      walk(call.block.body, lexical_nesting(nesting) + [Scope.new(kind: :factory, path: node.name.to_s)], out, **ctx)
+    end
+
+    # A factory scope names the class being built but opens no lexical
+    # constant scope, so it never joins a constant's path (#339).
+    def lexical_nesting(nesting)
+      nesting.reject(&:factory?)
+    end
+
+    def unsupported_reason(_node, literal, guarded: false, **)
+      return "guarded by a condition" if guarded
+      return "its value is not a hash or array literal" if literal.nil?
+
+      nil
+    end
+
+    # `Point = Data.define(...) do ... end`: only the four core factories
+    # count, called on the bare constant (mirrors SubjectFinder).
+    def factory_scope?(node)
+      call = node.value
+      return false unless call.is_a?(Prism::CallNode) && call.block.is_a?(Prism::BlockNode)
+      return false unless call.receiver.is_a?(Prism::ConstantReadNode)
+
+      CLASS_FACTORIES[call.receiver.name] == call.name
+    end
+
+    # The hash or array literal behind the value, looking through `.freeze`
+    # calls only: any other receiver chain transforms the value, so the
+    # literal is not what the constant holds.
+    def literal_value(value)
+      value = value.receiver while value.is_a?(Prism::CallNode) && value.name == :freeze &&
+                                   value.arguments.nil? && value.block.nil? && value.receiver
+      value if value.is_a?(Prism::HashNode) || value.is_a?(Prism::ArrayNode)
+    end
+
+    def record_unsupported(out, node, nesting, reason, **ctx)
+      # A bare target takes the lexical owner. A ROOTED qualified target names
+      # its constant absolutely ("::RULES" is RULES anywhere). An UNROOTED one
+      # resolves through the lexical scope: "Shop::RULES" inside
+      # `module Outer; module Shop` writes Outer::Shop::RULES. Every id on the
+      # write's scope chain is a candidate, so each goes on the ambiguous list
+      # for demotion after the walk; over-matching only demotes a subject.
+      if node.respond_to?(:name)
+        name = node.name
+        owner = owner_path(nesting)
+      else
+        name = node.target.slice.sub(/\A::/, "")
+        owner = nil
+        unless node.target.slice.start_with?("::")
+          nesting.length.downto(0) do |depth|
+            prefix = owner_path(nesting[0...depth])
+            out[:ambiguous] << (prefix ? "#{prefix}::#{name}" : name)
+          end
+        end
+      end
+      out[:unsupported] << Unsupported.new(name: name, owner: owner, file: ctx[:file],
+                                           node: node, reason: reason)
+    end
+
+    # A subject whose id an unrooted qualified write may resolve to cannot be
+    # mutated safely: replaying the file lets that write overwrite it.
+    def demote_ambiguous(out, **ctx)
+      return if out[:ambiguous].empty?
+
+      poisoned = out[:subjects].select { |subject| out[:ambiguous].include?(subject.id) }
+      out[:subjects] -= poisoned
+      poisoned.each do |subject|
+        out[:unsupported] << Unsupported.new(name: subject.name, owner: subject.owner, file: ctx[:file],
+                                             node: subject.node,
+                                             reason: "an unrooted qualified write may overwrite it")
+      end
+    end
+
+    # Lexical path of the enclosing class/module, or nil at the top level.
+    # A singleton-class scope renders as "<attached>.singleton_class":
+    # constants assigned in `class << self` bind on the singleton class,
+    # not on the attached class (#380). Factory scopes open no lexical
+    # constant scope, but a factory's block is class_eval'd, so a `class <<
+    # self` directly inside one attaches to the factory's class.
+    def owner_path(nesting)
+      return nil if nesting.empty?
+
+      parts = []
+      factory_path = nil
+      nesting.each do |scope|
+        if scope.sclass?
+          # `self` is the innermost named scope: the factory's class inside a
+          # factory block (its block is class_eval'd), the attached class or
+          # module otherwise.
+          if factory_path
+            # factory_path carries the full prefix already: replace, never
+            # append, or the enclosing scope doubles (#395).
+            parts = ["#{factory_path}.singleton_class"]
+          elsif parts.any?
+            parts[-1] = "#{parts.last}.singleton_class"
+          end
+          factory_path = nil
+        elsif scope.factory?
+          factory_path = (parts + [scope.path.delete_prefix("::")]).join("::")
+        else
+          parts.clear if scope.path.start_with?("::")
+          parts << scope.path.delete_prefix("::")
+          factory_path = nil
+        end
+      end
+      parts.empty? ? nil : parts.join("::")
+    end
+  end
+end

data/lib/saboteur/coverage_reads.rb

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  # Every Coverage.result read goes through here. With the methods report
+  # on, the C call hashes each method owner and trusts the return type, so
+  # a loaded class whose `hash` does not return an Integer (forem's
+  # ReactionCategory, #564) makes every read raise TypeError - a "please
+  # report it" crash for what is a bug in the application's code. Refuse
+  # instead. The handler runs no app code (an ObjectSpace scan would call
+  # #hash/#name on hostile classes) and the error's backtrace names no
+  # owning class, so the message stays generic rather than accusing one.
+  module CoverageReads
+    module_function
+
+    def result(stop:, clear:)
+      Coverage.result(stop:, clear:)
+    rescue TypeError => e
+      raise Error, diagnostic(e)
+    end
+
+    def diagnostic(error)
+      "Coverage.result raised TypeError (#{error.message}): Coverage's method report hashes every " \
+        "method owner and trusts the result, and a loaded class whose #hash does not return an " \
+        "Integer (Ruby's #hash contract) breaks it. This is a bug in the application's code, " \
+        "not in saboteur."
+    end
+  end
+end

data/lib/saboteur/custom_map.rb

@@ -64,7 +64,14 @@ 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</)
+      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
 
       expanded = File.expand_path(spec, root)
       unless expanded.start_with?("#{root}/")
@@ -72,6 +79,10 @@ module Saboteur
       end
       return if Dir.glob(expanded).any?
 
+      if named
+        raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}; " \
+                           'regex map specs support \1 backreferences only'
+      end
       raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}, which matches no file"
     end