simplecov 1.1.0 → 1.2.0

data/lib/simplecov/exit_codes.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Exit statuses SimpleCov sets when coverage checks fail, and the output
-  # helper the enforcement machinery reports through.
   module ExitCodes
     SUCCESS = 0
     EXCEPTION = 1
@@ -10,21 +8,33 @@ module SimpleCov
     MAXIMUM_COVERAGE_DROP = 3
     MAXIMUM_COVERAGE = 4
 
-    # Threshold-violation reports and exit-status notices are the output of
-    # the enforcement feature, not Ruby warnings: routing them through
-    # `Kernel#warn` made `-W0` swallow the explanation for a failing exit
-    # code, let `Warning.warn` hooks (warning trackers, raise-on-warning
-    # test setups) intercept them mid-`at_exit`, and fed colorized text to
+    # The plural unit each criterion's misses count in, for the checks that report
+    # counts rather than percents.
+    UNITS = {line: "lines", branch: "branches", method: "methods"}.freeze
+
+    # Threshold-violation reports and exit-status notices are the output of the
+    # enforcement feature, not Ruby warnings: routing them through `Kernel#warn`
+    # made `-W0` swallow the explanation for a failing exit code, let
+    # `Warning.warn` hooks intercept them mid-at_exit, and fed colorized text to
     # warning logs. `print_errors false` remains the intended opt-out.
+    #
+    # A parallel runner can close a worker's stderr before its at_exit hooks
+    # run, hence the rescue.
     def self.print_error(message)
       $stderr.puts message # rubocop:disable Style/StderrPuts
+    rescue IOError
+      # The violation still has to set the exit status even when its
+      # explanation cannot be printed.
     end
   end
 end
 
 require_relative "exit_codes/check"
+require_relative "exit_codes/baseline_check"
 require_relative "exit_codes/exit_code_handling"
 require_relative "exit_codes/maximum_coverage_drop_check"
+require_relative "exit_codes/maximum_missed_check"
+require_relative "exit_codes/maximum_missed_per_file_check"
 require_relative "exit_codes/maximum_overall_coverage_check"
 require_relative "exit_codes/minimum_coverage_by_file_check"
 require_relative "exit_codes/minimum_coverage_by_group_check"

data/lib/simplecov/exit_handling.rb

@@ -2,9 +2,11 @@
 
 require "English"
 
-# `at_exit` orchestration: post-suite report generation, threshold
-# checks, deferral when a sibling subprocess already wrote a fresher
-# report, and exit-status propagation.
+#
+# `at_exit` orchestration: post-suite report generation, threshold checks,
+# deferral when a sibling subprocess already wrote a fresher report, and
+# exit-status propagation.
+#
 module SimpleCov
   class << self
     # @api private
@@ -14,38 +16,59 @@ module SimpleCov
       :minimum_coverage_by_file_overrides,
       :minimum_coverage_by_group,
       :maximum_coverage,
-      :maximum_coverage_drop
+      :maximum_coverage_drop,
+      :maximum_missed,
+      :maximum_missed_per_file,
+      :maximum_missed_per_file_overrides,
+      :baseline
     )
 
     def at_exit_behavior
-      # If we are in a different process than called start, don't interfere.
-      return if SimpleCov.pid != Process.pid
+      # A different process than the one that called start; don't interfere.
+      return unless started_in_this_process?
 
-      # If Coverage is no longer running (e.g. someone manually stopped it
-      # or a test consumed the result) then don't run exit tasks.
+      # Coverage is no longer running (someone stopped it manually, or a test
+      # consumed the result), so don't run exit tasks.
       return unless Coverage.running?
 
-      # Capture the suite's exit status BEFORE the deferral probe: its
-      # freshness check rescues filesystem errors, and completing any
-      # rescue inside an at_exit handler resets $ERROR_INFO to nil.
+      # Captured BEFORE the deferral probe: its freshness check rescues
+      # filesystem errors, and completing any rescue inside an at_exit handler
+      # resets $ERROR_INFO to nil.
       error_exit_status = exit_status_from_exception
 
       # Stand down when we'd only clobber a fresher report (#581).
       return if defer_to_existing_report?
 
-      SimpleCov.run_exit_tasks!(error_exit_status)
+      run_exit_tasks!(error_exit_status)
     end
 
