@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.15

package/skills/testing/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: testing
+description: Unit test route trees with buildRouteTree()
+argument-hint:
+---
+
+# Route Tree Unit Testing
+
+Unit test route definitions by inspecting the route tree, segment IDs, middleware, intercepts, loaders, and pattern matching without running a dev server.
+
+## Setup
+
+The `buildRouteTree` helper lives in `src/__tests__/helpers/route-tree.ts` (not shipped with npm). Import it in your test files:
+
+```typescript
+import { buildRouteTree } from "./helpers/route-tree.js";
+```
+
+## buildRouteTree(urlPatterns)
+
+Takes a `urls()` result and returns a `RouteTree` with inspection methods:
+
+```typescript
+import { urls } from "@rangojs/router";
+import { buildRouteTree } from "./helpers/route-tree.js";
+
+const tree = buildRouteTree(
+  urls(({ path, layout, middleware, loader, intercept, when }) => [
+    layout(RootLayout, () => [
+      middleware(authMiddleware),
+      path("/", HomePage, { name: "home" }),
+      path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
+        loader(PostLoader),
+      ]),
+    ]),
+  ])
+);
+```
+
+## RouteTree API
+
+### Route Patterns
+
+```typescript
+tree.routes()       // { home: "/", "blog.post": "/blog/:slug" }
+tree.routeNames()   // ["home", "blog.post"]
+```
+
+### URL Matching
+
+```typescript
+const m = tree.match("/blog/hello");
+m.routeKey  // "blog.post"
+m.params    // { slug: "hello" }
+
+tree.match("/nonexistent")  // null
+```
+
+### Segment IDs
+
+```typescript
+tree.segmentId("home")       // "M0L0L0R0"
+tree.segmentIds()            // { home: "M0L0L0R0", "blog.post": "M0L0L0R1" }
+tree.segmentPath("blog.post")
+// [
+//   { id: "M0L0",     type: "layout" },  // synthetic root
+//   { id: "M0L0L0",   type: "layout" },  // RootLayout
+//   { id: "M0L0L0R1", type: "route", pattern: "/blog/:slug" },
+// ]
+```
+
+### Entry Access
+
+```typescript
+tree.entry("blog.post")                   // EntryData
+tree.entry("blog.post")!.parent!.type     // "layout"
+tree.entryByPattern("/blog/:slug")        // EntryData (lookup by URL pattern)
+```
+
+### Middleware
+
+```typescript
+tree.hasMiddleware("home")                // true (inherited from layout)
+tree.middleware("home")                   // [authMiddleware] (direct only)
+tree.middlewareChain("home")
+// [{ segmentId: "M0L0L0", count: 1 }]   // all middleware root-to-route
+```
+
+### Loaders
+
+```typescript
+tree.hasLoaders("blog.post")  // true
+tree.loaders("blog.post")     // [LoaderEntry { loader, revalidate, cache? }]
+```
+
+### Intercepts
+
+```typescript
+tree.intercepts("home")
+// [{ slotName: "@modal", routeName: "card", hasWhen: true, whenCount: 1, hasLoader: false, hasMiddleware: false }]
+tree.interceptEntries("home")  // raw InterceptEntry[]
+```
+
+### Parallel Slots
+
+```typescript
+tree.parallelSlots("home")       // EntryData[] of type="parallel"
+tree.parallelSlotNames("home")   // ["@sidebar", "@main"]
+```
+
+### Boundaries
+
+```typescript
+tree.hasErrorBoundary("home")      // boolean
+tree.hasNotFoundBoundary("home")   // boolean
+```
+
+### Cache & Loading
+
+```typescript
+tree.hasCache("home")     // boolean
+tree.hasLoading("home")   // boolean
+```
+
+### Debug
+
+```typescript
+console.log(tree.debug());
+// Route Tree:
+//   home: / [M0L0L0R0] (M0L0 > M0L0L0 > M0L0L0R0) {mw:1}
+//   blog.post: /blog/:slug [M0L0L0R1] (M0L0 > M0L0L0 > M0L0L0R1) {mw:1, ld:1}
+```
+
+## Segment ID Format
+
+| Prefix | Meaning |
+|--------|---------|
+| `M0`   | Mount index (router instance) |
+| `L`    | Layout |
+| `R`    | Route |
+| `P`    | Parallel slot |
+| `D`    | Loader (data) |
+| `C`    | Cache boundary |
+
+Example: `M0L0L0R1` = mount 0, synthetic root layout, user layout, second route.
+
+## Examples
+
+### include() with prefix
+
+```typescript
+const blogPatterns = urls(({ path }) => [
+  path("/", BlogIndex, { name: "index" }),
+  path("/:slug", BlogPost, { name: "post" }),
+]);
+
+const tree = buildRouteTree(
+  urls(({ path, include }) => [
+    path("/", HomePage, { name: "home" }),
+    include("/blog", blogPatterns, { name: "blog" }),
+  ])
+);
+
+expect(tree.routes()).toEqual({
+  home: "/",
+  "blog.index": "/blog",
+  "blog.post": "/blog/:slug",
+});
+```
+
+### Middleware chain
+
+```typescript
+const authMw = async (ctx, next) => next();
+const logMw = async (ctx, next) => next();
+
+const tree = buildRouteTree(
+  urls(({ path, layout, middleware }) => [
+    layout(RootLayout, () => [
+      middleware(logMw),
+      layout(AuthLayout, () => [
+        middleware(authMw),
+        path("/dashboard", Dashboard, { name: "dashboard" }),
+      ]),
+    ]),
+  ])
+);
+
+expect(tree.middlewareChain("dashboard")).toEqual([
+  { segmentId: "M0L0L0", count: 1 },   // logMw on RootLayout
+  { segmentId: "M0L0L0L0", count: 1 }, // authMw on AuthLayout
+]);
+```
+
+### Intercepts with when()
+
+```typescript
+const tree = buildRouteTree(
+  urls(({ path, layout, intercept, when }) => [
+    layout(ShopLayout, () => [
+      path("/products", ProductList, { name: "products" }),
+      path("/products/:id", ProductDetail, { name: "product.detail" }),
+      intercept("@modal", "product.detail", ProductModal, () => [
+        when((ctx) => ctx.from.pathname.startsWith("/products")),
+      ]),
+    ]),
+  ])
+);
+
+const intercepts = tree.intercepts("products");
+// Note: intercepts are on the parent where intercept() is called
+```
+
+### Constrained parameters
+
+```typescript
+const tree = buildRouteTree(
+  urls(({ path }) => [
+    path("/:locale(en|fr)?/about", AboutPage, { name: "about" }),
+  ])
+);
+
+expect(tree.match("/about")).not.toBeNull();
+expect(tree.match("/fr/about")!.params).toEqual({ locale: "fr" });
+expect(tree.match("/de/about")).toBeNull();
+```

