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

package/src/config-validation.ts

@@ -0,0 +1,464 @@
+/**
+ * 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.ts';
+import { DEFAULT_RENDER_TIMEOUT_MS, RENDER_TIMEOUT_CEILING_MS } from './server/render-timeout.ts';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ConfigError {
+  field: string;
+  message: string;
+  value?: unknown;
+  suggestion?: string;
+  /**
+   * Refuse to start rather than log. Most config errors only warn — Vite may
+   * still work partially — but a fatal one would leave a security check
+   * running on a value the developer did not mean (`allowedOrigins`).
+   */
+  fatal?: true;
+}
+
+// ─── 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,
+  cache: 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;
+        }
+      }
+    }
+  }
+
+  // allowedOrigins
+  if (config.allowedOrigins !== undefined) {
+    if (!Array.isArray(config.allowedOrigins)) {
+      errors.push({
+        field: 'allowedOrigins',
+        message: 'allowedOrigins must be an array of origin strings.',
+        value: config.allowedOrigins,
+        fatal: true,
+        suggestion: 'Example: allowedOrigins: ["https://app.example.com"]',
+      });
+    } else {
+      for (const entry of config.allowedOrigins) {
+        const error = allowedOriginError(entry);
+        if (error) errors.push(error);
+      }
+    }
+  }
+
+  // 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: ${DEFAULT_RENDER_TIMEOUT_MS} (default). Setting 0 uses a ${RENDER_TIMEOUT_CEILING_MS / 1000}s 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.',
+      });
+    }
+  }
+
+  // cache
+  if (config.cache != null && typeof config.cache === 'object') {
+    if (
+      config.cache.strictKeyDiscipline !== undefined &&
+      typeof config.cache.strictKeyDiscipline !== 'boolean'
+    ) {
+      errors.push({
+        field: 'cache.strictKeyDiscipline',
+        message: `cache.strictKeyDiscipline must be a boolean (got ${JSON.stringify(config.cache.strictKeyDiscipline)}).`,
+        value: config.cache.strictKeyDiscipline,
+        suggestion:
+          'Use cache: { strictKeyDiscipline: true } to promote key-discipline warnings to errors.',
+      });
+    }
+  }
+
+  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;
+}
+
+/**
+ * Why one `allowedOrigins` entry can never match, or null when it can.
+ *
+ * The CSRF check compares entries to the request's `Origin` header by
+ * exact string, and browsers send only the canonical form — scheme, host,
+ * and non-default port, lowercased, no path. So an entry that is not its
+ * own `new URL(x).origin` (`https://example.com/`, `https://Example.com`,
+ * `example.com`) silently matches nothing. `"null"` is refused outright:
+ * it is the `Origin` of every opaque context at once.
+ */
+function allowedOriginError(entry: unknown): ConfigError | null {
+  const field = 'allowedOrigins';
+  const fatal = true;
+  if (typeof entry !== 'string') {
+    return {
+      field,
+      message: `allowedOrigins contains a non-string value: ${JSON.stringify(entry)}.`,
+      value: entry,
+      fatal,
+    };
+  }
+  if (entry === 'null') {
+    return {
+      field,
+      message:
+        'allowedOrigins cannot contain "null". Browsers send Origin: null from every opaque ' +
+        "context — sandboxed iframes (an attacker's <iframe sandbox> included), POSTs " +
+        'redirected across origins, and file: pages — so allowing it allows all of them.',
+      value: entry,
+      suggestion:
+        'To accept a cross-site POST on one endpoint, handle it in a route.ts that exports ' +
+        '`const csrf = false` instead.',
+      fatal,
+    };
+  }
+  // `new URL('https://*.example.com').origin` round-trips, so the canonical
+  // check alone would accept a wildcard that matches no real Origin.
+  if (entry.includes('*')) {
+    return {
+      field,
+      message: `allowedOrigins entry ${JSON.stringify(entry)} uses a wildcard. Matching is exact; wildcards are not supported.`,
+      value: entry,
+      suggestion:
+        'List each origin, e.g. ["https://app.example.com", "https://admin.example.com"].',
+      fatal,
+    };
+  }
+  const canonical = canonicalOrigin(entry) ?? canonicalOrigin(`https://${entry}`);
+  if (canonical === entry) return null;
+  return {
+    field,
+    message: `allowedOrigins entry ${JSON.stringify(entry)} is not a canonical origin, so it can never match a request's Origin header.`,
+    value: entry,
+    suggestion: canonical
+      ? `Did you mean "${canonical}"? An origin is scheme://host[:port] — lowercase, no path or trailing slash.`
+      : 'An origin is scheme://host[:port], e.g. "https://app.example.com".',
+    fatal,
+  };
+}
+
+/** `new URL(x).origin` for an http(s) URL, or null. Opaque origins are not origins here. */
+function canonicalOrigin(value: string): string | null {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:' ? url.origin : null;
+  } catch {
+    return null;
+  }
+}
+
+// ─── Formatting ─────────────────────────────────────────────────────────────
+
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * Format config errors for terminal output. Pass `color: false` for text
+ * that goes into a thrown `Error` — escapes there reach CI logs and the
+ * Vite overlay as raw bytes.
+ */
+export function formatConfigErrors(
+  errors: ConfigError[],
+  { color = true }: { color?: boolean } = {}
+): string {
+  if (errors.length === 0) return '';
+  const [red, bold, dim, reset] = color ? [RED, BOLD, DIM, RESET] : ['', '', '', ''];
+
+  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');
+}
+
+/**
+ * Surface config errors at startup: non-fatal ones are written to stderr
+ * (Vite may still work partially, and the message guides the fix); fatal
+ * ones then stop startup with a thrown error. Non-fatal errors are written
+ * first so a fatal one does not hide them.
+ */
+export function reportConfigErrors(
+  errors: ConfigError[],
+  write: (text: string) => void = (text) => process.stderr.write(text)
+): void {
+  const warnings = errors.filter((e) => !e.fatal);
+  if (warnings.length > 0) write(`${formatConfigErrors(warnings)}\n\n`);
+  const fatal = errors.filter((e) => e.fatal);
+  if (fatal.length > 0) throw new Error(formatConfigErrors(fatal, { color: false }));
+}
+
+// ─── 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');
+}