@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/routing/convention-lint.ts

@@ -0,0 +1,623 @@
+/**
+ * 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.
+ *
+ * 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, readFileSync } from 'node:fs';
+import type { RouteFile, RouteTree, SegmentNode } from './types.ts';
+import { swallow } from '../server/logger.ts';
+import { isMdxFilePath } from '../server/utils/mdx-file.ts';
+import {
+  fileDefaultExportIsLocalValue,
+  fileHasAnyExport,
+  fileHasDefaultExport,
+  fileHasDirective,
+  fileHasStarExport,
+} from './export-detect.ts';
+
+// ─── 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);
+
+  // Check 6: Client layouts cannot suppress server children before Flight
+  // serializes them. They remain valid UI boundaries, but not authorization
+  // or data-hiding boundaries.
+  checkClientLayouts(tree.root, warnings);
+
+  // Check 7: error.tsx / 404.tsx / 4xx.tsx / … without 'use client' directive
+  checkClientBoundaryFiles(tree.root, warnings);
+  if (tree.globalError) {
+    checkFileUseClientDirective(tree.globalError, 'global-error', warnings);
+  }
+
+  // Check 8: Wildcard MDX status files (4xx.mdx, 5xx.mdx, error.mdx) that
+  // reference `props` — props resolve on deny and throw paths but are empty
+  // on the boundary path. See design/10-error-handling.md §"MDX Props by Path".
+  checkWildcardMdxProps(tree.root, warnings);
+
+  return warnings;
+}
+
+function checkClientLayouts(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.layout && isScriptExtension(node.layout.extension)) {
+    try {
+      const isClient = fileHasDirective(node.layout.filePath, 'use client');
+      const isProvablyServer = fileDefaultExportIsLocalValue(node.layout.filePath);
+      if (isClient || !isProvablyServer) {
+        const certainty = isClient
+          ? `This layout is a client component.`
+          : `Timber cannot prove this layout is a server component because its default export comes from another module or an opaque expression.`;
+        warnings.push({
+          id: `CLIENT_LAYOUT_NOT_AUTH_BOUNDARY:${node.layout.filePath}`,
+          summary: isClient
+            ? `Client layout cannot securely suppress server children: ${node.layout.filePath}`
+            : `Layout may resolve to a client component and cannot be trusted as an auth boundary: ${node.layout.filePath}`,
+          details:
+            `  File: ${node.layout.filePath}\n\n` +
+            `  ${certainty}\n` +
+            `  React Flight resolves server content passed to a client layout before the layout runs in the browser.\n` +
+            `  Conditionally omitting children here does not prevent descendant server components from executing or being serialized.\n\n` +
+            `  To fix: Put authorization in access.ts or a provably server layout with a locally defined default component, and keep client components inside that boundary.\n`,
+          level: 'warn',
+        });
+      }
+    } catch (err) {
+      swallow(err, `convention-lint: unreadable layout file ${node.layout.filePath}`);
+    }
+  }
+  for (const child of node.children) checkClientLayouts(child, warnings);
+  for (const slot of Object.values(node.slots)) checkClientLayouts(slot, 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 Object.values(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 Object.values(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'] as const;
+
+/**
+ * Warn when a route.ts file doesn't appear to export any recognized HTTP methods.
+ *
+ * Uses AST-based detection via parseAst for precise matching.
+ * Falls back silently when the file can't be parsed (syntax errors produce
+ * no spurious warning — the TS compiler will catch those).
+ */
+function checkRouteExports(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.route) {
+    const filePath = node.route.filePath;
+    try {
+      const methods = fileHasAnyExport(filePath, HTTP_METHODS);
+      if (methods.size === 0 && !fileHasStarExport(filePath)) {
+        const hasDefault = fileHasDefaultExport(filePath);
+        const hint = hasDefault
+          ? '  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 (err) {
+      swallow(err, `convention-lint: unreadable route.ts ${filePath}`);
+    }
+  }
+
+  // Recurse
+  for (const child of node.children) {
+    checkRouteExports(child, warnings);
+  }
+  for (const slot of Object.values(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 ───────────────────────────────────────────
+
+/**
+ * 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 AST-based detection via parseAst for precise matching. Falls back
+ * silently when the file can't be parsed (no spurious warning on syntax errors).
+ */
+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 Object.values(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 {
+    if (!fileHasDefaultExport(filePath)) {
+      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 (err) {
+    swallow(err, `convention-lint: unreadable ${fileType} file ${filePath}`);
+  }
+}
+
+// ─── Check: Client Boundary Directive ───────────────────────────────────────
+
+/**
+ * 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).
+ *
+ * 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 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) {
+    checkClientBoundaryFiles(child, warnings);
+  }
+  for (const slot of Object.values(node.slots)) {
+    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(
+  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 {
+    verdict = classifyClientBoundaryFile(filePath);
+  } catch (err) {
+    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: Wildcard MDX Props ──────────────────────────────────────────────
+
+/**
+ * Wildcard status file keys in `statusFiles` whose props differ by path.
+ * `error` is not here — the scanner stores it in `node.error`, not
+ * `node.statusFiles`, and the check handles it separately below.
+ */
+const WILDCARD_MDX_STATUS_KEYS = new Set(['4xx', '5xx']);
+
+/**
+ * Warn when a wildcard MDX status file (`4xx.mdx`, `5xx.mdx`, `error.mdx`)
+ * appears to reference `props` in its source.
+ *
+ * These files are pre-rendered into `fallbackElement` on the error-boundary
+ * path, before the error happens, so they receive empty or partial props.
+ * On the deny and error-renderer paths they receive the real props. An author
+ * writing `{props.status}` gets the number on some paths and `undefined` on
+ * others — same source, different output.
+ *
+ * A text scan for `props` is acceptable here because the check is `level:
+ * 'warn'` — a false positive costs a printed line, not a refused build. A
+ * sound check would need the MDX compiler, which is optional, async, and
+ * scoped to the RSC environment. See TIM-1333.
+ *
+ * Exact-code MDX files (e.g. `503.mdx`) are unaffected — all four paths
+ * agree on their status.
+ */
+function checkWildcardMdxProps(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.statusFiles) {
+    for (const [key, file] of Object.entries(node.statusFiles)) {
+      if (WILDCARD_MDX_STATUS_KEYS.has(key) && isMdxFilePath(file.filePath)) {
+        checkMdxFileForProps(file.filePath, key, warnings);
+      }
+    }
+  }
+  if (node.error && isMdxFilePath(node.error.filePath)) {
+    checkMdxFileForProps(node.error.filePath, 'error', warnings);
+  }
+
+  for (const child of node.children) {
+    checkWildcardMdxProps(child, warnings);
+  }
+  for (const slot of Object.values(node.slots)) {
+    checkWildcardMdxProps(slot, warnings);
+  }
+}
+
+/**
+ * Check if an MDX file's source appears to reference `props`.
+ *
+ * MDX passes a `props` object to the default export function. A reference to
+ * `props.status` or `props.dangerouslyPassData` in a wildcard file works on
+ * the deny/throw paths but renders `undefined` on the boundary path.
+ */
+function checkMdxFileForProps(
+  filePath: string,
+  convention: string,
+  warnings: ConventionWarning[]
+): void {
+  let source: string;
+  try {
+    source = readFileSync(filePath, 'utf-8');
+  } catch {
+    return;
+  }
+
+  // MDX exposes props via the default export: export default function(props) { ... }
+  // and via JSX expressions: {props.status}. A text scan is intentionally
+  // broad — false positives are cheap at warn level.
+  if (!/\bprops\b/.test(source)) return;
+
+  const label = `${convention}.${filePath.endsWith('.md') ? 'md' : 'mdx'}`;
+  warnings.push({
+    id: `MDX_WILDCARD_PROPS:${filePath}`,
+    summary: `${label} references props, which are empty on the error boundary path: ${filePath}`,
+    details:
+      `  File: ${filePath}\n\n` +
+      `  Wildcard MDX status files (${convention}.mdx) are pre-rendered into\n` +
+      '  fallbackElement before the error occurs. On that path, props are\n' +
+      `  empty${convention === 'error' ? '' : ' (no status, no dangerouslyPassData)'}. On the deny() and error-renderer\n` +
+      '  paths, props.status resolves correctly.\n\n' +
+      '  If this file uses only static content and "props" appears in prose,\n' +
+      '  this warning is a false positive — ignore it.\n\n' +
+      '  To fix: Use only static content in wildcard MDX status files, or\n' +
+      '  use an exact-code file (e.g. 404.mdx) where all paths agree.\n',
+    level: 'warn',
+  });
+}
+
+// ─── 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 ─────────────────────────────────────────────────────────────
+
+import type { InspectColor } from 'node:util';
+import { styleText } from 'node:util';
+
+type Format = InspectColor | readonly InspectColor[];
+const noValidate = { validateStream: false } as const;
+
+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[],
+  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');
+  const warns = warnings.filter((w) => w.level === 'warn');
+
+  const lines: string[] = [];
+
+  if (errors.length > 0) {
+    lines.push(
+      `${style(['red', 'bold'], '[timber]')} ${style('red', `${errors.length} configuration error${errors.length !== 1 ? 's' : ''}:`)}`
+    );
+    for (const e of errors) {
+      lines.push('');
+      lines.push(`  ${style('red', '✗')} ${e.summary}`);
+      lines.push(style('dim', e.details));
+    }
+  }
+
+  if (warns.length > 0) {
+    if (errors.length > 0) lines.push('');
+    lines.push(
+      `${style(['yellow', 'bold'], '[timber]')} ${style('yellow', `${warns.length} configuration warning${warns.length !== 1 ? 's' : ''}:`)}`
+    );
+    for (const w of warns) {
+      lines.push('');
+      lines.push(`  ${style('yellow', '⚠')} ${w.summary}`);
+      lines.push(style('dim', w.details));
+    }
+  }
+
+  return lines.join('\n');
+}