rspec-tracer 1.2.3 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c0ed3fbdb4a082d56a4d83a528dff26bd174abeb28cf1669dc5dd79de521cee
-  data.tar.gz: ebc2fbdfde4c6ac82072b5464f5dc0441d73efd24b4410ed96d3892ea765f1a9
+  metadata.gz: 5a5c7bccaf770c4b630f3aafbe2965e7a88eebf912d4e5f331eb6001613e0559
+  data.tar.gz: cd2c8bb4ea28fa5c70807e8ca7e9249e16a7313f9e17662e3b76d20cc26a91ab
 SHA512:
-  metadata.gz: 1c28a6a997cf74dbb8d910972d9dd8e0b6e9f36aaacc9670e8a50a6bf7c0d4100f6cf421befcba8349750c3ba179a05b86d2a0cbdf740280d490d4bd42c37512
-  data.tar.gz: ce834032d235ea1e2775fb127ac040d6f12f560e7cf9babe5fd208a68cb5dd7260a2ac1f2af78b2a782a622902d9b8291adb2ca339837de70b9f12259e05a456
+  metadata.gz: 2a5889f5a017183e40e63b56c10b6abf2309dff7b18ca941c2f36552e947b508ca3ac144290143a44b2bf78c7f76569eba96d1d580f69eb9a2d2a138e3c004ba
+  data.tar.gz: 79ff93be56d9f9bee3c397b0d78ef0cb4114b5c746879d9afcbf6372d2eb55a8950b75f772372c78aaea3852a12a0750a1098758cf343c41c9caa86b485ac054

data/CHANGELOG.md

