simplecov 1.1.1 → 1.3.0

data/lib/simplecov/combine/methods_combiner.rb

@@ -6,44 +6,24 @@ require_relative "interned_counts"
 
 module SimpleCov
   module Combine
-    #
-    # Combine different method coverage results on a single file.
-    #
-    # Should be called through `CoverageAccumulator`.
     module MethodsCombiner
-    module_function
+      extend self
 
-      #
-      # Return merged methods or the existing methods if other is missing.
-      #
       # 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, ignoring the class and name elements —
-      # 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 or names 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 after merge (issue #1234). Combining sums the hit
-      # counts for matching methods and preserves methods that only appear
-      # in one result.
-      #
-      # @return [Hash]
-      #
+      # 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
 
-      # Folds `coverage` into `target`, an interned table keyed by method
-      # source identity. See `BranchesCombiner.absorb` for why a fold keeps
-      # its accumulator interned.
-      #
       # 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".
-      #
-      # @return [Hash, nil] `target`, created on the first coverage seen
+      # 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
 
@@ -51,16 +31,10 @@ module SimpleCov
         InternedCounts.absorb_counts(target, coverage, identities)
       end
 
-      # Turns an interned table back into the tuple-keyed hash the rest of
-      # SimpleCov reads. Done once, at the end of a fold.
-      #
-      # @return [Hash]
       def materialize(target)
         target.values.to_h
       end
 
-      # Bounded by the project's method count, like `RubyDataParser`'s parse
-      # cache.
       def identities
         @identities ||= IdentityInterner.build { |key| source_identity(key) }
       end

data/lib/simplecov/combine/results_combiner.rb

@@ -4,29 +4,12 @@ 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
-      # => ResultsCombiner: hand every result to one accumulator.
-      # ==> CoverageAccumulator::MergedFile: hold one file's merged coverage.
-      # ===> LinesCombiner: combine lines results.
-      # ===> BranchesCombiner: combine branches results.
-      # ===> MethodsCombiner: combine methods results.
-      #
-      # Callers that read their results one at a time (`ResultMerger`, to
-      # keep a big CI run's resultsets out of memory all at once) should
-      # drive a `CoverageAccumulator` directly instead of collecting the
-      # results to pass here.
-      #
-      # @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)
         accumulator = CoverageAccumulator.new
         results.each { |result| accumulator.absorb(result) }

data/lib/simplecov/combine.rb

@@ -1,12 +1,6 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Namespace for the pieces that combine coverage results.
-  #
-  # `CoverageAccumulator` is the entry point: it folds any number of
-  # resultsets together, delegating one file's lines, branches and methods to
-  # the combiner modules alongside it.
-  #
   module Combine
   end
 end

data/lib/simplecov/command_guesser.rb

@@ -1,16 +1,11 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  #
-  # Helper that tries to find out what test suite is running (for SimpleCov.command_name)
-  #
   module CommandGuesser
     class << self
-      # Storage for the original command line call that invoked the test suite.
-      # This has got to be stored as early as possible because i.e. rake and test/unit 2
-      # have a habit of tampering with ARGV, which makes i.e. the automatic distinction
-      # between rails unit/functional/integration tests impossible without this cached
-      # item.
+      # The original command line call that invoked the test suite. This has to
+      # be stored as early as possible because rake and test/unit 2 have a habit
+      # of tampering with ARGV.
       attr_reader :original_run_command
 
       # Assigning the flattened command clears any separately recorded program
@@ -37,10 +32,10 @@ module SimpleCov
         [framework, parallel_data].compact.join(" ")
       end
 
-    private
+      private
 
-      # When parallel_tests (or a compatible runner) is driving the suite,
-      # tag the command name with this worker's position in the pool.
+      # When parallel_tests (or a compatible runner) is driving the suite, tag
+      # the command name with this worker's position in the pool.
       def parallel_data
         groups, number = ENV.values_at("PARALLEL_TEST_GROUPS", "TEST_ENV_NUMBER")
         return unless groups && number
@@ -52,17 +47,14 @@ module SimpleCov
       end
 
       # The command is `"#{$PROGRAM_NAME} #{ARGV.join(' ')}"`, so a keyword only
