active_mutator 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60c123ba92745825d5041728a14144e2cad95ba814d54fcb72bba40e1d5c0089
-  data.tar.gz: b7f96c322c455aa01d4ef19e04aa017f61fecb82347b1da7e315cfdc4316708e
+  metadata.gz: cf0b7bed1f6b35d6ab688affd01cb2ccc362944019ae5c18bff2e1205cccb53e
+  data.tar.gz: 9b4d7cac2fc3f8e3a6d737db4aa7f3b8f3f46c00baa275669fecbc5752e50910
 SHA512:
-  metadata.gz: 134766964d548d79002d0364046d6a46cb9a3b3d14b334c7d7ee67b3581865c31f10184bd7666d59f5732122dbc74f8c8ffdd7ee14664cd610c38ba64675fc31
-  data.tar.gz: 22bd7813d2a1d061a045a3bc3c7cc2d21c31b3d34f6c8b26e0f2433921b131c124f0f652e3367657bfcc26e987dd7416763c33e05d3e074cfa688703047ec8e2
+  metadata.gz: f2ed986856e22c4881936ae20f66bac4ecdc57b31239b5786942be6c2128516db64542be9185da5f9e8bc06ad1acd893d9e231602e1cf553ad7c74d60af9ef61
+  data.tar.gz: 8f8bd75ed8572b8e1eee883644b412bc9e718eeb0b85f35e22d8f27b6f937113c505bccadca869fd33546895bbf68126a30b9931fc755c3df8d71e33b8168bb0

data/README.md

@@ -127,19 +127,33 @@ Each character on the progress line is one mutant, printed as it finishes:
 | `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`
-if unaccepted survivors or errors exist (or, with `--fail-at`, if the score
-is below the threshold), `0` otherwise, including when there are only
-`uncovered` or `accepted` results. The JSON report's `exit_reason` field
-(`unaccepted_survivors`, `worker_errors`, `clean`, `empty_plan`) is
-independent of the `--fail-at` gate. A `--since` or `--subject` run that
+discarded before scheduling and reported as a count only.
+
+| Exit | When |
+|---|---|
+| `0` | no unaccepted survivors or errors (only `uncovered` or `accepted` results count as clean), or the score meets `--fail-at` |
+| `1` | unaccepted survivors or errors (with `--fail-at`, only when the score is below it), or an empty plan (below) |
+| `2` | a usage or setup problem: a bad flag or config file, or a red baseline suite |
+| `3` | the run reached `--max-rss` and stopped |
+| `130` | the run was stopped by SIGINT (Ctrl-C) |
+| `143` | the run was stopped by SIGTERM (130 before 0.7.0) |
+
+A stopped run (`3`, `130`, `143`) kills its child processes, prints the
+summary for the mutants that finished with a `Partial mutation score:`
+line in place of `Mutation score:`, and never passes, whatever `--fail-at`
+says. See [Run diagnostics](docs/guides/diagnostics.md#aborted-runs).
+
+The JSON report's `exit_reason` field (`unaccepted_survivors`,
+`worker_errors`, `clean`, `empty_plan`, and for a stopped run `interrupted`
+or `memory_ceiling`) is independent of the `--fail-at` gate. `complete` is
+`false` only for a stopped run. A `--since` or `--subject` run that
 plans zero mutants skips the baseline, prints the usual count block with
 every status at `0` and no `Mutation score:` line (JSON: `score` is `null`,
 `exit_reason` is `empty_plan`), then warns with the cause and exits `1`
 unless `--allow-empty` is given. The count block is printed on every run,
 whatever the exit code, so log-scraping never has to handle a missing block.
