@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/routing/convention-lint.ts

@@ -0,0 +1,651 @@
+/**
+ * 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 } from 'node:fs';
+import type { RouteFile, RouteTree, SegmentNode } from './types.ts';
+import { swallow } from '../server/logger.ts';
+import {
+  fileDefaultExportIsLocalValue,
+  fileHasAnyExport,
+  fileHasDefaultExport,
+  fileHasDirective,
+  fileHasStarExport,
+  getCsrfExport,
+} 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: middleware.ts inside a parallel slot subtree (silently dead)
+  checkSlotMiddleware(tree.root, warnings);
+
+  // Check 9: `export const csrf` anywhere but route.ts, or in a form the
+  // scanner cannot read (TIM-1543)
+  checkCsrfExports(tree.root, warnings);
+  if (tree.proxy) checkCsrfExport(tree.proxy, 'proxy.ts', warnings);
+  if (tree.globalError) checkCsrfExport(tree.globalError, 'global-error', 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: CSRF Exemption Export ──────────────────────────────────────────
+
+/** Single-file segment conventions other than route.ts. */
+const NON_ROUTE_FILE_KEYS = [
+  'page',
+  'layout',
+  'middleware',
+  'access',
+  'error',
+  'default',
+  'denied',
+] as const satisfies readonly (keyof SegmentNode)[];
+
+/**
+ * Fail the build on a `csrf` export the CSRF gate would not honor.
+ *
+ * Both findings are proven from source, and both are fatal in the sense
+ * the error level requires: the developer wrote an exemption that silently
+ * does nothing, so a legitimate cross-site POST they meant to accept gets
+ * a 403 in production, or they believe a page or action is exempt when
+ * the gate still protects it. The exemption exists only on route.ts —
+ * server actions always get the check (design/08 §"Per-route exemption").
+ * A `'use server'` module cannot export it at all: plugin-rsc rejects every
+ * non-async-function export there.
+ */
+function checkCsrfExports(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.route) checkCsrfExport(node.route, 'route.ts', warnings);
+  for (const key of NON_ROUTE_FILE_KEYS) {
+    const file = node[key];
+    if (file) checkCsrfExport(file, key, warnings);
+  }
+  // Status files and metadata routes (sitemap.ts, opengraph-image.tsx, …).
+  // JSON status files are skipped by the script-extension check.
+  for (const [name, file] of Object.entries(node.statusFiles ?? {})) {
+    checkCsrfExport(file, name, warnings);
+  }
+  for (const [name, file] of Object.entries(node.metadataRoutes ?? {})) {
+    checkCsrfExport(file, name, warnings);
+  }
+  for (const child of node.children) checkCsrfExports(child, warnings);
+  for (const slot of Object.values(node.slots)) checkCsrfExports(slot, warnings);
+}
+
+function checkCsrfExport(file: RouteFile, convention: string, warnings: ConventionWarning[]): void {
+  if (!isScriptExtension(file.extension)) return;
+  const found = getCsrfExport(file.filePath);
+  if (found === 'absent') return;
+  const isRoute = convention === 'route.ts';
+  if (isRoute && found === 'exempt') return;
+  warnings.push({
+    id: `CSRF_EXPORT_INVALID:${file.filePath}`,
+    summary: isRoute
+      ? `route.ts csrf export must be exactly \`export const csrf = false\`: ${file.filePath}`
+      : `\`csrf\` can only be exported from route.ts, not ${convention}: ${file.filePath}`,
+    details:
+      `  File: ${file.filePath}\n\n` +
+      (isRoute
+        ? '  The CSRF gate reads this export from source before any module loads, so only\n' +
+          '  the literal form counts. Other values, `let`, and re-exports are not read.\n\n' +
+          '  To fix: write `export const csrf = false;` in this file, or remove the export.\n'
+        : '  The per-route CSRF exemption applies only to route.ts handlers. Pages, layouts\n' +
+          '  and server actions always get the CSRF check.\n\n' +
+          '  To fix: remove the export. To accept a cross-site POST, handle it in a route.ts\n' +
+          '  that exports `const csrf = false`.\n'),
+    level: 'error',
+  });
+}
+
+// ─── 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).
+ *
+ * `.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 {
+  // Only script extensions need the 'use client' check — .json status files
+  // never reach React at all, and are not in `statusFiles`.
+  if (!isScriptExtension(file.extension)) 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: Slot Middleware ─────────────────────────────────────────────────
+
+/**
+ * Error when middleware.ts appears inside a parallel slot subtree.
+ *
+ * Middleware is collected from the main matched segment chain only
+ * (route-matcher.ts `collectMiddlewareChain`). The slot resolver never
+ * walks `middleware` on its matched chain, so a middleware.ts under any
+ * `@slot/` directory silently never executes. `access.ts` in slot chains
+ * DOES run (via SlotAccessGate), making the asymmetry invisible unless
+ * you know to look.
+ *
+ * This is a build error rather than a warning: the file provably cannot
+ * run and its presence misleads the author into thinking the slot is
+ * middleware-protected.
+ *
+ * See design/07-routing.md §"Parallel Routes"
+ */
+function checkSlotMiddleware(node: SegmentNode, warnings: ConventionWarning[]): void {
+  for (const [slotName, slotRoot] of Object.entries(node.slots)) {
+    collectSlotMiddleware(slotRoot, slotName, warnings);
+  }
+  for (const child of node.children) {
+    checkSlotMiddleware(child, warnings);
+  }
+}
+
+/**
+ * Walk a slot subtree and report every middleware.ts found.
+ */
+function collectSlotMiddleware(
+  node: SegmentNode,
+  slotName: string,
+  warnings: ConventionWarning[]
+): void {
+  if (node.middleware) {
+    warnings.push({
+      id: `SLOT_MIDDLEWARE:${node.middleware.filePath}`,
+      summary: `middleware.ts inside slot @${slotName} never executes: ${node.middleware.filePath}`,
+      details:
+        `  File: ${node.middleware.filePath}\n\n` +
+        `  Middleware is collected from the main route chain only.\n` +
+        `  The slot resolver does not run middleware — this file is silently dead.\n` +
+        `  (access.ts in slots does run via SlotAccessGate; middleware.ts does not.)\n\n` +
+        `  To fix: Move the middleware logic into access.ts for slot-scoped auth,\n` +
+        `  or into a middleware.ts on the main route chain outside the slot.\n`,
+      level: 'error',
+    });
+  }
+  for (const child of node.children) {
+    collectSlotMiddleware(child, slotName, warnings);
+  }
+  for (const [nestedSlotName, nestedSlot] of Object.entries(node.slots)) {
+    collectSlotMiddleware(nestedSlot, nestedSlotName, warnings);
+  }
+}
+
+// ─── 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');
+}