simplecov 1.1.0 → 1.2.0

data/lib/simplecov/configuration/filters.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Inclusion and exclusion methods: `cover` and `skip`, plus the deprecated
-  # `track_files` and `add_filter` aliases.
   module Configuration
     attr_writer :filters
 
@@ -12,59 +10,38 @@ module SimpleCov
     # when any `cover` matcher is configured the report drops every file that
     # doesn't match at least one of them.
     #
-    # Strings are interpreted as shell globs (e.g. "lib/**/*.rb"), not
-    # substring matches — this is a deliberate departure from the legacy
-    # `add_filter` semantics and matches the way `track_files` already
-    # interprets its argument.
+    # Strings are interpreted as shell globs, not substring matches, a
+    # deliberate departure from the legacy `add_filter` semantics.
     #
-    # When the matcher is a string-glob, `cover` also expands the glob on
-    # disk so files that exist but were never required during the run still
-    # appear in the report (at 0% coverage). This is the "include unloaded
-    # files" half of the legacy `track_files` behavior, rolled into the
-    # same call.
-    #
-    #     SimpleCov.start do
-    #       cover "lib/**/*.rb", "app/**/*.rb"
-    #       cover(/_helper\.rb\z/)
-    #       cover { |sf| sf.lines.count > 5 }
-    #     end
+    # A string glob is also expanded on disk, so files that exist but were
+    # never required during the run still appear in the report at 0%. This is
+    # the "include unloaded files" half of the legacy `track_files` behavior.
     #
     def cover(*args, &block)
       args.each { |arg| cover_filters << build_cover_filter(arg) }
-      cover_filters << SimpleCov::BlockFilter.new(block) if block
+      cover_filters << BlockFilter.new(block) if block
       cover_filters
     end
 
-    # Returns the list of configured inclusion filters added via `cover`.
     def cover_filters
       @cover_filters ||= []
     end
 
-    # Returns the list of string globs passed to `cover` — used by the
-    # disk-discovery pass in `SimpleCov.tracked_file_paths` so files
-    # matching a `cover` glob appear in the report even when they were
-    # never required during the suite.
-    #
-    # Walks into `ArrayFilter` entries (built when a caller passes an
-    # array to `cover`) so a glob nested inside `cover(["lib/**/*.rb",
-    # /helper\.rb\z/])` still drives unloaded-file discovery.
+    # The string globs passed to `cover`, used by the disk-discovery pass in
+    # `SimpleCov.tracked_file_paths` so files matching a `cover` glob appear in
+    # the report even when they were never required during the suite.
     def cover_globs
       collect_cover_globs(cover_filters)
     end
 
-    # DEPRECATED: prefer `cover`, which both includes unloaded files (the
-    # historical `track_files` behavior) and restricts the report to the
-    # matching set.
     def track_files(glob)
-      SimpleCov::Deprecation.warn("`SimpleCov.track_files` is deprecated. " \
-                                  "#{track_files_replacement_hint(glob)}")
+      Deprecation.warn("`SimpleCov.track_files` is deprecated. " \
+                       "#{track_files_replacement_hint(glob)}")
       @tracked_files = glob
     end
 
-    # `track_files(nil)` is the documented way to clear a previously-set
-    # glob, but `cover(nil)` raises `ConfigurationError`, so don't point
-    # users at it. The `cover` API has no direct equivalent for "reset
-    # the inclusion list" — point users at the `@cover_filters` reset.
+    # `track_files(nil)` is the documented way to clear a previously-set glob,
+    # but `cover(nil)` raises `ConfigurationError`, so don't point users at it.
     def track_files_replacement_hint(glob)
       if glob.nil?
         "Replace with `SimpleCov.cover_filters.clear` — clearing the inclusion list."
@@ -76,86 +53,76 @@ module SimpleCov
       end
     end
 
-    # Returns the glob used to include files that were not explicitly required.
+    # Nil until `cover` names a glob: an unset ivar reads as nil, so the absence
+    # needs no guard of its own.
     def tracked_files
-      @tracked_files if defined?(@tracked_files)
+      @tracked_files
     end
 
-    # Returns the list of configured exclusion filters added via `skip`
-    # (or the deprecated `add_filter`).
     def filters
       @filters ||= []
     end
 
     #
     # Drop matching files from the coverage report. The inverse of `cover`.
