simplecov 0.22.0 → 1.3.0

data/lib/simplecov/cli.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "version"
+require_relative "color"
+require_relative "cli/dotfile"
+require_relative "cli/badge"
+require_relative "cli/clean"
+require_relative "cli/completions"
+require_relative "cli/coverage_file"
+require_relative "cli/coverage"
+require_relative "cli/dead_code"
+require_relative "cli/diff"
+require_relative "cli/history"
+require_relative "cli/merge"
+require_relative "cli/open"
+require_relative "cli/patch"
+require_relative "cli/ratchet"
+require_relative "cli/report"
+require_relative "cli/run"
+require_relative "cli/serve"
+require_relative "cli/show"
+require_relative "cli/status"
+require_relative "cli/tests"
+require_relative "cli/affected"
+require_relative "cli/uncovered"
+require_relative "cli/usage"
+require_relative "cli/watch"
+
+module SimpleCov
+  # Lightweight command-line front-end. Read-only subcommands consume
+  # JSONFormatter output, which the bundled HTMLFormatter already drops
+  # alongside the HTML, so no runtime hooking is needed for those. Default
+  # paths follow the project's `.simplecov` `coverage_dir` setting when one is
+  # present.
+  module CLI
+    COMMANDS = {
+      "coverage" => Coverage,
+      "show" => Show,
+      "run" => Run,
+      "open" => Open,
+      "report" => Report,
+      "status" => Status,
+      "history" => History,
+      "uncovered" => Uncovered,
+      "tests" => Tests,
+      "affected" => Affected,
+      "merge" => Merge,
+      "diff" => Diff,
+      "patch" => Patch,
+      "ratchet" => Ratchet,
+      "dead-code" => DeadCode,
+      "serve" => Serve,
+      "watch" => Watch,
+      "badge" => Badge,
+      "clean" => Clean,
+      "completions" => Completions
+    }.freeze
+
+    extend self
+
+    # Resolved once per process, by walking up from cwd for a `.simplecov` and
+    # loading it with `SimpleCov.start` neutered so it can't trigger tracking
+    # just because we asked it for a config value.
+    def coverage_dir
+      @coverage_dir ||= Dotfile.coverage_dir
+    end
+
+    def default_input
+      File.join(coverage_dir, "coverage.json")
+    end
+
+    def color_enabled?(opts, stream)
+      return false if opts[:no_color]
+
+      Color.enabled?(stream)
+    end
+
+    def default_report
+      File.join(coverage_dir, "index.html")
+    end
+
+    def default_resultset
+      File.join(coverage_dir, ".resultset.json")
+    end
+
+    def run(argv, stdout: $stdout, stderr: $stderr)
+      command, *rest = argv
+      handler = COMMANDS[command]
+      return dispatch(handler, command, rest, stdout: stdout, stderr: stderr) if handler
+      return stdout.puts(usage) || 0 if [nil, "help", "--help", "-h"].include?(command)
+      return stdout.puts("simplecov #{VERSION}") || 0 if %w[version --version -v].include?(command)
+
+      stderr.puts("simplecov: unknown command #{command.inspect}", usage)
+      1
+    end
+
+    # One rescue covers every subcommand's OptionParser, so a typo'd flag becomes
+    # a one-line error and exit status 1 instead of a backtrace.
+    def dispatch(handler, command, rest, stdout:, stderr:)
+      handler.run(rest, stdout: stdout, stderr: stderr)
+    rescue CommandHelpers::HelpRequested
+      stdout.puts(Usage.for(self, command))
+      0
+    rescue OptionParser::ParseError => e
+      stderr.puts("simplecov #{command}: #{e} (run `simplecov help` for usage)")
+      1
+    end
+
+    def usage
+      Usage.text(self)
+    end
+  end
+end

