solargraph 0.47.2 → 0.54.0

data/lib/solargraph/pin/method.rb

@@ -7,7 +7,7 @@ module Solargraph
     class Method < Closure
       include Solargraph::Parser::NodeMethods
 
-      # @return [Array<Pin::Parameter>]
+      # @return [::Array<Pin::Parameter>]
       attr_reader :parameters
 
       # @return [::Symbol] :public, :private, or :protected
@@ -18,16 +18,66 @@ module Solargraph
 
       # @param visibility [::Symbol] :public, :protected, or :private
       # @param explicit [Boolean]
-      def initialize visibility: :public, explicit: true, parameters: [], node: nil, attribute: false, **splat
+      # @param parameters [::Array<Pin::Parameter>]
+      # @param block [Pin::Signature, nil, ::Symbol]
+      # @param node [Parser::AST::Node, RubyVM::AbstractSyntaxTree::Node, nil]
+      # @param attribute [Boolean]
+      # @param signatures [::Array<Signature>, nil]
+      # @param anon_splat [Boolean]
+      # @param return_type [ComplexType, nil]
+      def initialize visibility: :public, explicit: true, parameters: [], block: :undefined, node: nil, attribute: false, signatures: nil, anon_splat: false, return_type: nil, **splat
         super(**splat)
         @visibility = visibility
         @explicit = explicit
         @parameters = parameters
+        @block = block
         @node = node
         @attribute = attribute
+        @signatures = signatures
+        @anon_splat = anon_splat
+        @return_type = return_type
       end
 
-      # @return [Array<String>]
+      def transform_types(&transform)
+        # @todo 'super' alone should work here I think, but doesn't typecheck at level typed
+        m = super(&transform)
+        m.signatures = m.signatures.map do |sig|
+          sig.transform_types(&transform)
+        end
+        m.parameters = m.parameters.map do |param|
+          param.transform_types(&transform)
+        end
+        m.block = block&.transform_types(&transform)
+        m.signature_help = nil
+        m.documentation = nil
+        m
+      end
+
+      # @param signature [Pin::Signature]
+      # @return [Pin::Method]
+      def with_single_signature(signature)
+        m = proxy signature.return_type
+        m.signature_help = nil
+        m.documentation = nil
+        # @todo populating the single parameters/return_type/block
+        #   arguments here seems to be needed for some specs to pass,
+        #   even though we have a signature with the same information.
+        #   Is this a problem for RBS-populated methods, which don't
+        #   populate these three?
+        m.parameters = signature.parameters
+        m.return_type = signature.return_type
+        m.block = signature.block
+        m.signatures = [signature]
+        m
+      end
+
+      # @return [Pin::Signature, nil]
+      def block
+        return @block unless @block == :undefined
+        @block = signatures.first.block
+      end
+
+      # @return [::Array<String>]
       def parameter_names
         @parameter_names ||= parameters.map(&:name)
       end
@@ -41,7 +91,100 @@ module Solargraph
       end
 
       def return_type
