rspec-tracer 1.0.3 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd23aee4693655e787948be6a1e049f99942f8bf0b7f763dd7b2df9f04a01eec
-  data.tar.gz: a88e6daf316e8f35fecb6661a08c837470c7f0e3396d5e63522c29614e975d6e
+  metadata.gz: 67309438f6000ac9913b4d3f48b3e7ba66c56e09674b2bf191b75d0d8134401c
+  data.tar.gz: e10e5253987938b6467920a7adda07dbbce152849373b1c8a4355e771007c196
 SHA512:
-  metadata.gz: f9ab2ad270d188230c5d6eb82593055151dcb1f0d43d2c15fb15bab5d96876d8cae12f70c75eff7c80e81c6c53d8930812c173b5e67899f007237170b66deb9a
-  data.tar.gz: 9d3ce6ded81c0ce02a6a294d1317a732890ef3814a443e87c5345c65e316463e9266af701fe03520283cf58e1e7ecf9165d5ad45aa224e4f46f5410b0790394a
+  metadata.gz: 80b3e75b07083b15e179fa4d108afbf31271ee15c3b87d48625ccfa481a6fa24a70114246fe9644b6d2d743732515029e9ec93e078a9207ed1c4c98ba61964ca
+  data.tar.gz: 8ac718e348b8cc6559b87b45d117cb20ddbca819687208124e1c8e7df557e97528d0da93823fe502e9d689646457037ce9be4c7529f3bdf853ecbcbb6f7a98e7

data/CHANGELOG.md

