solargraph 0.51.2 → 0.54.2

data/lib/solargraph/parser/node_methods.rb

@@ -3,38 +3,78 @@ module Solargraph
     class NodeMethods
       module_function
 
+      # @abstract
+      # @param node [Parser::AST::Node]
+      # @return [String]
       def unpack_name node
         raise NotImplementedError
       end
 
-      def infer_literal_type node
+      # @abstract
+      # @todo Temporarily here for testing. Move to Solargraph::Parser.
+      # @param node [Parser::AST::Node]
+      # @return [Array<Parser::AST::Node>]
+      def call_nodes_from node
         raise NotImplementedError
       end
 
-      def calls_from node
+      # Find all the nodes within the provided node that potentially return a
+      # value.
+      #
+      # The node parameter typically represents a method's logic, e.g., the
+      # second child (after the :args node) of a :def node. A simple one-line
+      # method would typically return itself, while a node with conditions
+      # would return the resulting node from each conditional branch. Nodes
+      # that follow a :return node are assumed to be unreachable. Nil values
+      # are converted to nil node types.
+      #
+      # @abstract
+      # @param node [Parser::AST::Node]
+      # @return [Array<Parser::AST::Node>]
+      def returns_from_method_body node
         raise NotImplementedError
       end
 
-      def returns_from node
+      # @abstract
+      # @param node [Parser::AST::Node]
+      #
+      # @return [Array<Parser::AST::Node>]
+      def const_nodes_from node
         raise NotImplementedError
       end
 
-      def process node
+      # @abstract
+      # @param cursor [Solargraph::Source::Cursor]
+      # @return [Parser::AST::Node, nil]
+      def find_recipient_node cursor
         raise NotImplementedError
       end
 
-      def references node
+      # @abstract
+      # @param node [Parser::AST::Node]
+      # @return [Array<AST::Node>] low-level value nodes in
+      #   value position.  Does not include explicit return
+      #   statements
+      def value_position_nodes_only(node)
         raise NotImplementedError
       end
 
-      def chain node, filename = nil, in_block = false
+      # @abstract
+      # @param nodes [Enumerable<Parser::AST::Node>]
+      def any_splatted_call?(nodes)
         raise NotImplementedError
       end
 
-      def node? node
+      # @abstract
+      # @param node [Parser::AST::Node]
+      # @return [void]
+      def process node
         raise NotImplementedError
       end
 
+      # @abstract
+      # @param node [Parser::AST::Node]
+      # @return [Hash{Parser::AST::Node => Chain}]
       def convert_hash node
         raise NotImplementedError
       end

data/lib/solargraph/parser/node_processor/base.rb

@@ -13,12 +13,13 @@ module Solargraph
         # @return [Array<Pin::Base>]
         attr_reader :pins
 
-        # @return [Array<Pin::Base>]
+        # @return [Array<Pin::BaseVariable>]
         attr_reader :locals
 
         # @param node [Parser::AST::Node]
         # @param region [Region]
         # @param pins [Array<Pin::Base>]
+        # @param locals [Array<Pin::LocalVariable>]
         def initialize node, region, pins, locals
           @node = node
           @region = region
@@ -54,20 +55,29 @@ module Solargraph
           Location.new(region.filename, range)
         end
 
+        # @param node [Parser::AST::Node]
+        # @return [String, nil]
         def comments_for(node)
           region.source.comments_for(node)
         end
 
+        # @param position [Solargraph::Position]
+        # @return [Pin::Closure, nil]
         def named_path_pin position
           pins.select{|pin| pin.is_a?(Pin::Closure) && pin.path && !pin.path.empty? && pin.location.range.contain?(position)}.last
         end
 
         # @todo Candidate for deprecation
+        # @param position [Solargraph::Position]
+        # @return [Pin::Closure, nil]
         def block_pin position
+          # @todo determine if this can return a Pin::Block
           pins.select{|pin| pin.is_a?(Pin::Closure) && pin.location.range.contain?(position)}.last
         end
 
         # @todo Candidate for deprecation
+        # @param position [Solargraph::Position]
+        # @return [Pin::Closure, nil]
         def closure_pin position
           pins.select{|pin| pin.is_a?(Pin::Closure) && pin.location.range.contain?(position)}.last
         end

data/lib/solargraph/parser/node_processor.rb

