mutineer 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7b8a623ac7db818d33df11a7ca32e26a67db7f156061027f018debeb17ced2f
-  data.tar.gz: 5957fb6e57cb5a5149822818f773f3e8d3da271bce7bb0cfc4d0a8640764aa40
+  metadata.gz: e18649829a9226ea7a5f654ef38602eabff4005ebf8a516fca4402460a7aac09
+  data.tar.gz: 9e3c166e5e2e513278aaf210f271ed0f070cd335d0de588318cb8aa71f6b6a06
 SHA512:
-  metadata.gz: 1de2a131774b7b587abbc8ca91a57da333688cb2fdb937defa002d661426137decf8b86fbde1a2d176a5525f8cb7d9a8b6a2bebc353960729704b3e8d2473213
-  data.tar.gz: '094d062c4c8458fda7061a575681f13022131b2b9078e5731bcbbfa300ac67b86e53691e4d9e104cc06e50832b66bd3dd32433c1bdf420e74b75a7b7748b4916'
+  metadata.gz: 2e10e1214d0b55a4c93c7fa13d4c3b39503d4e2b1e367a995e2d813e98bd55ce2c2774b429bd690f2ae55019a39c7ee539e3ef60ea51bf25e2bc61c602ab72b6
+  data.tar.gz: 146768f9f599d41af9e6549f65ad7658cdd55e3d57a6f35fa6d094cfef6be73b036bb3dc8ebe8616d03cf358cdaf78e5d8a3b40a996c7a4d18a06898b9454824

data/CHANGELOG.md

