@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.121

package/src/__augment-tests__/augment.ts

@@ -0,0 +1,81 @@
+/**
+ * Simulates a consumer augmenting the Rango global namespace, the way a real
+ * app does in router.tsx (Env/Vars) and via the generated router.named-routes.gen.ts
+ * (GeneratedRouteMap).
+ *
+ * This file is compiled ONLY by tsconfig.augment-check.json and is excluded from
+ * the main program, so the global augmentation here does not leak into the rest
+ * of the type tests, which assert the UNAUGMENTED fallbacks
+ * (see src/__tests__/augmentation-fallback-types.test.ts).
+ */
+
+export interface TestBindings {
+  DB: { query: (sql: string) => string };
+  SECRET: string;
+}
+
+export interface TestVars {
+  user?: { id: string; role: "admin" | "user" };
+  requestId?: string;
+}
+
+/**
+ * A userland domain type that controls its own JSON wire shape via `toJSON()`.
+ * This is the augmentation hook: `Rango.JsonSerialize` honors `toJSON()`, so a
+ * consumer adjusts how their type serializes with no registry API.
+ */
+export class Money {
+  constructor(public cents: number) {}
+  toJSON(): number {
+    return this.cents;
+  }
+}
+
+/**
+ * Mirrors `typeof router.routeMap`: the same routes as the generated map, plus a
+ * response route whose payload carries a userland class (`Money`, with
+ * `toJSON()`) and a `Date` — used to assert `Rango.PathResponse` reports the
+ * serialized JSON wire shape.
+ */
+export interface TestRegisteredRoutes {
+  readonly home: "/";
+  readonly "blog.post": "/blog/:slug";
+  readonly search: {
+    readonly path: "/search";
+    readonly search: { readonly q: "string"; readonly page: "number?" };
+  };
+  readonly order: {
+    readonly path: "/orders/:id";
+    readonly response: { id: string; total: Money; placedAt: Date };
+  };
+}
+
+declare global {
+  namespace Rango {
+    interface Env extends TestBindings {}
+    interface Vars extends TestVars {}
+    interface RegisteredRoutes extends TestRegisteredRoutes {}
+    // Mirrors the shape emitted into router.named-routes.gen.ts: plain string
+    // patterns, plus { path, search } objects for routes with a search schema.
+    interface GeneratedRouteMap {
+      readonly home: "/";
+      readonly "blog.post": "/blog/:slug";
+      readonly search: {
+        readonly path: "/search";
+        readonly search: { readonly q: "string"; readonly page: "number?" };
+      };
+    }
+
+    // Userland serialization overrides: full-transform replacement that
+    // special-cases one type and delegates the rest to the built-in. Isolated to
+    // this augment-check program, so the main suite's built-in behavior (e.g.
+    // JsonSerialize<bigint> = never) is unaffected — demonstrating overrides are
+    // per-project augmentation.
+    interface JsonSerializeOverride<T> {
+      app: T extends bigint ? string : Rango.JsonSerializeBuiltin<T>;
+    }
+    interface FlightSerializeOverride<T> {
+      app: T extends Money ? number : Rango.FlightSerializeBuiltin<T>;
+    }
+  }
+}

package/src/__augment-tests__/augmented.check.ts

