@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/routing/collision-spaces.ts

@@ -0,0 +1,281 @@
+/**
+ * Route collision spaces.
+ *
+ * A collision space is a set of routes that compete for URLs with each other,
+ * and there are three: the main tree, each parallel slot, and each intercepting
+ * subtree. This module owns the first two; `interception.ts` owns the third.
+ * All of them decide order-dependence with the one oracle in
+ * `collision-probe.ts`, so they cannot drift on what counts as two routes
+ * answering a single URL.
+ *
+ * See design/07-routing.md §"Route Collisions".
+ */
+
+import type { SegmentNode } from './types.js';
+import { computeInterceptedUrlBase } from './interception.js';
+import { findOrderDependentCollision, type ProbeLeaf } from './collision-probe.js';
+
+/**
+ * Validate that no two pages/routes in one collision space answer the same URL.
+ *
+ * Two route groups like (auth)/login/page.tsx and (marketing)/login/page.tsx both claim
+ * /login — the scanner must detect and reject this at build time.
+ *
+ * Each parallel slot is validated as its OWN collision space: a slot's pages
+ * intentionally share URL paths with the parent tree (that's the point of
+ * parallel routes), but two route groups INSIDE one slot claiming the same
+ * URL — e.g. @side/(a)/x/page.tsx + @side/(b)/x/page.tsx — still collide.
+ */
+export function validateRouteGroupCollisions(root: SegmentNode): void {
+  validateCollisionSpace(root, '', root.urlPath);
+}
+
+/**
+ * Validate one collision space — the main tree, or one parallel slot.
+ *
+ * **Two checks, and the difference between them matters.** Two leaves at the
+ * same `urlPath` are decided by string equality, which is exact and needs no
+ * probing: `(auth)/login` and `(marketing)/login` claim one set of URLs
+ * whatever the precedence rules are, and naming the shared path is the clearest
+ * thing to tell the author.
+ *
+ * Everything else is decided by asking the matcher, through the shared oracle
+ * in `collision-probe.ts` (TIM-1308). Comparing `urlPath` spellings misses
+ * every pair that matches the same URLs while being *spelled* differently:
+ * `x/(a)/[id]` beside `x/(b)/[slug]` are two bare dynamics in one priority
+ * tier, and `x/(a)/page.tsx` beside `x/(b)/[[...rest]]` both answer `/x`
+ * because an optional catch-all also matches zero parts. Both built before
+ * TIM-1308 with filesystem enumeration order deciding which page renders,
+ * which is precisely what this validator and `validateAffixedSiblingConflicts`
+ * exist to reject.
+ *
+ * Segment *kinds* stay distinct without any special-casing here, because the
+ * oracle inherits `matchNode`'s priority ordering: `x/(a)/[id]` beside
+ * `x/(b)/[...rest]` resolves the same way in either `children` order, so it is
+ * not reported. So does an affixed sibling against a bare one; the
+ * equal-specificity affix tie is `validateAffixedSiblingConflicts`' job, and
+ * duplicating it here would double-report.
+ */
+function validateCollisionSpace(spaceRoot: SegmentNode, segmentPath: string, base: string): void {
+  const leaves: ProbeLeaf[] = [];
+  collectRoutableLeaves(spaceRoot, new Map(), segmentPath, [], leaves, base);
+
+  const collision = findOrderDependentCollision(spaceRoot, leaves, base);
+  if (!collision) return;
+
+  throw new Error(
+    `Build error: route collision — two pages/routes answer the same URL.\n` +
+      `  URL:    ${collision.url}\n` +
+      `  File 1: ${collision.first}\n` +
+      `  File 2: ${collision.second}\n` +
+      `Both match it, so which one renders would be decided by filesystem enumeration ` +
+      `order — renaming a route group can flip it. Rename or move one of them.\n` +
+      `Routes are compared by the URLs they match, not by how they are spelled: [id] and ` +
+      `[slug] match the same URLs, and an optional catch-all also matches with zero ` +
+      `segments.`
+  );
+}
+
+/**
+ * Walk one collision space and collect its routable leaves (page or route
+ * files), throwing on an exact `urlPath` collision. Each slot recurses as its
+ * OWN space — slots are parallel routes that intentionally share URL paths with
+ * their parent tree, but collisions within a single slot are real errors.
+ *
+ * The early return at an intercepting node drops that subtree's own pages from
+ * this space, but not its slots: a slot is its own collision space wherever it
+ * sits, so `validateSlotsInsideInterceptingSubtree` picks those up before
+ * returning.
+ *
+ * `chain` accumulates the URL-contributing nodes from the space root down, for
+ * the probe oracle. Route groups are excluded because they are transparent for
+ * matching, and the space root itself is excluded because `matchUrlParts`
+ * matches parts against its *children* — the root consumes nothing.
+ */
+function collectRoutableLeaves(
+  node: SegmentNode,
+  seen: Map<string, { filePath: string; segmentPath: string }>,
+  segmentPath: string,
+  chain: SegmentNode[],
+  leaves: ProbeLeaf[],
+  base: string
+): void {
+  // Intercepting routes are resolved by the interception resolvers, not URL
+  // matching, and their computed urlPaths are not addresses — an interception
+  // mirrors the canonical route it replaces, so comparing those paths here
+  // would reject every correct interception. Skipping is not "unvalidated":
+  // `assertNoInterceptedPatternCollisions` gives each intercepting subtree its
+  // own collision space, keyed by the intercepted pattern rather than by these
+  // paths (TIM-1305). See design/07-routing.md §"Collisions Inside an
+  // Intercepting Subtree" and §"Why urlPath Stays Parent-Relative Inside an
+  // Intercepting Subtree".
+  const currentPath = segmentPath
+    ? `${segmentPath}/${node.segmentName}`
+    : node.segmentName || '(root)';
+
+  // The intercepting subtree's own pages leave this space — but its SLOTS do
+  // not leave every space, so they are picked up before returning. See
+  // `validateSlotsInsideInterceptingSubtree`.
+  if (node.segmentType === 'intercepting') {
+    // `node.urlPath` on an intercepting node is its OWNER's path — the input
+    // `computeInterceptedUrlBase` wants — because an intercepting segment adds
+    // no URL depth.
+    validateSlotsInsideInterceptingSubtree(
+      node,
+      currentPath,
+      interceptedBaseOf(node, node.urlPath)
+    );
+    return;
+  }
+
+  const routableFile = node.page ?? node.route;
+  if (routableFile) {
+    const existing = seen.get(node.urlPath);
+    if (existing) {
+      throw new Error(
+        `Build error: route collision — multiple route groups produce a page/route at the same URL path.\n` +
+          `  URL path: ${urlFromChain(base, chain)}\n` +
+          `  File 1:   ${existing.filePath} (via ${existing.segmentPath})\n` +
+          `  File 2:   ${routableFile.filePath} (via ${currentPath})\n` +
+          `Each URL path must map to exactly one page or route handler. ` +
+          `Rename or move one of the conflicting files.`
+      );
+    }
+    seen.set(node.urlPath, { filePath: routableFile.filePath, segmentPath: currentPath });
+    leaves.push({ filePath: routableFile.filePath, chain });
+  }
+
+  // Recurse into children. A route group contributes no URL part, so it is
+  // absent from the chain — exactly as `collectEffectiveChildren` flattens it
+  // away in the matcher.
+  for (const child of node.children) {
+    const isGroup = child.segmentType === 'group';
+    collectRoutableLeaves(
+      child,
+      seen,
+      currentPath,
+      isGroup ? chain : [...chain, child],
+      leaves,
+      base
+    );
+  }
+
+  // Recurse into slots — each slot is its own collision space, with its own
+  // seen map, its own leaf set and its own probe run.
+  //
+  // The base is accumulated from this space's own base rather than read off
+  // `slotNode.urlPath`, because this walk also runs on slot spaces nested inside
+  // an intercepting subtree, where `urlPath` is parent-relative and not an
+  // address. Outside one the two are identical by construction.
+  for (const slotNode of Object.values(node.slots)) {
+    validateCollisionSpace(slotNode, currentPath, urlFromChain(base, chain));
+  }
+}
+
+/**
+ * Validate every parallel slot nested anywhere inside an intercepting subtree.
+ *
+ * Two walks each skip these slots for their own good reason, and together they
+ * left them checked by nothing: `collectRoutableLeaves` returns at the
+ * intercepting node before it reaches them, and `walkInterceptedLeaves`
+ * deliberately does not descend slots — correct for rewrite generation, since a
+ * slot inside an intercepting subtree produces no rewrite. But "produces no
+ * rewrite" answers the rewrite question and not the resolution one, so
+ * `@side/(a)/x/page.tsx` beside `@side/(b)/x/page.tsx` under an interceptor
+ * built with filesystem order picking the page — the ordinary per-slot
+ * collision that fails the build anywhere else in the tree (codex, on PR #1002).
+ *
+ * A slot is its own collision space wherever it sits, so each one is validated
+ * as one.
+ *
+ * **Which interception shape this still applies to.** TIM-1311 answered the
+ * question this was written under — whether such a slot renders at all — and
+ * the answer is per-shape:
+ *
+ * - **Children path** (`(browse)/(...)photo/@side`): the intercepting node
+ *   joins the main route chain, so `route-element-builder.ts` resolves slots on
+ *   it and below it like any other chain segment. They render, and this is the
+ *   space where the check is load-bearing.
+ * - **Modal** (`feed/@modal/(.)photo/@side`): the slot sits inside another
+ *   slot's subtree, which no renderer descends for slots — so it never renders,
+ *   and `validateSlotPlacement` now rejects the placement before this runs.
+ *   That rule subsumes this one for the modal shape rather than conflicting
+ *   with it, exactly as anticipated.
+ *
+ * So this walk is reached only for children-path interceptors in a valid tree.
+ * It is not narrowed to them: the rule it states — a slot is its own collision
+ * space wherever it sits — is shape-independent, and making it conditional on a
+ * property the placement validator already guarantees would just be a second
+ * place for the two to disagree.
+ *
+ * The walk covers the whole subtree, not just the interceptor's direct slot
+ * children: `(...)photo/[id]/@side` is reached by neither walk for exactly the
+ * same reason as `(...)photo/@side`.
+ */
+function validateSlotsInsideInterceptingSubtree(
+  node: SegmentNode,
+  segmentPath: string,
+  base: string
+): void {
+  for (const slotNode of Object.values(node.slots)) {
+    // A slot adds no URL depth, so it answers its owner's base.
+    validateCollisionSpace(slotNode, segmentPath, base);
+  }
+  for (const child of node.children) {
+    validateSlotsInsideInterceptingSubtree(
+      child,
+      `${segmentPath}/${child.segmentName}`,
+      childInterceptedBase(child, base)
+    );
+  }
+}
+
+/**
+ * The URL a leaf answers, built from its space's base and its own chain.
+ *
+ * Read instead of `node.urlPath` because `urlPath` inside an intercepting
+ * subtree is parent-relative and is not an address — the collision URL has to
+ * be one the author can actually find. Outside an intercepting subtree the two
+ * are identical by construction: the base is the space root's `urlPath` and the
+ * chain is every URL-contributing segment below it.
+ */
+function urlFromChain(base: string, chain: SegmentNode[]): string {
+  if (chain.length === 0) return base || '/';
+  const tail = chain.map((n) => n.segmentName).join('/');
+  return `${base === '/' ? '' : base}/${tail}`;
+}
+
+/**
+ * The intercepted URL an intercepting directory's own page sits at.
+ *
+ * `urlPath` inside an intercepting subtree is deliberately parent-relative and
+ * is **not** an address (see design/07-routing.md §"Why urlPath Stays
+ * Parent-Relative Inside an Intercepting Subtree"), so a collision reported
+ * from one names a URL the author cannot find. The intercepted base is the real
+ * address, and it is what rewrite generation and the interception collision
+ * validator both already use.
+ */
+function interceptedBaseOf(node: SegmentNode, ownerUrlPath: string): string {
+  return computeInterceptedUrlBase(
+    ownerUrlPath,
+    node.interceptionMarker ?? '(.)',
+    node.interceptedSegmentName ?? node.segmentName
+  );
+}
+
+/**
+ * Extend an intercepted base by one child segment.
+ *
+ * Route groups are transparent and contribute nothing. A nested intercepting
+ * node re-bases from its own marker rather than appending — that tree is
+ * rejected by `validateInterceptionPlacement`, but collision validation runs
+ * first, so it still has to produce a sensible URL rather than one containing a
+ * literal "(.)b".
+ */
+function childInterceptedBase(child: SegmentNode, base: string): string {
+  // Slots are not in `children` — `scanChildren` files them under `slots` — so
+  // only groups are transparent here.
+  if (child.segmentType === 'group') return base;
+  if (child.segmentType === 'intercepting') return interceptedBaseOf(child, base);
+  return base === '/' ? `/${child.segmentName}` : `${base}/${child.segmentName}`;
+}

