Solargraph Ruby Language Server

Solargraph includes a type checker that uses YARD tags and code analysis to report missing type definitions. It operates in two primary modes:

• Strict mode: Performs type inference to determine if YARD tags match the types detected from the code.
• Strong mode: Requests that you clarify intentions by adding annotations for better validation.

Solargraph automatically generates code maps from installed gems using YARD or RBS information. When you require a gem, its API is included in code completion.

To eagerly cache gem documentation, use:

solargraph gems

If gems lack YARD or RBS information, you can install community-supported RBS types using gem_rbs_collection:

bundle exec rbs collection init
bundle exec rbs collection install

You can install Solargraph either as a global gem or as a development dependency in your project's Gemfile.

To install globally via the command line:

gem install solargraph

To add it to a specific project using Bundler, add this to your Gemfile:

gem 'solargraph', group: :development

For projects using Bundler, the most effective way to ensure Solargraph uses the correct gem versions and dependencies is to bundle Solargraph itself.

1. Add gem 'solargraph', group: :development to your Gemfile.
2. Run bundle install.
3. (Optional) Run bundle exec solargraph gems to generate documentation for cached, vendored, or local gems.

When starting the language server, use Bundler to ensure the correct environment:

• For TCP connection: bundle exec solargraph socket
• For stdio connection: bundle exec solargraph stdio

In VS Code, you can enable this via the solargraph.useBundler setting.

The Solargraph::DocMap class manages the collection of 'pins' (documentation metadata) generated from required gems. It supports two primary documentation sources:

1. YARD: Traditional Ruby documentation generated via YARD plugins.
2. RBS collection: Modern Ruby type definitions from RBS collections.

Solargraph attempts to combine these sources into a single set of pins for each gem. It uses a caching mechanism (PinCache) to avoid re-generating documentation metadata every time the language server starts. If a gem has both YARD and RBS documentation, Solargraph creates a 'combined' cache entry. If only one is available, it uses that instead.

Solargraph uses configuration files to control its behavior. The priority order is:

1. A .solargraph.yml file at the root of your project.
2. A global configuration file at ~/.config/solargraph/config.yml.

You can override the global configuration path using the SOLARGRAPH_GLOBAL_CONFIG environment variable.

To generate a new configuration file, run:

bundle exec solargraph config

If you need to use a specific version of rubocop for diagnostics or formatting (other than the latest installed version), specify it in your .solargraph.yml file under the reporters and formatter keys.

---
reporters:
- rubocop:version=0.61.0  # diagnostics
formatter:
  rubocop:
    version: 0.61.0       # formatting

Solargraph stores documentation for Ruby core and gems in a cache directory. The default is ~/.cache/solargraph (Linux) or C:\Users\<username>\.cache\solargraph (Windows).

You can change this location by setting the SOLARGRAPH_CACHE environment variable.

The Solargraph::LanguageServer::Host can be configured by passing a hash of options to the configure method. This allows updating settings such as logLevel and various feature toggles.

Default configuration keys include:

• completion (Boolean)
• hover (Boolean)
• symbols (Boolean)
• definitions (Boolean)
• typeDefinitions (Boolean)
• rename (Boolean)
• references (Boolean)
• autoformat (Boolean)
• diagnostics (Boolean)
• formatting (Boolean)
• folding (Boolean)
• highlights (Boolean)
• logLevel (String, e.g., 'warn')