docscribe 1.2.1 → 1.3.1

data/lib/docscribe/config/rbs.rb

@@ -11,6 +11,7 @@ module Docscribe
     # @return [Docscribe::Types::RBS::Provider, nil]
     def rbs_provider
       return nil unless rbs_enabled?
+      return nil unless ruby_supports_rbs?
 
       @rbs_provider ||= begin
         require 'docscribe/types/rbs/provider'
@@ -30,8 +31,43 @@ module Docscribe
       fetch_bool(%w[rbs enabled], false)
     end
 
+    # Method documentation.
+    #
+    # @raise [LoadError]
+    # @return [Object]
+    def core_rbs_provider
+      return nil unless ruby_supports_rbs?
+
+      @core_rbs_provider ||= begin
+        require 'docscribe/types/rbs/provider'
+        Docscribe::Types::RBS::Provider.new(
+          sig_dirs: [],
+          collapse_generics: false
+        )
+      rescue LoadError
+        nil
+      end
+    end
+
+    private
+
+    # Method documentation.
+    #
+    # @private
+    # @return [Boolean]
+    def ruby_supports_rbs?
+      return true if RUBY_VERSION >= '3.0'
+
+      @rbs_warning_emitted ||= begin
+        warn 'Docscribe: RBS requires Ruby 3.0+. Falling back to inference.'
+        true
+      end
+      false
+    end
+
     # Signature directories used by the RBS provider.
     #
+    # @private
     # @return [Array<String>]
     def rbs_sig_dirs
       Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map(&:to_s)
@@ -43,7 +79,8 @@ module Docscribe
     # - `Hash<Symbol, String>` => `Hash`
     # - `Array<Integer>`       => `Array`
     #
-    # @return [Boolean]
+    # @private
+    # @return [Object]
     def rbs_collapse_generics?
       fetch_bool(%w[rbs collapse_generics], false)
     end

data/lib/docscribe/config/template.rb

@@ -14,170 +14,94 @@ module Docscribe
         ---
         # Docscribe configuration file
         #
-        # Inspect what safe doc updates would be applied:
-        #   bundle exec docscribe lib
-        #
-        # Apply safe doc updates:
-        #   bundle exec docscribe -a lib
-        #
-        # Apply aggressive doc updates (rebuild existing doc blocks):
-        #   bundle exec docscribe -A lib
+        # Docscribe works without this file — create it only for customization.
         #
+        # Quick start:
+        #   bundle exec docscribe lib          # check what would change
+        #   bundle exec docscribe -a lib       # apply safe updates
+        #   bundle exec docscribe -A lib       # rebuild all doc blocks
 
         emit:
-          # Emit the header line:
-          #
-          #   +MyClass#my_method+ -> ReturnType
-          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
-
-          # Emit @return tag (can be overridden per scope/visibility under methods:).
-          return_tag: true
-
-          # Emit @private / @protected tags based on Ruby visibility context.
-          visibility_tags: true
-
-          # Emit @raise tags inferred from rescue clauses / raise/fail calls.
-          raise_tags: true
-
-          # Emit conditional rescue return tags:
-          #
-          #   @return [String] if FooError, BarError
-          rescue_conditional_returns: true
-
-          # Generate @!attribute docs for attr_reader/attr_writer/attr_accessor.
-          attributes: false
+          # What to include in generated documentation
+          header: false                       # +MyClass#foo+ -> ReturnType
+          param_tags: true                    # @param tags
+          return_tag: true                    # @return tag
+          visibility_tags: true               # @private / @protected
+          raise_tags: true                    # @raise tags
+          rescue_conditional_returns: true    # @return [Type] if Error
+          attributes: false                   # @!attribute for attr_*
+
+          # Placeholder text for generated docs
+          include_default_message: true       # "Method documentation."
+          include_param_documentation: true   # "Param documentation."
 
         doc:
-          # Default text inserted into each generated doc block.
+          # Default text and formatting
           default_message: "Method documentation."
-
-          # Default text appended to generated @param tags.
           param_documentation: "Param documentation."
+          param_tag_style: "type_name"        # "type_name" or "name_type"
+          sort_tags: true
+          tag_order: ["todo", "note", "api", "private", "protected", "param", "option", "yieldparam", "raise", "return"]
 
-          # Style for generated @param tags:
-          # - type_name => @param [Type] name
-          # - name_type => @param name [Type]
-          param_tag_style: "type_name"
+        inference:
+          # Type inference behavior
+          fallback_type: "Object"             # when uncertain
+          nil_as_optional: true               # String | nil => String?
+          treat_options_keyword_as_hash: true # options: keyword => Hash
 
