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,184 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "outer_reporter"
4
+ require_relative "../redaction"
5
+
6
+ module Mutineer
7
+ class MinitestIntegration
8
+ # Scores a run as `error`, not `killed`, when its first failing test failed
9
+ # because of an Active Record connection or lock error (#296). Such a
10
+ # failure says the database broke, not that a test caught the mutant.
11
+ # Child-process only, like MinitestIntegration.
12
+ #
13
+ # Only the first failed result on the outer reporter counts (see
14
+ # {OuterReporter}). A run that stops at its first failure ends there, so a
15
+ # full run and a `--matrix` run give the same verdict. One limit: the tests
16
+ # of a `parallelize_me!` class record in the order their threads finish, so
17
+ # a mutant that makes one parallel test hit a database error and another
18
+ # fail an assertion can score `error` in one run and `killed` in the next.
19
+ # Stdlib only: the app-side daemon loads this file without Prism. An
20
+ # unknown Minitest shape arms nothing, and the run keeps its 0 or 1.
21
+ module InTestDatabaseError
22
+ extend OuterReporter::Client
23
+
24
+ # The Active Record errors that mean the database, not the test, failed.
25
+ # Subclasses count too: `ConnectionTimeoutError` (a pool timeout) and
26
+ # `DatabaseConnectionError` are `ConnectionNotEstablished`. Looked up by
27
+ # name when a result is recorded, so a project without Active Record, or
28
+ # a Rails without `ConnectionFailed` (before 7.1), matches nothing. Other
29
+ # `StatementInvalid` errors are not here: a mutant can cause bad SQL.
30
+ NAMES = %w[
31
+ ActiveRecord::ConnectionNotEstablished
32
+ ActiveRecord::ConnectionFailed
33
+ ActiveRecord::Deadlocked
34
+ ActiveRecord::LockWaitTimeout
35
+ ].freeze
36
+
37
+ # Subclasses of {NAMES} that point at the code, not the database. Rails 8
38
+ # raises `ConnectionNotDefined` for a role or shard that no connection
39
+ # defines, which a mutant of a `connected_to` call can cause. Rails 7.2
40
+ # raises a plain `ConnectionNotEstablished` there, so on 7.2 such a mutant
41
+ # scores `error`. The message is not matched (plan Q2).
42
+ CODE_ERROR_NAMES = %w[ActiveRecord::ConnectionNotDefined].freeze
43
+
44
+ # The lock errors in {NAMES}, which get their own stderr hint.
45
+ LOCK_ERROR_NAMES = %w[ActiveRecord::Deadlocked ActiveRecord::LockWaitTimeout].freeze
46
+
47
+ # Prepended on `Minitest::CompositeReporter`.
48
+ module RecordFirstFailure
49
+ # Records the result, then lets the module keep the first failure.
50
+ #
51
+ # @param result [Minitest::Result] the result of one test.
52
+ # @return [void]
53
+ def record(result)
54
+ super
55
+ InTestDatabaseError.record(self, result)
56
+ end
57
+ end
58
+
59
+ class << self
60
+ # The first failed result's database error, false when that result
61
+ # failed for another reason, or nil before any failure.
62
+ #
63
+ # @return [Exception, false, nil]
64
+ attr_accessor :first_failure
65
+
66
+ # Installs the hooks and arms the module for this process.
67
+ #
68
+ # @return [Boolean] false when the Minitest shape is unknown.
69
+ def arm!
70
+ outer = OuterReporter.hook_for_loaded_minitest
71
+ return false unless outer
72
+
73
+ OuterReporter.prepend_once(::Minitest::CompositeReporter, RecordFirstFailure)
74
+ OuterReporter.prepend_once(::Minitest.singleton_class, outer)
75
+ OuterReporter.register(self)
76
+ self.armed_pid = Process.pid
77
+ self.armed_reporter = nil
78
+ self.first_failure = nil
79
+ true
80
+ end
81
+
82
+ # Clears the armed state.
83
+ #
84
+ # @return [void]
85
+ def disarm!
86
+ self.armed_pid = nil
87
+ self.armed_reporter = nil
88
+ self.first_failure = nil
89
+ end
90
+
91
+ # Keeps the first failed result recorded on the outer reporter. Minitest
92
+ # records from several threads only under its own reporter lock. A
93
+ # result it cannot read counts as an ordinary failure, so a fault here
94
+ # keeps the old verdict and never turns a kill into an error.
95
+ #
96
+ # @param reporter [Minitest::CompositeReporter] the recording reporter.
97
+ # @param result [Minitest::Result] the result of one test.
98
+ # @return [void]
99
+ def record(reporter, result)
100
+ return if result.passed? || result.skipped?
101
+ return unless first_failure.nil? && outer_reporter?(reporter)
102
+
103
+ self.first_failure = database_error(result.failures.first) || false
104
+ rescue StandardError
105
+ self.first_failure = false
106
+ end
107
+
108
+ # The run's exit code: 2 instead of 1 when the armed run's first failure
109
+ # was a database error. Then it also writes one line on stderr that
110
+ # names the error. `STDERR`, not `warn`: a test can leave `$stderr` as
111
+ # a `StringIO`. The flush matters because both fork boundaries end with
112
+ # `exit!`.
113
+ #
114
+ # @param code [Integer] 0 or 1 from the run.
115
+ # @return [Integer] `code`, or 2.
116
+ def exit_code(code)
117
+ error = first_failure if armed_here?
118
+ return code unless code == 1 && error
119
+
120
+ STDERR.puts(line(error))
121
+ STDERR.flush
122
+ 2
123
+ end
124
+
125
+ # The database error a failure wraps. The first entry of a result is
126
+ # the error that ended the test: Minitest records the setup or body
127
+ # error before a teardown error. The cause chain is not read: Active
128
+ # Record already translates driver errors into the listed classes.
129
+ #
130
+ # Minitest before 5.14 names the wrapped error `exception`.
131
+ #
132
+ # Shared with the matrix recorder so an unavailable database outcome
133
+ # cannot be named as a mutation kill.
134
+ #
135
+ # @api private
136
+ # @param failure [Minitest::Assertion, nil] the result's first entry.
137
+ # @return [Exception, nil]
138
+ def database_error(failure)
139
+ return unless failure.is_a?(::Minitest::UnexpectedError)
140
+
141
+ error = failure.respond_to?(:error) ? failure.error : failure.exception
142
+ return if loaded(CODE_ERROR_NAMES).any? { |klass| error.is_a?(klass) }
143
+
144
+ error if loaded(NAMES).any? { |klass| error.is_a?(klass) }
145
+ end
146
+
147
+ private
148
+
149
+ # The named classes this process has loaded.
150
+ #
151
+ # @param names [Array<String>] constant names.
152
+ # @return [Array<Class>]
153
+ def loaded(names)
154
+ names.filter_map { |name| Object.const_get(name) if Object.const_defined?(name) }
155
+ end
156
+
157
+ # The stderr line. Redacted before the cut to one line, so a cut can
158
+ # never split a password away from its URL. The wording fits every run,
159
+ # the clean check included, and a mutant can cause the error too.
160
+ #
161
+ # @param error [Exception] the database error.
162
+ # @return [String]
163
+ def line(error)
164
+ text = Redaction.text("#{error.class}: #{error.message}".scrub)
165
+ text = text.lines.first.to_s.chomp.delete_suffix(".")
166
+ "[mutineer-child] a test failed with a database error, so the run has no verdict: #{text}. #{hint(error)}"
167
+ end
168
+
169
+ # What to check for the error: a lock error comes from a second
170
+ # connection or thread, any other from the server.
171
+ #
172
+ # @param error [Exception] the database error.
173
+ # @return [String]
174
+ def hint(error)
175
+ if loaded(LOCK_ERROR_NAMES).any? { |klass| error.is_a?(klass) }
176
+ "Look for a test or app code that holds a lock on a second connection or thread."
177
+ else
178
+ "Check that the database server is up and has free connections."
179
+ end
180
+ end
181
+ end
182
+ end
183
+ end
184
+ end
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "outer_reporter"
4
+ require_relative "in_test_database_error"
4
5
  require_relative "../kill_channel"
