docscribe 1.5.0 → 1.5.1

data/lib/docscribe/config/template.rb

@@ -98,6 +98,7 @@ module Docscribe
           enabled: false
           rbi_dirs: ["sorbet/rbi", "rbi"]
           collapse_generics: false
+          collapse_object_generics: false
 
         # Preserve existing @param/@return descriptions in aggressive mode
         keep_descriptions: false

data/lib/docscribe/config.rb

@@ -11,14 +11,20 @@ module Docscribe
     #   @return [Hash<String, Object>]
     attr_reader :raw
 
+    # @!attribute [r] config_path
+    #   @return [String?]
+    attr_reader :config_path
+
     # Create a configuration object from a raw config hash.
     #
     # Missing keys are filled from {DEFAULT} via deep merge.
     #
+    # @param [String?] config_path optional path to the config file
     # @param [Hash<String, Object>] raw user-provided config hash
     # @return [void]
-    def initialize(raw = {})
-      @raw = deep_merge(DEFAULT, raw || {})
+    def initialize(config_path: nil, **raw)
+      @raw = deep_merge(DEFAULT, raw)
+      @config_path = config_path
     end
   end
 end

data/lib/docscribe/infer/params.rb

@@ -90,7 +90,7 @@ module Docscribe
       # @note module_function: defines #parse_expr (visibility: private)
       # @param [String?] src expression source
       # @raise [Parser::SyntaxError]
-      # @return [Parser::AST::Node, nil] if Parser::SyntaxError
+      # @return [Parser::AST::Node, nil]
       # @return [nil] if Parser::SyntaxError
       def parse_expr(src)
         return nil if src.nil? || src.strip.empty?

data/lib/docscribe/infer/returns.rb

@@ -14,7 +14,7 @@ module Docscribe
       # @note module_function: defines #infer_return_type (visibility: private)
       # @param [String?] method_source full method definition source
       # @raise [Parser::SyntaxError]
-      # @return [String] if Parser::SyntaxError
+      # @return [String]
       # @return [FALLBACK_TYPE] if Parser::SyntaxError
       def infer_return_type(method_source)
         return FALLBACK_TYPE if method_source.nil? || method_source.strip.empty?
@@ -67,16 +67,19 @@ module Docscribe
       # @param [Boolean] nil_as_optional whether `nil` unions should be rendered as optional types
       # @param [Object?] core_rbs_provider core RBS type lookup provider
       # @param [Hash<String, String>?] param_types parameter name -> type map
+      # @param [String?] container
+      # @param [Docscribe::Types::ProviderChain?] signature_provider
       # @return [Object]
-      def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true, core_rbs_provider: nil,
-                                 param_types: nil)
+      def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true, core_rbs_provider: nil, # rubocop:disable Metrics/ParameterLists
+                                 param_types: nil, container: nil, signature_provider: nil)
         body = extract_def_body(node)
         spec = { normal: FALLBACK_TYPE, rescues: [] } #: Hash[Symbol, untyped]
         return spec unless body
 
         types = build_local_variable_types(body, core_rbs_provider: core_rbs_provider, param_types: param_types)
         populate_returns_spec(spec, body, types, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
-                                                 core_rbs_provider: core_rbs_provider, param_types: param_types)
+                                                 core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                                 container: container, signature_provider: signature_provider)
         spec
       end
 
@@ -235,7 +238,7 @@ module Docscribe
       # @return [String, nil]
       def handle_lvar_node(node, **opts)
         name = node.children[0].to_s
-        opts[:local_var_types]&.fetch(name, nil) || opts[:fallback_type]
+        lookup_lvar_type(name, opts[:local_var_types], opts[:param_types]) || opts[:fallback_type]
       end
 
       # Handle `:ivar` node for last_expr_type — look up instance variable in local_var_types.
@@ -608,11 +611,8 @@ module Docscribe
       def handle_block_node(node, **opts)
         send_node = node.children[0]
         if send_node&.type == :send
-          recv = send_node.children[0]
-          meth = send_node.children[1]
-          rbs_type = resolve_rbs_for_send(recv, meth, opts[:core_rbs_provider], opts[:local_var_types],
-                                          opts[:param_types])
-          return rbs_type if rbs_type
+          type = send_rbs_type(send_node.children[0], send_node.children[1], **opts)
+          return type if type
         end
 
         run_last_expr_type(node.children[2], **opts)
@@ -628,11 +628,8 @@ module Docscribe
         recv = node.children[0]
         meth = node.children[1]
 
