solargraph 0.50.0 → 0.53.0

data/lib/solargraph/pin/documenting.rb

@@ -38,23 +38,20 @@ module Solargraph
         end
 
         def to_s
-          return "\n```ruby\n#{@plaintext}#{@plaintext.end_with?("\n") ? '' : "\n"}```\n\n" if code?
-          ReverseMarkdown.convert unescape_brackets(Kramdown::Document.new(escape_brackets(@plaintext), input: 'GFM').to_html)
+          return to_code if code?
+          to_markdown
         end
 
         private
 
-        # @param text [String]
         # @return [String]
-        def escape_brackets text
-          # text.gsub(/(\[[^\]]*\])([^\(]|\z)/, '!!!^\1^!!!\2')
-          text.gsub('[', '!!!!b').gsub(']', 'e!!!!')
+        def to_code
+          "\n```ruby\n#{Documenting.normalize_indentation(@plaintext)}#{@plaintext.end_with?("\n") ? '' : "\n"}```\n\n"
         end
 
-        # @param text [String]
         # @return [String]
-        def unescape_brackets text
-          text.gsub('!!!!b', '[').gsub('e!!!!', ']')
+        def to_markdown
+          ReverseMarkdown.convert Kramdown::Document.new(@plaintext, input: 'GFM').to_html
         end
       end
 
@@ -65,40 +62,34 @@ module Solargraph
           # line and at least two spaces of indentation. This is a common
           # convention in Ruby core documentation, e.g., String#split.
           sections = [DocSection.new(false)]
-          normalize_indentation(docstring.to_s).gsub(/\t/, '  ').lines.each do |l|
-            if l.strip.empty?
-              sections.last.concat l
-            else
-              if (l =~ /^  [^\s]/ && sections.last.plaintext =~ /(\r?\n[ \t]*?){2,}$/) || (l.start_with?('  ') && sections.last.code?)
-                # Code block
-                sections.push DocSection.new(true) unless sections.last.code?
-                sections.last.concat l[2..-1]
-              else
-                # Regular documentation
-                sections.push DocSection.new(false) if sections.last.code?
-                sections.last.concat l
-              end
+          Documenting.normalize_indentation(Documenting.strip_html_comments(docstring.to_s.gsub("\t", '  '))).lines.each do |l|
+            if l.start_with?('  ')
+              # Code block
+              sections.push DocSection.new(true) unless sections.last.code?
+            elsif sections.last.code?
+              # Regular documentation
+              sections.push DocSection.new(false)
             end
+            sections.last.concat l
           end
           sections.map(&:to_s).join.strip
         end
       end
 
-      private
-
-      # @param text [String]
-      # @return [String]
-      def normalize_indentation text
-        text.lines.map { |l| remove_odd_spaces(l) }.join
+      def self.strip_html_comments text
+        text.gsub(/<!--([\s\S]*?)-->/, '').strip
       end
 
-      # @param line [String]
+      # @param text [String]
       # @return [String]
-      def remove_odd_spaces line
-        return line unless line.start_with?(' ')
-        spaces = line.match(/^ +/)[0].length
-        return line unless spaces.odd?
-        line[1..-1]
+      def self.normalize_indentation text
+        left = text.lines.map do |line|
+          match = line.match(/^ +/)
+          next 0 unless match
+          match[0].length
+        end.min
+        return text if left.nil? || left.zero?
+        text.lines.map { |line| line[left..] }.join
       end
     end
   end

data/lib/solargraph/pin/instance_variable.rb

@@ -3,14 +3,17 @@
 module Solargraph
   module Pin
     class InstanceVariable < BaseVariable
+      # @return [ComplexType]
       def binder
         closure.binder
       end
 
+      # @return [::Symbol]
       def scope
         closure.binder.scope
       end
 
+      # @return [ComplexType]
       def context
         @context ||= begin
           result = super
@@ -22,6 +25,7 @@ module Solargraph
         end
       end
 
