active_mutator 0.1.0 → 0.2.0

data/lib/active_mutator/runner.rb

@@ -1,3 +1,5 @@
+require "json"
+
 module ActiveMutator
   class Runner
     def initialize(config, reporter: nil)
@@ -7,24 +9,34 @@ module ActiveMutator
 
     def call
       ENV["ACTIVE_MUTATOR"] = "1"
+      load_operators
       preload!
       preload_spec_helper!
       map = Baseline.new(root: @config.root).coverage_map(force: @config.force_baseline)
+      @reporter.coverage_map = map if @reporter.respond_to?(:coverage_map=)
       subjects = discover_subjects
       analyses = subjects.map { |s| Engine.new.analyze(s) }
       mutations = analyses.flat_map(&:mutations)
+      mutations = mutations.first(@config.max_mutants) if @config.max_mutants
       invalid_count = analyses.sum(&:invalid_count)
 
       fingerprints = Fingerprint.for_mutations(mutations, root: @config.root)
       ledger = AcceptedLedger.load(@config.root)
-      warn_stale(ledger, fingerprints.values)
+      scanned_files = prune_scope(subjects)
+      warn_stale(ledger, fingerprints.values, scanned_files)
 
       items, pre_results = plan_work(mutations, map, ledger: ledger, fingerprints: fingerprints)
+      return debug_plan(items, pre_results) if @config.debug_plan
+
       pre_results.each { |r| @reporter.on_result(r) }
-      scheduler = Scheduler.new(jobs: @config.jobs, on_result: @reporter.method(:on_result))
+      calibrators = if @config.adaptive_timeout
+                      { parallel: TimeoutCalibrator.new, serial: TimeoutCalibrator.new }
+                    end
+      scheduler = Scheduler.new(jobs: @config.jobs, on_result: @reporter.method(:on_result),
+                                calibrators: calibrators)
       results = scheduler.run(items) + pre_results
 
-      accept_survivors!(ledger, results, fingerprints) if @config.accept_survivors
+      accept_survivors!(ledger, results, fingerprints, scanned_files) if @config.accept_survivors
 
       @reporter.summary(results, invalid_count: invalid_count)
       exit_code(results)
@@ -39,27 +51,60 @@ module ActiveMutator
           pre_results << Result.new(mutation: mutation, status: :accepted, details: nil)
           next
         end
-        example_ids = map.examples_for(mutation.subject.file, mutation.lines)
+        example_ids = map.examples_for(mutation.subject.file, coverage_lines(mutation))
         if example_ids.empty?
           pre_results << Result.new(mutation: mutation, status: :uncovered, details: nil)
         else
           lane = example_ids.any? { |id| serial_example?(id) } ? :serial : :parallel
-          timeout = map.time_for(example_ids) * @config.timeout_factor + @config.timeout_floor
-          timeout += @config.browser_boot_seconds if lane == :serial
-          items << WorkItem.new(mutation: mutation, example_ids: example_ids, timeout: timeout, lane: lane)
+          variable = map.time_for(example_ids) * @config.timeout_factor
+          boot_extra = lane == :serial ? @config.browser_boot_seconds : 0.0
+          timeout = variable + @config.timeout_floor + boot_extra
+          items << WorkItem.new(mutation: mutation, example_ids: example_ids,
+                                timeout: timeout, lane: lane, variable: variable)
         end
       end
       [items, pre_results]
     end
 
     def exit_code(results)
-      results.any? { |r| r.status == :survived } ? 1 : 0
+      survived = results.count { |r| r.status == :survived }
+      return 0 if survived.zero?
+      return 1 unless @config.fail_at
+
+      detected = results.count { |r| %i[killed timeout].include?(r.status) }
+      score = detected * 100.0 / (detected + survived)
+      score >= @config.fail_at ? 0 : 1
     end
 
     private
 