-        @return_type ||= generate_complex_type
+        @return_type ||= ComplexType.new(signatures.map(&:return_type).flat_map(&:items))
+      end
+
+      # @param parameters [::Array<Parameter>]
+      # @param return_type [ComplexType]
+      # @return [Signature]
+      def generate_signature(parameters, return_type)
+        block = nil
+        yieldparam_tags = docstring.tags(:yieldparam)
+        yieldreturn_tags = docstring.tags(:yieldreturn)
+        generics = docstring.tags(:generic).map(&:name)
+        needs_block_param_signature =
+          parameters.last&.block? || !yieldreturn_tags.empty? || !yieldparam_tags.empty?
+        if needs_block_param_signature
+          yield_parameters = yieldparam_tags.map do |p|
+            name = p.name
+            decl = :arg
+            if name
+              decl = select_decl(name, false)
+              name = clean_param(name)
+            end
+            Pin::Parameter.new(
+              location: location,
+              closure: self,
+              comments: p.text,
+              name: name,
+              decl: decl,
+              presence: location ? location.range : nil,
+              return_type: ComplexType.try_parse(*p.types)
+            )
+          end
+          yield_return_type = ComplexType.try_parse(*yieldreturn_tags.flat_map(&:types))
+          block = Signature.new(generics, yield_parameters, yield_return_type)
+        end
+        Signature.new(generics, parameters, return_type, block)
+      end
+
+      # @return [::Array<Signature>]
+      def signatures
+        @signatures ||= begin
+          top_type = generate_complex_type
+          result = []
+          result.push generate_signature(parameters, top_type) if top_type.defined?
+          result.concat(overloads.map { |meth| generate_signature(meth.parameters, meth.return_type) }) unless overloads.empty?
+          result.push generate_signature(parameters, @return_type || ComplexType::UNDEFINED) if result.empty?
+          result
+        end
+      end
+
+      # @return [String, nil]
+      def detail
+        # This property is not cached in an instance variable because it can
+        # change when pins get proxied.
+        detail = String.new
+        detail += if signatures.length > 1
+          "(*) "
+        else
+          "(#{signatures.first.parameters.map(&:full).join(', ')}) " unless signatures.first.parameters.empty?
+        end.to_s
+        detail += "=#{probed? ? '~' : (proxied? ? '^' : '>')} #{return_type.to_s}" unless return_type.undefined?
+        detail.strip!
+        return nil if detail.empty?
+        detail
+      end
+
+      # @return [::Array<Hash>]
+      def signature_help
+        @signature_help ||= signatures.map do |sig|
+          {
+            label: name + '(' + sig.parameters.map(&:full).join(', ') + ')',
+            documentation: documentation
+          }
+        end
+      end
+
+      def desc
+        # ensure the signatures line up when logged
+        if signatures.length > 1
+          "\n#{to_rbs}\n"
+        else
+          to_rbs
+        end
+      end
+
+      def to_rbs
+        return nil if signatures.empty?
+
+        rbs = "def #{name}: #{signatures.first.to_rbs}"
+        signatures[1..].each do |sig|
+          rbs += "\n"
+          rbs += (' ' * (4 + name.length))
+          rbs += "| #{name}: #{sig.to_rbs}"
+        end
+        rbs
       end
 
       def path
@@ -72,6 +215,32 @@ module Solargraph
             end
             @documentation += lines.join("\n")
           end
+          yieldparam_tags = docstring.tags(:yieldparam)
+          unless yieldparam_tags.nil? or yieldparam_tags.empty?
+            @documentation += "\n\n" unless @documentation.empty?
+            @documentation += "Block Params:\n"
+            lines = []
+            yieldparam_tags.each do |p|
+              l = "* #{p.name}"
+              l += " [#{escape_brackets(p.types.join(', '))}]" unless p.types.nil? or p.types.empty?
+              l += " #{p.text}"
+              lines.push l
+            end
+            @documentation += lines.join("\n")
+          end
+          yieldreturn_tags = docstring.tags(:yieldreturn)
+          unless yieldreturn_tags.empty?
+            @documentation += "\n\n" unless @documentation.empty?
+            @documentation += "Block Returns:\n"
+            lines = []
+            yieldreturn_tags.each do |r|
+              l = "*"
+              l += " [#{escape_brackets(r.types.join(', '))}]" unless r.types.nil? or r.types.empty?
+              l += " #{r.text}"
+              lines.push l
+            end
+            @documentation += lines.join("\n")
+          end
           return_tags = docstring.tags(:return)
           unless return_tags.empty?
             @documentation += "\n\n" unless @documentation.empty?
@@ -87,6 +256,7 @@ module Solargraph
           end
           @documentation += "\n\n" unless @documentation.empty?
           @documentation += "Visibility: #{visibility}"
+          concat_example_tags
         end
         @documentation.to_s
       end
@@ -116,33 +286,90 @@ module Solargraph
         true
       end
 
-      # @return [Array<Pin::Method>]
+      # @return [::Array<Pin::Method>]
       def overloads
