saboteur 0.8.1 → 0.9.0

data/lib/saboteur/cli/preview_command.rb

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # `run --dry-run` and `run --list-operators`: plan output, no mutations
+    # (#334). Extracted from CLI by command.
+    module PreviewCommand
+      private
+
+      def preview
+        raise UsageError, "--dry-run and --list-operators print text, not --agent JSON; use --format json" if agent?
+        raise UsageError, "--id replays one mutant: not with --dry-run or --list-operators" if options[:id]
+
+        if options[:list_operators]
+          MutationSource::OperatorRegistry.list(@out, names: config["operators"],
+                                                      excluded: config["exclude_operators"])
+          return EXIT_OK
+        end
+
+        Preview.new(config, out: @out, err: @err, format: @format).call
+        EXIT_OK
+      end
+    end
+  end
+end

data/lib/saboteur/cli/run_budget_options.rb

@@ -13,6 +13,9 @@ module Saboteur
         opts.on("--seed N", Integer, "Seed for Ruby's random numbers in every test run (default 1)") do |v|
           set(:seed, v)
         end
+        opts.on("--coverage-parts N", Integer, "Build the coverage map in N parallel parts (default 1)") do |v|
+          set(:coverage_parts, v)
+        end
         opts.on("--baseline-passes N", Integer, "Unchanged-suite checks (default 2)") { |v| set(:baseline_passes, v) }
         opts.on("--max-duration DURATION", "Wall-clock budget for the whole run, e.g. 10m; exit 4 when spent - " \
                                            "the clock starts at engine entry, so boot, baselines and the " \

data/lib/saboteur/cli/run_command.rb

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # `saboteur run`: parse, validate, then preview or execute (#334).
+    # Extracted from CLI by command.
+    module RunCommand
+      private
+
+      def run_command = help_requested? ? show_help("run") : run
+
+      def run
+        parser.parse!(@argv)
+        reject_test_selection_conflicts
+        use_explicit_sources
+        validate_run_options
+        warn_dirty_tree
+
+        config.deprecation_warnings.each { |warning| @err.puts("saboteur: #{warning}") }
+
+        return preview if options[:list_operators] || options[:dry_run]
+
+        refuse_empty_source_set
+        execute_run
+      rescue ConfigError => e
+        report_failure(e, EXIT_USAGE)
+      rescue Error => e
+        report_failure(e, EXIT_TOOL)
+      end
+    end
+  end
+end

data/lib/saboteur/cli/run_output.rb

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # Where a run's own output goes: the report names it prints and the
+    # stdout redirect that keeps agent JSON clean (#334). Extracted from CLI.
+    module RunOutput
+      private
+
+      # One line naming the reports written, paths relative to the root when
+      # they sit under it (a blank line before it, as the old JSON line had).
+      def announce_reports(reports)
+        return if (written = reports.select { |path, _label| path }).empty?
+
+        root = File.join(File.realpath(config.root), "")
+        names = written.map do |path, label|
+          shown = File.expand_path(path).delete_prefix(root)
+          "#{shown} (#{label})"
+        end
+        @out.puts "\nReports: #{names.join(', ')}"
+      end
+
+      # Agent mode: stdout carries exactly one JSON payload. The target's own output (boot
+      # files, hooks, spec loading, child processes) goes to stderr while the engine runs.
+      # Descriptor 1 points at stderr for the block, so Kernel#puts, system and forked
+      # children cannot write into the JSON on stdout.
+      def stdout_on_stderr
+        saved = $stdout.dup
+        $stdout.reopen($stderr)
+        yield
+      ensure
+        $stdout.reopen(saved) if saved
+        saved&.close
+      end
+    end
+  end
+end

data/lib/saboteur/cli/run_reporting.rb

@@ -30,7 +30,7 @@ module Saboteur
       end
 
       def agent_run(arguments)
-        tree = WorkingTree.new(config.root, ignored: config.output_paths).state
+        tree = WorkingTree.new(config.root, ignored: config.ignored_tree_paths).state
         engine = Engine.new(config, **arguments)
         report = stdout_on_stderr { engine.call }
         payload = Reporter::Agent.call(report, agent_provenance(report, tree, engine))
@@ -65,7 +65,7 @@ module Saboteur
       # Computed lazily: only a run with survivors asks for it.
       def survivor_replay_command(report, engine)
         lambda do |digest|
-          tree = WorkingTree.new(config.root, ignored: config.output_paths).state
+          tree = WorkingTree.new(config.root, ignored: config.ignored_tree_paths).state
           Reporter::Agent::Commands.replay(agent_provenance(report, tree, engine), digest, capped: false)
         end
       end
@@ -82,7 +82,8 @@ module Saboteur
         path = config.path("json_report")
         return unless path
 
-        Reporter::Stryker.new(path).call(report, exit_cause: cause)
+        Reporter::Stryker.new(path).call(report, exit_cause: cause,
+                                                 score_gates: gates.score_gate_breakdowns(report))
         path
       rescue SystemCallError, IOError => e
         if config.explicit?("json_report")
@@ -124,8 +125,8 @@ module Saboteur
         path = config.path("score_history")
         return unless path
 
-        tree = WorkingTree.new(config.root, ignored: config.output_paths).state
-        scope = config.selection_settings.except("json_report", "html_report", "score_history", "cache_dir")
+        tree = WorkingTree.new(config.root, ignored: config.ignored_tree_paths).state
+        scope = config.selection_settings.except(*Config::OUTPUT_KEYS)
         # Recording is an auxiliary artifact: when the file cannot be
         # written - read-only tree inside a sandboxed child (#296) - warn
         # and let the run exit by its results instead of failing as a tool

data/lib/saboteur/cli/run_validation.rb

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The usage errors `saboteur run` finds before the target boots: option
+    # combinations that contradict each other (#334). Extracted from CLI.
+    module RunValidation
+      private
+
+      # Contradictory selection flags are a usage error before any file or
+      # repository check: --test wins over inference by precedence, but only
+      # one of them may be named. Config-file combinations are not errors:
+      # --test wins there, so generated commands stay valid over any config.
+      def reject_test_selection_conflicts
+        raise UsageError, "--all cannot be combined with --test" if options[:all] && options[:tests]&.any?
+
+        reject_test_command_conflicts
+        raise UsageError, "--all cannot be combined with --guess-tests" if options[:all] && options[:guess_tests]
+        return unless options[:guess_tests] && options[:tests]&.any?
+
+        raise UsageError, "--guess-tests cannot be combined with --test"
+      end
+
+      # --test-command replaces the whole in-process test machinery: test
+      # selection, coverage, parallelism and the sandbox do not apply.
+      def reject_test_command_conflicts
+        return unless options[:test_command]
+
+        # options[:tests] is nil or a non-empty list, so truthiness is the check.
+        raise UsageError, "--test-command cannot be combined with --test" if options[:tests]
+        raise UsageError, "--test-command cannot be combined with --incremental" if options[:incremental]
+      end
+
+      # Usage errors found before the target boots.
+      def validate_run_options
+        reject_format_conflicts
+        validate_shard_options
+        Selection::GitDiff.verify_ref!(config["since"], root: config.root) if config["since"]
+      end
+
+      # Agent mode allows no score gates (one strict exit 0); the json inventory is --dry-run planning only.
+      def reject_format_conflicts
+        if agent? && (config["threshold"] || gates.any?)
+          raise UsageError, "#{config['threshold'] ? '--threshold' : gates.agent_option_name} " \
+                            "cannot be combined with --agent"
+        end
+        return unless @format == "json" && !options[:dry_run]
+
+        raise UsageError, "--format json is the --dry-run mutant inventory; a run summary is --format agent"
+      end
+    end
+  end
+end

data/lib/saboteur/cli.rb

@@ -8,6 +8,7 @@ require_relative "doctor"
 require_relative "help"
 require_relative "reporter/replay"
 require_relative "baseline/command"
+require_relative "cli/error_cause"
 require_relative "cli/exit_status"
 require_relative "preview"
 require_relative "cli/run_reporting"
@@ -19,6 +20,20 @@ require_relative "cli/selection_options"
 require_relative "cli/presets"
 require_relative "cli/help_options"
 require_relative "cli/history_command"
+require_relative "cli/execution_options"
+require_relative "cli/matrix_option"
+require_relative "cli/output_options"
+require_relative "cli/explicit_file_options"
+require_relative "cli/doctor_command"
+require_relative "cli/agent_provenance"
+require_relative "cli/preview_command"
+require_relative "cli/help_command"
+require_relative "cli/run_validation"
+require_relative "cli/explicit_sources"
+require_relative "cli/run_output"
+require_relative "cli/dirty_tree_notice"
+require_relative "cli/run_command"
+require_relative "cli/failure_output"
 
 module Saboteur
   class CLI
@@ -32,7 +47,21 @@ module Saboteur
     include SelectionOptions
     include Presets
     include HistoryCommand
+    include ExecutionOptions
+    include MatrixOption
+    include OutputOptions
+    include ExplicitFileOptions
+    include DoctorCommand
+    include AgentProvenance
     include HelpOptions
+    include PreviewCommand
+    include HelpCommand
+    include RunValidation
+    include ExplicitSources
+    include RunOutput
+    include DirtyTreeNotice
+    include RunCommand
+    include FailureOutput
 
     USAGE = "Usage: saboteur run [SOURCE...] [--test TEST...] [--all] [--threshold PERCENT] [--since REF] " \
             "[--subject 'Klass#meth'] [--timeout-factor N] [--jobs N] [--seed N] [--id DIGEST]
@@ -96,321 +125,14 @@ module Saboteur
       end
     end
 
-    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 run_command = help_requested? ? show_help("run") : run
-
-    def doctor_command = help_requested? ? show_help("doctor") : doctor
-
     def history_entry(command) = help_requested? ? show_help(command) : history_command(command)
 
-    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
-
-    def usage_error(message = nil)
-      @err.puts(message) if message
-      @err.puts(USAGE)
-      agent_failure(message || USAGE, EXIT_USAGE)
-    end
-
-    def agent? = @format == "agent"
-
     def agent_requested? = self.class.agent_requested?(@argv)
 
-    # 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
-
-    def run
-      parser.parse!(@argv)
-      reject_test_selection_conflicts
-      use_explicit_sources
-      validate_run_options
-      warn_dirty_tree
-
-      config.deprecation_warnings.each { |warning| @err.puts("saboteur: #{warning}") }
-
-      return preview if options[:list_operators] || options[:dry_run]
-
-      refuse_empty_source_set
-      execute_run
-    rescue ConfigError => e
-      @err.puts("saboteur: #{e.message}")
-      agent_failure(e.message, EXIT_USAGE)
-    rescue Error => e
-      @err.puts("saboteur: #{e.message}")
-      agent_failure(e.message, EXIT_TOOL)
-    end
-
-    # 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 = @sources ? Config.load(path: options[:config], overrides: overrides.except(:include, :exclude)) : config
-      DirtyTreeWarning.for(warning, config_path: options[:config])&.then { |text| @err.puts(text) }
-    end
-
-    # Contradictory selection flags are a usage error before any file or
-    # repository check: --test wins over inference by precedence, but only
-    # one of them may be named. Config-file combinations are not errors:
-    # --test wins there, so generated commands stay valid over any config.
-    def reject_test_selection_conflicts
-      raise UsageError, "--all cannot be combined with --test" if options[:all] && options[:tests]&.any?
-
-      reject_test_command_conflicts
-      raise UsageError, "--all cannot be combined with --guess-tests" if options[:all] && options[:guess_tests]
-      return unless options[:guess_tests] && options[:tests]&.any?
-
-      raise UsageError, "--guess-tests cannot be combined with --test"
-    end
-
-    # --test-command replaces the whole in-process test machinery: test
-    # selection, coverage, parallelism and the sandbox do not apply.
-    def reject_test_command_conflicts
-      return unless options[:test_command]
-
-      # options[:tests] is nil or a non-empty list, so truthiness is the check.
-      raise UsageError, "--test-command cannot be combined with --test" if options[:tests]
-      raise UsageError, "--test-command cannot be combined with --incremental" if options[:incremental]
-    end
-
-    # Usage errors found before the target boots.
-    def validate_run_options
-      reject_format_conflicts
-      validate_shard_options
-      Selection::GitDiff.verify_ref!(config["since"], root: config.root) if config["since"]
-    end
-
-    # Agent mode allows no score gates (one strict exit 0); the json inventory is --dry-run planning only.
-    def reject_format_conflicts
-      if agent? && (config["threshold"] || gates.any?)
-        raise UsageError, "#{config['threshold'] ? '--threshold' : gates.agent_option_name} " \
-                          "cannot be combined with --agent"
-      end
-      return unless @format == "json" && !options[:dry_run]
-
-      raise UsageError, "--format json is the --dry-run mutant inventory; a run summary is --format agent"
-    end
-
-    # One line naming the reports written, paths relative to the root when
-    # they sit under it (a blank line before it, as the old JSON line had).
-    def announce_reports(reports)
-      return if (written = reports.select { |path, _label| path }).empty?
-
-      root = File.join(File.realpath(config.root), "")
-      names = written.map do |path, label|
-        shown = File.expand_path(path).delete_prefix(root)
-        "#{shown} (#{label})"
-      end
-      @out.puts "\nReports: #{names.join(', ')}"
-    end
-
-    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: #{e.message}")
-      EXIT_USAGE
-    rescue Error => e
-      @err.puts("saboteur: #{e.message}")
-      EXIT_TOOL
-    end
-
-    # Agent mode: stdout carries exactly one JSON payload. The target's own output (boot
-    # files, hooks, spec loading, child processes) goes to stderr while the engine runs.
-    # Descriptor 1 points at stderr for the block, so Kernel#puts, system and forked
-    # children cannot write into the JSON on stdout.
-    def stdout_on_stderr
-      saved = $stdout.dup
-      $stdout.reopen($stderr)
-      yield
-    ensure
-      $stdout.reopen(saved) if saved
-      saved&.close
-    end
-
-    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
-      )
-    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
-
-    # 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
-
     def overrides = options.except(:config, :id, :suite, :list_operators, :dry_run)
 
-    def preview
-      raise UsageError, "--dry-run and --list-operators print text, not --agent JSON; use --format json" if agent?
-      raise UsageError, "--id replays one mutant: not with --dry-run or --list-operators" if options[:id]
-
-      if options[:list_operators]
-        MutationSource::OperatorRegistry.list(@out, names: config["operators"], excluded: config["exclude_operators"])
-        return EXIT_OK
-      end
-
-      Preview.new(config, out: @out, err: @err, format: @format).call
-      EXIT_OK
-    end
-
-    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, ...)") do
-        set(:allow_hazardous, true)
-      end
-      opts.on("--fail-fast", "Stop after the first subject with a survivor (needs --jobs 1)") { set(:fail_fast, true) }
-      opts.on("--incremental", "Reuse earlier verdicts whose inputs did not change") { set(:incremental, true) }
-      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 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
-
-    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
-
-    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
-
     def add_subject(expr) = (options[:subjects] ||= []) << expr
 
     def set(key, value) = (options[key] = value)