@@ -1,3 +1,107 @@
+## [1.0.5] - 2026-05-17
+
+### Fixed
+
+- **`example_id` is now stable across runs and across no-op edits** —
+  `Example.from` previously fed `example.example_group.name` and
+  line numbers into the identity-hash payload. Two unrelated effects
+  shifted the resulting MD5 across runs that should have been
+  identical:
+
+  - `example_group.name` is RSpec's generated class name with a
+    load-order-dependent `_2` / `_3` suffix when two spec files share
+    a `describe` name (very common — e.g. `describe User do` in
+    `user_spec.rb` and `models/user_spec.rb`). The same example got
+    a different id depending on rspec's file load order, silently
+    thrashing the cache and breaking failed / pending always-re-run
+    guarantees.
+  - For unnamed examples (`it { }` / `specify { }` / `example { }`),
+    `example.description` falls back to RSpec's line-bearing
+    `"example at <path>:<line>"` string, so a no-op blank-line edit
+    above the example flipped its id and orphaned its cache entry.
+
+  The digest now uses `example_group.description` (the user's
+  string, not the generated class name), strips the trailing `:LINE`
+  from `shared_group_inclusion_backtrace` entries, and for unnamed
+  examples substitutes a line-independent positional discriminator
+  (the example's 0-based ordinal among the unnamed examples of its
+  group). `line_number` / `rerun_file_name` / `rerun_line_number`
+  still ride along in the stored payload for the reporter's location
+  columns but no longer enter the digest. Contract: *rename = new
+  identity; restructure = same identity.*
+
+  Affected since v1.0.0 (2021). One-time cold run on upgrade: every
+  cached `example_id` changes shape, so the first 1.0.5 run misses
+  the 1.0.4 cache uniformly and treats every example as no-cache;
+  the second run is warm again. Surfaced by the 2.0.0.pre.1 field
+  test against third-party Rails apps; ports
+  [#209](https://github.com/avmnu-sng/rspec-tracer/pull/209) and
+  [#211](https://github.com/avmnu-sng/rspec-tracer/pull/211) onto
+  this 1.0.x line. Closes
+  [#196](https://github.com/avmnu-sng/rspec-tracer/issues/196) and
+  [#210](https://github.com/avmnu-sng/rspec-tracer/issues/210).
+
+- **`RSpecTracer.start` no longer crashes when the user pre-started
+  `::Coverage`** — users who want branch coverage typically call
+  `Coverage.start(lines: true, branches: true)` before loading the
+  tracer. On the previous code path, `setup_coverage` called bare
+  `::Coverage.start` unconditionally, which raised
+  `RuntimeError: coverage measurement is already setup` and crashed
+  the tracer init. `setup_coverage` now guards on `Coverage.running?`
+  (Ruby 2.7+) and rescues `RuntimeError` for older Rubies; the
+  tracer attaches to the already-running `::Coverage` instance
+  instead of raising. Ports
+  [#207](https://github.com/avmnu-sng/rspec-tracer/pull/207)'s
+  Coverage-guard half (the 2.0-only `coverage_modes` DSL is not
+  backported). Closes
+  [#195](https://github.com/avmnu-sng/rspec-tracer/issues/195).
+
+- **`remote_cache` download and upload now log on success** — the
+  success paths on `RemoteCache::Cache#download` / `#upload` returned
+  silently, so a successful `rake rspec_tracer:remote_cache:download`
+  produced zero output and users couldn't tell from CI logs whether
+  the cache restored. Two `puts` lines now announce success:
+  `rspec-tracer remote_cache: restored cache from <sha>` after a
+  successful download, and `rspec-tracer remote_cache: uploaded cache
+  to <ref>` after a successful upload. Ports the basic-INFO portion of
+  [#201](https://github.com/avmnu-sng/rspec-tracer/pull/201) (the
+  cross-branch-fallback qualifier and `prune_all!` line are
+  2.0-only — 1.x has neither a multi-tier cache nor a prune_all
+  path). Closes
+  [#188](https://github.com/avmnu-sng/rspec-tracer/issues/188).
+
+### Changed
+
+- **Gemspec now requires MFA for publishing** — adds
+  `spec.metadata['rubygems_mfa_required'] = 'true'`. Pure packaging
+  metadata; no runtime impact for gem consumers. Ports
+  [#214](https://github.com/avmnu-sng/rspec-tracer/pull/214).
+
+## [1.0.4] - 2026-05-06
+
+### Fixed
+
+- **Parallel-tests purge race when a sibling worker is still mid-flush**
+  — the elected worker trusted only `parallel_tests`'s pid-file barrier
+  (`ParallelTests.wait_for_other_processes_to_finish`), which under
+  specific scheduling/I/O timing on GHA Linux x86_64 can return while a
+  sibling's `parallel_tests_N/` dir hasn't fully flushed. The elected
+  then merged + purged, racing the in-progress sibling. Symptoms:
+  intermittent leftover `parallel_tests_N/` dir post-purge AND/OR
+  silently dropped peer caches in the merge.
+
+  Backport of upstream PR
+  [#168](https://github.com/avmnu-sng/rspec-tracer/pull/168). Adds a
+  filesystem barrier layered on top of the pid-file wait. Each worker
+  writes a `.rspec_tracer_boot` marker at `RSpecTracer.start` time and
+  a `.rspec_tracer_done` marker as the first step of its at_exit tasks;
+  the elected worker waits for every booted peer's `.done` to
+  materialize before proceeding to merge + purge. Two independent
+  signals (pid file + filesystem) must agree before the elected worker
+  declares the peer set stable. Bounded at 5 s with a graceful warn
+  for crashed peers — their dirs are purged regardless of completion
+  state, and the merge accepts whatever's on disk.
+
 ## [1.0.3] - 2026-05-04
 
 ### Fixed

data/lib/rspec_tracer/example.rb

@@ -4,16 +4,64 @@ module RSpecTracer
   module Example
     module_function
 
+    # Identity-keyed cache of `<example_group> => Array<unnamed sibling>`
+    # populated lazily by `unnamed_description`. A group with N unnamed
+    # examples computes the sibling list once per group rather than N
+    # times. Memory is bounded by the live group set, which RSpec
+    # retains for the run anyway.
+    @unnamed_siblings_cache = {}.compare_by_identity
+
     def from(example)
-      data = {
-        example_group: example.example_group.name,
+      location = example_location(example)
+      identity = {
+        example_group: example.example_group.description,
         description: example.description,
         full_description: example.full_description,
         shared_group: example.metadata[:shared_group_inclusion_backtrace]
-          .map(&:formatted_inclusion_location)
-      }.merge(example_location(example))
+          .map { |frame| frame.formatted_inclusion_location.sub(/:\d+\z/, '') },
+        file_name: location[:file_name]
+      }
+
+      identity
+        .merge(location)
+        .merge(example_id: Digest::MD5.hexdigest(digest_identity(example, identity).to_json))
+    end
+
+    # The Hash actually fed to the MD5. For a named example this is
+    # `identity` unchanged. For an unnamed example (`it { }` /
+    # `specify { }` / `example { }`) RSpec's `description` is the
+    # line-bearing `"example at <path>:<line>"` fallback, so
+    # `description` is swapped for a line-independent positional
+    # discriminator before hashing. The returned/stored payload still
+    # carries RSpec's `description` / `full_description` untouched —
+    # only the digest input differs.
+    def digest_identity(example, identity)
+      return identity unless unnamed?(example)
+
+      identity.merge(description: unnamed_description(example))
+    end
+
+    # RSpec's raw `metadata[:description]` is `""` for `it { }` /
+    # `specify { }` / `example { }`; the `description` *method* would
+    # instead return the line-bearing `"example at <path>:<line>"`
+    # fallback, so the raw metadata value is what cleanly tells named
+    # from unnamed.
+    def unnamed?(example)
+      example.metadata[:description].to_s.strip.empty?
+    end
+
+    # 0-based ordinal of the example among the *unnamed* examples of
+    # its group. Stable across blank-line / comment edits and across
+    # adding or renaming *named* siblings; changes only when the
+    # unnamed examples are reordered or one is inserted / removed
+    # ahead of it. The Ruby-inspect-style `#<...>` form makes spoofing
+    # by a real user description implausible.
+    def unnamed_description(example)
+      group = example.example_group
+      unnamed_siblings = @unnamed_siblings_cache[group] ||=
+        group.examples.select { |sibling| unnamed?(sibling) }
 
-      data.merge(example_id: Digest::MD5.hexdigest(data.to_json))
+      "#<rspec-tracer unnamed example #{unnamed_siblings.index(example)}>"
     end
 
     def example_location(example)
@@ -53,6 +101,7 @@ module RSpecTracer
       RSpecTracer::SourceFile.file_name(file_path)
     end
 
-    private_class_method :example_location, :example_rerun_location, :location_file_name
+    private_class_method :digest_identity, :unnamed?, :unnamed_description,
+                         :example_location, :example_rerun_location, :location_file_name
   end
 end

data/lib/rspec_tracer/remote_cache/cache.rb

@@ -19,6 +19,8 @@ module RSpecTracer
 
         @aws.download_file(@cache_sha, 'last_run.json')
         @aws.download_dir(@cache_sha, last_run_id)
+
+        puts "rspec-tracer remote_cache: restored cache from #{@cache_sha}"
       rescue StandardError => e
         puts "Error: #{e.message}"
         puts e.backtrace.first(5).join("\n")
@@ -32,6 +34,8 @@ module RSpecTracer
 
         write_branch_refs(file_name)
         @aws.upload_branch_refs(@repo.branch_name, file_name)
+
+        puts "rspec-tracer remote_cache: uploaded cache to #{@repo.branch_ref}"
       rescue StandardError => e
         puts "Error: #{e.message}"
         puts e.backtrace.first(5).join("\n")

data/lib/rspec_tracer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RSpecTracer
-  VERSION = '1.0.3'
+  VERSION = '1.0.5'
 end

data/lib/rspec_tracer.rb

@@ -32,6 +32,17 @@ require_relative 'rspec_tracer/time_formatter'
 require_relative 'rspec_tracer/version'
 
 module RSpecTracer
+  # Filesystem barrier markers, layered on top of parallel_tests's
+  # pid-file wait to defend against the GHA-observed race where the
+  # gem's `wait_for_other_processes_to_finish` returns while a sibling
+  # worker hasn't fully flushed its `parallel_tests_N/` dir yet. Each
+  # worker writes BOOT at setup-time and DONE as the first step of its
+  # at_exit tasks; the elected worker waits for every booted peer's
+  # DONE marker (deadline-bounded) before proceeding to merge + purge.
+  PARALLEL_TESTS_BOOT_MARKER_FILENAME = '.rspec_tracer_boot'
+  PARALLEL_TESTS_DONE_MARKER_FILENAME = '.rspec_tracer_done'
+  PARALLEL_TESTS_PEER_DONE_DEADLINE_SECONDS = 5
+
   class << self
     attr_accessor :running, :pid, :no_examples
 
@@ -191,6 +202,27 @@ module RSpecTracer
       puts "Failed to load parallel tests (Error: #{e.message})"
     ensure
       track_parallel_tests_test_env_number
+      parallel_tests_touch_boot!
+    end
+
+    # Per-worker boot marker. Source-of-truth for "this worker booted
+    # past `RSpecTracer.start`", consumed by the elected worker's
+    # finalize-time peer enumeration. Idempotent; failures are warned
+    # and absorbed (boot-marker write must never block test execution).
+    def parallel_tests_touch_boot!
+      return unless parallel_tests?
+
+      FileUtils.mkdir_p(RSpecTracer.cache_path)
+      File.write(
+        File.join(RSpecTracer.cache_path, PARALLEL_TESTS_BOOT_MARKER_FILENAME),
+        JSON.generate(
+          pid: Process.pid,
+          test_env_number: ENV.fetch('TEST_ENV_NUMBER', ''),
+          started_at: Time.now.utc.iso8601
+        )
+      )
+    rescue StandardError => e
+      puts "RSpec tracer: failed to write boot marker (#{e.class}: #{e.message})"
     end
 
     def track_parallel_tests_test_env_number
@@ -231,7 +263,15 @@ module RSpecTracer
 
       require 'coverage'
 
+      return if ::Coverage.respond_to?(:running?) && ::Coverage.running?
+
       ::Coverage.start
+    rescue RuntimeError
+      # Ruby < 2.7 has no Coverage.running? predicate; the rescue
+      # catches the "user pre-started Coverage themselves" path on
+      # those Rubies. Safe to absorb — the tracer attaches to the
+      # already-running ::Coverage instance.
+      nil
     end
 
     def setup_trace_point
@@ -324,6 +364,15 @@ module RSpecTracer
     end
 
     def run_parallel_tests_exit_tasks
+      # Every worker — elected or not — drops its `.done` marker as the
+      # first thing in finalize so the elected worker's
+      # `parallel_tests_wait_for_peer_done_markers!` can observe it.
+      # Non-elected workers stop here; the elected worker proceeds to
+      # the merge + purge sequence (gated by `parallel_tests_executed?`,
+      # which now layers the peer-done barrier on top of the existing
+      # pid-file wait).
+      parallel_tests_touch_done!
+
       return unless parallel_tests_executed?
 
       merge_parallel_tests_reports
@@ -333,6 +382,24 @@ module RSpecTracer
       purge_parallel_tests_reports
     end
 
+    # Per-worker done marker. Written by every worker (elected or not)
+    # as the first step of `run_parallel_tests_exit_tasks`. Pairs with
+    # the boot marker for the elected worker's peer-done barrier:
+    # presence of `.done` means "this worker has signalled completion
+    # of its own writes"; absence (with `.boot` present) means "still
+    # mid-flush or crashed". Idempotent; failures are warned + absorbed.
+    def parallel_tests_touch_done!
+      return unless parallel_tests?
+
+      FileUtils.mkdir_p(RSpecTracer.cache_path)
+      File.write(
+        File.join(RSpecTracer.cache_path, PARALLEL_TESTS_DONE_MARKER_FILENAME),
+        Time.now.utc.iso8601
+      )
+    rescue StandardError => e
+      puts "RSpec tracer: failed to write done marker (#{e.class}: #{e.message})"
+    end
+
     def merge_parallel_tests_reports
       return unless parallel_tests_executed?
 
@@ -432,9 +499,62 @@ module RSpecTracer
 
       ParallelTests.wait_for_other_processes_to_finish
 
+      # Belt-and-suspenders barrier: pid-file said everyone's done, but
+      # the gem's `wait_for_other_processes_to_finish` has been observed
+      # on GHA Linux x86_64 to return while a sibling's `parallel_tests_N/`
+      # is still mid-flush. Cross-check via the `.boot`/`.done` filesystem
+      # markers before declaring the peer set stable. Idempotent: once
+      # all peers have flushed, subsequent calls just glob, find nothing
+      # missing, and return.
+      parallel_tests_wait_for_peer_done_markers!
+
       true
     end
 
+    # Block until every peer that wrote `.boot` has also written `.done`,
+    # or the deadline elapses. Polled at 50ms — fine enough to close the
+    # typical "barrier returned a tick early" case within a poll or two,
+    # coarse enough not to dominate CPU.
+    #
+    # On timeout we log and proceed: a peer that never wrote `.done`
+    # either crashed (then its dir is orphan content; the subsequent
+    # purge cleans it) or is genuinely hung (the elected can't fix that
+    # — we choose merge correctness over indefinite wait).
+    def parallel_tests_wait_for_peer_done_markers!
+      base_dir = File.dirname(RSpecTracer.cache_path)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + PARALLEL_TESTS_PEER_DONE_DEADLINE_SECONDS
+
+      loop do
+        missing = parallel_tests_peer_dirs_missing_done(base_dir)
+        return if missing.empty?
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          puts 'RSpec tracer: peers booted without finishing within ' \
+               "#{PARALLEL_TESTS_PEER_DONE_DEADLINE_SECONDS}s: #{missing.inspect}; " \
+               'proceeding (peer dirs will be purged regardless of completion state)'
+          return
+        end
+
+        sleep 0.05
+      end
+    end
+
+    # Set difference of `.boot`-bearing peer dirs and `.done`-bearing
+    # peer dirs under `base_dir`. A returned entry means "this peer
+    # registered but has not signalled completion yet" — either still
+    # mid-flush or crashed.
+    def parallel_tests_peer_dirs_missing_done(base_dir)
+      boot_dirs = parallel_tests_peer_dirs_with_marker(base_dir, PARALLEL_TESTS_BOOT_MARKER_FILENAME)
+      done_dirs = parallel_tests_peer_dirs_with_marker(base_dir, PARALLEL_TESTS_DONE_MARKER_FILENAME)
+      boot_dirs - done_dirs
+    end
+
+    def parallel_tests_peer_dirs_with_marker(base_dir, marker_filename)
+      Dir.glob(File.join(base_dir, 'parallel_tests_*', marker_filename)).map do |path|
+        File.dirname(path)
+      end
+    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 per run,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-tracer
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.5
 platform: ruby
 authors:
 - Abhimanyu Singh
@@ -118,9 +118,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/avmnu-sng/rspec-tracer
-  source_code_uri: https://github.com/avmnu-sng/rspec-tracer/tree/v1.0.3
+  source_code_uri: https://github.com/avmnu-sng/rspec-tracer/tree/v1.0.5
   changelog_uri: https://github.com/avmnu-sng/rspec-tracer/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/avmnu-sng/rspec-tracer/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib