mutineer 1.7.0 → 1.8.1

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 (46) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +466 -0
  3. data/README.md +157 -747
  4. data/lib/mutineer/baseline.rb +1 -1
  5. data/lib/mutineer/changed_lines.rb +2 -1
  6. data/lib/mutineer/cli.rb +132 -28
  7. data/lib/mutineer/concern_blocks.rb +187 -5
  8. data/lib/mutineer/config.rb +6 -0
  9. data/lib/mutineer/coverage_map.rb +92 -17
  10. data/lib/mutineer/daemon_backend.rb +75 -32
  11. data/lib/mutineer/daemon_client.rb +50 -17
  12. data/lib/mutineer/daemon_server.rb +93 -41
  13. data/lib/mutineer/external_backend.rb +150 -17
  14. data/lib/mutineer/init.rb +1 -1
  15. data/lib/mutineer/isolation.rb +70 -25
  16. data/lib/mutineer/job_plan.rb +119 -34
  17. data/lib/mutineer/kill_channel.rb +24 -14
  18. data/lib/mutineer/migrate.rb +10 -8
  19. data/lib/mutineer/minitest_integration/in_test_database_error.rb +184 -0
  20. data/lib/mutineer/minitest_integration/kill_recorder.rb +25 -17
  21. data/lib/mutineer/minitest_integration.rb +44 -14
  22. data/lib/mutineer/mutators/array_literal.rb +4 -2
  23. data/lib/mutineer/mutators/base.rb +22 -0
  24. data/lib/mutineer/mutators/call_to_receiver.rb +20 -7
  25. data/lib/mutineer/mutators/chain_link.rb +6 -6
  26. data/lib/mutineer/mutators/condition_forcing.rb +6 -3
  27. data/lib/mutineer/mutators/operand_removal.rb +4 -2
  28. data/lib/mutineer/mutators/range_literal.rb +105 -4
  29. data/lib/mutineer/mutators/return_nil.rb +1 -0
  30. data/lib/mutineer/orphan_guard.rb +18 -6
  31. data/lib/mutineer/pairing.rb +62 -1
  32. data/lib/mutineer/project.rb +226 -12
  33. data/lib/mutineer/rails_worker_db.rb +200 -16
  34. data/lib/mutineer/redaction.rb +112 -11
  35. data/lib/mutineer/reporter.rb +109 -21
  36. data/lib/mutineer/result.rb +33 -5
  37. data/lib/mutineer/runner.rb +126 -18
  38. data/lib/mutineer/statement_lines.rb +14 -8
  39. data/lib/mutineer/subject.rb +13 -5
  40. data/lib/mutineer/test_runners/minitest.rb +2 -1
  41. data/lib/mutineer/test_runners.rb +4 -2
  42. data/lib/mutineer/triage.rb +2 -2
  43. data/lib/mutineer/version.rb +1 -1
  44. data/lib/mutineer/worker_pool.rb +2 -1
  45. data/skills/mutineer/SKILL.md +84 -0
  46. metadata +5 -1
@@ -50,7 +50,7 @@ module Mutineer
50
50
  # @return [Mutineer::Baseline] baseline object.
51
51
  # @raise [Mutineer::ConfigError] when the file is missing or invalid.
52
52
  def self.load(path)
53
- doc = JSON.parse(File.read(path))
53
+ doc = JSON.parse(File.read(path, encoding: "UTF-8"))
54
54
  unless doc.is_a?(Hash) && doc["schema_version"] && doc["survivors"].is_a?(Array)
55
55
  raise ConfigError, "not a Mutineer JSON report: #{path}"
56
56
  end
@@ -73,7 +73,8 @@ module Mutineer
73
73
  # @return [String] diff text, or `""` on failure (after a stderr warning).
74
74
  def git_diff(ref, abs_file, project_root)
75
75
  out, _err, status = Open3.capture3(
76
- "git", "--literal-pathspecs", "-C", project_root, "diff", "--unified=0", ref, "--", abs_file
76
+ "git", "--literal-pathspecs", "-C", project_root, "diff", "--unified=0", ref, "--", abs_file,
77
+ binmode: true # the hunk regex must not trip on a changed line's non-ASCII bytes
77
78
  )
78
79
  if status.success?
79
80
  return out if indexed?(abs_file, project_root)
