@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/src/routing/schema-validation.ts

@@ -0,0 +1,155 @@
+/**
+ * Schema key/value validation against the filesystem route tree.
+ *
+ * Runs at codegen time (build + dev) to catch mismatches between
+ * app/schema.ts keys and the actual dynamic segments on disk.
+ *
+ * Design doc: design/41-global-params.md
+ */
+
+import { readFileCached } from './file-cache.js';
+import type { RouteTree, SegmentNode } from './types.js';
+import { findSchemaFile, parseExistingSchemaKeys } from '../cli-schema-sync.js';
+import { classifyUrlSegment } from './segment-classify.js';
+
+export interface SchemaWarning {
+  type: 'stale-key' | 'missing-key' | 'bracket-mismatch';
+  key: string;
+  message: string;
+  filesystemKey?: string;
+}
+
+/**
+ * Collect all unique bracket-keyed dynamic segment names from a route tree.
+ * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+ */
+export function collectDynamicSegmentsFromTree(tree: RouteTree): Set<string> {
+  const segments = new Set<string>();
+  walkTree(tree.root, segments);
+  return segments;
+}
+
+function walkTree(node: SegmentNode, segments: Set<string>): void {
+  if (node.paramName && node.segmentName) {
+    const classified = classifyUrlSegment(node.segmentName);
+    if (classified.kind !== 'static') {
+      // Use bare bracket form for schema keys — affixed segments like
+      // `img-[id].png` register as `[id]`, matching runtime codec lookup.
+      if (classified.kind === 'dynamic' && (classified.prefix || classified.suffix)) {
+        segments.add(`[${classified.name}]`);
+      } else {
+        segments.add(node.segmentName);
+      }
+    }
+  }
+  for (const child of node.children) {
+    walkTree(child, segments);
+  }
+  for (const slot of Object.values(node.slots)) {
+    walkTree(slot, segments);
+  }
+}
+
+/**
+ * Extract the param name from a bracket key.
+ * '[id]' → 'id', '[...slug]' → 'slug', '[[...topic]]' → 'topic'
+ */
+function extractParamName(bracketKey: string): string | null {
+  const seg = classifyUrlSegment(bracketKey);
+  if (seg.kind === 'static') return null;
+  return seg.name;
+}
+
+/**
+ * Validate schema keys against the filesystem route tree.
+ *
+ * Returns warnings for:
+ * - Stale keys: schema keys that don't match any filesystem segment
+ * - Bracket form mismatches: same param name, different bracket form
+ * - Missing keys: filesystem segments not registered in schema (informational)
+ */
+export function validateSchemaAgainstRoutes(tree: RouteTree, appDir: string): SchemaWarning[] {
+  const schemaPath = findSchemaFile(appDir);
+  if (!schemaPath) return [];
+
+  const content = readFileCached(schemaPath);
+  const schemaKeys = parseExistingSchemaKeys(content);
+
+  if (schemaKeys.length === 0) return [];
+
+  const filesystemSegments = collectDynamicSegmentsFromTree(tree);
+
+  return validateKeys(schemaKeys, filesystemSegments);
+}
+
+/**
+ * Core validation: compare schema keys against filesystem segments.
+ * Exported separately for testing without filesystem dependencies.
+ */
+export function validateKeys(
+  schemaKeys: string[],
+  filesystemSegments: Set<string>
+): SchemaWarning[] {
+  const warnings: SchemaWarning[] = [];
+
+  // Build a map of param name → bracket form for filesystem segments
+  const fsParamToKey = new Map<string, string>();
+  for (const fsKey of filesystemSegments) {
+    const name = extractParamName(fsKey);
+    if (name) {
+      fsParamToKey.set(name, fsKey);
+    }
+  }
+
+  // Build a set of schema param names for the missing-key check
+  const schemaParamNames = new Set<string>();
+
+  for (const schemaKey of schemaKeys) {
+    const schemaParamName = extractParamName(schemaKey);
+    if (!schemaParamName) continue;
+
+    schemaParamNames.add(schemaParamName);
+
+    if (filesystemSegments.has(schemaKey)) {
+      // Exact match — no issue
+      continue;
+    }
+
+    // Check if the param name exists but with a different bracket form
+    const fsKey = fsParamToKey.get(schemaParamName);
+    if (fsKey) {
+      warnings.push({
+        type: 'bracket-mismatch',
+        key: schemaKey,
+        filesystemKey: fsKey,
+        message:
+          `Schema key '${schemaKey}' does not match filesystem bracket form '${fsKey}'. ` +
+          `Update the schema key to '${fsKey}'.`,
+      });
+    } else {
+      warnings.push({
+        type: 'stale-key',
+        key: schemaKey,
+        message:
+          `Schema key '${schemaKey}' does not match any dynamic segment in the filesystem. ` +
+          `Remove it from app/schema.ts or create the corresponding route segment.`,
+      });
+    }
+  }
+
+  // Check for filesystem segments not in schema (informational)
+  for (const fsKey of filesystemSegments) {
+    const name = extractParamName(fsKey);
+    if (name && !schemaParamNames.has(name)) {
+      warnings.push({
+        type: 'missing-key',
+        key: fsKey,
+        message:
+          `Dynamic segment '${fsKey}' has no codec in app/schema.ts (defaults to string). ` +
+          `Run: timber schema sync`,
+      });
+    }
+  }
+
+  return warnings;
+}

