simplecov 1.1.0 → 1.2.0

data/lib/simplecov/configuration.rb

@@ -3,82 +3,81 @@
 require "fileutils"
 
 module SimpleCov
-  #
-  # Bundles the configuration options used for SimpleCov. All methods
-  # defined here are usable from SimpleCov directly. Please check out
-  # SimpleCov documentation for further info.
-  #
   module Configuration
-    #
-    # The root for the project. This defaults to the
-    # current working directory.
-    #
-    # Configure with SimpleCov.root('/my/project/path')
-    #
     def root(root = nil)
-      return @root if defined?(@root) && root.nil?
+      return @root if instance_variable_defined?(:@root) && root.nil?
 
+      self.root = root
+      @root
+    end
+
+    # nil means the working directory, the default the reader would have derived.
+    def root=(root)
       @coverage_path = nil unless @coverage_path_explicit # invalidate cache
       @root = File.expand_path(root || Dir.getwd)
     end
 
-    #
-    # The name of the output and cache directory. Defaults to 'coverage'
-    #
-    # Configure with SimpleCov.coverage_dir('cov')
-    #
     def coverage_dir(dir = nil)
-      return @coverage_dir if defined?(@coverage_dir) && dir.nil?
+      return @coverage_dir if instance_variable_defined?(:@coverage_dir) && dir.nil?
+
+      self.coverage_dir = dir
+      @coverage_dir
+    end
 
+    # nil means the default 'coverage', recorded as a derivation rather than a
+    # choice.
+    def coverage_dir=(dir)
       @coverage_path = nil unless @coverage_path_explicit # invalidate cache
       @coverage_dir_explicit = true unless dir.nil?
       @coverage_dir = dir || "coverage"
     end
 
     #
-    # Returns the full path to the output directory. By default
-    # constructed from `SimpleCov.root` + `SimpleCov.coverage_dir`, but
-    # callers can override with an arbitrary absolute path — handy for
-    # out-of-tree build directories. See #716.
+    # Defaults to `SimpleCov.root` + `SimpleCov.coverage_dir`, but callers can
+    # override with an arbitrary absolute path, handy for out-of-tree build
+    # directories (#716).
     #
-    # Reading is pure: the directory is only created when a path is
-    # explicitly assigned (the user has signaled they intend to write
-    # there). The codepaths that actually write into the directory
-    # (formatters, `LastRun`, `ResultsetStore`) ensure existence
-    # themselves, so read-only CLI subcommands that interpolate the
-    # path into status text don't materialize a stray `coverage/`
-    # directory.
+    # Reading is pure: the directory is only created when a path is explicitly
+    # assigned. The codepaths that write into it ensure existence themselves,
+    # so read-only CLI subcommands that interpolate the path into status text
+    # don't materialize a stray `coverage/` directory.
     #
     def coverage_path(path = nil)
-      if path
-        expanded = File.expand_path(path)
-        @coverage_path = expanded
-        @coverage_path_explicit = true
-        FileUtils.mkdir_p expanded
-      end
+      self.coverage_path = path if path
 
       @coverage_path ||= File.expand_path(coverage_dir, root)
     end
 
+    # Assigning is the signal the caller intends to write there, so the
+    # directory is created.
+    def coverage_path=(path)
+      expanded = File.expand_path(path)
+      @coverage_path = expanded
+      @coverage_path_explicit = true
+      FileUtils.mkdir_p expanded
+    end
+
     #
-    # The name of the command (a.k.a. Test Suite) currently running.
-    # Used for result merging and caching. Auto-detected; set explicitly
-    # with SimpleCov.command_name("test:units").
+    # The name of the command (a.k.a. Test Suite) currently running. Used for
+    # result merging and caching. Auto-detected.
     #
     def command_name(name = nil)
-      @command_name = name unless name.nil?
-      @command_name ||= SimpleCov::CommandGuesser.guess
+      self.command_name = name unless name.nil?
+      @command_name ||= CommandGuesser.guess
+    end
+
+    def command_name=(name)
+      @command_name = name
     end
 
-    # Returns the hash of available profiles
     def profiles
-      @profiles ||= SimpleCov::Profiles.new
+      @profiles ||= Profiles.new
     end
 
     #
