cosmicgraph 0.49.0

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Solargraph
+  class YardMap
+    class Mapper
+      module ToNamespace
+        extend YardMap::Helpers
+
+        def self.make code_object, spec, closure = nil
+          closure ||= Solargraph::Pin::Namespace.new(
+            name: code_object.namespace.to_s,
+            closure: Pin::ROOT_PIN,
+            gates: [code_object.namespace.to_s]
+          )
+          Pin::Namespace.new(
+            location: object_location(code_object, spec),
+            name: code_object.name.to_s,
+            comments: code_object.docstring ? code_object.docstring.all.to_s : '',
+            type: code_object.is_a?(YARD::CodeObjects::ClassObject) ? :class : :module,
+            visibility: code_object.visibility,
+            closure: closure
+          )
+        end
+      end
+    end
+  end
+end

data/lib/solargraph/yard_map/mapper.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Solargraph
+  class YardMap
+    class Mapper
+      autoload :ToMethod, 'solargraph/yard_map/mapper/to_method'
+      autoload :ToNamespace, 'solargraph/yard_map/mapper/to_namespace'
+      autoload :ToConstant, 'solargraph/yard_map/mapper/to_constant'
+
+      # @param code_objects [Array<YARD::CodeObjects::Base>]
+      # @param spec [Gem::Specification]
+      def initialize code_objects, spec = nil
+        @code_objects = code_objects
+        @spec = spec
+        @pins = []
+        @namespace_pins = {}
+      end
+
+      # @return [Array<Pin::Base>]
+      def map
+        @code_objects.each do |co|
+          @pins.concat generate_pins co
+        end
+        # Some yardocs contain documentation for dependencies that can be
+        # ignored here. The YardMap will load dependencies separately.
+        @pins.keep_if { |pin| pin.location.nil? || File.file?(pin.location.filename) } if @spec
+        @pins
+      end
+
+      private
+
+      # @param code_object [YARD::CodeObjects::Base]
+      # @return [Array<Pin::Base>]
+      def generate_pins code_object
+        result = []
+        if code_object.is_a?(YARD::CodeObjects::NamespaceObject)
+          nspin = ToNamespace.make(code_object, @spec, @namespace_pins[code_object.namespace.to_s])
+          @namespace_pins[code_object.path] = nspin
+          result.push nspin
+          if code_object.is_a?(YARD::CodeObjects::ClassObject) and !code_object.superclass.nil?
+            # This method of superclass detection is a bit of a hack. If
+            # the superclass is a Proxy, it is assumed to be undefined in its
+            # yardoc and converted to a fully qualified namespace.
+            superclass = if code_object.superclass.is_a?(YARD::CodeObjects::Proxy)
+              "::#{code_object.superclass}"
+            else
+              code_object.superclass.to_s
+            end
+            result.push Solargraph::Pin::Reference::Superclass.new(name: superclass, closure: nspin)
+          end
+          code_object.class_mixins.each do |m|
+            result.push Solargraph::Pin::Reference::Extend.new(closure: nspin, name: m.path)
+          end
+          code_object.instance_mixins.each do |m|
+            result.push Solargraph::Pin::Reference::Include.new(
+              closure: nspin, # @todo Fix this
+              name: m.path
+            )
+          end
+        elsif code_object.is_a?(YARD::CodeObjects::MethodObject)
+          closure = @namespace_pins[code_object.namespace.to_s]
+          if code_object.name == :initialize && code_object.scope == :instance
+            # @todo Check the visibility of <Class>.new
+            result.push ToMethod.make(code_object, 'new', :class, :public, closure, @spec)
+            result.push ToMethod.make(code_object, 'initialize', :instance, :private, closure, @spec)
+          else
+            result.push ToMethod.make(code_object, nil, nil, nil, closure, @spec)
+          end
+        elsif code_object.is_a?(YARD::CodeObjects::ConstantObject)
+          closure = @namespace_pins[code_object.namespace]
+          result.push ToConstant.make(code_object, closure, @spec)
+        end
+        result
+      end
+    end
+  end
+end

