Core Symbolication

/**
 * Creates a symbolication context from source map content
 * @param SourceMapConsumer - SourceMapConsumer constructor from 'source-map' library
 * @param sourceMapContent - String content of the source map
 * @param options - Optional configuration for line/column offsets and naming
 * @returns SymbolicationContext for performing symbolication operations
 */
function createContext(
  SourceMapConsumer: typeof SourceMapConsumer,
  sourceMapContent: string,
  options?: ContextOptionsInput
): SymbolicationContext;

const Symbolication = require('metro-symbolicate/private/Symbolication');
const { SourceMapConsumer } = require('source-map');
const fs = require('fs');

// Basic context creation
const sourceMapContent = fs.readFileSync('bundle.js.map', 'utf8');
const context = Symbolication.createContext(SourceMapConsumer, sourceMapContent);

// With custom options
const context = Symbolication.createContext(SourceMapConsumer, sourceMapContent, {
  nameSource: 'function_names',
  inputLineStart: 0,
  outputLineStart: 1
});

/**
 * Creates a symbolication context from a directory of source maps
 * @param SourceMapConsumer - SourceMapConsumer constructor from 'source-map' library
 * @param sourceMapDir - Path to directory containing source map files
 * @param options - Optional configuration for line/column offsets and naming
 * @returns SymbolicationContext for performing symbolication operations
 */
function unstable_createDirectoryContext(
  SourceMapConsumer: typeof SourceMapConsumer,
  sourceMapDir: string,
  options?: ContextOptionsInput
): SymbolicationContext;

const Symbolication = require('metro-symbolicate/private/Symbolication');
const { SourceMapConsumer } = require('source-map');

// Directory-based context
const context = Symbolication.unstable_createDirectoryContext(
  SourceMapConsumer,
  './source-maps/',
  { nameSource: 'identifier_names' }
);

/**
 * Symbolicates a complete stack trace string
 * @param stackTrace - Stack trace string with bundled locations
 * @returns Symbolicated stack trace with original source locations
 */
symbolicate(stackTrace: string): string;

const stackTrace = `
Error: Something went wrong
    at Object.foo (bundle.js:1:234)
    at bar (bundle.js:2:456)
    at baz (bundle.js:3:789)
`;

const symbolicatedTrace = context.symbolicate(stackTrace);
console.log(symbolicatedTrace);
// Output:
// Error: Something went wrong
//     at Object.foo (src/utils.js:15:8)
//     at bar (src/main.js:22:12)
//     at baz (src/app.js:45:6)

/**
 * Gets original source position for bundled coordinates
 * @param line - Line number in bundled code
 * @param column - Column number in bundled code
 * @param moduleIds - Optional module identifiers for segmented bundles
 * @returns Original position information or null if not found
 */
getOriginalPositionFor(
  line: number,
  column: number,
  moduleIds?: ?SingleMapModuleIds
): ?{
  source: ?string;
  line: ?number;
  column: ?number;
  name: ?string;
};

// Basic coordinate translation
const original = context.getOriginalPositionFor(42, 15);
if (original) {
  console.log(`Original: ${original.source}:${original.line}:${original.column}`);
  console.log(`Function: ${original.name}`);
}

// With module IDs for segmented bundles
const originalWithModule = context.getOriginalPositionFor(10, 5, {
  segmentId: 123,
  localId: 456
});

/**
 * Parses a file name to extract module identifiers
 * @param fileName - File name potentially containing module ID (e.g., "123.js")
 * @returns Module identifiers or null if not a module file name
 */
parseFileName(fileName: string): ?SingleMapModuleIds;

// Parse module file names
const moduleIds = context.parseFileName('123.js');
if (moduleIds) {
  console.log(`Segment ID: ${moduleIds.segmentId}`);
  console.log(`Local ID: ${moduleIds.localId}`);
}

// Non-module file names return null
const noIds = context.parseFileName('regular-file.js'); // null

/**
 * Symbolicates a profiler map file
 * @param profMapFile - Path to .profmap file
 * @returns Symbolicated profiler map content
 */
symbolicateProfilerMap(profMapFile: string): string;

const fs = require('fs');

// Symbolicate profiler map
const symbolicatedProfMap = context.symbolicateProfilerMap('./trace.profmap');

// Write symbolicated output
fs.writeFileSync('./symbolicated-trace.profmap', symbolicatedProfMap);

