simplecov 1.1.0 → 1.2.0

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

data/lib/simplecov/configuration/coverage_criteria.rb

@@ -1,10 +1,6 @@
 # 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`. The standalone `:eval`
-  # toggle lives in `eval_coverage.rb`.
   module Configuration
     SUPPORTED_COVERAGE_CRITERIA = %i[line branch method oneshot_line].freeze
     DEFAULT_COVERAGE_CRITERION = :line
@@ -12,34 +8,36 @@ module SimpleCov
     LINE_COVERAGE_ALTERNATIVES = {line: :oneshot_line, oneshot_line: :line}.freeze #: line_coverage_alternatives
     private_constant :LINE_COVERAGE_ALTERNATIVES
 
-    # Enable one or more coverage criteria. `:eval` is accepted as a
-    # shorthand for the standalone eval-coverage toggle.
     def enable_coverage(*criteria)
-      criteria.each { |criterion| criterion == :eval ? enable_eval_coverage : add_coverage_criterion(criterion) }
+      criteria.each do |criterion|
+        criterion.equal?(:eval) ? enable_eval_coverage : add_coverage_criterion(_ = criterion)
+      end
     end
 
-    # Remove `criterion` from the set of enabled coverage criteria.
-    # `:eval` turns the standalone eval-coverage toggle back off,
-    # mirroring `enable_coverage`. 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.
+    # 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)
-      return disable_eval_coverage if criterion == :eval
+      return disable_eval_coverage if criterion.equal?(:eval)
 
-      raise_if_criterion_unsupported(criterion)
-      coverage_criteria.delete(criterion)
-      @primary_coverage = nil if @primary_coverage == criterion
+      raise_if_criterion_unsupported(_ = criterion)
+      coverage_criteria.delete(_ = criterion)
+      @primary_coverage = nil if @primary_coverage.equal?(criterion)
     end
 
     def primary_coverage(criterion = nil)
       if criterion.nil?
         @primary_coverage ||= default_primary_coverage
       else
-        raise_if_criterion_disabled(criterion)
-        @primary_coverage = criterion
+        self.primary_coverage = criterion
       end
     end
 
+    def primary_coverage=(criterion)
+      raise_if_criterion_disabled(criterion)
+      @primary_coverage = criterion
+    end
+
     def coverage_criteria
       @coverage_criteria ||= Set[DEFAULT_COVERAGE_CRITERION]
     end
@@ -48,20 +46,17 @@ module SimpleCov
       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`."
+      raise ConfigurationError,
+        "At least one coverage criterion must be enabled. " \
+        "Re-enable one with `enable_coverage :line`, `:branch`, or `:method`."
     end
 
     # Whether this run produces line data at all. The oneshot variant counts:
@@ -89,23 +84,23 @@ module SimpleCov
       coverage_criterion_supported?(:methods)
     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
+    # 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 its fallback is "always unsupported".
     def coverage_criterion_supported?(criterion)
-      require "coverage"
+      load_coverage
       return Coverage.supported?(criterion) if Coverage.respond_to?(:supported?)
 
-      criterion != :eval && RUBY_ENGINE != "jruby"
+      !criterion.eql?(:eval) && !RUBY_ENGINE.eql?("jruby")
+    end
+
+    # Loading `simplecov/configuration` on its own leaves Coverage undefined, and
+    # this question is asked at configuration time.
+    def load_coverage
+      require "coverage"
     end
-    # simplecov:enable
 
-  private
+    private
 
     def add_coverage_criterion(criterion)
       raise_if_criterion_unsupported(criterion)
@@ -114,41 +109,35 @@ module SimpleCov
       coverage_criteria << criterion
     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`.
+    # Answering `:line` even when it is disabled would propagate broken state
+    # into `minimum_coverage 90`, so fall back to whichever criterion the user
+    # actually enabled, in insertion order.
     def default_primary_coverage
       return DEFAULT_COVERAGE_CRITERION if coverage_criterion_enabled?(DEFAULT_COVERAGE_CRITERION)
 
-      # Set#first types as nilable, but an empty criteria set is rejected at
-      # start_tracking before any caller can observe a nil here.
       _ = coverage_criteria.first
     end
 
     def raise_if_criterion_disabled(criterion)
-      # `coverage :eval` by itself IS supported — it's a standalone
-      # toggle, never in the enabled-criteria set — so the generic
-      # "unsupported criterion" message below would mislead here.
-      if criterion == :eval
-        raise SimpleCov::ConfigurationError,
-              "Coverage criterion :eval only toggles measuring eval'd code; " \
-              "it cannot carry thresholds or serve as the primary criterion"
+      if criterion.equal?(:eval)
+        raise ConfigurationError,
+          "Coverage criterion :eval only toggles measuring eval'd code; " \
+          "it cannot carry thresholds or serve as the primary criterion"
       end
 
       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)"
+      raise 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}"
+      raise ConfigurationError,
+        "Unsupported coverage criterion #{criterion}, supported values are #{SUPPORTED_COVERAGE_CRITERIA}"
     end
   end
 end

data/lib/simplecov/configuration/deprecations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../deprecation"
+
+module SimpleCov
+  module Configuration
+    DEPRECATION_MODES = Deprecation::MODES
+
+    # The configuration DSL migrates by warn-and-delegate, which means a project
+    # can run on deprecated spellings indefinitely without noticing.
+    # `deprecations :raise` turns every deprecated API into a ConfigurationError,
+    # so a project that has migrated can guard in CI against old spellings
+    # creeping back. There is deliberately no silencing mode: a deprecation you
+    # cannot see is a migration you never make.
+    def deprecations(mode = nil)
+      return Deprecation.mode unless mode
+
+      Deprecation.mode = mode
+    end
+  end
+end

data/lib/simplecov/configuration/eval_coverage.rb

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # The standalone eval-coverage toggle (`enable_coverage :eval`),
-  # instrumenting `eval`'d code on Rubies that support it. Kept separate
-  # from the criteria-set logic in `coverage_criteria.rb` because `:eval`
-  # is a boolean toggle, never a member of the enabled-criteria set.
   module Configuration
+    # The standalone eval-coverage toggle, kept apart from the criteria-set logic
+    # in `coverage_criteria.rb` because `:eval` is a boolean toggle, never a
+    # member of the enabled-criteria set.
     def coverage_for_eval_supported?
       coverage_criterion_supported?(:eval)
     end
@@ -14,17 +13,14 @@ module SimpleCov
       @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`.")
+      Deprecation.warn("`SimpleCov.enable_coverage_for_eval` is deprecated. " \
+                       "Replace with `SimpleCov.enable_coverage :eval`.")
       enable_eval_coverage
     end
 
-  private
+    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