Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ on:

jobs:
check:
name: fmt · clippy · test
name: fmt · clippy · doc · test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
Expand All @@ -28,5 +28,13 @@ jobs:
- name: Clippy
run: cargo clippy --workspace --all-targets -- -D warnings

# Rustdoc warnings (broken intra-doc links) are build failures here too.
# Missing `# Errors` sections are caught by the Clippy step above, through
# the denied `missing_errors_doc` lint. `--lib` keeps
# the doc set to the two library APIs and dodges the known output-filename
# collision between the `spdr` lib and the `spdr` binary (cargo#6313).
- name: Docs
run: RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --lib

- name: Test
run: cargo test --workspace
51 changes: 51 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,57 @@ All notable changes to this project are documented here. The format is based on
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

Quality and documentation pass over the shipped surface. No decoded-output
change: every test and snapshot passes unchanged. The public API gains `const`
on six accessors, which is additive and therefore a semver commitment:
removing `const` later would be breaking.

### Added

- `const` on six public accessors: `Finding::severity`, `Finding::code`,
`SpdImage::is_empty`, `CasLatencies::contains` and `Timings::base_data_rate_mt_s`
in `spdr`, plus `DecodeResults::all_decoded` in `spdr-cli`.
- Regression tests for the two saturation guards and the supported-CAS bit
domain, so the silent-narrowing fix below cannot come back unnoticed. The
two saturation tests were confirmed to fail against the previous `as` cast
(they reported a wrapped `CL5` instead of a saturated one). The bit-domain
test is a characterization test: the base arithmetic was already correct, so
it pins the behaviour rather than catching a regression.
- 31 pure decoders and accessors marked `const fn` (27 in `spdr`, 4 in
`spdr-cli`). All of them are crate-internal helpers or accessors; no public
`decode_*` entry point is `const`, so a downstream user still cannot decode
an SPD image at compile time.
- An explicit `# Errors` section on every public `Result`-returning function,
and a curated set of `clippy::pedantic` lints (silent-cast, doc, and argument
idioms) denied at the workspace level, so the classes of issue fixed here
cannot silently regress. CI now also builds rustdoc with `-D warnings`.

### Fixed

- The documented reason the fuzz harness "cannot link on Windows" was wrong: it
does compile and link under MSVC, then fails to load on the
`clang_rt.asan_dynamic-x86_64.dll` import. Corrected in
`spdr/fuzz/Cargo.toml` and the Phase 6 report, with the attempt recorded in
the deep-run ledger instead of left silently blank.
- Rustdoc parsed bit-range notation in doc comments (`bits [7:5]`) as
intra-doc links, emitting 21 unresolved-link warnings on the base `6b0d2d5`.
The notation is now written as a code span, which rustdoc does not link, and
renders exactly as written. The rendered documentation was correct before and
after; the defect was the warnings, which the new doc gate turns into a build
failure.
- The two internal CAS-latency derivations (the linter's supported-set check and
the vendor-profile rated CL) narrowed `u32` quotients to `u16` with an
unchecked `as`. The quotient always fit for decoded SPD bytes, but the
narrowing is now explicit and saturating instead of wrapping for out-of-range
hand-built values.
- The supported-CAS mask arithmetic and the reference-raw-card `Display` used
unchecked narrowing casts on a constant bit count and on array-length
indexing; both now compute in one integer domain, with a compile-time check
tying the mask bit count to its byte count.
- A rustdoc warning: a public doc link to a private item in `spdr-cli`.

## [0.1.1] - 2026-09-16

Metadata only. No code, no API change, no behaviour change from 0.1.0.
Expand Down
16 changes: 16 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,19 @@ unsafe_code = "forbid"

