LSP (Language Server Protocol)
The built-in language server was introduced in RuboCop 1.53. This experimental feature has been under consideration for a while. |
The Language Server Protocol is the modern standard for providing cross-editor support for various programming languages.
This feature enables extremely fast interactions through the LSP.
Offense detection and autocorrection are performed in real-time by editors and IDEs using the language server. The Server Mode is primarily used to speed up RuboCop runs in the terminal. Therefore, if you want real-time feedback from RuboCop in your editor or IDE, opting to use this language server instead of the server mode will not only provide a fast and efficient solution, but also offer a straightforward setup for integration.
Examples of LSP Client
Here are examples of LSP client configurations.
VS Code
vscode-rubocop integrates RuboCop into VS Code.
You can install this VS Code extension from the Visual Studio Marketplace.
For VS Code-based IDEs like VSCodium or Eclipse Theia, the extension can be installed from the Open VSX Registry.
Emacs (Eglot)
Eglot is a client for Language Server Protocol servers on Emacs.
Add the following to your Emacs configuration file (e.g. ~/.emacs.d/init.el
):
(require 'eglot)
(add-to-list 'eglot-server-programs '(ruby-mode . ("bundle" "exec" "rubocop" "--lsp")))
(add-hook 'ruby-mode-hook 'eglot-ensure)
Below is an example of additional setting for autocorrecting on save:
(add-hook 'ruby-mode-hook (lambda () (add-hook 'before-save-hook 'eglot-format-buffer nil 'local)))
If you run into problems, first use "M-x eglot-reconnect" to reconnect to the language server.
See Eglot’s official documentation for more information.
Emacs (LSP Mode)
LSP Mode is an Emacs client/library for the Language Server Protocol.
You can get the new lsp-mode
package from MELPA.
See LSP Mode official documentation for more information: https://emacs-lsp.github.io/lsp-mode/page/lsp-rubocop/
Vim and Neovim (coc.nvim)
coc.nvim is an extension host for Vim and Neovim, powered by Node.js. It allows the loading of extensions similar to VSCode and provides hosting for language servers.
Add the following to your coc.nvim configuration file. For example, in Vim, it would be ~/.vim/coc-settings.json
,
and in Neovim, it would be ~/.config/nvim/coc-settings.json
:
{
"languageserver": {
"rubocop": {
"command": "bundle",
"args" : ["exec", "rubocop", "--lsp"],
"filetypes": ["ruby"],
"rootPatterns": [".git", "Gemfile"],
"requireRootPattern": true
}
}
}
Below is an example of additional setting for autocorrecting on save:
{
"coc.preferences.formatOnSave": true
}
See coc.nvim’s official documentation for more information.
Neovim (nvim-lspconfig)
nvim-lspconfig provides quickstart configs for Neovim’s LSP.
Add the following to your nvim-lspconfig configuration file (e.g. ~/.config/nvim/init.lua
):
vim.opt.signcolumn = "yes"
vim.api.nvim_create_autocmd("FileType", {
pattern = "ruby",
callback = function()
vim.lsp.start {
name = "rubocop",
cmd = { "bundle", "exec", "rubocop", "--lsp" },
}
end,
})
Below is an example of additional setting for autocorrecting on save:
vim.api.nvim_create_autocmd("BufWritePre", {
pattern = "*.rb",
callback = function()
vim.lsp.buf.format()
end,
})
See nvim-lspconfig’s official documentation for more information.
Helix
Helix is a post-modern modal text editor with built-in language server support.
Add the following to your Helix language configuration file (e.g. ~/.config/helix/languages.toml
):
Helix 23.10 or later:
[language-server.rubocop]
command = "bundle"
args = ["exec", "rubocop", "--lsp"]
[[language]]
name = "ruby"
auto-format = true
language-servers = [
{ name = "rubocop" }
]
Before Helix 23.10 or earlier:
[[language]]
name = "ruby"
language-server = { command = "bundle", args = ["exec", "rubocop", "--lsp"] }
auto-format = true
See Helix’s official documentation for more information: https://docs.helix-editor.com/languages.html
Sublime Text
For Sublime Text LSP support is available through the Sublime-LSP plugin.
Add the following to its settings (accessible via Preferences → Package Settings → LSP → Settings
) to enable RuboCop:
{
"clients": {
"rubocop": {
"enabled": true,
"command": ["bundle", "exec", "rubocop", "--lsp"],
"selector": "source.ruby | text.html.ruby | text.html.rails",
},
},
}
Autocorrection
The language server supports textDocument/formatting
method and is autocorrectable. The autocorrection is safe by default (rubocop -a
).
LSP client can switch to unsafe autocorrection (rubocop -A
) by passing the following safeAutocorrect
parameter in the initialize
request.
{
"jsonrpc": "2.0",
"id": 42,
"method": "initialize",
"params": {
"initializationOptions": {
"safeAutocorrect": false
}
}
}
For detailed instructions on setting the parameter, please refer to the configuration methods of your LSP client.
The safeAutocorrect parameter was introduced in RuboCop 1.54.
|
As execute commands in the workspace/executeCommand
parameters, it provides rubocop.formatAutocorrects
for safe autocorrections (rubocop -a
) and
rubocop.formatAutocorrectsAll
for unsafe autocorrections (rubocop -A
).
These parameters take precedence over the initializationOptions:safeAutocorrect
value set in the initialize
parameter.
The rubocop.formatAutocorrectsAll execute command was introduced in RuboCop 1.56.
|
Lint Mode
LSP client can run lint cops by passing the following lintMode
parameter in the initialize
request
if you only want to enable the feature as a linter like ruby -w
:
{
"jsonrpc": "2.0",
"id": 42,
"method": "initialize",
"params": {
"initializationOptions": {
"lintMode": true
}
}
}
Furthermore, enabling autocorrect in a LSP client at the time of saving equates to the effect of rubocop -l
option.
For detailed instructions on setting the parameter, please refer to the configuration methods of your LSP client.
The lintMode parameter was introduced in RuboCop 1.55.
|
Layout Mode
LSP client can run layout cops by passing the following layoutMode
parameter in the initialize
request
if you only want to enable the feature as a formatter:
{
"jsonrpc": "2.0",
"id": 42,
"method": "initialize",
"params": {
"initializationOptions": {
"layoutMode": true
}
}
}
Furthermore, enabling autocorrect in a LSP client at the time of saving equates to the effect of rubocop -x
option.
For detailed instructions on setting the parameter, please refer to the configuration methods of your LSP client.
The layoutMode parameter was introduced in RuboCop 1.55.
|
Enable YJIT
YJIT, a Ruby JIT compiler, has been supported since Ruby 3.1.
In an LSP client, you can enable YJIT by launching rubocop --lsp
with the RUBY_YJIT_ENABLE=1
environment variable using the env
command:
env RUBY_YJIT_ENABLE=1 bundle exec rubocop --lsp
Below is an example for Emacs’s Eglot:
(add-to-list 'eglot-server-programs '(ruby-mode . ("env" "RUBY_YJIT_ENABLE=1" "bundle" "exec" "rubocop" "--lsp")))
The console of the LSP client will display +YJIT
:
RuboCop 1.63.4 language server +YJIT initialized, PID 13501
For more details, please refer to the respective LSP configuration documentation. In some cases, like with vscode-rubocop, it may be available as a built-in option: https://github.com/rubocop/vscode-rubocop#rubocopyjitenabled
Run as a Language Server
Run rubocop --lsp
command from LSP client.
When the language server is started, the command displays the language server’s PID:
$ ps aux | grep 'rubocop --lsp'
user 17414 0.0 0.2 5557716 144376 ?? Ss 4:48PM 0:02.13 rubocop --lsp /Users/user/src/github.com/rubocop/rubocop
rubocop --lsp is for starting LSP client, so users don’t manually execute it.
|
Language Server Development
RuboCop provides APIs for developers of original language server or tools analogous to LSP, using RuboCop as the backend, instead of the RuboCop’s built-in LSP.
-
RuboCop::LSP.enable
enables LSP mode, customizing for LSP-specific features such as autocorrection and short offense message. -
RuboCop::LSP.disable
disables LSP mode, which can be particularly useful for testing. And intentional autocorrection by the user can be specified. e.g,workspace/executeCommand
andtextDocument/codeAction
LSP methods.
When implementing custom cops, RuboCop::LSP.enabled?
can be used to achieve behavior that considers these states.