data/lib/mutineer/cli.rb CHANGED
@@ -1,5 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require "fileutils"
3
4
  require "optparse"
4
5
  require "open3"
5
6
  require_relative "version"
@@ -17,6 +18,7 @@ require_relative "migrate"
17
18
  require_relative "mutator_registry"
18
19
  require_relative "triage"
19
20
  require_relative "init"
21
+ require_relative "redaction"
20
22
 
21
23
  module Mutineer
22
24
  # Command-line entry point. `start` is the single public method called by
@@ -34,7 +36,7 @@ module Mutineer
34
36
  Usage: mutineer [options] <command> [args]
35
37
 
36
38
  Commands:
37
- run [options] <source...> --test <test> [--test <test>...]
39
+ run [options] <source...> [--test <test>...]
38
40
  Mutate, run, and report
39
41
  run --dry-run [options] <source...> Print candidate mutations only
40
42
  triage REPORT.json --reason TEXT
@@ -48,7 +50,9 @@ module Mutineer
48
50
  --force replaces an existing file.
49
51
 
50
52
  Run options:
51
- --test FILE Test file covering the sources (one per flag; repeat it)
53
+ --test FILE Test file covering the sources (one per flag; repeat it).
54
+ Omit to pair each source with its test by convention
55
+ (not under --dry-run)
52
56
  --operators LIST Comma-separated operator names (default: Tier 1 set)
53
57
  --threshold FLOAT Fail (exit 1) when score < FLOAT (default: 0 = off)
54
58
  --baseline FILE Fail (exit 1) on NEW survivors / score drop vs a prior
@@ -73,7 +77,7 @@ module Mutineer
73
77
  cover these sources
74
78
  --framework NAME minitest or rspec (default: auto-detect from --test names)
75
79
  --boot FILE Require FILE once in the parent to boot the app env, then
76
- fork per mutant (Rails apps; requires --test)
80
+ fork per mutant (Rails apps; needs a test, given or found by convention)
77
81
  --rails Boot config/environment; without --daemon, defaults to
78
82
  redefine and serial execution
79
83
  --test-command CMD Run the target suite in the app's own runtime as a
@@ -97,7 +101,9 @@ module Mutineer
97
101
  matrix:)
98
102
  --allow-empty A run with no mutants is expected; do not warn (--no-allow-empty
99
103
  beats a .mutineer.yml allow_empty:)
100
- --verbose Surface the real error when a fork capture fails (alias: --debug)
104
+ --verbose Show full error details: the backtrace and causes of a load
105
+ failure, the real error of a failed fork capture, and the
106
+ --test-command output (alias: --debug)
101
107
 
102
108
  Options:
103
109
  --list-operators List available operators (default vs optional) and exit
@@ -178,7 +184,7 @@ module Mutineer
178
184
 
179
185
  begin
180
186
  parser.parse!(argv)
181
- rescue OptionParser::InvalidOption, OptionParser::MissingArgument, Mutineer::ConfigError => e
187
+ rescue OptionParser::ParseError, Mutineer::ConfigError => e
182
188
  warn "mutineer: #{e.message}"
183
189
  exit 2
184
190
  end
@@ -207,7 +213,9 @@ module Mutineer
207
213
  case argv.first
208
214
  when "run"
209
215
  warn_config_root_mismatch(file_path, config.project_root) if file_path
210
- tests_as_sources = argv[1..].grep(%r{(\A|/)(test|spec)/.*_(test|spec)\.rb\z})
216
+ tests_as_sources = argv[1..].select do |arg|
217
+ Pairing.test_given_as_source?(arg, project_root: config.project_root, tests: config.tests)
218
+ end
211
219
  if config.explicit?(:tests) && tests_as_sources.any?
212
220
  warn "mutineer: #{tests_as_sources.join(', ')} looks like a test file, not a source. " \
213
221
  "--test takes one file; repeat it for each test file (--test a_test.rb --test b_test.rb)"
@@ -233,6 +241,18 @@ module Mutineer
233
241
  warn "mutineer: unknown command '#{argv.first}'"
234
242
  exit 2
235
243
  end
