fix(docs): parse Zod 4 function schemas in node API reference generator (#23798)

## Motivation

The Node JSON-RPC API reference generator
(`docs/scripts/node_api_reference_generation/generate_node_api_reference.ts`)
does not instantiate Zod at runtime — it string-parses the schema source
(`AztecNodeApiSchema = { ... }`) via the TypeScript compiler API.
`parseZodFunctionExpr` only recognized the **Zod 3** DSL:

```ts
z.function().args(BlockParameterSchema, schemas.Fr).returns(schemas.Fr)
```

After the repo-wide Zod 3 → 4 migration, every schema moved to the Zod 4
form:

```ts
getPublicStorageAt: z.function({
  input: z.tuple([BlockParameterSchema, schemas.AztecAddress, schemas.Fr]),
  output: schemas.Fr,
}),
```

There is no `.args(` / `.returns(` left, so `argsStart`/`returnsStart`
are `-1` and **every** method is emitted with `Parameters: None` and
`Returns: void`. It does not throw — it silently produces a useless
reference. This is the breakage referenced in #23660 ("the
node-api-reference generator is currently incompatible with the repo's
Zod 4 schemas — a pre-existing issue affecting all methods"); it
predates that PR and stems from the Zod 4 migration (the generator last
regenerated cleanly in #22934, when schemas were still Zod 3).

## Approach

Rewrote `parseZodFunctionExpr` to read the Zod 4 `z.function({ input:
z.tuple([...]), output: <expr> })` object: it extracts the `input` tuple
elements as the parameter list and the `output` expression as the return
type, reusing the existing `simplifyZodType` mapping. The legacy
`.args().returns()` path is kept as a fallback so older versioned-docs
schemas still regenerate. Added small helpers `findMatchingBracket`,
`findTopLevelColon`, and `parseInputArgs`.

## Verification

The only changed logic is the pure expression parser, so I unit-tested
the actual functions (loaded from this file) against real schema strings
copied verbatim from `aztec-node.ts`, plus a legacy Zod 3 string:

```
PASS  getPublicStorageAt (multi-arg tuple)            -> [BlockHash|number|"latest", AztecAddress, Fr] / Fr
PASS  getWorldStateSyncStatus (empty tuple)           -> [] / WorldStateSyncStatus
PASS  getTxReceipt (class.schema)                     -> [TxHash] / TxReceipt
PASS  getPendingTxs (optionals + array output)        -> [number|undefined, TxHash|undefined] / Tx[]
PASS  getBlockNumber (optional ref + branded return)  -> [ChainTip|undefined] / number
PASS  registerContractFunctionSignatures (nested arr) -> [string[]] / void
PASS  LEGACY Zod 3 .args().returns()                  -> [number, boolean|undefined] / void
7/7 passed
```

Red→green: pre-fix, the same parser returns `{ paramTypes: [],
returnType: "void" }` for every Zod 4 string.

**Not done in this PR (needs the built monorepo):** I did not run the
full generator end-to-end (`yarn generate:node-api-reference` requires
`yarn-project/node_modules`) or commit a regenerated
`node-api-reference.md`. A maintainer/CI should run the generator and
commit the refreshed reference as a follow-up.

## Out of scope (follow-ups)

The generator's static tables have also drifted from the current RPC
surface and will produce misplaced/ungrouped output even after this
parser fix — kept separate to keep this change focused:

- `METHOD_GROUPS` lists removed methods (`getPublicLogs`,
`getContractClassLogs`, `getPublicLogsByTagsFromContract`) and omits
current ones (`getPrivateLogsByTags`, `getPublicLogsByTags`,
`getCheckpointNumber`, `getCheckpointsData`, `getValidatorStats`, …).
- `simplifyZodType` still maps deleted schemas (`LogFilterSchema`,
`GetPublicLogsResponseSchema`, `GetContractClassLogsResponseSchema`) and
lacks `LogResultSchema` / `PrivateLogsQuerySchema` /
`PublicLogsQuerySchema` / `TxReceiptSchema`.

The separate TypeScript API reference generator
(`typescript_api_generation/`) is unrelated to this bug.

---
*Created by
[claudebox](https://claudebox.work/v2/sessions/46be71fd1d38fe81) ·
group: `slackbot`*

Author: critesjosh

docs/scripts/node_api_reference_generation/generate_node_api_reference.ts

@@ -180,7 +180,7 @@ function parseSchemaObject(
     const name = prop.name?.getText(sourceFile);
     if (!name) continue;
 
-    // The value is a Zod expression like z.function().args(...).returns(...)
+    // The value is a Zod expression like z.function({ input: z.tuple([...]), output: ... })
     const exprText = prop.initializer.getText(sourceFile);
     const info = parseZodFunctionExpr(exprText);
     result.set(name, info);
@@ -190,19 +190,49 @@ function parseSchemaObject(
 /**
  * Parse a Zod function expression string to extract simplified parameter types and return type.
  *
+ * Handles the Zod 4 object form used by the schemas, and falls back to the legacy Zod 3
+ * `.args().returns()` chain so older versioned-docs schemas still regenerate.
+ *
  * Examples:
- *   "z.function().args(BlockParameterSchema, schemas.Fr).returns(schemas.Fr)"
- *   "z.function().returns(z.boolean())"
- *   "z.function().args(z.number(), optional(z.boolean())).returns(z.void())"
+ *   "z.function({ input: z.tuple([BlockParameterSchema, schemas.Fr]), output: schemas.Fr })"
+ *   "z.function({ input: z.tuple([]), output: z.boolean() })"
+ *   "z.function().args(z.number(), optional(z.boolean())).returns(z.void())"  // legacy
  */
 function parseZodFunctionExpr(expr: string): { paramTypes: string[]; returnType: string } {
-  const paramTypes: string[] = [];
-  let returnType = 'void';
-
   // Normalize whitespace (multi-line expressions use \n + indentation)
   const normalized = expr.replace(/\s+/g, ' ').trim();
 
-  // Extract .args(...) content — match balanced parens for args
+  // Zod 4 form: z.function({ input: z.tuple([...]), output: <expr> })
+  const fnStart = normalized.indexOf('z.function(');
+  if (fnStart !== -1) {
+    const objStart = normalized.indexOf('{', fnStart);
+    if (objStart !== -1) {
+      const objEnd = findMatchingBracket(normalized, objStart);
+      if (objEnd !== -1) {
+        let inputExpr: string | undefined;
+        let outputExpr: string | undefined;
+        for (const entry of splitTopLevelArgs(normalized.substring(objStart + 1, objEnd))) {
+          const colon = findTopLevelColon(entry);
+          if (colon === -1) continue;
+          const key = entry.substring(0, colon).trim();
+          const value = entry.substring(colon + 1).trim();
+          if (key === 'input') inputExpr = value;
+          else if (key === 'output') outputExpr = value;
+        }
+        if (inputExpr !== undefined || outputExpr !== undefined) {
+          return {
+            paramTypes: inputExpr ? parseInputArgs(inputExpr) : [],
+            returnType: outputExpr ? simplifyZodType(outputExpr) : 'void',
+          };
+        }
+      }
+    }
+  }
+
+  // Legacy Zod 3 form: z.function().args(...).returns(...)
+  const paramTypes: string[] = [];
+  let returnType = 'void';
+
   const argsStart = normalized.indexOf('.args(');
   if (argsStart !== -1) {
     const argsContentStart = argsStart + '.args('.length;
@@ -215,7 +245,6 @@ function parseZodFunctionExpr(expr: string): { paramTypes: string[]; returnType:
     }
   }
 
-  // Extract .returns(...) content — match balanced parens for returns
   const returnsStart = normalized.indexOf('.returns(');
   if (returnsStart !== -1) {
     const returnsContentStart = returnsStart + '.returns('.length;
@@ -228,6 +257,34 @@ function parseZodFunctionExpr(expr: string): { paramTypes: string[]; returnType:
   return { paramTypes, returnType };
 }
 
+/**
+ * Extract the parameter type list from a Zod 4 `input:` value, which is normally a
+ * `z.tuple([...])`. Each tuple element is simplified independently so per-parameter docs
+ * (names + types) line up with the interface signature.
+ */
+function parseInputArgs(inputExpr: string): string[] {
+  const e = inputExpr.trim();
+
+  const optionalWrapperMatch = e.match(/^optional\(([\s\S]+)\)$/);
+  if (optionalWrapperMatch) return parseInputArgs(optionalWrapperMatch[1]);
+
+  const tupleStart = e.indexOf('z.tuple(');
+  if (tupleStart !== -1) {
+    const bracketOpen = e.indexOf('[', tupleStart);
+    if (bracketOpen !== -1) {
+      const bracketClose = findMatchingBracket(e, bracketOpen);
+      if (bracketClose !== -1) {
+        const inner = e.substring(bracketOpen + 1, bracketClose).trim();
+        if (!inner) return [];
+        return splitTopLevelArgs(inner).map(simplifyZodType);
+      }
+    }
+  }
+
+  // Non-tuple input (rare) — treat the whole expression as a single parameter.
+  return [simplifyZodType(e)];
+}
+
 /**
  * Find the position of the closing paren that matches the opening paren at `openPos`.
  * Returns the index of the closing paren, or -1 if not found.
@@ -244,6 +301,37 @@ function findMatchingParen(text: string, openPos: number): number {
   return -1;
 }
 
+/**
+ * Find the index of the bracket matching the opener at `openPos` (one of `(` `[` `{`).
+ * Returns the index of the matching closer, or -1 if not found.
+ */
+function findMatchingBracket(text: string, openPos: number): number {
+  const open = text[openPos];
+  const close = open === '(' ? ')' : open === '[' ? ']' : open === '{' ? '}' : '';
+  if (!close) return -1;
+  let depth = 0;
+  for (let i = openPos; i < text.length; i++) {
+    if (text[i] === open) depth++;
+    else if (text[i] === close) {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+/** Index of the first top-level `:` (depth 0 across `()`, `[]`, `{}`), or -1. */
+function findTopLevelColon(text: string): number {
+  let depth = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') depth--;
+    else if (c === ':' && depth === 0) return i;
+  }
+  return -1;
+}
+
 /**
  * Split comma-separated arguments at the top level (respecting nested parentheses and brackets).
  */