saboteur 0.6.0 → 0.8.0

data/lib/saboteur/cli/source_set.rb

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The effective source set a run will mutate, refused when it is empty.
+    module SourceSet
+      private
+
+      # The Rails-shaped footgun (#447): the default include targets plain
+      # gems, so a first run on an app/ tree selects nothing and would exit 0
+      # over 0 subjects - a green gate that mutates nothing, every CI run.
+      # Refuse like a typo'd source: exit 2, name the stale pattern and the
+      # way out. --dry-run still previews: it gates nothing.
+      def refuse_empty_source_set
+        return unless config.included_files.empty?
+
+        raise UsageError, empty_source_set_message
+      end
+
+      # A --since ref whose resolved range diffs empty yields 0 subjects
+      # and a green run over nothing: `saboteur pr <merge_sha>` on a
+      # checkout AT the merge diffs the merge against itself (#643).
+      # Refuse like a typo'd ref: exit 2, name the base and the range.
+      def refuse_empty_since_range
+        ref = config["since"]
+        return unless ref
+
+        paths = Selection::GitDiff.changed_paths(ref, root: config.root)
+        return unless paths.values.all?(&:empty?)
+
+        base = Selection::GitDiff.merge_base(ref, root: config.root)
+        raise UsageError, "--since #{ref}: the resolved range #{base}..the working tree has no changes - " \
+                          "the run would pass with 0 subjects. A checkout AT the ref (the CI merge-sha " \
+                          "checkout) diffs it against itself: fetch the merge's parent, or point --since " \
+                          "at the base of the change under test"
+      end
+
+      def empty_source_set_message
+        include_patterns = config["include"]
+        matched = include_patterns.flat_map { |pattern| Dir.glob(pattern, base: config.root) }
+                                  .select { |file| file.end_with?(".rb") }
+        cause = if matched.empty?
+                  "include: #{include_patterns.join(', ')} selects no Ruby file"
+                else
+                  "exclude: #{config['exclude'].join(', ')} removes every included file"
+                end
+        "#{cause} - the run would pass with 0 subjects. Point include at your code " \
+          "(Rails apps: bundle exec rails generate saboteur:install writes the config) or fix the patterns"
+      end
+    end
+  end
+end

