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,243 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Mutineer
4
+ # Lets the reload strategy load a concern file a second time (#256).
5
+ #
6
+ # ActiveSupport::Concern stores an `included` or `prepended` block once. A
7
+ # second block with another `source_location` raises
8
+ # `MultipleIncludedBlocks` (or `MultiplePrependBlocks`). Rails reloads keep
9
+ # the file's path, but a mutant loads from a temp file beside it, so every
10
+ # mutant of a concern with such a block would error. {.forget} removes the
11
+ # stored blocks that the source file defined, so the mutant's load stores
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.
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?}).
22
+ #
23
+ # Call it only in a forked child that loads the mutant. Without
24
+ # ActiveSupport, {.replace} and {.forget} do nothing; {.store_hook_def} and
25
+ # {.place_hook_def} work without it.
26
+ #
27
+ # Stdlib-only, so the app-side daemon can load it.
28
+ module ConcernBlocks
29
+ # Where ActiveSupport::Concern stores each block.
30
+ STORED_BLOCKS = %i[@_included_block @_prepended_block].freeze
31
+
32
+ # Forgets the source file's stored blocks, runs the block that loads the
33
+ # mutant, then puts back each forgotten block the load did not store again.
34
+ # A concern the mutant's load skips (an `unless defined?` guard) keeps its
35
+ # original block, so a class that includes it during the tests still gets it.
36
+ #
37
+ # @param source_file [String] the file the mutant replaces.
38
+ # @yield the mutant's load.
39
+ # @return [Object] what the block returns.
40
+ def self.replace(source_file)
41
+ forgotten = forget(source_file)
42
+ yield
43
+ ensure
44
+ forgotten&.each do |concern, name, block|
45
+ concern.instance_variable_set(name, block) unless concern.instance_variable_defined?(name)
46
+ end
47
+ end
48
+
49
+ # Removes every stored `included` and `prepended` block that the source
50
+ # file defined, from every concern. Blocks from other files stay.
51
+ #
52
+ # @param source_file [String] the file the mutant replaces.
53
+ # @return [Array<Array(Module, Symbol, Proc)>] each concern, where it stored
54
+ # the block, and the block removed.
55
+ def self.forget(source_file)
56
+ return [] unless defined?(::ActiveSupport::Concern)
57
+
58
+ path = real_path(source_file)
59
+ forgotten = []
60
+ ObjectSpace.each_object(::ActiveSupport::Concern) do |concern|
61
+ STORED_BLOCKS.each do |name|
62
+ next unless concern.instance_variable_defined?(name)
63
+
64
+ block = concern.instance_variable_get(name)
65
+ file = block.source_location&.first
66
+ next unless file && real_path(file) == path
67
+
68
+ concern.remove_instance_variable(name)
69
+ forgotten << [concern, name, block]
70
+ end
71
+ end
72
+ forgotten
73
+ end
74
+
75
+ # Keeps the mutated hook-block def for {.place_hook_def}. The mutant file
76
+ # calls it in the concern's body, just before the hook call, so the block has
77
+ # the same constant scope as the hook block (#297).
78
+ #
79
+ # @yield the mutated def, run later with `class_eval` in each owner.
80
+ # @return [nil]
81
+ def self.store_hook_def(&block)
82
+ @hook_def = block
83
+ nil
84
+ end
85
+
86
+ # Takes the def {.store_hook_def} kept, clears it, and runs it with
87
+ # `class_eval` in each module whose own method came from the original def
88
+ # (see {.owners}), so that module gets the mutated method and nothing else in
89
+ # the block runs again. Each owner keeps the method's visibility. A class
90
+ # that includes the concern later gets the mutant from the stored block.
91
+ #
92
+ # @param source_file [String] the file the mutant replaces.
93
+ # @param line [Integer] the original def's first line.
94
+ # @param name [Symbol] the method name.
95
+ # @param singleton [Boolean] true for a class method.
96
+ # @raise [RuntimeError] when no def was kept (the mutant file did not reach
97
+ # its hook call), or when a module keeps the original under another name
98
+ # (see {.aliases}) or in a live method handle; the child then scores the
99
+ # mutant `error`.
100
+ # @return [Integer] how many owners got the mutated def.
101
+ def self.place_hook_def(source_file:, line:, name:, singleton:)
102
+ block = @hook_def
103
+ @hook_def = nil
104
+ where = "mutineer: could not place the mutant of #{name} (#{source_file}:#{line})"
105
+ unless block
106
+ raise "#{where}: the mutant file did not reach its included or prepended call. " \
107
+ "This is a mutineer bug; please report it."
108
+ end
109
+
110
+ # Check before owner and alias lookup create temporary UnboundMethods.
111
+ if retained_hook_def?(source_file: source_file, line: line, name: name)
112
+ raise "#{where}: the original is retained in a Method or UnboundMethod object, " \
113
+ "so the mutant scores error."
114
+ end
115
+
116
+ # ponytail: one ObjectSpace walk per mutant (about 11 ms with Rails loaded);
117
+ # index modules by method name if a large app makes it slow.
118
+ modules = ObjectSpace.each_object(Module).to_a
119
+ found = owners(modules, source_file: source_file, line: line, name: name, singleton: singleton)
120
+ mod, other = aliases(modules, source_file: source_file, line: line, name: name, singleton: singleton).first
121
+ if mod
122
+ raise "#{where}: #{mod.inspect}#{singleton ? "." : "#"}#{other} is an alias of it and keeps the " \
123
+ "original method, so the mutant scores error."
124
+ end
125
+
126
+ found.each do |owner|
127
+ target = singleton ? owner.singleton_class : owner
128
+ visibility = if target.private_method_defined?(name, false) then :private
129
+ elsif target.protected_method_defined?(name, false) then :protected
130
+ end
131
+ owner.class_eval(&block) # a `def` in the block defines public
132
+ target.send(visibility, name) if visibility
133
+ end
134
+ found.size
135
+ end
136
+
137
+ # Each module whose own method `name` (its singleton class's, for a class
138
+ # method) has the original def's file and line: every place the original
139
+ # block defined it. A subclass that overrides the method, or a class that
140
+ # only inherits it, is not one.
141
+ #
142
+ # @param modules [Array<Module>] every module, including singleton classes
143
+ # into which a concern can be included.
144
+ # @param source_file [String] the file the mutant replaces.
145
+ # @param line [Integer] the original def's first line.
146
+ # @param name [Symbol] the method name.
147
+ # @param singleton [Boolean] true for a class method.
148
+ # @return [Array<Module>]
149
+ def self.owners(modules, source_file:, line:, name:, singleton:)
150
+ path = real_path(source_file)
151
+ modules.select { |mod| own_method_at?(singleton ? mod.singleton_class : mod, name, path, line) }
152
+ end
153
+
154
+ # Each other name any module has for the original def: an alias made
155
+ # outside the block. Check independently of {.owners}: a wrapper can replace
156
+ # the original name while its alias keeps the original body, so the mutant
157
+ # could falsely survive even when no current-name owner remains.
158
+ #
159
+ # @param modules [Array<Module>] every module, including singleton classes.
160
+ # @param source_file [String] the file the mutant replaces.
161
+ # @param line [Integer] the original def's first line.
162
+ # @param name [Symbol] the method name.
163
+ # @param singleton [Boolean] true for a class method.
164
+ # @return [Array<Array(Module, Symbol)>] each module and its alias name.
165
+ def self.aliases(modules, source_file:, line:, name:, singleton:)
166
+ path = real_path(source_file)
167
+ modules.flat_map do |mod|
168
+ target = singleton ? mod.singleton_class : mod
169
+ (target.instance_methods(false) + target.private_instance_methods(false)).filter_map do |other|
170
+ [mod, other] if other != name && own_method_at?(target, other, path, line, original_name: name)
171
+ end
172
+ end
173
+ end
174
+
175
+ # True when the module's own method `name` starts at this file and line.
176
+ # A prepended method can hide it from `instance_method`, so follow `super`
177
+ # until the lookup reaches the method whose owner is the module itself.
178
+ #
179
+ # @param target [Module] the module or singleton class to read.
180
+ # @param name [Symbol] the method name.
181
+ # @param path [String] the source file's real path.
182
+ # @param line [Integer] the def's first line.
183
+ # @param original_name [Symbol] the name the original definition used;
184
+ # distinguishes an alias from another definition on the same line.
185
+ # @return [Boolean]
186
+ def self.own_method_at?(target, name, path, line, original_name: name)
187
+ return false unless target.method_defined?(name, false) || target.private_method_defined?(name, false)
188
+
189
+ method = target.instance_method(name)
190
+ method = method.super_method while method && !method.owner.equal?(target)
191
+ return false unless method
192
+
193
+ file, def_line = method.source_location
194
+ method.original_name == original_name && def_line == line && !file.nil? && real_path(file) == path
195
+ end
196
+
197
+ # True when a live Method or UnboundMethod keeps the original definition.
198
+ # A wrapper can call that handle after the named method was replaced, so
199
+ # loading another def cannot make the wrapper test the mutant. A matching
200
+ # but unreachable reflection result is harmless: collect it, then check
201
+ # again. Most mutants have no matching handle and need no explicit GC.
202
+ #
203
+ # @param source_file [String] the file the mutant replaces.
204
+ # @param line [Integer] the original def's first line.
205
+ # @param name [Symbol] the original method name.
206
+ # @return [Boolean]
207
+ def self.retained_hook_def?(source_file:, line:, name:)
208
+ path = real_path(source_file)
209
+ return false unless method_handle_at?(path, line, name)
210
+
211
+ GC.start
212
+ method_handle_at?(path, line, name)
213
+ end
214
+
215
+ # True when the heap contains a handle for this original definition. Return
216
+ # only a boolean, so the first check does not itself retain a dead handle
217
+ # across the GC in {.retained_hook_def?}.
218
+ #
219
+ # @param path [String] the source file's real path.
220
+ # @param line [Integer] the original def's first line.
221
+ # @param name [Symbol] the original method name.
222
+ # @return [Boolean]
223
+ def self.method_handle_at?(path, line, name)
224
+ [Method, UnboundMethod].any? do |kind|
225
+ ObjectSpace.each_object(kind).any? do |method|
226
+ file, def_line = method.source_location
227
+ method.original_name == name && def_line == line && !file.nil? && real_path(file) == path
228
+ end
229
+ end
230
+ end
231
+
232
+ # The file's real path, so a symlinked or relative path matches the path
233
+ # Ruby recorded when it loaded the file.
234
+ #
235
+ # @param file [String] a file path.
236
+ # @return [String]
237
+ def self.real_path(file)
238
+ File.realpath(file)
239
+ rescue SystemCallError
240
+ File.expand_path(file)
241
+ end
242
+ end
243
+ end
@@ -1,9 +1,25 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require "did_you_mean"
3
4
  require "etc"
