rigortype 0.1.4 → 0.1.5

data/lib/rigor/environment/rbs_coverage_report.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Environment
+    # Open item O4 Layer 3 slice 3 — graceful-degradation
+    # coverage report.
+    #
+    # When the user has a `Gemfile.lock` (via slice 1) and rigor
+    # has resolved its target-project RBS sources (DEFAULT_LIBRARIES,
+    # `data/vendored_gem_sigs/`, slice-1 bundle-shipped `sig/`,
+    # slice-2 `rbs_collection.lock.yaml` paths), this module
+    # classifies each locked gem by RBS provenance and surfaces
+    # the "no RBS available" set so the run-start diagnostic in
+    # {Rigor::Analysis::Runner} can suggest `rbs collection
+    # install` or `dependencies.source_inference:` for the
+    # uncovered gems.
+    #
+    # The classification is a pure function over the inputs
+    # (`locked_gems`, two arrays of resolved sig paths). It does
+    # NOT touch the filesystem on its own — the caller passes in
+    # what discovery returned.
+    module RbsCoverageReport
+      # Frozen result row.
+      #
+      # `source` is a Symbol naming where RBS for this gem
+      # resolves; `:missing` means none of the four resolution
+      # paths covered it.
+      Coverage = Data.define(:gem_name, :version, :source) do
+        def initialize(gem_name:, version:, source:)
+          super(
+            gem_name: -gem_name.to_s,
+            version: -version.to_s,
+            source: source
+          )
+        end
+      end
+
+      # Names of gems whose RBS ships under
+      # `data/vendored_gem_sigs/`. Kept in sync with the
+      # vendored-stubs directory listing; when a new gem is
+      # vendored, add its name here too. (The set is small
+      # enough that hard-coding is acceptable; a directory walk
+      # at every call would add stat-cost to no benefit.)
+      VENDORED_GEM_NAMES = Set[
+        "bcrypt", "idn-ruby", "mysql2", "nokogiri", "pg", "redis"
+      ].freeze
+
+      # @param locked_gems [Hash{String => LockfileResolver::LockedGem}]
+      #   The lockfile-resolved gem set. Empty hash → no
+      #   coverage analysis to do.
+      # @param default_libraries [Array<String>] gem names rigor
+      #   auto-loads through `RBS::EnvironmentLoader#add(library:)`.
+      #   Pass `Rigor::Environment::DEFAULT_LIBRARIES` from callers
+      #   running in a project context.
+      # @param bundle_sig_paths [Array<Pathname, String>] the
+      #   discovered `<bundle>/.../gems/<name>-<ver>/sig` paths
+      #   from {BundleSigDiscovery.discover}.
+      # @param rbs_collection_paths [Array<Pathname, String>] the
+      #   discovered `<collection>/<name>/<version>/` paths from
+      #   {RbsCollectionDiscovery.discover}.
+      # @return [Array<Coverage>] one row per locked gem; sorted
+      #   by gem name for deterministic output.
+      def self.classify(locked_gems:, default_libraries:,
+                        bundle_sig_paths:, rbs_collection_paths:)
+        default_set = default_libraries.to_set
+        bundle_names = extract_gem_names_from_bundle_paths(bundle_sig_paths)
+        collection_names = extract_gem_names_from_collection_paths(rbs_collection_paths)
+
+        locked_gems.each_value.map do |locked|
+          name = locked.name
+          source = if default_set.include?(name)
+                     :default_library
+                   elsif VENDORED_GEM_NAMES.include?(name)
+                     :vendored_gem_sig
+                   elsif bundle_names.include?(name)
+                     :bundle_sig
+                   elsif collection_names.include?(name)
+                     :rbs_collection
+                   else
+                     :missing
+                   end
+          Coverage.new(gem_name: name, version: locked.version, source: source)
+        end.sort_by(&:gem_name)
+      end
+
+      # Convenience accessor for the run-start diagnostic.
+      # Filters {classify} down to `:missing` rows.
+      def self.missing(coverage_rows)
+        coverage_rows.select { |row| row.source == :missing }
+      end
+
+      def self.extract_gem_names_from_bundle_paths(paths)
+        paths.each_with_object(Set.new) do |path, set|
+          pathname = path.is_a?(Pathname) ? path : Pathname.new(path)
+          set << BundleSigDiscovery.gem_name_from_sig_path(pathname)
+        end
+      end
+      private_class_method :extract_gem_names_from_bundle_paths
+
+      def self.extract_gem_names_from_collection_paths(paths)
+        # `RbsCollectionDiscovery.discover` returns
+        # `<collection_root>/<name>/<version>/` so the parent
+        # basename is the gem name.
+        paths.each_with_object(Set.new) do |path, set|
+          pathname = path.is_a?(Pathname) ? path : Pathname.new(path)
+          set << pathname.parent.basename.to_s
+        end
+      end
+      private_class_method :extract_gem_names_from_collection_paths
+    end
+  end
+end

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__
+        )
+        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
@@ -122,6 +153,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 +165,38 @@ module Rigor
         # v0.0.9 cache `Cache::Descriptor` regression did.
       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 +314,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 +328,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 +366,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 +482,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 +491,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 +547,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 +558,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 +583,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 +594,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 +615,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