docscribe 1.4.1 → 1.5.0

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

@@ -14,18 +14,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
@@ -41,27 +42,17 @@ module Docscribe
         # @param [Symbol, String] name method name
         # @raise [::RBS::BaseError]
         # @raise [StandardError]
-        # @return [Docscribe::Types::MethodSignature, nil]
+        # @return [Docscribe::Types::MethodSignature, nil] if StandardError
+        # @return [nil] if ::RBS::BaseError
+        # @return [nil] if StandardError
         def signature_for(container:, scope:, name:)
           load_env!
-
-          definition = definition_for(container: container, scope: scope)
-          method_def = definition.methods[name.to_sym]
-          return nil unless method_def
-
-          method_type = method_def.method_types.first
-          return nil unless method_type
-
-          func = method_type.type
-          build_signature(func)
+          lookup_signature(container, scope, name)
         rescue ::RBS::BaseError => e
-          warn_once("Docscribe: RBS error: #{e.class}: #{e.message}")
+          handle_rbs_error(e, 'RBS error')
           nil
         rescue StandardError => e
-          warn_once(
-            'Docscribe: RBS integration failed (falling back to inference): ' \
-            "#{e.class}: #{e.message}\nFeel free to open an issue on github."
-          )
+          handle_rbs_error(e, 'RBS integration failed (falling back to inference)')
           nil
         end
 
@@ -75,33 +66,69 @@ 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
 
-          @env = build_env(@sig_dirs + @collection_dirs)
+          @env = try_with_fallback_build_env(
+            @sig_dirs + @collection_dirs,
+            @collection_dirs
+          )
+        end
+
+        # Look up a method signature from the loaded RBS definition builder.
+        #
+        # @private
+        # @param [String] container fully qualified class/module name
+        # @param [Symbol] scope :instance or :class
+        # @param [Symbol, String] name method name to look up
+        # @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
+
+          func = method_type.type #: ::RBS::Types::Function
+          build_signature(func)
+        end
+
+        # Try building an environment from combined dirs, falling back to
+        # user-only dirs on failure when collection dirs are present.
+        #
+        # @private
+        # @param [Array<String>] all_dirs combined sig and collection dirs
+        # @param [Array<String>] collection_dirs RBS collection directories
+        # @raise [::RBS::BaseError]
+        # @raise [StandardError]
+        # @return [RBS::Environment] if ::RBS::BaseError
+        # @return [Object] if ::RBS::BaseError
+        def try_with_fallback_build_env(all_dirs, collection_dirs)
+          build_env(all_dirs)
         rescue ::RBS::BaseError => e
-          raise unless @collection_dirs.any? && !@collection_dropped
+          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
-          @env = build_env(@sig_dirs)
+          build_env(@sig_dirs)
         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
 
           dirs.each do |dir|
             path = Pathname(dir)
@@ -116,12 +143,12 @@ module Docscribe
         # 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:)
           type_name = parse_type_name(absolute_const(container))
-          scope == :class ? @builder.build_singleton(type_name) : @builder.build_instance(type_name)
+          scope == :class ? @builder&.build_singleton(type_name) : @builder&.build_instance(type_name)
         end
 
         # Parse a fully-qualified constant string into an RBS TypeName.
@@ -131,10 +158,11 @@ 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)
+          name ||= :Object
           ::RBS::TypeName.new(
             name: name,
             namespace: ::RBS::Namespace.new(path: path, absolute: absolute)
@@ -144,7 +172,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
@@ -155,58 +183,76 @@ 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 = {}
+          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)
 
-          func.required_keywords.each do |kw, p|
-            param_types[kw.to_s] = format_type(p.type)
-          end
+          add_keywords!(param_types, func.required_keywords)
+          add_keywords!(param_types, func.optional_keywords)
 
-          func.optional_keywords.each do |kw, p|
+          [param_types, positional_types]
+        end
+
+        # Add keyword parameters to the normalized parameter map.
+        #
+        # @private
+        # @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|
             param_types[kw.to_s] = format_type(p.type)
           end
-
-          param_types
         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
@@ -221,7 +267,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
@@ -237,19 +283,38 @@ 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 [RBS::BaseError, StandardError] error the raised exception
+        # @param [String] context human-readable context label
+        # @return [void]
+        def handle_rbs_error(error, context)
+          case error
+          when ::RBS::BaseError
+            warn_once("Docscribe: #{context}: #{error.class}: #{error.message}")
+          else
+            warn_once(
+              "Docscribe: #{context}: #{error.class}: #{error.message}\n" \
+              'Feel free to open an issue on github.'
+            )
+          end
+        end
+
         # Print one debug warning per provider instance when debugging is enabled.
         #
         # @private
-        # @param [String] msg
+        # @param [String] msg warning message text
         # @return [void]
         def warn_once(msg)
           return unless ENV['DOCSCRIBE_RBS_DEBUG'] == '1'