5
6
 
6
7
  module Mutineer
@@ -22,7 +23,7 @@ module Mutineer
22
23
  # Prepended on each loaded test class: one test's run. Serial and parallel
23
24
  # runs both call it, in Minitest 5 and 6.
24
25
  module MarkSkippedTest
25
- # Runs the test inside a `skip` region once a serial test has killed.
26
+ # Runs the test inside a `skip` region once a serial test has failed.
26
27
  #
27
28
  # @return [Minitest::Result]
28
29
  def run
@@ -35,7 +36,7 @@ module Mutineer
35
36
  # A run without `--matrix` skips both after a stop (see
36
37
  # StopAtFirstFailure::SkipAfterStop6).
37
38
  module MarkSkippedClass6
38
- # Runs the class inside a `skip` region once a serial test has killed.
39
+ # Runs the class inside a `skip` region once a serial test has failed.
39
40
  #
40
41
  # @param reporter [Minitest::CompositeReporter]
41
42
  # @param options [Hash]
@@ -46,7 +47,7 @@ module Mutineer
46
47
  end
47
48
 
48
49
  # Runs one test's class-level step inside a `skip` region once a
49
- # serial test has killed.
50
+ # serial test has failed.
50
51
  #
51
52
  # @param klass [Class]
52
53
  # @param method_name [String]
