docscribe 1.0.0 → 1.2.0

data/lib/docscribe/parsing.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'parser/source/buffer'
+require 'rubygems' # for Gem::Version
+
+module Docscribe
+  # Parser backend selection for Docscribe.
+  #
+  # Docscribe always works with parser-gem-compatible AST nodes (`Parser::AST::Node`)
+  # and parser source locations (`Parser::Source::*`) because rewriting relies on
+  # `Parser::Source::TreeRewriter`.
+  #
+  # On Ruby 3.4+, Prism can parse newer syntax before the parser gem fully supports it,
+  # so Docscribe can use Prism and translate the result into parser-gem-compatible nodes.
+  #
+  # Backends:
+  # - `:parser` => parser gem
+  # - `:prism`  => Prism + translation
+  # - `:auto`   => choose based on runtime Ruby version or env override
+  #
+  # You can force a backend with:
+  # - `DOCSCRIBE_PARSER_BACKEND=parser`
+  # - `DOCSCRIBE_PARSER_BACKEND=prism`
+  module Parsing
+    class << self
+      # Parse source code into a parser-gem-compatible AST.
+      #
+      # @param [String] code Ruby source
+      # @param [String] file source name used for parser locations
+      # @param [Symbol] backend :auto, :parser, or :prism
+      # @return [Parser::AST::Node, nil]
+      def parse(code, file: '(docscribe)', backend: :auto)
+        buffer = Parser::Source::Buffer.new(file, source: code)
+        parse_buffer(buffer, backend: backend)
+      end
+
+      # Parse a prepared source buffer into a parser-gem-compatible AST.
+      #
+      # @param [Parser::Source::Buffer] buffer
+      # @param [Symbol] backend :auto, :parser, or :prism
+      # @return [Parser::AST::Node, nil]
+      def parse_buffer(buffer, backend: :auto)
+        parser = parser_for(backend: backend)
+        parser.parse(buffer)
+      end
+
+      # Parse source code and also return comments when supported by the backend.
+      #
+      # @param [String] code Ruby source
+      # @param [String] file source name used for parser locations
+      # @param [Symbol] backend :auto, :parser, or :prism
+      # @return [Array<(Parser::AST::Node, Array)>]
+      def parse_with_comments(code, file: '(docscribe)', backend: :auto)
+        buffer = Parser::Source::Buffer.new(file, source: code)
+        parse_with_comments_buffer(buffer, backend: backend)
+      end
+
+      # Parse a prepared source buffer and also return comments when supported by the backend.
+      #
+      # @param [Parser::Source::Buffer] buffer
+      # @param [Symbol] backend :auto, :parser, or :prism
+      # @return [Array<(Parser::AST::Node, Array)>]
+      def parse_with_comments_buffer(buffer, backend: :auto)
+        parser = parser_for(backend: backend)
+        parser.parse_with_comments(buffer)
+      end
+
+      private
+
+      # Build the backend-specific parser object.
+      #
+      # @private
+      # @param [Symbol] backend
+      # @return [Object]
+      def parser_for(backend: :auto)
+        case backend(backend)
+        when :parser
+          require 'parser/current'
+          Parser::CurrentRuby.new
+        when :prism
+          require 'prism'
+          Prism::Translation::ParserCurrent.new
+        end
+      end
+
+      # Resolve the effective parser backend.
+      #
+      # Resolution order:
+      # - `DOCSCRIBE_PARSER_BACKEND` env var, if set
+      # - explicit `backend:` argument
+      # - auto choice based on Ruby version
+      #
+      # @private
+      # @param [Symbol] backend requested backend
+      # @raise [ArgumentError]
+      # @return [Symbol] :parser or :prism
+      def backend(backend = :auto)
+        env = ENV.fetch('DOCSCRIBE_PARSER_BACKEND') { nil }
+        backend = env.to_sym if env && !env.empty?
+
+        case backend
+        when :auto
+          ruby_gte_34? ? :prism : :parser
+        when :parser, :prism
+          backend
+        else
+          raise ArgumentError, "Unknown backend: #{backend.inspect}"
+        end
+      end
+
+      # Whether the current Ruby version is 3.4 or newer.
+      #
+      # @private
+      # @return [Boolean]
+      def ruby_gte_34?
+        Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.4')
+      end
+    end
+  end
+end

