@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.120

package/src/routing/scanner.ts

@@ -18,8 +18,10 @@ import type {
   ScannerConfig,
   InterceptionMarker,
 } from './types.js';
-import { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
-import { classifyMetadataRoute, isDynamicMetadataExtension } from '#/server/metadata-routes.js';
+import { classifySegment } from './segment-classify.js';
+import { DEFAULT_PAGE_EXTENSIONS } from './types.js';
+import { classifyMetadataRoute, isDynamicMetadataExtension } from '../server/metadata-routes.js';
+import { swallow } from '../server/logger.js';
 
 /**
  * Pattern matching encoded path delimiters that must be rejected during route discovery.
@@ -53,7 +55,7 @@ const LEGACY_STATUS_FILES: Record<string, number> = {
 /**
  * File convention names that are always .ts/.tsx (never .mdx etc.)
  */
-const FIXED_CONVENTIONS = new Set(['middleware', 'access', 'route', 'prerender', 'search-params']);
+const FIXED_CONVENTIONS = new Set(['middleware', 'access', 'route', 'params']);
 
 /**
  * Status-code file patterns:
@@ -83,6 +85,14 @@ export function scanRoutes(appDir: string, config: ScannerConfig = {}): RouteTre
     tree.proxy = proxyFile;
   }
 
+  // Check for global-error.{tsx,ts,jsx,js} at app root.
+  // Tier 2 error page — renders standalone (no layouts) when no segment-level
+  // error file is found. See design/10-error-handling.md §"Tier 2".
+  const globalErrorFile = findPageExtFile(appDir, 'global-error', extSet);
+  if (globalErrorFile) {
+    tree.globalError = globalErrorFile;
+  }
+
   // Scan the root directory's files
   scanSegmentFiles(appDir, tree.root, extSet);
 
@@ -92,6 +102,10 @@ export function scanRoutes(appDir: string, config: ScannerConfig = {}): RouteTre
   // Validate: detect route group collisions (different groups producing pages at the same URL)
   validateRouteGroupCollisions(tree.root);
 
+  // Validate: detect duplicate param names in nested dynamic segments
+  // e.g., /[id]/items/[id] — same param name in ancestor and descendant
+  validateDuplicateParamNames(tree.root);
+
   return tree;
 }
 
@@ -114,96 +128,10 @@ function createSegmentNode(
     interceptionMarker,
     interceptedSegmentName,
     children: [],
-    slots: new Map(),
+    slots: {},
   };
 }
 
-/**
- * Classify a directory name into its segment type.
- */
-export function classifySegment(dirName: string): {
-  type: SegmentType;
-  paramName?: string;
-  interceptionMarker?: InterceptionMarker;
-  interceptedSegmentName?: string;
-} {
-  // Private folder: _name (excluded from routing)
-  if (dirName.startsWith('_')) {
-    return { type: 'private' };
-  }
-
-  // Parallel route slot: @name
-  if (dirName.startsWith('@')) {
-    return { type: 'slot' };
-  }
-
-  // Intercepting routes: (.)name, (..)name, (...)name, (..)(..)name
-  // Check before route groups since intercepting markers also start with (
-  const interception = parseInterceptionMarker(dirName);
-  if (interception) {
-    return {
-      type: 'intercepting',
-      interceptionMarker: interception.marker,
-      interceptedSegmentName: interception.segmentName,
-    };
-  }
-
-  // Route group: (name)
-  if (dirName.startsWith('(') && dirName.endsWith(')')) {
-    return { type: 'group' };
-  }
-
-  // Optional catch-all: [[...name]]
-  if (dirName.startsWith('[[...') && dirName.endsWith(']]')) {
-    const paramName = dirName.slice(5, -2);
-    return { type: 'optional-catch-all', paramName };
-  }
-
-  // Catch-all: [...name]
-  if (dirName.startsWith('[...') && dirName.endsWith(']')) {
-    const paramName = dirName.slice(4, -1);
-    return { type: 'catch-all', paramName };
-  }
-
-  // Dynamic: [name]
-  if (dirName.startsWith('[') && dirName.endsWith(']')) {
-    const paramName = dirName.slice(1, -1);
-    return { type: 'dynamic', paramName };
-  }
-
-  return { type: 'static' };
-}
-
-/**
- * Parse an interception marker from a directory name.
- *
- * Returns the marker and the remaining segment name, or null if not an
- * intercepting route. Markers are checked longest-first to avoid (..)
- * matching before (..)(..).
- *
- * Examples:
- *   "(.)photo"      → { marker: "(.)", segmentName: "photo" }
- *   "(..)feed"      → { marker: "(..)", segmentName: "feed" }
- *   "(...)photos"   → { marker: "(...)", segmentName: "photos" }
- *   "(..)(..)admin" → { marker: "(..)(..)", segmentName: "admin" }
- *   "(marketing)"   → null (route group, not interception)
- */
-function parseInterceptionMarker(
-  dirName: string
-): { marker: InterceptionMarker; segmentName: string } | null {
-  for (const marker of INTERCEPTION_MARKERS) {
-    if (dirName.startsWith(marker)) {
-      const rest = dirName.slice(marker.length);
-      // Must have a segment name after the marker, and the rest must not
-      // be empty or end with ) (which would be a route group like "(auth)")
-      if (rest.length > 0 && !rest.endsWith(')')) {
-        return { marker, segmentName: rest };
-      }
-    }
-  }
-  return null;
-}
-
 /**
  * Compute the URL path for a child segment given its parent's URL path.
  * Route groups, slots, and intercepting routes do NOT add URL depth.
@@ -225,7 +153,8 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
   let entries: string[];
   try {
     entries = readdirSync(dirPath);
-  } catch {
+  } catch (err) {
+    swallow(err, `scanSegmentFiles: unreadable directory ${dirPath}`, { level: 'warn' });
     return;
   }
 
@@ -278,11 +207,8 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
         case 'route':
           node.route = file;
           break;
-        case 'prerender':
-          node.prerender = file;
-          break;
-        case 'search-params':
-          node.searchParams = file;
+        case 'params':
+          node.params = file;
           break;
       }
       continue;
@@ -292,27 +218,27 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
     // Recognized regardless of pageExtensions — .json is a data format, not a page extension.
     if (STATUS_CODE_PATTERN.test(name) && ext === 'json') {
       if (!node.jsonStatusFiles) {
-        node.jsonStatusFiles = new Map();
+        node.jsonStatusFiles = {};
       }
-      node.jsonStatusFiles.set(name, { filePath: fullPath, extension: ext });
+      node.jsonStatusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
 
     // Status-code files (401.tsx, 4xx.tsx, 503.tsx, 5xx.tsx)
     if (STATUS_CODE_PATTERN.test(name) && extSet.has(ext)) {
       if (!node.statusFiles) {
-        node.statusFiles = new Map();
+        node.statusFiles = {};
       }
-      node.statusFiles.set(name, { filePath: fullPath, extension: ext });
+      node.statusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
 
     // Legacy compat files (not-found.tsx, forbidden.tsx, unauthorized.tsx)
     if (name in LEGACY_STATUS_FILES && extSet.has(ext)) {
       if (!node.legacyStatusFiles) {
-        node.legacyStatusFiles = new Map();
+        node.legacyStatusFiles = {};
       }
-      node.legacyStatusFiles.set(name, { filePath: fullPath, extension: ext });
+      node.legacyStatusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
 
@@ -323,19 +249,19 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
     const metaInfo = classifyMetadataRoute(entry);
     if (metaInfo) {
       if (!node.metadataRoutes) {
-        node.metadataRoutes = new Map();
+        node.metadataRoutes = {};
       }
-      const existing = node.metadataRoutes.get(name);
+      const existing = node.metadataRoutes[name];
       if (existing) {
         // Dynamic > static precedence: only overwrite if the new file is dynamic
         // or the existing file is static (dynamic always wins).
         const existingIsDynamic = isDynamicMetadataExtension(name, existing.extension);
         const newIsDynamic = isDynamicMetadataExtension(name, ext);
         if (newIsDynamic || !existingIsDynamic) {
-          node.metadataRoutes.set(name, { filePath: fullPath, extension: ext });
+          node.metadataRoutes[name] = { filePath: fullPath, extension: ext };
         }
       } else {
-        node.metadataRoutes.set(name, { filePath: fullPath, extension: ext });
+        node.metadataRoutes[name] = { filePath: fullPath, extension: ext };
       }
     }
   }
@@ -358,7 +284,8 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
   let entries: string[];
   try {
     entries = readdirSync(dirPath);
-  } catch {
+  } catch (err) {
+    swallow(err, `scanChildren: unreadable directory ${dirPath}`, { level: 'warn' });
     return;
   }
 
@@ -412,10 +339,10 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
     // Recurse into subdirectories
     scanChildren(fullPath, childNode, extSet);
 
-    // Attach to parent: slots go into slots map, everything else is a child
+    // Attach to parent: slots go into slots record, everything else is a child
     if (type === 'slot') {
       const slotName = entry.slice(1); // remove @
-      parentNode.slots.set(slotName, childNode);
+      parentNode.slots[slotName] = childNode;
     } else {
       parentNode.children.push(childNode);
     }
@@ -477,11 +404,59 @@ function collectRoutableLeaves(
   }
 
   // Recurse into slots — each slot is its own parallel route space
-  for (const [, slotNode] of node.slots) {
+  for (const slotNode of Object.values(node.slots)) {
     collectRoutableLeaves(slotNode, seen, currentPath, true);
   }
 }
 
+/**
+ * Validate that no route chain contains duplicate dynamic param names.
+ *
+ * Example violation:
+ *   app/[id]/items/[id]/page.tsx — 'id' appears twice in the ancestor chain.
+ *
+ * Route groups are transparent — params accumulate through them.
+ * Slots are independent — duplicate detection does NOT cross slot boundaries.
+ *
+ * See design/07-routing.md §"Duplicate Param Name Detection"
+ */
+function validateDuplicateParamNames(root: SegmentNode): void {
+  walkForDuplicateParams(root, new Map());
+}
+
+/**
+ * Recursively walk the segment tree, tracking seen param names → segment paths.
+ * Throws on the first duplicate found.
+ */
+function walkForDuplicateParams(node: SegmentNode, seen: Map<string, string>): void {
+  // If this node introduces a param name, check for duplicates
+  if (node.paramName) {
+    const existing = seen.get(node.paramName);
+    if (existing) {
+      throw new Error(
+        `[timber] Duplicate param name '${node.paramName}' in route chain.\n` +
+          `  First defined at: ${existing}\n` +
+          `  Duplicate at: ${node.urlPath || '/'}\n` +
+          `  Rename one of the segments to avoid ambiguity.`
+      );
+    }
+    // Add to seen for descendants (use a new Map to avoid polluting siblings)
+    seen = new Map(seen);
+    seen.set(node.paramName, node.urlPath || '/');
+  }
+
+  // Recurse into children (they inherit the accumulated params)
+  for (const child of node.children) {
+    walkForDuplicateParams(child, seen);
+  }
+
+  // Slots are independent parallel routes — start fresh param tracking
+  // (a slot's params don't conflict with the main route's params)
+  for (const slotNode of Object.values(node.slots)) {
+    walkForDuplicateParams(slotNode, new Map(seen));
+  }
+}
+
 /**
  * Find a fixed-extension file (proxy.ts) in a directory.
  */
@@ -498,3 +473,25 @@ function findFixedFile(dirPath: string, name: string): RouteFile | undefined {
   }
   return undefined;
 }
