active_mutator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c401b5edbafa0a072b6672e088a9016f918d9e76ce6b264a9e2a054b1b538cc6
+  data.tar.gz: d2a1908e950d8687e68524184efc2bce200d595be3b25f31e3a0e92a95325b3e
+SHA512:
+  metadata.gz: 9d42e2e4a207ab1c6ced606eeeee342389b503da5055e207d282df220f112537f90b5f967079dfd76060d740f710d5441c8422565e7bdad314fa4bc9cf5d07c6
+  data.tar.gz: 3e226d88dc71b5b0b698f5e2a1148a38c7f6b12e0cd47411033368a0bf7d18a90d0ca8243fa3d2841ebd1b1be4cfb554c41732b4e1eacc2961f6477ddb692cc7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel John
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,244 @@
+# active_mutator
+
+Mutation testing for Ruby, built on [Prism](https://github.com/ruby/prism).
+Open source, RSpec-integrated, Rails-first.
+
+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.
+
+## A surviving mutant, in one example
+
+```ruby
+def discount(total)
+  return 0 if total < 100
+  total / 10
+end
+```
+
+```ruby
+it { expect(calc.discount(50)).to eq(0) }
+it { expect(calc.discount(200)).to eq(20) }
+```
+
+Both examples pass. Line coverage on `discount` is 100%. Run active_mutator
+and one mutant survives anyway:
+
+```
+Surviving mutants:
+
+  Calculator#discount (lib/calculator.rb:11)
+    replace `<` with `<=`
+    - total < 100
+    + 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
+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.
+
+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
+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.
+
+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)**.
+
+## Install
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem "active_mutator"
+end
+```
+
+Requires Ruby ≥ 3.2, RSpec, and a green suite. Linux/macOS (MRI fork).
+
+## Quick start
+
+```bash
+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)).
+Then each mutant runs in its own fork against only its covering examples.
+
+### Reading the output
+
+```
+$ bundle exec active_mutator app/models/calculator.rb
+
+.....S..T...U..A....
+
+killed: 14
+survived: 1
+timeout: 1
+error: 0
+uncovered: 1
+accepted: 1
+invalid (discarded): 2
+Mutation score: 93.8%
+
+Surviving mutants:
+
+  Calculator#discount (app/models/calculator.rb:9)
+    replace `<` with `<=`
+    - total < 100
+    + total <= 100
+```
+
+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) |
+| `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 |
+
+`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.
+
+## How it works, compactly
+
+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
+   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
+   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
+   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 —
+**[`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 --changed                # uncommitted work only (dev loop)
+active_mutator --since origin/main      # PR scope (CI)
+active_mutator --subject 'Foo::Bar#baz' # one method
+```
+
+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.
+
+Score = (killed + timeout) / (killed + timeout + survived).
+
+## The dev loop
+
+TDD until green, then verify the tests constrain the behavior:
+
+```bash
+bundle exec active_mutator --changed --format json
+```
+
+Kill survivors by writing the missing tests. For genuine equivalent mutants:
+
+```bash
+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).
+Agent workflow: see [`docs/skills/mutation-check.md`](docs/skills/mutation-check.md).
+
+## CI recipe
+
+- Per-PR: `active_mutator --since origin/main` (minutes)
+- Nightly: `active_mutator --force-baseline` (full run; also recovers the
+  incremental baseline's newly-covering-example blind spot)
+
+## 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 |
+| `--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) |
+
+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"]
+```
+
+## 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).
+
+## 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
+  discovery, source-span edits, the coverage map, the fork pipeline, and
+  honest limits.
+- [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.
+
+## 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.
+
+## License
+
+[MIT](LICENSE).

data/exe/active_mutator

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require "active_mutator"
+
+exit ActiveMutator::CLI.run(ARGV)

data/lib/active_mutator/accepted_ledger.rb

@@ -0,0 +1,45 @@
+require "json"
+require "set"
+
+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.
+  class AcceptedLedger
+    FILENAME = ".active_mutator_accepted.json"
+
+    def self.load(root)
+      path = File.join(root, FILENAME)
+      entries = File.exist?(path) ? JSON.parse(File.read(path)) : []
+      new(path, entries.map { |e| from_hash(e) })
+    end
+
+    def self.from_hash(hash)
+      Fingerprint.new(file: hash.fetch("file"), subject: hash.fetch("subject"),
+                      description: hash.fetch("description"),
+                      original_snippet: hash.fetch("original_snippet"),
+                      ordinal: hash.fetch("ordinal"))
+    end
+
+    def initialize(path, entries)
+      @path = path
+      @entries = entries
+    end
+
+    def accepted?(fingerprint) = @entries.include?(fingerprint)
+
+    def stale_entries(all_current_fingerprints)
+      current = all_current_fingerprints.to_set
+      @entries.reject { |e| current.include?(e) }
+    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) }
+      AtomicFile.write(@path, JSON.pretty_generate(@entries.map(&:to_h)))
+      nil
+    end
+  end
+end

