mutineer 1.2.0 → 1.4.0

data/lib/mutineer/cli.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "optparse"
-require "set"
 require "open3"
 require_relative "version"
 require_relative "config"
@@ -67,19 +66,14 @@ module Mutineer
         --help            Print this help and exit
     USAGE
 
-    # Field symbols whose config-file value is suppressed when the flag is typed.
-    PRECEDENCE_FLAGS = %i[operators jobs threshold only].freeze
-
-    # Deprecated internal strategy names, mapped to their canonical equivalents.
-    STRATEGY_ALIASES = { "7a" => "reload", "7b" => "redefine" }.freeze
-
     # Parses arguments, executes the command, and exits.
     #
     # @param argv [Array<String>] raw command-line arguments.
     # @return [void]
     def self.start(argv)
-      opts = {}            # symbol => value, the CLI-provided Config fields
-      explicit = Set.new   # precedence keys the user typed
+      # The CLI layer holds only the fields the user typed, so Config.resolve
+      # can tell a typed `false`/`nil` from an absent flag by whether the key exists.
+      opts = {}
       show_operators = false
 
       parser = OptionParser.new do |o|
@@ -94,47 +88,40 @@ module Mutineer
         end
         o.on("--list-operators") { show_operators = true }
         o.on("--dry-run") { opts[:dry_run] = true }
-        o.on("--fail-fast") { opts[:fail_fast] = true; explicit << :fail_fast }
-        o.on("--only NAME") { |v| opts[:only] = v; explicit << :only }
-        o.on("--since REF") { |v| opts[:since] = v; explicit << :since }
-        # A typed "no" must beat a .mutineer.yml `since:` key (CLI-over-config
-        # precedence): marking :since explicit with a nil value blocks the fill.
-        o.on("--no-since") { opts[:since] = nil; explicit << :since }
+        o.on("--fail-fast") { opts[:fail_fast] = true }
+        o.on("--only NAME") { |v| opts[:only] = v }
+        o.on("--since REF") { |v| opts[:since] = Config.parse(:since, v) }
+        # A typed "no" must beat a .mutineer.yml `since:` key: the key is present
+        # with a nil value, and nil is a value.
+        o.on("--no-since") { opts[:since] = nil }
         o.on("--test FILE") { |v| (opts[:tests] ||= []) << v }
-        o.on("--operators LIST") { |v| opts[:operators] = v.split(",").map(&:strip); explicit << :operators }
-        o.on("--threshold FLOAT") do |v|
-          f = Float(v, exception: false)
-          if f.nil?
-            warn "mutineer: --threshold requires a number between 0 and 100 (got: #{v.inspect})"
-            exit 2
-          end
-          opts[:threshold] = f
-          explicit << :threshold
+        o.on("--operators LIST") do |v|
+          opts[:operators] = Config.parse(:operators, v.split(",").map(&:strip))
         end
-        o.on("--jobs N") { |v| opts[:jobs] = v; explicit << :jobs }
-        o.on("--strategy STRAT") { |v| opts[:strategy] = v; explicit << :strategy }
-        o.on("--framework NAME") { |v| opts[:framework] = v; explicit << :framework }
-        o.on("--boot FILE") { |v| opts[:boot] = v; explicit << :boot }
+        o.on("--threshold FLOAT") { |v| opts[:threshold] = Config.parse(:threshold, v) }
+        o.on("--jobs N") { |v| opts[:jobs] = Config.parse(:jobs, v) }
+        o.on("--strategy STRAT") { |v| opts[:strategy] = Config.parse(:strategy, v) }
+        o.on("--framework NAME") { |v| opts[:framework] = Config.parse(:framework, v) }
+        o.on("--boot FILE") { |v| opts[:boot] = v }
         o.on("--rails") { opts[:rails] = true }
         o.on("--verbose") { opts[:verbose] = true }
         o.on("--debug") { opts[:verbose] = true } # alias of --verbose
-        o.on("--format FORMAT") { |v| opts[:format] = v }
+        o.on("--format FORMAT") { |v| opts[:format] = Config.parse(:format, v) }
         o.on("--output FILE") { |v| opts[:output] = v }