+
+/**
+ * Find a file using the configured page extensions (tsx, ts, jsx, js, mdx, etc.).
+ * Used for app-root conventions like global-error that aren't per-segment.
+ */
+function findPageExtFile(
+  dirPath: string,
+  name: string,
+  extSet: Set<string>
+): RouteFile | undefined {
+  for (const ext of extSet) {
+    const fullPath = join(dirPath, `${name}.${ext}`);
+    try {
+      if (statSync(fullPath).isFile()) {
+        return { filePath: fullPath, extension: ext };
+      }
+    } catch {
+      // File doesn't exist
+    }
+  }
+  return undefined;
+}

package/src/routing/segment-classify.ts

@@ -0,0 +1,188 @@
+/**
+ * Shared segment classifier — both URL tokens and filesystem directory names.
+ *
+ * `classifyUrlSegment(token)` is a pure single-pass character parser that
+ * classifies a route segment token (e.g. "dashboard", "[id]", "[...slug]",
+ * "[[...path]]") into a typed discriminated union. NO regex, NO Node.js-only
+ * APIs — safe to import from browser code (used by `Link` interpolation).
+ *
+ * `classifySegment(dirName)` is the build-time directory-name classifier
+ * used by the scanner. It recognizes timber-only conventions (private
+ * `_*`, parallel `@*`, route groups `(name)`, intercepting routes
+ * `(.)`/`(..)`/`(...)`/`(..)(..)`) and delegates bracket syntax to
+ * `classifyUrlSegment`. It is the **single source of truth** for what
+ * counts as a routing segment — there is no separate copy in the
+ * scanner. (TIM-848.)
+ *
+ * Malformed input falls through to `{ kind: 'static' }` — the safe default.
+ *
+ * If you change the bracket syntax, update ONLY this file. Every
+ * consumer imports from here.
+ *
+ * See design/07-routing.md §"Route Segments"
+ */
+
+import type { InterceptionMarker, SegmentType } from './types.js';
+import { INTERCEPTION_MARKERS } from './types.js';
+
+export type UrlSegment =
+  | { kind: 'static'; value: string }
+  | { kind: 'dynamic'; name: string }
+  | { kind: 'catch-all'; name: string }
+  | { kind: 'optional-catch-all'; name: string };
+
+/**
+ * Classify a URL path segment token.
+ *
+ * Walks the string left-to-right in one pass:
+ *   1. If it doesn't start with '[', it's static.
+ *   2. Count opening brackets (1 or 2) to detect optional.
+ *   3. Check for '...' to detect catch-all.
+ *   4. Read the param name up to the closing bracket.
+ *   5. Validate the expected closing sequence (']' or ']]').
+ *   6. Reject if there are leftover characters after the close.
+ *
+ * Any structural violation → static (safe default).
+ */
+export function classifyUrlSegment(token: string): UrlSegment {
+  const len = token.length;
+
+  // Must start with '[' to be dynamic
+  if (len === 0 || token[0] !== '[') {
+    return { kind: 'static', value: token };
+  }
+
+  let i = 1;
+
+  // Check for optional: '[[...'
+  const optional = token[i] === '[';
+  if (optional) i++;
+
+  // Check for catch-all: '...'
+  const catchAll = i + 2 < len && token[i] === '.' && token[i + 1] === '.' && token[i + 2] === '.';
+  if (catchAll) i += 3;
+
+  // Read param name — everything up to ']'
+  const nameStart = i;
+  while (i < len && token[i] !== ']') i++;
+
+  // Must have found a ']' and name must be non-empty
+  if (i >= len || i === nameStart) {
+    return { kind: 'static', value: token };
+  }
+
+  const name = token.slice(nameStart, i);
+  i++; // skip first ']'
+
+  // Optional requires a second ']'
+  if (optional) {
+    if (i >= len || token[i] !== ']') {
+      return { kind: 'static', value: token };
+    }
+    i++;
+  }
+
+  // Must be at end of string — no trailing characters
+  if (i !== len) {
+    return { kind: 'static', value: token };
+  }
+
+  if (optional && catchAll) return { kind: 'optional-catch-all', name };
+  if (catchAll) return { kind: 'catch-all', name };
+  if (optional) {
+    // '[[name]]' without '...' is malformed — not a valid segment syntax
+    return { kind: 'static', value: token };
+  }
+  return { kind: 'dynamic', name };
+}
+
+// ─── Directory-name classifier (build-time scanner) ─────────────────────────
+
+/** Result of classifying a filesystem directory name. */
+export interface SegmentClassification {
+  type: SegmentType;
+  paramName?: string;
+  interceptionMarker?: InterceptionMarker;
+  interceptedSegmentName?: string;
+}
+
+/**
+ * Classify a directory name into its segment type.
+ *
+ * Recognizes all timber file-system conventions in priority order:
+ *   1. Private folders: `_name` (excluded from routing)
+ *   2. Parallel route slots: `@name`
+ *   3. Intercepting routes: `(.)name`, `(..)name`, `(...)name`, `(..)(..)name`
+ *   4. Route groups: `(name)`
+ *   5. Bracket syntax: `[id]`, `[...slug]`, `[[...path]]` (delegated to
+ *      `classifyUrlSegment`)
+ *   6. Static: anything else
+ *
+ * If you change the bracket syntax, update only `classifyUrlSegment`.
+ * If you change the directory-prefix conventions, update this function.
+ */
+export function classifySegment(dirName: string): SegmentClassification {
+  // Private folder: _name (excluded from routing)
+  if (dirName.startsWith('_')) {
+    return { type: 'private' };
+  }
+
+  // Parallel route slot: @name
+  if (dirName.startsWith('@')) {
+    return { type: 'slot' };
+  }
+
+  // Intercepting routes: (.)name, (..)name, (...)name, (..)(..)name
+  // Check before route groups since intercepting markers also start with (
+  const interception = parseInterceptionMarker(dirName);
+  if (interception) {
+    return {
+      type: 'intercepting',
+      interceptionMarker: interception.marker,
+      interceptedSegmentName: interception.segmentName,
+    };
+  }
+
+  // Route group: (name)
+  if (dirName.startsWith('(') && dirName.endsWith(')')) {
+    return { type: 'group' };
+  }
+
+  // Bracket-syntax segments: [param], [...param], [[...param]]
+  const urlSeg = classifyUrlSegment(dirName);
+  if (urlSeg.kind !== 'static') {
+    return { type: urlSeg.kind, paramName: urlSeg.name };
+  }
+
+  return { type: 'static' };
+}
+
+/**
+ * Parse an interception marker from a directory name.
+ *
+ * Returns the marker and the remaining segment name, or null if not an
+ * intercepting route. Markers are checked longest-first to avoid `(..)`
+ * matching before `(..)(..)`.
+ *
+ * Examples:
+ *   "(.)photo"      → { marker: "(.)", segmentName: "photo" }
+ *   "(..)feed"      → { marker: "(..)", segmentName: "feed" }
+ *   "(...)photos"   → { marker: "(...)", segmentName: "photos" }
+ *   "(..)(..)admin" → { marker: "(..)(..)", segmentName: "admin" }
+ *   "(marketing)"   → null (route group, not interception)
+ */
+function parseInterceptionMarker(
+  dirName: string
+): { marker: InterceptionMarker; segmentName: string } | null {
+  for (const marker of INTERCEPTION_MARKERS) {
+    if (dirName.startsWith(marker)) {
+      const rest = dirName.slice(marker.length);
+      // Must have a segment name after the marker, and the rest must not
+      // be empty or end with ) (which would be a route group like "(auth)")
+      if (rest.length > 0 && !rest.endsWith(')')) {
+        return { marker, segmentName: rest };
+      }
+    }
+  }
+  return null;
+}