244
+ rescue StandardError, ScriptError => e
245
+ # Last resort (#341): an error no handler above expects would otherwise
246
+ # reach Ruby's default printer, which shows its message unredacted. Same
247
+ # exit 1 as that printer, with the message and backtrace redacted. A
248
+ # message that raises while it is built is not shown at all.
249
+ details = begin
250
+ e.full_message(highlight: false)
251
+ rescue StandardError, ScriptError
252
+ Redaction::FAILED
253
+ end
254
+ warn "mutineer: #{Redaction.text(details)}"
255
+ exit 1
236
256
  end
237
257
 
238
258
  # Rewrites old-format ids in the loaded `.mutineer.yml` `ignore:` list.
@@ -248,7 +268,7 @@ module Mutineer
248
268
  # @return [void]
249
269
  def self.migrate(config, file_path)
250
270
  current, old_to_new = Migrate.id_maps(config)
251
- text = File.read(file_path)
271
+ text = File.read(file_path, encoding: "UTF-8")
252
272
  outcome = Migrate.rewrite(text, current, old_to_new)
253
273
  outcome.replacements.each do |rep|
254
274
  puts "[mutineer] #{rep.old_id} -> #{rep.new_ids.join(', ')}"
@@ -336,38 +356,55 @@ module Mutineer
336
356
  config.dry_run ? dry_run(config) : execute(config)
337
357
  rescue ArgumentError => e
338
358
  # Unknown --operators value surfaces here; no backtrace reaches the user.
359
+ warn "mutineer: #{Redaction.text(e.message)}"
360
+ exit 2
361
+ rescue Mutineer::ConfigError => e
362
+ # A config value that only the booted app can check (`shared_databases`
363
+ # naming the primary database). A usage error, raised before any mutant runs.
339
364
  warn "mutineer: #{e.message}"
340
365
  exit 2
341
366
  rescue SystemCallError => e
342
367
  # A missing/unreadable path reaches here as Errno::ENOENT etc. A plain
343
368
  # message and usage exit, never a raw backtrace.
344
- warn "mutineer: #{e.message}"
369
+ warn "mutineer: #{Redaction.text(e.message)}"
345
370
  exit 2
346
371
  rescue SyntaxError => e
347
- # A syntactically invalid source file surfaces when `require`d; report it
348
- # cleanly rather than dumping a backtrace.
349
- warn "mutineer: cannot load source: #{e.message}"
372
+ # Boot, source and require files report a SyntaxError as ProjectLoadError
373
+ # below. This covers a file loaded on any other path; report it cleanly
374
+ # rather than dumping a backtrace.
375
+ warn "mutineer: cannot load source: #{Redaction.text(e.message)}"
350
376
  exit 1
351
377
  rescue Mutineer::ParseError => e
352
- warn "mutineer: error reading: #{e.message}"
378
+ warn "mutineer: error reading: #{Redaction.text(e.message)}"
353
379
  exit 1
354
380
  rescue Mutineer::SmokeCheckError => e
355
381
  # The unmutated suite is not green under --test-command: a broken
356
382
  # environment, not weak tests. Runtime error (exit 1), not usage (exit 2).
357
- warn "mutineer: #{e.message}"
383
+ warn "mutineer: #{Redaction.text(e.message)}"
358
384
  exit 1
359
385
  rescue Mutineer::ConcurrentRunError => e
360
386
  # Another process owns a source file. Runtime error (exit 1), not a
361
387
  # backtrace: the working tree is still the other run's responsibility.
362
- warn "mutineer: #{e.message}"
388
+ warn "mutineer: #{Redaction.text(e.message)}"
363
389
  exit 1
364
390
  rescue Mutineer::CoverageFromError => e
365
- warn "mutineer: #{e.message}"
391
+ warn "mutineer: #{Redaction.text(e.message)}"
366
392
  exit 2
367
393
  rescue Mutineer::DaemonBootError => e
368
394
  # The daemon is gone for good, so the run ended rather than scoring the rest
369
395
  # against it. A deliberate stop deserves a message, not a raw backtrace.
396
+ warn "mutineer: #{Redaction.text(e.message)}"
397
+ exit 1
398
+ rescue Mutineer::ProjectLoadError => e
399
+ # A boot file, source or --require file failed to load. The message is
400
+ # already redacted; --verbose adds the backtrace and the cause chain.
370
401
  warn "mutineer: #{e.message}"
