evilution 0.29.0 → 0.30.0

data/lib/evilution/ast/heredoc_span.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../ast"
+
+# Computes the byte-length needed for a mutation whose target range contains
+# heredoc anchors (`<<~MARKER` / `<<-MARKER` / `<<MARKER`).
+#
+# Prism reports a heredoc anchor's `location` as the inline range of just
+# `<<~MARKER` — the body lines and the closing terminator live in `closing_loc`
+# which is on a later line. An operator that builds a byte edit from the
+# anchor's inline range (e.g. `argument_removal` using
+# `node.arguments.location`) covers the anchor but leaves the body+terminator
+# in place, producing an orphaned heredoc fragment that the parser rejects.
+#
+# `extend_length` walks the supplied AST node for heredoc descendants whose
+# anchor falls inside `[offset, offset + length)` and returns a length wide
+# enough to also cover those descendants' `closing_loc.end_offset` — so the
+# mutation's `replacement` replaces the heredoc body and terminator along with
+# the anchor.
+module Evilution::AST::HeredocSpan
+  module_function
+
+  def extend_length(node:, offset:, length:)
+    return length if node.nil?
+
+    end_offset = offset + length
+    max_end = end_offset
+    Walker.new(offset, end_offset) do |closing_end|
+      max_end = closing_end if closing_end > max_end
+    end.visit(node)
+    max_end - offset
+  end
+
+  class Walker < Prism::Visitor
+    def initialize(start_offset, end_offset, &block)
+      super()
+      @start_offset = start_offset
+      @end_offset = end_offset
+      @block = block
+    end
+
+    def visit_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    def visit_interpolated_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    def visit_x_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    def visit_interpolated_x_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    private
+
+    def record_if_heredoc(node)
+      return unless heredoc?(node)
+
+      closing = node.closing_loc
+      return unless anchor_in_range?(node) && closing
+
+      @block.call(closing_end_excluding_trailing_newline(closing))
+    end
+
+    def heredoc?(node)
+      node.respond_to?(:heredoc?) && node.heredoc?
+    end
+
+    # Anchor must be inside the mutation's target range; only then does its
+    # heredoc body sit outside the range and need pulling in.
+    def anchor_in_range?(node)
+      opening = node.opening_loc
+      return false if opening.nil?
+
+      opening.start_offset >= @start_offset && opening.start_offset < @end_offset
+    end
+
+    # Prism's closing_loc covers the terminator including the trailing
+    # newline. Excluding that newline preserves line structure after the
+    # replacement (any code that follows lands on its own line).
+    def closing_end_excluding_trailing_newline(closing)
+      end_off = closing.end_offset
+      slice = closing.slice
+      end_off -= 1 if slice && slice.end_with?("\n")
+      end_off
+    end
+  end
+  private_constant :Walker
+end

data/lib/evilution/baseline.rb

@@ -15,16 +15,18 @@ class Evilution::Baseline
     end
   end
 
-  def initialize(spec_resolver: Evilution::SpecResolver.new, timeout: 30, runner: nil, fallback_dir: "spec")
+  def initialize(spec_resolver: Evilution::SpecResolver.new, timeout: 30, runner: nil,
+                 fallback_dir: "spec", test_files: nil)
     @spec_resolver = spec_resolver
     @timeout = timeout
     @runner = runner
     @fallback_dir = fallback_dir
+    @test_files = test_files
   end
 
   def call(subjects)
     start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    spec_files = resolve_unique_spec_files(subjects)
+    spec_files = baseline_spec_files(subjects)
     failed = Set.new
 
     spec_files.each do |spec_file|
@@ -96,6 +98,17 @@ class Evilution::Baseline
 
   private
 
+  # When --spec was provided, run those files only. Auto-discovery is skipped
+  # entirely — the user has declared what covers their subjects and any
+  # mismatch between auto-discovery and their declaration is what produced
+  # the misleading "No matching test found" warning users have reported even
+  # while passing --spec.
+  def baseline_spec_files(subjects)
+    return Array(@test_files).uniq if @test_files && !@test_files.empty?
+
+    resolve_unique_spec_files(subjects)
+  end
+
   def resolve_unique_spec_files(subjects)
     warned = Set.new
     subjects.map do |s|

