solargraph 0.54.0 → 0.58.0

data/lib/solargraph/doc_map.rb

@@ -1,11 +1,18 @@
 # frozen_string_literal: true
 
+require 'pathname'
+require 'benchmark'
+require 'open3'
+
 module Solargraph
   # A collection of pins generated from required gems.
   #
   class DocMap
+    include Logging
+
     # @return [Array<String>]
     attr_reader :requires
+    alias required requires
 
     # @return [Array<Gem::Specification>]
     attr_reader :preferences
@@ -14,31 +21,147 @@ module Solargraph
     attr_reader :pins
 
     # @return [Array<Gem::Specification>]
-    attr_reader :uncached_gemspecs
+    def uncached_gemspecs
+      uncached_yard_gemspecs.concat(uncached_rbs_collection_gemspecs)
+                            .sort
+                            .uniq { |gemspec| "#{gemspec.name}:#{gemspec.version}" }
+    end
+
+    # @return [Array<Gem::Specification>]
+    attr_reader :uncached_yard_gemspecs
+
+    # @return [Array<Gem::Specification>]
+    attr_reader :uncached_rbs_collection_gemspecs
+
+    # @return [String, nil]
+    attr_reader :rbs_collection_path
+
+    # @return [String, nil]
+    attr_reader :rbs_collection_config_path
+
+    # @return [Workspace, nil]
+    attr_reader :workspace
+
+    # @return [Environ]
+    attr_reader :environ
 
     # @param requires [Array<String>]
     # @param preferences [Array<Gem::Specification>]
-    # @param rbs_path [String, Pathname, nil]
-    def initialize(requires, preferences, rbs_path = nil)
+    # @param workspace [Workspace, nil]
+    def initialize(requires, preferences, workspace = nil)
       @requires = requires.compact
       @preferences = preferences.compact
-      @rbs_path = rbs_path
-      generate
+      @workspace = workspace
+      @rbs_collection_path = workspace&.rbs_collection_path
+      @rbs_collection_config_path = workspace&.rbs_collection_config_path
+      @environ = Convention.for_global(self)
+      @requires.concat @environ.requires if @environ
+      load_serialized_gem_pins
+      pins.concat @environ.pins
+    end
+
+    # @param out [IO]
+    # @return [void]
+    def cache_all!(out)
+      # if we log at debug level:
+      if logger.info?
+        gem_desc = uncached_gemspecs.map { |gemspec| "#{gemspec.name}:#{gemspec.version}" }.join(', ')
+        logger.info "Caching pins for gems: #{gem_desc}" unless uncached_gemspecs.empty?
+      end
+      logger.debug { "Caching for YARD: #{uncached_yard_gemspecs.map(&:name)}" }
+      logger.debug { "Caching for RBS collection: #{uncached_rbs_collection_gemspecs.map(&:name)}" }
+      load_serialized_gem_pins
+      uncached_gemspecs.each do |gemspec|
+        cache(gemspec, out: out)
+      end
+      load_serialized_gem_pins
+      @uncached_rbs_collection_gemspecs = []
+      @uncached_yard_gemspecs = []
+    end
+
+    # @param gemspec [Gem::Specification]
+    # @param out [IO]
+    # @return [void]
+    def cache_yard_pins(gemspec, out)
+      pins = GemPins.build_yard_pins(yard_plugins, gemspec)
+      PinCache.serialize_yard_gem(gemspec, pins)
+      logger.info { "Cached #{pins.length} YARD pins for gem #{gemspec.name}:#{gemspec.version}" } unless pins.empty?
+    end
+
+    # @param gemspec [Gem::Specification]
+    # @param out [IO]
+    # @return [void]
+    def cache_rbs_collection_pins(gemspec, out)
+      rbs_map = RbsMap.from_gemspec(gemspec, rbs_collection_path, rbs_collection_config_path)
+      pins = rbs_map.pins
+      rbs_version_cache_key = rbs_map.cache_key
+      # cache pins even if result is zero, so we don't retry building pins
+      pins ||= []
+      PinCache.serialize_rbs_collection_gem(gemspec, rbs_version_cache_key, pins)
+      logger.info { "Cached #{pins.length} RBS collection pins for gem #{gemspec.name} #{gemspec.version} with cache_key #{rbs_version_cache_key.inspect}" unless pins.empty? }
+    end
+
+    # @param gemspec [Gem::Specification]
+    # @param rebuild [Boolean] whether to rebuild the pins even if they are cached
+    # @param out [IO, nil] output stream for logging
+    # @return [void]
+    def cache(gemspec, rebuild: false, out: nil)
+      build_yard = uncached_yard_gemspecs.include?(gemspec) || rebuild
+      build_rbs_collection = uncached_rbs_collection_gemspecs.include?(gemspec) || rebuild
+      if build_yard || build_rbs_collection
+        type = []
+        type << 'YARD' if build_yard
+        type << 'RBS collection' if build_rbs_collection
+        out.puts("Caching #{type.join(' and ')} pins for gem #{gemspec.name}:#{gemspec.version}") if out
+      end
+      cache_yard_pins(gemspec, out) if build_yard
+      cache_rbs_collection_pins(gemspec, out) if build_rbs_collection
     end
 
     # @return [Array<Gem::Specification>]
     def gemspecs