-`--allow-empty` forgives the empty plan only when the `--since` diff touched
-no candidate source file; see [Empty plans in CI](#empty-plans-in-ci).
+`--allow-empty` forgives the empty plan only when the `--since` diff changed
+no code in a candidate source file; see [Empty plans in CI](#empty-plans-in-ci).
 
 When survivors exist, the summary also prints a per-operator table showing
 how often each operator's mutants survive, to help spot likely-equivalent
@@ -263,9 +277,16 @@ itself whether that emptiness is fine:
 - **Exit 0** with `--no-class-level` when every changed line in the
   candidate files falls inside class-body code that flag dropped. The
   warning names `--no-class-level` as the reason.
-- **Exit 1** otherwise. A candidate source file changed but produced no
-  mutants, and the warning lists the file(s). A comment-only edit in `lib/`
-  counts as a real change here.
+- **Exit 0** when the only changes in the candidate files are comments or
+  blank lines, added or deleted. A magic comment such as
+  `# frozen_string_literal: true` counts as code, and so does a file that
+  fails to parse.
+- **Exit 0** when a file only lost code and no method spans the spot, e.g.
+  a whole method was removed. A deletion inside a method makes `--since`
+  mutate that method, like any other edit to it, so it never reaches this
+  rule unless the method has nothing left to mutate.
+- **Exit 1** otherwise. A candidate file's code changed but produced no
+  mutants, and the warning lists the file(s).
 - With `--subject` and no `--since` there is no diff to judge, so
   `--allow-empty` exits `0` unconditionally.
 
@@ -284,7 +305,7 @@ projects used to tell a docs-only PR from a broken `--since` range.
 | `--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 |
-| `--allow-empty` | off | forgive an empty `--since`/`--subject` plan, but only when the `--since` diff touched no candidate source file (default: warn and exit 1) |
+| `--allow-empty` | off | forgive an empty `--since`/`--subject` plan, but only when the `--since` diff changed no code in a candidate source file (default: warn and exit 1) |
 | `--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 |
@@ -297,6 +318,10 @@ projects used to tell a docs-only PR from a broken `--since` range.
 | `--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 |
+| `--diagnostics` | off | print timestamped phase, mutant, and memory lines to stderr, for finding out where a CI run died (see [Run diagnostics](docs/guides/diagnostics.md)) |
+| `--events FILE` | none | write the same events as NDJSON, one object per line, flushed as they happen |
+| `--sample-interval S` | 5 | seconds between memory samples with `--diagnostics`, `--events`, or `--max-rss` |
+| `--max-rss SIZE` | none | stop the run and exit 3 when the gem's total memory reaches SIZE (`6G`, `6144M`, or plain MB); warns once at 90% |
 | `--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
@@ -334,7 +359,10 @@ replaces the default `spec`),
 `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`).
