import { readdir, readFile } from "node:fs/promises"; import path from "node:path"; import { parseAsync } from "@babel/core"; /** * scale-architecture.md §12 / §41. Source gate against frontend N+1 request fan-out. * * In feature code and application use cases, a physical-request dispatch must * not run once per element of a collection. The gate rejects a dispatch call * - inside a loop statement (for / for-of / for-in / while / do-while), or * - inside a callback passed to an array iteration method * (map, flatMap, forEach, filter, reduce, some, every, find, findIndex), * where a dispatch is `fetch(...)`, or any method call on a receiver named like * a transport (`http`, `executor`, `client`, `gateway`, `api`, `transport`). * * The HTTP runtime itself (src/adapters/http) owns its bounded retry loop and is * out of scope. A reviewed exception is written on the call's line as * `// fanout-reviewed: `. * * 0929/12-01. A failure names both ways out: fetch page after page through * `createCursorPaginationRuntime` (src/adapters/query-cache) assembled in the * feature's `adapters/`, or mark a bounded, reviewed repetition on the call's * line. Every reviewed exception is counted and listed in the result line. * * What it does not see: a dispatch through a receiver named otherwise * (`repository.load()`, a destructured `get`), a dispatch in a named function * that a loop calls, recursion, and promises built before an iteration and * awaited inside it. Reviews still look for those. */ export const REQUEST_FANOUT_ROOTS = Object.freeze(["src/features", "src/application"]); const TRANSPORT_RECEIVER = /^(?:http|executor|client|gateway|api|transport)$|(?:Http|Executor|Client|Gateway|Api|Transport)$/u; const ITERATION_METHODS = new Set([ "map", "flatMap", "forEach", "filter", "reduce", "some", "every", "find", "findIndex", ]); const LOOP_TYPES = new Set([ "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement", ]); const FUNCTION_TYPES = new Set(["ArrowFunctionExpression", "FunctionExpression"]); type Node = { type: string; loc?: { start: { line: number } } } & Record; export type FanoutViolation = Readonly<{ file: string; line: number; call: string; context: string }>; export type FanoutReviewedException = Readonly<{ file: string; line: number; call: string; reason: string }>; const REVIEWED = /fanout-reviewed:\s*(\S.*?)\s*$/u; /** How to fix a failure; both ways the source gate accepts. */ export const FANOUT_REMEDY = "load one page per request with createCursorPaginationRuntime (src/adapters/query-cache) assembled in the " + "feature's adapters/, or, for a bounded repetition someone reviewed, write `// fanout-reviewed: ` on the call's line"; function receiverName(node: Node | undefined): string | null { if (!node) return null; if (node.type === "Identifier") return node["name"] as string; if (node.type === "MemberExpression" && (node["property"] as Node).type === "Identifier") { return ((node["property"] as Node)["name"] as string) ?? null; } if (node.type === "ThisExpression") return "this"; return null; } function dispatchDescription(call: Node): string | null { const callee = call["callee"] as Node; if (callee.type === "Identifier" && callee["name"] === "fetch") return "fetch()"; if (callee.type === "MemberExpression") { const receiver = receiverName(callee["object"] as Node); const property = callee["property"] as Node; const method = property.type === "Identifier" ? (property["name"] as string) : "?"; if (receiver && TRANSPORT_RECEIVER.test(receiver)) return `${receiver}.${method}()`; } return null; } function iterationCallback(parent: Node | undefined, child: Node): string | null { if (!parent || parent.type !== "CallExpression" || !FUNCTION_TYPES.has(child.type)) return null; if (!(parent["arguments"] as Node[]).includes(child)) return null; const callee = parent["callee"] as Node; if (callee.type !== "MemberExpression") return null; const property = callee["property"] as Node; const method = property.type === "Identifier" ? (property["name"] as string) : ""; return ITERATION_METHODS.has(method) ? `.${method}() callback` : null; } export async function findRequestFanout( file: string, sourceText: string, ): Promise { return (await inspectRequestFanout(file, sourceText)).violations; } /** Per-row dispatches, and the ones a `fanout-reviewed:` comment let through. */ export async function inspectRequestFanout( file: string, sourceText: string, ): Promise> { const plugins: ("jsx" | ["typescript", { dts: boolean }])[] = [["typescript", { dts: false }]]; if (file.endsWith(".tsx")) plugins.push("jsx"); const tree = (await parseAsync(sourceText, { filename: file, babelrc: false, configFile: false, sourceType: "module", parserOpts: { plugins }, })) as unknown as Node | null; if (!tree) throw new Error(`cannot parse ${file}`); const lines = sourceText.split("\n"); const violations: FanoutViolation[] = []; const reviewed: FanoutReviewedException[] = []; const visit = (node: Node, parent: Node | undefined, repeating: string | null): void => { let context = repeating; if (LOOP_TYPES.has(node.type)) context = node.type.replace("Statement", " loop"); const callback = iterationCallback(parent, node); if (callback) context = callback; // A nested function declared (not iterated) resets the repetition context. if (!callback && FUNCTION_TYPES.has(node.type)) context = null; if (node.type === "FunctionDeclaration") context = null; if (node.type === "CallExpression" && context) { const call = dispatchDescription(node); const line = node.loc?.start.line ?? 0; const reason = REVIEWED.exec(lines[line - 1] ?? "")?.[1]; if (call && reason !== undefined) reviewed.push({ file, line, call, reason }); else if (call) violations.push({ file, line, call, context }); } for (const [key, value] of Object.entries(node)) { if (key === "loc" || key === "start" || key === "end" || key === "extra") continue; const children = Array.isArray(value) ? value : [value]; for (const child of children) { if (child && typeof child === "object" && typeof (child as Node).type === "string") { visit(child as Node, node, context); } } } }; visit(tree, undefined, null); return { violations, reviewed }; } async function sourceFiles(directory: string): Promise { const found: string[] = []; let entries; try { entries = await readdir(directory, { withFileTypes: true }); } catch { return found; } for (const entry of entries) { const target = path.join(directory, entry.name); if (entry.isDirectory()) found.push(...(await sourceFiles(target))); else if (/\.tsx?$/u.test(entry.name) && !/\.d\.ts$/u.test(entry.name)) found.push(target); } return found; } export async function scanRequestFanout( root: string, roots: readonly string[] = REQUEST_FANOUT_ROOTS, ): Promise> { const files = (await Promise.all(roots.map((entry) => sourceFiles(path.join(root, entry))))).flat(); const violations: FanoutViolation[] = []; const reviewed: FanoutReviewedException[] = []; for (const file of files) { const found = await inspectRequestFanout(path.relative(root, file), await readFile(file, "utf8")); violations.push(...found.violations); reviewed.push(...found.reviewed); } return { files: files.length, violations, reviewed }; } export function formatFanoutViolation(violation: FanoutViolation): string { return `FAIL ${violation.file}:${violation.line} ${violation.call} inside ${violation.context}: ${FANOUT_REMEDY}`; } function formatReviewed(reviewed: readonly FanoutReviewedException[]): string { if (reviewed.length === 0) return "0 reviewed exceptions"; return `${reviewed.length} reviewed exception${reviewed.length === 1 ? "" : "s"} (` + `${reviewed.map((entry) => `${entry.file}:${entry.line} ${entry.reason}`).join("; ")})`; } /** * The forbidden fixture must be rejected; the allowed fixture must pass, with * its reviewed cursor loop counted as a reviewed exception. */ export async function checkRequestFanoutFixtures(root: string): Promise> { const forbidden = await scanRequestFanout(root, ["tests/fixtures/architecture/request-fanout/forbidden"]); const allowed = await scanRequestFanout(root, ["tests/fixtures/architecture/request-fanout/allowed"]); const ok = forbidden.violations.length >= forbidden.files && forbidden.files > 0 && allowed.violations.length === 0 && allowed.reviewed.length > 0; return { ok, line: `request fan-out fixtures: forbidden ${forbidden.violations.length} rejected in ${forbidden.files} files, ` + `allowed ${allowed.violations.length} violations and ${formatReviewed(allowed.reviewed)} ${ok ? "PASS" : "FAIL"}`, }; } async function main(): Promise { const fixture = process.argv.includes("--fixture"); const root = process.cwd(); if (fixture) { const result = await checkRequestFanoutFixtures(root); process.stdout.write(`${result.line}\n`); if (!result.ok) process.exitCode = 1; return; } const result = await scanRequestFanout(root); for (const violation of result.violations) process.stderr.write(`${formatFanoutViolation(violation)}\n`); process.stdout.write( `request fan-out: ${result.files} files scanned, ${result.violations.length} per-row dispatches, ` + `${formatReviewed(result.reviewed)} ${result.violations.length === 0 ? "PASS" : "FAIL"}\n`, ); if (result.violations.length > 0) process.exitCode = 1; } if (import.meta.url === `file://${process.argv[1]}`) { await main(); }