simplecov 1.1.0 → 1.2.0

data/lib/simplecov/directive.rb

@@ -3,42 +3,24 @@
 require "ripper"
 
 module SimpleCov
-  # Parses `# simplecov:disable` / `# simplecov:enable` directive comments.
+  # Parses `# simplecov:disable` / `# simplecov:enable` directive comments, in
+  # both the block form (the directive is the entire comment on its own line,
+  # opening a region that runs until the matching enable) and the inline form
+  # (the directive trails real code, affecting that line alone).
   #
-  # Two forms are supported:
-  #
-  # Block form (the directive is the entire comment on its own line) opens a
-  # region that runs until the matching `# simplecov:enable`:
-  #
-  #   # simplecov:disable line
-  #   ...
-  #   # simplecov:enable line
-  #
-  # Inline form (the directive trails real code on the same line) only affects
-  # that single line and does not need to be re-enabled:
-  #
-  #   raise "absurd" # simplecov:disable
-  #
-  # Categories are `:line`, `:branch`, and `:method`. They may be combined
-  # with commas. Omitting categories targets all three.
-  #
-  # Any text after the directive (and the optional category list) is treated
-  # as a free-form reason and discarded:
-  #
-  #   # simplecov:disable line not worth testing this glue
-  #
-  # As a consequence, an unrecognised category name silently falls into the
-  # reason bucket. `# simplecov:disable cyclomatic` is parsed as the bare
-  # form (disable everything) with reason "cyclomatic" — a deliberate
-  # over-disable so the typo is visible in the report rather than silently
-  # disabling nothing.
+  # Categories are `:line`, `:branch`, and `:method`, combinable with commas.
+  # Omitting categories targets all three. Any text after the directive is a
+  # free-form reason and is discarded, so an unrecognised category name
+  # silently falls into the reason bucket and disables everything: a
+  # deliberate over-disable, so the typo is visible in the report rather than
+  # silently disabling nothing.
   #
   # Comment extraction goes through `Ripper.lex` so directive markers inside
   # string literals or heredocs are correctly ignored.
   class Directive
     CATEGORIES = %i[line branch method].freeze
 
-    CATEGORY_PATTERN = "(?:#{CATEGORIES.join('|')})".freeze
+    CATEGORY_PATTERN = "(?:#{CATEGORIES.join("|")})".freeze
     CATEGORIES_PATTERN = "(?:#{CATEGORY_PATTERN}(?:\\s*,\\s*#{CATEGORY_PATTERN})*)".freeze
     PATTERN = /
       \#\s*simplecov\s*:\s*
@@ -50,11 +32,9 @@ module SimpleCov
 
     attr_reader :line_number, :mode, :categories
 
-    # Walk an array of source lines and return the disabled line ranges per
-    # category as `{ line: [Range, ...], branch: [...], method: [...] }`.
-    # An unclosed `disable` block extends to the end of the file.
-    def self.disabled_ranges(src_lines)
-      lines = src_lines.to_a
+    # The disabled line ranges per category. An unclosed `disable` block
+    # extends to the end of the file.
+    def self.disabled_ranges(lines)
       ranges = CATEGORIES.to_h do |category|
         empty = [] # : Array[Range[Integer]]
         [category, empty]
@@ -62,14 +42,14 @@ module SimpleCov
       open_starts = {} # : Hash[Symbol, Integer]
 
       directives_in(lines).each { |directive| directive.apply(ranges, open_starts) }
-      open_starts.each { |category, start| ranges[category] << (start..lines.size) }
+      open_starts.each { |category, start| ranges.fetch(category) << (start..lines.size) }
 
       ranges
     end
 
-    # Extract every directive in the file, in source order. Comments inside
-    # string literals or heredocs are skipped because Ripper.lex doesn't tag
-    # them as :on_comment tokens.
+    # Every directive in the file, in source order. Comments inside string
+    # literals or heredocs are skipped because Ripper.lex doesn't tag them as
+    # :on_comment tokens.
     def self.directives_in(lines)
       return [] unless source_might_contain_directive?(lines)
 
