next-route-graph 1.1.0 → 1.2.0

package/dist/index.js

@@ -5,11 +5,13 @@
  * Programmatic SDK entry point.
  */
 export { analyzeRoutes } from "./core/analyzer.js";
+export { inspectProject, filterRoutes } from "./core/inspect.js";
+export { buildRouteGraph } from "./render/graph.js";
 export { detectAppRouter } from "./core/detector.js";
 export { lintRoutes } from "./core/linter.js";
 export { detectHttpMethods, detectRenderingType, detectRouteConfig, detectServerActions, extractRouteMetadata, getPrologueDirectives, getSegmentType, HTTP_METHODS, parseRoutePath, parseSpecialFileType, SPECIAL_FILES, stripComments, } from "./core/parser.js";
 export { scanAppDir } from "./core/scanner.js";
 // Domain Errors
-export { AmbiguousRouterError, NextRouteGraphError, NoAppRouterError, ProjectNotFoundError, RouteDirectoryReadError, RouteLintError, } from "./errors/index.js";
+export { AmbiguousRouterError, NextRouteGraphError, NoAppRouterError, ProjectNotFoundError, RouteDirectoryReadError, RouteFileReadError, RouteLintError, } from "./errors/index.js";
 // Renderers & Strategy Pattern
-export { DotRenderer, FlatRenderer, getRenderer, JsonRenderer, MarkdownRenderer, MermaidRenderer, renderDot, renderFlat, renderJson, renderMarkdown, renderMermaid, renderTree, TreeRenderer, } from "./render/index.js";
+export { DotRenderer, FlatRenderer, getRenderer, HtmlRenderer, JsonRenderer, MarkdownRenderer, MermaidRenderer, renderDot, renderFlat, renderHtml, renderJson, renderMarkdown, renderMermaid, renderTree, TreeRenderer, SvgRenderer, renderSvg, } from "./render/index.js";

package/dist/preview.d.ts

@@ -0,0 +1,4 @@
+import http from "node:http";
+/** Serve a single in-memory report on loopback. No project files are exposed. */
+export declare function startPreview(html: string, port: number): Promise<http.Server>;
+//# sourceMappingURL=preview.d.ts.map

package/dist/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,iFAAiF;AACjF,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAoBtB"}

package/dist/preview.js

