evilution 0.33.0 → 0.35.0

data/docs/migration-from-mutant.md

@@ -0,0 +1,226 @@
+# Migrating from `mutant` to Evilution
+
+This guide is for teams moving off [`mutant`](https://github.com/mbj/mutant) — whose
+runtime is under a commercial license — to Evilution, which is MIT-licensed with no
+commercial restrictions. It maps the commands, config, and output you already know
+onto their Evilution equivalents, and is honest about where the two tools differ.
+
+Evilution is not a drop-in fork of mutant. It produces its own mutations with its own
+operator set and selects work by **file path** rather than by subject expression. The
+result is the same kind of signal — surviving mutations expose weak tests — but the
+numbers and the workflow are not identical. The `compare` command (below) exists
+precisely so you can line the two tools up and see the difference for yourself.
+
+## TL;DR
+
+| mutant | Evilution |
+| --- | --- |
+| `mutant run --use rspec -- 'MyApp::Foo*'` | `evilution run lib/my_app/ --target 'MyApp::Foo*'` |
+| `mutant.yml` | `.evilution.yml` (run `evilution init` to scaffold) |
+| `mutant-rspec` / `mutant-minitest` gems | built in: `--integration rspec\|minitest\|test-unit` |
+| "mutation coverage" %, "alive" | "mutation score" 0.0–1.0, "survived" |
+| commercial license for the runtime | MIT |
+
+## 1. Install
+
+Drop the mutant gems and add Evilution:
+
+```ruby
+# Gemfile — remove:  gem "mutant", "mutant-rspec"
+gem "evilution", group: :test
+```
+
+```sh
+bundle install
+bundle exec evilution init   # writes a commented .evilution.yml
+```
+
+There is no separate integration gem to install — RSpec, Minitest, and Test::Unit
+support ships in the core gem.
+
+## 2. The core workflow shift: files, not subjects
+
+mutant is **subject-driven**: you pass a match expression and it finds the code.
+Evilution is **file-driven**: you pass file paths, and optionally narrow with
+`--target`.
+
+```sh
+# mutant
+bundle exec mutant run --use rspec -- 'MyApp::Calculator#add'
+
+# evilution — point at the file, optionally filter to the method
+bundle exec evilution run lib/my_app/calculator.rb --target 'MyApp::Calculator#add'
+
+# whole directory, then filter by expression
+bundle exec evilution run lib/ --target 'MyApp::Calculator*'
+```
+
+`--target` accepts the expression shapes you are used to, plus a source glob:
+
+| Intent | mutant match | Evilution `--target` |
+| --- | --- | --- |
+| One method | `MyApp::Foo#bar` | `MyApp::Foo#bar` |
+| One class | `MyApp::Foo` | `MyApp::Foo` |
+| Namespace (recursive) | `MyApp::Foo*` | `MyApp::Foo*` |
+| All instance methods | `MyApp::Foo#` | `MyApp::Foo#` |
+| All singleton methods | `MyApp::Foo.` | `MyApp::Foo.` |
+| Subclasses | _(n/a)_ | `descendants:MyApp::Foo` |
+| By file glob | _(use file args)_ | `source:lib/**/*.rb` |
+
+## 3. Command mapping
+
+| Task | mutant | Evilution |
+| --- | --- | --- |
+| Run mutation testing | `mutant run -- 'Foo'` | `evilution run lib/foo.rb` (alias `mutate`; binary alias `evil`) |
+| Choose framework | `--use rspec` / `mutant-minitest` | `--integration rspec\|minitest\|test-unit` |
+| Parallel workers | `-j N` / `--jobs N` | `-j N` / `--jobs N` |
+| Fail fast | `--fail-fast` | `--fail-fast [N]` (off by default; N defaults to 1 when the flag is given without a value) |
+| Coverage gate | `--score` (default `1.0` / 100%) | `--min-score` (default `0.0`) |
+| Preview mutations | `mutant util mutation` / `mutant environment subject list` | `evilution util mutation -e 'a + b'` / `evilution subjects lib/foo.rb` |
+| Set load path / requires | `--include lib --require my_app` | handled by `--preload` (auto-detects `spec/spec_helper.rb` etc.) + Bundler |
+| JSON report | session JSON (always written) | `--format json` (`--save-session` to persist) |
+| Inline opt-out | `# mutant:disable` | `# evilution:disable` |
+| Aggressive operators | _(always on)_ | `--profile strict` (or `--strict`) |
+
+### Things mutant has that Evilution does not (yet)
+
+- **`--since <git-ref>`** — mutant can restrict subjects to lines changed since a git
+  ref. Evilution has no diff-aware selection. The closest tools are `--incremental`
+  (caches `killed`/`timeout` results and skips unchanged mutations on re-runs — a
+  different model) and `--target source:<glob>` / explicit file args to scope a run.
+
+### Things Evilution adds
+
+- `--format html` interactive report, and `evilution compare` (see §6).
+- Per-mutation **example targeting** (runs only the examples that exercise the mutated
+  code) — on by default, tune with `example_targeting*` keys.
+- `--suggest-tests` emits concrete test code for survivors.
+- Explicit `:unresolved` status when no spec maps to a source file (a coverage-gap
+  signal rather than a silent skip).
+
+## 4. Config translation (`mutant.yml` → `.evilution.yml`)
+
+```yaml
+# mutant.yml
+integration:
+  name: rspec
+jobs: 8
+includes:
+  - lib
+requires:
+  - my_app
+matcher:
+  subjects:
+    - MyApp::Billing*
+  ignore:
+    - MyApp::Billing::Legacy#deprecated
+```
+
+```yaml
+# .evilution.yml
+integration: rspec
+jobs: 8
+# `includes` / `requires` are usually unnecessary — Evilution preloads the test
+# helper (and the gem entry) automatically. Override only if needed:
+preload: spec/spec_helper.rb
+# `matcher.subjects` -> run file args + --target; expression below is illustrative.
+target: "MyApp::Billing*"
+# `matcher.ignore` -> AST ignore patterns (see docs/ast_pattern_syntax.md) or an
+# inline `# evilution:disable` comment on the method.
+ignore_patterns: []
+```
+
+Key-by-key:
+
+| `mutant.yml` | `.evilution.yml` | Notes |
+| --- | --- | --- |
+| `integration.name: rspec` | `integration: rspec` | string, not a mapping |
+| `jobs` | `jobs` | same |
+| `includes` | _(usually omit)_ | Bundler + `preload` cover the load path |
+| `requires` | `preload` | a single preload file (autodetected by default) |
+| `matcher.subjects` | `target` + file args | one expression; combine with positional paths |
+| `matcher.ignore` | `ignore_patterns` / `# evilution:disable` | AST patterns or inline comments |
+| `fail_fast` | `fail_fast` | integer N or `null` |
+| `--score` gate (CLI; default `1.0`) | `min_score` | evilution defaults to `0.0` — set your own gate |
+| _(n/a)_ | `profile: strict` | opt into aggressive truthiness mutators |
+
+Run `evilution init` for a fully commented template, and point your editor at
+`schema/evilution.config.schema.json` for autocomplete/validation.
+
+> **Note:** the `integration` enum in that JSON schema currently lists only `rspec`
+> and `minitest`. `test-unit` (normalized internally to `test_unit`) is fully
+> supported by the runtime, but a schema-aware editor may flag it as invalid until
+> the schema catches up — it will still run.
+
+## 5. Output differences
+
+The vocabulary and the math differ — read this before comparing dashboards.
+
+| Concept | mutant | Evilution |
+| --- | --- | --- |
+| Detected mutation | `killed` | `killed` |
+| Undetected mutation | `alive` | `survived` |
+| Headline metric | "mutation coverage" (%) | "mutation score" (0.0–1.0) |
+| Pre-existing test failure | `neutral` / `noop` | `neutral` |
+| Operator name in report | **not emitted** | emitted, e.g. `Arithmetic::Swap` |
+| Per-mutation diff | unified diff with `@@` header + context | `- old` / `+ new` pair (and a full `unified_diff` for survivors) |
+| Report shape | nested: session → subject → coverage results | flat per-status buckets |
+
+**Score formula.** mutant's coverage is roughly `killed / (total - neutral)` and the
+culture is to gate at 100%. Evilution's score is:
+
+```
+score = killed / (total - errors - neutral - equivalent - unresolved - unparseable)
+```
+
+i.e. only `killed / (killed + survived + timed_out)`. It defaults to a `min_score` of
+`0.0` (no gate) — set your own threshold in CI with `--min-score`.
+
+**Extra statuses** Evilution reports that mutant has no equivalent for:
+
+- `unresolved` — no spec file mapped to the mutated source (coverage gap, excluded from score)
+- `unparseable` — the mutated source did not parse, so it never ran (excluded)
+- `equivalent` — proven behaviorally identical to the original (excluded)
+- `timeout` / `error` — surfaced explicitly per mutation
+
+**Exit codes:** `0` pass · `1` score below `--min-score` (survivors to address) · `2` error.
+
+## 6. Verify the migration with `compare`
+
+`evilution compare` ingests **both** a mutant session JSON and an Evilution JSON
+report, normalizes them to a common shape, and buckets the mutations so you can see
+whether the same code is being killed:
+
+```sh
+# produce an evilution report
+bundle exec evilution run lib/ --format json --save-session
+
+# line it up against your last mutant session JSON
+bundle exec evilution compare \
+  --against .mutant/results/<session-id>.json \
+  --current .evilution/results/<timestamp>.json \
+  --format text
+```
+
+The tool auto-detects which file came from which tool. Because the two tools use
+different operator sets, expect the mutation **counts** to differ — the useful signal
+is which subjects lose or gain coverage, not an exact 1:1 match. Operator names are
+absent from mutant's JSON, so comparison keys on file + line + normalized diff, not on
+operator.
+
+## 7. Known gaps & parity notes
+
+- **Different mutations.** Evilution ships its own operator registry (`--profile
+  default` / `strict`); it is not mutant's AST-handler set. Counts and specific
+  survivors will differ. Use `compare` to quantify.
+- **No diff-based selection** (`--since <ref>`). Use file args, `--target source:`,
+  or `--incremental`.
+- **File-driven, not subject-driven.** Always pass paths; narrow with `--target`.
+- **100%-coverage culture.** Evilution does not assume a 100% gate; choose `min_score`
+  deliberately, and note that `:unresolved` mutations are excluded from the score
+  rather than counted as failures.
+- **Operator names** appear in Evilution output but not mutant's, so cross-tool diffs
+  match on location + change, not operator identity.
+
+If something you relied on in mutant has no clear equivalent here, please open an issue
+— parity feedback directly shapes the 1.0 roadmap.

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

@@ -66,6 +66,11 @@ class Evilution::CLI::Parser::OptionsBuilder
             "Disable per-mutation example targeting (run all examples in resolved spec files)") do
       @options[:example_targeting] = false
     end
