mutineer 1.7.0 → 1.8.0

data/lib/mutineer/subject.rb

@@ -15,10 +15,17 @@ module Mutineer
   # constant names, such as an `included` block that runs in each includer),
   # so the redefine strategy cannot load a mutant onto it. `hook_block` is true
   # for a def anywhere inside a concern's `included` or `prepended` block, which
-  # ActiveSupport runs only when a class first includes the concern, so the
-  # reload strategy cannot load a mutant onto it either (#256).
+  # ActiveSupport runs only when a class first includes the concern, so a
+  # reload of the file does not reach a class that already has it (#256).
+  # `reload_hook_call` is the `included` or `prepended` call node of such a
+  # block when reload can still place the def: the mutant file stores the
+  # mutated def just before that call, and the child loads it into each class
+  # that has the method (#297). It is nil when reload cannot place the def, even
+  # when `hook_block` is true (see docs/json-schema.md for the cases).
+  # `enclosing_subject` is the subject of the `def` whose body holds this one,
+  # or nil, so the redefine strategy can load each enclosing method too (#290).
   Subject = Struct.new(:file, :namespace, :name, :singleton, :def_node, :lexical, :block_owner, :owner_unknown,
-                       :hook_block, keyword_init: true) do
+                       :hook_block, :reload_hook_call, :enclosing_subject, keyword_init: true) do
     # Returns the fully-qualified subject name.
     #
     # @return [String] namespaced method name like `Billing::Invoice#total`.
@@ -38,12 +45,13 @@ module Mutineer
     # call it, so the mutant is not run. Redefine needs a named owner. Reload
     # loads the whole file again, which redefines everything except what a
     # concern's `included` or `prepended` block defines: that block does not run
-    # again in a class that already includes the concern.
+    # again in a class that already includes the concern. Reload places such a
+    # def only when discovery found its {#reload_hook_call} (#297).
     #
     # @param strategy [String] `"reload"` or `"redefine"`.
     # @return [Boolean]
     def unplaceable?(strategy)
-      strategy == "redefine" ? owner_unknown == true : hook_block == true
+      strategy == "redefine" ? owner_unknown == true : hook_block == true && reload_hook_call.nil?
     end
 
     # Returns the body location for the subject, if any.

data/lib/mutineer/test_runners/minitest.rb

@@ -13,7 +13,8 @@ module Mutineer
       #   first failing test.
       # @param record_to [IO, nil] a `--matrix` run: send each test's outcome to
       #   this channel and run every test.
-      # @return [Integer] 0 on success, 1 on failure.
+      # @return [Integer] 0 on success, 1 on failure, 2 when the first failure
+      #   was an Active Record connection or lock error.
       def self.run(test_files, stop_at_first_failure: false, record_to: nil)
         MinitestIntegration.run(test_files, stop_at_first_failure: stop_at_first_failure, record_to: record_to)
       end

data/lib/mutineer/test_runners.rb

@@ -8,8 +8,10 @@ module Mutineer
   #
   # Each runner responds to
   # `.run(files, stop_at_first_failure: false, record_to: nil) -> 0/1/2`
-  # (0 = all passed, 1 = any failure, 2 = only an error outside tests, which
-  # the RSpec runner reports) and is called only inside a forked child.
+  # (0 = all passed, 1 = any failure, 2 = no verdict: an error outside tests,
+  # which the RSpec runner reports, or a Minitest run whose first failure was
+  # an Active Record connection or lock error, #296) and is called only inside
+  # a forked child.
   # Only the mutant path passes `stop_at_first_failure: true`; a `--matrix`
   # mutant run passes `record_to:` instead (a {KillChannel} pipe) and runs every
   # test. The fork boundary silences stdout (see ChildStdout); the runners do not.

data/lib/mutineer/triage.rb

@@ -92,7 +92,7 @@ module Mutineer
         return nil
       end
 
-      doc = JSON.parse(File.read(path))
+      doc = JSON.parse(File.read(path, encoding: "UTF-8"))
       rows = doc.is_a?(Hash) ? doc["survivors"] : nil
       unless rows.is_a?(Array)
         err.puts "mutineer: triage report has no survivors list"

data/lib/mutineer/version.rb

@@ -2,5 +2,5 @@
 
 module Mutineer
   # Current Mutineer release version.
-  VERSION = "1.7.0"
+  VERSION = "1.8.0"
 end

data/lib/mutineer/worker_pool.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "result"
+require_relative "redaction"
 
 module Mutineer
   # Fixed-size fork pool. `run` forks up to `size` children at once; each child
@@ -74,7 +75,7 @@ module Mutineer
               begin
                 yield(*items[idx])
               rescue Exception => e # rubocop:disable Lint/RescueException
-                Result.error("worker crashed: #{e.class}: #{e.message}")
+                Result.error("worker crashed: #{Redaction.describe(e)}")
               end
             begin
               wr.write(Marshal.dump(payload))

