simplecov 1.1.1 → 1.3.0

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

@@ -7,59 +7,56 @@ require_relative "command_helpers"
 
 module SimpleCov
   module CLI
-    # `simplecov merge <files...>` — wrap 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. Requires the full simplecov library to be on the
-    # load path; lazy-required so the read-only subcommands above don't
-    # pay for ResultMerger (and its Coverage runtime guard).
+    # `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
 
-    module_function
+      extend self
 
       def run(args, stdout:, stderr:, **)
         opts = parse(args)
-        return error(stderr, "missing input files") if opts[:files].empty?
-        return 1 unless valid_inputs?(opts[:files], stderr)
+        return error(stderr, "missing input files") if opts.fetch(:files).empty?
 
-        require "simplecov"
-        result = SimpleCov::ResultMerger.merge_results(*opts[:files], ignore_timeout: !opts[:honor_timeout])
+        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
 
-      def commit(opts, result, stdout)
-        verb = opts[:dry_run] ? "would write" : "wrote"
-        write(opts[:output], result) unless opts[:dry_run]
-        stdout.puts("simplecov merge: #{verb} #{opts[:output]}") unless opts[:quiet]
+      # 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 valid_inputs?(files, stderr)
-        parsed = parse_inputs(files, stderr) or return false
-
-        warn_about_duplicate_command_names(parsed, stderr)
-        true
+      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: SimpleCov::CLI.default_resultset, honor_timeout: false, dry_run: false, quiet: false}
+        opts = {output: CLI.default_resultset, honor_timeout: false, dry_run: false, quiet: false}
         files =
-          OptionParser.new do |o|
+          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 }
-            o.on("-q", "--quiet") { opts[:quiet] = true }
+            quiet_option(o, opts)
           end.parse(args)
         opts.merge(files: files)
       end
 
-      # Validate every input file up-front and return a {path => parsed}
-      # hash. Surfacing per-file errors here turns ResultMerger's
-      # generic "no mergeable results" into a message that points at
-      # the specific input causing the failure.
+      # 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|
@@ -69,31 +66,29 @@ module SimpleCov
         end
       end
 
-      # Read first, classify by the exception: an exist?-then-read pair
-      # is racy, and rescuing only ENOENT crashed with a backtrace on a
-      # directory (EISDIR) or an unreadable file (EACCES).
+      # 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.is_a?(Hash) && !data.empty?
+        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.message})")
+        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.strip})")
+        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}")
-        nil
       end
 
-      # When two input files share a command_name, ResultMerger folds
-      # them together with last-write-wins on the timestamp — easy to
-      # mistake for "no merge happened." Surface the overlap so the
-      # operator can rename the workers or accept the merge knowingly.
+      # 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|
@@ -108,7 +103,7 @@ module SimpleCov
 
       def duplicate_warning(command_name, paths)
         "simplecov merge: warning — command_name #{command_name.inspect} " \
-          "appears in #{paths.size} input files (#{paths.join(', ')}); " \
+          "appears in #{paths.size} input files (#{paths.join(", ")}); " \
           "entries will be merged"
       end
 

data/lib/simplecov/cli/open.rb

@@ -5,42 +5,39 @@ require_relative "command_helpers"
 
 module SimpleCov
   module CLI
-    # `simplecov open [--report PATH]` — open the HTML report in the
-    # platform's default browser. Tiny QoL wrapper around `xdg-open` /
-    # `open` / `start` so users don't have to type a file:// URL.
     module Open
       extend CommandHelpers
 
-    module_function
+      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['host_os']}") unless 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 = SimpleCov::CLI.default_report
-        OptionParser.new do |o|
+        path = CLI.default_report
+        build_parser do |o|
           o.on("--report PATH") { |v| path = v }
         end.parse(args)
         path
       end
 
-      # Returns 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 (not an executable), so route 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.
+      # 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["host_os"]
-        when /darwin/             then ["open"]
+        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"]
+        when /linux|bsd|solaris/ then ["xdg-open"]
         end
       end
     end