data/lib/active_mutator/analysis.rb

@@ -0,0 +1,3 @@
+module ActiveMutator
+  Analysis = Data.define(:mutations, :invalid_count)
+end

data/lib/active_mutator/atomic_file.rb

@@ -0,0 +1,15 @@
+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.
+  module AtomicFile
+    def self.write(path, content)
+      File.open("#{path}.lock", File::CREAT | File::RDWR, 0o644) do |lock|
+        lock.flock(File::LOCK_EX)
+        tmp = "#{path}.tmp#{Process.pid}"
+        File.write(tmp, content)
+        File.rename(tmp, path)
+      end
+      nil
+    end
+  end
+end

data/lib/active_mutator/baseline.rb

@@ -0,0 +1,125 @@
+require "digest"
+require "fileutils"
+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.
+  class Baseline
+    def initialize(root:, cache_dir: File.join(root, ".active_mutator"))
+      @root = root
+      @cache_dir = cache_dir
+      @out_path = File.join(cache_dir, "coverage.json")
+    end
+
+    attr_reader :last_refresh
+
+    def coverage_map(force: false)
+      digests = current_digests
+      if !force && File.exist?(@out_path)
+        map = CoverageMap.load(@out_path)
+        if map.fresh?(digests)
+          @last_refresh = :cached
+          return map
+        end
+        if map.version == 2
+          delta = BaselineDelta.compute(old_digests: stored_digests(map), new_digests: digests,
+                                        coverage_map: map, root: @root)
+          unless delta.full?
+            run_partial!(delta)
+            stamp_digests(digests)
+            @last_refresh = :partial
+            return CoverageMap.load(@out_path)
+          end
+        end
+      end
+      run_baseline!
+      stamp_digests(digests)
+      @last_refresh = :full
+      CoverageMap.load(@out_path)
+    end
+
+    private
+
+    def run_baseline!
+      FileUtils.mkdir_p(@cache_dir)
+      env = baseline_env(@out_path)
+      # 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 produced no coverage output" unless File.exist?(@out_path)
+    end
+
+    def baseline_env(out_path)
+      {
+        "ACTIVE_MUTATOR" => "1",
+        "ACTIVE_MUTATOR_ROOT" => @root,
+        "ACTIVE_MUTATOR_BASELINE_OUT" => out_path,
+        # 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.
+        #
+        # Absolute path, not the gem-relative "active_mutator/baseline_hooks":
+        # `bundle exec` appends its own "-rbundler/setup" to RUBYOPT AFTER
+        # whatever RUBYOPT already held, so a bare gem-relative require here
+        # would run before Bundler has put this gem's lib/ on $LOAD_PATH and
+        # raise LoadError. An absolute path bypasses $LOAD_PATH entirely.
+        "RUBYOPT" => "-r#{File.expand_path("baseline_hooks", __dir__)}"
+      }
+    end
+
+    def stored_digests(map)
+      JSON.parse(File.read(@out_path)).fetch("digests", {})
+    end
+
+    def run_partial!(delta)
+      targets = delta.rerun_spec_files + delta.rerun_example_ids
+      partial_out = File.join(@cache_dir, "partial.json")
+      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 produced no output" unless File.exist?(partial_out)
+      end
+      merge_partial!(partial_out, delta)
+    ensure
+      FileUtils.rm_f(partial_out) if partial_out
+    end
+
+    def merge_partial!(partial_out, delta)
+      cache = JSON.parse(File.read(@out_path))
+      part = File.exist?(partial_out) ? JSON.parse(File.read(partial_out)) : { "records" => {}, "times" => {} }
+
+      rerun_prefixes = delta.rerun_spec_files.map { |rel| "#{rel}[" }
+      obsolete = lambda do |example_id|
+        bare = example_id.sub(%r{\A\./}, "")
+        delta.rerun_example_ids.include?(example_id) ||
+          delta.drop_example_ids.include?(example_id) ||
+          rerun_prefixes.any? { |p| bare.start_with?(p) }
+      end
+
+      cache["records"].reject! { |id, _| obsolete.call(id) }
+      cache["times"].reject! { |id, _| obsolete.call(id) }
+      cache["records"].each_value do |hits|
+        hits.reject! { |(path, _)| delta.drop_source_files.include?(path) }
+      end
+      cache["records"].merge!(part.fetch("records", {}))
+      cache["times"].merge!(part.fetch("times", {}))
+      AtomicFile.write(@out_path, JSON.generate(cache))
+    end
+
+    def stamp_digests(digests)
+      data = JSON.parse(File.read(@out_path))
+      data["digests"] = digests
+      AtomicFile.write(@out_path, JSON.generate(data))
+    end
+
+    def current_digests
+      files = Dir[File.join(@root, "{app,lib,spec}/**/*.rb")].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
+  end
+end