package/src/routing/segment-classify.ts

@@ -0,0 +1,223 @@
+/**
+ * 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; prefix?: string; suffix?: 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. Find the first '[' — characters before it are the prefix.
+ *   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. Characters after the close are the suffix.
+ *   7. Reject affixes on catch-all/optional-catch-all.
+ *   8. Reject affixes that contain '[' or ']' (no multi-param segments).
+ *
+ * Any structural violation → static (safe default).
+ */
+export function classifyUrlSegment(token: string): UrlSegment {
+  const len = token.length;
+  if (len === 0) return { kind: 'static', value: token };
+
+  // Find first '[' — characters before it are the prefix
+  const bracketStart = token.indexOf('[');
+  if (bracketStart === -1) return { kind: 'static', value: token };
+
+  const prefix = token.slice(0, bracketStart);
+
+  let i = bracketStart + 1;
+
+  // Check for optional: '[[...'
+  const optional = i < len && 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++;
+  }
+
+  const suffix = token.slice(i);
+
+  // Reject affixes containing brackets (no multi-param segments like [foo]-[bar])
+  if (suffix.includes('[') || suffix.includes(']')) {
+    return { kind: 'static', value: token };
+  }
+  if (prefix.includes(']')) {
+    return { kind: 'static', value: token };
+  }
+
+  const hasAffixes = prefix.length > 0 || suffix.length > 0;
+
+  if (optional && catchAll) {
+    // No affixes on optional catch-all
+    if (hasAffixes) return { kind: 'static', value: token };
+    return { kind: 'optional-catch-all', name };
+  }
+  if (catchAll) {
+    // No affixes on catch-all
+    if (hasAffixes) return { kind: 'static', value: token };
+    return { kind: 'catch-all', name };
+  }
+  if (optional) {
+    // '[[name]]' without '...' is malformed — not a valid segment syntax
+    return { kind: 'static', value: token };
+  }
+
+  if (hasAffixes) {
+    return {
+      kind: 'dynamic',
+      name,
+      prefix: prefix || undefined,
+      suffix: suffix || undefined,
+    };
+  }
+  return { kind: 'dynamic', name };
+}
+
+// ─── Directory-name classifier (build-time scanner) ─────────────────────────
+
+/** Result of classifying a filesystem directory name. */
+export interface SegmentClassification {
+  type: SegmentType;
+  paramName?: string;
+  paramPrefix?: string;
+  paramSuffix?: 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') {
+    const result: SegmentClassification = { type: urlSeg.kind, paramName: urlSeg.name };
+    if (urlSeg.kind === 'dynamic') {
+      if (urlSeg.prefix) result.paramPrefix = urlSeg.prefix;
+      if (urlSeg.suffix) result.paramSuffix = urlSeg.suffix;
+    }
+    return result;
+  }
+
+  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);
+}

package/src/routing/types.ts

@@ -3,6 +3,23 @@
  *
  * The route tree is built by scanning the app/ directory and recognizing
  * file conventions (page.*, layout.*, middleware.ts, access.ts, route.ts, etc.).
+ *
+ * **Single shape, two specializations** (TIM-848):
+ *
+ * `SegmentNode<TFile>` is the one canonical in-memory shape for the
+ * timber route tree. The same interface is used at build time (with
+ * `TFile = RouteFile`) and at request time (with `TFile = ManifestFile`,
+ * see `server/route-matcher.ts`). Walkers parameterized over `TFile`
+ * work on either, eliminating the previous duplication between
+ * `SegmentNode` (Map-based) and `ManifestSegmentNode` (object-based).
+ *
+ * Keyed groups (`slots`, `statusFiles`, `jsonStatusFiles`,
+ * `legacyStatusFiles`, `metadataRoutes`) are plain `Record<string, …>`
+ * objects rather than `Map`s so that the build-time tree can be
+ * serialized into the virtual route manifest with no shape transform.
+ *
+ * See design/07-routing.md §"Route Tree Shape" and design/18-build-system.md
+ * §"Route Manifest Shape".
  */
 
 /** Segment type classification */
@@ -27,7 +44,14 @@ export type InterceptionMarker = '(.)' | '(..)' | '(...)' | '(..)(..)';
 /** All recognized interception markers, ordered longest-first for parsing. */
 export const INTERCEPTION_MARKERS: InterceptionMarker[] = ['(..)(..)', '(.)', '(..)', '(...)'];
 
