evilution 0.23.0 → 0.25.0

data/lib/evilution/compare/normalizer.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "../compare"
+require_relative "record"
+require_relative "fingerprint"
+
+class Evilution::Compare::Normalizer
+  EVILUTION_BUCKETS = %w[killed survived timed_out errors neutral equivalent unresolved unparseable].freeze
+  EVILUTION_STATUS_MAP = {
+    "killed" => :killed,
+    "survived" => :survived,
+    "timeout" => :timeout,
+    "error" => :error,
+    "neutral" => :neutral,
+    "equivalent" => :equivalent,
+    "unresolved" => :unresolved,
+    "unparseable" => :unparseable
+  }.freeze
+
+  def from_evilution(json)
+    records = []
+    EVILUTION_BUCKETS.each do |bucket|
+      Array(json[bucket]).each do |entry|
+        records << build_evilution_record(entry, index: records.size)
+      end
+    end
+    records
+  end
+
+  def from_mutant(json)
+    records = []
+    Array(json["subject_results"]).each do |subject|
+      source_path = subject["source_path"] or
+        raise Evilution::Compare::InvalidInput.new("missing 'source_path' on subject", index: records.size)
+      Array(subject["coverage_results"]).each do |cov|
+        records << build_mutant_record(cov, source_path: source_path, index: records.size)
+      end
+    end
+    records
+  end
+
+  private
+
+  def build_evilution_record(entry, index:)
+    file_path = entry["file"] or raise Evilution::Compare::InvalidInput.new("missing 'file' in record", index: index)
+    line = entry["line"] or raise Evilution::Compare::InvalidInput.new("missing 'line' in record", index: index)
+    diff = entry["diff"].to_s
+    status = EVILUTION_STATUS_MAP[entry["status"]] ||
+             raise(Evilution::Compare::InvalidInput.new("unknown status #{entry["status"].inspect}", index: index))
+    body = Evilution::Compare::Fingerprint.extract_from_evilution_diff(diff)
+    Evilution::Compare::Record.new(
+      source: :evilution,
+      file_path: file_path,
+      line: line,
+      status: status,
+      fingerprint: Evilution::Compare::Fingerprint.compute(file_path: file_path, line: line, body: body),
+      operator: entry["operator"],
+      diff_body: diff,
+      raw: entry
+    )
+  end
+
+  def build_mutant_record(cov, source_path:, index:)
+    mr = cov["mutation_result"] or raise Evilution::Compare::InvalidInput.new("missing mutation_result", index: index)
+    cr = cov["criteria_result"] or raise Evilution::Compare::InvalidInput.new("missing criteria_result", index: index)
+    ident = mr["mutation_identification"].to_s
+    line = parse_mutant_line(ident, index)
+    diff = mr["mutation_diff"].to_s
+    status = derive_mutant_status(mr, cr, index)
+    body = Evilution::Compare::Fingerprint.extract_from_mutant_diff(diff)
+    Evilution::Compare::Record.new(
+      source: :mutant,
+      file_path: source_path,
+      line: line,
+      status: status,
+      fingerprint: Evilution::Compare::Fingerprint.compute(file_path: source_path, line: line, body: body),
+      operator: nil,
+      diff_body: diff,
+      raw: { "mutation_result" => mr, "criteria_result" => cr, "source_path" => source_path }
+    )
+  end
+
+  # mutant_identification format: <type>:<subject>:<path>:<line>:<sha1[0..4]>.
+  # Line is always the second-to-last colon-separated field. Works with paths
+  # containing colons (e.g. Windows drive letters) because we index from the
+  # right, but a malformed path-less identification will raise InvalidInput.
+  def parse_mutant_line(ident, index)
+    parts = ident.split(":")
+    raise Evilution::Compare::InvalidInput.new("cannot parse line from #{ident.inspect}", index: index) if parts.length < 5
+
+    Integer(parts[-2])
+  rescue ArgumentError
+    raise Evilution::Compare::InvalidInput.new("non-integer line in #{ident.inspect}", index: index)
+  end
+
+  def derive_mutant_status(mr, cr, index)
+    type = mr["mutation_type"]
+    return :neutral if %w[neutral noop].include?(type)
+    return :timeout if cr["timeout"]
+    return :error   if cr["process_abort"]
+    return :killed  if cr["test_result"]
+    return :survived if type == "evil"
+
+    raise Evilution::Compare::InvalidInput.new("unknown mutant result shape: type=#{type.inspect} cr=#{cr.inspect}", index: index)
+  end
+end

