evilution 0.22.6 → 0.23.0

data/lib/evilution/mcp/mutate_tool.rb

@@ -6,13 +6,28 @@ require_relative "../config"
 require_relative "../runner"
 require_relative "../reporter/json"
 require_relative "../reporter/suggestion"
+require_relative "../spec_resolver"
 
 require_relative "../mcp"
 
 class Evilution::MCP::MutateTool < MCP::Tool
   tool_name "evilution-mutate"
-  description "Run mutation testing on Ruby source files. " \
-              "Use suggest_tests: true to get concrete test code (RSpec or Minitest) for surviving mutants."
+  description "Run mutation testing on Ruby source files and return structured JSON — not parsed CLI text. " \
+              "Built for iterative TDD: " \
+              "'incremental: true' caches killed/timeout results so rerunning on unchanged files is fast; " \
+              "'save_session: true' persists results for later diffing via evilution-session; " \
+              "'suggest_tests: true' streams concrete RSpec/Minitest code for each survivor as progress " \
+              "events so you can drop fixes straight into a test file. " \
+              "Respects .evilution.yml (timeout, jobs, integration, target, ignore_patterns, isolation) by default — " \
+              "pair with evilution-info to discover subjects and specs before you call this tool. " \
+              "Supports line-range file targeting (lib/foo.rb:15-30), 'target' method filter, explicit 'spec' overrides, " \
+              "'fail_fast' for early exit on N survivors, 'baseline: false' to skip the green-suite precheck, " \
+              "and 'verbosity' (full/summary/minimal) to match the agent's context budget. " \
+              "Survived mutants are enriched beyond `evilution --format json`: each entry includes " \
+              "'subject' (Class#method), resolved 'spec_file', and a concrete 'next_step' hint — " \
+              "so the agent can jump straight to writing the missing test. " \
+              "Prefer this over shelling out to 'evilution' — the response is machine-readable " \
+              "and already trimmed for survived-mutant triage."
   input_schema(
     properties: {
       files: {
@@ -46,6 +61,37 @@ class Evilution::MCP::MutateTool < MCP::Tool
         description: "When true, suggestions for survived mutants include concrete test code " \
                      "instead of static description text (default: false)"
       },
+      incremental: {
+        type: "boolean",
+        description: "Cache killed/timeout results and skip re-running them on unchanged files. " \
+                     "Set true when iterating on the same files to speed up repeat runs."
+      },
+      integration: {
+        type: "string",
+        enum: %w[rspec minitest],
+        description: "Test integration to use (default: rspec)"
+      },
+      isolation: {
+        type: "string",
+        enum: %w[auto fork in_process],
+        description: "Isolation strategy for mutation execution (default: auto)"
+      },
+      baseline: {
+        type: "boolean",
+        description: "Run a baseline test suite check before mutations (default: true). " \
+                     "Set false to skip when you already know the suite is green."
+      },
+      save_session: {
+        type: "boolean",
+        description: "Save session results to .evilution/results/ for later inspection via evilution-session"
+      },
+      skip_config: {
+        type: "boolean",
+        description: "When true, ignore .evilution.yml / config/evilution.yml. " \
+                     "MCP-specific overrides (JSON output, quiet mode, preload disabled) and explicit tool " \
+                     "parameters still apply. Default: false — project config is loaded so the MCP run " \
+                     "matches `evilution` CLI behavior."
+      },
       verbosity: {
         type: "string",
         enum: %w[full summary minimal],
@@ -57,27 +103,28 @@ class Evilution::MCP::MutateTool < MCP::Tool
   )
 
   class << self
-    # rubocop:disable Metrics/ParameterLists
-    def call(server_context:, files: [], target: nil, timeout: nil, jobs: nil,
-             fail_fast: nil, spec: nil, suggest_tests: nil, verbosity: nil)
+    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, target, timeout, jobs, fail_fast, spec,
-                                      suggest_tests)
+      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))
+      compact = trim_report(report, normalize_verbosity(verbosity), summary.survived_results, config)
 
       ::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