402
+ if config.verbose
403
+ (e.backtrace || []).each { |frame| warn "\t#{Redaction.text(frame)}" }
404
+ e.causes.each { |cause| warn "mutineer: caused by: #{cause}" }
405
+ else
406
+ warn "mutineer: re-run with --verbose for the backtrace and causes"
407
+ end
371
408
  exit 1
372
409
  end
373
410
 
@@ -383,8 +420,9 @@ module Mutineer
383
420
  validate_test_command!(config) if config.test_command
384
421
 
385
422
  validate_since!(config) if config.since
386
- preflight_output!(config.output) if config.output
423
+ preflight_output!(config.output, config) if config.output
387
424
  preflight_baseline!(config.baseline) if config.baseline
425
+ preflight_same_file!(config) if config.output && config.baseline && !config.dry_run
388
426
 
389
427
  # When --test is omitted, infer each source's test by convention. Autopair
390
428
  # also re-detects framework from inferred tests when --framework was not set.
@@ -636,13 +674,50 @@ module Mutineer
636
674
  exit 2
637
675
  end
638
676
 
639
- # Preflights an output path.
677
+ # #281: a report written over its own baseline turns a failed gate into the
678
+ # next baseline. Same check as the Action's guard (action.yml); the message
679
+ # is that guard's text adapted for the CLI, so keep the two in step. The
680
+ # output is expanded the way Reporter#report writes it, so `x/../b.json`
681
+ # with a missing `x/` still matches `b.json`. File.identical? is false when
682
+ # either file is missing, so a new output path never matches.
683
+ # Unlike the Action's guard, a dry run skips this check: it writes no report.
684
+ #
685
+ # @api private
686
+ # @param config [Mutineer::Config] run configuration (output and baseline set).
687
+ # @return [void]
688
+ def self.preflight_same_file!(config)
689
+ output = File.expand_path(config.output)
690
+ return unless File.identical?(output, config.baseline)
691
+
692
+ warn "mutineer: --output and #{config.origin(:baseline)} are the same file ('#{File.realpath(output)}'). " \
693
+ "A failing run would replace the baseline. Write the report to a separate path. " \
694
+ "Copy that file onto the baseline only when the run exits 0."
695
+ exit 2
696
+ end
697
+
698
+ # Preflights an output path. A missing parent is a usage error (exit 2),
699
+ # except the cache directory: the documented `--output .mutineer/run.json`
700
+ # must work on a fresh checkout. It is created here, before the run, so a
701
+ # failure to create it exits 2 up front. A later failed check can leave the
702
+ # empty cache directory behind (a real run creates it anyway). A dry run
703
+ # writes no report, so it creates nothing.
640
704
  #
641
705
  # @api private
642
706
  # @param path [String] output file path.
707
+ # @param config [Mutineer::Config] run configuration (for the cache directory).
643
708
  # @return [void]
644
- def self.preflight_output!(path)
709
+ def self.preflight_output!(path, config)
645
710
  dir = File.dirname(File.expand_path(path))
711
+ if !File.exist?(dir) && dir == File.expand_path(config.cache_dir, config.project_root)
712
+ return if config.dry_run
713
+
714
+ begin
715
+ FileUtils.mkdir_p(dir)
716
+ rescue SystemCallError => e
717
+ warn "mutineer: cannot write to #{path}: #{e.message}"
718
+ exit 2
719
+ end
720
+ end
646
721
  return if File.directory?(dir) && File.writable?(dir)
647
722
 
648
723
  reason = File.directory?(dir) ? "directory is not writable" : "no such directory"
@@ -683,18 +758,24 @@ module Mutineer
683
758
  baseline: delta ? delta.legacy_matches : 0 }
684
759
  reporter.report(out: $stdout, err: $stderr, threshold: config.threshold,
685
760
  format: config.format, output: config.output, baseline: delta,
686
- scoped: !config.since.nil?, legacy_id_matches: legacy_id_matches)
761
+ scoped: !config.since.nil?, legacy_id_matches: legacy_id_matches,
762
+ declined: extras.fetch(:declined, {}))
687
763
  warn_empty_run(config, extras) if aggregate.total.zero?
688
764
 
689
765
  # Warn (stderr, so it never pollutes json/html) that an external run's score
690
766
  # is not comparable to an in-process run: no coverage narrowing (uncovered
