simplecov 1.0.2 → 1.1.0

data/lib/simplecov/formatter/json_formatter.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "base"
-require "fileutils"
+require_relative "coverage_json_writer"
 require "json"
-require "time"
 
 module SimpleCov
   module Formatter
@@ -11,7 +10,7 @@ module SimpleCov
     # standalone, alongside the HTML formatter, or by external tools that
     # consume SimpleCov output.
     class JSONFormatter < Base
-      FILENAME = "coverage.json"
+      FILENAME = CoverageJSONWriter::FILENAME
 
       # `include_source:` defaults to `SimpleCov.source_in_json` (true
       # by default) so the historical payload shape is unchanged.
@@ -19,19 +18,12 @@ module SimpleCov
       # 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
+        ResultHashFormatter.format(result, include_source: include_source)
       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
+        CoverageJSONWriter.write(output_path, self.class.build_hash(result), result)
+        emit_status(result)
       end
 
     private
@@ -43,41 +35,6 @@ module SimpleCov
       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

data/lib/simplecov/formatter/multi_formatter.rb

@@ -10,7 +10,7 @@ module SimpleCov
       module InstanceMethods
         def format(result)
           formatters.map do |formatter|
-            formatter.new.format(result)
+            Formatter.format(formatter, result)
           rescue StandardError => e
             warn("Formatter #{formatter} failed with #{e.class}: #{e.message} (#{(_ = e.backtrace).first})")
             nil

data/lib/simplecov/formatter/simple_formatter.rb

@@ -8,16 +8,19 @@ module SimpleCov
     class SimpleFormatter
       # Takes a SimpleCov::Result and generates a string out of it
       def format(result)
-        result.groups.map { |name, files| format_group(name, files) }.join
+        criterion = SimpleCov.coverage_statistics_key(SimpleCov.primary_coverage)
+        result.groups.map { |name, files| format_group(name, files, criterion) }.join
       end
 
     private
 
-      def format_group(name, files)
+      def format_group(name, files, criterion)
         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
+        # The configured primary criterion is enabled, so every result file
+        # carries its corresponding statistic despite the nilable public API.
+        body = files.map do |file|
+          "#{file.filename} (coverage: #{(_ = file.covered_percent(criterion)).floor(2)}%)\n"
+        end.join
         "#{header}#{body}\n"
       end
     end

data/lib/simplecov/formatter.rb

@@ -6,6 +6,18 @@ module SimpleCov
   # and can be wired up via `SimpleCov.formatter=`.
   # TODO: Documentation on how to build your own formatters
   module Formatter
+    # Formatters can be configured either as classes (instantiated
+    # fresh for every report) or as ready-built instances — the only
+    # way to reach constructor options like
+    # `HTMLFormatter.new(silent: true)`. See #1240.
+    def self.instance_for(formatter)
+      formatter.is_a?(Class) ? formatter.new : formatter
+    end
+
+    # Normalize a class or instance, then dispatch the result to it.
+    def self.format(formatter, result)
+      instance_for(formatter).format(result)
+    end
   end
 end
 

data/lib/simplecov/group_names.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  # Semantic names owned by result processing rather than user configuration.
+  module GroupNames
+    UNGROUPED = "Ungrouped"
+
+  module_function
+
+    # Group names are Hash keys, report labels, and JSON object keys all at
+    # once, so they are normalized to Strings up front: a Symbol spelling
+    # (`group :Controllers`) means the String, and anything else has no
+    # sensible serialized form. Normalizing before `validate!` also keeps
+    # `group :Ungrouped` from slipping past the reservation below.
+    def normalize(group_name)
+      case group_name
+      when String then group_name
+      when Symbol then group_name.to_s
+      else
+        raise SimpleCov::ConfigurationError,
+              "Group names must be Strings, got #{group_name.inspect} (#{group_name.class})"
+      end
+    end
+
+    def validate!(group_names)
+      return group_names unless group_names.include?(UNGROUPED)
+
+      raise SimpleCov::ConfigurationError,
+            "#{UNGROUPED.inspect} is reserved for files that do not match a configured group"
+    end
+  end
+end

data/lib/simplecov/last_run.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require "fileutils"
 require "json"
+require_relative "atomic_file"
 
 module SimpleCov
   # Reads and writes coverage/.last_run.json — the previous run's coverage
@@ -18,17 +18,24 @@ module SimpleCov
         json = File.read(last_run_path)
         return nil if json.strip.empty?
 
-        JSON.parse(json, symbolize_names: true)
+        parsed = JSON.parse(json, symbolize_names: true)
+        # 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.
+        parsed.is_a?(Hash) ? parsed : invalid_last_run
+      rescue JSON::ParserError
+        invalid_last_run
       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)
-        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)
+        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"
+        nil
       end
     end
   end

