Introduce NodeContext for listeners (#2099)

* Introduce TargetContext

* Update tests

* Update ADDONS docs

* Fix types

* Remove accidental comment

* Cleanup

* Update lib/ruby_lsp/listeners/completion.rb

Co-authored-by: Vinicius Stock <[email protected]>

* Rename to NodeContext

* Rename 'closest' to 'node'

* Rename

* Rename file

* Lint

* Fix naming

* Explain

---------

Co-authored-by: Vinicius Stock <[email protected]>

Author: andyw8

ADDONS.md

@@ -143,7 +143,7 @@ module RubyLsp
         "Ruby LSP My Gem"
       end
 
-      def create_hover_listener(response_builder, nesting, index, dispatcher)
+      def create_hover_listener(response_builder, node_context, index, dispatcher)
         # Use the listener factory methods to instantiate listeners with parameters sent by the LSP combined with any
         # pre-computed information in the addon. These factory methods are invoked on every request
         Hover.new(client, response_builder, @config, dispatcher)
@@ -259,13 +259,13 @@ module RubyLsp
         "Ruby LSP My Gem"
       end
 
-      def create_hover_listener(response_builder, nesting, index, dispatcher)
-        MyHoverListener.new(@message_queue, response_builder, nesting, index, dispatcher)
+      def create_hover_listener(response_builder, node_context, index, dispatcher)
+        MyHoverListener.new(@message_queue, response_builder, node_context, index, dispatcher)
       end
     end
 
     class MyHoverListener
-      def initialize(message_queue, response_builder, nesting, index, dispatcher)
+      def initialize(message_queue, response_builder, node_context, index, dispatcher)
         @message_queue = message_queue
 
         @message_queue << Notification.new(

lib/ruby_lsp/addon.rb

@@ -131,11 +131,11 @@ def create_code_lens_listener(response_builder, uri, dispatcher); end
     sig do
       overridable.params(
         response_builder: ResponseBuilders::Hover,
-        nesting: T::Array[String],
+        node_context: NodeContext,
         dispatcher: Prism::Dispatcher,
       ).void
     end
-    def create_hover_listener(response_builder, nesting, dispatcher); end
+    def create_hover_listener(response_builder, node_context, dispatcher); end
 
     # Creates a new DocumentSymbol listener. This method is invoked on every DocumentSymbol request
     sig do
@@ -159,21 +159,21 @@ def create_semantic_highlighting_listener(response_builder, dispatcher); end
       overridable.params(
         response_builder: ResponseBuilders::CollectionResponseBuilder[Interface::Location],
         uri: URI::Generic,
-        nesting: T::Array[String],
+        node_context: NodeContext,
         dispatcher: Prism::Dispatcher,
       ).void
     end
-    def create_definition_listener(response_builder, uri, nesting, dispatcher); end
+    def create_definition_listener(response_builder, uri, node_context, dispatcher); end
 
     # Creates a new Completion listener. This method is invoked on every Completion request
     sig do
       overridable.params(
         response_builder: ResponseBuilders::CollectionResponseBuilder[Interface::CompletionItem],
-        nesting: T::Array[String],
+        node_context: NodeContext,
         dispatcher: Prism::Dispatcher,
         uri: URI::Generic,
       ).void
     end
-    def create_completion_listener(response_builder, nesting, dispatcher, uri); end
+    def create_completion_listener(response_builder, node_context, dispatcher, uri); end
   end
 end

lib/ruby_lsp/document.rb

@@ -110,7 +110,7 @@ def create_scanner
       params(
         position: T::Hash[Symbol, T.untyped],
         node_types: T::Array[T.class_of(Prism::Node)],
-      ).returns([T.nilable(Prism::Node), T.nilable(Prism::Node), T::Array[String]])
+      ).returns(NodeContext)
     end
     def locate_node(position, node_types: [])
       locate(@parse_result.value, create_scanner.find_char_position(position), node_types: node_types)
@@ -121,7 +121,7 @@ def locate_node(position, node_types: [])
         node: Prism::Node,
         char_position: Integer,
         node_types: T::Array[T.class_of(Prism::Node)],
-      ).returns([T.nilable(Prism::Node), T.nilable(Prism::Node), T::Array[String]])
+      ).returns(NodeContext)
     end
     def locate(node, char_position, node_types: [])
       queue = T.let(node.child_nodes.compact, T::Array[T.nilable(Prism::Node)])
@@ -170,7 +170,7 @@ def locate(node, char_position, node_types: [])
         end
       end
 