data/lib/simplecov/cli/patch/changed_lines.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "../git"
+
+module SimpleCov
+  module CLI
+    module Patch
+      # Run `git diff --unified=0` against a base and parse the result into
+      # `{root:, changes: {path => [added line numbers] | :all}}`, where
+      # `root` is the repository toplevel the paths are relative to and
+      # `:all` marks an untracked file, whose every line is new.
+      module ChangedLines
+        # A `git diff --unified=0` hunk header. Only the new-file side is
+        # captured: removed lines cannot be covered.
+        HUNK_HEADER = /\A@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/
+
+        UNQUOTE = {
+          "\\" => "\\", '"' => '"', "n" => "\n", "t" => "\t", "r" => "\r",
+          "a" => "\a", "b" => "\b", "f" => "\f", "v" => "\v"
+        }.freeze
+
+        extend self
+
+        # nil signals "could not diff" (already reported); empty changes are a
+        # valid result meaning the change touched no lines at all. Everything
+        # runs against the repository toplevel rather than the cwd, because
+        # `--relative` from a subdirectory would exclude every change outside
+        # that subdirectory from a `--minimum` gate.
+        def call(base, find_renames:, stderr:)
+          root = git_toplevel
+          return report_git_error(stderr, base, nil) unless root
+
+          output, detail = git_diff(root, base, find_renames: find_renames)
+          return report_git_error(stderr, base, detail) unless output
+
+          # `scrub` keeps a non-UTF-8 content line from blowing up the regexp
+          # parse; hunk headers are pure ASCII.
+          changes = parse_diff(output.scrub) #: Hash[String, untyped]
+          untracked_files(root).each { |path| changes[path] = :all }
+          {root: root, changes: changes}
+        end
+
+        def git_toplevel
+          Git.toplevel
+        end
+
+        # `--merge-base <base>` diffs the merge base of <base> and the working
+        # tree against the working tree: the change reads as its own work even
+        # when <base> has moved on independently, and uncommitted edits count
+        # too. The rest pins the output against a user's git config so it can't
+        # skew the numbers, run code, or throw off the parse: `--no-ext-diff` /
+        # `--no-textconv` (either runs a configured command, and the latter also
+        # renumbers lines), `--no-color`, `core.quotePath=false` (emit non-ASCII
+        # paths literally, so they still match report keys),
+        # `--inter-hunk-context=0` (never merge hunks over unchanged lines,
+        # which would score those lines as touched), fixed `a/`/`b/` prefixes
+        # (so the `diff_path` strip can't be fooled by `diff.noprefix`), and
+        # `--no-renames` unless asked (so a moved file reads as all-new).
+        # stderr is kept out of the parsed stream and its first line returned as
+        # the failure detail, so "unknown revision" reaches the user.
+        def git_diff(root, base, find_renames:)
+          # Refusing an option-like ref keeps a `--base` value from being read by
+          # git as an option instead of a revision (`--output=FILE` writes to
+          # disk, `--line-prefix=` empties the diff so a `--minimum` gate passes).
+          return [nil, "a ref cannot begin with \"-\""] if Git.option_like_ref?(base)
+
+          argv = ["-C", root, "-c", "core.quotePath=false", "diff", "--unified=0",
+            "--no-color", "--no-ext-diff", "--no-textconv", "--inter-hunk-context=0",
+            "--dst-prefix=b/",
+            find_renames ? "--find-renames" : "--no-renames", "--merge-base", base, "--"]
+          stdout, detail, success = Git.capture(*argv)
+          [(stdout if success), detail]
+        end
+
+        # A brand-new file that was never `git add`ed appears in no diff, but its
+        # lines are this change's lines all the same, and skipping it would pass
+        # a `--minimum` gate over entirely unscored new code. A failure here
+        # contributes nothing rather than failing the run.
+        def untracked_files(root)
+          stdout, _detail, success = Git.capture("-C", root, "ls-files", "--others", "--exclude-standard", "-z")
+          success ? (_ = stdout).scrub.split("\0") : []
+        end
+
+        def report_git_error(stderr, base, detail)
+          reason = detail.to_s.empty? ? "is this a git working tree, and does the ref exist?" : detail
+          stderr.puts("simplecov patch: could not run `git diff` against #{base.inspect} (#{reason})")
+        end
+
+        # Split into per-file sections first so a file's `+++` header, its first,
+        # before any hunk, is what names the path. Inside a hunk an added line is
+        # itself `+`-prefixed, so a touched line whose own text begins with
+        # `++ ` renders as `+++ ...`; reading only the section's first `+++`
+        # keeps that content line from standing in as the header.
+        def parse_diff(output)
+          changes = {} #: Hash[String, Array[Integer]]
+          sections = output.split(/^(?=diff --git )/)
+          sections.each do |section|
+            path = section_path(section) or next
+            section.each_line do |line|
+              match = HUNK_HEADER.match(line)
+              record_hunk(changes, path, match) if match
+            end
+          end
+          changes
+        end
+
+        # `+++ /dev/null` (a deletion) yields nil.
+        def section_path(section)
+          header = section[/^\+\+\+ .+/]
+          header && diff_path(header)
+        end
+
+        def record_hunk(changes, path, match)
+          start = Integer(match[1])
+          count = match[2] ? Integer(match[2]) : 1
+          return if count.zero? # a pure-deletion hunk adds nothing
+
+          (changes[path] ||= []).concat((start...(start + count)).to_a)
+        end
+
+        def diff_path(line)
+          raw = unquote(line[4..].to_s.chomp)
+          # git's own literal token for an absent side, not this host's null
+          # device, so File::NULL (which is "NUL" on Windows) would be wrong.
+          return nil if raw.eql?("/dev/null") # rubocop:disable Style/FileNull
+
+          raw.sub(%r{\A[ab]/}, "")
+        end
+
+        # A path carrying a quote, backslash, or control character is emitted as
+        # `"b/lib/we\"ird.rb"` even under `core.quotePath=false` (which only
+        # covers non-ASCII), and left quoted it matches no coverage key.
+        def unquote(raw)
+          return raw unless raw.length >= 2 && raw.start_with?('"') && raw.end_with?('"')
+
+          # Unescaped as raw bytes: an octal escape is a bare byte, and mixing one
+          # into a UTF-8 string would raise mid-gsub.
+          unquoted = (_ = raw.b[1..-2]).gsub(/\\(?:[0-7]{1,3}|.)/) { |escape| unescape(escape) }
+          unquoted.force_encoding(raw.encoding).scrub
+        end
+
+        def unescape(escape)
+          body = _ = escape[1..]
+          body.match?(/\A[0-7]/) ? Integer(body, 8).chr : UNQUOTE.fetch(body, body)
+        end
+      end
+    end
+  end
+end