simplecov 1.1.0 → 1.2.0

data/lib/simplecov/coverage_violations.rb

@@ -1,48 +1,71 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Computes coverage threshold violations for a given result. Shared by
-  # the exit-code checks and the JSON formatter's `errors` section.
-  #
-  # Each method returns an array of violation hashes. All percents are
-  # rounded via `SimpleCov.round_coverage` so downstream consumers don't
-  # need to round again.
   module CoverageViolations
     class << self
-      # @return [Array<Hash>] {:criterion, :expected, :actual}
       def minimum_overall(result, thresholds)
         thresholds.filter_map do |criterion, expected|
-          actual = percent_for(result, criterion) or next
+          actual = floored_percent_for(result, criterion) or next
           {criterion: criterion, expected: expected, actual: actual} if actual < expected
         end
       end
 
-      # @return [Array<Hash>] {:criterion, :expected, :actual}
-      # Tolerance: `percent_for` floors the actual percent to two decimal
-      # places (matching the existing minimum-coverage behavior), so an
-      # actual of e.g. 95.4287 is treated as 95.42 — meaning a maximum of
-      # 95.42 still passes. See issue #187 for the rationale.
+      # An actual of 95.4287 floors to 95.42, so a maximum of 95.42 passes
+      # (#187).
       def maximum_overall(result, thresholds)
         thresholds.filter_map do |criterion, expected|
-          actual = percent_for(result, criterion) or next
+          actual = floored_percent_for(result, criterion) or next
           {criterion: criterion, expected: expected, actual: actual} if actual > expected
         end
       end
 
-      # @return [Array<Hash>] {:criterion, :expected, :actual, :filename, :project_filename}
-      #
-      # `defaults` is the criterion-keyed Hash applied to every file.
-      # `overrides` is an ordered Hash<pattern, criterion_thresholds> of per-path
-      # overrides; for each file, defaults are merged with every matching override
-      # (later wins per criterion, overrides win over defaults).
-      def minimum_by_file(result, defaults, overrides = {})
+      # A file and criterion with a `baseline` floor is exempt here: the baseline
+      # check holds it to its own floor instead, which is the fall-through the
+      # ratchet workflow rests on (#1268).
+      def minimum_by_file(result, defaults, overrides = {}, baseline: nil)
         result.files.flat_map do |file|
           effective = effective_per_file_thresholds(file, defaults, overrides)
-          effective.filter_map { |criterion, expected| file_minimum_violation(file, criterion, expected) }
+          effective.filter_map do |criterion, expected|
+            next if baseline&.covers?(file.project_filename, criterion)
+
+            file_minimum_violation(file, criterion, expected)
+          end
+        end
+      end
+
+      # A baseline violation needs the file below its floor on both axes: a
+      # percent under the floor's, and (when the floor records one) more misses
+      # than it allows. The missed count is what keeps percent movement from
+      # pure edits out of the answer.
+      def baseline(result, baseline)
+        return [] unless baseline
+
+        result.files.flat_map do |file|
+          entry = baseline.entry_for(file.project_filename)
+          next [] unless entry
+
+          entry.filter_map { |criterion, floor| baseline_violation(file, criterion, floor) }
+        end
+      end
+
+      def maximum_missed(result, caps)
+        caps.filter_map do |criterion, maximum|
+          actual = missed_for(result, criterion) or next
+          {criterion: criterion, maximum: maximum, actual: actual} if actual > maximum
+        end
+      end
+
+      def maximum_missed_by_file(result, defaults, overrides = {}, baseline: nil)
+        result.files.flat_map do |file|
+          effective = effective_per_file_thresholds(file, defaults, overrides)
+          effective.filter_map do |criterion, maximum|
+            next if baseline&.covers?(file.project_filename, criterion)
+
+            file_missed_cap_violation(file, criterion, maximum)
+          end
         end
       end
 
-      # @return [Array<Hash>] {:group_name, :criterion, :expected, :actual}
       def minimum_by_group(result, thresholds)
         thresholds.flat_map do |group_name, minimums|
           group = lookup_group(result, group_name)
@@ -51,50 +74,38 @@ module SimpleCov
         end
       end
 
