Class: Mutineer::Config

Inherits:
Struct
  • Object
show all
Defined in:
lib/mutineer/config.rb

Overview

Plain run configuration, populated by the CLI (or directly by the integration test). operators nil means "all default operators"; threshold 0.0 means the CI gate is off (spec §10).

Also holds: jobs (parallel workers), format (human|json), output (report file), strategy (reload|redefine), require_paths (extra files to load). Config loading and the CLI > file > default precedence merge live here; each layer holds only the keys the user wrote, and Config#explicit? reports them.

matrix (--matrix) runs every covering test for each mutant and reports which tests kill it (see KillMatrix); it never changes a verdict.

shared_databases (file only) names test database configs that parallel --daemon workers may share; see DaemonBackend.worker_count_for.

test_map (file key tests, no flag) holds checked source→test pattern entries that pairing adds to a source's paired tests (#382). Distinct from :tests, the CLI --test file list.

Boot mode adds: boot (a file to require ONCE in the parent so the app env, e.g. Rails, is booted before forking; sources are then NOT manually required) and rails (sugar: defaults boot to config/environment, prefers redefine without a daemon, and reconnects ActiveRecord per fork).

unpaired_sources is code only. Pairing stores each source it skips because no conventional test exists. An explicit test list leaves it empty. There is no flag and no config-file key.

Constant Summary collapse

CONFIG_FILE =

Config file name.

".mutineer.yml"
KNOWN_KEYS =

Keys accepted in .mutineer.yml, derived from the schema. require maps to :require_paths; tests maps to :test_map (not the CLI :tests field).

CONFIG_OPTIONS.filter_map(&:yaml_key).freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(explicit: [], from_file: [], **kwargs) ⇒ Config

Returns a new instance of Config.

Parameters:

  • explicit (Array<Symbol>) (defaults to: []) —

    fields the user wrote (CLI or file). Derived values fill only the others; a programmatic Config.new writes none.

  • from_file (Array<Symbol>) (defaults to: []) —

    the explicit fields whose value came from the config file (the command line did not override them).



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
# File 'lib/mutineer/config.rb', line 129

def initialize(explicit: [], from_file: [], **kwargs)
  super(**kwargs)
  @explicit = explicit.to_a.dup.freeze
  @from_file = from_file.to_a.dup.freeze
  self.sources       ||= []
  self.tests         ||= []
  self.threshold     ||= 0.0
  self.dry_run       ||= false
  self.cache_dir     ||= ".mutineer"
  self.project_root = FsPath.read(project_root || Dir.pwd)
  self.load_paths    ||= ["lib"]
  self.jobs          ||= Etc.nprocessors
  self.format        ||= "human"
  self.strategy      ||= "reload"
  self.require_paths ||= []
  self.rails         = false if rails.nil?
  self.verbose       = false if verbose.nil?
  self.ignore        ||= []
  self.ignore_reasons ||= {}
  self.baseline_epsilon ||= 0.0
  self.fail_fast     = false if fail_fast.nil?
  self.daemon        = false if daemon.nil?
  self.matrix        = false if matrix.nil?
  self.allow_empty   = false if allow_empty.nil?
  self.shared_databases ||= []
  self.unpaired_sources ||= []
  self.test_map      ||= []
end

Instance Attribute Details

#allow_empty ⇒ Object

Returns the value of attribute allow_empty

Returns:

  • (Object) —

    the current value of allow_empty



106
107
108
# File 'lib/mutineer/config.rb', line 106

def allow_empty
  @allow_empty
end

#baseline ⇒ Object

Returns the value of attribute baseline

Returns:

  • (Object) —

    the current value of baseline



106
107
108
# File 'lib/mutineer/config.rb', line 106

def baseline
  @baseline
end

#baseline_epsilon ⇒ Object

Returns the value of attribute baseline_epsilon

Returns:

  • (Object) —

    the current value of baseline_epsilon



106
107
108
# File 'lib/mutineer/config.rb', line 106

def baseline_epsilon
  @baseline_epsilon
end

#boot ⇒ Object

