cosmicgraph 0.49.0

data/lib/solargraph/pin/base.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    # The base class for map pins.
+    #
+    class Base
+      include Common
+      include Conversions
+      include Documenting
+
+      # @return [YARD::CodeObjects::Base]
+      attr_reader :code_object
+
+      # @return [Solargraph::Location]
+      attr_reader :location
+
+      # @return [String]
+      attr_reader :name
+
+      # @return [String]
+      attr_reader :path
+
+      # @return [::Symbol]
+      attr_accessor :source
+
+      # @param location [Solargraph::Location, nil]
+      # @param kind [Integer]
+      # @param closure [Solargraph::Pin::Closure, nil]
+      # @param name [String]
+      # @param comments [String]
+      def initialize location: nil, closure: nil, name: '', comments: ''
+        @location = location
+        @closure = closure
+        @name = name
+        @comments = comments
+      end
+
+      # @return [String]
+      def comments
+        @comments ||= ''
+      end
+
+      # @return [String, nil]
+      def filename
+        return nil if location.nil?
+        location.filename
+      end
+
+      # @return [Integer]
+      def completion_item_kind
+        LanguageServer::CompletionItemKinds::KEYWORD
+      end
+
+      # @return [Integer, nil]
+      def symbol_kind
+        nil
+      end
+
+      def to_s
+        name.to_s
+      end
+
+      # @return [Boolean]
+      def variable?
+        false
+      end
+
+      # Pin equality is determined using the #nearly? method and also
+      # requiring both pins to have the same location.
+      #
+      def == other
+        return false unless nearly? other
+        comments == other.comments and location == other.location
+      end
+
+      # True if the specified pin is a near match to this one. A near match
+      # indicates that the pins contain mostly the same data. Any differences
+      # between them should not have an impact on the API surface.
+      #
+      # @param other [Solargraph::Pin::Base, Object]
+      # @return [Boolean]
+      def nearly? other
+        self.class == other.class &&
+          name == other.name &&
+          (closure == other.closure || (closure && closure.nearly?(other.closure))) &&
+          (comments == other.comments ||
+            (((maybe_directives? == false && other.maybe_directives? == false) || compare_directives(directives, other.directives)) &&
+            compare_docstring_tags(docstring, other.docstring))
+          )
+      end
+
+      # The pin's return type.
+      #
+      # @return [ComplexType]
+      def return_type
+        @return_type ||= ComplexType::UNDEFINED
+      end
+
+      # @return [YARD::Docstring]
+      def docstring
+        parse_comments unless defined?(@docstring)
+        @docstring ||= Solargraph::Source.parse_docstring('').to_docstring
+      end
+
+      # @return [Array<YARD::Tags::Directive>]
+      def directives
+        parse_comments unless defined?(@directives)
+        @directives
+      end
+
+      # @return [Array<YARD::Tags::MacroDirective>]
+      def macros
+        @macros ||= collect_macros
+      end
+
+      # Perform a quick check to see if this pin possibly includes YARD
+      # directives. This method does not require parsing the comments.
+      #
+      # After the comments have been parsed, this method will return false if
+      # no directives were found, regardless of whether it previously appeared
+      # possible.
+      #
+      # @return [Boolean]
+      def maybe_directives?
+        return !@directives.empty? if defined?(@directives)
+        @maybe_directives ||= comments.include?('@!')
+      end
+
+      # @return [Boolean]
+      def deprecated?
+        @deprecated ||= docstring.has_tag?('deprecated')
+      end
+
+      # Get a fully qualified type from the pin's return type.
+      #
+      # The relative type is determined from YARD documentation (@return,
+      # @param, @type, etc.) and its namespaces are fully qualified using the
+      # provided ApiMap.
+      #
+      # @param api_map [ApiMap]
+      # @return [ComplexType]
+      def typify api_map
+        return_type.qualify(api_map, namespace)
+      end
+
+      # Infer the pin's return type via static code analysis.
+      #
+      # @param api_map [ApiMap]
+      # @return [ComplexType]
+      def probe api_map
+        typify api_map
+      end
+
+      # @deprecated Use #typify and/or #probe instead
+      # @param api_map [ApiMap]
+      # @return [ComplexType]
+      def infer api_map
+        Solargraph::Logging.logger.warn "WARNING: Pin #infer methods are deprecated. Use #typify or #probe instead."
+        type = typify(api_map)
+        return type unless type.undefined?
+        probe api_map
+      end
+
+      # Try to merge data from another pin. Merges are only possible if the
+      # pins are near matches (see the #nearly? method). The changes should
+      # not have any side effects on the API surface.
+      #
+      # @param pin [Pin::Base] The pin to merge into this one
+      # @return [Boolean] True if the pins were merged
+      def try_merge! pin
+        return false unless nearly?(pin)
+        @location = pin.location
+        @closure = pin.closure
+        return true if comments == pin.comments
+        @comments = pin.comments
+        @docstring = pin.docstring
+        @return_type = pin.return_type
+        @documentation = nil
+        @deprecated = nil
+        reset_conversions
+        true
+      end
+
+      def proxied?
+        @proxied ||= false
+      end
+
+      def probed?
+        @probed ||= false
+      end
+
+      # @param api_map [ApiMap]
+      # @return [self]
+      def realize api_map
+        return self if return_type.defined?
+        type = typify(api_map)
+        return proxy(type) if type.defined?
+        type = probe(api_map)
+        return self if type.undefined?
+        result = proxy(type)
+        result.probed = true
+        result
+      end
+
+      # Return a proxy for this pin with the specified return type. Other than
+      # the return type and the #proxied? setting, the proxy should be a clone
+      # of the original.
+      #
+      # @param return_type [ComplexType]
+      # @return [self]
+      def proxy return_type
+        result = dup
+        result.return_type = return_type
+        result.proxied = true
+        result
+      end
+
+      def identity
+        @identity ||= "#{closure.context.namespace}|#{name}"
+      end
+
+      def inspect
+        "#<#{self.class} `#{self.path}` at #{self.location.inspect}>"
+      end
+
+      protected
+
+      # @return [Boolean]
+      attr_writer :probed
+
+      # @return [Boolean]
+      attr_writer :proxied
+
+      # @return [ComplexType]
+      attr_writer :return_type
+
+      private
+
+      # @return [void]
+      def parse_comments
+        # HACK: Avoid a NoMethodError on nil with empty overload tags
+        if comments.nil? || comments.empty? || comments.strip.end_with?('@overload')
+          @docstring = nil
+          @directives = []
+        else
+          # HACK: Pass a dummy code object to the parser for plugins that
+          # expect it not to be nil
+          parse = Solargraph::Source.parse_docstring(comments)
+          @docstring = parse.to_docstring
+          @directives = parse.directives
+        end
+      end
+
+      # True if two docstrings have the same tags, regardless of any other
+      # differences.
+      #
+      # @param d1 [YARD::Docstring]
+      # @param d2 [YARD::Docstring]
+      # @return [Boolean]
+      def compare_docstring_tags d1, d2
+        return false if d1.tags.length != d2.tags.length
+        d1.tags.each_index do |i|
+          return false unless compare_tags(d1.tags[i], d2.tags[i])
+        end
+        true
+      end
+
+      # @param dir1 [Array<YARD::Tags::Directive>]
+      # @param dir2 [Array<YARD::Tags::Directive>]
+      # @return [Boolean]
+      def compare_directives dir1, dir2
+        return false if dir1.length != dir2.length
+        dir1.each_index do |i|
+          return false unless compare_tags(dir1[i].tag, dir2[i].tag)
+        end
+        true
+      end
+
+      # @param tag1 [YARD::Tags::Tag]
+      # @param tag2 [YARD::Tags::Tag]
+      # @return [Boolean]
+      def compare_tags tag1, tag2
+        tag1.class == tag2.class &&
+          tag1.tag_name == tag2.tag_name &&
+          tag1.text == tag2.text &&
+          tag1.name == tag2.name &&
+          tag1.types == tag2.types
+      end
+
+      # @return [Array<YARD::Tags::Handlers::Directive>]
+      def collect_macros
+        return [] unless maybe_directives?
+        parse = Solargraph::Source.parse_docstring(comments)
+        parse.directives.select{ |d| d.tag.tag_name == 'macro' }
+      end
+    end
+  end
+end

