cosmicgraph 0.49.0

data/lib/solargraph/pin/documenting.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'kramdown'
+require 'kramdown-parser-gfm'
+require 'yard'
+require 'reverse_markdown'
+require 'solargraph/converters/dl'
+require 'solargraph/converters/dt'
+require 'solargraph/converters/dd'
+require 'solargraph/converters/misc'
+
+module Solargraph
+  module Pin
+    # A module to add the Pin::Base#documentation method.
+    #
+    module Documenting
+      # A documentation formatter that either performs Markdown conversion for
+      # text, or applies backticks for code blocks.
+      #
+      class DocSection
+        # @return [String]
+        attr_reader :plaintext
+
+        # @param code [Boolean] True if this section is a code block
+        def initialize code
+          @plaintext = String.new('')
+          @code = code
+        end
+
+        def code?
+          @code
+        end
+
+        # @param text [String]
+        # @return [String]
+        def concat text
+          @plaintext.concat text
+        end
+
+        def to_s
+          return "\n```ruby\n#{@plaintext}#{@plaintext.end_with?("\n") ? '' : "\n"}```\n\n" if code?
+          ReverseMarkdown.convert unescape_brackets(Kramdown::Document.new(escape_brackets(@plaintext), input: 'GFM').to_html)
+        end
+
+        private
+
+        # @param text [String]
+        # @return [String]
+        def escape_brackets text
+          # text.gsub(/(\[[^\]]*\])([^\(]|\z)/, '!!!^\1^!!!\2')
+          text.gsub('[', '!!!!b').gsub(']', 'e!!!!')
+        end
+
+        # @param text [String]
+        # @return [String]
+        def unescape_brackets text
+          text.gsub('!!!!b', '[').gsub('e!!!!', ']')
+        end
+      end
+
+      # @return [String]
+      def documentation
+        @documentation ||= begin
+          # Using DocSections allows for code blocks that start with an empty
+          # line and at least two spaces of indentation. This is a common
+          # convention in Ruby core documentation, e.g., String#split.
+          sections = [DocSection.new(false)]
+          normalize_indentation(docstring.to_s).gsub(/\t/, '  ').lines.each do |l|
+            if l.strip.empty?
+              sections.last.concat l
+            else
+              if (l =~ /^  [^\s]/ && sections.last.plaintext =~ /(\r?\n[ \t]*?){2,}$/) || (l.start_with?('  ') && sections.last.code?)
+                # Code block
+                sections.push DocSection.new(true) unless sections.last.code?
+                sections.last.concat l[2..-1]
+              else
+                # Regular documentation
+                sections.push DocSection.new(false) if sections.last.code?
+                sections.last.concat l
+              end
+            end
+          end
+          sections.map(&:to_s).join.strip
+        end
+      end
+
+      private
+
+      # @param text [String]
+      # @return [String]
+      def normalize_indentation text
+        text.lines.map { |l| remove_odd_spaces(l) }.join
+      end
+
+      # @param line [String]
+      # @return [String]
+      def remove_odd_spaces line
+        return line unless line.start_with?(' ')
+        spaces = line.match(/^ +/)[0].length
+        return line unless spaces.odd?
+        line[1..-1]
+      end
+    end
+  end
+end

data/lib/solargraph/pin/duck_method.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    # DuckMethod pins are used to add completion items for type tags that
+    # use duck typing, e.g., `@param file [#read]`.
+    #
+    class DuckMethod < Pin::Method
+      # @param location [Solargraph::Location]
+      # @param name [String]
+      # def initialize location, name
+      #   # super(location, '', name, nil, :instance, :public, [])
+      # end
+    end
+  end
+end

data/lib/solargraph/pin/global_variable.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    class GlobalVariable < BaseVariable
+    end
+  end
+end

data/lib/solargraph/pin/instance_variable.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    class InstanceVariable < BaseVariable
+      def binder
+        closure.binder
+      end
+
+      def scope
+        closure.binder.scope
+      end
+
+      def context
+        @context ||= begin
+          result = super
+          if scope == :class
+            ComplexType.parse("Class<#{result.namespace}>")
+          else
+            ComplexType.parse("#{result.namespace}")
+          end
+        end
+      end
+
+      def nearly? other
+        super && binder == other.binder
+      end
+    end
+  end
+end

data/lib/solargraph/pin/keyword.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    class Keyword < Base
+      def initialize name
+        super(name: name)
+      end
+
+      def name
+        @name
+      end
+    end
+  end
+end