Returns the value of attribute boot

Returns:

  • (Object) —

    the current value of boot



106
107
108
# File 'lib/mutineer/config.rb', line 106

def boot
  @boot
end

#cache_dir ⇒ Object

Returns the value of attribute cache_dir

Returns:

  • (Object) —

    the current value of cache_dir



106
107
108
# File 'lib/mutineer/config.rb', line 106

def cache_dir
  @cache_dir
end

#capture_timeout ⇒ Object

Returns the value of attribute capture_timeout

Returns:

  • (Object) —

    the current value of capture_timeout



106
107
108
# File 'lib/mutineer/config.rb', line 106

def capture_timeout
  @capture_timeout
end

#coverage_from ⇒ Object

Returns the value of attribute coverage_from

Returns:

  • (Object) —

    the current value of coverage_from



106
107
108
# File 'lib/mutineer/config.rb', line 106

def coverage_from
  @coverage_from
end

#daemon ⇒ Object

Returns the value of attribute daemon

Returns:

  • (Object) —

    the current value of daemon



106
107
108
# File 'lib/mutineer/config.rb', line 106

def daemon
  @daemon
end

#daemon_timeout ⇒ Object

Returns the value of attribute daemon_timeout

Returns:

  • (Object) —

    the current value of daemon_timeout



106
107
108
# File 'lib/mutineer/config.rb', line 106

def daemon_timeout
  @daemon_timeout
end

#dry_run ⇒ Object

Returns the value of attribute dry_run

Returns:

  • (Object) —

    the current value of dry_run



106
107
108
# File 'lib/mutineer/config.rb', line 106

def dry_run
  @dry_run
end

#fail_fast ⇒ Object

Returns the value of attribute fail_fast

Returns:

  • (Object) —

    the current value of fail_fast



106
107
108
# File 'lib/mutineer/config.rb', line 106

def fail_fast
  @fail_fast
end

#format ⇒ Object

Returns the value of attribute format

Returns:

  • (Object) —

    the current value of format



106
107
108
# File 'lib/mutineer/config.rb', line 106

def format
  @format
end

#framework ⇒ Object

Returns the value of attribute framework

Returns:

  • (Object) —

    the current value of framework



106
107
108
# File 'lib/mutineer/config.rb', line 106

def framework
  @framework
end

#ignore ⇒ Object

Returns the value of attribute ignore

Returns:

  • (Object) —

    the current value of ignore



106
107
108
# File 'lib/mutineer/config.rb', line 106

def ignore
  @ignore
end

#ignore_reasons ⇒ Object

Returns the value of attribute ignore_reasons

Returns:

  • (Object) —

    the current value of ignore_reasons



106
107
108
# File 'lib/mutineer/config.rb', line 106

def ignore_reasons
  @ignore_reasons
end

#jobs ⇒ Object

Returns the value of attribute jobs

Returns:

  • (Object) —

    the current value of jobs



106
107
108
# File 'lib/mutineer/config.rb', line 106

def jobs
  @jobs
end

#load_paths ⇒ Object

Returns the value of attribute load_paths

Returns:

  • (Object) —

    the current value of load_paths



106
107
108
# File 'lib/mutineer/config.rb', line 106

def load_paths
  @load_paths
end

#matrix ⇒ Object

Returns the value of attribute matrix

Returns:

  • (Object) —

    the current value of matrix



106
107
108
# File 'lib/mutineer/config.rb', line 106

def matrix
  @matrix
end

#only ⇒ Object

Returns the value of attribute only

Returns:

  • (Object) —

    the current value of only



106
107
108
# File 'lib/mutineer/config.rb', line 106

def only
  @only
end

#operators ⇒ Object

Returns the value of attribute operators

Returns:

  • (Object) —

    the current value of operators



106
107
108
# File 'lib/mutineer/config.rb', line 106

def operators
  @operators
end

#output ⇒ Object

Returns the value of attribute output

Returns:

  • (Object) —

    the current value of output



106
107
108
# File 'lib/mutineer/config.rb', line 106

def output
  @output
end

#project_root ⇒ Object

