next-route-graph 1.0.2 → 1.2.0

package/dist/core/linter.js

@@ -0,0 +1,194 @@
+import path from "node:path";
+/**
+ * Normalizes dynamic segments (e.g. [id], [slug], [...catch]) to a wildcard token
+ * to detect overlapping routing patterns.
+ */
+function createPatternKey(routePath) {
+    const segments = routePath.split("/").filter(Boolean);
+    return segments
+        .map((seg) => {
+        if (seg.startsWith("[[...") && seg.endsWith("]]"))
+            return ":optCatchAll";
+        if (seg.startsWith("[...") && seg.endsWith("]"))
+            return ":catchAll";
+        if (seg.startsWith("[") && seg.endsWith("]"))
+            return ":dynamic";
+        return seg;
+    })
+        .join("/");
+}
+/**
+ * Validates Next.js App Router routes and file structures against best practices
+ * and official framework rules.
+ *
+ * @param routes - Array of all analyzed route entries
+ * @param files - All discovered files in the App Router directory
+ * @returns LintResult containing discovered errors, warnings, and info diagnostics
+ */
+export function lintRoutes(routes, files) {
+    const issues = [];
+    // Group files by relative directory
+    const dirGroup = new Map();
+    for (const file of files) {
+        const dir = path.dirname(file.relativePath).replace(/\\/g, "/");
+        const existing = dirGroup.get(dir) || [];
+        existing.push(file);
+        dirGroup.set(dir, existing);
+    }
+    // -------------------------------------------------------------
+    // Rule 1: Root Layout Check (require-root-layout)
+    // -------------------------------------------------------------
+    // Next.js requires a root layout. If top-level layout is absent,
+    // Next.js supports Multiple Root Layouts inside top-level route groups (e.g. app/(shop)/layout.tsx).
+    const hasTopLevelRootLayout = files.some((f) => {
+        const dir = path.dirname(f.relativePath).replace(/\\/g, "/");
+        const isRoot = dir === "." || dir === "";
+        return isRoot && /^layout\.(tsx|ts|jsx|js)$/.test(f.fileName);
+    });
+    if (!hasTopLevelRootLayout && routes.length > 0) {
+        // Check if every route has at least one layout in its layoutChain
+        const routesWithoutLayout = routes.filter((r) => r.type === "page" && (!r.layoutChain || r.layoutChain.length === 0));
+        if (routesWithoutLayout.length > 0) {
+            issues.push({
+                rule: "require-root-layout",
+                severity: "error",
+                message: "Root layout is missing from the App Router root, and one or more routes lack a route group root layout.",
+                hint: "Create an 'app/layout.tsx' file, or add a 'layout.tsx' inside each top-level route group.",
+            });
+        }
+    }
+    // -------------------------------------------------------------
+    // Rule 2: Page and Route Handler Conflict (no-page-route-conflict)
+    // -------------------------------------------------------------
+    for (const [dir, dirFiles] of dirGroup.entries()) {
+        const hasPage = dirFiles.some((f) => /^page\.(tsx|ts|jsx|js)$/.test(f.fileName));
+        const hasRoute = dirFiles.some((f) => /^route\.(tsx|ts|jsx|js)$/.test(f.fileName));
+        if (hasPage && hasRoute) {
+            const displayDir = dir === "." ? "root (app/)" : dir;
+            issues.push({
+                rule: "no-page-route-conflict",
+                severity: "error",
+                filePath: dir,
+                message: `Segment "${displayDir}" contains both page and route handler files.`,
+                hint: "Next.js does not allow page.(tsx|js) and route.(ts|js) in the same directory segment.",
+            });
+        }
+    }
+    // -------------------------------------------------------------
+    // 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 publicRoutes) {
+        const key = JSON.stringify([branchKey(route), route.path]);
+        const existing = pathToFileMap.get(key) || [];
+        existing.push(route);
+        pathToFileMap.set(key, existing);
+    }
+    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",
+                severity: "error",
+                routePath,
+                message: `Multiple route files resolve to the same public URL path "${routePath}":\n  - ${fileList.join("\n  - ")}`,
+                hint: "Next.js cannot serve multiple pages at the exact same URL. Remove or rename one of the conflicting routes.",
+            });
+        }
+    }
+    // -------------------------------------------------------------
+    // Rule 4: Dynamic Segment Collisions (no-route-collisions)
+    // -------------------------------------------------------------
+    const patternMap = new Map();
+    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 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.",
+            });
+        }
+    }
+    // -------------------------------------------------------------
+    // Rule 5: Parallel Route Slot Fallback (parallel-missing-default)
+    // -------------------------------------------------------------
+    const slotDirs = new Set();
+    for (const file of files) {
+        const parts = file.relativePath.replace(/\\/g, "/").split("/");
+        for (let i = 0; i < parts.length - 1; i++) {
+            if (parts[i]?.startsWith("@")) {
+                const slotPath = parts.slice(0, i + 1).join("/");
+                slotDirs.add(slotPath);
+            }
+        }
+    }
+    for (const slotDir of slotDirs) {
+        const slotFiles = dirGroup.get(slotDir) || [];
+        const hasDefault = slotFiles.some((f) => /^default\.(tsx|ts|jsx|js)$/.test(f.fileName));
+        if (!hasDefault) {
+            issues.push({
+                rule: "parallel-missing-default",
+                severity: "warning",
+                filePath: slotDir,
+                message: `Parallel route slot "${slotDir}" does not define a default.(tsx|js) fallback.`,
+                hint: "Next.js requires default.js in parallel slots to prevent 404s when navigating between unrelated pages.",
+            });
+        }
+    }
+    // -------------------------------------------------------------
+    // Rule 6: Global Error Boundary Location (global-error-location)
+    // -------------------------------------------------------------
+    for (const file of files) {
+        if (/^global-error\.(tsx|ts|jsx|js)$/.test(file.fileName)) {
+            const dir = path.dirname(file.relativePath).replace(/\\/g, "/");
+            const isRoot = dir === "." || dir === "";
+            if (!isRoot) {
+                issues.push({
+                    rule: "global-error-location",
+                    severity: "warning",
+                    filePath: file.relativePath,
+                    message: `global-error must be defined at the root App Router directory, but was found in "${dir}".`,
+                    hint: "Move global-error.(tsx|js) to the root app directory. Subdirectories should use error.(tsx|js).",
+                });
+            }
+        }
+    }
+    const errorCount = issues.filter((i) => i.severity === "error").length;
+    const warningCount = issues.filter((i) => i.severity === "warning").length;
+    const infoCount = issues.filter((i) => i.severity === "info").length;
+    return {
+        issues,
+        hasErrors: errorCount > 0,
+        errorCount,
+        warningCount,
+        infoCount,
+    };
+}

