rspec-tracer 1.2.2 → 2.0.0.pre.1

data/lib/rspec_tracer.rb

@@ -10,73 +10,109 @@ require 'json'
 require 'pathname'
 require 'set'
 
-require_relative 'rspec_tracer/coverage_merger'
-require_relative 'rspec_tracer/coverage_reporter'
-require_relative 'rspec_tracer/coverage_writer'
 require_relative 'rspec_tracer/defaults'
+require_relative 'rspec_tracer/engine'
 require_relative 'rspec_tracer/example'
-require_relative 'rspec_tracer/html_reporter/reporter'
+# Reporters must load before load_config so the Configuration DSL's
+# `add_reporter` can validate symbol names against
+# `Reporters::Registry::BUILT_INS` when a user `.rspec-tracer` calls
+# it at configure time.
+require_relative 'rspec_tracer/reporters/base'
+require_relative 'rspec_tracer/reporters/payload_builder'
+require_relative 'rspec_tracer/reporters/coverage_json_reporter'
+require_relative 'rspec_tracer/reporters/json_reporter'
+require_relative 'rspec_tracer/reporters/terminal_reporter'
+require_relative 'rspec_tracer/reporters/html_reporter'
+require_relative 'rspec_tracer/reporters/registry'
 require_relative 'rspec_tracer/load_config'
-require_relative 'rspec_tracer/remote_cache/cache'
-require_relative 'rspec_tracer/report_generator'
-require_relative 'rspec_tracer/report_merger'
-require_relative 'rspec_tracer/report_writer'
-require_relative 'rspec_tracer/rspec_reporter'
-require_relative 'rspec_tracer/rspec_runner'
-require_relative 'rspec_tracer/ruby_coverage'
-require_relative 'rspec_tracer/runner'
+# RemoteCache is loaded lazily from its Rakefile shim (user-driven),
+# not at gem-load time. The user-facing tasks `rspec_tracer:remote_cache:*`
+# pull in `lib/rspec_tracer/remote_cache.rb` when the user's Rakefile
+# loads the shim. Test-suite runs that never invoke a cache task pay
+# zero load cost for aws/git subshell code.
+require_relative 'rspec_tracer/rspec/installation'
+require_relative 'rspec_tracer/rspec/parallel_tests'
 require_relative 'rspec_tracer/source_file'
 require_relative 'rspec_tracer/time_formatter'
 require_relative 'rspec_tracer/version'
 
+# Top-level entry point. Drives the lifecycle:
+#
+#   RSpecTracer.start
+#     -> RSpec::Installation.install!  (prepend RunnerHook + ReporterHook)
+#     -> setup_coverage                (::Coverage.start unless SimpleCov owns it)
+#     -> setup_rails                   (detect ::Rails::VERSION)
+#     -> Engine.new.setup              (observers + cache load + filter decisions)
+#
+#   at_exit_behavior (installed via `at_exit` elsewhere in the boot
+#   flow) runs the finalize stack: Engine#finalize writes the 13-file
+#   snapshot via Storage::JsonBackend, Reporters::CoverageJsonReporter
+#   writes coverage.json (single owner, replacing the 1.x
+#   CoverageReporter + CoverageWriter pair retired in 2.0),
+#   ParallelTests#finalize! merges per-worker caches on the last worker.
 module RSpecTracer
   class << self
+    # Internal attribute.
+    # @api private
     attr_accessor :running, :pid, :no_examples, :duplicate_examples
 
+    # Boot the tracer. Idempotent — safe to call multiple times in a
+    # single process (subsequent calls return without re-installing
+    # hooks). Drives the lifecycle:
+    #
+    #   * Installs the RSpec runner / reporter prepend chain.
+    #   * Starts `::Coverage` unless SimpleCov already owns it.
+    #   * Detects Rails (memoized in `RSpecTracer.rails?`).
+    #   * Builds the {RSpecTracer::Engine} and installs observers.
+    #
+    # Must be called BEFORE any application code loads so the boot
+    # set captured by `Coverage.peek_result` is empty. With SimpleCov,
+    # call `SimpleCov.start` first; rspec-tracer warns at boot when
+    # SimpleCov is loaded but not started.
+    #
+    # @return [void]
     def start