+    # Custom operators must exist in the PARENT before Engine analysis:
+    # subclassing Operators::Base self-registers, and forks inherit the
+    # loaded class. `requires` can't serve — those load inside the fork's
+    # setup, after mutations are already planned.
+    def load_operators
+      @config.operator_paths.each do |f|
+        require File.expand_path(f, @config.root)
+      rescue LoadError, SyntaxError => e
+        raise Error, "operator file not loadable: #{f}: #{e.message}"
+      end
+    end
+
+    # Line coverage attributes multi-line expressions to their statement anchor
+    # line (version-dependently), so a sub-expression mutant's own lines may
+    # carry no coverage at all. Look up the whole subject instead: a mutant must
+    # run against every example covering any line of its method.
+    def coverage_lines(mutation)
+      mutation.lines.to_a | mutation.subject.line_range.to_a
+    end
+
     def build_reporter
-      @config.format == :json ? Reporter::Json.new : Reporter::Terminal.new
+      case @config.format
+      when :json then Reporter::Json.new
+      when :stryker_json then Reporter::StrykerJson.new(root: @config.root)
+      when :github then Reporter::Github.new(root: @config.root)
+      else Reporter::Terminal.new
+      end
     end
 
     def preload!
@@ -77,9 +122,14 @@ module ActiveMutator
     def discover_subjects
       paths = @config.paths.empty? ? default_paths : @config.paths
       subjects = paths
-        .flat_map { |p| Dir[File.join(@config.root, p, "**", "*.rb")] }
+        .flat_map { |p| expand_path_arg(p) }
+        .uniq
+        .reject { |file| excluded?(file) }
         .sort.flat_map { |file| SubjectFinder.call(file) }
-      subjects = subjects.select { |s| s.name == @config.subject_filter } if @config.subject_filter
+      if @config.subject_filter
+        matcher = SubjectMatcher.new(@config.subject_filter)
+        subjects = subjects.select { |s| matcher.match?(s.name) }
+      end
       if @config.since
         filter = SinceFilter.new(ref: @config.since, root: @config.root)
         subjects = subjects.select { |s| filter.cover?(s) }
@@ -87,6 +137,34 @@ module ActiveMutator
       subjects
     end
 
+    # Positional args may be files or directories. Anything else is an error:
+    # a mistyped path that silently matched nothing produced a false green
+    # (0 subjects, exit 0) — see #23.
+    def expand_path_arg(path)
+      full = File.expand_path(path, @config.root)
+      if File.file?(full)
+        raise Error, "not a Ruby file: #{path}" unless full.end_with?(".rb")
+
+        [full]
+      elsif Dir.exist?(full)
+        Dir[File.join(full, "**", "*.rb")]
+      else
+        raise Error, "no such file or directory: #{path}"
+      end
+    end
+
+    def excluded?(file)
+      flags = File::FNM_PATHNAME | File::FNM_EXTGLOB
+      relative = file.delete_prefix(@config.root.chomp("/") + "/")
+      @config.exclude.any? do |pattern|
+        # Gitignore-like ergonomics: "lib/gen", "lib/gen/" and "lib/gen/**"
+        # all exclude the whole subtree, not just direct children.
+        dir = pattern.sub(%r{(/\*\*)?/?\z}, "")
+        File.fnmatch?(pattern, relative, flags) ||
+          File.fnmatch?("#{dir}/**/*", relative, flags)
+      end
+    end
+
     def default_paths
       %w[app lib].select { |p| Dir.exist?(File.join(@config.root, p)) }
     end
@@ -121,22 +199,48 @@ module ActiveMutator
 
     # A preloaded helper commonly starts SimpleCov. Its at_exit would fire in
     # THIS parent process at the end of the mutation run, clobbering the
-    # project's real coverage data — and minimum_coverage would exit(1) for a
+    # project's real coverage data, and minimum_coverage would exit(1) for a
     # bogus reason. Neutralize it.
     def disarm_simplecov
       SimpleCov.at_exit {} if defined?(SimpleCov)
     end
 
