evilution 0.28.0 → 0.30.0

data/lib/evilution/feedback/setup_warning.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../feedback"
+
+# Detects "setup misconfiguration" patterns where mutation testing returned a
+# result that is technically valid (score 0.0 with all-errored mutations) but
+# is almost certainly the wrong score because the worker process couldn't
+# evaluate any mutated source.
+#
+# Most common cause: MCP runs default to `preload: false` to keep the long-lived
+# MCP server clean. Rails / Zeitwerk projects that depend on autoload then fail
+# in every worker with `NameError: uninitialized constant ...`. The user sees
+# "0% PASS-but-FAIL" with no obvious hint that they need to pass an explicit
+# `preload: spec/rails_helper.rb` option.
+#
+# When triggered, this returns a warning string the MCP response can surface
+# alongside the trimmed report — turning a silent wrong score into a loud
+# pointer at the likely fix.
+module Evilution::Feedback::SetupWarning
+  module_function
+
+  ERROR_DOMINANCE_THRESHOLD = 0.8
+  ERROR_CLASS_CLUSTER_THRESHOLD = 0.8
+
+  def call(summary)
+    return nil if summary.nil?
+    return nil unless errors_dominate?(summary)
+
+    errored = summary.results.select(&:error?)
+    dominant_class = dominant_error_class(errored)
+    return nil unless dominant_class
+
+    message_for(dominant_class, errored.size, summary.total)
+  end
+
+  def errors_dominate?(summary)
+    return false if summary.total.zero?
+
+    summary.errors.to_f / summary.total >= ERROR_DOMINANCE_THRESHOLD
+  end
+  private_class_method :errors_dominate?
+
+  def dominant_error_class(errored_results)
+    return nil if errored_results.empty?
+
+    counts = errored_results.each_with_object(Hash.new(0)) do |result, acc|
+      acc[result.error_class] += 1 if result.error_class
+    end
+    return nil if counts.empty?
+
+    klass, count = counts.max_by { |_, v| v }
+    return nil if count.to_f / errored_results.size < ERROR_CLASS_CLUSTER_THRESHOLD
+
+    klass
+  end
+  private_class_method :dominant_error_class
+
+  NAME_ERROR_HINT = "Most mutations errored with NameError. This usually means autoloaded constants " \
+                    "(Rails / Zeitwerk) weren't available when the mutation re-evaluated the source. " \
+                    "Pass `preload: 'spec/rails_helper.rb'` (or your project's preload entry) so the " \
+                    "MCP server requires it before forking workers."
+
+  LOAD_ERROR_HINT = "Most mutations errored with LoadError. A `require` in the mutated source path " \
+                    "failed before any test ran. Check that the file's dependencies are reachable from " \
+                    "the MCP server's load path, or pass `preload: '<entrypoint>'` to set them up."
+
+  GENERIC_HINT_TEMPLATE = "Most mutations errored with %<klass>s (%<count>d / %<total>d). The mutation " \
+                          "score reflects this setup failure, not the test suite. Try the CLI for an " \
+                          "independent reading, or pass `preload: '<path>'` if the failure is autoload-related."
+
+  def message_for(klass, count, total)
+    case klass.to_s
+    when "NameError" then NAME_ERROR_HINT
+    when "LoadError" then LOAD_ERROR_HINT
+    else format(GENERIC_HINT_TEMPLATE, klass: klass, count: count, total: total)
+    end
+  end
+  private_class_method :message_for
+end

