saboteur 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 767101a27863dfddcfd14ed0f71737ba34764feebd1824625c2354119f5144cc
-  data.tar.gz: 237fca7fc890cf682a4f4b10f2e2fbdfc23759d575ba5dfd804d60bc28febcb3
+  metadata.gz: a5c52cb7485073b569359bf940160095370103747d55a6065b7f067726a1a53c
+  data.tar.gz: 40fca0c1c0f8391de86d7f17960d908add226682d93be2610775fc888ab36f60
 SHA512:
-  metadata.gz: 2b7e6f93cd8844cf886905e009157a7227389b1a11f47ead943f8075d52e45c8533925b60ee04c41e9678039090c0072b3ad19f64a7ea5135b8e311ada65e2bd
-  data.tar.gz: 24faf1ebcfecaa018a4b415f86ceb40c73c2889fe49ff65718fba3e9709971e4c431756a6e4990436bc1fefbdb1fb8cdee72bf66953d5d76aa02d5b166435b70
+  metadata.gz: 061e0b5a97c95048048767d3724ea883ea144e7530b9a52631d52c896f4154e1a63f7b65ef7b5817053a42ab31eb97c168aa3079c87e9d9a3e8be1ae949d7bdf
+  data.tar.gz: e29bcfafdaf2fc7ecffbc4f8746349d79c908dfc2de1530998b525c691135c2bfb4ade67575374178742b1fddb29ab96a7d9ff67656d29dbd7c096ba0b50d0dc

data/CHANGELOG.md