Returns the value of attribute project_root

Returns:

  • (Object) —

    the current value of project_root



106
107
108
# File 'lib/mutineer/config.rb', line 106

def project_root
  @project_root
end

#rails ⇒ Object

Returns the value of attribute rails

Returns:

  • (Object) —

    the current value of rails



106
107
108
# File 'lib/mutineer/config.rb', line 106

def rails
  @rails
end

#require_paths ⇒ Object

Returns the value of attribute require_paths

Returns:

  • (Object) —

    the current value of require_paths



106
107
108
# File 'lib/mutineer/config.rb', line 106

def require_paths
  @require_paths
end

#shared_databases ⇒ Object

Returns the value of attribute shared_databases

Returns:

  • (Object) —

    the current value of shared_databases



106
107
108
# File 'lib/mutineer/config.rb', line 106

def shared_databases
  @shared_databases
end

#since ⇒ Object

Returns the value of attribute since

Returns:

  • (Object) —

    the current value of since



106
107
108
# File 'lib/mutineer/config.rb', line 106

def since
  @since
end

#sources ⇒ Object

Returns the value of attribute sources

Returns:

  • (Object) —

    the current value of sources



106
107
108
# File 'lib/mutineer/config.rb', line 106

def sources
  @sources
end

#strategy ⇒ Object

Returns the value of attribute strategy

Returns:

  • (Object) —

    the current value of strategy



106
107
108
# File 'lib/mutineer/config.rb', line 106

def strategy
  @strategy
end

#test_command ⇒ Object

Returns the value of attribute test_command

Returns:

  • (Object) —

    the current value of test_command



106
107
108
# File 'lib/mutineer/config.rb', line 106

def test_command
  @test_command
end

#test_map ⇒ Object

Returns the value of attribute test_map

Returns:

  • (Object) —

    the current value of test_map



106
107
108
# File 'lib/mutineer/config.rb', line 106

def test_map
  @test_map
end

#tests ⇒ Object

Returns the value of attribute tests

Returns:

  • (Object) —

    the current value of tests



106
107
108
# File 'lib/mutineer/config.rb', line 106

def tests
  @tests
end

#threshold ⇒ Object

Returns the value of attribute threshold

Returns:

  • (Object) —

    the current value of threshold



106
107
108
# File 'lib/mutineer/config.rb', line 106

def threshold
  @threshold
end

#timeout ⇒ Object

Returns the value of attribute timeout

Returns:

  • (Object) —

    the current value of timeout



106
107
108
# File 'lib/mutineer/config.rb', line 106

def timeout
  @timeout
end

#unpaired_sources ⇒ Object

Returns the value of attribute unpaired_sources

Returns:

  • (Object) —

    the current value of unpaired_sources



106
107
108
# File 'lib/mutineer/config.rb', line 106

def unpaired_sources
  @unpaired_sources
end

#verbose ⇒ Object

Returns the value of attribute verbose

Returns:

  • (Object) —

    the current value of verbose



106
107
108
# File 'lib/mutineer/config.rb', line 106

def verbose
  @verbose
end

Class Method Details

.detect_framework(tests) ⇒ String

Pick rspec when a MAJORITY of the given test files end with _spec.rb; otherwise minitest. Empty/ambiguous -> minitest (the safe default).

Parameters:

  • tests (Array<String>) —

    test file paths.

Returns:

  • (String) —

    "rspec" or "minitest".



308
309
310
311
312
# File 'lib/mutineer/config.rb', line 308

def self.detect_framework(tests)
  tests = Array(tests)
  specs = tests.count { |t| t.to_s.end_with?("_spec.rb") }
  specs > tests.length / 2.0 ? "rspec" : "minitest"
end

.field_for(known_key) ⇒ Symbol

Maps a config key to its Struct field. Reads the schema row so YAML keys that differ from the field (require → :require_paths, tests → :test_map) stay correct without a hand-maintained alias list.

Parameters:

  • known_key (String) —

    config key.

Returns:

  • (Symbol) —

    struct field name.



320
321
322
# File 'lib/mutineer/config.rb', line 320