/**
 * Symbolicates attribution object in-place
 * @param obj - Attribution object to modify with original source information
 */
symbolicateAttribution(obj: Object): void;

// Process attribution data
const attributionData = {
  location: {
    file: 'bundle.js',
    line: 42,
    column: 15,
    bytecodeSize: 1024
  }
};

context.symbolicateAttribution(attributionData);
// attributionData.location now contains original source information
console.log(attributionData.location.file); // 'src/component.js'

/**
 * Symbolicates a Chrome CPU profile file
 * @param traceFile - Path to .cpuprofile file
 * @param streams - Output streams for results and errors
 */
symbolicateChromeTrace(
  traceFile: string,
  streams: { stdout: any; stderr: any }
): void;

// Symbolicate CPU profile
context.symbolicateChromeTrace('./profile.cpuprofile', {
  stdout: process.stdout,
  stderr: process.stderr
});

/**
 * Symbolicates Hermes minidump crash information
 * @param crashInfo - Hermes crash dump data
 * @returns Symbolicated stack trace array
 */
symbolicateHermesMinidumpTrace(
  crashInfo: HermesMinidumpCrashInfo
): SymbolicatedStackTrace;

/**
 * Symbolicates Hermes coverage trace information
 * @param coverageInfo - Hermes coverage data
 * @returns Symbolicated coverage trace array
 */
symbolicateHermesCoverageTrace(
  coverageInfo: HermesCoverageInfo
): SymbolicatedStackTrace;

// Process Hermes crash dump
const crashData = JSON.parse(fs.readFileSync('hermes-crash.json', 'utf8'));
const symbolicatedCrash = context.symbolicateHermesMinidumpTrace(crashData);

// Process Hermes coverage trace
const coverageData = JSON.parse(fs.readFileSync('coverage.json', 'utf8'));
const symbolicatedCoverage = context.symbolicateHermesCoverageTrace(coverageData);

/**
 * Symbolicates a Chrome heap snapshot
 * @param snapshotContent - Heap snapshot JSON content as string
 * @returns Symbolicated heap snapshot object
 */
symbolicateHeapSnapshot(snapshotContent: string): ChromeHeapSnapshot;

// Symbolicate heap snapshot
const snapshotContent = fs.readFileSync('heap.heapsnapshot', 'utf8');
const symbolicatedSnapshot = context.symbolicateHeapSnapshot(snapshotContent);

// Write symbolicated snapshot
fs.writeFileSync(
  'symbolicated-heap.json',
  JSON.stringify(symbolicatedSnapshot)
);

type ContextOptionsInput = {
  /** Source for symbol names: 'function_names' (default) or 'identifier_names' */
  nameSource?: 'function_names' | 'identifier_names';
  /** Starting line number for input (default: 1) */
  inputLineStart?: number;
  /** Starting column number for input (default: 0) */
  inputColumnStart?: number;
  /** Starting line number for output (default: 1) */
  outputLineStart?: number;
  /** Starting column number for output (default: 0) */
  outputColumnStart?: number;
};

type SingleMapModuleIds = {
  /** Segment identifier for the module */
  segmentId: number;
  /** Local identifier within the segment */
  localId: ?number;
};

type HermesMinidumpCrashInfo = {
  callstack: $ReadOnlyArray<HermesMinidumpStackFrame | NativeCodeStackFrame>;
};

type HermesMinidumpStackFrame = $ReadOnly<{
  ByteCodeOffset: number;
  FunctionID: number;
  CJSModuleOffset?: number; // Legacy, renamed to SegmentID
  SegmentID?: number;
  SourceURL: string;
  StackFrameRegOffs: string;
  SourceLocation?: string;
}>;

type HermesCoverageInfo = {
  executedFunctions: $ReadOnlyArray<HermesCoverageStackFrame>;
};

type HermesCoverageStackFrame = $ReadOnly<{
  line: number; // SegmentID or zero-based line
  column: number; // VirtualOffset or zero-based column
  SourceURL: ?string;
}>;

type SymbolicatedStackTrace = $ReadOnlyArray<
  SymbolicatedStackFrame | NativeCodeStackFrame
>;

type SymbolicatedStackFrame = $ReadOnly<{
  source: ?string;
  line: ?number;
  column: ?number;
  name: ?string;
}>;

type NativeCodeStackFrame = $ReadOnly<{
  NativeCode: true;
  StackFrameRegOffs: string;
}>;