data/lib/simplecov/lines_classifier.rb

@@ -13,6 +13,16 @@ module SimpleCov
     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.current_nocov_token}:)/o
     end
@@ -34,21 +44,32 @@ module SimpleCov
     def classify(lines)
       lines = lines.to_a
       directive_disabled = directive_disabled_line_set(lines)
-      skipping = false
+      # 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|
-        skipping = !skipping if self.class.no_cov_line?(line)
-        not_relevant_line?(line, line_number, skipping, directive_disabled) ? NOT_RELEVANT : RELEVANT
+        classify_line(line, line_number, directive_disabled, skip_state)
       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)
+    # 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)

data/lib/simplecov/load_global_config.rb

@@ -3,8 +3,11 @@
 # `~/.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)
+# 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")

data/lib/simplecov/parallel_adapters/base.rb

@@ -55,6 +55,23 @@ module SimpleCov
         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

data/lib/simplecov/parallel_adapters/generic.rb

@@ -23,7 +23,7 @@ module SimpleCov
     class GenericAdapter < Base
       class << self
         def active?
-          return false if SimpleCov.parallel_tests == false
+          return false if forced_off?
 
           ENV.key?("TEST_ENV_NUMBER")
         end
@@ -36,7 +36,7 @@ module SimpleCov
         end
 
         def expected_worker_count
-          ENV["PARALLEL_TEST_GROUPS"]&.to_i || 1
+          parallel_test_groups_count
         end
       end
     end

data/lib/simplecov/parallel_adapters/parallel_tests.rb

@@ -16,7 +16,7 @@ module SimpleCov
     class ParallelTestsAdapter < Base
       class << self
         def active?
-          return false if SimpleCov.parallel_tests == false
+          return false if forced_off?
 
           ensure_loaded
           # !! to coerce `defined?` (returns nil or "constant") to a proper bool.
@@ -50,7 +50,7 @@ module SimpleCov
         end
 
         def expected_worker_count
-          ENV["PARALLEL_TEST_GROUPS"]&.to_i || 1
+          parallel_test_groups_count
         end
 
         # Auto-require `parallel_tests` when it's installed AND the env

data/lib/simplecov/parallel_coordination.rb

@@ -77,7 +77,7 @@ module SimpleCov
       deadline = monotonic_time + parallel_wait_timeout
       tracker = {count: 0, since: monotonic_time}
       loop do
-        seen = SimpleCov::ResultMerger.read_resultset.size
+        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)
@@ -86,6 +86,11 @@ module SimpleCov
       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.

