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

package/src/routing/collision-probe.ts

@@ -0,0 +1,438 @@
+/**
+ * The order-dependence oracle shared by every route collision validator.
+ *
+ * A "collision space" is a set of pages that compete for URLs with each other:
+ * the main tree, each parallel slot, each intercepting subtree. Two pages in
+ * one space that answer the same URL are ambiguous — `matchNode` resolves the
+ * tie by whichever `children` array lists first, so which page renders is
+ * decided by filesystem enumeration order and renaming a route group can flip
+ * it. Every space rejects that shape, and they all reject it the same way,
+ * through this module.
+ *
+ * **The check asks the real matcher rather than modelling it.** For each leaf
+ * we build a URL it matches, then run `matchUrlParts` twice — once on the
+ * space, once on a clone with every `children` array reversed — and compare the
+ * winners. A URL answered by two or more candidates in the same priority tier
+ * resolves to whichever comes first in `children`, so reversing the arrays
+ * flips it; a URL with a single winner, or one settled by a higher tier, is
+ * unaffected. Order-dependence is therefore detected exactly, with no second
+ * copy of the precedence rules to drift.
+ *
+ * That drift is why this is written as an oracle. The interception validator's
+ * first version normalized each pattern into a "match shape" and compared
+ * shapes, which meant reimplementing `matchNode`'s tiers, its group flattening,
+ * and its zero-length optional-catch-all handling. Five review rounds found
+ * five divergences between the two — param spelling, a zero-length catch-all,
+ * the bracket tokens colliding with legal static directory names, a page
+ * settling a grouped catch-all, and a page settling a *direct* one (which the
+ * model could not express at all, because `matchNode` checks every route-group
+ * page before any direct optional catch-all). Each fix was locally right and
+ * the next divergence surfaced anyway. The model was the defect.
+ *
+ * **Every claim made here is existential** — "here is a URL these two contend
+ * for" — which is what a finite set of probes can actually establish. The
+ * reverse, "this page can never win any URL", is universal, and a probe's
+ * silence is not evidence for it: a leaf that loses every probe may still own
+ * URLs no probe visited. An earlier revision reported that as an
+ * unreachable-page error and produced two false build errors in one review
+ * round. Probe inadequacy must only ever cost a missed collision, never a
+ * rejected app — so nothing here may report a leaf as unreachable.
+ *
+ * See design/07-routing.md §"Comparing Routes by the URLs They Match".
+ */
+
+import type { SegmentNode } from './types.ts';
+import { effectiveUrlSegment } from './segment-classify.ts';
+// The validators ask the real matcher which page answers a URL rather than
+// modelling its precedence rules a second time. `tree-match.ts` is a pure
+// walker over `SegmentNode` with no request-time state, and
+// `server/chain-url-parts.ts` already imports the other direction.
+import { matchUrlParts } from '../server/tree-match.ts';
+
+/** One page-or-route-bearing node in a collision space. */
+export interface ProbeLeaf {
+  /** The file that serves it — what the error message names. */
+  filePath: string;
+  /**
+   * The nodes from the space root down to this leaf that contribute URL parts
+   * — route groups excluded, since they are transparent for matching. Empty
+   * for the space root's own page: `matchUrlParts` matches parts against the
+   * root's *children*, so the root itself consumes nothing.
+   */
+  chain: SegmentNode[];
+}
+
+/** Two files in one space that a single URL resolves to order-dependently. */
+export interface ProbedCollision {
+  /** The contended URL, written for a human (see `describeProbeUrl`). */
+  url: string;
+  /** The file that wins in filesystem order. */
+  first: string;
+  /** The file that wins when every `children` array is reversed. */
+  second: string;
+}
+
+/**
+ * Find a URL in this collision space whose winner depends on `children` order,
+ * or null if every probed URL resolves the same way in both orderings.
+ *
+ * `spaceRoot` is the node `matchUrlParts` starts from — the app root, a slot
+ * node, or an intercepting directory. `base` is the URL that root sits at, used
+ * only to render the reported URL.
+ */
+export function findOrderDependentCollision(
+  spaceRoot: SegmentNode,
+  leaves: Iterable<ProbeLeaf>,
+  base: string
+): ProbedCollision | null {
+  const reversed = withReversedChildren(spaceRoot);
+  const longTail = longTailLength(spaceRoot) + 1;
+  // Computed once for the space, not per leaf: it bounds the second candidate
+  // wave, which only runs for a leaf the first wave never reached.
+  const minLength = longestStaticName(spaceRoot);
+
+  // Each probe is checked as it is generated, and the first flipped winner
+  // returns immediately. Accumulating every probe first and scanning afterwards
+  // reports the same collision — this walks the same probes in the same order —
+  // but it pays for the whole space before saying anything, and the leaves that
+  // cost the most are exactly the ones a found collision makes irrelevant.
+  //
+  // In a space of N equivalent dynamic siblings, only the first and last can
+  // win a probe (one per ordering), so every middle leaf is unreachable and
+  // exhausts the entire candidate alphabet looking for a value that reaches it
+  // — 300 such siblings took ~2.5s to produce a build error the very first
+  // probe already proved (codex, on PR #1002). A valid space of the same size
+  // scans in ~35ms, so the cost was confined to the error path, but a slow
+  // error is still a bad error.
+  //
+  // Deduped so a space with many leaves does not re-probe one URL, and so the
+  // collision reported does not depend on which leaf generated a shared probe.
+  const seen = new Set<string>();
+  for (const leaf of leaves) {
+    for (const { parts, display } of probeUrlsForLeaf(
+      spaceRoot,
+      reversed,
+      leaf,
+      longTail,
+      minLength
+    )) {
+      const key = parts.join('/');
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const first = matchedLeafFile(spaceRoot, parts);
+      const second = matchedLeafFile(reversed, parts);
+      if (!first || !second || first === second) continue;
+      return { url: describeProbeUrl(base, display), first, second };
+    }
+  }
+
+  return null;
+}
+
+/** Join a probe's display parts onto its space's base. */
+function describeProbeUrl(base: string, display: string[]): string {
+  if (display.length === 0) return base || '/';
+  return `${base === '/' ? '' : base}/${display.join('/')}`;
+}
+
+/**
+ * The file `matchUrlParts` resolves for a URL, or null if nothing does.
+ *
+ * A `route.ts` counts: `isTerminal` accepts either, so a route handler is a
+ * legitimate winner of the walk and an ambiguity between a page and a route
+ * handler is as real as one between two pages.
+ */
+function matchedLeafFile(node: SegmentNode, parts: string[]): string | null {
+  const match = matchUrlParts(node, parts);
+  if (!match) return null;
+  const leaf = match.chain[match.chain.length - 1];
+  return leaf.page?.filePath ?? leaf.route?.filePath ?? null;
+}
+
+/**
+ * A generated URL, and how to show it to a human.
+ *
+ * `display` is built alongside `parts` rather than derived from it by
+ * substitution: a *static* segment can legitimately be named the same as the
+ * probe value, and replacing every occurrence of that string rewrote the
+ * literal directory to `<any>` — reporting `/<any>/<any>` for a collision under
+ * a static `atimber-probea`, which claims a URL position is dynamic when the
+ * author wrote it out (codex, on PR #1002). Only the segment that generated a
+ * value knows whether it stood for one.
+ */
+interface ProbeUrl {
+  parts: string[];
+  display: string[];
+  /**
+   * Whether any part of this URL stood in for a value. When nothing did, every
+   * candidate generates the identical URL and the search can stop after one.
+   */
+  dynamic: boolean;
+}
+
+/**
+ * The values a probe's dynamic parts are tried with, in order.
+ *
+ * A probe stands in for "any value" at a dynamic position, so it is only useful
+ * if it reaches the leaf it was built for. A *static* sibling's literal name or
+ * a more specific *affixed* sibling's pattern can claim it instead, and that
+ * higher-priority segment then wins in both orderings — a genuine tie
+ * underneath goes unreported, which is safe but is the whole thing these
+ * validators are for.
+ *
+ * Which values are claimable is a question about `matchNode`'s precedence, so
+ * `probeUrlsForLeaf` asks `matchUrlParts` rather than deciding it here. This
+ * only has to offer enough shapes for the search to find one that works: an
+ * affixed sibling constrains the head of the value, its tail, or both, so head
+ * and tail are varied over an alphanumeric alphabet. The head varies fastest
+ * because a prefix is the more common affix. Exhausting the list is a missed
+ * collision like any other inadequate probe, so this is a search and not a
+ * proof — nothing downstream may treat it as one.
+ *
+ * Exported so a test that has to *name* a capturing static sibling can derive
+ * the name from this list rather than restate it — a fixture spelling the value
+ * out by hand stops being a capture the moment the list changes, and passes.
+ *
+ * Three revisions of a hand-built value each dodged one more capture and were
+ * each followed by another (avoid static names; avoid affix boundary
+ * characters; avoid re-affixed forms of static names — then a strictly more
+ * specific affixed sibling, TIM-1313). Each rule was modelling affix precedence
+ * by hand, which is what the match-shape model was deleted for.
+ */
+export function* probeCandidates(minLength = 0): Generator<string> {
+  const alphabet = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  const base = 'timber-probe';
+
+  function* wave(core: string): Generator<string> {
+    for (const tail of alphabet) {
+      for (const head of alphabet) yield `${head}${core}${tail}`;
+    }
+  }
+
+  yield* wave(base);
+
+  // A second wave, longer than every static segment name in the space.
+  //
+  // A static sibling claims a probe only by **string equality**, so a value
+  // longer than every static name in the space cannot be claimed by one — that
+  // is a fact about lengths, not a model of `matchNode`'s precedence, which is
+  // what makes it safe to state as an invariant where "pick an unclaimable
+  // value" was not. An app holding a static directory for all 1296 first-wave
+  // candidates claimed every probe and hid a real collision (codex, on
+  // PR #1002); it cannot do the same here, because the length is derived from
+  // its own longest static and adding a longer one only pushes this further out.
+  //
+  // Affix capture is not addressed by length and is not addressable this way:
+  // an affixed pattern matches infinitely many values, so escaping one is still
+  // the head/tail search below. The first wave is byte-identical to what it was
+  // before this existed, so nothing that already found a value changes.
+  const padded = base.padEnd(Math.max(base.length, minLength), 'x');
+  if (padded !== base) yield* wave(padded);
+}
+
+/**
+ * The longest static segment name anywhere in the space.
+ *
+ * Read through `effectiveUrlSegment` so an intercepting directory counts as the
+ * segment it intercepts, and only static kinds count: a dynamic sibling claims
+ * a probe by pattern rather than by equality, which no length can escape.
+ */
+function longestStaticName(node: SegmentNode): number {
+  let longest = 0;
+  for (const child of node.children) {
+    const seg = effectiveUrlSegment(child);
+    if (seg.segmentType === 'static') longest = Math.max(longest, seg.segmentName.length);
+    longest = Math.max(longest, longestStaticName(child));
+  }
+  return longest;
+}
+
+/**
+ * The probe URLs for one leaf, built from the first candidate value that
+ * actually reaches it.
+ *
+ * "Reaches it" is `matchUrlParts` resolving one of the leaf's own URLs to the
+ * leaf's file, in either ordering — either is enough, because a leaf that wins
+ * only in the reversed ordering is precisely the contention being looked for.
+ * A catch-all leaf may be reached by its long probe and not its short one (at
+ * one part it loses to a bare dynamic sibling deterministically), so any one of
+ * the generated URLs landing is enough to accept the value.
+ *
+ * A leaf that no candidate reaches is shadowed at its position for every value
+ * tried — most often because it sits below a catch-all, which `matchNode`
+ * accepts only as a terminal and never descends past. Its probes are still
+ * emitted, from the first candidate: a probe that misses its own leaf is never
+ * *wrong* — it is a real URL, and a winner that differs between the two
+ * orderings is a real ambiguity whichever leaf it belongs to. Nothing here may
+ * report the leaf as unreachable; that is the universal claim these validators
+ * do not make.
+ */
+function probeUrlsForLeaf(
+  root: SegmentNode,
+  reversed: SegmentNode,
+  leaf: ProbeLeaf,
+  longTail: number,
+  minLength: number
+): ProbeUrl[] {
+  let fallback: ProbeUrl[] | null = null;
+
+  for (const value of probeCandidates(minLength)) {
+    const urls = probeUrlsFor(leaf.chain, value, longTail);
+    const reaches = urls.some(
+      ({ parts }) =>
+        matchedLeafFile(root, parts) === leaf.filePath ||
+        matchedLeafFile(reversed, parts) === leaf.filePath
+    );
+    if (reaches) return urls;
+    fallback ??= urls;
+
+    // A leaf with no dynamic part in its chain matches exactly one URL, so the
+    // candidate value never appears in it and every further candidate would
+    // generate the identical probe. Searching on would cost the whole alphabet
+    // per statically-shadowed leaf — and in the main tree those are ordinary
+    // (anything below a catch-all) rather than the pathology they are inside an
+    // intercepting subtree. Stopping is not a weaker check: the URLs are the
+    // same ones, and they are still probed via `fallback`.
+    if (!urls.some(({ dynamic }) => dynamic)) break;
+  }
+
+  // `probeCandidates` is non-empty, so this is only reached with a fallback.
+  return fallback ?? [];
+}
+
+/**
+ * The URL part one segment contributes to a probe.
+ *
+ * A dynamic segment stands for any single value, so it contributes the
+ * candidate value — re-affixed, since an affixed segment only matches parts
+ * that carry its prefix and suffix, so a probe without them could not reach it.
+ * A catch-all stands for one or more parts, and one is enough to reach the leaf.
+ *
+ * The re-affixed part is the reason a value cannot be checked once for the
+ * whole space: it exposes the value to every affixed sibling that *extends*
+ * this segment's affixes, which differs per position. `probeUrlsForLeaf` asks
+ * the matcher whether the assembled URL reaches its leaf, and moves to the next
+ * candidate when it does not.
+ *
+ * Segments are read through `effectiveUrlSegment` so an intercepting directory
+ * contributes the part the segment it intercepts would.
+ */
+function probePartFor(node: SegmentNode, value: string): ProbePart {
+  const seg = effectiveUrlSegment(node);
+  switch (seg.segmentType) {
+    case 'dynamic': {
+      const prefix = seg.paramPrefix ?? '';
+      const suffix = seg.paramSuffix ?? '';
+      // The affixes are kept in the shown form too: `x-<any>` says which URLs
+      // are contended for, where a bare `<any>` would claim every value at that
+      // position.
+      return {
+        part: `${prefix}${value}${suffix}`,
+        shown: `${prefix}<any>${suffix}`,
+        dynamic: true,
+      };
+    }
+    case 'catch-all':
+    case 'optional-catch-all':
+      return { part: value, shown: '<any>', dynamic: true };
+    default:
+      return { part: seg.segmentName, shown: seg.segmentName, dynamic: false };
+  }
+}
+
+/** One URL part of a probe: what to send, what to show, and whether it stands for a value. */
+interface ProbePart {
+  part: string;
+  shown: string;
+  dynamic: boolean;
+}
+
+/**
+ * The URLs that reach a leaf.
+ *
+ * An **optional catch-all also matches zero parts**, so it answers the URL its
+ * parent sits at as well as longer ones. Both are probed: whether the shorter
+ * one is actually *its* to answer is `matchUrlParts`' business, not something
+ * to decide here — a page above it, or in a route group beside it, may take
+ * that URL deterministically, and the probe will simply report the same winner
+ * in both orderings.
+ */
+function probeUrlsFor(chain: SegmentNode[], value: string, longTail: number): ProbeUrl[] {
+  const probeParts = chain.map((node) => probePartFor(node, value));
+  const url = (ps: ProbePart[]): ProbeUrl => ({
+    parts: ps.map((p) => p.part),
+    display: ps.map((p) => p.shown),
+    dynamic: ps.some((p) => p.dynamic),
+  });
+
+  // The kind that decides the probe lengths is the last part-CONTRIBUTING
+  // segment's, which is why it is read off the chain rather than off the leaf
+  // node. An empty chain is the space root's own page: the walk matches parts
+  // against that node's children, so the node's own segment consumes nothing
+  // and the only URL that reaches the page is the empty one — even when the
+  // root is itself a catch-all (`(.)[...rest]`).
+  const leaf = chain[chain.length - 1];
+  const kind = leaf && effectiveUrlSegment(leaf).segmentType;
+  const isCatchAll = kind === 'catch-all' || kind === 'optional-catch-all';
+  if (!isCatchAll) return [url(probeParts)];
+
+  // `matchNode` accepts a catch-all only as a terminal, so a catch-all that
+  // *is* the leaf owns the whole tail of the probe and it can be re-sized
+  // freely. (A catch-all higher in the chain has descendants nothing can
+  // reach; those leaves are the statically-shadowed case above.)
+  const head = probeParts.slice(0, -1);
+  const urls = [url(probeParts)];
+
+  // A LONG tail as well as a short one. At one part a catch-all loses to any
+  // bare dynamic sibling, deterministically — so a one-part probe reports that
+  // sibling in both orderings and two catch-alls competing at every longer URL
+  // go unnoticed. `longTail` is past every finite branch in the space, where
+  // no fixed-length competitor can still be matching.
+  if (longTail > 1) {
+    // Every part is the candidate value verbatim. Decorating them to differ
+    // (`${value}-0`) puts them back inside patterns like `[value]-0/[...rest]`,
+    // which outranks a catch-all — the trailing counter reintroduced exactly
+    // the affix capture the value is being searched for (codex, on PR #1000).
+    // The parts need not differ from each other; a catch-all consumes them all.
+    const tail: ProbePart[] = Array.from({ length: longTail }, () => ({
+      part: value,
+      shown: '<any>',
+      dynamic: true,
+    }));
+    urls.push(url([...head, ...tail]));
+  }
+
+  // An optional catch-all also matches zero parts.
+  if (kind === 'optional-catch-all') urls.push(url(head));
+
+  return urls;
+}
+
+/**
+ * One more than the longest fixed-length path in the space.
+ *
+ * A probe of this length cannot be claimed by any branch that consumes a fixed
+ * number of URL parts, so whatever matches it is a catch-all — which is
+ * exactly the competition a short probe hides.
+ */
+function longTailLength(node: SegmentNode): number {
+  let deepest = 0;
+  for (const child of node.children) {
+    const own = child.segmentType === 'group' ? 0 : 1;
+    deepest = Math.max(deepest, own + longTailLength(child));
+  }
+  return deepest;
+}
+
+/**
+ * The subtree with every `children` array reversed, top to bottom.
+ *
+ * Nodes are shallow-copied, so files and slots are shared with the original —
+ * only the ordering `matchNode` reads is different. Slots are not reversed
+ * because `matchNode` never walks them; each slot is validated as its own
+ * collision space, with its own reversed clone.
+ */
+function withReversedChildren(node: SegmentNode): SegmentNode {
+  return { ...node, children: [...node.children].reverse().map(withReversedChildren) };
+}