vsg-bridge-ls/doc/architecture/vsg-interface.md

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

  • schema is the stable protocol identifier.
  • schema_version changes only for incompatible semantic or required-field changes. New optional fields may be added without incrementing it.
  • complete is true only when analysis finished and diagnostics is an authoritative result. It defaults to true for compatibility with early version 1 producers that omitted the field.
  • errors is empty for a complete result. An incomplete result sets complete to false, leaves rules and diagnostics empty, and supplies at least one object with a broad kind (analysis, protocol, or internal) and human-readable message. Consumers must allow future kinds.
  • Consumers must reject unknown schema identifiers and unsupported versions.
  • tool.version is the actual running VSG version, not a bridge constant.
  • rules contains exactly the distinct rules referenced by diagnostics.
  • Rule keys and diagnostic rule references are exact VSG unique IDs.
  • Severity name is the configured display name. Severity type is VSG's semantic type and is currently error or warning.
  • configuration is the effective configuration after built-in, global, group, file, and rule-specific settings have been applied.
  • fixable reports 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 rules and diagnostics objects/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.data so 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-action or layered bridge configuration, a Show VSG rule documentation action may execute a server-owned command that requests window/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.