simplecov 0.22.0 → 1.1.1

data/lib/simplecov/formatter/html_formatter.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require_relative "base"
+require_relative "../atomic_file"
+require_relative "../coverage_json"
+require_relative "json_formatter"
+
+module SimpleCov
+  module Formatter
+    # Generates a single self-contained HTML coverage report. The compiled
+    # template (public/index.html) already carries the viewer app's JS and
+    # CSS inline; format substitutes the coverage JSON at the data marker
+    # and writes one index.html, so the report can be mailed, uploaded as
+    # a single CI artifact, or opened from anywhere without sibling files.
+    # A coverage.json is written alongside from the same in-memory hash.
+    class HTMLFormatter < Base
+      # Placeholder in the compiled template where the report's data goes.
+      DATA_MARKER = "<!-- SIMPLECOV_COVERAGE_DATA -->"
+
+      # The sibling files a 1.0.0 through 1.0.3 report wrote next to
+      # index.html. They are stale the moment a single-file report lands
+      # on top of them — `simplecov serve` would happily keep serving the
+      # old coverage_data.js — so formatting removes the known names.
+      LEGACY_REPORT_FILES = %w[
+        coverage_data.js application.js application.css
+        favicon_green.png favicon_red.png favicon_yellow.png
+      ].freeze
+
+      def format(result)
+        # The inlined report data feeds the client-side viewer, which
+        # renders source from the embedded array — it always needs
+        # `source`, regardless of `SimpleCov.source_in_json`. The
+        # side-file `coverage.json` honors the setting so downstream
+        # tools that read source from disk can opt into a smaller
+        # payload. The embedded copy is serialized compactly (pretty
+        # printing puts every element of every per-line coverage array
+        # on its own indented line, roughly doubling the payload);
+        # coverage.json stays pretty-printed for human readers.
+        viewer_hash = JSONFormatter.build_hash(result, include_source: true)
+        json_hash = SimpleCov.source_in_json ? viewer_hash : source_less_hash(viewer_hash)
+        write_report_files(json_hash, viewer_hash, result)
+        emit_status(result)
+      end
+
+      # Generate HTML from a pre-existing coverage.json file without
+      # needing a live SimpleCov::Result or even a running test suite.
+      # The round-trip through parse/generate compacts the (typically
+      # pretty-printed) input and rejects invalid JSON here rather than
+      # embedding it and failing at view time.
+      def format_from_json(json_path, output_dir)
+        data = ViewerDataValidator.call(SimpleCov::CoverageJSON.load(json_path))
+        json = JSON.generate(data)
+        AtomicFile.write(File.join(output_dir, "index.html"), render_report(json), binary: true)
+      end
+
+    private
+
+      def entry_point_filename
+        "index.html"
+      end
+
+      def source_less_hash(hash)
+        coverage = hash.fetch(:coverage).transform_values { |file| file.except(:source) }
+        hash.merge(coverage: coverage)
+      end
+
+      def write_report_files(json_hash, viewer_hash, result)
+        CoverageJSONWriter.write(output_path, json_hash, result)
+        AtomicFile.write(File.join(output_path, "index.html"), render_report(JSON.generate(viewer_hash)), binary: true)
+        FileUtils.rm_f(LEGACY_REPORT_FILES.map { |name| File.join(output_path, name) })
+      end
+
+      # Substitute the coverage JSON into the compiled template. `<` is
+      # escaped as \u003c — valid JSON, since `<` can only occur inside
+      # strings — so embedded source text containing "</script>" or
+      # "<!--" cannot terminate the surrounding <script> element. Block
+      # forms keep gsub/sub from interpreting backslashes in the JSON as
+      # replacement-string back-references.
+      def render_report(json)
+        # UTF-8 explicitly, not the locale's `Encoding.default_external`:
+        # the JSON payload is UTF-8, and substituting it into a template
+        # tagged US-ASCII (or a Windows code page) raises
+        # Encoding::CompatibilityError the moment either side carries a
+        # non-ASCII character.
+        template = File.read(File.join(public_dir, "index.html"), encoding: Encoding::UTF_8)
+        unless template.include?(DATA_MARKER)
+          raise "SimpleCov's HTML template is missing its #{DATA_MARKER.inspect} marker"
+        end
+
+        data_script = "<script>window.SIMPLECOV_DATA = #{json.gsub('<') { '\u003c' }};</script>"
+        template.sub(DATA_MARKER) { data_script }
+      end
+
+      def public_dir
+        # `.to_s` collapses `__dir__`'s nil arm (only possible under eval,
+        # which can't happen for a file on disk) so the path is a String.
+        File.join(__dir__.to_s, "html_formatter/public/")
+      end
+    end
+  end
+end
+
+require_relative "html_formatter/viewer_data_validator"

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class JSONFormatter
+      # Translates the threshold violations reported by
+      # `SimpleCov::CoverageViolations` into the `:errors` section of
+      # coverage.json. Each violation is keyed by criterion
+      # (`:lines` / `:branches` / `:methods`) so consumers can render
+      # per-criterion messages without re-deriving them.
+      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_minimum_by_group(result, errors)
+            format_maximum_overall(result, errors)
+            format_maximum_drop(result, errors)
+            errors
+          end
+
+        private
+
+          def format_minimum_overall(result, errors)
+            SimpleCov::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 = SimpleCov::CoverageViolations.minimum_by_file(
+              result, SimpleCov.minimum_coverage_by_file, SimpleCov.minimum_coverage_by_file_overrides
+            )
+            violations.each { |violation| record_by_file(violation, errors) }
+          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 = SimpleCov::CoverageViolations.minimum_by_group(result, SimpleCov.minimum_coverage_by_group)
+            return if violations.empty?
+
+            # `bucket` lazily creates the errors key, so only touch it when
+            # there is a violation to record.
+            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)
+            SimpleCov::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)
+            SimpleCov::CoverageViolations.maximum_drop(result, SimpleCov.maximum_coverage_drop).each do |violation|
+              bucket(errors, :maximum_coverage_drop)[key_for(violation)] =
+                {maximum: violation.fetch(:maximum), actual: violation.fetch(:actual)}
+            end
+          end
+
+          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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "open3"
+require "time"
+require_relative "errors_formatter"
+require_relative "source_file_formatter"
+
+module SimpleCov
+  module Formatter
+    class JSONFormatter
+      # Builds the hash that JSONFormatter serializes to coverage.json:
+      # meta, per-file coverage data, group totals, and aggregate stats.
+      class ResultHashFormatter
+        # Bump SCHEMA_VERSION (and SCHEMA_URL) when the JSON shape
+        # changes. Additive changes bump the minor segment, removals or
+        # shape changes bump the major segment. The versioned file at
+        # schemas/coverage-vX.Y.schema.json is the canonical artifact
+        # consumers should pin to, schemas/coverage.schema.json is a
+        # convenience alias that always tracks the latest. See the
+        # `coverage.json` schema section of the README for the rationale.
+        SCHEMA_VERSION = "1.0"
+        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)
+            {
+              :$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)
+            }
+          end
+
+        private
+
+          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)]
+            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: SimpleCov::VERSION,
+              command_name: result.command_name,
+              project_name: SimpleCov.project_name,
+              timestamp: result.created_at.iso8601(3),
+              root: SimpleCov.root,
+              commit: git_commit,
+              primary_coverage: SimpleCov.primary_coverage.to_s
+            }.merge!(coverage_flags)
+          end
+
+          # Full git commit SHA of `SimpleCov.root`'s HEAD, or nil when the
+          # project isn't a git checkout or git isn't on PATH. 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 from
+          # coverage.json. stderr is captured (not 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.to_s, "rev-parse", "HEAD")
+            status.success? ? output.strip : nil
+          rescue StandardError
+            nil
+          end
+
+          def coverage_flags
+            {
+              line_coverage: SimpleCov.line_coverage?,
+              branch_coverage: SimpleCov.branch_coverage?,
+              method_coverage: SimpleCov.method_coverage?
+            }
+          end
+
+          def format_coverage_statistics(statistics)
+            result = {} #: Hash[Symbol, untyped]
+            result[:lines]    = format_line_statistic(statistics[:line])      if statistics[:line]
+            result[:branches] = format_single_statistic(statistics[:branch])  if statistics[:branch]
+            result[:methods]  = format_single_statistic(statistics[:method])  if statistics[:method]
+            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,93 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class JSONFormatter
+      # Renders a single `SimpleCov::SourceFile` as the per-file payload
+      # in coverage.json: source code plus per-enabled-criterion arrays
+      # and totals.
+      class SourceFileFormatter
+        class << self
+          def call(source_file, include_source: true)
+            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
+          end
+
+        private
+
+          # No per-line encoding conversion here: SourceLoader guarantees
+          # every line leaves it as valid UTF-8 (transcoding declared
+          # encodings, scrubbing invalid bytes), 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,46 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "coverage_json_writer"
+require "json"
+
+module SimpleCov
+  module Formatter
+    # Writes coverage results as JSON to coverage/coverage.json. Used
+    # standalone, alongside the HTML formatter, or by external tools that
+    # consume SimpleCov output.
+    class JSONFormatter < Base
+      FILENAME = CoverageJSONWriter::FILENAME
+
+      # `include_source:` defaults to `SimpleCov.source_in_json` (true
+      # by default) so the historical payload shape is unchanged.
+      # 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
+# `class JSONFormatter` reopen inside result_hash_formatter.rb doesn't
+# accidentally 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

