evilution 0.24.0 → 0.26.0

data/README.md

@@ -27,6 +27,8 @@ Or standalone: `gem install evilution`
 evilution [command] [options] [files...]
 ```
 
+The shorter alias `evil` ships alongside `evilution` and accepts identical arguments (handy with `alias be='bundle exec'` → `be evil run ...`).
+
 ### Commands
 
 | Command              | Description                                        | Default |
@@ -42,6 +44,7 @@ evilution [command] [options] [files...]
 | `session gc --older-than D` | Garbage-collect sessions older than D (e.g. 30d) |         |
 | `util mutation`      | Preview mutations for a file or inline code         |         |
 | `environment show`   | Display runtime environment and settings            |         |
+| `compare --against A --current B` | Compare two saved session JSON files into fixed / new / persistent / flaky / reintroduced buckets |         |
 
 ### Options (for `run` command)
 
@@ -53,6 +56,9 @@ evilution [command] [options] [files...]
 | `--min-score FLOAT`          | Float   | 0.0          | Minimum mutation score (0.0–1.0) to pass.         |
 | `--spec FILES`               | Array   | _(none)_     | Spec files to run (comma-separated). Defaults to auto-detection via `SpecResolver`. |
 | `--spec-dir DIR`             | String  | _(none)_     | Include all `*_spec.rb` files in DIR recursively. Composable with `--spec`. |
+| `--spec-pattern GLOB`        | String  | _(none)_     | Restrict resolved spec candidates to files matching GLOB (e.g. `spec/models/**/*_spec.rb`). |
+| `--no-example-targeting`     | Boolean | _(enabled)_  | Disable per-mutation example targeting (always run every example in the resolved spec file). Example targeting scans each example body for symbols from the mutated method and runs only the matching subset. |
+| `--example-targeting-fallback MODE` | String | `full_file` | Behavior when no example matches: `full_file` (run the whole spec file) or `unresolved` (skip the mutation as `:unresolved`). |
 | `-j`, `--jobs N`             | Integer | 1            | Number of parallel workers. Uses demand-driven work distribution with pipe-based IPC. |
 | `--no-baseline`              | Boolean | _(enabled)_  | Skip baseline test suite check. By default, a baseline run detects pre-existing failures and marks those mutations as `neutral`. |
 | `--fail-fast [N]`            | Integer | _(none)_     | Stop after N surviving mutants (default 1 if no value given). |
@@ -101,6 +107,9 @@ Creates `.evilution.yml`:
 # baseline_session: null   # path to session file for HTML comparison
 # ignore_patterns: []      # AST patterns to exclude (see docs/ast_pattern_syntax.md)
 # progress: true           # TTY progress bar
+# example_targeting: true  # per-mutation example targeting via body-token scan
+# example_targeting_fallback: full_file  # full_file | unresolved
+# spec_pattern: null       # restrict resolved spec candidates to files matching GLOB
 ```
 
 **Precedence**: CLI flags override `.evilution.yml` values.
@@ -142,7 +151,11 @@ Use `--format json` for machine-readable output. Schema:
     "survived": "integer — mutations NOT detected (test passed = gap in coverage)",
     "timed_out": "integer — mutations that exceeded timeout",
     "errors": "integer   — mutations that caused unexpected errors",
-    "score": "float      — killed / (total - errors), range 0.0-1.0, rounded to 4 decimals",
+    "neutral": "integer  — mutations whose tests already failed before mutation (baseline failure)",
+    "equivalent": "integer — mutations proven to have identical behavior to the original",
+    "unresolved": "integer — mutations where no spec file resolved (coverage gap, not a failure)",
+    "unparseable": "integer — mutations whose mutated source did not parse (short-circuited, never executed)",
+    "score": "float      — killed / (total - errors - neutral - equivalent - unresolved - unparseable), range 0.0-1.0, rounded to 4 decimals",
     "duration": "float   — total wall-clock seconds, rounded to 4 decimals",
     "peak_memory_mb": "float (optional) — peak RSS across all mutation child processes, in MB"
   },
@@ -151,9 +164,10 @@ Use `--format json` for machine-readable output. Schema:
       "operator": "string — mutation operator name (see Operators table)",
       "file": "string    — relative path to mutated file",
       "line": "integer   — line number of the mutation",