4
5
  require "yaml"
5
6
 
6
7
  module Mutineer
8
+ # The phrase every 1.x warning uses for behaviour that 2.0 turns into an
9
+ # error, so the 2.0 release can find each of those sites with one search.
10
+ BECOMES_ERROR_IN_2_0 = "this becomes an error in Mutineer 2.0"
11
+
12
+ # A "did you mean" hint for a misspelled name, using the stdlib spell
13
+ # checker that Ruby itself uses for NameError.
14
+ #
15
+ # @param word [String] the name the user wrote.
16
+ # @param candidates [Array<String>] the names that are valid here.
17
+ # @return [String] ` (did you mean "x"?)` for the closest candidate, or "" when none is close.
18
+ def self.did_you_mean(word, candidates)
19
+ match = DidYouMean::SpellChecker.new(dictionary: candidates).correct(word.to_s).first
20
+ match ? " (did you mean #{match.inspect}?)" : ""
21
+ end
22
+
7
23
  # Raised by the config layer instead of calling exit/abort. A data class must
8
24
  # never kill the host process. The CLI rescues this and maps it to exit 2.
9
25
  class ConfigError < StandardError; end
@@ -36,7 +52,7 @@ module Mutineer
36
52
  ConfigOption.new(field: :framework, type: :enum, yaml_key: "framework", flag: "--framework",
37
53
  values: %w[minitest rspec]),