package/src/routing/convention-lint.ts

@@ -4,17 +4,25 @@
  * Runs at scan time (build and dev startup). Each check produces a warning
  * with the file path, what's wrong, and what to do about it.
  *
- * These are warnings, not errors — they don't block the build. The goal is
- * to catch issues that would otherwise produce cryptic runtime behavior
- * (silent 404s, empty pages, confusing React errors).
+ * Most checks are warnings — they don't block the build. The goal is to catch
+ * issues that would otherwise produce cryptic runtime behavior (silent 404s,
+ * empty pages, confusing React errors).
+ *
+ * A check emits `level: 'error'` only when the misconfiguration is *proven*
+ * (never inferred from an absence the analysis cannot see through) and fatal
+ * to rendering. `plugins/routing.ts` turns those into a thrown build error,
+ * so a false positive there refuses a working app — see
+ * `classifyClientBoundaryFile` for how that bar is met.
  *
  * Design doc: 07-routing.md, 10-error-handling.md
  */
 
 import { existsSync } from 'node:fs';
-import type { RouteTree, SegmentNode } from './types.js';
+import type { RouteFile, RouteTree, SegmentNode } from './types.js';
 import { swallow } from '../server/logger.js';
+import { isMdxFilePath } from '../server/utils/mdx-file.js';
 import {
+  fileDefaultExportIsLocalValue,
   fileHasAnyExport,
   fileHasDefaultExport,
   fileHasDirective,
@@ -61,10 +69,10 @@ export function lintConventions(tree: RouteTree, appDir: string): ConventionWarn
   // Check 5: page.tsx / layout.tsx without default export
   checkDefaultExports(tree.root, warnings);
 
-  // Check 6: error.tsx / global-error.tsx without 'use client' directive
-  checkErrorDirectives(tree.root, warnings);
-  if (tree.globalError && isScriptExtension(tree.globalError.extension)) {
-    checkFileUseClientDirective(tree.globalError.filePath, 'global-error', warnings);
+  // Check 6: error.tsx / 404.tsx / 4xx.tsx / … without 'use client' directive
+  checkClientBoundaryFiles(tree.root, warnings);
+  if (tree.globalError) {
+    checkFileUseClientDirective(tree.globalError, 'global-error', warnings);
   }
 
   return warnings;
@@ -272,54 +280,132 @@ function checkFileDefaultExport(
   }
 }
 
-// ─── Check: Error Directive ─────────────────────────────────────────────────
+// ─── Check: Client Boundary Directive ───────────────────────────────────────
 
 /**
- * Warn when error.tsx or global-error.tsx is missing 'use client'.
+ * Check every file the renderer hands to `TimberErrorBoundary` as a component
+ * prop: `error.tsx`, `global-error.tsx`, and the status-code family
+ * (`404.tsx`, `4xx.tsx`, `503.tsx`, …).
+ *
+ * `TimberErrorBoundary` is a client component, so a server component passed as
+ * `fallbackComponent` is a function crossing the RSC → client boundary. React
+ * Flight refuses to serialize it, and because the boundary wraps the segment's
+ * *children*, the failure hits every page under that segment — not just the
+ * error path. The raw message ("Functions cannot be passed directly to Client
+ * Components") names neither the file nor the fix (TIM-1329).
  *
- * React's error boundary API requires client components. Without the directive,
- * the error boundary silently fails — the component renders as a server component
- * with no error catching. Users discover this only via cryptic runtime errors.
+ * MDX status files are exempt: they are server components by design and the
+ * renderer pre-renders them into `fallbackElement` instead. See TIM-503 and
+ * `server/error-boundary-wrapper.ts`.
+ *
+ * `.json` status files never reach React at all, and are not in `statusFiles`.
  */
-function checkErrorDirectives(node: SegmentNode, warnings: ConventionWarning[]): void {
-  if (node.error && isScriptExtension(node.error.extension)) {
-    checkFileUseClientDirective(node.error.filePath, 'error', warnings);
+function checkClientBoundaryFiles(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.error) {
+    checkFileUseClientDirective(node.error, 'error', warnings);
+  }
+
+  for (const [key, file] of Object.entries(node.statusFiles ?? {})) {
+    checkFileUseClientDirective(file, key, warnings);
   }
 
   for (const child of node.children) {
-    checkErrorDirectives(child, warnings);
+    checkClientBoundaryFiles(child, warnings);
   }
   for (const slot of Object.values(node.slots)) {
-    checkErrorDirectives(slot, warnings);
+    checkClientBoundaryFiles(slot, warnings);
   }
 }
 
+/**
+ * `'client'` — carries the directive.
+ * `'server'` — proven server component: no directive, and the default export is
+ *   a function or class built by this very module, so no other file's directive
+ *   can be governing it.
+ * `'unknown'` — no directive, but the exported value may come from elsewhere
+ *   (`export { default } from './client-thing'`), or the file could not be
+ *   read or parsed. Never escalated to a build error.
+ */
+type ClientBoundaryVerdict = 'client' | 'server' | 'unknown';
+
+function classifyClientBoundaryFile(filePath: string): ClientBoundaryVerdict {
+  if (fileHasDirective(filePath, 'use client')) return 'client';
+  if (fileDefaultExportIsLocalValue(filePath)) return 'server';
+  return 'unknown';
+}
+
+/** Example component name for the fix snippet, keyed by convention name. */
+function exampleComponentName(convention: string): string {
+  if (convention === 'global-error') return 'GlobalError';
+  if (convention === 'error') return 'ErrorBoundary';
+  if (convention === '404') return 'NotFound';
+  return 'StatusPage';
+}
+
+/**
+ * @param file      the route file (its extension decides whether the check applies)
+ * @param convention the convention name — `error`, `global-error`, `404`, `4xx`, …
+ */
 function checkFileUseClientDirective(
-  filePath: string,
-  fileType: string,
+  file: RouteFile,
+  convention: string,
   warnings: ConventionWarning[]
 ): void {
+  // MDX/markdown status and error files are server components by design — the
+  // renderer pre-renders them into `fallbackElement`, so they never cross the
+  // boundary as a function.
+  //
+  // The exemption is the *complement* of the renderer's own test, using the
+  // renderer's own helper: everything `error-boundary-wrapper.ts` and
+  // `error-renderer.ts` do not treat as MDX, they pass as a component. An
+  // independent "is this a script extension?" list here would be a second
+  // expression of that fact, free to drift into a gap where a file is a
+  // component to the renderer and exempt to the linter.
+  if (isMdxFilePath(file.filePath)) return;
+
+  const filePath = file.filePath;
+  const label = `${convention}.${file.extension}`;
+  let verdict: ClientBoundaryVerdict;
   try {
-    if (!fileHasDirective(filePath, 'use client')) {
-      warnings.push({
-        id: `ERROR_NO_USE_CLIENT:${filePath}`,
-        summary: `${fileType}.tsx is missing 'use client': ${filePath}`,
-        details:
-          `  File: ${filePath}\n\n` +
-          `  ${fileType}.tsx must start with 'use client' because React error\n` +
-          '  boundaries require client components. Without it, the error boundary\n' +
-          '  silently fails and errors are uncaught.\n\n' +
-          "  To fix: Add 'use client' as the first line of the file:\n\n" +
-          "    'use client';\n\n" +
-          `    export default function ${fileType === 'global-error' ? 'GlobalError' : 'ErrorBoundary'}({ error, reset }) {\n` +
-          '      return <div><h2>Something went wrong</h2><button onClick={reset}>Try again</button></div>;\n' +
-          '    }\n',
-        level: 'warn',
-      });
-    }
+    verdict = classifyClientBoundaryFile(filePath);
   } catch (err) {
-    swallow(err, `convention-lint: unreadable ${fileType} file ${filePath}`);
+    swallow(err, `convention-lint: unreadable ${label} file ${filePath}`);
+    return;
   }
+  if (verdict === 'client') return;
+
+  const isError = verdict === 'server';
+  const name = exampleComponentName(convention);
+  const props =
+    convention === 'error' || convention === 'global-error' ? '{ error, reset }' : '{ status }';
+
+  warnings.push({
+    id: `NEEDS_USE_CLIENT:${filePath}`,
+    summary: isError
+      ? `${label} is a server component and must be a client component: ${filePath}`
+      : `${label} may be missing 'use client': ${filePath}`,
+    details:
+      `  File: ${filePath}\n\n` +
+      `  ${label} is handed to timber's error boundary — a client\n` +
+      '  component — as a prop. A server component cannot cross that boundary:\n' +
+      '  React fails with "Functions cannot be passed directly to Client\n' +
+      '  Components", and every page under this segment fails to render.\n\n' +
+      (isError
+        ? "  To fix: Add 'use client' as the first line of the file:\n\n" +
+          "    'use client';\n\n" +
+          `    export default function ${name}(${props}) {\n` +
+          '      return <h1>…</h1>;\n' +
+          '    }\n'
+        : // The default export comes from somewhere this analysis cannot follow
+          // — a re-export, an imported binding, a wrapper call. It may well
+          // already be a client component, so say what was checked rather than
+          // assert a break.
+          "  This file has no 'use client' directive, and its default export\n" +
+          '  comes from elsewhere, so timber cannot tell which it is. If the\n' +
+          "  module it re-exports starts with 'use client', nothing is wrong\n" +
+          '  and you can ignore this. Otherwise add the directive there.\n'),
+    level: isError ? 'error' : 'warn',
+  });
 }
 
 // ─── Check: App Directory Exists ────────────────────────────────────────────
@@ -352,14 +438,27 @@ import { styleText } from 'node:util';
 
 type Format = InspectColor | readonly InspectColor[];
 const noValidate = { validateStream: false } as const;
-const style = (fmt: Format, text: string) => styleText(fmt, text, noValidate);
+
+export interface FormatOptions {
+  /**
+   * Emit ANSI escapes. Off when the text becomes an `Error` message —
+   * whoever prints it decides its formatting, and colored escapes inside
+   * an exception leak into logs and stack traces.
+   */
+  color?: boolean;
+}
 
 /**
  * Format warnings for terminal output.
  *
  * Groups by severity, uses colors, and includes fix suggestions.
  */
-export function formatConventionWarnings(warnings: ConventionWarning[]): string {
+export function formatConventionWarnings(
+  warnings: ConventionWarning[],
+  options: FormatOptions = {}
+): string {
+  const { color = true } = options;
+  const style = (fmt: Format, text: string) => (color ? styleText(fmt, text, noValidate) : text);
   if (warnings.length === 0) return '';
 
   const errors = warnings.filter((w) => w.level === 'error');