solargraph 0.61.0 → 0.62.0

data/lib/solargraph/parser/parser_gem/node_processors/gvasgn_node.rb

@@ -12,6 +12,7 @@ module Solargraph
               closure: region.closure,
               name: node.children[0].to_s,
               comments: comments_for(node),
+              type_assertion: type_assertion_for(node),
               assignment: node.children[1],
               source: :parser
             )

data/lib/solargraph/parser/parser_gem/node_processors/ivasgn_node.rb

@@ -14,6 +14,7 @@ module Solargraph
               closure: region.closure,
               name: node.children[0].to_s,
               comments: comments_for(node),
+              type_assertion: type_assertion_for(node),
               assignment: node.children[1],
               source: :parser
             )
@@ -28,6 +29,7 @@ module Solargraph
                                               name: region.closure.name),
                   name: node.children[0].to_s,
                   comments: comments_for(node),
+                  type_assertion: type_assertion_for(node),
                   assignment: node.children[1],
                   source: :parser
                 )

data/lib/solargraph/parser/parser_gem/node_processors/lvasgn_node.rb

@@ -18,6 +18,7 @@ module Solargraph
               name: node.children[0].to_s,
               assignment: node.children[1],
               comments: comments_for(node),
+              type_assertion: type_assertion_for(node),
               presence: presence,
               source: :parser
             )

data/lib/solargraph/parser/parser_gem/node_processors/send_node.rb

@@ -40,10 +40,16 @@ module Solargraph
                 process_private_constant
               elsif method_name == :alias_method && node.children[2] && node.children[2] && node.children[2].type == :sym && node.children[3] && node.children[3].type == :sym
                 process_alias_method
+              elsif %i[def_delegator def_delegators].include?(method_name) && extends_forwardable?
+                process_def_delegators
               elsif method_name == :private_class_method && node.children[2].is_a?(AST::Node)
                 # Processing a private class can potentially handle children on its own
                 return if process_private_class_method
               end
