12 KiB
VSG diagnostic stream interface
This document defines the boundary between the VSG fork and vsg-bridge-ls.
It is intentionally additive: existing VSG commands remain byte-for-byte and
behaviorally unchanged when the new arguments are absent.
Commands
Diagnostic request
vsg --stdin --all_phases --diagnostics_json --no-failure [VSG configuration arguments]
--diagnostics_json is a new boolean argument. It selects the protocol below
for diagnostics written to stdout. It does not replace, alias, or change
--json, --output_format, or any existing report format.
The new mode is incompatible with options that also claim stdout, including
--stdout and --debug. Validate only combinations involving the new option;
do not tighten validation for existing invocations.
Stdout always contains exactly one UTF-8 JSON object followed by one newline,
including when argument validation, configuration, parsing, rules, or rendering
fail. Human headers, progress, debug text, and fixed VHDL must never appear on
stdout in this mode. Failure details may also go to stderr and operational
failures return nonzero. --no-failure continues to affect findings as it does
today; it must not hide an incomplete analysis or protocol error.
Scoped correction request
vsg --stdin --fix --stdout --fix_rule RULE:LINE --no-failure [VSG configuration arguments]
--fix_rule is a new repeatable argument and a thin in-memory translation to
the existing --fix_only structure:
{"fix":{"rule":{"RULE":[LINE]}}}
Parse the selector by its final colon. The rule ID must be nonempty and LINE
must be a positive decimal integer. Deduplicate repeated selectors. Require
--fix; reject combination with --fix_only rather than defining precedence.
All other fixing behavior, phase ordering, stdout content, and exit semantics
remain owned by the existing VSG implementation.
--fix_rule is part of the approved interface. Its implementation must remain
limited to argument parsing, validation, deduplication, and construction of the
existing --fix_only data structure; it must not introduce another fix engine.
If that boundary cannot be maintained, stop and report the design conflict
rather than broadening the fork change or silently substituting another bridge
protocol.
Diagnostic document version 1
The top-level JSON object is:
{
"schema": "vsg.diagnostics",
"schema_version": 1,
"complete": true,
"tool": {"name": "vsg", "version": "3.35.0"},
"source": {"name": "stdin"},
"rules": {
"architecture_003": {
"severity": {"name": "Error", "type": "error"},
"fixable": true,
"phase": 3,
"subphase": 1,
"configuration": {
"disable": false,
"fixable": true,
"phase": 3,
"severity": "Error"
},
"documentation": {
"rule": "https://vhdl-style-guide.readthedocs.io/en/latest/architecture_rules.html#architecture-003",
"configuration": null
}
}
},
"diagnostics": [
{
"rule": "architecture_003",
"location": {"start_line": 4, "end_line": 4},
"message": "Insert blank line above"
}
],
"errors": []
}
Required semantics
schemais the stable protocol identifier.schema_versionchanges only for incompatible semantic or required-field changes. New optional fields may be added without incrementing it.completeistrueonly when analysis finished anddiagnosticsis an authoritative result. It defaults totruefor compatibility with early version 1 producers that omitted the field.errorsis empty for a complete result. An incomplete result setscompletetofalse, leavesrulesanddiagnosticsempty, and supplies at least one object with a broadkind(analysis,protocol, orinternal) and human-readablemessage. Consumers must allow future kinds.- Consumers must reject unknown schema identifiers and unsupported versions.
tool.versionis the actual running VSG version, not a bridge constant.rulescontains exactly the distinct rules referenced bydiagnostics.- Rule keys and diagnostic rule references are exact VSG unique IDs.
- Severity
nameis the configured display name. Severitytypeis VSG's semantic type and is currentlyerrororwarning. configurationis the effective configuration after built-in, global, group, file, and rule-specific settings have been applied.fixablereports the effective rule property; it does not promise that a selected fix will change a stale or already-corrected buffer.- Finding lines are one-based and inclusive. Version 1 style findings deliberately have no column fields. Incomplete parser errors may carry their best available one-based line and column.
- Documentation values are absolute HTTPS URLs or
null. Built-in rule links are preferred. Local rules may have no link. - Diagnostics are sorted by start line and then rule ID. Rule object keys are emitted in deterministic order to keep fixtures and debugging stable.
- Empty results still emit the complete envelope with empty
rulesanddiagnosticsobjects/arrays.
An analysis failure uses the same protocol identity and version:
{
"schema": "vsg.diagnostics",
"schema_version": 1,
"complete": false,
"tool": {"name": "vsg", "version": "3.35.0"},
"source": {"name": "stdin"},
"rules": {},
"diagnostics": [],
"errors": [{
"kind": "syntax",
"message": "Unexpected token while parsing entity_declaration; expected `end`",
"location": {"line": 1, "column": 1}
}]
}
Consumer behavior
By default the bridge maps VSG error to LSP Warning and VSG warning to LSP
Information, keeping style findings distinct from code-breaking parser errors.
Strict diagnostic severity maps them to LSP Error and Warning respectively.
Information remains LSP Information in either mode. The bridge preserves the
configured name in diagnostic data and fails visibly on an unknown type instead
of assigning a default severity.
Unknown optional JSON fields are ignored. A declared unsupported schema or
schema version is a compatibility error and is reported prominently. Malformed
JSON, incomplete analysis, missing required fields, invalid line numbers,
dangling rule references, malformed URLs, or inconsistent metadata are
recoverable tool failures: the bridge warns, clears stale style findings and
correction actions, and remains available for the next document update. A
located syntax error is published as a non-fixable LSP error on the reported
line. If a structured incomplete analysis has no trustworthy location, the
bridge publishes one non-fixable analysis-failed error covering the document.
This error reports VSG's inability to analyze the input rather than asserting
that the input is invalid VHDL. Complete analysis restores normal style
diagnostics and correction actions. One bad response must never crash the
language server or corrupt results from a newer document version.
Correction granularity
Version 1 corrections are keyed by (document version, rule ID, line). A
single action may fix multiple violations from the same rule on the same line,
because VSG's existing selector cannot distinguish them further. The bridge
must not claim a character-precise correction.
The corrected VHDL remains the complete stdout document produced by VSG. The bridge should compute a line-block edit by removing common unchanged leading and trailing lines. If a trustworthy line-block edit cannot be computed, it may return a versioned full-document edit; it must never guess replacement text.
VSG documents that line numbers can move when multiple fixes are applied.
The version 1 interface therefore supports one rule-and-line correction at a
time, exposed by the bridge only with --experimental-rule-fix while its
editor behavior is evaluated.
Why version 1 uses line ranges
VSG's public diagnostic result identifies a source line, not a character span. Some internal rule indexes identify entries in a mutable token stream; they are not byte, Unicode scalar, or UTF-16 offsets into the submitted document. Fix phases can insert or remove tokens before later rules run. Some valid findings, such as missing blank lines, describe a position between source characters, while indentation and alignment rules can describe a group of tokens or lines.
The bridge would have to duplicate VSG parsing and phase behavior to guess more precise ranges, and those guesses could highlight or replace the wrong text. Line ranges are therefore the most precise generally valid contract. A future schema may carry optional VSG-produced source spans with an explicit coordinate encoding and source-version meaning; consumers must retain the line-range fallback.
Whole-document fix-all
The bridge offers a standard LSP source action with kind
source.fixAll.vsg. It sends the current in-memory document to the existing VSG
command without requiring a new VSG interface:
vsg --stdin --stdout --fix -fp 7 --no-failure
Existing VSG configuration arguments remain separate arguments and are added in
the same way as other bridge invocations. The action is explicit editor sugar
over VSG formatting; it does not run automatically on save unless the user
configures the editor to request it. The bridge must bind the result to the
document version, reject stale results, and return a versioned workspace edit.
If VSG cannot parse or fix the submitted stdin, it returns that input unchanged
so the operation is a no-op; it must never represent failure as empty corrected
text. The bridge therefore receives no destructive edit from a handled parse
failure.
It may use a safe line-block edit or fall back to a full-document replacement.
Correction menus must be cheap: advertise actions from validated in-memory
diagnostics, then invoke VSG only after the client executes the selected
server-owned command. The command applies the resulting versioned workspace
edit through workspace/applyEdit.
Formatting and correction actions are withheld whenever analysis of the current
document version is incomplete.
Experimental individual rule fix
Per-rule actions are exposed only when the bridge starts with:
vsg-bridge-ls --experimental-rule-fix
The runtime gate controls action exposure without changing the VSG protocol or
binary. Each action must be labelled experimental, carry a document version and
one (rule, line) selector, and retain all normal validation and stale-edit
checks. Opening the menu must not start VSG; selecting an action starts one VSG
process.
Experimental multi-rule line fix
An additional action may select every distinct fixable rule reported on a line
and invoke VSG once with the corresponding repeated --fix_rule selectors.
This action is disabled by default and is exposed only when the bridge starts
with:
vsg-bridge-ls --experimental-multi-rule-line-fix
A runtime option is preferred to a Cargo feature: users install one binary,
editors can opt in independently, and CI tests the same artifact that is
distributed. This option gates only grouped action exposure; protocol parsing
remains identical. Single-rule correction exposure is independently gated by
--experimental-rule-fix. The grouped action title and command data must label
the behavior experimental.
The action must use one VSG process so that VSG retains ownership of phase and rule ordering. It must not loop over stale original line numbers in the bridge. Before this gate can be removed, the planned corpus, property, and integration checks must pass and the promotion evidence must be recorded in the bridge documentation.
Documentation presentation
- Put the rule URL in LSP
Diagnostic.codeDescription.href. - Put rule metadata in
Diagnostic.dataso it survives into code-action requests. - Offer hover Markdown containing rule, message, configured severity, phase, fixability, effective configuration, and available links.
- When explicitly enabled by
--allow-browser-actionor layered bridge configuration, aShow VSG rule documentationaction may execute a server-owned command that requestswindow/showDocument. Do not advertise the command without both permission and client support.
Compatibility and ownership
VSG owns rule analysis, severity, fixability, effective configuration, documentation identity, and corrected text. The bridge owns JSON validation, UTF-16 LSP positions, document-version safety, user-facing actions, and edits.
No VSG submodule is needed. Runtime output from the installed VSG executable is the authority and cannot safely be replaced by a catalog generated from some other checkout.