evilution 0.23.0 → 0.25.0

data/lib/evilution/integration/minitest.rb

@@ -4,6 +4,7 @@ require "stringio"
 require_relative "base"
 require_relative "minitest_crash_detector"
 require_relative "../spec_resolver"
+require_relative "../spec_selector"
 
 require_relative "../integration"
 
@@ -35,10 +36,13 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     }
   end
 
-  def initialize(test_files: nil, hooks: nil)
+  def initialize(test_files: nil, hooks: nil, fallback_to_full_suite: false, spec_selector: nil)
     @test_files = test_files
     @minitest_loaded = false
-    @spec_resolver = Evilution::SpecResolver.new(test_dir: "test", test_suffix: "_test.rb", request_dir: "integration")
+    @spec_selector = spec_selector || Evilution::SpecSelector.new(
+      spec_resolver: Evilution::SpecResolver.new(test_dir: "test", test_suffix: "_test.rb", request_dir: "integration")
+    )
+    @fallback_to_full_suite = fallback_to_full_suite
     @crash_detector = nil
     @warned_files = Set.new
     super(hooks: hooks)
@@ -62,6 +66,8 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
   def run_tests(mutation)
     reset_state
     files = resolve_test_files(mutation)
+    return unresolved_result(mutation) if files.nil?
+
     command = "ruby -Itest #{files.join(" ")}"
 
     files.each { |f| load(File.expand_path(f)) }
@@ -75,6 +81,15 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     { passed: false, error: e.message, test_command: command }
   end
 
+  def unresolved_result(mutation)
+    {
+      passed: false,
+      unresolved: true,
+      error: "no matching test resolved for #{mutation.file_path}",
+      test_command: "ruby -Itest (skipped: no test resolved for #{mutation.file_path})"
+    }
+  end
+
   def build_args(_mutation)
     ["--seed", "0"]
   end
@@ -112,10 +127,12 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     if passed
       { passed: true, test_command: command }
     elsif detector.only_crashes?
+      classes = detector.unique_crash_classes
       {
         passed: false,
         test_crashed: true,
         error: "test crashes: #{detector.crash_summary}",
+        error_class: (classes.first if classes.length == 1),
         test_command: command
       }
     else
@@ -126,13 +143,13 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
   def resolve_test_files(mutation)
     return test_files if test_files
 
-    resolved = @spec_resolver.call(mutation.file_path)
-    unless resolved
+    resolved = Array(@spec_selector.call(mutation.file_path))
+    if resolved.empty?
       warn_unresolved_test(mutation.file_path)
-      return glob_test_files
+      return @fallback_to_full_suite ? glob_test_files : nil
     end
 
-    [resolved]
+    resolved
   end
 
   def glob_test_files
@@ -144,7 +161,8 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     return if @warned_files.include?(file_path)
 
     @warned_files << file_path
-    warn "[evilution] No matching test found for #{file_path}, running full suite. " \
+    action = @fallback_to_full_suite ? "running full suite" : "marking mutation unresolved"
+    warn "[evilution] No matching test found for #{file_path}, #{action}. " \
          "Use --spec to specify the test file."
   end
 end

data/lib/evilution/integration/minitest_crash_detector.rb

@@ -49,7 +49,10 @@ class Evilution::Integration::MinitestCrashDetector
   def crash_summary
     return nil if @crashes.empty?
 
-    types = @crashes.map { |e| e.class.name }.uniq
-    "#{types.join(", ")} (#{@crashes.length} crash#{"es" unless @crashes.length == 1})"
+    "#{unique_crash_classes.join(", ")} (#{@crashes.length} crash#{"es" unless @crashes.length == 1})"
+  end
+
+  def unique_crash_classes
+    @crashes.map { |e| e.class.name }.uniq
   end
 end

data/lib/evilution/integration/rspec.rb

