vhdl-style-guide/DISCLOSURE.md

5.3 KiB

Authorship, LLM Use, and Safety Disclosure

This document describes the narrow stream-integration fork of VSG: how it was developed, where an LLM was used, what is tested, and which operations can affect source code. It does not make claims about the development process of the complete upstream project.

Authorship

The original VSG parser, rule library, fix engine, command-line application, and most of this repository predate the fork. They are the work of Jeremy C. Leary and upstream contributors. The fork maintainer chose the integration requirements, keeps the patch set deliberately narrow, and accepts releases.

The fork-specific standard-input and standard-output integration, machine-readable diagnostics, rule-scoped fix adapter, packaging automation, tests, and related documentation were developed or refined with an LLM coding assistant under maintainer direction. Development has been iterative, so this repository does not claim reliable line-by-line attribution between human and LLM-assisted work. The fork commits above the tracked upstream branch keep the integration changes reviewable as a separate patch series.

What the fork adds

The fork builds on VSG's existing --stdin and --no-failure options and adds a small command-line boundary around existing behavior:

  • --diagnostics_json emits a versioned diagnostic document;
  • --stdout emits corrected VHDL instead of writing it to a source file;
  • --fix_rule RULE:LINE adapts a selection to VSG's existing --fix_only mechanism; and
  • packaging and CI exercise the complete stream interface as an installed artifact.

The parser, rules, phase ordering, and correction engine remain VSG's. The fork does not add a second VHDL parser or formatter.

Diagnostic JSON and side effects

--diagnostics_json requires --stdin and is incompatible with fixing and other options that claim standard output. VSG parses the submitted text and runs its normal rules, then serializes the resulting findings and effective rule metadata. The JSON does not contain or execute replacement text and does not introduce a path that writes back to the submitted source.

In this mode, producing JSON cannot change the VHDL, its behavior, or its formatting. Output is always one valid JSON document: successful analysis is marked complete, while argument, configuration, parsing, or unexpected failures produce an incomplete envelope with empty findings and structured error metadata. Details may also go to standard error. The process does not use or contact an LLM at runtime.

This source-integrity statement is specifically about diagnostic mode. VSG still reads explicitly supplied configuration and local-rule files, and local rules are Python code that must be trusted. Operating-system logging, wrappers, or custom rules are outside this fork's boundary.

Fixing is intentionally different. With --stdin --fix --stdout, VSG returns corrected VHDL on standard output and does not write the input to a source file; a caller such as the bridge may choose to apply that output. If parsing or fixing cannot complete, this stream mode returns the original input unchanged; an empty or partial result is never presented as a correction. Existing VSG file workflows retain their upstream behavior, including any explicitly requested file changes.

What is tested

Focused fork tests cover:

  • required and conflicting option validation;
  • deterministic, versioned JSON and empty diagnostic collections;
  • effective severity, fixability, documentation metadata, and Unicode text;
  • invalid VHDL, invalid configuration, and unexpected failures with a valid incomplete JSON document, including parser locations when available;
  • rule selector parsing, validation, and deduplication;
  • selected rules on the same line and across correction phases;
  • corrections that insert lines; and
  • unchanged output when a selected rule is unknown.

CI also runs the upstream unit and style suites, builds both wheel and source distributions, and installs and smoke-tests the wheel through both pip and uv. The smoke tests exercise stdin/stdout formatting from the installed artifact.

The tests cover known cases; they are not formal verification. In particular, they do not prove VHDL semantic equivalence after formatting, cover every third-party local rule, or remove upstream parser limitations such as embedded PSL and VHDL 2019.

Risk by operation

Operation Source-change risk Main remaining risk
--stdin --diagnostics_json None by design A finding or its metadata may be incomplete or incorrect.
--stdin --stdout --fix Returns changed text by design Applying the output may introduce an unwanted formatting change.
--fix_rule Returns selected changes by design Correction phases can move later findings, making original line selections stale.
Existing file-based VSG commands Unchanged by the fork They retain the behavior and risks documented by upstream VSG.

The machine interface uses one-based line ranges because VSG does not provide generally valid character spans. Consumers must validate the schema and must not reinterpret internal token indexes as source columns.

For important or safety-critical HDL, keep work in version control, inspect corrected output, and run the normal simulation, synthesis, linting, and review process before accepting a change.