pink_spoon 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a1dfe02635dfec7fd176f0727ddbf7feff1a23e17ef63fdcee94c283a4e008c
-  data.tar.gz: 355c66c3af0e1cb8169d2b3b2887f161558376578a9b009bca577943d536e460
+  metadata.gz: 9b276ba7405e08362bb430d60c37fc1620923b76c64da8484d08108ac6206e18
+  data.tar.gz: 31f275f9b72e231be93b8d9f9377496bd507b2e40d7dd1c6eb6c85eda80855d5
 SHA512:
-  metadata.gz: f9682658394a75acd7987bbe67df72a15041a81fe47cb8d560df327410d05b62dc421808341c8f7337d84b084b331d197dab0588d86ffdc6d4b5184cf44fe869
-  data.tar.gz: a5738766fbfe3171f40148117075fa5379a5aa25893387ad43db668558f0e6b2e1786164d4b7fd6077f6352df4242da1abb447191b7672ee926bd51327afe8dd
+  metadata.gz: c8ba5f82e91947b993ae5784281518a2dc2c2685c2ecb6fd931eb85e56ae5342081d47457a9f31ce35b8ef2df4905f4cabd50974246004c443bea8af98b9b19c
+  data.tar.gz: 1dfcdad69156b586eebdaa38f4d5aba482c43f8cb3cc1f5cb906ff6e7727cdc02132d909003f05a9ac3ce557ddc06538bd0549ae16ce14b580b573df7bf9ea3e

data/lib/pink_spoon/constant_resolver.rb

@@ -18,6 +18,24 @@ module PinkSpoon
   class ConstantResolver
     PASSTHROUGH_METHODS = %w[freeze dup clone tap then yield_self].freeze
 
