evilution 0.24.0 → 0.26.0

data/lib/evilution/compare/fingerprint.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../compare"
+
+module Evilution::Compare::Fingerprint
+  module_function
+
+  def extract_from_evilution_diff(diff)
+    minus = []
+    plus = []
+    diff.to_s.each_line do |line|
+      line = line.chomp
+      if line.start_with?("- ")
+        minus << line[2..]
+      elsif line.start_with?("+ ")
+        plus << line[2..]
+      end
+    end
+    { minus: minus, plus: plus }
+  end
+
+  def extract_from_mutant_diff(diff)
+    minus = []
+    plus = []
+    diff.to_s.each_line do |line|
+      line = line.chomp
+      next if line.start_with?("---", "+++", "@@")
+
+      if line.start_with?("-")
+        minus << line[1..]
+      elsif line.start_with?("+")
+        plus << line[1..]
+      end
+    end
+    { minus: minus, plus: plus }
+  end
+
+  # v1 limitation: only " and ' literals are preserved. Regex literals (/.../),
+  # heredocs, %w[], %q{} forms are treated as ordinary code — whitespace runs
+  # inside them collapse. A mutation touching whitespace inside a regex may
+  # false-match across tools.
+  # rubocop:disable Metrics/PerceivedComplexity, Style/MultipleComparison
+  def normalize_line(line)
+    out = +""
+    i = 0
+    in_literal = nil
+    last_was_space = false
+    chars = line.chars
+    while i < chars.length
+      ch = chars[i]
+      if in_literal
+        out << ch
+        if ch == "\\" && i + 1 < chars.length
+          out << chars[i + 1]
+          i += 2
+          next
+        end
+        in_literal = nil if ch == in_literal
+      elsif ch == '"' || ch == "'"
+        in_literal = ch
+        out << ch
+        last_was_space = false
+      elsif ch == " " || ch == "\t"
+        out << " " unless last_was_space || out.empty?
+        last_was_space = true
+      else
+        out << ch
+        last_was_space = false
+      end
+      i += 1
+    end
+    out.rstrip
+  end
+  # rubocop:enable Metrics/PerceivedComplexity, Style/MultipleComparison
+
+  def compute(file_path:, line:, body:)
+    minus = body[:minus].map { |l| normalize_line(l) }
+    plus  = body[:plus].map  { |l| normalize_line(l) }
+    payload = [file_path, line.to_s, minus.join("\n"), plus.join("\n")].join("\x00")
+    Digest::SHA256.hexdigest(payload)
+  end
+end

data/lib/evilution/compare/invalid_input.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "../compare"
+
+class Evilution::Compare::InvalidInput < StandardError
+  attr_reader :index
+
+  def initialize(message, index: nil)
+    super(message)
+    @index = index
+  end
+end

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,6 @@
+# frozen_string_literal: true
+
+module Evilution::Compare
+end
+
+require_relative "compare/invalid_input"

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