data/lib/evilution/cli/commands/compare.rb

@@ -9,6 +9,7 @@ require_relative "../../compare"
 require_relative "../../compare/categorizer"
 require_relative "../../compare/detector"
 require_relative "../../compare/normalizer"
+require_relative "../../session/schema"
 
 class Evilution::CLI::Commands::Compare < Evilution::CLI::Command
   SUPPORTED_FORMATS = %i[json text].freeze
@@ -46,6 +47,7 @@ class Evilution::CLI::Commands::Compare < Evilution::CLI::Command
     raise Evilution::Error, "file not found: #{path}" unless File.exist?(path)
 
     json = JSON.parse(File.read(path))
+    validate_session_schema(json, path)
     tool = Evilution::Compare::Detector.call(json)
     normalize(json, tool)
   rescue ::JSON::ParserError => e
@@ -56,6 +58,17 @@ class Evilution::CLI::Commands::Compare < Evilution::CLI::Command
     raise Evilution::Error, e.message
   end
 
+  # Validate before detection: schema_version is an evilution-only marker. A
+  # future schema may rearrange the shape enough that Detector cannot classify
+  # it; in that case the user must still see "Upgrade the evilution gem", not
+  # "cannot detect tool".
+  def validate_session_schema(json, path)
+    return unless json.is_a?(Hash)
+    return unless json.key?("schema_version") || json.key?(:schema_version)
+
+    Evilution::Session::Schema.validate!(json, source: path)
+  end
+
   def normalize(json, tool)
     normalizer = Evilution::Compare::Normalizer.new
     case tool

data/lib/evilution/cli/parser/command_extractor.rb

@@ -16,6 +16,8 @@ class Evilution::CLI::Parser::CommandExtractor
     "gc" => :session_gc
   }.freeze
 
+  RUN_ALIASES = %w[run mutate].freeze
+
   TESTS_SUBCOMMANDS = { "list" => :tests_list }.freeze
   ENVIRONMENT_SUBCOMMANDS = { "show" => :environment_show }.freeze
   UTIL_SUBCOMMANDS = { "mutation" => :util_mutation }.freeze
@@ -51,7 +53,7 @@ class Evilution::CLI::Parser::CommandExtractor
     if SIMPLE_COMMANDS.key?(first)
       @command = SIMPLE_COMMANDS[first]
       @argv.shift
-    elsif first == "run"
+    elsif RUN_ALIASES.include?(first)
       @argv.shift
     elsif SUBCOMMAND_FAMILIES.key?(first)
       @argv.shift

data/lib/evilution/cli/parser/options_builder.rb

@@ -36,8 +36,8 @@ class Evilution::CLI::Parser::OptionsBuilder
     opts.separator ""
     opts.separator "Line-range targeting: lib/foo.rb:15-30, lib/foo.rb:15, lib/foo.rb:15-"
     opts.separator ""
-    opts.separator "Commands: run (default), init, session {list,show,diff,gc}, subjects, tests {list},"
-    opts.separator "         util {mutation}, environment {show}, compare, mcp, version"
+    opts.separator "Commands: run (default; alias: mutate), init, session {list,show,diff,gc}, subjects,"
+    opts.separator "         tests {list}, util {mutation}, environment {show}, compare, mcp, version"
     opts.separator ""
     opts.separator "Options:"
   end

data/lib/evilution/config/file_loader.rb

@@ -5,12 +5,19 @@ require "yaml"
 module Evilution::Config::FileLoader
   module_function
 
+  # Keys recognised in YAML config files. `target_files` is intentionally excluded
+  # because it is CLI-positional (the file paths after `evilution run`).
+  KNOWN_KEYS = (Evilution::Config::DEFAULTS.keys + %i[hooks]).uniq.freeze
+
   def load
     Evilution::Config::CONFIG_FILES.each do |path|
       next unless File.exist?(path)
 
       data = YAML.safe_load_file(path, symbolize_names: true)
