@useavalon/avalon 0.1.0

package/src/nitro/route-discovery.ts

@@ -0,0 +1,439 @@
+/**
+ * Route Discovery Module for Nitro
+ *
+ * This module provides minimal route discovery for Avalon's SSR pages.
+ * 
+ * IMPORTANT: This module is simplified to complement Nitro's native routing:
+ * - API routes: Handled by Nitro's auto-discovery from `api/` directory
+ * - Page routes: Discovered here for SSR rendering (pages are components, not h3 handlers)
+ * - Middleware: Handled by Nitro's auto-discovery from `middleware/` directory
+ *
+ * The page discovery is needed because Avalon pages are React/Vue/Svelte components
+ * that require SSR rendering, which is different from Nitro's h3 route handlers.
+ *
+ * @module nitro/route-discovery
+ */
+
+import { stat } from "node:fs/promises";
+import { basename, dirname, relative } from "node:path";
+import { walk } from "../utils/fs.ts";
+import type { DiscoveredRoute } from "./types.ts";
+
+/**
+ * Supported page file extensions
+ */
+export const PAGE_EXTENSIONS = [
+  ".tsx",
+  ".ts",
+  ".jsx",
+  ".js",
+  ".vue",
+  ".svelte",
+  ".md",
+  ".mdx",
+];
+
+/**
+ * Options for page route discovery
+ */
+export interface PageDiscoveryOptions {
+  /** Pages directory path (absolute or relative to project root) */
+  pagesDir: string;
+  /** Enable development mode logging */
+  developmentMode?: boolean;
+  /** Directories to exclude from scanning */
+  excludeDirectories?: string[];
+}
+
+/**
+ * Result of file path to pattern conversion
+ */
+export interface FilePathPatternResult {
+  /** Route pattern (e.g., /users/:id) */
+  pattern: string;
+  /** Extracted parameter names */
+  params: string[];
+}
+
+/**
+ * Discovers page routes from multiple directories with route prefixes
+ * 
+ * This supports modular architecture where pages can be in different modules,
+ * each with their own route prefix.
+ *
+ * @param pageDirs - Array of page directories with their route prefixes
+ * @param options - Discovery options
+ * @returns Array of discovered page routes
+ */
+export async function discoverPageRoutesFromMultipleDirs(
+  pageDirs: Array<{ dir: string; prefix: string }>,
+  options?: Pick<PageDiscoveryOptions, "developmentMode" | "excludeDirectories">
+): Promise<DiscoveredRoute[]> {
+  const allRoutes: DiscoveredRoute[] = [];
+
+  for (const { dir, prefix } of pageDirs) {
+    const routes = await discoverPageRoutes(dir, options);
+    
+    // Apply prefix to routes (except for root prefix '/')
+    for (const route of routes) {
+      if (prefix !== '/') {
+        // Combine prefix with pattern
+        // /prefix + /path -> /prefix/path
+        // /prefix + / -> /prefix
+        const combinedPattern = route.pattern === '/' 
+          ? prefix 
+          : prefix + route.pattern;
+        route.pattern = combinedPattern;
+      }
+      allRoutes.push(route);
+    }
+  }
+
+  // Sort all routes by specificity
+  return sortRoutesBySpecificity(allRoutes);
+}
+
+/**
+ * Discovers page routes from the pages directory for SSR rendering
+ *
+ * NOTE: This is specifically for page components that need SSR rendering.
+ * API routes should be placed in the `api/` directory and are auto-discovered
+ * by Nitro's native file-system routing.
+ *
+ * @param pagesDir - Path to the pages directory
+ * @param options - Discovery options
+ * @returns Array of discovered page routes
+ *
+ * @example
+ * ```ts
+ * const routes = await discoverPageRoutes('src/pages', {
+ *   developmentMode: true,
+ * });
+ * ```
+ */
+export async function discoverPageRoutes(
+  pagesDir: string,
+  options?: Pick<PageDiscoveryOptions, "developmentMode" | "excludeDirectories">
+): Promise<DiscoveredRoute[]> {
+  const routes: DiscoveredRoute[] = [];
+  const excludeDirs = options?.excludeDirectories ?? ["node_modules", ".git"];
+
+  try {
+    // Check if directory exists
+    const statResult = await stat(pagesDir);
+    if (!statResult.isDirectory()) {
+      if (options?.developmentMode) {
+        console.warn(
+          `[route-discovery] Pages path is not a directory: ${pagesDir}`
+        );
+      }
+      return [];
+    }
+  } catch (error) {
+    if (error instanceof Error && (error as NodeJS.ErrnoException).code === 'ENOENT') {
+      if (options?.developmentMode) {
+        console.warn(
+          `[route-discovery] Pages directory not found: ${pagesDir}`
+        );
+      }
+      return [];
+    }
+    throw error;
+  }
+
+  // Walk through the pages directory
+  const extensions = PAGE_EXTENSIONS.map((e) => e.slice(1)); // Remove leading dot
+
+  for await (
+    const entry of walk(pagesDir, {
+      includeDirs: false,
+      includeSymlinks: false,
+      exts: extensions,
+    })
+  ) {
+    if (!entry.isFile) continue;
+
+    const relativePath = relative(pagesDir, entry.path);
+
+    // Skip files in excluded directories
+    if (excludeDirs.some((dir) => relativePath.includes(dir))) {
+      continue;
+    }
+
+    // Skip private files (in folders starting with _)
+    if (isPrivateFile(relativePath)) {
+      continue;
+    }
+
+    // Convert file path to route pattern
+    const { pattern, params } = filePathToPattern(relativePath);
+
+    routes.push({
+      type: "page",
+      filePath: entry.path,
+      pattern,
+      params,
+    });
+  }
+
+  // Sort routes by specificity (more specific routes first)
+  return sortRoutesBySpecificity(routes);
+}
+
+/**
+ * Converts a file path to a route pattern
+ *
+ * Handles:
+ * - Index files (index.tsx -> /)
+ * - Dynamic segments ([param] -> :param)
+ * - Catch-all segments ([...slug] -> **)
+ * - Route groups ((group) -> removed from path)
+ *
+ * @param filePath - Relative file path from pages directory
+ * @returns Pattern and extracted parameter names
+ *
+ * @example
+ * ```ts
+ * filePathToPattern('users/[id].tsx')
+ * // { pattern: '/users/:id', params: ['id'] }
+ *
+ * filePathToPattern('blog/[...slug].tsx')
+ * // { pattern: '/blog/**', params: ['slug'] }
+ * ```
+ */
+export function filePathToPattern(filePath: string): FilePathPatternResult {
+  const params: string[] = [];
+
+  let pattern = filePath
+    // Normalize path separators
+    .replace(/\\/g, "/")
+    // Remove file extension
+    .replace(/\.(tsx|ts|jsx|js|vue|svelte|md|mdx)$/, "")
+    // Remove route groups (parentheses)
+    .replace(/\([^)]+\)\//g, "")
+    .replace(/\([^)]+\)$/, "");
+
+  // Handle index files
+  if (basename(pattern) === "index") {
+    pattern = dirname(pattern);
+    if (pattern === ".") {
+      pattern = "";
+    }
+  }
+
+  // Convert dynamic segments [param] to :param
+  // Convert catch-all segments [...slug] to **
+  pattern = pattern.replace(/\[([^\]]+)\]/g, (_, param) => {
+    if (param.startsWith("...")) {
+      // Catch-all segment
+      const paramName = param.slice(3);
+      params.push(paramName);
+      return "**";
+    } else {
+      // Dynamic segment
+      params.push(param);
+      return `:${param}`;
+    }
+  });
+
+  // Ensure leading slash
+  if (!pattern.startsWith("/")) {
+    pattern = "/" + pattern;
+  }
+
+  // Handle root path
+  if (pattern === "/" || pattern === "") {
+    pattern = "/";
+  }
+
+  // Remove trailing slash (except for root)
+  if (pattern.length > 1 && pattern.endsWith("/")) {
+    pattern = pattern.slice(0, -1);
+  }
+
+  return { pattern, params };
+}
+
+/**
+ * Checks if a file is in a private folder (starts with _)
+ *
+ * @param relativePath - Relative file path
+ * @returns True if the file is private
+ */
+export function isPrivateFile(relativePath: string): boolean {
+  const pathParts = relativePath.split(/[/\\]/);
+  return pathParts.some((part) => part.startsWith("_"));
+}
+
+/**
+ * Calculates route specificity score for sorting
+ * Lower score = more specific = higher priority
+ *
+ * @param route - Discovered route
+ * @returns Specificity score
+ */
+export function calculateRouteSpecificity(route: DiscoveredRoute): number {
+  const segments = route.pattern.split("/").filter((s) => s.length > 0);
+  let score = 0;
+
+  for (const segment of segments) {
+    if (segment === "**") {
+      // Catch-all has lowest priority
+      score += 1000;
+    } else if (segment.startsWith(":")) {
+      // Dynamic segment has medium priority
+      score += 100;
+    } else {
+      // Static segment has highest priority
+      score += 1;
+    }
+  }
+
+  // Shorter paths are more specific (for same type of segments)
+  score += segments.length;
+
+  return score;
+}
+
+/**
+ * Sorts routes by specificity (most specific first)
+ *
+ * @param routes - Array of discovered routes
+ * @returns Sorted array of routes
+ */
+export function sortRoutesBySpecificity(
+  routes: DiscoveredRoute[]
+): DiscoveredRoute[] {
+  return [...routes].sort((a, b) => {
+    const scoreA = calculateRouteSpecificity(a);
+    const scoreB = calculateRouteSpecificity(b);
+    return scoreA - scoreB;
+  });
+}
+
+/**
+ * Validates a route pattern for correctness
+ *
+ * @param pattern - Route pattern to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+export function validateRoutePattern(pattern: string): string[] {
+  const errors: string[] = [];
+
+  // Check for leading slash
+  if (!pattern.startsWith("/")) {
+    errors.push("Route pattern must start with /");
+  }
+
+  // Check for malformed dynamic segments
+  const malformedSegments = pattern.match(/\[[^\]]*$/g);
+  if (malformedSegments) {
+    errors.push(
+      `Malformed dynamic segments: ${malformedSegments.join(", ")}. Dynamic segments must be properly closed with ]`
+    );
+  }
+
+  // Check for empty dynamic segments
+  const emptySegments = pattern.match(/\[\]/g);
+  if (emptySegments) {
+    errors.push(
+      "Empty dynamic segments [] are not allowed. Use [param] for dynamic segments or [...rest] for catch-all"
+    );
+  }
+
+  // Check for nested dynamic segments
+  const nestedSegments = pattern.match(/\[[^\]]*\[[^\]]*\]/g);
+  if (nestedSegments) {
+    errors.push(
+      `Nested dynamic segments are not supported: ${nestedSegments.join(", ")}`
+    );
+  }
+
+  return errors;
+}
+
+/**
+ * Extracts parameter names from a route pattern
+ *
+ * @param pattern - Route pattern (e.g., /users/:id/posts/:postId)
+ * @returns Array of parameter names
+ */
+export function extractParamsFromPattern(pattern: string): string[] {
+  const params: string[] = [];
+
+  // Match :param patterns
+  const dynamicMatches = pattern.matchAll(/:([^/]+)/g);
+  for (const match of dynamicMatches) {
+    params.push(match[1]);
+  }
+
+  // Match ** catch-all (represented as unnamed param)
+  if (pattern.includes("**")) {
+    params.push("slug");
+  }
+
+  return params;
+}
+
+/**
+ * Checks if a route pattern matches a given URL path
+ *
+ * @param pattern - Route pattern
+ * @param path - URL path to match
+ * @returns True if the pattern matches the path
+ */
+export function matchRoutePattern(
+  pattern: string,
+  path: string
+): { matches: boolean; params: Record<string, string> } {
+  const params: Record<string, string> = {};
+
+  // Normalize paths
+  const normalizedPattern = pattern.replace(/\/$/, "") || "/";
+  const normalizedPath = path.replace(/\/$/, "") || "/";
+
+  const patternSegments = normalizedPattern.split("/").filter((s) => s);
+  const pathSegments = normalizedPath.split("/").filter((s) => s);
+
+  let patternIndex = 0;
+  let pathIndex = 0;
+
+  while (patternIndex < patternSegments.length) {
+    const patternSegment = patternSegments[patternIndex];
+
+    if (patternSegment === "**") {
+      // Catch-all: match remaining path segments
+      const remainingPath = pathSegments.slice(pathIndex).join("/");
+      params["slug"] = remainingPath;
+      return { matches: true, params };
+    }
+
+    if (pathIndex >= pathSegments.length) {
+      // No more path segments but pattern has more
+      return { matches: false, params: {} };
+    }
+
+    const pathSegment = pathSegments[pathIndex];
+
+    if (patternSegment.startsWith(":")) {
+      // Dynamic segment: extract param value
+      const paramName = patternSegment.slice(1);
+      params[paramName] = pathSegment;
+    } else if (patternSegment !== pathSegment) {
+      // Static segment: must match exactly
+      return { matches: false, params: {} };
+    }
+
+    patternIndex++;
+    pathIndex++;
+  }
+
+  // Check if all path segments were consumed
+  if (pathIndex < pathSegments.length) {
+    return { matches: false, params: {} };
+  }
+
+  return { matches: true, params };
+}
+
+