@@ -6,6 +6,118 @@ All notable changes are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-12
+
+### Changed
+- **Breaking:** configuration moved from YAML to Ruby. `.saboteur.yml` becomes
+  `config/saboteur.rb` (`Saboteur.configure do |c| ... end`, same key names),
+  and `.saboteur-ignore.yml` becomes `config/saboteur_ignore.rb`
+  (`Saboteur.ignore do |i| i.mutation "<digest>", subject:, reason: end`,
+  reason still mandatory). A legacy YAML file stops the run with a pointer to
+  the new file instead of being read. Unknown settings fail with the line
+  number and a did-you-mean suggestion. `rails generate saboteur:install`
+  writes `config/saboteur.rb` (never overwriting without `--force`);
+  `config/saboteur_ignore.rb` and `config/saboteur_custom_map.rb` are optional
+  and created by hand when needed.
+- A run in which more than half of the executed mutants errored now exits 3
+  (the tool failed). Before, only a run where every executed mutant errored
+  did. Errored mutants are outside the score, so such a run tested almost
+  nothing. This applies with and without `--threshold`. The JSON report records the reason under
+  `saboteur.exitCause` (`ok`, `survivors`, `belowThreshold`, `errorMajority`,
+  `incompleteUnderThreshold`; in `--agent` mode `ok`, `survivors`,
+  `errorMajority` or `incomplete`).
+- A whole-suite coverage build that records no lines for any included file
+  now exits 3 and the empty map is not cached, instead of testing nothing.
+  With `--test`, an empty map stays a legitimate "no coverage" outcome.
+- Rails fixtures (`spec/fixtures`, `test/fixtures`), `db/structure.sql`,
+  `db/schema.rb` and `config/*.yml` are part of the coverage and verdict
+  cache fingerprint, so a changed fixture or schema invalidates cached
+  results. The new `fingerprint_extra` setting adds other globs whose
+  contents should invalidate caches, for example `data/*.csv`.
+- The baseline and coverage phases show progress and write real logs, so a
+  slow or failing phase can be diagnosed from the output.
+- When the baseline child is killed by a signal, the message names it
+  (`SIGKILL` adds a possible-OOM hint) instead of reporting a bare failure.
+
+### Removed
+- The coarse-survivor gate: a surviving whole-body mutant no longer skips the
+  method's fine mutants; every eligible fine mutant runs.
+
+### Fixed
+- Mutations inside private `module_function` helpers are preserved when the
+  method is re-evaluated; they previously reverted and reported as false
+  survivors.
+- Rails apps that test against in-memory SQLite (`:memory:`) no longer fail
+  in forked workers with "Could not find table": saboteur never disconnects,
+  renames or copies an in-memory pool. Each in-memory database is
+  snapshotted to a temporary file after boot, and every forked child
+  restores the snapshot into its own fresh database.
+- With a Rails app under Bootsnap, Coverage no longer sees an empty map:
+  saboteur sets `DISABLE_BOOTSNAP_COMPILE_CACHE=1` for its own process when
+  the variable is unset, because bytecode from Bootsnap's compile cache
+  carries no coverage counters.
+- A relative SQLite `database:` path resolves against `Rails.root` (as Rails
+  7.1+ does) for the per-worker copy and its cleanup. The copy uses SQLite's
+  backup API after a WAL checkpoint, refuses to run when a reader keeps the
+  WAL busy, and a missing source file is an error rather than a skipped copy.
+- Per-worker database copies (`jobs` above 1) are dropped when the run ends,
+  best effort: a failed drop is a warning and never changes the outcome. A
+  copy left by a killed run is reclaimed by the next run. A failed copy
+  names the sessions blocking it.
+- For `rails: true`, the app's `spec/` directory is on the load path before
+  `require` is processed, as with rspec, so a boot file such as a dummy app's
+  `spec/rails_helper.rb` can require its siblings.
+- When Rails did not load, the error points engine users at the dummy app's
+  environment file or helper (`DummyApp.setup` in `spec/rails_helper.rb`).
+
+### Added
+- `rails generate saboteur:install` and a Rails quickstart in the README. The
+  generator writes `config/saboteur.rb` and never overwrites without `--force`.
+- The warning about threads alive when a worker forks names those threads,
+  falling back to their backtraces for unnamed ones.
+- `--test` no longer requires source operands when `--since` is given: the
+  changed files are the sources, so `saboteur run --since origin/main --test
+  spec/billing_spec.rb` scopes a pull-request run to chosen specs. A `--since`
+  run without `--test` now warns before it starts that the two baseline passes
+  run the loaded suite (a cold coverage cache adds one more pass), with the
+  spec-file count and how to scope them, instead of going quiet for hours on a
+  large app.
+- `config/saboteur_custom_map.rb` declares explicit source-file to spec-file
+  mappings (`SABOTEUR_CUSTOM_MAP`): exact paths, globs (the more specific glob
+  wins; equal specificity is an error) and Regexps with capture substitution.
+  Invalid maps fail the run with the file and key; stale and duplicate keys
+  warn on runs, and `saboteur doctor` fails on stale keys. The map is parsed
+  and validated only for now - it does not change which specs run yet.
+
+- An integration target can declare a known error profile
+  (`allow_error_fraction` per strategy in integration/targets.yml): the
+  majority-error exit is accepted only when the run's own fresh report
+  carries the CLI's `errorMajority` marker, the errored fraction stays
+  within the bound, and no mutant hit a resource limit. The JSON report
+  records the run's exit cause under `saboteur.exitCause`.
+- A survivor lists the first five tests that covered its line and still passed
+  with the mutant applied, in the terminal and the HTML page.
+- In diff mode (`--since`), each survivor names the changed line it relates to
+  (`changed line: path:N` in the terminal, `changedLines` in each JSON finding),
+  because a multi-line statement is reported at its first line.
+- The score is split into assertion kills and crash kills, in the terminal,
+  the JSON report (`saboteur.scores`) and the HTML page. A second score leaves
+  out whole-body mutants (`body_nil`, `body_true`, `body_false`, `body_raise`). The headline score and
+  `--threshold` are unchanged.
+- `saboteur run --agent` (`--format agent`): one bounded JSON summary (under 8 KiB) on stdout
+  with status, verdict, provenance, the first three findings and the commands for full
+  detail. Exit 0 means a complete, clean run only: 1 survivors, 2 usage or config error,
+  3 incomplete or failed. `--threshold` cannot be combined with it. The next commands are shell-escaped and keep the
+  full selection; the working-tree state is read before the run; target output stays on stderr. `saboteur agent-skill`
+  prints an AGENTS.md block for coding agents (also in `docs/agent-skill.md`). Classic
+  exit codes are unchanged.
+- Fine `pair_removal` mutants for hash literals and keyword lists, including
+  sole associations, with token-based separators and the normal method cap.
+- Fine `argument_removal` mutants: remove one ordinary argument from a
+  parenthesized call while preserving keywords and blocks. Token-based comma
+  edits respect comments and strings. Existing candidate validation, order and
+  per-method caps apply. Unparenthesized calls and heredoc arguments are skipped.
+
 ## [0.3.0] - 2026-10-11
 
 ### Added
@@ -64,7 +176,7 @@ First release that does mutation testing. MIT licensed.
 ### Added
 - `saboteur run` with `--since`, `--subject`, `--timeout-factor`, `--jobs`,
   `--reeval`, `--json`, `--no-cache`, `--incremental`, `--config`.
