evilution 0.28.0 → 0.30.0

data/lib/evilution/runner/mutation_executor/strategy/parallel.rb

@@ -18,8 +18,17 @@ class Evilution::Runner::MutationExecutor::Strategy::Parallel
     @notifier.start(mutations.length)
     pool = @pool_factory.call
     state = { results: [], truncated: false, completed: 0 }
-    all_worker_stats = []
+    all_worker_stats = run_batches(mutations, pool, baseline_result, integration, state)
 
+    log_worker_diagnostics(all_worker_stats)
+    @notifier.finish
+    build_result(state)
+  end
+
+  private
+
+  def run_batches(mutations, pool, baseline_result, integration, state)
+    all_worker_stats = []
     mutations.each_slice(@config.jobs) do |batch|
       break if state[:truncated]
 
@@ -27,24 +36,37 @@ class Evilution::Runner::MutationExecutor::Strategy::Parallel
       all_worker_stats.concat(pool.worker_stats)
       process_batch(batch_results, baseline_result, state)
     end
+    all_worker_stats
+  end
 
-    @diagnostics.log_worker_stats(@diagnostics.aggregate_worker_stats(all_worker_stats)) if @diagnostics
-    @notifier.finish
-    [state[:results], state[:truncated]]
+  def log_worker_diagnostics(all_worker_stats)
+    return unless @diagnostics
+
+    @diagnostics.log_worker_stats(@diagnostics.aggregate_worker_stats(all_worker_stats))
   end
 
-  private
+  def build_result(state)
+    Evilution::Runner::MutationExecutor::ExecutionResult.new(results: state[:results], truncated: state[:truncated])
+  end
 
   def run_batch(batch, pool, integration)
-    uncached_indices, cached_results = @cache.partition(batch, packer: @packer)
-    worker_results = run_uncached(batch, uncached_indices, pool, integration)
-    compact_results = merge(batch, uncached_indices, cached_results, worker_results)
-    batch_results = batch.zip(compact_results).map { |m, h| @packer.rebuild(m, h) }
-    uncached_indices.each { |i| @cache.store(batch_results[i].mutation, batch_results[i]) }
+    partition = @cache.partition(batch, packer: @packer)
+    worker_results = run_uncached(batch, partition.uncached_indices, pool, integration)
+    compact_results = merge(batch, partition.uncached_indices, partition.cached_results, worker_results)
+    batch_results = rebuild_results(batch, compact_results)
+    cache_results(batch_results, partition.uncached_indices)
     batch.each(&:strip_sources!)
     batch_results
   end
 
+  def rebuild_results(batch, compact_results)
+    batch.zip(compact_results).map { |m, h| @packer.rebuild(m, h) }
+  end
+
+  def cache_results(batch_results, uncached_indices)
+    uncached_indices.each { |i| @cache.store(batch_results[i].mutation, batch_results[i]) }
+  end
+
   def run_uncached(batch, uncached_indices, pool, integration)
     return [] if uncached_indices.empty?
 

data/lib/evilution/runner/mutation_executor/strategy/sequential.rb

@@ -27,6 +27,6 @@ class Evilution::Runner::MutationExecutor::Strategy::Sequential
     end
 
     @notifier.finish
-    [results, truncated]
+    Evilution::Runner::MutationExecutor::ExecutionResult.new(results: results, truncated: truncated)
   end
 end

data/lib/evilution/runner/mutation_executor.rb

@@ -3,6 +3,8 @@
 require_relative "../runner"
 
 class Evilution::Runner::MutationExecutor
+  ExecutionResult = Data.define(:results, :truncated)
+
   autoload :ResultCache, File.expand_path("mutation_executor/result_cache", __dir__)
   autoload :ResultPacker, File.expand_path("mutation_executor/result_packer", __dir__)
   autoload :ResultNotifier, File.expand_path("mutation_executor/result_notifier", __dir__)

data/lib/evilution/runner/mutation_planner.rb

@@ -9,6 +9,12 @@ require_relative "../equivalent/detector"
 class Evilution::Runner::MutationPlanner
   Plan = Struct.new(:enabled, :equivalent, :skipped_count, :disabled_mutations, keyword_init: true)
 
