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
@@ -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
@@ -2,5 +2,5 @@
2
2
 
3
3
  module Mutineer
4
4
  # Current Mutineer release version.
5
- VERSION = "1.6.0"
5
+ VERSION = "1.8.0"
6
6
  end
@@ -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: #{e.class}: #{e.message}")
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.6.0
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