rigortype 0.1.4 → 0.1.6

data/lib/rigor/environment/rbs_loader.rb

@@ -49,6 +49,13 @@ module Rigor
         # miss without holding a loader instance, and the
         # instance-side {#build_env} delegates here so the
         # implementation stays single-rooted.
+        #
+        # Vendored gem stubs (`data/vendored_gem_sigs/<gem>/`) are
+        # loaded on top of `signature_paths` so the per-gem RBS
+        # bundled with Rigor itself is in scope for every analysis
+        # run. The gem stubs are intentionally read-only and
+        # appended LAST so user-supplied `signature_paths` win on
+        # name conflicts.
         def build_env_for(libraries:, signature_paths:)
           rbs_loader = RBS::EnvironmentLoader.new
           libraries.each do |library|
@@ -60,8 +67,32 @@ module Rigor
             path = Pathname(path) unless path.is_a?(Pathname)
             rbs_loader.add(path: path) if path.directory?
           end
+          vendored_gem_sig_paths.each do |path|
+            rbs_loader.add(path: path) if path.directory?
+          end
           RBS::Environment.from_loader(rbs_loader).resolve_type_names
         end
+
+        # Per-gem `data/vendored_gem_sigs/<gem>/` directories that
+        # ship with Rigor. Each subdirectory is one gem's RBS surface
+        # (the `<gem>.rbs` file is the typical content; `LICENSE.upstream`
+        # records provenance). Coverage is deliberately scoped to the
+        # native-extension and "everywhere in Rails" gems whose absence
+        # dominated `call.undefined-method` noise in the real-world
+        # survey at `docs/notes/20260515-real-world-rails-survey.md`.
+        VENDORED_GEM_SIGS_ROOT = File.expand_path(
+          "../../../data/vendored_gem_sigs",
+          __dir__
+        ).freeze
+        private_constant :VENDORED_GEM_SIGS_ROOT
+
+        def vendored_gem_sig_paths
+          return [] unless File.directory?(VENDORED_GEM_SIGS_ROOT)
+
+          Dir.children(VENDORED_GEM_SIGS_ROOT).map do |gem_dir|
+            Pathname(File.join(VENDORED_GEM_SIGS_ROOT, gem_dir))
+          end
+        end
       end
 
       attr_reader :libraries, :signature_paths, :cache_store
@@ -87,7 +118,20 @@ module Rigor
         @libraries = libraries.map(&:to_s).freeze
         @signature_paths = signature_paths.map { |p| Pathname(p) }.freeze
         @cache_store = cache_store
-        @state = { env: nil, builder: nil }
+        # Per-loader memoization bucket. Held as a single
+        # mutable Hash so the loader instance itself can be
+        # `.freeze`d (per ADR-15 reflection-facade contract)
+        # without losing the lazy-memo behaviour. Slot names
+        # currently consulted: `:env`, `:env_loaded`,
+        # `:env_build_warned`, `:builder`, `:reflection`,
+        # `:instance_definitions_table`,
+        # `:singleton_definitions_table`. Constructed via
+        # `Hash.new` (NOT a `{ ... }` literal) so Rigor's
+        # `HashShape` narrowing doesn't infer a fixed key set
+        # from the initial state and fold post-initial slot
+        # reads (e.g. `@state[:env_loaded]`) to a constant
+        # `nil`.
+        @state = Hash.new # rubocop:disable Style/EmptyLiteral
         @instance_definition_cache = {}
         @singleton_definition_cache = {}
         @class_known_cache = {}
@@ -122,6 +166,7 @@ module Rigor
       # it never recurses back through {#class_known?}.
       def each_known_class_name
         return enum_for(:each_known_class_name) unless block_given?
+        return if env.nil?
 
         env.class_decls.each_key { |rbs_name| yield rbs_name.to_s }
         env.class_alias_decls.each_key { |rbs_name| yield rbs_name.to_s }
