simplecov 1.1.1 → 1.3.0

data/lib/simplecov/configuration/groups.rb

@@ -1,38 +1,44 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Group configuration is kept separate from inclusion and exclusion filters,
-  # while sharing their matcher parser through the main Configuration module.
   module Configuration
-    # Returns the configured groups. Add groups using SimpleCov.group.
     def groups
       @groups ||= {}
     end
 
+    # The group set `SimpleCov.grouped` bins against when its caller names none.
+    # It reads through a method of its own because the keyword it defaults
+    # shadows `groups`, so the default has to name a receiver, and every
+    # spelling of that receiver is the same call.
+    #
+    # mutant:disable — for that reason: `SimpleCov.groups`, `self.groups` and
+    # `groups()` cannot be told apart.
+    def default_groups
+      groups
+    end
+
     def groups=(new_groups)
       new_groups = new_groups.to_h { |name, filter| [GroupNames.normalize(name), filter] }
       GroupNames.validate!(new_groups.keys)
       @groups = new_groups
     end
 
-    # Define a display group for files. Same matcher grammar as `skip`,
-    # but instead of dropping the matching files it bins them under
-    # `group_name` for the formatter. Files matched by no group fall
-    # into the implicit "Ungrouped" bucket.
+    # Same matcher grammar as `skip`, but instead of dropping the matching files
+    # it bins them under `group_name` for the formatter. Files matched by no
+    # group fall into the implicit "Ungrouped" bucket.
     def group(group_name, filter_argument = nil, &)
       group_name = GroupNames.normalize(group_name)
       GroupNames.validate!([group_name])
       groups[group_name] = parse_filter(filter_argument, &)
     end
 
-    # DEPRECATED: alias for `group`. Same arguments, same behavior.
     def add_group(group_name, filter_argument = nil, &block)
       example = if block
