mutineer 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b48ca68bd77d82bd83917312fe4bc2377954403e0a63c99702c9059b9dde07b
-  data.tar.gz: 0c11eaa74d07db731902b2fe70313f71b17eded8a59f10e5652b86985c11641c
+  metadata.gz: e18649829a9226ea7a5f654ef38602eabff4005ebf8a516fca4402460a7aac09
+  data.tar.gz: 9e3c166e5e2e513278aaf210f271ed0f070cd335d0de588318cb8aa71f6b6a06
 SHA512:
-  metadata.gz: 23505720f25f34b80bde51fb0a900c16a40295966ec8bd14713d22eca03ea0058a69d83b3f701672adee6a20b10f342f09d8b561d974f2a8f23d12a82ba22e46
-  data.tar.gz: cb2b659574bf1454ef265e3723b2c906485589696316cb63d9fb81d7696e04867e9fec73ee36b8d67063c7d941f4165fd35c922cc47cbc19466ec839ff8cbc2c
+  metadata.gz: 2e10e1214d0b55a4c93c7fa13d4c3b39503d4e2b1e367a995e2d813e98bd55ce2c2774b429bd690f2ae55019a39c7ee539e3ef60ea51bf25e2bc61c602ab72b6
+  data.tar.gz: 146768f9f599d41af9e6549f65ad7658cdd55e3d57a6f35fa6d094cfef6be73b036bb3dc8ebe8616d03cf358cdaf78e5d8a3b40a996c7a4d18a06898b9454824

data/CHANGELOG.md

