Conversation
Adds `zig build doctest` (backed by tools/doctest.sh) that: - Diffs the README Quickstart code block against examples/quickstart.zig byte-for-byte, so README<->code drift fails the build. - Runs the compiled quickstart binary and asserts the documented `wire: N bytes` output line. - Verifies the README's documented build steps (test, bench, example-echo) actually exist in `zig build --help`. Vendors the README Quickstart verbatim into examples/quickstart.zig with a header explaining the contract. README and vendored example agreed on first run — no drift to report. First-pass scope: one code block locked in, five checks. Follow-ups can extend the doc-test surface to the wire-format table, the API signature blocks, and the bench output schema. Pattern lifted from zig-cobs (d29a51a).
Prior v1.0 + "production-grade hygiene milestone" framing was a Type-I
error class. Two independent reasons it doesn't fit:
1. Zig itself is on 0.16, not 1.0. No Zig library can claim API
stability beyond "stable on Zig 0.16 today" until the language
itself ships 1.0.
2. Zero production deployment, soak time, or incident history.
Hygiene-milestone shipping (LICENSE / SECURITY / CI / CODE_OF_CONDUCT
/ dependabot / CODEOWNERS) is real, but it's NOT sufficient for
"production-grade."
This commit adds:
- STATUS.md with per-component proof-vocabulary index covering
buildPacket/parsePacket, encode/decode, CRC32 trailer, COBS wrap,
the 6-test fuzz harness (10k+100k+bit-corruption+truncation+
version-rejection+length-tampering), throughput (compiled-only;
no committed RESULTS.md yet), README/code drift, and the CI
matrix; plus 4 explicit gates (G1 hardware-verified throughput +
a real bench/RESULTS.md, G2 soak time, G3 independent protocol/
security review, G4 Zig 1.0) all marked NOT YET CLOSED.
- CHANGELOG Unreleased "Honesty correction 2026-05-15" entry naming
the prior over-claim and pinning the proof vocabulary going forward.
v1.x git tag is honored for changelog continuity, but every reader
should treat this repo as pre-1.0 in semver spirit until G4 + at least
one of G1/G2/G3 close. Same correction is being applied fleet-wide.
Adopts the zig-cobs v1.2.0 coverage-driver pattern. Closes the Wave-4 fleet-wide gap "we cite test counts without naming what % of code those tests actually exercise" for zig-frame-protocol. Measured: 100.00% (48/48) line coverage on src/root.zig via kcov against a dedicated `coverage-driver` executable that exercises every public function (packetLen, maxEncodedLen, buildPacket, encodePacket, encode, parsePacket, decode) and every public error variant (PayloadTooLarge, BufferTooSmall, Truncated, InvalidEncoding, ChecksumMismatch, UnsupportedVersion). What changes: - examples/coverage_driver.zig (new) — single-binary driver - tools/coverage.sh (new) — `bash tools/coverage.sh` wrapper that builds, runs kcov, prints %, fails on <80% - build.zig — new `coverage-driver` step installs the exe - .github/workflows/ci.yml — new `line-coverage (kcov)` job runs on every push and uploads kcov HTML as a CI artifact - README.md — evidence vocabulary now names `coverage-measured` with the 48/48 line count - CHANGELOG.md — v0.2.0 entry - build.zig.zon — version 1.0.0 → 0.2.0 (per the honesty correction doctrine: drop the premature v1.x tag); paths expanded Verified locally: `bash tools/coverage.sh` prints "src/root.zig line coverage: 100.00% (48/48)". `zig build test --summary all` still green. Why a coverage-driver instead of `zig test`: the Zig 0.16 test runner's debug-info layout does not surface line-coverage to kcov through the nixpkgs kcov build (compiled without libbfd-dev). A plain executable has standard ELF+DWARF and kcov captures it cleanly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adopts the zig-cobs v1.2.0 coverage-driver pattern. Closes the Wave-4 fleet-wide gap "we cite test counts without naming what % of code those tests actually exercise" for zig-frame-protocol.
Measured: 100.00% (48/48) line coverage on
src/root.zigvia kcov against a dedicatedcoverage-driverexecutable.Changes
examples/coverage_driver.zig— single-binary driver covering every public function + every error variant.tools/coverage.sh— wrapper that builds + runs kcov + prints % + fails on <80%..github/workflows/ci.yml— newline-coverage (kcov)job; HTML uploaded as CI artifact.README.md— evidence vocabulary now namescoverage-measured(48/48).CHANGELOG.md— v0.2.0 entry.build.zig— newcoverage-driverstep.build.zig.zon— version 1.0.0 → 0.2.0 (per the no-premature-production-claims doctrine).Why a coverage-driver instead of
zig testZig 0.16 test-runner debug-info layout doesn't surface line-coverage to kcov through the nixpkgs build (no libbfd-dev). Plain exe with standard ELF+DWARF works cleanly.
Test plan
zig build test --summary allpasses.bash tools/coverage.sh→ 100.00%.