@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

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.ts';
+import { computeInterceptedUrlBase } from './interception.ts';
+import { findOrderDependentCollision, type ProbeLeaf } from './collision-probe.ts';
+
+/**
+ * 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}`;
+}