-    # @api private — called from the at_exit block (which pre-captures
-    # the status, see there) and by `collate` (the default argument).
-    def run_exit_tasks!(error_exit_status = exit_status_from_exception)
+    # @api private -- everything the end of a measured run does, answered as the
+    # exit status the process should end with rather than performed as an exit.
+    # The one side effect left to the caller is ending the process, which is
+    # what makes this whole path answerable from inside a test.
+    def run_exit_tasks(error_exit_status = exit_status_from_exception)
       at_exit.call
 
-      exit_and_report_previous_error(error_exit_status) if previous_error?(error_exit_status)
-      process_results_and_report_error if ready_to_process_results?
+      if previous_error?(error_exit_status)
+        report_previous_error
+        error_exit_status
+      elsif ready_to_process_results?
+        report_processing_failure(process_result(result))
+      else
+        ExitCodes::SUCCESS
+      end
     end
 
-    # @api private — returns the exit status from the exit exception.
+    # @api private -- the exiting adapter over `run_exit_tasks`, called from the
+    # at_exit block (which pre-captures the status, see there) and by `collate`.
+    def run_exit_tasks!(error_exit_status = exit_status_from_exception)
+      status = run_exit_tasks(error_exit_status)
+
+      # Force exit with stored status (#5).
+      Kernel.exit(status) unless successful?(status)
+    end
+
+    # @api private
     def exit_status_from_exception
       @exit_exception = $ERROR_INFO
       return nil unless @exit_exception
@@ -53,76 +76,88 @@ module SimpleCov
       if @exit_exception.is_a?(SystemExit)
         @exit_exception.status
       else
-        SimpleCov::ExitCodes::EXCEPTION
+        ExitCodes::EXCEPTION
       end
     end
 
-    # @api private — strict boolean so rspec-mocks 4's predicate matcher
-    # accepts it. test_unit sets status 0 on success, so SUCCESS must
-    # also be treated as "not a previous error".
+    # @api private -- strict boolean so rspec-mocks 4's predicate matcher
+    # accepts it. test_unit sets status 0 on success, so SUCCESS must also be
+    # treated as "not a previous error".
     def previous_error?(error_exit_status)
-      !!(error_exit_status && error_exit_status != SimpleCov::ExitCodes::SUCCESS)
+      return false unless error_exit_status
+
+      !successful?(error_exit_status)
     end
 
-    # @api private
-    def exit_and_report_previous_error(exit_status)
-      if print_errors
-        ExitCodes.print_error SimpleCov::Color.colorize(
-          "Stopped processing SimpleCov as a previous error not related to SimpleCov has been detected",
-          :yellow
-        )
-      end
-      Kernel.exit(exit_status)
+    # @api private -- the notice alone; the status it accompanies is the
+    # caller's to answer with.
+    def report_previous_error
+      return unless print_errors
+
+      ExitCodes.print_error Color.colorize(
+        "Stopped processing SimpleCov as a previous error not related to SimpleCov has been detected",
+        :yellow
+      )
     end
 
-    # @api private — the process that owns final merge processing is the
-    # only one that reports against thresholds, and only when its
-    # `wait_for_other_processes` confirmed every sibling reported.
-    # When the wait times out, the merged total is partial and
-    # comparing it against `minimum_coverage` / `maximum_coverage`
-    # would surface a spurious "below minimum" violation about the
-    # missing slice rather than a real shortfall.
+    # @api private. The process that owns final merge processing is the only one
+    # that reports against thresholds, and only when its
+    # `wait_for_other_processes` confirmed every sibling reported. When the wait
+    # times out the merged total is partial, and comparing it against the
+    # thresholds would surface a spurious violation about the missing slice.
     def ready_to_process_results?
       merge_finalization_owner? && result? &&
         (collating_result? || parallel_results_complete?)
     end
 