+    opts.on("--example-targeting MODE", %w[lexical coverage full_file],
+            "Per-mutation targeting: lexical (default, name-grep), coverage (run only the",
+            "examples that execute the mutated line), or full_file (run all resolved examples)") do |m|
+      apply_example_targeting_mode(m)
+    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
@@ -77,6 +82,18 @@ class Evilution::CLI::Parser::OptionsBuilder
     end
   end
 
+  # Map the single --example-targeting flag onto the two underlying config axes:
+  # full_file is "targeting off" (run all resolved examples); lexical/coverage
+  # turn targeting on and select the strategy.
+  def apply_example_targeting_mode(mode)
+    if mode == "full_file"
+      @options[:example_targeting] = false
+    else
+      @options[:example_targeting] = true
+      @options[:example_targeting_strategy] = mode.to_sym
+    end
+  end
+
   def add_flag_options(opts)
     opts.on("--fail-fast", "Stop after N surviving mutants " \
                            "(default: disabled; if provided without N, uses 1; use --fail-fast=N)") { @options[:fail_fast] ||= 1 }

data/lib/evilution/config/builders/spec_resolver.rb

@@ -6,7 +6,9 @@ require_relative "../../spec_resolver"
 class Evilution::Config::Builders::SpecResolver
   def self.call(integration:)
     case integration
