@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/src/routing/convention-lint.ts

@@ -0,0 +1,394 @@
+/**
+ * Convention linter — validates common misconfigurations in the route tree.
+ *
+ * Runs at scan time (build and dev startup). Each check produces a warning
+ * with the file path, what's wrong, and what to do about it.
+ *
+ * These are warnings, not errors — they don't block the build. The goal is
+ * to catch issues that would otherwise produce cryptic runtime behavior
+ * (silent 404s, empty pages, confusing React errors).
+ *
+ * Design doc: 07-routing.md, 10-error-handling.md
+ */
+
+import { existsSync } from 'node:fs';
+import type { RouteTree, SegmentNode } from './types.js';
+import { swallow } from '../server/logger.js';
+import {
+  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 / 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);
+  }
+
+  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: Error Directive ─────────────────────────────────────────────────
+
+/**
+ * Warn when error.tsx or global-error.tsx is missing 'use client'.
+ *
+ * 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.
+ */
+function checkErrorDirectives(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.error && isScriptExtension(node.error.extension)) {
+    checkFileUseClientDirective(node.error.filePath, 'error', warnings);
+  }
+
+  for (const child of node.children) {
+    checkErrorDirectives(child, warnings);
+  }
+  for (const slot of Object.values(node.slots)) {
+    checkErrorDirectives(slot, warnings);
+  }
+}
+
+function checkFileUseClientDirective(
+  filePath: string,
+  fileType: string,
+  warnings: ConventionWarning[]
+): void {
+  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',
+      });
+    }
+  } catch (err) {
+    swallow(err, `convention-lint: unreadable ${fileType} file ${filePath}`);
+  }
+}
+
+// ─── 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;
+const style = (fmt: Format, text: string) => styleText(fmt, text, noValidate);
+
+/**
+ * Format warnings for terminal output.
+ *
+ * Groups by severity, uses colors, and includes fix suggestions.
+ */
+export function formatConventionWarnings(warnings: ConventionWarning[]): string {
+  if (warnings.length === 0) return '';
+
+  const errors = warnings.filter((w) => w.level === 'error');
+  const warns = warnings.filter((w) => w.level === 'warn');
+
+  const lines: string[] = [];
+
+  if (errors.length > 0) {
+    lines.push(
+      `${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');
+}

package/src/routing/export-detect.ts

@@ -0,0 +1,304 @@
+/**
+ * AST-based export detection for route files.
+ *
+ * Uses Vite's `parseAst` (backed by oxc) to precisely detect named and
+ * default exports, replacing the regex-based approach that was fragile
+ * with TypeScript syntax (type exports, `as` aliases, comments, etc.).
+ */
+
+import { existsSync } from 'node:fs';
+import { parseAst } from 'vite';
+import { readFileCached } from './file-cache.js';
+
+interface AstNode {
+  type: string;
+  exportKind?: string;
+  declaration?: AstNode;
+  specifiers?: Array<{
+    exported?: { name: string };
+    local?: { name: string };
+    exportKind?: string;
+  }>;
+  id?: { name: string };
+  declarations?: Array<{ id?: { name: string } }>;
+}
+
+interface ProgramNode {
+  body: AstNode[];
+}
+
+function tryParse(source: string): ProgramNode | null {
+  try {
+    return parseAst(source, { lang: 'tsx' }) as unknown as ProgramNode;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Collect all named export identifiers from a parsed program.
+ * Handles: `export function X`, `export const X`, `export { X }`,
+ * `export { X } from '...'`, `export { Y as X }`.
+ */
+function collectNamedExports(program: ProgramNode): Set<string> {
+  const names = new Set<string>();
+  for (const stmt of program.body) {
+    if (stmt.type !== 'ExportNamedDeclaration') continue;
+    // Skip `export type ...` declarations — they're erased at runtime
+    if (stmt.exportKind === 'type') continue;
+
+    if (stmt.declaration) {
+      if (stmt.declaration.id?.name) {
+        names.add(stmt.declaration.id.name);
+      }
+      if (stmt.declaration.declarations) {
+        for (const decl of stmt.declaration.declarations) {
+          if (decl.id?.name) names.add(decl.id.name);
+        }
+      }
+    }
+
+    if (stmt.specifiers) {
+      for (const spec of stmt.specifiers) {
+        // Skip `export { type X }` — per-specifier type exports
+        if (spec.exportKind === 'type') continue;
+        if (spec.exported?.name && spec.exported.name !== 'default') {
+          names.add(spec.exported.name);
+        }
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Check whether a program has a default export.
+ * Handles: `export default ...`, `export { X as default }`,
+ * `export { default } from '...'`.
+ */
+function hasDefaultExport(program: ProgramNode): boolean {
+  for (const stmt of program.body) {
+    if (stmt.type === 'ExportDefaultDeclaration') return true;
+    if (stmt.type === 'ExportNamedDeclaration' && stmt.specifiers) {
+      for (const spec of stmt.specifiers) {
+        if (spec.exported?.name === 'default') return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Check whether a program has any bare `export * from '...'` declarations.
+ * Excludes `export * as X from '...'` (namespace re-exports) since those
+ * create a namespace object, not individual top-level exports.
+ */
+function hasStarExport(program: ProgramNode): boolean {
+  return program.body.some(
+    (stmt) =>
+      stmt.type === 'ExportAllDeclaration' && !(stmt as any).exported && stmt.exportKind !== 'type'
+  );
+}
+
+/**
+ * Check if a file exports a specific named export.
+ * Returns false if the file doesn't exist or can't be parsed.
+ */
+export function fileHasExport(filePath: string, exportName: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return false;
+    return collectNamedExports(program).has(exportName);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a file has any of the given named exports.
+ * Returns the set of matching export names.
+ */
+export function fileHasAnyExport(filePath: string, exportNames: readonly string[]): Set<string> {
+  const matches = new Set<string>();
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return matches;
+    const exports = collectNamedExports(program);
+    for (const name of exportNames) {
+      if (exports.has(name)) matches.add(name);
+    }
+  } catch {
+    // Graceful fallback: return empty set
+  }
+  return matches;
+}
+
+/**
+ * Check if a file has a default export.
+ * Returns false if the file doesn't exist or can't be parsed.
+ */
+export function fileHasDefaultExport(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return false;
+    return hasDefaultExport(program);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a file has any `export * from '...'` declarations.
+ * Returns false if the file doesn't exist or can't be parsed.
+ */
+export function fileHasStarExport(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return false;
+    return hasStarExport(program);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parsed value of `export const prerender` from a route file.
+ *
+ * - `true` / `false` — literal boolean
+ * - `{ ttl?, tags? }` — ISR options object (prerender: true is implied)
+ * - `undefined` — no `export const prerender` found
+ *
+ * See design/45-cache-lifetimes.md §"Route-Level Static".
+ */
+export type PrerenderExportValue = boolean | { ttl?: number; tags?: string[] };
+
+function extractLiteralValue(node: AstNode): unknown {
+  if (!node) return undefined;
+  const n = node as any;
+  if (n.type === 'Literal') return n.value;
+  if (n.type === 'UnaryExpression' && n.operator === '-' && n.argument?.type === 'Literal') {
+    return -(n.argument.value as number);
+  }
+  if (n.type === 'ArrayExpression') {
+    const elements = n.elements as AstNode[] | undefined;
+    if (!elements) return undefined;
+    const result: unknown[] = [];
+    for (const el of elements) {
+      const v = extractLiteralValue(el);
+      if (v === undefined) return undefined;
+      result.push(v);
+    }
+    return result;
+  }
+  return undefined;
+}
+
+function extractObjectLiteral(node: AstNode): Record<string, unknown> | undefined {
+  if ((node as any).type !== 'ObjectExpression') return undefined;
+  const props = (node as any).properties as AstNode[] | undefined;
+  if (!props) return undefined;
+  const result: Record<string, unknown> = {};
+  for (const prop of props) {
+    const p = prop as any;
+    if (p.type === 'SpreadElement') return undefined;
+    if (p.type !== 'Property' || p.computed) return undefined;
+    const key =
+      p.key?.type === 'Identifier'
+        ? p.key.name
+        : p.key?.type === 'Literal'
+          ? String(p.key.value)
+          : undefined;
+    if (!key) return undefined;
+    const value = extractLiteralValue(p.value);
+    if (value === undefined) return undefined;
+    result[key] = value;
+  }
+  return result;
+}
+
+/**
+ * Extract the value of `export const prerender` from a file.
+ * Returns undefined if the file doesn't export `prerender` or can't be parsed.
+ *
+ * Supports:
+ *   export const prerender = true;
+ *   export const prerender = false;
+ *   export const prerender = { ttl: 3600, tags: ['docs'] };
+ */
+export function getPrerenderExport(filePath: string): PrerenderExportValue | undefined {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return undefined;
+
+    for (const stmt of program.body) {
+      if (stmt.type !== 'ExportNamedDeclaration') continue;
+      if (stmt.exportKind === 'type') continue;
+      if (!stmt.declaration) continue;
+      const decl = stmt.declaration;
+      if (decl.type !== 'VariableDeclaration') continue;
+      const declarations = decl.declarations as
+        | Array<{
+            id?: { name?: string };
+            init?: AstNode;
+          }>
+        | undefined;
+      if (!declarations) continue;
+      for (const d of declarations) {
+        if (d.id?.name !== 'prerender' || !d.init) continue;
+        const init = d.init as any;
+        if (init.type === 'Literal' && typeof init.value === 'boolean') {
+          return init.value;
+        }
+        if (init.type === 'ObjectExpression') {
+          const obj = extractObjectLiteral(init);
+          if (!obj) return undefined;
+          const result: { ttl?: number; tags?: string[] } = {};
+          if ('ttl' in obj && typeof obj.ttl === 'number') result.ttl = obj.ttl;
+          if (
+            'tags' in obj &&
+            Array.isArray(obj.tags) &&
+            obj.tags.every((t: unknown) => typeof t === 'string')
+          ) {
+            result.tags = obj.tags as string[];
+          }
+          return result;
+        }
+        return undefined;
+      }
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Check if a file starts with a specific directive (e.g. "use client").
+ * Directives are string literal expression statements at the top of the file.
+ */
+export function fileHasDirective(filePath: string, directive: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return false;
+    for (const stmt of program.body) {
+      if (stmt.type !== 'ExpressionStatement') break;
+      const expr = (stmt as any).expression;
+      if (expr?.type !== 'Literal' || typeof expr.value !== 'string') break;
+      if (expr.value === directive) return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}