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

package/src/dev-tools/overlay.ts

@@ -0,0 +1,469 @@
+/**
+ * Dev error overlay — formats and sends errors to Vite's browser overlay and stderr.
+ *
+ * Integrates with Vite's built-in error overlay (`server.hot.send`) rather
+ * than implementing a custom overlay.
+ *
+ * Stack trace source-mapping uses the correct Vite environment module graph:
+ * RSC errors use `server.environments.rsc.moduleGraph`, SSR/other errors use
+ * `server.environments.ssr.moduleGraph`. `server.ssrFixStacktrace()` is NOT
+ * used because it hardcodes the SSR module graph, which doesn't contain
+ * source maps for RSC modules (separate Vite environment with its own
+ * module graph). This caused RSC errors to show transpiled line numbers
+ * instead of original source positions.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+
+import type { ViteDevServer, DevEnvironment } from 'vite';
+import { createRequire } from 'node:module';
+import { resolve, dirname } from 'node:path';
+import { classifyFrame, type FrameType } from './stack-classifier.js';
+
+// ─── Trace Mapping (lazy-loaded) ─────────────────────────────────────────────
+
+interface TraceMappingModule {
+  TraceMap: new (map: unknown) => unknown;
+  originalPositionFor: (
+    map: unknown,
+    needle: { line: number; column: number }
+  ) => { source: string | null; line: number | null; column: number | null };
+}
+
+let _traceMapping: TraceMappingModule | null = null;
+
+/**
+ * Lazy-load @jridgewell/trace-mapping from Vite's dependency tree.
+ * Vite bundles it internally; we resolve from Vite's package to avoid
+ * adding a direct dependency.
+ */
+function getTraceMapping(): TraceMappingModule {
+  if (_traceMapping) return _traceMapping;
+  // Resolve from Vite's package location so we pick up its transitive
+  // @jridgewell/trace-mapping without declaring it as a direct dependency.
+  // createRequire(import.meta.url) gives us ESM-compatible require (TIM-796),
+  // then we hop to Vite's path to reach its dependency tree (TIM-804).
+  const esmRequire = createRequire(import.meta.url);
+  const vitePath = esmRequire.resolve('vite');
+  const viteRequire = createRequire(vitePath);
+  _traceMapping = viteRequire('@jridgewell/trace-mapping') as TraceMappingModule;
+  return _traceMapping;
+}
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+/** The phase of the pipeline where the error occurred. */
+export type ErrorPhase =
+  | 'module-transform'
+  | 'proxy'
+  | 'middleware'
+  | 'access'
+  | 'render'
+  | 'handler';
+
+/** Labels for terminal output. */
+export const PHASE_LABELS: Record<ErrorPhase, string> = {
+  'module-transform': 'Module Transform',
+  'proxy': 'Proxy',
+  'middleware': 'Middleware',
+  'access': 'Access Check',
+  'render': 'RSC Render',
+  'handler': 'Route Handler',
+};
+
+// ─── Frame Classification (re-exported from stack-classifier) ───────────────
+
+export {
+  classifyFrame,
+  classifyStack,
+  type FrameType,
+  type ClassifiedFrame,
+} from './stack-classifier.js';
+
+// ─── Component Stack Extraction ─────────────────────────────────────────────
+
+/**
+ * Extract the React component stack from an error, if present.
+ * React attaches this as `componentStack` during renderToReadableStream errors.
+ */
+export function extractComponentStack(error: unknown): string | null {
+  if (
+    error &&
+    typeof error === 'object' &&
+    'componentStack' in error &&
+    typeof (error as Record<string, unknown>).componentStack === 'string'
+  ) {
+    return (error as Record<string, unknown>).componentStack as string;
+  }
+  return null;
+}
+
+// ─── First App Frame Parsing ────────────────────────────────────────────────
+
+interface SourceLocation {
+  file: string;
+  line: number;
+  column: number;
+}
+
+/**
+ * Parse the first application frame from a stack trace.
+ * Returns file/line/column for the overlay's `loc` field.
+ */
+export function parseFirstAppFrame(stack: string, projectRoot: string): SourceLocation | null {
+  const lines = stack.split('\n');
+  // Match patterns like:
+  //   at functionName (/absolute/path:line:column)
+  //   at /absolute/path:line:column
+  const parenRegex = /\(([^)]+):(\d+):(\d+)\)/;
+  const bareRegex = /at (\/[^:]+):(\d+):(\d+)/;
+
+  for (const line of lines) {
+    if (classifyFrame(line, projectRoot) !== 'app') continue;
+
+    const match = parenRegex.exec(line) ?? bareRegex.exec(line);
+    if (!match) continue;
+
+    const [, file, lineNum, col] = match;
+    if (file && lineNum && col) {
+      return { file, line: parseInt(lineNum, 10), column: parseInt(col, 10) };
+    }
+  }
+
+  return null;
+}
+
+// ─── Error Phase Classification ─────────────────────────────────────────────
+
+/**
+ * Classify the error phase by inspecting the error's stack trace.
+ * Falls back to 'render' if no specific phase can be determined.
+ */
+export function classifyErrorPhase(error: Error, projectRoot: string): ErrorPhase {
+  const stack = error.stack ?? '';
+
+  // Check for React component stack (render error)
+  if (extractComponentStack(error)) return 'render';
+
+  // Check for specific file patterns in app frames
+  const appRoot = projectRoot.replace(/\/$/, '');
+  if (stack.includes(`${appRoot}/app/`) || stack.includes('/app/')) {
+    if (stack.includes('/middleware.ts') || stack.includes('/middleware.js')) return 'middleware';
+    if (stack.includes('/access.ts') || stack.includes('/access.js')) return 'access';
+    if (stack.includes('/route.ts') || stack.includes('/route.js')) return 'handler';
+  }
+
+  return 'render';
+}
+
+// ─── Terminal Formatting ────────────────────────────────────────────────────
+
+// formatTerminalError is implemented in the dedicated terminal formatter module
+// (terminal.ts) to keep this file under 500 lines.
+// Import for use in sendErrorToOverlay, and re-export for external consumers.
+import { formatTerminalError as _formatTerminalError } from './terminal.js';
+export const formatTerminalError = _formatTerminalError;
+
+// ─── RSC Debug Context ──────────────────────────────────────────────────────
+
+/**
+ * Component info extracted from the RSC debug channel.
+ * Contains only names, environments, and stack frames — never source code.
+ */
+export interface RscDebugComponentInfo {
+  name: string;
+  env: string | null;
+  stack: unknown[] | null;
+}
+
+/**
+ * Format RSC debug component info into a readable string for the overlay.
+ *
+ * Renders the server component tree that was active when an error occurred,
+ * including component names and source locations from stack frames. This
+ * gives developers visibility into which server components were rendering
+ * without exposing source code.
+ *
+ * Returns an empty string if no components are provided.
+ */
+export function formatRscDebugContext(components: RscDebugComponentInfo[]): string {
+  if (!components || components.length === 0) return '';
+
+  // Deduplicate by name — the debug channel may emit the same component
+  // multiple times (e.g., when re-rendered or when multiple instances exist).
+  const seen = new Set<string>();
+  const unique: RscDebugComponentInfo[] = [];
+  for (const c of components) {
+    if (!seen.has(c.name)) {
+      seen.add(c.name);
+      unique.push(c);
+    }
+  }
+
+  const lines: string[] = ['Server Component Tree:'];
+  for (let i = 0; i < unique.length; i++) {
+    const c = unique[i]!;
+    const indent = '  '.repeat(i + 1);
+    const envLabel = c.env ? ` [${c.env}]` : '';
+
+    // Extract file location from stack frames if available
+    let locStr = '';
+    if (c.stack && c.stack.length > 0) {
+      const frame = c.stack[0] as [string, string, number, number] | undefined;
+      if (Array.isArray(frame) && frame.length >= 3) {
+        locStr = ` (${frame[1]}:${frame[2]})`;
+      }
+    }
+
+    lines.push(`${indent}${c.name}${envLabel}${locStr}`);
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Module Runner Offset ───────────────────────────────────────────────────
+
+/**
+ * Dynamically compute the line offset that Vite's module runner adds
+ * when wrapping modules in an async function.
+ *
+ * Vite's `calculateOffsetOnce()` uses the same technique: create a new
+ * AsyncFunction, throw from line 1, and check where the engine reports
+ * the error. The difference between the reported line and 1 is the offset.
+ *
+ * This is engine-dependent (currently 2 on Node 18-22) and could change
+ * in future Node.js or V8 versions. Computing it at runtime ensures we
+ * always match the actual behavior.
+ */
+let _cachedOffset: number | null = null;
+
+export function calculateModuleRunnerOffset(): number {
+  if (_cachedOffset !== null) return _cachedOffset;
+
+  try {
+    // Parse the AsyncFunction source to count wrapper lines before the body.
+    // AsyncFunction.toString() returns something like:
+    //   "async function anonymous(\n) {\nBODY\n}"
+    // The number of newlines before BODY is the offset Vite's module runner adds.
+    // eslint-disable-next-line no-new-func -- intentional: mirrors Vite's technique
+    const AsyncFunction = async function () {}.constructor as typeof Function;
+    const wrapper = new AsyncFunction('BODY');
+    const src = wrapper.toString();
+    const bodyIndex = src.indexOf('BODY');
+    if (bodyIndex === -1) {
+      _cachedOffset = 2; // fallback
+      return _cachedOffset;
+    }
+    const beforeBody = src.slice(0, bodyIndex);
+    const newlineCount = (beforeBody.match(/\n/g) || []).length;
+    _cachedOffset = newlineCount;
+  } catch (e) {
+    console.debug(
+      '[timber] overlay offset calculation failed:',
+      e instanceof Error ? e.message : e
+    );
+    _cachedOffset = 2; // fallback to known-good value
+  }
+
+  return _cachedOffset;
+}
+
+// ─── Stack Trace Source-Mapping ──────────────────────────────────────────────
+
+/**
+ * Phases where the error originated in the RSC environment.
+ * These use `server.environments.rsc.moduleGraph` for source-mapping.
+ */
+const RSC_PHASES: ReadonlySet<ErrorPhase> = new Set(['render', 'access', 'middleware', 'handler']);
+
+/**
+ * Rewrite an error's stack trace using the correct Vite environment module graph.
+ *
+ * `server.ssrFixStacktrace()` hardcodes `server.environments.ssr.moduleGraph`,
+ * but RSC errors have stack frames pointing to modules loaded in the RSC
+ * environment — a separate Vite module graph with separate transform results
+ * and source maps. Using the SSR module graph silently fails to find the
+ * modules, leaving transpiled/bundled line numbers in the stack trace.
+ *
+ * This function picks the RSC module graph for render-phase errors and falls
+ * back to SSR for module-transform/proxy errors. If the first pass doesn't
+ * rewrite any frames (e.g., mixed RSC+SSR stack), it tries the other graph.
+ */
+function fixStacktraceForEnvironment(server: ViteDevServer, error: Error, phase: ErrorPhase): void {
+  if (!error.stack) return;
+
+  // Pick the primary environment based on error phase
+  const primaryEnvName = RSC_PHASES.has(phase) ? 'rsc' : 'ssr';
+  const fallbackEnvName = primaryEnvName === 'rsc' ? 'ssr' : 'rsc';
+
+  const primaryEnv = server.environments[primaryEnvName] as DevEnvironment | undefined;
+  const fallbackEnv = server.environments[fallbackEnvName] as DevEnvironment | undefined;
+
+  // Try primary environment first
+  if (primaryEnv?.moduleGraph) {
+    const rewritten = rewriteStacktrace(error.stack, primaryEnv.moduleGraph);
+    if (rewritten.changed) {
+      error.stack = rewritten.stack;
+      return;
+    }
+  }
+
+  // Fall back to the other environment if primary didn't rewrite anything
+  if (fallbackEnv?.moduleGraph) {
+    const rewritten = rewriteStacktrace(error.stack, fallbackEnv.moduleGraph);
+    if (rewritten.changed) {
+      error.stack = rewritten.stack;
+      return;
+    }
+  }
+}
+
+/**
+ * Rewrite stack trace frames using source maps from an environment's module graph.
+ *
+ * Mirrors Vite's internal `ssrRewriteStacktrace` logic but works with any
+ * `EnvironmentModuleGraph`, not just the SSR one.
+ *
+ * Returns the rewritten stack and whether any frames were actually changed.
+ */
+function rewriteStacktrace(
+  stack: string,
+  moduleGraph: DevEnvironment['moduleGraph']
+): { stack: string; changed: boolean } {
+  let changed = false;
+
+  const result = stack
+    .split('\n')
+    .map((line) => {
+      return line.replace(
+        /^ {4}at (?:(\S.*?)\s\()?(.+?):(\d+)(?::(\d+))?\)?/,
+        (input, varName, id, lineStr, colStr) => {
+          if (!id) return input;
+
+          const mod = moduleGraph.getModuleById(id);
+          const rawSourceMap = mod?.transformResult?.map;
+          if (!rawSourceMap) return input;
+
+          // Vite's module runner wraps each module in an async function,
+          // adding N lines before the module body. The offset is computed
+          // dynamically to match the actual engine behavior (see TIM-783).
+          const OFFSET = calculateModuleRunnerOffset();
+          const origLine = Number(lineStr) - OFFSET;
+          const origCol = Number(colStr) - 1;
+          if (origLine <= 0 || origCol < 0) return input;
+
+          // Use @jridgewell/trace-mapping resolved from Vite's dependency tree.
+          // Vite bundles it internally; we resolve from Vite's package location
+          // to avoid adding a direct dependency.
+          let pos: { source: string | null; line: number | null; column: number | null };
+          try {
+            const { TraceMap: TM, originalPositionFor: opf } = getTraceMapping();
+            const traced = new TM(rawSourceMap);
+            pos = opf(traced, { line: origLine, column: origCol });
+          } catch (e) {
+            console.debug(
+              '[timber] source map tracing failed:',
+              e instanceof Error ? e.message : e
+            );
+            return input;
+          }
+
+          if (!pos.source || pos.line == null) return input;
+
+          changed = true;
+          const source = `${resolve(dirname(id), pos.source)}:${pos.line}:${(pos.column ?? 0) + 1}`;
+          const trimmedVarName = varName?.trim();
+          if (!trimmedVarName || trimmedVarName === 'eval') return `    at ${source}`;
+          return `    at ${trimmedVarName} (${source})`;
+        }
+      );
+    })
+    .join('\n');
+
+  return { stack: result, changed };
+}
+
+// ─── Error Source-Mapping (exported for use by fallback-error.ts) ────────────
+
+/**
+ * Source-map an error's stack trace using the Vite dev server's module graph.
+ *
+ * Exported so that the fallback error renderer (fallback-error.ts) can
+ * source-map errors before rendering the dev error page. Without this,
+ * the dev error page shows transpiled positions (e.g. page.tsx:1:1 instead
+ * of page.tsx:4:9).
+ *
+ * See TIM-811.
+ */
+export function fixErrorStacktrace(server: ViteDevServer, error: Error, phase?: ErrorPhase): void {
+  fixStacktraceForEnvironment(
+    server,
+    error,
+    phase ?? classifyErrorPhase(error, server.config.root)
+  );
+}
+
+// ─── Overlay Integration ────────────────────────────────────────────────────
+
+/**
+ * Send an error to Vite's browser overlay and log it to stderr.
+ *
+ * Uses `server.ssrFixStacktrace()` to map stack traces back to source,
+ * then sends the error via `server.hot.send()` for the browser overlay.
+ *
+ * When `rscDebugComponents` is provided (dev mode only), the server
+ * component tree context is appended to the error message. This helps
+ * developers identify which server component caused the error without
+ * exposing source code.
+ *
+ * The dev server remains running — errors are handled, not fatal.
+ */
+export function sendErrorToOverlay(
+  server: ViteDevServer,
+  error: Error,
+  phase: ErrorPhase,
+  projectRoot: string,
+  rscDebugComponents?: RscDebugComponentInfo[]
+): void {
+  // Fix stack trace to use source-mapped positions.
+  // Use the RSC environment's module graph for render/access/middleware errors
+  // (which originate in the RSC environment), and fall back to SSR for others.
+  // server.ssrFixStacktrace() is NOT used — it hardcodes the SSR module graph
+  // which doesn't contain source maps for RSC-loaded modules.
+  fixStacktraceForEnvironment(server, error, phase);
+
+  // Log to stderr with frame dimming
+  const formatted = formatTerminalError(error, phase, projectRoot);
+  process.stderr.write(`${formatted}\n`);
+
+  // Build overlay payload
+  const loc = parseFirstAppFrame(error.stack ?? '', projectRoot);
+  const componentStack = extractComponentStack(error);
+
+  let message = error.message;
+  if (componentStack) {
+    message = `${error.message}\n\nComponent Stack:\n${componentStack.trim()}`;
+  }
+
+  // Append RSC debug context if available (dev mode only)
+  const debugContext = formatRscDebugContext(rscDebugComponents ?? []);
+  if (debugContext) {
+    message = `${message}\n\n${debugContext}`;
+  }
+
+  // Send to browser via Vite's error overlay protocol
+  try {
+    server.hot.send({
+      type: 'error',
+      err: {
+        message,
+        stack: error.stack ?? '',
+        id: loc?.file,
+        plugin: `timber (${PHASE_LABELS[phase]})`,
+        loc: loc ? { file: loc.file, line: loc.line, column: loc.column } : undefined,
+      },
+    });
+  } catch (e) {
+    console.debug('[timber] overlay error send failed:', e instanceof Error ? e.message : e);
+  }
+}

package/src/dev-tools/stack-classifier.ts

@@ -0,0 +1,75 @@
+/**
+ * Stack trace frame classifier — categorizes stack frames by origin.
+ *
+ * Provides `classifyFrame` (single frame) and `classifyStack` (full stack
+ * string) as the shared primitives used by the error page, terminal
+ * formatter, and overlay.
+ *
+ * Dev-only: this module is only imported by other dev-tools modules.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type FrameType = 'app' | 'framework' | 'internal';
+
+export interface ClassifiedFrame {
+  raw: string;
+  type: FrameType;
+  file?: string;
+  line?: number;
+  col?: number;
+}
+
+// ─── Frame Parsing ──────────────────────────────────────────────────────────
+
+/** Parse file/line/col from a stack frame line. */
+function parseFrame(frameLine: string): { file?: string; line?: number; col?: number } {
+  const parenMatch = /\(([^)]+):(\d+):(\d+)\)/.exec(frameLine);
+  if (parenMatch) {
+    return { file: parenMatch[1], line: Number(parenMatch[2]), col: Number(parenMatch[3]) };
+  }
+  const bareMatch = /at (\/[^:]+):(\d+):(\d+)/.exec(frameLine);
+  if (bareMatch) {
+    return { file: bareMatch[1], line: Number(bareMatch[2]), col: Number(bareMatch[3]) };
+  }
+  return {};
+}
+
+// ─── Classification ─────────────────────────────────────────────────────────
+
+/**
+ * Classify a single stack frame line by origin.
+ *
+ * - 'app': user application code (in project root, not node_modules)
+ * - 'framework': timber-app internal code
+ * - 'internal': node_modules, Node.js internals
+ */
+export function classifyFrame(frameLine: string, projectRoot: string): FrameType {
+  const trimmed = frameLine.trim();
+
+  if (trimmed.includes('packages/timber-app/')) return 'framework';
+  if (trimmed.includes('node_modules/')) return 'internal';
+  if (trimmed.startsWith('at node:') || trimmed.includes('(node:')) return 'internal';
+  if (trimmed.includes(projectRoot)) return 'app';
+
+  return 'internal';
+}
+
+/**
+ * Classify all frames in a full stack trace string.
+ *
+ * Parses the stack, skips the first line (error message), filters to
+ * lines starting with "at ", and returns classified frames with optional
+ * file/line/col metadata.
+ */
+export function classifyStack(stack: string, projectRoot: string): ClassifiedFrame[] {
+  return stack
+    .split('\n')
+    .slice(1) // skip first line (error message)
+    .filter((line) => line.trim().startsWith('at '))
+    .map((raw) => {
+      const type = classifyFrame(raw, projectRoot);
+      const { file, line, col } = parseFrame(raw);
+      return { raw, type, file, line, col };
+    });
+}