-    when :minitest
+    when :minitest, :test_unit
+      # test-unit gems mirror minitest's layout (test/ root, _test.rb suffix);
+      # without this they default to spec/_spec.rb and resolve to nothing.
       Evilution::SpecResolver.new(test_dir: "test", test_suffix: "_test.rb", request_dir: "integration")
     else
       Evilution::SpecResolver.new

data/lib/evilution/config/validators/example_targeting_strategy.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::ExampleTargetingStrategy < Evilution::Config::Validators::Base
+  STRATEGIES = %i[lexical coverage].freeze
+
+  def self.call(value)
+    unless value.is_a?(String) || value.is_a?(Symbol)
+      raise Evilution::ConfigError,
+            "example_targeting_strategy must be lexical or coverage, got #{value.inspect}"
+    end
+
+    sym = value.to_sym
+    unless STRATEGIES.include?(sym)
+      raise Evilution::ConfigError,
+            "example_targeting_strategy must be lexical or coverage, got #{sym.inspect}"
+    end
+
+    sym
+  end
+end

data/lib/evilution/config.rb

@@ -17,7 +17,7 @@ class Evilution::Config
     show_disabled: false, baseline_session: nil, skip_heredoc_literals: false,
     related_specs_heuristic: false, fallback_to_full_suite: false, preload: nil,
     spec_mappings: {}, spec_pattern: nil, example_targeting: true,