@@ -2,31 +2,35 @@
 
 module SimpleCov
   module Formatter
+    # Wraps multiple formatters so SimpleCov.formatter can drive several
+    # output formats (HTML + JSON, etc.) in a single run.
     class MultiFormatter
+      # Shared `#format` implementation; included into individual
+      # MultiFormatter subclasses built by `MultiFormatter.new`.
       module InstanceMethods
         def format(result)
           formatters.map do |formatter|
-            formatter.new.format(result)
+            Formatter.format(formatter, result)
           rescue StandardError => e
-            warn("Formatter #{formatter} failed with #{e.class}: #{e.message} (#{e.backtrace.first})")
+            warn("Formatter #{formatter} failed with #{e.class}: #{e.message} (#{(_ = e.backtrace).first})")
             nil
           end
         end
       end
 
       def self.new(formatters = nil)
+        # Normalize eagerly and capture the list in the closure. Array()
+        # is pure for every accepted input shape (nil, single formatter,
+        # array, or another MultiFormatter class), so this is equivalent
+        # to the historical lazy per-instance memoization.
+        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

@@ -8,17 +8,20 @@ module SimpleCov
     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"
+        # The configured primary criterion is enabled, so every result file
+        # carries its corresponding statistic despite the nilable public API.
+        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,26 @@
 # frozen_string_literal: true
 
 module SimpleCov
