solargraph 0.47.2 → 0.53.3

data/lib/solargraph/complex_type/type_methods.rb

@@ -2,9 +2,23 @@
 
 module Solargraph
   class ComplexType
-    # Methods for accessing type data.
+    # Methods for accessing type data available from
+    # both ComplexType and UniqueType.
     #
+    # @abstract This mixin relies on these -
+    #   instance variables:
+    #     @name: String
+    #     @subtypes: Array<ComplexType>
+    #     @rooted: boolish
+    #   methods:
+    #     transform()
     module TypeMethods
+      # @!method transform(new_name = nil, &transform_type)
+      #   @param new_name [String, nil]
+      #   @yieldparam t [UniqueType]
+      #   @yieldreturn [UniqueType]
+      #   @return [UniqueType, nil]
+
       # @return [String]
       attr_reader :name
 
@@ -24,8 +38,7 @@ module Solargraph
 
       # @return [Boolean]
       def nil_type?
-        @nil_type = (name.casecmp('nil') == 0) if @nil_type.nil?
-        @nil_type
+        @nil_type ||= (name.casecmp('nil') == 0)
       end
 
       # @return [Boolean]
@@ -45,6 +58,22 @@ module Solargraph
         name == 'undefined'
       end
 
+      # @param generics_to_erase [Enumerable<String>]
+      # @return [self]
+      def erase_generics(generics_to_erase)
+        transform do |type|
+          if type.name == ComplexType::GENERIC_TAG_NAME
+            if type.all_params.length == 1 && generics_to_erase.include?(type.all_params.first.to_s)
+              ComplexType::UNDEFINED
+            else
+              type
+            end
+          else
+            type
+          end
+        end
+      end
+
       # @return [Boolean]
       def list_parameters?
         substring.start_with?('<')
@@ -80,12 +109,25 @@ module Solargraph
         end.call
       end
 
-      # @return [Symbol] :class or :instance
+      # @return [String]
+      def rooted_namespace
+        return namespace unless rooted?
+        "::#{namespace}"
+      end
+
+      # @return [String]
+      def rooted_name
+        return name unless rooted?
+        "::#{name}"
+      end
+
+      # @return [::Symbol] :class or :instance
       def scope
         @scope ||= :instance if duck_type? || nil_type?
         @scope ||= (name == 'Class' || name == 'Module') && !subtypes.empty? ? :class : :instance
       end
 
+      # @param other [Object]
       def == other
         return false unless self.class == other.class
         tag == other.tag
@@ -99,8 +141,9 @@ module Solargraph
       #
       # @param api_map [ApiMap] The ApiMap that performs qualification
       # @param context [String] The namespace from which to resolve names
-      # @return [ComplexType] The generated ComplexType
+      # @return [self, ComplexType, UniqueType] The generated ComplexType
       def qualify api_map, context = ''
+        return self if name == GENERIC_TAG_NAME
         return ComplexType.new([self]) if duck_type? || void? || undefined?
         recon = (rooted? ? '' : context)
         fqns = api_map.qualify(name, recon)
@@ -109,22 +152,28 @@ module Solargraph
           return UniqueType::UNDEFINED
         end
         fqns = "::#{fqns}" # Ensure the resulting complex type is rooted
-        ltypes = key_types.map do |t|
-          t.qualify api_map, context
-        end
-        rtypes = value_types.map do |t|
-          t.qualify api_map, context
-        end
+        all_ltypes = key_types.map { |t| t.qualify api_map, context }.uniq
+        all_rtypes = value_types.map { |t| t.qualify api_map, context }
         if list_parameters?
+          rtypes = all_rtypes.uniq
           Solargraph::ComplexType.parse("#{fqns}<#{rtypes.map(&:tag).join(', ')}>")
         elsif fixed_parameters?
-          Solargraph::ComplexType.parse("#{fqns}(#{rtypes.map(&:tag).join(', ')})")
+          Solargraph::ComplexType.parse("#{fqns}(#{all_rtypes.map(&:tag).join(', ')})")
         elsif hash_parameters?
