pink_spoon 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fecc3a95f0a37f4c8a764c1dc116960bfd04f7911605512f591aed76d2981f64
-  data.tar.gz: a76ef303890dd64f6028b2cee4f943462c173c684c1e4551c22560415b40cfd2
+  metadata.gz: 7a1dfe02635dfec7fd176f0727ddbf7feff1a23e17ef63fdcee94c283a4e008c
+  data.tar.gz: 355c66c3af0e1cb8169d2b3b2887f161558376578a9b009bca577943d536e460
 SHA512:
-  metadata.gz: '06128423c7fc856fe1bda76bc2f754e8911556e0f1bb2098866c050db9c909553fe51475591c1bd3996b7af49ce383cc8fce48754f4e0f71c7484534535af6e9'
-  data.tar.gz: 4d28946be92e5ceb745533cb8e1b9f65edf4390248add98b16c96c69c4252a14ac0bfae429df27ab839c3d99649191ba13c37d6a53c696c8ee772e029fca66d8
+  metadata.gz: f9682658394a75acd7987bbe67df72a15041a81fe47cb8d560df327410d05b62dc421808341c8f7337d84b084b331d197dab0588d86ffdc6d4b5184cf44fe869
+  data.tar.gz: a5738766fbfe3171f40148117075fa5379a5aa25893387ad43db668558f0e6b2e1786164d4b7fd6077f6352df4242da1abb447191b7672ee926bd51327afe8dd

data/lib/pink_spoon/constant_resolver.rb

@@ -28,6 +28,7 @@ module PinkSpoon
       include_context include_examples include_shared_examples_for
       shared_examples shared_context shared_examples_for
       aggregate_failures
+      described_class
     ].freeze
 
     RSPEC_MODULE_METHODS = %w[describe shared_examples shared_context shared_examples_for].freeze
@@ -69,6 +70,22 @@ module PinkSpoon
       @_nesting   = nil
     end
 
+    # Returns the inferred type of a local variable (including block params), or nil.
+    # Used by hover to show type info alongside the "block parameter" label.
+    def infer_variable_type(var_name, program_node, nesting = nil)
+      @_nesting = nesting
+      find_local_var_type(var_name, program_node, nil)
+    rescue
+      nil
+    ensure
+      @_nesting = nil
+    end
+
+    # Returns the class name passed to the outermost describe(MyClass) block, or nil.
+    def described_class_in(program_node)
+      find_described_class(program_node)
+    end
+
     # Public entry point for completion: returns the type string of a receiver node.
     def resolve_receiver_type(receiver_node, program_node, nesting = nil)
       @_nesting = nesting
@@ -162,6 +179,22 @@ module PinkSpoon
         return nil if _seen.include?(guard)
         find_ivar_type(ivar, ast, source, _seen + [guard])
       when Prism::CallNode
+        # described_class → the class passed to the outermost describe(MyClass)
+        if receiver.name == :described_class && receiver.receiver.nil?
+          return find_described_class(ast)
+        end
+        # Bare call used as a receiver (e.g. have_been_made.once).
+        # Try ExampleGroup mixin chain, then a global RBI search so that
+        # WebMock/custom methods work even without an explicit mixin link.
+        if receiver.receiver.nil?
+          rspec_return = follow_chain("RSpec::Core::ExampleGroup", receiver.name.to_s)
+          return rspec_return if rspec_return
+          found_type = @rbi_index.find_type_for_method(receiver.name.to_s)
+          if found_type
+            ret = @rbi_index.return_type_for(found_type, receiver.name.to_s)
+            return ret if ret
+          end
+        end
         # T.must(x) → resolve x
         if receiver.name == :must && t_module?(receiver.receiver)
           arg = receiver.arguments&.arguments&.first
@@ -253,6 +286,12 @@ module PinkSpoon
       nil
     end
 
+    def find_described_class(ast)
+      finder = DescribedClassFinder.new
+      finder.visit(ast)
+      finder.result
+    end
+
     # ------------------------------------------------------------------
     # Local variable type resolution
     # ------------------------------------------------------------------
@@ -271,16 +310,35 @@ module PinkSpoon
       param_type = find_method_param_type(var_name)
       return param_type if param_type
 
-      # Block parameter: method { |var| } — infer element type from receiver.
+      # Block parameter: method { |var| } — infer type from the enclosing call.
       finder = BlockParamFinder.new(var_name)
       finder.visit(ast)
-      return nil unless finder.enclosing_call&.receiver
+      return nil unless finder.enclosing_call
+
+      call        = finder.enclosing_call
+      method_name = call.name.to_s
 
-      call          = finder.enclosing_call
-      receiver_type = resolve_receiver(call.receiver, ast, source, _seen)
+      receiver_type = if call.receiver
+        resolve_receiver(call.receiver, ast, source, _seen)
+      else
+        # Bare call (e.g. stub_request { |req| }): try ExampleGroup then global.
+        @rbi_index.return_type_for("RSpec::Core::ExampleGroup", method_name) ||
+          begin
+            ft = @rbi_index.find_type_for_method(method_name)
+            ft ? "#{ft}" : nil
+          end
+      end
       return nil unless receiver_type
 
-      method_name = call.name.to_s
+      # Prefer the explicit yield type declared in the sig (yields(SomeType)).
+      yt = @rbi_index.yield_type_for(receiver_type, method_name)
+      # For bare calls that resolved via find_type_for_method, also try that type.
+      if yt.nil? && call.receiver.nil?
+        ft = @rbi_index.find_type_for_method(method_name)
+        yt = @rbi_index.yield_type_for(ft, method_name) if ft
+      end
+      return yt if yt
+
       if ENUMERATION_METHODS.include?(method_name)
         extract_element_type(receiver_type)
       else
@@ -304,10 +362,7 @@ module PinkSpoon
     def find_method_param_type(param_name)
       return nil unless @_call_line && @_nesting
 
