@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/server/route-matcher.ts

@@ -8,67 +8,53 @@
  * See design/07-routing.md §"Request Lifecycle"
  */
 
-import type { RouteMatch } from './pipeline.js';
-import type { MiddlewareFn } from './middleware-runner.js';
+import type { RouteMatch } from './pipeline.ts';
+import type { MiddlewareFn } from './middleware-runner.ts';
+import type { SegmentNode, RouteTree } from '../routing/types.ts';
 import {
   METADATA_ROUTE_CONVENTIONS,
   isStaticMetadataExtension,
   resolveStaticContentType,
+  resolveServePathForFile,
   type MetadataRouteType,
-} from './metadata-routes.js';
+} from './metadata-routes.ts';
+import { matchUrlParts, matchUrlPartsAll } from './tree-match.ts';
 
 // ─── Manifest Types ───────────────────────────────────────────────────────
-// The virtual module manifest has a slightly different shape than SegmentNode:
-// file references are { load, filePath } instead of RouteFile.
+//
+// TIM-848: the runtime route manifest re-uses the same `SegmentNode<TFile>`
+// / `RouteTree<TFile>` interfaces from `routing/types.ts`. The only
+// difference between build-time and runtime is the file reference payload
+// — build-time has `{ filePath, extension }`, runtime has `{ filePath, load }`.
+// Walkers parameterized over `TFile` work on either; there is no separate
+// "manifest" tree shape.
 
 /** A file reference in the manifest (lazy import + path). */
