Integration test: 2026-08-04

.github/workflows/plugins.yml

@@ -196,7 +196,7 @@ jobs:
         # solargraph-rails supports Ruby 3.0+
         # This job uses 3.2 due to a problem compiling sqlite3 in earlier versions
         ruby-version: '3.2'
-        bundler-cache: false
+        bundler-cache: true
         # https://github.com/apiology/solargraph/actions/runs/19400815835/job/55508092473?pr=17
         rubygems: latest
         bundler: latest

.github/workflows/rspec.yml

@@ -25,21 +25,28 @@ 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.0', '4.0.3', '4.1.1']
         exclude:
           - ruby-version: '3.1'
-            rbs-version: '4.0.0'
+            rbs-version: '4.0.3'
           - ruby-version: '3.1'
-            rbs-version: '4.0.1'
-          - ruby-version: '3.1'
-            rbs-version: '4.0.2'
+            rbs-version: '4.1.1'
     steps:
     - uses: actions/checkout@v3
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: true
+        # Without this pin, ruby/setup-ruby uses whatever bundler ships
+        # with each matrix Ruby version individually, rather than one
+        # consistent version across the matrix. Confirmed by removing
+        # it: stdlib/default-gem resolution changed enough that
+        # Workspace::Gemspecs#resolve_require('yaml') started returning
+        # nil, failing spec/api_map_method_spec.rb's YAML test across
+        # most of the matrix. Keep this in sync with Gemfile.lock's
+        # BUNDLED WITH version, and with the same pin below.
+        bundler: 2.5.23
     - name: Set rbs version
       run: echo "gem 'rbs', '${{ matrix.rbs-version }}'" >> .Gemfile
     #  /home/runner/.rubies/ruby-head/lib/ruby/gems/3.5.0+2/gems/rbs-3.9.4/lib/rbs.rb:11:
@@ -67,7 +74,15 @@ jobs:
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: '3.4'
+        # See the matching pin in the rspec matrix job above for why
+        # this is needed - keep both in sync with Gemfile.lock's
+        # BUNDLED WITH version.
+        bundler: 2.5.23
         bundler-cache: true
+    - name: Install gems
+      run: |
+        bundle _2.5.23_ install
+        bundle update rbs # use latest available for this Ruby version
     - name: Update types
       run: bundle exec rbs collection update
     - name: Run tests

.github/workflows/typecheck.yml

@@ -38,5 +38,3 @@ jobs:
       run: bundle exec rbs collection install
     - name: Typecheck self
       run: SOLARGRAPH_ASSERTS=on bundle exec solargraph typecheck --level strong
-      # @todo Temporary, expect to revert in 0.60
-      continue-on-error: true

.rubocop.yml

@@ -92,6 +92,12 @@ Metrics/PerceivedComplexity:
   Max: 40
 RSpec/ExampleLength:
   Max: 310
+# Autocorrect mangles short-style Hash tags with nested generics/parens
+# (e.g. Hash{Array(String, Array<String>) => String}) into invalid syntax.
+# Confirmed broken through rubocop-yard 1.3.0 (latest as of this writing),
+# against yard 0.9.45 (also latest as of this writing).
+YARD/CollectionStyle:
+  Enabled: false
 
 plugins:
   - rubocop-rspec

.rubocop_todo.yml

@@ -85,6 +85,7 @@ Metrics/AbcSize:
   Exclude:
     - 'lib/solargraph/api_map/source_to_yard.rb'
     - 'lib/solargraph/parser/parser_gem/node_chainer.rb'
+    - 'lib/solargraph/shell.rb'
     - 'lib/solargraph/source/source_chainer.rb'
     - 'lib/solargraph/source_map/clip.rb'
     - 'lib/solargraph/source_map/mapper.rb'

Gemfile

@@ -5,6 +5,7 @@ source 'https://rubygems.org'
 gemspec name: 'solargraph'
 
 # Test fixture gems
+# @sg-ignore Wrong argument type for Kernel#gem: arg_1 expected String, received Hash
 gem 'gem-with-yard-macros', path: 'spec/fixtures/gem-with-yard-macros'
 
 # Local gemfile for development tools, etc.