data/lib/solargraph/yard_map/to_method.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Solargraph
+  class YardMap
+    class ToMethod
+      module InnerMethods
+        module_function
+
+        # @param code_object [YARD::CodeObjects::Base]
+        # @return [Array<Solargraph::Pin::Parameter>]
+        def get_parameters code_object, location, comments
+          return [] unless code_object.is_a?(YARD::CodeObjects::MethodObject)
+          # HACK: Skip `nil` and `self` parameters that are sometimes emitted
+          # for methods defined in C
+          # See https://github.com/castwide/solargraph/issues/345
+          code_object.parameters.select { |a| a[0] && a[0] != 'self' }.map do |a|
+            Solargraph::Pin::Parameter.new(
+              location: location,
+              closure: self,
+              comments: comments,
+              name: arg_name(a),
+              presence: nil,
+              decl: arg_type(a),
+              asgn_code: a[1]
+            )
+          end
+        end
+
+        # @param a [Array]
+        # @return [String]
+        def arg_name a
+          a[0].gsub(/[^a-z0-9_]/i, '')
+        end
+
+        # @param a [Array]
+        # @return [::Symbol]
+        def arg_type a
+          if a[0].start_with?('**')
+            :kwrestarg
+          elsif a[0].start_with?('*')
+            :restarg
+          elsif a[0].start_with?('&')
+            :blockarg
+          elsif a[0].end_with?(':')
+            a[1] ? :kwoptarg : :kwarg
+          elsif a[1]
+            :optarg
+          else
+            :arg
+          end
+        end
+      end
+      private_constant :InnerMethods
+
+      # include YardMixin
+      # extend YardMixin
+      extend Helpers
+
+      def make code_object, name = nil, scope = nil, visibility = nil, closure = nil, spec = nil
+        closure ||= Solargraph::Pin::Namespace.new(
+          name: code_object.namespace.to_s,
+          gates: [code_object.namespace.to_s]
+        )
+        location = object_location(code_object, spec)
+        comments = code_object.docstring ? code_object.docstring.all.to_s : ''
+        Pin::Method.new(
+          location: location,
+          closure: closure,
+          name: name || code_object.name.to_s,
+          comments: comments,
+          scope: scope || code_object.scope,
+          visibility: visibility || code_object.visibility,
+          parameters: InnerMethods.get_parameters(code_object, location, comments),
+          explicit: code_object.is_explicit?
+        )
+      end
+    end
+  end
+end