+          ltypes = all_ltypes.uniq
+          rtypes = all_rtypes.uniq
           Solargraph::ComplexType.parse("#{fqns}{#{ltypes.map(&:tag).join(', ')} => #{rtypes.map(&:tag).join(', ')}}")
         else
           Solargraph::ComplexType.parse(fqns)
         end
       end
+
+      # @yieldparam [UniqueType]
+      # @return [Enumerator<UniqueType>]
+      def each_unique_type &block
+        return enum_for(__method__) unless block_given?
+        yield self
+      end
     end
   end
 end

data/lib/solargraph/complex_type/unique_type.rb

@@ -8,6 +8,8 @@ module Solargraph
     class UniqueType
       include TypeMethods
 
+      attr_reader :all_params, :subtypes, :key_types
+
       # Create a UniqueType with the specified name and an optional substring.
       # The substring is the parameter section of a parametrized type, e.g.,
       # for the type `Array<String>`, the name is `Array` and the substring is
@@ -25,42 +27,217 @@ module Solargraph
         end
         @substring = substring
         @tag = @name + substring
+        # @type [Array<ComplexType>]
         @key_types = []
+        # @type [Array<ComplexType>]
         @subtypes = []
+        # @type [Array<ComplexType>]
+        @all_params = []
         return unless parameters?
-        if @substring.start_with?('<(') && @substring.end_with?(')>')
-          subs = ComplexType.parse(substring[2..-3], partial: true)
-        else
-          subs = ComplexType.parse(substring[1..-2], partial: true)
-        end
+        # @todo we should be able to probe the type of 'subs' without
+        #   hoisting the definition outside of the if statement
+        subs = if @substring.start_with?('<(') && @substring.end_with?(')>')
+                 ComplexType.parse(substring[2..-3], partial: true)
+               else
+                 ComplexType.parse(substring[1..-2], partial: true)
+               end
         if hash_parameters?
           raise ComplexTypeError, "Bad hash type" unless !subs.is_a?(ComplexType) and subs.length == 2 and !subs[0].is_a?(UniqueType) and !subs[1].is_a?(UniqueType)
+          # @todo should be able to resolve map; both types have it
+          #   with same return type
+          # @sg-ignore
           @key_types.concat subs[0].map { |u| ComplexType.new([u]) }
+          # @sg-ignore
           @subtypes.concat subs[1].map { |u| ComplexType.new([u]) }
         else
           @subtypes.concat subs
         end
+        @all_params.concat @key_types
+        @all_params.concat @subtypes
       end
 
       def to_s
         tag
       end
 
-      def self_to dst
-        return self unless selfy?
-        new_name = (@name == 'self' ? dst : @name)
-        new_key_types = @key_types.map { |t| t.self_to dst }
-        new_subtypes = @subtypes.map { |t| t.self_to dst }
-        if hash_parameters?
-          UniqueType.new(new_name, "{#{new_key_types.join(', ')} => #{new_subtypes.join(', ')}}")
-        elsif parameters?
-          if @substring.start_with?'<('
-            UniqueType.new(new_name, "<(#{new_subtypes.join(', ')})>")
+      # @return [Array<UniqueType>]
+      def items
+        [self]
+      end
+
+      # @return [String]
+      def rbs_name
+        if name == 'undefined'
+          'untyped'
+        else
+          rooted_name
+        end
+      end
+
+      # @return [String]
+      def to_rbs
+        if ['Tuple', 'Array'].include?(name) && fixed_parameters?
+          # tuples don't have a name; they're just [foo, bar, baz].
+          if substring == '()'
+            # but there are no zero element tuples, so we go with an array
+            'Array[]'
           else
-            UniqueType.new(new_name, "<#{new_subtypes.join(', ')}>")
+            # already generated surrounded by []
+            parameters_as_rbs
           end
         else