data/lib/solargraph/pin/base_variable.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    class BaseVariable < Base
+      include Solargraph::Parser::NodeMethods
+      # include Solargraph::Source::NodeMethods
+
+      # @return [Parser::AST::Node, nil]
+      attr_reader :assignment
+
+      # @param assignment [Parser::AST::Node, nil]
+      def initialize assignment: nil, **splat
+        super(**splat)
+        @assignment = assignment
+      end
+
+      def completion_item_kind
+        Solargraph::LanguageServer::CompletionItemKinds::VARIABLE
+      end
+
+      # @return [Integer]
+      def symbol_kind
+        Solargraph::LanguageServer::SymbolKinds::VARIABLE
+      end
+
+      def return_type
+        @return_type ||= generate_complex_type
+      end
+
+      def nil_assignment?
+        return_type.nil?
+      end
+
+      def variable?
+        true
+      end
+
+      def probe api_map
+        return ComplexType::UNDEFINED if @assignment.nil?
+        types = []
+        returns_from(@assignment).each do |node|
+          # Nil nodes may not have a location
+          if node.nil? || node.type == :NIL || node.type == :nil
+            types.push ComplexType::NIL
+          else
+            rng = Range.from_node(node)
+            next if rng.nil?
+            pos = rng.ending
+            clip = api_map.clip_at(location.filename, pos)
+            # Use the return node for inference. The clip might infer from the
+            # first node in a method call instead of the entire call.
+            chain = Parser.chain(node, nil, clip.in_block?)
+            result = chain.infer(api_map, closure, clip.locals)
+            types.push result unless result.undefined?
+          end
+        end
+        return ComplexType::UNDEFINED if types.empty?
+        ComplexType.try_parse(*types.map(&:tag))
+      end
+
+      def == other
+        return false unless super
+        assignment == other.assignment
+      end
+
+      def try_merge! pin
+        return false unless super
+        @assignment = pin.assignment
+        @return_type = pin.return_type
+        true
+      end
+
+      private
+
+      # @return [ComplexType]
+      def generate_complex_type
+        tag = docstring.tag(:type)
+        return ComplexType.try_parse(*tag.types) unless tag.nil? || tag.types.nil? || tag.types.empty?
+        ComplexType.new
+      end
+    end
+  end
+end