@@ -4,6 +4,7 @@ require "stringio"
 require_relative "base"
 require_relative "crash_detector"
 require_relative "../spec_resolver"
+require_relative "../spec_selector"
 require_relative "../related_spec_heuristic"
 
 require_relative "../integration"
@@ -26,12 +27,15 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     { runner: baseline_runner }
   end
 
-  def initialize(test_files: nil, hooks: nil, related_specs_heuristic: false)
+  def initialize(test_files: nil, hooks: nil, related_specs_heuristic: false, fallback_to_full_suite: false,
+                 spec_selector: nil, example_filter: nil)
     @test_files = test_files
     @rspec_loaded = false
-    @spec_resolver = Evilution::SpecResolver.new
+    @spec_selector = spec_selector || Evilution::SpecSelector.new
     @related_spec_heuristic = Evilution::RelatedSpecHeuristic.new
     @related_specs_heuristic_enabled = related_specs_heuristic
+    @fallback_to_full_suite = fallback_to_full_suite
+    @example_filter = example_filter
     @crash_detector = nil
     @warned_files = Set.new
     super(hooks: hooks)
@@ -57,14 +61,21 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
   def run_tests(mutation)
     reset_state
 
+    files = resolve_test_files(mutation)
+    return unresolved_result(mutation) if files.nil?
+
+    targets = apply_example_filter(mutation, files)
+    return unresolved_example_result(mutation) if targets.nil?
+
     out = StringIO.new
     err = StringIO.new
-    command = "rspec"
-    args = build_args(mutation)
+    args = build_args(targets)
     command = "rspec #{args.join(" ")}"
 
     detector = reset_crash_detector
     eg_before = snapshot_example_groups
+    fe_before = snapshot_filtered_examples_keys
+    rep_before = snapshot_reporter_lengths
     status = ::RSpec::Core::Runner.run(args, out, err)
 
     build_rspec_result(status, command, detector)
@@ -72,13 +83,38 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     { passed: false, error: e.message, test_command: command }
   ensure
     release_rspec_state(eg_before)
+    release_filtered_examples(fe_before)
+    release_reporter_state(rep_before)
   end
 
-  def build_args(mutation)
-    files = resolve_test_files(mutation)
+  def build_args(files)
     ["--format", "progress", "--no-color", "--order", "defined", *files]
   end
 
+  def apply_example_filter(mutation, files)
+    return files unless @example_filter
+
+    @example_filter.call(mutation, files)
+  end
+
+  def unresolved_result(mutation)
+    {
+      passed: false,
+      unresolved: true,
+      error: "no matching spec resolved for #{mutation.file_path}",
+      test_command: "rspec (skipped: no spec resolved for #{mutation.file_path})"
+    }
+  end
+
+  def unresolved_example_result(mutation)
+    {
+      passed: false,
+      unresolved: true,
+      error: "no matching example found for #{mutation.file_path}",
+      test_command: "rspec (skipped: no matching example for #{mutation.file_path})"
+    }
+  end
+
   def reset_state
     if ::RSpec.respond_to?(:clear_examples)
       ::RSpec.clear_examples
@@ -127,6 +163,54 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     world.instance_variable_set(:@sources_by_path, {}) if world.instance_variable_defined?(:@sources_by_path)
   end
 