+      # @param other [InstanceVariable]
       def nearly? other
         super && binder == other.binder
       end

data/lib/solargraph/pin/local_variable.rb

@@ -6,12 +6,16 @@ module Solargraph
       # @return [Range]
       attr_reader :presence
 
+      # @param assignment [AST::Node, nil]
+      # @param presence [Range, nil]
+      # @param splat [Hash]
       def initialize assignment: nil, presence: nil, **splat
         super(**splat)
         @assignment = assignment
         @presence = presence
       end
 
+      # @param pin [self]
       def try_merge! pin
         return false unless super
         @presence = pin.presence
@@ -21,11 +25,16 @@ module Solargraph
       # @param other_closure [Pin::Closure]
       # @param other_loc [Location]
       def visible_at?(other_closure, other_loc)
-        return true if location.filename == other_loc.filename &&
+        location.filename == other_loc.filename &&
           presence.include?(other_loc.range.start) &&
           match_named_closure(other_closure, closure)
       end
 
+      # @return [String]
+      def to_rbs
+        (name || '(anon)') + ' ' + (return_type&.to_rbs || 'untyped')
+      end
+
       private
 
       # @param tag1 [String]
@@ -40,6 +49,9 @@ module Solargraph
           (['', 'Class<>'].include?(tag1) && ['', 'Class<>'].include?(tag2))
       end
 
+      # @param needle [Pin::Base]
+      # @param haystack [Pin::Base]
+      # @return [Boolean]
       def match_named_closure needle, haystack
         return true if needle == haystack || haystack.is_a?(Pin::Block)
         cursor = haystack

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,21 +18,66 @@ module Solargraph
 
       # @param visibility [::Symbol] :public, :protected, or :private
       # @param explicit [Boolean]
-      # @param parameters [Array<Pin::Parameter>]
-      # @param node [Parser::AST::Node, RubyVM::AbstractSyntaxTree::Node]
+      # @param parameters [::Array<Pin::Parameter>]
+      # @param block [Pin::Signature, nil, ::Symbol]
+      # @param node [Parser::AST::Node, RubyVM::AbstractSyntaxTree::Node, nil]
       # @param attribute [Boolean]
-      def initialize visibility: :public, explicit: true, parameters: [], node: nil, attribute: false, signatures: nil, anon_splat: false, **splat
+      # @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
@@ -46,22 +91,56 @@ module Solargraph
       end
 
       def return_type
-        @return_type ||= ComplexType.try_parse(*signatures.map(&:return_type).map(&:to_s))
+        @return_type ||= ComplexType.new(signatures.map(&:return_type).flat_map(&:items))
       end
 
-      # @return [Array<Signature>]
+      # @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 Signature.new(parameters, top_type) if top_type.defined?
-          result.concat(overloads.map { |meth| Signature.new(meth.parameters, meth.return_type) })
-          result.push Signature.new(parameters, top_type) if result.empty?
+          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, top_type) if result.empty?
           result
         end
       end
 
-      # @return [String]
+      # @return [String, nil]
       def detail
         # This property is not cached in an instance variable because it can
         # change when pins get proxied.
@@ -77,7 +156,7 @@ module Solargraph
         detail
       end
 