data/lib/solargraph/pin/block.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    class Block < Closure
+      # The signature of the method that receives this block.
+      #
+      # @return [Parser::AST::Node]
+      attr_reader :receiver
+
+      # @param args [Array<Parameter>]
+      def initialize receiver: nil, args: [], context: nil, **splat
+        super(**splat)
+        @receiver = receiver
+        @context = context
+        @parameters = args
+      end
+
+      # @param api_map [ApiMap]
+      # @return [void]
+      def rebind api_map
+        @binder ||= binder_or_nil(api_map)
+      end
+
+      def binder
+        @binder || closure.binder
+      end
+
+      # @return [Array<Parameter>]
+      def parameters
+        @parameters ||= []
+      end
+
+      # @return [Array<String>]
+      def parameter_names
+        @parameter_names ||= parameters.map(&:name)
+      end
+
+      private
+
+      # @param api_map [ApiMap]
+      # @return [ComplexType, nil]
+      def binder_or_nil api_map
+        return nil unless receiver
+        word = receiver.children.find { |c| c.is_a?(::Symbol) }.to_s
+        return nil unless api_map.rebindable_method_names.include?(word)
+        chain = Parser.chain(receiver, location.filename)
+        locals = api_map.source_map(location.filename).locals_at(location)
+        links_last_word = chain.links.last.word
+        if %w[instance_eval instance_exec class_eval class_exec module_eval module_exec].include?(links_last_word)
+          return chain.base.infer(api_map, self, locals)
+        end
+        if 'define_method' == links_last_word and chain.define(api_map, self, locals).first&.path == 'Module#define_method' # change class type to instance type
+          if chain.links.size > 1 # Class.define_method
+            ty = chain.base.infer(api_map, self, locals)
+            return Solargraph::ComplexType.parse(ty.namespace)
+          else # define_method without self
+            return Solargraph::ComplexType.parse(closure.binder.namespace)
+          end
+        end
+        # other case without early return, read block yieldself tags
+        receiver_pin = chain.define(api_map, self, locals).first
+        if receiver_pin && receiver_pin.docstring
+          ys = receiver_pin.docstring.tag(:yieldself)
+          if ys && ys.types && !ys.types.empty?
+            return ComplexType.try_parse(*ys.types).qualify(api_map, receiver_pin.context.namespace)
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/solargraph/pin/class_variable.rb

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

data/lib/solargraph/pin/closure.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    class Closure < Base
+      # @return [::Symbol] :class or :instance
+      attr_reader :scope
+
+      def initialize scope: :class, **splat
+        super(**splat)
+        @scope = scope
+      end
+
+      def context
+        @context ||= begin
+          result = super
+          if scope == :instance
+            Solargraph::ComplexType.parse(result.namespace)
+          else
+            result
+          end
+        end
+      end
+
+      def binder
+        @binder || context
+      end
+
+      # @return [Array<String>]
+      def gates
+        # @todo This check might not be necessary. There should always be a
+        #   root pin
+        closure ? closure.gates : ['']
+      end
+    end
+  end
+end