38
54
  ConfigOption.new(field: :verbose, type: :bool, yaml_key: "verbose", flag: "--verbose"),
39
- ConfigOption.new(field: :ignore, type: :string_list, yaml_key: "ignore"),
55
+ ConfigOption.new(field: :ignore, type: :ignore_list, yaml_key: "ignore"),
40
56
  ConfigOption.new(field: :baseline, type: :string, yaml_key: "baseline", flag: "--baseline"),
41
57
  ConfigOption.new(field: :fail_fast, type: :bool, yaml_key: "fail_fast", flag: "--fail-fast"),
42
58
  ConfigOption.new(field: :matrix, type: :bool, yaml_key: "matrix", flag: "--matrix"),
@@ -46,6 +62,9 @@ module Mutineer
46
62
  ConfigOption.new(field: :capture_timeout, type: :positive_int, yaml_key: "capture_timeout",
47
63
  flag: "--capture-timeout"),
48
64
  ConfigOption.new(field: :cache_dir, type: :string, yaml_key: "cache_dir", flag: "--cache-dir"),
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"),
67
+ ConfigOption.new(field: :coverage_from, type: :string, flag: "--coverage-from"),
49
68
  ConfigOption.new(field: :format, type: :enum, flag: "--format", values: %w[human json html]),
