evilution 0.35.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 492fc3dd9f7676eaf9c263b1342602250561a382afe2aa9f5871daa04ce842a7
-  data.tar.gz: 8982ff01289997d8abaa3d5cb122de065ef0ebfcc1c043767e423d97a7d714f6
+  metadata.gz: 26a7a721749a19cb1f10d77b46a9d78d394ce5c112ba5d5fab8963de4a1a5f14
+  data.tar.gz: 65ee839279c74e07dd84d153015bfff6e29daf56d87929da75991fdef67e49c5
 SHA512:
-  metadata.gz: 6653347d505820a813fa673d60013806738b1e37e9f268c4c9c429c531644998a6e9d27bac2dfe93613eaa4aca6b8a257ed44867d9a1d92d4f4c5a27a16f93fa
-  data.tar.gz: d6da79725f113a9e11ac33da8e835ecf58db554db34efdd5b74a015b190bc4717864718f04462993801a9b44d606ff53de303a32dbcb7bf7fe15d5b4d71cb6b8
+  metadata.gz: 587598737cb636180b40cfb2466ecd0aac34c827eddb5432b543fc33b2b7e94b2e5b2a03915598fb9c41e9174bab8baad06ffab620f4174d8f686f9173f8fd1b
+  data.tar.gz: 85be8b922c45fab5e0e50fd8f17a6d5a572a9b9a2139181f0ca0283dc52c241bcd54b512e0cb3a5be9588edc31cd8b46fedd10437e8caf0c3e3104229c1f7127

data/.beads/interactions.jsonl

