@backtrack-js/browser 0.4.0

package/bin/symbolize.cjs

@@ -0,0 +1,654 @@
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+const {
+  TraceMap,
+  originalPositionFor,
+  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 = /^\s*at\s+(.+):(\d+):(\d+)\s*$/;
+
+/**
+ * Remove query string, hash, diretórios e decodifica URL para obter o nome do bundle.
+ * @param {string} generatedFile
+ * @returns {string}
+ */
+function extractBundleName(generatedFile) {
+  if (!generatedFile || typeof generatedFile !== 'string') return '';
+  let cleaned = generatedFile;
+  // Remove hash
+  cleaned = cleaned.split('#')[0];
+  // Remove query string
+  cleaned = cleaned.split('?')[0];
+  // URL decode
+  try {
+    cleaned = decodeURIComponent(cleaned);
+  } catch {}
+  // Extrai nome do arquivo
+  const segments = cleaned.split(/[/\\]/);
+  return segments[segments.length - 1] || '';
+}
+
+/**
+ * Normaliza o caminho do arquivo de origem para evitar vazar caminhos absolutos locais.
+ * Salva preferencialmente a partir de src/ e trata prefixos como webpack:///./
+ * @param {string} rawSource
+ * @returns {string | undefined}
+ */
+function normalizeSourceFile(rawSource) {
+  if (!rawSource || typeof rawSource !== 'string') return undefined;
+  let normalized = rawSource.replace(/\\/g, '/');
+
+  // Tratar prefixos comuns de bundlers
+  normalized = normalized.replace(/^webpack:\/\/\/\.\//, '');
+  normalized = normalized.replace(/^webpack:\/\/\//, '');
+  normalized = normalized.replace(/^\.\//, '');
+
+  // Caminhos absolutos: salvar preferencialmente a partir de src/
+  const srcIdx = normalized.lastIndexOf('src/');
+  if (srcIdx !== -1) {
+    return normalized.slice(srcIdx);
+  }
+
+  // Detectar caminhos absolutos: file://, POSIX (/...) ou Windows (C:/... ou //UNC)
+  const isFileUri = /^file:\/\//i.test(rawSource) || /^file:\/\//i.test(normalized);
+  const isPosixAbsolute = normalized.startsWith('/');
+  const isWindowsAbsolute = /^[a-zA-Z]:\//.test(normalized) || normalized.startsWith('//');
+
+  if (isFileUri || isPosixAbsolute || isWindowsAbsolute) {
+    // Se for absoluto e não tiver src/, retornar apenas o nome do arquivo
+    const segments = normalized.split(/[/\\]/);
+    const fileName = segments[segments.length - 1];
+    return fileName || normalized;
+  }
+
+  // Caminhos relativos legítimos não são alterados
+  return normalized;
+}
+
+/**
+ * Percorre recursivamente o diretório em busca de arquivos .js.map, .mjs.map e .cjs.map.
+ * @param {string} dir
+ * @returns {Map<string, string[]>}
+ */
+function findSourceMaps(dir) {
+  const mapFilesByBundle = new Map();
+
+  function walk(currentDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const name = entry.name;
+        let bundleName = null;
+        if (name.endsWith('.js.map')) {
+          bundleName = name.slice(0, -4);
+        } else if (name.endsWith('.mjs.map')) {
+          bundleName = name.slice(0, -4);
+        } else if (name.endsWith('.cjs.map')) {
+          bundleName = name.slice(0, -4);
+        }
+
+        if (bundleName) {
+          if (!mapFilesByBundle.has(bundleName)) {
+            mapFilesByBundle.set(bundleName, []);
+          }
+          mapFilesByBundle.get(bundleName).push(fullPath);
+        }
+      }
+    }
+  }
+
+  if (dir && typeof dir === 'string' && fs.existsSync(dir)) {
+    walk(dir);
+  }
+
+  return mapFilesByBundle;
+}
+
+/**
+ * Extrai linhas de contexto do código-fonte original contido no .map.
+ * @param {any} map
+ * @param {string} rawSource
+ * @param {number} originalLine
+ * @param {number | undefined} contextLinesOption
+ * @returns {{ context?: { before: string[], line: string, after: string[] }, warning?: string }}
+ */
+function extractContext(map, rawSource, originalLine, contextLinesOption) {
+  let content = null;
+  try {
+    content = sourceContentFor(map, rawSource, true);
+  } catch {
+    return {
+      context: undefined,
+      warning: `sourcesContent não disponível para ${rawSource}.`
+    };
+  }
+
+  if (!content || typeof content !== 'string') {
+    return {
+      context: undefined,
+      warning: `sourcesContent não disponível para ${rawSource}.`
+    };
+  }
+
+  const allLines = content.split(/\r?\n/);
+  const lineIdx = originalLine - 1; // 1-based para 0-based
+
+  if (lineIdx < 0 || lineIdx >= allLines.length) {
+    return { context: undefined, warning: undefined };
+  }
+
+  let cl = typeof contextLinesOption === 'number' ? contextLinesOption : 3;
+  cl = Math.max(0, Math.min(10, cl)); // Limites: mínimo 0, máximo 10
+
+  const startIdx = Math.max(0, lineIdx - cl);
+  const endIdx = Math.min(allLines.length - 1, lineIdx + cl);
+
+  const truncate = (str) => {
+    if (str.length > 2000) {
+      return str.slice(0, 2000);
+    }
+    return str;
+  };
+
+  const before = [];
+  for (let i = startIdx; i < lineIdx; i++) {
+    before.push(truncate(allLines[i]));
+  }
+
+  const line = truncate(allLines[lineIdx]);
+
+  const after = [];
+  for (let i = lineIdx + 1; i <= endIdx; i++) {
+    after.push(truncate(allLines[i]));
+  }
+
+  return {
+    context: { before, line, after },
+    warning: undefined
+  };
+}
+
+/**
+ * Resolve os frames de uma stack V8 utilizando os source maps disponíveis.
+ * @param {string} stack
+ * @param {{ sourceMapsDirectory: string, contextLines?: number }} options
+ * @returns {{
+ *   frames: Array<{
+ *     generatedFile: string,
+ *     generatedLine: number,
+ *     generatedColumn: number,
+ *     sourceFile?: string,
+ *     sourceLine?: number,
+ *     sourceColumn?: number,
+ *     functionName?: string,
+ *     context?: { before: string[], line: string, after: string[] }
+ *   }>,
+ *   resolvedCount: number,
+ *   unresolvedCount: number,
+ *   warnings: string[]
+ * }}
+ */
+function symbolicateStack(stack, options) {
+  const result = {
+    frames: [],
+    resolvedCount: 0,
+    unresolvedCount: 0,
+    warnings: []
+  };
+
+  if (!stack || typeof stack !== 'string') {
+    return result;
+  }
+
+  const sourceMapsDir = options?.sourceMapsDirectory;
+  const contextLines = options?.contextLines;
+
+  const bundleMapFiles = findSourceMaps(sourceMapsDir);
+  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
+      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 bundleName = extractBundleName(generatedFile);
+    const matchingMaps = bundleMapFiles.get(bundleName);
+
+    const unresolvedFrame = {
+      generatedFile,
+      generatedLine,
+      generatedColumn,
+      ...(parsedFunctionName ? { functionName: parsedFunctionName } : {})
+    };
+
+    if (!matchingMaps || matchingMaps.length === 0) {
+      result.frames.push(unresolvedFrame);
+      result.unresolvedCount++;
+      continue;
+    }
+
+    if (matchingMaps.length > 1) {
+      result.frames.push(unresolvedFrame);
+      result.unresolvedCount++;
+      result.warnings.push(`Mais de um source map encontrado para ${bundleName}.`);
+      continue;
+    }
+
+    const mapPath = matchingMaps[0];
+    let traceMap = traceMapCache.get(mapPath);
+    if (!traceMap) {
+      try {
+        const rawContent = fs.readFileSync(mapPath, 'utf-8');
+        const parsedJson = JSON.parse(rawContent);
+        traceMap = new TraceMap(parsedJson);
+        traceMapCache.set(mapPath, traceMap);
+      } catch (err) {
+        result.frames.push(unresolvedFrame);
+        result.unresolvedCount++;
+        result.warnings.push(`Erro ao carregar source map ${mapPath}: ${err.message}`);
+        continue;
+      }
+    }
+
+    // A coluna da stack do navegador (V8) é 1-based, enquanto o TraceMap espera coluna 0-based
+    const lookupColumn = generatedColumn > 0 ? generatedColumn - 1 : 0;
+    let original = null;
+    try {
+      original = originalPositionFor(traceMap, {
+        line: generatedLine,
+        column: lookupColumn
+      });
+    } catch {
+      result.frames.push(unresolvedFrame);
+      result.unresolvedCount++;
+      continue;
+    }
+
+    if (!original || !original.source || original.line == null) {
+      result.frames.push(unresolvedFrame);
+      result.unresolvedCount++;
+      continue;
+    }
+
+    const resolvedFrame = {
+      generatedFile,
+      generatedLine,
+      generatedColumn,
+      sourceFile: normalizeSourceFile(original.source),
+      sourceLine: original.line,
+      sourceColumn: original.column,
+      functionName: original.name ?? parsedFunctionName
+    };
+
+    const { context, warning } = extractContext(traceMap, original.source, original.line, contextLines);
+    if (context) {
+      resolvedFrame.context = context;
+    }
+    if (warning) {
+      result.warnings.push(warning);
+    }
+
+    result.frames.push(resolvedFrame);
+    result.resolvedCount++;
+  }
+
+  return result;
+}
+
+/**
+ * Detecta se o buffer possui o cabeçalho mágico de gzip (0x1f, 0x8b).
+ * @param {Buffer} buffer
+ * @returns {boolean}
+ */
+function isGzip(buffer) {
+  return Buffer.isBuffer(buffer) && buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b;
+}
+
+/**
+ * Calcula o caminho de saída padrão para o incidente simbolizado.
+ * Ex: bug.ffr.json -> bug.symbolicated.ffr.json
+ *     bug.ffr.json.gz -> bug.symbolicated.ffr.json
+ * @param {string} inputPath
+ * @returns {string}
+ */
+function computeDefaultOutputPath(inputPath) {
+  const dir = path.dirname(inputPath);
+  let base = path.basename(inputPath);
+
+  if (base.endsWith('.ffr.json.gz')) {
+    base = base.slice(0, -'.ffr.json.gz'.length);
+  } else if (base.endsWith('.ffr.json')) {
+    base = base.slice(0, -'.ffr.json'.length);
+  } else if (base.endsWith('.json.gz')) {
+    base = base.slice(0, -'.json.gz'.length);
+  } else if (base.endsWith('.json')) {
+    base = base.slice(0, -'.json'.length);
+  } else if (base.endsWith('.gz')) {
+    base = base.slice(0, -'.gz'.length);
+  }
+
+  return path.join(dir, `${base}.symbolicated.ffr.json`);
+}
+
+function printSymbolizeHelp() {
+  console.log(`
+Uso: backtrack symbolize <incidente> --sourcemaps <diretório> [opções]
+
+Argumentos obrigatórios:
+  <incidente>                   Caminho para o arquivo do incidente (.ffr.json, .ffr.json.gz, etc.)
+  --sourcemaps <diretório>       Diretório contendo os arquivos .map
+
+Opções adicionais:
+  --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
+`.trim());
+}
+
+/**
+ * Tenta carregar validateFlightRecorderArtifact do build gerado.
+ */
+async function loadValidator() {
+  try {
+    const mod = require('../dist/index.cjs');
+    if (mod && typeof mod.validateFlightRecorderArtifact === 'function') {
+      return mod.validateFlightRecorderArtifact;
+    }
+  } catch {}
+  try {
+    const mod = await import('../dist/index.js');
+    if (mod && typeof mod.validateFlightRecorderArtifact === 'function') {
+      return mod.validateFlightRecorderArtifact;
+    }
+  } catch {}
+  return null;
+}
+
+/**
+ * Executa o comando symbolize com os argumentos fornecidos na CLI.
+ * @param {string[]} args
+ * @returns {Promise<number>} Código de saída (0 ou 1)
+ */
+async function run(args = []) {
+  let incidentPath = null;
+  let sourcemapsDir = null;
+  let outputPath = null;
+  let contextLines = 3;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') {
+      printSymbolizeHelp();
+      return 0;
+    }
+    if (arg === '--sourcemaps') {
+      sourcemapsDir = args[++i];
+    } else if (arg === '--output') {
+      outputPath = args[++i];
+    } else if (arg === '--context-lines') {
+      const val = parseInt(args[++i], 10);
+      if (!Number.isNaN(val)) {
+        contextLines = val;
+      }
+    } else if (!arg.startsWith('-') && !incidentPath) {
+      incidentPath = arg;
+    } else {
+      console.error(`[Backtrack] Argumento desconhecido ou inválido: ${arg}`);
+      process.exitCode = 1;
+      return 1;
+    }
+  }
+
+  if (!incidentPath) {
+    console.error('[Backtrack] Erro: Caminho do arquivo de incidente não informado.');
+    process.exitCode = 1;
+    return 1;
+  }
+
+  if (!sourcemapsDir) {
+    console.error('[Backtrack] Erro: Opção --sourcemaps é obrigatória.');
+    process.exitCode = 1;
+    return 1;
+  }
+
+  if (!fs.existsSync(incidentPath)) {
+    console.error(`[Backtrack] Erro: Arquivo de incidente não encontrado: ${incidentPath}`);
+    process.exitCode = 1;
+    return 1;
+  }
+
+  if (!fs.existsSync(sourcemapsDir) || !fs.statSync(sourcemapsDir).isDirectory()) {
+    console.error(`[Backtrack] Erro: Diretório de source maps não encontrado: ${sourcemapsDir}`);
+    process.exitCode = 1;
+    return 1;
+  }
+
+  const finalOutputPath = outputPath || computeDefaultOutputPath(incidentPath);
+  const resolvedInput = path.resolve(incidentPath);
+  const resolvedOutput = path.resolve(finalOutputPath);
+
+  if (
+    resolvedInput === resolvedOutput ||
+    (process.platform === 'win32' && resolvedInput.toLowerCase() === resolvedOutput.toLowerCase())
+  ) {
+    console.error('[Backtrack] Erro: o arquivo de saída não pode sobrescrever o incidente original.');
+    process.exitCode = 1;
+    return 1;
+  }
+
+  let bytes;
+  try {
+    bytes = fs.readFileSync(incidentPath);
+  } catch (err) {
+    console.error(`[Backtrack] Erro ao ler o arquivo de incidente: ${err.message}`);
+    process.exitCode = 1;
+    return 1;
+  }
+
+  let json;
+  try {
+    json = isGzip(bytes)
+      ? zlib.gunzipSync(bytes).toString('utf8')
+      : bytes.toString('utf8');
+  } catch (err) {
+    console.error(`[Backtrack] Erro ao descompactar incidente: ${err.message}`);
+    process.exitCode = 1;
+    return 1;
+  }
+
+  const MAX_BYTES = 50 * 1024 * 1024;
+  if (Buffer.byteLength(json, 'utf8') > MAX_BYTES) {
+    console.error('[Backtrack] Erro: Tamanho do incidente descompactado excede o limite de 50 MB.');
+    process.exitCode = 1;
+    return 1;
+  }
+
+  let artifact;
+  try {
+    artifact = JSON.parse(json);
+  } catch (err) {
+    console.error(`[Backtrack] Erro ao analisar JSON do incidente: ${err.message}`);
+    process.exitCode = 1;
+    return 1;
+  }
+
+  const validate = await loadValidator();
+  if (validate) {
+    const valResult = validate(artifact);
+    if (!valResult.success) {
+      console.error('[Backtrack] Erro: Artefato inválido:');
+      for (const errorMsg of valResult.errors) {
+        console.error(`  - ${errorMsg}`);
+      }
+      process.exitCode = 1;
+      return 1;
+    }
+  } else {
+    if (
+      !artifact ||
+      typeof artifact !== 'object' ||
+      !Array.isArray(artifact.timeline) ||
+      !artifact.incident ||
+      typeof artifact.incident.id !== 'string'
+    ) {
+      console.error('[Backtrack] Erro: Artefato inválido: estrutura básica incorreta.');
+      process.exitCode = 1;
+      return 1;
+    }
+  }
+
+  let errorEventsCount = 0;
+  let totalResolvedFrames = 0;
+  let totalUnresolvedFrames = 0;
+  const allWarnings = [];
+
+  const newTimeline = artifact.timeline.map((event) => {
+    if (event.type !== 'error' || !event.stack || typeof event.stack !== 'string') {
+      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);
+    }
+
+    return {
+      ...event,
+      ...(result.frames.length > 0
+        ? { resolvedStack: result.frames }
+        : {})
+    };
+  });
+
+  if (totalResolvedFrames === 0 && totalUnresolvedFrames === 0) {
+    console.log('[Backtrack] Nenhuma stack compatível foi encontrada.');
+    process.exitCode = 0;
+    return 0;
+  }
+
+  const uniqueWarnings = Array.from(new Set(allWarnings));
+
+  if (totalUnresolvedFrames > 0) {
+    console.log('[Backtrack] Symbolication parcial.\n');
+  } else {
+    console.log('[Backtrack] Symbolication concluída.\n');
+  }
+
+  console.log(`Incidente: ${artifact.incident.id}`);
+  console.log(`Erros encontrados: ${errorEventsCount}`);
+  console.log(`Frames resolvidos: ${totalResolvedFrames}`);
+  console.log(`Frames não resolvidos: ${totalUnresolvedFrames}`);
+  console.log(`Saída: ${resolvedOutput}`);
+
+  if (uniqueWarnings.length > 0) {
+    console.log('\nAvisos:');
+    for (const w of uniqueWarnings) {
+      console.log(`- ${w}`);
+    }
+  }
+
+  const symbolicatedArtifact = {
+    ...artifact,
+    timeline: newTimeline
+  };
+
+  const tempPath = `${resolvedOutput}.tmp`;
+  try {
+    fs.writeFileSync(tempPath, JSON.stringify(symbolicatedArtifact, null, 2), 'utf8');
+    if (fs.existsSync(resolvedOutput)) {
+      fs.unlinkSync(resolvedOutput);
+    }
+    fs.renameSync(tempPath, resolvedOutput);
+  } catch (err) {
+    if (fs.existsSync(tempPath)) {
+      try {
+        fs.unlinkSync(tempPath);
+      } catch {}
+    }
+    console.error(`[Backtrack] Erro ao gravar arquivo de saída: ${err.message}`);
+    process.exitCode = 1;
+    return 1;
+  }
+
+  process.exitCode = 0;
+  return 0;
+}
+
+if (require.main === module) {
+  run(process.argv.slice(2)).then((code) => {
+    if (typeof code === 'number') {
+      process.exitCode = code;
+    }
+  }).catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  symbolicateStack,
+  FRAME_WITH_FUNCTION,
+  FRAME_WITHOUT_FUNCTION,
+  extractBundleName,
+  normalizeSourceFile,
+  isGzip,
+  computeDefaultOutputPath,
+  loadValidator,
+  run
+};