rigortype 0.2.7 → 0.2.8

data/lib/rigor/cache/incremental_snapshot.rb

@@ -6,34 +6,25 @@ require "zlib"
 
 module Rigor
   module Cache
-    # ADR-46 — disk persistence for the incremental analyzer's per-file
-    # state, so a `--incremental` session survives across processes (one
-    # `rigor check` invocation reads the prior run's per-file diagnostics +
-    # dependency graph, re-analyzes only the changed closure, and serves the
-    # rest from disk).
+    # ADR-46 — disk persistence for the incremental analyzer's per-file state, so a `--incremental` session
+    # survives across processes (one `rigor check` invocation reads the prior run's per-file diagnostics +
+    # dependency graph, re-analyzes only the changed closure, and serves the rest from disk).
     #
-    # Unlike ADR-45's whole-run cache (record-and-validate ONE entry,
-    # invalidated by any analyzed-file change), this snapshot is loaded
-    # UNCONDITIONALLY when the global fingerprint matches — the per-file
-    # digests *inside* it drive the incremental re-analysis decision; they
-    # do not gate the load. The fingerprint captures the inputs whose change
-    # requires a full rebuild — the resolved configuration, the RBS
-    # environment, the engine version — but NOT the analyzed source
-    # contents. A fingerprint mismatch (config / gem / version change) drops
-    # the snapshot and forces a full re-analysis, the conservative
-    # direction.
+    # Unlike ADR-45's whole-run cache (record-and-validate ONE entry, invalidated by any analyzed-file change),
+    # this snapshot is loaded UNCONDITIONALLY when the global fingerprint matches — the per-file digests
+    # *inside* it drive the incremental re-analysis decision; they do not gate the load. The fingerprint
+    # captures the inputs whose change requires a full rebuild — the resolved configuration, the RBS
+    # environment, the engine version — but NOT the analyzed source contents. A fingerprint mismatch (config /
+    # gem / version change) drops the snapshot and forces a full re-analysis, the conservative direction.
     #
-    # Every operation is fault-tolerant: a missing, unreadable, schema-
-    # mismatched, fingerprint-mismatched, or corrupt snapshot loads as nil
-    # (→ a cold full run), and a write failure is swallowed (→ the next run
-    # is cold). A cache must never break a run (the ADR-45 invariant).
+    # Every operation is fault-tolerant: a missing, unreadable, schema-mismatched, fingerprint-mismatched, or
+    # corrupt snapshot loads as nil (→ a cold full run), and a write failure is swallowed (→ the next run is
+    # cold). A cache must never break a run (the ADR-45 invariant).
     class IncrementalSnapshot
-      # Bump when the on-disk shape changes so stale snapshots are ignored
-      # rather than mis-deserialized. 5: the blob is zlib-deflated
-      # (ADR-54 WD2 parity with `Store` entries — the snapshot is the
-      # one cache artefact that does not go through `Store`); a raw
-      # pre-5 blob fails the inflate and loads as nil, the usual
-      # fault-tolerant cold-run path.
+      # Bump when the on-disk shape changes so stale snapshots are ignored rather than mis-deserialized. 5:
+      # the blob is zlib-deflated (ADR-54 WD2 parity with `Store` entries — the snapshot is the one cache
+      # artefact that does not go through `Store`); a raw pre-5 blob fails the inflate and loads as nil, the
+      # usual fault-tolerant cold-run path.
       SCHEMA = 5
 
       # The persisted per-file state.
@@ -52,19 +43,15 @@ module Rigor
                             :symbol_sources, :ancestry_sources, :symbol_fingerprints,
                             :missing, :class_decls)
 
