mutineer 1.8.1 → 1.9.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 (52) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +733 -0
  3. data/README.md +85 -50
  4. data/lib/mutineer/changed_lines.rb +2 -1
  5. data/lib/mutineer/child_cause.rb +149 -0
  6. data/lib/mutineer/child_stdout.rb +12 -1
  7. data/lib/mutineer/cli.rb +540 -59
  8. data/lib/mutineer/command_redact.rb +38 -0
  9. data/lib/mutineer/concern_blocks.rb +95 -24
  10. data/lib/mutineer/config.rb +112 -6
  11. data/lib/mutineer/coverage_map.rb +1345 -156
  12. data/lib/mutineer/daemon_backend.rb +41 -18
  13. data/lib/mutineer/daemon_client.rb +104 -21
  14. data/lib/mutineer/daemon_server.rb +85 -14
  15. data/lib/mutineer/database_urls.rb +189 -0
  16. data/lib/mutineer/external_backend.rb +93 -6
  17. data/lib/mutineer/fs_path.rb +125 -0
  18. data/lib/mutineer/isolation.rb +380 -25
  19. data/lib/mutineer/job_plan.rb +352 -41
  20. data/lib/mutineer/minitest_integration/file_order.rb +56 -0
  21. data/lib/mutineer/minitest_integration/in_test_database_error.rb +243 -19
  22. data/lib/mutineer/minitest_integration.rb +26 -58
  23. data/lib/mutineer/mutant_id.rb +4 -1
  24. data/lib/mutineer/mutation.rb +10 -4
  25. data/lib/mutineer/mutator_registry.rb +6 -3
  26. data/lib/mutineer/mutators/collection_method.rb +195 -6
  27. data/lib/mutineer/mutators/literal_mutation.rb +33 -3
  28. data/lib/mutineer/mutators/range_literal.rb +78 -29
  29. data/lib/mutineer/mutators/rescue_body.rb +126 -0
  30. data/lib/mutineer/mutators/return_nil.rb +23 -6
  31. data/lib/mutineer/output_filter.rb +451 -0
  32. data/lib/mutineer/pairing.rb +463 -31
  33. data/lib/mutineer/parser.rb +53 -0
  34. data/lib/mutineer/project_path.rb +15 -8
  35. data/lib/mutineer/rails_worker_db.rb +366 -6
  36. data/lib/mutineer/reach_probe.rb +229 -0
  37. data/lib/mutineer/redaction.rb +301 -41
  38. data/lib/mutineer/reload_guards.rb +985 -0
  39. data/lib/mutineer/reporter.rb +467 -58
  40. data/lib/mutineer/result.rb +6 -7
  41. data/lib/mutineer/run_seed.rb +16 -0
  42. data/lib/mutineer/runner.rb +194 -55
  43. data/lib/mutineer/source_bytes.rb +187 -0
  44. data/lib/mutineer/statement_lines.rb +108 -14
  45. data/lib/mutineer/test_runners/rspec.rb +118 -10
  46. data/lib/mutineer/test_runners/rspec_seed.rb +151 -0
  47. data/lib/mutineer/test_runners.rb +3 -2
  48. data/lib/mutineer/triage.rb +55 -10
  49. data/lib/mutineer/version.rb +1 -1
  50. data/lib/mutineer.rb +1 -0
  51. data/skills/mutineer/SKILL.md +12 -4
  52. metadata +13 -1
data/lib/mutineer/cli.rb CHANGED
@@ -19,6 +19,8 @@ require_relative "mutator_registry"
19
19
  require_relative "triage"
20
20
  require_relative "init"
21
21
  require_relative "redaction"
22
+ require_relative "database_urls"
23
+ require_relative "output_filter"
22
24
 
23
25
  module Mutineer
24
26
  # Command-line entry point. `start` is the single public method called by
@@ -31,6 +33,10 @@ module Mutineer
31
33
  # 2 usage / flag error (unknown subcommand, invalid flag, unknown operator,
32
34
  # out-of-range threshold)
33
35
  class CLI
36
+ # How to run a source that pairing skipped.
37
+ # The reporter keeps its own copy of the longer hint.
38
+ UNPAIRED_RUN_HINT = "Add a test at the conventional path, or run those sources in a separate command with --test."
39
+
34
40
  # Command-line usage banner.
35
41
  BANNER = <<~USAGE
36
42
  Usage: mutineer [options] <command> [args]
@@ -41,18 +47,29 @@ module Mutineer
41
47
  run --dry-run [options] <source...> Print candidate mutations only
42
48
  triage REPORT.json --reason TEXT
43
49
  (--id ID ... | --all) Print ignore: entries for
44
- survivors. Does not edit files.
50
+ survivors and for each copy
51
+ dropped as a repeat of one.
52
+ Does not edit files.
45
53
  migrate [options] <source...> Rewrite old ignore ids in
46
- .mutineer.yml. --dry-run prints
47
- each change and writes nothing
54
+ .mutineer.yml. --dry-run lists
55
+ each change and every entry
56
+ that matches no mutant, writes
57
+ nothing, and exits 1 for a miss.
58
+ run warns and still exits 0
48
59
  init [--rails] [--force] Write .mutineer.yml and print
49
60
  the first run command.
50
61
  --force replaces an existing file.
62
+ config KEY [run options] Print the cache_dir or baseline
63
+ that run would use. Writes nothing
51
64
 
52
65
  Run options:
53
- --test FILE Test file covering the sources (one per flag; repeat it).
66
+ --test PATH Test file, directory or quoted glob (repeat for more).
54
67
  Omit to pair each source with its test by convention
55
- (not under --dry-run)
68
+ and any tests: map in .mutineer.yml (not under
69
+ --dry-run). A source at app/<dir>/concerns/ with no
70
+ test there also pairs with a split test at its
71
+ namespace path.
72
+ --test replaces pairing and the map
56
73
  --operators LIST Comma-separated operator names (default: Tier 1 set)