data/lib/saboteur/cli/survivors_command.rb

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "json"
+
+module Saboteur
+  class CLI
+    # saboteur survivors <report.json> (#475): a read-only, line-oriented
+    # terminal browser for the Stryker JSON report. It never boots the
+    # project or reruns tests; it lists survivors, filters them, and for
+    # one digest prints the diff, the exact replay command and the
+    # ignore-file template. It never edits the ignore file.
+    module SurvivorsCommand
+      private
+
+      def survivors_command
+        survivors_command_inner
+      rescue UsageError => e
+        @err.puts("saboteur: #{e.message}")
+        EXIT_USAGE
+      end
+
+      def survivors_command_inner
+        parser = OptionParser.new do |opts|
+          opts.on("--ranked", "Review-priority order: the report's ranked findings first")
+          opts.on("--file SUBSTR", "Only survivors whose path contains SUBSTR")
+          opts.on("--operator NAME", "Only survivors of operator NAME")
+          opts.on("--triage LABEL", "Only survivors classified LABEL (for example missing_test)")
+          opts.on("--show DIGEST", "Diff, replay command and ignore template for one survivor")
+        end
+        options = {}
+        args = parser.parse!(@argv, into: options)
+        path = args.shift or raise UsageError,
+                                   "survivors expects a report path: saboteur survivors .saboteur/report.json"
+        raise UsageError, "unexpected arguments: #{args.join(' ')}" if args.any?
+
+        report = load_survivor_report(path)
+        browser = SurvivorsBrowser.new(report)
+        if options[:show]
+          @out.puts(browser.show(options[:show]))
+        else
+          @out.puts(browser.list(**options.slice(:ranked, :file, :operator, :triage)))
+        end
+        EXIT_OK
+      end
+
+      def load_survivor_report(path)
+        raise UsageError, "report not found: #{path}" unless File.file?(path)
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        raise UsageError, "#{path} is not a readable saboteur report: #{e.message}"
+      end
+    end
+
+    # Reads the report's files section (the complete mutant list), not the
+    # capped findings, so survivors beyond the findings limit still list.
+    class SurvivorsBrowser
+      def initialize(report)
+        @report = report
+        @findings = report.dig("saboteur", "findings") || {}
+      end
+
+      def list(ranked: false, file: nil, operator: nil, triage: nil)
+        survivors = filtered(file, operator, triage)
+        survivors = ranked_order(survivors) if ranked
+        return "no survivors#{filters_note(file, operator, triage)}" if survivors.empty?
+
+        [header(survivors.size, file, operator, triage), *rows(survivors)]
+      end
+
+      def show(digest)
+        survivor = all_survivors.find { |s| s[:digest].start_with?(digest) } ||
+                   raise(UsageError, "no survivor with digest #{digest} in this report")
+        finding = findings_by_digest[survivor[:digest]] || {}
+        subject = finding["subject"]
+        [
+          "#{survivor[:path]}:#{survivor[:line]}  #{survivor[:operator]}  #{survivor[:digest]}",
+          "",
+          "- #{finding['original'] || original_line(survivor)}",
+          "+ #{finding['replacement'] || survivor[:replacement]}",
+          "",
+          "Replay exactly this mutant:",
+          "  bundle exec saboteur run --id #{survivor[:digest]}",
+          "",
+          "Ignore-file entry (config/saboteur_ignore.rb):",
+          *ignore_entry(survivor, subject)
+        ].join("\n")
+      end
+
+      private
+
+      def filtered(file, operator, triage)
+        survivors = all_survivors
+        survivors = survivors.select { |s| s[:path].include?(file) } if file
+        survivors = survivors.select { |s| s[:operator] == operator } if operator
+        triage ? survivors.select { |s| s[:classification] == triage } : survivors
+      end
+
+      def header(size, file, operator, triage)
+        text = "#{size} survivor#{'s' unless size == 1}#{filters_note(file, operator, triage)}"
+        truncated = @findings["survivorsTruncated"].to_i
+        return text unless truncated.positive?
+
+        "#{text} (the report's ranked findings name only the first #{@findings['limit'] || 10})"
+      end
+
+      def rows(survivors)
+        survivors.each_with_index.map do |s, i|
+          format("%3<i>d. %<path>s:%<line>d  %-28<operator>s %<digest>s  %<classification>s",
+                 i: i + 1, path: s[:path], line: s[:line], operator: s[:operator], digest: s[:digest],
+                 classification: s[:classification] || "-")
+        end
+      end
+
+      def ignore_entry(survivor, subject)
+        note = subject ? subject.inspect : '"Klass#meth" # TODO: capped findings omit this digest - fill it in'
+        [%(  i.mutation "#{survivor[:digest]}",), "      subject: #{note},", %(      reason: "...")]
+      end
+
+      def all_survivors
+        @all_survivors ||= begin
+          survivors = @report.fetch("files", {}).flat_map do |path, entry|
+            entry.fetch("mutants", []).select { |m| m["status"] == "Survived" }.map do |m|
+              { path: path, line: m.dig("location", "start", "line").to_i, operator: m["mutatorName"],
+                digest: m["id"], replacement: m["replacement"], classification: m["classification"],
+                covered: m["coveredBy"] || [], source: entry["source"] }
+            end
+          end
+          survivors.sort_by { |s| [s[:path], s[:line], s[:digest]] }
+        end
+      end
+
+      def ranked_order(survivors)
+        rank = @findings.fetch("survivors", []).each_with_index.to_h { |f, i| [f["digest"], i] }
+        survivors.sort_by { |s| [rank[s[:digest]] || Float::INFINITY, -s[:covered].size, s[:path], s[:line], s[:digest]] }
+      end
+
+      def findings_by_digest
+        @findings_by_digest ||=
+          (@findings.fetch("survivors", []) + @findings.fetch("accepted", [])).to_h { |f| [f["digest"], f] }
+      end
+
+      def original_line(survivor)
+        survivor[:source].to_s.lines[survivor[:line] - 1].to_s.strip
+      end
+
+      def filters_note(file, operator, triage)
+        parts = []
+        parts << "file~#{file}" if file
+        parts << "operator=#{operator}" if operator
+        parts << "triage=#{triage}" if triage
+        parts.empty? ? "" : " (#{parts.join(', ')})"
+      end
+    end
+  end
+end

data/lib/saboteur/cli.rb

@@ -3,6 +3,7 @@
 
 require "optparse"
 require_relative "../saboteur"
+require_relative "crash_report"
 require_relative "doctor"
 require_relative "help"
 require_relative "reporter/replay"
@@ -10,14 +11,30 @@ require_relative "baseline/command"
 require_relative "cli/exit_status"
 require_relative "preview"
 require_relative "cli/run_reporting"