-        if opts[:core_rbs_provider]
-          rbs_type = resolve_rbs_for_send(recv, meth, opts[:core_rbs_provider], opts[:local_var_types],
-                                          opts[:param_types])
-          return rbs_type if rbs_type
-        end
+        rbs_type = send_rbs_type(recv, meth, **opts) if opts[:core_rbs_provider]
+        return rbs_type if rbs_type
 
         compound_type = infer_from_compound_assign(node, **opts)
         return compound_type if compound_type
@@ -640,6 +637,25 @@ module Docscribe
         Literals.type_from_literal(node, fallback_type: opts[:fallback_type])
       end
 
+      # Resolve RBS return type for a send node, trying explicit receiver first,
+      # then falling back to the method's container for implicit self calls.
+      #
+      # @note module_function: defines #send_rbs_type (visibility: private)
+      # @param [Parser::AST::Node, nil] recv the receiver node
+      # @param [Symbol] meth the method name
+      # @param [Object] opts additional keyword options
+      # @return [String, nil]
+      def send_rbs_type(recv, meth, **opts)
+        rbs_type = resolve_rbs_for_send(recv, meth, opts[:core_rbs_provider], opts[:local_var_types],
+                                        opts[:param_types])
+        return rbs_type if rbs_type
+
+        rbs_type = resolve_rbs_for_send_with_signature_provider(recv, meth, **opts)
+        return rbs_type if rbs_type
+
+        container_rbs_return_type(meth, **opts) if recv.nil?
+      end
+
       # Resolve RBS return type for a send node's receiver, if possible.
       #
       # Handles `:lvar`, chained `:send`, literal (`:int`, `:str`, etc.),
@@ -653,13 +669,59 @@ module Docscribe
       # @param [Hash<String, String>, nil] param_types parameter name to type map
       # @return [String, nil] resolved type or nil if unresolvable
       def resolve_rbs_for_send(recv, meth, core_rbs_provider, local_var_types, param_types)
-        return nil unless core_rbs_provider
-
         recv_type = receiver_rbs_type_name(recv, core_rbs_provider, local_var_types, param_types)
         return nil unless recv_type
 
-        rbs = resolve_rbs_return_type(recv_type, meth, core_rbs_provider)
-        rbs unless rbs == FALLBACK_TYPE
+        if core_rbs_provider
+          rbs = resolve_rbs_return_type(recv_type, meth, core_rbs_provider)
+          return rbs unless rbs == FALLBACK_TYPE
+        end
+
+        nil
+      end
+
+      # Resolve RBS return type via signature_provider fallback.
+      #
+      # Tries project-level RBS when core_rbs_provider fails.
+      #
+      # @note module_function: defines #resolve_rbs_for_send_with_signature_provider (visibility: private)
+      # @param [Parser::AST::Node, nil] recv the receiver node
+      # @param [Symbol] meth the method name
+      # @param [Object] opts additional keyword options
+      # @return [String, nil]
+      def resolve_rbs_for_send_with_signature_provider(recv, meth, **opts)
+        return nil unless opts[:signature_provider]
+
+        recv_type = receiver_rbs_type_name(recv, opts[:core_rbs_provider], opts[:local_var_types],
+                                           opts[:param_types])
+        return nil unless recv_type
+
+        opts[:signature_provider].signature_for(container: recv_type, scope: :instance, name: meth)&.return_type
+      end
+
+      # Resolve return type from the current method's container via RBS.
+      #
+      # Handles implicit self calls (recv is nil) by looking up the method
+      # on the container class.
+      #
+      # @note module_function: defines #container_rbs_return_type (visibility: private)
+      # @param [Symbol] meth the method name being called
+      # @param [Object] opts additional keyword options (must include :container and :core_rbs_provider)
+      # @return [String, nil] resolved type or nil if unresolvable
+      def container_rbs_return_type(meth, **opts)
+        return unless opts[:container]
+
+        if opts[:core_rbs_provider]
+          rbs = resolve_rbs_return_type(opts[:container], meth, opts[:core_rbs_provider])
+          return rbs unless rbs == FALLBACK_TYPE
+        end
+
+        if opts[:signature_provider]
+          sig = opts[:signature_provider].signature_for(container: opts[:container], scope: :instance, name: meth)
+          return sig.return_type if sig
+        end
+
+        nil
       end
 
       # Map a receiver AST node to its RBS type name string.

