saboteur 0.7.0 → 0.8.1

data/lib/saboteur/dirty_tree_warning.rb

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  # The warning shown before a run on a tree with uncommitted
+  # changes (#309, #316); the headline says uncommitted or untracked, so a
+  # tree of only scratch files is not read as edits (#604). Mutants run your code and can change the tree, so the
+  # warning stays; it splits the raw count so a tree full of notes or trial
+  # setup files does not read like application edits about to be mutated.
+  #
+  # Each change lands in exactly one group, so the groups add up to the
+  # count: saboteur setup files first (the config file the run reads, a
+  # trial Gemfile and its lock), then the mutation scope (a file the
+  # configured include and exclude select, the way Config#included_files
+  # does), then the rest. A path the patterns match also counts, so a
+  # deleted source is still inside the scope. The scope is the configured
+  # one: --since, --subject and source operands narrow a run further, after
+  # this warning.
+  class DirtyTreeWarning
+    SHOWN_PATHS = 5
+    MATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+    ADVICE = "Mutants run your code and could alter or delete files; " \
+             "run on a clean, committed tree or a CI checkout."
+
+    # The warning text for the run's working tree, or nil on a clean or
+    # unknown tree. The root is physical (realpath), like the paths
+    # Config#included_files returns.
+    def self.for(config, config_path:, gemfile: ENV.fetch("BUNDLE_GEMFILE", nil))
+      state = WorkingTree.new(config.root, ignored: config.output_paths).state
+      root = File.realpath(config.root)
+      new(state, included: relative(config.included_files, root), include: config["include"],
+                 exclude: config["exclude"], root: root,
+                 setup_files: setup_files(root, config_path: config_path, gemfile: gemfile)).to_s
+    end
+
+    # Files a trial of saboteur adds, relative to the root: the config file
+    # the run reads and, when BUNDLE_GEMFILE names a Gemfile other than the
+    # root's own, that Gemfile and its lock. Each file is compared by its
+    # physical path, so a /var spelling of a /private/var root still
+    # matches (#503).
+    def self.setup_files(root, config_path:, gemfile:)
+      files = [physical(File.expand_path(config_path || Config::FILE, root))]
+      trial = gemfile && physical(File.expand_path(gemfile, root))
+      files.push(trial, lockfile_for(trial)) if trial && trial != File.join(root, "Gemfile")
+      relative(files, root)
+    end
+
+    # Bundler's own rule, the same one preflight's execution inputs check
+    # against Bundler.default_lockfile: a gems.rb trial locks to gems.locked
+    # next to it; every other name gets ".lock" appended.
+    def self.lockfile_for(gemfile)
+      return File.join(File.dirname(gemfile), "gems.locked") if File.basename(gemfile) == "gems.rb"
+
+      "#{gemfile}.lock"
+    end
+
+    # git status paths are relative to the root, so the patterns are too:
+    # Dir.glob accepts a leading ./ or an absolute path under the root and
+    # File.fnmatch? does not (#503). A pattern outside the root stays
+    # absolute and matches no git path.
+    def self.relative_patterns(patterns, root)
+      patterns.map { |pattern| File.expand_path(pattern, root).delete_prefix(File.join(root, "")) }
+    end
+
+    # The path with its directory resolved, so a file that does not exist
+    # yet still gets the physical spelling of where it would be.
+    def self.physical(path)
+      File.join(File.realpath(File.dirname(path)), File.basename(path))
+    rescue SystemCallError
+      path
+    end
+
+    # A file outside the root keeps its absolute path, which no
+    # root-relative git path can equal.
+    def self.relative(files, root)
+      prefix = File.join(root, "")
+      files.map { |file| file.delete_prefix(prefix) }
+    end
+
+    private_class_method :physical, :relative
+
+    def initialize(state, included:, include:, exclude:, setup_files:, root:)
+      @state = state
+      @included = included.to_set
+      @include = self.class.relative_patterns(include, root)
+      @exclude = self.class.relative_patterns(exclude, root)
+      @setup_files = setup_files
+    end
+
+    def to_s
+      return unless @state.dirty
+
+      setup, rest = @state.changes.partition { |change| @setup_files.include?(change.path) }
+      scope, outside = rest.partition { |change| in_scope?(change.path) }
+      [summary(setup, scope, outside), named("inside the mutation scope", scope), named("setup files", setup),
+       "  #{ADVICE}"].compact.join("\n")
+    end
+
+    private
+
+    def summary(setup, scope, outside)
+      groups = [scope.empty? ? "none inside the mutation scope" : counted("inside the mutation scope", scope),
+                counted("outside it", outside)]
+      groups << counted("saboteur setup file(s)", setup) unless setup.empty?
+      "saboteur: warning: #{@state.changed_files} uncommitted or untracked change(s) in the working tree: " \
+        "#{groups.join(', ')}."
+    end
+
+    def counted(label, changes)
+      tracked = changes.count(&:tracked)
+      "#{changes.size} #{label} (#{tracked} tracked, #{changes.size - tracked} untracked)"
+    end
+
+    def named(label, changes)
+      return if changes.empty?
+
+      paths = changes.first(SHOWN_PATHS).map(&:path).join(", ")
+      more = changes.size - SHOWN_PATHS
+      "  #{label}: #{paths}#{" and #{more} more" if more.positive?}"
+    end
+
+    def in_scope?(path)
+      @included.include?(path) || (path.end_with?(".rb") && matches?(@include, path) && !matches?(@exclude, path))
+    end
+
+    def matches?(patterns, path)
+      patterns.any? { |pattern| File.fnmatch?(pattern, path, MATCH_FLAGS) }
+    end
+  end
+end