data/lib/simplecov/color.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  # ANSI colorization for stderr diagnostics. Thresholds mirror the HTML
+  # formatter so a team's mental model of "what's the cutoff" is the same in
+  # the terminal and in the report.
+  module Color
+    GREEN_THRESHOLD = 90
+    YELLOW_THRESHOLD = 75
+
+    ANSI = {
+      red: "\e[31m",
+      yellow: "\e[33m",
+      green: "\e[32m",
+      reset: "\e[0m"
+    }.freeze
+
+    extend self
+
+    # Precedence, highest first: an explicit `SimpleCov.color` true/false (the
+    # default `:auto` falls through), then `NO_COLOR`, then `FORCE_COLOR`, then
+    # `stream.tty?`. `NO_COLOR` wins over `FORCE_COLOR` when both are set.
+    #
+    # `stream` is the IO the colorized text is destined for. CLI subcommands
+    # that print to stdout should pass `$stdout` so a redirected pipe doesn't
+    # get ANSI sequences.
+    #
+    # `SimpleCov.color` only exists once the full library is loaded, and the
+    # standalone CLI loads this file without it, so a missing config reads as
+    # its `:auto` default. A parallel runner can also close a worker's stdio
+    # before its at_exit hooks run, and a closed stream is not a tty.
+    def enabled?(stream = $stderr)
+      config = SimpleCov.color if SimpleCov.respond_to?(:color)
+      return config if [true, false].include?(config)
+      return false if env_set?("NO_COLOR")
+      return true if env_set?("FORCE_COLOR")
+
+      stream.tty?
+    rescue IOError
+      false
+    end
+
+    def for_percent(percent)
+      return :green if percent >= GREEN_THRESHOLD
+      return :yellow if percent >= YELLOW_THRESHOLD
+
+      :red
+    end
+
+    def colorize(text, color, enabled: enabled?)
+      return text unless enabled
+
+      "#{ANSI.fetch(color)}#{text}#{ANSI.fetch(:reset)}"
+    end
+
+    def colorize_percent(percent, text = nil, enabled: enabled?)
+      colorize(text || format("%.2f%%", percent), for_percent(percent), enabled: enabled)
+    end
+
+    def env_set?(name)
+      value = ENV.fetch(name, nil)
+      value && !value.empty?
+    end
+  end
+end

data/lib/simplecov/combine/branches_combiner.rb

@@ -1,31 +1,54 @@
 # frozen_string_literal: true
 
+require_relative "../source_file/ruby_data_parser"
+require_relative "identity_interner"
+require_relative "interned_counts"
+
 module SimpleCov
   module Combine
-    #
-    # Combine different branch coverage results on single file.
-    #
-    # Should be called through `SimpleCov.combine`.
     module BranchesCombiner
-    module_function
-
-      #
-      # Return merged branches or the existed brach if other is missing.
-      #
-      # Branches inside files are always same if they exist, the difference only in coverage count.
-      # Branch coverage report for any conditional case is built from hash, it's key is a condition and
-      # it's body is a hash << keys from condition and value is coverage rate >>.
-      # ex: branches =>{ [:if, 3, 8, 6, 8, 36] => {[:then, 4, 8, 6, 8, 12] => 1, [:else, 5, 8, 6, 8, 36]=>2}, other conditions...}
-      # We create copy of result and update it values depending on the combined branches coverage values.
-      #
-      # @return [Hash]
-      #
+      extend self
+
       def combine(coverage_a, coverage_b)
-        coverage_a.merge(coverage_b) do |_condition, branches_inside_a, branches_inside_b|
-          branches_inside_a.merge(branches_inside_b) do |_branch, a_count, b_count|
-            a_count + b_count
-          end
+        merged = absorb({}, coverage_a) #: Hash[untyped, [untyped, Hash[untyped, untyped]]]
+        materialize(absorb(merged, coverage_b))
+      end
+
+      # Folds `coverage` into `target`, an interned table keyed by condition
+      # identity. Kept interned rather than turned back into tuple keys per merge,
+      # so a fold over N resultsets interns each condition once instead of
+      # re-interning the whole accumulated table N times.
+      def absorb(target, coverage)
+        return target unless coverage
+
+        coverage.each do |condition, branches_inside|
+          entry = target[identities[condition]] ||= new_condition(condition)
+          InternedCounts.absorb_counts(entry.fetch(1), branches_inside, identities)
         end
+
+        target
+      end
+
+      def new_condition(condition)
+        arms = {} #: Hash[untyped, untyped]
+        [condition, arms]
+      end
+
+      # Turns an interned table back into the tuple-keyed hash the rest of
+      # SimpleCov reads. Done once, at the end of a fold.
+      def materialize(target)
+        target.values.to_h { |condition, branches| [condition, branches.values.to_h] }
+      end
+
+      def identities
+        @identities ||= IdentityInterner.build { |tuple| tuple_identity(tuple) }
+      end
+
+      # Branches match on source span, whatever ids the recording processes handed
+      # them (#1233).
+      def tuple_identity(tuple)
+        type, _id, start_line, start_column, end_line, end_column = SourceFile::RubyDataParser.call(tuple)
+        [type, start_line, start_column, end_line, end_column].freeze
       end
     end
   end