data/skills/mutineer/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: mutineer
+description: Mutation testing for Ruby (Prism + stdlib, zero deps). Mutates source one change at a time, runs the suite against each mutant, and reports the mutants tests fail to catch, with a versioned JSON contract and CI/agent gating. Use when checking whether a Ruby test suite would catch a change, finding weak or missing tests, gating CI on a mutation score, or acting on mutineer's JSON report.
+---
+
+# Mutineer
+
+Mutation testing for Ruby, built for CI gates and AI coding agents. Line coverage tells
+you which code *ran*; mutation testing tells you whether your tests would *notice if it
+broke*.
+
+## Install
+
+```sh
+gem install mutineer
+```
+
+## Run
+
+```sh
+mutineer run <source...> [--test <test>...] [options]   # no --test: pairs each source with its test by convention; unmatched sources are skipped; --dry-run with --rails/--boot needs --test
+```
+
+Example — mutate `lib/calculator.rb`, gate CI below 90%:
+
+```sh
+mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
+```
+
+## Agent loop
+
+1. Edit code and tests on a branch. Fetch `origin/main` before using it below.
+2. Run diff-scoped, as JSON:
+   ```sh
+   mutineer run app/ --since origin/main --threshold 90 --format json --output .mutineer/run.json
+   ```
+3. Parse `survivors[]` — each carries a `diff` and an `id`. File moves, renames,
+   project-root changes, and changes to repeated-name or repeated-mutation order can
+   change ids; see [Mutant ids](https://github.com/davidteren/mutineer/blob/main/docs/results.md#mutant-ids). Review each change
+   against the intended behaviour. If review finds a test gap, write or strengthen
+   a test that fails under that change.
+4. Re-run. Accept the result only when this run exits `0`, `summary.score` is not `null`,
+   and `summary.score >= 90`. If every scored mutant must be killed, also require `summary.survived == 0`.
+   Mutineer 1.7.0 and earlier gate on the rounded score, so a run just below the threshold can
+   still exit `0`. On those versions, also require
+   `summary.killed * 100 >= 90 * (summary.killed + summary.survived)`.
+
+Stop after a few unsuccessful attempts and ask a person to review the survivor.
+Failed attempts do not prove that a mutant is equivalent. To
+suppress it, `mutineer triage .mutineer/run.json --reason TEXT --id ID` prints an
+`ignore:` entry for `.mutineer.yml` (Mutineer 1.7 or later reads it). See
+[Suppressing equivalent mutants](https://github.com/davidteren/mutineer/blob/main/docs/results.md#suppressing-equivalent-mutants).
+
+Keep `fail_fast` disabled (the default). If the active `.mutineer.yml` sets it to
+`true`, temporarily change that value to `false` for the loop. Restore the original
+value when the loop ends, before committing. A fail-fast run is partial,
+and its score and exit code do not cover the full scope.
+
+Zero survivors alone is not success: an empty or fully suppressed scope, or a run
+with no usable verdicts, also has zero survivors. If the score is null, stop and
+report “no score”. Check `no_coverage[]` for test gaps and `no_verdict[]` for
+harness failures, and fix them before starting a new run. A positive threshold fails when nothing can be scored and something
+broke, or when more than one mutant has no verdict and they exceed 10% of those
+attempted; it does not require zero errors. Set the threshold to your target.
+
+An empty run (`summary.total` is 0) exits 0 in 1.x and prints a warning on stderr. Treat it as "no score". Pass `--allow-empty` only when an empty run is expected. A `--since` run whose changes hold no mutable code says "nothing to test in the changes since REF"; that is a valid success. Warnings that start with `mutineer:` or `[mutineer]` also go to stderr: the empty-run warning, "did you mean" hints, notes about Mutineer 2.0, the count of errored mutants, and a notice that a `PARALLEL_WORKERS` value you set was replaced with 1.
+
+## Exit codes
+
+<!-- contract:exit-codes -->
+| Code | Meaning |
+|------|---------|
+| `0` | Score ≥ threshold (or no gate) **and** no baseline regression. |
+| `1` | Score below `--threshold`, OR nothing could be scored and something broke, or more than one mutant produced no verdict and they exceed 10% of those attempted, OR a `--baseline` regression, OR a runtime error, including a boot, source or `require:` file that raises while loading. |
+| `2` | Usage / invalid-flag error, including a mistyped flag, a bad path (such as a missing `--boot` or `require:` file), or an unreadable baseline. |
+<!-- /contract:exit-codes -->
+
+## References
+
+- Docs: https://davidteren.github.io/mutineer/
+- Agent & CI guide: https://davidteren.github.io/mutineer/agentic-coding.html
+- JSON schema: https://davidteren.github.io/mutineer/json-schema.html
+- Ruby API: https://davidteren.github.io/mutineer/api/
+- Source: https://github.com/davidteren/mutineer

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutineer
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - David Teren
@@ -72,6 +72,7 @@ files:
 - lib/mutineer/kill_matrix.rb
 - lib/mutineer/migrate.rb
 - lib/mutineer/minitest_integration.rb
+- lib/mutineer/minitest_integration/in_test_database_error.rb
 - lib/mutineer/minitest_integration/kill_recorder.rb
 - lib/mutineer/minitest_integration/outer_reporter.rb
 - lib/mutineer/minitest_integration/stop_at_first_failure.rb
@@ -119,6 +120,7 @@ files:
 - lib/mutineer/triage.rb
 - lib/mutineer/version.rb
 - lib/mutineer/worker_pool.rb
+- skills/mutineer/SKILL.md
 homepage: https://github.com/davidteren/mutineer
 licenses:
 - MIT
@@ -128,6 +130,8 @@ metadata:
   bug_tracker_uri: https://github.com/davidteren/mutineer/issues
   documentation_uri: https://davidteren.github.io/mutineer/
   rubygems_mfa_required: 'true'
+  hyperdrive_targets: "*"
+  hyperdrive_artifacts: skill
 rdoc_options: []
 require_paths:
 - lib