-      @gemspecs ||= required_gem_map.values.compact
+      @gemspecs ||= required_gems_map.values.compact.flatten
     end
 
     # @return [Array<String>]
     def unresolved_requires
-      @unresolved_requires ||= required_gem_map.select { |_, gemspec| gemspec.nil? }.keys
+      @unresolved_requires ||= required_gems_map.select { |_, gemspecs| gemspecs.nil? }.keys
     end
 
-    # @return [Hash{Gem::Specification => Array[Pin::Base]}]
-    def self.gems_in_memory
-      @gems_in_memory ||= {}
+    # @return [Hash{Array(String, String) => Array<Pin::Base>}] Indexed by gemspec name and version
+    def self.all_yard_gems_in_memory
+      @yard_gems_in_memory ||= {}
+    end
+
+    # @return [Hash{String => Hash{Array(String, String) => Array<Pin::Base>}}] stored by RBS collection path
+    def self.all_rbs_collection_gems_in_memory
+      @rbs_collection_gems_in_memory ||= {}
+    end
+
+    # @return [Hash{Array(String, String) => Array<Pin::Base>}] Indexed by gemspec name and version
+    def yard_pins_in_memory
+      self.class.all_yard_gems_in_memory
+    end
+
+    # @return [Hash{Array(String, String) => Array<Pin::Base>}] Indexed by gemspec name and version
+    def rbs_collection_pins_in_memory
+      self.class.all_rbs_collection_gems_in_memory[rbs_collection_path] ||= {}
+    end
+
+    # @return [Hash{Array(String, String) => Array<Pin::Base>}] Indexed by gemspec name and version
+    def self.all_combined_pins_in_memory
+      @combined_pins_in_memory ||= {}
+    end
+
+    # @todo this should also include an index by the hash of the RBS collection
+    # @return [Hash{Array(String, String) => Array<Pin::Base>}] Indexed by gemspec name and version
+    def combined_pins_in_memory
+      self.class.all_combined_pins_in_memory
+    end
+
+    # @return [Array<String>]
+    def yard_plugins
+      @environ.yard_plugins
     end
 
     # @return [Set<Gem::Specification>]
@@ -49,23 +172,38 @@ module Solargraph
     private
 
     # @return [void]
-    def generate
+    def load_serialized_gem_pins
       @pins = []