+          "#{rbs_name}#{parameters_as_rbs}"
+        end
+      end
+
+      # @return [String]
+      def parameters_as_rbs
+        parameters? ? "[#{all_params.map { |s| s.to_rbs }.join(', ')}]" : ''
+      end
+
+      def generic?
+        name == GENERIC_TAG_NAME || all_params.any?(&:generic?)
+      end
+
+
+      # @param generics_to_resolve [Enumerable<String>]
+      # @param context_type [UniqueType, nil]
+      # @param resolved_generic_values [Hash{String => ComplexType}] Added to as types are encountered or resolved
+      # @return [UniqueType, ComplexType]
+      def resolve_generics_from_context generics_to_resolve, context_type, resolved_generic_values: {}
+        if name == ComplexType::GENERIC_TAG_NAME
+          type_param = subtypes.first&.name
+          return self unless generics_to_resolve.include? type_param
+          unless context_type.nil? || !resolved_generic_values[type_param].nil?
+            new_binding = true
+            resolved_generic_values[type_param] = context_type
+          end
+          if new_binding
+            resolved_generic_values.transform_values! do |complex_type|
+              complex_type.resolve_generics_from_context(generics_to_resolve, nil, resolved_generic_values: resolved_generic_values)
+            end
+          end
+          return resolved_generic_values[type_param] || self
+        end
+
+        # @todo typechecking should complain when the method being called has no @yieldparam tag
+        new_key_types = resolve_param_generics_from_context(generics_to_resolve, context_type, resolved_generic_values, &:key_types)
+        new_subtypes = resolve_param_generics_from_context(generics_to_resolve, context_type, resolved_generic_values, &:subtypes)
+        recreate(new_key_types: new_key_types, new_subtypes: new_subtypes)
+      end
+
+      # @param generics_to_resolve [Enumerable<String>]
+      # @param context_type [UniqueType]
+      # @param resolved_generic_values [Hash{String => ComplexType}]
+      # @yieldreturn [Array<ComplexType>]
+      # @return [Array<ComplexType>]
+      def resolve_param_generics_from_context(generics_to_resolve, context_type, resolved_generic_values)
+        types = yield self
+        types.each_with_index.flat_map do |ct, i|
+          ct.items.flat_map do |ut|
+            context_params = yield context_type if context_type
+            if context_params && context_params[i]
+              type_arg = context_params[i]
+              type_arg.map do |new_unique_context_type|
+                ut.resolve_generics_from_context generics_to_resolve, new_unique_context_type, resolved_generic_values: resolved_generic_values
+              end
+            else
+              ut.resolve_generics_from_context generics_to_resolve, nil, resolved_generic_values: resolved_generic_values
+            end
+          end
+        end
+      end
+
+      # Probe the concrete type for each of the generic type
+      # parameters used in this type, and return a new type if
+      # possible.
+      #
+      # @param definitions [Pin::Namespace, Pin::Method] The module/class/method which uses generic types
+      # @param context_type [ComplexType] The receiver type
+      # @return [UniqueType, ComplexType]
+      def resolve_generics definitions, context_type
+        return self if definitions.nil? || definitions.generics.empty?
+
+        transform(name) do |t|
+          if t.name == GENERIC_TAG_NAME
+            idx = definitions.generics.index(t.subtypes.first&.name)
+            next t if idx.nil?
+            context_type.all_params[idx] || ComplexType::UNDEFINED
+          else
+            t
+          end
+        end
+      end
+
+      # @yieldparam t [self]
+      # @yieldreturn [self]
+      # @return [Array<self>]
+      def map &block
+        [block.yield(self)]
+      end
+
+      # @return [Array<UniqueType>]
+      def to_a
+        [self]
+      end
+
+      # @param new_name [String, nil]
+      # @param new_key_types [Array<UniqueType>, nil]
+      # @param new_subtypes [Array<UniqueType>, nil]
+      # @return [self]
+      def recreate(new_name: nil, new_key_types: nil, new_subtypes: nil)
+        new_name ||= name
+        new_key_types ||= @key_types
+        new_subtypes ||= @subtypes
+        if new_key_types.none?(&:defined?) && new_subtypes.none?(&:defined?)
+          # if all subtypes are undefined, erase down to the non-parametric type
+          UniqueType.new(new_name)
+        elsif new_key_types.empty? && new_subtypes.empty?
           UniqueType.new(new_name)
