docscribe 1.4.2 → 1.5.1

data/lib/docscribe/types/rbs/provider.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'pathname'
+require 'yaml'
 require 'docscribe/types/signature'
 require 'docscribe/types/rbs/type_formatter'
 require 'docscribe/types/rbs/collection_loader'
@@ -14,18 +15,19 @@ module Docscribe
       # The provider returns Docscribe's normalized signature model so the rest of
       # the pipeline can stay independent of the underlying signature source.
       class Provider
+        # Initialize
+        #
         # @param [Array<String>] sig_dirs directories containing `.rbs` files
         # @param [Array<String>] collection_dirs RBS collection directories
-        #   (loaded separately; on error they are silently dropped and only
-        #   user sig_dirs are used)
         # @param [Boolean] collapse_generics whether generic container types
-        #   should be simplified during formatting
-        # @return [Object]
-        def initialize(sig_dirs:, collection_dirs: [], collapse_generics: false)
+        # @param [Boolean] collapse_object_generics collapse Object generics flag
+        # @return [void]
+        def initialize(sig_dirs:, collection_dirs: [], collapse_generics: false, collapse_object_generics: false)
           require 'rbs'
           @sig_dirs = Array(sig_dirs).map(&:to_s)
           @collection_dirs = Array(collection_dirs).map(&:to_s)
           @collapse_generics = !!collapse_generics
+          @collapse_object_generics = !!collapse_object_generics
           @env = nil
           @builder = nil
           @warned = false
@@ -42,6 +44,8 @@ module Docscribe
         # @raise [::RBS::BaseError]
         # @raise [StandardError]
         # @return [Docscribe::Types::MethodSignature, nil]
+        # @return [nil] if ::RBS::BaseError
+        # @return [nil] if StandardError
         def signature_for(container:, scope:, name:)
           load_env!
           lookup_signature(container, scope, name)
@@ -63,8 +67,6 @@ module Docscribe
         # dirs are dropped and only user sig_dirs are used.
         #
         # @private
-        # @raise [::RBS::BaseError]
-        # @raise [StandardError]
         # @return [void]
         def load_env!
           return if @env && @builder
@@ -84,13 +86,16 @@ module Docscribe
         # @return [Docscribe::Types::MethodSignature, nil]
         def lookup_signature(container, scope, name)
           definition = definition_for(container: container, scope: scope)
+          return nil unless definition
+
           method_def = definition.methods[name.to_sym]
           return nil unless method_def
 
           method_type = method_def.method_types.first
           return nil unless method_type
 
-          build_signature(method_type.type)
+          func = method_type.type #: ::RBS::Types::Function
+          build_signature(func)
         end
 
         # Try building an environment from combined dirs, falling back to
@@ -98,32 +103,103 @@ module Docscribe
         #
         # @private
         # @param [Array<String>] all_dirs combined sig and collection dirs
-        # @param [Array<String>] collection_dirs
+        # @param [Array<String>] collection_dirs RBS collection directories
         # @raise [::RBS::BaseError]
         # @raise [StandardError]
-        # @return [::RBS::Environment]
+        # @return [RBS::Environment]
+        # @return [RBS::Environment] if ::RBS::BaseError
         def try_with_fallback_build_env(all_dirs, collection_dirs)
-          build_env(all_dirs)
+          # First attempt: load core types + all dirs (sig + collection).
+          # If duplicate declarations occur (stdlib gem in both `library: 'rbs'`
+          # and collection), retry with individual collection gem dirs,
+          # skipping those already provided by the rbs stdlib.
+          build_env_with_collection(all_dirs, collection_dirs)
         rescue ::RBS::BaseError => e
           raise unless collection_dirs.any? && !@collection_dropped
 
           @collection_dropped = true
-          if ENV['DOCSCRIBE_RBS_DEBUG'] == '1'
-            warn "Docscribe: RBS collection error (#{e.class}), dropping collection dirs. " \
-                 'Set DOCSCRIBE_RBS_DEBUG=1 for details.'
-          end
+          warn "Docscribe: RBS collection error (#{e.class}), dropping collection dirs. " \
+               'Set DOCSCRIBE_RBS_DEBUG=1 for details.'
           build_env(@sig_dirs)
         end
 