def self.field_for(known_key)
  CONFIG_OPTIONS.find { |o| o.yaml_key == known_key }&.field || known_key.to_sym
end

.filter_operators(names, file_name) ⇒ Array<String>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Drop (with a warning) operator names the registry does not know. Referenced lazily so config.rb carries no load-order dependency on the registry; by the time a config is parsed at runtime, it is loaded.

Parameters:

  • names (Array<String>) —

    operator names.

  • file_name (String) —

    config file name for warnings.

Returns:

  • (Array<String>) —

    known operator names.



613
614
615
616
617
618
619
620
621
622
# File 'lib/mutineer/config.rb', line 613

def self.filter_operators(names, file_name)
  known = MutatorRegistry::ALL.keys
  names.select do |n|
    next true if known.include?(n)

    warn "mutineer: unknown operator #{n.inspect} in #{file_name}#{Mutineer.did_you_mean(n, known)}; " \
         "ignored, and #{BECOMES_ERROR_IN_2_0} (known: #{known.join(', ')})"
    false
  end
end

.find_file(start = Dir.pwd, home = File.expand_path("~")) ⇒ Object

Walk from start toward home, returning the first .mutineer.yml path found or nil. Checks home itself, then stops; if start is above home (e.g. /tmp), the walk continues to the filesystem root. Pure discovery; reads no file content.



184
185
186
187
188
189
190
191
192
193
194
195
196
197
# File 'lib/mutineer/config.rb', line 184

def self.find_file(start = Dir.pwd, home = File.expand_path("~"))
  dir = File.expand_path(start)
  loop do
    candidate = File.join(dir, CONFIG_FILE)
    return candidate if File.file?(candidate)
    break if dir == home

    parent = File.dirname(dir)
    break if parent == dir # filesystem root

    dir = parent
  end
  nil
end

.finite_float(value) ⇒ Float?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Reads a finite Float from a number or a plain decimal string. Rejects booleans, NaN and Infinity: Float(true) is an error, but a YAML .nan is a Float. A string must be digits with an optional fraction, the same digits-only rule as jobs: Float() alone would also read 0x10, 1_0, +2 and 1e2.

Parameters:

  • value (Object) —

    raw value.

Returns:

  • (Float, nil) —

    the number, or nil when it is not a finite number.



417
418
419
420
421
422
423
# File 'lib/mutineer/config.rb', line 417

def self.finite_float(value)
  f = case value
      when Integer, Float then value.to_f
      when String then Float(value) if value.match?(/\A\d+(\.\d+)?\z/)
      end
  f if f&.finite?
end

.from_file(path, defer_operators: false) ⇒ Hash{Symbol => Object}

Parse a .mutineer.yml into a symbol-keyed hash of recognized keys. Unknown keys emit a one-line stderr warning and are ignored. Unknown operator names warn and are dropped. If that leaves no names, the file is an error: an empty operator list would run nothing and exit 0. Pass defer_operators: true only when the command line replaces that list, so a blank or all-unknown file list does not block --operators. A YAML syntax error raises ConfigError: never a silent fallback to defaults, and never an exit from the lib layer.

Parameters:

  • path (String) —

    config file path.

  • defer_operators (Boolean) (defaults to: false) —

    keep an empty operator list for a CLI override.

Returns:

  • (Hash{Symbol => Object})


211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
# File 'lib/mutineer/config.rb', line 211

def self.from_file(path, defer_operators: false)
  raw = YAML.safe_load(File.read(path)) || {}
  name = File.basename(path)
  unless raw.is_a?(Hash)
    warn "mutineer: #{name} ignored: expected a YAML mapping of keys to values"
    return {}
  end

  out = {}
  raw.each do |key, value|
    ks = key.to_s
    unless KNOWN_KEYS.include?(ks)
      warn "mutineer: unknown config key #{ks.inspect} in #{name}#{Mutineer.did_you_mean(ks, KNOWN_KEYS)}; " \
           "ignored, and #{BECOMES_ERROR_IN_2_0} (known: #{KNOWN_KEYS.join(', ')})"
      next
    end
    field = field_for(ks)
    parsed = parse(field, value, file: name, defer_operators: defer_operators)
    if field == :ignore
      out[:ignore] = parsed.fetch(:ids)
      out[:ignore_reasons] = parsed.fetch(:reasons)
      next
    end
    if field == :operators
      parsed = filter_operators(parsed, name)
      if parsed.empty? && !defer_operators
        raise ConfigError, "#{name}: operators must name at least one known operator"
      end
    end
    out[field] = parsed
  end
  out