+  def snapshot_filtered_examples_keys
+    fe = rspec_world_ivar(:@filtered_examples)
+    fe ? Set.new(fe.keys.map(&:object_id)) : nil
+  end
+
+  def snapshot_reporter_lengths
+    reporter = rspec_config_ivar(:@reporter)
+    return nil unless reporter
+
+    %i[@examples @failed_examples @pending_examples].each_with_object({}) do |ivar, acc|
+      next unless reporter.instance_variable_defined?(ivar)
+
+      arr = reporter.instance_variable_get(ivar)
+      acc[ivar] = arr.length if arr.is_a?(Array)
+    end
+  end
+
+  def release_filtered_examples(snapshot_keys)
+    fe = rspec_world_ivar(:@filtered_examples)
+    return unless fe && snapshot_keys
+
+    fe.each_key.to_a.each do |k|
+      fe.delete(k) unless snapshot_keys.include?(k.object_id)
+    end
+  end
+
+  def release_reporter_state(lengths)
+    return unless lengths
+
+    reporter = rspec_config_ivar(:@reporter)
+    return unless reporter
+
+    lengths.each do |ivar, length|
+      arr = reporter.instance_variable_get(ivar)
+      arr.slice!(length..) if arr.is_a?(Array) && arr.length > length
+    end
+  end
+
+  def rspec_world_ivar(ivar)
+    world = ::RSpec.world
+    world.instance_variable_defined?(ivar) ? world.instance_variable_get(ivar) : nil
+  end
+
+  def rspec_config_ivar(ivar)
+    config = ::RSpec.configuration
+    config.instance_variable_defined?(ivar) ? config.instance_variable_get(ivar) : nil
+  end
+
   def reset_crash_detector
     if @crash_detector
       @crash_detector.reset
@@ -141,10 +225,12 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     if status.zero?
       { passed: true, test_command: command }
     elsif detector.only_crashes?
+      classes = detector.unique_crash_classes
       {
         passed: false,
         test_crashed: true,
         error: "test crashes: #{detector.crash_summary}",
+        error_class: (classes.first if classes.length == 1),
         test_command: command
       }
     else
@@ -155,23 +241,24 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
   def resolve_test_files(mutation)
     return test_files if test_files
 
-    resolved = @spec_resolver.call(mutation.file_path)
-    unless resolved
+    resolved = Array(@spec_selector.call(mutation.file_path))
+    if resolved.empty?
       warn_unresolved_spec(mutation.file_path)
-      return ["spec"]
+      return @fallback_to_full_suite ? ["spec"] : nil
     end
 
-    return [resolved] unless @related_specs_heuristic_enabled
+    return resolved unless @related_specs_heuristic_enabled
 
     related = @related_spec_heuristic.call(mutation)
-    ([resolved] + related).uniq
+    (resolved + related).uniq
   end
 
   def warn_unresolved_spec(file_path)
     return if @warned_files.include?(file_path)
 
     @warned_files << file_path
-    warn "[evilution] No matching spec found for #{file_path}, running full suite. " \
+    action = @fallback_to_full_suite ? "running full suite" : "marking mutation unresolved"
+    warn "[evilution] No matching spec found for #{file_path}, #{action}. " \
          "Use --spec to specify the spec file."
   end
 

data/lib/evilution/isolation/fork.rb

@@ -15,10 +15,18 @@ class Evilution::Isolation::Fork
   end
 
   def call(mutation:, test_command:, timeout:)
+    pid = nil
     sandbox_dir = Dir.mktmpdir("evilution-run")
     start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     parent_rss = Evilution::Memory.rss_kb
     read_io, write_io = IO.pipe
+    # Marshal result payload is ASCII-8BIT; pipes default to text mode and may
+    # transcode according to their external/internal encodings (influenced by
+    # Encoding.default_external and/or Encoding.default_internal — Rails sets
+    # the latter to UTF-8), failing on bytes with no mapping. Force binmode on
+    # both ends.
+    read_io.binmode
+    write_io.binmode
 
     pid = ::Process.fork do
       ENV["TMPDIR"] = sandbox_dir
@@ -39,6 +47,7 @@ class Evilution::Isolation::Fork
   ensure
     read_io&.close
     write_io&.close
+    ensure_reaped(pid)
     restore_original_source(mutation)
     FileUtils.rm_rf(sandbox_dir) if sandbox_dir
   end
@@ -82,6 +91,22 @@ class Evilution::Isolation::Fork
     end
   end
 