@@ -59,7 +60,7 @@ module Mutineer
59
60
 
60
61
  # The Minitest 5 form of {MarkSkippedClass6}.
61
62
  module MarkSkippedClass5
62
- # Runs the class inside a `skip` region once a serial test has killed.
63
+ # Runs the class inside a `skip` region once a serial test has failed.
63
64
  #
64
65
  # @param reporter [Minitest::CompositeReporter]
65
66
  # @param options [Hash]
@@ -70,7 +71,7 @@ module Mutineer
70
71
  end
71
72
 
72
73
  # Runs one test's class-level step inside a `skip` region once a
73
- # serial test has killed.
74
+ # serial test has failed.
74
75
  #
75
76
  # @param klass [Class]
76
77
  # @param method_name [String]
@@ -114,11 +115,11 @@ module Mutineer
114
115
  # @return [Integer, nil]
115
116
  attr_accessor :seen
116
117
 
117
- # True once a serial test killed: from then on, a run without `--matrix`
118
- # skips each later test and class.
118
+ # True once a serial test failed, including a database failure: from
119
+ # then on, a run without `--matrix` skips each later test and class.
119
120
  #
120
121
  # @return [Boolean, nil]
121
- attr_accessor :serial_killed
122
+ attr_accessor :serial_failed
122
123
 
123
124
  # Installs the hooks, arms the recorder for this process, and writes the
124
125
  # channel's `start` line. Call it after the test files load, so the
@@ -149,7 +150,7 @@ module Mutineer
149
150
  # the run joins it without running, which would break the count.
150
151
  self.runnables = runnables.dup
151
152
  self.seen = 0
152
- self.serial_killed = false
153
+ self.serial_failed = false
153
154
  KillChannel.write_start(channel)
154
155
  true
155
156
  end
@@ -186,7 +187,7 @@ module Mutineer
186
187
  self.armed_reporter = nil
187
188
  self.channel = nil
188
189
  self.runnables = nil
189
- self.serial_killed = false
190
+ self.serial_failed = false
190
191
  end
191
192
 
192
193
  # Writes the `parallel` line when the first parallel class starts on the
@@ -206,7 +207,7 @@ module Mutineer
206
207
  end
207
208
 