-        # --baseline is also a .mutineer.yml key, so mark it explicit when typed
-        # (CLI wins over the file). --baseline-epsilon is CLI-only.
-        o.on("--baseline FILE") { |v| opts[:baseline] = v; explicit << :baseline }
-        o.on("--baseline-epsilon FLOAT") { |v| opts[:baseline_epsilon] = v.to_f }
+        # --baseline-epsilon is CLI-only.
+        o.on("--baseline FILE") { |v| opts[:baseline] = v }
+        o.on("--baseline-epsilon FLOAT") { |v| opts[:baseline_epsilon] = Config.parse(:baseline_epsilon, v) }
         # Run the target suite as a subprocess in the app's OWN runtime so
         # mutineer (Ruby >= 3.4) can mutation-test apps pinned to an older Ruby.
-        o.on("--test-command CMD") { |v| opts[:test_command] = v; explicit << :test_command }
+        o.on("--test-command CMD") { |v| opts[:test_command] = v }
         # Boot the app ONCE in a persistent daemon and fork per mutant, with
         # per-worker DB isolation so --jobs N is safe under Rails.
-        o.on("--daemon") { opts[:daemon] = true; explicit << :daemon }
+        o.on("--daemon") { opts[:daemon] = true }
       end
 
       begin
         parser.parse!(argv)
-      rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+      rescue OptionParser::InvalidOption, OptionParser::MissingArgument, Mutineer::ConfigError => e
         warn "mutineer: #{e.message}"
         exit 2
       end
@@ -152,7 +139,7 @@ module Mutineer
       begin
         file_path = Config.find_file
         file_hash = file_path ? Config.from_file(file_path) : {}
-        config = Config.resolve(opts, file_hash, explicit)
+        config = Config.resolve(opts, file_hash)
       rescue Mutineer::ConfigError => e
         # The lib layer raises instead of killing the host; the CLI maps a
         # config (usage) error to exit 2.
@@ -162,10 +149,11 @@ module Mutineer
 
       case argv.first
       when "run"
+        warn_config_root_mismatch(file_path, config.project_root) if file_path
         # A directory source expands to its **/*.rb files; literal files pass
         # through. Test inference (when --test is omitted) happens in validate!.
         config.sources = Pairing.expand_sources(argv[1..], project_root: config.project_root)
-        run(config, explicit)
+        run(config)
       else
         warn "mutineer: unknown command '#{argv.first}'"
         exit 2
@@ -186,14 +174,13 @@ module Mutineer
     # Runs the requested command after validation.
     #
     # @param config [Mutineer::Config] run configuration.
-    # @param explicit [Set<Symbol>] explicit CLI fields.
     # @return [void]
-    def self.run(config, explicit = Set.new)
+    def self.run(config)
       if config.sources.empty?
         warn "mutineer: run requires at least one source file"
         exit 2
       end
-      validate!(config, explicit)
+      validate!(config)
 
       config.dry_run ? dry_run(config) : execute(config)
     rescue ArgumentError => e
@@ -235,39 +222,8 @@ module Mutineer
     #
     # @api private
     # @param config [Mutineer::Config] run configuration.
-    # @param explicit [Set<Symbol>] explicit CLI fields.
     # @return [void]
-    def self.validate!(config, explicit = Set.new)
-      unless (0.0..100.0).cover?(config.threshold)
-        warn "mutineer: --threshold must be between 0 and 100"
-        exit 2
-      end
-
-      jobs = Integer(config.jobs.to_s, exception: false)
-      if jobs.nil? || jobs < 1
-        warn "mutineer: --jobs requires a positive integer (got: #{config.jobs})"
-        exit 2
-      end
-      config.jobs = jobs
-
-      unless %w[human json html].include?(config.format)
-        warn %(mutineer: unknown format "#{config.format}". Expected: human, json, html)
-        exit 2
-      end
-
-      # Canonical strategies are reload|redefine; 7a/7b are accepted as deprecated
-      # aliases. Normalize to canonical so the rest of the pipeline sees one name.
-      config.strategy = STRATEGY_ALIASES.fetch(config.strategy, config.strategy)
-      unless %w[reload redefine].include?(config.strategy)
-        warn %(mutineer: unknown strategy "#{config.strategy}". Expected: reload, redefine)
-        exit 2
-      end
-
-      unless %w[minitest rspec].include?(config.framework)
-        warn %(mutineer: unknown framework "#{config.framework}". Expected: minitest, rspec)
-        exit 2
-      end
-
+    def self.validate!(config)
       validate_test_command!(config) if config.test_command
 
       validate_since!(config) if config.since
