mutineer 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7b8a623ac7db818d33df11a7ca32e26a67db7f156061027f018debeb17ced2f
-  data.tar.gz: 5957fb6e57cb5a5149822818f773f3e8d3da271bce7bb0cfc4d0a8640764aa40
+  metadata.gz: 50113a063a85737ad99476f85e78cb2ac015f267018d19ba6350ba36ff4ac6df
+  data.tar.gz: c12343a00d2df6d495859644c326bc650e33d013ddf009f2648c06a199aceb86
 SHA512:
-  metadata.gz: 1de2a131774b7b587abbc8ca91a57da333688cb2fdb937defa002d661426137decf8b86fbde1a2d176a5525f8cb7d9a8b6a2bebc353960729704b3e8d2473213
-  data.tar.gz: '094d062c4c8458fda7061a575681f13022131b2b9078e5731bcbbfa300ac67b86e53691e4d9e104cc06e50832b66bd3dd32433c1bdf420e74b75a7b7748b4916'
+  metadata.gz: a170b15c6883a4dcec6a2798c3b102a5f9c9ded1f46c166df98d0e5bdf5b891ca5b24892efe06245680b45a94da38638adc36ca9a48a48d2ac1c07b29126f173
+  data.tar.gz: a30272ff6afb48dd666d6945c6532d987ef335e0e78dc422420cf26cdbec639ee1c850118a10ba25e10a426a2644b3926e39698126eaad0646707a4f2be2e719

data/CHANGELOG.md