data/lib/evilution/compare/record.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "../compare"
+
+module Evilution::Compare
+  Record = Data.define(
+    :source,
+    :file_path,
+    :line,
+    :status,
+    :fingerprint,
+    :operator,
+    :diff_body,
+    :raw
+  )
+end

data/lib/evilution/compare.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/OneClassPerFile
+module Evilution::Compare
+end
+
+class Evilution::Compare::InvalidInput < StandardError
+  attr_reader :index
+
+  def initialize(message, index: nil)
+    super(message)
+    @index = index
+  end
+end
+# rubocop:enable Style/OneClassPerFile

data/lib/evilution/config.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "yaml"
+require_relative "spec_resolver"
+require_relative "spec_selector"
 
 class Evilution::Config
   CONFIG_FILES = %w[.evilution.yml config/evilution.yml].freeze
@@ -28,19 +30,32 @@ class Evilution::Config
     baseline_session: nil,
     skip_heredoc_literals: false,
     related_specs_heuristic: false,
-    preload: nil
+    fallback_to_full_suite: false,
+    preload: nil,
+    spec_mappings: {},
+    spec_pattern: nil,
+    example_targeting: true,
+    example_targeting_fallback: :full_file,
+    example_targeting_cache: { max_files: 50, max_blocks: 10_000 }
   }.freeze
 
+  EXAMPLE_TARGETING_FALLBACKS = %i[full_file unresolved].freeze
+  private_constant :EXAMPLE_TARGETING_FALLBACKS
+
   attr_reader :target_files, :timeout, :format,
               :target, :min_score, :integration, :verbose, :quiet,
               :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, :related_specs_heuristic, :preload
+              :skip_heredoc_literals, :related_specs_heuristic,
+              :fallback_to_full_suite, :preload, :spec_mappings, :spec_pattern,
+              :example_targeting, :example_targeting_fallback, :example_targeting_cache,
+              :spec_selector
 
   def initialize(**options)
     file_options = options.delete(:skip_config_file) ? {} : load_config_file
-    merged = DEFAULTS.merge(file_options).merge(options)
+    env_options = load_env_options
+    merged = DEFAULTS.merge(file_options).merge(env_options).merge(options)
     assign_attributes(merged)
     freeze
   end
@@ -101,6 +116,14 @@ class Evilution::Config
     related_specs_heuristic
   end
 
+  def example_targeting?
+    example_targeting
+  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)
@@ -155,6 +178,12 @@ class Evilution::Config
       # 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
       # auto-detected when isolation resolves to :fork. Set to false to disable.
@@ -165,6 +194,23 @@ class Evilution::Config
       #   worker_process_start: config/evilution_hooks/worker_start.rb
       #   mutation_insert_pre: config/evilution_hooks/mutation_pre.rb
 
+      # Per-mutation example targeting (default: true). When enabled, Evilution
+      # parses resolved spec files and restricts each mutation run to examples
+      # whose bodies reference the mutated method/class token. Set to false
+      # to run every example in the resolved spec files. You can also disable
+      # without editing the file by exporting EV_DISABLE_EXAMPLE_TARGETING=1.
+      # example_targeting: true
+
+      # Behavior when targeting finds no matching example (default: full_file).
+      # full_file  - run every example in the resolved spec files
+      # unresolved - mark the mutation :unresolved and skip
+      # example_targeting_fallback: full_file
+
+      # LRU cache bounds for the spec AST parser that powers example targeting.
+      # example_targeting_cache:
+      #   max_files: 50
+      #   max_blocks: 10000
+
       # AST patterns to skip during mutation generation (default: [])
       # See docs/ast_pattern_syntax.md for pattern syntax
       # ignore_patterns:
@@ -210,8 +256,91 @@ class Evilution::Config
     @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])
