|
Rust CI vsg-bridge-ls failed CI.
MadGobblins/vsg-bridge-ls/pipeline/head There was a failure building this commit
Details
|
||
|---|---|---|
| .cargo | ||
| doc | ||
| scripts | ||
| showcase | ||
| src | ||
| tests | ||
| vhdl | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| Cross.toml | ||
| DISCLOSURE.md | ||
| 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.
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_fixandexperimental_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
- Installation alternatives and PATH troubleshooting
- Install VSG from source
- Generate a project configuration
- Use multiple language servers
- Layered bridge configuration reference
- 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.