mutation_tester 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8391c9817c1f430ec2231982495e11ff1f6866c3ce11b8e67d9ab421894c44ab
-  data.tar.gz: c82152c72bf0c0faaa22807ade06134fc814dd0faddde7f3849100b29b2f54fa
+  metadata.gz: 95884456f3cb22f463001c227181cbb9250fe09c3e94eec4039cc0fac54c6e18
+  data.tar.gz: 984f636d787af8f79d4d117684f57a69bdd48347651ecbb6421468d2730522e8
 SHA512:
-  metadata.gz: d663fe8bc725c6b99e50d0752c3c8452397794672ac2a79a64e1cc6da70b1076abca47bf5143050cc3afd405320ff584d17c587cca8fff47bed27a3f184ed543
-  data.tar.gz: f33e5cbcdf08e032015b358e2b027b7846af163d2d5bab5954abf13f6d06d48e3a584677ace35e97f9aee67e48faa96a5c5ffcc2704b9416984e4605bcecdff1
+  metadata.gz: 890a83603e65df88fcad21e62a27faa57c8540c403d8ca92ae218b9471d04471272f01f409f7c32cff8bf567feda042167c75b7be83962315c06976626ec142b
+  data.tar.gz: 943bb88ba38f80d37c78ecde8f91567000e952a4b68209cfac9d94aa336129b8ce2bdec2eaac4759fa328fb334daa79fd34a8a7a587d069804fcf1d4c907c943

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [1.5.0] - 2026-08-08
+
+- Added `--after-fork FILE` (and `config.after_fork_file` / the `MUTATION_TESTER_AFTER_FORK` environment variable): a Ruby file loaded inside each preloaded in-memory clone right after it forks and receives its per-worker environment, so the app can re-establish per-worker state such as its ActiveRecord connection. With `--worker-env` set, this keeps the `in_memory` runner available in parallel runs instead of falling back to `fork`: each clone now receives its own per-worker value of the variable through the existing per-clone environment plumbing and runs the after-fork file once, giving in-memory execution and per-worker database isolation at the same time. Failure modes stay loud: a clone whose after-fork file raises reports the error on stderr and is dropped, its worker deciding its share of mutants file-based, and a missing after-fork file makes the whole run fall back to file-based execution with a warning. A serial in-memory run (`-p 1`) has only one worker and now stays in memory with `--worker-env` even without the hook.
+- A serial file-based run (`-p 1`) with `--worker-env` now decides each mutant in a shadow workspace instead of writing mutants into the real source file with a `.mutation_backup` alongside, so a process killed mid-run can no longer leave a mutated source file in the checkout. This combination occurs naturally when a caller uses one code path for both a parallel run and a serial re-run. Without `--worker-env` serial file-based runs keep the in-place strategy (the next run still restores a leftover backup automatically).
+
+## [1.4.2] - 2026-08-05
+
+- Added `--spec-map 'PATTERN=>REPLACEMENT'`, a repeatable rule that builds the whole spec path from the whole source path with a regular expression, for the layouts the `{name}` template cannot express. `{name}` is the source path minus a leading `lib/`, so a template can only wrap it with a prefix and a suffix; every mapping that substitutes *inside* the path, after a variable-length prefix, was out of reach: `packs/identity/app/models/party.rb -> packs/identity/test/models/party_test.rb` (Packwerk / packs-rails), the same shape with Rails engines, and the plain Rails `app/ -> test/` rule. Because `--since` requires `--glob` and `--glob` maps through `--spec-glob`, such a layout previously lost the entire batch tier at once and had to be reimplemented in a wrapper script. The first matching rule wins and a source matching no rule falls back to `--spec-glob`, so one run can cover `app/` through a rule and `lib/` through the template. The flag works with `--glob`, a positional `FILE` list and `--staged`; a malformed rule is a usage error (exit code `2`) reported before any mutation runs.
+- Fixed `--glob` finishing with status `0` when every matched file was skipped. The two batch paths used different predicates over the same result, and the `--glob` one gated on "something matched and every processed file passed", which is vacuously true over an empty processed list. A run that matched four files and skipped all four (a wrong `--spec-glob`, a test directory moved by a refactor) printed `All processed files met the mutation score threshold`, set `"passed": true` in the JSON envelope and passed the run, which is the worst direction for a quality gate: it vouches for a score it never measured. Both paths now share one predicate: a batch that matched files but measured none fails with status `1` and prints `No files were mutation-tested`, while a `--since` run whose matched files were all unchanged still passes, so a pull request that touches nothing keeps its documented green run.
+- Added `--minimum-score N` to set the threshold a file must reach for a single run. `config.minimum_score` (default 80) had no CLI flag and no environment variable, so the CLI's own gate was fixed at 80 and the shipped `examples/hooks/pre-push` worked around it with `--json` plus `jq`. An existing codebase can now start below 80 and raise the number over time without a wrapper.
+
 ## [1.4.1] - 2026-08-03
 
 - Fixed parallel runs reporting every mutant as survived (`Killed: 0`, score `0.0%`) on projects whose test file reaches its source through `$LOAD_PATH` (a Rails app run with `-Itest` in `RUBYOPT`, for example). A preloaded worker is started once in the real project root, so Ruby absolutizes every `-I`/`RUBYLIB` entry against that directory; the forked child then changed into the shadow workspace but kept resolving `require "test_helper"` back to the original tree, which loaded the unmutated source. Each job now rewrites the `$LOAD_PATH` entries of the mirrored project root into the workspace, so a preloaded worker resolves project code exactly like the `spawn` runner that starts inside the workspace. Only Minitest suites hit this in practice: RSpec re-adds `lib` and its default path at run time, after the child has changed directory. Serial runs and the `spawn` runner were never affected, which is why the same file scored 96.55% serially and 0.0% with `-p 8`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mutation_tester (1.4.1)
+    mutation_tester (1.4.2)
       parallel (~> 1.20)
       parser (~> 3.3)
       rainbow (~> 3.0)

