solargraph 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b84e595d8f1d4042f81bbfb7c27dc56913a0de8c
-  data.tar.gz: 0ddfb700d7f1a8e10ec74f021954e1b9fa1375ce
+  metadata.gz: f0eee03f14aa3abbcaad7015b94ad8c33df50acc
+  data.tar.gz: b4485de9e9cf36aa8df184687cd9e5476e6b627d
 SHA512:
-  metadata.gz: 171c19a787d30924b510b21d08c443c348d96d8c551fbefd03535dacc8e22fd289ace4f4f270e9469d61d813dc3c640e7ffed21d093826ef787173d0c80e5703
-  data.tar.gz: 88637fc48b37ef6bc2c7e3e5f4051fc87fa8901c829bf94bffc877d884f7e47fca750182241cb3d2cf539811e7c9275358a0792a42e6ea666815b59bb94a24c8
+  metadata.gz: 3845660c58589e9d5222d9800fb3a48aa3970aa548468f643363d653b28b6b086c2d3b5c7d38afb322e6f45271292096acec3af7be24088d726957de7cbcbd1b
+  data.tar.gz: 3040f8716959d1378a2478dd23d76c8232f0451669860267f5cbb07b7be6ed2bda987039912d6501665e3cf7d3af6ff1d9e71e01792cdca949bfdf45c09f42b6

data/.yardopts

@@ -0,0 +1,2 @@
+lib/**/*.rb
+-e lib/yard-solargraph.rb

data/lib/solargraph/api_map/source.rb

@@ -20,6 +20,10 @@ module Solargraph
       # @return [Array<Integer>]
       attr_reader :stubbed_lines
 
+      attr_reader :directives
+
+      attr_reader :path_macros
+
       include NodeMethods
 
       def initialize code, node, comments, filename, stubbed_lines = []
@@ -29,6 +33,7 @@ module Solargraph
         @node = root
         @comments = comments
         @directives = {}
+        @path_macros = {}
         @docstring_hash = associate_comments(node, comments)
         @filename = filename
         @mtime = (!filename.nil? and File.exist?(filename) ? File.mtime(filename) : nil)
@@ -54,6 +59,10 @@ module Solargraph
               gen_src = Source.virtual("def #{d.tag.name};end", filename)
               gen_pin = gen_src.method_pins.first
               method_pins.push Solargraph::Pin::Directed::Method.new(gen_src, gen_pin.node, ns, :instance, :public, docstring, gen_pin.name)
+            elsif d.tag.tag_name == 'macro'
+              # @todo Handle various types of macros (attach, new, whatever)
+              path = path_for(k.node)
+              @path_macros[path] = v
             else
               STDERR.puts "Nothing to do for directive: #{d}"
             end
@@ -61,6 +70,10 @@ module Solargraph
         end
       end
 
+      def macro path
+        @path_macros[path]
+      end
+
       def namespaces
         @namespace_nodes.keys
       end
@@ -160,6 +173,15 @@ module Solargraph
         parts.join('::')
       end
 
+      def path_for node
+        path = namespace_for(node) || ''
+        mp = (method_pins + attribute_pins).select{|p| p.node == node}.first
+        unless mp.nil?
+          path += (mp.scope == :instance ? '#' : '.') + mp.name
+        end
+        path
+      end
+
       def include? node
         @all_nodes.include? node
       end
@@ -394,11 +416,6 @@ module Solargraph
           stubs = []
           fixed_position = false
           tmp = code
-          if !offset.nil? and offset > 0
-            if tmp[offset - 1] == '.'
-              tmp = tmp[0..offset-2] + '_' + tmp[offset..-1]
-            end
-          end
           begin
             node, comments = Parser::CurrentRuby.parse_with_comments(tmp)
             Source.new(code, node, comments, filename, stubs)
@@ -407,11 +424,11 @@ module Solargraph
               tries += 1
               # Stub periods before the offset to retain the expected node tree
               if !offset.nil? and tmp[offset-1] == '.'
