solargraph 0.51.2 → 0.54.2

data/lib/solargraph/api_map/store.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
-require 'set'
 
 module Solargraph
   class ApiMap
+    # Queryable collection of Pins representing a Workspace, gems and the Ruby
+    # core.
+    #
     class Store
-      # @return [Enumerable<Solargraph::Pin::Base>]
+      # @return [Array<Solargraph::Pin::Base>]
       attr_reader :pins
 
       # @param pins [Enumerable<Solargraph::Pin::Base>]
@@ -26,7 +28,7 @@ module Solargraph
       # @param fqns [String]
       # @param scope [Symbol]
       # @param visibility [Array<Symbol>]
-      # @return [Enumerable<Solargraph::Pin::Base>]
+      # @return [Enumerable<Solargraph::Pin::Method>]
       def get_methods fqns, scope: :instance, visibility: [:public]
         namespace_children(fqns).select do |pin|
           pin.is_a?(Pin::Method) && pin.scope == scope && visibility.include?(pin.visibility)
@@ -36,6 +38,7 @@ module Solargraph
       # @param fqns [String]
       # @return [String, nil]
       def get_superclass fqns
+        raise "Do not prefix fully qualified namespaces with '::' - #{fqns.inspect}" if fqns.start_with?('::')
         return superclass_references[fqns].first if superclass_references.key?(fqns)
         return 'Object' if fqns != 'BasicObject' && namespace_exists?(fqns)
         return 'Object' if fqns == 'Boolean'
@@ -61,11 +64,15 @@ module Solargraph
       end
 
       # @param path [String]
-      # @return [Enumerable<Solargraph::Pin::Base>]
+      # @return [Array<Solargraph::Pin::Base>]
       def get_path_pins path
         path_pin_hash[path] || []
       end
 
+      def cacheable_pins
+        @cacheable_pins ||= pins_by_class(Pin::Namespace) + pins_by_class(Pin::Constant) + pins_by_class(Pin::Method) + pins_by_class(Pin::Reference)
+      end
+
       # @param fqns [String]
       # @param scope [Symbol] :class or :instance
       # @return [Enumerable<Solargraph::Pin::Base>]
@@ -117,7 +124,7 @@ module Solargraph
         result
       end
 
-      # @return [Hash]
+      # @return [Hash{String => YARD::Tags::MacroDirective}]
       def named_macros
         @named_macros ||= begin
           result = {}
@@ -141,14 +148,15 @@ module Solargraph
         to_s
       end
 
-      # @param klass [Class]
-      # @return [Enumerable<Solargraph::Pin::Base>]
+      # @generic T
+      # @param klass [Class<T>]
+      # @return [Set<T>]
       def pins_by_class klass
-        @pin_select_cache[klass] ||= @pin_class_hash.each_with_object(Set.new) { |(key, o), n| n.merge(o) if key <= klass }
+        # @type [Set<Solargraph::Pin::Base>]
+        s = Set.new
+        @pin_select_cache[klass] ||= @pin_class_hash.each_with_object(s) { |(key, o), n| n.merge(o) if key <= klass }
       end
 
-      private
-
       # @param fqns [String]
       # @return [Array<Solargraph::Pin::Namespace>]
       def fqns_pins fqns
@@ -164,6 +172,9 @@ module Solargraph
         fqns_pins_map[[base, name]]
       end
 
+      private
+
+      # @return [Hash{::Array(String, String) => ::Array<Pin::Namespace>}]
       def fqns_pins_map
         @fqns_pins_map ||= Hash.new do |h, (base, name)|
           value = namespace_children(base).select { |pin| pin.name == name && pin.is_a?(Pin::Namespace) }
@@ -176,18 +187,22 @@ module Solargraph
         pins_by_class(Pin::Symbol)
       end
 
+      # @return [Hash{String => Array<String>}]
       def superclass_references
         @superclass_references ||= {}
       end
 
+      # @return [Hash{String => Array<String>}]
       def include_references
         @include_references ||= {}
       end
 
+      # @return [Hash{String => Array<String>}]
       def prepend_references
         @prepend_references ||= {}
       end
 
+      # @return [Hash{String => Array<String>}]
       def extend_references
         @extend_references ||= {}
       end
@@ -198,31 +213,58 @@ module Solargraph
         namespace_map[name] || []
       end
 
-      # @return [Hash]
+      # @return [Hash{String => Enumerable<Pin::Base>}
       def namespace_map
         @namespace_map ||= {}
       end
 
+      # @return [Enumerable<Pin::InstanceVariable>]
       def all_instance_variables
         pins_by_class(Pin::InstanceVariable)
       end
 
+      # @return [Hash{String => Array<Pin::Base>}]
       def path_pin_hash
         @path_pin_hash ||= {}
       end
 
+      # Add references to a map
+      #
+      # @param h [Hash{String => Pin:Base}]
+      # @param reference_pin [Pin::Reference]
+      #
+      # @return [void]
+      def store_parametric_reference(h, reference_pin)
+        referenced_ns = reference_pin.name
+        referenced_tag_params = reference_pin.generic_values
+        referenced_tag = referenced_ns +
+                         if referenced_tag_params && referenced_tag_params.length > 0
+                           "<" + referenced_tag_params.join(', ') + ">"
+                         else
+                           ''
+                         end
+        referencing_ns = reference_pin.namespace
+        h[referencing_ns] ||= []
+        h[referencing_ns].push referenced_tag
+      end
+
       # @return [void]
       def index
         set = pins.to_set
         @pin_class_hash = set.classify(&:class).transform_values(&:to_a)
+        # @type [Hash{Class => ::Array<Solargraph::Pin::Base>}]
         @pin_select_cache = {}
         @namespace_map = set.classify(&:namespace)
         @path_pin_hash = set.classify(&:path)
         @namespaces = @path_pin_hash.keys.compact.to_set
         pins_by_class(Pin::Reference::Include).each do |pin|
-          include_references[pin.namespace] ||= []
-          include_references[pin.namespace].push pin.name
+          store_parametric_reference(include_references, pin)
         end
+        # @todo move the rest of these reference pins over to use
+        #   generic types, adding rbs_map/conversions.rb code to
+        #   populate type parameters and adding related specs ensuring
+        #   the generics get resolved, along with any api_map.rb
+        #   changes needed in
         pins_by_class(Pin::Reference::Prepend).each do |pin|
           prepend_references[pin.namespace] ||= []
           prepend_references[pin.namespace].push pin.name
@@ -242,8 +284,8 @@ module Solargraph
             get_path_pins(pin.path.sub(/#initialize/, '.new')).first
           end
           (ovr.tags.map(&:tag_name) + ovr.delete).uniq.each do |tag|
-            pin.docstring.delete_tags tag.to_sym
-            new_pin.docstring.delete_tags tag.to_sym if new_pin
+            pin.docstring.delete_tags tag
+            new_pin.docstring.delete_tags tag if new_pin
           end
           ovr.tags.each do |tag|
             pin.docstring.add_tag(tag)
@@ -256,6 +298,9 @@ module Solargraph
         end
       end
 
+      # @param pin [Pin::Base]
+      # @param tag [String]
+      # @return [void]
       def redefine_return_type pin, tag
         return unless pin && tag.tag_name == 'return'
         pin.instance_variable_set(:@return_type, ComplexType.try_parse(tag.type))