simplecov 0.22.0 → 1.3.0

data/lib/simplecov/configuration/filters.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  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, not substring matches, a
+    # deliberate departure from the legacy `add_filter` semantics.
+    #
+    # 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 << BlockFilter.new(block) if block
+      cover_filters
+    end
+
+    def cover_filters
+      @cover_filters ||= []
+    end
+
+    # 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
+
+    def track_files(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.
+    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
+
+    # 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
+    end
+
+    def filters
+      @filters ||= []
+    end
+
+    #
+    # Drop matching files from the coverage report. The inverse of `cover`.
+    # 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
+
+    def add_filter(filter_argument = nil, &block)
+      example = block ? "`SimpleCov.skip { ... }`" : "`SimpleCov.skip #{filter_argument.inspect}`"
+      Deprecation.warn("`SimpleCov.add_filter` is deprecated. " \
+                       "Replace with `SimpleCov.skip` (same arguments, same behavior). Example: #{example}.")
+      skip(filter_argument, &block)
+    end
+
+    # `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
+
+    def clear_filters
+      @filters = []
+    end
+
+    # Order matters: call this before your own `skip` invocations.
+    def no_default_skips
+      clear_filters
+    end
+
+    private
+
+    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
+
+      Filter.build_filter(filter)
+    end
+
+    # Strings are treated as globs, not substrings (that's `skip`'s
+    # semantics); everything else dispatches exactly like `add_filter`.
+    def build_cover_filter(arg)
+      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
+
+    # Descends into `ArrayFilter` wrappers built by `cover(["a", "b"])`.
+    def collect_cover_globs(filter_list)
+      filter_list.flat_map do |filter|
+        case filter
+        when GlobFilter then filter.filter_argument
+        when ArrayFilter then collect_cover_globs(filter.filter_argument)
+        else []
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/configuration/formatting.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "../formatter/multi_formatter"
+
+module SimpleCov
+  module Configuration
+    attr_writer :formatter, :print_error_status
+
+    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
+      end
+    end
+
+    def formatters(formatters = :__no_arg__)
+      case formatters
+      when :__no_arg__
+        configured = formatter
+        configured ? [configured] : []
+      else
+        self.formatters = formatters
+      end
+    end
+
+    # `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)
+      @formatter = combined_formatter(Array(formatters || nil))
+    end
+
+    def color(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
+
+    def print_errors(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
+
+    def source_in_json(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
+
+    def print_error_status
+      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
+
+    def nocov_token(nocov_token = nil)
+      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_method :skip_token, :nocov_token
+
+    def current_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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    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
+
+    # 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
+
+    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
+      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/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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    IGNORABLE_BRANCH_TYPES = %i[implicit_else eval_generated].freeze
+    IGNORABLE_METHOD_TYPES = %i[eval_generated].freeze
+
+    # 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)
+      Deprecation.warn("`SimpleCov.ignore_branches` is deprecated. " \
+                       "Replace with `coverage(:branch) { ignore #{types.map(&:inspect).join(", ")} }`.")
+      store_ignored_branches(types)
+    end
+
+    def ignored_branches
+      @ignored_branches ||= []
+    end
+
+    def ignored_branch?(type)
+      ignored_branches.include?(type)
+    end
+
+    def ignore_methods(*types)
+      Deprecation.warn("`SimpleCov.ignore_methods` is deprecated. " \
+                       "Replace with `coverage(:method) { ignore #{types.map(&:inspect).join(", ")} }`.")
+      store_ignored_methods(types)
+    end
+
+    def ignored_methods
+      @ignored_methods ||= []
+    end
+
+    def ignored_method?(type)
+      ignored_methods.include?(type)
+    end
+
+    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 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 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,197 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    #
+    # Whether SimpleCov should hook `Process._fork` to attach itself to
+    # subprocesses. Required when the suite uses parallel test workers (Rails'
+    # `parallelize(workers:)`). Defaults to false.
+    #
+    def merge_subprocesses(value = nil)
+      return @enable_for_subprocesses if instance_variable_defined?(:@enable_for_subprocesses) && value.nil?
+
+      self.merge_subprocesses = value
+      @enable_for_subprocesses
+    end
+
+    # false stands in for nothing, so the answer is always a real opt-in or
+    # opt-out.
+    def merge_subprocesses=(value)
+      @enable_for_subprocesses = value || false
+    end
+
+    # @api private
+    def enabled_for_subprocesses?
+      !!@enable_for_subprocesses
+    end
+
+    #
+    # 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 @parallel_tests if value.eql?(:__no_arg__)
+
+      self.parallel_tests = _ = value
+    end
+
+    def parallel_tests=(value)
+      @parallel_tests = value
+    end
+
+    def enable_for_subprocesses(value = nil)
+      Deprecation.warn("`SimpleCov.enable_for_subprocesses` is deprecated. " \
+                       "Replace with `SimpleCov.merge_subprocesses` (same value, same behavior).")
+      merge_subprocesses(value)
+    end
+
+    def merging(use = nil)
+      self.merging = use unless use.nil?
+      # Unset reads as nil, and only an explicit `merging false` turns it off.
+      @use_merging = true if @use_merging.nil?
+      @use_merging
+    end
+
+    def merging=(use)
+      @use_merging = use
+    end
+
+    #
+    # Whether SimpleCov's selected final process owns merge processing: waiting
+    # for sibling workers, building the merged result, formatting, enforcing
+    # thresholds, and writing `.last_run.json`.
+    #
+    # Defaults to true, except for recognized multi-worker parallel runs that
+    # explicitly write to a custom coverage destination while merging is
+    # enabled. Those runs are likely using an external `SimpleCov.collate` step
+    # to finalize the merge.
+    #
+    # Splatted rather than defaulted: false is a value someone sets on purpose,
+    # so "given nothing" cannot be told from it by looking at the argument.
+    def finalize_merge(*value)
+      unless value.empty?
+        explicit, = value
+        self.finalize_merge = _ = explicit
+      end
+
+      return @finalize_merge if @finalize_merge_explicit
+
+      inferred = inferred_finalize_merge?
+      warn_about_inferred_finalize_merge unless inferred
+      inferred
+    end
+
+    # Writing is what makes the answer explicit rather than inferred.
+    def finalize_merge=(value)
+      @finalize_merge = value
+      @finalize_merge_explicit = true
+    end
+
+    def finalize_merge?
+      finalize_merge
+    end
+
+    # @api private
+    def merge_finalization_owner?
+      collating_result? || (finalize_merge? && final_result_process?)
+    end
+
+    def use_merging(use = nil)
+      Deprecation.warn("`SimpleCov.use_merging` is deprecated. " \
+                       "Replace with `SimpleCov.merging` (same value, same behavior).")
+      merging(use)
+    end
+
+    #
+    # The maximum age (in seconds) of a resultset to still be included in
+    # merged results. Default is 600 seconds.
+    #
+    # A numeric SIMPLECOV_MERGE_TIMEOUT in the environment takes precedence
+    # over the configured value: `simplecov watch` re-runs test subsets across
+    # a long session and extends its child runs' merge window this way, where
+    # editing every watched project's configuration is not an option.
+    #
+    def merge_timeout(seconds = nil)
+      self.merge_timeout = seconds
+      # Memoized through a local rather than `|| (@merge_timeout ||= 600)`:
+      # steep 2.0's logic-type interpreter crashes on an or-assignment nested in
+      # a logical operand, and ivar narrowing doesn't carry across statements
+      # the way a local's does.
+      configured = @merge_timeout || 600
+      @merge_timeout = configured
+      env_merge_timeout || configured
+    end
+
+    # Anything but an Integer is ignored, the way the dual method always did.
+    def merge_timeout=(seconds)
+      @merge_timeout = seconds if seconds.instance_of?(Integer)
+    end
+
+    def env_merge_timeout
+      value = ENV.fetch("SIMPLECOV_MERGE_TIMEOUT", nil)
+      Integer(value, 10) if value&.match?(/\A\d+\z/)
+    end
+
+    #
+    # How long (in seconds) the reporting process waits for the remaining
+    # parallel-test workers to write their resultsets before it proceeds with a
+    # partial merge. Default is 60 seconds. Raise it when a slow worker
+    # routinely finishes well after the others, so its coverage is still
+    # included and the threshold checks aren't skipped against a partial total.
+    #
+    def parallel_wait_timeout(seconds = nil)
+      self.parallel_wait_timeout = seconds
+      @parallel_wait_timeout ||= 60
+    end
+
+    # Anything but an Integer is ignored, the way the dual method always did.
+    def parallel_wait_timeout=(seconds)
+      @parallel_wait_timeout = seconds if seconds.instance_of?(Integer)
+    end
+
+    private
+
+    def inferred_finalize_merge?
+      return true unless merging
+
+      adapter = 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.eql?(File.expand_path("coverage", root))
+    end
+
+    def explicit_coverage_destination?
+      @coverage_path_explicit || @coverage_dir_explicit
+    end
+
+    def warn_about_inferred_finalize_merge
+      return if @finalize_merge_inference_warned
+      return unless print_errors
+
+      @finalize_merge_inference_warned = true
+      warn 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

data/lib/simplecov/configuration/missed_caps.rb

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

data/lib/simplecov/configuration/production.rb

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