+      return if defined?(@started) && @started
+
       RSpecTracer.running = false
       RSpecTracer.pid = Process.pid
-
-      return if RUBY_ENGINE == 'jruby' && !valid_jruby_opts?
+      @run_started_at = ::Time.now.utc
+      @run_monotonic_start = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      @started = true
 
       RSpecTracer.logger.debug "Started RSpec tracer (pid: #{RSpecTracer.pid})"
 
-      parallel_tests_setup
-      initial_setup
-    end
-
-    # rubocop:disable Metrics/AbcSize
-    def filter_examples
-      groups = Set.new
-      to_run = Hash.new { |hash, group| hash[group] = [] }
-
-      RSpec.world.filtered_examples.each_pair do |example_group, examples|
-        examples.each do |example|
-          tracer_example = RSpecTracer::Example.from(example)
-          example_id = tracer_example[:example_id]
-          example.metadata[:rspec_tracer_example_id] = example_id
-
-          if runner.run_example?(example_id)
-            run_reason = runner.run_example_reason(example_id)
-            tracer_example[:run_reason] = run_reason
-            example.metadata[:description] = "#{example.description} (#{run_reason})"
-
-            to_run[example_group] << example
-            groups << example.example_group.parent_groups.last
-
-            runner.register_example(tracer_example)
-          else
-            runner.on_example_skipped(example_id)
-          end
-        end
-      end
-
-      runner.deregister_duplicate_examples
+      warn_on_simplecov_load_order_mistake
 
-      [to_run, groups.to_a]
+      @parallel_tests = RSpecTracer::RSpec::ParallelTests.active?
+      RSpecTracer::RSpec::ParallelTests.setup! if parallel_tests?
+      initial_setup
     end
-    # rubocop:enable Metrics/AbcSize
 
+    # SimpleCov load-order is part of the documented contract -
+    # SimpleCov.start MUST run before RSpecTracer.start when both are
+    # used together (see README §SimpleCov interop). When the user
+    # has SimpleCov loaded but not started, we'd silently call
+    # ::Coverage.start ourselves and SimpleCov's later setup would
+    # bolt onto a Coverage already in flight, with the user's
+    # add_filter calls applied after rspec-tracer started consuming
+    # data. Surface the load-order mistake at start time so the user
+    # gets a one-line warning instead of mysteriously-broken
+    # coverage output.
+    def warn_on_simplecov_load_order_mistake
+      return unless defined?(::SimpleCov)
+      return if ::SimpleCov.respond_to?(:running) && ::SimpleCov.running
+
+      RSpecTracer.logger.warn(
+        'SimpleCov is loaded but not started. ' \
+        'Call SimpleCov.start before RSpecTracer.start so the ' \
+        'tracer respects SimpleCov\'s filter chain. See README ' \
+        'section "Working with SimpleCov".'
+      )
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
     def at_exit_behavior
       return unless RSpecTracer.pid == Process.pid && RSpecTracer.running
 
@@ -84,141 +120,69 @@ module RSpecTracer
 
       run_exit_tasks
     ensure
-      FileUtils.rm_f(RSpecTracer.lock_file) if parallel_tests_last_process?
+      if RSpecTracer::RSpec::ParallelTests.active? &&
+          RSpecTracer::RSpec::ParallelTests.last_process?
+        RSpecTracer::RSpec::ParallelTests.remove_lock_file!
+      end
 
       RSpecTracer.running = false
     end
 
