solargraph 0.54.0 → 0.58.0

data/lib/solargraph/pin/method.rb

@@ -4,38 +4,110 @@ module Solargraph
   module Pin
     # The base class for method and attribute pins.
     #
-    class Method < Closure
+    class Method < Callable
       include Solargraph::Parser::NodeMethods
 
-      # @return [::Array<Pin::Parameter>]
-      attr_reader :parameters
-
       # @return [::Symbol] :public, :private, or :protected
       attr_reader :visibility
 
+      attr_writer :signatures
+
       # @return [Parser::AST::Node]
       attr_reader :node
 
       # @param visibility [::Symbol] :public, :protected, or :private
       # @param explicit [Boolean]
-      # @param parameters [::Array<Pin::Parameter>]
-      # @param block [Pin::Signature, nil, ::Symbol]
-      # @param node [Parser::AST::Node, RubyVM::AbstractSyntaxTree::Node, nil]
+      # @param block [Pin::Signature, nil, :undefined]
+      # @param node [Parser::AST::Node, nil]
       # @param attribute [Boolean]
       # @param signatures [::Array<Signature>, nil]
       # @param anon_splat [Boolean]
-      # @param return_type [ComplexType, nil]
-      def initialize visibility: :public, explicit: true, parameters: [], block: :undefined, node: nil, attribute: false, signatures: nil, anon_splat: false, return_type: nil, **splat
+      def initialize visibility: :public, explicit: true, block: :undefined, node: nil, attribute: false, signatures: nil, anon_splat: false,
+                     **splat
         super(**splat)
         @visibility = visibility
         @explicit = explicit
-        @parameters = parameters
         @block = block
         @node = node
         @attribute = attribute
         @signatures = signatures
         @anon_splat = anon_splat
-        @return_type = return_type
+      end
+
+      # @param signature_pins [Array<Pin::Signature>]
+      # @return [Array<Pin::Signature>]
+      def combine_all_signature_pins(*signature_pins)
+        # @type [Hash{Array => Array<Pin::Signature>}]
+        by_arity = {}
+        signature_pins.each do |signature_pin|
+          by_arity[signature_pin.arity] ||= []
+          by_arity[signature_pin.arity] << signature_pin
+        end
+        by_arity.transform_values! do |same_arity_pins|
+          # @param memo [Pin::Signature, nil]
+          # @param signature [Pin::Signature]
+          same_arity_pins.reduce(nil) do |memo, signature|
+            next signature if memo.nil?
+            memo.combine_with(signature)
+          end
+        end
+        by_arity.values.flatten
+      end
+
+      # @param other [Pin::Method]
+      # @return [::Symbol]
+      def combine_visibility(other)
+        if dodgy_visibility_source? && !other.dodgy_visibility_source?
+          other.visibility
+        elsif other.dodgy_visibility_source? && !dodgy_visibility_source?
+          visibility
+        else
+          assert_same(other, :visibility)
+        end
+      end
+
+      # @param other [Pin::Method]
+      # @return [Array<Pin::Signature>]
+      def combine_signatures(other)
+        all_undefined = signatures.all? { |sig| sig.return_type.undefined? }
+        other_all_undefined = other.signatures.all? { |sig| sig.return_type.undefined? }
+        if all_undefined && !other_all_undefined
+          other.signatures
+        elsif other_all_undefined && !all_undefined
+          signatures
+        else
+          combine_all_signature_pins(*signatures, *other.signatures)
+        end
+      end
+
+      def combine_with(other, attrs = {})
+        priority_choice = choose_priority(other)
+        return priority_choice unless priority_choice.nil?
+
+        sigs = combine_signatures(other)
+        parameters = if sigs.length > 0
+          [].freeze
+        else
+          choose(other, :parameters).clone.freeze
+        end
+        new_attrs = {
+          visibility: combine_visibility(other),
+          # @sg-ignore https://github.com/castwide/solargraph/pull/1050
+          explicit: explicit? || other.explicit?,
+          block: combine_blocks(other),
+          node: choose_node(other, :node),
+          attribute: prefer_rbs_location(other, :attribute?),
+          parameters: parameters,
+          signatures: sigs,
+          anon_splat: assert_same(other, :anon_splat?),
+          return_type: nil # pulled from signatures on first call
+        }.merge(attrs)
+        super(other, new_attrs)
+      end
+
+      # @param other [Pin::Method]
+      def == other
+        super && other.node == node
       end
 
       def transform_types(&transform)
@@ -44,21 +116,34 @@ module Solargraph
         m.signatures = m.signatures.map do |sig|
           sig.transform_types(&transform)
         end
