solargraph 0.56.0 → 0.58.2

data/lib/solargraph/api_map/constants.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module Solargraph
+  class ApiMap
+    # Methods for handling constants.
+    #
+    class Constants
+      # @param store [Store]
+      def initialize store
+        @store = store
+      end
+
+      # Resolve a name to a fully qualified namespace or constant.
+      #
+      # `Constants#resolve` finds fully qualified (absolute)
+      # namespaces based on relative names and the open gates
+      # (namespaces) provided.  Names must be runtime-visible (erased)
+      # non-literal types, non-duck, non-signature types - e.g.,
+      # TrueClass, NilClass, Integer and Hash instead of true, nil,
+      # 96, or Hash{String => Symbol}
+      #
+      # Note: You may want to be using #qualify.  Notably, #resolve:
+      # - does not handle anything with type parameters
+      # - will not gracefully handle nil, self and Boolean
+      # - will return a constant name instead of following its assignment
+      #
+      # @param name [String] Namespace which may relative and not be rooted.
+      # @param gates [Array<Array<String>, String>] Namespaces to search while resolving the name
+      #
+      # @return [String, nil] fully qualified namespace (i.e., is
+      #   absolute, but will not start with ::)
+      def resolve(name, *gates)
+        return store.get_path_pins(name[2..]).first&.path if name.start_with?('::')
+
+        flat = gates.flatten
+        flat.push '' if flat.empty?
+        if cached_resolve.include? [name, flat]
+          cached_result = cached_resolve[[name, flat]]
+          # don't recurse
+          return nil if cached_result == :in_process
+          return cached_result
+        end
+        resolve_and_cache(name, flat)
+      end
+
+      # Get a fully qualified namespace from a reference pin.
+      #
+      # @param pin [Pin::Reference]
+      # @return [String, nil]
+      def dereference pin
+        qualify_type(pin.type, *pin.reference_gates)&.tag
+      end
+
+      # Collect a list of all constants defined in the specified gates.
+      #
+      # @param gates [Array<Array<String>, String>]
+      # @return [Array<Solargraph::Pin::Namespace, Solargraph::Pin::Constant>]
+      def collect(*gates)
+        flat = gates.flatten
+        cached_collect[flat] || collect_and_cache(flat)
+      end
+
+      # Determine a fully qualified namespace for a given tag
+      # referenced from the specified open gates. This method will
+      # search in each gate until it finds a match for the name.
+      #
+      # @param tag [String, nil] The type to match
+      # @param gates [Array<String>]
+      # @return [String, nil] fully qualified tag
+      def qualify tag, *gates
+        type = ComplexType.try_parse(tag)
+        qualify_type(type, *gates)&.tag
+      end
+
+      # @param type [ComplexType, nil] The type to match
+      # @param gates [Array<String>]
+      #
+      # @return [ComplexType, nil] A new rooted ComplexType
+      def qualify_type type, *gates
+        return nil if type.nil?
+        return type if type.selfy? || type.literal? || type.tag == 'nil' || type.interface? ||
+                       type.tag == 'Boolean'
+
+        gates.push '' unless gates.include?('')
+        fqns = resolve(type.rooted_namespace, *gates)
+        return unless fqns
+        pin = store.get_path_pins(fqns).first
+        if pin.is_a?(Pin::Constant)
+          const = Solargraph::Parser::NodeMethods.unpack_name(pin.assignment)
+          return unless const
+          fqns = resolve(const, *pin.gates)
+        end
+        type.recreate(new_name: fqns, make_rooted: true)
+      end
+
+      # @return [void]
+      def clear
+        [cached_collect, cached_resolve].each(&:clear)
+      end
+
+      private
+
+      # @return [Store]
+      attr_reader :store
+
+      # @param name [String]
+      # @param gates [Array<String>]
+      # @return [String, nil]
+      def resolve_and_cache name, gates
+        cached_resolve[[name, gates]] = :in_process
+        cached_resolve[[name, gates]] = resolve_uncached(name, gates)
+      end
+
+      # @param name [String]
+      # @param gates [Array<String>]
+      # @return [String, nil]
+      def resolve_uncached name, gates
+        resolved = nil
+        base = gates
+        parts = name.split('::')
+        first = nil
+        parts.each.with_index do |nam, idx|
+          resolved, remainder = complex_resolve(nam, base, idx != parts.length - 1)
+          first ||= remainder
+          if resolved
+            base = [resolved]
+          else
+            return resolve(name, first) unless first.empty?
+          end
+        end
+        resolved
+      end
+
+      # @todo I'm not sure of a better way to express the return value in YARD.
+      #   It's a tuple where the first element is a nullable string. Something
+      #   like `Array(String|nil, Array<String>)` would be more accurate.
+      #
+      # @param name [String]
+      # @param gates [Array<String>]
+      # @param internal [Boolean] True if the name is not the last in the namespace
+      # @return [Array(Object, Array<String>)]
+      def complex_resolve name, gates, internal
+        resolved = nil
+        gates.each.with_index do |gate, idx|
+          resolved = simple_resolve(name, gate, internal)
+          return [resolved, gates[(idx + 1)..]] if resolved
+          store.get_ancestor_references(gate).each do |ref|
+            return ref.name.sub(/^::/, '') if ref.name.end_with?("::#{name}") && ref.name.start_with?('::')
+
+            mixin = resolve(ref.name, ref.reference_gates)
+            next unless mixin
+
+            resolved = simple_resolve(name, mixin, internal)
+            return [resolved, gates[(idx + 1)..]] if resolved
+          end
+        end
+        [nil, []]
+      end
+
+      # @param name [String]
+      # @param gate [String]
+      # @param internal [Boolean] True if the name is not the last in the namespace
+      # @return [String, nil]
+      def simple_resolve name, gate, internal
+        here = "#{gate}::#{name}".sub(/^::/, '').sub(/::$/, '')
+        pin = store.get_path_pins(here).first
+        if pin.is_a?(Pin::Constant) && internal
+          const = Solargraph::Parser::NodeMethods.unpack_name(pin.assignment)
+          return unless const
+          resolve(const, pin.gates)
+        else
+          pin&.path
+        end
+      end
+
+      # @param gates [Array<String>]
+      # @return [Array<Solargraph::Pin::Namespace, Solargraph::Pin::Constant>]
+      def collect_and_cache gates
+        skip = Set.new
+        cached_collect[gates] = gates.flat_map do |gate|
+          inner_get_constants(gate, %i[public private], skip)
+        end
+      end
+
+      # @return [Hash{Array(String, Array<String>) => String, :in_process, nil}]
+      def cached_resolve
+        @cached_resolve ||= {}
+      end
+
+      # @return [Hash{Array<String> => Array<Solargraph::Pin::Namespace, Solargraph::Pin::Constant>}]
+      def cached_collect
+        @cached_collect ||= {}
+      end
+
+      # Determine fully qualified namespace for a given namespace used
+      # inside the definition of another tag ("context"). This method
+      # will start the search in the specified context until it finds a
+      # match for the namespace.
+      #
+      # @param namespace [String, nil] The namespace to
+      #   match
+      # @param context_namespace [String] The context namespace in which the
+      #   tag was referenced; start from here to resolve the name
+      # @return [String, nil] fully qualified namespace
+      def qualify_namespace namespace, context_namespace = ''
+        if namespace.start_with?('::')
+          inner_qualify(namespace[2..], '', Set.new)
+        else
+          inner_qualify(namespace, context_namespace, Set.new)
+        end
+      end
+
+      # @param name [String] Namespace to fully qualify
+      # @param root [String] The context to search
+      # @param skip [Set<String>] Contexts already searched
+      # @return [String, nil] Fully qualified ("rooted") namespace
+      def inner_qualify name, root, skip
+        return name if name == ComplexType::GENERIC_TAG_NAME
+        return nil if name.nil?
+        return nil if skip.include?(root)
+        skip.add root
+        possibles = []
+        if name == ''
+          return '' if root == ''
+
+          inner_qualify(root, '', skip)
+        else
+          return name if root == '' && store.namespace_exists?(name)
+          roots = root.to_s.split('::')
+          while roots.length.positive?
+            fqns = "#{roots.join('::')}::#{name}"
+            return fqns if store.namespace_exists?(fqns)
+            incs = store.get_includes(roots.join('::'))
+            incs.each do |inc|
+              foundinc = inner_qualify(name, inc.type.to_s, skip)
+              possibles.push foundinc unless foundinc.nil?
+            end
+            roots.pop
+          end
+          if possibles.empty?
+            incs = store.get_includes('')
+            incs.each do |inc|
+              foundinc = inner_qualify(name, inc.type.to_s, skip)
+              possibles.push foundinc unless foundinc.nil?
+            end
+          end
+          return name if store.namespace_exists?(name)
+          possibles.last
+        end
+      end
+
+      # @param fqns [String]
+      # @param visibility [Array<Symbol>]
+      # @param skip [Set<String>]
+      # @return [Array<Solargraph::Pin::Namespace, Solargraph::Pin::Constant>]
+      def inner_get_constants fqns, visibility, skip
+        return [] if fqns.nil? || skip.include?(fqns)
+        skip.add fqns
+        result = []
+
+        store.get_prepends(fqns).each do |pre|
+          pre_fqns = resolve(pre.name, pre.closure.gates - skip.to_a)
+          result.concat inner_get_constants(pre_fqns, [:public], skip)
+        end
+        result.concat(store.get_constants(fqns, visibility).sort { |a, b| a.name <=> b.name })
+        store.get_includes(fqns).each do |pin|
+          inc_fqns = resolve(pin.name, pin.closure.gates - skip.to_a)
+          result.concat inner_get_constants(inc_fqns, [:public], skip)
+        end
+        sc_ref = store.get_superclass(fqns)
+        if sc_ref
+          fqsc = dereference(sc_ref)
+          result.concat inner_get_constants(fqsc, [:public], skip) unless %w[Object BasicObject].include?(fqsc)
+        end
+        result
+      end
+    end
+  end
+end

