simplecov 1.1.1 → 1.3.0

data/lib/simplecov/cli/status.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "time"
+require_relative "command_helpers"
+require_relative "git"
+require_relative "status/facts"
+
+module SimpleCov
+  module CLI
+    module Status
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:)
+        opts, = parse_common(args)
+        document = CoverageFile.load_document(opts.fetch(:input), command: "status", stderr: stderr)
+        return 1 unless document
+
+        facts = Facts.gather(document, CLI.default_resultset)
+        opts.fetch(:json) ? stdout.puts(JSON.pretty_generate(facts)) : print_facts(facts, opts, stdout)
+        0
+      end
+
+      def print_facts(facts, opts, stdout)
+        stdout.puts("report #{opts.fetch(:input)}")
+        report_lines(facts).each { |line| stdout.puts("  #{line}") }
+        print_resultset(facts, stdout)
+      end
+
+      def report_lines(facts)
+        [
+          facts.fetch(:generated_at) && "generated #{facts.fetch(:generated_at)}#{age_suffix(facts.fetch(:age))}",
+          provenance_words(facts),
+          "commit #{commit_words(facts)}",
+          (totals_words(facts.fetch(:totals)) unless facts.fetch(:totals).empty?),
+          "tests recorded: #{contexts_words(facts.fetch(:contexts))}"
+        ].compact
+      end
+
+      def provenance_words(facts)
+        "by simplecov #{facts.fetch(:version)} running #{facts.fetch(:command_name)}"
+      end
+
+      def commit_words(facts)
+        commit = facts.fetch(:commit)
+        return "not recorded" unless commit.instance_of?(String)
+
+        "#{commit[0, 7]} (#{distance_words(facts.fetch(:behind))})"
+      end
+
+      def distance_words(behind)
+        return "not in this repository's history" unless behind
+        return "current HEAD" if behind.zero?
+
+        "#{behind} commit#{"s" unless one?(behind)} behind HEAD"
+      end
+
+      def totals_words(totals)
+        totals.map { |name, percent| "#{name} #{format("%.2f%%", percent)}" }.join(", ")
+      end
+
+      def contexts_words(count)
+        count ? "#{count} (track_tests)" : "none (enable track_tests to select and re-run by test)"
+      end
+
+      def print_resultset(facts, stdout)
+        entries = facts.fetch(:resultset)
+        return stdout.puts("resultset none") unless entries
+
+        stdout.puts("resultset #{facts.fetch(:resultset_path)}")
+        entries.each do |entry|
+          age = entry.fetch(:age) ? "#{age_in_words(entry.fetch(:age))} ago" : "age unknown"
+          stdout.puts("  #{entry.fetch(:command)}: #{age}")
+        end
+      end
+
+      def age_suffix(age)
+        " (#{age_in_words(age)} ago)" if age
+      end
+
+      def age_in_words(seconds)
+        return "#{seconds.round} seconds" if seconds < 90
+        return "#{(seconds / 60.0).round} minutes" if seconds < 5400
+        return "#{(seconds / 3600.0).round} hours" if seconds < 129_600
+
+        "#{(seconds / 86_400.0).round} days"
+      end
+    end
+  end
+end

