saboteur 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a4dcacd09e6b4ca97537446ae6cbc73b13fb2c6dabcc26f22ea26784e869151
-  data.tar.gz: 83c7e9f8121a1193c518cbfcba50b825d13b0e08ccd90f3085f88d932855fd03
+  metadata.gz: 30c6af46486b9fc1138b568c45934cc895f786a79ea5215607f493a5a7d5af68
+  data.tar.gz: a7a8038afc6166347fac807028cf7f45acecbb7e4c27e32f8917c4167b805bac
 SHA512:
-  metadata.gz: a9baa6f9af8e3f2ecd0e2fd661104550e23b7b5e2f368d4cd996b5648994537888d88ba1130477525b93d4df13a756585eed3f9ffb27f309057e7452d069a982
-  data.tar.gz: 782690794b535288178addb949cf7b0e530e19d4e55acd20c837903f4ddb8818581b42cacfc5af1d1ccb7ba4a6dd9e0cbd84a5059f143407f99195e2ed14a046
+  metadata.gz: 66817191adf235c1fb6adb41d3218704557d2d3305fab299f17cc38bb3b392733f0a52615d84aadb5e4fd940046db9336de9efa178b205d58cc8e1c61374c25a
+  data.tar.gz: 132649f6b81d5ee312341a032df36b890af481704deee6c4b5cd4a013736c857ddc7887b27318409a1db05ea2621cbc8b2791ff4d0c40d3509810a6e13f7a405

data/CHANGELOG.md