data/lib/evilution/gem_detector.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Evilution::GemDetector
+  @cache = {}
+  @mutex = Mutex.new
+
+  class << self
+    def gem_root_for(path)
+      return nil if path.nil?
+
+      dir = starting_dir(path)
+      return nil if dir.nil?
+
+      @mutex.synchronize do
+        return @cache[dir] if @cache.key?(dir)
+
+        @cache[dir] = walk_up(dir)
+      end
+    end
+
+    def gem_root_for_any(paths)
+      Array(paths).each do |path|
+        root = gem_root_for(path)
+        return root if root
+      end
+      nil
+    end
+
+    def gem_entry_for(root, target_paths: nil)
+      gem_name = gem_name_for(root, target_paths: target_paths)
+      return nil unless gem_name
+
+      dotted = File.join(root, "lib", "#{gem_name.tr("-", "/")}.rb")
+      return dotted if File.file?(dotted)
+
+      flat = File.join(root, "lib", "#{gem_name}.rb")
+      return flat if File.file?(flat)
+
+      nil
+    end
+
+    def reset_cache!
+      @mutex.synchronize { @cache.clear }
+    end
+
+    private
+
+    def starting_dir(path)
+      return File.expand_path(path) if File.directory?(path)
+      return File.expand_path(File.dirname(path)) if File.file?(path)
+
+      parent = File.expand_path(File.dirname(path))
+      File.directory?(parent) ? parent : nil
+    end
+
+    def walk_up(dir)
+      current = dir
+      loop do
+        return current unless Dir.glob(File.join(current, "*.gemspec")).empty?
+
+        parent = File.dirname(current)
+        return nil if parent == current
+
+        current = parent
+      end
+    end
+
+    # When the root has multiple gemspecs (e.g. dotenv ships dotenv.gemspec
+    # alongside dotenv-rails.gemspec), `Dir.glob.first` is filesystem-order-
+    # dependent and often picks the wrong one — preloading the rails companion
+    # then raises `uninitialized constant Rails`. Disambiguate by:
+    #   1. exact-entry match — if a target is *exactly* the lib entry for a
+    #      gemspec (`lib/dotenv/rails.rb` for `dotenv-rails.gemspec`), use it
+    #   2. first-lib-subdir match — `lib/dotenv/parser.rb` matches `dotenv`
+    #   3. fall back to the shortest gemspec basename — `dotenv` <
+    #      `dotenv-rails`, which is the conventional "parent" gem.
+    def gem_name_for(root, target_paths: nil)
+      names = Dir.glob(File.join(root, "*.gemspec")).map { |p| File.basename(p, ".gemspec") }
+      return nil if names.empty?
+      return names.first if names.length == 1
+
+      paths = Array(target_paths)
+      match_by_exact_entry(root, names, paths) ||
+        match_by_subdir(root, names, paths) ||
+        names.min_by(&:length)
+    end
+
+    def match_by_exact_entry(root, names, paths)
+      paths.each do |path|
+        next if path.nil?
+
+        expanded = File.expand_path(path)
+        match = names.find { |n| entry_paths_for(root, n).include?(expanded) }
+        return match if match
+      end
+      nil
+    end
+
+    def entry_paths_for(root, gem_name)
+      [
+        File.join(root, "lib", "#{gem_name.tr("-", "/")}.rb"),
+        File.join(root, "lib", "#{gem_name}.rb")
+      ]
+    end
+
+    def match_by_subdir(root, names, paths)
+      paths.each do |path|
+        subdir = lib_subdir_for(root, path)
+        next if subdir.nil?
+
+        match = names.find { |n| n == subdir }
+        return match if match
+      end
+      nil
+    end
+
+    # For `<root>/lib/dotenv/parser.rb` returns "dotenv". For
+    # `<root>/lib/dotenv-rails.rb` returns "dotenv-rails". Returns nil when
+    # the target isn't under `<root>/lib/`.
+    def lib_subdir_for(root, path)
+      return nil if path.nil?
+
+      expanded = File.expand_path(path)
+      lib_root = File.join(File.expand_path(root), "lib")
+      return nil unless expanded.start_with?("#{lib_root}/")
+
+      relative = expanded[(lib_root.length + 1)..]
+      first_segment = relative.split("/", 2).first
+      File.basename(first_segment, ".rb")
+    end
+  end
+end

