rspec-tracer 1.2.3 → 2.0.0.pre.2

data/lib/rspec_tracer/tracker/io_hooks.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require_relative 'file_digest'
+require_relative 'input'
+# Sub-module hooks loaded eagerly: $LOADED_FEATURES makes require
+# idempotent so placement doesn't change observable behavior, and
+# Engine always calls IOHooks.install at boot - the previous
+# install-time require_relative deferred a load that always fires
+# anyway, paying the same total cost ~5 ms later at the cost of
+# the standard requires-at-top Ruby convention.
+require_relative 'io_hooks/file'
+require_relative 'io_hooks/io'
+require_relative 'io_hooks/yaml'
+require_relative 'io_hooks/json'
+require_relative 'io_hooks/kernel'
+
+module RSpecTracer
+  module Tracker
+    # Observer #2 in the 2.0 tracker pipeline (CoverageAdapter is #1).
+    # Intercepts Ruby's file-reading primitives via Module#prepend and
+    # emits Tracker::Input values for files touched by the currently-
+    # active example.
+    #
+    # Lifecycle:
+    #   1. IOHooks.install(root:, filter:, extensions:) - called once
+    #      at Tracker.setup time. Prepends hook modules onto
+    #      File/IO/YAML/JSON/Kernel singleton classes.
+    #   2. Example execution runs inside IOHooks.with_bucket(bucket)
+    #      {...}. Hooks push Inputs into the thread-local bucket;
+    #      outside a with_bucket call every hook fast-rejects.
+    #   3. IOHooks.uninstall clears state - prepended modules stay in
+    #      the ancestry (Ruby has no public API to remove a prepend),
+    #      but every hook fast-rejects on the nil @root_prefix guard,
+    #      so post-uninstall they're functionally no-ops.
+    #
+    # Hot-path rejection order (cheapest first):
+    #   1. @root_prefix present        (install state)
+    #   2. thread-local bucket present (inside an example)
+    #   3. path is String / to_s-able
+    #   4. path.start_with?(@root_prefix)
+    #   5. allow-predicate (extensions + filter, or .rb for Kernel)
+    #   6. bucket.key?(identity)       (dedup before SHA256)
+    #
+    # Digest is SHA256 hex (same as CoverageAdapter; schema_version
+    # bump to change). Computed only *after* dedup, so a file read N
+    # times in one example pays the SHA256 cost exactly once.
+    module IOHooks
+      # Non-Ruby extensions the hook is interested in. .rb is covered
+      # by CoverageAdapter, so it's excluded from the default :data
+      # allow-set. Kernel#load uses a separate predicate (.rb only).
+      DEFAULT_EXTENSIONS = %w[
+        .yml .yaml .json .erb .haml .slim .builder .jbuilder .ru .rake
+      ].to_set.freeze
+
+      BUCKET_KEY = :rspec_tracer_io_bucket
+      # Re-entry guard: Digest::SHA256.file internally opens the file,
+      # which re-fires the File.open hook. Without this flag, the
+      # first hooked read blows the stack via infinite recursion.
+      REENTRY_KEY = :rspec_tracer_io_in_hook
+
+      class << self
+        attr_reader :root
+
+        def install(root:, filter: ->(_path) { true }, extensions: DEFAULT_EXTENSIONS)
+          @root = File.expand_path(root)
+          @root_prefix = "#{@root}/"
+          @extensions = extensions
+          @filter = filter
+
+          ::File.singleton_class.prepend(FileReads)
+          ::IO.singleton_class.prepend(IOReads)
+          ::YAML.singleton_class.prepend(YAMLReads) if defined?(::YAML)
+          ::JSON.singleton_class.prepend(JSONReads) if defined?(::JSON)
+          # Two prepends: singleton_class catches `Kernel.load('x')`,
+          # the module itself catches implicit `load 'x'` in method
+          # bodies (via Object's ancestor chain). `module_function`
+          # on Kernel creates two separate method objects, so both
+          # dispatch paths must be instrumented independently.
+          ::Kernel.singleton_class.prepend(KernelReads)
+          ::Kernel.prepend(KernelReads)
+
+          self
+        end
+
+        def uninstall
+          @root = nil
+          @root_prefix = nil
+          @extensions = nil
+          @filter = nil
+          self
+        end
+
+        def installed?
+          !@root_prefix.nil?
+        end
+
+        def current_bucket
+          Thread.current[BUCKET_KEY]
+        end
+
+        def with_bucket(bucket)
+          prev = Thread.current[BUCKET_KEY]
+          Thread.current[BUCKET_KEY] = bucket
+          begin
+            yield
+          ensure
+            Thread.current[BUCKET_KEY] = prev
+          end
+        end
+
+        # Non-block lifecycle for integration with RSpec hooks (which
+        # can't wrap the example body in a Ruby block). The Tracker
+        # coordinator calls set_bucket at example_started time and
+        # clear_bucket at example_finished time. Unlike with_bucket,
+        # these do not save/restore a prior bucket - the coordinator
+        # owns the Thread.current slot for the span of an example.
+        # rubocop:disable Naming/AccessorMethodName
+        def set_bucket(bucket)
+          Thread.current[BUCKET_KEY] = bucket
+        end
+        # rubocop:enable Naming/AccessorMethodName
+
+        def clear_bucket
+          Thread.current[BUCKET_KEY] = nil
+        end
+
+        # Record a :data input (File/IO/YAML/JSON hooks). The
+        # allow-predicate is the coordinator's default extension +
+        # filter combo.
+        def record(path)
+          _record(path, :data) do |p|
+            @extensions.include?(File.extname(p)) && @filter.call(p)
+          end
+        end
+
+        # Record a :ruby input (Kernel#load hook). Belt-and-suspenders
+        # for dynamically-constructed load paths that might bypass the
+        # Coverage module's require-graph observation. The example
+        # registry dedupes overlap with CoverageAdapter.
+        def record_ruby_load(path)
+          _record(path, :ruby) { |p| p.end_with?('.rb') }
+        end
+
+        private
+
+        # All hook entrypoints funnel through here. Fast-path order is
+        # tuned for the common case (hook fires, there's no bucket):
+        # do the cheapest checks first and bail before touching any
+        # allocation. Only on the slow path do we set the re-entry
+        # guard - `Digest::SHA256.file` internally opens the file and
+        # would otherwise blow the stack.
+        #
+        # Any error is swallowed - hooks never propagate failure into
+        # the user's test suite (CLAUDE.md "graceful degradation").
+        #
+        # The early-return ladder looks complex to RuboCop's metric
+        # but is actually the simplest shape for a hot path: each
+        # guard rejects in ~1-2 machine ops.
+        # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
+        def _record(path, kind)
+          return if @root_prefix.nil?
+
+          bucket = Thread.current[BUCKET_KEY]
+          return if bucket.nil?
+          return unless path.is_a?(String) || path.respond_to?(:to_s)
+
+          path_str = path.to_s
+          return unless path_str.start_with?(@root_prefix)
+          return unless yield(path_str)
+
+          identity = "#{kind}:#{path_str[@root_prefix.length..]}"
+          return if bucket.key?(identity)
+          return if Thread.current[REENTRY_KEY]
+
+          Thread.current[REENTRY_KEY] = true
+          begin
+            digest = FileDigest.compute(path_str)
+            if digest
+              bucket[identity] = Input.for_file(
+                path: path_str, kind: kind, digest: digest, root: @root
+              )
+            end
+          ensure
+            Thread.current[REENTRY_KEY] = false
+          end
+        rescue StandardError
+          nil
+        end
+        # rubocop:enable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/loaded_files_tracker.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require 'coverage'
+require 'set'
+
+require_relative 'file_digest'
+require_relative 'input'
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Observer #5 in the 2.0 tracker pipeline. Closes the constants-
+    # lookup blind spot in 1.x's coverage-diff approach.
+    #
+    # The bug: when file A defines constants at load time and example E2
+    # references them without triggering a re-require, E2's coverage
+    # diff is empty for A. If A changes, the filter incorrectly skips
+    # E2 on the next run.
+    #
+    # The fix: track every project file Ruby has ever loaded during the
+    # process, and attribute them as transitive dependencies of every
+    # example that runs afterward.
+    #
+    #   - `@boot_set`: frozen Set<String> captured at Tracker.setup.
+    #     Files loaded before any example runs (spec_helper requires,
+    #     gem boot code, constant autoloads). Changes to these are
+    #     whole-suite invalidators - any modification re-runs every
+    #     example.
+    #   - `@loaded_set`: append-only Set<String>. Grows as examples run
+    #     and Coverage observes new files. Before each example, the
+    #     filter treats the entire @loaded_set as input to that example;
+    #     after each example, any newly-loaded path is attributed
+    #     specifically to the just-completed example *and* added to
+    #     @loaded_set for the benefit of subsequent examples.
+    #
+    # Rationale - why not smarter?
+    # ----------------------------
+    # The cheaper alternatives all fail correctness or cost:
+    #   - TracePoint(:class, :c_return) fires on every C method call;
+    #     orders-of-magnitude overhead.
+    #   - Ruby-AST scans for constant references are unreliable under
+    #     metaprogramming (const_get, send, autoload blocks).
+    #   - Constant-table introspection doesn't tell us which *example*
+    #     used which constant.
+    #   - Stack-trace sampling is probabilistic - inappropriate for
+    #     cache correctness.
+    # The "loaded set" approach is the cheapest correct solution. Cost:
+    # the test cache is slightly less selective (a lib/constants.rb
+    # change re-runs every example that ran after it loaded rather than
+    # just some subset). Correctness is the win.
+    #
+    # Input kind reuse
+    # ----------------
+    # Emits Input values with `kind: :ruby` - every file in the
+    # loaded-set is a Ruby source file (`::Coverage` tracks Ruby only),
+    # and the dependency graph keys on path (ignoring kind) so a
+    # separate `:transitive_load` kind would buy nothing observable.
+    # Overlap with CoverageAdapter's `:ruby` emissions dedupes naturally
+    # at graph registration.
+    #
+    # Digest cache
+    # ------------
+    # Each path is digested at most once per run (first time it appears
+    # in either the boot set or a stop_example diff). The cache backs
+    # both `loaded_set_inputs` and `boot_set_digest_snapshot`, so
+    # boot-set invalidation comparison is free after the initial capture.
+    #
+    # Enablement flag
+    # ---------------
+    # `enabled:` (default true) threads through from
+    # Configuration#transitive_load_tracking. When false, every method
+    # degrades to a no-op that returns empty collections. This gives
+    # teams an opt-out for pathological suites where the transitive
+    # over-approximation is too aggressive.
+    class LoadedFilesTracker
+      # Internal constant.
+      # @api private
+      DEFAULT_PEEK = -> { ::Coverage.peek_result.keys }
+
+      # boot_set is exposed as an attr_reader rather than a hand-
+      # rolled method so RuboCop's Style/TrivialAccessors stays quiet;
+      # nil is a valid "not yet captured" state callers rely on.
+      attr_reader :root, :boot_set
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def initialize(root:, peek: DEFAULT_PEEK, enabled: true)
+        @root = File.expand_path(root)
+        @root_prefix = "#{@root}/"
+        @peek = peek
+        @enabled = enabled
+        @boot_set = nil
+        @loaded_set = Set.new
+        @input_cache = {}
+        # Steady-state fast-path cache for stop_example: ::Coverage's
+        # tracked-file set grows monotonically; if peek_result.length
+        # is unchanged since the last stop_example call, no new project
+        # files can have appeared. Skip the per-path filter loop
+        # entirely. Initialized to nil so the first call always falls
+        # through to full work + populates the cache.
+        @last_peek_length = nil
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def enabled?
+        @enabled
+      end
+
+      # Capture the boot set once. Idempotent: subsequent calls return
+      # the frozen Set captured on the first call. When disabled,
+      # returns an empty frozen Set without touching ::Coverage.
+      #
+      # Paths whose digest fails (unreadable files) are dropped on the
+      # floor - they stay absent from @boot_set, @loaded_set, and
+      # @input_cache, preserving the "every tracked path has an Input"
+      # invariant. Downstream filtering accepts the slight under-count
+      # (a truly-unreadable boot file was never going to be a useful
+      # invalidation signal anyway).
+      def capture_boot_set!
+        return @boot_set unless @boot_set.nil?
+
+        if @enabled
+          successful_paths = build_inputs(filtered_peek_paths).each_with_object(Set.new) do |input, acc|
+            acc << input.path
+          end
+          # Construct @loaded_set and @boot_set from distinct Set
+          # instances so freezing one can't poison the other -
+          # stop_example must be able to mutate @loaded_set forever
+          # while @boot_set stays frozen for invalidator comparison.
+          @loaded_set = successful_paths
+          @boot_set = Set.new(successful_paths).freeze
+        else
+          @loaded_set = Set.new
+          @boot_set = Set.new.freeze
+        end
+        @boot_set
+      end
+
+      # Hash[relative_path => sha256_hex] for every file in the boot
+      # set. The engine compares this against the previous run's
+      # stored `Snapshot.boot_set` - any inequality is a whole-suite
+      # invalidator.
+      #
+      # Invariant (enforced by capture_boot_set!): every path in
+      # `@boot_set` has a matching `@input_cache` entry, so the fetch
+      # never raises. Disabled trackers produce an empty `@boot_set`,
+      # so the enumeration naturally returns {} without a guard.
+      def boot_set_digest_snapshot
+        return {} if @boot_set.nil?
+
+        @boot_set.to_h { |path| [relative_path(path), @input_cache.fetch(path).digest] }
+      end
+
+      # Compare the current boot set's digest snapshot against a
+      # previously-stored one. `nil` previous_snapshot (first run, no
+      # cache) is treated as "not invalidated by this signal" - first
+      # run is already a cold run for unrelated reasons.
+      #
+      # Disabled tracker never invalidates - the engine ORs this with
+      # WholeSuiteInvalidators.invalidated?, so returning false keeps
+      # the tracker silent when the feature is off.
+      def boot_set_invalidated?(previous_snapshot)
+        return false unless @enabled
+        return false if previous_snapshot.nil?
+
+        boot_set_digest_snapshot != previous_snapshot
+      end
+
+      # Set<Input> covering the full @loaded_set. Callers merge this
+      # into an example's Input bucket at start_example time - every
+      # file loaded up to this point is a transitive dependency.
+      # Returns a fresh Set per call so mutation stays local.
+      #
+      # Disabled trackers never populate @input_cache (capture_boot_set!
+      # skips the build_inputs pass), so no explicit enabled guard is
+      # needed - the enumeration naturally yields Set.new.
+      def loaded_set_inputs
+        @input_cache.values.to_set
+      end
+
+      # Diff-and-grow. Called after an example finishes: peeks
+      # ::Coverage, finds paths the tracker hadn't seen yet, digests
+      # them, adds them to @loaded_set + @input_cache, and returns the
+      # new-paths-only Input set so the caller can attribute them to
+      # the just-completed example.
+      #
+      # Paths whose digest fails are dropped from both @loaded_set and
+      # the returned set - the next stop_example will retry them
+      # (useful if the failure was transient) and keeps the
+      # "@loaded_set => @input_cache has an entry" invariant.
+      #
+      # Steady state (no new files loaded this example) is ~O(|peek|)
+      # with no digest work.
+      def stop_example(_example_id)
+        return Set.new unless @enabled
+
+        new_paths = new_filtered_paths
+        return Set.new if new_paths.empty?
+
+        new_inputs = build_inputs(new_paths)
+        @loaded_set.merge(new_inputs.map(&:path))
+        new_inputs
+      end
+
+      # Defensive copy for external callers / property specs. Callers
+      # that want read-only size should use `loaded_set_size` instead -
+      # avoids the dup allocation.
+      def loaded_set
+        @loaded_set.dup
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def loaded_set_size
+        @loaded_set.size
+      end
+
+      private
+
+      # Full filtered peek - returns a Set of every under-root String
+      # path in the peek result. Used by capture_boot_set! (no prior
+      # `@loaded_set` to diff against).
+      def filtered_peek_paths
+        @peek.call.each_with_object(Set.new) do |path, acc|
+          acc << path if path.is_a?(String) && path.start_with?(@root_prefix)
+        end
+      rescue StandardError
+        Set.new
+      end
+
+      # Diff-filtered peek - returns only paths not yet in @loaded_set.
+      # One hash lookup per peek entry (vs. the two a Set.new + Set - Set
+      # pipeline would pay). Halves stop_example steady-state cost.
+      #
+      # Steady-state fast-path: ::Coverage's tracked-file set grows
+      # monotonically across the run, so when peek_result.length matches
+      # the cached length from the previous call no new project paths
+      # can have appeared. Returns [] without iterating - cuts the
+      # per-call cost from ~70 us (full filter loop over ~500 paths) to
+      # one Array#length comparison. A profile pass identified this
+      # loop as the dominant per-example cost in the engine microbench
+      # (16% TOTAL); the fast-path drops it to <1%.
+      def new_filtered_paths
+        paths = @peek.call
+        return [] if @last_peek_length == paths.length
+
+        @last_peek_length = paths.length
+        paths.each_with_object([]) do |path, acc|
+          next unless path.is_a?(String)
+          next unless path.start_with?(@root_prefix)
+          next if @loaded_set.include?(path)
+
+          acc << path
+        end
+      rescue StandardError
+        []
+      end
+
+      # Builds Input objects for paths not yet cached; returns the Set
+      # of Inputs produced for `paths` (may exclude entries whose
+      # digest failed). Side effect: populates @input_cache.
+      #
+      # Callers are responsible for passing only paths absent from
+      # `@input_cache` (capture_boot_set! on empty cache, stop_example
+      # on `filtered_peek_keys - @loaded_set` where `@loaded_set`
+      # mirrors `@input_cache`'s keys modulo digest failures).
+      def build_inputs(paths)
+        paths.each_with_object(Set.new) do |path, acc|
+          digest = file_digest(path)
+          next if digest.nil?
+
+          input = Input.for_file(path: path, kind: :ruby, digest: digest, root: @root)
+          @input_cache[path] = input
+          acc << input
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def file_digest(path)
+        FileDigest.compute(path)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def relative_path(abs_path)
+        return abs_path unless abs_path.start_with?(@root_prefix)
+
+        abs_path[@root_prefix.length..]
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/new_file_detector.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require_relative 'declared_globs'
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Observer #5 (composition of DeclaredGlobs + cache diff). Fixes
+    # a 1.x gap: fetch_changed_files only iterated the previous run's
+    # cache, so newly-added source files were never discovered and
+    # never triggered re-runs.
+    #
+    # The fix: at boot, walk the union of user-declared globs and a
+    # pure-Ruby default set (lib/**/*.rb). Every match on disk that is
+    # not in the loaded cache's known_paths emits an Input, which the
+    # filter engine treats as "added" and re-runs any example whose
+    # dependency graph could plausibly include it.
+    #
+    # Kind is :declared for every emission. The pure-Ruby default is
+    # logically a pre-declared glob on the user's behalf - the
+    # attribution semantics are identical to an explicit
+    # `track_files 'lib/**/*.rb'`.
+    #
+    # The Rails preset (app/**/*.rb) flows through
+    # Configuration#track_rails_defaults; the default list here stays
+    # framework-agnostic.
+    class NewFileDetector
+      # Internal constant.
+      # @api private
+      DEFAULT_GLOBS = %w[lib/**/*.rb].freeze
+
+      # Internal attribute.
+      # @api private
+      attr_reader :root
+
+      # Input contract: declared_globs and default_globs are Arrays of
+      # String glob patterns. Configuration#declared_globs already
+      # normalizes user input (flatten / compact / to_s / uniq / freeze),
+      # and DeclaredGlobs#initialize re-applies the same coercion
+      # downstream (`Array(globs).flatten.compact.map(&:to_s).uniq.freeze`),
+      # so this constructor stays narrow on purpose - any defensive
+      # coercion here would be triple-applied dead code.
+      def initialize(root:, declared_globs: [], default_globs: DEFAULT_GLOBS)
+        @root = File.expand_path(root)
+        @walker = DeclaredGlobs.new(root: @root, globs: declared_globs + default_globs)
+      end
+
+      # Set<Input> for every on-disk match not present in the supplied
+      # known_paths Set. Called once per suite boot; the walker's
+      # underlying digest work is memoized on the DeclaredGlobs
+      # instance so repeated calls within a single suite don't re-hash.
+      # Engine#compute_change_set passes a Set directly; Set#include?
+      # is O(1) so no upstream `to_set` is needed.
+      def new_files(known_paths:)
+        @walker.walk.reject { |input| known_paths.include?(input.path) }.to_set
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/whole_suite_invalidators.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+require_relative 'file_digest'
+require_relative '../version'
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Observer #4 in the 2.0 tracker pipeline. Emits the binary
+    # "blow it all up" signal that runs before any per-example
+    # filtering - when any watched file changes, the filter engine
+    # treats every example as affected.
+    #
+    # Watch list is deliberately hard-coded (not config-overridable):
+    # these are the files whose semantics are universal across any
+    # rspec-tracer user.
+    #
+    #   - Gemfile.lock   : dependency changes ripple through every spec
+    #   - .ruby-version  : Ruby version changes can shift any behavior
+    #   - .rspec-tracer  : tracer config changes (filters, declared
+    #                      globs) affect what the cache considers fresh
+    #
+    # Plus a synthetic entry for the rspec-tracer gem identity itself -
+    # a gem upgrade that changes invalidation semantics has to
+    # invalidate the cache, which lockfile tracking alone doesn't catch
+    # (the gem path is version-stamped but Gemfile.lock only sees the
+    # constraint, not the resolved install).
+    #
+    # Graceful degradation (CLAUDE.md): absent watch files are skipped
+    # silently. Key-presence asymmetry is the invalidation signal
+    # (snapshot A has key, snapshot B does not => invalidated).
+    class WholeSuiteInvalidators
+      # Internal constant.
+      # @api private
+      WATCH_FILES = %w[Gemfile.lock .ruby-version .rspec-tracer].freeze
+      # Internal constant.
+      # @api private
+      GEM_IDENTITY_KEY = 'rspec-tracer-gem'
+
+      # Internal attribute.
+      # @api private
+      attr_reader :root, :gem_version
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def initialize(root:, gem_version: RSpecTracer::VERSION)
+        @root = File.expand_path(root)
+        @gem_version = gem_version
+      end
+
+      # Fresh snapshot on every call - callers typically take one at
+      # boot (stored as the "current" snapshot) and compare against a
+      # previously-loaded snapshot (returned by the storage backend).
+      # Unlike DeclaredGlobs.walk, this is not memoized: the caller
+      # chooses when to sample.
+      def digest_snapshot
+        snapshot = {}
+        WATCH_FILES.each do |rel|
+          digest = file_digest(File.join(@root, rel))
+          snapshot[rel] = digest unless digest.nil?
+        end
+        snapshot[GEM_IDENTITY_KEY] = gem_identity_digest
+        snapshot
+      end
+
+      # nil previous_snapshot = first-run case (no cache); treat as
+      # invalidated so the filter engine runs every example. Any
+      # subsequent run with a stored snapshot compares value-equality
+      # across the whole Hash, which captures added/removed/changed
+      # watch files in one check.
+      def invalidated?(previous_snapshot)
+        return true if previous_snapshot.nil?
+
+        digest_snapshot != previous_snapshot
+      end
+
+      private
+
+      # SystemCallError on missing / non-file paths is treated as
+      # "not present" via the central FileDigest cache, which returns
+      # nil. Mirrors every other tracker's digest path.
+      def file_digest(path)
+        FileDigest.compute(path)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def gem_identity_digest
+        Digest::SHA256.hexdigest("rspec-tracer-#{@gem_version}")
+      end
+    end
+  end
+end

data/lib/rspec_tracer/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 module RSpecTracer
-  VERSION = '1.2.3'
+  # The currently installed gem version, in `MAJOR.MINOR.PATCH[.pre.N]`
+  # form. Bumped per release; CI's release workflow asserts the tag
+  # matches this constant before pushing to RubyGems.
+  VERSION = '2.0.0.pre.2'
 end