-    example_targeting_fallback: :full_file,
+    example_targeting_fallback: :full_file, example_targeting_strategy: :lexical,
     example_targeting_cache: { max_files: 50, max_blocks: 10_000 },
     quiet_children: false, quiet_children_dir: "tmp/evilution_children",
     profile: :default, canary: true
@@ -30,7 +30,8 @@ class Evilution::Config
               :ignore_patterns, :show_disabled, :baseline_session,
               :skip_heredoc_literals, :related_specs_heuristic,
               :fallback_to_full_suite, :preload, :spec_mappings, :spec_pattern,
-              :example_targeting, :example_targeting_fallback, :example_targeting_cache,
+              :example_targeting, :example_targeting_fallback, :example_targeting_strategy,
+              :example_targeting_cache,
               :spec_selector, :quiet_children, :quiet_children_dir, :profile, :canary
 
   def initialize(**options)
@@ -104,6 +105,10 @@ class Evilution::Config
     example_targeting
   end
 
+  def coverage_targeting?
+    example_targeting && example_targeting_strategy == :coverage
+  end
+
   def fallback_to_full_suite?
     fallback_to_full_suite
   end
@@ -187,6 +192,13 @@ class Evilution::Config
       # without editing the file by exporting EV_DISABLE_EXAMPLE_TARGETING=1.
       # example_targeting: true
 
+      # How targeting picks examples (default: lexical).
+      # lexical  - text-grep resolved spec files for the mutated method/class name
+      # coverage - run exactly the examples that EXECUTE the mutated line, from a
+      #            cached full-suite line-coverage map (falls back to lexical for
+      #            any file the map has not fully built)
+      # example_targeting_strategy: lexical
+
       # 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
@@ -275,6 +287,7 @@ class Evilution::Config
   def assign_example_targeting(merged)
     @example_targeting          = merged[:example_targeting] ? true : false
     @example_targeting_fallback = Validators::ExampleTargetingFallback.call(merged[:example_targeting_fallback])
+    @example_targeting_strategy = Validators::ExampleTargetingStrategy.call(merged[:example_targeting_strategy])
     @example_targeting_cache    = Validators::ExampleTargetingCache.call(merged[:example_targeting_cache])
   end
 end
