next-arch-map 0.1.22 → 0.1.24

package/dist/cli.js

@@ -3,6 +3,7 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { analyzeProject, diffGraphs } from "./index.js";
+import { captureScreenshots, generateParamsTemplate, } from "./screenshot.js";
 import { serve } from "./serve.js";
 import { readJsonFile, writeJsonFile } from "./utils.js";
 async function main() {
@@ -17,6 +18,28 @@ async function main() {
         await serve(options);
         return;
     }
+    if (commandOrArg === "screenshot") {
+        const options = parseScreenshotArgs(rest);
+        if (options.generateParams) {
+            generateParamsTemplate({
+                graphPath: path.resolve(options.graphPath),
+                outPath: path.resolve(options.paramsPath),
+            });
+            console.log(`params template written to ${options.paramsPath}`);
+            return;
+        }
+        if (!options.baseUrl) {
+            throw new Error("The screenshot command requires --base-url <url>.");
+        }
+        const result = await captureScreenshots({
+            baseUrl: options.baseUrl,
+            graphPath: path.resolve(options.graphPath),
+            outDir: path.resolve(options.outDir),
+            paramsPath: path.resolve(options.paramsPath),
+        });
+        logScreenshotSummary(result);
+        return;
+    }
     if (commandOrArg === "diff") {
         const options = parseDiffArgs(rest);
         const beforePath = path.resolve(options.beforePath);
@@ -198,6 +221,46 @@ function parseDevArgs(args) {
         appDirs: appDirs.length > 0 ? appDirs : undefined,
     };
 }
+function parseScreenshotArgs(args) {
+    let baseUrl = "";
+    let graphPath = "arch/graph.full.json";
+    let outDir = "arch/screenshots";
+    let paramsPath = "arch/screenshot-params.json";
+    let generateParams = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--base-url" && args[index + 1]) {
+            baseUrl = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (argument === "--graph" && args[index + 1]) {
+            graphPath = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (argument === "--out-dir" && args[index + 1]) {
+            outDir = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (argument === "--params" && args[index + 1]) {
+            paramsPath = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (argument === "--generate-params") {
+            generateParams = true;
+            continue;
+        }
+        if (argument === "--help" || argument === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+    return { baseUrl, graphPath, outDir, paramsPath, generateParams };
+}
 async function runDev(options) {
     const children = [];
     const cleanup = () => {
@@ -292,9 +355,13 @@ function logDiffSummary(diff, beforePath, afterPath, outputFile) {
         `removedEdges=${removedEdges}`,
     ].join(" "));
 }
+function logScreenshotSummary(result) {
+    console.log([`mode=screenshot`, `captured=${result.captured}`, `skipped=${result.skipped}`].join(" "));
+}
 function printHelp() {
     console.log(`next-arch-map analyze [options]
 next-arch-map diff --before <path> --after <path> [--out <path>]
+next-arch-map screenshot [options]
 next-arch-map serve [options]
 next-arch-map dev [options]
 
@@ -308,6 +375,13 @@ Diff options:
   --after <path>         Path to the updated graph JSON.
   --out <path>           Output diff JSON path. Defaults to arch/graph.diff.json.
 
+Screenshot options:
+  --base-url <url>       Base URL of the running app (e.g. http://localhost:3000).
+  --graph <path>         Path to graph JSON. Defaults to arch/graph.full.json.
+  --out-dir <path>       Directory for screenshot PNGs. Defaults to arch/screenshots.
+  --params <path>        Path to params JSON. Defaults to arch/screenshot-params.json.
+  --generate-params      Generate a params template for dynamic routes and exit.
+
 Serve options:
   --project-root <path>  Project root to analyze. Defaults to the current working directory.
   --port <number>        Port to listen on. Defaults to 4321.

package/dist/index.d.ts

@@ -16,3 +16,4 @@ export { analyzePagesToEndpoints } from "./analyzers/pagesToEndpoints.js";
 export { analyzeEndpointsToDb } from "./analyzers/endpointsToDb.js";
 export { mergeGraphs, mergePartial } from "./merge.js";
 export { getDbModelsForPage, getEndpointsForPage, getPagesForDbModel } from "./query.js";
+export { captureScreenshots, generateParamsTemplate } from "./screenshot.js";

package/dist/index.js

@@ -21,3 +21,4 @@ export { analyzePagesToEndpoints } from "./analyzers/pagesToEndpoints.js";
 export { analyzeEndpointsToDb } from "./analyzers/endpointsToDb.js";
 export { mergeGraphs, mergePartial } from "./merge.js";
 export { getDbModelsForPage, getEndpointsForPage, getPagesForDbModel } from "./query.js";
+export { captureScreenshots, generateParamsTemplate } from "./screenshot.js";

package/dist/screenshot.d.ts

@@ -0,0 +1,22 @@
+import type { Graph } from "./model.js";
+export declare function isDynamicRoute(route: string): boolean;
+export declare function extractRouteParamNames(route: string): string[];
+export declare function resolveRoute(route: string, params: Record<string, string>): string;
+export declare function sanitizeFilename(route: string): string;
+export type GenerateParamsOptions = {
+    graphPath: string;
+    outPath: string;
+};
+export declare function generateParamsTemplate(options: GenerateParamsOptions): void;
+export type CaptureScreenshotsOptions = {
+    baseUrl: string;
+    graphPath: string;
+    outDir: string;
+    paramsPath?: string;
+};
+export type CaptureResult = {
+    graph: Graph;
+    captured: number;
+    skipped: number;
+};
+export declare function captureScreenshots(options: CaptureScreenshotsOptions): Promise<CaptureResult>;

package/dist/screenshot.js

@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readJsonFile, writeJsonFile } from "./utils.js";
+const DYNAMIC_SEGMENT_PATTERN = /\[[\w.]+\]/;
+const PARAM_SEGMENT_PATTERN = /\[{1,2}(?:\.{3})?(\w+)\]{1,2}/g;
+export function isDynamicRoute(route) {
+    return DYNAMIC_SEGMENT_PATTERN.test(route);
+}
+export function extractRouteParamNames(route) {
+    const names = [];
+    for (const match of route.matchAll(PARAM_SEGMENT_PATTERN)) {
+        names.push(match[1]);
+    }
+    return names;
+}
+export function resolveRoute(route, params) {
+    return route.replace(PARAM_SEGMENT_PATTERN, (_match, name) => {
+        return params[name] ?? _match;
+    });
+}
+export function sanitizeFilename(route) {
+    if (route === "/")
+        return "index.png";
+    const name = route
+        .replace(/^\//, "")
+        .replace(/\//g, "-");
+    return `${name}.png`;
+}
+export function generateParamsTemplate(options) {
+    const graph = readJsonFile(options.graphPath);
+    const template = {};
+    for (const node of graph.nodes) {
+        if (node.type !== "page")
+            continue;
+        const route = node.meta?.route ?? node.label;
+        if (!isDynamicRoute(String(route)))
+            continue;
+        const paramNames = extractRouteParamNames(String(route));
+        const params = {};
+        for (const name of paramNames) {
+            params[name] = "";
+        }
+        template[String(route)] = params;
+    }
+    writeJsonFile(options.outPath, template);
+}
+export async function captureScreenshots(options) {
+    let playwright;
+    try {
+        const moduleName = "playwright";
+        playwright = await import(/* webpackIgnore: true */ moduleName);
+    }
+    catch {
+        throw new Error("Playwright is required for screenshots. Install it with: npm install playwright");
+    }
+    const graph = readJsonFile(options.graphPath);
+    const params = options.paramsPath &&
+        fs.existsSync(options.paramsPath)
+        ? readJsonFile(options.paramsPath)
+        : {};
+    const pageNodes = graph.nodes
+        .filter((node) => node.type === "page")
+        .sort((a, b) => a.label.localeCompare(b.label));
+    let captured = 0;
+    let skipped = 0;
+    const browser = await playwright.chromium.launch();
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    try {
+        for (const node of pageNodes) {
+            const route = String(node.meta?.route ?? node.label);
+            if (isDynamicRoute(route)) {
+                const routeParams = params[route];
+                if (!routeParams || Object.values(routeParams).some((v) => !v)) {
+                    console.log(`skipped ${route} (missing params)`);
+                    skipped += 1;
+                    continue;
+                }
+                const resolved = resolveRoute(route, routeParams);
+                try {
+                    await capturePageScreenshot(page, node, resolved, options);
+                    captured += 1;
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    console.log(`failed ${route}: ${message}`);
+                    skipped += 1;
+                }
+            }
+            else {
+                try {
+                    await capturePageScreenshot(page, node, route, options);
+                    captured += 1;
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    console.log(`failed ${route}: ${message}`);
+                    skipped += 1;
+                }
+            }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    writeJsonFile(options.graphPath, graph);
+    return { graph, captured, skipped };
+}
+async function capturePageScreenshot(page, node, resolvedRoute, options) {
+    const url = options.baseUrl.replace(/\/$/, "") + resolvedRoute;
+    await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 });
+    const buffer = await page.screenshot({ fullPage: true });
+    fs.mkdirSync(options.outDir, { recursive: true });
+    const filename = sanitizeFilename(resolvedRoute);
+    fs.writeFileSync(path.join(options.outDir, filename), buffer);
+    if (!node.meta)
+        node.meta = {};
+    node.meta.screenshot = `data:image/png;base64,${buffer.toString("base64")}`;
+    console.log(`captured ${resolvedRoute} → ${filename}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-arch-map",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Static analyzer that builds a multi-layer architecture graph for Next.js-style apps.",
   "type": "module",
   "bin": {
@@ -47,6 +47,14 @@
     "chokidar": "^3.6.0",
     "typescript": "^5.8.2"
   },
+  "peerDependencies": {
+    "playwright": ">=1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^20.19.0",

package/viewer/src/App.tsx

@@ -9,15 +9,12 @@ const ALL_NODE_TYPES: NodeType[] = [
   "page",
   "endpoint",
   "handler",
-  "action",
   "db",
 ];
 const ALL_EDGE_KINDS: EdgeKind[] = [
   "page-endpoint",
   "endpoint-db",
   "endpoint-handler",
-  "page-action",
-  "action-endpoint",
 ];
 
 

package/viewer/src/Filters.tsx

@@ -15,7 +15,6 @@ const NODE_TYPE_COLORS: Record<NodeType, string> = {
   page: "bg-blue-500",
   endpoint: "bg-emerald-600",
   handler: "bg-teal-500",
-  action: "bg-amber-400",
   db: "bg-red-600",
 };
 

package/viewer/src/GraphView.tsx

@@ -31,7 +31,6 @@ const NODE_COLOR: Record<NodeType, string> = {
   endpoint: "#059669",
   db: "#dc2626",
   handler: "#14b8a6",
-  action: "#fbbf24",
 };
 
 const NODE_BORDER: Record<NodeType, string> = {
@@ -39,15 +38,12 @@ const NODE_BORDER: Record<NodeType, string> = {
   endpoint: "#047857",
   db: "#b91c1c",
   handler: "#0d9488",
-  action: "#f59e0b",
 };
 
 const EDGE_COLOR: Record<EdgeKind, string> = {
   "page-endpoint": "#06b6d4",
   "endpoint-db": "#f97316",
   "endpoint-handler": "#22c55e",
-  "page-action": "#eab308",
-  "action-endpoint": "#a855f7",
 };
 
 const DIFF_BORDER_COLOR: Record<DiffStatus, string> = {
@@ -141,14 +137,34 @@ function reorderColumn(
   nodes.forEach((node, i) => nodeRowIndex.set(node.id, i));
 }
 
+function DescriptionLine({ text, dark }: { text: string; dark?: boolean }) {
+  return (
+    <div
+      style={{
+        marginTop: 3,
+        fontSize: 10,
+        fontWeight: 400,
+        opacity: 0.85,
+        lineHeight: 1.3,
+        color: dark ? "#1e293b" : "#ffffff",
+      }}
+    >
+      {text}
+    </div>
+  );
+}
+
 function PageNode({ data }: NodeProps) {
-  const screenshot = (data as Record<string, unknown>).screenshot as string | undefined;
+  const d = data as Record<string, unknown>;
+  const screenshot = d.screenshot as string | undefined;
+  const description = d.description as string | undefined;
   return (
     <div>
       <Handle type="target" position={Position.Left} style={{ visibility: "hidden" }} />
       <div style={{ fontSize: 12, fontWeight: 600 }}>
-        {String((data as Record<string, unknown>).label ?? "")}
+        {String(d.label ?? "")}
       </div>
+      {description && <DescriptionLine text={description} />}
       {screenshot && (
         <img
           src={screenshot}
@@ -166,7 +182,26 @@ function PageNode({ data }: NodeProps) {
   );
 }
 
-const nodeTypes = { pageNode: PageNode };
+function DescribedNode({ data }: NodeProps) {
+  const d = data as Record<string, unknown>;
+  const description = d.description as string | undefined;
+  const dark = d.dark as boolean | undefined;
+  return (
+    <div>
+      <Handle type="target" position={Position.Left} style={{ visibility: "hidden" }} />
+      <div style={{ fontSize: 12, fontWeight: 600 }}>
+        {String(d.label ?? "")}
+      </div>
+      {description && <DescriptionLine text={description} dark={dark} />}
+      <Handle type="source" position={Position.Right} style={{ visibility: "hidden" }} />
+    </div>
+  );
+}
+
+const nodeTypes = {
+  pageNode: PageNode,
+  describedNode: DescribedNode,
+};
 
 export function GraphView(props: GraphViewProps) {
   const {
@@ -202,7 +237,7 @@ export function GraphView(props: GraphViewProps) {
 
   // Compute layout without hover state — this is the expensive part
   const { flowNodes: baseFlowNodes, flowEdges: baseFlowEdges } = useMemo(() => {
-    const typeOrder: NodeType[] = ["page", "action", "endpoint", "handler", "db"];
+    const typeOrder: NodeType[] = ["page", "endpoint", "handler", "db"];
     const visibleNodes = graph.nodes.filter((node) => visibleNodeTypes.has(node.type));
     const visibleNodeIds = new Set(visibleNodes.map((node) => node.id));
     const nodesByType = new Map<NodeType, typeof visibleNodes>(
@@ -238,11 +273,24 @@ export function GraphView(props: GraphViewProps) {
         const borderStyle = status === "removed" ? "dashed" : "solid";
         const isPage = node.type === "page";
         const screenshot = isPage ? (node.meta?.screenshot as string | undefined) : undefined;
+        const description = node.meta?.description as string | undefined;
+        const isDarkText = false;
+
+        const nodeType = isPage
+          ? "pageNode"
+          : description
+            ? "describedNode"
+            : undefined;
 
         flowNodes.push({
           id: node.id,
-          ...(isPage ? { type: "pageNode" } : {}),
-          data: { label: node.label, ...(screenshot ? { screenshot } : {}) },
+          ...(nodeType ? { type: nodeType } : {}),
+          data: {
+            label: node.label,
+            ...(screenshot ? { screenshot } : {}),
+            ...(description ? { description } : {}),
+            ...(isDarkText ? { dark: true } : {}),
+          },
           position: {
             x: 80 + columnIndex * columnWidth,
             y: 80 + rowIndex * rowHeight,
@@ -256,7 +304,7 @@ export function GraphView(props: GraphViewProps) {
             border: `2px ${borderStyle} ${borderColor}`,
             padding: "10px 14px",
             background: NODE_COLOR[node.type],
-            color: node.type === "action" ? "#1e293b" : "#ffffff",
+            color: "#ffffff",
             fontSize: 12,
             fontWeight: 600,
             fontFamily: "'Inter', -apple-system, sans-serif",

package/viewer/src/NodeDetails.tsx

@@ -46,6 +46,12 @@ export function NodeDetails({ node }: NodeDetailsProps) {
           {node.id}
         </div>
 
+        {(node.meta?.descriptionLong || node.meta?.description) && (
+          <p className="text-xs text-slate-600 leading-relaxed">
+            {String(node.meta.descriptionLong ?? node.meta.description)}
+          </p>
+        )}
+
         {filePath !== undefined && filePath !== null && (
           <div className="text-[11px] text-slate-500">
             <span className="text-slate-400">file: </span>
@@ -53,9 +59,27 @@ export function NodeDetails({ node }: NodeDetailsProps) {
           </div>
         )}
 
+        {node.meta?.screenshot && (
+          <div className="mt-2">
+            <img
+              src={String(node.meta.screenshot)}
+              alt={`Screenshot of ${node.label}`}
+              className="w-full rounded-md border border-slate-200"
+            />
+          </div>
+        )}
+
         {node.meta && (
           <pre className="mt-2 p-2.5 rounded-md bg-slate-50 border border-slate-100 text-[11px] font-mono text-slate-600 max-h-40 overflow-auto whitespace-pre-wrap break-all">
-            {JSON.stringify(node.meta, null, 2)}
+            {JSON.stringify(
+              Object.fromEntries(
+                Object.entries(node.meta).filter(
+                  ([key]) => key !== "screenshot" && key !== "description" && key !== "descriptionLong",
+                ),
+              ),
+              null,
+              2,
+            )}
           </pre>
         )}
       </div>

package/viewer/src/types.ts

@@ -2,8 +2,7 @@ export type NodeType =
   | "page"
   | "endpoint"
   | "db"
-  | "handler"
-  | "action";
+  | "handler";
 
 export type Node = {
   id: string;