+    # These always return String regardless of receiver type.
+    UNIVERSAL_STRING_METHODS = %w[to_s to_str inspect].freeze
+
+    # String methods that return String when called on a String receiver.
+    # Used as a fallback when no RBI data is available for the core library.
+    STRING_SELF_RETURNING_METHODS = %w[
+      tr tr_s encode force_encoding b
+      gsub sub gsub! sub!
+      strip lstrip rstrip strip! lstrip! rstrip!
+      chomp chop chomp! chop!
+      upcase downcase swapcase capitalize
+      upcase! downcase! swapcase! capitalize!
+      reverse reverse! squeeze delete scrub
+      unicode_normalize unicode_normalize!
+      replace insert prepend center ljust rjust
+      slice [] + * %
+    ].freeze
+
     RSPEC_EXAMPLE_GROUP_METHODS = %w[
       it example specify
       context describe
@@ -250,11 +268,19 @@ module PinkSpoon
 
     def follow_chain(type, method_name)
       return type if PASSTHROUGH_METHODS.include?(method_name)
+      return "String" if UNIVERSAL_STRING_METHODS.include?(method_name)
       return nil unless type
 
       clean = unwrap_sorbet_wrapper(type)
-      ret   = @rbi_index.return_type_for(clean, method_name)&.delete_prefix("::")
-      ret ? unwrap_sorbet_wrapper(ret) : nil
+      # Strip generic parameters before RBI lookup: T::Array[Account] → T::Array
+      base  = clean.sub(/\[.*\]\z/, "")
+      ret   = @rbi_index.return_type_for(base, method_name)&.delete_prefix("::")
+      return unwrap_sorbet_wrapper(ret) if ret
+
+      # Fall back to known String method return types when RBI data is absent.
+      return base if base == "String" && STRING_SELF_RETURNING_METHODS.include?(method_name)
+
+      nil
     end
 
     def unwrap_sorbet_wrapper(type)

data/lib/pink_spoon/doc_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "open3"
+
 module PinkSpoon
   # Fetches YARD/RDoc comments from installed gem source files for a given
   # type + method. Handles both regular `def` and DSL-style definitions like
@@ -81,6 +83,22 @@ module PinkSpoon
       nil
     end
 
+    # Returns hover markdown for a known file+line (used as fallback when
+    # find_constant_location cannot locate the constant via gem-hint scanning).
+    def extract_for_location(loc)
+      return nil unless loc
+
+      raw = read_comments(loc[:file], loc[:line])
+      if raw.empty?
+        decl = declaration_line(loc[:file], loc[:line])
+        decl ? "```ruby\n#{decl}\n```" : nil
+      else
+        render(raw)
+      end
+    rescue
+      nil
+    end
+
     # Returns { file: absolute_path, line: integer } or nil.
     def find_source(type, method_name)
       cache_key = "loc:#{type}##{method_name}"
@@ -101,6 +119,8 @@ module PinkSpoon
         if loc
           raw = read_comments(loc[:file], loc[:line])
           raw.empty? ? nil : render(raw)
+        else
+          extract_via_ri(type, method_name)
         end
       end
     rescue
@@ -114,45 +134,52 @@ module PinkSpoon
       name    = parts.last
       hint    = parts.first.to_s.downcase
       escaped = Regexp.escape(name)
+      target  = parts.join("::")
 
-      # Matches class/module definitions AND constant value assignments.
-      # e.g.  class Formatters, module Core, SOME_CONST = "value"
-      pattern = /^\s*(?:(?:class|module)\s+(?:\w+::)*#{escaped}\b|#{escaped}\s*=)/
-
+      # Gem files: fast single-line regex scan.
+      # Gem source is usually well-structured (one class per file, inline namespaces),
+      # so the regex false-positive risk is low and parsing every gem file is too slow.
+      gem_pattern = /^\s*(?:(?:class|module)\s+(?:\w+::)*#{escaped}\b|#{escaped}\s*=)/
       gem_dirs_for(hint).each do |gem_dir|
         Dir.glob("#{gem_dir}/lib/**/*.rb").sort.each do |file|
-          line = first_line_matching(file, pattern)
+          line = first_line_matching(file, gem_pattern)
           return { file: file, line: line } if line
         end
       end
 
-      # 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).
+      # Project files: parse with Prism so we track the fully-qualified name.
+      # A regex on individual lines cannot tell whether `module Restrictions` is
+      # top-level or nested inside `module Routes { module Restrictions }` — only
+      # a full parse can distinguish them.
+      prefilter = /\b#{escaped}\b/
+
       %w[lib app spec test].each do |subdir|
         dir = File.join(@root_path, subdir)
         next unless File.directory?(dir)
 
         if parts.size > 1
+          # Zeitwerk conventional path: try the direct file first.
           candidate = File.join(dir, *parts.map { |p| underscore(p) }) + ".rb"
           if File.exist?(candidate)
-            line = first_line_matching(candidate, pattern)
+            line = exact_constant_line(candidate, target)
             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
+          # Glob fallback with progressive namespace prefix shortening.
+          # Full prefix first preserves false-positive safety for deep hierarchies.
+          all_files = Dir.glob("#{dir}/**/*.rb").sort
+          (parts.size - 1).downto(1) do |depth|
+            intermediate = parts[0...depth].map { |p| underscore(p) }.join("/")
+            all_files.each do |file|
+              next unless file.include?("/#{intermediate}/") || file.end_with?("/#{intermediate}.rb")
+              next unless first_line_matching(file, prefilter)
+              line = exact_constant_line(file, target)
+              return { file: file, line: line } if line
+            end
           end
         else
           Dir.glob("#{dir}/**/*.rb").sort.each do |file|
-            line = first_line_matching(file, pattern)
+            next unless first_line_matching(file, prefilter)
+            line = exact_constant_line(file, target)
             return { file: file, line: line } if line
           end
         end
@@ -161,6 +188,21 @@ module PinkSpoon
       nil
     end
 
+    # Returns the line number where +target+ (fully-qualified, e.g. "Restrictions"
+    # or "Routes::Restrictions") is defined in +file+, or nil if not found.
+    # Parses the file with Prism and tracks the scope stack so that a nested
+    # `module Restrictions` inside `module Routes` is NOT mistaken for the
+    # top-level `Restrictions` module.
+    def exact_constant_line(file, target)
+      source = File.read(file)
+      result = Prism.parse(source)
+      finder = ConstantDefinitionFinder.new(target)
+      finder.visit(result.value)
+      finder.line
+    rescue
+      nil
+    end
+
     def underscore(str)
       str.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
@@ -224,7 +266,11 @@ module PinkSpoon
       nil
     end
 
+    DIRECTIVE_RE = /^#\s*(?:rubocop:|frozen_string_literal:|typed:|encoding:|source:\/\/)/.freeze
+
     # Reads the contiguous comment block immediately above line_no (1-based).
+    # Stops at non-comment lines and at directive comments (rubocop, sorbet typed,
+    # frozen_string_literal, encoding, source://) which are never documentation.
     def read_comments(file, line_no)
       lines = File.readlines(file, chomp: true)
       block = []
@@ -233,6 +279,7 @@ module PinkSpoon
       while i >= 0
         stripped = lines[i].strip
         break unless stripped.start_with?("#")
+        break if stripped.match?(DIRECTIVE_RE)
         block.unshift(stripped.sub(/^#[ \t]?/, ""))
         i -= 1
       end
@@ -250,6 +297,20 @@ module PinkSpoon
       []
     end
 
+    # Fetches documentation for core Ruby types (String, Integer, etc.) via the
+    # `ri` tool. Used when `find_location` returns nil because the type has no
+    # gem source (built-in C extension methods like String#tr, String#encode).
+    def extract_via_ri(type, method_name)
+      out, _err, status = Open3.capture3("ri", "--no-pager", "--format=markdown", "#{type}##{method_name}")
+      return nil unless status.success?
+      content = out.strip
+      return nil if content.empty? || content.include?("Nothing known about")
+      # Strip the "# Type#method" title — the hover panel renders its own header.
+      content.sub(/\A#[^\n]+\n+/, "").strip.then { |s| s.empty? ? nil : s }
+    rescue
+      nil
+    end
+
     YARD_TAG_RE = /^@(\w+)(?:\s+(.*))?$/.freeze
 
     # Converts a raw comment array into a markdown string.
@@ -289,5 +350,42 @@ module PinkSpoon
       result = output.join("\n").strip
       result.empty? ? nil : result
     end
+
+    # Walks a Prism AST and records the line where +target+ is defined.
+    # Tracks the full qualified name via a scope stack, so a nested
+    # `module Restrictions` inside `module Routes` only matches
+    # "Routes::Restrictions", never bare "Restrictions".
+    class ConstantDefinitionFinder < Prism::Visitor
+      attr_reader :line
+
+      def initialize(target)
+        @target = target.delete_prefix("::")
+        @scope  = []
+        @line   = nil
+      end
+
+      def visit_module_node(node)
+        push_scope(node.constant_path.slice.delete_prefix("::"), node.location.start_line) { super }
+      end
+
+      def visit_class_node(node)
+        push_scope(node.constant_path.slice.delete_prefix("::"), node.location.start_line) { super }
+      end
+
+      def visit_constant_write_node(node)
+        fqn = (@scope + [node.name.to_s]).join("::")
+        @line ||= node.location.start_line if fqn == @target
+        super
+      end
+
+      private
+
+      def push_scope(name, start_line)
+        @scope.push(name)
+        @line ||= start_line if @scope.join("::") == @target
+        yield
+        @scope.pop
+      end
+    end
   end
 end

data/lib/pink_spoon/rbi_index.rb

@@ -332,6 +332,15 @@ module PinkSpoon
         super
       end
 
+      def visit_constant_write_node(node)
+        source_comment = source_comment_at(node.location.start_line)
+        if source_comment
+          full_name = (@scope + [node.name.to_s]).join("::")
+          @const_sources[full_name] = source_comment
+        end
+        super
+      end
+
       def visit_def_node(node)
         method_name  = node.name.to_s
         sig          = @pending_sig

data/lib/pink_spoon/version.rb

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

data/lib/ruby_lsp/pink_spoon/completion_listener.rb

@@ -36,6 +36,10 @@ module RubyLsp
       INSERT_FORMAT_SNIPPET    = 2
       INSERT_FORMAT_PLAINTEXT  = 1
 
+      # Methods universal to all Ruby objects — excluded from core-type completions
+      # so we don't flood the list with nil?, frozen?, object_id, etc.
+      OBJECT_METHODS = Object.public_instance_methods.freeze
+
       def initialize(response_builder, node_context, dispatcher, uri, resolver, rbi_index)
         @response_builder = response_builder
         @node_context     = node_context
@@ -81,7 +85,10 @@ module RubyLsp
 
         range = loc_to_range(node.message_loc || node.location)
 
-        @rbi_index.methods_for(type).each do |method_name, sig_or_def|
+        rbi_methods = @rbi_index.methods_for(type)
+        methods = rbi_methods.empty? ? core_ruby_methods_for(type) : rbi_methods
+
+        methods.each do |method_name, sig_or_def|
           @response_builder << Interface::CompletionItem.new(
             label:              method_name,
             filter_text:        method_name,
@@ -188,6 +195,18 @@ module RubyLsp
         end
       end
 
+      # Returns method names for core Ruby types (String, Integer, Array, etc.)
+      # via reflection when the RBI index has no entries for the type.
+      # Excludes Object/Kernel/BasicObject methods to keep the list focused.
+      def core_ruby_methods_for(type)
+        klass = Object.const_get(type)
+        return {} unless klass.is_a?(Module)
+        (klass.public_instance_methods - OBJECT_METHODS).sort
+          .each_with_object({}) { |m, h| h[m.to_s] = nil }
+      rescue NameError, TypeError
+        {}
+      end
+
       # Converts a Prism location (1-based lines) to an LSP Range (0-based).
       def loc_to_range(loc)
         Interface::Range.new(

data/lib/ruby_lsp/pink_spoon/definition_listener.rb

@@ -83,7 +83,66 @@ module RubyLsp
 
       def on_constant_read_node_enter(node)
         return unless node.equal?(@node_context.node)
-        goto_constant(node.name.to_s)
+
+        bare_name = node.name.to_s
+        nesting   = @node_context.instance_variable_get(:@nesting_nodes)
+
+        # When the constant is the leading segment of a :: path, look up the full
+        # path first. This prevents a same-named ancestor namespace (e.g.
+        # Routes::Restrictions) from winning over the intended top-level one.
+        if (full_path = leading_constant_path(node))
+          lexical_candidates(full_path, nesting).each do |candidate|
+            file_loc = @rbi_index.const_source_for(candidate)
+            # Reject wrong RBI entries — Tapioca can point to the wrong file.
+            if file_loc && @doc_extractor
+              file_loc = nil unless @doc_extractor.exact_constant_line(file_loc[:file], candidate)
+            end
+            file_loc ||= @doc_extractor&.find_constant_source(candidate)
+            next unless file_loc
+
+            # Right file found via the full path. Navigate to where bare_name is
+            # defined within it (the enclosing module, not the child class).
+            line = @doc_extractor&.exact_constant_line(file_loc[:file], bare_name)
+            # Navigate even when bare_name has no separate declaration
+            # (e.g. `class Restrictions::CreditorRestrictor` with no `module Restrictions`).
+            # The RBI verification above already confirmed this is the right file.
+            push_location(file_loc[:file], line || 1)
+            return
+          end
+        end
+
+        # Successor-filter fallback: read the immediate child from the parent
+        # ConstantPathNode directly. This runs whether or not leading_constant_path
+        # succeeded — the parent is always available from @node_context. Candidate
+        # "Routes::Restrictions" is rejected when "Routes::Restrictions::CreditorRestrictor"
+        # doesn't exist; "Restrictions" is accepted because "Restrictions::CreditorRestrictor" does.
+        path_parent = @node_context.parent
+        if path_parent.is_a?(Prism::ConstantPathNode)
+          suffix = path_parent.child.slice.delete_prefix("::") rescue nil
+          if suffix && !suffix.empty?
+            lexical_candidates(bare_name, nesting).each do |candidate|
+              qualified_child = "#{candidate}::#{suffix}"
+              child_loc = @rbi_index.const_source_for(qualified_child)
+              if child_loc && @doc_extractor
+                child_loc = nil unless @doc_extractor.exact_constant_line(child_loc[:file], qualified_child)
+              end
+              child_loc ||= @doc_extractor&.find_constant_source(qualified_child)
+              next unless child_loc
+
+              location = @rbi_index.const_source_for(candidate)
+              if location && @doc_extractor
+                location = nil unless @doc_extractor.exact_constant_line(location[:file], candidate)
+              end
+              location ||= @doc_extractor&.find_constant_source(candidate)
+              next unless location
+
+              push_location(location[:file], location[:line])
+              return
+            end
+          end
+        end
+
+        goto_constant(bare_name)
       end
 
       def on_constant_path_node_enter(node)
@@ -293,6 +352,15 @@ module RubyLsp
 
         lexical_candidates(bare_name, nesting).each do |candidate|
           location = @rbi_index.const_source_for(candidate)
+
+          # Verify the RBI source comment actually defines this constant.
+          # Tapioca can write a wrong path (e.g. Routes::Restrictions when the
+          # real constant is top-level Restrictions). Reject the RBI result when
+          # the target file does not define the expected fully-qualified name.
+          if location && @doc_extractor
+            location = nil unless @doc_extractor.exact_constant_line(location[:file], candidate)
+          end
+
           location ||= @doc_extractor&.find_constant_source(candidate)
           next unless location
 
@@ -355,6 +423,25 @@ module RubyLsp
         nil
       end
 
+      # Returns the full constant path string when +node+ is the leading
+      # constant of a ConstantPathNode (e.g. returns "Restrictions::CreditorRestrictor"
+      # when +node+ is the `Restrictions` ConstantReadNode in that expression).
+      # Returns nil when the constant stands alone (not part of a :: path).
+      #
+      # ruby-lsp sets NodeContext#parent to the immediate AST parent of the cursor
+      # node. For `Restrictions` in `Restrictions::CreditorRestrictor`, that parent
+      # is the ConstantPathNode. We confirm our node is the left-hand side by
+      # checking that the path's own .parent field (Prism's LHS of ::) is our node.
+      def leading_constant_path(node)
+        path_node = @node_context.parent
+        return nil unless path_node.is_a?(Prism::ConstantPathNode)
+        return nil unless path_node.parent.equal?(node)
+
+        path_node.slice.delete_prefix("::")
+      rescue
+        nil
+      end
+
       def push_location(file, line)
         target_uri = "file://#{file}"
 

data/lib/ruby_lsp/pink_spoon/hover_listener.rb

@@ -180,6 +180,12 @@ module RubyLsp
         return unless @doc_extractor
 
         doc = @doc_extractor.extract_for_constant(type)
+
+        if doc.nil?
+          loc = @rbi_index.const_source_for(type)
+          doc = @doc_extractor.extract_for_location(loc) if loc
+        end
+
         return unless doc
 
         @response_builder.push("**`#{type}`**\n\n#{doc}", category: :documentation)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pink_spoon
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Jānis Harbs
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-13 00:00:00.000000000 Z
+date: 2026-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -40,7 +39,6 @@ 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: []
@@ -60,10 +58,8 @@ 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
@@ -78,8 +74,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: 'ruby-lsp addon: resolves types from Sorbet RBI files'
 test_files: []