data/docs/ci.md

@@ -29,7 +29,8 @@ The same thing, condensed to a copy-pasteable minimal workflow. It matches the
 maintained template above; reach for the template when you want the parallel and
 multi-file variants. The quality gate needs no extra configuration: the CLI exits
 non-zero when the mutation score is below the threshold, which fails the step (and
-the job).
+the job). The threshold defaults to 80 and `--minimum-score N` sets it for a
+single run, so an existing codebase can start lower and ratchet the number up.
 
 ```yaml
 name: Mutation Testing
@@ -108,6 +109,28 @@ jobs:
 A PR that touches nothing under `lib/` exits `0` with a "Nothing to mutate"
 message, so the gate never blocks unrelated changes.
 
+### What the batch exit code guarantees
+
+A batch run exits `0` only when at least one file was actually mutation-tested
+and every processed file met the threshold, or when the `--since` filter left
+nothing to mutate. If the glob matched files but *every* one of them was skipped
+(most often `no matching spec file`), the run exits `1`: nothing was measured, so
+the gate has nothing to vouch for. That keeps a typo in `--spec-glob` /
+`--spec-map`, or a refactor that moves the test directory, from silently turning
+a green job into a job that measures nothing.
+
+For an application whose tests do not sit under `spec/`, map the paths with
+`--spec-map` (see
+[Mapping sources to specs](../readme.md#mapping-sources-to-specs)):
+
+```yaml
+      - name: Run mutation tests on changed files only
+        run: |
+          bundle exec mutation_test --glob '{app,packs/*/app}/**/*.rb' \
+            --spec-map '\A((?:packs/[^/]+/)?)app/(.+)\.rb\z=>\1test/\2_test.rb' \
+            --since "origin/${{ github.base_ref }}" --fail-fast
+```
+
 ## Machine mode as a CI gate and artifact
 
 `--json` makes the CLI double as the gate (its exit code follows the threshold)

data/docs/execution-runners.md

@@ -134,6 +134,18 @@ no fallback is possible.
   in a fresh fork of its own clone. If a pooled worker dies mid-run, that
   worker finishes its share of mutants through the file-based path with a
   warning; the other workers stay in memory.
+- With `--worker-env` the preloaded clones would all share the primary
+  worker's already-established database connection, so a parallel run
+  (`-p N`, N > 1) skips the in-memory runner with a warning unless
+  `--after-fork FILE` is also given. With `--after-fork`, each clone
+  receives its per-worker value of the `--worker-env` variable and loads
+  `FILE` right after forking, and that file re-establishes the per-worker
+  state (typically the ActiveRecord connection), which keeps the whole run
+  in memory with per-worker database isolation. A serial run (`-p 1`) has
+  only one worker and stays in memory without any hook. A clone whose
+  after-fork file raises reports the error on stderr and is dropped, and
+  its worker falls back to the file-based path; a missing after-fork file
+  makes the whole run fall back with a warning.
 - Before any mutant runs, the runner re-applies the **unmutated** source in a
   probe child and runs the suite. If that probe fails (for example the file has
   top-level side effects that break on a second execution, or the class is

data/exe/mutation_test

@@ -60,6 +60,14 @@ OptionParser.new do |opts|
     options[:spec_glob] = template
   end
 
+  opts.on('--spec-map RULE', "Regex spec-mapping rule 'PATTERN#{MutationTester::BatchRunner::SPEC_MAP_SEPARATOR}REPLACEMENT' applied to the whole source path to build the whole spec path (e.g. '\\A((?:packs/[^/]+/)?)app/(.+)\\.rb\\z#{MutationTester::BatchRunner::SPEC_MAP_SEPARATOR}\\1test/\\2_test.rb'). Repeatable; the first matching rule wins and a source matching no rule falls back to --spec-glob. Requires a FILE list, --staged, or --glob.") do |rule|
+    (options[:spec_map] ||= []) << rule
+  end
+
+  opts.on('--minimum-score N', Float, "Mutation score percentage a file must reach to pass (default: #{MutationTester::Configuration::DEFAULT_MINIMUM_SCORE})") do |score|
+    options[:minimum_score] = score
+  end
+
   opts.on('--since REV', 'Incremental batch mode: mutate only the files matched by --glob that changed since git revision REV (new files count as changed). Requires --glob.') do |rev|
     options[:since] = rev
   end
@@ -80,10 +88,14 @@ OptionParser.new do |opts|
     options[:strict_equality] = true
   end
 
-  opts.on('--worker-env NAME', 'Set environment variable NAME to a distinct per-worker value before each parallel worker boots (parallel_tests TEST_ENV_NUMBER convention: worker 0 -> "", worker N -> N+1), so a parallel_tests-style database.yml selects a per-worker database. Provision the databases yourself (e.g. rake parallel:prepare). The in_memory runner cannot isolate a per-worker database, so this flag makes the runner fall back to fork.') do |name|
+  opts.on('--worker-env NAME', 'Set environment variable NAME to a distinct per-worker value before each parallel worker boots (parallel_tests TEST_ENV_NUMBER convention: worker 0 -> "", worker N -> N+1), so a parallel_tests-style database.yml selects a per-worker database. Provision the databases yourself (e.g. rake parallel:prepare). Without --after-fork a parallel in_memory run falls back to fork (preloaded clones share one database connection); pair it with --after-fork to keep the in_memory runner. A serial run (-p 1) decides mutants in a shadow workspace instead of mutating the checkout in place.') do |name|
     options[:worker_env] = name
   end
 
+  opts.on('--after-fork FILE', 'Ruby file loaded inside each preloaded in-memory clone right after it forks and receives its per-worker environment (see --worker-env), so the app can re-establish per-worker state such as its database connection (e.g. a file calling ActiveRecord::Base.establish_connection). With --worker-env set, this keeps the in_memory runner available in parallel runs.') do |file|
+    options[:after_fork] = file
+  end
+
   opts.on('-h', '--help', 'Show this help message') do
     puts opts
     exit
@@ -150,6 +162,13 @@ end
 glob_mode = !options[:glob].nil?
 staged_mode = options.fetch(:staged, false)
 
+spec_map = begin
+  (options[:spec_map] || []).map { |rule| MutationTester::BatchRunner.parse_spec_map(rule) }
+rescue MutationTester::Error => e
+  usage_error.call(e.message,
+                   "Quote the rule so the shell keeps it intact, e.g. --spec-map '\\Aapp/(.+)\\.rb\\z=>test/\\1_test.rb'.")
+end
+
 apply_configuration = lambda do
   MutationTester.configure do |config|
     config.parallel_processes = options[:parallel] if options[:parallel]
@@ -158,10 +177,12 @@ apply_configuration = lambda do
     config.show_progress = !options[:no_progress]
     config.reporters = selected_reporters if selected_reporters
     config.output_dir = options[:output_dir] if options[:output_dir]
+    config.minimum_score = options[:minimum_score] if options[:minimum_score]
     config.test_selection = false if options[:no_test_selection]
     config.timeout_factor = options[:timeout_factor] if options[:timeout_factor]
     config.timeout_policy = options[:timeout_policy] if options[:timeout_policy]
     config.worker_env_var = options[:worker_env] if options.key?(:worker_env)
+    config.after_fork_file = options[:after_fork] if options.key?(:after_fork)
     config.fail_fast = options.fetch(:fail_fast, false)
     config.mutation_types[:strict_equality] = true if options[:strict_equality]
 
@@ -224,18 +245,17 @@ if glob_mode
   batch = MutationTester::BatchRunner.new(
     glob: options[:glob],
     spec_template: options[:spec_glob],
+    spec_map: spec_map,
     config: MutationTester.configuration,
     since: options[:since],
     changed_files: changed_files
   )
 
-  run_batch_machine.call(batch, ->(result) { result.matched_any? && result.success? }) if json_mode
+  run_batch_machine.call(batch, ->(result) { result.gate_passed? }) if json_mode
 
   result = guard_interrupt.call { batch.run }
 
-  exit 1 unless result.matched_any?
-
-  exit(result.success? ? 0 : 1)
+  exit(result.gate_passed? ? 0 : 1)
 end
 
 if !staged_mode && ARGV.empty?
@@ -255,6 +275,11 @@ if options[:spec_glob] && legacy_pair
                    'Use --spec-glob with a positional FILE list, --staged, or --glob.')
 end
 
+if options[:spec_map] && legacy_pair
+  usage_error.call('--spec-map does not apply to an explicit SOURCE_FILE TEST_FILE pair.',
+                   'Use --spec-map with a positional FILE list, --staged, or --glob.')
+end
+
 if legacy_pair
   source_file, test_file = ARGV
 else
@@ -278,7 +303,7 @@ else
   single_file_json = json_mode && !staged_mode && sources.length == 1
 
   if single_file_json
-    outcome = MutationTester::BatchRunner.new(files: sources, spec_template: options[:spec_glob]).classify(sources.first)
+    outcome = MutationTester::BatchRunner.new(files: sources, spec_template: options[:spec_glob], spec_map: spec_map).classify(sources.first)
     if outcome.is_a?(MutationTester::BatchRunner::SkippedEntry)
       reason = MutationTester::BatchRunner::SKIP_REASONS.fetch(outcome.reason)
       detail = outcome.expected_spec ? " (expected #{outcome.expected_spec})" : ''
@@ -293,14 +318,15 @@ else
     batch = MutationTester::BatchRunner.new(
       files: sources,
       spec_template: options[:spec_glob],
+      spec_map: spec_map,
       config: MutationTester.configuration
     )
 
-    run_batch_machine.call(batch, ->(result) { result.processed.any? && result.success? }) if json_mode
+    run_batch_machine.call(batch, ->(result) { result.gate_passed? }) if json_mode
 
     result = guard_interrupt.call { batch.run }
 
-    exit(result.processed.any? && result.success? ? 0 : 1)
+    exit(result.gate_passed? ? 0 : 1)
   end
 end
 

data/lib/mutation_tester/batch_runner.rb

@@ -9,6 +9,8 @@ module MutationTester
 
     DEFAULT_SPEC_TEMPLATE = 'spec/{name}_spec.rb'.freeze
 
+    SPEC_MAP_SEPARATOR = '=>'.freeze
+
     TEST_FILE_SUFFIXES = ['_spec.rb', '.spec.rb', '_test.rb'].freeze
 
     SKIP_REASONS = {
@@ -57,6 +59,18 @@ module MutationTester
         !(processed.empty? && skipped.empty? && (unchanged || []).empty?)
       end
 
+      def nothing_measured?
+        processed.empty? && !skipped.empty?
+      end
+
+      def gate_passed?
+        return false unless matched_any?
+        return false if nothing_measured?
+        return true if processed.empty?
+
+        success?
+      end
+
       def interrupted?
         !!interrupted
       end
@@ -100,6 +114,24 @@ module MutationTester
             .map { |path| Pathname.new(File.expand_path(path, toplevel)).relative_path_from(base).to_s }
     end
 
+    def self.parse_spec_map(rule)
+      pattern, replacement = rule.to_s.split(SPEC_MAP_SEPARATOR, 2)
+      if replacement.nil?
+        raise MutationTester::Error,
+              "--spec-map #{rule.to_s.inspect} has no #{SPEC_MAP_SEPARATOR} separator; " \
+              "write it as 'PATTERN#{SPEC_MAP_SEPARATOR}REPLACEMENT'"
+      end
+      if pattern.empty?
+        raise MutationTester::Error, "--spec-map #{rule.to_s.inspect} has an empty pattern"
+      end
+
+      begin
+        [Regexp.new(pattern), replacement]
+      rescue RegexpError => e
+        raise MutationTester::Error, "--spec-map pattern #{pattern.inspect} is not a valid regular expression: #{e.message}"
+      end
+    end
+
     def self.test_file?(path)
       basename = File.basename(path)
       return true if TEST_FILE_SUFFIXES.any? { |suffix| basename.end_with?(suffix) }
@@ -118,12 +150,13 @@ module MutationTester
     end
     private_class_method :git_capture
 
-    def initialize(glob: nil, files: nil, spec_template: nil, config: MutationTester.configuration, since: nil, changed_files: nil)
+    def initialize(glob: nil, files: nil, spec_template: nil, spec_map: nil, config: MutationTester.configuration, since: nil, changed_files: nil)
       raise ArgumentError, 'provide exactly one of glob: or files:' unless glob.nil? ^ files.nil?
 
       @glob = glob
       @files = files
       @spec_template = spec_template.nil? || spec_template.empty? ? DEFAULT_SPEC_TEMPLATE : spec_template
+      @spec_map = spec_map || []
       @config = config
       @since = since
       @changed_files = changed_files
@@ -203,6 +236,10 @@ module MutationTester
     end
 
     def spec_path_for(source_file)
+      normalized = source_file.sub(%r{\A\./}, '')
+      pattern, replacement = @spec_map.find { |rule_pattern, _| rule_pattern.match?(normalized) }
+      return normalized.sub(pattern, replacement) if pattern
+
       @spec_template.gsub(NAME_PLACEHOLDER, source_name(source_file))
     end
 
@@ -254,8 +291,9 @@ module MutationTester
       puts Rainbow('=' * 80).bright
       failed = result.processed.reject(&:passed?)
       degraded = failed.select(&:degraded?)
-      if @files && result.processed.empty?
-        puts Rainbow('❌ No files were mutation-tested: every listed file was skipped').red
+      if result.nothing_measured?
+        scope = @files ? 'listed' : 'matched'
+        puts Rainbow("❌ No files were mutation-tested: every #{scope} file was skipped").red
       elsif result.success?
         puts Rainbow('✓ All processed files met the mutation score threshold').green
       elsif degraded.size == failed.size

data/lib/mutation_tester/configuration.rb

@@ -5,6 +5,7 @@ module MutationTester
     RUNNER_MODES = %i[auto fork spawn in_memory].freeze
     TIMEOUT_POLICIES = %i[killed separate].freeze
     AUTO_PARALLEL_CAP = 8
+    DEFAULT_MINIMUM_SCORE = 80.0
     DEFAULT_TIMEOUT = 30
     DEFAULT_TIMEOUT_FACTOR = 5
     CALIBRATED_TIMEOUT_FLOOR = 5
@@ -18,7 +19,8 @@ module MutationTester
       number <= 0 ? '' : (number + 1).to_s
     end
 
-    attr_reader :parallel_processes, :runner, :worker_env_var, :timeout, :timeout_factor, :timeout_policy
+    attr_reader :parallel_processes, :runner, :worker_env_var, :after_fork_file, :timeout, :timeout_factor,
+      :timeout_policy
 
     attr_accessor :baseline_duration,
       :baseline_timeout,
@@ -37,6 +39,7 @@ module MutationTester
       self.parallel_processes = ENV['MUTATION_TESTER_PARALLEL_PROCESSES'] || self.class.auto_parallel_processes
       self.runner = ENV['MUTATION_TESTER_RUNNER'] || :auto
       self.worker_env_var = ENV['MUTATION_TESTER_WORKER_ENV']
+      self.after_fork_file = ENV['MUTATION_TESTER_AFTER_FORK']
       @timeout = DEFAULT_TIMEOUT
       @timeout_factor = DEFAULT_TIMEOUT_FACTOR
       @timeout_policy = :killed
@@ -56,7 +59,7 @@ module MutationTester
       }
       @reporters = %i[console html json]
       @output_dir = 'tmp/mutation_reports'
-      @minimum_score = 80.0
+      @minimum_score = DEFAULT_MINIMUM_SCORE
       @fail_on_threshold = true
       @verbose = false
       @show_file_path = true
@@ -135,6 +138,11 @@ module MutationTester
       @worker_env_var = normalized.empty? ? nil : normalized
     end
 
+    def after_fork_file=(value)
+      normalized = value.to_s.strip
+      @after_fork_file = normalized.empty? ? nil : File.expand_path(normalized)
+    end
+
     def worker_env_assignment(index)
       return nil unless @worker_env_var
 

data/lib/mutation_tester/fork_runner/worker.rb

@@ -238,6 +238,17 @@ spawn_clone = lambda do |request, out|
     out.close
     STDIN.reopen(File::NULL)
     request['env']&.each { |name, value| ENV[name] = value }
+    if request['after_fork']
+      begin
+        load(request['after_fork'])
+      rescue ScriptError, StandardError => e
+        clone_out.puts(JSON.generate(
+          'event' => 'clone_error',
+          'message' => "the after-fork file #{request['after_fork']} raised #{e.class}: #{e.message}; this clone is unavailable"
+        ))
+        raise
+      end
+    end
     serve.call(input, clone_out)
   end
   Process.detach(child)

data/lib/mutation_tester/fork_runner.rb

@@ -39,10 +39,10 @@ module MutationTester
         refill_pool(pool_key(use_bundle_exec, framework), count, primary, env_for: env_for)
       end
 
-      def prepare_in_memory_pool(count, primary)
+      def prepare_in_memory_pool(count, primary, env_for: nil, after_fork: nil)
         return [] unless available? && primary&.ready?
 
-        refill_pool(IN_MEMORY_POOL_KEY, count, primary)
+        refill_pool(IN_MEMORY_POOL_KEY, count, primary, env_for: env_for, after_fork: after_fork)
       end
 
       def in_memory_pool_prepared?
@@ -116,13 +116,13 @@ module MutationTester
         Parallel.worker_number if defined?(Parallel) && Parallel.respond_to?(:worker_number)
       end
 
-      def refill_pool(key, count, primary, env_for: nil)
+      def refill_pool(key, count, primary, env_for: nil, after_fork: nil)
         entry = (pool[key] ||= { owner: Process.pid, runners: [] })
         entry[:runners] = entry[:runners].each_with_index.map do |runner, index|
-          runner&.ready? ? runner : primary.fork_clone(env: env_for&.call(index))
+          runner&.ready? ? runner : primary.fork_clone(env: env_for&.call(index), after_fork: after_fork)
         end
         entry[:runners].size.upto(count - 1) do |index|
-          entry[:runners] << primary.fork_clone(env: env_for&.call(index))
+          entry[:runners] << primary.fork_clone(env: env_for&.call(index), after_fork: after_fork)
         end
         entry[:runners]
       end
@@ -198,7 +198,7 @@ module MutationTester
       fail_worker
     end
 
-    def fork_clone(env: nil)
+    def fork_clone(env: nil, after_fork: nil)
       return nil unless ready?
       return nil unless File.respond_to?(:mkfifo)
 
@@ -210,6 +210,7 @@ module MutationTester
 
       clone_request = { 'job' => job_path, 'events' => events_path }
       clone_request['env'] = env if env
+      clone_request['after_fork'] = after_fork if after_fork
       @job_writer.puts(JSON.generate('clone' => clone_request))
       event = read_event(monotonic_time + CLONE_TIMEOUT)
       return nil unless event.is_a?(Hash) && event['event'] == 'cloned'
@@ -264,6 +265,11 @@ module MutationTester
           next
         end
 
+        if event['event'] == 'clone_error'
+          warn("[MutationTester] #{event['message']}")
+          return false
+        end
+
         return event['event'] == 'ready'
       end
     end

data/lib/mutation_tester/mutation_runner.rb

@@ -56,16 +56,17 @@ module MutationTester
       elsif in_memory_first?
         run_in_memory_series(mutations, &progress_callback)
       elsif @config.parallel_processes == 1
-        run_in_place_series(mutations, &progress_callback)
+        run_file_based_series(mutations, &progress_callback)
       else
         run_in_shadow_parallel(mutations, &progress_callback)
       end
     end
 
     def in_memory_first?
-      return false if @config.worker_env_var
+      return false unless %i[in_memory auto].include?(@config.runner)
+      return true unless @config.worker_env_var
 
-      %i[in_memory auto].include?(@config.runner)
+      @config.parallel_processes == 1 || !@config.after_fork_file.nil?
     end
 
     def run_in_memory_series(mutations, &progress_callback)
@@ -100,7 +101,12 @@ module MutationTester
       blocker = prepare_in_memory_execution
       return fall_back_to_parallel_file_based(blocker, mutations, &progress_callback) if blocker
 
-      pool = ForkRunner.prepare_in_memory_pool([@config.parallel_processes, mutations.size].min, @in_memory_runner)
+      pool = ForkRunner.prepare_in_memory_pool(
+        [@config.parallel_processes, mutations.size].min,
+        @in_memory_runner,
+        env_for: worker_env_for,
+        after_fork: @config.after_fork_file
+      )
       if pool.compact.empty?
         return fall_back_to_parallel_file_based('the preloaded worker pool could not be cloned', mutations, &progress_callback)
       end
@@ -161,6 +167,28 @@ module MutationTester
       cleanup_shadow_workspaces
     end
 
+    def run_file_based_series(mutations, &progress_callback)
+      project_root = @config.worker_env_var ? discoverable_project_root : nil
+      return run_in_place_series(mutations, &progress_callback) unless project_root
+
+      run_in_shadow_series(mutations, project_root, &progress_callback)
+    end
+
+    def run_in_shadow_series(mutations, project_root, &progress_callback)
+      warn "[MutationTester] --worker-env #{@config.worker_env_var} is set, so the serial run decides each mutant in a shadow workspace and never mutates the checkout in place."
+      shadow_run_root
+      results = []
+      mutations.each_with_index do |mutation, index|
+        result = run_single_mutation(mutation, :shadow, project_root)
+        progress_callback.call(mutation, index + 1) if progress_callback
+        results << result
+        break if stop_early?(result)
+      end
+      results
+    ensure
+      cleanup_shadow_workspaces
+    end
+
     def run_in_place_series(mutations, &progress_callback)
       write_in_place_backup
       results = []
@@ -401,6 +429,9 @@ module MutationTester
 
     def prepare_in_memory_execution
       return 'Process.fork is not supported on this platform' unless ForkRunner.available?
+      if @config.after_fork_file && !File.exist?(@config.after_fork_file)
+        return "the after-fork file #{@config.after_fork_file} does not exist"
+      end
       if InMemoryLoader.load_time_defined_guard?(@original_content)
         return 'the source file uses defined? at load time, so redefinition would silently skip the guarded code'
       end
@@ -451,7 +482,7 @@ module MutationTester
       offset_callback = progress_callback && lambda do |mutation, index|
         progress_callback.call(mutation, completed + index)
       end
-      run_in_place_series(mutations, &offset_callback)
+      run_file_based_series(mutations, &offset_callback)
     end
 
     def fall_back_to_parallel_file_based(reason, mutations, &progress_callback)
@@ -470,8 +501,9 @@ module MutationTester
     def announce_worker_env_in_memory_opt_out
       return unless @config.worker_env_var
       return unless %i[in_memory auto].include?(@config.runner)
+      return if @config.parallel_processes == 1 || @config.after_fork_file
 
-      warn "[MutationTester] --worker-env #{@config.worker_env_var} is set, so the in-memory runner is skipped (its clones share one preloaded database connection); using the fork runner for per-worker database isolation."
+      warn "[MutationTester] --worker-env #{@config.worker_env_var} is set without --after-fork, so the in-memory runner is skipped (its clones share one preloaded database connection); using the fork runner for per-worker database isolation. Pass --after-fork FILE to keep the in-memory runner and re-establish per-worker connections inside each clone."
     end
 
     def run_mutation_load_time(mutation, result, project_root)

data/lib/mutation_tester/version.rb

@@ -1,3 +1,3 @@
 module MutationTester
-  VERSION = '1.4.1'.freeze
+  VERSION = '1.5.0'.freeze
 end

data/readme.md

@@ -204,11 +204,14 @@ mutation_test [OPTIONS] --glob 'lib/**/*.rb'
 | `--staged` | Mutation-test the files staged in git (`git diff --cached --name-only`; files staged as deleted are ignored), mapping each to its spec like a positional `FILE` list. Cannot be combined with positional arguments or `--glob`. See [File lists and --staged](#file-lists-and---staged-test-what-you-changed). |
 | `--glob PATTERN` | Batch mode: mutation-test every source file matching `PATTERN`, mapping each to its spec by convention (see [Batch mode](#batch-mode-run-many-files-in-one-command)). |
 | `--spec-glob TEMPLATE` | Spec-mapping template with a `{name}` placeholder (default: `spec/{name}_spec.rb`). Requires a positional `FILE` list, `--staged`, or `--glob`. |
+| `--spec-map RULE` | Spec-mapping rule `'PATTERN=>REPLACEMENT'`: a regular expression applied to the whole source path to build the whole spec path, for layouts a `{name}` template cannot express (Rails `app/` -> `test/`, engines, Packwerk packs). Repeatable, first matching rule wins, a source matching no rule falls back to `--spec-glob`. Requires a positional `FILE` list, `--staged`, or `--glob`. See [Mapping sources to specs](#mapping-sources-to-specs). |
+| `--minimum-score N` | Mutation score percentage a file must reach to pass (default: 80). Drives the `PASS`/`FAIL` verdict and the exit code. |
 | `--since REV` | Incremental batch mode: mutate only the files matched by `--glob` that changed since git revision `REV` (new files count as changed). Requires `--glob`. See [Incremental mode](#incremental-mode-mutate-only-what-changed). |
 | `--fail-fast` | Stop the run at the first surviving mutant and finish with a failing status. Works in single-file mode and with `--glob`. |
 | `--timeout-factor N` | Per-mutant timeout budget as `N` times the measured baseline test run, never below 5 s (default: 5, must be > 0). Ignored when `config.timeout` is set explicitly, which keeps a fixed budget. See [Configuration](#configuration). |
 | `--timeout-policy MODE` | Scoring policy for timed-out mutants: `killed` (default) counts a timeout as a kill; `separate` keeps timeouts out of the score entirely (`killed / (killed + survived)`) and reports them only as their own category in the console, JSON and HTML reports. |
-| `--worker-env NAME` | Set environment variable `NAME` to a distinct per-worker value before each parallel worker boots (`parallel_tests` `TEST_ENV_NUMBER` convention: worker 0 -> `""`, worker N -> `N+1`), so a `parallel_tests`-style `database.yml` selects a per-worker database. You provision the databases (e.g. `rake parallel:prepare`). Not supported by the `in_memory` runner (it falls back to `fork`). See [Making parallelism work with Rails](#making-parallelism-work-with-rails). |
+| `--worker-env NAME` | Set environment variable `NAME` to a distinct per-worker value before each parallel worker boots (`parallel_tests` `TEST_ENV_NUMBER` convention: worker 0 -> `""`, worker N -> `N+1`), so a `parallel_tests`-style `database.yml` selects a per-worker database. You provision the databases (e.g. `rake parallel:prepare`). A parallel `in_memory` run falls back to `fork` unless `--after-fork` is also given; a serial run (`-p 1`) decides mutants in a shadow workspace instead of mutating the checkout in place. See [Making parallelism work with Rails](#making-parallelism-work-with-rails). |
+| `--after-fork FILE` | Ruby file loaded inside each preloaded in-memory clone right after it forks and receives its per-worker environment (see `--worker-env`), so the app can re-establish per-worker state such as its database connection. With `--worker-env` set, this keeps the `in_memory` runner available in parallel runs. A clone whose after-fork file raises is dropped with a stderr warning and its worker falls back to file-based execution. See [Making parallelism work with Rails](#making-parallelism-work-with-rails). |
 | `--strict-equality` | Enable the opt-in strict-equality probes (`==` → `eql?` and `==` → `equal?`). Default off; expect noise on code that does not distinguish numeric types or object identity. See [Strict Equality Mutations](docs/mutation-types.md#strict-equality-mutations-opt-in). |
 | `-h, --help` | Show help message. |
 | `-v, --version` | Show version. |
@@ -314,8 +317,8 @@ reported as `SKIPPED` with an explicit reason and never count as a success:
 - **not a Ruby source file** - e.g. a staged `.md` or config file.
 - **a test file, not a mutable source** - a test file passed directly
   (`*_spec.rb`, `*.spec.rb`, `*_test.rb`, `test_*.rb`, or minitest content).
-- **no matching spec file** - the convention (or `--spec-glob`) points at a
-  spec that does not exist; the expected path is printed.
+- **no matching spec file** - the convention (or `--spec-glob` / `--spec-map`)
+  points at a spec that does not exist; the expected path is printed.
 
 Exit codes: `0` when at least one file was processed and every processed file
 met the threshold; `1` when any processed file was below threshold or when
@@ -336,16 +339,8 @@ run, so you no longer need to script a loop around `mutation_test` or depend on
 the Rails-only `rake mutation:test_models` task.
 
 Each matched source file is mapped to its spec by convention: `lib/X.rb` becomes
-`spec/X_spec.rb`. Concretely the spec path is `spec/{name}_spec.rb` where `{name}`
-is the source path with a leading `lib/` segment removed and the `.rb` extension
-stripped, subdirectories preserved (`lib/foo/bar.rb` -> `spec/foo/bar_spec.rb`).
-
-Override the convention with `--spec-glob TEMPLATE`, a template containing the
-`{name}` placeholder. For a Minitest project laid out under `test/`:
-
-```bash
-bundle exec mutation_test --glob 'lib/**/*.rb' --spec-glob 'test/{name}_test.rb'
-```
+`spec/X_spec.rb`. See [Mapping sources to specs](#mapping-sources-to-specs) for
+the two ways to override that convention.
 
 Behaviour:
 
@@ -359,18 +354,27 @@ Behaviour:
   file with its score and `PASS`/`FAIL` against the threshold, followed by a
   clearly separated `SKIPPED` list.
 - **A source file with no matching spec is `SKIPPED`**, reported explicitly and
-  never counted as a success. A skipped file does not by itself fail the run.
+  never counted as a success. A single skipped file next to processed ones does
+  not by itself fail the run, but a run that skipped *every* matched file
+  measured nothing and fails (see the exit codes below).
 
 Exit codes:
 
-- `0` - every processed file met the mutation score threshold (including a
-  `--since` run where nothing changed, see below).
+- `0` - at least one file was mutation-tested and every processed file met the
+  mutation score threshold. A `--since` run where nothing changed also exits `0`
+  (see below).
 - `1` - at least one processed file was below threshold, the glob matched no
-  source files at all, or `--fail-fast` stopped the run at a surviving mutant.
-- `2` - a usage error: `--spec-glob` with an explicit `SOURCE_FILE TEST_FILE`
-  pair, `--since` given without `--glob`, `--staged` combined with positional
-  arguments or `--glob`, or `--since`/`--staged` used outside a git repository
-  (for `--since` also an unknown revision).
+  source files at all, every matched file was skipped so nothing was actually
+  mutation-tested, or `--fail-fast` stopped the run at a surviving mutant.
+- `2` - a usage error: `--spec-glob` or `--spec-map` with an explicit
+  `SOURCE_FILE TEST_FILE` pair, a malformed `--spec-map` rule, `--since` given
+  without `--glob`, `--staged` combined with positional arguments or `--glob`,
+  or `--since`/`--staged` used outside a git repository (for `--since` also an
+  unknown revision).
+
+The "every matched file was skipped" case is deliberate: a typo in
+`--spec-glob`/`--spec-map`, or a refactor that moves the test directory, would
+otherwise leave a green CI step that measured nothing.
 
 ```bash
 # Minitest project, JSON report per file, custom output directory
