simplecov 1.1.1 → 1.3.0

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)

data/lib/simplecov/formatter/base.rb

@@ -6,42 +6,35 @@ module SimpleCov
   module Formatter
     # @api private
     #
-    # Shared scaffolding for formatters that write a coverage report to
-    # an output directory and emit a "Coverage report generated for X
-    # to Y" summary on stderr (it's a status message, not data).
-    # Subclasses override `format` to do their actual writing, and may
-    # override `message_prefix` (e.g. JSON prepends "JSON ").
+    # Shared scaffolding for formatters that write a coverage report to an
+    # output directory and emit a "Coverage report generated for X to Y"
+    # summary on stderr. Subclasses override `format`, and may override
+    # `message_prefix`.
     class Base
-      # `output_dir` defaults to `SimpleCov.coverage_path` so the at_exit
-      # pipeline keeps working unchanged. Pass it explicitly to write
-      # somewhere else (handy for tests that don't want to clobber the
-      # project's `coverage/` directory).
+      # `output_dir` defaults to `SimpleCov.coverage_path`. Pass it explicitly
+      # to write somewhere else.
       def initialize(silent: false, output_dir: nil)
         @silent = silent
         @output_dir = output_dir
       end
 
-    private
+      private
 
       # The one home of the "status lines go to stderr, not through warn"
-      # decision (see #1225). stderr rather than stdout because this is a
-      # status message, not the program's output, so it stays out of
-      # pipelines like `rspec -f json`. And `$stderr.puts` rather than
-      # `warn` so the line neither reaches `Warning.warn` hooks (warning
-      # trackers, raise-on-warning test setups) nor vanishes under `-W0`.
-      # Subclasses call this at the end of their `format`.
+      # decision (#1225). stderr rather than stdout because this is a status
+      # message, not the program's output, so it stays out of pipelines like
+      # `rspec -f json`. And `$stderr.puts` rather than `warn` so the line
+      # neither reaches `Warning.warn` hooks nor vanishes under `-W0`.
       def emit_status(result)
         $stderr.puts output_message(result) unless @silent # rubocop:disable Style/StderrPuts
       rescue IOError
-        # A parallel runner can close a worker's stderr before its at_exit
-        # hooks run (rspec-conductor does). Losing the status line must not
-        # abort the exit tasks that follow report generation, i.e. the
-        # threshold checks and the .last_run.json write.
+        # A parallel runner can close a worker's stderr before its at_exit hooks
+        # run (rspec-conductor does). Losing the status line must not abort the
+        # exit tasks that follow report generation.
       end
 
-      # Subclasses override to prepend a marker (e.g. "JSON ") to the
-      # summary line. Default empty for the HTML formatter, which has
-      # historically been the unmarked default.
+      # Subclasses override to prepend a marker (e.g. "JSON ") to the summary
+      # line. Empty for the HTML formatter, historically the unmarked default.
       def message_prefix
         ""
       end
@@ -50,15 +43,11 @@ module SimpleCov
         @output_dir || SimpleCov.coverage_path
       end
 
-      # The path shown in the "Coverage report generated for X to Y"
-      # status line. Renders relative to cwd when `output_path` lives
-      # inside cwd (e.g. `coverage` instead of `/Users/me/proj/coverage`)
-      # and appends the formatter's `entry_point_filename` so the line
-      # points at a concrete file the user (or a terminal that
-      # hyperlinks paths) can act on — e.g. `coverage/index.html`
-      # instead of the bare directory `coverage`. Paths outside cwd
-      # stay absolute; a `../../../tmp/cov` display would be more
-      # confusing than the absolute form. See issue #197.
+      # The path shown in the "Coverage report generated for X to Y" status line.
+      # Rendered relative to cwd when `output_path` lives inside cwd, with the
+      # formatter's `entry_point_filename` appended so the line points at a
+      # concrete file a terminal can hyperlink. Paths outside cwd stay
+      # absolute; a `../../../tmp/cov` display would be more confusing (#197).
       def displayable_output_path
         directory = relative_or_absolute_output_path
         entry_point = entry_point_filename
@@ -70,47 +59,40 @@ module SimpleCov
         relative = Pathname.new(absolute).relative_path_from(Pathname.pwd).to_s
         relative.start_with?("..") ? absolute : relative
       rescue ArgumentError
-        # Pathname#relative_path_from raises across mixed absolute/
-        # relative inputs (and across Windows drives) — keep the
-        # absolute form on any unresolvable case.
+        # Pathname#relative_path_from raises across mixed absolute/relative
+        # inputs, and across Windows drives.
         output_path
       end
 
-      # Subclasses override to name the report's entry-point file
-      # (e.g. `index.html` for HTML, `coverage.json` for JSON), which
-      # gets appended to the directory in the status line. Default nil
-      # leaves the bare directory in place for any third-party formatter
-      # that has no single canonical entry point.
+      # Subclasses override to name the report's entry-point file, which gets
+      # appended to the directory in the status line. The empty body answers
+      # nil, which leaves the bare directory in place for any third-party
+      # formatter that has no single canonical entry point.
       def entry_point_filename
-        nil
       end
 
