simplecov 0.22.0 → 1.0.0.rc2

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 : {}
+          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,77 @@
+# 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)
+        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`.
+        warn output_message(result) unless @silent
+      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)
+        start_time = SimpleCov.process_start_time or return
+        existing_ts = existing_timestamp(path) or return
+        return unless existing_ts > start_time
+
+        warn "simplecov: #{path} was written at #{existing_ts.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_timestamp(path)
+        return nil unless File.exist?(path)
+
+        timestamp = JSON.parse(File.read(path), symbolize_names: true).dig(:meta, :timestamp)
+        timestamp && Time.iso8601(timestamp)
+      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,7 +2,11 @@
 
 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|
@@ -22,11 +26,6 @@ module SimpleCov
           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,15 @@ 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"
+        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,21 @@
 # frozen_string_literal: true
 
+require "set"
+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 +33,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,51 @@
+# 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
+
+        # 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,42 @@
+# 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?
+          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

data/lib/simplecov/parallel_adapters/parallel_tests.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SimpleCov
+  module ParallelAdapters
+    # Adapter for [grosser/parallel_tests](https://github.com/grosser/parallel_tests).
+    # This is the historical default — SimpleCov has special-cased
+    # parallel_tests since 0.18 — and remains the most precise option for
+    # projects on it. Detection is the standard pair: the `ParallelTests`
+    # constant has been loaded AND `TEST_ENV_NUMBER` is set. The gem itself
+    # is autoloaded lazily on first `active?` check so users who don't have
+    # it installed see no warnings (see #1018).
+    class ParallelTestsAdapter < Base
+      class << self
+        def active?
+          ensure_loaded
+          # !! to coerce `defined?` (returns nil or "constant") to a proper bool.
+          !!(defined?(::ParallelTests) && ENV.key?("TEST_ENV_NUMBER"))
+        end
+
+        # Pick the *first* started process to do the final-result work,
+        # not the last. The parallel_tests README recommends
+        # `first_process?` for "do something once after every worker
+        # finishes" hooks, so user code that has its own
+        # `wait_for_other_processes_to_finish` in an `RSpec.after(:suite)`
+        # overwhelmingly waits in the first process — picking the same
+        # side avoids the cross-process deadlock #922 reported. Also
+        # handles `PARALLEL_TEST_GROUPS=1` naturally (the only worker's
+        # `TEST_ENV_NUMBER` is "" and `first_process?` tests for that
+        # empty string).
+        def first_worker?
+          ::ParallelTests.first_process?
+        end
+
+        def wait_for_siblings
+          ::ParallelTests.wait_for_other_processes_to_finish
+        end
+
+        def expected_worker_count
+          ENV["PARALLEL_TEST_GROUPS"]&.to_i || 1
+        end
+
+        # Auto-require `parallel_tests` when it's installed AND the env
+        # vars it sets are present, so callers can rely on
+        # `defined?(::ParallelTests)` downstream. parallel_tests is an
+        # optional dependency (see https://github.com/grosser/parallel_tests/issues/772),
+        # and `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` are commonly set
+        # for other reasons (custom subprocess coordination, CI sharding,
+        # the parallel_rspec gem which intentionally mirrors the env-var
+        # convention), so a missing gem is treated as "user isn't using
+        # parallel_tests" — silently skip and let GenericAdapter handle
+        # it. Users who want to override the auto-detect can set
+        # `SimpleCov.parallel_tests true` (force on) or `false` (force
+        # off). See #1018.
+        def ensure_loaded
+          return if defined?(::ParallelTests) # simplecov:disable — only true after a previous load
+          return if SimpleCov.parallel_tests == false # simplecov:disable — only fires when user opts out
+          # simplecov:disable — env-var-only path
+          return unless SimpleCov.parallel_tests || env_suggests_parallel_tests?
+
+          # simplecov:disable — only fires under a real parallel_tests setup
+          require "parallel_tests"
+        rescue LoadError
+          # Gem isn't installed; stay quiet — warning here regressed
+          # users who use those env vars for their own subprocess
+          # coordination.
+          # simplecov:enable
+        end
+
+        def env_suggests_parallel_tests?
+          ENV.key?("TEST_ENV_NUMBER") && ENV.key?("PARALLEL_TEST_GROUPS")
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/parallel_adapters.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "parallel_adapters/base"
+require_relative "parallel_adapters/parallel_tests"
+require_relative "parallel_adapters/generic"
+
+module SimpleCov
+  # Registry + selection for parallel-test-runner adapters. An adapter
+  # answers a small fixed set of questions on SimpleCov's behalf:
+  #
+  #   - `active?` — are WE the runner in charge for this process?
+  #   - `first_worker?` — should this process do the final-result work?
+  #   - `wait_for_siblings` — block until siblings finish (optional)
+  #   - `expected_worker_count` — how many workers total
+  #
+  # `SimpleCov::ParallelAdapters::Base` provides safe no-op defaults; two
+  # adapters ship out of the box:
+  #
+  #   - `ParallelTestsAdapter` — wraps the grosser/parallel_tests gem
+  #     (precise sync + first-process detection via the gem's own API).
+  #   - `GenericAdapter` — env-var-only detection for runners that follow
+  #     the parallel_tests `TEST_ENV_NUMBER` convention but don't ship a
+  #     Ruby API (parallel_rspec, custom CI sharding, knapsack-style
+  #     splitters). See https://github.com/simplecov-ruby/simplecov/issues/1065.
+  #
+  # Users can plug in additional adapters:
+  #
+  #   SimpleCov::ParallelAdapters.register MyRunnerAdapter
+  #
+  # An adapter just needs to be a class responding to the four methods
+  # above. Subclass `SimpleCov::ParallelAdapters::Base` to inherit the
+  # no-op defaults and override only what you need (the contract methods
+  # are defined as class methods, so plain inheritance is what carries
+  # them through; `extend Base` won't pick them up).
+  module ParallelAdapters
+  module_function
+
+    # Adapters in selection order. ParallelTestsAdapter first (most
+    # specific — uses the gem's own API when the gem is loaded); then
+    # GenericAdapter as the env-var fallback. User-registered adapters
+    # are prepended (#register puts new entries at the front) so
+    # downstream code can override the built-ins by registering a more
+    # specific match.
+    def adapters
+      @adapters ||= [ParallelTestsAdapter, GenericAdapter]
+    end
+
+    # Register a custom adapter. Newly registered adapters are inserted
+    # at the front of the selection list so a custom adapter for a
+    # specific runner takes precedence over the built-in ParallelTests
+    # and Generic adapters.
+    #
+    #   class MyRunnerAdapter < SimpleCov::ParallelAdapters::Base
+    #     def self.active?       = ENV["MY_RUNNER_PID"]
+    #     def self.first_worker? = ENV["MY_RUNNER_PID"].to_i == 1
+    #     def self.expected_worker_count = ENV["MY_RUNNER_WORKERS"].to_i
+    #   end
+    #
+    #   SimpleCov::ParallelAdapters.register MyRunnerAdapter
+    def register(adapter)
+      reset_current!
+      adapters.unshift(adapter) unless adapters.include?(adapter)
+      adapter
+    end
+
+    # The adapter SimpleCov should consult for this process — the first
+    # registered adapter whose `active?` returns true. Returns nil when
+    # no adapter is active (i.e., we're not running under any recognized
+    # parallel test runner), in which case the caller should treat the
+    # process as single-worker.
+    def current
+      return @current if defined?(@current)
+
+      @current = adapters.find(&:active?)
+    end
+
+    # Clear the memoized `current` selection. Primarily for tests that
+    # mutate env vars between examples; production runs are single-shot.
+    def reset_current!
+      remove_instance_variable(:@current) if defined?(@current)
+    end
+  end
+end