pink_spoon 0.1.0

data/lib/pink_spoon/doc_extractor.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+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
+  # `define_example_method :it` or `define_example_group_method :describe`.
+  #
+  # Gem lookup uses the downcased first namespace component so that
+  # `RSpec::Core::ExampleGroup` correctly finds the `rspec-core` gem
+  # rather than trying the broken underscore form `r_spec`.
+  class DocExtractor
+    def initialize(root_path)
+      @root_path = root_path
+      @cache     = {}
+    end
+
+    # Returns { file:, line: } for the first assignment of ivar_name (@foo = ...)
+    # in any source file belonging to the given type's gem or project.
+    def find_ivar_in_type(type, ivar_name)
+      cache_key = "ivar:#{type}##{ivar_name}"
+      return @cache[cache_key] if @cache.key?(cache_key)
+
+      @cache[cache_key] = begin
+        escaped = Regexp.escape(ivar_name)
+        pattern = /#{escaped}\s*=/
+        hint    = type.split("::").first.to_s.downcase
+
+        gem_dirs_for(hint).each do |gem_dir|
+          Dir.glob("#{gem_dir}/lib/**/*.rb").sort.each do |file|
+            line = first_line_matching(file, pattern)
+            return { file: file, line: line } if line
+          end
+        end
+
+        %w[lib app].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
+          end
+        end
+
+        nil
+      end
+    rescue
+      nil
+    end
+
+    # Returns { file: absolute_path, line: integer } for a class/module definition.
+    def find_constant_source(type)
+      cache_key = "const_loc:#{type}"
+      return @cache[cache_key] if @cache.key?(cache_key)
+
+      @cache[cache_key] = find_constant_location(type)
+    rescue
+      nil
+    end
+
+    # Returns markdown docs for a class/module/constant.
+    # When there is a YARD comment above the definition, renders it.
+    # When there is no comment, falls back to showing the declaration line itself.
+    def extract_for_constant(type)
+      cache_key = "const_doc:#{type}"
+      return @cache[cache_key] if @cache.key?(cache_key)
+
+      @cache[cache_key] = begin
+        loc = find_constant_location(type)
+        if 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
+        end
+      end
+    rescue
+      nil
+    end
+
+    # Returns { file: absolute_path, line: integer } or nil.
+    def find_source(type, method_name)
+      cache_key = "loc:#{type}##{method_name}"
+      return @cache[cache_key] if @cache.key?(cache_key)
+
+      @cache[cache_key] = find_location(type, method_name)
+    rescue
+      nil
+    end
+
+    # Returns a markdown string with the doc comment, or nil.
+    def extract(type, method_name)
+      cache_key = "doc:#{type}##{method_name}"
+      return @cache[cache_key] if @cache.key?(cache_key)
+
+      @cache[cache_key] = begin
+        loc = find_location(type, method_name)
+        if loc
+          raw = read_comments(loc[:file], loc[:line])
+          raw.empty? ? nil : render(raw)
+        end
+      end
+    rescue
+      nil
+    end
+
+    private
+
+    def find_constant_location(type)
+      parts   = type.delete_prefix("::").split("::")
+      name    = parts.last
+      hint    = parts.first.to_s.downcase
+      escaped = Regexp.escape(name)
+
+      # 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_dirs_for(hint).each do |gem_dir|
+        Dir.glob("#{gem_dir}/lib/**/*.rb").sort.each do |file|
+          line = first_line_matching(file, pattern)
+          return { file: file, line: line } if line
+        end
+      end
+
+      # Fall back to project source (lib/, app/).
+      %w[lib app].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
+        end
+      end
+
+      nil
+    end
+
+    def first_line_matching(file, pattern)
+      File.foreach(file).with_index(1) { |l, i| return i if l.match?(pattern) }
+      nil
+    rescue
+      nil
+    end
+
+    def declaration_line(file, line_no)
+      line = File.readlines(file, chomp: true)[line_no - 1]&.strip
+      return nil if line.nil? || line.empty?
+      line.length > 120 ? "#{line[0..116]}..." : line
+    rescue
+      nil
+    end
+
+    def find_location(type, method_name)
+      gem_hint = type.split("::").first.to_s.downcase
+
+      gem_dirs_for(gem_hint).each do |gem_dir|
+        Dir.glob("#{gem_dir}/lib/**/*.rb").sort.each do |file|
+          line_no = find_method_line(file, method_name)
+          return { file: file, line: line_no } if line_no
+        end
+      end
+
+      # Fall back to project source (lib/, app/) for project-defined methods.
+      %w[lib app].each do |subdir|
+        dir = File.join(@root_path, subdir)
+        next unless File.directory?(dir)
+        Dir.glob("#{dir}/**/*.rb").sort.each do |file|
+          line_no = find_method_line(file, method_name)
+          return { file: file, line: line_no } if line_no
+        end
+      end
+
+      nil
+    end
+
+    # Searches a file for a method definition by name.
+    # Matches both regular defs and DSL-style macro calls:
+    #   def method_name / def self.method_name
+    #   some_macro :method_name  (e.g. define_example_method :it)
+    def find_method_line(file, method_name)
+      escaped = Regexp.escape(method_name)
+      def_re  = /\bdef\s+(?:self\.)?#{escaped}(?=[\s\(;]|\z)/
+      dsl_re  = /\b\w[\w!?]*\s+:#{escaped}\s*(?:#.*)?$/
+
+      File.foreach(file).with_index(1) do |line, i|
+        stripped = line.strip
+        return i if stripped.match?(def_re) || stripped.match?(dsl_re)
+      end
+
+      nil
+    rescue
+      nil
+    end
+
+    # Reads the contiguous comment block immediately above line_no (1-based).
+    def read_comments(file, line_no)
+      lines = File.readlines(file, chomp: true)
+      block = []
+      i     = line_no - 2  # one line above the target, 0-indexed
+
+      while i >= 0
+        stripped = lines[i].strip
+        break unless stripped.start_with?("#")
+        block.unshift(stripped.sub(/^#[ \t]?/, ""))
+        i -= 1
+      end
+
+      block
+    end
+
+    def gem_dirs_for(hint)
+      return [] if hint.empty?
+
+      Gem::Specification.each.filter_map do |spec|
+        spec.gem_dir if spec.name.start_with?(hint) || spec.name.include?(hint)
+      end
+    rescue
+      []
+    end
+
+    YARD_TAG_RE = /^@(\w+)(?:\s+(.*))?$/.freeze
+
+    # Converts a raw comment array into a markdown string.
+    def render(lines)
+      output = []
+
+      lines.each do |line|
+        if (m = line.match(YARD_TAG_RE))
+          tag, rest = m[1], m[2].to_s.strip
+          case tag
+          when "param"
+            name, desc = rest.split(/\s+/, 2)
+            output << "**`#{name}`** — #{desc}"
+          when "return"
+            output << "**Returns:** #{rest}"
+          when "see"
+            output << "**See Also:** `#{rest}`"
+          when "example"
+            label = rest.empty? ? "" : " #{rest}"
+            output << "**Example:**#{label}"
+          when "raise", "raises"
+            output << "**Raises:** `#{rest}`"
+          when "deprecated"
+            output << "**Deprecated.** #{rest}"
+          when "note"
+            output << "> #{rest}"
+          when "api"
+            nil
+          else
+            output << "_@#{tag}_ #{rest}".strip
+          end
+        else
+          output << line
+        end
+      end
+
+      result = output.join("\n").strip
+      result.empty? ? nil : result
+    end
+  end
+end

data/lib/pink_spoon/rbi_index.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module PinkSpoon
+  # Parses every sorbet/rbi/**/*.rbi file in the project and builds:
+  #
+  #   @sigs[type][method]   → sig string
+  #   @types[type][method]  → return type string
+  #   @mixins[type]         → [mixin_type, ...] from extend/include calls
+  #
+  # Type keys are fully qualified with "::" prefix normalised away.
+  # Lookups walk the mixin chain so Hesiod.register_gauge resolves even
+  # 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] = {} }
+      build
+    end
+
+    # Returns the sig string for type#method, or nil.
+    # Follows extend/include chain when not found directly.
+    def signature_for(type, method_name, _seen = [])
+      t = normalise(type)
+      return nil if _seen.include?(t)
+
+      direct = @sigs[t][method_name.to_s]
+      return direct if direct
+
+      @mixins[t].each do |mixin|
+        result = signature_for(mixin, method_name, _seen + [t])
+        return result if result
+      end
+
+      nil
+    end
+
+    # Returns the return-type string for type#method, or nil.
+    # Follows extend/include chain when not found directly.
+    def return_type_for(type, method_name, _seen = [])
+      t = normalise(type)
+      return nil if _seen.include?(t)
+
+      direct = @types[t][method_name.to_s]
+      return direct if direct
+
+      @mixins[t].each do |mixin|
+        result = return_type_for(mixin, method_name, _seen + [t])
+        return result if result
+      end
+
+      nil
+    end
+
+    # Returns markdown hover content for type#method, or nil if we know
+    # nothing about the method at all. Prefers the Sorbet sig; falls back
+    # to the plain def line so callers always get something useful.
+    def hover_content_for(type, method_name, _seen = [])
+      t = normalise(type)
+      return nil if _seen.include?(t)
+
+      sig      = @sigs[t][method_name.to_s]
+      def_line = @defs[t][method_name.to_s]
+      source   = @sources[t][method_name.to_s]
+
+      if sig || def_line
+        parts = []
+        parts << source   if source
+        parts << sig      if sig
+        parts << def_line if def_line
+        body = parts.join("\n")
+        return "**`#{t}##{method_name}`** _(via RBI)_\n\n```ruby\n#{body}\n```"
+      end
+
+      @mixins[t].each do |mixin|
+        result = hover_content_for(mixin, method_name, _seen + [t])
+        return result if result
+      end
+
+      nil
+    end
+
+    # Returns { file:, line: } for the .rbi definition of type#method, or nil.
+    # Follows extend/include/superclass chain when not found directly.
+    def rbi_location_for(type, method_name, _seen = [])
+      t = normalise(type)
+      return nil if _seen.include?(t)
+
+      loc = @locations[t][method_name.to_s]
+      return loc if loc
+
+      @mixins[t].each do |mixin|
+        result = rbi_location_for(mixin, method_name, _seen + [t])
+        return result if result
+      end
+
+      nil
+    end
+
+    # Returns the direct parent/mixin types for the given type (one level, no chain walk).
+    def mixins_for(type)
+      @mixins[normalise(type)].dup
+    end
+
+    # Returns { param_name => type_string } for type#method, or nil.
+    # Follows the mixin chain.
+    def params_for(type, method_name, _seen = [])
+      t = normalise(type)
+      return nil if _seen.include?(t)
+
+      direct = @params[t][method_name.to_s]
+      return direct if direct && !direct.empty?
+
+      @mixins[t].each do |mixin|
+        result = params_for(mixin, method_name, _seen + [t])
+        return result if result && !result.empty?
+      end
+
+      nil
+    end
+
+    # Returns { method_name => sig_or_def_line } for a type including all mixins.
+    # Used by the completion listener to enumerate available methods.
+    def methods_for(type, _seen = [])
+      t = normalise(type)
+      return {} if _seen.include?(t)
+
+      result = {}
+      @mixins[t].each do |mixin|
+        result.merge!(methods_for(mixin, _seen + [t]))
+      end
+
+      @defs[t].each do |method, def_line|
+        result[method] = @sigs[t][method] || def_line
+      end
+
+      result
+    end
+
+    # All known types (for debugging / testing).
+    def types = @sigs.keys
+
+    private
+
+    def build
+      rbi_dir = File.join(@root_path, "sorbet", "rbi")
+      return unless File.directory?(rbi_dir)
+
+      Dir.glob("#{rbi_dir}/**/*.rbi").each do |path|
+        parse_file(path)
+      rescue => e
+        $stderr.puts "[pink-spoon] skipping #{path}: #{e.message}"
+      end
+
+      $stderr.puts "[pink-spoon] indexed #{@sigs.values.sum(&:size)} signatures " \
+                   "across #{@sigs.size} types (#{@mixins.size} with mixins)"
+    end
+
+    def parse_file(path)
+      source = File.read(path)
+      result = Prism.parse(source)
+
+      comment_map = {}
+      result.comments.each { |c| comment_map[c.location.start_line] = c.slice }
+
+      visitor = RbiVisitor.new(comment_map)
+      visitor.visit(result.value)
+
+      visitor.entries.each do |entry|
+        type = normalise(entry[:type])
+        @sigs[type][entry[:method]]      = entry[:sig]
+        @types[type][entry[:method]]     = entry[:return_type]
+        @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]
+        @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
+    end
+
+    def normalise(type)
+      type.to_s.delete_prefix("::")
+    end
+
+    # ------------------------------------------------------------------
+    # Prism AST visitor that walks RBI files and extracts:
+    #   - sig+def pairs (entries)
+    #   - extend/include calls (mixins)
+    # ------------------------------------------------------------------
+    class RbiVisitor < Prism::Visitor
+      attr_reader :entries, :mixins
+
+      def initialize(comment_map = {})
+        @entries     = []
+        @mixins      = Hash.new { |h, k| h[k] = [] }
+        @scope       = []
+        @pending_sig = nil
+        @comment_map = comment_map
+      end
+
+      def visit_module_node(node)
+        push_scope(node.constant_path) { super }
+      end
+
+      def visit_class_node(node)
+        push_scope(node.constant_path) do
+          # Record superclass as a parent so method lookups walk the chain.
+          if node.superclass
+            type   = @scope.join("::")
+            parent = const_path_to_string(node.superclass).delete_prefix("::")
+            @mixins[type] << parent unless @mixins[type].include?(parent)
+          end
+          super
+        end
+      end
+
+      def visit_call_node(node)
+        if node.name == :sig && node.receiver.nil?
+          @pending_sig = node.slice
+        elsif (node.name == :extend || node.name == :include) && node.receiver.nil?
+          record_mixins(node)
+        end
+        super
+      end
+
+      def visit_def_node(node)
+        method_name  = node.name.to_s
+        sig          = @pending_sig
+        @pending_sig = nil
+
+        # Build a plain def line even when no Sorbet sig exists.
+        # e.g. "def init_label_set(labels)"
+        params    = node.parameters&.slice
+        def_line  = params ? "def #{method_name}(#{params})" : "def #{method_name}"
+
+        # Check for a "# source://" comment on the line immediately before this def.
+        preceding = @comment_map[node.location.start_line - 1]
+        source    = preceding&.match?(/# source:\/\//) ? preceding : nil
+
+        @entries << {
+          type:        @scope.join("::"),
+          method:      method_name,
+          sig:         sig,
+          def_line:    def_line,
+          return_type: sig ? extract_return_type(sig) : nil,
+          params:      sig ? extract_params(sig) : {},
+          source:      source,
+          line:        node.location.start_line,
+        }
+
+        super
+      end
+
+      private
+
+      def record_mixins(call_node)
+        type = @scope.join("::")
+        return if type.empty?
+
+        call_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
+          @mixins[type] << name if name
+        end
+      end
+
+      def push_scope(const_path, &block)
+        @scope.push(const_path_to_string(const_path))
+        block.call
+        @scope.pop
+      end
+
+      def const_path_to_string(node)
+        return nil if node.nil?
+        case node
+        when Prism::ConstantReadNode  then node.name.to_s
+        when Prism::ConstantPathNode  then [const_path_to_string(node.parent), node.name.to_s].compact.join("::")
+        else node.slice
+        end
+      end
+
+      def extract_return_type(sig)
+        match = sig.match(/returns\(\s*([\w:]+)\s*\)/)
+        match&.[](1)
+      end
+
+      def extract_params(sig)
+        m = sig.match(/params\((.+)\)/m)
+        return {} unless m
+
+        params_str = m[1].gsub(/\s+/, " ").strip
+        result     = {}
+        depth      = 0
+        current    = +""
+
+        params_str.each_char do |c|
+          case c
+          when "(", "[", "<" then depth += 1; current << c
+          when ")", "]", ">" then depth -= 1; current << c
+          when ","
+            if depth == 0
+              store_param(current.strip, result)
+              current = +""
+            else
+              current << c
+            end
+          else
+            current << c
+          end
+        end
+        store_param(current.strip, result) unless current.strip.empty?
+        result
+      end
+
+      def store_param(pair, result)
+        m = pair.match(/^(\w+):\s*(.+)$/)
+        return unless m
+        result[m[1]] = m[2].strip.delete_prefix("::")
+      end
+    end
+  end
+end