-        m.parameters = m.parameters.map do |param|
-          param.transform_types(&transform)
-        end
         m.block = block&.transform_types(&transform)
-        m.signature_help = nil
-        m.documentation = nil
+        m.reset_generated!
         m
       end
 
+      # @return [void]
+      def reset_generated!
+        super
+        unless signatures.empty?
+          return_type = nil
+          @block = :undefined
+          parameters = []
+        end
+        block&.reset_generated!
+        @signatures&.each(&:reset_generated!)
+        signature_help = nil
+        documentation = nil
+      end
+
+      def all_rooted?
+        super && parameters.all?(&:all_rooted?) && (!block || block&.all_rooted?) && signatures.all?(&:all_rooted?)
+      end
+
       # @param signature [Pin::Signature]
       # @return [Pin::Method]
       def with_single_signature(signature)
         m = proxy signature.return_type
-        m.signature_help = nil
-        m.documentation = nil
+        m.reset_generated!
         # @todo populating the single parameters/return_type/block
         #   arguments here seems to be needed for some specs to pass,
         #   even though we have a signature with the same information.
@@ -71,15 +156,14 @@ module Solargraph
         m
       end
 
+      def block?
+        !block.nil?
+      end
+
       # @return [Pin::Signature, nil]
       def block
         return @block unless @block == :undefined
-        @block = signatures.first.block
-      end
-
-      # @return [::Array<String>]
-      def parameter_names
-        @parameter_names ||= parameters.map(&:name)
+        @block = signatures.first&.block
       end
 
       def completion_item_kind
@@ -119,13 +203,18 @@ module Solargraph
               name: name,
               decl: decl,
               presence: location ? location.range : nil,
-              return_type: ComplexType.try_parse(*p.types)
+              return_type: ComplexType.try_parse(*p.types),
+              source: source
             )
           end
           yield_return_type = ComplexType.try_parse(*yieldreturn_tags.flat_map(&:types))
-          block = Signature.new(generics, yield_parameters, yield_return_type)
+          block = Signature.new(generics: generics, parameters: yield_parameters, return_type: yield_return_type, source: source,
+                                closure: self, location: location, type_location: type_location)
         end
-        Signature.new(generics, parameters, return_type, block)
+        signature = Signature.new(generics: generics, parameters: parameters, return_type: return_type, block: block, closure: self, source: source,
+                                  location: location, type_location: type_location)
+        block.closure = signature if block
+        signature
       end
 
       # @return [::Array<Signature>]
@@ -140,6 +229,14 @@ module Solargraph
         end
       end
 
+      # @param return_type [ComplexType]
+      # @return [self]
+      def proxy_with_signatures return_type
+        out = proxy return_type
+        out.signatures = out.signatures.map { |sig| sig.proxy return_type }
+        out
+      end
+
       # @return [String, nil]
       def detail
         # This property is not cached in an instance variable because it can
@@ -166,12 +263,12 @@ module Solargraph
         end
       end
 
-      def desc
+      def inner_desc
         # ensure the signatures line up when logged
         if signatures.length > 1
-          "\n#{to_rbs}\n"
+          path + " \n#{to_rbs}\n"
         else
-          to_rbs
+          super
         end
       end
 
@@ -191,21 +288,35 @@ module Solargraph
         @path ||= "#{namespace}#{(scope == :instance ? '#' : '.')}#{name}"
       end
 
+      # @return [String]
+      def method_name
+        name
+      end
+
       def typify api_map
+        logger.debug { "Method#typify(self=#{self}, binder=#{binder}, closure=#{closure}, context=#{context.rooted_tags}, return_type=#{return_type.rooted_tags}) - starting" }
         decl = super
-        return decl unless decl.undefined?
+        unless decl.undefined?
+          logger.debug { "Method#typify(self=#{self}, binder=#{binder}, closure=#{closure}, context=#{context}) => #{decl.rooted_tags.inspect} - decl found" }
+          return decl
+        end
         type = see_reference(api_map) || typify_from_super(api_map)
-        return type.qualify(api_map, namespace) unless type.nil?
-        name.end_with?('?') ? ComplexType::BOOLEAN : ComplexType::UNDEFINED
+        logger.debug { "Method#typify(self=#{self}) - type=#{type&.rooted_tags.inspect}" }
+        unless type.nil?
+          qualified = type.qualify(api_map, *closure.gates)
+          logger.debug { "Method#typify(self=#{self}) => #{qualified.rooted_tags.inspect}" }
+          return qualified
+        end
+        super
       end
 
       def documentation
         if @documentation.nil?
