simplecov 0.22.0 → 1.1.1

data/lib/simplecov/configuration/coverage_criteria.rb

@@ -0,0 +1,154 @@
+# 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
+    ONESHOT_LINE_COVERAGE_CRITERION = :oneshot_line
+    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) }
+    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.
+    def disable_coverage(criterion)
+      return disable_eval_coverage if criterion == :eval
+
+      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
+
+    # Whether this run produces line data at all. The oneshot variant counts:
+    # `ResultAdapter` turns its executed-line list back into a line array. A
+    # branch-only or method-only run produces none, and `Coverage.result`
+    # entries for the files it loaded carry no `"lines"` key.
+    def line_coverage?
+      coverage_criterion_enabled?(DEFAULT_COVERAGE_CRITERION) ||
+        coverage_criterion_enabled?(ONESHOT_LINE_COVERAGE_CRITERION)
+    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
+
+    # 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
+
+  private
+
+    def add_coverage_criterion(criterion)
+      raise_if_criterion_unsupported(criterion)
+      incompatible = LINE_COVERAGE_ALTERNATIVES[criterion]
+      disable_coverage(incompatible) if incompatible
+      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`.
+    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"
+      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)"
+    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

data/lib/simplecov/configuration/eval_coverage.rb

@@ -0,0 +1,41 @@
+# 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
+    def coverage_for_eval_supported?
+      coverage_criterion_supported?(:eval)
+    end
+
+    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
+
+    # No support check needed: off is a safe state on every Ruby.
+    def disable_eval_coverage
+      @coverage_for_eval_enabled = false
+    end
+  end
+end

data/lib/simplecov/configuration/filters.rb

@@ -0,0 +1,164 @@
+# 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
+
+    #
+    # Restrict the universe of files in the coverage report to those matching
+    # one or more globs, regexps, or block predicates. Multiple calls union;
+    # 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.
+    #
+    # 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
+    #
+    def cover(*args, &block)
+      args.each { |arg| cover_filters << build_cover_filter(arg) }
+      cover_filters << SimpleCov::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.
+    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)}")
+      @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.
+    def track_files_replacement_hint(glob)
+      if glob.nil?
+        "Replace with `SimpleCov.cover_filters.clear` — clearing the inclusion list."
+      else
+        "Replace with `SimpleCov.cover #{glob.inspect}` — `cover` includes unloaded files on disk " \
+          "(the historical `track_files` behavior) and also restricts the report to the matching set. " \
+          "If you want to keep additional files outside #{glob.inspect} in the report, pass every " \
+          "directory you care about, e.g. `cover #{glob.inspect}, \"app/**/*.rb\"`."
+      end
+    end
+
+    # Returns the glob used to include files that were not explicitly required.
+    def tracked_files
+      @tracked_files if defined?(@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.
+    #
+    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}.")
+      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
+    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.
+    def no_default_skips
+      clear_filters
+    end
+
+  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)
+    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`.
+    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."
+    end
+
+    # Walk a list of cover filters and return the string globs they hold,
+    # descending 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)
+        else []
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/configuration/formatting.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+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.
+    #
+    def formatter(formatter = :__no_arg__)
+      case formatter
+      when :__no_arg__
+        @formatter
+      else
+        @formatter = formatter || nil # normalize `false` to `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__
+        configured = formatter
+        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.
+    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.
+    #
+    def color(value = :__no_arg__)
+      return defined?(@color) ? @color : :auto if value == :__no_arg__
+
+      @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__
+
+      @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__
+
+      @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
+    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.")
+      current_nocov_token(nocov_token)
+    end
+    alias 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?
+
+      @nocov_token = value || "nocov"
+    end
+  end
+end

data/lib/simplecov/configuration/groups.rb

@@ -0,0 +1,42 @@
+# 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
+
+    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.
+    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.add_group` is deprecated. " \
+        "Replace with `SimpleCov.group` (same arguments, same behavior). Example: #{example}."
+      )
+      group(group_name, filter_argument, &block)
+    end
+  end
+end

data/lib/simplecov/configuration/ignored_entries.rb

@@ -0,0 +1,63 @@
+# 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.
+    def ignore_branches(*types)
+      types.each { |type| raise_if_branch_type_unsupported(type) }
+      ignored_branches.concat(types).uniq!
+      ignored_branches
+    end
+
+    def ignored_branches
+      @ignored_branches ||= []
+    end
+
+    def ignored_branch?(type)
+      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
+    end
+
+    def ignored_methods
+      @ignored_methods ||= []
+    end
+
+    def ignored_method?(type)
+      ignored_methods.include?(type)
+    end
+
+  private
+
+    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}"
+    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}"
+    end
+  end
+end