evilution 0.29.0 → 0.30.0

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."
+    }
+  }
+}

data/script/build_runtime_snapshot

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Builds tmp/evilution-runtime/ — a renamed copy of lib/ + exe/ where the
+# Evilution module is rebranded to EvilutionRuntime. Used by bin/evilution-self
+# so the mutation harness stays out of the namespace that subject `eval` clobbers.
+# Throwaway dogfood infrastructure (EV-yyd8). No tests.
+
+require "fileutils"
+
+ROOT       = File.expand_path("..", __dir__)
+SNAPSHOT   = File.join(ROOT, "tmp", "evilution-runtime")
+SUBJECT_LIB = File.join(ROOT, "lib")
+SUBJECT_EXE = File.join(ROOT, "exe")
+
+def main
+  prepare_destination
+  copy_sources
+  rename_entrypoints
+  rewrite_sources
+  write_snapshot_sha
+  print_summary
+end
+
+def prepare_destination
+  FileUtils.rm_rf(SNAPSHOT)
+  FileUtils.mkdir_p(SNAPSHOT)
+end
+
+def copy_sources
+  FileUtils.cp_r(SUBJECT_LIB, SNAPSHOT)
+  FileUtils.cp_r(SUBJECT_EXE, SNAPSHOT)
+end
+
+def rename_entrypoints
+  File.rename(
+    File.join(SNAPSHOT, "lib", "evilution.rb"),
+    File.join(SNAPSHOT, "lib", "evilution_runtime.rb")
+  )
+  File.rename(
+    File.join(SNAPSHOT, "lib", "evilution"),
+    File.join(SNAPSHOT, "lib", "evilution_runtime")
+  )
+  File.rename(
+    File.join(SNAPSHOT, "exe", "evilution"),
+    File.join(SNAPSHOT, "exe", "evilution_runtime")
+  )
+  # exe/evil alias not needed in snapshot
+  evil_alias = File.join(SNAPSHOT, "exe", "evil")
+  FileUtils.rm_f(evil_alias)
+end
+
+def rewrite_sources
+  files = Dir.glob(File.join(SNAPSHOT, "**", "*.rb")) +
+          [File.join(SNAPSHOT, "exe", "evilution_runtime")]
+  files.uniq!
+  rewritten = 0
+  files.each do |path|
+    next unless File.file?(path)
+
+    original = File.read(path)
+    updated  = rewrite(original)
+    next if updated == original
+
+    File.write(path, updated)
+    rewritten += 1
+  end
+  @rewritten_count = rewritten
+end
+
+def rewrite(source)
+  source
+    .gsub(/\bEvilution\b/, "EvilutionRuntime")
+    .gsub(%r{(require\s+)(["'])evilution(["'/])}, '\1\2evilution_runtime\3')
+    .gsub(%r{(require_relative\s+)(["'])((?:\.\./)*)evilution(["'/])}, '\1\2\3evilution_runtime\4')
+end
+
+def write_snapshot_sha
+  sha = `git -C #{ROOT} rev-parse HEAD`.strip
+  File.write(File.join(SNAPSHOT, ".snapshot_sha"), "#{sha}\n")
+end
+
+def print_summary
+  puts "snapshot built at #{SNAPSHOT}"
+  puts "files rewritten: #{@rewritten_count}"
+end
+
+main

data/script/run_self_baseline

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Throwaway driver (EV-yyd8): runs bin/evilution-self against every lib/evilution
+# subdir to re-baseline self-mutation coverage. Per-dir logs go to
+# tmp/baseline_logs/<dir>.self.log. Aggregate summary printed to stdout.
+
+require "English"
+require "fileutils"
+require "shellwords"
+
+ROOT     = File.expand_path("..", __dir__)
+LOG_DIR  = File.join(ROOT, "tmp", "baseline_logs")
+WRAPPER  = File.join(ROOT, "bin", "evilution-self")
+
+# Originally three Process.fork-using files (isolation/fork.rb,
+# parallel/work_queue/worker.rb, baseline.rb) were skipped because subject
+# grandchildren inherited the runtime marshal pipe write-end and hung the
+# parent. EV-9qh1 fixed the protocol (length-prefix + polling waitpid), so the
+# skip list is now empty.
+SKIP_FILES = [].freeze
+
+FileUtils.mkdir_p(LOG_DIR)
+
+dirs = Dir.children(File.join(ROOT, "lib", "evilution"))
+          .select { |entry| File.directory?(File.join(ROOT, "lib", "evilution", entry)) }
+          .sort
+
+results = []
+dirs.each do |dir|
+  files = Dir.glob(File.join(ROOT, "lib", "evilution", dir, "**", "*.rb"))
+  files.reject! { |f| SKIP_FILES.include?(f) }
+
+  if files.empty?
+    puts "==> #{dir} (skipped — only fork-using files)"
+    results << { dir: dir, exitstatus: nil, log: nil, skipped: true }
+    next
+  end
+
+  log = File.join(LOG_DIR, "#{dir}.self.log")
+  cmd = [WRAPPER, "--strict", "--jobs=4", "--timeout=15", "--quiet-children", *files]
+  puts "==> #{dir} (#{files.length} files)"
+  pid = spawn(*cmd, out: log, err: %i[child out])
+  Process.wait(pid)
+  status = $CHILD_STATUS
+  results << { dir: dir, exitstatus: status.exitstatus, log: log, skipped: false }
+  puts "    exit=#{status.exitstatus}  log=#{log}"
+end
+
+# Toplevel files (lib/evilution/*.rb directly under lib/evilution/ — those that
+# aren't in a subdir). EV-j2kz tagged this set as 'toplevel'.
+toplevel_files = Dir.glob(File.join(ROOT, "lib", "evilution", "*.rb"))
+toplevel_files.reject! { |f| SKIP_FILES.include?(f) }
+unless toplevel_files.empty?
+  log = File.join(LOG_DIR, "toplevel.self.log")
+  cmd = [WRAPPER, "--strict", "--jobs=4", "--timeout=15", "--quiet-children", *toplevel_files]
+  puts "==> toplevel (#{toplevel_files.length} files)"
+  pid = spawn(*cmd, out: log, err: %i[child out])
+  Process.wait(pid)
+  status = $CHILD_STATUS
+  results << { dir: "toplevel", exitstatus: status.exitstatus, log: log, skipped: false }
+  puts "    exit=#{status.exitstatus}  log=#{log}"
+end
+
+puts
+puts "=== summary ==="
+results.each do |r|
+  if r[:skipped]
+    puts format("%<dir>-15s SKIPPED", dir: r[:dir])
+    next
+  end
+  measurable = `grep -E '^Mutations: ' #{Shellwords.escape(r[:log])} 2>/dev/null | tail -1`.strip
+  measurable = "NO_SUMMARY" if measurable.empty?
+  puts format("%<dir>-15s exit=%<exit>s  %<measurable>s",
+              dir: r[:dir], exit: r[:exitstatus], measurable: measurable)
+end
+
+puts
+puts "skipped files (fork-bug workaround): #{SKIP_FILES.map { |p| p.sub("#{ROOT}/", "") }.join(", ")}"

data/script/run_self_validation

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# EV-yyd8 fast validation: pick ONE small representative file per originally-
+# crashing dir from EV-j2kz baseline, run bin/evilution-self against it, log
+# results. Demonstrates the dual-runtime harness lifts the parent-crash issue
+# for each previously-broken dir without requiring a multi-hour full re-run.
+
+require "English"
+require "fileutils"
+require "shellwords"
+
+ROOT    = File.expand_path("..", __dir__)
+LOG_DIR = File.join(ROOT, "tmp", "baseline_logs")
+WRAPPER = File.join(ROOT, "bin", "evilution-self")
+
+# One representative file per originally-crashing dir from EV-j2kz baseline.
+# isolation/in_process.rb is the same file used in the spec verification step.
+TARGETS = {
+  "isolation" => "lib/evilution/isolation/in_process.rb",
+  "result" => "lib/evilution/result/error_info.rb",
+  "compare" => "lib/evilution/compare/invalid_input.rb",
+  "parallel" => "lib/evilution/parallel/work_queue/collection_state.rb",
+  "ast" => "lib/evilution/ast/source_surgeon.rb",
+  "integration" => "lib/evilution/integration/loading.rb",
+  "runner" => "lib/evilution/runner/mutation_executor/neutralizer.rb",
+  "cli" => "lib/evilution/cli/result.rb",
+  "mutator" => "lib/evilution/mutator/operator.rb",
+  "toplevel" => "lib/evilution/memory.rb"
+}.freeze
+
+FileUtils.mkdir_p(LOG_DIR)
+
+results = []
+TARGETS.each do |dir, file|
+  full = File.join(ROOT, file)
+  log  = File.join(LOG_DIR, "#{dir}.validation.log")
+  cmd  = [WRAPPER, "--strict", "--jobs=1", "--timeout=15", "--quiet-children", full]
+  puts "==> #{dir}: #{file}"
+  pid = spawn(*cmd, out: log, err: %i[child out])
+  Process.wait(pid)
+  status = $CHILD_STATUS
+  results << { dir: dir, file: file, exitstatus: status.exitstatus, log: log }
+  puts "    exit=#{status.exitstatus}  log=#{log}"
+end
+
+puts
+puts "=== validation summary ==="
+results.each do |r|
+  measurable = `grep -E '^Mutations: ' #{Shellwords.escape(r[:log])} 2>/dev/null | tail -1`.strip
+  measurable = "NO_SUMMARY" if measurable.empty?
+  puts format("%<dir>-12s %<file>-55s exit=%<exit>s  %<measurable>s",
+              dir: r[:dir], file: r[:file], exit: r[:exitstatus], measurable: measurable)
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evilution
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 0.30.0
 platform: ruby
 authors:
 - Denis Kiselev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-06 00:00:00.000000000 Z
+date: 2026-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -106,11 +106,13 @@ files:
 - docs/ast_pattern_syntax.md
 - docs/isolation.md
 - docs/mutation_density_benchmark.md
+- docs/versioning.md
 - exe/evil
 - exe/evilution
 - lib/evilution.rb
 - lib/evilution/ast.rb
 - lib/evilution/ast/constant_names.rb
+- lib/evilution/ast/heredoc_span.rb
 - lib/evilution/ast/inheritance_scanner.rb
 - lib/evilution/ast/parser.rb
 - lib/evilution/ast/pattern.rb
@@ -202,6 +204,8 @@ files:
 - lib/evilution/feedback.rb
 - lib/evilution/feedback/detector.rb
 - lib/evilution/feedback/messages.rb
+- lib/evilution/feedback/setup_warning.rb
+- lib/evilution/gem_detector.rb
 - lib/evilution/git.rb
 - lib/evilution/git/changed_files.rb
 - lib/evilution/hooks.rb
@@ -211,6 +215,7 @@ files:
 - lib/evilution/integration/base.rb
 - lib/evilution/integration/crash_detector.rb
 - lib/evilution/integration/loading.rb
+- lib/evilution/integration/loading/body_call_neutralizer.rb
 - lib/evilution/integration/loading/concern_state_cleaner.rb
 - lib/evilution/integration/loading/constant_pinner.rb
 - lib/evilution/integration/loading/mutation_applier.rb
@@ -269,6 +274,7 @@ files:
 - lib/evilution/mutator.rb
 - lib/evilution/mutator/base.rb
 - lib/evilution/mutator/operator.rb
+- lib/evilution/mutator/operator/argument_method_call_replacement.rb
 - lib/evilution/mutator/operator/argument_nil_substitution.rb
 - lib/evilution/mutator/operator/argument_removal.rb
 - lib/evilution/mutator/operator/arithmetic_replacement.rb
@@ -308,6 +314,7 @@ files:
 - lib/evilution/mutator/operator/integer_literal.rb
 - lib/evilution/mutator/operator/keyword_argument.rb
 - lib/evilution/mutator/operator/lambda_body.rb
+- lib/evilution/mutator/operator/last_expression_removal.rb
 - lib/evilution/mutator/operator/local_variable_assignment.rb
 - lib/evilution/mutator/operator/loop_flip.rb
 - lib/evilution/mutator/operator/method_body_replacement.rb
@@ -371,6 +378,7 @@ files:
 - lib/evilution/reporter/cli/line_formatters.rb
 - lib/evilution/reporter/cli/line_formatters/duration.rb
 - lib/evilution/reporter/cli/line_formatters/efficiency.rb
+- lib/evilution/reporter/cli/line_formatters/error_rate_warning.rb
 - lib/evilution/reporter/cli/line_formatters/feedback_footer.rb
 - lib/evilution/reporter/cli/line_formatters/header.rb
 - lib/evilution/reporter/cli/line_formatters/mutations.rb
@@ -457,6 +465,7 @@ files:
 - lib/evilution/runner/subject_pipeline.rb
 - lib/evilution/session.rb
 - lib/evilution/session/diff.rb
+- lib/evilution/session/schema.rb
 - lib/evilution/session/store.rb
 - lib/evilution/source_ast_cache.rb
 - lib/evilution/spec_ast_cache.rb
@@ -466,7 +475,11 @@ files:
 - lib/evilution/temp_dir_tracker.rb
 - lib/evilution/version.rb
 - lib/tasks/memory_check.rake
+- schema/evilution.config.schema.json
+- script/build_runtime_snapshot
 - script/memory_check
+- script/run_self_baseline
+- script/run_self_validation
 - scripts/benchmark_density
 - scripts/benchmark_density.yml
 - scripts/compare_mutations