evilution 0.24.0 → 0.25.0

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

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../mutate_tool"
+require_relative "../../runner"
+require_relative "../../spec_resolver"
+
+module Evilution::MCP::MutateTool::SurvivedEnricher
+  def self.call(data, survived_results, config)
+    entries = data["survived"]
+    return unless entries.is_a?(Array)
+
+    explicit_spec = explicit_spec_override(config)
+    resolver = explicit_spec ? nil : resolver_for_integration(config.integration)
+    cache = {}
+
+    entries.each_with_index do |entry, index|
+      result = survived_results[index]
+      next unless result
+
+      mutation = result.mutation
+      entry["subject"] = mutation.subject.name
+      spec_file = explicit_spec || cache.fetch(mutation.file_path) do
+        cache[mutation.file_path] = resolver.call(mutation.file_path)
+      end
+      entry["spec_file"] = spec_file if spec_file
+      entry["next_step"] = build_next_step(mutation, spec_file)
+    end
+  end
+
+  def self.explicit_spec_override(config)
+    return nil unless config.respond_to?(:spec_files)
+
+    files = Array(config.spec_files).compact.map(&:to_s).reject(&:empty?)
+    files.first
+  end
+  private_class_method :explicit_spec_override
+
+  def self.resolver_for_integration(integration)
+    integration_class = Evilution::Runner::INTEGRATIONS[integration.to_sym]
+    return Evilution::SpecResolver.new unless integration_class
+
+    integration_class.baseline_options[:spec_resolver] || Evilution::SpecResolver.new
+  end
+  private_class_method :resolver_for_integration
+
+  def self.build_next_step(mutation, spec_file)
+    target = spec_file || "the covering test file"
+    "Add a test in #{target} that fails against this mutation at #{mutation.file_path}:#{mutation.line} " \
+      "(#{mutation.subject.name}, #{mutation.operator_name})."
+  end
+  private_class_method :build_next_step
+end

data/lib/evilution/mcp/mutate_tool.rb

@@ -5,7 +5,6 @@ require "mcp"
 require_relative "../config"
 require_relative "../runner"
 require_relative "../reporter/json"
-require_relative "../reporter/suggestion"
 require_relative "../spec_resolver"
 
 require_relative "../mcp"
@@ -104,194 +103,43 @@ class Evilution::MCP::MutateTool < MCP::Tool
 
   class << self
     def call(server_context:, files: [], verbosity: nil, **opts)
-      validate_opts!(opts)
-      parsed_files, line_ranges = parse_files(Array(files))
-      config_opts = build_config_opts(parsed_files, line_ranges, opts)
-      config = Evilution::Config.new(**config_opts)
-      suggest_tests = opts[:suggest_tests]
-      on_result = build_streaming_callback(server_context, suggest_tests, config.integration)
-      runner = Evilution::Runner.new(config: config, on_result: on_result)
-      summary = runner.call
-      report = Evilution::Reporter::JSON.new(suggest_tests: suggest_tests == true, integration: config.integration).call(summary)
-      compact = trim_report(report, normalize_verbosity(verbosity), summary.survived_results, config)
+      Evilution::MCP::MutateTool::OptionParser.validate!(opts)
+      parsed_files, line_ranges = Evilution::MCP::MutateTool::OptionParser.parse_files(Array(files))
+      config = Evilution::MCP::MutateTool::ConfigBuilder.build(
+        files: parsed_files,
+        line_ranges: line_ranges,
+        params: opts
+      )
+      on_result = Evilution::MCP::MutateTool::ProgressStreamer.build(
+        server_context: server_context,
+        suggest_tests: opts[:suggest_tests],
+        integration: config.integration
+      )
+      summary = Evilution::Runner.new(config: config, on_result: on_result).call
+      report = Evilution::Reporter::JSON.new(
+        suggest_tests: opts[:suggest_tests] == true,
+        integration: config.integration
+      ).call(summary)
+      normalized_verbosity = Evilution::MCP::MutateTool::OptionParser.normalize_verbosity(verbosity)
+      compact = Evilution::MCP::MutateTool::ReportTrimmer.call(
+        report,
+        verbosity: normalized_verbosity,
+        survived_results: summary.survived_results,
+        config: config,
+        enricher: Evilution::MCP::MutateTool::SurvivedEnricher
+      )
 
       ::MCP::Tool::Response.new([{ type: "text", text: compact }])
     rescue Evilution::Error => e
