0
# Core Symbolication
1

2
Core API for creating symbolication contexts and translating bundle positions to original source locations.
3

4
## Capabilities
5

6
### Create Symbolication Context
7

8
Creates a symbolication context from source map content for processing stack traces and coordinates.
9

10
```javascript { .api }
11
/**
12
 * Creates a symbolication context from source map content
13
 * @param SourceMapConsumer - SourceMapConsumer constructor from 'source-map' library
14
 * @param sourceMapContent - String content of the source map
15
 * @param options - Optional configuration for line/column offsets and naming
16
 * @returns SymbolicationContext for performing symbolication operations
17
 */
18
function createContext(
19
  SourceMapConsumer: typeof SourceMapConsumer,
20
  sourceMapContent: string,
21
  options?: ContextOptionsInput
22
): SymbolicationContext;
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
const Symbolication = require('metro-symbolicate/private/Symbolication');
29
const { SourceMapConsumer } = require('source-map');
30
const fs = require('fs');
31

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

36
// With custom options
37
const context = Symbolication.createContext(SourceMapConsumer, sourceMapContent, {
38
  nameSource: 'function_names',
39
  inputLineStart: 0,
40
  outputLineStart: 1
41
});
42
```
43

44
### Create Directory Context (Unstable)
45

46
Creates a symbolication context from a directory containing multiple source map files.
47

48
```javascript { .api }
49
/**
50
 * Creates a symbolication context from a directory of source maps
51
 * @param SourceMapConsumer - SourceMapConsumer constructor from 'source-map' library
52
 * @param sourceMapDir - Path to directory containing source map files
53
 * @param options - Optional configuration for line/column offsets and naming
54
 * @returns SymbolicationContext for performing symbolication operations
55
 */
56
function unstable_createDirectoryContext(
57
  SourceMapConsumer: typeof SourceMapConsumer,
58
  sourceMapDir: string,
59
  options?: ContextOptionsInput
60
): SymbolicationContext;
61
```
62

63
**Usage Examples:**
64

65
```javascript
66
const Symbolication = require('metro-symbolicate/private/Symbolication');
67
const { SourceMapConsumer } = require('source-map');
68

69
// Directory-based context
70
const context = Symbolication.unstable_createDirectoryContext(
71
  SourceMapConsumer,
72
  './source-maps/',
73
  { nameSource: 'identifier_names' }
74
);
75
```
76

77
### Symbolicate Stack Traces
78

79
Transforms stack traces from bundled locations to original source locations.
80

81
```javascript { .api }
82
/**
83
 * Symbolicates a complete stack trace string
84
 * @param stackTrace - Stack trace string with bundled locations
85
 * @returns Symbolicated stack trace with original source locations
86
 */
87
symbolicate(stackTrace: string): string;
88
```
89

90
**Usage Examples:**
91

92
```javascript
93
const stackTrace = `
94
Error: Something went wrong
95
    at Object.foo (bundle.js:1:234)
96
    at bar (bundle.js:2:456)
97
    at baz (bundle.js:3:789)
98
`;
99

100
const symbolicatedTrace = context.symbolicate(stackTrace);
101
console.log(symbolicatedTrace);
102
// Output:
103
// Error: Something went wrong
104
//     at Object.foo (src/utils.js:15:8)
105
//     at bar (src/main.js:22:12)
106
//     at baz (src/app.js:45:6)
107
```
108

109
### Get Original Position
110

111
Translates specific line and column coordinates to original source locations.
112

113
```javascript { .api }
114
/**
115
 * Gets original source position for bundled coordinates
116
 * @param line - Line number in bundled code
117
 * @param column - Column number in bundled code
118
 * @param moduleIds - Optional module identifiers for segmented bundles
119
 * @returns Original position information or null if not found
120
 */
121
getOriginalPositionFor(
122
  line: number,
123
  column: number,
124
  moduleIds?: ?SingleMapModuleIds
125
): ?{
126
  source: ?string;
127
  line: ?number;
128
  column: ?number;
129
  name: ?string;
130
};
131
```
132