+        elsif hash_parameters?
+          UniqueType.new(new_name, "{#{new_key_types.join(', ')} => #{new_subtypes.join(', ')}}")
+        elsif @substring.start_with?('<(')
+          # @todo This clause is probably wrong, and if so, fixing it
+          #    will be some level of breaking change.  Probably best
+          #    handled before real tuple support is rolled out and
+          #    folks start relying on it more.
+          #
+          #   (String) is a one element tuple in https://yardoc.org/types
+          #   <String> is an array of zero or more Strings in https://yardoc.org/types
+          #   Array<(String)> could be an Array of one-element tuples or a
+          #     one element tuple.  https://yardoc.org/types treats it
+          #     as the former.
+          #   Array<(String), Integer> is not ambiguous if we accept
+          #     (String) as a tuple type, but not currently understood
+          #     by Solargraph.
+          UniqueType.new(new_name, "<(#{new_subtypes.join(', ')})>")
+        elsif fixed_parameters?
+          UniqueType.new(new_name, "(#{new_subtypes.join(', ')})")
+        else
+          UniqueType.new(new_name, "<#{new_subtypes.join(', ')}>")
+        end
+      end
+
+      # Apply the given transformation to each subtype and then finally to this type
+      #
+      # @param new_name [String, nil]
+      # @yieldparam t [UniqueType]
+      # @yieldreturn [self]
+      # @return [self]
+      def transform(new_name = nil, &transform_type)
+        new_key_types = @key_types.flat_map { |ct| ct.map { |ut| ut.transform(&transform_type) } }.compact
+        new_subtypes = @subtypes.flat_map { |ct| ct.map { |ut| ut.transform(&transform_type) } }.compact
+        new_type = recreate(new_name: new_name || rooted_name, new_key_types: new_key_types, new_subtypes: new_subtypes)
+        yield new_type
+      end
+
+      # Transform references to the 'self' type to the specified concrete namespace
+      # @param dst [String]
+      # @return [UniqueType]
+      def self_to dst
+        transform do |t|
+          next t if t.name != 'self'
+          t.recreate(new_name: dst, new_key_types: [], new_subtypes: [])
         end
       end
 

data/lib/solargraph/complex_type.rb

@@ -4,64 +4,120 @@ module Solargraph
   # A container for type data based on YARD type tags.
   #
   class ComplexType
+    GENERIC_TAG_NAME = 'generic'.freeze
     # @!parse
     #   include TypeMethods
 
     autoload :TypeMethods, 'solargraph/complex_type/type_methods'
     autoload :UniqueType,  'solargraph/complex_type/unique_type'
 
-    # @param types [Array<UniqueType>]
+    # @param types [Array<[UniqueType, ComplexType]>]
     def initialize types = [UniqueType::UNDEFINED]
-      @items = types.uniq(&:to_s)
+      # @todo @items here should not need an annotation
+      # @type [Array<UniqueType>]
+      @items = types.flat_map(&:items).uniq(&:to_s)
     end
 
     # @param api_map [ApiMap]
     # @param context [String]
     # @return [ComplexType]
     def qualify api_map, context = ''
-      types = @items.map do |t|
+      red = reduce_object
+      types = red.items.map do |t|
         next t if ['Boolean', 'nil', 'void', 'undefined'].include?(t.name)
         t.qualify api_map, context
       end
-      ComplexType.new(types)
+      ComplexType.new(types).reduce_object
     end
 
+    # @param generics_to_resolve [Enumerable<String>]]
+    # @param context_type [UniqueType, nil]
+    # @param resolved_generic_values [Hash{String => ComplexType}] Added to as types are encountered or resolved
+    # @return [self]
+    def resolve_generics_from_context generics_to_resolve, context_type, resolved_generic_values: {}
+      return self unless generic?
+
+      ComplexType.new(@items.map { |i| i.resolve_generics_from_context(generics_to_resolve, context_type, resolved_generic_values: resolved_generic_values) })
+    end
+
+    # @return [UniqueType]
     def first
       @items.first
     end
 
