solargraph 0.52.0 → 0.53.0

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

@@ -1,10 +1,26 @@
 # frozen_string_literal: true
 
 require 'parser'
+require 'ast'
 
+# Teach AST::Node#children about its generic type
+#
+# @todo contribute back to https://github.com/ruby/gem_rbs_collection/blob/main/gems/ast/2.4/ast.rbs
+#
+# @!parse
+#   module ::AST
+#     class Node
+#       # New children
+#
+#       # @return [Array<AST::Node>]
+#       attr_reader :children
+#     end
+#   end
+
+# https://github.com/whitequark/parser
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeMethods
         module_function
 
@@ -17,6 +33,7 @@ module Solargraph
         # @param node [Parser::AST::Node]
         # @return [Array<String>]
         def pack_name(node)
+          # @type [Array<String>]
           parts = []
           if node.is_a?(AST::Node)
             node.children.each { |n|
@@ -75,6 +92,10 @@ module Solargraph
           Position.new(node.loc.last_line, node.loc.last_column)
         end
 
+        # @param node [Parser::AST::Node]
+        # @param signature [String]
+        #
+        # @return [String]
         def drill_signature node, signature
           return signature unless node.is_a?(AST::Node)
           if node.type == :const or node.type == :cbase
@@ -96,6 +117,8 @@ module Solargraph
           signature
         end
 
+        # @param node [Parser::AST::Node]
+        # @return [Hash{Parser::AST::Node => Chain}]
         def convert_hash node
           return {} unless Parser.is_ast_node?(node)
           return convert_hash(node.children[0]) if node.type == :kwsplat
@@ -110,6 +133,9 @@ module Solargraph
 
         NIL_NODE = ::Parser::AST::Node.new(:nil)
 
+        # @param node [Parser::AST::Node]
+        #
+        # @return [Array<Parser::AST::Node>]
         def const_nodes_from node
           return [] unless Parser.is_ast_node?(node)
           result = []
@@ -121,20 +147,25 @@ module Solargraph
           result
         end
 
+        # @param node [Parser::AST::Node]
         def splatted_hash? node
           Parser.is_ast_node?(node.children[0]) && node.children[0].type == :kwsplat
         end
 
+        # @param node [Parser::AST::Node]
         def splatted_call? node
           return false unless Parser.is_ast_node?(node)
           Parser.is_ast_node?(node.children[0]) && node.children[0].type == :kwsplat && node.children[0].children[0].type != :hash
         end
 
+        # @param nodes [Enumerable<Parser::AST::Node>]
         def any_splatted_call?(nodes)
           nodes.any? { |n| splatted_call?(n) }
         end
 
         # @todo Temporarily here for testing. Move to Solargraph::Parser.
+        # @param node [Parser::AST::Node]
+        # @return [Array<Parser::AST::Node>]
         def call_nodes_from node
           return [] unless node.is_a?(::Parser::AST::Node)
           result = []
@@ -172,11 +203,22 @@ module Solargraph
         #
         # @param node [Parser::AST::Node]
         # @return [Array<Parser::AST::Node>]
-        def returns_from node
-          DeepInference.get_return_nodes(node).map { |n| n || NIL_NODE }
+        def returns_from_method_body node
+          # @todo is the || NIL_NODE necessary?
+          # STDERR.puts("Evaluating expression: #{node.inspect}")
+          DeepInference.from_method_body(node).map { |n| n || NIL_NODE }
+        end
+
+        # @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)
+          DeepInference.value_position_nodes_only(node).map { |n| n || NIL_NODE }
         end
 
         # @param cursor [Solargraph::Source::Cursor]
+        # @return [Parser::AST::Node, nil]
         def find_recipient_node cursor
           return repaired_find_recipient_node(cursor) if cursor.source.repaired? && cursor.source.code[cursor.offset - 1] == '('
           source = cursor.source
@@ -211,36 +253,130 @@ module Solargraph
           nil
         end
 
+        # @param cursor [Solargraph::Source::Cursor]
+        # @return [Parser::AST::Node, nil]
         def repaired_find_recipient_node cursor
           cursor = cursor.source.cursor_at([cursor.position.line, cursor.position.column - 1])
           node = cursor.source.tree_at(cursor.position.line, cursor.position.column).first
           return node if node && node.type == :send
         end
 
+        #
+        # Concepts:
+        #
+        #  - statement - one single node in the AST.  Generally used
+        #    synonymously with how the Parser gem uses the term
+        #    'expression'.  This may have side effects (e.g.,
+        #    registering a method in the namespace, modifying
+        #    variables or doing I/O).  It may encapsulate multiple
+        #    other statements (see compound statement).
+        #
+        #  - value - something that can be assigned to a variable by
+        #    evaluating a statement
+        #
+        #  - value node - the 'lowest level' AST node whose return
+        #    type is a subset of the value type of the overall
+        #    statement.  Might be a literal, a method call, etc - the
+        #    goal is to find the lowest level node, which we can use
+        #    Chains and Pins later on to determine the type of.
+        #
+        #    e.g., if the node 'b ? 123 : 456' were a return value, we
+        #    know the actual return values possible are 123 and 456,
+        #    and can disregard the rest.
+        #
+        #  - value type - the type representing the multiple possible
+        #    values that can result from evaluation of the statement.
+        #
+        #  - return type - the type describing the values a statement
+        #    might evaluate to.  When used with a method, the term
+        #    describes the values that may result from the method
+        #    being called, and includes explicit return statements
+        #    within the method body's closure.
+        #
+        #  - method body - a compound statement with parameters whose
+        #    return value type must account both for the explicit
+        #    'return' statemnts as well as the final statements
+        #    executed in any given control flow through the method.
+        #
+        #  - explicit return statement - a statement which, when part of a
+        #     method body, is a possible value of a call to that method -
+        #     e.g., "return 123"
+        #
+        #  - compound statement - a statement which can be expanded to
+        #     be multiple statements in a row, executed in the context
+        #     of a method which can be explicitly returned from.
+        #
+        #  - value position - the positions in the AST where the
+        #    return type of the statement would be one of the return
+        #    types of any compound statements it is a part of.  For a
+        #    compound statement, the last of the child statements
+        #    would be in return position.  This concept can be applied
+        #    recursively through e.g. conditionals to find a list of
+        #    statements in value positions.
         module DeepInference
           class << self
-            CONDITIONAL = [:if, :unless]
-            REDUCEABLE = [:begin, :kwbegin]
+            CONDITIONAL_ALL_BUT_FIRST = [:if, :unless, :or_asgn]
+            CONDITIONAL_ALL = [:or]
+            ONLY_ONE_CHILD = [:return]
+            FIRST_TWO_CHILDREN = [:rescue]
+            COMPOUND_STATEMENTS = [:begin, :kwbegin]
             SKIPPABLE = [:def, :defs, :class, :sclass, :module]
+            FUNCTION_VALUE = [:block]
+            CASE_STATEMENT = [:case]
 
-            # @param node [Parser::AST::Node]
+            # @param node [AST::Node] a method body compound statement
+            # @param include_explicit_returns [Boolean] If true,
+            #    include the value nodes of the parameter of the
+            #    'return' statements in the type returned.
+            # @return [Array<AST::Node>] low-level value nodes from
+            #   both nodes in value position as well as explicit
+            #   return statements in the method's closure.
+            def from_method_body node
+              from_value_position_statement(node, include_explicit_returns: true)
+            end
+
+            # @param node [AST::Node] an individual statement, to be
+            #   evaluated outside the context of a containing method
+            # @return [Array<AST::Node>] low-level value nodes in
+            #   value position.  Does not include explicit return
+            #   statements
+            def value_position_nodes_only(node)
+              from_value_position_statement(node, include_explicit_returns: false)
+            end
+
+            # Look at known control statements and use them to find
+            # more specific return nodes.
+            #
+            # @param node [Parser::AST::Node] Statement which is in
+            #    value position for a method body
+            # @param include_explicit_returns [Boolean] If true,
+            #    include the value nodes of the parameter of the
+            #    'return' statements in the type returned.
             # @return [Array<Parser::AST::Node>]
-            def get_return_nodes node
+            def from_value_position_statement node, include_explicit_returns: true
+              # STDERR.puts("from_expression called on #{node.inspect}")
               return [] unless node.is_a?(::Parser::AST::Node)
+              # @type [Array<Parser::AST::Node>]
               result = []
-              if REDUCEABLE.include?(node.type)
-                result.concat get_return_nodes_from_children(node)
-              elsif CONDITIONAL.include?(node.type)
+              if COMPOUND_STATEMENTS.include?(node.type)
+                result.concat from_value_position_compound_statement node
+              elsif CONDITIONAL_ALL_BUT_FIRST.include?(node.type)
                 result.concat reduce_to_value_nodes(node.children[1..-1])
                 # result.push NIL_NODE unless node.children[2]
-              elsif node.type == :or
+              elsif CONDITIONAL_ALL.include?(node.type)
                 result.concat reduce_to_value_nodes(node.children)
-              elsif node.type == :return
+              elsif ONLY_ONE_CHILD.include?(node.type)
                 result.concat reduce_to_value_nodes([node.children[0]])
-              elsif node.type == :block
+              elsif FIRST_TWO_CHILDREN.include?(node.type)
+                result.concat reduce_to_value_nodes([node.children[0], node.children[1]])
+              elsif FUNCTION_VALUE.include?(node.type)
+                # the block itself is a first class value that could be returned
                 result.push node
-                result.concat get_return_nodes_only(node.children[2])
-              elsif node.type == :case
+                # @todo any explicit returns actually return from
+                #   scope in which the proc is run.  This asssumes
+                #   that the function is executed here.
+                result.concat explicit_return_values_from_compound_statement(node.children[2]) if include_explicit_returns
+              elsif CASE_STATEMENT.include?(node.type)
                 node.children[1..-1].each do |cc|
                   if cc.nil?
                     result.push NIL_NODE
@@ -251,36 +387,68 @@ module Solargraph
                     result.concat reduce_to_value_nodes([cc])
                   end
                 end
+              elsif node.type == :resbody
+                result.concat reduce_to_value_nodes([node.children[2]])
               else
                 result.push node
               end
               result
             end
 
-            private
-
-            def get_return_nodes_from_children parent
+            # Treat parent as as a begin block and use the last node's
+            # return node plus any explicit return nodes' return nodes.  e.g.,
+            #
+            #    123
+            #    456
+            #    return 'a' if foo == bar
+            #    789
+            #
+            #  would return 'a' and 789.
+            #
+            # @param parent [Parser::AST::Node]
+            #
+            # @return [Array<Parser::AST::Node>]
+            def from_value_position_compound_statement parent
               result = []
               nodes = parent.children.select{|n| n.is_a?(AST::Node)}
               nodes.each_with_index do |node, idx|
                 if node.type == :block
-                  result.concat get_return_nodes_only(node.children[2])
+                  result.concat explicit_return_values_from_compound_statement(node.children[2])
+                elsif node.type == :rescue
+                  # body statements
+                  result.concat from_value_position_statement(node.children[0])
+                  # rescue statements
+                  result.concat from_value_position_statement(node.children[1])
                 elsif SKIPPABLE.include?(node.type)
                   next
+                elsif node.type == :resbody
+                  result.concat reduce_to_value_nodes([node.children[2]])
                 elsif node.type == :return
                   result.concat reduce_to_value_nodes([node.children[0]])
-                  # Return the result here because the rest of the code is
-                  # unreachable
+                  # Return here because the rest of the code is
+                  # unreachable and shouldn't be looked at
                   return result
                 else
-                  result.concat get_return_nodes_only(node)
+                  result.concat explicit_return_values_from_compound_statement(node)
                 end
-                result.concat reduce_to_value_nodes([nodes.last]) if idx == nodes.length - 1
+                # handle last line of compound statements, which is in
+                # value position.  we already have the explicit values
+                # from above; now we need to also gather the value
+                # position nodes
+                result.concat from_value_position_statement(nodes.last, include_explicit_returns: false) if idx == nodes.length - 1
               end
               result
             end
 
-            def get_return_nodes_only parent
+            private
+
+            # Useful when this statement isn't in value position, but
+            # we care explicit return statements nonetheless.
+            #
+            # @param parent [Parser::AST::Node]
+            #
+            # @return [Array<Parser::AST::Node>]
+            def explicit_return_values_from_compound_statement parent
               return [] unless parent.is_a?(::Parser::AST::Node)
               result = []
               nodes = parent.children.select{|n| n.is_a?(::Parser::AST::Node)}
@@ -292,27 +460,31 @@ module Solargraph
                   # unreachable
                   return result
                 else
-                  result.concat get_return_nodes_only(node)
+                  result.concat explicit_return_values_from_compound_statement(node)
                 end
               end
               result
             end
 
+            # @param nodes [Enumerable<Parser::AST::Node, BaseObject>]
+            # @return [Array<Parser::AST::Node, nil>]
             def reduce_to_value_nodes nodes
               result = []
               nodes.each do |node|
                 if !node.is_a?(::Parser::AST::Node)
                   result.push nil
-                elsif REDUCEABLE.include?(node.type)
-                  result.concat get_return_nodes_from_children(node)
-                elsif CONDITIONAL.include?(node.type)
+                elsif COMPOUND_STATEMENTS.include?(node.type)
+                  result.concat from_value_position_compound_statement(node)
+                elsif CONDITIONAL_ALL_BUT_FIRST.include?(node.type)
                   result.concat reduce_to_value_nodes(node.children[1..-1])
                 elsif node.type == :return
                   result.concat reduce_to_value_nodes([node.children[0]])
                 elsif node.type == :or
                   result.concat reduce_to_value_nodes(node.children)
                 elsif node.type == :block
-                  result.concat get_return_nodes_only(node.children[2])
+                  result.concat explicit_return_values_from_compound_statement(node.children[2])
+                elsif node.type == :resbody
+                  result.concat reduce_to_value_nodes([node.children[2]])
                 else
                   result.push node
                 end

data/lib/solargraph/parser/{rubyvm → parser_gem}/node_processors/alias_node.rb

@@ -2,7 +2,7 @@
 
 module Solargraph
   module Parser
-    module Rubyvm
+    module ParserGem
       module NodeProcessors
         class AliasNode < Parser::NodeProcessor::Base
           def process

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

@@ -2,7 +2,7 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class ArgsNode < Parser::NodeProcessor::Base
           def process
@@ -29,6 +29,7 @@ module Solargraph
 
           private
 
+          # @return [void]
           def forward
             loc = get_node_location(node)
             locals.push Solargraph::Pin::Parameter.new(
@@ -40,6 +41,8 @@ module Solargraph
             region.closure.parameters.push locals.last
           end
 
+          # @param node [AST::Node]
+          # @return [Symbol]
           def get_decl node
             node.type
           end

data/lib/solargraph/parser/{rubyvm → parser_gem}/node_processors/begin_node.rb

@@ -2,7 +2,7 @@
 
 module Solargraph
   module Parser
-    module Rubyvm
+    module ParserGem
       module NodeProcessors
         class BeginNode < Parser::NodeProcessor::Base
           def process

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

@@ -2,10 +2,10 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class BlockNode < Parser::NodeProcessor::Base
-          include Legacy::NodeMethods
+          include ParserGem::NodeMethods
 
           def process
             location = get_node_location(node)
@@ -21,6 +21,7 @@ module Solargraph
             pins.push Solargraph::Pin::Block.new(
               location: location,
               closure: parent,
+              node: node,
               receiver: node.children[0],
               comments: comments_for(node),
               scope: region.scope || region.closure.context.scope

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

@@ -2,10 +2,10 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class CasgnNode < Parser::NodeProcessor::Base
-          include Legacy::NodeMethods
+          include ParserGem::NodeMethods
 
           def process
             pins.push Solargraph::Pin::Constant.new(

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

@@ -2,7 +2,7 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class CvasgnNode < Parser::NodeProcessor::Base
           def process

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

@@ -2,7 +2,7 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class DefNode < Parser::NodeProcessor::Base
           def process

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

@@ -2,10 +2,10 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class DefsNode < DefNode
-          include Legacy::NodeMethods
+          include ParserGem::NodeMethods
 
           def process
             s_visi = region.visibility

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

@@ -2,7 +2,7 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class GvasgnNode < Parser::NodeProcessor::Base
           def process

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

@@ -2,10 +2,10 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class IvasgnNode < Parser::NodeProcessor::Base
-          include Legacy::NodeMethods
+          include ParserGem::NodeMethods
 
           def process
             loc = get_node_location(node)

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

@@ -2,10 +2,10 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class LvasgnNode < Parser::NodeProcessor::Base
-          include Legacy::NodeMethods
+          include ParserGem::NodeMethods
 
           def process
             here = get_node_start_position(node)

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

@@ -2,10 +2,10 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class NamespaceNode < Parser::NodeProcessor::Base
-          include Legacy::NodeMethods
+          include ParserGem::NodeMethods
 
           def process
             sc = nil

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

@@ -2,7 +2,7 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class OrasgnNode < Parser::NodeProcessor::Base
           def process

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

@@ -2,13 +2,13 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class ResbodyNode < Parser::NodeProcessor::Base
-          include Legacy::NodeMethods
+          include ParserGem::NodeMethods
 
           def process
-            if node.children[1]
+            if node.children[1] # Exception local variable name
               here = get_node_start_position(node.children[1])
               presence = Range.new(here, region.closure.location.range.ending)
               loc = get_node_location(node.children[1])

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

@@ -2,7 +2,7 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class SclassNode < Parser::NodeProcessor::Base
           def process

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

@@ -2,10 +2,10 @@
 
 module Solargraph
   module Parser
-    module Legacy
+    module ParserGem
       module NodeProcessors
         class SendNode < Parser::NodeProcessor::Base
-          include Legacy::NodeMethods
+          include ParserGem::NodeMethods
 
           def process
             if node.children[0].nil?

data/lib/solargraph/parser/{rubyvm → parser_gem}/node_processors/sym_node.rb

@@ -2,7 +2,7 @@
 
 module Solargraph
   module Parser
-    module Rubyvm
+    module ParserGem
       module NodeProcessors
         class SymNode < Parser::NodeProcessor::Base
           def process

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'solargraph/parser/node_processor'
+
+module Solargraph
+  module Parser
+    module ParserGem
+      module NodeProcessors
+        autoload :BeginNode,     'solargraph/parser/parser_gem/node_processors/begin_node'
+        autoload :DefNode,       'solargraph/parser/parser_gem/node_processors/def_node'
+        autoload :DefsNode,      'solargraph/parser/parser_gem/node_processors/defs_node'
+        autoload :SendNode,      'solargraph/parser/parser_gem/node_processors/send_node'
+        autoload :NamespaceNode, 'solargraph/parser/parser_gem/node_processors/namespace_node'
+        autoload :SclassNode,    'solargraph/parser/parser_gem/node_processors/sclass_node'
+        autoload :IvasgnNode,    'solargraph/parser/parser_gem/node_processors/ivasgn_node'
+        autoload :CvasgnNode,    'solargraph/parser/parser_gem/node_processors/cvasgn_node'
+        autoload :LvasgnNode,    'solargraph/parser/parser_gem/node_processors/lvasgn_node'
+        autoload :GvasgnNode,    'solargraph/parser/parser_gem/node_processors/gvasgn_node'
+        autoload :CasgnNode,     'solargraph/parser/parser_gem/node_processors/casgn_node'
+        autoload :AliasNode,     'solargraph/parser/parser_gem/node_processors/alias_node'
+        autoload :ArgsNode,      'solargraph/parser/parser_gem/node_processors/args_node'
+        autoload :BlockNode,     'solargraph/parser/parser_gem/node_processors/block_node'
+        autoload :OrasgnNode,    'solargraph/parser/parser_gem/node_processors/orasgn_node'
+        autoload :SymNode,       'solargraph/parser/parser_gem/node_processors/sym_node'
+        autoload :ResbodyNode,   'solargraph/parser/parser_gem/node_processors/resbody_node'
+      end
+    end
+
+    module NodeProcessor
+      register :source,       ParserGem::NodeProcessors::BeginNode
+      register :begin,        ParserGem::NodeProcessors::BeginNode
+      register :kwbegin,      ParserGem::NodeProcessors::BeginNode
+      register :rescue,       ParserGem::NodeProcessors::BeginNode
+      register :resbody,      ParserGem::NodeProcessors::ResbodyNode
+      register :def,          ParserGem::NodeProcessors::DefNode
+      register :defs,         ParserGem::NodeProcessors::DefsNode
+      register :send,         ParserGem::NodeProcessors::SendNode
+      register :class,        ParserGem::NodeProcessors::NamespaceNode
+      register :module,       ParserGem::NodeProcessors::NamespaceNode
+      register :sclass,       ParserGem::NodeProcessors::SclassNode
+      register :ivasgn,       ParserGem::NodeProcessors::IvasgnNode
+      register :cvasgn,       ParserGem::NodeProcessors::CvasgnNode
+      register :lvasgn,       ParserGem::NodeProcessors::LvasgnNode
+      register :gvasgn,       ParserGem::NodeProcessors::GvasgnNode
+      register :casgn,        ParserGem::NodeProcessors::CasgnNode
+      register :alias,        ParserGem::NodeProcessors::AliasNode
+      register :args,         ParserGem::NodeProcessors::ArgsNode
+      register :forward_args, ParserGem::NodeProcessors::ArgsNode
+      register :block,        ParserGem::NodeProcessors::BlockNode
+      register :or_asgn,      ParserGem::NodeProcessors::OrasgnNode
+      register :sym,          ParserGem::NodeProcessors::SymNode
+    end
+  end
+end