57
74
  --threshold FLOAT Fail (exit 1) when score < FLOAT (default: 0 = off)
58
75
  --baseline FILE Fail (exit 1) on NEW survivors / score drop vs a prior
@@ -69,21 +86,27 @@ module Mutineer
69
86
  not with --daemon or --test-command); a mutant over it
70
87
  is a timeout, excluded from the score
71
88
  --capture-timeout SECONDS Time limit for each coverage-capture subprocess
72
- and the clean check (default: 120; not with --test-command)
89
+ and the clean check (default: 120; not with --test-command);
90
+ the combined clean check gets the larger of this and
91
+ 1.5x its files' summed capture time, rounded up
73
92
  --cache-dir DIR Directory for the coverage cache (default: .mutineer;
74
93
  not with --test-command)
75
94
  --coverage-from FILE Reuse the coverage.json of a --rails/--boot capture over
76
95
  these sources or more; runs alone only the tests that
77
96
  cover these sources
78
97
  --framework NAME minitest or rspec (default: auto-detect from --test names)
79
- --boot FILE Require FILE once in the parent to boot the app env, then
80
- fork per mutant (Rails apps; needs a test, given or found by convention)
98
+ --boot FILE Require FILE once in the parent before the sources, then
99
+ fork per mutant (an app entry point or a gem's lib/<name>.rb;
100
+ needs a test, given or found by convention)
81
101
  --rails Boot config/environment; without --daemon, defaults to
82
102
  redefine and serial execution
83
103
  --test-command CMD Run the target suite in the app's own runtime as a
84
104
  subprocess (for apps on Ruby < 3.4). CMD must contain
85
105
  %{files}. Scrubs Mutineer Ruby PATH pins; set RAILS_ENV
86
- on the mutineer command (not as KEY=val inside CMD)
106
+ on the mutineer command (not as KEY=val inside CMD).
107
+ CMD must run tests in a fixed order: put SEED=1
108
+ before the mutineer command for Minitest, or add
109
+ --order defined to an RSpec CMD
87
110
  --daemon Boot the app ONCE in a persistent daemon and fork per
88
111
  mutant, with per-worker DB isolation so --jobs N is safe
89
112
  under Rails (needs --rails/--boot; not with --test-command).
@@ -116,6 +139,15 @@ module Mutineer
116
139
  # @param argv [Array<String>] raw command-line arguments.
117
140
  # @return [void]
118
141
  def self.start(argv)
142
+ # Reports and warnings name paths. Under an ASCII locale the stdio
143
+ # encoding is US-ASCII, so a non-ASCII path cannot be written.
144
+ # Binary mode writes each string's own bytes: UTF-8 text stays UTF-8,
145
+ # and a path that is not valid UTF-8 does not raise on the way out (#346).
146
+ [$stdout, $stderr].each(&:binmode)
147
+
148
+ # Set before any exit: the method's ensure reads it, and exit runs ensure.
149
+ filter_owned = false
150
+ previous_urls = nil
119
151
  if argv.first == "triage"
120
152
  exit Triage.run(argv[1..])
121
153
  end
@@ -151,7 +183,7 @@ module Mutineer
151
183
  # A typed "no" must beat a .mutineer.yml `since:` key: the key is present
152
184
  # with a nil value, and nil is a value.
153
185
  o.on("--no-since") { opts[:since] = nil }
154
- o.on("--test FILE") { |v| (opts[:tests] ||= []) << v }
186
+ o.on("--test PATH") { |v| (opts[:tests] ||= []) << v }
155
187
  o.on("--operators LIST") do |v|
156
188
  opts[:operators] = Config.parse(:operators, v.split(",").map(&:strip))
157
189
  end
@@ -213,17 +245,39 @@ module Mutineer
213
245
  case argv.first
214
246
  when "run"
215
247
  warn_config_root_mismatch(file_path, config.project_root) if file_path
248
+ # Matrix conflicts first — same order as validate! — so a --matrix
249
+ # clash is not hidden by a shape or expansion error (#407 OCR).
250
+ # Expand --test before the guard. The guard reads config.tests.
251
+ # migrate and config do not call this (#380).
252
+ # A bad --test-command is reported next, not hidden by a --test error.
253
+ validate_matrix!(config) if config.matrix
254
+ validate_test_command_shape!(config) if config.test_command
255
+ expand_tests!(config) if config.explicit?(:tests)
216
256
  tests_as_sources = argv[1..].select do |arg|
217
257
  Pairing.test_given_as_source?(arg, project_root: config.project_root, tests: config.tests)
218
258
  end
219
259
  if config.explicit?(:tests) && tests_as_sources.any?
220
260
  warn "mutineer: #{tests_as_sources.join(', ')} looks like a test file, not a source. " \
221
- "--test takes one file; repeat it for each test file (--test a_test.rb --test b_test.rb)"
261
+ "A shell expands an unquoted glob into many files. " \
262
+ "Quote the glob (--test 'test/**/*_test.rb'), pass the directory (--test test), " \
263
+ "or repeat --test for each file"
222
264
  exit 2
223
265
  end
224
266
  # A directory source expands to its **/*.rb files; a file inside the
225
267
  # project becomes its root-relative path (#104). Test inference (when --test is omitted) happens in validate!.
226
268
  config.sources = Pairing.expand_sources(argv[1..], project_root: config.project_root)
269
+ # Direct writes from the app, a fork, or a subprocess inherit these
270
+ # pipes (#341). Dotenv files are merged with any URLs the caller
271
+ # already set, and that list is restored when start returns.
272
+ previous_urls = Redaction.extra_urls
273
+ Redaction.extra_urls = (previous_urls + DatabaseUrls.from_files(config.project_root)).uniq
274
+ case OutputFilter.install
275
+ when :started
276
+ filter_owned = true
277
+ when :failed
278
+ warn "mutineer: cannot redirect stdout and stderr, so a database password would be printed"
279
+ exit 1
280
+ end
227
281
  run(config)
228
282
  when "migrate"
229
283
  warn_config_root_mismatch(file_path, config.project_root) if file_path
