/vscode-standard-ruby

The official VS Code extension for the Standard Ruby linter and code formatter

Primary LanguageTypeScriptOtherNOASSERTION

vscode-standard-ruby

This is the official VS Code extension for Standard Ruby, maintained by your friends at Test Double.

If you want to lint and format your Ruby in VS Code with Standard, you can either use this bespoke extension or configure Ruby LSP to use our built-in Ruby LSP add-on, which additionally offers Quick Fixes via Code Action support.

If you choose to use this extension, you can install it from the Visual Studio Marketplace.

Language Server Capabilities

These are the capabilities of this extension, each enabled by Standard's built-in LSP server:

Capability Support
Diagnostics (Linting) ✅
Document Formatting ✅
Execute Command (Trigger autofix) ✅
Everything else ❌

Requirements

Configuration

The extension only offers a few of its own configuration options, but because it conforms to the VS Code Formatting API, several general editor settings can impact the extension's behavior as well.

General editor settings

There are two general editor settings that you'll want to verify are set in order to use Standard Ruby as your formatter.

editor.defaultFormatter

First, if you want the extension to format your Ruby files, you need to specify Standard as your formatter of choice by setting editor.defaultFormatter under a "[ruby]" section of settings.json like this:

"[ruby]": {
  "editor.defaultFormatter": "testdouble.vscode-standard-ruby"
},

editor.formatOnSave

To automatically apply fixes to your Ruby with Standard Ruby, check Format on Save in the Formatting settings under Text Editor:

Format a file on save. A formatter must be available, the file must not be saved after delay, and the editor must not be shutting down.

Or, in settings.json:

"editor.formatOnSave": true,

Extension-specific settings

To edit Standard Ruby's own options, first expand Extensions and select Standard Ruby from the sidebar of the Settings editor.

standardRuby.mode

The Mode setting determines how (and whether) Standard Ruby runs in a given workspace. Generally, it will try to execute standardrb via bundle exec if possible, and fall back on searching for a global standardrb bin in your PATH.

Enable Standard Ruby via the workspace's Gemfile or else fall back on a global installation unless a Gemfile is present and its bundle does not include standard

  • "Always run—whether via Bundler or globally" (JSON: enableUnconditionally) this mode will first attempt to run via Bundler, but if that fails for any reason, it will attempt to run standardrb in your PATH
  • [Default] "Run unless the bundle excludes standard" (JSON: enableViaGemfileOrMissingGemfile) this mode will attempt to run Standard via Bundler, but if a bundle exists and the standard gem isn't in it (i.e. you're working in a project doesn't use Standard), the extension will disable itself. If, however, no bundle is present in the workspace, it will fall back on the first standardrb executable in your PATH
  • "Run only via Bundler, never globally" (JSON: enableViaGemfile) the same as the default enableViaGemfileOrMissingGemfile, but will never run standardrb from your PATH (as a result, single-file windows and workspace folders without a Gemfile may never activate the extension)
  • "Run only globally, never via Bundler" (JSON: onlyRunGlobally) if you want to avoid running the bundled version of Standard, this mode will never interact with Bundler and will only run standardrb on your PATH
  • "Disable the extension" (JSON: disable) disable the extension entirely

Or, in settings.json:

"standardRuby.mode": "enableViaGemfile",

standardRuby.autofix

The auto-fix option does what it says on the tin. if you don't want Standard to automatically edit your documents on save, you can disable it here:

Autofix

You might want to disable this if you're using Standard to highlight problems but don't want it to edit your files automatically. You could also accomplish this by disabling editor.formatOnSave, but as that's a global setting across all languages, it's more straightforward to uncheck this extension setting.

Or, in settings.json:

"standardRuby.autofix": true,

standardRuby.commandPath

As described above, the extension contains logic to determine which version of standardrb to launch. If you want a specific binary to run instead, you can set it here.

Command Path

This will override whatever search strategy is set in standardRuby.mode (except for disable, in which case the extension will remain disabled).

Or, in settings.json:

{
  "standardRuby.commandPath": "${userHome}/.rbenv/shims/standardrb"
}

Changing settings only for a specific project

You may want to apply certain settings to a specific project, which you can do by configuring them in the Workspace scope as opposed to the global User scope.

Workspace scope

Clicking "Workspace" before changing a setting will save it to .vscode/settings.json inside the root workspace directory and will not affect the extension's behavior in other workspace folders.

Manually triggering a format with automatic fixes

In addition to the built-in VS Code Formatting API, you can trigger the extension to format and auto-fix the current file listing by running the command "Standard Ruby: Format with Automatic Fixes":

Autofix command

This is handy if you don't want to enable format-on-save, already have another formatter associated with Ruby files, want to format your code before saving, or just want to bind a shortcut to Standard's formatting action.

To map a keybind to the command, search for it by name in the Keyboard Shortcuts editor:

Keybinding

Or, in keybindings.json:

[
  {
    "key": "ctrl+alt+cmd+f",
    "command": "standardRuby.formatAutoFixes"
  }
]

Decoding the Status Bar item

The extension also includes a status bar item to convey the status of the current file listing at a glance.

When the file conforms to Standard without issue:

Status: no issues

When the file contains a low-severity formatting issue:

Status: info

When the file contains a normal linter error:

Status: info

When the file fails to parse at all:

Status: parse failure

Clicking the status bar item will open the problems tab:

Problems tab

Limitations

There's some room for improvement yet, but it isn't yet clear whether these limitations will be a big deal in practice:

  • The extension will only launch a single instance of standardrb --lsp per workspace. If you're using a multi-root workspace, they'll all be handled by whatever Standard version is found in the first one
  • Standard's LSP only supports "Full" text document synchronization, both because it seemed hard to implement incremental sync correctly and because attempting to pass RuboCop's runner a partial document would result in inconsistent formatting results

Acknowledgements

This extension's codebase was initially based on Kevin Newton's vscode-syntax-tree extension, which has a similar architecture (VS Code language client communicating with a long-running Ruby process via STDIO). Thank you, Kevin! 💚

Code of Conduct

This project follows Test Double's code of conduct for all community interactions, including (but not limited to) one-on-one communications, public posts/comments, code reviews, pull requests, and GitHub issues. If violations occur, Test Double will take any action they deem appropriate for the infraction, up to and including blocking a user from the organization's repositories.