data/lib/solargraph/pin/keyword_param.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    class KeywordParam < Symbol
+    end
+  end
+end

data/lib/solargraph/pin/local_variable.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    class LocalVariable < BaseVariable
+      # @return [Range]
+      attr_reader :presence
+
+      def initialize assignment: nil, presence: nil, **splat
+        super(**splat)
+        @assignment = assignment
+        @presence = presence
+      end
+
+      def try_merge! pin
+        return false unless super
+        @presence = pin.presence
+        true
+      end
+
+      # @param other_closure [Pin::Closure]
+      # @param other_loc [Location]
+      def visible_at?(other_closure, other_loc)
+        return true if location.filename == other_loc.filename &&
+          presence.include?(other_loc.range.start) &&
+          match_named_closure(other_closure, closure)
+      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
+
+      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

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    # The base class for method and attribute pins.
+    #
+    class Method < Closure
+      include Solargraph::Parser::NodeMethods
+
+      # @return [Array<Pin::Parameter>]
+      attr_reader :parameters
+
+      # @return [::Symbol] :public, :private, or :protected
+      attr_reader :visibility
+
+      # @return [Parser::AST::Node]
+      attr_reader :node
+
+      # @param visibility [::Symbol] :public, :protected, or :private
+      # @param explicit [Boolean]
+      # @param parameters [Array<Pin::Parameter>]
+      # @param node [Parser::AST::Node, RubyVM::AbstractSyntaxTree::Node]
+      # @param attribute [Boolean]
+      def initialize visibility: :public, explicit: true, parameters: [], node: nil, attribute: false, signatures: nil, anon_splat: false, **splat
+        super(**splat)
+        @visibility = visibility
+        @explicit = explicit
+        @parameters = parameters
+        @node = node
+        @attribute = attribute
+        @signatures = signatures
+        @anon_splat = anon_splat
+      end
+
+      # @return [Array<String>]
+      def parameter_names
+        @parameter_names ||= parameters.map(&:name)
+      end
+
+      def completion_item_kind
+        attribute? ? Solargraph::LanguageServer::CompletionItemKinds::PROPERTY : Solargraph::LanguageServer::CompletionItemKinds::METHOD
+      end
+
+      def symbol_kind
+        attribute? ? Solargraph::LanguageServer::SymbolKinds::PROPERTY : LanguageServer::SymbolKinds::METHOD
+      end
+
+      def return_type
+        @return_type ||= ComplexType.try_parse(*signatures.map(&:return_type).map(&:to_s))
+      end
+
+      # @return [Array<Signature>]
+      def signatures
+        @signatures ||= begin
+          top_type = generate_complex_type
+          result = []
+          result.push Signature.new(parameters, top_type) if top_type.defined?
+          result.concat(overloads.map { |meth| Signature.new(meth.parameters, meth.return_type) })
+          result.push Signature.new(parameters, top_type) if result.empty?
+          result
+        end
+      end
+
+      # @return [String]
+      def detail
+        # This property is not cached in an instance variable because it can
+        # change when pins get proxied.
+        detail = String.new
+        detail += if signatures.length > 1
+          "(*) "
+        else
+          "(#{signatures.first.parameters.map(&:full).join(', ')}) " unless signatures.first.parameters.empty?
+        end.to_s
+        detail += "=#{probed? ? '~' : (proxied? ? '^' : '>')} #{return_type.to_s}" unless return_type.undefined?
+        detail.strip!
+        return nil if detail.empty?
+        detail
+      end
+
+      # @return [Array<Hash>]
+      def signature_help
+        @signature_help ||= signatures.map do |sig|
+          {
+            label: name + '(' + sig.parameters.map(&:full).join(', ') + ')',
+            documentation: documentation
+          }
+        end
+      end
+
+      def path
+        @path ||= "#{namespace}#{(scope == :instance ? '#' : '.')}#{name}"
+      end
+
+      def typify api_map
+        decl = super
+        return decl unless decl.undefined?
+        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
+      end
+
+      def documentation
+        if @documentation.nil?
+          @documentation ||= super || ''
+          param_tags = docstring.tags(:param)
+          unless param_tags.nil? or param_tags.empty?
+            @documentation += "\n\n" unless @documentation.empty?
+            @documentation += "Params:\n"
+            lines = []
+            param_tags.each do |p|
+              l = "* #{p.name}"
+              l += " [#{escape_brackets(p.types.join(', '))}]" unless p.types.nil? or p.types.empty?
+              l += " #{p.text}"
+              lines.push l
+            end
+            @documentation += lines.join("\n")
+          end
+          return_tags = docstring.tags(:return)
+          unless return_tags.empty?
+            @documentation += "\n\n" unless @documentation.empty?
+            @documentation += "Returns:\n"
+            lines = []
+            return_tags.each do |r|
+              l = "*"
+              l += " [#{escape_brackets(r.types.join(', '))}]" unless r.types.nil? or r.types.empty?
+              l += " #{r.text}"
+              lines.push l
+            end
+            @documentation += lines.join("\n")
+          end
+          @documentation += "\n\n" unless @documentation.empty?
+          @documentation += "Visibility: #{visibility}"
+        end
+        @documentation.to_s
+      end
+
+      def explicit?
+        @explicit
+      end
+
+      def attribute?
+        @attribute
+      end
+
+      def nearly? other
+        return false unless super
+        parameters == other.parameters and
+          scope == other.scope and
+          visibility == other.visibility
+      end
+
+      def probe api_map
+        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
+        @overloads ||= docstring.tags(:overload).map do |tag|
+          Pin::Signature.new(
+            tag.parameters.map do |src|
+              name, decl = parse_overload_param(src.first)
+              Pin::Parameter.new(
+                location: location,
+                closure: self,
+                comments: tag.docstring.all.to_s,
+                name: name,
+                decl: decl,
+                presence: location ? location.range : nil,
+                return_type: param_type_from_name(tag, src.first)
+              )
+            end,
+            ComplexType.try_parse(*tag.docstring.tags(:return).flat_map(&:types))
+          )
+        end
+        @overloads
+      end
+
+      def anon_splat?
+        @anon_splat
+      end
+
+      private
+
+      def select_decl name, asgn
+        if name.start_with?('**')
+          :kwrestarg
+        elsif name.start_with?('*')
+          :restarg
+        elsif name.start_with?('&')
+          :blockarg
+        elsif name.end_with?(':') && asgn
+          :kwoptarg
+        elsif name.end_with?(':')
+          :kwarg
+        elsif asgn
+          :optarg
+        else
+          :arg
+        end
+      end
+
+      def clean_param name
+        name.gsub(/[*&:]/, '')
+      end
+
+      # @param tag [YARD::Tags::OverloadTag]
+      def param_type_from_name(tag, name)
+        param = tag.tags(:param).select { |t| t.name == name }.first
+        return ComplexType::UNDEFINED unless param
+        ComplexType.try_parse(*param.types)
+      end
+
+      # @return [ComplexType]
+      def generate_complex_type
+        tags = docstring.tags(:return).map(&:types).flatten.reject(&:nil?)
+        return ComplexType::UNDEFINED if tags.empty?
+        ComplexType.try_parse *tags
+      end
+
+      # @param api_map [ApiMap]
+      # @return [ComplexType, nil]
+      def see_reference api_map
+        docstring.ref_tags.each do |ref|
+          next unless ref.tag_name == 'return' && ref.owner
+          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?
+        resolve_reference match[1], api_map
+      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 }
+        return nil if stack.empty?
+        stack.each do |pin|
+          return pin.return_type unless pin.return_type.undefined?
+        end
+        nil
+      end
+
+      # @param ref [String]
+      # @param api_map [ApiMap]
+      # @return [ComplexType]
+      def resolve_reference ref, api_map
+        parts = ref.split(/[\.#]/)
+        if parts.first.empty? || parts.one?
+          path = "#{namespace}#{ref}"
+        else
+          fqns = api_map.qualify(parts.first, namespace)
+          return ComplexType::UNDEFINED if fqns.nil?
+          path = fqns + ref[parts.first.length] + parts.last
+        end
+        pins = api_map.get_path_pins(path)
+        pins.each do |pin|
+          type = pin.typify(api_map)
+          return type unless type.undefined?
+        end
+        nil
+      end
+
+      # @return [Parser::AST::Node, nil]
+      def method_body_node
+        return nil if node.nil?
+        return node.children[1].children.last if node.type == :DEFN
+        return node.children[2].children.last if node.type == :DEFS
+        return node.children[2] if node.type == :def || node.type == :DEFS
+        return node.children[3] if node.type == :defs
+        nil
+      end
+
+      # @param api_map [ApiMap]
+      # @return [ComplexType]
+      def infer_from_return_nodes api_map
+        return ComplexType::UNDEFINED if node.nil?
+        result = []
+        has_nil = false
+        return ComplexType::NIL if method_body_node.nil?
+        returns_from(method_body_node).each do |n|
+          if n.nil? || [:NIL, :nil].include?(n.type)
+            has_nil = true
+            next
+          end
+          rng = Range.from_node(n)
+          next unless rng
+          clip = api_map.clip_at(
+            location.filename,
+            rng.ending
+          )
+          chain = Solargraph::Parser.chain(n, location.filename)
+          type = chain.infer(api_map, self, clip.locals)
+          result.push type unless type.undefined?
+        end
+        result.push ComplexType::NIL if has_nil
+        return ComplexType::UNDEFINED if result.empty?
+        ComplexType.try_parse(*result.map(&:tag).uniq)
+      end
+
+      def infer_from_iv api_map
+        types = []
+        varname = "@#{name.gsub(/=$/, '')}"
+        pins = api_map.get_instance_variable_pins(binder.namespace, binder.scope).select { |iv| iv.name == varname }
+        pins.each do |pin|
+          type = pin.typify(api_map)
+          type = pin.probe(api_map) if type.undefined?
+          types.push type if type.defined?
+        end
+        return ComplexType::UNDEFINED if types.empty?
+        ComplexType.try_parse(*types.map(&:tag).uniq)
+      end
+
+      # When YARD parses an overload tag, it includes rest modifiers in the parameters names.
+      #
+      # @param arg [String]
+      # @return [Array(String, Symbol)]
+      def parse_overload_param(name)
+        if name.start_with?('**')
+          [name[2..-1], :kwrestarg]
+        elsif name.start_with?('*')
+          [name[1..-1], :restarg]
+        else
+          [name, :arg]
+        end
+      end
+    end
+  end
+end

data/lib/solargraph/pin/method_alias.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    # Use this class to track method aliases for later remapping. Common
+    # examples that defer mapping are aliases for superclass methods or
+    # methods from included modules.
+    #
+    class MethodAlias < Method
+      # @return [::Symbol]
+      attr_reader :scope
+
+      # @return [String]
+      attr_reader :original
+
+      def initialize scope: :instance, original: nil, **splat
+        super(**splat)
+        @scope = scope
+        @original = original
+      end
+
+      def visibility
+        :public
+      end
+
+      def path
+        @path ||= namespace + (scope == :instance ? '#' : '.') + name
+      end
+    end
+  end
+end

data/lib/solargraph/pin/namespace.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    class Namespace < Closure
+      # @return [::Symbol] :public or :private
+      attr_reader :visibility
+
+      # @return [::Symbol] :class or :module
+      attr_reader :type
+
+      attr_reader :parameters
+
+      # @param type [::Symbol] :class or :module
+      # @param visibility [::Symbol] :public or :private
+      # @param gates [Array<String>]
+      def initialize type: :class, visibility: :public, gates: [''], parameters: [], **splat
+        # super(location, namespace, name, comments)
+        super(**splat)
+        @type = type
+        @visibility = visibility
+        if name.start_with?('::')
+          @name = name[2..-1]
+          @closure = Solargraph::Pin::ROOT_PIN
+        end
+        @open_gates = gates
+        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
+          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('::')])
+          @context = nil
+        end
+        @parameters = parameters
+      end
+
+      def namespace
+        context.namespace
+      end
+
+      def full_context
+        @full_context ||= ComplexType.try_parse("#{type.to_s.capitalize}<#{path}>")
+      end
+
+      def binder
+        full_context
+      end
+
+      def scope
+        context.scope
+      end
+
+      def completion_item_kind
+        (type == :class ? LanguageServer::CompletionItemKinds::CLASS : LanguageServer::CompletionItemKinds::MODULE)
+      end
+
+      # @return [Integer]
+      def symbol_kind
+        (type == :class ? LanguageServer::SymbolKinds::CLASS : LanguageServer::SymbolKinds::MODULE)
+      end
+
+      def path
+        @path ||= (namespace.empty? ? '' : "#{namespace}::") + name
+      end
+
+      def return_type
+        @return_type ||= ComplexType.try_parse( (type == :class ? 'Class' : 'Module') + "<#{path}>" )
+      end
+
+      def domains
+        @domains ||= []
+      end
+
+      def typify api_map
+        return_type
+      end
+
+      def gates
+        @gates ||= if path.empty?
+          @open_gates
+        else
+          [path] + @open_gates
+        end
+      end
+    end
+  end
+end