simplecov 1.1.1 → 1.2.0

data/lib/simplecov/cli/diff/output.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Diff
+      module Output
+        STATUS_SUFFIX = {"added" => "(new file)", "removed" => "(removed)"}.freeze
+
+        extend self
+
+        def emit_text(stdout, rows, color)
+          if rows.empty?
+            stdout.puts("simplecov diff: no per-file coverage changes")
+          else
+            rows.each { |row| stdout.puts(format_row(row, color)) }
+          end
+        end
+
+        def format_row(row, color)
+          line = "  #{delta_parts(row, color).join("  ")}  #{row.fetch(:file)}"
+          suffix = STATUS_SUFFIX[row.fetch(:status)]
+          suffix ? "#{line}  #{suffix}" : line
+        end
+
+        def delta_parts(row, color)
+          [
+            format_delta(row.fetch(:line_delta), "lines", color),
+            (format_delta(row.fetch(:branch_delta), "branches", color) if row.fetch(:branch_delta).abs > EPSILON),
+            (format_delta(row.fetch(:method_delta), "methods", color) if row.fetch(:method_delta).abs > EPSILON)
+          ].compact
+        end
+
+        # Deltas are sign-based, not threshold-based: a +5% bump is green and a -5%
+        # drop is red, regardless of where the absolute coverage level lands. A drop
+        # carries its own minus, so the sign is a prefix a rise has and a drop has
+        # not.
+        def format_delta(delta, label, color)
+          sign = "+" if delta.positive?
+          text = format("%<sign>s%<delta>6.2f%% %<label>s", sign: sign, delta: delta, label: label)
+          Color.colorize(text, delta.negative? ? :red : :green, enabled: color)
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/diff.rb

@@ -3,50 +3,52 @@
 require "json"
 require "optparse"
 require_relative "command_helpers"
+require_relative "diff/output"
 
 module SimpleCov
   module CLI
-    # `simplecov diff <baseline>` — print per-file coverage deltas between
-    # coverage.json (--input) and a baseline coverage.json
-    # checked in alongside the suite. Only files whose coverage moved
-    # are listed; --fail-on-drop exits non-zero when any file regressed,
-    # so this composes with CI as a "coverage of this PR didn't drop"
-    # gate. Resolves the long-standing "diff coverage" feature request.
+    # `simplecov diff <baseline>`: per-file coverage deltas between coverage.json
+    # and a baseline coverage.json checked in alongside the suite. Only files
+    # whose coverage moved are listed, and `--fail-on-drop` exits non-zero when
+    # any file regressed, so this composes as a "coverage of this PR didn't drop"
+    # gate.
     module Diff
       extend CommandHelpers
 
-      EPSILON = 0.005 # tolerance below which a delta is considered noise
+      # Tolerance below which a delta is considered noise.
+      EPSILON = 0.005
 
-      STATUS_SUFFIX = {"added" => "(new file)", "removed" => "(removed)"}.freeze
-
-    module_function
+      extend self
 
       def run(args, stdout:, stderr:, **)
         opts = parse(args, stderr)
         return 1 unless opts
 
-        rows = compute_rows(opts[:current], opts[:baseline], opts[:threshold])
-        rows.sort_by! { |row| row[:line_delta] }
-        if opts[:json]
+        rows = compute_rows(opts.fetch(:current), opts.fetch(:baseline), opts.fetch(:threshold))
+        rows.sort_by! { |row| row.fetch(:line_delta) }
+        if opts.fetch(:json)
           stdout.puts(JSON.pretty_generate(rows))
         else
-          emit_text(stdout, rows, SimpleCov::CLI.color_enabled?(opts, stdout))
+          Output.emit_text(stdout, rows, CLI.color_enabled?(opts, stdout))
         end
-        opts[:fail_on_drop] && coverage_drop?(rows) ? 1 : 0
+        (opts.fetch(:fail_on_drop) && coverage_drop?(rows)) ? 1 : 0
       end
 
       def parse(args, stderr)
         opts = parse_flags(args)
-        return stderr.puts("simplecov diff: missing baseline argument") && nil if opts[:rest].empty?
+        if opts.fetch(:rest).empty?
+          stderr.puts("simplecov diff: missing baseline argument")
+          return nil
+        end
 
-        opts[:baseline] = load_coverage(opts[:rest].first, stderr) or return nil
-        opts[:current]  = load_coverage(opts[:input], stderr) or return nil
+        opts[:baseline] = load_coverage(opts.fetch(:rest).first, stderr) or return nil
+        opts[:current] = load_coverage(opts.fetch(:input), stderr) or return nil
         opts
       end
 
       def parse_flags(args)
         opts, rest = parse_common(args, fail_on_drop: false, threshold: 0.0) do |o, options|
