|
Rust CI vsg-bridge-ls passed CI.
MadGobblins/vsg-bridge-ls/pipeline/head This commit looks good
Details
|
||
|---|---|---|
| .cargo | ||
| doc | ||
| scripts | ||
| showcase | ||
| src | ||
| tests | ||
| vhdl | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| Cross.toml | ||
| Jenkinsfile | ||
| LICENSE | ||
| README.md | ||
| build.rs | ||
| deny.toml | ||
| release.sh | ||
| rust-release.toml | ||
| tarpaulin.toml | ||
README.md
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.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
- Installation alternatives and PATH troubleshooting
- Layered bridge configuration
- Helix, Vim, and VSCodium setup
- VSG/bridge machine interface
- Experimental individual rule fixes
- Debug-information mode
- Development and packaging
- Release procedure
The bridge is deliberately small. Contributions should preserve clean LSP standard output and keep the VSG subprocess boundary explicit.