-    def process_results_and_report_error
-      exit_status = process_result(result)
-
-      # Force exit with stored status (see github issue #5)
-      return unless exit_status.positive?
-
-      if print_errors
-        ExitCodes.print_error SimpleCov::Color.colorize(
+    # @api private -- answers the status it was handed, explaining it first when
+    # it is a coverage failure worth explaining.
+    def report_processing_failure(exit_status)
+      if exit_status.positive? && print_errors
+        ExitCodes.print_error Color.colorize(
           "SimpleCov failed with exit #{exit_status} due to a coverage related error", :red
         )
       end
-      Kernel.exit exit_status
+      exit_status
     end
 
-    # @api private — `exit_status = SimpleCov.process_result(SimpleCov.result)`.
+    # @api private. The history entry is recorded on the same successful-run
+    # condition `.last_run.json` uses, so a run that failed its thresholds
+    # becomes neither the drop baseline nor a data point in the trend.
     def process_result(result)
       result_exit_status = result_exit_status(result)
-      write_last_run(result) if result_exit_status == SimpleCov::ExitCodes::SUCCESS
+      if successful?(result_exit_status)
+        write_last_run(result)
+        History.record(result)
+      end
       result_exit_status
     end
 
+    # mutant:disable -- a pid is an Integer, and Integers answer ==, eql? and
+    # equal? alike for the same value.
+    def started_in_this_process?
+      SimpleCov.pid == Process.pid
+    end
+
+    # Asked as a predicate rather than compared against `ExitCodes::SUCCESS`,
+    # because two equal Integers are equal through every spelling of the
+    # comparison.
+    def successful?(status)
+      status.zero?
+    end
+
     def result_exit_status(result)
       ExitCodes::ExitCodeHandling.call(result, coverage_limits: build_coverage_limits)
     end
 
-  private
+    private
 
+    # Every CoverageLimits member is named after the configuration reader that
+    # supplies it, so a new limit only has to be added to the Data definition
+    # and the checks.
     def build_coverage_limits
-      CoverageLimits.new(
-        minimum_coverage: minimum_coverage,
-        minimum_coverage_by_file: minimum_coverage_by_file,
-        minimum_coverage_by_file_overrides: minimum_coverage_by_file_overrides,
-        minimum_coverage_by_group: minimum_coverage_by_group,
-        maximum_coverage: maximum_coverage,
-        maximum_coverage_drop: maximum_coverage_drop
-      )
+      limits = CoverageLimits.members.to_h { |name| [name, public_send(name)] } #: Hash[Symbol, untyped]
+      CoverageLimits.new(**limits)
     end
   end
 end

data/lib/simplecov/file_list.rb

@@ -1,31 +1,20 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # An array of SimpleCov SourceFile instances with additional collection helper
-  # methods for calculating coverage across them etc.
   class FileList
     include Enumerable
     extend Forwardable
 
-    def_delegators :@files,
-                   # For Enumerable
-                   :each,
-                   # also delegating methods implemented in Enumerable as they have
-                   # custom Array implementations which are presumably better/more
-                   # resource efficient
-                   :size, :map, :count,
-                   # surprisingly not in Enumerable
-                   :empty?, :length,
-                   # still act like we're kinda an array
-                   :to_a, :to_ary
+    # Enumerable's own implementations are skipped where Array has a better
+    # one, and `to_a` / `to_ary` keep this acting like the array it wraps.
+    def_delegators :@files, :each, :size, :map, :count, :empty?, :length, :to_a, :to_ary
 
     def initialize(files)
       @files = files
     end
 
-    # The per-criterion coverage statistics across all files. With no argument
-    # returns the `{line:, branch:, method:}` Hash; pass a criterion symbol
-    # (`:line` / `:branch` / `:method`) to get that one CoverageStatistics.
+    # With no argument answers the `{line:, branch:, method:}` Hash, and with a
+    # criterion symbol that one CoverageStatistics.
     def coverage_statistics(criterion = nil)
       stats = (@coverage_statistics ||= compute_coverage_statistics)
       criterion ? stats[criterion] : stats
@@ -35,34 +24,27 @@ module SimpleCov
       @coverage_statistics_by_file ||= compute_coverage_statistics_by_file
     end
 
-    # Returns the count of lines that have coverage
     def covered_lines
       coverage_statistics[:line]&.covered
     end
 
-    # Returns the count of lines that have been missed
     def missed_lines
       coverage_statistics[:line]&.missed
     end
 
-    # Returns the count of lines that are not relevant for coverage
     def never_lines
       sum { |f| f.never_lines.size }
     end
 
-    # Returns the count of skipped lines
     def skipped_lines
       sum { |f| f.skipped_lines.size }
     end
 
-    # Computes the coverage based upon lines covered and lines missed for each file
-    # Returns an array with all coverage percentages
     def covered_percentages
       map(&:covered_percent)
     end
 
-    # Finds the least covered file and returns that file's name, or nil
-    # for an empty list (e.g. a fully filtered result).
+    # Nil for an empty list, such as a fully filtered result.
     def least_covered_file
       # `covered_percent` is nil only for an unmeasured criterion, and :line
       # is always measured, so the `|| 0.0` arm never fires at runtime; it
@@ -70,36 +52,28 @@ module SimpleCov
       min_by { |file| file.covered_percent || 0.0 }&.filename
     end
 
-    # Returns the overall amount of relevant lines of code across all files in this list
     def lines_of_code
       coverage_statistics[:line]&.total
     end
 
-    # The coverage across all files in percent, for the given criterion (line
-    # by default). Returns nil if the criterion was not measured.
-    # @return [Float, nil]
+    # Nil if the criterion was not measured.
     def covered_percent(criterion = :line)
       coverage_statistics(criterion)&.percent
     end
 
-    # The strength (average hits per relevant unit) for the given criterion
-    # (line by default).
-    # @return [Float, nil]
+    # The strength (average hits per relevant unit) for the given criterion.
     def covered_strength(criterion = :line)
       coverage_statistics(criterion)&.strength
     end
 
-    # Return total count of branches in all files
     def total_branches
       coverage_statistics[:branch]&.total
     end
 
-    # Return total count of covered branches
     def covered_branches
       coverage_statistics[:branch]&.covered
     end
 
-    # Return total count of covered branches
     def missed_branches
       coverage_statistics[:branch]&.missed
     end
@@ -108,17 +82,14 @@ module SimpleCov
       coverage_statistics[:branch]&.percent
     end
 
-    # Return total count of methods in all files
     def total_methods
       coverage_statistics[:method]&.total
     end
 
-    # Return total count of covered methods
     def covered_methods
       coverage_statistics[:method]&.covered
     end
 
-    # Return total count of missed methods
     def missed_methods
       coverage_statistics[:method]&.missed
     end
@@ -127,23 +98,21 @@ module SimpleCov
       coverage_statistics[:method]&.percent
     end
 
-  private
+    private
 
-    # Seed the result hash with one entry per criterion the user
-    # enabled — so an empty FileList (e.g. a group with no files) still
-    # yields the right shape — then fold each file's stats into the
-    # matching bucket. `SourceFile#coverage_statistics` always reports
-    # all three criteria; FileList is the layer that filters to the
-    # enabled set so disabled criteria don't surface in totals, JSON,
-    # or the HTML report.
+    # Seeded with one entry per criterion the user enabled, so an empty FileList
+    # still yields the right shape. `SourceFile#coverage_statistics` always
+    # reports all three criteria; FileList is the layer that filters to the
+    # enabled set so disabled criteria don't surface in totals, JSON, or the
+    # HTML report.
     def compute_coverage_statistics_by_file
       seed = enabled_criteria_for_reporting.to_h do |criterion|
         bucket = [] #: Array[CoverageStatistics]
         [criterion, bucket]
       end
-      @files.each_with_object(seed) do |file, together|
+      each_with_object(seed) do |file, together|
         file.coverage_statistics.each do |criterion, stats|
-          together[criterion] << stats if together.key?(criterion)
+          together.fetch(criterion) << stats if together.key?(criterion)
         end
       end
     end
@@ -152,12 +121,12 @@ module SimpleCov
       coverage_statistics_by_file.transform_values { |stats| CoverageStatistics.from(stats) }
     end
 
-    # `:line` (or its `:oneshot_line` synonym) is reported when either
-    # criterion is enabled; the JRuby-gated branch/method criteria are
-    # reported when they pass their own engine-support check.
+    # `:line` (or its `:oneshot_line` synonym) is reported when either criterion
+    # is enabled; the JRuby-gated branch/method criteria are reported when they
+    # pass their own engine-support check.
     def enabled_criteria_for_reporting
       criteria = [] #: Array[SimpleCov::criterion]
-      criteria << :line   if SimpleCov.line_coverage?
+      criteria << :line if SimpleCov.line_coverage?
       criteria << :branch if SimpleCov.branch_coverage?
       criteria << :method if SimpleCov.method_coverage?
       criteria

data/lib/simplecov/filter.rb

@@ -2,15 +2,8 @@
 
 module SimpleCov
   #
-  # Base filter class. Inherit from this to create custom filters,
-  # and overwrite the matches?(source_file) instance method
-  #
-  # # A sample class that rejects all source files.
-  # class StupidFilter < SimpleCov::Filter
-  #   def matches?(source_file)
-  #     false
-  #   end
-  # end
+  # Base filter class. Inherit from this to create custom filters, and
+  # override `matches?(source_file)`.
   #
   class Filter
     attr_reader :filter_argument
@@ -25,50 +18,46 @@ module SimpleCov
 
     # Whether this filter's verdict depends only on the file's path, so it can
     # be decided before that file has any coverage. Used when recording which
-    # tracked files a process did not load, where no coverage exists yet.
-    # Defaults to false so a custom filter is never guessed at. See #1250.
+    # tracked files a process did not load. Defaults to false so a custom
+    # filter is never guessed at (#1250).
     def path_only?
       false
     end
 
-    # `string_filter` selects the semantics of bare String arguments —
-    # StringFilter's segment-substring match for `add_filter`/`skip`,
-    # GlobFilter for `cover` — and threads through Array elements so a
-    # list gets the same treatment as its members.
-    def self.build_filter(filter_argument, string_filter: SimpleCov::StringFilter)
+    # `string_filter` selects the semantics of bare String arguments:
+    # StringFilter's segment-substring match for `skip`, GlobFilter for
+    # `cover`. It threads through Array elements so a list gets the same
+    # treatment as its members.
+    def self.build_filter(filter_argument, string_filter: StringFilter)
       case filter_argument
-      when SimpleCov::Filter then filter_argument
-      when String            then string_filter.new(filter_argument)
+      when Filter then filter_argument
+      when String then string_filter.new(filter_argument)
       when Array
-        SimpleCov::ArrayFilter.new(filter_argument.map { |arg| build_filter(arg, string_filter: string_filter) })
+        ArrayFilter.new(filter_argument.map { |arg| build_filter(arg, string_filter: string_filter) })
       else class_for_argument(filter_argument).new(filter_argument)
       end
     end
 
     def self.class_for_argument(filter_argument)
       filter_classes_by_argument_type.find { |type, _| filter_argument.is_a?(type) }&.last ||
-        raise(SimpleCov::ConfigurationError, "You have provided an unrecognized filter type")
+        raise(ConfigurationError, "You have provided an unrecognized filter type")
     end
 
     def self.filter_classes_by_argument_type
       @filter_classes_by_argument_type ||= {
-        String => SimpleCov::StringFilter,
-        Regexp => SimpleCov::RegexFilter,
-        Array => SimpleCov::ArrayFilter,
-        Proc => SimpleCov::BlockFilter
+        String => StringFilter,
+        Regexp => RegexFilter,
+        Array => ArrayFilter,
+        Proc => BlockFilter
       }.freeze
     end
     private_class_method :filter_classes_by_argument_type
   end
 
-  # Filter that matches when the source file's project path contains the
-  # configured string at a path-segment boundary.
-  class StringFilter < SimpleCov::Filter
-    # Returns true when the given source file's filename matches the
-    # string configured when initializing this Filter with StringFilter.new('somestring').
-    # Matching is path-segment-aware: the argument must appear immediately after a "/"
-    # and be followed by "/" or end-of-string, so "lib" matches "/lib/foo.rb" but not
-    # "/app/models/library.rb".
+  class StringFilter < Filter
+    # Matching is path-segment-aware: the argument must appear immediately
+    # after a "/" and be followed by "/" or end-of-string, so "lib" matches
+    # "/lib/foo.rb" but not "/app/models/library.rb".
     def matches?(source_file)
       source_file.project_filename.match?(segment_pattern)
     end
@@ -77,7 +66,7 @@ module SimpleCov
       true
     end
 
-  private
+    private
 
     def segment_pattern
       @segment_pattern ||= compute_segment_pattern
@@ -85,34 +74,32 @@ module SimpleCov
 
     def compute_segment_pattern
       normalized = filter_argument.delete_prefix("/")
-      escaped    = Regexp.escape(normalized)
-      boundary   = '(?:\A|/)'
+      escaped = Regexp.escape(normalized)
+      boundary = '(?:\A|/)'
 
       if normalized.end_with?("/")
         # Trailing slash signals directory-only matching.
         /#{boundary}#{escaped}/
       elsif normalized.include?(".") && !normalized.include?("/")
-        # Bare filename pattern (e.g. "test.rb" matches "faked_test.rb"):
-        # allow a substring match within a single path segment. Multi-segment
-        # arguments must not get this relaxation, or "app/models/user.rb"
-        # would also match "webapp/models/user.rb".
-        %r{#{boundary}[^/]*#{escaped}(?=[/.]|\z)}
+        # Bare filename pattern ("test.rb" matches "faked_test.rb"): allow a
+        # substring match within a single path segment. Multi-segment arguments
+        # must not get this relaxation, or "app/models/user.rb" would also
+        # match "webapp/models/user.rb". No boundary here: `[^/]*` already
+        # reaches back to the segment start, so prefixing one matches the same
+        # paths.
+        %r{[^/]*#{escaped}(?=[/.]|\z)}
       else
-        # Directory or path: require a segment-boundary match so "lib"
-        # matches "lib/" but not "library/".
+        # Require a segment-boundary match so "lib" matches "lib/" but not
+        # "library/".
         %r{#{boundary}#{escaped}(?=[/.]|\z)}
       end
     end
   end
 
-  # Filter that matches when the source file's project path matches the
-  # configured Regexp.
-  class RegexFilter < SimpleCov::Filter
-    # Returns true when the given source file's filename matches the
-    # regex configured when initializing this Filter with RegexFilter.new(/someregex/).
-    # Uses `Regexp#match?` so the predicate returns a real boolean — `=~`
-    # would return the match position (an Integer or nil), which trips
-    # rspec-mocks 4's stricter predicate-matcher type check.
+  class RegexFilter < Filter
+    # `Regexp#match?` rather than `=~` so the predicate returns a real boolean:
+    # `=~` would return the match position, which trips rspec-mocks 4's
+    # stricter predicate-matcher type check.
     def matches?(source_file)
       filter_argument.match?(source_file.project_filename)
     end
@@ -122,21 +109,16 @@ module SimpleCov
     end
   end
 
-  # Filter that matches when the configured block returns truthy for the
-  # source file.
-  class BlockFilter < SimpleCov::Filter
-    # Returns true if the block given when initializing this filter with BlockFilter.new {|src_file| ... }
-    # returns true for the given source file.
+  class BlockFilter < Filter
     def matches?(source_file)
       filter_argument.call(source_file)
     end
   end
 
-  # Filter that matches when the source file's project path matches the
-  # configured shell glob (e.g. "lib/**/*.rb"). Used by `cover` and
-  # `skip` when callers want glob semantics instead of the substring
-  # match of `StringFilter`.
-  class GlobFilter < SimpleCov::Filter
+  # Matches when the source file's project path matches the configured shell
+  # glob. Used by `cover`, and by `skip` when callers want glob semantics
+  # instead of `StringFilter`'s substring match.
+  class GlobFilter < Filter
     def matches?(source_file)
       File.fnmatch?(filter_argument, source_file.project_filename, File::FNM_PATHNAME | File::FNM_EXTGLOB)
     end
@@ -146,9 +128,7 @@ module SimpleCov
     end
   end
 
-  # Filter that matches when any of its component filters (built from the
-  # array's elements) match the source file.
-  class ArrayFilter < SimpleCov::Filter
+  class ArrayFilter < Filter
     def initialize(filter_argument)
       filter_objects = filter_argument.map do |arg|
         Filter.build_filter(arg)
@@ -157,13 +137,10 @@ module SimpleCov
       super(filter_objects)
     end
 
-    # Path-decidable only when every component filter is.
     def path_only?
       filter_argument.all?(&:path_only?)
     end
 
-    # Returns true if any of the filters in the array match the given source file.
-    # Configure this Filter like StringFilter.new(['some/path', /^some_regex/, Proc.new {|src_file| ... }])
     def matches?(source_files_list)
       filter_argument.any? do |arg|
         arg.matches?(source_files_list)