data/lib/solargraph/yard_map.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require 'yard'
+require 'yard-solargraph'
+require 'rubygems/package'
+require 'set'
+
+module Solargraph
+  # The YardMap provides access to YARD documentation for the Ruby core, the
+  # stdlib, and gems.
+  #
+  class YardMap
+    class NoYardocError < StandardError; end
+
+    autoload :Cache,       'solargraph/yard_map/cache'
+    autoload :Mapper,      'solargraph/yard_map/mapper'
+    autoload :RdocToYard,  'solargraph/yard_map/rdoc_to_yard'
+    autoload :Helpers,     'solargraph/yard_map/helpers'
+    autoload :ToMethod,    'solargraph/yard_map/to_method'
+
+    include ApiMap::BundlerMethods
+
+    # @return [Boolean]
+    attr_writer :with_dependencies
+
+    # @param required [Array<String>, Set<String>]
+    # @param directory [String]
+    # @param source_gems [Array<String>, Set<String>]
+    # @param with_dependencies [Boolean]
+    def initialize(required: [], directory: '', source_gems: [], with_dependencies: true)
+      @with_dependencies = with_dependencies
+      change required.to_set, directory, source_gems.to_set
+    end
+
+    # @return [Array<Solargraph::Pin::Base>]
+    def pins
+      @pins ||= []
+    end
+
+    def with_dependencies?
+      @with_dependencies ||= true unless @with_dependencies == false
+      @with_dependencies
+    end
+
+    # @param new_requires [Set<String>] Required paths to use for loading gems
+    # @param new_directory [String] The workspace directory
+    # @param new_source_gems [Set<String>] Gems under local development (i.e., part of the workspace)
+    # @return [Boolean]
+    def change new_requires, new_directory, new_source_gems
+      return false if new_requires == base_required && new_directory == @directory && new_source_gems == @source_gems
+      @gem_paths = {}
+      base_required.replace new_requires
+      required.replace new_requires
+      # HACK: Hardcoded YAML handling
+      required.add 'psych' if new_requires.include?('yaml')
+      @source_gems = new_source_gems
+      @directory = new_directory
+      process_requires
+      @rebindable_method_names = nil
+      @pin_class_hash = nil
+      @pin_select_cache = {}
+      pins.each { |p| p.source = :yard }
+      true
+    end
+
+    # @return [Set<String>]
+    def rebindable_method_names
+      @rebindable_method_names ||= pins_by_class(Pin::Method)
+        .select { |pin| pin.comments && pin.comments.include?('@yieldself') }
+        .map(&:name)
+        .concat(['instance_eval', 'instance_exec', 'class_eval', 'class_exec', 'module_eval', 'module_exec', 'define_method'])
+        .to_set
+    end
+
+    # @return [Array<String>]
+    def yardocs
+      @yardocs ||= []
+    end
+
+    # @return [Set<String>]
+    def required
+      @required ||= Set.new
+    end
+
+    # @return [Array<String>]
+    def unresolved_requires
+      @unresolved_requires ||= []
+    end
+
+    # @return [Array<String>]
+    def missing_docs
+      @missing_docs ||= []
+    end
+
+    # @param y [String]
+    # @return [YARD::Registry]
+    def load_yardoc y
+      if y.is_a?(Array)
+        YARD::Registry.load y, true
+      else
+        YARD::Registry.load! y
+      end
+    rescue StandardError => e
+      Solargraph::Logging.logger.warn "Error loading yardoc '#{y}' #{e.class} #{e.message}"
+      yardocs.delete y
+      nil
+    end
+
+    # @param path [String]
+    # @return [Pin::Base]
+    def path_pin path
+      pins.select { |p| p.path == path }.first
+    end
+
+    # Get the location of a file referenced by a require path.
+    #
+    # @param path [String]
+    # @return [Location]
+    def require_reference path
+      # @type [Gem::Specification]
+      spec = spec_for_require(path)
+      spec.full_require_paths.each do |rp|
+        file = File.join(rp, "#{path}.rb")
+        next unless File.file?(file)
+        return Solargraph::Location.new(file, Solargraph::Range.from_to(0, 0, 0, 0))
+      end
+      nil
+    rescue Gem::LoadError
+      nil
+    end
+
+    def base_required
+      @base_required ||= Set.new
+    end
+
+    def directory
+      @directory ||= ''
+    end
+
+    private
+
+    # @return [YardMap::Cache]
+    def cache
+      @cache ||= YardMap::Cache.new
+    end
+
+    # @return [Hash]
+    def pin_class_hash
+      @pin_class_hash ||= pins.to_set.classify(&:class).transform_values(&:to_a)
+    end
+
+    # @return [Array<Pin::Base>]
+    def pins_by_class klass
+      @pin_select_cache[klass] ||= pin_class_hash.select { |key, _| key <= klass }.values.flatten
+    end
+
+    # @param ns [YARD::CodeObjects::NamespaceObject]
+    # @return [Array<YARD::CodeObjects::Base>]
+    def recurse_namespace_object ns
+      result = []
+      ns.children.each do |c|
+        result.push c
+        result.concat recurse_namespace_object(c) if c.respond_to?(:children)
+      end
+      result
+    end
+
+    # @return [void]
+    def process_requires
+      @gemset = process_gemsets
+      required.merge @gemset.keys if required.include?('bundler/require')
+      pins.clear
+      unresolved_requires.clear
+      missing_docs.clear
+      environ = Convention.for_global(self)
+      done = []
+      already_errored = []
+      (required + environ.requires).each do |r|
+        next if r.nil? || r.empty? || done.include?(r)
+        done.push r
+        cached = cache.get_path_pins(r)
+        unless cached.nil?
+          pins.concat cached
+          next
+        end
+        result = pins_for_require r, already_errored
+        result.delete_if(&:nil?)
+        unless result.empty?
+          cache.set_path_pins r, result
+          pins.concat result
+        end
+      end
+      if required.include?('yaml') && required.include?('psych')
+        # HACK: Hardcoded YAML handling
+        # @todo Why can't this be handled with an override or a virtual pin?
+        pin = path_pin('YAML')
+        pin.instance_variable_set(:@return_type, ComplexType.parse('Module<Psych>')) unless pin.nil?
+      end
+      pins.concat environ.pins
+    end
+
+    def process_error(req, result, already_errored, yd = 1)
+      base = req.split('/').first
+      return if already_errored.include?(base)
+      already_errored.push base
+      if yd.nil?
+        missing_docs.push req
+      else
+        unresolved_requires.push req
+      end
+    end
+
+    def process_gemsets
+      return {} if directory.empty? || !File.file?(File.join(directory, 'Gemfile'))
+      require_from_bundle(directory)
+    end
+
+    # @param r [String]
+    def pins_for_require r, already_errored
+      result = []
+      begin
+        name = r.split('/').first
+        return [] if name.empty? || @source_gems.include?(name) || @gem_paths.key?(name)
+        spec = spec_for_require(name)
+        @gem_paths[name] = spec.full_gem_path
+
+        yd = yardoc_file_for_spec(spec)
+        # YARD detects gems for certain libraries that do not have a yardoc
+        # but exist in the stdlib. `fileutils` is an example. Treat those
+        # cases as errors and check the stdlib yardoc.
+        if yd.nil?
+          process_error(r, result, already_errored, nil)
+          return []
+        end
+        unless yardocs.include?(yd)
+          yardocs.unshift yd
+          result.concat process_yardoc yd, spec
+          if with_dependencies?
+            (spec.dependencies - spec.development_dependencies).each do |dep|
+              result.concat pins_for_require dep.name, already_errored
+            end
+          end
+        end
+      rescue Gem::LoadError, NoYardocError
+        process_error(r, result, already_errored)
+      end
+      return result
+    end
+
+    # @param y [String, nil]
+    # @param spec [Gem::Specification, nil]
+    # @return [Array<Pin::Base>]
+    def process_yardoc y, spec = nil
+      return [] if y.nil?
+      if spec
+        cache = Solargraph::Cache.load('gems', "#{spec.name}-#{spec.version}.ser")
+        return cache if cache
+      end
+      size = Dir.glob(File.join(y, '**', '*'))
+        .map{ |f| File.size(f) }
+        .inject(:+)
+      if !size.nil? && size > 20_000_000
+        Solargraph::Logging.logger.warn "Yardoc at #{y} is too large to process (#{size} bytes)"
+        return []
+      end
+      Solargraph.logger.info "Loading #{spec.name} #{spec.version} from #{y}"
+      load_yardoc y
+      result = Mapper.new(YARD::Registry.all, spec).map
+      raise NoYardocError, "Yardoc at #{y} is empty" if result.empty?
+      if spec
+        Solargraph::Cache.save 'gems', "#{spec.name}-#{spec.version}.ser", result
+      end
+      result
+    end
+
+    # @param spec [Gem::Specification]
+    # @return [String]
+    def yardoc_file_for_spec spec
+      YARD::Registry.yardoc_file_for_gem(spec.name, "= #{spec.version}")
+    end
+
+    # @param path [String]
+    # @return [Gem::Specification]
+    def spec_for_require path
+      name = path.split('/').first
+      spec = Gem::Specification.find_by_name(name, @gemset[name])
+
+      # Avoid loading the spec again if it's going to be skipped anyway
+      return spec if @source_gems.include?(spec.name)
+      # Avoid loading the spec again if it's already the correct version
+      if @gemset[spec.name] && @gemset[spec.name] != spec.version
+        begin
+          return Gem::Specification.find_by_name(spec.name, "= #{@gemset[spec.name]}")
+        rescue Gem::LoadError
+          Solargraph.logger.warn "Unable to load #{spec.name} #{@gemset[spec.name]} specified by workspace, using #{spec.version} instead"
+        end
+      end
+      spec
+    end
+  end
+end