-    def start_example_trace
-      trace_point.enable
-    end
-
-    def stop_example_trace(example_id)
-      trace_point.disable
-
-      @examples_traced_files[example_id] = @traced_files
-      @traced_files = Set.new
-    end
-
-    def runner
-      @runner if defined?(@runner)
-    end
-
-    def coverage_reporter
-      @coverage_reporter if defined?(@coverage_reporter)
-    end
-
-    def report_writer
-      @report_writer if defined?(@report_writer)
-    end
-
-    def coverage_merger
-      @coverage_merger if defined?(@coverage_merger)
-    end
-
-    def report_merger
-      @report_merger if defined?(@report_merger)
-    end
-
-    def trace_point
-      @trace_point if defined?(@trace_point)
-    end
-
-    def traced_files
-      @traced_files if defined?(@traced_files)
-    end
-
-    def examples_traced_files
-      @examples_traced_files if defined?(@examples_traced_files)
+    # The current {RSpecTracer::Engine} instance, or nil if
+    # {.start} hasn't been called yet.
+    #
+    # @return [RSpecTracer::Engine, nil]
+    def engine
+      @engine if defined?(@engine)
     end
 
+    # True if SimpleCov was loaded AND running at the time
+    # {.start} was invoked. Determines whether rspec-tracer
+    # owns `::Coverage.start` itself (false) or defers to
+    # SimpleCov's coverage lifecycle (true).
+    #
+    # @return [Boolean]
     def simplecov?
       defined?(@simplecov) && @simplecov == true
     end
 
+    # True if `parallel_tests` is in use (detected via
+    # `ParallelTests.active?` at {.start} time). Affects
+    # cache + report directory scoping (per-worker dirs)
+    # and finalize-time merging.
+    #
+    # @return [Boolean]
     def parallel_tests?
       defined?(@parallel_tests) && @parallel_tests == true
     end
 
-    private
-
-    def valid_jruby_opts?
-      require 'jruby'
-
-      return true if Java::OrgJruby::RubyInstanceConfig.FULL_TRACE_ENABLED &&
-        JRuby.runtime.object_space_enabled?
-
-      RSpecTracer.logger.warn <<-WARN.strip.gsub(/\s+/, ' ')
-        RSpec Tracer is not running as it requires debug and object space enabled. Use
-        command line options "--debug" and "-X+O" or set the "debug.fullTrace=true" and
-        "objectspace.enabled=true" options in your .jrubyrc file. You can also use
-        JRUBY_OPTS="--debug -X+O".
-      WARN
-
-      false
+    # True if Rails is loaded in this process (detected via
+    # `defined?(::Rails::VERSION)` at {.start} time). Memoized;
+    # subsequent Rails activations within the same run are not
+    # re-detected. Drives the auto-installation of Rails-side
+    # observers (template + AR notification subscribers).
+    #
+    # @return [Boolean]
+    def rails?
+      defined?(@rails) && @rails == true
     end
 
-    def initial_setup
-      unless setup_rspec?
-        RSpecTracer.logger.error 'Could not find a running RSpec process'
+    private
 
-        return
-      end
+    # Internal method on the tracer pipeline.
+    # @api private
+    def initial_setup
+      RSpecTracer::RSpec::Installation.install!
 
       setup_coverage
-      setup_trace_point
+      setup_rails
 
