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: `. */ 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 }>; 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 { 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 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; if (call && !/fanout-reviewed:\s*\S/u.test(lines[line - 1] ?? "")) { 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; } 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[] = []; for (const file of files) { violations.push( ...(await findRequestFanout(path.relative(root, file), await readFile(file, "utf8"))), ); } return { files: files.length, violations }; } async function main(): Promise { const fixture = process.argv.includes("--fixture"); const root = process.cwd(); if (fixture) { // The forbidden fixture must be rejected; the allowed fixture must pass. 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; process.stdout.write( `request fan-out fixtures: forbidden ${forbidden.violations.length} rejected in ${forbidden.files} files, allowed ${allowed.violations.length} violations ${ok ? "PASS" : "FAIL"}\n`, ); if (!ok) process.exitCode = 1; return; } const result = await scanRequestFanout(root); for (const violation of result.violations) { process.stderr.write( `FAIL ${violation.file}:${violation.line} ${violation.call} inside ${violation.context}\n`, ); } process.stdout.write( `request fan-out: ${result.files} files scanned, ${result.violations.length} per-row dispatches ${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(); }