@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/server/static-not-found.ts

@@ -0,0 +1,134 @@
+/**
+ * 404.html generation for static builds.
+ *
+ * `404.html` is written unconditionally (design/11-platform.md item 7). When
+ * the not-found probe does not produce a usable page, the framework default
+ * status page is written instead and the reason is reported as a warning —
+ * a static deploy that silently shipped no 404 page fell back to the host's
+ * generic one, and nothing in the build output said so (TIM-1258).
+ *
+ * The classification lives here, apart from the generation orchestration, so
+ * it can be exercised directly: every branch is a different diagnosis handed
+ * to a developer, and a wrong one sends them to the wrong file.
+ */
+
+import { resolveStatusFile } from './status-code-resolver.js';
+import { DEFAULT_STATUS_PAGE_CONTENT_TYPE, defaultStatusPageHtml } from './default-status-page.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+
+/**
+ * The probe path. `_timber/` is the framework's reserved prefix and
+ * `__not_found` is a private segment (double underscore), so user routes —
+ * including a catch-all `[...slug]` — cannot claim it.
+ */
+export const NOT_FOUND_PROBE_PATH = '/_timber/__not_found';
+
+/** URL path the static build maps to `404.html`. See plugins/static-build.ts. */
+export const NOT_FOUND_ENTRY_PATH = '/_timber_not_found';
+
+/** What the probe produced: a response, or the failure that replaced one. */
+export type NotFoundProbe =
+  | {
+      kind: 'response';
+      status: number;
+      body: Uint8Array;
+      headers: Record<string, string>;
+      contentType: string;
+    }
+  | { kind: 'threw'; error: unknown };
+
+export interface NotFoundResult {
+  /** Body to write as `404.html` — never empty. */
+  body: Uint8Array;
+  headers: Record<string, string>;
+  contentType: string;
+  /** Non-fatal problem to report, or null when the app rendered its own page. */
+  warning: string | null;
+  /** Build log line. Names *which* page was written. */
+  logLine: string;
+}
+
+/**
+ * Whether the not-found chain has anything to render for this root.
+ *
+ * Asks the resolver rather than inspecting file names: `renderNoMatchPage`
+ * builds its chain from the root segment alone and resolves through exactly
+ * these two calls, so this cannot drift from what the request path does. A
+ * hand-rolled key check gets it wrong — a root that declares only `500.tsx`
+ * has status files but nothing a 404 can select.
+ */
+function rootDeclaresNotFoundPage(root: ManifestSegmentNode): boolean {
+  return (
+    resolveStatusFile(404, [root], 'component') !== null ||
+    resolveStatusFile(404, [root], 'json') !== null
+  );
+}
+
+/** The framework default page, as a `404.html` payload. */
+function frameworkDefault(warning: string): NotFoundResult {
+  return {
+    body: new TextEncoder().encode(defaultStatusPageHtml(404)),
+    headers: { 'content-type': DEFAULT_STATUS_PAGE_CONTENT_TYPE },
+    contentType: DEFAULT_STATUS_PAGE_CONTENT_TYPE,
+    warning,
+    // Say which page was written — "rendered" would claim the app produced it.
+    logLine: '[timber] Static generation: wrote the framework default 404.html',
+  };
+}
+
+/**
+ * Decide what to write as `404.html`, and what to tell the developer.
+ *
+ * @param probe  What requesting {@link NOT_FOUND_PROBE_PATH} produced.
+ * @param root   Root segment of the route manifest — the only thing that can
+ *               distinguish an absent not-found page from a broken one.
+ */
+export function resolveNotFoundPage(
+  probe: NotFoundProbe,
+  root: ManifestSegmentNode
+): NotFoundResult {
+  if (probe.kind === 'threw') {
+    const message = probe.error instanceof Error ? probe.error.message : String(probe.error);
+    return frameworkDefault(
+      `the not-found page failed to render — writing the framework default 404.html. ${message}`
+    );
+  }
+
+  if (probe.status !== 404) {
+    return frameworkDefault(
+      `the not-found probe ${NOT_FOUND_PROBE_PATH} answered ${probe.status}, not 404 — ` +
+        `writing the framework default 404.html instead. A catch-all route or middleware is ` +
+        `claiming unmatched URLs.`
+    );
+  }
+
+  // The pipeline produced nothing, or produced the framework default itself.
+  // Compared by identity against the same builder rather than by a proxy like
+  // "the body is empty", which the default page invalidated.
+  const isDefault =
+    probe.body.byteLength === 0 ||
+    new TextDecoder().decode(probe.body) === defaultStatusPageHtml(404);
+
+  if (isDefault) {
+    // Which of the two it is cannot be read off the response: the deny chain
+    // answers "no status file" and "the status file threw" with the same
+    // bytes. Telling a developer whose 404.tsx just crashed to "add
+    // app/404.tsx" sends them to a file that already exists and buries the
+    // real failure, which the chain logged on its way past.
+    return frameworkDefault(
+      rootDeclaresNotFoundPage(root)
+        ? `the app's not-found page did not render — writing the framework default 404.html. ` +
+            `A root status file exists but produced no page; see the render error logged above.`
+        : `the app has no not-found page — writing the framework default 404.html. ` +
+            `Add app/404.tsx (or 4xx.tsx / error.tsx) to control it.`
+    );
+  }
+
+  return {
+    body: probe.body,
+    headers: probe.headers,
+    contentType: probe.contentType,
+    warning: null,
+    logLine: '[timber] Static generation: rendered 404.html',
+  };
+}