data/lib/solargraph/api_map/index.rb

@@ -1,175 +1,193 @@
-# frozen_string_literal: true
-
-module Solargraph
-  class ApiMap
-    class Index
-      include Logging
-
-      # @param pins [Array<Pin::Base>]
-      def initialize pins = []
-        catalog pins
-      end
-
-      # @return [Array<Pin::Base>]
-      def pins
-        @pins ||= []
-      end
-
-      # @return [Hash{String => Array<Pin::Namespace>}]
-      def namespace_hash
-        @namespace_hash ||= Hash.new { |h, k| h[k] = [] }
-      end
-
-      # @return [Hash{String => Array<Pin::Base>}]
-      def pin_class_hash
-        @pin_class_hash ||= Hash.new { |h, k| h[k] = [] }
-      end
-
-      # @return [Hash{String => Array<Pin::Base>}]
-      def path_pin_hash
-        @path_pin_hash ||= Hash.new { |h, k| h[k] = [] }
-      end
-
-      # @generic T
-      # @param klass [Class<generic<T>>]
-      # @return [Set<generic<T>>]
-      def pins_by_class 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
-
-      # @return [Hash{String => Array<Pin::Reference::Include>}]
-      def include_references
-        @include_references ||= Hash.new { |h, k| h[k] = [] }
-      end
-
-      # @return [Hash{String => Array<Pin::Reference::Extend>}]
-      def extend_references
-        @extend_references ||= Hash.new { |h, k| h[k] = [] }
-      end
-
-      # @return [Hash{String => Array<Pin::Reference::Prepend>}]
-      def prepend_references
-        @prepend_references ||= Hash.new { |h, k| h[k] = [] }
-      end
-
-      # @return [Hash{String => Array<Pin::Reference::Superclass>}]
-      def superclass_references
-        @superclass_references ||= Hash.new { |h, k| h[k] = [] }
-      end
-
-      # @param pins [Array<Pin::Base>]
-      def merge pins
-        deep_clone.catalog pins
-      end
-
-      protected
-
-      attr_writer :pins, :pin_select_cache, :namespace_hash, :pin_class_hash, :path_pin_hash, :include_references,
-                  :extend_references, :prepend_references, :superclass_references
-
-      def deep_clone
-        Index.allocate.tap do |copy|
-          copy.pin_select_cache = {}
-          copy.pins = pins.clone
-          %i[
-            namespace_hash pin_class_hash path_pin_hash include_references extend_references prepend_references
-            superclass_references
-          ].each do |sym|
-            copy.send("#{sym}=", send(sym).clone)
-            copy.send(sym)&.transform_values!(&:clone)
-          end
-        end
-      end
-
-      # @param new_pins [Array<Pin::Base>]
-      def catalog new_pins
-        @pin_select_cache = {}
-        pins.concat new_pins
-        set = new_pins.to_set
-        set.classify(&:class)
-           .map { |k, v| pin_class_hash[k].concat v.to_a }
-        set.classify(&:namespace)
-           .map { |k, v| namespace_hash[k].concat v.to_a }
-        set.classify(&:path)
-           .map { |k, v| path_pin_hash[k].concat v.to_a }
-        @namespaces = path_pin_hash.keys.compact.to_set
-        map_references Pin::Reference::Include, include_references
-        map_references Pin::Reference::Prepend, prepend_references
-        map_references Pin::Reference::Extend, extend_references
-        map_references Pin::Reference::Superclass, superclass_references
-        map_overrides
-        self
-      end
-
-      # @param klass [Class<Pin::Reference>]
-      # @param hash [Hash{String => Array<Pin::Reference>}]
-      # @return [void]
-      def map_references klass, hash
-        pins_by_class(klass).each do |pin|
-          store_parametric_reference(hash, pin)
-        end
-      end
-
-      # Add references to a map
-      #
-      # @param hash [Hash{String => Array<Pin::Reference>}]
-      # @param reference_pin [Pin::Reference]
-      #
-      # @return [void]
-      def store_parametric_reference(hash, 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
-        hash[referencing_ns].push referenced_tag
-      end
-
-      # @return [void]
-      def map_overrides
-        pins_by_class(Pin::Reference::Override).each do |ovr|
-          logger.debug { "ApiMap::Index#map_overrides: Looking at override #{ovr} for #{ovr.name}" }
-          pins = path_pin_hash[ovr.name]
-          logger.debug { "ApiMap::Index#map_overrides: pins for path=#{ovr.name}: #{pins}" }
-          pins.each do |pin|
-            new_pin = if pin.path.end_with?('#initialize')
-                        path_pin_hash[pin.path.sub(/#initialize/, '.new')].first
-                      end
-            (ovr.tags.map(&:tag_name) + ovr.delete).uniq.each do |tag|
-              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)
-              redefine_return_type pin, tag
-              if new_pin
-                new_pin.docstring.add_tag(tag)
-                redefine_return_type new_pin, tag
-              end
-            end
-          end
-        end
-      end
-
-      # @param pin [Pin::Method]
-      # @param tag [YARD::Tags::Tag]
-      # @return [void]
-      def redefine_return_type pin, tag
-        # @todo can this be made to not mutate existing pins and use
-        #   proxy() / proxy_with_signatures() instead?
-        return unless pin && tag.tag_name == 'return'
-        pin.instance_variable_set(:@return_type, ComplexType.try_parse(tag.type))
-        pin.signatures.each do |sig|
-          sig.instance_variable_set(:@return_type, ComplexType.try_parse(tag.type))
-        end
-        pin.reset_generated!
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Solargraph
+  class ApiMap
+    class Index
+      include Logging
+
+      # @param pins [Array<Pin::Base>]
+      def initialize pins = []
+        catalog pins
+      end
+
+      # @return [Array<Pin::Base>]
+      def pins
+        @pins ||= []
+      end
+
+      # @return [Hash{String => Array<Pin::Namespace>}]
+      def namespace_hash
+        # @param h [String]
+        # @param k [Array<Pin::Namespace>]
+        @namespace_hash ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @return [Hash{String => Array<Pin::Base>}]
+      def pin_class_hash
+        # @param h [String]
+        # @param k [Array<Pin::Base>]
+        @pin_class_hash ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @return [Hash{String => Array<Pin::Base>}]
+      def path_pin_hash
+        # @param h [String]
+        # @param k [Array<Pin::Base>]
+        @path_pin_hash ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @generic T
+      # @param klass [Class<generic<T>>]
+      # @return [Set<generic<T>>]
+      def pins_by_class klass
+        # @type [Set<Solargraph::Pin::Base>]
+        s = Set.new
+        # @sg-ignore need to support destructured args in blocks
+        @pin_select_cache[klass] ||= pin_class_hash.each_with_object(s) { |(key, o), n| n.merge(o) if key <= klass }
+      end
+
+      # @return [Hash{String => Array<String>}]
+      def include_references
+        # @param h [String]
+        # @param k [Array<String>]
+        @include_references ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @return [Hash{String => Array<Pin::Reference::Include>}]
+      def include_reference_pins
+        # @param h [String]
+        # @param k [Array<Pin::Reference::Include>]
+        @include_reference_pins ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @return [Hash{String => Array<String>}]
+      def extend_references
+        # @param h [String]
+        # @param k [Array<String>]
+        @extend_references ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @return [Hash{String => Array<String>}]
+      def prepend_references
+        # @param h [String]
+        # @param k [Array<String>]
+        @prepend_references ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @return [Hash{String => Array<String>}]
+      def superclass_references
+        # @param h [String]
+        # @param k [Array<String>]
+        @superclass_references ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @param pins [Enumerable<Pin::Base>]
+      # @return [self]
+      def merge pins
+        deep_clone.catalog pins
+      end
+
+      protected
+
+      attr_writer :pins, :pin_select_cache, :namespace_hash, :pin_class_hash, :path_pin_hash, :include_references,
+                  :extend_references, :prepend_references, :superclass_references
+
+      # @return [self]
+      def deep_clone
+        Index.allocate.tap do |copy|
+          copy.pin_select_cache = {}
+          copy.pins = pins.clone
+          %i[
+            namespace_hash pin_class_hash path_pin_hash include_references extend_references prepend_references
+            superclass_references
+          ].each do |sym|
+            copy.send("#{sym}=", send(sym).clone)
+            copy.send(sym)&.transform_values!(&:clone)
+          end
+        end
+      end
+
+      # @param new_pins [Enumerable<Pin::Base>]
+      #
+      # @return [self]
+      def catalog new_pins
+        # @type [Hash{Class<generic<T>> => Set<generic<T>>}]
+        @pin_select_cache = {}
+        pins.concat new_pins
+        set = new_pins.to_set
+        # @param k [String]
+        # @param v [Set<Pin::Base>]
+        set.classify(&:class)
+          .map { |k, v| pin_class_hash[k].concat v.to_a }
+        # @param k [String]
+        # @param v [Set<Pin::Namespace>]
+        set.classify(&:namespace)
+          .map { |k, v| namespace_hash[k].concat v.to_a }
+        # @param k [String]
+        # @param v [Set<Pin::Base>]
+        set.classify(&:path)
+          .map { |k, v| path_pin_hash[k].concat v.to_a }
+        @namespaces = path_pin_hash.keys.compact.to_set
+        map_references Pin::Reference::Include, include_references
+        map_references Pin::Reference::Prepend, prepend_references
+        map_references Pin::Reference::Extend, extend_references
+        map_references Pin::Reference::Superclass, superclass_references
+        map_overrides
+        self
+      end
+
+      # @generic T
+      # @param klass [Class<generic<T>>]
+      # @param hash [Hash{String => generic<T>}]
+      #
+      # @return [void]
+      def map_references klass, hash
+        # @param pin [generic<T>]
+        pins_by_class(klass).each do |pin|
+          hash[pin.namespace].push pin
+        end
+      end
+
+      # @return [void]
+      def map_overrides
+        # @param ovr [Pin::Reference::Override]
+        pins_by_class(Pin::Reference::Override).each do |ovr|
+          logger.debug { "ApiMap::Index#map_overrides: Looking at override #{ovr} for #{ovr.name}" }
+          pins = path_pin_hash[ovr.name]
+          logger.debug { "ApiMap::Index#map_overrides: pins for path=#{ovr.name}: #{pins}" }
+          pins.each do |pin|
+            new_pin = if pin.path.end_with?('#initialize')
+                        path_pin_hash[pin.path.sub(/#initialize/, '.new')].first
+                      end
+            (ovr.tags.map(&:tag_name) + ovr.delete).uniq.each do |tag|
+              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)
+              redefine_return_type pin, tag
+              if new_pin
+                new_pin.docstring.add_tag(tag)
+                redefine_return_type new_pin, tag
+              end
+            end
+          end
+        end
+      end
+
+      # @param pin [Pin::Method]
+      # @param tag [YARD::Tags::Tag]
+      # @return [void]
+      def redefine_return_type pin, tag
+        # @todo can this be made to not mutate existing pins and use
+        #   proxy() / proxy_with_signatures() instead?
+        return unless pin && tag.tag_name == 'return'
+        pin.instance_variable_set(:@return_type, ComplexType.try_parse(tag.type))
+        pin.signatures.each do |sig|
+          sig.instance_variable_set(:@return_type, ComplexType.try_parse(tag.type))
+        end
+        pin.reset_generated!
+      end
+    end
+  end
+end