50
69
  ConfigOption.new(field: :strategy, type: :enum, flag: "--strategy", values: %w[reload redefine],
51
70
  aliases: STRATEGY_ALIASES),
@@ -66,6 +85,9 @@ module Mutineer
66
85
  # `matrix` (--matrix) runs every covering test for each mutant and reports
67
86
  # which tests kill it (see KillMatrix); it never changes a verdict.
68
87
  #
88
+ # `shared_databases` (file only) names test database configs that parallel
89
+ # `--daemon` workers may share; see DaemonBackend.worker_count_for.
90
+ #
69
91
  # Boot mode adds: boot (a file to require ONCE in the parent so the app env,
70
92
  # e.g. Rails, is booted before forking; sources are then NOT manually required)
71
93
  # and rails (sugar: defaults boot to config/environment, prefers redefine without
@@ -74,11 +96,12 @@ module Mutineer
74
96
  :sources, :tests, :operators, :threshold, :only, :dry_run,
75
97
  :cache_dir, :project_root, :load_paths,
76
98
  :jobs, :format, :output, :strategy, :require_paths,
77
- :boot, :rails, :since, :framework, :verbose, :ignore,
99
+ :boot, :rails, :since, :framework, :verbose, :ignore, :ignore_reasons,
78
100
  # :daemon is user-facing (--daemon flag + KNOWN_KEYS + boolean coerce).
79
101
  # :daemon_timeout stays programmatic (set by tests/Runner; no flag yet).
80
102
  :baseline, :baseline_epsilon, :fail_fast, :test_command,
81
- :daemon, :daemon_timeout, :timeout, :capture_timeout, :matrix,
103
+ :daemon, :daemon_timeout, :timeout, :capture_timeout, :matrix, :allow_empty, :coverage_from,
104
+ :shared_databases,
82
105
  keyword_init: true
83
106
  ) do
84
107
  # Config file name.
@@ -109,10 +132,13 @@ module Mutineer
109
132
  self.rails = false if rails.nil?
110
133
  self.verbose = false if verbose.nil?
111
134
  self.ignore ||= []
135
+ self.ignore_reasons ||= {}
112
136
  self.baseline_epsilon ||= 0.0
113
137
  self.fail_fast = false if fail_fast.nil?
114
138
  self.daemon = false if daemon.nil?
115
139
  self.matrix = false if matrix.nil?
140
+ self.allow_empty = false if allow_empty.nil?
141
+ self.shared_databases ||= []
116
142
  end
117
143
 
118
144
  # True when the user wrote `key`, on the command line or in the config
@@ -180,12 +206,17 @@ module Mutineer
180
206
  raw.each do |key, value|
181
207
  ks = key.to_s
182
208
  unless KNOWN_KEYS.include?(ks)
183
- warn "mutineer: unknown config key #{ks.inspect} in #{name} " \
184
- "(known: #{KNOWN_KEYS.join(', ')}); ignored"
209
+ warn "mutineer: unknown config key #{ks.inspect} in #{name}#{Mutineer.did_you_mean(ks, KNOWN_KEYS)}; " \
210
+ "ignored, and #{BECOMES_ERROR_IN_2_0} (known: #{KNOWN_KEYS.join(', ')})"
185
211
  next
186
212
  end
187
213
  field = field_for(ks)
188
214
  parsed = parse(field, value, file: name, defer_operators: defer_operators)