-      @runner = RSpecTracer::Runner.new
-      @coverage_reporter = RSpecTracer::CoverageReporter.new
-      @report_writer = RSpecTracer::ReportWriter.new(RSpecTracer.cache_path, @runner.reporter)
-    end
-
-    def parallel_tests_setup
-      @parallel_tests = !(ENV.fetch('TEST_ENV_NUMBER', nil) && ENV.fetch('PARALLEL_TEST_GROUPS', nil)).nil?
-
-      return unless parallel_tests?
-
-      require 'parallel_tests' unless defined?(ParallelTests)
-
-      @coverage_merger = RSpecTracer::CoverageMerger.new
-      @report_merger = RSpecTracer::ReportMerger.new
-    rescue LoadError => e
-      RSpecTracer.logger.error "Failed to load parallel tests (Error: #{e.message})"
-    ensure
-      track_parallel_tests_test_env_number
-    end
-
-    def track_parallel_tests_test_env_number
-      return unless parallel_tests?
-
-      File.open(RSpecTracer.lock_file, File::RDWR | File::CREAT, 0o644) do |f|
-        f.flock(File::LOCK_EX)
-
-        test_num = [f.read.to_i, ENV['TEST_ENV_NUMBER'].to_i].max
-
-        f.rewind
-        f.write("#{test_num}\n")
-        f.flush
-        f.truncate(f.pos)
-      end
-    end
-
-    def setup_rspec?
-      runners = ObjectSpace.each_object(::RSpec::Core::Runner) do |runner|
-        runner_clazz = runner.singleton_class
-        clazz = RSpecTracer::RSpecRunner
-
-        runner_clazz.prepend(clazz) unless runner_clazz.ancestors.include?(clazz)
-
-        reporter_clazz = runner.configuration.reporter.singleton_class
-        clazz = RSpecTracer::RSpecReporter
-
-        reporter_clazz.prepend(clazz) unless reporter_clazz.ancestors.include?(clazz)
-      end
-
-      runners.positive?
+      @engine = RSpecTracer::Engine.new(configuration: RSpecTracer)
+      @engine.setup
     end
 
+    # Internal method on the tracer pipeline.
+    # @api private
     def setup_coverage
       @simplecov = defined?(SimpleCov) && SimpleCov.running
 
@@ -229,244 +193,131 @@ module RSpecTracer
       ::Coverage.start
     end
 
-    def setup_trace_point
-      @traced_files = Set.new
-      @examples_traced_files = {}
-
-      @trace_point = TracePoint.new(:call) do |tp|
-        RSpecTracer.traced_files << tp.path if tp.path.start_with?(RSpecTracer.root)
-      end
+    # Detects Rails by the presence of `::Rails::VERSION`. Users who
+    # require `rspec_tracer/rails` transitively load the Railtie (when
+    # Rails is also present); this method only sets the flag consumed
+    # by `RSpecTracer.rails?`. Safe when Rails is absent - the
+    # `defined?` guard returns nil, flag stays false.
+    def setup_rails
+      @rails = defined?(::Rails::VERSION) && !::Rails::VERSION.nil?
     end
 
+    # Internal method on the tracer pipeline.
+    # @api private
     def run_exit_tasks
       if RSpecTracer.no_examples
         RSpecTracer.logger.info 'Skipped reports generation since all examples were filtered out'
       else
-        generate_reports
+        snapshot = run_finalize
+        # Under parallel_tests, defer reporter emission until
+        # last-process finalize merges per-worker snapshots into the
+        # top-level cache. Each worker still persists its per-worker
+        # snapshot for the merge to consume. Earlier behavior had every
+        # worker emit reporters into rspec_tracer_report/parallel_tests_N/
+        # and purge_worker_dirs! removed those dirs - leaving the user
+        # with no usable terminal/JSON/HTML output. Now reporters fire
+        # ONCE at the merged top-level location.
+        emit_reporters(snapshot) if snapshot && !parallel_tests?
       end
 
-      simplecov? ? run_simplecov_exit_task : run_coverage_exit_task
-
-      run_parallel_tests_exit_tasks
-    end
-
-    def generate_reports
-      RSpecTracer.logger.debug "RSpec tracer is generating reports (pid: #{RSpecTracer.pid})"
-
-      process_dependency
-      process_coverage
+      emit_coverage_json
 
-      RSpecTracer::ReportGenerator.new(runner.reporter, runner.cache).generate_report
-      report_writer.write_report
-      RSpecTracer::HTMLReporter::Reporter.new(RSpecTracer.report_path, runner.reporter).generate_report
+      RSpecTracer::RSpec::ParallelTests.finalize! if parallel_tests?
     end
 
