rigortype 0.0.1

data/lib/rigor/environment/rbs_loader.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+require_relative "../type"
+require_relative "../inference/rbs_type_translator"
+require_relative "rbs_hierarchy"
+
+module Rigor
+  class Environment
+    # Loads RBS class declarations and method definitions from disk and
+    # exposes them to the inference engine in a small, stable surface.
+    #
+    # Slice 4 phase 1 only enabled the RBS *core* signatures shipped with
+    # the `rbs` gem (`Object`, `Integer`, `String`, `Array`, ...). Phase
+    # 2a adds opt-in stdlib library loading (`pathname`, `json`,
+    # `tempfile`, ...) and arbitrary-directory signature loading
+    # (typically the project's local `sig/` tree). Both are off by
+    # default on `RbsLoader.default` so the core-only fast path stays
+    # cheap; project-aware loading is opted into through
+    # {Environment.for_project} or by constructing a custom loader.
+    #
+    # The default instance is shared across the process: building the
+    # core RBS environment costs hundreds of milliseconds and the data
+    # is read-only. The shared instance is frozen, but holds a mutable
+    # state hash for lazy memoization of the heavy `RBS::Environment`
+    # and `RBS::DefinitionBuilder` -- the user-visible API stays purely
+    # functional.
+    #
+    # See docs/internal-spec/inference-engine.md for the binding contract.
+    # rubocop:disable Metrics/ClassLength
+    class RbsLoader
+      class << self
+        def default
+          @default ||= new.freeze
+        end
+
+        # Used by tests to discard the cached default loader; production
+        # code MUST NOT call this. The shared loader holds a several-MB
+        # RBS::Environment, so dropping it during a normal run wastes the
+        # cost of rebuilding it.
+        def reset_default!
+          @default = nil
+        end
+      end
+
+      attr_reader :libraries, :signature_paths
+
+      # @param libraries [Array<String, Symbol>] stdlib library names to
+      #   load on top of core (e.g., `["pathname", "json"]`). Empty by
+      #   default. Each entry MUST correspond to a directory under the
+      #   `rbs` gem's `stdlib/` tree; unknown names are silently dropped
+      #   on environment build (the underlying `RBS::EnvironmentLoader`
+      #   raises and we fail-soft).
+      # @param signature_paths [Array<String, Pathname>] additional
+      #   directories of `.rbs` files to load (typically the project's
+      #   `sig/` tree). Non-existent or non-directory paths are filtered
+      #   out at build time so the loader stays robust to fixtures and
+      #   bare repositories.
+      def initialize(libraries: [], signature_paths: [])
+        @libraries = libraries.map(&:to_s).freeze
+        @signature_paths = signature_paths.map { |p| Pathname(p) }.freeze
+        @state = { env: nil, builder: nil }
+        @instance_definition_cache = {}
+        @singleton_definition_cache = {}
+        @class_known_cache = {}
+        @hierarchy = RbsHierarchy.new(self)
+      end
+
+      # Returns true when an RBS class or module declaration with the given
+      # name is loaded. Accepts unprefixed or top-level-prefixed names
+      # ("Integer" or "::Integer"). Memoized per-name (positive and
+      # negative results both cache).
+      def class_known?(name)
+        key = name.to_s
+        return @class_known_cache[key] if @class_known_cache.key?(key)
+
+        @class_known_cache[key] = compute_class_known(name)
+      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;
+      #   we fail-soft and return nil so the caller can fall back).
+      def instance_definition(class_name)
+        key = class_name.to_s
+        return @instance_definition_cache[key] if @instance_definition_cache.key?(key)
+
+        @instance_definition_cache[key] = build_instance_definition(class_name)
+      end
+
+      # @return [RBS::Definition::Method, nil]
+      def instance_method(class_name:, method_name:)
+        definition = instance_definition(class_name)
+        return nil unless definition
+
+        definition.methods[method_name.to_sym]
+      end
+
+      # @return [RBS::Definition, nil] the resolved singleton (class
+      #   object) definition for `class_name`. The methods on this
+      #   definition are the *class methods* of `class_name`, including
+      #   those inherited from `Class` and `Module` for class types.
+      #   Returns nil for unknown names and on RBS build errors (fail-soft).
+      def singleton_definition(class_name)
+        key = class_name.to_s
+        return @singleton_definition_cache[key] if @singleton_definition_cache.key?(key)
+
+        @singleton_definition_cache[key] = build_singleton_definition(class_name)
+      end
+
+      # @return [RBS::Definition::Method, nil] the class method on
+      #   `class_name`. For example, `singleton_method(class_name:
+      #   "Integer", method_name: :sqrt)` returns the definition for
+      #   `Integer.sqrt`, while `singleton_method(class_name: "Foo",
+      #   method_name: :new)` returns Class#new for any class type.
+      def singleton_method(class_name:, method_name:)
+        definition = singleton_definition(class_name)
+        return nil unless definition
+
+        definition.methods[method_name.to_sym]
+      end
+
+      # Slice 4 phase 2d. Returns the class's declared type-parameter
+      # names as Symbols (e.g., `[:Elem]` for `Array`, `[:K, :V]` for
+      # `Hash`). Used by the dispatcher to build the substitution map
+      # from receiver `type_args` into the method's return type. The
+      # instance definition is the canonical source because singleton
+      # methods (e.g., `Array.new`) parameterize over the same `Elem`
+      # as instance methods.
+      #
+      # Returns an empty array for non-generic classes and for unknown
+      # names (the loader stays fail-soft). NOTE: in the `rbs` gem,
+      # `RBS::Definition#type_params` returns `Array<Symbol>` directly,
+      # not the AST `TypeParam` object (those live on the AST level).
+      def class_type_param_names(class_name)
+        definition = instance_definition(class_name)
+        return [] unless definition
+
+        definition.type_params.dup
+      end
+
+      def class_ordering(lhs, rhs)
+        @hierarchy.class_ordering(lhs, rhs)
+      end
+
+      # Slice A constant-value lookup. Returns the translated
+      # `Rigor::Type` for a non-class constant declaration
+      # (`BUCKETS: Array[Symbol]`, `DEFAULT_PATH: String`, ...) or
+      # `nil` when no constant entry exists for `name` in the
+      # loaded RBS environment. Callers MUST treat the return
+      # value as authoritative when present and as "unknown" when
+      # nil; the loader does NOT consult the class declarations
+      # here — class objects are still resolved through
+      # {#class_known?} and `Environment#singleton_for_name`.
+      def constant_type(name)
+        rbs_name = parse_type_name(name)
+        return nil unless rbs_name
+
+        entry = env.constant_decls[rbs_name]
+        return nil unless entry
+
+        translated = Inference::RbsTypeTranslator.translate(entry.decl.type)
+        translated unless translated.is_a?(Type::Bot)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def env
+        @state[:env] ||= build_env
+      end
+
+      def builder
+        @state[:builder] ||= RBS::DefinitionBuilder.new(env: env)
+      end
+
+      def build_env
+        rbs_loader = RBS::EnvironmentLoader.new
+        @libraries.each do |library|
+          # Phase 2a deliberately fails-soft on unknown stdlib libraries
+          # so a stale `.rigor.yml` (or future config plumbing) does not
+          # take down the whole analyzer. Phase 2b will surface this
+          # through diagnostics once the configuration layer can name
+          # the offending source. The unknown-library check happens at
+          # `from_loader` time, not at `add` time, so we have to gate
+          # ahead of `add`.
+          next unless rbs_loader.has_library?(library: library, version: nil)
+
+          rbs_loader.add(library: library, version: nil)
+        end
+        @signature_paths.each do |path|
+          rbs_loader.add(path: path) if path.directory?
+        end
+        RBS::Environment.from_loader(rbs_loader).resolve_type_names
+      end
+
+      def build_instance_definition(class_name)
+        rbs_name = parse_type_name(class_name)
+        return nil unless rbs_name
+        return nil unless env.class_decls.key?(rbs_name)
+
+        builder.build_instance(rbs_name)
+      rescue StandardError
+        nil
+      end
+
+      def build_singleton_definition(class_name)
+        rbs_name = parse_type_name(class_name)
+        return nil unless rbs_name
+        return nil unless env.class_decls.key?(rbs_name)
+
+        builder.build_singleton(rbs_name)
+      rescue StandardError
+        nil
+      end
+
+      def parse_type_name(name)
+        s = name.to_s
+        return nil if s.empty?
+
+        s = "::#{s}" unless s.start_with?("::")
+        RBS::TypeName.parse(s)
+      rescue StandardError
+        nil
+      end
+
+      def compute_class_known(name)
+        rbs_name = parse_type_name(name)
+        return false unless rbs_name
+
+        # `RBS::Environment#class_decls` after `resolve_type_names`
+        # holds entries for both classes AND modules; the gem unifies
+        # them under one map post-resolution. Aliases live in their
+        # own table.
+        env.class_decls.key?(rbs_name) || env.class_alias_decls.key?(rbs_name)
+      rescue StandardError
+        false
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/rigor/environment.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require_relative "environment/class_registry"
+require_relative "environment/rbs_loader"
+
+module Rigor
+  # The engine's view of the type universe outside the current scope.
+  # Slice 1 only exposed the class registry; Slice 4 adds the RBS loader,
+  # which threads through ExpressionTyper and MethodDispatcher to type
+  # constant references and method calls that the literal-typer and
+  # constant-folding tiers cannot answer.
+  #
+  # See docs/internal-spec/inference-engine.md for the binding contract.
+  class Environment
+    DEFAULT_PROJECT_SIG_DIR = "sig"
+    private_constant :DEFAULT_PROJECT_SIG_DIR
+
+    # Slice A stdlib expansion. Stdlib libraries that
+    # `Environment.for_project` loads on top of RBS core unless
+    # the caller passes an explicit `libraries:` array. Each
+    # entry MUST be a stdlib library name accepted by
+    # `RBS::EnvironmentLoader#has_library?`; unknown libraries
+    # MUST fail-soft (`RbsLoader#build_env` already filters
+    # through `has_library?`). The default set covers the common
+    # stdlib surface a Ruby program is likely to import
+    # (`pathname`, `optparse`, `json`, `yaml`, `fileutils`,
+    # `tempfile`, `uri`, `logger`, `date`) plus the analyzer-
+    # adjacent gems shipping their own RBS in this bundle
+    # (`prism`, `rbs`). On hosts where one of these libraries is
+    # not installed, the loader silently drops it.
+    #
+    # Callers MAY add to the default by passing
+    # `libraries: %w[csv ...]`; the explicit list is appended to
+    # `DEFAULT_LIBRARIES` and de-duplicated. Callers that need
+    # a strictly RBS-core view MUST construct an `RbsLoader`
+    # directly instead of going through `for_project`.
+    DEFAULT_LIBRARIES = %w[
+      pathname optparse json yaml fileutils tempfile uri logger date
+      prism rbs
+    ].freeze
+
+    attr_reader :class_registry, :rbs_loader
+
+    # @param class_registry [Rigor::Environment::ClassRegistry]
+    # @param rbs_loader [Rigor::Environment::RbsLoader, nil] when nil the
+    #   environment is "RBS-blind"; useful in tests that want to assert
+    #   how the engine behaves without RBS data. The default Environment
+    #   wires the shared core loader, which is itself lazy: requesting an
+    #   environment instance does NOT load RBS until a method or class
+    #   query actually consults the loader.
+    def initialize(class_registry: ClassRegistry.default, rbs_loader: nil)
+      @class_registry = class_registry
+      @rbs_loader = rbs_loader
+      freeze
+    end
+
+    class << self
+      def default
+        @default ||= new(rbs_loader: RbsLoader.default).freeze
+      end
+
+      # Builds an Environment that consults the project's local
+      # signatures and any opt-in stdlib libraries on top of RBS core.
+      #
+      # @param root [String, Pathname] project root used to auto-detect
+      #   the default signature path. Defaults to the current working
+      #   directory.
+      # @param libraries [Array<String, Symbol>] additional stdlib
+      #   libraries to load on top of {DEFAULT_LIBRARIES}. The
+      #   final list is the union of the two, de-duplicated while
+      #   preserving order. Pass an empty array (the default) to
+      #   load only the defaults.
+      # @param signature_paths [Array<String, Pathname>, nil] explicit
+      #   list of `sig/`-style directories. When `nil` (the default),
+      #   the canonical project layout `<root>/sig` is used if it
+      #   exists, otherwise no signature path is loaded.
+      # @return [Rigor::Environment]
+      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil)
+        resolved_paths = signature_paths || default_signature_paths(root)
+        merged_libraries = (DEFAULT_LIBRARIES + libraries.map(&:to_s)).uniq
+        loader = RbsLoader.new(libraries: merged_libraries, signature_paths: resolved_paths)
+        new(rbs_loader: loader)
+      end
+
+      private
+
+      def default_signature_paths(root)
+        sig = Pathname(root) / DEFAULT_PROJECT_SIG_DIR
+        sig.directory? ? [sig] : []
+      end
+    end
+
+    # Resolves a constant name to a Rigor::Type::Nominal (the *instance*
+    # type carrier). Consults the static class registry first (cheap,
+    # hardcoded), then falls back to the RBS loader. Returns nil when
+    # the name is unknown to both.
+    #
+    # NOTE: This is the construction helper for "an instance of class
+    # `Foo`". For "the class object `Foo` itself" (the value of the
+    # constant), use {#singleton_for_name} instead.
+    def nominal_for_name(name)
+      registered = class_registry.nominal_for_name(name)
+      return registered if registered
+
+      class_known_in_rbs?(name) ? Type::Combinator.nominal_of(name.to_s) : nil
+    end
+
+    # Resolves a constant name to a Rigor::Type::Singleton (the *class
+    # object* carrier). The expression `Foo` evaluates to the class
+    # object, whose RBS type is `singleton(Foo)` -- this method is the
+    # corresponding Rigor construction helper.
+    #
+    # The lookup uses the same registry/RBS chain as {#nominal_for_name}
+    # so a class is either known to both queries or to neither.
+    def singleton_for_name(name)
+      return nil unless class_known?(name)
+
+      Type::Combinator.singleton_of(name.to_s)
+    end
+
+    # Slice A constant-value lookup. Returns the translated
+    # `Rigor::Type` for an RBS-declared **non-class** constant
+    # (`Rigor::Analysis::FactStore::BUCKETS: Array[Symbol]`,
+    # `Rigor::Configuration::DEFAULT_PATH: String`, ...) or `nil`
+    # when no RBS constant declaration covers `name`. This is the
+    # value-bearing counterpart of {#singleton_for_name}, which
+    # only resolves names that name a class or module. Callers
+    # that need to type a `Prism::ConstantReadNode`/
+    # `Prism::ConstantPathNode` MUST consult {#singleton_for_name}
+    # first and fall through to this query when the constant is
+    # not a class.
+    def constant_for_name(name)
+      return nil if rbs_loader.nil?
+
+      rbs_loader.constant_type(name.to_s)
+    end
+
+    # Returns true when the constant name is known to either the static
+    # registry or the RBS loader. Useful for callers that only need a
+    # presence check without materialising a type carrier.
+    def class_known?(name)
+      return true if class_registry.nominal_for_name(name)
+
+      class_known_in_rbs?(name)
+    end
+
+    # Compares two class/module names using analyzer-owned class data.
+    # Returns `:equal`, `:subclass`, `:superclass`, `:disjoint`, or
+    # `:unknown`. The static registry handles built-ins cheaply; the RBS
+    # loader handles project/stdlib classes without relying on host Ruby
+    # constants being loaded.
+    def class_ordering(lhs, rhs)
+      lhs = normalize_class_name(lhs)
+      rhs = normalize_class_name(rhs)
+      return :equal if lhs == rhs
+
+      registry_result = class_registry.class_ordering(lhs, rhs)
+      return registry_result unless registry_result == :unknown
+
+      return :unknown unless rbs_loader
+
+      rbs_loader.class_ordering(lhs, rhs)
+    end
+
+    private
+
+    def class_known_in_rbs?(name)
+      return false unless rbs_loader
+
+      rbs_loader.class_known?(name)
+    end
+
+    def normalize_class_name(name)
+      name.to_s.delete_prefix("::")
+    end
+  end
+end