-- Subjects found with Prism; mutations are byte-range edits: whole-method
+- Subjects found with Prism; mutations are byte-range edits: whole-body
   `nil`/`true`/`false`/`raise` first, then comparison, boolean, arithmetic,
   numeric literal, statement removal, condition, negation, safe navigation
   and `||=`.

data/README.md

@@ -31,14 +31,22 @@ fail?" for many small breakages and lists the ones nobody noticed. Read the
 
 ### The unchanged suite is checked first
 
-Every run with selected subjects runs the entire unchanged suite twice in fresh
+Every run with selected subjects runs the loaded unchanged suite twice (the specs chosen with `--test`, if given) in fresh
 supervised children before coverage lookup or incremental verdict reuse. This
 costs two suite runs even on a cache hit, plus a coverage-building suite run on
 a cache miss. Both baseline passes must be green, complete and in the same
-RSpec order at the run seed. A failure exits 3, stops mutation and names the log and fix. Each suite pass
+RSpec order at the run seed. A failure exits 3, stops mutation and names the log and fix. Long phases
+print their elapsed time about every 30 seconds, and each phase's log holds
+the suite's progress and full failure detail. Each suite pass
 uses `coverage_timeout` and configured memory/process limits (the suite memory
 budget is four times `max_memory_mb`, as for coverage). Older benchmark numbers
 need a rerun before they describe this extra fixed cost.
+A whole-suite coverage build that records no lines for any included file
+means the setup hid the app from Coverage (Bootsnap's compile cache is the
+common cause), so the run fails with exit 3 instead of testing nothing, and
+the empty map is not cached. With `--test` an empty map instead stays a
+legitimate "no coverage" outcome, because the chosen specs may not touch the
+selected sources.
 Two passes detect observed instability, not every possible flaky test. See
 [baseline stability](docs/baseline-stability.md) for limits and hook behaviour.
 
