@backtrack-js/browser 0.5.2 → 0.5.4

package/README.md

@@ -1,54 +1,56 @@
-# Backtrack JS
-
-Flight recorder para aplicações web: captura uma janela recente da sessão, salva incidentes localmente e ajuda a investigar replay, rede e stack traces.
-
-## Instalação
-
-```sh
-npm install @backtrack-js/browser
-```
-
-Inicialize uma vez no cliente:
-
-```typescript
-import { Backtrack } from '@backtrack-js/browser';
-
-void Backtrack.init({
-  bufferMinutes: 5,
-  showWidget: true,
-  network: { capturePayloads: false }
-}).catch(error => {
-  console.warn('Backtrack não pôde iniciar', error);
-});
-```
-
-O widget permite salvar uma gravação. Abra o artefato no visualizador para investigar. A biblioteca não envia gravações para um servidor por padrão.
-
-## Documentação
-
-[English documentation](site/docs/content/en/overview.md) · [Português](site/docs/content/pt/overview.md)
-
-- [Primeiros passos](site/docs/content/pt/quickstart.md) e [integrações](site/docs/content/pt/integrations.md).
-- [Configuração](site/docs/content/pt/configuration.md), [privacidade e sanitização](site/docs/content/pt/privacy.md), [rede e disparos automáticos](site/docs/content/pt/network.md).
-- [Visualizador](site/docs/content/pt/viewer.md), [source maps](site/docs/content/pt/source-maps.md), [exportação local](site/docs/content/pt/local-export.md) e [transportes](site/docs/content/pt/transport.md).
-- [Referência da API](site/docs/content/pt/api.md), [solução de problemas](site/docs/content/pt/troubleshooting.md) e [versões e limitações](site/docs/content/pt/releases.md).
-
-Os guias descrevem o contrato local da versão 0.5.1. Recursos ainda não implementados são identificados explicitamente. Dados sintéticos não desativam automaticamente a sanitização fixa.
-
-## Desenvolvimento
-
-```sh
-npm install
-npm run build
-npm run build:viewer
-npm run build:site
-npm run preview:site
-```
-
-Documentação local: http://localhost:4174/docs/
-
-[Como editar e publicar o site](site/README.md). A saída do site é `dist/site`; a do visualizador permanece separada. A documentação ainda precisa de um destino de publicação.
-
-## Licença
-
-[Backtrack Free-Use License](LICENSE)
+# Backtrack JS
+
+Flight recorder para aplicações web: captura uma janela recente da sessão, salva incidentes localmente e ajuda a investigar replay, rede e stack traces.
+
+## Instalação
+
+```sh
+npm install @backtrack-js/browser
+```
+
+Inicialize uma vez no cliente:
+
+```typescript
+import { Backtrack } from '@backtrack-js/browser';
+
+void Backtrack.init({
+  bufferMinutes: 5,
+  showWidget: true,
+  network: { capturePayloads: false }
+}).catch(error => {
+  console.warn('Backtrack não pôde iniciar', error);
+});
+```
+
+Inicialize antes das interações: a captura retroativa usa apenas o histórico já registrado. O widget permite salvar uma gravação. Abra o artefato no visualizador para investigar. A biblioteca não envia gravações para um servidor por padrão.
+
+## Documentação
+
+[English documentation](site/docs/content/en/overview.md) · [Português](site/docs/content/pt/overview.md)
+
+- [Primeiros passos](site/docs/content/pt/quickstart.md) e [integrações](site/docs/content/pt/integrations.md).
+- [Configuração](site/docs/content/pt/configuration.md), [privacidade e sanitização](site/docs/content/pt/privacy.md), [rede e disparos automáticos](site/docs/content/pt/network.md).
+- [Visualizador](site/docs/content/pt/viewer.md), [source maps](site/docs/content/pt/source-maps.md), [exportação local](site/docs/content/pt/local-export.md) e [transportes](site/docs/content/pt/transport.md).
+- [Referência da API](site/docs/content/pt/api.md), [solução de problemas](site/docs/content/pt/troubleshooting.md) e [versões e limitações](site/docs/content/pt/releases.md).
+
+Os guias descrevem o contrato local da versão 0.5.3. Recursos ainda não implementados são identificados explicitamente. Dados sintéticos não desativam automaticamente a sanitização fixa.
+
+## Desenvolvimento
+
+```sh
+npm install
+npm run build
+npm run build:viewer
+npm run build:site
+npm run preview:site
+```
+
+Documentação local: http://localhost:4174/docs/
+
+[Como editar e publicar o site](site/README.md). A saída do site é `dist/site`; a do visualizador permanece separada. Destinos: [backtrack-site.netlify.app](https://backtrack-site.netlify.app) (documentação) e [backtrack-viewer.netlify.app](https://backtrack-viewer.netlify.app) (visualizador).
+
+Mudanças por versão: [CHANGELOG.md](CHANGELOG.md).
+
+## Licença
+
+[Backtrack Free-Use License](LICENSE)

package/bin/cli.cjs

@@ -7,6 +7,8 @@ Uso: backtrack [comando] [opções]
 Comandos:
   viewer                        Inicia o servidor local do Backtrack Viewer (padrão)
   symbolize <incidente> [opções] Resolve stack traces usando source maps
+  export-context <incidente>     Exporta relatórios locais em um pacote .tar
+  mcp --directory <pasta>        Inicia MCP stdio local somente leitura
 
 Opções globais:
   -h, --help                    Mostra esta mensagem de ajuda
@@ -22,8 +24,9 @@ if (command === '--help' || command === '-h') {
   return;
 }
 
-if (command === 'symbolize') {
-  const result = require('./symbolize.cjs').run(process.argv.slice(3));
+if (command === 'symbolize' || command === 'export-context' || command === 'mcp') {
+  const runner = command === 'symbolize' ? require('./symbolize.cjs') : command === 'mcp' ? require('./mcp.cjs') : require('./export-context.cjs');
+  const result = runner.run(process.argv.slice(3));
   if (result instanceof Promise) {
     result.then((code) => {
       if (typeof code === 'number') {

package/bin/export-context.cjs

@@ -0,0 +1,50 @@
+const fs = require('fs');
+const path = require('path');
+const { readLimitedFile } = require('./symbolize.cjs');
+
+async function run(args = []) {
+  let input, output;
+  const options = {};
+  const flags = {
+    '--max-events': 'maxEvents', '--max-bytes': 'maxSizeBytes',
+    '--before': 'windowBeforeSeconds', '--after': 'windowAfterSeconds'
+  };
+  try {
+    for (let index = 0; index < args.length; index++) {
+      const arg = args[index];
+      if (arg === '--help' || arg === '-h') {
+        console.log('Uso: backtrack export-context <incidente.json[.gz]> [--output <arquivo.tar>] [--max-events <1..1000>] [--max-bytes <4096..1048576>] [--before <segundos>] [--after <segundos>]\nExporta relatórios locais mascarados; não executa source maps, não inclui a gravação original e não modifica AGENTS.md. Saídas existentes nunca são sobrescritas.');
+        return 0;
+      }
+      if (arg === '--output' || Object.hasOwn(flags, arg)) {
+        const value = args[++index];
+        if (!value || value.startsWith('-')) throw new Error('Opção exige um valor.');
+        if (arg === '--output') output = value;
+        else {
+          if (!/^\d+(?:\.\d+)?$/.test(value) || !Number.isFinite(Number(value))) throw new Error('Limite numérico inválido.');
+          options[flags[arg]] = Number(value);
+        }
+      } else if (!arg.startsWith('-') && !input) input = arg;
+      else throw new Error('Argumento desconhecido ou duplicado.');
+    }
+    if (!input) throw new Error('Informe o incidente de entrada.');
+    const inputPath = path.resolve(input);
+    const outputPath = path.resolve(output || input.replace(/(?:\.ffr)?\.json(?:\.gz)?$/i, '') + '.context.tar');
+    if (fs.existsSync(outputPath)) throw new Error('O arquivo de saída já existe. Escolha outro caminho.');
+    const mod = require('../dist/index.cjs');
+    if (typeof mod.createIncidentContextPackage !== 'function' || typeof mod.decompressArtifact !== 'function') throw new Error('Build indisponível ou desatualizado. Execute o build da biblioteca.');
+    const artifact = await mod.decompressArtifact(new Uint8Array(readLimitedFile(inputPath)));
+    const bytes = mod.createIncidentContextPackage(artifact, options);
+    // Exclusive creation prevents replacement of input, links and unrelated files.
+    const fd = fs.openSync(outputPath, 'wx');
+    try { fs.writeFileSync(fd, bytes); }
+    catch (error) { fs.closeSync(fd); fs.unlinkSync(outputPath); throw error; }
+    fs.closeSync(fd);
+    console.log('[Backtrack] Pacote de contexto exportado. Extraia e comece em incident.md.');
+    return 0;
+  } catch (error) {
+    console.error('[Backtrack] Falha na exportação: ' + error.message);
+    return 1;
+  }
+}
+module.exports = { run };

package/bin/mcp.cjs

@@ -0,0 +1,19 @@
+const path = require('path');
+const { readProjectFile } = require('./symbolize.cjs');
+
+async function run(args = []) {
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    console.log('Uso: backtrack mcp --directory <pasta-absoluta-de-incidentes>\nMCP stdio somente leitura. Lê apenas <incidentId>.json nessa pasta; não executa comandos, não resolve mapas e não modifica arquivos.');
+    return 0;
+  }
+  try {
+    if (args.length !== 2 || args[0] !== '--directory' || !path.isAbsolute(args[1])) throw new Error('Informe --directory absoluto.');
+    const { runIncidentMcp } = require('../dist/mcp.cjs');
+    await runIncidentMcp(args[1], readProjectFile);
+    return 0;
+  } catch {
+    console.error('[Backtrack MCP] Falha: confira --directory absoluto, pasta regular e build atualizado.');
+    return 1;
+  }
+}
+module.exports = { run };

package/bin/symbolize.cjs

@@ -1,12 +1,79 @@
 const fs = require('fs');
 const path = require('path');
 const zlib = require('zlib');
+const { execFileSync } = require('child_process');
 const {
   TraceMap,
   originalPositionFor,
   sourceContentFor
 } = require('@jridgewell/trace-mapping');
 
+const MAX_LOCAL_BYTES = 50 * 1024 * 1024;
+
+function withinProject(root, file) {
+  const relative = path.relative(root, file);
+  return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep));
+}
+
+function projectMapsDirectory(projectRoot, directory) {
+  const root = fs.realpathSync(projectRoot);
+  const candidate = path.resolve(directory);
+  if (!withinProject(root, candidate)) throw new Error('Diretório fora do projeto autorizado.');
+  const real = fs.realpathSync(candidate);
+  if (!withinProject(root, real) || !fs.statSync(real).isDirectory()) {
+    throw new Error('Diretório de mapas escapa do projeto autorizado.');
+  }
+  return { root, directory: real };
+}
+
+/** Bounded read from an explicitly selected regular file; rejects growth and replacement. */
+function readLimitedFile(file, maxBytes = MAX_LOCAL_BYTES) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) throw new Error('Limite de leitura inválido.');
+  const expected = fs.statSync(file);
+  if (!expected.isFile() || expected.size > maxBytes) throw new Error('Arquivo excede o limite de leitura ou não é regular.');
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  try {
+    const actual = fs.fstatSync(fd);
+    if (!actual.isFile() || actual.dev !== expected.dev || actual.ino !== expected.ino || actual.size !== expected.size) {
+      throw new Error('Arquivo mudou durante a leitura.');
+    }
+    const buffer = Buffer.alloc(actual.size + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const read = fs.readSync(fd, buffer, size, buffer.length - size, null);
+      if (!read) break;
+      size += read;
+    }
+    if (size > maxBytes || size > actual.size) throw new Error('Arquivo excede o limite ou mudou durante a leitura.');
+    return buffer.subarray(0, size);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** Relative references are data. Only this explicit local resolver may read them. */
+function isProjectReference(reference) {
+  return typeof reference === 'string' && reference.length > 0 && !reference.includes('\0') &&
+    !path.posix.isAbsolute(reference) && !path.win32.isAbsolute(reference) && !reference.includes(':') &&
+    !reference.split(/[/\\]/).includes('..');
+}
+
+function sourceMapProjectReference(reference) {
+  const relative = reference.replace(/^webpack:\/\/\/(?:\.\/)?/, '').replace(/^\.\//, '');
+  // Empty disables lookup; never turn an absolute/traversing map source into a local filename.
+  return isProjectReference(relative) ? relative : '';
+}
+
+function readProjectFile(projectRoot, reference, maxBytes = MAX_LOCAL_BYTES) {
+  if (!isProjectReference(reference)) throw new Error('Referência de arquivo inválida para o projeto.');
+  const root = fs.realpathSync(projectRoot);
+  const candidate = path.resolve(root, reference.replace(/\\/g, '/'));
+  if (!withinProject(root, candidate)) throw new Error('Arquivo fora do projeto autorizado.');
+  const real = fs.realpathSync(candidate);
+  if (!withinProject(root, real)) throw new Error('Arquivo escapa do projeto autorizado.');
+  return readLimitedFile(real, maxBytes).toString('utf8');
+}
+
 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*$/;
@@ -142,46 +209,30 @@ function normalizeSourceFile(rawSource) {
  * @param {string} dir
  * @returns {Map<string, string[]>}
  */
-function findSourceMaps(dir) {
+function findSourceMaps(dir, root) {
   const mapFilesByBundle = new Map();
-
-  function walk(currentDir) {
-    let entries;
-    try {
-      entries = fs.readdirSync(currentDir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-
+  const pending = [{ directory: dir, depth: 0 }];
+  let entriesCount = 0;
+  while (pending.length) {
+    const current = pending.pop();
+    if (current.depth > 100) throw new Error('Profundidade de mapas excede o limite.');
+    const checked = projectMapsDirectory(root, current.directory);
+    const entries = fs.readdirSync(checked.directory, { withFileTypes: true });
+    entriesCount += entries.length;
+    if (entriesCount > 100000) throw new Error('Quantidade de arquivos de mapas excede o limite.');
     for (const entry of entries) {
-      const fullPath = path.join(currentDir, entry.name);
+      // Do not follow links during discovery, including directory junctions.
+      if (entry.isSymbolicLink()) continue;
+      const fullPath = path.join(checked.directory, 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);
-        }
+        pending.push({ directory: fullPath, depth: current.depth + 1 });
+      } else if (entry.isFile() && /\.(?:js|mjs|cjs)\.map$/.test(entry.name)) {
+        const bundleName = entry.name.slice(0, -4);
+        if (!mapFilesByBundle.has(bundleName)) mapFilesByBundle.set(bundleName, []);
+        mapFilesByBundle.get(bundleName).push(fullPath);
       }
     }
   }
-
-  if (dir && typeof dir === 'string' && fs.existsSync(dir)) {
-    walk(dir);
-  }
-
   return mapFilesByBundle;
 }
 
@@ -211,6 +262,10 @@ function extractContext(map, rawSource, originalLine, contextLinesOption) {
     };
   }
 
+  return extractTextContext(content, originalLine, contextLinesOption);
+}
+
+function extractTextContext(content, originalLine, contextLinesOption) {
   const allLines = content.split(/\r?\n/);
   const lineIdx = originalLine - 1; // 1-based para 0-based
 
@@ -252,7 +307,7 @@ function extractContext(map, rawSource, originalLine, contextLinesOption) {
 /**
  * Resolve os frames de uma stack V8 utilizando os source maps disponíveis.
  * @param {string} stack
- * @param {{ sourceMapsDirectory: string, contextLines?: number }} options
+ * @param {{ sourceMapsDirectory: string, projectRoot?: string, contextLines?: number }} options
  * @returns {{
  *   frames: Array<{
  *     generatedFile: string,
@@ -284,12 +339,23 @@ function symbolicateStack(stack, options) {
   const sourceMapsDir = options?.sourceMapsDirectory;
   const contextLines = options?.contextLines;
 
-  const bundleMapFiles = findSourceMaps(sourceMapsDir);
+  const projectRoot = options?.projectRoot ?? process.cwd();
+  let bundleMapFiles = new Map();
+  try {
+    const checked = projectMapsDirectory(projectRoot, sourceMapsDir);
+    bundleMapFiles = findSourceMaps(checked.directory, checked.root);
+  } catch (error) {
+    result.warnings.push(error.message);
+  }
   const traceMapCache = new Map();
 
   const lines = stack.split(/\r?\n/);
 
   for (const line of lines) {
+    if (result.frames.length >= 100) {
+      result.warnings.push('Resolução limitada a 100 frames; a stack original permanece preservada.');
+      break;
+    }
     const parsed = parseStackFrame(line);
     if (!parsed) {
       continue;
@@ -324,7 +390,7 @@ function symbolicateStack(stack, options) {
     let cached = traceMapCache.get(mapPath);
     if (!cached) {
       try {
-        const rawContent = fs.readFileSync(mapPath, 'utf-8');
+        const rawContent = readProjectFile(projectRoot, path.relative(fs.realpathSync(projectRoot), mapPath));
         const parsedJson = JSON.parse(rawContent);
         const declaredBundle = parsedJson.file && typeof parsedJson.file === 'string'
           ? extractBundleName(parsedJson.file)
@@ -377,6 +443,7 @@ function symbolicateStack(stack, options) {
       generatedLine,
       generatedColumn,
       sourceFile: normalizeSourceFile(original.source),
+      sourceReference: sourceMapProjectReference(original.source),
       sourceLine: original.line,
       sourceColumn: original.column,
       ...((original.name ?? functionName) ? { functionName: original.name ?? functionName } : {})
@@ -385,6 +452,7 @@ function symbolicateStack(stack, options) {
     const { context, warning } = extractContext(traceMap, original.source, original.line, contextLines);
     if (context) {
       resolvedFrame.context = context;
+      resolvedFrame.contextOrigin = 'source_map';
     }
     if (warning) {
       result.warnings.push(warning);
@@ -402,6 +470,59 @@ function symbolicateStack(stack, options) {
  * @param {Buffer} buffer
  * @returns {boolean}
  */
+/** Compare complete identities only; imported strings never become Git arguments. */
+function compareCommits(captureCommit, localCommit, workingTree = 'unknown') {
+  const fullCommit = value => typeof value === 'string' && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(value);
+  const commitMatch = fullCommit(captureCommit) && fullCommit(localCommit)
+    ? (captureCommit.toLowerCase() === localCommit.toLowerCase() ? 'matched' : 'divergent')
+    : 'unknown';
+  return { version: 1, ...(captureCommit !== undefined ? { captureCommit } : {}),
+    ...(fullCommit(localCommit) ? { localCommit } : {}), commitMatch, workingTree };
+}
+
+function inspectLocalVersion(projectRoot, captureCommit) {
+  // Fixed, bounded, read-only Git operations; do not inherit Git routing overrides.
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) if (key.toUpperCase().startsWith('GIT_')) delete env[key];
+  const options = { cwd: projectRoot, encoding: 'utf8', timeout: 5000,
+    maxBuffer: 1024 * 1024, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], env };
+  let localCommit;
+  let workingTree = 'unknown';
+  try {
+    localCommit = execFileSync('git', ['-c', 'core.fsmonitor=false', 'rev-parse', '--verify', 'HEAD'], options).trim();
+    try {
+      workingTree = execFileSync('git', ['-c', 'core.fsmonitor=false', 'status', '--porcelain', '--untracked-files=normal'], options).trim()
+        ? 'modified' : 'clean';
+    } catch {}
+  } catch {}
+  return compareCommits(captureCommit, localCommit, workingTree);
+}
+
+function enrichLocalFrames(frames, projectRoot, contextLines, warnings) {
+  return frames?.map(frame => {
+    // Refresh checkout excerpts on reruns; preserve imported/map context independently.
+    const { localContext: _previous, localContextTruncated: _truncated, ...reference } = frame;
+    if (!frame.sourceFile || !Number.isSafeInteger(frame.sourceLine)) return reference;
+    const rawReference = frame.sourceReference ?? frame.sourceFile;
+    const localReference = rawReference.replace(/^webpack:\/\/\/(?:\.\/)?/, '').replace(/^\.\//, '');
+    try {
+      const content = readProjectFile(projectRoot, localReference, 1024 * 1024);
+      const { context } = extractTextContext(content, frame.sourceLine, contextLines);
+      if (!context) {
+        warnings.push('Linha local indisponível: ' + frame.sourceFile + ':' + frame.sourceLine);
+        return reference;
+      }
+      const allLines = content.split(/\r?\n/);
+      const radius = Math.max(0, Math.min(10, Number.isFinite(contextLines) ? contextLines : 3));
+      const selected = allLines.slice(Math.max(0, frame.sourceLine - 1 - radius), frame.sourceLine + radius);
+      return { ...reference, localContext: context, localContextTruncated: selected.some(line => line.length > 2000) };
+    } catch {
+      warnings.push('Trecho local indisponível ou referência bloqueada: ' + frame.sourceFile);
+      return reference;
+    }
+  });
+}
+
 function isGzip(buffer) {
   return Buffer.isBuffer(buffer) && buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b;
 }
@@ -441,6 +562,7 @@ Argumentos obrigatórios:
   --sourcemaps <diretório>       Diretório contendo os arquivos .map
 
 Opções adicionais:
+  --project-root <diretório>    Projeto autorizado para leitura de mapas (padrão: diretório atual)
   --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)
@@ -478,6 +600,7 @@ async function run(args = []) {
   let outputPath = null;
   let releaseArg = null;
   let contextLines = 3;
+  let projectRoot = process.cwd();
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -487,6 +610,13 @@ async function run(args = []) {
     }
     if (arg === '--sourcemaps') {
       sourcemapsDir = args[++i];
+    } else if (arg === '--project-root') {
+      projectRoot = args[++i];
+      if (!projectRoot || projectRoot.startsWith('-')) {
+        console.error('[Backtrack] Erro: Opção --project-root exige um diretório.');
+        process.exitCode = 1;
+        return 1;
+      }
     } else if (arg === '--output') {
       outputPath = args[++i];
     } else if (arg === '--release') {
@@ -549,7 +679,7 @@ async function run(args = []) {
 
   let bytes;
   try {
-    bytes = fs.readFileSync(incidentPath);
+    bytes = readLimitedFile(incidentPath);
   } catch (err) {
     console.error(`[Backtrack] Erro ao ler o arquivo de incidente: ${err.message}`);
     process.exitCode = 1;
@@ -559,7 +689,7 @@ async function run(args = []) {
   let json;
   try {
     json = isGzip(bytes)
-      ? zlib.gunzipSync(bytes).toString('utf8')
+      ? zlib.gunzipSync(bytes, { maxOutputLength: MAX_LOCAL_BYTES }).toString('utf8')
       : bytes.toString('utf8');
   } catch (err) {
     console.error(`[Backtrack] Erro ao descompactar incidente: ${err.message}`);
@@ -584,31 +714,31 @@ async function run(args = []) {
   }
 
   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;
-    }
+  if (!validate) {
+    console.error('[Backtrack] Erro: Validador indisponível. Execute o build antes de importar incidentes.');
+    process.exitCode = 1;
+    return 1;
+  }
+  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;
+  }
+  artifact = valResult.data;
+  try {
+    const checked = projectMapsDirectory(projectRoot, sourcemapsDir);
+    projectRoot = checked.root;
+    sourcemapsDir = checked.directory;
+  } catch (error) {
+    console.error('[Backtrack] Erro: ' + error.message);
+    process.exitCode = 1;
+    return 1;
   }
 
   const allWarnings = [];
+  const codeContext = inspectLocalVersion(projectRoot, artifact.environment.gitCommit);
 
   const artifactRelease = artifact.context && typeof artifact.context.release === 'string'
     ? artifact.context.release
@@ -649,7 +779,7 @@ async function run(args = []) {
     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) {
+    if (!hasStack && !hasComponentStack && !event.resolvedStack?.length && !event.resolvedComponentStack?.length) {
       return event;
     }
 
@@ -660,6 +790,7 @@ async function run(args = []) {
     if (hasStack) {
       const stackResult = symbolicateStack(event.stack, {
         sourceMapsDirectory: sourcemapsDir,
+        projectRoot,
         contextLines
       });
       stackResolvedCount = stackResult.resolvedCount;
@@ -676,6 +807,7 @@ async function run(args = []) {
     if (hasComponentStack) {
       const componentResult = symbolicateStack(event.componentStack, {
         sourceMapsDirectory: sourcemapsDir,
+        projectRoot,
         contextLines
       });
       componentResolvedCount = componentResult.resolvedCount;
@@ -702,10 +834,10 @@ async function run(args = []) {
     return {
       ...event,
       ...(resolvedStack && resolvedStack.length > 0
-        ? { resolvedStack }
+        ? { resolvedStack: enrichLocalFrames(resolvedStack, projectRoot, contextLines, allWarnings) }
         : {}),
       ...(resolvedComponentStack && resolvedComponentStack.length > 0
-        ? { resolvedComponentStack }
+        ? { resolvedComponentStack: enrichLocalFrames(resolvedComponentStack, projectRoot, contextLines, allWarnings) }
         : {})
     };
   });
@@ -713,7 +845,9 @@ async function run(args = []) {
   const totalResolved = exceptionResolvedFrames + reactResolvedFrames;
   const totalUnresolved = exceptionUnresolvedFrames + reactUnresolvedFrames;
 
-  if (totalResolved === 0 && totalUnresolved === 0) {
+  const hasExistingReferences = newTimeline.some(event => event.type === 'error' &&
+    (event.resolvedStack?.length || event.resolvedComponentStack?.length));
+  if (totalResolved === 0 && totalUnresolved === 0 && !hasExistingReferences) {
     console.log('[Backtrack] Nenhuma stack compatível foi encontrada.');
     process.exitCode = 0;
     return 0;
@@ -728,6 +862,8 @@ async function run(args = []) {
   }
 
   console.log(`Incidente: ${artifact.incident.id}`);
+  console.log(`Commits: captura=${codeContext.captureCommit ?? 'desconhecido'}; local=${codeContext.localCommit ?? 'desconhecido'}; correspondência=${codeContext.commitMatch}; checkout=${codeContext.workingTree}`);
+  console.log('Referências são pontos de investigação; trechos locais têm correspondência não confirmada.');
   if (releaseStatusMsg) {
     console.log(releaseStatusMsg);
   }
@@ -747,8 +883,15 @@ async function run(args = []) {
 
   const symbolicatedArtifact = {
     ...artifact,
-    timeline: newTimeline
+    timeline: newTimeline,
+    codeContext
   };
+  const outputValidation = validate(symbolicatedArtifact);
+  if (!outputValidation.success) {
+    console.error('[Backtrack] Erro: enriquecimento excede os limites ou produziu dados inválidos.');
+    process.exitCode = 1;
+    return 1;
+  }
 
   const tempPath = `${resolvedOutput}.tmp`;
   try {
@@ -786,6 +929,11 @@ if (require.main === module) {
 module.exports = {
   parseStackFrame,
   symbolicateStack,
+  compareCommits,
+  inspectLocalVersion,
+  enrichLocalFrames,
+  readProjectFile,
+  readLimitedFile,
   FRAME_WITH_FUNCTION,
   FRAME_WITHOUT_FUNCTION,
   extractBundleName,