data/lib/simplecov/cli/tests/redundancy.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Tests
+      # The `--redundant` sweep: the contexts whose covered lines other contexts
+      # also cover, the tests contributing no coverage of their own. A context is
+      # non-redundant exactly when some line is covered by it alone, so per file
+      # two bitmaps (lines seen once, lines seen more than once) find the uniquely
+      # covered lines and a second pass credits each to its owner.
+      module Redundancy
+        extend self
+
+        def redundant_ids(document, contexts, opts, stderr)
+          tables = sweep_tables(document, contexts, opts, stderr)
+          return unless tables
+
+          unique = unique_owners(tables, contexts.size)
+          contexts.each_index.reject { |index| unique.fetch(index) }.map { |index| contexts.fetch(index) }.sort
+        end
+
+        def unique_owners(tables, context_count)
+          unique = Array.new(context_count, false)
+          tables.each do |table|
+            lone = lone_bits(table)
+            table.each { |index, bitmap| unique[index] = true if bitmap.anybits?(lone) }
+          end
+          unique
+        end
+
+        # A bit enters `once` when brand new and leaves for good when any later
+        # bitmap carries it again. The two halves of the update are provably
+        # disjoint, so they are summed: for disjoint bits that builds the number OR
+        # would, and it leaves no spelling of the combination without a witness.
+        def lone_bits(table)
+          once = 0
+          ever = 0
+          table.each_value do |bitmap|
+            once = (once & ~bitmap) + (bitmap & ~ever)
+            ever |= bitmap
+          end
+          once
+        end
+
+        # The sweep reads tables no query named, so a malformed one anywhere poisons
+        # the whole answer, matching the targeted queries' all-or-nothing tolerance.
+        def sweep_tables(document, contexts, opts, stderr)
+          coverage = document["coverage"]
+          return invalid(opts, stderr, '"coverage" must be an object') unless coverage.is_a?(Hash)
+
+          tables = [] #: Array[Hash[Integer, Integer]]
+          coverage.each do |path, entry|
+            table = entry.is_a?(Hash) && swept_table(entry, contexts)
+            return invalid(opts, stderr, complaint(path, entry)) unless table
+
+            tables << table
+          end
+          tables
+        end
+
+        def swept_table(entry, contexts)
+          raw = entry["contexts"] || {}
+          Tests.decode_table(raw, contexts.size) if raw.is_a?(Hash)
+        end
+
+        def complaint(path, entry)
+          return "entry for #{path} must be an object" unless entry.is_a?(Hash)
+
+          "entry for #{path} carries a malformed \"contexts\" table"
+        end
+
+        def invalid(opts, stderr, reason)
+          CoverageFile.report_invalid(stderr, "tests", opts.fetch(:input), reason)
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/tests.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+require_relative "tests/redundancy"
+
+module SimpleCov
+  module CLI
+    # `simplecov tests [<path>[:<line>]]`: list the recorded tests from a
+    # coverage.json written under `track_tests`. Text output is one id per line
+    # so the list can feed a test runner directly; empty answers keep stdout
+    # empty and note the emptiness on stderr instead.
+    module Tests
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:)
+        opts = parse(args)
+        return error(stderr, "line number must be positive") if opts.fetch(:line)&.zero?
+
+        document = CoverageFile.load_document(opts.fetch(:input), command: "tests", stderr: stderr)
+        return 1 unless document
+
+        ids = resolve(document, opts, stderr)
+        return 1 unless ids
+
+        emit(ids, opts, stdout, stderr)
+        0
+      end
+
+      def parse(args)
+        opts, rest = parse_common(args) do |parser, options|
+          parser.on("--redundant") { options[:redundant] = true }
+        end
+        opts[:target] = rest.first
+        split = split_target(rest.first)
+        opts[:path] = split.fetch(:path)
+        opts[:line] = split.fetch(:line)
+        opts
+      end
+
+      # Only an all-digit tail after the last colon reads as a line number, so
+      # Windows drive colons and exotic filenames stay plain paths.
+      def split_target(target)
+        return {path: nil, line: nil} unless target
+
+        path, sep, tail = target.rpartition(":")
+        return {path: target, line: nil} if sep.empty? || !tail.match?(/\A\d+\z/)
+
+        {path: path, line: Integer(tail, 10)}
+      end
+
+      def resolve(document, opts, stderr)
+        contexts = recorded_contexts(document, opts, stderr)
+        return unless contexts
+
+        opts[:no_recording] = contexts.empty?
+        ids = selected_ids(document, contexts, opts, stderr)
+        return ids unless ids && opts[:redundant]
+
+        redundant = Redundancy.redundant_ids(document, contexts, opts, stderr)
+        redundant && (ids & redundant)
+      end
+
+      def selected_ids(document, contexts, opts, stderr)
+        return contexts.sort unless opts.fetch(:path)
+
+        entry = locate_entry(document, opts, stderr)
+        return unless entry
+
+        table = context_table(entry, contexts, opts, stderr)
+        table && ids_from(table, contexts, opts.fetch(:line))
+      end
+
+      def locate_entry(document, opts, stderr)
+        coverage = document["coverage"]
+        input = opts.fetch(:input)
+        unless coverage.is_a?(Hash)
+          return CoverageFile.report_invalid(stderr, "tests", input, '"coverage" must be an object')
+        end
+
+        path = opts.fetch(:path)
+        match = CoverageFile.lookup(coverage, path)
+        return error_nil(stderr, CoverageFile.not_found_message(coverage, path, input)) unless match
+        return match.last if match.last.is_a?(Hash)
+
+        CoverageFile.report_invalid(stderr, "tests", input, "entry for #{path} must be an object")
+      end
+
+      def context_table(entry, contexts, opts, stderr)
+        raw = entry["contexts"] || {}
+        table = decode_table(raw, contexts.size) if raw.is_a?(Hash)
+        return table if table
+
+        CoverageFile.report_invalid(stderr, "tests", opts.fetch(:input),
+          "entry for #{opts.fetch(:path)} carries a malformed \"contexts\" table")
+      end
+
+      # An absent key is an untouched file; anything malformed, a foreign index or
+      # a non-hex bitmap, poisons the whole answer, matching the all-or-nothing
+      # tolerance the resultset reader applies.
+      def decode_table(raw, context_count)
+        table = {} #: Hash[Integer, Integer]
+        raw.each do |index, hex|
+          return nil unless index.is_a?(String) && index.match?(/\A\d+\z/)
+          return nil unless hex.is_a?(String) && hex.match?(/\A\h+\z/)
+
+          position = Integer(index, 10)
+          return nil unless position < context_count
+
+          table[position] = Integer(hex, 16)
+        end
+        table
+      end
+
+      def ids_from(table, contexts, line)
+        bit = line && (1 << (line - 1))
+        table.filter_map { |index, bitmap| contexts.fetch(index) if bit.nil? || bitmap.anybits?(bit) }.sort
+      end
+
+      def emit(ids, opts, stdout, stderr)
+        return stdout.puts(JSON.pretty_generate(ids)) if opts.fetch(:json)
+        return note_empty(opts, stderr) if ids.empty?
+
+        ids.each { |id| stdout.puts(id) }
+      end
+
+      def note_empty(opts, stderr)
+        stderr.puts("simplecov tests: #{empty_message(opts)}")
+      end
+
+      def empty_message(opts)
+        target = opts.fetch(:target)
+        if opts[:redundant] && !opts.fetch(:no_recording)
+          return "no redundant test covers #{target}" if target
+
+          "no redundant tests, every recorded test covers at least one line uniquely"
+        elsif target
+          "no recorded test covers #{target}"
+        else
+          "no tests recorded"
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/uncovered/misses.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Uncovered
+      module Misses
+        extend self
+
+        def missed_for(payload, criterion)
+          case criterion
+          when :line then payload["lines"].instance_of?(Array) ? Show::Annotator.missed_lines(payload) : []
+          when :branch then collect(payload["branches"])
+          else collect(payload["methods"])
+          end
+        end
+
+        def collect(items)
+          missed = [] #: Array[Integer]
+          Show::Annotator.each_missed(items) { |line| missed << line }
+          missed.uniq.sort
+        end
+
+        def annotate(stdout, files, criterion, kind)
+          root = "#{File.expand_path(SimpleCov.root)}/"
+          diagnostics = files.flat_map do |fname, _pct, _covered, _total, missed|
+            Annotations.diagnostics(fname.delete_prefix(root), missed, criterion)
+          end
+          Annotations.emit(stdout, kind, diagnostics)
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/uncovered.rb