-      @uncached_gemspecs = []
-      required_gem_map.each do |path, gemspec|
-        if gemspec
-          try_cache gemspec
-        else
-          try_stdlib_map path
+      @uncached_yard_gemspecs = []
+      @uncached_rbs_collection_gemspecs = []
+      with_gemspecs, without_gemspecs = required_gems_map.partition { |_, v| v }
+      # @sg-ignore Need support for RBS duck interfaces like _ToHash
+      # @type [Array<String>]
+      paths = Hash[without_gemspecs].keys
+      # @sg-ignore Need support for RBS duck interfaces like _ToHash
+      # @type [Array<Gem::Specification>]
+      gemspecs = Hash[with_gemspecs].values.flatten.compact + dependencies.to_a
+
+      paths.each do |path|
+        rbs_pins = deserialize_stdlib_rbs_map path
+      end
+
+      logger.debug { "DocMap#load_serialized_gem_pins: Combining pins..." }
+      time = Benchmark.measure do
+        gemspecs.each do |gemspec|
+          pins = deserialize_combined_pin_cache gemspec
+          @pins.concat pins if pins
         end
       end
-      dependencies.each { |dep| try_cache dep }
-      @uncached_gemspecs.uniq!
+      logger.info { "DocMap#load_serialized_gem_pins: Loaded and processed serialized pins together in #{time.real} seconds" }
+      @uncached_yard_gemspecs.uniq!
+      @uncached_rbs_collection_gemspecs.uniq!
+      nil
     end
 
-    # @return [Hash{String => Gem::Specification, nil}]
-    def required_gem_map
-      @required_gem_map ||= requires.to_h { |path| [path, resolve_path_to_gemspec(path)] }
+    # @return [Hash{String => Array<Gem::Specification>}]
+    def required_gems_map
+      @required_gems_map ||= requires.to_h { |path| [path, resolve_path_to_gemspecs(path)] }
     end
 
     # @return [Hash{String => Gem::Specification}]
@@ -73,61 +211,109 @@ module Solargraph
       @preference_map ||= preferences.to_h { |gemspec| [gemspec.name, gemspec] }
     end
 
+    # @param gemspec [Gem::Specification]
+    # @return [Array<Pin::Base>, nil]
+    def deserialize_yard_pin_cache gemspec
+      if yard_pins_in_memory.key?([gemspec.name, gemspec.version])
+        return yard_pins_in_memory[[gemspec.name, gemspec.version]]
+      end
+
+      cached = PinCache.deserialize_yard_gem(gemspec)
+      if cached
+        logger.info { "Loaded #{cached.length} cached YARD pins from #{gemspec.name}:#{gemspec.version}" }
+        yard_pins_in_memory[[gemspec.name, gemspec.version]] = cached
+        cached
+      else
+        logger.debug "No YARD pin cache for #{gemspec.name}:#{gemspec.version}"
+        @uncached_yard_gemspecs.push gemspec
+        nil
+      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)
-        cached = Cache.load(cache_file)
-        gempins = update_from_collection(gemspec, cached)
-        self.class.gems_in_memory[gemspec] = gempins
-        @pins.concat gempins
+    def deserialize_combined_pin_cache(gemspec)
+      unless combined_pins_in_memory[[gemspec.name, gemspec.version]].nil?
+        return combined_pins_in_memory[[gemspec.name, gemspec.version]]
+      end
+
+      rbs_map = RbsMap.from_gemspec(gemspec, rbs_collection_path, rbs_collection_config_path)
+      rbs_version_cache_key = rbs_map.cache_key
+
+      cached = PinCache.deserialize_combined_gem(gemspec, rbs_version_cache_key)
+      if cached
+        logger.info { "Loaded #{cached.length} cached YARD pins from #{gemspec.name}:#{gemspec.version}" }
+        combined_pins_in_memory[[gemspec.name, gemspec.version]] = cached
+        return combined_pins_in_memory[[gemspec.name, gemspec.version]]
+      end
+
+      rbs_collection_pins = deserialize_rbs_collection_cache gemspec, rbs_version_cache_key
+
+      yard_pins = deserialize_yard_pin_cache gemspec
+
+      if !rbs_collection_pins.nil? && !yard_pins.nil?
+        logger.debug { "Combining pins for #{gemspec.name}:#{gemspec.version}" }
+        combined_pins = GemPins.combine(yard_pins, rbs_collection_pins)
+        PinCache.serialize_combined_gem(gemspec, rbs_version_cache_key, combined_pins)
+        combined_pins_in_memory[[gemspec.name, gemspec.version]] = combined_pins
+        logger.info { "Generated #{combined_pins_in_memory[[gemspec.name, gemspec.version]].length} combined pins for #{gemspec.name} #{gemspec.version}" }
+        return combined_pins
+      end
+
+      if !yard_pins.nil?
+        logger.debug { "Using only YARD pins for #{gemspec.name}:#{gemspec.version}" }
+        combined_pins_in_memory[[gemspec.name, gemspec.version]] = yard_pins
+        return combined_pins_in_memory[[gemspec.name, gemspec.version]]
+      elsif !rbs_collection_pins.nil?
+        logger.debug { "Using only RBS collection pins for #{gemspec.name}:#{gemspec.version}" }
+        combined_pins_in_memory[[gemspec.name, gemspec.version]] = rbs_collection_pins
+        return combined_pins_in_memory[[gemspec.name, gemspec.version]]
       else
