docs: fail CI when the aztec.js reference drifts

.claude/skills/release-docs/SKILL.md

@@ -156,12 +156,17 @@ self-identify its release type, set `RELEASE_TYPE` explicitly.
 cd docs
 RELEASE_TYPE=<release_type> yarn generate:aztec-nr-api <nodeVersion>
 RELEASE_TYPE=<release_type> yarn generate:typescript-api <nodeVersion>
+./scripts/aztecjs_reference_generation/update_docs.sh current
 ```
 
 This creates/updates the API docs in:
 
 - `docs/static/aztec-nr-api/<release_type>/` (e.g. `mainnet/`, `testnet/`)
 - `docs/static/typescript-api/<release_type>/`
+- `docs/docs-developers/docs/aztec-js/aztec_js_reference.md`
+
+`docs/bootstrap.sh` fails CI when the Aztec.js reference drifts, so in practice it
+should already be current; run it anyway so a release never ships a stale page.
 
 **Prerequisites — you MUST build dependencies before generating API docs:**
 

docs/bootstrap.sh

@@ -34,6 +34,15 @@ function build_docs {
   cache_upload docs-$hash.tar.gz build
 }
 
+function check_generated_refs {
+  if [ "${CI:-0}" -eq 1 ] && [ $(arch) == arm64 ]; then
+    echo "Not checking generated docs for arm64 in CI."
+    return
+  fi
+  echo_header "check generated aztec.js reference"
+  ./scripts/aztecjs_reference_generation/update_docs.sh --check
+}
+
 function test_cmds {
   if [ "${CI:-0}" -eq 1 ] && [ $(arch) == arm64 ]; then
     # Not running docs tests for arm64 in CI.
@@ -129,13 +138,15 @@ case "$cmd" in
   "ci")
     build_examples
     build_docs
+    check_generated_refs
     test
     check_orphaned_urls
     check_references
     ;;
   "")
     build_examples
     build_docs
+    check_generated_refs
     check_orphaned_urls
     check_references
     ;;

docs/scripts/aztecjs_reference_generation/README.md

@@ -26,8 +26,16 @@ A **two-phase pipeline** with complete control over output:
 
 # Generate to specific version
 ./scripts/aztecjs_reference_generation/update_docs.sh v2.0.2
+
+# Fail if the committed current-version page is out of date
+./scripts/aztecjs_reference_generation/update_docs.sh --check
 ```
 
+`--check` regenerates into a temp file and diffs it against the committed page,
+ignoring the embedded generation timestamp. `docs/bootstrap.sh` runs it so a change
+to `yarn-project/aztec.js/src` that alters the reference cannot land without the
+regenerated page.
+
 ### Convenience Script (Testing - Custom Approach)
 
 ```bash

docs/scripts/aztecjs_reference_generation/update_docs.sh

@@ -1,15 +1,25 @@
 #!/usr/bin/env bash
 # Script to regenerate auto-generated Aztec.js API documentation
-# Usage: ./scripts/aztecjs_reference_generation/update_docs.sh [target_version]
+# Usage: ./scripts/aztecjs_reference_generation/update_docs.sh [target_version] [--check]
 #
 # Examples:
 #   ./scripts/aztecjs_reference_generation/update_docs.sh                    # Updates all versions
 #   ./scripts/aztecjs_reference_generation/update_docs.sh current            # Updates current only
 #   ./scripts/aztecjs_reference_generation/update_docs.sh v2.0.2             # Updates v2.0.2 only
+#   ./scripts/aztecjs_reference_generation/update_docs.sh --check            # Fails if current is stale
 
 set -euo pipefail
 
-TARGET_VERSION="${1:-all}"
+CHECK_ONLY=false
+TARGET_VERSION=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --check) CHECK_ONLY=true ;;
+    *) TARGET_VERSION="$1" ;;
+  esac
+  shift
+done
+TARGET_VERSION="${TARGET_VERSION:-all}"
 
 # Constants
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -21,6 +31,13 @@ readonly OUTPUT_FILE="aztec_js_reference.md"
 readonly SIDEBAR_POSITION="98"
 readonly TITLE="Reference"
 
+# --check and the error paths exit before the deploy step, so the per-run temp files are
+# cleaned up on exit. The defaults cover exits from before the names are assigned.
+cleanup() {
+  rm -f "${TEMP_JSON:-}" "${TEMP_MD:-}" "${TEMP_WITH_FRONTMATTER:-}"
+}
+trap cleanup EXIT
+
 echo "=== Aztec.js API Documentation Update Script ==="
 echo ""
 
@@ -71,6 +88,51 @@ EOF
 # Append markdown content (skip first line which is duplicate title)
 tail -n +2 "$TEMP_MD" >> "$TEMP_WITH_FRONTMATTER"
 
+# --check: compare against the committed current-version page instead of deploying.
+if [[ "$CHECK_ONLY" == true ]]; then
+  echo ""
+  echo "Step 3: Comparing against the committed reference..."
+  readonly COMMITTED="$DOCS_ROOT/docs-developers/docs/aztec-js/$OUTPUT_FILE"
+
+  if [[ ! -f "$COMMITTED" ]]; then
+    echo "Error: no committed reference at $COMMITTED"
+    exit 1
+  fi
+
+  # The page stamps its own generation time, so that line always differs.
+  normalize() {
+    sed 's/^\*Generated: .*\*$/*Generated: <ignored>*/' "$1"
+  }
+
+  DRIFT=$(diff -U1 --label committed --label regenerated \
+    <(normalize "$COMMITTED") <(normalize "$TEMP_WITH_FRONTMATTER") || true)
+
+  if [[ -z "$DRIFT" ]]; then
+    echo "  ✓ Reference matches aztec.js"
+    exit 0
+  fi
+
+  # Print the drift. Not every cause reproduces on the author's machine: the generator infers
+  # return types through the type checker, so what it emits also depends on which yarn-project
+  # packages the environment has built.
+  DRIFT_LINES=$(printf '%s\n' "$DRIFT" | wc -l | tr -d ' ')
+  echo "" >&2
+  printf '%s\n' "$DRIFT" | head -60 >&2 || true
+  if ((DRIFT_LINES > 60)); then
+    echo "... and $((DRIFT_LINES - 60)) more diff lines" >&2
+  fi
+
+  cat >&2 <<EOF
+
+The committed Aztec.js reference no longer matches yarn-project/aztec.js/src.
+
+Regenerate it and commit the result:
+
+  cd docs && ./scripts/aztecjs_reference_generation/update_docs.sh current
+EOF
+  exit 1
+fi
+
 # Step 4: Deploy to target locations
 echo ""
 echo "Step 3: Deploying documentation..."
@@ -122,9 +184,6 @@ case "$TARGET_VERSION" in
     ;;
 esac
 
-# Cleanup
-rm -f "$TEMP_JSON" "$TEMP_MD" "$TEMP_WITH_FRONTMATTER"
-
 echo ""
 echo "=== Documentation Update Complete ==="
 echo ""