data/lib/evilution/integration/loading/body_call_neutralizer.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../loading"
+
+# Strip non-idempotent class/module-body side-effect calls from a mutated
+# source before re-eval. Such calls (e.g. dry-monads `register_mixin`, plugin
+# registries) raise on second invocation because they assume single-eval
+# semantics. The first invocation already ran in the parent process during
+# preload — the child fork inherits the resulting state, so re-running them
+# is wasted work that aborts the eval before the mutated method takes effect.
+#
+# Strategy: walk Prism tree, find CallNodes that sit directly under a class
+# or module body (not inside a def). Calls on a small allowlist of patterns
+# known to be idempotent (`include`, `attr_*`, visibility modifiers, etc.)
+# are preserved; everything else is replaced byte-for-byte with `nil`.
+class Evilution::Integration::Loading::BodyCallNeutralizer
+  IDEMPOTENT_CALLS = %i[
+    include extend prepend using
+    attr_reader attr_writer attr_accessor
+    private public protected module_function private_class_method public_class_method
+    alias_method
+    define_method define_singleton_method
+    delegate
+    require require_relative autoload
+  ].to_set.freeze
+
+  class << self
+    attr_writer :preloaded_features
+
+    # Snapshot of `$LOADED_FEATURES` captured at parent preload-end (or lazily
+    # initialised on first access). Forks inherit this set via copy-on-write,
+    # so worker processes see the same membership the parent saw when it
+    # finished its preload phase. Frozen so in-place mutation cannot silently
+    # change neutralization semantics or force child forks to copy the page.
+    def preloaded_features
+      @preloaded_features ||= $LOADED_FEATURES.to_set.freeze
+    end
+
+    def reset_preload_snapshot!
+      @preloaded_features = nil
+    end
+  end
+
+  # `file_path` (optional) lets callers gate neutralization on whether the
+  # target file was actually preloaded into the parent. The neutralizer's
+  # premise — "this body has already run once, re-running it would double-
+  # register" — only holds when the parent loaded the file. Lazy-loaded
+  # plugin files (e.g. roda's `lib/roda/plugins/typecast_params.rb`, which
+  # the gem only requires when the user opts in via `plugin :typecast_params`)
+  # are first-loaded inside the child fork, so neutralizing their DSL calls
+  # strips method definitions that subsequent sibling statements (alias, etc.)
+  # depend on, producing cascading NameError. Callers that don't pass a path
+  # get the legacy always-neutralize behavior.
+  def call(source, file_path: nil)
+    return source if file_path && !preloaded?(file_path)
+
+    result = Prism.parse(source)
+    return source if result.failure?
+
+    edits = collect_edits(result.value)
+    return source if edits.empty?
+
+    apply_edits(source, edits)
+  end
+
+  private
+
+  def preloaded?(file_path)
+    self.class.preloaded_features.include?(File.expand_path(file_path))
+  end
+
+  def collect_edits(tree)
+    edits = []
+    walker = Walker.new(IDEMPOTENT_CALLS, edits)
+    walker.visit(tree)
+    edits
+  end
+
+  def apply_edits(source, edits)
+    bytes = source.b
+    edits.sort_by!(&:first).reverse_each do |start_offset, end_offset|
+      bytes[start_offset, end_offset - start_offset] = "nil"
+    end
+    bytes.force_encoding(source.encoding)
+  end
+
+  class Walker < Prism::Visitor
+    def initialize(allowlist, edits)
+      super()
+      @allowlist = allowlist
+      @edits = edits
+    end
+
+    def visit_class_node(node)
+      scan_body(node.body)
+      super
+    end
+
+    def visit_module_node(node)
+      scan_body(node.body)
+      super
+    end
+
+    def visit_singleton_class_node(node)
+      scan_body(node.body)
+      super
+    end
+
+    private
+
+    # Examine top-level statements in a class/module body. Only direct-child
+    # CallNodes are candidates for neutralization. Calls nested inside any
+    # other expression (constant assignments, conditionals, etc.) are left
+    # alone — neutralizing them would break the surrounding expression.
+    # Nested class/module bodies are walked through the normal visitor.
+    def scan_body(body_node)
+      return unless body_node.is_a?(Prism::StatementsNode)
+
+      body_node.body.each do |stmt|
+        next unless stmt.is_a?(Prism::CallNode)
+        next if @allowlist.include?(stmt.name)
+        next if stmt.receiver && !stmt.receiver.is_a?(Prism::SelfNode)
+
+        @edits << [stmt.location.start_offset, replacement_end_offset(stmt)]
+      end
+    end
+
+    # Prism CallNode location ends at the close of the call syntax (e.g. the
+    # closing `)` or the `<<~MARKER` opener for a heredoc argument). It does
+    # NOT include the heredoc body lines or the trailing terminator. Replacing
+    # only the CallNode range leaves the heredoc body orphaned, producing a
+    # parse error. Extend the range to cover any heredoc terminators inside
+    # the call.
+    def replacement_end_offset(call)
+      collector = HeredocEndCollector.new
+      collector.visit(call)
+      [call.location.end_offset, *collector.end_offsets].max
+    end
+  end
+  private_constant :Walker
+
+  class HeredocEndCollector < Prism::Visitor
+    attr_reader :end_offsets
+
+    def initialize
+      super
+      @end_offsets = []
+    end
+
+    def visit_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    def visit_interpolated_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    def visit_interpolated_x_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    def visit_x_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    private
+
+    def record_if_heredoc(node)
+      return unless node.respond_to?(:heredoc?) && node.heredoc?
+
+      closing = node.closing_loc
+      return unless closing
+
+      # Prism's heredoc closing_loc includes the leading whitespace and the
+      # trailing newline of the terminator line (e.g. "    CODE\n"). Excluding
+      # that newline preserves line structure so subsequent code lands on its
+      # own line after the replacement.
+      end_off = closing.end_offset
+      slice = closing.slice
+      end_off -= 1 if slice && slice.end_with?("\n")
+      @end_offsets << end_off
+    end
+  end
+  private_constant :HeredocEndCollector
+end