+    # @return [String]
+    def to_rbs
+      ((@items.length > 1 ? '(' : '') +
+       @items.map(&:to_rbs).join(' | ') +
+       (@items.length > 1 ? ')' : ''))
+    end
+
+    # @yieldparam [UniqueType]
+    # @return [Array]
     def map &block
       @items.map &block
     end
 
     # @yieldparam [UniqueType]
-    # @return [Array]
+    # @return [Enumerable<UniqueType>]
     def each &block
       @items.each &block
     end
 
+    # @yieldparam [UniqueType]
+    # @return [void]
+    # @overload each_unique_type()
+    #   @return [Enumerator<UniqueType>]
+    def each_unique_type &block
+      return enum_for(__method__) unless block_given?
+
+      @items.each do |item|
+        item.each_unique_type &block
+      end
+    end
+
+    # @return [Integer]
     def length
       @items.length
     end
 
+    # @return [Array<UniqueType>]
+    def to_a
+      @items
+    end
+
+    # @param index [Integer]
+    # @return [UniqueType]
     def [](index)
       @items[index]
     end
 
+    # @return [Array<UniqueType>]
     def select &block
       @items.select &block
     end
+
+    # @return [String]
     def namespace
       # cache this attr for high frequency call
       @namespace ||= method_missing(:namespace).to_s
     end
 
+    # @return [Array<String>]
+    def namespaces
+      @items.map(&:namespace)
+    end
+
+    # @param name [Symbol]
+    # @return [Object, nil]
     def method_missing name, *args, &block
       return if @items.first.nil?
       return @items.first.send(name, *args, &block) if respond_to_missing?(name)
       super
     end
 
+    # @param name [Symbol]
+    # @param include_private [Boolean]
     def respond_to_missing?(name, include_private = false)
       TypeMethods.public_instance_methods.include?(name) || super
     end
@@ -75,13 +131,33 @@ module Solargraph
     end
 
     def any? &block
-      @items.any? &block
+      @items.compact.any? &block
     end
 
     def selfy?
       @items.any?(&:selfy?)
     end
 
+    def generic?
+      any?(&:generic?)
+    end
+
+    # @param new_name [String, nil]
+    # @yieldparam t [UniqueType]
+    # @yieldreturn [UniqueType]
+    # @return [ComplexType]
+    def transform(new_name = nil, &transform_type)
+      ComplexType.new(map { |ut| ut.transform(new_name, &transform_type) })
+    end
+
+    # @param definitions [Pin::Namespace, Pin::Method]
+    # @param context_type [ComplexType]
+    # @return [ComplexType]
+    def resolve_generics definitions, context_type
+      result = @items.map { |i| i.resolve_generics(definitions, context_type) }
+      ComplexType.parse(*result.map(&:tag))
+    end
+
     # @param dst [String]
     # @return [ComplexType]
     def self_to dst
@@ -95,6 +171,25 @@ module Solargraph
       @items.any?(&:nil_type?)
     end
 
+    # @return [Array<ComplexType>]
+    def all_params
+      @items.first.all_params || []
+    end
+
+    attr_reader :items
+
+    protected
+
+    # @return [ComplexType]
+    def reduce_object
+      return self if name != 'Object' || subtypes.empty?
+      ComplexType.try_parse(reduce_class(subtypes.join(', ')))
+    end
+
+    def bottom?
+      @items.all?(&:bot?)
+    end
+
     private
 
     # @todo This is a quick and dirty hack that forces `self` keywords
@@ -124,9 +219,13 @@ module Solargraph
       #   used internally.
       #
       # @param *strings [Array<String>] The type definitions to parse
-      # @param partial [Boolean] True if the string is part of a another type
-      # @return [ComplexType, Array, nil]
+      # @return [ComplexType]
+      # @overload parse(*strings, partial: false)
+      #  @todo Need ability to use a literal true as a type below
+      #  @param partial [Boolean] True if the string is part of a another type
+      #  @return [Array<UniqueType>]
       def parse *strings, partial: false