-    def accept_survivors!(ledger, results, fingerprints)
+    # Only a run with no subject-level narrowing has fully scanned a file;
+    # anything narrower must not prune (or warn about) out-of-scope entries.
+    # MAINTENANCE: any future flag that narrows the mutant set below "every
+    # subject in the scanned files" MUST be added to this nil-trigger list,
+    # or scoped accept runs will clobber out-of-scope ledger entries (#24).
+    def prune_scope(subjects)
+      return nil if @config.subject_filter || @config.since || @config.max_mutants
+
+      subjects.map { |s| s.file.delete_prefix("#{@config.root}/") }.uniq
+    end
+
+    def accept_survivors!(ledger, results, fingerprints, scanned_files)
       survivors = results.select { |r| r.status == :survived }.map { |r| fingerprints[r.mutation] }
       return if survivors.empty?
 
-      ledger.accept!(survivors, fingerprints.values)
+      ledger.accept!(survivors, fingerprints.values, scanned_files: scanned_files)
     end
 
-    def warn_stale(ledger, all_fingerprints)
-      ledger.stale_entries(all_fingerprints).each do |entry|
-        warn "active_mutator: stale accepted fingerprint (no matching mutant): #{entry.subject} — #{entry.description}"
+    def debug_plan(items, pre_results)
+      plan = items.map do |i|
+        { "subject" => i.mutation.subject.name, "description" => i.mutation.description,
+          "file" => i.mutation.subject.file, "line" => i.mutation.line,
+          "lane" => i.lane.to_s, "timeout" => i.timeout.round(2),
+          "examples" => i.example_ids.size }
+      end
+      skipped = pre_results.group_by { |r| r.status.to_s }.transform_values(&:size)
+      puts JSON.pretty_generate("planned" => plan, "pre_resolved" => skipped)
+      0
+    end
+
+    def warn_stale(ledger, all_fingerprints, scanned_files)
+      ledger.stale_entries(all_fingerprints, scanned_files: scanned_files).each do |entry|
+        warn "active_mutator: stale accepted fingerprint (no matching mutant): #{entry.subject}, #{entry.description}"
+      end
+      ledger.missing_file_entries(@config.root).each do |entry|
+        warn "active_mutator: accepted fingerprint references missing file: #{entry.file} (#{entry.subject})"
       end
     end
   end

data/lib/active_mutator/scheduler.rb

@@ -5,10 +5,16 @@ module ActiveMutator
   # Parent enforces per-item deadlines with SIGKILL (worker-side timeouts
   # cannot interrupt all infinite loops).
   class Scheduler
-    def initialize(jobs:, worker: Worker.method(:run), on_result: nil)
+    OrphanedError = Class.new(Error)
+
+    def initialize(jobs:, worker: Worker.method(:run), on_result: nil,
+                   calibrators: nil, orphaned: -> { Process.ppid == 1 })
       @jobs = jobs
       @worker = worker
       @on_result = on_result
+      @calibrators = calibrators
+      @orphaned = orphaned
+      @last_logged_scale = {} # lane => last scale logged for that lane
     end
 
     def run(items)
@@ -32,6 +38,7 @@ module ActiveMutator
       queue = items.dup
       results = []
       until queue.empty? && running.empty?
+        abort_if_orphaned!(running)
         spawn(queue.shift, running) while running.size < width && !queue.empty?
         reap(running, results)
         sleep 0.02 unless running.empty?
@@ -39,6 +46,22 @@ module ActiveMutator
       results
     end
 
+    # SIGKILL on the parent (or a closed terminal, or CI teardown) cannot be
+    # trapped, so a killed run would otherwise keep forking through the whole
+    # queue with nobody supervising it. Orphaned processes get reparented to
+    # init/launchd (ppid 1); when that happens, stop everything and bail.
+    def abort_if_orphaned!(running)
+      return unless @orphaned.call
+
+      running.each_key do |pid|
+        kill(pid)
+      rescue StandardError
+        nil
+      end
+      running.clear
+      raise OrphanedError, "parent process died; aborting mutation run"
+    end
+
     def spawn(item, running)
       reader, writer = IO.pipe
       pid = fork do
@@ -51,7 +74,12 @@ module ActiveMutator
         Process.exit!(0)
       end
       writer.close