rescue Psych::SyntaxError => e
  raise ConfigError, "#{File.basename(path)} parse error: #{e.message}"
end

.ignore_id_text(value) ⇒ String?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Text of one ignore id. An integer is the decimal digits YAML kept. A leading zero is already gone by then, so quote an id that needs one. Any other type is not an id.

Parameters:

  • value (Object) —

    a list item, a scalar ignore value, or a mapping id.

Returns:

  • (String, nil) —

    the id text, or nil when the value cannot be an id.



564
565
566
567
568
569
# File 'lib/mutineer/config.rb', line 564

def self.ignore_id_text(value)
  case value
  when String then value
  when Integer then value.to_s
  end
end

.ignore_mapping(item, number, label) ⇒ Array(String, String), Array(nil, nil)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

One ignore: mapping. Returns the id and reason, or nil when the entry is not usable.

Parameters:

  • item (Hash) —

    the mapping.

  • number (Integer) —

    1-based index in the list.

  • label (String) —

    config file name.

Returns:

  • (Array(String, String), Array(nil, nil))


579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
# File 'lib/mutineer/config.rb', line 579

def self.ignore_mapping(item, number, label)
  unknown = item.keys.map(&:to_s) - %w[id reason]
  unless unknown.empty?
    names = unknown.map(&:inspect).join(", ")
    warn "mutineer: ignore entry #{number} in #{label} has unknown key #{names}; " \
         "ignored, and #{BECOMES_ERROR_IN_2_0}"
    return [nil, nil]
  end

  id = ignore_id_text(item["id"] || item[:id])
  unless id.is_a?(String) && !id.strip.empty?
    warn "mutineer: ignore entry #{number} in #{label} has no id; ignored, and #{BECOMES_ERROR_IN_2_0}"
    return [nil, nil]
  end

  reason = item.key?("reason") ? item["reason"] : item[:reason]
  if !reason.nil? && !reason.is_a?(String)
    warn "mutineer: ignore entry #{number} in #{label} reason must be text; " \
         "ignored, and #{BECOMES_ERROR_IN_2_0}"
    return [nil, nil]
  end

  text = reason.to_s.strip
  [id, text.empty? ? nil : text]
end

.parse(field, value, file: nil, defer_operators: false) ⇒ Object

Parses one raw value into the typed value for field. A value that does not fit its type raises ConfigError naming where it came from, so the CLI and .mutineer.yml report the same mistake in the same way. nil and false are valid results for some fields (since: false means "no scoping").

Parameters:

  • field (Symbol) —

    Config field name (a row of the option schema).

  • value (Object) —

    raw CLI string or YAML value.

  • file (String, nil) (defaults to: nil) —

    config file name when the value came from it; nil when it came from the command line.

  • defer_operators (Boolean) (defaults to: false) —

    when true, a blank operator list is returned instead of raising, so --operators can replace it. The flag itself still rejects a blank list.

Returns:

  • (Object) —

    the typed value.

Raises:



338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
# File 'lib/mutineer/config.rb', line 338