data/lib/evilution/integration/loading/mutation_applier.rb

@@ -10,7 +10,15 @@ require_relative "redefinition_recovery"
 # Composes the load-time pipeline that applies a mutation's new source to the
 # running VM: syntax-validate -> pin top-level constants (beats Zeitwerk) ->
 # clear AS::Concern state -> eval inside a redefinition-recovery wrapper.
-# Returns nil on success or a failure-shaped hash on any error.
+# The eval target is mutation.eval_source, which Mutator::Base pre-populates
+# with the neutralized form (non-idempotent class-body calls replaced with
+# `nil`). The neutralization itself happens once at mutation-generation time
+# rather than per-iter — SyntaxValidator still runs Prism per mutation, but
+# the extra neutralizer parse stays out of the hot path. Falls back to
+# mutation.mutated_source when no pre-eval transform was attached.
+# RedefinitionRecovery stays as a safety net for cases the neutralizer's
+# allowlist heuristic misses. Returns nil on success or a failure-shaped
+# hash on any error.
 class Evilution::Integration::Loading::MutationApplier
   def initialize(syntax_validator: Evilution::Integration::Loading::SyntaxValidator.new,
                  constant_pinner: Evilution::Integration::Loading::ConstantPinner.new,
@@ -25,28 +33,40 @@ class Evilution::Integration::Loading::MutationApplier
   end
 
   def call(mutation)
-    syntax_error = @syntax_validator.call(mutation.mutated_source)
+    eval_target = resolve_eval_target(mutation)
+    syntax_error = @syntax_validator.call(eval_target)
     return syntax_error if syntax_error
 
+    apply(mutation, eval_target)
+    nil
+  rescue SyntaxError => e
+    failure_result(e, "syntax error in mutated source: #{e.message}")
+  rescue ScriptError, StandardError => e
+    failure_result(e, "#{e.class}: #{e.message}")
+  end
+
+  private
+
+  def resolve_eval_target(mutation)
+    return mutation.eval_source if mutation.respond_to?(:eval_source)
+
+    mutation.mutated_source
+  end
+
+  def apply(mutation, eval_target)
     @constant_pinner.call(mutation.original_source)
     @concern_state_cleaner.call(mutation.file_path)
     @redefinition_recovery.call(mutation.original_source) do
-      @source_evaluator.call(mutation.mutated_source, mutation.file_path)
+      @source_evaluator.call(eval_target, mutation.file_path)
     end
-    nil
-  rescue SyntaxError => e
-    {
-      passed: false,
-      error: "syntax error in mutated source: #{e.message}",
-      error_class: e.class.name,
-      error_backtrace: Array(e.backtrace).first(5)
-    }
-  rescue ScriptError, StandardError => e
+  end
+
+  def failure_result(error, message)
     {
       passed: false,
-      error: "#{e.class}: #{e.message}",
-      error_class: e.class.name,
-      error_backtrace: Array(e.backtrace).first(5)
+      error: message,
+      error_class: error.class.name,
+      error_backtrace: Array(error.backtrace).first(5)
     }
   end
 end

data/lib/evilution/integration/loading/redefinition_recovery.rb

@@ -6,7 +6,22 @@ require_relative "../../ast/constant_names"
 # Some DSLs (Rails 8 enum, define_method guards) raise ArgumentError on
 # re-declaration. On such a conflict we strip constants declared in the source
 # and retry the load once against a fresh namespace.
+#
+# A second class of idempotency violation comes from gem-internal registries
+# (dry-monads `register_mixin`, Rails plugins, etc.) which raise when called
+# a second time in the same process. For these we swallow the error: the
+# class body executed up to the raise point — method defs preceding the
+# registry call are already in place — and any state change blocked by the
+# guard was intentional duplicate-prevention from the gem's side. Mutations
+# that target a def *after* such a class-body call would not be applied;
+# emit a one-shot warning so that mode is visible.
 class Evilution::Integration::Loading::RedefinitionRecovery
+  IDEMPOTENCY_PATTERNS = [
+    "already registered",
+    "already initialized",
+    "already exists"
+  ].freeze
+
   def initialize(constant_names: Evilution::AST::ConstantNames.new)
     @constant_names = constant_names
   end
@@ -14,8 +29,28 @@ class Evilution::Integration::Loading::RedefinitionRecovery
   def call(source, &block)
     block.call
   rescue ArgumentError => e
-    raise unless redefinition_conflict?(e)
+    if redefinition_conflict?(e)
+      remove_defined_constants(source)
+      block.call
+    elsif idempotency_violation?(e)
+      warn_once_for(e)
+      nil
+    else
+      raise
+    end
+  rescue TypeError => e
+    raise unless superclass_mismatch?(e)
 
+    # `class X < Struct.new(...)` (or Data.define / Class.new in the same
+    # position) returns a fresh anonymous parent class on every call, so the
+    # recorded superclass of the existing X differs from the re-eval's. Ruby
+    # raises TypeError. Simply swallowing would leave the *original* class
+    # in place and silently report the mutation as survived — a false
+    # negative. Instead, strip the constants this source declares and retry
+    # exactly once, mirroring the ArgumentError 'already defined' path. If
+    # the retry still mismatches (genuine inheritance conflict the mutation
+    # cannot resolve), propagate so the mutation reports :error rather than
+    # being silently miscounted.
     remove_defined_constants(source)
     block.call
   end
@@ -26,6 +61,28 @@ class Evilution::Integration::Loading::RedefinitionRecovery
     error.message.include?("already defined")
   end
 
+  def idempotency_violation?(error)
+    msg = error.message
+    IDEMPOTENCY_PATTERNS.any? { |pat| msg.include?(pat) }
+  end
+
+  def superclass_mismatch?(error)
+    error.message.include?("superclass mismatch")
+  end
+
+  def warn_once_for(error)
+    return if @warned_messages&.include?(error.message)
+
+    @warned_messages ||= []
+    @warned_messages << error.message
+    $stderr.write(
+      "[evilution] swallowed idempotency violation on re-eval: " \
+      "#{error.class}: #{error.message}. " \
+      "Method defs preceding the raise point were re-applied; " \
+      "mutations targeting code after the raise will not take effect.\n"
+    )
+  end
+
   def remove_defined_constants(source)
     @constant_names.call(source).reverse_each do |name|
       parent_name, _, local_name = name.rpartition("::")

data/lib/evilution/integration/minitest.rb

@@ -10,22 +10,61 @@ require_relative "../integration"
 
 class Evilution::Integration::Minitest < Evilution::Integration::Base
   def self.baseline_runner
-    lambda { |test_file|
-      require "minitest"
-      require "stringio"
-      ::Minitest::Runnable.runnables.clear
-      files = File.directory?(test_file) ? Dir.glob(File.join(test_file, "**/*_test.rb")) : [test_file]
-      files.each { |f| load(File.expand_path(f)) }
-      out = StringIO.new
-      options = ::Minitest.process_args(["--seed", "0"])
-      options[:io] = out
-      reporter = ::Minitest::CompositeReporter.new
-      reporter << ::Minitest::SummaryReporter.new(out, options)
-      reporter.start
+    ->(test_file) { run_baseline_test_file(test_file) }
+  end
+
+  def self.run_baseline_test_file(test_file)
+    require "minitest"
+    require "stringio"
+    ::Minitest::Runnable.runnables.clear
+    baseline_test_files(test_file).each { |f| load(File.expand_path(f)) }
+    run_baseline_minitest
+  end
+
+  def self.baseline_test_files(test_file)
+    File.directory?(test_file) ? Dir.glob(File.join(test_file, "**/*_test.rb")) : [test_file]
+  end
+
+  def self.run_baseline_minitest
+    out = StringIO.new
+    options = ::Minitest.process_args(["--seed", "0"])
+    options[:io] = out
+    reporter = ::Minitest::CompositeReporter.new
+    reporter << ::Minitest::SummaryReporter.new(out, options)
+    initialize_minitest_state(reporter, options)
+    reporter.start
+    dispatch_minitest_suites(reporter, options)
+    reporter.report
+    reporter.passed?
+  end
+
+  # Mirror Minitest.run's preamble: seed setup + plugin init. Without seeding
+  # Minitest.seed before dispatching suites, Minitest 5.x raises
+  # `TypeError: no implicit conversion of nil into Integer` from
+  # Minitest::Test.runnable_methods calling `srand(Minitest.seed)` on nil.
+  # init_plugins also needs Minitest.reporter set first because some plugins
+  # (pride) read it during init.
+  def self.initialize_minitest_state(reporter, options)
+    ::Minitest.seed = options[:seed]
+    srand(::Minitest.seed) if ::Minitest.seed
+
+    ::Minitest.reporter = reporter
+    ::Minitest.init_plugins(options) if ::Minitest.respond_to?(:init_plugins)
+    ::Minitest.reporter = nil
+  end
+
+  # Dispatch to the version-appropriate suite runner. Minitest 6 removed
+  # ::Minitest.__run; the equivalent public entry point is run_all_suites.
+  # Minitest 5.x still exposes __run.
+  def self.dispatch_minitest_suites(reporter, options)
+    if ::Minitest.respond_to?(:run_all_suites)
+      ::Minitest.run_all_suites(reporter, options)
+    elsif ::Minitest.respond_to?(:__run)
       ::Minitest.__run(reporter, options)
-      reporter.report
-      reporter.passed?
-    }
+    else
+      raise Evilution::Error,
+            "Minitest #{::Minitest::VERSION} has neither run_all_suites nor __run"
+    end
   end
 
   def self.baseline_options
@@ -107,13 +146,18 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     reporter << ::Minitest::SummaryReporter.new(out, options)
     reporter << detector
 
+    self.class.initialize_minitest_state(reporter, options)
     reporter.start
-    ::Minitest.__run(reporter, options)
+    dispatch_minitest_suites(reporter, options)
     reporter.report
 
     reporter.passed?
   end
 
+  def dispatch_minitest_suites(reporter, options)
+    self.class.dispatch_minitest_suites(reporter, options)
+  end
+
   def reset_crash_detector
     if @crash_detector
       @crash_detector.reset

data/lib/evilution/integration/rspec/result_builder.rb

@@ -21,7 +21,7 @@ class Evilution::Integration::RSpec::ResultBuilder
     }
   end
 
