solargraph 0.60.4 → 0.62.0

data/lib/solargraph/source_map/mapper.rb

@@ -12,7 +12,7 @@ module Solargraph
 
       private_class_method :new
 
-      DIRECTIVE_REGEXP = /(@!method|@!attribute|@!visibility|@!domain|@!macro|@!parse|@!override)/
+      DIRECTIVE_REGEXP = /(@!method|@method|@!attribute|@!visibility|@!scope|@!domain|@!macro|@!parse|@!override)/
 
       # Generate the data.
       #
@@ -104,9 +104,13 @@ module Solargraph
         directive_processor = YardMap::Directives.for(directive)
         return unless directive_processor
 
-        @pins += directive_processor.process_directive(
+        new_pins = directive_processor.process_directive(
           @source, @pins, source_position, comment_position, directive
         )
+        # A @!scope directive in the indented text of another directive applies
+        # only to the object that directive defines.
+        YardMap::Directives::ScopeDirective.apply_nested directive, new_pins
+        @pins += new_pins
       end
 
       # @param comment [String]

data/lib/solargraph/source_map.rb

@@ -12,6 +12,7 @@ module Solargraph
     autoload :Clip,          'solargraph/source_map/clip'
     autoload :Completion,    'solargraph/source_map/completion'
     autoload :Data,          'solargraph/source_map/data'
+    autoload :Call,          'solargraph/source_map/call'
 
     # @return [Source]
     attr_reader :source
@@ -82,6 +83,16 @@ module Solargraph
       pins_by_class(Pin::Reference::Require)
     end
 
+    def calls *method_names
+      symbolized = method_names.map(&:to_sym)
+      node_map.find_by_type(:send).select { |node| node.children[0].nil? && symbolized.include?(node.children[1].to_sym) }
+              .map { |node| Call.new(self, Parser.chain(node), locate_namespace_pin(node.loc.line, node.loc.column)) }
+    end
+
+    def node_map
+      @node_map ||= Source::NodeMap.new(source.node)
+    end
+
     # @return [Environ]
     def conventions_environ
       @conventions_environ ||= Environ.new
@@ -128,6 +139,10 @@ module Solargraph
       _locate_pin line, character, Pin::Namespace, Pin::Method
     end
 
+    def locate_namespace_pin line, character
+      _locate_pin line, character, Pin::Namespace, Pin::Singleton
+    end
+
     # @param line [Integer]
     # @param character [Integer]
     # @return [Pin::Closure]
@@ -190,12 +205,14 @@ module Solargraph
       end
     end
 
-    private
-
     # @return [Array<Pin::Base>]
-    attr_writer :convention_pins
+    def convention_pins
+      @convention_pins || []
+    end
+
+    private
 
-    # @return [Hash{Class<Pin::Base> => Array<Pin::Base>}]
+    # @return [Hash{Class, Pin::Base => Array<Pin::Base>}]
     def pin_class_hash
       # @todo Need to support generic resolution in classify and transform_values
       @pin_class_hash ||= pins.to_set.classify(&:class).transform_values(&:to_a)
@@ -206,9 +223,12 @@ module Solargraph
       @data ||= Data.new(source)
     end
 
+    # @param pins [Array<Pin::Base>]
     # @return [Array<Pin::Base>]
-    def convention_pins
-      @convention_pins || []
+    def convention_pins= pins
+      # unmemoizing the document_symbols in case it was called from any of conventions
+      @document_symbols = nil
+      @convention_pins = pins
     end
 
     # @generic T
@@ -221,9 +241,8 @@ module Solargraph
       position = Position.new(line, character)
       found = nil
       pins.each do |pin|
-        # @todo Attribute pins should not be treated like closures, but
-        #   there's probably a better way to handle it
-        next if pin.is_a?(Pin::Method) && pin.attribute?
+        # A bodyless method pin covers its declaring statement's range but isn't a closure.
+        next if pin.is_a?(Pin::Method) && !pin.body?
         found = pin if (klasses.empty? || klasses.any? do |kls|
           pin.is_a?(kls)
           # @sg-ignore Need to add nil check here

data/lib/solargraph/type_checker/rules.rb

@@ -75,11 +75,11 @@ module Solargraph
       # @todo 22: Translate to something flow sensitive typing understands
       # @todo 3: Need a downcast here
       #
-      # flow sensitive typing could handle (96):
+      # flow sensitive typing could handle (99):
       #
       # @todo 36: flow sensitive typing needs to handle attrs
       # @todo 29: flow sensitive typing should be able to handle redefinition
-      # @todo 19: flow sensitive typing needs to narrow down type with an if is_a? check
+      # @todo 21: flow sensitive typing needs to narrow down type with an if is_a? check
       # @todo 13: Need to validate config
       # @todo 8: flow sensitive typing should support .class == .class
       # @todo 6: need boolish support for ? methods
@@ -113,6 +113,7 @@ module Solargraph
       # @todo 1: flow sensitive typing needs to create separate ranges for postfix if
       # @todo 1: flow sensitive typing needs to handle constants
       # @todo 1: flow sensitive typing needs to eliminate literal from union with return if foo == :bar
+      # @todo 1: Array#flatten returns a bare Array
       def require_all_unique_types_match_expected?
         report?(:require_all_unique_types_match_expected, :strong)
       end

data/lib/solargraph/type_checker.rb

@@ -141,6 +141,8 @@ module Solargraph
     # @return [Array<Problem>]
     def method_return_type_problems_for pin
       return [] if pin.is_a?(Pin::MethodAlias)
+      # An unresolvable DelegatedMethod's type comes from its @!method directive, not a @return tag.
+      return [] if pin.is_a?(Pin::DelegatedMethod) && !pin.resolvable?(api_map)
       result = []
       declared = pin.typify(api_map).self_to_type(pin.full_context).qualify(api_map, *pin.gates)
       if declared.undefined?
@@ -219,7 +221,7 @@ module Solargraph
         params = param_details_from_stack(sig, stack)
         if rules.require_type_tags?
           sig.parameters.each do |par|
-            break if %i[restarg kwrestarg blockarg].include?(par.decl)
+            break if %i[restarg kwrestarg blockarg forward_args].include?(par.decl)
             unless params[par.name]
               if pin.attribute?
                 inferred = pin.probe(api_map).self_to_type(pin.full_context)
@@ -388,6 +390,7 @@ module Solargraph
       return [] unless last_base_link.is_a?(Solargraph::Source::Chain::Call)
 
       arguments = last_base_link.arguments
+      return [] if any_forwarded_args?(arguments.map(&:node))
 
       pins = base.define(api_map, closure_pin, locals)
 

data/lib/solargraph/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Solargraph
-  VERSION = ENV.fetch('SOLARGRAPH_FORCE_VERSION', '0.60.4')
+  VERSION = ENV.fetch('SOLARGRAPH_FORCE_VERSION', '0.62.0')
 end

data/lib/solargraph/workspace.rb

@@ -10,7 +10,6 @@ module Solargraph
   #
   class Workspace
     autoload :Config, 'solargraph/workspace/config'
-    autoload :Gemspecs, 'solargraph/workspace/gemspecs'
     autoload :RequirePaths, 'solargraph/workspace/require_paths'
 
     # @return [String]

data/lib/solargraph/yard_map/cache.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     class Cache
       def initialize
         # @type [Hash{String => Array<Solargraph::Pin::Base>}]

data/lib/solargraph/yard_map/directives/attribute_directive.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     module Directives
       module AttributeDirective
         module_function

data/lib/solargraph/yard_map/directives/domain_directive.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     module Directives
       module DomainDirective
         module_function

data/lib/solargraph/yard_map/directives/method_directive.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     module Directives
       module MethodDirective
         module_function

data/lib/solargraph/yard_map/directives/override_directive.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     module Directives
       module OverrideDirective
         module_function

data/lib/solargraph/yard_map/directives/parse_directive.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     module Directives
       module ParseDirective
         module_function

data/lib/solargraph/yard_map/directives/scope_directive.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module YardMap
+    module Directives
+      # Implements YARD's @!scope directive.
+      #
+      # As described in YARD::Tags::ScopeDirective, a @!scope directive that
+      # appears in a docstring attached to a method definition applies only to
+      # that method. Anywhere else it applies to all of the methods that follow
+      # it within the namespace it was defined in.
+      #
+      #   class Example
+      #     # @!scope class
+      #     def foo; end  # => Example.foo
+      #
+      #     def bar; end  # => Example#bar
+      #   end
+      #
+      #   class Other
+      #     # @!scope class
+      #
+      #     def foo; end  # => Other.foo
+      #
+      #     def bar; end  # => Other.bar
+      #   end
+      #
+      module ScopeDirective
+        module_function
+
+        VALID_SCOPES = %i[class instance].freeze
+
+        # Directives that define an object whose scope is inherited from a
+        # @!scope directive. @!parse is not one of them because the code it
+        # contains already declares the scope of everything it defines.
+        SCOPED_DIRECTIVES = %w[method attribute].freeze
+
+        # @param source [Solargraph::Source]
+        # @param pins [Array<Solargraph::Pin::Base>]
+        # @param source_position [Position]
+        # @param comment_position [Position]
+        # @param directive [YARD::Tags::Directive]
+        # @return [Array<Solargraph::Pin::Base>]
+        def process_directive source, pins, source_position, comment_position, directive
+          kind = parse_scope directive
+          return [] if kind.nil?
+
+          attached = attached_method pins, source_position
+          if attached && no_empty_lines?(source.code, comment_position.line, source_position.line)
+            attached.scope = kind
+          else
+            apply_to_namespace pins, kind, source_position
+          end
+
+          []
+        end
+
+        # @param directive [YARD::Tags::Directive]
+        # @return [::Symbol, nil] :class, :instance, or nil if the directive is malformed
+        def parse_scope directive
+          kind = directive.tag.text.to_s.strip.downcase.to_sym
+          VALID_SCOPES.include?(kind) ? kind : nil
+        end
+
+        # True if the scope of the object defined by this directive can be set
+        # by a @!scope directive.
+        #
+        # @param directive [YARD::Tags::Directive]
+        # @return [Boolean]
+        def scopes_directive? directive
+          SCOPED_DIRECTIVES.include? directive.tag.tag_name
+        end
+
+        # The scope set by a @!scope directive that appears in the indented
+        # text of another directive:
+        #
+        #   @!method foo
+        #     @!scope class
+        #
+        # YARD parses the indented text of a directive with a state of its own,
+        # so a directive nested this way applies only to the object the
+        # enclosing directive defines. It never affects the objects that
+        # follow.
+        #
+        # @param directive [YARD::Tags::Directive]
+        # @return [::Symbol, nil] :class, :instance, or nil if there is none
+        def nested_scope directive
+          text = directive.tag.text.to_s
+          return nil unless text.include? '@!scope'
+
+          kind = nil
+          Solargraph::Source.parse_docstring(text).directives.each do |nested|
+            next unless nested.tag.tag_name == 'scope'
+
+            # A later directive overrides an earlier one, but an invalid value
+            # leaves the current one in place, as it does in YARD.
+            kind = parse_scope(nested) || kind
+          end
+          kind
+        end
+
+        # Set the scope of pins generated by a directive.
+        #
+        # @param pins [Array<Solargraph::Pin::Base>]
+        # @param kind [::Symbol, nil] :class or :instance; nothing happens if nil
+        # @return [void]
+        def apply_scope pins, kind
+          return if kind.nil?
+
+          # Only methods have a scope. Applying one to any other kind of pin,
+          # such as a namespace generated by @!parse, would corrupt its path.
+          pins.each { |pin| pin.scope = kind if pin.is_a?(Pin::Method) }
+        end
+
+        # Apply a @!scope directive from the indented text of another directive
+        # to the pins that directive generated.
+        #
+        # @param directive [YARD::Tags::Directive]
+        # @param pins [Array<Solargraph::Pin::Base>] the pins generated by the directive
+        # @return [void]
+        def apply_nested directive, pins
+          return unless scopes_directive? directive
+
+          apply_scope pins, nested_scope(directive)
+        end
+
+        # Applies the scope to each method that follows the directive within
+        # the namespace the directive appears in. Methods in nested namespaces
+        # are excluded, since the directive only affects its own namespace.
+        #
+        # @param pins [Array<Solargraph::Pin::Base>]
+        # @param kind [::Symbol] :class or :instance
+        # @param source_position [Position]
+        # @return [void]
+        def apply_to_namespace pins, kind, source_position
+          namespace = namespace_at pins, source_position
+          return if namespace.nil?
+
+          pins.each do |pin|
+            next unless pin.is_a?(Pin::Method)
+            next unless pin.namespace == namespace.path
+            # @sg-ignore flow sensitive typing should narrow location after the nil check
+            next if pin.location.nil? || pin.location.range.start.line < source_position.line
+
+            pin.scope = kind
+          end
+        end
+
+        # The method defined on the line the comment is attached to, if any.
+        #
+        # @param pins [Array<Solargraph::Pin::Base>]
+        # @param source_position [Position]
+        # @return [Pin::Method, nil]
+        def attached_method pins, source_position
+          pins.select { |pin| pin.is_a?(Pin::Method) && pin.location&.range&.contain?(source_position) }.last
+        end
+
+        # @param pins [Array<Solargraph::Pin::Base>]
+        # @param position [Position]
+        # @return [Pin::Namespace, nil]
+        def namespace_at pins, position
+          pins.select { |pin| pin.is_a?(Pin::Namespace) && pin.location&.range&.contain?(position) }.last
+        end
+
+        # @param code [String]
+        # @param line1 [Integer]
+        # @param line2 [Integer]
+        # @return [Boolean]
+        def no_empty_lines? code, line1, line2
+          lines = code.lines[line1..line2]
+          return false if lines.nil?
+
+          lines.none? { |line| line.strip.empty? }
+        end
+      end
+    end
+  end
+end

data/lib/solargraph/yard_map/directives/visibility_directive.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     module Directives
       module VisibilityDirective
         module_function

data/lib/solargraph/yard_map/directives.rb

@@ -1,17 +1,18 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     module Directives
       autoload :AttributeDirective, 'solargraph/yard_map/directives/attribute_directive'
       autoload :MethodDirective, 'solargraph/yard_map/directives/method_directive'
       autoload :DomainDirective, 'solargraph/yard_map/directives/domain_directive'
       autoload :OverrideDirective, 'solargraph/yard_map/directives/override_directive'
       autoload :ParseDirective, 'solargraph/yard_map/directives/parse_directive'
+      autoload :ScopeDirective, 'solargraph/yard_map/directives/scope_directive'
       autoload :VisibilityDirective, 'solargraph/yard_map/directives/visibility_directive'
 
       # @param directive [YARD::Tags::Directive]
-      # @return [Class<AttributeDirective>, Class<MethodDirective>, Class<DomainDirective>, Class<OverrideDirective>, Class<ParseDirective>, Class<VisibilityDirective>, nil]
+      # @return [Class<AttributeDirective>, Class<MethodDirective>, Class<DomainDirective>, Class<OverrideDirective>, Class<ParseDirective>, Class<ScopeDirective>, Class<VisibilityDirective>, nil]
       def self.for directive
         case directive.tag.tag_name
         when 'attribute'
@@ -24,6 +25,8 @@ module Solargraph
           OverrideDirective
         when 'parse'
           ParseDirective
+        when 'scope'
+          ScopeDirective
         when 'visibility'
           VisibilityDirective
         else # rubocop:disable Style/EmptyElse

data/lib/solargraph/yard_map/helpers.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     module Helpers
       module_function
 

data/lib/solargraph/yard_map/macro.rb

@@ -1,9 +1,26 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     class Macro
-      PROCESSABLE_DIRECTIVES = %w[method attribute parse].freeze
+      PROCESSABLE_DIRECTIVES = %w[method attribute parse scope].freeze
+
+      # Directives whose text is a value rather than a definition. The comments
+      # attached to the macro's call site belong to the objects the macro
+      # generates, but adding them to one of these directives would invalidate
+      # its content.
+      VALUE_DIRECTIVES = %w[parse scope].freeze
+
+      # Directives that define an object capable of owning @overload tags.
+      OVERLOAD_OWNERS = %w[method attribute parse].freeze
+
+      # The directive used to generate a pin for the @overload tags a macro
+      # declares without an owning @!method directive. Its arguments are
+      # represented by (...) so that any of the overloads remains valid.
+      OVERLOAD_METHOD_DIRECTIVE = '@!method $1(...)'
+
+      # An @overload tag that starts a line of a macro's text.
+      OVERLOAD_TAG_LINE = /^\s*@overload(\s|$)/
 
       class << self
         # @param directive [YARD::Tags::Directive]
@@ -73,13 +90,34 @@ module Solargraph
       # @return [Array<Pin::Base>]
       def generate_pins_from chain, pin, source_map
         call_location = Solargraph::Location.from_node(chain.node)
+        return [] unless call_location
+
+        # A @!scope directive in a macro applies to the objects the macro
+        # generates after it, the same way it applies to the objects that
+        # follow it in a namespace. Its effect ends with the macro.
+        #
+        # @type [::Symbol, nil]
+        inherited_scope = nil
+
         # @param generated_pins [Array<Pin::Base>]
         generate_yardoc_from(chain, source_map).reduce([]) do |generated_pins, directive|
+          # @sg-ignore flow sensitive typing confuses this block variable with the #directive attr reader
+          if directive.tag.tag_name == 'scope'
+            inherited_scope = Directives::ScopeDirective.parse_scope(directive) || inherited_scope
+            next generated_pins
+          end
           directive_processor = YardMap::Directives.for(directive)
-          next generated_pins unless directive_processor && call_location
-          generated_pins + directive_processor.process_directive(
+          next generated_pins unless directive_processor
+          new_pins = directive_processor.process_directive(
             source_map.source, source_map.pins, call_location.range.start, call_location.range.start, directive
           )
+          if Directives::ScopeDirective.scopes_directive?(directive)
+            # A @!scope directive nested in another directive's text applies
+            # only to the object that directive defines.
+            scope = Directives::ScopeDirective.nested_scope(directive) || inherited_scope
+            Directives::ScopeDirective.apply_scope new_pins, scope
+          end
+          generated_pins + new_pins
         end
       end
 
@@ -96,18 +134,59 @@ module Solargraph
         code = source_map.source.code_for(chain.node)
         expanded_comment = macro_object.expand([name, *values], code)
                                        .gsub(/\n(?!@!|\s)/, "\n  ")
-        directives = Solargraph::Source.parse_docstring(expanded_comment).directives.select do |directive|
+        parsed_docstring = Solargraph::Source.parse_docstring(expanded_comment)
+        directives = parsed_docstring.directives.select do |directive|
           PROCESSABLE_DIRECTIVES.include?(directive.tag.tag_name)
         end
+        # A macro can document the methods it generates with bare @overload
+        # tags instead of wrapping them in a @!method directive. Those overloads
+        # have no pin to attach to and would otherwise be discarded, so
+        # generate the pin they describe.
+        if declares_overloads? && directives.none? { |directive| OVERLOAD_OWNERS.include?(directive.tag.tag_name) }
+          directives += generate_overload_directives([name, *values], code)
+        end
         directives.each do |directive|
+          next if VALUE_DIRECTIVES.include? directive.tag.tag_name
+
           # @sg-ignore chain.node is assumed to exist
           comments = source_map.source.comments_for(chain.node)
-          if comments&.length&.positive? && directive.tag.tag_name != 'parse'
+          if comments&.length&.positive?
             directive.tag.text += "\n#{comments}"
           end
         end
         directives
       end
+
+      # True if the macro declares @overload tags. The tags are read from the
+      # macro's text and not from its parsed docstring because the indentation
+      # a macro's content ends up with can nest the tags inside other objects.
+      #
+      # @return [Boolean]
+      def declares_overloads?
+        text.match?(OVERLOAD_TAG_LINE)
+      end
+
+      # Generates the @!method directive for a macro's bare @overload tags. The
+      # pin takes the name the macro generates, that is, the pin a
+      # @!method $1(...) directive would produce, and keeps the overloads in
+      # its comments.
+      #
+      # The macro's unprocessed text is used here and not its macro data. The
+      # data is re-indented for @! directives, which flattens the nesting that
+      # keeps a @param attached to the @overload it describes.
+      #
+      # @param call_params [Array<String>]
+      # @param code [String]
+      # @return [Array<YARD::Tags::Directive>]
+      def generate_overload_directives call_params, code
+        body = text.each_line.map { |line| "  #{line}" }.join
+        expanded = YARD::CodeObjects::MacroObject.expand(
+          "#{OVERLOAD_METHOD_DIRECTIVE}\n#{body}", call_params, code
+        )
+        Solargraph::Source.parse_docstring(expanded).directives.select do |directive|
+          directive.tag.tag_name == 'method'
+        end
+      end
     end
   end
 end

data/lib/solargraph/yard_map/mapper/to_constant.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     class Mapper
       module ToConstant
         extend YardMap::Helpers

data/lib/solargraph/yard_map/mapper/to_method.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     class Mapper
       module ToMethod
         extend YardMap::Helpers

data/lib/solargraph/yard_map/mapper/to_namespace.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     class Mapper
       module ToNamespace
         extend YardMap::Helpers

data/lib/solargraph/yard_map/mapper.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Solargraph
-  class YardMap
+  module YardMap
     class Mapper
       autoload :ToMethod, 'solargraph/yard_map/mapper/to_method'
       autoload :ToNamespace, 'solargraph/yard_map/mapper/to_namespace'
@@ -33,7 +33,7 @@ module Solargraph
       private
 
       def core_store
-        @core_store ||= ApiMap::Store.new(RbsMap::CoreMap.new.pins)
+        @core_store ||= ApiMap::Store.new(RbsMap::Core.new.pins)
       end
 
       # @param code_object [YARD::CodeObjects::Base]

data/lib/solargraph/yard_map.rb

@@ -7,7 +7,7 @@ module Solargraph
   # The YardMap provides access to YARD documentation for the Ruby core, the
   # stdlib, and gems.
   #
-  class YardMap
+  module YardMap
     class NoYardocError < StandardError; end
 
     autoload :Cache,       'solargraph/yard_map/cache'