+require_relative "cli/survivors_command"
+require_relative "cli/source_set"
+require_relative "cli/run_budget_options"
+require_relative "cli/shard_options"
+require_relative "cli/selection_options"
+require_relative "cli/presets"
+require_relative "cli/help_options"
+require_relative "cli/history_command"
 
 module Saboteur
   class CLI
     include Baseline::Command
     include ExitStatus
     include RunReporting
-
-    USAGE = "Usage: saboteur run [SOURCE...] [--test TEST...] [--threshold PERCENT] [--since REF] " \
+    include SurvivorsCommand
+    include SourceSet
+    include RunBudgetOptions
+    include ShardOptions
+    include SelectionOptions
+    include Presets
+    include HistoryCommand
+    include HelpOptions
+
+    USAGE = "Usage: saboteur run [SOURCE...] [--test TEST...] [--all] [--threshold PERCENT] [--since REF] " \
             "[--subject 'Klass#meth'] [--timeout-factor N] [--jobs N] [--seed N] [--id DIGEST]
 " \
             "Run 'saboteur help' for every command, option, config key and exit code."
@@ -26,10 +43,18 @@ module Saboteur
     EXIT_SURVIVORS = 1
     EXIT_USAGE = 2
     EXIT_TOOL = 3
+    EXIT_BUDGET = 4
     class UsageError < ConfigError; end
 
     attr_reader :options
 
+    # Found before parsing, so any error, even a bad option that comes first, still
+    # answers an agent with JSON. Class-level: the executable's fallback reads raw arguments.
+    def self.agent_requested?(argv)
+      argv.include?("--agent") || argv.include?("--format=agent") ||
+        argv.each_cons(2).any? { |flag, value| flag == "--format" && value == "agent" }
+    end
+
     def initialize(argv, out: $stdout, err: $stderr)
       @argv = argv.dup
       @out = out
@@ -39,18 +64,21 @@ module Saboteur
     end
 
     def call
-      case @argv.shift
+      command = @argv.shift
+      case command
       when "run" then run_command
       when "baseline" then baseline
-      when "doctor" then help_requested? ? show_help("doctor") : doctor
+      when "survivors" then survivors_command
+      when "doctor" then doctor_command
+      when "badge", "trend" then history_entry(command)
       when "version", "--version" then @out.puts(VERSION) || EXIT_OK
-      when "help" then show_help(@argv.shift)
+      when "help", "--help", "-h" then show_help(@argv.shift)
       when "agent-skill" then @out.print(AgentSkill::TEXT) || EXIT_OK
-      when "--help", "-h" then show_help(nil)
-      else usage_error
+      else preset_or_usage_error(command)
       end
     rescue OptionParser::ParseError => e
       usage_error(e.message)
+    rescue StandardError => e then internal_error(e)
     end
 
     def config
@@ -68,11 +96,6 @@ module Saboteur
       end
     end
 
-    # Each command's own option lines, as printed under OPTIONS in `saboteur help`.
-    def option_lines
-      { "run" => parser.summarize, "doctor" => doctor_parser.summarize, "baseline" => baseline_parser.summarize }
-    end
-
     def doctor_parser
       OptionParser.new do |opts|
         opts.banner = "Usage: saboteur doctor [--config PATH] [--seed N] [--suite] [--test PATH]"
@@ -87,13 +110,13 @@ module Saboteur
 
     private
 
-    def run_command
-      help_requested? ? show_help("run") : run
-    end
+    def run_command = help_requested? ? show_help("run") : run
 
-    def help_requested?
-      @argv.intersect?(%w[--help -h])
-    end
+    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)
@@ -110,16 +133,9 @@ module Saboteur
       agent_failure(message || USAGE, EXIT_USAGE)
     end
 
-    def agent?
-      @format == "agent"
-    end
+    def agent? = @format == "agent"
 
-    # Found before parsing, so any error, even a bad option that comes first, still
-    # answers an agent with JSON.
-    def agent_requested?
-      @argv.include?("--agent") || @argv.include?("--format=agent") ||
-        @argv.each_cons(2).any? { |flag, value| flag == "--format" && value == "agent" }
-    end
+    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)
@@ -129,12 +145,17 @@ module Saboteur
 
     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
+      refuse_empty_since_range
       execute_run
     rescue ConfigError => e
       @err.puts("saboteur: #{e.message}")
@@ -146,28 +167,60 @@ module Saboteur
 
     # 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
-      WorkingTree.new(config.root, ignored: config.output_paths).state.warning&.then { |text| @err.puts(text) }
+      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_threshold_with_agent_format
+      reject_format_conflicts
+      validate_shard_options
       Selection::GitDiff.verify_ref!(config["since"], root: config.root) if config["since"]
     end
 