+  GenerationResult = Data.define(:mutations, :skipped)
+  DisabledFilterResult = Data.define(:enabled, :disabled)
+  SigFilterResult = Data.define(:enabled, :skipped)
+  EquivalentFilterResult = Data.define(:equivalent, :enabled)
+  private_constant :GenerationResult, :DisabledFilterResult, :SigFilterResult, :EquivalentFilterResult
+
   def initialize(config, registry:, disable_detector: Evilution::DisableComment.new,
                  sig_detector: Evilution::AST::SorbetSigDetector.new)
     @config = config
@@ -20,25 +26,55 @@ class Evilution::Runner::MutationPlanner
   end
 
   def call(subjects)
-    mutations, generation_skipped = generate(subjects)
-    mutations, disabled = filter_disabled(mutations)
-    disabled.each(&:strip_sources!) if config.show_disabled?
-    disabled_mutations = config.show_disabled? ? disabled : []
+    generation = generate(subjects)
+    deduped = deduplicate(generation.mutations)
+    disabled_filter = filter_disabled(deduped)
+    disabled_mutations = compute_disabled_mutations(disabled_filter)
+    sig_filter = filter_sig_blocks(disabled_filter.enabled)
+    equivalent_filter = filter_equivalent(sig_filter.enabled)
+
+    build_plan(equivalent_filter, disabled_mutations, total_skipped(generation, disabled_filter, sig_filter))
+  end
+
+  private
+
+  attr_reader :config, :registry
+
+  def compute_disabled_mutations(disabled_filter)
+    return [] unless config.show_disabled?
+
+    disabled_filter.disabled.each(&:strip_sources!)
+    disabled_filter.disabled
+  end
 
-    mutations, sig_skipped = filter_sig_blocks(mutations)
-    equivalent, enabled = filter_equivalent(mutations)
+  def total_skipped(generation, disabled_filter, sig_filter)
+    generation.skipped + disabled_filter.disabled.length + sig_filter.skipped
+  end
 
+  def build_plan(equivalent_filter, disabled_mutations, skipped_count)
     Plan.new(
-      enabled: enabled,
-      equivalent: equivalent,
-      skipped_count: generation_skipped + disabled.length + sig_skipped,
+      enabled: equivalent_filter.enabled,
+      equivalent: equivalent_filter.equivalent,
+      skipped_count: skipped_count,
       disabled_mutations: disabled_mutations
     )
   end
 
-  private
-
-  attr_reader :config, :registry
+  # Two operators can independently emit the same byte-level mutation
+  # (statement_deletion deleting a trailing literal AND last_expression_removal
+  # producing the same result, for example). Running both is wasted compute
+  # and inflates the denominator. Key is (file_path, mutated_source) — two
+  # mutations producing the same resulting source are operationally identical
+  # regardless of operator name. Order-stable: first occurrence wins, so
+  # operator-name ordering in the registry determines which name surfaces.
+  def deduplicate(mutations)
+    seen = {}
+    mutations.each do |mutation|
+      key = [mutation.file_path, mutation.mutated_source]
+      seen[key] ||= mutation
+    end
+    seen.values
+  end
 
   def generate(subjects)
     filter = build_ignore_filter
@@ -47,7 +83,7 @@ class Evilution::Runner::MutationPlanner
       registry.mutations_for(subject, filter: filter, operator_options: operator_options)
     end
     skipped = filter ? filter.skipped_count : 0
-    [mutations, skipped]
+    GenerationResult.new(mutations: mutations, skipped: skipped)
   end
 
   def build_operator_options
@@ -73,7 +109,7 @@ class Evilution::Runner::MutationPlanner
       end
     end
 
-    [enabled, disabled]
+    DisabledFilterResult.new(enabled: enabled, disabled: disabled)
   end
 
   def mutation_disabled?(mutation)
@@ -102,7 +138,7 @@ class Evilution::Runner::MutationPlanner
       end
     end
 
