simplecov 0.22.0 → 1.0.0

data/lib/simplecov/combine/lines_combiner.rb

@@ -9,34 +9,36 @@ module SimpleCov
     module LinesCombiner
     module_function
 
+      # Build a fresh array sized to the longer input. The previous
+      # implementation mutated whichever input was longer in place,
+      # which could surprise callers holding a reference to that array
+      # (e.g. the parsed `coverage` key of a resultset hash being
+      # passed into a second merge).
       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
+        size = [coverage_a.size, coverage_b.size].max
+        Array.new(size) { |i| merge_line_coverage(coverage_a[i], coverage_b[i]) }
       end
 
-      # Return depends on coverage in a specific line
-      #
-      # @param [Integer || nil] first_val
-      # @param [Integer || nil] second_val
+      # Two runs of the same source file should agree on which lines
+      # are coverage-relevant (`nil` for comments / whitespace, `0`+
+      # for executable). When they don't, treat "relevant on either
+      # side" as relevant rather than masking a real `0` as `nil`,
+      # which would silently drop an uncovered line from the
+      # denominator and inflate the percentage.
       #
       # Logic:
       #
-      # => nil + 0 = nil
       # => nil + nil = nil
-      # => int + int = int
+      # => nil + int = int (preserves a relevant-but-uncovered 0)
+      # => int + int = int (sum)
       #
+      # @param [Integer || nil] first_val
+      # @param [Integer || nil] second_val
       # @return [Integer || nil]
       def merge_line_coverage(first_val, second_val)
-        sum = first_val.to_i + second_val.to_i
+        return nil if first_val.nil? && second_val.nil?
 
-        if sum.zero? && (first_val.nil? || second_val.nil?)
-          nil
-        else
-          sum
-        end
+        first_val.to_i + second_val.to_i
       end
     end
   end

data/lib/simplecov/combine/methods_combiner.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Combine
+    #
+    # Combine different method coverage results on a single file.
+    #
+    # Should be called through `SimpleCov.combine`.
+    module MethodsCombiner
+    module_function
+
+      #
+      # Return merged methods or the existing methods if other is missing.
+      #
+      # Method coverage is a flat hash mapping method identifiers to hit counts.
+      # Combining sums the hit counts for matching methods and preserves methods
+      # that only appear in one result.
+      #
+      # @return [Hash]
+      #
+      def combine(coverage_a, coverage_b)
+        coverage_a.merge(coverage_b) { |_key, a_count, b_count| a_count + b_count }
+      end
+    end
+  end
+end

data/lib/simplecov/combine/results_combiner.rb

@@ -13,9 +13,10 @@ module SimpleCov
       #
       # 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.
+      # ==> FileCombiner: collect result of next combine levels lines, branches, and methods.
       # ===> LinesCombiner: combine lines results.
       # ===> BranchesCombiner: combine branches results.
+      # ===> MethodsCombiner: combine methods results.
       #
       # @return [Hash]
       #
@@ -36,11 +37,11 @@ module SimpleCov
       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(
+        results_files.to_h do |file_name|
+          [file_name, combine_file_coverage(
             combined_results[file_name],
             result[file_name]
-          )
+          )]
         end
       end
 

data/lib/simplecov/command_guesser.rb

@@ -14,50 +14,64 @@ module SimpleCov
       attr_accessor :original_run_command
 
       def guess
-        from_env || from_command_line_options || from_defined_constants
+        [from_command_line_options || from_defined_constants, parallel_data].compact.join(" ")
       end
 
     private
 
-      def from_env
-        # If being run from inside parallel_tests set the command name according to the process number
-        return unless ENV["PARALLEL_TEST_GROUPS"] && ENV["TEST_ENV_NUMBER"]
+      # 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
 
-        number = ENV["TEST_ENV_NUMBER"]
+        # parallel_tests sets the first worker's TEST_ENV_NUMBER to "" rather
+        # than "1"; restore the position so the rendered label reads cleanly.
         number = "1" if number.empty?
-        "(#{number}/#{ENV['PARALLEL_TEST_GROUPS']})"
+        "(#{number}/#{groups})"
       end
 
+      COMMAND_LINE_FRAMEWORKS = {
+        %r{test/functional/} => "Functional Tests",
+        %r{test/\{.*functional.*\}/} => "Functional Tests",
+        %r{test/integration/} => "Integration Tests",
+        %r{test/} => "Unit Tests",
+        /spec/ => "RSpec",
+        /cucumber/ => "Cucumber Features",
+        /features/ => "Cucumber Features"
+      }.freeze
+      private_constant :COMMAND_LINE_FRAMEWORKS
+
       def from_command_line_options