215
+ if field == :ignore
216
+ out[:ignore] = parsed.fetch(:ids)
217
+ out[:ignore_reasons] = parsed.fetch(:reasons)
218
+ next
219
+ end
189
220
  if field == :operators
190
221
  parsed = filter_operators(parsed, name)
191
222
  if parsed.empty? && !defer_operators
@@ -220,7 +251,9 @@ module Mutineer
220
251
  config.strategy = "redefine"
221
252
  end
222
253
  unless config.daemon
223
- if config.jobs.to_i > 1
254
+ # A typed --no-daemon already chose the serial run; only an explicit
255
+ # --jobs N still needs telling that --daemon is the way to get N.
256
+ if config.jobs.to_i > 1 && (!config.explicit?(:daemon) || config.explicit?(:jobs))
224
257
  warn "[mutineer] --rails without --daemon runs serially (shared test DB); " \
225
258
  "forcing --jobs 1. Use --daemon for safe --jobs N."
226
259
  end
@@ -235,6 +268,24 @@ module Mutineer
235
268
  config
236
269
  end
237
270
 
271
+ # Mutineer 2.0 makes the daemon the default under --rails for Minitest, so a
272
+ # run that would change says so now. The CLI calls this after test pairing,
273
+ # which can still switch the framework to rspec. The runs that 2.0 keeps on this path
274
+ # stay quiet: RSpec, --test-command, --matrix and --fail-fast cannot use the
275
+ # daemon, a --dry-run runs no tests, and a written `daemon` value (true or
276
+ # false) is the user's choice.
277
+ #
278
+ # @api private
279
+ # @param config [Mutineer::Config] the resolved config.
280
+ # @return [void]
281
+ def self.warn_rails_default_change(config)
282
+ return unless config.rails && !config.explicit?(:daemon) && config.framework == "minitest"
283
+ return if config.test_command || config.matrix || config.fail_fast || config.dry_run
284
+
285
+ warn "[mutineer] in Mutineer 2.0, --rails uses --daemon by default: parallel workers (unless " \
286
+ "--jobs 1) and the reload strategy. Pass --no-daemon (or daemon: false) to keep this run as it is."
287
+ end
288
+
238
289
  # Pick rspec when a MAJORITY of the given test files end with _spec.rb;
239
290
  # otherwise minitest. Empty/ambiguous -> minitest (the safe default).
240
291
  #
@@ -299,6 +350,8 @@ module Mutineer
299
350
 
300
351
  prefix = file ? "#{file}: " : ""
301
352
  raise ConfigError, "#{prefix}unknown #{field} #{value.to_s.inspect}. Expected: #{opt.values.join(', ')}"
353
+ when :ignore_list
354
+ parse_ignore_list(value, file)
302
355
  when :string_list
303
356
  items = Array(value).map(&:to_s)
304
357
  # Only `operators` treats [] as "run these" rather than "use the
@@ -319,6 +372,7 @@ module Mutineer
319
372
  # A blank cache directory (an unset CI variable) would put coverage.json
320
373
  # in the project root, so it is an error, not the default.
321
374
  raise ConfigError, "#{origin} must be a directory, not blank #{got}" if field == :cache_dir && value.to_s.strip.empty?
375
+ raise ConfigError, "#{origin} must be a file, not blank #{got}" if field == :coverage_from && value.to_s.strip.empty?
322
376
 
323
377
  value.to_s
324
378
  when :since
@@ -350,6 +404,98 @@ module Mutineer
350
404
  f if f&.finite?
351
405
  end
352
406
 