@@ -78,13 +58,13 @@ module SimpleCov
       end
     end
 
-    # Cheap pre-check so we don't tokenize files that obviously can't contain
-    # a directive.
+    # Cheap pre-check, so files that obviously can't contain a directive are
+    # never tokenized.
     def self.source_might_contain_directive?(lines)
       lines.any? do |line|
         line.include?("simplecov")
       rescue ArgumentError, EncodingError
-        false # simplecov:disable — defensive guard for invalid byte sequences in source
+        false
       end
     end
 
@@ -94,72 +74,76 @@ module SimpleCov
 
       new(
         line_number: line_number,
-        # `to_s` is a no-op: the pattern requires the `mode` group, so it
-        # is present whenever `match` is; it also satisfies the type checker.
-        mode: match[:mode].to_s.to_sym,
+        # The pattern admits exactly two modes, so asking whether this one is
+        # `disable` names the other by elimination. Comparing the captured text
+        # also keeps the nilable capture out of `to_sym`.
+        mode: match[:mode].eql?("disable") ? :disable : :enable,
         categories: parse_categories(match[:categories]),
         inline: inline?(lines, line_number, column + match.begin(0))
       )
     rescue ArgumentError, EncodingError
-      # E.g., comment text contains an invalid byte sequence in UTF-8.
+      # The comment text contains an invalid byte sequence, say.
       nil
     end
 
+    # The bare form targets every category, and answers the frozen constant
+    # itself: a directive's categories are only ever iterated.
     def self.parse_categories(text)
-      return CATEGORIES.dup if text.nil?
+      return CATEGORIES if text.nil?
 
       text.split(/\s*,\s*/).map(&:to_sym)
     end
 
-    # Whether the directive sits after non-whitespace content on its line.
     # `column` is the byte column of the directive's `#` in the source line,
-    # adjusted for any prefix that may precede it within the comment token
-    # (e.g., `# prefix # simplecov:disable line`).
+    # adjusted for any prefix that may precede it within the comment token.
     def self.inline?(lines, line_number, column)
-      line = lines[line_number - 1].to_s
-      !line.byteslice(0, column).to_s.strip.empty?
+      line = lines.at(line_number - 1).to_s
+      # Indentation is all a non-inline directive may have before it, so
+      # stripping the prefix from the left decides the question. Doing it from
+      # the right instead would raise on a line whose trailing bytes are
+      # invalid, which is a property of the code after the directive.
+      !line.byteslice(0, column).to_s.lstrip.empty?
     rescue ArgumentError, EncodingError
-      false # simplecov:disable — defensive guard for invalid byte sequences
+      false
     end
 
     def self.comments_in(lines)
       source = lines.map { |line| line.end_with?("\n") ? line : "#{line}\n" }.join
       Ripper.lex(source).filter_map do |(line_number, column), type, text|
-        [line_number, column, text] if type == :on_comment
+        [line_number, column, text] if type.equal?(:on_comment)
       end
     rescue ArgumentError, EncodingError
-      [] # simplecov:disable — Ripper.lex can raise on invalid byte sequences
+      []
     end
 
     private_class_method :directives_in, :source_might_contain_directive?,
-                         :parse_comment, :parse_categories, :inline?, :comments_in
+      :parse_comment, :parse_categories, :inline?, :comments_in
 
     def initialize(line_number:, mode:, categories:, inline:)
       @line_number = line_number
-      @mode        = mode
-      @categories  = categories
-      @inline      = inline
+      @mode = mode
+      @categories = categories
+      @inline = inline
     end
 
     def disabled?
-      mode == :disable
+      mode.equal?(:disable)
     end
 
     def inline?
       @inline
     end
 
-    # Apply this directive's effect to the in-flight per-category state.
     # Inline directives mark just their line; block disables open a region;
     # block enables close one. Re-opening an already-open block is a no-op.
     def apply(ranges, open_starts)
       categories.each do |category|
         if inline?
