evilution 0.29.0 → 0.30.0

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,10 +33,11 @@ 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)
+    apply(mutation, eval_target)
     nil
   rescue SyntaxError => e
     failure_result(e, "syntax error in mutated source: #{e.message}")
@@ -38,11 +47,17 @@ class Evilution::Integration::Loading::MutationApplier
 
   private
 
-  def apply(mutation)
+  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
   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

@@ -31,12 +31,42 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     options[:io] = out
     reporter = ::Minitest::CompositeReporter.new
     reporter << ::Minitest::SummaryReporter.new(out, options)
+    initialize_minitest_state(reporter, options)
     reporter.start
-    ::Minitest.__run(reporter, options)
+    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)
+    else
+      raise Evilution::Error,
+            "Minitest #{::Minitest::VERSION} has neither run_all_suites nor __run"
+    end
+  end
+
   def self.baseline_options
     {
       runner: baseline_runner,
@@ -116,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

data/lib/evilution/integration/rspec.rb

@@ -82,7 +82,7 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     snapshot = @state_guard.snapshot
     begin
       status = ::RSpec::Core::Runner.run(args, StringIO.new, StringIO.new)
-      @result_builder.from_run(status, command, detector)
+      @result_builder.from_run(status, command, detector, examples_loaded:)
     rescue StandardError => e
       { passed: false, error: e.message, test_command: command }
     ensure
@@ -90,6 +90,21 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     end
   end
 
+  # Count of examples loaded into RSpec.world by this run. Used to distinguish
+  # "test failed → mutation killed" (positive count, nonzero status) from
+  # "spec file failed to load / RSpec returned nonzero with nothing observed"
+  # (zero count, nonzero status). The latter must NOT be classified as killed
+  # — silently counting it would inflate scores with mutations no example
+  # actually saw (EV-720r).
+  def examples_loaded
+    world = ::RSpec.world
+    return nil unless world.respond_to?(:example_count)
+
+    world.example_count
+  rescue StandardError
+    nil
+  end
+
   def reset_examples
     ::RSpec.respond_to?(:clear_examples) ? ::RSpec.clear_examples : ::RSpec.reset
   end

data/lib/evilution/isolation/fork.rb

@@ -52,7 +52,9 @@ class Evilution::Isolation::Fork
       suppress_child_output
       @hooks.fire(:worker_process_start, mutation:) if @hooks
       result = execute_in_child(mutation, test_command)
-      Marshal.dump(result, write_io)
+      payload = Marshal.dump(result)
+      write_io.write([payload.bytesize].pack("N"))
+      write_io.write(payload)
       write_io.close
       exit!(result[:passed] ? 0 : 1)
     end
@@ -91,20 +93,85 @@ class Evilution::Isolation::Fork
     }
   end
 
+  # Length-prefixed read with waitpid polling. Subject specs that exercise
+  # Process.fork inside test_command leave a grandchild that inherits write_io
+  # via fork — if the grandchild outlives the child, a plain `read_io.read`
+  # never sees EOF and hangs forever. The length prefix makes payload reads
+  # bounded; the waitpid-WNOHANG check inside the poll loop lets us exit
+  # promptly when the child died without writing anything.
   def wait_for_result(pid, read_io, timeout)
-    if read_io.wait_readable(timeout)
-      data = read_io.read
-      ::Process.wait(pid)
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+    loop do
+      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return timeout_result(pid) if remaining <= 0
+
+      if read_io.wait_readable([remaining, 0.5].min)
+        payload = read_payload(read_io, deadline)
+        return reap_and_decode(pid, payload) if payload
+      end
+
+      next unless ::Process.waitpid(pid, ::Process::WNOHANG)
+
+      # Child exited. Drain any final payload that arrived between
+      # wait_readable timeout and waitpid (race) before declaring empty.
+      final = read_payload(read_io, Process.clock_gettime(Process::CLOCK_MONOTONIC) + 0.1)
+      return decode_payload(final) if final
+
+      return empty_result
+    end
+  end
+
+  def reap_and_decode(pid, payload)
+    ::Process.wait(pid)
+    decode_payload(payload)
+  end
+
+  def read_payload(read_io, deadline)
+    header = read_n_bytes(read_io, 4, deadline)
+    return nil unless header
+
+    size = header.unpack1("N")
+    read_n_bytes(read_io, size, deadline)
+  end
 