Rakefile

@@ -49,7 +49,6 @@ task :full_spec do
   FileUtils.mv('coverage/full-new', 'coverage/full')
 end
 
-# @sg-ignore #undercover return type could not be inferred
 # @return [Process::Status]
 def undercover
   simplecov_collate

lib/solargraph.rb

@@ -80,11 +80,8 @@ def self.assert_or_log type, msg = nil, &block
       raise "No message given for #{type.inspect}" if msg.nil?
 
       # conditional aliases to handle compatibility corner cases
-      # @sg-ignore flow sensitive typing needs to handle 'raise if'
       return if type == :alias_target_missing && msg.include?('highline/compatibility.rb')
-      # @sg-ignore flow sensitive typing needs to handle 'raise if'
       return if type == :alias_target_missing && msg.include?('lib/json/add/date.rb')
-      # @sg-ignore flow sensitive typing needs to handle 'raise if'
       return if type == :alias_target_missing && msg.include?('rubocop-ast.rbs')
       # @todo :combine_with_visibility is not ready for prime time -
       #  lots of disagreements found in practice that heuristics need

lib/solargraph/api_map.rb

@@ -116,9 +116,8 @@ def catalog bench
       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?
+                        @doc_map.any_uncached?
 
       if recreate_docmap
         @doc_map = DocMap.new(unresolved_requires, bench.workspace, out: nil) # @todo Implement gem preferences
@@ -145,10 +144,12 @@ def process_macros
           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)
+            # @sg-ignore Need to add nil check here
             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
+              # @sg-ignore Need to add nil check here
               match.macros.each do |macro|
                 macro_pins.concat macro.generate_pins_from(chain, match, source_map)
               end
@@ -170,16 +171,6 @@ 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
@@ -188,7 +179,6 @@ def core_pins
     # @param name [String, nil]
     # @return [Solargraph::YardMap::Macro, nil]
     def named_macro name
-      # @sg-ignore Need to add nil check here
       store.named_macros[name]
     end
 
@@ -205,9 +195,11 @@ def conventions_environ
     # @param filename [String]
     # @param position [Position, Array(Integer, Integer)]
     # @return [Source::Cursor]
+    # @sg-ignore Need to add nil check here
     def cursor_at filename, position
       position = Position.normalize(position)
       raise FileNotFoundError, "File not found: #{filename}" unless source_map_hash.key?(filename)
+      # @sg-ignore Need to add nil check here
       source_map_hash[filename].cursor_at(position)
     end
 
@@ -241,7 +233,7 @@ def self.load directory, loose_unions: true
     # @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)
+      doc_map.cache_doc_map_gems!(out, rebuild: rebuild)
     end
 
     # @param gemspec [Gem::Specification]
@@ -416,7 +408,7 @@ def var_at_location candidates, name, closure, location
         !pin.visible_at?(closure, location) && !pin.starts_at?(location)
       end
 
-      vars_at_location.inject(&:combine_with)
+      vars_at_location.inject { |acc, pin| acc.combine_with(pin, location: location) }
     end
 
     # Get an array of class variable pins for a namespace.
@@ -442,6 +434,20 @@ def get_block_pins
       store.pins_by_class(Pin::Block)
     end
 
+    # Get the methods a namespace (e.g. an RBS interface) declares
+    # directly on itself, excluding ones inherited from Object,
+    # superclasses, or mixins. Useful for structural (duck-type)
+    # checks against an interface's own contract, e.g. whether some
+    # other type implements every method `Hash::_Key` itself declares
+    # (`#hash`, `#eql?`), independent of the interface's name.
+    #
+    # @param rooted_tag [String] The fully qualified namespace/interface to search for methods
+    # @param scope [Symbol] :class or :instance
+    # @return [Array<Solargraph::Pin::Method>]
+    def get_own_methods rooted_tag, scope: :instance
+      get_methods(rooted_tag, scope: scope).select { |pin| pin.closure&.path == rooted_tag }
+    end
+
     # Get an array of methods available in a particular context.
     #
     # @param rooted_tag [String] The fully qualified namespace to search for methods