-      # Emit one summary line per criterion that the run actually
-      # measured. The header line ("Coverage report generated for X
-      # to Y") is always first; per-criterion lines follow in the
-      # order of `result.coverage_statistics` (which is the same
-      # insertion order as `SourceFile#coverage_statistics`, which in
-      # turn reflects what the user enabled).
+      # One summary line per criterion the run actually measured, in the order
+      # of `result.coverage_statistics`, which reflects what the user enabled.
       def output_message(result)
         header = "#{message_prefix}Coverage report generated for #{result.command_name} to #{displayable_output_path}"
-        body   = result.coverage_statistics.filter_map { |criterion, stat| stats_line(criterion, stat) }
+        body = result.coverage_statistics.filter_map { |criterion, stat| stats_line(criterion, stat) }
         [header, *body].join("\n")
       end
 
-      # Returns nil for branch/method criteria that have nothing to
-      # measure (e.g. a file with no branches under branch coverage).
-      # Showing "Branch coverage: 0 / 0 (100.00%)" is noise; the older
-      # output specifically suppressed it.
+      # Returns nil for branch/method criteria that have nothing to measure.
+      # Showing "Branch coverage: 0 / 0 (100.00%)" is noise.
       def stats_line(criterion, stat)
-        return if criterion != :line && !stat.total.positive?
+        return if !criterion.equal?(:line) && !stat.total.positive?
 
         percent = SimpleCov.round_coverage(stat.percent)
+        # `Symbol#capitalize` answers a Symbol, which `%<label>s` renders as its
+        # capitalized name, so the label needs no `to_s` step of its own.
         Kernel.format(
           "%<label>s coverage: %<covered>d / %<total>d (%<percent>s)",
-          label: criterion.to_s.capitalize,
+          label: criterion.capitalize,
           covered: stat.covered,
           total: stat.total,
-          percent: SimpleCov::Color.colorize_percent(percent)
+          percent: Color.colorize_percent(percent)
         )
       end
     end

data/lib/simplecov/formatter/baseline_formatter.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../atomic_file"
+
+module SimpleCov
+  module Formatter
+    # Auto-ratchets the per-file coverage baseline as a formatter, for teams
+    # that want floors to tighten on every run instead of by deliberate
+    # `simplecov ratchet` invocations. The semantics are exactly the CLI's, and
+    # the file is rewritten only when a floor actually moved.
+    #
+    # The exit checks still judge the run against the floors as they were when
+    # it started (the baseline is read once per path), and ratcheting never
+    # loosens a floor, so tightening before the checks cannot flip a failing
+    # file to passing.
+    class BaselineFormatter < Base
+      def format(result)
+        emit_status(ratchet(result))
+      end
+
+      private
+
+      def ratchet(result)
+        current = current_floors(result)
+        existing = SimpleCov.baseline
+        return generate(current) unless existing
+
+        outcome = existing.ratchet(current)
+        changed = outcome.tightened.any? || outcome.pruned.any?
+        write(outcome.baseline) if changed
+        note = summary(outcome, changed)
+        regressed = outcome.regressed
+        regressed.empty? ? note : "#{note}#{below_floors(regressed)}"
+      end
+
+      def generate(current)
+        baseline = Baseline.generate(current)
+        write(baseline)
+        files = baseline.entries.size
+        "Coverage baseline generated to #{displayable_output_path} (#{files} #{files.eql?(1) ? "file" : "files"})"
+      end
+
+      def summary(outcome, changed)
+        return "Coverage baseline unchanged at #{displayable_output_path}" unless changed
+
+        "Coverage baseline ratcheted to #{displayable_output_path} " \
+          "(#{outcome.tightened.size} tightened, #{outcome.pruned.size} pruned)"
+      end
+
+      def below_floors(regressed)
+        noun = regressed.size.eql?(1) ? "1 file below its floor" : "#{regressed.size} files below their floors"
+        ", #{noun}: #{regressed.join(", ")}"
+      end
+
+      # `SourceFile#coverage_statistics` answers for disabled criteria too, as
+      # empty statistics, so the criteria are gated on the configuration rather
+      # than on the stats' presence.
+      def current_floors(result)
+        criteria = measured_criteria
+        floors = {} #: Baseline::current_floors
+        result.files.each do |file|
+          floors[file.project_filename] = criteria.to_h { |criterion| [criterion, floor_of(file, criterion)] }
+        end
+        floors
+      end
+
+      def measured_criteria
+        criteria = [] #: Array[Symbol]
+        criteria << :line if SimpleCov.line_coverage?
+        criteria << :branch if SimpleCov.branch_coverage?
+        criteria << :method if SimpleCov.method_coverage?
+        criteria
+      end
+
+      def floor_of(file, criterion)
+        stats = file.coverage_statistics(criterion)
+        {percent: SimpleCov.round_coverage(stats.percent), missed: stats.missed}
+      end
+
+      def write(baseline)
+        AtomicFile.write(output_path, baseline.to_yaml)
+      end
+
+      # The baseline lives where the exit check reads it, not under the coverage
+      # directory: it is checked-in policy, not a report artifact.
+      def output_path
+        File.expand_path(SimpleCov.baseline_file, SimpleCov.root)
+      end
+
+      # `format` hands the ratchet's summary to `emit_status`, which passes it
+      # through to here in the result's place.
+      def output_message(message)
+        message
+      end
+    end
+  end
+end