-    [enabled, skipped]
+    SigFilterResult.new(enabled: enabled, skipped: skipped)
   end
 
   def mutation_in_sig_block?(mutation)
@@ -120,6 +156,7 @@ class Evilution::Runner::MutationPlanner
   end
 
   def filter_equivalent(mutations)
-    Evilution::Equivalent::Detector.new.call(mutations)
+    equivalent, enabled = Evilution::Equivalent::Detector.new.call(mutations)
+    EquivalentFilterResult.new(equivalent: equivalent, enabled: enabled)
   end
 end

data/lib/evilution/runner/subject_pipeline.rb

@@ -104,17 +104,27 @@ class Evilution::Runner::SubjectPipeline
 
   def target_matcher
     target = config.target
-    if target.end_with?("*")
-      prefix = target.chomp("*")
-      ->(s) { s.name.split(/[#.]/).first.start_with?(prefix) }
-    elsif target.end_with?("#", ".")
-      prefix = target
-      ->(s) { s.name.start_with?(prefix) }
-    elsif target.include?("#") || target.include?(".")
-      ->(s) { s.name == target }
-    else
-      ->(s) { s.name.start_with?("#{target}#") || s.name.start_with?("#{target}.") }
-    end
+    return wildcard_matcher(target.chomp("*")) if target.end_with?("*")
+    return prefix_matcher(target) if target.end_with?("#", ".")
+    return exact_matcher(target) if target.include?("#") || target.include?(".")
+
+    class_matcher(target)
+  end
+
+  def wildcard_matcher(prefix)
+    ->(s) { s.name.split(/[#.]/).first.start_with?(prefix) }
+  end
+
+  def prefix_matcher(prefix)
+    ->(s) { s.name.start_with?(prefix) }
+  end
+
+  def exact_matcher(target)
+    ->(s) { s.name == target }
+  end
+
+  def class_matcher(target)
+    ->(s) { s.name.start_with?("#{target}#") || s.name.start_with?("#{target}.") }
   end
 
   def filter_by_line_ranges(subjects)

data/lib/evilution/runner.rb

@@ -32,13 +32,13 @@ class Evilution::Runner
     plan = mutation_planner.call(subjects)
     release_subject_nodes(subjects)
     clear_operator_caches
-    results, truncated = run_mutations(plan.enabled, baseline_result)
-    results += equivalent_results(plan.equivalent)
+    execution = run_mutations(plan.enabled, baseline_result)
+    results = execution.results + equivalent_results(plan.equivalent)
     log_memory("after run_mutations", "#{results.length} results")
 
     duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-    summary = Evilution::Result::Summary.new(results: results, duration: duration, truncated: truncated,
+    summary = Evilution::Result::Summary.new(results: results, duration: duration, truncated: execution.truncated,
                                              skipped: plan.skipped_count,
                                              disabled_mutations: plan.disabled_mutations)
     output_report(summary)

data/lib/evilution/session/diff.rb

@@ -38,20 +38,29 @@ class Evilution::Session::Diff
   def call(base_data, head_data)
     base_survivors = base_data["survived"] || []
     head_survivors = head_data["survived"] || []
-
-    base_keys = base_survivors.to_set { |m| mutation_key(m) }
-    head_keys = head_survivors.to_set { |m| mutation_key(m) }
+    fixed, new_survivors, persistent = partition_survivors(base_survivors, head_survivors)
 
     Result.new(
       summary: build_summary_diff(base_data, head_data),
-      fixed: base_survivors.reject { |m| head_keys.include?(mutation_key(m)) },
-      new_survivors: head_survivors.reject { |m| base_keys.include?(mutation_key(m)) },
-      persistent: head_survivors.select { |m| base_keys.include?(mutation_key(m)) }
+      fixed: fixed,
+      new_survivors: new_survivors,
+      persistent: persistent
     )
   end
 
   private
 
+  def partition_survivors(base_survivors, head_survivors)
+    base_keys = base_survivors.to_set { |m| mutation_key(m) }
+    head_keys = head_survivors.to_set { |m| mutation_key(m) }
+
+    [
+      base_survivors.reject { |m| head_keys.include?(mutation_key(m)) },
+      head_survivors.reject { |m| base_keys.include?(mutation_key(m)) },
+      head_survivors.select { |m| base_keys.include?(mutation_key(m)) }
+    ]
+  end
+
   def build_summary_diff(base_data, head_data)
     base = extract_summary_values(base_data)
     head = extract_summary_values(head_data)

data/lib/evilution/session/schema.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+
+module Evilution::Session::Schema
+  CURRENT_VERSION = 1
+
+  module_function
+
+  # Validates the schema_version of a parsed session JSON Hash.
+  #
+  # Sessions written before schema_version was introduced (key absent
+  # entirely) are treated as CURRENT_VERSION — the JSON shape that defined
+  # version 1. A key that is explicitly present but null/non-positive/non-
+  # integer is rejected as invalid; "missing" and "corrupted" must not
+  # collapse into the same lenient bucket. A schema_version newer than this
+  # gem supports raises Evilution::Error with an explicit "upgrade the gem"
+  # message so future writers cannot be silently misread.
+  def validate!(data, source: nil)
+    return unless data.key?("schema_version") || data.key?(:schema_version)
+
+    raw = data.fetch("schema_version") { data[:schema_version] }
+    raise_invalid!(raw, source) unless raw.is_a?(Integer) && raw.positive?
+    return if raw <= CURRENT_VERSION
+
+    raise_future!(raw, source)
+  end
+
+  def raise_invalid!(value, source)
+    raise Evilution::Error,
+          "invalid schema_version #{value.inspect}#{location_clause(source)}: must be a positive Integer"
+  end
+
+  def raise_future!(value, source)
+    raise Evilution::Error,
+          "session file#{location_clause(source)} has schema_version #{value}, " \
+          "newer than this evilution gem supports (current: #{CURRENT_VERSION}). " \
+          "Upgrade the evilution gem."
+  end
+
+  def location_clause(source)
+    source ? " at #{source}" : ""
+  end
+end

data/lib/evilution/session/store.rb

@@ -6,6 +6,7 @@ require "time"
 require "fileutils"
 
 require_relative "../session"
+require_relative "schema"
 
 class Evilution::Session::Store
   DEFAULT_DIR = ".evilution/results"
@@ -38,7 +39,9 @@ class Evilution::Session::Store
   def load(path)
     raise Evilution::Error, "session file not found: #{path}" unless File.exist?(path)
 
-    JSON.parse(File.read(path))
+    data = JSON.parse(File.read(path))
+    Evilution::Session::Schema.validate!(data, source: path) if data.is_a?(Hash)
+    data
   end
 
   def gc(older_than:)
@@ -60,6 +63,7 @@ class Evilution::Session::Store
 
   def build_session_data(summary, now)
     {
+      schema_version: Evilution::Session::Schema::CURRENT_VERSION,
       version: Evilution::VERSION,
       timestamp: now.iso8601,
       git: git_context,

data/lib/evilution/spec_ast_cache.rb

@@ -62,18 +62,27 @@ class Evilution::SpecAstCache
     raise Evilution::ParseError.new("file not found: #{path}", file: path) unless File.exist?(path)
 
     source = read_source(path)
+    result = parse_source(path, source)
+    collect_blocks(source, result, extract_comment_ranges(result))
+  end
+
+  def parse_source(path, source)
     result = Prism.parse(source)
+    return result unless result.failure?
 
-    if result.failure?
-      raise Evilution::ParseError.new(
-        "failed to parse #{path}: #{result.errors.map(&:message).join(", ")}",
-        file: path
-      )
-    end
+    raise Evilution::ParseError.new(
+      "failed to parse #{path}: #{result.errors.map(&:message).join(", ")}",
+      file: path
+    )
+  end
 
-    comment_ranges = result.comments
-                           .map { |c| c.location.start_offset...c.location.end_offset }
-                           .sort_by(&:begin)
+  def extract_comment_ranges(result)
+    result.comments
+          .map { |c| c.location.start_offset...c.location.end_offset }
+          .sort_by(&:begin)
+  end
+
+  def collect_blocks(source, result, comment_ranges)
     collector = BlockCollector.new(source, comment_ranges)
     collector.visit(result.value)
     collector.blocks
@@ -133,16 +142,21 @@ class Evilution::SpecAstCache
     def strip_comments(slice, base_offset)
       return slice if @comment_ranges.empty?
 
-      ranges = comment_ranges_within(base_offset, base_offset + slice.bytesize)
+      end_offset = base_offset + slice.bytesize
+      ranges = comment_ranges_within(base_offset, end_offset)
       return slice if ranges.empty?
 
+      splice_excluding_ranges(base_offset, end_offset, ranges)
+    end
+
+    def splice_excluding_ranges(start_off, end_off, ranges)
       result = +""
-      cursor = base_offset
+      cursor = start_off
       ranges.each do |range|
         result << @source.byteslice(cursor, range.begin - cursor)
         cursor = range.end
       end
-      result << @source.byteslice(cursor, base_offset + slice.bytesize - cursor)
+      result << @source.byteslice(cursor, end_off - cursor)
       result
     end
 

data/lib/evilution/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Evilution
-  VERSION = "0.28.0"
+  VERSION = "0.30.0"
 end

data/lib/evilution.rb

@@ -94,6 +94,8 @@ require_relative "evilution/mutator/operator/equality_to_identity"
 require_relative "evilution/mutator/operator/lambda_body"
 require_relative "evilution/mutator/operator/begin_unwrap"
 require_relative "evilution/mutator/operator/block_param_removal"
+require_relative "evilution/mutator/operator/last_expression_removal"
+require_relative "evilution/mutator/operator/argument_method_call_replacement"
 require_relative "evilution/mutator/registry"
 require_relative "evilution/equivalent"
 require_relative "evilution/equivalent/heuristic"

data/schema/evilution.config.schema.json

@@ -0,0 +1,205 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/marinazzio/evilution/blob/master/schema/evilution.config.schema.json",
+  "title": "Evilution Configuration",
+  "description": "Schema for .evilution.yml / config/evilution.yml. Declaring `schema_version` opts the file into strict validation at load time.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "enum": [1],
+      "description": "Config schema version. Currently must be 1. Declaring it enables strict validation: unknown keys are rejected and a future schema_version is refused."
+    },
+    "timeout": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 30,
+      "description": "Per-mutation timeout in seconds."
+    },
+    "format": {
+      "type": "string",
+      "enum": ["text", "json", "html"],
+      "default": "text",
+      "description": "Output format."
+    },
+    "target": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Filter expression: method (Foo#bar), class (Foo), namespace wildcard (Foo*), method-type selector (Foo# / Foo.), descendants (descendants:Foo), or source glob (source:**/*.rb)."
+    },
+    "min_score": {
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 1.0,
+      "default": 0.0,
+      "description": "Minimum mutation score (0.0–1.0) for exit code 0."
+    },
+    "integration": {
+      "type": "string",
+      "enum": ["rspec", "minitest"],
+      "default": "rspec",
+      "description": "Test framework integration."
+    },
+    "verbose": {
+      "type": "boolean",
+      "default": false,
+      "description": "Verbose output (RSS/GC stats per phase, error details for errored mutations)."
+    },
+    "quiet": {
+      "type": "boolean",
+      "default": false,
+      "description": "Suppress output."
+    },
+    "jobs": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1,
+      "description": "Number of parallel workers."
+    },
+    "fail_fast": {
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "default": null,
+      "description": "Stop after N surviving mutants. null or omitted = disabled."
+    },
+    "baseline": {
+      "type": "boolean",
+      "default": true,
+      "description": "Run baseline test suite first to detect pre-existing failures and mark those mutations :neutral."
+    },
+    "isolation": {
+      "type": "string",
+      "enum": ["auto", "fork", "in_process"],
+      "default": "auto",
+      "description": "Isolation strategy. auto selects fork for Rails projects."
+    },
+    "incremental": {
+      "type": "boolean",
+      "default": false,
+      "description": "Cache killed/timeout results across runs and skip them when source is unchanged."
+    },
+    "suggest_tests": {
+      "type": "boolean",
+      "default": false,
+      "description": "Generate concrete test code in survivor suggestions (RSpec or Minitest, matching integration)."
+    },
+    "progress": {
+      "type": "boolean",
+      "default": true,
+      "description": "TTY progress bar."
+    },
+    "save_session": {
+      "type": "boolean",
+      "default": false,
+      "description": "Save session JSON under .evilution/results/."
+    },
+    "line_ranges": {
+      "type": "object",
+      "default": {},
+      "description": "Per-file line-range constraints. Typically set via CLI; rare in YAML.",
+      "additionalProperties": true
+    },
+    "spec_files": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Explicit spec files to run. Bypasses auto-detection when non-empty."
+    },
+    "ignore_patterns": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "AST patterns to skip during mutation generation. See docs/ast_pattern_syntax.md."
+    },
+    "show_disabled": {
+      "type": "boolean",
+      "default": false,
+      "description": "Report mutations skipped by `# evilution:disable` comments."
+    },
+    "baseline_session": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Saved session file path for HTML report comparison."
+    },
+    "skip_heredoc_literals": {
+      "type": "boolean",
+      "default": false,
+      "description": "Skip all string literal mutations inside heredocs (recommended for Rails: heredoc SQL/templates rarely have coverage)."
+    },
+    "related_specs_heuristic": {
+      "type": "boolean",
+      "default": false,
+      "description": "When a mutation removes an `includes(...)` call, also run matching specs from spec/{requests,integration,features,system}."
+    },
+    "fallback_to_full_suite": {
+      "type": "boolean",
+      "default": false,
+      "description": "When no matching spec resolves, run the entire suite instead of marking the mutation :unresolved."
+    },
+    "preload": {
+      "type": ["string", "boolean", "null"],
+      "default": null,
+      "description": "Path to preload before forking workers. false to disable. null to auto-detect spec/rails_helper.rb -> spec/spec_helper.rb -> test/test_helper.rb for Rails projects."
+    },
+    "spec_mappings": {
+      "type": "object",
+      "default": {},
+      "description": "Custom mapping from source file to spec file(s). Keys are source paths; values are spec path strings or arrays of spec paths.",
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "string" },
+          { "type": "array", "items": { "type": "string" } }
+        ]
+      }
+    },
+    "spec_pattern": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Glob restricting resolved spec candidates to files matching this pattern."
+    },
+    "example_targeting": {
+      "type": "boolean",
+      "default": true,
+      "description": "Per-mutation example-level targeting via body-token scan."
+    },
+    "example_targeting_fallback": {
+      "type": "string",
+      "enum": ["full_file", "unresolved"],
+      "default": "full_file",
+      "description": "Behavior when targeting finds no matching example."
+    },
+    "example_targeting_cache": {
+      "type": "object",
+      "default": { "max_files": 50, "max_blocks": 10000 },
+      "additionalProperties": false,
+      "description": "LRU cache bounds for the spec AST parser that powers example targeting.",
+      "properties": {
+        "max_files": { "type": "integer", "minimum": 1 },
+        "max_blocks": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "quiet_children": {
+      "type": "boolean",
+      "default": false,
+      "description": "Redirect each worker's stdout/stderr to per-pid files under quiet_children_dir."
+    },
+    "quiet_children_dir": {
+      "type": "string",
+      "default": "tmp/evilution_children",
+      "description": "Directory for --quiet-children per-pid log files."
+    },
+    "profile": {
+      "type": "string",
+      "enum": ["default", "strict"],
+      "default": "default",
+      "description": "Operator profile. strict adds aggressive truthiness mutators on top of default."
+    },
+    "hooks": {
+      "type": "object",
+      "default": {},
+      "additionalProperties": { "type": "string" },
+      "description": "Lifecycle hooks: keys are event names (e.g. worker_process_start, mutation_insert_pre); values are paths to Ruby files returning a Proc."
+    }
+  }
+}