+  # Defensive reap: if normal control flow raised before wait_for_result
+  # reaped the child (e.g. Marshal.load on corrupt payload), the child becomes
+  # a zombie. Reuse terminate_child for the bounded TERM + GRACE_PERIOD + KILL
+  # ladder so this never hangs the ensure path; swallow SystemCallError so
+  # cleanup can't mask the primary failure.
+  def ensure_reaped(pid)
+    return unless pid
+
+    reaped = ::Process.waitpid(pid, ::Process::WNOHANG)
+    return if reaped
+
+    terminate_child(pid)
+  rescue SystemCallError
+    nil
+  end
+
   def terminate_child(pid)
     ::Process.kill("TERM", pid) rescue nil # rubocop:disable Style/RescueModifier
     _, status = ::Process.waitpid2(pid, ::Process::WNOHANG)
@@ -98,6 +123,7 @@ class Evilution::Isolation::Fork
   def classify_status(result)
     return :timeout if result[:timeout]
     return :killed if result[:test_crashed]
+    return :unresolved if result[:unresolved]
     return :error if result[:error]
     return :survived if result[:passed]
 

data/lib/evilution/isolation/in_process.rb

@@ -65,6 +65,7 @@ class Evilution::Isolation::InProcess
   def classify_status(result)
     return :timeout if result[:timeout]
     return :killed if result[:test_crashed]
+    return :unresolved if result[:unresolved]
     return :error if result[:error]
     return :survived if result[:passed]
 

data/lib/evilution/mcp/info_tool.rb

@@ -5,6 +5,7 @@ require "mcp"
 require_relative "../config"
 require_relative "../runner"
 require_relative "../mutator/registry"
+require_relative "../result/mutation_result"
 require_relative "../spec_resolver"
 require_relative "../ast/pattern/filter"
 require_relative "../version"
@@ -14,20 +15,23 @@ require_relative "../mcp"
 class Evilution::MCP::InfoTool < MCP::Tool
   tool_name "evilution-info"
   description "Discover what evilution sees before running any mutations. " \
-              "One tool, three actions: " \
+              "One tool, four actions: " \
               "'subjects' lists every mutatable method in the target files with its file, line, and mutation count; " \
               "'tests' resolves which spec/test files cover the given sources (so you pick the right --spec before mutating); " \
               "'environment' dumps the effective config (version, ruby, config file, timeout, " \
