solargraph 0.52.0 → 0.53.0

data/lib/solargraph/source/chain.rb

@@ -19,8 +19,10 @@ module Solargraph
       autoload :GlobalVariable,   'solargraph/source/chain/global_variable'
       autoload :Literal,          'solargraph/source/chain/literal'
       autoload :Head,             'solargraph/source/chain/head'
+      autoload :If,               'solargraph/source/chain/if'
       autoload :Or,               'solargraph/source/chain/or'
       autoload :BlockVariable,    'solargraph/source/chain/block_variable'
+      autoload :BlockSymbol,      'solargraph/source/chain/block_symbol'
       autoload :ZSuper,           'solargraph/source/chain/z_super'
       autoload :Hash,             'solargraph/source/chain/hash'
       autoload :Array,            'solargraph/source/chain/array'
@@ -36,7 +38,9 @@ module Solargraph
 
       attr_reader :node
 
+      # @param node [Parser::AST::Node, nil]
       # @param links [::Array<Chain::Link>]
+      # @param splat [Boolean]
       def initialize links, node = nil, splat = false
         @links = links.clone
         @links.push UNDEFINED_CALL if @links.empty?
@@ -57,7 +61,8 @@ module Solargraph
 
       # @param api_map [ApiMap]
       # @param name_pin [Pin::Base]
-      # @param locals [Array<Pin::Base>]
+      # @param locals [::Enumerable<Pin::LocalVariable>]
+      #
       # @return [::Array<Pin::Base>]
       def define api_map, name_pin, locals
         return [] if undefined?
@@ -74,7 +79,7 @@ module Solargraph
 
       # @param api_map [ApiMap]
       # @param name_pin [Pin::Base]
-      # @param locals [Array<Pin::Base>]
+      # @param locals [::Enumerable<Pin::LocalVariable>]
       # @return [ComplexType]
       def infer api_map, name_pin, locals
         from_here = base.infer(api_map, name_pin, locals) unless links.length == 1
@@ -114,12 +119,16 @@ module Solargraph
 
       private
 
-      # @param pins [Array<Pin::Base>]
+      # @param pins [::Array<Pin::Base>]
       # @param context [Pin::Base]
       # @param api_map [ApiMap]
+      # @param locals [::Enumerable<Pin::LocalVariable>]
       # @return [ComplexType]
       def infer_first_defined pins, context, api_map, locals
         possibles = []
+        # @todo this param tag shouldn't be needed to probe the type
+        # @todo ...but given it is needed, typecheck should complain that it is needed
+        # @param pin [Pin::Base]
         pins.each do |pin|
           # Avoid infinite recursion
           next if @@inference_stack.include?(pin.identity)
@@ -129,6 +138,9 @@ module Solargraph
           @@inference_stack.pop
           if type.defined?
             if type.generic?
+              # @todo even at strong, no typechecking complaint
+              #   happens when a [Pin::Base,nil] is passed into a method
+              #   that accepts only [Pin::Namespace] as an argument
               type = type.resolve_generics(pin.closure, context.return_type)
             end
             if type.defined?
@@ -142,6 +154,7 @@ module Solargraph
           return ComplexType::UNDEFINED if @@inference_depth >= 10 && pins.first.is_a?(Pin::Method)
 
           @@inference_depth += 1
+          # @param pin [Pin::Base]
           pins.each do |pin|
             # Avoid infinite recursion
             next if @@inference_stack.include?(pin.identity)
@@ -157,6 +170,7 @@ module Solargraph
           @@inference_depth -= 1
         end
         return ComplexType::UNDEFINED if possibles.empty?
+
         type = if possibles.length > 1
           sorted = possibles.map { |t| t.rooted? ? "::#{t}" : t.to_s }.sort { |a, _| a == 'nil' ? 1 : 0 }
           ComplexType.parse(*sorted)