-      running[pid] = { reader: reader, item: item, deadline: now + item.timeout }
+      calibrator = calibrator_for(item)
+      budget = calibrator ? calibrator.budget_for(item) : item.timeout
+      log_scale(calibrator, item.lane)
+      started = now
+      running[pid] = { reader: reader, item: item, started: started,
+                       budget: budget, deadline: started + budget }
     end
 
     def reap(running, results)
@@ -59,7 +87,11 @@ module ActiveMutator
         done, _status = Process.waitpid2(pid, Process::WNOHANG)
         if done
           running.delete(pid)
-          results << finish(entry)
+          result = finish(entry)
+          if result.status == :killed
+            calibrator_for(entry[:item])&.record(now - entry[:started], entry[:budget])
+          end
+          results << result
         elsif now > entry[:deadline]
           kill(pid)
           running.delete(pid)
@@ -73,8 +105,16 @@ module ActiveMutator
       payload = entry[:reader].read.to_s
       entry[:reader].close
       data = payload.empty? ? nil : JSON.parse(payload)
-      status = data ? data.fetch("status").to_sym : :error
-      details = data ? data["details"] : "worker exited without reporting"
+      # A self-mutation of Worker#emit can produce well-formed JSON without a
+      # "status" key (or with a non-Hash root); treat any unusable payload as
+      # a worker error instead of crashing the whole run.
+      reported = data.is_a?(Hash) && data.key?("status")
+      status = reported ? data["status"].to_sym : :error
+      details = reported ? data["details"] : "worker exited without reporting"
+    rescue JSON::ParserError
+      report(Result.new(mutation: entry[:item].mutation, status: :error,
+                        details: "worker emitted unparseable payload"))
+    else
       report(Result.new(mutation: entry[:item].mutation, status: status, details: details))
     end
 
@@ -86,7 +126,7 @@ module ActiveMutator
     def kill(pid)
       Process.kill("KILL", -pid) # negative pid = whole process group
     rescue Errno::ESRCH, Errno::EPERM
-      # Group not established yet (setpgid race) or already gone — direct kill.
+      # Group not established yet (setpgid race) or already gone: direct kill.
       begin
         Process.kill("KILL", pid)
       rescue Errno::ESRCH
@@ -100,7 +140,7 @@ module ActiveMutator
       end
     end
 
-    # Returns {sig => previous_handler} so #run can restore on exit —
+    # Returns {sig => previous_handler} so #run can restore on exit,
     # otherwise our traps permanently replace the host's (e.g. RSpec's Ctrl-C).
     def install_signal_handlers(running)
       %w[INT TERM].to_h do |sig|
@@ -120,6 +160,23 @@ module ActiveMutator
       previous.each { |sig, handler| trap(sig, handler || "DEFAULT") }
     end
 
+    def calibrator_for(item)
+      @calibrators && @calibrators[item.lane]
+    end
+
+    # Effective budgets are otherwise invisible (--debug-plan shows static
+    # ones by design). One stderr line per scale CHANGE per lane, not per
+    # spawn — the two lanes calibrate independently, so the lane is named.
+    def log_scale(calibrator, lane)
+      return unless calibrator&.warmed?
+
+      scale = calibrator.scale.round(2)
+      return if scale == @last_logged_scale[lane]
+
+      @last_logged_scale[lane] = scale
+      warn "active_mutator: adaptive timeout scale (#{lane}): #{scale}"
+    end
+
     def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 end

data/lib/active_mutator/source_location.rb

@@ -0,0 +1,21 @@
+module ActiveMutator
+  # 1-based line/column (never 0 — the Stryker schema rejects 0) for an
+  # exclusive byte range within a source string.
+  module SourceLocation
+    def self.locate(source, byte_range)
+      {
+        start: position(source, byte_range.begin),
+        end: position(source, byte_range.end)
+      }
+    end
+
+    def self.position(source, offset)
+      prefix = source.byteslice(0, offset)
+      last_newline = prefix.rindex("\n")
+      {
+        line: prefix.count("\n") + 1,
+        column: offset - (last_newline ? last_newline + 1 : 0) + 1
+      }
+    end
+  end
+end

data/lib/active_mutator/subject.rb