-          ranges[category] << (line_number..line_number) if disabled?
+          ranges.fetch(category) << (line_number..line_number) if disabled?
         elsif disabled?
           open_starts[category] ||= line_number
         elsif (start = open_starts.delete(category))
-          ranges[category] << (start..line_number)
+          ranges.fetch(category) << (start..line_number)
         end
       end
     end

data/lib/simplecov/exit_codes/baseline_check.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ExitCodes
+    # Fails when a file listed in the checked-in baseline drops below its own
+    # floor on both axes: a lower percent than the floor records and more misses
+    # than it allows. The second condition is the dampener that keeps an edit
+    # with no coverage change from failing the run; a percent-only floor is
+    # decided by the percent alone.
+    class BaselineCheck < Check
+      def initialize(result, baseline)
+        super(result, nil)
+        @baseline = baseline
+      end
+
+      def exit_code
+        MINIMUM_COVERAGE
+      end
+
+      private
+
+      def compute_violations
+        CoverageViolations.baseline(result, @baseline)
+      end
+
+      def violation_lines(violation)
+        message = format(
+          "%<criterion>s coverage (%<actual>s) dropped below its baseline floor (%<expected>s%%) in %<filename>s",
+          criterion: violation.fetch(:criterion).capitalize,
+          actual: Color.colorize_percent(violation.fetch(:actual)),
+          expected: violation.fetch(:expected),
+          filename: violation.fetch(:project_filename)
+        )
+        ["#{message}#{missed_clause(violation)}."]
+      end
+
+      def missed_clause(violation)
+        allowed = violation.fetch(:allowed_missed)
+        return unless allowed
+
+        units = UNITS.fetch(SimpleCov.coverage_statistics_key(violation.fetch(:criterion)))
+        " (#{violation.fetch(:actual_missed)} uncovered #{units}, #{allowed} allowed)"
+      end
+    end
+  end
+end

data/lib/simplecov/exit_codes/check.rb

@@ -2,11 +2,9 @@
 
 module SimpleCov
   module ExitCodes
-    # Shared skeleton for the threshold checks: stash the result and the
-    # threshold configuration, fail when any violation exists, and
-    # report one message per violation. Subclasses supply `exit_code`,
-    # `compute_violations` (memoized here — `failing?` and `report` both
-    # consult it), and `report_violation`.
+    # Shared skeleton for the threshold checks. Subclasses supply `exit_code`,
+    # `compute_violations` (memoized here, since `failing?` and `report_lines`
+    # both consult it), and `violation_lines`.
     class Check
       def initialize(result, thresholds)
         @result = result
@@ -17,17 +15,25 @@ module SimpleCov
         violations.any?
       end
 
+      def violations
+        @violations ||= compute_violations
+      end
+
+      # Concatenated rather than flat-mapped: a check answering a bare string
+      # instead of its list of lines is an error this raises, not a spelling the
+      # flattening would forgive.
+      def report_lines
+        lines = [] #: Array[String]
+        violations.each_with_object(lines) { |violation, into| into.concat(violation_lines(violation)) }
+      end
+
       def report
-        violations.each { |violation| report_violation(violation) }
+        report_lines.each { |line| ExitCodes.print_error(line) }
       end
 
-    private
+      private
 
       attr_reader :result, :thresholds
-
-      def violations
-        @violations ||= compute_violations
-      end
     end
   end
 end

data/lib/simplecov/exit_codes/exit_code_handling.rb

@@ -2,10 +2,8 @@
 
 module SimpleCov
   module ExitCodes
-    # Runs every coverage check against the result and returns the exit
-    # code from the first failing one (or SUCCESS if all pass).
     module ExitCodeHandling
-    module_function
+      extend self
 
       def call(result, coverage_limits:)
         checks = coverage_checks(result, coverage_limits)
@@ -15,21 +13,36 @@ module SimpleCov
           failing_check.report if SimpleCov.print_errors
           failing_check.exit_code
         else
