next-arch-map 0.1.0

package/dist/cli.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { analyzeProject, diffGraphs } from "./index.js";
+import { serve } from "./serve.js";
+import { readJsonFile, writeJsonFile } from "./utils.js";
+async function main() {
+    const [commandOrArg, ...rest] = process.argv.slice(2);
+    if (commandOrArg === "dev") {
+        const options = parseDevArgs(rest);
+        await runDev(options);
+        return;
+    }
+    if (commandOrArg === "serve") {
+        const options = parseServeArgs(rest);
+        await serve(options);
+        return;
+    }
+    if (commandOrArg === "diff") {
+        const options = parseDiffArgs(rest);
+        const beforePath = path.resolve(options.beforePath);
+        const afterPath = path.resolve(options.afterPath);
+        const outputFile = path.resolve(options.out);
+        const beforeGraph = readJsonFile(beforePath);
+        const afterGraph = readJsonFile(afterPath);
+        const diff = diffGraphs(beforeGraph, afterGraph);
+        writeJsonFile(outputFile, diff);
+        logDiffSummary(diff, beforePath, afterPath, outputFile);
+        return;
+    }
+    const analyzeArgs = commandOrArg === "analyze" ? rest : process.argv.slice(2);
+    const options = parseAnalyzeArgs(analyzeArgs);
+    const graph = await analyzeProject({
+        projectRoot: options.projectRoot,
+        appDirs: options.appDirs,
+    });
+    const outputFile = path.resolve(options.projectRoot, options.out);
+    writeJsonFile(outputFile, graph);
+    logAnalyzeSummary(graph, outputFile, options.projectRoot);
+}
+function parseAnalyzeArgs(args) {
+    let projectRoot = process.cwd();
+    let out = "arch/graph.full.json";
+    const appDirs = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--project-root" && args[index + 1]) {
+            projectRoot = path.resolve(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (argument === "--out" && args[index + 1]) {
+            out = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (argument === "--app-dir" && args[index + 1]) {
+            appDirs.push(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (argument === "--help" || argument === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+    return {
+        projectRoot,
+        out,
+        appDirs: appDirs.length > 0 ? appDirs : undefined,
+    };
+}
+function parseDiffArgs(args) {
+    let beforePath = "";
+    let afterPath = "";
+    let out = "arch/graph.diff.json";
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--before" && args[index + 1]) {
+            beforePath = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (argument === "--after" && args[index + 1]) {
+            afterPath = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (argument === "--out" && args[index + 1]) {
+            out = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (argument === "--help" || argument === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+    if (!beforePath || !afterPath) {
+        throw new Error("The diff command requires --before <path> and --after <path>.");
+    }
+    return {
+        beforePath,
+        afterPath,
+        out,
+    };
+}
+function parseServeArgs(args) {
+    let projectRoot = process.cwd();
+    let port = 4321;
+    const appDirs = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--project-root" && args[index + 1]) {
+            projectRoot = path.resolve(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (argument === "--port" && args[index + 1]) {
+            port = Number(args[index + 1]);
+            if (!Number.isInteger(port) || port <= 0) {
+                throw new Error(`Invalid port: ${args[index + 1]}`);
+            }
+            index += 1;
+            continue;
+        }
+        if (argument === "--app-dir" && args[index + 1]) {
+            appDirs.push(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (argument === "--help" || argument === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+    return {
+        projectRoot,
+        port,
+        appDirs: appDirs.length > 0 ? appDirs : undefined,
+    };
+}
+function parseDevArgs(args) {
+    let projectRoot = process.cwd();
+    let port = 4321;
+    let viewerDir = "";
+    const appDirs = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--project-root" && args[index + 1]) {
+            projectRoot = path.resolve(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (argument === "--port" && args[index + 1]) {
+            port = Number(args[index + 1]);
+            if (!Number.isInteger(port) || port <= 0) {
+                throw new Error(`Invalid port: ${args[index + 1]}`);
+            }
+            index += 1;
+            continue;
+        }
+        if (argument === "--viewer-dir" && args[index + 1]) {
+            viewerDir = path.resolve(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (argument === "--app-dir" && args[index + 1]) {
+            appDirs.push(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (argument === "--help" || argument === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+    if (!viewerDir) {
+        // Try to find the viewer relative to the analyzer package
+        const packageDir = path.dirname(path.dirname(new URL(import.meta.url).pathname));
+        const builtinViewer = path.join(packageDir, "viewer");
+        if (fs.existsSync(path.join(builtinViewer, "package.json"))) {
+            viewerDir = builtinViewer;
+        }
+        if (!viewerDir) {
+            throw new Error("Could not find viewer directory. Provide --viewer-dir <path> pointing to the viewer app.");
+        }
+    }
+    return {
+        projectRoot,
+        port,
+        viewerDir,
+        appDirs: appDirs.length > 0 ? appDirs : undefined,
+    };
+}
+async function runDev(options) {
+    const children = [];
+    const cleanup = () => {
+        for (const child of children) {
+            child.kill("SIGTERM");
+        }
+    };
+    process.once("SIGINT", () => {
+        cleanup();
+        process.exit(0);
+    });
+    process.once("SIGTERM", () => {
+        cleanup();
+        process.exit(0);
+    });
+    // Start the analyzer serve process
+    const serveProcess = spawn(process.execPath, [
+        path.resolve(path.dirname(new URL(import.meta.url).pathname), "cli.js"),
+        "serve",
+        "--project-root",
+        options.projectRoot,
+        "--port",
+        String(options.port),
+        ...(options.appDirs ?? []).flatMap((dir) => ["--app-dir", dir]),
+    ], { stdio: "inherit" });
+    children.push(serveProcess);
+    // Start the viewer dev server
+    const viewerProcess = spawn("npm", ["run", "dev"], {
+        cwd: options.viewerDir,
+        stdio: "inherit",
+        shell: process.platform === "win32",
+    });
+    children.push(viewerProcess);
+    // If either process exits, tear down the other
+    const onExit = (name) => (code) => {
+        console.log(`${name} exited with code ${code}`);
+        cleanup();
+        process.exit(code ?? 1);
+    };
+    serveProcess.once("exit", onExit("analyzer"));
+    viewerProcess.once("exit", onExit("viewer"));
+    // Keep the process alive
+    await new Promise(() => { });
+}
+function logAnalyzeSummary(graph, outputFile, projectRoot) {
+    const pageCount = graph.nodes.filter((node) => node.type === "page").length;
+    const endpointCount = graph.nodes.filter((node) => node.type === "endpoint").length;
+    const dbCount = graph.nodes.filter((node) => node.type === "db").length;
+    const uiCount = graph.nodes.filter((node) => node.type === "ui").length;
+    console.log([
+        `pages=${pageCount}`,
+        `endpoints=${endpointCount}`,
+        `db=${dbCount}`,
+        `ui=${uiCount}`,
+        `edges=${graph.edges.length}`,
+        `file=${path.relative(projectRoot, outputFile)}`,
+    ].join(" "));
+}
+function logDiffSummary(diff, beforePath, afterPath, outputFile) {
+    const addedNodes = diff.nodes.filter((node) => node.status === "added").length;
+    const removedNodes = diff.nodes.filter((node) => node.status === "removed").length;
+    const addedEdges = diff.edges.filter((edge) => edge.status === "added").length;
+    const removedEdges = diff.edges.filter((edge) => edge.status === "removed").length;
+    console.log([
+        "mode=diff",
+        `before=${path.relative(process.cwd(), beforePath)}`,
+        `after=${path.relative(process.cwd(), afterPath)}`,
+        `out=${path.relative(process.cwd(), outputFile)}`,
+        `nodes=${diff.nodes.length}`,
+        `edges=${diff.edges.length}`,
+        `addedNodes=${addedNodes}`,
+        `removedNodes=${removedNodes}`,
+        `addedEdges=${addedEdges}`,
+        `removedEdges=${removedEdges}`,
+    ].join(" "));
+}
+function printHelp() {
+    console.log(`next-arch-map analyze [options]
+next-arch-map diff --before <path> --after <path> [--out <path>]
+next-arch-map serve [options]
+next-arch-map dev [options]
+
+Analyze options:
+  --project-root <path>  Project root to analyze. Defaults to the current working directory.
+  --out <path>           Output JSON path, relative to the project root by default.
+  --app-dir <path>       App Router directory to scan. Can be provided multiple times.
+
+Diff options:
+  --before <path>        Path to the baseline graph JSON.
+  --after <path>         Path to the updated graph JSON.
+  --out <path>           Output diff JSON path. Defaults to arch/graph.diff.json.
+
+Serve options:
+  --project-root <path>  Project root to analyze. Defaults to the current working directory.
+  --port <number>        Port to listen on. Defaults to 4321.
+  --app-dir <path>       App Router directory to scan. Can be provided multiple times.
+
+Dev options:
+  --project-root <path>  Project root to analyze. Defaults to the current working directory.
+  --port <number>        Port for the analyzer server. Defaults to 4321.
+  --viewer-dir <path>    Path to the viewer app. Auto-detected if bundled with the package.
+  --app-dir <path>       App Router directory to scan. Can be provided multiple times.
+
+General:
+  --help                 Show this help message.`);
+}
+void main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+});

package/dist/diff.d.ts

@@ -0,0 +1,15 @@
+import type { Edge, Graph, Node } from "./model.js";
+export type DiffStatus = "added" | "removed" | "modified" | "unchanged";
+export type NodeDiff = {
+    node: Node;
+    status: DiffStatus;
+};
+export type EdgeDiff = {
+    edge: Edge;
+    status: DiffStatus;
+};
+export type GraphDiff = {
+    nodes: NodeDiff[];
+    edges: EdgeDiff[];
+};
+export declare function diffGraphs(before: Graph, after: Graph): GraphDiff;

package/dist/diff.js

@@ -0,0 +1,68 @@
+import { buildEdgeKey } from "./utils.js";
+function nodeEqual(a, b) {
+    return a.type === b.type && a.label === b.label && JSON.stringify(a.meta) === JSON.stringify(b.meta);
+}
+function edgeEqual(a, b) {
+    return JSON.stringify(a.meta) === JSON.stringify(b.meta);
+}
+export function diffGraphs(before, after) {
+    const beforeNodes = new Map();
+    const afterNodes = new Map();
+    const beforeEdges = new Map();
+    const afterEdges = new Map();
+    for (const node of before.nodes) {
+        beforeNodes.set(node.id, node);
+    }
+    for (const node of after.nodes) {
+        afterNodes.set(node.id, node);
+    }
+    for (const edge of before.edges) {
+        beforeEdges.set(buildEdgeKey(edge.from, edge.to, edge.kind), edge);
+    }
+    for (const edge of after.edges) {
+        afterEdges.set(buildEdgeKey(edge.from, edge.to, edge.kind), edge);
+    }
+    const nodes = [];
+    const edges = [];
+    const allNodeKeys = new Set([...beforeNodes.keys(), ...afterNodes.keys()]);
+    for (const key of allNodeKeys) {
+        const beforeNode = beforeNodes.get(key);
+        const afterNode = afterNodes.get(key);
+        if (beforeNode && !afterNode) {
+            nodes.push({ node: beforeNode, status: "removed" });
+            continue;
+        }
+        if (!beforeNode && afterNode) {
+            nodes.push({ node: afterNode, status: "added" });
+            continue;
+        }
+        if (beforeNode && afterNode) {
+            const status = nodeEqual(beforeNode, afterNode) ? "unchanged" : "modified";
+            nodes.push({ node: afterNode, status });
+        }
+    }
+    const allEdgeKeys = new Set([...beforeEdges.keys(), ...afterEdges.keys()]);
+    for (const key of allEdgeKeys) {
+        const beforeEdge = beforeEdges.get(key);
+        const afterEdge = afterEdges.get(key);
+        if (beforeEdge && !afterEdge) {
+            edges.push({ edge: beforeEdge, status: "removed" });
+            continue;
+        }
+        if (!beforeEdge && afterEdge) {
+            edges.push({ edge: afterEdge, status: "added" });
+            continue;
+        }
+        if (beforeEdge && afterEdge) {
+            const status = edgeEqual(beforeEdge, afterEdge) ? "unchanged" : "modified";
+            edges.push({ edge: afterEdge, status });
+        }
+    }
+    nodes.sort((left, right) => left.node.id.localeCompare(right.node.id));
+    edges.sort((left, right) => {
+        const leftKey = `${left.edge.kind}:${left.edge.from}:${left.edge.to}`;
+        const rightKey = `${right.edge.kind}:${right.edge.from}:${right.edge.to}`;
+        return leftKey.localeCompare(rightKey);
+    });
+    return { nodes, edges };
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import type { Graph } from "./model.js";
+export type AnalyzeProjectOptions = {
+    projectRoot: string;
+    appDirs?: string[];
+    extraScanDirs?: string[];
+    apiDirs?: string[];
+    httpClientIdentifiers?: string[];
+    httpClientMethods?: string[];
+    dbClientIdentifiers?: string[];
+    uiImportPathGlobs?: string[];
+};
+export declare function analyzeProject(options: AnalyzeProjectOptions): Promise<Graph>;
+export { diffGraphs } from "./diff.js";
+export type { DiffStatus, EdgeDiff, GraphDiff, NodeDiff } from "./diff.js";
+export type { Edge, EdgeKind, Graph, Node, NodeType } from "./model.js";
+export { analyzePagesToEndpoints } from "./analyzers/pagesToEndpoints.js";
+export { analyzeEndpointsToDb } from "./analyzers/endpointsToDb.js";
+export { analyzePagesToUi } from "./analyzers/pagesToUi.js";
+export { mergeGraphs, mergePartial } from "./merge.js";
+export { getDbModelsForPage, getEndpointsForPage, getPagesForDbModel, } from "./query.js";

package/dist/index.js

@@ -0,0 +1,30 @@
+import { analyzeEndpointsToDb } from "./analyzers/endpointsToDb.js";
+import { analyzePagesToEndpoints } from "./analyzers/pagesToEndpoints.js";
+import { analyzePagesToUi } from "./analyzers/pagesToUi.js";
+import { mergePartial } from "./merge.js";
+export async function analyzeProject(options) {
+    const pagesToEndpoints = await analyzePagesToEndpoints({
+        projectRoot: options.projectRoot,
+        appDirs: options.appDirs,
+        extraScanDirs: options.extraScanDirs,
+        httpClientIdentifiers: options.httpClientIdentifiers,
+        httpClientMethods: options.httpClientMethods,
+    });
+    const endpointsToDb = await analyzeEndpointsToDb({
+        projectRoot: options.projectRoot,
+        apiDirs: options.apiDirs,
+        dbClientIdentifiers: options.dbClientIdentifiers,
+    });
+    const pagesToUi = await analyzePagesToUi({
+        projectRoot: options.projectRoot,
+        appDirs: options.appDirs,
+        uiImportPathGlobs: options.uiImportPathGlobs,
+    });
+    return mergePartial(mergePartial(pagesToEndpoints, endpointsToDb), pagesToUi);
+}
+export { diffGraphs } from "./diff.js";
+export { analyzePagesToEndpoints } from "./analyzers/pagesToEndpoints.js";
+export { analyzeEndpointsToDb } from "./analyzers/endpointsToDb.js";
+export { analyzePagesToUi } from "./analyzers/pagesToUi.js";
+export { mergeGraphs, mergePartial } from "./merge.js";
+export { getDbModelsForPage, getEndpointsForPage, getPagesForDbModel, } from "./query.js";

package/dist/merge.d.ts

@@ -0,0 +1,6 @@
+import type { Edge, Graph, Node } from "./model.js";
+export declare function mergeGraphs(graphs: Graph[]): Graph;
+export declare function mergePartial(base: Graph, additions: {
+    nodes: Node[];
+    edges: Edge[];
+}): Graph;

package/dist/merge.js

@@ -0,0 +1,29 @@
+import { buildEdgeKey, mergeEdge, mergeNode } from "./utils.js";
+export function mergeGraphs(graphs) {
+    return graphs.reduce((accumulator, graph) => mergePartial(accumulator, graph), { nodes: [], edges: [] });
+}
+export function mergePartial(base, additions) {
+    const nodesById = new Map();
+    const edgesByKey = new Map();
+    for (const node of base.nodes) {
+        nodesById.set(node.id, node);
+    }
+    for (const node of additions.nodes) {
+        const existingNode = nodesById.get(node.id);
+        nodesById.set(node.id, existingNode ? mergeNode(existingNode, node) : node);
+    }
+    for (const edge of base.edges) {
+        edgesByKey.set(buildEdgeKey(edge.from, edge.to, edge.kind), edge);
+    }
+    for (const edge of additions.edges) {
+        const edgeKey = buildEdgeKey(edge.from, edge.to, edge.kind);
+        const existingEdge = edgesByKey.get(edgeKey);
+        edgesByKey.set(edgeKey, existingEdge ? mergeEdge(existingEdge, edge) : edge);
+    }
+    return {
+        nodes: [...nodesById.values()].sort((left, right) => left.id.localeCompare(right.id)),
+        edges: [...edgesByKey.values()].sort((left, right) => left.kind.localeCompare(right.kind) ||
+            left.from.localeCompare(right.from) ||
+            left.to.localeCompare(right.to)),
+    };
+}

package/dist/model.d.ts

@@ -0,0 +1,18 @@
+export type NodeType = "page" | "endpoint" | "db" | "ui" | "handler" | "action";
+export type Node = {
+    id: string;
+    type: NodeType;
+    label: string;
+    meta?: Record<string, any>;
+};
+export type EdgeKind = "page-endpoint" | "endpoint-db" | "page-ui" | "endpoint-handler" | "page-action" | "action-endpoint";
+export type Edge = {
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    meta?: Record<string, any>;
+};
+export type Graph = {
+    nodes: Node[];
+    edges: Edge[];
+};

package/dist/model.js

@@ -0,0 +1 @@
+export {};

package/dist/query.d.ts

@@ -0,0 +1,6 @@
+import type { Graph, Node } from "./model.js";
+export declare function getPageNode(graph: Graph, route: string): Node | null;
+export declare function getDbNode(graph: Graph, modelName: string): Node | null;
+export declare function getEndpointsForPage(graph: Graph, route: string): Node[];
+export declare function getDbModelsForPage(graph: Graph, route: string): Node[];
+export declare function getPagesForDbModel(graph: Graph, modelName: string): Node[];

package/dist/query.js

@@ -0,0 +1,79 @@
+export function getPageNode(graph, route) {
+    const id = `page:${route}`;
+    return graph.nodes.find((node) => node.id === id) ?? null;
+}
+export function getDbNode(graph, modelName) {
+    const id = `db:${modelName}`;
+    return graph.nodes.find((node) => node.id === id) ?? null;
+}
+export function getEndpointsForPage(graph, route) {
+    const pageNode = getPageNode(graph, route);
+    if (!pageNode) {
+        return [];
+    }
+    const endpointIds = new Set();
+    const actionIds = new Set();
+    for (const edge of graph.edges) {
+        if (edge.kind === "page-endpoint" && edge.from === pageNode.id) {
+            endpointIds.add(edge.to);
+        }
+        if (edge.kind === "page-action" && edge.from === pageNode.id) {
+            actionIds.add(edge.to);
+        }
+    }
+    if (actionIds.size > 0) {
+        for (const edge of graph.edges) {
+            if (edge.kind === "action-endpoint" && actionIds.has(edge.from)) {
+                endpointIds.add(edge.to);
+            }
+        }
+    }
+    return graph.nodes.filter((node) => endpointIds.has(node.id));
+}
+export function getDbModelsForPage(graph, route) {
+    const endpoints = getEndpointsForPage(graph, route);
+    if (endpoints.length === 0) {
+        return [];
+    }
+    const endpointIds = new Set(endpoints.map((node) => node.id));
+    const dbIds = new Set();
+    for (const edge of graph.edges) {
+        if (edge.kind === "endpoint-db" && endpointIds.has(edge.from)) {
+            dbIds.add(edge.to);
+        }
+    }
+    return graph.nodes.filter((node) => dbIds.has(node.id));
+}
+export function getPagesForDbModel(graph, modelName) {
+    const dbNode = getDbNode(graph, modelName);
+    if (!dbNode) {
+        return [];
+    }
+    const endpointIds = new Set();
+    const pageIds = new Set();
+    const actionIds = new Set();
+    for (const edge of graph.edges) {
+        if (edge.kind === "endpoint-db" && edge.to === dbNode.id) {
+            endpointIds.add(edge.from);
+        }
+    }
+    if (endpointIds.size === 0) {
+        return [];
+    }
+    for (const edge of graph.edges) {
+        if (edge.kind === "page-endpoint" && endpointIds.has(edge.to)) {
+            pageIds.add(edge.from);
+        }
+        if (edge.kind === "action-endpoint" && endpointIds.has(edge.to)) {
+            actionIds.add(edge.from);
+        }
+    }
+    if (actionIds.size > 0) {
+        for (const edge of graph.edges) {
+            if (edge.kind === "page-action" && actionIds.has(edge.to)) {
+                pageIds.add(edge.from);
+            }
+        }
+    }
+    return graph.nodes.filter((node) => pageIds.has(node.id));
+}

package/dist/serve.d.ts

@@ -0,0 +1,6 @@
+export type ServeOptions = {
+    projectRoot: string;
+    port?: number;
+    appDirs?: string[];
+};
+export declare function serve(options: ServeOptions): Promise<void>;