133
**Usage Examples:**
134

135
```javascript
136
// Basic coordinate translation
137
const original = context.getOriginalPositionFor(42, 15);
138
if (original) {
139
  console.log(`Original: ${original.source}:${original.line}:${original.column}`);
140
  console.log(`Function: ${original.name}`);
141
}
142

143
// With module IDs for segmented bundles
144
const originalWithModule = context.getOriginalPositionFor(10, 5, {
145
  segmentId: 123,
146
  localId: 456
147
});
148
```
149

150
### Parse File Names
151

152
Parses module file names to extract module identifiers for segmented bundles.
153

154
```javascript { .api }
155
/**
156
 * Parses a file name to extract module identifiers
157
 * @param fileName - File name potentially containing module ID (e.g., "123.js")
158
 * @returns Module identifiers or null if not a module file name
159
 */
160
parseFileName(fileName: string): ?SingleMapModuleIds;
161
```
162

163
**Usage Examples:**
164

165
```javascript
166
// Parse module file names
167
const moduleIds = context.parseFileName('123.js');
168
if (moduleIds) {
169
  console.log(`Segment ID: ${moduleIds.segmentId}`);
170
  console.log(`Local ID: ${moduleIds.localId}`);
171
}
172

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

177
### Symbolicate Profiler Maps
178

179
Processes React Native profiler map files to translate profiling data.
180

181
```javascript { .api }
182
/**
183
 * Symbolicates a profiler map file
184
 * @param profMapFile - Path to .profmap file
185
 * @returns Symbolicated profiler map content
186
 */
187
symbolicateProfilerMap(profMapFile: string): string;
188
```
189

190
**Usage Examples:**
191

192
```javascript
193
const fs = require('fs');
194

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

198
// Write symbolicated output
199
fs.writeFileSync('./symbolicated-trace.profmap', symbolicatedProfMap);
200
```
201

202
### Symbolicate Attribution Data
203

204
Processes bundle size attribution data for analysis tools.
205

206
```javascript { .api }
207
/**
208
 * Symbolicates attribution object in-place
209
 * @param obj - Attribution object to modify with original source information
210
 */
211
symbolicateAttribution(obj: Object): void;
212
```
213

214
**Usage Examples:**
215

216
```javascript
217
// Process attribution data
218
const attributionData = {
219
  location: {
220
    file: 'bundle.js',
221
    line: 42,
222
    column: 15,
223
    bytecodeSize: 1024
224
  }
225
};
226

227
context.symbolicateAttribution(attributionData);
228
// attributionData.location now contains original source information
229
console.log(attributionData.location.file); // 'src/component.js'
230
```
231

232
### Symbolicate Chrome Traces
233

234
Processes Chrome DevTools CPU profile files.
235

236
```javascript { .api }
237
/**
238
 * Symbolicates a Chrome CPU profile file
239
 * @param traceFile - Path to .cpuprofile file
240
 * @param streams - Output streams for results and errors
241
 */
242
symbolicateChromeTrace(
243
  traceFile: string,
244
  streams: { stdout: any; stderr: any }
245
): void;
246
```
247

248
**Usage Examples:**
249

250
```javascript
251
// Symbolicate CPU profile
252
context.symbolicateChromeTrace('./profile.cpuprofile', {
253
  stdout: process.stdout,
254
  stderr: process.stderr
255
});
256
```
257

258
### Hermes Integration
259

260
Special methods for processing Hermes JavaScript engine crash dumps and coverage traces.
261

262
```javascript { .api }
263
/**
264
 * Symbolicates Hermes minidump crash information
265
 * @param crashInfo - Hermes crash dump data
266
 * @returns Symbolicated stack trace array
267
 */
268
symbolicateHermesMinidumpTrace(
269
  crashInfo: HermesMinidumpCrashInfo
270
): SymbolicatedStackTrace;
271