-                tmp = tmp[0, offset-1] + '_' + tmp[offset..-1]
+                tmp = tmp[0, offset-1] + ';' + tmp[offset..-1]
               elsif !fixed_position and !offset.nil?
                 fixed_position = true
                 beg = beginning_of_line_from(tmp, offset)
-                tmp = tmp[0, beg] + '#' + tmp[beg+1..-1]
+                tmp = "#{tmp[0, beg]}##{tmp[beg+1..-1]}"
                 stubs.push(pos[0])
               elsif e.message.include?('token $end')
                 tmp += "\nend"

data/lib/solargraph/api_map/source_to_yard.rb

@@ -23,6 +23,7 @@ module Solargraph
         @root_code_object ||= YARD::CodeObjects::RootObject.new(nil, 'root')
       end
 
+      # @param sources [Array<Solargraph::ApiMap::Source>] Sources for code objects
       def rake_yard sources
         code_object_map.clear
         sources.each do |s|

data/lib/solargraph/api_map.rb

@@ -11,20 +11,9 @@ module Solargraph
     autoload :SourceToYard, 'solargraph/api_map/source_to_yard'
     @@source_cache = {}
 
-    KEYWORDS = [
-      '__ENCODING__', '__LINE__', '__FILE__', 'BEGIN', 'END', 'alias', 'and',
-      'begin', 'break', 'case', 'class', 'def', 'defined?', 'do', 'else',
-      'elsif', 'end', 'ensure', 'false', 'for', 'if', 'in', 'module', 'next',
-      'nil', 'not', 'or', 'redo', 'rescue', 'retry', 'return', 'self', 'super',
-      'then', 'true', 'undef', 'unless', 'until', 'when', 'while', 'yield'
-    ].freeze
-
-    METHODS_RETURNING_SELF = [
-      'clone', 'dup', 'freeze', 'taint', 'untaint'
-    ].freeze
-
     include NodeMethods
     include Solargraph::ApiMap::SourceToYard
+    include CoreFills
 
     # The root directory of the project. The ApiMap will search here for
     # additional files to parse and analyze.
@@ -58,6 +47,10 @@ module Solargraph
       yard_map
     end
 
+    # Get the configuration for the ApiMap's workspace. This method will
+    # initialize the settings from the workspace's root .solargraph.yml file
+    # if it exists.
+    #
     # @return [Solargraph::ApiMap::Config]
     def config reload = false
       @config = ApiMap::Config.new(@workspace) if @config.nil? or reload
@@ -78,6 +71,8 @@ module Solargraph
       @required ||= []
     end
 
+    # Get a YardMap associated with the current namespace.
+    #
     # @return [Solargraph::YardMap]
     def yard_map
       refresh
@@ -87,6 +82,8 @@ module Solargraph
       @yard_map
     end
 
+    # Get a LiveMap associated with the current namespace.
+    #
     # @return [Solargraph::LiveMap]
     def live_map
       @live_map ||= Solargraph::LiveMap.new(self)
@@ -130,19 +127,24 @@ module Solargraph
       virtualize code, filename
     end
 
+    # Refresh the ApiMap.
+    #
+    # @param force [Boolean] Perform a refresh even if the map is not "stale."
     def refresh force = false
       process_maps if @stale or force
     end
 
+    # True if a workspace file has been created, modified, or deleted since
+    # the last time the map was processed.
+    #
+    # @return [Boolean]
     def changed?
       current = config.calculated
       unless (Set.new(current) ^ workspace_files).empty?
-        STDERR.puts "Change based on difference in file list"
         return true
       end
       current.each do |f|
         if !File.exist?(f) or File.mtime(f) != source_file_mtime(f)
-          STDERR.puts "Change based on file #{f}"
           return true
         end
       end
@@ -159,39 +161,48 @@ module Solargraph
       @sources[filename].docstring_for(node)
     end
 