@@ -294,6 +307,7 @@ require_relative "config/validators/ignore_patterns"
 require_relative "config/validators/spec_pattern"
 require_relative "config/validators/spec_mappings"
 require_relative "config/validators/example_targeting_fallback"
+require_relative "config/validators/example_targeting_strategy"
 require_relative "config/validators/example_targeting_cache"
 require_relative "config/validators/profile"
 require_relative "config/builders"

data/lib/evilution/coverage/digest.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../coverage"
+
+# Stable, content-addressed digest of a source file, used by MapStore to detect
+# when a cached coverage entry has gone stale. Path-independent: the digest
+# depends only on the bytes, so moving a file does not invalidate it. Returns
+# nil for a missing file so callers treat it as "not fresh".
+class Evilution::Coverage::Digest
+  def for_file(path)
+    return nil unless File.file?(path)
+
+    ::Digest::SHA256.hexdigest(File.binread(path))
+  end
+end

data/lib/evilution/coverage/map.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "../coverage"
+
+# Immutable query over a per-example line-coverage index:
+#   source file -> line -> [example locations ("spec.rb:line")].
+# built_files records the source files for which the build completed, so
+# callers can distinguish "line genuinely uncovered" (file built, no entry)
+# from "we never built this file" (must fall back, not assert a gap).
+class Evilution::Coverage::Map
+  def self.from_h(hash)
+    index = (hash["index"] || {}).transform_values do |lines|
+      lines.transform_keys(&:to_i)
+    end
+    executed = (hash["executed_lines"] || {}).transform_values { |lines| lines.map(&:to_i) }
+    new(index: index, built_files: hash["built_files"] || [], executed_lines: executed)
+  end
+
+  # executed_lines records, per file, the lines that ran at all during the build
+  # (including lines covered only at load, e.g. a `def` line, which are
+  # attributed to no single example). It lets a caller tell a TRUE coverage gap
+  # (line never executed) from a load-covered line an example may still exercise
+  # indirectly -- so the latter falls back instead of being mis-skipped.
+  def initialize(index:, built_files:, executed_lines: {})
+    @index = deep_freeze_index(index)
+    @built_files = built_files.to_a.freeze
+    @executed_lines = deep_freeze_executed(executed_lines)
+    freeze
+  end
+
+  def examples_for(file, line)
+    @index.dig(file, line) || []
+  end
+
+  def built?(file)
+    @built_files.include?(file)
+  end
+
+  def executed?(file, line)
+    lines = @executed_lines[file]
+    !lines.nil? && lines.include?(line)
+  end
+
+  def to_h
+    { "index" => @index, "built_files" => @built_files, "executed_lines" => @executed_lines }
+  end
+
+  private
+
+  def deep_freeze_index(index)
+    index.each_with_object({}) do |(file, lines), out|
+      frozen_lines = lines.each_with_object({}) do |(line, locs), inner|
+        inner[line] = locs.uniq.sort.freeze
+      end
+      out[file] = frozen_lines.freeze
+    end.freeze
+  end
+
+  def deep_freeze_executed(executed)
+    executed.each_with_object({}) do |(file, lines), out|
+      out[file] = lines.map(&:to_i).uniq.sort.freeze
+    end.freeze
+  end
+end