-    # rubocop:enable Metrics/ParameterLists
 
     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
 
@@ -110,18 +157,21 @@ class Evilution::MCP::MutateTool < MCP::Tool
       raise Evilution::ParseError, "invalid line range: #{str.inspect}"
     end
 
-    def build_config_opts(files, line_ranges, target, timeout, jobs, fail_fast, spec, suggest_tests)
+    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, skip_config_file: true,
-               preload: false }
-      opts[:target] = target if target
-      opts[:timeout] = timeout if timeout
-      opts[:jobs] = jobs if jobs
-      opts[:fail_fast] = fail_fast if fail_fast
-      opts[:spec_files] = spec if spec
-      opts[:suggest_tests] = true if suggest_tests
+      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
 
@@ -133,7 +183,7 @@ class Evilution::MCP::MutateTool < MCP::Tool
       raise Evilution::ParseError, "invalid verbosity: #{value.inspect} (must be full, summary, or minimal)"
     end
 
-    def trim_report(json_string, verbosity)
+    def trim_report(json_string, verbosity, survived_results, config)
       data = ::JSON.parse(json_string)
       case verbosity
       when "full"
@@ -151,9 +201,52 @@ class Evilution::MCP::MutateTool < MCP::Tool
         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/lib/evilution/mcp/server.rb

@@ -3,9 +3,8 @@
 require "mcp"
 require_relative "../version"
 require_relative "mutate_tool"
-require_relative "session_list_tool"
-require_relative "session_show_tool"
-require_relative "session_diff_tool"
+require_relative "session_tool"
+require_relative "info_tool"
 
 require_relative "../mcp"
 
@@ -14,7 +13,7 @@ class Evilution::MCP::Server
     ::MCP::Server.new(
       name: "evilution",
       version: Evilution::VERSION,
-      tools: [Evilution::MCP::MutateTool, Evilution::MCP::SessionListTool, Evilution::MCP::SessionShowTool, Evilution::MCP::SessionDiffTool]
+      tools: [Evilution::MCP::MutateTool, Evilution::MCP::SessionTool, Evilution::MCP::InfoTool]
     )
   end
 end

data/lib/evilution/mcp/session_diff_tool.rb

@@ -7,9 +7,13 @@ require_relative "../session/diff"
 
 require_relative "../mcp"
 
+# @deprecated Superseded by {Evilution::MCP::SessionTool} (action: "diff") as of 0.22.8.
+#   No longer registered with the MCP server; retained only for direct Ruby callers.
+#   Will be removed entirely — tracked by EV-h8pw / GH #686.
 class Evilution::MCP::SessionDiffTool < MCP::Tool
   tool_name "evilution-session-diff"
