solargraph 0.52.0 → 0.53.0

data/lib/solargraph/doc_map.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Solargraph
+  # A collection of pins generated from required gems.
+  #
+  class DocMap
+    # @return [Array<String>]
+    attr_reader :requires
+
+    # @return [Array<Gem::Specification>]
+    attr_reader :dependencies
+
+    # @return [Array<Pin::Base>]
+    attr_reader :pins
+
+    # @return [Array<Gem::Specification>]
+    attr_reader :uncached_gemspecs
+
+    # @param requires [Array<String>]
+    # @param dependencies [Array<Gem::Specification>]
+    def initialize(requires, dependencies)
+      @requires = requires
+      @dependencies = dependencies
+      generate
+    end
+
+    # @return [Array<Gem::Specification>]
+    def gemspecs
+      @gemspecs ||= required_gem_map.values.compact
+    end
+
+    # @return [Array<String>]
+    def unresolved_requires
+      @unresolved_requires ||= required_gem_map.select { |_, gemspec| gemspec.nil? }.keys
+    end
+
+    # @return [Hash{Gem::Specification => Array[Pin::Base]}]
+    def self.gems_in_memory
+      @gems_in_memory ||= {}
+    end
+
+    private
+
+    # @return [Hash{String => Gem::Specification, nil}]
+    def required_gem_map
+      @required_gem_map ||= requires.to_h { |path| [path, resolve_path_to_gemspec(path)] }
+    end
+
+    # @return [Hash{String => Gem::Specification}]
+    def dependency_map
+      @dependency_map ||= dependencies.to_h { |gemspec| [gemspec.name, gemspec] }
+    end
+
+    # @return [void]
+    def generate
+      @pins = []
+      @uncached_gemspecs = []
+      required_gem_map.each do |path, gemspec|
+        if gemspec
+          try_cache gemspec
+        else
+          try_stdlib_map path
+        end
+      end
+    end
+
+    # @param gemspec [Gem::Specification]
+    # @return [void]
+    def try_cache gemspec
+      return if try_gem_in_memory(gemspec)
+      cache_file = File.join('gems', "#{gemspec.name}-#{gemspec.version}.ser")
+      if Cache.exist?(cache_file)
+        gempins = Cache.load(cache_file)
+        self.class.gems_in_memory[gemspec] = gempins
+        @pins.concat gempins
+      else
+        Solargraph.logger.debug "No pin cache for #{gemspec.name} #{gemspec.version}"
+        @uncached_gemspecs.push gemspec
+      end
+    end
+
+    # @param path [String] require path that might be in the RBS stdlib collection
+    # @return [void]
+    def try_stdlib_map path
+      map = RbsMap::StdlibMap.load(path)
+      if map.resolved?
+        Solargraph.logger.debug "Loading stdlib pins for #{path}"
+        @pins.concat map.pins
+      else
+        # @todo Temporarily ignoring unresolved `require 'set'`
+        Solargraph.logger.warn "Require path #{path} could not be resolved" unless path == 'set'
+      end
+    end
+
+    # @param gemspec [Gem::Specification]
+    # @return [Boolean]
+    def try_gem_in_memory gemspec
+      gempins = DocMap.gems_in_memory[gemspec]
+      return false unless gempins
+      Solargraph.logger.debug "Found #{gemspec.name} #{gemspec.version} in memory"
+      @pins.concat gempins
+      true
+    end
+
+    # @param path [String]
+    # @return [Gem::Specification, nil]
+    def resolve_path_to_gemspec path
+      gemspec = Gem::Specification.find_by_path(path)
+      if gemspec.nil?
+        gem_name_guess = path.split('/').first
+        begin
+          # this can happen when the gem is included via a local path in
+          # a Gemfile; Gem doesn't try to index the paths in that case.
+          #
+          # See if we can make a good guess:
+          potential_gemspec = Gem::Specification.find_by_name(gem_name_guess)
+          file = "lib/#{path}.rb"
+          gemspec = potential_gemspec if potential_gemspec.files.any? { |gemspec_file| file == gemspec_file }
+        rescue Gem::MissingSpecError
+          Solargraph.logger.debug "Require path #{path} could not be resolved to a gem via find_by_path or guess of #{gem_name_guess}"
+          nil
+        end
+      end
+      return gemspec if dependencies.empty? || gemspec.nil?
+
+      if dependency_map.key?(gemspec.name)
+        return gemspec if gemspec.version == dependency_map[gemspec.name].version
+
+        change_gemspec_version gemspec, dependency_map[by_path.name].version
+      else
+        Solargraph.logger.warn "Gem #{gemspec.name} is not an expected dependency"
+        gemspec
+      end
+    end
+
+    # @param gemspec [Gem::Specification]
+    # @param version [Gem::Version]
+    # @return [Gem::Specification]
+    def change_gemspec_version gemspec, version
+      Gem::Specification.find_by_name(gemspec.name, "= #{version}")
+    rescue Gem::MissingSpecError
+      Solargraph.logger.info "Gem #{gemspec.name} version #{version} not found. Using #{gemspec.version} instead"
+      gemspec
+    end
+  end
+end

