Skip to content

docs: pay down the restructure's doc debt - #386

Merged
lann merged 1 commit into
mainfrom
fix/287
Aug 18, 2026
Merged

docs: pay down the restructure's doc debt#386
lann merged 1 commit into
mainfrom
fix/287

Conversation

@lannbot

@lannbot lannbot commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Fixes #287.

Every bullet of the issue, corrected to what the referenced files actually do (each claim re-verified against the tree at HEAD before editing):

  • Five dead relative links. js/componentize/README.md's guest-crate link (../polymorph-webcrypto-guest../../rust/guest; the Rename to polymorph-components/polymorph-webcrypto #330 rename had churned the link text without fixing the path prefix), its demo link (→ ../../examples/componentize-demo) and toolchain-workflow link (→ ../../.github/…), js/componentize/wpt/README.md's workflow link (→ ../../../.github/…), and examples/componentize-demo/README.md's library link (../../webcrypto-componentize../../js/componentize). Verified with a relative-link check over every tracked *.md: all filesystem links now resolve (the root README's ../../releases is GitHub-web-relative by design, from releases: caret-honest 0.1.0 regime; polymorph-test + deltic pins to v0.1.0 #383).
  • Inverted toolchain claims (root README). wpt::test componentizes its runner from the tree — there is no published runner component — and downloads the digest-verified toolchain (component.sh's own header); componentize::test uses that same downloaded toolchain rather than "needing the componentize-js CLI" (nobody here builds it — the library README's Toolchain section).
  • Consumer world instructions (js/componentize README). The prescribed two-interface world fails at componentize time against the shim's ~30 static imports. The instructions now point at the webcrypto.js header as the authoritative registry (per the docs-state-invariants rule, no second enumerated copy to drift) and at componentize-demo's complete, compiling wit/world.wit.
  • Vendored-table gap (wpt README). The wrapKey_unwrapKey row (landed 0c39433), placed in the table where groups.js registers the group, described as component.sh builds it (wrapped callable + vectors file).
  • Minor pair. just ci runs the core CI jobs' checks, not "everything CI runs" / "mirrors CI exactly" — the dedicated engine-leg jobs (the Firefox conformance leg, the macOS WebKit conformance and parity legs) and the cross-target conformance-aggregate job run only in CI (README + AGENTS.md). The hpke experiment's compose comment now names justfile.shared.just, where _compose lives.

Docs-only (plus one justfile comment): the root and hpke justfiles still parse; no gate's inputs change.

The rust/+js/ restructure (182f911) and later growth left the docs
contradicting the tree; every claim below is corrected to what the
referenced files actually do.

- Five dead relative links: the js/componentize README's guest-crate,
  demo, and toolchain-workflow links (all still resolving inside js/),
  the wpt README's workflow link, and the componentize-demo README's
  library link.
- The root README described the two componentize checks' requirements
  backwards: wpt::test componentizes its runner from the tree (there is
  no published runner component) and downloads the digest-verified
  toolchain, and componentize::test uses that same downloaded toolchain
  (nobody here builds the CLI) — per component.sh and the library's
  Toolchain section.
- The js/componentize consumer instructions prescribed a two-interface
  world, which fails at componentize time against the shim's static
  imports; the world requirement now points at the webcrypto.js header
  (the authoritative registry) and the demo's complete world.
- The wpt README's vendored table gains the wrapKey_unwrapKey row
  (landed 0c39433).
- `just ci` runs the core CI jobs' checks, not "everything CI runs" /
  "mirrors CI exactly": the engine-leg jobs (Firefox, the macOS WebKit
  pair) and the conformance-aggregate job run only in CI (README,
  AGENTS.md). The hpke experiment's compose comment names
  justfile.shared.just, where _compose lives.
@lann
lann merged commit 9832d74 into main Aug 18, 2026
10 checks passed
@lann
lann deleted the fix/287 branch August 18, 2026 00:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

post-restructure doc debt: broken links, inverted toolchain claims, stale consumer instructions

2 participants