docscribe 1.5.2 → 1.6.1

data/lib/docscribe/types/overload_selector.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Types
+    # Selects best matching overload from RBS signatures for given arguments.
+    module OverloadSelector
+      class << self
+        # @param [Array<Object>] overloads
+        # @param [Integer] arg_count
+        # @param [Array<String>] param_names
+        # @return [Object?]
+        def select(overloads, arg_count:, param_names: [])
+          return nil if overloads.nil? || overloads.empty?
+          return overloads.first if overloads.size == 1
+
+          best = best_match(overloads, arg_count, param_names)
+          best&.first || overloads.first
+        end
+
+        # @param [Array<Object>] overloads
+        # @param [Integer] arg_count
+        # @param [Array<String>] param_names
+        # @return [(Object, Integer)?]
+        def best_match(overloads, arg_count, param_names)
+          candidates = overloads.map { |sig| score_signature(sig, arg_count: arg_count, param_names: param_names) }
+          candidates.compact.max_by { |_sig, score| score }
+        end
+
+        private
+
+        # @private
+        # @param [Object] sig
+        # @param [Integer] arg_count
+        # @param [Array<String>] param_names
+        # @return [(Object, Integer)?]
+        def score_signature(sig, arg_count:, param_names:)
+          score = 0
+
+          pos_count = sig.positional_types&.length.to_i
+          return nil if pos_count > arg_count
+
+          score += score_positional(pos_count, arg_count, sig)
+          score += score_params(sig, param_names)
+          score += 3 if sig.return_type && !sig.return_type.empty?
+          score += 1 if sig.return_type && sig.return_type != 'Object'
+
+          [sig, score]
+        end
+
+        # @private
+        # @param [Integer] pos_count
+        # @param [Integer] arg_count
+        # @param [Object] sig
+        # @return [Integer]
+        def score_positional(pos_count, arg_count, sig)
+          if pos_count == arg_count
+            10
+          elsif pos_count < arg_count && sig.rest_positional
+            5
+          else
+            0
+          end
+        end
+
+        # @private
+        # @param [Object] sig
+        # @param [Array<String>] param_names
+        # @return [Integer]
+        def score_params(sig, param_names)
+          if sig.param_types
+            (sig.param_types.keys & param_names).length * 2
+          else
+            0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/types/provider_chain.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'overload_selector'
+
 module Docscribe
   module Types
     # Resolve method signatures by querying a list of providers in order.
@@ -22,18 +24,39 @@ module Docscribe
 
       # Resolve a method signature from the first provider that can supply it.
       #
+      # When overloads are present, selects the best-matching signature.
+      #
       # @param [String] container e.g. "MyModule::MyClass"
       # @param [Symbol] scope :instance or :class
       # @param [Symbol, String] name method name
+      # @param [Integer?] param_count number of actual arguments
+      # @param [Array<String>] param_names actual parameter names
       # @return [Docscribe::Types::MethodSignature, nil]
-      def signature_for(container:, scope:, name:)
+      def signature_for(container:, scope:, name:, param_count: nil, param_names: [])
         @providers.each do |provider|
           sig = provider.signature_for(container: container, scope: scope, name: name)
-          return sig if sig
+          next unless sig
+
+          return sig unless sig.overloads&.any?
+
+          best = select_overload(sig, param_count, param_names)
+          return best if best
         end
 
         nil
       end
+
+      # @param [Docscribe::Types::MethodSignature] sig
+      # @param [Integer?] param_count
+      # @param [Array<String>] param_names
+      # @return [Docscribe::Types::MethodSignature, nil]
+      def select_overload(sig, param_count, param_names)
+        OverloadSelector.select(
+          [sig, *sig.overloads],
+          arg_count: param_count || 0,
+          param_names: param_names
+        )
+      end
     end
   end
 end

data/lib/docscribe/types/signature.rb

@@ -21,7 +21,12 @@ module Docscribe
     # @!attribute [rw] rest_keywords
     #   @return [Docscribe::Types::RestKeywords, nil]
     #   @param [Docscribe::Types::RestKeywords, nil] value
+    #
+    # @!attribute [rw] overloads
+    #   @return [Array<Docscribe::Types::MethodSignature>, nil]
+    #   @param [Array<Docscribe::Types::MethodSignature>, nil] value
     MethodSignature = Struct.new(:return_type, :param_types, :positional_types, :rest_positional, :rest_keywords,
+                                 :overloads,
                                  keyword_init: true)
 
     # @!attribute [rw] name

data/lib/docscribe/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docscribe
 version: !ruby/object:Gem::Version
-  version: 1.5.2
+  version: 1.6.1
 platform: ruby
 authors:
 - unurgunite
@@ -163,6 +163,8 @@ files:
 - lib/docscribe/cli.rb
 - lib/docscribe/cli/check_for_comments.rb
 - lib/docscribe/cli/config_builder.rb
+- lib/docscribe/cli/config_dump.rb
+- lib/docscribe/cli/coverage.rb
 - lib/docscribe/cli/formatters.rb
 - lib/docscribe/cli/formatters/json.rb
 - lib/docscribe/cli/formatters/sarif.rb
@@ -188,6 +190,7 @@ files:
 - lib/docscribe/config/utils.rb
 - lib/docscribe/infer.rb
 - lib/docscribe/infer/ast_walk.rb
+- lib/docscribe/infer/behavior.rb
 - lib/docscribe/infer/constants.rb
 - lib/docscribe/infer/literals.rb
 - lib/docscribe/infer/names.rb
@@ -209,6 +212,11 @@ files:
 - lib/docscribe/plugin/registry.rb
 - lib/docscribe/plugin/tag.rb
 - lib/docscribe/server.rb
+- lib/docscribe/server/base.rb
+- lib/docscribe/server/client.rb
+- lib/docscribe/server/daemon.rb
+- lib/docscribe/server/protocol.rb
+- lib/docscribe/types/overload_selector.rb
 - lib/docscribe/types/provider_chain.rb
 - lib/docscribe/types/rbs/collection_loader.rb
 - lib/docscribe/types/rbs/provider.rb
@@ -230,7 +238,7 @@ metadata:
   changelog_uri: https://github.com/unurgunite/docscribe/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message: |
-  You installed docscribe 1.5.2. Your future self (and your team) thank you.
+  You installed docscribe 1.6.1. Your future self (and your team) thank you.
 
     $ docscribe --help
 
@@ -250,7 +258,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Auto-generate inline YARD documentation for Ruby by analyzing code AST. Supports
   RBS and Sorbet type signatures.