@@ -276,7 +232,7 @@ module Mutineer
 
       # When --test is omitted, infer each source's test by convention. Autopair
       # also re-detects framework from inferred tests when --framework was not set.
-      autopair!(config, explicit) unless config.dry_run
+      autopair!(config) unless config.dry_run
 
       # Daemon validation runs AFTER autopair so auto-inferred *_spec.rb tests
       # cannot bypass the RSpec rejection (framework would still be minitest if we
@@ -407,9 +363,8 @@ module Mutineer
     #
     # @api private
     # @param config [Mutineer::Config] run configuration.
-    # @param explicit [Set<Symbol>] explicit CLI fields.
     # @return [void]
-    def self.autopair!(config, explicit)
+    def self.autopair!(config)
       return unless config.tests.empty?
 
       paired = config.sources.filter_map do |s|
@@ -421,7 +376,7 @@ module Mutineer
       end
       config.sources = paired.map(&:first)
       config.tests   = paired.map(&:last).uniq
-      config.framework = Config.detect_framework(config.tests) unless explicit.include?(:framework)
+      config.framework = Config.detect_framework(config.tests) unless config.explicit?(:framework)
 
       return unless config.sources.empty?
       return if config.boot # let the --boot/--rails-requires-test check report it
@@ -469,7 +424,8 @@ module Mutineer
         exit 2
       end
 
-      aggregate, source_map = Runner.execute(config)
+      aggregate, source_map, extras = Runner.execute(config)
+      warn_legacy_ignore_matches(extras[:legacy_ignore_matches])
       reporter = Reporter.new(aggregate, source_map)
 
       # Diff the current run against the baseline (preflighted above) by the
@@ -479,12 +435,18 @@ module Mutineer
       # so only the new-survivor half of the gate applies (see Baseline#diff).
       delta = if config.baseline
                 Baseline.load(config.baseline).diff(aggregate, epsilon: config.baseline_epsilon,
-                                                               scoped: !config.since.nil?)
+                                                               scoped: !config.since.nil?,
+                                                               id_map: extras[:id_map],
+                                                               project_root: config.project_root)
               end
+      warn_legacy_baseline if delta&.legacy_matches&.positive?
 
+      # ignore counts old-format entries (one warning each), not the ids they matched.
+      legacy_id_matches = { ignore: extras[:legacy_ignore_matches].size,
+                            baseline: delta ? delta.legacy_matches : 0 }
       reporter.report(out: $stdout, err: $stderr, threshold: config.threshold,
                       format: config.format, output: config.output, baseline: delta,
-                      scoped: !config.since.nil?)
+                      scoped: !config.since.nil?, legacy_id_matches: legacy_id_matches)
 
       # Warn (stderr, so it never pollutes json/html) that an external run's score
       # is not comparable to an in-process run: no coverage narrowing (uncovered
@@ -523,6 +485,64 @@ module Mutineer
         "enable with --operators <list>."
     end
 
