simplecov 0.22.0 → 1.0.0

data/lib/simplecov/configuration/filters.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  # Inclusion / exclusion / grouping methods: `cover`, `skip`, `group`,
+  # plus the deprecated `track_files` / `add_filter` / `add_group`
+  # aliases. Mutates the same `filters`, `groups`, and `cover_filters`
+  # collections the main Configuration module exposes.
+  module Configuration
+    attr_writer :filters, :groups
+
+    #
+    # 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.add_not_loaded_files` 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
+
+    # Returns the configured groups. Add groups using SimpleCov.group.
+    def groups
+      @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, &)
+      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
+
+    # 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).
+    def build_cover_filter(arg)
+      case arg
+      when String            then SimpleCov::GlobFilter.new(arg)
+      when Regexp            then SimpleCov::RegexFilter.new(arg)
+      when Proc              then SimpleCov::BlockFilter.new(arg)
+      when SimpleCov::Filter then arg
+      when Array             then SimpleCov::ArrayFilter.new(arg.map { |a| build_cover_filter(a) })
+      else raise SimpleCov::ConfigurationError, "Unsupported `cover` argument #{arg.inspect}; " \
+                                                "expected a String glob, Regexp, Proc, " \
+                                                "SimpleCov::Filter, or Array of those."
+      end
+    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,119 @@
+# 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. 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__)
+      return @formatter if formatter == :__no_arg__
+
+      @formatter = formatter || nil # normalize `false` to `nil`
+    end
+
+    # Sets the configured formatters. Pass `[]` to opt out of
+    # formatting entirely; see `formatter` for the rationale.
+    def formatters(formatters = :__no_arg__)
+      return Array(formatter) if formatters == :__no_arg__
+
+      self.formatters = formatters
+      formatters
+    end
+
+    # Sets the configured formatters. Equivalent to `formatters [...]`.
+    def formatters=(formatters)
+      @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 viewer's `coverage_data.js` 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/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

data/lib/simplecov/configuration/merging.rb

@@ -0,0 +1,164 @@
+# 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.
+    #
+    def merge_subprocesses(value = nil)
+      return @enable_for_subprocesses if defined?(@enable_for_subprocesses) && value.nil?
+
+      @enable_for_subprocesses = value || false
+    end
+
+    # @api private — predicate used by `start_tracking` to decide
+    # whether to install the fork hook.
+    def enabled_for_subprocesses?
+      defined?(@enable_for_subprocesses) ? @enable_for_subprocesses : false
+    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.
+    #
+    def parallel_tests(value = :__no_arg__)
+      return defined?(@parallel_tests) ? @parallel_tests : nil if value == :__no_arg__
+
+      @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).")
+      return @enable_for_subprocesses if defined?(@enable_for_subprocesses) && value.nil?
+
+      @enable_for_subprocesses = value || false
+    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
+      @use_merging
+    end
+
+    #
+    # Get or set whether this process owns final 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.
+    #
+    def finalize_merge(value = :__no_arg__)
+      unless value == :__no_arg__
+        @finalize_merge = value
+        @finalize_merge_explicit = true
+      end
+
+      return @finalize_merge if defined?(@finalize_merge_explicit) && @finalize_merge_explicit
+
+      inferred = inferred_finalize_merge?
+      warn_about_inferred_finalize_merge unless inferred
+      inferred
+    end
+
+    def finalize_merge?
+      finalize_merge
+    end
+
+    # @api private
+    def merge_finalization_owner?
+      collating_result? || finalize_merge?
+    end
+
+    # DEPRECATED: alias for `merging`. Same value, same behavior.
+    def use_merging(use = nil)
+      SimpleCov::Deprecation.warn("`SimpleCov.use_merging` is deprecated. " \
+                                  "Replace with `SimpleCov.merging` (same value, same behavior).")
+      @use_merging = use unless use.nil?
+      @use_merging = true unless defined?(@use_merging) && @use_merging == false
+    end
+
+    #
+    # Defines the maximum age (in seconds) of a resultset to still be
+    # included in merged results. Default is 600 seconds (10 minutes).
+    #
+    def merge_timeout(seconds = nil)
+      @merge_timeout = seconds if seconds.is_a?(Integer)
+      @merge_timeout ||= 600
+    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.
+    #
+    def parallel_wait_timeout(seconds = nil)
+      @parallel_wait_timeout = seconds if seconds.is_a?(Integer)
+      @parallel_wait_timeout ||= 60
+    end
+
+  private
+
+    def inferred_finalize_merge?
+      return true unless merging
+
+      adapter = SimpleCov::ParallelAdapters.current
+      return true unless adapter
+      return true unless adapter.expected_worker_count > 1
+      return true unless parallel_worker_environment?
+      return true unless explicit_custom_coverage_destination?
+
+      false
+    end
+
+    def parallel_worker_environment?
+      ENV.key?("TEST_ENV_NUMBER") || ENV.key?("PARALLEL_TEST_GROUPS")
+    end
+
+    def explicit_custom_coverage_destination?
+      return false unless explicit_coverage_destination?
+
+      coverage_path != File.expand_path("coverage", root)
+    end
+
+    def explicit_coverage_destination?
+      (defined?(@coverage_path_explicit) && @coverage_path_explicit) ||
+        (defined?(@coverage_dir_explicit) && @coverage_dir_explicit)
+    end
+
+    def warn_about_inferred_finalize_merge
+      return if defined?(@finalize_merge_inference_warned) && @finalize_merge_inference_warned
+      return unless print_errors
+
+      @finalize_merge_inference_warned = true
+      warn SimpleCov::Color.colorize(inferred_finalize_merge_warning, :yellow)
+    end
+
+    def inferred_finalize_merge_warning
+      "SimpleCov inferred `finalize_merge false` because this parallel worker is merging " \
+        "into a custom coverage destination. Set `SimpleCov.finalize_merge false` to keep " \
+        "external collation ownership, or `SimpleCov.finalize_merge true` if this worker " \
+        "should wait, merge, format, enforce thresholds, and write `.last_run.json`. " \
+        "See https://github.com/simplecov-ruby/simplecov#merge-finalization-ownership."
+    end
+  end
+end