data/lib/solargraph/pin/common.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    module Common
+      # @return [Location]
+      attr_reader :location
+
+      # @return [Pin::Base, nil]
+      attr_reader :closure
+
+      # @return [String]
+      def name
+        @name ||= ''
+      end
+
+      # @return [ComplexType]
+      def return_type
+        @return_type ||= ComplexType::UNDEFINED
+      end
+
+      # @return [ComplexType]
+      def context
+        # Get the static context from the nearest namespace
+        @context ||= find_context
+      end
+      alias full_context context
+
+      # @return [String]
+      def namespace
+        context.namespace.to_s
+      end
+
+      # @return [ComplexType]
+      def binder
+        @binder || context
+      end
+
+      # @return [String]
+      def comments
+        @comments ||= ''
+      end
+
+      # @return [String]
+      def path
+        @path ||= name.empty? ? context.namespace : "#{context.namespace}::#{name}"
+      end
+
+      private
+
+      # @return [ComplexType]
+      def find_context
+        here = closure
+        until here.nil?
+          if here.is_a?(Pin::Namespace)
+            return here.return_type
+          elsif here.is_a?(Pin::Method)
+            if here.scope == :instance
+              return ComplexType.try_parse(here.context.namespace)
+            else
+              return here.context
+            end
+          end
+          here = here.closure
+        end
+        ComplexType::ROOT
+      end
+    end
+  end
+end

data/lib/solargraph/pin/constant.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Pin
+    class Constant < BaseVariable
+      attr_reader :visibility
+
+      def initialize visibility: :public, **splat
+        super(**splat)
+        @visibility = visibility
+      end
+
+      def return_type
+        @return_type ||= generate_complex_type
+      end
+
+      def completion_item_kind
+        Solargraph::LanguageServer::CompletionItemKinds::CONSTANT
+      end
+
+      # @return [Integer]
+      def symbol_kind
+        LanguageServer::SymbolKinds::CONSTANT
+      end
+
+      def path
+        @path ||= context.namespace.to_s.empty? ? name : "#{context.namespace}::#{name}"
+      end
+
+      private
+
+      # @return [ComplexType]
+      def generate_complex_type
+        tags = docstring.tags(:return).map(&:types).flatten.reject(&:nil?)
+        if tags.empty?
+          tags = docstring.tags(:type).map(&:types).flatten.reject(&:nil?)
+        end
+        return ComplexType::UNDEFINED if tags.empty?
+        ComplexType.try_parse *tags
+      end
+    end
+  end
+end

data/lib/solargraph/pin/conversions.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module Solargraph
+  module Pin
+    # @todo Move this stuff. It should be the responsibility of the language server.
+    module Conversions
+      # @return [Hash]
+      def completion_item
+        @completion_item ||= {
+          label: name,
+          kind: completion_item_kind,
+          detail: detail,
+          data: {
+            path: path,
+            return_type: return_type.tag,
+            location: (location ? location.to_hash : nil),
+            deprecated: deprecated?
+          }
+        }
+      end
+
+      # @return [Hash]
+      def resolve_completion_item
+        @resolve_completion_item ||= begin
+          extra = {}
+          alldoc = ''
+          # alldoc += link_documentation unless link_documentation.nil?
+          # alldoc += "\n\n" unless alldoc.empty?
+          alldoc += documentation unless documentation.nil?
+          extra[:documentation] = alldoc unless alldoc.empty?
+          completion_item.merge(extra)
+        end
+      end
+
+      # @return [Array<Hash>]
+      def signature_help
+        []
+      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 += "=#{probed? ? '~' : (proxied? ? '^' : '>')} #{return_type.to_s}" unless return_type.undefined?
+        detail.strip!
+        return nil if detail.empty?
+        detail
+      end
+
+      # Get a markdown-flavored link to a documentation page.
+      #
+      # @return [String]
+      def link_documentation
+        @link_documentation ||= generate_link
+      end
+
+      def text_documentation
+        this_path = path || return_type.tag
+        return nil if this_path == 'undefined'
+        escape_brackets this_path
+      end
+
+      def reset_conversions
+        @completion_item = nil
+        @resolve_completion_item = nil
+        @signature_help = nil
+        @detail = nil
+        @link_documentation = nil
+      end
+
+      private
+
+      # @return [String]
+      def generate_link
+        this_path = path || return_type.tag
+        return nil if this_path == 'undefined'
+        return nil if this_path.nil? || this_path == 'undefined'
+        "[#{escape_brackets(this_path).gsub('_', '\\\\_')}](solargraph:/document?query=#{CGI.escape(this_path)})"
+      end
+
+      # @param text [String]
+      # @return [String]
+      def escape_brackets text
+        # text.gsub(/(\<|\>)/, "\\#{$1}")
+        text.gsub("<", '\<').gsub(">", '\>')
+      end
+    end
+  end
+end