@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.91

package/src/plugins/dev-error-overlay.ts

@@ -1,13 +1,53 @@
 /**
  * Dev error overlay — formats and sends errors to Vite's browser overlay and stderr.
  *
- * Integrates with Vite's built-in error overlay (`server.ssrFixStacktrace` +
- * `server.hot.send`) rather than implementing a custom overlay.
+ * 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 } from 'vite';
+import type { ViteDevServer, DevEnvironment } from 'vite';
+import { createRequire } from 'node:module';
+import { resolve, dirname } from 'node:path';
+
+// ─── 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 ──────────────────────────────────────────────────────────────────
 
@@ -21,7 +61,7 @@ export type ErrorPhase =
   | 'handler';
 
 /** Labels for terminal output. */
-const PHASE_LABELS: Record<ErrorPhase, string> = {
+export const PHASE_LABELS: Record<ErrorPhase, string> = {
   'module-transform': 'Module Transform',
   'proxy': 'Proxy',
   'middleware': 'Middleware',
@@ -131,55 +171,243 @@ export function classifyErrorPhase(error: Error, projectRoot: string): ErrorPhas
 
 // ─── Terminal Formatting ────────────────────────────────────────────────────
 
-// ANSI codes
-const RED = '\x1b[31m';
-const DIM = '\x1b[2m';
-const RESET = '\x1b[0m';
-const BOLD = '\x1b[1m';
+// formatTerminalError is implemented in the dedicated terminal formatter module
+// (dev-terminal-error.ts) to keep this file under 500 lines.
+// Import for use in sendErrorToOverlay, and re-export for external consumers.
+import { formatTerminalError as _formatTerminalError } from './dev-terminal-error.js';
+export const formatTerminalError = _formatTerminalError;
+
+// ─── RSC Debug Context ──────────────────────────────────────────────────────
 
 /**
- * Format an error for terminal output.
- *
- * - Red for the error message and phase label
- * - Dim for framework-internal frames
- * - Normal for application frames
- * - Separate section for component stack (if present)
+ * Component info extracted from the RSC debug channel.
+ * Contains only names, environments, and stack frames — never source code.
  */
-export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot: string): string {
-  const lines: string[] = [];
-
-  // Phase header + error message
-  lines.push(`${RED}${BOLD}[timber] ${PHASE_LABELS[phase]} Error${RESET}`);
-  lines.push(`${RED}${error.message}${RESET}`);
-  lines.push('');
+export interface RscDebugComponentInfo {
+  name: string;
+  env: string | null;
+  stack: unknown[] | null;
+}
 
-  // Component stack (if present)
-  const componentStack = extractComponentStack(error);
-  if (componentStack) {
-    lines.push(`${BOLD}Component Stack:${RESET}`);
-    for (const csLine of componentStack.trim().split('\n')) {
-      lines.push(`  ${csLine.trim()}`);
+/**
+ * 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);
     }
-    lines.push('');
   }
 
-  // Stack trace with frame dimming
-  if (error.stack) {
-    lines.push(`${BOLD}Stack Trace:${RESET}`);
-    const stackLines = error.stack.split('\n').slice(1); // Skip the first line (message)
-    for (const stackLine of stackLines) {
-      const frameType = classifyFrame(stackLine, projectRoot);
-      if (frameType === 'app') {
-        lines.push(stackLine);
-      } else {
-        lines.push(`${DIM}${stackLine}${RESET}`);
+  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 {
+    _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 {
+            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 ────────────────────────────────────────────────────
 
 /**
@@ -188,16 +416,26 @@ export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot
  * 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
+  projectRoot: string,
+  rscDebugComponents?: RscDebugComponentInfo[]
 ): void {
-  // Fix stack trace to use source-mapped positions
-  server.ssrFixStacktrace(error);
+  // 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);
@@ -212,6 +450,12 @@ export function sendErrorToOverlay(
     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({