@@ -0,0 +1,25 @@
+import http from "node:http";
+/** Serve a single in-memory report on loopback. No project files are exposed. */
+export async function startPreview(html, port) {
+    const server = http.createServer((req, res) => {
+        res.setHeader("X-Content-Type-Options", "nosniff");
+        res.setHeader("Cache-Control", "no-store");
+        if (req.method !== "GET" && req.method !== "HEAD") {
+            res.writeHead(405, { Allow: "GET, HEAD" });
+            res.end();
+        }
+        else if (req.url !== "/") {
+            res.writeHead(404);
+            res.end();
+        }
+        else {
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(req.method === "HEAD" ? undefined : html);
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", resolve);
+    });
+    return server;
+}

package/dist/render/dot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../../src/render/dot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAc,MAAM,mBAAmB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAqC9D;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA2DxD;AAED,qBAAa,WAAY,YAAW,cAAc;IAChD,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM;CAGvC"}
+{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../../src/render/dot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAa9D;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAsDxD;AAED,qBAAa,WAAY,YAAW,cAAc;IAChD,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM;CAGvC"}

package/dist/render/dot.js

@@ -1,31 +1,13 @@
+import { buildRouteGraph } from "./graph.js";
 /**
  * Escapes backslashes and double quotes for Graphviz DOT format.
  */
 function escapeDot(str) {
-    return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-/**
- * Sanitizes project name to form a valid Graphviz identifier.
- */
-function sanitizeIdentifier(name) {
-    return name.replace(/[^a-zA-Z0-9_]/g, "_");
-}
-/**
- * Finds the nearest parent route in the route list.
- */
-function findParentRoute(route, allRoutes) {
-    if (route.path === "/")
-        return null;
-    const parts = route.path.split("/").filter(Boolean);
-    while (parts.length > 1) {
-        parts.pop();
-        const parentPath = "/" + parts.join("/");
-        const match = allRoutes.find((r) => r.path === parentPath);
-        if (match)
-            return match;
-    }
-    const rootRoute = allRoutes.find((r) => r.path === "/");
-    return rootRoute && rootRoute !== route ? rootRoute : null;
+    return str
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\r/g, "\\r")
+        .replace(/\n/g, "\\n");
 }
 /**
  * Generates a Graphviz DOT representation of the routes.
@@ -47,36 +29,32 @@ export function renderDot(result) {
         lines.push("}");
         return lines.join("\n");
     }
-    const idMap = new Map();
-    routes.forEach((route, index) => {
-        const id = `node_${index}`;
-        idMap.set(route, id);
-        const labels = [route.path];
-        if (route.methods && route.methods.length > 0) {
-            labels.push(`[${route.methods.join(", ")}]`);
-        }
-        else if (route.rendering === "client") {
-            labels.push("[client]");
+    const nodes = buildRouteGraph(routes);
+    nodes.forEach((node) => {
+        const route = node.routes[0];
+        const id = node.id;
+        const labels = [node.path];
+        for (const endpoint of node.routes) {
+            labels.push(endpoint.file);
+            if (endpoint.methods?.length)
+                labels.push(`[${endpoint.methods.join(", ")}]`);
+            else if (endpoint.rendering === "client")
+                labels.push("[client]");
+            else if (endpoint.segmentType !== "static")
+                labels.push(`[${endpoint.segmentType}]`);
         }
-        else if (route.segmentType !== "static") {
-            labels.push(`[${route.segmentType}]`);
-        }
-        const labelText = escapeDot(labels.join("\\n"));
-        const color = route.rendering === "client"
+        const labelText = labels.map(escapeDot).join("\\n");
+        const color = route?.rendering === "client"
             ? 'fillcolor="#ecfeff", color="#06b6d4"'
-            : route.type === "route"
+            : route?.type === "route"
                 ? 'fillcolor="#fdf4ff", color="#c026d3"'
                 : 'fillcolor="#f8fafc", color="#64748b"';
         lines.push(`  ${id} [label="${labelText}", ${color}];`);
     });
     lines.push("");
-    routes.forEach((route) => {
-        const currentId = idMap.get(route);
-        const parent = findParentRoute(route, routes);
-        if (parent) {
-            const parentId = idMap.get(parent);
-            lines.push(`  ${parentId} -> ${currentId};`);
-        }
+    nodes.forEach((node) => {
+        if (node.parentId)
+            lines.push(`  ${node.parentId} -> ${node.id};`);
     });
     lines.push("}");
     return lines.join("\n");

package/dist/render/graph.d.ts

@@ -0,0 +1,13 @@
+import type { RouteEntry } from "../types/index.js";
+export interface RouteGraphNode {
+    id: string;
+    path: string;
+    depth: number;
+    parentId?: string;
+    routes: RouteEntry[];
+}
+/** URL hierarchy, including non-endpoint segments. Duplicate URLs retain every source. */
+export declare function buildRouteGraph(routes: RouteEntry[]): RouteGraphNode[];
+/** Escape text and attributes in HTML and XML, including untrusted source filenames. */
+export declare function escapeMarkup(value: string): string;
+//# sourceMappingURL=graph.d.ts.map

package/dist/render/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/render/graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,cAAc,EAAE,CA0CtE;AAED,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQlD"}

package/dist/render/graph.js

@@ -0,0 +1,53 @@
+/** URL hierarchy, including non-endpoint segments. Duplicate URLs retain every source. */
+export function buildRouteGraph(routes) {
+    if (routes.length === 0)
+        return [];
+    const nodes = new Map();
+    nodes.set("/", { id: "root", path: "/", depth: 0, routes: [] });
+    for (const route of routes) {
+        let parent = nodes.get("/");
+        const segments = route.path.split("/").filter(Boolean);
+        for (let depth = 1; depth <= segments.length; depth++) {
+            const path = "/" + segments.slice(0, depth).join("/");
+            let node = nodes.get(path);
+            if (!node) {
+                node = {
+                    id: `segment_${nodes.size}`,
+                    path,
+                    depth,
+                    parentId: parent.id,
+                    routes: [],
+                };
+                nodes.set(path, node);
+            }
+            parent = node;
+        }
+        parent.routes.push(route);
+    }
+    // A preorder keeps connecting lines clear even when SDK input is unsorted.
+    const children = new Map();
+    for (const node of nodes.values()) {
+        const siblings = children.get(node.parentId ?? "") ?? [];
+        siblings.push(node);
+        children.set(node.parentId ?? "", siblings);
+    }
+    const ordered = [];
+    const visit = (parentId) => {
+        for (const node of (children.get(parentId) ?? []).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) {
+            ordered.push(node);
+            visit(node.id);
+        }
+    };
+    visit("");
+    return ordered;
+}
+/** Escape text and attributes in HTML and XML, including untrusted source filenames. */
+export function escapeMarkup(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;")
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, "");
+}

package/dist/render/html.d.ts

@@ -0,0 +1,8 @@
+import type { AnalysisResult } from "../types/index.js";
+import type { OutputRenderer } from "./renderer.interface.js";
+/** Self-contained report. All source data is escaped; no project code is executed. */
+export declare function renderHtml(result: AnalysisResult): string;
+export declare class HtmlRenderer implements OutputRenderer {
+    render(result: AnalysisResult): string;
+}
+//# sourceMappingURL=html.d.ts.map

package/dist/render/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/render/html.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAOxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAK9D,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA+dzD;AAkOD,qBAAa,YAAa,YAAW,cAAc;IACjD,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM;CAGvC"}