+    # Warns once when the loaded .mutineer.yml sits outside the run directory
+    # (#126). Mutant ids hash each file's path relative to the run directory,
+    # but the config is found by walking up, so a run from a subdirectory loads
+    # the same ignore list while its ids no longer match. A config in the home
+    # directory is a personal default, not a project root, so it never warns.
+    #
+    # @param file_path [String] the .mutineer.yml that was loaded.
+    # @param project_root [String] the run directory ids are relative to.
+    # @return [void]
+    def self.warn_config_root_mismatch(file_path, project_root)
+      config_dir = ProjectPath.root_real(File.dirname(file_path))
+      return if config_dir == ProjectPath.root_real(project_root)
+      return if config_dir == ProjectPath.root_real(Dir.home)
+
+      warn "[mutineer] loaded #{file_path}, but mutant ids are relative to the run directory " \
+           "#{project_root}, not to #{config_dir}. Ignore ids and baselines written from " \
+           "#{config_dir} will not match this run. Run mutineer from #{config_dir}."
+    end
+
+    # Warns once per old-format `ignore:` entry (#126), naming each new id it
+    # matched with that mutant's file and subject. mutineer cannot tell a full
+    # run from a narrowed one, so the text always says the list covers only this
+    # run's mutants. An entry that matched more than one distinct mutant (in
+    # other files, or same-named methods in one file) over-matched: the old id
+    # could not tell them apart, so replacing it with every new id would keep
+    # suppressing the mutants it hid by accident.
+    #
+    # @param matches [Hash{String => Array<Hash{Symbol => String}>}] old-format
+    #   entry => one `{id:, file:, subject:}` hash per matched mutant.
+    # @return [void]
+    def self.warn_legacy_ignore_matches(matches)
+      matches.each do |old, hits|
+        listed = hits.map { |h| "#{h[:id]} (#{h[:file]}, #{h[:subject]})" }.join(", ")
+        advice = if hits.map { |h| h[:id] }.uniq.size > 1
+                   "#{old} over-matched: the old format could not tell these mutants apart. " \
+                     "Replace #{old} and keep only the ids for the mutant you meant to ignore, not all of them."
+                 else
+                   "Replace #{old} with the new ids in your ignore list."
+                 end
+        warn "[mutineer] ignore entry #{old} uses the old id format, which did not include the " \
+             "file path. It matched these new ids: #{listed}. This list covers only mutants in " \
+             "this run's sources and operators; a run over every source gives the complete " \
+             "replacement. #{advice}"
+      end
+    end
+
+    # Warns once that the --baseline file stores old-format ids (#126), so the
+    # diff fell back to matching on them. Called only when a survivor matched
+    # through an old id alone.
+    #
+    # @return [void]
+    def self.warn_legacy_baseline
+      warn "[mutineer] the baseline uses the old id format, which did not include the file " \
+           "path, so survivors were matched on their old ids and files. Regenerate the baseline " \
+           "(run with --format json and save the output), but only after every gate that reads " \
+           "it runs this mutineer version or later."
+    end
+
     # Runs dry-run mode. Reuses Runner.collect_jobs (+ filter_since) so the
     # candidate list cannot drift from a real run's job selection.
     #
@@ -530,7 +550,8 @@ module Mutineer
     # @return [void]
     def self.dry_run(config)
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
-      jobs, ignored_results, source_map = Runner.collect_jobs(config, operator_classes)
+      jobs, ignored_results, source_map, extras = Runner.collect_jobs(config, operator_classes)
+      warn_legacy_ignore_matches(extras[:legacy_ignore_matches])
       # Narrow jobs and ignored the same way so the summary matches the printed list.
       if config.since
         jobs = Runner.filter_since(jobs, source_map, config)

data/lib/mutineer/config.rb

@@ -8,13 +8,55 @@ module Mutineer
   # never kill the host process. The CLI rescues this and maps it to exit 2.
   class ConfigError < StandardError; end
 
+  # One row of the option schema: how a Config field is parsed and where the
+  # user can set it. `yaml_key` is nil for CLI-only options; `flag` is nil for
+  # YAML-only ones. `values`/`aliases` apply to the :enum type.
+  #
+  # @api private
+  ConfigOption = Struct.new(:field, :type, :yaml_key, :flag, :values, :aliases, keyword_init: true)
+
+  # Deprecated internal strategy names, mapped to their canonical equivalents.
+  STRATEGY_ALIASES = { "7a" => "reload", "7b" => "redefine" }.freeze
+
+  # The option schema. Config.parse is the only place that turns a raw value
+  # (a CLI string or a YAML scalar) into a typed one, so a value is checked once,
+  # at the boundary, whichever layer wrote it. Row order fixes the order of
+  # KNOWN_KEYS in warnings.
+  #
+  # @api private
+  CONFIG_OPTIONS = [
+    ConfigOption.new(field: :operators, type: :string_list, yaml_key: "operators", flag: "--operators"),
+    ConfigOption.new(field: :jobs, type: :positive_int, yaml_key: "jobs", flag: "--jobs"),
+    ConfigOption.new(field: :threshold, type: :percent, yaml_key: "threshold", flag: "--threshold"),
+    ConfigOption.new(field: :only, type: :string, yaml_key: "only", flag: "--only"),
+    ConfigOption.new(field: :require_paths, type: :string_list, yaml_key: "require"),
+    ConfigOption.new(field: :boot, type: :string, yaml_key: "boot", flag: "--boot"),
+    ConfigOption.new(field: :rails, type: :bool, yaml_key: "rails", flag: "--rails"),
+    ConfigOption.new(field: :since, type: :since, yaml_key: "since", flag: "--since"),
+    ConfigOption.new(field: :framework, type: :enum, yaml_key: "framework", flag: "--framework",
+                     values: %w[minitest rspec]),
+    ConfigOption.new(field: :verbose, type: :bool, yaml_key: "verbose", flag: "--verbose"),
+    ConfigOption.new(field: :ignore, type: :string_list, yaml_key: "ignore"),
+    ConfigOption.new(field: :baseline, type: :string, yaml_key: "baseline", flag: "--baseline"),
+    ConfigOption.new(field: :fail_fast, type: :bool, yaml_key: "fail_fast", flag: "--fail-fast"),
+    ConfigOption.new(field: :test_command, type: :string, yaml_key: "test_command", flag: "--test-command"),
+    ConfigOption.new(field: :daemon, type: :bool, yaml_key: "daemon", flag: "--daemon"),
+    ConfigOption.new(field: :format, type: :enum, flag: "--format", values: %w[human json html]),
+    ConfigOption.new(field: :strategy, type: :enum, flag: "--strategy", values: %w[reload redefine],
+                     aliases: STRATEGY_ALIASES),
+    ConfigOption.new(field: :output, type: :string, flag: "--output"),
+    ConfigOption.new(field: :baseline_epsilon, type: :nonneg_float, flag: "--baseline-epsilon"),
+    ConfigOption.new(field: :dry_run, type: :bool, flag: "--dry-run")
+  ].freeze
+
   # 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.