-    # Allows you to configure simplecov in a block instead of
-    # prepending SimpleCov to each config method. Parameterized blocks retain
-    # their caller context and receive this configuration target explicitly.
+    # Configure simplecov in a block instead of prepending SimpleCov to each
+    # config method. Parameterized blocks retain their caller context and
+    # receive this configuration target explicitly.
     #
     def configure(&block)
       raise ArgumentError, "configuration block required" unless block
@@ -91,61 +90,49 @@ module SimpleCov
       self
     end
 
-    #
-    # Gets or sets the behavior to process coverage results.
-    # By default, it stores/merges the current result and formats only
-    # from the final reporting process.
-    #
     def at_exit(&block)
       @at_exit = block if block
       configured = @at_exit
       return configured if configured
-      return proc {} unless active_session?
+      return -> {} unless active_session?
 
-      @at_exit = proc do
+      @at_exit = lambda do
         result = SimpleCov.result
         result.format! if result && SimpleCov.merge_finalization_owner?
       end
     end
 
-    # Whether SimpleCov has anything to do at exit: the Coverage module
-    # is actively tracking, or a `@result` has already been assembled
-    # (e.g. by `SimpleCov.collate`, which never starts Coverage).
+    # The Coverage module is actively tracking, or a `@result` has already been
+    # assembled (`SimpleCov.collate` never starts Coverage).
     def active_session?
-      SimpleCov.result? || (defined?(Coverage) && Coverage.running?)
+      !!SimpleCov.result? || coverage_running?
+    end
+
+    # A configuration loaded on its own may have no Coverage to ask, which is
+    # not something a suite that measures coverage can be.
+    def coverage_running?
+      defined?(Coverage) ? Coverage.running? : false
     end
 
-    #
-    # Gets or sets the behavior to start a new forked Process.
-    # Defaults to adding " (subprocess: #{serial})" to command_name and
-    # starting SimpleCov in quiet mode.
-    #
     def at_fork(&block)
       @at_fork = block if block
       @at_fork ||= lambda { |_pid|
-        # Needs a name that's unique per worker within a run yet identical
-        # across runs. Build it from SimpleCov's stable fork serial rather
-        # than the OS pid: with the pid, every run produced uniquely-named
-        # results that never overwrote the previous run's, so they piled up
-        # in .resultset.json until merge_timeout and the merged report's
-        # file set drifted from run to run. See issue #1171.
+        # Needs a name that's unique per worker within a run yet identical across
+        # runs. Built from SimpleCov's stable fork serial rather than the OS pid:
+        # with the pid, every run produced uniquely-named results that never
+        # overwrote the previous run's, so they piled up in .resultset.json
+        # until merge_timeout and the merged report's file set drifted from run
+        # to run (#1171).
         SimpleCov.command_name "#{SimpleCov.command_name} (subprocess: #{SimpleCov.subprocess_serial})"
-        # be quiet, the parent process will use the regular formatter
         SimpleCov.print_errors false
-        SimpleCov.formatter SimpleCov::Formatter::SimpleFormatter
+        SimpleCov.formatter Formatter::SimpleFormatter
         SimpleCov.minimum_coverage 0
         SimpleCov.start
       }
     end
 
-    #
-    # Returns the project name — defaults to the last dirname in
-    # SimpleCov.root, capitalized with underscores → spaces.
-    #
+    # Only a String renames, and a name already chosen survives anything else.
     def project_name(new_name = nil)
-      current = defined?(@project_name) ? @project_name : nil
-      return current if current && new_name.nil?
-
       @project_name = new_name if new_name.is_a?(String)
       @project_name ||= File.basename(root).capitalize.tr("_", " ")
     end
@@ -160,4 +147,11 @@ require_relative "configuration/groups"
 require_relative "configuration/formatting"
 require_relative "configuration/ignored_entries"
 require_relative "configuration/merging"
+require_relative "configuration/test_tracking"
 require_relative "configuration/thresholds"
+require_relative "configuration/baseline"
+require_relative "configuration/deprecations"
+require_relative "configuration/history"
+require_relative "configuration/missed_caps"
+require_relative "configuration/production"
+require_relative "configuration/view_coverage"

data/lib/simplecov/configuration_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  class ConfigurationError < StandardError; end
+end

