mutation_tester 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20fff769b6b8b7efeb874208f5e3c25206ca92a2fc9f220bdd4fcb520eab944c
-  data.tar.gz: 3b630985b285958780d49d356cbe04f629ce50e1aca947d2f40d8bdddd274d42
+  metadata.gz: 03a2b2364ebede84e6b56cfe4fba7d0450475262d59aa754abe0ce34ee1a83ba
+  data.tar.gz: 7439181f228ffbf2d1cf2e603ac21a91a46c764cd66f0ebfcc40dab30a2f2188
 SHA512:
-  metadata.gz: f40cf255d91681f4ae191b444ba8f99ba897ea746b2f157190d69bce091e90c4aaec9bde9c73fe69008de17916478ff40227a7e2439de687d4a576d72d664d0a
-  data.tar.gz: 9c8d46ca0d8a98dff41de40b61e8fdd60c68c55ed37303e02d08009968a0263bf932e0892af3e13af12810c27cb61f695f1d01a77e46f2dbc375735fe49b87a4
+  metadata.gz: 6be68e2928ca7ecc1a382e01c66cb5ab7d0afa35e5cf5b6008a62d0599fe399af17a8960a3f4e62025d40e640850c4fde423cff5aa2de69d34db2f6139661342
+  data.tar.gz: fb12cf8fd83bc37529e7e0fcdc8bb72bc902df0c846b05ad8fb856d8db8b382cf18fb2058b42f5efa2b161f573517b368d7aee92563c4115c7b3669a3d2e5ba9

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [1.3.0] - 2026-07-15
+
+- Calibrated the per-mutant timeout against the measured baseline run: unless `config.timeout` is set explicitly, each mutant now gets `max(5s, timeout_factor * baseline duration)` (factor configurable via `config.timeout_factor` / `--timeout-factor N`, default 5) instead of a fixed 30 s, so a loaded machine no longer inflates the mutation score by killing healthy-but-slow runs as timeouts. An explicit `config.timeout` (including `nil` for no deadline) keeps today's fixed-budget behavior and disables calibration. Added the opt-in `config.timeout_policy = :separate` / `--timeout-policy separate`, which scores `killed / (killed + survived)` with timeouts excluded from the score and reported only as their own category; the default `:killed` policy and its output are unchanged.
+- Runs that finish without a single scored mutant (every mutant errored or was stillborn) are now reported as an infrastructure/runner failure with the error/stillborn counts instead of a misleading "score 0.0% is below threshold" verdict. `Core` exposes `infrastructure_failure?` to distinguish such degraded runs (including the shadow-workspace abort) from a genuine threshold failure, and `mutation_test` maps them to the new exit code `3` in single-file mode (`0` pass, `1` threshold failure, `2` usage error, `130` interrupt). The batch summary names degraded files instead of blaming the threshold.
+
 ## [1.2.0] - 2026-07-14
 
 - Fixed the in-memory runner reporting false survivors for mutations that only take effect at class-load time (constants consumed by macros, `validates`/`has_many`/`before_save`/`scope`/`attribute`, and anything inside an `included do` block). The mutator now classifies each mutation by AST context, and the in-memory run routes load-time mutations to the file-based path while keeping method-body mutations in memory, so the default (`auto`) score matches a full `fork` run on Rails concerns and models. Measured on a real Rails concern the default score went from a misleading 1.63% to the correct 35.77%.

data/Gemfile.lock

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

data/docs/json-schema.md

@@ -52,13 +52,13 @@ history of changes.
 | `metadata.source_file`         | string  | Absolute path of the mutated source file.                                                                                                                                                                                                                                                                                                       |
 | `metadata.spec_file`           | string  | Absolute path of the test file that was run.                                                                                                                                                                                                                                                                                                    |
 | `summary.total`                | integer | Total number of mutations produced (all statuses).                                                                                                                                                                                                                                                                                              |
