@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.91

package/src/routing/convention-lint.ts

@@ -0,0 +1,356 @@
+/**
+ * Convention linter — validates common misconfigurations in the route tree.
+ *
+ * Runs at scan time (build and dev startup). Each check produces a warning
+ * with the file path, what's wrong, and what to do about it.
+ *
+ * These are warnings, not errors — they don't block the build. The goal is
+ * to catch issues that would otherwise produce cryptic runtime behavior
+ * (silent 404s, empty pages, confusing React errors).
+ *
+ * Design doc: 07-routing.md, 10-error-handling.md
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import type { RouteTree, SegmentNode } from './types.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ConventionWarning {
+  /** Warning ID for deduplication and filtering. */
+  id: string;
+  /** Human-readable single-line summary. */
+  summary: string;
+  /** Multi-line details with file path and fix suggestion. */
+  details: string;
+  /** Severity: 'warn' for potential issues, 'error' for definite misconfigurations. */
+  level: 'warn' | 'error';
+}
+
+// ─── Lint Rules ─────────────────────────────────────────────────────────────
+
+/**
+ * Run all convention lint checks on a route tree.
+ *
+ * Returns an array of warnings. Empty array means everything looks good.
+ */
+export function lintConventions(tree: RouteTree, appDir: string): ConventionWarning[] {
+  const warnings: ConventionWarning[] = [];
+
+  // Check 1: app/ directory exists (caller should check before scanning,
+  // but we validate the root has at least one routable file)
+  checkEmptyApp(tree.root, appDir, warnings);
+
+  // Check 2: route.ts without recognized HTTP method exports
+  checkRouteExports(tree.root, warnings);
+
+  // Check 3: Segments with layout but no page/route anywhere in subtree
+  // (not a misconfiguration per se — layouts without pages are valid for
+  // route groups. Skip this check.)
+
+  // Check 4: Root segment has no layout.tsx (no HTML shell)
+  checkRootLayout(tree.root, warnings);
+
+  // Check 5: page.tsx / layout.tsx without default export
+  checkDefaultExports(tree.root, warnings);
+
+  return warnings;
+}
+
+// ─── Check: Empty App ───────────────────────────────────────────────────────
+
+/**
+ * Warn when the app/ directory has no routable files at all.
+ *
+ * This catches the "I created app/ but didn't add any pages" case where
+ * every request silently 404s with no guidance.
+ */
+function checkEmptyApp(root: SegmentNode, appDir: string, warnings: ConventionWarning[]): void {
+  if (hasAnyRoutable(root)) return;
+
+  warnings.push({
+    id: 'EMPTY_APP',
+    summary: 'No pages or route handlers found in app/',
+    details:
+      `  Directory: ${appDir}\n\n` +
+      '  Your app/ directory has no page.tsx or route.ts files.\n' +
+      '  Every request will return 404.\n\n' +
+      '  To fix: Create app/page.tsx with a default export:\n\n' +
+      '    export default function Home() {\n      return <h1>Hello</h1>;\n    }\n',
+    level: 'warn',
+  });
+}
+
+/**
+ * Check if a segment tree has any routable files (page or route) anywhere.
+ */
+function hasAnyRoutable(node: SegmentNode): boolean {
+  if (node.page || node.route) return true;
+  for (const child of node.children) {
+    if (hasAnyRoutable(child)) return true;
+  }
+  for (const [, slot] of node.slots) {
+    if (hasAnyRoutable(slot)) return true;
+  }
+  return false;
+}
+
+/**
+ * Check if a segment tree has any page files (not just route handlers).
+ * Used by checkRootLayout to avoid false positives for API-only apps (TIM-794).
+ * API-only apps (just route.ts handlers) don't need a root layout.
+ */
+function hasAnyPage(node: SegmentNode): boolean {
+  if (node.page) return true;
+  for (const child of node.children) {
+    if (hasAnyPage(child)) return true;
+  }
+  for (const [, slot] of node.slots) {
+    if (hasAnyPage(slot)) return true;
+  }
+  return false;
+}
+
+// ─── Check: Route Exports ───────────────────────────────────────────────────
+
+/** HTTP methods that route.ts can export. */
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+
+/**
+ * Pattern to detect named exports that look like HTTP method handlers.
+ * Matches: export function GET, export const GET, export async function POST, etc.
+ * Also matches: export { GET } or re-exports like export { GET } from './handler'.
+ *
+ * The re-export branch uses word boundaries (\b) around method names to avoid
+ * matching substrings (e.g. TARGET should not match GET). See TIM-795.
+ */
+const EXPORT_PATTERN = new RegExp(
+  `export\\s+(?:async\\s+)?(?:function|const|let|var)\\s+(${HTTP_METHODS.join('|')})\\b` +
+    `|export\\s*\\{[^}]*\\b(${HTTP_METHODS.join('|')})\\b[^}]*\\}`
+);
+
+/**
+ * Warn when a route.ts file doesn't appear to export any recognized HTTP methods.
+ *
+ * Uses static analysis (regex on source text) — not module loading.
+ * This is intentionally conservative: it may miss complex re-exports but
+ * catches the common case of an empty route.ts or one with wrong export names.
+ */
+function checkRouteExports(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.route) {
+    const filePath = node.route.filePath;
+    try {
+      const source = readFileSync(filePath, 'utf-8');
+      if (!EXPORT_PATTERN.test(source)) {
+        // Check if there's a default export (common mistake)
+        const hasDefaultExport = /export\s+default\b/.test(source);
+        const hint = hasDefaultExport
+          ? '  It looks like you have a default export. route.ts uses named exports\n' +
+            '  for HTTP methods (GET, POST, etc.), not a default export.\n'
+          : '';
+
+        warnings.push({
+          id: 'ROUTE_NO_METHODS',
+          summary: `route.ts has no HTTP method exports: ${filePath}`,
+          details:
+            `  File: ${filePath}\n\n` +
+            '  route.ts files must export named HTTP method handlers.\n' +
+            '  Without them, the route matches but returns 405 Method Not Allowed.\n\n' +
+            hint +
+            '  Example:\n\n' +
+            '    export function GET(ctx: RouteContext) {\n' +
+            "      return Response.json({ hello: 'world' });\n" +
+            '    }\n',
+          level: 'warn',
+        });
+      }
+    } catch {
+      // Can't read the file — skip silently
+    }
+  }
+
+  // Recurse
+  for (const child of node.children) {
+    checkRouteExports(child, warnings);
+  }
+  for (const [, slot] of node.slots) {
+    checkRouteExports(slot, warnings);
+  }
+}
+
+// ─── Check: Root Layout ─────────────────────────────────────────────────────
+
+/**
+ * Warn when the root segment has no layout.tsx.
+ *
+ * Without a root layout, there's no HTML shell (<html>, <body>).
+ * The page will render but may have hydration issues or no proper document structure.
+ */
+function checkRootLayout(root: SegmentNode, warnings: ConventionWarning[]): void {
+  if (root.layout) return;
+
+  // Only warn if there are pages — API-only apps (just route.ts handlers)
+  // don't need a root layout (TIM-794).
+  if (!hasAnyPage(root)) return;
+
+  warnings.push({
+    id: 'NO_ROOT_LAYOUT',
+    summary: 'No root layout.tsx found',
+    details:
+      '  Your app has pages but no root layout.\n' +
+      '  Without app/layout.tsx, pages have no <html> or <body> wrapper.\n\n' +
+      '  To fix: Create app/layout.tsx:\n\n' +
+      '    export default function RootLayout({ children }: { children: React.ReactNode }) {\n' +
+      '      return (\n' +
+      '        <html lang="en">\n' +
+      '          <body>{children}</body>\n' +
+      '        </html>\n' +
+      '      );\n' +
+      '    }\n',
+    level: 'warn',
+  });
+}
+
+// ─── Check: Default Exports ───────────────────────────────────────────
+
+/**
+ * Pattern to detect a default export in source code.
+ * Matches: export default function, export default class, export default
+ * Also matches: export { X as default }, export { default } from './Impl'
+ *
+ * The third alternative catches bare `default` re-exports (TIM-790).
+ * The negative lookahead (?!\s+as\b) prevents matching `export { default as X }`
+ * which is a named export, not a default export (TIM-806).
+ */
+const DEFAULT_EXPORT_PATTERN =
+  /export\s+default\b|export\s*\{[^}]*\bas\s+default\b|export\s*\{[^}]*\bdefault\b(?!\s+as\b)[^}]*\}/;
+
+/**
+ * Warn when page.tsx or layout.tsx files don't have a default export.
+ *
+ * Without a default export:
+ * - page.tsx: the page renders nothing (empty content)
+ * - layout.tsx: the layout module loads but has no component to render
+ *
+ * Uses static analysis (regex on source text) — intentionally conservative.
+ */
+function checkDefaultExports(node: SegmentNode, warnings: ConventionWarning[]): void {
+  // Check page files (tsx/ts/jsx/js only — not mdx, which is default-exported by the mdx compiler)
+  if (node.page && isScriptExtension(node.page.extension)) {
+    checkFileDefaultExport(node.page.filePath, 'page', warnings);
+  }
+
+  // Check layout files
+  if (node.layout && isScriptExtension(node.layout.extension)) {
+    checkFileDefaultExport(node.layout.filePath, 'layout', warnings);
+  }
+
+  // Recurse
+  for (const child of node.children) {
+    checkDefaultExports(child, warnings);
+  }
+  for (const [, slot] of node.slots) {
+    checkDefaultExports(slot, warnings);
+  }
+}
+
+function isScriptExtension(ext: string): boolean {
+  return ext === 'tsx' || ext === 'ts' || ext === 'jsx' || ext === 'js';
+}
+
+function checkFileDefaultExport(
+  filePath: string,
+  fileType: string,
+  warnings: ConventionWarning[]
+): void {
+  try {
+    const source = readFileSync(filePath, 'utf-8');
+    if (!DEFAULT_EXPORT_PATTERN.test(source)) {
+      warnings.push({
+        id: `NO_DEFAULT_EXPORT:${filePath}`,
+        summary: `${fileType}.tsx has no default export: ${filePath}`,
+        details:
+          `  File: ${filePath}\n\n` +
+          `  ${fileType}.tsx files must export a default React component.\n` +
+          `  Without a default export, the ${fileType === 'page' ? 'page renders nothing' : 'layout has no component to wrap children'}.\n\n` +
+          `  To fix: Add a default export:\n\n` +
+          `    export default function My${fileType === 'page' ? 'Page' : 'Layout'}(${fileType === 'layout' ? '{ children }' : ''}) {\n` +
+          `      return ${fileType === 'layout' ? '<div>{children}</div>' : '<h1>Hello</h1>'};\n` +
+          `    }\n`,
+        level: 'warn',
+      });
+    }
+  } catch {
+    // Can't read file — skip silently
+  }
+}
+
+// ─── Check: App Directory Exists ────────────────────────────────────────────
+
+/**
+ * Check if the app/ directory exists. Called before scanning.
+ * Returns a warning if missing, or null if the directory exists.
+ */
+export function checkAppDirExists(appDir: string): ConventionWarning | null {
+  if (existsSync(appDir)) return null;
+
+  return {
+    id: 'NO_APP_DIR',
+    summary: 'No app/ directory found',
+    details:
+      `  Expected: ${appDir}\n\n` +
+      '  timber.js requires an app/ directory for file-system routing.\n' +
+      '  Every request will return 404 until you create it.\n\n' +
+      '  To fix: Create the app/ directory with a page:\n\n' +
+      '    mkdir -p app\n' +
+      '    # Create app/layout.tsx and app/page.tsx\n',
+    level: 'error',
+  };
+}
+
+// ─── Formatting ─────────────────────────────────────────────────────────────
+
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * Format warnings for terminal output.
+ *
+ * Groups by severity, uses colors, and includes fix suggestions.
+ */
+export function formatConventionWarnings(warnings: ConventionWarning[]): string {
+  if (warnings.length === 0) return '';
+
+  const errors = warnings.filter((w) => w.level === 'error');
+  const warns = warnings.filter((w) => w.level === 'warn');
+
+  const lines: string[] = [];
+
+  if (errors.length > 0) {
+    lines.push(
+      `${RED}${BOLD}[timber]${RESET} ${RED}${errors.length} configuration error${errors.length !== 1 ? 's' : ''}:${RESET}`
+    );
+    for (const e of errors) {
+      lines.push('');
+      lines.push(`  ${RED}✗${RESET} ${e.summary}`);
+      lines.push(`${DIM}${e.details}${RESET}`);
+    }
+  }
+
+  if (warns.length > 0) {
+    if (errors.length > 0) lines.push('');
+    lines.push(
+      `${YELLOW}${BOLD}[timber]${RESET} ${YELLOW}${warns.length} configuration warning${warns.length !== 1 ? 's' : ''}:${RESET}`
+    );
+    for (const w of warns) {
+      lines.push('');
+      lines.push(`  ${YELLOW}⚠${RESET} ${w.summary}`);
+      lines.push(`${DIM}${w.details}${RESET}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/routing/index.ts

@@ -12,3 +12,5 @@ export type {
 export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
 export { collectInterceptionRewrites } from './interception.js';
 export type { InterceptionRewrite } from './interception.js';
+export { classifyUrlSegment } from './segment-classify.js';
+export type { UrlSegment } from './segment-classify.js';

package/src/routing/link-codegen.ts

@@ -0,0 +1,262 @@
+/**
+ * Typed `<Link>` codegen — interface augmentation generation.
+ *
+ * Extracted from `codegen.ts` to keep that file under the project's
+ * 500-line cap. This module owns everything that emits the
+ * `interface LinkFunction { ... }` augmentation blocks in the generated
+ * `.timber/timber-routes.d.ts`.
+ *
+ * Two augmentation blocks are emitted:
+ *
+ * 1. **Per-route discriminated union** (`formatTypedLinkOverloads`) —
+ *    one call signature whose props is a union keyed on `href`. TS
+ *    narrows by literal href and reports prop errors against the
+ *    matched variant. See TIM-835 and `design/09-typescript.md`.
+ *
+ * 2. **Catch-all overloads** (`formatLinkCatchAllOverloads`) — external
+ *    href literals (`http://`, `mailto:`, etc.) and a computed-string
+ *    `<H extends string>` signature for runtime-computed paths.
+ *
+ * Block ordering is critical for error UX: per-route is emitted FIRST
+ * so that, after TS's "later overload set ordered first" merge rule,
+ * the discriminated union ends up LAST in resolution order — the
+ * overload TS reports against on failure.
+ */
+
+import type { ParamEntry, RouteEntry } from './codegen-types.js';
+import { buildCodecChainType, formatSearchParamsType } from './codegen-shared.js';
+
+/** Shared Link base-props type literal used in every emitted call signature. */
+export 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 }";
+
+/**
+ * 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}'
+ */
+export 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('/');
+}
+
+/**
+ * Format the segmentParams 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`.
+ *
+ * When the segment's params chain (TIM-834) declares a typed codec, the
+ * inferred type from the codec wins via a nested conditional.
+ */
+export function formatLinkParamsType(params: ParamEntry[], importBase?: string): string {
+  if (params.length === 0) {
+    return '{}';
+  }
+
+  const fields = params.map((p) => {
+    const fallback = p.type === 'string' ? 'string | number' : p.type;
+    const codecType = buildCodecChainType(p, importBase, fallback);
+    return `${p.name}: ${codecType}`;
+  });
+  return `{ ${fields.join('; ')} }`;
+}
+
+/**
+ * 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.
+ */
+export 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.
+ *
+ * TIM-835: This emits a SINGLE call signature whose props is a
+ * discriminated union keyed on `href`. TypeScript narrows the union by
+ * the literal `href` at the call site, then checks the rest of the
+ * props against the matched variant. When `segmentParams` or
+ * `searchParams` is wrong, TS reports the error against the matched
+ * variant — naming the user's actual `href` and the offending field.
+ *
+ * Before TIM-835, this function emitted N separate per-route overloads
+ * (one per route, sometimes two for dynamic routes). When ALL overloads
+ * failed, TS would pick an arbitrary failed overload (heuristically the
+ * "last tried") to render the diagnostic, often pointing at a route
+ * completely unrelated to the one the user wrote. The discriminated
+ * union sidesteps overload-resolution heuristics entirely.
+ *
+ * Open property shapes (`Record<string, unknown>` instead of `never`)
+ * for `segmentParams` on routes that don't declare them keep generic
+ * `LinkProps`-spreading wrappers compiling. (Aligned with TIM-833.)
+ *
+ * TIM-832: this function still emits the per-route block FIRST and the
+ * catch-all block follows, so per-route remains the LAST overload set in
+ * resolution order — the one TS reports against on failure. With a
+ * discriminated union there is only one call signature in this block,
+ * so the resolved-template-vs-pattern ordering reduces to placing the
+ * pattern variant before the resolved-template variant inside the union.
+ */
+export function formatTypedLinkOverloads(routes: RouteEntry[], importBase?: string): string[] {
+  const lines: string[] = [];
+  const baseProps = LINK_BASE_PROPS_TYPE;
+
+  // Build the union variants. Each route contributes one variant for the
+  // pattern href (e.g. '/products/[id]') and, for dynamic routes, an
+  // additional variant for the resolved-template href (e.g.
+  // `/products/${string}`).
+  //
+  // The PATTERN variant must be listed BEFORE the resolved-template
+  // variant for the same route so that when the user writes the literal
+  // pattern href (`<Link href="/products/[id]" />`), TS narrows to the
+  // pattern variant (which carries the typed `segmentParams` shape)
+  // rather than the looser resolved-template variant. Without this
+  // ordering, TS would silently match the resolved-template variant
+  // first — swallowing typed-segmentParams type errors.
+  const variants: string[] = [];
+  for (const route of routes) {
+    const hasDynamicParams = route.params.length > 0;
+    // For routes with no dynamic params, accept an absent OR open-shape
+    // segmentParams. `Record<string, unknown>` keeps generic spreads
+    // compiling and gives a readable error if a non-object is passed.
+    const paramsProp = hasDynamicParams
+      ? `segmentParams: ${formatLinkParamsType(route.params, importBase)}`
+      : 'segmentParams?: Record<string, unknown>';
+
+    const searchParamsType = route.hasSearchParams
+      ? formatSearchParamsType(route, importBase)
+      : null;
+    // TIM-830: pattern href uses the FLAT `Partial<T>` shape — the
+    // runtime registry is keyed by the un-interpolated pattern.
+    //
+    // TIM-835: when the route has NO searchParams definition, use
+    // `Record<string, never>` (forbids any keys) instead of
+    // `Record<string, unknown>` so passing unexpected query params is a
+    // type error. Generic-spread compatibility is preserved by the
+    // matching open shape on `segmentParams` (which is the prop users
+    // typically forward through wrapper components).
+    const patternSearchParamsProp = searchParamsType
+      ? `searchParams?: Partial<${searchParamsType}>`
+      : 'searchParams?: Record<string, never>';
+
+    // Pattern variant FIRST (more specific).
+    variants.push(
+      `${baseProps} & { href: '${route.urlPath}'; ${paramsProp}; ${patternSearchParamsProp} }`
+    );
+
+    // Resolved-template variant SECOND (looser, matches interpolated hrefs).
+    if (hasDynamicParams) {
+      const templatePattern = buildResolvedPattern(route);
+      if (templatePattern) {
+        // TIM-830: resolved-template href keeps the WRAPPED
+        // `{ definition, values }` shape — the registry can't be looked
+        // up by an already-interpolated href.
+        const resolvedSearchParamsProp = searchParamsType
+          ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
+          : 'searchParams?: Record<string, never>';
+        // TIM-835: `Record<string, never>` for segmentParams forbids ANY
+        // provided keys on the resolved-template variant. Without this,
+        // the resolved-template would shadow the pattern variant for
+        // literal pattern hrefs (`<Link href="/products/[id]" segmentParams={...} />`)
+        // because both variants accept the literal `'/products/[id]'`
+        // and the looser variant would silently swallow segmentParams
+        // type errors.
+        variants.push(
+          `${baseProps} & { href: \`${templatePattern}\`; segmentParams?: Record<string, never>; ${resolvedSearchParamsProp} }`
+        );
+      }
+    }
+  }
+
+  lines.push('  interface LinkFunction {');
+  if (variants.length === 0) {
+    // No page routes — emit nothing. The catch-all block in the second
+    // augmentation still provides external/computed-string signatures.
+    lines.push('  }');
+    return lines;
+  }
+  lines.push('    (');
+  lines.push('      props:');
+  for (const variant of variants) {
+    lines.push(`        | (${variant})`);
+  }
+  lines.push(`    ): import('react').JSX.Element`);
+  lines.push('  }');
+
+  return lines;
+}