691
- # mutants count as survivors), and an infra failure that still starts the
692
- # suite is scored as a kill (exit 126/127 are scored error). Daemon coverage fallback warnings are emitted from the runner
693
- # only when the map is unavailable, not on every --daemon run.
767
+ # mutants count as survivors), and an infra failure that exits 1 can still
768
+ # score as a kill (#292): with the summary check on, when its output names a
769
+ # failing test; with it off (the clean run printed no Minitest or RSpec
770
+ # summary line), on any exit 1, a load crash included. Daemon coverage
771
+ # fallback warnings are emitted from the runner only when the map is
772
+ # unavailable, not on every --daemon run.
694
773
  if config.test_command
695
774
  warn "[mutineer] --test-command score is an upper bound, not comparable to an " \
696
- "in-process run: no coverage narrowing (uncovered mutants count as survivors) " \
697
- "and an infra failure is scored as a kill (except exit 126 and 127, scored error)."
775
+ "in-process run: no coverage narrowing (uncovered mutants count as survivors). " \
776
+ "Only exit 1 counts as a kill, or a SimpleCov gate exit whose summary shows a failing " \
777
+ "test (an RSpec --failure-exit-code other than 1 makes every kill an error). When the clean run printed a Minitest or RSpec summary line, " \
778
+ "Mutineer also reads it to tell a crash from a kill. See https://github.com/davidteren/mutineer/blob/main/docs/rails-setup.md#apps-on-ruby--34"
698
779
  end
699
780
 
700
781
  # Nudge toward the opt-in tier-2 operators (human report only: never
@@ -717,15 +798,21 @@ module Mutineer
717
798
  #
718
799
  # @param config [Mutineer::Config] run configuration.
719
800
  # @param extras [Hash] the run extras; `:unscoped_mutants` counts the mutants (run and
720
- # suppressed) before --since.
801
+ # suppressed) before --since, and `:declined` the candidates each operator did not mutate.
721
802
  # @return [void]
722
803
  def self.warn_empty_run(config, extras)
723
804
  # Mutants existed before --since narrowed them: the changes held none.
724
805
  if config.since && extras[:unscoped_mutants].to_i.positive?
725
806
  warn "mutineer: nothing to test in the changes since #{config.since}"
726
807
  elsif !config.allow_empty
727
- warn "mutineer: no mutants were generated. Check that the sources contain code the " \
728
- "operators mutate. The run exits 0, and #{BECOMES_ERROR_IN_2_0}. " \
808
+ declined = extras.fetch(:declined, {}).values.sum
809
+ cause = if declined.positive?
810
+ "#{declined} #{declined == 1 ? 'candidate was' : 'candidates were'} declined " \
811
+ "(--dry-run shows the count per operator)."
812
+ else
813
+ "Check that the sources contain code the operators mutate."
814
+ end
815
+ warn "mutineer: no mutants were generated. #{cause} The run exits 0, and #{BECOMES_ERROR_IN_2_0}. " \
729
816
  "Pass --allow-empty (or allow_empty: true) if an empty run is expected."
730
817
  end
731
818
  end
@@ -837,8 +924,25 @@ module Mutineer
837
924
  breakdown = per_operator.map { |op, n| "#{op}: #{n}" }.join(", ")
838
925
  summary = breakdown.empty? ? "" : "#{breakdown} — "
839
926
  puts "#{summary}#{total} mutations (dry run, not executed); " \
840
- "#{skipped} skipped (invalid); #{ignored} ignored (suppressed)"
927
+ "#{skipped} skipped (invalid); #{ignored} ignored (suppressed); " \
928
+ "#{declined_summary(extras[:declined], since: config.since)}"
841
929
  exit 0
842
930
  end
931
+
932
+ # Formats the dry run's declined count: the total, then each operator's
933
+ # count when the total is above zero. `--since` does not narrow the count,
934
+ # so under `--since` the text says so.
935
+ #
936
+ # @param declined [Hash{String => Integer}] operator name => declined count.
937
+ # @param since [String, nil] the `--since` ref, when set.
938
+ # @return [String] e.g. `2 declined (range: 2)`.
939
+ def self.declined_summary(declined, since:)
940
+ total = declined.values.sum
941
+ text = "#{total} declined"
942
+ text += " in the scanned files (not narrowed by --since)" if since
943
+ return text if total.zero?
944
+
945
+ "#{text} (#{declined.map { |op, n| "#{op}: #{n}" }.join(', ')})"
946
+ end
843
947
  end