-    #
-    # See README for the full grammar; `skip` accepts a String (path-segment
-    # substring), Regexp, block predicate, or Array of any of those.
+    # Accepts a String (path-segment substring), Regexp, block predicate, or
+    # Array of any of those.
     #
     def skip(filter_argument = nil, &)
       filters << parse_filter(filter_argument, &)
     end
 
-    # DEPRECATED: alias for `skip`. Same matcher grammar, identical behavior.
     def add_filter(filter_argument = nil, &block)
       example = block ? "`SimpleCov.skip { ... }`" : "`SimpleCov.skip #{filter_argument.inspect}`"
-      SimpleCov::Deprecation.warn("`SimpleCov.add_filter` is deprecated. " \
-                                  "Replace with `SimpleCov.skip` (same arguments, same behavior). Example: #{example}.")
+      Deprecation.warn("`SimpleCov.add_filter` is deprecated. " \
+                       "Replace with `SimpleCov.skip` (same arguments, same behavior). Example: #{example}.")
       skip(filter_argument, &block)
     end
 
-    # Remove any filters whose `filter_argument` equals the given value.
-    # Returns true when at least one filter was removed, false otherwise.
-    def remove_filter(filter_argument) # rubocop:disable Naming/PredicateMethod
-      before = filters.size
-      filters.reject! { |filter| filter.respond_to?(:filter_argument) && filter.filter_argument == filter_argument }
-      filters.size != before
+    # `reject!` answers nil when it rejected nothing, which is the whole of
+    # "was anything removed".
+    def remove_filter(filter_argument)
+      rejected = filters.reject! do |filter|
+        filter.respond_to?(:filter_argument) && filter.filter_argument.eql?(filter_argument)
+      end
+      !rejected.nil?
     end
 
-    # Remove every filter from the chain, including the defaults installed
-    # by `SimpleCov.start`.
     def clear_filters
       @filters = []
     end
 
-    # Drop every filter previously installed (defaults plus anything
-    # earlier in this block) so subsequent `skip` calls start from a
-    # clean slate. Order matters — call this before your own `skip`
-    # invocations.
+    # Order matters: call this before your own `skip` invocations.
     def no_default_skips
       clear_filters
     end
 
-  private
+    private
 
-    # The actual filter processor. Not meant for direct use.
     def parse_filter(filter_argument = nil, &filter_proc)
       filter = filter_argument || filter_proc
 
       raise ArgumentError, "Please specify either a filter or a block to filter with" unless filter
 
-      SimpleCov::Filter.build_filter(filter)
+      Filter.build_filter(filter)
     end
 
-    # Build a filter for a `cover` argument. Strings are treated as
-    # globs (not substrings — that's `skip`/`add_filter`'s semantics);
-    # everything else dispatches exactly like `add_filter`.
+    # Strings are treated as globs, not substrings (that's `skip`'s
+    # semantics); everything else dispatches exactly like `add_filter`.
     def build_cover_filter(arg)
-      SimpleCov::Filter.build_filter(arg, string_filter: SimpleCov::GlobFilter)
-    rescue SimpleCov::ConfigurationError
-      raise SimpleCov::ConfigurationError, "Unsupported `cover` argument #{arg.inspect}; " \
-                                           "expected a String glob, Regexp, Proc, " \
-                                           "SimpleCov::Filter, or Array of those."
+      Filter.build_filter(arg, string_filter: GlobFilter)
+    rescue ConfigurationError
+      raise ConfigurationError, "Unsupported `cover` argument #{arg.inspect}; " \
+                                "expected a String glob, Regexp, Proc, " \
+                                "SimpleCov::Filter, or Array of those."
     end
 
-    # Walk a list of cover filters and return the string globs they hold,
-    # descending into `ArrayFilter` wrappers built by `cover(["a", "b"])`.
+    # Descends into `ArrayFilter` wrappers built by `cover(["a", "b"])`.
     def collect_cover_globs(filter_list)
       filter_list.flat_map do |filter|
         case filter
-        when SimpleCov::GlobFilter  then filter.filter_argument
-        when SimpleCov::ArrayFilter then collect_cover_globs(filter.filter_argument)
+        when GlobFilter then filter.filter_argument
+        when ArrayFilter then collect_cover_globs(filter.filter_argument)
         else []
         end
       end

data/lib/simplecov/configuration/formatting.rb

