feat(docs): modify references pr request to add a comment + add references to node docs (#18771)

AztecBot · web-flow · commit 1347f119a6c2 · 2025-12-11T05:50:46.000Z
This modifies the references frontmatter PR request to add a comment
describing the files changed and what docs reference them.
diff --git a/docs/docs-network/reference/cli_reference.md b/docs/docs-network/reference/cli_reference.md
@@ -2,6 +2,7 @@
 sidebar_position: 1
 title: Cli Reference
 description: A reference of the --help output when running aztec start.
+references: ["yarn-project/aztec/src/cli/aztec_start_options.ts", "yarn-project/aztec/src/cli/cli.ts"]
 keywords:
   [
     aztec,
diff --git a/docs/docs-network/setup/bootnode_operation.md b/docs/docs-network/setup/bootnode_operation.md
@@ -3,6 +3,7 @@ id: bootnode_operation
 sidebar_position: 3
 title: Using and running a bootnode
 description: Learn how to connect to and operate bootnodes for peer discovery in the Aztec network.
+references: ["yarn-project/aztec/src/cli/cmds/start_p2p_bootstrap.ts"]
 ---
 
 ## Overview
diff --git a/docs/docs-network/setup/running_a_node.md b/docs/docs-network/setup/running_a_node.md
@@ -3,6 +3,7 @@ id: running_a_node
 sidebar_position: 2
 title: Running a Full Node
 description: A comprehensive guide on how to run a full node on the Aztec network using Docker Compose.
+references: ["yarn-project/aztec/src/cli/cmds/start_node.ts"]
 ---
 
 ## Overview
diff --git a/docs/docs-network/setup/running_a_prover.md b/docs/docs-network/setup/running_a_prover.md
@@ -3,6 +3,7 @@ id: running_a_prover
 sidebar_position: 4
 title: Running a Prover
 description: A comprehensive guide on how to run an Aztec prover on the network using Docker Compose in a distributed configuration.
+references: ["yarn-project/aztec/src/cli/cmds/start_prover_node.ts"]
 ---
 
 ## Overview
diff --git a/docs/network_versioned_docs/version-v2.1.4/concepts/governance/governance.md b/docs/network_versioned_docs/version-v2.1.4/concepts/governance/governance.md
@@ -3,6 +3,7 @@ id: governance
 sidebar_position: 3
 title: Governance Overview
 description: Learn about the governance process on the Aztec network.
+references: ["l1-contracts/src/governance/Governance.sol", "l1-contracts/src/governance/interfaces/IGovernance.sol"]
 ---
 
 import Image from "@theme/IdealImage";
diff --git a/docs/network_versioned_docs/version-v2.1.4/operation/keystore/creating_keystores.md b/docs/network_versioned_docs/version-v2.1.4/operation/keystore/creating_keystores.md
@@ -3,6 +3,7 @@ id: creating_keystores
 sidebar_position: 0
 title: Creating Sequencer Keystores
 description: Learn how to create sequencer keystores for running validators on the Aztec network using the Aztec CLI.
+references: ["yarn-project/cli/src/cmds/validator_keys/index.ts"]
 ---
 
 ## Overview
diff --git a/docs/network_versioned_docs/version-v2.1.4/operation/keystore/index.md b/docs/network_versioned_docs/version-v2.1.4/operation/keystore/index.md
@@ -3,6 +3,7 @@ id: advanced_keystore_guide
 sidebar_position: 2
 title: Advanced Keystore Usage
 description: Learn how to configure keystores with remote signers, mnemonics, JSON V3 keystores, and multiple publishers for enhanced security and flexibility.
+references: ["yarn-project/node-keystore/src/config.ts", "yarn-project/node-keystore/src/schemas.ts"]
 ---
 
 ## Overview
diff --git a/docs/network_versioned_docs/version-v2.1.4/operation/metrics_reference.md b/docs/network_versioned_docs/version-v2.1.4/operation/metrics_reference.md
@@ -1,6 +1,7 @@
 ---
 title: Key Metrics Reference
 description: Comprehensive guide to understanding and using the metrics exposed by your Aztec node for monitoring and observability.
+references: ["yarn-project/aztec-node/src/aztec-node/node_metrics.ts", "yarn-project/sequencer-client/src/sequencer/metrics.ts", "yarn-project/prover-node/src/metrics.ts", "yarn-project/archiver/src/archiver/instrumentation.ts"]
 ---
 
 ## Overview
diff --git a/docs/network_versioned_docs/version-v2.1.4/operation/sequencer_management/creating_and_voting_on_proposals.md b/docs/network_versioned_docs/version-v2.1.4/operation/sequencer_management/creating_and_voting_on_proposals.md
@@ -3,6 +3,7 @@ id: creating_and_voting_on_proposals
 sidebar_position: 1
 title: Governance and Proposal Process
 description: Learn how to participate in protocol governance as a sequencer, including signaling support, creating proposals, and voting
+references: ["l1-contracts/src/governance/Governance.sol", "l1-contracts/src/governance/interfaces/IGovernance.sol"]
 ---
 
 ## Overview
diff --git a/docs/network_versioned_docs/version-v2.1.4/reference/ethereum_rpc_reference.md b/docs/network_versioned_docs/version-v2.1.4/reference/ethereum_rpc_reference.md
@@ -3,6 +3,7 @@ id: ethereum_rpc_reference
 sidebar_position: 3
 title: Ethereum RPC call reference
 description: A comprehensive reference of Ethereum RPC calls used by different Aztec node components, including archiver, sequencer, prover, and slasher nodes.
+references: ["yarn-project/ethereum/src/client.ts", "yarn-project/sequencer-client/src/publisher/sequencer-publisher.ts"]
 ---
 
 This guide provides a comprehensive reference of Ethereum RPC calls used by different Aztec node components. Understanding these calls helps with infrastructure planning, monitoring, and debugging.
diff --git a/docs/network_versioned_docs/version-v2.1.4/reference/glossary.md b/docs/network_versioned_docs/version-v2.1.4/reference/glossary.md
@@ -3,6 +3,7 @@ id: glossary
 sidebar_position: 4
 title: Glossary
 description: A comprehensive glossary of terms used throughout the Aztec network documentation, covering node operations, consensus, cryptography, and infrastructure concepts.
+references: ["yarn-project/stdlib/src/interfaces/aztec-node.ts", "yarn-project/archiver/src/archiver/archiver.ts", "yarn-project/sequencer-client/src/sequencer/sequencer.ts", "yarn-project/prover-node/src/prover-node.ts"]
 ---
 
 This glossary defines key terms used throughout the Aztec network documentation. Terms are organized alphabetically with cross-references to related concepts.
diff --git a/docs/network_versioned_docs/version-v2.1.9-ignition/setup/sequencer_management.md b/docs/network_versioned_docs/version-v2.1.9-ignition/setup/sequencer_management.md
@@ -3,6 +3,7 @@ id: sequencer_management
 sidebar_position: 1
 title: Running a Sequencer
 description: Learn how to manage your sequencer on the Aztec network, including registration, keystore configuration, stake management, and status monitoring.
+references: ["yarn-project/node-keystore/src/config.ts"]
 ---
 
 ## Overview
diff --git a/docs/scripts/check_doc_references.sh b/docs/scripts/check_doc_references.sh
@@ -7,7 +7,8 @@ set -euo pipefail
 # 1. Extracts all 'references' fields from documentation markdown frontmatter
 # 2. Checks if any referenced files were changed in the current PR
 # 3. Requests AztecProtocol/devrel team as reviewers if files changed and PR is not draft
-# 4. Skips if devrel team is already requested as a reviewer
+# 4. Adds a comprehensive PR comment showing which changed files are referenced by which docs
+# 5. Skips reviewer request if devrel team is already requested or a member has approved
 #
 # Usage: check_doc_references.sh [pr_number] [docs_dir]
 #
@@ -116,9 +117,17 @@ fi
 # Extract all reference file paths from markdown frontmatter
 # Expected format: references: ["path/from/repo/root/file.ts", "another/file.ts"]
 # Paths should be absolute from repository root (not relative with ../)
-echo "Extracting references from markdown files in $DOCS_DIR..."
-REFERENCE_FILES=$(
-  find "$DOCS_DIR" -type f -name "*.md" -exec awk '
+# Also create a mapping of source files to documentation files
+# Note: We only scan docs/docs/ (current docs), not versioned_docs/
+# Versioned docs are historical snapshots and should not be modified when references change
+echo "Extracting references from markdown files in $DOCS_DIR/docs..."
+
+# Create a temporary file to store the mapping
+MAPPING_FILE=$(mktemp)
+trap "rm -f $MAPPING_FILE" EXIT
+
+find "$DOCS_DIR/docs" -type f -name "*.md" -print0 | while IFS= read -r -d '' doc_file; do
+  awk -v doc="$doc_file" '
     BEGIN { in_frontmatter = 0 }
     /^---$/ {
       if (NR == 1) {
@@ -136,13 +145,32 @@ REFERENCE_FILES=$(
         split(refs, arr, /,[ ]*/)
         for (i in arr) {
           if (arr[i] != "") {
-            print arr[i]
+            # Output format: source_file|doc_file
+            print arr[i] "|" doc
           }
         }
       }
     }
-  ' {} \; | sort -u
-)
+  ' "$doc_file"
+done > "$MAPPING_FILE"
+# Validate all referenced files exist
+echo "Validating referenced files exist..."
+MISSING_FILES=""
+while IFS='|' read -r ref_file doc_file; do
+  if [[ ! -f "$ref_file" ]]; then
+    MISSING_FILES="${MISSING_FILES}  - ${ref_file} (referenced in ${doc_file})\n"
+  fi
+done < "$MAPPING_FILE"
+
+if [[ -n "$MISSING_FILES" ]]; then
+  echo ""
+  echo "ERROR: The following referenced files do not exist:"
+  echo -e "$MISSING_FILES"
+  echo "Please update the 'references' frontmatter in the affected documentation files."
+  exit 1
+fi
+# Extract unique referenced files
+REFERENCE_FILES=$(cut -d'|' -f1 "$MAPPING_FILE" | sort -u)
 
 if [[ -z "$REFERENCE_FILES" ]]; then
   echo "No reference files found in documentation frontmatter."
@@ -195,12 +223,26 @@ if [[ -z "$CHANGED_FILES" ]]; then
 fi
 echo "Found $(echo "$CHANGED_FILES" | wc -l) changed file(s) in PR."
 
-# Check if any referenced files were changed
+# Check if any referenced files were changed and build mapping
 # Reference paths are absolute from repo root, so we can compare directly
 CHANGED_REFERENCES=""
+declare -A FILE_TO_DOCS_MAP
+
 while IFS= read -r ref_file; do
   if echo "$CHANGED_FILES" | grep -qF "$ref_file"; then
     CHANGED_REFERENCES="${CHANGED_REFERENCES}${ref_file}\n"
+
+    # Find all docs that reference this changed file
+    while IFS='|' read -r src_file doc_file; do
+      if [[ "$src_file" == "$ref_file" ]]; then
+        # Store in associative array (append to existing value if key exists)
+        if [[ -n "${FILE_TO_DOCS_MAP[$ref_file]}" ]]; then
+          FILE_TO_DOCS_MAP[$ref_file]="${FILE_TO_DOCS_MAP[$ref_file]}|${doc_file}"
+        else
+          FILE_TO_DOCS_MAP[$ref_file]="$doc_file"
+        fi
+      fi
+    done < "$MAPPING_FILE"
   fi
 done <<< "$REFERENCE_FILES"
 
@@ -213,26 +255,95 @@ echo ""
 echo "The following referenced files were changed in this PR:"
 echo -e "$CHANGED_REFERENCES"
 echo ""
+
+# Build comprehensive PR comment with file-to-docs mapping
+COMMENT_BODY="📚 **Documentation References Updated**
+
+The following source files that changed in this PR are referenced by documentation:
+
+### Changed Files → Documentation
+"
+
+# Get unique doc files count
+ALL_DOCS=""
+CHANGED_FILE_COUNT=0
+
+# Sort the keys for consistent output
+SORTED_KEYS=$(for key in "${!FILE_TO_DOCS_MAP[@]}"; do echo "$key"; done | sort)
+
+while IFS= read -r changed_file; do
+  [[ -z "$changed_file" ]] && continue
+  CHANGED_FILE_COUNT=$((CHANGED_FILE_COUNT + 1))
+
+  COMMENT_BODY="${COMMENT_BODY}
+**\`${changed_file}\`**"
+
+  # Get docs for this file and split by pipe
+  docs="${FILE_TO_DOCS_MAP[$changed_file]}"
+
+  # Convert pipe-separated list to array and iterate
+  IFS='|' read -ra DOC_ARRAY <<< "$docs"
+  for doc_file in "${DOC_ARRAY[@]}"; do
+    COMMENT_BODY="${COMMENT_BODY}
+- 📄 \`${doc_file}\`"
+
+    # Track all unique docs
+    if ! echo "$ALL_DOCS" | grep -qF "$doc_file"; then
+      ALL_DOCS="${ALL_DOCS}${doc_file}\n"
+    fi
+  done
+done <<< "$SORTED_KEYS"
+
+# Count unique docs
+DOC_FILE_COUNT=$(echo -e "$ALL_DOCS" | grep -v '^$' | sort -u | wc -l)
+
+COMMENT_BODY="${COMMENT_BODY}
+
+---
+**Summary:** ${CHANGED_FILE_COUNT} changed file(s) referenced by ${DOC_FILE_COUNT} documentation file(s)
+
+@AztecProtocol/devrel team has been requested for review."
+
 echo "Requesting AztecProtocol/devrel team as a reviewer for PR #$PR_NUMBER..."
 
 # Request AztecProtocol/devrel team as a reviewer
+REVIEWER_REQUESTED=false
 if gh pr edit "$PR_NUMBER" --add-reviewer AztecProtocol/devrel 2>/dev/null; then
   echo "✓ Successfully requested AztecProtocol/devrel team as a reviewer."
+  REVIEWER_REQUESTED=true
 else
   echo "⚠ Failed to request AztecProtocol/devrel team as a reviewer. They may need to be added manually."
 
-  # Add a PR comment to notify about the failure
-  COMMENT_BODY="⚠️ **Documentation Reference Check**
-
-Failed to automatically request @AztecProtocol/devrel as reviewers.
-
-**Referenced files changed:**
-$(echo -e "$CHANGED_REFERENCES" | sed 's/^/- /')
+  # Update comment to reflect failure
+  COMMENT_BODY="⚠️ ${COMMENT_BODY}
 
-Please manually request @AztecProtocol/devrel as reviewers for this PR."
-
-  gh pr comment "$PR_NUMBER" --body "$COMMENT_BODY" 2>/dev/null || echo "Note: Could not add PR comment."
+**Note:** Failed to automatically add @AztecProtocol/devrel as reviewers. Please add them manually."
+fi
 
-  # Don't block the build
-  exit 0
+# Check if we've already posted a documentation reference comment
+echo "Checking for existing documentation reference comment..."
+EXISTING_COMMENT=$(gh pr view "$PR_NUMBER" --json comments --jq '.comments[] | select(.body | startswith("📚 **Documentation References Updated**")) | .id' 2>/dev/null | head -n 1 || echo "")
+
+if [[ -n "$EXISTING_COMMENT" ]]; then
+  echo "Found existing documentation reference comment (ID: $EXISTING_COMMENT). Updating it..."
+  if gh api "repos/{owner}/{repo}/issues/comments/$EXISTING_COMMENT" -X PATCH -f body="$COMMENT_BODY" 2>/dev/null; then
+    echo "✓ Successfully updated existing documentation reference comment."
+  else
+    echo "⚠ Failed to update existing comment. Will try to add new comment instead."
+    if gh pr comment "$PR_NUMBER" --body "$COMMENT_BODY" 2>/dev/null; then
+      echo "✓ Successfully added new documentation reference comment."
+    else
+      echo "⚠ Failed to add PR comment."
+    fi
+  fi
+else
+  echo "No existing documentation reference comment found. Adding new comment..."
+  if gh pr comment "$PR_NUMBER" --body "$COMMENT_BODY" 2>/dev/null; then
+    echo "✓ Successfully added documentation reference comment."
+  else
+    echo "⚠ Failed to add PR comment."
+  fi
 fi
+
+# Exit successfully even if comment fails (don't block builds)
+exit 0

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@`
`2`	`2`	`sidebar_position: 1`
`3`	`3`	`title: Cli Reference`
`4`	`4`	`description: A reference of the --help output when running aztec start.`
	`5`	`+references: ["yarn-project/aztec/src/cli/aztec_start_options.ts", "yarn-project/aztec/src/cli/cli.ts"]`
`5`	`6`	`keywords:`
`6`	`7`	`[`
`7`	`8`	`aztec,`