data/lib/saboteur/doctor.rb

@@ -98,6 +98,19 @@ module Saboteur
       else
         @out.puts "Sandbox: #{Engine::SandboxPolicy.sandbox_gap(abi)}; " \
                   "children would run with the hazard guard and canary only"
+        if RUBY_PLATFORM.match?(/darwin/i) && @config["sandbox"] == "seatbelt"
+          @out.puts %(Seatbelt (opt-in, #436): probe #{Execution::Seatbelt.probe} - capability probe only, ) \
+                    "not verified isolation"
+        elsif RUBY_PLATFORM.match?(/darwin/i)
+          # Point at the way OUT of the degraded state, like the run
+          # warning does (#667): the opt-in Seatbelt sandbox, or silence.
+          @out.puts "macOS: mutants run unsandboxed (Landlock is Linux-only) - a container contains " \
+                    "filesystem writes outside the project"
+          @out.puts %(macOS: opt into the sandbox with c.sandbox = "seatbelt" ) \
+                    "(docs/guides/macos-seatbelt-sandbox.md), or set c.sandbox = false to silence this"
+          @out.puts "Network: never restricted on any platform, and a plain container keeps outbound " \
+                    "access - deny or stub the network when a mutant could reach real APIs"
+        end
       end
     end
 

data/lib/saboteur/engine/baseline_guard.rb

@@ -4,6 +4,7 @@
 require "json"
 require "fileutils"
 require_relative "../text"
+require_relative "../frameworks/sqlite_memory_database"
 
 module Saboteur
   class Engine
@@ -23,7 +24,7 @@ module Saboteur
       # coverage build when the cache is cold, so the first timed pass can
       # price the rest (#260).
       def initialize(config:, integration:, hooks:, supervisor:, diagnostics:, full_passes: 2, between_passes: nil,
-                     timeout_cap: nil)
+                     timeout_cap: nil, run_started: nil)
         @config = config
         @integration = integration
         @hooks = hooks
@@ -32,6 +33,7 @@ module Saboteur
         @full_passes = full_passes
         @between_passes = between_passes
         @timeout_cap = timeout_cap
+        @run_started = run_started
         @completed_passes = 0
       end
 
@@ -50,10 +52,7 @@ module Saboteur
           started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           data = check(number)
           announce_first_pass_cost(number, started)
-          unless data["passed"] && data["failed"].empty?
-            refuse(number,
-                   "the suite failed: #{Array(data['failed']).join(', ')}")
-          end
+          refuse_suite_failure(number, data) unless data["passed"] && data["failed"].empty?
           executed = data["executed"]
           refuse(number, "executed tests do not match the loaded suite") unless
             executed.sort == expected.sort
@@ -66,6 +65,16 @@ module Saboteur
 
       private
 
+      def refuse_failed_suite(number, data)
+        outside = data["failed"].empty?
+        reason = if outside
+                   "the suite errored outside any example; see the log tail"
+                 else
+                   "the suite failed: #{data['failed'].join(', ')}"
+                 end
+        refuse(number, with_hint(reason, data), tail: outside)
+      end
+
       # A spent --max-duration budget skips the remaining passes - including
       # the first, when boot alone already spent it (#245).
       def budget_spent?(_index)
@@ -85,16 +94,47 @@ module Saboteur
       end
 
       # Once the first pass is timed, the total cost stops being a guess:
-      # the remaining full passes cost roughly the same each.
+      # the remaining full passes cost roughly the same each. full_passes
+      # includes the cold-cache coverage build (#260), so name what actually
+      # remains: with baseline_passes 1 the one remaining pass is the coverage
+      # build, not another baseline check (#465).
       def announce_first_pass_cost(number, started)
         return unless number == 1
 
-        remaining = @full_passes - number
-        return if remaining.zero?
-
+        coverage_pending = @full_passes > @config["baseline_passes"]
+        remaining = @full_passes - number - (coverage_pending ? 1 : 0)
         elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round
-        @diagnostics.inform("baseline check #{number} took #{elapsed} s; about #{elapsed * remaining} s left for " \
-                            "the remaining #{remaining} full #{remaining == 1 ? 'pass' : 'passes'} at that rate")
+        warn_budget_projection(elapsed, remaining + (coverage_pending ? 1 : 0))
+        return if remaining.zero? && !coverage_pending
+
+        work = []
+        work << "the remaining #{remaining} full #{remaining == 1 ? 'pass' : 'passes'}" if remaining.positive?
+        work << "the coverage map build" if coverage_pending
+        total = remaining + (coverage_pending ? 1 : 0)
+        @diagnostics.inform("baseline check #{number} took #{elapsed} s; about #{elapsed * total} s left for " \
+                            "#{work.join(' and ')} at that rate")
+      end
+
+      # The first timed pass also prices the run against --max-duration:
+      # boot and this pass are spent, the remaining passes and a cold
+      # coverage build cost about that much again at that rate, and only
+      # what is left feeds mutants. Warn while a Ctrl-C is still cheap -
+      # the refusal only fires once the coverage build is unaffordable
+      # outright (#637).
+      def warn_budget_projection(pass_elapsed, remaining_passes)
+        budget = @config["max_duration"]
+        return unless budget && @run_started
+
+        spent = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @run_started
+        projected = spent + (pass_elapsed * remaining_passes)
+        mutants_get = budget - projected
+        return if mutants_get >= pass_elapsed
+
+        verdict = mutants_get <= 0 ? "exceeds" : "barely fits"
+        @diagnostics.warn("projected baseline+coverage ~#{projected.round}s #{verdict} " \
+                          "--max-duration #{budget.round}s; mutants would get " \
+                          "~#{format('%g', [mutants_get, 0].max.round(1))}s. Raise --max-duration, pass fewer " \
+                          "--baseline-passes, or narrow the scope")
       end
 
       # An admitted pass still gets only the time left in the run budget:
@@ -117,6 +157,24 @@ module Saboteur
                                   "phase timeout)"
       end
 
+      # A containment limit stopping a healthy suite means the limit, not
+      # the suite: name the knob and its current value, like the sqlite
+      # :memory: hint (#387), so the user is not sent debugging a green
+      # suite (#459).
+      def stopped_reason(result)
+        reason = "the suite stopped: #{result.stopped_by} (#{result.detail})"
+        case result.stopped_by
+        when :processes
+          "#{reason}. If this suite forks heavily by design, raise the limit with " \
+          "c.max_processes (currently #{@config['max_processes']})"
+        when :memory
+          "#{reason}. If this suite legitimately needs more memory, raise the limit with " \
+          "c.max_memory_mb (currently #{@config['max_memory_mb']} MB)"
+        else
+          reason
+        end
+      end
+
       def check(number)
         Execution::ForkReadiness.prepare_heap
         heartbeat = @diagnostics.progress_heartbeat("baseline check #{number}").watch(log_path(number))
@@ -126,14 +184,14 @@ module Saboteur
           record(writer, number)
         end
         refuse_budget_stop(number, admitted) if budget_stopped?(result, admitted)
-        refuse(number, "the suite stopped: #{result.stopped_by} (#{result.detail})") if result.stopped_by
+        refuse(number, stopped_reason(result)) if result.stopped_by
         # Before the payload checks: a child killed by a signal (the OOM
         # killer, say) writes nothing, and the signal is the explanation. A
         # child the supervisor itself killed after it had reported is not a
         # failure: its payload is checked below.
         refuse(number, unsuccessful_exit(result.exit_status, result.memory_pressure)) if result.child_failed?
         refuse(number, "the child did not report a result") if result.payload.empty?
-        refuse(number, "the suite left child processes behind") if result.leftover_pids.any?
+        refuse(number, leftover_message(result), excerpt: false) if result.leftover_pids.any?
         parse_result(number, result.payload)
       end
 
@@ -151,7 +209,7 @@ module Saboteur
       def parse_result(number, payload)
         data = JSON.parse(payload)
         refuse(number, "the child reported an invalid result") unless data.is_a?(Hash)
-        refuse(number, data["error"]) if data["error"]
+        refuse(number, with_hint(data["error"], data)) if data["error"]
         refuse(number, "the child reported invalid test results") unless valid_result?(data)
         data
       rescue JSON::ParserError
@@ -172,31 +230,87 @@ module Saboteur
         @hooks.run(:after_fork)
         Kernel.srand(@config["seed"])
         result = @integration.run_baseline(seed: @config["seed"])
-        writer.write(JSON.generate(passed: result.passed, failed: result.failed_ids, executed: result.executed_ids))
+        payload = { passed: result.passed, failed: result.failed_ids, executed: result.executed_ids }
+        payload[:hint] = Frameworks::SqliteMemoryDatabase.fork_loss_hint unless result.passed
+        writer.write(JSON.generate(payload))
       rescue Exception => e # rubocop:disable Lint/RescueException
-        writer.write(JSON.generate(error: "#{e.class}: #{e.message}"))
+        writer.write(JSON.generate(error: "#{e.class}: #{e.message}",
+                                   hint: Frameworks::SqliteMemoryDatabase.fork_loss_hint))
       ensure
         writer.close
       end
 
+      # A failed unchanged suite never runs mutants: warn first when the
+      # failure carries the Minitest signature (#626), then refuse.
+      def refuse_suite_failure(number, data)
+        warn_minitest_signature(number)
+        refuse_failed_suite(number, data)
+      end
+
+      # Minitest::Spec suites in *_spec.rb clothing load under the RSpec
+      # integration and then fail the baseline with NoMethodError for
+      # Minitest-only methods (#626): the refusal still reads "fix the
+      # suite", so warn what the signature actually points at. It stays a
+      # warning: an RSpec suite can require minitest for a helper and
+      # fail for its own reason, and a heuristic refusal would
+      # false-positive there.
+      def warn_minitest_signature(number)
+        lines = log_lines(number)
+        errors = lines.grep(/NoMethodError/)
+        return if errors.empty? || !spec_helper_requires_minitest?
+
+        symptom = (lines.find { |line| line.include?("undefined method") } || errors.first).strip
+        @diagnostics.warn("the baseline failure looks like a Minitest suite running under RSpec, not a " \
+                          "broken RSpec suite: the log shows #{errors.size} " \
+                          "NoMethodError#{'s' if errors.size > 1} (for example: #{symptom.slice(0, EXCERPT_WIDTH)}) " \
+                          "and spec/spec_helper.rb requires minitest. saboteur is RSpec-only, so a " \
+                          "Minitest suite cannot be mutation tested with it.")
+      end
+
+      # The framework check behind the warning: spec_helper is the
+      # suite's own declaration of what it runs on.
+      def spec_helper_requires_minitest?
+        File.read(File.join(@config.root, "spec", "spec_helper.rb")).match?(/^\s*require\s+["']minitest/)
+      rescue SystemCallError
+        false
+      end
+
+      # A child that recognises its own failure shape (an empty sqlite
+      # :memory: database after the fork, #387) says how to fix it.
+      def with_hint(reason, data)
+        data["hint"] ? "#{reason}. #{data['hint']}" : reason
+      end
+
       def log_path(number)
         File.join(@config.path("cache_dir"), "baseline-#{number}.log")
       end
 
-      def refuse(number, reason)
+      # Leftover children are a pass-with-leaks verdict, not a suite
+      # failure: the message names the leaked processes (the supervisor's
+      # pre-kill notes) and skips the log excerpt, which holds only RSpec
+      # output and can never show them (#486).
+      def leftover_message(result)
+        notes = result.leftover_notes
+        detail = notes.empty? ? result.leftover_pids.join(", ") : notes.join(", ")
+        count = result.leftover_pids.size
+        "the suite passed but left #{count} child #{count == 1 ? 'process' : 'processes'} behind: #{detail}"
+      end
+
+      def refuse(number, reason, excerpt: true, tail: false)
         raise Error, "baseline check #{number} failed at seed #{@config['seed']}: #{reason}. " \
-                     "#{failure_excerpt(number)}See the full log at #{log_path(number)}. Fix the suite or its " \
-                     "setup, then run saboteur again with the same seed. No mutants were started."
+                     "#{failure_excerpt(number, tail: tail) if excerpt}See the full log at #{log_path(number)}. " \
+                     "Fix the suite or its setup, then run saboteur again with the same seed. " \
+                     "No mutants were started."
       end
 
       # The first lines of the failure, inline, so the cause is readable
       # without opening the log: RSpec's "Failures:" section when the log has
       # one, otherwise the last lines of the log.
-      def failure_excerpt(number)
+      def failure_excerpt(number, tail: false)
         lines = log_lines(number)
         return "" if lines.empty?
 
-        start = lines.index { |line| line.start_with?("Failures:") }
+        start = lines.index { |line| line.start_with?("Failures:") } unless tail
         shown = start ? lines[start, EXCERPT_LINES] : lines.last(EXCERPT_LINES)
         "The log says:\n#{shown.map { |line| "  #{line.slice(0, EXCERPT_WIDTH)}" }.join("\n")}\n"
       end

data/lib/saboteur/engine/boot.rb

@@ -10,6 +10,10 @@ module Saboteur
       # A test suite that (perhaps only under a mutant) starts a saboteur run
       # would otherwise run saboteur inside a saboteur child, recursively.
       def self.refuse_recursion!
+        if ENV[Execution::ExternalRunner::CHILD_MARKER]
+          raise Error, "refusing to start: this process runs inside a saboteur external test command " \
+                       "(#{Execution::ExternalRunner::CHILD_MARKER} is set); a nested run could race its tree"
+        end
         return unless ENV[Execution::Supervisor::CHILD_ENV]
 
         raise Error, "refusing to start: this process is a saboteur child " \
@@ -62,7 +66,9 @@ module Saboteur
         @rails = rails = Frameworks::Rails.new(@config, @hooks) if @config["rails"]
         rails&.before_boot
         @hooks.run(:before_boot)
-        add_spec_to_load_path if @config["rails"]
+        add_spec_to_load_path
+        # Helpers may configure RSpec before the integration loads specs.
+        Integration::RSpec.new(@config).require_framework if @config["integration"] == "rspec"
         @config["require"].each { |file| require File.expand_path(file, @root) }
         integration = Integration.fetch(@config["integration"]).new(@config)
         integration.setup
@@ -74,8 +80,10 @@ module Saboteur
       private
 
       # rspec puts spec/ on the load path, so a boot file under spec/ (a
-      # dummy app's rails_helper, say) can require its siblings. Match
-      # that, or the same require list fails to load.
+      # dummy app's rails_helper, or a non-Rails gem's spec_helper that
+      # requires its siblings) can require its siblings. Match that for
+      # every project - a non-Rails gem does not add spec/ itself (#615) -
+      # or the same require list fails to load.
       def add_spec_to_load_path
         path = File.join(@root, "spec")
         $LOAD_PATH.unshift(path) unless $LOAD_PATH.include?(path)

data/lib/saboteur/engine/bytecode_equivalence.rb

@@ -42,11 +42,27 @@ module Saboteur
 
       def fingerprint(text, frozen)
         options = { frozen_string_literal: frozen }
-        strip_positions(RubyVM::InstructionSequence.compile(text, nil, nil, 1, options).to_a)
+        iseq = warnings_silenced do
+          RubyVM::InstructionSequence.compile(text, "saboteur/bytecode-equivalence", nil, 1, options)
+        end
+        strip_positions(iseq.to_a)
       rescue SyntaxError, StandardError
         nil
       end
 
+      # Mutants compile one by one, and generated bodies (body_nil,
+      # statement_removal) trip Ruby's own void-context warnings, so a host
+      # suite running with -w gets one line per mutant flooding stderr
+      # (#592, #656). The check is internal: silence the compiler. A mutant
+      # that does not parse still fails the compile and runs.
+      def warnings_silenced
+        saved = $VERBOSE
+        $VERBOSE = nil
+        yield
+      ensure
+        $VERBOSE = saved
+      end
+
       # Structural equality that never coerces: an Integer is not a Float,
       # and +0.0 is not -0.0 (1.0 / +0.0 and 1.0 / -0.0 are different
       # infinities), which eql? alone would not tell apart.

data/lib/saboteur/engine/candidate_selection.rb

@@ -22,6 +22,10 @@ module Saboteur
         reason = subject.skip_reason || (skip_reason_for(subject) if @map.tests_for(subject).empty?)
         if reason
           @skipped_subjects[subject] = reason
+          # In a scoped run every subject is part of the change under
+          # review, so a skip is said up front, not only in the end-of-run
+          # summary (#574).
+          @diagnostics.announce(skip_announcement(subject, reason)) if scope
           return @selected[subject] = []
         end
 
@@ -44,9 +48,25 @@ module Saboteur
 
       private
 
+      # A scoped no-coverage skip names the specs the run loaded: coverage
+      # living in a sibling spec file is otherwise invisible, and the false
+      # read is "untestable" when the truth is "not loaded" (#636). Names
+      # at most five, like the other selection notes.
+      def skip_announcement(subject, reason)
+        line = "#{subject.id}: skipped (#{reason}); its change is not verified by this run"
+        return line unless reason == "no coverage"
+
+        loaded = @map.tests.map { |id| id.split("[").first.delete_prefix("./") }.uniq.sort
+        more = loaded.size > 5 ? ", ..." : ""
+        names = loaded.empty? ? "none" : loaded.first(5).join(", ")
+        "#{line} - loaded specs: #{names}#{more}; " \
+          "other spec files may cover it, pass --test to load them"
+      end
+
       # Load-only code is not "no coverage": it ran, just never inside a
       # test, and no forked test can re-run it (see CoverageMap::RAN_AT_LOAD).
       def skip_reason_for(subject)
+        return Selection::CoverageMap::PRELOADED if @map.preloaded?(subject.file)
         return "no coverage" unless @map.ran_at_load?(subject.file, subject.coverage_lines)
 
         Selection::CoverageMap::RAN_AT_LOAD

data/lib/saboteur/engine/candidates.rb

@@ -10,6 +10,25 @@ module Saboteur
     # a subject into runnable candidates: applied, re-parsed, de-duplicated,
     # coarse first. Returns [[mutation, mutated_text]].
     class Candidates
+      # The generator for constant hash/array literal subjects (#306); the
+      # method operators walk a def body a constant does not have.
+      def self.build(config, diagnostics, hazard_guard:)
+        new(build_sources(config), diagnostics, hazard_guard: hazard_guard,
+                                                constant_source: build_constant_source(config))
+      end
+
+      # Constants are generated by the builtin operator family, so a
+      # config that drops "builtin" from c.sources drops constant mutation
+      # too: the configured sources are the boundary for every subject
+      # kind (#319). Custom sources never see constants.
+      def self.build_constant_source(config)
+        return nil unless config["sources"].include?("builtin")
+
+        MutationSource::ConstantLiterals.new(operators: config["operators"],
+                                             exclude_operators: config["exclude_operators"],
+                                             arid: config["arid"])
+      end
+
       def self.build_sources(config)
         root = File.realpath(config.root)
         config["sources"].map do |entry|
@@ -19,15 +38,26 @@ module Saboteur
           end
 
           file, const = entry.split(":", 2)
-          raise ConfigError, "mutation source #{entry.inspect} must be builtin or path.rb:ClassName" unless const
+          unless const
+            if entry.include?("*")
+              raise ConfigError, "mutation source #{entry.inspect} looks like a source glob; " \
+                                 "did you mean c.include? c.sources registers custom operator sources " \
+                                 "(builtin or path.rb:ClassName)"
+            end
+            raise ConfigError, "mutation source #{entry.inspect} must be builtin or path.rb:ClassName"
+          end
 
           require File.expand_path(file, root)
           Object.const_get(const).new
         end
       end
 
-      def initialize(sources, diagnostics, hazard_guard: nil, bytecode: BytecodeEquivalence.new)
+      # constant_source: the generator for ConstantSubject instances; nil
+      # leaves constants with no candidates (a safe empty list).
+      def initialize(sources, diagnostics, hazard_guard: nil, bytecode: BytecodeEquivalence.new,
+                     constant_source: nil)
         @sources = sources
+        @constant_source = constant_source
         @diagnostics = diagnostics
         @hazard_guard = hazard_guard
         @bytecode = bytecode
@@ -40,7 +70,7 @@ module Saboteur
         end
 
         seen = Set[subject.source]
-        list = @sources.flat_map { |source| proposals(source, subject) }.filter_map do |mutation|
+        list = sources_for(subject).flat_map { |source| proposals(source, subject) }.filter_map do |mutation|
           candidate(subject, mutation, seen)
         end
         list = suppress_inline(list, subject)
@@ -50,6 +80,15 @@ module Saboteur
 
       private
 
+      # Constant literals have their own generator; external custom sources
+      # implement the def-subject contract and never see constants (#306).
+      def sources_for(subject)
+        return @sources unless subject.is_a?(ConstantSubject)
+        return [] unless @constant_source
+
+        [@constant_source]
+      end
+
       def suppress_inline(list, subject)
         directives = InlineSuppression.new(subject.file, subject.file_source)
         list.reject do |mutation, _text|
@@ -95,6 +134,7 @@ module Saboteur
         seen << text
         unless parses?(text)
           @diagnostics.count_invalid_mutation
+          @diagnostics.warn("#{subject.id}: dropped #{mutation.operator} mutation (did not parse)")
           return record_drop(subject, mutation, "invalid_syntax")
         end