data/lib/solargraph.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+Encoding.default_external = 'UTF-8'
+
+require 'solargraph/version'
+
+# The top-level namespace for the Solargraph code mapping, documentation,
+# static analysis, and language server libraries.
+#
+module Solargraph
+  class InvalidOffsetError         < RangeError;    end
+  class DiagnosticsError           < RuntimeError;  end
+  class FileNotFoundError          < RuntimeError;  end
+  class SourceNotAvailableError    < StandardError; end
+  class ComplexTypeError           < StandardError; end
+  class WorkspaceTooLargeError     < RuntimeError;  end
+  class BundleNotFoundError        < StandardError; end
+  class InvalidRubocopVersionError < RuntimeError;  end
+
+  autoload :Position,         'solargraph/position'
+  autoload :Range,            'solargraph/range'
+  autoload :Location,         'solargraph/location'
+  autoload :Shell,            'solargraph/shell'
+  autoload :Source,           'solargraph/source'
+  autoload :SourceMap,        'solargraph/source_map'
+  autoload :ApiMap,           'solargraph/api_map'
+  autoload :YardMap,          'solargraph/yard_map'
+  autoload :Pin,              'solargraph/pin'
+  autoload :ServerMethods,    'solargraph/server_methods'
+  autoload :LanguageServer,   'solargraph/language_server'
+  autoload :Workspace,        'solargraph/workspace'
+  autoload :Page,             'solargraph/page'
+  autoload :Library,          'solargraph/library'
+  autoload :Diagnostics,      'solargraph/diagnostics'
+  autoload :ComplexType,      'solargraph/complex_type'
+  autoload :Bench,            'solargraph/bench'
+  autoload :Logging,          'solargraph/logging'
+  autoload :TypeChecker,      'solargraph/type_checker'
+  autoload :Environ,          'solargraph/environ'
+  autoload :Convention,       'solargraph/convention'
+  autoload :Documentor,       'solargraph/documentor'
+  autoload :Parser,           'solargraph/parser'
+  autoload :RbsMap,           'solargraph/rbs_map'
+  autoload :Cache,            'solargraph/cache'
+
+  dir = File.dirname(__FILE__)
+  YARD_EXTENSION_FILE = File.join(dir, 'yard-solargraph.rb')
+  VIEWS_PATH = File.join(dir, 'solargraph', 'views')
+
+  # A convenience method for Solargraph::Logging.logger.
+  #
+  # @return [Logger]
+  def self.logger
+    Solargraph::Logging.logger
+  end
+
+  # A helper method that runs Bundler.with_unbundled_env or falls back to
+  # Bundler.with_clean_env for earlier versions of Bundler.
+  #
+  # @return [void]
+  def self.with_clean_env &block
+    meth = if Bundler.respond_to?(:with_original_env)
+      :with_original_env
+    else
+      :with_clean_env
+    end
+    Bundler.send meth, &block
+  end
+end