@@ -6,6 +6,72 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-09-30
+
+### Added
+- **Condition-forcing operators** (Tier-2, opt-in via `--operators`):
+  `condition_true` and `condition_false` replace an `if`/`elsif`/`unless`,
+  ternary, modifier or `case`/`in` guard condition with `(true)` or `(false)`, so
+  its branch always runs or never runs. A surviving mutant means no selected
+  test detected the forced condition. A literal condition, also in
+  parentheses, makes no mutant: forcing it changes nothing or repeats the
+  `boolean_literal` flip. A condition that holds a heredoc makes no mutant.
+  A condition that assigns a variable keeps its code, and only its value
+  is forced (`(m = x; true)`), so later code still sees the variable.
+  The never-runs side of an else-less conditional can
+  be the same program as the `nil` that `statement_removal` or `return_nil`
+  puts in its place; it is still made, so these mutants and their ids do not
+  depend on which other operators run.
+- **Operator-assignment operator** (Tier-2, opt-in via `--operators`):
+  `operator_assignment` swaps the operator of a compound assignment:
+  `+=` <-> `-=`, `*=` <-> `/=`, and `%=` and `**=` -> `*=`. It covers local,
+  instance, class and global variables, constants, calls (`a.b += 1`) and
+  index calls (`a[i] += 1`). The `arithmetic` operator never sees these
+  forms, because Prism does not parse them as calls. The operator does not
+  change `||=`, `&&=`, or the bitwise and shift forms (`|=`, `<<=`).
+
+### Fixed
+- **A typed `--rails`, `--verbose` or `--debug` beats `rails: false` and
+  `verbose: false` in `.mutineer.yml`** (#103). The flag was dropped, so the
+  run went on without Rails boot or verbose output. The config layers now keep
+  only the keys the user wrote, and "did the user write this" comes from those
+  keys, not from a hand-kept list.
+- **`framework: rspec` in `.mutineer.yml` survives test pairing** (#103).
+  Pairing re-detected the framework from the test file names, so an RSpec
+  suite in `test/calc_test.rb` ran under Minitest.
+- **A bad number is an error, not a rounded value** (#105). `--jobs 1.9` and
+  `--baseline-epsilon abc` no longer become `1` and `0.0`. One option schema
+  parses each value once, where it enters, for both the command line and
+  `.mutineer.yml`.
+- **`--since` keeps a source file that git does not track yet** (#156). Before,
+  such a file counted as unchanged. The run scored no mutants, and a positive
+  `--threshold` still exited 0. The file is now new in full, so all its
+  mutants run.
+
+### Changed
+- **These now exit 2 with a message that names the option**: `jobs: 1.9` or
+  `jobs: true` in `.mutineer.yml` (before: `1`, or a crash); a bad, negative
+  or non-finite `--baseline-epsilon` (before: `0.0`); a boolean key in
+  `.mutineer.yml` that is not `true` or `false`, such as the string `"yes"`
+  (before: `false`).
+- **`--jobs` takes plain digits only.** `0x2`, `+2`, `" 2"` and `1_0` exit 2.
+  Before, `Integer()` read them as 2, 2, 2 and 10. `--threshold` and
+  `--baseline-epsilon` take a plain decimal, such as `2` or `2.5`, from a
+  string. `0x10`, `+2`, `1_0` and `1e2` exit 2. Before, `Float()` read them
+  as 16.0, 2.0, 10.0 and 100.0.
+- **A string option that gets `true`, `false` or no value exits 2**, such as
+  `only: false` or `baseline:` in `.mutineer.yml`. A blank `since` also exits 2,
+  in the file and on the command line, so an unset shell variable does not
+  turn scoping off. `since: false` still means no scoping.
+- **Config file errors start with the file and key**, for example
+  `.mutineer.yml: threshold must be a number between 0 and 100`, where they
+  started with `--threshold`.
+- **The docs site is built in CI** — a Pages workflow runs `rake site:build`
+  and deploys the result, so the YARD HTML under `/api/`, `llms-full.txt`,
+  `json-schema.html` and `sitemap.xml` are no longer committed. CI checks
+  that the site builds, in place of `rake yard:pages:check`. The site keeps
+  its URLs (#153).
+
 ## [1.3.0] - 2026-09-29
 
 ### Changed
@@ -611,6 +677,7 @@ Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[1.4.0]: https://github.com/davidteren/mutineer/releases/tag/v1.4.0
 [1.3.0]: https://github.com/davidteren/mutineer/releases/tag/v1.3.0
 [1.2.0]: https://github.com/davidteren/mutineer/releases/tag/v1.2.0
 [1.1.0]: https://github.com/davidteren/mutineer/releases/tag/v1.1.0

data/README.md

@@ -85,7 +85,8 @@ Run `mutineer --list-operators` to see them. Default (Tier 1): `arithmetic`,
 Available but off by default (Tier 2, enable via `--operators`): `return_nil`,
 `literal_mutation`, `condition_negation`, `string_literal`, `regex`,
 `collection_method`, `safe_navigation`, `range`, `negation_removal`, `chain_link`,
-`operand_removal`, `array_literal`.
+`operand_removal`, `array_literal`, `condition_true`,
+`condition_false`, `operator_assignment`.
 
 ## Rails apps
 

data/lib/mutineer/changed_lines.rb

@@ -56,6 +56,10 @@ module Mutineer
     end
 
     # Returns the stdout of `git -C <root> diff --unified=0 <ref> -- <file>`.
+    # A file that is not in the index has no usable diff, so `new_file_diff`
+    # supplies one that marks every line new. That includes a file the ref still
+    # has, deleted and then written again: git prints only a deletion hunk for it.
+    # Paths are literal, so a name such as `file[1].rb` is not read as a glob.
     #
     # A failure is warned, never silent: an empty result means "no changed
     # lines", which under `--since` removes every mutant for the file — a green
@@ -67,9 +71,9 @@ module Mutineer
     # @return [String] diff text, or `""` on failure (after a stderr warning).
     def git_diff(ref, abs_file, project_root)
       out, _err, status = Open3.capture3(
-        "git", "-C", project_root, "diff", "--unified=0", ref, "--", abs_file
+        "git", "--literal-pathspecs", "-C", project_root, "diff", "--unified=0", ref, "--", abs_file
       )
-      return out if status.success?
+      return(indexed?(abs_file, project_root) ? out : new_file_diff(abs_file)) if status.success?
 
       warn "[mutineer] git diff failed for #{abs_file}; its lines will not be mutated (--since)"
       ""
@@ -77,5 +81,33 @@ module Mutineer
       warn "[mutineer] git diff failed for #{abs_file} (#{e.class}); its lines will not be mutated (--since)"
       ""
     end
+
+    # Tells whether the index holds the file. Only then is git's own diff the
+    # truth; the diff text cannot tell, because a mode-only diff must stay empty.
+    #
+    # @param abs_file [String] absolute path of the file being diffed.
+    # @param project_root [String] repository root for `git -C`.
+    # @return [Boolean] true when the index holds the file.
+    def indexed?(abs_file, project_root)
+      _out, _err, known = Open3.capture3(
+        "git", "--literal-pathspecs", "-C", project_root, "ls-files", "--error-unmatch", "--", abs_file
+      )
+      known.success?
+    end
+
+    # Returns a diff that marks a file as entirely new. It returns `""` when
+    # the file is empty or cannot be read (after a warning). A file outside the
+    # index has every line new; read as "unchanged", `--since` would score
+    # nothing and a positive threshold would still exit 0.
+    #
+    # @param abs_file [String] absolute path of the file being diffed.
+    # @return [String] a one-hunk diff header, or `""`.
+    def new_file_diff(abs_file)
+      count = File.foreach(abs_file).count
+      count.zero? ? "" : "@@ -0,0 +1,#{count} @@\n"
+    rescue SystemCallError => e
+      warn "[mutineer] cannot read #{abs_file} (#{e.class}); its lines will not be mutated (--since)"
+      ""
+    end
   end
 end

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.
@@ -166,7 +153,7 @@ module Mutineer
         # 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
@@ -187,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
@@ -236,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
@@ -277,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
@@ -408,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|
@@ -422,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

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/mutator_registry.rb

@@ -17,6 +17,8 @@ require_relative "mutators/negation_removal"
 require_relative "mutators/chain_link"
 require_relative "mutators/operand_removal"
 require_relative "mutators/array_literal"
+require_relative "mutators/condition_forcing"
+require_relative "mutators/operator_assignment"
 
 module Mutineer
   # Maps operator names to operator classes.
@@ -45,7 +47,10 @@ module Mutineer
       "negation_removal"   => Mutators::NegationRemoval,
       "chain_link"         => Mutators::ChainLink,
       "operand_removal"    => Mutators::OperandRemoval,
-      "array_literal"      => Mutators::ArrayLiteral
+      "array_literal"      => Mutators::ArrayLiteral,
+      "condition_true"     => Mutators::ConditionTrue,
+      "condition_false"    => Mutators::ConditionFalse,
+      "operator_assignment" => Mutators::OperatorAssignment
     }.freeze
 
     # The default Tier-1 operator set.
@@ -53,7 +58,8 @@ module Mutineer
     # Tier-2 operators that remain opt-in.
     TIER2_NAMES   = %w[return_nil literal_mutation condition_negation string_literal regex collection_method
                        safe_navigation range negation_removal
-                       chain_link operand_removal array_literal].freeze
+                       chain_link operand_removal array_literal
+                       condition_true condition_false operator_assignment].freeze
 
     # Short human-readable descriptions for each operator.
     DESCRIPTIONS = {
@@ -73,7 +79,10 @@ module Mutineer
       "negation_removal"   => "!x, not x -> x",
       "chain_link"         => "drop one call from a chain: a.b.c -> a.c",
       "operand_removal"    => "a && b -> a, b",
-      "array_literal"      => "[a, b] -> []"
+      "array_literal"      => "[a, b] -> []",
+      "condition_true"     => "if/elsif/unless/ternary/modifier/case-in guard condition -> true",
+      "condition_false"    => "if/elsif/unless/ternary/modifier/case-in guard condition -> false",
+      "operator_assignment" => "+= <-> -=, *= <-> /=, %= -> *=, **= -> *= (not ||=, &&=)"
     }.freeze
 
     # Resolves operator names to classes.

data/lib/mutineer/mutators/condition_forcing.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Shared base of the condition-forcing mutators (Tier-2).
+    #
+    # Replaces the condition of an `if`, `elsif`, `unless`, ternary, modifier
+    # guard (`x if y`) or `case`/`in` guard with a literal, so its branch always
+    # runs or never runs. {ConditionTrue} forces `true` and {ConditionFalse}
+    # forces `false`; one mutation per condition each.
+    #
+    # A condition that is already `true`, `false` or `nil`, even in
+    # parentheses, is left alone: forcing it changes nothing or repeats the
+    # `boolean_literal` flip. This holds even when `boolean_literal` does not run.
+    # A condition that holds a heredoc is left alone too: the heredoc body lies
+    # outside the condition, so it would stay behind as code. A condition that
+    # assigns a variable keeps its code and only its value is forced.
+    #
+    # The never-runs side of an else-less conditional can be the same program
+    # as the `nil` that `statement_removal` or `return_nil` puts in place of the
+    # whole conditional. It is still made: dropping it would make the mutants
+    # of one operator depend on which other operators run, and on what the user
+    # suppressed for them. The two then get the same verdict.
+    #
+    # `condition_negation` wraps the condition in `!( ... )`, which neither
+    # forced value is.
+    class ConditionForcing < Base
+      # Condition nodes that `boolean_literal` already mutates.
+      LITERALS = [Prism::TrueNode, Prism::FalseNode, Prism::NilNode].freeze
+
+      # Visits if nodes: `if`, `elsif`, a ternary, a modifier `if` and an
+      # `in ... if` guard.
+      #
+      # @param node [Prism::IfNode] node to inspect.
+      # @return [void]
+      def visit_if_node(node)
+        force(node)
+        super
+      end
+
+      # Visits unless nodes: `unless`, a modifier `unless` and an
+      # `in ... unless` guard.
+      #
+      # @param node [Prism::UnlessNode] node to inspect.
+      # @return [void]
+      def visit_unless_node(node)
+        force(node)
+        super
+      end
+
+      # Nested method definitions are discovered as their own subjects; do not
+      # recurse into them (prevents double-counting their conditions).
+      #
+      # @param node [Prism::DefNode] nested definition node.
+      # @return [void]
+      def visit_def_node(node); end
+
+      private
+
+      # Emits the forced condition unless the condition is a literal or holds a
+      # heredoc, whose body would stay behind as code.
+      #
+      # @param node [Prism::IfNode, Prism::UnlessNode] the conditional.
+      # @return [void]
+      def force(node)
+        predicate = node.predicate
+        return if LITERALS.include?(unwrap(predicate).class) || heredoc?(predicate)
+
+        loc = predicate.location
+        @mutations << Mutation.new(
+          start_offset: loc.start_offset,
+          end_offset: loc.end_offset,
+          replacement: replacement(predicate),
+          operator: self.class::OPERATOR
+        )
+      end
+
+      # Returns the forced value for the condition, always in parentheses, so it
+      # cannot fuse with a keyword or a `?` next to it: `x if@a` becomes
+      # `x if(true)` and `@a?1:2` becomes `(true)?1:2`. A condition that assigns
+      # a variable keeps its code, so later reads still see the variable:
+      # `(m = x; true)`.
+      #
+      # @param predicate [Prism::Node] the condition.
+      # @return [String] the replacement source.
+      def replacement(predicate)
+        value = self.class::VALUE.to_s
+        writes?(predicate) ? "(#{predicate.slice}; #{value})" : "(#{value})"
+      end
+
+      # Returns whether the node writes a variable or constant anywhere inside
+      # it: a local, instance, class or global variable, or a constant, in a
+      # plain, compound, multiple or pattern write, or a named regex capture.
+      #
+      # @param node [Prism::Node] the node to inspect.
+      # @return [Boolean] true when a write or target node is inside.
+      def writes?(node)
+        return true if node.type.name.end_with?("_write_node", "_target_node")
+
+        node.compact_child_nodes.any? { |child| writes?(child) }
+      end
+
+      # Returns the node inside parentheses that hold exactly one expression,
+      # so `(true)` and `((true))` read as `true`.
+      #
+      # @param node [Prism::Node] the condition.
+      # @return [Prism::Node] the innermost wrapped node, or `node` itself.
+      def unwrap(node)
+        body = node.body if node.is_a?(Prism::ParenthesesNode)
+        body = body.body.first if body.is_a?(Prism::StatementsNode) && body.body.size == 1
+        body && !body.is_a?(Prism::StatementsNode) ? unwrap(body) : node
+      end
+    end
+
+    # Condition-forcing mutator: the condition becomes `true` (Tier-2).
+    #
+    # An `if` branch always runs; an `unless` branch never runs. The mutant
+    # survives when no test runs the code with the condition false (for an
+    # `if`) or true (for an `unless`) and checks what changes.
+    class ConditionTrue < ConditionForcing
+      # The literal the condition is replaced with.
+      VALUE = true
+      # The operator name mutations carry.
+      OPERATOR = :condition_true
+    end
+
+    # Condition-forcing mutator: the condition becomes `false` (Tier-2).
+    #
+    # An `if` branch never runs; an `unless` branch always runs. The mutant
+    # survives when no test needs the branch the condition guards (for an
+    # `if`) or skips it (for an `unless`).
+    class ConditionFalse < ConditionForcing
+      # The literal the condition is replaced with.
+      VALUE = false
+      # The operator name mutations carry.
+      OPERATOR = :condition_false
+    end
+  end
+end

data/lib/mutineer/mutators/operator_assignment.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Operator-assignment mutator (Tier-2).
+    #
+    # Swaps the operator of a compound assignment, one mutation per
+    # occurrence: `t += x` -> `t -= x`. Prism parses `t += x` as its own
+    # node, not as a CallNode, so the arithmetic mutator never sees it.
+    #
+    # The mapping is the same as for arithmetic. Other compound operators
+    # (`||=`, `&&=`, `|=`, `<<=` and the rest) are not changed.
+    class OperatorAssignment < Base
+      # Token replacements for compound arithmetic operators.
+      REPLACEMENTS = {
+        :+ => "-=", :- => "+=", :* => "/=", :/ => "*=", :% => "*=", :** => "*="
+      }.freeze
+
+      # Visits `t += x`.
+      #
+      # @param node [Prism::LocalVariableOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_local_variable_operator_write_node(node)
+        emit(node)
+        super # the value can hold its own compound assignment
+      end
+
+      # Visits `@t += x`.
+      #
+      # @param node [Prism::InstanceVariableOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_instance_variable_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `@@t += x`.
+      #
+      # @param node [Prism::ClassVariableOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_class_variable_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `$t += x`.
+      #
+      # @param node [Prism::GlobalVariableOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_global_variable_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `T += x`.
+      #
+      # @param node [Prism::ConstantOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_constant_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `A::T += x` and `::T += x`.
+      #
+      # @param node [Prism::ConstantPathOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_constant_path_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `a.b += x` and `a&.b += x`.
+      #
+      # @param node [Prism::CallOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_call_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Visits `a[i] += x`.
+      #
+      # @param node [Prism::IndexOperatorWriteNode] node to inspect.
+      # @return [void]
+      def visit_index_operator_write_node(node)
+        emit(node)
+        super
+      end
+
+      # Skips a nested method definition. The project finds it as a subject of
+      # its own, so a visit here counts its compound assignments twice.
+      #
+      # @param node [Prism::DefNode] nested definition node.
+      # @return [void]
+      def visit_def_node(node); end
+
+      private
+
+      # Emits a mutation when the node's operator has a replacement.
+      #
+      # @param node [Prism::Node] a node with `binary_operator` and `binary_operator_loc`.
+      # @return [void]
+      def emit(node)
+        replacement = REPLACEMENTS[node.binary_operator]
+        return unless replacement
+
+        loc = node.binary_operator_loc
+        @mutations << Mutation.new(
+          start_offset: loc.start_offset,
+          end_offset: loc.end_offset,
+          replacement: replacement,
+          operator: :operator_assignment
+        )
+      end
+    end
+  end
+end

data/lib/mutineer/version.rb

@@ -2,5 +2,5 @@
 
 module Mutineer
   # Current Mutineer release version.
-  VERSION = "1.3.0"
+  VERSION = "1.4.0"
 end

data/lib/mutineer.rb

@@ -31,6 +31,8 @@ require_relative "mutineer/mutators/negation_removal"
 require_relative "mutineer/mutators/chain_link"
 require_relative "mutineer/mutators/operand_removal"
 require_relative "mutineer/mutators/array_literal"
+require_relative "mutineer/mutators/condition_forcing"
+require_relative "mutineer/mutators/operator_assignment"
 require_relative "mutineer/mutator_registry"
 require_relative "mutineer/worker_pool"
 require_relative "mutineer/progress"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutineer
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - David Teren
@@ -77,10 +77,12 @@ files:
 - lib/mutineer/mutators/chain_link.rb
 - lib/mutineer/mutators/collection_method.rb
 - lib/mutineer/mutators/comparison.rb
+- lib/mutineer/mutators/condition_forcing.rb
 - lib/mutineer/mutators/condition_negation.rb
 - lib/mutineer/mutators/literal_mutation.rb
 - lib/mutineer/mutators/negation_removal.rb
 - lib/mutineer/mutators/operand_removal.rb
+- lib/mutineer/mutators/operator_assignment.rb
 - lib/mutineer/mutators/range_literal.rb
 - lib/mutineer/mutators/regex_literal.rb
 - lib/mutineer/mutators/return_nil.rb