-        Solargraph.logger.debug "No pin cache for #{gemspec.name} #{gemspec.version}"
-        @uncached_gemspecs.push gemspec
+        logger.debug { "Pins not yet cached for #{gemspec.name}:#{gemspec.version}" }
+        return nil
       end
     end
 
     # @param path [String] require path that might be in the RBS stdlib collection
     # @return [void]
-    def try_stdlib_map path
+    def deserialize_stdlib_rbs_map path
       map = RbsMap::StdlibMap.load(path)
       if map.resolved?
-        Solargraph.logger.debug "Loading stdlib pins for #{path}"
+        logger.debug { "Loading stdlib pins for #{path}" }
         @pins.concat map.pins
+        logger.debug { "Loaded #{map.pins.length} stdlib pins for #{path}" }
+        map.pins
       else
         # @todo Temporarily ignoring unresolved `require 'set'`
-        Solargraph.logger.debug "Require path #{path} could not be resolved" unless path == 'set'
+        logger.debug { "Require path #{path} could not be resolved in RBS" } unless path == 'set'
+        nil
       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
-
-    def update_from_collection gemspec, gempins
-      return gempins unless @rbs_path && File.directory?(@rbs_path)
-      return gempins if RbsMap.new(gemspec.name, gemspec.version).resolved?
-
-      rbs_map = RbsMap.new(gemspec.name, gemspec.version, directories: [@rbs_path])
-      return gempins unless rbs_map.resolved?
-
-      Solargraph.logger.info "Updating #{gemspec.name} #{gemspec.version} from collection"
-      GemPins.combine(gempins, rbs_map)
+    # @param rbs_version_cache_key [String]
+    # @return [Array<Pin::Base>, nil]
+    def deserialize_rbs_collection_cache gemspec, rbs_version_cache_key
+      return if rbs_collection_pins_in_memory.key?([gemspec, rbs_version_cache_key])
+      cached = PinCache.deserialize_rbs_collection_gem(gemspec, rbs_version_cache_key)
+      if cached
+        logger.info { "Loaded #{cached.length} pins from RBS collection cache for #{gemspec.name}:#{gemspec.version}" } unless cached.empty?
+        rbs_collection_pins_in_memory[[gemspec, rbs_version_cache_key]] = cached
+        cached
+      else
+        logger.debug "No RBS collection pin cache for #{gemspec.name} #{gemspec.version}"
+        @uncached_rbs_collection_gemspecs.push gemspec
+        nil
+      end
     end
 
     # @param path [String]