package/src/server/status-code-resolver.ts

@@ -5,6 +5,12 @@
  * correct file to render by walking the fallback chain described in
  * design/10-error-handling.md §"Status-Code Files".
  *
+ * **Generic over `TFile`** (TIM-848). Walks `SegmentNode<TFile>` trees
+ * regardless of whether `TFile` is the build-time `RouteFile` or the
+ * runtime `ManifestFile`. Before TIM-848 there were two near-identical
+ * resolvers — one for the Map-based scanner output and one for the
+ * object-based runtime manifest. Now there is one.
+ *
  * Supports two format families:
  * - 'component' (default): .tsx/.jsx/.mdx status files → React rendering pipeline
  * - 'json': .json status files → raw JSON response, no React
@@ -13,21 +19,19 @@
  *
  * **Component chain (4xx):**
  *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
- *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
- *   Pass 3 — error.tsx (leaf → root)
- *   Pass 4 — framework default (returns null)
+ *   Pass 2 — error.tsx (leaf → root)
+ *   Pass 3 — framework default (returns null)
  *
- * **JSON chain (4xx):**
- *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
+ * **JSON chain (4xx and 5xx):**
+ *   Pass 1 — json status files (leaf → root): {status}.json → {category}.json
  *   Pass 2 — framework default JSON (returns null, caller provides bare JSON)
  *
- * **5xx (component only):**
+ * **5xx component:**
  *   Per-segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
- *   Then global-error.tsx (future)
  *   Then framework default (returns null)
  */
 
-import type { SegmentNode, RouteFile } from '#/routing/types.js';
+import type { SegmentNode } from '../routing/types.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -35,16 +39,15 @@ import type { SegmentNode, RouteFile } from '#/routing/types.js';
 export type StatusFileKind =
   | 'exact' // e.g. 403.tsx matched status 403
   | 'category' // e.g. 4xx.tsx matched status 403
-  | 'legacy' // e.g. not-found.tsx matched status 404
   | 'error'; // error.tsx as last resort
 
 /** Response format family for status-code resolution. */
 export type StatusFileFormat = 'component' | 'json';
 
 /** Result of resolving a status-code file for a segment chain. */
