@timber-js/app 0.2.0-alpha.90 → 0.2.0-alpha.92

package/src/routing/codegen.ts

@@ -9,29 +9,14 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { relative, posix } from 'node:path';
 import type { RouteTree, SegmentNode } from './types.js';
-
-/** A single route entry extracted from the segment tree. */
-interface RouteEntry {
-  /** URL path pattern (e.g. "/products/[id]") */
-  urlPath: string;
-  /** Accumulated params from all ancestor dynamic segments */
-  params: ParamEntry[];
-  /** Whether the page.tsx exports searchParams */
-  hasSearchParams: boolean;
-  /** Absolute path to the page file that exports searchParams (for import paths) */
-  searchParamsPagePath?: string;
-  /** Whether this is an API route (route.ts) vs page route */
-  isApiRoute: boolean;
-}
-
-interface ParamEntry {
-  name: string;
-  type: 'string' | 'string[]' | 'string[] | undefined';
-  /** When a layout/page exports defineParams, the absolute path to that file. */
-  codecFilePath?: string;
-}
+import type { ParamEntry, RouteEntry } from './codegen-types.js';
+import {
+  buildCodecChainType,
+  emitResolveSegmentFieldHelper,
+  formatSearchParamsType,
+} from './codegen-shared.js';
+import { formatLinkCatchAllOverloads, formatTypedLinkOverloads } from './link-codegen.js';
 
 /** Options for route map generation. */
 export interface CodegenOptions {
@@ -53,7 +38,7 @@ export interface CodegenOptions {
  */
 export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}): string {
   const routes: RouteEntry[] = [];
-  collectRoutes(tree.root, [], routes);
+  collectRoutes(tree.root, [], [], routes);
 
   // Sort routes alphabetically for deterministic output
   routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
@@ -73,28 +58,73 @@ export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}):
 function collectRoutes(
   node: SegmentNode,
   ancestorParams: ParamEntry[],
+  ancestorParamsFiles: string[],
   routes: RouteEntry[]
 ): void {
-  // Accumulate params from this segment
+  // TIM-834: Identify this segment's own params.ts (if it has a
+  // segmentParams export). The full chain of params.ts files in the
+  // route ancestry is threaded down via `ancestorParamsFiles`; codec
+  // resolution for each ParamEntry is deferred until leaf time so that
+  // descendant params.ts files can override ancestor codecs (closest-
+  // to-leaf wins, matching the runtime semantics of
+  // coerceSegmentParams which walks segments top-down and overwrites
+  // earlier coercions).
+  const ownParamsFile =
+    node.params && fileHasExport(node.params.filePath, 'segmentParams')
+      ? node.params.filePath
+      : undefined;
+
+  // Accumulate params from this segment. We attach `codecFilePaths`
+  // later (at leaf time) using the FULL chain so descendant overrides
+  // are visible. The legacy layout/page fallback is recorded now
+  // because it is per-segment (and does not participate in inheritance).
   const params = [...ancestorParams];
   if (node.paramName) {
-    // Check if layout or page exports a params codec for this segment
-    const codecFile = findParamsExport(node);
+    const legacyFallback = ownParamsFile ? undefined : findLegacyParamsExport(node);
     params.push({
       name: node.paramName,
       type: paramTypeForSegment(node.segmentType),
-      codecFilePath: codecFile,
+      // Codec chain populated at leaf time. We carry the per-segment
+      // legacy fallback (if any) so leaf-time resolution can fall back
+      // to it when no params.ts in the chain declares this key.
+      legacyCodecFilePath: legacyFallback,
     });
   }
 
+  // Extend the chain for descendants of this segment.
+  const nextAncestorFiles = ownParamsFile
+    ? [...ancestorParamsFiles, ownParamsFile]
+    : ancestorParamsFiles;
+
   // Check if this segment is a leaf route (has page or route file)
   const isPage = !!node.page;
   const isApiRoute = !!node.route;
 
   if (isPage || isApiRoute) {
+    // TIM-834 P1 fix: at LEAF time, the full chain of params.ts files
+    // (root-to-leaf) is known. Resolve every ParamEntry's
+    // `codecFilePaths` to the chain in LEAF-FIRST order so the
+    // closest-to-leaf entry is checked first — matching runtime
+    // closest-wins semantics. The chain is shared by all params in the
+    // route, so we compute it once.
+    const leafFirstChain = nextAncestorFiles.length > 0 ? [...nextAncestorFiles].reverse() : [];
+    const resolvedParams: ParamEntry[] = params.map((p) => {
+      const codecFilePaths =
+        leafFirstChain.length > 0
+          ? leafFirstChain
+          : p.legacyCodecFilePath
+            ? [p.legacyCodecFilePath]
+            : undefined;
+      return {
+        name: p.name,
+        type: p.type,
+        codecFilePaths,
+      };
+    });
+
     const entry: RouteEntry = {
       urlPath: node.urlPath,
-      params: [...params],
+      params: resolvedParams,
       hasSearchParams: false,
       isApiRoute,
     };
@@ -115,12 +145,12 @@ function collectRoutes(
 
   // Recurse into children
   for (const child of node.children) {
-    collectRoutes(child, params, routes);
+    collectRoutes(child, params, nextAncestorFiles, routes);
   }
 
   // Recurse into slots (they share the parent's URL path, but may have their own pages)
   for (const [, slot] of node.slots) {
-    collectRoutes(slot, params, routes);
+    collectRoutes(slot, params, nextAncestorFiles, routes);
   }
 }
 
@@ -159,18 +189,13 @@ function fileHasExport(filePath: string, exportName: string): boolean {
 }
 
 /**
- * Find which file exports `segmentParams` for a dynamic segment.
+ * Find a legacy `segmentParams` export on layout.tsx or page.tsx.
  *
- * Priority: params.ts (convention file) > layout > page.
- * params.ts is the canonical location (TIM-508). Layout/page fallback
- * exists for backward compat during migration.
+ * Backward-compat shim: TIM-508 made params.ts the canonical location
+ * for `segmentParams`. Layout/page exports are still accepted for the
+ * OWN segment only (not inherited by descendants — see TIM-834).
  */
-function findParamsExport(node: SegmentNode): string | undefined {
-  // params.ts convention file — primary location
-  if (node.params && fileHasExport(node.params.filePath, 'segmentParams')) {
-    return node.params.filePath;
-  }
-  // Fallback: layout or page export (legacy, will be removed)
+function findLegacyParamsExport(node: SegmentNode): string | undefined {
   if (node.layout && fileHasExport(node.layout.filePath, 'segmentParams')) {
     return node.layout.filePath;
   }
@@ -195,6 +220,12 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
   // (removing exports like bindUseQueryStates that aren't listed here).
   lines.push('export {};');
   lines.push('');
+
+  // TIM-834 P2: emit the shared codec-resolution helper type ONCE so the
+  // per-param chain conditionals reference it instead of inlining the
+  // fallback in both branches (which grows O(2^N) in chain depth).
+  lines.push(emitResolveSegmentFieldHelper());
+  lines.push('');
   lines.push("declare module '@timber-js/app' {");
   lines.push('  interface Routes {');
 
@@ -290,79 +321,12 @@ function formatParamsType(params: ParamEntry[], importBase?: string): string {
   }
 
   const fields = params.map((p) => {
-    if (p.codecFilePath) {
-      // Use the codec's inferred type from the layout/page file
-      const absPath = p.codecFilePath.replace(/\.(ts|tsx)$/, '');
-      let importPath: string;
-      if (importBase) {
-        importPath = './' + relative(importBase, absPath).replace(/\\/g, '/');
-      } else {
-        importPath = './' + posix.basename(absPath);
-      }
-      // Extract T from the 'segmentParams' named export's ParamsDefinition<T>
-      const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/segment-params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;
-      return `${p.name}: ${codecType}`;
-    }
-    return `${p.name}: ${p.type}`;
-  });
-  return `{ ${fields.join('; ')} }`;
-}
-
-/**
- * Format the params type for Link overloads.
- *
- * Link params accept `string | number` for single dynamic segments
- * (convenience — values are stringified at runtime). Catch-all and
- * optional catch-all remain `string[]` / `string[] | undefined`.
- *
- * Uses DIRECT types (not conditional) to preserve excess property checking.
- */
-function formatLinkParamsType(params: ParamEntry[], importBase?: string): string {
-  if (params.length === 0) {
-    return '{}';
-  }
-
-  const fields = params.map((p) => {
-    if (p.codecFilePath) {
-      const absPath = p.codecFilePath.replace(/\.(ts|tsx)$/, '');
-      let importPath: string;
-      if (importBase) {
-        importPath = './' + relative(importBase, absPath).replace(/\\/g, '/');
-      } else {
-        importPath = './' + posix.basename(absPath);
-      }
-      const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/segment-params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;
-      return `${p.name}: ${codecType}`;
-    }
-    const type = p.type === 'string' ? 'string | number' : p.type;
-    return `${p.name}: ${type}`;
+    const codecType = buildCodecChainType(p, importBase, p.type);
+    return `${p.name}: ${codecType}`;
   });
   return `{ ${fields.join('; ')} }`;
 }
 
-/**
- * Format the searchParams type for a route entry.
- *
- * When a page.tsx exports searchParams, we reference its inferred type via an import type.
- * The import path is relative to `importBase` (the directory where the .d.ts will be
- * written). When importBase is undefined, falls back to a bare relative path.
- */
-function formatSearchParamsType(route: RouteEntry, importBase?: string): string {
-  if (route.hasSearchParams && route.searchParamsPagePath) {
-    const absPath = route.searchParamsPagePath.replace(/\.(ts|tsx)$/, '');
-    let importPath: string;
-    if (importBase) {
-      // Make the path relative to the output directory, converted to posix separators
-      importPath = './' + relative(importBase, absPath).replace(/\\/g, '/');
-    } else {
-      importPath = './' + posix.basename(absPath);
-    }
-    // Extract the type from the named 'searchParams' export of the page module.
-    return `(typeof import('${importPath}'))['searchParams'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
-  }
-  return '{}';
-}
-
 /**
  * Generate useQueryStates overloads.
  *
@@ -392,173 +356,8 @@ function formatUseQueryStatesOverloads(routes: RouteEntry[], importBase?: string
   return lines;
 }
 
-/**
- * Build a TypeScript template literal pattern for a dynamic route.
- * e.g. '/products/[id]'        → '/products/${string}'
- *      '/blog/[...slug]'       → '/blog/${string}'
- *      '/docs/[[...path]]'     → '/docs/${string}' (also matches /docs)
- *      '/[org]/[repo]'         → '/${string}/${string}'
- */
-function buildResolvedPattern(route: RouteEntry): string | null {
-  const parts = route.urlPath.split('/');
-  const templateParts = parts.map((part) => {
-    if (part.startsWith('[[...') && part.endsWith(']]')) {
-      // Optional catch-all — matches any trailing path
-      return '${string}';
-    }
-    if (part.startsWith('[...') && part.endsWith(']')) {
-      // Catch-all — matches one or more segments
-      return '${string}';
-    }
-    if (part.startsWith('[') && part.endsWith(']')) {
-      // Dynamic segment
-      return '${string}';
-    }
-    return part;
-  });
-  return templateParts.join('/');
-}
-
-/** Shared Link base-props type literal used in every emitted call signature. */
-const LINK_BASE_PROPS_TYPE =
-  "Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & { prefetch?: boolean; scroll?: boolean; preserveSearchParams?: true | string[]; onNavigate?: import('./client/link.js').OnNavigateHandler; children?: import('react').ReactNode }";
-
-/**
- * TIM-832: Catch-all call signatures for `<Link>` — external hrefs and
- * computed `string` variables. Emitted from codegen in a SEPARATE
- * `declare module` block (declared AFTER the per-route block) so the TS
- * "later overload set ordered first" rule places these catch-all
- * signatures ahead of per-route in resolution order, leaving per-route
- * as the final overload whose error message is reported on failure.
- *
- * The conditional `string extends H ? ... : never` protection preserves
- * TIM-624's guarantee that unknown internal path literals don't match
- * the catch-all — typos like `<Link href="/typo" />` still error.
- */
-function formatLinkCatchAllOverloads(): string[] {
-  const lines: string[] = [];
-  const baseProps = LINK_BASE_PROPS_TYPE;
-
-  // TIM-830: the catch-all signatures accept EITHER the legacy
-  // `{ definition, values }` wrapper OR a flat `Record<string, unknown>`
-  // values object. External/computed hrefs can't be looked up in the
-  // runtime registry, so the wrapped form is still the reliable path;
-  // the flat form is kept permissive for callers migrating from typed-
-  // route hrefs to computed strings. `resolveHref` discriminates at
-  // runtime via the presence of a `definition` key.
-  const catchAllSearchParams =
-    '{ definition: SearchParamsDefinition<Record<string, unknown>>; values: Record<string, unknown> } | Record<string, unknown>';
-
-  // ExternalHref inlined here rather than referenced as an exported
-  // alias so the generated .d.ts stands alone without source imports.
-  const externalHref =
-    '`http://${string}` | `https://${string}` | `mailto:${string}` | `tel:${string}` | `ftp://${string}` | `//${string}` | `#${string}` | `?${string}`';
-
-  lines.push('  // Typed Link overloads — catch-all (block 2 / emitted second)');
-  lines.push('  interface LinkFunction {');
-
-  // (1) External/literal-protocol hrefs.
-  lines.push(`    (props: ${baseProps} & {`);
-  lines.push(`      href: ${externalHref}`);
-  lines.push(`      segmentParams?: never`);
-  lines.push(`      searchParams?: ${catchAllSearchParams}`);
-  lines.push(`    }): import('react').JSX.Element`);
-
-  // (2) Computed/variable href — non-literal `string` only.
-  // `string extends H` is true only when H is the wide `string` type,
-  // not a specific literal. Literal internal paths (typos) that don't
-  // match any per-route signature collapse to `never` here, but since
-  // this block is NOT the "last overload" at resolution time, TS
-  // instead reports the error from the per-route block — which now
-  // says `Type '"/typo"' is not assignable to type '"/products/[id]"'`
-  // or similar per-route-specific guidance.
-  lines.push(`    <H extends string>(`);
-  lines.push(`      props: string extends H`);
-  lines.push(`        ? ${baseProps} & {`);
-  lines.push(`            href: H`);
-  lines.push(`            segmentParams?: Record<string, string | number | string[]>`);
-  lines.push(`            searchParams?: ${catchAllSearchParams}`);
-  lines.push(`          }`);
-  lines.push(`        : never`);
-  lines.push(`    ): import('react').JSX.Element`);
-
-  lines.push('  }');
-  return lines;
-}
-
-/**
- * Generate typed per-route Link call signatures via LinkFunction
- * interface merging.
- *
- * Each call signature uses DIRECT types (not conditional types) for
- * segmentParams, preserving TypeScript's excess property checking.
- * Interface merging is the only reliable way to add "overloads" via
- * module augmentation — function overloads can't be augmented.
- *
- * TIM-832: this function emits ONLY the per-route block. The catch-all
- * block is emitted separately by `formatLinkCatchAllOverloads` inside a
- * second `declare module` so TS overload ordering reports per-route
- * errors (see `formatDeclarationFile`).
- */
-function formatTypedLinkOverloads(routes: RouteEntry[], importBase?: string): string[] {
-  const lines: string[] = [];
-  const baseProps = LINK_BASE_PROPS_TYPE;
-
-  lines.push('  interface LinkFunction {');
-  for (const route of routes) {
-    const hasDynamicParams = route.params.length > 0;
-    const paramsProp = hasDynamicParams
-      ? `segmentParams: ${formatLinkParamsType(route.params, importBase)}`
-      : 'segmentParams?: never';
-
-    const searchParamsType = route.hasSearchParams
-      ? formatSearchParamsType(route, importBase)
-      : null;
-    // TIM-830: the per-route pattern signature (href: '/products/[id]')
-    // uses a FLAT `Partial<T>` shape — the registry is keyed by the
-    // un-interpolated pattern, which matches `href` here exactly.
-    const patternSearchParamsProp = searchParamsType
-      ? `searchParams?: Partial<${searchParamsType}>`
-      : 'searchParams?: never';
-
-    // TIM-832: For dynamic routes, emit the resolved-template signature
-    // FIRST and the pattern signature SECOND. The TS overload resolution
-    // order is top-to-bottom, and TS reports the error from the LAST
-    // overload tried on a failed call. For a user who passes the literal
-    // pattern href (`href="/products/[id]"`) and mistyped segmentParams,
-    // we want the PATTERN signature's error (which names the specific
-    // `segmentParams` shape like `{ id: string | number }`) to be the one
-    // TS reports — so the pattern must come LAST.
-    //
-    // TIM-830: the resolved-template signature keeps the legacy WRAPPED
-    // `{ definition, values }` shape. The runtime registry is keyed by
-    // the un-interpolated pattern (e.g. '/products/[id]'), so a flat
-    // lookup for an already-interpolated href like '/products/42' would
-    // fail. Flat values only work on the pattern signature below where
-    // `href` is the pattern itself. Callers using a resolved-template
-    // href must pass the definition inline, same as the external/
-    // computed catch-all signature.
-    if (hasDynamicParams) {
-      const templatePattern = buildResolvedPattern(route);
-      if (templatePattern) {
-        const resolvedSearchParamsProp = searchParamsType
-          ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
-          : 'searchParams?: never';
-        lines.push(`    (props: ${baseProps} & {`);
-        lines.push(`      href: \`${templatePattern}\``);
-        lines.push(`      segmentParams?: never`);
-        lines.push(`      ${resolvedSearchParamsProp}`);
-        lines.push(`    }): import('react').JSX.Element`);
-      }
-    }
-
-    lines.push(`    (props: ${baseProps} & {`);
-    lines.push(`      href: '${route.urlPath}'`);
-    lines.push(`      ${paramsProp}`);
-    lines.push(`      ${patternSearchParamsProp}`);
-    lines.push(`    }): import('react').JSX.Element`);
-  }
-  lines.push('  }');
-
-  return lines;
-}
+// Link overload formatters and helpers (`formatTypedLinkOverloads`,
+// `formatLinkCatchAllOverloads`, `formatLinkParamsType`,
+// `buildResolvedPattern`, `LINK_BASE_PROPS_TYPE`) were extracted to
+// `./link-codegen.ts` (TIM-835) to keep this file under the 500-line
+// cap. They are imported at the top of this file.