-    # @return [Gem::Specification, nil]
-    def resolve_path_to_gemspec path
+    # @return [::Array<Gem::Specification>, nil]
+    def resolve_path_to_gemspecs path
       return nil if path.empty?
+      return gemspecs_required_from_bundler if path == 'bundler/require'
 
+      # @type [Gem::Specification, nil]
       gemspec = Gem::Specification.find_by_path(path)
       if gemspec.nil?
         gem_name_guess = path.split('/').first
@@ -140,20 +326,23 @@ module Solargraph
           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
+          logger.debug { "Require path #{path} could not be resolved to a gem via find_by_path or guess of #{gem_name_guess}" }
+          []
         end
       end
-      gemspec_or_preference gemspec
+      return nil if gemspec.nil?
+      [gemspec_or_preference(gemspec)]
     end
 
-    # @param gemspec [Gem::Specification, nil]
-    # @return [Gem::Specification, nil]
+    # @param gemspec [Gem::Specification]
+    # @return [Gem::Specification]
     def gemspec_or_preference gemspec
-      return gemspec unless gemspec && preference_map.key?(gemspec.name)
+      # :nocov: dormant feature
+      return gemspec unless preference_map.key?(gemspec.name)
       return gemspec if gemspec.version == preference_map[gemspec.name].version
 
-      change_gemspec_version gemspec, preference_map[by_path.name].version
+      change_gemspec_version gemspec, preference_map[gemspec.name].version
+      # :nocov:
     end
 
     # @param gemspec [Gem::Specification]
@@ -169,12 +358,18 @@ module Solargraph
     # @param gemspec [Gem::Specification]
     # @return [Array<Gem::Specification>]
     def fetch_dependencies gemspec
+      # @param spec [Gem::Dependency]
+      # @param deps [Set<Gem::Specification>]
       only_runtime_dependencies(gemspec).each_with_object(Set.new) do |spec, deps|
         Solargraph.logger.info "Adding #{spec.name} dependency for #{gemspec.name}"
-        dep = Gem::Specification.find_by_name(spec.name, spec.requirement)
+        dep = Gem.loaded_specs[spec.name]
+        # @todo is next line necessary?
+        # @sg-ignore Unresolved call to requirement on Gem::Dependency
+        dep ||= Gem::Specification.find_by_name(spec.name, spec.requirement)
         deps.merge fetch_dependencies(dep) if deps.add?(dep)
       rescue Gem::MissingSpecError
-        Solargraph.logger.warn "Gem dependency #{spec.name} #{spec.requirements} for #{gemspec.name} not found."
+        # @sg-ignore Unresolved call to requirement on Gem::Dependency
+        Solargraph.logger.warn "Gem dependency #{spec.name} #{spec.requirement} for #{gemspec.name} not found in RubyGems."
       end.to_a
     end
 
@@ -183,5 +378,62 @@ module Solargraph
     def only_runtime_dependencies gemspec
       gemspec.dependencies - gemspec.development_dependencies
     end