@@ -378,6 +382,66 @@ bundle exec mutation_test --glob 'lib/**/*.rb' --spec-glob 'test/{name}_test.rb'
   --reporters json --output-dir build/mutation
 ```
 
+### Mapping sources to specs
+
+Every mode that takes more than an explicit `SOURCE_FILE TEST_FILE` pair (a
+positional `FILE` list, `--staged`, `--glob`) derives the test path from the
+source path. Two mechanisms do that, checked in this order:
+
+1. `--spec-map 'PATTERN=>REPLACEMENT'` - regular-expression rules.
+2. `--spec-glob TEMPLATE` - a `{name}` template (default `spec/{name}_spec.rb`).
+
+**`--spec-glob TEMPLATE`** substitutes `{name}`, which is the source path with a
+leading `lib/` segment removed and the `.rb` extension stripped, subdirectories
+preserved (`lib/foo/bar.rb` -> `spec/foo/bar_spec.rb`). Because `{name}` is one
+value, a template can only add a prefix and a suffix around the source path. For
+a Minitest project laid out under `test/` that is enough:
+
+```bash
+bundle exec mutation_test --glob 'lib/**/*.rb' --spec-glob 'test/{name}_test.rb'
+```
+
+**`--spec-map 'PATTERN=>REPLACEMENT'`** covers the layouts a template cannot
+express: those that substitute *inside* the path, after a variable-length
+prefix. `PATTERN` is a Ruby regular expression matched against the whole source
+path (a leading `./` removed); the first `=>` separates it from `REPLACEMENT`,
+which may use `\1`, `\2`, ... backreferences and produces the whole spec path.
+Only the first match in the path is replaced.
+
+- The flag is repeatable and the first matching rule wins.
+- A source that matches no rule falls back to `--spec-glob` (or the default
+  convention), so one command can cover `app/` and `lib/` at once.
+- Quote the rule in single quotes so the shell leaves the backslashes alone.
+
+Rails and Rails-shaped layouts, where the rule is "replace the `app/` segment
+with `test/`, keep whatever prefix comes before it":
+
+```bash
+# Plain Rails, Minitest: app/models/current.rb -> test/models/current_test.rb
+bundle exec mutation_test --glob 'app/**/*.rb' \
+  --spec-map '\Aapp/(.+)\.rb\z=>test/\1_test.rb'
+
+# Plain Rails, RSpec: app/models/user.rb -> spec/models/user_spec.rb
+bundle exec mutation_test --glob 'app/**/*.rb' \
+  --spec-map '\Aapp/(.+)\.rb\z=>spec/\1_spec.rb'
+
+# Packwerk / packs-rails and engines, with the app root as an optional prefix:
+#   app/models/current.rb                -> test/models/current_test.rb
+#   packs/identity/app/models/party.rb   -> packs/identity/test/models/party_test.rb
+#   engines/billing/app/jobs/send_job.rb -> engines/billing/test/jobs/send_job_test.rb
+bundle exec mutation_test --glob '{app,packs/*/app,engines/*/app}/**/*.rb' \
+  --spec-map '\A((?:(?:packs|engines)/[^/]+/)?)app/(.+)\.rb\z=>\1test/\2_test.rb'
+
+# app/ through the rule, lib/ through the template, in one run
+bundle exec mutation_test --glob '{app,lib}/**/*.rb' \
+  --spec-map '\Aapp/(.+)\.rb\z=>test/\1_test.rb' \
+  --spec-glob 'test/{name}_test.rb'
+```
+
+When a rule produces a path that does not exist, the file is reported as
+`SKIPPED (no matching spec file)` with the expected path printed, and a run in
+which *every* file was skipped that way fails with exit code `1`.
+
 ### Incremental mode: mutate only what changed
 
 `--since REV` narrows a `--glob` batch to the files that changed since a git
@@ -447,6 +511,19 @@ MutationTester.configure do |config|
   # setting a specific mode forces it. See the Execution model section below.
   config.runner = :auto
 
+  # Per-worker database isolation (parallel_tests TEST_ENV_NUMBER convention).
+  # Set to an environment variable name to give each parallel worker a distinct
+  # value before it boots its test environment. Equivalent to the --worker-env
+  # CLI flag. See Making parallelism work with Rails below.
+  # config.worker_env_var = "TEST_ENV_NUMBER"
+
+  # Ruby file loaded inside each preloaded in-memory clone right after it forks
+  # and receives its per-worker environment, so the app can re-establish
+  # per-worker state such as its database connection. Keeps the in_memory
+  # runner available in parallel worker-env runs. Equivalent to the
+  # --after-fork CLI flag.
+  # config.after_fork_file = "db/mutation_after_fork.rb"
+
   # Two-phase test selection (RSpec only): fast-kill on a matching example
   # subset, always confirmed by the full file before a mutant is reported as
   # survived. Set to false to always run the full file. See Execution model.
@@ -463,7 +540,7 @@ MutationTester.configure do |config|
   # Set it explicitly to write elsewhere (this example uses "mutation_reports"):
   config.output_dir = "mutation_reports"
 
-  # Quality thresholds
+  # Quality thresholds. The CLI flag --minimum-score overrides this per run.
   config.minimum_score = 80.0
   config.fail_on_threshold = true
 
@@ -581,16 +658,48 @@ bundle exec mutation_test app/models/user.rb spec/models/user_spec.rb \
   -p 4 --worker-env TEST_ENV_NUMBER
 
 # Batch over a whole directory the same way
-bundle exec mutation_test --glob 'app/models/**/*.rb' --spec-glob 'spec/models/{name}_spec.rb' \
+bundle exec mutation_test --glob 'app/models/**/*.rb' \
+  --spec-map '\Aapp/(.+)\.rb\z=>spec/\1_spec.rb' \
   -p 4 --worker-env TEST_ENV_NUMBER
 ```
 
 `MUTATION_TESTER_WORKER_ENV=TEST_ENV_NUMBER` is equivalent to passing the flag.
 