+            elsif %i[include extend prepend].include?(method_name) && Parser.is_ast_node?(node.children[0]) && node.children[0].type == :const
+              process_qualified_mixin method_name
+            elsif included_hook_parameter?(node.children[0])
+              process_included_hook_mixin method_name
             elsif method_name == :require && node.children[0].to_s == '(const nil :Bundler)'
               pins.push Pin::Reference::Require.new(
                 Solargraph::Location.new(region.filename,
@@ -55,6 +61,91 @@ module Solargraph
 
           private
 
+          # True when the enclosing namespace extends Forwardable, which is
+          # what makes def_delegator and def_delegators available there.
+          # Matched by name only, so a same-named local module would fool this.
+          #
+          # @return [Boolean]
+          def extends_forwardable?
+            pins.any? do |pin|
+              pin.is_a?(Pin::Reference::Extend) &&
+                pin.closure == region.closure &&
+                ['Forwardable', '::Forwardable'].include?(pin.name)
+            end
+          end
+
+          # The word behind a symbol or string node, e.g. :@records or "size".
+          #
+          # @param subject [Object]
+          # @return [String, nil]
+          def symbol_word subject
+            return nil unless subject.is_a?(::Parser::AST::Node)
+
+            # @sg-ignore flow sensitive typing needs to narrow down type with an if is_a? check
+            return nil unless %i[sym str].include?(subject.type)
+
+            # @sg-ignore flow sensitive typing needs to narrow down type with an if is_a? check
+            subject.children.first.to_s
+          end
+
+          # Forwardable's def_delegator/def_delegators define real methods
+          # whose behavior - including return type - comes from the method
+          # they forward to. Map them to DelegatedMethod pins, which resolve
+          # the receiver and the forwarded method lazily.
+          #
+          # @return [void]
+          def process_def_delegators
+            receiver_word = symbol_word(node.children[2])
+            return if receiver_word.nil?
+
+            receiver_chain = delegation_receiver_chain(receiver_word)
+            if node.children[1] == :def_delegator
+              receiver_method_name = symbol_word(node.children[3])
+              return if receiver_method_name.nil?
+
+              name = symbol_word(node.children[4]) || receiver_method_name
+              push_delegated_method(name, receiver_method_name, receiver_chain)
+            else
+              (node.children[3..] || []).each do |method_node|
+                word = symbol_word(method_node)
+                next if word.nil?
+
+                push_delegated_method(word, word, receiver_chain)
+              end
+            end
+          end
+
+          # @param word [String] the delegation target, e.g. "@records" or "records"
+          # @return [Source::Chain]
+          def delegation_receiver_chain word
+            link = if word.start_with?('@@')
+                     Source::Chain::ClassVariable.new(word)
+                   elsif word.start_with?('@')
+                     Source::Chain::InstanceVariable.new(word, node, get_node_location(node))
+                   else
+                     Source::Chain::Call.new(word, get_node_location(node))
+                   end
+            Source::Chain.new([link])
+          end
+
+          # @param name [String]
+          # @param receiver_method_name [String]
+          # @param receiver_chain [Source::Chain]
+          # @return [void]
+          def push_delegated_method name, receiver_method_name, receiver_chain
+            pins.push Solargraph::Pin::DelegatedMethod.new(
+              location: get_node_location(node),
+              closure: region.closure,
+              name: name,
+              receiver: receiver_chain,
+              receiver_method_name: receiver_method_name,
+              scope: region.scope || :instance,
+              visibility: region.visibility,
+              comments: comments_for(node),
+              source: :parser
+            )
+          end
+
           # @return [void]
           def process_visibility
             if node.children.length > 2
@@ -127,6 +218,20 @@ module Solargraph
             end
           end
 
+          # @param options [Hash{String => AST::Node}]
+          # @param name [String]
+          # @param default [Boolean]
+          # @return [Boolean]
+          def boolean_option options, name, default
+            value = options[name]
+            return default unless Parser.is_ast_node?(value)
+            # rubocop:disable Lint/BooleanSymbol -- these are AST node types
+            return true if value.type == :true
+            return false if value.type == :false
+            # rubocop:enable Lint/BooleanSymbol
+            default
+          end
+
           # @return [void]
           def process_include
             return unless node.children[2].is_a?(AST::Node) && node.children[2].type == :const
@@ -158,6 +263,42 @@ module Solargraph
             end
           end
 
+          # Process mixins called on an explicit receiver, e.g.,
+          # +Object.prepend(self)+ in ActiveSupport or
+          # +Integer.prepend ActiveSupport::NumericWithFormat+. Without this,
+          # gems that extend core classes this way lose every method they
+          # share with Object, Module, Integer, etc.
+          #
+          # @param keyword [::Symbol] one of :include, :extend, :prepend
+          # @return [void]
+          def process_qualified_mixin keyword
+            reference_class = {
+              include: Pin::Reference::Include,
+              extend: Pin::Reference::Extend,
+              prepend: Pin::Reference::Prepend
+            }[keyword]
+            return if reference_class.nil?
+            receiver = node.children[0]
+            target = unpack_name(receiver)
+            return if target.nil? || target.empty?
+            closure = Pin::Namespace.new(location: get_node_location(receiver), name: target, source: :parser)
+            node.children[2..].each do |arg|
+              next unless Parser.is_ast_node?(arg)
+              name = if arg.type == :self
+                       region.closure&.full_context&.namespace
+                     elsif arg.type == :const
+                       unpack_name(arg)
+                     end
+              next if name.nil? || name.empty?
+              pins.push reference_class.new(
+                location: get_node_location(arg),
+                closure: closure,
+                name: name,
+                source: :parser
+              )
+            end
+          end
+
           # @return [void]
           def process_extend
             # @sg-ignore Need to add nil check here
@@ -181,6 +322,50 @@ module Solargraph
             end
           end
 
+          # @param receiver [::Parser::AST::Node, nil]
+          # @return [Boolean] whether receiver is the parameter of a module's
+          #   +self.included(base)+ hook
+          def included_hook_parameter? receiver
+            hook = region.closure
+            return false if receiver.nil? || receiver.type != :lvar
+            return false unless hook.is_a?(Pin::Method) && hook.scope == :class && hook.name == 'included'
+            hook.parameters.first&.name == receiver.children[0].to_s
+          end
+
+          # Map +base.extend ClassMethods+, +base.send(:include, Helpers)+
+          # and similar calls in a +self.included(base)+ hook, which apply to
+          # every class that includes the hook's module
+          #
+          # @param method_name [::Symbol]
+          # @return [void]
+          def process_included_hook_mixin method_name
+            args = node.children[2..] || []
+            if %i[send public_send].include?(method_name)
+              keyword = args.first
+              return unless Parser.is_ast_node?(keyword) && keyword.type == :sym
+              method_name = keyword.children[0]
+              args = args.drop(1)
+            end
+            return unless %i[include extend prepend].include?(method_name)
+            hook = region.closure
+            args.each do |arg|
+              next unless Parser.is_ast_node?(arg)
+              name = if arg.type == :self
+                       hook.namespace
+                     elsif arg.type == :const
+                       unpack_name(arg)
+                     end
+              next if name.nil? || name.empty?
+              pins.push Pin::Reference::IncludedMixin.new(
+                location: get_node_location(arg),
+                closure: hook.closure,
+                name: name,
+                keyword: method_name,
+                source: :parser
+              )
+            end
+          end
+
           # @return [void]
           def process_require
             return unless node.children[2].is_a?(AST::Node) && node.children[2].type == :str

data/lib/solargraph/parser/parser_gem/node_processors/struct_definition/struct_assignment_node.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Parser
+    module ParserGem
+      module NodeProcessors
+        module StructDefinition
+          # A node wrapper for a Struct definition via const assignment.
+          # @example
+          #   MyStruct = Struct.new(:bar, :baz) do
+          #     def foo
+          #     end
+          #   end
+          class StructAssignmentNode < StructDefintionNode
+            class << self
+              # @example
+              # s(:casgn, nil, :Foo,
+              #   s(:block,
+              #     s(:send,
+              #       s(:const, nil, :Struct), :new,
+              #       s(:sym, :bar),
+              #       s(:sym, :baz)),
+              #     s(:args),
+              #     s(:def, :foo,
+              #       s(:args),
+              #       s(:send, nil, :bar))))
+              #
+              # @param node [Parser::AST::Node]
+              def match? node
+                return false unless node&.type == :casgn
+                return false if node.children[2].nil?
+
+                struct_node = if node.children[2].type == :block
+                                node.children[2].children[0]
+                              else
+                                node.children[2]
+                              end
+
+                struct_definition_node?(struct_node)
+              end
+            end
+
+            def class_name
+              if node.children[0]
+                Parser::NodeMethods.unpack_name(node.children[0]) + "::#{node.children[1]}"
+              else
+                node.children[1].to_s
+              end
+            end
+
+            private
+
+            # @return [Parser::AST::Node]
+            def struct_node
+              if node.children[2].type == :block
+                node.children[2].children[0]
+              else
+                node.children[2]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solargraph/parser/parser_gem/node_processors/struct_definition/struct_definition_node.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Parser
+    module ParserGem
+      module NodeProcessors
+        module StructDefinition
+          # A node wrapper for a Struct definition via inheritance.
+          # @example
+          #   class MyStruct < Struct.new(:bar, :baz)
+          #     def foo
+          #     end
+          #   end
+          class StructDefintionNode
+            class << self
+              # @example
+              #   s(:class,
+              #     s(:const, nil, :Foo),
+              #     s(:send,
+              #       s(:const, nil, :Struct), :new,
+              #       s(:sym, :bar),
+              #       s(:sym, :baz)),
+              #       s(:hash,
+              #         s(:pair,
+              #           s(:sym, :keyword_init),
+              #           s(:true)))),
+              #     s(:def, :foo,
+              #       s(:args),
+              #       s(:send, nil, :bar)))
+              #
+              # @param node [Parser::AST::Node]
+              def match? node
+                return false unless node&.type == :class
+
+                struct_definition_node?(node.children[1])
+              end
+
+              private
+
+              # @param struct_node [Parser::AST::Node]
+              # @return [Boolean]
+              def struct_definition_node? struct_node
+                return false unless struct_node.is_a?(::Parser::AST::Node)
+                return false unless struct_node&.type == :send
+                return false unless struct_node.children[0]&.type == :const
+                return false unless struct_node.children[0].children[1] == :Struct
+                return false unless struct_node.children[1] == :new
+
+                true
+              end
+            end
+
+            # @param node [Parser::AST::Node]
+            def initialize node
+              @node = node
+            end
+
+            # @return [String]
+            def class_name
+              Parser::NodeMethods.unpack_name(node)
+            end
+
+            # @return [Array<Array(Parser::AST::Node, String)>]
+            def attributes
+              struct_attribute_nodes.map do |struct_def_param|
+                next unless struct_def_param.type == :sym
+                [struct_def_param, struct_def_param.children[0].to_s]
+              end.compact
+            end
+
+            def keyword_init?
+              keyword_init_param = struct_attribute_nodes.find do |struct_def_param|
+                struct_def_param.type == :hash && struct_def_param.children[0].type == :pair &&
+                  struct_def_param.children[0].children[0].children[0] == :keyword_init
+              end
+
+              return false if keyword_init_param.nil?
+
+              # rubocop:disable-next Lint/BooleanSymbol
+              keyword_init_param.children[0].children[1].type == :true
+            end
+
+            # @return [Parser::AST::Node]
+            def body_node
+              node.children[2]
+            end
+
+            private
+
+            # @return [Parser::AST::Node]
+            attr_reader :node
+
+            # @return [Parser::AST::Node]
+            def struct_node
+              node.children[1]
+            end
+
+            # @sg-ignore Need to add nil check here
+            # @return [Array<Parser::AST::Node>]
+            def struct_attribute_nodes
+              struct_node.children[2..]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solargraph/parser/parser_gem/node_processors/struct_definition.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Parser
+    module ParserGem
+      module NodeProcessors
+        module StructDefinition
+          autoload :StructDefintionNode, 'solargraph/parser/parser_gem/node_processors/struct_definition/struct_definition_node'
+          autoload :StructAssignmentNode, 'solargraph/parser/parser_gem/node_processors/struct_definition/struct_assignment_node'
+
+          class StructNode < Parser::NodeProcessor::Base
+            # @return [Boolean] continue processing the next processor of the same node.
+            def process
+              return true if struct_definition_node.nil?
+
+              loc = get_node_location(node)
+              nspin = Solargraph::Pin::Namespace.new(
+                type: :class,
+                location: loc,
+                closure: region.closure,
+                # @sg-ignore flow sensitive typing needs to handle attrs
+                name: struct_definition_node.class_name,
+                docstring: docstring,
+                visibility: :public,
+                gates: region.closure.gates.freeze,
+                source: :struct_definition
+              )
+              pins.push nspin
+
+              # define initialize method
+              initialize_method_pin = Pin::Method.new(
+                name: 'initialize',
+                parameters: [],
+                scope: :instance,
+                location: get_node_location(node),
+                closure: nspin,
+                visibility: :private,
+                docstring: docstring,
+                source: :struct_definition
+              )
+
+              pins.push initialize_method_pin
+
+              # @sg-ignore flow sensitive typing needs to handle attrs
+              struct_definition_node.attributes.map do |attribute_node, attribute_name|
+                initialize_method_pin.parameters.push(
+                  Pin::Parameter.new(
+                    name: attribute_name,
+                    decl: struct_definition_node.keyword_init? ? :kwoptarg : :arg,
+                    location: get_node_location(attribute_node),
+                    closure: initialize_method_pin,
+                    source: :struct_definition
+                  )
+                )
+              end
+
+              # define attribute accessors and instance variables
+              # @sg-ignore flow sensitive typing needs to handle attrs
+              struct_definition_node.attributes.each do |attribute_node, attribute_name|
+                [attribute_name, "#{attribute_name}="].each do |name|
+                  docs = docstring.tags.find { |t| t.tag_name == 'param' && t.name == attribute_name }
+
+                  attribute_type = ComplexType.parse(tag_string(docs))
+                  return_type_comment = attribute_comment(docs, false)
+                  param_comment = attribute_comment(docs, true)
+
+                  method_pin = Pin::Method.new(
+                    name: name,
+                    parameters: [],
+                    scope: :instance,
+                    location: get_node_location(attribute_node),
+                    closure: nspin,
+                    docstring: YARD::Docstring.new(return_type_comment),
+                    # even assignments return the value
+                    comments: return_type_comment,
+                    return_type: attribute_type,
+                    visibility: :public,
+                    source: :struct_definition
+                  )
+
+                  if name.end_with?('=')
+                    method_pin.parameters << Pin::Parameter.new(
+                      name: attribute_name,
+                      location: get_node_location(attribute_node),
+                      closure: method_pin,
+                      return_type: attribute_type,
+                      comments: param_comment,
+                      source: :struct_definition
+                    )
+
+                    pins.push Pin::InstanceVariable.new(name: "@#{attribute_name}",
+                                                        closure: method_pin,
+                                                        location: get_node_location(attribute_node),
+                                                        return_type: attribute_type,
+                                                        comments: "@type [#{attribute_type.rooted_tags}]",
+                                                        source: :struct_definition)
+                  end
+
+                  pins.push method_pin
+                end
+              end
+
+              process_children region.update(closure: nspin, visibility: :public)
+              false
+            end
+
+            private
+
+            # @return [StructDefinition::StructDefintionNode, StructDefinition::StructAssignmentNode, nil]
+            def struct_definition_node
+              @struct_definition_node ||= if StructDefintionNode.match?(node)
+                                            StructDefintionNode.new(node)
+                                          elsif StructAssignmentNode.match?(node)
+                                            StructAssignmentNode.new(node)
+                                          end
+            end
+
+            # Gets/generates the relevant docstring for this struct & it's attributes
+            # @return [YARD::Docstring]
+            def docstring
+              @docstring ||= parse_comments
+            end
+
+            # Parses any relevant comments for a struct int a yard docstring
+            # @return [YARD::Docstring]
+            def parse_comments
+              struct_comments = comments_for(node) || ''
+              # @sg-ignore Need to add nil check here
+              struct_definition_node.attributes.each do |attr_node, attr_name|
+                comment = comments_for(attr_node)
+                next if comment.nil?
+
+                # We should support specific comments for an attribute, and that can be either a @return on an @param
+                # But since we merge into the struct_comments, then we should interpret either as a param
+                comment = "@param #{attr_name}#{comment[7..]}" if comment.start_with?('@return')
+
+                struct_comments += "\n#{comment}"
+              end
+
+              Solargraph::Source.parse_docstring(struct_comments).to_docstring
+            end
+
+            # @param tag [YARD::Tags::Tag, nil] The param tag for this attribute.xtract_
+            #
+            # @return [String]
+            def tag_string tag
+              tag&.types&.join(',') || 'undefined'
+            end
+
+            # @param tag [YARD::Tags::Tag, nil] The param tag for this attribute. If nil, this method is a no-op
+            # @param for_setter [Boolean] If true, will return a @param tag instead of a @return tag
+            #
+            # @return [String] The formatted comment for the attribute
+            def attribute_comment tag, for_setter
+              return '' if tag.nil?
+
+              suffix = "[#{tag_string(tag)}] #{tag.text}"
+
+              if for_setter
+                "@param #{tag.name} #{suffix}"
+              else
+                "@return #{suffix}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end