active_mutator 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c401b5edbafa0a072b6672e088a9016f918d9e76ce6b264a9e2a054b1b538cc6
-  data.tar.gz: d2a1908e950d8687e68524184efc2bce200d595be3b25f31e3a0e92a95325b3e
+  metadata.gz: 5729b9385c24e575708a5227a3838ae28e09dd2ddf3e40e1883e9e74f7399275
+  data.tar.gz: 69b41b3304c8c008f54f6c20547ff9283d26a278eea706dc7cf923466dde1b5c
 SHA512:
-  metadata.gz: 9d42e2e4a207ab1c6ced606eeeee342389b503da5055e207d282df220f112537f90b5f967079dfd76060d740f710d5441c8422565e7bdad314fa4bc9cf5d07c6
-  data.tar.gz: 3e226d88dc71b5b0b698f5e2a1148a38c7f6b12e0cd47411033368a0bf7d18a90d0ca8243fa3d2841ebd1b1be4cfb554c41732b4e1eacc2961f6477ddb692cc7
+  metadata.gz: 3e0dce87a35314cb96e68e7051e3dfa8bbc329b58a3c41beef1201c7c5e8a3205d58a28593bf99382dfd1f9a9fd52859b44def8e2ee5d57dd0879e9dfcadec37
+  data.tar.gz: 5ec63925341ef8356801ee171e83af5b6323feb0f15838b1430421c9e5aaf73017d0e5ebaafb653039917a97144933e3572c2d182ba0544de27fbe60a0d7d6ca

data/README.md

@@ -1,13 +1,16 @@
 # active_mutator
 