@@ -57,9 +65,8 @@ bundle exec saboteur run --subject 'YourClass#your_method'
 ```
 
 Outside a Bundler project, `gem install saboteur` installs the same executable.
-Rails apps need a Rails block in `.saboteur.yml` (boot file, `app/**/*.rb`,
-`rails: true`); see [Rails apps](#rails-apps) below. The defaults are for plain
-gems (`lib/**/*.rb`, `rails: false`, `jobs: 1`) and are not Rails-aware.
+Rails app? Follow the [Rails quickstart](#rails-apps) below: the defaults are for
+plain gems (`lib/**/*.rb`, `rails: false`, `jobs: 1`) and are not Rails-aware.
 
 Start with one method. You get counts per status, a score, timing, and a
 unified diff for every survivor, so you can read the exact change your tests
@@ -74,22 +81,24 @@ line coverage touched the changed statement. Tests that killed earlier mutants
 of the same method go first, then the fastest, and the first failure stops the
 run. A change no test reaches is reported as "no coverage", not as a survivor.
 
-**It does not waste time on dead ends.** Each method first gets whole-body
-mutants (`nil` and `raise`, or `true`/`false` for predicates; a few methods,
-such as some that rescue or log, get none). If your suite does not notice
-that, saboteur says so and skips the fine-grained mutants for that method. Subjects with no tests
-are skipped before any mutants are generated, and each method is capped at
-`max_mutants_per_method` mutants (100 by default).
+**It runs coarse mutants first, then fine mutants.** Each method first gets
+whole-body mutants: `nil` (`true`/`false` for predicates) unless the body is empty or
+only logs, and `raise` unless a catch-all rescue would absorb it. Fine-grained mutants run
+regardless of the coarse verdict, including a survivor or a reused verdict.
+Deleting a body unnoticed does not prove its smaller changes are harmless.
+Subjects with no tests are skipped before any mutants are generated, and each
+method is capped at `max_mutants_per_method` mutants (100 by default). Running
+fine mutants after coarse survivors can increase run time and change scores.
 
 **It prepares memory before it forks.** Before workers fork, saboteur warms and
 compacts the Ruby heap ([`ForkReadiness`](lib/saboteur/execution/fork_readiness.rb)),
 which is meant to let workers share more pages with their parent and copy less.
-The physical-memory benefit is not yet established by a published benchmark.
+Observed on the pinned hashie workload (paired runs, below): about 17-18% lower peak PSS at 2 and 6 workers. Not a general guarantee.
 
 **It is aimed at pull requests.** `--since origin/main` mutates only the methods
 your branch changed: fine-grained mutants on the changed lines, plus the
 whole-body mutants of those methods. On one real change in saboteur's own history, that took a file
-from 139 mutants to 7, and median wall time fell 22.9%. The time saving is
+from 139 mutants to 7, and median wall time fell 22.9% (measured at d2b7abb, before the coarse-survivor gate was removed; a rerun is pending). The time saving is
 smaller than the mutant count because building the coverage map is a fixed
 cost, and this is one file, not a Rails app, so it is not a general speed
 claim. The full method, raw timings and
@@ -97,8 +106,8 @@ caveats are in [bench/since](bench/since/README.md).
 
 **It checks its own kills.** After a method's mutants run, saboteur re-runs the
 killing tests against the *unchanged* method. If they fail there too, the kill
-is not credited and becomes an error. In our comparison on lobsters, 0 of 20
-checked kills were fake. Every mutant runs in a supervised child with deadline,
+is not credited and becomes an error. In one comparison on lobsters, 0 of 20
+randomly sampled kills were fake. Every mutant runs in a supervised child with deadline,
 memory and process limits, and saboteur tracks and kills the processes it
 starts.
 
@@ -124,17 +133,20 @@ Positional operands name the sources to mutate: Ruby files, or directories
 (all their `.rb` files). Each must exist; a typo or a non-Ruby file exits 2
 before anything runs. They replace `include` and `exclude`. `--test`
 (repeatable; spec files or directories, with an optional `:LINE` or `[1:2]`
-selector; needs at least one source) replaces only the files RSpec runs. Other
+selector; needs at least one source, unless `--since` is given - the changed
+files are the sources) replaces only the files RSpec runs. Other
 `rspec_args` and `.rspec` options such as `--require` stay. The coverage map
 is built from only those specs, each mutant runs only the ones that cover it,
 and the selection is part of the coverage and `--incremental` cache keys.
 
-`--threshold PERCENT` (0 to 100, or `threshold:` in `.saboteur.yml`) is for CI.
+`--threshold PERCENT` (0 to 100, or `c.threshold` in `config/saboteur.rb`) is for CI.
 The run exits 1 when the score is below PERCENT and 0 when it is at or above,
 even with survivors. It fails closed: a run that tested no mutant has no score
 and exits 1, and a run where any mutant errored or hit a resource limit exits 3,
 because the score covers only part of the run. Without a threshold, any
-unignored survivor exits 1.
+unignored survivor exits 1. Either way, a run where more than half of the
+executed mutants errored exits 3: errored mutants are outside the score,
+so such a run tested almost nothing.
 
 Other flags: `--jobs N` (concurrent workers), `--timeout-factor N`,
 `--config PATH`, `--integration NAME`, `--reeval class_eval|nesting`,
@@ -142,7 +154,11 @@ Other flags: `--jobs N` (concurrent workers), `--timeout-factor N`,
 
 For pull requests, start with `--since` against your target branch. This is a
 workflow recommendation, not a CLI default: plain `run` still checks the whole
-configured project. Keep whole-project runs on main: diff mode does not check every method affected by a
+configured project. To scope the specs as well, pass them with `--test` and no
+source operands: `bundle exec saboteur run --since origin/main --test spec/billing_spec.rb`.
+With `--since` and no `--test`, the run warns before it starts that the two baseline passes
+run the loaded suite (a cold coverage cache adds one more pass), and how to
+scope them. Keep whole-project runs on main: diff mode does not check every method affected by a
 dependency change. [The pull-request guide](docs/pull-requests.md) covers
 checkout history, a GitHub Actions example, configuration and limits.
 
@@ -152,7 +168,7 @@ mutation reports or coverage/verdict caches. Target boot files and tests still
 run, so their normal side effects remain. See the [doctor guide](docs/guides/doctor.md).
 
 `--id` runs exactly one current mutant with its coverage-selected tests, bypassing
-per-method caps, coarse gating, ignore suppression and incremental verdict reuse.
+per-method caps, ignore suppression and incremental verdict reuse.
 It still honors `--subject` and `--since` changed-line selection. See the
 [replay guide](docs/guides/replay.md) for digest format, checks and limits.
 
@@ -167,16 +183,42 @@ unchanged. It cannot see a change in a method this one calls, so run without
 it now and then (and in CI on the main branch).
 
 Output: counts per status, the score, timing, and a unified diff for every
-survivor. The JSON report goes to `.saboteur/report.json` and a self-contained HTML
+survivor. Under each diff the terminal lists the tests that covered that line
+and still passed with the mutant applied (the first five, likeliest killers
+first; the rest are under `coveredBy` in the JSON report). The missing
+check may belong in one of them. Line coverage can overstate which tests
+exercise a line, so treat the list as a lead. A survivor reused with
+`--incremental` was not run again, and the list says its tests passed in an
+earlier run. The HTML page shows the same list in the
+survivor's notes. The JSON report goes to `.saboteur/report.json` and a self-contained HTML
 report (one file, no scripts, no network) to `.saboteur/report.html`. Change
-the paths with `--json` / `--html` or `json_report` / `html_report` in
-`.saboteur.yml`; set either to `null` to turn that report off. The two paths
+the paths with `--json` / `--html` or `c.json_report` / `c.html_report` in
+`config/saboteur.rb`; set either to `nil` to turn that report off. The two paths
 must differ. The HTML page shows the covered mutation score
 `(killed + timeout) / (killed + survived + timeout)`, which leaves NoCoverage
 out and keeps survivors accepted on the ignore list in the denominator. A tool
 that reads the JSON report may show a different score, because the schema counts
 NoCoverage as undetected.
 
+The score is split by how the mutant was killed. A crash kill (a `NoMethodError`,
+a `TypeError`, a parse error) shows the code ran and broke, not that a test
+checked a value. The terminal prints
+`score 100.0 % (assertion 50.0 %, crash 50.0 %)`: each share is a part of
+tested mutants, so the parts add up to the score. Timeouts and kills with no
+recorded cause (a verdict reused from an older run, a test that called `exit`,
+a failure outside any example) are named when there are some. Whole-body
+mutants (`body_nil`, `body_true`, `body_false`, `body_raise`) are killed by
+almost any test that runs the method, so a second line scores the run without
+them, and shows them alone. The headline score and `--threshold` still count every
+mutant. The JSON report carries both splits under `saboteur.scores`
+(`all` and `withoutWholeBodyMutants`), and the HTML page prints them under
+the score. The JSON also records why the run exited the way it did under
+`saboteur.exitCause` (`ok`, `survivors`, `belowThreshold`,
+`errorMajority`, `incompleteUnderThreshold`). In `--agent` mode the cause
+follows the agent verdict, so the report and the process exit classify the
+run the same way: `ok` for clean, `survivors` for survivors, and otherwise
+`errorMajority` when most mutants errored or `incomplete`.
+
 For code-review surfaces, the JSON report also carries a `saboteur.findings`
 section: a bounded, deterministically ordered list of survivors, coarse
 mutants first (a surviving coarse mutant hints that no test pins the method's
@@ -188,6 +230,15 @@ Survivors accepted on the ignore list are listed separately with their
 reason, and `survivorsTruncated` and `acceptedTruncated` count what the bound
 left out; the full data stays in the schema's `files` section.
 
+In diff mode (`--since`), a mutant is reported at the line where its statement
+starts. A statement that spans several lines can start a line or two above the
+line that changed. Under each survivor the terminal therefore prints
+`changed line: path:N`, the changed line or lines (the first three) the mutant
+touches, and each finding carries them as `changedLines`. Use `changedLines`,
+not `line`, to put a note on a changed line of the pull-request diff. A
+whole-body mutant of a method whose only change is its signature touches no
+changed line and prints none.
+
 Exit codes: 0 no survivors (or all on the ignore list), or the score meets
 `--threshold`; 1 survivors, or the score is below `--threshold` or missing;
 2 bad configuration or a missing source or test; 3 the tool failed (with
@@ -203,38 +254,126 @@ other errors and reused cached kills are not included. See
 
 ## ⚙️ Configuration
 
-`.saboteur.yml` in the project root; CLI flags override it. Keep the shared
+`config/saboteur.rb` in the project root; CLI flags override it. Keep the shared
 config usable for whole-project runs and pass `--since` in the pull-request
-job. A PR-only config may set `since: origin/main`; omit `since` (or use
-`since: null`) in the config for audits on main. Use your actual target branch.
-
-```yaml
-include: [lib/**/*.rb]
-exclude: [lib/my_gem/version.rb]
-require: []                 # boot files, e.g. ./config/environment
-reeval: nesting             # or class_eval; see docs/design.md 6.1
-timeout_factor: 3           # per-mutant deadline = factor x its tests' recorded time
-timeout_min: 5
-max_memory_mb: 2048         # memory growth cap per mutant process tree
-max_processes: 64
-max_mutants_per_method: 100  # positive integer; raise it for a broader run
-ignore_file: .saboteur-ignore.yml
-seed: 1                     # Ruby's random seed in every test run
+job. A PR-only config may set `c.since = "origin/main"`; omit `since` (or use
+`c.since = nil`) in the config for audits on main. Use your actual target branch.
+
+```ruby
+Saboteur.configure do |c|
+  c.include = ["lib/**/*.rb"]
+  c.exclude = ["lib/my_gem/version.rb"]
+  c.require = []                 # boot files, e.g. ./config/environment
+  c.reeval = "nesting"           # or "class_eval"; see docs/design.md 6.1
+  c.timeout_factor = 3           # per-mutant deadline = factor x its tests' recorded time
+  c.timeout_min = 5
+  c.max_memory_mb = 2048         # memory growth cap per mutant process tree
+  c.max_processes = 64
+  c.max_mutants_per_method = 100 # positive integer; raise it for a broader run
+  c.ignore_file = "config/saboteur_ignore.rb"
+  c.seed = 1                     # Ruby's random seed in every test run
+  c.fingerprint_extra = []       # extra globs whose contents invalidate caches, e.g. ["data/*.csv"]
+end
 ```
 
 ### Rails apps
 
