From 8c6754e7b41a1ec11e933e9220f585687c6f2008 Mon Sep 17 00:00:00 2001
From: Mohith26 <109003762+Mohith26@users.noreply.github.com>
Date: Wed, 4 Nov 2026 08:12:38 -0500
Subject: [PATCH] Add references, rename and definition for local variables

Resolve local variables per scope with a Prism visitor that uses the
depth Prism assigns to each local variable node. This covers reads,
writes, parameters, block locals, pattern matching, regexp named
captures and hash/keyword shorthands, and only looks at the current
document since locals can't be referenced from other files.
---
 jekyll/index.markdown                         |  17 +-
 lib/ruby_lsp/internal.rb                      |   1 +
 lib/ruby_lsp/requests/definition.rb           |  19 +
 lib/ruby_lsp/requests/prepare_rename.rb       |  13 +
 lib/ruby_lsp/requests/references.rb           |  23 +
 lib/ruby_lsp/requests/rename.rb               |  57 +++
 .../requests/support/local_variable_finder.rb | 437 ++++++++++++++++++
 test/requests/definition_expectations_test.rb |  55 ++-
 .../prepare_rename_expectations_test.rb       |  27 ++
 test/requests/references_test.rb              |  87 ++++
 test/requests/rename_test.rb                  | 177 +++++++
 .../support/local_variable_finder_test.rb     | 349 ++++++++++++++
 12 files changed, 1256 insertions(+), 6 deletions(-)
 create mode 100644 lib/ruby_lsp/requests/support/local_variable_finder.rb
 create mode 100644 test/requests/support/local_variable_finder_test.rb

diff --git a/jekyll/index.markdown b/jekyll/index.markdown
index 5c8a57fc39..882d238745 100644
--- a/jekyll/index.markdown
+++ b/jekyll/index.markdown
@@ -133,7 +133,8 @@ Sorry, your browser doesn't support embedded videos. This video demonstrates the
 ### Go-to-Definition
 
 Go-to-definition allows users to navigate to the target constant or method's definition,
-whether they're defined in your project or its dependencies.
+whether they're defined in your project or its dependencies. For local variables, it jumps to the parameter or the first
+assignment that declares the variable in the current scope.
 
 In VS Code this feature can be triggered by one of the following methods:
 
@@ -479,7 +480,14 @@ Rename allows developers to rename all occurrences of the entity under the curso
 renaming can be triggered by right clicking the entity to rename or by pressing F2 on it. You can also preview the
 edits that will be applied by pressing CTRL/CMD + Enter after typing the desired new name.
 
-Rename is currently only supported for constants, module names and class names.
+Rename is currently supported for constants, module names, class names and local variables (including method and
+block parameters).
+
+Local variables are renamed only within the scope that declares them, so a variable with the same name in another method
+or block is left untouched. When the variable is used as a shorthand hash value or keyword argument (`{ name: }` or
+`foo(name:)`), the key is kept and only the value is renamed (`{ name: new_name }`). Renaming is rejected if the new name
+is already used by another local or by a method call in the same scope, since that would change the program's behavior.
+Keyword parameters can't be renamed because callers refer to them by name.
 
 <video src="images/rename.mp4" width="100%" controls>
 Sorry, your browser doesn't support embedded videos. This video shows renaming a symbol across the project.
@@ -487,8 +495,9 @@ Sorry, your browser doesn't support embedded videos. This video shows renaming a
 
 ### Find references
 
-The find references request allows users to both see a list of references or jump to reference locations. Note that
-only constants are currently supported, but support for methods, instance variables and local variables is planned.
+The find references request allows users to both see a list of references or jump to reference locations. It supports
+constants, methods, instance variables and local variables. Local variable references are resolved from the current file
+only, taking scopes into account, so a local with the same name in another method or block is not included.
 
 <video src="images/references.mp4" width="100%" controls>
 Sorry, your browser doesn't support embedded videos. This video demonstrates finding references to a constant.
diff --git a/lib/ruby_lsp/internal.rb b/lib/ruby_lsp/internal.rb
index 1083c51450..83a398ee8c 100644
--- a/lib/ruby_lsp/internal.rb
+++ b/lib/ruby_lsp/internal.rb
@@ -62,6 +62,7 @@
 require "ruby_lsp/requests/support/annotation"
 require "ruby_lsp/requests/support/sorbet"
 require "ruby_lsp/requests/support/common"
+require "ruby_lsp/requests/support/local_variable_finder"
 require "ruby_lsp/requests/support/formatter"
 require "ruby_lsp/requests/support/rubocop_runner"
 require "ruby_lsp/requests/support/rubocop_formatter"
diff --git a/lib/ruby_lsp/requests/definition.rb b/lib/ruby_lsp/requests/definition.rb
index 53ad3c29ba..e74985aa01 100644
--- a/lib/ruby_lsp/requests/definition.rb
+++ b/lib/ruby_lsp/requests/definition.rb
@@ -19,6 +19,25 @@ def initialize(document, global_state, position, dispatcher, sorbet_level)
         char_position, _ = document.find_index_by_position(position)
         delegate_request_if_needed!(global_state, document, char_position)
 
