solargraph 0.58.1 → 0.59.0.dev.1

data/lib/solargraph/yardoc.rb

@@ -1,87 +1,97 @@
-# frozen_string_literal: true
-
-require 'open3'
-
-module Solargraph
-  # Methods for caching and loading YARD documentation for gems.
-  #
-  module Yardoc
-    module_function
-
-    # Build and cache a gem's yardoc and return the path. If the cache already
-    # exists, do nothing and return the path.
-    #
-    # @param yard_plugins [Array<String>] The names of YARD plugins to use.
-    # @param gemspec [Gem::Specification]
-    # @return [String] The path to the cached yardoc.
-    def cache(yard_plugins, gemspec)
-      path = PinCache.yardoc_path gemspec
-      return path if cached?(gemspec)
-
-      unless Dir.exist? gemspec.gem_dir
-        # Can happen in at least some (old?) RubyGems versions when we
-        # have a gemspec describing a standard library like bundler.
-        #
-        # https://github.com/apiology/solargraph/actions/runs/17650140201/job/50158676842?pr=10
-        Solargraph.logger.info { "Bad info from gemspec - #{gemspec.gem_dir} does not exist" }
-        return path
-      end
-
-      Solargraph.logger.info "Caching yardoc for #{gemspec.name} #{gemspec.version}"
-      cmd = "yardoc --db #{path} --no-output --plugin solargraph"
-      yard_plugins.each { |plugin| cmd << " --plugin #{plugin}" }
-      Solargraph.logger.debug { "Running: #{cmd}" }
-      # @todo set these up to run in parallel
-      stdout_and_stderr_str, status = Open3.capture2e(current_bundle_env_tweaks, cmd, chdir: gemspec.gem_dir)
-      unless status.success?
-        Solargraph.logger.warn { "YARD failed running #{cmd.inspect} in #{gemspec.gem_dir}" }
-        Solargraph.logger.info stdout_and_stderr_str
-      end
-      path
-    end
-
-    # True if the gem yardoc is cached.
-    #
-    # @param gemspec [Gem::Specification]
-    def cached?(gemspec)
-      yardoc = File.join(PinCache.yardoc_path(gemspec), 'complete')
-      File.exist?(yardoc)
-    end
-
-    # True if another process is currently building the yardoc cache.
-    #
-    # @param gemspec [Gem::Specification]
-    def processing?(gemspec)
-      yardoc = File.join(PinCache.yardoc_path(gemspec), 'processing')
-      File.exist?(yardoc)
-    end
-
-    # Load a gem's yardoc and return its code objects.
-    #
-    # @note This method modifies the global YARD registry.
-    #
-    # @param gemspec [Gem::Specification]
-    # @return [Array<YARD::CodeObjects::Base>]
-    def load!(gemspec)
-      YARD::Registry.load! PinCache.yardoc_path gemspec
-      YARD::Registry.all
-    end
-
-    # If the BUNDLE_GEMFILE environment variable is set, we need to
-    # make sure it's an absolute path, as we'll be changing
-    # directories.
-    #
-    # 'bundle exec' sets an absolute path here, but at least the
-    # overcommit gem does not, breaking on-the-fly documention with a
-    # spawned yardoc command from our current bundle
-    #
-    # @return [Hash{String => String}] a hash of environment variables to override
-    def current_bundle_env_tweaks
-      tweaks = {}
-      if ENV['BUNDLE_GEMFILE'] && !ENV['BUNDLE_GEMFILE'].empty?
-        tweaks['BUNDLE_GEMFILE'] = File.expand_path(ENV['BUNDLE_GEMFILE'])
-      end
-      tweaks
-    end
-  end
-end
+# frozen_string_literal: true
+
+require 'open3'
+
+module Solargraph
+  # Methods for caching and loading YARD documentation for gems.
+  #
+  module Yardoc
+    module_function
+
+    # Build and save a gem's yardoc into a given path.
+    #
+    # @param gem_yardoc_path [String] the path to the yardoc cache of a particular gem
+    # @param yard_plugins [Array<String>]
+    # @param gemspec [Gem::Specification]
+    #
+    # @return [void]
+    def build_docs gem_yardoc_path, yard_plugins, gemspec
+      return if docs_built?(gem_yardoc_path)
+
+      unless Dir.exist? gemspec.gem_dir
+        # Can happen in at least some (old?) RubyGems versions when we
+        # have a gemspec describing a standard library like bundler.
+        #
+        # https://github.com/apiology/solargraph/actions/runs/17650140201/job/50158676842?pr=10
+        Solargraph.logger.info { "Bad info from gemspec - #{gemspec.gem_dir} does not exist" }
+        return
+      end
+
+      Solargraph.logger.info "Caching yardoc for #{gemspec.name} #{gemspec.version}"
+      cmd = "yardoc --db #{gem_yardoc_path} --no-output --plugin solargraph"
+      yard_plugins.each { |plugin| cmd << " --plugin #{plugin}" }
+      Solargraph.logger.debug { "Running: #{cmd}" }
+      # @todo set these up to run in parallel
+      # @sg-ignore Our fill won't work properly due to an issue in
+      #   Callable#arity_matches? - see comment there
+      stdout_and_stderr_str, status = Open3.capture2e(current_bundle_env_tweaks, cmd, chdir: gemspec.gem_dir)
+      return if status.success?
+      Solargraph.logger.warn { "YARD failed running #{cmd.inspect} in #{gemspec.gem_dir}" }
+      Solargraph.logger.info stdout_and_stderr_str
+    end
+
+    # @param gem_yardoc_path [String] the path to the yardoc cache of a particular gem
+    # @param gemspec [Gem::Specification, Bundler::LazySpecification]
+    # @param out [StringIO, IO, nil] where to log messages
+    # @return [Array<Pin::Base>]
+    def build_pins gem_yardoc_path, gemspec, out: $stderr
+      yardoc = load!(gem_yardoc_path)
+      YardMap::Mapper.new(yardoc, gemspec).map
+    end
+
+    # True if the gem yardoc is cached.
+    #
+    # @param gem_yardoc_path [String]
+    def docs_built? gem_yardoc_path
+      yardoc = File.join(gem_yardoc_path, 'complete')
+      File.exist?(yardoc)
+    end
+
+    # True if another process is currently building the yardoc cache.
+    #
+    # @param gem_yardoc_path [String] the path to the yardoc cache of a particular gem
+    def processing? gem_yardoc_path
+      yardoc = File.join(gem_yardoc_path, 'processing')
+      File.exist?(yardoc)
+    end
+
+    # Load a gem's yardoc and return its code objects.
+    #
+    # @note This method modifies the global YARD registry.
+    #
+    # @param gem_yardoc_path [String] the path to the yardoc cache of a particular gem
+    # @return [Array<YARD::CodeObjects::Base>]
+    def load! gem_yardoc_path
+      YARD::Registry.load! gem_yardoc_path
+      YARD::Registry.all
+    end
+
+    # If the BUNDLE_GEMFILE environment variable is set, we need to
+    # make sure it's an absolute path, as we'll be changing
+    # directories.
+    #
+    # 'bundle exec' sets an absolute path here, but at least the
+    # overcommit gem does not, breaking on-the-fly documention with a
+    # spawned yardoc command from our current bundle
+    #
+    # @return [Hash{String => String}] a hash of environment variables to override
+    def current_bundle_env_tweaks
+      tweaks = {}
+      # @sg-ignore Translate to something flow sensitive typing understands
+      if ENV['BUNDLE_GEMFILE'] && !ENV['BUNDLE_GEMFILE'].empty?
+        tweaks['BUNDLE_GEMFILE'] = File.expand_path(ENV['BUNDLE_GEMFILE'])
+      end
+      tweaks
+    end
+  end
+end