-                  "`SimpleCov.group #{group_name.inspect} { ... }`"
-                else
-                  "`SimpleCov.group #{group_name.inspect}, #{filter_argument.inspect}`"
-                end
-      SimpleCov::Deprecation.warn(
+        "`SimpleCov.group #{group_name.inspect} { ... }`"
+      else
+        "`SimpleCov.group #{group_name.inspect}, #{filter_argument.inspect}`"
+      end
+      Deprecation.warn(
         "`SimpleCov.add_group` is deprecated. " \
         "Replace with `SimpleCov.group` (same arguments, same behavior). Example: #{example}."
       )

data/lib/simplecov/configuration/history.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    DROP_BASELINES = %i[last_run median branch].freeze
+
+    # How many runs coverage/.history.json keeps, newest kept. 0 disables
+    # recording entirely, and anything but a count of runs is refused.
+    def history_limit(limit = nil)
+      return @history_limit ||= 100 if limit.nil?
+
+      self.history_limit = limit
+      _ = @history_limit
+    end
+
+    def history_limit=(limit)
+      unless limit.instance_of?(Integer) && limit >= 0
+        raise ConfigurationError, "history_limit takes a non-negative integer, got #{limit.inspect}"
+      end
+
+      @history_limit = limit
+    end
+
+    # What `maximum_coverage_drop` measures the drop against: `:last_run` (the
+    # default) the previous run whatever it was, `:median` the median of the
+    # recorded history so one run that dipped for an unrelated reason cannot
+    # quietly become the baseline, and `:branch` the newest recorded run on the
+    # current git branch so a feature branch is compared with itself.
+    #
+    # The latter two read coverage/.history.json and find nothing to compare
+    # against while it is empty, which counts as "no previous run" the way a
+    # missing .last_run.json does.
+    def drop_baseline(mode = nil)
+      return @drop_baseline ||= :last_run if mode.nil?
+
+      unless DROP_BASELINES.include?(mode)
+        raise ConfigurationError,
+          "drop_baseline takes one of #{DROP_BASELINES}, got #{mode.inspect}"
+      end
+
+      @drop_baseline = mode
+    end
+  end
+end

data/lib/simplecov/configuration/ignored_entries.rb

@@ -1,21 +1,18 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Coverage-entry filters scoped to branch / method criteria. See
-  # `ignore_branches` and `ignore_methods`, and #1033 /
-  # #1046 for the synthetic-entry detection rationale.
   module Configuration
-    # Branch types accepted by `ignore_branches`.
     IGNORABLE_BRANCH_TYPES = %i[implicit_else eval_generated].freeze
-    # Method types accepted by `ignore_methods`.
     IGNORABLE_METHOD_TYPES = %i[eval_generated].freeze
 
-    # Variadic; multiple calls union. Setting is recorded regardless
-    # of whether branch coverage is enabled at call time. See #1033, #1046.
+    # Deprecated in favour of `coverage(:branch) { ignore :implicit_else }`,
+    # which fixes the criterion by context the way the threshold verbs do. One
+    # difference rides out the deprecation period: the coverage block enables the
+    # criterion it names, while this legacy setter records without enabling.
     def ignore_branches(*types)
-      types.each { |type| raise_if_branch_type_unsupported(type) }
-      ignored_branches.concat(types).uniq!
-      ignored_branches
+      Deprecation.warn("`SimpleCov.ignore_branches` is deprecated. " \
+                       "Replace with `coverage(:branch) { ignore #{types.map(&:inspect).join(", ")} }`.")
+      store_ignored_branches(types)
     end
 
     def ignored_branches
@@ -26,12 +23,10 @@ module SimpleCov
       ignored_branches.include?(type)
     end
 
-    # See `ignore_branches`. The only supported method-type token today
-    # is `:eval_generated`; see #1046 for the rationale.
     def ignore_methods(*types)
-      types.each { |type| raise_if_method_type_unsupported(type) }
-      ignored_methods.concat(types).uniq!
-      ignored_methods
+      Deprecation.warn("`SimpleCov.ignore_methods` is deprecated. " \
+                       "Replace with `coverage(:method) { ignore #{types.map(&:inspect).join(", ")} }`.")
+      store_ignored_methods(types)
     end
 
     def ignored_methods
@@ -42,22 +37,36 @@ module SimpleCov
       ignored_methods.include?(type)
     end
 
-  private
+    private
+
+    # Variadic semantics: multiple calls union, duplicates are no-ops, unknown
+    # tokens raise.
+    def store_ignored_branches(types)
+      types.each { |type| raise_if_branch_type_unsupported(type) }
+      ignored_branches.concat(types).uniq!
+      ignored_branches
+    end
+
+    def store_ignored_methods(types)
+      types.each { |type| raise_if_method_type_unsupported(type) }
+      ignored_methods.concat(types).uniq!
+      ignored_methods
+    end
 
     def raise_if_branch_type_unsupported(type)
       return if IGNORABLE_BRANCH_TYPES.member?(type)
 
-      raise SimpleCov::ConfigurationError,
-            "Unsupported branch type #{type.inspect} for `ignore_branches`. " \
-            "Supported values are #{IGNORABLE_BRANCH_TYPES.inspect}"
+      raise ConfigurationError,
+        "Unsupported branch type #{type.inspect} for `ignore_branches`. " \
+        "Supported values are #{IGNORABLE_BRANCH_TYPES.inspect}"
     end
 
     def raise_if_method_type_unsupported(type)
       return if IGNORABLE_METHOD_TYPES.member?(type)
 
-      raise SimpleCov::ConfigurationError,
-            "Unsupported method type #{type.inspect} for `ignore_methods`. " \
-            "Supported values are #{IGNORABLE_METHOD_TYPES.inspect}"
+      raise ConfigurationError,
+        "Unsupported method type #{type.inspect} for `ignore_methods`. " \
+        "Supported values are #{IGNORABLE_METHOD_TYPES.inspect}"
     end
   end
 end

data/lib/simplecov/configuration/merging.rb

@@ -1,80 +1,93 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Result merging and subprocess / parallel-test coordination:
-  # `merging`, `merge_subprocesses`, `merge_timeout`, `parallel_tests`.
   module Configuration
     #
-    # Get or set whether SimpleCov should hook `Process._fork` to
-    # attach itself to subprocesses. Required when the suite uses
-    # parallel test workers (e.g. Rails' `parallelize(workers:)`).
-    # Defaults to false.
+    # Whether SimpleCov should hook `Process._fork` to attach itself to
+    # subprocesses. Required when the suite uses parallel test workers (Rails'
+    # `parallelize(workers:)`). Defaults to false.
     #
     def merge_subprocesses(value = nil)
-      return @enable_for_subprocesses if defined?(@enable_for_subprocesses) && value.nil?
+      return @enable_for_subprocesses if instance_variable_defined?(:@enable_for_subprocesses) && value.nil?
 
+      self.merge_subprocesses = value
+      @enable_for_subprocesses
+    end
+
+    # false stands in for nothing, so the answer is always a real opt-in or
+    # opt-out.
+    def merge_subprocesses=(value)
       @enable_for_subprocesses = value || false
     end
 
-    # @api private — predicate used by `start_tracking` to decide
-    # whether to install the fork hook.
+    # @api private
     def enabled_for_subprocesses?
-      defined?(@enable_for_subprocesses) ? @enable_for_subprocesses : false
+      !!@enable_for_subprocesses
     end
 
     #
-    # Get or set whether SimpleCov should auto-require the
-    # `parallel_tests` gem when it sees `TEST_ENV_NUMBER` /
-    # `PARALLEL_TEST_GROUPS` in the environment. Defaults to auto-detect
-    # (nil). See #1018.
+    # Whether SimpleCov should auto-require the `parallel_tests` gem when it
+    # sees `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` in the environment.
+    # Defaults to auto-detect (nil). See #1018.
     #
     def parallel_tests(value = :__no_arg__)
-      return defined?(@parallel_tests) ? @parallel_tests : nil if value == :__no_arg__
+      return @parallel_tests if value.eql?(:__no_arg__)
+
+      self.parallel_tests = _ = value
+    end
 
+    def parallel_tests=(value)
       @parallel_tests = value
     end
 
-    # DEPRECATED: alias for `merge_subprocesses`. Same value/behavior.
     def enable_for_subprocesses(value = nil)
-      SimpleCov::Deprecation.warn("`SimpleCov.enable_for_subprocesses` is deprecated. " \
-                                  "Replace with `SimpleCov.merge_subprocesses` (same value, same behavior).")
+      Deprecation.warn("`SimpleCov.enable_for_subprocesses` is deprecated. " \
+                       "Replace with `SimpleCov.merge_subprocesses` (same value, same behavior).")
       merge_subprocesses(value)
     end
 
-    #
-    # Get or set whether to merge results from multiple test suites
-    # (test:units, test:functionals, cucumber, ...) into a single
-    # coverage report. Defaults to true.
-    #
     def merging(use = nil)
-      @use_merging = use unless use.nil?
-      @use_merging = true unless defined?(@use_merging) && @use_merging == false
+      self.merging = use unless use.nil?
+      # Unset reads as nil, and only an explicit `merging false` turns it off.
+      @use_merging = true if @use_merging.nil?
       @use_merging
     end
 
+    def merging=(use)
+      @use_merging = use
+    end
+
     #
-    # Get or set whether SimpleCov's selected final process owns merge processing:
-    # waiting for sibling workers, building the merged result, formatting,
-    # enforcing thresholds, and writing `.last_run.json`.
+    # Whether SimpleCov's selected final process owns merge processing: waiting
+    # for sibling workers, building the merged result, formatting, enforcing
+    # thresholds, and writing `.last_run.json`.
     #
-    # Defaults to true, except for recognized multi-worker parallel runs
-    # that explicitly write to a custom coverage destination while merging
-    # is enabled. Those runs are likely using an external `SimpleCov.collate`
-    # step to finalize the merge.
+    # Defaults to true, except for recognized multi-worker parallel runs that
+    # explicitly write to a custom coverage destination while merging is
+    # enabled. Those runs are likely using an external `SimpleCov.collate` step
+    # to finalize the merge.
     #
-    def finalize_merge(value = :__no_arg__)
-      unless value == :__no_arg__
-        @finalize_merge = value
-        @finalize_merge_explicit = true
+    # Splatted rather than defaulted: false is a value someone sets on purpose,
+    # so "given nothing" cannot be told from it by looking at the argument.
+    def finalize_merge(*value)
+      unless value.empty?
+        explicit, = value
+        self.finalize_merge = _ = explicit
       end
 
-      return @finalize_merge if defined?(@finalize_merge_explicit) && @finalize_merge_explicit
+      return @finalize_merge if @finalize_merge_explicit
 
       inferred = inferred_finalize_merge?
       warn_about_inferred_finalize_merge unless inferred
       inferred
     end
 
+    # Writing is what makes the answer explicit rather than inferred.
+    def finalize_merge=(value)
+      @finalize_merge = value
+      @finalize_merge_explicit = true
+    end
+
     def finalize_merge?
       finalize_merge
     end
@@ -84,45 +97,65 @@ module SimpleCov
       collating_result? || (finalize_merge? && final_result_process?)
     end
 
-    # DEPRECATED: alias for `merging`. Same value, same behavior.
-    # Delegating (rather than duplicating the body) also fixes the
-    # return value: this used to return nil where `merging` returns
-    # false, because the final expression was the skipped guard
-    # assignment rather than the stored value.
     def use_merging(use = nil)
-      SimpleCov::Deprecation.warn("`SimpleCov.use_merging` is deprecated. " \
-                                  "Replace with `SimpleCov.merging` (same value, same behavior).")
+      Deprecation.warn("`SimpleCov.use_merging` is deprecated. " \
+                       "Replace with `SimpleCov.merging` (same value, same behavior).")
       merging(use)
     end
 
     #
-    # Defines the maximum age (in seconds) of a resultset to still be
-    # included in merged results. Default is 600 seconds (10 minutes).
+    # The maximum age (in seconds) of a resultset to still be included in
+    # merged results. Default is 600 seconds.
+    #
+    # A numeric SIMPLECOV_MERGE_TIMEOUT in the environment takes precedence
+    # over the configured value: `simplecov watch` re-runs test subsets across
+    # a long session and extends its child runs' merge window this way, where
+    # editing every watched project's configuration is not an option.
     #
     def merge_timeout(seconds = nil)
-      @merge_timeout = seconds if seconds.is_a?(Integer)
-      @merge_timeout ||= 600
+      self.merge_timeout = seconds
+      # Memoized through a local rather than `|| (@merge_timeout ||= 600)`:
+      # steep 2.0's logic-type interpreter crashes on an or-assignment nested in
+      # a logical operand, and ivar narrowing doesn't carry across statements
+      # the way a local's does.
+      configured = @merge_timeout || 600
+      @merge_timeout = configured
+      env_merge_timeout || configured
+    end
+
+    # Anything but an Integer is ignored, the way the dual method always did.
+    def merge_timeout=(seconds)
+      @merge_timeout = seconds if seconds.instance_of?(Integer)
+    end
+
+    def env_merge_timeout
+      value = ENV.fetch("SIMPLECOV_MERGE_TIMEOUT", nil)
+      Integer(value, 10) if value&.match?(/\A\d+\z/)
     end
 
     #
-    # Defines how long (in seconds) the reporting process waits for the
-    # remaining parallel-test workers to write their resultsets before it
-    # proceeds with a partial merge. Default is 60 seconds. Raise it when a
-    # slow worker routinely finishes well after the others, so its coverage
-    # is still included and the minimum / maximum coverage checks aren't
-    # skipped against a partial total.
+    # How long (in seconds) the reporting process waits for the remaining
+    # parallel-test workers to write their resultsets before it proceeds with a
+    # partial merge. Default is 60 seconds. Raise it when a slow worker
+    # routinely finishes well after the others, so its coverage is still
+    # included and the threshold checks aren't skipped against a partial total.
     #
     def parallel_wait_timeout(seconds = nil)
-      @parallel_wait_timeout = seconds if seconds.is_a?(Integer)
+      self.parallel_wait_timeout = seconds
       @parallel_wait_timeout ||= 60
     end
 
-  private
+    # Anything but an Integer is ignored, the way the dual method always did.
+    def parallel_wait_timeout=(seconds)
+      @parallel_wait_timeout = seconds if seconds.instance_of?(Integer)
+    end
+
+    private
 
     def inferred_finalize_merge?
       return true unless merging
 
-      adapter = SimpleCov::ParallelAdapters.current
+      adapter = ParallelAdapters.current
       return true unless adapter
       return true unless adapter.expected_worker_count > 1
       return true unless parallel_worker_environment?
@@ -138,20 +171,19 @@ module SimpleCov
     def explicit_custom_coverage_destination?
       return false unless explicit_coverage_destination?
 
-      coverage_path != File.expand_path("coverage", root)
+      !coverage_path.eql?(File.expand_path("coverage", root))
     end
 
     def explicit_coverage_destination?
-      (defined?(@coverage_path_explicit) && @coverage_path_explicit) ||
-        (defined?(@coverage_dir_explicit) && @coverage_dir_explicit)
+      @coverage_path_explicit || @coverage_dir_explicit
     end
 
     def warn_about_inferred_finalize_merge
-      return if defined?(@finalize_merge_inference_warned) && @finalize_merge_inference_warned
+      return if @finalize_merge_inference_warned
       return unless print_errors
 
       @finalize_merge_inference_warned = true
-      warn SimpleCov::Color.colorize(inferred_finalize_merge_warning, :yellow)
+      warn Color.colorize(inferred_finalize_merge_warning, :yellow)
     end
 
     def inferred_finalize_merge_warning

data/lib/simplecov/configuration/missed_caps.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    # Caps the total number of misses per criterion. Where a percent minimum
+    # asks for a ratio, this asks for an absolute burn-down number, which stays
+    # meaningful as the codebase grows and shrinks.
+    def maximum_missed(counts = nil)
+      return @maximum_missed ||= {} unless counts
+
+      @maximum_missed = normalized_missed_caps(counts, "maximum_missed")
+    end
+
+    # Unlike a percent minimum, which systematically flatters big files, this
+    # holds every file to the same absolute budget. Files with a baseline entry
+    # are exempt per covered criterion, as they are from the per-file minimum.
+    def maximum_missed_per_file(counts = nil)
+      return @maximum_missed_per_file ||= {} unless counts
+
+      Deprecation.warn("`SimpleCov.maximum_missed_per_file` is deprecated. " \
+                       "Replace it with:\n#{missed_per_file_replacement(counts)}")
+      @maximum_missed_per_file = normalized_missed_caps(counts, "maximum_missed_per_file")
+    end
+
+    def maximum_missed_per_file_overrides
+      @maximum_missed_per_file_overrides ||= {}
+    end
+
+    private
+
+    def normalized_missed_caps(counts, setting)
+      counts = {primary_coverage => counts} if counts.is_a?(Numeric)
+      counts.each_key { |criterion| raise_if_criterion_disabled(criterion) }
+      counts.each_value { |cap| raise_on_invalid_missed_cap(cap, setting) }
+      _ = counts
+    end
+
+    def raise_on_invalid_missed_cap(cap, setting)
+      return if cap.instance_of?(Integer) && cap >= 0
+
+      raise ConfigurationError,
+        "#{setting} takes a non-negative integer count of misses, got #{cap.inspect}"
+    end
+
+    def missed_per_file_replacement(counts)
+      counts = {primary_coverage => counts} if counts.is_a?(Numeric)
+      counts.map { |criterion, cap| "  coverage(#{criterion.inspect}) { maximum_missed #{cap}, per: :file }" }
+        .join("\n")
+    end
+  end
+end

data/lib/simplecov/configuration/production.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    # The path to a production coverage store, the file a `SimpleCov::Production`
+    # sink wrote. Relative paths resolve against `SimpleCov.root`. The store is
+    # read at report time, and an unreadable or invalid file warns and leaves the
+    # section out, because a missing night's data should not fail the suite that
+    # measured the tests.
+    def production_coverage(path = nil)
+      return @production_coverage if path.nil?
+
+      self.production_coverage = path
+      @production_coverage
+    end
+
+    def production_coverage=(path)
+      raise ConfigurationError, "production_coverage takes a path, got #{path.inspect}" unless path.is_a?(String)
+
+      @production_coverage = File.expand_path(path, root)
+    end
+  end
+end

data/lib/simplecov/configuration/test_tracking.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    TRACK_TESTS_GRANULARITIES = %i[test file].freeze
+
+    # Enables recording of which test covered which line. Off by default:
+    # sampling coverage around every test costs run time, and the recorded map
+    # costs space in `.resultset.json`. RSpec examples and Minitest tests are
+    # wrapped automatically; other runners wrap their own units of work with
+    # `SimpleCov.track_test`. A bare `track_tests` enables, and only an explicit
+    # `track_tests false` turns it back off.
+    #
+    # `granularity` decides what one recorded context stands for: a test
+    # (`:test`, the default) or a whole test file (`:file`). File granularity is
+    # the batching lever for suites where per-test sampling costs too much.
+    def track_tests(enabled = nil, granularity: nil)
+      if granularity && !TRACK_TESTS_GRANULARITIES.include?(granularity)
+        raise ConfigurationError,
+          "Unsupported track_tests granularity #{granularity.inspect}, " \
+          "supported values are #{TRACK_TESTS_GRANULARITIES.inspect}"
+      end
+
+      @track_tests_granularity = granularity if granularity
+      @track_tests = enabled.nil? || enabled
+    end
+
+    def track_tests?
+      !!@track_tests
+    end
+
+    def track_tests_granularity
+      @track_tests_granularity || :test
+    end
+
+    # @api private. The map is built from per-line execution count deltas, which
+    # `:oneshot_line` does not produce: a line reports only its first hit ever,
+    # so every test after the first would show no delta.
+    def validate_test_tracking!
+      return unless track_tests?
+      return if coverage_criterion_enabled?(DEFAULT_COVERAGE_CRITERION)
+
+      raise ConfigurationError,
+        "`track_tests` needs line coverage with execution counts. " \
+        "Enable it with `enable_coverage :line` (`:oneshot_line` cannot record per-test data)."
+    end
+  end
+end