evilution 0.34.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 005b0edbf9ced13a00a85d07939564cec9f38d93dec0e1d923f30a9d7cb2c779
-  data.tar.gz: a7554571383f34fd21ca7d8d61f733e446d1d2c6349816267459b19309605689
+  metadata.gz: 492fc3dd9f7676eaf9c263b1342602250561a382afe2aa9f5871daa04ce842a7
+  data.tar.gz: 8982ff01289997d8abaa3d5cb122de065ef0ebfcc1c043767e423d97a7d714f6
 SHA512:
-  metadata.gz: 6227ee0e3df976329f59f286b21cfaa69bbd4455d00a1fe37dc4c77a9ff553f9e2c4fa7e112b7b19d7e6cc45c5ef2f98ccb2e03f7733fbd97ff7be6ad8582c71
-  data.tar.gz: e4a36d7eaa5826c8621d042beb1bedb7c612a67118b4456a909caa1f813bb0863098b57e113684faf9a8797ac0993f2d2d2ee2ee92562376c6e3a35cbb92ecad
+  metadata.gz: 6653347d505820a813fa673d60013806738b1e37e9f268c4c9c429c531644998a6e9d27bac2dfe93613eaa4aca6b8a257ed44867d9a1d92d4f4c5a27a16f93fa
+  data.tar.gz: d6da79725f113a9e11ac33da8e835ecf58db554db34efdd5b74a015b190bc4717864718f04462993801a9b44d606ff53de303a32dbcb7bf7fe15d5b4d71cb6b8

data/.rubocop_todo.yml

@@ -15,6 +15,7 @@ Metrics/ClassLength:
     - "lib/evilution/runner.rb"
     - "lib/evilution/runner/isolation_resolver.rb"
     - "lib/evilution/cli/parser/options_builder.rb"
+    - "lib/evilution/spec_resolver.rb"
 
 Metrics/MethodLength:
   Exclude:

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Versioning policy: see [docs/versioning.md](docs/versioning.md).
 