@@ -2,37 +2,41 @@
 
 require "json"
 require "optparse"
+require_relative "annotations"
 require_relative "command_helpers"
+require_relative "patch/output"
+require_relative "show/annotator"
+require_relative "uncovered/misses"
 
 module SimpleCov
   module CLI
-    # `simplecov uncovered [--threshold N] [--top N] [--criterion C]` — list
-    # the lowest-coverage files (by the chosen criterion, ascending), so a
-    # developer can answer "where should I add tests next?" without
-    # opening a browser. Reads coverage.json directly.
+    # `simplecov uncovered`: the lowest-coverage files by the chosen criterion,
+    # ascending, so a developer can answer "where should I add tests next?"
+    # without opening a browser.
     module Uncovered
       extend CommandHelpers
 
       DEFAULT_TOP = 10
 
-    module_function
+      extend self
 
       def run(args, stdout:, stderr:, **)
         opts = parse(args)
-        keys = CoverageFile::CRITERIA[opts[:criterion]]
-        return unknown_criterion(opts[:criterion], stderr) unless keys
+        issue = Annotations.issue(opts)
+        return error(stderr, issue) if issue
 
+        keys = CoverageFile::CRITERIA[opts.fetch(:criterion)]
+        return unknown_criterion(opts.fetch(:criterion), stderr) unless keys
+
+        opts[:missing] = true if opts.fetch(:annotate)
         report(opts, keys, stdout, stderr)
       end
 
       def report(opts, keys, stdout, stderr)
