find instance variable references with matched scopes (#3377)

* find instance variable references with matched scope

* handling top level references and refactoring

Author: mikeygough

lib/ruby_indexer/lib/ruby_indexer/reference_finder.rb

@@ -32,10 +32,14 @@ class InstanceVariableTarget < Target
       #: String
       attr_reader :name
 
-      #: (String name) -> void
-      def initialize(name)
+      #: Array[String]
+      attr_reader :owner_ancestors
+
+      #: (String name, Array[String] owner_ancestors) -> void
+      def initialize(name, owner_ancestors)
         super()
         @name = name
+        @owner_ancestors = owner_ancestors
       end
     end
 
@@ -322,7 +326,10 @@ def collect_constant_references(name, location)
     def collect_instance_variable_references(name, location, declaration)
       return unless @target.is_a?(InstanceVariableTarget) && name == @target.name
 
-      @references << Reference.new(name, location, declaration: declaration)
+      receiver_type = Index.actual_nesting(@stack, nil).join("::")
+      if @target.owner_ancestors.include?(receiver_type)
+        @references << Reference.new(name, location, declaration: declaration)
+      end
     end
   end
 end

lib/ruby_indexer/test/reference_finder_test.rb

@@ -216,22 +216,43 @@ def foo
       assert_equal(11, refs[2].location.start_line)
     end
 
-    def test_finds_instance_variable_read_references
-      refs = find_instance_variable_references("@foo", <<~RUBY)
+    def test_finds_instance_variable_references
+      refs = find_instance_variable_references("@name", ["Foo"], <<~RUBY)
         class Foo
-          def foo
-            @foo
+          def initialize
+            @name = "foo"
+          end
+          def name
+            @name
+          end
+          def name_capital
+            @name[0]
+          end
+        end
+
+        class Bar
+          def initialize
+            @name = "foo"
+          end
+          def name
+            @name
           end
         end
       RUBY
-      assert_equal(1, refs.size)
+      assert_equal(3, refs.size)
 
-      assert_equal("@foo", refs[0].name)
+      assert_equal("@name", refs[0].name)
       assert_equal(3, refs[0].location.start_line)
+
+      assert_equal("@name", refs[1].name)
+      assert_equal(6, refs[1].location.start_line)
+
+      assert_equal("@name", refs[2].name)
+      assert_equal(9, refs[2].location.start_line)
     end
 
     def test_finds_instance_variable_write_references
-      refs = find_instance_variable_references("@foo", <<~RUBY)
+      refs = find_instance_variable_references("@foo", ["Foo"], <<~RUBY)
         class Foo
           def write
             @foo = 1
@@ -252,26 +273,70 @@ def write
       assert_equal(7, refs[4].location.start_line)
     end
 
-    def test_finds_instance_variable_references_ignore_context
-      refs = find_instance_variable_references("@name", <<~RUBY)
-        class Foo
+    def test_finds_instance_variable_references_in_owner_ancestors
+      refs = find_instance_variable_references("@name", ["Foo", "Base", "Top", "Parent"], <<~RUBY)
+        module Base
+          def change_name(name)
+            @name = name
+          end
           def name
+            @name
+          end
+
+          module ::Top
+            def name
+              @name
+            end
+          end
+        end
+
+        class Parent
+          def initialize
+            @name = "parent"
+          end
+          def name_capital
+            @name[0]
+          end
+        end
+
+        class Foo < Parent
+          include Base
+          def initialize
             @name = "foo"
           end
+          def name
+            @name
+          end
         end
+
         class Bar
           def name
             @name = "bar"
           end
         end
       RUBY
-      assert_equal(2, refs.size)
+      assert_equal(7, refs.size)
 
       assert_equal("@name", refs[0].name)
       assert_equal(3, refs[0].location.start_line)
 
       assert_equal("@name", refs[1].name)
-      assert_equal(8, refs[1].location.start_line)
+      assert_equal(6, refs[1].location.start_line)
+
+      assert_equal("@name", refs[2].name)
+      assert_equal(11, refs[2].location.start_line)
+
+      assert_equal("@name", refs[3].name)
+      assert_equal(18, refs[3].location.start_line)
+
+      assert_equal("@name", refs[4].name)
+      assert_equal(21, refs[4].location.start_line)
+
+      assert_equal("@name", refs[5].name)
+      assert_equal(28, refs[5].location.start_line)
+
+      assert_equal("@name", refs[6].name)
+      assert_equal(31, refs[6].location.start_line)
     end
 
     def test_accounts_for_reopened_classes
@@ -310,8 +375,8 @@ def find_method_references(method_name, source)
       find_references(target, source)
     end
 
-    def find_instance_variable_references(instance_variable_name, source)
-      target = ReferenceFinder::InstanceVariableTarget.new(instance_variable_name)
+    def find_instance_variable_references(instance_variable_name, owner_ancestors, source)
+      target = ReferenceFinder::InstanceVariableTarget.new(instance_variable_name, owner_ancestors)
       find_references(target, source)
     end
 

lib/ruby_lsp/listeners/hover.rb

@@ -7,6 +7,7 @@ class Hover
       include Requests::Support::Common
 
       ALLOWED_TARGETS = [
+        Prism::BreakNode,
         Prism::CallNode,
         Prism::ConstantReadNode,
         Prism::ConstantWriteNode,
@@ -54,6 +55,7 @@ def initialize(response_builder, global_state, uri, node_context, dispatcher, so
 
         dispatcher.register(
           self,
+          :on_break_node_enter,
           :on_constant_read_node_enter,
           :on_constant_write_node_enter,
           :on_constant_path_node_enter,
@@ -244,6 +246,11 @@ def on_class_variable_write_node_enter(node)
         handle_class_variable_hover(node.name.to_s)
       end
 
+      #: (Prism::BreakNode node) -> void
+      def on_break_node_enter(node)
+        handle_keyword_documentation(node.keyword)
+      end
+
       private
 
       #: ((Prism::InterpolatedStringNode | Prism::StringNode) node) -> void

lib/ruby_lsp/requests/references.rb

@@ -101,7 +101,11 @@ def create_reference_target(target_node, node_context)
           Prism::InstanceVariableReadNode,
           Prism::InstanceVariableTargetNode,
           Prism::InstanceVariableWriteNode
-          RubyIndexer::ReferenceFinder::InstanceVariableTarget.new(target_node.name.to_s)
+          receiver_type = @global_state.type_inferrer.infer_receiver_type(node_context)
+          return unless receiver_type
+
+          ancestors = @global_state.index.linearized_ancestors_of(receiver_type.name)
+          RubyIndexer::ReferenceFinder::InstanceVariableTarget.new(target_node.name.to_s, ancestors)
         when Prism::CallNode, Prism::DefNode
           RubyIndexer::ReferenceFinder::MethodTarget.new(target_node.name.to_s)
         end

lib/ruby_lsp/static_docs.rb

@@ -15,5 +15,7 @@ module RubyLsp
   # A map of keyword => short documentation to be displayed on hover or completion
   KEYWORD_DOCS = {
     "yield" => "Invokes the passed block with the given arguments",
+    "case" => "Starts a case expression for pattern matching or multiple condition checking",
+    "break" => "Terminates the execution of a block, loop, or method",
   }.freeze #: Hash[String, String]
 end

static_docs/break.md

@@ -0,0 +1,101 @@
+# Break
+
+In Ruby, the `break` keyword is used to exit a loop or block prematurely. Unlike `next` which skips to the next iteration, `break` terminates the loop entirely and continues with the code after the loop.
+
+```ruby
+# Basic break usage in a loop
+5.times do |i|
+  break if i == 3
+
+  puts i
+end
+# Output:
+# 0
+# 1
+# 2
+```
+
+The `break` statement can be used with any of Ruby's iteration methods or loops.
+
+```ruby
+# Using break with different types of loops
+array = [1, 2, 3, 4, 5]
+
+# With each
+array.each do |num|
+  break if num > 3
+
+  puts "Number: #{num}"
+end
+# Output:
+# Number: 1
+# Number: 2
+# Number: 3
+
+# With infinite loop
+i = 0
+loop do
+  i += 1
+  break if i >= 5
+
+  puts "Count: #{i}"
+end
+```
+
+## Break with a Value
+
+When used inside a block, `break` can return a value that becomes the result of the method call.
+
+```ruby
+# Using break with a return value
+result = [1, 2, 3, 4, 5].map do |num|
+  break "Too large!" if num > 3
+
+  num * 2
+end
+puts result # Output: "Too large!"
+
+# Break in find method
+number = (1..100).find do |n|
+  break n if n > 50 && n.even?
+end
+puts number # Output: 52
+```
+
+## Break in Nested Loops
+
+When using `break` in nested loops, it only exits the innermost loop unless explicitly used with a label (not commonly used in Ruby).
+
+```ruby
+# Break in nested iteration
+result = (1..3).each do |i|
+  puts "Outer loop: #{i}"
+
+  (1..3).each do |j|
+    break if j == 2
+
+    puts "  Inner loop: #{j}"
+  end
+end
+# Output:
+# Outer loop: 1
+#   Inner loop: 1
+# Outer loop: 2
+#   Inner loop: 1
+# Outer loop: 3
+#   Inner loop: 1
+
+# Breaking from nested loops using a flag
+found = false
+(1..3).each do |i|
+  (1..3).each do |j|
+    if i * j == 4
+      found = true
+      break
+    end
+  end
+  break if found
+end
+```
+
+The `break` keyword is essential for controlling loop execution and implementing early exit conditions. It's particularly useful when you've found what you're looking for and don't need to continue iterating.