data/lib/simplecov/parallel_result_merger.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  #
+  # Folds a list of resultset files into one merged coverage table across
+  # forked worker processes. Drives `SimpleCov.collate(..., processes: N)`.
+  #
+  # `ResultMerger.absorb_results` is a fold over N independent
+  # read-parse-combine steps, so it splits cleanly: each worker runs that
+  # same fold over a contiguous slice of the file list and ships the pair
+  # back over a pipe, and the parent combines the handful of per-worker
+  # pairs it gets back. Reading and parsing the shards — where a collate
+  # over a few hundred CI jobs spends most of its time — is what actually
+  # parallelises.
+  #
+  # The slices are contiguous and merged back in order, so the fold visits
+  # the resultsets in the order the serial fold visits them and the merged
+  # result is identical to `SimpleCov.collate`'s, not merely equivalent.
+  #
+  # Every failure path returns nil rather than a partial merge, so the caller
+  # can redo the fold serially: reporting coverage for a subset of the
+  # resultsets would silently understate it.
+  #
+  module ParallelResultMerger
+  module_function
+
+    #
+    # `ResultMerger.merge_and_store` across `processes` forked workers. One
+    # worker hands straight back to `ResultMerger`, so the default `collate`
+    # takes exactly the path it always has and never reaches this module's
+    # machinery at all.
+    #
+    def merge_and_store(*file_paths, processes:, ignore_timeout: false)
+      return ResultMerger.merge_and_store(*file_paths, ignore_timeout: ignore_timeout) if processes < 2
+
+      result = merge_results(*file_paths, processes: processes, ignore_timeout: ignore_timeout)
+      ResultMerger.store_result(result) if result
+      result
+    end
+
+    #
+    # `ResultMerger.merge_results` across `processes` forked workers, merging
+    # in this process instead whenever the fan-out did not produce a complete
+    # merge — a runtime that cannot fork, nothing worth splitting, or a worker
+    # that died. The result is the same either way; only the time it took to
+    # get there differs.
+    #
+    def merge_results(*file_paths, processes:, ignore_timeout: false)
+      tracked_files = Set.new
+      pair = absorb_results(file_paths, processes: processes, ignore_timeout: ignore_timeout,
+                                        tracked_files: tracked_files)
+      # A nil pair means nothing was fanned out at all, so the serial path
+      # is exactly `ResultMerger.merge_results` — delegate rather than
+      # re-implement its collector wiring.
+      return ResultMerger.merge_results(*file_paths, ignore_timeout: ignore_timeout) unless pair
+
+      command_names, coverage = pair
+      ResultMerger.create_result(command_names, coverage, tracked_files: tracked_files)
+    end
+
+    #
+    # `ResultMerger.absorb_results` across at most `processes` forked
+    # workers: same arguments, same `[command_names, coverage]` return.
+    #
+    # The tracked paths a worker's slice carried come back with its payload
+    # rather than through a collector block, since the block a serial absorb
+    # takes would be mutating a Set in the wrong process.
+    #
+    # @return [Array(Array<String>, Hash), nil] the pair
+    #   `ResultMerger.create_result` consumes, or nil when the work could not
+    #   be fanned out and the caller should merge in this process instead.
+    #
+    def absorb_results(file_paths, processes:, ignore_timeout: false, tracked_files: Set.new)
+      # One worker folds the whole list anyway, and one file is a fold of
+      # one — in both cases the fork and the round trip are pure overhead.
+      return nil if processes < 2 || file_paths.size < 2
+      # The portable feature test, and the one the rest of the ecosystem uses.
+      # CRuby leaves `fork` undefined on Windows; JRuby and TruffleRuby cannot
+      # fork on the JVM and deliberately answer false here so libraries can
+      # detect that without rescuing an exception — TruffleRuby's compatibility
+      # guide names this as the correct check. They do still define
+      # `Kernel#fork` and raise `NotImplementedError` from it, so probing that
+      # instead would answer true and send them down the fan-out.
+      return nil unless Process.respond_to?(:fork)
+
+      fan_out(chunk(file_paths, processes), ignore_timeout: ignore_timeout, tracked_files: tracked_files)
+    end
+
+    # Contiguous slices whose sizes differ by at most one, so no worker is
+    # left folding twice its share while the others idle. There are never
+    # more slices than files: asking for more processes than there are
+    # resultsets just gives one resultset per process.
+    def chunk(file_paths, processes)
+      groups = [processes, file_paths.size].min
+      base, remainder = file_paths.size.divmod(groups)
+      remaining = file_paths.dup
+
+      Array.new(groups) { |index| remaining.shift(base + (index < remainder ? 1 : 0)) }
+    end
+
+    # A `fork` that fails here raises, and is left to. `absorb_results` has
+    # already excluded the runtimes that never fork, so what remains is the OS
+    # refusing a process we expected to get — EAGAIN at RLIMIT_NPROC, ENOMEM
+    # under memory pressure. That says something is wrong with the machine
+    # rather than with the merge, and quietly absorbing it would hide it.
+    def fan_out(chunks, ignore_timeout:, tracked_files: Set.new)
+      workers = spawn_workers(chunks, ignore_timeout: ignore_timeout)
+      payloads = collect(workers)
+      return nil unless payloads
+
+      payloads.each { |(_pair, tracked)| tracked_files.merge(tracked) }
+      ResultMerger.merge_coverage(*payloads.map(&:first))
+    end
+
+    def spawn_workers(chunks, ignore_timeout:)
+      workers = [] #: Array[Hash[Symbol, untyped]]
+
+      chunks.each do |chunk|
+        workers << spawn_worker(chunk, ignore_timeout: ignore_timeout)
+      rescue StandardError
+        abandon(workers)
+        raise
+      end
+
+      workers
+    end
+
+    def abandon(workers)
+      workers.each do |worker|
+        worker[:reader].close
+        succeeded?(worker[:pid])
+      end
+    end
+
+    # `fork` itself can fail (EAGAIN under a process limit). The caller
+    # cleans up the workers it knows about, but this pipe is ours: the
+    # parent's writer end always closes, and the reader closes too when
+    # no child was spawned to feed it. Steep cannot type body locals
+    # inside an ensure, hence the ignore markers; the safe navigation
+    # keeps the cleanup well-defined when `IO.pipe` itself raised.
+    def spawn_worker(chunk, ignore_timeout:)
+      reader, writer = IO.pipe
+      pid = fork { run_in_child(reader, writer, chunk, ignore_timeout) }
+      {pid: pid, reader: reader}
+    ensure
+      # steep:ignore:start
+      writer&.close
+      reader&.close unless pid
+      # steep:ignore:end
+    end
+
+    # Everything the child does. `exit!` rather than `exit` because it must
+    # never fall through to the collating process's inherited `at_exit`
+    # handlers — SimpleCov's own report generation included.
+    def run_in_child(reader, writer, chunk, ignore_timeout)
+      reader.close
+      exit!(run_worker(chunk, writer, ignore_timeout: ignore_timeout))
+    end
+
+    # The body of a worker: merge the slice, ship it back, and report the exit
+    # status the child should terminate with. Kept free of the exit itself so
+    # it can be exercised in-process.
+    #
+    # The slice's tracked paths travel with the pair because the parent needs
+    # the union across every worker to know what nothing loaded.
+    def run_worker(chunk, writer, ignore_timeout:)
+      tracked_files = Set.new
+      pair = ResultMerger.absorb_results(chunk, ignore_timeout: ignore_timeout,
+                                         &ResultMerger::UnloadedFiles.collector(tracked_files))
+      Marshal.dump([pair, tracked_files.to_a], writer)
+      writer.close
+      0
+    rescue StandardError => e
+      warn "[SimpleCov]: parallel merge worker failed: #{e.class}: #{e.message}" if SimpleCov.print_errors
+      1
+    end
+
+    # Deserializes on a thread per worker so every pipe is drained while the
+    # workers are still writing. A payload larger than the pipe buffer would
+    # otherwise block its worker mid-write, and the parent would block
+    # reaping a worker that can never finish.
+    #
+    # Returns nil if any worker failed, so the caller can fall back to the
+    # serial fold rather than report a subset of the resultsets as the whole.
+    def collect(workers)
+      payloads = drain(workers)
+      failed = workers.count { |worker| !succeeded?(worker[:pid]) }
+      return payloads if failed.zero? && payloads.all?
+
+      warn_about_failed_workers(failed, workers.size)
+      nil
+    ensure
+      workers.each { |worker| worker[:reader].close }
+    end
+
+    def drain(workers)
+      workers.map { |worker| Thread.new { read_payload(worker[:reader]) } }.map(&:value)
+    end
+
+    def read_payload(reader)
+      # The writer is a fork of this very process and the pipe never leaves
+      # it, so this is our own data coming back through our own kernel
+      # buffer, not input. A worker that died mid-write leaves the stream
+      # truncated, which Marshal reports by raising rather than returning.
+      # RBS types `Marshal.load`'s source as `_Source`, which IO satisfies
+      # structurally but not nominally.
+      # steep:ignore:start
+      Marshal.load(reader) # rubocop:disable Security/MarshalLoad
+      # steep:ignore:end
+    rescue StandardError
+      nil
+    end
+
+    def succeeded?(pid)
+      _pid, status = Process.wait2(pid)
+      status.success?
+    rescue SystemCallError
+      # Errno::ECHILD — nothing left to reap, so there is no status to judge
+      # this worker's slice by and we have to assume it did not finish.
+      false
+    end
+
+    def warn_about_failed_workers(failed, total)
+      return unless SimpleCov.print_errors
+
+      warn "[SimpleCov]: parallel merge did not complete (#{failed} of #{total} workers failed); " \
+           "merging the resultsets in this process instead."
+    end
+  end
+end