+
+
+    def inspect
+      self.class.inspect
+    end
+
+    # @return [Array<Gem::Specification>, nil]
+    def gemspecs_required_from_bundler
+      # @todo Handle projects with custom Bundler/Gemfile setups
+      return unless workspace.gemfile?
+
+      if workspace.gemfile? && Bundler.definition&.lockfile&.to_s&.start_with?(workspace.directory)
+        # Find only the gems bundler is now using
+        Bundler.definition.locked_gems.specs.flat_map do |lazy_spec|
+          logger.info "Handling #{lazy_spec.name}:#{lazy_spec.version}"
+          [Gem::Specification.find_by_name(lazy_spec.name, lazy_spec.version)]
+        rescue Gem::MissingSpecError => e
+          logger.info("Could not find #{lazy_spec.name}:#{lazy_spec.version} with find_by_name, falling back to guess")
+          # can happen in local filesystem references
+          specs = resolve_path_to_gemspecs lazy_spec.name
+          logger.warn "Gem #{lazy_spec.name} #{lazy_spec.version} from bundle not found: #{e}" if specs.nil?
+          next specs
+        end.compact
+      else
+        logger.info 'Fetching gemspecs required from Bundler (bundler/require)'
+        gemspecs_required_from_external_bundle
+      end
+    end
+
+    # @return [Array<Gem::Specification>, nil]
+    def gemspecs_required_from_external_bundle
+      logger.info 'Fetching gemspecs required from external bundle'
+      return [] unless workspace&.directory
+
+      Solargraph.with_clean_env do
+        cmd = [
+          'ruby', '-e',
+          "require 'bundler'; require 'json'; Dir.chdir('#{workspace&.directory}') { puts Bundler.definition.locked_gems.specs.map { |spec| [spec.name, spec.version] }.to_h.to_json }"
+        ]
+        o, e, s = Open3.capture3(*cmd)
+        if s.success?
+          Solargraph.logger.debug "External bundle: #{o}"
+          hash = o && !o.empty? ? JSON.parse(o.split("\n").last) : {}
+          hash.flat_map do |name, version|
+            Gem::Specification.find_by_name(name, version)
+          rescue Gem::MissingSpecError => e
+            logger.info("Could not find #{name}:#{version} with find_by_name, falling back to guess")
+            # can happen in local filesystem references
+            specs = resolve_path_to_gemspecs name
+            logger.warn "Gem #{name} #{version} from bundle not found: #{e}" if specs.nil?
+            next specs
+          end.compact
+        else
+          Solargraph.logger.warn "Failed to load gems from bundle at #{workspace&.directory}: #{e}"
+        end
+      end
+    end
   end
 end

data/lib/solargraph/environ.rb

@@ -13,16 +13,21 @@ module Solargraph
     # @return [Array<String>]
     attr_reader :domains
 
-    # @return [Array<Pin::Reference::Override>]
+    # @return [Array<Pin::Base>]
     attr_reader :pins
 
+    # @return [Array<String>]
+    attr_reader :yard_plugins
+
     # @param requires [Array<String>]
     # @param domains [Array<String>]
     # @param pins [Array<Pin::Base>]
-    def initialize requires: [], domains: [], pins: []
+    # @param yard_plugins [Array<String>]
+    def initialize requires: [], domains: [], pins: [], yard_plugins: []
       @requires = requires
       @domains = domains
       @pins = pins
+      @yard_plugins = yard_plugins
     end
 
     # @return [self]
@@ -30,6 +35,7 @@ module Solargraph
       domains.clear
       requires.clear
       pins.clear
+      yard_plugins.clear
       self
     end
 
@@ -39,6 +45,7 @@ module Solargraph
       domains.concat other.domains
       requires.concat other.requires
       pins.concat other.pins
+      yard_plugins.concat other.yard_plugins
       self
     end
   end

data/lib/solargraph/equality.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Solargraph
+  # @abstract This mixin relies on these -
+  #   methods:
+  #     equality_fields()
+  module Equality
+    # @!method equality_fields
+    #   @return [Array]
+
+    # @param other [Object]
+    # @return [Boolean]
+    def eql?(other)
+      self.class.eql?(other.class) &&
+        # @sg-ignore https://github.com/castwide/solargraph/pull/1114
+        equality_fields.eql?(other.equality_fields)
+    end
+
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      self.eql?(other)
+    end
+
+    def hash
+      equality_fields.hash
+    end
+
+    def freeze
+      equality_fields.each(&:freeze)
+      super
+    end
+  end
+end

data/lib/solargraph/gem_pins.rb

@@ -7,59 +7,85 @@ module Solargraph
   # 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.
