3.7 KiB
vsg_bridge_ls
vsg_bridge_ls reports VSG
diagnostics through the Language Server Protocol (LSP). A complete setup needs
the companion VSG fork and this bridge.
The bridge requires the companion package's version 1 diagnostic interface
(--diagnostics_json). An upstream VSG installation without that option is not
compatible.
Helix is the only actively maintained and tested editor integration. The Vim and VSCodium recipes are best-effort and may need adjustment for your setup.
1. Install the VSG fork
The preferred installation uses uv pip and the prebuilt package:
uv venv .venv
uv pip install --python .venv/bin/python \
--index https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/ \
vsg
Without uv, use standard pip:
python3 -m venv .venv
. .venv/bin/activate
python -m pip install \
--index-url https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/ \
--extra-index-url https://pypi.org/simple \
vsg
2. Install the bridge
cargo install --locked \
--git https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls.git
Activate the environment and verify both executables:
. .venv/bin/activate
command -v vsg
command -v vsg_bridge_ls
vsg_bridge_ls --version
The version includes both the Cargo release and build commit, for example
0.2.0+git.0123abcd, so editor logs can identify the exact binary.
3. Configure Helix
Add this minimal setup to ~/.config/helix/languages.toml:
[language-server.vsg_bridge_ls]
command = "vsg_bridge_ls"
[[language]]
name = "vhdl"
language-servers = ["vsg_bridge_ls"]
auto-format = false
Start Helix from the activated environment:
. .venv/bin/activate
hx path/to/file.vhd
Diagnostics should appear as you edit. Run :format to ask the bridge to
format the current in-memory buffer through the same VSG fix-all path used by
source.fixAll.vsg. No separate editor formatter command is required.
Hover a diagnosed line to see the VSG rule, configured severity, correction
phase, fixability, relevant configuration, and available documentation links.
Clients supporting LSP window/showDocument can also ask the bridge to open a
rule's documentation externally.
The code-action menu offers a Quick Fix for each fixable VSG rule on the
diagnosed line. Each action reruns VSG against the current in-memory document
and returns a versioned whole-line edit. Fix all VSG findings
(source.fixAll.vsg) is an explicit whole-document action equivalent to VSG's
normal phase-seven formatter; it runs on save only when the editor is configured
to request that action.
For deliberately unformatted files and expected interactions, see the LSP showcase.
An additional multi-rule action is available behind
--experimental-multi-rule-line-fix. It is disabled by default because VSG
phases can move later findings to different lines. See the
experimental action safety notes
before enabling it.
More documentation
- Installation alternatives and PATH troubleshooting
- Helix, Vim, and VSCodium setup
- VSG/bridge machine interface
- Development and packaging
The bridge is deliberately small. Contributions should preserve clean LSP standard output and keep the VSG subprocess boundary explicit.