data/lib/simplecov/report_deferral.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# The clobber-prevention backstop: an empty process stands down instead
+# of formatting over a fresher report a sibling produced. Split from
+# exit_handling.rb, which orchestrates the at_exit flow that consults
+# this. See issue #581.
+module SimpleCov
+  class << self
+    # Returns true when our process has no coverage data to contribute
+    # (after the resultset merge) and a newer report already exists on
+    # disk. Typically fires when `SimpleCov.start` ran in a parent
+    # process that shelled out to the test runner. See issue #581.
+    def defer_to_existing_report?
+      return false unless existing_report_newer_than_us?
+
+      res = result
+      empty = res.nil? || res.files.empty?
+      warn_about_deferred_report if empty
+      empty
+    end
+
+    # `.last_run.json` only exists after fully successful runs, so alone
+    # it left the backstop inert when the child run failed — the case
+    # where clobbering its report hurts most. The report stamp is
+    # touched by every formatting process regardless of exit status. The
+    # rescue covers a file vanishing mid-at_exit (`rm -rf coverage`).
+    def existing_report_newer_than_us?
+      return false unless process_start_time
+
+      [SimpleCov::LastRun.last_run_path, SimpleCov::ReportStamp.path].any? do |path|
+        File.mtime(path) > process_start_time
+      rescue SystemCallError
+        false
+      end
+    end
+
+    def warn_about_deferred_report
+      return unless print_errors
+
+      ExitCodes.print_error SimpleCov::Color.colorize(
+        "Skipping SimpleCov report — this process tracked no application code and a newer " \
+        "report already exists at #{coverage_path}. This usually means SimpleCov.start ran in a " \
+        "parent process (e.g. a Rakefile or Rails' Bundler.require) that shelled out to the test " \
+        "runner. See https://github.com/simplecov-ruby/simplecov/issues/581.",
+        :yellow
+      )
+    end
+  end
+end