@backtrack-js/browser 0.4.2 → 0.5.0

package/README.md

@@ -89,6 +89,7 @@ npx backtrack symbolize <incident> --sourcemaps <directory> [options]
 | `<incident>` | Path to an exported incident: `.json`, `.ffr.json`, `.gz` or `.ffr.json.gz`. Gzip is detected automatically. |
 | `--sourcemaps <directory>` | Directory containing your `.js.map`, `.mjs.map` and `.cjs.map` files. Searched recursively (e.g. `./dist`, `./build`). |
 | `--output <file>` | Custom output path. Defaults to `<name>.symbolicated.ffr.json` next to the original. The output can never overwrite the input file. |
+| `--release <id>` | Build or release identifier. Validates against the incident's recorded release (if present), warning on mismatch. |
 | `--context-lines <number>` | Lines of original source shown before and after the failing line. Range 0–10, default 3. |
 | `-h, --help` | Show help. |
 
@@ -103,8 +104,10 @@ npx backtrack symbolize ./incidents/checkout-bug.ffr.json --sourcemaps ./dist --
 
 Incidente: inc_1727500000_3f2a
 Erros encontrados: 1
-Frames resolvidos: 4
-Frames não resolvidos: 0
+Frames da exceção resolvidos: 4
+Frames da exceção não resolvidos: 0
+Frames React resolvidos: 2
+Frames React não resolvidos: 0
 Saída: /projects/app/incidents/checkout-bug.symbolicated.ffr.json
 ```
 
@@ -125,10 +128,18 @@ applyCoupon  src/cart/coupon.ts:42:18
 ### What it does (and doesn't do)
 
 - **Validates safely:** Reads the incident (up to 50 MB, gzip supported) and validates its schema with a strict validator. The original file is never modified.
-- **Maps V8 frames:** Finds error events that carry a stack and maps each minified frame with [@jridgewell/trace-mapping](https://github.com/jridgewell/trace-mapping).
+- **Multi-browser stack parsing:** Supports V8 (Chrome/Edge), Firefox, and Safari stack formats, stripping URL hashes/query strings and skipping native frames (`[native code]`).
+- **Resolves both exception location and React tree:** Simboliza tanto o ponto onde a exceção foi lançada (`resolvedStack`) quanto a árvore de componentes React (`resolvedComponentStack`), mantendo-os estritamente separados.
+- **Sourcemap validation:** Checks the sourcemap `file` attribute against the minified bundle to prevent cross-bundle misattribution.
 - **Extracts source context:** Extracts the original code from `sourcesContent`, so your source maps must include it.
 - **Doesn't leak local paths:** File paths are normalized (e.g. `C:\Users\alice\...` or `/home/bob/...` become paths starting at `src/`).
-- **Atomic write:** Writes the result atomically (to a `.tmp` file, then renames) and stores it in a new `resolvedStack` field.
+- **Atomic write:** Writes the result atomically (to a `.tmp` file, then renames) and stores it in `resolvedStack` and `resolvedComponentStack`.
+
+### Limitations & Caveats
+
+- **Frames without line/column:** Stack frames missing line or column numbers cannot be mapped to source locations.
+- **Matching sourcemap release:** Source maps must correspond to the exact production build that generated the incident. Use `--release <id>` to ensure compatibility.
+- **Privacy notice:** O artefato poderá incluir replay visual, URLs, logs, respostas de rede, anotações e trechos do código-fonte incorporados durante a symbolication.
 
 ---
 
@@ -201,15 +212,36 @@ const jsonBlob = new Blob([JSON.stringify(artifact, null, 2)], { type: 'applicat
 ```
 
 ### Exception Capture
-In React Error Boundaries or try/catch blocks:
+
+#### React Error Boundary
+Em Error Boundaries (ex: `componentDidCatch` ou `react-error-boundary`), forneça `source: 'react'` e a árvore de componentes `componentStack`:
 
 ```typescript
-recorder.captureException(error, {
-  source: 'react',
-  componentStack: errorInfo.componentStack
-});
+// React Error Boundary (captura renderização/lifecycle com árvore de componentes)
+componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+  recorder.captureException(error, {
+    source: 'react',
+    componentStack: errorInfo.componentStack
+  });
+}
 ```
 