208
209
  # Runs the block between `skip` and `unskip` when a serial test has
209
- # killed in this armed process, else just runs it. No `ensure`: a block
210
+ # failed in this armed process, else just runs it. No `ensure`: a block
210
211
  # that never returns (an exit, a crash) must leave its region open, so
211
212
  # the parent knows the child ended where a run without `--matrix`
212
213
  # would not have been.
@@ -214,7 +215,7 @@ module Mutineer
214
215
  # @yieldreturn [Object]
215
216
  # @return [Object] the block's value.
216
217
  def skipping
217
- open = channel && serial_killed && armed_here?
218
+ open = channel && serial_failed && armed_here?
218
219
  KillChannel.write_skip(channel) if open
219
220
  value = yield
220
221
  KillChannel.write_unskip(channel) if open
@@ -222,9 +223,10 @@ module Mutineer
222
223
  end
223
224
 
224
225
  # Sends one result recorded on `reporter`: a pass, or a kill for a
225
- # failure or an error. Skips send no test line, though they count as
226
- # seen, and results on other reporters count for nothing. The
227
- # `parallel` line goes out when the first parallel class starts (see
226
+ # failure or an error, or an unavailable database outcome. Skips send
227
+ # no test line, though they count as seen, and results on other
228
+ # reporters count for nothing. The `parallel` line goes out when the
229
+ # first parallel class starts (see
228
230
  # {.class_starting}), so a kill that precedes it came from a serial test.
229
231
  #
230
232
  # @param reporter [Minitest::CompositeReporter] the recording reporter.
@@ -251,8 +253,14 @@ module Mutineer
251
253
  def send_result(result)
252
254
  return if result.skipped?
253
255
 
254
- event = result.passed? ? KillChannel::PASS : KillChannel::KILL
255
- self.serial_killed = true if event == KillChannel::KILL && !parallel_marked
256
+ event = if result.passed?
257
+ KillChannel::PASS
258
+ elsif InTestDatabaseError.database_error(result.failures.first)
259
+ KillChannel::UNAVAILABLE
260
+ else
261
+ KillChannel::KILL
262
+ end
263
+ self.serial_failed = true if event != KillChannel::PASS && !parallel_marked
256
264
  file, line = Array(result.source_location)
257
265
  KillChannel.write(channel, event, file, *name_and_id(result, line))
258
266
  rescue StandardError
@@ -2,11 +2,13 @@
2
2
 
3
3
  require_relative "minitest_integration/stop_at_first_failure"
4
4
  require_relative "minitest_integration/kill_recorder"
5
+ require_relative "minitest_integration/in_test_database_error"
5
6
 
6
7
  module Mutineer
7
8
  # Child-process-only: loads a test file in the current process and runs it
8
9
  # programmatically, returning an exit status integer (0 = all passed,
9
- # 1 = any failure/error).
10
+ # 1 = any failure/error, 2 = the first failure was an Active Record
11
+ # connection or lock error).
10
12
  #
11
13
  # Never call this in the parent — it manipulates global Minitest state
12
14
  # (autorun, runnables) that only makes sense in a throwaway forked child.
@@ -14,15 +16,39 @@ module Mutineer
14
16
  # A missing minitest is rescued as FrameworkUnavailable (Isolation.run
15
17
  # still turns that raise into exit 2). There is no rescue around the
16
18
  # suite run itself: Isolation.run's fork block is the single exception
17
- # boundary for unexpected errors. Swallowing those here would create a
18
- # second exit-2 path and break this method's 0/1 return contract.
19
+ # boundary for unexpected errors. Swallowing those here would hide a
20
+ # crash as a verdict. The one 2 this method returns on purpose comes from
21
+ # Minitest's own results: the run's first failing test failed with an
22
+ # Active Record connection or lock error (#296, {InTestDatabaseError}).
19
23
  class MinitestIntegration