@@ -6,6 +6,106 @@ All notable changes are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-20
+
+### Added
+
+- Five new mutation operators: `and_assign` drops the guard on `&&=`
+  (#873), `jump_value` replaces unchecked early-exit values (#875),
+  `rescue_removal` removes exception handlers no test reaches (#877),
+  `when_removal` removes case branches no test takes (#887), and
+  `unary_removal` removes signs and complements no test sees (#890).
+- `--resume DIR` keeps verdicts in a directory across runs, with a
+  manifest check on the directory (#840, #831), and `--incremental`
+  checkpoints verdicts while the run is going (#820, documented in #822).
+- Partial and parallel coverage: `c.coverage_parts` deals the suite into
+  parts built in parallel (#741: #769, #772, #774, #776), keeps each
+  finished part when a build stops (#860), and reuses the saved parts
+  when a parallel build is rerun (#862). The partial map merge and an
+  opt-in shadow run compare a partial rebuild against the full map
+  (#829, #832), and `partial_coverage = "use"` skips the full build when
+  only spec files or covered sources changed, rerunning just the stale
+  spec files and merging them into the earlier map (#918).
+- TracePoint coverage recorders: `MethodCalls` records Ruby method
+  entries (#794, #795), a line-hits recorder reads branches once per
+  spec file (#894, #897), and `c.coverage_recorder = "trace"` picks the
+  TracePoint build (#898).
+- Constant-reference spec selection: a spec that requires a spec-less
+  file counts as its reference reader (#876, #879), a stop that keeps a
+  hub file's cap says how many specs reference it (#881), and the agent
+  JSON provenance reports and flags findings whose specs were chosen by
+  reference (#884, #885).
+- The GitHub Action posts surviving mutants as pull-request review
+  comments on the lines the PR head has (#788, #789, #793), matches the
+  review comment bot login without regard to case (#791), documents the
+  review comment inputs (#790), and exposes max-timeouts and max-errors
+  as inputs (#246, #767).
+- Integration targets: a target can name its own gemfile (#900), carry
+  patch, env and recorder options (#899), and run setup commands and add
+  gems (#910). doorkeeper, paper_trail, cancancan and lobsters join the
+  recorder-parity targets (#901, #908, #912).
+- The JSON report adds per-gate score breakdowns (#473, #766) and a
+  `saboteur.complete` field (#784).
+- A real-bug corpus runner with a manual CI workflow, and the s-z and
+  i-r corpus slices (#652: #915, #916).
+- A coverage cache miss says why it missed and what changed (#812), and
+  spec shards balance by recorded per-example run time (#747, #748).
+- Warnings across the survivor, sandbox grant, shadow, worker, budget
+  and `--since`/`--subject` messages lead with the outcome and name the
+  remedy, per the documented message style (#332 series, #796).
+
+### Fixed
+
+- `--since` ignores a line whose only change is its trailing comment
+  (#892, fixed in #921).
+- `script/rspec-shard` no longer dies of SIGPIPE on a long spec list
+  (#878).
+- `or_assign` no longer mutates constant targets inside a def (#874).
+- A test that suspends Coverage no longer breaks the map build; Coverage
+  resumes after it (#869).
+- Worker pool cleanup no longer leaks live entries or masks errors, and
+  keeps unregistering workers when the orphan sweep goes blind (#762:
+  #770, #771); containment and the live registry survive a blind process
+  table (#762: #764).
+- A timed-out Gemfile resolver no longer blocks on escaped-grandchild
+  pipes, and the resolver-pipe specs reap escaped grandchildren (#734,
+  #750). A `path:` source equal to the project root rebases onto the
+  copy root (#729), external test-command `path:` sources are refused or
+  rebased (#644, #721), and the BUNDLE_GEMFILE pin gaps close with
+  lockfile-mismatch refusals (#732).
+- A cached coverage map is read as untrusted input: its field types,
+  durations and loaded files are checked, non-finite values are
+  rejected, and the inputs snapshot binds to the map and the runtime
+  (#853, #854, #859, #825). Stored verdicts are type-checked before
+  reuse (#842).
+- Cache files and the coverage map write through an exclusive private
+  temp file (#846, #850).
+- Registry DSL blocks in Ohai/Puppet style promote their defs to
+  subjects (#700, #727).
+- The baseline checks the unchanged suite in the coverage build's parts
+  instead of a separate pass (#930).
+
+### Security
+
+- CI workflow-command injection is closed at every sink: the unmatched
+  whole_file pattern (#856), repo-controlled file names in the
+  constant-safety warnings (#857), name_list items (#858),
+  repo-controlled names in the syntax, custom map and sandbox grant
+  warnings (#870), every Diagnostics warning line (#871), the terminal
+  report at one choke point (#872), the stop and gate messages (#919),
+  and the CLI error sinks (#917, fixed in #920).
+- The review comment planner is hardened against untrusted input (#783),
+  and the Action fetches the pull request base with the token in a step
+  of its own, with the token-handling scripts pinned (#797, #798).
+
+### Documentation
+
+- The getting-started guide shows a gem-installed run (#815), the
+  config-key table documents every key and the Rails config points at it
+  (#809), the Action guide documents a per-path score gate (#817),
+  `--incremental` verdict saving is documented (#822), and the warning
+  and note style convention is written down (#796).
+
 ## [0.8.1] - 2026-10-18
 
 ### Added

data/README.md

@@ -127,6 +127,16 @@ the macro itself `ran at load` instead of letting its mutants survive.
   before a kill is rejected, so its mutants are still scored.
 - **Reports for people and tools.** Terminal, HTML, a Stryker-compatible
   JSON report, and a stable agent JSON API with a deprecation policy.
+  The GitHub Action posts surviving mutants as review comments on the
+  diff lines of the pull request.
+- **Resumable runs.** `--resume DIR` keeps verdicts across runs and
+  `--incremental` checkpoints them while the run is going, so a stopped
+  run picks up where it left off.
+- **Faster coverage builds.** `c.coverage_parts` builds the coverage map
+  in parallel parts, `partial_coverage = "use"` rebuilds only the stale
+  spec files and merges them into the saved map, and
+  `c.coverage_recorder = "trace"` builds the map with a TracePoint
+  recorder.
 - **A plan before the run.** `saboteur run --dry-run --format json` prints
   the versioned [mutant inventory](docs/dry-run-json.md) - every planned
   mutant with its stable digest and edits - without booting the suite.

data/exe/saboteur

@@ -11,7 +11,7 @@
 # (one line, invalid bytes scrubbed, bounded length) still exits 3.
 begin
   require "coverage"
-  Coverage.setup(lines: true, methods: true, branches: true) if Coverage.state == :idle
+  Coverage.setup(lines: true, branches: true) if Coverage.state == :idle
 
   require "saboteur/crash_report"
 rescue LoadError, StandardError => e
@@ -27,7 +27,11 @@ end
 # ones. The engine suspends counting right after boot and reads the
 # counters as the map's load lines (a forked child would not inherit them).
 begin
-  Coverage.resume if ARGV.first == "run" && Coverage.state == :suspended
+  if ARGV.first == "run" && Coverage.state == :suspended
+    require "saboteur/method_calls"
+    Saboteur::MethodCalls.boot
+    Coverage.resume
+  end
 
   require "saboteur/cli"
 

data/lib/saboteur/attribute_finder.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "prism"
+require_relative "deep_source"
 require_relative "subject"
 
 module Saboteur
@@ -24,6 +25,8 @@ module Saboteur
       result = Prism.parse(File.binread(file), filepath: file)
       return [] if result.failure?
 
+      DeepSource.check!(result.value, file)
+
       found = []
       walk(result.value, [], found)
       found

data/lib/saboteur/baseline/run_evidence.rb

@@ -3,6 +3,7 @@
 
 require_relative "identity"
 require_relative "completeness"
+require_relative "../config"
 require_relative "../engine/run_fingerprint"
 
 module Saboteur
@@ -11,7 +12,7 @@ module Saboteur
     # This does not attest external database, network or environment state.
     class RunEvidence
       SAFE_DROPS = %w[unchanged duplicate].freeze
-      OUTPUT_SETTINGS = %w[cache_dir json_report html_report score_history].freeze
+      OUTPUT_SETTINGS = Config::OUTPUT_KEYS
 
       def initialize(config:, extra_files: [])
         @config = config

data/lib/saboteur/cli/agent_provenance.rb

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # Agent-mode provenance: the record a JSON report carries so its rerun
+    # and replay commands reproduce the run exactly (#334). Extracted from
+    # CLI; the builder and its settings helpers are private to the mixin.
+    module AgentProvenance
+      private
+
+      def agent_provenance(report, tree, engine)
+        Reporter::Agent::Provenance.new(
+          ref: config["since"], seed: report.seed, head: tree.head, working_tree: tree.label,
+          changed_files: tree.changed_files, mode: agent_mode, json_report: config.path("json_report"),
+          subjects: Array(config["subjects"]), tests: Array(engine.guessed_tests || config["tests"]),
+          sources: @sources || [],
+          config_path: options[:config], digest: options[:id], cache: config["cache"],
+          incremental: config["incremental"], settings: agent_settings, typed_settings: typed_settings,
+          referenced: report.referenced
+        )
+      end
+
+      # The settings keys typed on the command line: a typed empty operator
+      # list may clear a config value, so the generated commands keep it.
+      def typed_settings = options.keys & Reporter::Agent::Commands::SETTING_FLAGS.keys
+
+      # A whole-suite run records its scope as --all, so the generated rerun
+      # and replay commands do not default back to inference (which can exit
+      # 2 in a project with a spec-less source file).
+      def agent_settings
+        settings = options.slice(*Reporter::Agent::Commands::SETTING_FLAGS.keys)
+                          .merge(operators: config["operators"], exclude_operators: config["exclude_operators"])
+        # The effective mode: named tests win over a configured whole-suite
+        # selection by precedence, so all is recorded only when no tests
+        # resolved - otherwise the follow-up commands would carry both --all
+        # and --test, which the CLI rejects.
+        settings[:all] = true if (config["all"] || config["test_selection"] == "all") && config["tests"].empty?
+        # CLI-only switches that change candidate availability or boot, so a
+        # printed rerun/replay must keep them (config-file settings like
+        # arid/hazard patterns, whole-file, require, rspec_args and rails ride
+        # along through --config or the default config path).
+        settings[:allow_hazardous] = true if options[:allow_hazardous]
+        settings[:allow_focus] = true if options[:allow_focus]
+        # An explicit false (--no-max-duration-ok over a config true) is a
+        # setting too: dropping it would silently re-enable the config value.
+        settings[:max_duration_ok] = options[:max_duration_ok] unless options[:max_duration_ok].nil?
+        settings
+      end
+
+      def agent_mode
+        return "replay" if options[:id]
+        return "diff" if config["since"]
+
+        @sources&.any? ? "files" : "full"
+      end
+    end
+  end
+end

data/lib/saboteur/cli/dirty_tree_notice.rb

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The uncommitted-work warning printed before a run (#334). Extracted
+    # from CLI.
+    module DirtyTreeNotice
+      private
+
+      # Mutants run your code, and a mutant of code that writes or deletes files
+      # can change the tree. Say so up front when uncommitted work is at stake.
+      # The scope the warning names is the configured one: positional source
+      # operands narrow the run after the warning, so the include/exclude they
+      # imply stay out of its config (#309, #503 review).
+      def warn_dirty_tree
+        warning = if @sources
+                    Config.load(path: options[:config],
+                                overrides: overrides.except(:include,
+                                                            :exclude))
+                  else
+                    config
+                  end
+        DirtyTreeWarning.for(warning, config_path: options[:config])&.then { |text| @err.puts(text) }
+      end
+    end
+  end
+end

data/lib/saboteur/cli/doctor_command.rb

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # `saboteur doctor`: environment report and optional unchanged suite
+    # passes, never mutations (#334). Extracted from CLI by command.
+    module DoctorCommand
+      def doctor_parser
+        OptionParser.new do |opts|
+          opts.banner = "Usage: saboteur doctor [--config PATH] [--seed N] [--suite] [--test PATH]"
+          opts.on("--config PATH", "Config file (default config/saboteur.rb)") { |value| set(:config, value) }
+          opts.on("--seed N", Integer, "Seed for the two baseline runs (default 1)") { |value| set(:seed, value) }
+          opts.on("--suite", "Also run the unchanged suite twice (slow on a large suite)") { set(:suite, true) }
+          opts.on("--test PATH", "Spec file or directory for the suite runs; repeatable. Implies --suite") do |value|
+            (options[:tests] ||= []) << value
+          end
+        end
+      end
+
+      private
+
+      def doctor_command = help_requested? ? show_help("doctor") : doctor
+
+      def doctor
+        doctor_parser.parse!(@argv)
+        raise UsageError, "unexpected arguments: #{@argv.join(' ')}" if @argv.any?
+
+        options[:tests]&.each { |test| require_existing_test(test) }
+        Doctor.new(config, out: @out, suite: options[:suite] || options.key?(:tests)).call
+        EXIT_OK
+      rescue ConfigError => e
+        @err.puts("saboteur: #{Text.display_safe_lines(e.message)}")
+        EXIT_USAGE
+      rescue Error => e
+        @err.puts("saboteur: #{Text.display_safe_lines(e.message)}")
+        EXIT_TOOL
+      end
+    end
+  end
+end

data/lib/saboteur/cli/error_cause.rb

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The detail line a "mostly errored" or "incomplete" exit message adds:
+    # the most common first line of the errored results' reasons, so a run
+    # that exits on its error count still names why (a worker killed by a
+    # signal, say) instead of leaving the cause in the stdout error list.
+    module ErrorCause
+      def self.incomplete(problem)
+        "saboteur: #{problem.size} mutant(s) errored or hit a resource limit, so the score is " \
+          "incomplete#{line(problem)}"
+      end
+
+      LIMIT = 200
+
+      # "" when no result carries a reason.
+      def self.line(errored)
+        reasons = errored.filter_map { |result| first_line(result.reason) }.reject(&:empty?)
+        return "" if reasons.empty?
+
+        # Worker numbers and pids differ between otherwise identical deaths.
+        group = reasons.group_by { |reason| reason.delete("0-9") }.values.max_by(&:size)
+        "\n  most common cause (#{group.size} of #{errored.size}): #{group.first}"
+      end
+
+      # A reason can carry invalid bytes, terminal escapes or a huge line,
+      # and this runs on the way to the exit code: scrub, escape controls and
+      # cap before anything groups or prints it, and never raise.
+      def self.first_line(reason)
+        text = Text.utf8(reason.to_s).lines.map(&:strip).find { |line| !line.empty? }.to_s
+        text = Text.display_safe(text.gsub(/\e\[[0-9;]*[A-Za-z]/, ""))
+        text.length > LIMIT ? "#{text[0, LIMIT]}..." : text
+      rescue StandardError
+        reason.to_s.dump[0, LIMIT]
+      end
+    end
+  end
+end

data/lib/saboteur/cli/execution_options.rb

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # Execution, cache and hazard flags for `saboteur run` (#334).
+    module ExecutionOptions
+      private
+
+      def define_execution_options(opts)
+        opts.on("--timeout-factor N", Float, "Multiple of baseline runtime (default 3)") { |v| set(:timeout_factor, v) }
+        opts.on("--jobs N", Integer, "Concurrent workers (default 1)") { |v| set(:jobs, v) }
+        add_run_budget_options(opts)
+        opts.on("--config PATH", "Config file (default config/saboteur.rb)") { |v| set(:config, v) }
+        opts.on("--integration NAME", "Test adapter (rspec)") { |v| set(:integration, v) }
+        opts.on("--reeval STRATEGY", Execution::Reevaluator::STRATEGIES, "class_eval or nesting") { |v| set(:reeval, v) }
+        opts.on("--no-cache", "Rebuild the coverage map") { set(:cache, false) }
+        opts.on("--allow-hazardous",
+                "Also run mutants inside destructive calls (rm_rf, system, ...)") { set(:allow_hazardous, true) }
+        opts.on("--fail-fast",
+                "Stop after the first subject with a survivor (needs --jobs 1)") { set(:fail_fast, true) }
+        add_reuse_options(opts)
+        opts.on("--allow-focus", "Run even when a focus filter (fit, fdescribe, :focus) narrows the suite") do
+          set(:allow_focus, true)
+        end
+        opts.on("--all", "Run the whole configured test suite instead of inferring the specs named after the " \
+                         "mutated files") { set(:all, true) }
+        opts.on("--test-command CMD", "Run CMD per mutant in the project root; exit 0 means the mutant survived. " \
+                                      "For apps that cannot load in this Ruby; much slower, serial, no coverage") do |v|
+          set(:test_command, v)
+        end
+        opts.on("--[no-]guess-tests", "Deprecated alias: inferred specs are already the default; " \
+                                      "--no-guess-tests warns and is ignored - use --all for the whole suite") do |v|
+          set(:guess_tests, v)
+        end
+      end
+
+      def add_reuse_options(opts)
+        opts.on("--incremental", "Reuse earlier verdicts whose inputs did not change") { set(:incremental, true) }
+        opts.on("--resume DIR", "Keep verdicts in DIR and reuse them in a later run with the same inputs") do |v|
+          set(:resume, v)
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/cli/exit_status.rb

@@ -14,11 +14,9 @@ module Saboteur
       end
 
       # The crash log lives with the other run state. A broken config (or a
-      # nil cache_dir) must not swallow the crash report itself, so fall
-      # back to no log.
+      # nil cache_dir) must not swallow the crash report itself: no log.
       def crash_log_path
-        dir = config.path("cache_dir")
-        dir && File.join(dir, CrashReport::LOG_NAME)
+        config.path("cache_dir")&.then { |dir| File.join(dir, CrashReport::LOG_NAME) }
       rescue StandardError
         nil
       end
@@ -34,7 +32,8 @@ module Saboteur
 
         return EXIT_TOOL if incomplete_under_threshold?(report)
 
-        failed_quality_gate?(report) || gates.failed?(report, @err) ? EXIT_SURVIVORS : EXIT_OK
+        quality_failed = failed_quality_gate?(report)
+        gates.failed?(report, @err, record_cause: !quality_failed) || quality_failed ? EXIT_SURVIVORS : EXIT_OK
       end
 
       # A spent --max-duration budget exits 4 on its own, before the gates:
@@ -62,7 +61,7 @@ module Saboteur
       def unverifiable_scope?(report)
         if unverifiable_review?(report)
           report.skipped_subjects.each do |subject, reason|
-            @err.puts("saboteur: #{subject.id} was skipped (#{reason}), so the change under test was not verified")
+            @err.puts(subject.skipped_gate_sentence(reason, report.root))
           end
           return true
         end
@@ -86,10 +85,9 @@ module Saboteur
       def mostly_errored?(report)
         return false unless report.majority_errored?
 
-        executed = report.executed
-        errors = executed.count { |result| result.status == :error }
-        @err.puts("saboteur: #{errors} of #{executed.size} mutants errored, so the run tested almost nothing; " \
-                  "fix the errors and run again")
+        errored = report.executed.select { |result| result.status == :error }
+        @err.puts("saboteur: fix the errors and run again\n  #{errored.size} of #{report.executed.size} " \
+                  "mutants errored, so the run tested almost nothing#{ErrorCause.line(errored)}")
         true
       end
 
@@ -159,10 +157,10 @@ module Saboteur
       def incomplete_under_threshold?(report)
         return false if config["threshold"].nil?
 
-        count = report.counts.values_at(*(gates.judges_errors? ? %i[resource_limit] : %i[error resource_limit])).sum
-        @err.puts("saboteur: #{count} mutant(s) errored or hit a resource limit, so the score is incomplete") if
-          count.positive?
-        count.positive?
+        statuses = gates.judges_errors? ? %i[resource_limit] : %i[error resource_limit]
+        problem = report.results.select { |result| statuses.include?(result.status) }
+        @err.puts(ErrorCause.incomplete(problem)) if problem.any?
+        problem.any?
       end
     end
   end

data/lib/saboteur/cli/explicit_file_options.rb

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # Explicit test selection and quality-gate flags (#334).
+    module ExplicitFileOptions
+      private
+
+      def define_explicit_file_options(opts)
+        opts.on("--test PATH", "Spec file or directory to run; repeatable. Replaces the configured spec paths") do |v|
+          (options[:tests] ||= []) << v
+        end
+        opts.on("--threshold PERCENT", Float, "Exit 1 when the score is below PERCENT (0-100)") do |v|
+          set(:threshold, v)
+        end
+        Gates.define_options(opts) { |key, value| set(key, value) }
+      end
+    end
+  end
+end

data/lib/saboteur/cli/explicit_sources.rb

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The source and test operands of `saboteur run`, checked against the
+    # file system before anything boots (#334). Extracted from CLI.
+    module ExplicitSources
+      private
+
+      # Positional arguments name the files (or directories) to mutate. They
+      # replace the configured include and exclude patterns. Each must exist,
+      # so a typo is an error and not a run over zero subjects.
+      def use_explicit_sources
+        Selection::SourceScope.verify_no_specs!(@argv)
+        options[:tests]&.each { |test| require_existing_test(test) }
+        # --test may stand alone: the configured include (or the --since
+        # diff) names the sources. The files must still exist.
+        return if @argv.empty?
+
+        @sources = @argv.dup
+        options[:include] = @argv.map { |source| source_pattern(source) }
+        options[:exclude] = []
+      end
+
+      def source_pattern(source)
+        return "#{glob_escape(source.chomp('/'))}/**/*.rb" if File.directory?(source)
+        raise UsageError, "source is not a Ruby file: #{source}" if File.file?(source) && !source.end_with?(".rb")
+        raise UsageError, "source file not found: #{source}" unless File.file?(source)
+
+        glob_escape(source)
+      end
+
+      # include is a list of glob patterns; a named file must match only itself.
+      def glob_escape(path)
+        path.gsub(/[\\*?\[\]{}]/) { |character| "\\#{character}" }
+      end
+
+      # A test may carry an example selector: spec/a_spec.rb:12 or spec/a_spec.rb[1:2].
+      def require_existing_test(test)
+        path = test.sub(/(:\d+|\[[\d:,]+\])+\z/, "")
+        raise UsageError, "test file not found: #{test}" unless File.exist?(path)
+      end
+    end
+  end
+end

data/lib/saboteur/cli/failure_output.rb

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # Where a failed command speaks: stderr for people, and in agent mode the
+    # same failure as JSON on stdout (#334). Extracted from CLI.
+    module FailureOutput
+      private
+
+      def usage_error(message = nil)
+        @err.puts(message) if message
+        @err.puts(USAGE)
+        agent_failure(message || USAGE, EXIT_USAGE)
+      end
+
+      def agent? = @format == "agent"
+
+      # In agent mode the failure is also on stdout, where the agent reads its answer.
+      def agent_failure(message, exit_code)
+        @out.print(Reporter::Agent.render(Reporter::Agent.failure(message, exit_code))) if agent?
+        exit_code
+      end
+
+      # Error messages interpolate repository-controlled names, so each line is
+      # made safe before it is printed (a newline then "::error::" in a file
+      # name must not become a workflow command in the CI log).
+      def report_failure(error, exit_code)
+        message = Text.display_safe_lines(error.message)
+        @err.puts("saboteur: #{message}")
+        agent_failure(message, exit_code)
+      end
+    end
+  end
+end

data/lib/saboteur/cli/help_command.rb

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # `saboteur help` and the `--help` of every command (#334). Extracted
+    # from CLI by command.
+    module HelpCommand
+      private
+
+      def help_requested? = @argv.intersect?(%w[--help -h])
+
+      def show_help(command_name)
+        help = Help.new(option_lines: option_lines)
+        text = command_name ? help.command(command_name) : help.overview
+        return @out.puts(text) || EXIT_OK if text
+
+        @err.puts("unknown command: #{command_name}. Commands: #{help.command_names.join(', ')}")
+        EXIT_USAGE
+      end
+    end
+  end
+end

data/lib/saboteur/cli/matrix_option.rb

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The --matrix flag for `saboteur run` (#334).
+    module MatrixOption
+      private
+
+      def define_matrix_option(opts)
+        opts.on("--matrix", "Run every covering test per mutant and list blind and redundant tests") do
+          set(:matrix, true)
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/cli/output_options.rb

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # Report destinations and text output flags for `saboteur run` (#334).
+    module OutputOptions
+      private
+
+      def define_output_options(opts)
+        opts.on("--score-history PATH", "Append score history JSONL (opt-in)") { |v| set(:score_history, v) }
+        opts.on("--json PATH", "Stryker JSON report path") { |v| set(:json_report, v) }
+        opts.on("--html PATH", "Self-contained HTML report path") { |v| set(:html_report, v) }
+        opts.on("--format FORMAT", %w[text agent json], "text, agent or json (--dry-run inventory)") { |v| @format = v }
+        opts.on("--agent", "Same as --format agent") { @format = "agent" }
+        opts.on("--verbose", "Text report: also print score split, timings and kill causes;",
+                "a crash prints its backtrace") do
+          @verbose = true
+          set(:verbose, true)
+        end
+        opts.on("--[no-]color", "Colour the text report (default: on for a terminal unless NO_COLOR is set)") do |v|
+          @color = v ? :always : :never
+        end
+      end
+    end
+  end
+end