-        coverage = CoverageFile.load_coverage(opts[:input], command: "uncovered", stderr: stderr)
+        coverage = CoverageFile.load_coverage(opts.fetch(:input), command: "uncovered", stderr: stderr)
         return 1 unless coverage
 
-        files = rank(coverage, opts[:threshold], keys).first(opts[:top])
-        return stdout.puts(empty_message(opts[:json])) || 0 if files.empty?
-
-        emit(stdout, files, opts)
+        emit(stdout, rank(coverage, opts, keys).first(opts.fetch(:top)), opts)
         0
       end
 
@@ -42,22 +46,30 @@ module SimpleCov
       end
 
       def emit(stdout, files, opts)
-        opts[:json] ? emit_json(stdout, files) : emit_text(stdout, files, SimpleCov::CLI.color_enabled?(opts, stdout))
+        kind = opts.fetch(:annotate)
+        return Misses.annotate(stdout, files, opts.fetch(:criterion), kind) if kind
+        return stdout.puts(empty_message(opts.fetch(:json))) if files.empty?
+
+        opts.fetch(:json) ? emit_json(stdout, files) : emit_text(stdout, files, CLI.color_enabled?(opts, stdout))
       end
 
       def parse(args)
-        opts, = parse_common(args, threshold: 100.0, top: DEFAULT_TOP, criterion: :line) do |o, options|
-          o.on("--threshold N", Float) { |v| options[:threshold] = v }
-          o.on("--top N", Integer)     { |v| options[:top] = validate_top(v) }
-          o.on("--criterion C")        { |v| options[:criterion] = v.to_sym }
-        end
+        opts, = parse_common(args, threshold: 100.0, top: DEFAULT_TOP, criterion: :line,
+          missing: false, annotate: nil) { |o, options| own_options(o, options) }
         opts
       end
 
-      # A negative count would raise from `Array#first`; report it as
-      # the parse error it is (`--top 0` is allowed and shows nothing).
-      # OptionParser prepends the offending option's name, so the raise
-      # carries only the reason.
+      def own_options(parser, options)
+        parser.on("--threshold N", Float) { |v| options[:threshold] = v }
+        parser.on("--top N", Integer) { |v| options[:top] = validate_top(v) }
+        parser.on("--criterion C") { |v| options[:criterion] = v.to_sym }
+        parser.on("--missing") { options[:missing] = true }
+        parser.on("--annotate KIND") { |v| options[:annotate] = v }
+      end
+
+      # A negative count would raise from `Array#first`, so it is reported as the
+      # parse error it is. `--top 0` is allowed and shows nothing. OptionParser
+      # prepends the offending option's name, so the raise carries only the reason.
       def validate_top(value)
         raise OptionParser::InvalidArgument, "must not be negative" if value.negative?
 
@@ -65,12 +77,18 @@ module SimpleCov
       end
 
       def emit_text(stdout, files, color)
-        files.each { |fname, pct, covered, total| stdout.puts(format_row(fname, pct, covered, total, color)) }
+        files.each do |fname, pct, covered, total, missed|
+          row = format_row(fname, pct, covered, total, color)
+          row += "  missing #{Patch::Output.ranges(missed, ",")}" if missed&.any?
+          stdout.puts(row)
+        end
       end
 
       def emit_json(stdout, files)
-        rows = files.map do |fname, pct, covered, total|
-          {"file" => fname, "percent" => pct, "covered" => covered, "total" => total}
+        rows = files.map do |fname, pct, covered, total, missed|
+          row = {"file" => fname, "percent" => pct, "covered" => covered, "total" => total}
+          row["missing"] = missed if missed
+          row
         end
         stdout.puts(JSON.pretty_generate(rows))
       end
@@ -79,24 +97,30 @@ module SimpleCov
         json ? "[]" : "simplecov uncovered: nothing to report"
       end
 
