active_mutator 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5729b9385c24e575708a5227a3838ae28e09dd2ddf3e40e1883e9e74f7399275
-  data.tar.gz: 69b41b3304c8c008f54f6c20547ff9283d26a278eea706dc7cf923466dde1b5c
+  metadata.gz: 0c97d4e4b28fb22f07d54f258e65162b4a4e9c731ab89caa851610e1ff3d1a83
+  data.tar.gz: dfd2fdddc29f209281e45001ae7a21bd6d75fce6833a5f4086f3592d36378843
 SHA512:
-  metadata.gz: 3e0dce87a35314cb96e68e7051e3dfa8bbc329b58a3c41beef1201c7c5e8a3205d58a28593bf99382dfd1f9a9fd52859b44def8e2ee5d57dd0879e9dfcadec37
-  data.tar.gz: 5ec63925341ef8356801ee171e83af5b6323feb0f15838b1430421c9e5aaf73017d0e5ebaafb653039917a97144933e3572c2d182ba0544de27fbe60a0d7d6ca
+  metadata.gz: 983e510da62ef0a31abefd1342485e17a365013ce13eb16b9ad3a1b929ca5ff13c643c15ae9529c6b0def30215268b1a2c424d102489f4351d27b2c9cddd2ca1
+  data.tar.gz: 272643ac14e46cfba0e0ea95d4b9fe4cedc7ace3b7359eaabdf7bed60a8caf2451f84ba3986828f9528dfe402e9fe1fe4d9b20d7daa63f842ec728ebfb4ef2af

data/README.md

@@ -258,13 +258,23 @@ survivors show inline on the PR diff. Pairs with the CI recipe:
 | `--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 |
+| `--spec-path DIR` | `spec/` | where spec files live, relative to the project root (repeatable; the first use replaces the default `spec/`), e.g. `--spec-path engines/billing/spec --spec-path spec` |
 | `--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) |
 
+`--spec-path` tells active_mutator where spec files live (coverage
+classification, digests, escalation); RSpec's own discovery is still the
+project's job — a project with specs under `test/` also needs
+`--default-path test` in its `.rspec`. The serial-lane defaults stay
+`spec/system/` and `spec/features/` regardless of `--spec-path`; a
+custom spec root with browser specs should set `--serial-pattern`
+(e.g. `--serial-pattern test/system/`) itself.
+
 `--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
@@ -284,10 +294,15 @@ 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`,
+`spec_paths` (where spec files live, relative to the project root;
+replaces the default `spec`),
 `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`).
+`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
@@ -297,22 +312,72 @@ exclude:
   - lib/generated
 serial_patterns:
   - spec/system/
+spec_paths:
+  - engines/billing/spec
+  - spec
 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.
-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`.
+## 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
 

data/lib/active_mutator/baseline.rb

@@ -5,10 +5,11 @@ require "json"
 module ActiveMutator
   # Runs the host suite once, instrumented, in a subprocess. Produces and
   # caches the CoverageMap. Invalidation is coarse: any digest change in
-  # {app,lib,spec}/**/*.rb triggers a full re-run.
+  # {app,lib}/**/*.rb or the configured spec paths triggers a full re-run.
   class Baseline
-    def initialize(root:, cache_dir: File.join(root, ".active_mutator"))
+    def initialize(root:, spec_paths: ["spec"], cache_dir: File.join(root, ".active_mutator"))
       @root = root
+      @spec_paths = spec_paths
       @cache_dir = cache_dir
       @out_path = File.join(cache_dir, "coverage.json")
     end
@@ -19,13 +20,19 @@ module ActiveMutator
       digests = current_digests
       if !force && File.exist?(@out_path)
         map = CoverageMap.load(@out_path)
