Pin Rust compatibility and publish coverage

This commit is contained in:
Dandaedre 2026-10-02 21:08:47 +02:00
parent 5bec60dfe4
commit 486cbf7e44
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
12 changed files with 1416 additions and 20 deletions

2
.cargo/config.toml Normal file
View File

@ -0,0 +1,2 @@
[resolver]
incompatible-rust-versions = "fallback"

8
.gitignore vendored
View File

@ -3,10 +3,7 @@
# will have compiled files and executables
debug/
target/
# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
Cargo.lock
coverage/
# These are backup files generated by rustfmt
**/*.rs.bk
@ -15,4 +12,5 @@ Cargo.lock
*.pdb
venv/
.cargo/
.cargo/*
!.cargo/config.toml

1037
Cargo.lock generated Normal file

File diff suppressed because it is too large Load Diff

View File

@ -3,6 +3,7 @@ name = "vsg_bridge_ls"
description = "A very featureless VSG to lsp bridge"
version = "0.1.0"
edition = "2021"
rust-version = "1.85.1"
categories =["developement-tools"]
license = "GPL-2.0"
keywords = ["lsp", "bridge"]
@ -11,17 +12,13 @@ authors = ["dandaedre"]
[dependencies]
anyhow = "1.0.93"
async-tungstenite = { version = "0.28.0", features = ["tokio", "tokio-runtime"] }
clap = { version = "4.5.21", features = ["derive"] }
once_cell = "1.20.2"
regex = "1.11.1"
serde_json = "1.0.133"
tokio = { version = "1.41.1", features = ["default", "io-std", "io-util", "macros", "rt-multi-thread", "tokio-macros"] }
tokio-macros = "2.4.0"
tokio-utils = "0.1.2"
tower-lsp = "0.20.0"
tracing-subscriber = "0.3.18"
ws_stream_tungstenite = { version = "0.14.0", features = ["tokio_io"] }
[profile.dev]
debug = 0

103
Jenkinsfile vendored
View File

@ -7,6 +7,8 @@ pipeline {
environment {
CARGO_TERM_COLOR = 'never'
RUST_BACKTRACE = '1'
MSRV = '1.85.1'
CARGO_LLVM_COV_VERSION = '0.9.0'
}
stages {
@ -36,13 +38,44 @@ pipeline {
rustup toolchain install stable \
--profile minimal \
--component rustfmt \
--component clippy
--component clippy \
--component llvm-tools-preview
rustup toolchain install "${MSRV}" \
--profile minimal
rustup default stable
echo
rustc --version
cargo --version
installed_llvm_cov=$(cargo llvm-cov --version 2>/dev/null || true)
if [ "${installed_llvm_cov}" != "cargo-llvm-cov ${CARGO_LLVM_COV_VERSION}" ]; then
cargo install cargo-llvm-cov \
--locked \
--version "${CARGO_LLVM_COV_VERSION}"
fi
'''
}
}
stage('MSRV') {
steps {
sh '''
set -eu
echo "Checking all targets with Rust ${MSRV}..."
cargo "+${MSRV}" check \
--locked \
--all-targets \
--all-features
cargo "+${MSRV}" test \
--locked \
--all-targets \
--all-features
'''
}
}
@ -70,6 +103,7 @@ pipeline {
echo "Running cargo check..."
cargo check \
--locked \
--all-targets \
--all-features
'''
@ -84,6 +118,7 @@ pipeline {
echo "Running tests..."
cargo test \
--locked \
--all-targets \
--all-features
'''
@ -98,8 +133,66 @@ pipeline {
echo "Running Clippy..."
cargo clippy \
--locked \
--all-targets \
--all-features
--all-features \
-- \
-D warnings
'''
}
}
stage('Coverage') {
steps {
sh '''
set -eu
cargo llvm-cov clean --workspace
cargo llvm-cov \
--locked \
--all-features \
--html \
--output-dir coverage
cargo llvm-cov report \
--json \
--summary-only \
--output-path coverage/summary.json
cargo llvm-cov report \
--lcov \
--output-path coverage/lcov.info
coverage_percent=$(cargo llvm-cov report --summary-only | awk '
$1 == "TOTAL" {
gsub(/%/, "", $10)
print $10
}
')
scripts/render-coverage-badge.sh \
"${coverage_percent}" \
coverage/coverage.svg
'''
archiveArtifacts(
allowEmptyArchive: false,
artifacts: 'coverage/**/*',
fingerprint: true
)
}
}
stage('Publish coverage') {
when {
allOf {
branch 'main'
expression {
return env.COVERAGE_PUBLISH_ROOT?.trim()
}
}
}
steps {
sh '''
set -eu
scripts/publish-coverage.sh "${COVERAGE_PUBLISH_ROOT}"
'''
}
}
@ -111,7 +204,7 @@ pipeline {
conclusion: 'SUCCESS',
name: 'Rust CI',
summary: 'vsg_bridge_ls passed CI.',
text: 'Formatting, cargo check, tests, and Clippy completed successfully.',
text: 'MSRV/stable checks, formatting, tests, Clippy, and coverage completed successfully.',
title: 'Build Successful'
)
@ -123,7 +216,7 @@ pipeline {
conclusion: 'FAILURE',
name: 'Rust CI',
summary: 'vsg_bridge_ls failed CI.',
text: 'Formatting, cargo check, tests, or Clippy failed. Check the Jenkins log.',
text: 'An MSRV/stable, formatting, test, Clippy, or coverage check failed. Check the Jenkins log.',
title: 'Build Failed'
)
@ -142,4 +235,4 @@ pipeline {
echo '⚠️ vsg_bridge_ls CI is unstable.'
}
}
}
}