+#### Captura manual (try / catch)
+Para exceções capturadas imperativamente em handlers de eventos, chamadas assíncronas ou blocos `try/catch`, use `source: 'manual'`:
+
+```typescript
+// Captura imperativa sem árvore de componentes React
+try {
+  processCheckout();
+} catch (err) {
+  recorder.captureException(err, {
+    source: 'manual'
+  });
+}
+```
+
+> **Atenção:** Use `source: 'react'` apenas quando o erro foi capturado por um Error Boundary com a árvore de renderização. O visualizador e o simbolizador tratam `source: 'react'` e `componentStack` como a árvore de componentes da interface, e a stack JavaScript comum como o local exato do disparo da exceção.
+
 ---
 
 ## Remote Transport & beforeSend

package/bin/symbolize.cjs

@@ -7,9 +7,77 @@ const {
   sourceContentFor
 } = require('@jridgewell/trace-mapping');
 
-// ponytail: parser inicial cobre stacks V8; adicionar Firefox/Safari quando fixtures reais exigirem.
 const FRAME_WITH_FUNCTION = /^\s*at\s+(.+?)\s+\((.+):(\d+):(\d+)\)\s*$/;
+const FRAME_WITHOUT_FUNCTION_PARENS = /^\s*at\s+\((.+):(\d+):(\d+)\)\s*$/;
 const FRAME_WITHOUT_FUNCTION = /^\s*at\s+(.+):(\d+):(\d+)\s*$/;
