solargraph 0.32.1 → 0.32.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51463c0c8d89512dafa3f4ff9dc36f1b17247f3624ac11ea434af3022dbdf9ad
-  data.tar.gz: eeab854453e908f0106d1a15241f2261bb286e7f8353a0490027d822995025a3
+  metadata.gz: 80e5d1c7f259f52bafd116d70e972be0409e282539c568f19ecb4114d7b88f36
+  data.tar.gz: ae52fc598ab045b3cae66f84fcc5157f69d3d51cbd283f396760fab35f22ec4f
 SHA512:
-  metadata.gz: e5ce65116ddc68b6a485b0d02be1b5fb8c2690b45bc2d02c8e58c548953d8382f59e516860ac2427655770cfb71d62ff290ff6f4c4c43bf84c3e83e98d534e81
-  data.tar.gz: 3efd573fa3d457eafe950f6860cb50517b922ce064cb0d334ddbcabc7647d6fd9f46ff76fa7e88008fb7d54e93a4c6ebc5ad15b571c6fddcc2d6fcd5f563fcf4
+  metadata.gz: 1473f5115ab0b6890318053325754af90eb37b949dab4397efbd71db929d1a0272d6e4b9429a21cb127aaa6c4268ee0112837be9fc794fd4581cc9f3729face2
+  data.tar.gz: 23c8737bafb64c0acf80db643d0df6e990cc73f1ef3ece715507170c3dbc1449118cb923642f6ef7da73c426c448710eda58dcf3e2167ed8b0f986db04caa56e

data/.gitignore

@@ -0,0 +1,9 @@
+Gemfile.lock
+
+.idea
+.vscode
+.yardoc
+.solargraph.yml
+doc
+coverage
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,6 @@
+Layout/EndOfLine:
+  EnforcedStyle: lf
+Style/MethodDefParentheses:
+  Enabled: false
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,25 @@
+language: ruby
+rvm:
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
+  - 2.5.1
+  - 2.5.3
+  - 2.6.0
+  - 2.6.1
+  - jruby-9.1.16.0
+  - jruby-9.2
+matrix:
+  include:
+    - rvm: 2.4
+      os: osx
+# Update RubyGems and Bundler due to error with Bundler 1.16.1 and RubyGems 2.7.3
+# See https://github.com/travis-ci/travis-ci/issues/8978
+before_install:
+- ruby ./travis-bundler.rb
+- bundle install
+before_script: bundle exec yard gems
+script: bundle exec rspec
+# cache:
+#   - bundler

data/EXAMPLES.md

@@ -0,0 +1,76 @@
+# Code Examples
+
+This document provides simple examples of how to use the Solargraph library. The examples are intended as a starting point for developers who want to modify or extend the library, or integrate its tools into other software.
+
+Language client implementors who want to connect to Solargraph language servers should refer to [LANGUAGE_SERVER.md](LANGUAGE_SERVER.md).
+
+## Querying Ruby Core Methods
+
+```Ruby
+api_map = Solargraph::ApiMap.new
+pins = api_map.get_methods('String') # Get public instance methods of the String class
+```
+
+## Adding a File to an ApiMap
+
+```Ruby
+api_map = Solargraph::ApiMap.new
+source = Solargraph::Source.load_string('class MyClass; end', 'my_class.rb')
+api_map.map source # Add the source to the map
+pins = api_map.get_constants('') # The constants in the global namespace will include `MyClass`
+```
+
+## Adding a Workspace to an ApiMap
+
+```Ruby
+api_map = Solargraph::ApiMap.load('/path/to/workspace')
+pins = api_map.get_constants('') # Results will include constants defined in the project's code
+```
+
+## Querying Definitions from a Location in Source Code
+
+```Ruby
+api_map = Solargraph::ApiMap.new
+source = Solargraph::Source.load_string("var = 'a string'; puts var", 'example.rb')
+api_map.virtualize source
+clip = api_map.clip_at('example.rb', Solargraph::Position.new(0, 23))
+pins = clip.define # `var` is recognized as a local variable containing a String
+```
+
+## Querying Completion Suggestions
+```Ruby
+api_map = Solargraph::ApiMap.new
+source = Solargraph::Source.load_string("String.", 'example.rb')
+api_map.map source
+clip = api_map.clip_at('example.rb', Solargraph::Position.new(0, 7))
+completion = clip.complete # Suggestions will include String class methods
+```
+
+## Adding a Message to the Language Server Protocol
+
+```Ruby
+class MyMessage < Solargraph::LanguageServer::Message::Base
+  def process
+    STDERR.puts "Server received MyMessage with the following parameters: #{params}"
+  end
+end
+
+Solargraph::LanguageServer::Message.register '$/myMessage', MyMessage
+```
+
+## Adding a Diagnostics Reporter to the Language Server
+
+```Ruby
+class MyReporter < Solargraph::Diagnostics::Base
+  def diagnose source, api_map
+    # Return an array of hash objects that conform to the LSP's Diagnostic specification
+    []
+  end
+end
+
+Solargraph::Diagnostics.register 'my_reporter', MyReporter
+```
+
+## More Examples
+
+Developers are encouraged to refer to the specs for more examples of how to use Solargraph.

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec name: 'solargraph'