data/lib/solargraph.rb

@@ -1,105 +1,126 @@
-# frozen_string_literal: true
-
-Encoding.default_external = 'UTF-8'
-
-require 'bundler'
-require 'set'
-require 'yard-solargraph'
-require 'solargraph/yard_tags'
-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 :Yardoc,           'solargraph/yardoc'
-  autoload :YardMap,          'solargraph/yard_map'
-  autoload :Pin,              'solargraph/pin'
-  autoload :DocMap,           'solargraph/doc_map'
-  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 :Equality,         'solargraph/equality'
-  autoload :Convention,       'solargraph/convention'
-  autoload :Parser,           'solargraph/parser'
-  autoload :RbsMap,           'solargraph/rbs_map'
-  autoload :GemPins,          'solargraph/gem_pins'
-  autoload :PinCache,         'solargraph/pin_cache'
-
-  dir = File.dirname(__FILE__)
-  VIEWS_PATH = File.join(dir, 'solargraph', 'views')
-
-  CHDIR_MUTEX = Mutex.new
-
-  # @param type [Symbol] Type of assert.
-  def self.asserts_on?(type)
-    if ENV['SOLARGRAPH_ASSERTS'].nil? || ENV['SOLARGRAPH_ASSERTS'].empty?
-      false
-    elsif ENV['SOLARGRAPH_ASSERTS'] == 'on'
-      true
-    else
-      logger.warn "Unrecognized SOLARGRAPH_ASSERTS value: #{ENV['SOLARGRAPH_ASSERTS']}"
-      false
-    end
-  end
-
-  # @param type [Symbol] The type of assertion to perform.
-  # @param msg [String, nil] An optional message to log
-  # @param block [Proc] A block that returns a message to log
-  # @return [void]
-  def self.assert_or_log(type, msg = nil, &block)
-    raise (msg || block.call) if asserts_on?(type) && ![:combine_with_visibility].include?(type)
-    logger.info msg, &block
-  end
-
-  # 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.
-  #
-  # @generic T
-  # @yieldreturn [generic<T>]
-  # @sg-ignore dynamic call, but both functions behave the same
-  # @return [generic<T>]
-  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
-
-# Ensure that ParserGem node processors are properly loaded to avoid conflicts
-# with Convention node processors
-require 'solargraph/parser/parser_gem/node_processors'
+# frozen_string_literal: true
+
+Encoding.default_external = 'UTF-8'
+
+require 'bundler'
+require 'set'
+require 'yard-solargraph'
+require 'solargraph/yard_tags'
+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 :Yardoc,           'solargraph/yardoc'
+  autoload :YardMap,          'solargraph/yard_map'
+  autoload :Pin,              'solargraph/pin'
+  autoload :DocMap,           'solargraph/doc_map'
+  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 :Equality,         'solargraph/equality'
+  autoload :Convention,       'solargraph/convention'
+  autoload :Parser,           'solargraph/parser'
+  autoload :RbsMap,           'solargraph/rbs_map'
+  autoload :GemPins,          'solargraph/gem_pins'
+  autoload :PinCache,         'solargraph/pin_cache'
+
+  dir = File.dirname(__FILE__)
+  VIEWS_PATH = File.join(dir, 'solargraph', 'views')
+
+  CHDIR_MUTEX = Mutex.new
+
+  def self.asserts_on?
+    # @sg-ignore Translate to something flow sensitive typing understands
+    if ENV['SOLARGRAPH_ASSERTS'].nil? || ENV['SOLARGRAPH_ASSERTS'].empty?
+      false
+    elsif ENV['SOLARGRAPH_ASSERTS'] == 'on'
+      true
+    else
+      logger.warn "Unrecognized SOLARGRAPH_ASSERTS value: #{ENV['SOLARGRAPH_ASSERTS']}"
+      false
+    end
+  end
+
+  # @param type [Symbol] The type of assertion to perform.
+  # @param msg [String, nil] An optional message to log
+  # @param block [Proc] A block that returns a message to log
+  # @return [void]
+  def self.assert_or_log(type, msg = nil, &block)
+    if asserts_on?
+      # @type [String, nil]
+      msg ||= block.call
+
+      raise "No message given for #{type.inspect}" if msg.nil?
+
+      # conditional aliases to handle compatibility corner cases
+      # @sg-ignore flow sensitive typing needs to handle 'raise if'
+      return if type == :alias_target_missing && msg.include?('highline/compatibility.rb')
+      # @sg-ignore flow sensitive typing needs to handle 'raise if'
+      return if type == :alias_target_missing && msg.include?('lib/json/add/date.rb')
+      # @todo :combine_with_visibility is not ready for prime time -
+      #  lots of disagreements found in practice that heuristics need
+      #  to be created for and/or debugging needs to resolve in pin
+      #  generation.
+      # @todo :api_map_namespace_pin_stack triggers in a badly handled
+      #   self type case - 'keeps track of self type in method
+      #   parameters in subclass' in call_spec.rb
+      return if %i[api_map_namespace_pin_stack combine_with_visibility].include?(type)
+
+      raise msg
+    end
+    logger.info msg, &block
+  end
+
+  # 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.
+  #
+  # @generic T
+  # @yieldreturn [generic<T>]
+  # @sg-ignore dynamic call, but both functions behave the same
+  # @return [generic<T>]
+  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
+
+# Ensure that ParserGem node processors are properly loaded to avoid conflicts
+# with Convention node processors
+require 'solargraph/parser/parser_gem/node_processors'

