@supernal/interface 1.0.0

package/dist/esm/src/routes/RouteContractGenerator.d.ts

@@ -0,0 +1,37 @@
+import { RouteScanResult } from './scanners/RouteScanner';
+/**
+ * Generates type-safe route contracts with structured output.
+ * Groups routes by category (Views, API, etc.) and HTTP methods.
+ *
+ * @example
+ * ```typescript
+ * import { RouteContractGenerator } from '@supernal/interface-core/routes';
+ *
+ * const generator = new RouteContractGenerator();
+ * const scanResult = await scanner.scan();
+ *
+ * // Generate contracts
+ * const content = generator.generate(scanResult);
+ *
+ * // Generated output:
+ * // export const Routes = {
+ * //   Views: {
+ * //     Overview: '/:repo/:branch/overview'
+ * //   },
+ * //   API: {
+ * //     Users: {
+ * //       GET: '/api/users',
+ * //       POST: '/api/users'
+ * //     }
+ * //   }
+ * // } as const;
+ * ```
+ */
+export declare class RouteContractGenerator {
+    generate(scanResult: RouteScanResult): string;
+    private groupRoutes;
+    private generateViews;
+    private generateAPI;
+    private toPascalCase;
+}
+//# sourceMappingURL=RouteContractGenerator.d.ts.map

package/dist/esm/src/routes/RouteContractGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteContractGenerator.d.ts","sourceRoot":"","sources":["../../../../src/routes/RouteContractGenerator.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,sBAAsB;IACjC,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,MAAM;IA2B7C,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,WAAW;IA+BnB,OAAO,CAAC,YAAY;CAMrB"}

package/dist/esm/src/routes/RouteContractGenerator.js

@@ -0,0 +1,115 @@
+// Generated from: 2025-12-28-simple-name-extraction.md
+// Generated on: 2025-12-28
+// DO NOT EDIT - Regenerate from documentation if changes needed
+/**
+ * Generates type-safe route contracts with structured output.
+ * Groups routes by category (Views, API, etc.) and HTTP methods.
+ *
+ * @example
+ * ```typescript
+ * import { RouteContractGenerator } from '@supernal/interface-core/routes';
+ *
+ * const generator = new RouteContractGenerator();
+ * const scanResult = await scanner.scan();
+ *
+ * // Generate contracts
+ * const content = generator.generate(scanResult);
+ *
+ * // Generated output:
+ * // export const Routes = {
+ * //   Views: {
+ * //     Overview: '/:repo/:branch/overview'
+ * //   },
+ * //   API: {
+ * //     Users: {
+ * //       GET: '/api/users',
+ * //       POST: '/api/users'
+ * //     }
+ * //   }
+ * // } as const;
+ * ```
+ */
+export class RouteContractGenerator {
+    generate(scanResult) {
+        // Group routes by category
+        const grouped = this.groupRoutes(scanResult.routes);
+        return `
+// Generated from route scanning
+// DO NOT EDIT - Regenerate with: sc routes generate
+
+${this.generateViews(grouped.view)}
+${this.generateAPI(grouped.api)}
+
+// Helper to build route with params
+// Supports both string patterns and route objects with metadata
+export function buildRoute(
+  route: string | { pattern: string; [key: string]: any }, 
+  params: Record<string, string>
+): string {
+  const pattern = typeof route === 'string' ? route : route.pattern;
+  let result = pattern;
+  for (const [key, value] of Object.entries(params)) {
+    result = result.replace(\`:$\{key}\`, value);
+  }
+  return result;
+}
+`.trim();
+    }
+    groupRoutes(routes) {
+        const grouped = {};
+        routes.forEach(route => {
+            const category = route.metadata?.category || 'other';
+            if (!grouped[category])
+                grouped[category] = [];
+            grouped[category].push(route);
+        });
+        return grouped;
+    }
+    generateViews(views = []) {
+        if (views.length === 0)
+            return '';
+        const entries = views.map(view => {
+            const name = this.toPascalCase(view.id.replace('view-', ''));
+            return `    ${name}: '${view.pattern}',`;
+        }).join('\n');
+        return `
+export const Routes = {
+  Views: {
+${entries}
+  },
+`;
+    }
+    generateAPI(apis = []) {
+        if (apis.length === 0)
+            return '';
+        const entries = apis.map(api => {
+            const name = this.toPascalCase(api.id.replace('api-', ''));
+            const methods = api.metadata?.methods;
+            const params = api.params;
+            // Generate route object with metadata
+            if (methods || params.length > 0) {
+                const parts = [
+                    `pattern: '${api.pattern}'`,
+                    methods && methods.length > 0 ? `methods: [${methods.map(m => `'${m}'`).join(', ')}] as const` : null,
+                    params.length > 0 ? `params: [${params.map(p => `'${p}'`).join(', ')}] as const` : null,
+                ].filter(Boolean);
+                return `    ${name}: {\n      ${parts.join(',\n      ')}\n    },`;
+            }
+            // Fallback: simple string (for backward compatibility)
+            return `    ${name}: '${api.pattern}',`;
+        }).join('\n');
+        return `
+  API: {
+${entries}
+  },
+} as const;
+`;
+    }
+    toPascalCase(str) {
+        return str
+            .split(/[-_]/)
+            .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+            .join('');
+    }
+}
+//# sourceMappingURL=RouteContractGenerator.js.map