-    # @deprecated Use get_docstring_for instead.
-    def get_comment_for node
-      get_docstring_for node
-    end
-
+    # An array of suggestions based on Ruby keywords (`if`, `end`, etc.).
+    #
     # @return [Array<Solargraph::Suggestion>]
-    def self.get_keywords
+    def self.keywords
       @keyword_suggestions ||= KEYWORDS.map{ |s|
         Suggestion.new(s.to_s, kind: Suggestion::KEYWORD, detail: 'Keyword')
       }.freeze
     end
 
+    # An array of namespace names defined in the ApiMap.
+    #
     # @return [Array<String>]
     def namespaces
       refresh
       namespace_map.keys
     end
 
+    # True if the namespace exists.
+    #
+    # @param name [String] The namespace to match
+    # @param root [String] The context to search
+    # @return [Boolean]
     def namespace_exists? name, root = ''
       !find_fully_qualified_namespace(name, root).nil?
     end
 
-    # @deprecated Use get_constants instead.
-    def namespaces_in name, root = ''
-      get_constants name, root
-    end
-
+    # Get an array of constant pins defined in the ApiMap. (This method does
+    # not include constants from external gems or the Ruby core.)
+    #
+    # @param namespace [String] The namespace to match
+    # @param root [String] The context to search
     # @return [Array<Solargraph::Pin::Constant>]
     def get_constant_pins namespace, root
       fqns = find_fully_qualified_namespace(namespace, root)
       @const_pins[fqns] || []
     end
 
+    # Get suggestions for constants in the specified namespace. The result
+    # will include constant variables, classes, and modules.
+    #
+    # @param namespace [String] The namespace to match
+    # @param root [String] The context to search
     # @return [Array<Solargraph::Suggestion>]
     def get_constants namespace, root = ''
       result = []
@@ -212,17 +223,11 @@ module Solargraph
       result
     end
 
-    def find_namespace_pins fqns
-      set = nil
-      if fqns.include?('::')
-        set = @namespace_pins[fqns.split('::')[0..-2].join('::')]
-      else
-        set = @namespace_pins['']
-      end
-      return [] if set.nil?
-      set.select{|p| p.path == fqns}
-    end
-
+    # Get a fully qualified namespace name. This method will start the search
+    # in the specified root until it finds a match for the name.
+    #
+    # @param name [String] The namespace to match
+    # @param root [String] The context to search
     # @return [String]
     def find_fully_qualified_namespace name, root = '', skip = []
       refresh
@@ -263,18 +268,22 @@ module Solargraph
       result
     end
 
-    def get_namespace_nodes(fqns)
-      return file_nodes if fqns == '' or fqns.nil?
-      refresh
-      namespace_map[fqns] || []
-    end
-
+    # Get an array of instance variable pins defined in specified namespace
+    # and scope.
+    #
+    # @param namespace [String] A fully qualified namespace
+    # @param scope [Symbol] :instance or :class
     # @return [Array<Solargraph::Pin::InstanceVariable>]
     def get_instance_variable_pins(namespace, scope = :instance)
       refresh
       (@ivar_pins[namespace] || []).select{ |pin| pin.scope == scope }
     end
 
+    # Get an array of instance variable suggestions defined in specified
+    # namespace and scope.
+    #
+    # @param namespace [String] A fully qualified namespace
+    # @param scope [Symbol] :instance or :class
     # @return [Array<Solargraph::Suggestion>]
     def get_instance_variables(namespace, scope = :instance)
       refresh
@@ -332,7 +341,13 @@ module Solargraph
       return nil if pins.nil?
       pin = pins.select{|p| p.name == var and p.scope == scope}.first
       return nil if pin.nil?
