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