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

package/src/routing/codegen.ts

@@ -12,14 +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 { buildSchemaParamType } from './codegen-shared.js';
 import { effectiveUrlSegment, type UrlSegmentIdentity } from './segment-classify.js';
-import { fileHasExport } from './export-detect.js';
 import { formatLinkCatchAllOverloads, formatTypedLinkOverloads } from './link-codegen.js';
 
 /** Options for route map generation. */
@@ -50,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));
@@ -81,7 +75,6 @@ function detectSchema(appDir: string | undefined): boolean {
 function collectRoutes(
   node: SegmentNode,
   ancestorParams: ParamEntry[],
-  ancestorParamsFiles: string[],
   parentTreePath: string,
   routes: RouteEntry[],
   hasSchema: boolean,
@@ -91,23 +84,7 @@ function collectRoutes(
   // 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
@@ -120,72 +97,44 @@ function collectRoutes(
   const urlSegment = effectiveUrlSegment(node);
   const params = [...ancestorParams];
   if (urlSegment.paramName) {
-    const legacyFallback = ownParamsFile ? undefined : findLegacyParamsExport(node);
     params.push({
       name: urlSegment.paramName,
       bracketName: bracketNameForSegment(urlSegment),
       type: paramTypeForSegment(urlSegment.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,
     });
   }
 
-  // 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);
   }
 
@@ -195,44 +144,30 @@ function collectRoutes(
   // alone was not enough.
   for (const child of node.children) {
     const childIntercepting = insideIntercepting || child.segmentType === 'intercepting';
-    collectRoutes(
-      child,
-      params,
-      nextAncestorFiles,
-      treePath,
-      routes,
-      hasSchema,
-      insideSlot,
-      childIntercepting
-    );
+    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,
-      insideIntercepting
-    );
+    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
@@ -247,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()];
 }
@@ -296,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.
@@ -436,14 +340,6 @@ 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.
   //
@@ -451,18 +347,23 @@ function formatDeclarationFile(
   // 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.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(`    }`);
   }
 
@@ -493,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}`
       );
@@ -511,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'");
     }
@@ -522,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}`
         );
@@ -535,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.
     //
@@ -555,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('');
     }
 