@@ -1,7 +1,13 @@
 module ActiveMutator
   # A mutable unit: one method definition.
   # byte_range/line_range cover the whole `def ... end`.
-  Subject = Data.define(:name, :file, :byte_range, :line_range, :constant_scope, :kind) do
+  # sclass: def lives inside `class << self` — its source slice is `def foo`,
+  # so Inserter must target the singleton class, not the constant itself.
+  Subject = Data.define(:name, :file, :byte_range, :line_range, :constant_scope, :kind, :sclass) do
+    def initialize(name:, file:, byte_range:, line_range:, constant_scope:, kind:, sclass: false)
+      super
+    end
+
     def singleton? = kind == :singleton
   end
 end

data/lib/active_mutator/subject_finder.rb

@@ -1,36 +1,73 @@
+require "set"
+
 module ActiveMutator
   class SubjectFinder < Prism::Visitor
+    SKIP_MARKER = /#\s*active_mutator:\s*skip\b/
+
     def self.call(file)
       result = Prism.parse(File.read(file))
       return [] unless result.success?
 
-      finder = new(file)
+      skip_lines = result.comments
+        .select { |c| c.slice.match?(SKIP_MARKER) }
+        .to_set { |c| c.location.start_line }
+      finder = new(file, skip_lines: skip_lines)
       finder.visit(result.value)
       finder.subjects
     end
 
     attr_reader :subjects
 
-    def initialize(file)
+    def initialize(file, skip_lines: Set.new)
       @file = file
+      @skip_lines = skip_lines
       @stack = []
       @subjects = []
+      @sclass_depth = 0
       super()
     end
 
+    # Classes/modules declared inside `class << self` hang their constant on
+    # the SINGLETON class, so a lexically-joined scope like "Foo::Bar" is not
+    # reachable via Object.const_get — Inserter would crash. Skipped entirely.
     def visit_class_node(node)
+      return if @sclass_depth.positive?
+
       with_scope(node.constant_path.slice) { super }
     end
 
     def visit_module_node(node)
+      return if @sclass_depth.positive?
+
       with_scope(node.constant_path.slice) { super }
     end
 
-    # `class << self` bodies are a documented v1 limit: not visited.
-    def visit_singleton_class_node(node); end
+    # `class << self` inside a constant scope: defs there are singleton
+    # methods of the enclosing constant. `class << obj` and a top-level
+    # `class << self` (no constant to hang the method on) stay skipped.
+    def visit_singleton_class_node(node)
+      return unless node.expression.is_a?(Prism::SelfNode) && !@stack.empty?
+
+      @sclass_depth += 1
+      begin
+        super
+      ensure
+        @sclass_depth -= 1
+      end
+    end
+
+    # Defs inside blocks (`Data.define do ... end`, `class_eval do ... end`)
+    # do not live on the enclosing constant scope, so Inserter would redefine
+    # them on the wrong constant and every mutant would falsely survive.
+    # Same v1 limit as `class << self`: not visited. Note this also hides
+    # classes/modules defined inside blocks (accepted v1 limit).
+    def visit_block_node(node); end
 
     def visit_def_node(node)
-      singleton = node.receiver.is_a?(Prism::SelfNode)
+      return if @skip_lines.include?(node.location.start_line - 1)
+
+      sclass = @sclass_depth.positive?
+      singleton = sclass || node.receiver.is_a?(Prism::SelfNode)
       scope = @stack.empty? ? nil : @stack.join("::")
       loc = node.location
       @subjects << Subject.new(
@@ -39,9 +76,11 @@ module ActiveMutator
         byte_range: loc.start_offset...loc.end_offset,
         line_range: loc.start_line..loc.end_line,
         constant_scope: scope,
-        kind: singleton ? :singleton : :instance
+        kind: singleton ? :singleton : :instance,
+        sclass: sclass
       )
-      # No `super`: nested defs are out of scope for v1.
+      # No `super`: nested defs get no subject of their own -- their bodies
+      # are mutated via the OUTER def (Engine#walk descends into them).
     end
 
     private

data/lib/active_mutator/subject_matcher.rb