-      error_payload = build_error_payload(e)
-      ::MCP::Tool::Response.new([{ type: "text", text: ::JSON.generate(error_payload) }], error: true)
-    end
-
-    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
-
-    private
-
-    def 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 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 validate_opts!(opts)
-      unknown = opts.keys - ALLOWED_OPT_KEYS
-      return if unknown.empty?
-
-      raise Evilution::ParseError, "unknown parameters: #{unknown.join(", ")}"
-    end
-
-    def build_config_opts(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]
-      PASSTHROUGH_KEYS.each { |key| opts[key] = params[key] unless params[key].nil? }
-      opts
-    end
-
-    def 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 trim_report(json_string, verbosity, survived_results, config)
-      data = ::JSON.parse(json_string)
-      case verbosity
-      when "full"
-        strip_diffs(data, "killed")
-        strip_diffs(data, "neutral")
-        strip_diffs(data, "equivalent")
-      when "summary"
-        data.delete("killed")
-        data.delete("neutral")
-        data.delete("equivalent")
-      when "minimal"
-        data.delete("killed")
-        data.delete("neutral")
-        data.delete("equivalent")
-        data.delete("timed_out")
-        data.delete("errors")
-      end
-      enrich_survived(data, survived_results, config)
-      ::JSON.generate(data)
-    end
-
-    def enrich_survived(data, survived_results, config)
-      entries = data["survived"]
-      return unless entries.is_a?(Array)
-
-      explicit_spec = explicit_spec_override(config)
-      resolver = explicit_spec ? nil : resolver_for_integration(config.integration)
-      cache = {}
-
-      entries.each_with_index do |entry, index|
-        result = survived_results[index]
-        next unless result
-
-        mutation = result.mutation
-        entry["subject"] = mutation.subject.name
-        spec_file = explicit_spec || cache.fetch(mutation.file_path) do
-          cache[mutation.file_path] = resolver.call(mutation.file_path)
-        end
-        entry["spec_file"] = spec_file if spec_file
-        entry["next_step"] = build_next_step(mutation, spec_file)
-      end
-    end
-
-    def explicit_spec_override(config)
-      return nil unless config.respond_to?(:spec_files)
-
-      files = Array(config.spec_files).compact.map(&:to_s).reject(&:empty?)
-      files.first
-    end
-
-    def resolver_for_integration(integration)
-      integration_class = Evilution::Runner::INTEGRATIONS[integration.to_sym]
-      return Evilution::SpecResolver.new unless integration_class
-
-      integration_class.baseline_options[:spec_resolver] || Evilution::SpecResolver.new
-    end
-
-    def build_next_step(mutation, spec_file)
-      target = spec_file || "the covering test file"
-      "Add a test in #{target} that fails against this mutation at #{mutation.file_path}:#{mutation.line} " \
-        "(#{mutation.subject.name}, #{mutation.operator_name})."
-    end
-
-    def strip_diffs(data, key)
-      return unless data[key]
-
-      data[key].each { |entry| entry.delete("diff") }
-    end
-
-    def build_streaming_callback(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 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
-
-    def build_error_payload(error)
-      error_type = case error
-                   when Evilution::ConfigError then "config_error"
-                   when Evilution::ParseError then "parse_error"
-                   else "runtime_error"
-                   end
-
-      payload = { type: error_type, message: error.message }
-      payload[:file] = error.file if error.file
-      { error: payload }
+      payload = Evilution::MCP::MutateTool::ErrorPayload.build(e)
+      ::MCP::Tool::Response.new([{ type: "text", text: ::JSON.generate(payload) }], error: true)
     end
   end
 end
+
+require_relative "mutate_tool/error_payload"
+require_relative "mutate_tool/option_parser"
+require_relative "mutate_tool/config_builder"
+require_relative "mutate_tool/report_trimmer"
+require_relative "mutate_tool/survived_enricher"
+require_relative "mutate_tool/progress_streamer"

data/lib/evilution/mutation.rb

@@ -1,27 +1,44 @@
 # frozen_string_literal: true
 
 require "diff/lcs"
-require "diff/lcs/hunk"
 
 class Evilution::Mutation
   attr_reader :subject, :operator_name, :original_source,
-              :mutated_source, :file_path, :line, :column
+              :mutated_source, :original_slice, :mutated_slice,
+              :file_path, :line, :column, :parse_status
 
-  def initialize(subject:, operator_name:, original_source:, mutated_source:, file_path:, line:, column: 0)
+  # rubocop:disable Metrics/ParameterLists
+  def initialize(subject:, operator_name:, original_source:, mutated_source:,
+                 file_path:, line:, column: 0, original_slice: nil, mutated_slice: nil,
+                 parse_status: :ok)
+    # rubocop:enable Metrics/ParameterLists
     @subject = subject
     @operator_name = operator_name
     @original_source = original_source
     @mutated_source = mutated_source
+    @original_slice = original_slice
+    @mutated_slice = mutated_slice
     @file_path = file_path
     @line = line
     @column = column
+    @parse_status = parse_status
     @diff = nil
   end
 
+  def unparseable?
+    @parse_status == :unparseable
+  end
+
   def diff
     @diff ||= compute_diff
   end
 
+  def unified_diff
+    return @unified_diff if defined?(@unified_diff)
+
+    @unified_diff = compute_unified_diff
+  end
+
   def strip_sources!
     diff # ensure diff is cached before clearing sources
     @original_source = nil
@@ -49,6 +66,29 @@ class Evilution::Mutation
     result.join("\n")
   end
 
+  def compute_unified_diff
+    return nil if @original_slice.nil? || @mutated_slice.nil?
+
+    original_lines = @original_slice.lines
+    mutated_lines = @mutated_slice.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
+    ].reject(&:empty?).join("\n")
+  end
+
+  def format_sdiff_change(change)
+    case change.action
+    when "=" then " #{change.old_element.chomp}"
+    when "-" then "-#{change.old_element.chomp}"
+    when "+" then "+#{change.new_element.chomp}"
+    when "!" then "-#{change.old_element.chomp}\n+#{change.new_element.chomp}"
+    end
+  end
+
   public
 
   def to_s