-      return data.is_a?(Hash) ? data : {}
+      return {} unless data.is_a?(Hash)
+
+      validate_schema!(data, path: path) if data.key?(:schema_version)
+      return data
     rescue Psych::SyntaxError, Psych::DisallowedClass => e
       raise Evilution::ConfigError.new("failed to parse config file #{path}: #{e.message}", file: path)
     rescue SystemCallError => e
@@ -19,4 +26,36 @@ module Evilution::Config::FileLoader
 
     {}
   end
+
+  def validate_schema!(data, path:)
+    validate_schema_version_value!(data[:schema_version], path: path)
+    validate_known_keys!(data.keys, path: path)
+  end
+
+  def validate_schema_version_value!(version, path:)
+    unless version.is_a?(Integer) && version.positive?
+      raise Evilution::ConfigError.new(
+        "invalid schema_version #{version.inspect} in #{path}: must be a positive Integer",
+        file: path
+      )
+    end
+
+    return if version <= Evilution::Config::CURRENT_SCHEMA_VERSION
+
+    raise Evilution::ConfigError.new(
+      "schema_version #{version} in #{path} is newer than this evilution gem supports " \
+      "(current: #{Evilution::Config::CURRENT_SCHEMA_VERSION}). Upgrade the gem.",
+      file: path
+    )
+  end
+
+  def validate_known_keys!(keys, path:)
+    unknown = keys - KNOWN_KEYS
+    return if unknown.empty?
+
+    raise Evilution::ConfigError.new(
+      "unknown key(s) #{unknown.inspect} in #{path}. Known keys: #{KNOWN_KEYS.sort.inspect}",
+      file: path
+    )
+  end
 end

data/lib/evilution/config.rb

@@ -6,8 +6,10 @@ require_relative "spec_selector"
 
 class Evilution::Config
   CONFIG_FILES = %w[.evilution.yml config/evilution.yml].freeze
+  CURRENT_SCHEMA_VERSION = 1
 
   DEFAULTS = {
+    schema_version: CURRENT_SCHEMA_VERSION,
     timeout: 30, format: :text, target: nil, min_score: 0.0, integration: :rspec,
     verbose: false, quiet: false, jobs: 1, fail_fast: nil, baseline: true,
     isolation: :auto, incremental: false, suggest_tests: false, progress: true,
@@ -21,7 +23,7 @@ class Evilution::Config
     profile: :default
   }.freeze
 
-  attr_reader :target_files, :timeout, :format,
+  attr_reader :target_files, :schema_version, :timeout, :format,
               :target, :min_score, :integration, :verbose, :quiet,
               :jobs, :fail_fast, :baseline, :isolation, :incremental, :suggest_tests,
               :progress, :save_session, :line_ranges, :spec_files, :hooks,
@@ -112,6 +114,13 @@ class Evilution::Config
       # Evilution configuration
       # See: https://github.com/marinazzio/evilution
 
+      # Schema version for this config file (current: #{CURRENT_SCHEMA_VERSION}).
+      # Declaring schema_version opts the file into strict validation:
+      # unknown keys raise ConfigError, and a future schema_version is
+      # rejected so an old gem cannot silently misread a newer config.
+      # Omit to keep the legacy lenient behavior (unknown keys ignored).
+      schema_version: #{CURRENT_SCHEMA_VERSION}
+
       # Per-mutation timeout in seconds (default: 30)
       # timeout: 30
 
