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

[AztecBot]

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:

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:

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 · group: slackbot

[AztecBot]

Flakey Tests

🤖 says: This CI run detected 1 tests that failed, but were tolerated due to a .test_patterns.yml entry.

\033FLAKED\033 (8;;http://ci.aztec-labs.com/0737c69f9e912ada�0737c69f9e912ada8;;�):  yarn-project/end-to-end/scripts/run_test.sh simple src/e2e_p2p/inactivity_slash_with_consecutive_epochs.test.ts (448s) (code: 0) group:e2e-p2p-epoch-flakes