844
948
  end
@@ -10,13 +10,19 @@ module Mutineer
10
10
  # mutant of a concern with such a block would error. {.forget} removes the
11
11
  # stored blocks that the source file defined, so the mutant's load stores
12
12
  # its own. {.replace} wraps the load and puts back any block the load did not
13
- # store again, such as one under an `unless defined?` guard. A class that
14
- # already includes the concern keeps what the original block defined in it:
15
- # ActiveSupport does not run the block there again.
16
- # Discovery marks the defs in these blocks (see {Subject#unplaceable?}).
13
+ # store again, such as one under an `unless defined?` guard.
14
+ #
15
+ # ActiveSupport does not run the block again in a class that already includes
16
+ # the concern, so that class keeps what the original block defined. For a def
17
+ # in the block, the mutant file also passes the mutated def to
18
+ # {.store_hook_def}, just before the `included` or `prepended` call, and
19
+ # {.place_hook_def} then loads only that def into each class that has the
20
+ # method (#297). Nothing else in the block runs again. Discovery decides which
21
+ # defs can be placed this way (see {Subject#unplaceable?}).
17
22
  #
18
23
  # Call it only in a forked child that loads the mutant. Without
19
- # ActiveSupport it does nothing.
24
+ # ActiveSupport, {.replace} and {.forget} do nothing; {.store_hook_def} and
25
+ # {.place_hook_def} work without it.
20
26
  #
21
27
  # Stdlib-only, so the app-side daemon can load it.
22
28
  module ConcernBlocks
@@ -40,6 +46,25 @@ module Mutineer
40
46
  end
41
47
  end
42
48
 
49
+ # Loads the mutant file at `path` over `source_file`, through {.replace}.
50
+ # The load assigns each of the file's constants a second time, so Ruby
51
+ # would warn twice per constant, per mutant (#364). Warnings are off for
52
+ # the load only, and back on before the tests run.
53
+ #
54
+ # @param source_file [String] the file the mutant replaces.
55
+ # @param path [String] the mutant file to load.
56
+ # @return [Object] what `load` returns.
57
+ def self.load_mutant(source_file, path)
58
+ replace(source_file) do
59
+ verbose, $VERBOSE = $VERBOSE, nil
60
+ begin
61
+ load path
62
+ ensure
63
+ $VERBOSE = verbose
64
+ end
65
+ end
66
+ end
67
+
43
68
  # Removes every stored `included` and `prepended` block that the source
44
69
  # file defined, from every concern. Blocks from other files stay.
45
70
  #
@@ -66,6 +91,163 @@ module Mutineer
66
91
  forgotten
67
92
  end
68
93
 
