active_mutator 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfe7e211472b45836efb059eb37472307becf74e85b8441664e8cec836c10c26
-  data.tar.gz: 6e0ed299bc84b8c912e73314f58ea88cc2fbb783f6949aea14285a27ea2e5bd9
+  metadata.gz: 5729b9385c24e575708a5227a3838ae28e09dd2ddf3e40e1883e9e74f7399275
+  data.tar.gz: 69b41b3304c8c008f54f6c20547ff9283d26a278eea706dc7cf923466dde1b5c
 SHA512:
-  metadata.gz: 6153450b921e1647a13d14f4e473cc123c045ff738f2cea1b6786797e265b05bc7bc00233bdf66f192296be1c372f0c458f6910992d01716320033b86a0a00e9
-  data.tar.gz: b1d9c1133f21dbe6370651c2d00e7e4173620ac13986ce24e8b91931f5f5793985d41cf2f8a7be626b73c948b6a473dec99f6e3560f52630cdad83c8ab3d5d72
+  metadata.gz: 3e0dce87a35314cb96e68e7051e3dfa8bbc329b58a3c41beef1201c7c5e8a3205d58a28593bf99382dfd1f9a9fd52859b44def8e2ee5d57dd0879e9dfcadec37
+  data.tar.gz: 5ec63925341ef8356801ee171e83af5b6323feb0f15838b1430421c9e5aaf73017d0e5ebaafb653039917a97144933e3572c2d182ba0544de27fbe60a0d7d6ca

data/README.md