data/lib/solargraph/gem_pins.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'rbs'
+
+module Solargraph
+  # A utility for building gem pins from a combination of YARD and RBS
+  # documentation.
+  #
+  module GemPins
+    # Build an array of pins from a gem specification. The process starts with
+    # YARD, enhances the resulting pins with RBS definitions, and appends RBS
+    # pins that don't exist in the YARD mapping.
+    #
+    # @param gemspec [Gem::Specification]
+    # @return [Array<Pin::Base>]
+    def self.build(gemspec)
+      yard_pins = build_yard_pins(gemspec)
+      rbs_map = RbsMap.from_gemspec(gemspec)
+      in_yard = Set.new
+      combined = yard_pins.map do |yard|
+        in_yard.add yard.path
+        next yard unless yard.is_a?(Pin::Method)
+        rbs = rbs_map.path_pin(yard.path)
+        next yard unless rbs
+        # @todo Could not include: attribute and anon_splat
+        # @sg-ignore
+        yard.class.new(
+          location: yard.location,
+          closure: yard.closure,
+          name: yard.name,
+          comments: yard.comments,
+          scope: yard.scope,
+          parameters: rbs.parameters,
+          generics: rbs.generics,
+          node: yard.node,
+          signatures: yard.signatures,
+          return_type: best_return_type(rbs.return_type, yard.return_type)
+        )
+      end
+      in_rbs = rbs_map.pins.reject { |pin| in_yard.include?(pin.path) }
+      combined + in_rbs
+    end
+
+    class << self
+      private
+
+      # @param gemspec [Gem::Specification]
+      # @return [Array<Pin::Base>]
+      def build_yard_pins(gemspec)
+        Yardoc.cache(gemspec) unless Yardoc.cached?(gemspec)
+        yardoc = Yardoc.load!(gemspec)
+        YardMap::Mapper.new(yardoc, gemspec).map
+      end
+
+      # Select the first defined type.
+      #
+      # @param choices [Array<ComplexType>]
+      # @return [ComplexType]
+      def best_return_type *choices
+        choices.find { |pin| pin.defined? } || choices.first || ComplexType::UNDEFINED
+      end
+    end
+  end
+end

data/lib/solargraph/language_server/host/cataloger.rb

@@ -6,6 +6,7 @@ module Solargraph
       # An asynchronous library cataloging handler.
       #
       class Cataloger
+        # @param host [Host]
         def initialize host
           @host = host
           @stopped = true

data/lib/solargraph/language_server/host/diagnoser.rb

@@ -38,7 +38,7 @@ module Solargraph
 
         # Start the diagnosis thread.
         #
-        # @return [self]
+        # @return [self, nil]
         def start
           return unless @stopped
           @stopped = false
@@ -81,7 +81,7 @@ module Solargraph
         # @return [Mutex]
         attr_reader :mutex
 
-        # @return [Array]
+        # @return [::Array]
         attr_reader :queue
       end
     end

data/lib/solargraph/language_server/host/dispatch.rb

@@ -6,6 +6,12 @@ module Solargraph
       # Methods for associating sources with libraries via URIs.
       #
       module Dispatch
+        # @abstract
+        # @return [Host::Diagnoser]
+        def diagnoser
+          raise NotImplementedError, 'Host::Dispatch requires a diagnoser method'
+        end
+
         # @return [Sources]
         def sources
           @sources ||= begin
