simplecov 0.22.0 → 1.3.0

data/lib/simplecov/filter.rb

@@ -2,15 +2,8 @@
 
 module SimpleCov
   #
-  # Base filter class. Inherit from this to create custom filters,
-  # and overwrite the passes?(source_file) instance method
-  #
-  # # A sample class that rejects all source files.
-  # class StupidFilter < SimpleCov::Filter
-  #   def passes?(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
@@ -20,61 +13,122 @@ module SimpleCov
     end
 
     def matches?(_source_file)
-      raise "The base filter class is not intended for direct use"
+      raise NotImplementedError, "The base filter class is not intended for direct use"
     end
 
-    def passes?(source_file)
-      warn "#{Kernel.caller.first}: [DEPRECATION] #passes? is deprecated. Use #matches? instead."
-      matches?(source_file)
+    # 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. Defaults to false so a custom
+    # filter is never guessed at (#1250).
+    def path_only?
+      false
     end
 
-    def self.build_filter(filter_argument)
-      return filter_argument if filter_argument.is_a?(SimpleCov::Filter)
-
-      class_for_argument(filter_argument).new(filter_argument)
+    # `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 Filter then filter_argument
+      when String then string_filter.new(filter_argument)
+      when Array
+        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)
-      case filter_argument
-      when String
-        SimpleCov::StringFilter
-      when Regexp
-        SimpleCov::RegexFilter
-      when Array
-        SimpleCov::ArrayFilter
-      when Proc
-        SimpleCov::BlockFilter
+      filter_classes_by_argument_type.find { |type, _| filter_argument.is_a?(type) }&.last ||
+        raise(ConfigurationError, "You have provided an unrecognized filter type")
+    end
+
+    def self.filter_classes_by_argument_type
+      @filter_classes_by_argument_type ||= {
+        String => StringFilter,
+        Regexp => RegexFilter,
+        Array => ArrayFilter,
+        Proc => BlockFilter
+      }.freeze
+    end
+    private_class_method :filter_classes_by_argument_type
+  end
+
+  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
+
+    def path_only?
+      true
+    end
+
+    private
+
+    def segment_pattern
+      @segment_pattern ||= compute_segment_pattern
+    end
+
+    def compute_segment_pattern
+      normalized = filter_argument.delete_prefix("/")
+      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 ("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
-        raise ArgumentError, "You have provided an unrecognized filter type"
+        # Require a segment-boundary match so "lib" matches "lib/" but not
+        # "library/".
+        %r{#{boundary}#{escaped}(?=[/.]|\z)}
       end
     end
   end
 
-  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')
+  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)
-      source_file.project_filename.include?(filter_argument)
+      filter_argument.match?(source_file.project_filename)
+    end
+
+    def path_only?
+      true
     end
   end
 
-  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/)
+  class BlockFilter < Filter
     def matches?(source_file)
-      (source_file.project_filename =~ filter_argument)
+      filter_argument.call(source_file)
     end
   end
 
-  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.
+  # 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)
-      filter_argument.call(source_file)
+      File.fnmatch?(filter_argument, source_file.project_filename, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+    end
+
+    def path_only?
+      true
     end
   end
 
-  class ArrayFilter < SimpleCov::Filter
+  class ArrayFilter < Filter
     def initialize(filter_argument)
       filter_objects = filter_argument.map do |arg|
         Filter.build_filter(arg)
@@ -83,8 +137,10 @@ module SimpleCov
       super(filter_objects)
     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 path_only?
+      filter_argument.all?(&:path_only?)
+    end
+
     def matches?(source_files_list)
       filter_argument.any? do |arg|
         arg.matches?(source_files_list)

data/lib/simplecov/formatter/base.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+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. Subclasses override `format`, and may override
+    # `message_prefix`.
+    class Base
+      # `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
+
+      # The one home of the "status lines go to stderr, not through warn"
+      # 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.
+      end
+
+      # 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
+
+      def output_path
+        @output_dir || SimpleCov.coverage_path
+      end
+
+      # 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
+        entry_point ? File.join(directory, entry_point) : directory
+      end
+
+      def relative_or_absolute_output_path
+        absolute = output_path
+        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.
+        output_path
+      end
+
+      # 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
+      end
+
+      # 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) }
+        [header, *body].join("\n")
+      end
+
+      # 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.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.capitalize,
+          covered: stat.covered,
+          total: stat.total,
+          percent: Color.colorize_percent(percent)
+        )
+      end
+    end
+  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

