next-route-graph 1.0.2 → 1.2.0

package/dist/errors/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Custom error hierarchy for next-route-graph
+ */
+export declare abstract class NextRouteGraphError extends Error {
+    abstract readonly code: string;
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export declare class ProjectNotFoundError extends NextRouteGraphError {
+    readonly code = "ERR_PROJECT_NOT_FOUND";
+    constructor(projectPath?: string);
+}
+export declare class AmbiguousRouterError extends NextRouteGraphError {
+    readonly code = "ERR_AMBIGUOUS_ROUTER";
+    constructor();
+}
+export declare class NoAppRouterError extends NextRouteGraphError {
+    readonly code = "ERR_NO_APP_ROUTER";
+    constructor();
+}
+export declare class RouteDirectoryReadError extends NextRouteGraphError {
+    readonly code = "ERR_DIRECTORY_READ";
+    constructor(dirPath?: string, cause?: unknown);
+}
+export declare class RouteFileReadError extends NextRouteGraphError {
+    readonly code = "ERR_FILE_READ";
+    constructor(filePath: string, cause: unknown);
+}
+export declare class RouteLintError extends NextRouteGraphError {
+    readonly code = "ERR_ROUTE_LINT";
+    readonly errorCount: number;
+    readonly warningCount: number;
+    constructor(errorCount: number, warningCount?: number);
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,8BAAsB,mBAAoB,SAAQ,KAAK;IACrD,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAM3C;AAED,qBAAa,oBAAqB,SAAQ,mBAAmB;IAC3D,QAAQ,CAAC,IAAI,2BAA2B;gBAE5B,WAAW,CAAC,EAAE,MAAM;CAQjC;AAED,qBAAa,oBAAqB,SAAQ,mBAAmB;IAC3D,QAAQ,CAAC,IAAI,0BAA0B;;CAQxC;AAED,qBAAa,gBAAiB,SAAQ,mBAAmB;IACvD,QAAQ,CAAC,IAAI,uBAAuB;;CAQrC;AAED,qBAAa,uBAAwB,SAAQ,mBAAmB;IAC9D,QAAQ,CAAC,IAAI,wBAAwB;gBAEzB,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAW9C;AAED,qBAAa,kBAAmB,SAAQ,mBAAmB;IACzD,QAAQ,CAAC,IAAI,mBAAmB;gBAEpB,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAO7C;AAED,qBAAa,cAAe,SAAQ,mBAAmB;IACrD,QAAQ,CAAC,IAAI,oBAAoB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAElB,UAAU,EAAE,MAAM,EAAE,YAAY,GAAE,MAAU;CAWzD"}

package/dist/errors/index.js

@@ -0,0 +1,65 @@
+/**
+ * Custom error hierarchy for next-route-graph
+ */
+export class NextRouteGraphError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = this.constructor.name;
+        this.hint = hint;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class ProjectNotFoundError extends NextRouteGraphError {
+    code = "ERR_PROJECT_NOT_FOUND";
+    constructor(projectPath) {
+        super(projectPath
+            ? `The specified project path does not exist: "${projectPath}"`
+            : "The specified project path does not exist.", "Please verify the directory path exists and you have read permissions.");
+    }
+}
+export class AmbiguousRouterError extends NextRouteGraphError {
+    code = "ERR_AMBIGUOUS_ROUTER";
+    constructor() {
+        super(`Could not determine the App Router root. Found both "./app" and "./src/app".`, "Next.js only supports one App Router root. Please keep either ./app or ./src/app.");
+    }
+}
+export class NoAppRouterError extends NextRouteGraphError {
+    code = "ERR_NO_APP_ROUTER";
+    constructor() {
+        super(`No Next.js App Router directory found.\n\nExpected:\n  ./app\n  ./src/app`, "Expected to find an ./app or ./src/app directory containing App Router files.");
+    }
+}
+export class RouteDirectoryReadError extends NextRouteGraphError {
+    code = "ERR_DIRECTORY_READ";
+    constructor(dirPath, cause) {
+        super("Unable to read the App Router directory.", dirPath
+            ? `Ensure you have filesystem read permissions for "${dirPath}".`
+            : "Ensure you have filesystem read permissions for this folder.");
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+export class RouteFileReadError extends NextRouteGraphError {
+    code = "ERR_FILE_READ";
+    constructor(filePath, cause) {
+        super(`Unable to read route file: "${filePath}"`, "Check that the file still exists and is readable, then scan again.");
+        this.cause = cause;
+    }
+}
+export class RouteLintError extends NextRouteGraphError {
+    code = "ERR_ROUTE_LINT";
+    errorCount;
+    warningCount;
+    constructor(errorCount, warningCount = 0) {
+        const details = [];
+        if (errorCount > 0)
+            details.push(`${errorCount} error(s)`);
+        if (warningCount > 0)
+            details.push(`${warningCount} warning(s)`);
+        super(`Route validation failed with ${details.join(" and ") || "issues"}.`, "Fix the reported route issues. Use a normal scan without --check or --strict to inspect without failing validation.");
+        this.errorCount = errorCount;
+        this.warningCount = warningCount;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * next-route-graph
+ *
+ * Inspect, lint, and visualize Next.js App Router project routes.
+ * Programmatic SDK entry point.
+ */
+export { analyzeRoutes } from "./core/analyzer.js";
+export { inspectProject, filterRoutes } from "./core/inspect.js";
+export { buildRouteGraph, type RouteGraphNode } from "./render/graph.js";
+export { detectAppRouter, type DetectionResult } 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";
+export { AmbiguousRouterError, NextRouteGraphError, NoAppRouterError, ProjectNotFoundError, RouteDirectoryReadError, RouteFileReadError, RouteLintError, } from "./errors/index.js";
+export { DotRenderer, FlatRenderer, getRenderer, HtmlRenderer, JsonRenderer, MarkdownRenderer, MermaidRenderer, renderDot, renderFlat, renderHtml, renderJson, renderMarkdown, renderMermaid, renderTree, TreeRenderer, SvgRenderer, renderSvg, } from "./render/index.js";
+export type { OutputRenderer } from "./render/index.js";
+export type { AnalysisResult, CLIOptions, DiscoveredFile, HttpMethod, LintIssue, LintResult, LintSeverity, OutputFormat, RenderingType, RouteEntry, RouteFile, SegmentType, SpecialFileType, SummaryStats, } from "./types/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,UAAU,EACV,YAAY,EACZ,WAAW,EACX,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD,YAAY,EACV,cAAc,EACd,UAAU,EACV,cAAc,EACd,UAAU,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,UAAU,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,YAAY,GACb,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * next-route-graph
+ *
+ * Inspect, lint, and visualize Next.js App Router project routes.
+ * 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, RouteFileReadError, RouteLintError, } from "./errors/index.js";
+// Renderers & Strategy Pattern
+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

@@ -0,0 +1,13 @@
+import { AnalysisResult } from "../types/index.js";
+import type { OutputRenderer } from "./renderer.interface.js";
+/**
+ * Generates a Graphviz DOT representation of the routes.
+ *
+ * @param result - AnalysisResult
+ * @returns Graphviz DOT diagram string
+ */
+export declare function renderDot(result: AnalysisResult): string;
+export declare class DotRenderer implements OutputRenderer {
+    render(result: AnalysisResult): string;
+}
+//# sourceMappingURL=dot.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,66 @@
+import { buildRouteGraph } from "./graph.js";
+/**
+ * Escapes backslashes and double quotes for Graphviz DOT format.
+ */
+function escapeDot(str) {
+    return str
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\r/g, "\\r")
+        .replace(/\n/g, "\\n");
+}
+/**
+ * Generates a Graphviz DOT representation of the routes.
+ *
+ * @param result - AnalysisResult
+ * @returns Graphviz DOT diagram string
+ */
+export function renderDot(result) {
+    const lines = [];
+    const graphName = `${escapeDot(result.project)}Routes`;
+    lines.push(`digraph "${graphName}" {`);
+    lines.push("  rankdir=TB;");
+    lines.push('  node [shape=box, style="rounded,filled", fontname="Helvetica", fillcolor="#f8fafc", color="#cbd5e1"];');
+    lines.push('  edge [color="#94a3b8"];');
+    lines.push("");
+    const routes = result.routes;
+    if (routes.length === 0) {
+        lines.push('  empty [label="(No routes discovered)"];');
+        lines.push("}");
+        return lines.join("\n");
+    }
+    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}]`);
+        }
+        const labelText = labels.map(escapeDot).join("\\n");
+        const color = route?.rendering === "client"
+            ? 'fillcolor="#ecfeff", color="#06b6d4"'
+            : route?.type === "route"
+                ? 'fillcolor="#fdf4ff", color="#c026d3"'
+                : 'fillcolor="#f8fafc", color="#64748b"';
+        lines.push(`  ${id} [label="${labelText}", ${color}];`);
+    });
+    lines.push("");
+    nodes.forEach((node) => {
+        if (node.parentId)
+            lines.push(`  ${node.parentId} -> ${node.id};`);
+    });
+    lines.push("}");
+    return lines.join("\n");
+}
+export class DotRenderer {
+    render(result) {
+        return renderDot(result);
+    }
+}

package/dist/render/flat.d.ts

@@ -0,0 +1,13 @@
+import { AnalysisResult, RouteEntry } from "../types/index.js";
+import type { OutputRenderer } from "./renderer.interface.js";
+/**
+ * Formats routes as a flat list of URL paths.
+ *
+ * @param input - Array of route entries or full AnalysisResult
+ * @returns Newline-separated route paths
+ */
+export declare function renderFlat(input: RouteEntry[] | AnalysisResult): string;
+export declare class FlatRenderer implements OutputRenderer {
+    render(result: AnalysisResult): string;
+}
+//# sourceMappingURL=flat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flat.d.ts","sourceRoot":"","sources":["../../src/render/flat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,cAAc,GAAG,MAAM,CAGvE;AAED,qBAAa,YAAa,YAAW,cAAc;IACjD,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM;CAGvC"}

package/dist/render/flat.js

@@ -1,3 +1,15 @@
-export function renderFlat(routes) {
-    return routes.map((r) => r.path).join("\n");
+/**
+ * Formats routes as a flat list of URL paths.
+ *
+ * @param input - Array of route entries or full AnalysisResult
+ * @returns Newline-separated route paths
+ */
+export function renderFlat(input) {
+    const routes = Array.isArray(input) ? input : input.routes;
+    return routes.map((route) => route.path).join("\n");
+}
+export class FlatRenderer {
+    render(result) {
+        return renderFlat(result);
+    }
 }

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"}