solargraph 0.58.2 → 0.59.0.dev.1

data/lib/solargraph/pin/common.rb

@@ -6,12 +6,24 @@ module Solargraph
       # @!method source
       #   @abstract
       #   @return [Source, nil]
+      # @!method reset_generated!
+      #   @abstract
+      #   @return [void]
       # @type @closure [Pin::Closure, nil]
+      # @type @binder [ComplexType, ComplexType::UniqueType, nil]
+
+      # @todo Missed nil violation
+      # @return [Location, nil]
+      attr_accessor :location
 
-      # @return [Location]
-      attr_reader :location
+      # @param value [Pin::Closure]
+      # @return [void]
+      def closure=(value)
+        @closure = value
+        # remove cached values generated from closure
+        reset_generated!
+      end
 
-      # @sg-ignore Solargraph::Pin::Common#closure return type could not be inferred
       # @return [Pin::Closure, nil]
       def closure
         Solargraph.assert_or_log(:closure, "Closure not set on #{self.class} #{name.inspect} from #{source.inspect}") unless @closure
@@ -23,12 +35,13 @@ module Solargraph
         @name ||= ''
       end
 
+      # @todo redundant with Base#return_type?
       # @return [ComplexType]
       def return_type
         @return_type ||= ComplexType::UNDEFINED
       end
 
-      # @return [ComplexType]
+      # @return [ComplexType, ComplexType::UniqueType]
       def context
         # Get the static context from the nearest namespace
         @context ||= find_context
@@ -40,7 +53,8 @@ module Solargraph
         context.namespace.to_s
       end
 
-      # @return [ComplexType]
+      # @return [ComplexType, ComplexType::UniqueType]
+      # @sg-ignore https://github.com/castwide/solargraph/pull/1100
       def binder
         @binder || context
       end
@@ -70,6 +84,7 @@ module Solargraph
           elsif here.is_a?(Pin::Method)
             return here.context
           end
+          # @sg-ignore Need to add nil check here
           here = here.closure
         end
         ComplexType::ROOT

data/lib/solargraph/pin/compound_statement.rb

@@ -0,0 +1,55 @@
+module Solargraph
+  module Pin
+    # A series of statements where if a given statement executes, /all
+    # of the previous statements in the sequence must have executed as
+    # well/.  In other words, the statements are run from the top in
+    # sequence, until interrupted by something like a
+    # return/break/next/raise/etc.
+    #
+    # This mix-in is used in flow sensitive typing to determine how
+    # far we can assume a given assertion about a type can be trusted
+    # to be true.
+    #
+    # Some examples in Ruby:
+    #
+    # * Bodies of methods and Ruby blocks
+    # * Branches of conditionals and loops - if/elsif/else,
+    #   unless/else, when, until, ||=, ?:, switch/case/else
+    # * The body of begin-end/try/rescue/ensure statements
+    #
+    # Compare/contrast with:
+    #
+    # * Scope - a sequence where variables declared are not available
+    #   after the end of the scope.  Note that this is not necessarily
+    #   true for a compound statement.
+    # * Compound statement - synonym
+    # * Block - in Ruby this has a special meaning (a closure passed to a method), but
+    #   in general parlance this is also a synonym.
+    # * Closure - a sequence which is also a scope
+    # * Namespace - a named sequence which is also a scope and a
+    #   closure
+    #
+    # See:
+    #   https://cse.buffalo.edu/~regan/cse305/RubyBNF.pdf
+    #   https://ruby-doc.org/docs/ruby-doc-bundle/Manual/man-1.4/syntax.html
+    #   https://en.wikipedia.org/wiki/Block_(programming)
+    #
+    # Note:
+    #
+    # Just because statement #1 in a sequence is executed, it doesn't
+    # mean that future ones will.  Consider the effect of
+    # break/next/return/raise/etc. on control flow.
+    class CompoundStatement < Pin::Base
+      attr_reader :node
+
+      # @param receiver [Parser::AST::Node, nil]
+      # @param node [Parser::AST::Node, nil]
+      # @param context [ComplexType, nil]
+      # @param args [::Array<Parameter>]
+      def initialize node: nil, **splat
+        super(**splat)
+        @node = node
+      end
+    end
+  end
+end

data/lib/solargraph/pin/conversions.rb

@@ -43,6 +43,7 @@ module Solargraph
           data: {
             path: path,
             return_type: return_type.tag,
+            # @sg-ignore flow sensitive typing needs to handle attrs
             location: (location ? location.to_hash : nil),
             deprecated: deprecated?
           }
