How shopify/ruby-lsp works
Project Type and Purpose
• This is a language server implementation for Ruby. It uses the language server protocol to allow editors—especially VS Code—to get features like code completion, definition lookup, diagnostics, formatting, and more.
• Its dual nature appears in both Ruby (core server logic, indexing, request handling) and TypeScript (VS Code extension that communicates with the Ruby process).
File Structure Insights
• The top-level directories (e.g., “lib”, “exe”, “bin”, “jekyll”, “vscode”, “sorbet”, “test”) indicate clearly separated concerns:
• “lib/ruby_lsp”: Contains the core server code, listeners for different requests (completion, definition, hover, etc.), response builders, and utilities.
• “lib/ruby_indexer”: Implements indexing functionality to enable fast code lookup, search, and integration with RBS (Ruby signatures).
• “vscode”: Contains the VS Code extension’s source code in TypeScript responsible for client-side integration.
• “jekyll” and “static_docs”: Provide documentation and a website (likely rendered via Jekyll).
• “test”: Contains comprehensive tests for all aspects of the LSP, including integration and functional tests.
• “sorbet”: Contains static type information and RBI files that may be used to ensure type safety.
• The existence of CI/CD workflows in “.github/workflows” and configuration files (like Gemfile, Rakefile, etc.) indicate rigorous build, test, and deployment processes.
a. Clients (Editors and Extensions):
• VS Code Extension (in the “vscode” directory, TypeScript) that communicates with the Ruby LSP.
• Other potential clients via the LSP (as indicated in the README with references to multiple editors).
b. Ruby LSP Server:
• Core Modules:
• Ruby LSP Core (lib/ruby_lsp) with the Base Server, listeners for each language feature (completion, definition, hover, etc.), and request handlers.
• Request modules (found within lib/ruby_lsp/requests) that define how incoming messages are processed.
• Response Builders (in lib/ruby_lsp/response_builders) to construct the final responses.
• Indexing and Analysis:
• “lib/ruby_indexer” for indexing Ruby code, handling declarations, locating references, and processing RBS.
• Integration with RuboCop and static analysis (as seen with the additional “lib/rubocop/cop/ruby_lsp” components).
• Ancillary Features:
• Scripts, configuration for Bundler, and Sandboxing (e.g., “exe/ruby-lsp”, “bin/tapioca”).
• Command-line scripts and report generation utilities.
c. Communication and Data Flow:
• The VS Code extension initiates a Language Server Protocol connection with the Ruby LSP server.
• The server receives requests (e.g., code completion, definition lookup) and delegates to the appropriate request handler or listener.
• Data (such as symbol declarations, diagnostic information, and code indexes) is gathered through the indexer and then packaged by the response builders to be sent back through the LSP connection to the client.
d. Supporting Infrastructure:
• CI/CD workflows configured in “.github/workflows” for testing, publishing, and version bumping.
• Configuration files (e.g., Gemfile, Rakefile) to manage dependencies and build tasks.
• Documentation websites via “jekyll” and static docs in “static_docs”.