package/dist/core/parser.d.ts

@@ -0,0 +1,95 @@
+import { HttpMethod, RenderingType, SpecialFileType } from "../types/index.js";
+/**
+ * Recognizable Next.js App Router special file names without extensions
+ */
+export declare const SPECIAL_FILES: Set<SpecialFileType>;
+/**
+ * Standard HTTP methods handled by Next.js route handlers
+ */
+export declare const HTTP_METHODS: readonly HttpMethod[];
+/**
+ * Determines whether a file name matches a Next.js App Router convention file.
+ *
+ * @param fileName - File name with extension (e.g., 'page.tsx', 'layout.js', 'global-error.tsx')
+ * @returns SpecialFileType or null if it's not a recognized convention file
+ */
+export declare function parseSpecialFileType(fileName: string): SpecialFileType | null;
+/**
+ * Extracts prologue directives (e.g., "use client", "use server") declared at the
+ * top of a JavaScript/TypeScript source file.
+ *
+ * Accurately skips shebangs, whitespace, single-line comments, and multi-line comments.
+ * Avoids false positives from comments, template strings, or inner variables.
+ *
+ * @param content - Source file content
+ * @returns Set of discovered directive strings
+ */
+export declare function getPrologueDirectives(content: string): Set<string>;
+/**
+ * Strips comments from JavaScript/TypeScript source code to avoid false positives
+ * when matching exported declarations.
+ */
+export declare function stripComments(content: string): string;
+/**
+ * Analyzes the source content or file on disk to detect if a "use client" directive is present.
+ * Defaults to 'server' per Next.js App Router defaults.
+ *
+ * @param fileContentOrPath - Source code string or disk path to the file
+ * @returns 'client' if "use client" directive is declared, otherwise 'server'
+ */
+export declare function detectRenderingType(fileContentOrPath: string): Promise<RenderingType>;
+/**
+ * Inspects a route file's source content to detect exported HTTP methods.
+ * Used for App Router route.ts handlers.
+ * Ignores commented-out declarations and matches multiline or typed exports.
+ *
+ * @param content - Source code content of the file
+ * @returns Array of discovered HTTP methods
+ */
+export declare function detectHttpMethods(content: string): HttpMethod[];
+/**
+ * Detects if a file defines Server Actions via the "use server" directive.
+ * Checks file-level directive as well as inline function-level Server Actions.
+ *
+ * @param content - Source code content of the file
+ * @returns True if the file contains a "use server" directive
+ */
+export declare function detectServerActions(content: string): boolean;
+/**
+ * Extracts route segment configuration options like runtime and dynamic mode.
+ * Supports TypeScript type annotations and ignores commented-out code.
+ *
+ * @param content - Source code content
+ * @returns Extracted configuration object
+ */
+export declare function detectRouteConfig(content: string): {
+    runtime?: "nodejs" | "edge";
+    dynamicConfig?: "auto" | "force-dynamic" | "error" | "force-static";
+};
+/**
+ * Extracts parallel slots (e.g., '@modal') and intercepting markers from a path.
+ *
+ * @param relativePath - Relative file path
+ * @returns Discovered metadata about slots and intercepting patterns
+ */
+export declare function extractRouteMetadata(relativePath: string): {
+    slots: string[];
+    intercepting?: string;
+};
+/**
+ * Normalizes a relative filesystem path within App Router into a public URL route.
+ * Handles Route Groups (folder), Parallel Routes (@slot), and Intercepting Routes.
+ * Decodes Next.js %5F prefixes to underscores for public URLs.
+ *
+ * @param relativePath - App-relative path to a convention file (e.g. 'blog/[slug]/page.tsx')
+ * @returns Normalized URL path (e.g. '/blog/[slug]')
+ */
+export declare function parseRoutePath(relativePath: string): string;
+/**
+ * Classifies a route path into its segment dynamic type.
+ *
+ * @param routePath - Normalized route path
+ * @returns 'optional-catch-all' | 'catch-all' | 'dynamic' | 'static'
+ */
+export declare function getSegmentType(routePath: string): "static" | "dynamic" | "catch-all" | "optional-catch-all";
+//# sourceMappingURL=parser.d.ts.map

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

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