407
+ # Reads an `ignore:` value into ids plus a reason for each mapping.
408
+ # A bare string or integer is an id with no reason. YAML reads an unquoted
409
+ # all-digit id as an integer, and the id text is those decimal digits.
410
+ # A mapping may hold `id` and `reason` only. A mapping with no id, or with
411
+ # any other key, is dropped and warned: 2.0 will reject it. Callers that
412
+ # match ids keep the id list.
413
+ #
414
+ # @api private
415
+ # @param value [Object] the raw YAML value.
416
+ # @param file [String, nil] config file name.
417
+ # @return [Hash] `:ids` is an array of id strings. `:reasons` maps an id to its text.
418
+ def self.parse_ignore_list(value, file)
419
+ label = file || CONFIG_FILE
420
+ case value
421
+ when nil then return { ids: [], reasons: {} }
422
+ when String, Integer then return { ids: [ignore_id_text(value)], reasons: {} }
423
+ when Array then items = value
424
+ when Hash then items = [value]
425
+ else
426
+ warn "mutineer: ignore in #{label} must be a list; ignored, and #{BECOMES_ERROR_IN_2_0}"
427
+ return { ids: [], reasons: {} }
428
+ end
429
+
430
+ ids = []
431
+ reasons = {}
432
+ items.each_with_index do |item, index|
433
+ number = index + 1
434
+ id = ignore_id_text(item)
435
+ if id
436
+ ids << id unless id.empty? || ids.include?(id)
437
+ elsif item.is_a?(Hash)
438
+ mapped, reason = ignore_mapping(item, number, label)
439
+ next if mapped.nil?
440
+
441
+ ids << mapped unless ids.include?(mapped)
442
+ reasons[mapped] = reason if reason
443
+ else
444
+ warn "mutineer: ignore entry #{number} in #{label} is not an id or a mapping; " \
445
+ "ignored, and #{BECOMES_ERROR_IN_2_0}"
446
+ end
447
+ end
448
+ { ids: ids, reasons: reasons }
449
+ end
450
+
451
+ # Text of one ignore id. An integer is the decimal digits YAML kept.
452
+ # A leading zero is already gone by then, so quote an id that needs one.
453
+ # Any other type is not an id.
454
+ #
455
+ # @api private
456
+ # @param value [Object] a list item, a scalar ignore value, or a mapping id.
457
+ # @return [String, nil] the id text, or nil when the value cannot be an id.
458
+ def self.ignore_id_text(value)
459
+ case value
460
+ when String then value
461
+ when Integer then value.to_s
462
+ end
463
+ end
464
+
465
+ # One `ignore:` mapping. Returns the id and reason, or nil when the entry
466
+ # is not usable.
467
+ #
468
+ # @api private
469
+ # @param item [Hash] the mapping.
470
+ # @param number [Integer] 1-based index in the list.
471
+ # @param label [String] config file name.
472
+ # @return [Array(String, String), Array(nil, nil)]
473
+ def self.ignore_mapping(item, number, label)
474
+ unknown = item.keys.map(&:to_s) - %w[id reason]
475
+ unless unknown.empty?
476
+ names = unknown.map(&:inspect).join(", ")
477
+ warn "mutineer: ignore entry #{number} in #{label} has unknown key #{names}; " \
478
+ "ignored, and #{BECOMES_ERROR_IN_2_0}"
479
+ return [nil, nil]
480
+ end
481
+
482
+ id = ignore_id_text(item["id"] || item[:id])
483
+ unless id.is_a?(String) && !id.strip.empty?
484
+ warn "mutineer: ignore entry #{number} in #{label} has no id; ignored, and #{BECOMES_ERROR_IN_2_0}"
485
+ return [nil, nil]
486
+ end
487
+
488
+ reason = item.key?("reason") ? item["reason"] : item[:reason]
489
+ if !reason.nil? && !reason.is_a?(String)
490
+ warn "mutineer: ignore entry #{number} in #{label} reason must be text; " \
491
+ "ignored, and #{BECOMES_ERROR_IN_2_0}"
492
+ return [nil, nil]
493
+ end
494
+
495
+ text = reason.to_s.strip
496
+ [id, text.empty? ? nil : text]
497
+ end
498
+
353
499
  # Drop (with a warning) operator names the registry does not know.
354
500
  # Referenced lazily so config.rb carries no load-order dependency on the
355
501
  # registry; by the time a config is parsed at runtime, it is loaded.
@@ -363,8 +509,8 @@ module Mutineer
363
509
  names.select do |n|
364
510
  next true if known.include?(n)
365
511
 
366
- warn "mutineer: unknown operator #{n.inspect} in #{file_name} " \
367
- "(known: #{known.join(', ')}); ignored"
512
+ warn "mutineer: unknown operator #{n.inspect} in #{file_name}#{Mutineer.did_you_mean(n, known)}; " \
513
+ "ignored, and #{BECOMES_ERROR_IN_2_0} (known: #{known.join(', ')})"
368
514
  false
369
515
  end
370
516
  end