vsg-bridge-ls/README.md

3.7 KiB

vsg_bridge_ls

version tests test coverage

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

The bridge is deliberately small. Contributions should preserve clean LSP standard output and keep the VSG subprocess boundary explicit.