-          o.on("--fail-on-drop")       { options[:fail_on_drop] = true }
+          o.on("--fail-on-drop") { options[:fail_on_drop] = true }
           o.on("--threshold N", Float) { |v| options[:threshold] = v }
         end
         opts.merge(rest: rest)
@@ -59,9 +61,8 @@ module SimpleCov
         normalize_keys(coverage)
       end
 
-      # Strip a leading slash so coverage.json files written before the
-      # `project_filename` change (keys like "/lib/foo.rb") still diff
-      # cleanly against newer reports (keys like "lib/foo.rb").
+      # Strips a leading slash so coverage.json files written before the
+      # `project_filename` change still diff cleanly against newer reports.
       def normalize_keys(coverage)
         coverage.transform_keys { |key| key.delete_prefix("/") }
       end
@@ -71,17 +72,15 @@ module SimpleCov
         files.filter_map { |fname| compute_row(fname, current[fname], baseline[fname], threshold) }
       end
 
-      # EPSILON keeps float noise out regardless of threshold; the
-      # threshold itself is inclusive, so a file that moved exactly N%
-      # is listed under `--threshold N`, matching the "at least N%" the
-      # usage text promises.
+      # The threshold is inclusive, so a file that moved exactly N% is listed under
+      # `--threshold N`, matching the "at least N%" the usage text promises.
       def compute_row(fname, current_payload, baseline_payload, threshold)
         deltas = compute_deltas(current_payload, baseline_payload)
         floor = threshold.abs
         return nil unless deltas.values.any? { |delta| delta.abs > EPSILON && delta.abs >= floor }
 
         {file: fname, status: status_for(current_payload, baseline_payload),
-         line_delta: deltas[:line], branch_delta: deltas[:branch], method_delta: deltas[:method]}
+         line_delta: deltas.fetch(:line), branch_delta: deltas.fetch(:branch), method_delta: deltas.fetch(:method)}
       end
 
       def compute_deltas(current_payload, baseline_payload)
@@ -91,56 +90,25 @@ module SimpleCov
       end
 
       def status_for(current_payload, baseline_payload)
-        return "added"   if baseline_payload.nil?
+        return "added" if baseline_payload.nil?
         return "removed" if current_payload.nil?
 
         "changed"
       end
 
       def pct_for(fields, payload)
-        return 0.0 unless payload.is_a?(Hash) && payload[fields[:total]].to_i.positive?
-
-        payload[fields[:percent]].to_f
-      end
-
-      def emit_text(stdout, rows, color)
-        return stdout.puts("simplecov diff: no per-file coverage changes") if rows.empty?
+        return 0.0 unless payload.instance_of?(Hash) && payload[fields.fetch(:total)].to_i.positive?
 
-        rows.each { |row| stdout.puts(format_row(row, color)) }
+        payload[fields.fetch(:percent)].to_f
       end
 
-      def format_row(row, color)
-        line = "  #{delta_parts(row, color).join('  ')}  #{row[:file]}"
-        suffix = STATUS_SUFFIX[row[:status]]
-        suffix ? "#{line}  #{suffix}" : line
-      end
-
-      def delta_parts(row, color)
-        [
-          format_delta(row[:line_delta], "lines", color),
-          (format_delta(row[:branch_delta], "branches", color) if row[:branch_delta].abs > EPSILON),
-          (format_delta(row[:method_delta], "methods", color)  if row[:method_delta].abs > EPSILON)
-        ].compact
-      end
-
-      # A removed file's deltas are all -baseline%, but deleting a
-      # covered file (dead code cleanup) is not a coverage regression,
-      # so removed rows never trip the --fail-on-drop gate. Drops are
-      # gated on EPSILON like row inclusion and display: a row listed
-      # for a gain in one criterion must not fail the run over float
-      # noise in another, invisible in the printed output.
+      # A removed file's deltas are all -baseline%, but deleting a covered file is
+      # not a coverage regression, so removed rows never trip the gate. Drops are
+      # gated on EPSILON like row inclusion and display, so a row listed for a gain
+      # in one criterion cannot fail the run over float noise in another.
       def coverage_drop?(rows)
