rspec-tracer 1.2.2 → 2.0.0.pre.1

data/lib/rspec_tracer/storage/lazy_snapshot.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative 'snapshot'
+
+module RSpecTracer
+  module Storage
+    # Lazy-reading view returned by `JsonBackend#load_graph`. Presents
+    # the same field surface as `Storage::Snapshot` but defers the disk
+    # read + deserialization for each field until the caller touches it.
+    #
+    # Rationale: on a large cache (100 MB+), eager-reading every file
+    # at setup dominates warm-run startup (see issue #17 / B12). Engine
+    # at setup touches 10/15 fields; reporters never touch the previous
+    # snapshot; third-party tooling often reads one or two. The 3-5
+    # fields the Engine does NOT touch at setup (duplicate_examples,
+    # reverse_dependency, env_dependency; examples_coverage is deferred
+    # to finalize per the seed refactor) save their full disk+parse
+    # cost for every run.
+    #
+    # Duck-types `Snapshot`: every Struct member becomes a method here,
+    # `respond_to?` returns true for each, `to_h` materializes the
+    # whole thing. Callers doing `prev.send(field)` or `prev.field`
+    # work unchanged.
+    #
+    # Thread-safety: the memoization Hash is not guarded. Engine is
+    # single-threaded per run; parallel_tests workers each own their
+    # own LazySnapshot instance. If a future caller reads fields from
+    # multiple threads, wrap with a Monitor at construct time.
+    class LazySnapshot
+      LAZY_FIELDS = (Snapshot.members - %i[schema_version run_id]).freeze
+
+      attr_reader :schema_version, :run_id
+
+      def initialize(schema_version:, run_id:, reader:)
+        @schema_version = schema_version
+        @run_id = run_id
+        @reader = reader
+        @loaded = {}
+      end
+
+      LAZY_FIELDS.each do |field|
+        define_method(field) do
+          return @loaded[field] if @loaded.key?(field)
+
+          @loaded[field] = @reader.read(field)
+        end
+      end
+
+      # Hash view matching `Struct#to_h` so callers composing snapshots
+      # (merge pipelines, reporter helpers) get the familiar shape.
+      # Forces every field to materialize, so only call this when the
+      # full cache is genuinely required.
+      def to_h
+        Snapshot.members.to_h { |m| [m, public_send(m)] }
+      end
+
+      # Materialize a full eager Snapshot. Use when an API requires the
+      # Struct type (Merger input, backends that accept Snapshot on
+      # save). Reads every field.
+      def to_snapshot
+        Snapshot.new(**to_h)
+      end
+    end
+  end
+end

data/lib/rspec_tracer/storage/schema.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal Storage — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Storage
+    # Cache schema version and compatibility policy. 1.x shipped caches
+    # without any version stamp; 2.0's first migration is simply to
+    # start emitting a version and refuse to load anything else.
+    #
+    # Compatibility rule (from ARCHITECTURE.md):
+    #   - `CURRENT` is written into every new cache manifest.
+    #   - `SUPPORTED` is the set of versions this backend is willing
+    #     to load. For 2.0 there is exactly one supported version.
+    #   - On mismatch, `load_graph` returns nil after an `info` log
+    #     line and the run proceeds cold. No in-place migrators.
+    #
+    # Future version bumps (schema_version 3, 4, ...) add entries to
+    # `SUPPORTED` only if the backend can load both shapes. If a
+    # change is breaking, `SUPPORTED` resets to `[CURRENT]` and the
+    # caller pays one cold run on upgrade - the deal 1.x users already
+    # expect for any rspec-tracer version bump.
+    module Schema
+      # schema_version 2 was the first versioned schema (1.x was
+      # unstamped). 2.0 adds `Snapshot.boot_set` - breaking for any
+      # reader that assumed the v2 field list - so CURRENT bumps to 3
+      # and SUPPORTED narrows to only the new version. No v2 caches
+      # were ever persisted in user land.
+      CURRENT = 3
+      # Internal constant.
+      # @api private
+      SUPPORTED = [CURRENT].freeze
+
+      # True when the caller can load a cache stamped with `version`.
+      # nil (an unstamped 1.x cache) is explicitly unsupported -
+      # treating nil as "compatible" would defeat the whole point of
+      # the version field. The caller logs and falls back to cold run.
+      def self.supported?(version)
+        SUPPORTED.include?(version)
+      end
+    end
+  end
+end