@@ -237,6 +291,8 @@ module Mutineer
237
291
  end
238
292
  config.sources = Pairing.expand_sources(argv[1..], project_root: config.project_root)
239
293
  migrate(config, file_path)
294
+ when "config"
295
+ print_setting(config, argv[1])
240
296
  else
241
297
  warn "mutineer: unknown command '#{argv.first}'"
242
298
  exit 2
@@ -253,6 +309,38 @@ module Mutineer
253
309
  end
254
310
  warn "mutineer: #{Redaction.text(details)}"
255
311
  exit 1
312
+ ensure
313
+ # Flush after the report is printed and before the process exits, while
314
+ # extra_urls is still set. Then drop them so a later in-process call
315
+ # does not keep this project's passwords.
316
+ OutputFilter.uninstall if filter_owned
317
+ Redaction.extra_urls = previous_urls unless previous_urls.nil?
318
+ end
319
+
320
+ # Settings `mutineer config` prints. The GitHub Action asks for these
321
+ # (#394), so it does not copy the CLI's precedence and flag rules.
322
+ PRINTABLE_SETTINGS = %w[cache_dir baseline].freeze
323
+
324
+ # Prints the value `run` would use for one setting, resolved from the same
325
+ # flags and .mutineer.yml, and exits 0. An unset value prints nothing.
326
+ # Read-only: it creates no folder and writes no file. Other arguments, such
327
+ # as sources, are ignored, so a caller can pass a run's arguments as they are.
328
+ # An unknown or missing key is a usage error (exit 2).
329
+ #
330
+ # @api private
331
+ # @param config [Mutineer::Config] the resolved configuration.
332
+ # @param key [String, nil] the setting name.
333
+ # @return [void]
334
+ def self.print_setting(config, key)
335
+ unless PRINTABLE_SETTINGS.include?(key)
336
+ warn "mutineer: config needs one of #{PRINTABLE_SETTINGS.join(', ')}#{" (got '#{key}')" if key}"
337
+ exit 2
338
+ end
339
+ value = config[key.to_sym]
340
+ # Exactly one newline, even after a value that ends in one (puts would
341
+ # add none), so a caller can strip it and keep the value whole.
342
+ print value, "\n" unless value.nil?
343
+ exit 0
256
344
  end
257
345
 
258
346
  # Rewrites old-format ids in the loaded `.mutineer.yml` `ignore:` list.
@@ -398,7 +486,10 @@ module Mutineer
398
486
  rescue Mutineer::ProjectLoadError => e
399
487
  # A boot file, source or --require file failed to load. The message is
400
488
  # already redacted; --verbose adds the backtrace and the cause chain.
489
+ # A source NameError with no boot file adds one line that points at
490
+ # boot: (#376). The hint is static text, so it needs no redaction.
401
491
  warn "mutineer: #{e.message}"
492
+ warn "mutineer: #{e.hint}" if e.hint
402
493
  if config.verbose
403
494
  (e.backtrace || []).each { |frame| warn "\t#{Redaction.text(frame)}" }
404
495
  e.causes.each { |cause| warn "mutineer: caused by: #{cause}" }
@@ -420,9 +511,21 @@ module Mutineer
420
511
  validate_test_command!(config) if config.test_command
421
512
 
422
513
  validate_since!(config) if config.since
423
- preflight_output!(config.output, config) if config.output
514
+ # Non-JSON dry runs ignore --output (warn_unused_dry_run_settings); skip
515
+ # the path check so a missing parent does not exit 2 before that warning.
516
+ if config.output && (!config.dry_run || config.format == "json")
517
+ preflight_output!(config.output, config)
518
+ end
424
519
  preflight_baseline!(config.baseline) if config.baseline
425
- preflight_same_file!(config) if config.output && config.baseline && !config.dry_run
520
+ # Human dry runs write nothing; JSON dry runs write --output (#362), so
521
+ # they need the same-file guard that blocks overwriting a baseline (#281).
522
+ if config.output && config.baseline && (!config.dry_run || config.format == "json")
523
+ preflight_same_file!(config)
524
+ end
525
+
526
+ # Resolve / warn for the tests: map before autopair. Dry-run skips
527
+ # autopair but still checks unmatched patterns (#382 R5, R12).
528
+ prepare_test_map!(config)
426
529
 
427
530
  # When --test is omitted, infer each source's test by convention. Autopair
428
531
  # also re-detects framework from inferred tests when --framework was not set.
@@ -433,6 +536,7 @@ module Mutineer
433
536
  # validated before discovery).
434
537
  validate_daemon!(config) if config.daemon
435
538
  warn_unused_coverage_from(config)
539
+ warn_unused_dry_run_settings(config)
436
540
 
437
541
  # Boot mode needs at least one --test file (nothing to select from otherwise).
438
542
  if config.boot && config.tests.empty?
@@ -454,14 +558,7 @@ module Mutineer
454
558
  # @param config [Mutineer::Config] run configuration.
455
559
  # @return [void]
456
560
  def self.validate_test_command!(config)
457
- if config.test_command.strip.empty?
458
- warn "mutineer: --test-command must not be empty"
459
- exit 2
460
- end
461
- unless config.test_command.include?("%{files}")
462
- warn "mutineer: --test-command must contain %{files} (where the --test paths are substituted)"
463
- exit 2
464
- end
561
+ validate_test_command_shape!(config)
465
562
  if config.boot
466
563
  warn "mutineer: --test-command cannot be combined with --boot/--rails " \
467
564
  "(the external subprocess boots the app itself)"
@@ -479,6 +576,23 @@ module Mutineer
479
576
  config.jobs = 1
480
577
  end
481
578
 
