simplecov 1.1.0 → 1.2.0

data/lib/simplecov/formatter/html_formatter/viewer_data_validator.rb

@@ -5,8 +5,6 @@ require "time"
 module SimpleCov
   module Formatter
     class HTMLFormatter
-      # Validates the subset of coverage.json that the browser viewer
-      # dereferences without defensive fallbacks.
       module ViewerDataValidator
         META_STRINGS = %w[simplecov_version command_name project_name timestamp].freeze
         COVERAGE_FLAGS = {
@@ -25,36 +23,95 @@ module SimpleCov
             validate_statistics!(data.fetch("total"), meta, "total")
             data.fetch("coverage").each { |filename, file| validate_file!(filename, file) }
             data.fetch("groups").each { |name, group| validate_group!(name, group, meta) }
+            validate_contexts!(data)
+            validate_production!(data)
             data
           end
 
-        private
+          private
 
           def validate_section!(data, key)
-            return if data[key].is_a?(Hash)
+            return if data[key].instance_of?(Hash)
 
-            raise SimpleCov::CoverageJSON::Error, "#{key.inspect} must be an object"
+            raise CoverageJSON::Error, "#{key.inspect} must be an object"
           end
 
           def validate_file!(filename, file)
-            unless file.is_a?(Hash)
-              raise SimpleCov::CoverageJSON::Error, "coverage entry #{filename.inspect} must be an object"
+            unless file.instance_of?(Hash)
+              raise CoverageJSON::Error, "coverage entry #{filename.inspect} must be an object"
             end
 
             source = file["source"]
-            return if source.is_a?(Array) && source.all?(String)
+            return if source.instance_of?(Array) && source.all?(String)
 
-            raise SimpleCov::CoverageJSON::Error,
-                  "coverage entry #{filename.inspect} must include an array of source strings; " \
-                  "regenerate with source_in_json true"
+            raise CoverageJSON::Error,
+              "coverage entry #{filename.inspect} must include an array of source strings; " \
+              "regenerate with source_in_json true"
+          end
+
+          def validate_contexts!(data)
+            contexts = data["contexts"]
+            valid = contexts.nil? || (contexts.instance_of?(Array) && contexts.all?(String))
+            raise CoverageJSON::Error, '"contexts" must be an array of strings' unless valid
+
+            count = Array(contexts).size
+            data.fetch("coverage").each { |filename, file| validate_context_table!(filename, file["contexts"], count) }
+          end
+
+          def validate_context_table!(filename, table, count)
+            return if table.nil? || (table.instance_of?(Hash) && table.all? do |key, value|
+              context_entry?(key, value, count)
+            end)
+
+            raise CoverageJSON::Error,
+              "coverage entry #{filename.inspect} contexts must map recorded context indices to hex bitmaps"
+          end
+
+          def context_entry?(key, value, count)
+            key.instance_of?(String) && key.match?(/\A\d+\z/) && Integer(key) < count &&
+              value.instance_of?(String) && value.match?(/\A\h+\z/)
+          end
+
+          def validate_production!(data)
+            production = data["production"]
+            return if production.nil?
+
+            raise CoverageJSON::Error, '"production" must be an object' unless production.instance_of?(Hash)
+
+            files = validate_type!(production, "files", Hash, "production")
+            files.each { |filename, entry| validate_production_file!(filename, entry) }
+          end
+
+          def validate_production_file!(filename, entry)
+            unless production_lines?(entry)
+              raise CoverageJSON::Error,
+                "production entry #{filename.inspect} must list sorted line numbers"
+            end
+            last_seen = entry["last_seen"]
+            return if last_seen.nil? || last_seen.instance_of?(String)
+
+            raise CoverageJSON::Error, "production entry #{filename.inspect} last_seen must be a string"
+          end
+
+          def production_lines?(entry)
+            lines = entry["lines"] if entry.instance_of?(Hash)
+            lines.instance_of?(Array) && lines.all? { |line| line.instance_of?(Integer) && line.positive? }
           end
 
           def validate_meta!(meta)
             META_STRINGS.each { |key| validate_type!(meta, key, String, "meta") }
+            validate_command_names!(meta)
             Time.iso8601(meta.fetch("timestamp"))
             COVERAGE_FLAGS.each_key { |key| validate_boolean!(meta, key) }
           rescue ArgumentError
-            raise SimpleCov::CoverageJSON::Error, "meta.timestamp must be an ISO 8601 date-time"
+            raise CoverageJSON::Error, "meta.timestamp must be an ISO 8601 date-time"
+          end
+
+          def validate_command_names!(meta)
+            names = meta["command_names"]
+            return if names.nil? || (names.instance_of?(Array) && names.all?(String))
+
+            raise CoverageJSON::Error, "meta.command_names must be an array of strings"
           end
 
           def validate_statistics!(statistics, meta, location)
@@ -67,11 +124,11 @@ module SimpleCov
           end
 
           def validate_group!(name, group, meta)
-            raise SimpleCov::CoverageJSON::Error, "group #{name.inspect} must be an object" unless group.is_a?(Hash)
+            raise CoverageJSON::Error, "group #{name.inspect} must be an object" unless group.instance_of?(Hash)
 
             files = group["files"]
-            unless files.is_a?(Array) && files.all?(String)
-              raise SimpleCov::CoverageJSON::Error, "group #{name.inspect}.files must be an array of strings"
+            unless files.instance_of?(Array) && files.all?(String)
+              raise CoverageJSON::Error, "group #{name.inspect}.files must be an array of strings"
             end
 
             validate_statistics!(group, meta, "group #{name.inspect}")
@@ -81,13 +138,13 @@ module SimpleCov
             value = object[key]
             return value if value.is_a?(type)
 
-            raise SimpleCov::CoverageJSON::Error, "#{location}.#{key} must be a #{type.name.downcase}"
+            raise CoverageJSON::Error, "#{location}.#{key} must be a #{type.name.downcase}"
           end
 
           def validate_boolean!(meta, key)
             return if [true, false].include?(meta[key])
 
-            raise SimpleCov::CoverageJSON::Error, "meta.#{key} must be a boolean"
+            raise CoverageJSON::Error, "meta.#{key} must be a boolean"
           end
         end
       end

data/lib/simplecov/formatter/html_formatter.rb

@@ -10,57 +10,45 @@ 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.
+    # template already carries the viewer app's JS and CSS inline, so the report
+    # can be mailed, uploaded as one 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.
+      # Generates HTML from a pre-existing coverage.json without a live Result or
+      # even a running test suite. The round-trip through parse/generate compacts
+      # the input and rejects invalid JSON here rather than at view time.
       def format_from_json(json_path, output_dir)
-        data = ViewerDataValidator.call(SimpleCov::CoverageJSON.load(json_path))
+        data = ViewerDataValidator.call(CoverageJSON.load(json_path))
         json = JSON.generate(data)
         AtomicFile.write(File.join(output_dir, "index.html"), render_report(json), binary: true)
       end
 
-    private
+      private
 
       def entry_point_filename
         "index.html"
       end
 
+      # The inlined report data feeds the client-side viewer, which renders source
+      # from the embedded array, so it always needs `source` regardless of
+      # `SimpleCov.source_in_json`. The side-file `coverage.json` honors the
+      # setting, and stays pretty-printed for human readers while the embedded
+      # copy is serialized compactly.
       def source_less_hash(hash)
         coverage = hash.fetch(:coverage).transform_values { |file| file.except(:source) }
         hash.merge(coverage: coverage)
@@ -72,31 +60,26 @@ module SimpleCov
         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.
+      # `<` is escaped as \u003c, valid JSON since `<` can only occur inside
+      # strings, so embedded source text containing "</script>" cannot terminate
+      # the surrounding element. Block forms keep gsub/sub from interpreting
+      # backslashes in the JSON as replacement-string back-references.
+      #
+      # The template is read as UTF-8 explicitly, not the locale's
+      # `Encoding.default_external`: substituting a UTF-8 payload into a template
+      # tagged US-ASCII raises Encoding::CompatibilityError.
       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>"
+        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/")
+        "#{__dir__}/html_formatter/public/"
       end
     end
   end

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

@@ -3,11 +3,6 @@
 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
@@ -17,27 +12,45 @@ module SimpleCov
             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
+          private
 
           def format_minimum_overall(result, errors)
-            SimpleCov::CoverageViolations.minimum_overall(result, SimpleCov.minimum_coverage).each do |violation|
+            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 = 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]
@@ -45,11 +58,9 @@ module SimpleCov
           end
 
           def format_minimum_by_group(result, errors)