-      pin.return_type
+      type = pin.return_type
+      if type.nil?
+        zparts = resolve_node_signature(pin.assignment_node).split('.')
+        ztype = infer_signature_type(zparts[0..-2].join('.'), namespace, scope: :instance, call_node: pin.assignment_node)
+        type = get_return_type_from_macro(ztype, zparts[-1], pin.assignment_node, :instance, [:public, :private, :protected])
+      end
+      type
     end
 
     # @return [String]
@@ -366,6 +381,8 @@ module Solargraph
 
     # @return [String]
     def infer_assignment_node_type node, namespace
+      cached = cache.get_assignment_node_type(node, namespace)
+      return cached unless cached.nil?
       name_i = (node.type == :casgn ? 1 : 0) 
       sig_i = (node.type == :casgn ? 2 : 1)
       type = infer_literal_node_type(node.children[sig_i])
@@ -373,13 +390,32 @@ module Solargraph
         sig = resolve_node_signature(node.children[sig_i])
         # Avoid infinite loops from variable assignments that reference themselves
         return nil if node.children[name_i].to_s == sig.split('.').first
-        type = infer_signature_type(sig, namespace)
+        type = infer_signature_type(sig, namespace, call_node: node.children[sig_i])
       end
+      cache.set_assignment_node_type(node, namespace, type)
       type
     end
 
+    def get_call_arguments node
+      return [] unless node.type == :send
+      result = []
+      node.children[2..-1].each do |c|
+        result.push unpack_name(c)
+      end
+      result
+    end
+
+    # Get the return type for a signature within the specified namespace and
+    # scope.
+    #
+    # @example
+    #   api_map.infer_signature_type('String.new', '') #=> 'String'
+    #
+    # @param signature [String]
+    # @param namespace [String] A fully qualified namespace
+    # @param scope [Symbol] :class or :instance
     # @return [String]
-    def infer_signature_type signature, namespace, scope: :class
+    def infer_signature_type signature, namespace, scope: :class, call_node: nil
       namespace ||= ''
       if cache.has_signature_type?(signature, namespace, scope)
         return cache.get_signature_type(signature, namespace, scope)
@@ -396,20 +432,20 @@ module Solargraph
       end
       result = nil
       if namespace.end_with?('#class')
-        result = infer_signature_type signature, namespace[0..-7], scope: (scope == :class ? :instance : :class)
+        result = infer_signature_type signature, namespace[0..-7], scope: (scope == :class ? :instance : :class), call_node: call_node
       else
         parts = signature.split('.', 2)
         if parts[0].start_with?('@@')
           type = infer_class_variable(parts[0], namespace)
           if type.nil? or parts.empty?
-            result = inner_infer_signature_type(parts[1], type, scope: :instance)
+            result = inner_infer_signature_type(parts[1], type, scope: :instance, call_node: call_node)
           else
             result = type
           end
         elsif parts[0].start_with?('@')
           type = infer_instance_variable(parts[0], namespace, scope)
           if type.nil? or parts.empty?
-            result = inner_infer_signature_type(parts[1], type, scope: :instance)
+            result = inner_infer_signature_type(parts[1], type, scope: :instance, call_node: call_node)
           else
             result = type
           end
@@ -417,21 +453,29 @@ module Solargraph
           type = find_fully_qualified_namespace(parts[0], namespace)
           if type.nil?
             # It's a method call
-            type = inner_infer_signature_type(parts[0], namespace, scope: scope)
-            if parts[1].nil?
+            type = inner_infer_signature_type(parts[0], namespace, scope: scope, call_node: call_node)
+            if parts.length < 2
+              if type.nil? and !parts.length.nil?
+                path = "#{clean_namespace_string(namespace)}#{scope == :class ? '.' : '#'}#{parts[0]}"
+                subtypes = get_subtypes(namespace)
+                type = subtypes[0] if METHODS_RETURNING_SUBTYPES.include?(path)
+              end
               result = type
             else
-              result = inner_infer_signature_type(parts[1], type, scope: :instance)
+              result = inner_infer_signature_type(parts[1], type, scope: :instance, call_node: call_node)
             end
           else