@@ -1,15 +1,37 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+/**
+ * Recognizable Next.js App Router special file names without extensions
+ */
 export const SPECIAL_FILES = new Set([
     "page",
     "layout",
     "loading",
     "error",
+    "global-error",
     "not-found",
     "template",
     "default",
     "route",
 ]);
+/**
+ * Standard HTTP methods handled by Next.js route handlers
+ */
+export const HTTP_METHODS = [
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+];
+/**
+ * Determines whether a file name matches a Next.js App Router convention file.
+ *
+ * @param fileName - File name with extension (e.g., 'page.tsx', 'layout.js', 'global-error.tsx')
+ * @returns SpecialFileType or null if it's not a recognized convention file
+ */
 export function parseSpecialFileType(fileName) {
     const baseName = path.parse(fileName).name;
     if (SPECIAL_FILES.has(baseName)) {
@@ -17,46 +39,251 @@ export function parseSpecialFileType(fileName) {
     }
     return null;
 }
-export async function detectRenderingType(filePath) {
-    try {
-        const content = await fs.readFile(filePath, "utf-8");
-        const firstLines = content.slice(0, 500);
-        const clientDirectiveRegex = /^(?:(?:\s*\/\/.*?\n)|(?:\s*\/\*[\s\S]*?\*\/)|(?:\s*))["']use client["']/m;
-        if (clientDirectiveRegex.test(firstLines)) {
-            return "client";
+/**
+ * Extracts prologue directives (e.g., "use client", "use server") declared at the
+ * top of a JavaScript/TypeScript source file.
+ *
+ * Accurately skips shebangs, whitespace, single-line comments, and multi-line comments.
+ * Avoids false positives from comments, template strings, or inner variables.
+ *
+ * @param content - Source file content
+ * @returns Set of discovered directive strings
+ */
+export function getPrologueDirectives(content) {
+    const directives = new Set();
+    let code = content.replace(/^#![^\n]*\n/, ""); // Strip shebang if present
+    let index = 0;
+    const len = code.length;
+    while (index < len) {
+        // Skip whitespace
+        while (index < len && /\s/.test(code[index])) {
+            index++;
+        }
+        if (index >= len)
+            break;
+        // Skip single-line comments
+        if (code[index] === "/" && code[index + 1] === "/") {
+            index += 2;
+            while (index < len && code[index] !== "\n") {
+                index++;
+            }
+            continue;
+        }
+        // Skip multi-line comments
+        if (code[index] === "/" && code[index + 1] === "*") {
+            index += 2;
+            while (index < len && !(code[index] === "*" && code[index + 1] === "/")) {
+                index++;
+            }
+            if (index < len) {
+                index += 2; // skip */
+            }
+            continue;
+        }
+        // Check string literal directive: 'use ...' or "use ..."
+        const char = code[index];
+        if (char === '"' || char === "'") {
+            const quote = char;
+            let endIndex = index + 1;
+            while (endIndex < len &&
+                code[endIndex] !== quote &&
+                code[endIndex] !== "\n") {
+                endIndex++;
+            }
+            if (endIndex < len && code[endIndex] === quote) {
+                const strVal = code.slice(index + 1, endIndex);
+                let after = endIndex + 1;
+                while (after < len && (code[after] === " " || code[after] === "\t")) {
+                    after++;
+                }
+                if (after >= len ||
+                    code[after] === ";" ||
+                    code[after] === "\n" ||
+                    code[after] === "\r") {
+                    directives.add(strVal);
+                    index = code[after] === ";" ? after + 1 : after;
+                    continue;
+                }
+            }
+        }
+        // Any non-directive token ends the directive prologue
+        break;
+    }
+    return directives;
+}
+/**
+ * Strips comments from JavaScript/TypeScript source code to avoid false positives
+ * when matching exported declarations.
+ */
+export function stripComments(content) {
+    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.
+ * Defaults to 'server' per Next.js App Router defaults.
+ *
+ * @param fileContentOrPath - Source code string or disk path to the file
+ * @returns 'client' if "use client" directive is declared, otherwise 'server'
+ */
+export async function detectRenderingType(fileContentOrPath) {
+    let content = fileContentOrPath;
+    // If input looks like a potential file path, attempt reading from disk
+    if (!fileContentOrPath.includes("\n") &&
+        !fileContentOrPath.includes("\r") &&
+        !fileContentOrPath.includes(";") &&
+        !fileContentOrPath.includes("{")) {
+        try {
+            content = await fs.readFile(fileContentOrPath, "utf-8");
+        }
+        catch {
+            // If reading fails, treat input string directly as content
+            content = fileContentOrPath;
         }
     }
-    catch { }
-    return "server";
+    const directives = getPrologueDirectives(content);
+    return directives.has("use client") ? "client" : "server";
 }
+/**
+ * Inspects a route file's source content to detect exported HTTP methods.
+ * Used for App Router route.ts handlers.
+ * Ignores commented-out declarations and matches multiline or typed exports.
+ *
+ * @param content - Source code content of the file
+ * @returns Array of discovered HTTP methods
+ */
+export function detectHttpMethods(content) {
+    const cleanCode = stripComments(content);
+    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 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.
+ * Checks file-level directive as well as inline function-level Server Actions.
+ *
+ * @param content - Source code content of the file
+ * @returns True if the file contains a "use server" directive
+ */
+export function detectServerActions(content) {
+    const directives = getPrologueDirectives(content);
+    if (directives.has("use server")) {
+        return true;
+    }
+    const cleanCode = stripComments(content);
+    // Matches inline server actions: async function / function / arrow function body starting with 'use server'
+    const inlinePattern = /(?:async\s+function|function|\=>)\s*[^{]*\{[\s\r\n]*['"]use server['"]/m;
+    return inlinePattern.test(cleanCode);
+}
+/**
+ * Extracts route segment configuration options like runtime and dynamic mode.
+ * Supports TypeScript type annotations and ignores commented-out code.
+ *
+ * @param content - Source code content
+ * @returns Extracted configuration object
+ */
+export function detectRouteConfig(content) {
+    const result = {};
+    const cleanCode = stripComments(content);
+    const runtimeMatch = cleanCode.match(/export\s+(?:const|let)\s+runtime(?:\s*:\s*[^=]+)?\s*=\s*['"](nodejs|edge)['"]/);
+    if (runtimeMatch?.[1]) {
+        result.runtime = runtimeMatch[1];
+    }
+    const dynamicMatch = cleanCode.match(/export\s+(?:const|let)\s+dynamic(?:\s*:\s*[^=]+)?\s*=\s*['"](auto|force-dynamic|error|force-static)['"]/);
+    if (dynamicMatch?.[1]) {
+        result.dynamicConfig = dynamicMatch[1];
+    }
+    return result;
+}
+/**
+ * Extracts parallel slots (e.g., '@modal') and intercepting markers from a path.
+ *
+ * @param relativePath - Relative file path
+ * @returns Discovered metadata about slots and intercepting patterns
+ */
+export function extractRouteMetadata(relativePath) {
+    const parts = relativePath.split("/");
+    const slots = [];
+    let intercepting;
+    for (const part of parts) {
+        if (part.startsWith("@")) {
+            slots.push(part);
+        }
+        // Match (..)(..) before (..)
+        const interceptMatch = part.match(/^(\(\.\.\)\(\.\.\)|\(\.\.\.\)|\(\.\.\)|\(\.\))/);
+        if (interceptMatch && !intercepting) {
+            intercepting = interceptMatch[1];
+        }
+    }
+    return { slots, intercepting };
+}
+/**
+ * Normalizes a relative filesystem path within App Router into a public URL route.
+ * Handles Route Groups (folder), Parallel Routes (@slot), and Intercepting Routes.
+ * Decodes Next.js %5F prefixes to underscores for public URLs.
+ *
+ * @param relativePath - App-relative path to a convention file (e.g. 'blog/[slug]/page.tsx')
+ * @returns Normalized URL path (e.g. '/blog/[slug]')
+ */
 export function parseRoutePath(relativePath) {
     const parts = relativePath.split("/");
-    parts.pop();
+    parts.pop(); // Remove file name
     const urlSegments = [];
     for (const part of parts) {
         if (!part)
             continue;
+        // Ignore Route Groups like (marketing) or (shop)
         if (part.startsWith("(") && part.endsWith(")")) {
             const inner = part.slice(1, -1);
             if (!inner.startsWith(".") && inner !== "...") {
                 continue;
             }
         }
+        // Ignore parallel route slot directories like @analytics or @auth
         if (part.startsWith("@")) {
             continue;
         }
         let cleanedPart = part;
-        if (cleanedPart.startsWith("(.)") ||
-            cleanedPart.startsWith("(..)") ||
-            cleanedPart.startsWith("(...)") ||
-            cleanedPart.startsWith("(..)(..)")) {
-            cleanedPart = cleanedPart.replace(/^(?:\(\.\.\.\)|\(\.\.\)|\(\.\))/, "");
+        // Decode escaped underscore %5F per Next.js spec
+        if (cleanedPart.startsWith("%5F") || cleanedPart.startsWith("%5f")) {
+            cleanedPart = "_" + cleanedPart.slice(3);
+        }
+        // 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("/");
     return routePath === "/" ? "/" : routePath.replace(/\/+/g, "/");
 }
+/**
+ * Classifies a route path into its segment dynamic type.
+ *
+ * @param routePath - Normalized route path
+ * @returns 'optional-catch-all' | 'catch-all' | 'dynamic' | 'static'
+ */
 export function getSegmentType(routePath) {
     if (routePath.includes("[[...")) {
         return "optional-catch-all";

package/dist/core/scanner.d.ts

@@ -0,0 +1,12 @@
+import { DiscoveredFile } from "../types/index.js";
+/**
+ * Recursively scans a Next.js App Router directory to discover route-related source files.
+ * Correctly ignores private folders (_folder), hidden directories, and build artifacts.
+ *
+ * @param rootDir - Root App Router directory path
+ * @param currentDir - Current directory during recursive traversal
+ * @returns Array of discovered App Router files
+ * @throws {RouteDirectoryReadError} If directory reading fails
+ */
+export declare function scanAppDir(rootDir: string, currentDir?: string): Promise<DiscoveredFile[]>;
+//# sourceMappingURL=scanner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/core/scanner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AA6BnD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,MAAgB,GAC3B,OAAO,CAAC,cAAc,EAAE,CAAC,CAmC3B"}

package/dist/core/scanner.js

@@ -1,27 +1,53 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { RouteDirectoryReadError } from "../errors/index.js";
 const ALLOWED_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx"]);
-const IGNORE_DIRS = new Set([
+const IGNORE_DIR_NAMES = new Set([
     "node_modules",
-    ".git",
-    ".next",
     "dist",
     "build",
     "coverage",
+    "out",
+    ".next",
+    ".git",
+    ".turbo",
+    ".vercel",
 ]);
+/**
+ * Checks whether a directory should be excluded from App Router route discovery.
+ * Follows Next.js conventions:
+ * - Folders starting with '_' are Private Folders (opted out of routing).
+ * - Folders starting with '.' are hidden / tooling directories.
+ * - Build output and dependency folders are excluded.
+ */
+function shouldIgnoreDirectory(dirName) {
+    if (dirName.startsWith("_") || dirName.startsWith(".")) {
+        return true;
+    }
+    return IGNORE_DIR_NAMES.has(dirName);
+}
+/**
+ * Recursively scans a Next.js App Router directory to discover route-related source files.
+ * Correctly ignores private folders (_folder), hidden directories, and build artifacts.
+ *
+ * @param rootDir - Root App Router directory path
+ * @param currentDir - Current directory during recursive traversal
+ * @returns Array of discovered App Router files
+ * @throws {RouteDirectoryReadError} If directory reading fails
+ */
 export async function scanAppDir(rootDir, currentDir = rootDir) {
     let files = [];
     let entries;
     try {
         entries = await fs.readdir(currentDir, { withFileTypes: true });
     }
-    catch {
-        throw new Error("Unable to read the App Router directory.");
+    catch (err) {
+        throw new RouteDirectoryReadError(currentDir, err);
     }
     for (const entry of entries) {
         const fullPath = path.join(currentDir, entry.name);
         if (entry.isDirectory()) {
-            if (!IGNORE_DIRS.has(entry.name)) {
+            if (!shouldIgnoreDirectory(entry.name)) {
                 const subFiles = await scanAppDir(rootDir, fullPath);
                 files = files.concat(subFiles);
             }