-          # Sort generated / merged tags in safe mode when possible.
-          sort_tags: true
+        filter:
+          # Which methods and files to process
+          # Method format: "Container#method" (instance) or "Container.method" (class)
+          # Supports globs ("*#initialize") and regex ("/^MyApp::.*$/")
+          include: []
+          exclude: []
+          visibilities: ["public", "protected", "private"]
+          scopes: ["instance", "class"]
 
-          # Tag order used when sorting contiguous tag runs.
-          tag_order: ["todo", "note", "api", "private", "protected", "param", "option", "yieldparam", "raise", "return"]
+          files:
+            # File paths relative to project root (globs or /regex/)
+            include: []
+            exclude: ["spec"]
 
         methods:
-          # Per-scope / per-visibility overrides.
+          # Override defaults per scope and visibility.
+          # Empty {} means "use values from `doc` section".
           #
           # Example:
-          # methods:
           #   instance:
           #     public:
           #       default_message: "Public API."
-          #       return_tag: true
+          #     private:
+          #       return_tag: false
           instance:
             public: {}
             protected: {}
             private: {}
-
           class:
             public: {}
             protected: {}
             private: {}
 
-        inference:
-          # Type used when inference is uncertain.
-          fallback_type: "Object"
-
-          # Whether nil unions become optional types (for example String | nil => String?).
-          nil_as_optional: true
-
-          # Special-case: treat keyword arg named options/options: as a Hash.
-          treat_options_keyword_as_hash: true
-
-        filter:
-          # Filter which methods Docscribe touches.
-          #
-          # Method id format:
-          #   instance: "MyModule::MyClass#instance_method"
-          #   class:    "MyModule::MyClass.class_method"
-          #
-          # Patterns:
-          # - glob: "*#initialize", "MyApp::*#*"
-          # - regex: "/^MyApp::.*#(foo|bar)$/"
-          #
-          # Semantics:
-          # - scopes / visibilities act as allow-lists
-          # - exclude wins
-          # - if include is empty => include everything (subject to allow-lists)
-          visibilities: ["public", "protected", "private"]
-          scopes: ["instance", "class"]
-          include: []
-          exclude: []
-
-          files:
-            # Filter which files Docscribe processes (paths are matched relative
-            # to the project root).
-            #
-            # Tips:
-            # - Use directory shorthand to exclude a whole directory:
-            #     exclude: ["spec"]
-            # - Or use globs:
-            #     exclude: ["spec/**/*.rb", "vendor/**/*.rb"]
-            include: []
-            exclude: ["spec"]
-
         rbs:
-          # Optional: use RBS signatures to improve @param / @return types.
-          #
-          # CLI equivalent:
-          # bundle exec docscribe -a --rbs --sig-dir sig lib
-          #
-          # Under Bundler, you may need `gem "rbs"` in your Gemfile (or a
-          # Gemfile that includes it), otherwise `require "rbs"` may fail and
-          # Docscribe will fall back to inference.
+          # Use RBS signatures for better types (requires `gem "rbs"`)
           enabled: false
-
-          # Signature directories (repeatable via --sig-dir).
           sig_dirs: ["sig"]
-
-          # If true, simplify generic types:
-          # - Hash<Symbol, String> => Hash
-          # - Array<Integer>       => Array
-          collapse_generics: false
+          collapse_generics: false            # Hash<Symbol, String> => Hash
+          collection: false                   # auto-discover from rbs_collection.lock.yaml
 
         sorbet:
-          # Optional: use Sorbet signatures from inline `sig` declarations and
-          # RBI files to improve @param / @return types.
-          #
-          # CLI equivalent:
-          # bundle exec docscribe -a --sorbet --rbi-dir sorbet/rbi lib
-          #
-          # Sorbet resolution order is:
-          # 1. inline `sig` in the current source file
-          # 2. RBI files
-          # 3. RBS
-          # 4. AST inference
+          # Use Sorbet inline sigs and RBI files for better types
           enabled: false
-
-          # RBI directories scanned recursively for `.rbi` files
-          # (repeatable via --rbi-dir).
           rbi_dirs: ["sorbet/rbi", "rbi"]
-
-          # If true, simplify generic types:
-          # - Hash<Symbol, String> => Hash
-          # - Array<Integer>       => Array
           collapse_generics: false
+
+        plugins:
+          # Load custom plugins
+          # Example:
+          #   require:
+          #     - ./docscribe_plugins
+          #     - docscribe-rails-associations
+          require: []
       YAML
     end
   end

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

@@ -24,7 +24,9 @@ module Docscribe
         return FALLBACK_TYPE unless root && %i[def defs].include?(root.type)
 
         body = root.children.last