-The defaults target a plain gem, so a Rails app needs this in `.saboteur.yml`:
+Quickstart for a Rails + RSpec app. The defaults target a plain gem, so a Rails
+app needs a few settings; the generator writes them for you.
+
+**1. Add the gem**
+
+```sh
+bundle add saboteur --group test
+```
+
+**2. Generate the setup**
+
+```sh
+bundle exec rails generate saboteur:install
+```
+
+This writes `config/saboteur.rb`, a `bin/saboteur` binstub (it sets `RAILS_ENV=test`
+for you) and a `.gitignore` entry for `.saboteur/`. It never overwrites an
+existing file unless you pass `--force`, and never edits your Gemfile.
 
-```yaml
-include: [app/**/*.rb]
-require: [./config/environment]   # boots the app
-rails: true                       # reconnects ActiveRecord after fork, per-worker databases
-jobs: 4                           # optional; the default is 1
+Prefer to do it by hand, or on a version without the generator? Put this in
+`config/saboteur.rb`:
+
+```ruby
+Saboteur.configure do |c|
+  c.include = ["app/**/*.rb"]
+  c.require = ["./config/environment"] # boots the app
+  c.rails = true                       # reconnects ActiveRecord after fork, per-worker databases
+  c.jobs = 4                           # optional; the default is 1
+end
 ```
 
-Run with `RAILS_ENV=test` and turn SimpleCov off for the run. An install
-generator is planned; until then this block is the supported setup.
+**3. Check the setup**
+
+```sh
+bin/saboteur doctor
+```
+
+Doctor boots your app, checks the config and the test database host, and runs
+your suite twice before any mutation. Fix whatever it reports first. Turn
+SimpleCov off for the run if you use it.
+
+**4. Test what your branch changed**
+
+```sh
+bin/saboteur run --since main
+```
+
+It mutates only the methods changed since `main` and reports each survivor with
+its diff: a change your tests did not notice. Write a test that fails on that
+diff, then run again. Use `--since origin/main` in CI. Without the generator, use
+`bundle exec saboteur` and `RAILS_ENV=test` instead of `bin/saboteur`.
+
+saboteur puts the app's `spec/` directory on the load path before
+processing `require`, matching rspec, so a boot file like a dummy app's
+`spec/rails_helper.rb` can require its siblings.
+
+With `jobs` above 1 on SQLite, each extra worker gets a copy of the test
+database made through SQLite's backup API, so the copy is a consistent
+snapshot. A relative `database:` path resolves against `Rails.root`, the
+same as Rails 7.1+ does, for the copy and for its cleanup. The copy
+checkpoints the source first (`PRAGMA wal_checkpoint(TRUNCATE)`) and
+refuses to run when a reader keeps the WAL busy, because copying on
+would silently miss committed rows. A source file that does not exist is
+an error, not a skipped copy. An in-memory SQLite database (`:memory:`) is
+never copied, renamed or disconnected. After the app boots, each in-memory
+database is snapshotted to a temporary file through SQLite's backup API,
+and every forked child restores the snapshot into its own fresh database -
+a child cannot keep the parent's connection (ActiveRecord discards
+inherited pools and sqlite3 closes inherited writable handles), so without
+the snapshot it would see an empty database.
+
+For a Rails engine, point `require` at the dummy app's environment -
+`test/dummy/config/environment.rb`, usually loaded for you by
+`spec/rails_helper.rb`. Only a dynamically created dummy app has no
+environment file; there, require the helper that calls setup instead,
+such as `DummyApp.setup` in `spec/rails_helper.rb`.
+
+Bootsnap needs no extra setting: bytecode from its compile cache carries no
+coverage counters, so saboteur sets `DISABLE_BOOTSNAP_COMPILE_CACHE=1` for its
+own process when the variable is not already set (Bootsnap treats any set
+value as off) and runs the eager load with Coverage active. App code is seen
+by Coverage with the app unchanged.
+
+With `jobs: 4` (or more), each extra worker gets a copy of every test
+database, named `<database>_saboteur2` and up, made with
+`CREATE DATABASE ... TEMPLATE` on Postgres or a file copy on SQLite.
+saboteur drops the copies when the run ends, on a best-effort basis: a
+drop that fails is reported as a warning and never changes the run's
+outcome. A copy left behind - by a failed drop or a killed run - is
+reclaimed by the next run, whose prepare starts from
+`DROP DATABASE IF EXISTS`. MySQL is not supported for `jobs` above 1.
+
+Rails fixtures (`spec/fixtures`, `test/fixtures`), `db/structure.sql`,
+`db/schema.rb` and `config/*.yml` (including `database.yml`) are part of the
+cache fingerprint automatically. Use `fingerprint_extra` for any other file your
+tests read.
 
 ### Skipped subjects and the mutant cap
 
@@ -261,11 +400,13 @@ mutants; the limit does not bound how many proposals a custom source creates.
 
 Every survivor is printed with a digest. Accept it with a reason:
 
-```yaml
-# .saboteur-ignore.yml
-- subject: "Billing::Invoice#total"
-  mutation: "1a2b3c4d5e6f7a8b"
-  reason: "equivalent: amounts are always whole cents"
+```ruby
+# config/saboteur_ignore.rb
+Saboteur.ignore do |i|
+  i.mutation "1a2b3c4d5e6f7a8b",
+             subject: "Billing::Invoice#total",
+             reason: "equivalent: amounts are always whole cents"
+end
 ```
 
 An entry without a reason is rejected.
@@ -320,6 +461,46 @@ No speed, type-safety or real-fault detection improvement is claimed. See
 [the literal operator rationale](docs/literal-operators.md) for fault evidence
 and limits, including string encoding/frozen-value behavior.
 
+## Argument removal
+
+Builtin removes one ordinary positional argument from a parenthesized call.
+For `Model.includes(:a, :b, c: :d)`, the two proposals remove `:a` or `:b`,
+without deleting the statement or changing `c: :d`. This lets a preload check
+exercise missing associations instead of only a missing return value.
+The operator and source name is `argument_removal`.
+
+Only parenthesized calls are supported in this first version. Keyword hashes,
+splats, argument forwarding, bracket indexing/assignment syntax and arguments containing
+heredocs are unchanged. Explicit hash arguments count as positional arguments.
+Blocks and keyword pairs remain intact; separators come from Prism tokens,
+so commas inside strings or comments are not mistaken for separators.
+Arid statements, parameter defaults and nested definitions are skipped.
+
+These fine proposals follow existing builtin proposals, with the same validation,
+deduplication and `max_mutants_per_method` cap. Earlier digests and relative order
+stay unchanged for unchanged subjects. Extra proposals can change scores or be
+omitted by the cap. Removing an argument can still raise an arity error; no
+non-crashing guarantee is made. The regression uses a small preload-like receiver
+and checks the missing associations, not an ActiveRecord SQL benchmark. See
+[the validation notes](docs/argument-removal.md) for the pinned snapshot migration.
+
+## Hash and keyword pair removal
+
+Builtin removes one key/value association from a hash literal or keyword list.
+`Model.includes(:a, :b, c: :d)` becomes `Model.includes(:a, :b )`, so a nested
+preload guard can be exercised without deleting the whole statement. A sole
+hash pair becomes `{}`. Operator and source name: `pair_removal`.
+
+Both parenthesized and command calls are supported. Splats stay intact; pairs
+containing heredocs, parameter defaults, arid statements and nested definitions
+are skipped. Token-based separator edits preserve comments and blocks. Nested
+hash values and callable bodies are visited. Removing a required keyword can
+still crash; the regression uses a preload-like receiver, not an ActiveRecord
+SQL benchmark. These fine proposals follow earlier builtin proposals and use
+the usual validation, deduplication, order and `max_mutants_per_method` cap.
+More proposals can change scores and cap coverage. See
+[the validation notes](docs/pair-removal.md) for snapshot changes.
+
 ## 🔌 Extending
 
 Public API, stable across minor versions:
@@ -334,9 +515,10 @@ Public API, stable across minor versions:
 
 ## 🌍 Where it has run
 
-An early release (0.3.0). Tested on the RSpec suites of plain gems
+An early release (0.4.0). Tested on the RSpec suites of plain gems
 (dry-inflector, tty-color, hashie, addressable) and of two Rails 8.1 apps:
-human-essentials on Postgres (4,080 mutants, 6 workers) and lobsters on SQLite,
+human-essentials on Postgres (4,080 mutants, 6 workers; the 2026-10-10 run, before
+the baseline check and the coarse-gate removal) and lobsters on SQLite,
 both on macOS. Not yet tried on MySQL or older Rails versions. RSpec only, by
 design. Results: [docs/validation](docs/validation).
 
@@ -344,17 +526,20 @@ design. Results: [docs/validation](docs/validation).
 
 A small, non-exhaustive comparison with [mutineer](https://github.com/davidteren/mutineer)
 1.6.0 on four RSpec projects (two libraries, two Rails apps). Each configuration
-ran once on sampled files, so treat the numbers as indicative. mutineer is ahead
+ran once on sampled files, so treat the numbers as indicative. The table was
+measured at 2b6ec02, before the literal, filter and argument operators and
+before the coarse-survivor gate was removed, so mutant counts and times will
+change; a rerun is pending. mutineer is ahead
 on number of operators and CI extras, and it supports Minitest.
 
 | Metric | saboteur | mutineer |
 |---|---|---|
-| Fake kills (lobsters) | 0 of 20 checked | 8 of 8 checked |
+| Fake kills (lobsters) | 0 of 20 sampled at random | 8 of 8 hand-checked (identical mutants, not a random sample) |
 | Rails app with 6 workers | yes, same verdicts as 1 worker | 1 worker only |
 | Runs on the Postgres app | yes | no |
 | Time per mutant, hashie | 0.008 s | 0.092 s |
 | Peak memory, hashie (summed process RSS) | 595 MB | 471 MB |
-| Choice of operators, CI features | fixed set, fewer | 20 operators, baseline, HTML, GitHub Action |
+| Choice of operators, CI features | fixed set, fewer | 22 operators, baseline, HTML, GitHub Action |
 
 Full results, method and limitations:
 [benchmark page](https://vamsipavanmahesh.github.io/saboteur/benchmark/).
@@ -380,12 +565,12 @@ variants, as before.
 
 Peak RSS is unchanged (median ~660 MB at jobs=6 both variants): the PR does not
 touch less memory, it keeps more of it shared between workers after fork, which
-is what PSS measures. On machines running many parallel workers this is the
-difference that keeps the box out of swap.
+is what PSS measures. On this workload the PSS drop is about 17-18% at 2 and 6 workers on a
+2 GB sandbox. Swap was not measured.
 
-Wall time on uncontended runs: 30-36s for both variants at every job level (no
-regression; per-cell minimums 48s vs 49s at jobs=1, 32s vs 31s at jobs=2, 30s
-vs 32s at jobs=6, PR first). The shared sandbox had multi-minute CPU-starvation
+Wall time on uncontended runs, per-cell minimums, PR first: 48s vs 49s at jobs=1, 32s vs 31s at jobs=2, 30s vs
+32s at jobs=6. These are noisy per-cell minima from historical runs and do not
+show a direction either way. The shared sandbox had multi-minute CPU-starvation
 windows during this session (walls up to 594s); affected runs are flagged via
 sampler cadence and excluded from wall analysis. Absolute times are specific to
 this 2-core sandbox. Environment, method and the contention log are on the
@@ -397,7 +582,7 @@ this 2-core sandbox. Environment, method and the contention log are on the
 team workflow (GitHub Action, baseline, HTML report), then 1.0. saboteur stays
 RSpec-only. Design
 details are in [docs/design.md](docs/design.md), prior art in
-[docs/prior-art.md](docs/prior-art.md), and the project checklist in
+[docs/prior-art.md](docs/prior-art.md), and project status in
 [docs/status.md](docs/status.md).
 
 ## 🤝 Contributing

data/lib/generators/saboteur/install/install_generator.rb

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "rails/generators"
+require "saboteur/install"
+
+module Saboteur
+  module Generators
+    # rails generate saboteur:install [--force]
+    class InstallGenerator < Rails::Generators::Base
+      desc "Writes config/saboteur.rb, bin/saboteur and a .gitignore entry for a Rails + RSpec app."
+
+      def install_saboteur
+        installer = Saboteur::Install.new(root: destination_root, force: options[:force])
+        installer.call.each { |result| say_status(result.status, result.path) }
+        hint = installer.gemfile_hint
+        say("\n#{hint}") if hint
+      end
+    end
+  end
+end