active_mutator 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfe7e211472b45836efb059eb37472307becf74e85b8441664e8cec836c10c26
-  data.tar.gz: 6e0ed299bc84b8c912e73314f58ea88cc2fbb783f6949aea14285a27ea2e5bd9
+  metadata.gz: '08222e2342f45fd4c9150cd9201383231f1add08c5c5582bccf74f4350c87181'
+  data.tar.gz: ae88865c407500e7b7fcc0cb9a0ab72fe90aa2860136f9bd523203a1baae9c35
 SHA512:
-  metadata.gz: 6153450b921e1647a13d14f4e473cc123c045ff738f2cea1b6786797e265b05bc7bc00233bdf66f192296be1c372f0c458f6910992d01716320033b86a0a00e9
-  data.tar.gz: b1d9c1133f21dbe6370651c2d00e7e4173620ac13986ce24e8b91931f5f5793985d41cf2f8a7be626b73c948b6a473dec99f6e3560f52630cdad83c8ab3d5d72
+  metadata.gz: c0ed008b82b47bf0e70e74bd51330eafaeb02f6c7241e5a19e2a75395293db1ccf02e3f13f3810abf2da1972f5b50b678e35bae4efb946b139aac22e0faccfd0
+  data.tar.gz: dd02830ae6b56cdc687cf90dc5131d1409298ac8e5d03217a57f92a044aca4dee6731043498e1f021d9eee4ef064af8cab80fb048263046dfe28fe719bef0077

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,27 @@ 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) |
+| `--[no-]class-level` | on | mutate class-level code (macros, constants, DSL/scope lambdas) via class-body subjects |
+| `--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 +278,92 @@ guard SimpleCov or other tooling in your spec helper:
 SimpleCov.start "rails" unless ENV["ACTIVE_MUTATOR"]
 ```
 