package/dist/esm/src/routes/RouteContractGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteContractGenerator.js","sourceRoot":"","sources":["../../../../src/routes/RouteContractGenerator.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/routes/RouteContractsConfig.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Configuration for route contract generation
+ *
+ * This config lives in the target project (e.g., apps/my-dashboard/route-contracts.config.ts)
+ * and tells the generator where to find routes and where to output contracts.
+ */
+/**
+ * Route information structure
+ */
+export interface RouteInfo {
+    id: string;
+    pattern: string;
+    params: string[];
+    metadata?: {
+        description?: string;
+        source?: string;
+        [key: string]: any;
+    };
+}
+export interface RouteContractsConfig {
+    /**
+     * Type of routing system
+     * Determines which scanner to use
+     */
+    routingSystem: 'nextjs-dynamic' | 'nextjs-pages' | 'react-router' | 'custom' | 'manual' | 'nextjs-name-extraction';
+    /**
+     * Manual route specification (optional)
+     * Use this for non-standard routing systems or when scanner can't detect routes
+     */
+    routes?: RouteInfo[];
+    /**
+     * Paths to scan for route definitions (relative to project root)
+     */
+    scanPaths: {
+        /** Where to find route definitions (e.g., src/app for Next.js 14) */
+        routes?: string[];
+        /** Where to find route config files (e.g., routing.config.ts) */
+        configs?: string[];
+        /** Where to find view/page components */
+        components?: string[];
+    };
+    /**
+     * Output configuration
+     */
+    output: {
+        /** Where to write Routes.ts (relative to project root) */
+        contractsPath: string;
+        /** Where to write test utilities (optional) */
+        testUtilsPath?: string;
+        /** TypeScript module format */
+        moduleFormat?: 'esm' | 'commonjs';
+    };
+    /**
+     * Route extraction patterns (for custom routing systems)
+     */
+    extraction?: {
+        /** Regex patterns to find route definitions */
+        patterns?: string[];
+        /** File extensions to scan */
+        extensions?: string[];
+        /** Custom scanner function (advanced) */
+        customScanner?: string;
+    };
+    /**
+     * Generation options
+     */
+    generation?: {
+        /** Include JSDoc comments */
+        includeJsDocs?: boolean;
+        /** Add validation helpers */
+        includeValidation?: boolean;
+        /** Add type guards */
+        includeTypeGuards?: boolean;
+        /** Default parameter values (per route) */
+        defaults?: Record<string, any>;
+    };
+    /**
+     * Migration options
+     */
+    migration?: {
+        /** Patterns to detect routes in code */
+        detectPatterns?: string[];
+        /** File patterns to migrate */
+        filePatterns?: string[];
+        /** Dry run by default */
+        dryRun?: boolean;
+    };
+}
+/**
+ * Example config for Next.js 14 app with dynamic routing
+ */
+export declare const exampleNextjsConfig: RouteContractsConfig;
+//# sourceMappingURL=RouteContractsConfig.d.ts.map

