next-arch-map 0.1.0

package/dist/serve.js

@@ -0,0 +1,166 @@
+import http from "node:http";
+import path from "node:path";
+import chokidar from "chokidar";
+import { analyzeProject } from "./index.js";
+import { diffGraphs } from "./diff.js";
+import { getDbModelsForPage, getEndpointsForPage, getPagesForDbModel, } from "./query.js";
+export async function serve(options) {
+    const projectRoot = path.resolve(options.projectRoot);
+    const port = options.port ?? 4321;
+    let currentGraph = null;
+    let previousGraph = null;
+    let isAnalyzing = false;
+    let rerunRequested = false;
+    async function runAnalysis() {
+        if (isAnalyzing) {
+            rerunRequested = true;
+            return;
+        }
+        isAnalyzing = true;
+        try {
+            const nextGraph = await analyzeProject({
+                projectRoot,
+                appDirs: options.appDirs,
+            });
+            previousGraph = currentGraph;
+            currentGraph = nextGraph;
+            const pageCount = currentGraph.nodes.filter((node) => node.type === "page").length;
+            const endpointCount = currentGraph.nodes.filter((node) => node.type === "endpoint").length;
+            const handlerCount = currentGraph.nodes.filter((node) => node.type === "handler").length;
+            const actionCount = currentGraph.nodes.filter((node) => node.type === "action").length;
+            const dbCount = currentGraph.nodes.filter((node) => node.type === "db").length;
+            const uiCount = currentGraph.nodes.filter((node) => node.type === "ui").length;
+            console.log([
+                "mode=serve",
+                `pages=${pageCount}`,
+                `actions=${actionCount}`,
+                `endpoints=${endpointCount}`,
+                `handlers=${handlerCount}`,
+                `db=${dbCount}`,
+                `ui=${uiCount}`,
+                `nodes=${currentGraph.nodes.length}`,
+                `edges=${currentGraph.edges.length}`,
+            ].join(" "));
+        }
+        catch (error) {
+            console.error("Analysis error:", error);
+        }
+        finally {
+            isAnalyzing = false;
+            if (rerunRequested) {
+                rerunRequested = false;
+                await runAnalysis();
+            }
+        }
+    }
+    await runAnalysis();
+    const watcher = chokidar.watch(projectRoot, {
+        ignored: ["**/node_modules/**", "**/.git/**", "**/.next/**", "**/arch/**"],
+        ignoreInitial: true,
+    });
+    watcher.on("all", () => {
+        void runAnalysis();
+    });
+    const server = http.createServer((req, res) => {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+        if (req.method === "OPTIONS") {
+            res.statusCode = 204;
+            res.end();
+            return;
+        }
+        const requestUrl = req.url ? new URL(req.url, `http://localhost:${port}`) : null;
+        const pathname = requestUrl?.pathname ?? "";
+        if (req.method === "GET" && pathname === "/graph") {
+            if (!currentGraph) {
+                res.statusCode = 503;
+                res.end("Graph not ready");
+                return;
+            }
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify(currentGraph));
+            return;
+        }
+        if (req.method === "GET" && pathname === "/diff") {
+            if (!currentGraph || !previousGraph) {
+                res.statusCode = 503;
+                res.end("Diff not ready");
+                return;
+            }
+            const diff = diffGraphs(previousGraph, currentGraph);
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify(diff));
+            return;
+        }
+        if (req.method === "GET" && pathname === "/query/page-to-endpoints") {
+            if (!currentGraph) {
+                res.statusCode = 503;
+                res.end("Graph not ready");
+                return;
+            }
+            const route = requestUrl?.searchParams.get("route") ?? "/";
+            const endpoints = getEndpointsForPage(currentGraph, route);
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ route, endpoints }));
+            return;
+        }
+        if (req.method === "GET" && pathname === "/query/page-to-db") {
+            if (!currentGraph) {
+                res.statusCode = 503;
+                res.end("Graph not ready");
+                return;
+            }
+            const route = requestUrl?.searchParams.get("route") ?? "/";
+            const dbModels = getDbModelsForPage(currentGraph, route);
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ route, dbModels }));
+            return;
+        }
+        if (req.method === "GET" && pathname === "/query/db-to-pages") {
+            if (!currentGraph) {
+                res.statusCode = 503;
+                res.end("Graph not ready");
+                return;
+            }
+            const model = requestUrl?.searchParams.get("model");
+            if (!model) {
+                res.statusCode = 400;
+                res.end("Missing model query parameter");
+                return;
+            }
+            const pages = getPagesForDbModel(currentGraph, model);
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ model, pages }));
+            return;
+        }
+        res.statusCode = 404;
+        res.end("Not found");
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, () => {
+            server.off("error", reject);
+            console.log(`next-arch-map serve listening on http://localhost:${port}`);
+            resolve();
+        });
+    });
+    const close = async () => {
+        await watcher.close();
+        await new Promise((resolve, reject) => {
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        });
+    };
+    process.once("SIGINT", () => {
+        void close().finally(() => process.exit(0));
+    });
+    process.once("SIGTERM", () => {
+        void close().finally(() => process.exit(0));
+    });
+}