-## Known limits (v1.1)
+## 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`),
+`class_level` (`true`/`false`, default `true` — mutate class-level code),
+`class_level_closure_cap` (integer, default `10` — max constants a
+class-body mutant may reload before it is `skipped`).
+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
+```
 
-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).
+## Class-level mutation
+
+Class-level code — macros (`validates`, `scope`, `has_many`), constants,
+and DSL/scope lambdas — IS mutated. Each Zeitwerk-shaped file gets a
+`… (class body)` subject alongside its method subjects, and the same
+operator set runs over its class-level statements. Because re-running a
+macro *accumulates* rather than replaces (calling `validates` twice adds a
+second validator), a class-body mutant can't be inserted with `class_eval`
+the way a `def` mutant is. Instead active_mutator removes the target
+constant and re-evaluates the whole mutated file, reloading anything
+attached to it (includers, subclasses, extenders) in dependency order. See
+[`docs/guides/how-it-works.md`](docs/guides/how-it-works.md) for the full
+closure-reload pipeline.
+
+Disable it with `--no-class-level` (or `class_level: false` in the config
+file). A class-body mutant whose closure can't be reloaded faithfully — the
+closure exceeds `class_level_closure_cap` (default `10`), the constant was
+reopened elsewhere, or an attacher is anonymous/native — is reported
+`skipped` (progress char `-`): listed but **not counted in the score**,
+because a mutant we can't insert faithfully must not be called survived or
+killed.
+
+## Known limits
+
+Method bodies **and** Zeitwerk-shaped class bodies are mutated; the
+remaining limits are:
+
+- **Class-body mutation requires a Zeitwerk-shaped file** — exactly one
+  top-level class/module per file. Multi-constant files and core-class
+  monkey-patches/reopens are not class-body-mutated (issue #32). Their
+  method bodies still are.
+- **Most code inside blocks is not mutated.** `ActiveSupport::Concern` DSL
+  blocks (`included`/`prepended`/`class_methods do … end`) ARE mutated — their
+  bodies re-run as class-level code in the includer (issue #31). Every other
+  block (`has_many :x do … end` and any `do … end`/`{ … }` body) is pruned to
+  avoid false survivors from mutating code whose run-time context is unknown.
+- **Constants captured by value go stale.** A reference that holds the
+  target *by value* rather than by ancestry — an alias (`ALIAS = SomeClass`),
+  a registry the class was pushed into, a memoized instance, a class
+  variable captured at load — keeps pointing at the pre-reload object after
+  the closure reload. Such stale references can produce false survivors.
+- **Whole-file re-eval re-runs class-body side effects.** The reload
+  re-evaluates the target and every attacher's class body, so non-idempotent
+  load-time side effects (global self-registration, descendant tracking) run
+  twice — which can double or mask a count a spec asserts on.
+- **`refine`-based modules are not discovered or reloaded.** Refinements
+  are anonymous and don't appear in normal `ancestors`.
+- **RSpec only.** Test selection, worker setup, and the world-group filter
+  are all RSpec-API-shaped.
+- **Method-body scope details:** 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's residual blind spot:** constant-reference
+  detection handles the common case since 0.2; 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 +375,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,61 @@ 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)
+
+      pattern = constant_reference_pattern(File.read(abs))
+      return [] unless pattern
+
+      all_specs = spec_contents.keys
+
+      covering_specs = coverage_map.examples_covering_file(abs)
+                                   .map { |id| spec_file_of(id) }.to_a.uniq
+      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
+
+    # Regexp matching any textual reference to a constant DEFINED in `source`,
+    # or nil when the source defines none. Shared by newly_covering_candidates
+    # and Runner's phase-2 escalation so the escaping/word-boundary rules live
+    # in one place.
+    #
+    # 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.
+    def self.constant_reference_pattern(source)
+      constants = DefinedConstants.in_source(source)
+      return nil if constants.empty?
+
+      /\b(?:#{constants.map { |c| Regexp.escape(c) }.join("|")})\b/
+    end
   end
 end

data/lib/active_mutator/class_shape.rb

@@ -0,0 +1,47 @@
+module ActiveMutator
+  # Structural predicates over a parsed file that the class-level machinery
+  # must apply IDENTICALLY in more than one place. Centralized so the gates
+  # cannot drift:
+  #   - SubjectFinder decides which files get a class-body subject.
+  #   - ClosureReload decides which dependent files are safe to remove_const
+  #     and re-eval.
+  # Both need the same "is this file a single reloadable constant?" rule, and
+  # both need the same "does this class-body statement belong to another
+  # subject?" rule.
+  # `extend self`, not `module_function`: module_function copies each method
+  # onto the singleton at definition time, so a def-level mutant (which
+  # redefines the INSTANCE method in the fork) would never reach the singleton
+  # copy that callers invoke — an untestable false survivor. `extend self`
+  # keeps ONE method object, dispatched to via the singleton's ancestry.
+  module ClassShape
+    extend self
+
+    # Zeitwerk-shaped: the file defines exactly one top-level constant, so
+    # remove_const + whole-file re-eval reinstates precisely that constant
+    # (issue #32). A file with more than one would re-run macros on / reassign
+    # the constants that were NOT removed (accumulation and "already
+    # initialized constant" bugs).
+    #
+    # Counts every top-level constant-DEFINING form, not just `class`/`module`
+    # blocks: `Adapter = Class.new`, `Point = Struct.new(...)`,
+    # `Config = Data.define(...)`, and plain `CONST = ...` are ConstantWriteNodes
+    # (or ConstantPathWriteNodes) that a class/module-only count missed, letting
+    # a two-constant file slip through and get reassigned on re-eval.
+    def single_top_level_constant?(program)
+      program.statements.body.count { |s| defines_constant?(s) } == 1
+    end
+
+    def defines_constant?(node)
+      node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode) ||
+        node.is_a?(Prism::ConstantWriteNode) || node.is_a?(Prism::ConstantPathWriteNode)
+    end
+
+    # A class-body statement that is owned by a DIFFERENT subject — its own
+    # def, or a nested class/module/singleton-class that gets its own subjects.
+    # The class-body walk must neither collect edits for it nor delete it.
+    def owned_by_other_subject?(node)
+      node.is_a?(Prism::DefNode) || node.is_a?(Prism::ClassNode) ||
+        node.is_a?(Prism::ModuleNode) || node.is_a?(Prism::SingletonClassNode)
+    end
+  end
+end

data/lib/active_mutator/cli.rb

@@ -22,16 +22,21 @@ 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,
+        operators: [], class_level: true, class_level_closure_cap: 10
       }
+      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[:operators] << v }
+        o.on("--[no-]class-level", "Mutate class-level code: macros, constants, DSL lambdas (default: on)") { |v| options[:class_level] = 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 +48,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)