evilution 0.22.7 → 0.24.0

data/lib/evilution/config.rb

@@ -27,6 +27,8 @@ class Evilution::Config
     show_disabled: false,
     baseline_session: nil,
     skip_heredoc_literals: false,
+    related_specs_heuristic: false,
+    fallback_to_full_suite: false,
     preload: nil
   }.freeze
 
@@ -35,7 +37,8 @@ class Evilution::Config
               :jobs, :fail_fast, :baseline, :isolation, :incremental, :suggest_tests,
               :progress, :save_session, :line_ranges, :spec_files, :hooks,
               :ignore_patterns, :show_disabled, :baseline_session,
-              :skip_heredoc_literals, :preload
+              :skip_heredoc_literals, :related_specs_heuristic,
+              :fallback_to_full_suite, :preload
 
   def initialize(**options)
     file_options = options.delete(:skip_config_file) ? {} : load_config_file
@@ -96,6 +99,14 @@ class Evilution::Config
     skip_heredoc_literals
   end
 
+  def related_specs_heuristic?
+    related_specs_heuristic
+  end
+
+  def fallback_to_full_suite?
+    fallback_to_full_suite
+  end
+
   def self.file_options
     CONFIG_FILES.each do |path|
       next unless File.exist?(path)
@@ -138,8 +149,23 @@ class Evilution::Config
       # Generate concrete test code in suggestions, matching integration (default: false)
       # suggest_tests: false
 
-      # Skip all string literal mutations inside heredocs (default: false)
-      # skip_heredoc_literals: false
+      # Skip all string literal mutations inside heredocs (default: false).
+      # Useful for Rails apps where heredoc content (SQL, templates, fixtures)
+      # rarely has meaningful test coverage and produces noisy survivors.
+      # skip_heredoc_literals: true
+
+      # Opt into the RelatedSpecHeuristic, which appends request/integration/
+      # feature/system specs for mutations that touch `.includes(...)` calls
+      # (default: false). Off by default because the fan-out can be heavy and
+      # push runs over the per-mutation timeout. Enable if you need coverage
+      # of N+1 regressions that only surface in higher-level specs.
+      # related_specs_heuristic: true
+
+      # When no matching spec resolves for a mutation's source file, the
+      # default is to skip that mutation and mark it :unresolved in the
+      # report (a coverage gap signal). Set to true to fall back to running
+      # the entire test suite for such mutations instead (slow, high memory).
+      # fallback_to_full_suite: false
 
       # Preload file required in the parent process before forking workers.
       # For Rails projects, spec/rails_helper.rb or test/test_helper.rb is
@@ -195,6 +221,8 @@ class Evilution::Config
     @show_disabled = merged[:show_disabled]
     @baseline_session = merged[:baseline_session]
     @skip_heredoc_literals = merged[:skip_heredoc_literals]
+    @related_specs_heuristic = merged[:related_specs_heuristic]
+    @fallback_to_full_suite = merged[:fallback_to_full_suite]
     @hooks = validate_hooks(merged[:hooks])
     @preload = validate_preload(merged[:preload])
   end

data/lib/evilution/integration/base.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
-require "fileutils"
 require "prism"
-require "tmpdir"
 require_relative "../integration"
-require_relative "../temp_dir_tracker"
 
 class Evilution::Integration::Base
   def self.baseline_runner
@@ -20,7 +17,6 @@ class Evilution::Integration::Base
   end
 
   def call(mutation)
-    @temp_dir = nil
     ensure_framework_loaded
     fire_hook(:mutation_insert_pre, mutation: mutation, file_path: mutation.file_path)
     load_error = apply_mutation(mutation)
@@ -28,8 +24,6 @@ class Evilution::Integration::Base
 
     fire_hook(:mutation_insert_post, mutation: mutation, file_path: mutation.file_path)
     run_tests(mutation)
-  ensure
-    restore_original(mutation)
   end
 
   private