-          @documentation ||= super || ''
+          method_docs ||= super || ''
           param_tags = docstring.tags(:param)
           unless param_tags.nil? or param_tags.empty?
-            @documentation += "\n\n" unless @documentation.empty?
-            @documentation += "Params:\n"
+            method_docs += "\n\n" unless method_docs.empty?
+            method_docs += "Params:\n"
             lines = []
             param_tags.each do |p|
               l = "* #{p.name}"
@@ -213,12 +324,12 @@ module Solargraph
               l += " #{p.text}"
               lines.push l
             end
-            @documentation += lines.join("\n")
+            method_docs += lines.join("\n")
           end
           yieldparam_tags = docstring.tags(:yieldparam)
           unless yieldparam_tags.nil? or yieldparam_tags.empty?
-            @documentation += "\n\n" unless @documentation.empty?
-            @documentation += "Block Params:\n"
+            method_docs += "\n\n" unless method_docs.empty?
+            method_docs += "Block Params:\n"
             lines = []
             yieldparam_tags.each do |p|
               l = "* #{p.name}"
@@ -226,12 +337,12 @@ module Solargraph
               l += " #{p.text}"
               lines.push l
             end
-            @documentation += lines.join("\n")
+            method_docs += lines.join("\n")
           end
           yieldreturn_tags = docstring.tags(:yieldreturn)
           unless yieldreturn_tags.empty?
-            @documentation += "\n\n" unless @documentation.empty?
-            @documentation += "Block Returns:\n"
+            method_docs += "\n\n" unless method_docs.empty?
+            method_docs += "Block Returns:\n"
             lines = []
             yieldreturn_tags.each do |r|
               l = "*"
@@ -239,12 +350,12 @@ module Solargraph
               l += " #{r.text}"
               lines.push l
             end
-            @documentation += lines.join("\n")
+            method_docs += lines.join("\n")
           end
           return_tags = docstring.tags(:return)
           unless return_tags.empty?
-            @documentation += "\n\n" unless @documentation.empty?
-            @documentation += "Returns:\n"
+            method_docs += "\n\n" unless method_docs.empty?
+            method_docs += "Returns:\n"
             lines = []
             return_tags.each do |r|
               l = "*"
@@ -252,10 +363,11 @@ module Solargraph
               l += " #{r.text}"
               lines.push l
             end
-            @documentation += lines.join("\n")
+            method_docs += lines.join("\n")
           end
-          @documentation += "\n\n" unless @documentation.empty?
-          @documentation += "Visibility: #{visibility}"
+          method_docs += "\n\n" unless method_docs.empty?
+          method_docs += "Visibility: #{visibility}"
+          @documentation = method_docs
           concat_example_tags
         end
         @documentation.to_s
@@ -269,10 +381,14 @@ module Solargraph
         @attribute
       end
 
+      # @parm other [self]
       def nearly? other
-        return false unless super
-        parameters == other.parameters and
-          scope == other.scope and
+        super &&
+          # @sg-ignore https://github.com/castwide/solargraph/pull/1050
+          parameters == other.parameters &&
+          # @sg-ignore https://github.com/castwide/solargraph/pull/1050
+          scope == other.scope &&
+          # @sg-ignore https://github.com/castwide/solargraph/pull/1050
           visibility == other.visibility
       end
 
@@ -280,20 +396,17 @@ module Solargraph
         attribute? ? infer_from_iv(api_map) : infer_from_return_nodes(api_map)
       end
 
-      def try_merge! pin
-        return false unless super
-        @node = pin.node
-        true
-      end
-
       # @return [::Array<Pin::Method>]
       def overloads
         # Ignore overload tags with nil parameters. If it's not an array, the
         # tag's source is likely malformed.
+
+        # @param tag [YARD::Tags::OverloadTag]
         @overloads ||= docstring.tags(:overload).select(&:parameters).map do |tag|
           Pin::Signature.new(
-            generics,
-            tag.parameters.map do |src|
+            generics: generics,
+            # @param src [Array(String, String)]
+            parameters: tag.parameters.map do |src|
               name, decl = parse_overload_param(src.first)
               Pin::Parameter.new(
                 location: location,
@@ -302,10 +415,13 @@ module Solargraph
                 name: name,
                 decl: decl,
                 presence: location ? location.range : nil,
-                return_type: param_type_from_name(tag, src.first)
+                return_type: param_type_from_name(tag, src.first),
+                source: :overloads
               )
             end,
-            ComplexType.try_parse(*tag.docstring.tags(:return).flat_map(&:types))
+            closure: self,
+            return_type: ComplexType.try_parse(*tag.docstring.tags(:return).flat_map(&:types)),
+            source: :overloads,
           )
         end
         @overloads
