Fix generic binding and block signature merging through a @!parse stub

[apiology]

Fixes #1286

Problem:

A @generic tag that a @!parse stub adds to a class already defined elsewhere doesn't apply, so the type variable never binds and every call downstream of it stops resolving.

# widgetbox.rb - the gem's own class, no generics
module Widgetbox
  class Collection
    def self.make; new; end
    def last; nil; end
  end

  class Widget
    # @return [String, nil]
    def resource_subtype; end
  end
end

# annotations.rb - a @!parse stub adds @generic T and the return types
# @!parse
#   module Widgetbox
#     # @generic T
#     class Collection
#       class << self
#         # @return [Widgetbox::Collection<Widgetbox::Widget>]
#         def make; end
#       end
#       # @return [generic<T>]
#       def last; end
#     end
#   end

# app.rb
# @return [String, nil]
def check
  Widgetbox::Collection.make.last.resource_subtype
end

$ solargraph typecheck --level strong app.rb
app.rb:2: #check return type could not be inferred

It happens whenever the plain definition is mapped first — a gem loading ahead of the workspace, or simply appearing earlier in the same file — so an annotation written this way is inert with nothing reported to say so.

Solution:

Choose the namespace pin that actually declares generics rather than whichever loaded first, and combine same-path method pins so a stub's @return tags survive alongside the gem's own definition.

---

Problem:

A workspace @!parse stub's block parameter type has no effect when the gem's own doc already declares a return type:

module Widgetbox
  class << self
    # @return [String]
    def build(&block) = 'x'
  end
end

# @!parse
#   module Widgetbox
#     class << self
#       # @yieldparam config [String]
#       # @return [String]
#       def build(&block); end
#     end
#   end

Widgetbox.build { |config| config.upcase } # Unresolved call to upcase

The method pin itself carries only one of the two signatures, so hover and completion lose the same information inference does.

Solution:

combine_signatures_by_type_arity buckets signatures by type_arity before merging, and a block's declared-parameter count changes that bucket, so this adds a pass that merges block-informativeness-only differences first and makes Callable#combine_blocks prefer the more informative block instead of choosing arbitrarily; two related gaps stay open (a stub missing @return is discarded wholesale by combine_signatures, and def self.build paired with class << self never combines pins at all).

🤖 Generated with Claude Code