-      [closest, parent, nesting.map { |n| n.constant_path.location.slice }]
+      NodeContext.new(closest, parent, nesting.map { |n| n.constant_path.location.slice })
     end
 
     sig { returns(T::Boolean) }

lib/ruby_lsp/internal.rb

@@ -29,6 +29,7 @@
 require "ruby_lsp/server"
 require "ruby_lsp/requests"
 require "ruby_lsp/response_builders"
+require "ruby_lsp/node_context"
 require "ruby_lsp/document"
 require "ruby_lsp/ruby_document"
 require "ruby_lsp/store"

lib/ruby_lsp/listeners/completion.rb

@@ -11,17 +11,17 @@ class Completion
         params(
           response_builder: ResponseBuilders::CollectionResponseBuilder[Interface::CompletionItem],
           global_state: GlobalState,
-          nesting: T::Array[String],
+          node_context: NodeContext,
           typechecker_enabled: T::Boolean,
           dispatcher: Prism::Dispatcher,
           uri: URI::Generic,
         ).void
       end
-      def initialize(response_builder, global_state, nesting, typechecker_enabled, dispatcher, uri) # rubocop:disable Metrics/ParameterLists
+      def initialize(response_builder, global_state, node_context, typechecker_enabled, dispatcher, uri) # rubocop:disable Metrics/ParameterLists
         @response_builder = response_builder
         @global_state = global_state
         @index = T.let(global_state.index, RubyIndexer::Index)
-        @nesting = nesting
+        @node_context = node_context
         @typechecker_enabled = typechecker_enabled
         @uri = uri
 
@@ -47,7 +47,7 @@ def on_constant_read_node_enter(node)
         name = constant_name(node)
         return if name.nil?
 