@@ -24,6 +24,7 @@ module Solargraph
       # @param node [Parser::AST::Node]
       # @param region [Region]
       # @param pins [Array<Pin::Base>]
+      # @param locals [Array<Pin::BaseVariable>]
       # @return [Array(Array<Pin::Base>, Array<Pin::Base>)]
       def self.process node, region = Region.new, pins = [], locals = []
         if pins.empty?

data/lib/solargraph/parser/{legacy → parser_gem}/class_methods.rb

@@ -1,12 +1,15 @@
+# frozen_string_literal: true
+
 require 'parser/current'
+require 'parser/source/buffer'
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module ClassMethods
         # @param code [String]
-        # @param filename [String]
-        # @return [Array(Parser::AST::Node, Array<Parser::Source::Comment>)]
+        # @param filename [String, nil]
+        # @return [Array(Parser::AST::Node, Hash{Integer => String})]
         def parse_with_comments code, filename = nil
           buffer = ::Parser::Source::Buffer.new(filename, 0)
           buffer.source = code
@@ -29,7 +32,7 @@ module Solargraph
           raise Parser::SyntaxError, e.message
         end
 
-        # @return [Parser::Base]
+        # @return [::Parser::Base]
         def parser
           # @todo Consider setting an instance variable. We might not need to
           #   recreate the parser every time we use it.
@@ -39,19 +42,26 @@ module Solargraph
           parser
         end
 
+        # @param source [Source]
+        # @return [Array(Array<Pin::Base>, Array<Pin::Base>)]
         def map source
           NodeProcessor.process(source.node, Region.new(source: source))
         end
 
-        def returns_from node
-          NodeMethods.returns_from(node)
-        end
-
+        # @param source [Source]
+        # @param name [String]
+        # @return [Array<Location>]
         def references source, name
           if name.end_with?("=")
             reg = /#{Regexp.escape name[0..-2]}\s*=/
+            # @param code [String]
+            # @param offset [Integer]
+            # @return [Array(Integer, Integer), Array(nil, nil)]
             extract_offset = ->(code, offset) { reg.match(code, offset).offset(0) }
           else
+            # @param code [String]
+            # @param offset [Integer]
+            # @return [Array(Integer, Integer), Array(nil, nil)]
             extract_offset = ->(code, offset) { [soff = code.index(name, offset), soff + name.length] }
           end
           inner_node_references(name, source.node).map do |n|
@@ -80,36 +90,48 @@ module Solargraph
           result
         end
 
+        # @return [Source::Chain]
         def chain *args
           NodeChainer.chain *args
         end
 
+        # @return [Source::Chain]
         def chain_string *args
           NodeChainer.load_string *args
         end
 
+        # @return [Array(Array<Pin::Base>, Array<Pin::Base>)]
         def process_node *args
           Solargraph::Parser::NodeProcessor.process *args
         end
 
+        # @param node [Parser::AST::Node]
+        # @return [String, nil]
         def infer_literal_node_type node
           NodeMethods.infer_literal_node_type node
         end
 
+        # @return [Integer]
         def version
           parser.version
         end
 
+        # @param node [BasicObject]
+        # @return [Boolean]
         def is_ast_node? node
           node.is_a?(::Parser::AST::Node)
         end
 
+        # @param node [Parser::AST::Node]
+        # @return [Range]
         def node_range node
           st = Position.new(node.loc.line, node.loc.column)
           en = Position.new(node.loc.last_line, node.loc.last_column)
           Range.new(st, en)
         end
 
+        # @param node [Parser::AST::Node]
+        # @return [Array<Range>]
         def string_ranges node
           return [] unless is_ast_node?(node)
           result = []
@@ -128,7 +150,7 @@ module Solargraph
             end
           end
           result
-        end  
+        end
       end
     end
   end

data/lib/solargraph/parser/{legacy → parser_gem}/flawed_builder.rb

@@ -2,11 +2,13 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       # A custom builder for source parsers that ignores character encoding
       # issues in literal strings.
       #
       class FlawedBuilder < ::Parser::Builders::Default
+        # @param token [::Parser::AST::Node]
+        # @return [String]
         def string_value(token)
           value(token)
         end

data/lib/solargraph/parser/{legacy → parser_gem}/node_chainer.rb