@@ -164,10 +178,12 @@ module Solargraph
           ComplexType.parse(possibles.map(&:to_s).join(', '))
         end
         return type if context.nil? || context.return_type.undefined?
-        type.self_to(context.return_type.namespace)
+
+        type.self_to(context.return_type.tag)
       end
 
       # @param type [ComplexType]
+      # @return [ComplexType]
       def maybe_nil type
         return type if type.undefined? || type.void? || type.nullable?
         return type unless nullable?

data/lib/solargraph/source/change.rb

@@ -69,6 +69,9 @@ module Solargraph
 
       private
 
+      # @param text [String]
+      # @param insert [String]
+      # @return [String]
       def commit text, insert
         start_offset = Position.to_offset(text, range.start)
         end_offset = Position.to_offset(text, range.ending)

data/lib/solargraph/source/cursor.rb

@@ -115,6 +115,7 @@ module Solargraph
       end
       alias receiver recipient
 
+      # @return [AST::Node]
       def node
         @node ||= source.node_at(position.line, position.column)
       end
@@ -135,6 +136,7 @@ module Solargraph
         end
       end
 
+      # @return [Parser::AST::Node, nil]
       def recipient_node
         @recipient_node ||= Solargraph::Parser::NodeMethods.find_recipient_node(self)
       end

data/lib/solargraph/source/source_chainer.rb

@@ -14,10 +14,10 @@ module Solargraph
 
       class << self
         # @param source [Source]
-        # @param position [Position]
+        # @param position [Position, Array(Integer, Integer)]
         # @return [Source::Chain]
         def chain source, position
-          new(source, position).chain
+          new(source, Solargraph::Position.normalize(position)).chain
         end
       end
 
@@ -41,8 +41,6 @@ module Solargraph
           parent = nil
           if !source.repaired? && source.parsed? && source.synchronized?
             tree = source.tree_at(position.line, position.column)
-            # node, parent = source.tree_at(position.line, position.column)[0..2]
-            tree.shift while tree.length > 1 && tree.first.type == :SCOPE
             node, parent = tree[0..2]
           elsif source.parsed? && source.repaired? && end_of_phrase == '.'
             node, parent = source.tree_at(fixed_position.line, fixed_position.column)[0..2]
@@ -60,7 +58,7 @@ module Solargraph
         end
         return Chain.new([Chain::UNDEFINED_CALL]) if node.nil? || (node.type == :sym && !phrase.start_with?(':'))
         # chain = NodeChainer.chain(node, source.filename, parent && parent.type == :block)
-        chain = Parser.chain(node, source.filename, parent && [:ITER, :block].include?(parent.type))
+        chain = Parser.chain(node, source.filename, parent)
         if source.repaired? || !source.parsed? || !source.synchronized?
           if end_of_phrase.strip == '.'
             chain.links.push Chain::UNDEFINED_CALL
@@ -128,10 +126,13 @@ module Solargraph
         Position.line_char_to_offset(@source.code, line, column)
       end
 
+      # @return [Integer]
       def signature_data
         @signature_data ||= get_signature_data_at(offset)
       end
 
+      # @param index [Integer]
+      # @return [Integer]
       def get_signature_data_at index
         brackets = 0
         squares = 0

data/lib/solargraph/source.rb

@@ -8,7 +8,6 @@ module Solargraph
   class Source
     autoload :Updater,       'solargraph/source/updater'
     autoload :Change,        'solargraph/source/change'
-    autoload :Mapper,        'solargraph/source/mapper'
     autoload :EncodingFixes, 'solargraph/source/encoding_fixes'
     autoload :Cursor,        'solargraph/source/cursor'
     autoload :Chain,         'solargraph/source/chain'
@@ -213,6 +212,7 @@ module Solargraph
       end
     end
 
+    # @return [::Array<Range>]
     def string_ranges
       @string_ranges ||= Parser.string_ranges(node)
     end
@@ -250,7 +250,7 @@ module Solargraph
     end
 
     # @param node [Parser::AST::Node]