-      if data.empty?
-        { timeout: false, passed: false, error: "empty result from child" }
+  # Bounded non-blocking read. Returns `count` bytes or nil on EOF / deadline.
+  # Uses `read_nonblock` so a child that wrote a partial frame (e.g. wrote the
+  # header then died with a grandchild keeping write_io open) cannot extend
+  # past the polling deadline.
+  def read_n_bytes(read_io, count, deadline)
+    return "" if count.zero?
+
+    buf = +""
+    while buf.bytesize < count
+      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return nil if remaining <= 0
+
+      chunk = read_io.read_nonblock(count - buf.bytesize, exception: false)
+      case chunk
+      when :wait_readable
+        return nil unless read_io.wait_readable([remaining, 0.5].min)
+      when nil
+        return nil
       else
-        { timeout: false }.merge(Marshal.load(data))
+        buf << chunk
       end
-    else
-      terminate_child(pid)
-      { timeout: true }
     end
+    buf
+  end
+
+  def decode_payload(data)
+    return empty_result if data.nil? || data.empty?
+
+    { timeout: false }.merge(Marshal.load(data))
+  end
+
+  def empty_result
+    { timeout: false, passed: false, error: "empty result from child" }
+  end
+
+  def timeout_result(pid)
+    terminate_child(pid)
+    { timeout: true }
   end
 
   # Defensive reap: if normal control flow raised before wait_for_result

data/lib/evilution/mcp/info_tool/response_formatter.rb

@@ -7,10 +7,23 @@ require_relative "error_mapper"
 module Evilution::MCP::InfoTool::ResponseFormatter
   module_function
 
+  # Wraps the payload as a successful MCP text response and injects the
+  # outer-envelope schema_version so agents that cache contracts can detect
+  # incompatible servers. Existing schema_version keys in the payload are
+  # preserved (e.g. session JSON keeps its own schema_version unchanged).
   def success(payload)
-    ::MCP::Tool::Response.new([{ type: "text", text: ::JSON.generate(payload) }])
+    versioned = inject_schema_version(payload)
+    ::MCP::Tool::Response.new([{ type: "text", text: ::JSON.generate(versioned) }])
   end
 
+  def inject_schema_version(payload)
+    return payload unless payload.is_a?(Hash)
+    return payload if payload.key?("schema_version") || payload.key?(:schema_version)
+
+    { "schema_version" => Evilution::MCP::CONTRACT_VERSION }.merge(payload)
+  end
+  private_class_method :inject_schema_version
+
   def error(type, message)
     ::MCP::Tool::Response.new(
       [{ type: "text", text: ::JSON.generate({ error: { type: type, message: message } }) }],

data/lib/evilution/mcp/info_tool.rb

@@ -27,7 +27,9 @@ class Evilution::MCP::InfoTool < MCP::Tool
               "'feedback' returns the public discussion URL plus consent and privacy guidance for posting " \
               "feedback on errors, usage problems, friction, or missing capabilities. " \
               "Use this instead of shelling out to 'evilution subjects', 'evilution tests list', or 'evilution environment show' — " \
-              "the response is structured JSON so you can plan the next mutation run without parsing CLI text."
+              "the response is structured JSON so you can plan the next mutation run without parsing CLI text. " \
+              "Contract: input schema, action enum, and per-action output shapes are stable for the 1.x line; " \
+              "see README \"MCP Server\" section for the full deprecation policy."
   input_schema(
     properties: {
       action: {

data/lib/evilution/mcp/mutate_tool/option_parser.rb

@@ -5,7 +5,7 @@ require_relative "../mutate_tool"
 module Evilution::MCP::MutateTool::OptionParser
   VALID_VERBOSITIES = %w[full summary minimal].freeze
   PASSTHROUGH_KEYS = %i[target timeout jobs fail_fast suggest_tests incremental integration
-                        isolation baseline save_session].freeze
+                        isolation baseline save_session preload].freeze
   ALLOWED_OPT_KEYS = (PASSTHROUGH_KEYS + %i[spec skip_config]).freeze
 
   ParsedPaths = Data.define(:files, :ranges)