@@ -15,7 +21,7 @@ module Solargraph
           end
         end
 
-        # @return [Array<Library>]
+        # @return [::Array<Library>]
         def libraries
           @libraries ||= []
         end
@@ -27,9 +33,9 @@ module Solargraph
         # @return [void]
         def update_libraries uri
           src = sources.find(uri)
-          libraries.each do |lib|
-            lib.merge src if lib.contain?(src.filename)
-          end
+          using = libraries.select { |lib| lib.contain?(src.filename) }
+          using.push generic_library_for(uri) if using.empty?
+          using.each { |lib| lib.merge src }
           diagnoser.schedule uri
         end
 

data/lib/solargraph/language_server/host/message_worker.rb

@@ -16,6 +16,7 @@ module Solargraph
         end
 
         # pending handle messages
+        # @return [Array<Hash>]
         def messages
           @messages ||= []
         end
@@ -24,6 +25,7 @@ module Solargraph
           @stopped
         end
 
+        # @return [void]
         def stop
           @stopped = true
         end
@@ -37,6 +39,7 @@ module Solargraph
           end
         end
 
+        # @return [void]
         def start
           return unless @stopped
           @stopped = false
@@ -45,6 +48,7 @@ module Solargraph
           end
         end
 
+        # @return [void]
         def tick
           message = @mutex.synchronize do
             @resource.wait(@mutex) if messages.empty?

data/lib/solargraph/language_server/host/sources.rb

@@ -43,6 +43,7 @@ module Solargraph
           end
         end
 
+        # @param uri [String]
         # @return [void]
         def add_uri(uri)
           queue.push(uri)
@@ -72,6 +73,8 @@ module Solargraph
           open_source_hash[uri] = source
         end
 
+        # @param uri [String]
+        # @return [void]
         def open_from_disk uri
           source = Solargraph::Source.load(UriHelpers.uri_to_file(uri))
           open_source_hash[uri] = source
@@ -83,7 +86,7 @@ module Solargraph
         #
         # @param uri [String]
         # @param updater [Source::Updater]
-        # @return [Source]
+        # @return [void]
         def update uri, updater
           src = find(uri)
           mutex.synchronize { open_source_hash[uri] = src.synchronize(updater) }
@@ -109,7 +112,7 @@ module Solargraph
         # @raise [FileNotFoundError] if the URI does not match an open source.
         #
         # @param uri [String]
-        # @return [Source]
+        # @return [Solargraph::Source]
         def find uri
           open_source_hash[uri] || raise(Solargraph::FileNotFoundError, "Host could not find #{uri}")
         end
@@ -136,7 +139,7 @@ module Solargraph
 
         private
 
-        # @return [Hash]
+        # @return [Hash{String => Solargraph::Source}]
         def open_source_hash
           @open_source_hash ||= {}
         end
@@ -146,7 +149,7 @@ module Solargraph
 
         # An array of source URIs that are waiting to finish synchronizing.
         #
-        # @return [Array<String>]
+        # @return [::Array<String>]
         def queue
           @queue ||= []
         end

data/lib/solargraph/language_server/host.rb

@@ -3,7 +3,6 @@
 require 'diff/lcs'
 require 'observer'
 require 'securerandom'
-require 'set'
 
 module Solargraph
   module LanguageServer
@@ -59,7 +58,7 @@ module Solargraph
         logger.level = LOG_LEVELS[options['logLevel']] || DEFAULT_LOG_LEVEL
       end
 
-      # @return [Hash]
+      # @return [Hash{String => [Boolean, String]}]
       def options
         @options ||= default_configuration
       end
@@ -101,8 +100,8 @@ module Solargraph
       # Start processing a request from the client. After the message is
       # processed, caller is responsible for sending the response.
       #
-      # @param request [Hash] The contents of the message.
-      # @return [Solargraph::LanguageServer::Message::Base] The message handler.
+      # @param request [Hash{String => unspecified}] The contents of the message.
+      # @return [Solargraph::LanguageServer::Message::Base, nil] The message handler.
       def receive request
         if request['method']
           logger.info "Server received #{request['method']}"