-        last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true) || FALLBACK_TYPE
+        local_var_types = build_local_variable_types(body)
+        last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true,
+                             local_var_types: local_var_types) || FALLBACK_TYPE
       rescue Parser::SyntaxError
         FALLBACK_TYPE
       end
@@ -43,7 +45,9 @@ module Docscribe
 
         return FALLBACK_TYPE unless body
 
-        last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true) || FALLBACK_TYPE
+        local_var_types = build_local_variable_types(body)
+        last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true,
+                             local_var_types: local_var_types) || FALLBACK_TYPE
       end
 
       # Return a structured return-type spec for a method node.
@@ -56,8 +60,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]
@@ -67,10 +74,16 @@ module Docscribe
         spec = { normal: FALLBACK_TYPE, rescues: [] }
         return spec unless body
 
+        local_var_types = build_local_variable_types(body)
+
         if body.type == :rescue
           main_body = body.children[0]
+          rescue_local_var_types = build_local_variable_types(body)
+          all_local_var_types = rescue_local_var_types || local_var_types
           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,
+                                      local_var_types: all_local_var_types) || FALLBACK_TYPE
 
           body.children.each do |ch|
             next unless ch.is_a?(Parser::AST::Node) && ch.type == :resbody
@@ -78,18 +91,51 @@ 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,
+                                          local_var_types: all_local_var_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,
+                                 local_var_types: local_var_types) || FALLBACK_TYPE
         end
 
         spec
       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 [Object] node Param documentation.
+      # @return [String] FALLBACK_TYPE if lookup fails
+      def build_local_variable_types(node)
+        types = {}
+        ASTWalk.walk(node) do |n|
+          case n.type
+          when :lvasgn, :gvasgn, :ivasgn
+            name = n.children[0].to_s
+            value = n.children[1]
+            if value
+              inferred = Literals.type_from_literal(value, fallback_type: FALLBACK_TYPE)
+              types[name] = inferred if inferred && inferred != FALLBACK_TYPE
+            end
+          when :casgn
+            name = n.children[0].to_s
+            value = n.children[2]
+            if value
+              inferred = Literals.type_from_literal(value, fallback_type: FALLBACK_TYPE)
+              types[name] = inferred if inferred && inferred != FALLBACK_TYPE
+            end
+          end
+        end
+        types.empty? ? nil : types
+      end
+
       # Infer the type of the last expression in a node.
       #
       # Supports:
@@ -98,30 +144,45 @@ 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
+      # @param [nil] local_var_types Param documentation.
       # @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,
+                         local_var_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,
+                                             local_var_types: local_var_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,
+                                               local_var_types: local_var_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,
+                                               local_var_types: local_var_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,
+                                                  local_var_types: local_var_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,
+                                    local_var_types: local_var_types)
             end
           end.compact
 
@@ -136,11 +197,89 @@ module Docscribe
         when :return
           Literals.type_from_literal(node.children.first, fallback_type: fallback_type)
 
+        when :block
+          send_node = node.children[0]
+          if send_node&.type == :send
+            recv = send_node.children[0]
+            meth = send_node.children[1]
+
+            if core_rbs_provider && recv&.type == :lvar
+              lvar_name = recv.children.first
+              recv_type = nil
+              recv_type = local_var_types[lvar_name.to_s] if local_var_types && lvar_name
+              recv_type = param_types[lvar_name.to_s] if !recv_type && param_types && lvar_name
+              if recv_type
+                rbs_type = resolve_rbs_return_type(recv_type, meth, core_rbs_provider)
+                return rbs_type unless rbs_type == FALLBACK_TYPE
+              end
+            elsif core_rbs_provider && recv&.type == :send
+              inner_type = last_expr_type(recv, fallback_type: nil, nil_as_optional: false,
+                                                core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                                local_var_types: local_var_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
+            end
+          end
+
+          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,
+                                           local_var_types: local_var_types)
+
+        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,
+                                              local_var_types: local_var_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 on local variable: p1.positive? or admins.any?
+            lvar_name = recv.children.first
+            recv_type = nil
+            recv_type = local_var_types[lvar_name.to_s] if local_var_types && lvar_name
+            recv_type = param_types[lvar_name.to_s] if !recv_type && param_types && lvar_name
+            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
+
+          Literals.type_from_literal(node, fallback_type: fallback_type)
+
         else
           Literals.type_from_literal(node, fallback_type: fallback_type)
         end
       end
 
+      # Method documentation.
+      #
+      # @note module_function: when included, also defines #resolve_rbs_return_type (instance visibility: private)
+      # @param [Object] container_type Param documentation.
+      # @param [Object] method_name Param documentation.
+      # @param [Object] core_rbs_provider Param documentation.
+      # @return [Object]
+      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