+class-body mutant may reload before it is `skipped`),
+`diagnostics` (`true`/`false`, default `false`),
+`events_file` (a path), `sample_interval` (seconds, default `5`),
+`max_rss` (a size like `6G`, `6144M`, or plain MB).
 Unknown keys and wrong types are errors, not silent no-ops.
 
 ```yaml
@@ -421,6 +449,10 @@ remaining limits are:
 - [Operator reference](docs/guides/operators.md): every mutation
   active_mutator can generate, with before/after examples and what a
   survivor of each one means.
+- [Run diagnostics](docs/guides/diagnostics.md): `--diagnostics`,
+  `--events`, and `--max-rss`. Find the phase and mutants a dying CI run
+  was in, stop a run before it runs out of memory, and the `--events`
+  NDJSON schema.
 - [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

data/lib/active_mutator/abort_flag.rb

@@ -0,0 +1,53 @@
+module ActiveMutator
+  # A run stopped early by SIGINT, SIGTERM, or the memory ceiling. Carries
+  # what finished (`results`) and what was still running (`in_flight`).
+  class Aborted < StandardError
+    attr_reader :reason, :results, :in_flight
+
+    def initialize(reason, results: [], in_flight: [])
+      super("run aborted: #{reason}")
+      @reason = reason
+      @results = results
+      @in_flight = in_flight
+    end
+
+    # The same abort, with the finished results a caller up the stack knows.
+    def with_results(results) = self.class.new(reason, results: results, in_flight: in_flight)
+  end
+
+  # Where a signal or a memory breach lands. `trip!` is safe in a trap
+  # handler: no I/O and no locks (a Mutex in a trap raises ThreadError).
+  #
+  # Outside a `deferred` block, a trip raises Aborted on the main thread at
+  # once: boot and planning own no child processes, so there is nothing to
+  # clean up. Inside one (the baseline child's wait, the fork pool) it only
+  # records the reason; the owner's poll loop kills its children and then
+  # raises with what it knows. The first reason wins, and later trips are
+  # ignored while the abort is under way.
+  class AbortFlag
+    attr_reader :reason
+
+    def trip!(reason)
+      return if @reason
+
+      @reason = reason
+      Thread.main.raise(Aborted.new(reason)) unless @deferred
+    end
+
+    # Not an endless def: its one line runs at load, so coverage could
+    # never tie it to the specs that call it.
+    def tripped?
+      !@reason.nil?
+    end
+
+    def deferred
+      outer = @deferred
+      @deferred = true
+      raise Aborted, @reason if @reason
+
+      yield
+    ensure
+      @deferred = outer
+    end
+  end
+end

data/lib/active_mutator/baseline.rb

@@ -7,48 +7,69 @@ module ActiveMutator
   # caches the CoverageMap. Invalidation is coarse: any digest change in
   # {app,lib}/**/*.rb or the configured spec paths triggers a full re-run.
   class Baseline
-    def initialize(root:, spec_paths: ["spec"], cache_dir: File.join(root, ".active_mutator"))
+    def initialize(root:, spec_paths: ["spec"], cache_dir: File.join(root, ".active_mutator"), events: Events.new,
+                   abort: AbortFlag.new)
+      @abort = abort
       @root = root
       @spec_paths = spec_paths
       @cache_dir = cache_dir
       @out_path = File.join(cache_dir, "coverage.json")
+      @events = events
     end
 
-    attr_reader :last_refresh
+    POLL_SECONDS = 0.05
+
+    # child_pid: the running baseline child, nil between runs. Read by the
+    # memory sampler from its own thread.
+    attr_reader :last_refresh, :child_pid
 
     def coverage_map(force: false)
       digests = current_digests
-      if !force && File.exist?(@out_path)
-        map = CoverageMap.load(@out_path)
-        # 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 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, spec_paths: @spec_paths)
-          unless delta.full?
-            run_partial!(delta)
-            stamp_digests(digests)
-            @last_refresh = :partial
-            return CoverageMap.load(@out_path)
-          end
-        end
+      unless force
+        map = reuse_cache(digests)
+        return map if map
       end
-      run_baseline!
-      stamp_digests(digests)
+      data = run_baseline!
       @last_refresh = :full
-      CoverageMap.load(@out_path)
+      stamp(data, digests)
     end
 
     private
 
+    # The cached map, refreshed in place when a delta allows it; nil when only
+    # a full rebuild will do. The old map (records plus its inverted index)
+    # lives only in this method, so it is garbage before the full rebuild's
+    # child starts.
+    def reuse_cache(digests)
+      return unless File.exist?(@out_path)
+
+      data = load_payload
+      map = CoverageMap.new(data)
+      # 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.
+      return unless map.spec_paths == @spec_paths
+
+      if map.fresh?(digests)
+        @last_refresh = :cached
+        return map
+      end
+      return unless map.version == 2
+
+      delta = BaselineDelta.compute(old_digests: map.digests, new_digests: digests,
+                                    coverage_map: map, root: @root, spec_paths: @spec_paths)
+      return if delta.full?
+
+      # The map shares data["records"], and the merge edits it in place: the
+      # old map must not be read past this point.
+      run_partial!(delta, data)
+      @last_refresh = :partial
+      stamp(data, digests)
+    end
+
     # 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).
@@ -60,22 +81,31 @@ module ActiveMutator
 
     def run_baseline!
       prepare_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)
+      ok = run_rspec(@out_path)
       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)
+      data = load_payload
+      verify_complete!(data)
+      data
+    end
+
+    # Its own phase, apart from the child's run: 0.6.0 died here, in the
+    # parent reading a huge file back. The size goes out BEFORE the parse, so
+    # the log names the cause even if nothing runs after it, and --max-rss
+    # can stop the run before the parse.
+    def load_payload(path = @out_path)
+      @events.emit(:phase_start, phase: :coverage_load, bytes: File.size(path))
+      data = JSON.parse(File.read(path))
+      @events.emit(:phase_end, phase: :coverage_load, examples: data.fetch("records", {}).size)
+      data
     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))
+    def verify_complete!(payload)
       expected = payload["expected_examples"]
       return unless expected
 
@@ -87,6 +117,60 @@ module ActiveMutator
             "re-run without interrupting the suite"
     end
 
+    # Spawned and polled, not `system`, so the parent knows the child's pid
+    # and keeps control while it runs. out: :err: the subprocess suite's
+    # progress output must not pollute our stdout (breaks `--format json`
+    # consumers).
+    #
+    # The phase starts once the child exists, so it carries the pid the
+    # memory sampler follows. The child gets its own process group so an
+    # abort can kill the whole suite (browsers, app servers) in one signal;
+    # a Ctrl-C reaches it through the Runner's trap instead of the terminal.
+    # So does nothing else: a hangup from a closed terminal never reaches it,
+    # so anything that ends the wait early (an abort, SIGHUP, SIGQUIT) kills
+    # the group on the way out.
+    def run_rspec(out_path, targets = [])
+      status = nil
+      @abort.deferred do
+        @child_pid = Process.spawn(baseline_env(out_path), *rspec_command(targets), chdir: @root, out: :err,
+                                                                                    pgroup: true)
+        status = @events.phase(:baseline, refresh: targets.empty? ? :full : :partial, pid: @child_pid) do
+          wait_child(@child_pid)
+        end
+        # The memory sample taken as the phase ends can trip the ceiling.
+        # Stop here, before the coverage parse: that's the spike it guards.
+        raise Aborted, @abort.reason if @abort.tripped?
+
+        status.success?
+      end
+    rescue SystemCallError # `bundle` missing: `system` returned nil here
+      false
+    ensure
+      kill_group(@child_pid) if @child_pid && status.nil?
+      @child_pid = nil
+    end
+
+    def rspec_command(targets) = ["bundle", "exec", "rspec", *targets]
+
+    # The flag is checked after the wait, so a trip that lands as the child
+    # exits still stops the run here, not after the coverage parse.
+    # run_rspec kills the child's group on the way out.
+    def wait_child(pid)
+      loop do
+        _, status = Process.waitpid2(pid, Process::WNOHANG)
+        raise Aborted, @abort.reason if @abort.tripped?
+        return status if status
+
+        sleep POLL_SECONDS
+      end
+    end
+
+    def kill_group(pid)
+      Process.kill("KILL", -pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil # already gone
+    end
+
     def baseline_env(out_path)
       {
         "ACTIVE_MUTATOR" => "1",
@@ -106,36 +190,25 @@ module ActiveMutator
       }
     end
 
-    def stored_digests(map)
-      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
+    def run_partial!(delta, cache)
       partial_out = File.join(@cache_dir, "partial.json")
+      targets = delta.rerun_spec_files + delta.rerun_example_ids
+      part = {}
       if targets.any?
-        env = baseline_env(partial_out)
-        ok = system(env, "bundle", "exec", "rspec", *targets, chdir: @root, out: :err)
+        ok = run_rspec(partial_out, targets)
         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)
+        part = load_payload(partial_out)
+        verify_complete!(part)
       end
-      merge_partial!(partial_out, delta)
+      merge_partial!(cache, part, delta)
     ensure
-      FileUtils.rm_f(partial_out) if partial_out
+      FileUtils.rm_f(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" => {} }
-
+    # Edits `cache` in place; the caller stamps and writes it.
+    def merge_partial!(cache, part, delta)
       rerun_prefixes = delta.rerun_spec_files.map { |rel| "#{rel}[" }
       obsolete = lambda do |example_id|
         bare = example_id.sub(%r{\A\./}, "")
@@ -151,14 +224,15 @@ module ActiveMutator
       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))
+    # Writes the stamped payload once and builds the map from the hash in
+    # hand, so the file is never parsed back.
+    def stamp(data, digests)
       data["digests"] = digests
       data["spec_paths"] = @spec_paths
       AtomicFile.write(@out_path, JSON.generate(data))
+      CoverageMap.new(data)
     end
 
     def current_digests

data/lib/active_mutator/baseline_hooks.rb

@@ -9,11 +9,16 @@ module ActiveMutator
     RECORDS = {}
     TIMES = {}
 
-    def self.diff_coverage(before, after, root, spec_paths: ["spec"])
+    def self.diff_coverage(before, after, root, spec_paths: ["spec"], gem_dirs: [])
       prefixes = spec_paths.map { |sp| "/#{sp}/" }
+      gem_prefixes = gem_dirs.map { |dir| File.join(dir, "") }
       hits = []
       after.each do |path, data|
         next unless path.start_with?(root)
+        # Gems installed under the root (e.g. `bundle config path
+        # vendor/bundle` on CI) would otherwise be recorded per example and
+        # blow up the map's memory.
+        next if gem_prefixes.any? { |p| path.start_with?(p) }
 
         # Relative to root, not a global substring check: `root` itself may
         # contain "/spec/" (e.g. a fixture nested under this gem's own