-          SimpleCov::ExitCodes::SUCCESS
+          SUCCESS
         end
       end
 
       def coverage_checks(result, coverage_limits)
         [
           MinimumOverallCoverageCheck.new(result, coverage_limits.minimum_coverage),
-          MinimumCoverageByFileCheck.new(
-            result, coverage_limits.minimum_coverage_by_file, coverage_limits.minimum_coverage_by_file_overrides
-          ),
+          minimum_by_file_check(result, coverage_limits),
+          BaselineCheck.new(result, coverage_limits.baseline),
           MinimumCoverageByGroupCheck.new(result, coverage_limits.minimum_coverage_by_group),
           MaximumOverallCoverageCheck.new(result, coverage_limits.maximum_coverage),
-          MaximumCoverageDropCheck.new(result, coverage_limits.maximum_coverage_drop)
+          MaximumCoverageDropCheck.new(result, coverage_limits.maximum_coverage_drop),
+          MaximumMissedCheck.new(result, coverage_limits.maximum_missed),
+          maximum_missed_per_file_check(result, coverage_limits)
         ]
       end
+
+      def minimum_by_file_check(result, coverage_limits)
+        MinimumCoverageByFileCheck.new(
+          result, coverage_limits.minimum_coverage_by_file, coverage_limits.minimum_coverage_by_file_overrides,
+          baseline: coverage_limits.baseline
+        )
+      end
+
+      def maximum_missed_per_file_check(result, coverage_limits)
+        MaximumMissedPerFileCheck.new(
+          result, coverage_limits.maximum_missed_per_file, coverage_limits.maximum_missed_per_file_overrides,
+          baseline: coverage_limits.baseline
+        )
+      end
     end
   end
 end

data/lib/simplecov/exit_codes/maximum_coverage_drop_check.rb

@@ -2,24 +2,21 @@
 
 module SimpleCov
   module ExitCodes
-    # Fails when any coverage criterion has dropped by more than the
-    # configured maximum since the last recorded run.
     class MaximumCoverageDropCheck < Check
       def exit_code
-        SimpleCov::ExitCodes::MAXIMUM_COVERAGE_DROP
+        MAXIMUM_COVERAGE_DROP
       end
 
-    private
+      private
 
       def compute_violations
-        SimpleCov::CoverageViolations.maximum_drop(result, thresholds)
+        CoverageViolations.maximum_drop(result, thresholds)
       end
 
-      # The "drop percent" is a delta, not a coverage level — it has no
-      # natural green/yellow/red mapping, so the whole line goes red to
-      # keep the failure visible at a glance.
-      def report_violation(violation)
-        ExitCodes.print_error SimpleCov::Color.colorize(message_for(violation), :red)
+      # The drop percent is a delta, not a coverage level, so it has no natural
+      # green/yellow/red mapping and the whole line goes red.
+      def violation_lines(violation)
+        [Color.colorize(message_for(violation), :red)]
       end
 
       def message_for(violation)

data/lib/simplecov/exit_codes/maximum_missed_check.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ExitCodes
+    class MaximumMissedCheck < Check
+      def exit_code
+        MINIMUM_COVERAGE
+      end
+
+      private
+
+      def compute_violations
+        CoverageViolations.maximum_missed(result, thresholds)
+      end
+
+      def violation_lines(violation)
+        [format(
+          "Missed %<units>s (%<actual>d) exceed the configured maximum_missed (%<maximum>d).",
+          units: UNITS.fetch(SimpleCov.coverage_statistics_key(violation.fetch(:criterion))),
+          actual: violation.fetch(:actual),
+          maximum: violation.fetch(:maximum)
+        )]
+      end
+    end
+  end
+end