-        rows.reject { |row| row[:status] == "removed" }
-            .any? { |row| row.values_at(:line_delta, :branch_delta, :method_delta).min < -EPSILON }
-      end
-
-      # Deltas are sign-based, not threshold-based: a +5% bump is good
-      # (green) and a -5% drop is bad (red), regardless of where the
-      # absolute coverage level lands.
-      def format_delta(delta, label, color)
-        sign = delta.positive? ? "+" : ""
-        text = format("%<sign>s%<delta>6.2f%% %<label>s", sign: sign, delta: delta, label: label)
-        SimpleCov::Color.colorize(text, delta.negative? ? :red : :green, enabled: color)
+        rows.reject { |row| row.fetch(:status).eql?("removed") }
+          .any? { |row| row.fetch_values(:line_delta, :branch_delta, :method_delta).min < -EPSILON }
       end
     end
   end

data/lib/simplecov/cli/dotfile.rb

@@ -4,14 +4,13 @@ require "pathname"
 
 module SimpleCov
   module CLI
-    # Loads a project's `.simplecov` config file purely to read
-    # `coverage_dir` from it, with `SimpleCov.start` and the at_exit
-    # hook installer neutered so the load doesn't trigger coverage
-    # tracking. Used by the CLI to default `--input` / `--report`
-    # paths to whatever the project's dotfile declares, without making
-    # every read-only subcommand pay for actually starting Coverage.
+    # Loads a project's `.simplecov` config file purely to read configuration
+    # from it, with `SimpleCov.start` and the at_exit hook installer neutered so
+    # the load doesn't trigger coverage tracking. Used by the CLI to default
+    # paths to whatever the project's dotfile declares, without making every
+    # read-only subcommand pay for actually starting Coverage.
     module Dotfile
-    module_function
+      extend self
 
       def coverage_dir
         dotfile = find
@@ -19,37 +18,73 @@ module SimpleCov
 
         with_simplecov_loaded { read_from(dotfile) }
       rescue ScriptError, StandardError => e
-        # simplecov:disable — defensive fallback for a bad dotfile; never
-        # fires in the project's own dogfood run. ScriptError covers the
-        # SyntaxError a malformed dotfile raises from `load` (it is not a
-        # StandardError) along with LoadError; StandardError covers the
-        # rest (EACCES, errors raised by the dotfile's own code, etc.).
-        warn "simplecov: failed to read coverage_dir from #{dotfile}: #{e.class}: #{e.message}"
+        # ScriptError covers the SyntaxError a malformed dotfile raises from
+        # `load` (it is not a StandardError) along with LoadError; StandardError
+        # covers the rest.
+        warn "simplecov: failed to read coverage_dir from #{dotfile}: #{e.class}: #{e}"
         "coverage"
-        # simplecov:enable
       end
 
-      # Load the dotfile, snapshot+restore `SimpleCov.coverage_dir` so we
-      # don't quietly clobber it in a host process that's already
-      # configured (e.g. when the CLI is exercised inline by simplecov's
-      # own spec suite). The snapshot is intentionally narrow: a dotfile
-      # can still mutate other SimpleCov configuration (filters, groups,
-      # formatters, command_name, ...) via `SimpleCov.configure` or
-      # `SimpleCov.start { ... }` blocks. The CLI normally runs as a
-      # top-level process where that's harmless; callers driving it from
-      # inside a Ruby host that cares about isolation should arrange that
-      # themselves.
+      # Read from `.simplecov` the way `coverage_dir` is, so a project that moved
+      # its baseline doesn't need `--baseline` on every ratchet.
+      def baseline_file
+        dotfile = find
+        return Baseline::DEFAULT_FILENAME unless dotfile
+
+        with_simplecov_loaded { read_baseline_file_from(dotfile) }
+      rescue ScriptError, StandardError => e
+        warn "simplecov: failed to read baseline_file from #{dotfile}: #{e.class}: #{e}"
+        Baseline::DEFAULT_FILENAME
+      end
+
+      # Nil when there is no dotfile, the dotfile names no store, or it cannot be
+      # read: unlike the other reads there is no sensible fallback path, and the
+      # command's own missing-store error is the right answer.
+      def production_coverage
+        dotfile = find
+        return nil unless dotfile
+
+        with_simplecov_loaded { read_production_coverage_from(dotfile) }
+      rescue ScriptError, StandardError => e
+        # `warn` answers nil, which is this reader's whole fallback.
+        warn "simplecov: failed to read production_coverage from #{dotfile}: #{e.class}: #{e}"
+      end
+
+      def read_production_coverage_from(dotfile)
+        snapshot = SimpleCov.instance_variable_get(:@production_coverage) #: String?
+        load_with_start_neutered(dotfile)
+        SimpleCov.production_coverage
+      ensure
+        # @type var snapshot: String?
+        SimpleCov.instance_variable_set(:@production_coverage, snapshot)
+      end
+
+      def read_baseline_file_from(dotfile)
+        snapshot = SimpleCov.instance_variable_get(:@baseline_file) #: String?
+        load_with_start_neutered(dotfile)
+        SimpleCov.baseline_file
+      ensure
+        # @type var snapshot: String?
+        SimpleCov.instance_variable_set(:@baseline_file, snapshot)
+      end
+
+      # Snapshot and restore `SimpleCov.coverage_dir` so we don't quietly clobber
+      # it in a host process that's already configured. The snapshot is
+      # intentionally narrow: a dotfile can still mutate other configuration
+      # via `SimpleCov.configure` or `SimpleCov.start { ... }` blocks.
       def read_from(dotfile)
         snapshot = SimpleCov.instance_variable_get(:@coverage_dir) #: String?
         load_with_start_neutered(dotfile)
         SimpleCov.coverage_dir
       ensure
