evilution 1.1.0 → 1.3.0

data/README.md

@@ -21,9 +21,15 @@ Add to `Gemfile`:
 gem "evilution", group: :test
 ```
 
-Then: `bundle install`
+Then:
+```shell
+bundle install
+```
 
-Or standalone: `gem install evilution`
+Or standalone:
+```shell
+gem install evilution
+```
 
 Requires `prism >= 1.5, < 2`. Older Rails apps (e.g. Rails 7.1 pins `prism 0.19`) must upgrade prism — the gemspec constraint forces bundler to resolve a compatible 1.x version. If your app pins `prism 2.x`, bundler will reject the install until evilution widens its upper bound.
 
@@ -88,7 +94,7 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 | `init`               | Generate `.evilution.yml` config file               |         |
 | `version`            | Print version string                                |         |
 | `subjects [files]`   | List mutation subjects with locations and counts    |         |
-| `tests list [files]` | List spec files mapped to source files              |         |
+| `tests list [files]` | List the spec files `run` would use for each source (layout, `spec_mappings`, `spec_pattern`) |         |
 | `session list`       | List saved session results                          |         |
 | `session show FILE`  | Display detailed session results                    |         |
 | `session diff A B`   | Compare two sessions (fixed/new/persistent)         |         |
@@ -104,6 +110,7 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 | `-t`, `--timeout N`          | Integer | 30           | Per-mutation timeout in seconds.                   |
 | `-f`, `--format FORMAT`      | String  | `text`       | Output format: `text`, `json`, or `html`.         |
 | `--target EXPR`              | String  | _(none)_     | Only mutate matching methods. Supports method name (`Foo::Bar#calculate`), class (`Foo`), namespace wildcards (`Foo::Bar*`), method-type selectors (`Foo#`, `Foo.`), descendants (`descendants:Foo`), and source globs (`source:lib/**/*.rb`). |
+| `--output FILE`              | String  | _(stdout)_   | Write the report to FILE instead of stdout. Useful when a preloaded spec helper writes to stdout on exit. |
 | `--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`, which also resolves non-mirrored (`spec/unit`, `test/unit`), dir-grouped (`test/unit/<class>/*_test.rb`), and flat `test_`-prefixed (`test/test_connection_pool_timed_stack.rb`) layouts. |
 | `--spec-dir DIR`             | String  | _(none)_     | Include all `*_spec.rb` files in DIR recursively. Composable with `--spec`. |
@@ -128,6 +135,7 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 | `--isolation MODE`           | String  | `auto`       | Isolation strategy: `auto`, `fork`, or `in_process`. `auto` selects `fork` for Rails projects and packaged gems (`*.gemspec`), `in_process` otherwise. See [docs/isolation.md](docs/isolation.md). |
 | `--preload FILE`             | String  | _(auto)_     | File to require in parent before forking workers. Auto-detect chain for Rails projects: `spec/rails_helper.rb` → `spec/spec_helper.rb` → `test/test_helper.rb`. For non-Rails gems: `spec/spec_helper.rb` → `test/test_helper.rb` → `test/helper.rb`, falling back to the gem entry `lib/<gem>.rb` (with a warning naming the searched paths). Pass `--no-preload` to opt out. |
 | `--no-preload`               | Boolean | _(enabled)_  | Disable parent-process preload.                     |
