mutineer 1.6.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +680 -0
  3. data/README.md +210 -499
  4. data/lib/mutineer/baseline.rb +1 -1
  5. data/lib/mutineer/changed_lines.rb +2 -1
  6. data/lib/mutineer/child_coverage.rb +53 -0
  7. data/lib/mutineer/cli.rb +293 -42
  8. data/lib/mutineer/concern_blocks.rb +243 -0
  9. data/lib/mutineer/config.rb +154 -8
  10. data/lib/mutineer/coverage_map.rb +265 -27
  11. data/lib/mutineer/daemon_backend.rb +244 -75
  12. data/lib/mutineer/daemon_client.rb +73 -10
  13. data/lib/mutineer/daemon_server.rb +226 -42
  14. data/lib/mutineer/external_backend.rb +159 -15
  15. data/lib/mutineer/init.rb +124 -0
  16. data/lib/mutineer/isolation.rb +78 -24
  17. data/lib/mutineer/job_plan.rb +234 -44
  18. data/lib/mutineer/kill_channel.rb +24 -14
  19. data/lib/mutineer/migrate.rb +707 -0
  20. data/lib/mutineer/minitest_integration/in_test_database_error.rb +184 -0
  21. data/lib/mutineer/minitest_integration/kill_recorder.rb +25 -17
  22. data/lib/mutineer/minitest_integration.rb +44 -14
  23. data/lib/mutineer/mutator_registry.rb +6 -2
  24. data/lib/mutineer/mutators/array_literal.rb +4 -2
  25. data/lib/mutineer/mutators/base.rb +36 -7
  26. data/lib/mutineer/mutators/call_to_receiver.rb +148 -0
  27. data/lib/mutineer/mutators/chain_link.rb +6 -6
  28. data/lib/mutineer/mutators/condition_forcing.rb +6 -3
  29. data/lib/mutineer/mutators/operand_removal.rb +4 -2
  30. data/lib/mutineer/mutators/range_literal.rb +105 -4
  31. data/lib/mutineer/mutators/return_nil.rb +1 -0
  32. data/lib/mutineer/orphan_guard.rb +84 -0
  33. data/lib/mutineer/pairing.rb +62 -1
  34. data/lib/mutineer/project.rb +302 -14
  35. data/lib/mutineer/rails_run_env.rb +73 -0
  36. data/lib/mutineer/rails_worker_db.rb +1596 -57
  37. data/lib/mutineer/redaction.rb +199 -0
  38. data/lib/mutineer/reporter.rb +173 -31
  39. data/lib/mutineer/result.rb +52 -15
  40. data/lib/mutineer/runner.rb +148 -28
  41. data/lib/mutineer/statement_lines.rb +24 -11
  42. data/lib/mutineer/subject.rb +30 -4
  43. data/lib/mutineer/test_runners/minitest.rb +2 -1
  44. data/lib/mutineer/test_runners/rspec.rb +15 -3
  45. data/lib/mutineer/test_runners.rb +5 -2
  46. data/lib/mutineer/triage.rb +111 -0
  47. data/lib/mutineer/version.rb +1 -1
  48. data/lib/mutineer/worker_pool.rb +2 -1
  49. data/lib/mutineer.rb +4 -0
  50. data/skills/mutineer/SKILL.md +84 -0
  51. metadata +13 -1