def self.parse(field, value, file: nil, defer_operators: false)
  opt = CONFIG_OPTIONS.find { |o| o.field == field } or raise ArgumentError, "unknown option #{field.inspect}"
  origin = file ? "#{file}: #{opt.yaml_key}" : opt.flag
  got = "(got: #{value.inspect})"
  case opt.type
  when :positive_int
    n = value.is_a?(Integer) ? value : (value.to_i if value.is_a?(String) && value.match?(/\A\d+\z/))
    raise ConfigError, "#{origin} must be a positive integer, digits only #{got}" if n.nil? || n < 1

    n
  when :percent
    f = finite_float(value)
    raise ConfigError, "#{origin} must be a number between 0 and 100 #{got}" unless f && (0.0..100.0).cover?(f)

    f
  when :nonneg_float
    f = finite_float(value)
    raise ConfigError, "#{origin} must be a finite number, 0 or greater #{got}" unless f && f >= 0.0

    f
  when :bool
    return value if [true, false].include?(value)
    return value == "true" if %w[true false].include?(value)

    raise ConfigError, "#{origin} must be true or false #{got}"
  when :enum
    name = opt.aliases&.fetch(value, nil) || value
    return name if opt.values.include?(name)

    prefix = file ? "#{file}: " : ""
    raise ConfigError, "#{prefix}unknown #{field} #{value.to_s.inspect}. Expected: #{opt.values.join(', ')}"
  when :ignore_list
    parse_ignore_list(value, file)
  when :test_map
    parse_test_map(value, file)
  when :string_list
    items = Array(value).map(&:to_s)
    # Only `operators` treats [] as "run these" rather than "use the
    # default". A blank key then makes no mutants and exits 0. An empty
    # `require` or `ignore` matches the default, so those stay valid.
    if field == :operators && !defer_operators && ([nil, true, false].include?(value) || items.empty? || items.all? { |item| item.strip.empty? })
      raise ConfigError, "#{origin} must name at least one operator, not blank #{got}"
    end

    items
  when :string
    # A key written with no value (`baseline:`) parses as nil. Keeping nil
    # would switch the feature off without a word; main failed here, so the
    # typo stays loud. An absent key never reaches parse, so it stays unset.
    # `only: false` must not become the subject name "false" either: it
    # matches nothing, so the run has no mutants and still exits 0.
    raise ConfigError, "#{origin} must be a string #{got}" if [nil, true, false].include?(value)
    # A blank cache directory (an unset CI variable) would put coverage.json
    # in the project root, so it is an error, not the default.
    raise ConfigError, "#{origin} must be a directory, not blank #{got}" if field == :cache_dir && value.to_s.strip.empty?
    raise ConfigError, "#{origin} must be a file, not blank #{got}" if field == :coverage_from && value.to_s.strip.empty?

    value.to_s
  when :since
    # `false` is the one way to say "no scoping" in the file. It becomes nil
    # so every consumer's nil-check (runner scoping, the report's scoped
    # marker) agrees; a false left raw would skip scoping but still mark
    # the report scoped. A blank value is an error, not "no scoping": a
    # `since: "$REF"` whose variable is unset must not turn scoping off.
    return nil if value == false
    raise ConfigError, "#{origin} must be a git ref, not blank #{got}" if value.to_s.strip.empty?

    value.to_s
  end
end

.parse_ignore_list(value, file) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Reads an ignore: value into ids plus a reason for each mapping. A bare string or integer is an id with no reason. YAML reads an unquoted all-digit id as an integer, and the id text is those decimal digits. A mapping may hold id and reason only. A mapping with no id, or with any other key, is dropped and warned: 2.0 will reject it. Callers that match ids keep the id list.

Parameters:

  • value (Object) —

    the raw YAML value.

  • file (String, nil) —

    config file name.

Returns:

  • (Hash) —

    :ids is an array of id strings. :reasons maps an id to its text.



524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
# File 'lib/mutineer/config.rb', line 524

def self.parse_ignore_list(value, file)
  label = file || CONFIG_FILE
  case value
  when nil then return { ids: [], reasons: {} }
  when String, Integer then return { ids: [ignore_id_text(value)], reasons: {} }
  when Array then items = value
  when Hash then items = [value]
  else
    warn "mutineer: ignore in #{label} must be a list; ignored, and #{BECOMES_ERROR_IN_2_0}"
    return { ids: [], reasons: {} }
  end

  ids = []
  reasons = {}
  items.each_with_index do |item, index|
    number = index + 1
    id = ignore_id_text(item)
    if id
      ids << id unless id.empty? || ids.include?(id)
    elsif item.is_a?(Hash)
      mapped, reason = ignore_mapping(item, number, label)
      next if mapped.nil?

      ids << mapped unless ids.include?(mapped)
      reasons[mapped] = reason if reason
    else
      warn "mutineer: ignore entry #{number} in #{label} is not an id or a mapping; " \
           "ignored, and #{BECOMES_ERROR_IN_2_0}"
    end
  end
  { ids: ids, reasons: reasons }