-        if map.fresh?(digests)
+        # A spec_paths change silently degrades the delta classifier: files
+        # under a removed spec path just vanish from the digest scan, so
+        # BaselineDelta treats their stale example records as untouched
+        # source coverage instead of dropping them. Force a full rebuild
+        # whenever the configured spec_paths differ from what the cache was
+        # stamped with.
+        if stored_spec_paths(map) == @spec_paths && map.fresh?(digests)
           @last_refresh = :cached
           return map
         end
-        if map.version == 2
+        if stored_spec_paths(map) == @spec_paths && map.version == 2
           delta = BaselineDelta.compute(old_digests: stored_digests(map), new_digests: digests,
-                                        coverage_map: map, root: @root)
+                                        coverage_map: map, root: @root, spec_paths: @spec_paths)
           unless delta.full?
             run_partial!(delta)
             stamp_digests(digests)
@@ -59,6 +66,25 @@ module ActiveMutator
       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 produced no coverage output" unless File.exist?(@out_path)
+
+      verify_complete!(@out_path)
+    end
+
+    # An aborted subprocess can still exit 0 with a partial map (RSpec
+    # rescues Errno::EPIPE and runs after(:suite)); stamping that as fresh
+    # silently reports every mutant uncovered. Payloads without the count
+    # predate this check and are accepted as-is.
+    def verify_complete!(out_path)
+      payload = JSON.parse(File.read(out_path))
+      expected = payload["expected_examples"]
+      return unless expected
+
+      recorded = payload.fetch("records", {}).size
+      return if recorded >= expected
+
+      raise BaselineFailed,
+            "baseline aborted early: #{recorded} of #{expected} examples recorded — " \
+            "re-run without interrupting the suite"
     end
 
     def baseline_env(out_path)
@@ -66,6 +92,7 @@ module ActiveMutator
         "ACTIVE_MUTATOR" => "1",
         "ACTIVE_MUTATOR_ROOT" => @root,
         "ACTIVE_MUTATOR_BASELINE_OUT" => out_path,
+        "ACTIVE_MUTATOR_SPEC_PATHS" => @spec_paths.join(":"),
         # RUBYOPT, not `rspec --require`: project .rspec requires (spec_helper
         # → app code) run before command-line requires, and Coverage misses
         # everything loaded before Coverage.start. -r fires before rspec boots.
@@ -83,6 +110,12 @@ module ActiveMutator
       JSON.parse(File.read(@out_path)).fetch("digests", {})
     end
 
+    # A pre-0.4.0 cache predates spec_paths and has no key; treat that as the
+    # old implicit default so existing default-config caches stay valid.
+    def stored_spec_paths(map)
+      JSON.parse(File.read(@out_path)).fetch("spec_paths", ["spec"])
+    end
+
     def run_partial!(delta)
       targets = delta.rerun_spec_files + delta.rerun_example_ids
       partial_out = File.join(@cache_dir, "partial.json")
@@ -91,6 +124,8 @@ module ActiveMutator
         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 produced no output" unless File.exist?(partial_out)
+
+        verify_complete!(partial_out)
       end
       merge_partial!(partial_out, delta)
     ensure
@@ -122,11 +157,14 @@ module ActiveMutator
     def stamp_digests(digests)
       data = JSON.parse(File.read(@out_path))
       data["digests"] = digests
+      data["spec_paths"] = @spec_paths
       AtomicFile.write(@out_path, JSON.generate(data))
     end
 
     def current_digests
-      files = Dir[File.join(@root, "{app,lib,spec}/**/*.rb")].sort
+      files = Dir[File.join(@root, "{app,lib}/**/*.rb")]
+      files += @spec_paths.flat_map { |sp| Dir[File.join(@root, sp, "**", "*.rb")] }
+      files = files.uniq.sort
       files += [File.join(@root, "Gemfile.lock"), File.join(@root, ".rspec")].select { |f| File.exist?(f) }
       files.to_h { |f| [f.delete_prefix("#{@root}/"), Digest::SHA256.file(f).hexdigest] }
     end