-      # The global fingerprint that gates a snapshot load: a digest of the
-      # inputs whose change requires a full rebuild — the engine version +
-      # schema, the resolved configuration, the analysis **roots** (the path
-      # arguments, e.g. `["lib"]`, NOT the expanded file list — so a snapshot
-      # is keyed to an invocation's roots but adding / removing a file under
-      # them is handled incrementally by the session, not a full rebuild), the
-      # resolved gem set (`Gemfile.lock` / `rbs_collection`), and the project's
-      # own RBS (`signature_paths` file contents). Built WITHOUT constructing
-      # the RBS environment so the warm path can gate the load cheaply, before
-      # the costly env build. The `--verify-incremental` gate is the safety net
-      # for any under-capture (it would surface as an incremental-vs-full
-      # mismatch). Returns nil on any error → the caller falls back to a
-      # non-persisted run.
+      # The global fingerprint that gates a snapshot load: a digest of the inputs whose change requires a full
+      # rebuild — the engine version + schema, the resolved configuration, the analysis **roots** (the path
+      # arguments, e.g. `["lib"]`, NOT the expanded file list — so a snapshot is keyed to an invocation's roots
+      # but adding / removing a file under them is handled incrementally by the session, not a full rebuild),
+      # the resolved gem set (`Gemfile.lock` / `rbs_collection`), and the project's own RBS (`signature_paths`
+      # file contents). Built WITHOUT constructing the RBS environment so the warm path can gate the load
+      # cheaply, before the costly env build. The `--verify-incremental` gate is the safety net for any
+      # under-capture (it would surface as an incremental-vs-full mismatch). Returns nil on any error → the
+      # caller falls back to a non-persisted run.
       def self.fingerprint(configuration:, roots:)
         parts = [
           "engine:#{Rigor::VERSION}:#{SCHEMA}",
@@ -84,10 +71,9 @@ module Rigor
       end
       private_class_method :digest_file_if_present
 
-      # Content-digest every `.rbs` under the configured signature paths
-      # (sorted for determinism) so a project RBS edit invalidates the
-      # snapshot. Sig trees are small; content (not mtime) keeps it stable
-      # across checkouts.
+      # Content-digest every `.rbs` under the configured signature paths (sorted for determinism) so a project
+      # RBS edit invalidates the snapshot. Sig trees are small; content (not mtime) keeps it stable across
+      # checkouts.
       def self.digest_signature_paths(signature_paths)
         globbed = Array(signature_paths).flat_map do |entry|
           File.directory?(entry) ? Dir.glob(File.join(entry, "**", "*.rbs")) : [entry]
@@ -105,8 +91,8 @@ module Rigor
 
       attr_reader :path
 
-      # The stored {Payload}, or nil when absent / unreadable / schema or
-      # fingerprint mismatch / corrupt. Never raises.
+      # The stored {Payload}, or nil when absent / unreadable / schema or fingerprint mismatch / corrupt.
+      # Never raises.
       def load(fingerprint:)
         data = Marshal.load(Zlib::Inflate.inflate(File.binread(@path))) # rubocop:disable Security/MarshalLoad
         return nil unless data.is_a?(Hash) && data[:schema] == SCHEMA && data[:fingerprint] == fingerprint
@@ -124,10 +110,8 @@ module Rigor
         nil
       end
 
-      # Persist `payload` under `fingerprint`. Writes via a temp file +
-      # atomic rename so a concurrent reader never sees a half-written
-      # snapshot. Returns true on success, false on any failure (never
-      # raises).
+      # Persist `payload` under `fingerprint`. Writes via a temp file + atomic rename so a concurrent reader
+      # never sees a half-written snapshot. Returns true on success, false on any failure (never raises).
       def save(fingerprint:, payload:)
         FileUtils.mkdir_p(File.dirname(@path))
         raw = Marshal.dump(

data/lib/rigor/cache/rbs_cache_producer.rb

@@ -6,24 +6,19 @@ module Rigor
   module Cache
     # Base for the RBS-derived cache producers.
     #
-    # Every producer (`RbsKnownClassNames`, `RbsConstantTable`,
-    # `RbsEnvironment`, the ancestor / type-param / definition tables, …)
-    # repeated the identical `fetch` wiring: build the RBS descriptor,
-    # then `store.fetch_or_compute` under the producer's id, yielding to
-    # the producer's `compute`. Only the `PRODUCER_ID` constant and the
-    # `compute(loader)` body actually differ between producers.
+    # Every producer (`RbsKnownClassNames`, `RbsConstantTable`, `RbsEnvironment`, the ancestor / type-param /
+    # definition tables, …) repeated the identical `fetch` wiring: build the RBS descriptor, then
+    # `store.fetch_or_compute` under the producer's id, yielding to the producer's `compute`. Only the
+    # `PRODUCER_ID` constant and the `compute(loader)` body actually differ between producers.
     #
-    # Subclasses declare `PRODUCER_ID` and a (private) `self.compute`;
-    # this base owns `fetch`. `self::PRODUCER_ID` resolves the constant on
-    # the concrete subclass, and `compute(loader)` dispatches to its
-    # private class method. See the `_CacheProducer` RBS interface for the
-    # structural contract.
+    # Subclasses declare `PRODUCER_ID` and a (private) `self.compute`; this base owns `fetch`.
+    # `self::PRODUCER_ID` resolves the constant on the concrete subclass, and `compute(loader)` dispatches to
+    # its private class method. See the `_CacheProducer` RBS interface for the structural contract.
     class RbsCacheProducer
       def self.fetch(loader:, store:)
-        # ADR-54 WD4 — the descriptor is identical for every producer
-        # consulting the same loader (same sig files, same libraries),
-        # so the loader memoises one build per process instead of
-        # re-digesting every .rbs file once per producer.
+        # ADR-54 WD4 — the descriptor is identical for every producer consulting the same loader (same sig
+        # files, same libraries), so the loader memoises one build per process instead of re-digesting every
+        # .rbs file once per producer.
         descriptor = loader.rbs_cache_descriptor
         store.fetch_or_compute(producer_id: self::PRODUCER_ID, params: {}, descriptor: descriptor) do
           compute(loader)

data/lib/rigor/cache/rbs_class_ancestor_table.rb

@@ -5,24 +5,18 @@ require_relative "rbs_cache_producer"
 
 module Rigor
   module Cache
-    # Cache producer that materialises the RBS-declared ancestor
-    # chain of every loaded class / module into a Marshal-clean
-    # `Hash<String, Array<String>>`. Ancestor names are top-level-
-    # stripped (e.g. `"Integer"` not `"::Integer"`) to match
-    # `Environment::RbsHierarchy#normalize_name`.
+    # Cache producer that materialises the RBS-declared ancestor chain of every loaded class / module into a
+    # Marshal-clean `Hash<String, Array<String>>`. Ancestor names are top-level-stripped (e.g. `"Integer"` not
+    # `"::Integer"`) to match `Environment::RbsHierarchy#normalize_name`.
     #
-    # The hierarchy is the substrate behind every `class_ordering`
-    # query, which is itself a hot path on the dispatcher (overload
-    # selection, narrowing, etc.). Building one ancestor chain
-    # requires a full `RBS::DefinitionBuilder#build_instance` over
-    # that class — a cold-cost dominated by RBS's own resolution
-    # work. Caching the table lets a warm process skip the build
-    # entirely and pay only a `Marshal.load` of the resulting
-    # hash.
+    # The hierarchy is the substrate behind every `class_ordering` query, which is itself a hot path on the
+    # dispatcher (overload selection, narrowing, etc.). Building one ancestor chain requires a full
+    # `RBS::DefinitionBuilder#build_instance` over that class — a cold-cost dominated by RBS's own resolution
+    # work. Caching the table lets a warm process skip the build entirely and pay only a `Marshal.load` of the
+    # resulting hash.
     #
-    # Cache descriptor shape is shared with every other cache
-    # producer that depends on the RBS environment — see
-    # {RbsDescriptor.build}.
+    # Cache descriptor shape is shared with every other cache producer that depends on the RBS environment —
+    # see {RbsDescriptor.build}.
     class RbsClassAncestorTable < RbsCacheProducer
       PRODUCER_ID = "rbs.class_ancestor_table"
 

data/lib/rigor/cache/rbs_class_type_param_names.rb

@@ -5,24 +5,18 @@ require_relative "rbs_cache_producer"
 
 module Rigor
   module Cache
-    # Cache producer that materialises every loaded class's
-    # RBS-declared type-parameter names as a Marshal-clean
-    # `Hash<String, Array<Symbol>>` keyed by top-level-stripped
-    # class name (e.g. `"Array"` → `[:Elem]`, `"Hash"` →
-    # `[:K, :V]`). Producer id `"rbs.class_type_param_names"`.
+    # Cache producer that materialises every loaded class's RBS-declared type-parameter names as a
+    # Marshal-clean `Hash<String, Array<Symbol>>` keyed by top-level-stripped class name (e.g. `"Array"` →
+    # `[:Elem]`, `"Hash"` → `[:K, :V]`). Producer id `"rbs.class_type_param_names"`.
     #
-    # The dispatcher reads type-parameter names every time it
-    # builds a substitution map from a receiver's `type_args`
-    # into a method's return type — it is one of the hottest
-    # reflection lookups during analysis. Building one entry
-    # requires a full `RBS::DefinitionBuilder#build_instance`
-    # over that class, the same expensive operation
-    # {RbsClassAncestorTable} caches; the two producers share
-    # the build cost when populated together.
+    # The dispatcher reads type-parameter names every time it builds a substitution map from a receiver's
+    # `type_args` into a method's return type — it is one of the hottest reflection lookups during analysis.
+    # Building one entry requires a full `RBS::DefinitionBuilder#build_instance` over that class, the same
+    # expensive operation {RbsClassAncestorTable} caches; the two producers share the build cost when
+    # populated together.
     #
-    # Cache descriptor shape is shared with every other cache
-    # producer that depends on the RBS environment — see
-    # {RbsDescriptor.build}.
+    # Cache descriptor shape is shared with every other cache producer that depends on the RBS environment —
+    # see {RbsDescriptor.build}.
     class RbsClassTypeParamNames < RbsCacheProducer
       PRODUCER_ID = "rbs.class_type_param_names"
 

data/lib/rigor/cache/rbs_constant_table.rb

@@ -5,17 +5,13 @@ require_relative "rbs_cache_producer"
 
 module Rigor
   module Cache
-    # Cache producer that materialises every RBS-declared constant
-    # to its translated `Rigor::Type` form and stores the result as
-    # a `Hash<String, Rigor::Type>` keyed by canonical constant name.
-    # This is the v0.0.8 first cached producer per ADR-6 § 7; it
-    # caches a post-translation artefact so the cache value is
-    # `Marshal`-clean (RBS-native objects carry `RBS::Location`,
-    # which lacks `_dump_data`).
+    # Cache producer that materialises every RBS-declared constant to its translated `Rigor::Type` form and
+    # stores the result as a `Hash<String, Rigor::Type>` keyed by canonical constant name. This is the v0.0.8
+    # first cached producer per ADR-6 § 7; it caches a post-translation artefact so the cache value is
+    # `Marshal`-clean (RBS-native objects carry `RBS::Location`, which lacks `_dump_data`).
     #
-    # Cache descriptor shape is shared with every other cache
-    # producer that depends on the RBS environment — see
-    # {RbsDescriptor.build} for the slot definitions.
+    # Cache descriptor shape is shared with every other cache producer that depends on the RBS environment —
+    # see {RbsDescriptor.build} for the slot definitions.
     class RbsConstantTable < RbsCacheProducer
       PRODUCER_ID = "rbs.constant_type_table"
 
@@ -28,9 +24,8 @@ module Rigor
           translated = Inference::RbsTypeTranslator.translate(entry.decl.type)
           table[name] = translated unless translated.is_a?(Type::Bot)
         rescue ::RBS::BaseError
-          # Skip entries whose RBS type fails to translate; the cache
-          # stays robust to a broken signature rather than corrupting
-          # the whole table. Analyzer-internal errors propagate.
+          # Skip entries whose RBS type fails to translate; the cache stays robust to a broken signature
+          # rather than corrupting the whole table. Analyzer-internal errors propagate.
         end
         table
       end

data/lib/rigor/cache/rbs_descriptor.rb

@@ -6,12 +6,10 @@ require_relative "descriptor"
 
 module Rigor
   module Cache
-    # Shared descriptor builder for cache producers that depend on the
-    # RBS environment (constant table, known-class set, future
-    # Marshal-clean reflection artefacts). Every consumer attaches the
-    # same three slots, so factoring the construction here keeps the
-    # producers small and ensures invalidation behaves identically
-    # across them.
+    # Shared descriptor builder for cache producers that depend on the RBS environment (constant table,
+    # known-class set, future Marshal-clean reflection artefacts). Every consumer attaches the same three
+    # slots, so factoring the construction here keeps the producers small and ensures invalidation behaves
+    # identically across them.
     module RbsDescriptor
       # @param loader [Rigor::Environment::RbsLoader]
       # @return [Rigor::Cache::Descriptor]
@@ -52,13 +50,10 @@ module Rigor
         )
       end
 
-      # ADR-32 WD5 — encode the loader's virtual_rbs set into a
-      # `ConfigEntry` so the env cache invalidates when a
-      # plugin-contributed synthesised RBS string changes (or
-      # appears for the first time). Returns nil when the
-      # loader has no virtual_rbs entries, so callers without
-      # any synthesizer-emitting plugin pay zero descriptor
-      # cost.
+      # ADR-32 WD5 — encode the loader's virtual_rbs set into a `ConfigEntry` so the env cache invalidates when
+      # a plugin-contributed synthesised RBS string changes (or appears for the first time). Returns nil when
+      # the loader has no virtual_rbs entries, so callers without any synthesizer-emitting plugin pay zero
+      # descriptor cost.
       def self.virtual_rbs_entry(loader)
         return nil unless loader.respond_to?(:virtual_rbs)
         return nil if loader.virtual_rbs.nil? || loader.virtual_rbs.empty?

data/lib/rigor/cache/rbs_environment.rb

@@ -6,27 +6,19 @@ require_relative "rbs_environment_marshal_patch"
 
 module Rigor
   module Cache
-    # Cache producer that materialises the entire
-    # `RBS::Environment` (the loader's `build_env` result) and
-    # round-trips it through `Marshal` against the patched
-    # `RBS::Location` (see {RbsEnvironmentMarshalPatch}).
+    # Cache producer that materialises the entire `RBS::Environment` (the loader's `build_env` result) and
+    # round-trips it through `Marshal` against the patched `RBS::Location` (see
+    # {RbsEnvironmentMarshalPatch}).
     #
-    # Cold runs pay the full
-    # `RBS::EnvironmentLoader#load + RBS::Environment.from_loader
-    # + resolve_type_names` cost once; warm runs (and a separate
-    # loader sharing the same Store) load the marshalled blob and
-    # skip the parse / resolve stages entirely. The
-    # `RbsConstantTable`, `RbsKnownClassNames`,
-    # `RbsClassAncestorTable`, and `RbsClassTypeParamNames`
-    # caches still live alongside this producer — their cached
-    # values are reached without re-touching env, but when an
-    # uncached lookup happens (`instance_method`,
-    # `singleton_method`, …) the env produced here is what
-    # answers it.
+    # Cold runs pay the full `RBS::EnvironmentLoader#load + RBS::Environment.from_loader +
+    # resolve_type_names` cost once; warm runs (and a separate loader sharing the same Store) load the
+    # marshalled blob and skip the parse / resolve stages entirely. The `RbsConstantTable`,
+    # `RbsKnownClassNames`, `RbsClassAncestorTable`, and `RbsClassTypeParamNames` caches still live alongside
+    # this producer — their cached values are reached without re-touching env, but when an uncached lookup
+    # happens (`instance_method`, `singleton_method`, …) the env produced here is what answers it.
     #
-    # Cache descriptor shape is shared with every other cache
-    # producer that depends on the RBS environment — see
-    # {RbsDescriptor.build}.
+    # Cache descriptor shape is shared with every other cache producer that depends on the RBS environment —
+    # see {RbsDescriptor.build}.
     class RbsEnvironment < RbsCacheProducer
       PRODUCER_ID = "rbs.environment"
 

data/lib/rigor/cache/rbs_environment_marshal_patch.rb

@@ -2,29 +2,21 @@
 
 require "rbs"
 
-# Adds `_dump` / `_load` to {RBS::Location} so an
-# `RBS::Environment` (and its transitive AST nodes, all of
-# which carry Locations) round-trips through `Marshal`. The
-# rbs gem's C-extension `RBS::Location` ships without the
-# Marshal hooks; until rbs grows them upstream this patch is
-# the minimal monkey-patch the v0.0.9 RBS::Environment cache
-# relies on.
+# Adds `_dump` / `_load` to {RBS::Location} so an `RBS::Environment` (and its transitive AST nodes, all of
+# which carry Locations) round-trips through `Marshal`. The rbs gem's C-extension `RBS::Location` ships
+# without the Marshal hooks; until rbs grows them upstream this patch is the minimal monkey-patch the v0.0.9
+# RBS::Environment cache relies on.
 #
 # Patch policy (purely additive):
 #
-# - `_dump` returns an empty string. The cached env loses
-#   per-node source-position info, but Rigor does not consult
-#   `RBS::Location` from any analysis code path (every
-#   diagnostic uses Prism's own location), so the loss is
-#   inert in practice.
-# - `_load` reconstructs a sentinel Location backed by an
-#   empty `<cached>` Buffer. Code paths that DID consult
-#   Location after a cache hit see a benign zero-range value
-#   rather than crashing.
+# - `_dump` returns an empty string. The cached env loses per-node source-position info, but Rigor does not
+#   consult `RBS::Location` from any analysis code path (every diagnostic uses Prism's own location), so the
+#   loss is inert in practice.
+# - `_load` reconstructs a sentinel Location backed by an empty `<cached>` Buffer. Code paths that DID consult
+#   Location after a cache hit see a benign zero-range value rather than crashing.
 #
-# Idempotent: the guard checks `method_defined?(:_dump)` so
-# requiring this file twice (or against an upstream rbs that
-# adds Marshal hooks itself) is a no-op.
+# Idempotent: the guard checks `method_defined?(:_dump)` so requiring this file twice (or against an upstream
+# rbs that adds Marshal hooks itself) is a no-op.
 module RBS
   class Location
     unless method_defined?(:_dump)

data/lib/rigor/cache/rbs_known_class_names.rb

@@ -5,20 +5,16 @@ require_relative "rbs_cache_producer"
 
 module Rigor
   module Cache
-    # Cache producer that materialises the set of every RBS-declared
-    # class / module / alias name (top-level prefixed, e.g.
-    # `"::Math"`) currently loaded into the environment. Marshal-
-    # clean — the cache value is a `Set<String>`.
+    # Cache producer that materialises the set of every RBS-declared class / module / alias name (top-level
+    # prefixed, e.g. `"::Math"`) currently loaded into the environment. Marshal-clean — the cache value is a
+    # `Set<String>`.
     #
-    # The set lets `RbsLoader#class_known?` answer point lookups in
-    # O(1) without re-parsing the name on each call, and lets a warm
-    # process skip the env walk entirely (the env still has to be
-    # built to enumerate decls on cold misses; subsequent processes
-    # sharing the Store load the set straight from disk).
+    # The set lets `RbsLoader#class_known?` answer point lookups in O(1) without re-parsing the name on each
+    # call, and lets a warm process skip the env walk entirely (the env still has to be built to enumerate
+    # decls on cold misses; subsequent processes sharing the Store load the set straight from disk).
     #
-    # Cache descriptor shape is shared with {RbsConstantTable} via
-    # {RbsDescriptor.build}; a single signature change or rbs gem
-    # bump invalidates both producers in lockstep.
+    # Cache descriptor shape is shared with {RbsConstantTable} via {RbsDescriptor.build}; a single signature
+    # change or rbs gem bump invalidates both producers in lockstep.
     class RbsKnownClassNames < RbsCacheProducer
       PRODUCER_ID = "rbs.known_class_names"