+        # @type [Hash{Array<String> => ComplexType}]
         @cache ||= {}
         unless partial
           cached = @cache[strings]
@@ -140,7 +239,7 @@ module Solargraph
           paren_stack = 0
           base = String.new
           subtype_string = String.new
-          type_string.each_char do |char|
+          type_string&.each_char do |char|
             if char == '='
               #raise ComplexTypeError, "Invalid = in type #{type_string}" unless curly_stack > 0
             elsif char == '<'
@@ -152,6 +251,9 @@ module Solargraph
                 raise ComplexTypeError, "Invalid hash thing" unless key_types.nil?
                 # types.push ComplexType.new([UniqueType.new(base[0..-2].strip)])
                 types.push UniqueType.new(base[0..-2].strip)
+                # @todo this should either expand key_type's type
+                #   automatically or complain about not being
+                #   compatible with key_type's type in type checking
                 key_types = types
                 types = []
                 base.clear
@@ -174,7 +276,7 @@ module Solargraph
               paren_stack += 1
             elsif char == ')'
               paren_stack -= 1
-              subtype_string += char if paren_stack == 0
+              subtype_string += char
               raise ComplexTypeError, "Invalid close in type #{type_string}" if paren_stack < 0
               next
             elsif char == ',' && point_stack == 0 && curly_stack == 0 && paren_stack == 0
@@ -221,5 +323,6 @@ module Solargraph
     NIL = ComplexType.parse('nil')
     SELF = ComplexType.parse('self')
     BOOLEAN = ComplexType.parse('Boolean')
+    BOT = ComplexType.parse('bot')
   end
 end

data/lib/solargraph/convention/rakefile.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Convention
+    class Rakefile < Base
+      def local source_map
+        basename = File.basename(source_map.filename)
+        return EMPTY_ENVIRON unless basename.end_with?('.rake') || basename == 'Rakefile'
+
+        @environ ||= Environ.new(
+          requires: ['rake'],
+          domains: ['Rake::DSL']
+        )
+      end
+    end
+  end
+end

data/lib/solargraph/convention.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'set'
 
 module Solargraph
   # Conventions provide a way to modify an ApiMap based on expectations about
@@ -9,8 +8,8 @@ module Solargraph
   module Convention
     autoload :Base,    'solargraph/convention/base'
     autoload :Gemfile, 'solargraph/convention/gemfile'
-    autoload :Rspec,   'solargraph/convention/rspec'
     autoload :Gemspec, 'solargraph/convention/gemspec'
+    autoload :Rakefile, 'solargraph/convention/rakefile'
 
     @@conventions = Set.new
 
@@ -42,6 +41,6 @@ module Solargraph
 
     register Gemfile
     register Gemspec
-    register Rspec
+    register Rakefile
   end
 end

data/lib/solargraph/converters/dd.rb

@@ -1,6 +1,11 @@
+require 'nokogiri'
+
 module ReverseMarkdown
   module Converters
     class Dd < Base
+      # @return [String]
+      # @param node [Nokogiri::XML::Element]
+      # @param state [Hash]
       def convert node, state = {}
         content = treat_children(node, state)
         ": #{content.strip}\n"

data/lib/solargraph/converters/dl.rb

@@ -1,6 +1,9 @@
 module ReverseMarkdown
   module Converters
     class Dl < Base
+      # @return [String]
+      # @param node [Nokogiri::XML::Element]
+      # @param state [Hash]
       def convert node, state = {}
         content = treat_children(node, state).strip
         "\n\n#{content}\n"

data/lib/solargraph/converters/dt.rb

@@ -1,6 +1,9 @@
 module ReverseMarkdown
   module Converters
     class Dt < Base
+      # @return [String]
+      # @param node [Nokogiri::XML::Element]
+      # @param state [Hash]
       def convert node, state = {}
         content = treat_children(node, state)
         "\n#{content.strip}\n"