-        @overloads ||= docstring.tags(:overload).map do |tag|
-          Solargraph::Pin::Method.new(
-            name: name,
-            closure: self,
-            # args: tag.parameters.map(&:first),
-            parameters: tag.parameters.map do |src|
+        # Ignore overload tags with nil parameters. If it's not an array, the
+        # tag's source is likely malformed.
+        @overloads ||= docstring.tags(:overload).select(&:parameters).map do |tag|
+          Pin::Signature.new(
+            generics,
+            tag.parameters.map do |src|
+              name, decl = parse_overload_param(src.first)
               Pin::Parameter.new(
                 location: location,
                 closure: self,
                 comments: tag.docstring.all.to_s,
-                name: src.first,
+                name: name,
+                decl: decl,
                 presence: location ? location.range : nil,
-                decl: :arg
+                return_type: param_type_from_name(tag, src.first)
               )
             end,
-            comments: tag.docstring.all.to_s
+            ComplexType.try_parse(*tag.docstring.tags(:return).flat_map(&:types))
           )
         end
+        @overloads
       end
 
+      def anon_splat?
+        @anon_splat
+      end
+
+      protected
+
+      attr_writer :block
+
+      attr_writer :parameters
+
+      attr_writer :signatures
+
+      attr_writer :signature_help
+
+      attr_writer :documentation
+
       private
 
+      # @param name [String]
+      # @param asgn [Boolean]
+      #
+      # @return [::Symbol]
+      def select_decl name, asgn
+        if name.start_with?('**')
+          :kwrestarg
+        elsif name.start_with?('*')
+          :restarg
+        elsif name.start_with?('&')
+          :blockarg
+        elsif name.end_with?(':') && asgn
+          :kwoptarg
+        elsif name.end_with?(':')
+          :kwarg
+        elsif asgn
+          :optarg
+        else
+          :arg
+        end
+      end
+
+      # @param name [String]
+      # @return [String]
+      def clean_param name
+        name.gsub(/[*&:]/, '')
+      end
+
+      # @param tag [YARD::Tags::OverloadTag]
+      # @param name [String]
+      #
+      # @return [ComplexType]
+      def param_type_from_name(tag, name)
+        param = tag.tags(:param).select { |t| t.name == name }.first
+        return ComplexType::UNDEFINED unless param
+        ComplexType.try_parse(*param.types)
+      end
+
       # @return [ComplexType]
       def generate_complex_type
-        tags = docstring.tags(:return).map(&:types).flatten.reject(&:nil?)
+        tags = docstring.tags(:return).map(&:types).flatten.compact
         return ComplexType::UNDEFINED if tags.empty?
         ComplexType.try_parse *tags
       end
@@ -173,7 +400,7 @@ module Solargraph
 
       # @param ref [String]
       # @param api_map [ApiMap]
-      # @return [ComplexType]
+      # @return [ComplexType, nil]
       def resolve_reference ref, api_map
         parts = ref.split(/[\.#]/)
         if parts.first.empty? || parts.one?
@@ -208,7 +435,7 @@ module Solargraph
         result = []
         has_nil = false
         return ComplexType::NIL if method_body_node.nil?
-        returns_from(method_body_node).each do |n|
+        returns_from_method_body(method_body_node).each do |n|
           if n.nil? || [:NIL, :nil].include?(n.type)
             has_nil = true
             next
@@ -228,6 +455,8 @@ module Solargraph
         ComplexType.try_parse(*result.map(&:tag).uniq)
       end
 
+      # @param [ApiMap] api_map
+      # @return [ComplexType]
       def infer_from_iv api_map
         types = []
         varname = "@#{name.gsub(/=$/, '')}"
@@ -240,6 +469,33 @@ module Solargraph
         return ComplexType::UNDEFINED if types.empty?
         ComplexType.try_parse(*types.map(&:tag).uniq)
       end
+
+      # When YARD parses an overload tag, it includes rest modifiers in the parameters names.
+      #
+      # @param name [String]
+      # @return [::Array(String, ::Symbol)]
+      def parse_overload_param(name)
+        if name.start_with?('**')
+          [name[2..-1], :kwrestarg]
+        elsif name.start_with?('*')
+          [name[1..-1], :restarg]
+        else
+          [name, :arg]
+        end
+      end
+
+      # @return [void]
+      def concat_example_tags
+        example_tags = docstring.tags(:example)
+        return if example_tags.empty?
+        @documentation += "\n\nExamples:\n\n```ruby\n"
+        @documentation += example_tags.map do |tag|
+          (tag.name && !tag.name.empty? ? "# #{tag.name}\n" : '') +
+            "#{tag.text}\n"
+        end
+        .join("\n")
+        .concat("```\n")
+      end
     end
   end
 end

data/lib/solargraph/pin/namespace.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'solargraph/yard_tags'
+
 module Solargraph
   module Pin
     class Namespace < Closure
@@ -11,7 +13,7 @@ module Solargraph
 
       # @param type [::Symbol] :class or :module
       # @param visibility [::Symbol] :public or :private
-      # @param gates [Array<String>]
+      # @param gates [::Array<String>]
       def initialize type: :class, visibility: :public, gates: [''], **splat
         # super(location, namespace, name, comments)
         super(**splat)
@@ -38,6 +40,18 @@ module Solargraph
         end
       end
 
+      def to_rbs
+        "#{@type.to_s} #{generics_as_rbs}#{return_type.to_rbs}"
+      end
+
+      def desc
+        if name.nil?
+          '(top-level)'
+        else
+          to_rbs
+        end
+      end
+
       def namespace
         context.namespace
       end
@@ -63,6 +77,7 @@ module Solargraph
         (type == :class ? LanguageServer::SymbolKinds::CLASS : LanguageServer::SymbolKinds::MODULE)
       end
 
+      # @return [String]
       def path
         @path ||= (namespace.empty? ? '' : "#{namespace}::") + name
       end
@@ -71,6 +86,7 @@ module Solargraph
         @return_type ||= ComplexType.try_parse( (type == :class ? 'Class' : 'Module') + "<#{path}>" )
       end
 
+      # @return [Array<String>]
       def domains
         @domains ||= []
       end

data/lib/solargraph/pin/parameter.rb

@@ -9,10 +9,14 @@ module Solargraph
       # @return [String]
       attr_reader :asgn_code
 
-      def initialize decl: :arg, asgn_code: nil, **splat
+      # @param decl [::Symbol] :arg, :optarg, :kwarg, :kwoptarg, :restarg, :kwrestarg, :block, :blockarg
+      # @param asgn_code [String, nil]
+      # @param return_type [ComplexType, nil]
+      def initialize decl: :arg, asgn_code: nil, return_type: nil, **splat
         super(**splat)
         @asgn_code = asgn_code
         @decl = decl
+        @return_type = return_type
       end
 
       def keyword?
@@ -31,14 +35,36 @@ module Solargraph
         decl == :restarg || decl == :kwrestarg
       end
 
+      def block?
+        [:block, :blockarg].include?(decl)
+      end
+
+      def to_rbs
+        case decl
+        when :optarg
+          "?#{super}"
+        when :kwarg
+          "#{name}: #{return_type.to_rbs}"
+        when :kwoptarg
+          "?#{name}: #{return_type.to_rbs}"
+        when :restarg
+          "*#{super}"
+        when :kwrestarg
+          "**#{super}"
+        else
+          super
+        end
+      end
+
+      # @return [String]
       def full
         case decl
         when :optarg
-          "#{name} = #{asgn_code}"
+          "#{name} = #{asgn_code || '?'}"
         when :kwarg
           "#{name}:"
         when :kwoptarg
-          "#{name}: #{asgn_code}"
+          "#{name}: #{asgn_code || '?'}"
         when :restarg
           "*#{name}"
         when :kwrestarg
@@ -50,6 +76,7 @@ module Solargraph
         end
       end
 
+      # @return [ComplexType]
       def return_type
         if @return_type.nil?
           @return_type = ComplexType::UNDEFINED
@@ -73,7 +100,9 @@ module Solargraph
       #
       # @return [Integer]
       def index
-        closure.parameter_names.index(name)
+        # @type [Method, Block]
+        method_pin = closure
+        method_pin.parameter_names.index(name)
       end
 
       # @param api_map [ApiMap]
@@ -95,7 +124,7 @@ module Solargraph
 
       private
 
-      # @return [YARD::Tags::Tag]
+      # @return [YARD::Tags::Tag, nil]
       def param_tag
         found = nil
         params = closure.docstring.tags(:param)
@@ -114,24 +143,7 @@ module Solargraph
       # @return [ComplexType]
       def typify_block_param api_map
         if closure.is_a?(Pin::Block) && closure.receiver
-          chain = Parser.chain(closure.receiver, filename)
-          clip = api_map.clip_at(location.filename, location.range.start)
-          locals = clip.locals - [self]
-          meths = chain.define(api_map, closure, locals)
-          meths.each do |meth|
-            if meth.docstring.has_tag?(:yieldparam_single_parameter)
-              type = chain.base.infer(api_map, closure, locals)
-              if type.defined? && !type.subtypes.empty?
-                bmeth = chain.base.define(api_map, closure, locals).first
-                return type.subtypes.first.qualify(api_map, bmeth.context.namespace)
-              end
-            else
-              yps = meth.docstring.tags(:yieldparam)
-              unless yps[index].nil? or yps[index].types.nil? or yps[index].types.empty?
-                return ComplexType.try_parse(yps[index].types.first).self_to(chain.base.infer(api_map, closure, locals).namespace).qualify(api_map, meth.context.namespace)
-              end
-            end
-          end
+          return closure.typify_parameters(api_map)[index]
         end
         ComplexType::UNDEFINED
       end
@@ -139,7 +151,7 @@ module Solargraph
       # @param api_map [ApiMap]
       # @return [ComplexType]
       def typify_method_param api_map
-        meths = api_map.get_method_stack(closure.full_context.namespace, closure.name, scope: closure.scope)
+        meths = api_map.get_method_stack(closure.full_context.tag, closure.name, scope: closure.scope)
         # meths.shift # Ignore the first one
         meths.each do |meth|
           found = nil
@@ -159,8 +171,8 @@ module Solargraph
 
       # @param heredoc [YARD::Docstring]
       # @param api_map [ApiMap]
-      # @param skip [Array]
-      # @return [Array<YARD::Tags::Tag>]
+      # @param skip [::Array]
+      # @return [::Array<YARD::Tags::Tag>]
       def see_reference heredoc, api_map, skip = []
         heredoc.ref_tags.each do |ref|
           next unless ref.tag_name == 'param' && ref.owner
@@ -172,8 +184,8 @@ module Solargraph
 
       # @param ref [String]
       # @param api_map [ApiMap]
-      # @param skip [Array]
-      # @return [Array<YARD::Tags::Tag>, nil]
+      # @param skip [::Array]
+      # @return [::Array<YARD::Tags::Tag>, nil]
       def resolve_reference ref, api_map, skip
         return nil if skip.include?(ref)
         skip.push ref

data/lib/solargraph/pin/reference/override.rb

@@ -4,10 +4,10 @@ module Solargraph
   module Pin
     class Reference
       class Override < Reference
-        # @return [Array<YARD::Tags::Tag>]
+        # @return [::Array<YARD::Tags::Tag>]
         attr_reader :tags
 
-        # @return [Array<Symbol>]
+        # @return [::Array<Symbol>]
         attr_reader :delete
 
         def initialize location, name, tags, delete = []

data/lib/solargraph/pin/reference.rb

@@ -9,6 +9,14 @@ module Solargraph
       autoload :Prepend,    'solargraph/pin/reference/prepend'
       autoload :Extend,     'solargraph/pin/reference/extend'
       autoload :Override,   'solargraph/pin/reference/override'
+
+      attr_reader :generic_values
+
+      # @param generic_values [Array<String>]
+      def initialize generic_values: [], **splat
+        super(**splat)
+        @generic_values = generic_values
+      end
     end
   end
 end

data/lib/solargraph/pin/search.rb

@@ -18,21 +18,21 @@ module Solargraph
         end
       end
 
-      # @param pins [Array<Pin::Base>]
+      # @param pins [::Array<Pin::Base>]
       # @param query [String]
       def initialize pins, query
         @pins = pins
         @query = query
       end
 
-      # @return [Array<Pin::Base>]
+      # @return [::Array<Pin::Base>]
       def results
         @results ||= do_query
       end
 
       private
 
-      # @return [Array<Pin::Base>]
+      # @return [::Array<Pin::Base>]
       def do_query
         return @pins if @query.nil? || @query.empty?
         @pins.map do |pin|
@@ -49,7 +49,7 @@ module Solargraph
       # @return [Float]
       def fuzzy_string_match str1, str2
         return (1.0 + (str2.length.to_f / str1.length.to_f)) if str1.downcase.include?(str2.downcase)
-        JaroWinkler.distance(str1, str2, ignore_case: true)
+        JaroWinkler.similarity(str1, str2, ignore_case: true)
       end
     end
   end