next-arch-map 0.1.0

package/dist/analyzers/pagesToEndpoints.js

@@ -0,0 +1,321 @@
+import ts from "typescript";
+import { buildActionNode, buildEdgeKey, buildEndpointNode, buildPageNode, collectStringConstants, ensureNode, getExistingDirectories, getPageRouteFromFile, getSourceFile, getStringLiteralValue, isIgnoredSourceFile, isPageFile, resolveProjectRoot, walkDirectory, } from "../utils.js";
+const DEFAULT_APP_DIRS = ["app", "src/app"];
+const DEFAULT_EXTRA_SCAN_DIRS = ["src/features", "src/services", "src/lib", "src/hooks"];
+const DEFAULT_HTTP_CLIENT_IDENTIFIERS = ["fetch", "axios", "apiClient"];
+const DEFAULT_HTTP_CLIENT_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+export async function analyzePagesToEndpoints(options) {
+    const projectRoot = resolveProjectRoot(options.projectRoot);
+    const appDirs = getExistingDirectories(projectRoot, options.appDirs ?? DEFAULT_APP_DIRS);
+    if (appDirs.length === 0) {
+        throw new Error("Could not find an app/ or src/app/ directory.");
+    }
+    const extraScanDirs = getExistingDirectories(projectRoot, options.extraScanDirs ?? DEFAULT_EXTRA_SCAN_DIRS);
+    const httpClientIdentifiers = new Set((options.httpClientIdentifiers ?? DEFAULT_HTTP_CLIENT_IDENTIFIERS).map((value) => value.trim()));
+    const httpClientMethods = new Set((options.httpClientMethods ?? DEFAULT_HTTP_CLIENT_METHODS).map((value) => value.toLowerCase()));
+    const nodes = [];
+    const edges = [];
+    const nodeIds = new Set();
+    const edgeKeys = new Set();
+    const sourceFileCache = new Map();
+    const callIndexByRoute = new Map();
+    const actionIdCountByRoute = new Map();
+    for (const appDir of appDirs) {
+        for (const filePath of walkDirectory(appDir)) {
+            if (isIgnoredSourceFile(filePath)) {
+                continue;
+            }
+            const sourceFile = getSourceFile(filePath, sourceFileCache);
+            if (!sourceFile) {
+                continue;
+            }
+            const httpCalls = collectHttpCalls(sourceFile, httpClientIdentifiers, httpClientMethods);
+            // Non-page files (route handlers, layouts, helpers) under app/ only
+            // contribute endpoint nodes without creating fake page flows.
+            if (!isPageFile(filePath)) {
+                for (const call of httpCalls) {
+                    ensureNode(nodes, nodeIds, buildEndpointNode(call.endpoint, filePath));
+                }
+                continue;
+            }
+            const route = getPageRouteFromFile(appDir, filePath);
+            ensureNode(nodes, nodeIds, buildPageNode(route, filePath));
+            for (const call of httpCalls) {
+                const nextCallIndex = (callIndexByRoute.get(route) ?? 0) + 1;
+                callIndexByRoute.set(route, nextCallIndex);
+                const actionContext = inferActionContext(call.node, sourceFile, nextCallIndex);
+                const actionId = allocateActionId(route, actionContext.id, actionIdCountByRoute);
+                const pageNode = ensureNode(nodes, nodeIds, buildPageNode(route, filePath));
+                const actionNode = ensureNode(nodes, nodeIds, buildActionNode(route, actionId, filePath, actionContext.meta));
+                const endpointNode = ensureNode(nodes, nodeIds, buildEndpointNode(call.endpoint, filePath));
+                const pageActionKey = buildEdgeKey(pageNode.id, actionNode.id, "page-action");
+                if (!edgeKeys.has(pageActionKey)) {
+                    edgeKeys.add(pageActionKey);
+                    edges.push({
+                        from: pageNode.id,
+                        to: actionNode.id,
+                        kind: "page-action",
+                    });
+                }
+                const actionEndpointKey = buildEdgeKey(actionNode.id, endpointNode.id, "action-endpoint");
+                if (!edgeKeys.has(actionEndpointKey)) {
+                    edgeKeys.add(actionEndpointKey);
+                    edges.push({
+                        from: actionNode.id,
+                        to: endpointNode.id,
+                        kind: "action-endpoint",
+                        meta: call.method ? { method: call.method } : undefined,
+                    });
+                }
+                const edgeKey = buildEdgeKey(pageNode.id, endpointNode.id, "page-endpoint");
+                if (edgeKeys.has(edgeKey)) {
+                    continue;
+                }
+                edgeKeys.add(edgeKey);
+                edges.push({
+                    from: pageNode.id,
+                    to: endpointNode.id,
+                    kind: "page-endpoint",
+                    meta: call.method ? { method: call.method } : undefined,
+                });
+            }
+        }
+    }
+    for (const scanDir of extraScanDirs) {
+        for (const filePath of walkDirectory(scanDir)) {
+            if (isIgnoredSourceFile(filePath)) {
+                continue;
+            }
+            const sourceFile = getSourceFile(filePath, sourceFileCache);
+            if (!sourceFile) {
+                continue;
+            }
+            for (const call of collectHttpCalls(sourceFile, httpClientIdentifiers, httpClientMethods)) {
+                ensureNode(nodes, nodeIds, buildEndpointNode(call.endpoint, filePath));
+            }
+        }
+    }
+    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 collectHttpCalls(sourceFile, httpClientIdentifiers, httpClientMethods) {
+    const calls = [];
+    const constMap = collectStringConstants(sourceFile);
+    const visitNode = (node) => {
+        if (ts.isCallExpression(node)) {
+            const httpCall = parseHttpCall(node, constMap, httpClientIdentifiers, httpClientMethods);
+            if (httpCall) {
+                calls.push({
+                    endpoint: httpCall.endpoint,
+                    method: httpCall.method,
+                    node,
+                });
+            }
+        }
+        ts.forEachChild(node, visitNode);
+    };
+    visitNode(sourceFile);
+    return calls;
+}
+function parseHttpCall(node, constMap, httpClientIdentifiers, httpClientMethods) {
+    const endpoint = getEndpointArgument(node.arguments[0], constMap);
+    if (!endpoint) {
+        return null;
+    }
+    if (ts.isIdentifier(node.expression) && httpClientIdentifiers.has(node.expression.text)) {
+        return {
+            endpoint,
+            method: "GET",
+        };
+    }
+    if (ts.isPropertyAccessExpression(node.expression) &&
+        ts.isIdentifier(node.expression.expression) &&
+        httpClientIdentifiers.has(node.expression.expression.text) &&
+        httpClientMethods.has(node.expression.name.text.toLowerCase())) {
+        return {
+            endpoint,
+            method: node.expression.name.text.toUpperCase(),
+        };
+    }
+    return null;
+}
+function getEndpointArgument(expression, constMap) {
+    if (!expression) {
+        return null;
+    }
+    if (ts.isIdentifier(expression)) {
+        return constMap.get(expression.text) ?? null;
+    }
+    return getStringLiteralValue(expression);
+}
+function inferActionContext(call, sourceFile, callIndex) {
+    const fallbackId = `call-${callIndex}`;
+    const meta = {};
+    let handlerName;
+    let componentName;
+    let inlineEventName;
+    let inlineElementName;
+    let current = call;
+    while (current && current !== sourceFile) {
+        if (!inlineEventName && ts.isJsxAttribute(current) && ts.isIdentifier(current.name)) {
+            inlineEventName = current.name.text;
+            inlineElementName = getJsxElementName(current);
+        }
+        if (!handlerName && isFunctionLikeNode(current)) {
+            handlerName = getFunctionLikeName(current);
+        }
+        if (isTopLevelNamedFunctionLike(current, sourceFile)) {
+            componentName = getFunctionLikeName(current) ?? componentName;
+        }
+        current = current.parent;
+    }
+    if (componentName) {
+        meta.componentName = componentName;
+    }
+    if (handlerName === componentName && !inlineEventName) {
+        handlerName = undefined;
+    }
+    if (handlerName) {
+        meta.handlerName = handlerName;
+    }
+    const eventBinding = inlineEventName || inlineElementName
+        ? {
+            eventName: inlineEventName,
+            elementName: inlineElementName,
+        }
+        : handlerName
+            ? findJsxBindingForHandler(sourceFile, handlerName)
+            : undefined;
+    if (eventBinding?.eventName) {
+        meta.eventName = eventBinding.eventName;
+    }
+    if (eventBinding?.elementName) {
+        meta.elementName = eventBinding.elementName;
+    }
+    const callTarget = getCallTargetName(call);
+    if (callTarget) {
+        meta.callTarget = callTarget;
+    }
+    const actionId = buildActionContextId({
+        componentName,
+        handlerName,
+        eventName: eventBinding?.eventName,
+        elementName: eventBinding?.elementName,
+        callTarget,
+    });
+    return {
+        id: actionId ?? fallbackId,
+        meta: Object.keys(meta).length > 0 ? meta : undefined,
+    };
+}
+function allocateActionId(route, baseActionId, countsByRoute) {
+    const normalizedActionId = normalizeActionId(baseActionId);
+    const routeCounts = countsByRoute.get(route) ?? new Map();
+    const nextCount = (routeCounts.get(normalizedActionId) ?? 0) + 1;
+    routeCounts.set(normalizedActionId, nextCount);
+    countsByRoute.set(route, routeCounts);
+    return nextCount === 1 ? normalizedActionId : `${normalizedActionId}.${nextCount}`;
+}
+function buildActionContextId(parts) {
+    if (parts.elementName && parts.eventName) {
+        return [parts.elementName, parts.eventName].map(normalizeActionId).join(".");
+    }
+    if (parts.componentName && parts.handlerName) {
+        return [parts.componentName, parts.handlerName].map(normalizeActionId).join(".");
+    }
+    if (parts.handlerName && parts.eventName) {
+        return [parts.handlerName, parts.eventName].map(normalizeActionId).join(".");
+    }
+    if (parts.handlerName) {
+        return normalizeActionId(parts.handlerName);
+    }
+    if (parts.componentName && parts.callTarget) {
+        return [parts.componentName, parts.callTarget].map(normalizeActionId).join(".");
+    }
+    if (parts.callTarget) {
+        return normalizeActionId(parts.callTarget);
+    }
+    return null;
+}
+function isFunctionLikeNode(node) {
+    return (ts.isArrowFunction(node) ||
+        ts.isFunctionDeclaration(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isMethodDeclaration(node));
+}
+function isTopLevelNamedFunctionLike(node, sourceFile) {
+    if (!isFunctionLikeNode(node)) {
+        return false;
+    }
+    if (!getFunctionLikeName(node)) {
+        return false;
+    }
+    if (ts.isFunctionDeclaration(node)) {
+        return node.parent === sourceFile;
+    }
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+        return ts.isVariableDeclaration(node.parent) && node.parent.parent.parent.parent === sourceFile;
+    }
+    return false;
+}
+function getFunctionLikeName(node) {
+    if ((ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isMethodDeclaration(node)) &&
+        node.name &&
+        ts.isIdentifier(node.name)) {
+        return node.name.text;
+    }
+    if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && ts.isVariableDeclaration(node.parent)) {
+        return ts.isIdentifier(node.parent.name) ? node.parent.name.text : undefined;
+    }
+    return undefined;
+}
+function findJsxBindingForHandler(sourceFile, handlerName) {
+    let match;
+    const visitNode = (node) => {
+        if (match) {
+            return;
+        }
+        if (ts.isJsxAttribute(node) &&
+            ts.isIdentifier(node.name) &&
+            node.initializer &&
+            ts.isJsxExpression(node.initializer) &&
+            node.initializer.expression &&
+            ts.isIdentifier(node.initializer.expression) &&
+            node.initializer.expression.text === handlerName) {
+            match = {
+                eventName: node.name.text,
+                elementName: getJsxElementName(node),
+            };
+            return;
+        }
+        ts.forEachChild(node, visitNode);
+    };
+    visitNode(sourceFile);
+    return match;
+}
+function getJsxElementName(attribute) {
+    const jsxOwner = attribute.parent.parent;
+    if (!jsxOwner) {
+        return undefined;
+    }
+    if (ts.isJsxOpeningElement(jsxOwner) || ts.isJsxSelfClosingElement(jsxOwner)) {
+        return jsxOwner.tagName.getText();
+    }
+    return undefined;
+}
+function getCallTargetName(call) {
+    if (ts.isIdentifier(call.expression)) {
+        return call.expression.text;
+    }
+    if (ts.isPropertyAccessExpression(call.expression)) {
+        return call.expression.getText();
+    }
+    return undefined;
+}
+function normalizeActionId(value) {
+    return value.replace(/[:#/]/g, ".").replace(/\s+/g, "");
+}

package/dist/analyzers/pagesToUi.d.ts

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

package/dist/analyzers/pagesToUi.js

@@ -0,0 +1,118 @@
+import path from "node:path";
+import ts from "typescript";
+import { buildEdgeKey, buildPageNode, buildUiNode, ensureNode, getExistingDirectories, getPageRouteFromFile, getSourceFile, isPageFile, resolveLocalModulePath, resolveProjectRoot, walkDirectory, } from "../utils.js";
+const DEFAULT_APP_DIRS = ["app", "src/app"];
+const DEFAULT_UI_IMPORT_PATH_GLOBS = [
+    "src/components/**",
+    "src/features/**/components/**",
+    "src/app/**/components/**",
+    "app/**/components/**",
+];
+export async function analyzePagesToUi(options) {
+    const projectRoot = resolveProjectRoot(options.projectRoot);
+    const appDirs = getExistingDirectories(projectRoot, options.appDirs ?? DEFAULT_APP_DIRS);
+    if (appDirs.length === 0) {
+        throw new Error("Could not find an app/ or src/app/ directory.");
+    }
+    const uiPathMatchers = (options.uiImportPathGlobs ?? DEFAULT_UI_IMPORT_PATH_GLOBS).map(globToRegExp);
+    const nodes = [];
+    const edges = [];
+    const nodeIds = new Set();
+    const edgeKeys = new Set();
+    for (const appDir of appDirs) {
+        for (const filePath of walkDirectory(appDir)) {
+            if (!isPageFile(filePath)) {
+                continue;
+            }
+            const route = getPageRouteFromFile(appDir, filePath);
+            const pageNode = ensureNode(nodes, nodeIds, buildPageNode(route, filePath));
+            const components = collectUiComponentUsages(filePath, projectRoot, uiPathMatchers);
+            for (const component of components) {
+                const uiNode = ensureNode(nodes, nodeIds, buildUiNode(component.componentName, component.filePath));
+                const edgeKey = buildEdgeKey(pageNode.id, uiNode.id, "page-ui");
+                if (edgeKeys.has(edgeKey)) {
+                    continue;
+                }
+                edgeKeys.add(edgeKey);
+                edges.push({
+                    from: pageNode.id,
+                    to: uiNode.id,
+                    kind: "page-ui",
+                });
+            }
+        }
+    }
+    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 collectUiComponentUsages(pageFilePath, projectRoot, uiPathMatchers) {
+    const sourceFile = getSourceFile(pageFilePath);
+    if (!sourceFile) {
+        return [];
+    }
+    const componentFilePaths = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+            continue;
+        }
+        const importSource = statement.moduleSpecifier.text;
+        const resolvedImportPath = resolveLocalModulePath(pageFilePath, importSource, projectRoot);
+        if (!isUiLikeImport(importSource, resolvedImportPath, projectRoot, uiPathMatchers)) {
+            continue;
+        }
+        const importClause = statement.importClause;
+        if (!importClause || importClause.isTypeOnly) {
+            continue;
+        }
+        const componentFilePath = resolvedImportPath ?? pageFilePath;
+        if (importClause.name && isUiComponentName(importClause.name.text)) {
+            componentFilePaths.set(importClause.name.text, componentFilePath);
+        }
+        if (importClause.namedBindings && ts.isNamedImports(importClause.namedBindings)) {
+            for (const element of importClause.namedBindings.elements) {
+                if (!element.isTypeOnly && isUiComponentName(element.name.text)) {
+                    componentFilePaths.set(element.name.text, componentFilePath);
+                }
+            }
+        }
+    }
+    return [...componentFilePaths.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([componentName, filePath]) => ({ componentName, filePath }));
+}
+function isUiLikeImport(importSource, resolvedImportPath, projectRoot, uiPathMatchers) {
+    if (/^\.\.?\/components(\/|$)/.test(importSource) || importSource.startsWith("@/components/")) {
+        return true;
+    }
+    if (!resolvedImportPath) {
+        return false;
+    }
+    const relativePath = path.relative(projectRoot, resolvedImportPath).replace(/\\/g, "/");
+    return uiPathMatchers.some((matcher) => matcher.test(relativePath));
+}
+function isUiComponentName(identifierName) {
+    return /^[A-Z]/.test(identifierName);
+}
+function globToRegExp(glob) {
+    let pattern = "^";
+    for (let index = 0; index < glob.length; index += 1) {
+        const character = glob[index];
+        const nextCharacter = glob[index + 1];
+        if (character === "*" && nextCharacter === "*") {
+            pattern += ".*";
+            index += 1;
+            continue;
+        }
+        if (character === "*") {
+            pattern += "[^/]*";
+            continue;
+        }
+        pattern += /[.+^${}()|[\]\\]/.test(character) ? `\\${character}` : character;
+    }
+    pattern += "$";
+    return new RegExp(pattern);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};