jimeh-solargraph 0.40.4.0

data/lib/solargraph/yard_map/core_docs.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'fileutils'
+
+module Solargraph
+  class YardMap
+    # Tools for managing core documentation.
+    #
+    module CoreDocs
+      # The URL for downloading core documentation
+      SOURCE = 'https://solargraph.org/download'
+
+      # The default core documentation version
+      DEFAULT = '2.2.2'
+
+      class << self
+        # The directory where core documentation is installed.
+        #
+        # @return [String]
+        def cache_dir
+          # The directory is not stored in a variable so it can be overridden
+          # in specs.
+          ENV['SOLARGRAPH_CACHE'] || File.join(Dir.home, '.solargraph', 'cache')
+        end
+
+        # Ensure installation of minimum documentation.
+        #
+        # @return [void]
+        def require_minimum
+          FileUtils.mkdir_p File.join(cache_dir, 'gems')
+          return unless best_match.nil?
+          FileUtils.cp File.join(Solargraph::YARDOC_PATH, "#{DEFAULT}.tar.gz"), cache_dir
+          install_archive File.join(cache_dir, "#{DEFAULT}.tar.gz")
+        end
+
+        # True if core documentation is installed for the specified version
+        # number.
+        #
+        # @param ver [String] The version number to check
+        # @return [Boolean]
+        def valid?(ver)
+          dir = File.join(cache_dir, ver)
+          return false unless File.directory?(dir)
+          return false unless File.directory?(File.join(dir, 'yardoc'))
+          return false unless File.directory?(File.join(dir, 'yardoc-stdlib'))
+          true
+        end
+
+        # Get a list of version numbers for currently installed core
+        # documentation.
+        #
+        # @return [Array<String>] The installed version numbers
+        def versions
+          dirs = Dir[File.join(cache_dir, '*')].map{|d| File.basename(d)}
+          dirs.keep_if{|d| valid?(d)}
+          dirs.sort!{|a, b| Gem::Version.new(b) <=> Gem::Version.new(a)}
+          dirs
+        end
+
+        # Get the version number of the installed core documentation that is
+        # the closest match for the current Ruby version.
+        #
+        # @return [String] The closest match
+        def best_match
+          avail = versions
+          cur = Gem::Version.new(RUBY_VERSION)
+          avail.each do |v|
+            return v if Gem::Version.new(v) <= cur
+          end
+          avail.last
+        end
+
+        # Get a list of core documentation versions that are available for
+        # download.
+        #
+        # @return [Array<String>] The version numbers
+        def available
+          uri = URI.parse("#{SOURCE}/versions.json")
+          response = Net::HTTP.get_response(uri)
+          obj = JSON.parse(response.body)
+          raise SourceNotAvailableError, "Error connecting to #{SOURCE}" unless obj['status'] == 'ok'
+          obj['cores']
+        end
+
+        # Get the version number of core documentation available for download
+        # that is the closest match for the current Ruby version.
+        #
+        # @param current [String] The version to compare
+        # @return [String] The version number of the best match
+        def best_download current = RUBY_VERSION
+          rv = Gem::Version.new(current)
+          found = available
+          found.each do |ver|
+            return ver if Gem::Version.new(ver) <= rv
+          end
+          found.last
+        end
+
+        # Get the path to a yardoc file for Ruby core documentation.
+        #
+        # @param ver [String] The version number (best match is default)
+        # @return [String] The path to the yardoc
+        def yardoc_file(ver = best_match)
+          raise ArgumentError, "Invalid core yardoc version #{ver}" unless valid?(ver)
+          File.join(cache_dir, ver, 'yardoc')
+        end
+
+        # Get the path to a yardoc file for Ruby stdlib documentation.
+        #
+        # @param ver [String] The version number (best match is default)
+        # @return [String] The path to the yardoc
+        def yardoc_stdlib_file(ver = best_match)
+          raise ArgumentError, "Invalid core yardoc version #{ver}" unless valid?(ver)
+          File.join(cache_dir, ver, 'yardoc-stdlib')
+        end
+
+        # Download the specified version of core documentation.
+        #
+        # @param version [String]
+        # @return [void]
+        def download version
+          FileUtils.mkdir_p cache_dir
+          uri = URI.parse("#{SOURCE}/#{version}.tar.gz")
+          # @type [Net::HTTPResponse]
+          response = Net::HTTP.get_response(uri)
+          if response.code == '404'
+            raise ArgumentError, "Version #{version} is not available from #{SOURCE}"
+          else
+            zipfile = File.join(cache_dir, "#{version}.tar.gz")
+            File.binwrite zipfile, response.body
+            install_archive zipfile
+          end
+        end
+
+        # Reset the core documentation cache to the minimum requirement.
+        #
+        # @return [void]
+        def clear
+          FileUtils.rm_rf cache_dir, secure: true
+          require_minimum
+        end
+
+        private
+
+        # Extract the specified archive to the core cache directory.
+        #
+        # @param filename [String]
+        # @return [void]
+        def install_archive filename
+          tar_extract = Gem::Package::TarReader.new(Zlib::GzipReader.open(filename))
+          tar_extract.rewind
+          tar_extract.each do |entry|
+            if entry.directory?
+              FileUtils.mkdir_p File.join(cache_dir, entry.full_name)
+            else
+              FileUtils.mkdir_p File.join(cache_dir, File.dirname(entry.full_name))
+              File.open(File.join(cache_dir, entry.full_name), 'wb') do |f|
+                f << entry.read
+              end
+            end
+          end
+          tar_extract.close
+        end
+      end
+    end
+  end
+end