data/lib/simplecov/context_map/union.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  class ContextMap
+    # Accumulates the context maps of every result a merge absorbs, under the
+    # all-or-nothing rule the resultset format needs: the merged result carries
+    # the union of the maps when every merged result recorded one, and no map at
+    # all otherwise. Keeping a partial union would present one worker's map as
+    # the whole run's, silently omitting the tests of the results that didn't
+    # record.
+    class Union
+      attr_reader :carrying, :entries
+
+      def initialize
+        @map = ContextMap.new
+        @complete = true
+        @carrying = 0
+        @entries = 0
+      end
+
+      def collector
+        ->(surviving) { absorb_resultset(surviving) }
+      end
+
+      def absorb_resultset(resultset)
+        resultset.each_value { |data| absorb_entry(data) }
+      end
+
+      def absorb_entry(data)
+        @entries += 1
+        map = ContextMap.from_hash(data["contexts"])
+        return @complete = false unless map
+
+        @carrying += 1
+        @map.absorb(map)
+      end
+
+      # The parallel merge builds one union per worker over its slice and ships it
+      # back, so the parent combines unions rather than re-reading entries.
+      def absorb_union(other)
+        @entries += other.entries
+        @carrying += other.carrying
+        @complete &&= other.complete?
+        @map.absorb(other.partial_map)
+        self
+      end
+
+      def complete?
+        @complete
+      end
+
+      # The union when every absorbed result carried a map, nil otherwise. Dropping
+      # warns when the merge mixed results with and without maps, since that
+      # usually means `track_tests` is on in some workers and not others; a merge
+      # where nothing recorded stays quiet.
+      def map
+        return @map if @complete
+
+        warn_about_partial_maps
+      end
+
+      protected
+
+      # Protected: only another union folding this one in may read it.
+      def partial_map
+        @map
+      end
+
+      private
+
+      def warn_about_partial_maps
+        return unless @carrying.positive? && SimpleCov.print_errors
+
+        warn "[SimpleCov]: Dropped the per-test map from the merged result: " \
+             "only #{@carrying} of #{@entries} merged results carry one. The map is " \
+             "kept only when every merged result records it, so enable `track_tests` " \
+             "in every suite that should contribute."
+      end
+    end
+  end
+end