579
+ # The --test-command text must not be blank and must contain %{files}.
580
+ # It prints nothing when the text is valid, so a second call is safe.
581
+ #
582
+ # @api private
583
+ # @param config [Mutineer::Config] run configuration.
584
+ # @return [void]
585
+ def self.validate_test_command_shape!(config)
586
+ if config.test_command.strip.empty?
587
+ warn "mutineer: --test-command must not be empty"
588
+ exit 2
589
+ end
590
+ return if config.test_command.include?("%{files}")
591
+
592
+ warn "mutineer: --test-command must contain %{files} (where the --test paths are substituted)"
593
+ exit 2
594
+ end
595
+
482
596
  # --daemon selects the persistent-daemon backend (boot once, fork per mutant,
483
597
  # per-worker DB isolation on SQLite, Postgres, and MySQL). Usage errors exit 2:
484
598
  # cannot combine with --test-command; requires --rails or --boot; minitest only;
@@ -533,6 +647,25 @@ module Mutineer
533
647
  warn_unused_settings(config, mode, %i[coverage_from]) if mode
534
648
  end
535
649
 
650
+ # `--dry-run` prints a candidate list; `--format html` never renders one,
651
+ # and `--output` only writes when `--format json` builds that list (#362).
652
+ #
653
+ # @api private
654
+ # @param config [Mutineer::Config] run configuration.
655
+ # @return [void]
656
+ def self.warn_unused_dry_run_settings(config)
657
+ return unless config.dry_run
658
+
659
+ if config.explicit?(:format) && config.format == "html"
660
+ warn "[mutineer] --format html has no effect with --dry-run " \
661
+ "(it applies to a completed run; use --format json for candidates); ignoring it."
662
+ end
663
+ return unless config.explicit?(:output) && config.format != "json"
664
+
665
+ warn "[mutineer] #{config.origin(:output)} has no effect with --dry-run " \
666
+ "(it applies to --format json dry runs); ignoring it."
667
+ end
668
+
536
669
  # A backend that never reads a setting the user set would silently do
537
670
  # nothing with it, so say so. `--test-command` builds no coverage map and
538
671
  # has its own runtime, so it reads none of {UNUSED_SETTING_SCOPE}; the
@@ -626,14 +759,154 @@ module Mutineer
626
759
  exit 2
627
760
  end
628
761
 
762
+ # Pairs each source with its conventional tests and any matching
763
+ # `tests:` map entries. A source with neither is unpaired. Source
764
+ # order is kept. This does not change `config`.
765
+ #
766
+ # @api private
767
+ # @param config [Mutineer::Config] run configuration.
768
+ # @param resolved [Hash, nil] output of {Pairing.resolve_test_map}, or nil.
769
+ # @return [Array(Array<Array(String, Array<String>)>, Array<String>)]
770
+ # paired rows of [source, tests], then unpaired paths.
771
+ def self.convention_pairs(config, resolved: nil)
772
+ resolved ||= @resolved_test_map
773
+ paired = []
774
+ unpaired = []
775
+ config.sources.each do |source|
776
+ convention = Pairing.infer_tests(source, project_root: config.project_root, prefer: config.framework)
777
+ mapped = resolved ? Pairing.mapped_tests_for(source, resolved) : []
778
+ tests = (convention + mapped).uniq
779
+ if tests.empty?
780
+ unpaired << source
781
+ else
782
+ paired << [source, tests]
783
+ end
784
+ end
785
+ [paired, unpaired]
786
+ end
787
+
788
+ # Expand each typed --test value before a run. A blank value exits 2.
789
+ # With --test-command, a directory stays as typed. A glob still expands.
790
+ # A directory or glob with no test file exits 2. Each expanded value
791
+ # prints one count on stderr. Duplicate files keep the first spelling.
792
+ # The framework is detected again from the expanded list, unless the
793
+ # user set it.
794
+ #
795
+ # @api private
796
+ # @param config [Mutineer::Config] run configuration.
797
+ # @return [void]
798
+ def self.expand_tests!(config)
799
+ root = config.project_root
800
+ seen = {}
801
+ tests = []
802
+ counts = []
803
+ errors = []
804
+
805
+ Array(config.tests).each do |value|
806
+ kind = Pairing.classify_test_value(value, project_root: root)
807
+ if kind == :blank
808
+ errors << %(mutineer: --test must name a file, a directory or a glob, not blank (got: "#{value}"))
809
+ next
810
+ end
811
+ if kind == :directory && config.test_command
812
+ store_test_path(tests, seen, root, value)
813
+ next
814
+ end
815
+
816
+ paths = Pairing.expand_test(value, project_root: root)
817
+ if paths.empty?
818
+ errors << no_test_match_message(value, kind)
819
+ next
820
+ end
821
+ if kind == :directory || kind == :glob
822
+ noun = paths.size == 1 ? "file" : "files"
823
+ counts << "[mutineer] --test #{value}: #{paths.size} test #{noun}"
824
+ end
825
+ paths.each { |path| store_test_path(tests, seen, root, path) }
826
+ end
827
+
828
+ unless errors.empty?
829
+ errors.each { |msg| warn msg }
830
+ exit 2
831
+ end
832
+
833
+ counts.each { |line| warn line }
834
+ config.tests = tests
835
+ config.framework = Config.detect_framework(config.tests) unless config.explicit?(:framework)
836
+ end
837
+
838
+ # Usage text when a directory or glob matched no test file.
839
+ #
840
+ # @api private
841
+ # @param value [String] the --test value, as typed.
842
+ # @param kind [Symbol] :directory or :glob.
843
+ # @return [String]
844
+ def self.no_test_match_message(value, kind)
845
+ message = "mutineer: --test #{value} matched no test files"
846
+ return message unless kind == :directory
847
+
848
+ "#{message}. A directory gives the files under it named *_test.rb, *_spec.rb or test_*.rb."
849
+ end
850
+
851
+ # Keep the first spelling of one absolute test path.
852
+ #
853
+ # @api private
854
+ # @param tests [Array<String>] paths kept so far.
855
+ # @param seen [Hash{String => true}] absolute paths already kept.
856
+ # @param root [String] project root.
857
+ # @param path [String] path as it should be stored.
858
+ # @return [void]
859
+ def self.store_test_path(tests, seen, root, path)
860
+ key = File.expand_path(path, root)
861
+ return if seen[key]
862
+
863
+ seen[key] = true
864
+ tests << path
865
+ end
866
+
867
+ # Warn or resolve the optional `tests:` map before pairing. With `--test`
868
+ # and a non-empty map, print one line that the map has no effect (R9) and
869
+ # resolve nothing. Otherwise expand every pattern; an unmatched pattern is
870
+ # exit 2 (R5). The resolved map is stashed for {autopair!} and
871
+ # {convention_pairs}. Dry-run still runs this check (R12) even though it
872
+ # skips autopair.
873
+ #
874
+ # @api private
875
+ # @param config [Mutineer::Config] run configuration.
876
+ # @return [void]
877
+ def self.prepare_test_map!(config)
878
+ @resolved_test_map = nil
879
+ return if config.test_map.empty?
880
+
881
+ if config.explicit?(:tests)
882
+ warn "[mutineer] #{config.origin(:test_map)} has no effect when --test is given"
883
+ return
884
+ end
885
+
886
+ resolved = Pairing.resolve_test_map(config.test_map, project_root: config.project_root)
887
+ unless resolved[:unmatched].empty?
888
+ miss = resolved[:unmatched].first
889
+ # Prefer the loaded path: find_file can pick a home or parent config,
890
+ # and basename-only text hides which file failed the map check.
891
+ label = Config.find_file || CONFIG_FILE
892
+ warn "mutineer: #{label}: tests entry #{miss[:entry]}: " \
893
+ "#{miss[:key]} pattern #{miss[:pattern].inspect} matched no file"
894
+ exit 2
895
+ end
896
+ @resolved_test_map = resolved
897
+ end
898
+
629
899
  # Auto-pair sources to tests by path convention when no --test was given