@@ -80,7 +81,7 @@ module Solargraph
 
       # Get a markdown-flavored link to a documentation page.
       #
-      # @return [String]
+      # @return [String, nil]
       def link_documentation
         @link_documentation ||= generate_link
       end

data/lib/solargraph/pin/delegated_method.rb

@@ -13,10 +13,11 @@ module Solargraph
       #
       # @param method [Method, nil] an already resolved method pin.
       # @param receiver [Source::Chain, nil] the source code used to resolve the receiver for this delegated method.
-      # @param name [String]
-      # @param receiver_method_name [String] the method name that will be called on the receiver (defaults to :name).
+      # @param name [String, nil]
+      # @param receiver_method_name [String, nil] the method name that will be called on the receiver (defaults to :name).
       def initialize(method: nil, receiver: nil, name: method&.name, receiver_method_name: name, **splat)
         raise ArgumentError, 'either :method or :receiver is required' if (method && receiver) || (!method && !receiver)
+        # @sg-ignore Need to add nil check here
         super(name: name, **splat)
 
         @receiver_chain = receiver
@@ -69,30 +70,40 @@ module Solargraph
       #
       # @param api_map [ApiMap]
       # @return [Pin::Method, nil]
+      # @sg-ignore Declared return type ::Solargraph::Pin::Method, nil
+      #   does not match inferred type nil, false for
+      #   Solargraph::Pin::DelegatedMethod#resolve_method
       def resolve_method api_map
         return if @resolved_method
 
+        # @sg-ignore Need to add nil check here
         resolver = @receiver_chain.define(api_map, self, []).first
 
         unless resolver
-          Solargraph.logger.warn \
-            "Delegated receiver for #{path} was resolved to nil from `#{print_chain(@receiver_chain)}'"
+          # @sg-ignore Need to add nil check here
+          Solargraph.logger.warn "Delegated receiver for #{path} was resolved to nil from `#{print_chain(@receiver_chain)}'"
           return
         end
 
+        # @sg-ignore Need to add nil check here
         receiver_type = resolver.return_type
 
+        # @sg-ignore Need to add nil check here
         return if receiver_type.undefined?
 
         receiver_path, method_scope =
+          # @sg-ignore Need to add nil check here
           if @receiver_chain.constant?
             # HACK: the `return_type` of a constant is Class<Whatever>, but looking up a method expects
             # the arguments `"Whatever"` and `scope: :class`.
+            # @sg-ignore Need to add nil check here
             [receiver_type.to_s.sub(/^Class<(.+)>$/, '\1'), :class]
           else
+            # @sg-ignore Need to add nil check here
             [receiver_type.to_s, :instance]
           end
 
+        # @sg-ignore Need to add nil check here
         method_stack = api_map.get_method_stack(receiver_path, @receiver_method_name, scope: method_scope)
         @resolved_method = method_stack.first
       end

data/lib/solargraph/pin/documenting.rb

@@ -104,6 +104,7 @@ module Solargraph
         left = text.lines.map do |line|
           match = line.match(/^ +/)
           next 0 unless match
+          # @sg-ignore Need to add nil check here
           match[0].length
         end.min
         return text if left.nil? || left.zero?

data/lib/solargraph/pin/instance_variable.rb

@@ -3,13 +3,17 @@
 module Solargraph
   module Pin
     class InstanceVariable < BaseVariable
-      # @return [ComplexType]
+      # @sg-ignore Need to add nil check here
+      # @return [ComplexType, ComplexType::UniqueType]
       def binder
+        # @sg-ignore Need to add nil check here
         closure.binder
       end
 
+      # @sg-ignore Need to add nil check here
       # @return [::Symbol]
       def scope
+        # @sg-ignore Need to add nil check here
         closure.binder.scope
       end
 

data/lib/solargraph/pin/keyword.rb

@@ -11,10 +11,6 @@ module Solargraph
       def closure
         @closure ||= Pin::ROOT_PIN
       end
-
-      def name
-        @name
-      end
     end
   end
 end

data/lib/solargraph/pin/local_variable.rb

@@ -3,73 +3,29 @@
 module Solargraph
   module Pin
     class LocalVariable < BaseVariable
