evilution 0.28.0 → 0.30.0

data/lib/evilution/mcp/session_tool.rb

@@ -15,7 +15,9 @@ class Evilution::MCP::SessionTool < MCP::Tool
               "'show' returns the full report for a session (summary, survived mutations with diffs, git context), " \
               "'diff' compares two sessions and surfaces new regressions, fixed mutations, persistent survivors, and score delta. " \
               "Prefer this over the CLI when auditing mutation score trends, triaging survivors, " \
-              "or verifying that a fix killed the right mutant."
+              "or verifying that a fix killed the right mutant. " \
+              "Contract: input schema, action enum, and output payloads are stable for the 1.x line; " \
+              "see README \"MCP Server\" section for the full deprecation policy."
   input_schema(
     properties: {
       action: {
@@ -50,6 +52,9 @@ class Evilution::MCP::SessionTool < MCP::Tool
 
   VALID_ACTIONS = %w[list show diff].freeze
 
+  LimitResult = Data.define(:limit, :error)
+  private_constant :LimitResult
+
   class << self
     def call(server_context:, action: nil, results_dir: nil, limit: nil, path: nil, base: nil, head: nil)
       return error_response("config_error", "action is required") unless action
@@ -65,28 +70,28 @@ class Evilution::MCP::SessionTool < MCP::Tool
     private
 
     def list_action(results_dir:, limit:)
-      normalized_limit, limit_error = normalize_limit(limit)
-      return error_response("config_error", limit_error) if limit_error
+      result = normalize_limit(limit)
+      return error_response("config_error", result.error) if result.error
 
       store_opts = {}
       store_opts[:results_dir] = results_dir if results_dir
       store = Evilution::Session::Store.new(**store_opts)
       entries = store.list
-      entries = entries.first(normalized_limit) unless normalized_limit.nil?
+      entries = entries.first(result.limit) unless result.limit.nil?
 
-      payload = entries.map { |e| e.transform_keys(&:to_s) }
-      success_response(payload)
+      sessions = entries.map { |e| e.transform_keys(&:to_s) }
+      success_response("schema_version" => Evilution::MCP::CONTRACT_VERSION, "sessions" => sessions)
     end
 
     def normalize_limit(limit)
-      return [nil, nil] if limit.nil?
+      return LimitResult.new(limit: nil, error: nil) if limit.nil?
 
       coerced = Integer(limit)
-      return [nil, "limit must be a non-negative integer"] if coerced.negative?
+      return LimitResult.new(limit: nil, error: "limit must be a non-negative integer") if coerced.negative?
 
-      [coerced, nil]
+      LimitResult.new(limit: coerced, error: nil)
     rescue ArgumentError, TypeError
-      [nil, "limit must be a non-negative integer"]
+      LimitResult.new(limit: nil, error: "limit must be a non-negative integer")
     end
 
     def show_action(path:, results_dir:)
@@ -107,20 +112,13 @@ class Evilution::MCP::SessionTool < MCP::Tool
     end
 
     def diff_action(base:, head:, results_dir:)
-      return error_response("config_error", "base is required") unless base
-      return error_response("config_error", "head is required") unless head
-
       dir = results_dir || Evilution::Session::Store::DEFAULT_DIR
-      return error_response("config_error", "base must be under results directory") unless within?(base, dir)
-      return error_response("config_error", "head must be under results directory") unless within?(head, dir)
+      validation = validate_diff_args(base, head, dir)
+      return validation if validation
 
-      store = Evilution::Session::Store.new(results_dir: dir)
-      base_data = store.load(base)
-      head_data = store.load(head)
-
-      diff = Evilution::Session::Diff.new
-      result = diff.call(base_data, head_data)
-      success_response(result.to_h)
+      result = load_and_diff(base, head, dir)
+      payload = { "schema_version" => Evilution::MCP::CONTRACT_VERSION }.merge(result.to_h)
+      success_response(payload)
     rescue Evilution::Error => e
       error_response("not_found", e.message)
     rescue ::JSON::ParserError => e
@@ -129,6 +127,20 @@ class Evilution::MCP::SessionTool < MCP::Tool
       error_response("runtime_error", e.message)
     end
 
+    def validate_diff_args(base, head, dir)
+      return error_response("config_error", "base is required") unless base
+      return error_response("config_error", "head is required") unless head
+      return error_response("config_error", "base must be under results directory") unless within?(base, dir)
+      return error_response("config_error", "head must be under results directory") unless within?(head, dir)
+
+      nil
+    end
+
+    def load_and_diff(base, head, dir)
+      store = Evilution::Session::Store.new(results_dir: dir)
+      Evilution::Session::Diff.new.call(store.load(base), store.load(head))
+    end
+
     def within?(path, results_dir)
       resolved_root = canonical_path(results_dir)
       resolved_path = canonical_path(path)

data/lib/evilution/mcp.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
 
 module Evilution::MCP
+  # Public contract version for the evilution MCP tool surface (input schemas,
+  # output payload shapes, error envelope, action enumerations). Bumped only
+  # at MAJOR releases per docs/versioning.md. Independent of session JSON
+  # schema versioning (Evilution::Session::Schema) so the two surfaces can
+  # rev separately.
+  CONTRACT_VERSION = 1
 end

data/lib/evilution/mutation.rb

@@ -10,13 +10,15 @@ class Evilution::Mutation
 
   attr_reader :subject, :operator_name, :parse_status, :location
 
-  def initialize(subject:, operator_name:, sources:, location:, slice: nil, parse_status: :ok)
+  def initialize(subject:, operator_name:, sources:, location:,
+                 slice: nil, parse_status: :ok, eval_source: nil)
     @subject = subject
     @operator_name = operator_name
     @sources = sources
     @location = location
     @slice = slice
     @parse_status = parse_status
+    @eval_source = eval_source
     @diff = nil
   end
 
@@ -28,6 +30,16 @@ class Evilution::Mutation
     @sources&.mutated
   end
 
+  # Source to feed to the load-time evaluator. Defaults to mutated_source
+  # when no pre-eval transform was applied at generation time. Mutator::Base
+  # populates this with the neutralized version (top-level idempotency-
+  # violating calls replaced with `nil`) so the worker eval doesn't re-run
+  # them. The neutralization Prism parse happens once at generation time,
+  # not per worker iteration.
+  def eval_source
+    @eval_source || mutated_source
+  end
+
   def original_slice
     @slice&.original
   end
@@ -74,22 +86,17 @@ class Evilution::Mutation
   private
 
   def compute_diff
-    original_lines = original_source.lines
-    mutated_lines = mutated_source.lines
-    diffs = ::Diff::LCS.diff(original_lines, mutated_lines)
-
+    diffs = ::Diff::LCS.diff(original_source.lines, mutated_source.lines)
     return "" if diffs.empty?
 
-    result = []
-    diffs.flatten(1).each do |change|
-      case change.action
-      when "-"
-        result << "- #{change.element.chomp}"
-      when "+"
-        result << "+ #{change.element.chomp}"
-      end
+    diffs.flatten(1).filter_map { |change| format_diff_change(change) }.join("\n")
+  end
+
+  def format_diff_change(change)
+    case change.action
+    when "-" then "- #{change.element.chomp}"
+    when "+" then "+ #{change.element.chomp}"
     end
-    result.join("\n")
   end
 
   def compute_unified_diff
@@ -97,15 +104,18 @@ class Evilution::Mutation
 
     original_lines = @slice.original.lines
     mutated_lines = @slice.mutated.lines
-    body = ::Diff::LCS.sdiff(original_lines, mutated_lines).map { |c| format_sdiff_change(c) }.join("\n")
     [
       "--- a/#{file_path}",
       "+++ b/#{file_path}",
       "@@ -#{line},#{original_lines.length} +#{line},#{mutated_lines.length} @@",
-      body
+      unified_diff_body(original_lines, mutated_lines)
     ].reject(&:empty?).join("\n")
   end
 
+  def unified_diff_body(original_lines, mutated_lines)
+    ::Diff::LCS.sdiff(original_lines, mutated_lines).map { |c| format_sdiff_change(c) }.join("\n")
+  end
+
   def format_sdiff_change(change)
     case change.action
     when "=" then " #{change.old_element.chomp}"

data/lib/evilution/mutator/base.rb

@@ -3,14 +3,31 @@
 require "prism"
 
 require_relative "../mutator"
+require_relative "../integration/loading/body_call_neutralizer"
+require_relative "../ast/heredoc_span"
 
 class Evilution::Mutator::Base < Prism::Visitor
+  AffectedSlices = Data.define(:original, :mutated)
+  private_constant :AffectedSlices
+
+  # Match a heredoc anchor `<<MARKER` / `<<-MARKER` / `<<~MARKER` (optionally
+  # quoted) when the identifier sits directly against the `<<` (or its
+  # `-`/`~`/quote prefix). The space-separated forms `arr << x`, `1 << 2`,
+  # `class << self` deliberately do NOT match — `<<` alone is also Ruby's
+  # shift / append / singleton-class operator, and skipping mutations that
+  # only contain those would lose useful coverage. False positive on the
+  # unusual no-space shift `obj<<value` is accepted (over-skip is safer than
+  # emitting an unparseable mutation).
+  HEREDOC_ANCHOR_PATTERN = /<<[-~]?["'`]?[A-Za-z_]/
+  private_constant :HEREDOC_ANCHOR_PATTERN
+
   attr_reader :mutations
 
   def initialize(**_options)
     @mutations = []
     @subject = nil
     @file_source = nil
+    @body_call_neutralizer = Evilution::Integration::Loading::BodyCallNeutralizer.new
   end
 
   def call(subject, filter: nil)
@@ -27,35 +44,68 @@ class Evilution::Mutator::Base < Prism::Visitor
   def add_mutation(offset:, length:, replacement:, node:)
     return if @filter && @filter.skip?(node)
 
-    surgery = Evilution::AST::SourceSurgeon.apply(
-      @file_source,
-      offset: offset,
-      length: length,
-      replacement: replacement
+    # When the byte range opens a heredoc but stops at its inline anchor,
+    # extend it to cover the body+terminator. Without this every operator
+    # whose edit straddles a `<<~MARKER` anchor (argument_removal,
+    # argument_nil_substitution, method_call_removal, statement_deletion,
+    # method_body_replacement, block_removal, conditional_branch,
+    # string_interpolation, ...) emits an orphan-heredoc unparseable.
+    extended_length = Evilution::AST::HeredocSpan.extend_length(
+      node: node, offset: offset, length: length
     )
-    mutated_source = surgery.source
 
-    original_slice, mutated_slice = slice_affected_lines(
-      mutated_source: mutated_source,
+    # If the replacement re-references a heredoc anchor (e.g. argument_removal
+    # rebuilding the args list with a kept `<<~MSG` arg), we cannot safely
+    # extend the range — doing so would strip the kept heredoc's body without
+    # putting it back. Skip the mutation rather than emit unparseable bytes.
+    # When the replacement is heredoc-free (nil, "", a literal, or a non-
+    # heredoc kept arg), extension cleanly sweeps the orphaned body+terminator.
+    return if extended_length > length && replacement.match?(HEREDOC_ANCHOR_PATTERN)
+
+    length = extended_length
+
+    surgery = Evilution::AST::SourceSurgeon.apply(
+      @file_source, offset: offset, length: length, replacement: replacement
+    )
+    slices = slice_affected_lines(
+      mutated_source: surgery.source,
       offset: offset,
       length: length,
       replacement_bytesize: replacement.bytesize
     )
 
-    @mutations << Evilution::Mutation.new(
+    @mutations << build_mutation_record(node, surgery, slices)
+  end
+
+  def build_mutation_record(node, surgery, slices)
+    Evilution::Mutation.new(
       subject: @subject,
       operator_name: self.class.operator_name,
-      sources: Evilution::Mutation::Sources.new(original: @file_source, mutated: mutated_source),
-      slice: Evilution::Mutation::Slice.new(original: original_slice, mutated: mutated_slice),
+      sources: Evilution::Mutation::Sources.new(original: @file_source, mutated: surgery.source),
+      slice: Evilution::Mutation::Slice.new(original: slices.original, mutated: slices.mutated),
       location: Evilution::Mutation::Location.new(
         file_path: @subject.file_path,
         line: node.location.start_line,
         column: node.location.start_column
       ),
-      parse_status: surgery.status
+      parse_status: surgery.status,
+      eval_source: build_eval_source(surgery)
     )
   end
 
+  # Pre-compute the worker's eval target so per-iter Prism re-parse cost
+  # stays out of the hot path. For parseable mutations we strip class/module
+  # body calls that are known to be non-idempotent (registries etc.); for
+  # unparseable bytes we fall through so the syntax validator can reject
+  # them at apply time. Passing the subject's file path lets the neutralizer
+  # skip files the parent never preloaded — those are lazy plugin files whose
+  # DSL calls are still needed for the child fork's first-time load.
+  def build_eval_source(surgery)
+    return surgery.source unless surgery.ok?
+
+    @body_call_neutralizer.call(surgery.source, file_path: @subject.file_path)
+  end
+
   NEWLINE_BYTE = 10
   private_constant :NEWLINE_BYTE
 
@@ -64,10 +114,10 @@ class Evilution::Mutator::Base < Prism::Visitor
     orig_line_end = line_end_byte(@file_source, [offset + length - 1, line_start].max)
     mut_line_end = line_end_byte(mutated_source, [offset + replacement_bytesize - 1, line_start].max)
 
-    [
-      @file_source.byteslice(line_start, orig_line_end - line_start),
-      mutated_source.byteslice(line_start, mut_line_end - line_start)
-    ]
+    AffectedSlices.new(
+      original: @file_source.byteslice(line_start, orig_line_end - line_start),
+      mutated: mutated_source.byteslice(line_start, mut_line_end - line_start)
+    )
   end
 
   def line_start_byte(source, offset)

data/lib/evilution/mutator/operator/argument_method_call_replacement.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../operator"
+
+# Replaces a method-call argument with its receiver: `fn(x.attr)` -> `fn(x)`.
+# High-signal for log payloads, structured-data construction, and API
+# request bodies where a method call on a local variable / param appears in
+# argument position. Covered byte-wise by `MethodCallRemoval` already; this
+# operator surfaces the same byte change under a more specific name so the
+# argument-substitution pattern is legible in mutation output.
+#
+# Fires for:
+# - positional / keyword arguments of any CallNode
+# - hash values inside HashNode / KeywordHashNode (incl. inside call args)
+# - array elements inside ArrayNode
+class Evilution::Mutator::Operator::ArgumentMethodCallReplacement < Evilution::Mutator::Base
+  def visit_call_node(node)
+    node.arguments.arguments.each { |arg| try_replace(arg) } if node.arguments
+
+    super
+  end
+
+  def visit_array_node(node)
+    node.elements.each { |element| try_replace(element) }
+    super
+  end
+
+  def visit_hash_node(node)
+    process_assocs(node.elements)
+    super
+  end
+
+  def visit_keyword_hash_node(node)
+    process_assocs(node.elements)
+    super
+  end
+
+  private
+
+  def process_assocs(elements)
+    elements.each do |assoc|
+      next unless assoc.is_a?(Prism::AssocNode)
+
+      try_replace(assoc.value)
+    end
+  end
+
+  def try_replace(value)
+    return unless value.is_a?(Prism::CallNode)
+    return unless value.receiver
+
+    add_mutation(
+      offset: value.location.start_offset,
+      length: value.location.length,
+      replacement: value.receiver.slice,
+      node: value
+    )
+  end
+end

data/lib/evilution/mutator/operator/argument_nil_substitution.rb

@@ -12,26 +12,23 @@ class Evilution::Mutator::Operator::ArgumentNilSubstitution < Evilution::Mutator
 
   def visit_call_node(node)
     args = node.arguments&.arguments
-
-    if mutable?(node, args)
-      args.each_index do |i|
-        parts = args.each_with_index.map { |a, j| j == i ? "nil" : a.slice }
-        replacement = parts.join(", ")
-
-        add_mutation(
-          offset: node.arguments.location.start_offset,
-          length: node.arguments.location.length,
-          replacement: replacement,
-          node: node
-        )
-      end
-    end
+    args.each_index { |i| emit_nil_substitution(node, args, i) } if mutable?(node, args)
 
     super
   end
 
   private
 
+  def emit_nil_substitution(node, args, i)
+    parts = args.each_with_index.map { |a, j| j == i ? "nil" : a.slice }
+    add_mutation(
+      offset: node.arguments.location.start_offset,
+      length: node.arguments.location.length,
+      replacement: parts.join(", "),
+      node: node
+    )
+  end
+
   def mutable?(node, args)
     args && args.length >= 1 && positional_only?(args) && node.name != :[]=
   end

data/lib/evilution/mutator/operator/argument_removal.rb

@@ -12,26 +12,23 @@ class Evilution::Mutator::Operator::ArgumentRemoval < Evilution::Mutator::Base
 
   def visit_call_node(node)
     args = node.arguments&.arguments
-
-    if mutable?(node, args)
-      args.each_index do |i|
-        remaining = args.each_with_index.filter_map { |a, j| a.slice if j != i }
-        replacement = remaining.join(", ")
-
-        add_mutation(
-          offset: node.arguments.location.start_offset,
-          length: node.arguments.location.length,
-          replacement:,
-          node:
-        )
-      end
-    end
+    args.each_index { |i| emit_argument_removal(node, args, i) } if mutable?(node, args)
 
     super
   end
 
   private
 
+  def emit_argument_removal(node, args, i)
+    remaining = args.each_with_index.filter_map { |a, j| a.slice if j != i }
+    add_mutation(
+      offset: node.arguments.location.start_offset,
+      length: node.arguments.location.length,
+      replacement: remaining.join(", "),
+      node: node
+    )
+  end
+
   def mutable?(node, args)
     args && args.length >= 2 && positional_only?(args) && node.name != :[]=
   end

data/lib/evilution/mutator/operator/begin_unwrap.rb

@@ -4,18 +4,30 @@ require_relative "../operator"
 
 class Evilution::Mutator::Operator::BeginUnwrap < Evilution::Mutator::Base
   def visit_begin_node(node)
-    return super if node.rescue_clause || node.else_clause || node.ensure_clause
-    return super if node.statements.nil?
-    return super if node.begin_keyword_loc.nil?
+    return super unless unwrappable?(node)
 
-    body_text = @file_source.byteslice(node.statements.location.start_offset, node.statements.location.length)
     add_mutation(
       offset: node.location.start_offset,
       length: node.location.length,
-      replacement: body_text,
+      replacement: body_text(node),
       node: node
     )
 
     super
   end
+
+  private
+
+  def unwrappable?(node)
+    return false if node.rescue_clause || node.else_clause || node.ensure_clause
+    return false if node.statements.nil?
+    return false if node.begin_keyword_loc.nil?
+
+    true
+  end
+
+  def body_text(node)
+    loc = node.statements.location
+    @file_source.byteslice(loc.start_offset, loc.length)
+  end
 end

data/lib/evilution/mutator/operator/bitwise_complement.rb

@@ -5,27 +5,34 @@ require_relative "../operator"
 class Evilution::Mutator::Operator::BitwiseComplement < Evilution::Mutator::Base
   def visit_call_node(node)
     if node.name == :~ && node.receiver && node.arguments.nil?
-      loc = node.message_loc
-      receiver_loc = node.receiver.location
-
-      # Remove ~: replace entire ~expr with just the receiver expression
-      receiver_source = byteslice_source(receiver_loc.start_offset, receiver_loc.length)
-      add_mutation(
-        offset: node.location.start_offset,
-        length: node.location.length,
-        replacement: receiver_source,
-        node: node
-      )
-
-      # Swap ~ with unary minus
-      add_mutation(
-        offset: loc.start_offset,
-        length: loc.length,
-        replacement: "-",
-        node: node
-      )
+      emit_remove_complement(node)
+      emit_swap_to_minus(node)
     end
 
     super
   end
+
+  private
+
+  # Replace `~expr` with just `expr`.
+  def emit_remove_complement(node)
+    receiver_loc = node.receiver.location
+    add_mutation(
+      offset: node.location.start_offset,
+      length: node.location.length,
+      replacement: byteslice_source(receiver_loc.start_offset, receiver_loc.length),
+      node: node
+    )
+  end
+
+  # Swap `~` with unary minus.
+  def emit_swap_to_minus(node)
+    loc = node.message_loc
+    add_mutation(
+      offset: loc.start_offset,
+      length: loc.length,
+      replacement: "-",
+      node: node
+    )
+  end
 end

data/lib/evilution/mutator/operator/block_param_removal.rb

@@ -6,6 +6,7 @@ class Evilution::Mutator::Operator::BlockParamRemoval < Evilution::Mutator::Base
   def visit_def_node(node)
     return super unless node.parameters
     return super unless node.parameters.block
+    return super if anonymous_block_forwarded?(node)
 
     if only_block_param?(node.parameters)
       remove_entire_params(node)
@@ -26,6 +27,37 @@ class Evilution::Mutator::Operator::BlockParamRemoval < Evilution::Mutator::Base
       params.keyword_rest.nil?
   end
 
+  # Skip the mutation when the def declares an anonymous `&` block parameter
+  # AND the body uses `&` to forward it. Ruby parses `def f(&) = g(&)` only
+  # because the signature declares the anonymous block; stripping `&` from the
+  # signature leaves the body's `&` orphaned and produces a parse error.
+  # Named block params (`&block`) are not affected here — removing those leaves
+  # body references like `block.call` as NameError at runtime, still parseable
+  # and still a useful (kill-able) mutation.
+  def anonymous_block_forwarded?(node)
+    return false unless node.parameters.block.name.nil?
+    return false if node.body.nil?
+
+    body_contains_anonymous_forward?(node.body)
+  end
+
+  def body_contains_anonymous_forward?(body)
+    queue = [body]
+    until queue.empty?
+      current = queue.shift
+      return true if current.is_a?(Prism::BlockArgumentNode) && current.expression.nil?
+
+      # A nested def introduces a fresh method scope, so any `&` inside it
+      # forwards the inner method's own block parameter, not ours. Stop
+      # descent. Blocks and lambdas inherit the enclosing method scope, so
+      # we keep walking through them.
+      next if current.is_a?(Prism::DefNode)
+
+      queue.concat(current.compact_child_nodes)
+    end
+    false
+  end
+
   def remove_entire_params(node)
     start_offset = node.lparen_loc.start_offset
     end_offset = node.rparen_loc.start_offset + node.rparen_loc.length
@@ -38,14 +70,7 @@ class Evilution::Mutator::Operator::BlockParamRemoval < Evilution::Mutator::Base
   end
 
   def remove_block_param(node)
-    block_loc = node.parameters.block.location
-    params_text = @file_source.byteslice(node.parameters.location.start_offset, node.parameters.location.length)
-    block_rel = block_loc.start_offset - node.parameters.location.start_offset
-
-    # Find the comma before the block param and remove ", &block"
-    comma_pos = params_text.rindex(",", block_rel - 1)
-    remove_start = node.parameters.location.start_offset + comma_pos
-    remove_end = block_loc.start_offset + block_loc.length
+    remove_start, remove_end = block_param_removal_range(node)
 
     add_mutation(
       offset: remove_start,
@@ -54,4 +79,21 @@ class Evilution::Mutator::Operator::BlockParamRemoval < Evilution::Mutator::Base
       node: node
     )
   end
+
+  # Range covering ", &block" — from the comma before the block param to the end of the block param.
+  def block_param_removal_range(node)
+    params_loc = node.parameters.location
+    block_loc = node.parameters.block.location
+    comma_pos = params_text(params_loc).rindex(",", block_loc.start_offset - params_loc.start_offset - 1)
+
+    [params_loc.start_offset + comma_pos, end_offset(block_loc)]
+  end
+
+  def params_text(params_loc)
+    @file_source.byteslice(params_loc.start_offset, params_loc.length)
+  end
+
+  def end_offset(loc)
+    loc.start_offset + loc.length
+  end
 end