-      class_node = @_nesting.reverse.find { |n| n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
-      return nil unless class_node
-
-      current_type = class_node.constant_path.slice.delete_prefix("::")
+      current_type = qualified_type_from_nesting(@_nesting)
       method_name  = EnclosingDefFinder.new(@_call_line).find(
         @_nesting.find { |n| n.is_a?(Prism::ProgramNode) }
       )
@@ -318,6 +373,14 @@ module PinkSpoon
       raw ? unwrap_sorbet_wrapper(raw) : nil
     end
 
+    def qualified_type_from_nesting(nesting)
+      return nil unless nesting
+      parts = nesting
+        .select { |n| n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
+        .map { |n| n.constant_path.slice.delete_prefix("::") }
+      parts.empty? ? nil : parts.join("::")
+    end
+
     def extract_element_type(type_str)
       return nil unless type_str
       m = type_str.match(/\[(\w+(?:::\w+)*)\]$/)
@@ -427,6 +490,23 @@ module PinkSpoon
       end
     end
 
+    # Finds the class constant passed as the first argument to the outermost
+    # describe(MyClass) or RSpec.describe(MyClass) call in the file.
+    class DescribedClassFinder < Prism::Visitor
+      attr_reader :result
+
+      def visit_call_node(node)
+        if node.name == :describe && @result.nil?
+          first = node.arguments&.arguments&.first
+          @result = case first
+                    when Prism::ConstantReadNode then first.name.to_s
+                    when Prism::ConstantPathNode then first.slice.delete_prefix("::")
+                    end
+        end
+        super
+      end
+    end
+
     # Finds the CallNode whose block introduces `var_name` as a parameter.
     # e.g.  entries.each { |entry| }  →  enclosing_call = entries.each(...)
     class BlockParamFinder < Prism::Visitor

data/lib/pink_spoon/doc_extractor.rb

@@ -32,7 +32,7 @@ module PinkSpoon
           end
         end
 
-        %w[lib app].each do |subdir|
+        %w[lib app spec test].each do |subdir|
           dir = File.join(@root_path, subdir)
           next unless File.directory?(dir)
           Dir.glob("#{dir}/**/*.rb").sort.each do |file|
@@ -126,19 +126,47 @@ module PinkSpoon
         end
       end
 
-      # Fall back to project source (lib/, app/).
-      %w[lib app].each do |subdir|
+      # For project files: try the conventional Zeitwerk path first so that a
+      # fully-qualified type like Acme::Billing::Worker resolves directly to
+      # lib/acme/billing/worker.rb rather than returning the first alphabetical
+      # match from a glob (which may be an unrelated class with the same name).
+      %w[lib app spec test].each do |subdir|
         dir = File.join(@root_path, subdir)
         next unless File.directory?(dir)
-        Dir.glob("#{dir}/**/*.rb").sort.each do |file|
-          line = first_line_matching(file, pattern)
-          return { file: file, line: line } if line
+
+        if parts.size > 1
+          candidate = File.join(dir, *parts.map { |p| underscore(p) }) + ".rb"
+          if File.exist?(candidate)
+            line = first_line_matching(candidate, pattern)
+            return { file: candidate, line: line || 1 } if line
+          end
+          # Glob fallback: require the file path to contain the full
+          # intermediate namespace so that lib/nexus/au/.../download.rb is
+          # not returned when looking for Nexus::Gb::Bacs::Form3::Retrievals::Download.
+          # Also accepts a single-file namespace (lib/my_gem.rb for MyGem::Foo).
+          intermediate = parts[0..-2].map { |p| underscore(p) }.join("/")
+          Dir.glob("#{dir}/**/*.rb").sort.each do |file|
+            next unless file.include?("/#{intermediate}/") || file.end_with?("/#{intermediate}.rb")
+            line = first_line_matching(file, pattern)
+            return { file: file, line: line } if line
+          end
+        else
+          Dir.glob("#{dir}/**/*.rb").sort.each do |file|
+            line = first_line_matching(file, pattern)
+            return { file: file, line: line } if line
+          end
         end
       end
 
       nil
     end
 
+    def underscore(str)
+      str.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+         .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+         .downcase
+    end
+
     def first_line_matching(file, pattern)
       File.foreach(file).with_index(1) { |l, i| return i if l.match?(pattern) }
       nil
@@ -165,7 +193,7 @@ module PinkSpoon
       end
 
       # Fall back to project source (lib/, app/) for project-defined methods.
-      %w[lib app].each do |subdir|
+      %w[lib app spec test].each do |subdir|
         dir = File.join(@root_path, subdir)
         next unless File.directory?(dir)
         Dir.glob("#{dir}/**/*.rb").sort.each do |file|

data/lib/pink_spoon/rbi_index.rb

@@ -14,14 +14,18 @@ module PinkSpoon
   # though the method is defined on Hesiod::Gauge (which Hesiod extends).
   class RbiIndex
     def initialize(root_path)
-      @root_path = root_path
-      @sigs      = Hash.new { |h, k| h[k] = {} }
-      @types     = Hash.new { |h, k| h[k] = {} }
-      @defs      = Hash.new { |h, k| h[k] = {} }
-      @sources   = Hash.new { |h, k| h[k] = {} }
-      @locations = Hash.new { |h, k| h[k] = {} }
-      @mixins    = Hash.new { |h, k| h[k] = [] }
-      @params    = Hash.new { |h, k| h[k] = {} }
+      @root_path       = root_path
+      @sigs            = Hash.new { |h, k| h[k] = {} }
+      @types           = Hash.new { |h, k| h[k] = {} }
+      @defs            = Hash.new { |h, k| h[k] = {} }
+      @sources         = Hash.new { |h, k| h[k] = {} }
+      @locations       = Hash.new { |h, k| h[k] = {} }
+      @mixins          = Hash.new { |h, k| h[k] = [] }
+      @params          = Hash.new { |h, k| h[k] = {} }
+      @yields              = Hash.new { |h, k| h[k] = {} }
+      @const_locations     = {}
+      @const_resolve_cache = {}
+      @method_type_cache   = {}
       build
     end
 
@@ -109,6 +113,20 @@ module PinkSpoon
       @mixins[normalise(type)].dup
     end
 
+    # Returns { file:, line: } pointing at the real gem source for a constant,
+    # resolved from the "# source://" comment in the RBI file, or nil.
+    # Resolution is deferred to call time and nil results are not cached so
+    # transient Bundler state changes don't permanently break lookups.
+    def const_source_for(type)
+      raw = @const_locations[normalise(type)]
+      return nil unless raw
+      cached = @const_resolve_cache[raw]
+      return cached if cached
+      loc = resolve_source_uri(raw)
+      @const_resolve_cache[raw] = loc if loc
+      loc
+    end
+
     # Returns { param_name => type_string } for type#method, or nil.
     # Follows the mixin chain.
     def params_for(type, method_name, _seen = [])
@@ -144,6 +162,42 @@ module PinkSpoon
       result
     end
 
+    # Returns the yield type declared in the sig (yields(Type)), or nil.
+    # e.g. for `sig { yields(WebMock::RequestSignature).returns(...) }`
+    # returns "WebMock::RequestSignature".
+    def yield_type_for(type, method_name, _seen = [])
+      t = normalise(type)
+      return nil if _seen.include?(t)
+
+      direct = @yields[t][method_name.to_s]
+      return direct if direct
+
+      @mixins[t].each do |mixin|
+        result = yield_type_for(mixin, method_name, _seen + [t])
+        return result if result
+      end
+
+      nil
+    end
+
+    # Returns the first RBI type that defines +method_name+, scanning all
+    # indexed types. Used as a last resort when mixin-chain lookups fail
+    # (e.g. WebMock methods not wired into RSpec::Core::ExampleGroup).
+    def find_type_for_method(method_name)
+      name = method_name.to_s
+      return @method_type_cache[name] if @method_type_cache.key?(name)
+
+      result = nil
+      @sigs.each { |type, methods| result = type and break if methods.key?(name) }
+      result ||= begin
+        found = nil
+        @defs.each { |type, methods| found = type and break if methods.key?(name) }
+        found
+      end
+      @method_type_cache[name] = result
+      result
+    end
+
     # All known types (for debugging / testing).
     def types = @sigs.keys
 
@@ -180,12 +234,51 @@ module PinkSpoon
         @defs[type][entry[:method]]      = entry[:def_line]
         @params[type][entry[:method]]    = entry[:params] if entry[:params]
         @sources[type][entry[:method]]   = entry[:source] if entry[:source]
+        @yields[type][entry[:method]]    = entry[:yield_type] if entry[:yield_type]
         @locations[type][entry[:method]] = { file: path, line: entry[:line] }
       end
 
       visitor.mixins.each do |type, mixin_list|
         @mixins[normalise(type)].concat(mixin_list.map { normalise(_1) }).uniq!
       end
+
+      visitor.const_sources.each do |type, raw_uri|
+        @const_locations[normalise(type)] = raw_uri
+      end
+    end
+
+    # Parses "# source://gem-name//lib/path/to/file.rb#42" and resolves
+    # the gem name to a real file path.
+    #
+    # Primary: scan $LOAD_PATH for entries containing /gems/<gem-name>-<version>/.
+    # $LOAD_PATH is fixed at process start and unaffected by Bundler state changes
+    # that ruby-lsp triggers during its indexing phase.
+    #
+    # Fallback: scan Gem.path directories (covers cases where the gem's lib dir
+    # is not explicitly on the load path).
+    def resolve_source_uri(comment)
+      m = comment.match(%r{source://([^/]+)//(.+?)#(\d+)})
+      return nil unless m
+      gem_name, rel_path, line = m[1], m[2], m[3].to_i
+      lp_pattern = %r{/gems/(#{Regexp.escape(gem_name)}-[^/]+)/}
+
+      $LOAD_PATH.each do |lp|
+        next unless (lm = lp.match(lp_pattern))
+        gem_dir = lp[0, lp.index(lm[0]) + lm[0].length - 1]
+        file = File.join(gem_dir, rel_path)
+        return { file: file, line: line } if File.exist?(file)
+      end
+
+      Gem.path.each do |gem_base|
+        Dir.glob("#{gem_base}/gems/#{gem_name}-*/").sort.reverse.each do |gem_dir|
+          file = File.join(gem_dir, rel_path)
+          return { file: file, line: line } if File.exist?(file)
+        end
+      end
+
+      nil
+    rescue
+      nil
     end
 
     def normalise(type)
@@ -198,25 +291,31 @@ module PinkSpoon
     #   - extend/include calls (mixins)
     # ------------------------------------------------------------------
     class RbiVisitor < Prism::Visitor
-      attr_reader :entries, :mixins
+      attr_reader :entries, :mixins, :const_sources
 
       def initialize(comment_map = {})
-        @entries     = []
-        @mixins      = Hash.new { |h, k| h[k] = [] }
-        @scope       = []
-        @pending_sig = nil
-        @comment_map = comment_map
+        @entries       = []
+        @mixins        = Hash.new { |h, k| h[k] = [] }
+        @const_sources = {}
+        @scope         = []
+        @pending_sig   = nil
+        @comment_map   = comment_map
       end
 
       def visit_module_node(node)
-        push_scope(node.constant_path) { super }
+        source_comment = source_comment_at(node.location.start_line)
+        push_scope(node.constant_path) do
+          @const_sources[@scope.join("::")] = source_comment if source_comment
+          super
+        end
       end
 
       def visit_class_node(node)
+        source_comment = source_comment_at(node.location.start_line)
         push_scope(node.constant_path) do
-          # Record superclass as a parent so method lookups walk the chain.
+          type = @scope.join("::")
+          @const_sources[type] = source_comment if source_comment
           if node.superclass
-            type   = @scope.join("::")
             parent = const_path_to_string(node.superclass).delete_prefix("::")
             @mixins[type] << parent unless @mixins[type].include?(parent)
           end
@@ -253,6 +352,7 @@ module PinkSpoon
           sig:         sig,
           def_line:    def_line,
           return_type: sig ? extract_return_type(sig) : nil,
+          yield_type:  sig ? extract_yield_type(sig) : nil,
           params:      sig ? extract_params(sig) : {},
           source:      source,
           line:        node.location.start_line,
@@ -263,6 +363,11 @@ module PinkSpoon
 
       private
 
+      def source_comment_at(start_line)
+        c = @comment_map[start_line - 1]
+        c if c&.include?("source://")
+      end
+
       def record_mixins(call_node)
         type = @scope.join("::")
         return if type.empty?
@@ -296,6 +401,11 @@ module PinkSpoon
         match&.[](1)
       end
 
+      def extract_yield_type(sig)
+        match = sig.match(/yields\(\s*([\w:]+)\s*\)/)
+        match&.[](1)&.delete_prefix("::")
+      end
+
       def extract_params(sig)
         m = sig.match(/params\((.+?)\)\s*\./m)
         return {} unless m

data/lib/pink_spoon/server.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "prism"
 require_relative "rbi_index"
 require_relative "constant_resolver"
 require_relative "definition_finder"
@@ -56,6 +57,8 @@ module PinkSpoon
         exit(0)
       when "textDocument/definition"
         write_response(id, on_definition(req[:params]))
+      when "textDocument/diagnostic"
+        write_response(id, { kind: "full", items: [] })
       when "textDocument/hover"
         write_response(id, on_hover(req[:params]))
       else
@@ -92,23 +95,19 @@ module PinkSpoon
     def on_definition(params)
       return nil unless @rbi_index
 
-      file   = uri_to_path(params.dig(:textDocument, :uri))
-      line   = params.dig(:position, :line)
-      col    = params.dig(:position, :character)
+      file = uri_to_path(params.dig(:textDocument, :uri))
+      line = params.dig(:position, :line)
+      col  = params.dig(:position, :character)
 
       resolved = @constant_resolver.resolve_at(file, line, col)
-      return nil unless resolved
-
-      location = @definition_finder.find(resolved[:type], resolved[:method])
-      return nil unless location
+      if resolved
+        location = @definition_finder.find(resolved[:type], resolved[:method])
+        return location_response(location[:file], location[:line]) if location
+      end
 
-      {
-        uri:   path_to_uri(location[:file]),
-        range: {
-          start: { line: location[:line] - 1, character: 0 },
-          end:   { line: location[:line] - 1, character: 0 },
-        },
-      }
+      local_variable_definition(file, line, col)
+    rescue
+      nil
     end
 
     def on_hover(params)
@@ -132,6 +131,34 @@ module PinkSpoon
       }
     end
 
+    def local_variable_definition(file, lsp_line, col)
+      return nil unless file && File.exist?(file)
+
+      result = Prism.parse_file(file)
+      return nil unless result.success?
+
+      prism_line = lsp_line + 1
+      var_node   = CursorLocalVarFinder.new(prism_line, col).tap { |f| f.visit(result.value) }.result
+      return nil unless var_node
+
+      decl_line = LocalVarDeclarationFinder.new(var_node.name.to_s, prism_line).tap { |f| f.visit(result.value) }.line
+      return nil unless decl_line
+
+      location_response(file, decl_line)
+    rescue
+      nil
+    end
+
+    def location_response(file, line)
+      {
+        uri:   path_to_uri(file),
+        range: {
+          start: { line: line - 1, character: 0 },
+          end:   { line: line - 1, character: 0 },
+        },
+      }
+    end
+
     # ------------------------------------------------------------------
     # Protocol helpers
     # ------------------------------------------------------------------
@@ -170,4 +197,58 @@ module PinkSpoon
       "file://#{path}"
     end
   end
+
+  # Finds the LocalVariableReadNode whose source range covers the given cursor.
+  class CursorLocalVarFinder < Prism::Visitor
+    attr_reader :result
+
+    def initialize(line, col)
+      @line = line
+      @col  = col
+    end
+
+    def visit_local_variable_read_node(node)
+      loc = node.location
+      if loc.start_line == @line &&
+         loc.start_column <= @col &&
+         loc.end_column   >  @col
+        @result = node
+      end
+      super
+    end
+  end
+
+  # Finds the line where a local variable was last declared (parameter or
+  # assignment) before a given line number.
+  class LocalVarDeclarationFinder < Prism::Visitor
+    def initialize(var_name, before_line)
+      @var_name    = var_name
+      @before_line = before_line
+      @candidates  = []
+    end
+
+    def line
+      @candidates.last
+    end
+
+    def visit_local_variable_write_node(node)          = record(node) || super
+    def visit_local_variable_operator_write_node(node) = record(node) || super
+    def visit_local_variable_or_write_node(node)       = record(node) || super
+    def visit_local_variable_and_write_node(node)      = record(node) || super
+    def visit_required_parameter_node(node)            = record(node) || super
+    def visit_optional_parameter_node(node)            = record(node) || super
+    def visit_rest_parameter_node(node)                = record(node) || super
+    def visit_keyword_rest_parameter_node(node)        = record(node) || super
+    def visit_block_parameter_node(node)               = record(node) || super
+    def visit_required_keyword_parameter_node(node)    = record(node) || super
+    def visit_optional_keyword_parameter_node(node)    = record(node) || super
+
+    private
+
+    def record(node)
+      return unless node.name.to_s == @var_name
+      line_no = node.location.start_line
+      @candidates << line_no if line_no <= @before_line
+    end
+  end
 end

data/lib/pink_spoon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PinkSpoon
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

data/lib/ruby_lsp/pink_spoon/addon.rb

@@ -13,6 +13,100 @@ require_relative "code_lens_listener"
 
 module RubyLsp
   module PinkSpoon
+    # Prepended to RubyLsp::Requests::Definition to handle local variable
+    # go-to-definition. Ruby-lsp excludes LocalVariableReadNode from its
+    # node_types list, so when the cursor is on a local variable (including
+    # when it is the receiver of a method call), ruby-lsp sets target = nil
+    # and calls no listeners. This patch does a second locate pass for that
+    # exact case and dispatches to pink-spoon's DefinitionListener.
+    module LocalVariableDefinitionFallback
+      class << self
+        attr_accessor :addon_instance
+      end
+
+      def initialize(document, global_state, position, dispatcher, sorbet_level)
+        super
+
+        return if @target
+        return unless document.is_a?(RubyLsp::RubyDocument)
+
+        char_position, _ = document.find_index_by_position(position)
+        lv_context = RubyLsp::RubyDocument.locate(
+          document.ast,
+          char_position,
+          node_types: [Prism::LocalVariableReadNode],
+          code_units_cache: document.code_units_cache,
+        )
+        return unless lv_context.node.is_a?(Prism::LocalVariableReadNode)
+
+        addon = LocalVariableDefinitionFallback.addon_instance
+        return unless addon
+
+        @_lv_dispatcher = Prism::Dispatcher.new
+        addon.create_definition_listener(@response_builder, document.uri, lv_context, @_lv_dispatcher)
+        @_lv_target = lv_context.node
+      end
+
+      def perform
+        result = super
+        if @_lv_target && @_lv_dispatcher && result.empty?
+          @_lv_dispatcher.dispatch_once(@_lv_target)
+          return @response_builder.response
+        end
+        result
+      end
+    end
+
+    # Same pattern as LocalVariableDefinitionFallback but for hover.
+    # Hover#perform returns nil when target is nil; here we intercept,
+    # do a second locate for LocalVariableReadNode, and return hover content.
+    module LocalVariableHoverFallback
+      class << self
+        attr_accessor :addon_instance
+      end
+
+      def initialize(document, global_state, position, dispatcher, sorbet_level)
+        super
+
+        return if @target
+        return unless document.is_a?(RubyLsp::RubyDocument)
+
+        char_position, _ = document.find_index_by_position(position)
+        lv_context = RubyLsp::RubyDocument.locate(
+          document.ast,
+          char_position,
+          node_types: [Prism::LocalVariableReadNode],
+          code_units_cache: document.code_units_cache,
+        )
+        return unless lv_context.node.is_a?(Prism::LocalVariableReadNode)
+
+        addon = LocalVariableHoverFallback.addon_instance
+        return unless addon
+
+        @_lv_hover_builder = RubyLsp::ResponseBuilders::Hover.new
+        @_lv_hover_dispatcher = Prism::Dispatcher.new
+        addon.create_hover_listener(@_lv_hover_builder, lv_context, @_lv_hover_dispatcher)
+        @_lv_hover_target = lv_context.node
+      end
+
+      def perform
+        result = super
+        return result if result
+
+        return nil unless @_lv_hover_target && @_lv_hover_dispatcher
+
+        @_lv_hover_dispatcher.dispatch_once(@_lv_hover_target)
+        return nil if @_lv_hover_builder.empty?
+
+        RubyLsp::Interface::Hover.new(
+          contents: RubyLsp::Interface::MarkupContent.new(
+            kind: "markdown",
+            value: @_lv_hover_builder.response,
+          ),
+        )
+      end
+    end
+
     class Addon < ::RubyLsp::Addon
       def activate(global_state, outgoing_queue)
         root = global_state.workspace_path
@@ -20,9 +114,22 @@ module RubyLsp
         @rbi_index         = ::PinkSpoon::RbiIndex.new(root)
         @constant_resolver = ::PinkSpoon::ConstantResolver.new(root, @rbi_index)
         @doc_extractor     = ::PinkSpoon::DocExtractor.new(root)
+
+        unless RubyLsp::Requests::Definition.ancestors.include?(LocalVariableDefinitionFallback)
+          LocalVariableDefinitionFallback.addon_instance = self
+          RubyLsp::Requests::Definition.prepend(LocalVariableDefinitionFallback)
+        end
+
+        unless RubyLsp::Requests::Hover.ancestors.include?(LocalVariableHoverFallback)
+          LocalVariableHoverFallback.addon_instance = self
+          RubyLsp::Requests::Hover.prepend(LocalVariableHoverFallback)
+        end
       end
 
-      def deactivate; end
+      def deactivate
+        LocalVariableDefinitionFallback.addon_instance = nil
+        LocalVariableHoverFallback.addon_instance = nil
+      end
 
       def name    = "Pink Spoon"
       def version = ::PinkSpoon::VERSION

data/lib/ruby_lsp/pink_spoon/definition_listener.rb

@@ -41,11 +41,31 @@ module RubyLsp
           source_location(resolved) || rbi_location(resolved)
         end
 
-        # Bare call (no explicit receiver): try two more strategies.
+        # Bare call with no location yet: try RSpec::Core::ExampleGroup.
+        # Handles expect, have_been_made, a_request, stub_request, etc.
+        if location.nil? && node.receiver.nil? && resolved.nil?
+          eg_resolved = { type: "RSpec::Core::ExampleGroup", method: node.name.to_s }
+          location = source_location(eg_resolved) || rbi_location(eg_resolved)
+        end
+
+        # described_class → go to the class passed to describe(MyClass)
+        if location.nil? && node.receiver.nil? && node.name == :described_class
+          described = @resolver.described_class_in(program_node)
+          if described
+            goto_constant(described)
+            return
+          end
+        end
+
+        # Bare call (no explicit receiver): current file first, then nesting.
+        # Checking the current file first avoids the project-wide scan in
+        # nesting_location picking up a same-named method in a different file
+        # (e.g. alphabetically earlier au/.../download.rb vs gb/.../download.rb).
         if location.nil? && node.receiver.nil?
           method_name = node.name.to_s
-          location    = nesting_location(method_name, nesting) ||
-                        current_file_location(method_name)
+          location    = current_file_location(method_name) ||
+                        nesting_location(method_name, nesting) ||
+                        included_module_location(method_name, program_node)
         end
 
         # Fallback: ruby-lsp resolves LocalVariableReadNode receivers up to the
@@ -94,12 +114,11 @@ module RubyLsp
       def on_def_node_enter(node)
         return unless node.equal?(@node_context.node)
 
-        nesting    = @node_context.instance_variable_get(:@nesting_nodes)
-        class_node = nesting&.reverse&.find { |n| n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
-        return unless class_node
+        nesting = @node_context.instance_variable_get(:@nesting_nodes)
+        type    = qualified_type_from_nesting(nesting)
+        return unless type
 
-        type = class_node.constant_path.slice.delete_prefix("::")
-        loc  = source_location({ type: type, method: node.name.to_s })
+        loc = source_location({ type: type, method: node.name.to_s })
         push_location(loc[:file], loc[:line]) if loc
       rescue
         nil
@@ -134,11 +153,10 @@ module RubyLsp
         end
 
         # Not found in current file — walk the parent class chain.
-        nesting    = @node_context.instance_variable_get(:@nesting_nodes)
-        class_node = nesting&.reverse&.find { |n| n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
-        return unless class_node
+        nesting      = @node_context.instance_variable_get(:@nesting_nodes)
+        current_type = qualified_type_from_nesting(nesting)
+        return unless current_type
 
-        current_type = class_node.constant_path.slice.delete_prefix("::")
         @rbi_index.mixins_for(current_type).each do |parent_type|
           loc = @doc_extractor&.find_ivar_in_type(parent_type, ivar_name)
           if loc
@@ -150,6 +168,27 @@ module RubyLsp
         nil
       end
 
+      # Handles go-to-definition for real local variables (entry = ..., |entry|, etc).
+      def on_local_variable_read_node_enter(node)
+        return unless node.equal?(@node_context.node)
+
+        file = @uri.to_s.delete_prefix("file://")
+        return unless file && File.exist?(file)
+
+        var_name  = node.name.to_s
+        read_line = node.location.start_line
+
+        result = Prism.parse_file(file)
+        finder = LocalVariableDefinitionFinder.new(var_name, read_line)
+        finder.visit(result.value)
+        line = finder.line
+        return unless line
+
+        push_location(file, line)
+      rescue
+        nil
+      end
+
       private
 
       def navigate_super(node)
@@ -157,11 +196,10 @@ module RubyLsp
         program_node = nesting&.find { |n| n.is_a?(Prism::ProgramNode) }
         return unless program_node
 
-        class_node = nesting.reverse.find { |n| n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
-        return unless class_node
+        current_type = qualified_type_from_nesting(nesting)
+        return unless current_type
 
-        current_type = class_node.constant_path.slice.delete_prefix("::")
-        method_name  = EnclosingMethodFinder.new(node.location.start_line).find(program_node)
+        method_name = EnclosingMethodFinder.new(node.location.start_line).find(program_node)
         return unless method_name
 
         @rbi_index.mixins_for(current_type).each do |parent_type|
@@ -203,15 +241,80 @@ module RubyLsp
         nil
       end
 
+      # Scans the file AST for include/extend/prepend calls and tries each
+      # module as a source for the method. Covers the case where a method comes
+      # from an included module that isn't in the RBI mixin chain.
+      def included_module_location(method_name, program_node)
+        included_module_names(program_node).each do |mod_name|
+          resolved = { type: mod_name, method: method_name }
+          loc = rbi_location(resolved) || source_location(resolved)
+          return loc if loc
+        end
+        nil
+      rescue
+        nil
+      end
+
+      def included_module_names(program_node)
+        names = []
+        collect_includes(program_node, names)
+        names
+      end
+
+      def collect_includes(node, names)
+        return unless node.is_a?(Prism::Node)
+        if node.is_a?(Prism::CallNode) && node.receiver.nil? &&
+           %i[include extend prepend].include?(node.name)
+          node.arguments&.arguments&.each do |arg|
+            name = case arg
+                   when Prism::ConstantReadNode then arg.name.to_s
+                   when Prism::ConstantPathNode then arg.slice.delete_prefix("::")
+                   end
+            names << name if name
+          end
+        end
+        node.child_nodes.compact.each { |child| collect_includes(child, names) }
+      end
+
       def guess_type_from_nesting(nesting)
-        class_node = nesting&.reverse&.find { |n| n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
-        class_node&.constant_path&.slice&.delete_prefix("::")
+        qualified_type_from_nesting(nesting)
       end
 
-      def goto_constant(type)
-        location = @doc_extractor&.find_constant_source(type)
-        return unless location
-        push_location(location[:file], location[:line])
+      def qualified_type_from_nesting(nesting)
+        return nil unless nesting
+        parts = nesting
+          .select { |n| n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
+          .map { |n| n.constant_path.slice.delete_prefix("::") }
+        parts.empty? ? nil : parts.join("::")
+      end
+
+      def goto_constant(bare_name)
+        nesting = @node_context.instance_variable_get(:@nesting_nodes)
+
+        lexical_candidates(bare_name, nesting).each do |candidate|
+          location = @rbi_index.const_source_for(candidate)
+          location ||= @doc_extractor&.find_constant_source(candidate)
+          next unless location
+
+          push_location(location[:file], location[:line])
+          return
+        end
+      end
+
+      def lexical_candidates(bare_name, nesting)
+        parts = nesting
+          &.select { |n| n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
+          &.map { |n| n.constant_path.slice.delete_prefix("::") }
+
+        return [bare_name] if parts.nil? || parts.empty?
+
+        candidates = []
+        while parts.any?
+          candidates << "#{parts.join("::")}::#{bare_name}"
+          parts.pop
+        end
+        candidates << bare_name
+        candidates
       end
 
       def rbi_location(resolved)
@@ -225,40 +328,13 @@ module RubyLsp
       # Infer the type from the innermost enclosing class/module in the nesting
       # and look the method up in the RBI index or gem source.
       def nesting_location(method_name, nesting)
-        return nil unless nesting
+        type = qualified_type_from_nesting(nesting)
+        return nil unless type
 
-        class_node = nesting.reverse.find do |n|
-          n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode)
-        end
-        return nil unless class_node
-
-        type     = class_node.constant_path.slice.delete_prefix("::")
         resolved = { type: type, method: method_name }
-
         rbi_location(resolved) || source_location(resolved)
       end
 
-      # Handles go-to-definition for real local variables (entry = ..., |entry|, etc).
-      def on_local_variable_read_node_enter(node)
-        return unless node.equal?(@node_context.node)
-
-        file = @uri.to_s.delete_prefix("file://")
-        return unless file && File.exist?(file)
-
-        var_name  = node.name.to_s
-        read_line = node.location.start_line
-
-        result = Prism.parse_file(file)
-        finder = LocalVariableDefinitionFinder.new(var_name, read_line)
-        finder.visit(result.value)
-        line = finder.line
-        return unless line
-
-        push_location(file, line)
-      rescue
-        nil
-      end
-
       # Last resort: scan the file the user is currently editing.
       # Matches def, let(:name), let!(:name), subject(:name), subject!(:name).
       def current_file_location(method_name)
@@ -280,13 +356,26 @@ module RubyLsp
       end
 
       def push_location(file, line)
+        target_uri = "file://#{file}"
+
+        begin
+          existing = @response_builder.response
+          return if existing.any? do |item|
+            (item.respond_to?(:target_uri) ? item.target_uri : item.uri) == target_uri
+          end
+        rescue
+          # Can't inspect existing results — proceed with the push
+        end
+
         line_lsp = line - 1
-        @response_builder << Interface::Location.new(
-          uri:   "file://#{file}",
-          range: Interface::Range.new(
-            start: Interface::Position.new(line: line_lsp, character: 0),
-            end:   Interface::Position.new(line: line_lsp, character: 0),
-          ),
+        range = Interface::Range.new(
+          start: Interface::Position.new(line: line_lsp, character: 0),
+          end:   Interface::Position.new(line: line_lsp, character: 0),
+        )
+        @response_builder << Interface::LocationLink.new(
+          target_uri:             target_uri,
+          target_range:           range,
+          target_selection_range: range,
         )
       end
 
@@ -336,6 +425,16 @@ module RubyLsp
           super
         end
 
+        def visit_rest_parameter_node(node)
+          record(node)
+          super
+        end
+
+        def visit_keyword_rest_parameter_node(node)
+          record(node)
+          super
+        end
+
         # Block parameters: do |entry|
         def visit_block_parameter_node(node)
           record(node)

data/lib/ruby_lsp/pink_spoon/hover_listener.rb

@@ -23,6 +23,7 @@ module RubyLsp
           :on_constant_read_node_enter,
           :on_constant_path_node_enter,
           :on_instance_variable_read_node_enter,
+          :on_local_variable_read_node_enter,
         )
       end
 
@@ -39,11 +40,10 @@ module RubyLsp
       def on_instance_variable_read_node_enter(node)
         return unless node.equal?(@node_context.node)
 
-        nesting    = @node_context.instance_variable_get(:@nesting_nodes)
-        class_node = nesting&.reverse&.find { |n| n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
-        return unless class_node
+        nesting  = @node_context.instance_variable_get(:@nesting_nodes)
+        type     = qualified_type_from_nesting(nesting)
+        return unless type
 
-        type     = class_node.constant_path.slice.delete_prefix("::")
         accessor = node.name.to_s.delete_prefix("@")
 
         content = @rbi_index.hover_content_for(type, accessor)
@@ -59,20 +59,123 @@ module RubyLsp
         program_node = nesting&.find { |n| n.is_a?(Prism::ProgramNode) }
         return unless program_node
 
+        if node.name == :described_class && node.receiver.nil?
+          described = @resolver.described_class_in(program_node)
+          if described
+            @response_builder.push("**`described_class`** → `#{described}`", category: :documentation)
+            return
+          end
+        end
+
         resolved = @resolver.resolve_from_call(node, program_node)
+
+        if resolved.nil? && node.receiver.nil?
+          type     = qualified_type_from_nesting(nesting)
+          resolved = { type: type, method: node.name.to_s } if type
+        end
+
+        # Bare call with still-unresolved type: try ExampleGroup.
+        # Catches RSpec/WebMock methods (expect, have_been_made, a_request, etc.)
+        # that arrive via globally-included modules not visible in the file AST.
+        if resolved.nil? && node.receiver.nil?
+          resolved = { type: "RSpec::Core::ExampleGroup", method: node.name.to_s }
+        end
+
         return unless resolved
 
         rbi_content = @rbi_index.hover_content_for(resolved[:type], resolved[:method])
         doc_content = @doc_extractor&.extract(resolved[:type], resolved[:method])
 
+        # If the main type chain yielded nothing and this is a bare call, scan the
+        # file AST for include/extend declarations and try each module directly.
+        # This covers methods that come from included modules not in the RBI chain.
+        if rbi_content.nil? && doc_content.nil? && node.receiver.nil?
+          rbi_content, doc_content = hover_from_included_modules(resolved[:method], program_node)
+        end
+
+        # Global fallback: find any RBI type that defines this method.
+        # Handles WebMock/custom methods not wired into the ExampleGroup chain.
+        if rbi_content.nil? && doc_content.nil? && node.receiver.nil?
+          found_type = @rbi_index.find_type_for_method(resolved[:method])
+          if found_type
+            rbi_content = @rbi_index.hover_content_for(found_type, resolved[:method])
+            doc_content = @doc_extractor&.extract(found_type, resolved[:method])
+          end
+        end
+
         content = combine(rbi_content, doc_content)
         return unless content
 
         @response_builder.push(content, category: :documentation)
       end
 
+      def on_local_variable_read_node_enter(node)
+        return unless node.equal?(@node_context.node)
+
+        nesting = @node_context.instance_variable_get(:@nesting_nodes)
+        program = nesting&.find { |n| n.is_a?(Prism::ProgramNode) }
+        return unless program
+
+        finder = LocalVarKindFinder.new(node.name.to_s, node.location.start_line)
+        finder.visit(program)
+        return unless finder.kind
+
+        label = case finder.kind
+                when :method_param then "parameter"
+                when :block_param  then "block parameter"
+                else                    "local variable"
+                end
+
+        type = @resolver.infer_variable_type(node.name.to_s, program, nesting)
+        text = type ? "**`#{node.name}`** — *#{label}* `#{type}`" \
+                    : "**`#{node.name}`** — *#{label}*"
+        @response_builder.push(text, category: :documentation)
+      rescue
+        nil
+      end
+
       private
 
+      def hover_from_included_modules(method_name, program_node)
+        included_module_names(program_node).each do |mod_name|
+          rbi = @rbi_index.hover_content_for(mod_name, method_name)
+          doc = @doc_extractor&.extract(mod_name, method_name)
+          return [rbi, doc] if rbi || doc
+        end
+        [nil, nil]
+      rescue
+        [nil, nil]
+      end
+
+      def included_module_names(program_node)
+        names = []
+        collect_includes(program_node, names)
+        names
+      end
+
+      def collect_includes(node, names)
+        return unless node.is_a?(Prism::Node)
+        if node.is_a?(Prism::CallNode) && node.receiver.nil? &&
+           %i[include extend prepend].include?(node.name)
+          node.arguments&.arguments&.each do |arg|
+            name = case arg
+                   when Prism::ConstantReadNode then arg.name.to_s
+                   when Prism::ConstantPathNode then arg.slice.delete_prefix("::")
+                   end
+            names << name if name
+          end
+        end
+        node.child_nodes.compact.each { |child| collect_includes(child, names) }
+      end
+
+      def qualified_type_from_nesting(nesting)
+        return nil unless nesting
+        parts = nesting
+          .select { |n| n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
+          .map { |n| n.constant_path.slice.delete_prefix("::") }
+        parts.empty? ? nil : parts.join("::")
+      end
+
       def serve_constant_hover(type)
         return unless @doc_extractor
 
@@ -90,5 +193,64 @@ module RubyLsp
         "#{rbi}\n\n---\n\n#{doc}"
       end
     end
+
+    # Determines whether a local variable is a method parameter, block
+    # parameter, or a plain local variable assignment.
+    class LocalVarKindFinder < Prism::Visitor
+      def initialize(var_name, before_line)
+        @var_name    = var_name
+        @before_line = before_line
+        @candidates  = []
+        @context     = []
+      end
+
+      def kind
+        @candidates.last&.last
+      end
+
+      def visit_def_node(node)
+        @context.push(:method)
+        super
+        @context.pop
+      end
+
+      def visit_block_node(node)
+        @context.push(:block)
+        super
+        @context.pop
+      end
+
+      def visit_lambda_node(node)
+        @context.push(:block)
+        super
+        @context.pop
+      end
+
+      def visit_local_variable_write_node(node)          = record(node, :local_var) || super
+      def visit_local_variable_operator_write_node(node) = record(node, :local_var) || super
+      def visit_local_variable_or_write_node(node)       = record(node, :local_var) || super
+      def visit_local_variable_and_write_node(node)      = record(node, :local_var) || super
+
+      def visit_required_parameter_node(node)         = record_param(node) || super
+      def visit_optional_parameter_node(node)         = record_param(node) || super
+      def visit_rest_parameter_node(node)             = record_param(node) || super
+      def visit_keyword_rest_parameter_node(node)     = record_param(node) || super
+      def visit_block_parameter_node(node)            = record_param(node) || super
+      def visit_required_keyword_parameter_node(node) = record_param(node) || super
+      def visit_optional_keyword_parameter_node(node) = record_param(node) || super
+
+      private
+
+      def record_param(node)
+        kind = @context.last == :block ? :block_param : :method_param
+        record(node, kind)
+      end
+
+      def record(node, kind)
+        return unless node.name.to_s == @var_name
+        line_no = node.location.start_line
+        @candidates << [line_no, kind] if line_no <= @before_line
+      end
+    end
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pink_spoon
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Jānis Harbs
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-02 00:00:00.000000000 Z
+date: 2026-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -39,6 +40,7 @@ dependencies:
         version: '0.22'
 description: Augments ruby-lsp hover and go-to-definition with type information from
   sorbet/rbi/**/*.rbi. Drop it in your Gemfile and it just works.
+email:
 executables:
 - pink-spoon
 extensions: []
@@ -58,8 +60,10 @@ files:
 - lib/ruby_lsp/pink_spoon/completion_listener.rb
 - lib/ruby_lsp/pink_spoon/definition_listener.rb
 - lib/ruby_lsp/pink_spoon/hover_listener.rb
+homepage:
 licenses: []
 metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -74,7 +78,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: 'ruby-lsp addon: resolves types from Sorbet RBI files'
 test_files: []