simplecov 0.22.0 → 1.0.2

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

@@ -0,0 +1,128 @@
+# 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
+
+        def initialize(result, include_source: true)
+          @result = result
+          @include_source = include_source
+        end
+
+        def format
+          {
+            :$schema => SCHEMA_URL,
+            :meta => format_meta,
+            :total => format_coverage_statistics(@result.coverage_statistics),
+            :coverage => format_files,
+            :groups => format_groups,
+            :errors => ErrorsFormatter.new(@result).call
+          }
+        end
+
+      private
+
+        def format_files
+          @result.files.to_h do |source_file|
+            [source_file.project_filename, SourceFileFormatter.new(source_file, include_source: @include_source).call]
+          end
+        end
+
+        def format_groups
+          @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
+          {
+            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: line_coverage_enabled?,
+            branch_coverage: SimpleCov.branch_coverage?,
+            method_coverage: SimpleCov.method_coverage?
+          }
+        end
+
+        # Mirrors SourceFileFormatter's predicate so meta.line_coverage
+        # tracks exactly which configurations cause the formatter to
+        # emit line stats.
+        def line_coverage_enabled?
+          SimpleCov.coverage_criterion_enabled?(:line) || SimpleCov.coverage_criterion_enabled?(:oneshot_line)
+        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

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

@@ -0,0 +1,99 @@
+# 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
+        def initialize(source_file, include_source: true)
+          @source_file = source_file
+          @include_source = include_source
+        end
+
+        def call
+          result = @include_source ? format_source_code : {} #: Hash[Symbol, untyped]
+          result.merge!(line_coverage_section) if line_coverage_enabled?
+          result.merge!(branch_coverage_section) if SimpleCov.branch_coverage?
+          result.merge!(method_coverage_section) if SimpleCov.method_coverage?
+          result
+        end
+
+      private
+
+        # `:oneshot_line` is a synonym for `:line` for stats purposes
+        # (see `SimpleCov.coverage_statistics_key`), so treat either as
+        # "line coverage is on" for the line-block emit decisions.
+        def line_coverage_enabled?
+          SimpleCov.coverage_criterion_enabled?(:line) || SimpleCov.coverage_criterion_enabled?(:oneshot_line)
+        end
+
+        def format_source_code
+          {source: @source_file.lines.map { |line| ensure_utf8(line.src.chomp) }}
+        end
+
+        def ensure_utf8(str)
+          str.encode("UTF-8", invalid: :replace, undef: :replace)
+        end
+
+        def line_coverage_section
+          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
+          {
+            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
+          {
+            methods: @source_file.methods.map { |method| format_method(method) },
+            methods_covered_percent: @source_file.covered_percent(:method),
+            covered_methods: @source_file.covered_methods.size,
+            missed_methods: @source_file.missed_methods.size,
+            total_methods: @source_file.methods.size
+          }
+        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

data/lib/simplecov/formatter/json_formatter.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require "fileutils"
+require "json"
+require "time"
+
+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 = "coverage.json"
+
+      # `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.new(result, include_source: include_source).format
+      end
+
+      def format(result)
+        FileUtils.mkdir_p(output_path)
+        path = File.join(output_path, FILENAME)
+        warn_if_concurrent_overwrite(path, result)
+        File.write(path, JSON.pretty_generate(self.class.build_hash(result)))
+        # stderr, not stdout: this is a status message, not the program's
+        # output. Keeps the line out of pipelines like `rspec -f json`. And
+        # $stderr.puts, not `warn`: a status line should not reach
+        # `Warning.warn` hooks or vanish under `-W0` (see #1225).
+        $stderr.puts output_message(result) unless @silent # rubocop:disable Style/StderrPuts
+      end
+
+    private
+
+      def message_prefix
+        "JSON "
+      end
+
+      def entry_point_filename
+        FILENAME
+      end
+
+      # Warns when the existing coverage.json has a timestamp newer than this
+      # process's start time — a strong signal that a sibling test process
+      # (e.g., parallel_tests) wrote it while we were running, and that our
+      # write is about to clobber their data.
+      def warn_if_concurrent_overwrite(path, result)
+        start_time = SimpleCov.process_start_time or return
+        existing = existing_meta(path) or return
+        return unless existing[:timestamp] > start_time
+
+        # The HTML formatter also writes coverage.json (it shares the file as
+        # a side artifact), so when both formatters are configured the file we
+        # find was just written by our own run, not a concurrent one. A
+        # matching command_name means the same merged result, so there's
+        # nothing to lose by overwriting. See issue #1171.
+        return if existing[:command_name] == result.command_name
+
+        warn "simplecov: #{path} was written at #{existing[:timestamp].iso8601} — after " \
+             "this process started at #{start_time.iso8601}. Overwriting " \
+             "likely loses coverage data from a concurrent test run. For " \
+             "parallel test setups, use SimpleCov::ResultMerger or run a single " \
+             "collation step after all workers finish."
+      end
+
+      def existing_meta(path)
+        return nil unless File.exist?(path)
+
+        meta = JSON.parse(File.read(path), symbolize_names: true)
+        timestamp = meta.dig(:meta, :timestamp)
+        return nil unless timestamp
+
+        {timestamp: Time.iso8601(timestamp), command_name: meta.dig(:meta, :command_name)}
+      rescue JSON::ParserError, ArgumentError
+        nil
+      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)
           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,17 @@ 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