-              "integration, isolation, and every other setting). " \
+              "integration, isolation, and every other setting); " \
+              "'statuses' returns the mutation-result status glossary (killed/survived/neutral/error/etc.) with " \
+              "per-status meaning and scoring semantics so agents can triage results without guessing. " \
               "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."
   input_schema(
     properties: {
       action: {
         type: "string",
-        enum: %w[subjects tests environment],
+        enum: %w[subjects tests environment statuses],
         description: "Which discovery operation to perform. " \
-                     "'subjects' lists mutatable methods; 'tests' resolves specs for sources; 'environment' dumps effective config."
+                     "'subjects' lists mutatable methods; 'tests' resolves specs for sources; " \
+                     "'environment' dumps effective config; 'statuses' returns the result-status glossary."
       },
       files: {
         type: "array",
@@ -60,7 +64,61 @@ class Evilution::MCP::InfoTool < MCP::Tool
     required: ["action"]
   )
 
-  VALID_ACTIONS = %w[subjects tests environment].freeze
+  VALID_ACTIONS = %w[subjects tests environment statuses].freeze
+
+  STATUS_GLOSSARY = [
+    {
+      "status" => "killed",
+      "meaning" => "A test failed when the mutation was applied — the test suite caught the mutation. " \
+                   "This is the desired outcome.",
+      "counted_in_score" => true
+    },
+    {
+      "status" => "survived",
+      "meaning" => "No test failed when the mutation was applied — gap in coverage. " \
+                   "The test suite did not detect the behavioral change.",
+      "counted_in_score" => true
+    },
+    {
+      "status" => "timeout",
+      "meaning" => "Test run exceeded the configured per-mutation timeout. " \
+                   "Treated like survived for scoring (counted in the denominator); " \
+                   "may indicate an infinite loop introduced by the mutation.",
+      "counted_in_score" => true
+    },
+    {
+      "status" => "error",
+      "meaning" => "Mutation execution raised an unexpected error (syntax error at load time, " \
+                   "boot failure, test-infrastructure crash). The mutation could not be evaluated.",
+      "counted_in_score" => false
+    },
+    {
+      "status" => "neutral",
+      "meaning" => "Baseline tests already failed before the mutation was applied — pre-existing " \
+                   "test-suite problem (flaky spec, infra collision, fixture setup failure). " \
+                   "Not a meaningful mutation signal.",
+      "counted_in_score" => false
+    },
+    {
+      "status" => "equivalent",
+      "meaning" => "Mutation is provably identical to the original source " \
+                   "(e.g. a no-op replacement that the parser or evaluator treats as semantically equal).",
+      "counted_in_score" => false
+    },
+    {
+      "status" => "unresolved",
+      "meaning" => "No spec/test file resolved for the mutated source — coverage gap, not a failure. " \
+                   "The file has no corresponding test file the resolver could locate.",
+      "counted_in_score" => false
+    },
+    {
+      "status" => "unparseable",
+      "meaning" => "Mutated source failed to parse (e.g. dangling heredoc after method_body_replacement). " \
+                   "Short-circuited before execution; no test run was attempted.",
+      "counted_in_score" => false
+    }
+  ].freeze
+  private_constant :STATUS_GLOSSARY
 
   class << self
     # rubocop:disable Lint/UnusedMethodArgument
@@ -78,6 +136,8 @@ class Evilution::MCP::InfoTool < MCP::Tool
         tests_action(files: parsed_files, spec: spec, integration: integration, skip_config: skip_config)
       when "environment"
         environment_action
+      when "statuses"
+        statuses_action
       end
     rescue Evilution::Error => e
       error_response_for(e)
@@ -213,6 +273,18 @@ class Evilution::MCP::InfoTool < MCP::Tool
       )
     end
 
+    def statuses_action
+      # Guard against drift: every STATUSES symbol must have a glossary entry.
+      defined = Evilution::Result::MutationResult::STATUSES.map(&:to_s).sort
+      documented = STATUS_GLOSSARY.map { |s| s["status"] }.sort
+      if defined != documented
+        missing = (defined - documented) + (documented - defined)
+        raise Evilution::Error, "status glossary drift: #{missing.inspect}"
+      end
+
+      success_response("statuses" => STATUS_GLOSSARY)
+    end
+
     def error_response_for(error)
       type = case error
              when Evilution::ConfigError then "config_error"

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../mutate_tool"
+require_relative "option_parser"
+require_relative "../../config"
+
+module Evilution::MCP::MutateTool::ConfigBuilder
+  def self.build(files:, line_ranges:, params:)
+    # Preload is disabled for MCP invocations: `require`-ing Rails into the
+    # long-lived MCP server would poison subsequent runs against other
+    # projects. MCP users who want the speedup should use the CLI.
+    opts = { target_files: files, line_ranges: line_ranges, format: :json, quiet: true, preload: false }
+    opts[:skip_config_file] = true if params[:skip_config]
+    opts[:spec_files] = params[:spec] if params[:spec]
+    Evilution::MCP::MutateTool::OptionParser::PASSTHROUGH_KEYS.each do |key|
+      opts[key] = params[key] unless params[key].nil?
+    end
+    Evilution::Config.new(**opts)
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "../mutate_tool"
+
+module Evilution::MCP::MutateTool::ErrorPayload
+  def self.build(error)
+    type = case error
+           when Evilution::ConfigError then "config_error"
+           when Evilution::ParseError  then "parse_error"
+           else "runtime_error"
+           end
+
+    payload = { type: type, message: error.message }
+    payload[:file] = error.file if error.file
+    { error: payload }
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+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
+  ALLOWED_OPT_KEYS = (PASSTHROUGH_KEYS + %i[spec skip_config]).freeze
+
+  def self.parse_files(raw_files)
+    files = []
+    ranges = {}
+
+    raw_files.each do |arg|
+      file, range_str = arg.split(":", 2)
+      files << file
+      next unless range_str
+
+      ranges[file] = parse_line_range(range_str)
+    end
+
+    [files, ranges]
+  end
+
+  def self.parse_line_range(str)
+    if str.include?("-")
+      start_str, end_str = str.split("-", 2)
+      start_line = Integer(start_str)
+      end_line = end_str.empty? ? Float::INFINITY : Integer(end_str)
+      start_line..end_line
+    else
+      line = Integer(str)
+      line..line
+    end
+  rescue ArgumentError, TypeError
+    raise Evilution::ParseError, "invalid line range: #{str.inspect}"
+  end
+
+  def self.normalize_verbosity(value)
+    normalized = value.to_s.strip.downcase
+    normalized = "summary" if normalized.empty?
+    return normalized if VALID_VERBOSITIES.include?(normalized)
+
+    raise Evilution::ParseError, "invalid verbosity: #{value.inspect} (must be full, summary, or minimal)"
+  end
+
+  def self.validate!(opts)
+    unknown = opts.keys - ALLOWED_OPT_KEYS
+    return if unknown.empty?
+
+    raise Evilution::ParseError, "unknown parameters: #{unknown.join(", ")}"
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../mutate_tool"
+require_relative "../../reporter/suggestion"
+
+module Evilution::MCP::MutateTool::ProgressStreamer
+  def self.build(server_context:, suggest_tests:, integration:)
+    return nil unless suggest_tests && server_context.respond_to?(:report_progress)
+
+    suggestion = Evilution::Reporter::Suggestion.new(suggest_tests: true, integration: integration)
+    survivor_index = 0
+
+    proc do |result|
+      next unless result.survived?
+
+      begin
+        survivor_index += 1
+        detail = build_suggestion_detail(result.mutation, suggestion)
+        server_context.report_progress(survivor_index, message: ::JSON.generate(detail))
+      rescue StandardError # rubocop:disable Lint/SuppressedException
+      end
+    end
+  end
+
+  def self.build_suggestion_detail(mutation, suggestion)
+    {
+      operator: mutation.operator_name,
+      file: mutation.file_path,
+      line: mutation.line,
+      subject: mutation.subject.name,
+      diff: mutation.diff,
+      suggestion: suggestion.suggestion_for(mutation)
+    }
+  end
+  private_class_method :build_suggestion_detail
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../mutate_tool"
+
+module Evilution::MCP::MutateTool::ReportTrimmer
+  MINIMAL_KEYS = %w[summary survived].freeze
+  FULL_DIFF_STRIP_KEYS = %w[killed neutral equivalent unresolved unparseable].freeze
+  SUMMARY_DROP_KEYS = %w[killed neutral equivalent unparseable].freeze
+
+  def self.call(json_string, verbosity:, survived_results:, config:, enricher:)
+    data = ::JSON.parse(json_string)
+    case verbosity
+    when "full"
+      FULL_DIFF_STRIP_KEYS.each { |key| strip_diffs(data, key) }
+    when "summary"
+      SUMMARY_DROP_KEYS.each { |key| data.delete(key) }
+    when "minimal"
+      data.keep_if { |key, _| MINIMAL_KEYS.include?(key) }
+    end
+    enricher.call(data, survived_results, config)
+    ::JSON.generate(data)
+  end
+
+  def self.strip_diffs(data, key)
+    return unless data[key]
+
+    data[key].each { |entry| entry.delete("diff") }
+  end
+  private_class_method :strip_diffs
+end