@@ -6,6 +6,321 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-10-06
+
+### Added
+- **`--timeout SECONDS` and `--capture-timeout SECONDS`**, also `timeout:` and
+  `capture_timeout:` in `.mutineer.yml`. They set the in-process per-mutant
+  time limit (default 10s) and the coverage-capture time limit (default 120s),
+  which were fixed. On a large Rails suite the clean run of the unmutated
+  tests took longer than 120s, so every run that offered the whole suite
+  stopped as not green, and a mutant on a line many tests cover took longer
+  than 10s and was scored `timeout`. `--daemon` keeps its own per-mutant
+  limit but uses `--capture-timeout` for its coverage capture;
+  `--test-command` uses neither. Either backend warns about a limit it was
+  given and does not use.
+- **`--cache-dir DIR`**, also `cache_dir:` in `.mutineer.yml`, sets where the
+  coverage cache is written (default `.mutineer`, as before). Two runs from the
+  same project root shared `.mutineer/coverage.json` and could overwrite each
+  other's map; each can now have its own directory. `--daemon` uses it too.
+  A blank value (an unset CI variable) exits 2 rather than writing the cache
+  into the project root.
+- **The README states how timeouts affect the score** (#62): a timed-out
+  mutant is left out of the score, and counts as a mutant with no verdict
+  under `--threshold`.
+- **`--matrix` reports which tests kill each mutant** (`matrix: true` in
+  `.mutineer.yml`). Each mutant runs every test in its covering files instead
+  of stopping at the first failure, and the child sends each test's outcome to
+  the parent as it is recorded. The report names blind tests, which ran in a
+  complete row and killed no mutant, and redundant tests, whose every kill
+  another test also makes. Redundancy is judged one test at a time, so delete
+  redundant tests one at a time. The human report lists up to 20 of each, the
+  HTML report all of them, and the JSON report moves to schema `1.5` with a
+  `matrix` block that appears only with the flag. A test is its file and its
+  id (the example id under RSpec), so examples that share a description stay
+  apart and an example whose generated description changes with the mutant
+  stays one test. Verdicts, the score and the exit code do not change: each
+  mutant gets the verdict a run without the flag gives. After a serial test
+  fails, an exit, a crash or the timeout in a later test, class or group
+  leaves it `killed`; an end in the code that run still reaches (the failing
+  test's class wrapper or group hooks, the suite's own cleanup) and a failure
+  in a `parallelize_me!` class keep the exit status. A row is complete only
+  when the child's stream arrived in order and every test reported (under
+  Minitest the recorder saw every test, under RSpec every planned example),
+  so a caught `Interrupt` leaves it incomplete. The human report names up
+  to 20 incomplete rows and the HTML and JSON reports all of them; the human
+  and HTML reports warn not to delete a blind test until its rows are
+  complete.
+  Minitest and RSpec 3.3+ are supported, on the in-process backend only;
+  `--daemon`, `--test-command`, `--fail-fast` and `--dry-run` exit 2 with it.
+  `--no-matrix` and `--no-fail-fast` beat the matching `.mutineer.yml` key,
+  so a file that sets one can still run with a flag that conflicts with it.
+- **`no_coverage[]` and `uncapturable[]` name each mutant.** Every entry in
+  the JSON report now has `operator`, `token` and `id`, as `ignored[]` has, so
+  mutants on one line can be told apart and an `id` can go in `ignore:`. The
+  entries are sorted by `(file, line, operator, id)`. `schema_version` is `1.6`.
+
+- **The site and README explain "clean-room" and compare Mutineer with
+  Mutant**, and the landing page hero has a one-minute explainer video. It
+  plays at 55% volume while in view (not with reduced motion; muted until
+  the first click or key where the browser requires it), pauses when it scrolls
+  away or the tab is hidden, and has an Enlarge button.
+
+### Changed
+- **The human report has a `Timeout:` row**, and the score line lists timeouts
+  apart from errored mutants. Before, the `Errored:` row and the score line
+  added the two together, while the JSON report kept them apart. The HTML
+  summary now shows a `timeout` count apart from `errored` too.
+- **A test file given as a source after `--test` exits 2.** `--test` takes one
+  file, so in `mutineer run app/x.rb --test spec/a_spec.rb spec/b_spec.rb` the
+  second spec became a source to mutate, and the run tested with one spec file
+  without a word. Now a source named `*_test.rb` or `*_spec.rb` inside a
+  `test/` or `spec/` directory, given with `--test`, is a usage error that says
+  to repeat `--test`. The usage line now reads `--test <test> [--test <test>...]`.
+
+### Fixed
+- **The RSpec runner keeps what gems configured before the run.** It called
+  `RSpec.reset`, which drops the whole configuration. Under `rails: true`, a
+  `--boot` file or `require:`, the app's gems load first, so a setting such as
+  rspec-retry's `verbose_retry` was gone, and a support file that set it
+  raised `NoMethodError`. The run stopped with "the unmutated suite is not
+  green". The runner now calls `RSpec.clear_examples`, which keeps the
+  configuration. Hooks that gems added now apply too: an example with
+  rspec-retry's `retry: 3` runs up to 3 times per mutant, as under `rspec`.
+- **`--since` no longer scores a file that Git ignores** (#168). A file
+  outside the index is scored in full, so a new file is not missed. That
+  check also caught files that Git ignores on purpose (`.gitignore`,
+  `.git/info/exclude` or the global excludes file), such as generated code
+  inside a directory run. Those files now get no mutants under `--since`,
+  and a warning names each one. Other untracked files are still scored in
+  full, and so is a file when Git cannot tell, such as one beyond a symlink or
+  inside a submodule.
+- **The human report escapes control characters from the source** (#163).
+  A surviving line that held a terminal control byte (for example ESC) was
+  printed as that byte, so it could change what the terminal showed. The
+  token, the replacement, the diff lines, method names, file paths and the
+  kill matrix's test names now print each control character except tab as
+  its Ruby escape (`\e`), and a byte that is not valid UTF-8 (a Latin-1
+  source) as `\xNN`. The JSON and HTML
+  reports already escaped text and do not change.
+- **One edit on a line is scored once** (#159). Some opt-in operators emitted
+  two mutants that give the same source: `literal_mutation` on `0` (the
+  "change to 1" and "add 1" rules), `negation_removal` on `!!x` (either `!`
+  removed), and `chain_link` or `operand_removal` on a repeated part such as
+  `a.b.b.c` or `x || x`. Each copy had its own id, so one surviving edit
+  counted twice. Now only the first copy on a line runs. Copies that start
+  on different lines (a multi-line chain) both stay, so `--since` never
+  loses the edit. Ids are assigned before the copy is dropped, so every kept
+  mutant keeps its id, and the dropped copy's id simply stops appearing.
+  Default runs do not change. If you use these operators with `--baseline`,
+  regenerate the baseline after upgrading: the score can move with no code
+  change, and in a full (unscoped) comparison a dropped copy that survived
+  is listed as fixed. An ignore entry for one copy's id still ignores only
+  that copy; the other copy still runs.
+- **`# mutineer:disable-line` inside a string no longer silences a line**
+  (#158). The marker was found with a text search, so a string such as
+  `"# mutineer:disable-line"` ignored every mutant on its line and left
+  them out of the score. Only a real `#` comment counts now. A heredoc or
+  regex that holds the text is ignored too.
+- **`./lib/x.rb` and an absolute path pair with a test** (#104). Auto-pairing
+  found the test for `lib/calc.rb` but not for `./lib/calc.rb` or the
+  absolute path to the same file. It reported "no test found by convention"
+  and exited 2. A file argument inside the project is now made relative to
+  the project root first, so equivalent spellings (`./`, `..`, absolute)
+  pair with the same test and run once. A symlink keeps its own name, so it
+  stays a separate source from its target. Reports show that root-relative
+  path. A path outside the project stays as typed.
+- **A mutant on another line of a multi-line statement runs its tests**
+  instead of being reported as `no_coverage`. Ruby counts one line of a
+  statement only. When the mutant's own line has no count, the runner now uses
+  the tests that ran the statement that holds the mutation. A heredoc body
+  belongs to its statement. This fallback skips a first or last line that also
+  holds other code, such as the `def` line, and the body of `x while c` and
+  `x until c`. It also gives no tests to a mutant in code of the statement
+  that runs only sometimes: a `when` or `in` condition, a `rescue` class
+  list, a parameter default, the rescue side of `x rescue y`, the value of
+  `||=` or `&&=`, the operand of `defined?`, the right side of `a ||` or
+  `a &&`, a branch of `x if c`, `x unless c`, a ternary or `else`, the
+  pattern of `v in p` or `v => p`, an
+  argument or block of `x&.m(...)`, and the value of `x&.m += v`. Those
+  mutants stay `no_coverage`, as before.
+- **A survivor diff for a multi-line mutant applies with `git apply`** (#106).
+  The JSON `diff` header always read `@@ -N +N @@`, even when the mutant
+  removed two lines and added one, so `git apply` rejected the patch as
+  corrupt. The header now carries each side's line count (`@@ -3,2 +3 @@`).
+  A one-line diff keeps its old header. A mutant that empties a line now
+  shows that empty line as a `+` line. A side whose last line has no final
+  newline gets ``. Lines of a CRLF file now keep
+  their `\r`, so the patch applies to that file.
+- **Split test files pair with their source** (#87). A source such as
+  `app/foo/bar.rb` now also uses `test/foo/bar_upsert_test.rb` and
+  `test/foo/bar_guards_test.rb`, together with `test/foo/bar_test.rb` when
+  that file exists. The same names under `test/lib/` pair with a `lib/`
+  source. Before, only the exact `bar_test.rb` name was tried, so a suite
+  split across `bar_*_test.rb` files was skipped and a gate could pass with
+  no mutants run. A spec the old rules already find is unchanged. The
+  split name is left for `user_session.rb` when that file exists, so
+  `user.rb` does not run `user_session_test.rb`. The same rule holds outside
+  `app/` and `lib/`: `src/user.rb` does not take `test/src/user_session_test.rb`
+  when `src/user_session.rb` exists. A longer source claims a split file
+  only when that source itself searches the directory the file is in.
+  A failed capture of `test/foo/bar_upsert_test.rb` can mark `app/foo/bar.rb`
+  uncapturable only when no successful capture covered that source and
+  `bar_upsert.rb` does not exist. A test outside that directory does not,
+  and neither does a source that only shares the test basename.
+  `user_session__test.rb` stays with `user.rb` when `user_session.rb`
+  exists, because that name is not the exact test or a split test for
+  `user_session`. A failed exact spec in the mirrored `spec/` or `spec/lib/` directory
+  marks an `app/` or `lib/` source the same way. A failed spec in another
+  directory does not. A project rooted at `/` still finds split tests
+  inside that root. A stored failure keeps the pairing from the moment it
+  was checked. Adding or deleting a longer source rebuilds the coverage
+  map, so that failure is not moved onto the shorter source.
+- **A blank `operators` key no longer runs zero mutants and exits 0** (#167).
+  `operators:` with no value became an empty list. The run made no mutants
+  and the gate passed. A blank operator list is now an error, and so is a
+  list of only unknown operator names. An empty `require` or `ignore` list
+  is still valid. `--operators` on the command line still replaces the
+  file list, including a blank or unknown file list.
+- **The daemon no longer runs the tool's Ruby settings inside the app** (#100).
+  Open3 keeps a variable when the spawn hash omits it, so a parent `RUBYOPT`
+  ran inside the app. The child now gets the environment Bundler saved before
+  it activated, passed with `unsetenv_others`. The app keeps its gem home,
+  excluded groups, Bundler config, and chruby path. An `RBENV_VERSION` or
+  `ASDF_RUBY_VERSION` already in the environment stays. That pin is often
+  the Ruby that started the tool. `.ruby-version` applies only when no pin
+  is set. The tool's `RUBYOPT` and `RUBYLIB` do not reach the child, including
+  a value Bundler had saved. A gem home, `BUNDLE_PATH`, or `BUNDLE_WITHOUT`
+  reaches the child only when Bundler saved the app's value. The same
+  rule covers `GEM_PATH` and `BUNDLER_VERSION`. An rbenv version
+  bin under `RBENV_ROOT`, or under `~/.rbenv` when that variable is unset,
+  leaves `PATH` only when that root has a shim directory. An asdf version
+  bin leaves only when an asdf shim directory exists, including
+  `ASDF_DATA_DIR/shims`. Without that shim, the bin stays and `bundle` can
+  still be found. The app Gemfile, an explicit Ruby pin, and Rails env are
+  applied after that.
+- **The Action refuses to run when `output` and `baseline` are the same file** (#160).
+  That setup used to work, and a failing run copied its report onto the
+  baseline. The next run then treated the failed report as the baseline, so
+  the gate could pass. The Action now stops before the run and exits 2.
+  The baseline may come from the `baseline` input, from `--baseline` in
+  `extra-args`, or from `.mutineer.yml`. A numeric path such as `123` is
+  read the same way as the CLI. Write the report to a separate path. Copy
+  that file onto the baseline in a later step, and only when this step
+  exits 0. You can also refresh the baseline with the CLI, and keep the
+  file only when the run exits 0. The next release moves the `v1` tag, so
+  workflows on `@v1` get this refusal then.
+- **A mutation no longer leaves a heredoc body behind as Ruby** (#134).
+  Replacing a node deletes the heredoc opener and not the body. The body
+  then parses as code, raises, and counts as a kill. A mutation that drops
+  the opener is skipped. A replacement that still contains the opener stays.
+- **A bare `public`, `private` or `protected` ends `module_function` mode**,
+  so later `def`s in the module body are named as instance methods, not
+  singleton methods (#144).
+- **Turning on reduced motion mid-visit finishes the landing page count-ups**,
+  so no number keeps changing after the visitor asks for less motion (#176).
+- **`rake site:build` can no longer delete a directory such as `lib/` or
+  `.git`** (#162). The task removed the destination it was given, and only
+  refused the checkout, its parents and `docs/`. It now always builds into
+  `_site/` at the checkout root, and `rake "site:build[DEST]"` and
+  `SITE_BUILD_DEST` are gone.
+- **Documentation matches the 1.4 behavior.** Config examples use supported keys,
+  agent loops check the exit code and a real score, and report totals explain
+  partial `--fail-fast` runs. The README lists every config key and its validation
+  rules. API README links work outside GitHub, repeated changelog headings have
+  unique anchors, and the website checks validate built links and anchors.
+  Mutant-id wording and the gem's Minitest/RSpec description are also corrected.
+- **A mutant in a nested method counts once** (#157). A `def` inside
+  another method is a subject of its own, but most operators also mutated
+  its code on the outer method. The same edit then counted twice in the
+  score, with two ids. Every operator now skips a nested `def` when it
+  mutates the outer method. A `def` inside `class << obj`, where `obj` is
+  not `self`, is not a subject, so the outer method still mutates its code.
+  `array_literal`, `chain_link`, `condition_true`, `condition_false`,
+  `operand_removal`, `operator_assignment` and `return_nil` skipped that
+  code before. Their new mutants there can show as new survivors against a
+  baseline.
+
+  A mutant id includes an ordinal among the mutants with the same operator
+  and token in a subject. When the duplicates leave the outer method, the
+  ordinals of its own mutants change. An old duplicate id can then name a
+  different mutant on the outer method, and an `ignore:` entry or a
+  baseline entry with that id applies to that mutant with no warning. If
+  your code has nested methods, regenerate the `ignore:` entries and the
+  baseline for the outer methods.
+
+  Under `--strategy redefine` (the `--rails` default), a mutant in a nested
+  method can survive or error even when a test would catch it. `redefine`
+  loads only the inner method, and a call to the outer method defines the
+  original inner method again. Before, the copy of the edit on the outer
+  method was killed. Now each edit has one verdict, from the inner method.
+
+## [1.4.0] - 2026-09-30
+
+### Added
+- **Condition-forcing operators** (Tier-2, opt-in via `--operators`):
+  `condition_true` and `condition_false` replace an `if`/`elsif`/`unless`,
+  ternary, modifier or `case`/`in` guard condition with `(true)` or `(false)`, so
+  its branch always runs or never runs. A surviving mutant means no selected
+  test detected the forced condition. A literal condition, also in
+  parentheses, makes no mutant: forcing it changes nothing or repeats the
+  `boolean_literal` flip. A condition that holds a heredoc makes no mutant.
+  A condition that assigns a variable keeps its code, and only its value
+  is forced (`(m = x; true)`), so later code still sees the variable.
+  The never-runs side of an else-less conditional can
+  be the same program as the `nil` that `statement_removal` or `return_nil`
+  puts in its place; it is still made, so these mutants and their ids do not
+  depend on which other operators run.
+- **Operator-assignment operator** (Tier-2, opt-in via `--operators`):
+  `operator_assignment` swaps the operator of a compound assignment:
+  `+=` <-> `-=`, `*=` <-> `/=`, and `%=` and `**=` -> `*=`. It covers local,
+  instance, class and global variables, constants, calls (`a.b += 1`) and
+  index calls (`a[i] += 1`). The `arithmetic` operator never sees these
+  forms, because Prism does not parse them as calls. The operator does not
+  change `||=`, `&&=`, or the bitwise and shift forms (`|=`, `<<=`).
+
+### Fixed
+- **A typed `--rails`, `--verbose` or `--debug` beats `rails: false` and
+  `verbose: false` in `.mutineer.yml`** (#103). The flag was dropped, so the
+  run went on without Rails boot or verbose output. The config layers now keep
+  only the keys the user wrote, and "did the user write this" comes from those
+  keys, not from a hand-kept list.
+- **`framework: rspec` in `.mutineer.yml` survives test pairing** (#103).
+  Pairing re-detected the framework from the test file names, so an RSpec
+  suite in `test/calc_test.rb` ran under Minitest.
+- **A bad number is an error, not a rounded value** (#105). `--jobs 1.9` and
+  `--baseline-epsilon abc` no longer become `1` and `0.0`. One option schema
+  parses each value once, where it enters, for both the command line and
+  `.mutineer.yml`.
+- **`--since` keeps a source file that git does not track yet** (#156). Before,
+  such a file counted as unchanged. The run scored no mutants, and a positive
+  `--threshold` still exited 0. The file is now new in full, so all its
+  mutants run.
+
+### Changed
+- **These now exit 2 with a message that names the option**: `jobs: 1.9` or
+  `jobs: true` in `.mutineer.yml` (before: `1`, or a crash); a bad, negative
+  or non-finite `--baseline-epsilon` (before: `0.0`); a boolean key in
+  `.mutineer.yml` that is not `true` or `false`, such as the string `"yes"`
+  (before: `false`).
+- **`--jobs` takes plain digits only.** `0x2`, `+2`, `" 2"` and `1_0` exit 2.
+  Before, `Integer()` read them as 2, 2, 2 and 10. `--threshold` and
+  `--baseline-epsilon` take a plain decimal, such as `2` or `2.5`, from a
+  string. `0x10`, `+2`, `1_0` and `1e2` exit 2. Before, `Float()` read them
+  as 16.0, 2.0, 10.0 and 100.0.
+- **A string option that gets `true`, `false` or no value exits 2**, such as
+  `only: false` or `baseline:` in `.mutineer.yml`. A blank `since` also exits 2,
+  in the file and on the command line, so an unset shell variable does not
+  turn scoping off. `since: false` still means no scoping.
+- **Config file errors start with the file and key**, for example
+  `.mutineer.yml: threshold must be a number between 0 and 100`, where they
+  started with `--threshold`.
+- **The docs site is built in CI** — a Pages workflow runs `rake site:build`
+  and deploys the result, so the YARD HTML under `/api/`, `llms-full.txt`,
+  `json-schema.html` and `sitemap.xml` are no longer committed. CI checks
+  that the site builds, in place of `rake yard:pages:check`. The site keeps
+  its URLs (#153).
+
 ## [1.3.0] - 2026-09-29
 
 ### Changed
@@ -611,6 +926,8 @@ 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.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
 [1.2.0]: https://github.com/davidteren/mutineer/releases/tag/v1.2.0
 [1.1.0]: https://github.com/davidteren/mutineer/releases/tag/v1.1.0