data/lib/simplecov/exit_codes/maximum_missed_per_file_check.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ExitCodes
+    class MaximumMissedPerFileCheck < Check
+      def initialize(result, maximum_missed_per_file, overrides = {}, baseline: nil)
+        super(result, maximum_missed_per_file)
+        @overrides = overrides
+        @baseline = baseline
+      end
+
+      def exit_code
+        MINIMUM_COVERAGE
+      end
+
+      private
+
+      def compute_violations
+        CoverageViolations.maximum_missed_by_file(result, thresholds, @overrides, baseline: @baseline)
+      end
+
+      def violation_lines(violation)
+        [format(
+          "Missed %<units>s (%<actual>d) exceed the configured maximum_missed_per_file (%<maximum>d) " \
+          "in %<filename>s.",
+          units: UNITS.fetch(SimpleCov.coverage_statistics_key(violation.fetch(:criterion))),
+          actual: violation.fetch(:actual),
+          maximum: violation.fetch(:maximum),
+          filename: violation.fetch(:project_filename)
+        )]
+      end
+    end
+  end
+end

data/lib/simplecov/exit_codes/maximum_overall_coverage_check.rb

@@ -2,30 +2,25 @@
 
 module SimpleCov
   module ExitCodes
-    # Fails when the overall (project-wide) coverage for any criterion is
-    # above the configured maximum. Pair with
-    # `SimpleCov::ExitCodes::MinimumOverallCoverageCheck` (or use
-    # `SimpleCov.expected_coverage`) to pin coverage to an exact value
-    # and surface unexpected increases instead of silently absorbing them.
     class MaximumOverallCoverageCheck < Check
       def exit_code
-        SimpleCov::ExitCodes::MAXIMUM_COVERAGE
+        MAXIMUM_COVERAGE
       end
 
-    private
+      private
 
       def compute_violations
-        SimpleCov::CoverageViolations.maximum_overall(result, thresholds)
+        CoverageViolations.maximum_overall(result, thresholds)
       end
 
-      def report_violation(violation)
-        ExitCodes.print_error format(
+      def violation_lines(violation)
+        [format(
           "%<criterion>s coverage (%<actual>s) is above the expected maximum coverage (%<expected>.2f%%). " \
           "Time to bump the threshold!",
           criterion: violation.fetch(:criterion).capitalize,
-          actual: SimpleCov::Color.colorize_percent(violation.fetch(:actual)),
+          actual: Color.colorize_percent(violation.fetch(:actual)),
           expected: violation.fetch(:expected)
-        )
+        )]
       end
     end
   end

data/lib/simplecov/exit_codes/minimum_coverage_by_file_check.rb

@@ -2,33 +2,34 @@
 
 module SimpleCov
   module ExitCodes
-    # Fails when any individual file falls below the configured minimum
-    # coverage for any criterion.
     class MinimumCoverageByFileCheck < Check
-      def initialize(result, minimum_coverage_by_file, overrides = {})
+      # `baseline:` exempts the file-and-criterion pairs it covers: those answer to
+      # their own floor via `BaselineCheck` instead.
+      def initialize(result, minimum_coverage_by_file, overrides = {}, baseline: nil)
         super(result, minimum_coverage_by_file)
         @overrides = overrides
+        @baseline = baseline
       end
 
       def exit_code
-        SimpleCov::ExitCodes::MINIMUM_COVERAGE
+        MINIMUM_COVERAGE
       end
 
-    private
+      private
 
       def compute_violations
-        SimpleCov::CoverageViolations.minimum_by_file(result, thresholds, @overrides)
+        CoverageViolations.minimum_by_file(result, thresholds, @overrides, baseline: @baseline)
       end
 
-      def report_violation(violation)
-        ExitCodes.print_error format(
+      def violation_lines(violation)
+        [format(
           "%<criterion>s coverage by file (%<actual>s) is below the expected minimum coverage " \
           "(%<expected>.2f%%) in %<filename>s.",
           criterion: violation.fetch(:criterion).capitalize,
-          actual: SimpleCov::Color.colorize_percent(violation.fetch(:actual)),
+          actual: Color.colorize_percent(violation.fetch(:actual)),
           expected: violation.fetch(:expected),
           filename: violation.fetch(:project_filename)
-        )
+        )]
       end
     end
   end