-    # @return [String]
+    # @return [String, nil]
     def comments_for node
       rng = Range.from_node(node)
       stringified_comments[rng.start.line] ||= begin
@@ -301,7 +301,7 @@ module Solargraph
 
     # Get a hash of comments grouped by the line numbers of the associated code.
     #
-    # @return [Hash{Integer => Array<Parser::Source::Comment>}]
+    # @return [Hash{Integer => String}]
     def associated_comments
       @associated_comments ||= begin
         result = {}
@@ -323,6 +323,8 @@ module Solargraph
 
     private
 
+    # @param line [Integer]
+    # @return [Integer]
     def first_not_empty_from line
       cursor = line
       cursor += 1 while cursor < code_lines.length && code_lines[cursor].strip.empty?
@@ -411,7 +413,7 @@ module Solargraph
       result
     end
 
-    # @param n [Parser::AST::Node]
+    # @param n [Parser::AST::Node, nil]
     # @return [Array<Parser::AST::Node>]
     def string_nodes_in n
       result = []
@@ -425,30 +427,23 @@ module Solargraph
       result
     end
 
-    # @param node [Parser::AST::Node]
+    # @param node [Parser::AST::Node, nil]
     # @param position [Position]
     # @param stack [Array<Parser::AST::Node>]
     # @return [void]
     def inner_tree_at node, position, stack
       return if node.nil?
       here = Range.from_node(node)
-      if here.contain?(position) || colonized(here, position, node)
+      if here.contain?(position)
         stack.unshift node
         node.children.each do |c|
           next unless Parser.is_ast_node?(c)
-          next if !Parser.rubyvm? && c.loc.expression.nil?
+          next if c.loc.expression.nil?
           inner_tree_at(c, position, stack)
         end
       end
     end
 
-    def colonized range, position, node
-      node.type == :COLON2 &&
-        range.ending.line == position.line &&
-        range.ending.character == position.character - 2 &&
-        code[Position.to_offset(code, Position.new(position.line, position.character - 2)), 2] == '::'
-    end
-
     protected
 
     # @return [String]
@@ -464,7 +459,7 @@ module Solargraph
       @code = val
     end
 
-    # @return [Parser::AST::Node]
+    # @return [Parser::AST::Node, nil]
     attr_writer :node
 
     # @return [Array<Range>]
@@ -476,7 +471,7 @@ module Solargraph
     # @return [Boolean]
     attr_writer :parsed
 
-    # @return [Array<Parser::Source::Comment>]
+    # @return [Hash{Integer => String}
     attr_writer :comments
 
     # @return [Boolean]
@@ -516,6 +511,10 @@ module Solargraph
         # HACK: Pass a dummy code object to the parser for plugins that
         # expect it not to be nil
         YARD::Docstring.parser.parse(comments, YARD::CodeObjects::Base.new(:root, 'stub'))
+      rescue StandardError => e
+        Solargraph.logger.info "YARD failed to parse docstring: [#{e.class}] #{e.message}"
+        Solargraph.logger.debug "Unparsed comment: #{comments}"
+        YARD::Docstring.parser
       end
     end
   end

data/lib/solargraph/source_map/clip.rb

@@ -13,7 +13,7 @@ module Solargraph
         @cursor = cursor
       end
 
-      # @return [Array<Pin::Base>]
+      # @return [Array<Pin::Base>] Relevant pins for infering the type of the Cursor's position
       def define
         return [] if cursor.comment? || cursor.chain.literal?
         result = cursor.chain.define(api_map, block, locals)
@@ -55,18 +55,19 @@ module Solargraph
           return ComplexType.try_parse('Object') if dfn && dfn.path == 'Class#new'
         end
         return result unless result.tag == 'self'
-        ComplexType.try_parse(cursor.chain.base.infer(api_map, block, locals).namespace)
+        ComplexType.try_parse(cursor.chain.base.infer(api_map, block, locals).tag)
       end
 
       # Get an array of all the locals that are visible from the cursors's
       # position. Locals can be local variables, method parameters, or block
       # parameters. The array starts with the nearest local pin.
       #