-export interface StatusFileResolution {
+export interface StatusFileResolution<TFile> {
   /** The matched route file. */
-  file: RouteFile;
+  file: TFile;
   /** The HTTP status code (always the original status, not the file's code). */
   status: number;
   /** How the file was matched. */
@@ -57,26 +60,38 @@ export interface StatusFileResolution {
 export type SlotDeniedKind = 'denied' | 'default';
 
 /** Result of resolving a slot denied file. */
-export interface SlotDeniedResolution {
+export interface SlotDeniedResolution<TFile> {
   /** The matched route file (denied.tsx or default.tsx). */
-  file: RouteFile;
+  file: TFile;
   /** Slot name without @ prefix. */
   slotName: string;
   /** How the file was matched. */
   kind: SlotDeniedKind;
 }
 
-// ─── Legacy Compat Mapping ───────────────────────────────────────────────────
+// ─── Lookup Helpers ──────────────────────────────────────────────────────
 
 /**
- * Maps legacy file convention names to their corresponding HTTP status codes.
- * Only used in the 4xx component fallback chain.
+ * Look up `{statusStr}` then `{categoryKey}` (e.g. "4xx" / "5xx") in a
+ * status-file group on a single segment. Shared by all three fallback
+ * chains — the only structural difference between component 4xx,
+ * component 5xx, and JSON resolution is *which* group is searched and
+ * how the per-segment loop is layered around it.
  */
-const LEGACY_FILE_TO_STATUS: Record<string, number> = {
-  'not-found': 404,
-  'forbidden': 403,
-  'unauthorized': 401,
-};
+function lookupInGroup<TFile>(
+  group: Record<string, TFile> | undefined,
+  statusStr: string,
+  categoryKey: string,
+  segmentIndex: number,
+  status: number
+): StatusFileResolution<TFile> | null {
+  if (!group) return null;
+  const exact = group[statusStr];
+  if (exact) return { file: exact, status, kind: 'exact', segmentIndex };
+  const category = group[categoryKey];
+  if (category) return { file: category, status, kind: 'category', segmentIndex };
+  return null;
+}
 
 // ─── Resolver ────────────────────────────────────────────────────────────────
 
@@ -90,71 +105,56 @@ const LEGACY_FILE_TO_STATUS: Record<string, number> = {
  * @param status - The HTTP status code (4xx or 5xx).
  * @param segments - The matched segment chain from root (index 0) to leaf (last).
  * @param format - The response format family ('component' or 'json'). Defaults to 'component'.
+ * @param maxIndex - Optional upper bound on the segment index to search.
+ *   When set, the resolver only considers segments `0..maxIndex` (inclusive),
+ *   skipping any segments deeper in the tree. Used by the deny renderers to
+ *   prevent resolving a status file below a denied segment — matching
+ *   `buildDenyPageChain`'s start-at-i semantics. The error renderers omit
+ *   this parameter, so the full chain is searched — a 500 from a leaf page
+ *   should use the leaf's own `5xx.tsx`. See TIM-1358.
  */
-export function resolveStatusFile(
+export function resolveStatusFile<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>,
-  format: StatusFileFormat = 'component'
-): StatusFileResolution | null {
-  if (status >= 400 && status <= 499) {
-    return format === 'json' ? resolve4xxJson(status, segments) : resolve4xx(status, segments);
-  }
-  if (status >= 500 && status <= 599) {
-    // JSON format for 5xx uses the same json chain pattern
-    return format === 'json' ? resolve5xxJson(status, segments) : resolve5xx(status, segments);
-  }
-  return null;
+  segments: ReadonlyArray<SegmentNode<TFile>>,
+  format: StatusFileFormat = 'component',
+  maxIndex?: number
+): StatusFileResolution<TFile> | null {
+  if (status < 400 || status > 599) return null;
+  if (format === 'json') return resolveJson(status, segments, maxIndex);
+  if (status <= 499) return resolve4xx(status, segments, maxIndex);
+  return resolve5xx(status, segments, maxIndex);
 }
 
 /**
- * 4xx component fallback chain (three separate passes):
- *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
- *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
- *   Pass 3 — error.tsx (leaf → root)
+ * 4xx component fallback chain — two separate full passes leaf→root.
+ *
+ * The passes must be separate (not interleaved per-segment) so that a
+ * root-level `404.tsx` beats a leaf-level `error.tsx`. The 5xx chain
+ * inverts this and is per-segment: a leaf's `error.tsx` beats a root's
+ * `5xx.tsx`. This asymmetry is the only reason these two functions exist
+ * separately.
+ *
+ *   Pass 1 — {status}.tsx → 4xx.tsx           (statusFiles)
+ *   Pass 2 — error.tsx                         (error)
  */
-function resolve4xx(
+function resolve4xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>,
+  maxIndex?: number
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
+  const start =
+    maxIndex !== undefined ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
 
-  // Pass 1: status files across all segments (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.statusFiles) continue;
-
-    // Exact match first
-    const exact = segment.statusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    // Category catch-all
-    const category = segment.statusFiles.get('4xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
+  for (let i = start; i >= 0; i--) {
+    const r = lookupInGroup(segments[i].statusFiles, statusStr, '4xx', i, status);
+    if (r) return r;
   }
 
-  // Pass 2: legacy compat files (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.legacyStatusFiles) continue;
-
-    for (const [name, legacyStatus] of Object.entries(LEGACY_FILE_TO_STATUS)) {
-      if (legacyStatus === status) {
-        const file = segment.legacyStatusFiles.get(name);
-        if (file) {
-          return { file, status, kind: 'legacy', segmentIndex: i };
-        }
-      }
-    }
-  }
-
-  // Pass 3: error.tsx (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    if (segments[i].error) {
-      return { file: segments[i].error!, status, kind: 'error', segmentIndex: i };
+  for (let i = start; i >= 0; i--) {
+    const errorFile = segments[i].error;
+    if (errorFile) {
+      return { file: errorFile, status, kind: 'error', segmentIndex: i };
     }
   }
 
@@ -162,64 +162,25 @@ function resolve4xx(
 }
 
 /**
- * 4xx JSON fallback chain (single pass):
- *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
- *   No legacy compat, no error.tsx — JSON chain terminates at category catch-all.
- */
-function resolve4xxJson(
-  status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
-  const statusStr = String(status);
-
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.jsonStatusFiles) continue;
-
-    // Exact match first
-    const exact = segment.jsonStatusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    // Category catch-all
-    const category = segment.jsonStatusFiles.get('4xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
-  }
-
-  return null;
-}
-
-/**
- * 5xx component fallback chain (single pass, per-segment):
- *   At each segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
+ * 5xx component fallback chain — single pass, per-segment leaf→root.
+ *
+ * At each segment: {status}.tsx → 5xx.tsx → error.tsx. A leaf's
+ * `error.tsx` therefore beats a root's `5xx.tsx`, which is the
+ * intentional inverse of the 4xx chain.
  */
-function resolve5xx(
+function resolve5xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>,
+  maxIndex?: number
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
+  const start =
+    maxIndex !== undefined ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
 
-  for (let i = segments.length - 1; i >= 0; i--) {
+  for (let i = start; i >= 0; i--) {
     const segment = segments[i];
-
-    // Exact status file
-    if (segment.statusFiles) {
-      const exact = segment.statusFiles.get(statusStr);
-      if (exact) {
-        return { file: exact, status, kind: 'exact', segmentIndex: i };
-      }
-
-      // Category catch-all
-      const category = segment.statusFiles.get('5xx');
-      if (category) {
-        return { file: category, status, kind: 'category', segmentIndex: i };
-      }
-    }
-
-    // error.tsx at this segment level (for 5xx, checked per-segment)
+    const r = lookupInGroup(segment.statusFiles, statusStr, '5xx', i, status);
+    if (r) return r;
     if (segment.error) {
       return { file: segment.error, status, kind: 'error', segmentIndex: i };
     }
@@ -229,29 +190,25 @@ function resolve5xx(
 }
 
 /**
- * 5xx JSON fallback chain (single pass):
- *   At each segment (leaf → root): {status}.json → 5xx.json
- *   No error.tsx equivalent — JSON chain terminates at category catch-all.
+ * JSON fallback chain (for both 4xx and 5xx) — single pass leaf→root.
+ *
+ * At each segment: {status}.json → {category}.json. No legacy compat,
+ * no error.tsx — the JSON chain terminates at the category catch-all
+ * and the caller falls back to a bare-JSON framework default.
  */
-function resolve5xxJson(
+function resolveJson<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>,
+  maxIndex?: number
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
+  const categoryKey = status >= 500 ? '5xx' : '4xx';
+  const start =
+    maxIndex !== undefined ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
 
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.jsonStatusFiles) continue;
-
-    const exact = segment.jsonStatusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    const category = segment.jsonStatusFiles.get('5xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
+  for (let i = start; i >= 0; i--) {
+    const r = lookupInGroup(segments[i].jsonStatusFiles, statusStr, categoryKey, i, status);
+    if (r) return r;
   }
 
   return null;
@@ -267,7 +224,9 @@ function resolve5xxJson(
  *
  * @param slotNode - The segment node for the slot (segmentType === 'slot').
  */
-export function resolveSlotDenied(slotNode: SegmentNode): SlotDeniedResolution | null {
+export function resolveSlotDenied<TFile>(
+  slotNode: SegmentNode<TFile>
+): SlotDeniedResolution<TFile> | null {
   const slotName = slotNode.segmentName.replace(/^@/, '');
 
   if (slotNode.denied) {