+const FRAME_FIREFOX_SAFARI = /^\s*(.*?)\s*@\s*(.+):(\d+):(\d+)\s*$/;
+
+/**
+ * Analisa uma linha de stack trace (V8, Firefox ou Safari) e extrai
+ * nome da função, arquivo gerado, linha e coluna.
+ * @param {string} line
+ * @returns {{ functionName?: string, generatedFile: string, generatedLine: number, generatedColumn: number } | undefined}
+ */
+function parseStackFrame(line) {
+  if (!line || typeof line !== 'string') {
+    return undefined;
+  }
+
+  let functionName = undefined;
+  let generatedFile = undefined;
+  let lineStr = undefined;
+  let colStr = undefined;
+
+  const withFnMatch = line.match(FRAME_WITH_FUNCTION);
+  if (withFnMatch) {
+    functionName = withFnMatch[1].trim();
+    generatedFile = withFnMatch[2].trim();
+    lineStr = withFnMatch[3];
+    colStr = withFnMatch[4];
+  } else {
+    const withoutFnParensMatch = line.match(FRAME_WITHOUT_FUNCTION_PARENS);
+    if (withoutFnParensMatch) {
+      generatedFile = withoutFnParensMatch[1].trim();
+      lineStr = withoutFnParensMatch[2];
+      colStr = withoutFnParensMatch[3];
+    } else {
+      const withoutFnMatch = line.match(FRAME_WITHOUT_FUNCTION);
+      if (withoutFnMatch) {
+        generatedFile = withoutFnMatch[1].trim();
+        lineStr = withoutFnMatch[2];
+        colStr = withoutFnMatch[3];
+      } else {
+        const ffSafariMatch = line.match(FRAME_FIREFOX_SAFARI);
+        if (ffSafariMatch) {
+          const fn = ffSafariMatch[1].trim();
+          functionName = fn.length > 0 ? fn : undefined;
+          generatedFile = ffSafariMatch[2].trim();
+          lineStr = ffSafariMatch[3];
+          colStr = ffSafariMatch[4];
+        }
+      }
+    }
+  }
+
+  if (!generatedFile || !lineStr || !colStr) {
+    return undefined;
+  }
+
+  const generatedLine = parseInt(lineStr, 10);
+  const generatedColumn = parseInt(colStr, 10);
+
+  if (!Number.isInteger(generatedLine) || generatedLine <= 0 ||
+      !Number.isInteger(generatedColumn) || generatedColumn <= 0) {
+    return undefined;
+  }
+
+  return {
+    functionName,
+    generatedFile,
+    generatedLine,
+    generatedColumn
+  };
+}
 
 /**
  * Remove query string, hash, diretórios e decodifica URL para obter o nome do bundle.
@@ -220,45 +288,14 @@ function symbolicateStack(stack, options) {
   const traceMapCache = new Map();
 
   const lines = stack.split(/\r?\n/);
-  // Ignora a primeira linha contendo a mensagem do erro (se não for um frame)
-  const candidateLines = lines.length > 1 && !lines[0].trim().startsWith('at ')
-    ? lines.slice(1)
-    : lines;
-
-  for (const line of candidateLines) {
-    let parsedFunctionName = undefined;
-    let generatedFile = undefined;
-    let lineStr = undefined;
-    let colStr = undefined;
-
-    const withFnMatch = line.match(FRAME_WITH_FUNCTION);
-    if (withFnMatch) {
-      parsedFunctionName = withFnMatch[1];
-      generatedFile = withFnMatch[2];
-      lineStr = withFnMatch[3];
-      colStr = withFnMatch[4];
-    } else {
-      const withoutFnMatch = line.match(FRAME_WITHOUT_FUNCTION);
-      if (withoutFnMatch) {
-        generatedFile = withoutFnMatch[1];
-        lineStr = withoutFnMatch[2];
-        colStr = withoutFnMatch[3];
-      }
-    }
 
-    if (!generatedFile || !lineStr || !colStr) {
-      // Ignora linhas que não correspondam a um frame
+  for (const line of lines) {
+    const parsed = parseStackFrame(line);
+    if (!parsed) {
       continue;
     }
 
-    const generatedLine = parseInt(lineStr, 10);
-    const generatedColumn = parseInt(colStr, 10);
-
-    // Valida que linha e coluna são inteiros positivos
-    if (!Number.isInteger(generatedLine) || generatedLine <= 0 ||
-        !Number.isInteger(generatedColumn) || generatedColumn <= 0) {
-      continue;
-    }
+    const { functionName, generatedFile, generatedLine, generatedColumn } = parsed;
 
     const bundleName = extractBundleName(generatedFile);
     const matchingMaps = bundleMapFiles.get(bundleName);
@@ -267,7 +304,7 @@ function symbolicateStack(stack, options) {
       generatedFile,
       generatedLine,
       generatedColumn,
-      ...(parsedFunctionName ? { functionName: parsedFunctionName } : {})
+      ...(functionName ? { functionName } : {})
     };
 
     if (!matchingMaps || matchingMaps.length === 0) {
@@ -284,13 +321,17 @@ function symbolicateStack(stack, options) {
     }
 
     const mapPath = matchingMaps[0];
-    let traceMap = traceMapCache.get(mapPath);
-    if (!traceMap) {
+    let cached = traceMapCache.get(mapPath);
+    if (!cached) {
       try {
         const rawContent = fs.readFileSync(mapPath, 'utf-8');
         const parsedJson = JSON.parse(rawContent);
-        traceMap = new TraceMap(parsedJson);
-        traceMapCache.set(mapPath, traceMap);
+        const declaredBundle = parsedJson.file && typeof parsedJson.file === 'string'
+          ? extractBundleName(parsedJson.file)
+          : null;
+        const traceMap = new TraceMap(parsedJson);
+        cached = { traceMap, declaredBundle };
+        traceMapCache.set(mapPath, cached);
       } catch (err) {
         result.frames.push(unresolvedFrame);
         result.unresolvedCount++;
@@ -299,7 +340,19 @@ function symbolicateStack(stack, options) {
       }
     }
 
-    // A coluna da stack do navegador (V8) é 1-based, enquanto o TraceMap espera coluna 0-based
+    if (cached.declaredBundle && cached.declaredBundle !== bundleName) {
+      result.frames.push(unresolvedFrame);
+      result.unresolvedCount++;
+      const mapName = path.basename(mapPath);
+      result.warnings.push(
+        `Source map ${mapName} declara o bundle ${cached.declaredBundle}, mas o frame pertence a ${bundleName}.`
+      );
+      continue;
+    }
+
+    const traceMap = cached.traceMap;
+
+    // A coluna da stack do navegador (V8/Firefox/Safari) é 1-based, enquanto o TraceMap espera coluna 0-based
     const lookupColumn = generatedColumn > 0 ? generatedColumn - 1 : 0;
     let original = null;
     try {
@@ -326,7 +379,7 @@ function symbolicateStack(stack, options) {
       sourceFile: normalizeSourceFile(original.source),
       sourceLine: original.line,
       sourceColumn: original.column,
-      functionName: original.name ?? parsedFunctionName
+      ...((original.name ?? functionName) ? { functionName: original.name ?? functionName } : {})
     };
 
     const { context, warning } = extractContext(traceMap, original.source, original.line, contextLines);
@@ -388,6 +441,7 @@ Argumentos obrigatórios:
   --sourcemaps <diretório>       Diretório contendo os arquivos .map
 
 Opções adicionais:
+  --release <versão>            Versão da release para validação de compatibilidade
   --output <arquivo>            Caminho do arquivo de saída (padrão: <incidente>.symbolicated.ffr.json)
   --context-lines <número>      Quantidade de linhas de contexto antes e depois do erro (0-10, padrão: 3)
   -h, --help                    Mostra esta mensagem de ajuda
@@ -422,6 +476,7 @@ async function run(args = []) {
   let incidentPath = null;
   let sourcemapsDir = null;
   let outputPath = null;
+  let releaseArg = null;
   let contextLines = 3;
 
   for (let i = 0; i < args.length; i++) {
@@ -434,6 +489,13 @@ async function run(args = []) {
       sourcemapsDir = args[++i];
     } else if (arg === '--output') {
       outputPath = args[++i];
+    } else if (arg === '--release') {
+      releaseArg = args[++i];
+      if (!releaseArg || releaseArg.startsWith('-')) {
+        console.error('[Backtrack] Erro: Opção --release exige uma versão.');
+        process.exitCode = 1;
+        return 1;
+      }
     } else if (arg === '--context-lines') {
       const val = parseInt(args[++i], 10);
       if (!Number.isNaN(val)) {
@@ -546,37 +608,112 @@ async function run(args = []) {
     }
   }
 
-  let errorEventsCount = 0;
-  let totalResolvedFrames = 0;
-  let totalUnresolvedFrames = 0;
   const allWarnings = [];
 
+  const artifactRelease = artifact.context && typeof artifact.context.release === 'string'
+    ? artifact.context.release
+    : undefined;
+
+  let releaseStatusMsg = null;
+
+  if (releaseArg) {
+    if (artifactRelease) {
+      if (artifactRelease !== releaseArg) {
+        console.error(
+          `[Backtrack] Erro: Release informada (${releaseArg}) é incompatível com a release do incidente (${artifactRelease}).`
+        );
+        process.exitCode = 1;
+        return 1;
+      } else {
+        releaseStatusMsg = `Release: ${releaseArg} (release informada compatível)`;
+      }
+    } else {
+      allWarnings.push('A versão da release não pôde ser confirmada.');
+    }
+  } else if (artifactRelease) {
+    releaseStatusMsg = `Release do incidente: ${artifactRelease}`;
+    allWarnings.push(`Os source maps devem pertencer exatamente à release ${artifactRelease}.`);
+  }
+
+  let errorEventsCount = 0;
+  let exceptionResolvedFrames = 0;
+  let exceptionUnresolvedFrames = 0;
+  let reactResolvedFrames = 0;
+  let reactUnresolvedFrames = 0;
+
   const newTimeline = artifact.timeline.map((event) => {
-    if (event.type !== 'error' || !event.stack || typeof event.stack !== 'string') {
+    if (event.type !== 'error') {
+      return event;
+    }
+
+    const hasStack = typeof event.stack === 'string' && event.stack.trim().length > 0;
+    const hasComponentStack = typeof event.componentStack === 'string' && event.componentStack.trim().length > 0;
+
+    if (!hasStack && !hasComponentStack) {
       return event;
     }
 
     errorEventsCount++;
-    const result = symbolicateStack(event.stack, {
-      sourceMapsDirectory: sourcemapsDir,
-      contextLines
-    });
-
-    totalResolvedFrames += result.resolvedCount;
-    totalUnresolvedFrames += result.unresolvedCount;
-    if (result.warnings && result.warnings.length > 0) {
-      allWarnings.push(...result.warnings);
+
+    let stackFrames = [];
+    let stackResolvedCount = 0;
+    if (hasStack) {
+      const stackResult = symbolicateStack(event.stack, {
+        sourceMapsDirectory: sourcemapsDir,
+        contextLines
+      });
+      stackResolvedCount = stackResult.resolvedCount;
+      exceptionResolvedFrames += stackResult.resolvedCount;
+      exceptionUnresolvedFrames += stackResult.unresolvedCount;
+      if (stackResult.warnings && stackResult.warnings.length > 0) {
+        allWarnings.push(...stackResult.warnings);
+      }
+      stackFrames = stackResult.frames;
     }
 
+    let componentFrames = [];
+    let componentResolvedCount = 0;
+    if (hasComponentStack) {
+      const componentResult = symbolicateStack(event.componentStack, {
+        sourceMapsDirectory: sourcemapsDir,
+        contextLines
+      });
+      componentResolvedCount = componentResult.resolvedCount;
+      reactResolvedFrames += componentResult.resolvedCount;
+      reactUnresolvedFrames += componentResult.unresolvedCount;
+      if (componentResult.warnings && componentResult.warnings.length > 0) {
+        allWarnings.push(...componentResult.warnings);
+      }
+      componentFrames = componentResult.frames;
+    }
+
+    // Preserva stack e componentStack exatamente como recebidas.
+    // Não remove resolvedStack ou resolvedComponentStack existente se a nova execução não resolver nada.
+    const resolvedStack = stackFrames.length > 0 &&
+      (stackResolvedCount > 0 || !event.resolvedStack?.length)
+      ? stackFrames
+      : event.resolvedStack;
+
+    const resolvedComponentStack = componentFrames.length > 0 &&
+      (componentResolvedCount > 0 || !event.resolvedComponentStack?.length)
+      ? componentFrames
+      : event.resolvedComponentStack;
+
     return {
       ...event,
-      ...(result.frames.length > 0
-        ? { resolvedStack: result.frames }
+      ...(resolvedStack && resolvedStack.length > 0
+        ? { resolvedStack }
+        : {}),
+      ...(resolvedComponentStack && resolvedComponentStack.length > 0
+        ? { resolvedComponentStack }
         : {})
     };
   });
 
-  if (totalResolvedFrames === 0 && totalUnresolvedFrames === 0) {
+  const totalResolved = exceptionResolvedFrames + reactResolvedFrames;
+  const totalUnresolved = exceptionUnresolvedFrames + reactUnresolvedFrames;
+
+  if (totalResolved === 0 && totalUnresolved === 0) {
     console.log('[Backtrack] Nenhuma stack compatível foi encontrada.');
     process.exitCode = 0;
     return 0;
@@ -584,16 +721,21 @@ async function run(args = []) {
 
   const uniqueWarnings = Array.from(new Set(allWarnings));
 
-  if (totalUnresolvedFrames > 0) {
+  if (totalUnresolved > 0) {
     console.log('[Backtrack] Symbolication parcial.\n');
   } else {
     console.log('[Backtrack] Symbolication concluída.\n');
   }
 
   console.log(`Incidente: ${artifact.incident.id}`);
+  if (releaseStatusMsg) {
+    console.log(releaseStatusMsg);
+  }
   console.log(`Erros encontrados: ${errorEventsCount}`);
-  console.log(`Frames resolvidos: ${totalResolvedFrames}`);
-  console.log(`Frames não resolvidos: ${totalUnresolvedFrames}`);
+  console.log(`Frames da exceção resolvidos: ${exceptionResolvedFrames}`);
+  console.log(`Frames da exceção não resolvidos: ${exceptionUnresolvedFrames}`);
+  console.log(`Frames React resolvidos: ${reactResolvedFrames}`);
+  console.log(`Frames React não resolvidos: ${reactUnresolvedFrames}`);
   console.log(`Saída: ${resolvedOutput}`);
 
   if (uniqueWarnings.length > 0) {
@@ -642,6 +784,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  parseStackFrame,
   symbolicateStack,
   FRAME_WITH_FUNCTION,
   FRAME_WITHOUT_FUNCTION,