Warn when coverage.json is clobbered by a concurrent process

Record the time each JSONFormatter process loads as `PROCESS_START_TIME`
and, before writing `coverage.json`, compare the existing file's
`meta.timestamp` against it. If the file on disk was written *after*
this process started, another test run likely produced it — warn that
the overwrite will lose their data and point at `SimpleCov::ResultMerger`.

The check is zero-cost for the common case (no existing file, or an
older one from a prior sequential run) and has no state beyond the
existing `meta.timestamp` field.

Sequential re-runs do not warn: the prior file's timestamp predates
the new process's start. parallel_tests-style setups, where workers
share `PROCESS_START_TIME` but finish at different times, do warn
once the later writers reach format time.

Author: sferik

lib/simplecov/formatter/json_formatter.rb

@@ -2,12 +2,20 @@
 
 require_relative "json_formatter/result_hash_formatter"
 require "json"
+require "time"
 
 module SimpleCov
   module Formatter
     class JSONFormatter
       FILENAME = "coverage.json"
 
+      # Captured when the class loads, which is close enough to "when this
+      # Ruby process started tracking coverage". Used to detect whether an
+      # existing coverage.json was written by a sibling process running
+      # concurrently (see #warn_if_concurrent_overwrite).
+      PROCESS_START_TIME = Time.now
+      private_constant :PROCESS_START_TIME
+
       def initialize(silent: false)
         @silent = silent
       end
@@ -17,13 +25,38 @@ def self.build_hash(result)
       end
 
       def format(result)
-        json = JSON.pretty_generate(self.class.build_hash(result))
-        File.write(File.join(SimpleCov.coverage_path, FILENAME), json)
+        path = File.join(SimpleCov.coverage_path, FILENAME)
+        warn_if_concurrent_overwrite(path)
+        File.write(path, JSON.pretty_generate(self.class.build_hash(result)))
         puts output_message(result) unless @silent
       end
 
     private
 
+      # 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)
+        existing_ts = existing_timestamp(path) or return
+        return unless existing_ts > PROCESS_START_TIME
+
+        warn "simplecov: #{path} was written at #{existing_ts.iso8601} — after " \
+             "this process started at #{PROCESS_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
+
       def output_message(result)
         "JSON Coverage report generated for #{result.command_name} to #{SimpleCov.coverage_path}. " \
           "#{result.covered_lines} / #{result.total_lines} LOC (#{result.covered_percent.round(2)}%) covered."

spec/json_formatter_spec.rb

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
 
 require "helper"
+require "fileutils"
 
 describe SimpleCov::Formatter::JSONFormatter do
   subject { described_class.new(silent: true) }
 
   let(:fixed_time) { Time.new(2024, 1, 1, 0, 0, 0, "+00:00") }
 
+  # Prevent stale coverage.json from prior tests from triggering the
+  # concurrent-overwrite warning.
+  before { FileUtils.rm_f("tmp/coverage/coverage.json") }
+
   let(:result) do
     res = SimpleCov::Result.new({
                                   source_fixture("json/sample.rb") => {"lines" => [
@@ -305,6 +310,57 @@
         expect(json_output).to eq(json_result("sample_groups"))
       end
     end
+
+    context "when an existing coverage.json was written after this process started" do
+      let(:coverage_path) { "tmp/coverage/coverage.json" }
+      let(:future_timestamp) { (Time.now + 3600).iso8601 }
+
+      before do
+        FileUtils.mkdir_p("tmp/coverage")
+        File.write(coverage_path, JSON.generate(meta: {timestamp: future_timestamp}))
+      end
+
+      it "warns that a concurrent process may have written it" do
+        stderr = capture_stderr { subject.format(result) }
+
+        expect(stderr).to include("simplecov:")
+        expect(stderr).to include(future_timestamp)
+        expect(stderr).to include("concurrent test run")
+      end
+
+      it "still writes the new file" do
+        capture_stderr { subject.format(result) }
+
+        expect(json_output.fetch("meta").fetch("timestamp")).to eq(fixed_time.iso8601)
+      end
+    end
+
+    context "when an existing coverage.json predates this process" do
+      before do
+        FileUtils.mkdir_p("tmp/coverage")
+        past_timestamp = (Time.now - 3600).iso8601
+        File.write("tmp/coverage/coverage.json", JSON.generate(meta: {timestamp: past_timestamp}))
+      end
+
+      it "does not warn" do
+        stderr = capture_stderr { subject.format(result) }
+
+        expect(stderr).to be_empty
+      end
+    end
+
+    context "when the existing coverage.json is malformed" do
+      before do
+        FileUtils.mkdir_p("tmp/coverage")
+        File.write("tmp/coverage/coverage.json", "not-json")
+      end
+
+      it "does not warn or raise" do
+        stderr = capture_stderr { subject.format(result) }
+
+        expect(stderr).to be_empty
+      end
+    end
   end
 
   def enable_branch_coverage