20
- # The seed of a mutant run (one that stops at the first failure, or a
21
- # `--matrix` run that records every test), unless `SEED` is set. With the
22
- # stop, the test order can decide `killed` vs `timeout`; a fixed order keeps
23
- # the verdict stable for a `--baseline` gate. A matrix run uses the same
24
+ # The seed of every Minitest run Mutineer starts, unless `SEED` is set:
25
+ # coverage capture, the clean checks and the mutant runs (#282). A file's
26
+ # clean check then runs its tests in the order a mutant run of that file
27
+ # uses. Several covering files can still differ from the combined clean
28
+ # check: a smaller class list shuffles differently. With the stop,
29
+ # the test order can decide `killed` vs `timeout`; a fixed order keeps the
30
+ # verdict stable for a `--baseline` gate. A `--matrix` run uses the same
24
31
  # order, so its first failure comes at the same point as the stop's.
25
- STOP_AT_FIRST_FAILURE_SEED = 1
32
+ #
33
+ # @api private
34
+ PINNED_SEED = 1
35
+
36
+ # The arguments that give `Minitest.run` the shared seed. With `SEED` set,
37
+ # none: Minitest reads `SEED` itself.
38
+ #
39
+ # @api private
40
+ # @return [Array<String>] `["--seed", "1"]`, or `[]` when `SEED` is set.
41
+ def self.seed_args
42
+ ENV["SEED"] ? [] : ["--seed", seed]
43
+ end
44
+
45
+ # The seed the Minitest runs use: `SEED` when set, else {PINNED_SEED}.
46
+ #
47
+ # @api private
48
+ # @return [String]
49
+ def self.seed
50
+ ENV.fetch("SEED", PINNED_SEED.to_s)
51
+ end
26
52
 
27
53
  # Tested via runner_test.rb, not in isolation — a direct unit test
28
54
  # would require forking and duplicate isolation_test's coverage.
@@ -36,7 +62,8 @@ module Mutineer
36
62
  # test. Only the mutant path passes true.
37
63
  # @param record_to [IO, nil] a `--matrix` run: send each test's outcome to
38
64
  # this channel (see {KillRecorder}) and run every test.
39
- # @return [Integer] 0 on success, 1 on failure.
65
+ # @return [Integer] 0 on success, 1 on failure, 2 when the first failure
66
+ # was an Active Record connection or lock error (see {InTestDatabaseError}).
40
67
  # @raise [ArgumentError] when both options are given: a matrix run never stops.
41
68
  def self.run(test_files, stop_at_first_failure: false, record_to: nil)
42
69
  if stop_at_first_failure && record_to
@@ -75,22 +102,25 @@ module Mutineer
75
102
  elsif stop_at_first_failure
76
103
  StopAtFirstFailure.arm!(Minitest::Runnable.runnables)
77
104
  end
78
- # Pin the seed only when a hook is armed; an unknown Minitest shape gets
79
- # the normal full, randomly ordered run.
80
- args = armed && !ENV["SEED"] ? ["--seed", STOP_AT_FIRST_FAILURE_SEED.to_s] : []
105
+ # An unknown Minitest shape arms no hook and gets a full run, in the
106
+ # same seeded order.
81
107
  keep_file_order(rank) if armed
108
+ # Every run, on its own line: `armed` decides the file order (#296).
109
+ InTestDatabaseError.arm!
82
110
  # No silencing here: the fork boundary that calls this method has already
83
111
  # pointed stdout at File::NULL (see ChildStdout).
84
- passed = Minitest.run(args)
112
+ passed = Minitest.run(seed_args)
85
113
  # Reached only when the suite returned: a test that exits the process
86
114
  # skips it, and the parent then keeps the row incomplete.
87
115
  KillRecorder.finish! if record_to
88
116
 
89
117
  # A plugin can replace the summary reporter, so a stop decides by itself.
90
- passed && !StopAtFirstFailure.stopped_here? ? 0 : 1
118
+ code = passed && !StopAtFirstFailure.stopped_here? ? 0 : 1
119
+ InTestDatabaseError.exit_code(code)
91
120
  ensure