272
/**
273
 * Symbolicates Hermes coverage trace information
274
 * @param coverageInfo - Hermes coverage data
275
 * @returns Symbolicated coverage trace array
276
 */
277
symbolicateHermesCoverageTrace(
278
  coverageInfo: HermesCoverageInfo
279
): SymbolicatedStackTrace;
280
```
281

282
**Usage Examples:**
283

284
```javascript
285
// Process Hermes crash dump
286
const crashData = JSON.parse(fs.readFileSync('hermes-crash.json', 'utf8'));
287
const symbolicatedCrash = context.symbolicateHermesMinidumpTrace(crashData);
288

289
// Process Hermes coverage trace
290
const coverageData = JSON.parse(fs.readFileSync('coverage.json', 'utf8'));
291
const symbolicatedCoverage = context.symbolicateHermesCoverageTrace(coverageData);
292
```
293

294
### Symbolicate Heap Snapshots
295

296
Processes Chrome DevTools heap snapshots and heap timelines.
297

298
```javascript { .api }
299
/**
300
 * Symbolicates a Chrome heap snapshot
301
 * @param snapshotContent - Heap snapshot JSON content as string
302
 * @returns Symbolicated heap snapshot object
303
 */
304
symbolicateHeapSnapshot(snapshotContent: string): ChromeHeapSnapshot;
305
```
306

307
**Usage Examples:**
308

309
```javascript
310
// Symbolicate heap snapshot
311
const snapshotContent = fs.readFileSync('heap.heapsnapshot', 'utf8');
312
const symbolicatedSnapshot = context.symbolicateHeapSnapshot(snapshotContent);
313

314
// Write symbolicated snapshot
315
fs.writeFileSync(
316
  'symbolicated-heap.json',
317
  JSON.stringify(symbolicatedSnapshot)
318
);
319
```
320

321
## Types
322

323
```javascript { .api }
324
type ContextOptionsInput = {
325
  /** Source for symbol names: 'function_names' (default) or 'identifier_names' */
326
  nameSource?: 'function_names' | 'identifier_names';
327
  /** Starting line number for input (default: 1) */
328
  inputLineStart?: number;
329
  /** Starting column number for input (default: 0) */
330
  inputColumnStart?: number;
331
  /** Starting line number for output (default: 1) */
332
  outputLineStart?: number;
333
  /** Starting column number for output (default: 0) */
334
  outputColumnStart?: number;
335
};
336

337
type SingleMapModuleIds = {
338
  /** Segment identifier for the module */
339
  segmentId: number;
340
  /** Local identifier within the segment */
341
  localId: ?number;
342
};
343

344
type HermesMinidumpCrashInfo = {
345
  callstack: $ReadOnlyArray<HermesMinidumpStackFrame | NativeCodeStackFrame>;
346
};
347

348
type HermesMinidumpStackFrame = $ReadOnly<{
349
  ByteCodeOffset: number;
350
  FunctionID: number;
351
  CJSModuleOffset?: number; // Legacy, renamed to SegmentID
352
  SegmentID?: number;
353
  SourceURL: string;
354
  StackFrameRegOffs: string;
355
  SourceLocation?: string;
356
}>;
357

358
type HermesCoverageInfo = {
359
  executedFunctions: $ReadOnlyArray<HermesCoverageStackFrame>;
360
};
361

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

368
type SymbolicatedStackTrace = $ReadOnlyArray<
369
  SymbolicatedStackFrame | NativeCodeStackFrame
370
>;
371

372
type SymbolicatedStackFrame = $ReadOnly<{
373
  source: ?string;
374
  line: ?number;
375
  column: ?number;
376
  name: ?string;
377
}>;
378

379
type NativeCodeStackFrame = $ReadOnly<{
380
  NativeCode: true;
381
  StackFrameRegOffs: string;
382
}>;
383
```