@@ -33,6 +38,20 @@ module ActiveMutator
       hits
     end
 
+    # Computed per example, not at load: this file loads via RUBYOPT before
+    # Bundler sets up its install path.
+    def self.gem_dirs
+      dirs = Gem.path.dup
+      if defined?(Bundler)
+        begin
+          dirs << Bundler.bundle_path.to_s
+        rescue Bundler::BundlerError
+          # No Gemfile, so Gem.path covers it.
+        end
+      end
+      dirs.uniq
+    end
+
     def self.build_payload(records, times, expected_examples: nil)
       payload = { "version" => 2, "records" => records, "times" => times }
       payload["expected_examples"] = expected_examples if expected_examples
@@ -56,7 +75,10 @@ if ENV["ACTIVE_MUTATOR_BASELINE_OUT"]
       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, spec_paths: spec_paths)
+        ActiveMutator::BaselineHooks.diff_coverage(
+          before, after, root,
+          spec_paths: spec_paths, gem_dirs: ActiveMutator::BaselineHooks.gem_dirs
+        )
       # NOT example.execution_result.run_time: that is nil until after
       # around hooks complete.
       ActiveMutator::BaselineHooks::TIMES[example.id] = elapsed

data/lib/active_mutator/cli.rb

@@ -32,7 +32,8 @@ module ActiveMutator
         spec_paths: ["spec"],
         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, allow_empty: false