-      def rank(coverage_hash, threshold, keys)
-        rows = coverage_hash.filter_map { |fname, payload| row_for(fname, payload, threshold, keys) }
+      def rank(coverage_hash, opts, keys)
+        rows = coverage_hash.filter_map { |fname, payload| row_for(fname, payload, opts, keys) }
         rows.sort_by { |_fname, pct, _c, _t| pct }
       end
 
-      def row_for(fname, payload, threshold, keys)
-        return unless payload.is_a?(Hash) && payload[keys[:total]].to_i.positive?
+      def row_for(fname, payload, opts, keys)
+        return unless payload.instance_of?(Hash) && payload[keys.fetch(:total)].to_i.positive?
 
-        pct = payload[keys[:percent]].to_f
-        return if pct >= threshold
+        pct = payload[keys.fetch(:percent)].to_f
+        return if pct >= opts.fetch(:threshold)
+
+        build_row(fname, pct, payload, opts, keys)
+      end
 
-        [fname, pct, payload[keys[:covered]].to_i, payload[keys[:total]].to_i]
+      def build_row(fname, pct, payload, opts, keys)
+        row = [fname, pct, payload[keys.fetch(:covered)].to_i, payload.fetch(keys.fetch(:total)).to_i]
+        row << Misses.missed_for(payload, opts.fetch(:criterion)) if opts.fetch(:missing)
+        row
       end
 
       def format_row(fname, pct, covered, total, color)
         format("%<pct>s  %<covered>d/%<total>d  %<fname>s",
-               pct: SimpleCov::Color.colorize_percent(pct, format("%6.2f%%", pct), enabled: color),
-               covered: covered, total: total, fname: fname)
+          pct: Color.colorize_percent(pct, format("%6.2f%%", pct), enabled: color),
+          covered: covered, total: total, fname: fname)
       end
     end
   end

