mutineer 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50113a063a85737ad99476f85e78cb2ac015f267018d19ba6350ba36ff4ac6df
-  data.tar.gz: c12343a00d2df6d495859644c326bc650e33d013ddf009f2648c06a199aceb86
+  metadata.gz: eeac45268c75073f522daa5d26dd65fe425ae66b604cfb7543c0b529ab71f2e6
+  data.tar.gz: 834755a3b106f02013ef75b9515f18e692d1c6ac219bee42b837da8a6f696fc7
 SHA512:
-  metadata.gz: a170b15c6883a4dcec6a2798c3b102a5f9c9ded1f46c166df98d0e5bdf5b891ca5b24892efe06245680b45a94da38638adc36ca9a48a48d2ac1c07b29126f173
-  data.tar.gz: a30272ff6afb48dd666d6945c6532d987ef335e0e78dc422420cf26cdbec639ee1c850118a10ba25e10a426a2644b3926e39698126eaad0646707a4f2be2e719
+  metadata.gz: '092252eef7f756e5fa117784b7c3696777127b0f1f1b96825c38d99a9f8d362a23416ad2351685e62bd780563a2b7fa2eab0e926c10bee3e293293ff88e0d28d'
+  data.tar.gz: 02344ad3f678a639a37f0272577e50e5f189e585a9246be0b0f1451202a03c63cb57e013181e349ab7b4db04f36fb2333e2de7d864063c4da92d4394f5dce6b3

data/CHANGELOG.md