@@ -128,8 +128,14 @@ Each character on the progress line is one mutant, printed as it finishes:
 
 `invalid` mutants (edits that don't even re-parse as valid Ruby) are
 discarded before scheduling and reported as a count only. Exit code is `1`
-if unaccepted survivors exist, `0` otherwise, including when there are
-only `uncovered`, `accepted`, or `error` results.
+if unaccepted survivors exist (or, with `--fail-at`, if the score is below
+the threshold), `0` otherwise, including when there are only `uncovered`,
+`accepted`, or `error` results. The JSON report's `exit_reason` field
+reflects survivor presence, independent of the `--fail-at` gate.
+
+When survivors exist, the summary also prints a per-operator table showing
+how often each operator's mutants survive, to help spot likely-equivalent
+mutant patterns.
 
 ## How it works, compactly
 
@@ -155,17 +161,42 @@ the serial lane for browser specs, timeout budgets, and every status, is in
 
 ```bash
 active_mutator                          # mutate app/ and lib/, full run
-active_mutator app/models               # scope by path
+active_mutator app/models               # scope by path (directory)
+active_mutator app/models/document.rb   # scope to a single file
 active_mutator --changed                # uncommitted work only (dev loop)
 active_mutator --since origin/main      # PR scope (CI)
 active_mutator --subject 'Foo::Bar#baz' # one method
+active_mutator --exclude 'lib/generated' # skip a subtree (repeatable)
+```
+
+`--subject` also takes broader expressions: `Foo::Bar` (all methods of
+that constant), `Foo::Bar*` (raw name prefix — matches `Foo::Bar::Qux`
+and also `Foo::Barn`), `Foo::Bar#*` (instance
+methods only), `Foo::Bar.*` (singleton methods only).
+
+`--exclude PAT` is a glob relative to the project root, applied during
+subject discovery, and gitignore-like: `lib/generated`, `lib/generated/`,
+and `lib/generated/**` all exclude the whole subtree. File globs like
+`**/legacy/*` work too.
+
+Skip a single method by putting `# active_mutator:skip` on the line above
+its `def`:
+
+```ruby
+# active_mutator:skip
+def legacy_delegator
+  target.call
+end
 ```
 
 Statuses: `killed` (test failed, this is good), `survived` (test gap),
 `timeout` (counts as detected), `uncovered` (no covering example, this is
 coverage debt), `accepted` (known-equivalent, see ledger), `error`,
 `invalid` (discarded).
-Exit code 1 if unaccepted survivors exist.
+Exit code is 1 if unaccepted survivors exist (or, with `--fail-at`, if the
+score is below the threshold). Mistyped positional paths (a file that
+doesn't exist, or a non-`.rb` file) are an error (exit 2) instead of a
+vacuous green run.
 
 Score = (killed + timeout) / (killed + timeout + survived).
 
@@ -185,13 +216,31 @@ git add .active_mutator_accepted.json                     # committed state
 ```
 
 Acceptance takes effect on the next run. The accepting run still exits 1.
+Scoped accepting runs (`--changed`, `--subject`, path args) are safe: the
+ledger only prunes entries in files fully scanned by non-narrowed runs, so
+out-of-scope acceptances are never dropped.
 Agent workflow: see [`docs/skills/mutation-check.md`](docs/skills/mutation-check.md).
 
+## Reports
+
+`--format stryker-json` writes `.active_mutator/mutation-report.json` in the
+Stryker [mutation-testing-report-schema](https://github.com/stryker-mutator/mutation-testing-elements)
+v2 format. Open it in the
+[Stryker report viewer](https://microsoft.github.io/mutation-testing-elements/)
+for per-file mutant maps with inline diffs, filterable by status.
+
+`--format github` prints one `::warning` annotation per surviving mutant, so
+survivors show inline on the PR diff. Pairs with the CI recipe:
+
+    bundle exec active_mutator --since origin/main --format github
+
 ## CI recipe
 
-- Per-PR: `active_mutator --since origin/main` (minutes)
+- Per-PR: `active_mutator --since origin/main --format github` (minutes;
+  survivors annotate the PR diff)
 - Nightly: `active_mutator --force-baseline` (full run; also recovers the
-  incremental baseline's newly-covering-example blind spot)
+  residual blind spot — constant-reference detection handles the common
+  newly-covering-example case since 0.2)
 
 ## Flags
 
@@ -200,15 +249,26 @@ Agent workflow: see [`docs/skills/mutation-check.md`](docs/skills/mutation-check
 | `--jobs N` | half the cores | fork-pool width |
 | `--changed` | none | mutate uncommitted + untracked work |
 | `--since REF` | none | mutate methods changed since REF |
-| `--subject NAME` | none | one subject, e.g. `Foo#bar` |
-| `--format terminal\|json` | terminal | report format |
+| `--subject EXPR` | none | subject expression, e.g. `Foo#bar`, `Foo::Bar`, `Foo::Bar*`, `Foo#*`, `Foo.*` |
+| `--exclude PAT` | none | skip files matching glob during subject discovery (repeatable, gitignore-like) |
+| `--max-mutants N` | none | deterministic sample of the first N mutants (quick smoke run on huge scopes; accepted/uncovered mutants count against N) |
+| `--debug-plan` | off | print planned mutants as JSON and exit without running |
+| `--format terminal\|json\|stryker-json\|github` | terminal | report format |
 | `--accept-survivors` | off | record survivors to the acceptance ledger |
 | `--force-baseline` | off | ignore cached coverage map |
 | `--preload-helper FILE` / `--no-preload-helper` | auto-detect | parent spec-helper preload |
 | `--serial-pattern PAT` | `spec/system/`, `spec/features/` | covering-path prefixes forced serial |
 | `--browser-boot-seconds S` | 15 | serial-lane timeout bump |
 | `--timeout-factor F` / `--timeout-floor S` | 8 / 10 | mutation timeout budget |
+| `--[no-]adaptive-timeout` | on | scale timeout budgets from observed worker wall times (median utilization, grow-only, clamped 1x–4x; `--timeout-factor`/`--timeout-floor` set the starting budget) |
 | `--require FILE` | none | preload files (repeatable) |
+| `--operator FILE` | none | load a custom operator file before analysis (repeatable) |
+| `--fail-at SCORE` | none (strict) | exit 0 if score >= SCORE even with survivors (opt-in relaxation for gradual adoption; 0 = report-only) |
+
+`--debug-plan` prints the planned mutant list as one JSON document
+(`{"planned": [...], "pre_resolved": {...}}`) and exits without running
+anything. A coverage baseline is still built or loaded, since timeouts
+and covering examples come from it.
 
 Every active_mutator process sets `ENV["ACTIVE_MUTATOR"] = "1"`. Use it to
 guard SimpleCov or other tooling in your spec helper:
@@ -217,12 +277,42 @@ guard SimpleCov or other tooling in your spec helper:
 SimpleCov.start "rails" unless ENV["ACTIVE_MUTATOR"]
 ```
 
+## Configuration file
+
+Put team-wide settings in `.active_mutator.yml` at the project root; CLI
+flags override file values (`--require` and `--exclude` add to the file's
+lists; the first `--serial-pattern` replaces them). Recognized keys:
+`jobs`, `format`, `timeout_factor`, `timeout_floor`,
+`browser_boot_seconds`, `fail_at`, `exclude`, `serial_patterns`,
+`requires`, `operators` (custom operator files, loaded before analysis; see
+[Custom operators](docs/guides/custom-operators.md)),
+`preload_helper` (a path, or `false` to skip preload),
+`adaptive_timeout` (`true`/`false`).
+Unknown keys and wrong types are errors, not silent no-ops.
+
+```yaml
+# .active_mutator.yml
+jobs: 4
+exclude:
+  - lib/generated
+serial_patterns:
+  - spec/system/
+fail_at: 90   # legacy suite: gate on score instead of zero-survivors
+```
+
 ## Known limits (v1.1)
 
 Method bodies only (no class-macro/constant mutation). RSpec only.
-Heredoc strings are not mutated. `class << self` bodies and nested defs
-are skipped. The incremental baseline can miss examples that only cover
-changed code after the change (nightly `--force-baseline` recovers).
+Plain heredoc bodies ARE mutated (emptied); interpolated heredocs are
+skipped. `class << self` bodies are mutated as singleton subjects
+(`class << obj` and top-level `class << self` are skipped). Nested defs
+mutate as part of the enclosing method's body — they get no subject of
+their own (a directly-inserted mutant would be reverted whenever the
+outer method re-runs the `def`). The incremental baseline recovers the residual blind spot —
+constant-reference detection handles the common case since 0.2, and a few
+residual cases (pure indirection, partially-covering files, leaf-only or
+wrapper-only references, `class ::Foo`, `Data.define`/`Struct.new` value
+objects) are caught by nightly `--force-baseline`.
 
 ## Guides
 
@@ -234,6 +324,8 @@ changed code after the change (nightly `--force-baseline` recovers).
 - [Operator reference](docs/guides/operators.md): every mutation
   active_mutator can generate, with before/after examples and what a
   survivor of each one means.
+- [Custom operators](docs/guides/custom-operators.md): write and load your
+  own mutation operators with `--operator` / the `operators:` config key.
 - [Mutation-check skill](docs/skills/mutation-check.md): the agent-facing
   workflow. Run, read survivors, strengthen tests, or accept with a reason.
 

data/lib/active_mutator/accepted_ledger.rb

@@ -5,6 +5,10 @@ module ActiveMutator
   # Committed, repo-root ledger of accepted (equivalent) survivors.
   # Deliberately NOT inside .active_mutator/: that dir is gitignored and
   # disposable, while acceptance decisions are durable team/CI state.
+  #
+  # Entries whose file no longer exists are kept, not pruned: the file may
+  # still exist on another branch, so deletion is the user's call. The runner
+  # warns about them on every run instead (see #missing_file_entries).
   class AcceptedLedger
     FILENAME = ".active_mutator_accepted.json"
 
@@ -28,16 +32,27 @@ module ActiveMutator
 
     def accepted?(fingerprint) = @entries.include?(fingerprint)
 
-    def stale_entries(all_current_fingerprints)
+    # Entries outside the scanned files can't be judged by this run, so they
+    # are never stale here. scanned_files: nil means "no file was fully
+    # scanned" (subject-level filtering active) — union only, prune nothing.
+    # See #24: a scoped accept run once deleted every out-of-scope entry.
+    def stale_entries(all_current_fingerprints, scanned_files:)
+      return [] if scanned_files.nil?
+
       current = all_current_fingerprints.to_set
-      @entries.reject { |e| current.include?(e) }
+      scanned = scanned_files.to_set
+      @entries.reject { |e| current.include?(e) || !scanned.include?(e.file) }
     end
 
-    # Union new acceptances in, prune anything no longer matching a current
-    # mutant, write atomically.
-    def accept!(new_fingerprints, all_current_fingerprints)
-      current = all_current_fingerprints.to_set
-      @entries = (@entries + new_fingerprints).uniq.select { |e| current.include?(e) }
+    # Missing is objective regardless of run scope: such entries can never
+    # appear in scanned_files, so without this they'd be immortal AND silent.
+    def missing_file_entries(root)
+      @entries.reject { |e| File.exist?(File.join(root, e.file)) }
+    end
+
+    def accept!(new_fingerprints, all_current_fingerprints, scanned_files:)
+      stale = stale_entries(all_current_fingerprints, scanned_files: scanned_files).to_set
+      @entries = (@entries + new_fingerprints).uniq.reject { |e| stale.include?(e) }
       AtomicFile.write(@path, JSON.pretty_generate(@entries.map(&:to_h)))
       nil
     end

data/lib/active_mutator/baseline_delta.rb

@@ -11,6 +11,10 @@ module ActiveMutator
     FULL = Delta.new(full: true, rerun_spec_files: [], rerun_example_ids: [],
                      drop_example_ids: [], drop_source_files: [])
 
+    # If a changed constant is referenced by more than this share of all spec
+    # files, a full re-run is cheaper and simpler than a giant partial one.
+    REFERENCE_FULL_RATIO = 0.5
+
     def self.compute(old_digests:, new_digests:, coverage_map:, root:)
       changed = (old_digests.keys | new_digests.keys)
                 .reject { |k| old_digests[k] == new_digests[k] }
@@ -21,6 +25,13 @@ module ActiveMutator
       drop_example_ids = []
       drop_source_files = []
 
+      # Read the spec-file list and their contents once per compute call, not
+      # once per changed source file: newly_covering_candidates scans every
+      # spec file, so re-globbing and re-reading inside the loop was
+      # O(changed_files x spec_files) IO. Built lazily so a delta with no
+      # scannable source change pays nothing.
+      spec_contents = nil
+
       changed.each do |rel|
         added = !old_digests.key?(rel)
         deleted = !new_digests.key?(rel)
@@ -39,7 +50,17 @@ module ActiveMutator
         else
           abs = File.join(root, rel)
           drop_source_files << abs if deleted
-          rerun_example_ids.concat(coverage_map.examples_covering_file(abs)) unless added
+          unless added
+            rerun_example_ids.concat(coverage_map.examples_covering_file(abs))
+          end
+          unless deleted
+            spec_contents ||= Dir[File.join(root, "spec/**/*_spec.rb")].to_h { |f| [f, File.read(f)] }
+            candidates = newly_covering_candidates(root: root, rel: rel, coverage_map: coverage_map,
+                                                   spec_contents: spec_contents)
+            return FULL if candidates == :full
+
+            rerun_spec_files.concat(candidates)
+          end
         end
       end
 
@@ -53,5 +74,50 @@ module ActiveMutator
     def self.full_trigger?(rel)
       rel.start_with?("spec/support/") || !rel.end_with?(".rb")
     end
+
+    # #11: an unchanged spec file can START covering a changed source file
+    # because of the edit itself. Cheap static detection: spec files that
+    # textually reference a constant the changed file defines, but currently
+    # contribute zero coverage to it, get re-run. Files already covering it
+    # are handled example-by-example via rerun_example_ids.
+    def self.newly_covering_candidates(root:, rel:, coverage_map:, spec_contents:)
+      abs = File.join(root, rel)
+      return [] unless File.exist?(abs)
+
+      constants = DefinedConstants.in_source(File.read(abs))
+      return [] if constants.empty?
+
+      all_specs = spec_contents.keys
+
+      covering_specs = coverage_map.examples_covering_file(abs)
+                                   .map { |id| spec_file_of(id) }.to_a.uniq
+      # Escaping is required: dynamic-namespace class definitions (e.g.
+      # `class (a)::Baz`, `class foo.bar::Baz`) make constant_path.slice carry
+      # regex metachars. Unescaped, "(a)::Baz" would match the literal text
+      # "a::Baz" — a false candidate.
+      # TODO(#11, Task 10 residual gap): a top-level `class ::Foo` yields the
+      # slice "::Foo", and /\b::Foo\b/ can never match (no word boundary
+      # before ":"), so such files are silently unscanned.
+      pattern = /\b(?:#{constants.map { |c| Regexp.escape(c) }.join("|")})\b/
+      candidates = all_specs.filter_map do |spec_abs|
+        spec_rel = spec_abs.delete_prefix(root).delete_prefix("/")
+        next if covering_specs.include?(spec_rel)
+
+        spec_rel if spec_contents.fetch(spec_abs).match?(pattern)
+      end
+      if candidates.size > 1 && candidates.size > all_specs.size * REFERENCE_FULL_RATIO
+        # Never silently degrade: a full baseline where the user expected an
+        # incremental refresh must be explained, or it looks like a hang.
+        warn "active_mutator: constant-reference scan matched #{candidates.size} of " \
+             "#{all_specs.size} spec files for #{rel}; falling back to full baseline"
+        return :full
+      end
+
+      candidates
+    end
+
+    def self.spec_file_of(example_id)
+      example_id.sub(%r{\A\./}, "").sub(/\[.*\]\z/, "")
+    end
   end
 end

data/lib/active_mutator/cli.rb

@@ -22,16 +22,20 @@ module ActiveMutator
         # boot cost (RSpec setup + spec file loading).
         requires: [], timeout_factor: 8.0, timeout_floor: 10.0, force_baseline: false,
         preload_helper: nil, serial_patterns: ["spec/system/", "spec/features/"],
-        browser_boot_seconds: 15.0, accept_survivors: false
+        browser_boot_seconds: 15.0, accept_survivors: false, exclude: [],
+        max_mutants: nil, debug_plan: false, fail_at: nil, adaptive_timeout: true,
+        operator_paths: []
       }
+      options.merge!(ConfigFile.load(Dir.pwd))
       paths = OptionParser.new do |o|
         o.banner = "Usage: active_mutator [paths] [options]"
         o.on("--since REF", "Mutate only methods changed since git REF") { |v| options[:since] = v }
         o.on("--changed", "Mutate uncommitted work (alias for --since HEAD, plus untracked files)") { options[:since] = "HEAD" }
-        o.on("--subject NAME", "Mutate only the named subject, e.g. Foo::Bar#baz") { |v| options[:subject_filter] = v }
+        o.on("--subject NAME", "Mutate matching subjects: Foo::Bar#baz, Foo::Bar, Foo::Bar*, Foo::Bar#*") { |v| options[:subject_filter] = v }
         o.on("--jobs N", Integer, "Concurrent workers (default: half the CPU count)") { |v| options[:jobs] = v }
-        o.on("--format FMT", %w[terminal json], "Output format") { |v| options[:format] = v.to_sym }
-        o.on("--require FILE", "File to require before mutating (repeatable)") { |v| options[:requires] << v }
+        o.on("--format FMT", ConfigFile::FORMATS, "Output format") { |v| options[:format] = v.tr("-", "_").to_sym }
+        o.on("--require FILE", "File to require before mutating (repeatable; adds to config-file requires)") { |v| options[:requires] << v }
+        o.on("--operator FILE", "Ruby file defining a custom operator, loaded before analysis (repeatable)") { |v| options[:operator_paths] << v }
         o.on("--force-baseline", "Ignore cached coverage map") { options[:force_baseline] = true }
         o.on("--timeout-factor F", Float, "Timeout = baseline time * F + floor") { |v| options[:timeout_factor] = v }
         o.on("--timeout-floor S", Float, "Minimum timeout seconds") { |v| options[:timeout_floor] = v }
@@ -43,7 +47,15 @@ module ActiveMutator
           options[:serial_patterns] << v
         end
         o.on("--browser-boot-seconds S", Float, "Extra timeout budget for serial-lane mutants") { |v| options[:browser_boot_seconds] = v }
+        o.on("--[no-]adaptive-timeout", "Scale timeout budgets from observed worker wall times (default: on)") { |v| options[:adaptive_timeout] = v }
         o.on("--accept-survivors", "Record surviving mutants into the acceptance ledger") { options[:accept_survivors] = true }
+        o.on("--exclude PAT", "Skip files matching glob, relative to root (repeatable)") { |v| options[:exclude] << v }
+        o.on("--max-mutants N", Integer, "Deterministically sample the first N mutants") { |v| options[:max_mutants] = v }
+        o.on("--debug-plan", "Print the planned mutant list as JSON and exit") { options[:debug_plan] = true }
+        o.on("--fail-at SCORE", Float, "Exit 0 if mutation score >= SCORE even with survivors (default: any survivor fails)") do |v|
+          raise OptionParser::InvalidArgument, "--fail-at must be within 0..100" unless (0..100).cover?(v)
+          options[:fail_at] = v
+        end
       end.parse(argv)
       options.delete(:serial_patterns_replaced)
 

data/lib/active_mutator/config.rb

@@ -4,5 +4,6 @@ module ActiveMutator
   Config = Data.define(:paths, :since, :subject_filter, :jobs, :format, :requires,
                        :timeout_factor, :timeout_floor, :force_baseline, :root,
                        :preload_helper, :serial_patterns, :browser_boot_seconds,
-                       :accept_survivors)
+                       :accept_survivors, :exclude, :max_mutants, :debug_plan,
+                       :fail_at, :adaptive_timeout, :operator_paths)
 end

data/lib/active_mutator/config_file.rb

@@ -0,0 +1,89 @@
+require "yaml"
+
+module ActiveMutator
+  # Project config file, layered UNDER CLI flags: CLI.parse seeds its option
+  # defaults from this before OptionParser runs, so any flag given on the
+  # command line wins. Strict on unknown keys and types — a typo silently
+  # ignored would be a config that silently doesn't apply.
+  class ConfigFile
+    FILENAME = ".active_mutator.yml"
+
+    FORMATS = %w[terminal json stryker-json github].freeze
+
+    KEYS = {
+      "jobs" => :integer,
+      "format" => :format,
+      "timeout_factor" => :number,
+      "timeout_floor" => :number,
+      "browser_boot_seconds" => :number,
+      "fail_at" => :score,
+      "exclude" => :string_list,
+      "serial_patterns" => :string_list,
+      "requires" => :string_list,
+      "operators" => :string_list,
+      "preload_helper" => :preload_helper,
+      "adaptive_timeout" => :boolean
+    }.freeze
+
+    # YAML keys that don't match their Config member name.
+    RENAMES = { "operators" => :operator_paths }.freeze
+
+    def self.load(root)
+      path = File.join(root, FILENAME)
+      return {} unless File.exist?(path)
+
+      data = parse(path)
+      return {} if data.nil?
+      raise Error, "#{FILENAME}: top level must be a mapping" unless data.is_a?(Hash)
+
+      data.to_h do |key, value|
+        validator = KEYS[key]
+        raise Error, "#{FILENAME}: unknown config key: #{key}" unless validator
+
+        [RENAMES.fetch(key, key.to_sym), coerce(key, validator, value)]
+      end
+    end
+
+    def self.parse(path)
+      YAML.safe_load_file(path, aliases: true)
+    rescue Psych::Exception => e
+      raise Error, "#{FILENAME}: #{e.message}"
+    end
+
+    def self.coerce(key, validator, value)
+      case validator
+      when :integer
+        raise Error, "#{FILENAME}: #{key} must be an integer" unless value.is_a?(Integer)
+        value
+      when :number
+        raise Error, "#{FILENAME}: #{key} must be a number" unless value.is_a?(Numeric)
+        value.to_f
+      when :score
+        raise Error, "#{FILENAME}: #{key} must be a number" unless value.is_a?(Numeric)
+        raise Error, "#{FILENAME}: #{key} must be within 0..100" unless (0..100).cover?(value)
+        value.to_f
+      when :format
+        unless FORMATS.include?(value)
+          raise Error, "#{FILENAME}: format must be one of #{FORMATS.join(", ")}"
+        end
+        value.tr("-", "_").to_sym
+      when :string_list
+        unless value.is_a?(Array) && value.all?(String)
+          raise Error, "#{FILENAME}: #{key} must be a list of strings"
+        end
+        value
+      when :boolean
+        unless [true, false].include?(value)
+          raise Error, "#{FILENAME}: #{key} must be true or false"
+        end
+        value
+      when :preload_helper
+        return :none if value == false
+        raise Error, "#{FILENAME}: preload_helper must be a path or false" unless value.is_a?(String)
+        value
+      else
+        raise Error, "unhandled validator #{validator}"
+      end
+    end
+  end
+end

data/lib/active_mutator/defined_constants.rb

@@ -0,0 +1,48 @@
+require "prism"
+
+module ActiveMutator
+  # Deepest fully qualified names of classes/modules a source file defines
+  # ("Billing::Invoice"). Two shorthands are deliberately never emitted,
+  # because either would let a single common token match half of any real
+  # spec suite and trip BaselineDelta's full-run fallback on every edit:
+  #   - bare leaves ("Config" for MyApp::Config)
+  #   - pure namespace wrappers ("MyApp" for `module MyApp; class Config`):
+  #     every file in a namespaced app reopens the top module, and every
+  #     spec mentions it.
+  # A wrapper is a node whose non-empty direct body contains ONLY nested
+  # class/module definitions. A module with its own defs/macros/constants is
+  # a real edit target and IS emitted; so is an empty or def-less leaf class
+  # (macro-only ActiveRecord models).
+  #
+  # Guard is errors.any?, not warnings: Prism produces a complete AST for
+  # warnings-only input (`if a = 2`), and those definitions are real.
+  module DefinedConstants
+    def self.in_source(source)
+      result = Prism.parse(source)
+      return [] if result.errors.any?
+
+      names = []
+      walk(result.value, [], names)
+      names.uniq
+    end
+
+    # The walk intentionally descends into block bodies (unlike SubjectFinder,
+    # which skips them): over-inclusion is the safe direction for spec-file
+    # matching, so a constant defined inside a block is still emitted.
+    def self.walk(node, scope, names)
+      if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+        scope = scope + [node.constant_path.slice]
+        names << scope.join("::") unless namespace_wrapper?(node)
+      end
+      node.compact_child_nodes.each { |child| walk(child, scope, names) }
+    end
+    private_class_method :walk
+
+    def self.namespace_wrapper?(node)
+      statements = node.body.is_a?(Prism::StatementsNode) ? node.body.body : []
+      statements.any? &&
+        statements.all? { |s| s.is_a?(Prism::ClassNode) || s.is_a?(Prism::ModuleNode) }
+    end
+    private_class_method :namespace_wrapper?
+  end
+end

data/lib/active_mutator/edit.rb

@@ -1,5 +1,11 @@
 module ActiveMutator
   # A single mutation as a text edit: replace `range` (exclusive byte Range)
-  # in the original source with `replacement`.
-  Edit = Data.define(:range, :replacement, :description)
+  # in the original source with `replacement`. `operator` is the producing
+  # operator's demodulized class name ("CallSwap"), "Unknown" outside the
+  # operator pipeline.
+  Edit = Data.define(:range, :replacement, :description, :operator) do
+    def initialize(range:, replacement:, description:, operator: "Unknown")
+      super
+    end
+  end
 end

data/lib/active_mutator/engine.rb

@@ -35,14 +35,27 @@ module ActiveMutator
     def collect_edits(def_node)
       edits = []
       walk(def_node.body) do |node|
-        @operators.each { |op| edits.concat(op.edits(node)) }
+        @operators.each do |op|
+          edits.concat(op.edits(node))
+        rescue StandardError => e
+          # Fail loud but attributed: a buggy (likely third-party) operator
+          # should point at itself, not surface as a bare crash mid-analysis.
+          raise Error, "operator #{op.class.name} failed on #{node.class.name}: #{e.message}"
+        end
       end
       edits
     end
 
     def walk(node, &blk)
       return if node.nil?
-      return if node.is_a?(Prism::DefNode) # nested defs are separate subjects
+      # Descend into nested DefNodes rather than treating them as separate
+      # subjects. Giving a nested def its own subject identity is a trap:
+      # every call of the outer method re-executes the nested `def`, which
+      # would silently revert a directly-inserted mutant mid-run (phantom
+      # survivors). Instead we mutate the nested body as part of the outer
+      # def's re-evaled source. (SubjectFinder still emits no subject for
+      # nested defs.) walk is called as walk(def_node.body), so the outer
+      # DefNode itself never passes through here.
 
       yield node
       node.compact_child_nodes.each { |child| walk(child, &blk) }

data/lib/active_mutator/inserter.rb

@@ -1,13 +1,16 @@
 module ActiveMutator
   # Redefines the subject's method with its mutated source. `class_eval` of a
   # `def` handles instance methods; a `def self.x` source string defines the
-  # singleton method the same way. Top-level subjects eval at main scope.
+  # singleton method the same way. An sclass subject's source is a plain
+  # `def foo` that must land on the constant's singleton class, so we route it
+  # through `.singleton_class.class_eval`. Top-level subjects eval at main scope.
   class Inserter
     def insert(mutation)
       subject = mutation.subject
       if subject.constant_scope
-        Object.const_get(subject.constant_scope)
-              .class_eval(mutation.mutated_def_source, subject.file, mutation.mutated_def_line)
+        target = Object.const_get(subject.constant_scope)
+        target = target.singleton_class if subject.sclass
+        target.class_eval(mutation.mutated_def_source, subject.file, mutation.mutated_def_line)
       else
         eval(mutation.mutated_def_source, TOPLEVEL_BINDING, # rubocop:disable Security/Eval
              subject.file, mutation.mutated_def_line)

data/lib/active_mutator/operators/base.rb

@@ -18,7 +18,8 @@ module ActiveMutator
       def loc_range(loc) = loc.start_offset...loc.end_offset
 
       def edit(range, replacement, description)
-        Edit.new(range: range, replacement: replacement, description: description)
+        Edit.new(range: range, replacement: replacement, description: description,
+                 operator: self.class.name.split("::").last)
       end
     end
   end

data/lib/active_mutator/operators/call_swap.rb

@@ -9,6 +9,22 @@ module ActiveMutator
         min: "max", max: "min",
         first: "last", last: "first",
         any?: "none?", none?: "any?",
+        # all? is one-way: any? already pairs with none?, so all?→any? adds a
+        # distinct mutant without a redundant reverse edge.
+        all?: "any?",
+        take: "drop", drop: "take",
+        min_by: "max_by", max_by: "min_by",
+        # sort→reverse is one-way by design: reverse already has a strong
+        # forward mutant here, and reverse→sort would double-map `reverse`
+        # against nothing useful (reverse has no MAP entry to preserve).
+        sort: "reverse",
+        # detect/find→first is one-way: first ignores the retained block, so
+        # the mutant usually differs (equivalent only when element 0 already
+        # satisfies the predicate). No reverse edge: `first` is taken by
+        # first→last above.
+        detect: "first", find: "first",
+        # Evaluated and rejected: sum (initial-arg arity mismatch),
+        # find_index (no safe partner — rindex is Array-only).
         # Rails-aware pack:
         present?: "blank?", blank?: "present?",
         save: "save!", save!: "save"

data/lib/active_mutator/operators/literal.rb

@@ -23,8 +23,8 @@ module ActiveMutator
 
       def string_edits(node)
         opening = node.opening_loc&.slice
-        return [] unless opening                  # quote-less parts (interpolation)
-        return [] if opening.start_with?("<<")    # heredocs: v1 limit
+        return [] unless opening                # quote-less parts (interpolation)
+        return heredoc_edits(node) if opening.start_with?("<<")
 
         if node.unescaped.empty?
           [edit(loc_range(node.location), %("active_mutator"), %(replace "" with "active_mutator"))]
@@ -32,6 +32,18 @@ module ActiveMutator
           [edit(loc_range(node.location), %(""), %(replace string with ""))]
         end
       end
+
+      # The node span covers the `<<~X` opening token; splicing there breaks
+      # the source. Mutate the body content range instead: nonempty body →
+      # empty heredoc (opening line directly followed by the terminator).
+      # The guard is on the DEDENTED VALUE (unescaped), not content_loc: a
+      # squiggly body that dedents to "" would only lose whitespace bytes —
+      # an equivalent mutant — so it is skipped even though content is nonempty.
+      def heredoc_edits(node)
+        return [] if node.unescaped.empty?
+
+        [edit(loc_range(node.content_loc), "", "empty heredoc body")]
+      end
     end
   end
 end