@@ -2,7 +2,7 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       # A factory for generating chains from nodes.
       #
       class NodeChainer
@@ -10,11 +10,12 @@ module Solargraph
         Chain = Source::Chain
 
         # @param node [Parser::AST::Node]
-        # @param filename [String]
-        def initialize node, filename = nil, in_block = false
+        # @param filename [String, nil]
+        # @param parent [Parser::AST::Node, nil]
+        def initialize node, filename = nil, parent = nil
           @node = node
           @filename = filename
-          @in_block = in_block ? 1 : 0
+          @parent = parent
         end
 
         # @return [Source::Chain]
@@ -25,10 +26,11 @@ module Solargraph
 
         class << self
           # @param node [Parser::AST::Node]
-          # @param filename [String]
+          # @param filename [String, nil]
+          # @param parent [Parser::AST::Node, nil]
           # @return [Source::Chain]
-          def chain node, filename = nil, in_block = false
-            NodeChainer.new(node, filename, in_block).chain
+          def chain node, filename = nil, parent = nil
+            NodeChainer.new(node, filename, parent).chain
           end
 
           # @param code [String]
@@ -47,66 +49,61 @@ module Solargraph
         # @return [Array<Chain::Link>]
         def generate_links n
           return [] unless n.is_a?(::Parser::AST::Node)
-          return generate_links(n.children[0]) if n.type == :begin
           return generate_links(n.children[0]) if n.type == :splat
+          # @type [Array<Chain::Link>]
           result = []
           if n.type == :block
-            @in_block += 1
-            result.concat generate_links(n.children[0])
-            @in_block -= 1
+            result.concat NodeChainer.chain(n.children[0], @filename, n).links
           elsif n.type == :send
             if n.children[0].is_a?(::Parser::AST::Node)
               result.concat generate_links(n.children[0])
-              args = []
-              n.children[2..-1].each do |c|
-                args.push NodeChainer.chain(c)
-              end
-              result.push Chain::Call.new(n.children[1].to_s, args, @in_block > 0 || block_passed?(n))
+              result.push Chain::Call.new(n.children[1].to_s, node_args(n), passed_block(n))
             elsif n.children[0].nil?
               args = []
               n.children[2..-1].each do |c|
-                args.push NodeChainer.chain(c)
+                args.push NodeChainer.chain(c, @filename, n)
               end
-              result.push Chain::Call.new(n.children[1].to_s, args, @in_block > 0 || block_passed?(n))
+              result.push Chain::Call.new(n.children[1].to_s, node_args(n), passed_block(n))
             else
               raise "No idea what to do with #{n}"
             end
           elsif n.type == :csend
             if n.children[0].is_a?(::Parser::AST::Node)
               result.concat generate_links(n.children[0])
-              args = []
-              n.children[2..-1].each do |c|
-                args.push NodeChainer.chain(c)
-              end
-              result.push Chain::QCall.new(n.children[1].to_s, args, @in_block > 0 || block_passed?(n))
+              result.push Chain::QCall.new(n.children[1].to_s, node_args(n))
             elsif n.children[0].nil?
-              args = []
-              n.children[2..-1].each do |c|
-                args.push NodeChainer.chain(c)
-              end
-              result.push Chain::QCall.new(n.children[1].to_s, args, @in_block > 0 || block_passed?(n))
+              result.push Chain::QCall.new(n.children[1].to_s, node_args(n))
             else
               raise "No idea what to do with #{n}"
             end
           elsif n.type == :self
             result.push Chain::Head.new('self')
           elsif n.type == :zsuper
-            result.push Chain::ZSuper.new('super', @in_block > 0 || block_passed?(n))
+            result.push Chain::ZSuper.new('super')
           elsif n.type == :super
-            args = n.children.map { |c| NodeChainer.chain(c) }
-            result.push Chain::Call.new('super', args, @in_block > 0 || block_passed?(n))
+            args = n.children.map { |c| NodeChainer.chain(c, @filename, n) }
+            result.push Chain::Call.new('super', args)
+          elsif n.type == :yield
+            args = n.children.map { |c| NodeChainer.chain(c, @filename, n) }
+            result.push Chain::Call.new('yield', args)
           elsif n.type == :const
             const = unpack_name(n)
             result.push Chain::Constant.new(const)