data/lib/docscribe/types/provider_chain.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Types
+    # Resolve method signatures by querying a list of providers in order.
+    #
+    # The first provider that returns a non-nil signature wins.
+    #
+    # This lets Docscribe combine multiple external type sources behind one
+    # interface, for example:
+    # - inline Sorbet signatures in the current file
+    # - Sorbet RBI files
+    # - RBS files
+    class ProviderChain
+      # @param [Array<#signature_for>] providers ordered signature providers
+      # @return [Object]
+      def initialize(*providers)
+        @providers = providers.compact
+      end
+
+      # Resolve a method signature from the first provider that can supply it.
+      #
+      # @param [String] container e.g. "MyModule::MyClass"
+      # @param [Symbol] scope :instance or :class
+      # @param [Symbol, String] name method name
+      # @return [Docscribe::Types::MethodSignature, nil]
+      def signature_for(container:, scope:, name:)
+        @providers.each do |provider|
+          sig = provider.signature_for(container: container, scope: scope, name: name)
+          return sig if sig
+        end
+
+        nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'docscribe/types/signature'
+require 'docscribe/types/rbs/type_formatter'
+
+module Docscribe
+  module Types
+    module RBS
+      # Resolve method signatures from `.rbs` files using the official RBS
+      # environment and definition builder APIs.
+      #
+      # The provider returns Docscribe's normalized signature model so the rest of
+      # the pipeline can stay independent of the underlying signature source.
+      class Provider
+        # @param [Array<String>] sig_dirs directories containing `.rbs` files
+        # @param [Boolean] collapse_generics whether generic container types
+        #   should be simplified during formatting
+        # @return [Object]
+        def initialize(sig_dirs:, collapse_generics: false)
+          require 'rbs'
+          @sig_dirs = Array(sig_dirs).map(&:to_s)
+          @collapse_generics = !!collapse_generics
+          @env = nil
+          @builder = nil
+          @warned = false
+        end
+
+        # Look up a normalized method signature from loaded RBS definitions.
+        #
+        # Returns nil when the method cannot be resolved or when RBS lookup fails.
+        #
+        # @param [String] container e.g. "MyModule::MyClass"
+        # @param [Symbol] scope :instance or :class
+        # @param [Symbol, String] name method name
+        # @raise [::RBS::BaseError]
+        # @raise [StandardError]
+        # @return [Docscribe::Types::MethodSignature, nil]
+        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)
+        rescue ::RBS::BaseError => e
+          warn_once("Docscribe: RBS error: #{e.class}: #{e.message}")
+          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."
+          )
+          nil
+        end
+
+        private
+
+        # Lazily load and resolve the RBS environment.
+        #
+        # @private
+        # @return [void]
+        def load_env!
+          return if @env && @builder
+
+          loader = ::RBS::EnvironmentLoader.new
+
+          @sig_dirs.each do |dir|
+            path = Pathname(dir)
+            loader.add(path: path) if path.directory?
+          end
+
+          @env = ::RBS::Environment.from_loader(loader).resolve_type_names
+          @builder = ::RBS::DefinitionBuilder.new(env: @env)
+        end
+
+        # Build the appropriate instance or singleton definition for a container.
+        #
+        # @private
+        # @param [String] container
+        # @param [Symbol] scope
+        # @return [Object]
+        def definition_for(container:, scope:)
+          type_name = ::RBS::TypeName.parse(absolute_const(container))
+          scope == :class ? @builder.build_singleton(type_name) : @builder.build_instance(type_name)
+        end
+
+        # Normalize a container name into an absolute constant path.
+        #
+        # @private
+        # @param [String] container
+        # @return [String]
+        def absolute_const(container)
+          s = container.to_s
+          s.start_with?('::') ? s : "::#{s}"
+        end
+
+        # Convert an RBS function type into Docscribe's simplified signature
+        # model.
+        #
+        # @private
+        # @param [::RBS::Types::Function] func
+        # @return [Docscribe::Types::MethodSignature]
+        def build_signature(func)
+          MethodSignature.new(
+            return_type: format_type(func.return_type),
+            param_types: build_param_types(func),
+            rest_positional: build_rest_positional(func),
+            rest_keywords: build_rest_keywords(func)
+          )
+        end
+
+        # Build a name => type map for positional and keyword parameters.
+        #
+        # @private
+        # @param [::RBS::Types::Function] func
+        # @return [Hash{String => String}]
+        def build_param_types(func)
+          param_types = {}
+
+          add_positionals!(param_types, func.required_positionals)
+          add_positionals!(param_types, func.optional_positionals)
+          add_positionals!(param_types, func.trailing_positionals)
+
+          func.required_keywords.each do |kw, p|
+            param_types[kw.to_s] = format_type(p.type)
+          end
+
+          func.optional_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.
+        #
+        # @private
+        # @param [Hash{String => String}] param_types
+        # @param [Array<Object>] list
+        # @return [void]
+        def add_positionals!(param_types, list)
+          list.each do |p|
+            next unless p.name
+
+            param_types[p.name.to_s] = format_type(p.type)
+          end
+        end
+
+        # Build normalized `*args` metadata.
+        #
+        # @private
+        # @param [::RBS::Types::Function] func
+        # @return [Docscribe::Types::RestPositional, nil]
+        def build_rest_positional(func)
+          rp = func.rest_positionals
+          return nil unless rp
+
+          RestPositional.new(
+            name: rp.name&.to_s,
+            element_type: format_type(rp.type)
+          )
+        end
+
+        # Build normalized `**kwargs` metadata.
+        #
+        # @private
+        # @param [::RBS::Types::Function] func
+        # @return [Docscribe::Types::RestKeywords, nil]
+        def build_rest_keywords(func)
+          rk = func.rest_keywords
+          return nil unless rk
+
+          RestKeywords.new(
+            name: rk.name&.to_s,
+            type: format_type(rk.type)
+          )
+        end
+
+        # Format an RBS type object into the YARD-ish type syntax used by
+        # generated comments.
+        #
+        # @private
+        # @param [Object] type
+        # @return [String]
+        def format_type(type)
+          Docscribe::Types::RBS::TypeFormatter.to_yard(
+            type,
+            collapse_generics: @collapse_generics
+          )
+        end
+
+        # Print one debug warning per provider instance when debugging is enabled.
+        #
+        # @private
+        # @param [String] msg
+        # @return [void]
+        def warn_once(msg)
+          return unless ENV['DOCSCRIBE_RBS_DEBUG'] == '1'
+          return if @warned
+
+          @warned = true
+          warn msg
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Types
+    module RBS
+      # Convert RBS type objects into YARD-ish type strings.
+      #
+      # This is intentionally best-effort formatting: YARD type syntax is simpler than RBS,
+      # so some information is collapsed or approximated.
+      module TypeFormatter
+        module_function
+
+        # Convert one RBS type object into a YARD-ish string.
+        #
+        # Supported categories include:
+        # - base types (`bool`, `nil`, `void`, `untyped`)
+        # - optional and union types
+        # - named types with optional generic arguments
+        # - literal types
+        # - Proc types
+        #
+        # @note module_function: when included, also defines #to_yard (instance visibility: private)
+        # @param [Object] type RBS type object
+        # @param [Boolean] collapse_generics whether generic arguments should be omitted
+        # @return [String]
+        def to_yard(type, collapse_generics: false)
+          return 'Object' unless type
+
+          # RBS is loaded lazily by the provider; constants below exist only when rbs is available.
+          case type
+          when ::RBS::Types::Bases::Any
+            'Object'
+          when ::RBS::Types::Bases::Bool
+            'Boolean'
+          when ::RBS::Types::Bases::Void
+            'void'
+          when ::RBS::Types::Bases::Nil
+            'nil'
+          when ::RBS::Types::Optional
+            "#{to_yard(type.type, collapse_generics: collapse_generics)}?"
+          when ::RBS::Types::Union
+            format_union(type, collapse_generics: collapse_generics)
+          when ::RBS::Types::ClassInstance,
+            ::RBS::Types::ClassSingleton,
+            ::RBS::Types::Interface,
+            ::RBS::Types::Alias
+            format_named(type, collapse_generics: collapse_generics)
+          when ::RBS::Types::Literal
+            literal_to_yard(type.literal)
+          when ::RBS::Types::Proc
+            'Proc'
+          else
+            fallback_string(type)
+          end
+        end
+
+        # Format an RBS union type as a comma-separated YARD union.
+        #
+        # Example:
+        # - `String | Integer | nil` => `"String, Integer, nil"`
+        #
+        # @note module_function: when included, also defines #format_union (instance visibility: private)
+        # @param [::RBS::Types::Union] type
+        # @param [Boolean] collapse_generics
+        # @return [String]
+        def format_union(type, collapse_generics:)
+          type.types.map { |t| to_yard(t, collapse_generics: collapse_generics) }
+              .uniq
+              .join(', ')
+        end
+
+        # Format a named RBS type, optionally preserving generic arguments.
+        #
+        # Examples:
+        # - `::String` => `"String"`
+        # - `::Hash[::Symbol, untyped]` => `"Hash<Symbol, Object>"`
+        # - with `collapse_generics: true` => `"Hash"`
+        #
+        # @note module_function: when included, also defines #format_named (instance visibility: private)
+        # @param [Object] type named RBS type
+        # @param [Boolean] collapse_generics
+        # @return [String]
+        def format_named(type, collapse_generics:)
+          name = type.name.to_s.delete_prefix('::')
+          args = type.respond_to?(:args) ? type.args : []
+
+          if args && !args.empty?
+            return name if collapse_generics
+
+            "#{name}<#{args.map { |a| to_yard(a, collapse_generics: collapse_generics) }.join(', ')}>"
+          else
+            name
+          end
+        end
+
+        # Map a literal Ruby value from an RBS literal type into a YARD-ish type name.
+        #
+        # @note module_function: when included, also defines #literal_to_yard (instance visibility: private)
+        # @param [Object] lit literal value
+        # @return [String]
+        def literal_to_yard(lit)
+          case lit
+          when Integer then 'Integer'
+          when Float   then 'Float'
+          when String  then 'String'
+          when Symbol  then 'Symbol'
+          when TrueClass, FalseClass then 'Boolean'
+          when NilClass then 'nil'
+          else 'Object'
+          end
+        end
+
+        # Fallback string conversion for unsupported or unexpected RBS type objects.
+        #
+        # Performs a few normalizations for nicer YARD output:
+        # - strips leading `::`
+        # - converts `bool` to `Boolean`
+        # - converts `untyped` to `Object`
+        #
+        # @note module_function: when included, also defines #fallback_string (instance visibility: private)
+        # @param [Object] type
+        # @return [String]
+        def fallback_string(type)
+          type.to_s
+              .gsub(/\A::/, '')
+              .gsub(/\bbool\b/, 'Boolean')
+              .gsub(/\buntyped\b/, 'Object')
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/types/signature.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+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
+    #
+    # @!attribute [rw] param_types
+    #   @return [Object]
+    #   @param [Object] value
+    #
+    # @!attribute [rw] rest_positional
+    #   @return [Object]
+    #   @param [Object] value
+    #
+    # @!attribute [rw] rest_keywords
+    #   @return [Object]
+    #   @param [Object] value
+    MethodSignature = Struct.new(:return_type, :param_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
+    #
+    # @!attribute [rw] element_type
+    #   @return [Object]
+    #   @param [Object] 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
+    #
+    # @!attribute [rw] type
+    #   @return [Object]
+    #   @param [Object] value
+    RestKeywords = Struct.new(:name, :type, keyword_init: true)
+  end
+end