-      # @return [Range]
-      attr_reader :presence
-
-      def presence_certain?
-        @presence_certain
-      end
+      # @param api_map [ApiMap]
+      # @return [ComplexType, ComplexType::UniqueType]
+      def probe api_map
+        if presence_certain? && return_type && return_type&.defined?
+          # flow sensitive typing has already figured out this type
+          # has been downcast - use the type it figured out
+          # @sg-ignore flow sensitive typing should support ivars
+          return adjust_type api_map, return_type.qualify(api_map, *gates)
+        end
 
-      # @param assignment [AST::Node, nil]
-      # @param presence [Range, nil]
-      # @param presence_certain [Boolean]
-      # @param splat [Hash]
-      def initialize assignment: nil, presence: nil, presence_certain: false, **splat
-        super(**splat)
-        @assignment = assignment
-        @presence = presence
-        @presence_certain = presence_certain
+        super
       end
 
       def combine_with(other, attrs={})
-        new_attrs = {
-          assignment: assert_same(other, :assignment),
-          presence_certain: assert_same(other, :presence_certain?),
-        }.merge(attrs)
-        new_attrs[:presence] = assert_same(other, :presence) unless attrs.key?(:presence)
+        # keep this as a parameter
+        return other.combine_with(self, attrs) if other.is_a?(Parameter) && !self.is_a?(Parameter)
 
-        super(other, new_attrs)
-      end
-
-      # @param other_closure [Pin::Closure]
-      # @param other_loc [Location]
-      def visible_at?(other_closure, other_loc)
-        location.filename == other_loc.filename &&
-          presence.include?(other_loc.range.start) &&
-          match_named_closure(other_closure, closure)
+        super
       end
 
       def to_rbs
         (name || '(anon)') + ' ' + (return_type&.to_rbs || 'untyped')
       end
-
-      private
-
-      # @param tag1 [String]
-      # @param tag2 [String]
-      # @return [Boolean]
-      def match_tags tag1, tag2
-        # @todo This is an unfortunate hack made necessary by a discrepancy in
-        #   how tags indicate the root namespace. The long-term solution is to
-        #   standardize it, whether it's `Class<>`, an empty string, or
-        #   something else.
-        tag1 == tag2 ||
-          (['', 'Class<>'].include?(tag1) && ['', 'Class<>'].include?(tag2))
-      end
-
-      # @param needle [Pin::Base]
-      # @param haystack [Pin::Base]
-      # @return [Boolean]
-      def match_named_closure needle, haystack
-        return true if needle == haystack || haystack.is_a?(Pin::Block)
-        cursor = haystack
-        until cursor.nil?
-          return true if needle.path == cursor.path
-          return false if cursor.path && !cursor.path.empty?
-          cursor = cursor.closure
-        end
-        false
-      end
     end
   end
 end

data/lib/solargraph/pin/method.rb

@@ -22,8 +22,9 @@ module Solargraph
       # @param attribute [Boolean]
       # @param signatures [::Array<Signature>, nil]
       # @param anon_splat [Boolean]
+      # @param context [ComplexType, ComplexType::UniqueType, nil]
       def initialize visibility: :public, explicit: true, block: :undefined, node: nil, attribute: false, signatures: nil, anon_splat: false,
-                     **splat
+                     context: nil, **splat
         super(**splat)
         @visibility = visibility
         @explicit = explicit
@@ -32,26 +33,7 @@ module Solargraph
         @attribute = attribute
         @signatures = signatures
         @anon_splat = anon_splat
-      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
+        @context = context if context
       end
 
       # @param other [Pin::Method]
@@ -66,20 +48,6 @@ module Solargraph
         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?
@@ -92,7 +60,6 @@ module Solargraph
         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),
@@ -160,6 +127,8 @@ module Solargraph
         !block.nil?
       end
 
+      # @sg-ignore flow sensitive typing needs to remove literal with
+      #   this unless block
       # @return [Pin::Signature, nil]
       def block
         return @block unless @block == :undefined
@@ -179,9 +148,10 @@ module Solargraph
       end
 
       # @param parameters [::Array<Parameter>]
-      # @param return_type [ComplexType]
+      # @param return_type [ComplexType, nil]
       # @return [Signature]
       def generate_signature(parameters, return_type)
+        # @type [Pin::Signature, nil]
         block = nil
         yieldparam_tags = docstring.tags(:yieldparam)
         yieldreturn_tags = docstring.tags(:yieldreturn)
@@ -202,6 +172,7 @@ module Solargraph
               comments: p.text,
               name: name,
               decl: decl,