data/lib/simplecov/combine/coverage_accumulator.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require_relative "branches_combiner"
+require_relative "lines_combiner"
+require_relative "methods_combiner"
+
+module SimpleCov
+  module Combine
+    #
+    # Folds any number of resultsets' coverage into one, absorbing them one
+    # at a time so that a caller reading resultsets off disk never holds more
+    # than one in memory, and so the accumulated side can be updated in place
+    # rather than rebuilt once per resultset.
+    #
+    class CoverageAccumulator
+      # A file some process actually loaded has at least one executed line; a
+      # simulated (never-loaded) file's lines are all `nil` or `0`.
+      #
+      # `Array()` plus the `Numeric` test rather than `any?(&:positive?)`
+      # because this reads straight off a parsed resultset, which is external
+      # input and can carry anything under "lines".
+      def self.executed?(lines)
+        counts = Array(lines) #: Array[untyped]
+        counts.any? { |count| count.is_a?(Numeric) && count.positive? }
+      end
+
+      def self.fold(pairs)
+        accumulator = new
+        command_names = [] #: Array[String]
+
+        pairs.each do |names, coverage|
+          command_names.concat(names)
+          accumulator.absorb(coverage)
+        end
+
+        [command_names, accumulator.result]
+      end
+
+      def initialize
+        # Whether a criterion is enabled can't change mid-fold, so read it once
+        # here rather than once per file. `branch_coverage?` reaches
+        # `Coverage.supported?`, and a large parallel run merges thousands of
+        # files.
+        @branch_coverage = SimpleCov.branch_coverage?
+        @method_coverage = SimpleCov.method_coverage?
+      end
+
+      def absorb(coverage)
+        return self unless coverage
+
+        files = (@files ||= {}) #: Hash[String, untyped]
+        coverage.each do |filename, file_coverage|
+          files[filename] = merge_file(files[filename], file_coverage)
+        end
+
+        self
+      end
+
+      # `nil` until the first absorb, so callers can tell "no results" apart
+      # from "results that cover nothing": only the former means there is no
+      # report to build.
+      def result
+        @files&.transform_values do |entry|
+          case entry
+          when MergedFile then entry.to_h
+          else entry
+          end
+        end
+      end
+
+      private
+
+      def merge_file(existing, file_coverage)
+        case existing
+        when nil then file_coverage
+        when MergedFile then existing.absorb(file_coverage)
+        else MergedFile.new(existing, branches: @branch_coverage, methods: @method_coverage).absorb(file_coverage)
+        end
+      end
+
+      #
+      # One file's accumulated coverage.
+      #
+      # A criterion is carried for this file when the data carries it, not when
+      # this process happens to measure it: `simplecov merge` never ran
+      # SimpleCov.start at all, and dropping a table it did not ask for would
+      # lose branch data the producers did measure. A nil table means nobody
+      # measured that criterion, an empty one means it was measured and the
+      # file has none.
+      #
+      class MergedFile
+        def initialize(coverage, branches:, methods:)
+          @branch_coverage = branches
+          @method_coverage = methods
+          @lines = LinesCombiner.merge_into(nil, coverage["lines"])
+          branches_table = coverage["branches"]
+          @branches = BranchesCombiner.absorb(new_table, branches_table) if branches || branches_table
+          @methods = MethodsCombiner.absorb(nil, coverage["methods"])
+        end
+
+        def absorb(coverage)
+          reconcile_synthesized(coverage)
+          @lines = LinesCombiner.merge_into(@lines, coverage["lines"])
+          self
+        end
+
+        def to_h
+          merged = {"lines" => @lines} #: Hash[String, untyped]
+          merged["branches"] = BranchesCombiner.materialize(@branches) if @branches
+          merged["methods"] = MethodsCombiner.materialize(@methods) if @methods
+          merged
+        end
+
+        private
+
+        def new_table
+          {} #: Hash[untyped, untyped]
+        end
+
+        # When exactly one side of the merge was actually executed, its branch
+        # and method tuples are authoritative and the other side's are dropped.
+        # SimulateCoverage synthesizes those tuples statically, so a location
+        # that drifts from what Coverage emits would otherwise be unioned in by
+        # position and survive as a phantom, permanently-missed branch (#1233).
+        # Lines are never dropped: a simulated file's line shape is correct and
+        # carries the unloaded-file denominator (#1059).
+        def reconcile_synthesized(coverage)
+          incoming_lines = coverage["lines"]
+          return absorb_tuples(coverage) unless lines_measured?(@lines) && lines_measured?(incoming_lines)
+
+          incoming_executed = executed?(incoming_lines)
+
+          if executed?(@lines).equal?(incoming_executed)
+            absorb_tuples(coverage)
+          elsif incoming_executed
+            replace_tuples(coverage)
+          else
+            drop_incoming_tuples(coverage)
+          end
+        end
+
+        def absorb_tuples(coverage)
+          branches_table = coverage["branches"]
+          @branches = BranchesCombiner.absorb(@branches || new_table, branches_table) if branches_table
+          @methods = MethodsCombiner.absorb(@methods, coverage["methods"])
+        end
+
+        def drop_incoming_tuples(coverage)
+          @methods ||= {} if @method_coverage && coverage["methods"] #: Hash[untyped, untyped]
+        end
+
+        def replace_tuples(coverage)
+          @branches = authoritative_table(BranchesCombiner, coverage["branches"], @branch_coverage)
+          @methods = authoritative_table(MethodsCombiner, coverage["methods"], @method_coverage && !@methods.nil?)
+        end
+
+        def authoritative_table(combiner, table, keep_empty)
+          return combiner.absorb(new_table, table) if table
+
+          new_table if keep_empty
+        end
+
+        # Absent lines do not mean the side never ran: a branch-only or
+        # method-only run omits them even for the files it loaded.
+        def lines_measured?(lines)
+          !Array(lines).empty?
+        end
+
+        def executed?(lines)
+          CoverageAccumulator.executed?(lines)
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/combine/identity_interner.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Combine
+    # Builds the raw-key => interned-identity caches the tuple combiners keep. A
+    # key is mapped on first sight and kept: the pairwise fold would otherwise
+    # re-derive the accumulator's identities on every one of its merges, always
+    # to the same answer.
+    #
+    # Identities exist only to be hash keys, and `Array#hash` is not memoized, so
+    # keying on the identity tuple itself would rehash its elements for every key
+    # of both sides of every merge. An Integer hashes as an immediate. Two keys
+    # share an id exactly when their identities are equal, so the string and
+    # array forms of one key still merge together.
+    module IdentityInterner
+      extend self
+
+      def build
+        ids = {} #: Hash[::Array[untyped], Integer]
+        Hash.new do |cache, key|
+          identity = yield(key)
+          cache[key] = ids[identity] ||= ids.size
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/combine/interned_counts.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Combine
+    # The inner merge loop the branches and methods combiners share: folds
+    # `source`'s tuple => count pairs into `target`, an interned table keyed by
+    # each tuple's merge identity and holding `[raw_key, count]` pairs. The
+    # first-seen raw key is kept for display; counts sum. `target` and its pairs
+    # are always built by this loop, so updating them in place can't reach data a
+    # caller still holds.
+    module InternedCounts
+      extend self
+
+      def absorb_counts(target, source, identities)
+        source.each do |key, count|
+          interned = identities[key]
+          entry = target[interned]
+          if entry
+            entry[1] += count
+          else
+            target[interned] = [key, count]
+          end
+        end
+        target
+      end
+    end
+  end
+end