-      "status": "string  — result status: 'survived', 'killed', 'timeout', or 'error'",
+      "status": "string  — result status: 'survived', 'killed', 'timeout', 'error', 'neutral', 'equivalent', 'unresolved', or 'unparseable'",
       "duration": "float — seconds this mutation took, rounded to 4 decimals",
-      "diff": "string    — unified diff snippet",
+      "diff": "string    — legacy +/- diff snippet",
+      "unified_diff": "string (optional, survived only) — git-style unified diff with `--- a/file`, `+++ b/file`, `@@` hunk header and sdiff body; omitted when source slices are unavailable",
       "suggestion": "string — actionable hint for surviving mutants (survived only)"
     }
   ],
@@ -168,6 +182,10 @@ Use `--format json` for machine-readable output. Schema:
     }
   ],
   "killed": ["... same shape as survived entries ..."],
+  "neutral": ["... same shape as survived entries ..."],
+  "equivalent": ["... same shape as survived entries ..."],
+  "unresolved": ["... same shape as survived entries — coverage gap: no spec file resolved for these mutations"],
+  "unparseable": ["... same shape as survived entries — mutated source failed to parse and was never executed"],
   "timed_out": ["... same shape as survived entries ..."],
   "errors": [
     {
@@ -182,6 +200,21 @@ Use `--format json` for machine-readable output. Schema:
 
 **Key metric**: `summary.score` — the mutation score. Higher is better. 1.0 means all mutations were caught.
 
+### Mutation Statuses
+
+| Status       | Meaning                                                               | Counted in score? |
+|--------------|-----------------------------------------------------------------------|-------------------|
+| `killed`     | A test failed when the mutation was applied — test suite caught it    | numerator + denominator |
+| `survived`   | No test failed — gap in coverage                                       | denominator only  |
+| `timeout`    | Test run exceeded `--timeout` — treated like survived for scoring     | denominator only  |
+| `error`      | Mutation caused an unexpected error (syntax error, boot failure, etc.) | excluded from denominator |
+| `neutral`    | Baseline tests already failed before mutation — not a meaningful signal | excluded          |
+| `equivalent` | Mutation is provably identical to the original (e.g. no-op replacement) | excluded          |
+| `unresolved` | No spec file resolved for the mutated source — **coverage gap, not a failure**. Use `--fallback-full-suite` to run the full suite instead. | excluded |
+| `unparseable` | Mutated source failed to parse (e.g. dangling heredoc opener after `method_body_replacement`). Short-circuited — never executed. | excluded |
+
+Unresolved mutations indicate a missing test mapping — the file has no corresponding test file that the resolver could find (for example, an RSpec `_spec.rb` file or a Minitest `_test.rb` file, depending on configuration). They are reported separately so you can act on them (add a test, adjust test naming, or opt in to the full-suite fallback) without inflating the error count.
+
 ## Mutation Operators (72 total)
 
 Each operator name is stable and appears in JSON output under `survived[].operator`.
@@ -314,7 +347,7 @@ Unlike `evilution --format json`, every survived entry returned by `evilution-mu
 | `spec_file` | Resolved spec/test path (when one exists) — e.g. an RSpec spec file or Minitest test file, so you can drop new tests straight into it |
 | `next_step` | Concrete natural-language hint — "add a test in X that fails against this mutation at Y:line" |
 
-These fields are added in addition to the existing `operator`, `file`, `line`, `diff`, `suggestion`, and `test_command` so agents can triage survivors in one pass.
+These fields are added in addition to the existing `operator`, `file`, `line`, `diff`, `unified_diff`, `suggestion`, and `test_command` so agents can triage survivors in one pass.
 
 ### Concrete Test Suggestions
 
@@ -419,6 +452,49 @@ bundle exec evilution run lib/ --format json --min-score 0.8 --quiet
 
 Note: `--quiet` suppresses all stdout output (including JSON). Use it in CI only when you care about the exit code and do not need JSON output.
 
+### 9. Regression tracking across runs (`compare`)
+
+```bash
+bundle exec evilution run lib/ --format json --save-session
+# later, after edits:
+bundle exec evilution run lib/ --format json --save-session
+
+bundle exec evilution compare \
+  --against .evilution/results/<earlier>.json \
+  --current  .evilution/results/<later>.json \
+  --format json
+```
+
+Output buckets:
+
+| Bucket          | Meaning |
+|-----------------|---------|
+| `fixed`         | Survived previously, killed now — the new test actually landed |
+| `new`           | Did not exist previously, surviving now — a fresh gap |
+| `persistent`    | Survived in both runs — carry-over debt |
+| `reintroduced`  | Killed previously, survived now — regression |
+| `flaky`         | Status flipped and back — unstable test |
+
+Use in CI to gate merges on `reintroduced` being empty, or to surface `new` survivors for reviewer attention without failing the build on `persistent` debt.
+
+## Parallel Runs with SQLite
+
+Running with `-j N` forks worker processes. If your Rails app uses SQLite, every worker opens the same `db/test.sqlite3` file, and concurrent writers collide on the database-level lock. Symptoms: `ActiveRecord::StatementTimeout`, `SQLite3::BusyException`, and slow runs. Evilution classifies these crashes as `:neutral` (see [EV-toid / #814](https://github.com/taxdome/evilution/issues/814)) so the mutation score is not polluted, but the wall-clock penalty remains.
+
+Evilution follows the [`parallel_tests`](https://github.com/grosser/parallel_tests) convention: each worker receives a `TEST_ENV_NUMBER` environment variable (`""` for worker 1, `"2"` for worker 2, `"3"` for worker 3, …). Interpolate it into `config/database.yml` so each worker gets its own SQLite file:
+
+```yaml
+test:
+  adapter: sqlite3
+  database: db/test<%= ENV['TEST_ENV_NUMBER'] %>.sqlite3
+  pool: 5
+  timeout: 5000
+```
+
+After the first `jobs > 1` run, each worker creates its own file (`db/test.sqlite3`, `db/test2.sqlite3`, …). Seed each with `rake db:test:prepare` before running Evilution, or ensure your preload sets up schema on connect.
+
+When Evilution detects a parallel run against a SQLite-backed `config/database.yml`, it prints a one-time startup warning pointing to this section.
+
 ## Development
 
 ### Memory leak check

data/exe/evil

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "evilution"
+
+exit Evilution::CLI.new(ARGV).call

data/lib/evilution/ast/constant_names.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../ast"
+
+# Walks a Prism AST and returns every class/module constant declared, nested
+# names rendered fully-qualified (e.g. "Foo::Bar"). Order is source order:
+# outer declarations precede their nested children.
+class Evilution::AST::ConstantNames
+  def call(source)
+    result = Prism.parse(source)
+    return [] if result.failure?
+
+    collect(result.value)
+  end
+
+  private
+
+  def collect(node, nesting = [])
+    names = []
+    case node
+    when Prism::ModuleNode, Prism::ClassNode
+      const = node.constant_path.full_name
+      qualified = nesting.any? && !const.include?("::") ? "#{nesting.join("::")}::#{const}" : const
+      names << qualified
+      names.concat(collect(node.body, nesting + [const])) if node.body
+    when Prism::ProgramNode
+      names.concat(collect(node.statements, nesting)) if node.statements
+    when Prism::StatementsNode
+      node.body.each { |child| names.concat(collect(child, nesting)) }
+    end
+    names
+  end
+end

data/lib/evilution/ast/source_surgeon.rb

@@ -1,11 +1,25 @@
 # frozen_string_literal: true
 
+require "prism"
+
 require_relative "../ast"
 
 module Evilution::AST::SourceSurgeon
+  Result = Struct.new(:source, :status, keyword_init: true) do
+    def ok?
+      status == :ok
+    end
+
+    def unparseable?
+      status == :unparseable
+    end
+  end
+
   def self.apply(source, offset:, length:, replacement:)
     binary = source.b
     binary[offset, length] = replacement.b
-    binary.force_encoding(source.encoding)
+    mutated = binary.force_encoding(source.encoding)
+    status = Prism.parse(mutated).success? ? :ok : :unparseable
+    Result.new(source: mutated, status: status).freeze
   end
 end

data/lib/evilution/cli/commands/compare.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../printers/compare"
+require_relative "../../compare"
+require_relative "../../compare/categorizer"
+require_relative "../../compare/detector"
+require_relative "../../compare/normalizer"
+
+class Evilution::CLI::Commands::Compare < Evilution::CLI::Command
+  SUPPORTED_FORMATS = %i[json text].freeze
+
+  private
+
+  def perform
+    paths = resolve_paths
+    raise Evilution::ConfigError, "exactly two file paths required for compare" unless paths.length == 2
+
+    fmt = @options[:format] || :json
+    raise Evilution::ConfigError, "compare supports --format text or json, got #{fmt.inspect}" unless SUPPORTED_FORMATS.include?(fmt)
+
+    against = load_and_normalize(paths[0])
+    current = load_and_normalize(paths[1])
+    buckets = Evilution::Compare::Categorizer.call(against, current)
+    Evilution::CLI::Printers::Compare.new(buckets, format: fmt).render(@stdout)
+    0
+  end
+
+  # Flags bind to roles (--against -> slot 0, --current -> slot 1);
+  # positional @files fill whatever role the flags didn't claim, in order.
+  # Extra positional args after both slots are filled are a user error.
+  def resolve_paths
+    positional = @files.dup
+    against = @options[:against] || positional.shift
+    current = @options[:current] || positional.shift
+
+    raise Evilution::ConfigError, "exactly two file paths required for compare" unless positional.empty?
+
+    [against, current].compact
+  end
+
+  def load_and_normalize(path)
+    raise Evilution::Error, "file not found: #{path}" unless File.exist?(path)
+
+    json = JSON.parse(File.read(path))
+    tool = Evilution::Compare::Detector.call(json)
+    normalize(json, tool)
+  rescue ::JSON::ParserError => e
+    raise Evilution::Error, "invalid JSON in #{path}: #{e.message}"
+  rescue Evilution::Compare::InvalidInput => e
+    raise Evilution::Error, "#{path}: #{e.message}"
+  rescue SystemCallError => e
+    raise Evilution::Error, e.message
+  end
+
+  def normalize(json, tool)
+    normalizer = Evilution::Compare::Normalizer.new
+    case tool
+    when :mutant    then normalizer.from_mutant(json)
+    when :evilution then normalizer.from_evilution(json)
+    end
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:compare, Evilution::CLI::Commands::Compare)

data/lib/evilution/cli/parser/command_extractor.rb

@@ -5,7 +5,8 @@ class Evilution::CLI::Parser::CommandExtractor
     "version" => :version,
     "init" => :init,
     "mcp" => :mcp,
-    "subjects" => :subjects
+    "subjects" => :subjects,
+    "compare" => :compare
   }.freeze
 
   SESSION_SUBCOMMANDS = {

data/lib/evilution/cli/parser/options_builder.rb

@@ -23,6 +23,7 @@ class Evilution::CLI::Parser::OptionsBuilder
       add_flag_options(opts)
       add_extra_flag_options(opts)
       add_session_options(opts)
+      add_compare_options(opts)
     end
   end
 
@@ -33,7 +34,7 @@ class Evilution::CLI::Parser::OptionsBuilder
     opts.separator "Line-range targeting: lib/foo.rb:15-30, lib/foo.rb:15, lib/foo.rb:15-"
     opts.separator ""
     opts.separator "Commands: run (default), init, session {list,show,diff,gc}, subjects, tests {list},"
-    opts.separator "         util {mutation}, environment {show}, mcp, version"
+    opts.separator "         util {mutation}, environment {show}, compare, mcp, version"
     opts.separator ""
     opts.separator "Options:"
   end
@@ -48,6 +49,16 @@ class Evilution::CLI::Parser::OptionsBuilder
     opts.on("--min-score FLOAT", Float, "Minimum mutation score to pass") { |s| @options[:min_score] = s }
     opts.on("--spec FILES", Array, "Spec files to run (comma-separated)") { |f| @options[:spec_files] = f }
     opts.on("--spec-dir DIR", "Include all specs in DIR") { |d| expand_spec_dir(d) }
+    opts.on("--spec-pattern GLOB",
+            "Restrict resolved spec candidates to files matching GLOB") { |p| @options[:spec_pattern] = p }
+    opts.on("--no-example-targeting",
+            "Disable per-mutation example targeting (run all examples in resolved spec files)") do
+      @options[:example_targeting] = false
+    end
+    opts.on("--example-targeting-fallback MODE", %w[full_file unresolved],
+            "Fallback when example targeting finds no match: full_file (default) or unresolved") do |m|
+      @options[:example_targeting_fallback] = m
+    end
     opts.on("--target EXPR",
             "Filter: method (Foo#bar), type (Foo#/Foo.), namespace (Foo*),",
             "class (Foo), glob (source:**/*.rb), hierarchy (descendants:Foo)") do |m|
@@ -96,6 +107,15 @@ class Evilution::CLI::Parser::OptionsBuilder
     end
   end
 
+  def add_compare_options(opts)
+    opts.on("--against PATH", "Prior mutation run to compare against (used with `compare` command)") do |p|
+      @options[:against] = p
+    end
+    opts.on("--current PATH", "Current mutation run to compare (used with `compare` command)") do |p|
+      @options[:current] = p
+    end
+  end
+
   def expand_spec_dir(dir)
     specs = Evilution::CLI::Parser::FileArgs.expand_spec_dir(dir)
     @options[:spec_files] = Array(@options[:spec_files]) + specs

data/lib/evilution/cli/printers/compare.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../printers"
+
+class Evilution::CLI::Printers::Compare
+  SCHEMA = {
+    "shared" => %w[file line operator fp],
+    "alive_only" => %w[file line operator fp other_status]
+  }.freeze
+
+  FILE_LINE_WIDTH = 40
+  OPERATOR_WIDTH  = 22
+  FP_LENGTH       = 7
+  MUTANT_OPERATOR = "(mutant)"
+  ABSENT_STATUS   = "absent"
+
+  def initialize(buckets, format: :json)
+    @buckets = buckets
+    @format  = format || :json
+  end
+
+  def render(io)
+    case @format
+    when :json then render_json(io)
+    when :text then render_text(io)
+    else raise Evilution::Error, "unknown compare format: #{@format.inspect}"
+    end
+  end
+
+  private
+
+  def render_json(io)
+    payload = {
+      "schema" => SCHEMA,
+      "summary" => summary_hash,
+      "alive_only_against" => @buckets[:alive_only_against].map { |e| alive_entry_array(e) },
+      "alive_only_current" => @buckets[:alive_only_current].map { |e| alive_entry_array(e) },
+      "shared_alive" => @buckets[:shared_alive].map { |e| shared_entry_array(e) },
+      "shared_dead" => @buckets[:shared_dead].map { |e| shared_entry_array(e) }
+    }
+    io.puts(JSON.generate(payload))
+  end
+
+  def render_text(io)
+    io.puts("Compare results")
+    io.puts("-" * 15)
+    io.puts(summary_line)
+
+    if fully_empty?
+      io.puts("No mutations to compare.")
+      return
+    end
+
+    print_alive_block(io, :alive_only_against, "current")
+    print_alive_block(io, :alive_only_current, "against")
+    print_shared_block(io, :shared_alive)
+    print_shared_block(io, :shared_dead)
+  end
+
+  def summary_hash
+    against_count = @buckets[:alive_only_against].length
+    current_count = @buckets[:alive_only_current].length
+    {
+      "alive_only_against" => against_count,
+      "alive_only_current" => current_count,
+      "shared_alive" => @buckets[:shared_alive].length,
+      "shared_dead" => @buckets[:shared_dead].length,
+      "excluded_against" => @buckets[:excluded_against],
+      "excluded_current" => @buckets[:excluded_current],
+      "delta" => current_count - against_count
+    }
+  end
+
+  def summary_line
+    s = summary_hash
+    parts = [
+      "summary:",
+      "alive_only_against=#{s["alive_only_against"]}",
+      "alive_only_current=#{s["alive_only_current"]}",
+      "shared_alive=#{s["shared_alive"]}",
+      "shared_dead=#{s["shared_dead"]}",
+      "excluded=#{s["excluded_against"]}/#{s["excluded_current"]}",
+      "delta=#{format_delta(s["delta"])}"
+    ]
+    parts.join(" ")
+  end
+
+  def format_delta(delta)
+    return "\u00B10" if delta.zero?
+
+    format("%+d", delta)
+  end
+
+  def fully_empty?
+    @buckets[:alive_only_against].empty? &&
+      @buckets[:alive_only_current].empty? &&
+      @buckets[:shared_alive].empty? &&
+      @buckets[:shared_dead].empty? &&
+      @buckets[:excluded_against].zero? &&
+      @buckets[:excluded_current].zero?
+  end
+
+  def alive_entry_array(entry)
+    r = entry[:record]
+    peer = entry[:peer_status]
+    peer_str = peer.nil? ? ABSENT_STATUS : peer.to_s
+    [r.file_path, r.line, r.operator, r.fingerprint, peer_str]
+  end
+
+  def shared_entry_array(entry)
+    r = entry[:against]
+    [r.file_path, r.line, shared_operator(entry), r.fingerprint]
+  end
+
+  # Mutant-sourced records always have operator=nil. When comparing mutant
+  # vs evilution, prefer whichever side has an operator so the shared row
+  # stays informative.
+  def shared_operator(entry)
+    entry[:against].operator || entry[:current].operator
+  end
+
+  def print_alive_block(io, bucket_key, peer_side_label)
+    entries = @buckets[bucket_key]
+    return if entries.empty?
+
+    io.puts("")
+    io.puts("#{bucket_key} (#{entries.length}):")
+    entries.each { |entry| io.puts(format_alive_row(entry, peer_side_label)) }
+  end
+
+  def print_shared_block(io, bucket_key)
+    entries = @buckets[bucket_key]
+    return if entries.empty?
+
+    io.puts("")
+    io.puts("#{bucket_key} (#{entries.length}):")
+    entries.each { |entry| io.puts(format_shared_row(entry)) }
+  end
+
+  def format_alive_row(entry, peer_side_label)
+    r = entry[:record]
+    peer = entry[:peer_status]
+    peer_str = peer.nil? ? ABSENT_STATUS : peer.to_s
+    "  #{row_prefix(r)}  (#{peer_side_label}: #{peer_str})"
+  end
+
+  def format_shared_row(entry)
+    r = entry[:against]
+    "  #{row_prefix(r, operator: shared_operator(entry))}"
+  end
+
+  def row_prefix(record, operator: record.operator)
+    file_line = "#{record.file_path}:#{record.line}"
+    op_label  = operator || MUTANT_OPERATOR
+    fp        = record.fingerprint.to_s[0, FP_LENGTH]
+    "#{file_line.ljust(FILE_LINE_WIDTH)}#{op_label.ljust(OPERATOR_WIDTH)}#{fp}"
+  end
+end

data/lib/evilution/cli.rb

@@ -16,6 +16,7 @@ require_relative "cli/commands/session_list"
 require_relative "cli/commands/session_show"
 require_relative "cli/commands/session_diff"
 require_relative "cli/commands/session_gc"
+require_relative "cli/commands/compare"
 require_relative "cli/commands/run"
 
 class Evilution::CLI

data/lib/evilution/compare/categorizer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "../compare"
+require_relative "record"
+
+module Evilution::Compare::Categorizer
+  ALIVE = %i[survived].freeze
+  DEAD  = %i[killed timeout error].freeze
+  # neutral, equivalent, unresolved, unparseable are non-actionable signals
+  # — excluded from alive/dead buckets, counted in summary.
+
+  module_function
+
+  # @param against [Array<Record>] prior run (baseline)
+  # @param current [Array<Record>] current run
+  # @return [Hash] bucketed comparison result with keys:
+  #   - `:alive_only_against` => `Array<{record: Record, peer_status: Symbol|nil}>`
+  #     records that survived in against but not in current (or absent in current).
+  #     `peer_status` is the current-side record's status symbol, or `nil` when
+  #     no current-side record exists for that fingerprint.
+  #   - `:alive_only_current` => `Array<{record: Record, peer_status: Symbol|nil}>`
+  #     mirror of the above from the current side.
+  #   - `:shared_alive` => `Array<{against: Record, current: Record}>`
+  #     mutations that survived in both runs.
+  #   - `:shared_dead` => `Array<{against: Record, current: Record}>`
+  #     mutations killed/timed-out/errored in both runs.
+  #   - `:excluded_against` => `Integer`
+  #     count of against records with non-actionable statuses (neutral,
+  #     equivalent, unresolved, unparseable).
+  #   - `:excluded_current` => `Integer` mirror for the current side.
+  def call(against, current)
+    # Duplicate fingerprints within one side should not happen (Normalizer
+    # invariant). If they do, last write wins — we do not dedupe proactively.
+    against_by_fp = index_by_fingerprint(against)
+    current_by_fp = index_by_fingerprint(current)
+
+    buckets = {
+      alive_only_against: [],
+      alive_only_current: [],
+      shared_alive: [],
+      shared_dead: [],
+      excluded_against: 0,
+      excluded_current: 0
+    }
+
+    (against_by_fp.keys | current_by_fp.keys).each do |fp|
+      classify(against_by_fp[fp], current_by_fp[fp], buckets)
+    end
+
+    sort_buckets!(buckets)
+    buckets
+  end
+
+  # Dispatches one fingerprint pair into buckets.
+  # Either record may be nil (fingerprint present on only one side).
+  def classify(against_record, current_record, buckets)
+    count_excluded(against_record, current_record, buckets)
+    a_kind = kind_of(against_record)
+    c_kind = kind_of(current_record)
+
+    if a_kind == :alive && c_kind == :alive
+      buckets[:shared_alive] << { against: against_record, current: current_record }
+    elsif a_kind == :dead && c_kind == :dead
+      buckets[:shared_dead] << { against: against_record, current: current_record }
+    else
+      bucket_single_sided(against_record, current_record, a_kind, c_kind, buckets)
+    end
+    # A dead-only fingerprint (dead on one side, absent on the other) is
+    # intentionally not bucketed and not counted as excluded.
+  end
+
+  def count_excluded(against_record, current_record, buckets)
+    buckets[:excluded_against] += 1 if against_record && kind_of(against_record) == :excluded
+    buckets[:excluded_current] += 1 if current_record && kind_of(current_record) == :excluded
+  end
+
+  def bucket_single_sided(against_record, current_record, a_kind, c_kind, buckets)
+    # peer_status is the peer record's status symbol, or nil if peer absent.
+    # When the peer is excluded, its status symbol (e.g. :neutral) flows through.
+    a_peer = current_record && current_record.status
+    c_peer = against_record && against_record.status
+    buckets[:alive_only_against] << { record: against_record, peer_status: a_peer } if a_kind == :alive
+    buckets[:alive_only_current] << { record: current_record, peer_status: c_peer } if c_kind == :alive
+  end
+
+  # Returns :alive, :dead, :excluded, or nil (for nil records).
+  def kind_of(record)
+    return nil if record.nil?
+    return :alive if ALIVE.include?(record.status)
+    return :dead  if DEAD.include?(record.status)
+
+    :excluded
+  end
+
+  def sort_buckets!(buckets)
+    buckets[:alive_only_against].sort_by! { |e| sort_key(e[:record]) }
+    buckets[:alive_only_current].sort_by! { |e| sort_key(e[:record]) }
+    buckets[:shared_alive].sort_by!       { |e| sort_key(e[:against]) }
+    buckets[:shared_dead].sort_by!        { |e| sort_key(e[:against]) }
+  end
+
+  def sort_key(record)
+    [record.file_path, record.line, record.fingerprint]
+  end
+
+  def index_by_fingerprint(records)
+    records.to_h { |r| [r.fingerprint, r] }
+  end
+end

data/lib/evilution/compare/detector.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../compare"
+require_relative "normalizer"
+
+module Evilution::Compare::Detector
+  module_function
+
+  def call(json)
+    raise Evilution::Compare::InvalidInput, "expected Hash, got #{json.class}" unless json.is_a?(Hash)
+
+    mutant = json.key?("subject_results")
+    evilution = json.key?("summary") && Evilution::Compare::Normalizer::EVILUTION_BUCKETS.any? { |k| json.key?(k) }
+
+    raise Evilution::Compare::InvalidInput, "ambiguous JSON shape - both mutant and evilution markers present" if mutant && evilution
+    return :mutant if mutant
+    return :evilution if evilution
+
+    raise Evilution::Compare::InvalidInput, "cannot detect tool from JSON shape"
+  end
+end