@@ -55,15 +49,13 @@ class Evilution::Integration::Base
   end
 
   def apply_mutation(mutation)
-    @temp_dir = Dir.mktmpdir("evilution")
-    Evilution::TempDirTracker.register(@temp_dir)
-    @displaced_feature = nil
-    subpath = resolve_require_subpath(mutation.file_path)
-
-    if subpath
-      apply_via_require(mutation, subpath)
-    else
-      apply_via_load(mutation)
+    prism_error = validate_mutated_syntax(mutation.mutated_source)
+    return prism_error if prism_error
+
+    pin_autoloaded_constants(mutation.original_source)
+    clear_concern_state(mutation.file_path)
+    with_redefinition_recovery(mutation.original_source) do
+      eval_mutated_source(mutation)
     end
     nil
   rescue SyntaxError => e
@@ -82,29 +74,25 @@ class Evilution::Integration::Base
     }
   end
 
-  def apply_via_require(mutation, subpath)
-    dest = File.join(@temp_dir, subpath)
-    FileUtils.mkdir_p(File.dirname(dest))
-    File.write(dest, mutation.mutated_source)
-    $LOAD_PATH.unshift(@temp_dir)
-    displace_loaded_feature(mutation.file_path)
-    pin_autoloaded_constants(mutation.original_source)
-    clear_concern_state(mutation.file_path)
-    with_redefinition_recovery(mutation.original_source) do
-      require(subpath.delete_suffix(".rb"))
-    end
+  def validate_mutated_syntax(source)
+    return nil if Prism.parse(source).success?
+
+    {
+      passed: false,
+      error: "mutated source has syntax errors",
+      error_class: "SyntaxError",
+      error_backtrace: []
+    }
   end
 
-  def apply_via_load(mutation)
+  # Evaluate the mutated source with __FILE__ set to the original path so
+  # that `require_relative` and `__dir__` resolve against the real source
+  # tree, where sibling files actually exist.
+  def eval_mutated_source(mutation)
     absolute = File.expand_path(mutation.file_path)
-    dest = File.join(@temp_dir, absolute)
-    FileUtils.mkdir_p(File.dirname(dest))
-    File.write(dest, mutation.mutated_source)
-    pin_autoloaded_constants(mutation.original_source)
-    clear_concern_state(mutation.file_path)
-    with_redefinition_recovery(mutation.original_source) do
-      load(dest)
-    end
+    # rubocop:disable Security/Eval
+    eval(mutation.mutated_source, TOPLEVEL_BINDING, absolute, 1)
+    # rubocop:enable Security/Eval
   end
 
   def with_redefinition_recovery(original_source)
@@ -120,18 +108,6 @@ class Evilution::Integration::Base
     error.message.include?("already defined")
   end
 
-  def restore_original(_mutation)
-    return unless @temp_dir
-
-    $LOAD_PATH.delete(@temp_dir)
-    $LOADED_FEATURES.reject! { |f| f.start_with?(@temp_dir) }
-    $LOADED_FEATURES << @displaced_feature if @displaced_feature && !$LOADED_FEATURES.include?(@displaced_feature)
-    @displaced_feature = nil
-    FileUtils.rm_rf(@temp_dir)
-    Evilution::TempDirTracker.unregister(@temp_dir)
-    @temp_dir = nil
-  end
-
   def pin_autoloaded_constants(source)
     collect_constant_names(Prism.parse(source).value).each do |name|
       Object.const_get(name) if Object.const_defined?(name, false)
@@ -223,12 +199,4 @@ class Evilution::Integration::Base
 
     best_subpath
   end
-
-  def displace_loaded_feature(file_path)
-    absolute = File.expand_path(file_path)
-    return unless $LOADED_FEATURES.include?(absolute)
-
-    @displaced_feature = absolute
-    $LOADED_FEATURES.delete(absolute)
-  end
 end