data/lib/rspec_tracer/storage/serializer/json.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RSpecTracer
+  # Internal Storage — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Storage
+    # Internal Serializer — see {RSpecTracer} for the user-facing surface.
+    # @api private
+    module Serializer
+      # Default serializer for JsonBackend. Produces pretty-printed
+      # JSON strings; reads tolerate binary-mode bytes by forcing
+      # UTF-8 on decode (preserves the fix for example titles with
+      # non-ASCII bytes on US-ASCII-defaulted filesystems).
+      #
+      # Class-level methods (not module_function) so mutant-rspec can
+      # observe mutations through the call path; see the mutation-
+      # friendly-modules memo.
+      class Json
+        # Internal helper for the tracer pipeline.
+        # @api private
+        def self.extension
+          'json'
+        end
+
+        # Internal helper for the tracer pipeline.
+        # @api private
+        def self.encode(payload)
+          ::JSON.pretty_generate(payload)
+        end
+
+        # Internal helper for the tracer pipeline.
+        # @api private
+        def self.decode(bytes)
+          ::JSON.parse(bytes.dup.force_encoding('UTF-8'))
+        end
+      end
+    end
+  end
+end

data/lib/rspec_tracer/storage/serializer/msgpack.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+module RSpecTracer
+  # Internal Storage — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Storage
+    # Internal Serializer — see {RSpecTracer} for the user-facing surface.
+    # @api private
+    module Serializer
+      # Raised when the caller asks for :msgpack but the msgpack gem
+      # is not in the user's bundle. JsonBackend rescues at construct
+      # time + falls back to the Json serializer with a warn line,
+      # same optional-dep pattern the RedisBackend uses for the redis
+      # gem.
+      class MsgpackGemNotInstalled < StandardError; end
+
+      # MessagePack + zlib serializer. msgpack encode is ~2x smaller
+      # than pretty JSON on our representative dependency graphs;
+      # zlib deflate then buys another ~5x on path-repetitive
+      # payloads (dependency.json is the big one - the same path
+      # string appears once per example that touched it). Combined
+      # ratio matches the ~4-6x claim in remote_cache/archive.rb.
+      #
+      # Stdlib zlib avoids adding a second gem dep; msgpack itself is
+      # the single new dev-group gem. Users who want the backend
+      # add `gem 'msgpack'` to their own Gemfile per
+      # USER_FACING_SURFACE.md optional-dep convention.
+      #
+      # The require is lazy so pure-Ruby suites that stay on :json
+      # do not pay the msgpack load cost and so the LoadError path
+      # is exercisable in unit specs (hide_const-based).
+      class Msgpack
+        # Internal helper for the tracer pipeline.
+        # @api private
+        def self.extension
+          'msgpack.gz'
+        end
+
+        # Internal helper for the tracer pipeline.
+        # @api private
+        def self.encode(payload)
+          ensure_available!
+          ::Zlib::Deflate.deflate(::MessagePack.pack(payload))
+        end
+
+        # Internal helper for the tracer pipeline.
+        # @api private
+        def self.decode(bytes)
+          ensure_available!
+          ::MessagePack.unpack(::Zlib::Inflate.inflate(bytes))
+        end
+
+        # Probe used by JsonBackend#initialize to decide whether to
+        # fall back to the Json serializer at construct time. True
+        # iff `require 'msgpack'` succeeds; false when the gem is
+        # missing. Idempotent without an explicit memo because Ruby's
+        # `require` short-circuits via `$LOADED_FEATURES` on repeat
+        # calls and `defined?(::MessagePack)` cheaply detects the
+        # post-load constant. The previous @msgpack_loaded ivar memo
+        # was load-bearing for mutation observability: once any prior
+        # test tripped the memo, mutations on the require line were
+        # observably equivalent.
+        def self.available?
+          ensure_available!
+          true
+        rescue MsgpackGemNotInstalled
+          false
+        end
+
+        class << self
+          private
+
+          # Internal method on the tracer pipeline.
+          # @api private
+          def ensure_available!
+            return if defined?(::MessagePack)
+
+            require 'msgpack'
+          rescue ::LoadError
+            raise MsgpackGemNotInstalled,
+                  "msgpack gem is not installed; add `gem 'msgpack'` to your Gemfile " \
+                  'to use the :msgpack serializer.'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec_tracer/storage/snapshot.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module RSpecTracer
+  # Internal Storage — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Storage
+    # Value object returned by `Backend#load_graph` and accepted by
+    # `Backend#save_graph`. Bundles every collection that 1.x's
+    # report_writer persists plus the schema_version + run_id envelope
+    # so a full cache can be reconstructed in one trip.
+    #
+    # The field layout mirrors 1.x's on-disk contract (see
+    # `JsonBackend::FILENAMES`); every field round-trips through
+    # `to_h` / `from_h` so the backend can serialize without reaching
+    # into struct internals.
+    #
+    # `examples_coverage` may be `nil` when a caller explicitly loads
+    # the cheap header only. The default load is eager - `nil` vs `{}`
+    # distinguishes "not yet loaded" from "loaded and empty."
+    #
+    # Methods are defined on the reopened class body (not inside the
+    # Struct.new block) so mutant can introspect them - same pattern
+    # as Tracker::Input.
+    #
+    # `boot_set` - Hash[relative_path => sha256_hex] of every project
+    # file loaded before any example runs (spec_helper requires, gem
+    # boot, eager autoload). Backs the constants-blind-spot fix: the
+    # engine compares this against the previous run's boot_set and ORs
+    # any mismatch with WholeSuiteInvalidators when computing the
+    # whole_suite_invalidated bool. Per-example loaded-set attribution
+    # folds into `dependency` via the existing graph registration path
+    # - no separate field.
+    #
+    # `wsi_snapshot` - Hash[watch_name => sha256_hex] produced by
+    # `WholeSuiteInvalidators#digest_snapshot`. Without it, a warm run
+    # can't tell whether Gemfile.lock / .ruby-version / .rspec-tracer
+    # (or the tracer gem identity) changed since the previous run, and
+    # the engine falls back to "first run = invalidate everything" on
+    # every warm run. The field is optional in the JSON layout so older
+    # caches continue to load (missing wsi.json coerces to `{}`, which
+    # compares unequal and triggers one cold re-run - safe fallback,
+    # same cost as any other cache miss).
+    #
+    # `env_snapshot` - Hash[env_name => md5_hex] produced by
+    # `Tracker::EnvSnapshot#digest_snapshot`. Covers env-var values
+    # declared via the per-example `tracks: { env: ... }` DSL.
+    # Without it, a warm run can't tell whether an env-gated example
+    # needs to re-run when the env changes. Same optional-in-JSON
+    # treatment as wsi_snapshot: missing file coerces to `{}`, no
+    # schema_version bump, one cold re-run on upgrade.
+    #
+    # `env_dependency` - Hash[example_id => Array<env_name>] capturing
+    # which env keys each tracked example declared. The per-run
+    # `env_snapshot` stores the digest of each key; this map stores
+    # the example-to-key attribution that the reporter layer needs to
+    # render "which env vars does this example depend on." Without it,
+    # reports can't surface env dependencies - Engine's per-run
+    # `@tracks_env` map would otherwise be lost at finalize.
+    # Same optional-in-JSON treatment as wsi_snapshot / env_snapshot:
+    # missing file coerces to `{}`, no schema_version bump.
+    #
+    # `cache_hit_reason` is a SUITE-LEVEL aggregate. It maps
+    # `reason_string => count` (e.g. `{"Files changed" => 12,
+    # "No cache" => 5}`) and surfaces "why did each non-skipped
+    # example run." JsonBackend persists it as `cache_hit_reason.json`
+    # under the per-run dir (same shape as wsi_snapshot / env_snapshot:
+    # one file per field; missing file coerces to `{}`, no
+    # schema_version bump). SqliteBackend does not persist it (would
+    # require a meta-table column / schema bump); SqliteBackend users
+    # see the field as `{}` on read until a future enhancement
+    # extends the meta table.
+    Snapshot = Struct.new(
+      :schema_version,
+      :run_id,
+      :all_examples,
+      :duplicate_examples,
+      :interrupted_examples,
+      :flaky_examples,
+      :failed_examples,
+      :pending_examples,
+      :skipped_examples,
+      :all_files,
+      :dependency,
+      :reverse_dependency,
+      :examples_coverage,
+      :boot_set,
+      :wsi_snapshot,
+      :env_snapshot,
+      :env_dependency,
+      :cache_hit_reason,
+      keyword_init: true
+    )
+
+    # Internal Snapshot — see {RSpecTracer} for the user-facing surface.
+    # @api private
+    class Snapshot
+      # Defaults every collection to its 1.x starting shape: Hash for
+      # keyed collections, Set for example-id lists. Keeps spec
+      # construction terse and prevents accidental nil-deref when a
+      # save is composed incrementally.
+      def self.empty(schema_version:, run_id:)
+        new(
+          schema_version: schema_version,
+          run_id: run_id,
+          all_examples: {},
+          duplicate_examples: {},
+          interrupted_examples: Set.new,
+          flaky_examples: Set.new,
+          failed_examples: Set.new,
+          pending_examples: Set.new,
+          skipped_examples: Set.new,
+          all_files: {},
+          dependency: {},
+          reverse_dependency: {},
+          examples_coverage: {},
+          boot_set: {},
+          wsi_snapshot: {},
+          env_snapshot: {},
+          env_dependency: {},
+          cache_hit_reason: {}
+        )
+      end
+    end
+  end
+end