-      # @return [Array<Hash>] {:criterion, :maximum, :actual} where `actual`
-      #   is the observed drop (in percentage points) vs. the last run.
-      def maximum_drop(result, thresholds, last_run: SimpleCov::LastRun.read)
-        return [] unless last_run
+      def maximum_drop(result, thresholds, last_run: nil, mode: SimpleCov.drop_baseline)
+        baseline = drop_baseline_percents(mode, last_run)
+        return [] unless baseline
 
         thresholds.filter_map do |criterion, maximum|
-          actual = compute_drop(criterion, result, last_run)
+          actual = compute_drop(criterion, result, baseline)
           {criterion: criterion, maximum: maximum, actual: actual} if actual && actual > maximum
         end
       end
 
-    private
+      private
 
-      # Look up a criterion's percent on any coverage_statistics-bearing
-      # object (Result, SourceFile, FileList). Returns nil — and the
-      # caller silently skips — when the criterion was configured but not
-      # actually measured by the runtime (e.g. `minimum_coverage branch:
-      # 100` under the "strict" profile on JRuby, where the Coverage
-      # module doesn't emit branch data). The config-time
-      # `raise_if_criterion_disabled` check still catches the genuine
-      # "forgot to enable the criterion" mistake before we ever get here.
-      def percent_for(stats_source, criterion)
+      # Answers nil, and the caller silently skips, when the criterion was
+      # configured but not measured by the runtime (`branch: 100` under the
+      # "strict" profile on JRuby, say). The config-time
+      # `raise_if_criterion_disabled` check catches the genuine mistake earlier.
+      def floored_percent_for(stats_source, criterion)
         stats = stats_source.coverage_statistics[SimpleCov.coverage_statistics_key(criterion)]
         round(stats.percent) if stats
       end
 
-      # Walk the overrides in declaration order, merging each one that matches
-      # the file's project path into the running effective threshold (so the
-      # most-specific or latest-declared override wins per criterion). Returns
-      # the defaults Hash unchanged when nothing matches.
       def effective_per_file_thresholds(file, defaults, overrides)
-        return defaults if overrides.empty?
-
         path = file.project_filename
         overrides.reduce(defaults) do |acc, (pattern, criterion_thresholds)|
           path_matches?(path, pattern) ? acc.merge(criterion_thresholds) : acc
         end
       end
 
-      # Per-path matching for `minimum_coverage_by_file` overrides. Strings
-      # ending in `/` are treated as directory prefixes; otherwise they must
-      # match `project_filename` exactly. Regexps are tested via `match?`.
-      # The configuration setter rejects anything other than String/Regexp,
-      # so no dead `else` branch is needed here.
+      # `==` and `eql?` are indistinguishable for the String operands, so that
+      # mutation is equivalent. The override examples pin every arm instead.
+      # mutant:disable
+      # mutant:disable
       def path_matches?(project_filename, pattern)
         return project_filename.match?(pattern) if pattern.is_a?(Regexp)
         return project_filename.start_with?(pattern) if pattern.end_with?("/")
@@ -102,8 +113,33 @@ module SimpleCov
         project_filename == pattern
       end
 
+      def missed_for(stats_source, criterion)
+        stats = stats_source.coverage_statistics[SimpleCov.coverage_statistics_key(criterion)]
+        stats&.missed
+      end
+
+      def file_missed_cap_violation(file, criterion, maximum)
+        actual = missed_for(file, criterion) or return
+        return unless actual > maximum
+
+        {criterion: criterion, maximum: maximum, actual: actual,
+         filename: file.filename, project_filename: file.project_filename}
+      end
+
+      def baseline_violation(file, criterion, floor)
+        stats = file.coverage_statistics[SimpleCov.coverage_statistics_key(criterion)]
+        return unless stats
+
+        actual = round(stats.percent)
+        return unless actual < floor.percent
+        return if floor.missed && stats.missed <= floor.missed
+
+        {criterion: criterion, expected: floor.percent, allowed_missed: floor.missed, actual: actual,
+         actual_missed: stats.missed, filename: file.filename, project_filename: file.project_filename}
+      end
+
       def file_minimum_violation(file, criterion, expected)