-      # carries meaning when it begins a path segment or an argument. Matching it
-      # as a bare substring lets any part of the *interpreter* path decide the
+      # carries meaning when it begins a path segment or an argument. Matching
+      # it as a bare substring lets any part of the interpreter path decide the
       # suite name: a Ruby installed under `latest/bin` (as mise does) contains
-      # "test/", so every run through it was labelled "Unit Tests". The same
-      # applies within ARGV, where `spec/greatest/` used to match just as wrongly.
+      # "test/", so every run through it was labelled "Unit Tests".
       #
       # A backslash bounds a segment too, or a Windows `spec\foo_spec.rb` would
-      # lose a match the bare substrings used to make. The `test/` patterns below
-      # still spell their separator as `/` only, so a backslash `test\functional\`
-      # goes unrecognised there, but that is how it has always been rather than
-      # something the anchoring took away.
+      # lose a match. The `test/` patterns below still spell their separator as
+      # `/` only, which is how it has always been.
       SEGMENT_START = %r{(?<![^\s/\\])}
       private_constant :SEGMENT_START
       SEGMENT_END = %r{(?=[\s/\\]|\z)}
@@ -80,15 +72,16 @@ module SimpleCov
       private_constant :COMMAND_LINE_FRAMEWORKS
 
       def from_command_line_options
-        COMMAND_LINE_FRAMEWORKS.find { |pattern, _| pattern.match?(original_run_command.to_s) }&.last
+        # A command that was never recorded matches nothing, which `match?`
+        # answers for a nil of its own accord.
+        COMMAND_LINE_FRAMEWORKS.find { |pattern, _| pattern.match?(original_run_command) }&.last
       end
 
       # Which binary was invoked outranks everything else on the command line.
       # `rspec features` is an RSpec suite whose examples live in features/, not
       # a Cucumber run, and only the executable name says so. Generic runners
       # (`ruby`, `rake`, a bare `*_test.rb` script) are absent on purpose: they
