simplecov 0.22.0 → 1.3.0

data/lib/simplecov/history.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "time"
+require_relative "atomic_file"
+
+module SimpleCov
+  # A bounded record of past runs, coverage/.history.json (#1267): one entry
+  # per reported run carrying the per-criterion totals, the per-group and
+  # per-file percentages, a timestamp, and the branch and commit when the
+  # project is a git checkout. It is what turns "did the number move since the
+  # very last run" into direction of travel.
+  #
+  # Entries are capped and written atomically, and a corrupt or foreign file
+  # degrades to an empty history with a warning rather than crashing the
+  # at_exit hook, the same tolerance `.last_run.json` has. The file is
+  # deliberately plain committable JSON.
+  module History
+    ENVELOPE = "simplecov_history"
+    FORMAT_VERSION = 1
+
+    class << self
+      def history_path
+        File.join(SimpleCov.coverage_path, ".history.json")
+      end
+
+      def record(result)
+        limit = SimpleCov.history_limit
+        return if limit.zero?
+
+        entries = read
+        entries << entry_for(result)
+        write(entries.last(limit))
+      end
+
+      def read
+        return [] unless File.exist?(history_path)
+
+        content = File.read(history_path)
+        return [] if content.match?(/\A\s*\z/)
+
+        entries = JSON.parse(content).dig(ENVELOPE, "entries")
+        entries.instance_of?(Array) ? entries : invalid_history
+      rescue JSON::ParserError
+        invalid_history
+      end
+
+      # The recorded entries plus `result` as the newest, capped, and without
+      # writing anything: what the report artifacts embed, so the embedded history
+      # includes the run being reported even though recording happens later.
+      def entries_with(result)
+        (read << entry_for(result)).last(SimpleCov.history_limit)
+      end
+
+      # A detached HEAD reports its branch as nil rather than the literal "HEAD"
+      # most CI checkouts would record.
+      def git_info
+        branch = git("rev-parse", "--abbrev-ref", "HEAD")
+        branch = nil if branch.eql?("HEAD")
+        [branch, git("rev-parse", "HEAD")]
+      end
+
+      private
+
+      def entry_for(result)
+        branch, commit = git_info
+        {
+          # getutc, not utc: the destructive variant would rezone the Time the result
+          # still holds.
+          "created_at" => result.created_at.getutc.iso8601,
+          "branch" => branch,
+          "commit" => commit,
+          "totals" => measured_percents(result),
+          "groups" => result.groups.transform_values { |files| measured_percents(files) },
+          "files" => files_percents(result)
+        }
+      end
+
+      def measured_percents(stats_source)
+        stats_source.coverage_statistics.to_h do |criterion, stats|
+          [criterion.to_s, SimpleCov.round_coverage(stats.percent)]
+        end
+      end
+
+      def files_percents(result)
+        measured = result.coverage_statistics
+        initial = {} #: Hash[String, Hash[String, Numeric]]
+        result.files.each_with_object(initial) do |file, percents|
+          stats = file.coverage_statistics
+          percents[file.project_filename] = measured.to_h do |criterion, _run_total|
+            [criterion.to_s, SimpleCov.round_coverage(stats.fetch(criterion).percent)]
+          end
+        end
+      end
+
+      def write(entries)
+        payload = {ENVELOPE => {"format_version" => FORMAT_VERSION, "entries" => entries}}
+        AtomicFile.write(history_path, "#{JSON.pretty_generate(payload)}\n")
+      end
+
+      def invalid_history
+        warn "[SimpleCov]: Warning! Parsing JSON content of .history.json failed, starting a fresh history"
+        []
+      end
+
+      def git(*)
+        output, status = Open3.capture2e("git", "-C", SimpleCov.root.to_s, *)
+        output.rstrip if status.success?
+      rescue
+        nil
+      end
+    end
+  end
+end

data/lib/simplecov/last_run.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "atomic_file"
 
 module SimpleCov
   module LastRun
@@ -9,19 +10,29 @@ module SimpleCov
         File.join(SimpleCov.coverage_path, ".last_run.json")
       end
 
+      # The maximum_coverage_drop check digs into a Hash, so anything else in a
+      # corrupt or hand-edited file counts as "no previous run" rather than
+      # crashing the at_exit hook.
       def read
         return nil unless File.exist?(last_run_path)
 
         json = File.read(last_run_path)
-        return nil if json.strip.empty?
+        return nil if json.match?(/\A\s*\z/)
 
-        JSON.parse(json, symbolize_names: true)
+        parsed = JSON.parse(json, symbolize_names: true)
+        parsed.instance_of?(Hash) ? parsed : invalid_last_run
+      rescue JSON::ParserError
+        invalid_last_run
       end
 
       def write(json)
-        File.open(last_run_path, "w+") do |f|
-          f.puts JSON.pretty_generate(json)
-        end
+        AtomicFile.write(last_run_path, "#{JSON.pretty_generate(json)}\n")
+      end
+
+      private
+
+      def invalid_last_run
+        warn "[SimpleCov]: Warning! Parsing JSON content of .last_run.json failed, ignoring the previous run"
       end
     end
   end