data/lib/simplecov/context_map.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  #
+  # Records which context covered which line: a list of context ids and, per
+  # source file, a bitmap of covered lines for each context that touched the
+  # file. A context is any labeled region of execution, and the vocabulary is
+  # deliberately the general one (coverage.py calls the same idea dynamic
+  # contexts), so the stored format doesn't bake simplecov's current use into
+  # a name.
+  #
+  # The naive shape of this data, a list of ids on every line, is
+  # O(contexts x lines) strings. Context ids are interned instead, and each
+  # context's covered lines within a file are a single Integer bitmap with bit
+  # N set when line N+1 was executed, which packs a thousand-line file into
+  # ~125 bytes and makes the union of two recordings a bitwise OR.
+  #
+  # Serialized into `.resultset.json` as `{"version" => 1, "contexts" =>
+  # [...ids...], "files" => {path => {context index => bitmap as hex}}}`. The
+  # format is tolerated, not trusted: `.from_hash` returns nil for anything
+  # malformed or future-versioned, which the merge treats the same as a map
+  # that was never recorded.
+  #
+  class ContextMap
+    # Bumped on any change an older reader could misread, so `.from_hash` can
+    # treat a future format as absent instead of answering from it wrongly.
+    VERSION = 1
+
+    def initialize
+      @contexts = [] #: Array[String]
+      @indices = {} #: Hash[String, Integer]
+      @files = {} #: Hash[String, Hash[Integer, Integer]]
+    end
+
+    # `lines_by_file` maps a source path to the bitmap of lines the context
+    # executed there. The id is interned even when the delta is empty: the
+    # context ran, and keeping it distinguishes "covered nothing of its own"
+    # from "never recorded".
+    def record(context_id, lines_by_file)
+      index = intern(context_id)
+      lines_by_file.each do |path, bitmap|
+        next if bitmap.zero?
+
+        table = (@files[path] ||= {})
+        table[index] = (table[index] || 0) | bitmap
+      end
+      self
+    end
+
+    # Sorted for stable output, since recording order varies between runs and
+    # merges. The path is resolved against `SimpleCov.root`, so callers can
+    # pass either an absolute or a project-relative one.
+    #
+    # A line number below 1 needs no guard of its own: it shifts the probe bit
+    # right off the end of the bitmap, leaving a mask no line can match.
+    def covering(path, line)
+      table = @files[File.expand_path(path, SimpleCov.root)]
+      return [] unless table
+
+      bit = 1 << (line - 1)
+      table.filter_map { |index, bitmap| @contexts.fetch(index) if bitmap.anybits?(bit) }.sort
+    end
+
+    def contexts
+      @contexts.dup
+    end
+
+    def empty?
+      @contexts.empty?
+    end
+
+    # Other's contexts are re-interned, so maps recorded by different processes
+    # merge by id, and a context both sides saw contributes one entry.
+    def absorb(other)
+      remap = other.interned_contexts.map { |context_id| intern(context_id) }
+      other.file_tables.each do |path, table|
+        target = (@files[path] ||= {})
+        table.each do |index, bitmap|
+          key = remap.fetch(index)
+          target[key] = (target[key] || 0) | bitmap
+        end
+      end
+      self
+    end
+
+    # `only:` restricts the files to a given set of paths, so the map follows
+    # the same universe as the coverage it sits beside. The context list is
+    # never restricted: which contexts ran is true regardless of which files
+    # survived filtering.
+    def to_h(only: nil)
+      # Selected rather than sliced: `only` is a Set, and splatting one into
+      # `slice` is a call `to_a` answers for, which makes dropping the `to_a` a
+      # mutation nothing can observe.
+      tables = only ? @files.select { |path, _table| only.include?(path) } : @files # rubocop:disable Style/HashSlice
+      serialized = tables.transform_values { |table| serialize_table(table) }
+      {"version" => VERSION, "contexts" => @contexts.dup, "files" => serialized}
+    end
+
+    # Index string => hex bitmap, the wire encoding `to_h` writes.
+    # coverage.json shares the resultset's encoding through this, so the format
+    # has one owner.
+    def serialized_bitmaps_for(path)
+      serialize_table(@files[File.expand_path(path, SimpleCov.root)] || {})
+    end
+
+    # @api private
+    def intern(context_id)
+      @indices[context_id] ||= begin
+        @contexts << context_id
+        @contexts.size - 1
+      end
+    end
+
+    class << self
+      # nil when the data is not a well-formed map of this format version.
+      # All-or-nothing on purpose: a partially salvaged map would answer
+      # `covering` queries with silent gaps, and the merge already drops an
+      # absent map consistently.
+      def from_hash(data)
+        # `eql?` rather than `==`: a version written as 1.0 is not this format,
+        # and reading it as if it were is what the version gate exists to stop.
+        return nil unless data.instance_of?(Hash) && data["version"].eql?(VERSION)
+
+        contexts = data["contexts"]
+        files = data["files"]
+        return nil unless contexts.instance_of?(Array) && contexts.all?(String) && files.instance_of?(Hash)
+
+        build(contexts, files)
+      end
+
+      private
+
+      def build(contexts, files)
+        map = new
+        contexts.each { |context_id| map.intern(context_id) }
+        files.each do |path, table|
+          return nil unless path.instance_of?(String) && table.instance_of?(Hash)
+          return nil unless absorb_table(map, contexts, path, table)
+        end
+        map
+      end
+
+      def absorb_table(map, contexts, path, table)
+        table.all? do |index, encoded|
+          position = parse_index(index, contexts.size)
+          bitmap = parse_bitmap(encoded)
+          map.record(contexts.fetch(position), path => bitmap) if position && bitmap
+        end
+      end
+
+      # A serialized context index is a decimal string pointing into the entry's
+      # own context list. An out-of-range one makes the whole map malformed.
+      def parse_index(index, size)
+        return nil unless index.instance_of?(String) && index.match?(/\A\d+\z/)
+
+        value = index.to_i
+        value if value < size
+      end
+
+      def parse_bitmap(encoded)
+        return nil unless encoded.instance_of?(String) && encoded.match?(/\A\h+\z/)
+
+        encoded.to_i(16)
+      end
+    end
+
+    private
+
+    # Sorted by index: recording and merge order vary run to run, and a
+    # deterministic serialization keeps stored resultsets diffable.
+    def serialize_table(table)
+      table.sort.to_h { |index, bitmap| [index.to_s, bitmap.to_s(16)] }
+    end
+
+    protected
+
+    # Live state, not copies, which is why these are protected rather than
+    # public.
+    def interned_contexts
+      @contexts
+    end
+
+    def file_tables
+      @files
+    end
+  end
+end