data/lib/evilution/coverage/map_builder.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "coverage"
+require "stringio"
+require_relative "../coverage"
+require_relative "map"
+require_relative "recorder"
+
+# Builds a per-example coverage Map by running the given spec files under
+# ::Coverage (lines mode) with the Recorder installed as an around(:each)
+# hook. The run happens in a FORKED CHILD so the global ::RSpec.configure
+# hook, ::RSpec.world mutation, and ::Coverage state never leak into the
+# calling process; the parent receives only the serialized map over a pipe.
+class Evilution::Coverage::MapBuilder
+  LOCATION_LINE_SUFFIX = /\A(.+?)(:\d+(?::\d+)*)\z/
+
+  # RSpec reports example locations relative to its run dir as "./spec/x.rb:5".
+  # Store them ABSOLUTE (path expanded against the project root, line suffix
+  # preserved) so they replay regardless of the per-mutation run's CWD --
+  # Integration::RSpec#resolve_target passes absolute targets through unchanged.
+  def self.absolute_location(raw, root)
+    match = LOCATION_LINE_SUFFIX.match(raw)
+    path, suffix = match ? [match[1], match[2]] : [raw, ""]
+    "#{File.expand_path(path, root)}#{suffix}"
+  end
+
+  def initialize(spec_files:, target_files:, project_root: Evilution::PROJECT_ROOT)
+    @spec_files = spec_files
+    @target_files = target_files
+    @project_root = project_root.to_s
+  end
+
+  def call
+    read_io, write_io = IO.pipe
+    read_io.binmode
+    write_io.binmode
+    pid = fork do
+      read_io.close
+      Marshal.dump(build_in_child.to_h, write_io)
+      write_io.close
+      exit!(0)
+    end
+    write_io.close
+    payload = read_io.read
+    read_io.close
+    Process.wait(pid)
+    # Trust boundary: payload is a Marshal dump this process's own forked child
+    # produced over a private pipe -- same rationale as Channel::Frame.
+    Evilution::Coverage::Map.from_h(Marshal.load(payload))
+  end
+
+  private
+
+  # Runs entirely inside the forked child.
+  def build_in_child
+    recorder = Evilution::Coverage::Recorder.new(target_files: @target_files)
+    ::Coverage.start(lines: true) unless ::Coverage.running?
+    # The child inherited the parent's fully-loaded RSpec.world; wipe it so the
+    # nested runner executes ONLY @spec_files and never re-enters the host suite
+    # (which would recursively fork this builder).
+    reset_world
+    install_hook(recorder)
+    ::RSpec::Core::Runner.run(@spec_files, StringIO.new, StringIO.new)
+    recorder.to_map(built_files: @target_files)
+  end
+
+  def reset_world
+    ::RSpec.respond_to?(:clear_examples) ? ::RSpec.clear_examples : ::RSpec.reset
+  end
+
+  def install_hook(recorder)
+    root = @project_root
+    ::RSpec.configure do |config|
+      config.around(:each) do |example|
+        location = Evilution::Coverage::MapBuilder.absolute_location(
+          example.metadata[:location].to_s, root
+        )
+        recorder.around_example(location) { example.run }
+      end
+    end
+  end
+end

data/lib/evilution/coverage/map_store.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "../coverage"
+require_relative "map"
+require_relative "digest"
+
+# Disk cache for a per-example coverage Map under .evilution/coverage/, keyed by
+# a per-file content digest so a map survives across runs and invalidates one
+# file at a time.
+#
+# load is partial: it returns a Map pruned to the files whose on-disk content
+# still matches the cached digest. A stale or deleted file is dropped (so its
+# `built?` is false and the caller falls back to lexical targeting) while every
+# fresh file stays queryable. A missing or corrupt cache returns nil, signalling
+# the caller to rebuild from scratch.
+class Evilution::Coverage::MapStore
+  DEFAULT_ROOT = ".evilution/coverage"
+  CACHE_FILE = "map.json"
+
+  def initialize(root: DEFAULT_ROOT, digest: Evilution::Coverage::Digest.new)
+    @root = root
+    @digest = digest
+  end
+
+  def save(map, source_files)
+    payload = { "digests" => digests_for(source_files), "map" => map.to_h }
+    FileUtils.mkdir_p(@root)
+    File.write(cache_path, JSON.generate(payload))
+  end
+
+  def load(source_files)
+    payload = read_payload
+    return nil unless payload
+
+    cached_digests = payload["digests"] || {}
+    fresh = source_files.select { |file| fresh?(file, cached_digests) }
+    pruned_map(payload["map"] || {}, fresh)
+  end
+
+  # Source files whose on-disk content no longer matches the cache (changed,
+  # deleted, or never cached) -- the caller rebuilds these. Every file is stale
+  # when there is no cache at all.
+  def stale_files(source_files)
+    payload = read_payload
+    return source_files.dup unless payload
+
+    cached_digests = payload["digests"] || {}
+    source_files.reject { |file| fresh?(file, cached_digests) }
+  end
+
+  private
+
+  def fresh?(file, cached_digests)
+    cached = cached_digests[file]
+    !cached.nil? && cached == @digest.for_file(file)
+  end
+
+  def pruned_map(raw_map, fresh_files)
+    index = (raw_map["index"] || {}).slice(*fresh_files)
+    built = (raw_map["built_files"] || []) & fresh_files
+    executed = (raw_map["executed_lines"] || {}).slice(*fresh_files)
+    Evilution::Coverage::Map.from_h(
+      "index" => index, "built_files" => built, "executed_lines" => executed
+    )
+  end
+
+  def digests_for(source_files)
+    source_files.each_with_object({}) do |file, out|
+      digest = @digest.for_file(file)
+      out[file] = digest unless digest.nil?
+    end
+  end
+
+  def read_payload
+    return nil unless File.file?(cache_path)
+
+    JSON.parse(File.read(cache_path))
+  rescue JSON::ParserError, Errno::ENOENT
+    nil
+  end
+
+  def cache_path
+    File.join(@root, CACHE_FILE)
+  end
+end