@@ -0,0 +1,116 @@
+/**
+ * Compile-only assertions for the AUGMENTED Rango namespace.
+ *
+ * Pins the type-safety contract a consumer gets after augmenting Env, Vars, and
+ * GeneratedRouteMap. A regression in the fallback chains (global-namespace.ts)
+ * turns these into tsc errors. Run via tsconfig.augment-check.json.
+ */
+import "./augment.js";
+import type { Handler, RouteParams, RouteSearchParams } from "../index.js";
+import type { DefaultRouteName } from "../types/global-namespace.js";
+import { href } from "../href-client.js";
+import type { Money, TestBindings } from "./augment.js";
+
+type Expect<T extends true> = T;
+type Equal<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+    ? true
+    : false;
+
+// Env: ctx.env resolves to the augmented bindings, not `unknown`/`any`.
+const envHandler: Handler<"home"> = (ctx) => {
+  type _envIsBindings = Expect<Equal<typeof ctx.env, TestBindings>>;
+  ctx.env.DB.query("select 1");
+  // @ts-expect-error - unknown binding is rejected once Env is augmented
+  ctx.env.MISSING();
+  return null;
+};
+void envHandler;
+
+// Vars: ctx.get is keyed by the augmented Vars.
+const varsHandler: Handler<"home"> = (ctx) => {
+  const user = ctx.get("user");
+  type _userTyped = Expect<
+    Equal<typeof user, { id: string; role: "admin" | "user" } | undefined>
+  >;
+  // @ts-expect-error - unknown var key is rejected once Vars is augmented
+  ctx.get("nope");
+  return null;
+};
+void varsHandler;
+
+// routeName narrows to the generated route names.
+type _routeName = Expect<
+  Equal<DefaultRouteName, "home" | "blog.post" | "search">
+>;
+
+// RouteParams / RouteSearchParams resolve from the generated map with no
+// explicit route map argument.
+type _params = Expect<Equal<RouteParams<"blog.post">, { slug: string }>>;
+type _search = Expect<
+  Equal<RouteSearchParams<"search">, { q: string | undefined; page?: number }>
+>;
+
+// href / Rango.Path read GeneratedRouteMap even without a manual RegisteredRoutes
+// augmentation — this is the core of the "rango generate alone enables typed
+// href()" guarantee. The paths below come from the generated map in augment.ts.
+href("/");
+href("/blog/anything");
+href("/search");
+// @ts-expect-error - path is not in the generated route map
+href("/not-a-route");
+
+// Rango.Path is the ambient input type for wrapper functions around href().
+// No import needed — it reads the same generated map href() does.
+function wrappedHref(path: Rango.Path): string {
+  return href(path);
+}
+const arrowHref = (path: Rango.Path): string => href(path);
+
+wrappedHref("/blog/anything");
+arrowHref("/search?q=hello");
+// @ts-expect-error - wrapper preserves the same generated-map validation
+wrappedHref("/not-a-route");
+
+// Userland serialization augmentation: a consumer's custom class adjusts its JSON
+// wire shape via toJSON(), and Rango.PathResponse reports the serialized payload
+// (Money -> number, Date -> string) — both by pattern and by concrete path.
+type _orderWireByPattern = Expect<
+  Equal<
+    Rango.PathResponse<"/orders/:id">,
+    { id: string; total: number; placedAt: string }
+  >
+>;
+type _orderWireByPath = Expect<
+  Equal<
+    Rango.PathResponse<"/orders/42">,
+    { id: string; total: number; placedAt: string }
+  >
+>;
+
+// Project serialization overrides: the consumer augments JsonSerializeOverride /
+// FlightSerializeOverride (see augment.ts) with a full transform that delegates to
+// the built-in, and the transforms honor it — winning over the built-in rules.
+// bigint normally JSON-serializes to `never`; Money is a class React Flight would
+// otherwise reject structurally. Delegation keeps every other type (incl. the
+// /orders payload above) on the built-in behavior.
+type _jsonOverride = Expect<Equal<Rango.JsonSerialize<bigint>, string>>;
+type _jsonOverrideNested = Expect<
+  Equal<
+    Rango.JsonSerialize<{ id: bigint; name: string }>,
+    { id: string; name: string }
+  >
+>;
+type _flightOverride = Expect<Equal<Rango.FlightSerialize<Money>, number>>;
+
+// Reference the top-level assertion aliases so they are unambiguously evaluated.
+export type _Assertions = [
+  _routeName,
+  _params,
+  _search,
+  _orderWireByPattern,
+  _orderWireByPath,
+  _jsonOverride,
+  _jsonOverrideNested,
+  _flightOverride,
+];

package/src/__internal.ts

