ReviewOS

zig-utils/zig-js

Docs: align the pinned BunPress renderer with the checked output manifest

#631
Closed chris opened this 9 days ago ·
9 days ago

Problem

The docs gate checks out BunPress commit 1262895355142cb57ae7850dec7bf31cc5f5999d, whose package version is 0.1.21, while docs/.data/bunpress-output-v1.json records generator 0.2.6 and a materially newer rendered tree including search-index.json. The manifest check therefore fails every page.

Evidence: CI run 32338430544 docs job: generator 0.2.6 -> 0.1.21, removed: search-index.json, and changed hashes for all rendered pages.

Required implementation

  • Identify and pin the exact owned BunPress/STX/highlighter revisions that reproduce the checked manifest.
  • Update the workflow, dependency inventory, and lock metadata as one atomic source-graph change.
  • Regenerate the manifest only if the intended pinned graph produces an intentional renderer change; do not accept output from an unpinned dirty checkout.
  • Preserve the fail-closed manifest comparison.

Acceptance

  • A clean checkout of the declared owned renderer graph passes bun run docs:build.
  • zig build docs-link-check and zig build dependency-audit pass.
  • The inventory hashes/revisions exactly match CI checkout refs and package metadata.

Parent: #494 Related: #459, #492

9 days ago

Landed in 787f2a81.

The CI renderer graph now pins BunPress v0.2.6 at c0907f46685f0cede0556982feb44fc5133e96c7, installs its complete frozen dependency graph, and removes the obsolete standalone STX and ts-syntax-highlighter checkouts.

Verification:

  • clean exact-revision BunPress worktree and bun install --frozen-lockfile
  • 49-page build and checked-in manifest verification both passed
  • docs link audit passed for 267 files
  • dependency audit passed for 15 edges and 60 tools
  • workflow YAML and all changed JSON parsed successfully

The regenerated manifest contains the complete output from the pinned renderer graph, including the intended #632 benchmark-page changes.

9 days ago

Reopened after the first uncancelled Linux docs gate exposed a remaining renderer defect: job 96342382776 produced the same 254,740-byte search-index.json but with a different SHA-256 than macOS. All 267 documentation links passed and all page output matched. The pinned BunPress search index currently consumes Glob.scan() order without sorting, so filesystem enumeration can make the JSON record order host-dependent. I am fixing deterministic ordering in the owned BunPress source and will repin/regenerate zig-js after its tests pass.

9 days ago

The cross-filesystem fix is now landed in both owned repositories:

  • BunPress d248efd3 / stacksjs/bunpress#85: collect, normalize, deduplicate, and sort the complete search source inventory before document rendering.
  • zig-js c6d4de15: pin that exact BunPress revision and regenerate the 49-page manifest.

The corrected local search index is still 254,740 bytes; its canonical sorted SHA-256 is now 89836ff2b9cf1e23cb25dc381fcebe832172ad906d8a837a01e86255a3e68805. BunPress passes 22/22 focused and 562/562 full tests plus type checking. zig-js passes two manifest reproductions, 267-link validation, dependency audit (15 edges / 60 tools), and workflow/JSON parsing. Fresh Linux CI will verify the same sorted artifact.

9 days ago

Fresh Ubuntu validation passes the complete pinned documentation gate: docs. The deterministic BunPress source fix and zig-js repin in c6d4de15 now reproduce the checked-in 49-page manifest across macOS and Linux.

Sign in to comment on this issue.