@@ -133,6 +178,68 @@ module Rigor
         # v0.0.9 cache `Cache::Descriptor` regression did.
       end
 
+      # ADR-20 slice 2e — iterates over every `%a{...}`
+      # annotation attached to a class- or module-level
+      # declaration in the loaded RBS environment, yielding
+      # `(annotation_string, source_location)` pairs. Used by
+      # {Rigor::Inference::HktRegistry.scan_rbs_loader} to
+      # find `rigor:v1:hkt_register` / `rigor:v1:hkt_define`
+      # directives in user-authored overlays and merge them
+      # into the per-`Environment` HKT registry. Yields nothing
+      # when the env failed to build (fail-soft, same shape as
+      # {#each_known_class_name}).
+      def each_class_decl_annotation
+        return enum_for(:each_class_decl_annotation) unless block_given?
+        return if env.nil?
+
+        env.class_decls.each_value do |entry|
+          entry.each_decl do |decl|
+            next unless decl.respond_to?(:annotations)
+
+            decl.annotations.each { |a| yield a.string, a.location }
+          end
+        end
+      rescue ::RBS::BaseError, ::Ractor::IsolationError
+        # fail-soft: matches each_known_class_name's policy.
+        # Ractor::IsolationError surfaces when the scan is
+        # invoked from a non-main Ractor pool worker before
+        # ADR-15's full deep-freeze migration completes — the
+        # worker falls back to the base (builtins-only)
+        # registry rather than crashing.
+      end
+
+      # Returns a frozen `Hash<String, String>` mapping each loaded
+      # class / module name (top-level prefixed) to the file path of
+      # its FIRST declaration's RBS source. Used by
+      # {Rigor::Analysis::RunStats} to attribute the type universe
+      # between "project sig/" (paths under the configured
+      # `signature_paths`) and "bundled" (everything else — RBS
+      # core, stdlib libraries, gem-bundled RBS). Each value is a
+      # frozen `String` so the whole result is `Ractor.shareable?`
+      # — the Phase 4b worker pool ships a snapshot back to the
+      # coordinator on the first `:prepare` message.
+      def class_decl_paths
+        return {}.freeze if env.nil?
+
+        result = {}
+        env.class_decls.each do |rbs_name, entry|
+          decl = entry.primary_decl
+          next if decl.nil?
+
+          location = decl.location
+          next if location.nil?
+
+          buffer = location.buffer
+          name = buffer.respond_to?(:name) ? buffer.name : nil
+          next if name.nil?
+
+          result[rbs_name.to_s.dup.freeze] = name.to_s.dup.freeze
+        end
+        result.freeze
+      rescue ::RBS::BaseError
+        {}.freeze
+      end
+
       # @return [RBS::Definition, nil] the resolved instance definition
       #   for `class_name`, or nil when the class is unknown or its
       #   definition cannot be built (RBS may raise on broken hierarchies;
@@ -250,6 +357,8 @@ module Rigor
       #   materialises the constant-type table; ordinary callers
       #   should keep using {#constant_type} for point lookups.
       def constant_names
+        return [] if env.nil?
+
         env.constant_decls.keys.map(&:to_s)
       rescue ::RBS::BaseError
         []
@@ -262,6 +371,7 @@ module Rigor
       # back into the cache when `cache_store` is set).
       def each_constant_decl
         return enum_for(:each_constant_decl) unless block_given?
+        return if env.nil?
 
         env.constant_decls.each do |rbs_name, entry|
           yield rbs_name.to_s, entry
@@ -299,26 +409,109 @@ module Rigor
         nil
       end
 