+        result.groups.map { |name, files| format_group(name, files) }.join
+      end
+
+    private
+
+      def format_group(name, files)
+        header = "Group: #{name}\n#{'=' * 40}\n"
+        # `covered_percent` is nilable across criteria, but line stats are
+        # always measured, so the no-argument call can't return nil here.
+        body   = files.map { |file| "#{file.filename} (coverage: #{(_ = file.covered_percent).floor(2)}%)\n" }.join
+        "#{header}#{body}\n"
       end
     end
   end

data/lib/simplecov/formatter.rb

@@ -1,6 +1,9 @@
 # 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
   end
@@ -8,3 +11,4 @@ end
 
 require_relative "formatter/simple_formatter"
 require_relative "formatter/multi_formatter"
+require_relative "formatter/json_formatter"

data/lib/simplecov/last_run.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "json"
 
 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
@@ -18,10 +21,14 @@ module SimpleCov
         JSON.parse(json, symbolize_names: true)
       end
 
+      # Write to a process-private temp file, then atomically rename, so a
+      # concurrent reader (e.g. another parallel-tests worker checking
+      # MaximumCoverageDrop) never sees a half-written file.
       def write(json)
-        File.open(last_run_path, "w+") do |f|
-          f.puts JSON.pretty_generate(json)
-        end
+        FileUtils.mkdir_p(SimpleCov.coverage_path)
+        temp_path = "#{last_run_path}.#{Process.pid}.tmp"
+        File.open(temp_path, "w") { |f| f.puts JSON.pretty_generate(json) }
+        File.rename(temp_path, last_run_path)
       end
     end
   end

data/lib/simplecov/lines_classifier.rb

@@ -1,19 +1,20 @@
 # frozen_string_literal: true
 
+require_relative "directive"
+
 module SimpleCov
   # Classifies whether lines are relevant for code coverage analysis.
   # Comments & whitespace lines, and :nocov: token blocks, are considered not relevant.
-
   class LinesClassifier
     RELEVANT = 0
     NOT_RELEVANT = nil
 
-    WHITESPACE_LINE = /^\s*$/.freeze
-    COMMENT_LINE = /^\s*#/.freeze
+    WHITESPACE_LINE = /^\s*$/
+    COMMENT_LINE = /^\s*#/
     WHITESPACE_OR_COMMENT_LINE = Regexp.union(WHITESPACE_LINE, COMMENT_LINE)
 
     def self.no_cov_line
-      /^(\s*)#(\s*)(:#{SimpleCov.nocov_token}:)/o
+      /^(\s*)#(\s*)(:#{SimpleCov.current_nocov_token}:)/o
     end
 
     def self.no_cov_line?(line)
@@ -31,17 +32,28 @@ module SimpleCov
     end
 
     def classify(lines)
+      lines = lines.to_a
+      directive_disabled = directive_disabled_line_set(lines)
       skipping = false
 
-      lines.map do |line|
-        if self.class.no_cov_line?(line)
-          skipping = !skipping
-          NOT_RELEVANT
-        elsif skipping || self.class.whitespace_line?(line)
-          NOT_RELEVANT
-        else
-          RELEVANT
-        end
+      lines.map.with_index(1) do |line, line_number|
+        skipping = !skipping if self.class.no_cov_line?(line)
+        not_relevant_line?(line, line_number, skipping, directive_disabled) ? NOT_RELEVANT : RELEVANT
+      end
+    end
+
+  private
+
+    def not_relevant_line?(line, line_number, skipping, directive_disabled)
+      skipping ||
+        self.class.no_cov_line?(line) ||
+        directive_disabled.include?(line_number) ||
+        self.class.whitespace_line?(line)
+    end
+
+    def directive_disabled_line_set(lines)
+      Directive.disabled_ranges(lines).fetch(:line).each_with_object(Set.new) do |range, set|
+        range.each { |line_number| set.add(line_number) }
       end
     end
   end