-    def process_dependency
+    # Engine-owned finalize path. Writes the 15-file JSON cache via
+    # Storage::JsonBackend. Per-example coverage deltas live on the
+    # Engine; 2.0 retired the CoverageReporter mid-flow piece (the
+    # legacy `coverage_reporter.generate_final_examples_coverage +
+    # merge_coverage(engine.merge_skipped_coverage(...))` is now folded
+    # into Reporters::CoverageJsonReporter#generate, which fires from
+    # `emit_coverage_json` after this method returns).
+    def run_finalize
       starting = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
-      runner.register_interrupted_examples
-      runner.register_deleted_examples
-      runner.register_dependency(coverage_reporter.examples_coverage)
-      runner.register_traced_dependency(@examples_traced_files)
+      snapshot = engine.finalize
 
       ending = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       elapsed = RSpecTracer::TimeFormatter.format_time(ending - starting)
 
-      RSpecTracer.logger.debug "RSpec tracer processed dependency (took #{elapsed})"
-    end
-
-    def process_coverage
-      starting = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-      coverage_reporter.generate_final_examples_coverage
-      coverage_reporter.merge_coverage(runner.generate_missed_coverage)
-      runner.register_examples_coverage(coverage_reporter.examples_coverage)
-
-      ending = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      elapsed = RSpecTracer::TimeFormatter.format_time(ending - starting)
-
-      RSpecTracer.logger.debug "RSpec tracer processed coverage (took #{elapsed})"
-    end
-
-    def run_simplecov_exit_task
-      coverage_clazz = ::Coverage.singleton_class
-      clazz = RSpecTracer::RubyCoverage
-      coverage_clazz.prepend(clazz) unless coverage_clazz.ancestors.include?(clazz)
-
-      RSpecTracer.logger.debug 'SimpleCov will now generate coverage report (<3 RSpec tracer)'
-
-      coverage_reporter.record_coverage if RSpecTracer.no_examples
-    end
-
-    def run_coverage_exit_task
-      starting = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-      coverage_reporter.record_coverage if RSpecTracer.no_examples
-      coverage_reporter.generate_final_coverage
-
-      file_name = File.join(RSpecTracer.coverage_path, 'coverage.json')
-      coverage_writer = RSpecTracer::CoverageWriter.new(file_name, coverage_reporter)
-
-      coverage_writer.write_report
-
-      ending = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-      coverage_writer.print_stats(ending - starting)
-    end
-
-    def run_parallel_tests_exit_tasks
-      return unless parallel_tests_executed?
-
-      merge_parallel_tests_reports
-      write_parallel_tests_merged_report
-      merge_parallel_tests_coverage_reports
-      write_parallel_tests_coverage_report
-      purge_parallel_tests_reports
-    end
-
-    def merge_parallel_tests_reports
-      return unless parallel_tests_executed?
-
-      starting = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      reports_dir = []
-
-      parallel_tests_peer_dirs(File.dirname(RSpecTracer.cache_path)).each do |cache_dir|
-        run_id = JSON.parse(File.read(File.join(cache_dir, 'last_run.json'), encoding: 'UTF-8'))['run_id']
-
-        reports_dir << File.join(cache_dir, run_id)
-      end
-
-      report_merger.merge(reports_dir)
-
-      ending = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      elapsed = RSpecTracer::TimeFormatter.format_time(ending - starting)
-
-      RSpecTracer.logger.debug "RSpec tracer merged parallel tests reports (took #{elapsed})"
-    end
-
-    def write_parallel_tests_merged_report
-      return unless parallel_tests_executed?
-
-      report_dir = File.dirname(RSpecTracer.cache_path)
-
-      RSpecTracer::ReportWriter.new(report_dir, report_merger).write_report
-
-      report_dir = File.dirname(RSpecTracer.report_path)
-
-      RSpecTracer::HTMLReporter::Reporter.new(report_dir, report_merger).generate_report
-    end
-
-    def merge_parallel_tests_coverage_reports
-      return unless parallel_tests_executed? && !simplecov?
-
-      starting = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-      reports_dir = parallel_tests_peer_dirs(File.dirname(RSpecTracer.coverage_path))
-
-      coverage_merger.merge(reports_dir)
-
-      ending = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      elapsed = RSpecTracer::TimeFormatter.format_time(ending - starting)
-
-      RSpecTracer.logger.debug "RSpec tracer merged parallel tests coverage reports (took #{elapsed})"
-    end
-
-    def write_parallel_tests_coverage_report
-      return unless parallel_tests_executed? && !simplecov?
-
-      starting = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-      coverage_path = File.dirname(RSpecTracer.coverage_path)
-      file_name = File.join(coverage_path, 'coverage.json')
-      coverage_writer = RSpecTracer::CoverageWriter.new(file_name, coverage_merger)
-
-      coverage_writer.write_report
-
-      ending = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-      coverage_writer.print_stats(ending - starting)
-    end
-
-    def purge_parallel_tests_reports
-      return unless parallel_tests_executed?
-
-      [RSpecTracer.cache_path, RSpecTracer.coverage_path, RSpecTracer.report_path].each do |path|
-        parallel_tests_peer_dirs(File.dirname(path)).each do |worker_dir|
-          FileUtils.rm_rf(worker_dir)
-        end
-      end
-    end
-
-    # Returns every `parallel_tests_*` subdirectory directly under
-    # `base_path`. Used by the parallel_tests merge + purge paths.
-    #
-    # Earlier patches iterated `1..ENV['PARALLEL_TEST_GROUPS'].to_i`
-    # to construct dir names, but parallel_tests's own runner sets
-    # PARALLEL_TEST_GROUPS to the user-requested process count
-    # (`Parallel.processor_count` by default), NOT the actual worker
-    # count. When num_processes < spawned_worker_count, the upper
-    # bound was too small: peer caches with TEST_ENV_NUMBER above the
-    # bound were silently dropped from the merge AND left behind by
-    # the purge. PR #101's commit message documented this gem
-    # behaviour for `last_process?` detection but did not extend the
-    # fix to the iteration call-sites; this method closes that gap.
-    # Globbing the actual filesystem state is robust to the env
-    # discrepancy regardless of how the gem partitions specs.
-    def parallel_tests_peer_dirs(base_path)
-      Dir.glob(File.join(base_path, 'parallel_tests_*')).select do |path|
-        File.directory?(path)
-      end
-    end
-
-    def parallel_tests_executed?
-      return false unless parallel_tests? && parallel_tests_last_process?
-
-      ParallelTests.wait_for_other_processes_to_finish
-
-      true
-    end
-
-    # Elects the worker that performs the per-run merge. Delegates to
-    # `::ParallelTests.first_process?`, which returns true iff
-    # `TEST_ENV_NUMBER.to_i <= 1` — i.e. for exactly one worker
-    # (TEST_ENV_NUMBER == '' or '1'), regardless of how many workers
-    # were actually spawned vs. how many CPUs the runner reports.
-    #
-    # Two previously attempted approaches do NOT work here:
-    #
-    #   1. The lock-file scheme below (each worker writing its
-    #      TEST_ENV_NUMBER to `rspec_tracer.lock` via
-    #      `track_parallel_tests_test_env_number`; last_process picked
-    #      the max) deadlocked under slow CI: worker 1 could finish
-    #      its examples before worker 2 even loaded spec_helper,
-    #      observe itself as the max, and enter
-    #      `::ParallelTests.wait_for_other_processes_to_finish`
-    #      concurrently with worker 2's own self-election — both
-    #      workers then spun on each other's pid.
-    #
-    #   2. `::ParallelTests.last_process?` compares TEST_ENV_NUMBER
-    #      against PARALLEL_TEST_GROUPS, which parallel_rspec sets to
-    #      the CPU-based *intended* process count — NOT the actual
-    #      worker count. When spec files < CPU count (common), no
-    #      TEST_ENV_NUMBER ever matches PARALLEL_TEST_GROUPS and the
-    #      merge is silently skipped.
-    #
-    # `first_process?` avoids both: set by the parent at spawn,
-    # immutable thereafter, and identifies exactly one worker
-    # regardless of CPU count. The elected worker still calls
-    # `wait_for_other_processes_to_finish` before merging so peer
-    # caches are guaranteed on disk.
-    #
-    # `track_parallel_tests_test_env_number` and the lock-file
-    # cleanup in `at_exit_behavior` are retained for backward
-    # compatibility with users who observe `rspec_tracer.lock` /
-    # set `RSPEC_TRACER_LOCK_FILE`; the file is still written and
-    # removed but is no longer consulted.
-    def parallel_tests_last_process?
-      return false unless parallel_tests?
-      return false unless defined?(::ParallelTests)
-
-      ::ParallelTests.first_process?
+      RSpecTracer.logger.debug "RSpec tracer persisted cache (took #{elapsed})"
+      snapshot
+    rescue StandardError => e
+      # Graceful-degradation contract per ARCHITECTURE.md
+      # section Cache corruption recovery: never propagate storage errors
+      # into the user's test suite. Read-only cache_path, disk-full
+      # mid-write, permission flips between runs - log and skip
+      # report emission. The caller (run_exit_tasks) checks for nil
+      # before calling emit_reporters; coverage / parallel_tests
+      # finalize paths run independently downstream.
+      RSpecTracer.logger.warn(
+        "rspec-tracer: cache persistence failed (#{e.class}: #{e.message}); " \
+        'skipping report generation. Verify cache_path is writable.'
+      )
+      nil
+    end
+
+    # Fire the configured reporters against the persisted
+    # Snapshot. Fires per-worker under parallel_tests (same cadence as
+    # coverage.json emission); each worker produces its own report.json
+    # under its per-worker report_dir. The Registry rescues every
+    # reporter individually, so a buggy reporter warns and continues -
+    # never propagates a non-zero exit into the user's test suite
+    # (graceful degradation contract, same as Storage backends).
+    def emit_reporters(snapshot)
+      RSpecTracer::Reporters::Registry.emit_all(
+        configuration: RSpecTracer,
+        snapshot: snapshot,
+        report_dir: RSpecTracer.report_path,
+        run_metadata: build_run_metadata
+      )
+    rescue StandardError => e
+      RSpecTracer.logger.warn(
+        "rspec-tracer: reporter pipeline failed (#{e.class}: #{e.message})"
+      )
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def build_run_metadata
+      {
+        pid: RSpecTracer.pid,
+        run_time: run_elapsed_seconds,
+        started_at: defined?(@run_started_at) ? @run_started_at : nil,
+        cache_path: RSpecTracer.cache_path,
+        parallel_tests: RSpecTracer.parallel_tests?,
+        rails: RSpecTracer.rails?
+      }
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def run_elapsed_seconds
+      return nil unless defined?(@run_monotonic_start) && @run_monotonic_start
+
+      (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - @run_monotonic_start).round(4)
+    end
+
+    # Dedicated coverage.json firing path, parallel to the
+    # report-reporters Registry pipeline. Fires unconditionally - even
+    # when no examples ran (matches 1.x where coverage.json gets
+    # written with whatever boot-time peek_result returned + filter +
+    # stub). The emitter handles SimpleCov interop internally
+    # (installs `::Coverage.singleton_class.prepend` shim instead of
+    # writing coverage.json when SimpleCov is loaded).
+    def emit_coverage_json
+      return unless engine
+
+      RSpecTracer::Reporters::CoverageJsonReporter.new(
+        snapshot: nil,
+        report_dir: RSpecTracer.report_path,
+        run_metadata: build_run_metadata,
+        logger: RSpecTracer.logger
+      ).generate
+    rescue StandardError => e
+      RSpecTracer.logger.warn(
+        "rspec-tracer: coverage.json emit failed (#{e.class}: #{e.message})"
+      )
     end
   end
 end