+              # @sg-ignore flow sensitive typing needs to handle attrs
               presence: location ? location.range : nil,
               return_type: ComplexType.try_parse(*p.types),
               source: source
@@ -247,6 +218,7 @@ module Solargraph
         else
           "(#{signatures.first.parameters.map(&:full).join(', ')}) " unless signatures.first.parameters.empty?
         end.to_s
+        # @sg-ignore Need to add nil check here
         detail += "=#{probed? ? '~' : (proxied? ? '^' : '>')} #{return_type.to_s}" unless return_type.undefined?
         detail.strip!
         return nil if detail.empty?
@@ -276,6 +248,7 @@ module Solargraph
         return nil if signatures.empty?
 
         rbs = "def #{name}: #{signatures.first.to_rbs}"
+        # @sg-ignore Need to add nil check here
         signatures[1..].each do |sig|
           rbs += "\n"
           rbs += (' ' * (4 + name.length))
@@ -294,6 +267,7 @@ module Solargraph
       end
 
       def typify api_map
+        # @sg-ignore Need to add nil check here
         logger.debug { "Method#typify(self=#{self}, binder=#{binder}, closure=#{closure}, context=#{context.rooted_tags}, return_type=#{return_type.rooted_tags}) - starting" }
         decl = super
         unless decl.undefined?
@@ -303,6 +277,7 @@ module Solargraph
         type = see_reference(api_map) || typify_from_super(api_map)
         logger.debug { "Method#typify(self=#{self}) - type=#{type&.rooted_tags.inspect}" }
         unless type.nil?
+          # @sg-ignore Need to add nil check here
           qualified = type.qualify(api_map, *closure.gates)
           logger.debug { "Method#typify(self=#{self}) => #{qualified.rooted_tags.inspect}" }
           return qualified
@@ -396,7 +371,7 @@ module Solargraph
         attribute? ? infer_from_iv(api_map) : infer_from_return_nodes(api_map)
       end
 
-      # @return [::Array<Pin::Method>]
+      # @return [::Array<Pin::Signature>]
       def overloads
         # Ignore overload tags with nil parameters. If it's not an array, the
         # tag's source is likely malformed.
@@ -414,6 +389,7 @@ module Solargraph
                 comments: tag.docstring.all.to_s,
                 name: name,
                 decl: decl,
+                # @sg-ignore flow sensitive typing needs to handle attrs
                 presence: location ? location.range : nil,
                 return_type: param_type_from_name(tag, src.first),
                 source: :overloads
@@ -468,10 +444,12 @@ module Solargraph
 
       attr_writer :documentation
 
+      # @sg-ignore Need to add nil check here
       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
+        # @sg-ignore Need to add nil check here
         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::') ||
@@ -485,6 +463,71 @@ module Solargraph
 
       private
 
+      # @param other [Pin::Method]
+      # @return [Array<Pin::Signature>]
+      def combine_signatures(other)
+        all_undefined = signatures.all? { |sig| !sig.return_type&.defined? }
+        other_all_undefined = other.signatures.all? { |sig| !sig.return_type&.defined? }
+        if all_undefined && !other_all_undefined
+          other.signatures
+        elsif other_all_undefined && !all_undefined
+          signatures
+        else
+          combine_signatures_by_type_arity(*signatures, *other.signatures)
+        end
+      end
+
+      # @param signature_pins [Array<Pin::Signature>]
+      #
+      # @return [Array<Pin::Signature>]
+      def combine_signatures_by_type_arity(*signature_pins)
+        # @type [Hash{Array => Array<Pin::Signature>}]
+        by_type_arity = {}
+        signature_pins.each do |signature_pin|
+          by_type_arity[signature_pin.type_arity] ||= []
+          by_type_arity[signature_pin.type_arity] << signature_pin
+        end
+
+        by_type_arity.transform_values! do |same_type_arity_signatures|
+          combine_same_type_arity_signatures same_type_arity_signatures
+        end
+        by_type_arity.values.flatten
+      end
+
+      # @param same_type_arity_signatures [Array<Pin::Signature>]
+      #
+      # @return [Array<Pin::Signature>]
+      def combine_same_type_arity_signatures(same_type_arity_signatures)
+        # This is an O(n^2) operation, so bail out if n is not small
+        return same_type_arity_signatures if same_type_arity_signatures.length > 10
+
+        # @param old_signatures [Array<Pin::Signature>]
+        # @param new_signature [Pin::Signature]
+        same_type_arity_signatures.reduce([]) do |old_signatures, new_signature|
+          next [new_signature] if old_signatures.empty?
+
+          found_merge = false
+          old_signatures.flat_map do |old_signature|
+            potential_new_signature = old_signature.combine_with(new_signature)
+
+            if potential_new_signature.type_arity == old_signature.type_arity
+              # the number of types in each parameter and return type
+              # match, so we found compatible signatures to merge.  If
+              # we increased the number of types, we'd potentially
+              # have taken away the ability to use parameter types to
+              # choose the correct return type (while Ruby doesn't
+              # dispatch based on type, RBS does distinguish overloads
+              # based on types, not just arity, allowing for type
+              # information describing how methods behave based on
+              # their input types)
+              old_signatures - [old_signature] + [potential_new_signature]
+            else
+              old_signatures + [new_signature]
+            end
+          end
+        end
+      end
+
       # @param name [String]
       # @param asgn [Boolean]
       #