data/lib/solargraph/yard_map/core_fills.rb

@@ -0,0 +1,185 @@
+module Solargraph
+  class YardMap
+    module CoreFills
+      Override = Pin::Reference::Override
+
+      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'
+      ].map { |k| Pin::Keyword.new(k) }
+
+      methods_with_yieldparam_subtypes = %w[
+        Array#each Array#map Array#map! Array#any? Array#all? Array#index
+        Array#keep_if Array#delete_if
+        Enumerable#each_entry Enumerable#map Enumerable#any? Enumerable#all?
+        Enumerable#select Enumerable#reject
+        Set#each
+      ]
+
+      OVERRIDES = [
+        Override.method_return('Array#concat', 'Array'),
+        Override.method_return('Array#keep_if', 'self'),
+        Override.method_return('Array#delete_if', 'self'),
+        Override.from_comment('Array#map', %(
+@overload map(&block)
+  @return [Array]
+@overload map()
+  @return [Enumerator]
+        )),
+        Override.from_comment('Array#reject', %(
+@overload reject(&block)
+  @return [self]
+@overload reject()
+  @return [Enumerator]
+        )),
+        Override.method_return('Array#reverse', 'self', delete: ['overload']),
+        Override.from_comment('Array#select', %(
+@overload select(&block)
+  @return [self]
+@overload select()
+  @return [Enumerator]
+        )),
+        Override.from_comment('Array#[]', %(
+@overload [](range)
+  @param range [Range]
+  @return [self]
+@overload [](num1, num2)
+  @param num1 [Integer]
+  @param num2 [Integer]
+  @return [self]
+@overload [](num)
+  @param num [Integer]
+  @return_single_parameter
+@return_single_parameter
+        )),
+        Override.from_comment('Array#first', %(
+@overload first(num)
+  @param num [Integer]
+  @return [self]
+@return_single_parameter
+        )),
+        Override.from_comment('Array#last', %(
+@overload last(num)
+  @param num [Integer]
+  @return [self]
+@return_single_parameter
+        )),
+        Override.method_return('Array#map', 'Array'),
+        Override.method_return('Array#uniq', 'self'),
+        Override.method_return('Array#zip', 'Array, nil'),
+
+        Override.from_comment('BasicObject#==', %(
+@param other [BasicObject]
+@return [Boolean]
+        )),
+        Override.method_return('BasicObject#initialize', 'void'),
+
+        Override.method_return('Class#new', 'self'),
+        Override.method_return('Class.new', 'Class<Object>'),
+        Override.method_return('Class#allocate', 'self'),
+        Override.method_return('Class.allocate', 'Class<Object>'),
+
+        Override.method_return('Enumerable#select', 'self'),
+
+        Override.method_return('File.absolute_path', 'String'),
+        Override.method_return('File.basename', 'String'),
+        Override.method_return('File.dirname', 'String'),
+        Override.method_return('File.extname', 'String'),
+        Override.method_return('File.join', 'String'),
+
+        Override.from_comment('Float#+', %(
+@param y [Numeric]
+@return [Numeric]
+        )),
+
+        Override.from_comment('Hash#[]', %(
+@return_value_parameter
+        )),
+
+        # @todo This override isn't robust enough. It needs to allow for
+        #   parameterized Hash types, e.g., [Hash{Symbol => String}].
+        Override.from_comment('Hash#[]=', %(
+@param_tuple
+        )),
+
+        Override.method_return('Hash#merge', 'Hash'),
+
+        Override.from_comment('Integer#+', %(
+@param y [Numeric]
+@return [Numeric]
+        )),
+
+        Override.method_return('Kernel#puts', 'nil'),
+
+        Override.from_comment('Numeric#+', %(
+@param y [Numeric]
+@return [Numeric]
+        )),
+
+        Override.method_return('Object#!', 'Boolean'),
+        Override.method_return('Object#clone', 'self', delete: [:overload]),
+        Override.method_return('Object#dup', 'self', delete: [:overload]),
+        Override.method_return('Object#freeze', 'self', delete: [:overload]),
+        Override.method_return('Object#inspect', 'String'),
+        Override.method_return('Object#taint', 'self'),
+        Override.method_return('Object#to_s', 'String'),
+        Override.method_return('Object#untaint', 'self'),
+        Override.from_comment('Object#tap', %(
+@return [self]
+@yieldparam [self]
+        )),
+
+        Override.from_comment('STDERR', %(
+@type [IO]
+        )),
+
+        Override.from_comment('STDIN', %(
+@type [IO]
+        )),
+
+        Override.from_comment('STDOUT', %(
+@type [IO]
+        )),
+
+        Override.method_return('String#freeze', 'self'),
+        Override.method_return('String#split', 'Array<String>'),
+        Override.method_return('String#lines', 'Array<String>'),
+        Override.from_comment('String#each_line', %(
+@yieldparam [String]
+        )),
+        Override.from_comment('String.new', %(
+@overload new(*)
+  @return [self]
+      ))
+      ].concat(
+        methods_with_yieldparam_subtypes.map do |path|
+          Override.from_comment(path, %(
+@yieldparam_single_parameter
+            ))
+        end
+      )
+
+      PINS = [
+        Pin::Reference::Superclass.new(closure: Pin::Namespace.new(name: 'File'), name: 'IO'),
+        Pin::Reference::Superclass.new(closure: Pin::Namespace.new(name: 'Integer'), name: 'Numeric'),
+        Pin::Reference::Superclass.new(closure: Pin::Namespace.new(name: 'Float'), name: 'Numeric')
+      ].concat(
+        # HACK: Add Errno exception classes
+        begin
+          errno = Solargraph::Pin::Namespace.new(name: 'Errno')
+          result = []
+          Errno.constants.each do |const|
+            result.push Solargraph::Pin::Namespace.new(type: :class, name: const.to_s, closure: errno)
+            result.push Solargraph::Pin::Reference::Superclass.new(closure: result.last, name: 'SystemCallError')
+          end
+          result
+        end
+      )
+
+      ALL = KEYWORDS + PINS + OVERRIDES
+    end
+  end
+end