+        # Sorbet already handles local variables in typed files
+        local_variable = unless sorbet_level.true_or_higher?
+          Support::LocalVariableFinder.new(document.ast).variable_at(char_position, document.code_units_cache)
+        end
+
+        if local_variable
+          declaration = local_variable.first.declaration
+
+          if declaration
+            @response_builder << Interface::Location.new(
+              uri: document.uri.to_s,
+              range: Support::LocalVariableFinder.range_for(declaration.location, document.code_units_cache),
+            )
+          end
+
+          @target = nil #: Prism::Node?
+          return
+        end
+
         node_context = RubyDocument.locate(
           document.ast,
           char_position,
diff --git a/lib/ruby_lsp/requests/prepare_rename.rb b/lib/ruby_lsp/requests/prepare_rename.rb
index 8b8cc278cf..ec9d1aac86 100644
--- a/lib/ruby_lsp/requests/prepare_rename.rb
+++ b/lib/ruby_lsp/requests/prepare_rename.rb
@@ -21,6 +21,19 @@ def initialize(document, position)
       def perform
         char_position, _ = @document.find_index_by_position(@position)
 
+        local_variable = Support::LocalVariableFinder.new(@document.ast).variable_at(
+          char_position,
+          @document.code_units_cache,
+        )
+
+        if local_variable
+          variable, occurrence = local_variable
+          # Renaming a keyword parameter would break every caller passing it by name
+          return if variable.occurrences.any? { |o| o.kind == :keyword_parameter }
+
+          return Support::LocalVariableFinder.range_for(occurrence.location, @document.code_units_cache)
+        end
+
         node_context = RubyDocument.locate(
           @document.ast,
           char_position,
diff --git a/lib/ruby_lsp/requests/references.rb b/lib/ruby_lsp/requests/references.rb
index f400224a47..5b9482c9ca 100644
--- a/lib/ruby_lsp/requests/references.rb
+++ b/lib/ruby_lsp/requests/references.rb
@@ -25,6 +25,13 @@ def perform
         position = @params[:position]
         char_position, _ = @document.find_index_by_position(position)
 
+        # Local variables can only be referenced in the current document, so there's no need to search the workspace
+        local_variable = Support::LocalVariableFinder.new(@document.ast).variable_at(
+          char_position,
+          @document.code_units_cache,
+        )
+        return collect_local_variable_references(local_variable.first) if local_variable
+
         node_context = RubyDocument.locate(
           @document.ast,
           char_position,
@@ -81,6 +88,22 @@ def perform
 
       private
 
+      #: (Support::LocalVariableFinder::Variable variable) -> Array[Interface::Location]
+      def collect_local_variable_references(variable)
+        include_declaration = @params.dig(:context, :includeDeclaration) != false
+        declaration = variable.declaration
+        code_units_cache = @document.code_units_cache
+
+        variable.occurrences.filter_map do |occurrence|
+          next if !include_declaration && occurrence.equal?(declaration)
+
+          Interface::Location.new(
+            uri: @document.uri.to_s,
+            range: Support::LocalVariableFinder.range_for(occurrence.location, code_units_cache),
+          )
+        end
+      end
+
       #: ((Prism::ConstantReadNode | Prism::ConstantPathNode | Prism::ConstantPathTargetNode | Prism::InstanceVariableAndWriteNode | Prism::InstanceVariableOperatorWriteNode | Prism::InstanceVariableOrWriteNode | Prism::InstanceVariableReadNode | Prism::InstanceVariableTargetNode | Prism::InstanceVariableWriteNode | Prism::CallNode | Prism::DefNode) target_node, NodeContext node_context) -> RubyIndexer::ReferenceFinder::Target?
       def create_reference_target(target_node, node_context)
         case target_node
diff --git a/lib/ruby_lsp/requests/rename.rb b/lib/ruby_lsp/requests/rename.rb
index a8e8276410..375940c3c7 100644
--- a/lib/ruby_lsp/requests/rename.rb
+++ b/lib/ruby_lsp/requests/rename.rb
@@ -33,6 +33,10 @@ def initialize(global_state, store, document, params)
       def perform
         char_position, _ = @document.find_index_by_position(@position)
 
+        local_variable_finder = Support::LocalVariableFinder.new(@document.ast)
+        local_variable = local_variable_finder.variable_at(char_position, @document.code_units_cache)
+        return rename_local_variable(local_variable_finder, local_variable.first) if local_variable
+
         node_context = RubyDocument.locate(
           @document.ast,
           char_position,
@@ -89,6 +93,59 @@ def perform
 
       private
 
+      #: (Support::LocalVariableFinder finder, Support::LocalVariableFinder::Variable variable) -> Interface::WorkspaceEdit
+      def rename_local_variable(finder, variable)
+        if variable.occurrences.any? { |occurrence| occurrence.kind == :keyword_parameter }
+          raise InvalidNameError, "Keyword parameters can't be renamed because callers refer to them by name"
+        end
+
+        unless valid_local_variable_name?(@new_name)
+          raise InvalidNameError, "`#{@new_name}` is not a valid local variable name"
+        end
+
+        old_name = variable.name.to_s
+        return Interface::WorkspaceEdit.new(changes: {}) if old_name == @new_name
+
+        if finder.name_in_use?(variable, @new_name.to_sym)
+          raise InvalidNameError, "The new name is already in use by a local variable or method call in the same scope"
+        end
+
+        code_units_cache = @document.code_units_cache
+        edits = variable.occurrences.map do |occurrence|
+          location = occurrence.location
+
+          if occurrence.kind == :shorthand
+            # `{ name: }` has to become `{ name: new_name }`, otherwise the key would change too
+            key_location = location.copy(length: location.length + 1)
+            Interface::TextEdit.new(
+              range: Support::LocalVariableFinder.range_for(key_location, code_units_cache),
+              new_text: "#{old_name}: #{@new_name}",
+            )
+          else
+            Interface::TextEdit.new(
+              range: Support::LocalVariableFinder.range_for(location, code_units_cache),
+              new_text: @new_name,
+            )
+          end
+        end
+
+        Interface::WorkspaceEdit.new(changes: { @document.uri.to_s => edits })
+      end
+
+      #: (String name) -> bool
+      def valid_local_variable_name?(name)
+        result = Prism.parse("#{name} = nil")
+        return false unless result.success?
+
+        statements = result.value.statements.body
+        return false unless statements.length == 1
+
+        node = statements.first
+        return false unless node.is_a?(Prism::LocalVariableWriteNode)
+
+        node.name.to_s == name
+      end
+
       #: (String fully_qualified_name, Array[(Interface::RenameFile | Interface::TextDocumentEdit)] document_changes) -> void
       def collect_file_renames(fully_qualified_name, document_changes)
         # Check if the declarations of the symbol being renamed match the file name. In case they do, we automatically
diff --git a/lib/ruby_lsp/requests/support/local_variable_finder.rb b/lib/ruby_lsp/requests/support/local_variable_finder.rb
new file mode 100644
index 0000000000..668ff3ab0d
--- /dev/null
+++ b/lib/ruby_lsp/requests/support/local_variable_finder.rb
@@ -0,0 +1,437 @@
+# typed: strict
+# frozen_string_literal: true
+
+module RubyLsp
+  module Requests
+    module Support
+      # Resolves local variables in a single document. Every read, write, target and parameter is grouped by the scope
+      # that declares it, using the `depth` Prism assigns to each local variable node. This means that two locals with the
+      # same name in different methods or blocks are kept apart, while a block that reads a local from its enclosing
+      # method is correctly linked to it.
+      #
+      # Local variables can't be referenced from other files, so this never needs the index or a workspace scan.
+      class LocalVariableFinder < Prism::Visitor
+        # A single place where a local variable appears in the source
+        class Occurrence
+          # One of `:read`, `:write`, `:parameter`, `:keyword_parameter`, `:shorthand` or `:regexp_capture`.
+          # `:shorthand` is a value omitted from a hash or keyword argument (`{ name: }`) or from a hash pattern
+          # (`in { name: }`), where the name also acts as the key
+          #: Symbol
+          attr_reader :kind
+
+          # The location of the variable's name only
+          #: Prism::Location
+          attr_reader :location
+
+          #: (Prism::Location location, Symbol kind, write: bool) -> void
+          def initialize(location, kind, write:)
+            @location = location
+            @kind = kind
+            @write = write
+          end
+
+          # Whether this occurrence assigns the variable, which includes parameters
+          #: -> bool
+          def write?
+            @write
+          end
+        end
+
+        # A local variable and all of the places where it appears, in source order
+        class Variable
+          #: Symbol
+          attr_reader :name
+
+          #: Prism::Node
+          attr_reader :scope
+
+          #: Array[Occurrence]
+          attr_reader :occurrences
+
+          #: (Symbol name, Prism::Node scope) -> void
+          def initialize(name, scope)
+            @name = name
+            @scope = scope
+            @occurrences = [] #: Array[Occurrence]
+          end
+
+          # The parameter or first assignment that introduced the variable
+          #: -> Occurrence?
+          def declaration
+            @occurrences.find(&:write?)
+          end
+        end
+
+        class << self
+          # Builds an LSP range for a location, accounting for the encoding negotiated with the client so that names after
+          # multibyte characters are still placed correctly
+          #: (Prism::Location location, (^(Integer arg0) -> Integer | Prism::CodeUnitsCache) code_units_cache) -> Interface::Range
+          def range_for(location, code_units_cache)
+            Interface::Range.new(
+              start: Interface::Position.new(
+                line: location.start_line - 1,
+                character: location.cached_start_code_units_column(code_units_cache),
+              ),
+              end: Interface::Position.new(
+                line: location.end_line - 1,
+                character: location.cached_end_code_units_column(code_units_cache),
+              ),
+            )
+          end
+        end
+
+        HARD_SCOPES = [
+          Prism::ProgramNode,
+          Prism::ClassNode,
+          Prism::ModuleNode,
+          Prism::SingletonClassNode,
+          Prism::DefNode,
+        ].freeze #: Array[singleton(Prism::Node)]
+
+        #: (Prism::Node ast) -> void
+        def initialize(ast)
+          super()
+          @scopes = [] #: Array[Prism::Node]
+          @variables = {}.compare_by_identity #: Hash[Prism::Node, Hash[Symbol, Variable]]
+          # The enclosing scope of every block and lambda, so we can walk up to the scopes they can see
+          @parent_scopes = {}.compare_by_identity #: Hash[Prism::Node, Prism::Node]
+          # Blocks and lambdas nested directly in each scope, without crossing a method or class boundary
+          @child_scopes = {}.compare_by_identity #: Hash[Prism::Node, Array[Prism::Node]]
+          # Names of method calls without receiver or arguments (e.g.: `foo`), per scope. A local with the same name would
+          # shadow them
+          @variable_calls = {}.compare_by_identity #: Hash[Prism::Node, Array[Symbol]]
+          ast.accept(self)
+
+          @variables.each_value do |variables|
+            variables.each_value { |variable| variable.occurrences.sort_by! { |o| o.location.start_offset } }
+          end
+        end
+
+        # Finds the local variable whose name covers the given position. A position right after the end of the name also
+        # counts, so that requests work when the cursor is placed at the end of the identifier
+        #: (Integer char_position, (^(Integer arg0) -> Integer | Prism::CodeUnitsCache) code_units_cache) -> [Variable, Occurrence]?
+        def variable_at(char_position, code_units_cache)
+          adjacent = nil #: [Variable, Occurrence]?
+
+          @variables.each_value do |variables|
+            variables.each_value do |variable|
+              variable.occurrences.each do |occurrence|
+                location = occurrence.location
+                start_offset = location.cached_start_code_units_offset(code_units_cache)
+                end_offset = location.cached_end_code_units_offset(code_units_cache)
+
+                return [variable, occurrence] if start_offset <= char_position && char_position < end_offset
+
+                adjacent ||= [variable, occurrence] if char_position == end_offset
+              end
+            end
+          end
+
+          adjacent
+        end
+
+        # Returns true if renaming `variable` to `new_name` would make it collide with another local or with a method
+        # call that would then be shadowed
+        #: (Variable variable, Symbol new_name) -> bool
+        def name_in_use?(variable, new_name)
+          visible = scopes_visible_from(variable.scope)
+
+          visible.any? do |scope|
+            locals_of(scope).include?(new_name) || @variable_calls[scope]&.include?(new_name)
+          end
+        end
+
+        # @override
+        #: (Prism::ProgramNode node) -> void
+        def visit_program_node(node)
+          with_scope(node) { super }
+        end
+
+        # @override
+        #: (Prism::ClassNode node) -> void
+        def visit_class_node(node)
+          # The constant path and the superclass are evaluated in the enclosing scope
+          visit(node.constant_path)
+          visit(node.superclass)
+          with_scope(node) { visit(node.body) }
+        end
+
+        # @override
+        #: (Prism::ModuleNode node) -> void
+        def visit_module_node(node)
+          visit(node.constant_path)
+          with_scope(node) { visit(node.body) }
+        end
+
+        # @override
+        #: (Prism::SingletonClassNode node) -> void
+        def visit_singleton_class_node(node)
+          visit(node.expression)
+          with_scope(node) { visit(node.body) }
+        end
+
+        # @override
+        #: (Prism::DefNode node) -> void
+        def visit_def_node(node)
+          # The receiver in `def foo.bar` is evaluated in the enclosing scope
+          visit(node.receiver)
+          with_scope(node) do
+            visit(node.parameters)
+            visit(node.body)
+          end
+        end
+
+        # @override
+        #: (Prism::BlockNode node) -> void
+        def visit_block_node(node)
+          with_scope(node) { super }
+        end
+
+        # @override
+        #: (Prism::LambdaNode node) -> void
+        def visit_lambda_node(node)
+          with_scope(node) { super }
+        end
+
+        # @override
+        #: (Prism::LocalVariableReadNode node) -> void
+        def visit_local_variable_read_node(node)
+          add(node.name, node.depth, node.location, :read)
+        end
+
+        # @override
+        #: (Prism::LocalVariableTargetNode node) -> void
+        def visit_local_variable_target_node(node)
+          add(node.name, node.depth, node.location, :write)
+        end
+
+        # @override
+        #: (Prism::LocalVariableWriteNode node) -> void
+        def visit_local_variable_write_node(node)
+          add(node.name, node.depth, node.name_loc, :write)
+          super
+        end
+
+        # @override
+        #: (Prism::LocalVariableAndWriteNode node) -> void
+        def visit_local_variable_and_write_node(node)
+          add(node.name, node.depth, node.name_loc, :write)
+          super
+        end
+
+        # @override
+        #: (Prism::LocalVariableOrWriteNode node) -> void
+        def visit_local_variable_or_write_node(node)
+          add(node.name, node.depth, node.name_loc, :write)
+          super
+        end
+
+        # @override
+        #: (Prism::LocalVariableOperatorWriteNode node) -> void
+        def visit_local_variable_operator_write_node(node)
+          add(node.name, node.depth, node.name_loc, :write)
+          super
+        end
+
+        # @override
+        #: (Prism::RequiredParameterNode node) -> void
+        def visit_required_parameter_node(node)
+          add(node.name, 0, node.location, :parameter)
+        end
+
+        # @override
+        #: (Prism::OptionalParameterNode node) -> void
+        def visit_optional_parameter_node(node)
+          add(node.name, 0, node.name_loc, :parameter)
+          super
+        end
+
+        # @override
+        #: (Prism::RestParameterNode node) -> void
+        def visit_rest_parameter_node(node)
+          add_named_parameter(node.name, node.name_loc, :parameter)
+        end
+
+        # @override
+        #: (Prism::KeywordRestParameterNode node) -> void
+        def visit_keyword_rest_parameter_node(node)
+          add_named_parameter(node.name, node.name_loc, :parameter)
+        end
+
+        # @override
+        #: (Prism::BlockParameterNode node) -> void
+        def visit_block_parameter_node(node)
+          add_named_parameter(node.name, node.name_loc, :parameter)
+        end
+
+        # @override
+        #: (Prism::RequiredKeywordParameterNode node) -> void
+        def visit_required_keyword_parameter_node(node)
+          # The name location includes the trailing colon
+          add(node.name, 0, name_only(node.name_loc, node.name), :keyword_parameter)
+        end
+
+        # @override
+        #: (Prism::OptionalKeywordParameterNode node) -> void
+        def visit_optional_keyword_parameter_node(node)
+          add(node.name, 0, name_only(node.name_loc, node.name), :keyword_parameter)
+          super
+        end
+
+        # @override
+        #: (Prism::BlockLocalVariableNode node) -> void
+        def visit_block_local_variable_node(node)
+          add(node.name, 0, node.location, :write)
+        end
+
+        # @override
+        #: (Prism::ImplicitNode node) -> void
+        def visit_implicit_node(node)
+          value = node.value
+
+          case value
+          when Prism::LocalVariableReadNode
+            # In `{ name: }` the location of the value includes the colon
+            add(value.name, value.depth, name_only(value.location, value.name), :shorthand, write: false)
+          when Prism::LocalVariableTargetNode
+            # `in { name: }` assigns the matched value to `name`
+            add(value.name, value.depth, name_only(value.location, value.name), :shorthand, write: true)
+          else
+            super
+          end
+        end
+
+        # @override
+        #: (Prism::MatchWriteNode node) -> void
+        def visit_match_write_node(node)
+          # Named captures in `/(?<year>\d+)/ =~ string` define locals. The target nodes span the whole regexp, so we
+          # find the location of the name inside of the capture group instead
+          regexp = node.call.receiver
+
+          node.targets.each do |target|
+            next unless target.is_a?(Prism::LocalVariableTargetNode)
+
+            locations = regexp.is_a?(Prism::RegularExpressionNode) ? capture_name_locations(regexp, target.name) : []
+            # Even if we can't point at the name, we still need to register the local in its scope
+            register_name(target.name, target.depth)
+            locations.each { |location| add(target.name, target.depth, location, :regexp_capture) }
+          end
+
+          visit(node.call)
+        end
+
+        # @override
+        #: (Prism::CallNode node) -> void
+        def visit_call_node(node)
+          scope = @scopes.last
+          (@variable_calls[scope] ||= []) << node.name if scope && node.variable_call?
+          super
+        end
+
+        private
+
+        #: (Prism::Node scope) { -> void } -> void
+        def with_scope(scope, &block)
+          parent = @scopes.last
+
+          if parent && !HARD_SCOPES.include?(scope.class)
+            @parent_scopes[scope] = parent
+            (@child_scopes[parent] ||= []) << scope
+          end
+
+          @scopes << scope
+          block.call
+        ensure
+          @scopes.pop
+        end
+
+        #: (Symbol name, Integer depth, Prism::Location location, Symbol kind, ?write: bool) -> void
+        def add(name, depth, location, kind, write: kind != :read)
+          variable = register_name(name, depth)
+          variable&.occurrences&.<<(Occurrence.new(location, kind, write: write))
+        end
+
+        #: (Symbol? name, Prism::Location? location, Symbol kind) -> void
+        def add_named_parameter(name, location, kind)
+          # Anonymous parameters such as `*`, `**` and `&` don't define a local we can reference
+          return unless name && location
+
+          add(name, 0, location, kind)
+        end
+
+        #: (Symbol name, Integer depth) -> Variable?
+        def register_name(name, depth)
+          # Numbered parameters (`_1`) can't be renamed or declared
+          return if name.match?(/\A_[1-9]\z/)
+
+          scope = @scopes[-1 - depth]
+          return unless scope
+
+          variables = (@variables[scope] ||= {})
+          variables[name] ||= Variable.new(name, scope)
+        end
+
+        #: (Prism::Location location, Symbol name) -> Prism::Location
+        def name_only(location, name)
+          location.copy(length: name.to_s.bytesize)
+        end
+
+        # A regexp may repeat the same group name (e.g.: `/(?<n>a)|(?<n>b)/`), so we return all of them
+        #: (Prism::RegularExpressionNode regexp, Symbol name) -> Array[Prism::Location]
+        def capture_name_locations(regexp, name)
+          content_location = regexp.content_loc
+          content = content_location.slice
+          name_length = name.to_s.bytesize
+          locations = [] #: Array[Prism::Location]
+
+          ["(?<#{name}>", "(?'#{name}'"].each do |group|
+            search_from = 0
+
+            loop do
+              index = content.index(group, search_from)
+              break unless index
+
+              start_offset = content_location.start_offset + content[0, index + 3].to_s.bytesize
+              locations << content_location.copy(start_offset: start_offset, length: name_length)
+              search_from = index + group.length
+            end
+          end
+
+          locations
+        end
+
+        # The declaring scope, the blocks it encloses and the blocks enclosing it all share the same locals
+        #: (Prism::Node scope) -> Array[Prism::Node]
+        def scopes_visible_from(scope)
+          visible = [] #: Array[Prism::Node]
+          pending = [scope]
+
+          until pending.empty?
+            current = pending.pop #: as !nil
+            visible << current
+            pending.concat(@child_scopes[current] || [])
+          end
+
+          parent = @parent_scopes[scope] #: Prism::Node?
+          while parent
+            visible << parent
+            parent = @parent_scopes[parent]
+          end
+
+          visible
+        end
+
+        #: (Prism::Node scope) -> Array[Symbol]
+        def locals_of(scope)
+          case scope
+          when Prism::ProgramNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode, Prism::DefNode,
+            Prism::BlockNode, Prism::LambdaNode
+            scope.locals
+          else
+            []
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/test/requests/definition_expectations_test.rb b/test/requests/definition_expectations_test.rb
index 5845300aac..335dd027ab 100644
--- a/test/requests/definition_expectations_test.rb
+++ b/test/requests/definition_expectations_test.rb
@@ -136,6 +136,55 @@ class Baz
     end
   end
 
+  def test_definition_for_local_variables
+    source = <<~RUBY
+      def foo(items)
+        total = 0
+        items.each { |item| total += item }
+        total
+      end
+    RUBY
+
+    with_server(source, stub_no_typechecker: true) do |server, uri|
+      server.process_message(
+        id: 1,
+        method: "textDocument/definition",
+        params: { textDocument: { uri: uri }, position: { line: 3, character: 2 } },
+      )
+      location = server.pop_response.response.first
+      assert_equal(uri.to_s, location.uri)
+      assert_equal({ line: 1, character: 2 }, location.range.start.to_hash)
+      assert_equal({ line: 1, character: 7 }, location.range.end.to_hash)
+
+      # Parameters are the declaration of the local
+      server.process_message(
+        id: 2,
+        method: "textDocument/definition",
+        params: { textDocument: { uri: uri }, position: { line: 2, character: 35 } },
+      )
+      location = server.pop_response.response.first
+      assert_equal({ line: 2, character: 16 }, location.range.start.to_hash)
+      assert_equal({ line: 2, character: 20 }, location.range.end.to_hash)
+    end
+  end
+
+  def test_definition_for_local_variables_defers_to_sorbet_in_typed_files
+    source = <<~RUBY
+      # typed: true
+      value = 1
+      value
+    RUBY
+
+    with_server(source) do |server, uri|
+      server.process_message(
+        id: 1,
+        method: "textDocument/definition",
+        params: { textDocument: { uri: uri }, position: { line: 2, character: 0 } },
+      )
+      assert_empty(server.pop_response.response)
+    end
+  end
+
   def test_multibyte_character_precision
     source = <<~RUBY
       module Fほげ
@@ -1374,13 +1423,15 @@ def with_foo(foo)
     RUBY
 
     with_server(source) do |server, uri|
-      # On the `foo` receiver, we should not show any results
+      # On the `foo` receiver, we should jump to the parameter and not to any methods
       server.process_message(
         id: 1,
         method: "textDocument/definition",
         params: { textDocument: { uri: uri }, position: { character: 19, line: 8 } },
       )
-      assert_empty(server.pop_response.response)
+      response = server.pop_response.response
+      assert_equal(1, response.length)
+      assert_equal({ line: 7, character: 15 }, response.first.range.start.to_hash)
 
       # On `message`, we should
       server.process_message(
diff --git a/test/requests/prepare_rename_expectations_test.rb b/test/requests/prepare_rename_expectations_test.rb
index ae690a209f..c8b197bcce 100644
--- a/test/requests/prepare_rename_expectations_test.rb
+++ b/test/requests/prepare_rename_expectations_test.rb
@@ -14,6 +14,33 @@ def run_expectations(source)
     RubyLsp::Requests::PrepareRename.new(document, position).perform
   end
 
+  def test_prepare_rename_for_local_variables
+    source = <<~RUBY
+      def foo(name, label:)
+        value = name
+        value
+      end
+    RUBY
+
+    document = RubyLsp::RubyDocument.new(
+      source: source,
+      version: 1,
+      uri: URI("file:///fake.rb"),
+      global_state: @global_state,
+    )
+
+    range = RubyLsp::Requests::PrepareRename.new(document, { line: 2, character: 3 }).perform #: as !nil
+    assert_equal({ line: 2, character: 2 }, range.start.to_hash)
+    assert_equal({ line: 2, character: 7 }, range.end.to_hash)
+
+    range = RubyLsp::Requests::PrepareRename.new(document, { line: 0, character: 9 }).perform #: as !nil
+    assert_equal({ line: 0, character: 8 }, range.start.to_hash)
+    assert_equal({ line: 0, character: 12 }, range.end.to_hash)
+
+    # Keyword parameters are part of the method's signature, so they can't be renamed locally
+    assert_nil(RubyLsp::Requests::PrepareRename.new(document, { line: 0, character: 15 }).perform)
+  end
+
   private
 
   def default_position
diff --git a/test/requests/references_test.rb b/test/requests/references_test.rb
index 9297db34ef..7c26b8d01f 100644
--- a/test/requests/references_test.rb
+++ b/test/requests/references_test.rb
@@ -12,8 +12,95 @@ def test_finds_constant_references
     assert_equal([0, 3], refs)
   end
 
+  def test_finds_local_variable_references_in_the_current_document
+    source = <<~RUBY
+      def foo(items)
+        total = 0
+        items.each { |item| total += item }
+        puts(total)
+      end
+
+      def bar
+        total = 1
+      end
+    RUBY
+
+    refs = find_local_references(source, { line: 3, character: 7 }).map { |ref| range_tuple(ref.range) }
+    assert_equal([[1, 2, 1, 7], [2, 22, 2, 27], [3, 7, 3, 12]], refs)
+  end
+
+  def test_local_variable_references_honor_include_declaration
+    source = <<~RUBY
+      def foo(name)
+        name.upcase
+        name
+      end
+    RUBY
+
+    refs = find_local_references(source, { line: 2, character: 2 }, include_declaration: false)
+    assert_equal([[1, 2, 1, 6], [2, 2, 2, 6]], refs.map { |ref| range_tuple(ref.range) })
+  end
+
+  def test_local_variable_in_call_arguments_is_not_treated_as_the_method
+    source = <<~RUBY
+      value = 1
+      puts(value)
+    RUBY
+
+    refs = find_local_references(source, { line: 1, character: 6 })
+    assert_equal([[0, 0, 0, 5], [1, 5, 1, 10]], refs.map { |ref| range_tuple(ref.range) })
+    assert(refs.all? { |ref| ref.uri == "file:///fake.rb" })
+  end
+
+  def test_finds_local_variable_references_in_erb
+    source = <<~ERB
+      <% items.each do |item| %>
+        <li><%= item.name %></li>
+      <% end %>
+    ERB
+
+    global_state = RubyLsp::GlobalState.new
+    document = RubyLsp::ERBDocument.new(
+      source: source,
+      version: 1,
+      uri: URI("file:///fake.erb"),
+      global_state: global_state,
+    )
+
+    refs = RubyLsp::Requests::References.new(
+      global_state,
+      RubyLsp::Store.new(global_state),
+      document,
+      { position: { line: 1, character: 10 } },
+    ).perform
+
+    assert_equal([[0, 18, 0, 22], [1, 10, 1, 14]], refs.map { |ref| range_tuple(ref.range) })
+  end
+
   private
 
+  def find_local_references(source, position, include_declaration: true)
+    global_state = RubyLsp::GlobalState.new
+    store = RubyLsp::Store.new(global_state)
+    document = RubyLsp::RubyDocument.new(
+      source: source,
+      version: 1,
+      uri: URI("file:///fake.rb"),
+      global_state: global_state,
+    )
+
+    RubyLsp::Requests::References.new(
+      global_state,
+      store,
+      document,
+      { position: position, context: { includeDeclaration: include_declaration } },
+    ).perform
+  end
+
+  def range_tuple(range)
+    [range.start.line, range.start.character, range.end.line, range.end.character]
+  end
+
   def find_references(fixture_path, position)
     source = File.read(fixture_path)
     path = File.expand_path(fixture_path)
diff --git a/test/requests/rename_test.rb b/test/requests/rename_test.rb
index d9bf7c01ec..682807f377 100644
--- a/test/requests/rename_test.rb
+++ b/test/requests/rename_test.rb
@@ -105,8 +105,185 @@ class RenameMe
     assert_equal("NewMe", untitled_change.edits[0].new_text)
   end
 
+  def test_renaming_a_local_variable
+    source = <<~RUBY
+      def foo(items)
+        total = 0
+        items.each { |item| total += item }
+        total
+      end
+
+      def bar
+        total = 1
+      end
+    RUBY
+
+    expected = <<~RUBY
+      def foo(items)
+        sum = 0
+        items.each { |item| sum += item }
+        sum
+      end
+
+      def bar
+        total = 1
+      end
+    RUBY
+
+    assert_equal(expected, rename_local(source, { line: 3, character: 2 }, "sum"))
+  end
+
+  def test_renaming_a_method_parameter
+    source = <<~RUBY
+      def foo(name, label = name)
+        "\#{label}: \#{name}"
+      end
+    RUBY
+
+    expected = <<~RUBY
+      def foo(title, label = title)
+        "\#{label}: \#{title}"
+      end
+    RUBY
+
+    assert_equal(expected, rename_local(source, { line: 0, character: 8 }, "title"))
+  end
+
+  def test_renaming_a_local_used_as_a_shorthand_keeps_the_keys
+    source = <<~RUBY
+      name = "x"
+      { name: }
+      foo(name:)
+    RUBY
+
+    expected = <<~RUBY
+      title = "x"
+      { name: title }
+      foo(name: title)
+    RUBY
+
+    assert_equal(expected, rename_local(source, { line: 0, character: 0 }, "title"))
+  end
+
+  def test_renaming_a_local_bound_by_a_hash_pattern_keeps_the_key
+    source = <<~RUBY
+      def foo(input)
+        case input
+        in { name: } then name
+        end
+      end
+    RUBY
+
+    expected = <<~RUBY
+      def foo(input)
+        case input
+        in { name: matched } then matched
+        end
+      end
+    RUBY
+
+    assert_equal(expected, rename_local(source, { line: 2, character: 20 }, "matched"))
+  end
+
+  def test_renaming_a_regexp_named_capture
+    source = <<~RUBY
+      if /(?<year>\\d+)/ =~ date
+        year
+      end
+    RUBY
+
+    expected = <<~RUBY
+      if /(?<release_year>\\d+)/ =~ date
+        release_year
+      end
+    RUBY
+
+    assert_equal(expected, rename_local(source, { line: 1, character: 2 }, "release_year"))
+  end
+
+  def test_renaming_a_local_after_multibyte_characters
+    source = <<~RUBY
+      greeting = "こんにちは"; puts greeting
+    RUBY
+
+    expected = <<~RUBY
+      message = "こんにちは"; puts message
+    RUBY
+
+    assert_equal(expected, rename_local(source, { line: 0, character: 25 }, "message"))
+  end
+
+  def test_renaming_a_local_to_a_name_in_use_raises
+    source = <<~RUBY
+      def foo(other)
+        value = 1
+        [1].each { |n| value += n }
+        helper
+      end
+    RUBY
+
+    ["other", "n", "helper"].each do |new_name|
+      assert_raises(RubyLsp::Requests::Rename::InvalidNameError) do
+        rename_local(source, { line: 1, character: 2 }, new_name)
+      end
+    end
+  end
+
+  def test_renaming_a_local_to_an_invalid_name_raises
+    source = <<~RUBY
+      value = 1
+    RUBY
+
+    ["Value", "end", "1abc", "foo bar", "@value", "_1"].each do |new_name|
+      assert_raises(RubyLsp::Requests::Rename::InvalidNameError) do
+        rename_local(source, { line: 0, character: 0 }, new_name)
+      end
+    end
+  end
+
+  def test_renaming_a_keyword_parameter_raises
+    source = <<~RUBY
+      def foo(name:)
+        name
+      end
+    RUBY
+
+    error = assert_raises(RubyLsp::Requests::Rename::InvalidNameError) do
+      rename_local(source, { line: 1, character: 2 }, "title")
+    end
+    assert_match(/Keyword parameters/, error.message)
+  end
+
   private
 
+  def rename_local(source, position, new_name)
+    global_state = RubyLsp::GlobalState.new
+    global_state.apply_options({ capabilities: { general: { positionEncodings: ["utf-16"] } } })
+    store = RubyLsp::Store.new(global_state)
+    document = RubyLsp::RubyDocument.new(
+      source: source.dup,
+      version: 1,
+      uri: URI("file:///fake.rb"),
+      global_state: global_state,
+    )
+
+    workspace_edit = RubyLsp::Requests::Rename.new(
+      global_state,
+      store,
+      document,
+      { position: position, newName: new_name },
+    ).perform #: as !nil
+
+    edits = workspace_edit.changes&.fetch("file:///fake.rb") || []
+    # Edits are relative to the original source, so apply them from the end of the document backwards
+    edits = edits.sort_by { |edit| [edit.range.start.line, edit.range.start.character] }.reverse
+    document.push_edits(
+      edits.map { |edit| { range: edit.range.to_hash.transform_values(&:to_hash), text: edit.new_text } },
+      version: 2,
+    )
+    document.source
+  end
+
   def expect_renames(fixture_path, new_fixture_path, expected, position, new_name)
     source = File.read(fixture_path)
     global_state = RubyLsp::GlobalState.new
diff --git a/test/requests/support/local_variable_finder_test.rb b/test/requests/support/local_variable_finder_test.rb
new file mode 100644
index 0000000000..df86adf273
--- /dev/null
+++ b/test/requests/support/local_variable_finder_test.rb
@@ -0,0 +1,349 @@
+# typed: true
+# frozen_string_literal: true
+
+require "test_helper"
+
+class LocalVariableFinderTest < Minitest::Test
+  def test_groups_reads_and_writes_of_the_same_variable
+    source = <<~RUBY
+      total = 0
+      total += 1
+      total ||= 2
+      total &&= 3
+      a, total = 1, 2
+      puts(total)
+    RUBY
+
+    assert_occurrences(source, [0, 0], [[0, 0], [1, 0], [2, 0], [3, 0], [4, 3], [5, 5]])
+  end
+
+  def test_separates_variables_with_the_same_name_in_different_methods
+    source = <<~RUBY
+      def foo
+        name = 1
+        name
+      end
+
+      def bar
+        name = 2
+        name
+      end
+    RUBY
+
+    assert_occurrences(source, [6, 2], [[6, 2], [7, 2]])
+  end
+
+  def test_method_scope_does_not_see_top_level_locals
+    source = <<~RUBY
+      value = 1
+
+      def foo
+        value = 2
+        value
+      end
+
+      value
+    RUBY
+
+    assert_occurrences(source, [0, 0], [[0, 0], [7, 0]])
+    assert_occurrences(source, [4, 2], [[3, 2], [4, 2]])
+  end
+
+  def test_blocks_see_locals_from_the_enclosing_scope
+    source = <<~RUBY
+      def foo
+        count = 0
+        [1, 2].each do |item|
+          count += item
+          -> { count }
+        end
+        count
+      end
+    RUBY
+
+    assert_occurrences(source, [6, 2], [[1, 2], [3, 4], [4, 9], [6, 2]])
+    assert_occurrences(source, [3, 13], [[2, 18], [3, 13]])
+  end
+
+  def test_block_parameters_and_block_locals_shadow_outer_locals
+    source = <<~RUBY
+      item = 1
+      tmp = 2
+      [1].each { |item; tmp| tmp = item }
+      item + tmp
+    RUBY
+
+    assert_occurrences(source, [0, 0], [[0, 0], [3, 0]])
+    assert_occurrences(source, [1, 0], [[1, 0], [3, 7]])
+    assert_occurrences(source, [2, 12], [[2, 12], [2, 29]])
+    assert_occurrences(source, [2, 23], [[2, 18], [2, 23]])
+  end
+
+  def test_locals_first_assigned_in_a_block_are_local_to_the_block
+    source = <<~RUBY
+      [1].each { result = 1; result }
+      [2].each { result = 2; result }
+    RUBY
+
+    assert_occurrences(source, [1, 11], [[1, 11], [1, 23]])
+  end
+
+  def test_all_parameter_types
+    source = <<~RUBY
+      def foo(a, b = a, *rest, c:, d: a, **opts, &blk)
+        [a, b, rest, c, d, opts, blk]
+      end
+    RUBY
+
+    assert_occurrences(source, [0, 8], [[0, 8], [0, 15], [0, 32], [1, 3]])
+    assert_occurrences(source, [1, 6], [[0, 11], [1, 6]])
+    assert_occurrences(source, [1, 9], [[0, 19], [1, 9]])
+    assert_occurrences(source, [1, 15], [[0, 25], [1, 15]])
+    assert_occurrences(source, [1, 18], [[0, 29], [1, 18]])
+    assert_occurrences(source, [1, 21], [[0, 37], [1, 21]])
+    assert_occurrences(source, [1, 27], [[0, 44], [1, 27]])
+  end
+
+  def test_keyword_parameter_names_exclude_the_colon
+    source = <<~RUBY
+      def foo(name:)
+        name
+      end
+    RUBY
+
+    variable, _ = find(source, [1, 2])
+    occurrence = variable.occurrences.first
+    assert_equal("name", occurrence.location.slice)
+    assert_equal(:keyword_parameter, occurrence.kind)
+  end
+
+  def test_superclass_and_singleton_receivers_belong_to_the_outer_scope
+    source = <<~RUBY
+      parent = Object
+      target = Object.new
+      class Foo < parent
+        parent = 1
+      end
+      class << target
+      end
+      def target.bar; end
+    RUBY
+
+    assert_occurrences(source, [0, 0], [[0, 0], [2, 12]])
+    assert_occurrences(source, [1, 0], [[1, 0], [5, 9], [7, 4]])
+  end
+
+  def test_hash_and_keyword_argument_shorthand
+    source = <<~RUBY
+      name = "x"
+      { name: }
+      foo(name:)
+    RUBY
+
+    variable, _ = find(source, [0, 0])
+    assert_equal([:write, :shorthand, :shorthand], variable.occurrences.map(&:kind))
+    assert_equal(["name", "name", "name"], variable.occurrences.map { |o| o.location.slice })
+  end
+
+  def test_pattern_matching
+    source = <<~RUBY
+      expected = 1
+      case value
+      in { name: } then name
+      in [^expected, rest] then rest
+      in Integer => number then number
+      end
+    RUBY
+
+    assert_occurrences(source, [0, 0], [[0, 0], [3, 5]])
+    assert_occurrences(source, [2, 18], [[2, 5], [2, 18]])
+    assert_occurrences(source, [3, 26], [[3, 15], [3, 26]])
+    assert_occurrences(source, [4, 26], [[4, 14], [4, 26]])
+  end
+
+  def test_regexp_named_captures
+    source = <<~RUBY
+      if /(?<year>\\d+)-(?<month>\\d+)/ =~ date
+        [year, month]
+      end
+    RUBY
+
+    variable, _ = find(source, [1, 10])
+    assert_equal([[0, 20], [1, 9]], positions(variable))
+    assert_equal(:regexp_capture, variable.occurrences.first.kind)
+    assert_equal("month", variable.occurrences.first.location.slice)
+  end
+
+  def test_regexp_named_captures_repeated_in_the_same_regexp
+    source = <<~RUBY
+      if /(?<digit>\\d)|(?'digit'[a-f])/ =~ input
+        digit
+      end
+    RUBY
+
+    variable, _ = find(source, [1, 2])
+    assert_equal([[0, 7], [0, 20], [1, 2]], positions(variable))
+  end
+
+  def test_destructured_block_parameters
+    source = <<~RUBY
+      pairs.each { |(key, value), index| [key, value, index] }
+    RUBY
+
+    assert_occurrences(source, [0, 36], [[0, 15], [0, 36]])
+    assert_occurrences(source, [0, 41], [[0, 20], [0, 41]])
+    assert_occurrences(source, [0, 48], [[0, 28], [0, 48]])
+  end
+
+  def test_for_loops_and_rescue_targets
+    source = <<~RUBY
+      for item in [1] do item end
+      item
+      begin
+      rescue => error
+        error
+      end
+    RUBY
+
+    assert_occurrences(source, [1, 0], [[0, 4], [0, 19], [1, 0]])
+    assert_occurrences(source, [4, 2], [[3, 10], [4, 2]])
+  end
+
+  def test_declaration_is_the_first_assignment
+    source = <<~RUBY
+      def foo(flag)
+        if flag
+          value = 1
+        else
+          value = 2
+        end
+        value
+      end
+    RUBY
+
+    variable, _ = find(source, [6, 2])
+    declaration = variable.declaration #: as !nil
+    assert_equal([2, 4], [declaration.location.start_line - 1, declaration.location.start_column])
+  end
+
+  def test_ignores_numbered_and_it_parameters
+    source = <<~RUBY
+      [1].map { _1 }
+      [1].map { it }
+    RUBY
+
+    assert_nil(find(source, [0, 10]))
+    assert_nil(find(source, [1, 10]))
+  end
+
+  def test_cursor_at_the_end_of_a_name
+    source = <<~RUBY
+      foo = 1
+      foo
+    RUBY
+
+    assert_occurrences(source, [1, 3], [[0, 0], [1, 0]])
+  end
+
+  def test_cursor_outside_of_any_local
+    source = <<~RUBY
+      foo = bar
+      Baz
+    RUBY
+
+    assert_nil(find(source, [0, 7]))
+    assert_nil(find(source, [1, 1]))
+  end
+
+  def test_name_in_use
+    source = <<~RUBY
+      def foo(a)
+        b = 1
+        [1].each { |c| d = c }
+        helper
+      end
+
+      def bar
+        e = 1
+      end
+    RUBY
+
+    finder, variable = find_with_finder(source, [1, 2])
+
+    # Parameters and locals of the same method
+    assert(finder.name_in_use?(variable, :a))
+    # Locals of blocks that can see the variable
+    assert(finder.name_in_use?(variable, :c))
+    assert(finder.name_in_use?(variable, :d))
+    # Method calls that would be shadowed
+    assert(finder.name_in_use?(variable, :helper))
+    # Locals from a different method are fine
+    refute(finder.name_in_use?(variable, :e))
+    refute(finder.name_in_use?(variable, :unused))
+  end
+
+  def test_name_in_use_checks_enclosing_scopes_of_blocks
+    source = <<~RUBY
+      outer = 1
+      [1].each { inner = 2 }
+    RUBY
+
+    finder, variable = find_with_finder(source, [1, 11])
+    assert(finder.name_in_use?(variable, :outer))
+  end
+
+  def test_multibyte_characters_before_a_local
+    source = <<~RUBY
+      greeting = "こんにちは"; greeting
+    RUBY
+
+    global_state = RubyLsp::GlobalState.new
+    global_state.apply_options({ capabilities: { general: { positionEncodings: ["utf-16"] } } })
+    document = RubyLsp::RubyDocument.new(
+      source: source,
+      version: 1,
+      uri: URI("file:///fake.rb"),
+      global_state: global_state,
+    )
+    finder = RubyLsp::Requests::Support::LocalVariableFinder.new(document.ast)
+    char_position, _ = document.find_index_by_position({ line: 0, character: 20 })
+    variable, _ = finder.variable_at(char_position, document.code_units_cache) #: as !nil
+
+    range = RubyLsp::Requests::Support::LocalVariableFinder.range_for(
+      variable.occurrences.fetch(-1).location,
+      document.code_units_cache,
+    )
+    assert_equal({ line: 0, character: 20 }, range.start.to_hash)
+    assert_equal({ line: 0, character: 28 }, range.end.to_hash)
+  end
+
+  private
+
+  def find(source, position)
+    _finder, variable, occurrence = find_with_finder(source, position)
+    [variable, occurrence] if variable
+  end
+
+  def find_with_finder(source, position)
+    document = RubyLsp::RubyDocument.new(
+      source: source,
+      version: 1,
+      uri: URI("file:///fake.rb"),
+      global_state: RubyLsp::GlobalState.new,
+    )
+    char_position, _ = document.find_index_by_position({ line: position[0], character: position[1] })
+    finder = RubyLsp::Requests::Support::LocalVariableFinder.new(document.ast)
+    variable, occurrence = finder.variable_at(char_position, document.code_units_cache)
+    [finder, variable, occurrence] if variable
+  end
+
+  def positions(variable)
+    variable.occurrences.map { |o| [o.location.start_line - 1, o.location.start_column] }
+  end
+
+  def assert_occurrences(source, position, expected)
+    variable, _ = find(source, position)
+    refute_nil(variable, "Expected a local variable at #{position.inspect}")
+    assert_equal(expected, positions(variable))
+  end
+end