package/dist/esm/src/routes/RouteContractsConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteContractsConfig.d.ts","sourceRoot":"","sources":["../../../../src/routes/RouteContractsConfig.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE;QACT,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,aAAa,EAAE,gBAAgB,GAAG,cAAc,GAAG,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,wBAAwB,CAAC;IAEnH;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IAErB;;OAEG;IACH,SAAS,EAAE;QACT,qEAAqE;QACrE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAElB,iEAAiE;QACjE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QAEnB,yCAAyC;QACzC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IAEF;;OAEG;IACH,MAAM,EAAE;QACN,0DAA0D;QAC1D,aAAa,EAAE,MAAM,CAAC;QAEtB,+CAA+C;QAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;QAEvB,+BAA+B;QAC/B,YAAY,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;KACnC,CAAC;IAEF;;OAEG;IACH,UAAU,CAAC,EAAE;QACX,+CAA+C;QAC/C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QAEpB,8BAA8B;QAC9B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QAEtB,yCAAyC;QACzC,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IAEF;;OAEG;IACH,UAAU,CAAC,EAAE;QACX,6BAA6B;QAC7B,aAAa,CAAC,EAAE,OAAO,CAAC;QAExB,6BAA6B;QAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAE5B,sBAAsB;QACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAE5B,2CAA2C;QAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAChC,CAAC;IAEF;;OAEG;IACH,SAAS,CAAC,EAAE;QACV,wCAAwC;QACxC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAE1B,+BAA+B;QAC/B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QAExB,yBAAyB;QACzB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,oBA4BjC,CAAC"}

package/dist/esm/src/routes/RouteContractsConfig.js

@@ -0,0 +1,36 @@
+// Generated from: 2025-12-27-implementation.md
+// Generated on: 2025-12-28
+// DO NOT EDIT - Regenerate from documentation if changes needed
+/**
+ * Example config for Next.js 14 app with dynamic routing
+ */
+export const exampleNextjsConfig = {
+    routingSystem: 'nextjs-dynamic',
+    scanPaths: {
+        routes: ['src/app'],
+        configs: ['src/lib/routing'],
+        components: ['src/components/views'],
+    },
+    output: {
+        contractsPath: 'src/lib/routing/Routes.ts',
+        testUtilsPath: 'tests/utils/routes.ts',
+        moduleFormat: 'esm',
+    },
+    generation: {
+        includeJsDocs: true,
+        includeValidation: true,
+        defaults: {
+            repo: 'default-repo',
+            branch: 'main',
+        },
+    },
+    migration: {
+        detectPatterns: [
+            'page\\.goto\\([\'"`](.+?)[\'"`]\\)',
+            'navigate\\([\'"`](.+?)[\'"`]\\)',
+        ],
+        filePatterns: ['**/*.spec.ts', '**/*.test.ts'],
+        dryRun: false,
+    },
+};
+//# sourceMappingURL=RouteContractsConfig.js.map