-        case original_run_command
-        when /test\/functional\//, /test\/\{.*functional.*\}\//
-          "Functional Tests"
-        when /test\/integration\//
-          "Integration Tests"
-        when /test\//
-          "Unit Tests"
-        when /spec/
-          "RSpec"
-        when /cucumber/, /features/
-          "Cucumber Features"
-        end
+        COMMAND_LINE_FRAMEWORKS.find { |pattern, _| pattern.match?(original_run_command.to_s) }&.last
       end
 
+      # Inner array literals after the first are flagged uncovered by Ruby's
+      # Coverage module even though the constant evaluates as a whole — known
+      # quirk with multi-line array literals.
+      DEFINED_CONSTANT_FRAMEWORKS = [
+        ["RSpec",      -> { defined?(::RSpec) }],
+        ["Unit Tests", -> { defined?(Test::Unit) }],   # 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
-        # If the command regexps fail, let's try checking defined constants.
-        if defined?(RSpec)
-          "RSpec"
-        elsif defined?(Test::Unit)
-          "Unit Tests"
-        elsif defined?(Minitest)
-          "Minitest"
-        elsif defined?(MiniTest)
-          "MiniTest"
-        else
-          # TODO: Provide link to docs/wiki article
-          warn "SimpleCov failed to recognize the test framework and/or suite used. Please specify manually using SimpleCov.command_name 'Unit Tests'."
-          "Unknown Test Framework"
-        end
+        # 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/coverage.rb

@@ -0,0 +1,171 @@
+# 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
+
+    #
+    # 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. `:eval` is enable-only.
+    #
+    def coverage(criterion, primary: false, enabled: true, oneshot: false, **thresholds, &block)
+      criterion = enable_coverage_criterion(criterion, enabled: enabled, oneshot: oneshot)
+      primary_coverage(criterion) if primary
+
+      configurator = CoverageCriterion.new(self, criterion)
+      apply_threshold_options(configurator, thresholds)
+      configurator.instance_eval(&block) if block
+
+      criterion
+    end
+
+  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}."
+        end
+
+        configurator.public_send(verb, value)
+      end
+    end
+
+    # Enable 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:)
+      return enable_oneshot_line(criterion) if oneshot
+      return enable_eval_coverage_criterion if criterion == :eval
+
+      enabled ? enable_coverage(criterion) : disable_coverage(criterion)
+      criterion
+    end
+
+    def enable_oneshot_line(criterion)
+      unless criterion == :line
+        raise SimpleCov::ConfigurationError, "`oneshot: true` is only valid for `coverage :line`"
+      end
+
+      enable_coverage(ONESHOT_LINE_COVERAGE_CRITERION)
+      ONESHOT_LINE_COVERAGE_CRITERION
+    end
+
+    def enable_eval_coverage_criterion
+      enable_coverage(:eval)
+      :eval
+    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.
+    def store_overall_threshold(setting, criterion, percent)
+      raise_on_invalid_coverage({criterion => percent}, setting.to_s)
+      public_send(setting)[criterion] = percent
+    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}"
+      end
+
+      (minimum_coverage_by_file_overrides[target] ||= {})[criterion] = percent
+    end
+
+    def store_minimum_per_group(criterion, percent, group_name)
+      raise_on_invalid_coverage({criterion => percent}, "minimum_coverage_by_group")
+      (minimum_coverage_by_group[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.
+    #
+    class CoverageCriterion
+      def initialize(config, criterion)
+        @config = config
+        @criterion = criterion
+      end
+
+      # Overall (suite-wide) minimum for this criterion.
+      def minimum(percent)
+        @config.send(:store_overall_threshold, :minimum_coverage, @criterion, percent)
+      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)
+      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)
+      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)
+      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)
+      end
+
+      # Make this criterion the report's primary (leading) criterion.
+      def primary
+        @config.primary_coverage(@criterion)
+      end
+    end
+  end
+end