-      # @return [Array<Solargraph::Pin::Base>]
+      # @return [::Array<Solargraph::Pin::Base>]
       def locals
         @locals ||= source_map.locals_at(location)
       end
 
+      # @return [::Array<String>]
       def gates
         block.gates
       end
@@ -99,11 +100,12 @@ module Solargraph
         @source_map ||= api_map.source_map(cursor.filename)
       end
 
+      # @return [Location]
       def location
         Location.new(source_map.filename, Solargraph::Range.new(cursor.position, cursor.position))
       end
 
-      # @return [Solargraph::Pin::Base]
+      # @return [Solargraph::Pin::Closure]
       def block
         @block ||= source_map.locate_block_pin(cursor.node_position.line, cursor.node_position.character)
       end
@@ -115,7 +117,7 @@ module Solargraph
         @context_pin ||= source_map.locate_named_path_pin(cursor.node_position.line, cursor.node_position.character)
       end
 
-      # @return [Array<Pin::KeywordParam]
+      # @return [Array<Pin::KeywordParam>]
       def complete_keyword_parameters
         return [] unless cursor.argument? && cursor.chain.links.one? && cursor.word =~ /^[a-z0-9_]*:?$/
         pins = signify
@@ -139,7 +141,7 @@ module Solargraph
         result
       end
 
-      # @param result [Array<Pin::Base>]
+      # @param result [Enumerable<Pin::Base>]
       # @return [Completion]
       def package_completions result
         frag_start = cursor.start_of_word.to_s.downcase
@@ -150,6 +152,7 @@ module Solargraph
         Completion.new(filtered, cursor.range)
       end
 