+[![Gem Version](https://badge.fury.io/rb/active_mutator.svg)](https://rubygems.org/gems/active_mutator)
+
 Mutation testing for Ruby, built on [Prism](https://github.com/ruby/prism).
-Open source, RSpec-integrated, Rails-first.
+Open source, RSpec-integrated, Rails-first. Available on
+[RubyGems](https://rubygems.org/gems/active_mutator).
 
-active_mutator mutates your code one small change at a time (`>` → `>=`,
-`&&` → `||`, delete a statement, force a condition…), runs exactly the
-examples that cover the mutated line, and reports every mutant your suite
-fails to kill. A surviving mutant is a behavior change no test notices —
-a precise, machine-verified test gap.
+active_mutator mutates your code one small change at a time (`>` becomes `>=`,
+`&&` becomes `||`, a statement gets deleted, a condition gets forced, and so
+on). It runs exactly the examples that cover the mutated line, and reports
+every mutant your suite fails to kill. A surviving mutant is a behavior
+change no test notices: a precise, machine-verified test gap.
 
 ## A surviving mutant, in one example
 
@@ -35,31 +38,31 @@ Surviving mutants:
     + total <= 100
 ```
 
-Nothing in the test suite calls `discount(100)` — the one input where `<`
-and `<=` disagree. The tests pass, coverage is green, and the boundary is
-still unverified. That gap is invisible to coverage and obvious to
+Nothing in the test suite calls `discount(100)`, the one input where `<`
+and `<=` disagree. The tests pass, and coverage is green. But the boundary
+is still unverified. That gap is invisible to coverage and obvious to
 mutation testing. Add `it { expect(calc.discount(100)).to eq(0) }` and the
 mutant is killed.
 
 ## What is mutation testing?
 
 Coverage answers "did a test run this line?" Mutation testing answers "would
-a test *notice* if this line were wrong?" — a materially different, and
-usually more useful, question.
+a test *notice* if this line were wrong?" That is a different, and usually
+more useful, question.
 
 active_mutator applies one small, syntactically valid change to your code
 (a "mutant") and re-runs only the examples that cover it. If a test fails,
 the mutant is **killed**: your tests correctly reject that wrong behavior.
 If every covering test still passes, the mutant **survived**: something
-changed and nothing noticed. A survivor is not a hypothetical — it's the
-exact line, the exact before/after diff, and proof that no assertion
+changed and nothing noticed. A survivor is not a hypothetical. It is the
+exact line, the exact before and after diff, and proof that no assertion
 depends on the difference.
 
 Mutation score is `(killed + timeout) / (killed + timeout + survived)`.
-100% is usually not the right target — some mutants are behaviorally
-*equivalent* to the original and can never be killed by any test — which is
-why active_mutator has a committed acceptance ledger for closing survivors
-out with a stated reason instead of chasing an unreachable score.
+100% is usually not the right target. Some mutants are behaviorally
+*equivalent* to the original and can never be killed by any test. That is
+why active_mutator has a committed acceptance ledger. It lets you close
+survivors out with a stated reason instead of chasing an unreachable score.
 
 Full primer, including the origin of the technique and further reading:
 **[`docs/guides/what-is-mutation-testing.md`](docs/guides/what-is-mutation-testing.md)**.
@@ -73,7 +76,7 @@ group :development, :test do
 end
 ```
 
-Requires Ruby ≥ 3.2, RSpec, and a green suite. Linux/macOS (MRI fork).
+Requires Ruby 3.2 or later, RSpec, and a green suite. Linux/macOS (MRI fork).
 
 ## Quick start
 
@@ -82,9 +85,10 @@ bundle install
 bundle exec active_mutator app/models/calculator.rb
 ```
 
-First run performs an instrumented baseline of your suite to build the
-coverage map (cached in `.active_mutator/`, refreshed incrementally after
-that — see [`docs/guides/how-it-works.md`](docs/guides/how-it-works.md)).
+The first run performs an instrumented baseline of your suite to build the
+coverage map. The map is cached in `.active_mutator/` and refreshed
+incrementally after that (see
+[`docs/guides/how-it-works.md`](docs/guides/how-it-works.md)).
 Then each mutant runs in its own fork against only its covering examples.
 
 ### Reading the output
@@ -115,52 +119,84 @@ Each character on the progress line is one mutant, printed as it finishes:
 
 | Char | Status | Meaning |
 |---|---|---|
-| `.` | `killed` | a covering test failed — good, the mutant is dead |
-| `S` | `survived` | every covering test passed — a test gap |
-| `T` | `timeout` | ran past its time budget — counted as detected (likely an infinite loop) |
+| `.` | `killed` | a covering test failed. Good, the mutant is dead |
+| `S` | `survived` | every covering test passed. This is a test gap |
+| `T` | `timeout` | ran past its time budget. Counted as detected (likely an infinite loop) |
 | `E` | `error` | the worker crashed, or the mutated code raised outside a test assertion |
-| `U` | `uncovered` | no test executes the mutated line at all — coverage debt, worse than a survivor |
-| `A` | `accepted` | matches a known-equivalent entry in the acceptance ledger — excluded from the score |
+| `U` | `uncovered` | no test executes the mutated line at all. This is coverage debt, worse than a survivor |
+| `A` | `accepted` | matches a known-equivalent entry in the acceptance ledger. Excluded from the score |
 
 `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`
-iff unaccepted survivors exist — `0` otherwise, including when there are
-only `uncovered`/`accepted`/`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
 
-1. **Subject discovery** — a Prism visitor finds every method (`def`) in
+1. **Subject discovery**: a Prism visitor finds every method (`def`) in
    your target files.
-2. **Source-span edits** — each operator emits byte-range text edits
-   against the original file, not a rewritten AST; every mutant is
+2. **Source-span edits**: each operator emits byte-range text edits
+   against the original file, not a rewritten AST. Every mutant is
    re-parsed with Prism and discarded (`invalid`) if the edit produced
    something that doesn't parse. No unparser is ever built or maintained.
-3. **Coverage-mapped test selection** — one instrumented baseline run maps
-   every source line to the examples that cover it; incremental runs
+3. **Coverage-mapped test selection**: one instrumented baseline run maps
+   every source line to the examples that cover it. Incremental runs
    refresh only what changed instead of re-running the whole suite.
-4. **Fork-per-mutant kill runs** — the parent preloads your app and spec
-   helper once; each mutant is inserted and exercised in its own fork
+4. **Fork-per-mutant kill runs**: the parent preloads your app and spec
+   helper once. Each mutant is inserted and exercised in its own fork
    against just its covering examples, so results can't bleed state
    between mutants.
 
 Full architecture, including the coverage-cache format, the fork pipeline,
-the serial lane for browser specs, timeout budgets, and every status —
+the serial lane for browser specs, timeout budgets, and every status, is in
 **[`docs/guides/how-it-works.md`](docs/guides/how-it-works.md)**.
 
 ## Usage
 
 ```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 — good), `survived` (test gap), `timeout`
-(counts as detected), `uncovered` (no covering example — coverage debt),
-`accepted` (known-equivalent, see ledger), `error`, `invalid` (discarded).
-Exit code 1 iff unaccepted survivors exist.
+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 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).
 
@@ -179,65 +215,126 @@ bundle exec active_mutator --changed --accept-survivors   # records to ledger
 git add .active_mutator_accepted.json                     # committed state
 ```
 
-Acceptance takes effect on the NEXT run (the accepting run still exits 1).
+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
 
 | Flag | Default | Meaning |
 |---|---|---|
 | `--jobs N` | half the cores | fork-pool width |
-| `--changed` | — | mutate uncommitted + untracked work |
-| `--since REF` | — | mutate methods changed since REF |
-| `--subject NAME` | — | one subject, e.g. `Foo#bar` |
-| `--format terminal\|json` | terminal | report format |
+| `--changed` | none | mutate uncommitted + untracked work |
+| `--since REF` | none | mutate methods changed since REF |
+| `--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 |
-| `--require FILE` | — | preload files (repeatable) |
+| `--[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
+Every active_mutator process sets `ENV["ACTIVE_MUTATOR"] = "1"`. Use it to
 guard SimpleCov or other tooling in your spec helper:
 
 ```ruby
 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 not mutated · `class << self` bodies and nested defs
-skipped · incremental baseline can miss examples that only cover changed
-code after the change (nightly `--force-baseline` recovers).
+Method bodies only (no class-macro/constant mutation). RSpec only.
+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
 
-- [What is mutation testing?](docs/guides/what-is-mutation-testing.md) —
-  the concepts: kill/survive, score, equivalent mutants, further reading.
-- [How it works](docs/guides/how-it-works.md) — architecture: subject
+- [What is mutation testing?](docs/guides/what-is-mutation-testing.md):
+  the concepts. Kill/survive, score, equivalent mutants, further reading.
+- [How it works](docs/guides/how-it-works.md): architecture. Subject
   discovery, source-span edits, the coverage map, the fork pipeline, and
   honest limits.
-- [Operator reference](docs/guides/operators.md) — every mutation
+- [Operator reference](docs/guides/operators.md): every mutation
   active_mutator can generate, with before/after examples and what a
   survivor of each one means.
-- [Mutation-check skill](docs/skills/mutation-check.md) — the agent-facing
-  workflow: run, read survivors, strengthen tests, or accept with a reason.
+- [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.
 
 ## Contributing
 
 Issues and pull requests welcome. Run `bundle exec rspec` before sending a
-change; `bundle exec active_mutator --changed` on your own diff before
-sending a change that touches `lib/` is a good idea for the same reason
-you'd want it run on any other codebase.
+change. Also run `bundle exec active_mutator --changed` on your own diff
+before sending a change that touches `lib/`. This is a good idea for the
+same reason you'd want it run on any other codebase.
 
 ## License
 

data/lib/active_mutator/accepted_ledger.rb

@@ -3,8 +3,12 @@ require "set"
 
 module ActiveMutator
   # Committed, repo-root ledger of accepted (equivalent) survivors.
-  # Deliberately NOT inside .active_mutator/ — that dir is gitignored and
+  # 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/atomic_file.rb

@@ -1,6 +1,6 @@
 module ActiveMutator
   # flock-guarded write-to-temp + rename. Concurrent runs in one repo (an
-  # agent plus a human — the dev-loop case) must not corrupt cache or ledger.
+  # agent plus a human, the dev-loop case) must not corrupt cache or ledger.
   module AtomicFile
     def self.write(path, content)
       File.open("#{path}.lock", File::CREAT | File::RDWR, 0o644) do |lock|

data/lib/active_mutator/baseline.rb

@@ -42,13 +42,22 @@ module ActiveMutator
 
     private
 
-    def run_baseline!
+    # The cache is disposable and must never be committed. Host projects
+    # rarely gitignore it themselves, so the directory ignores its own
+    # contents (the node_modules trick).
+    def prepare_cache_dir
       FileUtils.mkdir_p(@cache_dir)
+      ignore = File.join(@cache_dir, ".gitignore")
+      File.write(ignore, "*\n") unless File.exist?(ignore)
+    end
+
+    def run_baseline!
+      prepare_cache_dir
       env = baseline_env(@out_path)
-      # out: :err — the subprocess suite's progress output must not pollute
+      # out: :err: the subprocess suite's progress output must not pollute
       # our stdout (breaks `--format json` consumers).
       ok = system(env, "bundle", "exec", "rspec", chdir: @root, out: :err)
-      raise BaselineFailed, "baseline suite failed — fix the suite before mutating" unless ok
+      raise BaselineFailed, "baseline suite failed, fix the suite before mutating" unless ok
       raise BaselineFailed, "baseline produced no coverage output" unless File.exist?(@out_path)
     end
 
@@ -80,7 +89,7 @@ module ActiveMutator
       if targets.any?
         env = baseline_env(partial_out)
         ok = system(env, "bundle", "exec", "rspec", *targets, chdir: @root, out: :err)
-        raise BaselineFailed, "partial baseline run failed — fix the suite before mutating" unless ok
+        raise BaselineFailed, "partial baseline run failed, fix the suite before mutating" unless ok
         raise BaselineFailed, "partial baseline produced no output" unless File.exist?(partial_out)
       end
       merge_partial!(partial_out, delta)

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

@@ -1,5 +1,5 @@
 # Loaded standalone via RUBYOPT=-ractive_mutator/baseline_hooks in the host
-# project's suite — before rspec boots, so Coverage instruments everything
+# project's suite, before rspec boots, so Coverage instruments everything
 # the suite loads (including code loaded by spec_helper). Records per-example
 # coverage diffs and writes the inverted map to ACTIVE_MUTATOR_BASELINE_OUT.
 require "json"
@@ -53,7 +53,7 @@ if ENV["ACTIVE_MUTATOR_BASELINE_OUT"]
       root = ENV.fetch("ACTIVE_MUTATOR_ROOT")
       ActiveMutator::BaselineHooks::RECORDS[example.id] =
         ActiveMutator::BaselineHooks.diff_coverage(before, after, root)
-      # NOT example.execution_result.run_time — that is nil until after
+      # NOT example.execution_result.run_time: that is nil until after
       # around hooks complete.
       ActiveMutator::BaselineHooks::TIMES[example.id] = elapsed
     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