+  # Namespace for SimpleCov result formatters. Built-in formatters live
+  # below this module; custom formatters should respond to `#format(result)`
+  # and can be wired up via `SimpleCov.formatter=`.
   # TODO: Documentation on how to build your own formatters
   module Formatter
+    # Formatters can be 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)`. See #1240.
+    def self.instance_for(formatter)
+      formatter.is_a?(Class) ? formatter.new : formatter
+    end
+
+    # Normalize a class or instance, then dispatch the result to it.
+    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"

data/lib/simplecov/group_names.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  # Semantic names owned by result processing rather than user configuration.
+  module GroupNames
+    UNGROUPED = "Ungrouped"
+
+  module_function
+
+    # 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
+    # (`group :Controllers`) 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 SimpleCov::ConfigurationError,
+              "Group names must be Strings, got #{group_name.inspect} (#{group_name.class})"
+      end
+    end
+
+    def validate!(group_names)
+      return group_names unless group_names.include?(UNGROUPED)
+
+      raise SimpleCov::ConfigurationError,
+            "#{UNGROUPED.inspect} is reserved for files that do not match a configured group"
+    end
+  end
+end

data/lib/simplecov/last_run.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "atomic_file"
 
 module SimpleCov
+  # Reads and writes coverage/.last_run.json — the previous run's coverage
+  # percentages used by MaximumCoverageDropCheck.
   module LastRun
     class << self
       def last_run_path
@@ -15,13 +18,24 @@ module SimpleCov
         json = File.read(last_run_path)
         return nil if json.strip.empty?
 
-        JSON.parse(json, symbolize_names: true)
+        parsed = JSON.parse(json, symbolize_names: true)
+        # The maximum_coverage_drop check digs into a Hash, so anything
+        # else in a corrupt or hand-edited file counts as "no previous
+        # run" rather than crashing the at_exit hook.
+        parsed.is_a?(Hash) ? parsed : invalid_last_run
+      rescue JSON::ParserError
+        invalid_last_run
       end
 
       def write(json)
-        File.open(last_run_path, "w+") do |f|
-          f.puts JSON.pretty_generate(json)
-        end
+        AtomicFile.write(last_run_path, "#{JSON.pretty_generate(json)}\n")
+      end
+
+    private
+
+      def invalid_last_run
+        warn "[SimpleCov]: Warning! Parsing JSON content of .last_run.json failed, ignoring the previous run"
+        nil
       end
     end
   end