vsg-bridge-ls/README.md

9.9 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.

Authorship and LLM disclosure

Dandaedre created the bridge and directs its development; upstream VSG remains the work of its original authors and contributors. Later implementation, testing, CI, and documentation were substantially developed or refined with an LLM assistant. No LLM is used at runtime. Diagnostics cannot modify VHDL, while explicit formatting and fix actions can. See the full authorship, testing, and safety disclosure.

1. Install the VSG fork

The modified VSG packages are published in the MadGobblins Python package index. The preferred installation uses uv pip and its prebuilt wheel:

uv venv .venv
uv pip install --python .venv/bin/python \
  --upgrade \
  --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 \
  --upgrade \
  --index-url https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/ \
  --extra-index-url https://pypi.org/simple \
  vsg

This is a narrow integration fork, so upstream remains the owner of VSG release numbers. Packages built between upstream tags instead use an automatic PEP 440 post version such as 3.35.0.post186+git.b7dc18c1; this lets --upgrade select newer fork commits. If an installation still remains on an equal or newer version—for example after rewritten development history—add --reinstall to the uv command or --force-reinstall to the pip command. As a final fallback, uninstall vsg and install it again manually.

2. Install the bridge

The preferred method uses cargo-binstall. Releases provide three prebuilt platform binaries; cargo-binstall selects and installs the one for the current system from the latest release candidate:

cargo binstall --git \
  https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls.git \
  vsg-bridge-ls

Without cargo-binstall, build and install the bridge from source:

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.3.6-rc.1+git.0123abcd, so editor logs can identify the exact binary. To start from a generated TOML file, see Generate a project configuration.

3. Configure Helix

Add this minimal setup 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",
]

[[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. If VSG encounters a syntax error, the bridge replaces stale style findings with one error on the reported line and temporarily withholds formatting and correction actions. Normal diagnostics and actions return after parsing succeeds again. When VSG cannot determine a trustworthy location, the bridge reports one whole-document analysis-failed error instead. Its wording says that VSG could not analyze the document, because unsupported valid VHDL can also cause a parser failure.

Style diagnostics use editor-friendly levels by default: VSG errors appear as LSP warnings, and VSG warnings appear as information. This keeps lint findings visually distinct from parser errors. Pass --strict-diagnostic-severity (or set strict_diagnostic_severity = true in bridge TOML) to preserve VSG's Error and Warning levels exactly.

Hover a diagnosed line to see the VSG rule, configured severity, correction phase, fixability, relevant configuration, and available documentation links. With --allow-browser-action, clients supporting LSP window/showDocument can also ask the bridge to open a rule's documentation externally.

Less common options are collected under Advanced usage.

Advanced usage

This section covers installing VSG from source, configuration generation, multiple language servers, experimental fixes, and debug mode.

Install VSG from source

To install the current fork directly from Git instead of the package index:

uv venv .venv
uv pip install --python .venv/bin/python --upgrade \
  "vsg @ git+https://proxy.dandaedre.com/gitea/MadGobblins/vhdl-style-guide.git@master"

This requires Git and builds VSG locally. Replace master with a commit hash for a reproducible installation. Add --reinstall when reinstalling the same commit after a local packaging or environment problem.

Generate a project configuration

From the project directory, --write-config creates vsg-bridge-ls.toml from the options supplied in the same command, then exits:

vsg-bridge-ls \
  --configuration /absolute/path/to/vsg.yaml \
  --experimental-rule-fix \
  --write-config

It refuses to overwrite an existing file. The most useful settings are:

  • vsg_configuration: VSG configuration paths, in loading order.
  • strict_diagnostic_severity: preserve VSG's Error and Warning levels.
  • experimental_rule_fix and experimental_multi_rule_line_fix: enable correction actions.
  • allow_browser_action: allow documentation actions to open HTTPS links.
  • debug_mode: expose troubleshooting information.
  • disable_hover: leave hover presentation to another language server.

Edit the generated file as needed and restart the language server. Explicit command-line options take priority over configuration files. See the configuration reference for all settings.

Multiple language servers

Helix can run the bridge alongside a semantic VHDL server such as vhdl_ls:

[language-server.vhdl_ls]
command = "vhdl_ls"
args = ["-l", "/usr/local/lib/vhdl_libraries"]

[[language]]
name = "vhdl"
file-types = ["vhd", "vhdl"]
language-servers = ["vhdl_ls", "vsg_bridge_ls"]
auto-format = false

Both servers may answer the same hover request. In Helix's hover popup, use Alt+n for the next result and Alt+p for the previous result. The bridge may appear first regardless of the order in language-servers; treat the popup as a set of results rather than relying on response order.

If VSG hover is unwanted, place this in vsg-bridge-ls.toml:

disable_hover = true

The equivalent command-line option is --disable-hover. Diagnostics, formatting, and code actions remain available; only hover is disabled.

Experimental fixes

With --experimental-rule-fix, the code-action menu immediately offers a Quick Fix for each fixable VSG rule on the diagnosed line. Building the menu does not run VSG; selecting one action runs one VSG process against the current in-memory document and asks the client to apply 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.

The commented argument above enables an additional multi-rule action. It is disabled by default because VSG phases can move later findings to different lines. See the experimental action safety notes before enabling it.

Debug mode

The independent --debug-mode flag adds the same debug snapshot to normal LSP hover (space+k in Helix), including on lines without diagnostics. A source action remains available as a fallback. The snapshot includes build, process, configuration, capability, and open-document metadata without source text or process environment variables. See the debug-mode reference.

More documentation

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