docscribe 1.2.0 → 1.3.0

data/lib/docscribe/config/template.rb

@@ -28,7 +28,15 @@ module Docscribe
           # Emit the header line:
           #
           #   +MyClass#my_method+ -> ReturnType
-          header: true
+          header: false
+
+          # Whether to include the default placeholder line:
+          #   # Method documentation.
+          include_default_message: true
+
+          # Whether to append placeholder text to generated @param tags:
+          #   # @param [String] name Param documentation.
+          include_param_documentation: true
 
           # Emit @param tags.
           param_tags: true
@@ -129,6 +137,18 @@ module Docscribe
             include: []
             exclude: ["spec"]
 
+        plugins:
+          # Load custom plugins by path or gem name.
+          #
+          # Each entry is passed to `require`. Registration happens inside
+          # the required file via Docscribe::Plugin::Registry.register.
+          #
+          # Example:
+          #   require:
+          #     - ./docscribe_plugins
+          #     - docscribe-rails-associations
+          require: []
+
         rbs:
           # Optional: use RBS signatures to improve @param / @return types.
           #
@@ -147,6 +167,11 @@ module Docscribe
           # - Hash<Symbol, String> => Hash
           # - Array<Integer>       => Array
           collapse_generics: false
+          # Auto-discover RBS collection from rbs_collection.lock.yaml.
+          # Equivalent to --rbs-collection CLI flag.
+          # Requires `bundle exec rbs collection install` to have been run.
+          #
+          collection: false
 
         sorbet:
           # Optional: use Sorbet signatures from inline `sig` declarations and

data/lib/docscribe/config.rb

@@ -33,3 +33,4 @@ require_relative 'config/filtering'
 require_relative 'config/rbs'
 require_relative 'config/sorting'
 require_relative 'config/sorbet'
+require_relative 'config/plugin'

data/lib/docscribe/infer/returns.rb

@@ -56,8 +56,11 @@ module Docscribe
       # @param [Parser::AST::Node] node `:def` or `:defs` node
       # @param [String] fallback_type type used when inference is uncertain
       # @param [Boolean] nil_as_optional whether `nil` unions should be rendered as optional types
+      # @param [nil] core_rbs_provider Param documentation.
+      # @param [nil] param_types Param documentation.
       # @return [Hash]
-      def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true)
+      def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true, core_rbs_provider: nil,
+                                 param_types: nil)
         body =
           case node.type
           when :def then node.children[2]
@@ -70,7 +73,8 @@ module Docscribe
         if body.type == :rescue
           main_body = body.children[0]
           spec[:normal] =
-            last_expr_type(main_body, fallback_type: fallback_type, nil_as_optional: nil_as_optional) || FALLBACK_TYPE
+            last_expr_type(main_body, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
+                                      core_rbs_provider: core_rbs_provider, param_types: param_types) || FALLBACK_TYPE
 
           body.children.each do |ch|
             next unless ch.is_a?(Parser::AST::Node) && ch.type == :resbody
@@ -78,13 +82,15 @@ module Docscribe
             exc_list, _asgn, rescue_body = *ch
             exc_names = Raises.exception_names_from_rescue_list(exc_list)
             rtype =
-              last_expr_type(rescue_body, fallback_type: fallback_type, nil_as_optional: nil_as_optional) ||
+              last_expr_type(rescue_body, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
+                                          core_rbs_provider: core_rbs_provider, param_types: param_types) ||
               fallback_type
             spec[:rescues] << [exc_names, rtype]
           end
         else
           spec[:normal] =
-            last_expr_type(body, fallback_type: fallback_type, nil_as_optional: nil_as_optional) || FALLBACK_TYPE
+            last_expr_type(body, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
+                                 core_rbs_provider: core_rbs_provider, param_types: param_types) || FALLBACK_TYPE
         end
 
         spec
@@ -98,30 +104,38 @@ module Docscribe
       # - `case` expressions
       # - explicit `return`
       # - literal-like expressions via {Literals.type_from_literal}
+      # - method calls with RBS core type lookup
       #
       # @note module_function: when included, also defines #last_expr_type (instance visibility: private)
       # @param [Parser::AST::Node, nil] node expression node
       # @param [String] fallback_type type used when inference is uncertain
       # @param [Boolean] nil_as_optional whether `nil` unions should be rendered as optional types
+      # @param [Object, nil] core_rbs_provider optional RBS provider for core type lookup
+      # @param [Hash, nil] param_types parameter name -> type map for lvar resolution
       # @return [String, nil]