630
- # (explicit --test wins). Each source with at least one inferred test on
631
- # disk joins the run; a source with none is dropped with a one-line stderr
632
- # warning and the run continues with the rest. Split files for one source
633
- # are all kept (#87). If every source is dropped: in boot mode the
634
- # dedicated --boot/--rails-requires-test check reports it; otherwise exit 2
635
- # with a usage message. The framework is re-detected from the inferred set
636
- # unless it was set explicitly (a spec-only project loads/reports as rspec).
900
+ # (explicit --test wins). Each source keeps its paired tests, then any
901
+ # mapped tests from the resolved `tests:` map (R6, R10). A source with
902
+ # neither is dropped with a one-line stderr warning and stored on
903
+ # `config.unpaired_sources`. The run continues with the rest. Split files
904
+ # for one source are all kept (#87). If every source is dropped: in boot
905
+ # mode the dedicated --boot/--rails-requires-test check reports it;
906
+ # otherwise exit 2 with a usage message. The framework is re-detected from
907
+ # the inferred set unless it was set explicitly (a spec-only project
908
+ # loads/reports as rspec). An explicit test list leaves `unpaired_sources`
909
+ # empty and does not drop sources.
637
910
  #
638
911
  # @api private
639
912
  # @param config [Mutineer::Config] run configuration.
@@ -641,13 +914,17 @@ module Mutineer
641
914
  def self.autopair!(config)
642
915
  return unless config.tests.empty?
643
916
 
644
- paired = config.sources.filter_map do |s|
645
- tests = Pairing.infer_tests(s, project_root: config.project_root, prefer: config.framework)
646
- [s, tests] unless tests.empty?
917
+ resolved = @resolved_test_map
918
+ @resolved_test_map = nil
919
+ if resolved.nil? && !config.test_map.empty? && !config.explicit?(:tests)
920
+ resolved = Pairing.resolve_test_map(config.test_map, project_root: config.project_root)
647
921
  end
648
- (config.sources - paired.map(&:first)).each do |s|
649
- warn "[mutineer] no test found by convention for #{s}; skipping"
922
+
923
+ paired, unpaired = convention_pairs(config, resolved: resolved)
924
+ unpaired.each do |source|
925
+ warn "[mutineer] no test found by convention for #{source}; skipping"
650
926
  end
927
+ config.unpaired_sources = unpaired
651
928
  config.sources = paired.map(&:first)
652
929
  config.tests = paired.flat_map(&:last).uniq
653
930
  config.framework = Config.detect_framework(config.tests) unless config.explicit?(:framework)
@@ -680,7 +957,8 @@ module Mutineer
680
957
  # output is expanded the way Reporter#report writes it, so `x/../b.json`
681
958
  # with a missing `x/` still matches `b.json`. File.identical? is false when
682
959
  # 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.
960
+ # Unlike the Action's guard, a human dry run skips this check: it writes no
961
+ # report. JSON dry runs write `--output`, so they call this guard (#362).
684
962
  #
685
963
  # @api private
686
964
  # @param config [Mutineer::Config] run configuration (output and baseline set).
@@ -699,8 +977,9 @@ module Mutineer
699
977
  # except the cache directory: the documented `--output .mutineer/run.json`
700
978
  # must work on a fresh checkout. It is created here, before the run, so a
701
979
  # 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.
980
+ # empty cache directory behind (a real run creates it anyway). A human dry
981
+ # run writes no report, so it creates nothing; `--dry-run --format json`
982
+ # writes the candidate list and may create the cache dir (#362).
704
983
  #
705
984
  # @api private
706
985
  # @param path [String] output file path.
@@ -709,7 +988,7 @@ module Mutineer
709
988
  def self.preflight_output!(path, config)
710
989
  dir = File.dirname(File.expand_path(path))
711
990
  if !File.exist?(dir) && dir == File.expand_path(config.cache_dir, config.project_root)
712
- return if config.dry_run
991
+ return if config.dry_run && config.format != "json"
713
992
 
714
993
  begin
715
994
  FileUtils.mkdir_p(dir)
@@ -735,10 +1014,25 @@ module Mutineer
735
1014
  exit 2
736
1015
  end
737
1016
 