92
121
  StopAtFirstFailure.disarm!
93
122
  KillRecorder.disarm!
123
+ InTestDatabaseError.disarm!
94
124
  end
95
125
 
96
126
  # Runs the test classes in the order of their files (#203). Minitest
@@ -1,5 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require_relative "config"
3
4
  require_relative "mutators/arithmetic"
4
5
  require_relative "mutators/comparison"
5
6
  require_relative "mutators/boolean_connector"
@@ -15,6 +16,7 @@ require_relative "mutators/safe_navigation"
15
16
  require_relative "mutators/range_literal"
16
17
  require_relative "mutators/negation_removal"
17
18
  require_relative "mutators/chain_link"
19
+ require_relative "mutators/call_to_receiver"
18
20
  require_relative "mutators/operand_removal"
19
21
  require_relative "mutators/array_literal"
20
22
  require_relative "mutators/condition_forcing"
@@ -46,6 +48,7 @@ module Mutineer
46
48
  "range" => Mutators::RangeLiteral,
47
49
  "negation_removal" => Mutators::NegationRemoval,
48
50
  "chain_link" => Mutators::ChainLink,
51
+ "call_to_receiver" => Mutators::CallToReceiver,
49
52
  "operand_removal" => Mutators::OperandRemoval,
50
53
  "array_literal" => Mutators::ArrayLiteral,
51
54
  "condition_true" => Mutators::ConditionTrue,
@@ -58,7 +61,7 @@ module Mutineer
58
61
  # Tier-2 operators that remain opt-in.
59
62
  TIER2_NAMES = %w[return_nil literal_mutation condition_negation string_literal regex collection_method
60
63
  safe_navigation range negation_removal
61
- chain_link operand_removal array_literal
64
+ chain_link call_to_receiver operand_removal array_literal
62
65
  condition_true condition_false operator_assignment].freeze
63
66
 
64
67
  # Short human-readable descriptions for each operator.
@@ -78,6 +81,7 @@ module Mutineer
78
81
  "range" => ".. <-> ...",
79
82
  "negation_removal" => "!x, not x -> x",
80
83
  "chain_link" => "drop one call from a chain: a.b.c -> a.c",
84
+ "call_to_receiver" => "drop the last call of a chain: foo.bar -> foo",
81
85
  "operand_removal" => "a && b -> a, b",
82
86
  "array_literal" => "[a, b] -> []",
83
87
  "condition_true" => "if/elsif/unless/ternary/modifier/case-in guard condition -> true",
@@ -91,7 +95,7 @@ module Mutineer
91
95
  # @return [Array<Class>] mutator classes in the requested order.
92
96
  # @raise [ArgumentError] when a name is unknown.
93
97
  def self.resolve(names = DEFAULT_NAMES)
94
- names.map { |n| ALL.fetch(n) { raise ArgumentError, "Unknown operator: #{n.inspect}" } }
98
+ names.map { |n| ALL.fetch(n) { raise ArgumentError, "Unknown operator: #{n.inspect}#{Mutineer.did_you_mean(n, ALL.keys)}" } }
95
99
  end
96
100
 
97
101
  # Returns whether the operator is part of the default Tier-1 set.
@@ -25,12 +25,14 @@ module Mutineer
25
25
  #
26
26
  # The operator skips an implicit array (`x = 1, 2`), because it has no
27
27
  # brackets. It also skips an array that holds a heredoc, because the
28
- # heredoc body stays behind as code.
28
+ # heredoc body stays behind as code. Only the heredoc skip counts as
29
+ # declined.
29
30
  #
30
31
  # @param node [Prism::ArrayNode] array node to inspect.
31
32
  # @return [void]
32
33
  def emit(node)
33
- return if node.opening_loc.nil? || node.elements.empty? || heredoc?(node)
34
+ return if node.opening_loc.nil? || node.elements.empty?
35
+ return decline if heredoc?(node)
34
36
 
