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

package/src/routing/codegen.ts

@@ -12,13 +12,8 @@ import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import type { RouteTree, SegmentNode } from './types.js';
 import type { ParamEntry, RouteEntry } from './codegen-types.js';
-import {
-  buildCodecChainType,
-  buildSchemaParamType,
-  emitResolveSegmentFieldHelper,
-  formatSearchParamsType,
-} from './codegen-shared.js';
-import { fileHasExport } from './export-detect.js';
+import { buildSchemaParamType } from './codegen-shared.js';
+import { effectiveUrlSegment, type UrlSegmentIdentity } from './segment-classify.js';
 import { formatLinkCatchAllOverloads, formatTypedLinkOverloads } from './link-codegen.js';
 
 /** Options for route map generation. */
@@ -49,7 +44,7 @@ export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}):
   const hasSchema = options.hasSchema ?? detectSchema(options.appDir);
 
   const routes: RouteEntry[] = [];
-  collectRoutes(tree.root, [], [], '', routes, hasSchema, false);
+  collectRoutes(tree.root, [], '', routes, hasSchema, false);
 
   // Sort routes alphabetically for deterministic output
   routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
@@ -80,124 +75,99 @@ function detectSchema(appDir: string | undefined): boolean {
 function collectRoutes(
   node: SegmentNode,
   ancestorParams: ParamEntry[],
-  ancestorParamsFiles: string[],
   parentTreePath: string,
   routes: RouteEntry[],
   hasSchema: boolean,
-  insideSlot: boolean
+  insideSlot: boolean,
+  insideIntercepting = false
 ): void {
   // Build the tree path (includes groups, slots — uniquely identifies this segment).
   // Root node has empty segmentName, producing treePath = ''.
   const treePath = node.segmentName ? `${parentTreePath}/${node.segmentName}` : parentTreePath;
-  // 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).
+  // Accumulate params from this segment.
+  //
+  // The segment is read through `effectiveUrlSegment` for the same reason the
+  // runtime coercer is: an intercepting node's own `segmentType` is
+  // 'intercepting' and its `paramName` is unset — the param it binds lives in
+  // the intercepted name (`(.)[albumSlug]` → `[albumSlug]`). Reading the node
+  // directly emitted `{}` for a segment the router does bind and coerce, so
+  // the types disagreed with the values for every intercepting page with a
+  // dynamic intercepted segment, and for its descendants, which lost the
+  // ancestor param too.
+  const urlSegment = effectiveUrlSegment(node);
   const params = [...ancestorParams];
-  if (node.paramName) {
-    const legacyFallback = ownParamsFile ? undefined : findLegacyParamsExport(node);
+  if (urlSegment.paramName) {
     params.push({
-      name: node.paramName,
-      bracketName: bracketNameForSegment(node),
-      type: paramTypeForSegment(node.segmentType),
-      // 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,
+      name: urlSegment.paramName,
+      bracketName: bracketNameForSegment(urlSegment),
+      type: paramTypeForSegment(urlSegment.segmentType),
     });
   }
 
-  // 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,
-        bracketName: p.bracketName,
-        type: p.type,
-        codecFilePaths,
-      };
-    });
-
+  // A segment that hosts code but is not itself addressable — a layout,
+  // middleware, or access check above the leaf — still gets a `$segment`
+  // module, so `getSegmentParams(SEGMENT_PATH)` is callable from it and needs
+  // a matching typed overload. Emitting only leaves left those call sites on
+  // the broad `Record<string, string | string[]>` signature, which since
+  // TIM-1342 (which deleted `defineSegmentParams`) is their ONLY typed path.
+  // design/41-global-params.md's Type Summary promises layouts and middleware
+  // exact accumulated params.
+  //
+  // `isRoutable: false` keeps them out of the urlPath-keyed emissions — the
+  // `Routes` interface and `<Link>` variants — where they would publish a URL
+  // that no request can reach. They belong only to the segmentPath-keyed
+  // APIs: `getSegmentParams`, `useSegmentParams`, `TimberSegmentParams`.
+  const hostsCode = !!node.layout || !!node.middleware || !!node.access;
+
+  if (isPage || isApiRoute || hostsCode) {
     const entry: RouteEntry = {
       urlPath: node.urlPath,
       segmentPath: treePath || '/',
-      params: resolvedParams,
-      hasSearchParams: false,
+      params,
       isApiRoute,
+      isRoutable: isPage || isApiRoute,
       isSlotRoute: insideSlot,
+      isInterceptingRoute: insideIntercepting,
       hasSchema,
     };
 
-    // Detect searchParams export from params.ts (primary) or page.tsx (fallback)
-    if (isPage) {
-      if (node.params && fileHasExport(node.params.filePath, 'searchParams')) {
-        entry.hasSearchParams = true;
-        entry.searchParamsPagePath = node.params.filePath;
-      } else if (node.page && fileHasExport(node.page.filePath, 'searchParams')) {
-        entry.hasSearchParams = true;
-        entry.searchParamsPagePath = node.page.filePath;
-      }
-    }
-
     routes.push(entry);
   }
 
