evilution 0.24.0 → 0.25.0

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
@@ -29,20 +31,31 @@ class Evilution::Config
     skip_heredoc_literals: false,
     related_specs_heuristic: false,
     fallback_to_full_suite: false,
-    preload: nil
+    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,
-              :fallback_to_full_suite, :preload
+              :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
@@ -103,6 +116,10 @@ class Evilution::Config
     related_specs_heuristic
   end
 
+  def example_targeting?
+    example_targeting
+  end
+
   def fallback_to_full_suite?
     fallback_to_full_suite
   end
@@ -177,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:
@@ -225,6 +259,88 @@ class Evilution::Config
     @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)
@@ -279,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/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

data/lib/evilution/integration/minitest.rb

@@ -4,6 +4,7 @@ require "stringio"
 require_relative "base"
 require_relative "minitest_crash_detector"
 require_relative "../spec_resolver"
+require_relative "../spec_selector"
 
 require_relative "../integration"
 
@@ -35,10 +36,12 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     }
   end
 
-  def initialize(test_files: nil, hooks: nil, fallback_to_full_suite: false)
+  def initialize(test_files: nil, hooks: nil, fallback_to_full_suite: false, spec_selector: nil)
     @test_files = test_files
     @minitest_loaded = false
-    @spec_resolver = Evilution::SpecResolver.new(test_dir: "test", test_suffix: "_test.rb", request_dir: "integration")
+    @spec_selector = spec_selector || Evilution::SpecSelector.new(
+      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
@@ -124,10 +127,12 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     if passed
       { passed: true, test_command: command }
     elsif detector.only_crashes?
+      classes = detector.unique_crash_classes
       {
         passed: false,
         test_crashed: true,
         error: "test crashes: #{detector.crash_summary}",
+        error_class: (classes.first if classes.length == 1),
         test_command: command
       }
     else
@@ -138,13 +143,13 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
   def resolve_test_files(mutation)
     return test_files if test_files
 
-    resolved = @spec_resolver.call(mutation.file_path)
-    unless resolved
+    resolved = Array(@spec_selector.call(mutation.file_path))
+    if resolved.empty?
       warn_unresolved_test(mutation.file_path)
       return @fallback_to_full_suite ? glob_test_files : nil
     end
 
-    [resolved]
+    resolved
   end
 
   def glob_test_files

data/lib/evilution/integration/minitest_crash_detector.rb

@@ -49,7 +49,10 @@ class Evilution::Integration::MinitestCrashDetector
   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
 end

data/lib/evilution/integration/rspec.rb

@@ -4,6 +4,7 @@ require "stringio"
 require_relative "base"
 require_relative "crash_detector"
 require_relative "../spec_resolver"
+require_relative "../spec_selector"
 require_relative "../related_spec_heuristic"
 
 require_relative "../integration"
@@ -26,13 +27,15 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     { runner: baseline_runner }
   end
 
-  def initialize(test_files: nil, hooks: nil, related_specs_heuristic: false, fallback_to_full_suite: false)
+  def initialize(test_files: nil, hooks: nil, related_specs_heuristic: false, fallback_to_full_suite: false,
+                 spec_selector: nil, example_filter: nil)
     @test_files = test_files
     @rspec_loaded = false
-    @spec_resolver = Evilution::SpecResolver.new
+    @spec_selector = spec_selector || Evilution::SpecSelector.new
     @related_spec_heuristic = Evilution::RelatedSpecHeuristic.new
     @related_specs_heuristic_enabled = related_specs_heuristic
     @fallback_to_full_suite = fallback_to_full_suite
+    @example_filter = example_filter
     @crash_detector = nil
     @warned_files = Set.new
     super(hooks: hooks)
@@ -61,13 +64,18 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     files = resolve_test_files(mutation)
     return unresolved_result(mutation) if files.nil?
 
+    targets = apply_example_filter(mutation, files)
+    return unresolved_example_result(mutation) if targets.nil?
+
     out = StringIO.new
     err = StringIO.new
-    args = build_args(files)
+    args = build_args(targets)
     command = "rspec #{args.join(" ")}"
 
     detector = reset_crash_detector
     eg_before = snapshot_example_groups
+    fe_before = snapshot_filtered_examples_keys
+    rep_before = snapshot_reporter_lengths
     status = ::RSpec::Core::Runner.run(args, out, err)
 
     build_rspec_result(status, command, detector)
@@ -75,12 +83,20 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     { passed: false, error: e.message, test_command: command }
   ensure
     release_rspec_state(eg_before)
+    release_filtered_examples(fe_before)
+    release_reporter_state(rep_before)
   end
 
   def build_args(files)
     ["--format", "progress", "--no-color", "--order", "defined", *files]
   end
 
+  def apply_example_filter(mutation, files)
+    return files unless @example_filter
+
+    @example_filter.call(mutation, files)
+  end
+
   def unresolved_result(mutation)
     {
       passed: false,
@@ -90,6 +106,15 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     }
   end
 
+  def unresolved_example_result(mutation)
+    {
+      passed: false,
+      unresolved: true,
+      error: "no matching example found for #{mutation.file_path}",
+      test_command: "rspec (skipped: no matching example for #{mutation.file_path})"
+    }
+  end
+
   def reset_state
     if ::RSpec.respond_to?(:clear_examples)
       ::RSpec.clear_examples
@@ -138,6 +163,54 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     world.instance_variable_set(:@sources_by_path, {}) if world.instance_variable_defined?(:@sources_by_path)
   end
 
+  def snapshot_filtered_examples_keys
+    fe = rspec_world_ivar(:@filtered_examples)
+    fe ? Set.new(fe.keys.map(&:object_id)) : nil
+  end
+
+  def snapshot_reporter_lengths
+    reporter = rspec_config_ivar(:@reporter)
+    return nil unless reporter
+
+    %i[@examples @failed_examples @pending_examples].each_with_object({}) do |ivar, acc|
+      next unless reporter.instance_variable_defined?(ivar)
+
+      arr = reporter.instance_variable_get(ivar)
+      acc[ivar] = arr.length if arr.is_a?(Array)
+    end
+  end
+
+  def release_filtered_examples(snapshot_keys)
+    fe = rspec_world_ivar(:@filtered_examples)
+    return unless fe && snapshot_keys
+
+    fe.each_key.to_a.each do |k|
+      fe.delete(k) unless snapshot_keys.include?(k.object_id)
+    end
+  end
+
+  def release_reporter_state(lengths)
+    return unless lengths
+
+    reporter = rspec_config_ivar(:@reporter)
+    return unless reporter
+
+    lengths.each do |ivar, length|
+      arr = reporter.instance_variable_get(ivar)
+      arr.slice!(length..) if arr.is_a?(Array) && arr.length > length
+    end
+  end
+
+  def rspec_world_ivar(ivar)
+    world = ::RSpec.world
+    world.instance_variable_defined?(ivar) ? world.instance_variable_get(ivar) : nil
+  end
+
+  def rspec_config_ivar(ivar)
+    config = ::RSpec.configuration
+    config.instance_variable_defined?(ivar) ? config.instance_variable_get(ivar) : nil
+  end
+
   def reset_crash_detector
     if @crash_detector
       @crash_detector.reset
@@ -152,10 +225,12 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     if status.zero?
       { passed: true, test_command: command }
     elsif detector.only_crashes?
+      classes = detector.unique_crash_classes
       {
         passed: false,
         test_crashed: true,
         error: "test crashes: #{detector.crash_summary}",
+        error_class: (classes.first if classes.length == 1),
         test_command: command
       }
     else
@@ -166,16 +241,16 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
   def resolve_test_files(mutation)
     return test_files if test_files
 
-    resolved = @spec_resolver.call(mutation.file_path)
-    unless resolved
+    resolved = Array(@spec_selector.call(mutation.file_path))
+    if resolved.empty?
       warn_unresolved_spec(mutation.file_path)
       return @fallback_to_full_suite ? ["spec"] : nil
     end
 
-    return [resolved] unless @related_specs_heuristic_enabled
+    return resolved unless @related_specs_heuristic_enabled
 
     related = @related_spec_heuristic.call(mutation)
-    ([resolved] + related).uniq
+    (resolved + related).uniq
   end
 
   def warn_unresolved_spec(file_path)

data/lib/evilution/isolation/fork.rb

@@ -15,10 +15,18 @@ class Evilution::Isolation::Fork
   end
 
   def call(mutation:, test_command:, timeout:)
+    pid = nil
     sandbox_dir = Dir.mktmpdir("evilution-run")
     start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     parent_rss = Evilution::Memory.rss_kb
     read_io, write_io = IO.pipe
+    # Marshal result payload is ASCII-8BIT; pipes default to text mode and may
+    # transcode according to their external/internal encodings (influenced by
+    # Encoding.default_external and/or Encoding.default_internal — Rails sets
+    # the latter to UTF-8), failing on bytes with no mapping. Force binmode on
+    # both ends.
+    read_io.binmode
+    write_io.binmode
 
     pid = ::Process.fork do
       ENV["TMPDIR"] = sandbox_dir
@@ -39,6 +47,7 @@ class Evilution::Isolation::Fork
   ensure
     read_io&.close
     write_io&.close
+    ensure_reaped(pid)
     restore_original_source(mutation)
     FileUtils.rm_rf(sandbox_dir) if sandbox_dir
   end
@@ -82,6 +91,22 @@ class Evilution::Isolation::Fork
     end
   end
 
+  # Defensive reap: if normal control flow raised before wait_for_result
+  # reaped the child (e.g. Marshal.load on corrupt payload), the child becomes
+  # a zombie. Reuse terminate_child for the bounded TERM + GRACE_PERIOD + KILL
+  # ladder so this never hangs the ensure path; swallow SystemCallError so
+  # cleanup can't mask the primary failure.
+  def ensure_reaped(pid)
+    return unless pid
+
+    reaped = ::Process.waitpid(pid, ::Process::WNOHANG)
+    return if reaped
+
+    terminate_child(pid)
+  rescue SystemCallError
+    nil
+  end
+
   def terminate_child(pid)
     ::Process.kill("TERM", pid) rescue nil # rubocop:disable Style/RescueModifier
     _, status = ::Process.waitpid2(pid, ::Process::WNOHANG)