@arcadialdev/arcality 3.0.4 → 4.0.0

package/src/services/routeDiscovery.mjs

@@ -0,0 +1,747 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PAGE_FILE_RE = /\.(js|jsx|ts|tsx)$/i;
+const IGNORE_DIRS = new Set([
+    '.git',
+    '.arcality',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    'logs',
+    'public',
+    'tests',
+    'bin'
+]);
+
+function toPosix(value) {
+    return String(value || '').split(path.sep).join('/');
+}
+
+function walk(dir, out = []) {
+    if (!fs.existsSync(dir)) return out;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (IGNORE_DIRS.has(entry.name)) continue;
+            walk(path.join(dir, entry.name), out);
+        } else {
+            out.push(path.join(dir, entry.name));
+        }
+    }
+    return out;
+}
+
+function stripExtension(filePath) {
+    return filePath.replace(/\.(js|jsx|ts|tsx)$/i, '');
+}
+
+function humanizeSegment(value) {
+    return String(value || '')
+        .replace(/\[[^\]]+\]/g, 'detalle')
+        .replace(/[()]/g, '')
+        .replace(/[-_]+/g, ' ')
+        .replace(/\b\w/g, char => char.toUpperCase());
+}
+
+function normalizeRoute(route) {
+    const text = String(route || '').trim();
+    if (!text || text === '/') return '/';
+    const normalized = text.startsWith('/') ? text : `/${text}`;
+    return normalized.replace(/\/+/g, '/');
+}
+
+function getBaseUrlPathSegments(baseUrl) {
+    try {
+        const pathname = new URL(String(baseUrl || '')).pathname || '/';
+        return pathname.split('/').filter(Boolean);
+    } catch {
+        return [];
+    }
+}
+
+function extractRouteParams(route) {
+    const params = [];
+    const normalized = normalizeRoute(route);
+    const nextMatches = normalized.matchAll(/\[([^\]]+)\]/g);
+    for (const match of nextMatches) {
+        const raw = match[1];
+        if (!raw) continue;
+        const catchAll = raw.startsWith('...');
+        const optionalCatchAll = raw.startsWith('[...');
+        const name = raw.replace(/^\.\.\./, '').replace(/^\[|\]$/g, '');
+        params.push({
+            name,
+            kind: catchAll || optionalCatchAll ? 'catch-all' : 'segment'
+        });
+    }
+
+    const reactMatches = normalized.matchAll(/:([a-zA-Z0-9_]+)/g);
+    for (const match of reactMatches) {
+        const name = match[1];
+        if (!name) continue;
+        if (params.some(param => param.name === name)) continue;
+        params.push({
+            name,
+            kind: 'segment'
+        });
+    }
+
+    return params;
+}
+
+function inferExampleValue(name, kind = 'segment', context = {}) {
+    const lower = String(name || '').toLowerCase();
+    const preferred = Array.isArray(context.preferredValues) ? context.preferredValues : [];
+    if (preferred.length > 0) return preferred[0];
+    if (kind === 'catch-all') return 'sample/nested/path';
+    if (lower === 'id' || lower.endsWith('id')) return '123';
+    if (lower.includes('uuid')) return '11111111-1111-1111-1111-111111111111';
+    if (lower.includes('slug')) return 'sample-item';
+    if (lower.includes('email')) return 'qa@example.com';
+    if (lower.includes('token')) return 'sample-token';
+    if (lower.includes('date')) return '2026-01-15';
+    if (lower.includes('year')) return '2026';
+    if (lower.includes('month')) return '06';
+    return 'sample-value';
+}
+
+function buildExampleRoute(route, params = [], context = {}) {
+    let exampleRoute = normalizeRoute(route);
+    for (const param of params) {
+        const nextToken = `[${param.kind === 'catch-all' ? '...' : ''}${param.name}]`;
+        const reactToken = `:${param.name}`;
+        const value = inferExampleValue(param.name, param.kind, param.exampleContext || context);
+        exampleRoute = exampleRoute.replace(nextToken, value).replace(reactToken, value);
+    }
+    return exampleRoute;
+}
+
+function inferRouteFamily(route) {
+    const normalized = normalizeRoute(route);
+    if (normalized === '/') return '/';
+    const parts = normalized.split('/').filter(Boolean);
+    if (parts.length <= 1) return normalized;
+    return `/${parts.filter(part => !/^\[.*\]$/.test(part) && !/^:/.test(part)).slice(0, 2).join('/')}` || normalized;
+}
+
+function inferPrimaryRouteTag(route) {
+    const parts = normalizeRoute(route).split('/').filter(Boolean);
+    const firstStatic = parts.find(part => !/^\[.*\]$/.test(part) && !/^:/.test(part));
+    return firstStatic || (parts[0] || 'general');
+}
+
+function slugifyRouteSegment(value) {
+    return String(value || '')
+        .replace(/^\[\.{3}/, '')
+        .replace(/^\[/, '')
+        .replace(/\]$/, '')
+        .replace(/[^\w-]+/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+}
+
+function buildRouteParams(route, projectContext = {}) {
+    const params = extractRouteParams(route);
+    const baseSegments = getBaseUrlPathSegments(projectContext.baseUrl);
+    let baseIndex = 0;
+
+    return params.map(param => {
+        const lower = String(param.name || '').toLowerCase();
+        let preferredValues = [];
+
+        if (lower === 'lang' || lower === 'locale') {
+            if (baseSegments[baseIndex]) {
+                preferredValues.push(baseSegments[baseIndex]);
+                baseIndex += 1;
+            }
+        } else if (lower === 'code' || lower === 'site' || lower === 'tenant') {
+            if (baseSegments[baseIndex]) {
+                preferredValues.push(baseSegments[baseIndex]);
+                baseIndex += 1;
+            }
+        }
+
+        return {
+            ...param,
+            exampleContext: { preferredValues }
+        };
+    });
+}
+
+function buildMissionName(route) {
+    if (route === '/') return 'GEN_home';
+    const parts = normalizeRoute(route).split('/').filter(Boolean);
+    const staticParts = parts.filter(part => !/^\[.*\]$/.test(part) && !/^:/.test(part)).map(slugifyRouteSegment).filter(Boolean);
+    const dynamicParts = parts
+        .filter(part => /^\[.*\]$/.test(part) || /^:/.test(part))
+        .map(part => slugifyRouteSegment(part.replace(/^:/, '')))
+        .filter(Boolean);
+
+    const staticTail = staticParts.slice(-3);
+    const dynamicTail = dynamicParts.slice(-1);
+    const slugParts = staticTail.length > 0 ? [...staticTail, ...dynamicTail] : (dynamicTail.length > 0 ? dynamicTail : ['route']);
+    const slug = slugParts.join('_') || 'home';
+    return `GEN_${slug}`;
+}
+
+function buildPrompt(route, routeMeta = {}) {
+    if (route === '/') {
+        return 'Abre la pagina principal y valida que cargue correctamente, mostrando contenido util y sin errores visibles.';
+    }
+    const label = humanizeSegment(route.replace(/^\/+/, ''));
+    if (routeMeta.isDynamicRoute && routeMeta.exampleRoute) {
+        return `Navega a ${route} y valida el flujo principal de ${label}, usando una ruta ejemplo como ${routeMeta.exampleRoute} para comprobar carga correcta, contexto del registro y ausencia de errores observables.`;
+    }
+    return `Navega a ${route} y valida el flujo principal de ${label}, verificando carga correcta, elementos clave visibles y ausencia de errores observables.`;
+}
+
+function buildExpectedResult(route, routeMeta = {}) {
+    if (route === '/') {
+        return 'La pagina principal carga correctamente y muestra contenido clave sin errores visibles.';
+    }
+    if (routeMeta.isDynamicRoute) {
+        return `La pagina ${route} carga correctamente con un registro de ejemplo y permite validar contexto observable sin errores visibles.`;
+    }
+    return `La pagina ${route} carga correctamente y permite validar al menos un flujo observable sin errores visibles.`;
+}
+
+function analyzeSourceSignals(sourceFile, route) {
+    let raw = '';
+    try {
+        raw = fs.readFileSync(sourceFile, 'utf8');
+    } catch {
+        raw = '';
+    }
+
+    const lower = raw.toLowerCase();
+    const routeLower = String(route || '').toLowerCase();
+    const fileLower = toPosix(sourceFile).toLowerCase();
+    const semanticFileLower = fileLower.replace(/\([^/\\]+\)/g, '');
+    const has = (...patterns) => patterns.some(pattern => lower.includes(pattern));
+    const routeHas = (...patterns) => patterns.some(pattern => routeLower.includes(pattern) || semanticFileLower.includes(pattern));
+    const isRouterConfigFile = has('createbrowserrouter', 'useroutes', '<routes', '<route');
+    const contextualHas = (...patterns) => {
+        if (routeHas(...patterns)) return true;
+        return !isRouterConfigFile && has(...patterns);
+    };
+
+    const signals = {
+        hasForm: has('<form', 'useform', 'formik', 'react-hook-form', 'zodresolver', 'onsubmit', 'handleSubmit'.toLowerCase()),
+        hasTable: has('<table', 'datatable', 'ag-grid', 'tanstack table', 'role="table"', 'role="grid"'),
+        hasSearch: contextualHas('search', 'buscar', 'query', 'placeholder="buscar', 'placeholder=\'buscar'),
+        hasFilter: contextualHas('filter', 'filtro', 'filtrar'),
+        hasCreateAction: contextualHas('crear', 'create', 'nuevo', 'new ', 'agregar', 'add '),
+        hasEditAction: contextualHas('editar', 'edit', 'actualizar', 'update'),
+        hasAuth: has('password', 'contraseña', 'iniciar sesión', 'login', 'sign in') || routeHas('login', 'signin', 'auth'),
+        hasCheckout: contextualHas('payment', 'card', 'checkout', 'billing', 'stripe'),
+        hasSettings: has('settings', 'configuración', 'preferencias', 'preferences') || routeHas('settings', 'config', 'preferences'),
+        hasUpload: contextualHas('type="file"', "type='file'", 'dropzone', 'upload', 'subir archivo', 'subir imagen'),
+        isDynamicRoute: /\[[^\]]+\]/.test(route) || /:\w+/.test(route),
+        routeSegments: routeLower.replace(/^\/+/, '').split('/').filter(Boolean),
+    };
+
+    signals.hasAuth = contextualHas('password', 'login', 'signin', 'sign in', 'auth', 'contrase', 'iniciar sesi');
+    signals.hasSettings = contextualHas('settings', 'preferences', 'preferencias', 'config');
+
+    signals.isDashboardLike = route === '/' || routeHas('dashboard', 'welcome', 'home', 'inicio');
+    signals.isListLike = signals.hasTable || signals.hasSearch || signals.hasFilter || routeHas('list', 'index', 'catalog', 'admin', 'users');
+    signals.isCrudLike = signals.hasCreateAction || signals.hasEditAction || routeHas('create', 'new', 'edit');
+    signals.keywords = Array.from(new Set([
+        ...(signals.hasForm ? ['form'] : []),
+        ...(signals.hasTable ? ['table'] : []),
+        ...(signals.hasSearch ? ['search'] : []),
+        ...(signals.hasFilter ? ['filter'] : []),
+        ...(signals.hasAuth ? ['auth'] : []),
+        ...(signals.hasCheckout ? ['checkout'] : []),
+        ...(signals.hasSettings ? ['settings'] : []),
+        ...(signals.hasUpload ? ['upload'] : []),
+        ...(signals.isDynamicRoute ? ['detail'] : []),
+        ...(signals.isDashboardLike ? ['dashboard'] : []),
+        ...(signals.isCrudLike ? ['crud'] : []),
+    ]));
+
+    return signals;
+}
+
+function buildRouteTags(route, signals) {
+    const topLevel = route === '/' ? 'root' : inferPrimaryRouteTag(route);
+    return Array.from(new Set(['generated', topLevel, ...signals.keywords, ...(signals.isDynamicRoute ? ['dynamic'] : [])]));
+}
+
+function inferPriority(signals) {
+    if (signals.hasCheckout || signals.hasAuth) return 'high';
+    if (signals.hasForm || signals.isCrudLike || signals.isDynamicRoute) return 'normal';
+    return 'normal';
+}
+
+function countRouteDepth(route) {
+    return normalizeRoute(route).split('/').filter(Boolean).length;
+}
+
+function scoreRouterKind(routerKind) {
+    switch (routerKind) {
+    case 'next-app':
+        return 120;
+    case 'next-pages':
+        return 115;
+    case 'react-router-config':
+        return 110;
+    case 'react-router-jsx':
+        return 105;
+    case 'react-router-config-index':
+        return 103;
+    case 'react-router-jsx-index':
+        return 100;
+    case 'react-router':
+        return 90;
+    case 'filesystem-fallback':
+        return 40;
+    case 'spa-root':
+        return 20;
+    default:
+        return 10;
+    }
+}
+
+function scoreCandidate(candidate) {
+    const signals = candidate.signals || {};
+    let score = scoreRouterKind(candidate.routerKind);
+    score += countRouteDepth(candidate.route) * 2;
+    score += (candidate.routeParams || []).length * 6;
+    score += signals.hasCheckout ? 8 : 0;
+    score += signals.hasAuth ? 8 : 0;
+    score += signals.hasForm ? 4 : 0;
+    score += signals.hasTable ? 3 : 0;
+    score += signals.hasSearch ? 2 : 0;
+    score += signals.hasFilter ? 2 : 0;
+    score += signals.isDynamicRoute ? 3 : 0;
+    score += signals.hasSettings ? 2 : 0;
+    score += signals.hasUpload ? 2 : 0;
+    score += signals.isDashboardLike ? 1 : 0;
+    return score;
+}
+
+function compareCandidates(a, b) {
+    const scoreDelta = scoreCandidate(b) - scoreCandidate(a);
+    if (scoreDelta !== 0) return scoreDelta;
+
+    const priorityRank = { high: 3, normal: 2, low: 1 };
+    const priorityDelta = (priorityRank[b.priority] || 0) - (priorityRank[a.priority] || 0);
+    if (priorityDelta !== 0) return priorityDelta;
+
+    const depthDelta = countRouteDepth(b.route) - countRouteDepth(a.route);
+    if (depthDelta !== 0) return depthDelta;
+
+    return a.pagePath.localeCompare(b.pagePath);
+}
+
+function dedupeAndSortCandidates(candidates = []) {
+    const bestByRoute = new Map();
+    for (const candidate of candidates) {
+        const key = normalizeRoute(candidate.route);
+        const current = bestByRoute.get(key);
+        if (!current || compareCandidates(candidate, current) < 0) {
+            bestByRoute.set(key, candidate);
+        }
+    }
+
+    return Array.from(bestByRoute.values()).sort(compareCandidates);
+}
+
+function createCandidate(projectRoot, sourceFile, route, framework, routerKind, projectContext = {}) {
+    const sourcePath = toPosix(path.relative(projectRoot, sourceFile));
+    const normalizedRoute = normalizeRoute(route);
+    const signals = analyzeSourceSignals(sourceFile, normalizedRoute);
+    const routeParams = buildRouteParams(normalizedRoute, projectContext);
+    const routeMeta = {
+        routeParams,
+        isDynamicRoute: routeParams.length > 0,
+        exampleRoute: buildExampleRoute(normalizedRoute, routeParams, projectContext),
+        routeFamily: inferRouteFamily(normalizedRoute)
+    };
+    return {
+        route: normalizedRoute,
+        pagePath: sourcePath,
+        sourcePath,
+        framework,
+        routerKind,
+        signals,
+        routeParams,
+        routeExamplePath: routeMeta.exampleRoute,
+        routeFamily: routeMeta.routeFamily,
+        name: buildMissionName(normalizedRoute),
+        prompt: buildPrompt(normalizedRoute, routeMeta),
+        expectedResult: buildExpectedResult(normalizedRoute, routeMeta),
+        tags: buildRouteTags(normalizedRoute, signals),
+        priority: inferPriority(signals)
+    };
+}
+
+function normalizeNextAppRoute(relativeFile) {
+    const withoutApp = toPosix(relativeFile).replace(/^(src\/)?app\//, '');
+    const withoutPage = withoutApp.replace(/\/page\.(js|jsx|ts|tsx)$/i, '');
+    const segments = withoutPage
+        .split('/')
+        .filter(Boolean)
+        .filter(segment => !/^\(.*\)$/.test(segment))
+        .filter(segment => !/^@/.test(segment));
+    if (segments.length === 0) return '/';
+    return `/${segments.join('/')}`;
+}
+
+function normalizeNextPagesRoute(relativeFile) {
+    const withoutPages = toPosix(relativeFile).replace(/^(src\/)?pages\//, '');
+    const noExt = stripExtension(withoutPages);
+    const normalized = noExt.replace(/\/index$/i, '');
+    if (!normalized) return '/';
+    return `/${normalized}`;
+}
+
+function extractBalancedBlock(text, startIndex, openChar, closeChar) {
+    let depth = 0;
+    let quote = null;
+    for (let i = startIndex; i < text.length; i++) {
+        const char = text[i];
+        const previous = text[i - 1];
+        if (quote) {
+            if (char === quote && previous !== '\\') quote = null;
+            continue;
+        }
+        if (char === '"' || char === '\'' || char === '`') {
+            quote = char;
+            continue;
+        }
+        if (char === openChar) depth += 1;
+        if (char === closeChar) {
+            depth -= 1;
+            if (depth === 0) {
+                return {
+                    content: text.slice(startIndex, i + 1),
+                    endIndex: i
+                };
+            }
+        }
+    }
+    return null;
+}
+
+function findTopLevelPropertyValue(objectLiteral, propertyName, expectedOpenChar) {
+    let depthCurly = 0;
+    let depthSquare = 0;
+    let depthParen = 0;
+    let quote = null;
+    const search = `${propertyName}:`;
+
+    for (let i = 0; i < objectLiteral.length; i++) {
+        const char = objectLiteral[i];
+        const previous = objectLiteral[i - 1];
+
+        if (quote) {
+            if (char === quote && previous !== '\\') quote = null;
+            continue;
+        }
+
+        if (char === '"' || char === '\'' || char === '`') {
+            quote = char;
+            continue;
+        }
+
+        if (char === '{') depthCurly += 1;
+        else if (char === '}') depthCurly -= 1;
+        else if (char === '[') depthSquare += 1;
+        else if (char === ']') depthSquare -= 1;
+        else if (char === '(') depthParen += 1;
+        else if (char === ')') depthParen -= 1;
+
+        if (depthCurly === 1 && depthSquare === 0 && depthParen === 0 && objectLiteral.slice(i, i + search.length) === search) {
+            let valueStart = i + search.length;
+            while (/\s/.test(objectLiteral[valueStart] || '')) valueStart += 1;
+            if (expectedOpenChar) {
+                if (objectLiteral[valueStart] !== expectedOpenChar) return null;
+                const closeChar = expectedOpenChar === '[' ? ']' : expectedOpenChar === '{' ? '}' : expectedOpenChar;
+                const block = extractBalancedBlock(objectLiteral, valueStart, expectedOpenChar, closeChar);
+                return block ? block.content : null;
+            }
+
+            const valueMatch = objectLiteral.slice(valueStart).match(/^(['"`])([^'"`]+)\1/);
+            if (valueMatch) return valueMatch[2];
+
+            const bareMatch = objectLiteral.slice(valueStart).match(/^(true|false|null|\d+)/);
+            return bareMatch ? bareMatch[1] : null;
+        }
+    }
+
+    return null;
+}
+
+function combineRoutes(parentRoute, childRoute, isIndex = false) {
+    const parent = normalizeRoute(parentRoute || '/');
+    const child = String(childRoute || '').trim();
+    if (isIndex || !child) return parent;
+    if (child === '/') return '/';
+    if (child.startsWith('/')) return normalizeRoute(child);
+    if (parent === '/') return normalizeRoute(child);
+    return normalizeRoute(`${parent}/${child}`);
+}
+
+function parseRouteObjectsFromArray(arrayLiteral, parentRoute, pushRoute) {
+    let quote = null;
+    let depthCurly = 0;
+    let depthSquare = 0;
+    let depthParen = 0;
+
+    for (let i = 0; i < arrayLiteral.length; i++) {
+        const char = arrayLiteral[i];
+        const previous = arrayLiteral[i - 1];
+
+        if (quote) {
+            if (char === quote && previous !== '\\') quote = null;
+            continue;
+        }
+
+        if (char === '"' || char === '\'' || char === '`') {
+            quote = char;
+            continue;
+        }
+
+        if (char === '[') {
+            depthSquare += 1;
+            continue;
+        }
+        if (char === ']') {
+            depthSquare -= 1;
+            continue;
+        }
+        if (char === '(') {
+            depthParen += 1;
+            continue;
+        }
+        if (char === ')') {
+            depthParen -= 1;
+            continue;
+        }
+        if (char === '{') {
+            depthCurly += 1;
+            if (depthSquare === 1 && depthCurly === 1 && depthParen === 0) {
+                const block = extractBalancedBlock(arrayLiteral, i, '{', '}');
+                if (block) {
+                    parseRouteObjectLiteral(block.content, parentRoute, pushRoute);
+                    i = block.endIndex;
+                    depthCurly = 0;
+                }
+            }
+            continue;
+        }
+        if (char === '}') {
+            depthCurly -= 1;
+        }
+    }
+}
+
+function parseRouteObjectLiteral(objectLiteral, parentRoute, pushRoute) {
+    const pathValue = findTopLevelPropertyValue(objectLiteral, 'path', null);
+    const indexValue = findTopLevelPropertyValue(objectLiteral, 'index', null);
+    const childrenLiteral = findTopLevelPropertyValue(objectLiteral, 'children', '[');
+    const isIndex = indexValue === 'true';
+    const currentRoute = combineRoutes(parentRoute, pathValue, isIndex);
+
+    if (pathValue && pathValue !== '*') {
+        pushRoute(currentRoute, 'react-router-config');
+    } else if (isIndex) {
+        pushRoute(currentRoute, 'react-router-config-index');
+    }
+
+    if (childrenLiteral) {
+        parseRouteObjectsFromArray(childrenLiteral, currentRoute, pushRoute);
+    }
+}
+
+function extractConfiguredRoutes(raw, pushRoute) {
+    let found = false;
+    const configPatterns = ['createBrowserRouter', 'useRoutes', 'createRoutesFromElements'];
+    for (const pattern of configPatterns) {
+        let searchIndex = 0;
+        while (searchIndex < raw.length) {
+            const start = raw.indexOf(pattern, searchIndex);
+            if (start === -1) break;
+            const arrayStart = raw.indexOf('[', start);
+            if (arrayStart === -1) break;
+            const arrayBlock = extractBalancedBlock(raw, arrayStart, '[', ']');
+            if (arrayBlock) {
+                parseRouteObjectsFromArray(arrayBlock.content, '/', pushRoute);
+                found = true;
+                searchIndex = arrayBlock.endIndex + 1;
+                continue;
+            }
+            searchIndex = start + pattern.length;
+        }
+    }
+    return found;
+}
+
+function parseJsxRouteAttributes(tagText) {
+    const pathMatch = tagText.match(/\bpath\s*=\s*["'`]([^"'`]+)["'`]/);
+    const indexMatch = /\bindex(?:\s*=\s*\{?\s*true\s*\}?)?/.test(tagText);
+    return {
+        path: pathMatch ? pathMatch[1].trim() : null,
+        index: indexMatch
+    };
+}
+
+function extractJsxNestedRoutes(raw, pushRoute) {
+    const routeTagRegex = /<\/?Route\b[^>]*\/?>/g;
+    const stack = [];
+    let found = false;
+
+    for (const match of raw.matchAll(routeTagRegex)) {
+        const tagText = match[0];
+        const isClosing = /^<\//.test(tagText);
+        const isSelfClosing = /\/>$/.test(tagText);
+
+        if (isClosing) {
+            stack.pop();
+            continue;
+        }
+
+        const attrs = parseJsxRouteAttributes(tagText);
+        const parentRoute = stack.length > 0 ? stack[stack.length - 1].route : '/';
+        const currentRoute = combineRoutes(parentRoute, attrs.path, attrs.index);
+
+        if ((attrs.path && attrs.path !== '*') || attrs.index) {
+            pushRoute(currentRoute, attrs.index ? 'react-router-jsx-index' : 'react-router-jsx');
+            found = true;
+        }
+
+        if (!isSelfClosing) {
+            stack.push({
+                route: currentRoute
+            });
+        }
+    }
+
+    return found;
+}
+
+function discoverNextAppRoutes(projectRoot, projectContext = {}) {
+    const appDirs = [
+        path.join(projectRoot, 'app'),
+        path.join(projectRoot, 'src', 'app')
+    ];
+    const candidates = [];
+
+    for (const appDir of appDirs) {
+        if (!fs.existsSync(appDir)) continue;
+        candidates.push(
+            ...walk(appDir)
+                .filter(file => /[\\/]page\.(js|jsx|ts|tsx)$/i.test(file))
+                .map(file => {
+                    const relative = path.relative(projectRoot, file);
+                    return createCandidate(projectRoot, file, normalizeNextAppRoute(relative), 'next', 'next-app', projectContext);
+                })
+        );
+    }
+
+    return dedupeAndSortCandidates(candidates);
+}
+
+function discoverNextPagesRoutes(projectRoot, projectContext = {}) {
+    const pagesDirs = [
+        path.join(projectRoot, 'pages'),
+        path.join(projectRoot, 'src', 'pages')
+    ];
+    const candidates = [];
+
+    for (const pagesDir of pagesDirs) {
+        if (!fs.existsSync(pagesDir)) continue;
+        candidates.push(
+            ...walk(pagesDir)
+                .filter(file => PAGE_FILE_RE.test(file))
+                .filter(file => !/[\\/]pages[\\/](api)([\\/]|$)/i.test(file))
+                .filter(file => !/[\\/]_(app|document|error)\.(js|jsx|ts|tsx)$/i.test(file))
+                .map(file => {
+                    const relative = path.relative(projectRoot, file);
+                    return createCandidate(projectRoot, file, normalizeNextPagesRoute(relative), 'next', 'next-pages', projectContext);
+                })
+        );
+    }
+
+    return dedupeAndSortCandidates(candidates);
+}
+
+function findReactRouterPaths(projectRoot, projectContext = {}) {
+    const srcDir = path.join(projectRoot, 'src');
+    if (!fs.existsSync(srcDir)) return [];
+    const files = walk(srcDir).filter(file => PAGE_FILE_RE.test(file));
+    const routes = new Map();
+    const pushRoute = (route, file, routerKind = 'react-router') => {
+        const normalizedRoute = route === '' ? '/' : normalizeRoute(route);
+        if (!routes.has(normalizedRoute)) {
+            routes.set(normalizedRoute, createCandidate(projectRoot, file, normalizedRoute, 'vite', routerKind, projectContext));
+        }
+    };
+
+    for (const file of files) {
+        const raw = fs.readFileSync(file, 'utf8');
+        const hasConfiguredRoutes = extractConfiguredRoutes(raw, (route, routerKind) => pushRoute(route, file, routerKind));
+        const hasNestedJsxRoutes = extractJsxNestedRoutes(raw, (route, routerKind) => pushRoute(route, file, routerKind));
+        const routeRegexes = [
+            ...(!hasNestedJsxRoutes ? [/<Route\b[^>]*\bpath=["'`]([^"'`]+)["'`]/g] : []),
+            ...(!hasConfiguredRoutes ? [/\bpath\s*:\s*["'`]([^"'`]+)["'`]/g] : [])
+        ];
+        for (const regex of routeRegexes) {
+            for (const match of raw.matchAll(regex)) {
+                const route = match[1]?.trim();
+                if (!route || route === '*') continue;
+                pushRoute(route.startsWith('/') ? route : `/${route}`, file);
+            }
+        }
+    }
+
+    if (routes.size > 0) return dedupeAndSortCandidates(Array.from(routes.values()));
+
+    const fallbackDirs = [
+        path.join(srcDir, 'pages'),
+        path.join(srcDir, 'views')
+    ];
+    for (const dir of fallbackDirs) {
+        if (!fs.existsSync(dir)) continue;
+        const candidates = walk(dir)
+            .filter(file => PAGE_FILE_RE.test(file))
+            .map(file => {
+                const relative = toPosix(path.relative(srcDir, file));
+                const route = `/${stripExtension(relative).replace(/^(pages|views)\//, '').replace(/\/index$/i, '')}`.replace(/\/+/g, '/');
+                return createCandidate(projectRoot, file, route === '/' ? '/' : route, 'vite', 'filesystem-fallback', projectContext);
+            });
+        if (candidates.length > 0) return dedupeAndSortCandidates(candidates);
+    }
+
+    const appLikeFiles = files.filter(file => /[\\/]src[\\/](App|main|index)\.(js|jsx|ts|tsx)$/i.test(file));
+    if (appLikeFiles.length > 0) {
+        return dedupeAndSortCandidates([createCandidate(projectRoot, appLikeFiles[0], '/', 'vite', 'spa-root', projectContext)]);
+    }
+
+    return [];
+}
+
+export function discoverProjectRoutes(projectRoot, framework = 'unknown', projectContext = {}) {
+    if (framework === 'next') {
+        const appRoutes = discoverNextAppRoutes(projectRoot, projectContext);
+        if (appRoutes.length > 0) return appRoutes;
+        return discoverNextPagesRoutes(projectRoot, projectContext);
+    }
+
+    if (framework === 'vite' || framework === 'cra') {
+        return findReactRouterPaths(projectRoot, projectContext);
+    }
+
+    const nextApp = discoverNextAppRoutes(projectRoot, projectContext);
+    if (nextApp.length > 0) return nextApp;
+
+    const nextPages = discoverNextPagesRoutes(projectRoot, projectContext);
+    if (nextPages.length > 0) return nextPages;
+
+    return findReactRouterPaths(projectRoot, projectContext);
+}