#!/usr/bin/env node // A scoped dependency rule, not a sandbox for untrusted generated code. import ts from "typescript"; import { readFileSync, statSync } from "node:fs"; import path from "node:path"; import { fileURLToPath } from "node:url"; const presentation = new Set([ "src/features/annotation-output/DashboardPresentation.tsx", "src/features/annotation-output/presentation.ts", "src/features/annotation-output/presentation.css", ]); const protocols = [ "src/lib/annotation-persistence.js", "src/lib/slice-edit-session.js", "src/lib/review-draft-persistence.js", "src/lib/review-decision-controller.js", "src/lib/review-decision-completion.js", ]; const packages = new Set(["react", "lucide-react", "zod"]); export function checkFrontendArchitecture({ root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."), read = (file) => readFileSync(path.join(root, file), "utf8"), exists = (file) => { try { return statSync(path.join(root, file)).isFile(); } catch { return false; } }, } = {}) { const issues = []; const visited = new Set(); function walk(file, policy, chain) { const key = `${policy}:${file}`; if (visited.has(key)) return; visited.add(key); const fail = (line, message) => issues.push({ file, line, message, chain: [...chain, file] }); let text; try { text = read(file); } catch { fail(1, "Protected module is missing or unreadable"); return; } if (file.endsWith(".css")) return; const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true); if (source.parseDiagnostics.length) { for (const diagnostic of source.parseDiagnostics) fail( source.getLineAndCharacterOfPosition(diagnostic.start ?? 0).line + 1, `Cannot parse module: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, " ")}`, ); return; } const dependency = (node, specifier) => { const line = source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1; if (!specifier || !ts.isStringLiteralLike(specifier)) { fail(line, "Computed module loading cannot be checked; use a literal import"); return; } const name = specifier.text; if (policy === "presentation" && packages.has(name)) return; if (!name.startsWith(".")) { fail(line, `Dependency '${name}' is outside the ${policy} layer`); return; } const base = path.posix.normalize(path.posix.join(path.posix.dirname(file), name)); const targets = [ base, ...[".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.tsx", "/index.js"].map((ext) => base + ext), ].filter(exists); if (targets.length > 1) { fail(line, `Ambiguous dependency '${name}'; use an explicit file path`); return; } const target = targets[0]; if (!target) { fail(line, `Cannot resolve '${name}'`); return; } const allowed = policy === "presentation" ? presentation.has(target) : target.startsWith("src/lib/") && /\.[jt]sx?$/.test(target); if (!allowed) { fail(line, `Dependency '${name}' is outside the ${policy} layer`); return; } walk(target, policy, [...chain, file]); }; const visit = (node) => { if ( policy === "protocol" && (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) ) { fail( source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1, "JSX introduces a React runtime dependency into a protocol module", ); return; } if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier) dependency(node, node.moduleSpecifier); else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) dependency(node, node.moduleReference.expression); else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) dependency(node, node.argument.literal); else if (ts.isCallExpression(node)) { let callee = node.expression; while (ts.isParenthesizedExpression(callee)) callee = callee.expression; if ( callee.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(callee) && callee.text === "require") || (ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression) && callee.expression.text === "module" && callee.name.text === "require") ) dependency(node, node.arguments[0]); else if ( ts.isPropertyAccessExpression(callee) && ts.isMetaProperty(callee.expression) && ["glob", "globEager"].includes(callee.name.text) ) dependency(node, undefined); } ts.forEachChild(node, visit); }; visit(source); } walk("src/features/annotation-output/DashboardPresentation.tsx", "presentation", []); walk("src/features/annotation-output/presentation.ts", "presentation", []); for (const file of protocols) walk(file, "protocol", []); return issues; } if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { const issues = checkFrontendArchitecture(); for (const issue of issues) console.error(`${issue.file}:${issue.line}: ${issue.message}\n ${issue.chain.join(" → ")}`); if (issues.length) process.exitCode = 1; else console.log("Frontend architecture: presentation and persistence dependency rules passed."); }