@rangojs/router 0.0.0-experimental.7 → 0.0.0-experimental.70

package/src/build/generate-manifest.ts

@@ -14,6 +14,8 @@ import { extractStaticPrefix } from "../router/pattern-matching.js";
 import { RSCRouterContext, runWithPrefixes } from "../server/context.js";
 import type { EntryData, TrackedInclude } from "../server/context.js";
 import type { TrailingSlashMode } from "../types.js";
+import { createRouteHelpers } from "../route-definition.js";
+import MapRootLayout from "../server/root-layout.js";
 
 /**
  * Node in the prefix tree
@@ -39,8 +41,16 @@ export interface GeneratedManifest {
   prefixTree: Record<string, PrefixTreeNode>;
   /** Complete route name → pattern mapping for href() */
   routeManifest: Record<string, string>;
-  /** Generation timestamp */
-  generatedAt: string;
+  /** Route name → trailing slash mode for trie redirect handling */
+  routeTrailingSlash?: Record<string, string>;
+  /** Route names using Prerender (for dev-mode Node.js delegation) */
+  prerenderRoutes?: string[];
+  /** Route names wrapped with Passthrough() (live handler for runtime fallback) */
+  passthroughRoutes?: string[];
+  /** Route name → response type for non-RSC routes */
+  responseTypeRoutes?: Record<string, string>;
+  /** Route name -> search schema descriptor for typed URL helpers */
+  routeSearchSchemas?: Record<string, Record<string, string>>;
 }
 
 /**
@@ -52,11 +62,19 @@ function buildPrefixTreeNode(
   namePrefix: string | undefined,
   patterns: UrlPatterns<any>,
   routeManifest: Record<string, string>,
-  visited: Set<unknown> = new Set()
+  routeAncestry: Record<string, string[]>, // internal: feeds trie building, not exported
+  mountIndex: number,
+  visited: Set<unknown> = new Set(),
+  routeTrailingSlash?: Record<string, string>,
+  prerenderRoutes?: string[],
+  prerenderDefs?: Record<string, any>,
+  passthroughRoutes?: string[],
+  responseTypeRoutes?: Record<string, string>,
+  routeSearchSchemas?: Record<string, Record<string, string>>,
 ): PrefixTreeNode {
   if (visited.has(patterns)) {
     console.warn(
-      `[@rangojs/router] Circular include detected at prefix "${urlPrefix}". Skipping.`
+      `[@rangojs/router] Circular include detected at prefix "${urlPrefix}". Skipping.`,
     );
     return {
       staticPrefix: extractStaticPrefix(urlPrefix),
@@ -72,6 +90,7 @@ function buildPrefixTreeNode(
   const patternsMap = new Map<string, string>();
   const patternsByPrefix = new Map<string, Map<string, string>>();
   const trailingSlashMap = new Map<string, TrailingSlashMode>();
+  const searchSchemasMap = new Map<string, Record<string, string>>();
   const trackedIncludes: TrackedInclude[] = [];
 
   RSCRouterContext.run(
@@ -80,17 +99,25 @@ function buildPrefixTreeNode(
       patterns: patternsMap,
       patternsByPrefix,
       trailingSlash: trailingSlashMap,
+      searchSchemas: searchSchemasMap,
       namespace: "build",
       parent: null,
       counters: {},
+      mountIndex,
       trackedIncludes, // Enable nested include tracking
     },
     () => {
-      // Run patterns with the URL and name prefixes
-      runWithPrefixes(urlPrefix, namePrefix, () => {
+      const helpers = createRouteHelpers();
+      // Wrap in root layout for correct parent hierarchy (matches runtime)
+      helpers.layout(MapRootLayout, () => {
+        if (urlPrefix || namePrefix) {
+          return runWithPrefixes(urlPrefix, namePrefix, () => {
+            return patterns.handler() as AllUseItems[];
+          });
+        }
         return patterns.handler() as AllUseItems[];
       });
-    }
+    },
   );
 
   // Collect route names defined in this include (routes have prefixes applied)
@@ -100,7 +127,48 @@ function buildPrefixTreeNode(
     routeManifest[name] = pattern;
   }
 
-  // Build children from tracked nested includes
+  // Collect trailing slash config
+  if (routeTrailingSlash) {
+    for (const [name, mode] of trailingSlashMap.entries()) {
+      routeTrailingSlash[name] = mode;
+    }
+  }
+  if (routeSearchSchemas) {
+    for (const [name, schema] of searchSchemasMap.entries()) {
+      routeSearchSchemas[name] = schema;
+    }
+  }
+
+  // Capture ancestry from manifest entries' parent chains
+  captureAncestry(manifest, routeAncestry);
+
+  // Collect prerender route names and handler definitions from manifest entries
+  if (prerenderRoutes) {
+    for (const [name, entry] of manifest) {
+      if (entry.type === "route" && entry.isPrerender) {
+        prerenderRoutes.push(name);
+        if (prerenderDefs && entry.prerenderDef) {
+          prerenderDefs[name] = entry.prerenderDef;
+        }
+        if (passthroughRoutes && entry.isPassthrough === true) {
+          passthroughRoutes.push(name);
+        }
+      }
+    }
+  }
+
+  // Collect response type routes from manifest entries
+  if (responseTypeRoutes) {
+    for (const [name, entry] of manifest) {
+      if (entry.type === "route" && entry.responseType) {
+        responseTypeRoutes[name] = entry.responseType;
+      }
+    }
+  }
+
+  // Build children from tracked nested includes.
+  // Multiple includes can share the same fullPrefix (e.g., include("/", patternsA),
+  // include("/", patternsB)). Merge their routes instead of overwriting.
   const children: Record<string, PrefixTreeNode> = {};
 
   for (const include of trackedIncludes) {
@@ -109,12 +177,31 @@ function buildPrefixTreeNode(
       include.namePrefix,
       include.patterns as UrlPatterns<any>,
       routeManifest,
-      visited
+      routeAncestry,
+      mountIndex,
+      visited,
+      routeTrailingSlash,
+      prerenderRoutes,
+      prerenderDefs,
+      passthroughRoutes,
+      responseTypeRoutes,
+      routeSearchSchemas,
     );
 
-    children[include.fullPrefix] = childNode;
+    const existing = children[include.fullPrefix];
+    if (existing) {
+      existing.routes.push(...childNode.routes);
+      Object.assign(existing.children, childNode.children);
+    } else {
+      children[include.fullPrefix] = childNode;
+    }
   }
 
+  // Remove from visited so sibling branches can reuse the same patterns
+  // without false circular-include detection. Only ancestors in the current
+  // recursion path should trigger the cycle guard.
+  visited.delete(patterns);
+
   return {
     staticPrefix: extractStaticPrefix(urlPrefix),
     fullPrefix: urlPrefix,
@@ -125,11 +212,40 @@ function buildPrefixTreeNode(
 }
 
 /**
- * Generate manifest from UrlPatterns
+ * Walk parent chains of route entries to extract ancestry shortCodes.
+ */
+function captureAncestry(
+  manifest: Map<string, EntryData>,
+  routeAncestry: Record<string, string[]>,
+): void {
+  for (const [routeName, entry] of manifest) {
+    if (entry.type === "route") {
+      const ancestry: string[] = [];
+      let current: EntryData | null = entry;
+      while (current) {
+        ancestry.unshift(current.shortCode);
+        current = current.parent;
+      }
+      routeAncestry[routeName] = ancestry;
+    }
+  }
+}
+
+/**
+ * Internal manifest result including build-pipeline-only fields.
+ * Not part of the public API — use generateManifest() for the public surface.
+ */
+export interface FullManifest extends GeneratedManifest {
+  _routeAncestry: Record<string, string[]>;
+  _prerenderDefs?: Record<string, any>;
+}
+
+/**
+ * Generate manifest from UrlPatterns (public API).
  *
- * This runs all patterns (including lazy ones) at build time to extract:
- * - The complete prefix tree for short-circuit optimization
- * - The complete route manifest for href()
+ * Returns only the public GeneratedManifest fields. Internal build pipeline
+ * consumers that need _routeAncestry or _prerenderDefs should use
+ * generateManifestFull() instead.
  *
  * @example
  * ```typescript
@@ -145,9 +261,31 @@ function buildPrefixTreeNode(
  * ```
  */
 export function generateManifest<TEnv>(
-  urlpatterns: UrlPatterns<TEnv, any>
+  urlpatterns: UrlPatterns<TEnv, any>,
+  mountIndex: number = 0,
 ): GeneratedManifest {
+  const {
+    _routeAncestry: _,
+    _prerenderDefs: __,
+    ...publicManifest
+  } = generateManifestFull(urlpatterns, mountIndex);
+  return publicManifest;
+}
+
+/**
+ * Generate manifest with internal build-pipeline fields.
+ *
+ * Used by the Vite plugin (discover-routers via dynamic import through
+ * @rangojs/router/build), manifest-init (direct import), and trie
+ * building. Not intended for external use.
+ */
+export function generateManifestFull<TEnv>(
+  urlpatterns: UrlPatterns<TEnv, any>,
+  mountIndex: number = 0,
+  options?: { urlPrefix?: string },
+): FullManifest {
   const routeManifest: Record<string, string> = {};
+  const routeAncestry: Record<string, string[]> = {};
   const prefixTree: Record<string, PrefixTreeNode> = {};
 
   // Run the root patterns handler with tracking enabled
@@ -155,6 +293,7 @@ export function generateManifest<TEnv>(
   const patternsMap = new Map<string, string>();
   const patternsByPrefix = new Map<string, Map<string, string>>();
   const trailingSlashMap = new Map<string, TrailingSlashMode>();
+  const searchSchemasMap = new Map<string, Record<string, string>>();
   const trackedIncludes: TrackedInclude[] = [];
 
   RSCRouterContext.run(
@@ -163,22 +302,63 @@ export function generateManifest<TEnv>(
       patterns: patternsMap,
       patternsByPrefix,
       trailingSlash: trailingSlashMap,
+      searchSchemas: searchSchemasMap,
       namespace: "build",
       parent: null,
       counters: {},
+      mountIndex,
       trackedIncludes, // Enable include tracking
+      // basename sets the initial URL prefix for all path() registrations
+      ...(options?.urlPrefix ? { urlPrefix: options.urlPrefix } : {}),
     },
     () => {
-      urlpatterns.handler();
-    }
+      const helpers = createRouteHelpers();
+      // Wrap in root layout for correct parent hierarchy (matches runtime)
+      helpers.layout(MapRootLayout, () => {
+        return urlpatterns.handler() as AllUseItems[];
+      });
+    },
   );
 
-  // Collect root-level routes
+  // Collect root-level routes and trailing slash config
+  const routeTrailingSlash: Record<string, string> = {};
   for (const [name, pattern] of patternsMap.entries()) {
     routeManifest[name] = pattern;
   }
+  for (const [name, mode] of trailingSlashMap.entries()) {
+    routeTrailingSlash[name] = mode;
+  }
+  const routeSearchSchemas: Record<string, Record<string, string>> = {};
+  for (const [name, schema] of searchSchemasMap.entries()) {
+    routeSearchSchemas[name] = schema;
+  }
+
+  // Capture ancestry from manifest entries' parent chains
+  captureAncestry(manifest, routeAncestry);
+
+  // Collect prerender route names and handler definitions across all levels
+  const prerenderRoutes: string[] = [];
+  const prerenderDefs: Record<string, any> = {};
+  const passthroughRoutes: string[] = [];
+  const responseTypeRoutes: Record<string, string> = {};
+  for (const [name, entry] of manifest) {
+    if (entry.type === "route" && entry.isPrerender) {
+      prerenderRoutes.push(name);
+      if (entry.prerenderDef) {
+        prerenderDefs[name] = entry.prerenderDef;
+      }
+      if (entry.isPassthrough === true) {
+        passthroughRoutes.push(name);
+      }
+    }
+    if (entry.type === "route" && entry.responseType) {
+      responseTypeRoutes[name] = entry.responseType;
+    }
+  }
 
-  // Build prefix tree from tracked includes (shared visited set for cycle detection)
+  // Build prefix tree from tracked includes (shared visited set for cycle detection).
+  // Multiple includes can share the same fullPrefix (e.g., include("/", patternsA),
+  // include("/", patternsB)). Merge their routes instead of overwriting.
   const visited = new Set<unknown>();
   for (const include of trackedIncludes) {
     const node = buildPrefixTreeNode(
@@ -186,16 +366,48 @@ export function generateManifest<TEnv>(
       include.namePrefix,
       include.patterns as UrlPatterns<any>,
       routeManifest,
-      visited
+      routeAncestry,
+      mountIndex,
+      visited,
+      routeTrailingSlash,
+      prerenderRoutes,
+      prerenderDefs,
+      passthroughRoutes,
+      responseTypeRoutes,
+      routeSearchSchemas,
     );
 
-    prefixTree[include.fullPrefix] = node;
+    const existing = prefixTree[include.fullPrefix];
+    if (existing) {
+      existing.routes.push(...node.routes);
+      Object.assign(existing.children, node.children);
+    } else {
+      prefixTree[include.fullPrefix] = node;
+    }
   }
 
   return {
     prefixTree,
     routeManifest,
-    generatedAt: new Date().toISOString(),
+    routeTrailingSlash:
+      Object.keys(routeTrailingSlash).length > 0
+        ? routeTrailingSlash
+        : undefined,
+    prerenderRoutes: prerenderRoutes.length > 0 ? prerenderRoutes : undefined,
+    passthroughRoutes:
+      passthroughRoutes.length > 0 ? passthroughRoutes : undefined,
+    responseTypeRoutes:
+      Object.keys(responseTypeRoutes).length > 0
+        ? responseTypeRoutes
+        : undefined,
+    routeSearchSchemas:
+      Object.keys(routeSearchSchemas).length > 0
+        ? routeSearchSchemas
+        : undefined,
+    _routeAncestry: routeAncestry,
+    // Internal: prerender handler definitions for build-time getParams() access
+    _prerenderDefs:
+      Object.keys(prerenderDefs).length > 0 ? prerenderDefs : undefined,
   };
 }
 
@@ -209,13 +421,12 @@ export function generateManifest<TEnv>(
  * ```
  */
 export function generateManifestCode<TEnv>(
-  urlpatterns: UrlPatterns<TEnv, any>
+  urlpatterns: UrlPatterns<TEnv, any>,
 ): string {
   const manifest = generateManifest(urlpatterns);
 
   return `/**
  * Auto-generated route manifest
- * Generated at: ${manifest.generatedAt}
  *
  * DO NOT EDIT - This file is generated by @rangojs/router
  */

package/src/build/generate-route-types.ts

@@ -0,0 +1,39 @@
+// Barrel re-export -- see route-types/ for implementations.
+export {
+  extractParamsFromPattern,
+  formatRouteEntry,
+} from "./route-types/param-extraction.js";
+export { extractRoutesFromSource } from "./route-types/ast-route-extraction.js";
+export {
+  generatePerModuleTypesSource,
+  generateRouteTypesSource,
+} from "./route-types/codegen.js";
+export {
+  DEFAULT_EXCLUDE_PATTERNS,
+  type ScanFilter,
+  createScanFilter,
+  findTsFiles,
+} from "./route-types/scan-filter.js";
+export {
+  writePerModuleRouteTypes,
+  writePerModuleRouteTypesForFile,
+} from "./route-types/per-module-writer.js";
+export {
+  type UnresolvableReason,
+  type UnresolvableInclude,
+  extractIncludesWithDiagnostics,
+} from "./route-types/include-resolution.js";
+export {
+  extractUrlsVariableFromRouter,
+  extractUrlsFromRouter,
+  extractBasenameFromRouter,
+  type UrlsExtractionResult,
+  buildCombinedRouteMapForRouterFile,
+  detectUnresolvableIncludes,
+  detectUnresolvableIncludesForUrlsFile,
+  findNestedRouterConflict,
+  formatNestedRouterConflictError,
+  findRouterFiles,
+  writeCombinedRouteTypes,
+} from "./route-types/router-processing.js";
+export { findUrlsVariableNames } from "./route-types/per-module-writer.js";

package/src/build/index.ts

@@ -17,6 +17,19 @@
 
 export {
   generateManifest,
+  generateManifestFull,
   generateManifestCode,
   type GeneratedManifest,
 } from "./generate-manifest.js";
+
+export { buildRouteTrie, type TrieNode, type TrieLeaf } from "./route-trie.js";
+
+export {
+  writePerModuleRouteTypes,
+  extractRoutesFromSource,
+  generatePerModuleTypesSource,
+  createScanFilter,
+  type ScanFilter,
+} from "./generate-route-types.js";
+
+export { hashParams } from "../prerender/param-hash.js";