next-arch-map 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# next-arch-map
+
+Static analyzer that builds a multi-layer graph for Next.js-style apps. The graph can contain pages, endpoints, DB entities, and UI components.
+
+## Quickstart
+
+```bash
+npm install --save-dev next-arch-map
+npx next-arch-map analyze --project-root . --out arch/graph.full.json
+```
+
+## What It Produces
+
+`next-arch-map` emits a single JSON graph:
+
+```json
+{
+  "nodes": [
+    { "id": "page:/dashboard", "type": "page", "label": "/dashboard" },
+    { "id": "endpoint:/api/users", "type": "endpoint", "label": "/api/users" },
+    { "id": "db:user", "type": "db", "label": "user" },
+    { "id": "ui:ProfileCard", "type": "ui", "label": "ProfileCard" }
+  ],
+  "edges": [
+    { "from": "page:/dashboard", "to": "endpoint:/api/users", "kind": "page-endpoint" },
+    { "from": "endpoint:/api/users", "to": "db:user", "kind": "endpoint-db" },
+    { "from": "page:/dashboard", "to": "ui:ProfileCard", "kind": "page-ui" }
+  ]
+}
+```
+
+## CLI
+
+```bash
+npx next-arch-map analyze --project-root . --out arch/graph.full.json
+```
+
+The CLI accepts:
+
+- `--project-root <path>`
+- `--out <path>`
+- `--app-dir <path>` (repeatable)
+
+## Library API
+
+```ts
+import { analyzeProject } from "next-arch-map";
+
+const graph = await analyzeProject({
+  projectRoot: process.cwd(),
+});
+```
+
+## Notes
+
+- Page to endpoint detection currently looks for direct string-literal HTTP calls such as `fetch("/api/...")`, `axios.get("/api/...")`, and `apiClient.get("/api/...")`.
+- Endpoint to DB detection currently looks for Prisma-style calls such as `prisma.user.findMany(...)`.
+- Page to UI detection currently looks at page imports that resolve into component-like paths.

package/dist/analyzers/endpointsToDb.d.ts

@@ -0,0 +1,11 @@
+import type { Edge, Node } from "../model.js";
+type AnalyzeEndpointsToDbOptions = {
+    projectRoot: string;
+    apiDirs?: string[];
+    dbClientIdentifiers?: string[];
+};
+export declare function analyzeEndpointsToDb(options: AnalyzeEndpointsToDbOptions): Promise<{
+    nodes: Node[];
+    edges: Edge[];
+}>;
+export {};

package/dist/analyzers/endpointsToDb.js