-    # Agent mode has one strict meaning for exit 0, so a score threshold cannot also decide it.
-    def reject_threshold_with_agent_format
-      return unless agent? && (config["threshold"] || gates.any?)
+    # 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, "#{config['threshold'] ? '--threshold' : '--max-* gates'} cannot be combined with --agent"
+      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)
-      written = reports.select { |path, _label| path }
-      return if written.empty?
+      return if (written = reports.select { |path, _label| path }).empty?
 
       root = File.join(File.realpath(config.root), "")
       names = written.map do |path, label|
@@ -209,16 +262,38 @@ module Saboteur
       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 || options[:tests]),
+        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
+        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
-      options.slice(*Reporter::Agent::Commands::SETTING_FLAGS.keys)
-             .merge(operators: config["operators"], exclude_operators: config["exclude_operators"])
+      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
@@ -228,40 +303,19 @@ module Saboteur
       @sources&.any? ? "files" : "full"
     end
 
-    # Writes the JSON report and returns its path, or nil when none is configured.
-    def write_json(report, cause)
-      path = config.path("json_report")
-      return unless path
-
-      Reporter::Stryker.new(path).call(report, exit_cause: cause)
-      path
-    end
-
-    def write_html(report)
-      path = config.path("html_report")
-      return unless path
-
-      Reporter::Html.new(path).call(report)
-      path
-    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
-      if @argv.empty?
-        raise UsageError, "--test needs at least one source file" if options[:tests] && !config["since"]
-
-        # With --since the changed files are the sources, so --test may
-        # stand alone; the files must still exist.
-        options[:tests]&.each { |test| require_existing_test(test) }
-        return
-      end
+      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] = []
-      options[:tests]&.each { |test| require_existing_test(test) }
     end
 
     def source_pattern(source)
@@ -283,12 +337,10 @@ module Saboteur
       raise UsageError, "test file not found: #{test}" unless File.exist?(path)
     end
 
-    def overrides
-      options.except(:config, :id, :suite, :list_operators, :dry_run)
-    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" if agent?
+      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]
@@ -296,30 +348,14 @@ module Saboteur
         return EXIT_OK
       end
 
-      Preview.new(config, out: @out, err: @err).call
+      Preview.new(config, out: @out, err: @err, format: @format).call
       EXIT_OK
     end
 
-    def define_selection_options(opts)
-      opts.on("--operators NAMES", Array, "Choose operator names (default: all)") do |v|
-        set(:operators, v)
-      end
-      opts.on("--exclude-operators NAMES", Array, "Exclude operator names from the selected set") do |v|
-        set(:exclude_operators, v)
-      end
-      opts.on("--list-operators", "List operator names and descriptions") { set(:list_operators, true) }
-      opts.on("--dry-run", "Preview mutants without boot, tests, forks or report writes") { set(:dry_run, true) }
-      opts.on("--id DIGEST", "Replay exactly one current mutant by its full digest") { |v| set(:id, v) }
-      opts.on("--since REF", "Only mutate subjects changed since git REF") { |v| options[:since] = v }
-      opts.on("--subject EXPR", "Klass#meth, Klass.meth or a namespace; repeatable") { |v| add_subject(v) }
-    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) }
-      opts.on("--seed N", Integer, "Seed for Ruby's random numbers in every test run (default 1)") do |v|
-        set(:seed, v)
-      end
+      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) }
@@ -332,8 +368,14 @@ module Saboteur
       opts.on("--allow-focus", "Run even when a focus filter (fit, fdescribe, :focus) narrows the suite") do
         set(:allow_focus, true)
       end
-      opts.on("--[no-]guess-tests", "With --since: run only the specs named after the changed files " \
-                                    "(lib/a.rb -> spec/a_spec.rb); the whole suite if any has none") do |v|
+      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
@@ -348,10 +390,10 @@ module Saboteur
       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], "text (default) or agent: one bounded JSON summary on stdout, " \
-                                                 "strict exit codes") { |v| @format = 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") { @verbose = true }
+      opts.on("--verbose", "Text report: also print score split, timings and kill causes;",
+              "a crash prints its backtrace") { @verbose = true }
       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
@@ -367,12 +409,8 @@ module Saboteur
       Gates.define_options(opts) { |key, value| set(key, value) }
     end
 
-    def add_subject(expr)
-      (options[:subjects] ||= []) << expr
-    end
+    def add_subject(expr) = (options[:subjects] ||= []) << expr
 
-    def set(key, value)
-      options[key] = value
-    end
+    def set(key, value) = (options[key] = value)
   end
 end