@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/src/routing/convention-lint.ts

@@ -0,0 +1,493 @@
+/**
+ * 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.js';
+import { swallow } from '../server/logger.js';
+import { isMdxFilePath } from '../server/utils/mdx-file.js';
+import {
+  fileDefaultExportIsLocalValue,
+  fileHasAnyExport,
+  fileHasDefaultExport,
+  fileHasDirective,
+  fileHasStarExport,
+} from './export-detect.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);
+
+  // 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;
+}
+
+// ─── 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: 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');
+}