package/dist/utils.d.ts

@@ -0,0 +1,82 @@
+import ts from "typescript";
+import type { Edge, Node } from "./model.js";
+export declare function resolveProjectRoot(projectRoot: string): string;
+export declare function resolveProjectPath(projectRoot: string, targetPath: string): string;
+export declare function directoryExists(directoryPath: string): boolean;
+export declare function fileExists(filePath: string): boolean;
+export declare function getExistingDirectories(projectRoot: string, candidateDirs: string[]): string[];
+export declare function walkDirectory(directoryPath: string): string[];
+export declare function isIgnoredSourceFile(filePath: string): boolean;
+export declare function isPageFile(filePath: string): boolean;
+export declare function isRouteHandlerFile(filePath: string): boolean;
+export declare function getPageRouteFromFile(appDir: string, filePath: string): string;
+export declare function getEndpointRouteFromFile(scanRoot: string, filePath: string): string;
+export declare function getScriptKind(filePath: string): ts.ScriptKind;
+export declare function getSourceFile(filePath: string, sourceFileCache?: Map<string, ts.SourceFile>): ts.SourceFile | null;
+export declare function resolveLocalModulePath(importerFilePath: string, specifier: string, projectRoot: string): string | null;
+export declare function ensureDirectory(directoryPath: string): void;
+export declare function readJsonFile<T>(filePath: string): T;
+export declare function writeJsonFile(filePath: string, value: unknown): void;
+export declare function buildEdgeKey(from: string, to: string, kind: string): string;
+export declare function ensureNode(nodes: Node[], nodeIds: Set<string>, node: Node): Node;
+export declare function collectStringConstants(sourceFile: ts.SourceFile): Map<string, string>;
+export declare function getStringLiteralValue(expression: ts.Expression): string | null;
+export declare function mergeMeta(baseMeta?: Record<string, any>, nextMeta?: Record<string, any>): Record<string, any> | undefined;
+export declare function mergeNode(existingNode: Node, nextNode: Node): Node;
+export declare function mergeEdge(existingEdge: Edge, nextEdge: Edge): Edge;
+export declare function buildPageNode(route: string, filePath: string): {
+    id: string;
+    type: "page";
+    label: string;
+    meta: {
+        filePath: string;
+        route: string;
+    };
+};
+export declare function buildEndpointNode(endpoint: string, filePath: string): {
+    id: string;
+    type: "endpoint";
+    label: string;
+    meta: {
+        filePath: string;
+        route: string;
+    };
+};
+export declare function buildHandlerNode(endpoint: string, filePath: string, method?: string): {
+    id: string;
+    type: "handler";
+    label: string;
+    meta: {
+        method?: string | undefined;
+        filePath: string;
+        route: string;
+    };
+};
+export declare function buildActionNode(pageRoute: string, actionId: string, filePath: string, extraMeta?: Record<string, unknown>): {
+    id: string;
+    type: "action";
+    label: string;
+    meta: {
+        filePath: string;
+        route: string;
+        actionId: string;
+    };
+};
+export declare function buildDbNode(modelName: string, filePath: string): {
+    id: string;
+    type: "db";
+    label: string;
+    meta: {
+        filePath: string;
+        model: string;
+    };
+};
+export declare function buildUiNode(componentName: string, filePath: string): {
+    id: string;
+    type: "ui";
+    label: string;
+    meta: {
+        filePath: string;
+        component: string;
+    };
+};