@@ -580,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`,

package/src/routing/convention-lint.ts

@@ -4,17 +4,25 @@
  * 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).
+ * Most checks are warnings — 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).
+ *
+ * A check emits `level: 'error'` only when the misconfiguration is *proven*
+ * (never inferred from an absence the analysis cannot see through) and fatal
+ * to rendering. `plugins/routing.ts` turns those into a thrown build error,
+ * so a false positive there refuses a working app — see
+ * `classifyClientBoundaryFile` for how that bar is met.
  *
  * Design doc: 07-routing.md, 10-error-handling.md
  */
 
 import { existsSync } from 'node:fs';
-import type { RouteTree, SegmentNode } from './types.js';
+import type { RouteFile, RouteTree, SegmentNode } from './types.js';
 import { swallow } from '../server/logger.js';
+import { isMdxFilePath } from '../server/utils/mdx-file.js';
 import {
+  fileDefaultExportIsLocalValue,
   fileHasAnyExport,
   fileHasDefaultExport,
   fileHasDirective,
@@ -61,10 +69,10 @@ export function lintConventions(tree: RouteTree, appDir: string): ConventionWarn
   // Check 5: page.tsx / layout.tsx without default export
   checkDefaultExports(tree.root, warnings);
 
-  // Check 6: error.tsx / global-error.tsx without 'use client' directive
-  checkErrorDirectives(tree.root, warnings);
-  if (tree.globalError && isScriptExtension(tree.globalError.extension)) {
-    checkFileUseClientDirective(tree.globalError.filePath, 'global-error', warnings);
+  // Check 6: error.tsx / 404.tsx / 4xx.tsx / … without 'use client' directive
+  checkClientBoundaryFiles(tree.root, warnings);
+  if (tree.globalError) {
+    checkFileUseClientDirective(tree.globalError, 'global-error', warnings);
   }
 
   return warnings;
@@ -272,54 +280,132 @@ function checkFileDefaultExport(
   }
 }
 
-// ─── Check: Error Directive ─────────────────────────────────────────────────
+// ─── Check: Client Boundary Directive ───────────────────────────────────────
 
 /**
- * Warn when error.tsx or global-error.tsx is missing 'use client'.
+ * Check every file the renderer hands to `TimberErrorBoundary` as a component
+ * prop: `error.tsx`, `global-error.tsx`, and the status-code family
+ * (`404.tsx`, `4xx.tsx`, `503.tsx`, …).
+ *
+ * `TimberErrorBoundary` is a client component, so a server component passed as
+ * `fallbackComponent` is a function crossing the RSC → client boundary. React
+ * Flight refuses to serialize it, and because the boundary wraps the segment's
+ * *children*, the failure hits every page under that segment — not just the
+ * error path. The raw message ("Functions cannot be passed directly to Client
+ * Components") names neither the file nor the fix (TIM-1329).
  *
- * React's error boundary API requires client components. Without the directive,
- * the error boundary silently fails — the component renders as a server component
- * with no error catching. Users discover this only via cryptic runtime errors.
+ * MDX status files are exempt: they are server components by design and the
+ * renderer pre-renders them into `fallbackElement` instead. See TIM-503 and
+ * `server/error-boundary-wrapper.ts`.
+ *
+ * `.json` status files never reach React at all, and are not in `statusFiles`.
  */
-function checkErrorDirectives(node: SegmentNode, warnings: ConventionWarning[]): void {
-  if (node.error && isScriptExtension(node.error.extension)) {
-    checkFileUseClientDirective(node.error.filePath, 'error', warnings);
+function checkClientBoundaryFiles(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.error) {
+    checkFileUseClientDirective(node.error, 'error', warnings);
+  }
+
+  for (const [key, file] of Object.entries(node.statusFiles ?? {})) {
+    checkFileUseClientDirective(file, key, warnings);
   }
 
   for (const child of node.children) {
-    checkErrorDirectives(child, warnings);
+    checkClientBoundaryFiles(child, warnings);
   }
   for (const slot of Object.values(node.slots)) {
-    checkErrorDirectives(slot, warnings);
+    checkClientBoundaryFiles(slot, warnings);
   }
 }
 
+/**
+ * `'client'` — carries the directive.
+ * `'server'` — proven server component: no directive, and the default export is
+ *   a function or class built by this very module, so no other file's directive
+ *   can be governing it.
+ * `'unknown'` — no directive, but the exported value may come from elsewhere
+ *   (`export { default } from './client-thing'`), or the file could not be
+ *   read or parsed. Never escalated to a build error.
+ */
+type ClientBoundaryVerdict = 'client' | 'server' | 'unknown';
+
+function classifyClientBoundaryFile(filePath: string): ClientBoundaryVerdict {
+  if (fileHasDirective(filePath, 'use client')) return 'client';
+  if (fileDefaultExportIsLocalValue(filePath)) return 'server';
+  return 'unknown';
+}
+
+/** Example component name for the fix snippet, keyed by convention name. */
+function exampleComponentName(convention: string): string {
+  if (convention === 'global-error') return 'GlobalError';
+  if (convention === 'error') return 'ErrorBoundary';
+  if (convention === '404') return 'NotFound';
+  return 'StatusPage';
+}
+
+/**
+ * @param file      the route file (its extension decides whether the check applies)
+ * @param convention the convention name — `error`, `global-error`, `404`, `4xx`, …
+ */
 function checkFileUseClientDirective(
-  filePath: string,
-  fileType: string,
+  file: RouteFile,
+  convention: string,
   warnings: ConventionWarning[]
 ): void {
+  // MDX/markdown status and error files are server components by design — the
+  // renderer pre-renders them into `fallbackElement`, so they never cross the
+  // boundary as a function.
+  //
+  // The exemption is the *complement* of the renderer's own test, using the
+  // renderer's own helper: everything `error-boundary-wrapper.ts` and
+  // `error-renderer.ts` do not treat as MDX, they pass as a component. An
+  // independent "is this a script extension?" list here would be a second
+  // expression of that fact, free to drift into a gap where a file is a
+  // component to the renderer and exempt to the linter.
+  if (isMdxFilePath(file.filePath)) return;
+
+  const filePath = file.filePath;
+  const label = `${convention}.${file.extension}`;
+  let verdict: ClientBoundaryVerdict;
   try {
-    if (!fileHasDirective(filePath, 'use client')) {
-      warnings.push({
-        id: `ERROR_NO_USE_CLIENT:${filePath}`,
-        summary: `${fileType}.tsx is missing 'use client': ${filePath}`,
-        details:
-          `  File: ${filePath}\n\n` +
-          `  ${fileType}.tsx must start with 'use client' because React error\n` +
-          '  boundaries require client components. Without it, the error boundary\n' +
-          '  silently fails and errors are uncaught.\n\n' +
-          "  To fix: Add 'use client' as the first line of the file:\n\n" +
-          "    'use client';\n\n" +
-          `    export default function ${fileType === 'global-error' ? 'GlobalError' : 'ErrorBoundary'}({ error, reset }) {\n` +
-          '      return <div><h2>Something went wrong</h2><button onClick={reset}>Try again</button></div>;\n' +
-          '    }\n',
-        level: 'warn',
-      });
-    }
+    verdict = classifyClientBoundaryFile(filePath);
   } catch (err) {
-    swallow(err, `convention-lint: unreadable ${fileType} file ${filePath}`);
+    swallow(err, `convention-lint: unreadable ${label} file ${filePath}`);
+    return;
   }
+  if (verdict === 'client') return;
+
+  const isError = verdict === 'server';
+  const name = exampleComponentName(convention);
+  const props =
+    convention === 'error' || convention === 'global-error' ? '{ error, reset }' : '{ status }';
+
+  warnings.push({
+    id: `NEEDS_USE_CLIENT:${filePath}`,
+    summary: isError
+      ? `${label} is a server component and must be a client component: ${filePath}`
+      : `${label} may be missing 'use client': ${filePath}`,
+    details:
+      `  File: ${filePath}\n\n` +
+      `  ${label} is handed to timber's error boundary — a client\n` +
+      '  component — as a prop. A server component cannot cross that boundary:\n' +
+      '  React fails with "Functions cannot be passed directly to Client\n' +
+      '  Components", and every page under this segment fails to render.\n\n' +
+      (isError
+        ? "  To fix: Add 'use client' as the first line of the file:\n\n" +
+          "    'use client';\n\n" +
+          `    export default function ${name}(${props}) {\n` +
+          '      return <h1>…</h1>;\n' +
+          '    }\n'
+        : // The default export comes from somewhere this analysis cannot follow
+          // — a re-export, an imported binding, a wrapper call. It may well
+          // already be a client component, so say what was checked rather than
+          // assert a break.
+          "  This file has no 'use client' directive, and its default export\n" +
+          '  comes from elsewhere, so timber cannot tell which it is. If the\n' +
+          "  module it re-exports starts with 'use client', nothing is wrong\n" +
+          '  and you can ignore this. Otherwise add the directive there.\n'),
+    level: isError ? 'error' : 'warn',
+  });
 }
 
 // ─── Check: App Directory Exists ────────────────────────────────────────────
@@ -352,14 +438,27 @@ import { styleText } from 'node:util';
 
 type Format = InspectColor | readonly InspectColor[];
 const noValidate = { validateStream: false } as const;
-const style = (fmt: Format, text: string) => styleText(fmt, text, noValidate);
+
+export interface FormatOptions {
+  /**
+   * Emit ANSI escapes. Off when the text becomes an `Error` message —
+   * whoever prints it decides its formatting, and colored escapes inside
+   * an exception leak into logs and stack traces.
+   */
+  color?: boolean;
+}
 
 /**
  * Format warnings for terminal output.
  *
  * Groups by severity, uses colors, and includes fix suggestions.
  */
-export function formatConventionWarnings(warnings: ConventionWarning[]): string {
+export function formatConventionWarnings(
+  warnings: ConventionWarning[],
+  options: FormatOptions = {}
+): string {
+  const { color = true } = options;
+  const style = (fmt: Format, text: string) => (color ? styleText(fmt, text, noValidate) : text);
   if (warnings.length === 0) return '';
 
   const errors = warnings.filter((w) => w.level === 'error');