-            result = inner_infer_signature_type(parts[1], type, scope: :class)
+            result = inner_infer_signature_type(parts[1], type, scope: :class, call_node: call_node)
           end
+          result = type if result == 'self'
         end
       end
       cache.set_signature_type signature, namespace, scope, result
       result
     end
 
+    # Get the namespace's type (Class or Module).
+    #
     # @param [String] A fully qualified namespace
     # @return [Symbol] :class, :module, or nil
     def get_namespace_type fqns
@@ -499,9 +543,7 @@ module Solargraph
     def get_instance_methods(namespace, root = '', visibility: [:public])
       refresh
       namespace = clean_namespace_string(namespace)
-      if namespace.end_with?('#class')
-        return get_methods(namespace.split('#').first, root, visibility: visibility)
-      elsif namespace.end_with?('#module')
+      if namespace.end_with?('#class') or namespace.end_with?('#module')
         return get_methods(namespace.split('#').first, root, visibility: visibility)
       end
       meths = []
@@ -531,21 +573,9 @@ module Solargraph
       meths
     end
 
-    # @return [Array<String>]
-    def get_include_strings_from *nodes
-      arr = []
-      nodes.each { |node|
-        next unless node.kind_of?(AST::Node)
-        arr.push unpack_name(node.children[2]) if (node.type == :send and node.children[1] == :include)
-        node.children.each { |n|
-          arr += get_include_strings_from(n) if n.kind_of?(AST::Node) and n.type != :class and n.type != :module and n.type != :sclass
-        }
-      }
-      arr
-    end
-
     # Update the ApiMap with the most recent version of the specified file.
     #
+    # @param filename [String]
     def update filename
       filename.gsub!(/\\/, '/')
       if filename.end_with?('.rb')
@@ -570,11 +600,16 @@ module Solargraph
       end
     end
 
+    # All sources generated from workspace files.
+    #
     # @return [Array<Solargraph::ApiMap::Source>]
     def sources
       @sources.values
     end
 
+    # Get an array of all suggestions that match the specified path.
+    #
+    # @param path [String] The path to find
     # @return [Array<Solargraph::Suggestion>]
     def get_path_suggestions path
       refresh
@@ -599,6 +634,12 @@ module Solargraph
       result
     end
 
+    # Get a list of documented paths that match the query.
+    #
+    # @example
+    #   api_map.query('str') # Results will include `String` and `Struct`
+    #
+    # @param query [String] The text to match
     # @return [Array<String>]
     def search query
       refresh
@@ -613,6 +654,12 @@ module Solargraph
       found.concat(yard_map.search(query)).uniq.sort
     end
 
+    # Get YARD documentation for the specified path.
+    #
+    # @example
+    #   api_map.document('String#split')
+    #
+    # @param path [String] The path to find
     # @return [Array<YARD::CodeObject::Base>]
     def document path
       refresh
@@ -634,6 +681,7 @@ module Solargraph
     def clear
       @stale = false
       namespace_map.clear
+      path_macros.clear
       @required = config.required.clone
     end
 
@@ -756,6 +804,7 @@ module Solargraph
         @namespace_pins[pin.namespace] ||= []
         @namespace_pins[pin.namespace].push pin
       end
+      path_macros.merge! source.path_macros
       source.required.each do |r|
         required.push r
       end
@@ -835,7 +884,7 @@ module Solargraph
     #
     # @return [String] The fully qualified namespace for the signature's type
     #   or nil if a type could not be determined
-    def inner_infer_signature_type signature, namespace, scope: :instance, top: true
+    def inner_infer_signature_type signature, namespace, scope: :instance, top: true, call_node: nil
       return nil if signature.nil?
       signature.gsub!(/\.$/, '')
       if signature.empty?
@@ -863,7 +912,8 @@ module Solargraph
         end
         if scope == :class and part == 'new'
           scope = :instance