package/src/routing/segment-codegen.ts

@@ -0,0 +1,98 @@
+/**
+ * $segment type generation and directory-to-route mapping.
+ *
+ * Generates per-route $segment.d.ts files in .timber/types/ that mirror
+ * the app/ directory structure. TypeScript's rootDirs feature makes these
+ * importable as './$segment' from route files.
+ *
+ * Design doc: design/41-global-params.md §The $segment Module
+ */
+
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { RouteTree, SegmentNode } from './types.js';
+
+/** Info carried per directory for type generation. */
+export interface SegmentInfo {
+  /** The URL route pattern (groups and slots stripped). e.g. '/[artistSlug]/[year]' */
+  route: string;
+  /** The full tree path including groups and slots — uniquely identifies a segment.
+   *  e.g. '/(browse)/[artistSlug]/@shows/[year]' */
+  segmentPath: string;
+}
+
+/**
+ * Build a map of absolute filesystem directory → segment info.
+ * Used by resolveId to map a $segment import's importer to the correct route,
+ * and by writeSegmentTypes to generate per-route $segment.d.ts files.
+ *
+ * Walks every segment (not just leaves) so layouts and middleware
+ * at any depth can import $segment.
+ */
+export function buildDirToRouteMap(tree: RouteTree, appDir: string): Map<string, SegmentInfo> {
+  const map = new Map<string, SegmentInfo>();
+
+  function walk(node: SegmentNode, fsPath: string, treePath: string): void {
+    map.set(fsPath, {
+      route: node.urlPath || '/',
+      segmentPath: treePath || '/',
+    });
+
+    for (const child of node.children) {
+      const childDir = join(fsPath, child.segmentName);
+      const childTreePath = `${treePath}/${child.segmentName}`;
+      walk(child, childDir, childTreePath);
+    }
+    for (const [slotName, slotNode] of Object.entries(node.slots)) {
+      const slotDir = join(fsPath, `@${slotName}`);
+      const slotTreePath = `${treePath}/@${slotName}`;
+      walk(slotNode, slotDir, slotTreePath);
+    }
+  }
+
+  walk(tree.root, appDir, '');
+  return map;
+}
+
+/**
+ * Generate the full $segment.d.ts content for a segment.
+ */
+export function generateSegmentDts(info: SegmentInfo): string {
+  return [
+    `export const ROUTE: '${info.route}';`,
+    `export const SEGMENT_PATH: '${info.segmentPath}';`,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Generate per-route $segment.d.ts files in .timber/types/ mirroring
+ * the app/ directory structure. These files are importable via TypeScript's
+ * rootDirs feature.
+ */
+export async function writeSegmentTypes(
+  routeTree: RouteTree,
+  appDir: string,
+  root: string
+): Promise<void> {
+  // Compute the relative prefix from project root to appDir.
+  // e.g. if appDir is /project/src/app, relative is 'src/app'
+  const relative = appDir.slice(root.length + 1);
+  const typesBase = join(root, '.timber', 'types', relative);
+  const map = buildDirToRouteMap(routeTree, appDir);
+
+  const writes: Promise<void>[] = [];
+  for (const [fsDir, info] of map) {
+    // Mirror the app/ structure under .timber/types/
+    const relDir = fsDir.slice(appDir.length); // e.g. '/[artistSlug]/[year]'
+    const segmentDir = join(typesBase, relDir);
+    const segmentFile = join(segmentDir, '$segment.d.ts');
+    const content = generateSegmentDts(info);
+
+    writes.push(
+      mkdir(segmentDir, { recursive: true }).then(() => writeFile(segmentFile, content, 'utf-8'))
+    );
+  }
+
+  await Promise.all(writes);
+}