simplecov 1.1.1 → 1.2.0

data/lib/simplecov/cli/show/sweep.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Show
+      module Sweep
+        extend self
+
+        def misses(coverage)
+          rows = coverage.filter_map do |filename, entry|
+            next unless entry.instance_of?(Hash) && entry["lines"].instance_of?(Array)
+
+            missed = Annotator.missed_lines(entry)
+            [display_path(filename), missed] unless missed.empty?
+          end
+          rows.sort_by(&:first)
+        end
+
+        def emit(rows, opts, stdout, stderr)
+          if opts.fetch(:json)
+            stdout.puts(JSON.pretty_generate(rows.map { |path, missed| {path: path, missed: missed} }))
+          elsif rows.empty?
+            stderr.puts("simplecov show: nothing uncovered")
+          else
+            rows.each { |path, missed| stdout.puts("#{path}:#{Patch::Output.ranges(missed, ",")}") }
+          end
+          0
+        end
+
+        def display_path(filename)
+          filename.delete_prefix("#{File.expand_path(SimpleCov.root)}/")
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/show.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+require_relative "patch/output"
+require_relative "show/annotator"
+require_relative "show/sweep"
+
+module SimpleCov
+  module CLI
+    # `simplecov show <path>`: annotated source in the terminal, the way
+    # `go tool cover` and `llvm-cov show` print it. `--uncovered-only` collapses
+    # the answer to `path:ranges`, a form that greps, fits in a commit message,
+    # and hands a coding agent exactly the lines whose tests are missing.
+    module Show
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:)
+        opts = parse(args)
+        return run_project(opts, stdout, stderr) unless opts.fetch(:path)
+
+        coverage = CoverageFile.load_coverage(opts.fetch(:input), command: "show", stderr: stderr)
+        return 1 unless coverage
+
+        located = locate_or_report(coverage, opts, stderr)
+        return 1 unless located
+
+        render(located, opts, stdout, stderr)
+      end
+
+      # No path sweeps the whole project, in the compact forms only. The annotated
+      # text form still wants one file.
+      def run_project(opts, stdout, stderr)
+        unless opts.fetch(:uncovered_only) || opts.fetch(:json)
+          return error(stderr, "missing path (annotating needs one file; --uncovered-only sweeps the whole project)")
+        end
+
+        coverage = CoverageFile.load_coverage(opts.fetch(:input), command: "show", stderr: stderr)
+        return 1 unless coverage
+
+        Sweep.emit(Sweep.misses(coverage), opts, stdout, stderr)
+      end
+
+      def parse(args)
+        opts = {input: CLI.default_input, no_color: false,
+                uncovered_only: false, json: false} #: Hash[Symbol, untyped]
+        rest = build_parser { |parser| options(parser, opts) }.parse(args)
+        opts[:path] = rest.first
+        opts
+      end
+
+      def options(parser, opts)
+        parser.on("--input PATH") { |v| opts[:input] = v }
+        parser.on("--no-color") { opts[:no_color] = true }
+        parser.on("--uncovered-only") { opts[:uncovered_only] = true }
+        parser.on("--json") { opts[:json] = true }
+      end
+
+      # A line-less report has no per-line hits to put in a gutter, so it is
+      # reported like an unresolvable path is.
+      def locate_or_report(coverage, opts, stderr)
+        path, input = opts.fetch_values(:path, :input)
+        match = CoverageFile.lookup(coverage, path)
+        return error_nil(stderr, CoverageFile.not_found_message(coverage, path, input)) unless match
+
+        entry = match.last
+        unless entry.instance_of?(Hash)
+          return CoverageFile.report_invalid(stderr, "show", input, "entry for #{path} must be an object")
+        end
+        return match if entry["lines"].instance_of?(Array)
+
+        error_nil(stderr, "no line coverage for #{path} in #{input}")
+      end
+
+      def render(located, opts, stdout, stderr)
+        filename, entry = located
+        return emit_json(entry, opts, stdout) if opts.fetch(:json)
+        return show_uncovered(entry, opts, stdout, stderr) if opts.fetch(:uncovered_only)
+
+        source = source_for(filename, entry, opts, stderr)
+        return 1 unless source
+
+        Annotator.call(source, entry, stdout, color: CLI.color_enabled?(opts, stdout))
+        0
+      end
+
+      def emit_json(entry, opts, stdout)
+        stdout.puts(JSON.pretty_generate(
+          path: opts.fetch(:path), missed: Annotator.missed_lines(entry),
+          lines: relevant_lines(entry), markers: Annotator.markers_for(entry)
+        ))
+        0
+      end
+
+      def relevant_lines(entry)
+        entry.fetch("lines").each_with_index.filter_map do |hit, index|
+          {number: index + 1, hits: hit} if hit.instance_of?(Integer)
+        end
+      end
+
+      def show_uncovered(entry, opts, stdout, stderr)
+        missed = Annotator.missed_lines(entry)
+        if missed.empty?
+          stderr.puts("simplecov show: nothing uncovered in #{opts.fetch(:path)}")
+        else
+          stdout.puts("#{opts.fetch(:path)}:#{Patch::Output.ranges(missed, ",")}")
+        end
+        0
+      end
+
+      # The report's own source when it carries one; otherwise the file on disk,
+      # accepted only while its line count still matches the report's, since
+      # annotating drifted source would put hit counts on the wrong lines.
+      def source_for(filename, entry, opts, stderr)
+        embedded = entry["source"]
+        return embedded if embedded.instance_of?(Array) && embedded.all?(String)
+        unless File.file?(filename)
+          return error_nil(stderr, "no source for #{opts.fetch(:path)} in #{opts.fetch(:input)} and no file " \
+                                   "at #{filename}, regenerate the report with `source_in_json true`")
+        end
+
+        lines = File.readlines(filename, chomp: true)
+        return lines if lines.size.eql?(entry.fetch("lines").size)
+
+        error_nil(stderr, "#{filename} has changed since the report (#{lines.size} lines now, " \
+                          "#{entry.fetch("lines").size} recorded), regenerate the report")
+      end
+    end
+  end
+end