-/** A single file discovered in a route segment */
+/**
+ * A single file discovered in a route segment at build time.
+ *
+ * The runtime equivalent (`ManifestFile`, defined in
+ * `server/route-matcher.ts`) replaces `extension` with a lazy `load`
+ * function. Walkers that only need `filePath` are parameterized over
+ * `TFile` and accept either.
+ */
 export interface RouteFile {
   /** Absolute path to the file */
   filePath: string;
@@ -35,14 +59,27 @@ export interface RouteFile {
   extension: string;
 }
 
-/** A node in the segment tree */
-export interface SegmentNode {
+/**
+ * A node in the segment tree.
+ *
+ * Generic over `TFile` so the same interface describes both the
+ * build-time tree (`SegmentNode<RouteFile>`, the default) and the
+ * runtime manifest tree (`SegmentNode<ManifestFile>`, aliased as
+ * `ManifestSegmentNode`). All keyed groups use `Record` (not `Map`)
+ * so the build-time tree serializes to the virtual route manifest
+ * with no shape transform.
+ */
+export interface SegmentNode<TFile = RouteFile> {
   /** The raw directory name (e.g. "dashboard", "[id]", "(auth)", "@sidebar") */
   segmentName: string;
   /** Classified segment type */
   segmentType: SegmentType;
   /** The dynamic param name, if dynamic (e.g. "id" for "[id]", "slug" for "[...slug]") */
   paramName?: string;
+  /** Literal prefix before the dynamic bracket (e.g. "img-" for "img-[id].png") */
+  paramPrefix?: string;
+  /** Literal suffix after the dynamic bracket (e.g. ".png" for "img-[id].png") */
+  paramSuffix?: string;
   /** The URL path prefix at this segment level (e.g. "/dashboard") */
   urlPath: string;
   /** For intercepting segments: the marker used, e.g. "(.)". */
@@ -54,40 +91,60 @@ export interface SegmentNode {
   interceptedSegmentName?: string;
 
   // --- File conventions ---
-  page?: RouteFile;
-  layout?: RouteFile;
-  middleware?: RouteFile;
-  access?: RouteFile;
-  route?: RouteFile;
-  error?: RouteFile;
-  default?: RouteFile;
+  page?: TFile;
+  layout?: TFile;
+  middleware?: TFile;
+  access?: TFile;
+  route?: TFile;
+  /**
+   * params.ts — isomorphic convention file exporting segmentParams and/or searchParams.
+   * Discovered by the scanner like middleware.ts and access.ts.
+   * See design/07-routing.md §"params.ts Convention File"
+   */
+  params?: TFile;
+  error?: TFile;
+  default?: TFile;
   /** Status-code files: 4xx.tsx, 5xx.tsx, {status}.tsx (component format) */
-  statusFiles?: Map<string, RouteFile>;
+  statusFiles?: Record<string, TFile>;
   /** JSON status-code files: 4xx.json, 5xx.json, {status}.json */
-  jsonStatusFiles?: Map<string, RouteFile>;
+  jsonStatusFiles?: Record<string, TFile>;
   /** denied.tsx — slot-only denial rendering */
-  denied?: RouteFile;
+  denied?: TFile;
   /** Legacy compat: not-found.tsx (maps to 404), forbidden.tsx (403), unauthorized.tsx (401) */
-  legacyStatusFiles?: Map<string, RouteFile>;
-  /** prerender.ts — signals build-time pre-rendering for this segment's shell */
-  prerender?: RouteFile;
-  /** search-params.ts — typed search params definition for this route */
-  searchParams?: RouteFile;
+  legacyStatusFiles?: Record<string, TFile>;
+
   /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
-  metadataRoutes?: Map<string, RouteFile>;
+  metadataRoutes?: Record<string, TFile>;
 
   // --- Children ---
-  children: SegmentNode[];
+  children: SegmentNode<TFile>[];
   /** Parallel route slots (keyed by slot name without @) */
-  slots: Map<string, SegmentNode>;
+  slots: Record<string, SegmentNode<TFile>>;
 }
 
-/** The full route tree output from the scanner */
-export interface RouteTree {
+/**
+ * The full route tree output from the scanner (or the root of the
+ * runtime route manifest, when `TFile = ManifestFile`).
+ *
+ * Generic so the same wrapper carries app-root metadata for both
+ * shapes. The runtime manifest extends this with `viteRoot` (see
+ * `ManifestRoot` in `server/route-matcher.ts`).
+ */
+export interface RouteTree<TFile = RouteFile> {
   /** The root segment node (representing app/) */
-  root: SegmentNode;
+  root: SegmentNode<TFile>;
   /** All discovered proxy.ts files (should be at most one, in app/) */
-  proxy?: RouteFile;
+  proxy?: TFile;
+  /**
+   * Global error page: app/global-error.{tsx,ts,jsx,js}
+   *
+   * Rendered as a standalone full-page replacement (no layout wrapping)
+   * when no segment-level error file is found. SSR-only render path.
+   * Must provide its own <html> and <body>.
+   *
+   * See design/10-error-handling.md §"Tier 2 — Global Error Page"
+   */
+  globalError?: TFile;
 }
 
 /** Configuration passed to the scanner */