+      # ADR-15 Phase 4b.x — eagerly drives every cached
+      # producer so a subsequent worker Ractor can serve all
+      # of its RBS queries from the Marshal blob on disk
+      # without ever calling `RBS::EnvironmentLoader.new`.
+      # The loader path that calls `EnvironmentLoader.new`
+      # transitively reads a chain of non-`Ractor.shareable?`
+      # module constants
+      # (`RBS::EnvironmentLoader::DEFAULT_CORE_ROOT`,
+      # `RBS::Repository::DEFAULT_STDLIB_ROOT`,
+      # `Gem::Requirement::DefaultRequirement`, …) and trips
+      # `Ractor::IsolationError`. Pre-warming the cache on
+      # the main Ractor and letting workers consult ONLY the
+      # Marshal-loaded blob sidesteps the whole chain.
+      #
+      # No-op when `cache_store` is nil — without a Store the
+      # worker has no choice but to build env via the loader,
+      # so the caller MUST ensure pool mode runs with caching
+      # enabled. Returns `self` so the call chains cleanly
+      # from the `Runner` pre-spawn hook.
+      def prewarm
+        return self if cache_store.nil?
+
+        env
+        known_class_names_set
+        constant_type_table
+        type_param_names_table
+        ancestor_names_table
+        instance_definitions_table
+        singleton_definitions_table
+        self
+      end
+
+      # ADR-15 Phase 2b — return the loader's read-only
+      # query surface as a frozen, `Ractor.shareable?`
+      # {Reflection} value object. Built lazily on first
+      # access; the loader memoises so repeated calls return
+      # the same instance.
+      #
+      # The Reflection consumes the loader's already-warmed
+      # cache producers (or, when no `cache_store` is set,
+      # eagerly walks the env). Once constructed, the
+      # Reflection carries the derived tables independently
+      # and never re-consults the loader — making it safe to
+      # share across Ractors while the loader stays per-
+      # process / per-Ractor for write-path operations.
+      def reflection
+        @state[:reflection] ||= begin
+          require_relative "reflection"
+          Environment::Reflection.new(
+            known_class_names: known_class_names_set,
+            instance_definitions: instance_definitions_table,
+            singleton_definitions: singleton_definitions_table,
+            type_param_names: type_param_names_table,
+            constant_types: constant_type_table,
+            ancestor_names: ancestor_names_table
+          )
+        end
+      end
+
       private
 
       def constant_type_table
         @constant_type_table ||= begin
           require_relative "../cache/rbs_constant_table"
-          Cache::RbsConstantTable.fetch(loader: self, store: cache_store)
+          fetch_or_compute_producer(Cache::RbsConstantTable)
         end
       end
 
       def known_class_names_set
         @known_class_names_set ||= begin
           require_relative "../cache/rbs_known_class_names"
-          Cache::RbsKnownClassNames.fetch(loader: self, store: cache_store)
+          fetch_or_compute_producer(Cache::RbsKnownClassNames)
         end
       end
 
       def type_param_names_table
         @type_param_names_table ||= begin
           require_relative "../cache/rbs_class_type_param_names"
-          Cache::RbsClassTypeParamNames.fetch(loader: self, store: cache_store)
+          fetch_or_compute_producer(Cache::RbsClassTypeParamNames)
+        end
+      end
+
+      # ADR-15 Phase 2b — the `Reflection` build path
+      # consumes these tables even when `cache_store` is nil
+      # (e.g. tests that build a `Reflection` without a
+      # persistent cache). The helper routes through the
+      # producer's `.fetch` when a store IS available, and
+      # falls back to the producer's `.compute` otherwise.
+      def fetch_or_compute_producer(producer)
+        return producer.fetch(loader: self, store: cache_store) if cache_store
+
+        producer.send(:compute, self)
+      end
+
+      # ADR-15 Phase 2b — `Hash<String, Array<String>>` of
+      # normalised ancestor chains per class. Consumes the
+      # existing `RbsClassAncestorTable` producer when
+      # `cache_store` is set; falls back to the producer's
+      # `compute` otherwise. Used by {#reflection}.
+      def ancestor_names_table
+        @ancestor_names_table ||= begin
+          require_relative "../cache/rbs_class_ancestor_table"
+          fetch_or_compute_producer(Cache::RbsClassAncestorTable)
         end
       end
 