[workspace.lints.clippy]
all = "deny"
# A curated set from `clippy::pedantic`, each entry naming a class this pass
# found a real issue of: silent `as` narrowing, undocumented `Result` errors,
# undocumented identifiers in docs, `&Option<T>` arguments, needless
# pass-by-value. Kept curated rather than a blanket `pedantic` so a future
# upstream pedantic lint cannot break CI on a toolchain bump. `ref_option` is
# not newer than the MSRV: clippy 1.85.1 reports it as implied by `pedantic`,
# so the 1.85 toolchain resolves it. `bool_to_int_with_if` was dropped: it is a
# style lint that forbids `if ok { 0 } else { 1 }` and asks for
# `i32::from(!ok)` instead, so its only effect here was to force a less
# readable exit-code expression.
cast_possible_truncation = "deny"
doc_markdown = "deny"
missing_errors_doc = "deny"
needless_pass_by_value = "deny"
ref_option = "deny"
trivially_copy_pass_by_ref = "deny"
48 changes: 42 additions & 6 deletions docs/implementations/2026-06-05-phase-6-robustness.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,9 @@ Two tools, split by where they can run:
ordinary `#[test]`s and ride into the existing `cargo test` job.
- **cargo-fuzz** is committed as a harness but is **not built or run here**.
libFuzzer needs a clang/LLVM toolchain (Linux or WSL) that Windows MSVC does
not provide, so the fuzz crate cannot link on this machine. It is scaffolded,
rustfmt-clean, and ready for Mert to run on Linux. No fuzz result is claimed.
not provide, so the fuzz crate cannot link on this machine (corrected
2026-10-16: see the addendum below). It is scaffolded, rustfmt-clean, and
ready for Mert to run on Linux. No fuzz result is claimed.

## What Changed

Expand Down Expand Up @@ -123,9 +124,10 @@ capturing the shrunk input, never a weakening of the property.
- **proptest in the gate, cargo-fuzz committed-but-not-run.** The split follows
what each tool needs. proptest is pure Rust and runs anywhere `cargo test`
does, so it is the always-on regression guard. libFuzzer needs clang/LLVM and
does not link under Windows MSVC, so the fuzz harness is scaffolded and
rustfmt-clean but deliberately not built here. The report states the fuzz crate
was not run rather than implying a fuzz result.
does not link under Windows MSVC (corrected 2026-10-16: see the addendum
below), so the fuzz harness is scaffolded and rustfmt-clean but deliberately
not built here. The report states the fuzz crate was not run rather than
implying a fuzz result.
- **A stronger assertion only where the space is finite.** The two proptest
properties assert no-panic only, because arbitrary and mutated bytes legitimately
produce `UnknownEnum` and `NonAscii`, which are correct outcomes, not failures.
Expand Down Expand Up @@ -167,7 +169,8 @@ Phase 1 through 5 unit, integration, and snapshot suites are untouched and green
### Fuzzing (Linux / WSL, run manually by Mert)

The fuzz crate is **not built or run on Windows**: libFuzzer cannot link under
MSVC. On a Linux or WSL host with a nightly toolchain and `cargo-fuzz` installed
MSVC (corrected 2026-10-16: see the addendum below). On a Linux or WSL host
with a nightly toolchain and `cargo-fuzz` installed
(`cargo install cargo-fuzz`), from the `spdr/` crate directory:

```
Expand All @@ -191,6 +194,39 @@ fixture's decode left unchanged.
| --- | --- | --- | --- | --- | --- |
| _pending_ | _pending_ | `cargo +nightly fuzz run decode_all -- -max_total_time=<s>` | _pending_ | _pending_ | _pending_ |

Attempted and recorded so the empty row above is not mistaken for an oversight:

| Date | Host | Command | Result |
| --- | --- | --- | --- |
| 2026-10-16 | Windows 11 x86_64, MSVC + Scoop LLVM 23 (run by `danalec`, the PR #1 author) | `cargo +nightly fuzz run decode_all -- -max_total_time=45` | Build and link succeed; the binary then exits `STATUS_DLL_NOT_FOUND` (0xC0000135) on the missing `clang_rt.asan_dynamic-x86_64.dll`, `STATUS_ENTRYPOINT_NOT_FOUND` (0xC0000139) with LLVM's runtime on `PATH`, and `CC=clang CXX=clang++` fails to link (LNK1120). Zero executions, so it earns no fuzz result. |

The same date's Windows substitute for a deep run is the proptest surface at
raised case counts, which passes on that host: from `spdr/`,
`PROPTEST_CASES=100000 cargo test --release --test robustness` (both properties
plus the exhaustive truncation test; 3 passed in 1.17 s on 2026-10-16). That is
still property-testing, not fuzzing, and the README wording stays accordingly.

## Addendum · 2026-10-16 · the fuzz harness on Windows, measured

The June rationale above says the fuzz crate "cannot link on this machine".
That was wrong. The correction is recorded here, dated, rather than rewritten
into the June text.

Measured on Windows 11 x86_64 with MSVC and Scoop LLVM 23, by `danalec` (the
author of PR #1): `cargo +nightly fuzz build decode_all` **does compile and
link**. The failure comes one step later, at load time.

| Variant | Outcome |
| --- | --- |
| Default (MSVC) | `STATUS_DLL_NOT_FOUND` (0xC0000135), on the missing `clang_rt.asan_dynamic-x86_64.dll` import |
| LLVM's runtime on `PATH` | `STATUS_ENTRYPOINT_NOT_FOUND` (0xC0000139) |
| `CC=clang CXX=clang++` | fails to link instead: LNK1120, unresolved external |

Zero executions, so this earns no fuzz result. The harness is scaffolded,
rustfmt-clean, and ready for Mert to run on Linux, where the deep run is still
owed. The README keeps saying "property-tested, not fuzzed" until a recorded
deep run lands.

Only after a recorded deep run with no crash does the README earn the word
"fuzzed" as a completed claim.

Expand Down
153 changes: 153 additions & 0 deletions docs/implementations/2026-10-25-narrowing-const-and-doc-gates.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
# Quality pass · narrowing, `const`, and the doc gate

A behaviour-preserving pass over the shipped surface, dated 2026-10-25 and
reviewed upstream in PR #1. No decoded output changed and every golden snapshot
passes byte for byte. Three things are worth recording here because each is
meaningful on its own: a CI gate that did not exist, a workspace lint policy,
and a numeric-behaviour change.

Every number quoted here is traced in `docs/numerical-claims.md`.

## Problem / Motivation

The core crate is `#![forbid(unsafe_code)]` and never panics, so its
interesting failure mode is not a crash but a **wrong value**. Two failure
classes were open:

1. **Silent narrowing.** A wider integer was narrowed to a narrower one with an
unchecked `as`. For decoded bytes every such quotient fits, so the casts
were safe in practice and fragile in principle: the invariant lived in a
comment instead of in the code, and a hand-built out-of-range value could
wrap to a plausible-looking number.
2. **Invisible doc breakage.** `cargo doc` was not run anywhere, so rustdoc
warnings could not fail a build. On the base `6b0d2d5` the doc build emits
22 warnings: 21 unresolved bit-range links in `spdr` and one public doc link
to a private item in `spdr-cli`.

## What Changed

### The CI gate

CI now builds the documentation with warnings as errors:

```yaml
- name: Docs
run: RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --lib
```