data/lib/docscribe/infer.rb

@@ -95,15 +95,19 @@ module Docscribe
       # @param [Boolean] nil_as_optional render nil as optional
       # @param [Docscribe::Types::RBS::Provider?] core_rbs_provider core RBS type lookup provider
       # @param [Hash<String, String>?] param_types parameter name -> type map
+      # @param [String?] container
+      # @param [Docscribe::Types::ProviderChain?] signature_provider
       # @return [Hash<Symbol, String, Array<(Array<String>, String)>>]
-      def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true, core_rbs_provider: nil,
-                                 param_types: nil)
+      def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true, core_rbs_provider: nil, # rubocop:disable Metrics/ParameterLists
+                                 param_types: nil, container: nil, signature_provider: nil)
         Returns.returns_spec_from_node(
           node,
           fallback_type: fallback_type,
           nil_as_optional: nil_as_optional,
           core_rbs_provider: core_rbs_provider,
-          param_types: param_types
+          param_types: param_types,
+          container: container,
+          signature_provider: signature_provider
         )
       end
 

data/lib/docscribe/inline_rewriter/doc_builder.rb

@@ -67,7 +67,7 @@ module Docscribe
       # @param [Docscribe::Config] config Docscribe configuration object
       # @param [Object] opts additional keyword options forwarded to doc_setup
       # @raise [StandardError]
-      # @return [String, nil] if StandardError
+      # @return [String, nil]
       # @return [nil] if StandardError
       def build(insertion, config:, **opts)
         setup = doc_setup(insertion, config: config, **opts)
@@ -87,7 +87,7 @@ module Docscribe
       # @param [Docscribe::Config] config Docscribe configuration object
       # @param [Object] options additional keyword options forwarded to downstream methods
       # @raise [StandardError]
-      # @return [String, nil] if StandardError
+      # @return [String, nil]
       # @return [nil] if StandardError
       def build_merge_additions(insertion, existing_lines:, config:, **options)
         setup = doc_setup(insertion, config: config, **options)
@@ -110,7 +110,7 @@ module Docscribe
       # @param [Docscribe::Config] config Docscribe configuration object
       # @param [Object] options additional keyword options forwarded to downstream methods
       # @raise [StandardError]
-      # @return [Hash<Symbol, Object>] if StandardError
+      # @return [Hash<Symbol, Object>]
       # @return [Hash] if StandardError
       def build_missing_merge_result(insertion, existing_lines:, config:, **options)
         setup = doc_setup(insertion, config: config, **options)
@@ -187,7 +187,9 @@ module Docscribe
       # @return [Hash<Symbol, Object>]
       def resolve_doc_setup!(setup, node, name, config, opts)
         external_sig = resolve_external_sig(setup[:container], setup[:scope], name, opts[:signature_provider])
