A very featureless VSG to lsp bridge
Go to file
Dandaedre da279289c9
Rust CI vsg-bridge-ls passed CI.
MadGobblins/vsg-bridge-ls/pipeline/head This commit looks good Details
Prepare 0.3.2 release candidate 3
2026-10-03 04:11:37 +02:00
.cargo Pin Rust compatibility and publish coverage 2026-10-02 21:08:47 +02:00
doc Prepare 0.3.2 release candidate 3 2026-10-03 04:11:37 +02:00
scripts Center badge text vertically 2026-10-03 00:19:08 +02:00
showcase Add layered bridge configuration 2026-10-03 03:20:57 +02:00
src Prepare 0.3.2 release candidate 3 2026-10-03 04:11:37 +02:00
tests Fix Windows release builds 2026-10-03 04:03:17 +02:00
vhdl Adds -ap to process all lints 2024-11-21 08:33:33 -06:00
.gitignore Prepare 0.3.2 release candidate 2026-10-03 03:24:31 +02:00
Cargo.lock Prepare 0.3.2 release candidate 3 2026-10-03 04:11:37 +02:00
Cargo.toml Prepare 0.3.2 release candidate 3 2026-10-03 04:11:37 +02:00
Cross.toml Fix Windows release builds 2026-10-03 04:03:17 +02:00
Jenkinsfile Fix Windows release builds 2026-10-03 04:03:17 +02:00
LICENSE
…
README.md Prepare 0.3.2 release candidate 3 2026-10-03 04:11:37 +02:00
build.rs Release bridge milestone 0.2.0 2026-10-03 01:39:53 +02:00
deny.toml Add Cargo dependency policy gates 2026-10-02 21:45:16 +02:00
release.sh Prepare 0.3.2 release candidate 2026-10-03 03:24:31 +02:00
rust-release.toml Prepare 0.3.2 release candidate 2026-10-03 03:24:31 +02:00
tarpaulin.toml Retain only the coverage badge 2026-10-02 23:28:11 +02:00

README.md

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.3.2-rc.3+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"
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

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. With --allow-browser-action, clients supporting LSP window/showDocument can also ask the bridge to open a rule's documentation externally.

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.

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.