@@ -332,6 +525,8 @@ module Rigor
       end
 
       def translate_constant_decl(rbs_name)
+        return nil if env.nil?
+
         entry = env.constant_decls[rbs_name]
         return nil unless entry
 
@@ -339,8 +534,41 @@ module Rigor
         translated unless translated.is_a?(Type::Bot)
       end
 
+      # The RBS environment for this loader. Memoised both on
+      # success AND on failure: when the env build raises
+      # (typically `RBS::DuplicatedDeclarationError` because a
+      # `signature_paths:` entry redeclares a constant or class
+      # already shipped by stdlib RBS), retrying on every
+      # subsequent `env` call would re-parse and re-resolve the
+      # whole sig set per AST node touched during analysis,
+      # multiplying per-file analysis cost by ~100x. Failures
+      # short-circuit to `nil` here and are surfaced to the user
+      # via `warn_about_env_build_failure_once` so the broken
+      # `signature_paths:` entry is identifiable.
       def env
-        @state[:env] ||= cache_store ? cached_env : build_env
+        return @state[:env] if @state[:env_loaded]
+
+        @state[:env_loaded] = true
+        @state[:env] = cache_store ? cached_env : build_env
+      rescue ::RBS::BaseError => e
+        warn_about_env_build_failure_once(e)
+        @state[:env] = nil
+      end
+
+      def warn_about_env_build_failure_once(error)
+        return if @state[:env_build_warned]
+
+        @state[:env_build_warned] = true
+        first_line = error.message.to_s.lines.first.to_s.strip
+        warn(
+          "rigor: RBS environment build failed: #{error.class}: #{first_line}\n  " \
+          "Likely cause: a `signature_paths:` entry redeclares a constant or class\n  " \
+          "already shipped by Rigor's bundled RBS (Ruby core / stdlib / gem-bundled\n  " \
+          "RBS / `data/vendored_gem_sigs/`). Rigor will continue analyzing with no\n  " \
+          "RBS env in scope, so most type-of queries will return `Dynamic[top]` and\n  " \
+          "most rule diagnostics will not fire. Remove the conflicting `.rbs` from\n  " \
+          "your `signature_paths:` to restore type coverage."
+        )
       end
 
       def cached_env
@@ -362,7 +590,7 @@ module Rigor
       def instance_definitions_table
         @state[:instance_definitions_table] ||= begin
           require_relative "../cache/rbs_instance_definitions"
-          Cache::RbsInstanceDefinitions.fetch(loader: self, store: cache_store)
+          fetch_or_compute_producer(Cache::RbsInstanceDefinitions)
         end
       end
 
@@ -373,7 +601,7 @@ module Rigor
       def singleton_definitions_table
         @state[:singleton_definitions_table] ||= begin
           require_relative "../cache/rbs_instance_definitions"
-          Cache::RbsSingletonDefinitions.fetch(loader: self, store: cache_store)
+          fetch_or_compute_producer(Cache::RbsSingletonDefinitions)
         end
       end
 
@@ -398,6 +626,7 @@ module Rigor
       def build_instance_definition(class_name)
         rbs_name = parse_type_name(class_name)
         return nil unless rbs_name
+        return nil if env.nil?
         return nil unless env.class_decls.key?(rbs_name)
 
         builder.build_instance(rbs_name)
@@ -408,6 +637,7 @@ module Rigor
       def build_singleton_definition(class_name)
         rbs_name = parse_type_name(class_name)
         return nil unless rbs_name
+        return nil if env.nil?
         return nil unless env.class_decls.key?(rbs_name)
 
         builder.build_singleton(rbs_name)
@@ -428,6 +658,7 @@ module Rigor
       def compute_class_known(name)
         rbs_name = parse_type_name(name)
         return false unless rbs_name