-          elsif [:lvar, :lvasgn].include?(n.type)
+          elsif [:lvasgn, :ivasgn, :gvasgn, :cvasgn].include?(n.type)
+            result.concat generate_links(n.children[1])
+          elsif n.type == :lvar
             result.push Chain::Call.new(n.children[0].to_s)
-          elsif [:ivar, :ivasgn].include?(n.type)
-            result.push Chain::InstanceVariable.new(n.children[0].to_s)
-          elsif [:cvar, :cvasgn].include?(n.type)
-            result.push Chain::ClassVariable.new(n.children[0].to_s)
-          elsif [:gvar, :gvasgn].include?(n.type)
-            result.push Chain::GlobalVariable.new(n.children[0].to_s)
+          elsif n.type == :ivar
+             result.push Chain::InstanceVariable.new(n.children[0].to_s)
+          elsif n.type == :cvar
+             result.push Chain::ClassVariable.new(n.children[0].to_s)
+          elsif n.type == :gvar
+             result.push Chain::GlobalVariable.new(n.children[0].to_s)
           elsif n.type == :or_asgn
+            # @todo: Need a new Link class here that evaluates the
+            #   existing variable type with the RHS, and generates a
+            #   union type of the LHS alone if never nil, or minus nil +
+            #   RHS if it is nilable.
             result.concat generate_links n.children[1]
           elsif [:class, :module, :def, :defs].include?(n.type)
             # @todo Undefined or what?
@@ -114,9 +111,11 @@ module Solargraph
           elsif n.type == :and
             result.concat generate_links(n.children.last)
           elsif n.type == :or
-            result.push Chain::Or.new([NodeChainer.chain(n.children[0], @filename), NodeChainer.chain(n.children[1], @filename)])
+            result.push Chain::Or.new([NodeChainer.chain(n.children[0], @filename), NodeChainer.chain(n.children[1], @filename, n)])
+          elsif n.type == :if
+            result.push Chain::If.new([NodeChainer.chain(n.children[1], @filename), NodeChainer.chain(n.children[2], @filename, n)])
           elsif [:begin, :kwbegin].include?(n.type)
-            result.concat generate_links(n.children[0])
+            result.concat generate_links(n.children.last)
           elsif n.type == :block_pass
             block_variable_name_node = n.children[0]
             if block_variable_name_node.nil?
@@ -124,10 +123,17 @@ module Solargraph
               # added in Ruby 3.1 - https://bugs.ruby-lang.org/issues/11256
               result.push Chain::BlockVariable.new(nil)
             else
-              result.push Chain::BlockVariable.new("&#{block_variable_name_node.children[0].to_s}")
+              if block_variable_name_node.type == :sym
+                result.push Chain::BlockSymbol.new("#{block_variable_name_node.children[0].to_s}")
+              else
+                result.push Chain::BlockVariable.new("&#{block_variable_name_node.children[0].to_s}")
+              end
             end
           elsif n.type == :hash
             result.push Chain::Hash.new('::Hash', hash_is_splatted?(n))
+          elsif n.type == :array
+            chained_children = n.children.map { |c| NodeChainer.chain(c) }
+            result.push Source::Chain::Array.new(chained_children)
           else
             lit = infer_literal_node_type(n)
             result.push (lit ? Chain::Literal.new(lit) : Chain::Link.new)
@@ -135,6 +141,7 @@ module Solargraph
           result
         end
 
+        # @param node [Parser::AST::Node]
         def hash_is_splatted? node
           return false unless Parser.is_ast_node?(node) && node.type == :hash
           return false unless Parser.is_ast_node?(node.children.last) && node.children.last.type == :kwsplat
@@ -142,8 +149,20 @@ module Solargraph
           true
         end
 
-        def block_passed? node
-          node.children.last.is_a?(::Parser::AST::Node) && node.children.last.type == :block_pass
+        # @param node [Parser::AST::Node]
+        # @return [Source::Chain, nil]
+        def passed_block node
+          return unless node == @node && @parent&.type == :block
+
+          NodeChainer.chain(@parent.children[2], @filename)
+        end
+
+        # @param node [Parser::AST::Node]
+        # @return [Array<Source::Chain>]
+        def node_args node
+          node.children[2..-1].map do |child|
+            NodeChainer.chain(child, @filename, node)
+          end
         end
       end
     end