+## [0.35.0] - 2026-06-24
+
+### Added
+
+- **Test::Unit now scores out-of-the-box: a dedicated canary spec plus a Test::Unit spec resolver** — `--integration test-unit` shared minitest's runtime but not its file conventions, so two things silently broke. (1) The proof-of-life canary always wrote either an RSpec `_spec.rb` or a minitest `_test.rb` and only ever generated RSpec/minitest source; under `test-unit` the synthetic mutation loaded nothing, scored `:error`, and aborted the run before any real mutation ran. The canary now emits a `Test::Unit::TestCase` subclass into a `_test.rb` file for `test-unit` (and keeps the `_test.rb`/`_spec.rb` split keyed on the integration). (2) The config spec-resolver builder fell through to the default `spec/`/`_spec.rb` resolver for `test-unit`, which resolved nothing for a `test/`-rooted suite; it now reuses minitest's `test/` + `_test.rb` resolver since test-unit gems mirror that layout (PR #1386)
+- **Auto-preload finds namespaced gem test helpers (`test/<gem>/helper.rb`)** — gems that namespace their suite keep the bootstrap at `test/<gem>/helper.rb` (e.g. ruby/csv: `test/csv/helper.rb`) rather than a flat `test/test_helper.rb`. The conventional preload chain missed it, so autodetect fell back to the bare gem entry point (`lib/<gem>.rb`) — which never sets up the test framework — and the canary aborted. The gem-helper search now also looks for the namespaced form, deriving the directory from the gem name (dotted form for dash-named gems plus the flat form): `test/<gem>/helper.rb`. `Evilution::GemDetector.gem_name` is exposed publicly so callers can build these conventional paths (PR #1386)
+
+### Fixed
+
+- **`SpecResolver` resolves flat `test_`-prefixed Test::Unit/minitest files (`test/test_connection_pool_timed_stack.rb`)** — some minitest/Test::Unit gems flatten a nested source's path into a single `test_`-prefixed file at the test root (`lib/connection_pool/timed_stack.rb` → `test/test_connection_pool_timed_stack.rb`, with no `test/connection_pool/` subdir), so the resolver found nothing and scored `:unresolved`. The resolver now derives a flat candidate from the **full** lib-relative path (every segment joined with `_`) — deliberately not from namespace-dropped variants, which would yield bare-basename forms (`test_timed_stack.rb`) that collide across namespaces and are already covered by the existing `test_<name>.rb` convention. Top-level sources produce nothing here, and the flat candidate ranks below the mirrored layouts so a 1:1 file always wins. Minitest suffix only (PR #1385)
+- **Unresolved-mutation warnings now name concrete recovery paths for behaviour-named spec layouts** — `SpecResolver` intentionally does not guess for **behaviour-named** layouts (specs named by behaviour, not by lib path, so nothing ties a source file to a spec — e.g. aasm's `lib/aasm/base.rb`, exercised through the public API by `spec/unit/{event,callbacks,guard,api}_spec.rb`). A fuzzy match there would report a misleading score, so every mutation stays `:unresolved` (a coverage gap, `errors=0`). The minitest, RSpec, and Test::Unit unresolved warnings now spell out the explicit opt-ins — name the covering specs via `--spec`/`--spec-dir`, or run the whole suite per mutation with `--fallback-full-suite` — so a behaviour-named layout reads as a fixable resolution choice rather than a silent 0%. Documented in the README "Unresolved mutations — behaviour-named spec layouts" section (PR #1384)
+
 ## [0.34.0] - 2026-06-16
 
 ### Added

data/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/marinazzio/evilution/refs/heads/master/assets/logo/evilution-mark-transparent.svg" width="160" height="160" alt="Evilution mascot">
+</p>
+
 [![Gem Version](https://badge.fury.io/rb/evilution.svg)](https://badge.fury.io/rb/evilution)
 
 # Evilution — Mutation Testing for Ruby
@@ -59,6 +63,13 @@ The first command writes a sibling `Gemfile.local.lock`. Decide whether to commi
 
 The evilution gemspec already declares `prism >= 1.5, < 2`, so adding the `gem "prism"` line above is only necessary on stacks that also pin prism in `Gemfile.lock`.
 
+## Migrating from `mutant`
+
+Coming from the commercially-licensed [`mutant`](https://github.com/mbj/mutant) gem? See
+[docs/migration-from-mutant.md](docs/migration-from-mutant.md) for a command/config
+mapping, output-terminology differences, and how to diff the two tools' results with
+`evilution compare` (it ingests mutant session JSON directly).
+
 ## Command Reference
 
 ```
@@ -94,7 +105,7 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 | `-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`). |
 | `--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`) and dir-grouped (`test/unit/<class>/*_test.rb`) layouts. |
+| `--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`. |
 | `--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. |
@@ -377,7 +388,7 @@ Compatibility policy for the `1.x` gem line:
 | `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 both the `lib/`-mirrored path and common non-mirrored buckets (`spec/unit`, `spec/lib`, `test/unit`, `test/lib`), 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.
+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 (74 total)
 
@@ -687,6 +698,22 @@ For each entry in `survived[]`:
 
 Entries in the JSON `errors[]` array represent mutations that raised an exception (syntax error, load failure, or runtime crash) rather than producing a test outcome. Each entry includes `error_class`, `error_message`, and the first 5 `error_backtrace` lines. Use these fields to decide whether the error is a bug in the mutation operator (file an issue), a load-time problem in the mutated source (often `NoMethodError: super called outside of method` or constant-redefinition issues), or a genuine crash that the original tests should have caught. Run with `--verbose` to stream the same error details to stderr during the run.
 
+### Unresolved mutations — behaviour-named spec layouts
+
+`SpecResolver` auto-detects mirrored (`spec/foo_spec.rb`), non-mirrored (`spec/unit`, `spec/lib`, `test/unit`), and dir-grouped (`test/unit/<class>/*_test.rb`) layouts. It deliberately does **not** guess for **behaviour-named** layouts — where specs are named by behaviour rather than by lib path, so no path or class name ties a source file to a spec. The canonical example is [aasm](https://github.com/aasm/aasm): `lib/aasm/base.rb` is the central DSL class, but it has no `base_spec.rb`; its behaviour is exercised through the public API by `spec/unit/{event,callbacks,guard,api}_spec.rb`, none of which name `AASM::Base`. Every mutation in such a file resolves to no spec and is reported `:unresolved` (a coverage gap, not a failure — `errors=0`).
+
+This is intentional: a fuzzy content/grep match would pick a wrong-but-plausible spec subset and report a misleading score. `:unresolved` plus the warning is the honest signal. To get a real score, opt into one of the two explicit recovery paths the warning names:
+
+```bash
+# run a directory of specs you know covers the file (--spec-dir globs it)
+bundle exec evilution mutate lib/aasm/base.rb --spec-dir spec/unit
+# or name explicit files as a single comma-separated --spec value (no shell glob)
+bundle exec evilution mutate lib/aasm/base.rb --spec spec/unit/event_spec.rb,spec/unit/callbacks_spec.rb
+
+# or run the whole suite per mutation (slower, but correct-by-superset)
+bundle exec evilution mutate lib/aasm/base.rb --fallback-full-suite
+```
+
 ### 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.

data/assets/logo/evilution-mark-transparent.svg

@@ -0,0 +1,53 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-label="Evilution — evil ruby mutant mascot">
+  <title>Evilution</title>
+  <defs>
+    <filter id="glow" x="-60%" y="-60%" width="220%" height="220%">
+      <feGaussianBlur stdDeviation="2.4" result="b"/>
+      <feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <!-- clawed arms (behind gem) -->
+  <g stroke="#470B13" stroke-width="2.5" stroke-linejoin="round">
+    <path d="M60 124 L40 132 L46 138 L36 142 L48 147 L40 153 L56 150 L64 136 Z" fill="#9A1826"/>
+    <path d="M196 124 L216 132 L210 138 L220 142 L208 147 L216 153 L200 150 L192 136 Z" fill="#7F1420"/>
+  </g>
+
+  <!-- faceted ruby body -->
+  <g stroke="#470B13" stroke-width="2.5" stroke-linejoin="round">
+    <polygon points="98,82 128,82 128,120 88,120" fill="#D5384A"/>
+    <polygon points="128,82 158,82 168,120 128,120" fill="#B91C2C"/>
+    <polygon points="54,120 88,120 98,82" fill="#E2566B"/>
+    <polygon points="168,120 202,120 158,82" fill="#911A28"/>
+    <polygon points="54,120 88,120 128,214" fill="#A81B2A"/>
+    <polygon points="88,120 128,120 128,214" fill="#911A28"/>
+    <polygon points="128,120 168,120 128,214" fill="#7C1320"/>
+    <polygon points="168,120 202,120 128,214" fill="#5E0F18"/>
+  </g>
+  <polygon points="98,82 158,82 202,120 128,214 54,120" fill="none" stroke="#3A0910" stroke-width="3" stroke-linejoin="round"/>
+
+  <!-- glowing mutant eyes -->
+  <g filter="url(#glow)">
+    <polygon points="100,99 123,106 118,117 96,110" fill="#22D3EE"/>
+    <polygon points="156,99 133,106 138,117 160,110" fill="#22D3EE"/>
+    <polygon points="110,105 118,107 116,113 108,111" fill="#0E1A2B"/>
+    <polygon points="146,105 138,107 140,113 148,111" fill="#0E1A2B"/>
+  </g>
+
+  <!-- fanged grin -->
+  <path d="M106 138 L150 138 L142 149 L134 144 L128 150 L122 144 L114 149 Z" fill="#1B060C"/>
+  <polygon points="118,138 125,138 122,148" fill="#EAF2F8"/>
+  <polygon points="131,138 138,138 134,148" fill="#EAF2F8"/>
+
+  <!-- mutation cracks leaking binary -->
+  <g filter="url(#glow)" fill="none" stroke="#67E8F9" stroke-width="1.7" stroke-linecap="round" opacity="0.92">
+    <polyline points="166,90 156,106 169,120 159,134"/>
+    <polyline points="82,150 92,160 86,172"/>
+  </g>
+  <g fill="#7FE9F7" font-family="monospace" font-size="11" font-weight="700" opacity="0.85">
+    <text x="170" y="128" transform="rotate(12 170 128)">1</text>
+    <text x="176" y="140" transform="rotate(12 176 140)">0</text>
+    <text x="168" y="150" transform="rotate(12 168 150)">1</text>
+    <text x="78" y="184" transform="rotate(-14 78 184)">0</text>
+  </g>
+</svg>

data/assets/logo/evilution-mark.svg

@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-label="Evilution — evil ruby mutant mascot">
+  <title>Evilution</title>
+  <defs>
+    <radialGradient id="bg" cx="50%" cy="40%" r="78%">
+      <stop offset="0%" stop-color="#27364D"/>
+      <stop offset="100%" stop-color="#1E293B"/>
+    </radialGradient>
+    <pattern id="hex" width="56" height="100" patternUnits="userSpaceOnUse" patternTransform="scale(0.42)">
+      <path d="M28 66L0 50L0 16L28 0L56 16L56 50L28 66L28 100M28 0L28 34L0 50M28 34L56 50"
+            fill="none" stroke="#3B4D68" stroke-width="2" opacity="0.30"/>
+    </pattern>
+    <filter id="glow" x="-60%" y="-60%" width="220%" height="220%">
+      <feGaussianBlur stdDeviation="2.4" result="b"/>
+      <feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <!-- backdrop -->
+  <rect width="256" height="256" rx="52" fill="url(#bg)"/>
+  <rect width="256" height="256" rx="52" fill="url(#hex)"/>
+
+  <!-- clawed arms (behind gem) -->
+  <g stroke="#470B13" stroke-width="2.5" stroke-linejoin="round">
+    <path d="M60 124 L40 132 L46 138 L36 142 L48 147 L40 153 L56 150 L64 136 Z" fill="#9A1826"/>
+    <path d="M196 124 L216 132 L210 138 L220 142 L208 147 L216 153 L200 150 L192 136 Z" fill="#7F1420"/>
+  </g>
+
+  <!-- faceted ruby body -->
+  <g stroke="#470B13" stroke-width="2.5" stroke-linejoin="round">
+    <!-- table (top) -->
+    <polygon points="98,82 128,82 128,120 88,120" fill="#D5384A"/>
+    <polygon points="128,82 158,82 168,120 128,120" fill="#B91C2C"/>
+    <!-- crown shoulders -->
+    <polygon points="54,120 88,120 98,82" fill="#E2566B"/>
+    <polygon points="168,120 202,120 158,82" fill="#911A28"/>
+    <!-- pavilion: main facet ridges run from the table corners (88,120 / 168,120)
+         down to the culet, continuing the crown's inclined edges -->
+    <polygon points="54,120 88,120 128,214" fill="#A81B2A"/>
+    <polygon points="88,120 128,120 128,214" fill="#911A28"/>
+    <polygon points="128,120 168,120 128,214" fill="#7C1320"/>
+    <polygon points="168,120 202,120 128,214" fill="#5E0F18"/>
+  </g>
+  <!-- crisp outer silhouette -->
+  <polygon points="98,82 158,82 202,120 128,214 54,120" fill="none" stroke="#3A0910" stroke-width="3" stroke-linejoin="round"/>
+
+  <!-- glowing mutant eyes -->
+  <g filter="url(#glow)">
+    <polygon points="100,99 123,106 118,117 96,110" fill="#22D3EE"/>
+    <polygon points="156,99 133,106 138,117 160,110" fill="#22D3EE"/>
+    <polygon points="110,105 118,107 116,113 108,111" fill="#0E1A2B"/>
+    <polygon points="146,105 138,107 140,113 148,111" fill="#0E1A2B"/>
+  </g>
+
+  <!-- fanged grin -->
+  <path d="M106 138 L150 138 L142 149 L134 144 L128 150 L122 144 L114 149 Z" fill="#1B060C"/>
+  <polygon points="118,138 125,138 122,148" fill="#EAF2F8"/>
+  <polygon points="131,138 138,138 134,148" fill="#EAF2F8"/>
+
+  <!-- mutation cracks leaking binary -->
+  <g filter="url(#glow)" fill="none" stroke="#67E8F9" stroke-width="1.7" stroke-linecap="round" opacity="0.92">
+    <polyline points="166,90 156,106 169,120 159,134"/>
+    <polyline points="82,150 92,160 86,172"/>
+  </g>
+  <g fill="#7FE9F7" font-family="monospace" font-size="11" font-weight="700" opacity="0.85">
+    <text x="170" y="128" transform="rotate(12 170 128)">1</text>
+    <text x="176" y="140" transform="rotate(12 176 140)">0</text>
+    <text x="168" y="150" transform="rotate(12 168 150)">1</text>
+    <text x="78" y="184" transform="rotate(-14 78 184)">0</text>
+  </g>
+</svg>

data/docs/isolation.md

@@ -87,6 +87,7 @@ order, falling back to the gem's library entry point (`lib/<gem>.rb`):
 1. `spec/spec_helper.rb` (RSpec)
 2. `test/test_helper.rb` (Minitest / Test::Unit)
 3. `test/helper.rb` (flat-layout convention)
+4. `test/<gem>/helper.rb` (namespaced suites, e.g. ruby/csv's `test/csv/helper.rb`; the namespace is derived from the gem name, with the dotted form for dash-named gems) (PR #1386)
 
 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

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/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/gem_detector.rb

@@ -43,6 +43,13 @@ module Evilution::GemDetector
       @mutex.synchronize { @cache.clear }
     end
 
+    # Public accessor for the resolved gem name (gemspec basename, disambiguated
+    # by target paths for multi-gemspec roots). Callers use it to derive
+    # conventional paths such as a namespaced test helper (test/<gem>/helper.rb).
+    def gem_name(root, target_paths: nil)
+      gem_name_for(root, target_paths: target_paths)
+    end
+
     private
 
     def starting_dir(path)

data/lib/evilution/integration/minitest.rb

@@ -276,8 +276,19 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     return if @warned_files.include?(file_path)
 
     @warned_files << file_path
-    action = @fallback_to_full_suite ? "running full suite" : "marking mutation unresolved"
-    warn "[evilution] No matching test found for #{file_path}, #{action}. " \
-         "Use --spec to specify the test file."
+    warn unresolved_test_message(file_path)
+  end
+
+  # Name both recovery paths when skipping :unresolved; when already falling
+  # back the suite is running, so only the explicit-spec hint applies.
+  # Behaviour-named layouts never auto-resolve (EV-ajby / GH #1376).
+  def unresolved_test_message(file_path)
+    if @fallback_to_full_suite
+      "[evilution] No matching test found for #{file_path}, running full suite. " \
+        "Use --spec to specify the test file."
+    else
+      "[evilution] No matching test found for #{file_path}, marking mutation unresolved. " \
+        "Use --spec to specify the test file, or --fallback-full-suite to run the whole suite."
+    end
   end
 end

data/lib/evilution/integration/rspec/unresolved_spec_warner.rb

@@ -11,8 +11,22 @@ class Evilution::Integration::RSpec::UnresolvedSpecWarner
     return if @warned.include?(file_path)
 
     @warned << file_path
-    action = fallback_to_full_suite ? "running full suite" : "marking mutation unresolved"
-    warn "[evilution] No matching spec found for #{file_path}, #{action}. " \
-         "Use --spec to specify the spec file."
+    warn message(file_path, fallback_to_full_suite)
+  end
+
+  private
+
+  # When already falling back the suite is running, so only the explicit-spec
+  # hint is useful. Otherwise the mutation is skipped :unresolved — name BOTH
+  # recovery paths, since behaviour-named layouts (specs not mirroring the lib
+  # path, e.g. aasm's base.rb) never auto-resolve (EV-ajby / GH #1376).
+  def message(file_path, fallback_to_full_suite)
+    if fallback_to_full_suite
+      "[evilution] No matching spec found for #{file_path}, running full suite. " \
+        "Use --spec to specify the spec file."
+    else
+      "[evilution] No matching spec found for #{file_path}, marking mutation unresolved. " \
+        "Use --spec to specify the spec file, or --fallback-full-suite to run the whole suite."
+    end
   end
 end

data/lib/evilution/integration/test_unit/test_file_resolver.rb

@@ -41,8 +41,19 @@ class Evilution::Integration::TestUnit::TestFileResolver
     return if @warned_files.include?(file_path)
 
     @warned_files << file_path
-    action = @fallback_to_full_suite ? "running full suite" : "marking mutation unresolved"
-    warn "[evilution] No matching test found for #{file_path}, #{action}. " \
-         "Use --spec to specify the test file."
+    warn unresolved_message(file_path)
+  end
+
+  # Name both recovery paths when skipping :unresolved; when already falling
+  # back the suite is running, so only the explicit-spec hint applies.
+  # Behaviour-named layouts never auto-resolve (EV-ajby / GH #1376).
+  def unresolved_message(file_path)
+    if @fallback_to_full_suite
+      "[evilution] No matching test found for #{file_path}, running full suite. " \
+        "Use --spec to specify the test file."
+    else
+      "[evilution] No matching test found for #{file_path}, marking mutation unresolved. " \
+        "Use --spec to specify the test file, or --fallback-full-suite to run the whole suite."
+    end
   end
 end

data/lib/evilution/runner/canary.rb

@@ -76,13 +76,30 @@ class Evilution::Runner::Canary
   end
 
   def write_spec(dir)
-    minitest = @config.integration == :minitest
-    name = minitest ? "canary_#{suffix}_test.rb" : "canary_#{suffix}_spec.rb"
-    path = File.join(dir, name)
-    File.write(path, minitest ? minitest_spec_source : rspec_spec_source)
+    path = File.join(dir, spec_filename)
+    File.write(path, spec_source)
     path
   end
 
+  # minitest and test-unit both live under a `_test.rb` file; rspec uses
+  # `_spec.rb`. Picking the wrong shape makes the integration load nothing (or
+  # raise), so the synthetic mutation scores :error and aborts the run.
+  def spec_filename
+    test_framework? ? "canary_#{suffix}_test.rb" : "canary_#{suffix}_spec.rb"
+  end
+
+  def test_framework?
+    %i[minitest test_unit].include?(@config.integration)
+  end
+
+  def spec_source
+    case @config.integration
+    when :minitest then minitest_spec_source
+    when :test_unit then test_unit_spec_source
+    else rspec_spec_source
+    end
+  end
+
   def rspec_spec_source
     <<~RUBY
       RSpec.describe("evilution proof-of-life canary") do
@@ -103,6 +120,16 @@ class Evilution::Runner::Canary
     RUBY
   end
 
+  def test_unit_spec_source
+    <<~RUBY
+      class EvilutionCanaryTest_#{suffix} < Test::Unit::TestCase
+        def test_pipeline_is_alive
+          assert(true)
+        end
+      end
+    RUBY
+  end
+
   def build_mutation(class_path)
     Evilution::Mutation.new(
       subject: Evilution::Subject.new(

data/lib/evilution/runner/isolation_resolver.rb

@@ -222,7 +222,21 @@ class Evilution::Runner::IsolationResolver
   end
 
   def find_first_existing_gem_helper
-    find_first_existing_under(detected_gem_root, GEM_PRELOAD_CANDIDATES)
+    find_first_existing_under(detected_gem_root, GEM_PRELOAD_CANDIDATES) ||
+      find_first_existing_under(detected_gem_root, nested_gem_helper_candidates)
+  end
+
+  # Gems that namespace their suite keep the helper at test/<gem>/helper.rb
+  # (ruby/csv: test/csv/helper.rb) rather than the flat test/helper.rb, so the
+  # conventional chain misses it and autodetect would fall back to the bare gem
+  # entry — which never sets up the test framework, aborting the canary.
+  # Derive the namespace dir from the gem name (dotted for dash-named gems, plus
+  # the flat form).
+  def nested_gem_helper_candidates
+    name = detected_gem_root && Evilution::GemDetector.gem_name(detected_gem_root, target_paths: target_files)
+    return [] unless name
+
+    [name.tr("-", "/"), name].uniq.map { |ns| File.join("test", ns, "helper.rb") }
   end
 
   def find_first_existing_under(root, candidates)

data/lib/evilution/spec_resolver.rb

@@ -161,7 +161,14 @@ class Evilution::SpecResolver
 
     fallbacks = primary.flat_map { |c| parent_fallback_candidates(c) }
 
-    (primary + fallbacks + prefix_convention_candidates(stripped)).uniq
+    (primary + fallbacks + convention_candidates(stripped)).uniq
+  end
+
+  # Non-mirrored Test::Unit/minitest filename conventions: the `test_<name>.rb`
+  # prefix and the flat namespace-prefixed form. Both rank below the mirrored
+  # layouts assembled in #candidate_test_paths.
+  def convention_candidates(stripped)
+    prefix_convention_candidates(stripped) + flat_prefixed_candidates(stripped)
   end
 
   # Conventional roots that may hold tests: the mirrored root plus the common
@@ -204,6 +211,25 @@ class Evilution::SpecResolver
     end
   end
 
+  # Test::Unit / minitest gems sometimes flatten a nested source's path into a
+  # single `test_`-prefixed file at the test root: lib/connection_pool/timed_stack.rb
+  # -> test/test_connection_pool_timed_stack.rb (no test/connection_pool/ subdir).
+  # Built from the FULL lib-relative path only (every segment joined with `_`),
+  # NOT from namespace-dropped variants — dropping segments would yield bare
+  # basename forms (test_timed_stack.rb) that collide across namespaces and are
+  # already covered by #prefix_convention_candidates. Top-level sources have no
+  # namespace to flatten, so they produce nothing here. Ranked below the mirrored
+  # layouts (appended last) so a 1:1 file always wins. Minitest suffix only.
+  def flat_prefixed_candidates(stripped)
+    return [] unless @test_suffix == MINITEST_SUFFIX
+    return [] unless stripped.include?("/")
+
+    name = stripped.delete_suffix(@test_suffix).tr("/", "_")
+    return [] if name.empty?
+
+    roots.map { |root| "#{root}/test_#{name}.rb" }
+  end
+
   def controller_to_request_test(stripped_path)
     return nil unless stripped_path.start_with?(CONTROLLER_PREFIX)
 

data/lib/evilution/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evilution
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.35.0
 platform: ruby
 authors:
 - Denis Kiselev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-16 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -99,6 +99,11 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- assets/logo/evilution-mark-1024.png
+- assets/logo/evilution-mark-64.png
+- assets/logo/evilution-mark-transparent-1024.png
+- assets/logo/evilution-mark-transparent.svg
+- assets/logo/evilution-mark.svg
 - claude-swarm.yml
 - comparison_results/baseline_2026-04-09.md
 - comparison_results/operator_classification.md
@@ -106,6 +111,7 @@ files:
 - docs/ast_pattern_syntax.md
 - docs/integrations.md
 - docs/isolation.md
+- docs/migration-from-mutant.md
 - docs/mutation_density_benchmark.md
 - docs/versioning.md
 - exe/evil