-| `summary.killed`               | integer | Effective kills (a `timeout` counts as a kill). Kept for backward compatibility.                                                                                                                                                                                                                                                                |
+| `summary.killed`               | integer | Effective kills (a `timeout` counts as a kill; under the opt-in `timeout_policy: :separate` only real kills are counted). Kept for backward compatibility.                                                                                                                                                                                      |
 | `summary.survived`             | integer | Number of surviving mutants.                                                                                                                                                                                                                                                                                                                    |
-| `summary.mutation_score`       | number  | Percentage `(killed + timeout) / (killed + timeout + survived) * 100`, rounded to 2 decimals. `stillborn` and `error` are excluded from the denominator.                                                                                                                                                                                        |
+| `summary.mutation_score`       | number  | Percentage `(killed + timeout) / (killed + timeout + survived) * 100`, rounded to 2 decimals; under the opt-in `timeout_policy: :separate` it is `killed / (killed + survived) * 100` with timeouts excluded. `stillborn` and `error` are excluded from the denominator.                                                                        |
 | `summary.quality_rating`       | string  | Human label derived from the score (Excellent/Good/Fair/Poor/Critical).                                                                                                                                                                                                                                                                         |
 | `summary.categories.killed`    | integer | Mutants whose covering tests failed.                                                                                                                                                                                                                                                                                                            |
 | `summary.categories.survived`  | integer | Mutants whose covering tests still passed (a test gap candidate).                                                                                                                                                                                                                                                                               |
-| `summary.categories.timeout`   | integer | Mutants that exceeded the per-mutant deadline (counted as kills in the score).                                                                                                                                                                                                                                                                  |
+| `summary.categories.timeout`   | integer | Mutants that exceeded the per-mutant deadline (counted as kills in the score by default; excluded from the score under `timeout_policy: :separate`).                                                                                                                                                                                            |
 | `summary.categories.stillborn` | integer | Mutants whose code no longer parses. Never run; excluded from the score.                                                                                                                                                                                                                                                                        |
 | `summary.categories.error`     | integer | Mutants that hit a runner-side error. Excluded from the score.                                                                                                                                                                                                                                                                                  |
 | `mutations[].id`               | integer | Stable id of the mutation within this run.                                                                                                                                                                                                                                                                                                      |
@@ -144,7 +144,7 @@ the exit code keeps its meaning (`0` passed, `1` failed).
 | `summary.files`        | integer | Files that entered the run: processed plus skipped. Files a `--since` filter left out as unchanged are not counted; they are reported on stderr.                                                                                             |
 | `summary.processed`    | integer | Files that were actually mutation-tested.                                                                                                                                                                                                    |
 | `summary.skipped`      | array   | One entry per skipped file: `file` (the path as given) and `reason`, one of `file not found`, `not a Ruby source file`, `a test file, not a mutable source`, `no matching spec file`.                                                        |
-| `summary.score`        | number  | Aggregate mutation score over every mutant of every processed file, with the per-file formula: `(killed + timeout) / (killed + timeout + survived) * 100`, rounded to 2 decimals; `stillborn` and `error` are excluded from the denominator. |
+| `summary.score`        | number  | Aggregate mutation score over every mutant of every processed file, with the per-file formula: `(killed + timeout) / (killed + timeout + survived) * 100` (or `killed / (killed + survived) * 100` under `timeout_policy: :separate`), rounded to 2 decimals; `stillborn` and `error` are excluded from the denominator. |
 | `summary.passed`       | boolean | `true` exactly when the process exits `0`: the run matched/processed files and every processed file met the threshold.                                                                                                                       |
 | `summary.interrupted`  | boolean | `true` when `--fail-fast` stopped the batch at a surviving mutant, so remaining files were not run and the envelope is partial.                                                                                                              |
 | `survivors[].file`     | string  | Absolute path of the mutated source file, the same convention as `files[].metadata.source_file`, so a survivor joins its full per-file report by an exact string match on this value.                                                        |