package/dist/utils.js

@@ -0,0 +1,306 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+const ROUTE_GROUP_PATTERN = /^\(.*\)$/;
+const SOURCE_FILE_PATTERN = /\.(ts|tsx|js|jsx)$/;
+const PAGE_FILE_PATTERN = /^page\.(ts|tsx|js|jsx)$/;
+const ROUTE_FILE_PATTERN = /^route\.(ts|tsx|js|jsx)$/;
+const SKIPPED_DIRECTORIES = new Set(["node_modules", ".git", ".next", "__tests__"]);
+export function resolveProjectRoot(projectRoot) {
+    return path.resolve(projectRoot);
+}
+export function resolveProjectPath(projectRoot, targetPath) {
+    return path.isAbsolute(targetPath) ? targetPath : path.resolve(projectRoot, targetPath);
+}
+export function directoryExists(directoryPath) {
+    return fs.existsSync(directoryPath) && fs.statSync(directoryPath).isDirectory();
+}
+export function fileExists(filePath) {
+    return fs.existsSync(filePath) && fs.statSync(filePath).isFile();
+}
+export function getExistingDirectories(projectRoot, candidateDirs) {
+    return candidateDirs
+        .map((directoryPath) => resolveProjectPath(projectRoot, directoryPath))
+        .filter(directoryExists);
+}
+export function walkDirectory(directoryPath) {
+    const files = [];
+    for (const entry of fs.readdirSync(directoryPath, { withFileTypes: true })) {
+        if (SKIPPED_DIRECTORIES.has(entry.name)) {
+            continue;
+        }
+        const entryPath = path.join(directoryPath, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...walkDirectory(entryPath));
+            continue;
+        }
+        if (SOURCE_FILE_PATTERN.test(entry.name)) {
+            files.push(entryPath);
+        }
+    }
+    return files;
+}
+export function isIgnoredSourceFile(filePath) {
+    return (!SOURCE_FILE_PATTERN.test(filePath) ||
+        filePath.endsWith(".test.ts") ||
+        filePath.endsWith(".test.tsx") ||
+        filePath.endsWith(".test.js") ||
+        filePath.endsWith(".test.jsx"));
+}
+export function isPageFile(filePath) {
+    return PAGE_FILE_PATTERN.test(path.basename(filePath));
+}
+export function isRouteHandlerFile(filePath) {
+    return ROUTE_FILE_PATTERN.test(path.basename(filePath));
+}
+export function getPageRouteFromFile(appDir, filePath) {
+    const segments = path.relative(appDir, filePath).split(path.sep).filter(Boolean);
+    if (segments.length === 0) {
+        return "/";
+    }
+    segments.pop();
+    const routeSegments = segments
+        .filter((segment) => !ROUTE_GROUP_PATTERN.test(segment))
+        .map(decodeRouteSegment);
+    return routeSegments.length === 0 ? "/" : `/${routeSegments.join("/")}`;
+}
+export function getEndpointRouteFromFile(scanRoot, filePath) {
+    const segments = path.relative(scanRoot, filePath).split(path.sep).filter(Boolean);
+    const fileName = segments.pop() ?? "";
+    const routeSegments = segments
+        .filter((segment) => !ROUTE_GROUP_PATTERN.test(segment))
+        .map(decodeRouteSegment);
+    const prefixedSegments = [...getEndpointPrefixSegments(scanRoot), ...routeSegments].filter(Boolean);
+    if (!ROUTE_FILE_PATTERN.test(fileName)) {
+        return prefixedSegments.length === 0 ? "/" : `/${prefixedSegments.join("/")}`;
+    }
+    if (prefixedSegments.length > 1 &&
+        prefixedSegments[0] === prefixedSegments[1]) {
+        prefixedSegments.shift();
+    }
+    return prefixedSegments.length === 0 ? "/" : `/${prefixedSegments.join("/")}`;
+}
+function getEndpointPrefixSegments(scanRoot) {
+    const normalized = scanRoot.replace(/\\/g, "/");
+    if (normalized.endsWith("/app/api") || normalized.endsWith("/src/app/api")) {
+        return ["api"];
+    }
+    if (normalized.endsWith("/src/api") || path.basename(scanRoot) === "api") {
+        return ["api"];
+    }
+    if (normalized.endsWith("/src/server") || path.basename(scanRoot) === "server") {
+        return ["server"];
+    }
+    return [];
+}
+function decodeRouteSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+export function getScriptKind(filePath) {
+    if (filePath.endsWith(".tsx")) {
+        return ts.ScriptKind.TSX;
+    }
+    if (filePath.endsWith(".jsx")) {
+        return ts.ScriptKind.JSX;
+    }
+    if (filePath.endsWith(".js")) {
+        return ts.ScriptKind.JS;
+    }
+    return ts.ScriptKind.TS;
+}
+export function getSourceFile(filePath, sourceFileCache) {
+    const cachedSourceFile = sourceFileCache?.get(filePath);
+    if (cachedSourceFile) {
+        return cachedSourceFile;
+    }
+    try {
+        const sourceFile = ts.createSourceFile(filePath, fs.readFileSync(filePath, "utf8"), ts.ScriptTarget.Latest, true, getScriptKind(filePath));
+        sourceFileCache?.set(filePath, sourceFile);
+        return sourceFile;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveLocalModulePath(importerFilePath, specifier, projectRoot) {
+    let basePath = null;
+    if (specifier.startsWith("./") || specifier.startsWith("../")) {
+        basePath = path.resolve(path.dirname(importerFilePath), specifier);
+    }
+    else if (specifier.startsWith("@/")) {
+        basePath = path.join(projectRoot, "src", specifier.slice(2));
+    }
+    if (!basePath) {
+        return null;
+    }
+    const candidates = [
+        basePath,
+        `${basePath}.ts`,
+        `${basePath}.tsx`,
+        `${basePath}.js`,
+        `${basePath}.jsx`,
+        path.join(basePath, "index.ts"),
+        path.join(basePath, "index.tsx"),
+        path.join(basePath, "index.js"),
+        path.join(basePath, "index.jsx"),
+    ];
+    for (const candidate of candidates) {
+        if (fileExists(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export function ensureDirectory(directoryPath) {
+    fs.mkdirSync(directoryPath, { recursive: true });
+}
+export function readJsonFile(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+export function writeJsonFile(filePath, value) {
+    ensureDirectory(path.dirname(filePath));
+    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+export function buildEdgeKey(from, to, kind) {
+    return `${from}::${to}::${kind}`;
+}
+export function ensureNode(nodes, nodeIds, node) {
+    if (nodeIds.has(node.id)) {
+        const existingNodeIndex = nodes.findIndex((entry) => entry.id === node.id);
+        if (existingNodeIndex === -1) {
+            return node;
+        }
+        const mergedNode = mergeNode(nodes[existingNodeIndex], node);
+        nodes[existingNodeIndex] = mergedNode;
+        return mergedNode;
+    }
+    nodeIds.add(node.id);
+    nodes.push(node);
+    return node;
+}
+export function collectStringConstants(sourceFile) {
+    const constMap = new Map();
+    const visitNode = (node) => {
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.initializer &&
+            ts.isVariableDeclarationList(node.parent) &&
+            (node.parent.flags & ts.NodeFlags.Const) !== 0) {
+            const stringValue = getStringLiteralValue(node.initializer);
+            if (stringValue !== null) {
+                constMap.set(node.name.text, stringValue);
+            }
+        }
+        ts.forEachChild(node, visitNode);
+    };
+    visitNode(sourceFile);
+    return constMap;
+}
+export function getStringLiteralValue(expression) {
+    if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) {
+        return expression.text;
+    }
+    return null;
+}
+export function mergeMeta(baseMeta, nextMeta) {
+    if (!baseMeta) {
+        return nextMeta;
+    }
+    if (!nextMeta) {
+        return baseMeta;
+    }
+    return {
+        ...baseMeta,
+        ...nextMeta,
+    };
+}
+export function mergeNode(existingNode, nextNode) {
+    return {
+        ...existingNode,
+        ...nextNode,
+        meta: mergeMeta(existingNode.meta, nextNode.meta),
+    };
+}
+export function mergeEdge(existingEdge, nextEdge) {
+    return {
+        ...existingEdge,
+        ...nextEdge,
+        meta: mergeMeta(existingEdge.meta, nextEdge.meta),
+    };
+}
+export function buildPageNode(route, filePath) {
+    return {
+        id: `page:${route}`,
+        type: "page",
+        label: route,
+        meta: {
+            filePath,
+            route,
+        },
+    };
+}
+export function buildEndpointNode(endpoint, filePath) {
+    return {
+        id: `endpoint:${endpoint}`,
+        type: "endpoint",
+        label: endpoint,
+        meta: {
+            filePath,
+            route: endpoint,
+        },
+    };
+}
+export function buildHandlerNode(endpoint, filePath, method) {
+    const label = method ? `${endpoint}#${method}` : endpoint;
+    return {
+        id: method ? `handler:${endpoint}:${method}` : `handler:${endpoint}`,
+        type: "handler",
+        label,
+        meta: {
+            filePath,
+            route: endpoint,
+            ...(method ? { method } : {}),
+        },
+    };
+}
+export function buildActionNode(pageRoute, actionId, filePath, extraMeta) {
+    const label = actionId;
+    return {
+        id: `action:${pageRoute}:${actionId}`,
+        type: "action",
+        label,
+        meta: {
+            filePath,
+            route: pageRoute,
+            actionId,
+            ...(extraMeta ?? {}),
+        },
+    };
+}
+export function buildDbNode(modelName, filePath) {
+    return {
+        id: `db:${modelName}`,
+        type: "db",
+        label: modelName,
+        meta: {
+            filePath,
+            model: modelName,
+        },
+    };
+}
+export function buildUiNode(componentName, filePath) {
+    return {
+        id: `ui:${componentName}`,
+        type: "ui",
+        label: componentName,
+        meta: {
+            filePath,
+            component: componentName,
+        },
+    };
+}

package/examples/nextjs-dev-route.md

@@ -0,0 +1,25 @@
+# Next.js Dev Route Integration
+
+1. Add a script in your Next.js app:
+
+```json
+{
+  "scripts": {
+    "arch:graph": "next-arch-map analyze --project-root . --out arch/graph.full.json"
+  }
+}
+```
+
+2. Run the analyzer before visiting your dev-only architecture route:
+
+```bash
+npm run arch:graph
+```
+
+3. In your Next.js `_dev/routes` page, read `arch/graph.full.json` on the server and pass it into a client-side inspector UI.
+
+4. In the UI:
+
+- render the route graph on the left
+- show page, endpoint, DB, and UI summaries in the sidebar
+- when a page is selected, derive its reachable endpoints and DB entities from the graph edges

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "next-arch-map",
+  "version": "0.1.0",
+  "description": "Static analyzer that builds a multi-layer architecture graph for Next.js-style apps.",
+  "type": "module",
+  "bin": {
+    "next-arch-map": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./model": {
+      "types": "./dist/model.d.ts",
+      "import": "./dist/model.js"
+    }
+  },
+  "files": [
+    "dist",
+    "viewer",
+    "README.md",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "dev": "node dist/cli.js dev"
+  },
+  "keywords": [
+    "nextjs",
+    "architecture",
+    "graph",
+    "static-analysis",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jesuscasal23/next-arch-map"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "chokidar": "^3.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "typescript": "^5.8.2"
+  }
+}

package/viewer/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>next-arch-map viewer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+  </html>