data/lib/simplecov/load_global_config.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
-require "etc"
-home_dir = (ENV["HOME"] && File.expand_path("~")) || Etc.getpwuid.dir || (ENV["USER"] && File.expand_path("~#{ENV['USER']}"))
-if home_dir
-  global_config_path = File.join(home_dir, ".simplecov")
+# `~/.simplecov` was historically resolved via a three-step fallback chain
+# (HOME, then `Etc.getpwuid.dir`, then `~$USER`) for hostile container
+# environments circa 2017. Modern CRuby/JRuby/TruffleRuby all set HOME
+# reliably, so trust it and skip silently when it isn't there.
+if ENV.fetch("HOME", nil)
+  # simplecov:disable — only fires when ~/.simplecov exists, which is
+  # developer-machine-dependent (we can't rely on it for the dogfood).
+  global_config_path = File.join(File.expand_path("~"), ".simplecov")
   load global_config_path if File.exist?(global_config_path)
+  # simplecov:enable
 end

data/lib/simplecov/parallel_adapters/base.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ParallelAdapters
+    # Default no-op implementations for a parallel-test-runner adapter.
+    # Real adapters subclass and override what they need; everything else
+    # falls back to "behave like a single-process run."
+    #
+    # Adapters are classes (used as singletons, never instantiated) — they
+    # answer a small fixed set of questions about whether THIS worker
+    # process is the one that should do final-result work, and provide an
+    # optional hook for waiting on sibling workers.
+    #
+    # @see SimpleCov::ParallelAdapters for the registry and selection.
+    class Base
+      class << self
+        # Should this adapter be selected for the current process? Adapters
+        # are tried in registration order; the first one whose `active?`
+        # returns true is chosen. Inactive adapters return `false`.
+        def active?
+          false
+        end
+
+        # Among the parallel workers in this run, should THIS worker do
+        # the final-result work (wait for siblings, merge resultsets,
+        # run threshold checks, format the report)? Default is `true`
+        # for the single-process case.
+        def first_worker?
+          true
+        end
+
+        # Optional: block until sibling workers have finished writing
+        # their resultsets. An adapter that wraps a parallel-test runner
+        # with a native synchronization primitive (e.g., `parallel_tests`'s
+        # `wait_for_other_processes_to_finish`) implements this for
+        # lower latency; otherwise SimpleCov polls the resultset cache
+        # as a fallback (see `SimpleCov.wait_for_parallel_results`).
+        def wait_for_siblings
+          # No-op default; polling fallback handles correctness.
+        end
+
+        # Does `wait_for_siblings` block until every sibling PROCESS has
+        # exited (so no further resultset can appear)? When true, the
+        # reporting worker can accept a settled resultset count below
+        # `expected_worker_count` as final instead of waiting out the whole
+        # `parallel_wait_timeout` for workers that produced no coverage.
+        # Defaults to false (no native wait; the poll is the only signal).
+        def native_wait?
+          false
+        end
+
+        # How many parallel workers are participating in this run. Used
+        # by the polling fallback to know how many resultset entries to
+        # expect. Defaults to 1 (single-process).
+        def expected_worker_count
+          1
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/parallel_adapters/generic.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SimpleCov
+  module ParallelAdapters
+    # Catch-all adapter for parallel test runners that follow the
+    # `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` env-var convention but
+    # don't ship a Ruby API for SimpleCov to hook (parallel_rspec,
+    # knapsack-style splitters, custom CI sharding scripts). Activates
+    # when `TEST_ENV_NUMBER` is set; doesn't require any specific gem to
+    # be loaded.
+    #
+    # Heuristic for `first_worker?`: the worker whose `TEST_ENV_NUMBER`
+    # is `""` (parallel_tests/parallel_rspec convention) or `"1"`
+    # (zero-based runners that start at 1). Any other value is treated
+    # as a non-first worker.
+    #
+    # `wait_for_siblings` is inherited from Base as a no-op — without a
+    # runner-provided API the only synchronization available is polling
+    # the resultset cache, which `SimpleCov.wait_for_parallel_results`
+    # does after the no-op returns.
+    class GenericAdapter < Base
+      class << self
+        def active?
+          return false if SimpleCov.parallel_tests == false
+
+          ENV.key?("TEST_ENV_NUMBER")
+        end
+
+        # parallel_tests sets the first worker's TEST_ENV_NUMBER to "";
+        # parallel_rspec inherits that. Runners that number from 1 use
+        # "1" for the first worker. Both shapes match.
+        def first_worker?
+          ["", "1"].include?(ENV.fetch("TEST_ENV_NUMBER", nil))
+        end
+
+        def expected_worker_count
+          ENV["PARALLEL_TEST_GROUPS"]&.to_i || 1
+        end
+      end
+    end
+  end
+end