@@ -3,35 +3,33 @@
 require_relative "../formatter/multi_formatter"
 
 module SimpleCov
-  # Formatter selection (`formatter` / `formatters`), reporting toggles
-  # (`print_errors`), and the deprecated `# :nocov:` token hook.
   module Configuration
     attr_writer :formatter, :print_error_status
 
-    #
-    # Gets or sets the configured formatter. Accepts a formatter class
-    # (instantiated fresh for every report) or a ready-built instance,
-    # which is how constructor options are passed — e.g.
-    # `formatter SimpleCov::Formatter::HTMLFormatter.new(silent: true)`
-    # to suppress the "Coverage report generated" status line (see
-    # #1240). Pass `false` (or `nil`) to opt out of formatting
-    # entirely — worker processes in big parallel CI setups (see #964)
-    # only need their `.resultset.json` on disk so a final
-    # `SimpleCov.collate` job can produce the report; running them
-    # without a formatter saves the per-job HTML/multi-formatter
-    # overhead.
-    #
+    BUILT_IN_FORMATS = {
+      html: :HTMLFormatter, json: :JSONFormatter, simple: :SimpleFormatter, baseline: :BaselineFormatter
+    }.freeze
+    private_constant :BUILT_IN_FORMATS
+
+    LAZY_FORMAT_REQUIRES = {html: "../../simplecov-html"}.freeze
+    private_constant :LAZY_FORMAT_REQUIRES
+
+    def formats(*names)
+      return formatters if names.empty?
+
+      self.formatters = names.map { |name| resolve_format(name) }
+      formatters
+    end
+
     def formatter(formatter = :__no_arg__)
       case formatter
       when :__no_arg__
         @formatter
       else
-        @formatter = formatter || nil # normalize `false` to `nil`
+        @formatter = formatter || nil
       end
     end
 
-    # Sets the configured formatters. Pass `[]` to opt out of
-    # formatting entirely; see `formatter` for the rationale.
     def formatters(formatters = :__no_arg__)
       case formatters
       when :__no_arg__
@@ -39,100 +37,93 @@ module SimpleCov
         configured ? [configured] : []
       else
         self.formatters = formatters
-        formatters
       end
     end
 
-    # Sets the configured formatters. Equivalent to `formatters [...]`.
-    # Accepts a single formatter as well as an Array, matching the pre-1.0 behavior
-    # where `MultiFormatter.new` normalized its input. Elements may be
-    # formatter classes or ready-built instances; see `formatter`.
-    # `nil`, `false`, and `[]` all opt out of formatting entirely —
-    # `false` normalized like `formatter false` does, since `Array(false)`
-    # would otherwise smuggle it in as a "formatter" that can only fail.
+    # `nil`, `false`, and `[]` all opt out of formatting entirely. `false` is
+    # normalized first, since `Array(false)` would otherwise smuggle it in as a
+    # "formatter" that can only fail.
     def formatters=(formatters)
-      formatters = Array(formatters || nil)
-      @formatter = formatters.empty? ? nil : SimpleCov::Formatter::MultiFormatter.new(formatters)
-    end
-
-    #
-    # Get or set whether SimpleCov colorizes its stderr diagnostics. Accepts
-    # `true` (always on), `false` (always off), or `:auto` (default: defer
-    # to `SimpleCov::Color`, which checks `$stderr.tty?` with `NO_COLOR`
-    # and `FORCE_COLOR` overrides). An explicit `true`/`false` wins over
-    # both auto-detection and the env vars, which is the right escape
-    # hatch when stderr is being piped through a wrapper that still
-    # renders ANSI in its own terminal (parallel_tests with
-    # `--combine-stderr`, log multiplexers, some CI runners). See #1157.
-    #
+      @formatter = combined_formatter(Array(formatters || nil))
+    end
+
     def color(value = :__no_arg__)
-      return defined?(@color) ? @color : :auto if value == :__no_arg__
+      return instance_variable_defined?(:@color) ? @color : :auto if value.eql?(:__no_arg__)
+
+      self.color = _ = value
+    end
 
+    def color=(value)
       @color = value
     end
 
-    #
-    # Get or set whether SimpleCov prints its own diagnostic warnings to
-    # stderr. Covers per-check threshold violations, the trailing
-    # "SimpleCov failed with exit ..." summary, and the deferred-report /
-    # previous-error notices. Defaults to true. Set to false to silence
-    # SimpleCov entirely when parsing tooling output (see issue #1155).
-    #
     def print_errors(value = :__no_arg__)
