docscribe 1.4.2 → 1.5.0

data/lib/docscribe/types/signature.rb

@@ -2,64 +2,44 @@
 
 module Docscribe
   module Types
-    # Simplified view of an RBS method signature for Docscribe.
-    #
-    # @!attribute return_type
-    #   @return [String] formatted return type for YARD output
-    # @!attribute param_types
-    #   @return [Hash{String=>String}] mapping of parameter name to formatted type
-    # @!attribute rest_positional
-    #   @return [RestPositional, nil] info for `*args`
-    # @!attribute rest_keywords
-    #   @return [RestKeywords, nil] info for `**kwargs`
-    #
     # @!attribute [rw] return_type
-    #   @return [Object]
-    #   @param [Object] value
+    #   @return [String]
+    #   @param [String] value
     #
     # @!attribute [rw] param_types
-    #   @return [Object]
-    #   @param [Object] value
+    #   @return [Hash<String, String>]
+    #   @param [Hash<String, String>] value
+    #
+    # @!attribute [rw] positional_types
+    #   @return [Array<String>]
+    #   @param [Array<String>] value
     #
     # @!attribute [rw] rest_positional
-    #   @return [Object]
-    #   @param [Object] value
+    #   @return [Docscribe::Types::RestPositional, nil]
+    #   @param [Docscribe::Types::RestPositional, nil] value
     #
     # @!attribute [rw] rest_keywords
-    #   @return [Object]
-    #   @param [Object] value
-    MethodSignature = Struct.new(:return_type, :param_types, :rest_positional, :rest_keywords, keyword_init: true)
+    #   @return [Docscribe::Types::RestKeywords, nil]
+    #   @param [Docscribe::Types::RestKeywords, nil] value
+    MethodSignature = Struct.new(:return_type, :param_types, :positional_types, :rest_positional, :rest_keywords,
+                                 keyword_init: true)
 
-    # Simplified representation of an RBS rest-positional parameter.
-    #
-    # @!attribute name
-    #   @return [String, nil] parameter name in RBS, if present
-    # @!attribute element_type
-    #   @return [String] formatted element type
-    #
     # @!attribute [rw] name
-    #   @return [Object]
-    #   @param [Object] value
+    #   @return [String, nil]
+    #   @param [String, nil] value
     #
     # @!attribute [rw] element_type
-    #   @return [Object]
-    #   @param [Object] value
+    #   @return [String]
+    #   @param [String] value
     RestPositional = Struct.new(:name, :element_type, keyword_init: true)
 
-    # Simplified representation of an RBS rest-keyword parameter.
-    #
-    # @!attribute name
-    #   @return [String, nil] parameter name in RBS, if present
-    # @!attribute type
-    #   @return [String] formatted kwargs type
-    #
     # @!attribute [rw] name
-    #   @return [Object]
-    #   @param [Object] value
+    #   @return [String, nil]
+    #   @param [String, nil] value
     #
     # @!attribute [rw] type
-    #   @return [Object]
-    #   @param [Object] value
+    #   @return [String]
+    #   @param [String] value
     RestKeywords = Struct.new(:name, :type, keyword_init: true)
   end
 end

data/lib/docscribe/types/sorbet/base_provider.rb

@@ -15,9 +15,10 @@ module Docscribe
       # - SourceProvider => inline `sig` declarations in the current Ruby file
       # - RBIProvider    => project RBI files
       class BaseProvider
+        # Initialize
+        #
         # @param [Boolean] collapse_generics whether generic container details
-        #   should be simplified during formatting
-        # @return [Object]
+        # @return [void]
         def initialize(collapse_generics: false)
           require 'rbs'
           @collapse_generics = !!collapse_generics
@@ -49,7 +50,9 @@ module Docscribe
         # @raise [::RBS::BaseError]
         # @raise [SyntaxError]
         # @raise [StandardError]
-        # @return [void]
+        # @return [void] if ::RBS::BaseError, SyntaxError, StandardError
+        # @return [nil] if LoadError
+        # @return [nil] if ::RBS::BaseError, SyntaxError, StandardError
         def load_from_string(source, label:)
           return unless defined?(RubyVM::AbstractSyntaxTree)
 
@@ -82,7 +85,7 @@ module Docscribe
         #
         # @private
         # @param [String] container normalized container name
-        # @param [Object] member
+        # @param [Object] member RBS method definition member
         # @return [void]
         def process_method_member(container, member)
           return unless method_definition_member?(member)
