solargraph 0.60.4 → 0.61.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c7397d5a9bbee07b12baa9372ce14f61216e5a310aa0f68605acabf8a9430e2
-  data.tar.gz: aeecf5c5d1ea7b1040fd3ae4bd9d1bff1685e468bd92b30dedfdd8ded2f1cd04
+  metadata.gz: 7b386e8d7447871b7850f167cab1483351050f92debdc40bb4b2ee9538e820e1
+  data.tar.gz: 3b88afe53d55f28b96004941ff37c2c8c9254c7e83ed597d90122aa1b6e374c2
 SHA512:
-  metadata.gz: f4abae37c4fc8b57efe4a7b3550a2edbfc64455e8852f81660220f4a67facf101eafd058805b58cf0be6f9d5b9d16317cd21f6cd3b47f0c666c48418ee0d54c2
-  data.tar.gz: e14586769600dd63e2a96b8bcb4a5e4aa9bb045948e87e8c06b6606e711fed6816347051505eb756df55fed375a0419431dd02a44c2082d6d1ec0e2b13c6564f
+  metadata.gz: 97f94421c920c20c8c5e2d5d8deae43ef7559cd082cedc022041ebc22252c04cb713e25fb8d5e96af1c258fe7aecffbc527c88829876944868911e31f20990ee
+  data.tar.gz: ad5d661d4340531998b669b8d499922f2c05c2fc94d04f1cdb9c2ed3ce207d0aa08875fd18e9a63f6e5a9c0688354e8ea8ada6bd865f76eaaa5a92393d2c6917

data/.github/workflows/plugins.yml

@@ -129,7 +129,7 @@ jobs:
     - name: clone https://github.com/lekemula/solargraph-rspec/
       run: |
        cd ..
-       git clone https://github.com/lekemula/solargraph-rspec.git
+       git clone https://github.com/lekemula/solargraph-rspec/
        cd solargraph-rspec
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

data/.github/workflows/rspec.yml

@@ -25,7 +25,7 @@ jobs:
         #   It currently 404s ("Unavailable version head for ruby"), failing CI:
         #   https://github.com/castwide/solargraph/actions/runs/25863741955/job/76000137015?pr=1187
         ruby-version: ['3.1', '3.2', '3.3', '3.4', '4.0']
-        rbs-version: ['3.10.0', '4.0.0', '4.0.1', '4.0.2']
+        rbs-version: ['3.10.4', '4.0.0', '4.0.1', '4.0.2']
         exclude:
           - ruby-version: '3.1'
             rbs-version: '4.0.0'
@@ -48,6 +48,8 @@ jobs:
     #    starting from Ruby 3.6.0
     - name: Work around legacy rbs deprecation on ruby > 3.4
       run: echo "gem 'tsort'" >> .Gemfile
