release: 0.2.0 — mdBook contract parity for the build path - #28
Conversation
Minor, not major, per the Phase 5 validation decision: the build path is
correct, tested and validated against a real 129-file book, but
{{#include}} is deliberately absent and `serve` has no test coverage, so
"major" would claim a completeness that is not there.
Adds the verification and validation reports, and states the {{#include}}
limitation in the README rather than leaving migrating users to discover it.
📊 Performance Benchmark Results
Raw Results{
"timestamp": "2026-08-11T18:35:06+00:00",
"benchmarks": [
{
"benchmark_name": "pagefind_init/pages/100",
"mean": {
"estimate": 1927600
},
"unit": "ns"
},
{
"benchmark_name": "pagefind_init/pages/500",
"mean": {
"estimate": 10438000
},
"unit": "ns"
}
]
}
|
🚀 Deployment PreviewYour changes have been deployed to Cloudflare Pages! 🔗 Preview URL: https://preview-28.md-book.pages.dev The deployment will be updated automatically when you push new changes to this PR. |
Clears the first validation condition: server.rs goes from 0% to 86.7% coverage. `book_routes` and `resolve_bind_addr` are extracted so behaviour can be exercised with warp::test rather than by binding ports. Writing those tests immediately found why the condition mattered: the catch-all `fs::file` fallback matched *every* path, including /live-reload, so the websocket upgrade was never reached. Live reload has silently never worked — the browser asked for a socket and got index.html. The reload route now precedes the file fallback, and a test performs the handshake and asserts a rebuild pushes "reload". Using the tool found a second gap: `serve -p 8080` was rejected because only `--port` existed. mdBook documents `-p`, so the short flag is added. On the second condition: UBS still cannot scan Rust. `ubs doctor` verifies js, python, cpp and golang and fails only on rust, with a stable hash across independent fetches — three distinct digests between the installer's pin, what upstream serves now, and the July cache. It fetches modules from an unpinned `master` while pinning digests in a released installer, so any upstream edit breaks verification by construction. Upstream's problem; the integrity check was not disabled. Substitute analysis with ast-grep and clippy is recorded in the validation report: zero unsafe blocks, zero panic!/todo!/unimplemented!, and seven unwrap/expect in production code, each verified guarded.
server.rs coverage 0% -> 86.7% closes the last open module boundary, taking totals to 87.1% lines and 174 tests. The UBS section now records the diagnosis (unpinned upstream branch vs pinned installer digest) and the substitute ast-grep/clippy analysis rather than just noting the tool failed.
|
Both validation conditions are now cleared, pushed to this branch.
Writing those tests immediately found why the condition mattered: the catch-all UBS diagnosed, not bypassed. Substitute analysis run directly with ast-grep and clippy: 0 Totals now: 174 tests, 87.1% line coverage, 9/9 module boundaries. |
📊 Performance Benchmark Results
Raw Results{
"timestamp": "2026-08-12T09:57:46+00:00",
"benchmarks": [
{
"benchmark_name": "pagefind_init/pages/50",
"mean": {
"estimate": 2292700
},
"unit": "ns"
},
{
"benchmark_name": "pagefind_init/pages/100",
"mean": {
"estimate": 4453400
},
"unit": "ns"
},
{
"benchmark_name": "pagefind_init/pages/500",
"mean": {
"estimate": 24821000
},
"unit": "ns"
}
]
}
|
🚀 Deployment PreviewYour changes have been deployed to Cloudflare Pages! 🔗 Preview URL: https://preview-28.md-book.pages.dev The deployment will be updated automatically when you push new changes to this PR. |
Requires md-book 0.2.0, merged as terraphim/md-book#28. The workflow clones md-book from main, so it picks this up on the next docs build: 574 pages in path order becomes 59 in SUMMARY order.
1 participant
Version bump, changelog, README scope note, and the Phase 4/5 reports.
Why 0.2.0 and not 1.0.0
Validation was conditional. Five of six Phase 1 success criteria are met and evidenced against terraphim-ai's real 129-file book; the sixth (
{{#include}}) is deliberately unmet, closed on evidence that no book md-book builds uses it.md-book servehas 0% test coverage. "Major" would claim a completeness that is not there.Evidence
What validation caught that verification could not
Three of four validation defects trace to design omissions, not implementation:
Known limitations, stated in the README
{{#include}},{{#playground}},{{#rustdoc_include}},{{#title}}unimplemented;mathjax-supportparses but does nothing;serveuntested.Reports
docs/plans/mdbook-parity-verification-report.md— traceability, coverage, defect register (15 defects with origin phases)docs/plans/mdbook-parity-validation-report.md— success criteria, NFRs, E2E scenarios, conditions