simplecov 1.1.1 → 1.3.0

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

data/lib/simplecov/cli/report.rb

@@ -6,46 +6,40 @@ require_relative "command_helpers"
 
 module SimpleCov
   module CLI
-    # `simplecov report [--input PATH]` — pretty-print the overall
-    # totals row plus per-group totals from a JSONFormatter
-    # coverage.json. Same numbers as the HTML report's totals row, for
-    # contexts where opening a browser isn't an option (CI logs, ssh
-    # sessions, terminal-only workflows).
     module Report
       extend CommandHelpers
 
       TOTAL_LABEL = "All Files"
-      SECTIONS = [%w[Line lines], %w[Branch branches], %w[Method methods]].freeze
+      SECTIONS = [%w[Line lines], %w[Branch branches], %w[Method methods]].freeze #: Array[[String, String]]
 
-    module_function
+      extend self
 
       def run(args, stdout:, stderr:)
         opts, = parse_common(args)
-        return 1 unless (data = load_data(opts[:input], stderr))
+        return 1 unless (data = load_data(opts.fetch(:input), stderr))
 
-        if opts[:json]
+        if opts.fetch(:json)
           emit_json(stdout, data)
         else
-          emit_text(stdout, data, SimpleCov::CLI.color_enabled?(opts, stdout))
+          emit_text(stdout, data, CLI.color_enabled?(opts, stdout))
         end
         0
       end
 
-      # Valid JSON isn't enough: a wrong-typed "total" or "groups" (or a
-      # wrong-typed group entry) used to escape here and crash the
-      # emitters with a backtrace instead of the one-line error the
-      # sibling commands print.
+      # Valid JSON isn't enough: a wrong-typed "total" or "groups" used to escape
+      # here and crash the emitters with a backtrace instead of the one-line error
+      # the sibling commands print.
       def load_data(input, stderr)
         data = CoverageFile.load_document(input, command: "report", stderr: stderr)
         return unless data
 
         none = {} #: Hash[String, untyped]
-        unless data.fetch("total", none).is_a?(Hash)
+        unless data.fetch("total", none).instance_of?(Hash)
           return CoverageFile.report_invalid(stderr, "report", input, '"total" must be an object')
         end
 
         groups = data.fetch("groups", none)
-        return data if groups.is_a?(Hash) && groups.each_value.all?(Hash)
+        return data if groups.instance_of?(Hash) && groups.each_value.all?(Hash)
 
         CoverageFile.report_invalid(stderr, "report", input, '"groups" must be an object of objects')
       end
@@ -54,7 +48,7 @@ module SimpleCov
         none = {} #: Hash[String, untyped]
         emit_totals(stdout, TOTAL_LABEL, data.fetch("total", none), color)
         data.fetch("groups", none).each do |name, group|
-          label = name == TOTAL_LABEL ? "#{name} (group)" : name
+          label = name.eql?(TOTAL_LABEL) ? "#{name} (group)" : name
           emit_totals(stdout, label, group, color)
         end
       end
@@ -66,12 +60,12 @@ module SimpleCov
       end
 
       def emit_section(stdout, display, section, color)
-        return unless section.is_a?(Hash) && section["total"].to_i.positive?
+        return unless section.instance_of?(Hash) && section["total"].to_i.positive?
 
         stdout.puts(stats_row(display,
-                              SimpleCov::Color.colorize_percent(section["percent"].to_f, enabled: color),
-                              section["covered"],
-                              section["total"]))
+          Color.colorize_percent(section["percent"].to_f, enabled: color),
+          section["covered"],
+          section.fetch("total")))
       end
 
       def emit_json(stdout, data)
@@ -85,10 +79,10 @@ module SimpleCov
         sections = {} #: Hash[String, untyped]
         SECTIONS.each_with_object(sections) do |(_, key), out|
           section = totals[key]
-          next unless section.is_a?(Hash) && section["total"].to_i.positive?
+          next unless section.instance_of?(Hash) && section["total"].to_i.positive?
 
-          out[key.to_s] = {
-            "percent" => section["percent"], "covered" => section["covered"], "total" => section["total"]
+          out[key] = {
+            "percent" => section["percent"], "covered" => section["covered"], "total" => section.fetch("total")
           }
         end
       end

data/lib/simplecov/cli/run.rb

@@ -2,29 +2,28 @@
 
 module SimpleCov
   module CLI
-    # `simplecov run <command...>` — exec the given command with
-    # simplecov auto-loaded so a coverage report drops into the
-    # project's coverage/ directory at the end. Useful for projects
-    # without a test_helper that already calls SimpleCov.start (e.g.
-    # plain `bundle exec rake test` on an unconfigured library).
     module Run
       AUTOSTART = File.expand_path("../autostart", __dir__.to_s)
 
-    module_function
+      extend self
 
       def run(args, stderr:, **)
-        cmd = args.first == "--" ? args.drop(1) : args
+        cmd = args.first.eql?("--") ? args.drop(1) : args
         if cmd.empty?
           stderr.puts("simplecov run: missing command")
           return 1
         end
 
-        Kernel.exec(rubyopt_env, *cmd)
+        exec_command(rubyopt_env, cmd)
       rescue Errno::ENOENT => e
-        stderr.puts("simplecov run: #{e.message}")
+        stderr.puts("simplecov run: #{e}")
         127
       end
 
+      def exec_command(env, cmd)
+        Kernel.exec(env, *cmd)
+      end
+
       def rubyopt_env
         existing = ENV["RUBYOPT"].to_s.strip
         injection = "-r#{AUTOSTART}"

data/lib/simplecov/cli/serve/report_preparer.rb

@@ -5,9 +5,6 @@ require_relative "../../coverage_json"
 module SimpleCov
   module CLI
     module Serve
-      # Ensures the coverage directory has a renderable entry point before
-      # the HTTP server binds. Existing self-contained reports take priority
-      # over their optional JSON sidecar.
       module ReportPreparer
         def self.call(dir)
           index_path = File.join(dir, "index.html")
@@ -17,11 +14,15 @@ module SimpleCov
 
           return "#{dir} has no index.html or coverage.json; run your test suite first" unless File.file?(json_path)
 
+          build_index(json_path, dir)
+        rescue CoverageJSON::Error, SystemCallError => e
+          "cannot build index.html from #{json_path}: #{e}"
+        end
+
+        def self.build_index(json_path, dir)
           require_relative "../../formatter/html_formatter"
-          SimpleCov::Formatter::HTMLFormatter.new.format_from_json(json_path, dir)
+          Formatter::HTMLFormatter.new.format_from_json(json_path, dir)
           nil
-        rescue SimpleCov::CoverageJSON::Error, SystemCallError => e
-          "cannot build index.html from #{json_path}: #{e.message}"
         end
       end
     end