-        # Restore even when the load raises, so a bad dotfile doesn't
-        # leave a host process's configured dir clobbered.
+        # Restored even when the load raises, so a bad dotfile doesn't leave a
+        # host process's configured dir clobbered.
         # @type var snapshot: String?
         SimpleCov.instance_variable_set(:@coverage_dir, snapshot)
       end
 
+      # The nearest `.simplecov` at or above the working directory, or nil, which
+      # is what the walk itself answers once it breaks at the filesystem root.
       def find
         dir = Pathname.new(Dir.pwd)
         loop do
@@ -59,38 +94,48 @@ module SimpleCov
 
           dir = dir.parent
         end
-        nil
       end
 
       def with_simplecov_loaded
         previous_no_defaults = ENV.fetch("SIMPLECOV_NO_DEFAULTS", nil) #: String?
-        previous_cli         = ENV.fetch("SIMPLECOV_CLI", nil) #: String?
+        previous_cli = ENV.fetch("SIMPLECOV_CLI", nil) #: String?
         ENV["SIMPLECOV_NO_DEFAULTS"] = "1"
         # SIMPLECOV_CLI lets a project's `.simplecov` opt some config into
-        # CLI-only behavior — e.g. simplecov itself sets `coverage_dir`
-        # to the dogfood path here but skips that for descendants.
+        # CLI-only behavior: simplecov itself sets `coverage_dir` to the dogfood
+        # path here but skips that for descendants.
         ENV["SIMPLECOV_CLI"] = "1"
-        require "simplecov"
+        load_simplecov
         yield
       ensure
         # @type var previous_no_defaults: String?
         # @type var previous_cli: String?
         ENV["SIMPLECOV_NO_DEFAULTS"] = previous_no_defaults
-        ENV["SIMPLECOV_CLI"]         = previous_cli
+        ENV["SIMPLECOV_CLI"] = previous_cli
+      end
+
+      # The deferred require exists for a standalone CLI process that has not
+      # loaded simplecov yet. It must happen inside the env guard above, so a
+      # first load here skips the default profile chain.
+      def load_simplecov
+        require "simplecov"
       end
 
-      # Load `path` with `SimpleCov.start` and the at_exit installer
-      # turned into no-ops, so a project whose dotfile calls
-      # `SimpleCov.start` doesn't trigger Coverage just because we asked
-      # for `coverage_dir`. Config inside any `SimpleCov.start { ... }`
-      # block still runs.
+      # A constant rather than a block written at the call site, where an empty
+      # block and one answering nil are the same thing to every caller and so
+      # to every test.
+      NEUTERED = proc {}
+
+      # Load `path` with `SimpleCov.start` and the at_exit installer turned into
+      # no-ops, so a project whose dotfile calls `SimpleCov.start` doesn't
+      # trigger Coverage just because we asked for `coverage_dir`. Config
+      # inside any `SimpleCov.start { ... }` block still runs.
       def load_with_start_neutered(path)
         klass = SimpleCov.singleton_class
         names = %i[start_tracking install_at_exit_hook]
         stash = names.to_h { |name| [name, klass.instance_method(name)] } #: Hash[Symbol, UnboundMethod]
         # define_method over an existing method emits a "method redefined"
         # warning under $VERBOSE; the override and restore are intentional.