data/lib/simplecov/combine/lines_combiner.rb

@@ -2,41 +2,47 @@
 
 module SimpleCov
   module Combine
-    #
-    # Combine two different lines coverage results on same file
-    #
-    # Should be called through `SimpleCov.combine`.
     module LinesCombiner
-    module_function
+      extend self
 
-      def combine(coverage_a, coverage_b)
-        coverage_a
-          .zip(coverage_b)
-          .map do |coverage_a_val, coverage_b_val|
-            merge_line_coverage(coverage_a_val, coverage_b_val)
-          end
-      end
-
-      # Return depends on coverage in a specific line
-      #
-      # @param [Integer || nil] first_val
-      # @param [Integer || nil] second_val
-      #
-      # Logic:
+      # Folds `source` into `target` rather than building a third array, so only
+      # for a `target` the caller owns outright: a caller still holding a
+      # reference would see it change. `source` is never touched.
       #
-      # => nil + 0 = nil
-      # => nil + nil = nil
-      # => int + int = int
+      # Two runs of the same source file should agree on which lines are
+      # coverage-relevant (`nil` for comments, `0`+ for executable). When they
+      # don't, "relevant on either side" wins rather than masking a real `0` as
+      # `nil`, which would drop an uncovered line from the denominator:
       #
-      # @return [Integer || nil]
-      def merge_line_coverage(first_val, second_val)
-        sum = first_val.to_i + second_val.to_i
+      #   nil + nil = nil
+      #   nil + int = int (preserves a relevant-but-uncovered 0)
+      #   int + int = int (sum)
+      def merge_into(target, source)
+        return target unless source
+        return source.dup unless target
 