94
+ # Keeps the mutated hook-block def for {.place_hook_def}. The mutant file
95
+ # calls it in the concern's body, just before the hook call, so the block has
96
+ # the same constant scope as the hook block (#297).
97
+ #
98
+ # @yield the mutated def, run later with `class_eval` in each owner.
99
+ # @return [nil]
100
+ def self.store_hook_def(&block)
101
+ @hook_def = block
102
+ nil
103
+ end
104
+
105
+ # Takes the def {.store_hook_def} kept, clears it, and runs it with
106
+ # `class_eval` in each module whose own method came from the original def
107
+ # (see {.owners}), so that module gets the mutated method and nothing else in
108
+ # the block runs again. Each owner keeps the method's visibility. A class
109
+ # that includes the concern later gets the mutant from the stored block.
110
+ #
111
+ # @param source_file [String] the file the mutant replaces.
112
+ # @param line [Integer] the original def's first line.
113
+ # @param name [Symbol] the method name.
114
+ # @param singleton [Boolean] true for a class method.
115
+ # @raise [RuntimeError] when no def was kept (the mutant file did not reach
116
+ # its hook call), or when a module keeps the original under another name
117
+ # (see {.aliases}) or in a live method handle; the child then scores the
118
+ # mutant `error`.
119
+ # @return [Integer] how many owners got the mutated def.
120
+ def self.place_hook_def(source_file:, line:, name:, singleton:)
121
+ block = @hook_def
122
+ @hook_def = nil
123
+ where = "mutineer: could not place the mutant of #{name} (#{source_file}:#{line})"
124
+ unless block
125
+ raise "#{where}: the mutant file did not reach its included or prepended call. " \
126
+ "This is a mutineer bug; please report it."
127
+ end
128
+
129
+ # Check before owner and alias lookup create temporary UnboundMethods.
130
+ if retained_hook_def?(source_file: source_file, line: line, name: name)
131
+ raise "#{where}: the original is retained in a Method or UnboundMethod object, " \
132
+ "so the mutant scores error."
133
+ end
134
+
135
+ # ponytail: one ObjectSpace walk per mutant (about 11 ms with Rails loaded);
136
+ # index modules by method name if a large app makes it slow.
137
+ modules = ObjectSpace.each_object(Module).to_a
138
+ found = owners(modules, source_file: source_file, line: line, name: name, singleton: singleton)
139
+ mod, other = aliases(modules, source_file: source_file, line: line, name: name, singleton: singleton).first
140
+ if mod
141
+ raise "#{where}: #{mod.inspect}#{singleton ? "." : "#"}#{other} is an alias of it and keeps the " \
142
+ "original method, so the mutant scores error."
143
+ end
144
+
145
+ found.each do |owner|
146
+ target = singleton ? owner.singleton_class : owner
147
+ visibility = if target.private_method_defined?(name, false) then :private
148
+ elsif target.protected_method_defined?(name, false) then :protected
149
+ end
150
+ owner.class_eval(&block) # a `def` in the block defines public
151
+ target.send(visibility, name) if visibility
152
+ end
153
+ found.size
154
+ end
155
+
156
+ # Each module whose own method `name` (its singleton class's, for a class
157
+ # method) has the original def's file and line: every place the original
158
+ # block defined it. A subclass that overrides the method, or a class that
159
+ # only inherits it, is not one.
160
+ #
161
+ # @param modules [Array<Module>] every module, including singleton classes
162
+ # into which a concern can be included.
163
+ # @param source_file [String] the file the mutant replaces.
164
+ # @param line [Integer] the original def's first line.
165
+ # @param name [Symbol] the method name.
166
+ # @param singleton [Boolean] true for a class method.
167
+ # @return [Array<Module>]
168
+ def self.owners(modules, source_file:, line:, name:, singleton:)
169
+ path = real_path(source_file)
170
+ modules.select { |mod| own_method_at?(singleton ? mod.singleton_class : mod, name, path, line) }
171
+ end
172
+
173
+ # Each other name any module has for the original def: an alias made
174
+ # outside the block. Check independently of {.owners}: a wrapper can replace
175
+ # the original name while its alias keeps the original body, so the mutant
176
+ # could falsely survive even when no current-name owner remains.
177
+ #
178
+ # @param modules [Array<Module>] every module, including singleton classes.
179
+ # @param source_file [String] the file the mutant replaces.
180
+ # @param line [Integer] the original def's first line.
181
+ # @param name [Symbol] the method name.
182
+ # @param singleton [Boolean] true for a class method.
183
+ # @return [Array<Array(Module, Symbol)>] each module and its alias name.
184
+ def self.aliases(modules, source_file:, line:, name:, singleton:)
185
+ path = real_path(source_file)
186
+ modules.flat_map do |mod|
187
+ target = singleton ? mod.singleton_class : mod
188
+ (target.instance_methods(false) + target.private_instance_methods(false)).filter_map do |other|
189
+ [mod, other] if other != name && own_method_at?(target, other, path, line, original_name: name)
190
+ end
191
+ end
192
+ end
193
+
194
+ # True when the module's own method `name` starts at this file and line.
195
+ # A prepended method can hide it from `instance_method`, so follow `super`
196
+ # until the lookup reaches the method whose owner is the module itself.
197
+ #
198
+ # @param target [Module] the module or singleton class to read.
199
+ # @param name [Symbol] the method name.
200
+ # @param path [String] the source file's real path.
201
+ # @param line [Integer] the def's first line.
202
+ # @param original_name [Symbol] the name the original definition used;
203
+ # distinguishes an alias from another definition on the same line.
204
+ # @return [Boolean]
205
+ def self.own_method_at?(target, name, path, line, original_name: name)
206
+ return false unless target.method_defined?(name, false) || target.private_method_defined?(name, false)
207
+
208
+ method = target.instance_method(name)
209
+ method = method.super_method while method && !method.owner.equal?(target)
210
+ return false unless method
211
+
212
+ file, def_line = method.source_location
213
+ method.original_name == original_name && def_line == line && !file.nil? && real_path(file) == path
214
+ end
215
+
216
+ # True when a live Method or UnboundMethod keeps the original definition.
217
+ # A wrapper can call that handle after the named method was replaced, so
218
+ # loading another def cannot make the wrapper test the mutant. A matching
219
+ # but unreachable reflection result is harmless: collect it, then check
220
+ # again. Most mutants have no matching handle and need no explicit GC.
221
+ #
222
+ # @param source_file [String] the file the mutant replaces.
223
+ # @param line [Integer] the original def's first line.
224
+ # @param name [Symbol] the original method name.
225
+ # @return [Boolean]
226
+ def self.retained_hook_def?(source_file:, line:, name:)
227
+ path = real_path(source_file)
228
+ return false unless method_handle_at?(path, line, name)
229
+
230
+ GC.start
231
+ method_handle_at?(path, line, name)
232
+ end
233
+
234
+ # True when the heap contains a handle for this original definition. Return
235
+ # only a boolean, so the first check does not itself retain a dead handle
236
+ # across the GC in {.retained_hook_def?}.
237
+ #
238
+ # @param path [String] the source file's real path.
239
+ # @param line [Integer] the original def's first line.
240
+ # @param name [Symbol] the original method name.
241
+ # @return [Boolean]
242
+ def self.method_handle_at?(path, line, name)
243
+ [Method, UnboundMethod].any? do |kind|
244
+ ObjectSpace.each_object(kind).any? do |method|
245
+ file, def_line = method.source_location
246
+ method.original_name == name && def_line == line && !file.nil? && real_path(file) == path
247
+ end
248
+ end
249
+ end
250
+
69
251
  # The file's real path, so a symlinked or relative path matches the path