+        # Build the environment, handling potential duplicate declarations
+        # between rbs stdlib and collection gems.
+        #
+        # @private
+        # @param [Array<String>] all_dirs combined sig and collection dirs
+        # @param [Array<String>] collection_dirs RBS collection directories
+        # @return [RBS::Environment]
+        def build_env_with_collection(all_dirs, collection_dirs)
+          loader = ::RBS::EnvironmentLoader.new
+          loader.add(library: 'rbs') # steep:ignore
+          load_stdlib_libraries!(loader)
+          add_dirs_to_loader!(loader, all_dirs, collection_dirs)
+          env = ::RBS::Environment.from_loader(loader).resolve_type_names
+          @builder = ::RBS::DefinitionBuilder.new(env: env)
+          env
+        end
+
+        # Add directories to the loader, handling collection dirs separately.
+        #
+        # @private
+        # @param [RBS::EnvironmentLoader] loader
+        # @param [Array<String>] all_dirs
+        # @param [Array<String>] collection_dirs
+        # @return [void]
+        def add_dirs_to_loader!(loader, all_dirs, collection_dirs)
+          stdlib = stdlib_gem_names
+          all_dirs.each do |dir|
+            path = Pathname(dir)
+            next unless path.directory?
+
+            if collection_dirs.include?(dir)
+              add_collection_gem_dirs(loader, path, stdlib)
+            else
+              loader.add(path: path)
+            end
+          end
+        end
+
+        # Add individual collection gem directories to the loader.
+        #
+        # @private
+        # @param [RBS::EnvironmentLoader] loader
+        # @param [Pathname] path
+        # @param [Array<String>] stdlib
+        # @return [void]
+        def add_collection_gem_dirs(loader, path, stdlib)
+          path.children.each do |child|
+            next unless child.directory?
+            next if stdlib.include?(child.basename.to_s)
+
+            loader.add(path: child)
+          end
+        end
+
+        # Names of stdlib gems bundled with the `rbs` gem.
+        #
+        # @private
+        # @raise [StandardError]
+        # @return [Array<String>]
+        # @return [Array] if StandardError
+        def stdlib_gem_names
+          rbs_spec = Gem::Specification.find_by_name('rbs')
+          stdlib_dir = File.join(rbs_spec.gem_dir, 'stdlib')
+          Dir.children(stdlib_dir)
+        rescue StandardError
+          []
+        end
+
         # Build an RBS environment from the given directories.
         #
         # @private
-        # @param [Array<String>] dirs
-        # @return [::RBS::Environment]
+        # @param [Array<String>] dirs directories to load RBS from
+        # @return [RBS::Environment]
         def build_env(dirs)
           loader = ::RBS::EnvironmentLoader.new
-          # Load core types transitively
-          loader.add(library: 'rbs')
+          loader.add(library: 'rbs') # steep:ignore
+          load_stdlib_libraries!(loader)
 
           dirs.each do |dir|
             path = Pathname(dir)
@@ -135,14 +211,54 @@ module Docscribe
           env
         end
 
+        # Load stdlib RBS libraries declared in rbs_collection.lock.yaml.
+        #
+        # Without this, RBS types defined in user sig/ files (e.g. UNIXSocket)
+        # fail to resolve and the entire RBS environment breaks, causing all
+        # type lookups to silently fall back to inference.
+        #
+        # @private
+        # @param [RBS::EnvironmentLoader] loader
+        # @raise [StandardError]
+        # @return [void]
+        # @return [nil] if StandardError
+        def load_stdlib_libraries!(loader)
+          lock_path = File.join(Dir.pwd, 'rbs_collection.lock.yaml')
+          return unless File.exist?(lock_path)
+
+          lock = YAML.safe_load_file(lock_path) # steep:ignore
+          (lock['gems'] || []).each { |gem| add_stdlib_gem(loader, gem) }
+        rescue StandardError => e
+          warn "Docscribe: Failed to parse rbs_collection.lock.yaml: #{e.message}"
+        end
+
+        # Add a single stdlib gem from the lock file to the loader.
+        #
+        # @private
+        # @param [RBS::EnvironmentLoader] loader
+        # @param [Object] gem gem entry from rbs_collection.lock.yaml
+        # @raise [StandardError]
+        # @return [void]
+        # @return [nil] if StandardError
+        def add_stdlib_gem(loader, gem)
+          return unless gem.is_a?(Hash) && gem.dig('source', 'type') == 'stdlib'
+
+          loader.add(library: gem['name']) # steep:ignore
+        rescue StandardError => e
+          warn "Docscribe: Failed to load stdlib RBS library '#{gem['name']}': #{e.message}"
+        end
+
         # Build the appropriate instance or singleton definition for a container.
         #
         # @private
-        # @param [String] container
-        # @param [Symbol] scope
-        # @return [Object]
+        # @param [String] container fully qualified class/module name
+        # @param [Symbol] scope :instance or :class
+        # @return [RBS::Definition, nil]
         def definition_for(container:, scope:)
+          container = container.sub(/\[.*\]/, '').sub(/<.*>/, '')
           type_name = parse_type_name(absolute_const(container))
+          return nil unless @builder&.env&.type_name?(type_name)
+
           scope == :class ? @builder&.build_singleton(type_name) : @builder&.build_instance(type_name)
         end
 
@@ -153,7 +269,7 @@ module Docscribe
         #
         # @private
         # @param [String] string e.g. "::Irb::Autosuggestions"
-        # @return [::RBS::TypeName]
+        # @return [RBS::TypeName]
         def parse_type_name(string)
           absolute = string.start_with?('::')
           *path, name = string.delete_prefix('::').split('::').map(&:to_sym)
@@ -167,7 +283,7 @@ module Docscribe
         # Normalize a container name into an absolute constant path.
         #
         # @private
-        # @param [String] container
+        # @param [String] container fully qualified class/module name
         # @return [String]
         def absolute_const(container)
           s = container.to_s
@@ -178,40 +294,49 @@ module Docscribe
         # model.
         #
         # @private
