active_mutator 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c401b5edbafa0a072b6672e088a9016f918d9e76ce6b264a9e2a054b1b538cc6
-  data.tar.gz: d2a1908e950d8687e68524184efc2bce200d595be3b25f31e3a0e92a95325b3e
+  metadata.gz: cfe7e211472b45836efb059eb37472307becf74e85b8441664e8cec836c10c26
+  data.tar.gz: 6e0ed299bc84b8c912e73314f58ea88cc2fbb783f6949aea14285a27ea2e5bd9
 SHA512:
-  metadata.gz: 9d42e2e4a207ab1c6ced606eeeee342389b503da5055e207d282df220f112537f90b5f967079dfd76060d740f710d5441c8422565e7bdad314fa4bc9cf5d07c6
-  data.tar.gz: 3e226d88dc71b5b0b698f5e2a1148a38c7f6b12e0cd47411033368a0bf7d18a90d0ca8243fa3d2841ebd1b1be4cfb554c41732b4e1eacc2961f6477ddb692cc7
+  metadata.gz: 6153450b921e1647a13d14f4e473cc123c045ff738f2cea1b6786797e265b05bc7bc00233bdf66f192296be1c372f0c458f6910992d01716320033b86a0a00e9
+  data.tar.gz: b1d9c1133f21dbe6370651c2d00e7e4173620ac13986ce24e8b91931f5f5793985d41cf2f8a7be626b73c948b6a473dec99f6e3560f52630cdad83c8ab3d5d72

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,36 +119,36 @@ 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, `0` otherwise, including when there are
+only `uncovered`, `accepted`, or `error` results.
 
 ## 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
@@ -157,10 +161,11 @@ 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.
+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.
 
 Score = (killed + timeout) / (killed + timeout + survived).
 
@@ -179,7 +184,7 @@ 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.
 Agent workflow: see [`docs/skills/mutation-check.md`](docs/skills/mutation-check.md).
 
 ## CI recipe