-  def from_run(status, command, detector)
+  def from_run(status, command, detector, examples_loaded: nil)
     return { passed: true, test_command: command } if status.zero?
 
     if detector.only_crashes?
@@ -35,6 +35,25 @@ class Evilution::Integration::RSpec::ResultBuilder
       }
     end
 
+    # Nonzero exit + zero examples loaded = the spec file did not register any
+    # examples (load error, autoload mismatch, etc.), so nothing ran against
+    # the mutation. Surfacing this as a generic fail would let classify_status
+    # fall through to its :killed default and silently inflate the kill count
+    # even though no example ever observed the mutation (EV-720r: macOS Rails
+    # users hit autoload / fail_if_no_examples paths that yielded killed=100%
+    # with empty worker output). Note: this checks LOADED count, not executed
+    # count — filters/skip/--fail-fast can leave loaded > executed, but the
+    # "spec failed to load entirely" case is the failure mode this guard targets.
+    if !examples_loaded.nil? && examples_loaded.zero?
+      return {
+        passed: false,
+        error: "RSpec exited #{status} but loaded 0 examples — no examples ran against the mutation. " \
+               "Likely the spec file failed to load, --spec was misrouted, or RSpec is configured " \
+               "with fail_if_no_examples. The mutation cannot be counted as killed.",
+        test_command: command
+      }
+    end
+
     { passed: false, test_command: command }
   end
 end