-        elsif !METHODS_RETURNING_SELF.include?(part)
+        else
+          curtype = type
           type = nil
           visibility = [:public]
           visibility.concat [:private, :protected] if top
@@ -873,9 +923,22 @@ module Solargraph
             tmp = get_methods(namespace, visibility: visibility)
           end
           tmp.concat get_instance_methods('Kernel', visibility: [:public]) if top
-          meth = tmp.select{|s| s.label == part}.first
-          return nil if meth.nil? or meth.return_type.nil?
-          type = meth.return_type
+          matches = tmp.select{|s| s.label == part}
+          return nil if matches.empty?
+          matches.each do |m|
+            type = get_return_type_from_macro(namespace, signature, call_node, scope, visibility)
+            if type.nil?
+              if METHODS_RETURNING_SELF.include?(m.path)
+                type = curtype
+              elsif METHODS_RETURNING_SUBTYPES.include?(m.path)
+                subtypes = get_subtypes(namespace)
+                type = subtypes[0]
+              else
+                type = m.return_type
+              end
+            end
+            break unless type.nil?
+          end
           scope = :instance
         end
         top = false
@@ -985,5 +1048,73 @@ module Solargraph
       end
       nil
     end
+
+    # @return [Array<Solargraph::Pin::Namespace>]
+    def find_namespace_pins fqns
+      set = nil
+      if fqns.include?('::')
+        set = @namespace_pins[fqns.split('::')[0..-2].join('::')]
+      else
+        set = @namespace_pins['']
+      end
+      return [] if set.nil?
+      set.select{|p| p.path == fqns}
+    end
+
+    def get_namespace_nodes(fqns)
+      return file_nodes if fqns == '' or fqns.nil?
+      refresh
+      namespace_map[fqns] || []
+    end
+
+    # @return [Array<String>]
+    def get_include_strings_from *nodes
+      arr = []
+      nodes.each { |node|
+        next unless node.kind_of?(AST::Node)
+        arr.push unpack_name(node.children[2]) if (node.type == :send and node.children[1] == :include)
+        node.children.each { |n|
+          arr += get_include_strings_from(n) if n.kind_of?(AST::Node) and n.type != :class and n.type != :module and n.type != :sclass
+        }
+      }
+      arr
+    end
+
+    # @todo DRY this method. It's duplicated in CodeMap
+    def get_subtypes type
+      return nil if type.nil?
+      match = type.match(/<([a-z0-9_:, ]*)>/i)
+      return [] if match.nil?
+      match[1].split(',').map(&:strip)
+    end
+
+    # @return [Hash]
+    def path_macros
+      @path_macros ||= {}
+    end
+
+    def get_return_type_from_macro namespace, signature, call_node, scope, visibility
+      return nil if signature.empty? or signature.include?('.') or call_node.nil?
+      path = "#{namespace}#{scope == :class ? '.' : '#'}#{signature}"
+      macmeth = get_path_suggestions(path).first
+      type = nil
+      unless macmeth.nil?
+        macro = path_macros[macmeth.path]
+        macro = macro.first unless macro.nil?
+        if macro.nil? and !macmeth.code_object.nil? and !macmeth.code_object.base_docstring.nil? and macmeth.code_object.base_docstring.all.include?('@!macro')
+          all = YARD::Docstring.parser.parse(macmeth.code_object.base_docstring.all).directives
+          macro = all.select{|m| m.tag.tag_name == 'macro'}.first
+        end
+        unless macro.nil?
+          docstring = YARD::Docstring.parser.parse(macro.tag.text).to_docstring
+          rt = docstring.tag(:return)
+          unless rt.nil? or rt.types.nil? or call_node.nil?
+            args = get_call_arguments(call_node)
+            type = "#{args[rt.types[0][1..-1].to_i-1]}"
+          end
+        end
+      end
+      type
+    end
   end
 end