@@ -315,18 +431,58 @@ module Solargraph
         @anon_splat
       end
 
-      protected
+      # @param api_map [ApiMap]
+      # @return [self]
+      def resolve_ref_tag api_map
+        return self if @resolved_ref_tag
+
+        @resolved_ref_tag = true
+        return self unless docstring.ref_tags.any?
+        docstring.ref_tags.each do |tag|
+          ref = if tag.owner.to_s.start_with?(/[#.]/)
+            api_map.get_methods(namespace)
+                   .select { |pin| pin.path.end_with?(tag.owner.to_s) }
+                   .first
+          else
+            # @todo Resolve relative namespaces
+            api_map.get_path_pins(tag.owner.to_s).first
+          end
+          next unless ref
 
-      attr_writer :block
+          docstring.add_tag(*ref.docstring.tags(:param))
+        end
+        self
+      end
+
+      # @param api_map [ApiMap]
+      # @return [Array<Pin::Method>]
+      def rest_of_stack api_map
+        api_map.get_method_stack(method_namespace, method_name, scope: scope).reject { |pin| pin.path == path }
+      end
 
-      attr_writer :parameters
+      protected
 
-      attr_writer :signatures
+      attr_writer :block
 
       attr_writer :signature_help
 
       attr_writer :documentation
 
+      def dodgy_visibility_source?
+        # as of 2025-03-12, the RBS generator used for
+        # e.g. activesupport did not understand 'private' markings
+        # inside 'class << self' blocks, but YARD did OK at it
+        source == :rbs && scope == :class && type_location&.filename&.include?('generated') && return_type.undefined? ||
+          # YARD's RBS generator seems to miss a lot of should-be protected instance methods
+          source == :rbs && scope == :instance && namespace.start_with?('YARD::') ||
+          # private on attr_readers seems to be broken in Prism's auto-generator script
+          source == :rbs && scope == :instance && namespace.start_with?('Prism::') ||
+          # The RBS for the RBS gem itself seems to use private as a
+          # 'is this a public API' concept, more aggressively than the
+          # actual code.  Let's respect that and ignore the actual .rb file.
+          source == :yardoc && scope == :instance && namespace.start_with?('RBS::')
+      end
+
       private
 
       # @param name [String]
@@ -362,6 +518,7 @@ module Solargraph
       #
       # @return [ComplexType]
       def param_type_from_name(tag, name)
+        # @param t [YARD::Tags::Tag]
         param = tag.tags(:param).select { |t| t.name == name }.first
         return ComplexType::UNDEFINED unless param
         ComplexType.try_parse(*param.types)
@@ -377,8 +534,12 @@ module Solargraph
       # @param api_map [ApiMap]
       # @return [ComplexType, nil]
       def see_reference api_map
+        # This should actually be an intersection type
+        # @param ref [YARD::Tags::Tag, Solargraph::Yard::Tags::RefTag]
         docstring.ref_tags.each do |ref|
+          # @sg-ignore ref should actually be an intersection type
           next unless ref.tag_name == 'return' && ref.owner
+          # @sg-ignore ref should actually be an intersection type
           result = resolve_reference(ref.owner.to_s, api_map)
           return result unless result.nil?
         end
@@ -387,10 +548,15 @@ module Solargraph
         resolve_reference match[1], api_map
       end
 
+      # @return [String]
+      def method_namespace
+        namespace
+      end
+
       # @param api_map [ApiMap]
       # @return [ComplexType, nil]
       def typify_from_super api_map
-        stack = api_map.get_method_stack(namespace, name, scope: scope).reject { |pin| pin.path == path }
+        stack = rest_of_stack api_map
         return nil if stack.empty?
         stack.each do |pin|
           return pin.return_type unless pin.return_type.undefined?
@@ -402,11 +568,11 @@ module Solargraph
       # @param api_map [ApiMap]
       # @return [ComplexType, nil]
       def resolve_reference ref, api_map
-        parts = ref.split(/[\.#]/)
+        parts = ref.split(/[.#]/)
         if parts.first.empty? || parts.one?
           path = "#{namespace}#{ref}"
         else
-          fqns = api_map.qualify(parts.first, namespace)
+          fqns = api_map.qualify(parts.first, *gates)
           return ComplexType::UNDEFINED if fqns.nil?
           path = fqns + ref[parts.first.length] + parts.last
         end
@@ -452,7 +618,7 @@ module Solargraph
         end
         result.push ComplexType::NIL if has_nil
         return ComplexType::UNDEFINED if result.empty?
-        ComplexType.try_parse(*result.map(&:tag).uniq)
+        ComplexType.new(result.uniq)
       end
 
       # @param [ApiMap] api_map
@@ -467,7 +633,7 @@ module Solargraph
           types.push type if type.defined?
         end
         return ComplexType::UNDEFINED if types.empty?
-        ComplexType.try_parse(*types.map(&:tag).uniq)
+        ComplexType.new(types.uniq)
       end
 
       # When YARD parses an overload tag, it includes rest modifiers in the parameters names.
@@ -475,6 +641,7 @@ module Solargraph
       # @param name [String]
       # @return [::Array(String, ::Symbol)]
       def parse_overload_param(name)
+        # @todo this needs to handle mandatory vs not args, kwargs, blocks, etc
         if name.start_with?('**')
           [name[2..-1], :kwrestarg]
         elsif name.start_with?('*')
@@ -496,6 +663,10 @@ module Solargraph
         .join("\n")
         .concat("```\n")
       end
+
+      protected
+
+      attr_writer :return_type
     end
   end
 end

data/lib/solargraph/pin/method_alias.rb

@@ -13,6 +13,9 @@ module Solargraph
       # @return [String]
       attr_reader :original
 
+      # @param scope [::Symbol]
+      # @param original [String, nil] The name of the original method
+      # @param splat [Hash] Additional options supported by superclasses
       def initialize scope: :instance, original: nil, **splat
         super(**splat)
         @scope = scope

data/lib/solargraph/pin/namespace.rb

@@ -11,44 +11,52 @@ module Solargraph
       # @return [::Symbol] :class or :module
       attr_reader :type
 
+      # does not assert like super, as a namespace without a closure
+      # may be the root level namespace, or it may not yet be
+      # qualified
+      attr_reader :closure
+
       # @param type [::Symbol] :class or :module
       # @param visibility [::Symbol] :public or :private
       # @param gates [::Array<String>]
-      def initialize type: :class, visibility: :public, gates: [''], **splat
+      # @param name [String]
+      def initialize type: :class, visibility: :public, gates: [''], name: '', **splat
         # super(location, namespace, name, comments)
-        super(**splat)
+        super(**splat, name: name)
         @type = type
         @visibility = visibility
         if name.start_with?('::')
-          @name = name[2..-1]
+          # @type [String]
+          name = name[2..-1] || ''
           @closure = Solargraph::Pin::ROOT_PIN
         end
         @open_gates = gates
-        if @name.include?('::')
+        if name.include?('::')
           # In this case, a chained namespace was opened (e.g., Foo::Bar)
           # but Foo does not exist.
-          parts = @name.split('::')
-          @name = parts.pop
+          parts = name.split('::')
+          name = parts.pop
           closure_name = if [Solargraph::Pin::ROOT_PIN, nil].include?(closure)
             ''
           else
             closure.full_context.namespace + '::'
           end
           closure_name += parts.join('::')
-          @closure = Pin::Namespace.new(name: closure_name, gates: [parts.join('::')])
+          @closure = Pin::Namespace.new(name: closure_name, gates: [parts.join('::')], source: :namespace)
           @context = nil
         end
+        @name = name
       end
 
       def to_rbs
-        "#{@type.to_s} #{generics_as_rbs}#{return_type.to_rbs}"
+        "#{@type.to_s} #{return_type.all_params.first.to_rbs}#{rbs_generics}".strip
       end
 
-      def desc
-        if name.nil?
+      def inner_desc
+        if name.nil? || name.empty?
           '(top-level)'
         else
-          to_rbs
+          super
         end
       end
 
@@ -57,7 +65,7 @@ module Solargraph
       end
 
       def full_context
-        @full_context ||= ComplexType.try_parse("#{type.to_s.capitalize}<#{path}>")
+        @full_context ||= ComplexType.try_parse("::#{type.to_s.capitalize}<#{path}>")
       end
 
       def binder
@@ -83,7 +91,7 @@ module Solargraph
       end
 
       def return_type
-        @return_type ||= ComplexType.try_parse( (type == :class ? 'Class' : 'Module') + "<#{path}>" )
+        @return_type ||= ComplexType.try_parse( (type == :class ? '::Class' : '::Module') + "<::#{path}>")
       end
 
       # @return [Array<String>]