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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +680 -0
- data/README.md +210 -499
- data/lib/mutineer/baseline.rb +1 -1
- data/lib/mutineer/changed_lines.rb +2 -1
- data/lib/mutineer/child_coverage.rb +53 -0
- data/lib/mutineer/cli.rb +293 -42
- data/lib/mutineer/concern_blocks.rb +243 -0
- data/lib/mutineer/config.rb +154 -8
- data/lib/mutineer/coverage_map.rb +265 -27
- data/lib/mutineer/daemon_backend.rb +244 -75
- data/lib/mutineer/daemon_client.rb +73 -10
- data/lib/mutineer/daemon_server.rb +226 -42
- data/lib/mutineer/external_backend.rb +159 -15
- data/lib/mutineer/init.rb +124 -0
- data/lib/mutineer/isolation.rb +78 -24
- data/lib/mutineer/job_plan.rb +234 -44
- data/lib/mutineer/kill_channel.rb +24 -14
- data/lib/mutineer/migrate.rb +707 -0
- data/lib/mutineer/minitest_integration/in_test_database_error.rb +184 -0
- data/lib/mutineer/minitest_integration/kill_recorder.rb +25 -17
- data/lib/mutineer/minitest_integration.rb +44 -14
- data/lib/mutineer/mutator_registry.rb +6 -2
- data/lib/mutineer/mutators/array_literal.rb +4 -2
- data/lib/mutineer/mutators/base.rb +36 -7
- data/lib/mutineer/mutators/call_to_receiver.rb +148 -0
- data/lib/mutineer/mutators/chain_link.rb +6 -6
- data/lib/mutineer/mutators/condition_forcing.rb +6 -3
- data/lib/mutineer/mutators/operand_removal.rb +4 -2
- data/lib/mutineer/mutators/range_literal.rb +105 -4
- data/lib/mutineer/mutators/return_nil.rb +1 -0
- data/lib/mutineer/orphan_guard.rb +84 -0
- data/lib/mutineer/pairing.rb +62 -1
- data/lib/mutineer/project.rb +302 -14
- data/lib/mutineer/rails_run_env.rb +73 -0
- data/lib/mutineer/rails_worker_db.rb +1596 -57
- data/lib/mutineer/redaction.rb +199 -0
- data/lib/mutineer/reporter.rb +173 -31
- data/lib/mutineer/result.rb +52 -15
- data/lib/mutineer/runner.rb +148 -28
- data/lib/mutineer/statement_lines.rb +24 -11
- data/lib/mutineer/subject.rb +30 -4
- data/lib/mutineer/test_runners/minitest.rb +2 -1
- data/lib/mutineer/test_runners/rspec.rb +15 -3
- data/lib/mutineer/test_runners.rb +5 -2
- data/lib/mutineer/triage.rb +111 -0
- data/lib/mutineer/version.rb +1 -1
- data/lib/mutineer/worker_pool.rb +2 -1
- data/lib/mutineer.rb +4 -0
- data/skills/mutineer/SKILL.md +84 -0
- metadata +13 -1
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "json"
|
|
4
|
+
require "optparse"
|
|
5
|
+
require "yaml"
|
|
6
|
+
|
|
7
|
+
module Mutineer
|
|
8
|
+
# Prints `.mutineer.yml` `ignore:` entries for survivors in a JSON report.
|
|
9
|
+
# The command writes to stdout and does not edit files. The user pastes the
|
|
10
|
+
# lines under `ignore:`.
|
|
11
|
+
module Triage
|
|
12
|
+
# Usage line for a bad invocation.
|
|
13
|
+
USAGE = "Usage: mutineer triage REPORT.json --reason TEXT (--id ID ... | --all)"
|
|
14
|
+
|
|
15
|
+
# Reads argv, prints the entries, and returns the process exit code.
|
|
16
|
+
# 0 is success. 2 is a usage error.
|
|
17
|
+
#
|
|
18
|
+
# @param argv [Array<String>] arguments after the `triage` command.
|
|
19
|
+
# @param out [IO] where the entries go.
|
|
20
|
+
# @param err [IO] where usage errors go.
|
|
21
|
+
# @return [Integer] 0 or 2.
|
|
22
|
+
def self.run(argv, out: $stdout, err: $stderr)
|
|
23
|
+
reason = nil
|
|
24
|
+
ids = []
|
|
25
|
+
all = false
|
|
26
|
+
parser = OptionParser.new do |o|
|
|
27
|
+
o.banner = USAGE
|
|
28
|
+
o.on("--reason TEXT") { |text| reason = text }
|
|
29
|
+
o.on("--id ID") { |id| ids << id }
|
|
30
|
+
o.on("--all") { all = true }
|
|
31
|
+
end
|
|
32
|
+
begin
|
|
33
|
+
parser.parse!(argv)
|
|
34
|
+
rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
|
|
35
|
+
err.puts "mutineer: #{e.message}"
|
|
36
|
+
return 2
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
report = argv.shift
|
|
40
|
+
if argv.any?
|
|
41
|
+
err.puts "mutineer: triage takes one report file"
|
|
42
|
+
return 2
|
|
43
|
+
end
|
|
44
|
+
if report.nil? || report.empty?
|
|
45
|
+
err.puts "mutineer: triage requires a JSON report file"
|
|
46
|
+
return 2
|
|
47
|
+
end
|
|
48
|
+
text = reason.to_s.strip
|
|
49
|
+
if reason.nil? || text.empty?
|
|
50
|
+
err.puts "mutineer: triage requires --reason TEXT"
|
|
51
|
+
return 2
|
|
52
|
+
end
|
|
53
|
+
if all && !ids.empty?
|
|
54
|
+
err.puts "mutineer: triage takes --id or --all, not both"
|
|
55
|
+
return 2
|
|
56
|
+
end
|
|
57
|
+
if !all && ids.empty?
|
|
58
|
+
err.puts "mutineer: triage requires --id ID or --all"
|
|
59
|
+
return 2
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
survivors = survivor_ids(report, err)
|
|
63
|
+
return 2 if survivors.nil?
|
|
64
|
+
|
|
65
|
+
chosen = all ? survivors : ids
|
|
66
|
+
missing = chosen.reject { |id| survivors.include?(id) }
|
|
67
|
+
unless missing.empty?
|
|
68
|
+
err.puts "mutineer: triage id is not a survivor: #{missing.join(', ')}"
|
|
69
|
+
return 2
|
|
70
|
+
end
|
|
71
|
+
|
|
72
|
+
entries = chosen.uniq.map { |id| { "id" => id, "reason" => text } }
|
|
73
|
+
if entries.empty?
|
|
74
|
+
err.puts "mutineer: triage has nothing to paste under ignore:"
|
|
75
|
+
return 0
|
|
76
|
+
end
|
|
77
|
+
|
|
78
|
+
body = YAML.dump(entries).sub(/\A---\n/, "")
|
|
79
|
+
out.write(body.end_with?("\n") ? body : "#{body}\n")
|
|
80
|
+
0
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
# Survivor ids from a JSON report, in report order. Nil when the file
|
|
84
|
+
# cannot be used, after a message on `err`.
|
|
85
|
+
#
|
|
86
|
+
# @param path [String] report path.
|
|
87
|
+
# @param err [IO] usage errors.
|
|
88
|
+
# @return [Array<String>, nil]
|
|
89
|
+
def self.survivor_ids(path, err)
|
|
90
|
+
unless File.file?(path)
|
|
91
|
+
err.puts "mutineer: triage report not found: #{path}"
|
|
92
|
+
return nil
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
doc = JSON.parse(File.read(path, encoding: "UTF-8"))
|
|
96
|
+
rows = doc.is_a?(Hash) ? doc["survivors"] : nil
|
|
97
|
+
unless rows.is_a?(Array)
|
|
98
|
+
err.puts "mutineer: triage report has no survivors list"
|
|
99
|
+
return nil
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
rows.filter_map { |row| row["id"] if row.is_a?(Hash) && row["id"].is_a?(String) }
|
|
103
|
+
rescue JSON::ParserError => e
|
|
104
|
+
err.puts "mutineer: triage report is not JSON: #{e.message}"
|
|
105
|
+
nil
|
|
106
|
+
rescue SystemCallError
|
|
107
|
+
err.puts "mutineer: triage report cannot be read: #{path}"
|
|
108
|
+
nil
|
|
109
|
+
end
|
|
110
|
+
end
|
|
111
|
+
end
|
data/lib/mutineer/version.rb
CHANGED
data/lib/mutineer/worker_pool.rb
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
require_relative "result"
|
|
4
|
+
require_relative "redaction"
|
|
4
5
|
|
|
5
6
|
module Mutineer
|
|
6
7
|
# Fixed-size fork pool. `run` forks up to `size` children at once; each child
|
|
@@ -74,7 +75,7 @@ module Mutineer
|
|
|
74
75
|
begin
|
|
75
76
|
yield(*items[idx])
|
|
76
77
|
rescue Exception => e # rubocop:disable Lint/RescueException
|
|
77
|
-
Result.error("worker crashed: #{
|
|
78
|
+
Result.error("worker crashed: #{Redaction.describe(e)}")
|
|
78
79
|
end
|
|
79
80
|
begin
|
|
80
81
|
wr.write(Marshal.dump(payload))
|
data/lib/mutineer.rb
CHANGED
|
@@ -29,6 +29,7 @@ require_relative "mutineer/mutators/safe_navigation"
|
|
|
29
29
|
require_relative "mutineer/mutators/range_literal"
|
|
30
30
|
require_relative "mutineer/mutators/negation_removal"
|
|
31
31
|
require_relative "mutineer/mutators/chain_link"
|
|
32
|
+
require_relative "mutineer/mutators/call_to_receiver"
|
|
32
33
|
require_relative "mutineer/mutators/operand_removal"
|
|
33
34
|
require_relative "mutineer/mutators/array_literal"
|
|
34
35
|
require_relative "mutineer/mutators/condition_forcing"
|
|
@@ -41,6 +42,9 @@ require_relative "mutineer/runner"
|
|
|
41
42
|
require_relative "mutineer/kill_matrix"
|
|
42
43
|
require_relative "mutineer/reporter"
|
|
43
44
|
require_relative "mutineer/baseline"
|
|
45
|
+
require_relative "mutineer/triage"
|
|
46
|
+
require_relative "mutineer/migrate"
|
|
47
|
+
require_relative "mutineer/init"
|
|
44
48
|
require_relative "mutineer/cli"
|
|
45
49
|
|
|
46
50
|
# Mutineer is the top-level namespace for the mutation-testing library.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mutineer
|
|
3
|
+
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.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Mutineer
|
|
7
|
+
|
|
8
|
+
Mutation testing for Ruby, built for CI gates and AI coding agents. Line coverage tells
|
|
9
|
+
you which code *ran*; mutation testing tells you whether your tests would *notice if it
|
|
10
|
+
broke*.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
gem install mutineer
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Run
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
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
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Example — mutate `lib/calculator.rb`, gate CI below 90%:
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Agent loop
|
|
31
|
+
|
|
32
|
+
1. Edit code and tests on a branch. Fetch `origin/main` before using it below.
|
|
33
|
+
2. Run diff-scoped, as JSON:
|
|
34
|
+
```sh
|
|
35
|
+
mutineer run app/ --since origin/main --threshold 90 --format json --output .mutineer/run.json
|
|
36
|
+
```
|
|
37
|
+
3. Parse `survivors[]` — each carries a `diff` and an `id`. File moves, renames,
|
|
38
|
+
project-root changes, and changes to repeated-name or repeated-mutation order can
|
|
39
|
+
change ids; see [Mutant ids](https://github.com/davidteren/mutineer/blob/main/docs/results.md#mutant-ids). Review each change
|
|
40
|
+
against the intended behaviour. If review finds a test gap, write or strengthen
|
|
41
|
+
a test that fails under that change.
|
|
42
|
+
4. Re-run. Accept the result only when this run exits `0`, `summary.score` is not `null`,
|
|
43
|
+
and `summary.score >= 90`. If every scored mutant must be killed, also require `summary.survived == 0`.
|
|
44
|
+
Mutineer 1.7.0 and earlier gate on the rounded score, so a run just below the threshold can
|
|
45
|
+
still exit `0`. On those versions, also require
|
|
46
|
+
`summary.killed * 100 >= 90 * (summary.killed + summary.survived)`.
|
|
47
|
+
|
|
48
|
+
Stop after a few unsuccessful attempts and ask a person to review the survivor.
|
|
49
|
+
Failed attempts do not prove that a mutant is equivalent. To
|
|
50
|
+
suppress it, `mutineer triage .mutineer/run.json --reason TEXT --id ID` prints an
|
|
51
|
+
`ignore:` entry for `.mutineer.yml` (Mutineer 1.7 or later reads it). See
|
|
52
|
+
[Suppressing equivalent mutants](https://github.com/davidteren/mutineer/blob/main/docs/results.md#suppressing-equivalent-mutants).
|
|
53
|
+
|
|
54
|
+
Keep `fail_fast` disabled (the default). If the active `.mutineer.yml` sets it to
|
|
55
|
+
`true`, temporarily change that value to `false` for the loop. Restore the original
|
|
56
|
+
value when the loop ends, before committing. A fail-fast run is partial,
|
|
57
|
+
and its score and exit code do not cover the full scope.
|
|
58
|
+
|
|
59
|
+
Zero survivors alone is not success: an empty or fully suppressed scope, or a run
|
|
60
|
+
with no usable verdicts, also has zero survivors. If the score is null, stop and
|
|
61
|
+
report “no score”. Check `no_coverage[]` for test gaps and `no_verdict[]` for
|
|
62
|
+
harness failures, and fix them before starting a new run. A positive threshold fails when nothing can be scored and something
|
|
63
|
+
broke, or when more than one mutant has no verdict and they exceed 10% of those
|
|
64
|
+
attempted; it does not require zero errors. Set the threshold to your target.
|
|
65
|
+
|
|
66
|
+
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.
|
|
67
|
+
|
|
68
|
+
## Exit codes
|
|
69
|
+
|
|
70
|
+
<!-- contract:exit-codes -->
|
|
71
|
+
| Code | Meaning |
|
|
72
|
+
|------|---------|
|
|
73
|
+
| `0` | Score ≥ threshold (or no gate) **and** no baseline regression. |
|
|
74
|
+
| `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. |
|
|
75
|
+
| `2` | Usage / invalid-flag error, including a mistyped flag, a bad path (such as a missing `--boot` or `require:` file), or an unreadable baseline. |
|
|
76
|
+
<!-- /contract:exit-codes -->
|
|
77
|
+
|
|
78
|
+
## References
|
|
79
|
+
|
|
80
|
+
- Docs: https://davidteren.github.io/mutineer/
|
|
81
|
+
- Agent & CI guide: https://davidteren.github.io/mutineer/agentic-coding.html
|
|
82
|
+
- JSON schema: https://davidteren.github.io/mutineer/json-schema.html
|
|
83
|
+
- Ruby API: https://davidteren.github.io/mutineer/api/
|
|
84
|
+
- Source: https://github.com/davidteren/mutineer
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: mutineer
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 1.
|
|
4
|
+
version: 1.8.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- David Teren
|
|
@@ -54,8 +54,10 @@ files:
|
|
|
54
54
|
- lib/mutineer.rb
|
|
55
55
|
- lib/mutineer/baseline.rb
|
|
56
56
|
- lib/mutineer/changed_lines.rb
|
|
57
|
+
- lib/mutineer/child_coverage.rb
|
|
57
58
|
- lib/mutineer/child_stdout.rb
|
|
58
59
|
- lib/mutineer/cli.rb
|
|
60
|
+
- lib/mutineer/concern_blocks.rb
|
|
59
61
|
- lib/mutineer/config.rb
|
|
60
62
|
- lib/mutineer/coverage_map.rb
|
|
61
63
|
- lib/mutineer/daemon_backend.rb
|
|
@@ -63,11 +65,14 @@ files:
|
|
|
63
65
|
- lib/mutineer/daemon_server.rb
|
|
64
66
|
- lib/mutineer/external_backend.rb
|
|
65
67
|
- lib/mutineer/file_swap.rb
|
|
68
|
+
- lib/mutineer/init.rb
|
|
66
69
|
- lib/mutineer/isolation.rb
|
|
67
70
|
- lib/mutineer/job_plan.rb
|
|
68
71
|
- lib/mutineer/kill_channel.rb
|
|
69
72
|
- lib/mutineer/kill_matrix.rb
|
|
73
|
+
- lib/mutineer/migrate.rb
|
|
70
74
|
- lib/mutineer/minitest_integration.rb
|
|
75
|
+
- lib/mutineer/minitest_integration/in_test_database_error.rb
|
|
71
76
|
- lib/mutineer/minitest_integration/kill_recorder.rb
|
|
72
77
|
- lib/mutineer/minitest_integration/outer_reporter.rb
|
|
73
78
|
- lib/mutineer/minitest_integration/stop_at_first_failure.rb
|
|
@@ -79,6 +84,7 @@ files:
|
|
|
79
84
|
- lib/mutineer/mutators/base.rb
|
|
80
85
|
- lib/mutineer/mutators/boolean_connector.rb
|
|
81
86
|
- lib/mutineer/mutators/boolean_literal.rb
|
|
87
|
+
- lib/mutineer/mutators/call_to_receiver.rb
|
|
82
88
|
- lib/mutineer/mutators/chain_link.rb
|
|
83
89
|
- lib/mutineer/mutators/collection_method.rb
|
|
84
90
|
- lib/mutineer/mutators/comparison.rb
|
|
@@ -100,7 +106,9 @@ files:
|
|
|
100
106
|
- lib/mutineer/progress.rb
|
|
101
107
|
- lib/mutineer/project.rb
|
|
102
108
|
- lib/mutineer/project_path.rb
|
|
109
|
+
- lib/mutineer/rails_run_env.rb
|
|
103
110
|
- lib/mutineer/rails_worker_db.rb
|
|
111
|
+
- lib/mutineer/redaction.rb
|
|
104
112
|
- lib/mutineer/reporter.rb
|
|
105
113
|
- lib/mutineer/result.rb
|
|
106
114
|
- lib/mutineer/runner.rb
|
|
@@ -109,8 +117,10 @@ files:
|
|
|
109
117
|
- lib/mutineer/test_runners.rb
|
|
110
118
|
- lib/mutineer/test_runners/minitest.rb
|
|
111
119
|
- lib/mutineer/test_runners/rspec.rb
|
|
120
|
+
- lib/mutineer/triage.rb
|
|
112
121
|
- lib/mutineer/version.rb
|
|
113
122
|
- lib/mutineer/worker_pool.rb
|
|
123
|
+
- skills/mutineer/SKILL.md
|
|
114
124
|
homepage: https://github.com/davidteren/mutineer
|
|
115
125
|
licenses:
|
|
116
126
|
- MIT
|
|
@@ -120,6 +130,8 @@ metadata:
|
|
|
120
130
|
bug_tracker_uri: https://github.com/davidteren/mutineer/issues
|
|
121
131
|
documentation_uri: https://davidteren.github.io/mutineer/
|
|
122
132
|
rubygems_mfa_required: 'true'
|
|
133
|
+
hyperdrive_targets: "*"
|
|
134
|
+
hyperdrive_artifacts: skill
|
|
123
135
|
rdoc_options: []
|
|
124
136
|
require_paths:
|
|
125
137
|
- lib
|