data/exe/mutation_test

@@ -68,6 +68,14 @@ OptionParser.new do |opts|
     options[:fail_fast] = true
   end
 
+  opts.on('--timeout-factor N', Float, "Per-mutant timeout budget as N times the measured baseline test run, never below #{MutationTester::Configuration::CALIBRATED_TIMEOUT_FLOOR}s (default: #{MutationTester::Configuration::DEFAULT_TIMEOUT_FACTOR}; ignored when config.timeout is set explicitly, which keeps a fixed budget)") do |n|
+    options[:timeout_factor] = n
+  end
+
+  opts.on('--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') do |mode|
+    options[:timeout_policy] = mode
+  end
+
   opts.on('--strict-equality', 'Enable strict equality probes (== to eql? and equal?); default off, expect noise on code that does not distinguish numeric types or object identity') do
     options[:strict_equality] = true
   end
@@ -151,6 +159,8 @@ apply_configuration = lambda do
     config.reporters = selected_reporters if selected_reporters
     config.output_dir = options[:output_dir] if options[:output_dir]
     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.fail_fast = options.fetch(:fail_fast, false)
     config.mutation_types[:strict_equality] = true if options[:strict_equality]
@@ -342,4 +352,5 @@ else
   success = guard_interrupt.call { core.run }
 end
 
-exit(success ? 0 : 1)
+exit 0 if success
+exit(core.infrastructure_failure? ? 3 : 1)

data/lib/mutation_tester/batch_runner.rb

@@ -20,10 +20,14 @@ module MutationTester
 
     SKIP_ORDER = %i[missing not_ruby test_file no_spec].freeze
 
-    ProcessedEntry = Struct.new(:source_file, :spec_file, :score, :passed, :output_dir, :results, :interrupted, keyword_init: true) do
+    ProcessedEntry = Struct.new(:source_file, :spec_file, :score, :passed, :output_dir, :results, :interrupted, :degraded, keyword_init: true) do
       def passed?
         passed
       end
+
+      def degraded?
+        !!degraded
+      end
     end
 
     SkippedEntry = Struct.new(:source_file, :expected_spec, :reason, keyword_init: true)
@@ -192,7 +196,8 @@ module MutationTester
         passed: passed,
         output_dir: file_config.output_dir,
         results: core.results,
-        interrupted: core.interrupted?
+        interrupted: core.interrupted?,
+        degraded: core.infrastructure_failure?
       )
       [entry, core.interrupted?]
     end
@@ -247,12 +252,19 @@ module MutationTester
       end
 
       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
       elsif result.success?
         puts Rainbow('✓ All processed files met the mutation score threshold').green
+      elsif degraded.size == failed.size
+        puts Rainbow('❌ The failing files produced no scored mutants; this indicates an infrastructure or runner problem, not a test-quality gap').red
       else
         puts Rainbow('❌ One or more files did not meet the mutation score threshold').red
+        unless degraded.empty?
+          puts Rainbow("⚠️ #{degraded.size} of the failing files produced no scored mutants (infrastructure or runner problem); see the per-file output above").yellow
+        end
       end
 
       print_survivors(result.survivors)

data/lib/mutation_tester/configuration.rb

@@ -3,7 +3,11 @@ require 'etc'
 module MutationTester
   class Configuration
     RUNNER_MODES = %i[auto fork spawn in_memory].freeze
+    TIMEOUT_POLICIES = %i[killed separate].freeze
     AUTO_PARALLEL_CAP = 8
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_TIMEOUT_FACTOR = 5
+    CALIBRATED_TIMEOUT_FLOOR = 5
 
     def self.auto_parallel_processes
       [[Etc.nprocessors, AUTO_PARALLEL_CAP].min, 1].max
@@ -14,9 +18,9 @@ module MutationTester
       number <= 0 ? '' : (number + 1).to_s
     end
 