package/dist/esm/src/routes/RouteContractsConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteContractsConfig.js","sourceRoot":"","sources":["../../../../src/routes/RouteContractsConfig.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,2BAA2B;AAC3B,gEAAgE;AA8GhE;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAyB;IACvD,aAAa,EAAE,gBAAgB;IAC/B,SAAS,EAAE;QACT,MAAM,EAAE,CAAC,SAAS,CAAC;QACnB,OAAO,EAAE,CAAC,iBAAiB,CAAC;QAC5B,UAAU,EAAE,CAAC,sBAAsB,CAAC;KACrC;IACD,MAAM,EAAE;QACN,aAAa,EAAE,2BAA2B;QAC1C,aAAa,EAAE,uBAAuB;QACtC,YAAY,EAAE,KAAK;KACpB;IACD,UAAU,EAAE;QACV,aAAa,EAAE,IAAI;QACnB,iBAAiB,EAAE,IAAI;QACvB,QAAQ,EAAE;YACR,IAAI,EAAE,cAAc;YACpB,MAAM,EAAE,MAAM;SACf;KACF;IACD,SAAS,EAAE;QACT,cAAc,EAAE;YACd,oCAAoC;YACpC,iCAAiC;SAClC;QACD,YAAY,EAAE,CAAC,cAAc,EAAE,cAAc,CAAC;QAC9C,MAAM,EAAE,KAAK;KACd;CACF,CAAC"}

package/dist/esm/src/routes/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Route Scanning System
+ *
+ * Scans Next.js routes (App Router + Pages Router) and generates
+ * type-safe route contracts with HTTP method extraction.
+ */
+export { RouteScanner } from './scanners/RouteScanner';
+export type { RouteInfo, RouteScanResult } from './scanners/RouteScanner';
+export { NextjsDynamicScanner } from './scanners/NextjsDynamicScanner';
+export { NameExtractor } from './scanners/NameExtractor';
+export { RouteContractGenerator } from './RouteContractGenerator';
+export { RouteContractsConfig } from './RouteContractsConfig';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/src/routes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/routes/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/esm/src/routes/index.js

@@ -0,0 +1,13 @@
+/**
+ * Route Scanning System
+ *
+ * Scans Next.js routes (App Router + Pages Router) and generates
+ * type-safe route contracts with HTTP method extraction.
+ */
+// Scanners
+export { RouteScanner } from './scanners/RouteScanner.js';
+export { NextjsDynamicScanner } from './scanners/NextjsDynamicScanner.js';
+export { NameExtractor } from './scanners/NameExtractor.js';
+// Generation
+export { RouteContractGenerator } from './RouteContractGenerator.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/src/routes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/routes/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,WAAW;AACX,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAGvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,aAAa;AACb,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/esm/src/routes/scanners/NameExtractor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Extract route names from existing code
+ * No decorators, no metadata - just find what's already named
+ */
+export declare class NameExtractor {
+    /**
+     * Extract array literals from source files
+     * Example: const VALID_VIEWS = ['overview', 'planning', ...]
+     */
+    extractArrayLiteral(filePath: string, variableName: string): string[];
+    /**
+     * Extract routes from Next.js app directory structure
+     * Finds: app/api/[param]/route.ts
+     */
+    extractAppDirectoryRoutes(appDir: string, prefix?: string): Array<{
+        name: string;
+        pattern: string;
+        params: string[];
+        methods?: string[];
+        sourceFile?: string;
+    }>;
+    /**
+     * Extract HTTP methods from a Next.js route file
+     * Supports multiple export patterns:
+     * - export async function GET/POST/etc(...)
+     * - export function GET/POST/etc(...)
+     * - export const GET/POST/etc = ...
+     * - export { handler as GET, handler as POST }
+     * - export const { GET, POST } = handlers
+     */
+    extractHttpMethods(routeFilePath: string): string[] | undefined;
+    private buildRoutePattern;
+    private extractParams;
+    private buildRouteName;
+}
+//# sourceMappingURL=NameExtractor.d.ts.map

package/dist/esm/src/routes/scanners/NameExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NameExtractor.d.ts","sourceRoot":"","sources":["../../../../../src/routes/scanners/NameExtractor.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,qBAAa,aAAa;IACxB;;;OAGG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE;IA6BrE;;;OAGG;IACH,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,KAAK,CAAC;QACpE,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IA4CF;;;;;;;;OAQG;IACH,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IA8C/D,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,cAAc;CAYvB"}