end

.parse_test_map(value, file) ⇒ Array<Hash{Symbol => Array<String>}>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Reads a tests: map into checked entries. Each entry is a Hash with :sources and :tests arrays of relative pattern strings. A single string pattern becomes a one-element list. [] is valid (no map). Absolute paths, blank patterns, unknown keys, and non-mapping entries raise ConfigError naming the file and tests entry N.

Parameters:

  • value (Object) —

    the raw YAML value.

  • file (String, nil) —

    config file name.

Returns:

  • (Array<Hash{Symbol => Array<String>}>)

Raises:



436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
# File 'lib/mutineer/config.rb', line 436

def self.parse_test_map(value, file)
  label = file || CONFIG_FILE
  origin = "#{label}: tests"
  got = "(got: #{value.inspect})"
  unless value.is_a?(Array)
    raise ConfigError, "#{origin} must be a list of mappings with sources and tests #{got}"
  end

  value.each_with_index.map do |entry, index|
    number = index + 1
    entry_origin = "#{origin} entry #{number}"
    unless entry.is_a?(Hash)
      raise ConfigError, "#{entry_origin} must be a mapping with sources and tests " \
                         "(got: #{entry.inspect})"
    end

    keys = entry.keys.map(&:to_s)
    unknown = keys - %w[sources tests]
    unless unknown.empty?
      names = unknown.map(&:inspect).join(", ")
      raise ConfigError, "#{entry_origin} has unknown key #{names}"
    end
    raise ConfigError, "#{entry_origin} is missing sources" unless keys.include?("sources")
    raise ConfigError, "#{entry_origin} is missing tests" unless keys.include?("tests")

    sources = entry.key?("sources") ? entry["sources"] : entry[:sources]
    tests = entry.key?("tests") ? entry["tests"] : entry[:tests]
    {
      sources: parse_test_map_patterns(sources, entry_origin, "sources"),
      tests: parse_test_map_patterns(tests, entry_origin, "tests")
    }
  end
end

.parse_test_map_patterns(value, entry_origin, key) ⇒ Array<String>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Turns one sources or tests value into a non-empty list of relative pattern strings. A bare string becomes a one-element list.

Parameters:

  • value (Object) —

    raw YAML value for the key.

  • entry_origin (String) —

    file: tests entry N prefix for errors.

  • key (String) —

    "sources" or "tests".

Returns:

  • (Array<String>)

Raises:



479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
# File 'lib/mutineer/config.rb', line 479

def self.parse_test_map_patterns(value, entry_origin, key)
  patterns = case value
             when String then [value]
             when Array then value
             else
               raise ConfigError, "#{entry_origin} #{key} must be a pattern or a list of " \
                                  "patterns (got: #{value.inspect})"
             end
  raise ConfigError, "#{entry_origin} #{key} must not be empty" if patterns.empty?

  patterns.map do |pattern|
    unless pattern.is_a?(String)
      raise ConfigError, "#{entry_origin} #{key} pattern must be a string " \
                         "(got: #{pattern.inspect})"
    end
    if pattern.strip.empty?
      raise ConfigError, "#{entry_origin} #{key} pattern must not be blank " \
                         "(got: #{pattern.inspect})"
    end
    if File.absolute_path?(pattern)
      raise ConfigError, "#{entry_origin} #{key} pattern must be relative, not absolute " \
                         "(got: #{pattern.inspect})"
    end
    # Patterns resolve against the run directory. A `..` segment can leave
    # that root, so reject it here the same way absolute paths are rejected.
    if pattern.split(%r{[/\\]}).include?("..")
      raise ConfigError, "#{entry_origin} #{key} pattern must stay under the run directory " \
                         "(got: #{pattern.inspect})"
    end

    pattern
  end
