A very featureless VSG to lsp bridge
Go to file
Dandaedre 8008534dfd
Rust CI vsg-bridge-ls passed CI.
MadGobblins/vsg-bridge-ls/pipeline/head This commit looks good Details
Replace stale findings with syntax failures
2026-10-03 21:16:34 +02:00
.cargo
…
doc Replace stale findings with syntax failures 2026-10-03 21:16:34 +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 Replace stale findings with syntax failures 2026-10-03 21:16:34 +02:00
tests Replace stale findings with syntax failures 2026-10-03 21:16:34 +02:00
vhdl
…
.gitignore Prepare 0.3.2 release candidate 2026-10-03 03:24:31 +02:00
Cargo.lock Contain malformed diagnostics and verify non-destructive fixes 2026-10-03 15:52:24 +02:00
Cargo.toml Contain malformed diagnostics and verify non-destructive fixes 2026-10-03 15:52:24 +02:00
Cross.toml Fix Windows release builds 2026-10-03 04:03:17 +02:00
DISCLOSURE.md Replace stale findings with syntax failures 2026-10-03 21:16:34 +02:00
Jenkinsfile Fix Windows release builds 2026-10-03 04:03:17 +02:00
LICENSE
…
README.md Replace stale findings with syntax failures 2026-10-03 21:16:34 +02:00
build.rs Release bridge milestone 0.2.0 2026-10-03 01:39:53 +02:00
deny.toml
…
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.

Authorship and LLM disclosure

  • Human foundation: Dandaedre created the project, its goals, and the first working bridge. VSG itself is the work of its upstream author and contributors. The maintainer decides the requirements and accepts releases.
  • LLM-assisted work: a substantial part of the later Rust implementation, protocol hardening, tests, CI, and documentation was written or refined with an LLM coding assistant under maintainer direction.
  • What is tested: automated tests cover the LSP lifecycle, in-memory and Unicode document handling, JSON validation, diagnostics, stale-result suppression, subprocess failures, formatting, and correction actions. CI also runs formatting, compilation, Clippy, dependency checks, and a 90% line coverage gate. Tests reduce risk; they do not prove the absence of defects.
  • Practical risk: normal diagnostics only read the editor buffer, run the local VSG process, and publish messages. The diagnostic JSON is metadata collected from VSG's analysis; it cannot change the VHDL or its formatting, and no LLM service is used at runtime. Formatting and fix actions are the exception: when explicitly requested, they can apply VSG-produced edits to the editor buffer. Per-rule fixes remain experimental. Review edits and keep work under version control, especially for safety-critical HDL. See the full authorship, testing, and risk disclosure for details.

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

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

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.