5.1 KiB
Authorship, LLM Use, and Safety Disclosure
This document explains how vsg-bridge-ls was developed, where an LLM was
used, what the project tests, and which actions can affect source code. It is a
process and risk disclosure, not a warranty or a substitute for project review.
Authorship
The project idea, requirements, and first working bridge were created by Dandaedre. The human maintainer decides the project's scope, evaluates its behavior, and accepts releases. The underlying VSG parser, rules, and formatter come from VSG and its upstream author and contributors.
A substantial part of the bridge's later Rust implementation, LSP and JSON protocol hardening, automated tests, CI, packaging, and documentation was written or refined with an LLM coding assistant under maintainer direction. Development has been iterative, so the repository does not claim reliable line-by-line attribution between human-written and LLM-assisted code. Git history remains the record of when each change was reviewed and accepted into the project.
What happens at runtime
The distributed language server contains no LLM and does not contact an LLM service. For normal diagnostics it:
- receives the current VHDL buffer from the editor;
- passes that text through standard input to the locally installed VSG executable;
- validates VSG's diagnostic JSON; and
- publishes LSP diagnostics, hover text, and available actions.
That path is observational. JSON contains diagnostic and rule metadata collected from VSG's analysis; producing or reading it cannot alter the VHDL, change its formatting, or write the source file. Source text is sent to the local VSG process, not to an LLM or a project-operated network service. The optional documentation action may ask the editor to open a public rule URL, but it is disabled unless explicitly allowed.
Formatting and fixes have a different boundary. An editor formatting request,
source.fixAll.vsg, or an enabled per-rule action asks VSG to produce corrected
text. The bridge then returns or requests a versioned edit, which the editor may
apply to its in-memory buffer. These actions are explicit unless the user has
configured the editor to run them automatically, such as on save.
What is tested
The automated suite covers:
- LSP initialization, shutdown, synchronization, and diagnostic clearing;
- use of unsaved in-memory text and suppression of stale results;
- JSON schema, metadata, severity, URL, and line-range validation;
- syntax-error location, stale-warning removal, and correction suppression;
- whole-document analysis errors when VSG cannot provide a safe location;
- default severity demotion and opt-in strict severity mapping;
- safe project-configuration generation without overwriting existing files;
- hover capability suppression for multi-language-server editor setups;
- ASCII, Unicode, UTF-16 positions, CRLF, empty lines, and document boundaries;
- missing, failing, stalled, or non-UTF-8 VSG subprocesses;
- formatting, whole-document fixes, scoped fixes, no-op edits, and concurrent document changes;
- feature gating for experimental fixes, browser actions, and debug output; and
- deterministic line-edit behavior over examples and bounded generated cases.
CI checks formatting, compilation on the declared minimum Rust version and current stable Rust, tests, Clippy warnings, dependency policy and known advisories, and a 90% line-coverage floor. Most tests use an injected or fake VSG runner for repeatability; an opt-in test also exercises the packaged VSG process boundary.
These checks demonstrate the tested cases only. They are not formal verification and do not prove that every editor, platform, VSG configuration, or VHDL input is handled correctly. Helix is the actively maintained editor integration; Vim and VSCodium instructions are best-effort.
Risk by operation
| Operation | Source-change risk | Main remaining risk |
|---|---|---|
| Diagnostics and hover | None by design | A bug may omit, duplicate, or misplace a finding. |
| Debug information | None by design | Metadata may reveal local paths or process details; source text and environment variables are intentionally excluded. |
| Open documentation | None to VHDL | When enabled, the editor may open an external HTTPS URL. |
| Format or fix all | Intentionally changes the editor buffer | A formatter defect or unexpected configuration may produce an unwanted edit. |
| Experimental per-rule or grouped fix | Intentionally changes the editor buffer | VSG phases can move findings between lines, so a scoped selection may not behave as expected. |
Document-version checks, protocol validation, feature gates, and conservative whole-line or whole-document edits reduce these risks. They cannot establish that a formatting change preserves the intended hardware behavior.
Treat the configured VSG executable, configuration files, and Python local rules as trusted inputs. Local rules are executable code in the VSG process and are outside the bridge's security boundary.
For important or safety-critical HDL, keep work in version control, inspect every applied edit, and run the project's normal simulation, synthesis, linting, and review process before accepting a change.