repository·main·Indexed 24 days ago
https://github.com/shopify/ruby-lspA language server implementation for Ruby that provides editor features such as autocompletion, code navigation, and documentation via the Language Server Protocol. It includes an official VS Code extension, a CLI for server management and troubleshooting, and an experimental add-on system for extending functionality through gems.
Ruby LSP implements the Language Server Protocol for Ruby to provide rich editor features. Key capabilities include:
The Ruby LSP roadmap outlines major milestones for the project. Key areas of focus include:
find references (methods, instance variables, local variables), rename support, show type hierarchy, and navigation between related code (e.g., from tests to implementations).new.extract to method and extract to class/module.The Ruby LSP extension runs inside the VS Code NodeJS runtime. Because NodeJS does not automatically inherit environment variables set in your shell (like those from rbenv or asdf), the extension must explicitly invoke your shell in interactive mode to capture the correct environment.
zsh -ic).~/.zshrc).rbenv exec ruby) and prints the resulting environment variables as JSON.ruby-lsp to their project's Gemfile, the extension creates a composed bundle inside a .ruby-lsp directory within your project.Ruby LSP supports VS Code multi-root workspaces by spawning a separate language server instance for each workspace root. This allows each workspace to use a different Ruby version and a different set of gems, which would be impossible in a single process.
To ensure proper functionality, you must define the workspace folders in a .code-workspace file. You can use files.exclude in the workspace settings to prevent the same files from appearing twice in the explorer if one directory is a sub-directory of another.
{
"folders": [
{
"name": "rails",
"path": ".",
},
{
"name": "react",
"path": "frontend",
},
],
"settings": {
"files.exclude": {
"frontend": true,
},
},
}Ruby LSP executes code from your workspace through several mechanisms:
Ruby LSP automatically performs bundler operations (such as bundle install or bundle update) when starting up or when detecting changes to your Gemfile. This results in:
Gemfile.Ruby LSP automatically discovers and loads add-ons from:
ruby_lsp/**/addon.rb files.ruby_lsp/**/addon.rb anywhere in your workspace.Add-ons are loaded via require and their activate method is called, allowing them to execute arbitrary Ruby code, including spawning processes or making network requests.
Ruby LSP attempts to identify the type of a receiver based on its identifier to provide better method completion.
How it works:
user inside module Admin matches Admin::User).Usage for exploration: You can use this to quickly explore methods in a class by typing the lowercase name of the class as an identifier:
pathname.a
integer.a
file.aWarning: This is an experimental feature. Do not rename variables solely to improve type guessing; readability should always come first. It can be easily fooled if a variable name does not match its actual type.
The Ancestors Hierarchy Request is an experimental feature that implements the Type Hierarchy Supertypes LSP request. It allows developers to:
Because it is experimental, behavior regarding singleton classes and the inclusion of modules versus pure classes is subject to change based on feedback and LSP specification clarifications.
Ruby LSP does not collect telemetry by default but allows integration with private metrics services. To enable this, you must create a separate VS Code extension that registers the command getTelemetrySenderObject.
This command must return an object that implements the vscode.TelemetrySender interface, including the following methods:
sendEventData(eventName: string, data: EventData): voidsendErrorData(error: Error, data?: Record<string, any>): voidflush(): Promise<void> (optional)// Your private VS Code extension
class Telemetry implements vscode.TelemetrySender {
constructor() {
// Initialize some API service or whatever is needed to collect metrics
}
sendEventData(eventName: string, data: EventData): void {
// Send events to some API or accumulate them to be sent in batch when `flush` is invoked by VS Code
}
sendErrorData(error: Error, data?: Record<string, any> | undefined): void {
// Send errors to some API or accumulate them to be sent in batch when `flush` is invoked by VS Code
}
async flush() {
// Optional function to flush accumulated events and errors
}
}
export async function activate(context: vscode.ExtensionContext) {
const telemetry = new Telemetry();
await telemetry.activate();
// Register the command that the Ruby LSP will search for to hook into
context.subscriptions.push(
vscode.commands.registerCommand("getTelemetrySenderObject", () => {
return telemetry;
}),
);
}To integrate seamlessly with project-specific dependencies (like linters, formatters, and test frameworks) without requiring users to manually add ruby-lsp to their project's Gemfile, Ruby LSP uses a composed bundle strategy.
When you run the ruby-lsp executable, it performs the following lifecycle:
ruby-lsp (without bundle exec).your_project/.ruby-lsp and generates a new Gemfile inside it. This generated Gemfile includes:ruby-lsp gem.Gemfile.debug and ruby-lsp-rails.bundle install and attempts to auto-update the ruby-lsp gem to ensure you have the latest features and fixes.BUNDLE_GEMFILE=.ruby-lsp/Gemfile bundle exec ruby-lsp. This ensures the language server runs with full access to your project's $LOAD_PATH and dependencies.This approach allows the language server to automatically detect and index declarations from gems without manual user configuration.
To avoid LocalJumpError when using yield, use the block_given? method. This method returns true if a block was passed to the current method and false otherwise, allowing you to handle the absence of a block gracefully.
def foo
if block_given?
result = yield(10)
puts result
else
puts "No block passed!"
end
end
foo do |a|
a * 2
end
# => 20
foo
# => No block passed!