70
252
  # Ruby recorded when it loaded the file.
71
253
  #
@@ -63,6 +63,7 @@ module Mutineer
63
63
  flag: "--capture-timeout"),
64
64
  ConfigOption.new(field: :cache_dir, type: :string, yaml_key: "cache_dir", flag: "--cache-dir"),
65
65
  ConfigOption.new(field: :allow_empty, type: :bool, yaml_key: "allow_empty", flag: "--allow-empty"),
66
+ ConfigOption.new(field: :shared_databases, type: :string_list, yaml_key: "shared_databases"),
66
67
  ConfigOption.new(field: :coverage_from, type: :string, flag: "--coverage-from"),
67
68
  ConfigOption.new(field: :format, type: :enum, flag: "--format", values: %w[human json html]),
68
69
  ConfigOption.new(field: :strategy, type: :enum, flag: "--strategy", values: %w[reload redefine],
@@ -84,6 +85,9 @@ module Mutineer
84
85
  # `matrix` (--matrix) runs every covering test for each mutant and reports
85
86
  # which tests kill it (see KillMatrix); it never changes a verdict.
86
87
  #
88
+ # `shared_databases` (file only) names test database configs that parallel
89
+ # `--daemon` workers may share; see DaemonBackend.worker_count_for.
90
+ #
87
91
  # Boot mode adds: boot (a file to require ONCE in the parent so the app env,
88
92
  # e.g. Rails, is booted before forking; sources are then NOT manually required)
89
93
  # and rails (sugar: defaults boot to config/environment, prefers redefine without
@@ -97,6 +101,7 @@ module Mutineer
97
101
  # :daemon_timeout stays programmatic (set by tests/Runner; no flag yet).
98
102
  :baseline, :baseline_epsilon, :fail_fast, :test_command,
99
103
  :daemon, :daemon_timeout, :timeout, :capture_timeout, :matrix, :allow_empty, :coverage_from,
104
+ :shared_databases,
100
105
  keyword_init: true
101
106
  ) do
102
107
  # Config file name.
@@ -133,6 +138,7 @@ module Mutineer
133
138
  self.daemon = false if daemon.nil?
134
139
  self.matrix = false if matrix.nil?
135
140
  self.allow_empty = false if allow_empty.nil?
141
+ self.shared_databases ||= []
136
142
  end
137
143
 
138
144
  # True when the user wrote `key`, on the command line or in the config