-    #
+    class << self
+      include Logging
+    end
+
+    # @param pins [Array<Pin::Base>]
+    # @return [Array<Pin::Base>]
+    def self.combine_method_pins_by_path(pins)
+      method_pins, alias_pins = pins.partition { |pin| pin.class == Pin::Method }
+      by_path = method_pins.group_by(&:path)
+      by_path.transform_values! do |pins|
+        GemPins.combine_method_pins(*pins)
+      end
+      by_path.values + alias_pins
+    end
+
+    # @param pins [Array<Pin::Method>]
+    # @return [Pin::Method, nil]
+    def self.combine_method_pins(*pins)
+      # @type [Pin::Method, nil]
+      combined_pin = nil
+      # @param memo [Pin::Method, nil]
+      # @param pin [Pin::Method]
+      out = pins.reduce(combined_pin) do |memo, pin|
+        next pin if memo.nil?
+        if memo == pin && memo.source != :combined
+          # @todo we should track down situations where we are handled
+          #   the same pin from the same source here and eliminate them -
+          #   this is an efficiency workaround for now
+          next memo
+        end
+        memo.combine_with(pin)
+      end
+      logger.debug { "GemPins.combine_method_pins(pins.length=#{pins.length}, pins=#{pins}) => #{out.inspect}" }
+      out
+    end
+
+    # @param yard_plugins [Array<String>] The names of YARD plugins to use.
     # @param gemspec [Gem::Specification]
     # @return [Array<Pin::Base>]
-    def self.build(gemspec)
-      yard_pins = build_yard_pins(gemspec)
-      rbs_map = RbsMap.from_gemspec(gemspec)
-      combine yard_pins, rbs_map
+    def self.build_yard_pins(yard_plugins, gemspec)
+      Yardoc.cache(yard_plugins, gemspec) unless Yardoc.cached?(gemspec)
+      return [] unless Yardoc.cached?(gemspec)
+      yardoc = Yardoc.load!(gemspec)
+      YardMap::Mapper.new(yardoc, gemspec).map
     end
 
     # @param yard_pins [Array<Pin::Base>]
-    # @param rbs_map [RbsMap]
+    # @param rbs_pins [Array<Pin::Base>]
+    #
     # @return [Array<Pin::Base>]
-    def self.combine(yard_pins, rbs_map)
+    def self.combine(yard_pins, rbs_pins)
       in_yard = Set.new
-      combined = yard_pins.map do |yard|
-        in_yard.add yard.path
-        next yard unless yard.is_a?(Pin::Method)
+      rbs_api_map = Solargraph::ApiMap.new(pins: rbs_pins)
+      combined = yard_pins.map do |yard_pin|
+        in_yard.add yard_pin.path
+        rbs_pin = rbs_api_map.get_path_pins(yard_pin.path).filter { |pin| pin.is_a? Pin::Method }.first
+        next yard_pin unless rbs_pin && yard_pin.class == Pin::Method
 
-        rbs = rbs_map.path_pin(yard.path, Pin::Method)
-        next yard unless rbs
+        unless rbs_pin
+          # @sg-ignore https://github.com/castwide/solargraph/pull/1114
+          logger.debug { "GemPins.combine: No rbs pin for #{yard_pin.path} - using YARD's '#{yard_pin.inspect} (return_type=#{yard_pin.return_type}; signatures=#{yard_pin.signatures})" }
+          next yard_pin
+        end
 
-        # @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)
-        )
+        out = combine_method_pins(rbs_pin, yard_pin)
+        logger.debug { "GemPins.combine: Combining yard.path=#{yard_pin.path} - rbs=#{rbs_pin.inspect} with yard=#{yard_pin.inspect} into #{out}" }
+        out
       end
-      in_rbs = rbs_map.pins.reject { |pin| in_yard.include?(pin.path) }
-      combined + in_rbs
+      in_rbs_only = rbs_pins.select do |pin|
+        pin.path.nil? || !in_yard.include?(pin.path)
+      end
+      out = combined + in_rbs_only
+      logger.debug { "GemPins#combine: Returning #{out.length} combined pins" }
+      out
     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>]