data/lib/simplecov/cli/status/facts.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Status
+      module Facts
+        extend self
+
+        def gather(document, resultset_path)
+          contexts = document["contexts"]
+          meta_facts(document).merge(
+            totals: totals(document["total"]),
+            contexts: (contexts.size if contexts.instance_of?(Array)),
+            resultset_path: resultset_path, resultset: readable_resultset(resultset_path)
+          )
+        end
+
+        def meta_facts(document)
+          none = {} #: Hash[String, untyped]
+          recorded = document["meta"]
+          meta = recorded.instance_of?(Hash) ? recorded : none
+          generated = parse_time(meta["timestamp"])
+          {
+            generated_at: meta["timestamp"], age: generated && whole_seconds(Time.now - generated),
+            version: meta["simplecov_version"], command_name: meta["command_name"],
+            commit: meta["commit"], behind: behind(meta["commit"])
+          }
+        end
+
+        def age_of(timestamp)
+          whole_seconds(Process.clock_gettime(Process::CLOCK_REALTIME) - timestamp)
+        end
+
+        def whole_seconds(elapsed)
+          elapsed.truncate
+        end
+
+        def parse_time(value)
+          Time.iso8601(value) if value.instance_of?(String)
+        rescue ArgumentError
+          nil
+        end
+
+        # Commits between the report's commit and HEAD: 0 at HEAD, nil when
+        # unanswerable, meaning no commit recorded, no git, or a commit this
+        # repository has never seen.
+        def behind(commit)
+          return nil unless commit.instance_of?(String)
+
+          stdout, _detail, success = Git.capture("rev-list", "--count", "#{commit}..HEAD")
+          commit_count(_ = stdout) if success
+        end
+
+        # `Integer` ignores surrounding whitespace on its own, so git's trailing
+        # newline needs no trimming. The base is spelled out because bare `Integer`
+        # reads a leading zero as octal.
+        def commit_count(output)
+          Integer(output, 10)
+        end
+
+        def totals(total)
+          return {} unless total.instance_of?(Hash)
+
+          rows = {"line" => "lines", "branch" => "branches", "method" => "methods"}.filter_map do |name, key|
+            percent = total.dig(key, "percent")
+            [name, percent] if percent.is_a?(Numeric)
+          end
+          rows.to_h
+        end
+
+        # An unreadable resultset answers nothing rather than raising: its
+        # absence is a fact, not an error.
+        def readable_resultset(path)
+          parsed = JSON.parse(File.read(path))
+          return nil unless parsed.instance_of?(Hash)
+
+          parsed.map do |command, data|
+            timestamp = data["timestamp"] if data.instance_of?(Hash)
+            {command: command, age: (age_of(timestamp) if timestamp.is_a?(Numeric))}
+          end
+        rescue SystemCallError, JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/status.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "time"
+require_relative "command_helpers"
+require_relative "git"
+require_relative "status/facts"
+
+module SimpleCov
+  module CLI
+    module Status
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:)
+        opts, = parse_common(args)
+        document = CoverageFile.load_document(opts.fetch(:input), command: "status", stderr: stderr)
+        return 1 unless document
+
+        facts = Facts.gather(document, CLI.default_resultset)
+        opts.fetch(:json) ? stdout.puts(JSON.pretty_generate(facts)) : print_facts(facts, opts, stdout)
+        0
+      end
+
+      def print_facts(facts, opts, stdout)
+        stdout.puts("report #{opts.fetch(:input)}")
+        report_lines(facts).each { |line| stdout.puts("  #{line}") }
+        print_resultset(facts, stdout)
+      end
+
+      def report_lines(facts)
+        [
+          facts.fetch(:generated_at) && "generated #{facts.fetch(:generated_at)}#{age_suffix(facts.fetch(:age))}",
+          provenance_words(facts),
+          "commit #{commit_words(facts)}",
+          (totals_words(facts.fetch(:totals)) unless facts.fetch(:totals).empty?),
+          "tests recorded: #{contexts_words(facts.fetch(:contexts))}"
+        ].compact
+      end
+
+      def provenance_words(facts)
+        "by simplecov #{facts.fetch(:version)} running #{facts.fetch(:command_name)}"
+      end
+
+      def commit_words(facts)
+        commit = facts.fetch(:commit)
+        return "not recorded" unless commit.instance_of?(String)
+
+        "#{commit[0, 7]} (#{distance_words(facts.fetch(:behind))})"
+      end
+
+      def distance_words(behind)
+        return "not in this repository's history" unless behind
+        return "current HEAD" if behind.zero?
+
+        "#{behind} commit#{"s" unless one?(behind)} behind HEAD"
+      end
+
+      def totals_words(totals)
+        totals.map { |name, percent| "#{name} #{format("%.2f%%", percent)}" }.join(", ")
+      end
+
+      def contexts_words(count)
+        count ? "#{count} (track_tests)" : "none (enable track_tests to select and re-run by test)"
+      end
+
+      def print_resultset(facts, stdout)
+        entries = facts.fetch(:resultset)
+        return stdout.puts("resultset none") unless entries
+
+        stdout.puts("resultset #{facts.fetch(:resultset_path)}")
+        entries.each do |entry|
+          age = entry.fetch(:age) ? "#{age_in_words(entry.fetch(:age))} ago" : "age unknown"
+          stdout.puts("  #{entry.fetch(:command)}: #{age}")
+        end
+      end
+
+      def age_suffix(age)
+        " (#{age_in_words(age)} ago)" if age
+      end
+
+      def age_in_words(seconds)
+        return "#{seconds.round} seconds" if seconds < 90
+        return "#{(seconds / 60.0).round} minutes" if seconds < 5400
+        return "#{(seconds / 3600.0).round} hours" if seconds < 129_600
+
+        "#{(seconds / 86_400.0).round} days"
+      end
+    end
+  end
+end

