solargraph 0.51.2 → 0.53.0

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,9 +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 == 'param'
+        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)
@@ -110,13 +152,16 @@ module Solargraph
           return UniqueType::UNDEFINED
         end
         fqns = "::#{fqns}" # Ensure the resulting complex type is rooted
-        ltypes = key_types.map { |t| t.qualify api_map, context }.uniq
-        rtypes = value_types.map { |t| t.qualify api_map, context }.uniq
+        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)

data/lib/solargraph/complex_type/unique_type.rb

@@ -27,18 +27,27 @@ 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
@@ -51,80 +60,168 @@ module Solargraph
         tag
       end
 
-      def to_rbs
-        "#{namespace}#{parameters? ? "[#{subtypes.map { |s| s.to_rbs }.join(', ')}]" : ''}"
-      end
-  
-      def parameterized?
-        name == 'param' || all_params.any?(&:parameterized?)
+      # @return [Array<UniqueType>]
+      def items
+        [self]
       end
 
-      def resolve_parameters definitions, context
-        new_name = if name == 'param'
-          idx = definitions.parameters.index(subtypes.first.name)
-          return ComplexType::UNDEFINED if idx.nil?
-          param_type = context.return_type.all_params[idx]
-          return ComplexType::UNDEFINED unless param_type
-          param_type.to_s
-        else
-          name
-        end
-        new_key_types = if name != 'param'
-          @key_types.map { |t| t.resolve_parameters(definitions, context) }.select(&:defined?)
+      # @return [String]
+      def rbs_name
+        if name == 'undefined'
+          'untyped'
         else
-          []
+          rooted_name
         end
-        new_subtypes = if name != 'param'
-          @subtypes.map { |t| t.resolve_parameters(definitions, context) }.select(&:defined?)
+      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
+            # already generated surrounded by []
+            parameters_as_rbs
+          end
         else
-          []
+          "#{rbs_name}#{parameters_as_rbs}"
         end
-        if name != 'param' && !(new_key_types.empty? && new_subtypes.empty?)
-          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(', ')})>")
-            else
-              UniqueType.new(new_name, "<#{new_subtypes.join(', ')}>")
+      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: {}
+        transform(name) do |t|
+          next t unless t.name == ComplexType::GENERIC_TAG_NAME
+
+          new_binding = false
+
+          type_param = t.subtypes.first&.name
+          next t 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
+          resolved_generic_values[type_param] || t
+        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
-            UniqueType.new(new_name)
+            t
           end
-        else
-          UniqueType.new(new_name)
         end
+      end
 
-        # idx = definitions.parameters.index(subtypes.first.name)
-        # STDERR.puts "Index: #{idx}"
-        # return ComplexType::UNDEFINED if idx.nil?
-        # param_type = context.return_type.all_params[idx]
-        # return ComplexType::UNDEFINED unless param_type
-        # ComplexType.try_parse(param_type.to_s)
+      # @yieldparam t [self]
+      # @yieldreturn [self]
+      # @return [Array<self>]
+      def map &block
+        [block.yield(self)]
       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?
+      # @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 parameters?
-          if @substring.start_with?'<('
-            UniqueType.new(new_name, "<(#{new_subtypes.join(', ')})>")
-          else
-            UniqueType.new(new_name, "<#{new_subtypes.join(', ')}>")
-          end
+        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)
+          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
 
       def selfy?
         @name == 'self' || @key_types.any?(&:selfy?) || @subtypes.any?(&:selfy?)
       end
-  
+
       UNDEFINED = UniqueType.new('undefined')
       BOOLEAN = UniqueType.new('Boolean')
     end

data/lib/solargraph/complex_type.rb

@@ -4,15 +4,18 @@ 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]
@@ -27,28 +30,44 @@ module Solargraph
       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 do |item|
-        "#{item.namespace}#{item.parameters? ? "[#{item.subtypes.map { |s| s.to_rbs }.join(', ')}]" : ''}"
-      end.join(' | ') + (@items.length > 1 ? ')' : '')).gsub(/undefined/, 'untyped')
+      ((@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 [Enumerator<UniqueType>]
+    # @return [void]
+    # @overload each_unique_type()
+    #   @return [Enumerator<UniqueType>]
     def each_unique_type &block
       return enum_for(__method__) unless block_given?
 
@@ -57,14 +76,23 @@ module Solargraph
       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
@@ -80,12 +108,16 @@ module Solargraph
       @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
@@ -106,12 +138,23 @@ module Solargraph
       @items.any?(&:selfy?)
     end
 
-    def parameterized?
-      any?(&:parameterized?)
+    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
 
-    def resolve_parameters definitions, context
-      result = @items.map { |i| i.resolve_parameters(definitions, context) }
+    # @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
 
@@ -128,19 +171,25 @@ module Solargraph
       @items.any?(&:nil_type?)
     end
 
+    # @return [Array<ComplexType>]
     def all_params
       @items.first.all_params || []
     end
 
-    protected
-
     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
@@ -170,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]
@@ -198,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
@@ -220,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
@@ -267,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.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

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"

data/lib/solargraph/diagnostics/rubocop.rb

@@ -29,9 +29,9 @@ module Solargraph
         store = RuboCop::ConfigStore.new
         runner = RuboCop::Runner.new(options, store)
         result = redirect_stdout{ runner.run(paths) }
-        
+
         return [] if result.empty?
-        
+
         make_array JSON.parse(result)
       rescue RuboCop::ValidationError, RuboCop::ConfigNotFoundError => e
         raise DiagnosticsError, "Error in RuboCop configuration: #{e.message}"
@@ -48,7 +48,7 @@ module Solargraph
         args.find { |a| a =~ /version=/ }.to_s.split('=').last
       end
 
-      # @param resp [Hash]
+      # @param resp [Hash{String => Array<Hash{String => Array<Hash{String => undefined}>}>}]
       # @return [Array<Hash>]
       def make_array resp
         diagnostics = []
@@ -62,8 +62,8 @@ module Solargraph
 
       # Convert a RuboCop offense to an LSP diagnostic
       #
-      # @param off [Hash] Offense received from Rubocop
-      # @return [Hash] LSP diagnostic
+      # @param off [Hash{String => unknown}] Offense received from Rubocop
+      # @return [Hash{Symbol => Hash, String, Integer}] LSP diagnostic
       def offense_to_diagnostic off
         {
           range: offense_range(off).to_hash,
@@ -81,19 +81,20 @@ module Solargraph
         Range.new(offense_start_position(off), offense_ending_position(off))
       end
 
-      # @param off [Hash]
+      # @param off [Hash{String => Hash{String => Integer}}]
       # @return [Position]
       def offense_start_position off
         Position.new(off['location']['start_line'] - 1, off['location']['start_column'] - 1)
       end
 
-      # @param off [Hash]
+      # @param off [Hash{String => Hash{String => Integer}}]
       # @return [Position]
       def offense_ending_position off
         if off['location']['start_line'] != off['location']['last_line']
           Position.new(off['location']['start_line'], 0)
         else
           start_line = off['location']['start_line'] - 1
+          # @type [Integer]
           last_column = off['location']['last_column']
           line = @source.code.lines[start_line]
           col_off = if line.nil? || line.empty?

data/lib/solargraph/diagnostics/rubocop_helpers.rb

@@ -12,6 +12,7 @@ module Solargraph
       #
       # @param version [String, nil]
       # @raise [InvalidRubocopVersionError] if _version_ is not installed
+      # @return [void]
       def require_rubocop(version = nil)
         begin
           gem_path = Gem::Specification.find_by_name('rubocop', version).full_gem_path