1017
+ operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
1018
+ unpaired, failures, unpaired_ids = JobPlan.unpaired_counts(config, operator_classes)
1019
+ warn_unpaired_count_failures(failures)
1020
+
738
1021
  aggregate, source_map, extras = Runner.execute(config)
739
- warn_legacy_ignore_matches(extras[:legacy_ignore_matches])
1022
+ # Pairing drops unpaired sources before collect_jobs. Their ids still
1023
+ # count, so a real run agrees with a dry run of the same files. The
1024
+ # baseline keeps the paired id map: an unpaired mutant is not a survivor.
1025
+ legacy_matches = merged_legacy_matches(extras[:legacy_ignore_matches], unpaired_ids[:legacy_ignore_matches])
1026
+ warn_legacy_ignore_matches(legacy_matches)
1027
+ # Matched before --since narrows the jobs, so an entry for a mutant
1028
+ # outside the diff is not listed. --only returns an empty list.
1029
+ known = { id_map: extras[:id_map].merge(unpaired_ids[:id_map]),
1030
+ dropped_id_map: extras[:dropped_id_map].merge(unpaired_ids[:dropped_id_map]) }
1031
+ unmatched_ignores = unmatched_ignore_ids(config, known)
1032
+ warn_unmatched_ignores(unmatched_ignores)
740
1033
  matrix = KillMatrix.new(aggregate.results) if config.matrix
741
- reporter = Reporter.new(aggregate, source_map, matrix: matrix)
1034
+ reporter = Reporter.new(aggregate, source_map, matrix: matrix, unpaired: unpaired,
1035
+ fail_fast: config.fail_fast)
742
1036
 
743
1037
  # Diff the current run against the baseline (preflighted above) by the
744
1038
  # stable survivor id. The delta is rendered inline (human section / additive
@@ -754,13 +1048,16 @@ module Mutineer
754
1048
  warn_legacy_baseline if delta&.legacy_matches&.positive?
755
1049
 
756
1050
  # ignore counts old-format entries (one warning each), not the ids they matched.
757
- legacy_id_matches = { ignore: extras[:legacy_ignore_matches].size,
1051
+ legacy_id_matches = { ignore: legacy_matches.size,
758
1052
  baseline: delta ? delta.legacy_matches : 0 }
759
1053
  reporter.report(out: $stdout, err: $stderr, threshold: config.threshold,
760
1054
  format: config.format, output: config.output, baseline: delta,
761
1055
  scoped: !config.since.nil?, legacy_id_matches: legacy_id_matches,
762
- declined: extras.fetch(:declined, {}))
763
- warn_empty_run(config, extras) if aggregate.total.zero?
1056
+ unmatched_ignores: unmatched_ignores,
1057
+ declined: extras.fetch(:declined, {}), subjects: extras.fetch(:subjects, 0),
1058
+ unmutated_subjects: extras.fetch(:unmutated_subjects, []),
1059
+ copies: extras.fetch(:copies, {}))
1060
+ warn_empty_run(config, extras, unpaired) if aggregate.total.zero?
764
1061
 
765
1062
  # Warn (stderr, so it never pollutes json/html) that an external run's score
766
1063
  # is not comparable to an in-process run: no coverage narrowing (uncovered
@@ -798,20 +1095,59 @@ module Mutineer
798
1095
  #
799
1096
  # @param config [Mutineer::Config] run configuration.
800
1097
  # @param extras [Hash] the run extras; `:unscoped_mutants` counts the mutants (run and
801
- # suppressed) before --since, and `:declined` the candidates each operator did not mutate.
1098
+ # suppressed) before --since, `:declined` the candidates each operator did not mutate,
1099
+ # and `:subjects` the methods found (#386).
1100
+ # @param unpaired [Hash{String => Integer, nil}] file => mutant count for sources
1101
+ # pairing skipped. nil means the count failed.
802
1102
  # @return [void]
803
- def self.warn_empty_run(config, extras)
1103
+ def self.warn_empty_run(config, extras, unpaired = {})
1104
+ known = unpaired.each_value.sum { |count| count.is_a?(Integer) ? count : 0 }
1105
+ if known.positive?
1106
+ body = if known == 1
1107
+ "1 mutant is in a source with no paired test"
1108
+ else
1109
+ "#{known} mutants are in sources with no paired test"
1110
+ end
1111
+ warn "mutineer: no mutant ran. #{body} (unpaired_sources[] in --format json). #{UNPAIRED_RUN_HINT}"
1112
+ return
1113
+ end
1114
+
1115
+ # No positive unpaired count, and at least one count failed: mutants may
1116
+ # still exist, so do not call the run empty. Name every unpaired source;
1117
+ # say how many of those counts are unavailable.
1118
+ unknown = unpaired.count { |_file, count| count.nil? }
1119
+ if unknown.positive?
1120
+ total = unpaired.size
1121
+ sources = total == 1 ? "1 source has" : "#{total} sources have"
1122
+ unavailable = unknown == 1 ? "1 of them" : "#{unknown} of them"
1123
+ warn "mutineer: no mutant ran. #{sources} no paired test; the mutant count is unavailable for " \
1124
+ "#{unavailable} (unpaired_sources[] in --format json). #{UNPAIRED_RUN_HINT}"
1125
+ return
1126
+ end
1127
+
804
1128
  # Mutants existed before --since narrowed them: the changes held none.
805
1129
  if config.since && extras[:unscoped_mutants].to_i.positive?
806
1130
  warn "mutineer: nothing to test in the changes since #{config.since}"
807
1131
  elsif !config.allow_empty
808
1132
  declined = extras.fetch(:declined, {}).values.sum
809
- cause = if declined.positive?
810
- "#{declined} #{declined == 1 ? 'candidate was' : 'candidates were'} declined " \
1133
+ methods = extras.fetch(:subjects, 0)
1134
+ causes = []
1135
+ if declined.positive?
1136
+ causes << "#{declined} #{declined == 1 ? 'candidate was' : 'candidates were'} declined " \
811
1137
  "(--dry-run shows the count per operator)."