-            violations = SimpleCov::CoverageViolations.minimum_by_group(result, SimpleCov.minimum_coverage_by_group)
+            violations = 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]
@@ -58,18 +69,37 @@ module SimpleCov
           end
 
           def format_maximum_overall(result, errors)
-            SimpleCov::CoverageViolations.maximum_overall(result, SimpleCov.maximum_coverage).each do |violation|
+            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)}
+            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
@@ -81,6 +111,10 @@ module SimpleCov
           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

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

@@ -3,28 +3,24 @@
 require "open3"
 require "time"
 require_relative "errors_formatter"
+require_relative "production_section_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"
+        # 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),
@@ -32,13 +28,28 @@ module SimpleCov
               :groups => format_groups(result),
               :errors => ErrorsFormatter.call(result)
             }
+            add_optional_sections(document, result)
+            document
           end
 
-        private
+          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)]
+              [source_file.project_filename,
+                SourceFileFormatter.call(source_file, include_source: include_source, contexts: result.contexts)]
             end
           end
 
@@ -52,26 +63,24 @@ module SimpleCov
           def format_meta(result)
             {
               schema_version: SCHEMA_VERSION,
-              simplecov_version: SimpleCov::VERSION,
-              command_name: result.command_name,
+              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
-            }.merge!(coverage_flags)
+              primary_coverage: SimpleCov.primary_coverage.to_s, **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.
+          # 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.to_s, "rev-parse", "HEAD")
-            status.success? ? output.strip : nil
-          rescue StandardError
+            output, status = Open3.capture2e("git", "-C", SimpleCov.root, "rev-parse", "HEAD")
+            output.strip if status.success?
+          rescue
             nil
           end
 
@@ -83,11 +92,16 @@ module SimpleCov
             }
           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]
-            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]
+            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
 

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

@@ -3,26 +3,30 @@
 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)
+          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
+          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.
+          # 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

data/lib/simplecov/formatter/json_formatter.rb

@@ -6,17 +6,12 @@ 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.
+      # 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
@@ -26,7 +21,7 @@ module SimpleCov
         emit_status(result)
       end
 
-    private
+      private
 
       def message_prefix
         "JSON "
@@ -39,8 +34,7 @@ module SimpleCov
   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`.
+# 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"