-      def last_expr_type(node, fallback_type:, nil_as_optional:)
+      def last_expr_type(node, fallback_type:, nil_as_optional:, core_rbs_provider: nil, param_types: nil)
         return nil unless node
 
         case node.type
         when :begin
-          last_expr_type(node.children.last, fallback_type: fallback_type, nil_as_optional: nil_as_optional)
+          last_expr_type(node.children.last, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
+                                             core_rbs_provider: core_rbs_provider, param_types: param_types)
 
         when :if
-          t = last_expr_type(node.children[1], fallback_type: fallback_type, nil_as_optional: nil_as_optional)
-          e = last_expr_type(node.children[2], fallback_type: fallback_type, nil_as_optional: nil_as_optional)
+          t = last_expr_type(node.children[1], fallback_type: fallback_type, nil_as_optional: nil_as_optional,
+                                               core_rbs_provider: core_rbs_provider, param_types: param_types)
+          e = last_expr_type(node.children[2], fallback_type: fallback_type, nil_as_optional: nil_as_optional,
+                                               core_rbs_provider: core_rbs_provider, param_types: param_types)
           unify_types(t, e, fallback_type: fallback_type, nil_as_optional: nil_as_optional)
 
         when :case
           branches = node.children[1..].compact.flat_map do |child|
             if child.type == :when
-              last_expr_type(child.children.last, fallback_type: fallback_type, nil_as_optional: nil_as_optional)
+              last_expr_type(child.children.last, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
+                                                  core_rbs_provider: core_rbs_provider, param_types: param_types)
             else
-              last_expr_type(child, fallback_type: fallback_type, nil_as_optional: nil_as_optional)
+              last_expr_type(child, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
+                                    core_rbs_provider: core_rbs_provider, param_types: param_types)
             end
           end.compact
 
@@ -136,11 +150,58 @@ module Docscribe
         when :return
           Literals.type_from_literal(node.children.first, fallback_type: fallback_type)
 
+        when :send
+          recv = node.children[0]
+          meth = node.children[1]
+
+          # Try to resolve return type from RBS core for method calls
+          if core_rbs_provider && recv&.type == :send
+            # Chained call: arg.to_i.positive?
+            inner_type = last_expr_type(recv, fallback_type: nil, nil_as_optional: false,
+                                              core_rbs_provider: core_rbs_provider, param_types: param_types)
+            if inner_type
+              rbs_type = resolve_rbs_return_type(inner_type, meth, core_rbs_provider)
+              return rbs_type unless rbs_type == FALLBACK_TYPE
+            end
+          elsif core_rbs_provider && recv&.type == :lvar
+            # Direct call: arg.positive?
+            lvar_name = recv.children.first
+            if lvar_name && param_types
+              recv_type = param_types[lvar_name.to_s]
+              if recv_type
+                rbs_type = resolve_rbs_return_type(recv_type, meth, core_rbs_provider)
+                return rbs_type unless rbs_type == FALLBACK_TYPE
+              end
+            end
+          end
+
+          Literals.type_from_literal(node, fallback_type: fallback_type)
+
         else
           Literals.type_from_literal(node, fallback_type: fallback_type)
         end
       end
 
+      # Resolve a return type from core RBS for a method call.
+      #
+      # @note module_function: when included, also defines #resolve_rbs_return_type (instance visibility: private)
+      # @private
+      # @param [String] container_type e.g. "Numeric", "String"
+      # @param [Symbol] method_name e.g. :positive?
+      # @param [Object, nil] core_rbs_provider RBS provider
+      # @return [String] FALLBACK_TYPE if lookup fails
+      def resolve_rbs_return_type(container_type, method_name, core_rbs_provider)
+        return FALLBACK_TYPE unless core_rbs_provider
+
+        sig = core_rbs_provider.signature_for(
+          container: container_type,
+          scope: :instance,
+          name: method_name
+        )
+
+        sig&.return_type || FALLBACK_TYPE
+      end
+
       # Unify two inferred types into a single type string.
       #
       # Rules:

data/lib/docscribe/infer.rb

@@ -93,12 +93,17 @@ module Docscribe
       # @param [Parser::AST::Node] node
       # @param [String] fallback_type
       # @param [Boolean] nil_as_optional
+      # @param [nil] core_rbs_provider Param documentation.
+      # @param [nil] param_types Param documentation.
       # @return [Hash]
-      def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true)
+      def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true, core_rbs_provider: nil,
+                                 param_types: nil)
         Returns.returns_spec_from_node(
           node,
           fallback_type: fallback_type,
-          nil_as_optional: nil_as_optional
+          nil_as_optional: nil_as_optional,
+          core_rbs_provider: core_rbs_provider,
+          param_types: param_types
         )
       end