@@ -1,3 +1,103 @@
+## [1.2.4] - 2026-05-17
+
+### Fixed
+
+- **`example_id` was unstable across runs — a long-standing bug since
+  v1.0.0.** `RSpecTracer::Example.from` built the MD5 identity hash
+  over a payload that included `example_group.name` (RSpec's
+  generated class name, which carries a load-order-dependent `_2` /
+  `_3` suffix when two spec files share a `describe` name) and the
+  example's `line_number`. The same example got a different id
+  depending on rspec's file load order — silently thrashing the
+  cache and breaking the always-re-run guarantees for failed,
+  pending, and flaky examples. A no-op blank-line edit above the
+  example flipped the id with the same effect.
+
+  The digest now uses a stable subset: the describe block's
+  *description* string (the user-supplied text, not RSpec's
+  generated class name), the example's `description`,
+  `full_description`, `shared_group` inclusion locations with the
+  trailing `:LINE` stripped, and `file_name`. `line_number` /
+  `rerun_file_name` / `rerun_line_number` still ride along in the
+  returned Hash for the HTML and JSON reporters' location columns,
+  but no longer enter the digest. Contract: **rename = new identity;
+  restructure = same identity.**
+
+  Unnamed examples (`it { }`, `specify { }`, `example { }`) needed
+  an extra step. RSpec's pre-run `description` for an unnamed
+  example is the line-bearing `"example at <path>:<line>"`
+  fallback, which would have re-leaked the line number straight
+  into the digest. The digest substitutes a line-independent
+  positional discriminator: the example's ordinal among the
+  *unnamed* examples of its group. Stability is preserved across
+  blank-line edits and across adding or renaming *named* siblings;
+  reordering the unnamed examples re-keys them (the documented
+  trade-off — give the example an explicit description for a fully
+  reorder-stable id).
+
+  **Upgrade note**: the cache file format is unchanged, so a v1.2.3
+  cache loads cleanly through v1.2.4 code. But every cached
+  `example_id` was computed against the old payload and the new
+  lookups will not match them, so the first run after upgrade
+  treats every example as `:no_cache` and re-runs the full suite.
+  Warm caches resume from the second run onward.
+
+  Surfaced by 2.0.0.pre.1 field testing against third-party Rails
+  apps. Fixed upstream in
+  [#209](https://github.com/avmnu-sng/rspec-tracer/pull/209) and
+  [#211](https://github.com/avmnu-sng/rspec-tracer/pull/211).
+
+- **`RSpecTracer.start` crashed when the user pre-started
+  `::Coverage`.** Users opting into branch coverage typically call
+  `Coverage.start(lines: true, branches: true)` before loading
+  rspec-tracer. The tracer's `setup_coverage` then called bare
+  `::Coverage.start` with no `running?` guard, raising
+  `RuntimeError: coverage measurement is already setup` and taking
+  the tracer down at boot.
+
+  Add a `Coverage.running?` predicate guard before the start call,
+  plus a defensive `RuntimeError` rescue with a `logger.warn` for
+  the case where the predicate returns false but `start` still
+  raises. Graceful degradation: coverage measurement is skipped
+  with a visible warn, the rest of the tracer pipeline continues.
+
+  Partial port of upstream
+  [#207](https://github.com/avmnu-sng/rspec-tracer/pull/207); the
+  `coverage_modes` config DSL half is 2.0-only.
+
+- **`remote_cache` success paths were silent at default log level.**
+  `RemoteCache::Cache#download` and `#upload` returned without
+  emitting anything after the underlying AWS calls succeeded, so a
+  successful `rake rspec_tracer:remote_cache:download` produced
+  zero output. Users couldn't tell from CI logs whether the cache
+  was actually restored or whether the run was cold.
+
+  Emit a single `RSpecTracer.logger.info` line on each operation's
+  success path: `"rspec-tracer remote_cache: restored cache from
+  <sha>"` on download, `"rspec-tracer remote_cache: uploaded cache
+  to <ref>"` on upload.
+
+  Partial port of upstream
+  [#201](https://github.com/avmnu-sng/rspec-tracer/pull/201); the
+  cross-branch-fallback qualifier is specific to 2.0's multi-tier
+  cache model and not applicable here.
+
+### Changed
+
+- **`rspec-tracer.gemspec` now declares `rubygems_mfa_required`** so
+  RubyGems enforces MFA on every publish. Packaging metadata only;
+  no behaviour change for users of the gem. Mirrors upstream
+  [#214](https://github.com/avmnu-sng/rspec-tracer/pull/214).
+
+- **`.github/workflows/release.yml` tag-trigger pattern tightened
+  to the strict `'v[0-9]+.[0-9]+.[0-9]+'` form** (1.x is
+  final-release only). The previous loose `'v*.*.*'` form would
+  have matched 4-segment shapes like `v2.0.0.rc.1` accidentally
+  because `*` greedy-matches dots; the strict per-segment digit
+  class rejects any non-digit. Documentation block above the
+  pattern explains the GHA filter-pattern flavor for future
+  maintainers. Workflow-only; no user-visible change.
+
 ## [1.2.3] - 2026-05-06
 
 ### Fixed

data/lib/rspec_tracer/example.rb

@@ -1,19 +1,122 @@
 # frozen_string_literal: true
 
 module RSpecTracer
+  # Builds the identity-hash payload (`:example_id`-keyed Hash) that
+  # RSpec::RunnerHook attaches to every example pre-run.
+  #
+  # == Identity stability contract
+  #
+  # `example_id` is the MD5 of a stable subset of the payload:
+  # `example_group` (the describe block's *description* string),
+  # `description`, `full_description`, `shared_group` (inclusion
+  # locations with the trailing line number stripped), and
+  # `file_name`. The contract, in one line: *rename = new identity;
+  # restructure = same identity.*
+  #
+  # Identity is PRESERVED when:
+  # - blank lines or comments are added/removed around the example
+  # - examples are reordered within a describe block (named
+  #   examples only - see "Unnamed examples" below)
+  # - a sibling describe / example in the same file is renamed
+  # - the example body or its hooks (`before`, `let`) are edited -
+  #   the file digest still triggers the re-run
+  #
+  # Identity CHANGES (one cold "No cache" run) when:
+  # - the file is renamed or moved
+  # - the `describe` / `it` / shared-example name is changed
+  # - the example moves to a different describe block
+  #
+  # == Unnamed examples (`it { }`, `specify { }`, `example { }`)
+  #
+  # An example with no description string has no stable name to hash,
+  # and identity must be computed pre-run (for the filter decision),
+  # before RSpec generates a matcher-derived description. The only
+  # line-independent signal RSpec exposes pre-run is position, so an
+  # unnamed example's identity is derived from its ordinal among the
+  # *unnamed* examples of its group. (RSpec's `description` for an
+  # unnamed example is the line-bearing `"example at <path>:<line>"`
+  # fallback, which would otherwise leak the line number straight
+  # back into the digest.)
+  #
+  # For unnamed examples the contract above is amended: identity is
+  # still PRESERVED across blank-line / comment edits, sibling
+  # renames, and adding or removing *named* siblings - but it CHANGES
+  # when the unnamed examples are reordered, or one is inserted or
+  # removed ahead of it. Give an example an explicit description
+  # (`it 'does X' do`) for a fully reorder-stable identity.
+  #
+  # `line_number` / `rerun_file_name` / `rerun_line_number` stay in
+  # the returned Hash for the reporter location columns, but are
+  # DELIBERATELY EXCLUDED from the digest - a no-op edit that shifts
+  # line numbers must not invalidate the cache. `example_group` uses
+  # `example_group.description` (the user's string) rather than
+  # `example_group.name`: RSpec's generated class name carries a
+  # load-order-dependent `_2` / `_3` suffix when two files share a
+  # describe name, which would otherwise flip the id across runs.
   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 example_group set, which
+    # RSpec retains for the run lifetime 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 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
+
+    # True when the example has no explicit description string. RSpec's
+    # raw `metadata[:description]` is `""` for `it { }` / `specify { }`
+    # / `example { }`; the `description` *method* would instead return
+    # the line-bearing fallback, so the raw metadata value is what
+    # cleanly tells named from unnamed.
+    def unnamed?(example)
+      example.metadata[:description].to_s.strip.empty?
+    end
+
+    # Line-independent identity discriminator for an unnamed example:
+    # its 0-based ordinal among the *unnamed* examples of its group.
+    # Stable across blank-line 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 string
+    # takes a Ruby-inspect-style `#<...>` form so that even if a user
+    # description literally matched, full_description would still
+    # differ between the unnamed example (`"<group> "`) and the named
+    # one (`"<group> #<...>"`), keeping digest collisions structurally
+    # impossible.
+    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 +156,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,11 +19,13 @@ module RSpecTracer
 
         @aws.download_file(@cache_sha, 'last_run.json')
         @aws.download_dir(@cache_sha, last_run_id)
+        RSpecTracer.logger.info "rspec-tracer remote_cache: restored cache from #{@cache_sha}"
       end
 
       def upload
         @aws.upload_file(@repo.branch_ref, 'last_run.json')
         @aws.upload_dir(@repo.branch_ref, last_run_id)
+        RSpecTracer.logger.info "rspec-tracer remote_cache: uploaded cache to #{@repo.branch_ref}"
 
         file_name = File.join(RSpecTracer.cache_path, 'branch_refs.json')
 

data/lib/rspec_tracer/version.rb

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

data/lib/rspec_tracer.rb

@@ -259,8 +259,11 @@ module RSpecTracer
       return if simplecov?
 
       require 'coverage'
+      return if ::Coverage.running?
 
       ::Coverage.start
+    rescue RuntimeError => e
+      RSpecTracer.logger.warn "coverage measurement setup skipped: #{e.message}"
     end
 
     def setup_trace_point

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-tracer
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.2.4
 platform: ruby
 authors:
 - Abhimanyu Singh
@@ -111,9 +111,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.2.3
+  source_code_uri: https://github.com/avmnu-sng/rspec-tracer/tree/v1.2.4
   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