data/lib/simplecov/lines_classifier.rb

@@ -1,47 +1,95 @@
 # frozen_string_literal: true
 
-module SimpleCov
-  # Classifies whether lines are relevant for code coverage analysis.
-  # Comments & whitespace lines, and :nocov: token blocks, are considered not relevant.
+require_relative "directive"
 
+module SimpleCov
+  # Classifies whether lines are relevant for code coverage analysis. Comments,
+  # whitespace lines, and disabled 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
 
+    # A marker is itself a comment, so the cheap whitespace-or-comment test gates
+    # 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 self.no_cov_line?(line)
       no_cov_line.match?(line)
     rescue ArgumentError
-      # E.g., line contains an invalid byte sequence in UTF-8
       false
     end
 
     def self.whitespace_line?(line)
       WHITESPACE_OR_COMMENT_LINE.match?(line)
     rescue ArgumentError
-      # E.g., line contains an invalid byte sequence in UTF-8
       false
     end
 
+    class SkipState
+      def initialize
+        @skipping = false
+      end
+
+      def skipping?
+        @skipping
+      end
+
+      def toggle
+        @skipping = !@skipping
+      end
+    end
+
+    # The skip state lives in a one-slot box owned by this call rather than in an
+    # ivar, so one classifier instance can serve concurrent `classify` calls
+    # without the toggles interleaving.
     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)
+      skip_state = SkipState.new
+
+      lines.map.with_index(1) do |line, line_number|
+        classify_line(line, line_number, directive_disabled, skip_state)
+      end
+    end
+
+    private
+
+    # mutant:disable — `NOT_RELEVANT` is nil, so naming it and writing
+    # the literal are the same value, and so is an `unless` that falls
+    # off its end. The name is kept because it says which of the two
+    # verdicts a line got, which nil alone does not.
+    def classify_line(line, line_number, directive_disabled, skip_state)
+      if self.class.whitespace_line?(line)
+        skip_state.toggle if self.class.no_cov_line?(line)
+        NOT_RELEVANT
+      elsif skip_state.skipping? || 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 through a three-step fallback chain
+# for hostile container environments circa 2017. Modern CRuby and JRuby both 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, 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,50 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ParallelAdapters
+    # Default no-op implementations for a parallel-test-runner adapter.
+    # Everything not overridden falls back to behaving like a single-process
+    # run. Adapters are classes, used as singletons and never instantiated.
+    class Base
+      class << self
+        def active?
+          false
+        end
+
+        def first_worker?
+          true
+        end
+
+        def wait_for_siblings
+        end
+
+        # Whether `wait_for_siblings` blocks 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`.
+        def native_wait?
+          false
+        end
+
+        def expected_worker_count
+          1
+        end
+
+        # mutant:disable — `false` is a singleton, so comparing against
+        # it answers the same through ==, eql? and equal?, and no
+        # example can tell the three apart.
+        def forced_off?
+          SimpleCov.parallel_tests == false
+        end
+
+        # 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", nil), exception: false)
+          count&.positive? ? count : 1
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/parallel_adapters/generic.rb

@@ -0,0 +1,33 @@
+# 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 ship no
+    # Ruby API for SimpleCov to hook. `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.
+    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 "", and runners
+        # that number from 1 use "1". Both shapes match; any other value is a
+        # non-first worker.
+        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,72 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SimpleCov
+  module ParallelAdapters
+    # Adapter for grosser/parallel_tests, the historical default and still the
+    # most precise option for projects on it. Detection requires the full native
+    # coordination contract: the `ParallelTests` constant loaded,
+    # `TEST_ENV_NUMBER` set, and `PARALLEL_PID_FILE` set, because the native
+    # wait API reads the pid-file path with `ENV.fetch`. A runner that only
+    # provides the env-var convention belongs to GenericAdapter.
+    class ParallelTestsAdapter < Base
+      class << self
+        def active?
+          return false if forced_off?
+
+          ensure_loaded
+          !!(defined?(::ParallelTests) && native_parallel_tests_environment?)
+        end
+
+        # The first started process, not the last. The parallel_tests README
+        # recommends `first_process?` for "do something once after every worker
+        # finishes" hooks, so user code with its own
+        # `wait_for_other_processes_to_finish` overwhelmingly waits in the first
+        # process, and picking the same side avoids the cross-process deadlock #922
+        # reported.
+        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
+
+        def native_wait?
+          native_parallel_tests_environment?
+        end
+
+        def expected_worker_count
+          parallel_test_groups_count
+        end
+
+        # parallel_tests is an optional dependency, and `TEST_ENV_NUMBER` /
+        # `PARALLEL_TEST_GROUPS` are commonly set for other reasons, so a missing
+        # gem is treated as "user isn't using parallel_tests": stay quiet and let
+        # GenericAdapter handle it. Warning here regressed users who use those env
+        # vars for their own subprocess coordination (#1018).
+        def ensure_loaded
+          return if defined?(::ParallelTests)
+          return if forced_off?
+          return unless SimpleCov.parallel_tests || env_suggests_parallel_tests?
+
+          # simplecov:disable — only fires under a real parallel_tests setup
+          require "parallel_tests"
+        rescue LoadError
+          # 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,54 @@
+# frozen_string_literal: true
+
+require_relative "parallel_adapters/base"
+require_relative "parallel_adapters/parallel_tests"
+require_relative "parallel_adapters/generic"
+
+module SimpleCov
+  # Registry and selection for parallel-test-runner adapters. An adapter
+  # answers a small fixed set of questions on SimpleCov's behalf: `active?`,
+  # `first_worker?`, `wait_for_siblings`, and `expected_worker_count`.
+  #
+  # `Base` provides safe no-op defaults. `ParallelTestsAdapter` wraps the
+  # grosser/parallel_tests gem; `GenericAdapter` is env-var-only detection for
+  # runners that follow the `TEST_ENV_NUMBER` convention without shipping a
+  # Ruby API (#1065, #1156).
+  #
+  # Users register their own with `ParallelAdapters.register MyAdapter`.
+  # Subclass `Base` to inherit the no-op defaults: the contract methods are
+  # class methods, so plain inheritance is what carries them through and
+  # `extend Base` won't pick them up.
+  module ParallelAdapters
+    extend self
+
+    # ParallelTestsAdapter first (most specific: it uses the gem's own API when
+    # the gem is loaded), then GenericAdapter as the env-var fallback.
+    # User-registered adapters are prepended.
+    def adapters
+      @adapters ||= [ParallelTestsAdapter, GenericAdapter]
+    end
+
+    # 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-ins.
+    def register(adapter)
+      reset_current!
+      adapters.unshift(adapter) unless adapters.include?(adapter)
+      adapter
+    end
+
+    # The first registered adapter whose `active?` answers true, or nil when
+    # none is, in which case the caller treats the process as single-worker.
+    def current
+      return @current if instance_variable_defined?(:@current)
+
+      @current = adapters.find(&:active?)
+    end
+
+    # Primarily for tests that mutate env vars between examples; production
+    # runs are single-shot.
+    def reset_current!
+      remove_instance_variable(:@current) if instance_variable_defined?(:@current)
+    end
+  end
+end

data/lib/simplecov/parallel_coordination.rb

@@ -0,0 +1,124 @@
+# 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 = ParallelAdapters.current
+      # 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 (Minitest's `parallelize`) have every worker produce
+      # the final report and its warnings (#1171).
+      return !forked_subprocess? unless adapter
+
+      adapter.first_worker?
+    end
+
+    # @api private
+    def wait_for_other_processes
+      adapter = ParallelAdapters.current
+      return unless adapter && final_result_process?
+
+      # Adapters that wrap a runner with a real "wait" primitive implement
+      # this; the rest 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. The outcome is captured so
+      # threshold checks can be suppressed 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.
+    def parallel_results_complete?
+      instance_variable_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 -- true when the reporting worker has every resultset it's
+    # going to get, false on timeout. Single-process runs short-circuit.
+    #
+    # Normally we poll until `expected` workers have reported or
+    # `SimpleCov.parallel_wait_timeout` elapses. When a native wait already
+    # confirmed every sibling process exited, no further resultset will appear,
+    # so a count below `expected` just means some workers produced none, and
+    # once the count holds steady for `PARALLEL_RESULTS_SETTLE` we accept it as
+    # final. Without a native wait 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 = ResultMerger.read_resultset
+      ResultMerger.worker_identities_for_run(resultset, run_id, process_start_time).size
+    end
+
+    # `tracker` carries the last count and the time it last changed across poll
+    # iterations. Answered through an if/else rather than an early return
+    # because falling through after a climb would read the clock a second time
+    # and answer the same `false` anyway.
+    def resultset_count_settled?(tracker, count)
+      if count > tracker.fetch(:count)
+        tracker[:count] = count
+        tracker[:since] = monotonic_time
+        false
+      else
+        count.positive? && (monotonic_time - tracker.fetch(:since)) >= PARALLEL_RESULTS_SETTLE
+      end
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # @api private -- 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 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

data/lib/simplecov/parallel_result_merger/worker_payload.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ParallelResultMerger
+    # What a worker ships back over its pipe: the `[command_names, coverage]` pair
+    # its slice folded to, the tracked paths the slice carried, and the slice's
+    # context-map union. Building and folding live together so the pipe format
+    # has one owner. The parent needs the union across every worker of the
+    # tracked paths, to know what nothing loaded, and of the maps, to judge the
+    # all-or-nothing rule over the whole run rather than per slice.
+    module WorkerPayload
+      extend self
+
+      def build(chunk, ignore_timeout:)
+        tracked_files = Set.new
+        context_maps = ContextMap::Union.new
+        pair = ResultMerger.absorb_results(chunk, ignore_timeout: ignore_timeout,
+          &ResultMerger.entry_collector(tracked_files, context_maps))
+        [pair, tracked_files.to_a, context_maps]
+      end
+
+      def absorb(payload, tracked_files, context_maps)
+        _pair, tracked, maps = payload
+        tracked_files.merge(tracked)
+        context_maps.absorb_union(maps)
+      end
+
+      def pair(payload)
+        payload.first
+      end
+    end
+  end
+end