@@ -193,9 +198,9 @@ Agent workflow: see [`docs/skills/mutation-check.md`](docs/skills/mutation-check
 | 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` |
+| `--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 |
 | `--accept-survivors` | off | record survivors to the acceptance ledger |
 | `--force-baseline` | off | ignore cached coverage map |
@@ -203,9 +208,9 @@ Agent workflow: see [`docs/skills/mutation-check.md`](docs/skills/mutation-check
 | `--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) |
+| `--require FILE` | none | preload files (repeatable) |
 
-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
@@ -214,30 +219,30 @@ 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).
+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).
 
 ## 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.
+- [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,7 +3,7 @@ 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.
   class AcceptedLedger
     FILENAME = ".active_mutator_accepted.json"

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_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/coverage_map.rb

@@ -3,7 +3,7 @@ require "json"
 module ActiveMutator
   # Cache format v2: primary data is per-example `records`
   # ({example_id => [[abs_path, line], ...]}); the inverted index is derived
-  # in memory at load. A missing/old version is simply stale — the cache is
+  # in memory at load. A missing/old version is simply stale: the cache is
   # disposable, so there is no migration path, only regeneration.
   class CoverageMap
     def self.load(path) = new(JSON.parse(File.read(path)))

data/lib/active_mutator/fingerprint.rb

@@ -1,7 +1,7 @@
 module ActiveMutator
   # Line-number-independent identity for a mutant, used by the acceptance
   # ledger. `ordinal` disambiguates byte-identical mutants within one subject
-  # (e.g. the two `>` in `a > 0 && b > 0`) by source order — without it,
+  # (e.g. the two `>` in `a > 0 && b > 0`) by source order. Without it,
   # accepting one would silently accept both.
   Fingerprint = Data.define(:file, :subject, :description, :original_snippet, :ordinal) do
     def self.for_mutations(mutations, root:)

data/lib/active_mutator/runner.rb

@@ -121,7 +121,7 @@ module ActiveMutator
 
     # A preloaded helper commonly starts SimpleCov. Its at_exit would fire in
     # THIS parent process at the end of the mutation run, clobbering the
-    # project's real coverage data — and minimum_coverage would exit(1) for a
+    # project's real coverage data, and minimum_coverage would exit(1) for a
     # bogus reason. Neutralize it.
     def disarm_simplecov
       SimpleCov.at_exit {} if defined?(SimpleCov)
@@ -136,7 +136,7 @@ module ActiveMutator
 
     def warn_stale(ledger, all_fingerprints)
       ledger.stale_entries(all_fingerprints).each do |entry|
-        warn "active_mutator: stale accepted fingerprint (no matching mutant): #{entry.subject} — #{entry.description}"
+        warn "active_mutator: stale accepted fingerprint (no matching mutant): #{entry.subject}, #{entry.description}"
       end
     end
   end

data/lib/active_mutator/scheduler.rb

@@ -5,10 +5,14 @@ module ActiveMutator
   # Parent enforces per-item deadlines with SIGKILL (worker-side timeouts
   # cannot interrupt all infinite loops).
   class Scheduler
-    def initialize(jobs:, worker: Worker.method(:run), on_result: nil)
+    OrphanedError = Class.new(Error)
+
+    def initialize(jobs:, worker: Worker.method(:run), on_result: nil,
+                   orphaned: -> { Process.ppid == 1 })
       @jobs = jobs
       @worker = worker
       @on_result = on_result
+      @orphaned = orphaned
     end
 
     def run(items)
@@ -32,6 +36,7 @@ module ActiveMutator
       queue = items.dup
       results = []
       until queue.empty? && running.empty?
+        abort_if_orphaned!(running)
         spawn(queue.shift, running) while running.size < width && !queue.empty?
         reap(running, results)
         sleep 0.02 unless running.empty?
@@ -39,6 +44,22 @@ module ActiveMutator
       results
     end
 
+    # SIGKILL on the parent (or a closed terminal, or CI teardown) cannot be
+    # trapped, so a killed run would otherwise keep forking through the whole
+    # queue with nobody supervising it. Orphaned processes get reparented to
+    # init/launchd (ppid 1); when that happens, stop everything and bail.
+    def abort_if_orphaned!(running)
+      return unless @orphaned.call
+
+      running.each_key do |pid|
+        kill(pid)
+      rescue StandardError
+        nil
+      end
+      running.clear
+      raise OrphanedError, "parent process died; aborting mutation run"
+    end
+
     def spawn(item, running)
       reader, writer = IO.pipe
       pid = fork do
@@ -86,7 +107,7 @@ module ActiveMutator
     def kill(pid)
       Process.kill("KILL", -pid) # negative pid = whole process group
     rescue Errno::ESRCH, Errno::EPERM
-      # Group not established yet (setpgid race) or already gone — direct kill.
+      # Group not established yet (setpgid race) or already gone: direct kill.
       begin
         Process.kill("KILL", pid)
       rescue Errno::ESRCH
@@ -100,7 +121,7 @@ module ActiveMutator
       end
     end
 
-    # Returns {sig => previous_handler} so #run can restore on exit —
+    # Returns {sig => previous_handler} so #run can restore on exit,
     # otherwise our traps permanently replace the host's (e.g. RSpec's Ctrl-C).
     def install_signal_handlers(running)
       %w[INT TERM].to_h do |sig|

data/lib/active_mutator/version.rb

@@ -1,3 +1,3 @@
 module ActiveMutator
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/active_mutator/worker.rb

@@ -3,7 +3,7 @@ require "set"
 
 module ActiveMutator
   # Runs INSIDE a fork. Order is critical: RSpec's setup phase loads the spec
-  # files, whose spec_helper/rails_helper loads the application — only THEN
+  # files, whose spec_helper/rails_helper loads the application. Only THEN
   # can the mutation be inserted over the loaded original. Insert-first would
   # NameError on any project not preloaded in the parent (all non-Rails
   # projects), and loading app code after insertion would silently restore
@@ -47,7 +47,7 @@ module ActiveMutator
       @writer.flush if @writer.respond_to?(:flush)
     end
 
-    # RSpec.world holds every group registered in the process — including any
+    # RSpec.world holds every group registered in the process, including any
     # top-level groups evaluated while the PARENT preloaded the spec helper
     # (spec/support files with RSpec.describe at load time are common). Those
     # leak into the fork; running them would report their failures as false

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_mutator
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Daniel John
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -52,10 +52,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
-description: 'Mutation testing for Ruby and Rails: Prism-based source-span mutations
+description: Mutation testing for Ruby and Rails. Uses Prism-based source-span mutations
   (no unparser), coverage-mapped test selection, and a fork-per-mutant kill pipeline.
-  Scopes to changed methods for a fast dev loop, or a diff for CI, with an incremental
-  coverage baseline and a committed acceptance ledger for equivalent mutants.'
+  Scopes to changed methods for a fast dev loop, or to a diff for CI. Includes an
+  incremental coverage baseline and a committed acceptance ledger for equivalent mutants.
 email:
 executables:
 - active_mutator