mutation_tester 1.4.1 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8391c9817c1f430ec2231982495e11ff1f6866c3ce11b8e67d9ab421894c44ab
-  data.tar.gz: c82152c72bf0c0faaa22807ade06134fc814dd0faddde7f3849100b29b2f54fa
+  metadata.gz: c743765bd0adb455bf1162627a35cb5b3232d45cfb83dca91ab139248a3acac1
+  data.tar.gz: 71eb3f98c61271896c6c4cc2e3b9b69c62fee77d50b3d94c0237b0dac9eefd53
 SHA512:
-  metadata.gz: d663fe8bc725c6b99e50d0752c3c8452397794672ac2a79a64e1cc6da70b1076abca47bf5143050cc3afd405320ff584d17c587cca8fff47bed27a3f184ed543
-  data.tar.gz: f33e5cbcdf08e032015b358e2b027b7846af163d2d5bab5954abf13f6d06d48e3a584677ace35e97f9aee67e48faa96a5c5ffcc2704b9416984e4605bcecdff1
+  metadata.gz: 3fac687f4fd5496daced6e16cf30e3dc39a0816fc5be7fe9f37caae4a05d3e088bdf1f80ee5b23f72610741d767cd410de81c6fcec09b4456d2936549f32266c
+  data.tar.gz: 13842db8fe228decfe6d3e165e5f80ea3c18af549e09051a3b12342f1ff3251ea5f81f8d375d1f0bdc5e76b6320f101ce791900016b8054630a3e0c2e14f3227

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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`.

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/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/version.rb

@@ -1,3 +1,3 @@
 module MutationTester
-  VERSION = '1.4.1'.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). |
@@ -314,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
@@ -336,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:
 
@@ -359,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
@@ -378,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
@@ -463,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
 
@@ -581,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
 ```
 
@@ -853,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.1
+  version: 1.4.2
 platform: ruby
 authors:
 - Kamil Dzierbicki
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parallel