next-route-graph 1.1.0 → 1.2.0

package/dist/cli.js

@@ -1,113 +1,140 @@
 #!/usr/bin/env node
-import { Command } from "commander";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { Command, Option } from "commander";
 import pc from "picocolors";
-import { analyzeRoutes } from "./core/analyzer.js";
-import { detectAppRouter } from "./core/detector.js";
-import { scanAppDir } from "./core/scanner.js";
+import { filterRoutes, inspectProject } from "./core/inspect.js";
 import { NextRouteGraphError, RouteLintError } from "./errors/index.js";
+import { startPreview } from "./preview.js";
 import { getRenderer } from "./render/index.js";
-/**
- * Determines the target output format based on CLI flags.
- */
 function resolveFormat(options) {
-    if (options.json)
-        return "json";
-    if (options.flat)
-        return "flat";
-    if (options.mermaid)
-        return "mermaid";
-    if (options.dot)
-        return "dot";
-    if (options.markdown)
-        return "markdown";
-    if (options.format)
-        return options.format;
-    return "tree";
+    const aliases = [
+        "json",
+        "flat",
+        "mermaid",
+        "dot",
+        "markdown",
+        "html",
+        "svg",
+    ];
+    const selected = aliases.filter((format) => options[format]);
+    if (selected.length + Number(Boolean(options.format)) > 1) {
+        throw new Error("Choose one output format: --format <type> or one format flag.");
+    }
+    const format = selected[0] ??
+        options.format ??
+        (options.serve !== undefined ? "html" : "tree");
+    if (options.html && options.output)
+        throw new Error("Use --html [file] or --output <file>, not both.");
+    if (options.serve !== undefined &&
+        (format !== "html" || options.output || options.html)) {
+        throw new Error("Use --serve on its own or with --format html; file output is separate.");
+    }
+    return format;
 }
 async function runAnalysis(projectPath, options) {
     try {
-        const { appDir, displayRoot } = detectAppRouter(projectPath);
-        const scannedFiles = await scanAppDir(appDir);
-        let analysisResult = await analyzeRoutes(scannedFiles, projectPath, displayRoot);
-        if (options.search) {
-            const search = options.search;
-            analysisResult.routes = analysisResult.routes.filter((route) => route.path.includes(search));
-            analysisResult.summary = {
-                ...analysisResult.summary,
-                routes: analysisResult.routes.length,
-                dynamic: analysisResult.routes.filter((route) => route.segmentType !== "static").length,
-                client: analysisResult.routes.filter((route) => route.rendering === "client").length,
-                server: analysisResult.routes.filter((route) => route.rendering === "server").length,
-            };
-        }
         const format = resolveFormat(options);
-        const renderer = getRenderer(format);
-        const output = renderer.render(analysisResult);
-        if (output) {
-            console.log(output);
+        const portText = options.serve === true ? "3000" : String(options.serve);
+        if (options.serve !== undefined &&
+            (!/^\d+$/.test(portText) || Number(portText) > 65535)) {
+            throw new Error("Preview port must be an integer between 0 and 65535 (0 chooses a free port).");
         }
-        // Determine exit code policy based on check mode and strict flag
-        const lint = analysisResult.lint;
-        if (lint) {
-            if (options.check) {
-                // In check mode: errors always fail; warnings fail if --strict is enabled
-                if (lint.hasErrors) {
-                    throw new RouteLintError(lint.errorCount, lint.warningCount);
-                }
-                if (options.strict && lint.warningCount > 0) {
-                    throw new RouteLintError(0, lint.warningCount);
-                }
-            }
-            else if (options.strict) {
-                // In default mode: fail if strict and either errors or warnings exist
-                if (lint.hasErrors || lint.warningCount > 0) {
-                    throw new RouteLintError(lint.errorCount, lint.warningCount);
-                }
+        const fullResult = await inspectProject(projectPath);
+        const result = options.search
+            ? filterRoutes(fullResult, options.search)
+            : fullResult;
+        let output = getRenderer(format).render(result);
+        const lint = fullResult.lint;
+        const failed = lint &&
+            ((options.check && lint.hasErrors) ||
+                (options.strict && (lint.hasErrors || lint.warningCount > 0)));
+        if (options.serve !== undefined) {
+            // A failed CI check must terminate instead of leaving a preview process alive.
+            if (failed)
+                throw new RouteLintError(lint.errorCount, lint.warningCount);
+            const server = await startPreview(output, Number(portText));
+            const address = server.address();
+            if (address && typeof address !== "string") {
+                console.error(pc.green(`✓ Route Graph server running at http://127.0.0.1:${address.port}`));
+                console.error("Static snapshot · Press Ctrl+C to stop");
             }
+            return;
+        }
+        const target = options.html
+            ? typeof options.html === "string"
+                ? options.html
+                : "route-graph.html"
+            : options.output;
+        if (target && target !== "-") {
+            const absolute = path.resolve(target);
+            await fs.mkdir(path.dirname(absolute), { recursive: true });
+            if (format === "tree")
+                output = stripVTControlCharacters(output);
+            await fs.writeFile(absolute, output + "\n", "utf-8");
+            console.error(pc.green(`✓ ${format === "html" ? "HTML report" : format.toUpperCase() + " export"} written to ${target}`));
         }
+        else if (output) {
+            process.stdout.write(output + "\n");
+        }
+        // Write the report before applying CI exit policy so failing checks leave artifacts.
+        if (failed)
+            throw new RouteLintError(lint.errorCount, lint.warningCount);
     }
     catch (error) {
-        if (options.json) {
-            console.error(JSON.stringify({ error: error.message, code: error.code }));
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json || options.format === "json") {
+            console.error(JSON.stringify({
+                error: message,
+                code: error instanceof NextRouteGraphError ? error.code : "ERR_CLI",
+            }));
         }
         else {
-            console.error(pc.red(`✗ ${error.message}`));
-            if (error instanceof NextRouteGraphError && error.hint) {
+            console.error(pc.red(`✗ ${message}`));
+            if (error instanceof NextRouteGraphError && error.hint)
                 console.error(pc.dim(`  Hint: ${error.hint}`));
-            }
         }
-        process.exit(1);
+        process.exitCode = 1;
     }
 }
 const program = new Command();
+const { version } = JSON.parse(await fs.readFile(new URL("../package.json", import.meta.url), "utf-8"));
 program
     .name("next-route-graph")
     .description("Inspect, lint, and visualize Next.js App Router project routes")
-    .version("1.1.0")
+    .version(version)
     .argument("[projectPath]", "Path to the Next.js project root", ".")
-    .option("--flat", "Output only flat route paths")
+    .option("--flat", "Output flat route paths")
     .option("--json", "Output machine-readable JSON")
-    .option("--mermaid", "Output Mermaid flowchart diagram")
-    .option("--dot", "Output Graphviz DOT graph")
-    .option("--markdown", "Output GitHub-flavored Markdown table")
-    .option("--format <type>", "Output format: tree, flat, json, mermaid, dot, markdown", "tree")
-    .option("--search <query>", "Filter routes by search string")
-    .option("--check", "Run route validation and lint checks")
-    .option("--strict", "Exit with non-zero code if route issues are detected")
-    .action(async (projectPath, options) => {
-    await runAnalysis(projectPath, options);
-});
+    .option("--mermaid", "Output Mermaid diagram source")
+    .option("--dot", "Output Graphviz DOT source")
+    .option("--markdown", "Output a Markdown table")
+    .option("--svg", "Output a rendered SVG route diagram")
+    .option("--html [file]", "Write an offline interactive HTML report (default: route-graph.html)")
+    .option("--serve [port]", "Preview an HTML snapshot on 127.0.0.1 (default: 3000)")
+    .addOption(new Option("--format <type>", "Output format (default: tree)").choices([
+    "tree",
+    "flat",
+    "json",
+    "mermaid",
+    "dot",
+    "markdown",
+    "html",
+    "svg",
+]))
+    .option("-o, --output <file>", "Write any format to a file; '-' writes to stdout")
+    .option("--search <query>", "Filter path, source file, or HTTP method (case-insensitive)")
+    .option("--check", "Fail on route validation errors")
+    .option("--strict", "Fail on errors or warnings")
+    .action(runAnalysis);
 program
     .command("check")
-    .description("Lint Next.js App Router for collisions, missing roots, and slot errors")
+    .description("Check route collisions, root layouts, and slot fallbacks")
     .argument("[projectPath]", "Path to the Next.js project root", ".")
     .option("--strict", "Fail on warnings in addition to errors")
     .option("--json", "Output check report as JSON")
     .action(async (projectPath, options) => {
-    await runAnalysis(projectPath, {
-        check: true,
-        strict: options.strict ?? false,
-        json: options.json,
-    });
+    await runAnalysis(projectPath, { ...options, check: true });
 });
-program.parse(process.argv);
+await program.parseAsync(process.argv);

package/dist/core/analyzer.d.ts

@@ -1,4 +1,8 @@
-import { AnalysisResult, DiscoveredFile } from "../types/index.js";
+import { AnalysisResult, DiscoveredFile, RouteEntry, SummaryStats } from "../types/index.js";
+/**
+ * Aggregates summary statistics for the analyzed routes and convention files.
+ */
+export declare function getRoutesSummary(routes: RouteEntry[], layouts: number, loading: number, errors: number): SummaryStats;
 /**
  * Analyzes discovered files in a Next.js App Router to construct route entries,
  * evaluate rendering types, HTTP methods, layouts, and linter rules.

package/dist/core/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../src/core/analyzer.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,cAAc,EACd,cAAc,EAIf,MAAM,mBAAmB,CAAC;AA+M3B;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,cAAc,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,CAAC,CA8CzB"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../src/core/analyzer.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,cAAc,EACd,cAAc,EACd,UAAU,EAEV,YAAY,EACb,MAAM,mBAAmB,CAAC;AAyK3B;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,YAAY,CA4Bd;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,cAAc,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,CAAC,CAqDzB"}

package/dist/core/analyzer.js

@@ -1,7 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { RouteFileReadError } from "../errors/index.js";
 import { lintRoutes } from "./linter.js";
-import { detectHttpMethods, detectRenderingType, detectRouteConfig, detectServerActions, extractRouteMetadata, getSegmentType, parseRoutePath, parseSpecialFileType, } from "./parser.js";
+import { detectHttpMethods, getPrologueDirectives, detectRouteConfig, detectServerActions, extractRouteMetadata, getSegmentType, parseRoutePath, parseSpecialFileType, } from "./parser.js";
 /**
  * Groups discovered files by their directory relative to the App Router root.
  */
@@ -38,8 +39,12 @@ async function processDirectoryFiles(dirFiles) {
         try {
             content = await fs.readFile(file.fullPath, "utf-8");
         }
-        catch { }
-        const rendering = await detectRenderingType(content);
+        catch (cause) {
+            throw new RouteFileReadError(file.relativePath, cause);
+        }
+        const rendering = getPrologueDirectives(content).has("use client")
+            ? "client"
+            : "server";
         const methods = specialType === "route" ? detectHttpMethods(content) : undefined;
         const hasServerActions = detectServerActions(content);
         const config = detectRouteConfig(content);
@@ -73,7 +78,7 @@ async function processDirectoryFiles(dirFiles) {
 /**
  * Finds all layout files in parent directories that wrap a specific directory.
  */
-function findLayoutChain(targetDir, allFiles) {
+function findLayoutChain(targetDir, layoutsByDirectory) {
     const layoutChain = [];
     const normalizedTarget = targetDir === "." ? "" : targetDir;
     const segments = normalizedTarget ? normalizedTarget.split("/") : [];
@@ -81,13 +86,9 @@ function findLayoutChain(targetDir, allFiles) {
     for (let i = 0; i <= segments.length; i++) {
         const currentPath = segments.slice(0, i).join("/");
         const checkDir = currentPath === "" ? "." : currentPath;
-        const layout = allFiles.find((f) => {
-            const dir = path.dirname(f.relativePath).replace(/\\/g, "/");
-            const isDir = dir === checkDir || (checkDir === "." && dir === "");
-            return isDir && parseSpecialFileType(f.fileName) === "layout";
-        });
+        const layout = layoutsByDirectory.get(checkDir);
         if (layout) {
-            layoutChain.push(layout.relativePath);
+            layoutChain.push(layout);
         }
     }
     return layoutChain;
@@ -96,7 +97,7 @@ function findLayoutChain(targetDir, allFiles) {
  * Creates a RouteEntry from the convention files in a directory.
  * Uses cached metadata from the in-memory RouteFile to eliminate duplicate disk reads.
  */
-function createRouteEntry(routeFiles, allFiles) {
+function createRouteEntry(routeFiles, layoutsByDirectory) {
     const pageFile = routeFiles.find((file) => file.type === "page");
     const routeHandlerFile = routeFiles.find((file) => file.type === "route");
     const primaryFile = pageFile ?? routeHandlerFile;
@@ -106,7 +107,7 @@ function createRouteEntry(routeFiles, allFiles) {
     const computedPath = parseRoutePath(primaryFile.relativePath);
     const metadata = extractRouteMetadata(primaryFile.relativePath);
     const dir = path.dirname(primaryFile.relativePath).replace(/\\/g, "/");
-    const layoutChain = findLayoutChain(dir, allFiles);
+    const layoutChain = findLayoutChain(dir, layoutsByDirectory);
     return {
         path: computedPath,
         type: pageFile ? "page" : "route",
@@ -126,7 +127,7 @@ function createRouteEntry(routeFiles, allFiles) {
 /**
  * Aggregates summary statistics for the analyzed routes and convention files.
  */
-function getRoutesSummary(routes, layouts, loading, errors) {
+export function getRoutesSummary(routes, layouts, loading, errors) {
     let dynamic = 0;
     let client = 0;
     let apiRoutes = 0;
@@ -165,6 +166,12 @@ function getRoutesSummary(routes, layouts, loading, errors) {
 export async function analyzeRoutes(files, projectPath, displayRoot) {
     const startTime = Date.now();
     const dirMap = groupFilesByDirectory(files);
+    const layoutsByDirectory = new Map();
+    for (const [dir, dirFiles] of dirMap) {
+        const layout = dirFiles.find((file) => parseSpecialFileType(file.fileName) === "layout");
+        if (layout)
+            layoutsByDirectory.set(dir, layout.relativePath);
+    }
     const discoveredRoutes = [];
     let totalLayouts = 0;
     let totalLoading = 0;
@@ -174,7 +181,7 @@ export async function analyzeRoutes(files, projectPath, displayRoot) {
         totalLayouts += result.layouts;
         totalLoading += result.loading;
         totalErrors += result.errors;
-        const route = createRouteEntry(result.routeFiles, files);
+        const route = createRouteEntry(result.routeFiles, layoutsByDirectory);
         if (route) {
             discoveredRoutes.push(route);
         }

package/dist/core/inspect.d.ts

@@ -0,0 +1,6 @@
+import type { AnalysisResult } from "../types/index.js";
+/** Scan a project without starting Next.js or executing project code. */
+export declare function inspectProject(projectPath?: string): Promise<AnalysisResult>;
+/** Filter endpoint counts; convention-file totals and diagnostics remain project-wide. */
+export declare function filterRoutes(result: AnalysisResult, query: string): AnalysisResult;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/core/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/core/inspect.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,yEAAyE;AACzE,wBAAsB,cAAc,CAClC,WAAW,SAAM,GAChB,OAAO,CAAC,cAAc,CAAC,CAMzB;AAED,0FAA0F;AAC1F,wBAAgB,YAAY,CAC1B,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,MAAM,GACZ,cAAc,CAiBhB"}

package/dist/core/inspect.js

@@ -0,0 +1,21 @@
+import { analyzeRoutes, getRoutesSummary } from "./analyzer.js";
+import { detectAppRouter } from "./detector.js";
+import { scanAppDir } from "./scanner.js";
+/** Scan a project without starting Next.js or executing project code. */
+export async function inspectProject(projectPath = ".") {
+    const start = performance.now();
+    const { appDir, displayRoot } = detectAppRouter(projectPath);
+    const files = await scanAppDir(appDir);
+    const result = await analyzeRoutes(files, projectPath, displayRoot);
+    return { ...result, executionTimeMs: Math.round(performance.now() - start) };
+}
+/** Filter endpoint counts; convention-file totals and diagnostics remain project-wide. */
+export function filterRoutes(result, query) {
+    const search = query.toLowerCase();
+    const routes = result.routes.filter((route) => [route.path, route.file, ...(route.methods ?? [])].some((value) => value.toLowerCase().includes(search)));
+    return {
+        ...result,
+        routes,
+        summary: getRoutesSummary(routes, result.summary.layouts, result.summary.loading, result.summary.errors),
+    };
+}

package/dist/core/linter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linter.d.ts","sourceRoot":"","sources":["../../src/core/linter.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EAEd,UAAU,EACV,UAAU,EACX,MAAM,mBAAmB,CAAC;AAkB3B;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAAE,EACpB,KAAK,EAAE,cAAc,EAAE,GACtB,UAAU,CA2KZ"}
+{"version":3,"file":"linter.d.ts","sourceRoot":"","sources":["../../src/core/linter.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EAEd,UAAU,EACV,UAAU,EACX,MAAM,mBAAmB,CAAC;AAkB3B;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAAE,EACpB,KAAK,EAAE,cAAc,EAAE,GACtB,UAAU,CA8LZ"}

package/dist/core/linter.js

@@ -13,7 +13,7 @@ function createPatternKey(routePath) {
             return ":catchAll";
         if (seg.startsWith("[") && seg.endsWith("]"))
             return ":dynamic";
-        return seg.toLowerCase();
+        return seg;
     })
         .join("/");
 }
@@ -47,7 +47,7 @@ export function lintRoutes(routes, files) {
     });
     if (!hasTopLevelRootLayout && routes.length > 0) {
         // Check if every route has at least one layout in its layoutChain
-        const routesWithoutLayout = routes.filter((r) => !r.layoutChain || r.layoutChain.length === 0);
+        const routesWithoutLayout = routes.filter((r) => r.type === "page" && (!r.layoutChain || r.layoutChain.length === 0));
         if (routesWithoutLayout.length > 0) {
             issues.push({
                 rule: "require-root-layout",
@@ -77,13 +77,28 @@ export function lintRoutes(routes, files) {
     // -------------------------------------------------------------
     // Rule 3: Exact URL Collision across Route Groups (no-duplicate-paths)
     // -------------------------------------------------------------
+    // Slots render alongside children, and intercepted pages intentionally share URLs.
+    // Collisions only apply within the same parallel-slot branch.
+    const branchKey = (route) => {
+        const parts = route.file.replace(/\\/g, "/").split("/");
+        let slot = -1;
+        parts.forEach((part, index) => {
+            if (part.startsWith("@"))
+                slot = index;
+        });
+        return slot < 0 ? "" : parts.slice(0, slot + 1).join("/");
+    };
+    const publicRoutes = routes.filter((route) => !route.intercepting);
     const pathToFileMap = new Map();
-    for (const route of routes) {
-        const existing = pathToFileMap.get(route.path) || [];
-        existing.push(route.file);
-        pathToFileMap.set(route.path, existing);
+    for (const route of publicRoutes) {
+        const key = JSON.stringify([branchKey(route), route.path]);
+        const existing = pathToFileMap.get(key) || [];
+        existing.push(route);
+        pathToFileMap.set(key, existing);
     }
-    for (const [routePath, fileList] of pathToFileMap.entries()) {
+    for (const entries of pathToFileMap.values()) {
+        const routePath = entries[0].path;
+        const fileList = entries.map((route) => route.file);
         if (fileList.length > 1) {
             issues.push({
                 rule: "no-duplicate-paths",
@@ -98,23 +113,28 @@ export function lintRoutes(routes, files) {
     // Rule 4: Dynamic Segment Collisions (no-route-collisions)
     // -------------------------------------------------------------
     const patternMap = new Map();
-    for (const route of routes) {
-        const key = createPatternKey(route.path);
-        const existing = patternMap.get(key) || [];
-        existing.push(route);
-        patternMap.set(key, existing);
+    for (const route of publicRoutes) {
+        const segments = route.path.split("/").filter(Boolean);
+        for (let depth = 1; depth <= segments.length; depth++) {
+            if (!segments[depth - 1].startsWith("["))
+                continue;
+            const prefix = "/" + segments.slice(0, depth).join("/");
+            const key = JSON.stringify([branchKey(route), createPatternKey(prefix)]);
+            const existing = patternMap.get(key) ?? new Set();
+            existing.add(prefix);
+            patternMap.set(key, existing);
+        }
     }
-    for (const [pattern, patternRoutes] of patternMap.entries()) {
-        if (patternRoutes.length > 1) {
-            const uniquePaths = Array.from(new Set(patternRoutes.map((r) => r.path)));
-            if (uniquePaths.length > 1) {
-                issues.push({
-                    rule: "no-route-collisions",
-                    severity: "error",
-                    message: `Dynamic route collision detected matching pattern "/${pattern}": ${uniquePaths.join(", ")}`,
-                    hint: "Next.js cannot disambiguate multiple dynamic segments at the same level. Unify the dynamic parameter names.",
-                });
-            }
+    for (const patternPaths of patternMap.values()) {
+        const uniquePaths = [...patternPaths];
+        const pattern = createPatternKey(uniquePaths[0]);
+        if (uniquePaths.length > 1) {
+            issues.push({
+                rule: "no-route-collisions",
+                severity: "error",
+                message: `Dynamic route collision detected matching pattern "/${pattern}": ${uniquePaths.join(", ")}`,
+                hint: "Next.js cannot disambiguate multiple dynamic segments at the same level. Unify the dynamic parameter names.",
+            });
         }
     }
     // -------------------------------------------------------------

package/dist/core/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/core/parser.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE/E;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,GAAG,CAAC,eAAe,CAU7C,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAQpC,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAQ7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAkElE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,aAAa,CAAC,CAoBxB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAmB/D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAW5D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG;IAClD,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,OAAO,GAAG,cAAc,CAAC;CACrE,CA2BA;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG;IAC1D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAmBA;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAwC3D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,GAChB,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,oBAAoB,CAc3D"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/core/parser.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE/E;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,GAAG,CAAC,eAAe,CAU7C,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAQpC,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAQ7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAsElE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,aAAa,CAAC,CAoBxB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAuB/D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAW5D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG;IAClD,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,OAAO,GAAG,cAAc,CAAC;CACrE,CA2BA;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG;IAC1D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAmBA;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CA+C3D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,GAChB,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,oBAAoB,CAc3D"}

package/dist/core/parser.js

@@ -85,7 +85,9 @@ export function getPrologueDirectives(content) {
         if (char === '"' || char === "'") {
             const quote = char;
             let endIndex = index + 1;
-            while (endIndex < len && code[endIndex] !== quote && code[endIndex] !== "\n") {
+            while (endIndex < len &&
+                code[endIndex] !== quote &&
+                code[endIndex] !== "\n") {
                 endIndex++;
             }
             if (endIndex < len && code[endIndex] === quote) {
@@ -114,9 +116,7 @@ export function getPrologueDirectives(content) {
  * when matching exported declarations.
  */
 export function stripComments(content) {
-    return content
-        .replace(/\/\*[\s\S]*?\*\//g, "")
-        .replace(/\/\/[^\n]*/g, "");
+    return content.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
 }
 /**
  * Analyzes the source content or file on disk to detect if a "use client" directive is present.
@@ -152,19 +152,25 @@ export async function detectRenderingType(fileContentOrPath) {
  * @returns Array of discovered HTTP methods
  */
 export function detectHttpMethods(content) {
-    const discovered = [];
     const cleanCode = stripComments(content);
-    for (const method of HTTP_METHODS) {
-        // Matches:
-        // 1. export [async] function GET(...)
-        // 2. export const/let/var GET = ... or export const GET: Handler = ...
-        // 3. export { GET } or export { handle as GET }
-        const pattern = new RegExp(`export\\s+(?:async\\s+)?(?:function\\s+${method}\\b|(?:const|let|var)\\s+${method}(?:\\s*:[^=]+)?\\s*=|\\{[^}]*\\b(?:as\\s+)?${method}\\b[^}]*\\})`, "m");
-        if (pattern.test(cleanCode)) {
-            discovered.push(method);
+    const namedExports = new Set();
+    for (const match of cleanCode.matchAll(/\bexport\s*\{([^}]*)\}/g)) {
+        for (const entry of match[1].split(",")) {
+            const specifier = entry.trim();
+            if (!specifier || specifier.startsWith("type "))
+                continue;
+            const name = specifier
+                .split(/\s+as\s+/)
+                .pop()
+                .trim();
+            namedExports.add(name);
         }
     }
-    return discovered;
+    return HTTP_METHODS.filter((method) => {
+        // Direct declarations and named exports use the exported name, not the local alias.
+        const pattern = new RegExp(`export\\s+(?:async\\s+)?(?:function\\s+${method}\\b|(?:const|let|var)\\s+${method}(?:\\s*:[^=]+)?\\s*=)`, "m");
+        return namedExports.has(method) || pattern.test(cleanCode);
+    });
 }
 /**
  * Detects if a file defines Server Actions via the "use server" directive.
@@ -256,8 +262,17 @@ export function parseRoutePath(relativePath) {
         if (cleanedPart.startsWith("%5F") || cleanedPart.startsWith("%5f")) {
             cleanedPart = "_" + cleanedPart.slice(3);
         }
-        // Strip intercepting route prefixes for the public URL mapping (match (..)(..) before (..))
-        cleanedPart = cleanedPart.replace(/^(?:\(\.\.\)\(\.\.\)|\(\.\.\.\)|\(\.\.\)|\(\.\))/, "");
+        // Match URL segments, not filesystem levels: groups and slots never count.
+        const interception = cleanedPart.match(/^(\(\.\.\.\)|(?:\(\.\.\))+|\(\.\))/)?.[0];
+        if (interception) {
+            if (interception === "(...)")
+                urlSegments.length = 0;
+            else if (interception !== "(.)") {
+                const levels = interception.length / "(..)".length;
+                urlSegments.splice(Math.max(0, urlSegments.length - levels));
+            }
+            cleanedPart = cleanedPart.slice(interception.length);
+        }
         urlSegments.push(cleanedPart);
     }
     const routePath = "/" + urlSegments.join("/");

package/dist/errors/index.d.ts

@@ -22,6 +22,10 @@ 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;

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

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

@@ -41,6 +41,13 @@ export class RouteDirectoryReadError extends NextRouteGraphError {
         }
     }
 }
+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;
@@ -51,7 +58,7 @@ export class RouteLintError extends NextRouteGraphError {
             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 or run without --strict.");
+        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

@@ -5,12 +5,14 @@
  * 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, RouteLintError, } from "./errors/index.js";
-export { DotRenderer, FlatRenderer, getRenderer, JsonRenderer, MarkdownRenderer, MermaidRenderer, renderDot, renderFlat, renderJson, renderMarkdown, renderMermaid, renderTree, TreeRenderer, } from "./render/index.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

@@ -1 +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,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,cAAc,GACf,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,UAAU,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,UAAU,EACV,YAAY,GACb,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"}
+{"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"}