-        returns_spec = compute_returns_spec(node, config, opts[:param_types], opts[:core_rbs_provider])
+        returns_spec = compute_returns_spec(node, config, opts[:param_types], opts[:core_rbs_provider],
+                                            signature_provider: opts[:signature_provider],
+                                            container: setup[:container])
         normal_type = opts[:return_type_override] || external_sig&.return_type || returns_spec[:normal]
 
         setup.merge(
@@ -229,11 +231,15 @@ module Docscribe
       # @param [Docscribe::Config] config Docscribe configuration object
       # @param [Hash<String, String>, nil] param_types hash accumulating parameter name-to-type mappings
       # @param [Object] core_rbs_provider RBS type provider
+      # @param [Docscribe::Types::ProviderChain?] signature_provider
+      # @param [String?] container
       # @return [Hash<Symbol, Object>]
-      def compute_returns_spec(node, config, param_types, core_rbs_provider)
+      def compute_returns_spec(node, config, param_types, core_rbs_provider, # rubocop:disable Metrics/ParameterLists
+                               signature_provider: nil, container: nil)
         Docscribe::Infer.returns_spec_from_node(
           node, fallback_type: config.fallback_type, nil_as_optional: config.nil_as_optional?,
-                param_types: param_types, core_rbs_provider: core_rbs_provider
+                param_types: param_types, core_rbs_provider: core_rbs_provider,
+                signature_provider: signature_provider, container: container
         )
       end
 
@@ -690,7 +696,7 @@ module Docscribe
       # @note module_function: defines #extract_raise_types_from_line (visibility: private)
       # @param [String] line a `@raise` doc line
       # @raise [StandardError]
-      # @return [Array<String, nil>] if StandardError
+      # @return [Array<String, nil>]
       # @return [Array] if StandardError
       def extract_raise_types_from_line(line)
         return [] unless line.match?(/^\s*#\s*@raise\b/)
@@ -1998,7 +2004,7 @@ module Docscribe
       # @note module_function: defines #safe_node_source (visibility: private)
       # @param [Parser::AST::Node] node AST node whose source text to extract
       # @raise [StandardError]
-      # @return [String] if StandardError
+      # @return [String]
       # @return [String] if StandardError
       def safe_node_source(node)
         node.loc.expression.source

data/lib/docscribe/inline_rewriter/source_helpers.rb

@@ -260,7 +260,7 @@ module Docscribe
       # @note module_function: defines #line_indent (visibility: private)
       # @param [Parser::AST::Node] node target AST node
       # @raise [StandardError]
-      # @return [String] if StandardError
+      # @return [String]
       # @return [String] if StandardError
       def line_indent(node)
         line = node.loc.expression.source_line

data/lib/docscribe/inline_rewriter.rb

@@ -178,7 +178,7 @@ module Docscribe
       # @param [Docscribe::Config] config the active Docscribe::Config
       # @param [Object, nil] core_rbs_provider optional externally-provided core RBS provider
       # @raise [StandardError]
-      # @return [Object, nil] if StandardError
+      # @return [Object, nil]
       # @return [nil] if StandardError
       def load_core_rbs_provider(config, core_rbs_provider)
         core_rbs_provider || (config.respond_to?(:core_rbs_provider) ? config.core_rbs_provider : nil)
@@ -456,7 +456,7 @@ module Docscribe
       # @private
       # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
       # @raise [StandardError]
-      # @return [Integer] if StandardError
+      # @return [Integer]
       # @return [Integer] if StandardError
       def plugin_insertion_priority(insertion)
         return 0 unless insertion.is_a?(Hash)
@@ -471,7 +471,7 @@ module Docscribe
       # @private
       # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
       # @raise [StandardError]
-      # @return [String] if StandardError
+      # @return [String]
       # @return [String] if StandardError
       def plugin_insertion_label(insertion)
         return 'unknown' unless insertion.is_a?(Hash)
@@ -487,7 +487,7 @@ module Docscribe
       # @private
       # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
       # @raise [StandardError]
-      # @return [Integer, nil] if StandardError
+      # @return [Integer, nil]
       # @return [nil] if StandardError
       def plugin_insertion_line(insertion)
         return nil unless insertion.is_a?(Hash)
@@ -794,7 +794,9 @@ module Docscribe
       # @return [void]
       def merge_existing_descriptions!(params, parsed)
         params[:param_descriptions] = parsed[:param_descriptions] if parsed[:param_descriptions].any?
-        params[:return_description] = parsed[:return_description] if parsed[:return_description]
+        if parsed[:return_description] && !parsed[:return_description].start_with?('if ')
+          params[:return_description] = parsed[:return_description]
+        end
         params[:description] = parsed[:description] if parsed[:description].any?
       end
 
@@ -854,15 +856,7 @@ module Docscribe
       # @param [Docscribe::Config] config the active Docscribe::Config
       # @return [Hash<String, String>, nil]
       def resolve_param_types(insertion, external_sig, config)
-        if external_sig
-          DocBuilder.build_param_types_from_node(
-            insertion.node, external_sig: external_sig, config: config
-          )
-        else
-          DocBuilder.build_param_types_from_node(
-            insertion.node, external_sig: nil, config: config
-          )
-        end
+        DocBuilder.build_param_types_from_node(insertion.node, external_sig: external_sig, config: config)
       end
 
       # Apply method insertion aggressive
@@ -1240,7 +1234,7 @@ module Docscribe
       # @param [Docscribe::Config] config the active Docscribe::Config
       # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
       # @raise [StandardError]
-      # @return [String, nil] if StandardError
+      # @return [String, nil]
       # @return [nil] if StandardError
       def build_attr_merge_additions(ins:, existing_lines:, config:, signature_provider:)
         missing = missing_attr_names(ins, existing_lines)
@@ -1326,7 +1320,7 @@ module Docscribe
       # @param [Docscribe::Config] config the active Docscribe::Config
       # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
       # @raise [StandardError]
-      # @return [String, nil] if StandardError
+      # @return [String, nil]
       # @return [nil] if StandardError
       def build_attr_doc_for_node(ins, config:, signature_provider:)
         indent = SourceHelpers.line_indent(ins.node)
@@ -1447,8 +1441,8 @@ module Docscribe
       # @param [Docscribe::Config] config the active configuration
       # @param [Docscribe::Types::ProviderChain, nil] signature_provider RBS signature provider
       # @raise [StandardError]
+      # @return [String]
       # @return [String] if StandardError
-      # @return [Object] if StandardError
       def attribute_type(ins, name_sym, config, signature_provider:)
         ty = config.fallback_type
         return ty unless signature_provider
@@ -1466,8 +1460,8 @@ module Docscribe
       # @param [String] code the source code being processed
       # @param [String] file the file name
       # @raise [StandardError]
-      # @return [Object, nil] if StandardError
-      # @return [Object?] if StandardError
+      # @return [Object, nil]
+      # @return [Docscribe::Types::RBS::Provider, nil?] if StandardError
       def build_signature_provider(config, code, file)
         if config.respond_to?(:signature_provider_for)
           config.signature_provider_for(source: code, file: file)
@@ -1525,7 +1519,7 @@ module Docscribe
       # @private
       # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
       # @raise [StandardError]
-      # @return [Integer] if StandardError
+      # @return [Integer]
       # @return [Object] if StandardError
       def method_line_for(insertion)
         anchor_node_for(insertion).loc.expression.line

data/lib/docscribe/lru_cache.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Docscribe
+  # Bounded LRU cache with O(1) access and eviction.
+  # Used by Server::Daemon for file rewrite caching.
+  class LRUCache
+    # @param [Integer] max_size
+    # @return [void]
+    def initialize(max_size = 1000)
+      @max_size = max_size
+      @data = {}
+    end
+
+    # @param [Object] key
+    # @return [Object]
+    def [](key)
+      val = @data[key]
+      return nil unless val
+
+      @data.delete(key)
+      @data[key] = val
+      val
+    end
+
+    # @param [Object] key
+    # @param [Object] val
+    # @return [Object]
+    def []=(key, val)
+      @data.delete(key) if @data.key?(key)
+      @data[key] = val
+      @data.shift if @data.size > @max_size
+    end
+
+    # @return [void]
+    def clear
+      @data.clear
+    end
+
+    # @return [Boolean]
+    def empty?
+      @data.empty?
+    end
+
+    # @return [Integer]
+    def size
+      @data.size
+    end
+  end
+end

data/lib/docscribe/parsing.rb

@@ -42,7 +42,7 @@ module Docscribe
       # @param [Parser::Source::Buffer] buffer prepared source buffer
       # @param [Symbol] backend :auto, :parser, or :prism
       # @raise [NoMethodError]
-      # @return [Parser::AST::Node, nil] if NoMethodError
+      # @return [Parser::AST::Node, nil]
       # @return [nil] if NoMethodError
       def parse_buffer(buffer, backend: :auto)
         parser = parser_for(backend: backend)
@@ -73,7 +73,7 @@ module Docscribe
       # @param [Parser::Source::Buffer] buffer prepared source buffer
       # @param [Symbol] backend :auto, :parser, or :prism
       # @raise [NoMethodError]
-      # @return [(Parser::AST::Node?, Array<Parser::Source::Comment>), nil] if NoMethodError
+      # @return [(Parser::AST::Node?, Array<Parser::Source::Comment>), nil]
       # @return [nil] if NoMethodError
       def parse_with_comments_buffer(buffer, backend: :auto)
         parser = parser_for(backend: backend)

data/lib/docscribe/plugin/registry.rb

@@ -54,7 +54,7 @@ module Docscribe
       # @param [String, Integer] priority plugin priority (higher wins for conflicts)
       # @raise [StandardError]
       # @raise [ArgumentError]
-      # @return [Integer] if StandardError
+      # @return [Integer]
       # @return [Object] if StandardError
       def parse_priority(priority)
         Integer(priority)

data/lib/docscribe/plugin.rb

@@ -58,7 +58,7 @@ module Docscribe
     # @param [Parser::AST::Node] ast parsed AST root node
     # @param [Parser::Source::Buffer] buffer source buffer for AST
     # @raise [StandardError]
-    # @return [Array<Hash<Symbol, Object>>] if StandardError
+    # @return [Array<Hash<Symbol, Object>>]
     # @return [Array] if StandardError
     def self.process_single_plugin_result(entry, ast, buffer)
       plugin = entry.plugin