simplecov 0.22.0 → 1.3.0

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

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../annotations"
+
+module SimpleCov
+  module CLI
+    module Patch
+      module Output
+        OPTIONAL_CRITERIA = %i[branch method].freeze
+
+        CRITERIA = %i[line branch method].freeze
+
+        extend self
+
+        # One diagnostic per contiguous missed range per measured criterion, in the
+        # CI host's own annotation form. Totals and the empty-change notice stay
+        # off stdout: the exit status under --minimum is the verdict.
+        def annotate(stdout, rows, kind)
+          diagnostics = rows.flat_map do |row|
+            CRITERIA.flat_map do |criterion|
+              stats = row.fetch(criterion)
+              stats ? Annotations.diagnostics(row.fetch(:file), stats.fetch(:missing), criterion) : []
+            end
+          end
+          Annotations.emit(stdout, kind, diagnostics)
+        end
+
+        def emit(stdout, rows, opts)
+          if opts.fetch(:json)
+            stdout.puts(JSON.pretty_generate(json_rows(rows)))
+          else
+            emit_text(stdout, rows, CLI.color_enabled?(opts, stdout))
+          end
+        end
+
+        def emit_text(stdout, rows, color)
+          return stdout.puts("simplecov patch: no coverable lines changed") if rows.empty?
+
+          rows.sort_by! { |row| [pct(row.fetch(:line)), row.fetch(:file)] }
+          rows.each { |row| stdout.puts(format_row(row, color)) }
+          stdout.puts(format_total(rows, color))
+        end
+
+        def format_row(row, color)
+          line = "  #{criterion_cells(row, color).join("  ")}  #{row.fetch(:file)}"
+          note = missing_note(row)
+          note.empty? ? line : "#{line}  #{note}"
+        end
+
+        def criterion_cells(row, color)
+          cells = [criterion_cell("lines", row.fetch(:line), color)]
+          cells << criterion_cell("branches", row.fetch(:branch), color) if measured?(row.fetch(:branch))
+          cells << criterion_cell("methods", row.fetch(:method), color) if measured?(row.fetch(:method))
+          cells
+        end
+
+        # A "lines" cell always, "branches" and "methods" cells only when the
+        # touched lines actually carried one: a hollow 0/0 cell is noise.
+        def criterion_cell(label, stats, color)
+          percent = pct(stats)
+          cell = Color.colorize(format("%6.2f%%", percent), (percent >= 100) ? :green : :red, enabled: color)
+          "#{cell} (#{stats.fetch(:covered)}/#{stats.fetch(:relevant)}) #{label}"
+        end
+
+        def missing_note(row)
+          parts = [] #: Array[String]
+          parts << "missing #{ranges(row.fetch(:line).fetch(:missing))}" if row.fetch(:line).fetch(:missing).any?
+          OPTIONAL_CRITERIA.each do |criterion|
+            stats = row.fetch(criterion)
+            parts << "#{criterion} #{ranges(stats.fetch(:missing))}" if measured?(stats) && stats.fetch(:missing).any?
+          end
+          parts.join("  ")
+        end
+
+        def format_total(rows, color)
+          totals = {line: sum_stats(rows, :line), branch: sum_stats(rows, :branch), method: sum_stats(rows, :method)}
+          "  Patch coverage: #{criterion_cells(totals, color).join(", ")}"
+        end
+
+        def json_rows(rows)
+          rows.map do |row|
+            data = {file: row.fetch(:file), line: row.fetch(:line).merge(percent: pct(row.fetch(:line)))}
+            OPTIONAL_CRITERIA.each do |criterion|
+              stats = row.fetch(criterion)
+              data[criterion] = stats.merge(percent: pct(stats)) if measured?(stats)
+            end
+            data
+          end
+        end
+
+        # Branch and method stats are nil when the report never measured them, and
+        # 0/0 when the change touched none.
+        def measured?(stats)
+          stats.is_a?(Hash) && stats.fetch(:relevant).positive?
+        end
+
+        # Collapses a sorted line list into ranges: [41, 42, 43, 47] -> "41-43, 47".
+        # The show subcommand borrows this with a bare-comma separator for its
+        # greppable `path:40,52-58,71` form.
+        def ranges(numbers, separator = ", ")
+          numbers.slice_when { |prev, curr| curr > prev + 1 }.each_with_object(+"") do |run, out|
+            out << separator unless out.empty?
+            out << (run.one? ? only(run) : span(run))
+          end
+        end
+
+        # mutant:disable
+        def only(run)
+          format("%<only>d", only: run.first)
+        end
+
+        def span(run)
+          format("%<from>d-%<to>d", from: run.first, to: run.last)
+        end
+
+        def sum_stats(rows, criterion)
+          stats = rows.filter_map { |row| row.fetch(criterion) }
+          {covered: stats.sum { |stat| stat.fetch(:covered) }, relevant: stats.sum { |stat| stat.fetch(:relevant) }}
+        end
+
+        def pct(stats)
+          relevant = stats.fetch(:relevant)
+          return 100.0 if relevant.zero?
+
+          (stats.fetch(:covered).to_f / relevant * 100).round(2)
+        end
+
+        # No --minimum is report-only. With one, every measured criterion must clear
+        # the floor, and `short?` never fails an unmeasured one.
+        def gate(rows, minimum)
+          return 0 unless minimum
+
+          below = %i[line branch method].any? { |criterion| short?(sum_stats(rows, criterion), minimum) }
+          below ? 1 : 0
+        end
+
+        # Cross-multiplied rather than compared as percentages so neither rounding
+        # nor float division can shift the verdict at the boundary: reading the
+        # displayed `pct` would round a 19_999/20_000 patch up to 100 and pass it
+        # against `--minimum 100`, while dividing makes 23/40 compute as 57.4999...
+        # and fail an exactly-57.5% patch. The minimum becomes an exact Rational
+        # from its own text, and `covered * 100` is an integer, so the comparison is
+        # exact. A criterion with nothing relevant never falls short.
+        def short?(stats, minimum)
+          stats.fetch(:covered) * 100 < Rational(minimum.to_s) * stats.fetch(:relevant)
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/patch.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require_relative "annotations"
+require_relative "command_helpers"
+require_relative "patch/changed_lines"
+require_relative "patch/output"
+
+module SimpleCov
+  module CLI
+    # `simplecov patch [--base REF]`: line coverage over only the lines a
+    # change touched. Where `diff` asks "did the number move" and needs a
+    # baseline artifact, `patch` asks the question a reviewer actually asks: is
+    # the code in this change tested? A project sitting at 40% cannot move its
+    # global number in one pull request, but it can insist that every line it
+    # adds is covered.
+    #
+    # Only files the report already carries are scored: a changed file
+    # SimpleCov never tracked is out of scope, and a line `LinesClassifier`
+    # considers never relevant stays out of the denominator the same way it
+    # stays out of the file total.
+    #
+    module Patch
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args, stderr)
+        return 1 unless opts
+
+        # An omitted --base resolves through origin's HEAD, so master and trunk
+        # repositories work bare; in CI, pass the pull request's target branch
+        # explicitly.
+        opts[:base] ||= Git.default_base
+        diffed = ChangedLines.call(opts.fetch(:base), find_renames: opts.fetch(:find_renames), stderr: stderr)
+        return 1 unless diffed
+
+        rows = compute_rows(opts.fetch(:coverage), diffed, stderr)
+        kind = opts.fetch(:annotate)
+        kind ? Output.annotate(stdout, rows, kind) : Output.emit(stdout, rows, opts)
+        Output.gate(rows, opts.fetch(:minimum))
+      end
+
+      def parse(args, stderr)
+        # No `base:` default: the run fills it in from the repository when the
+        # option is left out.
+        opts, rest = parse_common(args, find_renames: false, minimum: nil, annotate: nil) do |parser, options|
+          parser.on("--base REF") { |v| options[:base] = v }
+          parser.on("--minimum N", Float) { |v| options[:minimum] = v }
+          parser.on("--find-renames") { options[:find_renames] = true }
+          parser.on("--annotate KIND") { |v| options[:annotate] = v }
+        end
+        return unless positional_ok?(rest, stderr)
+
+        issue = Annotations.issue(opts)
+        return error_nil(stderr, issue) if issue
+
+        opts[:coverage] = CoverageFile.load_coverage(opts.fetch(:input), command: "patch", stderr: stderr) or return nil
+        opts
+      end
+
+      # A stray positional looks exactly like a ref, so a forgotten `--base`
+      # (`simplecov patch feature-x`) would otherwise diff against the default
+      # and gate the wrong change in silence.
+      def positional_ok?(rest, stderr)
+        return true if rest.empty?
+
+        error(stderr, "unexpected argument #{rest.first.inspect} (did you mean `--base #{rest.first}`?)")
+        false
+      end
+
+      # Everything below reads values that came out of a coverage.json, which
+      # carries plain objects, arrays and integers and never a subclass of one,
+      # so the shape checks ask about the class itself.
+
+      # Diff paths are exact root-relative names, so they resolve exactly against
+      # the report. The suffix fallback `CoverageFile.lookup` offers interactive
+      # commands could only ever bind a changed file the report doesn't carry to
+      # some other file's hits and score the wrong entry.
+      def compute_rows(coverage, diffed, stderr)
+        index = CoverageFile.exact_index(coverage)
+        diffed.fetch(:changes).filter_map do |path, lines|
+          payload = index[File.expand_path(path, diffed.fetch(:root))] || index[path]
+          next unless payload.instance_of?(Hash) # file the report doesn't carry -> out of scope
+
+          changed = changed_for(lines, payload)
+          warn_stale(path, payload, changed, stderr)
+          row = build_row(path, payload, changed)
+          row if scored?(row) # nothing coverable changed in this file
+        end
+      end
+
+      # An untracked file appears in no diff, so `:all` stands in for its line
+      # numbers: every line the report knows is this change's work.
+      def changed_for(lines, payload)
+        return lines.uniq unless lines.equal?(:all)
+
+        hits = payload["lines"]
+        hits.instance_of?(Array) ? (1..hits.length).to_a : []
+      end
+
+      # A changed line past the end of the report's lines array reads as
+      # never-relevant and silently drops out of the denominator, which is right
+      # for a fresh report and wrong for a stale one, so say which is likelier
+      # out loud instead of letting a `--minimum` gate pass vacuously.
+      def warn_stale(path, payload, changed, stderr)
+        hits = payload["lines"]
+        return unless hits.instance_of?(Array)
+        return if changed.empty? || changed.max <= hits.length
+
+        stderr.puts("simplecov patch: #{path} changed beyond the #{hits.length}-line entry in the " \
+                    "report (is the report stale? regenerate it and rerun)")
+      end
+
+      def build_row(path, payload, changed)
+        {
+          file: path,
+          line: line_stats(payload["lines"], changed),
+          branch: entry_stats(payload["branches"], changed),
+          method: entry_stats(payload["methods"], changed)
+        }
+      end
+
+      # A line counts only where the report gives it an Integer hit count; a
+      # never-relevant line (nil) or a `:nocov:` line ("ignored") stays out of
+      # the denominator, the same rule the file total uses.
+      def line_stats(hits, changed)
+        covered = 0
+        missing = [] #: Array[Integer]
+        return {covered: covered, relevant: 0, missing: missing} unless hits.instance_of?(Array)
+
+        changed.each do |number|
+          hit = hits.at(number - 1)
+          # nil / "ignored" (nocov) / any non-Integer -> never relevant, skipped.
+          next unless hit.instance_of?(Integer)
+
+          hit.positive? ? (covered += 1) : (missing << number)
+        end
+        {covered: covered, relevant: covered + missing.size, missing: missing.sort}
+      end
+
+      # Branches and methods share the report shape (a reported line and an
+      # integer hit count), so one scorer serves both. nil when the report
+      # carries no data for the criterion, so the output and gate skip it
+      # rather than reporting a hollow 0/0. A miss is recorded at the reported
+      # line so the note points where the source is.
+      def entry_stats(entries, changed)
+        return nil unless entries.instance_of?(Array)
+
+        covered = 0
+        missing = [] #: Array[Integer]
+        each_touched(entries, changed) do |line, hits|
+          hits.positive? ? (covered += 1) : (missing << line)
+        end
+        {covered: covered, relevant: covered + missing.size, missing: missing.uniq.sort}
+      end
+
+      # "ignored" (nocov) entries and entries off the change are skipped.
+      def each_touched(entries, changed)
+        entries.each do |entry|
+          next unless entry.instance_of?(Hash)
+
+          line = entry["report_line"] || entry["start_line"]
+          hits = entry["coverage"]
+          yield line, hits if changed.include?(line) && hits.instance_of?(Integer)
+        end
+      end
+
+      def scored?(row)
+        row.fetch(:line).fetch(:relevant).positive? ||
+          Output.measured?(row.fetch(:branch)) || Output.measured?(row.fetch(:method))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Ratchet
+      module Output
+        extend CommandHelpers
+
+        extend self
+
+        def emit(stdout, opts, outcome, generated)
+          return stdout.puts(JSON.generate(json_summary(opts, outcome, generated))) if opts.fetch(:json)
+
+          verb = opts.fetch(:dry_run) ? "would write" : "wrote"
+          stdout.puts("simplecov ratchet: #{verb} #{opts.fetch(:baseline)} (#{change_summary(outcome, generated)})")
+          report_regressed(stdout, outcome.regressed)
+        end
+
+        def change_summary(outcome, generated)
+          files = outcome.baseline.entries.size
+          return "#{files} #{one?(files) ? "file" : "files"}" if generated
+
+          "#{outcome.tightened.size} tightened, #{outcome.pruned.size} pruned, #{outcome.unchanged.size} unchanged"
+        end
+
+        def report_regressed(stdout, regressed)
+          return if regressed.empty?
+
+          noun = one?(regressed.size) ? "1 file below its floor" : "#{regressed.size} files below their floors"
+          stdout.puts("simplecov ratchet: #{noun}, entries kept unchanged")
+        end
+
+        def json_summary(opts, outcome, generated)
+          {
+            written: !opts.fetch(:dry_run), path: opts.fetch(:baseline), generated: generated,
+            files: outcome.baseline.entries.size,
+            tightened: outcome.tightened, pruned: outcome.pruned,
+            regressed: outcome.regressed, unchanged: outcome.unchanged
+          }
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/ratchet.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../atomic_file"
+require_relative "command_helpers"
+require_relative "coverage_file"
+require_relative "ratchet/output"
+
+module SimpleCov
+  module CLI
+    # `simplecov ratchet`: rewrite the checked-in per-file coverage baseline
+    # (#1268) from the current report. Floors only ever tighten, entries for
+    # files the report no longer carries are pruned, and files without an entry
+    # are never given one, so new code stays answerable to the global thresholds
+    # rather than to a floor cut at whatever it launched with. `--init`
+    # regenerates the whole file from the current state.
+    #
+    # The baseline path follows the project's `.simplecov` `baseline_file`
+    # setting when one is present, the same way the read-only commands follow
+    # `coverage_dir`.
+    module Ratchet
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:, **)
+        require "simplecov"
+        opts = parse(args, stderr) or return 1
+        coverage = CoverageFile.load_coverage(opts.fetch(:input), command: "ratchet", stderr: stderr) or return 1
+
+        outcome, generated = compute(opts, current_floors(coverage))
+        AtomicFile.write(opts.fetch(:baseline), outcome.baseline.to_yaml) unless opts.fetch(:dry_run)
+        Output.emit(stdout, opts, outcome, generated)
+        0
+      rescue ConfigurationError => e
+        error(stderr, e)
+      end
+
+      def parse(args, stderr)
+        opts, rest = parse_common(args, init: false, dry_run: false) do |parser, options|
+          parser.on("--baseline PATH") { |v| options[:baseline] = v }
+          parser.on("--init") { options[:init] = true }
+          parser.on("--dry-run") { options[:dry_run] = true }
+        end
+        return error_nil(stderr, "unexpected argument #{rest.first.inspect}") unless rest.empty?
+
+        opts[:baseline] ||= Dotfile.baseline_file
+        opts
+      end
+
+      # Only criteria the report carries for a file appear, so a line-only report
+      # leaves existing branch floors alone.
+      def current_floors(coverage)
+        initial = {} #: Baseline::current_floors
+        coverage.each_with_object(initial) do |(path, entry), floors|
+          criteria = CoverageFile::CRITERIA.filter_map do |criterion, keys|
+            percent = entry[keys.fetch(:percent)]
+            missed = entry[keys.fetch(:missed)]
+            [criterion, {percent: SimpleCov.round_coverage(percent), missed: missed}] if usable?(percent, missed)
+          end.to_h
+          floors[path] = criteria unless criteria.empty?
+        end
+      end
+
+      # A report row from another tool may be missing counts; only a complete pair
+      # can become a floor.
+      def usable?(percent, missed)
+        percent.is_a?(Numeric) && missed.instance_of?(Integer)
+      end
+
+      def compute(opts, current)
+        existing = Baseline.read_if_exists(opts.fetch(:baseline)) unless opts.fetch(:init)
+        return [existing.ratchet(current), false] if existing
+
+        none = [] #: Array[String]
+        outcome = Baseline::Outcome.new(
+          baseline: Baseline.generate(current),
+          tightened: none, pruned: none, regressed: none, unchanged: none
+        )
+        [outcome, true]
+      end
+    end
+  end
+end