simplecov 0.22.0 → 1.1.1

data/lib/simplecov/lines_classifier.rb

@@ -1,19 +1,30 @@
 # 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)
 
+    # The leading `^(\s*)#` anchor is load-bearing beyond matching the marker:
+    # `classify_line` only reaches this for lines that already passed
+    # `whitespace_line?`, which is sound only while every marker is also a
+    # comment. Loosening this to match a trailing `x = 1 # :nocov:` would stop
+    # the toggle firing. `lines_classifier_spec.rb` pins the implication.
+    #
+    # The `/o` flag freezes the interpolated nocov token at this
+    # process's first classification; a `nocov_token` configured after
+    # coverage has classified a file would be silently ignored. Sound
+    # today because configuration always precedes classification.
     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 +42,39 @@ module SimpleCov
     end
 
     def classify(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 = lines.to_a
+      directive_disabled = directive_disabled_line_set(lines)
+      # The `:nocov:` skip state lives in a one-slot box owned by this
+      # call, not in an ivar, so one classifier instance can serve
+      # concurrent `classify` calls without the toggles interleaving.
+      skip_state = [false]
+
+      lines.map.with_index(1) do |line, line_number|
+        classify_line(line, line_number, directive_disabled, skip_state)
+      end
+    end
+
+  private
+
+    # A `:nocov:` marker is itself a comment, so the cheap
+    # whitespace-or-comment test can gate the token match: a line of real
+    # code cannot be a marker, and no longer pays to be checked against
+    # one. That matters because this runs per line of every
+    # tracked-but-unloaded file, once in every process of a parallel run.
+    def classify_line(line, line_number, directive_disabled, skip_state)
+      if self.class.whitespace_line?(line)
+        skip_state[0] = !skip_state[0] if self.class.no_cov_line?(line)
+        NOT_RELEVANT
+      elsif skip_state[0] || directive_disabled.include?(line_number)
+        NOT_RELEVANT
+      else
+        RELEVANT
+      end
+    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,16 @@
 # 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. An ENV
+# check rather than Dir.home: JRuby raises from Dir.home with HOME
+# unset, and `File.expand_path("~")` raises for a set-but-empty HOME
+# (some container/CI images), which must not break `require "simplecov"`.
+unless ENV.fetch("HOME", "").empty?
+  # 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,78 @@
+# 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
+
+        # The user's explicit `SimpleCov.parallel_tests false` opt-out,
+        # which every adapter's `active?` honors before its own
+        # detection.
+        def forced_off?
+          SimpleCov.parallel_tests == false
+        end
+
+        # Shared implementation of the PARALLEL_TEST_GROUPS convention
+        # both built-in adapters follow for `expected_worker_count`.
+        # Unset, empty, non-numeric, and non-positive values all mean 1:
+        # an unparseable value must not yield 0 workers, which would end
+        # the sibling wait before it started.
+        def parallel_test_groups_count
+          count = Integer(ENV.fetch("PARALLEL_TEST_GROUPS", ""), exception: false)
+          count&.positive? ? count : 1
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/parallel_adapters/generic.rb

@@ -0,0 +1,45 @@
+# 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,
+    # rspec-conductor since 1.0.7, 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, rspec-conductor's
+    # default) or `"1"` (runners that number from 1, like rspec-conductor
+    # with `--first-is-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 forced_off?
+
+          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
+          parallel_test_groups_count
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/parallel_adapters/parallel_tests.rb

@@ -0,0 +1,93 @@
+# 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 requires the full native coordination
+    # contract: the `ParallelTests` constant has been loaded,
+    # `TEST_ENV_NUMBER` is set, and `PARALLEL_PID_FILE` is set. The pid-file
+    # path is required because the native wait API reads it with `ENV.fetch`.
+    # When a runner only provides the env-var convention, GenericAdapter is
+    # the correct coordination path.
+    class ParallelTestsAdapter < Base
+      class << self
+        def active?
+          return false if forced_off?
+
+          ensure_loaded
+          # !! to coerce `defined?` (returns nil or "constant") to a proper bool.
+          !!(defined?(::ParallelTests) && native_parallel_tests_environment?)
+        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
+          return unless native_parallel_tests_environment?
+
+          ::ParallelTests.wait_for_other_processes_to_finish
+        end
+
+        # The native wait blocks until every sibling process exits, but only
+        # when the pid-file contract is present (see `wait_for_siblings`).
+        def native_wait?
+          native_parallel_tests_environment?
+        end
+
+        def expected_worker_count
+          parallel_test_groups_count
+        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
+
+        def native_parallel_tests_environment?
+          ENV.key?("TEST_ENV_NUMBER") && ENV.key?("PARALLEL_PID_FILE")
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/parallel_adapters.rb

@@ -0,0 +1,85 @@
+# 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, rspec-conductor 1.0.7+, custom CI
+  #     sharding, knapsack-style splitters). See
+  #     https://github.com/simplecov-ruby/simplecov/issues/1065 and
+  #     https://github.com/simplecov-ruby/simplecov/issues/1156.
+  #
+  # 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

data/lib/simplecov/parallel_coordination.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# simplecov:disable
+# Methods below only fire under a parallel test runner; not reachable
+# from a single-process rspec run. Cucumber's test_projects exercise
+# the parallel_tests integration end-to-end in subprocesses, but
+# those subprocesses don't merge their Coverage data back into the
+# parent this dogfood report measures.
+module SimpleCov
+  class << self
+    # @api private
+    def final_result_process?
+      adapter = SimpleCov::ParallelAdapters.current
+      # No recognized parallel-test adapter. A subprocess forked while
+      # coverage was running is never the final reporter — the process that
+      # spawned it merges every slice and produces the report. Without this,
+      # fork-based runners that don't set TEST_ENV_NUMBER (e.g. Minitest's
+      # `parallelize`) have every worker produce the final report and its
+      # warnings. See issue #1171.
+      return !forked_subprocess? unless adapter
+
+      adapter.first_worker?
+    end
+
+    # @api private
+    def wait_for_other_processes
+      adapter = SimpleCov::ParallelAdapters.current
+      return unless adapter && final_result_process?
+
+      # Native synchronization first (adapters that wrap a runner with a
+      # real "wait" primitive — parallel_tests'
+      # `wait_for_other_processes_to_finish` — implement this; adapters
+      # without a native API no-op and rely on the polling fallback below).
+      adapter.wait_for_siblings
+
+      # The native wait can return before sibling at_exit handlers finish
+      # writing resultsets, and adapters without a native wait have
+      # nothing else. Either way, poll the resultset cache until all
+      # expected workers have reported or a timeout is reached. Capture
+      # the outcome so `ready_to_process_results?` can suppress min/max
+      # threshold checks against a partial total.
+      @parallel_results_complete =
+        wait_for_parallel_results(adapter.expected_worker_count, native_wait: adapter.native_wait?)
+    end
+
+    # @api private — true when every sibling reported its resultset
+    # before the wait deadline. Defaults to true outside a parallel
+    # run (when `wait_for_other_processes` is a no-op).
+    def parallel_results_complete?
+      defined?(@parallel_results_complete) ? @parallel_results_complete : true
+    end
+
+    # @api private — seconds the resultset count must hold steady, after a
+    # native wait, before we accept fewer than `expected` workers as final.
+    PARALLEL_RESULTS_SETTLE = 0.5
+    private_constant :PARALLEL_RESULTS_SETTLE
+
+    # @api private — returns true when the reporting worker has every
+    # resultset it's going to get, false on timeout. Single-process runs
+    # (expected <= 1) short-circuit to true with no waiting.
+    #
+    # Normally we poll until `expected` (= PARALLEL_TEST_GROUPS) workers have
+    # reported or `SimpleCov.parallel_wait_timeout` elapses; raise that setting
+    # when a slow worker routinely finishes well after the others.
+    #
+    # When a native wait already confirmed every sibling PROCESS exited
+    # (`native_wait`), no further resultset will appear, so a count below
+    # `expected` just means some workers produced none — e.g. parallel_test
+    # groups that got no spec file on a machine with more cores than files.
+    # Once the count then holds steady for `PARALLEL_RESULTS_SETTLE` we accept
+    # it as final rather than blocking for the whole timeout. Without a native
+    # wait (GenericAdapter) we can't tell an idle worker from a slow one, so we
+    # keep waiting the full timeout.
+    def wait_for_parallel_results(expected, native_wait: false)
+      return true unless expected > 1 # simplecov:disable branch — only false in real parallel runs
+
+      deadline = monotonic_time + parallel_wait_timeout
+      tracker = {count: 0, since: monotonic_time}
+      loop do
+        seen = current_parallel_worker_count
+        return true if seen >= expected
+        return true if native_wait && resultset_count_settled?(tracker, seen)
+        return false if parallel_wait_timed_out?(deadline, expected, seen)
+
+        sleep 0.1
+      end
+    end
+
+    def current_parallel_worker_count
+      resultset = SimpleCov::ResultMerger.read_resultset
+      SimpleCov::ResultMerger.worker_identities_for_run(resultset, SimpleCov.run_id, SimpleCov.process_start_time).size
+    end
+
+    # Track whether the resultset count has held steady (and positive) for
+    # `PARALLEL_RESULTS_SETTLE` seconds. `tracker` carries the last count and
+    # the time it last changed across poll iterations.
+    def resultset_count_settled?(tracker, count)
+      if count > tracker[:count]
+        tracker[:count] = count
+        tracker[:since] = monotonic_time
+        return false
+      end
+
+      count.positive? && (monotonic_time - tracker[:since]) >= PARALLEL_RESULTS_SETTLE
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # @api private — true once the wait deadline has passed; warns on
+    # the first timeout so the user knows the merged total is partial.
+    def parallel_wait_timed_out?(deadline, expected, seen)
+      return false unless monotonic_time > deadline
+
+      warn_about_incomplete_parallel_results(expected, seen)
+      true
+    end
+
+    # @api private
+    def warn_about_incomplete_parallel_results(expected, seen)
+      return unless print_errors
+
+      warn SimpleCov::Color.colorize(
+        "Only #{seen} of #{expected} parallel-test workers reported within " \
+        "#{parallel_wait_timeout}s, so coverage totals are partial and minimum / " \
+        "maximum coverage checks are skipped for this run. Increase " \
+        "SimpleCov.parallel_wait_timeout if a worker routinely needs longer.",
+        :yellow
+      )
+    end
+  end
+end
+# simplecov:enable