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

package/src/config-validation.ts

@@ -0,0 +1,330 @@
+/**
+ * Config validation — validates timber.config.ts at startup.
+ *
+ * Runs in the plugin's configResolved hook (once, at startup/build).
+ * Each check produces a clear error message with the invalid value,
+ * what's expected, and how to fix it.
+ *
+ * Design doc: 18-build-system.md
+ */
+
+import { createRequire } from 'node:module';
+import type { TimberUserConfig } from './config-types.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ConfigError {
+  field: string;
+  message: string;
+  value?: unknown;
+  suggestion?: string;
+}
+
+// ─── Known config keys ──────────────────────────────────────────────────────
+
+// `satisfies Record<keyof TimberUserConfig, true>` makes this drift-proof:
+// adding a key to TimberUserConfig without listing it here is a compile
+// error, so validateConfig can never reject a documented option (TIM-1066).
+const KNOWN_CONFIG_KEYS = {
+  output: true,
+  debug: true,
+  clientJavascript: true,
+  adapter: true,
+  allowedOrigins: true,
+  csrf: true,
+  limits: true,
+  forms: true,
+  pageExtensions: true,
+  slowRequestMs: true,
+  renderTimeoutMs: true,
+  devBrowserLogs: true,
+  dev: true,
+  serverTiming: true,
+  appDir: true,
+  mdx: true,
+  actionEncryption: true,
+  reactCompiler: true,
+  sitemap: true,
+  buildDir: true,
+  clientSegmentCache: true,
+  topLoader: true,
+  budget: true,
+} satisfies Record<keyof TimberUserConfig, true>;
+
+const knownKeys = new Set<string>(Object.keys(KNOWN_CONFIG_KEYS));
+
+// ─── Validation ─────────────────────────────────────────────────────────────
+
+/**
+ * Validate a TimberUserConfig object.
+ *
+ * Returns an array of errors. Empty array means the config is valid.
+ * Does not throw — the caller decides how to surface errors.
+ */
+export function validateConfig(config: TimberUserConfig): ConfigError[] {
+  const errors: ConfigError[] = [];
+
+  // output
+  if (config.output !== undefined && config.output !== 'server' && config.output !== 'static') {
+    errors.push({
+      field: 'output',
+      message: `Invalid output mode: "${String(config.output)}". Must be "server" or "static".`,
+      value: config.output,
+      suggestion: 'Use output: "server" (default) or output: "static" for static site generation.',
+    });
+  }
+
+  // pageExtensions
+  if (config.pageExtensions !== undefined) {
+    if (!Array.isArray(config.pageExtensions)) {
+      errors.push({
+        field: 'pageExtensions',
+        message: 'pageExtensions must be an array of strings.',
+        value: config.pageExtensions,
+        suggestion: 'Example: pageExtensions: ["tsx", "ts", "jsx", "js", "mdx"]',
+      });
+    } else {
+      for (const ext of config.pageExtensions) {
+        if (typeof ext !== 'string') {
+          errors.push({
+            field: 'pageExtensions',
+            message: `pageExtensions contains a non-string value: ${JSON.stringify(ext)}`,
+            value: ext,
+          });
+          break;
+        }
+        if (ext.startsWith('.')) {
+          errors.push({
+            field: 'pageExtensions',
+            message: `pageExtensions should not include the leading dot: "${ext}"`,
+            value: ext,
+            suggestion: `Use "${ext.slice(1)}" instead of "${ext}".`,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  // slowRequestMs
+  if (config.slowRequestMs !== undefined) {
+    if (typeof config.slowRequestMs !== 'number' || config.slowRequestMs < 0) {
+      errors.push({
+        field: 'slowRequestMs',
+        message: `slowRequestMs must be a non-negative number (got ${JSON.stringify(config.slowRequestMs)}).`,
+        value: config.slowRequestMs,
+        suggestion: 'Use slowRequestMs: 3000 (default) or slowRequestMs: 0 to disable.',
+      });
+    }
+  }
+
+  // renderTimeoutMs
+  if (config.renderTimeoutMs !== undefined) {
+    if (typeof config.renderTimeoutMs !== 'number' || config.renderTimeoutMs < 0) {
+      errors.push({
+        field: 'renderTimeoutMs',
+        message: `renderTimeoutMs must be a non-negative number (got ${JSON.stringify(config.renderTimeoutMs)}).`,
+        value: config.renderTimeoutMs,
+        suggestion: 'Use renderTimeoutMs: 30000 (default). Setting 0 uses a 120s safety ceiling.',
+      });
+    }
+  }
+
+  // serverTiming
+  if (config.serverTiming !== undefined) {
+    if (
+      config.serverTiming !== 'detailed' &&
+      config.serverTiming !== 'total' &&
+      config.serverTiming !== false
+    ) {
+      errors.push({
+        field: 'serverTiming',
+        message: `Invalid serverTiming value: ${JSON.stringify(config.serverTiming)}.`,
+        value: config.serverTiming,
+        suggestion: 'Use "detailed", "total", or false.',
+      });
+    }
+  }
+
+  // devBrowserLogs
+  if (config.devBrowserLogs !== undefined) {
+    const valid = ['error', 'warn', 'info', 'none'];
+    if (!valid.includes(config.devBrowserLogs)) {
+      errors.push({
+        field: 'devBrowserLogs',
+        message: `Invalid devBrowserLogs value: ${JSON.stringify(config.devBrowserLogs)}.`,
+        value: config.devBrowserLogs,
+        suggestion: `Use one of: ${valid.map((v) => `"${v}"`).join(', ')}.`,
+      });
+    }
+  }
+
+  // sitemap
+  if (config.sitemap != null && typeof config.sitemap === 'object') {
+    if (config.sitemap.enabled && !config.sitemap.baseUrl) {
+      errors.push({
+        field: 'sitemap.baseUrl',
+        message: 'sitemap.baseUrl is required when sitemap is enabled.',
+        suggestion: 'Add sitemap: { enabled: true, baseUrl: "https://example.com" }.',
+      });
+    }
+    if (
+      config.sitemap.defaultPriority !== undefined &&
+      (config.sitemap.defaultPriority < 0 || config.sitemap.defaultPriority > 1)
+    ) {
+      errors.push({
+        field: 'sitemap.defaultPriority',
+        message: `sitemap.defaultPriority must be between 0.0 and 1.0 (got ${config.sitemap.defaultPriority}).`,
+        value: config.sitemap.defaultPriority,
+      });
+    }
+  }
+
+  // budget
+  if (config.budget != null && typeof config.budget === 'object') {
+    if (
+      config.budget.firstLoadJs !== undefined &&
+      (typeof config.budget.firstLoadJs !== 'number' || config.budget.firstLoadJs <= 0)
+    ) {
+      errors.push({
+        field: 'budget.firstLoadJs',
+        message: `budget.firstLoadJs must be a positive number in bytes (got ${JSON.stringify(config.budget.firstLoadJs)}).`,
+        value: config.budget.firstLoadJs,
+        suggestion: 'Example: budget: { firstLoadJs: 150_000 } for a ~150 kB limit.',
+      });
+    }
+  }
+
+  const MOVED_TO_CACHE_FILE = new Set(['cacheHandler', 'cdnPurge']);
+
+  for (const key of Object.keys(config)) {
+    if (!knownKeys.has(key)) {
+      errors.push({
+        field: key,
+        message: `Unknown config option: "${key}".`,
+        suggestion: MOVED_TO_CACHE_FILE.has(key)
+          ? `"${key}" has moved to timber.cache.ts. Export cacheHandler as default, cdnPurge as a named export.`
+          : `Check for typos. Known options: ${[...knownKeys].sort().join(', ')}.`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+// ─── Formatting ─────────────────────────────────────────────────────────────
+
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * Format config errors for terminal output.
+ */
+export function formatConfigErrors(errors: ConfigError[]): string {
+  if (errors.length === 0) return '';
+
+  const lines: string[] = [];
+  lines.push(
+    `${RED}${BOLD}[timber]${RESET} ${RED}${errors.length} config error${errors.length !== 1 ? 's' : ''} in timber.config.ts:${RESET}`
+  );
+
+  for (const err of errors) {
+    lines.push('');
+    lines.push(`  ${RED}✗${RESET} ${BOLD}${err.field}${RESET}: ${err.message}`);
+    if (err.suggestion) {
+      lines.push(`    ${DIM}${err.suggestion}${RESET}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Virtual Module Name Mapping ────────────────────────────────────────────
+
+const VIRTUAL_MODULE_NAMES: Record<string, string> = {
+  'virtual:timber-rsc-entry': 'RSC entry (server component handler)',
+  'virtual:timber-ssr-entry': 'SSR entry (HTML renderer)',
+  'virtual:timber-browser-entry': 'Browser entry (client hydration)',
+  'virtual:timber-config': 'Runtime config (timber.config.ts)',
+  'virtual:timber-route-manifest': 'Route manifest (app/ file tree)',
+  'virtual:timber-instrumentation': 'Instrumentation (instrumentation.ts)',
+  'virtual:timber-cache-handler': 'Cache handler (timber.cache.ts)',
+  'virtual:timber-build-manifest': 'Build manifest (asset mapping)',
+};
+
+/**
+ * Add timber-specific context to an error message that references virtual modules.
+ *
+ * If the error message contains a `virtual:timber-*` ID, appends a
+ * human-readable explanation. Does not replace the original message.
+ */
+export function addVirtualModuleContext(errorMessage: string): string {
+  for (const [id, name] of Object.entries(VIRTUAL_MODULE_NAMES)) {
+    if (errorMessage.includes(id)) {
+      return `${errorMessage}\n\n  [timber] This error references "${id}" — timber's ${name}.\n  This is an internal module. The issue is likely in your app code or timber configuration.`;
+    }
+  }
+  return errorMessage;
+}
+
+// ─── Peer Dependency Check ──────────────────────────────────────────────────
+
+interface PeerDepResult {
+  name: string;
+  status: 'ok' | 'missing';
+}
+
+/**
+ * Required (non-optional) peer dependencies that must be installed.
+ */
+const REQUIRED_PEERS = ['react', 'react-dom', '@vitejs/plugin-react', '@vitejs/plugin-rsc'];
+
+/**
+ * Check that required peer dependencies are installed.
+ *
+ * Uses require.resolve with a try/catch — no fs scanning.
+ * Returns only the missing packages.
+ */
+export function checkPeerDependencies(projectRoot: string): PeerDepResult[] {
+  const results: PeerDepResult[] = [];
+
+  // Use createRequire from the project root to resolve as the user would.
+  // `createRequire` MUST be a top-level ESM import — inline `require('node:module')`
+  // throws "Dynamic require not supported" in ESM and the catch below would
+  // mark every peer as missing. Same class of bug as TIM-796.
+  const userRequire = createRequire(`${projectRoot}/package.json`);
+
+  for (const name of REQUIRED_PEERS) {
+    try {
+      userRequire.resolve(name);
+      results.push({ name, status: 'ok' });
+    } catch {
+      results.push({ name, status: 'missing' });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Format missing peer dependencies as an actionable warning.
+ */
+export function formatMissingPeers(results: PeerDepResult[]): string {
+  const missing = results.filter((r) => r.status === 'missing');
+  if (missing.length === 0) return '';
+
+  const names = missing.map((r) => r.name);
+  const lines: string[] = [];
+  lines.push(`${RED}${BOLD}[timber]${RESET} ${RED}Missing required dependencies:${RESET}`);
+  lines.push('');
+  for (const name of names) {
+    lines.push(`  ${RED}✗${RESET} ${name}`);
+  }
+  lines.push('');
+  lines.push(`  ${DIM}Install with:${RESET}`);
+  lines.push(`  ${BOLD}pnpm add ${names.join(' ')}${RESET}`);
+
+  return lines.join('\n');
+}

package/src/content/index.ts

@@ -1,13 +1,5 @@
-/**
- * @timber-js/app/content — Public API for content collections.
- *
- * Re-exports from content-collections and provides timber-specific utilities.
- * Users can import directly from 'content-collections' for generated types,
- * or use this module for the re-exports.
- *
- * Design doc: 20-content-collections.md §"Querying Collections"
- */
-
-// Re-export defineCollection and defineConfig for convenience.
-// Users can also import these directly from @content-collections/core.
-export { defineCollection, defineConfig } from '@content-collections/core';
+// @timber-js/app/content entry point removed per TIM-722.
+//
+// Import defineCollection and defineConfig directly from @content-collections/core.
+// This file is kept for the content plugin which uses other files in this directory.
+export {};