@@ -437,3 +437,14 @@
 {"id":"int-555de29c","kind":"field_change","created_at":"2026-06-16T07:54:17.438977358Z","actor":"Denis Kiselev","issue_id":"EV-z03y","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
 {"id":"int-616ccd27","kind":"field_change","created_at":"2026-06-16T09:31:30.217250542Z","actor":"Denis Kiselev","issue_id":"EV-z03y","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1375 (master). Dep on EV-rxob is provenance only; code fix shipped."}}
 {"id":"int-6d2f9b35","kind":"field_change","created_at":"2026-06-16T10:00:18.493013642Z","actor":"Denis Kiselev","issue_id":"EV-rxob","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"1.0 real-world validation complete. Rounds 2-4 ran 30+ gems across rspec/minitest/test-unit; no crash/memory blowup. All findings filed+fixed+merged: EV-z7f5/#1347, EV-gl1e/#1329, EV-52hf/#1341, EV-5hk5/#1373, EV-bi41/#1374, EV-z03y/#1375. Round-4 OOB re-verify confirmed fixes compound (state_machines 0->0.922, factory_bot/webmock/http real OOB scores, errors=0). Residual resolution-coverage gaps (behavior-named/flat-prefixed/non-std helper) tracked low-pri: EV-ajby/#1376, EV-6rbd/#1377, EV-no5u/#1378."}}
+{"id":"int-46080989","kind":"field_change","created_at":"2026-07-15T12:59:28.484284407Z","actor":"Denis Kiselev","issue_id":"EV-jj18","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-f2064cbf","kind":"field_change","created_at":"2026-07-15T13:25:07.606150972Z","actor":"Denis Kiselev","issue_id":"EV-fkw0","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}
+{"id":"int-eb2c5880","kind":"field_change","created_at":"2026-07-15T13:33:14.202699471Z","actor":"Denis Kiselev","issue_id":"EV-axze","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-fece2dce","kind":"field_change","created_at":"2026-07-15T13:33:14.634226625Z","actor":"Denis Kiselev","issue_id":"EV-7ab0","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-46a5d7e3","kind":"field_change","created_at":"2026-07-15T13:33:52.254966218Z","actor":"Denis Kiselev","issue_id":"EV-2bx6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-2b8ea434","kind":"field_change","created_at":"2026-07-15T13:33:52.673568305Z","actor":"Denis Kiselev","issue_id":"EV-dgjv","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-9f4fbaea","kind":"field_change","created_at":"2026-07-15T13:33:53.013705815Z","actor":"Denis Kiselev","issue_id":"EV-t1qg","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-608d35ec","kind":"field_change","created_at":"2026-07-15T13:33:53.352696649Z","actor":"Denis Kiselev","issue_id":"EV-vlbh","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-616f39e1","kind":"field_change","created_at":"2026-07-15T13:33:53.68007233Z","actor":"Denis Kiselev","issue_id":"EV-y194","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-abcaeb3a","kind":"field_change","created_at":"2026-07-15T13:33:54.363899883Z","actor":"Denis Kiselev","issue_id":"EV-j2kz","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-b8027311","kind":"field_change","created_at":"2026-07-15T13:34:47.737536249Z","actor":"Denis Kiselev","issue_id":"EV-w07i","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 Versioning policy: see [docs/versioning.md](docs/versioning.md).
 
+## [1.0.0] - 2026-07-15
+
+First stable release. From `1.0.0` onward evilution follows [Semantic Versioning](https://semver.org): the public contract — CLI commands and flags, `.evilution.yml` configuration keys, session JSON files, the MCP tool schemas, and process exit codes — is frozen and covered by the SemVer guarantees and deprecation cycle in [docs/versioning.md](docs/versioning.md). The `1.0.0` milestone is the culmination of the readiness work that shipped across the `0.31`–`0.35` line (config and session-JSON schema versioning, MCP tool-contract stabilization, the CLI flag deprecation sweep, real-world Rails validation, the parallel/isolation stress suite, and running evilution against its own suite to a mutation-score target).
+
+### Added
+
+- **Contributor architecture guide (`docs/architecture.md`)** — a single internals map for contributors: a high-level flow diagram, a module map of every `Evilution::` namespace, the end-to-end data flow from source file to scored result, and step-by-step recipes for adding a new mutator, reporter, or test integration. Linked from the README "Development" and "Internals" sections (EV-fkw0, PR #1407, GH #863)
+
+### Changed
+
+- **Public Ruby API frozen as internal (`docs/public_api.md`)** — evilution has no public Ruby API. The entire `Evilution::` namespace is internal and may change in any release; the supported, SemVer-governed surface is the CLI, config file, session JSON, MCP tools, and exit codes. The top-level `Evilution` module and the primary entry points (`Runner`, `CLI`, `Config`) carry an `@api private` YARD marker, the new [docs/public_api.md](docs/public_api.md) documents the contract surfaces, and [docs/versioning.md](docs/versioning.md) is updated to match (the MINOR trigger now covers "introducing a public Ruby facade where none exists" and the deprecation cycle no longer references a Ruby `@deprecated` path) (EV-jj18, PR #1406, GH #854)
+- **Dependency bumps** — `mcp` 0.21.0 → 0.24.0 (PRs #1402/#1403), plus CI/tooling updates (`rubocop` 1.88.2, `ruby/setup-ruby` 1.318.0, `actions/checkout` 7)
+
 ## [0.35.0] - 2026-06-24
 
 ### Added

data/README.md

@@ -11,7 +11,7 @@
 * **License**: MIT (free, no commercial restrictions)
 * **Language**: Ruby >= 3.3
 * **Parser**: Prism (Ruby's official AST parser, ships with Ruby 3.3+)
-* **Test frameworks**: RSpec and Minitest
+* **Test frameworks**: RSpec, Minitest, and Test::Unit
 
 ## Installation
 
@@ -783,6 +783,12 @@ When Evilution detects a parallel run against a SQLite-backed `config/database.y
 
 ## Development
 
+### Architecture
+
+New to the codebase? [docs/architecture.md](docs/architecture.md) is the
+contributor guide: the end-to-end mutation flow (source → result), a module map,
+and step-by-step recipes for adding a mutator, a reporter, or a test integration.
+
 ### Memory leak check
 
 Run before releasing to verify no memory regressions:
@@ -798,6 +804,9 @@ Tests 4 paths (InProcess isolation, Fork isolation, mutation generation + stripp
 
 ## Internals (for context, not for direct use)
 
+For the full contributor architecture — module map, data flow, and extension
+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
@@ -811,6 +820,8 @@ Tests 4 paths (InProcess isolation, Fork isolation, mutation generation + stripp
 
 `evilution` follows [Semantic Versioning](https://semver.org). The full policy — what counts as the public contract, what triggers a major bump, how deprecations work — is documented in [docs/versioning.md](docs/versioning.md).
 
+There is **no public Ruby API**: the entire `Evilution::` namespace is internal and may change in any release. Drive evilution through the CLI, `.evilution.yml`, the MCP tools, or hooks. See [docs/public_api.md](docs/public_api.md).
+
 ## Repository
 
 https://github.com/marinazzio/evilution

data/docs/architecture.md

@@ -0,0 +1,220 @@
+# Architecture (contributor guide)
+
+How evilution turns a source file into a mutation-testing report, and where to
+plug in new behavior. This is an internals map for contributors — none of the
+classes named here are a public API (see [public_api.md](public_api.md)); they
+can move or change in any release.
+
+For deeper dives on two subsystems that have their own docs, see
+[isolation.md](isolation.md) (fork vs in-process, sandboxing, signal safety) and
+[integrations.md](integrations.md) (RSpec / Minitest / Test::Unit specifics).
+
+## The one-paragraph version
+
+Evilution parses each target file with [Prism](https://github.com/ruby/prism)
+into an AST with exact byte offsets. Every method becomes a *subject*. Each
+mutation *operator* walks a subject's AST and emits *mutations* — byte-range
+edits applied by source-level surgery (no AST unparsing). For every mutation,
+evilution copies the file, applies the edit, runs the covering specs in an
+isolated worker, and records whether the tests noticed (`killed`) or not
+(`survived`). Results are aggregated into a `Summary`, scored, and handed to a
+reporter.
+
+## High-level flow
+
+```mermaid
+flowchart TD
+    CLI["exe/evilution → Evilution::CLI<br/>Commands::Run"] --> CFG["Config<br/>(YAML + CLI + env, frozen)"]
+    CFG --> RUN["Runner#call<br/>(orchestrator)"]
+    RUN --> SUB["SubjectPipeline<br/>AST::Parser → Subject per method"]
+    SUB --> BASE["BaselineRunner<br/>record already-failing specs"]
+    SUB --> PLAN["MutationPlanner<br/>Mutator::Registry → Mutation objects<br/>dedupe · disable · sig · equivalent"]
+    PLAN --> EXEC["MutationExecutor<br/>jobs=1 Sequential · jobs>1 Parallel::Pool"]
+    BASE --> EXEC
+    EXEC --> ISO["Isolation::Fork / InProcess<br/>apply mutation → Integration runs specs"]
+    ISO --> STAT["classify_status<br/>killed / survived / error / timeout / unresolved"]
+    STAT --> SUM["Result::Summary<br/>counts + score"]
+    SUM --> REP["ReportPublisher → Reporter::{CLI,JSON,HTML}"]
+    REP --> OUT["stdout / evilution-report.html<br/>+ optional Session::Store"]
+```
+
+## Module map
+
+Everything lives under `lib/evilution/`.
+
+| Namespace | Responsibility | Key entry points |
+|---|---|---|
+| `CLI`, `CLI::Commands::*` | Parse argv, build `Config`, dispatch subcommands (`run`, `session`, `compare`), map result to exit code. | `cli.rb`, `cli/commands/run.rb` |
+| `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::*` | 74 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` |
+| `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 |
+
+## Data flow, source → result
+
+Driven entirely by `Evilution::Runner#call` (`runner.rb:24`). Each step names the
+class that owns it.
+
+1. **Config** — `Config#initialize` merges YAML + CLI + env (`Config::Sources.merge`),
+   applies `DEFAULTS`, freezes. `Runner#initialize` builds the `AST::Parser`,
+   `Mutator::Registry.for_profile(config.profile)`, and (if `incremental`) a `Cache`.
+2. **Subjects** — `Runner::SubjectPipeline#call` resolves target files (explicit,
+   `source:<glob>`, or `Git::ChangedFiles`), then `AST::Parser#call` runs
+   `Prism.parse` and `AST::SubjectFinder` (a `Prism::Visitor`) emits one
+   `Evilution::Subject` per `def` node. Optional descendant/target/line-range filters follow.
+3. **Baseline** — `Runner::BaselineRunner#call` builds the integration from
+   `Runner::INTEGRATIONS` (`rspec`/`minitest`/`test_unit`) and records spec files
+   that already fail *before* any mutation, so their mutations aren't miscounted.
+   An optional `Runner::Canary` proves the pipeline can observe a known mutation.
+4. **Mutations** — `Runner::MutationPlanner#call` flat-maps subjects through
+   `Mutator::Registry#mutations_for`. The registry instantiates each operator and
+   runs `operator.call(subject, filter:)`; each operator subclasses
+   `Mutator::Base` and calls `add_mutation`, which runs `AST::SourceSurgeon` and
+   builds an immutable `Evilution::Mutation`. The planner then **deduplicates**
+   (by `file_path` + mutated source), and filters **disabled** (`DisableComment`),
+   **Sorbet `sig`** (`AST::SorbetSigDetector`), and **equivalent**
+   (`Equivalent::Detector`) mutations. Equivalent ones become `:equivalent`
+   results directly.
+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`).
+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
+   `@isolator.call(mutation:, test_command:, timeout:)`.
+7. **Isolate + test** — `Isolation::Fork#call` (default for Rails/gems) spawns a
+   sandboxed worker through `ProcessSupervisor#spawn` (own process group, TERM →
+   grace → KILL ladder, sandbox reap), applies the mutation
+   (`Integration::Loading::MutationApplier`), and runs `Integration::Base#call` →
+   `run_tests`. The child's result is marshaled back over a length-prefixed pipe.
+   `Isolation::InProcess` is the lighter path for plain-Ruby projects.
+8. **Status** — outcome flags come from the integration
+   (`Integration::RSpec::ResultBuilder`: passed / test_crashed / examples-loaded
+   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`.
+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).
+
+## How to add a new mutator
+
+A mutator is a `Prism::Visitor` subclass that emits byte-range edits.
+
+1. **Create the operator** in `lib/evilution/mutator/operator/<name>.rb`:
+
+   ```ruby
+   # frozen_string_literal: true
+
+   require_relative "../operator"
+
+   class Evilution::Mutator::Operator::MyThing < Evilution::Mutator::Base
+     def visit_integer_node(node)          # a Prism visit_*_node hook
+       add_mutation(
+         offset: node.location.start_offset,
+         length: node.location.length,
+         replacement: "42",                # the source text to splice in
+         node: node
+       )
+       super                               # ALWAYS call super to keep walking
+     end
+   end
+   ```
+
+   - Implement one or more `visit_<node_type>_node(node)` methods (the Prism node
+     names — `visit_call_node`, `visit_if_node`, …). Call `super` so child nodes
+     are still visited.
+   - Emit edits only through `add_mutation(offset:, length:, replacement:, node:)`.
+     It handles heredoc-span extension, the mutation filter, source surgery, and
+     builds the immutable `Mutation`. Never edit source strings directly.
+   - The operator's registered name is auto-derived from the class name
+     (`MyThing` → `my_thing`); that string is the `operator` field in JSON output
+     and is part of the public contract, so name it deliberately.
+
+2. **Require it** in `lib/evilution.rb` alongside the other
+   `require_relative "evilution/mutator/operator/..."` lines.
+
+3. **Register it** in `lib/evilution/mutator/registry.rb`: add the class to the
+   `default` list (runs in every profile) — or, for an aggressive operator meant
+   only for `profile: strict`, to `STRICT_EXTRA_OPERATORS` instead.
+
+4. **Test it** under `spec/evilution/mutator/operator/<name>_spec.rb`, mirroring an
+   existing operator spec. Adding an operator to the `default` profile shifts
+   mutation scores and is a **MINOR** version bump (see [versioning.md](versioning.md)).
+
+## How to add a new reporter
+
+A reporter is `.new(**opts)` + `#call(summary) -> String`. It consumes a frozen
+`Evilution::Result::Summary` and returns the rendered report body.
+
+1. **Create the reporter** in `lib/evilution/reporter/<format>.rb`:
+
+   ```ruby
+   # frozen_string_literal: true
+
+   require_relative "../reporter"
+
+   class Evilution::Reporter::Csv
+     def initialize(integration: :rspec)   # keyword args only; keep them optional
+       @integration = integration
+     end
+
+     def call(summary)                      # returns a String
+       # read summary.results, summary.score, summary.killed, summary.survived,
+       # summary.survived_results, etc. — see Result::Summary for the full API
+       "..."
+     end
+   end
+   ```
+
+   The `Summary` API a reporter reads includes: counts (`total`, `killed`,
+   `survived`, `errors`, `neutral`, `equivalent`, `unresolved`, `unparseable`,
+   `timed_out`), metrics (`score`, `score_denominator`, `success?(min_score:)`,
+   `efficiency`, `peak_memory_mb`), the raw `results`, and filtered lists
+   (`survived_results`, `killed_results`, …). Each result exposes `mutation`
+   (`operator_name`, `file_path`, `line`, `diff`), `status`, `duration`, and
+   status predicates (`killed?`, `survived?`, …).
+
+2. **Require it** in `lib/evilution.rb` (next to the other `reporter/*` requires)
+   **and** in `lib/evilution/runner.rb` (the runner requires reporters
+   independently, near the bottom of the file).
+
+3. **Wire the dispatch** in `Runner::ReportPublisher#build_reporter`
+   (`runner/report_publisher.rb`): add a `when :csv` branch returning your class,
+   and a matching `require_relative "../reporter/csv"` at the top. If the output
+   should go to a file rather than stdout, extend the `#publish` write branch
+   (only `:html` writes a file today; every other format is `$stdout.puts`ed).
+
+4. **Advertise the value.** There is no strict format allowlist to update —
+   `config.format` is only `to_sym`'d, not validated — but update the
+   `--format` help string in `cli/parser/options_builder.rb` so `csv` is
+   discoverable. (The `compare` subcommand keeps its *own* `SUPPORTED_FORMATS`
+   list; touch it only if `compare` should support the new format too.)
+
+Adding a new format is additive — a **MINOR** bump.
+
+## How to add a new test integration (bonus)
+
+Integrations subclass `Evilution::Integration::Base` (`integration/base.rb`),
+which defines the contract: class methods `baseline_runner` / `baseline_options`,
+and instance methods `run_tests(mutation)`, `ensure_framework_loaded`,
+`build_args(mutation)`, `reset_state` (each `raise NotImplementedError` until
+overridden). `Base#call` already handles applying the mutation and firing
+`mutation_insert_pre/post` hooks. Register the new class in
+`Runner::INTEGRATIONS` (`runner/baseline_runner.rb`) and allow its symbol in the
+integration config validator. See [integrations.md](integrations.md) for the
+framework-specific details.

data/docs/public_api.md

@@ -0,0 +1,50 @@
+# Public API
+
+This document defines evilution's public, SemVer-governed surface for `1.x`.
+
+## There is no public Ruby API
+
+**The entire `Evilution::` Ruby namespace is internal.** Every class, module,
+method, and constant under `Evilution::` may change, move, or disappear in any
+release — including patch releases — with no deprecation cycle. Do not `require`
+evilution and call into it programmatically expecting stability; internal
+refactors will break you without warning.
+
+Evilution is consumed through its CLI, its configuration file, its session
+output, and its MCP tools — not as a library you embed. The top-level
+`Evilution` module and the primary entry points (`Evilution::Runner`,
+`Evilution::CLI`, `Evilution::Config`) carry an `@api private` YARD marker; the
+namespace as a whole is internal by this declaration, whether or not an
+individual class is tagged.
+
+## What *is* the public contract
+
+These surfaces are stable under the [versioning policy](versioning.md). They are
+the supported way to drive evilution:
+
+| Surface | Authoritative reference |
+|---|---|
+| **CLI commands and flags** | README "Command Reference" |
+| **`.evilution.yml` configuration keys** | README "Configuration" |
+| **Session JSON files** (`.evilution/results/*.json`) | README "JSON Output Schema" |
+| **MCP tool schemas** (`evilution-mutate`, `evilution-session`, `evilution-info`) | README "MCP Server" → "Contract stability" |
+| **Process exit codes** (`0` pass, `1` fail, `2` error) | README "Exit Codes" |
+| **Hook events and payload keys** (configured via the `hooks:` config key) | README "Configuration" / hooks docs |
+
+Anything not in that table — and in particular anything reachable only by calling
+Ruby methods on `Evilution::` objects — is internal.
+
+## Why no Ruby API at 1.0
+
+Evilution's job is to run mutation testing from the command line (and from an MCP
+agent). The value users depend on is the behaviour of `evilution run`, the shape
+of the report it writes, and the config that tunes it — none of which requires a
+frozen object graph. Keeping the Ruby internals unfrozen lets the isolation,
+parallelism, and mutation-operator internals evolve freely across `1.x` without
+spending major-version budget. If a genuine embedding use case emerges, a small
+public facade can be introduced additively in a MINOR release.
+
+## See also
+
+- [Versioning & Upgrade Policy](versioning.md) — what each SemVer bump covers and
+  how deprecations work.

data/docs/versioning.md

@@ -7,14 +7,14 @@ This document defines what `evilution` promises across releases.
 | Bump          | Triggered by                                                                 |
 |---------------|-------------------------------------------------------------------------------|
 | MAJOR (`2.0`) | Removing or renaming anything in the public contract; changing semantics; tightening input validation. |
-| MINOR (`1.X`) | Adding a new CLI flag, config key, mutation operator, public Ruby method, or session/MCP field; relaxing validation; adding an operator to the `default` profile (whether brand-new or promoted from `strict`). |
+| MINOR (`1.X`) | Adding a new CLI flag, config key, mutation operator, or session/MCP field; introducing a public Ruby facade where none exists today; relaxing validation; adding an operator to the `default` profile (whether brand-new or promoted from `strict`). |
 | PATCH (`1.X.Y`) | Bug fix, performance improvement, documentation, internal refactor with no observable contract effect. |
 
 ## Public contract surface
 
 The following surfaces are covered by the SemVer guarantees above:
 
-- **Public Ruby API** — classes and methods explicitly documented as public. Everything else is internal and may change in any release.
+- **Public Ruby API** — there is none. The entire `Evilution::` namespace is internal and may change in any release. See [docs/public_api.md](public_api.md).
 - **CLI flags and commands** — the README "Command Reference" tables are the authoritative list.
 - **`.evilution.yml` configuration keys** — see the README "Configuration" section.
 - **Session JSON files** (`.evilution/results/*.json`) — see the README "JSON Output Schema" section.
@@ -27,7 +27,7 @@ Anything not on this list is internal. It can change in any release without a de
 
 When a feature on the public contract surface is deprecated:
 
-1. It is marked with the YARD `@deprecated` tag (Ruby API), or with a deprecation note in the relevant doc table (CLI flags, config keys, MCP fields).
+1. It is marked with a deprecation note in the relevant doc table (CLI flags, config keys, session/MCP fields).
 2. Where the call site is reachable at runtime, a one-line warning is emitted to stderr.
 3. The deprecated form remains functional for the entire `1.x` line. A feature deprecated in any `1.X` release continues to work in every subsequent `1.X+N` release.
 4. The earliest release that may remove the feature is the next major (`2.0`), per the SemVer table above.

data/lib/evilution/cli.rb

@@ -19,6 +19,7 @@ require_relative "cli/commands/session_gc"
 require_relative "cli/commands/compare"
 require_relative "cli/commands/run"
 
+# @api private
 class Evilution::CLI
   def initialize(argv, stdin: $stdin)
     parsed = Parser.new(argv, stdin: stdin).parse

data/lib/evilution/config.rb

@@ -4,6 +4,7 @@ require "yaml"
 require_relative "spec_resolver"
 require_relative "spec_selector"
 
+# @api private
 class Evilution::Config
   CONFIG_FILES = %w[.evilution.yml config/evilution.yml].freeze
   CURRENT_SCHEMA_VERSION = 1
@@ -117,7 +118,6 @@ class Evilution::Config
     FileLoader.load
   end
 
-  # Generates a default config file template.
   def self.default_template
     <<~YAML
       # Evilution configuration

data/lib/evilution/integration/loading/redefinition_recovery.rb

@@ -63,7 +63,9 @@ class Evilution::Integration::Loading::RedefinitionRecovery
 
   def idempotency_violation?(error)
     msg = error.message
-    IDEMPOTENCY_PATTERNS.any? { |pat| msg.include?(pat) }
+    # `msg` is a String and patterns are substrings, so `include?` is a
+    # substring test — `intersect?` would compare array elements, not text.
+    IDEMPOTENCY_PATTERNS.any? { |pat| msg.include?(pat) } # rubocop:disable Style/ArrayIntersect
   end
 
   def superclass_mismatch?(error)

data/lib/evilution/related_spec_heuristic.rb

@@ -31,14 +31,12 @@ class Evilution::RelatedSpecHeuristic
   def extract_domain(file_path)
     normalized = normalize_path(file_path)
 
-    # Strip common prefixes and get the relative path under app/ or lib/
     relative = normalized
                .delete_prefix("app/controllers/")
                .delete_prefix("app/models/")
                .delete_prefix("app/")
                .delete_prefix("lib/")
 
-    # Remove .rb extension and _controller suffix
     basename = relative.sub(/\.rb\z/, "")
     basename = basename.sub(/_controller\z/, "")
 

data/lib/evilution/runner.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require_relative "../evilution"
 
+# @api private
 class Evilution::Runner
   # Autoloaded: canary.rb subclasses Evilution::Error at class-body eval
   # time, which is not yet defined while evilution.rb is mid-load. Deferring

data/lib/evilution/version.rb

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

data/lib/evilution.rb

@@ -129,6 +129,12 @@ require_relative "evilution/cli"
 require_relative "evilution/disable_comment"
 require_relative "evilution/runner"
 
+# Evilution has no public Ruby API. The entire `Evilution::` namespace is
+# internal and may change in any release, including patches. The stable,
+# SemVer-governed contract is the CLI, `.evilution.yml` config keys, session
+# JSON files, the MCP tool schemas, and process exit codes. See
+# docs/public_api.md and docs/versioning.md.
+# @api private
 module Evilution
   # Captured at load time, before any isolator can chdir into a per-mutation
   # sandbox. Used as the anchor for resolving project-relative paths (spec

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evilution
 version: !ruby/object:Gem::Version
-  version: 0.35.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Denis Kiselev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-24 00:00:00.000000000 Z
+date: 2026-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -108,11 +108,13 @@ files:
 - comparison_results/baseline_2026-04-09.md
 - comparison_results/operator_classification.md
 - comparison_results/operator_prioritization.md
+- docs/architecture.md
 - docs/ast_pattern_syntax.md
 - docs/integrations.md
 - docs/isolation.md
 - docs/migration-from-mutant.md
 - docs/mutation_density_benchmark.md
+- docs/public_api.md
 - docs/versioning.md
 - exe/evil
 - exe/evilution