data/lib/simplecov/cli/tests/redundancy.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Tests
+      # The `--redundant` sweep: the contexts whose covered lines other contexts
+      # also cover, the tests contributing no coverage of their own. A context is
+      # non-redundant exactly when some line is covered by it alone, so per file
+      # two bitmaps (lines seen once, lines seen more than once) find the uniquely
+      # covered lines and a second pass credits each to its owner.
+      module Redundancy
+        extend self
+
+        def redundant_ids(document, contexts, opts, stderr)
+          tables = sweep_tables(document, contexts, opts, stderr)
+          return unless tables
+
+          unique = unique_owners(tables, contexts.size)
+          contexts.each_index.reject { |index| unique.fetch(index) }.map { |index| contexts.fetch(index) }.sort
+        end
+
+        def unique_owners(tables, context_count)
+          unique = Array.new(context_count, false)
+          tables.each do |table|
+            lone = lone_bits(table)
+            table.each { |index, bitmap| unique[index] = true if bitmap.anybits?(lone) }
+          end
+          unique
+        end
+
+        # A bit enters `once` when brand new and leaves for good when any later
+        # bitmap carries it again. The two halves of the update are provably
+        # disjoint, so they are summed: for disjoint bits that builds the number OR
+        # would, and it leaves no spelling of the combination without a witness.
+        def lone_bits(table)
+          once = 0
+          ever = 0
+          table.each_value do |bitmap|
+            once = (once & ~bitmap) + (bitmap & ~ever)
+            ever |= bitmap
+          end
+          once
+        end
+
+        # The sweep reads tables no query named, so a malformed one anywhere poisons
+        # the whole answer, matching the targeted queries' all-or-nothing tolerance.
+        def sweep_tables(document, contexts, opts, stderr)
+          coverage = document["coverage"]
+          return invalid(opts, stderr, '"coverage" must be an object') unless coverage.is_a?(Hash)
+
+          tables = [] #: Array[Hash[Integer, Integer]]
+          coverage.each do |path, entry|
+            table = entry.is_a?(Hash) && swept_table(entry, contexts)
+            return invalid(opts, stderr, complaint(path, entry)) unless table
+
+            tables << table
+          end
+          tables
+        end
+
+        def swept_table(entry, contexts)
+          raw = entry["contexts"] || {}
+          Tests.decode_table(raw, contexts.size) if raw.is_a?(Hash)
+        end
+
+        def complaint(path, entry)
+          return "entry for #{path} must be an object" unless entry.is_a?(Hash)
+
+          "entry for #{path} carries a malformed \"contexts\" table"
+        end
+
+        def invalid(opts, stderr, reason)
+          CoverageFile.report_invalid(stderr, "tests", opts.fetch(:input), reason)
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/tests.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+require_relative "tests/redundancy"
+
+module SimpleCov
+  module CLI
+    # `simplecov tests [<path>[:<line>]]`: list the recorded tests from a
+    # coverage.json written under `track_tests`. Text output is one id per line
+    # so the list can feed a test runner directly; empty answers keep stdout
+    # empty and note the emptiness on stderr instead.
+    module Tests
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:)
+        opts = parse(args)
+        return error(stderr, "line number must be positive") if opts.fetch(:line)&.zero?
+
+        document = CoverageFile.load_document(opts.fetch(:input), command: "tests", stderr: stderr)
+        return 1 unless document
+
+        ids = resolve(document, opts, stderr)
+        return 1 unless ids
+
+        emit(ids, opts, stdout, stderr)
+        0
+      end
+
+      def parse(args)
+        opts, rest = parse_common(args) do |parser, options|
+          parser.on("--redundant") { options[:redundant] = true }
+        end
+        opts[:target] = rest.first
+        split = split_target(rest.first)
+        opts[:path] = split.fetch(:path)
+        opts[:line] = split.fetch(:line)
+        opts
+      end
+
+      # Only an all-digit tail after the last colon reads as a line number, so
+      # Windows drive colons and exotic filenames stay plain paths.
+      def split_target(target)
+        return {path: nil, line: nil} unless target
+
+        path, sep, tail = target.rpartition(":")
+        return {path: target, line: nil} if sep.empty? || !tail.match?(/\A\d+\z/)
+
+        {path: path, line: Integer(tail, 10)}
+      end
+
+      def resolve(document, opts, stderr)
+        contexts = recorded_contexts(document, opts, stderr)
+        return unless contexts
+
+        opts[:no_recording] = contexts.empty?
+        ids = selected_ids(document, contexts, opts, stderr)
+        return ids unless ids && opts[:redundant]
+
+        redundant = Redundancy.redundant_ids(document, contexts, opts, stderr)
+        redundant && (ids & redundant)
+      end
+
+      def selected_ids(document, contexts, opts, stderr)
+        return contexts.sort unless opts.fetch(:path)
+
+        entry = locate_entry(document, opts, stderr)
+        return unless entry
+
+        table = context_table(entry, contexts, opts, stderr)
+        table && ids_from(table, contexts, opts.fetch(:line))
+      end
+
+      def locate_entry(document, opts, stderr)
+        coverage = document["coverage"]
+        input = opts.fetch(:input)
+        unless coverage.is_a?(Hash)
+          return CoverageFile.report_invalid(stderr, "tests", input, '"coverage" must be an object')
+        end
+
+        path = opts.fetch(:path)
+        match = CoverageFile.lookup(coverage, path)
+        return error_nil(stderr, CoverageFile.not_found_message(coverage, path, input)) unless match
+        return match.last if match.last.is_a?(Hash)
+
+        CoverageFile.report_invalid(stderr, "tests", input, "entry for #{path} must be an object")
+      end
+
+      def context_table(entry, contexts, opts, stderr)
+        raw = entry["contexts"] || {}
+        table = decode_table(raw, contexts.size) if raw.is_a?(Hash)
+        return table if table
+
+        CoverageFile.report_invalid(stderr, "tests", opts.fetch(:input),
+          "entry for #{opts.fetch(:path)} carries a malformed \"contexts\" table")
+      end
+
+      # An absent key is an untouched file; anything malformed, a foreign index or
+      # a non-hex bitmap, poisons the whole answer, matching the all-or-nothing
+      # tolerance the resultset reader applies.
+      def decode_table(raw, context_count)
+        table = {} #: Hash[Integer, Integer]
+        raw.each do |index, hex|
+          return nil unless index.is_a?(String) && index.match?(/\A\d+\z/)
+          return nil unless hex.is_a?(String) && hex.match?(/\A\h+\z/)
+
+          position = Integer(index, 10)
+          return nil unless position < context_count
+
+          table[position] = Integer(hex, 16)
+        end
+        table
+      end
+
+      def ids_from(table, contexts, line)
+        bit = line && (1 << (line - 1))
+        table.filter_map { |index, bitmap| contexts.fetch(index) if bit.nil? || bitmap.anybits?(bit) }.sort
+      end
+
+      def emit(ids, opts, stdout, stderr)
+        return stdout.puts(JSON.pretty_generate(ids)) if opts.fetch(:json)
+        return note_empty(opts, stderr) if ids.empty?
+
+        ids.each { |id| stdout.puts(id) }
+      end
+
+      def note_empty(opts, stderr)
+        stderr.puts("simplecov tests: #{empty_message(opts)}")
+      end
+
+      def empty_message(opts)
+        target = opts.fetch(:target)
+        if opts[:redundant] && !opts.fetch(:no_recording)
+          return "no redundant test covers #{target}" if target
+
+          "no redundant tests, every recorded test covers at least one line uniquely"
+        elsif target
+          "no recorded test covers #{target}"
+        else
+          "no tests recorded"
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/uncovered/misses.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Uncovered
+      module Misses
+        extend self
+
+        def missed_for(payload, criterion)
+          case criterion
+          when :line then payload["lines"].instance_of?(Array) ? Show::Annotator.missed_lines(payload) : []
+          when :branch then collect(payload["branches"])
+          else collect(payload["methods"])
+          end
+        end
+
+        def collect(items)
+          missed = [] #: Array[Integer]
+          Show::Annotator.each_missed(items) { |line| missed << line }
+          missed.uniq.sort
+        end
+
+        # GitHub workflow commands, one ::warning per contiguous missed range, so a
+        # plain workflow gets inline diff annotations with no upload step and no
+        # code-scanning permissions.
+        def annotate(stdout, files)
+          files.each do |fname, _pct, _covered, _total, missed|
+            path = fname.delete_prefix("#{File.expand_path(SimpleCov.root)}/")
+            missed.slice_when { |previous, current| current > previous + 1 }.each do |run|
+              stdout.puts("::warning file=#{path},line=#{run.first},endLine=#{run.last}::Not covered by tests")
+            end
+          end
+        end
+      end
+    end
+  end
+end