812
- else
813
- "Check that the sources contain code the operators mutate."
814
- end
1138
+ end
1139
+ # Name the methods the operators passed over (#386), so an empty run on
1140
+ # real code points at the operator set, not at the paths.
1141
+ if methods.positive?
1142
+ found = if methods == 1
1143
+ "1 method was found, and the selected operators made no mutant in it"
1144
+ else
1145
+ "#{methods} methods were found, and the selected operators made no mutant in any of them"
1146
+ end
1147
+ causes << "#{found} (--list-operators shows the others)."
1148
+ end
1149
+ causes << "Check that the sources contain code the operators mutate." if causes.empty?
1150
+ cause = causes.join(" ")
815
1151
  warn "mutineer: no mutants were generated. #{cause} The run exits 0, and #{BECOMES_ERROR_IN_2_0}. " \
816
1152
  "Pass --allow-empty (or allow_empty: true) if an empty run is expected."
817
1153
  end
@@ -850,6 +1186,67 @@ module Mutineer
850
1186
  "#{config_dir} will not match this run. Run mutineer from #{config_dir}."
851
1187
  end
852
1188
 
1189
+ # `ignore:` ids that match no mutant in this run's sources and operators.
1190
+ # The set is the new ids and old-format ids from {JobPlan.collect_jobs}
1191
+ # (`id_map` and `dropped_id_map`), including sources pairing skipped
1192
+ # ({JobPlan.unpaired_counts}), so a dropped repeat of an edit counts as
1193
+ # matched (#275) and an old-format id that still matches is not listed
1194
+ # (the legacy warning names it). Matching happens before `--since` narrows
1195
+ # the jobs, so an entry for a mutant outside the diff is not listed.
1196
+ # `--only` returns an empty list: methods are narrowed before matching, so
1197
+ # a miss there would not mean the entry is stale. File order, each id once.
1198
+ #
1199
+ # @param config [Mutineer::Config] run configuration.
1200
+ # @param extras [Hash] the {JobPlan.collect_jobs} extras (`:id_map`,
1201
+ # `:dropped_id_map`).
1202
+ # @return [Array<String>] unmatched ids.
1203
+ def self.unmatched_ignore_ids(config, extras)
1204
+ return [] if config.only
1205
+
1206
+ known = {}
1207
+ [extras[:id_map], extras[:dropped_id_map]].each do |map|
1208
+ map&.each do |new_id, old_id|
1209
+ known[new_id] = true
1210
+ known[old_id] = true
1211
+ end
1212
+ end
1213
+ seen = {}
1214
+ Array(config.ignore).each_with_object([]) do |id, out|
1215
+ next if known[id] || seen[id]
1216
+
1217
+ seen[id] = true
1218
+ out << id
1219
+ end
1220
+ end
1221
+
1222
+ # Old-format ignore matches from the paired run plus sources pairing
1223
+ # skipped. Arrays are copied, so the paired extras stay unchanged.
1224
+ #
1225
+ # @param paired [Hash{String => Array}] old id => hits from the paired run.
1226
+ # @param unpaired [Hash{String => Array}] the same from unpaired sources.
1227
+ # @return [Hash{String => Array}]
1228
+ def self.merged_legacy_matches(paired, unpaired)
1229
+ merged = paired.to_h { |old, hits| [old, hits.dup] }
1230
+ unpaired.each do |old, hits|
1231
+ (merged[old] ||= []).concat(hits)
1232
+ end
1233
+ merged
1234
+ end
1235
+
1236
+ # Warns once per `ignore:` entry that matched no mutant (#377). The text
1237
+ # says the list covers only this run, so a run of some files does not
1238
+ # claim an entry is stale in the rest of the project. The exit code does
1239
+ # not change. `--only` passes an empty list ({unmatched_ignore_ids}).
1240
+ #
1241
+ # @param ids [Array<String>] unmatched ids, in file order.
1242
+ # @return [void]
1243
+ def self.warn_unmatched_ignores(ids)
1244
+ ids.each do |id|
1245
+ warn "[mutineer] ignore entry #{id} matched no mutant in this run's sources and operators. " \
1246
+ "If those cover its code, the entry is stale: remove it."
1247
+ end
1248
+ end
1249
+
853
1250
  # Warns once per old-format `ignore:` entry (#126), naming each new id it
854
1251
  # matched with that mutant's file and subject. mutineer cannot tell a full
855
1252
  # run from a narrowed one, so the text always says the list covers only this
@@ -891,7 +1288,9 @@ module Mutineer
891
1288
  end
892
1289
 
893
1290
  # Runs dry-run mode. Reuses JobPlan.collect_jobs (+ scope_since) so the
894
- # candidate list cannot drift from a real run's job selection.
1291
+ # candidate list cannot drift from a real run's job selection. `--format
1292
+ # json` emits the lean candidate list (#362); other formats keep the human
1293
+ # listing.
895
1294
  #
896
1295
  # @param config [Mutineer::Config] run configuration.
897
1296
  # @return [void]
@@ -899,20 +1298,41 @@ module Mutineer
899
1298
  operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
900
1299
  jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
901
1300
  warn_legacy_ignore_matches(extras[:legacy_ignore_matches])
1301
+ unmatched_ignores = unmatched_ignore_ids(config, extras)
1302
+ warn_unmatched_ignores(unmatched_ignores)
902
1303
  # Narrow jobs and ignored the same way a real run does, so the summary
903
1304
  # matches the printed list.
904
- jobs, ignored_results, = JobPlan.scope_since(jobs, ignored_results, source_map, config)
1305
+ jobs, ignored_results, = JobPlan.scope_since(jobs, ignored_results, source_map, config, extras: extras)
905
1306
  ignored = ignored_results.size