package/dist/esm/src/routes/scanners/NameExtractor.js

@@ -0,0 +1,156 @@
+// Generated from: 2025-12-28-simple-name-extraction.md
+// Generated on: 2025-12-29
+// DO NOT EDIT - Regenerate from documentation if changes needed
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Extract route names from existing code
+ * No decorators, no metadata - just find what's already named
+ */
+export class NameExtractor {
+    /**
+     * Extract array literals from source files
+     * Example: const VALID_VIEWS = ['overview', 'planning', ...]
+     */
+    extractArrayLiteral(filePath, variableName) {
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            // Match: export const VALID_VIEWS = ['item1', 'item2', ...]
+            const pattern = new RegExp(`(?:export\\s+)?const\\s+${variableName}\\s*=\\s*\\[([^\\]]+)\\]`, 's');
+            const match = content.match(pattern);
+            if (!match)
+                return [];
+            // Parse string literals: 'item1', "item2", `item3`
+            const arrayContent = match[1];
+            const stringPattern = /['"`]([^'"`]+)['"`]/g;
+            const names = [];
+            let stringMatch;
+            while ((stringMatch = stringPattern.exec(arrayContent)) !== null) {
+                names.push(stringMatch[1]);
+            }
+            return names;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Extract routes from Next.js app directory structure
+     * Finds: app/api/[param]/route.ts
+     */
+    extractAppDirectoryRoutes(appDir, prefix = '') {
+        const routes = [];
+        const walkDir = (dir, currentPath = '') => {
+            if (!fs.existsSync(dir))
+                return;
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                const routePath = path.join(currentPath, entry.name);
+                if (entry.isDirectory()) {
+                    // Recurse into subdirectories
+                    walkDir(fullPath, routePath);
+                }
+                else if (entry.name === 'route.ts' || entry.name === 'route.js') {
+                    // Found a route file
+                    const segments = currentPath.split(path.sep).filter(s => s);
+                    const pattern = this.buildRoutePattern(segments, prefix);
+                    const params = this.extractParams(segments);
+                    const name = this.buildRouteName(segments);
+                    const methods = this.extractHttpMethods(fullPath);
+                    routes.push({
+                        name,
+                        pattern,
+                        params,
+                        methods,
+                        sourceFile: fullPath
+                    });
+                }
+            }
+        };
+        walkDir(appDir);
+        return routes;
+    }
+    /**
+     * Extract HTTP methods from a Next.js route file
+     * Supports multiple export patterns:
+     * - export async function GET/POST/etc(...)
+     * - export function GET/POST/etc(...)
+     * - export const GET/POST/etc = ...
+     * - export { handler as GET, handler as POST }
+     * - export const { GET, POST } = handlers
+     */
+    extractHttpMethods(routeFilePath) {
+        try {
+            const content = fs.readFileSync(routeFilePath, 'utf-8');
+            const methods = [];
+            const httpMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
+            for (const method of httpMethods) {
+                // Pattern 1: export async function GET( or export function GET(
+                const functionPattern = new RegExp(`export\\s+(?:async\\s+)?function\\s+${method}\\s*\\(`, 'm');
+                // Pattern 2: export const GET = ...
+                const constPattern = new RegExp(`export\\s+const\\s+${method}\\s*=`, 'm');
+                // Pattern 3: export { ... as GET, ... }
+                const reExportPattern = new RegExp(`export\\s*\\{[^}]*\\s+as\\s+${method}[,\\s}]`, 'm');
+                // Pattern 4: export const { GET, POST } = ...
+                const destructurePattern = new RegExp(`export\\s+const\\s*\\{[^}]*\\b${method}\\b[^}]*\\}`, 'm');
+                if (functionPattern.test(content) ||
+                    constPattern.test(content) ||
+                    reExportPattern.test(content) ||
+                    destructurePattern.test(content)) {
+                    methods.push(method);
+                }
+            }
+            return methods.length > 0 ? methods : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    buildRoutePattern(segments, prefix) {
+        const pathSegments = segments.map(seg => {
+            // [param] → :param
+            if (seg.startsWith('[') && seg.endsWith(']')) {
+                const param = seg.slice(1, -1);
+                // [[...catch]] → *catchAll (optional catch-all)
+                if (param.startsWith('[...') && param.endsWith(']')) {
+                    return `:${param.slice(4, -1)}*?`;
+                }
+                // [...catch] → *catchAll (required catch-all)
+                if (param.startsWith('...')) {
+                    return `:${param.slice(3)}*`;
+                }
+                // [param] → :param
+                return `:${param}`;
+            }
+            return seg;
+        });
+        return prefix + '/' + pathSegments.join('/');
+    }
+    extractParams(segments) {
+        return segments
+            .filter(seg => seg.startsWith('[') && seg.endsWith(']'))
+            .map(seg => {
+            const param = seg.slice(1, -1);
+            if (param.startsWith('...'))
+                return param.slice(3);
+            if (param.startsWith('[...') && param.endsWith(']')) {
+                return param.slice(4, -1);
+            }
+            return param;
+        });
+    }
+    buildRouteName(segments) {
+        // Convert path segments to PascalCase name
+        // api/[repoId]/requirements → RepoIdRequirements
+        return segments
+            .map(seg => {
+            // Strip brackets and dots: [repoId] → repoId
+            const clean = seg.replace(/[[\].]/g, '');
+            // PascalCase: repoId → RepoId
+            return clean.charAt(0).toUpperCase() + clean.slice(1);
+        })
+            .join('');
+    }
+}
+//# sourceMappingURL=NameExtractor.js.map

package/dist/esm/src/routes/scanners/NameExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NameExtractor.js","sourceRoot":"","sources":["../../../../../src/routes/scanners/NameExtractor.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/routes/scanners/NextjsDynamicScanner.d.ts

@@ -0,0 +1,35 @@
+import { RouteScanner, RouteInfo, RouteScanResult } from './RouteScanner';
+/**
+ * Scanner that extracts route names from Next.js applications.
+ *
+ * Supports two discovery strategies:
+ * 1. VALID_VIEWS arrays - Extracts view names from configuration files
+ * 2. App directory structure - Scans Next.js App Router directories for API routes
+ *
+ * @example
+ * ```typescript
+ * import { NextjsDynamicScanner } from '@supernal/interface-core/routes';
+ *
+ * const scanner = new NextjsDynamicScanner({
+ *   routingSystem: 'nextjs-name-extraction',
+ *   scanPaths: {
+ *     configs: ['src/lib/routing/slugService.ts'],  // Contains VALID_VIEWS
+ *     routes: ['src/app/api']                        // API routes directory
+ *   },
+ *   output: {
+ *     contractsPath: 'src/lib/routing/Routes.ts',
+ *     moduleFormat: 'esm'
+ *   }
+ * });
+ *
+ * const result = await scanner.scan();
+ * // result.routes contains all discovered routes
+ * ```
+ */
+export declare class NextjsDynamicScanner extends RouteScanner {
+    private extractor;
+    getName(): string;
+    scan(): Promise<RouteScanResult>;
+    validate(routes: RouteInfo[]): Promise<boolean>;
+}
+//# sourceMappingURL=NextjsDynamicScanner.d.ts.map

package/dist/esm/src/routes/scanners/NextjsDynamicScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NextjsDynamicScanner.d.ts","sourceRoot":"","sources":["../../../../../src/routes/scanners/NextjsDynamicScanner.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAG1E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,OAAO,CAAC,SAAS,CAAuB;IAExC,OAAO,IAAI,MAAM;IAIX,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC;IA+DhC,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CAItD"}