-  // Recurse into children
+  // Recurse into children. An intercepting subtree is flagged, and the flag is
+  // sticky — the descendants are where the false URLs are. See
+  // `RouteEntry.isInterceptingRoute` for what the flag drops and why dedupe
+  // alone was not enough.
   for (const child of node.children) {
-    collectRoutes(child, params, nextAncestorFiles, treePath, routes, hasSchema, insideSlot);
+    const childIntercepting = insideIntercepting || child.segmentType === 'intercepting';
+    collectRoutes(child, params, treePath, routes, hasSchema, insideSlot, childIntercepting);
   }
 
   // Recurse into slots (they share the parent's URL path, but may have their own pages)
   for (const slot of Object.values(node.slots)) {
-    collectRoutes(slot, params, nextAncestorFiles, treePath, routes, hasSchema, true);
+    collectRoutes(slot, params, treePath, routes, hasSchema, true, insideIntercepting);
   }
 }
 
 /**
  * Dedupe route entries by urlPath for urlPath-keyed emissions (the Routes
- * interface, useQueryStates overloads, and typed Link variants).
+ * interface and typed Link variants).
  *
  * Parallel-slot pages share their parent's urlPath; emitting one entry per
  * slot page produced duplicate interface keys (TS2300/TS2717 under
  * skipLibCheck:false) and duplicate overloads. The non-slot entry is the
  * canonical one; when only slot entries exist (parent has no page), the
  * lexicographically smallest segmentPath wins so output is independent of
- * slot scan order. A slot's searchParams definition is carried onto the
- * merged entry when the canonical entry has none — never silently dropped.
+ * slot scan order.
+ *
+ * The loser is discarded outright. It used to donate its `searchParams`
+ * definition to the winner, because a slot could carry one the parent page
+ * lacked; since TIM-1343 no route entry carries a searchParams definition at
+ * all, there is nothing left to merge.
  *
  * segmentPath-keyed emissions (getSegmentParams, useSegmentParams,
  * TimberSegmentParams) must NOT use this — segmentPaths are already unique
@@ -212,25 +182,11 @@ function dedupeRoutesByUrlPath(routes: RouteEntry[]): RouteEntry[] {
       continue;
     }
 
-    let winner = existing;
-    let loser = route;
     const routeWins =
       (existing.isSlotRoute && !route.isSlotRoute) ||
       (!!existing.isSlotRoute === !!route.isSlotRoute &&
         route.segmentPath.localeCompare(existing.segmentPath) < 0);
-    if (routeWins) {
-      winner = route;
-      loser = existing;
-    }
-
-    if (!winner.hasSearchParams && loser.hasSearchParams) {
-      winner = {
-        ...winner,
-        hasSearchParams: true,
-        searchParamsPagePath: loser.searchParamsPagePath,
-      };
-    }
-    byPath.set(route.urlPath, winner);
+    byPath.set(route.urlPath, routeWins ? route : existing);
   }
   return [...byPath.values()];
 }
@@ -243,7 +199,7 @@ function dedupeRoutesByUrlPath(routes: RouteEntry[]): RouteEntry[] {
  * For bare segments like `[id]` this is the segmentName itself.
  * For affixed segments like `img-[id].png` this is `[id]` — the bare bracket form.
  */