+        return false if env.nil?
 
         # `RBS::Environment#class_decls` after `resolve_type_names`
         # holds entries for both classes AND modules; the gem unifies

data/lib/rigor/environment/reflection.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Environment
+    # Frozen, `Ractor.shareable?` read-only RBS query facade.
+    # [ADR-15](../../../docs/adr/15-ractor-concurrency.md)
+    # Phase 2b extracts the read-only surface of {RbsLoader}
+    # into this carrier so future Ractor-isolated workers
+    # can share one Reflection across the pool while keeping
+    # the per-Ractor mutable accelerator state (per-process
+    # memo Hashes) where it belongs.
+    #
+    # Backing tables (all frozen at construction):
+    #
+    # - `known_class_names` — `Set<String>` of every
+    #   class / module / alias name in the loaded RBS
+    #   environment. Top-level prefixed (`"::Hash"`); plain
+    #   queries normalise via {#normalise}.
+    # - `instance_definitions` —
+    #   `Hash<String, RBS::Definition>` keyed on
+    #   `RBS::TypeName#to_s` (top-level prefixed).
+    # - `singleton_definitions` — same shape, singleton side.
+    # - `type_param_names` —
+    #   `Hash<String, Array<Symbol>>` of declared type
+    #   parameters per class.
+    # - `constant_types` — `Hash<String, Rigor::Type>` of
+    #   translated constant declarations.
+    # - `ancestor_names` — `Hash<String, Array<String>>` of
+    #   normalised ancestor chains per class.
+    #
+    # Each `Reflection` instance is `frozen?` at construction
+    # — every cached table is frozen, `self` is frozen.
+    # **NOT** `Ractor.shareable?`: the `instance_definitions`
+    # / `singleton_definitions` tables hold upstream
+    # `RBS::Definition` objects that transitively reference
+    # `RBS::Location` (C-extension state that
+    # `Ractor.make_shareable` rejects).
+    #
+    # The Ractor worker pool (ADR-15 Phase 4) sidesteps this
+    # by having each worker build ITS OWN `Reflection` from
+    # the shared `Cache::Store`. The cross-Ractor sharing
+    # point is the Store's on-disk + in-process memo layer,
+    # NOT the Reflection itself. Each Reflection is a per-
+    # Ractor immutable read-side view; this carrier exists
+    # to GUARANTEE the per-worker view never mutates after
+    # construction.
+    #
+    # If a future RBS release makes `RBS::Location`
+    # Ractor-shareable, swapping the `freeze` call below for
+    # `Ractor.make_shareable(self)` makes the whole carrier
+    # cross-Ractor-shareable in one line. Until then, the
+    # frozen-read-only contract is the deliverable.
+    class Reflection
+      attr_reader :known_class_names, :instance_definitions, :singleton_definitions,
+                  :type_param_names, :constant_types, :ancestor_names
+
+      def initialize(known_class_names:, instance_definitions:, singleton_definitions:,
+                     type_param_names:, constant_types:, ancestor_names:)
+        @known_class_names = freeze_set(known_class_names)
+        @instance_definitions = freeze_hash(instance_definitions)
+        @singleton_definitions = freeze_hash(singleton_definitions)
+        @type_param_names = freeze_hash(type_param_names)
+        @constant_types = freeze_hash(constant_types)
+        @ancestor_names = freeze_hash(ancestor_names)
+        freeze
+      end
+
+      def class_known?(name)
+        @known_class_names.include?(rooted(name))
+      end
+
+      def instance_definition(name)
+        @instance_definitions[rooted(name)]
+      end
+
+      def singleton_definition(name)
+        @singleton_definitions[rooted(name)]
+      end
+
+      def class_type_param_names(name)
+        @type_param_names.fetch(unrooted(name), [])
+      end
+
+      def constant_type(name)
+        @constant_types[rooted(name)]
+      end
+
+      # Three-valued `(lhs, rhs)` relation:
+      # `:equal` / `:subclass` / `:superclass` / `:disjoint` /
+      # `:unknown`. Mirrors {RbsHierarchy#class_ordering}'s
+      # contract; the Reflection's frozen ancestor table
+      # supports the same queries without any in-process
+      # mutation.
+      def class_ordering(lhs, rhs)
+        lhs = unrooted(lhs)
+        rhs = unrooted(rhs)
+        return :equal if lhs == rhs
+
+        lhs_ancestors = @ancestor_names[lhs]
+        rhs_ancestors = @ancestor_names[rhs]
+        return :unknown if lhs_ancestors.nil? || rhs_ancestors.nil? || lhs_ancestors.empty? || rhs_ancestors.empty?
+
+        if lhs_ancestors.include?(rhs)
+          :subclass
+        elsif rhs_ancestors.include?(lhs)
+          :superclass
+        else
+          :disjoint
+        end
+      end
+
+      # Yields every known class / module / alias name in
+      # the loader's canonical rooted form (`"::Hash"`).
+      def each_known_class_name(&)
+        @known_class_names.each(&)
+      end
+
+      private
+
+      # The cached tables use mixed key conventions inherited
+      # from the underlying RBS::TypeName surface: the
+      # name-set / definition tables / constant table store
+      # rooted `"::Foo"` keys; the type-param / ancestor
+      # tables store unrooted `"Foo"`. Reflection's queries
+      # normalise per-lookup so callers can pass either form.
+      def rooted(name)
+        s = name.to_s
+        s.start_with?("::") ? s : "::#{s}"
+      end
+
+      def unrooted(name)
+        name.to_s.delete_prefix("::")
+      end
+
+      def freeze_set(value)
+        return value if value.is_a?(Set) && value.frozen?
+
+        case value
+        when Set then value.dup.freeze
+        when Array, Hash then Set.new(value).freeze
+        else raise ArgumentError, "expected Set / Array / Hash, got #{value.class}"
+        end
+      end
+
+      def freeze_hash(value)
+        return value if value.frozen?
+
+        value.dup.freeze
+      end
+    end
+  end
+end