data/lib/active_mutator/baseline_delta.rb

@@ -15,10 +15,10 @@ module ActiveMutator
     # 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:)
+    def self.compute(old_digests:, new_digests:, coverage_map:, root:, spec_paths: ["spec"])
       changed = (old_digests.keys | new_digests.keys)
                 .reject { |k| old_digests[k] == new_digests[k] }
-      return FULL if changed.any? { |k| full_trigger?(k) }
+      return FULL if changed.any? { |k| full_trigger?(k, spec_paths: spec_paths) }
 
       rerun_spec_files = []
       rerun_example_ids = []
@@ -35,7 +35,7 @@ module ActiveMutator
       changed.each do |rel|
         added = !old_digests.key?(rel)
         deleted = !new_digests.key?(rel)
-        if rel.start_with?("spec/")
+        if spec_paths.any? { |sp| rel.start_with?("#{sp}/") }
           owned = coverage_map.examples_for_spec_file(rel)
           if deleted
             # A deleted spec file with no records is support-like: other spec
@@ -54,7 +54,7 @@ module ActiveMutator
             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)] }
+            spec_contents ||= spec_file_contents(root: root, spec_paths: spec_paths)
             candidates = newly_covering_candidates(root: root, rel: rel, coverage_map: coverage_map,
                                                    spec_contents: spec_contents)
             return FULL if candidates == :full
@@ -71,8 +71,17 @@ module ActiveMutator
                 drop_source_files: drop_source_files.uniq.sort)
     end
 
-    def self.full_trigger?(rel)
-      rel.start_with?("spec/support/") || !rel.end_with?(".rb")
+    def self.full_trigger?(rel, spec_paths: ["spec"])
+      spec_paths.any? { |sp| rel.start_with?("#{sp}/support/") } || !rel.end_with?(".rb")
+    end
+
+    # All *_spec.rb files under the configured spec paths, absolute path =>
+    # file content. Shared by the delta scan and Runner's phase-2 escalation
+    # so "where do specs live" is answered in exactly one place (#35).
+    def self.spec_file_contents(root:, spec_paths:)
+      spec_paths
+        .flat_map { |sp| Dir[File.join(root, sp, "**", "*_spec.rb")] }
+        .uniq.to_h { |f| [f, File.read(f)] }
     end
 
     # #11: an unchanged spec file can START covering a changed source file
@@ -84,21 +93,13 @@ module ActiveMutator
       abs = File.join(root, rel)
       return [] unless File.exist?(abs)
 
-      constants = DefinedConstants.in_source(File.read(abs))
-      return [] if constants.empty?
+      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
-      # 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)
@@ -119,5 +120,24 @@ module ActiveMutator
     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/baseline_hooks.rb

@@ -9,7 +9,8 @@ module ActiveMutator
     RECORDS = {}
     TIMES = {}
 
-    def self.diff_coverage(before, after, root)
+    def self.diff_coverage(before, after, root, spec_paths: ["spec"])
+      prefixes = spec_paths.map { |sp| "/#{sp}/" }
       hits = []
       after.each do |path, data|
         next unless path.start_with?(root)
@@ -19,7 +20,7 @@ module ActiveMutator
         # spec/fixtures/ tree), which would otherwise falsely exclude every
         # file under it.
         relative = path.delete_prefix(root)
-        next if relative.start_with?("/spec/")
+        next if prefixes.any? { |p| relative.start_with?(p) }
 
         before_lines = before.dig(path, :lines)
         data[:lines].each_with_index do |count, idx|
@@ -32,8 +33,10 @@ module ActiveMutator
       hits
     end
 
-    def self.build_payload(records, times)
-      { "version" => 2, "records" => records, "times" => times }
+    def self.build_payload(records, times, expected_examples: nil)
+      payload = { "version" => 2, "records" => records, "times" => times }
+      payload["expected_examples"] = expected_examples if expected_examples
+      payload
     end
   end
 end