-      return defined?(@print_error_status) ? @print_error_status : true if value == :__no_arg__
+      return instance_variable_defined?(:@print_error_status) ? @print_error_status : true if value.eql?(:__no_arg__)
 
+      self.print_errors = _ = value
+    end
+
+    def print_errors=(value)
       @print_error_status = value
     end
 
-    #
-    # Get or set whether `coverage.json` includes the full source-text
-    # array for every file. Defaults to true. Set to false when a
-    # downstream tool reads the project's source files directly and
-    # only needs the coverage metrics, so `coverage.json` doesn't carry
-    # a copy of the source tree (which dominates the payload on larger
-    # projects).
-    #
-    # The HTML report's embedded data always includes source — the
-    # client-side renderer needs it. Only `coverage.json` honors
-    # this setting.
-    #
-    #     SimpleCov.start do
-    #       source_in_json false
-    #     end
-    #
     def source_in_json(value = :__no_arg__)
-      return defined?(@source_in_json) ? @source_in_json : true if value == :__no_arg__
+      return instance_variable_defined?(:@source_in_json) ? @source_in_json : true if value.eql?(:__no_arg__)
+
+      self.source_in_json = _ = value
+    end
 
+    def source_in_json=(value)
       @source_in_json = value
     end
 
-    # DEPRECATED: alias for `print_errors`. Same value, same behavior.
     def print_error_status
-      SimpleCov::Deprecation.warn("`SimpleCov.print_error_status` is deprecated. " \
-                                  "Replace with `SimpleCov.print_errors` (same value).")
-      defined?(@print_error_status) ? @print_error_status : true
+      Deprecation.warn("`SimpleCov.print_error_status` is deprecated. " \
+                       "Replace with `SimpleCov.print_errors` (same value).")
+      instance_variable_defined?(:@print_error_status) ? @print_error_status : true
     end
 
-    #
-    # DEPRECATED: configure `# :nocov:` token override. Prefer
-    # `# simplecov:disable` / `# simplecov:enable` block comments (see
-    # SimpleCov::Directive). The `# :nocov:` toggle and this hook will
-    # be removed in a future release.
-    #
     def nocov_token(nocov_token = nil)
-      SimpleCov::Deprecation.warn("`SimpleCov.nocov_token` and `SimpleCov.skip_token` are deprecated. " \
-                                  "Replace with `# simplecov:disable` / `# simplecov:enable` block comments.")
+      Deprecation.warn("`SimpleCov.nocov_token` and `SimpleCov.skip_token` are deprecated. " \
+                       "Replace with `# simplecov:disable` / `# simplecov:enable` block comments.")
       current_nocov_token(nocov_token)
     end
-    alias skip_token nocov_token
+    alias_method :skip_token, :nocov_token
 
-    # Internal accessor used by SimpleCov to recognise `# :nocov:`
-    # markers without emitting the public-API deprecation warning. Will
-    # be removed alongside the deprecated `nocov_token` setter.
     def current_nocov_token(value = nil)
-      return @nocov_token if defined?(@nocov_token) && value.nil?
+      return @nocov_token if instance_variable_defined?(:@nocov_token) && value.nil?
 
       @nocov_token = value || "nocov"
     end
+
+    private
+
+    # An empty list is how a project opts out of formatting.
+    def combined_formatter(formatters)
+      return if formatters.empty?
+
+      Formatter::MultiFormatter.new(formatters)
+    end
+
+    def resolve_format(name)
+      return name unless name.instance_of?(Symbol)
+
+      constant = BUILT_IN_FORMATS[name]
+      unless constant
+        raise ConfigurationError,
+          "Unknown format #{name.inspect}. Built-in formats are :html, :json, :simple, and :baseline; " \
+          "pass a formatter class or instance for anything else."
+      end
+
+      require_html_formatter(name)
+      Formatter.const_get(constant)
+    end
+
+    # `formats :html` has to work in a process that never required the HTML
+    # formatter, which under SIMPLECOV_NO_DEFAULTS nothing else has.
+    def require_html_formatter(name)
+      path = LAZY_FORMAT_REQUIRES[name]
+      require_relative(path) if path
+    end
   end
 end

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