+        operators: [], class_level: true, class_level_closure_cap: 10, allow_empty: false,
+        diagnostics: false, events_file: nil, sample_interval: 5.0, max_rss: nil
       }
       options.merge!(ConfigFile.load(Dir.pwd))
       paths = OptionParser.new do |o|
@@ -67,8 +68,22 @@ module ActiveMutator
         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("--allow-empty",
-             "Exit 0 when --since/--subject plan no mutants and the --since diff touched no mutable " \
-             "source file (default: exit 1)") { options[:allow_empty] = true }
+             "Exit 0 when --since/--subject plan no mutants and the --since diff changed no code " \
+             "in a mutable source file (default: exit 1)") { options[:allow_empty] = true }
+        o.on("--diagnostics", "Print phase, mutant, and memory lines to stderr") { options[:diagnostics] = true }
+        o.on("--events FILE", "Write run events to FILE as NDJSON, one object per line") { |v| options[:events_file] = v }
+        o.on("--sample-interval S", Float,
+             "Seconds between memory samples with --diagnostics, --events, or --max-rss (default: 5)") do |v|
+          raise OptionParser::InvalidArgument, "--sample-interval must be > 0" unless v.positive?
+          options[:sample_interval] = v
+        end
+        o.on("--max-rss SIZE", "Stop the run (exit 3) when the gem's total memory reaches SIZE: 6G, 6144M, " \
+                               "or MB; warns at 90%") do |v|
+          kb = MemoryCeiling.parse_kb(v)
+          raise OptionParser::InvalidArgument, "--max-rss takes a size like 6G, 6144M, or 6144 (MB)" unless kb
+
+          options[:max_rss] = kb
+        end
         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

data/lib/active_mutator/config.rb

@@ -7,5 +7,12 @@ module ActiveMutator
                        :browser_boot_seconds,
                        :accept_survivors, :exclude, :max_mutants, :debug_plan,
                        :fail_at, :adaptive_timeout, :operators,