+| `--warmup NAME`              | String  | `none`       | After preload, warm lazily-initialised framework state once in the parent: `none` or `rails`. See [Warming up Rails before forking](#warming-up-rails-before-forking). |
 | `--skip-heredoc-literals`    | Boolean | false        | Skip all string literal mutations inside heredocs.  |
 | `--show-disabled`            | Boolean | false        | Report mutations skipped by `# evilution:disable` comments. |
 | `--fallback-full-suite`      | Boolean | false        | When no matching spec/test resolves for a mutation, run the whole test suite instead of marking it `:unresolved` and skipping. |
@@ -157,7 +165,7 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 
 Two profiles ship out of the box:
 
-- **`default`** — the 80 stable operators registered in `Mutator::Registry.default`. Suitable for everyday CI runs; balances coverage signal against survivor noise.
+- **`default`** — the 111 stable operators registered in `Mutator::Registry.default`. Suitable for everyday CI runs; balances coverage signal against survivor noise.
 - **`strict`** — adds extra truthiness mutators on top of `default`. Currently `PredicateToNil` (replaces every `x.predicate?` call with `nil` to surface tests that only assert truthiness rather than exact return values). Use for pre-merge audits where you want maximum sensitivity at the cost of more survivors.
 
 Set via `--profile=strict`, the `--strict` shortcut, or `profile: strict` in `.evilution.yml`.
@@ -167,9 +175,23 @@ Set via `--profile=strict`, the `--strict` shortcut, or `profile: strict` in `.e
 | Code | Meaning                                       | Agent action                          |
 |------|-----------------------------------------------|---------------------------------------|
 | 0    | Mutation score meets or exceeds `--min-score` | Success. No action needed.            |
-| 1    | Mutation score below `--min-score`            | Parse output, fix surviving mutants.  |
+| 1    | Mutation score below `--min-score`, or a target file resolved to no spec | Parse output, fix surviving mutants.  |
 | 2    | Tool error (bad config, parse failure, etc.)  | Check stderr, fix invocation.         |
 
+`min_score` defaults to `0.0`, so **no score gate is armed unless you set one**. The `Result:` line says so rather than implying a threshold nobody configured:
+
+```
+$ evilution run lib/half_tested.rb              # no gate
+Result: 66.67% (no minimum score set)           # exit 0
+
+$ evilution run lib/half_tested.rb --min-score 0.8
+Result: FAIL (score 66.67% < 80.00%)            # exit 1
+```
+
+Evilution owns the exit status: `--preload` loads the project's own spec helper into the parent process, and an at-exit hook it installs (SimpleCov calls `exit` with its own status when coverage is below the minimum) would otherwise replace the status evilution computed (GH #1608).
+
+The printed verdict and the exit code always use the same threshold. Previously the line was printed against a hard-coded 80% that the exit code did not share, so a failing-looking run still exited 0 (GH #1604).
+
 ## Configuration
 
 Generate default config: `bundle exec evilution init`
@@ -187,6 +209,7 @@ schema_version: 1            # opts into strict validation (rejects unknown keys
 # isolation: auto          # auto | fork | in_process (auto selects fork for Rails + gems)
 # canary: true             # proof-of-life synthetic mutation at session start (false to skip)
 # preload: null            # path to preload before forking; false to disable; auto-detects for Rails + gems
+# warmup: none            # rails: warm I18n, routes, assets and templates once after preload (fork isolation)
 # skip_heredoc_literals: false  # skip string literal mutations inside heredocs (recommended for Rails: heredoc SQL/templates rarely have test coverage)
 # show_disabled: false     # report mutations skipped by disable comments
 # baseline_session: null   # path to session file for HTML comparison
@@ -224,6 +247,7 @@ All keys recognised under `schema_version: 1`:
 | `timeout`                    | Integer                       | `30`                                   | Per-mutation timeout in seconds.                                                                                                         |
 | `format`                     | String                        | `text`                                 | Output format: `text`, `json`, `html`.                                                                                                   |
 | `target`                     | String / null                 | `null`                                 | Filter expression: method (`Foo#bar`), class (`Foo`), namespace (`Foo*`), descendants (`descendants:Foo`), source glob (`source:**/*.rb`). |
+| `output`                     | String                        | _(stdout)_                             | Write the report to this file instead of stdout.                                                                                         |
 | `min_score`                  | Float                         | `0.0`                                  | Minimum mutation score (0.0–1.0) for exit code 0.                                                                                        |
 | `integration`                | String                        | `rspec`                                | Test framework: `rspec`, `minitest`, or `test_unit`.                                                                                     |
 | `verbose`                    | Boolean                       | `false`                                | Verbose output (RSS/GC stats per phase, error details for errored mutations).                                                            |
@@ -245,6 +269,7 @@ All keys recognised under `schema_version: 1`:
 | `related_specs_heuristic`    | Boolean                       | `false`                                | Append related request/integration/feature/system specs for `includes(...)` mutations.                                                   |
 | `fallback_to_full_suite`     | Boolean                       | `false`                                | When no matching spec resolves, run the entire suite instead of marking the mutation `:unresolved`.                                      |
 | `preload`                    | String / Boolean / null       | `null`                                 | File to preload in parent before forking. `false` to disable. `null` to auto-detect for Rails projects and packaged gems.                |
+| `warmup`                     | String                        | `none`                                 | `rails` warms lazily-initialised Rails state once after preload so forks do not each pay it. `none` / `false` to skip.                  |
 | `spec_mappings`              | Hash&lt;String, String/Array&gt; | `{}`                                | Custom mapping from source path to spec path(s).                                                                                         |
 | `spec_pattern`               | String / null                 | `null`                                 | Glob restricting resolved spec candidates.                                                                                               |
 | `example_targeting`          | Boolean                       | `true`                                 | Per-mutation example-level targeting.                                                                                                    |
@@ -299,6 +324,8 @@ Schema:
     "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)",
+    "unresolved_target_files": "array of strings (optional) — target files that resolved to no spec at all; present only when non-empty, and the run fails when it is",
+    "infra_retried": "integer (optional) — mutations a parallel pass could not judge because the test process crashed on infrastructure, re-run serially afterwards; present only when non-zero",
     "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",
@@ -313,7 +340,20 @@ Schema:
       "duration": "float — seconds this mutation took, rounded to 4 decimals",
       "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)"
+      "suggestion": "string — actionable hint for surviving mutants (survived only)",
+      "neutral_reason": "object (optional, neutral only) — { kind: 'baseline_failure' | 'infra_error', detail: string|null — the failing spec file or the crash class; null when the run was given explicit --spec files and no single spec can be named }"
+    }
+  ],
+  "subjects": [
+    {
+      "name": "string      — subject name (e.g. 'Foo#bar')",
+      "file": "string      — relative path to source file",
+      "total": "integer    — mutations generated for this subject",
+      "killed": "integer   — mutations detected",
+      "verified": "integer — mutations that got a verdict (killed + survived + timed out)",
+      "survived": "integer — mutations that went undetected",
+      "score": "float      — killed / verified, 0.0 when nothing was verified, rounded to 4 decimals",
+      "reached": "boolean  — false when no mutation of this subject got a verdict at all"
     }
   ],
   "coverage_gaps": [
@@ -361,6 +401,10 @@ Sessions saved by `--save-session` (under `.evilution/results/*.json`) and consu
 
 Saved sessions also omit the per-status arrays (`killed`, `neutral`, `equivalent`, `unresolved`, `unparseable`, `timed_out`, `errors`) — only `survived` and `coverage_gaps` are persisted. The score, totals, and timestamps are stable for diff/compare consumers.
 
+#### stdout in JSON mode
+
+With `--format json`, stdout carries the JSON document and nothing else. Each mutation's test run writes to buffers evilution owns, whatever the isolation mode: under `in_process` the framework's configuration can outlive a single run — `--preload` builds it before isolation swaps `$stdout` — so the run claims RSpec's output and error streams outright rather than relying on RSpec to redirect them (GH #1627). Once the document is written, stdout is pointed at stderr, so anything a preloaded spec helper prints on the way out — SimpleCov's coverage report, for example — lands on stderr instead of after the document where it would leave `JSON.parse` with nothing to work with. `--output FILE` writes the document to a file and leaves stdout alone entirely.
+
 #### Schema versioning
 
 Every session and stdout JSON document carries a top-level `schema_version` integer (currently `1`). On read:
@@ -383,14 +427,70 @@ Compatibility policy for the `1.x` gem line:
 | `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          |
+| `neutral`    | Baseline tests already failed before mutation, or the test process crashed on infrastructure (DB lock, statement timeout) rather than on the mutation. Every neutral records which of the two, and the report groups them by it | 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). The resolver searches the `lib/`-mirrored path, common non-mirrored buckets (`spec/unit`, `spec/lib`, `test/unit`, `test/lib`), and the flat `test_`-prefixed Minitest/Test::Unit convention (`test/test_connection_pool_timed_stack.rb`), so a high unresolved rate usually means a genuinely missing or unconventionally-placed test; a run that leaves many mutations unresolved prints an unresolved-rate warning with a best-guess spec path per source file. They are reported separately so you can act on them (add a test, adjust test naming, pass `--spec`, or opt in to the full-suite fallback) without inflating the error count.
 
-## Mutation Operators (80 total)
+A *target file* that resolves to no test at all is a stronger condition than an individual unresolved mutation, and is reported on its own terms: evilution names the file and **fails the run**, whatever the mutations it did measure scored. Without this, adding one well-tested file to the command dilutes the unresolved rate and the untested file disappears behind a `PASS` (GH #1603):
+
+```
+$ evilution run app/services/untested.rb app/services/well_tested.rb
+Mutations: 98 total, 82 killed, 0 survived, 0 timed out, 2 neutral, 14 unresolved
+Score: 100.00% (82/82)
+! 1 of 2 target files has no resolvable spec — it was never tested:
+    app/services/untested.rb
+Result: FAIL (1 target file has no resolvable spec)
+$ echo $?
+1
+```
+
+The check covers files evilution found something to mutate in; a file it produced no mutations for (a constants-only file, say) is not reported. `--fallback-full-suite` runs such a file against the whole suite instead, so nothing goes untested and nothing is reported. The file list is also in JSON output under `summary.unresolved_target_files`.
+
+### Survivor Confirmation
+
+Per-mutation targeting runs a subset of a spec file's examples, chosen by matching the enclosing method's name against example bodies. That match keys on identifier text, so it can miss the example that would have caught a mutation — and the mutation is then reported as a survivor the suite actually covers. A survivor nobody can reproduce is worse than a missed kill: it sends the reader to write a test that is already there (GH #1624).
+
+Before any survivor is reported, it is therefore re-run against the whole resolved spec file, and that run is the one reported. Only survivors pay for the extra run, and only where the targeted subset was narrower than the file; a mutation the targeted examples already killed is never re-run.
+
+On evilution's own `lib/evilution/reporter/json/subjects.rb` this moved the reported score from 74.19% with 8 survivors to 93.55% with 2 — the six that disappeared were killed by an example in the same file all along, and the run now agrees with `--no-example-targeting` instead of contradicting it.
+
+### Neutral Mutations
+
+Neutral covers two unrelated situations that want opposite responses: a spec file that was already red before any mutation ran, and a test process that died on infrastructure rather than on the mutation. Each neutral records which, and the report groups by it, naming the spec or the error class (GH #1606):
+
+```
+Score: 100.00% (10/10 verified of 17 mutations, 7 neutral)
+
+Neutral mutations (7, not verified):
+  baseline already failing (spec/tally_spec.rb):
+    arithmetic_replacement: lib/tally.rb:9
+    integer_literal: lib/tally.rb:9
+```
+
+The score line names the remainder whenever the run left mutations out of the denominator, because full marks over a fraction of a run otherwise reads as a verdict on all of it. A clean run still prints the plain `Score: 100.00% (17/17)`.
+
+Those seven mutations were survivors until the spec file went red — a neutral of this kind is a hidden coverage gap, not a clean bill of health. JSON output carries `neutral_reason` as `{ kind, detail }` on neutral entries that have one; `detail` is null where no single spec can be named (an explicit `--spec` run), and the field is absent on a result recorded without a reason, which the text report shows as `reason not recorded`.
+
+### Per-Subject Scores
+
+The run's score is computed per file, and test selection resolves per file too, so a well-tested file that gains new untested methods still reports 100% — the number only ever describes what the resolved spec reaches (GH #1605). Every report therefore breaks the run down per subject, and the text report names the subjects the file-level score does not speak for:
+
+```
+Mutations: 33 total, 7 killed, 0 survived, 0 timed out, 26 unresolved
+Score: 100.00% (7/7)
+
+Subjects needing attention (2 subjects in 1 file):
+  lib/helper.rb
+    #summary_for  0.00%  (0/17)  nothing reached this subject
+    #total_for  0.00%  (0/9)  nothing reached this subject
+```
+
+A subject is listed when something survived, or when nothing reached it at all — zero verdicts, every mutation unresolved or neutral. Fully-killed subjects are not listed, so the section stays actionable. JSON output carries every subject under `subjects`, whether or not it needs attention, so a CI step can assert on `reached` or on a per-subject `score`.
+
+## Mutation Operators (111 total)
 
 Each operator name is stable and appears in JSON output under `survived[].operator`.
 
@@ -423,6 +523,29 @@ Each operator name is stable and appears in JSON output under `survived[].operat
 | `method_call_removal` | Remove method calls, keep receiver | `obj.foo(x)` -> `obj` |
 | `argument_removal` | Remove individual arguments | `foo(a, b)` -> `foo(b)` |
 | `argument_nil_substitution` | Replace arguments with `nil` | `foo(a, b)` -> `foo(nil, b)` |
+| `call_to_nil` | Replace a method call with `nil` (skips void statements, receivers of another call, and attribute or index writes) | `user.name` -> `nil` |
+| `safe_navigation_removal` | Replace `&.` with a plain call (skips `self` and literal receivers) | `user&.name` -> `user.name` |
+| `attribute_write_to_read` | Replace an attribute or index write with the matching read (skips writes `statement_deletion` already removes) | `a.foo = b` -> `a.foo`, `a[i] = b` -> `a[i]` |
+| `argument_propagation` | Replace a call with its only positional argument (skips operator methods, attribute writes and void statements) | `normalize(value)` -> `value` |
+| `argument_list_removal` | Drop a call's whole argument list, keeping any block (skips operator methods and attribute writes) | `foo(a, b)` -> `foo`, `foo(a, &b)` -> `foo(&b)` |
+| `symbol_to_proc_replacement` | Apply the `send_mutation` and `collection_replacement` selector tables to a symbol block-pass (skips alias swaps) | `map(&:to_s)` -> `map(&:to_i)` |
+| `dynamic_dispatch_resolution` | Resolve `send` / `__send__` / `public_send` with a literal symbol into a direct call, only where visibility checks can differ | `obj.send(:m, a)` -> `obj.m(a)` |
+| `keyword_argument_removal` | Drop one `key: value` argument at a call site (keeps `**opts`; skips a lone keyword) | `f(a: 1, b: 2)` -> `f(b: 2)` |
+| `double_negation_removal` | Replace a double negation with its operand | `!!x` -> `x` |
+| `regexp_anchor_to_predicate` | Rewrite a match against an anchored literal regexp as a prefix / suffix predicate (skips `match?` with `\A` / `\z`, an exact equivalent) | `x =~ /^foo/` -> `x.start_with?("foo")` |
+| `reduce_to_sum` | Rewrite a `+` reduction (`reduce` / `inject` with `:+` or `&:+`) into `sum` | `xs.reduce(:+)` -> `xs.sum`, `xs.inject(0, :+)` -> `xs.sum(0)` |
+| `array_coercion_to_literal` | Replace an `Array()` coercion with an array literal | `Array(x)` -> `[x]` |
+| `to_i_to_integer` | Replace lenient `to_i` with strict `Integer()` (skips numeric literal receivers) | `x.to_i` -> `Integer(x)`, `x.to_i(16)` -> `Integer(x, 16)` |
+| `coercion_emptying` | Replace a conversion with an empty value of its type (`to_a` / `to_ary`, `to_h` / `to_hash`, `to_s` / `to_str`) | `x.to_s` -> `""`, `x.to_h` -> `{}` |
+| `const_get_to_constant_path` | Resolve `const_get` with a literal symbol into a constant path | `X.const_get(:Y)` -> `X::Y` |
+| `proc_to_lambda` | Turn `proc { }` / `Proc.new { }` into `lambda { }` (arity checks, local `return`) | `proc { \|x\| x }` -> `lambda { \|x\| x }` |
+| `dig_to_fetch_chain` | Make the first step of a multi-key `dig` strict | `x.dig(a, b)` -> `x.fetch(a).dig(b)` |
+| `inequality_to_negated_identity` | Rewrite `!=` with the stricter `eql?` / `equal?` (skips nil, boolean and symbol literals) | `a != b` -> `!a.eql?(b)`, `!a.equal?(b)` |
+| `binary_operand_promotion` | Replace an arithmetic or bitwise expression with one of its operands (skips integer identities and void statements) | `a + b` -> `a`, `b` |
+| `receiver_constructor_swap` | Swap `Date` / `DateTime` / `Time.parse` for a stricter sibling constructor on the same receiver | `Date.parse(s)` -> `Date.iso8601(s)`, `Date.strptime(s)`, ... |
+| `block_body_to_nil` | Replace a block body with `nil`, keeping the iteration (skips `loop` and endless `cycle` / `cycle(nil)`, which would hang) | `xs.each { \|x\| log(x) }` -> `xs.each { \|x\| nil }` |
+| `block_body_to_raise` | Replace a block body with `raise` to prove the block is invoked (skips bodies with a `rescue` clause, which would swallow it) | `xs.each { \|x\| log(x) }` -> `xs.each { \|x\| raise }` |
+| `block_body_promotion` | Replace a call with its parameter-less block body, run once (skips blocks with parameters or a `rescue` / `ensure` clause) | `Base.transaction { save! }` -> `save!`, `3.times { poll }` -> `poll` |
 | `keyword_argument` | Remove keyword defaults/params | `def foo(bar: 42)` -> `def foo(bar:)` |
 | `multiple_assignment` | Remove targets or swap order | `a, b = 1, 2` -> `b, a = 1, 2` |
 | `block_removal` | Remove blocks from method calls | `items.map { \|x\| x * 2 }` -> `items.map` |
@@ -464,6 +587,14 @@ Each operator name is stable and appears in JSON output under `survived[].operat
 | `regex_capture` | Swap or nil-ify capture refs | `$1` -> `$2`, `$1` -> `nil` |
 | `loop_flip` | Swap while/until loops | `while cond` -> `until cond` |
 | `loop_body_to_raise` | Replace a loop body with `raise` | `while c; body; end` -> `while c; raise; end` |
+| `method_body_to_raise` | Replace a whole method body with `raise` | `def foo; body; end` -> `def foo; raise; end` |
+| `method_body_to_super` | Replace a method body with bare `super` where a super target exists | `def foo; body; end` -> `def foo; super; end` |
+| `typed_default_return` | Replace a single-expression body with the empty value of its inferred type | `def names(u); u.map(&:name); end` -> `def names(u); []; end` |
+| `block_parameter_drop` | Drop a block's single parameter | `users.each { |u| touch(u) }` -> `users.each { touch(u) }` |
+| `optional_parameter_to_required` | Drop an optional positional parameter's default | `def f(a = 1)` -> `def f(a)` |
+| `optional_default_injection` | Overwrite an optional parameter with its own default at the top of the body | `def f(a = 1); body; end` -> `def f(a = 1); a = 1; body; end` |
+| `block_destructuring_expansion` | Flatten a destructuring group in a block's parameters | `pairs.each_with_index { |(k, v), i| use(k, v, i) }` -> `pairs.each_with_index { |k, v, i| use(k, v, i) }` |
+| `forwarding_super_to_explicit` | Give a forwarding `super` an empty argument list | `def f(a); super; end` -> `def f(a); super(); end` |
 | `string_interpolation` | Replace interpolation content with nil | `"hello #{name}"` -> `"hello #{nil}"` |
 | `retry_removal` | Remove retry statements | `retry` -> `nil` |
 | `case_when` | Remove/replace case/when branches | Remove `when` branch, drop one condition from `when a, b`, body -> `nil`, empty body -> `raise`, remove `else` |
@@ -520,6 +651,12 @@ The `evilution-mutate` tool accepts a `verbosity` parameter to control response
 
 Use `minimal` when context window budget is tight and you only need to see what survived. The trimmed `errors` sample (each entry: `error_message`, `error_class`, location, plus the first 5 backtrace lines) is added so a partly-broken run is still self-diagnosable without escalating verbosity. Use `full` when you need to inspect killed/neutral/equivalent entries for debugging.
 
+What survives trimming matters when you are deciding whether to trust a score:
+
+- `neutral` entries — and with them each `neutral_reason` — are dropped at `summary` and `minimal`. Use `full` to see why mutations were neutralised.
+- `subjects` is kept at `full` and `summary`, and dropped at `minimal`, which keeps only `summary` and `survived`.
+- Everything inside `summary` survives at every level, including `unresolved_target_files`, `infra_retried` and the `neutral` count — so even a `minimal` response still says whether a target file went untested and how much of the run the score covers.
+
 ### Enriched Survived Entries
 
 Unlike `evilution --format json`, every survived entry returned by `evilution-mutate` carries extra fields so the agent can act without a second round-trip:
@@ -605,7 +742,7 @@ Per-tool placement:
 - **`evilution-session` `list`** — `{ "schema_version": Integer, "sessions": Array<{ file, timestamp, total, killed, survived, score, duration }> }`. Sessions are reverse-chronological; the array is filtered by `limit` when provided.
 - **`evilution-session` `show`** — the parsed session JSON document, exactly as written under `.evilution/results/*.json`. Field reference: see [Session JSON files](#session-json-files).
 - **`evilution-session` `diff`** — `{ "schema_version": Integer, "summary": { base_score, head_score, score_delta, base_survived, head_survived, base_total, head_total, base_killed, head_killed }, "fixed": Array, "new_survivors": Array, "persistent": Array }`. The mutation arrays carry the same per-mutation fields the session `survived` list uses (`operator`, `file`, `line`, `subject`, `diff`).
-- **`evilution-info` `subjects`** — `{ "schema_version": Integer, "subjects": Array<{ name, file, line, mutations }>, "total_subjects": Integer, "total_mutations": Integer }`.
+- **`evilution-info` `subjects`** — `{ "schema_version": Integer, "subjects": Array<{ name, file, line, mutations }>, "total_subjects": Integer, "total_mutations": Integer }`. Discovery only: this lists what *can* be mutated. The `subjects` array in a run's report is a different shape, carrying what each subject scored.
 - **`evilution-info` `tests`** — `{ "schema_version": Integer, "specs": Array<{ source, spec }>, "unresolved": Array<String>, "total_sources": Integer, "total_specs": Integer }`.
 - **`evilution-info` `environment`** — `{ "schema_version": Integer, "version": String, "ruby": String, "config_file": String|null, ... }` mirroring the effective `Evilution::Config`.
 - **`evilution-info` `statuses`** — `{ "schema_version": Integer, "statuses": Array<{ name, meaning, in_score }> }`.
@@ -636,7 +773,7 @@ When a parameter, action, or output field on the public MCP contract is deprecat
 bundle exec evilution run lib/ --format json --min-score 0.8
 ```
 
-Parse JSON output. Exit code 0 = pass, 1 = surviving mutants to address.
+Parse JSON output. Exit code 0 = pass, 1 = fail — either the score is below `--min-score`, or a target file resolved to no spec and was never tested (`summary.unresolved_target_files` names them). Without `--min-score` no score gate is armed; the run still fails on an untested target file.
 
 ### 2. PR / changed-lines scan (fast feedback)
 
@@ -691,8 +828,23 @@ bundle exec evilution run lib/models/user.rb lib/models/account.rb lib/models/or
 
 Pass multiple file paths on a single invocation to amortise startup cost. The framework (Rails, Sorbet, etc.) and the `preload` chain (`spec/rails_helper.rb` → `spec/spec_helper.rb` → `test/test_helper.rb`) load **once** in the parent process. When `--isolation=fork` is selected (the default `--isolation=auto` resolves to `fork` on Rails projects and packaged gems), every subsequent mutation across all files forks from that warmed parent — materially faster than scripting a `for f in ...; do bundle exec evilution run "$f"; done` loop, which pays the bootstrap per file. With `--isolation=in_process` (default for non-Rails, non-gem projects under `auto`), there is no per-mutation fork, but the parent-process boot still runs once instead of N times. Per-file paths and line numbers are preserved in the report (`survived[].file`, HTML grouping by source file).
 
+### What to read before acting on a score
+
+A score describes only the mutations that got a verdict. Four fields say what it leaves out, and each points at a different action:
+
+| Field | Meaning | What to do |
+|---|---|---|
+| `summary.unresolved_target_files` | A file you named resolved to no spec and was never tested; the run fails on this alone | Write a spec, pass `--spec`, or map it in `spec_mappings` — do not trust the score until this is empty |
+| `subjects[].reached == false` | Mutations were generated for that method but none got a verdict | The method is untested even where its file scores well; start here rather than with `survived[]` |
+| `neutral[].neutral_reason.kind == "baseline_failure"` | The spec file was already red before any mutation ran; `detail` names it | Fix that spec first — nothing about these mutations is measurable until it is green |
+| `neutral[].neutral_reason.kind == "infra_error"` | The test process crashed on infrastructure (DB lock, timeout); `detail` names the class | Not a coverage gap. Give parallel workers their own database, or run `-j 1` |
+
+`summary.infra_retried` reports how many mutations had to be re-run serially because of the last case; a large number means the parallel run was fighting shared infrastructure rather than measuring your suite.
+
 ### 6. Fixing surviving mutants
 
+Every entry in `survived[]` has already been re-run against the whole resolved spec file, so it is a gap the suite genuinely does not cover rather than an artefact of per-mutation example targeting.
+
 For each entry in `survived[]`:
 1. Read `file` at `line` to understand the code context
 2. Read `operator` to understand what was changed
@@ -720,6 +872,17 @@ bundle exec evilution mutate lib/aasm/base.rb --spec spec/unit/event_spec.rb,spe
 bundle exec evilution mutate lib/aasm/base.rb --fallback-full-suite
 ```
 
+To make the mapping permanent, declare it once in `.evilution.yml` under `spec_mappings`; the run, its baseline and `tests list` all honour it. `evilution tests list <file>` prints exactly the spec files a run would use, so it is the quick way to check a mapping before spending a run on it:
+
+```yaml
+spec_mappings:
+  lib/aasm/base.rb:
+    - spec/unit/event_spec.rb
+    - spec/unit/callbacks_spec.rb
+```
+
+Without `--fallback-full-suite` an unresolved source is also left out of the baseline, which does not run the whole test directory for it.
+
 ### Long Minitest fork runs — not a hang
 
 Minitest projects under `--isolation=fork` re-bootstrap the test environment (`test_helper.rb`, plugins, runnable state) once per mutation. On constant-heavy files (e.g. Shopify/liquid's `lib/liquid/lexer.rb`, ~270 mutations) the wall-clock cost is dominated by that per-fork bootstrap and any mutations that hit a `--timeout` rather than killing the test fast. A single-worker run (`-j 1`) on a few hundred mutations can take 4+ minutes; combined with `--no-progress` and a non-TTY stderr (CI, redirected logs) the run looks silent the entire time.
@@ -733,7 +896,7 @@ RUBYOPT="-Itest" bundle exec evilution mutate lib/<file>.rb \
   --spec test/<dir>/<file>_test.rb
 ```
 
-`-j 4` parallelises across workers, `-t 10` caps any mutation that pathologically loops at 10 s. Expect the run to print progress only when stderr is a TTY (use `bundle exec evilution mutate ... 2>&1 | tee log` to get progress while still saving output). The historical "Minitest fork hangs on liquid" report (EV-blnq / GH #1211) turned out to be a slow run + silent UX, not an actual deadlock — the worker logs show steady forward progress when captured via `--quiet-children --quiet-children-dir DIR`.
+`-j 4` parallelises across workers, `-t 10` caps any mutation that pathologically loops at 10 s. On a Rails app, add `--warmup rails` so each fork does not re-initialise I18n, routes and templates on its first request (see [Warming up Rails before forking](#warming-up-rails-before-forking)). Expect the run to print progress only when stderr is a TTY (use `bundle exec evilution mutate ... 2>&1 | tee log` to get progress while still saving output). The historical "Minitest fork hangs on liquid" report (GH #1211) turned out to be a slow run + silent UX, not an actual deadlock — the worker logs show steady forward progress when captured via `--quiet-children --quiet-children-dir DIR`.
 
 ### 8. CI gate
 
@@ -742,7 +905,9 @@ bundle exec evilution run lib/ --format json --min-score 0.8 --quiet
 # Exit code 0 = pass, 1 = fail, 2 = error
 ```
 
-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.
+Exit 1 covers two conditions: the score missed `--min-score`, and a target file that resolved to no spec. The second fails the run whether or not a score gate is set, so a CI step that names files explicitly cannot silently stop testing one of them.
+
+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. `--output FILE` is the alternative when a preloaded spec helper (SimpleCov, for example) writes to stdout on exit.
 
 ### 9. Regression tracking across runs (`compare`)
 
@@ -769,9 +934,32 @@ Output buckets:
 
 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.
 
+## Warming up Rails before forking
+
+Under `isolation: fork` the parent preloads once and every mutation runs in a fresh fork, which inherits only what the parent had already initialised. Rails initialises a lot lazily on a process's first request: loading locale files, building route helpers, resolving asset paths, compiling templates. Without a warm-up, every forked mutation whose tests make a request pays that cold start again, often several hundred milliseconds each.
+
+`warmup: rails` (or `--warmup rails`) does that initialisation once in the parent, right after the preload:
+
+- `I18n.eager_load!`
+- the route set's `url_helpers` (and `eager_load!` for lazily drawn routes on Rails 8)
+- an asset path lookup through the controller helpers
+- template precompilation, only if the [`actionview_precompiler`](https://github.com/jhawthorn/actionview_precompiler) gem is installed
+
+Each step is skipped if its library is not loaded, and skipped with a one-line note if it raises, so an app that does not fit a step still runs normally.
+
+Do not warm up by sending a real request from your preload (`Rails.application.call(...)`). Controller callbacks change process-global state that every fork then inherits: `I18n.locale`, gem request stores such as PaperTrail's, a session row in the database. Tests that depend on that state then fail in every fork, and evilution reports their mutations as killed. The steps above make no request and leave that state untouched.
+
 ## 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.
+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 [GH #814](https://github.com/marinazzio/evilution/issues/814)) so the mutation score is not polluted, but the wall-clock penalty remains.
+
+Because that contention only exists while several workers are running, those mutations are re-run one at a time once the pool is done, and the verdict from the quiet re-run is the one reported. Without it the neutral bucket moved with `-j` on identical input — the same files scoring 24 killed / 0 neutral at `-j 1` and 6 killed / 18 neutral at `-j 4` (GH #1607). The run says how much it had to redo:
+
+```
+! 18 mutations hit infrastructure errors under parallel workers; re-ran them serially.
+```
+
+The count is in JSON output as `summary.infra_retried`. Such a crash is also never written to the `--incremental` cache: the cache keeps no error class, so a cached `:killed` would be indistinguishable from a real one on the next run and would short-circuit both the demotion and the retry. A neutral from a failing baseline is never re-run — that is a real statement about the spec, not a missed verdict. The retry costs wall-clock time in proportion to the contention, which is another reason to give each worker its own database file:
 
 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:
 
@@ -816,7 +1004,7 @@ points — see [docs/architecture.md](docs/architecture.md).
 1. **Parse** — Prism parses Ruby files into ASTs with exact byte offsets
 2. **Extract** — Methods are identified as mutation subjects
 3. **Filter** — Disable comments, Sorbet `sig` blocks, and AST ignore patterns exclude mutations before execution
-4. **Mutate** — 80 operators produce text replacements at precise byte offsets (source-level surgery, no AST unparsing); heredoc literal text is skipped by default. Identical byte-mutations from different operators are deduplicated by `(file_path, mutated_source)` so the count is not inflated by overlap
+4. **Mutate** — 111 operators produce text replacements at precise byte offsets (source-level surgery, no AST unparsing); heredoc literal text is skipped by default. Identical byte-mutations from different operators are deduplicated by `(file_path, mutated_source)` so the count is not inflated by overlap
 5. **Isolate** — Mutations are applied to temporary file copies (never modifying originals); load-path redirection ensures `require` resolves the mutated copy. Default isolation is in-process for plain Ruby projects (no gemspec) and fork for Rails projects and packaged gems (auto-detected); `--isolation fork` forces forked child processes. Both sequential and parallel (`--jobs N`) modes respect the configured isolation strategy
 6. **Test** — The configured test framework (RSpec, Minitest, or Test::Unit) executes against the mutated source
 7. **Collect** — Source strings and AST nodes are released after use to minimize memory retention

data/docs/architecture.md

@@ -48,17 +48,52 @@ Everything lives under `lib/evilution/`.
 | `Config`, `Config::*` | Merge `.evilution.yml` + CLI flags + env, validate, freeze. | `config.rb`, `config/sources.rb`, `config/validators/*` |
 | `Runner`, `Runner::*` | Orchestrate the whole run. Each stage is its own collaborator. | `runner.rb`, `runner/*` |
 | `AST`, `Subject` | Prism parse, find method subjects, source surgery, pattern matching, heredoc spans. | `ast/parser.rb`, `ast/source_surgeon.rb`, `subject.rb` |
-| `Mutator`, `Mutator::Operator::*` | 80 operators (default profile) that emit byte-edits; registry + profiles. | `mutator/base.rb`, `mutator/registry.rb`, `mutator/operator/*` |
+| `Mutator`, `Mutator::Operator::*` | 111 operators (default profile) that emit byte-edits; registry + profiles. | `mutator/base.rb`, `mutator/registry.rb`, `mutator/operator/*` |
 | `Mutation` | An immutable mutation record (original/mutated sources, slice, location, parse status). | `mutation.rb` |
 | `SpecResolver`, `SpecSelector` | Map a source file to its covering spec files (layout heuristics + explicit mappings). | `spec_resolver.rb`, `spec_selector.rb` |
 | `Isolation::{Fork,InProcess}`, `ProcessSupervisor` | Run one mutation's tests in isolation; process-group lifecycle, sandboxing, TERM/KILL ladder. | `isolation/fork.rb`, `process_supervisor.rb` |
 | `Integration::{RSpec,Minitest,TestUnit}` | Apply a mutation and run the configured test framework; report the raw outcome. | `integration/base.rb`, `integration/rspec.rb` |
 | `Parallel::{Pool,WorkQueue}` | Fan mutations across worker processes for `jobs > 1`. | `parallel/pool.rb`, `parallel/work_queue.rb` |
 | `Result::{MutationResult,Summary}` | Per-mutation result + aggregated, scored summary. | `result/mutation_result.rb`, `result/summary.rb` |
+| `Result::{SubjectScore,SubjectScorer,NeutralReason}` | Score each subject on its own, and record why a neutral is neutral — what the file-level score does not speak for. | `result/subject_scorer.rb`, `result/neutral_reason.rb` |
 | `Reporter::{CLI,JSON,HTML,Suggestion}` | Render a `Summary` to text / JSON / HTML. | `reporter/*` |
 | `Session`, `Compare` | Persist runs to `.evilution/results/*.json`; diff two sessions. | `session/store.rb`, `compare.rb` |
 | `Coverage`, `Equivalent`, `Baseline`, `Cache`, `Hooks`, `MCP` | Coverage-based example targeting, equivalent-mutation detection, baseline capture, incremental cache, lifecycle hooks, MCP server. | respective dirs |
 
+## Require conventions
+
+Most directories under `lib/evilution/` have a parent file of the same name
+(`runner.rb` next to `runner/`) that declares the namespace. The rules:
+
+- **Every child requires its parent.** A file in `runner/` starts with
+  `require_relative "../runner"`, a file in `cli/commands/` with
+  `require_relative "../commands"`, and so on down the tree.
+- **A parent declares its namespace before requiring its children.** Usually
+  the class or module is defined first and children are required at the
+  bottom. Where the parent's own body needs its children loaded first (for
+  example a constant built from them), it opens with an empty declaration —
+  `class Evilution::CLI; end` — then requires the children, then defines the
+  rest. `cli.rb` and `integration/rspec/state_guard.rb` do this.
+- **Top-level files (`lib/evilution/*.rb`) are the exception.** Their parent is
+  `lib/evilution.rb`, the gem's entry point, which loads everything. A
+  top-level file that only needs the root module requires `version.rb`, which
+  defines `module Evilution` and nothing else. Only a file that genuinely needs
+  the whole gem requires `../evilution` — `runner.rb`, whose collaborators
+  reach every operator through `Mutator::Registry`.
+
+The parent require and the parent's own `require_relative` of its children
+form a cycle (`runner.rb` → `runner/canary.rb` → `runner.rb`). It is inert:
+Ruby does not load a file twice, so a re-entrant require of a file already
+being loaded returns immediately, and the namespace already exists because the
+parent declared it first. Reviews flagging it as a circular require can be
+answered with this section.
+
+Loading an arbitrary file on its own (`require "evilution/cli/command"` in a
+fresh process) is not a goal. The parent requires make most files work that
+way, but not all: a base class whose subclasses are required by the parent
+(`cli/command.rb`) cannot finish defining itself before those subclasses load.
+Load the gem through `require "evilution"`.
+
 ## Data flow, source → result
 
 Driven entirely by `Evilution::Runner#call` (`runner.rb:24`). Each step names the
@@ -87,7 +122,10 @@ class that owns it.
 5. **Spec resolution** — per subject, `SpecSelector#call(source_path)` picks specs
    (explicit `spec_files` → `spec_mappings` → `SpecResolver#resolve_specs` layout
    heuristics). Example-level targeting narrows to examples that reference the
-   mutated token (`ExampleFilter` / `CoverageExampleFilter`).
+   mutated token (`ExampleFilter` / `CoverageExampleFilter`). Separately,
+   `Runner::TargetSpecAudit` asks the same selector once per target file in the
+   parent, so a file that resolves to no spec at all is a fact the summary
+   carries rather than a handful of `unresolved` mutations.
 6. **Execute** — `Runner::MutationExecutor#call` picks a strategy by `config.jobs`:
    `Strategy::Sequential` for `jobs == 1`, `Strategy::Parallel` (via
    `Parallel::Pool` / `WorkQueue`) for `jobs > 1`. Either way each mutation reaches
@@ -103,13 +141,24 @@ class that owns it.
    guard / unresolved); the final symbol is chosen by
    `Isolation::Fork#classify_status`: `:timeout` → `:killed` (crash) →
    `:unresolved` → `:error` → `:survived` (tests passed) → default `:killed`.
-   A `NeutralizationPipeline` can reclassify results whose covering spec already
-   failed at baseline into `:neutral`.
+   A `NeutralizationPipeline` can reclassify results into `:neutral` — either
+   because the covering spec already failed at baseline (`Neutralizer::BaselineFailed`)
+   or because the test process crashed on infrastructure rather than on the
+   mutation (`Neutralizer::InfraError`). Each records a `Result::NeutralReason`,
+   since the two want opposite responses. A survivor is re-run against its whole
+   spec file before it is reported (`Integration::RSpec#confirm_survivor?`), so a
+   narrowed example set cannot invent one; after a parallel pass,
+   `MutationExecutor::InfraRetry` re-runs the infrastructure-neutralised
+   mutations serially, once the contention that caused them is gone.
 9. **Aggregate + report** — `Result::Summary` counts each status and computes
    `score = killed / score_denominator` (total minus error/neutral/equivalent/
    unresolved/unparseable). `Runner::ReportPublisher#publish` selects a reporter by
    `config.format` and writes it; `Session::Store` optionally persists the run.
-   `Commands::Run` maps `summary.success?(min_score:)` to exit code `0`/`1` (`2` on error).
+   `Summary#success?` is also false when a target file resolved to no spec, whatever
+   the score. `Commands::Run` maps `summary.success?(min_score:)` to exit code
+   `0`/`1` (`2` on error), and `CLI::ExitGuard` — installed by the executable before
+   anything can preload the project — has the final word on the process status, so a
+   preloaded spec helper's at-exit hook cannot replace it.
 
 ## How to add a new mutator
 

data/docs/isolation.md

@@ -48,7 +48,7 @@ framework must be loaded in the parent before forking — see [Automatic
 preload](#automatic-preload) — and `in_process` cannot preload them without
 polluting the host process. A non-Rails gem run under the old `in_process`
 default therefore produced 0 examples / 100% errors out of the box; defaulting
-gems to `fork` lets auto-preload fire (EV-z03y, PR #1375). A plain non-Rails,
+gems to `fork` lets auto-preload fire (PR #1375). A plain non-Rails,
 non-gem project (no gemspec) still defaults to `in_process`.
 
 The same hazard applies to any Ruby code that uses
@@ -92,12 +92,11 @@ order, falling back to the gem's library entry point (`lib/<gem>.rb`):
 When a gem is detected but none of those helpers exist, evilution prints a
 warning naming the locations it looked in and pointing at `--preload`, so a
 non-standard test layout reads as a fixable configuration issue rather than a
-silent 0% (EV-z03y, PR #1375).
+silent 0% (PR #1375).
 
 Minitest/Test::Unit helpers that `require "test_helper"` (or any non-relative
 `require "support/..."`) work without `-Itest`: evilution puts the test root
-on `$LOAD_PATH` for the preload just as the test runner would (EV-5hk5, PR
-#1373).
+on `$LOAD_PATH` for the preload just as the test runner would (PR #1373).
 
 No configuration needed.
 

data/exe/evil

@@ -3,4 +3,11 @@
 
 require "evilution"
 
-exit Evilution::CLI.new(ARGV).call
+# Installed before anything loads the project's spec helper, so this hook is the
+# last one standing and decides the process status — a helper's own at_exit hook
+# (SimpleCov calls exit with its own status) cannot replace it.
+# EV-g8ya / GH #1608.
+guard = Evilution::CLI::ExitGuard.new.install
+guard.status = Evilution::CLI.new(ARGV).call
+
+exit guard.status

data/exe/evilution

@@ -3,4 +3,11 @@
 
 require "evilution"
 
-exit Evilution::CLI.new(ARGV).call
+# Installed before anything loads the project's spec helper, so this hook is the
+# last one standing and decides the process status — a helper's own at_exit hook
+# (SimpleCov calls exit with its own status) cannot replace it.
+# EV-g8ya / GH #1608.
+guard = Evilution::CLI::ExitGuard.new.install
+guard.status = Evilution::CLI.new(ARGV).call
+
+exit guard.status

data/lib/evilution/ast/local_reads.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../ast"
+
+# Answers whether a scope body ever reads a given local name — the question an
+# operator asks before changing a parameter, since a parameter nothing reads
+# makes most such mutations behaviour-preserving.
+#
+# Scope-aware in the ways that matter here. A block shares the scope it is
+# written in, so a read inside one counts — unless the block binds the same name
+# itself, as a parameter or a block-local, in which case the read is of the
+# block's own variable. A nested def opens a scope of its own, where a local of
+# the same name is unrelated. A write is not a read.
+#
+# Shadowing is settled by Prism's own answer rather than by inspecting each
+# block's parameter list: a LocalVariableReadNode carries the number of scopes
+# between the read and the variable's declaration, so a read refers to the local
+# in question exactly when that depth matches the number of block scopes
+# descended to reach it.
+class Evilution::AST::LocalReads
+  def call(node, name, depth = 0)
+    return false if node.nil?
+    return true if reads?(node, name, depth)
+
+    node.compact_child_nodes.any? do |child|
+      next false if child.is_a?(Prism::DefNode)
+
+      call(child, name, depth + (scope?(child) ? 1 : 0))
+    end
+  end
+
+  private
+
+  def reads?(node, name, depth)
+    node.is_a?(Prism::LocalVariableReadNode) && node.name.to_s == name && node.depth == depth
+  end
+
+  def scope?(node)
+    node.is_a?(Prism::BlockNode) || node.is_a?(Prism::LambdaNode)
+  end
+end

data/lib/evilution/ast/parser.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "prism"
+require_relative "../ast"
 
 module Evilution::AST
   class Parser

data/lib/evilution/ast/pattern/filter.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../pattern"
 require_relative "parser"
 
 class Evilution::AST::Pattern::Filter