-      # @return [Array<Hash>]
+      # @return [::Array<Hash>]
       def signature_help
         @signature_help ||= signatures.map do |sig|
           {
@@ -87,6 +166,27 @@ module Solargraph
         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
         @path ||= "#{namespace}#{(scope == :instance ? '#' : '.')}#{name}"
       end
@@ -115,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?
@@ -130,6 +256,7 @@ module Solargraph
           end
           @documentation += "\n\n" unless @documentation.empty?
           @documentation += "Visibility: #{visibility}"
+          concat_example_tags
         end
         @documentation.to_s
       end
@@ -159,10 +286,11 @@ module Solargraph
         true
       end
 
-      # @return [Array<Pin::Method>]
+      # @return [::Array<Pin::Method>]
       def overloads
         @overloads ||= docstring.tags(:overload).map do |tag|
           Pin::Signature.new(
+            generics,
             tag.parameters.map do |src|
               name, decl = parse_overload_param(src.first)
               Pin::Parameter.new(
@@ -185,8 +313,24 @@ module Solargraph
         @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
@@ -205,11 +349,16 @@ module Solargraph
         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
@@ -218,7 +367,7 @@ module Solargraph
 
       # @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
@@ -249,7 +398,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?
@@ -284,7 +433,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
@@ -304,6 +453,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(/=$/, '')}"
@@ -319,8 +470,8 @@ module Solargraph
 
       # When YARD parses an overload tag, it includes rest modifiers in the parameters names.
       #
-      # @param arg [String]
-      # @return [Array(String, Symbol)]
+      # @param name [String]
+      # @return [::Array(String, ::Symbol)]
       def parse_overload_param(name)
         if name.start_with?('**')
           [name[2..-1], :kwrestarg]
@@ -330,6 +481,19 @@ module Solargraph
           [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
@@ -9,12 +11,10 @@ module Solargraph
       # @return [::Symbol] :class or :module
       attr_reader :type
 
-      attr_reader :parameters
-
       # @param type [::Symbol] :class or :module
       # @param visibility [::Symbol] :public or :private
-      # @param gates [Array<String>]
-      def initialize type: :class, visibility: :public, gates: [''], parameters: [], **splat
+      # @param gates [::Array<String>]
+      def initialize type: :class, visibility: :public, gates: [''], **splat
         # super(location, namespace, name, comments)
         super(**splat)
         @type = type
@@ -38,7 +38,18 @@ module Solargraph
           @closure = Pin::Namespace.new(name: closure_name, gates: [parts.join('::')])
           @context = nil
         end
-        @parameters = parameters
+      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
@@ -66,6 +77,7 @@ module Solargraph
         (type == :class ? LanguageServer::SymbolKinds::CLASS : LanguageServer::SymbolKinds::MODULE)
       end
 
+      # @return [String]
       def path
         @path ||= (namespace.empty? ? '' : "#{namespace}::") + name
       end
@@ -74,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,6 +9,9 @@ module Solargraph
       # @return [String]
       attr_reader :asgn_code
 
+      # @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
@@ -36,6 +39,24 @@ module Solargraph
         [: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
@@ -100,7 +121,7 @@ module Solargraph
 
       private
 
-      # @return [YARD::Tags::Tag]
+      # @return [YARD::Tags::Tag, nil]
       def param_tag
         found = nil
         params = closure.docstring.tags(:param)
@@ -119,21 +140,30 @@ module Solargraph
       # @return [ComplexType]
       def typify_block_param api_map
         if closure.is_a?(Pin::Block) && closure.receiver
-          chain = Parser.chain(closure.receiver, filename)
+          chain = Parser.chain(closure.receiver, filename, closure.node)
           clip = api_map.clip_at(location.filename, location.range.start)
           locals = clip.locals - [self]
           meths = chain.define(api_map, closure, locals)
+          receiver_type = chain.base.infer(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
+            block_signature = meth.block
+            if block_signature
+              yield_type = block_signature.parameters[index]&.return_type
             else
+              # @todo move the yieldparam tag parsing logic into the
+              #   creation of Method pins so we don't need this else
+              #   statement
               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)
+                yield_type = ComplexType.try_parse(yps[index].types.first)
+              end
+            end
+            unless yield_type.nil?
+              if yield_type.generic? && receiver_type.defined?
+                namespace_pin = api_map.get_namespace_pins(meth.namespace, closure.namespace).first
+                return yield_type.resolve_generics(namespace_pin, receiver_type)
+              else
+                return yield_type.self_to(chain.base.infer(api_map, closure, locals).namespace).qualify(api_map, meth.context.namespace)
               end
             end
           end
@@ -144,7 +174,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
@@ -164,8 +194,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
@@ -177,8 +207,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 = []