data/lib/yard-solargraph.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'yard'
+
+# Change YARD log IO to avoid sending unexpected messages to STDOUT
+YARD::Logger.instance.io = File.new(File::NULL, 'w')
+
+module Solargraph
+  # A placeholder for the @!domain directive. It doesn't need to do anything
+  # for yardocs. It's only used for Solargraph API maps.
+  class DomainDirective < YARD::Tags::Directive
+    def call; end
+  end
+end
+
+# Define a @type tag for documenting variables
+YARD::Tags::Library.define_tag("Type", :type, :with_types_and_name)
+# Define a @yieldself tag for documenting block contexts
+YARD::Tags::Library.define_tag("Yieldself", :yieldself, :with_types)
+# Define a @yieldpublic tag for documenting block domains
+YARD::Tags::Library.define_tag("Yieldpublic", :yieldpublic, :with_types)
+# Define a @return_single_parameter tag for returning e.g. Array parameters
+YARD::Tags::Library.define_tag('ReturnSingleParameter', :return_single_parameter)
+# Define a @yieldparam_single_parameter tag for yielding e.g. Array parameters
+YARD::Tags::Library.define_tag('YieldparamSingleParameter', :yieldparam_single_parameter)
+# Define a @return_value_parameter tag for returning e.g. Hash values
+YARD::Tags::Library.define_tag('ReturnValueParameter', :return_value_parameter)
+# Define a @param_tuple tag for e.g. Hash#[]= parameters
+YARD::Tags::Library.define_tag('ParamTuple', :param_tuple)
+# Define a @!domain directive for documenting DSLs
+YARD::Tags::Library.define_directive("domain", :with_types, Solargraph::DomainDirective)
+# Define an @!override directive for overriding method tags
+YARD::Tags::Library.define_directive("override", :with_name, Solargraph::DomainDirective)