@@ -208,6 +217,7 @@ class Evilution::Config
 
   SIMPLE_ATTR_TRANSFORMS = {
     target_files: ->(v) { Array(v) },
+    schema_version: nil,
     timeout: nil,
     format: :to_sym.to_proc,
     target: nil,

data/lib/evilution/equivalent/heuristic/dead_code.rb

@@ -3,8 +3,15 @@
 require_relative "../heuristic"
 
 class Evilution::Equivalent::Heuristic::DeadCode
+  # Both operators produce statement-deletion-shaped edits. MutationPlanner
+  # dedupes by (file_path, mutated_source); whichever operator is registered
+  # first surfaces its name on the surviving mutation. Classify equivalence
+  # by edit shape, not by operator label, so dead-code classification holds
+  # regardless of registry order (EV-74e3 PR #1236 review).
+  STATEMENT_DELETION_OPERATORS = %w[statement_deletion last_expression_removal].to_set.freeze
+
   def match?(mutation)
-    return false unless mutation.operator_name == "statement_deletion"
+    return false unless STATEMENT_DELETION_OPERATORS.include?(mutation.operator_name)
 
     node = mutation.subject.node
     return false unless node

data/lib/evilution/feedback/setup_warning.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../feedback"
+
+# Detects "setup misconfiguration" patterns where mutation testing returned a
+# result that is technically valid (score 0.0 with all-errored mutations) but
+# is almost certainly the wrong score because the worker process couldn't
+# evaluate any mutated source.
+#
+# Most common cause: MCP runs default to `preload: false` to keep the long-lived
+# MCP server clean. Rails / Zeitwerk projects that depend on autoload then fail
+# in every worker with `NameError: uninitialized constant ...`. The user sees
+# "0% PASS-but-FAIL" with no obvious hint that they need to pass an explicit
+# `preload: spec/rails_helper.rb` option.
+#
+# When triggered, this returns a warning string the MCP response can surface
+# alongside the trimmed report — turning a silent wrong score into a loud
+# pointer at the likely fix.
+module Evilution::Feedback::SetupWarning
+  module_function
+
+  ERROR_DOMINANCE_THRESHOLD = 0.8
+  ERROR_CLASS_CLUSTER_THRESHOLD = 0.8
+
+  def call(summary)
+    return nil if summary.nil?
+    return nil unless errors_dominate?(summary)
+
+    errored = summary.results.select(&:error?)
+    dominant_class = dominant_error_class(errored)
+    return nil unless dominant_class
+
+    message_for(dominant_class, errored.size, summary.total)
+  end
+
+  def errors_dominate?(summary)
+    return false if summary.total.zero?
+
+    summary.errors.to_f / summary.total >= ERROR_DOMINANCE_THRESHOLD
+  end
+  private_class_method :errors_dominate?
+
+  def dominant_error_class(errored_results)
+    return nil if errored_results.empty?
+
+    counts = errored_results.each_with_object(Hash.new(0)) do |result, acc|
+      acc[result.error_class] += 1 if result.error_class
+    end
+    return nil if counts.empty?
+
+    klass, count = counts.max_by { |_, v| v }
+    return nil if count.to_f / errored_results.size < ERROR_CLASS_CLUSTER_THRESHOLD
+
+    klass
+  end
+  private_class_method :dominant_error_class
+
+  NAME_ERROR_HINT = "Most mutations errored with NameError. This usually means autoloaded constants " \
+                    "(Rails / Zeitwerk) weren't available when the mutation re-evaluated the source. " \
+                    "Pass `preload: 'spec/rails_helper.rb'` (or your project's preload entry) so the " \
+                    "MCP server requires it before forking workers."
+
+  LOAD_ERROR_HINT = "Most mutations errored with LoadError. A `require` in the mutated source path " \
+                    "failed before any test ran. Check that the file's dependencies are reachable from " \
+                    "the MCP server's load path, or pass `preload: '<entrypoint>'` to set them up."
+
+  GENERIC_HINT_TEMPLATE = "Most mutations errored with %<klass>s (%<count>d / %<total>d). The mutation " \
+                          "score reflects this setup failure, not the test suite. Try the CLI for an " \
+                          "independent reading, or pass `preload: '<path>'` if the failure is autoload-related."
+
+  def message_for(klass, count, total)
+    case klass.to_s
+    when "NameError" then NAME_ERROR_HINT
+    when "LoadError" then LOAD_ERROR_HINT
+    else format(GENERIC_HINT_TEMPLATE, klass: klass, count: count, total: total)
+    end
+  end
+  private_class_method :message_for
+end

data/lib/evilution/gem_detector.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Evilution::GemDetector
+  @cache = {}
+  @mutex = Mutex.new
+
+  class << self
+    def gem_root_for(path)
+      return nil if path.nil?
+
+      dir = starting_dir(path)
+      return nil if dir.nil?
+
+      @mutex.synchronize do
+        return @cache[dir] if @cache.key?(dir)
+
+        @cache[dir] = walk_up(dir)
+      end
+    end
+
+    def gem_root_for_any(paths)
+      Array(paths).each do |path|
+        root = gem_root_for(path)
+        return root if root
+      end
+      nil
+    end
+
+    def gem_entry_for(root, target_paths: nil)
+      gem_name = gem_name_for(root, target_paths: target_paths)
+      return nil unless gem_name
+
+      dotted = File.join(root, "lib", "#{gem_name.tr("-", "/")}.rb")
+      return dotted if File.file?(dotted)
+
+      flat = File.join(root, "lib", "#{gem_name}.rb")
+      return flat if File.file?(flat)
+
+      nil
+    end
+
+    def reset_cache!
+      @mutex.synchronize { @cache.clear }
+    end
+
+    private
+
+    def starting_dir(path)
+      return File.expand_path(path) if File.directory?(path)
+      return File.expand_path(File.dirname(path)) if File.file?(path)
+
+      parent = File.expand_path(File.dirname(path))
+      File.directory?(parent) ? parent : nil
+    end
+
+    def walk_up(dir)
+      current = dir
+      loop do
+        return current unless Dir.glob(File.join(current, "*.gemspec")).empty?
+
+        parent = File.dirname(current)
+        return nil if parent == current
+
+        current = parent
+      end
+    end
+
+    # When the root has multiple gemspecs (e.g. dotenv ships dotenv.gemspec
+    # alongside dotenv-rails.gemspec), `Dir.glob.first` is filesystem-order-
+    # dependent and often picks the wrong one — preloading the rails companion
+    # then raises `uninitialized constant Rails`. Disambiguate by:
+    #   1. exact-entry match — if a target is *exactly* the lib entry for a
+    #      gemspec (`lib/dotenv/rails.rb` for `dotenv-rails.gemspec`), use it
+    #   2. first-lib-subdir match — `lib/dotenv/parser.rb` matches `dotenv`
+    #   3. fall back to the shortest gemspec basename — `dotenv` <
+    #      `dotenv-rails`, which is the conventional "parent" gem.
+    def gem_name_for(root, target_paths: nil)
+      names = Dir.glob(File.join(root, "*.gemspec")).map { |p| File.basename(p, ".gemspec") }
+      return nil if names.empty?
+      return names.first if names.length == 1
+
+      paths = Array(target_paths)
+      match_by_exact_entry(root, names, paths) ||
+        match_by_subdir(root, names, paths) ||
+        names.min_by(&:length)
+    end
+
+    def match_by_exact_entry(root, names, paths)
+      paths.each do |path|
+        next if path.nil?
+
+        expanded = File.expand_path(path)
+        match = names.find { |n| entry_paths_for(root, n).include?(expanded) }
+        return match if match
+      end
+      nil
+    end
+
+    def entry_paths_for(root, gem_name)
+      [
+        File.join(root, "lib", "#{gem_name.tr("-", "/")}.rb"),
+        File.join(root, "lib", "#{gem_name}.rb")
+      ]
+    end
+
+    def match_by_subdir(root, names, paths)
+      paths.each do |path|
+        subdir = lib_subdir_for(root, path)
+        next if subdir.nil?
+
+        match = names.find { |n| n == subdir }
+        return match if match
+      end
+      nil
+    end
+
+    # For `<root>/lib/dotenv/parser.rb` returns "dotenv". For
+    # `<root>/lib/dotenv-rails.rb` returns "dotenv-rails". Returns nil when
+    # the target isn't under `<root>/lib/`.
+    def lib_subdir_for(root, path)
+      return nil if path.nil?
+
+      expanded = File.expand_path(path)
+      lib_root = File.join(File.expand_path(root), "lib")
+      return nil unless expanded.start_with?("#{lib_root}/")
+
+      relative = expanded[(lib_root.length + 1)..]
+      first_segment = relative.split("/", 2).first
+      File.basename(first_segment, ".rb")
+    end
+  end
+end