docs: fail CI when the aztec.js reference drifts - #25249
Open
vezenovm wants to merge 17 commits into
Open
Conversation
Two bugs made a regeneration of the aztec.js API reference unlandable, which is part of why the committed reference had not been refreshed since December. The generator emitted multi-line types inside inline code spans. A type body containing a blank line closes the span early, leaving its braces and angle brackets to be parsed as MDX expressions and JSX tags, so the page no longer compiled and the docs build failed. Emit a fenced code block for multi-line types instead, matching what format_return_type already did, and collapse destructured parameter names onto one line. The table of contents also built anchors with its own slug logic, which stripped underscores that Docusaurus keeps. That left CAPABILITY_VERSION and the Contract / Protocol_Contracts section unreachable, and pointed NO_WAIT and NO_FROM at the NoWait and NoFrom headings instead. Derive the anchor from the rendered heading text the way github-slugger does. Also fix the aztec.js JSDoc that a regenerated reference trips cspell on: a "metadata" typo and the repo-flagged "on-chain" spelling.
Last generated on 2025-12-10, so the committed reference had drifted a long way from the source: 19 documented symbols no longer exist in aztec.js (including getGasLimits, which moved to the wallet SDK) and 82 current exports were missing entirely.
vezenovm
force-pushed
the
mv/aztecjs-reference-drift-check
branch
2 times, most recently
from
August 17, 2026 17:32
512e282 to
dd9b0b9
Compare
The aztec.js reference sat eight months out of date because nothing watched it: docs CI never regenerated or diffed it, it declares no `references:` frontmatter so the devrel drift alert ignored it, and the release checklist regenerated the aztec-nr, TypeDoc and CLI references but not this one. Add `--check` to update_docs.sh, which regenerates into a temp file and diffs it against the committed page, ignoring the generation timestamp the page stamps into itself. Wire it into docs/bootstrap.sh so a change to yarn-project/aztec.js/src that alters the reference cannot land without the regenerated page, and add the regeneration step to the release checklist so a release cannot ship a stale one either. The temp-file cleanup moves to an EXIT trap, since --check returns before the deploy step the old cleanup line sat after.
vezenovm
force-pushed
the
mv/aztecjs-reference-drift-check
branch
from
August 17, 2026 17:38
dd9b0b9 to
0f7be00
Compare
vezenovm
marked this pull request as ready for review
August 17, 2026 18:16
…ecjs-reference-regen
The parser walked subdirectories in fs.readdirSync order and sorted files with localeCompare, so the module and file order in the generated page depended on the filesystem and on the runtime's locale data: the same sources produced a different page on macOS and on Linux. Sort both by code unit. Reversing every readdir now leaves the regenerated page identical apart from its timestamp.
Two rounds of the check failing in CI could not be diagnosed from the log, because the failure only said to regenerate. Print the diff: the generator infers return types through the type checker, so its output depends on which yarn-project packages the environment has built, and that kind of drift does not reproduce on the author's machine.
Nine public members had no return annotation, so the generated API reference documented them through the type checker. Write the types out. They are the types the checker already reported, except waitForProven, which becomes Promise<BlockNumber> rather than retryUntil's Promise<NonNullable<BlockNumber>>.
The parser resolved @aztec/* imports, so an inferred return type depended on which sibling packages the environment had built: a page generated against a full build silently differed from one generated against a partial build, and the difference only surfaced in CI. Resolve relative imports only, so the page is a function of the aztec.js sources and nothing else. Types that cross a package boundary now have to be annotated in the source. Parsing also drops from ~50s to ~8s, since the checker no longer reads the workspace's declaration files.
vezenovm
marked this pull request as draft
August 18, 2026 11:23
yarn-project/aztec.js/src/contract/protocol_contracts is gitignored build output, generated from the compiled Noir protocol contracts. Documenting it made the page depend on noir-projects: a checkout cannot regenerate or verify the reference without those artifacts, and a change to a protocol contract left the committed page stale. The page now covers 8 modules and 182 exports, and generating it with that directory absent produces the same bytes.
Base automatically changed from
mv/aztecjs-reference-regen
to
merge-train/fairies
August 18, 2026 16:45
…ecjs-reference-drift-check # Conflicts: # docs/docs-developers/docs/aztec-js/aztec_js_reference.md # docs/scripts/aztecjs_reference_generation/parse_typescript.js # docs/scripts/aztecjs_reference_generation/transform_to_markdown.py
vezenovm
marked this pull request as ready for review
August 18, 2026 16:54
nchamo
approved these changes
Aug 18, 2026
nchamo
left a comment
nchamo
left a comment
Contributor
There was a problem hiding this comment.
If you manage to merge it before the repo split, then great. If not, we would need to port this to the new repo
| exit 0 | ||
| fi | ||
|
|
||
| # Print the drift. Not every cause reproduces on the author's machine: the generator infers |
Contributor
There was a problem hiding this comment.
relativeImportsOnlyHost (added later in this PR) makes the checker resolve relative imports only, so sibling build state can't change the output any more. Should we drop that part of the comment? Otherwise someone hitting a red check here will go rebuild yarn-project for nothing.
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
2 participants
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.
Stacked on #25248, which regenerates the page.
The aztec.js reference sat eight months out of date because nothing watched it. Docs CI never regenerated or diffed it (
docs/bootstrap.shonly builds and spellchecks). The release checklist regenerates the aztec-nr API, the TypeDoc TypeScript API and the three CLI references but not this one. The v5.1.0 release refreshed all of those in the same commit and left this page on its December content.Two changes so it cannot happen again:
update_docs.sh --checkregenerates into a temp file and diffs it against the committed page, ignoring the generation timestamp the page stamps into itself.docs/bootstrap.shgains acheck_generated_refsstep, so a change toyarn-project/aztec.js/srcthat alters the reference cannot land without the regenerated page. It skips on arm64 CI, matchingbuild_docsandtest_cmds.Verification
✓ Reference matches aztec.js), and the temp files are cleaned up.