simplecov 0.22.0 → 1.3.0

data/lib/simplecov/cli/dotfile.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module SimpleCov
+  module CLI
+    # 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
+      extend self
+
+      def coverage_dir
+        dotfile = find
+        return "coverage" unless dotfile
+
+        with_simplecov_loaded { read_from(dotfile) }
+      rescue ScriptError, StandardError => e
+        # 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"
+      end
+
+      # 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
+        # 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
+          candidate = dir.join(".simplecov")
+          return candidate.to_s if candidate.exist?
+          break if dir.root?
+
+          dir = dir.parent
+        end
+      end
+
+      def with_simplecov_loaded
+        previous_no_defaults = ENV.fetch("SIMPLECOV_NO_DEFAULTS", 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: simplecov itself sets `coverage_dir` to the dogfood
+        # path here but skips that for descendants.
+        ENV["SIMPLECOV_CLI"] = "1"
+        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
+      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
+
+      # 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, &(_ = NEUTERED)) } }
+        load path
+      ensure
+        # @type var stash: Hash[Symbol, UnboundMethod]
+        # @type var klass: Class
+        silence_verbose { stash.each { |name, method| klass.define_method(name, method) } }
+      end
+
+      def silence_verbose
+        previous = $VERBOSE #: bool?
+        $VERBOSE = nil
+        yield
+      ensure
+        # @type var previous: bool?
+        $VERBOSE = previous
+      end
+    end
+  end
+end

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

data/lib/simplecov/cli/merge.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../atomic_file"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    # `simplecov merge <files...>`: wraps `SimpleCov::ResultMerger` so a CI
+    # matrix that produces one .resultset.json per worker can stitch them
+    # together from the shell instead of dropping a Rake task into every project.
+    module Merge
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args)
+        return error(stderr, "missing input files") if opts.fetch(:files).empty?
+
+        parsed = parse_inputs(opts.fetch(:files), stderr)
+        return 1 unless parsed
+
+        warn_about_duplicate_command_names(parsed, stderr)
+        result = result_merger.merge_results(*opts.fetch(:files), ignore_timeout: !opts.fetch(:honor_timeout))
+        return error(stderr, "no mergeable results in input files") unless result
+
+        commit(opts, result, stdout)
+        0
+      end
+
+      # Loaded here rather than at the top of the file, so the read-only
+      # subcommands never pay for ResultMerger and its Coverage runtime guard.
+      def result_merger
+        require "simplecov"
+        ResultMerger
+      end
+
+      def commit(opts, result, stdout)
+        verb = opts.fetch(:dry_run) ? "would write" : "wrote"
+        write(opts.fetch(:output), result) unless opts.fetch(:dry_run)
+        stdout.puts("simplecov merge: #{verb} #{opts.fetch(:output)}") unless opts.fetch(:quiet)
+      end
+
+      def parse(args)
+        opts = {output: CLI.default_resultset, honor_timeout: false, dry_run: false, quiet: false}
+        files =
+          build_parser do |o|
+            o.on("--output PATH") { |v| opts[:output] = v }
+            o.on("--honor-timeout") { opts[:honor_timeout] = true }
+            o.on("--dry-run") { opts[:dry_run] = true }
+            quiet_option(o, opts)
+          end.parse(args)
+        opts.merge(files: files)
+      end
+
+      # Validating every input up front turns ResultMerger's generic "no mergeable
+      # results" into a message that points at the specific input causing it.
+      def parse_inputs(files, stderr)
+        parsed = {} #: Hash[String, Hash[String, untyped]]
+        files.each_with_object(parsed) do |path, memo|
+          data = parse_input(path, stderr) or return nil
+
+          memo[path] = data
+        end
+      end
+
+      # Read first and classify by the exception: an exist?-then-read pair is racy,
+      # and rescuing only ENOENT crashed with a backtrace on a directory or an
+      # unreadable file.
+      def parse_input(path, stderr)
+        data = JSON.parse(File.read(path))
+        return data if data.instance_of?(Hash) && !data.empty?
+
+        parse_input_error(stderr, path, "has no resultset entries")
+      rescue Errno::ENOENT
+        parse_input_error(stderr, path, "not found")
+      rescue JSON::ParserError => e
+        parse_input_error(stderr, path, "isn't valid JSON (#{e})")
+      rescue SystemCallError => e
+        parse_input_error(stderr, path, "cannot be read (#{e.message.lines.first.to_s.rstrip})")
+      end
+
+      def parse_input_error(stderr, path, reason)
+        stderr.puts("simplecov merge: input file #{path.inspect} #{reason}")
+      end
+
+      # ResultMerger folds entries that share a command_name together with
+      # last-write-wins on the timestamp, which is easy to mistake for "no merge
+      # happened", so the overlap is surfaced.
+      def warn_about_duplicate_command_names(parsed, stderr)
+        files_per_command = {} #: Hash[String, Array[String]]
+        parsed.each do |path, data|
+          data.each_key { |command_name| (files_per_command[command_name] ||= []) << path }
+        end
+        files_per_command.each do |command_name, paths|
+          next if paths.size < 2
+
+          stderr.puts(duplicate_warning(command_name, paths))
+        end
+      end
+
+      def duplicate_warning(command_name, paths)
+        "simplecov merge: warning — command_name #{command_name.inspect} " \
+          "appears in #{paths.size} input files (#{paths.join(", ")}); " \
+          "entries will be merged"
+      end
+
+      def write(path, result)
+        AtomicFile.write(path, JSON.pretty_generate(result.to_hash))
+      end
+    end
+  end
+end

data/lib/simplecov/cli/open.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    module Open
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stderr:, **)
+        path = parse(args)
+        return error(stderr, "#{path} not found") unless File.exist?(path)
+
+        opener = browser_opener
+        return error(stderr, "no known opener for #{RbConfig::CONFIG.fetch("host_os")}") unless opener
+
+        system(*opener, path) ? 0 : 1
+      end
+
+      def parse(args)
+        path = CLI.default_report
+        build_parser do |o|
+          o.on("--report PATH") { |v| path = v }
+        end.parse(args)
+        path
+      end
+
+      # The argv for the platform's "open this file" command, or nil if the host OS
+      # isn't recognized. On Windows, `start` is a cmd.exe builtin rather than an
+      # executable, so it routes through `cmd /c`; the empty string is the
+      # window-title positional `start` takes before the path, so a quoted path
+      # isn't mis-parsed as the title.
+      def browser_opener
+        case RbConfig::CONFIG.fetch("host_os")
+        when /darwin/ then ["open"]
+        when /mswin|mingw|cygwin/ then ["cmd", "/c", "start", ""]
+        when /linux|bsd|solaris/ then ["xdg-open"]
+        end
+      end
+    end
+  end
+end