data/lib/simplecov/exit_codes/minimum_coverage_by_group_check.rb

@@ -2,28 +2,26 @@
 
 module SimpleCov
   module ExitCodes
-    # Fails when any configured group falls below its minimum coverage
-    # threshold for any criterion.
     class MinimumCoverageByGroupCheck < Check
       def exit_code
-        SimpleCov::ExitCodes::MINIMUM_COVERAGE
+        MINIMUM_COVERAGE
       end
 
-    private
+      private
 
       def compute_violations
-        SimpleCov::CoverageViolations.minimum_by_group(result, thresholds)
+        CoverageViolations.minimum_by_group(result, thresholds)
       end
 
-      def report_violation(violation)
-        ExitCodes.print_error format(
+      def violation_lines(violation)
+        [format(
           "%<criterion>s coverage by group (%<actual>s) is below the expected minimum coverage " \
           "(%<expected>.2f%%) in %<group_name>s.",
           criterion: violation.fetch(:criterion).capitalize,
-          actual: SimpleCov::Color.colorize_percent(violation.fetch(:actual)),
+          actual: Color.colorize_percent(violation.fetch(:actual)),
           expected: violation.fetch(:expected),
           group_name: violation.fetch(:group_name)
-        )
+        )]
       end
     end
   end

data/lib/simplecov/exit_codes/minimum_overall_coverage_check.rb

@@ -2,53 +2,52 @@
 
 module SimpleCov
   module ExitCodes
-    # Fails when the overall (project-wide) coverage for any criterion is
-    # below the configured minimum.
     class MinimumOverallCoverageCheck < Check
       def exit_code
-        SimpleCov::ExitCodes::MINIMUM_COVERAGE
+        MINIMUM_COVERAGE
       end
 
-    private
+      private
 
       WORST_FILES_LIMIT = 5
       private_constant :WORST_FILES_LIMIT
 
       def compute_violations
-        SimpleCov::CoverageViolations.minimum_overall(result, thresholds)
+        CoverageViolations.minimum_overall(result, thresholds)
       end
 
-      def report_violation(violation)
+      def violation_lines(violation)
         criterion = violation.fetch(:criterion)
-        actual = violation.fetch(:actual)
-        ExitCodes.print_error format(
+        headline = format(
           "%<criterion>s coverage (%<actual>s) is below the expected minimum coverage (%<expected>.2f%%).",
           criterion: criterion.capitalize,
-          actual: SimpleCov::Color.colorize_percent(actual),
+          actual: Color.colorize_percent(violation.fetch(:actual)),
           expected: violation.fetch(:expected)
         )
-        report_worst_files(criterion)
+        [headline, *worst_files_lines(criterion)]
       end
 
-      def report_worst_files(criterion)
+      def worst_files_lines(criterion)
         worst = worst_files_for(criterion)
-        return if worst.empty?
+        return [] if worst.empty?
 
-        ExitCodes.print_error "  Lowest-coverage files (#{criterion}):"
-        worst.each do |path, percent|
-          ExitCodes.print_error format(
+        ["  Lowest-coverage files (#{criterion}):"] + worst.map do |path, percent|
+          format(
             "    %<percent>s  %<path>s",
-            percent: SimpleCov::Color.colorize_percent(percent, format("%6.2f%%", percent)),
+            percent: Color.colorize_percent(percent, format("%6.2f%%", percent)),
             path: path
           )
         end
       end
 
+      # The list is a hint at where to add tests, so a fully covered file has no
+      # business on it: without the filter, files at 100% padded the list out to
+      # its five entries (#1286).
       def worst_files_for(criterion)
         stats_key = SimpleCov.coverage_statistics_key(criterion)
         with_stats = result.files.filter_map do |source_file|
           stats = source_file.coverage_statistics[stats_key]
-          [source_file.project_filename, stats.percent] if stats
+          [source_file.project_filename, stats.percent] if stats && stats.percent < 100
         end
         with_stats.sort_by { |_path, percent| percent }.first(WORST_FILES_LIMIT)
       end