+    - name: Install bundle
+      run: bundle install
     - name: Update gems
       run: |
         bundle update rbs # use latest available for this Ruby version

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.61.0 - October 7, 2026
+- Clips qualify constant pins for completion (#1368)
+- Unused spec tags (#1370)
+- External gem dependency management (#1369)
+- Use a development branch of Solargraph::RSpec for plugin tests (#1371)
+- Pin::Base spec changes (#1372)
+- Consolidate cache and gems commands (#1373)
+- Sleep timeouts (#1375)
+- RbsMap loads minimal pins (#1377)
+- Fix 10x slowdown when analyzing projects with many gems (#1374)
+- Clone main solargraph-rspec repo in plugins workflow (#1388)
+- Add new Pin::FactoryParameter (#1063)
+- Support YARD `@!scope` directive (#1387)
+- Add nil guard to Hover (#1389)
+- Stop dropping union members that differ only by type parameter (#1273)
+
 ## 0.60.4 - August 30, 2026
 - Fix @yieldparam type lost on multi-overload block-form methods (#1289) (#1290)
 - Read inline RBS superclass params only on the class line (#1301)

data/Gemfile

@@ -4,9 +4,6 @@ source 'https://rubygems.org'
 
 gemspec name: 'solargraph'
 
-# Test fixture gems
-gem 'gem-with-yard-macros', path: 'spec/fixtures/gem-with-yard-macros'
-
 # Local gemfile for development tools, etc.
 local_gemfile = File.expand_path('.Gemfile', __dir__)
 instance_eval File.read local_gemfile if File.exist? local_gemfile

data/lib/solargraph/api_map/index.rb

@@ -92,6 +92,11 @@ module Solargraph
         @superclass_references ||= Hash.new { |h, k| h[k] = [] }
       end
 
+      # @return [Hash{String => Array<Pin::FactoryParameter>}]
+      def factory_parameter_hash
+        @factory_parameter_hash ||= Hash.new { |h, k| h[k] = [] }
+      end
+
       # @param pins [Enumerable<Pin::Base>]
       # @return [self]
       def merge pins
@@ -101,8 +106,8 @@ module Solargraph
       protected
 
       attr_writer :pins, :pin_select_cache, :namespace_hash, :pin_class_hash, :path_pin_hash, :include_references,
-                  :extend_references, :prepend_references, :superclass_references, :macro_method_names,
-                  :macro_method_name_pins
+                  :extend_references, :prepend_references, :superclass_references, :factory_parameter_hash,
+                  :macro_method_names, :macro_method_name_pins
 
       # @return [self]
       def deep_clone
@@ -148,6 +153,7 @@ module Solargraph
         macro_pins = pins_by_class(Pin::Method).select { |pin| pin.macros.any? }
         @macro_method_names = macro_pins.to_set(&:name)
         @macro_method_name_pins = macro_pins.to_set.classify(&:name)
+        map_factory_parameters
         map_overrides
         pins_by_class(Pin::Reference::TypeAlias).each { |pin| alias_hash[pin.name] = pin.return_type }
         self
@@ -210,6 +216,13 @@ module Solargraph
           sig.instance_variable_set(:@return_type, ComplexType.try_parse(tag.type))
         end
       end
+
+      # @return [void]
+      def map_factory_parameters
+        pins_by_class(Pin::FactoryParameter).each do |fp|
+          factory_parameter_hash[fp.method_path] << fp
+        end
+      end
     end
   end
 end

data/lib/solargraph/api_map/store.rb

@@ -261,6 +261,14 @@ module Solargraph
         ancestors.compact.uniq
       end
 
+      # Get factory parameters for a method pin.
+      #
+      # @param method_pin [Pin::Method]
+      # @return [Array<Pin::FactoryParameter>]
+      def factory_parameters_for_method method_pin
+        factory_parameter_hash[method_pin.path] || []
+      end
+
       # @param fqns [String]
       #
       # @return [Array<Solargraph::Pin::Reference>]
@@ -358,6 +366,11 @@ module Solargraph
         index.extend_references
       end
 
+      # @return [Hash{String => Array<Pin::FactoryParameter>}]
+      def factory_parameter_hash
+        index.factory_parameter_hash
+      end
+
       # @param name [String]
       # @return [Enumerable<Solargraph::Pin::Base>]
       def namespace_children name

data/lib/solargraph/api_map.rb

@@ -15,13 +15,9 @@ module Solargraph
     autoload :Index,          'solargraph/api_map/index'
     autoload :Constants,      'solargraph/api_map/constants'
 
-    # @return [Array<String>]
-    attr_reader :unresolved_requires
-
-    @@core_map = RbsMap::CoreMap.new
+    include Equality
 
-    # @return [Array<String>]
-    attr_reader :missing_docs
+    @@core_pins = Collection::Core.load
 
     # @param pins [Array<Solargraph::Pin::Base>]
     # @param loose_unions [Boolean] if true, a potential type can be
@@ -38,12 +34,6 @@ module Solargraph
       index pins
     end
 
-    # @param out [StringIO, IO, nil] output stream for logging
-    # @return [void]
-    def self.reset_core out: nil
-      @@core_map = RbsMap::CoreMap.new
-    end
-
     #
     # This is a mutable object, which is cached in the Chain class -
     # if you add any fields which change the results of calls (not
@@ -86,7 +76,7 @@ module Solargraph
       @source_map_hash = {}
       conventions_environ.clear
       cache.clear
-      store.update @@core_map.pins, pins
+      store.update @@core_pins, pins
       self
     end
 
@@ -106,6 +96,8 @@ module Solargraph
     # @param bench [Bench]
     # @return [self]
     def catalog bench
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @workspace = bench.workspace
       @source_map_hash = bench.source_map_hash
       # @type [Array<Pin::Base>]
       iced_pins = bench.icebox.flat_map(&:pins)
@@ -114,24 +106,27 @@ module Solargraph
       source_map_hash.each_value do |map|
         conventions_environ.merge map.conventions_environ
       end
-      unresolved_requires = (bench.external_requires + conventions_environ.requires + bench.workspace.config.required).to_a.compact.uniq
-      recreate_docmap = @unresolved_requires != unresolved_requires ||
-                        # @sg-ignore Unresolved call to rbs_collection_path on Solargraph::Workspace, nil
-                        workspace.rbs_collection_path != bench.workspace.rbs_collection_path ||
-                        @doc_map.uncached_gemspecs.any?
-
-      if recreate_docmap
-        @doc_map = DocMap.new(unresolved_requires, bench.workspace, out: nil) # @todo Implement gem preferences
-        @unresolved_requires = @doc_map.unresolved_requires
-      end
-      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      Solargraph.logger.info 'Cataloging ApiMap started'
-      @cache.clear if store.update(@@core_map.pins, @doc_map.pins, conventions_environ.pins, iced_pins, live_pins) { process_macros }
-      @missing_docs = [] # @todo Implement missing docs
+      # @todo Determine what needs to be sent to global conventions
+      conventions_environ.merge Convention.for_global(nil)
+      external_changed = external.update(bench.external_requires.to_a + conventions_environ.requires)
+      store_changed = store.update(@@core_pins, external.pins.clone, conventions_environ.pins, iced_pins, live_pins) { process_macros }
+      @cache.clear if external_changed || store_changed
       Solargraph.logger.info "Cataloging ApiMap finished in #{Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time} seconds"
       self
     end
 
+    def external
+      @external ||= External.new(workspace&.directory, [])
+    end
+
+    def unresolved_requires
+      external.unresolved_requires
+    end
+
+    def unloaded_gems
+      external.unloaded_gems
+    end
+
     # @return [Array<Pin::Base>]
     def process_macros
       macro_pins = []
@@ -144,45 +139,23 @@ module Solargraph
         method_candidates.each do |node|
           closure = source_map.locate_closure_pin(node.location.line, node.location.column)
           chain = Solargraph::Parser::ParserGem::NodeChainer.chain(node)
-          if node.children[0].nil? && store.macro_method_name_pins.key?(node.children[1].to_s)
-            match = store.macro_method_name_pins[node.children[1].to_s].find do |pin|
-              get_complex_type_methods(closure.return_type).include?(pin)
-            end
-            if match
-              match.macros.each do |macro|
-                macro_pins.concat macro.generate_pins_from(chain, match, source_map)
-              end
-              next
-            end
+          next unless node.children[0].nil? && store.macro_method_name_pins.key?(node.children[1].to_s)
+          match = store.macro_method_name_pins[node.children[1].to_s].find do |pin|
+            get_complex_type_methods(closure.return_type).include?(pin)
+          end
+          next unless match
+          match.macros.each do |macro|
+            macro_pins.concat macro.generate_pins_from(chain, match, source_map)
           end
+          next
         end
       end
       macro_pins
     end
 
-    # @return [DocMap]
-    def doc_map
-      @doc_map ||= DocMap.new([], Workspace.new('.'))
-    end
-
-    # @return [::Array<Gem::Specification>]
-    def uncached_gemspecs
-      doc_map.uncached_gemspecs || []
-    end
-
-    # @return [::Array<Gem::Specification>]
-    def uncached_rbs_collection_gemspecs
-      @doc_map.uncached_rbs_collection_gemspecs
-    end
-
-    # @return [::Array<Gem::Specification>]
-    def uncached_yard_gemspecs
-      @doc_map.uncached_yard_gemspecs
-    end
-
     # @return [Enumerable<Pin::Base>]
     def core_pins
-      @@core_map.pins
+      @@core_pins
     end
 
     # @param name [String, nil]
@@ -237,21 +210,6 @@ module Solargraph
       api_map
     end
 
-    # @param out [StringIO, IO, nil]
-    # @param rebuild [Boolean] whether to rebuild the pins even if they are cached
-    # @return [void]
-    def cache_all_for_doc_map! out: $stderr, rebuild: false
-      doc_map.cache_all!(out, rebuild: rebuild)
-    end
-
-    # @param gemspec [Gem::Specification]
-    # @param rebuild [Boolean]
-    # @param out [StringIO, IO, nil]
-    # @return [void]
-    def cache_gem gemspec, rebuild: false, out: nil
-      doc_map.cache(gemspec, rebuild: rebuild, out: out)
-    end
-
     class << self
       include Logging
     end
@@ -267,12 +225,12 @@ module Solargraph
     # @return [ApiMap]
     def self.load_with_cache directory, out = $stderr, loose_unions: true
       api_map = load(directory, loose_unions: loose_unions)
-      if api_map.uncached_gemspecs.empty?
-        logger.info { "All gems cached for #{directory}" }
-        return api_map
-      end
+      return api_map if api_map.external.unloaded_gems.empty?
 
-      api_map.cache_all_for_doc_map!(out: out)
+      api_map.external.unloaded_gems.each do |metagem|
+        out&.puts "Caching gem #{metagem.name} (#{metagem.cache_name})"
+        Collection::Gem.load metagem
+      end
       load(directory, loose_unions: loose_unions)
     end
 
@@ -288,6 +246,21 @@ module Solargraph
       store.pins_by_class(Pin::Keyword)
     end
 
+    # An array of pins based on factory parameters.
+    #
+    # @return [Enumerable<Solargraph::Pin::FactoryParameter>]
+    def factory_parameter_pins
+      store.pins_by_class(Pin::FactoryParameter)
+    end
+
+    # Get factory parameters for a method pin.
+    #
+    # @param method_pin [Solargraph::Pin::Method]
+    # @return [Array<Solargraph::Pin::FactoryParameter>]
+    def factory_parameters_for_method method_pin
+      store.factory_parameters_for_method(method_pin)
+    end
+
     # @param name [String]
     # @return [ComplexType, nil]
     def unalias name
@@ -609,6 +582,9 @@ module Solargraph
 
     # Get an array of pins that match the specified path.
     #
+    # @example
+    #   api_map.get_pins_by_path('String#split')
+    #
     # @param path [String]
     # @return [Array<Pin::Base>]
     def get_path_pins path
@@ -755,7 +731,7 @@ module Solargraph
 
     # @return [Workspace, nil]
     def workspace
-      doc_map.workspace
+      @workspace
     end
 
     # @param fq_reference_tag [String] A fully qualified whose method should be pulled in
@@ -1051,8 +1027,11 @@ module Solargraph
     #   that this overload of 'protected' will typecheck @sg-ignore
     # @sg-ignore
     def equality_fields
-      [self.class, @source_map_hash, conventions_environ, @doc_map, @unresolved_requires, @missing_docs,
-       @loose_unions]
+      # External is compared by identity and generation instead of by its pins:
+      # Chain#infer hashes the ApiMap on every inference, and Array#hash would
+      # walk every gem pin on each of those calls.
+      [@source_map_hash, conventions_environ, @external, @external&.generation,
+       @unresolved_requires, @loose_unions]
     end
   end
 end

data/lib/solargraph/cache_dir.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'rbs'
+
+module Solargraph
+  module CacheDir
+    module_function
+
+    # The base directory for cached YARD documentation and serialized pins.
+    #
+    # @return [String]
+    def base_dir
+      ENV['SOLARGRAPH_CACHE'] ||
+        (ENV['XDG_CACHE_HOME'] ? File.join(ENV['XDG_CACHE_HOME'], 'solargraph') : nil) ||
+        File.join(Dir.home, '.cache', 'solargraph')
+    end
+
+    # The working directory for the current Ruby, RBS, and Solargraph versions.
+    #
+    # @return [String]
+    def work_dir
+      File.join(base_dir, "ruby-#{RUBY_VERSION}", "rbs-#{RBS::VERSION}", "solargraph-#{Solargraph::VERSION}")
+    end
+
+    # The current gem directory.
+    #
+    # @return [String]
+    def gem_dir
+      File.join(work_dir, 'gems')
+    end
+
+    # The current stdlib directory.
+    #
+    # @return [String]
+    def stdlib_dir
+      File.join(work_dir, 'stdlib')
+    end
+
+    # The current RBS collection directory.
+    #
+    # @return [String]
+    def rbs_dir
+      File.join(work_dir, 'rbs')
+    end
+
+    # The directory for the current YARD version.
+    #
+    # @return [String]
+    def yard_dir
+      File.join(base_dir, "yard-#{YARD::VERSION}", "yard-activesupport-concern-#{YARD::ActiveSupport::Concern::VERSION}")
+    end
+
+    def clear
+      FileUtils.rm_rf base_dir
+    end
+  end
+end

data/lib/solargraph/collection/base.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Solargraph
+  module Collection
+    # The base class for cacheable pin collections. Subclasses need to
+    # implement #pins and #cache_file.
+    #
+    # @!method pins
+    #   The array of pins for this collection.
+    #   @abstract
+    #   @return [Array<Pin::Base>]
+    # @!method cache_file
+    #   The file that will store serialized pins.
+    #   @abstract
+    #   @return [String]
+    class Base
+      # @return [Array<Pin::Base>]
+      def load
+        Collection.cached(cache_file) { file_cache_pins || generate_pin_caches }
+      end
+
+      # @return [Array<Pin::Base>]
+      def self.load(...)
+        new(...).load
+      end
+
+      def self.uncache(...)
+        cache_file = new(...).cache_file
+        FileUtils.rm_rf cache_file
+        Collection.mem_cache.delete cache_file
+      end
+
+      private
+
+      def file_cache_pins
+        Marshal.load(File.read(cache_file, mode: 'rb')) if File.exist?(cache_file) # rubocop:disable Security/MarshalLoad
+      end
+
+      def generate_pin_caches
+        Collection.mem_cache[cache_file] = pins
+        serial = Marshal.dump(pins)
+        FileUtils.mkdir_p File.dirname(cache_file)
+        File.write cache_file, serial, mode: 'wb'
+        pins
+      end
+    end
+  end
+end

data/lib/solargraph/collection/core.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Collection
+    # Cacheable core pins.
+    #
+    class Core < Base
+      def cache_file
+        File.join CacheDir.work_dir, 'core.ser'
+      end
+
+      def pins
+        @pins ||= RbsMap::Core.pins
+      end
+    end
+  end
+end

data/lib/solargraph/collection/gem.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Collection
+    # Cacheable gem pins.
+    #
+    class Gem < Base
+      include Logging
+
+      attr_reader :metagem
+
+      # @param metagem [Metagem]
+      def initialize metagem
+        super()
+        @metagem = metagem
+      end
+
+      def cache_file
+        File.join CacheDir.gem_dir, "#{metagem.cache_name}.ser"
+      end
+
+      def load
+        return pins unless metagem.cacheable?
+        super
+      end
+
+      def pins
+        @pins ||= if metagem.cacheable?
+                    cacheable_pins
+                  else
+                    uncacheable_pins
+                  end
+      end
+
+      def self.cached? metagem
+        metagem.cacheable? && File.exist?(new(metagem).cache_file)
+      end
+
+      private
+
+      def cacheable_pins
+        code_objects = Yardoc.load!(metagem)
+        yard_pins = YardMap::Mapper.new(code_objects, metagem).map
+        rbs_pins = RbsMap::Gem.pins(metagem)
+        RbsMap::Helpers.combine(yard_pins, rbs_pins)
+      end
+
+      def uncacheable_pins
+        files = metagem.require_paths.flat_map { |path| Dir.glob(File.join(metagem.full_path, path, '**', '*.rb')) }
+        source_maps = files.map { |file| Solargraph::SourceMap.load(file) }
+        source_pins = source_maps.flat_map(&:pins)
+        rbs_pins = RbsMap::Gem.pins(metagem)
+        RbsMap::Helpers.combine(source_pins, rbs_pins)
+      end
+    end
+  end
+end

data/lib/solargraph/collection/rbs.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Solargraph
+  module Collection
+    # Cacheable pins from an RBS collection directory.
+    #
+    class Rbs < Base
+      # @return [String]
+      attr_reader :path
+
+      # @param path [String]
+      # @return [Array<Pin::Base>]
+      def self.load path
+        new(path).load
+      end
+
+      # @param path [String]
+      def initialize path
+        super()
+        @path = path
+      end
+
+      # @return [Array<Pin::Base>]
+      def pins
+        @pins ||= RbsMap::Path.pins(path)
+      end
+
+      # @return [String]
+      def cache_file
+        File.join CacheDir.rbs_dir, "#{key}.ser"
+      end
+
+      private
+
+      # A collection is rewritten in place by `rbs collection install`, so the
+      # newest signature mtime distinguishes one installation from the next.
+      #
+      # @return [String]
+      def key
+        @key ||= begin
+          stamp = Dir.glob(File.join(path, '**', '*.rbs')).map { |file| File.mtime(file).to_i }.max
+          format('%.32s', Digest::SHA256.hexdigest("#{File.expand_path(path)}:#{stamp}"))
+        end
+      end
+    end
+  end
+end

data/lib/solargraph/collection/stdlib.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Collection
+    # Cacheable stdlib pins.
+    #
+    class Stdlib < Base
+      attr_reader :library
+
+      # @param library [String]
+      def initialize library
+        super()
+        @library = library
+      end
+
+      def pins
+        @pins ||= RbsMap::Stdlib.pins(library)
+      end
+
+      def cache_file
+        File.join CacheDir.stdlib_dir, "#{library}.ser"
+      end
+    end
+  end
+end

data/lib/solargraph/collection.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Collection
+    autoload :Base,   'solargraph/collection/base'
+    autoload :Core,   'solargraph/collection/core'
+    autoload :Gem,    'solargraph/collection/gem'
+    autoload :Rbs,    'solargraph/collection/rbs'
+    autoload :Stdlib, 'solargraph/collection/stdlib'
+
+    # A hash for storing pin collections in memory.
+    #
+    # @return [Hash{String => Array<Pin::Base>}]
+    def self.mem_cache
+      @mem_cache ||= {}
+    end
+
+    # The pins cached under a key, storing the block result on a miss.
+    #
+    # @param key [String]
+    # @return [Array<Pin::Base>]
+    def self.cached key
+      mem_cache.fetch(key) { mem_cache[key] = yield }
+    end
+
+    # @return [void]
+    def self.clear_mem_cache
+      mem_cache.clear
+    end
+  end
+end