@@ -0,0 +1,348 @@
+import path from "node:path";
+import ts from "typescript";
+import { buildDbNode, buildEdgeKey, buildEndpointNode, buildHandlerNode, ensureNode, getEndpointRouteFromFile, getExistingDirectories, getSourceFile, isIgnoredSourceFile, isRouteHandlerFile, resolveLocalModulePath, resolveProjectRoot, walkDirectory, } from "../utils.js";
+const DEFAULT_API_DIRS = ["app", "src/app", "app/api", "src/app/api", "src/server", "src/api"];
+const DEFAULT_DB_CLIENT_IDENTIFIERS = ["prisma"];
+const ROUTE_METHOD_EXPORTS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+export async function analyzeEndpointsToDb(options) {
+    const projectRoot = resolveProjectRoot(options.projectRoot);
+    const scanRoots = getExistingDirectories(projectRoot, options.apiDirs ?? DEFAULT_API_DIRS);
+    const dbClientIdentifiers = new Set(options.dbClientIdentifiers ?? DEFAULT_DB_CLIENT_IDENTIFIERS);
+    const nodes = [];
+    const edges = [];
+    const nodeIds = new Set();
+    const edgeKeys = new Set();
+    const sourceFileCache = new Map();
+    const moduleCache = new Map();
+    const seenRouteFiles = new Set();
+    for (const scanRoot of scanRoots) {
+        for (const filePath of walkDirectory(scanRoot)) {
+            if (seenRouteFiles.has(filePath) || isIgnoredSourceFile(filePath) || !isRouteHandlerFile(filePath)) {
+                continue;
+            }
+            seenRouteFiles.add(filePath);
+            const endpointPath = getEndpointRouteFromFile(scanRoot, filePath);
+            const { availableMethods, dbUsageByModel } = analyzeEndpoint(filePath, projectRoot, moduleCache, sourceFileCache, dbClientIdentifiers);
+            const endpointNode = ensureNode(nodes, nodeIds, buildEndpointNode(endpointPath, filePath));
+            const handlerMethods = availableMethods.size > 0 ? [...availableMethods] : [undefined];
+            for (const methodName of handlerMethods) {
+                const handlerNode = ensureNode(nodes, nodeIds, buildHandlerNode(endpointPath, filePath, methodName));
+                const edgeKey = buildEdgeKey(endpointNode.id, handlerNode.id, "endpoint-handler");
+                if (edgeKeys.has(edgeKey)) {
+                    continue;
+                }
+                edgeKeys.add(edgeKey);
+                edges.push({
+                    from: endpointNode.id,
+                    to: handlerNode.id,
+                    kind: "endpoint-handler",
+                    meta: methodName ? { method: methodName } : undefined,
+                });
+            }
+            for (const [modelName, dbUsage] of dbUsageByModel) {
+                const dbNode = ensureNode(nodes, nodeIds, buildDbNode(modelName, dbUsage.filePath));
+                const edgeKey = buildEdgeKey(endpointNode.id, dbNode.id, "endpoint-db");
+                if (edgeKeys.has(edgeKey)) {
+                    continue;
+                }
+                edgeKeys.add(edgeKey);
+                edges.push({
+                    from: endpointNode.id,
+                    to: dbNode.id,
+                    kind: "endpoint-db",
+                    meta: dbUsage.actionName ? { action: dbUsage.actionName } : undefined,
+                });
+            }
+        }
+    }
+    return {
+        nodes: nodes.sort((left, right) => left.id.localeCompare(right.id)),
+        edges: edges.sort((left, right) => left.kind.localeCompare(right.kind) ||
+            left.from.localeCompare(right.from) ||
+            left.to.localeCompare(right.to)),
+    };
+}
+function analyzeEndpoint(routeFilePath, projectRoot, moduleCache, sourceFileCache, dbClientIdentifiers) {
+    const state = {
+        projectRoot,
+        moduleCache,
+        sourceFileCache,
+        visitedDeclarationKeys: new Set(),
+        dbUsageByModel: new Map(),
+    };
+    const availableMethods = new Set();
+    for (const methodName of ROUTE_METHOD_EXPORTS) {
+        const resolvedDeclaration = resolveExportReference(routeFilePath, methodName, state);
+        if (resolvedDeclaration) {
+            availableMethods.add(methodName);
+            analyzeDeclaration(resolvedDeclaration, state, new Set(dbClientIdentifiers));
+        }
+    }
+    return {
+        availableMethods,
+        dbUsageByModel: state.dbUsageByModel,
+    };
+}
+function analyzeDeclaration(declaration, state, activeDbClients) {
+    if (state.visitedDeclarationKeys.has(declaration.key)) {
+        return;
+    }
+    state.visitedDeclarationKeys.add(declaration.key);
+    visitNode(getAnalyzableNode(declaration.node), declaration.filePath, state, activeDbClients);
+}
+function visitNode(node, filePath, state, activeDbClients) {
+    if (ts.isCallExpression(node)) {
+        const dbUsage = parseDbUsage(node, activeDbClients);
+        if (dbUsage) {
+            const existingUsage = state.dbUsageByModel.get(dbUsage.modelName);
+            if (!existingUsage) {
+                state.dbUsageByModel.set(dbUsage.modelName, {
+                    actionName: dbUsage.actionName,
+                    filePath,
+                });
+            }
+            else if (!existingUsage.actionName && dbUsage.actionName) {
+                state.dbUsageByModel.set(dbUsage.modelName, {
+                    ...existingUsage,
+                    actionName: dbUsage.actionName,
+                });
+            }
+        }
+        const transactionCallback = getTransactionCallback(node, activeDbClients);
+        if (transactionCallback) {
+            visitNode(getFunctionBodyNode(transactionCallback.callback), filePath, state, new Set([...activeDbClients, transactionCallback.clientIdentifier]));
+        }
+        if (shouldResolveCall(node)) {
+            const resolvedCallee = resolveIdentifierReference(node.expression.text, filePath, state);
+            if (resolvedCallee) {
+                analyzeDeclaration(resolvedCallee, state, activeDbClients);
+            }
+        }
+    }
+    ts.forEachChild(node, (child) => visitNode(child, filePath, state, activeDbClients));
+}
+function parseDbUsage(node, activeDbClients) {
+    if (!ts.isPropertyAccessExpression(node.expression) ||
+        !ts.isPropertyAccessExpression(node.expression.expression) ||
+        !ts.isIdentifier(node.expression.expression.expression)) {
+        return null;
+    }
+    const clientIdentifier = node.expression.expression.expression.text;
+    if (!activeDbClients.has(clientIdentifier)) {
+        return null;
+    }
+    return {
+        modelName: node.expression.expression.name.text,
+        actionName: node.expression.name.text,
+    };
+}
+function getTransactionCallback(node, activeDbClients) {
+    if (!ts.isPropertyAccessExpression(node.expression) ||
+        !ts.isIdentifier(node.expression.expression) ||
+        !activeDbClients.has(node.expression.expression.text) ||
+        node.expression.name.text !== "$transaction") {
+        return null;
+    }
+    const callback = node.arguments.find((argument) => ts.isArrowFunction(argument) || ts.isFunctionExpression(argument));
+    const firstParameter = callback?.parameters[0];
+    if (!callback || !firstParameter || !ts.isIdentifier(firstParameter.name)) {
+        return null;
+    }
+    return {
+        callback,
+        clientIdentifier: firstParameter.name.text,
+    };
+}
+function shouldResolveCall(node) {
+    return (ts.isIdentifier(node.expression) &&
+        !node.arguments.some((argument) => ts.isArrowFunction(argument) || ts.isFunctionExpression(argument)));
+}
+function resolveIdentifierReference(identifierName, filePath, state) {
+    const moduleInfo = getModuleInfo(filePath, state);
+    const localDeclaration = moduleInfo.localDeclarations.get(identifierName);
+    if (localDeclaration) {
+        return {
+            filePath,
+            key: `${filePath}::local::${identifierName}`,
+            node: localDeclaration,
+        };
+    }
+    const importTarget = moduleInfo.importsByLocalName.get(identifierName);
+    if (!importTarget) {
+        return null;
+    }
+    return resolveExportReference(importTarget.filePath, importTarget.exportName, state);
+}
+function resolveExportReference(filePath, exportName, state, seen = new Set()) {
+    const seenKey = `${filePath}::${exportName}`;
+    if (seen.has(seenKey)) {
+        return null;
+    }
+    seen.add(seenKey);
+    const moduleInfo = getModuleInfo(filePath, state);
+    const exportTarget = moduleInfo.exportsByName.get(exportName);
+    if (!exportTarget) {
+        const fallbackDeclaration = moduleInfo.localDeclarations.get(exportName);
+        if (!fallbackDeclaration) {
+            return null;
+        }
+        return {
+            filePath,
+            key: `${filePath}::local::${exportName}`,
+            node: fallbackDeclaration,
+        };
+    }
+    if (exportTarget.kind === "local") {
+        const localDeclaration = moduleInfo.localDeclarations.get(exportTarget.localName);
+        if (!localDeclaration) {
+            return null;
+        }
+        return {
+            filePath,
+            key: `${filePath}::local::${exportTarget.localName}`,
+            node: localDeclaration,
+        };
+    }
+    if (exportTarget.kind === "node") {
+        return {
+            filePath,
+            key: `${filePath}::node::${exportName}`,
+            node: exportTarget.node,
+        };
+    }
+    return resolveExportReference(exportTarget.filePath, exportTarget.exportName, state, seen);
+}
+function getModuleInfo(filePath, state) {
+    const cachedModuleInfo = state.moduleCache.get(filePath);
+    if (cachedModuleInfo) {
+        return cachedModuleInfo;
+    }
+    const sourceFile = getSourceFile(filePath, state.sourceFileCache);
+    if (!sourceFile) {
+        throw new Error(`Could not parse ${path.relative(state.projectRoot, filePath)}.`);
+    }
+    const localDeclarations = new Map();
+    const importsByLocalName = new Map();
+    const exportsByName = new Map();
+    for (const statement of sourceFile.statements) {
+        if (ts.isFunctionDeclaration(statement) && statement.name) {
+            localDeclarations.set(statement.name.text, statement);
+            if (hasExportModifier(statement)) {
+                exportsByName.set(statement.name.text, {
+                    kind: "local",
+                    localName: statement.name.text,
+                });
+            }
+            if (hasDefaultModifier(statement)) {
+                exportsByName.set("default", {
+                    kind: "local",
+                    localName: statement.name.text,
+                });
+            }
+            continue;
+        }
+        if (ts.isVariableStatement(statement)) {
+            const exported = hasExportModifier(statement);
+            for (const declaration of statement.declarationList.declarations) {
+                if (!ts.isIdentifier(declaration.name)) {
+                    continue;
+                }
+                localDeclarations.set(declaration.name.text, declaration);
+                if (exported) {
+                    exportsByName.set(declaration.name.text, {
+                        kind: "local",
+                        localName: declaration.name.text,
+                    });
+                }
+            }
+            continue;
+        }
+        if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+            const resolvedImportPath = resolveLocalModulePath(filePath, statement.moduleSpecifier.text, state.projectRoot);
+            if (!resolvedImportPath || !statement.importClause) {
+                continue;
+            }
+            if (statement.importClause.name) {
+                importsByLocalName.set(statement.importClause.name.text, {
+                    filePath: resolvedImportPath,
+                    exportName: "default",
+                });
+            }
+            if (statement.importClause.namedBindings &&
+                ts.isNamedImports(statement.importClause.namedBindings)) {
+                for (const element of statement.importClause.namedBindings.elements) {
+                    importsByLocalName.set(element.name.text, {
+                        filePath: resolvedImportPath,
+                        exportName: element.propertyName?.text ?? element.name.text,
+                    });
+                }
+            }
+            continue;
+        }
+        if (ts.isExportDeclaration(statement) &&
+            statement.exportClause &&
+            ts.isNamedExports(statement.exportClause)) {
+            const resolvedModulePath = statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)
+                ? resolveLocalModulePath(filePath, statement.moduleSpecifier.text, state.projectRoot)
+                : null;
+            for (const element of statement.exportClause.elements) {
+                const exportName = element.name.text;
+                if (resolvedModulePath) {
+                    exportsByName.set(exportName, {
+                        kind: "reexport",
+                        filePath: resolvedModulePath,
+                        exportName: element.propertyName?.text ?? element.name.text,
+                    });
+                    continue;
+                }
+                exportsByName.set(exportName, {
+                    kind: "local",
+                    localName: element.propertyName?.text ?? element.name.text,
+                });
+            }
+            continue;
+        }
+        if (ts.isExportAssignment(statement)) {
+            if (ts.isIdentifier(statement.expression)) {
+                exportsByName.set("default", {
+                    kind: "local",
+                    localName: statement.expression.text,
+                });
+            }
+            else {
+                exportsByName.set("default", {
+                    kind: "node",
+                    node: statement.expression,
+                });
+            }
+        }
+    }
+    const moduleInfo = {
+        localDeclarations,
+        importsByLocalName,
+        exportsByName,
+    };
+    state.moduleCache.set(filePath, moduleInfo);
+    return moduleInfo;
+}
+function getAnalyzableNode(node) {
+    if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) {
+        return node.body ?? node;
+    }
+    if (ts.isVariableDeclaration(node)) {
+        return node.initializer ?? node;
+    }
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+        return getFunctionBodyNode(node);
+    }
+    return node;
+}
+function getFunctionBodyNode(node) {
+    return node.body;
+}
+function hasExportModifier(node) {
+    return ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}
+function hasDefaultModifier(node) {
+    return ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword) ?? false;
+}

package/dist/analyzers/pagesToEndpoints.d.ts

@@ -0,0 +1,10 @@
+import type { Graph } from "../model.js";
+type AnalyzePagesToEndpointsOptions = {
+    projectRoot: string;
+    appDirs?: string[];
+    extraScanDirs?: string[];
+    httpClientIdentifiers?: string[];
+    httpClientMethods?: string[];
+};
+export declare function analyzePagesToEndpoints(options: AnalyzePagesToEndpointsOptions): Promise<Graph>;
+export {};