-        silence_verbose { names.each { |name| klass.define_method(name) { nil } } }
+        silence_verbose { names.each { |name| klass.define_method(name, &(_ = NEUTERED)) } }
         load path
       ensure
         # @type var stash: Hash[Symbol, UnboundMethod]

data/lib/simplecov/cli/git.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module SimpleCov
+  module CLI
+    # The git plumbing the change-aware subcommands share: safe capture, the
+    # repository toplevel, ref hygiene, and the default base ref.
+    module Git
+      extend self
+
+      # [stdout, first stderr line, success]. A spawn failure reads as an
+      # unsuccessful run whose stdout is nil, so callers can tell "git ran and
+      # refused" from "git never ran".
+      def capture(*argv)
+        stdout, stderr, status = Open3.capture3("git", *argv)
+        [stdout, stderr.lines.first.to_s.strip, status.success?]
+      rescue => e
+        [nil, e.message, false]
+      end
+
+      def toplevel
+        stdout, _detail, success = capture("rev-parse", "--show-toplevel")
+        (_ = stdout).chomp if success
+      end
+
+      # A git ref can never begin with "-", so one that does would be read by git
+      # as an option instead of a revision.
+      def option_like_ref?(ref)
+        ref.start_with?("-")
+      end
+
+      # The branch origin's HEAD points at, so master and trunk repositories work
+      # bare, falling back to main where no origin HEAD is recorded.
+      def default_base
+        stdout, _detail, success = capture("symbolic-ref", "--short", "refs/remotes/origin/HEAD")
+        success ? (_ = stdout).chomp.delete_prefix("origin/") : "main"
+      end
+    end
+  end
+end

