Metadata-Version: 2.4
Name: vsg-rs
Version: 0.2.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Quality Assurance
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
License-File: THIRD_PARTY_LICENSES.md
Summary: A fast Rust-native VHDL formatter and style checker with VSG-compatible rules and configuration.
Keywords: vhdl,formatter,linter,vsg,fpga
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/ru551n/vsg-rs/tree/main/docs
Project-URL: Repository, https://github.com/ru551n/vsg-rs

# vsg-rs

A fast Rust-native VHDL formatter and style checker with VSG-compatible rules and configuration.

> **vsg-rs is an independent Rust implementation of a VHDL formatter and style checker that
> aims for compatibility with the rules and configuration of the VHDL Style Guide (VSG). It is not
> affiliated with, endorsed by, or maintained by the VHDL Style Guide project or its
> maintainers.**
>
> vsg-rs was inspired by the [VHDL Style Guide (VSG)](https://github.com/jeremiah-c-leary/vhdl-style-guide)
> project by Jeremiah Leary and contributors. vsg-rs contains no VSG code; VSG is used only as a
> behavioural reference.

**Status: beta.** Formatting is tested against a corpus of more than 11,000 real-world files.
192 VSG rules are implemented as lint rules with fixes (structure, identifier case, naming,
comments, `length_001`), and the other 779 layout rules are covered by the formatter's policy
(blank lines, alignment, keyword case, indentation). Expect layout changes before 1.0.

## Why

* **A real formatter.** Formatting is not "run the lint rules and apply their fixes". Source is
  parsed once into a lossless syntax tree and printed in one canonical layout, like rustfmt or
  Black. Running it twice changes nothing.
* **Long lines are folded, not just reported.** `length_001` becomes a formatter capability:
  calls, maps, aggregates, expressions, conditions, declarations and assignments fold at
  structural boundaries (see [docs/line-folding.md](docs/line-folding.md)).
* **Safe for format-on-save.** Every result is re-parsed and checked to contain exactly the same
  tokens and comments before it is used. Files with syntax errors are left untouched. In pipe
  mode, stdout carries nothing but the formatted source.
* **No fix phases.** No `--fix` runs that must be repeated until they converge, and no
  rule-order dependencies. Fixes that could change behaviour are only applied on request
  (`--unsafe-fixes`).
* **Fast.** Formatting a typical file from stdin takes a few milliseconds; parsing, formatting
  and verifying real-world VHDL runs at about 3.4 MB/s on one core, and files are processed in
  parallel ([performance](docs/performance.md)).

## Usage

```sh
pip install vsg-rs                     # Linux and Windows wheels, Python 3.10+ (or: uv tool install vsg-rs)
cargo install --path .                 # from source

vsg-rs fmt src/                        # format files in place
vsg-rs fmt --check src/                # CI: exit 1 if anything would change
vsg-rs fmt --diff src/foo.vhd          # show what would change
vsg-rs fmt --line-length 100 src/
cat foo.vhd | vsg-rs fmt --stdin-filename foo.vhd -   # editor integration
cat foo.vhd | vsg-rs fmt --range 10:24 -              # only lines 10 to 24

vsg-rs lint src/                       # report rule violations
vsg-rs check src/                      # CI: violations and unformatted files
vsg-rs check --output-format sarif src/ > vsg.sarif   # also json, junit, gitlab, syntastic, summary
vsg-rs fix src/                        # apply all safe fixes, then format
vsg-rs fix --unsafe-fixes --diff src/  # also fixes that may change behaviour (review them)
vsg-rs rules --all                     # every VSG rule and how vsg-rs handles it
```

Configuration uses the VSG format (YAML or JSON). It is read from `--config FILE`, or from the
nearest `vsg-rs.yaml` / `.vsg-rs.yaml` (or `.json`):

```yaml
rule:
  length_001:
    length: 100
  process_016:
    disable: true
  group:
    case::name:
      case: lower
file_rules:
  legacy/**/*.vhd:
    rule:
      length_001:
        disable: true
```

Formatting can be switched off for a region with `-- vsg-rs: fmt off` / `-- vsg-rs: fmt on`;
VSG's `-- vsg_off [rule ...]` / `-- vsg_on` comments suppress rules.

### Editor integration

Configure your editor to pipe the buffer through `vsg-rs fmt --stdin-filename <path> -` (add
`--range START:END` to format selected lines). On success (exit code 0) the buffer is replaced with stdout. On failure (exit code 2)
stdout is empty and stderr explains why; leave the buffer unchanged. See
[docs/editors.md](docs/editors.md) for VS Code, Neovim, Helix and Emacs setups.

## Documentation

* [Architecture](docs/architecture.md)
* [Editor integration](docs/editors.md) (pipe mode)
* [Formatting](docs/formatting.md), [line folding](docs/line-folding.md) and its
  [coverage matrix](docs/line-folding-coverage.md)
* [VHDL frontend](docs/vhdl-frontend.md) (why `vhdl_syntax`)
* [Compatibility with VSG](docs/compatibility.md) and [rule status](docs/rule-status.md)
* [Performance](docs/performance.md)
* [Releasing](docs/releasing.md) (Python package, platforms, release workflow)
* [VSG configuration model](docs/vsg-config.md), [VSG rule catalog](docs/vsg-rules.md)
* [Known VSG bugs](docs/upstream-bugs.md) and [limitations](docs/upstream-limitations.md) that
  vsg-rs is designed to avoid

## Development

```sh
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo run --release --example corpus -- --width 80 path/to/vhdl   # stability and overflow report
UPDATE_EXPECT=1 cargo test --test golden                           # re-bless golden files (review the diff)
```

## License

vsg-rs is licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
[MIT license](LICENSE-MIT), at your option. Third-party dependencies are listed in
[THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md). The VHDL parser, `vhdl_syntax`
from the rust_hdl project, is MPL-2.0 and is used as an unmodified dependency.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
vsg-rs, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.