+      # @return [Completion]
       def tag_complete
         result = []
         match = source_map.code[0..cursor.offset-1].match(/[\[<, ]([a-z0-9_:]*)\z/i)
@@ -168,6 +171,7 @@ module Solargraph
         package_completions(result)
       end
 
+      # @return [Completion]
       def code_complete
         result = []
         result.concat complete_keyword_parameters
@@ -209,13 +213,13 @@ module Solargraph
             result.concat api_map.get_constants(context_pin.context.namespace, *gates)
             result.concat api_map.get_methods(block.binder.namespace, scope: block.binder.scope, visibility: [:public, :private, :protected])
             result.concat api_map.get_methods('Kernel')
-            # result.concat ApiMap.keywords
             result.concat api_map.keyword_pins.to_a
           end
         end
         package_completions(result)
       end
 
+      # @return [Array<Pin::Base>]
       def file_global_methods
         return [] if cursor.word.empty?
         source_map.pins.select do |pin|

data/lib/solargraph/source_map/mapper.rb

@@ -64,6 +64,10 @@ module Solargraph
         pins.select{|pin| pin.is_a?(Pin::Closure) and pin.location.range.contain?(position)}.last
       end
 
+      # @param source_position [Position]
+      # @param comment_position [Position]
+      # @param comment [String]
+      # @return [void]
       def process_comment source_position, comment_position, comment
         return unless comment.encode('UTF-8', invalid: :replace, replace: '?') =~ DIRECTIVE_REGEXP
         cmnt = remove_inline_comment_hashes(comment)
@@ -79,6 +83,8 @@ module Solargraph
       end
 
       # @param comment [String]
+      # @param tag [String]
+      # @param start [Integer]
       # @return [Integer]
       def find_directive_line_number comment, tag, start
         # Avoid overruning the index
@@ -204,10 +210,14 @@ module Solargraph
         end
       end
 
+      # @param line1 [Integer]
+      # @param line2 [Integer]
       def no_empty_lines?(line1, line2)
         @code.lines[line1..line2].none? { |line| line.strip.empty? }
       end
 
+      # @param comment [String]
+      # @return [String]
       def remove_inline_comment_hashes comment
         ctxt = ''
         num = nil

data/lib/solargraph/source_map.rb

@@ -2,7 +2,6 @@
 
 require 'yard'
 require 'solargraph/yard_tags'
-require 'set'
 
 module Solargraph
   # An index of pins and other ApiMap-related data for a Source.
@@ -18,7 +17,7 @@ module Solargraph
     # @return [Array<Pin::Base>]
     attr_reader :pins
 
-    # @return [Array<Pin::Base>]
+    # @return [Array<Pin::LocalVariable>]
     attr_reader :locals
 
     # @param source [Source]
@@ -35,10 +34,13 @@ module Solargraph
       @pin_select_cache = {}
     end
 
+    # @param klass [Class]
+    # @return [Array<Pin::Base>]
     def pins_by_class klass
       @pin_select_cache[klass] ||= @pin_class_hash.select { |key, _| key <= klass }.values.flatten
     end
 
+    # @return [Set<String>]
     def rebindable_method_names
       @rebindable_method_names ||= pins_by_class(Pin::Method)
         .select { |pin| pin.comments && pin.comments.include?('@yieldreceiver') }
@@ -99,10 +101,16 @@ module Solargraph
       (pins + locals).select { |pin| pin.location == location }
     end
 
+    # @param line [Integer]
+    # @param character [Integer]
+    # @return [Pin::Method,Pin::Namespace]
     def locate_named_path_pin line, character
       _locate_pin line, character, Pin::Namespace, Pin::Method
     end
 
+    # @param line [Integer]
+    # @param character [Integer]
+    # @return [Pin::Namespace,Pin::Method,Pin::Block]
     def locate_block_pin line, character
       _locate_pin line, character, Pin::Namespace, Pin::Method, Pin::Block
     end
@@ -166,6 +174,8 @@ module Solargraph
       @convention_pins || []
     end
 
+    # @param pins [Array<Pin::Base>]
+    # @return [Array<Pin::Base>]
     def convention_pins=(pins)
       # unmemoizing the document_symbols in case it was called from any of convnetions
       @document_symbols = nil
@@ -175,7 +185,7 @@ module Solargraph
     # @param line [Integer]
     # @param character [Integer]
     # @param klasses [Array<Class>]
-    # @return [Pin::Base]
+    # @return [Pin::Base, nil]
     def _locate_pin line, character, *klasses
       position = Position.new(line, character)
       found = nil

data/lib/solargraph/type_checker/checks.rb

@@ -51,8 +51,13 @@ module Solargraph
       # @return [Boolean]
       def any_types_match? api_map, expected, inferred
         return duck_types_match?(api_map, expected, inferred) if expected.duck_type?
+        # walk through the union expected type and see if any members
+        # of the union match the inferred type
         expected.each do |exp|
           next if exp.duck_type?
+          # @todo: there should be a level of typechecking where all
+          #   unique types in the inferred must match one of the
+          #   expected unique types
           inferred.each do |inf|
             # return true if exp == inf || api_map.super_and_sub?(fuzz(inf), fuzz(exp))
             return true if exp == inf || either_way?(api_map, inf, exp)
@@ -103,9 +108,12 @@ module Solargraph
       # @param cls2 [ComplexType::UniqueType]
       # @return [Boolean]
       def either_way?(api_map, cls1, cls2)
-        f1 = fuzz(cls1)
-        f2 = fuzz(cls2)
+        # @todo there should be a level of typechecking which uses the
+        #   full tag with parameters to determine compatibility
+        f1 = cls1.name
+        f2 = cls2.name
         api_map.type_include?(f1, f2) || api_map.super_and_sub?(f1, f2) || api_map.super_and_sub?(f2, f1)
+        # api_map.type_include?(f1, f2) || api_map.super_and_sub?(f1, f2) || api_map.super_and_sub?(f2, f1)
       end
     end
   end