-                       :class_level, :class_level_closure_cap, :allow_empty)
+                       :class_level, :class_level_closure_cap, :allow_empty,
+                       :diagnostics, :events_file, :sample_interval, :max_rss) do
+    # Defaults for the 0.7.0 diagnostics fields, so a Config built by hand
+    # (specs, embedding hosts) doesn't have to name them. `max_rss` is in kB.
+    def initialize(diagnostics: false, events_file: nil, sample_interval: 5.0, max_rss: nil, **fields)
+      super
+    end
+  end
 end

data/lib/active_mutator/config_file.rb

@@ -26,7 +26,11 @@ module ActiveMutator
       "adaptive_timeout" => :boolean,
       "class_level" => :boolean,
       "class_level_closure_cap" => :positive_integer,
-      "allow_empty" => :boolean
+      "allow_empty" => :boolean,
+      "diagnostics" => :boolean,
+      "events_file" => :string,
+      "sample_interval" => :positive_number,
+      "max_rss" => :size
     }.freeze
 
     def self.load(root)
@@ -63,6 +67,10 @@ module ActiveMutator
       when :number
         raise Error, "#{FILENAME}: #{key} must be a number" unless value.is_a?(Numeric)
         value.to_f
+      when :positive_number
+        raise Error, "#{FILENAME}: #{key} must be a number" unless value.is_a?(Numeric)
+        raise Error, "#{FILENAME}: #{key} must be > 0" unless value.positive?
+        value.to_f
       when :score
         raise Error, "#{FILENAME}: #{key} must be a number" unless value.is_a?(Numeric)
         raise Error, "#{FILENAME}: #{key} must be within 0..100" unless (0..100).cover?(value)
@@ -72,6 +80,9 @@ module ActiveMutator
           raise Error, "#{FILENAME}: format must be one of #{FORMATS.join(", ")}"
         end
         value.tr("-", "_").to_sym
+      when :string
+        raise Error, "#{FILENAME}: #{key} must be a string" unless value.is_a?(String)
+        value
       when :string_list
         unless value.is_a?(Array) && value.all?(String)
           raise Error, "#{FILENAME}: #{key} must be a list of strings"
@@ -88,6 +99,11 @@ module ActiveMutator
           raise Error, "#{FILENAME}: #{key} must be true or false"
         end
         value
+      when :size
+        kb = MemoryCeiling.parse_kb(value)
+        raise Error, "#{FILENAME}: #{key} must be a size like 6G, 6144M, or 6144 (MB)" unless kb
+
+        kb
       when :preload_helper
         return :none if value == false
         raise Error, "#{FILENAME}: preload_helper must be a path or false" unless value.is_a?(String)

data/lib/active_mutator/coverage_map.rb

@@ -8,13 +8,16 @@ module ActiveMutator
   class CoverageMap
     def self.load(path) = new(JSON.parse(File.read(path)))
 
-    attr_reader :version, :records
+    attr_reader :version, :records, :digests, :spec_paths
 
     def initialize(data)
       @version = data["version"]
       @records = data.fetch("records", {})
       @times = data.fetch("times", {})
       @digests = data.fetch("digests", {})
+      # 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.
+      @spec_paths = data.fetch("spec_paths", ["spec"])
       @map = build_map
     end
 

data/lib/active_mutator/diagnostics/ndjson.rb

@@ -0,0 +1,25 @@
+require "json"
+
+module ActiveMutator
+  module Diagnostics
+    # --events FILE: every event as one JSON object per line. The public,
+    # versioned contract (docs/guides/diagnostics.md): new fields may appear
+    # under v1; a rename or removal bumps VERSION. The IO is sync, so each
+    # line reaches the OS as it's written and a SIGKILLed run still leaves
+    # everything up to the kill.
+    class Ndjson
+      VERSION = 1
+
+      def initialize(io)
+        @io = io
+        @io.sync = true
+      end
+
+      def call(event)
+        line = { "v" => VERSION, "event" => event.type.to_s,
+                 "t" => event.at.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ"), "elapsed" => event.elapsed.round(3) }
+        @io.write("#{JSON.generate(line.merge(event.fields.transform_keys(&:to_s)))}\n")
+      end
+    end
+  end
+end