simplecov 1.1.1 → 1.2.0

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

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SimpleCov
+  module CLI
+    module Patch
+      module Output
+        OPTIONAL_CRITERIA = %i[branch method].freeze
+
+        extend self
+
+        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,169 @@
+# frozen_string_literal: true
+
+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)
+        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) 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 }
+        end
+        return unless positional_ok?(rest, stderr)
+
+        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