data/LANGUAGE_SERVER.md

@@ -0,0 +1,51 @@
+# Language Server Protocol
+
+Solargraph supports the language server protocol as of gem version 0.18.0. The VSCode extension uses LSP as of extension version 0.14.0.
+
+## Using the Language Server
+
+Run `solargraph stdio` to use the language server via stdio.
+
+Run `solargraph socket` to use the language server via TCP socket. The default port is 7658.
+
+## Supported Capabilities
+
+* Hover
+* Completion
+* Signature help
+* Definition
+* Document symbols
+* Workspace symbols
+* Rename symbols
+* References
+* Formatting
+* Diagnostics (linting)
+
+## Work in Progress
+
+* On type formatting
+
+## Custom Features
+
+Solargraph's language server extends the protocol with additional methods for inline document pages.
+
+## Linting and Formatting
+
+Solargraph uses RuboCop for linting and formatting.
+
+## Diagnostics Reporters
+
+A .solargraph.yml file can be used to select which diagnostics reporters Solargraph should use. Example:
+
+```
+reporters:
+- rubocop
+- require_not_found
+```
+
+`rubocop` enables RuboCop linting. Its rules can be configured in a .rubocop.yml file.
+
+`require_not_found` highlights `require` calls where Solargraph could not resolve a required path. Note that this error does not
+necessarily mean that the path is incorrect; only that Solargraph was unable to recognize it.
+
+Run `solargraph reporters` for a list of available reporters.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017-2019 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/OVERVIEW.md

@@ -0,0 +1,37 @@
+# An Overview of Solargraph
+
+The Solargraph library consists of two major groups of components: the data providers and the language servers. The data providers manage the maps of information about a program. The language servers are the concrete implementations of transports and messages that enable the language server protocol.
+
+## Data Providers
+
+**ApiMap** (`Solargraph::ApiMap`): The component that provides information about a program based on its Workspace, external gems, and the Ruby core.
+
+**Workspace** (`Solargraph::Workspace`): A collection of Sources that comprise a project. Workspaces have configurations that define which files to include in maps and other project-related options. Users can configure the Workspace through a .solargraph.yml file in a project's root directory.
+
+**Source** (`Solargraph::Source`): Data about a single Ruby file. Sources parse Ruby code into an AST and handle incremental updates.
+
+**SourceMap** (`Solargraph::SourceMap`): A Source with generated pins for use in ApiMaps.
+
+**Pins** (`Solargraph::Pin`): Information about classes, modules, methods, variables, etc. Pins for different types of components extend `Pin::Base`. Most ApiMap queries return results as an array of Pins.
+
+**Cursor** (`Solargraph::Source::Cursor`): Information about a specific location in a Source.
+
+**Clip** (`Solargraph::SourceMap::Clip`): A Cursor bundled with an ApiMap to provide definitions, completions, and other information.
+
+**YardMap** (`Solargraph::YardMap`): A collection of YARD documents. ApiMaps use YardMaps to gather data from external gems and the Ruby core.
+
+**Library** (`Solargraph::Library`): The component that synchronizes a Workspace with an ApiMap. Libraries help ensure that the ApiMap gets updated when a file in the Workspace changes.
+
+## Language Servers
+
+**Host** (`Solargraph::LanguageServer::Host`): The component responsible for processing messages between the server and the client. Hosts maintain a project's Library and provide thread-safe methods for asynchronous operations.
+
+**Messages** (`Solargraph::LanguageServer::Message`): Implementations of LSP methods and notifications. Each message implementation extends `Message::Base`.
+
+**Transports** (`Solargraph::LanguageServer::Transport`): Server implementations for various protocols. The two transports that are currently supported are socket and stdio. The `Transport::DataReader` class provides a common interface for processing incoming JSON-RPC messages.
+
+## More Information
+
+The [EXAMPLES.md](EXAMPLES.md) document provides simple examples of how to use, extend, and modify the Solargraph library.
+
+Refer to [LANGUAGE_SERVER.md](LANGUAGE_SERVER.md) for information about connecting language clients to Solargraph language servers.

data/README.md