data/CHANGELOG.md CHANGED
@@ -6,6 +6,684 @@ All notable changes to this project are documented here. The format is based on
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [1.8.0] - 2026-10-29
10
+
11
+ ### Highlights
12
+
13
+ Read these before you upgrade. Details are in the sections below.
14
+
15
+ - **Scores can change after the upgrade.** Under `--strategy reload`, most methods
16
+ in a concern's `included` or `prepended` block are now scored (#297). Runs
17
+ that list `call_to_receiver` get more mutants (#274). Runs that list
18
+ `range` get new mutants for endless ranges (#299). A mutant that two
19
+ operators make now counts once (#275). These can change counts, scores
20
+ and survivors. If you gate on `--baseline`, write a new full baseline.
21
+ - **Delete `ignore:` entries for `range` mutants (#299).** A new `range`
22
+ mutant can take an old id, so an old entry can hide a real survivor.
23
+ - **Fewer false kills.** Under `--test-command`, a non-zero exit other than 1
24
+ scores `error`, and so does an exit 1 with no failing test in the summary
25
+ line (#292). An Active Record connection or lock error inside a Minitest
26
+ test scores `error` too (#296). Before, these scored `killed`.
27
+ - **Exit codes match STABILITY.md (#288).** A boot, source or `require:`
28
+ file that raises while it loads exits 1. A missing boot or `require:`
29
+ file exits 2.
30
+ - **`--threshold` compares the exact score (#280).** A run with 1999 of
31
+ 2000 mutants killed shows 100.0% but no longer passes `--threshold 100`.
32
+ - **New report data.** The JSON report adds `summary.declined` and
33
+ `summary.declined_by_operator` (schema `1.9`), and stderr warns when many
34
+ mutants could not run (#291).
35
+ - **Parallel `--daemon` with unused test databases (#316).** List them under
36
+ `shared_databases` to run more than one worker. Needs Rails 7.1 or later.
37
+ - **The gem ships the agent skill (#315).**
38
+ - **Releases wait for a maintainer.** Nothing publishes on a schedule or on
39
+ a tag push.
40
+
41
+ ### Added
42
+
43
+ - **`shared_databases` config key** (#316). An app with a second test
44
+ database ran one worker under `--daemon`. List the databases your tests
45
+ never use (`shared_databases: [cable]`), and the workers share them and run
46
+ in parallel. After each mutant, a parallel worker checks those databases.
47
+ The mutant scores `error` when a pool for one is still connected after the
48
+ tests, or ran SQL during them. A replica in the same `connects_to` counts
49
+ as its database. Listing the primary database stops the run with exit 2.
50
+ A name that matches no test database warns and is not checked. The check
51
+ needs Rails 7.1 or later. Three safety changes come with it for
52
+ `--rails --daemon`: a test database with `database_tasks: false` now
53
+ counts toward the one-worker limit, and the run keeps one worker when the
54
+ app's databases cannot be listed or the first daemon does not boot
55
+ (before, each case could start several workers). See
56
+ [More than one database](https://github.com/davidteren/mutineer/blob/main/docs/rails-setup.md#more-than-one-database)
57
+ for the transactional-tests caveat.
58
+ - **Counts of mutants that were not scored (#291).** Operators now count the
59
+ candidates they decline: a heredoc they cannot mutate safely, or an
60
+ equivalent skip such as an endless range or a skipped chain-link name. The
61
+ dry run prints the count. The human report prints it when the run has
62
+ mutants; when every candidate was declined, the empty-run warning names the
63
+ count instead (that warning is off under `--allow-empty`). The JSON report
64
+ adds `summary.declined` and `summary.declined_by_operator` (schema `1.9`).
65
+ A new stderr warning fires when unplaceable and skipped-invalid mutants are
66
+ more than one and more than 10% of the mutants a run tried to score. The
67
+ warning does not change the exit code. Measured on commit caa9e1a (this
68
+ change merged with main) with every operator: the dry run on `lib/`
69
+ declines 195 candidates beside 17,374 mutations (call_to_receiver 122,
70
+ chain_link 45, range 12, statement_removal 10, return_nil 6); the dry run
71
+ on the Rails fixture app declines 0 beside 69 mutations. A
72
+ `--strategy redefine --rails` run on the fixture app models (order,
73
+ price_list, billing/fee) has 0 unplaceable and 0 skipped-invalid of 12
74
+ attempted, so no warning. The fixture has no concerns, so it cannot tune
75
+ the 10% limit.
76
+ - **Included and prepended block methods under reload.** After you upgrade,
77
+ follow the [full baseline refresh recipe](https://davidteren.github.io/mutineer/agentic-coding.html#ci-gate)
78
+ with `--no-since --format json --output .mutineer/refreshed-baseline.json` and your
79
+ existing source and test options. Review the report and replace the stored
80
+ baseline. This applies only to runs that use `--strategy reload`: under
81
+ redefine these methods stay `unplaceable`. GitHub Action users on reload,
82
+ the Action's default (a Rails app without a daemon uses redefine), must
83
+ replace the file passed to the `baseline` input too. A check against an older
84
+ report lists the new survivors as regressions.
85
+ Under `--strategy reload`, in-process and on the daemon, a method in a
86
+ concern's `included` or `prepended` block is now mutated and scored (#297).
87
+ Mutineer loads the mutated method into each class that already has it. A
88
+ prepended wrapper that calls `super` reaches that mutated method too. A
89
+ concern included into an object's singleton class is supported. A class
90
+ that includes the concern later gets it from the reloaded block. The
91
+ rest of the block does not run again, so validators and callbacks are not
92
+ added twice. These mutants used to be `unplaceable`, so a reload score can go
93
+ down and a `--threshold` gate can start to fail. Some methods stay
94
+ `unplaceable`: a method in a class, module or `Struct.new` block inside the
95
+ block, a method inside another method or block, a method with an explicit
96
+ receiver other than `self` (such as `def base.tag` in `included do |base|`),
97
+ a hook-block method whose source line conflicts with another `def` or an
98
+ explicit Ruby method creator (the full rule is in `docs/json-schema.md`),
99
+ every method in a block that uses `alias` or `alias_method`, a method the
100
+ block itself calls, and every method in a block whose `included do` call is
101
+ not a plain line of the module
102
+ body (for example inside `if`, `unless`, or `x = included do`). The full list
103
+ is in `docs/json-schema.md`. If a class aliases a method that Mutineer does
104
+ run (one not in that list) outside the block, the mutant scores `error`,
105
+ because the alias keeps the original method. This also applies when a
106
+ wrapper replaces the original name and calls the saved alias. A retained
107
+ `Method` or `UnboundMethod` for the original also makes the mutant score
108
+ `error`: a wrapper can call that handle without testing the mutated method.
109
+ `--strategy redefine` still
110
+ reports all of these methods `unplaceable`.
111
+ - **The gem ships the agent skill.** `skills/mutineer/SKILL.md` is now
112
+ packaged in the gem, and the gemspec opts in as a
113
+ [Rails Hyperdrive](https://github.com/rails-hyperdrive/rails-hyperdrive)
114
+ companion (`hyperdrive_targets: "*"`, `hyperdrive_artifacts: "skill"`). In a
115
+ Rails app that bundles mutineer, `bin/rails hyperdrive:init` installs the
116
+ skill to `.claude/skills/mutineer/SKILL.md`. A test in the default suite
117
+ fails if the gemspec stops shipping the skill or drops the opt-in (#315).
118
+
119
+ ### Fixed
120
+
121
+ - **`--daemon` stops on MySQL older than 8.0 (#298).** The support matrix said
122
+ MySQL 5.7 is not supported, but `--daemon` ran on it. Mutineer now reads the
123
+ server version before it copies any worker database. MySQL older than 8.0
124
+ stops the run with `could not provision <base>: MySQL <version> is not
125
+ supported`. Pass `--no-daemon` (or set `daemon: false`) to stay serial.
126
+ MariaDB, MySQL 9 or later, and a server version Mutineer cannot read print
127
+ one warning and run.
128
+ - **An in-test database error scores `error`, not `killed` (#296).** When
129
+ the first failing test of a Minitest mutant run failed with an Active
130
+ Record connection or lock error (`ConnectionNotEstablished`, including pool
131
+ timeouts, `ConnectionFailed`, `Deadlocked`, `LockWaitTimeout`), the mutant
132
+ now scores `error` on `--daemon` and in-process. This includes an error in
133
+ `setup`. Errors are out of the score, so a lost database connection during
134
+ a run no longer raises the score. A stderr line names the error. A mutant
135
+ that really causes a deadlock, or that breaks connection-handling code, now
136
+ also scores `error`. More `error` verdicts can fail a `--threshold` run
137
+ through the existing no-verdict gate. Other database errors, such as a bad
138
+ SQL statement, still score `killed`. So does `ConnectionNotDefined`, which
139
+ Rails 8 raises for an unknown role or shard. Rails 7.2 raises a plain
140
+ `ConnectionNotEstablished` there, so such a mutant scores `error` on 7.2.
141
+ With `--matrix`, a database-failed test is never a killer and leaves its
142
+ row incomplete, even if an earlier assertion already killed the mutant.
143
+ - **An old temp file of the other mode no longer stops the boot (#287).**
144
+ Before the app boots, each mode sweeps the source directories. In 1.7.0
145
+ an in-process run removed only old `mutineer_mutant*.rb` files and the
146
+ daemon removed only old `mutineer_daemon*.rb` files, so a file the other
147
+ mode left made Zeitwerk raise. Now both boot sweeps remove an orphan of
148
+ either mode, and the daemon tells Zeitwerk to skip both names. You no
149
+ longer delete such a file by hand. A file of your own whose name only
150
+ starts with `mutineer_mutant` or `mutineer_daemon`, such as
151
+ `mutineer_mutant_helper.rb`, is no longer removed: a sweep now matches
152
+ only the temp file shape. An unlocked old file is removed even when its
153
+ creator's pid has been reused; a held file lock still protects it.
154
+ Do not run Mutineer older than 1.7.0
155
+ at the same time in the same checkout: it still writes temp files
156
+ without the dot, and a newer run's mutants error when Zeitwerk finds
157
+ one.
158
+ - **A second in-process run no longer deletes a live mutant file (#295).**
159
+ Each in-process run sweeps the source directories before its boot and
160
+ after its run. That sweep treated every `.mutineer_mutant*.rb` file as an
161
+ orphan, so it could delete another run's file between the write and the
162
+ load, and that mutant scored `errored`. Now the file is locked while it
163
+ loads, as the daemon's file is, and a sweep keeps a file whose creating
164
+ process still runs.
165
+ - **The `range` operator swaps endless ranges outside slices.** Before, it
166
+ skipped every endless range (`1..`, `1..nil`) as equivalent. But `(1..)`
167
+ and `(1...)` differ on `==`, `hash`, `exclude_end?` and `to_s`, so a test
168
+ can kill that mutant. Now the operator skips an endless range only when it
169
+ is a direct index argument of `[]`, `[]=`, `slice`, `slice!`, `byteslice`,
170
+ `bytesplice`, `values_at` or an index write, and the receiver is not a
171
+ class (`Array[1..]` is swapped). A Hash, Proc, or custom `[]`/`slice` can
172
+ still tell `1..` from `1...`, so those skips can hide a killable mutant. See
173
+ [Equivalent skips](https://davidteren.github.io/mutineer/equivalent-skips.html#endless-range).
174
+ A run that names `range` can get new mutants, new survivors and new mutant
175
+ ids. A new mutant can take the id of an older `range` mutant in the same
176
+ method, so an old `ignore:` id can name a different mutant. If you use
177
+ `range`:
178
+ - Delete the `ignore:` entries for `range` mutants.
179
+ - Save a new report with the same operators you gate with:
180
+ `mutineer run <paths> --operators <list> --no-since --format json --output <file>`.
181
+ Use it as your new baseline.
182
+ - Print new entries with
183
+ `mutineer triage <file> --reason TEXT (--id ID ... | --all)` and paste
184
+ them under `ignore:`. The command does not edit files.
185
+
186
+ Some new mutants are equivalent, for example a range used only with
187
+ `include?`, or a range in an Active Record query such as
188
+ `where(created_at: time..)`. Suppress them with `# mutineer:disable-line`
189
+ or an `ignore:` entry. (#299)
190
+ - **A test file given as a source after `--test` now exits 2 in more layouts
191
+ (#293).** The check missed Minitest `test_*.rb` files under `test/` or
192
+ `spec/`, and `*_test.rb` or `*_spec.rb` files in the same directory as a
193
+ `--test` file, such as the project root. Mutineer then mutated that file as
194
+ a source and never ran it as a test. With `--format json`, the stray file's
195
+ Minitest output also made the report invalid JSON. A support file with a
196
+ `test_` name under the top-level `test/` or `spec/` (other than
197
+ `test_helper.rb`) now also exits 2 when given as a source with `--test`.
198
+ - **A mutant on a later line of a call inside a one-line block can be killed
199
+ (#289).** A call can span several lines, such as
200
+ `users.map { |u| format("%s",` with arguments on the next lines. Mutineer
201
+ used to pick no tests for a mutant on a later line, so it was always
202
+ `no_coverage`. Now, when the lines of the statement give no tests, Mutineer
203
+ retries. It runs the tests that ran the first or last line of the
204
+ statement, never the `def` line. A kill counts. A survivor stays
205
+ `no_coverage` (or `ran_at_load`), because those tests may not have run it. A
206
+ score can rise with no test change. Such a mutant can now also end as
207
+ `error` or `timeout`. That counts toward the `--threshold` completeness
208
+ check.
209
+ - Mutineer reads its files and pipes as UTF-8 when `LANG` and `LC_ALL` are
210
+ unset (#303). Before, a non-ASCII character in a source file, a baseline, a
211
+ coverage cache, a triage report, `.mutineer.yml` (for `migrate`),
212
+ `db/schema.rb`, a `--since` diff, test-command output, or a daemon message
213
+ stopped the run with "invalid byte sequence in US-ASCII" (exit 2) or a
214
+ backtrace (exit 1). An invalid byte in test-command output now shows as
215
+ `\xNN`. Non-ASCII file and folder names are not covered yet (#346).
216
+ - **Upgrade note for `--test-command` with a custom failure exit code (#292).**
217
+ An RSpec setup with `--failure-exit-code 3` now scores every kill as
218
+ `error`. Use the default exit code, or a wrapper that maps a failure to
219
+ exit 1. An `error` verdict leaves the score, so the score can drop, and more
220
+ `error` verdicts can fail a `--threshold` run through the existing no-verdict
221
+ check. A mutant that only trips a SimpleCov `minimum_coverage` gate now
222
+ scores `survived` when the output has SimpleCov's gate message and a
223
+ passing Minitest or RSpec summary line. Without a summary line that
224
+ Mutineer recognizes, the gate's exit scores `error`, which leaves the
225
+ score. Either way the old false kill is gone, so the score can drop. A `--baseline` made before
226
+ this change can report new survivors and errors: make a new baseline after
227
+ the upgrade.
228
+ - **A `--test-command` exit other than 1 no longer counts as a kill (#292).**
229
+ Only exit 1 scores `killed`, the same rule as the in-process backend. One
230
+ exception: a SimpleCov gate exit whose summary reports a failing test also
231
+ scores `killed`. Any other non-zero exit scores `error`, such as a wrapper's
232
+ 137 after an out-of-memory kill.
233
+ - **A load crash under `--test-command` scores `error` (#292).** When the clean
234
+ run prints a Minitest or RSpec summary line, an exit 1 also needs a failing
235
+ test in that line. Code under test that calls `exit 1` or `abort` while the
236
+ default Minitest reporter runs its tests still scores `killed`, as in
237
+ process. Under RSpec or minitest-reporters, that case now scores `error`.
238
+ When a SimpleCov `minimum_coverage` gate replaces the exit code, the summary
239
+ line decides: a failing test is a kill, and a passing run is `survived`, as
240
+ in process. When the clean run
241
+ prints no summary line, Mutineer warns once and keeps the exit-code rule.
242
+
243
+ - **`--output .mutineer/run.json` on a fresh checkout.** The documented
244
+ report path no longer exits 2 when `.mutineer/` does not exist yet. The
245
+ output check now creates the cache directory (`cache_dir`) when it is the
246
+ missing parent. Any other missing directory still exits 2. This is a CLI
247
+ fix: the GitHub Action's `output` input still needs an existing directory
248
+ (#270, #340).
249
+
250
+ - **`--output` can no longer replace its own baseline.** When `--output`
251
+ and `--baseline` or `baseline:` in `.mutineer.yml` name the same file
252
+ (also through a symlink or hard link), a real `mutineer run` exits 2
253
+ before the run, with the GitHub Action's error adapted for the CLI. A dry run
254
+ still works because it writes no report. Before, a
255
+ failing run wrote its report over the baseline, and the next run passed
256
+ against it (#281).
257
+
258
+ - **`--threshold` compares the exact score, not the rounded one (#280).** The
259
+ score is rounded to one decimal for display, and the gate used to compare that
260
+ rounded value. A run with 1999 of 2000 mutants killed showed 100.0% and passed
261
+ `--threshold 100` with a survivor. The exit code, the Action, and the PASSED or
262
+ FAILED line now use the exact counts. When the rounded score points the other
263
+ way, the PASSED or FAILED line gives the counts and says that the score is
264
+ rounded.
265
+
266
+ - **The Minitest clean check now runs the tests in the order the mutant runs
267
+ use (#282).** Since 1.1.0, each mutant run used seed `1`, but coverage
268
+ capture, the clean checks and the `--daemon` mutant runs used a random
269
+ seed. An order-dependent suite could pass the clean check and then fail in
270
+ every mutant run, so each mutant scored a false `killed`. Every Minitest
271
+ run that Mutineer starts itself (not `--test-command`, see #338) now uses seed `1`,
272
+ or `SEED` when the environment sets it. Such a suite now stops the run
273
+ with "the unmutated suite is not green". The message names the configured
274
+ seed or default and notes that test helpers can change it. Capture, clean
275
+ checks and mutant runs all read `SEED` after loading the tests and helpers.
276
+ Check the listed test files with the same seed and helpers to investigate
277
+ the order-dependent test. A coverage cache from another
278
+ `SEED` in Mutineer's environment or an older version is captured again. A
279
+ `--coverage-from` capture from another `SEED` or an older version is
280
+ rejected with exit 2: capture it again with this version. The internal constant
281
+ `MinitestIntegration::STOP_AT_FIRST_FAILURE_SEED` is now `PINNED_SEED`.
282
+ One gap stays: when a mutant runs several covering test files, their test
283
+ classes can still run in a different order than in the combined clean
284
+ check. RSpec does not change.
285
+
286
+ - **`--daemon` SQLite workers load the schema file the app names (#317).**
287
+ The daemon always loaded `db/schema.rb` over an out-of-date worker copy,
288
+ even when `config/database.yml` sets `schema_dump:` to another file. An
289
+ app that keeps its SQLite schema in `db/schema_sqlite.rb` beside a MySQL
290
+ `db/schema.rb` errored every mutant. The booted daemon now asks Rails for
291
+ the file: `SCHEMA` when it is set, else `schema_dump:`, else
292
+ `db/schema.rb`. With `structure.sql`, a missing file, or
293
+ `schema_dump: false` (unless `SCHEMA` is set) it loads no schema, even
294
+ when a `db/schema.rb` exists: the worker keeps its copy of the test
295
+ database. A Postgres worker is a copy of the test database, so it was not
296
+ affected. MySQL already asked Rails for the file. It now also reads the
297
+ database's own `schema_format:` (Rails 8.1) and a string format such as
298
+ `"sql"`, the same as SQLite.
299
+
300
+ - **No `DATABASE_URL` password in load errors and mutineer's own messages (#288).**
301
+ A load error in the tool process (an
302
+ in-process `--boot` or `--rails` run, a source file, or a `require:`
303
+ file) no longer prints the raw password or a backtrace. The run prints a
304
+ `mutineer: cannot load <path>: ...` message (a `SyntaxError` keeps its code
305
+ excerpt) and exits 1. By default, a load error adds a hint to re-run with `--verbose`;
306
+ verbose output gives a redacted backtrace and cause chain. CLI error messages, the
307
+ fork child's error line, the worker crash text in the report, the daemon's
308
+ stderr lines (except bare passwords known only to the app after boot),
309
+ the failing test report and any load error from the
310
+ clean-suite and coverage checks, and the `--verbose` test command output
311
+ are redacted too. Output that app code or a test writes straight to
312
+ stderr in a fork or subprocess is not filtered (#341 tracks this and the
313
+ other known gaps). A `password=` query parameter in DATABASE_URL is now
314
+ hidden too.
315
+ Daemon stderr is now copied line by line as UTF-8, so an invalid byte
316
+ shows as U+FFFD. Output without a newline waits for a newline or EOF, so
317
+ credentials split across writes can be redacted together. A password that
318
+ equals the username no longer blanks the same text elsewhere (for example
319
+ `role "postgres"`). Each password form of 3 characters or fewer is hidden
320
+ only when no ASCII letter, digit or underscore touches either edge.
321
+ The limit applies separately to raw, decoded and escaped forms: `%61%62`
322
+ is still replaced inside longer text, while its decoded `ab` is matched
323
+ only as a whole token. A longer form is hidden wherever it appears,
324
+ and the password inside a URL is always
325
+ hidden.
326
+
327
+ - **`--strategy redefine` and path-relative methods.** Redefine now loads
328
+ the mutated method from a hidden file beside the source, as reload does.
329
+ It used the system temp directory before, so `__dir__` and
330
+ `require_relative` in the method pointed there, and every mutant of such
331
+ a method was falsely killed (#279). Redefine is also the default under
332
+ `--rails` without `--daemon`. When a source directory is not writable,
333
+ redefine still uses the system temp directory there, as before, and
334
+ the run warns that path-relative methods there can be falsely killed
335
+ (tracked in #339).
336
+
337
+ - `--test-command` now sets `DISABLE_BOOTSNAP_COMPILE_CACHE=1` for the test
338
+ command. Mutineer writes each mutant over the source file, and Bootsnap keys
339
+ its compile cache on path, size and whole-second mtime. Two same-size mutants
340
+ written in the same second could load the first one's cached code, so a
341
+ mutant could be scored on code that was not the mutant. Each mutant boot now
342
+ compiles the app again, which is slower. The variable works through
343
+ `require "bootsnap/setup"` on Bootsnap 1.7.0 or later; an app that calls
344
+ `Bootsnap.setup` itself must pass
345
+ `compile_cache_iseq: ENV["DISABLE_BOOTSNAP_COMPILE_CACHE"].nil?`, so only
346
+ mutant runs lose the cache. The `--daemon` path is unchanged (#285).
347
+
348
+ - **A mutant that two operators make is scored once** (#275).
349
+ `literal_mutation` and `string_literal` both turn `"hi"` into `""`, and
350
+ `chain_link` and `call_to_receiver` both turn `node.name.name` into
351
+ `node.name`. Each copy had its own id, so one surviving edit counted twice.
352
+ Now one copy runs: the copy of the operator that comes first in
353
+ `mutineer --list-operators`, whatever the `--operators` order. Only the
354
+ same text counts: a single-quoted `'hi'` still gives two mutants (`""` and
355
+ `''`). Both edits must also start on the same line: in a chain with one
356
+ call per line, the two copies start on different lines, so both are kept,
357
+ and `--since` filters each copy by its own start line.
358
+ - Every kept mutant keeps its id. The dropped copy's id no longer appears
359
+ in reports. Runs that use only one of these operators keep the same
360
+ mutants and ids.
361
+ - If you combine these operators, the mutant count and the score can move
362
+ with no code change, so a `--threshold` or `--baseline` gate can change
363
+ its result. Regenerate a `--baseline` file after upgrading, from a full
364
+ `--format json` run with no `--since`, `--only` or `--fail-fast` (pass
365
+ `--no-since` and `--no-fail-fast` when `.mutineer.yml` sets them). A
366
+ scoped report is refused as a baseline, and a partial one misses
367
+ mutants. In a full (unscoped) comparison, a dropped copy that survived
368
+ is listed as fixed.
369
+ - An ignore entry for one copy's id still ignores only that copy, as for
370
+ the #159 copies. So if you ignore the copy a report shows, the other copy
371
+ then runs and is reported, and it needs its own entry. Keep both entries:
372
+ a run with one operator alone still uses its entry, and
373
+ `mutineer migrate` keeps both as current ids. This also fixes the #159
374
+ copies: an `ignore:` list that names both copies of a repeated edit no
375
+ longer makes `mutineer migrate` exit 1.
376
+ - An old-format ignore entry that matches only a dropped copy gets the
377
+ old-id-format warning and counts in `summary.legacy_id_matches.ignore`,
378
+ so `mutineer migrate` updates it. For the #159 copies this is new: such
379
+ an entry was not counted before, so with one operator the count can go
380
+ up, and the warning can name an id that no report shows.
381
+ - Within a method, mutants now run and list in the `--list-operators`
382
+ order. This applies to any run whose `--operators` or `operators:` list
383
+ is in another order, so `--dry-run` lists and `--fail-fast` can differ.
384
+ - **A nested method's mutant under `--strategy redefine`.** Redefine now
385
+ also loads the mutated method into each method that encloses it. Before,
386
+ a call to the outer method defined the original inner method again, so
387
+ the mutant could falsely survive (#290). For a method nested in other
388
+ methods, redefine now gives the same verdict as reload when a test calls
389
+ an enclosing method by its own name. Mutant ids do not change, so
390
+ baselines and `ignore:` entries stay valid. Scores under redefine can
391
+ rise, and an `ignore:` entry added only to hide such a survivor can now
392
+ be removed. A method defined inside a non-builder block (for example
393
+ inside `define_method`), inside a `module_function` method, inside
394
+ `class << self` in a method, or called through an alias of the outer
395
+ method can still falsely survive under redefine. An enclosing method
396
+ that a memoizer or decorator wraps after its `def` loses that wrapper
397
+ when redefine loads it, so its verdict can differ from reload. Use
398
+ `--strategy reload` for those cases.
399
+
400
+ ### Changed
401
+
402
+ - **A release waits for a maintainer.** The Monday release-PR schedule is
403
+ gone, and pushing a `vX.Y.Z` tag leaves the gem unpublished. A human
404
+ collaborator with maintain or admin prepares a release PR by hand, tags by
405
+ hand, then runs the Release workflow on that tag with `confirm=publish`.
406
+ A required reviewer approves the `rubygems` GitHub environment before the
407
+ gem is pushed. A new Release run refuses to start the publish when that
408
+ environment is missing, has no required reviewers, or lets admins bypass
409
+ them. Re-running only the publish job of an earlier run does not repeat
410
+ that check. The publish job builds the commit that was dispatched, and it
411
+ stops before `gem push` if the tag moved while the job waited for
412
+ approval. The job no longer moves the floating major tag (`v1`). When the
413
+ release is the newest stable tag in its line, the job prints the command
414
+ and a maintainer runs it, so a ruleset can keep that tag for maintainers.
415
+ For a patch on an older line, it prints no command.
416
+ - **Load failures now use the runtime-error exit code (#288).** An
417
+ `ArgumentError` or `SystemCallError` raised while a boot file, a source
418
+ file or a `.mutineer.yml` `require:` file loads now exits 1 (runtime
419
+ error), instead of 2 (usage error). A missing boot or `require:` file now
420
+ exits 2 (usage error) with a one-line message. Before, it crashed with a
421
+ raw `LoadError` and a backtrace, and exited 1. With `--daemon` it is
422
+ checked before the daemon starts, so it exits 2 there too. Both moves bring
423
+ the code in line with the exit-code table in STABILITY.md, which already
424
+ lists a bad path as 2 and a runtime error as 1.
425
+ - **`call_to_receiver` now mutates last-call conversions such as `to_s` and
426
+ `to_i`.** `m[1].to_i` now gives the mutant `m[1]`. Before, the operator skipped the
427
+ same names as `chain_link`. Now it skips only `new`, `dup`, `clone`,
428
+ `freeze`, `itself` and `to_set`. `chain_link` does not change. Only runs
429
+ that list `call_to_receiver` in `--operators` (or `operators:`) change: they
430
+ get more mutants (113 more on Mutineer's own `lib/`). If you gate such a run
431
+ with `--threshold` or `--baseline`, expect new survivors: write a new
432
+ full-scope baseline with `mutineer run ... --no-since --no-fail-fast
433
+ --format json`, with no `--only`. A `to_s` mutant on a value that is already
434
+ a String is equivalent: suppress it with
435
+ `# mutineer:disable-line call_to_receiver` or an `ignore:` entry. (#274)
436
+ - Explain mutation testing before setup, with a runnable beginner guide and a
437
+ first run on one file. Simplify wording across the website and clarify Rails
438
+ setup, CI baselines, and reasons for ignoring a mutant.
439
+
440
+ ## [1.7.0] - 2026-10-23
441
+
442
+ ### Added
443
+
444
+ - **Call-to-receiver operator** (Tier-2, opt-in via `--operators`):
445
+ `call_to_receiver` replaces the last call of a chain with its receiver, with
446
+ the arguments and block of that call (`user.full_name` -> `user`). The mutant
447
+ survives when no test checks what that last call does. It does not overlap
448
+ with `chain_link`: `chain_link` drops a call in the middle of a chain, and
449
+ `call_to_receiver` drops only the last call. The two give the same source
450
+ only when the last call repeats the call before it (`node.name.name`). It
451
+ skips the same names as `chain_link`, and it skips operator calls and
452
+ setters.
453
+ - **Reasons on ignored mutants.** Text after `--` on
454
+ `# mutineer:disable-line`, and a `.mutineer.yml` `ignore:` mapping
455
+ (`id` plus `reason`), is stored on the ignored mutant. The JSON report
456
+ (`schema_version` 1.8) and the HTML report show it. A mapping with no
457
+ `id`, or with an unknown key, warns. Mutineer 1.7 is the first version
458
+ that reads a mapping. An older version matches no mutant to a mapping
459
+ and does not warn, so the mutant it names is not ignored. Upgrade
460
+ every gate that reads the file before you add a mapping.
461
+ `mutineer migrate` rewrites the old id inside a mapping and keeps its
462
+ reason.
463
+ - **`mutineer triage`.** It prints `ignore:` mapping entries for survivors
464
+ in a JSON report. `--reason` is required. Pass `--all` or `--id`. It
465
+ does not edit files.
466
+ - **Equivalent-skip page.** The docs list every built-in chain-link skip
467
+ and the endless-range skip, and why each one is equivalent.
468
+ - **Postgres worker databases for `--rails --daemon`.** Each worker gets
469
+ `<base>-mutineer-<N>`, copied from the test database before mutants run.
470
+ A second run cannot drop a database another live run holds. An app with
471
+ more than one database config runs one worker and says so once.
472
+ The worker databases stay after the run.
473
+ - **MySQL 8 worker databases for Minitest on `--rails --daemon`.** Each worker gets
474
+ `<base>-mutineer-<N>` on `mysql2` or `trilogy`, with the base shortened to fit
475
+ MySQL's 64-byte name limit. Mutineer creates the
476
+ database, loads `schema.rb` or `structure.sql`, and copies rows once at
477
+ the start. Triggers from the schema do not fire on the copied rows.
478
+ Mutineer creates them again after the copy.
479
+ A second run cannot drop a database another live run holds.
480
+ That work uses the TLS and timeout settings from the database config.
481
+ MariaDB is not tested. MySQL 5.7 is not supported. The worker databases
482
+ stay after the run.
483
+ - **`mutineer migrate`.** It rewrites old-format ids in `.mutineer.yml`
484
+ `ignore:` to the current ids. It keeps comments and every other line.
485
+ One old id that matches several mutants becomes every new id. An id that
486
+ matches nothing stays, and the command exits 1. A block scalar under
487
+ `ignore:` is not supported: the command exits 2 and does not change the
488
+ file. `--dry-run` prints each change and writes nothing. It does not
489
+ rewrite a baseline. Generate a new baseline with `--format json`. An
490
+ old-id warning names `mutineer migrate` and says that this becomes an
491
+ error in Mutineer 2.0. The baseline warning says to generate a new
492
+ baseline with `--format json`.
493
+ - **`mutineer init`.** It writes a commented `.mutineer.yml` with the default
494
+ operators. `since` stays commented, so the first run is a full scan.
495
+ `init --rails` also sets `rails: true` and prints the first run command.
496
+ An existing file is kept unless you pass `--force`.
497
+ - **Rails rollout guide.** The page walks from one model, to a report-only CI
498
+ job, to a `--since` and `--baseline` pull request gate, to `--threshold`
499
+ on chosen folders. It has a GitHub Actions recipe and a GitLab CI recipe.
500
+ - **A mutation-testing primer in the README.** "What is mutation testing?"
501
+ walks through one small example, from a surviving mutant to the test that
502
+ kills it, and says what each report row means and what to do with a
503
+ survivor. The usage block lists all four commands.
504
+ - **A production-ready section and a stability contract.** The README opens
505
+ with a support matrix for Ruby, database, framework, and parallelism.
506
+ `STABILITY.md` lists what a release keeps and what 2.0 will change.
507
+ `SECURITY.md`, `CONTRIBUTING.md`, and GitHub issue forms are new.
508
+ The docs home page takes the same section from the README at site build.
509
+ - **`--allow-empty` and `allow_empty:`.** A run with no mutants now warns
510
+ that Mutineer 2.0 will fail it, unless `--allow-empty` marks it as expected.
511
+ A `--since` run whose changes hold no mutants does not warn: it says the
512
+ changes hold nothing to test. A `--since` run with no mutants even before
513
+ scoping still warns. The exit code does not change in 1.x.
514
+ - **`--no-daemon`.** It beats a `.mutineer.yml` `daemon: true` for one run,
515
+ like `--no-fail-fast`. A Minitest `--rails` run without a `daemon` value now
516
+ prints a notice that 2.0 uses `--daemon` by default for `--rails`;
517
+ `--no-daemon` (or `daemon: false`) keeps the run serial and stops the
518
+ notice.
519
+ - **"Did you mean" hints.** Unknown names in `--operators`, in
520
+ `.mutineer.yml` `operators:` and keys, and in `# mutineer:disable-line`
521
+ markers get the closest valid name. The `.mutineer.yml` warnings also say
522
+ that 2.0 makes them errors.
523
+ - **`--coverage-from FILE` lets parallel shards share one coverage capture.**
524
+ A `--rails`/`--boot` run reads the `coverage.json` of an earlier run with
525
+ the same tests over these sources or more. It skips the capture. Each test
526
+ that covers one of its sources still runs alone, as on a cache hit, because
527
+ a mutant runs only those tests. A test that covers none of them does not,
528
+ so a shard runs far fewer tests alone than a full suite. All tests then run
529
+ once together, and the run saves its own cache.
530
+ Boot-mode caches now also record each source's fingerprint, the ownership
531
+ list and a digest of the other inputs. A capture that does not fit is an
532
+ error (exit 2), never a silent recapture. So is one where loading its other
533
+ sources ran these sources' code, which happens under lazy loading with
534
+ `--strategy redefine`. Without boot mode, and with `--daemon`,
535
+ `--test-command` or `--dry-run`, the flag warns that it has no effect.
536
+
537
+ ### Changed
538
+
539
+ - **Rails test workers stay off during a mutant run.** Mutineer sets
540
+ `PARALLEL_WORKERS` to `1` for in-process, `--daemon`, and `--test-command`
541
+ runs. A value you already set is replaced, and Mutineer prints one line.
542
+ The coverage cache stores the `PARALLEL_WORKERS` value, so a cache from an
543
+ older version rebuilds once. `--test-command` also sets `DISABLE_SPRING=1`.
544
+ The README explains `parallelize`, Bootsnap, and Redis after a fork.
545
+ - **`--test-command` exit codes 126 and 127 are scored `error`, not
546
+ `killed`.** A wrapper that could not start the suite ran no test. Under
547
+ `--threshold`, such a run can now score lower or fail the no-verdict limit,
548
+ where before it passed on false kills.
549
+ - **A run with errored mutants and no `--threshold` says so.** Errors are not
550
+ in the score, so they do not fail the run; the message says what
551
+ `--threshold` would enforce.
552
+ - **`--since` also narrows suppressed mutants.** A scoped report lists only
553
+ `ignored` mutants on changed lines, as `--dry-run --since` already did.
554
+ - **The empty-run message moved from the human report to one stderr warning
555
+ for every format.** "No mutations generated" is gone. An empty `--since`
556
+ run prints "nothing to test in the changes since REF" instead.
557
+
558
+ ### Fixed
559
+
560
+ - **Daemon errors no longer show the database password.** Rails parses
561
+ `DATABASE_URL` itself, and a malformed URL makes it raise an error that
562
+ quotes the whole URL. The daemon sent that error to the terminal when
563
+ the app failed to boot, and the same could happen when it set up worker
564
+ databases or the coverage map, and in a `--verbose` coverage warning.
565
+ Mutineer now replaces the password in any URL, and the `DATABASE_URL`
566
+ password anywhere else (escaped or cut short included), with
567
+ `[REDACTED]` before it reports the error.
568
+ - **`--strategy reload` runs concern files with an `included` or `prepended`
569
+ block (#256).** Every mutant in such a file was `errored`: ActiveSupport
570
+ raised `MultipleIncludedBlocks` (or `MultiplePrependBlocks`) because the
571
+ mutant loads from a temp file with another path. Before each reload mutant
572
+ loads, in-process and on the daemon, the forked child now forgets the blocks
573
+ that the source file stored, so methods in the concern body and in
574
+ `class_methods` are killed or survive as usual. A block the mutant's load
575
+ does not store again (a concern under an `unless defined?` guard) is put
576
+ back. A method inside an
577
+ `included` or `prepended` block is `unplaceable` under reload too: the block
578
+ does not run again in a class that already includes or prepends the
579
+ concern, so the mutant would falsely survive. That includes a method of a
580
+ class defined inside the block. Use `--test-command` to run those mutants.
581
+ - **No heredoc opener without its body.** A mutation that kept a heredoc
582
+ opener but replaced the lines of its body gave source that does not parse,
583
+ such as `operand_removal` on `foo(<<~EOS) ||` with the body and `bar` on
584
+ the next lines. The mutant showed only as `skipped (invalid)`. Now the
585
+ operator does not emit it.
586
+ - **An RSpec run that fails only on an error outside examples scores the
587
+ mutant `errored`, not `killed`.** A spec file that raised while loading, or
588
+ a failing `before(:suite)` hook, made RSpec exit 1, and every mutant was
589
+ scored `killed`. On a Rails app, `rails_helper` called `SimpleCov.start`
590
+ after `--rails` had suspended Coverage (#228), so each spec file raised as
591
+ it loaded, and 18 of 18 mutants were scored `killed`; 3 of them survive.
592
+ Now the runner returns 2 when RSpec recorded an error outside examples and
593
+ no example failed, so the mutant is `errored`: out of the score and in
594
+ `no_verdict`, so that run now fails `--threshold` instead of passing at
595
+ 100%. A failed example still kills.
596
+ Minitest and `--daemon` already score a test file that raises at load as
597
+ `errored`. `--test-command` sees only the exit status and still scores it
598
+ `killed`.
599
+ - **A Rails daemon boots again while a mutant file is still open.**
600
+ The file stays when another process holds it. The next boot skips
601
+ that file name instead of stopping.
602
+ - **A daemon crash no longer leaves a mutant file in your source folder
603
+ (#250).** When a daemon dies during a mutant, its child dies a moment
604
+ later. The new daemon cleaned up before that, so the child's file stayed.
605
+ The next Rails boot then failed on the file name. Each daemon run now
606
+ cleans up again when it ends or stops early. It waits up to 1.5 seconds
607
+ for the child to go. A file whose owner still runs after that stays
608
+ until the next daemon run removes it. On Linux, a file whose owner is a
609
+ zombie (in a container whose pid 1 does not reap it) is now removed.
610
+ With `--jobs N`, an error in one worker stops the others after their
611
+ current mutant, and a Ctrl-C quits every worker daemon before the run
612
+ ends.
613
+ - **SimpleCov in a test helper no longer breaks every mutant under
614
+ `--rails` or `--boot` (#248).** After the coverage map is built, mutineer
615
+ pauses Ruby's coverage (#228). SimpleCov saw the paused coverage as off and
616
+ tried to start it. Ruby refuses that while coverage is paused, so the test
617
+ helper raised in every mutant. Now a start in a mutant first stops the
618
+ paused coverage. A mutant whose tests start nothing keeps it paused and pays
619
+ nothing. This applies to `--daemon` too.
620
+ - **Methods in an ActiveSupport::Concern `class_methods` block are mutated
621
+ under `--strategy redefine` (#252).** ActiveSupport puts these methods in
622
+ the concern's `ClassMethods` module, and each includer gets them as class
623
+ methods. Mutineer named them as instance methods of the concern itself.
624
+ Redefine (the `--rails` default) then loaded each mutant onto the concern.
625
+ The tests called the includer's method, so every mutant falsely survived.
626
+ A concern with an instance method of the same name failed the other way:
627
+ the mutant replaced that instance method, so tests calling it ran the
628
+ wrong method and failed (an ArgumentError, when the arities differ), and
629
+ the mutant counted as killed whatever it changed. Both false survivors
630
+ and false kills are gone. An earlier redefine score is unreliable for
631
+ any file with a `class_methods` block: too low from false survivors, or
632
+ too high from false kills. Re-run those files.
633
+ These methods are now named `Concern::ClassMethods#name`, and redefine
634
+ loads the mutant onto that module. This applies to a module that ran
635
+ `extend ActiveSupport::Concern` earlier in the same file. The mutant ids of
636
+ these methods change, because an id contains the qualified name (owner and
637
+ method). An instance
638
+ method with the same name, later in the same file, can get a new id too.
639
+ An `ignore:` entry or a `--baseline` survivor for one of these methods no
640
+ longer matches. Replace it with the new id from a new run.
641
+ - **Methods in other `class_methods`, `included` and `prepended` blocks are
642
+ `unplaceable` under `--strategy redefine` (#252).** ActiveSupport runs an
643
+ `included` or `prepended` block in each includer, so no constant names the
644
+ class that owns its methods. A `class_methods` block that Mutineer cannot
645
+ tie to a concern has the same problem: one in a def, in Rails'
646
+ `concerning`, in an unassigned `Module.new`, or in a module that does not
647
+ run `extend ActiveSupport::Concern` earlier in the file. Redefine loaded each
648
+ mutant onto the enclosing module, and the mutant could falsely survive. Now
649
+ redefine reports these mutants as `unplaceable` and does not run them. Like
650
+ every `unplaceable` mutant, they leave the score and do not count toward
651
+ `--threshold`, so a gate that failed on these false survivors can now pass.
652
+ Their names and mutant ids do not change. `--strategy reload` runs them, except a
653
+ method in an `included` or `prepended` block (see #256 above). Another library's
654
+ method with one of these names is `unplaceable` under redefine too, even
655
+ when that library runs the block in the module itself and redefine used to
656
+ run it correctly. Mutineer cannot tell that library from ActiveSupport, so it
657
+ does not guess. For that other library's mutants, use `--strategy reload`.
658
+ - **A file in a namespace directory scores under `--rails --strategy reload`
659
+ and `--rails --daemon` (#253).** Mutineer writes each mutant to a temp file
660
+ next to the source and loads it. With lazy loading, loading it can be the
661
+ first time Zeitwerk scans that directory, such as `app/models/billing/`.
662
+ Zeitwerk then raised `Zeitwerk::NameError` on the temp file's name, and the
663
+ mutants of the file errored. Parallel daemon workers hit the same error on
664
+ each other's files. Now the temp files are hidden: `.mutineer_mutant*.rb`
665
+ and `.mutineer_daemon*.rb`. Zeitwerk skips hidden files, in every loader.
666
+ The cleanup sweeps still remove a file an older version left without the
667
+ dot. Each mode sweeps its own files before the app boots: an in-process run
668
+ now removes an old `mutineer_mutant*.rb` first, and the daemon removes an
669
+ old `mutineer_daemon*.rb`. An old file of the other mode still stops the
670
+ boot, so delete it by hand. Eager loading, the default on CI, scans every
671
+ directory at boot, so it never hit the error.
672
+ - **A mutant on a later line of a multi-line `&&` or `||` can be killed
673
+ (#254).** Ruby counts only the first line of a statement. For code that runs
674
+ only sometimes on a later line, such as the right side of `verified &&` on
675
+ its own line, Mutineer picked no tests, so the mutant was always
676
+ `no_coverage`, however good the tests were. Now it runs the tests that ran
677
+ the statement. A kill counts. A survivor stays `no_coverage`, because the
678
+ run cannot tell whether those tests reached it, so no survivor is added and
679
+ a score can rise with no test change. Such a mutant can now also end as
680
+ `errored` or `timeout`; like any mutant with no verdict, that counts toward
681
+ the `--threshold` completeness check, so a failure is reported, not hidden.
682
+ This also applies to a later `when` condition, the value of `x rescue y`,
683
+ `&.` arguments and an `||=` value on a later line, and to `--daemon`. A
684
+ branch of a ternary or `if`, and the body of `x if c`, keep the verdict they
685
+ had before.
686
+
9
687
  ## [1.6.0] - 2026-10-08
10
688
 
11
689
  ### Added
@@ -1150,6 +1828,8 @@ Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
1150
1828
  - `.mutineer.yml` configuration (CLI > config > default precedence).
1151
1829
  - Byte-correct source handling for multibyte (UTF-8) sources.
1152
1830
 
1831
+ [1.8.0]: https://github.com/davidteren/mutineer/releases/tag/v1.8.0
1832
+ [1.7.0]: https://github.com/davidteren/mutineer/releases/tag/v1.7.0
1153
1833
  [1.6.0]: https://github.com/davidteren/mutineer/releases/tag/v1.6.0
1154
1834
  [1.5.0]: https://github.com/davidteren/mutineer/releases/tag/v1.5.0
1155
1835
  [1.4.0]: https://github.com/davidteren/mutineer/releases/tag/v1.4.0