`--lib` keeps the doc set to the two library APIs and dodges the known
output-filename collision between the `spdr` library and the `spdr` binary
(cargo#6313).

### The workspace lint policy

`[workspace.lints.clippy]` denies a curated set from `clippy::pedantic`:
`cast_possible_truncation`, `missing_errors_doc`, `doc_markdown`,
`ref_option`, `needless_pass_by_value` and `trivially_copy_pass_by_ref`.
Curated rather than blanket, so that a future upstream pedantic lint cannot
break CI on a toolchain bump. `bool_to_int_with_if` was dropped from the set
during this pass; see below.

Two facts about that set were measured rather than assumed, and both corrected
claims made earlier in the review:

- `ref_option` is **not** newer than the MSRV. Clippy 1.85.1 reports it as
implied by `clippy::pedantic`, and an invented lint name on the same
toolchain gives `error[E0602]: unknown lint`, so the name is resolved rather
than ignored.
- `bool_to_int_with_if` fires on the *readable* branch form,
`if ok { 0 } else { 1 }`, and asks for `i32::from(!ok)` instead. It is a
style guard with no bearing on a wrong value, and its only effect here was
to force a less readable exit-code expression, so it was dropped from the
workspace deny list and the branch form kept.

### The numeric-behaviour change

Two CAS-latency derivations narrowed a `u32` quotient to `u16`. They now
narrow explicitly and saturate, so an out-of-range hand-built value cannot
wrap. The wrap case was a plausible latency: 65541 cycles came out as CL5,
which would have been reported as a real value.

The rated-CL derivation computes its round-to-nearest in `u64` rather than in
`u32`, so the rounding stays exact across the whole `u32` input range instead
of saturating the add and rounding down. Only the final narrowing to `u16`
saturates.

The supported-CAS mask arithmetic now computes its bit index in a single
integer domain, with a compile-time assertion tying the bit count to the byte
count it derives from. The reference-raw-card `Display` no longer casts the
alphabet length or the array indices.

### `const` and the public API

31 pure decoders and accessors are now `const fn` (27 in `spdr`, 4 in
`spdr-cli`). Every one of them is a crate-internal helper or an accessor: no
public `decode_*` entry point is `const`, so a downstream user still cannot
decode an SPD image at compile time.

Six public items did gain `const`, which is additive and therefore a semver
commitment: `Finding::severity`, `Finding::code`, `SpdImage::is_empty`,
`CasLatencies::contains` and `Timings::base_data_rate_mt_s` in `spdr`, plus
`DecodeResults::all_decoded` in `spdr-cli`. Removing `const` later would be
breaking.

Two crate-internal helpers had their visibility widened from `pub(crate)` to
`pub` during the pass. That was reverted: the compiler enforced the boundary,
a comment does not, and a future `pub use identity::*` would otherwise export
them silently. `const` was kept.

### Documentation completeness

Every public `Result`-returning function has an explicit `# Errors` section,
and identifiers in prose are backticked. Bit-range notation in doc comments
is written as a code span (`[7:5]`) rather than an escape, which rustdoc does
not turn into an intra-doc link and which reads cleanly in a crate whose source
is meant to be the open reference.

## Design Decisions

- **Curated lints, not blanket `pedantic`.** A blanket set means any new
upstream lint breaks CI on a toolchain bump, which is a maintenance tax the
project does not need. The curated set names the classes this pass actually
found.
- **Saturation, not wrapping.** A narrow cast that saturates is wrong on
out-of-range input; a narrow cast that wraps is wrong *and* plausible. When
the value cannot fit, reporting the maximum is the honest answer.
- **`u64` for the intermediate.** Widening the add and the divide costs
nothing on a `no_std` target and removes a rounding error that only shows up
near the top of the `u32` range.
- **The bit-domain test is a characterization test.** The base arithmetic was
already correct, so the test pins the behaviour rather than catching a
regression. The two saturation tests are genuine regression tests: both were
confirmed to fail against the previous `as` cast.
- **The README wording is unchanged.** It still says *property-tested, not
fuzzed*. The deep run is still owed on a Linux or WSL host; on Windows the
harness never reached a single execution. The on-box substitute is
`PROPTEST_CASES=100000 cargo test --release --test robustness`, which is
property-testing, not fuzzing.

## Verification

- `cargo fmt --check` · clean.
- `cargo clippy --workspace --all-targets -- -D warnings` · clean.
- `cargo clippy --workspace --all-targets -- -W clippy::pedantic` · one
warning: `bool_to_int_with_if` on the restored `if ok { 0 } else { 1 }` exit
code. The lint is not in the deny set and the CI gate does not enable blanket
`pedantic`, so the `-D warnings` gate stays clean. Measured on Windows and
Linux; traced in `docs/numerical-claims.md`. The zero-warning result belongs
to the pre-review head, where the exit code was `i32::from(!ok)`.
- `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --lib` · clean.
- `cargo build -p spdr` · clean, the existing `no_std` guard.
- `cargo test --workspace` · the full suite passing.
- MSRV 1.85.1: `cargo build -p spdr`, the clippy gate, and the full test suite
all clean.

The rendered documentation was correct before this pass and is correct after it.
What changed is that the warnings are gone and the build now fails on them.

## Related Docs

- `docs/numerical-claims.md` · every number quoted above, with its source.
- `docs/implementations/2026-06-05-phase-6-robustness.md` · the fuzz harness
and its measured Windows failure mode, with the 2026-10-16 addendum.
- `CHANGELOG.md` · the user-facing summary of the same change.
Loading
Loading