-      # name no framework, so those runs fall through to the path patterns, which
-      # is what keeps the test/functional vs test/integration split working.
+      # name no framework, so those runs fall through to the path patterns.
       EXECUTABLE_FRAMEWORKS = {
         "rspec" => "RSpec",
         "cucumber" => "Cucumber Features"
@@ -99,36 +92,29 @@ module SimpleCov
         program = original_program_name
         return unless program
 
-        # Trim any extension so Windows' rspec.bat is recognized too.
+        # The extension is trimmed so Windows' rspec.bat is recognized too.
         EXECUTABLE_FRAMEWORKS[File.basename(program, ".*")]
       end
 
       # Inner array literals after the first are flagged uncovered by Ruby's
-      # Coverage module even though the constant evaluates as a whole — known
+      # Coverage module even though the constant evaluates as a whole, a known
       # quirk with multi-line array literals.
       DEFINED_CONSTANT_FRAMEWORKS = [
-        ["RSpec",      -> { defined?(::RSpec) }],
+        ["RSpec", -> { defined?(::RSpec) }],
         ["Unit Tests", -> { defined?(Test::Unit) }],   # simplecov:disable
-        ["Minitest",   -> { defined?(::Minitest) }],   # simplecov:disable
-        ["MiniTest",   -> { defined?(MiniTest) }]      # simplecov:disable
+        ["Minitest", -> { defined?(::Minitest) }],   # simplecov:disable
+        ["MiniTest", -> { defined?(MiniTest) }]      # simplecov:disable
       ].freeze
       private_constant :DEFINED_CONSTANT_FRAMEWORKS
 
-      # If the command regexps fail, let's try checking defined constants.
       def from_defined_constants
-        # simplecov:disable branch — first iter returns when ::RSpec is defined; later branches unreachable
         DEFINED_CONSTANT_FRAMEWORKS.each { |name, defined_check| return name if defined_check.call }
-        # simplecov:enable branch
 
-        # TODO: Provide link to docs/wiki article
-        # simplecov:disable — only fires when no framework is detected, which
-        # is impossible while our own specs are running under rspec
         warn(
           "SimpleCov failed to recognize the test framework and/or suite used. " \
           "Please specify manually using SimpleCov.command_name 'Unit Tests'."
         )
         "Unknown Test Framework"
-        # simplecov:enable
       end
     end
   end

data/lib/simplecov/configuration/baseline.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    # The baseline's path, relative to `SimpleCov.root`; an absolute path is
+    # honored as given. The file's presence is the opt-in: generate it with
+    # `simplecov ratchet`, check it in, and the exit check holds every listed
+    # file to its own floor (#1268).
+    def baseline_file(path = nil)
+      return @baseline_file ||= Baseline::DEFAULT_FILENAME unless path
+
+      self.baseline_file = path
+      _ = @baseline_file
+    end
+
+    def baseline_file=(path)
+      @baseline_file = path
+    end
+
+    # Memoized per resolved path so the exit check and the JSON formatter's
+    # errors section read the file once, while a `baseline_file` or `root` change
+    # between reads is still picked up.
+    def baseline
+      resolved = File.expand_path(baseline_file, root)
+      return @baseline if @baseline_path.eql?(resolved)
+
+      @baseline_path = resolved
+      @baseline = Baseline.read_if_exists(resolved)
+    end
+  end
+end

data/lib/simplecov/configuration/coverage.rb

@@ -1,49 +1,13 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # The `coverage` configuration method configures each coverage criterion
-  # (`:line`, `:branch`, `:method`, `:eval`) uniformly in one place: naming a
-  # criterion enables it,
-  # and every threshold is declared with the same syntax regardless of which
-  # criterion it applies to. Because the criterion is fixed by the enclosing
-  # `coverage` call, threshold values are always plain percentages — there is
-  # no per-criterion Hash competing with the value for a slot.
-  #
-  #   SimpleCov.start do
-  #     coverage :line do
-  #       minimum          90
-  #       minimum_per_file 80
-  #       minimum_per_file 100, only: "app/mailers/request_mailer.rb"
-  #       maximum_drop     5
-  #     end
-  #
-  #     coverage :branch, minimum: 80
-  #     coverage :method, minimum: 100
-  #   end
-  #
-  # Line coverage is enabled by default, so `coverage :line` is only needed to
-  # set line thresholds or options. Thresholds feed the same internal stores
-  # as the flat `minimum_coverage` family, so enforcement is unchanged.
   module Configuration
-    # One-liner keyword options `coverage` accepts, each forwarding to the
-    # `CoverageCriterion` verb of the same name. `minimum_per_group` is omitted
-    # because it needs an `only:` target, so it's block-only.
-    COVERAGE_THRESHOLD_OPTIONS = %i[minimum maximum exact maximum_drop minimum_per_file].freeze
+    COVERAGE_THRESHOLD_OPTIONS = %i[minimum maximum exact maximum_drop ignore minimum_per_file
+      maximum_missed maximum_missed_per_file].freeze
 
-    #
-    # Configure (and, unless `enabled: false`, enable) a coverage criterion.
-    #
-    # Threshold options mirror the block verbs for one-liner use:
-    #   coverage :branch, minimum: 80, maximum_drop: 5
-    #
-    # `primary: true` makes this the report's leading criterion (and the one a
-    # bare `minimum_coverage 90` targets). `oneshot: true` (valid only for
-    # `:line`) selects the faster oneshot-lines mode.
-    #
     def coverage(criterion, primary: false, enabled: true, oneshot: false, **thresholds, &block)
       criterion = enable_coverage_criterion(criterion, enabled: enabled, oneshot: oneshot)
-      # The cast admits :eval, which primary_coverage rejects at runtime
-      # (it is a standalone toggle, never in the enabled-criteria set).
+      # The cast admits :eval, which primary_coverage rejects at runtime.
       primary_coverage(_ = criterion) if primary
 
       configurator = CoverageCriterion.new(self, criterion)
@@ -53,25 +17,20 @@ module SimpleCov
       criterion
     end
 
-  private
+    private
 
-    # Forward the one-liner threshold keywords (`coverage :branch, minimum: 80`)
-    # to the matching `CoverageCriterion` verbs, rejecting anything that isn't a
-    # recognized threshold option.
     def apply_threshold_options(configurator, options)
       options.each do |verb, value|
         unless COVERAGE_THRESHOLD_OPTIONS.include?(verb)
-          raise SimpleCov::ConfigurationError,
-                "Unknown `coverage` option #{verb.inspect}. " \
-                "Supported options are #{COVERAGE_THRESHOLD_OPTIONS.inspect}."
+          raise ConfigurationError,
+            "Unknown `coverage` option #{verb.inspect}. " \
+            "Supported options are #{COVERAGE_THRESHOLD_OPTIONS.inspect}."
         end
 
         configurator.public_send(verb, value)
       end
     end
 
-    # Enable or disable the criterion (or its oneshot / eval variant) and
-    # return the criterion symbol that thresholds should be stored under.
     def enable_coverage_criterion(criterion, enabled:, oneshot:)
       criterion = resolve_criterion_variant(criterion, oneshot)
       enabled ? enable_coverage(criterion) : disable_coverage(criterion)
@@ -81,27 +40,41 @@ module SimpleCov
     def resolve_criterion_variant(criterion, oneshot)
       return criterion unless oneshot
 
-      unless criterion == :line
-        raise SimpleCov::ConfigurationError, "`oneshot: true` is only valid for `coverage :line`"
-      end
+      raise ConfigurationError, "`oneshot: true` is only valid for `coverage :line`" unless criterion.equal?(:line)
 
       ONESHOT_LINE_COVERAGE_CRITERION
     end
 
-    # @api private — threshold-store writers used by CoverageCriterion. They
-    # write the same `@minimum_coverage` / `@maximum_coverage` / ... hashes the
-    # flat threshold methods populate, so the exit-code checks are unchanged.
+    # @api private
     def store_overall_threshold(setting, criterion, percent)
-      raise_on_invalid_coverage({criterion => percent}, setting.to_s)
+      raise_on_invalid_coverage({criterion => percent}, setting)
       public_send(setting)[criterion] = percent
     end
 
+    def store_missed_cap(setting, criterion, count)
+      raise_if_criterion_disabled(criterion)
+      raise_on_invalid_missed_cap(count, setting)
+      public_send(setting)[criterion] = count
+    end
+
+    def store_maximum_missed_per_file(criterion, count, target)
+      raise_if_criterion_disabled(criterion)
+      raise_on_invalid_missed_cap(count, "maximum_missed_per_file")
+      return maximum_missed_per_file[criterion] = count if target.nil?
+
+      unless target.is_a?(String) || target.is_a?(Regexp)
+        raise ConfigurationError, "`only:` must be a String path or Regexp, got #{target.inspect}"
+      end
+
+      (maximum_missed_per_file_overrides[target] ||= {})[criterion] = count
+    end
+
     def store_minimum_per_file(criterion, percent, target)
       raise_on_invalid_coverage({criterion => percent}, "minimum_coverage_by_file")
       return minimum_coverage_by_file[criterion] = percent if target.nil?
 
       unless target.is_a?(String) || target.is_a?(Regexp)
-        raise SimpleCov::ConfigurationError, "`only:` must be a String path or Regexp, got #{target.inspect}"
+        raise ConfigurationError, "`only:` must be a String path or Regexp, got #{target.inspect}"
       end
 
       (minimum_coverage_by_file_overrides[target] ||= {})[criterion] = percent
@@ -109,17 +82,13 @@ module SimpleCov
 
     def store_minimum_per_group(criterion, percent, group_name)
       raise_on_invalid_coverage({criterion => percent}, "minimum_coverage_by_group")
-      # Normalize like `group` does, so `only: :Models` finds the group
-      # defined as `group "Models"` at check time instead of storing a
-      # Symbol key no lookup ever matches.
+      # Normalized like `group` does, so `per: group(:Models)` finds the group
+      # defined as `group "Models"` at check time.
       (minimum_coverage_by_group[GroupNames.normalize(group_name)] ||= {})[criterion] = percent
     end
 
     #
-    # Receiver for a `coverage <criterion> do ... end` block. Each verb writes a
-    # threshold for the single criterion the block configures, so the value is
-    # always a plain percentage (`minimum_per_file 100` is unambiguous) and the
-    # syntax is identical across line, branch, and method coverage.
+    # Receiver for a `coverage <criterion> do ... end` block.
     #
     class CoverageCriterion
       def initialize(config, criterion)
@@ -127,46 +96,89 @@ module SimpleCov
         @criterion = criterion
       end
 
-      # Overall (suite-wide) minimum for this criterion.
-      def minimum(percent)
-        @config.send(:store_overall_threshold, :minimum_coverage, @criterion, percent)
+      def minimum(percent, per: nil)
+        case per
+        when nil then @config.__send__(:store_overall_threshold, :minimum_coverage, @criterion, percent)
+        when :file then @config.__send__(:store_minimum_per_file, @criterion, percent, nil)
+        when String, Regexp then @config.__send__(:store_minimum_per_file, @criterion, percent, per)
+        when GroupTarget then @config.__send__(:store_minimum_per_group, @criterion, percent, per.name)
+        else raise_invalid_per(per)
+        end
       end
 
-      # Overall maximum: fails the build if coverage rises above it. Paired with
-      # `minimum` (or via `exact`) this pins coverage so an unexpected jump fails.
       def maximum(percent)
-        @config.send(:store_overall_threshold, :maximum_coverage, @criterion, percent)
+        @config.__send__(:store_overall_threshold, :maximum_coverage, @criterion, percent)
       end
 
-      # Pin coverage to an exact figure (sets both `minimum` and `maximum`).
       def exact(percent)
         minimum(percent)
         maximum(percent)
       end
 
-      # Maximum allowed drop between runs (`maximum_drop 0` refuses any drop).
       def maximum_drop(percent)
-        @config.send(:store_overall_threshold, :maximum_coverage_drop, @criterion, percent)
+        @config.__send__(:store_overall_threshold, :maximum_coverage_drop, @criterion, percent)
+      end
+
+      def maximum_missed(count, per: nil)
+        case per
+        when nil then @config.__send__(:store_missed_cap, :maximum_missed, @criterion, count)
+        when :file then @config.__send__(:store_maximum_missed_per_file, @criterion, count, nil)
+        when String, Regexp then @config.__send__(:store_maximum_missed_per_file, @criterion, count, per)
+        when GroupTarget
+          raise ConfigurationError,
+            "maximum_missed does not support `per: group(...)` yet; see docs/Roadmap.md"
+        else raise_invalid_per(per)
+        end
+      end
+
+      def group(name)
+        GroupTarget.new(name: name)
+      end
+
+      # The flatten serves the one-liner keyword form, whose value arrives as a
+      # single argument (`ignore: %i[implicit_else]`).
+      def ignore(*types)
+        case @criterion
+        when :branch then @config.__send__(:store_ignored_branches, types.flatten)
+        when :method then @config.__send__(:store_ignored_methods, types.flatten)
+        else
+          raise ConfigurationError,
+            "`ignore` is supported for `coverage :branch` and `coverage :method`, not #{@criterion.inspect}"
+        end
       end
 
-      # Per-file minimum. With no `only:`, sets the default applied to every
-      # file; with `only:` (a String path or Regexp), overrides that default
-      # for the matching files.
       def minimum_per_file(percent, only: nil)
-        @config.send(:store_minimum_per_file, @criterion, percent, only)
+        Deprecation.warn("`minimum_per_file` is deprecated. " \
+                         "Replace with `minimum #{percent}, per: #{(only || :file).inspect}`.")
+        @config.__send__(:store_minimum_per_file, @criterion, percent, only)
       end
 
-      # Per-group minimum for the named group (defined via `group`).
       def minimum_per_group(percent, only:)
-        @config.send(:store_minimum_per_group, @criterion, percent, only)
+        Deprecation.warn("`minimum_per_group` is deprecated. " \
+                         "Replace with `minimum #{percent}, per: group(#{only.inspect})`.")
+        @config.__send__(:store_minimum_per_group, @criterion, percent, only)
+      end
+
+      def maximum_missed_per_file(count, only: nil)
+        Deprecation.warn("`maximum_missed_per_file` is deprecated. " \
+                         "Replace with `maximum_missed #{count}, per: #{(only || :file).inspect}`.")
+        @config.__send__(:store_maximum_missed_per_file, @criterion, count, only)
       end
 
-      # Make this criterion the report's primary (leading) criterion.
       def primary
         # @criterion is Symbol-wide because this receiver is also built for
         # :eval; primary_coverage validates at runtime.
         @config.primary_coverage(_ = @criterion)
       end
+
+      GroupTarget = Data.define(:name)
+
+      private
+
+      def raise_invalid_per(per)
+        raise ConfigurationError,
+          "`per:` must be :file, a String path, a Regexp, or group(\"Name\"), got #{per.inspect}"
+      end
     end
   end
 end