+    @spec_mappings = validate_spec_mappings(merged[:spec_mappings])
+    @spec_pattern = validate_spec_pattern(merged[:spec_pattern])
+    assign_example_targeting(merged)
+    @spec_selector = build_spec_selector
+  end
+
+  def assign_example_targeting(merged)
+    @example_targeting = merged[:example_targeting] ? true : false
+    @example_targeting_fallback = validate_example_targeting_fallback(merged[:example_targeting_fallback])
+    @example_targeting_cache = validate_example_targeting_cache(merged[:example_targeting_cache])
+  end
+
+  def build_spec_selector
+    Evilution::SpecSelector.new(
+      spec_files: @spec_files,
+      spec_mappings: @spec_mappings,
+      spec_pattern: @spec_pattern,
+      spec_resolver: build_spec_resolver
+    )
+  end
+
+  def build_spec_resolver
+    case @integration
+    when :minitest
+      Evilution::SpecResolver.new(test_dir: "test", test_suffix: "_test.rb", request_dir: "integration")
+    else
+      Evilution::SpecResolver.new
+    end
+  end
+
+  def validate_spec_mappings(value)
+    return {} if value.nil?
+
+    raise Evilution::ConfigError, "spec_mappings must be a Hash, got #{value.class}" unless value.is_a?(Hash)
+
+    normalized = value.each_with_object({}) do |(source, specs), acc|
+      key = normalize_spec_mappings_key(source)
+      acc[key] = normalize_spec_mappings_value(key, specs)
+    end
+
+    warn_missing_spec_mappings(normalized)
+    normalized
+  end
+
+  def normalize_spec_mappings_key(source)
+    key = source.to_s
+    key = key.delete_prefix("#{Dir.pwd}/") if key.start_with?("/")
+    key.delete_prefix("./")
+  end
+
+  def normalize_spec_mappings_value(source, specs)
+    case specs
+    when String then [specs]
+    when Array
+      specs.each do |entry|
+        unless entry.is_a?(String)
+          raise Evilution::ConfigError,
+                "spec_mappings[#{source.inspect}] entries must be string paths, got #{entry.class}"
+        end
+      end
+      specs
+    else
+      raise Evilution::ConfigError,
+            "spec_mappings[#{source.inspect}] must be a string or array of strings, got #{specs.class}"
+    end
+  end
+
+  def warn_missing_spec_mappings(mappings)
+    mappings.each do |source, specs|
+      specs.each do |spec_path|
+        next if File.exist?(spec_path)
+
+        warn "[evilution] spec_mappings[#{source.inspect}]: #{spec_path} not found, skipping"
+      end
+    end
+  end
+
+  def validate_spec_pattern(value)
+    return nil if value.nil?
+    return value if value.is_a?(String)
+
+    raise Evilution::ConfigError, "spec_pattern must be nil or a String glob, got #{value.class}"
   end
 
   def validate_preload(value)
@@ -266,6 +395,52 @@ class Evilution::Config
     patterns
   end
 
+  def validate_example_targeting_fallback(value)
+    unless value.is_a?(String) || value.is_a?(Symbol)
+      raise Evilution::ConfigError,
+            "example_targeting_fallback must be full_file or unresolved, got #{value.inspect}"
+    end
+
+    sym = value.to_sym
+    unless EXAMPLE_TARGETING_FALLBACKS.include?(sym)
+      raise Evilution::ConfigError,
+            "example_targeting_fallback must be full_file or unresolved, got #{sym.inspect}"
+    end
+
+    sym
+  end
+
+  def validate_example_targeting_cache(value)
+    raise Evilution::ConfigError, "example_targeting_cache must be a Hash, got #{value.class}" unless value.is_a?(Hash)
+
+    normalized = value.each_with_object({}) do |(k, v), acc|
+      unless k.is_a?(String) || k.is_a?(Symbol)
+        raise Evilution::ConfigError,
+              "example_targeting_cache keys must be Strings or Symbols, got #{k.inspect}"
+      end
+      acc[k.to_sym] = v
+    end
+    merged = DEFAULTS[:example_targeting_cache].merge(normalized)
+    validate_positive_int!(merged, :max_files)
+    validate_positive_int!(merged, :max_blocks)
+    merged
+  end
+
+  def validate_positive_int!(cache, key)
+    v = cache[key]
+    return if v.is_a?(Integer) && v >= 1
+
+    raise Evilution::ConfigError,
+          "example_targeting_cache.#{key} must be a positive integer, got #{v.inspect}"
+  end
+
+  def load_env_options
+    opts = {}
+    val = ENV.fetch("EV_DISABLE_EXAMPLE_TARGETING", nil)
+    opts[:example_targeting] = false if val && !val.empty? && val != "0"
+    opts
+  end
+
   def validate_hooks(value)
     return {} if value.nil?
     raise Evilution::ConfigError, "hooks must be a mapping of event names to file paths, got #{value.class}" unless value.is_a?(Hash)