data/lib/simplecov/formatter/coverage_json_writer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "../atomic_file"
+
+module SimpleCov
+  module Formatter
+    # Shared writer for the coverage.json artifact, used by JSONFormatter as its
+    # report and by HTMLFormatter as the side file feeding `simplecov serve` and
+    # external tools. Centralizing the write keeps the two copies byte-identical
+    # and gives both formatters the concurrent-overwrite warning of #1171.
+    module CoverageJSONWriter
+      FILENAME = "coverage.json"
+
+      META_SCAN_BYTES = 64 * 1024
+      private_constant :META_SCAN_BYTES
+
+      extend self
+
+      def write(output_path, hash, result)
+        path = File.join(output_path, FILENAME)
+        warn_if_concurrent_overwrite(path, result)
+        AtomicFile.write(path, JSON.pretty_generate(hash), binary: true)
+        path
+      end
+
+      # Warns when the existing coverage.json has a timestamp newer than this
+      # process's start time, a strong signal that a sibling test process wrote it
+      # while we were running. A matching command_name means the same merged
+      # result, which is what both formatters configured together produce, so
+      # there is nothing to lose by overwriting (#1171).
+      def warn_if_concurrent_overwrite(path, result)
+        start_time = SimpleCov.process_start_time or return
+        existing = existing_meta(path) or return
+        return unless existing.fetch(:timestamp) > start_time
+
+        return if existing.fetch(:command_name).eql?(result.command_name)
+
+        warn "simplecov: #{path} was written at #{existing[:timestamp].iso8601} — after " \
+             "this process started at #{start_time.iso8601}. Overwriting " \
+             "likely loses coverage data from a concurrent test run. For " \
+             "parallel test setups, use SimpleCov::ResultMerger or run a single " \
+             "collation step after all workers finish."
+      end
+
+      def existing_meta(path)
+        return nil unless File.exist?(path)
+
+        meta = parse_meta(path) or return nil
+        timestamp = parse_time(meta[:timestamp]) or return nil
+
+        {timestamp: timestamp, command_name: meta[:command_name]}
+      end
+
+      # Our own writer emits an ISO 8601 string, but coverage.json is whatever
+      # wrote it last: third-party formatters rewrite it in their own shape with
+      # an epoch integer, and `Time.iso8601` raised TypeError on that, taking the
+      # whole report down on the next run. Anything but the two spellings disables
+      # the concurrency check for this file instead of failing the write (#1285).
+      def parse_time(value)
+        case value
+        when String then Time.iso8601(value)
+        when Numeric then Time.at(value)
+        end
+      rescue ArgumentError
+        nil
+      end
+
+      def parse_meta(path)
+        parse_meta_head(path) || parse_meta_full(path)
+      end
+
+      # The meta object is flat and sits at the head of every file this module
+      # writes, so the common case parses just that slice instead of a
+      # multi-megabyte report. A miss falls back to the full parse.
+      def parse_meta_head(path)
+        head = File.read(path, META_SCAN_BYTES).to_s
+        slice = head[/"meta"\s*:\s*(\{.*?\})/m, 1]
+        return nil unless slice
+
+        JSON.parse(slice, symbolize_names: true)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def parse_meta_full(path)
+        parsed = JSON.parse(File.read(path), symbolize_names: true)
+        parsed[:meta] if parsed.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end