simplecov 0.22.0 → 1.3.0

data/lib/simplecov/formatter/json_formatter/errors_formatter.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class JSONFormatter
+      class ErrorsFormatter
+        CRITERION_KEYS = {line: :lines, branch: :branches, method: :methods}.freeze
+        private_constant :CRITERION_KEYS
+
+        class << self
+          def call(result)
+            errors = {} #: Hash[Symbol, Hash[untyped, untyped]]
+            format_minimum_overall(result, errors)
+            format_minimum_by_file(result, errors)
+            format_baseline(result, errors)
+            format_minimum_by_group(result, errors)
+            format_maximum_overall(result, errors)
+            format_maximum_drop(result, errors)
+            format_maximum_missed(result, errors)
+            format_maximum_missed_per_file(result, errors)
+            errors
+          end
+
+          private
+
+          def format_minimum_overall(result, errors)
+            CoverageViolations.minimum_overall(result, SimpleCov.minimum_coverage).each do |violation|
+              bucket(errors, :minimum_coverage)[key_for(violation)] = expected_actual(violation)
+            end
+          end
+
+          def format_minimum_by_file(result, errors)
+            violations = CoverageViolations.minimum_by_file(
+              result, SimpleCov.minimum_coverage_by_file, SimpleCov.minimum_coverage_by_file_overrides,
+              baseline: SimpleCov.baseline
+            )
+            violations.each { |violation| record_by_file(violation, errors) }
+          end
+
+          # Baseline-floor violations keyed like minimum_coverage_by_file: filename,
+          # then criterion. The payload adds the two missed counts the floor was judged
+          # by; `allowed_missed` is absent for a percent-only floor.
+          def format_baseline(result, errors)
+            CoverageViolations.baseline(result, SimpleCov.baseline).each do |violation|
+              by_file = bucket(errors, :baseline)
+              file_bucket = by_file[violation.fetch(:project_filename)] ||= {} #: Hash[untyped, untyped]
+              payload = expected_actual(violation).merge(actual_missed: violation.fetch(:actual_missed))
+              allowed = violation.fetch(:allowed_missed)
+              payload[:allowed_missed] = allowed if allowed
+              file_bucket[key_for(violation)] = payload
+            end
+          end
+
+          def record_by_file(violation, errors)
+            by_file = bucket(errors, :minimum_coverage_by_file)
+            file_bucket = by_file[violation.fetch(:project_filename)] ||= {} #: Hash[untyped, untyped]
+            file_bucket[key_for(violation)] = expected_actual(violation)
+          end
+
+          def format_minimum_by_group(result, errors)
+            violations = CoverageViolations.minimum_by_group(result, SimpleCov.minimum_coverage_by_group)
+            return if violations.empty?
+
+            by_group = bucket(errors, :minimum_coverage_by_group)
+            violations.each do |violation|
+              group_bucket = by_group[violation.fetch(:group_name)] ||= {} #: Hash[untyped, untyped]
+              group_bucket[key_for(violation)] = expected_actual(violation)
+            end
+          end
+
+          def format_maximum_overall(result, errors)
+            CoverageViolations.maximum_overall(result, SimpleCov.maximum_coverage).each do |violation|
+              bucket(errors, :maximum_coverage)[key_for(violation)] = expected_actual(violation)
+            end
+          end
+
+          def format_maximum_drop(result, errors)
+            CoverageViolations.maximum_drop(result, SimpleCov.maximum_coverage_drop).each do |violation|
+              bucket(errors, :maximum_coverage_drop)[key_for(violation)] = maximum_actual(violation)
+            end
+          end
+
+          def format_maximum_missed(result, errors)
+            CoverageViolations.maximum_missed(result, SimpleCov.maximum_missed).each do |violation|
+              bucket(errors, :maximum_missed)[key_for(violation)] = maximum_actual(violation)
+            end
+          end
+
+          def format_maximum_missed_per_file(result, errors)
+            violations = CoverageViolations.maximum_missed_by_file(
+              result, SimpleCov.maximum_missed_per_file, SimpleCov.maximum_missed_per_file_overrides,
+              baseline: SimpleCov.baseline
+            )
+            violations.each do |violation|
+              by_file = bucket(errors, :maximum_missed_per_file)
+              file_bucket = by_file[violation.fetch(:project_filename)] ||= {} #: Hash[untyped, untyped]
+              file_bucket[key_for(violation)] = maximum_actual(violation)
+            end
+          end
+
+          # Lazily creates the errors key, so callers only touch it when there is a
+          # violation to record.
+          def bucket(errors, name)
+            errors[name] ||= {} #: Hash[untyped, untyped]
+          end
+
+          def key_for(violation)
+            CRITERION_KEYS.fetch(SimpleCov.coverage_statistics_key(violation.fetch(:criterion)))
+          end
+
+          def expected_actual(violation)
+            {expected: violation.fetch(:expected), actual: violation.fetch(:actual)}
+          end
+
+          def maximum_actual(violation)
+            {maximum: violation.fetch(:maximum), actual: violation.fetch(:actual)}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/formatter/json_formatter/production_section_formatter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../../production/file_sink"
+
+module SimpleCov
+  module Formatter
+    class JSONFormatter
+      module ProductionSectionFormatter
+        extend self
+
+        # The section for the configured store, or nil when none is configured or it
+        # is unreadable. An unreadable store warns instead of raising: the report is
+        # generated at the end of a test run, and a missing night of production data
+        # must not fail the suite that measured the tests.
+        def call(path = SimpleCov.production_coverage)
+          return nil unless path
+
+          section(Production::FileSink.read(path))
+        rescue SystemCallError, Production::Error => e
+          warn "[SimpleCov] skipping production coverage (#{e})"
+        end
+
+        def section(store)
+          section = {} #: Hash[Symbol, untyped]
+          started_at = store["started_at"]
+          updated_at = store["updated_at"]
+          section[:started_at] = started_at if started_at
+          section[:updated_at] = updated_at if updated_at
+          section[:files] = files(store)
+          section
+        end
+
+        # `coverage` and `last_seen` are the two keys a parsed store always carries,
+        # since `FileSink.parse` substitutes an empty Hash for either one a document
+        # is missing.
+        def files(store)
+          last_seen = store.fetch("last_seen")
+          store.fetch("coverage").sort.to_h do |file, lines|
+            entry = {lines: lines} #: Hash[Symbol, untyped]
+            stamp = last_seen[file]
+            entry[:last_seen] = stamp if stamp
+            [file, entry]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/formatter/json_formatter/result_hash_formatter.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "open3"
+require "time"
+require_relative "errors_formatter"
+require_relative "production_section_formatter"
+require_relative "source_file_formatter"
+
+module SimpleCov
+  module Formatter
+    class JSONFormatter
+      class ResultHashFormatter
+        # Bump this (and SCHEMA_URL) when the JSON shape changes: additive changes
+        # bump the minor segment, removals or shape changes the major. The versioned
+        # file at schemas/coverage-vX.Y.schema.json is the canonical artifact
+        # consumers should pin to.
+        SCHEMA_VERSION = "1.3"
+        SCHEMA_URL = "https://raw.githubusercontent.com/simplecov-ruby/simplecov/main/schemas/coverage-v#{SCHEMA_VERSION}.schema.json".freeze
+        private_constant :SCHEMA_VERSION, :SCHEMA_URL
+
+        class << self
+          def format(result, include_source: true)
+            document = {
+              :$schema => SCHEMA_URL,
+              :meta => format_meta(result),
+              :total => format_coverage_statistics(result.coverage_statistics),
+              :coverage => format_files(result, include_source: include_source),
+              :groups => format_groups(result),
+              :errors => ErrorsFormatter.call(result)
+            }
+            add_optional_sections(document, result)
+            document
+          end
+
+          private
+
+          # Contexts are present exactly when the result carried a complete map, so
+          # consumers can tell "recorded and empty" from "not recorded". History is
+          # present only when past runs are recorded, since one point is not a trend,
+          # and production coverage only when a store is configured and readable.
+          def add_optional_sections(document, result)
+            document[:contexts] = result.contexts.contexts if result.contexts
+            history = History.entries_with(result)
+            document[:history] = history if history.length > 1
+            production = ProductionSectionFormatter.call
+            document[:production] = production if production
+          end
+
+          def format_files(result, include_source:)
+            result.files.to_h do |source_file|
+              [source_file.project_filename,
+                SourceFileFormatter.call(source_file, include_source: include_source, contexts: result.contexts)]
+            end
+          end
+
+          def format_groups(result)
+            result.groups.to_h do |name, file_list|
+              stats = format_coverage_statistics(file_list.coverage_statistics)
+              [name, stats.merge(files: file_list.map(&:project_filename))]
+            end
+          end
+
+          def format_meta(result)
+            {
+              schema_version: SCHEMA_VERSION,
+              simplecov_version: VERSION,
+              command_name: result.command_name, command_names: result.command_names,
+              project_name: SimpleCov.project_name,
+              timestamp: result.created_at.iso8601(3),
+              root: SimpleCov.root,
+              commit: git_commit,
+              primary_coverage: SimpleCov.primary_coverage.to_s, **coverage_flags
+            }
+          end
+
+          # Recorded so tools can recover the exact source a report was generated
+          # against, which matters most when `source_in_json false` drops the source
+          # text. stderr is captured rather than forwarded so a non-git project doesn't
+          # print git's diagnostics to the build.
+          def git_commit
+            output, status = Open3.capture2e("git", "-C", SimpleCov.root, "rev-parse", "HEAD")
+            output.strip if status.success?
+          rescue
+            nil
+          end
+
+          def coverage_flags
+            {
+              line_coverage: SimpleCov.line_coverage?,
+              branch_coverage: SimpleCov.branch_coverage?,
+              method_coverage: SimpleCov.method_coverage?
+            }
+          end
+
+          # A criterion the run did not measure is absent from `statistics` entirely,
+          # and gets no section.
+          def format_coverage_statistics(statistics)
+            result = {} #: Hash[Symbol, untyped]
+            line = statistics[:line]
+            branch = statistics[:branch]
+            method_stat = statistics[:method]
+            result[:lines] = format_line_statistic(line) if line
+            result[:branches] = format_single_statistic(branch) if branch
+            result[:methods] = format_single_statistic(method_stat) if method_stat
+            result
+          end
+
+          def format_line_statistic(stat)
+            {
+              covered: stat.covered,
+              missed: stat.missed,
+              omitted: stat.omitted,
+              total: stat.total,
+              percent: stat.percent,
+              strength: stat.strength
+            }
+          end
+
+          def format_single_statistic(stat)
+            {
+              covered: stat.covered,
+              missed: stat.missed,
+              total: stat.total,
+              percent: stat.percent,
+              strength: stat.strength
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/formatter/json_formatter/source_file_formatter.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class JSONFormatter
+      class SourceFileFormatter
+        class << self
+          def call(source_file, include_source: true, contexts: nil)
+            result = include_source ? format_source_code(source_file) : {} #: Hash[Symbol, untyped]
+            result.merge!(line_coverage_section(source_file)) if SimpleCov.line_coverage?
+            result.merge!(branch_coverage_section(source_file)) if SimpleCov.branch_coverage?
+            result.merge!(method_coverage_section(source_file)) if SimpleCov.method_coverage?
+            result.merge!(contexts_section(source_file, contexts)) if contexts
+            result
+          end
+
+          private
+
+          # An untouched file gets no key at all: under a present document-level
+          # `contexts` array, absence already says "no recorded context executed this
+          # file".
+          def contexts_section(source_file, contexts)
+            bitmaps = contexts.serialized_bitmaps_for(source_file.filename)
+            bitmaps.empty? ? {} : {contexts: bitmaps}
+          end
+
+          # No per-line encoding conversion: SourceLoader guarantees every line leaves
+          # it as valid UTF-8, and the converter copy this used to make per line was
+          # the single largest allocation source in formatting a large report.
+          def format_source_code(source_file)
+            {source: source_file.lines.map { |line| line.src.chomp }}
+          end
+
+          def line_coverage_section(source_file)
+            covered = source_file.covered_lines.size
+            missed = source_file.missed_lines.size
+            {
+              lines: source_file.lines.map { |line| format_line(line) },
+              lines_covered_percent: source_file.covered_percent,
+              covered_lines: covered,
+              missed_lines: missed,
+              omitted_lines: source_file.never_lines.size,
+              total_lines: covered + missed
+            }
+          end
+
+          def branch_coverage_section(source_file)
+            {
+              branches: source_file.branches.map { |branch| format_branch(branch) },
+              branches_covered_percent: source_file.covered_percent(:branch),
+              covered_branches: source_file.covered_branches.size,
+              missed_branches: source_file.missed_branches.size,
+              total_branches: source_file.total_branches.size
+            }
+          end
+
+          def method_coverage_section(source_file)
+            covered = source_file.covered_methods.size
+            missed = source_file.missed_methods.size
+
+            {
+              methods: source_file.methods.map { |method| format_method(method) },
+              methods_covered_percent: source_file.covered_percent(:method),
+              covered_methods: covered,
+              missed_methods: missed,
+              total_methods: covered + missed
+            }
+          end
+
+          def format_line(line)
+            line.skipped? ? "ignored" : line.coverage
+          end
+
+          def format_branch(branch)
+            {
+              type: branch.type,
+              start_line: branch.start_line,
+              end_line: branch.end_line,
+              coverage: format_line(branch),
+              inline: branch.inline?,
+              report_line: branch.report_line
+            }
+          end
+
+          def format_method(method)
+            {
+              name: method.to_s,
+              start_line: method.start_line,
+              end_line: method.end_line,
+              coverage: format_line(method)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/formatter/json_formatter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "coverage_json_writer"
+require "json"
+
+module SimpleCov
+  module Formatter
+    class JSONFormatter < Base
+      FILENAME = CoverageJSONWriter::FILENAME
+
+      # Callers that need the source array regardless of the global setting (the
+      # HTML formatter, which feeds the client-side viewer) pass
+      # `include_source: true` explicitly.
+      def self.build_hash(result, include_source: SimpleCov.source_in_json)
+        ResultHashFormatter.format(result, include_source: include_source)
+      end
+
+      def format(result)
+        CoverageJSONWriter.write(output_path, self.class.build_hash(result), result)
+        emit_status(result)
+      end
+
+      private
+
+      def message_prefix
+        "JSON "
+      end
+
+      def entry_point_filename
+        FILENAME
+      end
+    end
+  end
+end
+
+# Loaded after the JSONFormatter class is defined so the nested reopen inside
+# result_hash_formatter.rb doesn't create a JSONFormatter < Object before this
+# file gets a chance to declare `JSONFormatter < Base`.
+require_relative "json_formatter/result_hash_formatter"

data/lib/simplecov/formatter/multi_formatter.rb

@@ -6,27 +6,25 @@ module SimpleCov
       module InstanceMethods
         def format(result)
           formatters.map do |formatter|
-            formatter.new.format(result)
-          rescue StandardError => e
-            warn("Formatter #{formatter} failed with #{e.class}: #{e.message} (#{e.backtrace.first})")
-            nil
+            Formatter.format(formatter, result)
+          rescue => e
+            warn("Formatter #{formatter} failed with #{e.class}: #{e} (#{(_ = e.backtrace).first})")
           end
         end
       end
 
+      # Normalized eagerly and captured in the closure. `Array()` is pure for every
+      # accepted input shape, so this is equivalent to the historical lazy
+      # per-instance memoization.
       def self.new(formatters = nil)
+        formatter_list = Array(formatters)
         Class.new do
           define_method :formatters do
-            @formatters ||= Array(formatters)
+            formatter_list
           end
           include InstanceMethods
         end
       end
-
-      def self.[](*args)
-        warn "#{Kernel.caller.first}: [DEPRECATION] ::[] is deprecated. Use ::new instead."
-        new(Array(args))
-      end
     end
   end
 end

data/lib/simplecov/formatter/simple_formatter.rb

@@ -2,23 +2,20 @@
 
 module SimpleCov
   module Formatter
-    #
-    # A ridiculously simple formatter for SimpleCov results.
-    #
     class SimpleFormatter
-      # Takes a SimpleCov::Result and generates a string out of it
       def format(result)
-        output = +""
-        result.groups.each do |name, files|
-          output << "Group: #{name}\n"
-          output << "=" * 40
-          output << "\n"
-          files.each do |file|
-            output << "#{file.filename} (coverage: #{file.covered_percent.round(2)}%)\n"
-          end
-          output << "\n"
-        end
-        output
+        criterion = SimpleCov.coverage_statistics_key(SimpleCov.primary_coverage)
+        result.groups.map { |name, files| format_group(name, files, criterion) }.join
+      end
+
+      private
+
+      def format_group(name, files, criterion)
+        header = "Group: #{name}\n#{"=" * 40}\n"
+        body = files.map do |file|
+          "#{file.filename} (coverage: #{(_ = file.covered_percent(criterion)).floor(2)}%)\n"
+        end.join
+        "#{header}#{body}\n"
       end
     end
   end

data/lib/simplecov/formatter.rb

@@ -1,10 +1,30 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # TODO: Documentation on how to build your own formatters
   module Formatter
+    # Formatters are configured either as classes, instantiated fresh for every
+    # report, or as ready-built instances, the only way to reach constructor
+    # options like `HTMLFormatter.new(silent: true)` (#1240).
+    def self.instance_for(formatter)
+      instantiable?(formatter) ? formatter.new : formatter
+    end
+
+    # mutant:disable
+    # `Class` cannot itself be subclassed, so `instance_of?(Class)` answers for
+    # every object exactly as `is_a?(Class)` does: a difference no example can
+    # show, which is why it is disabled here rather than pinned by a test.
+    def self.instantiable?(formatter)
+      formatter.is_a?(Class)
+    end
+    private_class_method :instantiable?
+
+    def self.format(formatter, result)
+      instance_for(formatter).format(result)
+    end
   end
 end
 
 require_relative "formatter/simple_formatter"
 require_relative "formatter/multi_formatter"
+require_relative "formatter/json_formatter"
+require_relative "formatter/baseline_formatter"

data/lib/simplecov/group_names.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module GroupNames
+    UNGROUPED = "Ungrouped"
+
+    extend self
+
+    # Group names are Hash keys, report labels, and JSON object keys all at once,
+    # so they are normalized to Strings up front: a Symbol spelling means the
+    # String, and anything else has no sensible serialized form. Normalizing
+    # before `validate!` also keeps `group :Ungrouped` from slipping past the
+    # reservation below.
+    def normalize(group_name)
+      case group_name
+      when String then group_name
+      when Symbol then group_name.to_s
+      else
+        raise ConfigurationError,
+          "Group names must be Strings, got #{group_name.inspect} (#{group_name.class})"
+      end
+    end
+
+    # Each name in turn, rather than asking the collection: a String asked
+    # whether it "includes" the reserved name answers about its own characters.
+    def validate!(group_names)
+      return group_names unless group_names.any? { |name| name.eql?(UNGROUPED) }
+
+      raise ConfigurationError,
+        "#{UNGROUPED.inspect} is reserved for files that do not match a configured group"
+    end
+  end
+end