mutation_tester 1.4.0 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be945d45b6c4219df627808a62336abe51ce94b088d79db47e25c794cdf227bd
-  data.tar.gz: 80aaefd644319415bfb25cebab5eb28077f3b99c763d234d20cf6885f3c001d2
+  metadata.gz: c743765bd0adb455bf1162627a35cb5b3232d45cfb83dca91ab139248a3acac1
+  data.tar.gz: 71eb3f98c61271896c6c4cc2e3b9b69c62fee77d50b3d94c0237b0dac9eefd53
 SHA512:
-  metadata.gz: 2ad47074139c21bb7cd6db12eb53d2dd8c350b85c24c43f2ce44ba25590da1b3a4aa3f2e9f5ea2394abbdb8779e50cb9b3bb94418a94b03a1148ef2bd186b1f0
-  data.tar.gz: 58078c8af01ec3155be934d6917a3b66b0779f70bc20b04a23d05f82c06e9198000156fc13a7f7eece21cff11582d6b142a5ffb4aaa11d3191c15ebe4c3d9fbb
+  metadata.gz: 3fac687f4fd5496daced6e16cf30e3dc39a0816fc5be7fe9f37caae4a05d3e088bdf1f80ee5b23f72610741d767cd410de81c6fcec09b4456d2936549f32266c
+  data.tar.gz: 13842db8fe228decfe6d3e165e5f80ea3c18af549e09051a3b12342f1ff3251ea5f81f8d375d1f0bdc5e76b6320f101ce791900016b8054630a3e0c2e14f3227

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [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`.
+- The shadow-workspace sanity check now also proves that the workspace copy of the source is the code the tests execute: after the unmutated source passes there, the check replaces that copy with a `raise` and requires the run to fail. When it still passes, the run aborts as an infrastructure failure (exit code `3`) naming the likely causes, instead of reporting a complete-looking 0.0% score in which every mutant falsely survived.
+- The console summary now warns when a file with at least five scored mutants killed none of them, pointing at the runner rather than at test quality and suggesting a `--runner spawn` comparison.
+
 ## [1.4.0] - 2026-08-01
 
 - Minitest suites now use the same execution runners as RSpec instead of being pinned to `spawn`. The fork worker preloads `minitest` (disabling the `minitest/autorun` at-exit hook and driving `Minitest.run` itself, so the file still runs exactly once per mutant) and the in-memory runner preloads the test file once and re-evaluates each mutant in a fresh fork, so a Minitest project no longer pays a full interpreter, Bundler and framework boot per mutant. Preloaded workers are now keyed by framework, so a mixed-framework `--glob` run never hands a Minitest file to an RSpec-preloaded worker.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mutation_tester (1.4.0)
+    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

@@ -110,6 +110,15 @@ can cross the per-mutant deadline and be reported as a `timeout` instead of a
   `spawn`, even when `--runner fork` is requested.
 - If the helper process fails to preload the environment, the run warns once
   and falls back to `spawn`.
+- The helper process is started once in the real project root, so Ruby has
+  already absolutized every `-I` / `RUBYLIB` entry against that directory before
+  any mutant runs. Changing directory into a shadow workspace cannot undo that,
+  so each job additionally rewrites the `$LOAD_PATH` entries that point into the
+  mirrored project root so they point into the workspace. Without it a Minitest
+  file reaching its source through `require "test_helper"` would load the
+  original, unmutated tree and every mutant would falsely survive. RSpec re-adds
+  `lib` and its default path at run time, after the child has changed directory,
+  so it resolves the workspace copy either way.
 
 ### Limitations of the in-memory runner
 

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
@@ -150,6 +158,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,6 +173,7 @@ 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]
@@ -224,18 +240,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 +270,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 +298,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 +313,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
@@ -56,7 +57,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

data/lib/mutation_tester/core.rb

@@ -132,13 +132,25 @@ module MutationTester
       return true if mutation_runner.in_memory_first?
 
       puts Rainbow("\n🩺 Verifying the shadow workspace with the unmutated source...").yellow
-      if mutation_runner.shadow_baseline_passes?
-        puts Rainbow('✓ Shadow workspace verified with the unmutated source').green
-        return true
+      case mutation_runner.shadow_workspace_check
+      when :ok
+        puts Rainbow('✓ Shadow workspace verified: the unmutated source passes and the workspace copy is what the tests execute').green
+        true
+      when :canary
+        report_unreachable_workspace_source
+      else
+        puts Rainbow('❌ The unmutated source fails inside the shadow workspace; the shadow environment is unreliable.').red
+        puts Rainbow('   Every mutant would falsely die there, so the run is aborted instead of reporting a misleading score.').red
+        false
       end
+    end
 
-      puts Rainbow('❌ The unmutated source fails inside the shadow workspace; the shadow environment is unreliable.').red
-      puts Rainbow('   Every mutant would falsely die there, so the run is aborted instead of reporting a misleading score.').red
+    def report_unreachable_workspace_source
+      puts Rainbow('❌ The tests still pass with the workspace copy of the source replaced by a raise.').red
+      puts Rainbow('   The mutated file is therefore not the code the tests execute, so every mutant would falsely').red
+      puts Rainbow('   survive; the run is aborted instead of reporting a misleading 0.0% score.').red
+      puts Rainbow('   Usual causes: the tests resolve this source outside the workspace (an absolute entry in').red
+      puts Rainbow('   $LOAD_PATH, a symlinked .rb file, a preloaded copy of the class), or they never load it at all.').red
       false
     end
 

data/lib/mutation_tester/fork_runner/worker.rb

@@ -26,6 +26,26 @@ end
 
 monotonic = lambda { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
 
+resolved_path = lambda do |path|
+  File.realpath(path)
+rescue SystemCallError
+  path
+end
+
+mirror_load_path = lambda do |from, to|
+  next if from.nil? || to.nil? || from == to
+
+  roots = [from, resolved_path.call(from)].uniq.map { |root| root.chomp('/') }
+  $LOAD_PATH.map! do |entry|
+    path = File.expand_path(entry.to_s, from)
+    root = roots.find { |candidate| path == candidate || path.start_with?("#{candidate}/") }
+    next entry unless root
+
+    suffix = path.delete_prefix(root).delete_prefix('/')
+    suffix.empty? ? to : File.join(to, suffix)
+  end
+end
+
 current_child = nil
 preloaded = nil
 
@@ -50,6 +70,7 @@ supervise_child = lambda do |job, out, child_body|
     rescue Errno::EACCES, Errno::EPERM
     end
     Dir.chdir(job['chdir']) if job['chdir']
+    mirror_load_path.call(job['mirror_of'], job['chdir'])
     sink = File.open(job['log'] || File::NULL, 'w')
     sink.sync = true
     STDOUT.reopen(sink)

data/lib/mutation_tester/fork_runner.rb

@@ -153,7 +153,8 @@ module MutationTester
       @ready
     end
 
-    def execute(spec_file, timeout: nil, chdir: nil, capture: false, args: [], stop_on_first_failure: false)
+    def execute(spec_file, timeout: nil, chdir: nil, capture: false, args: [], stop_on_first_failure: false,
+                mirror_of: nil)
       log = capture ? Tempfile.new(['mutation_tester_fork', '.log']) : nil
       job = {
         spec: spec_file,
@@ -161,7 +162,8 @@ module MutationTester
         chdir: chdir,
         log: log&.path,
         args: args,
-        stop_on_first_failure: stop_on_first_failure
+        stop_on_first_failure: stop_on_first_failure,
+        mirror_of: mirror_of
       }
       @job_writer.puts(JSON.generate(job))
       status = await_result(timeout)['status']

data/lib/mutation_tester/mutation_runner.rb

@@ -4,6 +4,7 @@ require 'securerandom'
 
 module MutationTester
   class MutationRunner
+    CANARY_SOURCE = "raise 'mutation_tester canary: the workspace copy of this source was not executed'\n".freeze
     PARALLEL_INTERRUPT_LINE = "Parallel execution interrupted, exiting ...\n"
 
     class ParallelInterruptFilter
@@ -216,7 +217,7 @@ module MutationTester
         File.write(shadow_source, mutation[:code])
 
         outcome, phase = run_two_phase(mutation) do |example_filters|
-          run_specs_in_shadow(shadow_spec, shadow_root, example_filters: example_filters)
+          run_specs_in_shadow(shadow_spec, shadow_root, project_root, example_filters: example_filters)
         end
         apply_outcome(result, outcome, phase)
       ensure
@@ -240,6 +241,10 @@ module MutationTester
     end
 
     def shadow_baseline_passes?
+      shadow_workspace_check == :ok
+    end
+
+    def shadow_workspace_check
       project_root = find_project_root
 
       Dir.mktmpdir do |temp_dir|
@@ -254,12 +259,16 @@ module MutationTester
 
         File.unlink(shadow_source)
         File.write(shadow_source, @original_content)
+        return :baseline unless run_specs_in_shadow(shadow_spec, shadow_root, project_root).passed?
 
-        run_specs_in_shadow(shadow_spec, shadow_root).passed?
+        File.write(shadow_source, CANARY_SOURCE)
+        return :canary if run_specs_in_shadow(shadow_spec, shadow_root, project_root).passed?
+
+        :ok
       end
     rescue => e
       warn("[MutationTester] Shadow sanity check could not prepare the shadow workspace: #{e.message}")
-      false
+      :baseline
     end
 
     def shadow_copy_project(source, dest)
@@ -284,8 +293,9 @@ module MutationTester
       end
     end
 
-    def run_specs_in_shadow(spec_file, working_dir, example_filters: [])
-      test_command(spec_file, example_filters: example_filters).run(timeout: @config.effective_timeout, chdir: working_dir)
+    def run_specs_in_shadow(spec_file, working_dir, project_root, example_filters: [])
+      test_command(spec_file, example_filters: example_filters)
+        .run(timeout: @config.effective_timeout, chdir: working_dir, mirror_of: project_root)
     end
 
     def discoverable_project_root

data/lib/mutation_tester/reporters/console_reporter.rb

@@ -1,12 +1,15 @@
 module MutationTester
   module Reporters
     class ConsoleReporter < BaseReporter
+      NOTHING_KILLED_MIN_MUTANTS = 5
+
       def generate
         puts "\n" + Rainbow('=' * 80).bright
         puts Rainbow('🧬 MUTATION TESTING REPORT').bright.cyan
         puts Rainbow('=' * 80).bright
 
         print_summary
+        print_nothing_killed_warning
         print_survived_mutations if survived_count > 0
 
         puts "\n" + Rainbow('=' * 80).bright
@@ -30,6 +33,23 @@ module MutationTester
         puts "\n  " + progress_bar
       end
 
+      def print_nothing_killed_warning
+        return unless nothing_killed?
+
+        puts "\n#{Rainbow("⚠️  Not one of the #{scored_mutant_count} scored mutants was killed.").yellow}"
+        puts Rainbow('   A whole file that kills nothing is more often a runner problem (the mutated code never').yellow
+        puts Rainbow('   reached the tests) than a test-quality gap. Re-run with --runner spawn and compare before').yellow
+        puts Rainbow('   acting on this score.').yellow
+      end
+
+      def nothing_killed?
+        killed_count.zero? && timeout_count.zero? && scored_mutant_count >= NOTHING_KILLED_MIN_MUTANTS
+      end
+
+      def scored_mutant_count
+        killed_count + timeout_count + survived_count
+      end
+
       def print_timeout_deadline
         return unless timeout_count.positive?
 

data/lib/mutation_tester/test_command.rb

@@ -40,7 +40,7 @@ module MutationTester
       cmd
     end
 
-    def run(timeout: nil, chdir: nil, capture: false)
+    def run(timeout: nil, chdir: nil, capture: false, mirror_of: nil)
       if fork_execution?
         fork_runner = ForkRunner.acquire(use_bundle_exec: @use_bundle_exec, framework: @framework)
         if fork_runner
@@ -50,7 +50,8 @@ module MutationTester
             chdir: chdir || Dir.pwd,
             capture: capture,
             args: filter_args,
-            stop_on_first_failure: @stop_on_first_failure
+            stop_on_first_failure: @stop_on_first_failure,
+            mirror_of: mirror_of
           )
         end
       end

data/lib/mutation_tester/version.rb

@@ -1,3 +1,3 @@
 module MutationTester
-  VERSION = '1.4.0'.freeze
+  VERSION = '1.4.2'.freeze
 end

data/readme.md

@@ -204,6 +204,8 @@ 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). |
@@ -232,7 +234,9 @@ bundle exec mutation_test --reporters json,html --output-dir build/mutation \
   file, unknown reporter, source with a syntax error).
 - `2` - a usage error (conflicting flags; see the batch sections below).
 - `3` - the run aborted or degraded before reaching a verdict: the shadow workspace
-  was unreliable, or every mutant ended as `error`/`stillborn` so nothing was scored.
+  was unreliable (the unmutated source failed there, or the workspace copy of the
+  source turned out not to be the code the tests execute), or every mutant ended as
+  `error`/`stillborn` so nothing was scored.
   This signals an infrastructure or runner problem, not a test-quality gap, so CI
   hooks can distinguish it from a genuine threshold failure.
 - `130` - interrupted with Ctrl+C.
@@ -312,8 +316,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
@@ -334,16 +338,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:
 
@@ -357,18 +353,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
@@ -376,6 +381,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
@@ -461,7 +526,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
 
@@ -523,7 +588,16 @@ invalid value (less than 1, or non-numeric) falls back to 1 with a warning on st
 In parallel mode each mutant runs in an isolated shadow workspace. Every `.rb`
 file is a physical copy (non-Ruby files stay symlinks for speed), so mutations
 apply correctly even when a spec loads the source indirectly (e.g. via
-`spec_helper`). The parallel mutation score therefore matches serial.
+`spec_helper`), and `$LOAD_PATH` entries pointing into the project resolve
+inside the workspace, so a test file that reaches its source through
+`require "test_helper"` gets the mutated copy too. The parallel mutation score
+therefore matches serial.
+
+Before the first mutant, the run proves this in the workspace itself: the
+unmutated source must pass there, and the same suite must fail once that copy of
+the source is replaced by a `raise`. A run whose tests pass even then is aborted
+as an infrastructure failure (exit code `3`) rather than reported as a 0.0%
+score, because the mutated file is demonstrably not the code being executed.
 
 ### When to use serial vs parallel execution
 
@@ -570,7 +644,8 @@ 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
 ```
 
@@ -842,6 +917,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.0
+  version: 1.4.2
 platform: ruby
 authors:
 - Kamil Dzierbicki
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-01 00:00:00.000000000 Z
+date: 2026-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parallel