-        # @param [::RBS::Types::Function] func
+        # @param [RBS::Types::Function] func RBS function type to convert
         # @return [Docscribe::Types::MethodSignature]
         def build_signature(func)
+          param_types, positional_types = build_param_types(func)
           MethodSignature.new(
             return_type: format_type(func.return_type),
-            param_types: build_param_types(func),
+            param_types: param_types,
+            positional_types: positional_types,
             rest_positional: build_rest_positional(func),
             rest_keywords: build_rest_keywords(func)
           )
         end
 
-        # Build a name => type map for positional and keyword parameters.
+        # Build a name => type map and positional type list for all
+        # positional and keyword parameters.
+        #
+        # Returns [param_types (Hash), positional_types (Array)].
+        # positional_types includes ALL positional params in order (named
+        # and unnamed) so callers can fall back to positional matching when
+        # the RBS signature omits parameter names.
         #
         # @private
-        # @param [::RBS::Types::Function] func
-        # @return [Hash{String => String}]
+        # @param [RBS::Types::Function] func RBS function to extract params
+        # @return [(Hash<String, String>, Array<String>)]
         def build_param_types(func)
           param_types = {} #: Hash[String, String]
+          positional_types = [] #: Array[String]
 
-          add_positionals!(param_types, func.required_positionals)
-          add_positionals!(param_types, func.optional_positionals)
-          add_positionals!(param_types, func.trailing_positionals)
+          collect_positionals!(param_types, positional_types, func.required_positionals)
+          collect_positionals!(param_types, positional_types, func.optional_positionals)
+          collect_positionals!(param_types, positional_types, func.trailing_positionals)
 
           add_keywords!(param_types, func.required_keywords)
           add_keywords!(param_types, func.optional_keywords)
 
-          param_types
+          [param_types, positional_types]
         end
 
         # Add keyword parameters to the normalized parameter map.
         #
         # @private
-        # @param [Hash{String => String}] param_types
-        # @param [Hash{Symbol => Object}] keywords
+        # @param [Hash<String, String>] param_types normalized param type map
+        # @param [Hash<Symbol, RBS::Types::Function::Param>] keywords keyword parameter entries
         # @return [void]
         def add_keywords!(param_types, keywords)
           keywords.each do |kw, p|
@@ -219,24 +344,26 @@ module Docscribe
           end
         end
 
-        # Add named positional parameters to the normalized parameter map.
+        # Collect positional parameter types into both the name-keyed hash
+        # (when a name is available) and the ordered-position list (always).
         #
         # @private
-        # @param [Hash{String => String}] param_types
-        # @param [Array<Object>] list
+        # @param [Hash<String, String>] param_types normalized param type map
+        # @param [Array<String>] positional_types ordered type list
+        # @param [Array<RBS::Types::Function::Param>] list positional parameter objects
         # @return [void]
-        def add_positionals!(param_types, list)
+        def collect_positionals!(param_types, positional_types, list)
           list.each do |p|
-            next unless p.name
-
-            param_types[p.name.to_s] = format_type(p.type)
+            type_str = format_type(p.type)
+            positional_types << type_str
+            param_types[p.name.to_s] = type_str if p.name
           end
         end
 
         # Build normalized `*args` metadata.
         #
         # @private
-        # @param [::RBS::Types::Function] func
+        # @param [RBS::Types::Function] func RBS function for rest params
         # @return [Docscribe::Types::RestPositional, nil]
         def build_rest_positional(func)
           rp = func.rest_positionals
@@ -251,7 +378,7 @@ module Docscribe
         # Build normalized `**kwargs` metadata.
         #
         # @private
-        # @param [::RBS::Types::Function] func
+        # @param [RBS::Types::Function] func RBS function for rest keywords
         # @return [Docscribe::Types::RestKeywords, nil]
         def build_rest_keywords(func)
           rk = func.rest_keywords
@@ -267,21 +394,21 @@ module Docscribe
         # generated comments.
         #
         # @private
-        # @param [Object] type
+        # @param [Docscribe::Types::RBS::TypeFormatter::rbs_type] type RBS type object to format
         # @return [String]
         def format_type(type)
           Docscribe::Types::RBS::TypeFormatter.to_yard(
             type,
-            collapse_generics: @collapse_generics
+            collapse_generics: @collapse_generics,
+            collapse_object_generics: @collapse_object_generics
           )
         end
 
         # Emit a formatted RBS error warning with context-specific messaging.
         #
         # @private
-        # @param [StandardError] e the raised exception
+        # @param [RBS::BaseError, StandardError] error the raised exception
         # @param [String] context human-readable context label
-        # @param [StandardError] error the raised exception
         # @return [void]
         def handle_rbs_error(error, context)
           case error
@@ -295,13 +422,12 @@ module Docscribe
           end
         end
 
-        # Print one debug warning per provider instance when debugging is enabled.
+        # Print one warning per provider instance (avoiding repeated spam).
         #
         # @private
-        # @param [String] msg
+        # @param [String] msg warning message text
         # @return [void]
         def warn_once(msg)
-          return unless ENV['DOCSCRIBE_RBS_DEBUG'] == '1'
           return if @warned
 
           @warned = true