@@ -6,6 +6,137 @@ 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
+- **Mutant ids now include the project-relative file path** (#126). Before, two
+  mutants with the same method name, operator and token in different files got
+  the same id. That happened with a top-level `def` or block in two files, and
+  with a class reopened in another file. One `ignore:` entry then suppressed
+  both mutants, and `--baseline` could hide a new survivor behind an old one.
+  - Every survivor id changes once in this release. This affects any external
+    tool that tracks survivors by id.
+  - Moving or renaming a file now changes its ids.
+  - Ids follow the project root: the directory mutineer runs from, or the
+    Action's `working-directory`. A run from a different root gives different ids.
+    mutineer finds `.mutineer.yml` by walking up, so a run from a subdirectory
+    prints one `[mutineer]` warning that the loaded ignore ids will not match.
+  - A source outside the project root uses its absolute path, so its ids differ
+    between machines.
+  - Two methods with the same qualified name in one file (for example two
+    top-level `def index` in two DSL blocks) now get different ids. The second
+    and later ones hash their position among those methods; the first keeps its
+    id.
+- **The JSON report marks its id format** (schema `1.4`, additive).
+  `summary.id_format` is `2` for ids that include the file path.
+  `summary.legacy_id_matches` counts old-format `ignore:` entries (`ignore`) and
+  survivors matched only through an old-format baseline id (`baseline`). The
+  GitHub Action shows one warning annotation when either count is not zero.
+
+### Deprecated
+- **Old-format ids in `ignore:` and in baselines.** Matching on them is removed
+  in 2.0. Replace each old `ignore:` entry with the new ids from the warning
+  (only the intended ones when it over-matched several mutants).
+  Regenerate a baseline (`--format json`) only after every gate that reads it
+  runs this version or later (the Action's `version:` pin, your CI
+  `Gemfile.lock`). An older version treats every new-format survivor as new.
+
+### Fixed
+- **`module_function :name` and `module_function def name` promote only
+  their own module's methods** — a class or module in the same file with a
+  method of the same name kept an instance method in Ruby, but mutineer
+  named it as a class method. `--strategy redefine` then mutated a method the
+  tests never call, so a killable mutant falsely survived, and
+  `--only Class#name` selected nothing (#98). The affected methods now get
+  their correct names, so their mutant ids change: regenerate any ignore
+  entries or baseline survivors that pointed at them.
+- **A root-anchored reopening names the top-level constant** — a
+  `module ::Root` or `class ::Solo` written inside another module now gives
+  `Root` and `Solo`, not `Outer::Root` and `Outer::Solo`. This applies to every
+  method in such a body, with or without `module_function`, so their mutant
+  ids change too. `--strategy redefine` rebuilds such a body's scope as
+  written (`module Outer` then `class ::Solo`), so a constant from `Outer`
+  still resolves in the mutated method, as it does under `reload`. Before,
+  the method raised NameError in the test, which counted as a false kill
+  (#145).
+- **Old-format ids keep working, with a warning** (#126). An old-format
+  `ignore:` entry still suppresses the mutants it matched before. The run prints
+  one `[mutineer]` warning per entry with each new id, its file and its method.
+  When the entry matched several mutants (in different files, or same-named
+  methods in one file), the warning says it
+  over-matched and to keep only the ids for the mutant you meant to ignore. A
+  `--baseline` file without `summary.id_format` matches on new ids, or on old
+  ids from the same file, so no survivor reads as new or fixed only because its
+  id changed. A stored file outside the project root (a baseline written on
+  another machine) matches on the old id alone. The run prints one
+  `[mutineer]` warning to regenerate the baseline.
+
 ## [1.2.0] - 2026-09-28
 
 ### Added
@@ -546,6 +677,8 @@ 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
 [1.0.2]: https://github.com/davidteren/mutineer/releases/tag/v1.0.2

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
 
@@ -214,11 +215,59 @@ Some mutants are equivalent (behaviour-identical) and survive forever — keepin
 file off 100%. Suppress them so the score and `--threshold` gate stay meaningful:
 
 - **Inline:** `some_line # mutineer:disable-line` (or scope it: `# mutineer:disable-line comparison`). Put a reason after `--`: `# mutineer:disable-line comparison -- the test checks only 20`.
-- **Config:** a `.mutineer.yml` `ignore:` list of stable mutant ids. Each survivor's
+- **Config:** a `.mutineer.yml` `ignore:` list of mutant ids. Each survivor's
   `id` is printed in the JSON report, so copy it straight into `ignore:`.
 
 Suppressed mutants are excluded from the score (so 100% becomes reachable).
 
+## Mutant ids
+
+A mutant id is 12 hex characters. It hashes the file path (relative to the
+project root), the method's qualified name, the operator, the mutated code, and
+the mutant's position among identical mutants in that method. When one file has
+two methods with the same qualified name (for example two top-level `def index`
+in two DSL blocks), the second and later ones also hash their position among
+those methods, so their ids differ. The first one's id does not change. An edit
+outside the method does not change the id. Moving or renaming the file,
+renaming the method or its class, or adding an identical mutant earlier in the
+method does. Adding a method with the same name earlier in the same file also
+does.
+
+- The project root is the directory mutineer runs from (in the Action, the
+  `working-directory`). Run from the same root to get the same ids.
+- A source outside the project root uses its absolute path, so its ids differ
+  between machines.
+
+**Migrating from ids without the file path.** Before 1.3, ids did not include
+the file path, so two files could share an id (#126). Old-format ids keep
+working until 2.0, with a warning:
+
+- **`ignore:`** An old entry still suppresses its mutants. The run prints the
+  new ids for each old entry, each with its file and method. When it names one
+  mutant, replace the entry with that id. When it names several (in different
+  files, or same-named methods in one file), the old entry over-matched: it also
+  hid mutants you did not mean to ignore. The warning says so. Keep only the ids for the mutant you meant to
+  ignore, not all of them. The list covers only the sources and operators in
+  that run, so run over every source with every operator set you use (for
+  example your Tier-2 `--operators`) for the full list.
+- **`--baseline`** An old baseline still matches: a survivor matches a stored
+  one with the same old id in the same file. A stored file that is an absolute
+  path outside the project root (a baseline written on another machine)
+  matches on the old id alone. The run tells you to
+  regenerate it. Regenerate it with `--format json`, but only after every gate
+  that reads it runs 1.3 or later (the Action's `version:` pin, your CI
+  `Gemfile.lock`). An older version treats every new-format survivor as new.
+
+The JSON report's `summary.id_format` is `2` for the new format.
+`summary.legacy_id_matches.ignore` counts the old-format ignore entries a run
+matched, and `summary.legacy_id_matches.baseline` counts the survivors matched
+only through an old baseline id.
+
+Ids are relative to the directory you run mutineer from. mutineer finds
+`.mutineer.yml` by walking up. When the file it loads is in a parent directory
+(other than your home directory), it warns that the ignore ids will not match
+and tells you which directory to run from.
+
 ## CI gating
 
 Store a JSON run as a baseline, then fail the build only when a PR makes things
@@ -228,7 +277,7 @@ worse:
 mutineer run app/ --baseline .mutineer/baseline.json   # exit 1 on NEW survivors or a score drop
 ```
 
-`--baseline` reports which survivors are new (by stable id) and any score drop. It
+`--baseline` reports which survivors are new (by [mutant id](#mutant-ids)) and any score drop. It
 combines with `--threshold` (the worse of the two sets the exit code). Pass a
 directory (or several sources) to audit a whole layer in one boot — tests are
 auto-paired by convention and the report breaks down per source.
@@ -267,7 +316,7 @@ the format.
 
 ## For AI agents & pipelines
 
-Mutineer is built for programmatic use — versioned JSON, stable mutant ids,
+Mutineer is built for programmatic use — versioned JSON, [mutant ids](#mutant-ids) that survive unrelated edits,
 structured exit codes, and diff-scoped runs. See:
 
 - **AI agents & CI recipes** — the agent inner-loop and CI-gate recipes (and how

data/lib/mutineer/baseline.rb

@@ -1,18 +1,20 @@
 # frozen_string_literal: true
 
 require "json"
+require "set"
 require_relative "config" # for Mutineer::ConfigError
+require_relative "project_path"
 
 module Mutineer
   # CI baseline/delta gating. A baseline is a prior
   # `mutineer run --format json` document (no bespoke format to version).
-  # Diff the current run against it by the stable survivor id: a NEW survivor
+  # Diff the current run against it by survivor id: a NEW survivor
   # (id present now, absent in the baseline) OR a score drop is a regression the
   # CLI turns into exit 1. Pure data, stdlib `json` only, no fork, no Rails, so
   # it is testable in isolation from a canned JSON + a hand-built AggregateResult.
   class Baseline
     # The verdict of diffing a current run against the baseline.
-    #   new_survivors   - current Result objects whose stable id is absent from
+    #   new_survivors   - current Result objects whose id is absent from
     #                     the baseline (the regressions to name).
     #   fixed_survivors - baseline survivor hashes absent from the current run
     #                     (informational, never gates). Empty when either side
@@ -26,8 +28,18 @@ module Mutineer
     #                     render them side by side. False means the score-drop
     #                     check was skipped, not that it passed.
     #   regressed       - any new survivors OR a score drop.
+    #   legacy_matches  - current survivors found in an old-format baseline
+    #                     (no `summary.id_format`) only through their old-format
+    #                     id (#126). Non-zero means the baseline should be
+    #                     regenerated; the CLI warns. Always 0 for a new-format
+    #                     baseline.
     Delta = Data.define(:new_survivors, :fixed_survivors,
-                        :score_before, :score_after, :score_drop, :score_comparable, :regressed)
+                        :score_before, :score_after, :score_drop, :score_comparable, :regressed,
+                        :legacy_matches) do
+      # @param legacy_matches [Integer] survivors matched only through an old-format id.
+      # @return [void]
+      def initialize(legacy_matches: 0, **) = super
+    end
 
     # Load a prior --format json run. Raises ConfigError (NOT exit: a data class
     # must never kill the host) on a missing/unreadable file, unparseable JSON,
@@ -73,35 +85,74 @@ module Mutineer
       # Strict literal true only: a malformed value (say the STRING "false" in a
       # hand-edited baseline) must not silently disable the score-drop gate.
       @scoped = doc.dig("summary", "scoped") == true
+      # nil for a report written before ids included the file path (#126).
+      @id_format = doc.dig("summary", "id_format")
     end
 
-    # Diff a current AggregateResult against this baseline by stable survivor id.
+    # Diff a current AggregateResult against this baseline by survivor id.
     # `epsilon` tolerates float jitter on the score (default 0.0 = any drop
     # gates).
     #
     # `scoped: true` marks the current run as diff-scoped (`--since`): its score
     # is computed over only the changed-line mutants, a different denominator
     # from a full-run baseline, so comparing the two scores manufactures false
-    # regressions. A scoped diff keeps the new-survivor gate (stable ids compare
+    # regressions. A scoped diff keeps the new-survivor gate (ids compare
     # fine across scopes) and still reports both scores, but never sets
     # score_drop.
     #
+    # `id_map` maps each current new-format id to its old-format id (#126). A
+    # baseline without `summary.id_format` stores old-format ids, so a current
+    # survivor matches if its new OR old id is stored, and a stored id seen under
+    # either form is not fixed. Matches made only through the old id are counted
+    # on Delta#legacy_matches. The old id has no file path, so an old-id match
+    # must also come from the same file (the stored survivor's `file`, normalized
+    # against `project_root`): an equal old id from another file is a different
+    # mutant and stays new. A stored `file` that is absolute and outside
+    # `project_root` (a baseline written on another machine) can never equal a
+    # current file, so that survivor matches on its old id alone, as before #126.
+    #
     # @param aggregate [Mutineer::AggregateResult] current results.
     # @param epsilon [Float] score-drop tolerance.
     # @param scoped [Boolean] current run was diff-scoped (`--since`).
+    # @param id_map [Hash{String => String}] current new id => old-format id.
+    # @param project_root [String] root that survivor `file` paths resolve against.
     # @return [Mutineer::Baseline::Delta] delta summary.
-    def diff(aggregate, epsilon: 0.0, scoped: false)
+    def diff(aggregate, epsilon: 0.0, scoped: false, id_map: {}, project_root: Dir.pwd)
       current = aggregate.surviving_mutants
-      current_ids = current.map(&:id)
-      baseline_ids = @survivors.map { |h| h["id"] }
+      baseline_ids = @survivors.map { |h| h["id"] }.to_set
+      # A new-format baseline never matches on old ids.
+      legacy = @id_format.nil? ? id_map : {}
+      file_key = ->(path) { path && ProjectPath.relative(path, project_root) }
+      # [old id, file] for each stored survivor: an old id alone is ambiguous.
+      baseline_pairs = @survivors.map { |h| [h["id"], file_key.call(h["file"])] }.to_set
+      # Old ids stored with a file from another machine: matched on the id alone.
+      foreign = @survivors.select { |h| foreign_file?(h["file"], file_key) }.to_set
+      foreign_ids = foreign.map { |h| h["id"] }.to_set
+      legacy_pair = ->(r) { [legacy[r.id], file_key.call(r.subject&.file)] }
 
-      new_survivors = current.reject { |r| baseline_ids.include?(r.id) }
+      new_survivors = []
+      legacy_matches = 0
+      current.each do |r|
+        next if baseline_ids.include?(r.id)
+
+        if legacy[r.id] && (baseline_pairs.include?(legacy_pair.call(r)) || foreign_ids.include?(legacy[r.id]))
+          legacy_matches += 1
+        else
+          new_survivors << r
+        end
+      end
+      current_ids = current.map(&:id).to_set
+      current_pairs = current.select { |r| legacy[r.id] }.map { |r| legacy_pair.call(r) }.to_set
+      current_legacy_ids = current.filter_map { |r| legacy[r.id] }.to_set
       # Under a diff-scoped side an out-of-scope baseline survivor was never
       # re-tested, so reporting it "fixed" would be false: empty is honest.
       fixed = if scoped || @scoped
                 []
               else
-                @survivors.reject { |h| current_ids.include?(h["id"]) }
+                @survivors.reject do |h|
+                  current_ids.include?(h["id"]) || current_pairs.include?([h["id"], file_key.call(h["file"])]) ||
+                    (foreign.include?(h) && current_legacy_ids.include?(h["id"]))
+                end
               end
 
       current_score = aggregate.mutation_score
@@ -116,7 +167,19 @@ module Mutineer
       Delta.new(new_survivors: new_survivors, fixed_survivors: fixed,
                 score_before: @score, score_after: current_score,
                 score_drop: score_drop, score_comparable: comparable,
-                regressed: !new_survivors.empty? || score_drop)
+                regressed: !new_survivors.empty? || score_drop, legacy_matches: legacy_matches)
+    end
+
+    private
+
+    # True when a stored survivor's `file` is absolute and still absolute after
+    # normalizing against the project root, so it lies outside this checkout.
+    #
+    # @param file [String, nil] the stored survivor's `file`.
+    # @param file_key [Proc] normalizes a path against the project root.
+    # @return [Boolean] whether the file can never equal a current file.
+    def foreign_file?(file, file_key)
+      !file.nil? && File.absolute_path?(file) && File.absolute_path?(file_key.call(file))
     end
   end
 end

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