@@ -450,9 +456,14 @@ def get_block_pins
     # @param deep [Boolean] True to include superclasses, mixins, etc.
     # @return [Array<Solargraph::Pin::Method>]
     def get_methods rooted_tag, scope: :instance, visibility: [:public], deep: true
+      if rooted_tag.start_with? 'Array('
+        # Array() are really tuples - use our fill, as the RBS repo
+        # does not give us definitions for it
+        rooted_tag = "Solargraph::Fills::Tuple(#{rooted_tag[6..-2]})"
+      end
       rooted_type = ComplexType.try_parse(rooted_tag)
       fqns = rooted_type.namespace
-      namespace_pin = store.get_path_pins(fqns).select { |p| p.is_a?(Pin::Namespace) }.first
+      namespace_pin = namespace_pin_for_generics(fqns)
       cached = cache.get_methods(rooted_tag, scope, visibility, deep)
       return cached.clone unless cached.nil?
       # @type [Array<Solargraph::Pin::Method>]
@@ -592,6 +603,7 @@ def get_method_stack rooted_tag, name, scope: :instance, visibility: %i[private
                 else
                   get_methods(rooted_tag, scope: scope, visibility: visibility).select { |p| p.name == name }
                 end
+      # @sg-ignore Need to add nil check here
       methods = erase_generics(namespace_pin, rooted_type, methods) unless preserve_generics
       methods
     end
@@ -652,6 +664,7 @@ def query_symbols query
     # @return [Array<Solargraph::Pin::Base>]
     def locate_pins location
       return [] if location.nil? || !source_map_hash.key?(location.filename)
+      # @sg-ignore Need to add nil check here
       resolve_method_aliases source_map_hash[location.filename].locate_pins(location)
     end
 
@@ -670,6 +683,7 @@ def clip cursor
     # @return [Array<Pin::Symbol>]
     def document_symbols filename
       return [] unless source_map_hash.key?(filename) # @todo Raise error?
+      # @sg-ignore Need to add nil check here
       resolve_method_aliases source_map_hash[filename].document_symbols
     end
 
@@ -682,6 +696,7 @@ def source_maps
     #
     # @param filename [String]
     # @return [SourceMap]
+    # @sg-ignore Need to add nil check here
     def source_map filename
       raise FileNotFoundError, "Source map for `#{filename}` not found" unless source_map_hash.key?(filename)
       source_map_hash[filename]
@@ -706,14 +721,12 @@ def super_and_sub? sup, sub
       # @todo If two literals are different values of the same type, it would
       #   make more sense for super_and_sub? to return true, but there are a
       #   few callers that currently expect this to be false.
-      # @sg-ignore flow-sensitive typing should be able to handle redefinition
       return false if sup.literal? && sub.literal? && sup.to_s != sub.to_s
-      # @sg-ignore flow sensitive typing should be able to handle redefinition
       sup = sup.simplify_literals.to_s
-      # @sg-ignore flow sensitive typing should be able to handle redefinition
       sub = sub.simplify_literals.to_s
       return true if sup == sub
       sc_fqns = sub
+      # @sg-ignore flow sensitive typing unions rather than overrides types across multiple sequential reassignments
       while (sc = store.get_superclass(sc_fqns))
         # @sg-ignore flow sensitive typing needs to handle "if foo = bar"
         sc_new = store.constants.dereference(sc)
@@ -750,10 +763,10 @@ def resolve_method_aliases pins, visibility = %i[public private protected]
       logger.debug do
         "ApiMap#resolve_method_aliases(pins=#{pins.map(&:name)}, visibility=#{visibility}) => #{with_resolved_aliases.map(&:name)}"
       end
-      with_resolved_aliases
+      GemPins.combine_method_pins_by_path(with_resolved_aliases)
     end
 
-    # @return [Workspace, nil]
+    # @return [Workspace]
     def workspace
       doc_map.workspace
     end
@@ -783,9 +796,10 @@ def inner_get_methods_from_reference fq_reference_tag, namespace_pin, type, scop
       # @todo Can inner_get_methods be cached?  Lots of lookups of base types going on.
       methods = inner_get_methods(resolved_reference_type.tag, scope, visibility, deep, skip, no_core)
       if namespace_pin && !resolved_reference_type.all_params.empty?
-        reference_pin = store.get_path_pins(resolved_reference_type.name).select { |p| p.is_a?(Pin::Namespace) }.first
+        reference_pin = namespace_pin_for_generics(resolved_reference_type.name)
         # logger.debug { "ApiMap#add_methods_from_reference(type=#{type}) - resolving generics with #{reference_pin.generics}, #{resolved_reference_type.rooted_tags}" }
         methods = methods.map do |method_pin|
+          # @sg-ignore Need to add nil check here
           method_pin.resolve_generics(reference_pin, resolved_reference_type)
         end
       end
@@ -799,6 +813,15 @@ def qualify_superclass fq_sub_tag
       store.qualify_superclass fq_sub_tag
     end
 
+    # @param require_path [String]
+    #
+    # @return [Array<Gem::Specification>, nil]
+    def resolve_require require_path
+      raise "Unable to resolve require '#{require_path}' without a workspace" if workspace.nil?
+
+      Workspace::Gemspecs.new(workspace.directory).resolve_require require_path
+    end
+
     private
 
     # A hash of source maps with filename keys.
@@ -811,6 +834,21 @@ def store
       @store ||= Store.new
     end
 
+    # Get the namespace pin that should be used to resolve generic type
+    # parameters for a fully qualified namespace. Multiple pins can
+    # exist for the same namespace (e.g., a gem's own class definition
+    # plus a `@!parse` stub in a different file that adds `@generic`
+    # tags); the one that actually declares the generics must be used,
+    # regardless of load order.
+    #
+    # @param fqns [String]
+    # @return [Pin::Namespace, nil]
+    def namespace_pin_for_generics fqns
+      # @type [Array<Pin::Namespace>]
+      candidates = store.get_path_pins(fqns).select { |p| p.is_a?(Pin::Namespace) }
+      candidates.find { |p| !p.generics.empty? } || candidates.first
+    end
+
     # @return [Solargraph::ApiMap::Cache]
     attr_reader :cache
 
@@ -826,7 +864,7 @@ def inner_get_methods rooted_tag, scope, visibility, deep, skip, no_core = false
       rooted_type = ComplexType.parse(rooted_tag).force_rooted
       fqns = rooted_type.namespace
       rooted_type.all_params
-      namespace_pin = store.get_path_pins(fqns).select { |p| p.is_a?(Pin::Namespace) }.first
+      namespace_pin = namespace_pin_for_generics(fqns)
       return [] if no_core && fqns =~ /^(Object|BasicObject|Class|Module)$/
       reqstr = "#{fqns}|#{scope}|#{visibility.sort}|#{deep}"
       return [] if skip.include?(reqstr)
@@ -867,6 +905,7 @@ def inner_get_methods rooted_tag, scope, visibility, deep, skip, no_core = false
           end
           rooted_sc_tag = qualify_superclass(rooted_tag)
           unless rooted_sc_tag.nil?
+            # @sg-ignore Need to add nil check here
             result.concat inner_get_methods_from_reference(rooted_sc_tag, namespace_pin, rooted_type, scope,
                                                            visibility, true, skip, no_core)
           end
@@ -880,6 +919,7 @@ def inner_get_methods rooted_tag, scope, visibility, deep, skip, no_core = false
           end
           rooted_sc_tag = qualify_superclass(rooted_tag)
           unless rooted_sc_tag.nil?
+            # @sg-ignore Need to add nil check here
             result.concat inner_get_methods_from_reference(rooted_sc_tag, namespace_pin, rooted_type, scope,
                                                            visibility, true, skip, true)
           end
@@ -973,7 +1013,6 @@ def resolve_method_alias alias_pin
         # :nocov:
       end
 
-      # @sg-ignore ignore `received nil` for original
       create_resolved_alias_pin(alias_pin, original)
     end