+  # 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.
   #
   # 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)
@@ -33,11 +75,15 @@ module Mutineer
   ) do
     # Config file name.
     CONFIG_FILE = ".mutineer.yml"
-    # Keys accepted in .mutineer.yml. `require` maps to the :require_paths field.
-    KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework verbose ignore baseline fail_fast test_command daemon].freeze
+    # Keys accepted in .mutineer.yml, derived from the schema. `require` maps to the
+    # :require_paths field.
+    KNOWN_KEYS = CONFIG_OPTIONS.filter_map(&:yaml_key).freeze
 
-    def initialize(**kwargs)
-      super
+    # @param explicit [Array<Symbol>] fields the user wrote (CLI or file). Derived
+    #   values fill only the others; a programmatic Config.new writes none.
+    def initialize(explicit: [], **kwargs)
+      super(**kwargs)
+      @explicit = explicit.to_a.dup.freeze
       self.sources       ||= []
       self.tests         ||= []
       self.threshold     ||= 0.0
@@ -57,6 +103,17 @@ module Mutineer
       self.daemon        = false if daemon.nil?
     end
 
+    # 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.
+    #
+    # @param key [Symbol] Config field name.
+    # @return [Boolean]
+    def explicit?(key)
+      @explicit.include?(key)
+    end
+
     # 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;
@@ -96,28 +153,34 @@ module Mutineer
                "(known: #{KNOWN_KEYS.join(', ')}); ignored"
           next
         end
-        out[field_for(ks)] = coerce(ks, value, name)
+        field = field_for(ks)
+        parsed = parse(field, value, file: name)
+        parsed = filter_operators(parsed, name) if field == :operators
+        out[field] = parsed
       end
       out
     rescue Psych::SyntaxError => e
       raise ConfigError, "#{File.basename(path)} parse error: #{e.message}"
     end
 