@@ -91,13 +94,15 @@ module Docscribe
           overload = member.overloads&.first
           return unless overload
 
-          func = overload.method_type.type
+          func = overload.method_type.type #: ::RBS::Types::Function
           @index[[container, scope, member.name.to_s.to_sym]] = build_signature(func)
         end
 
+        # Method definition member
+        #
         # @private
-        # @param [Object] member
-        # @return [Boolean]
+        # @param [Object] member member to check for method def
+        # @return [Boolean, nil]
         def method_definition_member?(member)
           defined?(::RBS::AST::Members::MethodDefinition) &&
             member.is_a?(::RBS::AST::Members::MethodDefinition)
@@ -106,7 +111,7 @@ module Docscribe
         # Convert an RBS function type into Docscribe's simplified signature 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)
           MethodSignature.new(
@@ -120,8 +125,8 @@ module Docscribe
         # Build a name => type map for ordinary positional/keyword parameters.
         #
         # @private
-        # @param [::RBS::Types::Function] func
-        # @return [Hash{String => String}]
+        # @param [RBS::Types::Function] func RBS function to extract params
+        # @return [Hash<String, String>]
         def build_param_types(func)
           param_types = {} #: Hash[String, String]
 
@@ -138,8 +143,8 @@ module Docscribe
         # 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|
@@ -150,8 +155,8 @@ module Docscribe
         # Add positional parameters with names to the normalized param map.
         #
         # @private
-        # @param [Hash{String => String}] param_types
-        # @param [Array<Object>] list
+        # @param [Hash<String, String>] param_types normalized param type map
+        # @param [Array<RBS::Types::Function::Param>] list positional parameter objects
         # @return [void]
         def add_positionals!(param_types, list)
           list.each do |p|
@@ -164,7 +169,7 @@ module Docscribe
         # 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
@@ -182,7 +187,7 @@ module Docscribe
         # YARD output, we expose that as a Hash keyed by Symbol.
         #
         # @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
@@ -200,7 +205,7 @@ 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(
@@ -212,7 +217,7 @@ module Docscribe
         # Normalize container names so lookups are consistent.
         #
         # @private
-        # @param [String] name
+        # @param [String] name method name
         # @return [String]
         def normalize_container(name)
           name.to_s.delete_prefix('::')
@@ -221,7 +226,7 @@ module Docscribe
         # 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'

data/lib/docscribe/types/sorbet/rbi_provider.rb

@@ -12,11 +12,11 @@ module Docscribe
       # any signatures that can be parsed are indexed into Docscribe's normalized
       # signature model.
       class RBIProvider < BaseProvider
+        # Initialize
+        #
         # @param [Array<String>] rbi_dirs directories scanned recursively for
-        #   `.rbi` files
         # @param [Boolean] collapse_generics whether generic container types
-        #   should be simplified during formatting
-        # @return [Object]
+        # @return [void]
         def initialize(rbi_dirs:, collapse_generics: false)
           super(collapse_generics: collapse_generics)
 

data/lib/docscribe/types/sorbet/source_provider.rb

@@ -10,11 +10,12 @@ module Docscribe
       # This provider parses the source being rewritten and indexes any leading
       # `sig` declarations it can resolve through the RBS RBI prototype bridge.
       class SourceProvider < BaseProvider
+        # Initialize
+        #
         # @param [String] source Ruby source containing inline `sig` declarations
         # @param [String] file source label used in diagnostics/debug warnings
         # @param [Boolean] collapse_generics whether generic container types
-        #   should be simplified during formatting
-        # @return [Object]
+        # @return [void]
         def initialize(source:, file:, collapse_generics: false)
           super(collapse_generics: collapse_generics)
           load_from_string(source, label: file)

data/lib/docscribe/types/yard/formatter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative 'types'
+
+module Docscribe
+  module Types
+    module Yard
+      # Converts YARD type AST to RBS type strings
+      module Formatter
+        class << self
+          # @param [Docscribe::Types::Yard::node?] node
+          # @return [String]
+          def to_rbs(node) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+            return 'untyped' if node.nil?
+
+            case node
+            when Named then format_named(node)
+            when Generic then format_generic(node)
+            when Union then format_union(node)
+            when Intersection then format_intersection(node)
+            when Optional then format_optional(node)
+            when Tuple then format_tuple(node)
+            when HashMap then format_hash_map(node)
+            when Literal then format_literal(node)
+            else 'untyped'
+            end
+          end
+
+          private
+
+          # @private
+          # @param [Docscribe::Types::Yard::Named] node
+          # @return [String]
+          def format_named(node)
+            case node.name
+            when 'Boolean' then 'bool'
+            when 'Object' then 'untyped'
+            else node.name
+            end
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Generic] node
+          # @return [String]
+          def format_generic(node)
+            "#{node.base}[#{node.args.map { |a| to_rbs(a) }.join(', ')}]"
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Union] node
+          # @return [String]
+          def format_union(node)
+            node.types.map { |t| to_rbs(t) }.join(' | ')
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Intersection] node
+          # @return [String]
+          def format_intersection(node)
+            node.types.map { |t| to_rbs(t) }.join(' & ')
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Optional] node
+          # @return [String]
+          def format_optional(node)
+            "#{to_rbs(node.type)}?"
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Tuple] node
+          # @return [String]
+          def format_tuple(node)
+            "[#{node.types.map { |t| to_rbs(t) }.join(', ')}]"
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::HashMap] node
+          # @return [String]
+          def format_hash_map(node)
+            "Hash[#{to_rbs(node.key_type)}, #{to_rbs(node.value_type)}]"
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Literal] node
+          # @return [String]
+          def format_literal(node)
+            case node.value
+            when 'void' then 'void'
+            when 'nil' then 'nil'
+            when 'self' then 'self'
+            when 'true', 'false' then 'bool'
+            else 'untyped'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/types/yard/parser.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require_relative 'types'
+
+module Docscribe
+  module Types
+    # YARD type parser
+    module Yard
+      class << self
+        # @param [String?] string
+        # @return [Docscribe::Types::Yard::node?]
+        def parse(string)
+          return nil if string.nil? || string.strip.empty?
+
+          Parser.new(string).parse
+        end
+      end
+
+      # Parses YARD type strings into an AST
+      class Parser
+        # @param [String] string
+        # @return [void]
+        def initialize(string)
+          @s = string.strip
+          @i = 0
+        end
+
+        # @return [Docscribe::Types::Yard::node]
+        def parse
+          skip_space
+          node = parse_union
+          skip_space
+          node
+        end
+
+        private
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_union
+          types = [parse_intersection]
+          skip_space
+          while @i < @s.length && @s[@i] == ','
+            @i += 1
+            skip_space
+            types << parse_intersection
+            skip_space
+          end
+          types.size == 1 ? types.first : Union.new(types: types)
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_intersection
+          types = [parse_optional]
+          skip_space
+          while @i < @s.length && @s[@i] == '&'
+            @i += 1
+            skip_space
+            types << parse_optional
+            skip_space
+          end
+          types.size == 1 ? types.first : Intersection.new(types: types)
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_optional
+          type = parse_primary
+          skip_space
+          if @i < @s.length && @s[@i] == '?'
+            @i += 1
+            Optional.new(type: type)
+          else
+            type
+          end
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_primary
+          skip_space
+          case peek
+          when '(' then parse_tuple
+          when '{' then parse_hash_map
+          when '#' then parse_duck_type
+          else
+            parse_named_type
+          end
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::Named, Docscribe::Types::Yard::Literal, Docscribe::Types::Yard::Generic, Docscribe::Types::Yard::HashMap]
+        def parse_named_type
+          name = scan_name
+          return Literal.new(value: name) if literal?(name)
+
+          skip_space
+          if @i < @s.length && @s[@i] == '<'
+            parse_generic(Named.new(name: name))
+          elsif @i < @s.length && @s[@i] == '{'
+            parse_named_hash_map
+          else
+            Named.new(name: name)
+          end
+        end
+
+        # @private
+        # @param [Docscribe::Types::Yard::Named] base
+        # @return [Docscribe::Types::Yard::Generic]
+        def parse_generic(base)
+          @i += 1
+          args = parse_generic_args
+          @i += 1 if @i < @s.length && @s[@i] == '>'
+          Generic.new(base: base.name, args: args)
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_generic_arg
+          types = [parse_intersection]
+          skip_space
+          while @i < @s.length && @s[@i] == '|'
+            @i += 1
+            skip_space
+            types << parse_intersection
+            skip_space
+          end
+          types.size == 1 ? types.first : Union.new(types: types)
+        end
+
+        # @private
+        # @return [Array<Docscribe::Types::Yard::node>]
+        def parse_generic_args
+          args = [] #: Array[untyped]
+          skip_space
+          while @i < @s.length && @s[@i] != '>'
+            args << parse_generic_arg
+            skip_space
+            next unless @i < @s.length && @s[@i] == ','
+
+            @i += 1
+            skip_space
+          end
+          args
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::Tuple]
+        def parse_tuple
+          @i += 1
+          types = [] #: Array[untyped]
+          while @i < @s.length && @s[@i] != ')'
+            types << parse_tuple_element
+            @i += 1 and skip_space if @s[@i] == ','
+          end
+          @i += 1 if @s[@i] == ')'
+          Tuple.new(types: types)
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_tuple_element
+          type = parse_intersection
+          skip_space
+          if @i < @s.length && @s[@i] == '?'
+            @i += 1
+            Optional.new(type: type)
+          else
+            type
+          end
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::HashMap]
+        def parse_hash_map
+          @i += 1
+          key = parse_union
+          @i += 2 if @s[@i..(@i + 1)] == '=>'
+          value = parse_union
+          @i += 1 if @s[@i] == '}'
+          HashMap.new(key_type: key, value_type: value)
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::HashMap]
+        def parse_named_hash_map
+          parse_hash_map
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::Duck]
+        def parse_duck_type
+          methods = [] #: Array[String]
+          while @i < @s.length && @s[@i] == '#'
+            @i += 1
+            name = scan_name
+            methods << name
+            skip_space
+          end
+          Duck.new(method_names: methods)
+        end
+
+        # @private
+        # @return [String]
+        def scan_name
+          start = @i
+          @i += 1 while @i < @s.length && name_char?(@s[@i])
+          @s[start...@i]
+        end
+
+        # @private
+        # @param [String] char
+        # @return [Boolean]
+        def name_char?(char)
+          char.match?(/[a-zA-Z0-9_:]/)
+        end
+
+        # @private
+        # @param [String] name
+        # @return [Boolean]
+        def literal?(name)
+          %w[void nil self true false].include?(name)
+        end
+
+        # @private
+        # @return [void]
+        def skip_space
+          @i += 1 while @i < @s.length && @s[@i].match?(/\s/)
+        end
+
+        # @private
+        # @return [String?]
+        def peek
+          @i < @s.length ? @s[@i] : nil
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/types/yard/types.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Types
+    module Yard
+      # @!attribute [rw] name
+      #   @return [String]
+      #   @param [String] value
+      Named = Struct.new(:name, keyword_init: true)
+      # @!attribute [rw] base
+      #   @return [String]
+      #   @param [String] value
+      #
+      # @!attribute [rw] args
+      #   @return [Array<Docscribe::Types::Yard::node>]
+      #   @param [Array<Docscribe::Types::Yard::node>] value
+      Generic = Struct.new(:base, :args, keyword_init: true)
+      # @!attribute [rw] types
+      #   @return [Array<Docscribe::Types::Yard::node>]
+      #   @param [Array<Docscribe::Types::Yard::node>] value
+      Union = Struct.new(:types, keyword_init: true)
+      # @!attribute [rw] types
+      #   @return [Array<Docscribe::Types::Yard::node>]
+      #   @param [Array<Docscribe::Types::Yard::node>] value
+      Intersection = Struct.new(:types, keyword_init: true)
+      # @!attribute [rw] type
+      #   @return [Docscribe::Types::Yard::node]
+      #   @param [Docscribe::Types::Yard::node] value
+      Optional = Struct.new(:type, keyword_init: true)
+      # @!attribute [rw] types
+      #   @return [Array<Docscribe::Types::Yard::node>]
+      #   @param [Array<Docscribe::Types::Yard::node>] value
+      Tuple = Struct.new(:types, keyword_init: true)
+      # @!attribute [rw] key_type
+      #   @return [Docscribe::Types::Yard::node]
+      #   @param [Docscribe::Types::Yard::node] value
+      #
+      # @!attribute [rw] value_type
+      #   @return [Docscribe::Types::Yard::node]
+      #   @param [Docscribe::Types::Yard::node] value
+      HashMap = Struct.new(:key_type, :value_type, keyword_init: true)
+      # @!attribute [rw] method_names
+      #   @return [Array<String>]
+      #   @param [Array<String>] value
+      Duck = Struct.new(:method_names, keyword_init: true)
+      # @!attribute [rw] value
+      #   @return [String]
+      #   @param [String] value
+      Literal = Struct.new(:value, keyword_init: true)
+    end
+  end
+end

data/lib/docscribe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docscribe
-  VERSION = '1.4.2'
+  VERSION = '1.5.0'
 end