data/lib/simplecov/cli/usage.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Usage
+      extend self
+
+      def for(cli, command)
+        sections = text(cli).split("\n\n")
+        row = sections.fetch(1).lines.find { |line| line.match?(/\A  #{Regexp.escape(command)}[ \[]/) }
+        options = sections.select { |section| section_for?(section, command) }
+        ["Usage: simplecov #{command} [options]", row&.strip, *options].compact.join("\n\n")
+      end
+
+      def section_for?(section, command)
+        header = heading_of(section)
+        header.end_with?("options:") && header.delete_suffix("options:").split(%r{[\s/]+}).include?(command)
+      end
+
+      def heading_of(section)
+        section.lines.first.to_s.strip
+      end
+
+      # A method rather than a constant so its default paths resolve at call time
+      # against the active `.simplecov`.
+      def text(cli)
+        <<~USAGE
+          Usage: simplecov <command> [options]
+
+          Commands:
+            run <command...>          Execute <command> with SimpleCov pre-loaded
+                                      (works without a test_helper hook)
+            coverage <path>           Print coverage stats for the given file
+            show <path>               Print the file's source annotated with hit counts and misses
+            report                    Print the overall summary and group totals
+            status                    Report freshness: age, commit distance, recorded tests
+            history                   Print the recorded coverage trend, a sparkline per criterion
+            badge                     Render the coverage percent as an SVG badge
+            uncovered                 List the lowest-coverage files
+            tests [<path>[:<line>]]   List recorded tests for a file or line (needs track_tests)
+            affected                  List test files touching code changed since a git ref (needs track_tests)
+            merge <files...>          Merge multiple .resultset.json files
+            diff <baseline>           Show per-file coverage delta vs baseline
+            patch                     Show coverage of the lines a change touched
+            ratchet                   Rewrite the per-file coverage baseline, only ever tightening
+            dead-code                 Cross production coverage with the report to find dead code
+            open                      Open the HTML report in the default browser
+            serve                     Serve the coverage report over HTTP
+            watch <command...>        Re-run <command> on save and live-reload the served report
+            clean                     Remove the coverage report directory
+            completions <shell>       Emit the completion script for fish, bash, or zsh
+            help                      Show this message
+            version                   Print the version (also --version / -v)
+
+          Every command answers `--help` / `-h`. Default paths follow a project's
+          `.simplecov` SimpleCov.coverage_dir (#{cli.coverage_dir} for this run).
+
+          coverage / show / report / status / uncovered / tests / affected / diff / patch / ratchet / dead-code options:
+            --input PATH              Read from PATH instead of #{cli.default_input}
+            --no-color                Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+
+          coverage options:
+            --json                    Print the file's JSON entry verbatim
+
+          show options:
+            --uncovered-only          Print only <path>:<ranges> of the missed lines
+            --json                    Emit path, missed lines, per-line hits, and markers as JSON
+
+          report options:
+            --json                    Emit totals and group sections as JSON
+
+          status options:
+            --json                    Emit the freshness facts as a JSON object
+
+          history options:
+            --input PATH              Read from PATH instead of the coverage directory's .history.json
+            --file PATH               Follow one file's trajectory instead of the totals
+            --json                    Emit the entries (or the file's trajectory) as JSON
+            --no-color                Disable colorized deltas (also honors NO_COLOR / FORCE_COLOR env)
+
+          badge options:
+            --input PATH              Read from PATH instead of #{cli.default_input}
+            --output PATH             Write the badge to PATH instead of stdout
+            --criterion C             line, branch, or method (default: line)
+            --label TEXT              The badge's left-side text (default: the criterion's, like "line coverage")
+
+          uncovered options:
+            --threshold N             Only show files below N% coverage
+            --top N                   Show at most N files (default: 10)
+            --criterion C             line, branch, or method (default: line)
+            --missing                 Append the missed line ranges to each row
+            --annotate KIND           Emit CI annotations instead of rows: github, gitlab, rdjson, azure, teamcity, or buildkite
+            --json                    Emit results as a JSON array (for CI)
+
+          tests options:
+            --redundant               List only tests whose covered lines other tests also cover
+            --json                    Emit the test ids as a JSON array
+
+          affected options:
+            --base REF                Diff against the merge base of REF and HEAD (default: origin's HEAD, else main)
+            --run <command...>        Run <command> (all args after --run) with the selection appended, or bare on a full-suite fallback, exiting with the command's status
+            --json                    Emit {full_suite, triggers, tests} as a JSON object
+
+          merge options:
+            --output PATH             Write merged resultset to PATH (default: #{cli.default_resultset})
+            --honor-timeout           Drop entries older than merge_timeout
+            --dry-run                 Print what would be written without writing
+            -q, --quiet               Suppress the success status line
+
+          diff options:
+            --fail-on-drop            Exit non-zero when any file's coverage dropped vs baseline (deletions don't count)
+            --json                    Emit results as a JSON array (for CI)
+            --threshold N             Only show files whose absolute delta in any criterion is at least N%
+
+          patch options:
+            --base REF                Diff against the merge-base of REF for the touched lines (default: origin's HEAD, else main, or in CI the PR's target branch)
+            --minimum N               Exit non-zero when patch coverage on any measured criterion is below N%
+            --find-renames            Follow a renamed file instead of counting the moved file as all-new
+            --annotate KIND           Emit CI annotations instead of rows: github, gitlab, rdjson, azure, teamcity, or buildkite
+            --json                    Emit results as a JSON array (for CI)
+
+          dead-code options:
+            --production PATH         The production coverage file a SimpleCov::Production sink wrote (default: the project's `production_coverage`, required when none is configured)
+            --untested-in-production  Print code production runs that no test covers, instead of the dead rows
+            --json                    Emit every category (dead, possibly dead, untested in production) as JSON
+
+          ratchet options:
+            --baseline PATH           The baseline file to rewrite (default: the project's `baseline_file`, .simplecov_baseline.yml)
+            --init                    Regenerate from scratch: add entries for new files and reset every floor to the current state
+            --dry-run                 Print what would change without writing
+            --json                    Emit the summary (tightened / pruned / regressed entries) as JSON
+
+          open options:
+            --report PATH             Open PATH instead of #{cli.default_report}
+
+          serve options:
+            --port N                  Bind to port N (default: random open port)
+            --host HOST               Bind to HOST (default: 127.0.0.1)
+
+          watch options:
+            --port N                  Bind to port N (default: random open port)
+            --host HOST               Bind to HOST (default: 127.0.0.1)
+            --interval SECONDS        Poll the tracked files this often (default: 0.5)
+            --open                    Open the served report in the default browser
+
+          clean options:
+            --dry-run                 Print what would be removed without deleting
+            -q, --quiet               Suppress status lines
+        USAGE
+      end
+    end
+  end
+end