vsg-bridge-ls/doc/editor-configuration.md

5.1 KiB

Editor configuration

The bridge provides VSG diagnostics, opt-in rule-scoped Quick Fixes, an explicit source.fixAll.vsg action, and whole-document formatting over LSP. Formatting and fix-all both pipe the current in-memory buffer through the companion VSG fork's normal phase-seven formatter.

Helix is the only actively maintained and tested integration. The Vim and VSCodium recipes are best-effort starting points and may need adjustment. Whichever editor you use, launch it from the activated VSG environment or set absolute paths for both executables.

Helix

Add this configuration to ~/.config/helix/languages.toml:

[language-server.vsg_bridge_ls]
command = "vsg-bridge-ls"
args = [
  "--configuration", "/absolute/path/to/vsg-bridge-ls/showcase/vsg.yaml",
  # Uncomment to allow an action that opens rule documentation in a browser.
  # "--allow-browser-action",
  # Uncomment the next line to enable experimental individual rule fixes.
  # "--experimental-rule-fix",
  # Uncomment the next line to enable the experimental grouped line fix.
  # "--experimental-multi-rule-line-fix",
  # Uncomment the next line to expose debug information in hover and an action.
  # "--debug-mode",
]

[[language]]
name = "vhdl"
language-servers = ["vsg_bridge_ls"]
auto-format = false

To use another VSG configuration, change the path in the argument list. Repeat -c PATH for multiple files; relative paths are resolved from the project:

args = ["-c", "vhdl/config.yaml"]

The same bridge settings can live in the user or project TOML files described in the configuration reference. Explicit arguments in this editor setup take precedence.

The experimental grouped same-line action is enabled by uncommenting its entry in the complete example. It is deliberately off by default; read its safety notes before enabling it. Keep every option and value as a separate quoted array item with a trailing comma. An absolute configuration path avoids dependence on Helix's project working directory.

Debug mode is independent of the experimental correction modes. After enabling --debug-mode and restarting the server, use hover (space, then k) anywhere in an open VHDL document. Rule help is retained when the line has diagnostics, with the debug snapshot below it. The action-picker entry remains available as a fallback. See the debug-mode reference for the reported fields and privacy boundary.

If another VHDL server is installed, it can run alongside the bridge:

language-servers = ["vhdl_ls", "vsg_bridge_ls"]

Set auto-format = true only after testing the formatter on the project. The bridge owns the formatter arguments so diagnostics, fix-all, and formatting use one configured VSG executable and configuration. To check VSG independently:

vsg --stdin --stdout --fix -fp 7 --no-failure < vhdl/test.vhd

Use Helix's action picker (space, then a by default) on a diagnosed line to choose Fix all VSG findings. Start the bridge with --experimental-rule-fix to also offer one VSG rule correction. Hover (space, then k by default) shows the effective rule configuration and documentation. The menu is generated from current bridge state without starting VSG; only the selected correction starts a formatter process.

Vim (best-effort)

This example uses vim-lsp. With vim-plug, add the plugin and run :PlugInstall:

Plug 'prabirshrestha/vim-lsp'

Then register the bridge in .vimrc:

if executable('vsg-bridge-ls')
  au User lsp_setup call lsp#register_server({
        \ 'name': 'vsg_bridge_ls',
        \ 'cmd': {server_info->['vsg-bridge-ls']},
        \ 'allowlist': ['vhdl'],
        \ })
endif

Start Vim from the activated .venv. To pass a VSG configuration file, change the command to ['vsg-bridge-ls', '-c', 'vhdl/config.yaml'].

The bridge advertises standard LSP document formatting. Its standard code actions and formatting should appear through vim-lsp's corresponding commands.

VSCodium (best-effort)

VSCodium has no built-in setting for arbitrary LSP commands. One possible adapter is Generic LSP Proxy, but it is not currently available from Open VSX. Build its VSIX locally:

git clone https://github.com/mjmorales/vscode-generic-lsp-proxy.git
cd vscode-generic-lsp-proxy
npm install
npm run compile
npx vsce package
codium --install-extension generic-lsp-proxy-*.vsix
cd ..

Create .vscode/lsp-proxy.json in the VHDL project:

[
  {
    "languageId": "vhdl",
    "command": "vsg-bridge-ls",
    "transport": "stdio",
    "fileExtensions": [".vhd", ".vhdl"]
  }
]

Launch the project from the activated environment with codium ., then open a VHDL file. If diagnostics do not appear, check Output: Generic LSP Proxy. Desktop and sandboxed VSCodium installations may require an absolute command path or other PATH adjustments.

The bridge advertises standard LSP document formatting. Its opt-in Quick Fixes, source fix-all, and formatting should appear when the proxy preserves the corresponding standard LSP requests.