data/lib/simplecov/configuration/coverage_criteria.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  # Selection and validation of the coverage criteria Ruby's `Coverage`
+  # library should track. Supports `:line` (the historical default),
+  # `:branch`, `:method`, and `:oneshot_line`, plus the standalone
+  # `:eval` toggle for instrumenting `eval`'d code.
+  module Configuration
+    SUPPORTED_COVERAGE_CRITERIA = %i[line branch method oneshot_line].freeze
+    DEFAULT_COVERAGE_CRITERION = :line
+    ONESHOT_LINE_COVERAGE_CRITERION = :oneshot_line
+
+    # Enable one or more coverage criteria. `:eval` is accepted as a
+    # shorthand for the standalone eval-coverage toggle.
+    def enable_coverage(*criteria)
+      criteria.each do |criterion|
+        if criterion == :eval
+          enable_eval_coverage
+        else
+          raise_if_criterion_unsupported(criterion)
+          # :oneshot_lines can not be combined with :lines
+          coverage_criteria.delete(DEFAULT_COVERAGE_CRITERION) if criterion == ONESHOT_LINE_COVERAGE_CRITERION
+          coverage_criteria << criterion
+        end
+      end
+    end
+
+    # Remove `criterion` from the set of enabled coverage criteria.
+    # Disabling every criterion raises at `start_tracking` (not here),
+    # so config files that toggle criteria in arbitrary order don't
+    # have to worry about transient empty states.
+    def disable_coverage(criterion)
+      raise_if_criterion_unsupported(criterion)
+      coverage_criteria.delete(criterion)
+      @primary_coverage = nil if @primary_coverage == criterion
+    end
+
+    def primary_coverage(criterion = nil)
+      if criterion.nil?
+        @primary_coverage ||= default_primary_coverage
+      else
+        raise_if_criterion_disabled(criterion)
+        @primary_coverage = criterion
+      end
+    end
+
+    def coverage_criteria
+      @coverage_criteria ||= Set[DEFAULT_COVERAGE_CRITERION]
+    end
+
+    def coverage_criterion_enabled?(criterion)
+      coverage_criteria.member?(criterion)
+    end
+
+    # Reset the criteria back to the lazy default (`Set[:line]`).
+    def clear_coverage_criteria
+      @coverage_criteria = nil
+      @primary_coverage = nil
+    end
+
+    # @api private — called from `SimpleCov.start_tracking` to fail
+    # fast when the user has disabled every coverage criterion.
+    def validate_coverage_criteria!
+      return unless coverage_criteria.empty?
+
+      raise SimpleCov::ConfigurationError,
+            "At least one coverage criterion must be enabled. " \
+            "Re-enable one with `enable_coverage :line`, `:branch`, or `:method`."
+    end
+
+    def branch_coverage?
+      branch_coverage_supported? && coverage_criterion_enabled?(:branch)
+    end
+
+    def branch_coverage_supported?
+      coverage_criterion_supported?(:branches)
+    end
+
+    def method_coverage?
+      method_coverage_supported? && coverage_criterion_enabled?(:method)
+    end
+
+    def method_coverage_supported?
+      coverage_criterion_supported?(:methods)
+    end
+
+    def coverage_for_eval_supported?
+      coverage_criterion_supported?(:eval)
+    end
+
+    # Ask the Coverage runtime itself whether a criterion is supported
+    # (Ruby >= 3.2). Older Rubies don't expose `Coverage.supported?`, so
+    # fall back to the historical engine check that line/branch/method
+    # were unavailable on JRuby. `:eval` was added later, so on older
+    # Rubies its fallback is "always unsupported" rather than the
+    # JRuby-only one above. The fallback arm is unreachable from the
+    # dogfood report, which runs on a newer Ruby.
+    # simplecov:disable
+    def coverage_criterion_supported?(criterion)
+      require "coverage"
+      return Coverage.supported?(criterion) if Coverage.respond_to?(:supported?)
+
+      criterion != :eval && RUBY_ENGINE != "jruby"
+    end
+    # simplecov:enable
+
+    def coverage_for_eval_enabled?
+      @coverage_for_eval_enabled ||= false
+    end
+
+    # DEPRECATED: prefer `enable_coverage :eval`.
+    def enable_coverage_for_eval
+      SimpleCov::Deprecation.warn("`SimpleCov.enable_coverage_for_eval` is deprecated. " \
+                                  "Replace with `SimpleCov.enable_coverage :eval`.")
+      enable_eval_coverage
+    end
+
+  private
+
+    # Shared implementation backing both `enable_coverage :eval` and
+    # the deprecated `enable_coverage_for_eval`.
+    def enable_eval_coverage
+      if coverage_for_eval_supported?
+        @coverage_for_eval_enabled = true
+      else
+        warn "Coverage for eval is not available; Use Ruby 3.2.0 or later"
+      end
+    end
+
+    # If `:line` is enabled, it's the default primary; otherwise fall
+    # back to whichever criterion the user actually enabled (in
+    # insertion order). Returning `:line` even when disabled would
+    # propagate broken state into `minimum_coverage 90`.
+    def default_primary_coverage
+      return DEFAULT_COVERAGE_CRITERION if coverage_criterion_enabled?(DEFAULT_COVERAGE_CRITERION)
+
+      coverage_criteria.first
+    end
+
+    def raise_if_criterion_disabled(criterion)
+      raise_if_criterion_unsupported(criterion)
+      return if coverage_criterion_enabled?(criterion)
+
+      raise SimpleCov::ConfigurationError,
+            "Coverage criterion #{criterion}, is disabled! " \
+            "Please enable it first through enable_coverage #{criterion} (if supported)"
+    end
+
+    def raise_if_criterion_unsupported(criterion)
+      return if SUPPORTED_COVERAGE_CRITERIA.member?(criterion)
+
+      raise SimpleCov::ConfigurationError,
+            "Unsupported coverage criterion #{criterion}, supported values are #{SUPPORTED_COVERAGE_CRITERIA}"
+    end
+  end
+end