data/lib/active_mutator/baseline_delta.rb

@@ -0,0 +1,57 @@
+module ActiveMutator
+  # Decides how to refresh a stale coverage cache: surgically (re-run only
+  # affected spec files / examples) or fully (the safe fallback). Rules per
+  # the v1.1 spec's delta table; anything ambiguous prefers full.
+  class BaselineDelta
+    Delta = Data.define(:full, :rerun_spec_files, :rerun_example_ids,
+                        :drop_example_ids, :drop_source_files) do
+      def full? = full
+    end
+
+    FULL = Delta.new(full: true, rerun_spec_files: [], rerun_example_ids: [],
+                     drop_example_ids: [], drop_source_files: [])
+
+    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] }
+      return FULL if changed.any? { |k| full_trigger?(k) }
+
+      rerun_spec_files = []
+      rerun_example_ids = []
+      drop_example_ids = []
+      drop_source_files = []
+
+      changed.each do |rel|
+        added = !old_digests.key?(rel)
+        deleted = !new_digests.key?(rel)
+        if rel.start_with?("spec/")
+          owned = coverage_map.examples_for_spec_file(rel)
+          if deleted
+            # A deleted spec file with no records is support-like: other spec
+            # files may require it, and partial re-runs would explode. Full.
+            return FULL if owned.empty?
+            drop_example_ids.concat(owned)
+          elsif !added && owned.empty?
+            return FULL # pre-existing spec file owning no examples: support-like
+          else
+            rerun_spec_files << rel
+          end
+        else
+          abs = File.join(root, rel)
+          drop_source_files << abs if deleted
+          rerun_example_ids.concat(coverage_map.examples_covering_file(abs)) unless added
+        end
+      end
+
+      Delta.new(full: false,
+                rerun_spec_files: rerun_spec_files.uniq.sort,
+                rerun_example_ids: rerun_example_ids.uniq.sort,
+                drop_example_ids: drop_example_ids.uniq.sort,
+                drop_source_files: drop_source_files.uniq.sort)
+    end
+
+    def self.full_trigger?(rel)
+      rel.start_with?("spec/support/") || !rel.end_with?(".rb")
+    end
+  end
+end