-**Runner support.** `--worker-env` works with the `fork` and `spawn` runners, where each mutant boots its test
-environment freshly and picks up the variable. The `in_memory` runner clones a single preloaded worker that has already
-connected to one database, so it cannot isolate a per-worker database; when `--worker-env` is set the runner selection
-skips `in_memory` and uses `fork`, announcing the reason on stderr.
+**Runner support.** `--worker-env` works with the `fork` and `spawn` runners out of the box, because each mutant boots
+its test environment freshly and picks up the variable. The `in_memory` runner clones a single preloaded worker that
+has already connected to one database, so setting the variable alone cannot re-point an existing connection; in a
+parallel run without `--after-fork` the runner selection therefore skips `in_memory` and uses `fork`, announcing the
+reason on stderr. A serial run (`-p 1`) has only one worker and stays in memory.
+
+**Keeping the in-memory runner with `--after-fork`.** Pass `--after-fork FILE` (or
+`MUTATION_TESTER_AFTER_FORK=FILE`) to keep the `in_memory` runner in parallel worker-env runs. Each preloaded clone
+then receives its per-worker value of the `--worker-env` variable and loads `FILE` right after forking, and that file
+is where your app re-establishes its per-worker state. For a Rails app with a `TEST_ENV_NUMBER`-keyed `database.yml`
+that usually means reconnecting ActiveRecord:
+
+```ruby
+# db/mutation_after_fork.rb
+ActiveRecord::Base.establish_connection(
+  ActiveRecord::Base.configurations
+    .configs_for(env_name: 'test', name: 'primary')
+    .configuration_hash
+    .merge(database: "myapp_test#{ENV['TEST_ENV_NUMBER']}")
+)
+```
+
+```bash
+bundle exec mutation_test app/models/user.rb spec/models/user_spec.rb \
+  -p 4 --worker-env TEST_ENV_NUMBER --after-fork db/mutation_after_fork.rb
+```
+
+The file runs once per clone, inside the clone only (never in the primary preloaded worker or in your shell process).
+If it raises, the clone reports the error on stderr and is dropped, and its worker decides its share of mutants through
+the file-based path; if the file does not exist, the whole run falls back to file-based execution with a warning.
+
+**Serial runs never mutate your checkout.** With `--worker-env` set, a `-p 1` run on the file-based runners decides
+each mutant in a shadow workspace instead of writing mutants into the real source file, so a killed process cannot
+leave a mutated file behind. (Without `--worker-env`, a serial file-based run still uses in-place mutation with a
+`.mutation_backup` file that the next run restores automatically.)
 
 **Still simplest without a parallel database setup:** if you have not provisioned per-worker databases, keep Rails
 model runs on serial `-p 1`. `--worker-env` is only useful once the databases exist.
@@ -853,6 +962,14 @@ can drop the `jq` comparison and let the exit code be the gate:
 bundle exec mutation_test app/models/user.rb spec/models/user_spec.rb || exit 1
 ```
 
+`--minimum-score N` sets that threshold for a single run, which is how you start
+below 80 in an existing codebase and ratchet the number up over time:
+
+```sh
+bundle exec mutation_test --glob 'app/**/*.rb' \
+  --spec-map '\Aapp/(.+)\.rb\z=>spec/\1_spec.rb' --minimum-score 60 || exit 1
+```
+
 lefthook or overcommit users: call the shipped hook from your `pre-push` step
 instead of writing to `.git/hooks/`.
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mutation_tester
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Kamil Dzierbicki
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parallel