package/skills/typesafety/SKILL.md

@@ -45,22 +45,35 @@ export const urlpatterns = urls(({ path, layout }) => [
 
 ## Type-Safe href()
 
-### Server: ctx.reverse + scopedReverse
+### Server: ctx.reverse with global route names
 
-In route handlers, use `scopedReverse()` for local route name autocomplete:
+In route handlers, use `ctx.reverse()` with the global dotted route names
+from `router.named-routes.gen.ts`:
 
 ```typescript
-import { scopedReverse } from "@rangojs/router";
-
-path("/product/:slug", (ctx) => {
-  const reverse = scopedReverse<typeof shopPatterns>(ctx.reverse);
+import type { Handler } from "@rangojs/router";
 
-  reverse("cart");                        // Type-safe local name
-  reverse("product", { slug: "widget" }); // Type-safe with params
-  reverse("blog.post");                   // Absolute names always allowed
+export const ProductHandler: Handler<"shop.product"> = (ctx) => {
+  ctx.reverse("shop.cart");                       // Global name
+  ctx.reverse("shop.product", { slug: "widget" }); // With params
+  ctx.reverse("blog.post", { postId: "1" });       // Cross-module
 
   return <ProductPage slug={ctx.params.slug} />;
-}, { name: "product" })
+};
+```
+
+For opt-in per-module isolation (after running `npx rango generate urls/shop.tsx`),
+use `scopedReverse()` with a local route map:
+
+```typescript
+import { scopedReverse } from "@rangojs/router";
+import type { routes } from "./shop.gen.js";
+
+export const ProductHandler: Handler<"product", routes> = (ctx) => {
+  const reverse = scopedReverse<routes>(ctx.reverse);
+  reverse("cart");                        // Local name
+  reverse("product", { slug: "widget" }); // Local with params
+};
 ```
 
 ### Client: href + useHref
@@ -192,13 +205,14 @@ export const SearchPage: Handler<"search"> = (ctx) => {
 ```
 
 This avoids circular references because `Handler` defaults to `GeneratedRouteMap`
-(standalone gen file) instead of `RegisteredRoutes` (which depends on `router.tsx`).
+(from `router.named-routes.gen.ts`) instead of `RegisteredRoutes` (which depends on `router.tsx`).
 
-You can also pass an explicit route map if needed:
+You can also pass an explicit route map for per-module isolation (opt-in,
+after running `npx rango generate`):
 
 ```typescript
 import type { Handler } from "@rangojs/router";
-import type { routes } from "../urls.gen.js";
+import type { routes } from "./urls.gen.js";
 
 export const SearchPage: Handler<"search", routes> = (ctx) => { ... };
 ```
@@ -240,16 +254,15 @@ type P = RouteParams<"blogPost", routes>;
 
 ### Generated route types
 
-In the generated route types (`urls.gen.ts` and `GeneratedRouteMap`), routes with
-search schemas use `{ path, search }` objects:
+In the generated `router.named-routes.gen.ts`, routes with search schemas
+use `{ path, search }` objects:
 
 ```typescript
-// urls.gen.ts (auto-generated by `npx rango extract-names`)
-export const routes = {
-  search: { path: "/search", search: { q: "string", page: "number?", sort: "string?" } },
-  home: "/",  // No search schema -> plain string
+// router.named-routes.gen.ts (auto-generated)
+export const NamedRoutes = {
+  "search.index": { path: "/search", search: { q: "string", page: "number?", sort: "string?" } },
+  "home.index": "/",  // No search schema -> plain string
 } as const;
-export type routes = typeof routes;
 ```
 
 ## Loader Type Safety
@@ -426,9 +439,10 @@ global type declarations (like `RSCRouter.Env`).
 }
 ```
 
-The `files` array ensures `router.tsx` (which contains `declare global { namespace RSCRouter { ... } }`)
-is always included in the compilation even if nothing directly imports it. Each app gets its own
-typed environment without interfering with other apps.
+The `files` array ensures `router.tsx` (which contains `declare global { namespace RSCRouter { interface Env } }`)
+is always included in the compilation even if nothing directly imports it. Route types come from the
+auto-generated `*.named-routes.gen.ts` file (via `rango generate`), not from manual declaration.
+Each app gets its own typed environment without interfering with other apps.
 
 ## Complete Type-Safe Setup
 
@@ -450,21 +464,26 @@ export const urlpatterns = urls(({ path, layout, loader }) => [
   ]),
 ]);
 
-// 3. router.tsx - Registration
+// 3. router.tsx - Create router and export reverse
 const router = createRouter<AppEnv>({
   document: Document,
-  urls: urlpatterns,
-});
+}).routes(urlpatterns);
 