@@ -0,0 +1,106 @@
+# Solargraph
+
+IDE tools for the Ruby language.
+
+Solargraph is a set of tools to integrate Ruby code completion and inline documentation into IDEs.
+
+## Online Demo
+
+A web-based demonstration of Solargraph is available at http://solargraph.org/demo.
+
+## Installation
+
+Solargraph is available as a Ruby gem:
+
+    gem install solargraph
+
+## 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: https://github.com/autozimu/LanguageClient-neovim
+
+* **Emacs**
+    * GitHub: https://github.com/guskovd/emacs-solargraph
+
+* **Eclipse**
+    * Plugin: https://marketplace.eclipse.org/content/ruby-solargraph
+    * GitHub: https://github.com/PyvesB/eclipse-solargraph
+
+### 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. (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.
+
+### More Information
+
+See [http://solargraph.org/tips](http://solargraph.org/tips) for more tips on using Solargraph with an editor.
+
+## How It Works
+
+Solargraph uses [parser](https://github.com/whitequark/parser) for code analysis and [YARD](https://github.com/lsegal/yard) for API documentation.
+
+## Using the `solargraph` Executable
+
+The gem includes an executable that provides access to the library's features. For code completion, IDEs will typically integrate using `solargraph stdio` or `solargraph socket`.
+
+### Language Server Protocol
+
+The language server protocol is the recommended way for integrating Solargraph into editors and IDEs. Clients can connect using either stdio or TCP.
+See [LANGUAGE_SERVER.md](LANGUAGE_SERVER.md) for more information.
+
+The Solargraph gem ships with documentation for Ruby 2.2.2. As of gem version 0.15.0, there's an option to download additional 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-cores     # Clear the documentation cache
+
+## Solargraph and Bundler
+
+If you're using the Solargraph 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 access the gems in your project, you'll need to 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`.
+
+## Runtime Suggestions (EXPERIMENTAL)
+
+As of gem version 0.15.0, Solargraph includes experimental support for plugins.
+
+The Runtime plugin enhances code completion by querying namespaces for method names in a subprocess. If it finds any undocumented or "magic" methods, they get added to the suggestions.
+
+This feature is currently disabled by default. If you'd like to try it, you can enable it by setting the `plugins` section in your project's .solargraph.yml file:
+
+    plugins:
+    - runtime
+
+## Contributing to Solargraph
+
+### Bug Reports and Feature Requests
+
+GitHub 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/Rakefile

@@ -0,0 +1,14 @@
+require 'rake'
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+end
+
+desc "Open a Pry session preloaded with this library"
+task :console do
+  sh "pry -I lib -r solargraph.rb"
+end

data/SERVER.md

@@ -0,0 +1,95 @@
+# Solargraph Server Documentation
+
+**NOTE: The legacy web server is deprecated and no longer available as of gem version 0.21.0. This document is archived for the benefit of extensions and plugins that still use it. Client implementors should use the [language server protocol](LANGUAGE_SERVER.md) instead.**
+
+## Running the Server
+
+Use the following command to start the server:
+
+```
+solargraph server
+```
+
+The command accepts an optional `--port` setting. The default port is 7657. If you set the port to 0, the server will select the first available port.
+
+## API Endpoints
+
+### POST /suggest
+
+Get an array of suggestions to complete the code at the specified line and column of a file.
+
+**Parameters:**
+- `text` - the contents of the file
+- `filename` - the absolute path to the file
+- `line` - the zero-based line position of the cursor
+- `column` - the zero-based column position of the cursor
+- `workspace` - (optional) the root directory of the project
+- `with_all` - (optional) request verbose suggestions
+
+If `with_all` is set to 1, the suggestions will include documentation. The default is 0.
+
+### POST /define
+
+Get an array of suggestions that point to definitions for the symbol at the
+specified location in the file. This method supports classes, modules, method
+definitions, and variable assignments. The suggestions have a `location`
+property that identifies the definition's file, line, and column.
+
+**Parameters:**
+- `text` - the contents of the file
+- `filename` - the absolute path to the file
+- `line` - the zero-based line position of the cursor
+- `column` - the zero-based column position of the cursor
+- `workspace` - (optional) the root directory of the project
+
+### POST /resolve
+
+**Parameters:**
+- `filename` - the absolute path to the file
+- `path` - the code path to find (e.g., `String#upcase`)
+- `workspace` - (optional) the root directory of the project
+
+### POST /signify
+
+**Parameters:**
+- `text` - the contents of the file
+- `filename` - the absolute path to the file
+- `line` - the zero-based line position of the cursor
+- `column` - the zero-based column position of the cursor
+- `workspace` - (optional) the root directory of the project
+
+### GET /search
+
+Request an HTML page containing search results for the specified text.
+A search for "str" will include the String class in the results.
+
+**Parameters:**
+- `query` - the text to find
+- `workspace` - (optional) the root directory of the project
+
+### GET /document
+
+Request an HTML page containing documentation for the specified path. A path
+can be a class or module name, a class method (e.g., `Object.superclass`), or
+an instance method (e.g., `String#upcase`). Documentation will also be
+generated for the current workspace.
+
+**Parameters:**
+- `path` - the code path to find
+- `workspace` - (optional) the root directory of the project
+
+### POST /prepare
+
+Initialize an ApiMap for the specified workspace. This method can make
+subsequent requests for suggestions significantly faster.
+
+**Parameters:**
+- `workspace` - the root directory of the project
+
+### POST /update
+
+Update a file in the ApiMap for the specified workspace.
+
+**Parameters:**
+- `filename` - the absolute path to the file
+- `workspace` - the root directory of the project