data/lib/active_mutator/baseline_hooks.rb

@@ -0,0 +1,68 @@
+# Loaded standalone via RUBYOPT=-ractive_mutator/baseline_hooks in the host
+# 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"
+
+module ActiveMutator
+  module BaselineHooks
+    RECORDS = {}
+    TIMES = {}
+
+    def self.diff_coverage(before, after, root)
+      hits = []
+      after.each do |path, data|
+        next unless path.start_with?(root)
+
+        # Relative to root, not a global substring check: `root` itself may
+        # contain "/spec/" (e.g. a fixture nested under this gem's own
+        # spec/fixtures/ tree), which would otherwise falsely exclude every
+        # file under it.
+        relative = path.delete_prefix(root)
+        next if relative.start_with?("/spec/")
+
+        before_lines = before.dig(path, :lines)
+        data[:lines].each_with_index do |count, idx|
+          next if count.nil?
+
+          previous = before_lines ? before_lines[idx].to_i : 0
+          hits << [path, idx + 1] if count > previous
+        end
+      end
+      hits
+    end
+
+    def self.build_payload(records, times)
+      { "version" => 2, "records" => records, "times" => times }
+    end
+  end
+end
+
+if ENV["ACTIVE_MUTATOR_BASELINE_OUT"]
+  require "coverage"
+  Coverage.start(lines: true)
+  require "rspec/core" # loaded via RUBYOPT, so rspec isn't up yet
+
+  RSpec.configure do |config|
+    config.around(:each) do |example|
+      before = Coverage.peek_result
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      example.run
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+      after = Coverage.peek_result
+      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
+      # around hooks complete.
+      ActiveMutator::BaselineHooks::TIMES[example.id] = elapsed
+    end
+
+    config.after(:suite) do
+      payload = ActiveMutator::BaselineHooks.build_payload(
+        ActiveMutator::BaselineHooks::RECORDS, ActiveMutator::BaselineHooks::TIMES
+      )
+      File.write(ENV.fetch("ACTIVE_MUTATOR_BASELINE_OUT"), JSON.generate(payload))
+    end
+  end
+end

data/lib/active_mutator/cli.rb

@@ -0,0 +1,53 @@
+require "optparse"
+
+module ActiveMutator
+  module CLI
+    def self.run(argv)
+      Runner.new(parse(argv)).call
+    rescue OptionParser::ParseError, Error => e
+      warn "active_mutator: #{e.message}"
+      2
+    end
+
+    def self.parse(argv)
+      options = {
+        # Half the cores, not all of them: each worker pays full RSpec setup,
+        # and system-spec workers boot a browser + app server. Full-core
+        # oversubscription starves workers of CPU and turns slow-but-honest
+        # kills into false timeouts (observed on a real Rails monolith).
+        since: nil, subject_filter: nil, jobs: [Etc.nprocessors / 2, 1].max,
+        format: :terminal,
+        # Budgets derive from baseline times measured warm and unloaded; the
+        # factor must absorb parallel-load slowdown, and the floor the fork's
+        # 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
+      }
+      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("--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("--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 }
+        o.on("--preload-helper FILE", "Spec helper to preload in the parent (default: auto-detect)") { |v| options[:preload_helper] = v }
+        o.on("--no-preload-helper", "Skip spec-helper preload") { options[:preload_helper] = :none }
+        o.on("--serial-pattern PAT", "Covering-path prefix that forces the serial lane (repeatable; replaces defaults on first use)") do |v|
+          options[:serial_patterns] = [] unless options[:serial_patterns_replaced]
+          options[:serial_patterns_replaced] = true
+          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("--accept-survivors", "Record surviving mutants into the acceptance ledger") { options[:accept_survivors] = true }
+      end.parse(argv)
+      options.delete(:serial_patterns_replaced)
+
+      Config.new(paths: paths, root: Dir.pwd, **options)
+    end
+  end
+end

data/lib/active_mutator/config.rb

@@ -0,0 +1,8 @@
+require "etc"
+
+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)
+end