-        candidates = @index.prefix_search(name, @nesting)
+        candidates = @index.prefix_search(name, @node_context.nesting)
         candidates.each do |entries|
           complete_name = T.must(entries.first).name
           @response_builder << build_entry_completion(
@@ -161,20 +161,21 @@ def constant_path_completion(name, range)
           T.must(namespace).join("::")
         end
 
-        namespace_entries = @index.resolve(aliased_namespace, @nesting)
+        nesting = @node_context.nesting
+        namespace_entries = @index.resolve(aliased_namespace, nesting)
         return unless namespace_entries
 
         real_namespace = @index.follow_aliased_namespace(T.must(namespace_entries.first).name)
 
         candidates = @index.prefix_search(
           "#{real_namespace}::#{incomplete_name}",
-          top_level_reference ? [] : @nesting,
+          top_level_reference ? [] : nesting,
         )
         candidates.each do |entries|
           # The only time we may have a private constant reference from outside of the namespace is if we're dealing
           # with ConstantPath and the entry name doesn't start with the current nesting
           first_entry = T.must(entries.first)
-          next if first_entry.private? && !first_entry.name.start_with?("#{@nesting}::")
+          next if first_entry.private? && !first_entry.name.start_with?("#{nesting}::")
 
           constant_name = first_entry.name.delete_prefix("#{real_namespace}::")
           full_name = aliased_namespace.empty? ? constant_name : "#{aliased_namespace}::#{constant_name}"
@@ -191,7 +192,7 @@ def constant_path_completion(name, range)
 
       sig { params(name: String, location: Prism::Location).void }
       def handle_instance_variable_completion(name, location)
-        @index.instance_variable_completion_candidates(name, @nesting.join("::")).each do |entry|
+        @index.instance_variable_completion_candidates(name, @node_context.nesting.join("::")).each do |entry|
           variable_name = entry.name
 
           @response_builder << Interface::CompletionItem.new(
@@ -257,7 +258,7 @@ def complete_require_relative(node)
 
       sig { params(node: Prism::CallNode, name: String).void }
       def complete_self_receiver_method(node, name)
-        receiver_entries = @index[@nesting.join("::")]
+        receiver_entries = @index[@node_context.nesting.join("::")]
         return unless receiver_entries
 
         receiver = T.must(receiver_entries.first)
@@ -351,13 +352,14 @@ def build_entry_completion(real_name, incomplete_name, range, entries, top_level
         #
         #  Foo::B # --> completion inserts `Bar` instead of `Foo::Bar`
         # end
-        unless @nesting.join("::").start_with?(incomplete_name)
-          @nesting.each do |namespace|
+        nesting = @node_context.nesting
+        unless nesting.join("::").start_with?(incomplete_name)
+          nesting.each do |namespace|
             prefix = "#{namespace}::"
             shortened_name = insertion_text.delete_prefix(prefix)
 
             # If a different entry exists for the shortened name, then there's a conflict and we should not shorten it
-            conflict_name = "#{@nesting.join("::")}::#{shortened_name}"
+            conflict_name = "#{nesting.join("::")}::#{shortened_name}"
             break if real_name != conflict_name && @index[conflict_name]
 
             insertion_text = shortened_name
@@ -399,8 +401,9 @@ def build_entry_completion(real_name, incomplete_name, range, entries, top_level
       # ```
       sig { params(entry_name: String).returns(T::Boolean) }
       def top_level?(entry_name)
-        @nesting.length.downto(0).each do |i|
-          prefix = T.must(@nesting[0...i]).join("::")
+        nesting = @node_context.nesting
+        nesting.length.downto(0).each do |i|
+          prefix = T.must(nesting[0...i]).join("::")
           full_name = prefix.empty? ? entry_name : "#{prefix}::#{entry_name}"
           next if full_name == entry_name
 

lib/ruby_lsp/listeners/definition.rb

@@ -14,17 +14,17 @@ class Definition
           response_builder: ResponseBuilders::CollectionResponseBuilder[Interface::Location],
           global_state: GlobalState,
           uri: URI::Generic,
-          nesting: T::Array[String],
+          node_context: NodeContext,
           dispatcher: Prism::Dispatcher,
           typechecker_enabled: T::Boolean,
         ).void
       end
-      def initialize(response_builder, global_state, uri, nesting, dispatcher, typechecker_enabled) # rubocop:disable Metrics/ParameterLists
+      def initialize(response_builder, global_state, uri, node_context, dispatcher, typechecker_enabled) # rubocop:disable Metrics/ParameterLists
         @response_builder = response_builder
         @global_state = global_state
         @index = T.let(global_state.index, RubyIndexer::Index)
         @uri = uri
-        @nesting = nesting
+        @node_context = node_context
         @typechecker_enabled = typechecker_enabled
 
         dispatcher.register(
@@ -114,7 +114,7 @@ def on_instance_variable_target_node_enter(node)
 
       sig { params(name: String).void }
       def handle_instance_variable_definition(name)
-        entries = @index.resolve_instance_variable(name, @nesting.join("::"))
+        entries = @index.resolve_instance_variable(name, @node_context.nesting.join("::"))
         return unless entries
 
         entries.each do |entry|
@@ -135,7 +135,7 @@ def handle_instance_variable_definition(name)
       sig { params(message: String, self_receiver: T::Boolean).void }
       def handle_method_definition(message, self_receiver)
         methods = if self_receiver
-          @index.resolve_method(message, @nesting.join("::"))
+          @index.resolve_method(message, @node_context.nesting.join("::"))
         else
           # If the method doesn't have a receiver, then we provide a few candidates to jump to
           # But we don't want to provide too many candidates, as it can be overwhelming
@@ -203,13 +203,13 @@ def handle_require_definition(node)
 
       sig { params(value: String).void }
       def find_in_index(value)
-        entries = @index.resolve(value, @nesting)
+        entries = @index.resolve(value, @node_context.nesting)
         return unless entries
 
         # We should only allow jumping to the definition of private constants if the constant is defined in the same
         # namespace as the reference
         first_entry = T.must(entries.first)
-        return if first_entry.private? && first_entry.name != "#{@nesting.join("::")}::#{value}"
+        return if first_entry.private? && first_entry.name != "#{@node_context.nesting.join("::")}::#{value}"
 
         entries.each do |entry|
           location = entry.location

lib/ruby_lsp/listeners/hover.rb

@@ -36,17 +36,17 @@ class Hover
           response_builder: ResponseBuilders::Hover,
           global_state: GlobalState,
           uri: URI::Generic,
-          nesting: T::Array[String],
+          node_context: NodeContext,
           dispatcher: Prism::Dispatcher,
           typechecker_enabled: T::Boolean,
         ).void
       end
-      def initialize(response_builder, global_state, uri, nesting, dispatcher, typechecker_enabled) # rubocop:disable Metrics/ParameterLists
+      def initialize(response_builder, global_state, uri, node_context, dispatcher, typechecker_enabled) # rubocop:disable Metrics/ParameterLists
         @response_builder = response_builder
         @global_state = global_state
         @index = T.let(global_state.index, RubyIndexer::Index)
         @path = T.let(uri.to_standardized_path, T.nilable(String))
-        @nesting = nesting
+        @node_context = node_context
         @typechecker_enabled = typechecker_enabled
 
         dispatcher.register(
@@ -105,7 +105,7 @@ def on_call_node_enter(node)
         message = node.message
         return unless message
 
-        methods = @index.resolve_method(message, @nesting.join("::"))
+        methods = @index.resolve_method(message, @node_context.nesting.join("::"))
         return unless methods
 
         categorized_markdown_from_index_entries(message, methods).each do |category, content|
@@ -147,7 +147,7 @@ def on_instance_variable_target_node_enter(node)
 
       sig { params(name: String).void }
       def handle_instance_variable_hover(name)
-        entries = @index.resolve_instance_variable(name, @nesting.join("::"))
+        entries = @index.resolve_instance_variable(name, @node_context.nesting.join("::"))
         return unless entries
 
         categorized_markdown_from_index_entries(name, entries).each do |category, content|
@@ -159,13 +159,13 @@ def handle_instance_variable_hover(name)
 
       sig { params(name: String, location: Prism::Location).void }
       def generate_hover(name, location)
-        entries = @index.resolve(name, @nesting)
+        entries = @index.resolve(name, @node_context.nesting)
         return unless entries
 
         # We should only show hover for private constants if the constant is defined in the same namespace as the
         # reference
         first_entry = T.must(entries.first)
-        return if first_entry.private? && first_entry.name != "#{@nesting.join("::")}::#{name}"
+        return if first_entry.private? && first_entry.name != "#{@node_context.nesting.join("::")}::#{name}"
 
         categorized_markdown_from_index_entries(name, entries).each do |category, content|
           @response_builder.push(content, category: category)

lib/ruby_lsp/listeners/signature_help.rb

@@ -11,17 +11,17 @@ class SignatureHelp
         params(
           response_builder: ResponseBuilders::SignatureHelp,
           global_state: GlobalState,
-          nesting: T::Array[String],
+          node_context: NodeContext,
           dispatcher: Prism::Dispatcher,
           typechecker_enabled: T::Boolean,
         ).void
       end
-      def initialize(response_builder, global_state, nesting, dispatcher, typechecker_enabled)
+      def initialize(response_builder, global_state, node_context, dispatcher, typechecker_enabled)
         @typechecker_enabled = typechecker_enabled
         @response_builder = response_builder
         @global_state = global_state
         @index = T.let(global_state.index, RubyIndexer::Index)
-        @nesting = nesting
+        @node_context = node_context
         dispatcher.register(self, :on_call_node_enter)
       end
 
@@ -33,7 +33,7 @@ def on_call_node_enter(node)
         message = node.message
         return unless message
 
-        methods = @index.resolve_method(message, @nesting.join("::"))
+        methods = @index.resolve_method(message, @node_context.nesting.join("::"))
         return unless methods
 
         target_method = methods.first

lib/ruby_lsp/node_context.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+module RubyLsp
+  # This class allows listeners to access contextual information about a node in the AST, such as its parent
+  # and its namespace nesting.
+  class NodeContext
+    extend T::Sig
+
+    sig { returns(T.nilable(Prism::Node)) }
+    attr_reader :node, :parent
+
+    sig { returns(T::Array[String]) }
+    attr_reader :nesting
+
+    sig { params(node: T.nilable(Prism::Node), parent: T.nilable(Prism::Node), nesting: T::Array[String]).void }
+    def initialize(node, parent, nesting)
+      @node = node
+      @parent = parent
+      @nesting = nesting
+    end
+  end
+end

lib/ruby_lsp/requests/code_action_resolve.rb

@@ -68,9 +68,11 @@ def refactor_variable
         extracted_source = T.must(@document.source[start_index...end_index])
 
         # Find the closest statements node, so that we place the refactor in a valid position
-        closest_statements, parent_statements = @document
+        node_context = @document
           .locate(@document.tree, start_index, node_types: [Prism::StatementsNode, Prism::BlockNode])
 
+        closest_statements = node_context.node
+        parent_statements = node_context.parent
         return Error::InvalidTargetRange if closest_statements.nil? || closest_statements.child_nodes.compact.empty?
 
         # Find the node with the end line closest to the requested position, so that we can place the refactor
@@ -162,10 +164,8 @@ def refactor_method
         extracted_source = T.must(@document.source[start_index...end_index])
 
         # Find the closest method declaration node, so that we place the refactor in a valid position
-        closest_def, _ = T.cast(
-          @document.locate(@document.tree, start_index, node_types: [Prism::DefNode]),
-          [T.nilable(Prism::DefNode), T.nilable(Prism::Node), T::Array[String]],
-        )
+        node_context = @document.locate(@document.tree, start_index, node_types: [Prism::DefNode])
+        closest_def = T.cast(node_context.node, Prism::DefNode)
         return Error::InvalidTargetRange if closest_def.nil?
 
         end_keyword_loc = closest_def.end_keyword_loc