View File

@ -1,5 +1,7 @@
# vsg_bridge_ls
[![coverage](https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/coverage.svg)](https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/html/)
`vsg_bridge_ls` reports [VSG](https://github.com/jeremiah-c-leary/vhdl-style-guide)
diagnostics through the Language Server Protocol (LSP). A complete setup needs
the companion VSG fork and this bridge.
@ -32,7 +34,8 @@ python -m pip install \
## 2. Install the bridge
```sh
cargo install --git https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls.git
cargo install --locked \
--git https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls.git
```
Activate the environment and verify both executables:
@ -74,6 +77,7 @@ buffer with the fork.
- [Installation alternatives and PATH troubleshooting](doc/installation.md)
- [Helix, Vim, and VSCodium setup](doc/editor-configuration.md)
- [Development and packaging](doc/development.md)
- [Dependency and CI hardening plan](doc/supply-chain-hardening.md)
The bridge is deliberately small. Contributions should preserve clean LSP
standard output and keep the VSG subprocess boundary explicit.

View File

@ -1,16 +1,76 @@
# Development and packaging
## Rust compatibility
The bridge supports Rust 1.85.1 and newer. Rust does not publish long-term
support toolchains; 1.85.1 was chosen as a conservative distribution anchor
because it is shipped by Debian 13 stable. `Cargo.toml` declares the MSRV,
`Cargo.lock` pins an MSRV-compatible graph, and Jenkins checks that graph with
both Rust 1.85.1 and current stable.
Future dependency updates must preserve this check or deliberately update the
declared MSRV, documentation, and Jenkins value together. Cargo's MSRV-aware
resolver is enabled in `.cargo/config.toml` to avoid selecting newer compatible
crate releases that require a newer compiler.
## Bridge checks
Run the same checks as Jenkins before submitting a bridge change:
Run the same core checks as Jenkins before submitting a bridge change:
```sh
cargo +1.85.1 check --locked --all-targets --all-features
cargo +1.85.1 test --locked --all-targets --all-features
cargo fmt --all -- --check
cargo check --all-targets --all-features
cargo test --all-targets --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo check --locked --all-targets --all-features
cargo test --locked --all-targets --all-features
cargo clippy --locked --all-targets --all-features -- -D warnings
```
## Coverage
Jenkins uses pinned `cargo-llvm-cov` 0.9.0 with the current stable toolchain.
To generate the same reports locally, install the tool and `llvm-tools-preview`,
then run:
```sh
rustup component add llvm-tools-preview
cargo install cargo-llvm-cov --locked --version 0.9.0
cargo llvm-cov clean --workspace
cargo llvm-cov --locked --all-features --html --output-dir coverage
cargo llvm-cov report --json --summary-only --output-path coverage/summary.json
cargo llvm-cov report --lcov --output-path coverage/lcov.info
scripts/render-coverage-badge.sh \
"$(cargo llvm-cov report --summary-only | awk '$1 == "TOTAL" { gsub(/%/, "", $10); print $10 }')" \
coverage/coverage.svg
```
CI archives the HTML report, LCOV data, JSON summary, and SVG badge. There is no
coverage floor yet because the initial bridge has no meaningful automated test
suite. Add a ratcheted line-coverage floor once behavior tests exist; never add
brittle tests merely to improve the percentage.
For public reports, configure the Jenkins job or node environment variable
`COVERAGE_PUBLISH_ROOT` to the absolute path of the mounted coverage directory.
Successful `main` builds publish immutable artifacts under:
```text
MadGobblins/vsg-bridge-ls/<full-commit-id>/
```
The `main` symlink is updated only after the complete commit directory has been
moved into place. The README badge and report link use:
```text
https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/coverage.svg
https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/html/
```
The web server should receive this mount read-only, disable directory listing,
serve SVG with a restrictive content security policy, and apply long immutable
cache headers only to commit-addressed paths. Retention may remove old commit
directories, but should preserve tagged releases and every commit referenced by
the stable alias.
## Companion VSG fork
The fork keeps its stream-support patch small and rebases it onto upstream

View File

@ -58,13 +58,17 @@ python -m pip install \
Install the released branch directly from Gitea:
```sh
cargo install --git https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls.git
cargo install --locked \
--git https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls.git
```
For development, clone this repository and use `cargo build`. Cargo normally
places installed binaries in `~/.cargo/bin`; that directory must also be in the
editor's PATH.
The bridge supports Rust 1.85.1 and newer. `--locked` uses the dependency
versions tested by CI and is required to preserve that compatibility guarantee.
## PATH and virtual environments
Activating `.venv` before launching the editor is the simplest setup because

View File

@ -0,0 +1,73 @@
# Dependency and CI hardening plan
No single tool can prove that a dependency is safe. Use several independent
controls: reproducible resolution, known-vulnerability scanning, dependency
policy, human review, and an isolated build environment.
## Available controls
| Control | What it adds | Advantages | Costs and limits |
| --- | --- | --- | --- |
| Committed `Cargo.lock` and `--locked` | Exact versions and crates.io checksums | Fast, built into Cargo, reproducible, and prevents silent dependency drift | A checksum proves consistency, not that the first accepted crate was trustworthy; updates are manual |
| Pinned CI tools | Exact versions of coverage and security tools | Prevents surprise CI changes and makes failures reproducible | Pins become stale and the initial installation still trusts crates.io and its transitive graph |
| `cargo audit` | RustSec advisory and yanked-crate checks | Low setup cost and good signal for known vulnerabilities | Cannot detect unknown or deliberately malicious code; advisory updates require network access |
| `cargo deny` | License, source, duplicate, ban, advisory, and wildcard policy | One reviewable policy file; blocks unknown registries and Git sources | Needs license decisions and exception maintenance; duplicate versions are not automatically vulnerabilities |
| `cargo vet` | Human or imported audits for dependency code | Best direct answer to whether trusted reviewers inspected a crate | Highest maintenance cost; bootstrap requires imports, reviews, or explicit exemptions, and every update can need new evidence |
| Vendoring with `cargo vendor` | Repository or internal artifact copy of all crate sources | Offline builds, strong availability, and an inspectable frozen source set | Large diffs/storage, frequent refresh work, and vendoring malicious code does not make it safe |
| Private registry or registry proxy | Central allow-list, cache, and availability control | Useful across many projects; can quarantine versions and reduce external CI access | Becomes critical infrastructure and a concentrated trust/availability dependency |
| Ephemeral, unprivileged CI | Limits damage from build scripts and proc macros | Contains compromised build-time code and protects other jobs | Requires worker isolation; shared Cargo caches can reintroduce cross-job state |
| Network-denied build phase | Stops dependencies from calling external services during compilation/tests | Strong containment after sources and advisories are fetched | Requires a separate fetch phase and can expose packages that incorrectly depend on network access |
| Secretless pull-request jobs | Keeps tokens away from untrusted changes | Prevents straightforward credential theft through modified CI scripts | Publishing and deployment need a separate trusted-branch job or protected stage |
| SBOM and `cargo auditable` | Records the dependency graph in artifacts | Improves incident response and deployed-binary inventory | Primarily detective; it does not prevent compromise |
| Automated update proposals | Keeps dependencies and CI tools reviewably current | Small, regular updates are easier to review and audit | Notification noise and unsafe auto-merge rules can reduce review quality |
| Signed releases and provenance attestations | Connects published binaries to a reviewed build | Helps consumers verify origin and supports incident investigation | Key management and reproducible release infrastructure add substantial complexity |
## Recommended rollout
### Phase 1: reproducible baseline
1. Keep `Cargo.lock` committed because this repository builds an executable.
2. Require `--locked` in CI, installation documentation, and release builds.
3. Declare Rust 1.85.1 in `Cargo.toml` and test both that exact toolchain and
current stable.
4. Pin third-party CI tool versions. Review and update them deliberately.
These controls are implemented now.
The initial pass also removes four direct dependencies that Cargo reports or
source inspection confirms are unused; the safest dependency is one the program
does not need.
### Phase 2: policy gates
1. Add pinned `cargo-audit` and fail on RustSec findings and yanked packages.
2. Add `cargo-deny` with explicit allowed licenses, crates.io as the only
registry, unknown Git sources denied, wildcards denied, and duplicate
versions reported for review.
3. Permit exceptions only with a reason, an owner, and a removal condition.
4. Run advisory refresh in a network-enabled stage, then run compilation and
tests without outbound network access where the Jenkins worker supports it.
This is the best next cost/security tradeoff for this small project.
### Phase 3: isolate and attest releases
1. Run untrusted branches without credentials on disposable workers with
read-only base images and per-job Cargo directories.
2. Move package publication, coverage publication, tagging, and signing to a
protected trusted-branch job that consumes already-tested source revisions.
3. Generate an SBOM and build releases with `cargo auditable`.
4. Sign release checksums and publish provenance that records the commit,
toolchain, lockfile, and Jenkins build.
### Phase 4: stronger dependency trust when justified
Adopt `cargo vet` if the project becomes widely distributed or handles a more
sensitive boundary. Start with carefully selected audit imports, record every
exemption honestly, and require review of dependency diffs. Consider a private
registry proxy or vendoring if builds must continue without crates.io or policy
requires centralized dependency admission.
Do not begin with `cargo vet` or full vendoring for this bridge: their ongoing
review cost is disproportionate until the basic audit, policy, isolation, and
test gates are healthy.

63
scripts/publish-coverage.sh Executable file
View File

@ -0,0 +1,63 @@
#!/bin/sh
set -eu
usage() {
echo "usage: $0 <coverage-publication-root>" >&2
exit 2
}
[ "$#" -eq 1 ] || usage
publication_root=$1
case "$publication_root" in
/*) ;;
*)
echo "coverage publication root must be an absolute path: $publication_root" >&2
exit 2
;;
esac
if [ ! -d "$publication_root" ] || [ ! -w "$publication_root" ]; then
echo "coverage publication root is not a writable directory: $publication_root" >&2
exit 2
fi
for artifact in coverage/coverage.svg coverage/lcov.info coverage/summary.json coverage/html/index.html; do
if [ ! -f "$artifact" ]; then
echo "required coverage artifact is missing: $artifact" >&2
exit 2
fi
done
commit=$(git rev-parse --verify HEAD)
case "$commit" in
*[!0-9a-f]*|'')
echo "Git returned an invalid commit identifier: $commit" >&2
exit 2
;;
esac
project_root="$publication_root/MadGobblins/vsg-bridge-ls"
destination="$project_root/$commit"
mkdir -p -- "$project_root"
if [ -e "$destination" ]; then
if cmp -s coverage/summary.json "$destination/summary.json"; then
echo "coverage for $commit is already published"
else
echo "refusing to overwrite different coverage for immutable commit $commit" >&2
exit 1
fi
else
staging=$(mktemp -d "$project_root/.publish.XXXXXX")
trap 'rm -rf -- "$staging"' EXIT HUP INT TERM
cp -R -- coverage/. "$staging/"
mv -- "$staging" "$destination"
trap - EXIT HUP INT TERM
fi
latest_link="$project_root/.main.$$"
ln -s -- "$commit" "$latest_link"
mv -f -- "$latest_link" "$project_root/main"
echo "published coverage for $commit to $destination"

View File

@ -0,0 +1,64 @@
#!/bin/sh
set -eu
usage() {
echo "usage: $0 <line-coverage-percent> <output.svg>" >&2
exit 2
}
[ "$#" -eq 2 ] || usage
percent=$1
output=$2
if ! awk -v value="$percent" 'BEGIN {
valid = value ~ /^[0-9]+([.][0-9]+)?$/ && value >= 0 && value <= 100
exit(valid ? 0 : 1)
}'; then
echo "coverage percentage must be a number from 0 through 100: $percent" >&2
exit 2
fi
rounded=$(awk -v value="$percent" 'BEGIN { printf "%.0f", value }')
if [ "$rounded" -ge 90 ]; then
color='#4c1'
elif [ "$rounded" -ge 70 ]; then
color='#dfb317'
else
color='#e05d44'
fi
output_dir=${output%/*}
if [ "$output_dir" != "$output" ]; then
mkdir -p -- "$output_dir"
fi
temporary="${output}.tmp.$$"
trap 'rm -f -- "$temporary"' EXIT HUP INT TERM
sed \
-e "s/@PERCENT@/${rounded}/g" \
-e "s/@COLOR@/${color}/g" \
>"$temporary" <<'EOF'
<svg xmlns="http://www.w3.org/2000/svg" width="112" height="20" role="img" aria-label="coverage: @PERCENT@%">
<title>coverage: @PERCENT@%</title>
<linearGradient id="s" x2="0" y2="100%">
<stop offset="0" stop-color="#fff" stop-opacity=".7"/>
<stop offset=".1" stop-color="#aaa" stop-opacity=".1"/>
<stop offset=".9" stop-opacity=".3"/>
<stop offset="1" stop-opacity=".5"/>
</linearGradient>
<clipPath id="r"><rect width="112" height="20" rx="3"/></clipPath>
<g clip-path="url(#r)">
<rect width="75" height="20" fill="#555"/>
<rect x="75" width="37" height="20" fill="@COLOR@"/>
<rect width="112" height="20" fill="url(#s)"/>
</g>
<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
<text x="37.5" y="15">coverage</text>
<text x="93.5" y="15">@PERCENT@%</text>
</g>
</svg>
EOF
mv -- "$temporary" "$output"
trap - EXIT HUP INT TERM

View File

@ -35,6 +35,7 @@ struct Args {
configuration: Vec<String>,
}
/// Language-server state and arguments used for each VSG invocation.
#[allow(dead_code)]
#[derive(Debug)]
struct Backend {