@@ -127,6 +126,7 @@ module Solargraph
         else
           logger.warn "Invalid message received."
           logger.debug request
+          nil
         end
       end
 
@@ -505,6 +505,8 @@ module Solargraph
         library.read_text(filename)
       end
 
+      # @param uri [String]
+      # @return [Hash]
       def formatter_config uri
         library = library_for(uri)
         library.workspace.config.formatter
@@ -632,7 +634,7 @@ module Solargraph
         requests.keys
       end
 
-      # @return [Hash{String => Object}]
+      # @return [Hash{String => [Boolean,String]}]
       def default_configuration
         {
           'completion' => true,
@@ -663,6 +665,7 @@ module Solargraph
         libraries.each(&:catalog)
       end
 
+      # @return [Hash{String => BasicObject}]
       def client_capabilities
         @client_capabilities ||= {}
       end
@@ -687,7 +690,7 @@ module Solargraph
       # A hash of client requests by ID. The host uses this to keep track of
       # pending responses.
       #
-      # @return [Hash{Integer => Hash}]
+      # @return [Hash{Integer => Solargraph::LanguageServer::Host}]
       def requests
         @requests ||= {}
       end
@@ -779,6 +782,9 @@ module Solargraph
           'textDocument/definition' => {
             definitionProvider: true
           },
+          'textDocument/typeDefinition' => {
+            typeDefinitionProvider: true
+          },
           'textDocument/references' => {
             referencesProvider: true
           },
@@ -832,6 +838,9 @@ module Solargraph
         end
       end
 
+      # @param library [Library]
+      # @param uuid [String, nil]
+      # @return [void]
       def do_async_library_map library, uuid = nil
         total = library.workspace.sources.length
         if uuid

data/lib/solargraph/language_server/message/completion_item/resolve.rb

@@ -29,7 +29,7 @@ module Solargraph
           end
 
           # @param text [String]
-          # @return [Hash{Symbol => String}]
+          # @return [Hash{Symbol => String}, nil]
           def markup_content text
             return nil if text.strip.empty?
             {
@@ -38,6 +38,8 @@ module Solargraph
             }
           end
 
+          # @param pins [Array<Pin::Base>]
+          # @return [String]
           def join_docs pins
             result = []
             last_link = nil

data/lib/solargraph/language_server/message/extended/check_gem_version.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
-require 'rubygems'
+
+# @todo PR the RBS gem to add this
+# @!parse
+#   module ::Gem
+#    class SpecFetcher; end
+#   end
 
 module Solargraph
   module LanguageServer
@@ -11,16 +16,23 @@ module Solargraph
         # is true, notify the client when the gem is up to date.
         #
         class CheckGemVersion < Base
+          # @return [Gem::SpecFetcher]
           def self.fetcher
             @fetcher ||= Gem::SpecFetcher.new
           end
 
+          # @param obj [Gem::SpecFetcher]
+          # @return [Gem::SpecFetcher]
           def self.fetcher= obj
             @fetcher = obj
           end
 
           GEM_ZERO = Gem::Version.new('0.0.0')
 
+          # @param host [Solargraph::LanguageServer::Host]
+          # @param request [Hash]
+          # @param current [Gem::Version]
+          # @param available [Gem::Version, nil]
           def initialize host, request, current: Gem::Version.new(Solargraph::VERSION), available: nil
             super(host, request)
             @current = current

data/lib/solargraph/language_server/message/initialize.rb

@@ -54,6 +54,7 @@ module Solargraph
             params['workspaceFolders']
         end
 
+        # @return [Hash{Symbol => undefined}]
         def static_completion
           return {} unless host.options['completion']
           {
@@ -64,6 +65,7 @@ module Solargraph
           }
         end
 
+        # @return [Hash{Symbol => BasicObject}]
         def static_code_action
           {
             codeActionProvider: true,
@@ -71,6 +73,7 @@ module Solargraph
           }
         end
 
+        # @return [Hash{Symbol => BasicObject}]
         def static_signature_help
           {
             signatureHelpProvider: {
@@ -123,9 +126,9 @@ module Solargraph
         end
 
         def static_type_definitions
-          return {} unless host.options['type_definitions']
+          return {} unless host.options['typeDefinitions']
           {
-            definitionProvider: true
+            typeDefinitionProvider: true
           }
         end
 

data/lib/solargraph/language_server/message/text_document/hover.rb

@@ -37,6 +37,8 @@ module Solargraph
 
           private
 
+          # @param contents [Array<String>]
+          # @return [Hash{Symbol => Hash{Symbol => String}}, nil]
           def contents_or_nil contents
             stripped = contents
               .map(&:strip)

data/lib/solargraph/language_server/message/text_document.rb

@@ -12,7 +12,6 @@ module Solargraph
         autoload :DidSave,           'solargraph/language_server/message/text_document/did_save'
         autoload :Hover,             'solargraph/language_server/message/text_document/hover'
         autoload :SignatureHelp,     'solargraph/language_server/message/text_document/signature_help'
-        autoload :DiagnosticsQueue,  'solargraph/language_server/message/text_document/diagnostics_queue'
         autoload :OnTypeFormatting,  'solargraph/language_server/message/text_document/on_type_formatting'
         autoload :Definition,        'solargraph/language_server/message/text_document/definition'
         autoload :TypeDefinition,    'solargraph/language_server/message/text_document/type_definition'

data/lib/solargraph/language_server/message/workspace/did_change_configuration.rb

@@ -11,8 +11,12 @@ module Solargraph::LanguageServer::Message::Workspace
 
     private
 
+    # @return [void]
     def register_from_options
+      Solargraph.logger.debug "Registering capabilities from options: #{host.options.inspect}"
+      # @type [Array<String>]
       y = []
+      # @type [Array<String>]
       n = []
       (host.options['completion'] ? y : n).push('textDocument/completion')
       (host.options['hover'] ? y : n).push('textDocument/hover', 'textDocument/signatureHelp')
@@ -20,6 +24,7 @@ module Solargraph::LanguageServer::Message::Workspace
       (host.options['formatting'] ? y : n).push('textDocument/formatting')
       (host.options['symbols'] ? y : n).push('textDocument/documentSymbol', 'workspace/symbol')
       (host.options['definitions'] ? y : n).push('textDocument/definition')
+      (host.options['typeDefinitions'] ? y : n).push('textDocument/typeDefinition')
       (host.options['references'] ? y : n).push('textDocument/references')
       (host.options['folding'] ? y : n).push('textDocument/folding')
       (host.options['highlights'] ? y : n).push('textDocument/documentHighlight')

data/lib/solargraph/language_server/transport/adapter.rb

@@ -8,6 +8,17 @@ module Solargraph
       # A common module for running language servers in Backport.
       #
       module Adapter
+        # This runs in the context of Backport::Adapter, which
+        # provides write() - but if we didn't hide this behind a parse
+        # tag, it would override the one in the class.
+        #
+        # @!method write(text)
+        #   @abstract
+        #   Write the change to the specified text.
+        #   @param text [String] The text to be changed.
+        #   @return [String] The updated text.
+
+        # @return [void]
         def opening
           @host = Solargraph::LanguageServer::Host.new
           @host.add_observer self
@@ -18,15 +29,18 @@ module Solargraph
           end
         end
 
+        # @return [void]
         def closing
           @host.stop
         end
 
         # @param data [String]
+        # @return [void]
         def receiving data
           @data_reader.receive data
         end
 
+        # @return [void]
         def update
           if @host.stopped?
             shutdown
@@ -38,12 +52,13 @@ module Solargraph
 
         private
 
-        # @param request [String]
+        # @param request [Hash]
         # @return [void]
         def process request
           @host.process(request)
         end
 
+        # @return [void]
         def shutdown
           Backport.stop unless @host.options['transport'] == 'external'
         end

data/lib/solargraph/language_server/transport/data_reader.rb

@@ -16,6 +16,7 @@ module Solargraph
         # client.
         #
         # @yieldparam [Hash] The message received from the client
+        # @return [void]
         def set_message_handler &block
           @message_handler = block
         end
@@ -26,6 +27,7 @@ module Solargraph
         # will be buffered and subsequent data will be appended to the buffer.
         #
         # @param data [String]
+        # @return [void]
         def receive data
           data.each_char do |char|
             @buffer.concat char