After the 219 → 0 curation pass that closed every Lost public
reason in jouleclaw-rs, the next concern is regression — every
new `pub fn` landing without a `///` doc would silently drift
the count back up. This workflow makes that impossible.
NEW BEHAVIOUR
scan_self.rs gains a `--fail-on-lost` flag that exits non-
zero if the public-surface Lost count is greater than zero.
Default behaviour (no flag) is unchanged — the example
still prints the report and returns 0 for ad-hoc local runs.
.github/workflows/jouleclaw-public-surface-documented.yml
runs `cargo run -q -p jouleclaw-brownfield --example
scan_self -- --fail-on-lost` on every PR + main push that
touches `jouleclaw/jouleclaw-rs/**`. Failure surfaces a
GitHub error annotation pointing at the fix:
Fix by adding a `///` doc comment above each flagged
`pub fn`, OR by downgrading to `pub(crate)` if it isn't
consumer-visible.
Run locally with:
cargo run -p jouleclaw-brownfield --example scan_self
Path-scoped so unrelated PRs (other open-standards crates,
docs, etc.) don't pay the build cost. Cached cargo registry
+ target so steady-state runs are fast.
Pinned to Rust 1.96 (the workspace rust-version) via
dtolnay/rust-toolchain.
DESIGN NOTES
- Same example serves humans (locally, no flag → readable
report) and CI (with flag → enforcement). No second
binary, no script duplication.
- The check is "public-surface-only Lost == 0", NOT
"all-functions Lost == 0". Internal helpers are
deliberately excluded per substrate doctrine — `///` on
every `pub(crate)` helper isn't load-bearing.
- Includes the workflow file itself in the path filter so
workflow edits trigger a self-test on the same PR.
WHAT THIS GUARANTEES
Public surface stays at zero Lost forever. Every PR adding
a new `pub fn` either ships with a doc or fails CI. No
drift back to 219.
cargo run --example scan_self -- --fail-on-lost: exits 0
locally on main.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
8135e999ea