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,124 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "optparse"
4
+ require_relative "config"
5
+ require_relative "mutator_registry"
6
+
7
+ module Mutineer
8
+ # Writes a starter `.mutineer.yml` and prints the first run command.
9
+ # It does not replace an existing file unless `--force` is set.
10
+ module Init
11
+ # Usage line for a bad invocation.
12
+ USAGE = "Usage: mutineer init [--rails] [--force]"
13
+
14
+ # Writes the config and prints the first command.
15
+ # 0 is success. 2 is a usage error, a refused overwrite, or a missing directory.
16
+ #
17
+ # @param argv [Array<String>] arguments after `init`.
18
+ # @param out [IO] where the command goes.
19
+ # @param err [IO] where errors go.
20
+ # @param dir [String] directory that receives `.mutineer.yml`.
21
+ # @return [Integer] 0 or 2.
22
+ def self.run(argv, out: $stdout, err: $stderr, dir: Dir.pwd)
23
+ rails = false
24
+ force = false
25
+ help = false
26
+ parser = OptionParser.new do |o|
27
+ o.banner = USAGE
28
+ o.on("--rails") { rails = true }
29
+ o.on("--force") { force = true }
30
+ o.on("--help") { help = 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
+ if help
39
+ out.puts USAGE
40
+ return 0
41
+ end
42
+ unless argv.empty?
43
+ err.puts "mutineer: init takes no source paths"
44
+ return 2
45
+ end
46
+
47
+ path = File.join(dir, CONFIG_FILE)
48
+ if File.directory?(path)
49
+ err.puts "mutineer: #{CONFIG_FILE} is a directory"
50
+ return 2
51
+ end
52
+ if File.exist?(path) && !force
53
+ err.puts "mutineer: #{CONFIG_FILE} already exists. Pass --force to replace it."
54
+ return 2
55
+ end
56
+ # The command writes one file. It does not create the project directory.
57
+ unless File.directory?(dir)
58
+ err.puts "mutineer: cannot write #{CONFIG_FILE}: no such directory"
59
+ return 2
60
+ end
61
+
62
+ begin
63
+ File.write(path, template(rails: rails))
64
+ rescue SystemCallError => e
65
+ err.puts "mutineer: cannot write #{CONFIG_FILE}: #{e.message}"
66
+ return 2
67
+ end
68
+ command = command_for(dir, rails: rails)
69
+ if command
70
+ out.puts command
71
+ else
72
+ err.puts "mutineer: no source folder found. Create app/models or lib, then run mutineer on that folder."
73
+ end
74
+ 0
75
+ end
76
+
77
+ # Starter config. `since` stays commented so the first run is a full scan.
78
+ # `--rails` also sets `rails: true` and leaves `daemon` commented.
79
+ #
80
+ # @param rails [Boolean] when true, set `rails: true`.
81
+ # @return [String] YAML text.
82
+ def self.template(rails:)
83
+ operators = MutatorRegistry::DEFAULT_NAMES.map { |name| " - #{name}" }.join("\n")
84
+ head = <<~YAML
85
+ # Mutineer config. Command-line flags override this file.
86
+ # These operators are the default set.
87
+ operators:
88
+ YAML
89
+ tail = <<~YAML
90
+ # since: origin/main
91
+ # Leave this commented so the first run is a full scan.
92
+ YAML
93
+ body = "#{head}#{operators}\n\n#{tail}"
94
+ return body unless rails
95
+
96
+ extra = <<~YAML
97
+ rails: true
98
+
99
+ # daemon: true
100
+ # Leave this commented until the support matrix says the daemon fits.
101
+ # The matrix is on https://davidteren.github.io/mutineer/rails.html#daemon
102
+ YAML
103
+ "#{body.rstrip}\n\n#{extra}"
104
+ end
105
+
106
+ # The first run command. Plain init names `lib`.
107
+ # `--rails` names each existing folder among `app/models`, `app/services`, and `lib`.
108
+ # A missing folder is left out: `mutineer run` rejects a path that is not there.
109
+ #
110
+ # @param dir [String] project directory.
111
+ # @param rails [Boolean] when true, print the Rails source folders.
112
+ # @return [String, nil] the command, or nil when no Rails source folder exists.
113
+ def self.command_for(dir, rails:)
114
+ return "mutineer run lib" unless rails
115
+
116
+ folders = ["app/models", "app/services", "lib"].select do |folder|
117
+ File.directory?(File.join(dir, folder))
118
+ end
119
+ return if folders.empty?
120
+
121
+ "mutineer run #{folders.join(" ")}"
122
+ end
123
+ end
124
+ end
@@ -4,7 +4,10 @@ require "tempfile"
4
4
  require_relative "result"
5
5
  require_relative "parser"
6
6
  require_relative "child_stdout"
7
+ require_relative "child_coverage"
7
8
  require_relative "kill_channel"
9
+ require_relative "concern_blocks"
10
+ require_relative "redaction"
8
11
 
9
12
  module Mutineer
10
13
  # Fork-based isolation for running one mutant. The block runs in a child
@@ -56,6 +59,7 @@ module Mutineer
56
59
  code = 0
57
60
  begin
58
61
  ChildStdout.silence
62
+ ChildCoverage.allow_start
59
63
  # A block that takes no channel (a zero-arity lambda) still runs.
60
64
  result = channel ? yield(wr) : yield
61
65
  code = result.is_a?(Integer) ? result : 0
@@ -63,7 +67,7 @@ module Mutineer
63
67
  code = e.status
64
68
  rescue Exception => e # rubocop:disable Lint/RescueException
65
69
  # STDERR, not `warn`: a test may have left `$stderr` as a StringIO.
66
- STDERR.puts "[mutineer-child] #{e.class}: #{e.message}"
70
+ STDERR.puts "[mutineer-child] #{Redaction.describe(e)}"
67
71
  code = 2
68
72
  end
69
73
  STDERR.flush
@@ -135,9 +139,10 @@ module Mutineer
135
139
  #
136
140
  # The verdict matches a run without `--matrix`, which skips everything after
137
141
  # the first failing serial test except the code around it (see
138
- # {KillChannel}). So when a serial test has named a kill and the child then
142
+ # {KillChannel}). So when a serial test has named a failure and the child then
139
143
  # ended inside a region that run would skip (an exit, a crash or the
140
- # timeout in a later test, class or group), the mutant is `killed`: the
144
+ # timeout in a later test, class or group), its first failure decides:
145
+ # `error` for an unavailable database outcome, otherwise `killed`. The
141
146
  # plain run never reached that point. An end anywhere else keeps the exit
142
147
  # status, because the plain run reaches that code too: the rest of the
143
148
  # failing test's class wrapper or group hooks, or the suite hooks. A kill in
@@ -164,6 +169,7 @@ module Mutineer
164
169
  return result.with(kills: Kills.new(killed_by: [], ran: [], complete: false)) if report.invalid
165
170
 
166
171
  result = Result.killed if report.started && report.serial_kill && report.skipping.positive?
172
+ result = Result.error if report.started && report.serial_error && report.skipping.positive?
167
173
  agrees = result.killed? ? report.killed.any? : result.survived? && report.killed.empty?
168
174
  complete = finished && report.started && report.finished && report.lost.zero? && agrees
169
175
  result.with(kills: Kills.new(killed_by: report.killed, ran: report.ran, complete: complete))
@@ -179,15 +185,50 @@ module Mutineer
179
185
  # "base"`). Writing it elsewhere makes those requires resolve to the temp
180
186
  # dir and raise LoadError.
181
187
  #
188
+ # Loading the file reopens its namespace. With lazy loading, that can be the
189
+ # first time Zeitwerk scans the namespace's directory. Zeitwerk skips hidden
190
+ # files, so the leading dot keeps it from rejecting the tempfile's name as a
191
+ # constant, in this child and in any other running at the same time (#253).
192
+ #
193
+ # A concern's stored `included` and `prepended` blocks from the source file
194
+ # are forgotten around the load, so ActiveSupport accepts the blocks the
195
+ # temp file stores (#256). For a def in such a block, the caller passes the
196
+ # text from {JobPlan.hook_mutant} and then calls
197
+ # {ConcernBlocks.place_hook_def} (#297).
198
+ #
182
199
  # @api private
183
200
  # @param mutated [String] mutated source text.
184
201
  # @param source_file [String] original source file path.
185
202
  # @return [Object] whatever `load` returns.
186
203
  def self.apply_whole_file(mutated, source_file)
187
- Tempfile.create(["mutineer_mutant", ".rb"], File.dirname(File.expand_path(source_file))) do |f|
188
- f.write(mutated)
204
+ write_beside(mutated, source_file) { |path| ConcernBlocks.replace(source_file) { load path } }
205
+ end
206
+
207
+ # Writes `code` to a hidden `.mutineer_mutant` file beside `source_file`,
208
+ # yields its path, and removes it after the block. Both strategies write
209
+ # through here. Only redefine enables the system-temp fallback when the
210
+ # source directory is not writable.
211
+ #
212
+ # The file is locked until the block ends, as the daemon locks its own file
213
+ # (#295). A SIGKILL drops the lock too. The pid in the name and the lock
214
+ # tell another run's sweep that the file is in use, so the sweep does not
215
+ # delete it between the write and the `load`.
216
+ #
217
+ # @api private
218
+ # @param code [String] the Ruby source to write.
219
+ # @param source_file [String] the source file the code replaces.
220
+ # @param fallback [Boolean] use the system temp directory when the source
221
+ # directory is not writable; redefine only.
222
+ # @yieldparam path [String] absolute path of the written file.
223
+ # @return [Object] whatever the block returns.
224
+ def self.write_beside(code, source_file, fallback: false)
225
+ dir = File.dirname(File.expand_path(source_file))
226
+ dir = Dir.tmpdir if fallback && !File.writable?(dir)
227
+ Tempfile.create([".mutineer_mutant", ".rb"], dir) do |f|
228
+ f.flock(File::LOCK_EX) rescue nil # rubocop:disable Style/RescueModifier
229
+ f.write(code)
189
230
  f.flush
190
- load f.path
231
+ yield f.path
191
232
  end
192
233
  end
193
234
 
@@ -206,13 +247,6 @@ module Mutineer
206
247
  # @param source [String] full source text.
207
248
  # @return [Object] whatever `load` returns.
208
249
  def self.apply_surgical(mutation, subject, source)
209
- loc = subject.def_node.location
210
- def_start = loc.start_offset
211
- snippet = source.byteslice(def_start...loc.end_offset)
212
- rel_s = mutation.start_offset - def_start
213
- rel_e = mutation.end_offset - def_start
214
- mutated_def = snippet.byteslice(0...rel_s) + mutation.replacement + snippet.byteslice(rel_e..)
215
-
216
250
  # Rebuild the FULL namespace nesting textually so unqualified enclosing-
217
251
  # namespace constants resolve exactly as the reload strategy would. A
218
252
  # bare redefinition on the owner would collapse Module.nesting to [owner]
@@ -228,12 +262,7 @@ module Mutineer
228
262
  # falsely survives. Re-open the singleton class so the redefinition lands on
229
263
  # the same method the test calls. `def self.foo` already carries its
230
264
  # receiver, so it is left as-is (wrapping it would mis-target).
231
- inner =
232
- if subject.singleton && subject.def_node.receiver.nil?
233
- "class << self\n#{mutated_def}\nend"
234
- else
235
- mutated_def
236
- end
265
+ inner = mutated_def(mutation, subject, source)
237
266
  inner = "#{subject.block_owner}.class_eval do\n#{inner}\nend" if subject.block_owner
238
267
  wrapped = "#{prefix}#{inner}#{"\nend" * keywords.size}"
239
268
 
@@ -255,15 +284,40 @@ module Mutineer
255
284
  # Module.nesting identically, with no dynamic string execution for
256
285
  # scanners to flag. The input is the project's OWN source (the enclosing
257
286
  # method, textually mutated), loaded only in this forked child.
258
- Tempfile.create(["mutineer_surgical", ".rb"]) do |f|
259
- f.write(wrapped)
260
- f.flush
261
- load f.path
262
- end
287
+ #
288
+ # The file sits beside the source, as in apply_whole_file, so `__dir__`
289
+ # and `require_relative` in the method resolve against its real
290
+ # neighbours (#279). In the temp dir they raise ENOENT or LoadError, and
291
+ # every mutant of the method dies whatever it changes. The hidden
292
+ # `.mutineer_mutant` name keeps Zeitwerk away (#253) and lets the parent
293
+ # sweep an orphan after a timeout kill.
294
+ #
295
+ # A read-only source dir keeps the 1.x system-temp location, so redefine
296
+ # still runs there (only path-relative methods mis-score, as before: #339).
297
+ write_beside(wrapped, subject.file, fallback: true) { |path| load path }
263
298
 
264
299
  target.send(vis, subject.name) if vis && vis != :public
265
300
  end
266
301
 
302
+ # The enclosing def with the mutation applied, wrapped in `class << self`
303
+ # for a singleton def with no receiver (#20). Pure text: it reads no live
304
+ # module, so the tool process can call it too ({JobPlan.hook_mutant}).
305
+ #
306
+ # @api private
307
+ # @param mutation [Mutineer::Mutation] mutation to apply.
308
+ # @param subject [Mutineer::Subject] subject being mutated.
309
+ # @param source [String] full source text.
310
+ # @return [String] the mutated def.
311
+ def self.mutated_def(mutation, subject, source)
312
+ loc = subject.def_node.location
313
+ def_start = loc.start_offset
314
+ snippet = source.byteslice(def_start...loc.end_offset)
315
+ rel_s = mutation.start_offset - def_start
316
+ rel_e = mutation.end_offset - def_start
317
+ mutated = snippet.byteslice(0...rel_s) + mutation.replacement + snippet.byteslice(rel_e..)
318
+ subject.singleton && subject.def_node.receiver.nil? ? "class << self\n#{mutated}\nend" : mutated
319
+ end
320
+
267
321
  # Resolve each namespace ELEMENT to its live Module and pick the correct
268
322
  # keyword (reopening a class with `module` — or vice versa — raises
269
323
  # TypeError), so the textual wrapper matches the real definitions.