end

.resolve(cli_opts, file_hash) ⇒ Mutineer::Config

Merges the two user layers, CLI over file, then derives what neither wrote. A layer is a Hash of only the keys the user set, so precedence is merge and "did the user write this" is whether the key exists. Nothing tracks provenance by hand, and false/nil are ordinary values.

Parameters:

  • cli_opts (Hash{Symbol => Object}) —

    parsed command-line fields.

  • file_hash (Hash{Symbol => Object}) —

    parsed .mutineer.yml fields.

Returns:



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
# File 'lib/mutineer/config.rb', line 255

def self.resolve(cli_opts, file_hash)
  user = file_hash.merge(cli_opts)
  config = new(**user, explicit: user.keys, from_file: file_hash.keys - cli_opts.keys)

  # --rails sugar: boot config/environment. Prefer redefine only for the
  # in-process path (daemon is whole-file reload only). In-process --rails
  # shares one test database, so force serial unless --daemon.
  if config.rails
    config.boot ||= "config/environment"
    unless config.daemon || config.explicit?(:strategy)
      config.strategy = "redefine"
    end
    unless config.daemon
      # A typed --no-daemon already chose the serial run; only an explicit
      # --jobs N still needs telling that --daemon is the way to get N.
      if config.jobs.to_i > 1 && (!config.explicit?(:daemon) || config.explicit?(:jobs))
        warn "[mutineer] --rails without --daemon runs serially (shared test DB); " \
             "forcing --jobs 1. Use --daemon for safe --jobs N."
      end
      config.jobs = 1
    end
  end

  # Auto-detect the framework only when the user wrote none: a value from
  # either layer is already on config.framework and always wins. Default
  # minitest unless the test files clearly look RSpec.
  config.framework ||= detect_framework(config.tests)
  config
end

.warn_rails_default_change(config) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Mutineer 2.0 makes the daemon the default under --rails for Minitest, so a run that would change says so now. The CLI calls this after test pairing, which can still switch the framework to rspec. The runs that 2.0 keeps on this path stay quiet: RSpec, --test-command, --matrix and --fail-fast cannot use the daemon, a --dry-run runs no tests, and a written daemon value (true or false) is the user's choice.

Parameters:



295
296
297
298
299
300
301
# File 'lib/mutineer/config.rb', line 295

def self.warn_rails_default_change(config)
  return unless config.rails && !config.explicit?(:daemon) && config.framework == "minitest"
  return if config.test_command || config.matrix || config.fail_fast || config.dry_run

  warn "[mutineer] in Mutineer 2.0, --rails uses --daemon by default: parallel workers (unless " \
       "--jobs 1) and the reload strategy. Pass --no-daemon (or daemon: false) to keep this run as it is."
end

Instance Method Details

#explicit?(key) ⇒ Boolean

True when the user wrote key, on the command line or in the config file, whatever the value (false and nil count). The answer comes from which keys the layers held, so a new option needs no bookkeeping to be covered.

Parameters:

  • key (Symbol) —

    Config field name.

Returns:

  • (Boolean)


165
166
167
# File 'lib/mutineer/config.rb', line 165

def explicit?(key)
  @explicit.include?(key)
end

#origin(key) ⇒ String

Where the user set key, for messages: the config-file key (as name in .mutineer.yml) when its value came from the file, else the command-line flag.

Parameters:

  • key (Symbol) —

    Config field name (a row of the option schema).

Returns:

  • (String) —

    e.g. "--fail-fast" or "fail_fast in .mutineer.yml".



175
176
177
178
# File 'lib/mutineer/config.rb', line 175

def origin(key)
  opt = CONFIG_OPTIONS.find { |o| o.field == key } or raise ArgumentError, "unknown option #{key.inspect}"
  @from_file.include?(key) && opt.yaml_key ? "#{opt.yaml_key} in #{CONFIG_FILE}" : (opt.flag || opt.yaml_key)
end