data/lib/evilution/integration/minitest.rb

@@ -35,10 +35,11 @@ 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)
     @test_files = test_files
     @minitest_loaded = false
     @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 +63,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 +78,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,7 +124,12 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     if passed
       { passed: true, test_command: command }
     elsif detector.only_crashes?
-      { passed: false, error: "test crashes: #{detector.crash_summary}", test_command: command }
+      {
+        passed: false,
+        test_crashed: true,
+        error: "test crashes: #{detector.crash_summary}",
+        test_command: command
+      }
     else
       { passed: false, test_command: command }
     end
@@ -124,7 +141,7 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     resolved = @spec_resolver.call(mutation.file_path)
     unless resolved
       warn_unresolved_test(mutation.file_path)
-      return glob_test_files
+      return @fallback_to_full_suite ? glob_test_files : nil
     end
 
     [resolved]
@@ -139,7 +156,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/rspec.rb

@@ -26,11 +26,13 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     { runner: baseline_runner }
   end
 
-  def initialize(test_files: nil, hooks: nil)
+  def initialize(test_files: nil, hooks: nil, related_specs_heuristic: false, fallback_to_full_suite: false)
     @test_files = test_files
     @rspec_loaded = false
     @spec_resolver = Evilution::SpecResolver.new
     @related_spec_heuristic = Evilution::RelatedSpecHeuristic.new
+    @related_specs_heuristic_enabled = related_specs_heuristic
+    @fallback_to_full_suite = fallback_to_full_suite
     @crash_detector = nil
     @warned_files = Set.new
     super(hooks: hooks)
@@ -56,10 +58,12 @@ 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?
+
     out = StringIO.new
     err = StringIO.new
-    command = "rspec"
-    args = build_args(mutation)
+    args = build_args(files)
     command = "rspec #{args.join(" ")}"
 
     detector = reset_crash_detector
@@ -73,11 +77,19 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     release_rspec_state(eg_before)
   end
 
-  def build_args(mutation)
-    files = resolve_test_files(mutation)
+  def build_args(files)
     ["--format", "progress", "--no-color", "--order", "defined", *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 reset_state
     if ::RSpec.respond_to?(:clear_examples)
       ::RSpec.clear_examples
@@ -140,7 +152,12 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     if status.zero?
       { passed: true, test_command: command }
     elsif detector.only_crashes?
-      { passed: false, error: "test crashes: #{detector.crash_summary}", test_command: command }
+      {
+        passed: false,
+        test_crashed: true,
+        error: "test crashes: #{detector.crash_summary}",
+        test_command: command
+      }
     else
       { passed: false, test_command: command }
     end
@@ -152,9 +169,11 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     resolved = @spec_resolver.call(mutation.file_path)
     unless resolved
       warn_unresolved_spec(mutation.file_path)
-      return ["spec"]
+      return @fallback_to_full_suite ? ["spec"] : nil
     end
 
+    return [resolved] unless @related_specs_heuristic_enabled
+
     related = @related_spec_heuristic.call(mutation)
     ([resolved] + related).uniq
   end
@@ -163,7 +182,8 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     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

@@ -95,16 +95,18 @@ class Evilution::Isolation::Fork
     ::Process.wait(pid) rescue nil # rubocop:disable Style/RescueModifier
   end
 
+  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]
+
+    :killed
+  end
+
   def build_mutation_result(mutation, result, duration, parent_rss_kb)
-    status = if result[:timeout]
-               :timeout
-             elsif result[:error]
-               :error
-             elsif result[:passed]
-               :survived
-             else
-               :killed
-             end
+    status = classify_status(result)
 
     Evilution::Result::MutationResult.new(
       mutation: mutation,

data/lib/evilution/isolation/in_process.rb

@@ -62,16 +62,18 @@ class Evilution::Isolation::InProcess
     rss_after - rss_before
   end
 
+  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]
+
+    :killed
+  end
+
   def build_mutation_result(mutation, result, duration, rss_before, rss_after, memory_delta_kb)