data/lib/rigor/environment/reporters.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Environment
+    # Mutable container for the per-run analysis reporters
+    # ({Rigor::RbsExtended::Reporter} and
+    # {Rigor::Analysis::DependencySourceInference::BoundaryCrossReporter}).
+    # Held by {Environment} as a single attr; the reporters can be
+    # swapped through {Environment#attach_reporters!} so long-lived
+    # integrations (the LSP `ProjectContext`, future editor-mode
+    # daemons) can share one Environment across many `Runner.run`
+    # calls without each call's diagnostic events accumulating into
+    # a single reporter pair.
+    #
+    # Per-publish reset is the contract: at the start of every
+    # `Runner.run` in sequential mode, the runner stamps the
+    # environment's `Reporters` slot with the runner's own
+    # freshly-built reporter pair. Dispatchers / `RbsExtended`
+    # consumers continue to write through
+    # `environment.rbs_extended_reporter` /
+    # `environment.boundary_cross_reporter` — the lookup just hops
+    # through the `Reporters` slot rather than reading a frozen
+    # ivar.
+    #
+    # Construction default is `nil` on both slots so existing
+    # callers that don't care about reporters (project-default
+    # `Environment.default`, test scopes that don't drive
+    # dispatch) keep their current behaviour: reporter lookups
+    # return nil, and the consumer sites short-circuit on
+    # `reporter.nil?`.
+    class Reporters
+      attr_accessor :rbs_extended, :boundary_cross
+
+      def initialize(rbs_extended: nil, boundary_cross: nil)
+        @rbs_extended = rbs_extended
+        @boundary_cross = boundary_cross
+      end
+    end
+  end
+end