simplecov 1.1.1 → 1.2.0

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

data/lib/simplecov/formatter/coverage_json_writer.rb

@@ -6,23 +6,17 @@ require_relative "../atomic_file"
 
 module SimpleCov
   module Formatter
-    # Shared writer for the coverage.json artifact, used by JSONFormatter
-    # (as its report) and HTMLFormatter (as the side file feeding
-    # `simplecov serve` and external tools). Centralizing the write keeps
-    # the two copies byte-identical (same pretty printing, same binary
-    # mode, so no CRLF translation on Windows depending on which
-    # formatter wrote last) and gives both formatters the
-    # concurrent-overwrite warning of issue #1171.
+    # 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"
 
-      # The previous report can embed the project's entire source text,
-      # so the overwrite check bounds how much of it is read looking for
-      # the meta object before falling back to a full parse.
       META_SCAN_BYTES = 64 * 1024
       private_constant :META_SCAN_BYTES
 
-    module_function
+      extend self
 
       def write(output_path, hash, result)
         path = File.join(output_path, FILENAME)
@@ -32,20 +26,16 @@ module SimpleCov
       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
-      # (e.g., parallel_tests) wrote it while we were running, and that our
-      # write is about to clobber their data.
+      # 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[:timestamp] > start_time
+        return unless existing.fetch(:timestamp) > start_time
 
-        # Both formatters write coverage.json through this method, so when
-        # they are configured together the file found here was just written
-        # by our own run, not a concurrent one. A matching command_name
-        # means the same merged result, so there's nothing to lose by
-        # overwriting. See issue #1171.
-        return if existing[:command_name] == result.command_name
+        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 " \
@@ -58,11 +48,22 @@ module SimpleCov
         return nil unless File.exist?(path)
 
         meta = parse_meta(path) or return nil
-        timestamp = meta[:timestamp] or return nil
+        timestamp = parse_time(meta[:timestamp]) or return nil
 
-        {timestamp: Time.iso8601(timestamp), command_name: meta[:command_name]}
+        {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
-        # An unparseable timestamp disables the check for this file.
         nil
       end
 
@@ -70,17 +71,14 @@ module SimpleCov
         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 (foreign key order, a brace
-      # inside a meta string) falls back to the full parse.
+      # 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
 
-        # The captured slice is always a JSON object, so a successful parse
-        # is always a Hash.
         JSON.parse(slice, symbolize_names: true)
       rescue JSON::ParserError
         nil
@@ -88,7 +86,7 @@ module SimpleCov
 
       def parse_meta_full(path)
         parsed = JSON.parse(File.read(path), symbolize_names: true)
-        parsed.is_a?(Hash) ? parsed[:meta] : nil
+        parsed[:meta] if parsed.is_a?(Hash)
       rescue JSON::ParserError
         nil
       end