-  description "Compare two mutation testing sessions and return the diff. " \
+  description "DEPRECATED: use evilution-session with action: 'diff'. " \
+              "Compare two mutation testing sessions and return the diff. " \
               "Shows new regressions, fixed mutations, and persistent survivors."
   input_schema(
     properties: {

data/lib/evilution/mcp/session_list_tool.rb

@@ -6,9 +6,13 @@ require_relative "../session/store"
 
 require_relative "../mcp"
 
+# @deprecated Superseded by {Evilution::MCP::SessionTool} (action: "list") as of 0.22.8.
+#   No longer registered with the MCP server; retained only for direct Ruby callers.
+#   Will be removed entirely — tracked by EV-h8pw / GH #686.
 class Evilution::MCP::SessionListTool < MCP::Tool
   tool_name "evilution-session-list"
-  description "List past mutation testing sessions with summary statistics. " \
+  description "DEPRECATED: use evilution-session with action: 'list'. " \
+              "List past mutation testing sessions with summary statistics. " \
               "Returns sessions in reverse chronological order."
   input_schema(
     properties: {

data/lib/evilution/mcp/session_show_tool.rb

@@ -6,9 +6,13 @@ require_relative "../session/store"
 
 require_relative "../mcp"
 
+# @deprecated Superseded by {Evilution::MCP::SessionTool} (action: "show") as of 0.22.8.
+#   No longer registered with the MCP server; retained only for direct Ruby callers.
+#   Will be removed entirely — tracked by EV-h8pw / GH #686.
 class Evilution::MCP::SessionShowTool < MCP::Tool
   tool_name "evilution-session-show"
-  description "Show full details of a past mutation testing session, " \
+  description "DEPRECATED: use evilution-session with action: 'show'. " \
+              "Show full details of a past mutation testing session, " \
               "including survived mutations with diffs."
   input_schema(
     properties: {

data/lib/evilution/mcp/session_tool.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "json"
+require "mcp"
+require_relative "../session/store"
+require_relative "../session/diff"
+
+require_relative "../mcp"
+
+class Evilution::MCP::SessionTool < MCP::Tool
+  tool_name "evilution-session"
+  description "Inspect mutation testing history without re-running any tests. " \
+              "One tool, three actions: " \
+              "'list' browses saved sessions (reverse chronological), " \
+              "'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."
+  input_schema(
+    properties: {
+      action: {
+        type: "string",
+        enum: %w[list show diff],
+        description: "Which session operation to perform. 'list' browses history; 'show' displays one session; 'diff' compares two."
+      },
+      results_dir: {
+        type: "string",
+        description: "[list|show|diff] Session results directory (default: .evilution/results). " \
+                     "For show/diff, acts as the containment root: path/base/head must resolve under this directory."
+      },
+      limit: {
+        type: "integer",
+        description: "[list] Return only the N most recent sessions"
+      },
+      path: {
+        type: "string",
+        description: "[show] Path to a session JSON file (as returned by action=list); must be under results_dir"
+      },
+      base: {
+        type: "string",
+        description: "[diff] Path to the base (older) session JSON file; must be under results_dir"
+      },
+      head: {
+        type: "string",
+        description: "[diff] Path to the head (newer) session JSON file; must be under results_dir"
+      }
+    },
+    required: ["action"]
+  )
+
+  VALID_ACTIONS = %w[list show diff].freeze
+
+  class << self
+    # rubocop:disable Lint/UnusedMethodArgument
+    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
+      return error_response("config_error", "unknown action: #{action}") unless VALID_ACTIONS.include?(action)
+
+      case action
+      when "list" then list_action(results_dir: results_dir, limit: limit)
+      when "show" then show_action(path: path, results_dir: results_dir)
+      when "diff" then diff_action(base: base, head: head, results_dir: results_dir)
+      end
+    end
+    # rubocop:enable Lint/UnusedMethodArgument
+
+    private
+
+    def list_action(results_dir:, limit:)
+      normalized_limit, limit_error = normalize_limit(limit)
+      return error_response("config_error", limit_error) if limit_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?
+
+      payload = entries.map { |e| e.transform_keys(&:to_s) }
+      success_response(payload)
+    end
+
+    def normalize_limit(limit)
+      return [nil, nil] if limit.nil?
+
+      coerced = Integer(limit)
+      return [nil, "limit must be a non-negative integer"] if coerced.negative?
+
+      [coerced, nil]
+    rescue ArgumentError, TypeError
+      [nil, "limit must be a non-negative integer"]
+    end
+
+    def show_action(path:, results_dir:)
+      return error_response("config_error", "path is required") unless path
+
+      dir = results_dir || Evilution::Session::Store::DEFAULT_DIR
+      return error_response("config_error", "path must be under results directory") unless within?(path, dir)
+
+      store = Evilution::Session::Store.new(results_dir: dir)
+      data = store.load(path)
+      success_response(data)
+    rescue Evilution::Error => e
+      error_response("not_found", e.message)
+    rescue ::JSON::ParserError => e
+      error_response("parse_error", e.message)
+    rescue SystemCallError => e
+      error_response("runtime_error", e.message)
+    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)
+
+      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)
+    rescue Evilution::Error => e
+      error_response("not_found", e.message)
+    rescue ::JSON::ParserError => e
+      error_response("parse_error", e.message)
+    rescue SystemCallError => e
+      error_response("runtime_error", e.message)
+    end
+
+    def within?(path, results_dir)
+      resolved_root = canonical_path(results_dir)
+      resolved_path = canonical_path(path)
+      resolved_path == resolved_root || resolved_path.start_with?(resolved_root + File::SEPARATOR)
+    end
+
+    def canonical_path(path)
+      File.realpath(path)
+    rescue Errno::ENOENT
+      File.expand_path(path)
+    end
+
+    def success_response(payload)
+      ::MCP::Tool::Response.new([{ type: "text", text: ::JSON.generate(payload) }])
+    end
+
+    def error_response(type, message)
+      ::MCP::Tool::Response.new(
+        [{ type: "text", text: ::JSON.generate({ error: { type: type, message: message } }) }],
+        error: true
+      )
+    end
+  end
+end

data/lib/evilution/reporter/html.rb

@@ -121,6 +121,7 @@ class Evilution::Reporter::HTML
     survived_count = results.count(&:survived?)
     total = results.length
     survived = results.select(&:survived?)
+    errored = results.select(&:error?)
     map_html = build_mutation_map(results)
 
     <<~HTML
@@ -131,6 +132,7 @@ class Evilution::Reporter::HTML
         </h2>
         <div class="mutation-map">#{map_html}</div>
         #{build_survived_details(survived)}
+        #{build_error_details(errored)}
       </section>
     HTML
   end
@@ -218,6 +220,38 @@ class Evilution::Reporter::HTML
     HTML
   end
 
+  def build_error_details(errored)
+    return "" if errored.empty?
+
+    entries = errored
+              .sort_by { |r| [r.mutation.operator_name, r.mutation.line] }
+              .map { |r| build_error_entry(r) }
+              .join("\n")
+    <<~HTML
+      <div class="error-details">
+        <h3>Errors (#{errored.length})</h3>
+        #{entries}
+      </div>
+    HTML
+  end
+
+  def build_error_entry(result)
+    mutation = result.mutation
+    message = result.error_message.to_s
+    message_html = message.empty? ? "" : %(<pre class="error-message">#{h(message)}</pre>)
+    diff_html = format_diff(mutation.diff)
+    <<~HTML
+      <div class="error-entry">
+        <div class="error-header">
+          <span class="operator">#{h(mutation.operator_name)}</span>
+          <span class="location">#{h(mutation.file_path)}:#{mutation.line}</span>
+        </div>
+        <pre class="diff">#{diff_html}</pre>
+        #{message_html}
+      </div>
+    HTML
+  end
+
   def format_diff(diff)
     diff.split("\n").map do |line|
       escaped = h(line)
@@ -353,6 +387,13 @@ class Evilution::Reporter::HTML
         .delta-positive { color: #3fb950; font-weight: bold; }
         .delta-negative { color: #f85149; font-weight: bold; }
         .delta-neutral { color: #8b949e; font-weight: bold; }
+        .error-details { border-top: 1px solid #30363d; padding: 1rem; }
+        .error-details h3 { color: #d29922; font-size: 0.9rem; margin-bottom: 0.75rem; }
+        .error-entry { background: #1c1a10; border: 1px solid #4a3a10; border-radius: 6px; padding: 0.75rem; margin-bottom: 0.75rem; }
+        .error-header { display: flex; justify-content: space-between; margin-bottom: 0.5rem; font-size: 0.85rem; }
+        .error-header .operator { color: #d29922; font-weight: bold; }
+        .error-header .location { color: #8b949e; font-family: monospace; }
+        .error-message { background: #0d1117; border-radius: 4px; padding: 0.5rem 0.75rem; font-size: 0.8rem; color: #f85149; margin-top: 0.5rem; white-space: pre-wrap; overflow-x: auto; }
         .survived-entry.regression { border-color: #f85149; background: #2a1010; }
         .regression-badge { background: #da3633; color: #fff; font-size: 0.65rem; padding: 0.1rem 0.4rem; border-radius: 4px; margin-left: 0.5rem; text-transform: uppercase; font-weight: bold; }
         footer { text-align: center; color: #484f58; font-size: 0.75rem; margin-top: 2rem; padding-top: 1rem; border-top: 1px solid #21262d; }

data/lib/evilution/runner.rb

@@ -601,7 +601,9 @@ class Evilution::Runner
   def build_integration
     klass = resolve_integration_class
     test_files = config.spec_files.empty? ? nil : config.spec_files
-    klass.new(test_files: test_files, hooks: @hooks)
+    kwargs = { test_files: test_files, hooks: @hooks }
+    kwargs[:related_specs_heuristic] = config.related_specs_heuristic? if klass == Evilution::Integration::RSpec
+    klass.new(**kwargs)
   end
 
   def build_neutralization_resolver

data/lib/evilution/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Evilution
-  VERSION = "0.22.6"
+  VERSION = "0.23.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evilution
 version: !ruby/object:Gem::Version
-  version: 0.22.6
+  version: 0.23.0
 platform: ruby
 authors:
 - Denis Kiselev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-12 00:00:00.000000000 Z
+date: 2026-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -97,6 +97,32 @@ files:
 - lib/evilution/baseline.rb
 - lib/evilution/cache.rb
 - lib/evilution/cli.rb
+- lib/evilution/cli/command.rb
+- lib/evilution/cli/commands.rb
+- lib/evilution/cli/commands/environment_show.rb
+- lib/evilution/cli/commands/init.rb
+- lib/evilution/cli/commands/mcp.rb
+- lib/evilution/cli/commands/run.rb
+- lib/evilution/cli/commands/session_diff.rb
+- lib/evilution/cli/commands/session_gc.rb
+- lib/evilution/cli/commands/session_list.rb
+- lib/evilution/cli/commands/session_show.rb
+- lib/evilution/cli/commands/subjects.rb
+- lib/evilution/cli/commands/tests_list.rb
+- lib/evilution/cli/commands/util_mutation.rb
+- lib/evilution/cli/commands/version.rb
+- lib/evilution/cli/dispatcher.rb
+- lib/evilution/cli/parsed_args.rb
+- lib/evilution/cli/parser.rb
+- lib/evilution/cli/printers.rb
+- lib/evilution/cli/printers/environment.rb
+- lib/evilution/cli/printers/session_detail.rb
+- lib/evilution/cli/printers/session_diff.rb
+- lib/evilution/cli/printers/session_list.rb
+- lib/evilution/cli/printers/subjects.rb
+- lib/evilution/cli/printers/tests_list.rb
+- lib/evilution/cli/printers/util_mutation.rb
+- lib/evilution/cli/result.rb
 - lib/evilution/config.rb
 - lib/evilution/disable_comment.rb
 - lib/evilution/equivalent.rb
@@ -124,11 +150,13 @@ files:
 - lib/evilution/isolation/fork.rb
 - lib/evilution/isolation/in_process.rb
 - lib/evilution/mcp.rb
+- lib/evilution/mcp/info_tool.rb
 - lib/evilution/mcp/mutate_tool.rb
 - lib/evilution/mcp/server.rb
 - lib/evilution/mcp/session_diff_tool.rb
 - lib/evilution/mcp/session_list_tool.rb
 - lib/evilution/mcp/session_show_tool.rb
+- lib/evilution/mcp/session_tool.rb
 - lib/evilution/memory.rb
 - lib/evilution/memory/leak_check.rb
 - lib/evilution/mutation.rb