35
37
  @mutations << Mutation.new(
36
38
  start_offset: node.location.start_offset,
@@ -20,6 +20,7 @@ module Mutineer
20
20
  def mutations_for(subject, source)
21
21
  @source = source
22
22
  @mutations = []
23
+ @declined = 0
23
24
  @body = subject.def_node.body
24
25
  @body&.accept(self)
25
26
  drop_dangling_heredocs
@@ -50,26 +51,50 @@ module Mutineer
50
51
  @in_undiscovered = outer
51
52
  end
52
53
 
54
+ # Returns how many candidates the last {#mutations_for} call declined: an
55
+ # edit that would split a heredoc from its body, or an equivalent skip
56
+ # listed in docs/equivalent-skips.md. A declined candidate is never a
57
+ # mutation, so it is not in the run's total.
58
+ #
59
+ # @return [Integer] declined candidates; 0 before the first call.
60
+ def declined
61
+ @declined || 0
62
+ end
63
+
53
64
  private
54
65
 
55
- # Drops a mutation that deletes a heredoc opener and leaves its body.
66
+ # Counts one declined candidate.
67
+ #
68
+ # @return [nil] so a skip line reads `return decline if ...`.
69
+ def decline
70
+ @declined += 1
71
+ nil
72
+ end
73
+
74
+ # Drops a mutation that splits a heredoc opener from its body.
56
75
  #
57
76
  # The body sits past the opener's node. Replacing the opener with text
58
77
  # that does not contain it turns the body into Ruby, which parses and
59
78
  # then raises. A replacement that still contains the opener keeps the
60
- # body attached, so that mutation stays.
79
+ # body attached, so that mutation stays. The reverse also breaks: when
80
+ # the replaced range holds the body but the replacement keeps only the
81
+ # opener, the opener has no body and the source does not parse. A
82
+ # replacement that copies the opener and the body together stays.
83
+ # Each dropped mutation counts as declined.
61
84
  #
62
85
  # @return [void]
63
86
  def drop_dangling_heredocs
87
+ before = @mutations.size
64
88
  @mutations.reject! { |mutation| dangling_heredoc?(mutation) }
89
+ @declined += before - @mutations.size
65
90
  end
66
91
 
67
- # Returns whether the mutation removes a heredoc opener whose body hangs
68
- # past the replaced range.
92
+ # Returns whether the mutation replaces a heredoc opener and keeps the
93
+ # opener without its body, or the body without its opener.
69
94
  #
70
95
  # @param mutation [Mutineer::Mutation] candidate edit.
71
96
  # @param node [Prism::Node, nil] subtree to search. Defaults to the body.
72
- # @return [Boolean] true when the edit would leave a heredoc body behind.
97
+ # @return [Boolean] true when the edit would split a heredoc from its body.
73
98
  def dangling_heredoc?(mutation, node = @body)
74
99
  return false if node.nil? || !node.is_a?(Prism::Node)
75
100
 
@@ -78,9 +103,13 @@ module Mutineer
78
103
  if opening && opening.start_offset >= mutation.start_offset && opening.start_offset < mutation.end_offset
79
104
  closing = node.respond_to?(:closing_loc) ? node.closing_loc : nil
80
105
  hangs = closing.nil? || closing.end_offset > mutation.end_offset
106
+ opener = @source.byteslice(opening.start_offset, opening.end_offset - opening.start_offset)
107
+ kept = !opener.empty? && mutation.replacement.include?(opener)
81
108
  if hangs
82
- opener = @source.byteslice(opening.start_offset, opening.end_offset - opening.start_offset)
83
- return true if opener.empty? || !mutation.replacement.include?(opener)
109
+ return true unless kept
110
+ elsif kept
111
+ whole = @source.byteslice(opening.start_offset, closing.end_offset - opening.start_offset)
112
+ return true unless mutation.replacement.include?(whole)
84
113
  end
85
114
  end
86
115
  end