@@ -108,7 +108,11 @@ export type {
  * @internal
  * Router context for AsyncLocalStorage.
  */
-export type { RouterContext, RevalidationContext, InterceptResult } from "./router/router-context.js";
+export type {
+  RouterContext,
+  RevalidationContext,
+  InterceptResult,
+} from "./router/router-context.js";
 
 // ============================================================================
 // Match Pipeline (Internal)
@@ -118,7 +122,10 @@ export type { RouterContext, RevalidationContext, InterceptResult } from "./rout
  * @internal
  * Route match context during pipeline processing.
  */
-export type { MatchContext, MatchPipelineState } from "./router/match-context.js";
+export type {
+  MatchContext,
+  MatchPipelineState,
+} from "./router/match-context.js";
 
 /**
  * @internal
@@ -153,10 +160,102 @@ export type {
 /**
  * @internal
  * Internal handler context with additional props for router internals.
- * Includes `_originalRequest` and `_currentSegmentId`.
+ * Includes `_currentSegmentId` and `_responseType`.
  */
 export type { InternalHandlerContext } from "./types.js";
 
+// ============================================================================
+// Rendering (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Builds React element trees from route segments.
+ */
+export { renderSegments } from "./segment-system.js";
+
+// ============================================================================
+// Error Utilities (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Error sanitization and network error utilities.
+ */
+export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
+
+// ============================================================================
+// Type Utilities (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
+ */
+export type { ScopedRouteMap } from "./types.js";
+
+/**
+ * @internal
+ * Type-level utilities for reverse URL generation.
+ */
+export type { MergeRoutes, SanitizePrefix } from "./reverse.js";
+
+/**
+ * @internal
+ * Individual telemetry event types.
+ */
+export type {
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  RequestTimeoutEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+} from "./router/telemetry.js";
+
+// ============================================================================
+// Pre-render / Static Handler Guards (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Type guard for prerender handler definitions.
+ */
+export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
+
+/**
+ * @internal
+ * Type guard for static handler definitions.
+ */
+export { isStaticHandler } from "./static-handler.js";
+
+// ============================================================================
+// URL Pattern Internals
+// ============================================================================
+
+/**
+ * @internal
+ * Sentinel used to tag response-type route entries.
+ */
+export { RESPONSE_TYPE } from "./urls.js";
+
+// ============================================================================
+// Route Match Debug (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Debug utilities for route matching performance analysis.
+ */
+export {
+  enableMatchDebug,
+  getMatchDebugStats,
+} from "./router/pattern-matching.js";
+
 // ============================================================================
 // Debug Utilities (Internal)
 // ============================================================================
@@ -172,4 +271,3 @@ export {
   type SerializedEntry,
   type SerializedManifest,
 } from "./debug.js";
-

package/src/bin/rango.ts

@@ -1,24 +1,321 @@
-import { resolve } from "node:path";
-import { findTsFiles, writePerModuleRouteTypesForFile } from "../build/generate-route-types.ts";
+import { resolve, dirname } from "node:path";
+import { readFileSync, statSync, existsSync } from "node:fs";
+import {
+  findTsFiles,
+  writePerModuleRouteTypesForFile,
+  writeCombinedRouteTypes,
+  detectUnresolvableIncludes,
+  detectUnresolvableIncludesForUrlsFile,
+  findNestedRouterConflict,
+  formatNestedRouterConflictError,
+  type UnresolvableInclude,
+} from "../build/generate-route-types.ts";
 
-const [command, ...args] = process.argv.slice(2);
+const [command, ...rawArgs] = process.argv.slice(2);
 
-if (command === "extract-names") {
-  const dir = args[0] ?? "./src";
-  const resolvedDir = resolve(dir);
-  console.log(`[rango] Scanning ${resolvedDir} for url modules...`);
+if (command === "generate") {
+  // Parse flags
+  let mode: "default" | "runtime" | "static" = "default";
+  let configFile: string | undefined;
+  const positionalArgs: string[] = [];
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === "--runtime") {
+      mode = "runtime";
+    } else if (arg === "--static") {
+      mode = "static";
+    } else if (arg === "--config") {
+      configFile = rawArgs[++i];
+      if (!configFile) {
+        console.error("[rango] --config requires a path argument");
+        process.exit(1);
+      }
+    } else if (arg.startsWith("--")) {
+      console.error(`[rango] Unknown flag: ${arg}`);
+      process.exit(1);
+    } else {
+      positionalArgs.push(arg);
+    }
+  }
+
+  if (positionalArgs.length === 0) {
+    console.error(
+      "[rango] Usage: rango generate <file|dir> [file2 ...] [--runtime|--static] [--config <path>]",
+    );
+    process.exit(1);
+  }
+
+  if (configFile && mode !== "runtime") {
+    console.warn("[rango] --config is only used with --runtime, ignoring");
+  }
+
+  if (mode === "runtime") {
+    // Runtime discovery: dynamically import to avoid loading Vite for static-only usage
+    runRuntimeDiscovery(positionalArgs, configFile).catch((err) => {
+      console.error(`[rango] Runtime discovery failed: ${err.message}`);
+      process.exit(1);
+    });
+  } else {
+    runStaticGeneration(positionalArgs, mode);
+  }
+} else {
+  if (
+    command &&
+    command !== "help" &&
+    command !== "--help" &&
+    command !== "-h"
+  ) {
+    console.error(`[rango] Unknown command: ${command}\n`);
+  }
+  console.log(`Usage: rango generate <file|dir> [file2 ...] [--runtime|--static] [--config <path>]
+
+  Auto-detects file type (createRouter, urls) and generates
+  the appropriate .gen.ts route type files.
+
+Modes:
+  (default)   Static parser with error on unresolvable includes
+  --runtime   Vite-based runtime discovery (100% coverage)
+              Requires vite and @vitejs/plugin-rsc
+  --static    Static parser, accept partial output with warnings
+
+Options:
+  --config <path>  Path to vite.config.ts (--runtime only, auto-detected if omitted)
+
+Examples:
+  rango generate src/router.tsx
+  rango generate src/router.tsx --runtime
+  rango generate src/ --static`);
+  process.exit(
+    command && command !== "help" && command !== "--help" && command !== "-h"
+      ? 1
+      : 0,
+  );
+}
+
+/**
+ * Walk up from a file path to find the project root (directory containing
+ * package.json or vite.config.ts).
+ */
+function findProjectRoot(fromPath: string): string {
+  let dir = dirname(resolve(fromPath));
+  while (dir !== dirname(dir)) {
+    if (
+      existsSync(resolve(dir, "package.json")) ||
+      existsSync(resolve(dir, "vite.config.ts")) ||
+      existsSync(resolve(dir, "vite.config.js"))
+    ) {
+      return dir;
+    }
+    dir = dirname(dir);
+  }
+  // Fallback to cwd if no project root found
+  return process.cwd();
+}
+
+function runStaticGeneration(args: string[], mode: "default" | "static") {
+  // Expand args: files are used directly, directories are scanned
+  const files: string[] = [];
+  for (const arg of args) {
+    const resolved = resolve(arg);
+    try {
+      if (statSync(resolved).isDirectory()) {
+        files.push(...findTsFiles(resolved));
+      } else {
+        files.push(resolved);
+      }
+    } catch {
+      console.warn(`[rango] Skipping ${arg}: not found`);
+    }
+  }
+
+  if (files.length === 0) {
+    console.log("[rango] No files to process");
+    process.exit(0);
+  }
+
+  // Phase 1: Classify files
+  const routerFiles: string[] = [];
+  const urlsFiles: string[] = [];
 
-  const files = findTsFiles(resolvedDir);
   for (const filePath of files) {
-    writePerModuleRouteTypesForFile(filePath);
+    try {
+      const source = readFileSync(filePath, "utf-8");
+      if (/\bcreateRouter\s*[<(]/.test(source)) {
+        routerFiles.push(filePath);
+      }
+      if (source.includes("urls(")) {
+        urlsFiles.push(filePath);
+      }
+    } catch (err) {
+      console.warn(
+        `[rango] Failed to process ${filePath}: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  // Phase 2: Collect diagnostics from all files BEFORE writing anything
+  const allDiagnostics: Array<UnresolvableInclude & { routerFile: string }> =
+    [];
+
+  for (const routerFile of routerFiles) {
+    const diagnostics = detectUnresolvableIncludes(routerFile);
+    for (const d of diagnostics) {
+      allDiagnostics.push({ ...d, routerFile });
+    }
+  }
+
+  // Also check standalone urls files not covered by router-level detection
+  const routerFileSet = new Set(routerFiles);
+  for (const urlsFile of urlsFiles) {
+    if (routerFileSet.has(urlsFile)) continue;
+    const diagnostics = detectUnresolvableIncludesForUrlsFile(urlsFile);
+    for (const d of diagnostics) {
+      allDiagnostics.push({ ...d, routerFile: urlsFile });
+    }
   }
 
-  console.log(`[rango] Scanned ${files.length} file(s)`);
+  // Deduplicate diagnostics (router and urls detection may find the same issue)
+  const seen = new Set<string>();
+  const uniqueDiagnostics = allDiagnostics.filter((d) => {
+    const key = `${d.sourceFile}:${d.pathPrefix}:${d.reason}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  if (uniqueDiagnostics.length > 0 && mode === "default") {
+    // Hard error: no files written
+    console.error("\n[rango] Unresolvable includes detected:\n");
+    formatDiagnostics(uniqueDiagnostics);
+    console.error(
+      "\nThe static parser cannot resolve these includes because they use " +
+        "factory functions or dynamic expressions.\n\n" +
+        "Options:\n" +
+        "  rango generate <path> --runtime   Use Vite-based discovery (requires vite)\n" +
+        "  rango generate <path> --static    Accept partial output (missing routes above)\n",
+    );
+    process.exit(1);
+  }
+
+  if (uniqueDiagnostics.length > 0 && mode === "static") {
+    // Warning: partial output accepted
+    console.warn(
+      "\n[rango] Warning: partial output (unresolvable includes):\n",
+    );
+    formatDiagnostics(uniqueDiagnostics);
+    console.warn("");
+  }
+
+  const nestedRouterConflict = findNestedRouterConflict(routerFiles);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
+  // Phase 3: Write all outputs (only reached if diagnostics pass or --static)
+  for (const urlsFile of urlsFiles) {
+    writePerModuleRouteTypesForFile(urlsFile);
+  }
+
+  for (const routerFile of routerFiles) {
+    const projectRoot = findProjectRoot(routerFile);
+    writeCombinedRouteTypes(projectRoot, [routerFile]);
+  }
+
+  console.log(
+    `[rango] Processed ${files.length} file(s)${routerFiles.length ? ` (${routerFiles.length} router)` : ""}`,
+  );
   process.exit(0);
-} else {
-  console.log(`Usage: rango <command>
+}
+
+async function runRuntimeDiscovery(args: string[], configFile?: string) {
+  // Resolve the entry: find the router file from the arguments
+  const files: string[] = [];
+  for (const arg of args) {
+    const resolved = resolve(arg);
+    try {
+      if (statSync(resolved).isDirectory()) {
+        files.push(...findTsFiles(resolved));
+      } else {
+        files.push(resolved);
+      }
+    } catch {
+      console.warn(`[rango] Skipping ${arg}: not found`);
+    }
+  }
+
+  // Find router files among the inputs
+  const routerEntries: string[] = [];
+  for (const filePath of files) {
+    try {
+      const source = readFileSync(filePath, "utf-8");
+      if (/\bcreateRouter\s*[<(]/.test(source)) {
+        routerEntries.push(filePath);
+      }
+      // Also generate per-module types for urls files
+      if (source.includes("urls(")) {
+        writePerModuleRouteTypesForFile(filePath);
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  if (routerEntries.length === 0) {
+    console.error("[rango] No router files found in the provided paths");
+    process.exit(1);
+  }
+
+  const nestedRouterConflict = findNestedRouterConflict(routerEntries);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
+  let discoverAndWriteRouteTypes: typeof import("../build/runtime-discovery.ts").discoverAndWriteRouteTypes;
+  try {
+    const mod = await import("../build/runtime-discovery.ts");
+    discoverAndWriteRouteTypes = mod.discoverAndWriteRouteTypes;
+  } catch (err: any) {
+    if (
+      err.code === "ERR_MODULE_NOT_FOUND" ||
+      err.code === "MODULE_NOT_FOUND"
+    ) {
+      console.error(
+        "[rango] Runtime discovery requires 'vite' and '@vitejs/plugin-rsc'.\n" +
+          "Install them with: pnpm add -D vite @vitejs/plugin-rsc",
+      );
+    } else {
+      console.error(`[rango] Failed to load runtime discovery: ${err.message}`);
+    }
+    process.exit(1);
+  }
 
-Commands:
-  extract-names [dir]  Extract route names from url modules (default: ./src)`);
-  process.exit(command ? 1 : 0);
+  for (const entry of routerEntries) {
+    const projectRoot = findProjectRoot(entry);
+    const result = await discoverAndWriteRouteTypes({
+      root: projectRoot,
+      configFile,
+      entry,
+    });
+    console.log(
+      `[rango] Runtime discovery: ${result.routerCount} router(s), ${result.routeCount} route(s)`,
+    );
+  }
+}
+
+function formatDiagnostics(
+  diagnostics: Array<UnresolvableInclude & { routerFile: string }>,
+) {
+  for (const d of diagnostics) {
+    const prefix = d.namePrefix ? `${d.namePrefix}.*` : `${d.pathPrefix}*`;
+    console.error(`  ${prefix}`);
+    console.error(`    Reason:  ${d.reason} -- ${d.detail}`);
+    console.error(`    Source:  ${d.sourceFile}`);
+  }
 }