data/lib/evilution/coverage/recorder.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "../coverage"
+require_relative "map"
+
+# Wraps each example with a before/after coverage diff and attributes the
+# newly-executed lines (in target files only) to that example's location.
+# coverage_source is injected for testability; in production it is
+# -> { ::Coverage.peek_result }.
+class Evilution::Coverage::Recorder
+  def initialize(target_files:, coverage_source: -> { ::Coverage.peek_result })
+    @target_files = target_files.to_a
+    @coverage_source = coverage_source
+    @index = Hash.new { |h, file| h[file] = Hash.new { |g, line| g[line] = [] } }
+    @executed = Hash.new { |h, file| h[file] = [] }
+  end
+
+  def around_example(example_location)
+    before = snapshot
+    result = yield
+    after = snapshot
+    attribute(before, after, example_location)
+    result
+  end
+
+  def to_map(built_files:)
+    Evilution::Coverage::Map.new(
+      index: materialize(@index),
+      built_files: built_files,
+      executed_lines: @executed.transform_values(&:uniq)
+    )
+  end
+
+  private
+
+  def snapshot
+    @coverage_source.call || {}
+  end
+
+  def attribute(before, after, example_location)
+    @target_files.each do |file|
+      after_counts = line_counts(after[file])
+      next unless after_counts
+
+      record_executed(file, after_counts)
+      record_increases(file, line_counts(before[file]) || [], after_counts, example_location)
+    end
+  end
+
+  # Every line with a non-zero count in the after-snapshot has run at least once
+  # by now -- including lines covered only at load (a `def` line is already > 0
+  # in the first example's after-snapshot). Recording them lets the Map tell a
+  # load-covered line from a line that never ran.
+  def record_executed(file, after_counts)
+    after_counts.each_with_index do |count, idx|
+      next if count.nil? || count.zero?
+
+      @executed[file] << (idx + 1)
+    end
+  end
+
+  # Credit example_location with every line whose execution count rose between
+  # the before/after snapshots (a newly-executed, executable line).
+  def record_increases(file, before_counts, after_counts, example_location)
+    after_counts.each_with_index do |count, idx|
+      next if count.nil? || count.zero?
+      next unless count > (before_counts[idx] || 0)
+
+      @index[file][idx + 1] << example_location
+    end
+  end
+
+  # Coverage.peek_result yields per-file line counts either as a bare array
+  # (legacy Coverage.start) or as a { lines: [...] } hash (Coverage.start with
+  # lines:/branches:/methods: modes). Normalize to the bare counts array.
+  def line_counts(entry)
+    entry.is_a?(Hash) ? entry[:lines] : entry
+  end
+
+  def materialize(index)
+    index.each_with_object({}) do |(file, lines), out|
+      out[file] = lines.each_with_object({}) { |(line, locs), inner| inner[line] = locs }
+    end
+  end
+end