rspec-tracer 1.2.3 → 2.0.0.pre.2

data/lib/rspec_tracer/tracker/env_snapshot.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'digest/md5'
+require 'set'
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Observer #5 in the 2.0 tracker pipeline (WholeSuiteInvalidators
+    # is #4). Owns the per-run snapshot of environment-variable
+    # values that the per-example `tracks: { env: ... }` metadata declares.
+    #
+    # Watch list is caller-provided - unlike WholeSuiteInvalidators,
+    # which hard-codes Gemfile.lock / .ruby-version / .rspec-tracer,
+    # env names come from user metadata and are only known once
+    # RSpec has discovered every example. The engine unions every
+    # example's declared env names and hands the set to
+    # `digest_snapshot` at finalize time.
+    #
+    # Digest algorithm: `Digest::MD5.hexdigest(ENV[name].to_s)`.
+    # Missing env var digests the same as empty string - absent is a
+    # valid state. ENV is process-stable within a single run (we
+    # never mutate it mid-run), so one snapshot per run is enough.
+    #
+    # Graceful degradation: the observer never raises on malformed
+    # input. Non-String env names are coerced via #to_s; nil / empty
+    # names are skipped silently.
+    class EnvSnapshot
+      # ENV source is injectable for testability - specs can pass a
+      # Hash double without poking the real process env.
+      def initialize(env: ::ENV)
+        @env = env
+      end
+
+      # Snapshot the current ENV values for `names`. Returns
+      # `Hash[name => md5_hex]`. Idempotent; callers may invoke it
+      # repeatedly without side effects.
+      def digest_snapshot(names)
+        snapshot = {}
+        names.each do |raw|
+          key = raw.to_s
+          next if key.empty?
+
+          snapshot[key] = Digest::MD5.hexdigest(@env[key].to_s)
+        end
+        snapshot
+      end
+
+      # Return the set of env names whose digest differs between
+      # `previous_snapshot` and the current ENV. Keys in either
+      # snapshot participate:
+      #
+      #   - present in both, digests differ  => invalidated
+      #   - present in previous, absent now  => invalidated
+      #   - absent previously, present now   => invalidated
+      #
+      # `previous_snapshot` may be nil (first run, no cache); in that
+      # case every currently-tracked key is considered invalidated so
+      # the examples declaring them get a mandatory cold re-run on
+      # first sighting. `names` scopes the check: only keys in
+      # `names` are considered, which means one example adding a new
+      # `tracks: env: ...` doesn't cascade-invalidate examples that
+      # declared different env keys previously.
+      def invalidated_keys(previous_snapshot, names)
+        previous = previous_snapshot || {}
+        current = digest_snapshot(names)
+        invalidated = Set.new
+
+        current.each do |key, digest|
+          invalidated << key if digest != previous[key]
+        end
+        invalidated
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/example_registry.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Per-example status + metadata registry. The Filter consults the
+    # registry to decide which examples always re-run (failed / flaky
+    # / pending / interrupted); the registry also owns duplicate
+    # detection via RSpec's identity-hash surface (the same hash 1.x
+    # uses for `fail_on_duplicates`).
+    #
+    # This module owns the data structure only. `update_status` is
+    # called by the RSpec integration hooks on example-finished events
+    # and by signal handlers on interruption; `Tracker.setup` passes
+    # the registry instance through. The registry itself has no
+    # opinion about where status comes from.
+    #
+    # Statuses
+    # --------
+    #   :passed       - completed cleanly
+    #   :failed       - example assertion failed
+    #   :pending      - RSpec `pending`
+    #   :interrupted  - RSpec was killed mid-example (SIGINT / SIGTERM)
+    #   :flaky        - passed this run but previously failed
+    #                   (detected via retry semantics)
+    #   :skipped      - skipped via `skip` or `:skip` metadata; tracked
+    #                   for coverage attribution but NOT auto-re-run
+    #
+    # `always_re_run_ids` returns the union of {failed, flaky,
+    # pending, interrupted} - the 1.x invariant that examples with
+    # those statuses run on every subsequent suite regardless of
+    # whether their input files changed. `:skipped` is deliberately
+    # excluded (matches 1.x `skipped_examples.json` which is written
+    # but not added to the re-run set).
+    class ExampleRegistry
+      # Internal constant.
+      # @api private
+      STATUSES = %i[passed failed pending interrupted flaky skipped].freeze
+      # Internal constant.
+      # @api private
+      ALWAYS_RE_RUN_STATUSES = %i[failed flaky pending interrupted].freeze
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def initialize
+        @examples = {}
+        @identity_index = {}
+        @duplicates = {}
+      end
+
+      # Registers an example id with optional metadata (opaque Hash
+      # passed through to Snapshot.all_examples) and optional
+      # identity_hash for duplicate detection. First call wins for
+      # the identity_hash binding; subsequent calls with the same
+      # identity_hash but a different example_id accumulate into
+      # `@duplicates` and do not re-bind.
+      def register(example_id, metadata: {}, identity_hash: nil)
+        @examples[example_id] ||= { metadata: metadata.dup, status: nil }
+        track_identity(example_id, identity_hash) if identity_hash
+        self
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def update_status(example_id, status)
+        raise ArgumentError, "unknown status: #{status.inspect}" unless STATUSES.include?(status)
+        raise ArgumentError, "example not registered: #{example_id.inspect}" unless @examples.key?(example_id)
+
+        @examples[example_id][:status] = status
+        self
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def status_of(example_id)
+        @examples[example_id]&.dig(:status)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def metadata_of(example_id)
+        entry = @examples[example_id]
+        return nil if entry.nil?
+
+        entry[:metadata].dup
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def registered?(example_id)
+        @examples.key?(example_id)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def all_example_ids
+        @examples.keys.to_set
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def size
+        @examples.size
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def ids_with_status(status)
+        @examples.each_with_object(Set.new) do |(id, entry), acc|
+          acc << id if entry[:status] == status
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def always_re_run_ids
+        @examples.each_with_object(Set.new) do |(id, entry), acc|
+          acc << id if ALWAYS_RE_RUN_STATUSES.include?(entry[:status])
+        end
+      end
+
+      # Hash[identity_hash => Array<example_id>] of every collision
+      # observed. The array always has >= 2 entries (the first
+      # registrant plus every colliding follower).
+      def duplicates
+        @duplicates.transform_values(&:dup)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def duplicate?(identity_hash)
+        @duplicates.key?(identity_hash)
+      end
+
+      private
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def track_identity(example_id, identity_hash)
+        existing = @identity_index[identity_hash]
+        if existing.nil?
+          @identity_index[identity_hash] = example_id
+        elsif existing != example_id
+          bucket = (@duplicates[identity_hash] ||= [existing])
+          bucket << example_id unless bucket.include?(example_id)
+        end
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/file_digest.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Process-wide SHA256 file-digest cache. Keyed on absolute path
+    # with [mtime_ns, size] as the freshness check — when the file's
+    # stat timestamps + size match the cached values, the prior
+    # digest is reused; otherwise the digest is recomputed and the
+    # cache entry refreshed.
+    #
+    # The cache is populated lazily and never evicted within a
+    # process. Tracer runs are bounded (one rspec invocation per
+    # process), so unbounded growth is bounded by the project's
+    # dependency-graph size (typically << 10k unique files).
+    #
+    # SystemCallError on stat / digest is treated as "file gone /
+    # unreadable" and returns nil — same graceful-degradation
+    # contract every call site already implemented locally before
+    # this module centralized them.
+    #
+    # Thread-safety: rspec example execution is single-threaded
+    # (cold-subprocess contract); the cache uses a plain Hash without
+    # locking. Multi-threaded callers are unsupported (consistent
+    # with the rest of the tracer's threading model).
+    module FileDigest
+      class << self
+        # Returns the SHA256 hex digest of `path`, or nil when the
+        # file can't be stat'd (missing / permission denied / racey
+        # delete). Subsequent calls for the same path with unchanged
+        # stat skip the digest computation entirely.
+        def compute(path)
+          stat = File.stat(path)
+          key = (stat.mtime.to_i * 1_000_000_000) + stat.mtime.nsec
+          size = stat.size
+          cache = (@cache ||= {})
+          cached = cache[path]
+          return cached[2] if cached && cached[0] == key && cached[1] == size
+
+          digest = Digest::SHA256.file(path).hexdigest
+          cache[path] = [key, size, digest]
+          digest
+        rescue SystemCallError
+          nil
+        end
+
+        # Drop the cache. Tests that mutate file content in-place at
+        # nanosecond granularity (and so might collide on the
+        # mtime+size key) should call this between scenarios. Normal
+        # tracer runs never need it — the cache lives for one
+        # rspec invocation only.
+        def reset!
+          @cache = {}
+        end
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/filter.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Pure function that computes the filter result for a suite run:
+    # given the previous dependency graph, the current change set,
+    # the example registry, the whole-suite invalidation signal, and
+    # the full list of example ids that exist this run, return the
+    # Hash of {example_id => reason} for every example that must run.
+    #
+    # Stateless - every input is passed explicitly so the function is
+    # trivial to unit-test, property-test, and use as a behavior-
+    # parity target against 1.x's runner.rb.
+    #
+    # Precedence (first-match wins, highest to lowest):
+    #
+    #   1. :whole_suite_invalidator  - any watched file changed
+    #      (Gemfile.lock, .ruby-version, .rspec-tracer, gem version)
+    #      => every id in all_example_ids runs, no further checks.
+    #   2. :interrupted              - example was killed mid-run
+    #      on the previous run; always re-run.
+    #   3. :flaky_example            - example was marked flaky; always
+    #      re-run to re-observe.
+    #   4. :failed_example           - previous failure; always re-run.
+    #   5. :pending_example          - previous pending; always re-run.
+    #   6. :no_cache                 - example exists this run but
+    #      isn't in the graph (new example, never observed).
+    #   7. :files_changed            - example's cached dependency
+    #      set intersects the change_set.
+    #
+    # :skipped is deliberately not a reason - 1.x tracks skipped
+    # examples for coverage attribution but does not re-run them.
+    # ExampleRegistry#always_re_run_ids excludes :skipped; this
+    # function mirrors that by iterating only the four re-run
+    # statuses.
+    module Filter
+      # Internal constant.
+      # @api private
+      REASONS = %i[
+        whole_suite_invalidator
+        interrupted
+        flaky_example
+        failed_example
+        pending_example
+        no_cache
+        files_changed
+      ].freeze
+
+      # Map from registry status to filter reason. Keyed in
+      # precedence order so iteration preserves the precedence when
+      # first-match wins in #assign_once.
+      STATUS_TO_REASON = {
+        interrupted: :interrupted,
+        flaky: :flaky_example,
+        failed: :failed_example,
+        pending: :pending_example
+      }.freeze
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.select(graph:, change_set:, registry:, whole_suite_invalidated:, all_example_ids:)
+        ids = all_example_ids.to_set
+        return whole_suite_result(ids) if whole_suite_invalidated
+
+        result = {}
+        add_always_re_run(result, registry, ids)
+        add_new_examples(result, graph, ids)
+        add_files_changed(result, graph, change_set, ids)
+        result
+      end
+
+      # Convenience: Set<example_id> view of a select() result.
+      def self.to_run_set(result)
+        result.keys.to_set
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.whole_suite_result(ids)
+        ids.to_h { |id| [id, :whole_suite_invalidator] }
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.add_always_re_run(result, registry, ids)
+        STATUS_TO_REASON.each do |status, reason|
+          registry.ids_with_status(status).each do |id|
+            next unless ids.include?(id)
+
+            assign_once(result, id, reason)
+          end
+        end
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.add_new_examples(result, graph, ids)
+        known = graph.example_ids.to_set
+        ids.each do |id|
+          next if known.include?(id)
+
+          assign_once(result, id, :no_cache)
+        end
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.add_files_changed(result, graph, change_set, ids)
+        graph.examples_depending_on(change_set).each do |id|
+          next unless ids.include?(id)
+
+          assign_once(result, id, :files_changed)
+        end
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.assign_once(result, id, reason)
+        result[id] ||= reason
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/input.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Closed taxonomy of input sources. The kinds correspond to the
+    # observation surface: `:ruby` (Coverage-observed source), `:data`
+    # (I/O hooks), `:declared` / `:lockfile` (declared globs), `:env`
+    # (env_snapshot), `:notification` (Rails notifications),
+    # `:template` / `:schema` (Rails subscribers). Adding a new kind
+    # is a one-line change here plus a test; shrinking the set is a
+    # schema_version bump.
+    ALLOWED_INPUT_KINDS = %i[
+      ruby template data schema lockfile declared env notification
+    ].to_set.freeze
+
+    # Value object representing a single input to a test. A test is a
+    # pure function of its inputs (see ARCHITECTURE.md); every input
+    # the tracker observes becomes one Input.
+    #
+    # Construct via Input.for_file - it expands the absolute path,
+    # validates the kind, and precomputes the stable identity string.
+    # The returned struct is frozen.
+    #
+    # Equality, hash, and eql? key on :identity only - two Inputs with
+    # the same identity but different digests are considered the same
+    # input at different points in time. Freshness lives on :digest
+    # and is queried via #stale?.
+    #
+    # Digest algorithm is caller-chosen (the observer owns content
+    # hashing); 2.0's default is SHA256 hex (see CoverageAdapter).
+    # Changing the algorithm is a storage schema_version bump.
+    #
+    # Methods are defined on the reopened class body (not the
+    # Struct.new block) so mutant can introspect them via
+    # Method#source_location - block-scoped defs live on an anonymous
+    # singleton and mutant reports Subjects: 0 for them.
+    Input = Struct.new(:path, :kind, :digest, :identity, keyword_init: true)
+
+    # Internal Input — see {RSpecTracer} for the user-facing surface.
+    # @api private
+    class Input
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.for_file(path:, kind:, digest:, root:)
+        unless ALLOWED_INPUT_KINDS.include?(kind)
+          raise ArgumentError,
+                "invalid Input kind: #{kind.inspect}; " \
+                "allowed: #{ALLOWED_INPUT_KINDS.to_a.inspect}"
+        end
+
+        abs_path = File.expand_path(path)
+        identity = "#{kind}:#{relative_path(abs_path, root)}"
+
+        new(path: abs_path, kind: kind, digest: digest, identity: identity).freeze
+      end
+
+      # Strip `root/` prefix from an absolute path. When the path
+      # escapes the root (absolute symlink target, vendored gem under a
+      # different tree, etc.) we fall back to the full absolute path so
+      # identity stays unique - the deterministic rule is "same path
+      # under same root => same identity", nothing stronger.
+      def self.relative_path(abs_path, root)
+        root_abs = File.expand_path(root)
+        prefix = "#{root_abs}/"
+
+        return abs_path unless abs_path.start_with?(prefix)
+
+        abs_path[prefix.length..]
+      end
+
+      # `!=` handles every case correctly: nil-vs-nil is NOT stale
+      # (absent stayed absent), present-vs-nil and nil-vs-present are
+      # stale (file appeared/disappeared), and digest-vs-digest is
+      # stale iff the content changed.
+      def stale?(current_digest)
+        current_digest != digest
+      end
+
+      # Inputs are value-typed and not meant to be subclassed;
+      # `instance_of?` is precise where `is_a?` would let a subclass
+      # with matching identity compare equal.
+      def ==(other)
+        other.instance_of?(self.class) && identity == other.identity
+      end
+
+      alias eql? ==
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def hash
+        identity.hash
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/io_hooks/file.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Internal IOHooks — see {RSpecTracer} for the user-facing surface.
+    # @api private
+    module IOHooks
+      # Prepended onto File.singleton_class. Each method records the
+      # path (IOHooks.record fast-rejects outside a bucketed example
+      # and swallows any error) then forwards every argument + block
+      # to super via `(...)`.
+      #
+      # The `if Thread.current[BUCKET_KEY]` guard is the hot-path
+      # cut: FileReads sits in every File.singleton_class read on
+      # the entire process for the life of the run, even between
+      # examples and during boot. Without the guard each File.read
+      # paid 2 method-dispatch frames + IOHooks._record's
+      # `@root_prefix` nil-check before the inner bucket check could
+      # bail. With the guard, the bucket check happens at FileReads
+      # so the reject path skips IOHooks.record entirely. Cuts the
+      # M2 Max reject overhead from ~530 ns/call to ~300 ns/call.
+      module FileReads
+        # Internal method on the tracer pipeline.
+        # @api private
+        def read(path, ...)
+          IOHooks.record(path) if Thread.current[BUCKET_KEY]
+          super
+        end
+
+        # Internal method on the tracer pipeline.
+        # @api private
+        def binread(path, ...)
+          IOHooks.record(path) if Thread.current[BUCKET_KEY]
+          super
+        end
+
+        # Internal method on the tracer pipeline.
+        # @api private
+        def readlines(path, ...)
+          IOHooks.record(path) if Thread.current[BUCKET_KEY]
+          super
+        end
+
+        # Internal method on the tracer pipeline.
+        # @api private
+        def open(path, ...)
+          IOHooks.record(path) if Thread.current[BUCKET_KEY]
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/io_hooks/io.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Internal IOHooks — see {RSpecTracer} for the user-facing surface.
+    # @api private
+    module IOHooks
+      # Prepended onto IO.singleton_class. IO.read is the only method
+      # the brief asks for here - File.read covers the bulk of the
+      # use cases; IO.read exists mostly for compatibility with older
+      # code paths and third-party libraries that reach through IO.
+      module IOReads
+        # Internal method on the tracer pipeline.
+        # @api private
+        def read(path, ...)
+          IOHooks.record(path) if Thread.current[BUCKET_KEY]
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/io_hooks/json.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Internal IOHooks — see {RSpecTracer} for the user-facing surface.
+    # @api private
+    module IOHooks
+      # Prepended onto JSON.singleton_class. JSON.load_file is the
+      # user-level file-reading entry point; JSON.parse takes a
+      # string and is not hooked here.
+      module JSONReads
+        # Internal method on the tracer pipeline.
+        # @api private
+        def load_file(path, ...)
+          IOHooks.record(path) if Thread.current[BUCKET_KEY]
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/io_hooks/kernel.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Internal IOHooks — see {RSpecTracer} for the user-facing surface.
+    # @api private
+    module IOHooks
+      # Prepended onto both Kernel and Kernel.singleton_class so both
+      # implicit `load 'x.rb'` (method-lookup via Object's ancestor
+      # chain) and explicit `Kernel.load('x.rb')` (singleton dispatch)
+      # fire the hook. Records as :ruby - CoverageAdapter also sees
+      # these files through the Coverage module's load-path
+      # instrumentation; the example registry dedupes the overlap.
+      module KernelReads
+        # Internal method on the tracer pipeline.
+        # @api private
+        def load(path, ...)
+          IOHooks.record_ruby_load(path) if Thread.current[BUCKET_KEY]
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/io_hooks/yaml.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Internal IOHooks — see {RSpecTracer} for the user-facing surface.
+    # @api private
+    module IOHooks
+      # Prepended onto YAML.singleton_class (Psych). Hooks the three
+      # load_file-family entry points; Psych's internals eventually
+      # call File.read but YAML.load_file is the user-level API that
+      # .rspec-tracer filters target.
+      module YAMLReads
+        # Internal method on the tracer pipeline.
+        # @api private
+        def load_file(path, ...)
+          IOHooks.record(path) if Thread.current[BUCKET_KEY]
+          super
+        end
+
+        # Internal method on the tracer pipeline.
+        # @api private
+        def safe_load_file(path, ...)
+          IOHooks.record(path) if Thread.current[BUCKET_KEY]
+          super
+        end
+
+        # Internal method on the tracer pipeline.
+        # @api private
+        def unsafe_load_file(path, ...)
+          IOHooks.record(path) if Thread.current[BUCKET_KEY]
+          super
+        end
+      end
+    end
+  end
+end