data/lib/solargraph/yard_map/core_gen.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tmpdir'
+require 'pathname'
+require 'rubygems/package'
+require 'shellwords'
+
+module Solargraph
+  class YardMap
+    # Tools for generating core documentation.
+    #
+    module CoreGen
+      class << self
+        # Generate documentation from the specified Ruby source directory.
+        #
+        # @param ruby_dir [String] The Ruby source directory
+        # @param dest_dir [String] The destination directory for the yardocs
+        # @return [void]
+        def generate_docs ruby_dir, dest_dir
+          path_name = Pathname.new(Dir.pwd).join(dest_dir).to_s
+          FileUtils.mkdir_p path_name
+          Dir.chdir(ruby_dir) do
+            `yardoc -b "#{File.join(path_name, 'yardoc')}" -n *.c`
+            raise 'An error occurred generating the core yardoc.' unless $?.success?
+            `yardoc -b "#{File.join(path_name, 'yardoc-stdlib')}" -n lib ext`
+            raise 'An error occurred generating the stdlib yardoc.' unless $?.success?
+          end
+        end
+
+        # Generate a gzip of documentation from the specified Ruby source
+        # directory.
+        #
+        # This method is designed to generate the directory architecture that
+        # YardMap core docs expect.
+        #
+        # @param ruby_dir [String] The Ruby source directory
+        # @param ver_name [String, nil] The version name
+        # @param dest_dir [String] The destination directory
+        # @return [void]
+        def generate_gzip ruby_dir, ver_name = nil, dest_dir = Dir.pwd
+          Dir.mktmpdir do |tmp|
+            base_name = ver_name || begin
+              match = ruby_dir.match(/\d+\.\d+\.\d+$/)
+              raise "Unable to determine version name from #{ruby_dir}" if match.nil?
+              match[0]
+            end
+            path_name = Pathname.new(tmp).join(base_name).to_s
+            generate_docs ruby_dir, path_name
+            gzip path_name, Pathname.new(dest_dir).join("#{base_name}.tar.gz").to_s
+          end
+        end
+
+        private
+
+        # @param dir [String] The directory to compress
+        # @param dst [String] The destination file
+        def gzip dir, dst
+          File.open(dst, 'wb') do |file|
+            Zlib::GzipWriter.wrap(file) do |gzip|
+              Gem::Package::TarWriter.new(gzip) do |tar|
+                Dir["#{dir}/**/*"].each do |filename|
+                  next if File.directory?(filename)
+                  relname = File.join(File.basename(dir), filename[dir.length+1..-1])
+                  tar.add_file_simple(relname, 0o644, File.size(filename)) do |io|
+                    io.write File.read_binary(filename)
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solargraph/yard_map/helpers.rb

@@ -0,0 +1,16 @@
+module Solargraph
+  class YardMap
+    module Helpers
+      module_function
+
+      # @param code_object [YARD::CodeObjects::Base]
+      # @param spec [Gem::Specification]
+      # @return [Solargraph::Location, nil]
+      def object_location code_object, spec
+        return nil if spec.nil? || code_object.nil? || code_object.file.nil? || code_object.line.nil?
+        file = File.join(spec.full_gem_path, code_object.file)
+        Solargraph::Location.new(file, Solargraph::Range.from_to(code_object.line - 1, 0, code_object.line - 1, 0))
+      end
+    end
+  end
+end