-        if sum.zero? && (first_val.nil? || second_val.nil?)
-          nil
-        else
-          sum
+        size = source.size
+        target.fill(nil, target.size, size - target.size)
+        sum_into(target, source, size)
+      end
+
+      # The loop is written out rather than dispatching a block per element
+      # because this is the innermost loop of a merge: a 160-worker run over
+      # ~1,800 files folds tens of millions of line counts through it.
+      #
+      # Both sides go through `to_i`, which is what keeps the merge total over
+      # external input: a count a hand-edited or foreign resultset wrote as "3" or
+      # as a JSON float merges to a wrong answer instead of raising out of the
+      # middle of a merge. On the accumulated side it doubles as the nil arm.
+      def sum_into(target, source, size)
+        index = 0
+        while index < size
+          if (value = source[index])
+            target[index] = target.at(index).to_i + value.to_i
+          end
+          index += 1
         end
+        target
       end
     end
   end

data/lib/simplecov/combine/methods_combiner.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../source_file/ruby_data_parser"
+require_relative "identity_interner"
+require_relative "interned_counts"
+
+module SimpleCov
+  module Combine
+    module MethodsCombiner
+      extend self
+
+      # Method coverage maps `[class, name, start_line, start_col, end_line,
+      # end_col]` keys to hit counts. Keys are matched on their source identity,
+      # the location alone, because Ruby records one entry per defined method: the
+      # same `define_method` block defined onto different classes, or under
+      # different names, in different processes arrives with different receivers
+      # for the same source method, and matching on the full key would keep both,
+      # letting a never-called copy's 0 shadow a covered method (#1234).
+      def combine(coverage_a, coverage_b)
+        merged = absorb({}, coverage_a) #: Hash[untyped, [untyped, Integer]]
+        materialize(absorb(merged, coverage_b))
+      end
+
+      # A `nil` `target` stays `nil` until some resultset actually carries
+      # methods, so a merge can tell "no method data anywhere" apart from "method
+      # data that covers nothing".
+      def absorb(target, coverage)
+        return target unless coverage
+
+        target ||= {} #: Hash[untyped, [untyped, Integer]]
+        InternedCounts.absorb_counts(target, coverage, identities)
+      end
+
+      def materialize(target)
+        target.values.to_h
+      end
+
+      def identities
+        @identities ||= IdentityInterner.build { |key| source_identity(key) }
+      end
+
+      def source_identity(key)
+        _class_name, _method_name, *location = SourceFile::RubyDataParser.call(key)
+        location.freeze
+      end
+    end
+  end
+end

data/lib/simplecov/combine/results_combiner.rb

@@ -1,59 +1,19 @@
 # frozen_string_literal: true
 
+require_relative "coverage_accumulator"
+
 module SimpleCov
   module Combine
-    # There might be reports from different kinds of tests,
-    # e.g. RSpec and Cucumber. We need to combine their results
-    # into unified one. This class does that.
-    # To unite the results on file basis, it leverages
-    # the combine of lines and branches inside each file within given results.
     module ResultsCombiner
-    module_function
+      extend self
 
-      #
-      # Combine process explanation
-      # => ResultCombiner: define all present files between results and start combine on file level.
-      # ==> FileCombiner: collect result of next combine levels lines and branches.
-      # ===> LinesCombiner: combine lines results.
-      # ===> BranchesCombiner: combine branches results.
-      #
-      # @return [Hash]
-      #
+      # Callers that read their results one at a time, to keep a big CI run's
+      # resultsets out of memory at once, should drive a `CoverageAccumulator`
+      # directly instead of collecting the results to pass here.
       def combine(*results)
-        results.reduce({}) do |combined_results, next_result|
-          combine_result_sets(combined_results, next_result)
-        end
-      end
-
-      #
-      # Manage combining results on files level
-      #
-      # @param [Hash] combined_results
-      # @param [Hash] result
-      #
-      # @return [Hash]
-      #
-      def combine_result_sets(combined_results, result)
-        results_files = combined_results.keys | result.keys
-
-        results_files.each_with_object({}) do |file_name, file_combination|
-          file_combination[file_name] = combine_file_coverage(
-            combined_results[file_name],
-            result[file_name]
-          )
-        end
-      end
-
-      #
-      # Combine two files coverage results
-      #
-      # @param [Hash] coverage_a
-      # @param [Hash] coverage_b
-      #
-      # @return [Hash]
-      #
-      def combine_file_coverage(coverage_a, coverage_b)
-        Combine.combine(Combine::FilesCombiner, coverage_a, coverage_b)
+        accumulator = CoverageAccumulator.new
+        results.each { |result| accumulator.absorb(result) }
+        accumulator.result || {}
       end
     end
   end