data/rbs/fills/rubygems/0/dependency.rbs

@@ -0,0 +1,193 @@
+# <!-- rdoc-file=lib/rubygems/dependency.rb -->
+# The Dependency class holds a Gem name and a Gem::Requirement.
+#
+class Gem::Dependency
+  @name: untyped
+
+  @requirement: untyped
+
+  @type: untyped
+
+  @prerelease: untyped
+
+  @version_requirements: untyped
+
+  @version_requirement: untyped
+
+  # <!-- rdoc-file=lib/rubygems/dependency.rb -->
+  # Valid dependency types.
+  #
+  TYPES: ::Array[:development | :runtime]
+
+  # <!-- rdoc-file=lib/rubygems/dependency.rb -->
+  # Dependency name or regular expression.
+  #
+  attr_accessor name: untyped
+
+  # <!-- rdoc-file=lib/rubygems/dependency.rb -->
+  # Allows you to force this dependency to be a prerelease.
+  #
+  attr_writer prerelease: untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - new(name, *requirements)
+  # -->
+  # Constructs a dependency with `name` and `requirements`. The last argument can
+  # optionally be the dependency type, which defaults to `:runtime`.
+  #
+  def initialize: (untyped name, *untyped requirements) -> void
+
+  def hash: () -> untyped
+
+  def inspect: () -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - prerelease?()
+  # -->
+  # Does this dependency require a prerelease?
+  #
+  def prerelease?: () -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - latest_version?()
+  # -->
+  # Is this dependency simply asking for the latest version of a gem?
+  #
+  def latest_version?: () -> untyped
+
+  def pretty_print: (untyped q) -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - requirement()
+  # -->
+  # What does this dependency require?
+  #
+  def requirement: () -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - requirements_list()
+  # -->
+  #
+  def requirements_list: () -> untyped
+
+  def to_s: () -> ::String
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - type()
+  # -->
+  # Dependency type.
+  #
+  def type: () -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - runtime?()
+  # -->
+  #
+  def runtime?: () -> untyped
+
+  def ==: (untyped other) -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - <=>(other)
+  # -->
+  # Dependencies are ordered by name.
+  #
+  def <=>: (untyped other) -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - =~(other)
+  # -->
+  # Uses this dependency as a pattern to compare to `other`. This dependency will
+  # match if the name matches the other's name, and other has only an equal
+  # version requirement that satisfies this dependency.
+  #
+  def =~: (untyped other) -> (nil | false | untyped)
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - ===(other)
+  # -->
+  #
+  alias === =~
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - dep.match? name          => true or false
+  #   - dep.match? name, version => true or false
+  #   - dep.match? spec          => true or false
+  # -->
+  # Does this dependency match the specification described by `name` and `version`
+  # or match `spec`?
+  #
+  # NOTE:  Unlike #matches_spec? this method does not return true when the version
+  # is a prerelease version unless this is a prerelease dependency.
+  #
+  def match?: (untyped obj, ?untyped? version, ?bool allow_prerelease) -> (false | true | untyped)
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - matches_spec?(spec)
+  # -->
+  # Does this dependency match `spec`?
+  #
+  # NOTE:  This is not a convenience method.  Unlike #match? this method returns
+  # true when `spec` is a prerelease version even if this dependency is not a
+  # prerelease dependency.
+  #
+  def matches_spec?: (untyped spec) -> (false | true | untyped)
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - merge(other)
+  # -->
+  # Merges the requirements of `other` into this dependency
+  #
+  def merge: (untyped other) -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - matching_specs(platform_only = false)
+  # -->
+  #
+  def matching_specs: (?bool platform_only) -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - specific?()
+  # -->
+  # True if the dependency will not always match the latest version.
+  #
+  def specific?: () -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - to_specs()
+  # -->
+  #
+  def to_specs: () -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - to_spec()
+  # -->
+  #
+  def to_spec: () -> untyped
+
+  # <!--
+  #   rdoc-file=lib/rubygems/dependency.rb
+  #   - identity()
+  # -->
+  #
+  def identity: () -> (:complete | :abs_latest | :latest | :released)
+
+  def encode_with: (untyped coder) -> untyped
+end