@@ -532,19 +575,20 @@ module Solargraph
       end
 
       # @param api_map [ApiMap]
-      # @return [ComplexType, nil]
+      # @return [ComplexType, ComplexType::UniqueType, nil]
       def see_reference api_map
         # This should actually be an intersection type
-        # @param ref [YARD::Tags::Tag, Solargraph::Yard::Tags::RefTag]
+        # @param ref [YARD::Tags::Tag, 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
+          # @sg-ignore should actually be an intersection type
           result = resolve_reference(ref.owner.to_s, api_map)
           return result unless result.nil?
         end
         match = comments.match(/^[ \t]*\(see (.*)\)/m)
         return nil if match.nil?
+        # @sg-ignore Need to add nil check here
         resolve_reference match[1], api_map
       end
 
@@ -559,6 +603,7 @@ module Solargraph
         stack = rest_of_stack api_map
         return nil if stack.empty?
         stack.each do |pin|
+          # @sg-ignore Need to add nil check here
           return pin.return_type unless pin.return_type.undefined?
         end
         nil
@@ -566,7 +611,7 @@ module Solargraph
 
       # @param ref [String]
       # @param api_map [ApiMap]
-      # @return [ComplexType, nil]
+      # @return [ComplexType, ComplexType::UniqueType, nil]
       def resolve_reference ref, api_map
         parts = ref.split(/[.#]/)
         if parts.first.empty? || parts.one?
@@ -574,6 +619,7 @@ module Solargraph
         else
           fqns = api_map.qualify(parts.first, *gates)
           return ComplexType::UNDEFINED if fqns.nil?
+          # @sg-ignore Need to add nil check here
           path = fqns + ref[parts.first.length] + parts.last
         end
         pins = api_map.get_path_pins(path)
@@ -609,9 +655,11 @@ module Solargraph
           rng = Range.from_node(n)
           next unless rng
           clip = api_map.clip_at(
+            # @sg-ignore Need to add nil check here
             location.filename,
             rng.ending
           )
+          # @sg-ignore Need to add nil check here
           chain = Solargraph::Parser.chain(n, location.filename)
           type = chain.infer(api_map, self, clip.locals)
           result.push type unless type.undefined?

data/lib/solargraph/pin/method_alias.rb

@@ -26,6 +26,14 @@ module Solargraph
         :public
       end
 
+      def to_rbs
+        if scope == :class
+          "alias self.#{name} self.#{original}"
+        else
+          "alias #{name} #{original}"
+        end
+      end
+
       def path
         @path ||= namespace + (scope == :instance ? '#' : '.') + name
       end

data/lib/solargraph/pin/namespace.rb

@@ -26,7 +26,6 @@ module Solargraph
         @type = type
         @visibility = visibility
         if name.start_with?('::')
-          # @type [String]
           name = name[2..-1] || ''
           @closure = Solargraph::Pin::ROOT_PIN
         end
@@ -39,6 +38,7 @@ module Solargraph
           closure_name = if [Solargraph::Pin::ROOT_PIN, nil].include?(closure)
             ''
           else
+            # @sg-ignore Need to add nil check here
             closure.full_context.namespace + '::'
           end
           closure_name += parts.join('::')
@@ -48,6 +48,12 @@ module Solargraph
         @name = name
       end
 
+      def reset_generated!
+        @return_type = nil
+        @full_context = nil
+        @path = nil
+      end
+
       def to_rbs
         "#{@type.to_s} #{return_type.all_params.first.to_rbs}#{rbs_generics}".strip
       end