-    status = if result[:timeout]
-               :timeout
-             elsif result[:error]
-               :error
-             elsif result[:passed]
-               :survived
-             else
-               :killed
-             end
+    status = classify_status(result)
 
     Evilution::Result::MutationResult.new(
       mutation: mutation,

data/lib/evilution/mcp/info_tool.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "json"
+require "mcp"
+require_relative "../config"
+require_relative "../runner"
+require_relative "../mutator/registry"
+require_relative "../spec_resolver"
+require_relative "../ast/pattern/filter"
+require_relative "../version"
+
+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: " \
+              "'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). " \
+              "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],
+        description: "Which discovery operation to perform. " \
+                     "'subjects' lists mutatable methods; 'tests' resolves specs for sources; 'environment' dumps effective config."
+      },
+      files: {
+        type: "array",
+        items: { type: "string" },
+        description: "[subjects, tests] Target source files. Supports line-range syntax " \
+                     "(lib/foo.rb:15-30, lib/foo.rb:15, lib/foo.rb:15-); for 'tests' the range is " \
+                     "stripped before spec resolution."
+      },
+      target: {
+        type: "string",
+        description: "[subjects] Filter expression: method (Foo#bar), type (Foo#/Foo.), namespace (Foo*), class (Foo)"
+      },
+      spec: {
+        type: "array",
+        items: { type: "string" },
+        description: "[tests] Explicit spec files to return instead of auto-resolving from sources"
+      },
+      integration: {
+        type: "string",
+        description: "[subjects, tests] Test integration (rspec, minitest) — 'tests' selects " \
+                     "the matching spec resolver (spec/*_spec.rb for rspec, test/*_test.rb for minitest)"
+      },
+      skip_config: {
+        type: "boolean",
+        description: "[subjects, tests] When true, ignore .evilution.yml / config/evilution.yml; " \
+                     "explicit tool parameters still apply. " \
+                     "Default: false — project config is loaded so the result reflects what `evilution` CLI would see."
+      }
+    },
+    required: ["action"]
+  )
+
+  VALID_ACTIONS = %w[subjects tests environment].freeze
+
+  class << self
+    # rubocop:disable Lint/UnusedMethodArgument
+    def call(server_context:, action: nil, files: nil, target: nil, spec: nil, integration: nil, skip_config: nil)
+      return error_response("config_error", "action is required") unless action
+      return error_response("config_error", "unknown action: #{action}") unless VALID_ACTIONS.include?(action)
+
+      parsed_files, line_ranges = parse_files(Array(files)) if files
+
+      case action
+      when "subjects"
+        subjects_action(files: parsed_files, line_ranges: line_ranges, target: target,
+                        integration: integration, skip_config: skip_config)
+      when "tests"
+        tests_action(files: parsed_files, spec: spec, integration: integration, skip_config: skip_config)
+      when "environment"
+        environment_action
+      end
+    rescue Evilution::Error => e
+      error_response_for(e)
+    end
+    # rubocop:enable Lint/UnusedMethodArgument
+
+    private
+
+    def parse_files(raw_files)
+      files = []
+      ranges = {}
+
+      raw_files.each do |arg|
+        file, range_str = arg.split(":", 2)
+        files << file
+        ranges[file] = parse_line_range(range_str) if 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 subjects_action(files:, line_ranges:, target:, integration:, skip_config:)
+      return error_response("config_error", "files is required") if files.nil? || files.empty?
+
+      config = build_subjects_config(files: files, line_ranges: line_ranges,
+                                     target: target, integration: integration, skip_config: skip_config)
+      runner = Evilution::Runner.new(config: config)
+      subjects = runner.parse_and_filter_subjects
+
+      registry = Evilution::Mutator::Registry.default
+      filter = build_subject_filter(config)
+      operator_options = { skip_heredoc_literals: config.skip_heredoc_literals? }
+
+      entries = subjects.map do |subj|
+        count = registry.mutations_for(subj, filter: filter, operator_options: operator_options).length
+        { "name" => subj.name, "file" => subj.file_path, "line" => subj.line_number, "mutations" => count }
+      ensure
+        subj.release_node!
+      end
+
+      success_response(
+        "subjects" => entries,
+        "total_subjects" => entries.length,
+        "total_mutations" => entries.sum { |e| e["mutations"] }
+      )
+    end
+
+    def tests_action(files:, spec:, integration:, skip_config:)
+      return error_response("config_error", "files is required") if files.nil? || files.empty?
+
+      config = build_tests_config(files: files, spec: spec, integration: integration, skip_config: skip_config)
+      return explicit_specs_response(files, config.spec_files) if config.spec_files.any?
+
+      resolver = resolver_for_integration(config.integration)
+      resolved, unresolved = resolve_specs(files, resolver)
+      success_response(
+        "specs" => resolved,
+        "unresolved" => unresolved,
+        "total_sources" => files.length,
+        "total_specs" => resolved.map { |r| r["spec"] }.uniq.length
+      )
+    end
+
+    def build_subjects_config(files:, line_ranges:, target:, integration:, skip_config:)
+      opts = { target_files: files, line_ranges: line_ranges || {} }
+      opts[:skip_config_file] = true if skip_config
+      opts[:target] = target if target
+      opts[:integration] = integration if integration
+      Evilution::Config.new(**opts)
+    end
+
+    def build_tests_config(files:, spec:, integration:, skip_config:)
+      opts = { target_files: files }
+      opts[:skip_config_file] = true if skip_config
+      opts[:spec_files] = spec if spec
+      opts[:integration] = integration if integration
+      Evilution::Config.new(**opts)
+    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 explicit_specs_response(files, spec_files)
+      success_response(
+        "specs" => spec_files.map { |f| { "source" => nil, "spec" => f } },
+        "unresolved" => [],
+        "total_sources" => files.length,
+        "total_specs" => spec_files.length
+      )
+    end
+
+    def resolve_specs(files, resolver)
+      resolved = []
+      unresolved = []
+      files.each do |source|
+        found = resolver.call(source)
+        if found
+          resolved << { "source" => source, "spec" => found }
+        else
+          unresolved << source
+        end
+      end
+      [resolved, unresolved]
+    end
+
+    def environment_action
+      config = Evilution::Config.new(skip_config_file: false)
+      config_file = Evilution::Config::CONFIG_FILES.find { |path| File.exist?(path) }
+
+      success_response(
+        "version" => Evilution::VERSION,
+        "ruby" => RUBY_VERSION,
+        "config_file" => config_file,
+        "settings" => environment_settings(config)
+      )
+    end
+
+    def error_response_for(error)
+      type = case error
+             when Evilution::ConfigError then "config_error"
+             when Evilution::ParseError then "parse_error"
+             else "runtime_error"
+             end
+      error_response(type, error.message)
+    end
+
+    def environment_settings(config)
+      {
+        "timeout" => config.timeout,
+        "format" => config.format,
+        "integration" => config.integration,
+        "jobs" => config.jobs,
+        "isolation" => config.isolation,
+        "baseline" => config.baseline,
+        "incremental" => config.incremental,
+        "fail_fast" => config.fail_fast,
+        "min_score" => config.min_score,
+        "suggest_tests" => config.suggest_tests,
+        "save_session" => config.save_session,
+        "target" => config.target,
+        "skip_heredoc_literals" => config.skip_heredoc_literals,
+        "ignore_patterns" => config.ignore_patterns
+      }
+    end
+
+    def build_subject_filter(config)
+      return nil if config.ignore_patterns.empty?
+
+      Evilution::AST::Pattern::Filter.new(config.ignore_patterns)
+    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