-    # Apply precedence: start from the CLI-provided values, then fill in a
-    # config-file value only for keys the user did NOT type on the command line.
-    # `explicit` is a Set of field symbols the CLI saw with a value; a Set (not
-    # nil-sentinels) is used because some valid values are zero/false.
-    def self.resolve(cli_opts, file_hash, explicit)
-      merged = cli_opts.dup
-      file_hash.each { |k, v| merged[k] = v unless explicit.include?(k) }
-      config = new(**merged)
+    # 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.
+    #
+    # @param cli_opts [Hash{Symbol => Object}] parsed command-line fields.
+    # @param file_hash [Hash{Symbol => Object}] parsed .mutineer.yml fields.
+    # @return [Mutineer::Config]
+    def self.resolve(cli_opts, file_hash)
+      user = file_hash.merge(cli_opts)
+      config = new(**user, explicit: user.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 || explicit.include?(:strategy)
+        unless config.daemon || config.explicit?(:strategy)
           config.strategy = "redefine"
         end
         unless config.daemon
@@ -129,9 +192,9 @@ module Mutineer
         end
       end
 
-      # Auto-detect the framework only when neither CLI nor config file set it
-      # (explicit value, from either source, is already on config.framework and
-      # always wins). Default minitest unless the test files clearly look RSpec.
+      # 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
@@ -155,42 +218,87 @@ module Mutineer
       known_key == "require" ? :require_paths : known_key.to_sym
     end
 
-    # Coerces a config value to its target type.
+    # 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").
     #
-    # @param known_key [String] config key.
-    # @param value [Object] raw YAML value.
-    # @param file_name [String] config file name for warnings.
-    # @return [Object] coerced value.
-    def self.coerce(known_key, value, file_name)
-      case known_key
-      when "operators" then filter_operators(Array(value).map(&:to_s), file_name)
-      when "jobs"      then value.to_i
-      when "threshold"
-        f = Float(value, exception: false)
-        if f.nil?
-          raise ConfigError, "#{file_name}: threshold must be a number between 0 and 100 " \
-                             "(got: #{value.inspect})"
-        end
+    # @param field [Symbol] Config field name (a row of the option schema).
+    # @param value [Object] raw CLI string or YAML value.
+    # @param file [String, nil] config file name when the value came from it;
+    #   nil when it came from the command line.
+    # @return [Object] the typed value.
+    # @raise [Mutineer::ConfigError] when the value does not fit the field's type.
+    def self.parse(field, value, file: nil)
+      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 "require"   then Array(value).map(&:to_s)
-      when "boot"      then value.to_s
-      when "framework" then value.to_s
-      when "rails"     then value == true || value.to_s == "true"
-      when "daemon"    then value == true || value.to_s == "true"
-      when "verbose"   then value == true || value.to_s == "true"
-      when "fail_fast" then value == true || value.to_s == "true"
-      when "ignore"    then Array(value).map(&:to_s)
-      when "baseline"  then value.to_s
-      when "test_command" then value.to_s
-      when "since"
-        # false / empty normalize to nil ("no scoping"), 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.
-        value == false || value.to_s.empty? ? nil : value.to_s
-      else value
+      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 :string_list then Array(value).map(&:to_s)
+      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)
+
+        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
 
+    # 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`.
+    #
+    # @api private
+    # @param value [Object] raw value.
+    # @return [Float, nil] the number, or nil when it is not a finite number.
+    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
+
     # 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.

data/lib/mutineer/coverage_map.rb

@@ -9,6 +9,7 @@ require "set"
 require_relative "minitest_integration"
 require_relative "test_runners"
 require_relative "child_stdout"
+require_relative "project_path"
 
 module Mutineer
   # Maps `(source_file, line) -> [test_files]` so each mutant runs only against
@@ -722,11 +723,7 @@ module Mutineer
     #
     # @api private
     # @return [String] realpath of the project root when it exists.
-    def project_root_real
-      File.realpath(File.expand_path(@project_root))
-    rescue Errno::ENOENT
-      File.expand_path(@project_root)
-    end
+    def project_root_real = ProjectPath.root_real(@project_root)
 
     # Project-local `.rb` files loaded in this process at capture time.
     #
@@ -907,38 +904,18 @@ module Mutineer
     # @return [Array<String>] absolute load paths.
     def abs_load_paths   = @load_paths.map { |p| absolute(p) }
 
-    # Relativizes a path against the project root.
+    # Relativizes a path against the project root (see {ProjectPath.relative}).
     #
     # @api private
     # @param path [String] path to relativize.
-    # @return [String] relative path.
-    def relativize(path)
-      abs = path.start_with?("/") ? path : absolute(path)
-      abs = realpath_if_exists(abs)
-      root = project_root_real
-      prefix = root.end_with?("/") ? root : "#{root}/"
-      return abs unless abs.start_with?(prefix)
-
-      abs.delete_prefix(prefix)
-    end
+    # @return [String] relative path, or an absolute path when outside the root.
+    def relativize(path) = ProjectPath.relative(path, @project_root)
 
-    # Expands a path relative to the project root.
+    # Expands a path relative to the project root (see {ProjectPath.absolute}).
     #
     # @api private
     # @param path [String] path to expand.
     # @return [String] absolute path.
-    def absolute(path)
-      raw = File.absolute_path?(path) ? path : File.expand_path(path, @project_root)
-      realpath_if_exists(raw)
-    end
-
-    # Real path when the file exists, otherwise `path` unchanged.
-    #
-    # @api private
-    # @param path [String] absolute or relative path.
-    # @return [String]
-    def realpath_if_exists(path)
-      File.exist?(path) ? File.realpath(path) : path
-    end
+    def absolute(path) = ProjectPath.absolute(path, @project_root)
   end
 end