data/lib/simplecov/coverage_json.rb

@@ -3,9 +3,6 @@
 require "json"
 
 module SimpleCov
-  # Shared parser for coverage.json consumers. It enforces the encoding and
-  # stable outermost shape while leaving command- or viewer-specific fields to
-  # their respective callers.
   module CoverageJSON
     class Error < StandardError; end
 
@@ -14,11 +11,11 @@ module SimpleCov
       raise Error, "input is not valid UTF-8" unless source.valid_encoding?
 
       document = JSON.parse(source)
-      return document if document.is_a?(Hash)
+      return document if document.instance_of?(Hash)
 
       raise Error, "top-level value must be an object"
     rescue JSON::ParserError => e
-      raise Error, e.message
+      raise Error, e
     end
   end
 end

data/lib/simplecov/coverage_statistics.rb

@@ -1,22 +1,17 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Holds the individual data of a coverage result.
-  #
-  # This is uniform across coverage criteria as they all have:
-  #
-  # * total - how many things to cover there are (total relevant loc/branches)
-  # * covered - how many of the coverables are hit
-  # * missed - how many of the coverables are missed
-  # * omitted - how many lines cannot be covered (blank lines/comments); only meaningful for line coverage
-  # * percent - percentage as covered/missed
-  # * strength - average hits per coverable unit (will not exist for one shot lines format)
+  # One coverage criterion's numbers, uniform across criteria: total, covered,
+  # missed, omitted (only meaningful for line coverage), percent, and strength,
+  # the average hits per coverable unit, which the oneshot-lines format has no
+  # way to produce.
   class CoverageStatistics
     attr_reader :total, :covered, :missed, :omitted, :strength, :percent
 
-    # Seed for the reduce in `.from`: covered, missed, omitted, strength.
     ZERO_STATS = [0, 0, 0, 0.0].freeze #: [Integer, Integer, Integer, Float]
 
+    # Strength is remultiplied by loc because files have different strengths and
+    # line counts, giving them a different weight in the total.
     def self.from(coverage_statistics)
       sum_covered, sum_missed, sum_omitted, sum_total_strength =
         coverage_statistics.reduce(ZERO_STATS) do |(covered, missed, omitted, total_strength), stats|
@@ -24,8 +19,6 @@ module SimpleCov
             covered + stats.covered,
             missed + stats.missed,
             omitted + stats.omitted,
-            # gotta remultiply with loc because files have different strength and loc
-            # giving them a different "weight" in total
             total_strength + (stats.strength * stats.total)
           ]
         end
@@ -33,19 +26,16 @@ module SimpleCov
       new(covered: sum_covered, missed: sum_missed, omitted: sum_omitted, total_strength: sum_total_strength)
     end
 
-    # Requires only covered, missed and strength to be initialized.
-    #
-    # Other values are computed by this class.
-    def initialize(covered:, missed:, omitted: 0, total_strength: 0.0, percent: nil)
-      @covered  = covered
-      @missed   = missed
-      @omitted  = omitted
-      @total    = covered + missed
-      @percent  = percent || compute_percent(covered, missed, total)
+    def initialize(covered:, missed:, omitted: 0, total_strength: 0, percent: nil)
+      @covered = covered
+      @missed = missed
+      @omitted = omitted
+      @total = covered + missed
+      @percent = percent || compute_percent(covered, missed, total)
       @strength = compute_strength(total_strength, total)
     end
 
-  private
+    private
 
     def compute_percent(covered, missed, total)
       return 100.0 if missed.zero?
@@ -56,7 +46,7 @@ module SimpleCov
     def compute_strength(total_strength, total)
       return 0.0 if total.zero?
 
-      total_strength.to_f / total
+      total_strength.fdiv(total)
     end
   end
 end