solargraph 0.46.0 → 0.54.5

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017-2019 by Fred Snyder for Castwide Technologies
+Copyright (c) 2017-2023 by Fred Snyder for Castwide Technologies
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,128 +1,131 @@
-# Solargraph
-
-[![RSpec](https://github.com/castwide/solargraph/actions/workflows/rspec.yml/badge.svg)](https://github.com/castwide/solargraph/actions/workflows/rspec.yml)
-
-## A Ruby Language Server
-
-Solargraph provides a comprehensive suite of tools for Ruby programming: intellisense, diagnostics, inline documentation, and type checking.
-
-## Online Demo
-
-A web-based demonstration of Solargraph's autocomplete is available at https://solargraph.org/demo.
-
-## Installation
-
-Install the gem from the command line:
-
-    gem install solargraph
-
-Or add it to your Gemfile:
-
-    gem 'solargraph', group: :development
-
-## Using Solargraph
-
-Plug-ins and extensions are available for the following editors:
-
-* **Visual Studio Code**
-    * Extension: https://marketplace.visualstudio.com/items?itemName=castwide.solargraph
-    * GitHub: https://github.com/castwide/vscode-solargraph
-
-* **Atom**
-    * Package: https://atom.io/packages/ruby-solargraph
-    * GitHub: https://github.com/castwide/atom-solargraph
-
-* **Vim**
-    * GitHub: `LanguageClient-neovim`, https://github.com/autozimu/LanguageClient-neovim
-    * GitHub: `coc`, https://github.com/neoclide/coc-solargraph
-    * GitHub: `Vim-EasyComplete`, https://github.com/jayli/vim-easycomplete
-
-* **Emacs**
-    * GitHub: `eglot.el`, https://github.com/joaotavora/eglot
-    * GitHub: `lsp-mode.el`, https://github.com/emacs-lsp/lsp-mode
-
-* **Eclipse**
-    * Plugin: https://marketplace.eclipse.org/content/ruby-solargraph
-    * GitHub: https://github.com/PyvesB/eclipse-solargraph
-
-### Configuration
-
-Solargraph's behavior can be controlled via optional [configuration](https://solargraph.org/guides/configuration) files. The highest priority file is a `.solargraph.yml` file at the root of the project. If not present, any global configuration at `~/.config/solargraph/config.yml` will apply. The path to the global configuration can be overridden with the `SOLARGRAPH_GLOBAL_CONFIG` environment variable.
-
-### Gem Support
-
-Solargraph is capable of providing code completion and documentation for gems that have YARD documentation. You can make sure your gems are documented by running `yard gems` from the command line. (YARD is included as one of Solargraph's gem dependencies. The first time you run it might take a while if you have a lot of gems installed).
-
-When editing code, a `require` call that references a gem will pull the documentation into the code maps and include the gem's API in code completion and intellisense.
-
-If your project automatically requires bundled gems (e.g., `require 'bundler/require'`), Solargraph will add all of the Gemfile's default dependencies to the map.
-
-### Type Checking
-
-As of version 0.33.0, Solargraph includes a [type checker](https://github.com/castwide/solargraph/issues/192) that uses a combination of YARD tags and code analysis to report missing type definitions. In strict mode, it performs type inference to determine whether the tags match the types it detects from code.
-
-### Updating Core Documentation
-
-The Solargraph gem ships with documentation for Ruby 2.2.2. You can download documentation for other Ruby versions from the command line.
-
-    $ solargraph list-cores      # List the installed documentation versions
-    $ solargraph available-cores # List the versions available for download
-    $ solargraph download-core   # Install the best match for your Ruby version
-    $ solargraph clear           # Reset the documentation cache
-
-### The Documentation Cache
-
-Solargraph uses a cache directory to store documentation for the Ruby core and customized documentation for certain gems. The default location is `~/.solargraph/cache`, e.g., `/home/<username>/.solargraph/cache` on Linux or `C:\Users\<username>\.solargraph` on Windows.
-
-You can change the location of the cache directory with the `SOLARGRAPH_CACHE` environment variable. This can be useful if you want the cache to comply with the XDG Base Directory Specification.
-
-### Solargraph and Bundler
-
-If you're using the language server with a project that uses Bundler, the most comprehensive way to use your bundled gems is to bundle Solargraph.
-
-In the Gemfile:
-
-    gem 'solargraph', group: :development
-
-Run `bundle install` and use `bundle exec yard gems` to generate the documentation. This process documents cached or vendored gems, or even gems that are installed from a local path.
-
-In order to make sure you're using the correct dependencies, you can start the language server with Bundler. In VS Code, there's a `solargraph.useBundler` option. Other clients will vary, but the command you probably want to run is `bundle exec solargraph socket` or `bundle exec solargraph stdio`.
-
-### Rubocop Version
-
-If you have multiple versions of [`rubocop`](https://rubygems.org/gems/rubocop) installed and you would like to choose a version other than the latest to use, this specific version can be configured.
-
-In `.solargraph.yml`:
-
-```yaml
----
-reporters:
-- rubocop:version=0.61.0  # diagnostics
-formatter:
-  rubocop:
-    version: 0.61.0       # formatting
-```
-
-### Integrating Other Editors
-
-The [language server protocol](https://microsoft.github.io/language-server-protocol/specification) is the recommended way for integrating Solargraph into editors and IDEs. Clients can connect using either stdio or TCP. Language client developers should refer to [https://solargraph.org/guides/language-server](https://solargraph.org/guides/language-server).
-
-### More Information
-
-See [https://solargraph.org/guides](https://solargraph.org/guides) for more tips and tutorials about Solargraph.
-
-## Contributing to Solargraph
-
-### Bug Reports and Feature Requests
-
-[GitHub Issues](https://github.com/castwide/solargraph/issues) are the best place to ask questions, report problems, and suggest improvements.
-
-### Development
-
-Code contributions are always appreciated. Feel free to fork the repo and submit pull requests. Check for open issues that could use help. Start new issues to discuss changes that have a major impact on the code or require large time commitments.
-
-### Sponsorship and Donation
-
-Use Patreon to support ongoing development of Solargraph at [https://www.patreon.com/castwide](https://www.patreon.com/castwide).
-
-You can also make one-time donations via PayPal at [https://www.paypal.me/castwide](https://www.paypal.me/castwide).
+# Solargraph
+
+[![RSpec](https://github.com/castwide/solargraph/actions/workflows/rspec.yml/badge.svg)](https://github.com/castwide/solargraph/actions/workflows/rspec.yml)
+
+## A Ruby Language Server
+
+Solargraph provides a comprehensive suite of tools for Ruby programming: intellisense, diagnostics, inline documentation, and type checking.
+
+## Online Demo
+
+A web-based demonstration of Solargraph's autocomplete is available at https://solargraph.org/demo.
+
+## Installation
+
+Install the gem from the command line:
+
+    gem install solargraph
+
+Or add it to your Gemfile:
+
+    gem 'solargraph', group: :development
+
+## Using Solargraph
+
+Plug-ins and extensions are available for the following editors:
+
+* **Visual Studio Code**
+    * Extension: https://marketplace.visualstudio.com/items?itemName=castwide.solargraph
+    * GitHub: https://github.com/castwide/vscode-solargraph
+
+* **Sublime Text**
+    * Extension: https://packagecontrol.io/packages/LSP
+    * GitHub: https://github.com/sublimelsp/LSP
+    * Instructions: https://lsp.sublimetext.io/language_servers/#solargraph
+
+* **Vim**
+    * Github: `nvim-lspconfig`, https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#solargraph
+    * GitHub: `LanguageClient-neovim`, https://github.com/autozimu/LanguageClient-neovim
+    * GitHub: `coc`, https://github.com/neoclide/coc-solargraph
+    * GitHub: `Vim-EasyComplete`, https://github.com/jayli/vim-easycomplete
+
+* **Emacs**
+    * GitHub: `eglot.el`, https://github.com/joaotavora/eglot
+    * GitHub: `lsp-mode.el`, https://github.com/emacs-lsp/lsp-mode
+
+* **Eclipse**
+    * Plugin: https://marketplace.eclipse.org/content/ruby-solargraph
+    * GitHub: https://github.com/PyvesB/eclipse-solargraph
+
+### Configuration
+
+Solargraph's behavior can be controlled via optional [configuration](https://solargraph.org/guides/configuration) files. The highest priority file is a `.solargraph.yml` file at the root of the project. If not present, any global configuration at `~/.config/solargraph/config.yml` will apply. The path to the global configuration can be overridden with the `SOLARGRAPH_GLOBAL_CONFIG` environment variable.
+
+### Plugins
+
+Solargraph supports [plugins](https://solargraph.org/guides/plugins) that implements their own Solargraph features, such as diagnostics reporters and conventions to provide LSP features and type-checking, e.g. for frameworks which use metaprogramming and/or DSLs.
+
+For better Rails support, please consider using [solargraph-rails](https://github.com/iftheshoefritz/solargraph-rails/)
+
+The RSpec framework is supported via [solargraph-rspec](https://github.com/lekemula/solargraph-rspec/)
+
+### Gem Support
+
+**Note: Before version 0.53.0, it was recommended to run `yard gems` periodically or automate it with `yard config` to ensure that Solargraph had access to gem documentation. These steps are no longer necessary. Solargraph maintains its own gem documentation cache independent of the yardocs in your gem installations.**
+
+Solargraph automatically generates code maps from installed gems. You can also manage your cached gem documentation with the `solargraph gems` command.
+
+When editing code, a `require` call that references a gem will pull the documentation into the code maps and include the gem's API in code completion and intellisense.
+
+If your project automatically requires bundled gems (e.g., `require 'bundler/require'`), Solargraph will add all of the Gemfile's default dependencies to the map.
+
+### Type Checking
+
+As of version 0.33.0, Solargraph includes a [type checker](https://github.com/castwide/solargraph/issues/192) that uses a combination of YARD tags and code analysis to report missing type definitions. In strict mode, it performs type inference to determine whether the tags match the types it detects from code.
+
+### The Documentation Cache
+
+Solargraph uses a cache directory to store documentation for the Ruby core and gems. The default location is `~/.cache/solargraph`, e.g., `/home/<username>/.cache/solargraph` on Linux or `C:\Users\<username>\.cache\solargraph` on Windows.
+
+You can change the location of the cache directory with the `SOLARGRAPH_CACHE` environment variable.
+
+### Solargraph and Bundler
+
+If you're using the language server with a project that uses Bundler, the most comprehensive way to use your bundled gems is to bundle Solargraph.
+
+In the Gemfile:
+
+    gem 'solargraph', group: :development
+
+Run `bundle install` and optionally use `bundle exec solargraph gems` to generate the documentation. This process documents cached or vendored gems, or even gems that are installed from a local path.
+
+In order to make sure you're using the correct dependencies, you can start the language server with Bundler. In VS Code, there's a `solargraph.useBundler` option. Other clients will vary, but the command you probably want to run is `bundle exec solargraph socket` or `bundle exec solargraph stdio`.
+
+### Rubocop Version
+
+If you have multiple versions of [`rubocop`](https://rubygems.org/gems/rubocop) installed and you would like to choose a version other than the latest to use, this specific version can be configured.
+
+In `.solargraph.yml`:
+
+```yaml
+---
+reporters:
+- rubocop:version=0.61.0  # diagnostics
+formatter:
+  rubocop:
+    version: 0.61.0       # formatting
+```
+
+### Integrating Other Editors
+
+The [language server protocol](https://microsoft.github.io/language-server-protocol/specification) is the recommended way for integrating Solargraph into editors and IDEs. Clients can connect using either stdio or TCP. Language client developers should refer to [https://solargraph.org/guides/language-server](https://solargraph.org/guides/language-server).
+
+### More Information
+
+See [https://solargraph.org/guides](https://solargraph.org/guides) for more tips and tutorials about Solargraph.
+
+## Contributing to Solargraph
+
+### Bug Reports and Feature Requests
+
+[GitHub Issues](https://github.com/castwide/solargraph/issues) are the best place to ask questions, report problems, and suggest improvements.
+
+### Development
+
+Code contributions are always appreciated. Feel free to fork the repo and submit pull requests. Check for open issues that could use help. Start new issues to discuss changes that have a major impact on the code or require large time commitments.
+
+### Sponsorship and Donation
+
+Use Patreon to support ongoing development of Solargraph at [https://www.patreon.com/castwide](https://www.patreon.com/castwide).
+
+You can also make one-time donations via PayPal at [https://www.paypal.me/castwide](https://www.paypal.me/castwide).

data/SPONSORS.md

@@ -1,18 +1,10 @@
-# Sponsors
-
-Solargraph is developed and maintained by [Castwide Technologies](https://castwide.com).
-
-The following people and organizations provide funding or other resources. [Become a sponsor](https://patreon.com/castwide)
-
-## Linked Sponsors
-
-- **[Calyptix Security](https://www.calyptix.com/)**
-
-## Named Sponsors
-
-- Tom de Grunt
-- Akira Yamada
-- Erlend Finvåg
-- Matt Massicotte
-- Hasan Kumar
-- Oscar Rivas
+# Sponsors
+
+Solargraph is developed and maintained by [Castwide Technologies](https://castwide.com).
+
+The following people and organizations provide funding or other resources. [Become a sponsor](https://patreon.com/castwide)
+
+## Named Sponsors
+
+- Juan Carlos
+- Vince Broz

data/lib/solargraph/api_map/cache.rb

@@ -1,70 +1,109 @@
-# frozen_string_literal: true
-
-module Solargraph
-  class ApiMap
-    class Cache
-      def initialize
-        @methods = {}
-        @constants = {}
-        @qualified_namespaces = {}
-        @receiver_definitions = {}
-      end
-
-      # @return [Array<Pin::Method>]
-      def get_methods fqns, scope, visibility, deep
-        @methods[[fqns, scope, visibility.sort, deep]]
-      end
-
-      def set_methods fqns, scope, visibility, deep, value
-        @methods[[fqns, scope, visibility.sort, deep]] = value
-      end
-
-      # @return [Array<Pin::Base>]
-      def get_constants namespace, context
-        @constants[[namespace, context]]
-      end
-
-      def set_constants namespace, context, value
-        @constants[[namespace, context]] = value
-      end
-
-      # @return [String]
-      def get_qualified_namespace name, context
-        @qualified_namespaces[[name, context]]
-      end
-
-      def set_qualified_namespace name, context, value
-        @qualified_namespaces[[name, context]] = value
-      end
-
-      def receiver_defined? path
-        @receiver_definitions.key? path
-      end
-
-      # @return [Pin::Method]
-      def get_receiver_definition path
-        @receiver_definitions[path]
-      end
-
-      def set_receiver_definition path, pin
-        @receiver_definitions[path] = pin
-      end
-
-      # @return [void]
-      def clear
-        @methods.clear
-        @constants.clear
-        @qualified_namespaces.clear
-        @receiver_definitions.clear
-      end
-
-      # @return [Boolean]
-      def empty?
-        @methods.empty? &&
-          @constants.empty? &&
-          @qualified_namespaces.empty? &&
-          @receiver_definitions.empty?
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Solargraph
+  class ApiMap
+    class Cache
+      def initialize
+        # @type [Hash{Array => Array<Pin::Method>}]
+        @methods = {}
+        # @type [Hash{(String, Array<String>) => Array<Pin::Base>}]
+        @constants = {}
+        # @type [Hash{String => String}]
+        @qualified_namespaces = {}
+        # @type [Hash{String => Pin::Method}]
+        @receiver_definitions = {}
+        # @type [Hash{String => SourceMap::Clip}]
+        @clips = {}
+      end
+
+      def to_s
+        self.class.to_s
+      end
+
+      # avoid enormous dump
+      def inspect
+        to_s
+      end
+
+      # @param fqns [String]
+      # @param scope [Symbol]
+      # @param visibility [Array<Symbol>]
+      # @param deep [Boolean]
+      # @return [Array<Pin::Method>]
+      def get_methods fqns, scope, visibility, deep
+        @methods["#{fqns}|#{scope}|#{visibility}|#{deep}"]
+      end
+
+      # @param fqns [String]
+      # @param scope [Symbol]
+      # @param visibility [Array<Symbol>]
+      # @param deep [Boolean]
+      # @param value [Array<Pin::Method>]
+      # @return [void]
+      def set_methods fqns, scope, visibility, deep, value
+        @methods["#{fqns}|#{scope}|#{visibility}|#{deep}"] = value
+      end
+
+      # @param namespace [String]
+      # @param contexts [Array<String>]
+      # @return [Array<Pin::Base>]
+      def get_constants namespace, contexts
+        @constants["#{namespace}|#{contexts}"]
+      end
+
+      # @param namespace [String]
+      # @param contexts [Array<String>]
+      # @param value [Array<Pin::Base>]
+      # @return [void]
+      def set_constants namespace, contexts, value
+        @constants["#{namespace}|#{contexts}"] = value
+      end
+
+      # @param name [String]
+      # @param context [String]
+      # @return [String]
+      def get_qualified_namespace name, context
+        @qualified_namespaces["#{name}|#{context}"]
+      end
+
+      # @param name [String]
+      # @param context [String]
+      # @param value [String]
+      # @return [void]
+      def set_qualified_namespace name, context, value
+        @qualified_namespaces["#{name}|#{context}"] = value
+      end
+
+      # @param path [String]
+      # @return [Pin::Method]
+      def get_receiver_definition path
+        @receiver_definitions[path]
+      end
+
+      # @param path [String]
+      # @param pin [Pin::Method]
+      # @return [void]
+      def set_receiver_definition path, pin
+        @receiver_definitions[path] = pin
+      end
+
+      # @return [void]
+      def clear
+        return if empty?
+
+        all_caches.each(&:clear)
+      end
+
+      # @return [Boolean]
+      def empty?
+        all_caches.all?(&:empty?)
+      end
+
+      private
+
+      def all_caches
+        [@methods, @constants, @qualified_namespaces, @receiver_definitions, @clips]
+      end
+    end
+  end
+end

data/lib/solargraph/api_map/index.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Solargraph
+  class ApiMap
+    class Index
+      # @param pins [Array<Pin::Base>]
+      def initialize pins = []
+        catalog pins
+      end
+
+      # @return [Array<Pin::Base>]
+      def pins
+        @pins ||= []
+      end
+
+      # @return [Hash{String => Array<Pin::Namespace>}]
+      def namespace_hash
+        @namespace_hash ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @return [Hash{String => Array<Pin::Base>}]
+      def pin_class_hash
+        @pin_class_hash ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @return [Hash{String => Array<Pin::Base>}]
+      def path_pin_hash
+        @path_pin_hash ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @generic T
+      # @param klass [Class<generic<T>>]
+      # @return [Set<generic<T>>]
+      def pins_by_class klass
+        # @type [Set<Solargraph::Pin::Base>]
+        s = Set.new
+        @pin_select_cache[klass] ||= pin_class_hash.each_with_object(s) { |(key, o), n| n.merge(o) if key <= klass }
+      end
+
+      # @return [Hash{String => Array<Pin::Reference::Include>}]
+      def include_references
+        @include_references ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @return [Hash{String => Array<Pin::Reference::Extend>}]
+      def extend_references
+        @extend_references ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @return [Hash{String => Array<Pin::Reference::Prepend>}]
+      def prepend_references
+        @prepend_references ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @return [Hash{String => Array<Pin::Reference::Superclass>}]
+      def superclass_references
+        @superclass_references ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # @param pins [Array<Pin::Base>]
+      def merge pins
+        deep_clone.catalog pins
+      end
+
+      protected
+
+      attr_writer :pins, :pin_select_cache, :namespace_hash, :pin_class_hash, :path_pin_hash, :include_references,
+                  :extend_references, :prepend_references, :superclass_references
+
+      def deep_clone
+        Index.allocate.tap do |copy|
+          copy.pin_select_cache = {}
+          copy.pins = pins.clone
+          %i[
+            namespace_hash pin_class_hash path_pin_hash include_references extend_references prepend_references
+            superclass_references
+          ].each do |sym|
+            copy.send("#{sym}=", send(sym).clone)
+            copy.send(sym)&.transform_values!(&:clone)
+          end
+        end
+      end
+
+      # @param new_pins [Array<Pin::Base>]
+      def catalog new_pins
+        @pin_select_cache = {}
+        pins.concat new_pins
+        set = new_pins.to_set
+        set.classify(&:class)
+           .map { |k, v| pin_class_hash[k].concat v.to_a }
+        set.classify(&:namespace)
+           .map { |k, v| namespace_hash[k].concat v.to_a }
+        set.classify(&:path)
+           .map { |k, v| path_pin_hash[k].concat v.to_a }
+        @namespaces = path_pin_hash.keys.compact.to_set
+        map_references Pin::Reference::Include, include_references
+        map_references Pin::Reference::Prepend, prepend_references
+        map_references Pin::Reference::Extend, extend_references
+        map_references Pin::Reference::Superclass, superclass_references
+        map_overrides
+        self
+      end
+
+      # @param klass [Class<Pin::Reference>]
+      # @param hash [Hash{String => Array<Pin::Reference>}]
+      # @return [void]
+      def map_references klass, hash
+        pins_by_class(klass).each do |pin|
+          store_parametric_reference(hash, pin)
+        end
+      end
+
+      # Add references to a map
+      #
+      # @param hash [Hash{String => Array<Pin::Reference>}]
+      # @param reference_pin [Pin::Reference]
+      #
+      # @return [void]
+      def store_parametric_reference(hash, reference_pin)
+        referenced_ns = reference_pin.name
+        referenced_tag_params = reference_pin.generic_values
+        referenced_tag = referenced_ns +
+                         if referenced_tag_params && referenced_tag_params.length > 0
+                           "<" + referenced_tag_params.join(', ') + ">"
+                         else
+                           ''
+                         end
+        referencing_ns = reference_pin.namespace
+        hash[referencing_ns].push referenced_tag
+      end
+
+      # @return [void]
+      def map_overrides
+        pins_by_class(Pin::Reference::Override).each do |ovr|
+          pin = path_pin_hash[ovr.name].first
+          next if pin.nil?
+          new_pin = if pin.path.end_with?('#initialize')
+            path_pin_hash[pin.path.sub(/#initialize/, '.new')].first
+          end
+          (ovr.tags.map(&:tag_name) + ovr.delete).uniq.each do |tag|
+            pin.docstring.delete_tags tag
+            new_pin.docstring.delete_tags tag if new_pin
+          end
+          ovr.tags.each do |tag|
+            pin.docstring.add_tag(tag)
+            redefine_return_type pin, tag
+            if new_pin
+              new_pin.docstring.add_tag(tag)
+              redefine_return_type new_pin, tag
+            end
+          end
+        end
+      end
+
+      # @param pin [Pin::Method]
+      # @param tag [YARD::Tags::Tag]
+      # @return [void]
+      def redefine_return_type pin, tag
+        return unless pin && tag.tag_name == 'return'
+        pin.instance_variable_set(:@return_type, ComplexType.try_parse(tag.type))
+        pin.signatures.each do |sig|
+          sig.instance_variable_set(:@return_type, ComplexType.try_parse(tag.type))
+        end
+      end
+    end
+  end
+end