@@ -0,0 +1,23 @@
+module ActiveMutator
+  # Tiny subject-expression grammar for --subject:
+  #   Foo::Bar#baz  exact          Foo::Bar   all methods of the constant
+  #   Foo::Bar*     namespace      Foo::Bar#* instance-only   Foo::Bar.* singleton-only
+  class SubjectMatcher
+    def initialize(expression)
+      @regexp = compile(expression)
+    end
+
+    def match?(name) = @regexp.match?(name)
+
+    private
+
+    def compile(expr)
+      case expr
+      when /\A(.+)([#.])\*\z/ then /\A#{Regexp.escape($1)}#{Regexp.escape($2)}[^#.]+\z/
+      when /\A(.+)\*\z/       then /\A#{Regexp.escape($1)}/
+      when /[#.]/             then /\A#{Regexp.escape(expr)}\z/
+      else                         /\A#{Regexp.escape(expr)}[#.][^#.]+\z/
+      end
+    end
+  end
+end

data/lib/active_mutator/timeout_calibrator.rb

@@ -0,0 +1,75 @@
+module ActiveMutator
+  # Adaptive timeout budgets (#9). Static budgets derive from baseline times
+  # measured warm and unloaded; under parallel load they misclassify
+  # slow-but-honest kills as timeouts. The Scheduler feeds this with the
+  # observed wall time of every KILLED fork (errors exit artificially fast,
+  # survivors run their whole covering set — both would bias the median;
+  # timed-out forks have no known wall time at all). One instance per lane:
+  # parallel and serial run under different load regimes.
+  #
+  # Utilization is elapsed / the EFFECTIVE budget the fork ran under (the
+  # value budget_for returned at its spawn), not the static item.timeout —
+  # otherwise a pinned-high scale could never observe recovery (ratchet).
+  # Once WARMUP observations exist, remaining budgets' variable part is
+  # scaled by the clamped median utilization. The fixed part (timeout_floor
+  # + browser boot) is never scaled: fork boot cost does not shrink because
+  # examples run fast.
+  #
+  # The scale is grow-only (MIN_SCALE = 1.0): budgets may only extend beyond
+  # the static value, never fall below it. Downscaling has no recovery signal
+  # because timeouts are CENSORED samples — the scheduler skips them (they have
+  # no known wall time), so only killed forks feed the window. A low median
+  # utilization would shrink the budget, causing a legitimately slow kill to be
+  # reaped as a timeout; that censored kill never enters the window, so nothing
+  # ever pushes utilization back up. The shrink self-sustains — an asymmetric
+  # ratchet. Growing is safe (a too-large budget still records a real kill and
+  # relaxes); shrinking is not, so we forbid it.
+  class TimeoutCalibrator
+    WARMUP = 5
+    # A real sliding window, not full-run history: a 500-mutant run's early
+    # load regime must age out completely instead of anchoring the median
+    # forever. 30 samples is enough for a stable median and small enough to
+    # track load changes within a few dozen finishes.
+    WINDOW = 30
+    TARGET_UTILIZATION = 0.25
+    MIN_SCALE = 1.0
+    MAX_SCALE = 4.0
+
+    def initialize
+      @utilizations = []
+    end
+
+    def record(elapsed_seconds, budget)
+      return unless budget.positive?
+
+      @utilizations << elapsed_seconds / budget
+      @utilizations.shift while @utilizations.size > WINDOW
+    end
+
+    def warmed? = @utilizations.size >= WARMUP
+
+    def budget_for(item)
+      return item.timeout unless warmed?
+
+      fixed = item.timeout - item.variable
+      item.variable * scale + fixed
+    end
+
+    def scale
+      # An empty window has no median; a caller invoking scale without warmed?
+      # (median of [] is nil) would otherwise raise. Neutral scale = no change.
+      return 1.0 if @utilizations.empty?
+
+      s = median(@utilizations) / TARGET_UTILIZATION
+      s.clamp(MIN_SCALE, MAX_SCALE)
+    end
+
+    private
+
+    def median(values)
+      sorted = values.sort
+      mid = sorted.size / 2
+      sorted.size.odd? ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2.0
+    end
+  end
+end

data/lib/active_mutator/version.rb

@@ -1,3 +1,3 @@
 module ActiveMutator
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/active_mutator/work_item.rb

@@ -1,4 +1,11 @@
 module ActiveMutator
   # lane: :parallel (default pool) | :serial (browser-covered, one at a time)
-  WorkItem = Data.define(:mutation, :example_ids, :timeout, :lane)
+  # timeout:    static total budget (variable + fixed), kept for --debug-plan and compat
+  # variable:   the baseline-estimate-derived part (estimate * timeout_factor) — the
+  #             only part the TimeoutCalibrator scales
+  WorkItem = Data.define(:mutation, :example_ids, :timeout, :lane, :variable) do
+    def initialize(mutation:, example_ids:, timeout:, lane:, variable: 0.0)
+      super
+    end
+  end
 end

data/lib/active_mutator/worker.rb

@@ -3,7 +3,7 @@ require "set"
 
 module ActiveMutator
   # Runs INSIDE a fork. Order is critical: RSpec's setup phase loads the spec
-  # files, whose spec_helper/rails_helper loads the application — only THEN
+  # files, whose spec_helper/rails_helper loads the application. Only THEN
   # can the mutation be inserted over the loaded original. Insert-first would
   # NameError on any project not preloaded in the parent (all non-Rails
   # projects), and loading app code after insertion would silently restore
@@ -24,6 +24,9 @@ module ActiveMutator
       devnull = File.open(File::NULL, "w")
       runner = RSpec::Core::Runner.new(RSpec::Core::ConfigurationOptions.new(@example_ids))
       runner.setup(devnull, devnull)   # loads spec files -> loads the app
+      # One failure kills the mutant; running the rest of the covering set
+      # is pure waste inside the fork.
+      RSpec.configuration.fail_fast = 1
       Inserter.new.insert(@mutation)   # now the target constant exists
       after_fork_hygiene
       code = runner.run_specs(covering_groups)
@@ -47,7 +50,7 @@ module ActiveMutator
       @writer.flush if @writer.respond_to?(:flush)
     end
 
-    # RSpec.world holds every group registered in the process — including any
+    # RSpec.world holds every group registered in the process, including any
     # top-level groups evaluated while the PARENT preloaded the spec helper
     # (spec/support files with RSpec.describe at load time are common). Those
     # leak into the fork; running them would report their failures as false

data/lib/active_mutator.rb

@@ -11,6 +11,7 @@ require_relative "active_mutator/edit"
 require_relative "active_mutator/splicer"
 require_relative "active_mutator/subject"
 require_relative "active_mutator/subject_finder"
+require_relative "active_mutator/subject_matcher"
 require_relative "active_mutator/operators/base"
 require_relative "active_mutator/operators/conditional_boundary"
 require_relative "active_mutator/operators/condition_forcing"
@@ -27,16 +28,23 @@ require_relative "active_mutator/atomic_file"
 require_relative "active_mutator/coverage_map"
 require_relative "active_mutator/baseline"
 require_relative "active_mutator/baseline_delta"
+require_relative "active_mutator/defined_constants"
 require_relative "active_mutator/inserter"
 require_relative "active_mutator/worker"
 require_relative "active_mutator/result"
 require_relative "active_mutator/work_item"
+require_relative "active_mutator/timeout_calibrator"
 require_relative "active_mutator/scheduler"
+require_relative "active_mutator/reporter/operator_stats"
 require_relative "active_mutator/reporter/terminal"
+require_relative "active_mutator/reporter/github"
 require_relative "active_mutator/reporter/json"
+require_relative "active_mutator/source_location"
 require_relative "active_mutator/since_filter"
 require_relative "active_mutator/fingerprint"
 require_relative "active_mutator/accepted_ledger"
+require_relative "active_mutator/reporter/stryker_json"
 require_relative "active_mutator/config"
 require_relative "active_mutator/runner"
+require_relative "active_mutator/config_file"
 require_relative "active_mutator/cli"