-function bracketNameForSegment(node: SegmentNode): string {
+function bracketNameForSegment(node: UrlSegmentIdentity): string {
   if (node.paramPrefix || node.paramSuffix) {
     return `[${node.paramName}]`;
   }
@@ -261,23 +217,6 @@ function paramTypeForSegment(segmentType: string): ParamEntry['type'] {
   }
 }
 
-/**
- * Find a legacy `segmentParams` export on layout.tsx or page.tsx.
- *
- * 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 findLegacyParamsExport(node: SegmentNode): string | undefined {
-  if (node.layout && fileHasExport(node.layout.filePath, 'segmentParams')) {
-    return node.layout.filePath;
-  }
-  if (node.page && fileHasExport(node.page.filePath, 'segmentParams')) {
-    return node.page.filePath;
-  }
-  return undefined;
-}
-
 /**
  * Emit the schema-based type exports: TimberSegmentParams, TimberRoute,
  * AllSegmentParams, RoutesWithParams.
@@ -401,28 +340,30 @@ function formatDeclarationFile(
     lines.push('');
   }
 
-  if (!hasSchema) {
-    // 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('');
-  }
-
   // urlPath-keyed emissions use the deduped list (slot pages share their
   // parent's urlPath); segmentPath-keyed emissions below keep all entries.
-  const uniqueByUrlPath = dedupeRoutesByUrlPath(routes);
+  //
+  // Intercepting subtrees are dropped outright rather than deduped: their
+  // computed urlPath is not a route any request can reach, so a path that
+  // happens NOT to collide with a real one would otherwise be published as a
+  // real route. See `RouteEntry.isInterceptingRoute`.
+  const uniqueByUrlPath = dedupeRoutesByUrlPath(
+    routes.filter((r) => r.isRoutable && !r.isInterceptingRoute)
+  );
 
   lines.push("declare module '@timber-js/app' {");
   lines.push('  interface Routes {');
 
+  // TIM-1343: no `searchParams` member. With `params.ts` gone there is no
+  // convention file to read a definition from, so the framework has nothing
+  // to type it with — and an always-`{}` member is a claim that every route
+  // has no search params, which is false. Search-param types now come from
+  // the definition object itself, wherever the app chooses to keep it.
   for (const route of uniqueByUrlPath) {
-    const paramsType = formatParamsType(route.params, importBase, hasSchema);
-    const searchParamsType = formatSearchParamsType(route, importBase);
+    const paramsType = formatParamsType(route.params, hasSchema);
 
     lines.push(`    '${route.urlPath}': {`);
     lines.push(`      segmentParams: ${paramsType}`);
-    lines.push(`      searchParams: ${searchParamsType}`);
     lines.push(`    }`);
   }
 
@@ -453,7 +394,7 @@ function formatDeclarationFile(
       lines.push("  import type { AllSegmentParams } from '@timber-js/app'");
     }
     for (const route of dynamicRoutes) {
-      const paramsType = formatParamsType(route.params, importBase, hasSchema);
+      const paramsType = formatParamsType(route.params, hasSchema);
       lines.push(
         `  export function getSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`
       );
@@ -471,9 +412,7 @@ function formatDeclarationFile(
 
   if (dynamicRoutes.length > 0 || pageRoutes.length > 0) {
     lines.push("declare module '@timber-js/app/client' {");
-    lines.push(
-      "  import type { SearchParamsDefinition, SetParams, QueryStatesOptions, SearchParamCodec } from '@timber-js/app/search-params'"
-    );
+    lines.push("  import type { SearchParamsDefinition } from '@timber-js/app/search-params'");
     if (hasSchema) {
       lines.push("  import type { AllSegmentParams } from '@timber-js/app'");
     }
@@ -482,7 +421,7 @@ function formatDeclarationFile(
     // useSegmentParams overloads
     if (dynamicRoutes.length > 0) {
       for (const route of dynamicRoutes) {
-        const paramsType = formatParamsType(route.params, importBase, hasSchema);
+        const paramsType = formatParamsType(route.params, hasSchema);
         lines.push(
           `  export function useSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`
         );
@@ -495,12 +434,6 @@ function formatDeclarationFile(
       lines.push('');
     }
 
-    // useQueryStates overloads
-    if (pageRoutes.length > 0) {
-      lines.push(...formatUseQueryStatesOverloads(pageRoutes, importBase));
-      lines.push('');
-    }
-
     // Typed Link overloads — per-route with DIRECT types (no conditionals).
     // Direct types preserve TypeScript's excess property checking.
     //
@@ -515,7 +448,7 @@ function formatDeclarationFile(
     // confusing "Type 'string' is not assignable to type 'never'" cascade.
     if (pageRoutes.length > 0) {
       lines.push('  // Typed Link overloads — per-route (block 1 / emitted first)');
-      lines.push(...formatTypedLinkOverloads(pageRoutes, importBase, hasSchema));
+      lines.push(...formatTypedLinkOverloads(pageRoutes, hasSchema));
       lines.push('');
     }
 
@@ -540,48 +473,29 @@ function formatDeclarationFile(
 /**
  * Format the params type for a route entry.
  */
-function formatParamsType(params: ParamEntry[], importBase?: string, hasSchema?: boolean): string {
+function formatParamsType(params: ParamEntry[], hasSchema?: boolean): string {
   if (params.length === 0) {
     return '{}';
   }
 
+  // Without a schema a URL segment is an uninterpreted string — that IS
+  // its type. Per-segment codec chains used to narrow it here; TIM-1342
+  // deleted them along with params.ts.
   const fields = params.map((p) => {
-    const codecType = hasSchema
-      ? buildSchemaParamType(p)
-      : buildCodecChainType(p, importBase, p.type);
+    const codecType = hasSchema ? buildSchemaParamType(p) : p.type;
     return `${p.name}: ${codecType}`;
   });
   return `{ ${fields.join('; ')} }`;
 }
 
-/**
- * Generate useQueryStates overloads.
- *
- * For each page route:
- * - Routes with search-params.ts get a typed overload returning the inferred T
- * - Routes without search-params.ts get an overload returning [{}, SetParams<{}>]
- *
- * A fallback overload for standalone codecs (existing API) is emitted last.
- */
-function formatUseQueryStatesOverloads(routes: RouteEntry[], importBase?: string): string[] {
-  const lines: string[] = [];
-
-  for (const route of routes) {
-    const searchParamsType = route.hasSearchParams
-      ? formatSearchParamsType(route, importBase)
-      : '{}';
-    lines.push(
-      `  export function useQueryStates<R extends '${route.urlPath}'>(route: R, options?: QueryStatesOptions): [${searchParamsType}, SetParams<${searchParamsType}>]`
-    );
-  }
-
-  // Fallback: standalone codecs (existing API)
-  lines.push(
-    '  export function useQueryStates<T extends Record<string, unknown>>(codecs: { [K in keyof T]: SearchParamCodec<T[K]> }, options?: QueryStatesOptions): [T, SetParams<T>]'
-  );
-
-  return lines;
-}
+// TIM-1341: `useQueryStates` no longer has a route-string form, so the
+// generated `.d.ts` emits no overloads for it. Its source signature —
+// `useQueryStates(codecs, options?)` — is fully generic over the codec map
+// and needs no per-route augmentation. Reaching another route's codecs is
+// done by importing that route's `searchParams` definition from its
+// `params.ts` and calling `definition.useQueryStates()`, which is typed by
+// inference and cannot fail at runtime on an unpopulated registry.
+// See design/23-search-params.md §"Client Access".
 
 // Link overload formatters and helpers (`formatTypedLinkOverloads`,
 // `formatLinkCatchAllOverloads`, `formatLinkParamsType`,