1307
+ # One valid? pass for both formats: Mutation#valid? re-parses the whole file.
1308
+ valid, invalid = jobs.partition do |subject, mutation, _id|
1309
+ mutation.valid?(source_map[subject.file])
1310
+ end
1311
+ skipped = invalid.size
1312
+
1313
+ # Copies of the mutants this dry run accounts for: the valid candidates
1314
+ # it lists, and the ignored mutants a finished run lists. A candidate
1315
+ # that does not re-parse is skipped and has no row, so its repeats are
1316
+ # left out, as in a finished report (#374).
1317
+ copies = Reporter.copies_for(extras[:copies], valid.map(&:last) + ignored_results.map(&:id))
1318
+ dropped = Reporter.dropped_count_for(copies)
1319
+ if config.format == "json"
1320
+ rendered = Reporter.dry_run_json(valid, source_map, declined: extras[:declined] || {},
1321
+ skipped_invalid: skipped, ignored: ignored,
1322
+ unmatched_ignores: unmatched_ignores, copies: copies)
1323
+ if config.output
1324
+ abs = File.expand_path(config.output)
1325
+ File.write(abs, rendered)
1326
+ warn "Report written to #{abs}"
1327
+ else
1328
+ print rendered
1329
+ end
1330
+ exit 0
1331
+ end
906
1332
 
907
1333
  per_operator = Hash.new(0)
908
- skipped = 0
909
- jobs.each do |subject, mutation, _id|
1334
+ valid.each do |subject, mutation, _id|
910
1335
  source = source_map[subject.file]
911
- unless mutation.valid?(source)
912
- skipped += 1
913
- next
914
- end
915
-
916
1336
  line = source.byteslice(0, mutation.start_offset).count("\n") + 1
917
1337
  per_operator[mutation.operator] += 1
918
1338
  original = source.byteslice(mutation.start_offset...mutation.end_offset)
@@ -920,15 +1340,76 @@ module Mutineer
920
1340
  "#{subject.file}:#{line} `#{original}` -> `#{mutation.replacement}`"
921
1341
  end
922
1342
 
1343
+ # One line per method with no mutants, only with --verbose: on a Rails app
1344
+ # they can be most methods (#386). No brackets, so `^\[` still counts mutations.
1345
+ unmutated = extras[:unmutated_subjects]
1346
+ if config.verbose
1347
+ unmutated.each { |entry| puts "no mutants: #{entry[:subject]} #{entry[:file]}:#{entry[:line]}" }
1348
+ end
1349
+
923
1350
  total = per_operator.values.sum
924
1351
  breakdown = per_operator.map { |op, n| "#{op}: #{n}" }.join(", ")
925
1352
  summary = breakdown.empty? ? "" : "#{breakdown} — "
926
1353
  puts "#{summary}#{total} mutations (dry run, not executed); " \
927
1354
  "#{skipped} skipped (invalid); #{ignored} ignored (suppressed); " \
928
- "#{declined_summary(extras[:declined], since: config.since)}"
1355
+ "#{dropped} dropped (repeats of a kept mutant); " \
1356
+ "#{declined_summary(extras[:declined], since: config.since)}; " \
1357
+ "#{dry_run_unpaired_clause(config, jobs)}; " \
1358
+ "#{unmutated_summary(unmutated.size, extras[:subjects], since: config.since)}"
929
1359
  exit 0
930
1360
  end
931
1361
 
1362
+ # The dry-run unpaired clause. A run with tests, or with no unpaired
1363
+ # source, prints `0 unpaired`. A run with no tests counts jobs in the
1364
+ # unpaired sources. It does not drop those sources from the list above.
1365
+ #
1366
+ # @api private
1367
+ # @param config [Mutineer::Config] run configuration.
1368
+ # @param jobs [Array] scheduled jobs after `--since`.
1369
+ # @return [String] the clause, without a leading semicolon.
1370
+ def self.dry_run_unpaired_clause(config, jobs)
1371
+ return "0 unpaired" unless config.tests.empty?
1372
+
1373
+ _paired, unpaired = convention_pairs(config)
1374
+ return "0 unpaired" if unpaired.empty?
1375
+
1376
+ root = config.project_root
1377
+ unpaired_abs = unpaired.map { |file| File.expand_path(file, root) }
1378
+ count = jobs.count do |subject,|
1379
+ unpaired_abs.include?(File.expand_path(subject.file, root))
1380
+ end
1381
+ noun = unpaired.size == 1 ? "source has" : "sources have"
1382
+ "#{count} unpaired (#{unpaired.size} #{noun} no paired test; a run without --test skips them)"
1383
+ end
1384
+
1385
+ # Prints one stderr line per source whose mutant count failed.
1386
+ # The report still lists that source with no count. The run continues.
1387
+ #
1388
+ # @api private
1389
+ # @param failures [Array<Hash>] `{file:, error:}` rows from {JobPlan.unpaired_counts}.
1390
+ # @return [void]
1391
+ def self.warn_unpaired_count_failures(failures)
1392
+ failures.each do |failure|
1393
+ warn Redaction.text(
1394
+ "[mutineer] could not count the mutants in #{failure[:file]} (#{failure[:error]}). " \
1395
+ "The report lists it with no count.",
1396
+ env: ENV
1397
+ )
1398
+ end
1399
+ end
1400
+
1401
+ # Formats the dry run's count of methods with no mutants (#386). Under
1402
+ # `--since` the count is already narrowed to methods whose def intersects
1403
+ # the diff (#420).
1404
+ #
1405
+ # @param unmutated [Integer] methods the selected operators did not mutate.
1406
+ # @param subjects [Integer] methods discovered (in scope).
1407
+ # @param since [String, nil] unused; kept for call-site symmetry with {declined_summary}.
1408
+ # @return [String] e.g. `no mutants in 1 of 2 methods`.
1409
+ def self.unmutated_summary(unmutated, subjects, since:) # rubocop:disable Lint/UnusedMethodArgument
1410
+ "no mutants in #{unmutated} of #{subjects} methods"
1411
+ end
1412
+
932
1413
  # Formats the dry run's declined count: the total, then each operator's
933
1414
  # count when the total is above zero. `--since` does not narrow the count,
934
1415
  # so under `--since` the text says so.