@@ -51,16 +54,22 @@ if ENV["ACTIVE_MUTATOR_BASELINE_OUT"]
       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
       after = Coverage.peek_result
       root = ENV.fetch("ACTIVE_MUTATOR_ROOT")
+      spec_paths = ENV.fetch("ACTIVE_MUTATOR_SPEC_PATHS", "spec").split(":")
       ActiveMutator::BaselineHooks::RECORDS[example.id] =
-        ActiveMutator::BaselineHooks.diff_coverage(before, after, root)
+        ActiveMutator::BaselineHooks.diff_coverage(before, after, root, spec_paths: spec_paths)
       # NOT example.execution_result.run_time: that is nil until after
       # around hooks complete.
       ActiveMutator::BaselineHooks::TIMES[example.id] = elapsed
     end
 
     config.after(:suite) do
+      # The expected count lets the parent detect an aborted run: RSpec
+      # swallows some mid-suite failures (e.g. Errno::EPIPE on a closed
+      # stdout) yet still runs after(:suite) and exits 0, which would stamp
+      # a partial coverage map as a fresh, trusted baseline.
       payload = ActiveMutator::BaselineHooks.build_payload(
-        ActiveMutator::BaselineHooks::RECORDS, ActiveMutator::BaselineHooks::TIMES
+        ActiveMutator::BaselineHooks::RECORDS, ActiveMutator::BaselineHooks::TIMES,
+        expected_examples: RSpec.world.example_count
       )
       File.write(ENV.fetch("ACTIVE_MUTATOR_BASELINE_OUT"), JSON.generate(payload))
     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

@@ -3,6 +3,13 @@ require "optparse"
 module ActiveMutator
   module CLI
     def self.run(argv)
+      # Handled before OptionParser: its built-in --version handler prints
+      # "version unknown" and exits the process.
+      if argv.include?("--version")
+        puts "active_mutator #{VERSION}"
+        return 0
+      end
+
       Runner.new(parse(argv)).call
     rescue OptionParser::ParseError, Error => e
       warn "active_mutator: #{e.message}"
@@ -22,9 +29,10 @@ 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/"],
+        spec_paths: ["spec"],
         browser_boot_seconds: 15.0, accept_survivors: false, exclude: [],
         max_mutants: nil, debug_plan: false, fail_at: nil, adaptive_timeout: true,
-        operator_paths: []
+        operators: [], class_level: true, class_level_closure_cap: 10
       }
       options.merge!(ConfigFile.load(Dir.pwd))
       paths = OptionParser.new do |o|
@@ -35,7 +43,8 @@ module ActiveMutator
         o.on("--jobs N", Integer, "Concurrent workers (default: half the CPU count)") { |v| options[:jobs] = 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("--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 }
@@ -46,6 +55,11 @@ module ActiveMutator
           options[:serial_patterns_replaced] = true
           options[:serial_patterns] << v
         end
+        o.on("--spec-path DIR", "Directory holding spec files, relative to root (repeatable; replaces the default spec/ on first use)") do |v|
+          options[:spec_paths] = [] unless options[:spec_paths_replaced]
+          options[:spec_paths_replaced] = true
+          options[:spec_paths] << 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 }
@@ -58,6 +72,12 @@ module ActiveMutator
         end
       end.parse(argv)
       options.delete(:serial_patterns_replaced)
+      options.delete(:spec_paths_replaced)
+      options[:spec_paths] = options[:spec_paths].map { |sp| sp.sub(%r{/+\z}, "") }
+      raise OptionParser::InvalidArgument, "--spec-path list must not be empty" if options[:spec_paths].empty?
+      if options[:spec_paths].any? { |sp| sp.strip.empty? }
+        raise OptionParser::InvalidArgument, "--spec-path entries must not be blank"
+      end
 
       Config.new(paths: paths, root: Dir.pwd, **options)
     end