+// Optional: register environment type globally for implicit typing
 declare global {
   namespace RSCRouter {
     interface Env extends AppEnv {}
   }
 }
 
+export const reverse = router.reverse;
 export default router;
 
-// 4. loaders/*.ts - Type-safe loaders
+// 4. Run `npx rango generate src/router.tsx` to generate
+//    router.named-routes.gen.ts (auto-registers GeneratedRouteMap globally).
+//    No manual RegisteredRoutes declaration needed.
+
+// 5. loaders/*.ts - Type-safe loaders
 export const ProductLoader = createLoader("product", async (ctx) => {
   // ctx.params: { slug: string }
   // ctx.env.Variables.user: User | undefined
@@ -472,13 +491,12 @@ export const ProductLoader = createLoader("product", async (ctx) => {
   return { product: await fetchProduct(ctx.params.slug) };
 });
 
-// 5. Server: ctx.reverse for named routes
+// 6. Server: ctx.reverse for named routes
 path("/product/:slug", (ctx) => {
-  const reverse = scopedReverse<typeof urlpatterns>(ctx.reverse);
-  return <Link to={reverse("shop")}>Back to Shop</Link>;
+  return <Link to={ctx.reverse("shop")}>Back to Shop</Link>;
 }, { name: "product" })
 
-// 6. Client: useHref for mounted paths, href for absolute
+// 7. Client: useHref for mounted paths, href for absolute
 "use client";
 import { useHref, href, Link } from "@rangojs/router/client";
 <Link to={href("/shop/product/widget")}>Widget</Link>

package/src/bin/rango.ts

@@ -1,24 +1,75 @@
-import { resolve } from "node:path";
-import { findTsFiles, writePerModuleRouteTypesForFile } from "../build/generate-route-types.ts";
+import { resolve, dirname, extname } from "node:path";
+import { readFileSync, statSync } from "node:fs";
+import { findTsFiles, writePerModuleRouteTypesForFile, writeCombinedRouteTypes } from "../build/generate-route-types.ts";
 
 const [command, ...args] = 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") {
+  if (args.length === 0) {
+    console.error("[rango] Usage: rango generate <file|dir> [file2 ...]");
+    process.exit(1);
+  }
+
+  // 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);
+  }
+
+  const routerFiles: string[] = [];
 
-  const files = findTsFiles(resolvedDir);
   for (const filePath of files) {
-    writePerModuleRouteTypesForFile(filePath);
+    try {
+      const source = readFileSync(filePath, "utf-8");
+
+      // Detect file type and generate accordingly
+      const isRouter = /\bcreateRouter\s*[<(]/.test(source);
+      const isUrls = source.includes("urls(");
+
+      if (isRouter) {
+        routerFiles.push(filePath);
+      }
+
+      if (isUrls) {
+        writePerModuleRouteTypesForFile(filePath);
+      }
+    } catch (err) {
+      console.warn(`[rango] Failed to process ${filePath}: ${(err as Error).message}`);
+    }
+  }
+
+  // Generate named-routes for any detected router files
+  for (const routerFile of routerFiles) {
+    writeCombinedRouteTypes(dirname(routerFile), [routerFile]);
   }
 
-  console.log(`[rango] Scanned ${files.length} file(s)`);
+  console.log(`[rango] Processed ${files.length} file(s)${routerFiles.length ? ` (${routerFiles.length} router)` : ""}`);
   process.exit(0);
 } else {
-  console.log(`Usage: rango <command>
+  console.log(`Usage: rango generate <file|dir> [file2 ...]
+
+  Auto-detects file type (createRouter, urls) and generates
+  the appropriate .gen.ts route type files.
+
+  Pass files, directories, or a mix of both.
 
-Commands:
-  extract-names [dir]  Extract route names from url modules (default: ./src)`);
+Examples:
+  rango generate src/urls.tsx
+  rango generate src/router.tsx src/urls.tsx
+  rango generate src/`);
   process.exit(command ? 1 : 0);
 }