-interface ManifestFile {
+export interface ManifestFile {
   load: () => Promise<unknown>;
   filePath: string;
 }
 
-/** A segment node as it appears in the virtual:timber-route-manifest module. */
-export interface ManifestSegmentNode {
-  segmentName: string;
-  segmentType:
-    | 'static'
-    | 'dynamic'
-    | 'catch-all'
-    | 'optional-catch-all'
-    | 'group'
-    | 'slot'
-    | 'intercepting';
-  urlPath: string;
-  paramName?: string;
-  /** For intercepting segments: the marker used, e.g. "(.)". */
-  interceptionMarker?: '(.)' | '(..)' | '(...)' | '(..)(..)';
-  /** For intercepting segments: the segment name after stripping the marker. */
-  interceptedSegmentName?: string;
-
-  page?: ManifestFile;
-  layout?: ManifestFile;
-  middleware?: ManifestFile;
-  access?: ManifestFile;
-  route?: ManifestFile;
-  error?: ManifestFile;
-  default?: ManifestFile;
-  denied?: ManifestFile;
-  searchParams?: ManifestFile;
-  statusFiles?: Record<string, ManifestFile>;
-  jsonStatusFiles?: Record<string, ManifestFile>;
-  legacyStatusFiles?: Record<string, ManifestFile>;
-  prerender?: ManifestFile;
-  /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
-  metadataRoutes?: Record<string, ManifestFile>;
-
-  children: ManifestSegmentNode[];
-  slots: Record<string, ManifestSegmentNode>;
-}
+/**
+ * A segment node as it appears in the virtual:timber-route-manifest module.
+ *
+ * Type alias for `SegmentNode<ManifestFile>` — the same shape used by the
+ * scanner, only with lazy `load` functions instead of build-time extension
+ * metadata.
+ */
+export type ManifestSegmentNode = SegmentNode<ManifestFile>;
 
-/** The manifest shape from virtual:timber-route-manifest. */
-export interface ManifestRoot {
-  root: ManifestSegmentNode;
-  proxy?: ManifestFile;
+/**
+ * The manifest shape from virtual:timber-route-manifest.
+ *
+ * Extends `RouteTree<ManifestFile>` with `viteRoot`, the absolute path
+ * to the Vite project root captured at build/load time. Used by dev-only
+ * features (e.g., dev error page frame classification) that need a
+ * correct project root even when CWD differs (e.g., monorepo custom root).
+ * See TIM-807 / TIM-808.
+ */
+export interface ManifestRoot extends RouteTree<ManifestFile> {
+  viteRoot: string;
 }
 
 // ─── Matcher ──────────────────────────────────────────────────────────────
@@ -88,201 +74,72 @@ export function createRouteMatcher(
 /**
  * Match a canonical pathname against the segment tree.
  *
- * Splits the pathname into segments and walks the tree depth-first.
- * Returns the segment chain and extracted params on match.
+ * Splits the pathname into segments and delegates to the shared
+ * tree walker. Collects middleware from the matched segment chain.
  */
 function matchPathname(root: ManifestSegmentNode, pathname: string): RouteMatch | null {
-  // Split pathname into segments: "/blog/hello-world" → ["blog", "hello-world"]
-  // "/" → [] (empty segments)
   const parts = pathname === '/' ? [] : pathname.slice(1).split('/');
 
-  const segments: ManifestSegmentNode[] = [];
-  const params: Record<string, string | string[]> = {};
-
-  const matched = matchSegments(root, parts, 0, segments, params);
-  if (!matched) return null;
-
-  // Convert ManifestSegmentNodes to the SegmentNode shape expected by RouteMatch.
-  // The pipeline and tree builder use SegmentNode which has RouteFile references,
-  // but we pass the manifest nodes directly — they're structurally compatible
-  // for the fields the pipeline cares about (segments array + params).
-  // Resolve the leaf segment's middleware.ts if present.
-  // Only the leaf route's middleware runs — no chain, no inheritance.
-  const leafSegment = segments[segments.length - 1];
-  let middleware: MiddlewareFn | undefined;
-  if (leafSegment?.middleware) {
-    const loader = leafSegment.middleware.load;
-    middleware = async (ctx) => {
-      const mod = (await loader()) as { default?: MiddlewareFn };
-      if (mod.default) {
-        return mod.default(ctx);
-      }
-    };
-  }
+  const result = matchUrlParts(root, parts);
+  if (!result) return null;
 
   return {
-    // The pipeline uses segments as opaque objects passed to the renderer.
-    // Cast is safe — the renderer receives what the manifest provides.
-    segments: segments as unknown as RouteMatch['segments'],
-    params,
-    middleware,
+    segments: result.chain,
+    rawSegmentParams: result.params,
+    // Uncoerced until the pipeline runs the codecs; a copy, so nothing that
+    // later replaces or edits it can reach the raw record.
+    segmentParams: { ...result.params },
+    middlewareChain: collectMiddlewareChain(result.chain),
   };
 }
 
 /**
- * An effective child flattened through group segments.
- * Includes the chain of group nodes that must be added to the segments
- * array before the child itself (to preserve the group → child nesting
- * that the renderer expects).
- */
-interface EffectiveChild {
-  child: ManifestSegmentNode;
-  groupChain: ManifestSegmentNode[];
-}
-
-/**
- * Collect effective children by flattening through group segments.
+ * Collect middleware from a matched segment chain, root to leaf.
+ *
+ * Each entry is lazy-loaded via dynamic import on first invocation.
  *
- * Groups are transparent for URL matching — their non-group descendants
- * are returned with the chain of group nodes that lead to them. This
- * allows the caller to apply priority ordering (static > dynamic > ...)
- * across all groups uniformly instead of per-group.
+ * Shared with the children-path interception resolver
+ * (`children-interception.ts`), which assembles a chain from the tree rather
+ * than from a pathname but produces the same kind of `RouteMatch` — every
+ * `middleware.ts` above an intercepted page must run exactly as it does for
+ * the canonical route.
  */
-function collectEffectiveChildren(
-  node: ManifestSegmentNode,
-  groupChain: ManifestSegmentNode[] = []
-): EffectiveChild[] {
-  const result: EffectiveChild[] = [];
-  for (const child of node.children) {
-    if (child.segmentType === 'group') {
-      // Look through the group — its children become effective children
-      // with this group prepended to their chain
-      const nested = collectEffectiveChildren(child, [...groupChain, child]);
-      result.push(...nested);
-    } else {
-      result.push({ child, groupChain });
+export function collectMiddlewareChain(chain: ManifestSegmentNode[]): MiddlewareFn[] {
+  const middlewareChain: MiddlewareFn[] = [];
+  for (const segment of chain) {
+    if (segment.middleware) {
+      const loader = segment.middleware.load;
+      middlewareChain.push(async (ctx) => {
+        const mod = (await loader()) as { default?: MiddlewareFn };
+        if (mod.default) {
+          return mod.default(ctx);
+        }
+      });
     }
   }
-  return result;
+  return middlewareChain;
 }
 
 /**
- * Recursively match URL segments against the segment tree.
- *
- * Priority order for children at each level:
- *   1. Static segments (exact match)
- *   2. Dynamic segments ([param])
- *   3. Catch-all segments ([...param])
- *   4. Optional catch-all segments ([[...param]])
- *
- * Groups are transparent — they don't consume URL segments. Children
- * are flattened through groups so that priority ordering applies across
- * all groups uniformly (a static in group A always beats a dynamic in
- * group B, regardless of group ordering).
+ * Whether a matched chain renders as an API route: its leaf has a
+ * `route.ts` and no `page.tsx`. The same test `renderRoute` dispatches on,
+ * so every answer about a route's format — early hints, deny format, error
+ * format, error reporting — agrees with what actually ran.
  */
-function matchSegments(
-  node: ManifestSegmentNode,
-  parts: string[],
-  index: number,
-  segments: ManifestSegmentNode[],
-  params: Record<string, string | string[]>
-): boolean {
-  segments.push(node);
-
-  // All parts consumed — check if this node has a page or route
-  if (index >= parts.length) {
-    if (node.page || node.route) {
-      return true;
-    }
-
-    // Check group children (they don't consume URL segments)
-    for (const child of node.children) {
-      if (child.segmentType === 'group') {
-        if (matchSegments(child, parts, index, segments, params)) {
-          return true;
-        }
-      }
-    }
-
-    // Check optional catch-all children (direct and through groups)
-    const effective = collectEffectiveChildren(node);
-    for (const { child, groupChain } of effective) {
-      if (child.segmentType === 'optional-catch-all') {
-        if (child.page || child.route) {
-          segments.push(...groupChain, child);
-          // Zero segments → param is undefined (not set), matching Next.js semantics
-          return true;
-        }
-      }
-    }
-
-    segments.pop();
-    return false;
-  }
-
-  const part = parts[index];
-
-  // Flatten children through groups so priority ordering applies globally
-  // across all groups, not per-group.
-  const effective = collectEffectiveChildren(node);
-
-  // 1. Static segments
-  for (const { child, groupChain } of effective) {
-    if (child.segmentType === 'static' && child.segmentName === part) {
-      segments.push(...groupChain);
-      if (matchSegments(child, parts, index + 1, segments, params)) {
-        return true;
-      }
-      // Backtrack group chain
-      segments.length -= groupChain.length;
-    }
-  }
-
-  // 2. Dynamic segments ([param])
-  for (const { child, groupChain } of effective) {
-    if (child.segmentType === 'dynamic' && child.paramName) {
-      segments.push(...groupChain);
-      const prevParam = params[child.paramName];
-      params[child.paramName] = part;
-      if (matchSegments(child, parts, index + 1, segments, params)) {
-        return true;
-      }
-      // Backtrack
-      segments.length -= groupChain.length;
-      if (prevParam !== undefined) {
-        params[child.paramName] = prevParam;
-      } else {
-        delete params[child.paramName];
-      }
-    }
-  }
-
-  // 3. Catch-all segments ([...param])
-  for (const { child, groupChain } of effective) {
-    if (child.segmentType === 'catch-all' && child.paramName) {
-      if (child.page || child.route) {
-        const remaining = parts.slice(index);
-        segments.push(...groupChain, child);
-        params[child.paramName] = remaining;
-        return true;
-      }
-    }
-  }
-
-  // 4. Optional catch-all segments ([[...param]])
-  for (const { child, groupChain } of effective) {
-    if (child.segmentType === 'optional-catch-all' && child.paramName) {
-      if (child.page || child.route) {
-        const remaining = parts.slice(index);
-        segments.push(...groupChain, child);
-        params[child.paramName] = remaining;
-        return true;
-      }
-    }
-  }
+export function isApiRouteChain(segments: readonly ManifestSegmentNode[]): boolean {
+  const leaf = segments[segments.length - 1];
+  return !!leaf?.route && !leaf.page;
+}
 
-  segments.pop();
-  return false;
+/**
+ * Whether a matched chain is a route.ts handler that opted out of the CSRF
+ * check with `export const csrf = false`. Keyed on the same leaf
+ * `isApiRouteChain` dispatches on, so the exemption can only ever apply to
+ * the route.ts that will actually run — never to a page, and so never to a
+ * server action. See design/08-forms-and-actions.md §"Per-route exemption".
+ */
+export function isCsrfExemptRoute(segments: readonly ManifestSegmentNode[]): boolean {
+  return isApiRouteChain(segments) && segments[segments.length - 1]?.csrfExempt === true;
 }
 
 // ─── Metadata Route Matcher ─────────────────────────────────────────────
@@ -302,73 +159,187 @@ export interface MetadataRouteMatch {
    * that should be served from disk rather than executed as a handler.
    */
   isStatic: boolean;
+  /** Extracted segment params from dynamic segments in the URL prefix. */
+  segmentParams: Record<string, string | string[]>;
+}
+
+// Reverse lookup: serve path (with extension) → convention base name
+const SERVE_PATH_TO_CONVENTION = new Map<string, string>();
+for (const [baseName, convention] of Object.entries(METADATA_ROUTE_CONVENTIONS)) {
+  if (convention.serveExtension) {
+    for (const ext of [...convention.staticExtensions, convention.serveExtension]) {
+      SERVE_PATH_TO_CONVENTION.set(`${convention.servePath}.${ext}`, baseName);
+    }
+  } else {
+    SERVE_PATH_TO_CONVENTION.set(convention.servePath, baseName);
+  }
 }
 
 /**
  * Create a metadata route matcher from a manifest.
  *
- * Walks the segment tree and builds a map from serve paths to handler modules.
- * Metadata routes are matched by exact pathname (e.g., /sitemap.xml, /blog/sitemap.xml).
+ * Uses dynamic tree matching to resolve metadata routes, supporting
+ * dynamic segments like /docs/[slug]/opengraph-image.
  *
  * See design/16-metadata.md §"Metadata Routes"
  */
 export function createMetadataRouteMatcher(
   manifest: ManifestRoot
 ): (pathname: string) => MetadataRouteMatch | null {
-  // Build a static lookup map: pathname → match info
-  const routeMap = new Map<string, MetadataRouteMatch>();
-  collectMetadataRoutes(manifest.root, routeMap);
-
-  return (pathname: string) => routeMap.get(pathname) ?? null;
+  return (pathname: string) => matchMetadataPathname(manifest.root, pathname);
 }
 
 /**
- * Recursively collect metadata routes from the segment tree into a lookup map.
+ * Match a pathname against metadata routes in the segment tree.
+ *
+ * Checks if the last URL part is a known metadata route serve path,
+ * then walks the tree to find the segment that owns the route.
  */
-function collectMetadataRoutes(
-  node: ManifestSegmentNode,
-  map: Map<string, MetadataRouteMatch>
-): void {
-  if (node.metadataRoutes) {
-    for (const [baseName, file] of Object.entries(node.metadataRoutes)) {
-      const convention = METADATA_ROUTE_CONVENTIONS[baseName];
-      if (!convention) continue;
-
-      // Non-nestable routes (robots, manifest, favicon) only serve from root
-      if (!convention.nestable && node.urlPath !== '/') continue;
+function matchMetadataPathname(
+  root: ManifestSegmentNode,
+  pathname: string
+): MetadataRouteMatch | null {
+  const parts = pathname === '/' ? [] : pathname.slice(1).split('/');
+  if (parts.length === 0) return null;
+
+  const lastPart = parts[parts.length - 1];
+  const baseName = SERVE_PATH_TO_CONVENTION.get(lastPart);
+  if (!baseName) return null;
+
+  const convention = METADATA_ROUTE_CONVENTIONS[baseName];
+  if (!convention) return null;
+
+  // The prefix parts identify which segment owns this metadata route.
+  // For root-level routes (e.g. /sitemap.xml), prefix is empty → root segment.
+  const prefixParts = parts.slice(0, -1);
+
+  let segment: ManifestSegmentNode;
+  let params: Record<string, string | string[]>;
+  let file: ManifestFile | null = null;
+
+  // Find the metadata file owner. For prefix matches, iterate all matching
+  // segments in priority order — when competing bare-dynamic groups match
+  // the same prefix, the first may not own the file. For root-level matches,
+  // search all group children since findMetadataRouteInSegment may return
+  // a file with the wrong extension when multiple groups own the same
+  // convention with different static types.
+  segment = root;
+  params = {};
+  const candidates = [...metadataOwnerCandidates(root, prefixParts)];
+
+  // Two passes: direct owners first (node itself + groups), then
+  // zero-segment optional-catch-all descent. A direct owner across any
+  // candidate must beat a zero-segment catch-all on an earlier candidate.
+  for (const allowCatchAll of [false, true]) {
+    for (const candidate of candidates) {
+      if (!convention.nestable && candidate.segment !== root) continue;
+      const found = findMetadataRouteInSegment(
+        candidate.segment,
+        baseName,
+        allowCatchAll && convention.nestable
+      );
+      if (!found) continue;
+      if (convention.serveExtension) {
+        const resolvedServePath = resolveServePathForFile(baseName, found.filePath);
+        if (lastPart !== resolvedServePath) continue;
+      }
+      segment = candidate.segment;
+      params = candidate.params;
+      file = found;
+      break;
+    }
+    if (file) break;
+  }
 
-      // Build the serve pathname: segment urlPath + serve path
-      const prefix = node.urlPath === '/' ? '' : node.urlPath;
-      const pathname = `${prefix}/${convention.servePath}`;
+  if (!file) return null;
 
-      // Determine if this is a static file based on its extension.
-      // Static files (.xml, .txt, .png, .ico, etc.) are served from disk.
-      // Dynamic files (.ts, .tsx) export a handler function.
-      const ext = file.filePath.slice(file.filePath.lastIndexOf('.') + 1);
-      const isStatic = isStaticMetadataExtension(baseName, ext);
+  const ext = file.filePath.slice(file.filePath.lastIndexOf('.') + 1);
+  const isStatic = isStaticMetadataExtension(baseName, ext);
+  const contentType = isStatic
+    ? resolveStaticContentType(convention.contentType, ext)
+    : convention.contentType;
 
-      // Resolve generic content types (e.g. image/*) to concrete MIME types
-      // based on the file extension for static files.
-      const contentType = isStatic
-        ? resolveStaticContentType(convention.contentType, ext)
-        : convention.contentType;
+  return {
+    type: convention.type,
+    contentType,
+    file,
+    segment,
+    isStatic,
+    segmentParams: params,
+  };
+}
 
-      map.set(pathname, {
-        type: convention.type,
-        contentType,
-        file,
-        segment: node,
-        isStatic,
-      });
+/**
+ * Find a metadata route file in a segment, including children that match
+ * zero URL segments at the segment's own path:
+ *
+ * - Group children are transparent — they don't add URL depth.
+ * - Optional catch-all children ([[...slug]]) match zero segments, so
+ *   `app/docs/[[...path]]/icon.tsx` serves `/docs/icon`. The non-zero
+ *   case is handled by the tree walker (requireTerminal:false), but the
+ *   zero-segment case never reaches the walker — the parent node accepts
+ *   the fully-consumed prefix first, so the fallback lives here.
+ *
+ * Optional catch-all descent applies to NESTABLE conventions only. A
+ * non-nestable file (robots, manifest, favicon) inside `[[...slug]]` is
+ * not at the root — serving it there would bypass the root-only rule.
+ * Group descent is unconditional: groups are transparent and a group
+ * child of the root IS at the root.
+ *
+ * The segment's own metadata file wins over a zero-segment child's.
+ */
+function findMetadataRouteInSegment(
+  node: ManifestSegmentNode,
+  baseName: string,
+  nestable: boolean
+): ManifestFile | null {
+  if (node.metadataRoutes?.[baseName]) {
+    return node.metadataRoutes[baseName];
+  }
+  for (const child of node.children) {
+    if (child.segmentType === 'group' || (nestable && child.segmentType === 'optional-catch-all')) {
+      const found = findMetadataRouteInSegment(child, baseName, nestable);
+      if (found) return found;
     }
   }
+  return null;
+}
 
-  for (const child of node.children) {
-    collectMetadataRoutes(child, map);
+/**
+ * Yield candidate owner segments for a metadata route.
+ *
+ * For root-level metadata (empty prefix), yields the root and then each
+ * transparent group child — so extension validation can skip a group that
+ * owns the wrong static type and find the right one. For prefix matches,
+ * delegates to `matchUrlPartsAll` which handles all segment kinds.
+ */
+function* metadataOwnerCandidates(
+  root: ManifestSegmentNode,
+  prefixParts: string[]
+): Generator<{ segment: ManifestSegmentNode; params: Record<string, string | string[]> }> {
+  if (prefixParts.length === 0) {
+    yield { segment: root, params: {} };
+    // Also yield each group child individually so the caller can validate
+    // extensions per-group rather than taking the first file found.
+    for (const child of root.children) {
+      if (child.segmentType === 'group') {
+        yield* groupDescendants(child);
+      }
+    }
+  } else {
+    for (const result of matchUrlPartsAll(root, prefixParts, { requireTerminal: false })) {
+      yield { segment: result.chain[result.chain.length - 1], params: result.params };
+    }
   }
+}
 
-  // Also check inside group segments (they're transparent for URL paths)
-  for (const slotNode of Object.values(node.slots)) {
-    collectMetadataRoutes(slotNode, map);
+function* groupDescendants(
+  node: ManifestSegmentNode
+): Generator<{ segment: ManifestSegmentNode; params: Record<string, string | string[]> }> {
+  yield { segment: node, params: {} };
+  for (const child of node.children) {
+    if (child.segmentType === 'group') {
+      yield* groupDescendants(child);
+    }
   }
 }