@@ -6,6 +6,230 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-10-08
+
+### Added
+
+- **An `unplaceable` mutant status.** Under `--strategy redefine`, a mutant in
+  a method whose class or module has no constant name is not run. It is left
+  out of the score and, unlike `uncapturable`, out of `no_verdict`, so it does
+  not fail `--threshold`. The human report gives it an `Unplaceable:` row, the
+  HTML report a count, and the JSON report `summary.unplaceable` and an
+  `unplaceable[]` list; `schema_version` is `1.7`.
+- **The agent skill installs with `gh skill` and `npx skills` (#125).** It
+  moved from `docs/skill.md` to `skills/mutineer/SKILL.md`, the layout of the
+  Agent Skills specification, so `gh skill install davidteren/mutineer
+  mutineer` finds it and `npx skills add davidteren/mutineer --skill mutineer`
+  installs one `SKILL.md` instead of the whole `docs/` site. The site build
+  copies that file to `skill.md`, so its URL still works. The skill's
+  description now says when to use it, and the README shows how to install it.
+- **A `ran_at_load` mutant status** (#187). A mutant on a method-body line
+  that ran while the app booted or its class loaded gets this status when it
+  survives, or when only the load ran the line. A kill stays a kill. It is
+  left out of the score and out of `no_verdict`, so it does not fail
+  `--threshold`. The human report gives it a `Ran at load:` row that points
+  to `--test-command` to verify these mutants, the HTML report a count, and
+  the JSON report `summary.ran_at_load` and a `ran_at_load[]` list, within
+  schema `1.7`.
+
+### Changed
+
+- **Mutants no longer run under Coverage with `--boot` or `--rails` (#228).** Coverage
+  starts before the app boots so the coverage map can be built, and it used to
+  keep running in every mutant fork after that, though nothing read it. It is
+  now suspended once the map is built, from a fresh capture or from the cache.
+  Coverage that a host process started before the run is left running.
+  On a small app whose test calls tiny methods in a loop, the CPU time of a
+  whole in-process `--boot` run fell from 0.76s to 0.57s (median of five). On
+  the Rails fixture app the run is mostly boot, and the change is within noise
+  (1.61s before, 1.60s after). `--daemon` runs its mutants in worker daemons
+  that never start Coverage, so its time does not change (3.48s before, 3.44s
+  after); the map-building daemon now suspends Coverage after the map too.
+- **A mutant runs its paired test files first, then the cheapest (#203).** The
+  covering test files used to run in the order the coverage map stored them,
+  so a mutant that one fast file kills could still score `timeout` when slow
+  files ran first. Now the files that pairing finds for the source run first,
+  then the rest from fastest to slowest by the time each file took during
+  coverage capture, less the fastest file's time (the startup cost each
+  capture pays). The order is fixed for a given cache. Costs compare in
+  doubling buckets, so files of close cost keep their path order when a
+  rebuilt cache measures them again; a file near a bucket edge can still move,
+  so keep `.mutineer/` between CI runs for the most stable `--baseline`. The
+  order applies to Minitest (after the seeded class shuffle, with
+  `parallelize_me!` classes still last) and to RSpec. `--daemon` runs every
+  covering test with no stop, so the order does not change its verdicts. The
+  coverage cache now saves these timings, so a cache from an earlier version
+  rebuilds once. A complete run gives the same verdicts and `--matrix` rows,
+  but the new order can change which mutants time out, so a `--baseline` gate
+  can see a one-time change on upgrade.
+- **Job selection moved from `Mutineer::Runner` to a new `Mutineer::JobPlan`
+  module (#75).** The in-process runner, the `--daemon` backend and
+  `--dry-run` share it, so each file now requires what it uses and no
+  `require_relative` cycle exists in `lib/mutineer`. The moved methods are
+  `collect_jobs`, `filter_since`, `coverage_selection`, `ran_at_load?`,
+  `load_verdict`, `abort_if_unclean!`, `test_load_roots`, `source_dirs`,
+  `sweep_orphans`, `suppress_map`, `suppressed?` and `result_keys`. These were
+  internal methods, so `Runner` keeps no copies. Runs, reports and caches do
+  not change.
+
+### Fixed
+
+- **An endless method that only the tests call is no longer `no_coverage`
+  under `--rails`, `--boot` or `--daemon` (#209).** Ruby counts no line when
+  an endless method such as `def half(x) = x / 2` runs, only its `def` line
+  when it is defined. The boot defines it before any test runs, so the forked
+  coverage capture never saw that line run. Coverage now also
+  counts methods (`Coverage.start(lines: true, methods: true)`), and a test
+  that calls such a method covers its `def` line. Coverage caches from earlier
+  versions rebuild once.
+- **`module_function :name` in a reopened module inside `class << self`
+  promotes the method from the earlier opening (#216).** Ruby treats both
+  openings as one module, but Mutineer matched them only within one body, so
+  it named the method `#<Class:App>::M#c` instead of `#<Class:App>::M.c`.
+  The two openings now match by the module's full name. A module whose name
+  Mutineer cannot be sure of still matches only within its own body: a path
+  such as `self::X` or `Foo::X` written directly inside `class << self`, a
+  name under an anonymous class, or a module in a `class << self` inside a
+  method or a `class_eval` block. A `module self::X` in a block, or a
+  `self::X = ...` in a `class_eval` block, matches only openings in the same
+  block. A `self::X` like these now also stays apart from a
+  module of the same name outside `class << self`, where a `module_function`
+  in that module used to promote its methods.
+- **A `module self::X` or `class self::X` in a block is `unplaceable` under
+  `--strategy redefine` (#229).** In a block, `self` is not always the
+  enclosing class: in `Other.class_eval do` it is `Other`, and in
+  `Foo = Class.new do` it is the new class. Mutineer gave these modules a
+  known owner on the enclosing namespace, so redefine loaded the mutant onto
+  a module the tests never use, and the mutant could falsely survive or
+  score `error`. Such a module, everything nested in it, and a
+  `self::X = ...` in a block that does not build a class now have
+  their owner unknown: redefine reports their mutants as `unplaceable`, and
+  `--strategy reload` still runs them. In a `Data.define`, `Struct.new`,
+  `Class.new` or `Module.new` block, the module is now named under the
+  builder's constant (`Outer::Foo::X#c`, was `Outer::X#c`), so the subject
+  names and mutant ids of those methods change. `self::X` directly in a class
+  or module body is unchanged.
+
+- **`--daemon` worker databases start as a copy of the test database
+  (#222).** Each worker slot's SQLite database used to start from
+  `db/schema.rb` alone. Rows the daemon wrote while it booted, in
+  initializers or `--require` files, were only in the base test database, so
+  a test that read them passed in-process but failed under `--daemon`. On its
+  first use, a worker database is now a copy of the base test database (schema
+  and rows, made with the SQLite online backup API). The worker still loads
+  `db/schema.rb` when the copy's schema differs from it (another schema
+  version, or another or no `schema_sha1` checksum in `ar_internal_metadata`),
+  for example when the test database is empty, out of date, or set up with a
+  plain `load "db/schema.rb"`. That load drops the
+  copied rows of the tables it defines.
+- **Standalone coverage capture loads the `--require` files (#217).** A run
+  without `--boot` requires the sources and then each `--require` (or
+  `require:`) file before it forks the mutants, but the coverage capture
+  loaded only the sources. A source method that a `--require` file called
+  while it loaded was then not seen as run at load, so its mutant was a false
+  `survived` instead of `ran_at_load`. The capture and the clean-suite check
+  now load the `--require` files after the sources. With or without
+  `--boot`, the coverage cache rebuilds when one of them changes, is added,
+  is removed, or moves in the load order.
+- **`--daemon` loads the `--require` files (#220).** The daemon booted the app
+  but never loaded the `--require` (or `require:`) files, so a test that
+  needs one failed under `--daemon` and passed in-process. A source method
+  that such a file called while it loaded was also not seen as run at load,
+  so its mutant could be a false `survived` instead of `ran_at_load`. The
+  daemon now loads the files after the app boots, as an in-process run does,
+  and the daemon's coverage cache rebuilds when one of them changes.
+- **The release workflow publishes only stable tags** (#161). Its trigger,
+  `v*.*.*`, also matches a prerelease tag such as `v1.3.1-rc1`, and the only
+  guard checked that the tag matched `Mutineer::VERSION`. A prerelease tag
+  could then publish the gem and move the floating major tag (`v1`) that
+  Action users pin. The workflow now stops with a clear error before any
+  publish step unless the tag is a stable `vMAJOR.MINOR.PATCH`.
+- **Coverage capture keeps to `capture_timeout` from start to finish.** Under
+  `--boot` and `--daemon`, a hung test file ignored the timeout and blocked
+  the run; it is now skipped as "timed out", like a standalone capture. A
+  process that a test started and left running could keep the result pipe
+  open and make a boot-mode capture wait for it to exit. Each capture now runs
+  in its own process group, and a timeout stops the whole group, not only the
+  test process. A capture whose test finished just before the deadline could
+  also lose its valid result and report "invalid coverage output"; it now
+  gets a short grace period to read the result. (#101, #129)
+- **`--daemon` no longer waits forever on a daemon that stops answering**
+  (#101). A mutant whose verdict has not arrived 30 seconds after its own
+  timeout is scored `error`, and the daemon is killed and respawned, as after
+  a crash. A boot that has not finished after 600 seconds ends the run with a
+  message that says so (it is not retried by a second daemon), and shutdown no longer waits on a stuck daemon.
+
+- **A method in a `Data.define`, `Struct.new`, `Class.new` or `Module.new`
+  block belongs to the class or module the block builds.** In
+  `class App; Argo = Data.define(:url) do def self.load = ...; end; end` the
+  subject is now `App::Argo.load`, not `App.load`; at the top level it was
+  `.load`, with no owner. Under `--strategy redefine` (the `--rails` default)
+  the mutated method was loaded into the wrong class, so the real method never
+  changed and every such mutant falsely survived. The class or module is
+  named after the constant it is assigned to with `=`, `||=` or `&&=`, through
+  parentheses or `begin`, resolved as Ruby resolves the assignment: `X` in the
+  current namespace, `::X` and any path at the top level from `Object`,
+  `self::X` under the current class. When it cannot be named statically (no
+  constant, a relative path such as `User::Permission` inside a namespace, or
+  a constant assigned in `class << self`), redefine reports its mutants with
+  a new status, `unplaceable`, rather than load them onto the wrong class;
+  reload still runs them. `module_function :name` in a `Module.new` block
+  promotes that module's method. Mutant ids for these subjects change:
+  regenerate `ignore:` entries and baselines that name them.
+- **The automated release PR gets its required CI checks without a token
+  secret (#85).** `release-pr.yml` pushes the release branch with the default
+  `GITHUB_TOKEN`, which starts no other workflow, so the four required checks
+  never ran and the PR stayed blocked until a person closed and reopened it.
+  The job now dispatches `ci.yml` on the release branch (CI gained a
+  `workflow_dispatch` trigger), and those runs report the required checks on
+  the PR's head commit. With a `RELEASE_PR_TOKEN` secret set, the push
+  triggers CI as before and no dispatch is made.
+- **Code that runs while the app boots or a class loads no longer gives a false
+  `survived` or `no_coverage`** (#187). A class body such as
+  `ALL = [price(3)].freeze` runs `price` before any mutant is applied. Under
+  `--strategy redefine` (the `--rails` default) the load never runs again, so
+  a test that checks `ALL` saw the original value and the mutant falsely
+  survived. Under `--rails` or `--boot` no test was credited with lines that
+  ran during boot, so those mutants were falsely `no_coverage`. Mutineer now
+  reads the lines that ran at load (from the boot, or from requiring the
+  sources in standalone capture) and reports these mutants as `ran_at_load`,
+  under both strategies and with `--daemon`: reload runs the file's class body
+  again but not an initializer or another file's code, so a survivor there is
+  not trusted either. Under `--boot` with redefine, a
+  lazily loaded class (Zeitwerk, `autoload`) is loaded before the boot lines
+  are read, so its class body counts as load too. A baseline survivor that is
+  now `ran_at_load` is listed as fixed, not as a regression. Standalone
+  coverage caches from earlier versions rebuild once. A one-line or endless
+  `def` keeps its body on the `def` line, which Ruby counts when the method is
+  defined, so Mutineer reads the method's call count at load for it instead
+  (#209).
+- **A boot file that prints to stdout no longer breaks the daemon handshake
+  (#102).** Output from `puts`, `STDOUT`, `$stdout`, a direct fd 1 write, or a
+  subprocess reached the JSON channel before the ready message, so the daemon
+  failed with "daemon exited before the handshake". The daemon now keeps a
+  private copy of its original stdout for the protocol and points the app's
+  stdout at stderr, where that output stays visible.
+- **A class or module opened inside `class << self` belongs to the singleton
+  class (#208).** In `class App; class << self; class Q; def q1 ...` the
+  subject was `App::Q.q1`, a class method of a constant Ruby never defines:
+  `Q` is `App.singleton_class::Q`, and `q1` is an instance method. It is now
+  `#<Class:App>::Q#q1` with no known owner, as is a class or module opened in
+  a builder block there, and anything nested in either. Inside a builder
+  block, `class << self` opens the built class's singleton class, so a class
+  or constant there is named under it, for example `#<Class:App::P>::W`. Under
+  `--strategy redefine` loading the mutant raised `NameError` and scored
+  `error`; redefine now reports these mutants as `unplaceable`, and reload
+  still runs them. A compact `class Foo::X` and a top-level `class ::X` or
+  `::X = Class.new do` there are named as written (`::X` as `X`, now with
+  instance methods) and are owner-unknown too: redefine reopens them without
+  the singleton class, so constants their bodies look up through it would not
+  resolve. `module_function :name` in a body whose owner is unknown now
+  promotes that body's own methods, wherever it is: a `Foo::X = Module.new`
+  block's `c` is `Foo::X.c`, not `Foo::X#c`, and a def in an anonymous
+  `Class.new` block is no longer promoted by a `module_function` of the module
+  around it. Mutant ids for these subjects change: regenerate `ignore:`
+  entries and baselines that name them.
+
 ## [1.5.0] - 2026-10-06
 
 ### Added
@@ -926,6 +1150,7 @@ Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[1.6.0]: https://github.com/davidteren/mutineer/releases/tag/v1.6.0
 [1.5.0]: https://github.com/davidteren/mutineer/releases/tag/v1.5.0
 [1.4.0]: https://github.com/davidteren/mutineer/releases/tag/v1.4.0
 [1.3.0]: https://github.com/davidteren/mutineer/releases/tag/v1.3.0

data/README.md

@@ -21,7 +21,9 @@ for how the two tools differ.
 - **Coverage-guided** — each mutant runs only the test files that cover its line.
 - **Stops at the first failing test** — in-process runs (not `--daemon` or
   `--test-command`) stop a mutant's test run at the first failure, unless
-  `--matrix` asks for every covering test.
+  `--matrix` asks for every covering test. The source's paired test files run
+  first, then the rest from fastest to slowest in doubling steps (under 1 s,
+  1 to 3 s, 3 to 7 s, and so on); files in one step run in path order.
 
 📖 **[mutineer.github.io →](https://davidteren.github.io/mutineer/)** — overview, operators, and usage.
 
@@ -119,6 +121,18 @@ different entry point. Boot mode requires at least one `--test` file and is
 coverage-guided — each mutant runs only the test files that exercise its line
 (coverage is captured by forking the booted app, then cached).
 
+Some code runs while the app boots or a class loads, for example a class body
+that calls a method to build a constant, a `to_prepare` initializer, or a
+`--require` file that calls a source method. That run
+happens before the mutant is applied, and the forked test does not repeat it.
+A mutant on such a line is `ran_at_load`, not `survived` or `no_coverage`. It is
+left out of the score and does not fail `--threshold`; a kill still counts.
+This holds under both strategies: `reload` runs the mutated file's class body
+again, but not an initializer or another file's code, so a survivor on such a
+line is not trusted there either.
+Run those mutants with `--test-command`, which boots a fresh process per mutant,
+to get a verdict.
+
 Add Mutineer to your Gemfile's test group:
 
 ```ruby
@@ -144,7 +158,14 @@ RAILS_ENV=test bundle exec mutineer run \
   a mutant on an uncovered line is `no_coverage`, so the score stays comparable to
   the in-process `--rails` score.
 - **Safe `--jobs N`** — each worker routes to its own copy of the test database, so
-  parallel verdicts equal serial (no fixture cross-talk).
+  parallel verdicts equal serial (no fixture cross-talk). On first use, a
+  worker's database is a copy of the test database after the app boots, so rows
+  written by initializers or `--require` files are there, as in-process. When
+  the copy's schema differs from `db/schema.rb` (another schema version or
+  `schema_sha1` checksum, or no stored checksum, as in an empty or out-of-date
+  test database, or one set up with a plain `load "db/schema.rb"`), the
+  worker loads `db/schema.rb` over it, which drops the copied rows of the
+  tables it defines.
 - **One backend at a time** — `--daemon` can't be combined with `--test-command`
   (choose one), and it needs an app to boot (`--rails` or `--boot`).
 
@@ -227,7 +248,7 @@ Tradeoffs — this path is correct but not free:
 
 The mutation score is `killed / (killed + survived)`. A mutant whose tests run
 past `--timeout` is a `timeout`. It is neither killed nor survived, so it is
-left out of the score, like `no_coverage`, `uncapturable`, `errored`, skipped
+left out of the score, like `no_coverage`, `uncapturable`, `unplaceable`, `ran_at_load`, `errored`, skipped
 and ignored mutants. A timeout is not counted as a kill, because a hang the
 mutant caused and a suite that is just slow look the same. The human report
 shows the count in its `Timeout:` row, and the JSON report in `summary.timeout`.
@@ -435,6 +456,10 @@ structured exit codes, and diff-scoped runs. See:
   [source](https://davidteren.github.io/mutineer/json-schema.md)
 - **Ruby API (YARD)** — class reference for the shipped gem:
   [https://davidteren.github.io/mutineer/api/](https://davidteren.github.io/mutineer/api/)
+- **Agent skill** ([`skills/mutineer/SKILL.md`](https://github.com/davidteren/mutineer/blob/main/skills/mutineer/SKILL.md)): a short
+  card for coding agents with install, the agent loop, and exit codes. Install it
+  with `gh skill install davidteren/mutineer mutineer` or
+  `npx skills add davidteren/mutineer --skill mutineer`.
 
 ## Configuration
 

data/lib/mutineer/cli.rb

@@ -9,6 +9,7 @@ require_relative "project"
 require_relative "pairing"
 require_relative "changed_lines"
 require_relative "runner"
+require_relative "job_plan"
 require_relative "reporter"
 require_relative "kill_matrix"
 require_relative "baseline"
@@ -639,20 +640,20 @@ module Mutineer
            "it runs this mutineer version or later."
     end
 
-    # Runs dry-run mode. Reuses Runner.collect_jobs (+ filter_since) so the
+    # Runs dry-run mode. Reuses JobPlan.collect_jobs (+ filter_since) so the
     # candidate list cannot drift from a real run's job selection.
     #
     # @param config [Mutineer::Config] run configuration.
     # @return [void]
     def self.dry_run(config)
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
-      jobs, ignored_results, source_map, extras = Runner.collect_jobs(config, operator_classes)
+      jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
       warn_legacy_ignore_matches(extras[:legacy_ignore_matches])
       # Narrow jobs and ignored the same way so the summary matches the printed list.
       if config.since
-        jobs = Runner.filter_since(jobs, source_map, config)
+        jobs = JobPlan.filter_since(jobs, source_map, config)
         ignored_jobs = ignored_results.map { |r| [r.subject, r.mutation, r.id] }
-        ignored = Runner.filter_since(ignored_jobs, source_map, config).size
+        ignored = JobPlan.filter_since(ignored_jobs, source_map, config).size
       else
         ignored = ignored_results.size
       end