data/lib/evilution/example_filter.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../evilution"
+require_relative "spec_ast_cache"
+
+class Evilution::ExampleFilter
+  VALID_FALLBACKS = %i[full_file unresolved].freeze
+  private_constant :VALID_FALLBACKS
+
+  def initialize(cache:, fallback: :full_file, source_cache: nil)
+    raise ArgumentError, "invalid fallback: #{fallback.inspect}" unless VALID_FALLBACKS.include?(fallback)
+
+    @cache = cache
+    @fallback = fallback
+    @source_cache = source_cache
+  end
+
+  def call(mutation, spec_paths)
+    return fallback_result(spec_paths) if spec_paths.nil? || spec_paths.empty?
+
+    token = extract_token(mutation)
+    return fallback_result(spec_paths) unless token
+
+    locations = scan_specs(token, spec_paths)
+    return fallback_result(spec_paths) if locations.empty?
+
+    locations.sort
+  end
+
+  private
+
+  def fallback_result(spec_paths)
+    case @fallback
+    when :full_file then spec_paths
+    when :unresolved then nil
+    end
+  end
+
+  def extract_token(mutation)
+    result = if @source_cache.nil?
+               Prism.parse(mutation.original_source)
+             else
+               @source_cache.fetch(mutation.original_source)
+             end
+    return nil if result.failure?
+
+    finder = EnclosingNodeFinder.new(mutation.line)
+    finder.visit(result.value)
+    finder.token
+  end
+
+  def scan_specs(token, spec_paths)
+    pattern = /(?<!\w)#{Regexp.escape(token.downcase)}(?!\w)/
+    locations = []
+    spec_paths.each do |path|
+      blocks = @cache.fetch(path)
+      matches = blocks.select { |b| pattern.match?(b.body_text) }
+      innermost = filter_innermost(matches)
+      innermost.each { |b| locations << "#{path}:#{b.line}" }
+    end
+    locations.uniq
+  end
+
+  def filter_innermost(matches)
+    matches.reject do |outer|
+      matches.any? do |inner|
+        next false if inner.equal?(outer)
+
+        contained?(inner, outer)
+      end
+    end
+  end
+
+  def contained?(inner, outer)
+    inner.line >= outer.line && inner.end_line <= outer.end_line &&
+      !(inner.line == outer.line && inner.end_line == outer.end_line)
+  end
+
+  class EnclosingNodeFinder < Prism::Visitor
+    attr_reader :token
+
+    def initialize(target_line)
+      @target_line = target_line
+      @def_stack = []
+      @class_stack = []
+      @token = nil
+      @found = false
+      super()
+    end
+
+    def visit_def_node(node)
+      return if @found
+      return unless target_within?(node)
+
+      @def_stack.push(node.name.to_s)
+      capture_if_match(node)
+      super
+      @def_stack.pop
+    end
+
+    def visit_class_node(node)
+      return if @found
+      return unless target_within?(node)
+
+      @class_stack.push(unqualified_name(node.constant_path))
+      capture_if_match(node)
+      super
+      @class_stack.pop
+    end
+
+    def visit_module_node(node)
+      return if @found
+      return unless target_within?(node)
+
+      @class_stack.push(unqualified_name(node.constant_path))
+      capture_if_match(node)
+      super
+      @class_stack.pop
+    end
+
+    private
+
+    def capture_if_match(node)
+      return if @found
+      return unless target_within?(node)
+
+      @token = @def_stack.last || @class_stack.last
+      @found = true if @def_stack.any?
+    end
+
+    def target_within?(node)
+      loc = node.location
+      @target_line.between?(loc.start_line, loc.end_line)
+    end
+
+    def unqualified_name(constant_path)
+      raw = constant_path.respond_to?(:name) ? constant_path.name.to_s : constant_path.to_s
+      raw.split("::").last
+    end
+  end
+  private_constant :EnclosingNodeFinder
+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
@@ -58,15 +52,10 @@ class Evilution::Integration::Base
     prism_error = validate_mutated_syntax(mutation.mutated_source)
     return prism_error if prism_error
 
-    @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)
+    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
@@ -96,29 +85,14 @@ 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
-  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)
@@ -134,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)
@@ -237,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/crash_detector.rb

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