-        actual = percent_for(file, criterion) or return
+        actual = floored_percent_for(file, criterion) or return
         return unless actual < expected
 
         {
@@ -117,37 +153,94 @@ module SimpleCov
 
       def group_minimum_violations(group_name, group, minimums)
         minimums.filter_map do |criterion, expected|
-          actual = percent_for(group, criterion) or next
+          actual = floored_percent_for(group, criterion) or next
           {group_name: group_name, criterion: criterion, expected: expected, actual: actual} if actual < expected
         end
       end
 
-      # The misconfiguration notice is enforcement output, not a Ruby
-      # warning: like every other enforcement message it must survive
-      # `-W0` and `Warning.warn` hooks (see ExitCodes.print_error) and
-      # honor the `print_errors` opt-out.
+      # The misconfiguration notice is enforcement output, not a Ruby warning: it
+      # must survive `-W0` and `Warning.warn` hooks, and honor `print_errors`.
       def lookup_group(result, group_name)
         group = result.groups[group_name]
         if group.nil? && SimpleCov.print_errors
           ExitCodes.print_error "minimum_coverage_by_group: no group named '#{group_name}' exists. " \
-                                "Available groups: #{result.groups.keys.join(', ')}"
+                                "Available groups: #{result.groups.keys.join(", ")}"
         end
         group
       end
 
-      def compute_drop(criterion, result, last_run)
-        stats_key = SimpleCov.coverage_statistics_key(criterion)
-        last_coverage_percent = last_run.dig(:result, stats_key)
-        if last_coverage_percent.nil? && stats_key == :line
-          last_coverage_percent = last_run.dig(:result, :covered_percent)
+      def drop_baseline_percents(mode, last_run)
+        case mode
+        when :median then median_baseline
+        when :branch then branch_baseline
+        else last_run_baseline(last_run || LastRun.read)
+        end
+      end
+
+      # A hand-edited .last_run.json can carry any value type, and `LastRun.read`
+      # only vouches for the top level being a Hash. `:covered_percent` is the
+      # pre-criteria file format's spelling of the line percent.
+      def last_run_baseline(last_run)
+        return nil unless last_run.is_a?(Hash)
+
+        previous = (_ = last_run)[:result]
+        return nil unless previous.is_a?(Hash)
+
+        previous = _ = previous
+        {line: previous[:line] || previous[:covered_percent],
+         branch: previous[:branch], method: previous[:method]}
+      end
+
+      def median_baseline
+        totals = history_totals
+        baseline = {} #: Hash[Symbol, untyped]
+        %i[line branch method].each do |criterion|
+          values = totals.map { |entry| entry[criterion.to_s] }.grep(Numeric)
+          baseline[criterion] = median(values) unless values.empty?
+        end
+        baseline
+      end
+
+      def history_totals
+        History.read.filter_map do |entry|
+          entry.fetch("totals") if entry.is_a?(Hash) && entry["totals"].is_a?(Hash)
         end
-        # A hand-edited .last_run.json can carry any value type, and
-        # LastRun.read only vouches for the top level being a Hash.
+      end
+
+      def median(values)
+        sorted = values.sort
+        mid = sorted.length / 2
+        sorted.length.odd? ? sorted.fetch(mid) : (sorted.fetch(mid - 1) + sorted.fetch(mid)).fdiv(2)
+      end
+
+      def branch_baseline
+        branch, = History.git_info
+        return nil unless branch
+
+        entry = History.read.reverse_each.find { |candidate| branch_entry?(candidate, branch) }
+        return nil unless entry
+
+        totals = {} #: Hash[Symbol, untyped]
+        entry.fetch("totals").each { |key, value| totals[key.to_sym] = value }
+        totals
+      end
+
+      # `==` and `eql?` are indistinguishable for the String operands, so that
+      # mutation is equivalent. The branch-baseline examples pin every clause.
+      # mutant:disable
+      # mutant:disable
+      def branch_entry?(candidate, branch)
+        candidate.is_a?(Hash) && candidate["branch"] == branch && candidate["totals"].is_a?(Hash)
+      end
+
+      def compute_drop(criterion, result, baseline)
+        stats_key = SimpleCov.coverage_statistics_key(criterion)
+        last_coverage_percent = baseline[stats_key]
         # Treat a non-numeric percent like a missing one instead of
         # raising out of the at_exit hook.
         return unless last_coverage_percent.is_a?(Numeric)
 
-        current = percent_for(result, criterion) or return
+        current = floored_percent_for(result, criterion) or return
         (last_coverage_percent - current).floor(10)
       end
 

data/lib/simplecov/current_run.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  # The state one measured run accumulates in one process: the pid and start
+  # time that identify it, the result it computes, the flags the merge
+  # coordination reads, and the serial the parent hands each forked
+  # subprocess. A new run is a new object, which is what lets anything needing
+  # a clean slate begin one instead of unsetting state by hand.
+  class CurrentRun
+    attr_accessor :pid, :process_start_time, :result
+    attr_writer :collating_result
+
+    # The result, the coordination flags and the identity belong to the run that
+    # ends; the fork genealogy belongs to the process and carries over. A child
+    # that restarts tracking must not forget it was forked, or it would produce
+    # the final report itself, and a parent must not recount from zero, or its
+    # next children's names would collide with its first ones (#1171).
+    def successor
+      following = self.class.new
+      following.subprocess_serial = @subprocess_serial
+      following.mark_forked_subprocess! if forked_subprocess?
+      following
+    end
+
+    # Answers exactly false while no result was ever stored, which is how "never
+    # computed" stays distinct from "cleared to nil".
+    def result?
+      instance_variable_defined?(:@result) && (_ = @result)
+    end
+
+    def collating_result?
+      !!@collating_result
+    end
+
+    # Reading a mark that was never set answers nil, which is the answer wanted.
+    def forked_subprocess?
+      !!@forked_subprocess
+    end
+
+    def mark_forked_subprocess!
+      @forked_subprocess = true
+    end
+
+    # A monotonically increasing serial the parent assigns to each forked
+    # subprocess. The default `at_fork` builds the worker's command_name from
+    # this rather than the OS pid: the serial sequence is the same from one run
+    # to the next, so a re-run overwrites the previous run's resultset entries
+    # instead of writing uniquely-named ones that pile up (#1171).
+    def subprocess_serial
+      @subprocess_serial ||= 0
+    end
+
+    def next_subprocess_serial!
+      @subprocess_serial = subprocess_serial + 1
+    end
+
+    protected
+
+    attr_writer :subprocess_serial
+  end
+end

data/lib/simplecov/defaults.rb

@@ -4,46 +4,27 @@ require "English"
 require "pathname"
 require_relative "formatter/html_formatter"
 
-# Default configuration. Profiles autoload on first reference via
-# `SimpleCov.profiles.fetch_proc`; the unused ones (e.g. "rails")
-# never get required unless a user opts in.
 SimpleCov.configure do
   formatter SimpleCov::Formatter::HTMLFormatter
 
   load_profile "bundler_filter"
   load_profile "hidden_filter"
-  # Exclude files outside of SimpleCov.root. Mirrors the early prune done
-  # by SimpleCov::UselessResultsRemover so the user-facing filter chain
-  # honors the same boundary; both share the regex.
   load_profile "root_filter"
-  # Exclude test framework directories (`test/`, `spec/`, `features/`,
-  # `autotest/`). The test suite runs 100% of the test files themselves,
-  # which inflates totals and obscures the application coverage that
-  # actually matters. Drop with `remove_filter %r{\A(test|features|spec|autotest)/}`
-  # if you want test files counted (e.g. to surface dead helpers).
   load_profile "test_frameworks"
 end
 
-# Gotta stash this a-s-a-p, see the CommandGuesser class and i.e. #110 for further info.
-# The program name is kept separately as well: the join below is lossy for a
-# path containing a space, and the guesser reads the executable from it.
-SimpleCov::CommandGuesser.original_run_command = "#{$PROGRAM_NAME} #{ARGV.join(' ')}"
+# Stashed as early as possible, before rake or test/unit tamper with ARGV
+# (#110). The program name is kept separately as well: the join is lossy for
+# a path containing a space, and the guesser reads the executable from it.
+SimpleCov::CommandGuesser.original_run_command = "#{$PROGRAM_NAME} #{ARGV.join(" ")}"
 SimpleCov::CommandGuesser.original_program_name = $PROGRAM_NAME
 
-# Autoload config from ~/.simplecov if present
 require_relative "load_global_config"
 
-# Autoload config from .simplecov if present
-# Recurse upwards until we find .simplecov or reach the root directory
-
 config_path = Pathname.new(SimpleCov.root)
 loop do
   filename = config_path.join(".simplecov")
   if filename.exist?
-    # `.simplecov` is a configuration file; SimpleCov.start calls inside
-    # it draw a deprecation warning, and tracking still begins for
-    # backward compatibility. See `SimpleCov.with_dot_simplecov_autoload`
-    # and issue #581.
     SimpleCov.with_dot_simplecov_autoload do
       load filename.to_s
     rescue LoadError, StandardError => e

data/lib/simplecov/deprecation.rb

@@ -1,45 +1,63 @@
 # frozen_string_literal: true
 
+require_relative "configuration_error"
+
 module SimpleCov
-  # Emits legacy-API deprecation warnings, deduplicated by the source
-  # location that triggered them. A deprecated method called in a loop —
-  # or a config block re-evaluated once per parallel worker / spec file —
-  # otherwise repeats the same notice until stderr is unreadable. Keying
-  # on the caller location collapses those repeats to a single line while
-  # still warning separately about each distinct call site the user needs
-  # to fix. See issue #1204.
+  # Emits legacy-API deprecation warnings, deduplicated by the source location
+  # that triggered them. A deprecated method called in a loop, or a config
+  # block re-evaluated once per parallel worker, otherwise repeats the same
+  # notice until stderr is unreadable. Keying on the caller location collapses
+  # those repeats while still warning separately about each distinct call site
+  # the user needs to fix (#1204).
   module Deprecation
-  module_function
-
-    # Warn about a deprecated API. `message` is the notice without the
-    # `[DEPRECATION]` tag or location prefix (both are added here).
-    #
-    # `location` defaults to the caller of the deprecated method that
-    # called us — every shipped call site is a one-level alias such as
-    # `track_files`, so the frame two up is the user code. Pass `location:`
-    # explicitly when the relevant site isn't that frame (e.g. a source
-    # file and line discovered while parsing).
-    # `Array(...)` coerces a missing backtrace (nil) to `[]` so `.first`
-    # yields nil rather than raising — and, unlike `&.`, adds no branch for
-    # the unreachable no-caller case to the project's 100% coverage target.
-    def warn(message, location: Array(Kernel.caller(2..2)).first)
-      # Key on location when we have one (collapses a deprecated call in a
-      # loop to a single warning); fall back to the message so a missing
-      # backtrace never silently swallows every notice.
+    extend self
+
+    MODES = %i[warn raise].freeze
+
+    # The mode lives here rather than on the configuration singleton so that
+    # `warn` depends on nothing but itself. `SimpleCov.deprecations` is the
+    # front door that writes it, and the CLI, which loads none of the
+    # configuration surface, can still warn.
+    def mode
+      @mode ||= :warn
+    end
+
+    def mode=(mode)
+      raise ConfigurationError, "deprecations takes :warn or :raise, got #{mode.inspect}" unless MODES.include?(mode)
+
+      @mode = mode
+    end
+
+    # `message` is the notice without the `[DEPRECATION]` tag or location
+    # prefix, both of which are added here. `deprecations :raise` turns every
+    # deprecated API into an error before the dedup: an error is not a notice to
+    # collapse, and a CI guard must fail on the second offender as surely as on
+    # the first. A missing backtrace falls back to keying on the message, so it
+    # never silently swallows every notice.
+    def warn(message, location: caller_location)
+      raise ConfigurationError, message if mode.equal?(:raise)
+
       return unless emitted.add?(location || message)
 
       Kernel.warn "#{"#{location}: " if location}[DEPRECATION] #{message}"
     end
 
-    # Already-emitted dedup keys for this process. Parallel workers are
-    # separate processes with their own set, so each warns at most once.
+    # Every shipped call site is a one-level alias such as `track_files`, so the
+    # frame three up from here is the user's own code. `Array(...)` coerces a
+    # missing backtrace to `[]` so `.first` yields nil rather than raising.
+    def caller_location
+      Array(Kernel.caller(3..3)).first
+    end
+
+    # Parallel workers are separate processes with their own set, so each warns
+    # at most once.
     def emitted
       @emitted ||= Set.new
     end
 
-    # @api private — reset emitted state between tests.
     def reset!
       @emitted = Set.new
+      @mode = :warn
     end
   end
 end