data/rbs/fills/tuple/tuple.rbs

@@ -144,6 +144,34 @@ module Solargraph
                | [T] (8 index) { (int index) -> T } -> (I | T)
                | [T] (9 index) { (int index) -> T } -> (J | T)
                | [T] (int index) { (int index) -> T } -> (A | B | C | D | E | F | G | H | I | J | T)
+
+      # <!--
+      #   rdoc-file=array.rb
+      #   - first -> object or nil
+      #   - first(count) -> new_array
+      # -->
+      # Returns elements from `self`, or `nil`; does not modify `self`.
+      #
+      # With no argument given, returns the first element (if available):
+      #
+      #     a = [:foo, 'bar', 2]
+      #     a.first # => :foo
+      #     a # => [:foo, "bar", 2]
+      #
+      # If `self` is empty, returns `nil`.
+      #
+      #     [].first # => nil
+      #
+      # With a non-negative integer argument `count` given, returns the first `count`
+      # elements (as available) in a new array:
+      #
+      #     a.first(0)  # => []
+      #     a.first(2)  # => [:foo, "bar"]
+      #     a.first(50) # => [:foo, "bar", 2]
+      #
+      # Related: see [Methods for Querying](rdoc-ref:Array@Methods+for+Querying).
+      #
+      def first: %a{implicitly-returns-nil} () -> A
     end
   end
 end

data/rbs/shims/ast/0/node.rbs

@@ -0,0 +1,5 @@
+module ::AST
+  class Node
+     def children: () -> Array[self | Integer | String | Symbol | nil]
+  end
+end

data/rbs/shims/diff-lcs/1.5/diff-lcs.rbs

@@ -0,0 +1,11 @@
+module Diff
+end
+
+module Diff::LCS
+  def self.LCS: (Array[String], Array[String]) -> Array[String]
+              | (String, String) -> Array[String]
+  def self.diff: (Array[String], Array[String]) -> Array[Array[String]]
+              | (String, String) -> Array[Array[Diff::LCS::Change]]
+
+  def self.patch!: (Array[String], Array[String]) -> String
+end