data/lib/simplecov/cli/history/output.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module History
+      # Renders the trend: Unicode sparklines scaled to each series' own range,
+      # with the numbers beside them carrying the absolute scale.
+      module Output
+        BARS = %w[▁ ▂ ▃ ▄ ▅ ▆ ▇ █].freeze
+
+        CRITERIA_ORDER = %w[line branch method].freeze
+
+        extend self
+
+        def emit(stdout, opts, entries, color:)
+          return emit_json(stdout, opts, entries) if opts.fetch(:json)
+          return stdout.puts("simplecov history: no recorded runs in #{opts.fetch(:input)}") if entries.empty?
+
+          if opts.fetch(:file)
+            emit_file(stdout, opts, entries, color)
+          else
+            emit_totals(stdout, opts, entries, color)
+          end
+        end
+
+        def emit_totals(stdout, opts, entries, color)
+          stdout.puts("Coverage history: #{opts.fetch(:input)} (#{pluralize(entries.length, "run")})")
+          stdout.puts
+          emit_criteria_views(stdout, entries, color, "totals")
+        end
+
+        def emit_file(stdout, opts, entries, color)
+          file = opts.fetch(:file)
+          stdout.puts("Coverage history for #{file} (#{pluralize(entries.length, "run")})")
+          stdout.puts
+          emit_criteria_views(stdout, entries, color, "files", file)
+        end
+
+        def emit_criteria_views(stdout, entries, color, *path)
+          criteria = measured_criteria(entries, path)
+          emit_sparklines(stdout, entries, criteria, color, path)
+          stdout.puts
+          emit_rows(stdout, entries) { |entry| percents_cell(entry, criteria, path) }
+        end
+
+        def emit_sparklines(stdout, entries, criteria, color, path)
+          width = criteria.map(&:length).max
+          criteria.each do |criterion|
+            series = entries.map { |entry| numeric(entry.dig(*path, criterion)) }
+            stdout.puts("  #{criterion.ljust(width)}  #{sparkline(series)}  #{trend(series, color)}")
+          end
+        end
+
+        def emit_rows(stdout, entries)
+          width = entries.map { |entry| branch_of(entry).length }.max
+          entries.each do |entry|
+            commit = (entry["commit"] || "-")[0, 7].ljust(7)
+            stdout.puts("  #{entry["created_at"]}  #{branch_of(entry).ljust(width)}  #{commit}  #{yield(entry)}")
+          end
+        end
+
+        def branch_of(entry)
+          entry["branch"] || "-"
+        end
+
+        def percents_cell(entry, criteria, path)
+          cell = criteria.filter_map do |criterion|
+            value = numeric(entry.dig(*path, criterion))
+            "#{criterion} #{value}%" if value
+          end.join("  ")
+          cell.empty? ? "-" : cell
+        end
+
+        # Min-max scaled block characters, one per run, a space where the series has
+        # no value for that run. A flat series renders at mid height: direction of
+        # travel is the message, and a flat line says it plainly. A series with no
+        # numbers at all is all gaps, and answering that outright keeps the scale off
+        # a range it doesn't have.
+        def sparkline(series)
+          numeric = series.compact
+          return " " * series.length if numeric.empty?
+
+          min = numeric.min
+          span = numeric.max - min.to_f
+          series.map { |value| value.nil? ? " " : bar(value, min, span) }.join
+        end
+
+        def bar(value, min, span)
+          span.zero? ? BARS.fetch(3) : BARS.fetch(((value - min) / span * (BARS.length - 1)).round)
+        end
+
+        def trend(series, color)
+          numeric = series.compact
+          first = numeric.first
+          last = numeric.last
+          delta = (last - first).round(2)
+          sign = "+" unless delta.negative?
+          delta_text = Color.colorize("(#{sign}#{delta})", delta.negative? ? :red : :green, enabled: color)
+          "#{first}% → #{last}%  #{delta_text}"
+        end
+
+        def emit_json(stdout, opts, entries)
+          return stdout.puts(JSON.generate(entries)) unless opts.fetch(:file)
+
+          rows = entries.map do |entry|
+            percents = entry.dig("files", opts.fetch(:file))
+            {created_at: entry["created_at"], branch: entry["branch"], commit: entry["commit"],
+             percents: (percents if percents.instance_of?(Hash))}
+          end
+          stdout.puts(JSON.generate(rows))
+        end
+
+        # Criteria some run recorded a number for, in canonical order, so a criterion
+        # enabled midway still gets its sparkline. One no run recorded is left out:
+        # an all-gaps sparkline has no trend to read off it.
+        def measured_criteria(entries, path)
+          CRITERIA_ORDER.select do |criterion|
+            entries.any? do |entry|
+              percents = entry.dig(*path)
+              percents.instance_of?(Hash) && numeric(percents[criterion])
+            end
+          end
+        end
+
+        def numeric(value)
+          value if value.is_a?(Numeric)
+        end
+
+        def pluralize(number, noun)
+          "#{number} #{noun}#{"s" unless number.eql?(1)}"
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/history.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "command_helpers"
+require_relative "history/output"
+require_relative "../history"
+
+module SimpleCov
+  module CLI
+    # `simplecov history`: the recorded coverage trend in the terminal, a
+    # sparkline per measured criterion with the run rows beneath, and
+    # `--file PATH` for one file's trajectory instead of the totals.
+    module History
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args, stderr) or return 1
+        entries = load_entries(opts.fetch(:input), stderr) or return 1
+        return 1 unless file_recorded?(entries, opts, stderr)
+
+        Output.emit(stdout, opts, entries, color: CLI.color_enabled?(opts, stdout))
+        0
+      end
+
+      def parse(args, stderr)
+        opts, rest = parse_common(args, input: default_input, file: nil) do |parser, options|
+          parser.on("--file PATH") { |v| options[:file] = v }
+        end
+        return error_nil(stderr, "unexpected argument #{rest.first.inspect}") unless rest.empty?
+
+        opts
+      end
+
+      # The history file, not coverage.json: this command reads the sibling
+      # artifact the exit tasks append to.
+      def default_input
+        File.join(CLI.coverage_dir, ".history.json")
+      end
+
+      def load_entries(path, stderr)
+        document = JSON.parse(File.read(path))
+        entries = document.dig(SimpleCov::History::ENVELOPE, "entries") if document.instance_of?(Hash)
+        return entries if entries.instance_of?(Array)
+
+        error_nil(stderr, "#{path} is not a SimpleCov history file")
+      rescue Errno::ENOENT
+        error_nil(stderr, "#{path} not found (the history is recorded automatically each time a suite reports)")
+      rescue JSON::ParserError => e
+        error_nil(stderr, "#{path} is not valid JSON (#{e.message.lines.first.to_s.strip})")
+      rescue SystemCallError => e
+        error_nil(stderr, "#{path} could not be read (#{e})")
+      end
+
+      # A `--file` for a path no entry recorded deserves a loud answer, not an
+      # empty sparkline that reads as "0% forever".
+      def file_recorded?(entries, opts, stderr)
+        file = opts.fetch(:file)
+        return true unless file
+        return true if entries.any? { |entry| entry.instance_of?(Hash) && entry.dig("files", file).instance_of?(Hash) }
+
+        error(stderr, "no recorded coverage for #{file} in #{opts.fetch(:input)}")
+        false
+      end
+    end
+  end
+end