-    attr_reader :parallel_processes, :runner, :worker_env_var
+    attr_reader :parallel_processes, :runner, :worker_env_var, :timeout, :timeout_factor, :timeout_policy
 
-    attr_accessor :timeout,
+    attr_accessor :baseline_duration,
       :baseline_timeout,
       :mutation_types,
       :reporters,
@@ -33,7 +37,9 @@ 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']
-      @timeout = 30
+      @timeout = DEFAULT_TIMEOUT
+      @timeout_factor = DEFAULT_TIMEOUT_FACTOR
+      @timeout_policy = :killed
       @baseline_timeout = 300
       @mutation_types = {
         arithmetic: true,
@@ -73,6 +79,39 @@ module MutationTester
       @reporters = source.reporters.dup
     end
 
+    def timeout=(value)
+      @timeout_explicit = true
+      @timeout = value
+    end
+
+    def timeout_explicitly_set?
+      !!@timeout_explicit
+    end
+
+    def timeout_factor=(value)
+      factor = coerce_numeric(value)
+      unless factor.positive?
+        warn "[MutationTester] timeout_factor must be a number greater than 0; got #{value.inspect}, falling back to #{DEFAULT_TIMEOUT_FACTOR}."
+        factor = DEFAULT_TIMEOUT_FACTOR
+      end
+      @timeout_factor = factor
+    end
+
+    def timeout_policy=(value)
+      policy = value.to_s.strip.downcase.to_sym
+      unless TIMEOUT_POLICIES.include?(policy)
+        warn "[MutationTester] timeout_policy must be one of #{TIMEOUT_POLICIES.join(", ")}; got #{value.inspect}, falling back to killed."
+        policy = :killed
+      end
+      @timeout_policy = policy
+    end
+
+    def effective_timeout
+      return @timeout if timeout_explicitly_set? || @baseline_duration.nil?
+
+      [CALIBRATED_TIMEOUT_FLOOR, @timeout_factor * @baseline_duration].max
+    end
+
     def parallel_processes=(value)
       count = value.to_i
       if count < 1
@@ -101,5 +140,13 @@ module MutationTester
 
       { @worker_env_var => self.class.worker_env_value(index) }
     end
+
+    private
+
+    def coerce_numeric(value)
+      Float(value)
+    rescue ArgumentError, TypeError
+      0
+    end
   end
 end

data/lib/mutation_tester/core.rb

@@ -11,6 +11,7 @@ module MutationTester
       @mutations = []
       @results = []
       @parse_failed = false
+      @shadow_aborted = false
       MutationRunner.recover_in_place_backup(@source_file)
       @original_content = File.read(@source_file)
     end
@@ -27,11 +28,15 @@ module MutationTester
         return true
       end
 
-      return false unless shadow_environment_reliable?
+      unless shadow_environment_reliable?
+        @shadow_aborted = true
+        return false
+      end
 
       run_mutations
       generate_reports
       return report_interruption if interrupted?
+      return report_infrastructure_failure if infrastructure_failure?
 
       check_threshold
     ensure
@@ -46,7 +51,11 @@ module MutationTester
     end
 
     def mutation_score
-      Reporters::BaseReporter.score(@results)
+      Reporters::BaseReporter.score(@results, policy: @config.timeout_policy)
+    end
+
+    def infrastructure_failure?
+      @shadow_aborted || (!@results.empty? && scored_count.zero?)
     end
 
     def threshold_met?
@@ -69,7 +78,9 @@ module MutationTester
     def run_original_tests
       puts Rainbow("\n🧪 Running original tests...").yellow
       command = test_command
+      baseline_started = monotonic_time
       result = command.run(timeout: @config.baseline_timeout, capture: true)
+      baseline_elapsed = monotonic_time - baseline_started
 
       if result.timed_out?
         puts Rainbow("❌ Original tests exceeded the baseline deadline of #{@config.baseline_timeout}s and were terminated.").red
@@ -85,9 +96,14 @@ module MutationTester
         return false
       end
       puts Rainbow('✓ Original tests passed').green
+      @config.baseline_duration = baseline_elapsed
       true
     end
 
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     def replay_baseline_output(output)
       return if output.nil? || output.strip.empty?
 
@@ -178,6 +194,20 @@ module MutationTester
       false
     end
 
+    def scored_count
+      @results.count { |r| %i[killed timeout survived].include?(Reporters::BaseReporter.status_for(r)) }
+    end
+
+    def status_count(status)
+      @results.count { |r| Reporters::BaseReporter.status_for(r) == status }
+    end
+
+    def report_infrastructure_failure
+      puts Rainbow("\n❌ Run failed: none of the #{@results.size} mutants could be scored (#{status_count(:error)} error, #{status_count(:stillborn)} stillborn).").red
+      puts Rainbow('   This indicates an infrastructure or runner problem (test environment, workspace, or test command), not a test-quality gap.').red
+      false
+    end
+
     def check_threshold
       score = mutation_score
 

data/lib/mutation_tester/mutation_runner.rb

@@ -285,7 +285,7 @@ module MutationTester
     end
 
     def run_specs_in_shadow(spec_file, working_dir, example_filters: [])
-      test_command(spec_file, example_filters: example_filters).run(timeout: @config.timeout, chdir: working_dir)
+      test_command(spec_file, example_filters: example_filters).run(timeout: @config.effective_timeout, chdir: working_dir)
     end
 
     def discoverable_project_root
@@ -325,7 +325,7 @@ module MutationTester
     end
 
     def run_specs_in_place(spec_file, example_filters: [])
-      test_command(spec_file, example_filters: example_filters).run(timeout: @config.timeout)
+      test_command(spec_file, example_filters: example_filters).run(timeout: @config.effective_timeout)
     end
 
     def run_mutation_in_memory(mutation, result, project_root = nil)
@@ -335,7 +335,7 @@ module MutationTester
       outcome = runner.execute_in_memory(
         source: mutation[:code],
         path: @source_file,
-        timeout: @config.timeout,
+        timeout: @config.effective_timeout,
         chdir: Dir.pwd
       )
 
@@ -419,7 +419,7 @@ module MutationTester
       outcome = runner.execute_in_memory(
         source: @original_content,
         path: @source_file,
-        timeout: @config.timeout,
+        timeout: @config.effective_timeout,
         chdir: Dir.pwd
       )
       return nil if outcome.status == 'pass'

data/lib/mutation_tester/reporters/base_reporter.rb

@@ -3,12 +3,14 @@ module MutationTester
     class BaseReporter
       attr_reader :results, :source_file, :spec_file, :config
 
-      def self.score(results)
-        effective_killed = results.count { |r| %i[killed timeout].include?(status_for(r)) }
-        scored = results.count { |r| %i[killed timeout survived].include?(status_for(r)) }
+      def self.score(results, policy: :killed)
+        killing_statuses = policy == :separate ? %i[killed] : %i[killed timeout]
+        scoring_statuses = killing_statuses + %i[survived]
+        kills = results.count { |r| killing_statuses.include?(status_for(r)) }
+        scored = results.count { |r| scoring_statuses.include?(status_for(r)) }
         return 0.0 if scored.zero?
 
-        (effective_killed.to_f / scored * 100).round(2)
+        (kills.to_f / scored * 100).round(2)
       end
 
       def self.status_for(result)
@@ -62,6 +64,8 @@ module MutationTester
       end
 
       def effective_killed_count
+        return killed_count if @config.timeout_policy == :separate
+
         killed_count + timeout_count
       end
 
@@ -70,7 +74,7 @@ module MutationTester
       end
 
       def mutation_score
-        self.class.score(@results)
+        self.class.score(@results, policy: @config.timeout_policy)
       end
 
       def quality_rating

data/lib/mutation_tester/reporters/batch_json_reporter.rb

@@ -53,7 +53,7 @@ module MutationTester
       end
 
       def aggregate_score
-        BaseReporter.score(@result.processed.flat_map { |entry| entry.results || [] })
+        BaseReporter.score(@result.processed.flat_map { |entry| entry.results || [] }, policy: @config.timeout_policy)
       end
 
       def file_reports

data/lib/mutation_tester/version.rb

@@ -1,3 +1,3 @@
 module MutationTester
-  VERSION = '1.2.0'.freeze
+  VERSION = '1.3.0'.freeze
 end

data/lib/tasks/mutation_tester.rake

@@ -45,7 +45,7 @@ namespace :mutation do
     end
 
     unless all_passed
-      puts Rainbow("\n❌ One or more files did not meet the mutation score threshold").red
+      puts Rainbow("\n❌ One or more files failed mutation testing (see the per-file output above)").red
       abort
     end
   end

data/readme.md

@@ -206,6 +206,8 @@ mutation_test [OPTIONS] --glob 'lib/**/*.rb'
 | `--spec-glob TEMPLATE` | Spec-mapping template with a `{name}` placeholder (default: `spec/{name}_spec.rb`). Requires a positional `FILE` list, `--staged`, or `--glob`. |
 | `--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). |
 | `--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. |
@@ -223,6 +225,22 @@ bundle exec mutation_test --reporters json,html --output-dir build/mutation \
   app/models/user.rb spec/models/user_spec.rb
 ```
 
+### Exit codes (single-file mode)
+
+- `0` - the run passed (score met the threshold, or `fail_on_threshold` is disabled).
+- `1` - the mutation score is below the threshold, or the input is unusable (missing
+  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.
+  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.
+
+Batch modes (`FILE...` lists, `--staged`, `--glob`) keep the exit codes documented in
+their sections below (`0`/`1`/`2`); a degraded file is named explicitly in the batch
+summary instead of being blamed on the threshold.
+
 ### Running with rake
 
 You can also run mutation tests through rake tasks.
@@ -403,8 +421,24 @@ MutationTester.configure do |config|
   # config.parallel_processes = 1
   config.parallel_processes = 4
 
-  # Timeout for each test run (seconds)
-  config.timeout = 30
+  # Per-mutant timeout (seconds). Calibrated automatically by default:
+  # max(5, timeout_factor * measured baseline duration), so a loaded machine
+  # cannot inflate the score by turning healthy-but-slow runs into timeout
+  # kills; on code paths without a measured baseline the fixed default of 30
+  # applies. Setting config.timeout explicitly (a number, or nil for no
+  # deadline at all) disables calibration and keeps that fixed budget:
+  # config.timeout = 30
+
+  # Multiplier for the baseline-calibrated per-mutant timeout (> 0; an
+  # invalid value falls back to the default with a warning):
+  config.timeout_factor = 5
+
+  # Scoring policy for timed-out mutants. :killed (default) counts a timeout
+  # as a kill: (killed + timeout) / (killed + timeout + survived). :separate
+  # keeps timeouts out of the score entirely, killed / (killed + survived),
+  # and reports them only as their own category, so timeouts under load can
+  # never raise the score:
+  config.timeout_policy = :killed
 
   # Mutant execution runner: :auto (default), :fork, :spawn or :in_memory.
   # :auto picks the fastest safe path and announces any fallback on stderr;
@@ -725,7 +759,9 @@ to get a single, clean JSON document on **stdout** and nothing else: the banner,
 progress spinner, colours and the "report saved" notice all go to **stderr**, so
 the stream is safe to pipe straight into `jq` or a parser. The process still
 exits `0` when the mutation score meets the configured threshold and `1` when it
-does not, so the exit code remains a pass/fail signal.
+does not (a degraded single-file run exits `3`, see
+[Exit codes](#exit-codes-single-file-mode)), so the exit code remains a
+pass/fail signal.
 
 ```bash
 bundle exec mutation_test --json examples/calculator.rb examples/calculator_spec.rb | jq .

metadata

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