profiler-md 0.8.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,77 +1,63 @@
1
1
  import { RawSourceMap as SourceMap, SourceMapConsumer } from "source-map-js";
2
- //#region src/helpers/types.d.ts
2
+ type DeepReadonly<T> = T extends Map<infer K, infer V> ? ReadonlyMap<K, DeepReadonly<V>> : T extends Set<infer V> ? ReadonlySet<DeepReadonly<V>> : T extends TypedArray ? Readonly<T> : T extends (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]>; } : T;
3
3
  type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float16Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
4
4
  /**
5
- * Recursively makes all properties of `T` readonly, including nested objects,
6
- * arrays, and `Map`/`Set` collections.
5
+ * Receives a conversion's diagnostics, one message per call.
6
+ *
7
+ * Only defined methods are called, so `console` qualifies as a logger, and so
8
+ * does `{ warn: console.warn }`.
7
9
  */
8
- type DeepReadonly<T> = T extends Map<infer K, infer V> ? ReadonlyMap<K, DeepReadonly<V>> : T extends Set<infer V> ? ReadonlySet<DeepReadonly<V>> : T extends TypedArray ? Readonly<T> : T extends (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]>; } : T;
9
- //#endregion
10
- //#region src/location.d.ts
11
- /** A source reference, potentially with line and column information. */
12
- type SourceLocation = SourceReference & {
13
- /** The 1-based line number in the referenced source. */
14
- line?: number;
15
- /** The 1-based column number in the referenced source. */
16
- column?: number;
17
- };
18
- /** A reference to where a function is defined: a file or a logical name. */
19
- type SourceReference = FileReference | LogicalReference;
20
- type FileReference = {
21
- type: `absolute`;
22
- url: URL;
23
- } | {
24
- type: `relative`;
25
- path: string;
26
- };
10
+ type Logger = Partial<Record<Exclude<LogLevel, `none`>, (message: string) => void>>;
27
11
  /**
28
- * A named class, module, namespace, assembly, or native library (e.g.
29
- * `java.util.HashMap`).
12
+ * The verbosity of a conversion's diagnostics, from `none` (the default) to
13
+ * `debug`. A level enables its own messages and every level before it.
30
14
  */
31
- type LogicalReference = {
32
- type: `logical`;
33
- name: string;
34
- };
35
- type SourceLocationInput = ({
36
- type: `file`;
37
- /** A string parseable into a {@link URL} or file path. */
38
- urlOrPath: string;
39
- } | {
40
- type: `logical`;
41
- /**
42
- * The name of a class, module, namespace, assembly, or native library.
43
- */
44
- name: string;
45
- }) & {
46
- /** The 1-based line number in the referenced source. */
47
- line?: number;
48
- /** The 1-based column number in the referenced source. */
49
- column?: number;
50
- };
51
- //#endregion
52
- //#region src/modalities/metric.d.ts
53
- /** Phrases that can be used in prose related to a metric. */
54
- type MetricPhrases = {
55
- /** A noun to use in headings, like "CPU", "heap", etc. */
56
- titleNoun: string;
57
- /** A noun to use in columns like "time", "size", etc. */
58
- columnNoun: string;
59
- /** A verb to use in prose like "took", "allocated", etc. */
60
- pastTenseVerb: string;
61
- /** A verb phrase to use in prose like "time spent", "bytes allocated", etc. */
62
- pastParticipleVerbPhrase: string;
63
- };
15
+ type LogLevel = (typeof LOG_LEVELS)[number];
16
+ /** Every {@link LogLevel}, least to most verbose. */
17
+ declare const LOG_LEVELS: readonly ["none", "error", "warn", "info", "debug"];
64
18
  /**
65
- * Which direction of change in a metric's value is an improvement.
19
+ * The category of code a function originated from.
66
20
  *
67
- * A profiler records what a program consumed, so a smaller value is a better
68
- * one for every unit this package recognizes. `increase` is for a metric
69
- * measuring something a program produces, and `unknown` for a metric whose
70
- * emitter named a unit this package cannot classify, where a diff states the
71
- * direction of each change and calls neither better or worse.
21
+ * A closed set, so a category names the same thing whichever origin wrote the
22
+ * input and formatting can partition by it. The first three record where the
23
+ * code came from, the next two what the profiler could determine about a frame
24
+ * with no source file, and the rest name a runtime activity.
25
+ *
26
+ * These boundaries decide most assignments:
27
+ *
28
+ * - `stdlib` requires positive evidence that the code is the language's or
29
+ * runtime's own library: a standard-library path, module specifier,
30
+ * namespace, or package prefix. A missing source file is never evidence for
31
+ * `stdlib`
32
+ * - `native` is compiled code the profiler attributed to no source file, plus
33
+ * code located in a shared library or in a runtime's own C/C++ sources.
34
+ * `unknown` is a frame the profiler could not identify, a weaker claim,
35
+ * because the code may be a function in the profiled language
36
+ * - `compiler` is the runtime producing executable code, and `jit` is a frame
37
+ * executing code the runtime generated. Where a frame both executes generated
38
+ * code and does the work of a named activity, the activity takes precedence,
39
+ * so a garbage collection write barrier compiled inline is
40
+ * `garbage-collector`
72
41
  */
73
- type MetricImprovement = `decrease` | `increase` | `unknown`;
74
- /** A metric measured in a profile. */
42
+ type FunctionCategory = (typeof FUNCTION_CATEGORIES)[number];
43
+ declare const FUNCTION_CATEGORIES: readonly ["ours", "third-party", "stdlib", "native", "unknown", "garbage-collector", "compiler", "jit", "regexp", "kernel", "idle"];
44
+ /**
45
+ * Records why a parse used only part of its input, so the pipeline warns about
46
+ * the partial result, or rejects an input that produced no records.
47
+ */
48
+ type RecordTally = {
49
+ /**
50
+ * Records that the parser skipped `count` records of `unit` (e.g. `sample`)
51
+ * for `reason`, a participle phrase (e.g. `referencing a missing node`). A
52
+ * `count` of `0` records nothing.
53
+ */
54
+ skipped: (unit: string, reason: string, count?: number) => void;
55
+ /**
56
+ * Records that the input ends before `missing` (e.g.
57
+ * `the end-of-data marker`), which a complete input contains.
58
+ */
59
+ endsBefore: (missing: string) => void;
60
+ };
75
61
  type Metric = ({
76
62
  type: `time`;
77
63
  /** The number of milliseconds this time unit takes up. */
@@ -95,47 +81,79 @@ type Metric = ({
95
81
  proseUnit: string;
96
82
  }) & {
97
83
  phrases: MetricPhrases;
98
- /** Which direction of change in this metric's value is an improvement. */
99
84
  improvement: MetricImprovement;
100
85
  };
101
- //#endregion
102
- //#region src/modalities/stack-frame.d.ts
103
86
  /**
104
- * A function occurrence at an executing position.
87
+ * Which direction of change in a metric's value is an improvement.
105
88
  *
106
- * Its {@link name} and {@link location} (the function's *definition* location)
107
- * identify the function; frames sharing them are the same function.
89
+ * A profiler records what a program consumed, so a smaller value is a better
90
+ * one for every unit this package recognizes. `increase` is for a metric
91
+ * measuring something a program produces, and `unknown` for a metric whose
92
+ * profiler named a unit this package cannot classify, where a diff states the
93
+ * direction of each change and calls neither better nor worse.
94
+ */
95
+ type MetricImprovement = `decrease` | `increase` | `unknown`;
96
+ type MetricPhrases = {
97
+ /** A noun to use in headings, like "CPU", "heap", etc. */
98
+ titleNoun: string;
99
+ /** A noun to use in columns like "time", "size", etc. */
100
+ columnNoun: string;
101
+ /** A verb to use in prose like "took", "allocated", etc. */
102
+ pastTenseVerb: string;
103
+ /** A verb phrase to use in prose like "time spent", "bytes allocated", etc. */
104
+ pastParticipleVerbPhrase: string;
105
+ };
106
+ /**
107
+ * A frame record: a parser's record of one function reference, with each
108
+ * position the profiler recorded stored under its semantic.
108
109
  *
109
- * {@link line} is the *executing* line and is used for the per-line breakdown,
110
- * not identity.
110
+ * Its {@link name} and {@link definition} identify the function, so frame
111
+ * records sharing them are the same function. {@link executing} is never part
112
+ * of the identity, and the leaf frame's executing line feeds its function's
113
+ * per-line breakdown.
111
114
  *
112
- * A converter produces these raw; the resolved origin's `normalizeStackFrame` then
113
- * splits out the location and line for variants that pack them into the frame
114
- * string.
115
+ * A parser fills each slot from what the profiler records there, per the
116
+ * profiler's own source or spec, and leaves a slot the profiler doesn't record
117
+ * empty. It NEVER infers one position from another. The resolved origin's
118
+ * `normalizeStackFrame` then splits out the source and positions for variants
119
+ * that pack them into the frame string. It also moves a position that a
120
+ * profiler records under a different semantic into its slot.
115
121
  */
116
122
  type StackFrame = {
117
- /** The function's name, if known. */
118
123
  name?: string;
119
- /** Where the function was defined, if known. */
120
- location?: SourceLocationInput;
121
124
  /**
122
- * The 1-based line where this frame was sampled, if known.
125
+ * Where the function is defined, if known: the source it is in and, when
126
+ * the profiler records it, the position within that source.
123
127
  *
124
- * Distinct from {@link location}'s line (the definition line): this is the
125
- * executing line, which the aggregator forwards to the leaf function's
126
- * per-line breakdown. Never a function-identity component.
128
+ * The position is inside the definition because it is a position within
129
+ * that source, so it can't exist without one.
127
130
  */
128
- line?: number;
131
+ definition?: UnresolvedSourceReference & {
132
+ position?: SourcePosition;
133
+ };
134
+ /**
135
+ * The position this frame was at when recorded, if known.
136
+ *
137
+ * It is meaningful without a {@link definition}, because the line is still a
138
+ * line of the function.
139
+ */
140
+ executing?: SourcePosition;
141
+ /**
142
+ * Where this function was called: a position in the caller's source, if the
143
+ * profiler recorded it.
144
+ *
145
+ * Identifies and locates the function only under an origin declaring
146
+ * `call-site` identity (`OriginSpec.functionIdentity`), for a profiler that
147
+ * records no other position.
148
+ */
149
+ callSite?: UnresolvedSourceReference & {
150
+ position: SourcePosition;
151
+ };
129
152
  };
130
- //#endregion
131
- //#region src/modalities/call-graph/type.d.ts
132
153
  /**
133
154
  * An input parsed as a weighted call graph: functions with recorded self costs
134
- * plus caller→callee arcs with recorded call counts and inclusive costs. The
155
+ * plus caller→callee arcs with recorded call counts and total costs. The
135
156
  * formats it comes from record no call stacks.
136
- *
137
- * Origin detection, frame normalization, and aggregation run uniformly from
138
- * here, so a format's only custom logic is parsing into this.
139
157
  */
140
158
  type CallGraph = {
141
159
  type: `call-graph`;
@@ -147,41 +165,36 @@ type CallGraph = {
147
165
  */
148
166
  metrics: Metric[];
149
167
  /**
150
- * Each function node's frame (name and definition location), index-aligned
151
- * with {@link CallGraph.functions}. The aggregator normalizes the frames
152
- * through the origin pipeline like a sampling profile's, and merges
153
- * functions whose normalized frames share an identity.
168
+ * Each function's frame record (name and definition location),
169
+ * index-aligned with {@link CallGraph.functions}. The aggregator merges
170
+ * functions whose normalized frame records share an identity.
154
171
  */
155
172
  frames: StackFrame[];
156
- /** The graph's function nodes, indexed by {@link CallGraphCall.callee}. */
173
+ /** The graph's functions, indexed by {@link CallGraphArc.callee}. */
157
174
  functions: CallGraphFunction[];
158
175
  };
159
- /** A function node in a parsed call graph. */
160
176
  type CallGraphFunction = {
161
177
  /** The cost recorded directly in the function's body, per metric. */
162
178
  selfValues: number[];
163
179
  /** Each 1-based line to the self cost recorded at that line, per metric. */
164
180
  lineToValues: Map<number, number[]>;
165
- /** The function's outgoing calls. */
166
- calls: CallGraphCall[];
181
+ arcs: CallGraphArc[];
167
182
  };
168
- /** One caller→callee arc: the recorded call count and inclusive cost. */
169
- type CallGraphCall = {
183
+ /** One caller→callee arc: the recorded call count and total cost. */
184
+ type CallGraphArc = {
170
185
  /** The called function's index in {@link CallGraph.functions}. */
171
186
  callee: number;
172
187
  /** The recorded number of calls, or `0` when the format records none. */
173
188
  callCount: number;
174
189
  /**
175
- * The calls' inclusive cost per metric: cost recorded in the callee and its
190
+ * The calls' total cost per metric: cost recorded in the callee and its
176
191
  * callees during these calls.
177
192
  */
178
193
  totalValues: number[];
179
194
  };
180
- //#endregion
181
- //#region src/modalities/call-stack-profile/type.d.ts
182
195
  /**
183
- * A profile parsed into the uniform structure containing the distinct frames
184
- * and the observations that reference them.
196
+ * A profile parsed into the uniform structure containing the distinct frame
197
+ * records and the observations that reference them.
185
198
  *
186
199
  * A format that yields several profiles returns one of these per profile,
187
200
  * typically sharing the same {@link CallStackProfile.frames} array reference.
@@ -189,17 +202,17 @@ type CallGraphCall = {
189
202
  type CallStackProfile = {
190
203
  type: `call-stack-profile`;
191
204
  /**
192
- * The ID of the origin the format's own metadata points to (e.g. a
193
- * recorder's event-type definitions or a writer's self-identification
194
- * field), set by a parser when such evidence exists.
205
+ * The name the format's own metadata gives the writer (e.g. a recorder's
206
+ * event-type definitions or a writer's self-identification field), set by a
207
+ * parser when that metadata identifies one. It is an origin's ID or a name
208
+ * the origin's {@link OriginSpec.isOriginHint} accepts.
195
209
  *
196
- * A hint, not a decision: detection treats it like a marker entry of that
197
- * origin, so a forced origin ignores it and a higher-priority origin's
198
- * marker entry overrides it.
210
+ * Detection resolves to the origin it names over any marker entry, because the
211
+ * metadata is the writer identifying itself. A specified origin ignores it.
199
212
  */
200
213
  originHint?: string;
201
214
  /**
202
- * The distinct frames the observations reference.
215
+ * The distinct frame records the observations reference.
203
216
  *
204
217
  * A {@link Observation.frameIndices} entry is an index into this list.
205
218
  */
@@ -224,11 +237,11 @@ type CallStackProfile = {
224
237
  */
225
238
  lineMetrics?: Iterable<ObservationLineMetrics>;
226
239
  };
227
- /** One record of a profile: a call stack, its values, and how many it stands for. */
240
+ /** A call stack, a value per metric, and how many occurrences it stands for. */
228
241
  type Observation = {
229
242
  /**
230
- * An identifier for this record's call stack, if the caller has one (e.g. a
231
- * format that references stacks by a constant-pool index).
243
+ * An identifier for this observation's call stack, if the caller has one
244
+ * (e.g. a format that references call stacks by a constant-pool index).
232
245
  *
233
246
  * When provided, the aggregator memoizes the resolved call stack by this ID.
234
247
  */
@@ -237,21 +250,27 @@ type Observation = {
237
250
  values: number[];
238
251
  /** The call stack as indices into {@link CallStackProfile.frames}. */
239
252
  frameIndices: number[];
240
- /** The 1-based line number the leaf frame was at, if known. */
241
- line?: number;
242
253
  /**
243
- * How many identical occurrences this record stands for, defaulting to `1`.
254
+ * The 1-based line number the leaf frame was at, if known. Overrides the
255
+ * leaf frame's {@link StackFrame.executing} line.
256
+ */
257
+ executingLine?: number;
258
+ /**
259
+ * Whether the profiler dropped the call stack's outermost frames, so its
260
+ * last frame is not where the program's execution started. Set only where
261
+ * the format records it, defaulting to `false`. A root frame the
262
+ * origin recognizes as a truncation marker also sets it.
263
+ */
264
+ truncated?: boolean;
265
+ /**
266
+ * How many identical occurrences this observation stands for, defaulting to
267
+ * `1`.
244
268
  *
245
269
  * {@link CallStackProfile.countMetric} states what one of them is.
246
270
  */
247
271
  count?: number;
248
272
  };
249
- /**
250
- * Per-line metrics for one frame, added after the observations.
251
- *
252
- * Used by formats that report a function's self time broken down by line
253
- * separately from its observations.
254
- */
273
+ /** Per-line metrics for one frame. */
255
274
  type ObservationLineMetrics = {
256
275
  /** The frame's index into {@link CallStackProfile.frames}. */
257
276
  frame: number;
@@ -262,8 +281,6 @@ type ObservationLineMetrics = {
262
281
  values: number[];
263
282
  }[];
264
283
  };
265
- //#endregion
266
- //#region src/modalities/heap-snapshot/graph.d.ts
267
284
  /**
268
285
  * A successor and predecessor graph between heap snapshot nodes in CSR format.
269
286
  *
@@ -271,67 +288,34 @@ type ObservationLineMetrics = {
271
288
  */
272
289
  type NodeAdjacencyGraph = {
273
290
  /**
274
- * Start offset into
275
- * {@link NodeAdjacencyGraph.offsetToSuccessorOrdinal} and
276
- * {@link NodeAdjacencyGraph.offsetToSuccessorEdgeIndex} for each
277
- * node's successors in the graph.
278
- *
279
- * Node `i`'s successor ordinals occupy:
280
- * `[offsetToSuccessorOrdinal[i], offsetToSuccessorOrdinal[i + 1])`.
281
- *
282
- * Node `i`'s successor edges occupy:
283
- * `[offsetToSuccessorEdgeIndex[i], offsetToSuccessorEdgeIndex[i + 1])`.
291
+ * Node `i`'s successors occupy
292
+ * `[ordinalToSuccessorStartOffset[i], ordinalToSuccessorStartOffset[i + 1])`
293
+ * in {@link NodeAdjacencyGraph.offsetToSuccessorOrdinal} and
294
+ * {@link NodeAdjacencyGraph.offsetToSuccessorEdgeIndex}.
284
295
  */
285
296
  ordinalToSuccessorStartOffset: Int32Array;
286
- /**
287
- * Successor ordinals, packed contiguously and indexed via
288
- * {@link NodeAdjacencyGraph.ordinalToSuccessorStartOffset}.
289
- */
290
297
  offsetToSuccessorOrdinal: Int32Array;
291
- /**
292
- * Successor edge indices, packed contiguously and indexed via
293
- * {@link NodeAdjacencyGraph.ordinalToSuccessorStartOffset}.
294
- */
295
298
  offsetToSuccessorEdgeIndex: Int32Array;
296
299
  /**
297
- * Start offset into
298
- * {@link NodeAdjacencyGraph.offsetToPredecessorOrdinal} and
299
- * {@link NodeAdjacencyGraph.offsetToPredecessorEdgeIndex} for each
300
- * node's predecessors in the graph.
301
- *
302
- * Node `i`'s predecessor ordinals occupy:
303
- * `[offsetToPredecessorOrdinal[i], offsetToPredecessorOrdinal[i + 1])`.
304
- *
305
- * Node `i`'s predecessor edges occupy:
306
- * `[offsetToPredecessorEdgeIndex[i], offsetToPredecessorEdgeIndex[i + 1])`.
300
+ * Node `i`'s predecessors occupy
301
+ * `[ordinalToPredecessorStartOffset[i], ordinalToPredecessorStartOffset[i + 1])`
302
+ * in {@link NodeAdjacencyGraph.offsetToPredecessorOrdinal} and
303
+ * {@link NodeAdjacencyGraph.offsetToPredecessorEdgeIndex}.
307
304
  */
308
305
  ordinalToPredecessorStartOffset: Int32Array;
309
- /**
310
- * Predecessor ordinals, packed contiguously and indexed via
311
- * {@link NodeAdjacencyGraph.ordinalToPredecessorStartOffset}.
312
- */
313
306
  offsetToPredecessorOrdinal: Int32Array;
314
- /**
315
- * Predecessor edge indices, packed contiguously and indexed via
316
- * {@link NodeAdjacencyGraph.ordinalToPredecessorStartOffset}.
317
- */
318
307
  offsetToPredecessorEdgeIndex: Int32Array;
319
308
  };
320
- //#endregion
321
- //#region src/modalities/heap-snapshot/type.d.ts
322
309
  /**
323
- * A heap snapshot parsed into the uniform structure containing the node
324
- * adjacency graph and each node's unresolved category.
310
+ * A parsed heap snapshot.
325
311
  *
326
312
  * A format that yields several snapshots returns one of these per snapshot.
327
313
  */
328
314
  type HeapSnapshot = {
329
315
  type: `heap-snapshot`;
330
- /** Number of nodes in the snapshot. */
331
316
  nodeCount: number;
332
- /** Number of edges between nodes in the snapshot. */
317
+ /** The edges pointing at a node of the snapshot, retaining it or not. */
333
318
  edgeCount: number;
334
- /** The successor and predecessor graph between the snapshot's nodes. */
335
319
  nodeAdjacencyGraph: NodeAdjacencyGraph;
336
320
  /** Bytes allocated directly for the node. */
337
321
  selfSizeOf: (nodeOrdinal: number) => number;
@@ -341,15 +325,12 @@ type HeapSnapshot = {
341
325
  */
342
326
  nodes: Iterable<HeapSnapshotNode>;
343
327
  /**
344
- * Formats an edge label, which is computed lazily at formatting time, so it
345
- * receives the resolved formatting options.
346
- */
347
- formatEdgeLabel: (retainerOrdinal: number, edgeIndex: number, options: FormattingProfileToMdOptions) => string;
348
- /**
349
- * Formats a node label, which is computed lazily at formatting time, so it
350
- * receives the resolved formatting options.
328
+ * How the node at {@link retainerOrdinal} refers to another through the edge
329
+ * at {@link edgeIndex}, whose meaning is the format's own.
351
330
  */
352
- formatNodeLabel: (nodeOrdinal: number, options: FormattingProfileToMdOptions) => string;
331
+ retainerEdgeOf: (retainerOrdinal: number, edgeIndex: number) => RetainerEdge;
332
+ /** The node as a retainer path step or a retained node listing shows it. */
333
+ retainerOf: (nodeOrdinal: number) => RetainerNode;
353
334
  /** Whether the node is a bookkeeping node that never points to user code. */
354
335
  isInternalNode: (nodeOrdinal: number) => boolean;
355
336
  /**
@@ -360,21 +341,28 @@ type HeapSnapshot = {
360
341
  unresolvedCategoryOf: (nodeOrdinal: number) => UnresolvedHeapSnapshotNodeCategory;
361
342
  };
362
343
  /**
363
- * What a heap snapshot node holds.
364
- *
365
- * A closed set, so a category names the same thing whichever engine wrote the
366
- * snapshot and formatting can partition by it. V8 declares its own names for
367
- * most of these in `meta.node_types`. JavaScriptCore derives them from a node's
368
- * flags. Where an engine's name is its own, the category takes the name every
369
- * language shares: `internal` covers V8's `hidden` and JavaScriptCore's
370
- * `internal`, `function` covers V8's `closure` whether or not the function
371
- * captures anything, and `big-number` covers V8's `bigint` along with any
372
- * arbitrary-precision number a runtime allocates on the heap, such as Julia's
373
- * `BigFloat`.
344
+ * Every node contributes to its category's stats. A node with a `type` also
345
+ * aggregates into that type's entities.
374
346
  */
375
- type HeapSnapshotNodeCategory = (typeof HEAP_SNAPSHOT_NODE_CATEGORIES)[number];
376
- /** Every category {@link HeapSnapshotNodeCategory} allows. */
377
- declare const HEAP_SNAPSHOT_NODE_CATEGORIES: readonly ["object", "array", "string", "concatenated-string", "sliced-string", "function", "code", "regexp", "number", "big-number", "symbol", "native", "object-shape", "internal", "synthetic", "unknown"];
347
+ type HeapSnapshotNode = UnresolvedHeapSnapshotNodeCategory & ({
348
+ type?: undefined;
349
+ } | {
350
+ type: `constructor`;
351
+ name: string;
352
+ location?: SourceLocation;
353
+ /**
354
+ * The file reference the {@link name} parses as, when it is URL-shaped.
355
+ */
356
+ nameLocation?: FileReference;
357
+ } | {
358
+ type: `function`;
359
+ name: string;
360
+ location?: SourceLocation;
361
+ } | {
362
+ type: `string`;
363
+ /** The (truncated) string value, if known. */
364
+ name?: string;
365
+ });
378
366
  /**
379
367
  * What a heap snapshot node holds, as the format categorized it, before the
380
368
  * origin resolves it.
@@ -390,212 +378,356 @@ type UnresolvedHeapSnapshotNodeCategory = {
390
378
  declaredType?: string;
391
379
  };
392
380
  /**
393
- * A heap snapshot node.
381
+ * What a heap snapshot node holds.
394
382
  *
395
- * Every node contributes to its category's stats. A node with a `type` also
396
- * aggregates into that type's entities.
383
+ * A closed set, so a category names the same thing whichever engine wrote the
384
+ * snapshot and formatting can partition by it. V8 declares its own names for
385
+ * most of these in `meta.node_types`. JavaScriptCore derives them from a node's
386
+ * flags. Where an engine's name is its own, the category takes the name every
387
+ * language shares: `internal` covers V8's `hidden` and JavaScriptCore's
388
+ * `internal`, `function` covers V8's `closure` whether or not the function
389
+ * captures anything, and `big-number` covers V8's `bigint` along with any
390
+ * arbitrary-precision number a runtime allocates on the heap, such as Julia's
391
+ * `BigFloat`.
397
392
  */
398
- type HeapSnapshotNode = UnresolvedHeapSnapshotNodeCategory & ({
399
- type?: undefined;
393
+ type HeapSnapshotNodeCategory = (typeof HEAP_SNAPSHOT_NODE_CATEGORIES)[number];
394
+ declare const HEAP_SNAPSHOT_NODE_CATEGORIES: readonly ["object", "array", "string", "concatenated-string", "sliced-string", "function", "code", "regexp", "number", "big-number", "symbol", "native", "object-shape", "internal", "synthetic", "unknown"];
395
+ /** How a retainer refers to the node it retains. */
396
+ type RetainerEdge = {
397
+ type: `property`;
398
+ name: string;
399
+ /** The file reference the {@link name} parses as, when it is URL-shaped. */
400
+ nameLocation?: FileReference;
400
401
  } | {
401
- type: `constructor`;
402
- /** A human readable label for this constructor. */
402
+ type: `element`;
403
+ /** Undefined when the format records an index no array can have. */
404
+ index: number | undefined;
405
+ } | {
406
+ /** An edge the format labels as neither a property nor an element. */
407
+ type: `labeled`;
408
+ label: string;
409
+ } | {
410
+ type: `unlabeled`;
411
+ };
412
+ type RetainerNode = {
413
+ /** The retainer's node ordinal. */
414
+ id: number;
403
415
  name: string;
404
- /** The exact location where the node was defined. */
416
+ /** The file reference the {@link name} parses as, when it is URL-shaped. */
417
+ nameLocation?: FileReference;
405
418
  location?: SourceLocation;
419
+ };
420
+ /**
421
+ * An input parsed as a trace: a chronological record of events, each a span
422
+ * with a duration or an instant with none, and of gauge readings.
423
+ *
424
+ * A format that yields several traces returns one of these per trace.
425
+ */
426
+ type Trace = {
427
+ type: `trace`;
428
+ /** @see {@link CallStackProfile.originHint} */
429
+ originHint?: string;
406
430
  /**
407
- * The file reference the {@link name} parses as, when it is URL-shaped.
431
+ * How many milliseconds one unit of every start, time, duration, and CPU
432
+ * duration below takes up.
408
433
  */
409
- nameLocation?: FileReference;
410
- } | {
411
- type: `function`;
412
- /** A human readable label for this function. */
434
+ millisecondsPerTimeUnit: number;
435
+ /** The threads the events reference by index. */
436
+ threads: TraceThread[];
437
+ /**
438
+ * The events and readings as a lazily consumed iterable. A span follows the
439
+ * span it is nested in, at the position its {@link TraceSpan.parent} states,
440
+ * and precedes every later span outside that one.
441
+ */
442
+ events: Iterable<TraceEvent | TraceReading>;
443
+ };
444
+ /**
445
+ * A thread events were recorded on, named as the Markdown shows it. The name
446
+ * includes the thread's process where the trace records several processes.
447
+ */
448
+ type TraceThread = {
413
449
  name: string;
414
- /** The exact location where the function was defined. */
415
- location?: SourceLocation;
416
- } | {
417
- type: `string`;
418
- /** The (truncated) string value, if known. */
419
- name?: string;
420
- });
421
- //#endregion
422
- //#region src/formats/registry.d.ts
423
- /** Every supported format's converter, keyed by format ID. */
424
- declare const formatConverters: {
425
- readonly callgrind: {
426
- readonly title: "Callgrind";
427
- readonly extension: "callgrind";
428
- readonly languages: readonly ["c", "ruby"];
429
- readonly fallbackOrigin: "valgrind";
430
- readonly type: "binary";
431
- readonly matches: (bytes: Uint8Array) => boolean;
432
- readonly parse: (bytes: Uint8Array) => CallGraph[];
433
- readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallGraph[]>;
434
- };
435
- readonly collapsed: {
436
- readonly title: "Collapsed stacks";
437
- readonly extension: "collapsed";
438
- readonly languages: readonly ["elixir", "java", "php", "python", "ruby"];
439
- readonly fallbackOrigin: "unknown";
440
- readonly type: "binary";
441
- readonly matches: (bytes: Uint8Array) => boolean;
442
- readonly parse: (bytes: Uint8Array) => CallStackProfile[];
443
- readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallStackProfile[]>;
444
- };
445
- readonly 'ghc-eventlog': {
446
- readonly title: "GHC eventlog";
447
- readonly extension: "eventlog";
448
- readonly languages: readonly ["haskell"];
449
- readonly fallbackOrigin: "ghc";
450
- readonly type: "binary";
451
- readonly matches: (bytes: Uint8Array) => boolean;
452
- readonly parse: (bytes: Uint8Array) => CallStackProfile[];
453
- readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallStackProfile[]>;
454
- };
455
- readonly 'ghc-json-profile': {
456
- readonly title: "GHC JSON profile";
457
- readonly extension: "prof.json";
458
- readonly languages: readonly ["haskell"];
459
- readonly fallbackOrigin: "ghc";
460
- readonly type: "json";
461
- readonly matches: (json: unknown) => boolean;
462
- readonly parse: (json: unknown) => CallStackProfile[];
463
- };
464
- readonly hprof: {
465
- readonly title: "HPROF";
466
- readonly extension: "hprof";
467
- readonly languages: readonly ["java"];
468
- readonly fallbackOrigin: "jdk";
469
- readonly type: "binary";
470
- readonly matches: (bytes: Uint8Array) => boolean;
471
- readonly parse: (bytes: Uint8Array) => HeapSnapshot[];
472
- readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<HeapSnapshot[]>;
473
- };
474
- readonly jfr: {
475
- readonly title: "JFR";
476
- readonly extension: "jfr";
477
- readonly languages: readonly ["java"];
478
- readonly fallbackOrigin: "jdk";
479
- readonly type: "binary";
480
- readonly matches: (bytes: Uint8Array) => boolean;
481
- readonly parse: (bytes: Uint8Array) => CallStackProfile[];
482
- readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallStackProfile[]>;
483
- };
484
- readonly 'jsc-heap-snapshot': {
485
- readonly title: "JSC heap snapshot";
486
- readonly extension: "jsc-heap-snapshot.json";
487
- readonly languages: readonly ["javascript"];
488
- readonly fallbackOrigin: "safari";
489
- readonly type: "json";
490
- readonly matches: (json: unknown) => boolean;
491
- readonly parse: (json: unknown) => HeapSnapshot[];
492
- };
493
- readonly memray: {
494
- readonly title: "memray";
495
- readonly extension: "memray.bin";
496
- readonly languages: readonly ["python"];
497
- readonly fallbackOrigin: "memray";
498
- readonly type: "binary";
499
- readonly matches: (bytes: Uint8Array) => boolean;
500
- readonly parse: (input: Uint8Array) => CallStackProfile[];
501
- readonly parseAsync: (stream: ReadableStream<Uint8Array<ArrayBufferLike>>) => Promise<CallStackProfile[]>;
502
- };
503
- readonly perf: {
504
- readonly title: "perf.data";
505
- readonly extension: "perf.data";
506
- readonly languages: readonly ["c", "zig"];
507
- readonly fallbackOrigin: "perf";
508
- readonly type: "binary";
509
- readonly matches: (bytes: Uint8Array) => boolean;
510
- readonly parse: (bytes: Uint8Array) => CallStackProfile[];
511
- readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallStackProfile[]>;
512
- };
513
- readonly pprof: {
514
- readonly title: "pprof";
515
- readonly extension: "pprof";
516
- readonly languages: readonly ["c", "fortran", "go", "javascript", "julia", "ruby", "rust", "swift", "zig"];
517
- readonly fallbackOrigin: "unknown";
518
- readonly type: "binary";
519
- readonly matches: (bytes: Uint8Array) => boolean;
520
- readonly parse: (bytes: Uint8Array<ArrayBufferLike>) => CallStackProfile[];
521
- readonly parseAsync: (stream: ReadableStream<Uint8Array<ArrayBufferLike>>) => Promise<CallStackProfile[]>;
522
- };
523
- readonly speedscope: {
524
- readonly title: "Speedscope";
525
- readonly extension: "speedscope.json";
526
- readonly languages: readonly ["csharp", "php", "python", "ruby"];
527
- readonly fallbackOrigin: "unknown";
528
- readonly type: "json";
529
- readonly matches: (json: unknown) => boolean;
530
- readonly parse: (json: unknown) => CallStackProfile[];
531
- };
532
- readonly systing: {
533
- readonly title: "systing";
534
- readonly extension: "systing";
535
- readonly languages: readonly ["c", "python", "rust"];
536
- readonly fallbackOrigin: "systing";
537
- readonly type: "binary";
538
- readonly matches: (bytes: Uint8Array) => boolean;
539
- readonly parse: (bytes: Uint8Array) => CallStackProfile[];
540
- readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallStackProfile[]>;
541
- };
542
- readonly 'v8-cpu-profile': {
543
- readonly title: "V8 CPU profile";
544
- readonly extension: "cpuprofile";
545
- readonly languages: readonly ["javascript"];
546
- readonly fallbackOrigin: "chrome";
547
- readonly type: "json";
548
- readonly matches: (json: unknown) => boolean;
549
- readonly parse: (json: unknown) => CallStackProfile[];
550
- };
551
- readonly 'v8-heap-profile': {
552
- readonly title: "V8 heap profile";
553
- readonly extension: "heapprofile";
554
- readonly languages: readonly ["javascript"];
555
- readonly fallbackOrigin: "chrome";
556
- readonly type: "json";
557
- readonly matches: (json: unknown) => boolean;
558
- readonly parse: (json: unknown) => CallStackProfile[];
559
- };
560
- readonly 'v8-heap-snapshot': {
561
- readonly title: "V8 heap snapshot";
562
- readonly extension: "heapsnapshot";
563
- readonly languages: readonly ["javascript", "julia"];
564
- readonly fallbackOrigin: "chrome";
565
- readonly type: "json";
566
- readonly matches: (json: unknown) => boolean;
567
- readonly parse: (json: unknown) => HeapSnapshot[];
568
- };
569
- readonly 'webkit-timeline-recording': {
570
- readonly title: "WebKit timeline recording";
571
- readonly extension: "webkit-timeline-recording.json";
572
- readonly languages: readonly ["javascript"];
573
- readonly fallbackOrigin: "safari";
574
- readonly type: "json";
575
- readonly matches: (json: unknown) => boolean;
576
- readonly parse: (json: unknown) => CallStackProfile[];
577
- };
578
450
  };
579
- /** Supported profile format IDs. */
580
- type Format = keyof typeof formatConverters;
581
- //#endregion
582
- //#region src/origins/specs/index.d.ts
451
+ type TraceEvent = TraceSpan | TraceInstant;
452
+ type TraceEventFields = {
453
+ name: string;
454
+ /**
455
+ * The event's category, when the parser or a shared event constructor
456
+ * determines it. The origin categorizes an event that has none.
457
+ */
458
+ category?: TraceEventCategory;
459
+ /**
460
+ * The category names the format records for the event, which the origin
461
+ * maps to a category.
462
+ */
463
+ declaredCategories?: readonly string[];
464
+ /** The index in {@link Trace.threads} of the thread the event was on. */
465
+ thread?: number;
466
+ /** The attributes the parser or the origin determines. */
467
+ attributes?: readonly TraceAttribute[];
468
+ /**
469
+ * The event's arguments as the format records them. The origin's
470
+ * `normalizeTraceEvent` turns an argument into an attribute or a reading and
471
+ * removes it. Each one left that holds a string is an attribute.
472
+ */
473
+ arguments?: Readonly<Record<string, unknown>>;
474
+ };
475
+ /** A named event with a duration. */
476
+ type TraceSpan = TraceEventFields & {
477
+ type: `span`;
478
+ /** Absent when the input orders its events without timing them. */
479
+ start?: number;
480
+ /** Absent for a span the input never ends. */
481
+ duration?: number;
482
+ /** The span's CPU time, when recorded. */
483
+ cpuDuration?: number;
484
+ /**
485
+ * Whether the span is an operation that stays pending while threads do
486
+ * other work, overlapping others of its kind. Its duration is the time that
487
+ * elapsed, which no thread spent on it alone, so it has no self time and adds
488
+ * to no category's time.
489
+ */
490
+ async?: boolean;
491
+ /**
492
+ * The position in {@link Trace.events} of the span this one is nested in.
493
+ * Set only from nesting the input states, or from containment within one
494
+ * thread where the format's spans nest by construction.
495
+ */
496
+ parent?: number;
497
+ };
498
+ /** A named event at a moment, with no duration. */
499
+ type TraceInstant = TraceEventFields & {
500
+ type: `instant`;
501
+ /** Absent when the input orders its events without timing them. */
502
+ time?: number;
503
+ };
504
+ /** One recorded value of a gauge, a named quantity whose level varies. */
505
+ type TraceReading = {
506
+ type: `reading`;
507
+ /**
508
+ * Readings sharing a name, and a {@link thread} where they state one, are
509
+ * one gauge.
510
+ */
511
+ gauge: string;
512
+ /** What the gauge measures, the same for every reading of one gauge. */
513
+ metric: Metric;
514
+ /**
515
+ * The index in {@link Trace.threads} of the thread the gauge is a quantity
516
+ * of, where each thread has its own (e.g. a heap). Readings sharing a name
517
+ * on two threads are two gauges.
518
+ */
519
+ thread?: number;
520
+ /** Absent when the input orders its readings without timing them. */
521
+ time?: number;
522
+ value: number;
523
+ };
524
+ type TraceEventWithReadings = {
525
+ event: TraceEvent;
526
+ readings: readonly TraceReading[];
527
+ };
583
528
  /**
584
- * All origin specs in global detection-priority order.
529
+ * A key and a value on an event: a string, or an amount of something the event
530
+ * consumed or produced, which sums across events.
585
531
  *
586
- * Within a format, the detector tries candidates in this order, so origins that
587
- * share a format and whose marker entries overlap must be ordered carefully
588
- * (e.g. Deno before Node, since Deno supports `node:` specifiers). A parser
589
- * origin hint loses to a marker entry of a higher-priority origin, so a
590
- * markerless origin detected by a hint must also precede the origins whose
591
- * markers it should outrank.
532
+ * A level, which does not sum, is a gauge's {@link TraceReading} instead.
592
533
  */
593
- declare const originSpecs: ({
594
- readonly id: "deno";
595
- readonly title: "Deno";
596
- readonly formats: ["v8-cpu-profile"];
597
- readonly isMarkerEntry: ({ location }: {
598
- readonly id: number;
534
+ type TraceAttribute = {
535
+ key: string;
536
+ value: string | TraceAmount;
537
+ };
538
+ type TraceAmount = {
539
+ amount: number;
540
+ metric: Metric;
541
+ };
542
+ /**
543
+ * The activity a trace event records.
544
+ *
545
+ * A closed set, so a category means the same activity whichever origin wrote
546
+ * the input and formatting can partition by it.
547
+ *
548
+ * `garbage-collection-pause` is a span during which the collector stopped the
549
+ * program, and `garbage-collection` is collector work that ran beside it, so
550
+ * the first one's share of a trace is the share of the run spent paused.
551
+ */
552
+ type TraceEventCategory = (typeof TRACE_EVENT_CATEGORIES)[number];
553
+ declare const TRACE_EVENT_CATEGORIES: readonly ["script", "parsing", "compilation", "garbage-collection-pause", "garbage-collection", "style", "layout", "paint", "io", "other"];
554
+ /** Every supported format's spec, in canonical order. */
555
+ declare const formatSpecs: readonly [{
556
+ readonly id: "callgrind";
557
+ readonly title: "Callgrind";
558
+ readonly extension: "callgrind";
559
+ readonly languages: readonly ["c", "ruby"];
560
+ readonly fallbackOrigin: "valgrind";
561
+ readonly type: "binary";
562
+ readonly matches: (bytes: Uint8Array) => boolean;
563
+ readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallGraph[];
564
+ readonly parseAsync: (stream: ReadableStream<Uint8Array>, recordTally: RecordTally) => Promise<CallGraph[]>;
565
+ }, {
566
+ readonly id: "collapsed";
567
+ readonly title: "Collapsed stacks";
568
+ readonly extension: "collapsed";
569
+ readonly languages: readonly ["elixir", "java", "nix", "php", "python", "ruby"];
570
+ readonly fallbackOrigin: "unknown";
571
+ readonly type: "binary";
572
+ readonly matches: (bytes: Uint8Array) => boolean;
573
+ readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
574
+ readonly parseAsync: (stream: ReadableStream<Uint8Array>, recordTally: RecordTally) => Promise<CallStackProfile[]>;
575
+ }, {
576
+ readonly id: "ghc-eventlog";
577
+ readonly title: "GHC eventlog";
578
+ readonly extension: "eventlog";
579
+ readonly languages: readonly ["haskell"];
580
+ readonly fallbackOrigin: "ghc";
581
+ readonly type: "binary";
582
+ readonly matches: (bytes: Uint8Array) => boolean;
583
+ readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
584
+ }, {
585
+ readonly id: "ghc-json-profile";
586
+ readonly title: "GHC JSON profile";
587
+ readonly extension: "prof.json";
588
+ readonly languages: readonly ["haskell"];
589
+ readonly fallbackOrigin: "ghc";
590
+ readonly type: "json";
591
+ readonly matches: (json: unknown) => boolean;
592
+ readonly parse: (json: unknown, recordTally: RecordTally) => CallStackProfile[];
593
+ }, {
594
+ readonly id: "hprof";
595
+ readonly title: "HPROF";
596
+ readonly extension: "hprof";
597
+ readonly languages: readonly ["java"];
598
+ readonly fallbackOrigin: "jdk";
599
+ readonly type: "binary";
600
+ readonly matches: (bytes: Uint8Array) => boolean;
601
+ readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => HeapSnapshot[];
602
+ }, {
603
+ readonly id: "jfr";
604
+ readonly title: "JFR";
605
+ readonly extension: "jfr";
606
+ readonly languages: readonly ["java"];
607
+ readonly fallbackOrigin: "jdk";
608
+ readonly type: "binary";
609
+ readonly matches: (bytes: Uint8Array) => boolean;
610
+ readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
611
+ readonly parseAsync: (stream: ReadableStream<Uint8Array>, recordTally: RecordTally) => Promise<CallStackProfile[]>;
612
+ }, {
613
+ readonly id: "jsc-heap-snapshot";
614
+ readonly title: "JSC heap snapshot";
615
+ readonly extension: "jsc-heap-snapshot.json";
616
+ readonly languages: readonly ["javascript"];
617
+ readonly fallbackOrigin: "safari";
618
+ readonly type: "json";
619
+ readonly matches: (json: unknown) => boolean;
620
+ readonly parse: (json: unknown, recordTally: RecordTally) => HeapSnapshot[];
621
+ }, {
622
+ readonly id: "memray";
623
+ readonly title: "memray";
624
+ readonly extension: "memray.bin";
625
+ readonly languages: readonly ["python"];
626
+ readonly fallbackOrigin: "memray";
627
+ readonly type: "binary";
628
+ readonly matches: (bytes: Uint8Array) => boolean;
629
+ readonly parse: (input: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
630
+ readonly parseAsync: (stream: ReadableStream<Uint8Array>, recordTally: RecordTally) => Promise<CallStackProfile[]>;
631
+ }, {
632
+ readonly id: "perf";
633
+ readonly title: "perf.data";
634
+ readonly extension: "perf.data";
635
+ readonly languages: readonly ["c", "zig"];
636
+ readonly fallbackOrigin: "perf";
637
+ readonly type: "binary";
638
+ readonly matches: (bytes: Uint8Array) => boolean;
639
+ readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
640
+ }, {
641
+ readonly id: "pprof";
642
+ readonly title: "pprof";
643
+ readonly extension: "pprof";
644
+ readonly languages: readonly ["c", "fortran", "go", "javascript", "julia", "ruby", "rust", "swift", "zig"];
645
+ readonly fallbackOrigin: "unknown";
646
+ readonly type: "binary";
647
+ readonly matches: (bytes: Uint8Array) => boolean;
648
+ readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
649
+ }, {
650
+ readonly id: "speedscope";
651
+ readonly title: "Speedscope";
652
+ readonly extension: "speedscope.json";
653
+ readonly languages: readonly ["csharp", "php", "python", "ruby"];
654
+ readonly fallbackOrigin: "unknown";
655
+ readonly type: "json";
656
+ readonly matches: (json: unknown) => boolean;
657
+ readonly parse: (json: unknown, recordTally: RecordTally) => CallStackProfile[];
658
+ }, {
659
+ readonly id: "systing";
660
+ readonly title: "systing";
661
+ readonly extension: "systing";
662
+ readonly languages: readonly ["c", "python", "rust"];
663
+ readonly fallbackOrigin: "systing";
664
+ readonly type: "binary";
665
+ readonly matches: (bytes: Uint8Array) => boolean;
666
+ readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
667
+ readonly parseAsync: (stream: ReadableStream<Uint8Array>, recordTally: RecordTally) => Promise<CallStackProfile[]>;
668
+ }, {
669
+ readonly id: "trace-event";
670
+ readonly title: "Trace Event Format";
671
+ readonly extension: "trace-event.json";
672
+ readonly languages: readonly ["c", "javascript"];
673
+ readonly fallbackOrigin: "chrome";
674
+ readonly type: "json";
675
+ readonly matches: (json: unknown) => boolean;
676
+ readonly parse: (json: unknown, recordTally: RecordTally) => Trace[];
677
+ }, {
678
+ readonly id: "v8-cpu-profile";
679
+ readonly title: "V8 CPU profile";
680
+ readonly extension: "cpuprofile";
681
+ readonly languages: readonly ["javascript"];
682
+ readonly fallbackOrigin: "chrome";
683
+ readonly type: "json";
684
+ readonly matches: (json: unknown) => boolean;
685
+ readonly parse: (json: unknown, recordTally: RecordTally) => CallStackProfile[];
686
+ }, {
687
+ readonly id: "v8-heap-profile";
688
+ readonly title: "V8 heap profile";
689
+ readonly extension: "heapprofile";
690
+ readonly languages: readonly ["javascript"];
691
+ readonly fallbackOrigin: "chrome";
692
+ readonly type: "json";
693
+ readonly matches: (json: unknown) => boolean;
694
+ readonly parse: (json: unknown, recordTally: RecordTally) => CallStackProfile[];
695
+ }, {
696
+ readonly id: "v8-heap-snapshot";
697
+ readonly title: "V8 heap snapshot";
698
+ readonly extension: "heapsnapshot";
699
+ readonly languages: readonly ["javascript", "julia"];
700
+ readonly fallbackOrigin: "chrome";
701
+ readonly type: "json";
702
+ readonly matches: (json: unknown) => boolean;
703
+ readonly parse: (json: unknown, recordTally: RecordTally) => HeapSnapshot[];
704
+ }, {
705
+ readonly id: "webkit-timeline-recording";
706
+ readonly title: "WebKit timeline recording";
707
+ readonly extension: "webkit-timeline-recording.json";
708
+ readonly languages: readonly ["javascript"];
709
+ readonly fallbackOrigin: "safari";
710
+ readonly type: "json";
711
+ readonly matches: (json: unknown) => boolean;
712
+ readonly parse: (json: unknown, recordTally: RecordTally) => CallStackProfile[];
713
+ }];
714
+ type RegisteredFormatSpec = (typeof formatSpecs)[number];
715
+ type Format = RegisteredFormatSpec[`id`];
716
+ /** A trace event, alone or with the gauge readings its arguments record. */
717
+ type NormalizedTraceEvent = TraceEvent | TraceEventWithReadings | null;
718
+ /**
719
+ * All origin specs in global detection-priority order.
720
+ *
721
+ * Within a format, the detector tries candidates in this order, so origins that
722
+ * share a format and whose marker entries overlap must be ordered carefully
723
+ * (e.g. Deno before Node, since Deno supports `node:` specifiers). A parser
724
+ * origin hint outranks every marker entry, so the order ranks only markers.
725
+ */
726
+ declare const originSpecs: ({
727
+ readonly id: "deno";
728
+ readonly title: "Deno";
729
+ readonly formats: ["v8-cpu-profile"];
730
+ readonly isMarkerEntry: ({ location }: {
599
731
  readonly name?: string | undefined;
600
732
  readonly location?: {
601
733
  readonly type: `absolute`;
@@ -615,7 +747,6 @@ declare const originSpecs: ({
615
747
  } | undefined;
616
748
  }) => boolean;
617
749
  readonly categorizeEntry: (entry: {
618
- readonly id: number;
619
750
  readonly name?: string | undefined;
620
751
  readonly location?: {
621
752
  readonly type: `absolute`;
@@ -639,7 +770,6 @@ declare const originSpecs: ({
639
770
  readonly title: "Bun";
640
771
  readonly formats: ["v8-cpu-profile", "jsc-heap-snapshot", "v8-heap-snapshot"];
641
772
  readonly isMarkerEntry: ({ name, location }: {
642
- readonly id: number;
643
773
  readonly name?: string | undefined;
644
774
  readonly location?: {
645
775
  readonly type: `absolute`;
@@ -659,7 +789,6 @@ declare const originSpecs: ({
659
789
  } | undefined;
660
790
  }) => boolean;
661
791
  readonly categorizeEntry: (entry: {
662
- readonly id: number;
663
792
  readonly name?: string | undefined;
664
793
  readonly location?: {
665
794
  readonly type: `absolute`;
@@ -678,13 +807,13 @@ declare const originSpecs: ({
678
807
  readonly column?: number | undefined;
679
808
  } | undefined;
680
809
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
681
- readonly categorizeHeapSnapshotConstructor: (name: string) => "string" | "number" | "symbol" | "object" | "function" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "code" | "big-number" | "object-shape" | "internal" | "synthetic" | undefined;
810
+ readonly categorizeHeapSnapshotConstructor: (name: string) => "string" | "number" | "symbol" | "object" | "function" | "code" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "big-number" | "object-shape" | "internal" | "synthetic" | undefined;
811
+ readonly matchHeapSnapshotEdgeName: (name: string) => string | undefined;
682
812
  } | {
683
813
  readonly id: "node";
684
814
  readonly title: "Node.js";
685
- readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile"];
815
+ readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile", "trace-event"];
686
816
  readonly isMarkerEntry: ({ location }: {
687
- readonly id: number;
688
817
  readonly name?: string | undefined;
689
818
  readonly location?: {
690
819
  readonly type: `absolute`;
@@ -704,7 +833,6 @@ declare const originSpecs: ({
704
833
  } | undefined;
705
834
  }) => boolean;
706
835
  readonly categorizeEntry: (entry: {
707
- readonly id: number;
708
836
  readonly name?: string | undefined;
709
837
  readonly location?: {
710
838
  readonly type: `absolute`;
@@ -724,12 +852,17 @@ declare const originSpecs: ({
724
852
  } | undefined;
725
853
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
726
854
  readonly categorizeHeapSnapshotConstructor: (name: string) => HeapSnapshotNodeCategory | undefined;
855
+ readonly matchHeapSnapshotEdgeName: (name: string) => string | undefined;
856
+ readonly categorizeTraceEvent: (event: {
857
+ readonly name: string;
858
+ readonly declaredCategories?: readonly string[] | undefined;
859
+ }) => "script" | "parsing" | "compilation" | "garbage-collection-pause" | "garbage-collection" | "style" | "layout" | "paint" | "io" | "other" | undefined;
860
+ readonly normalizeTraceEvent: (event: TraceEvent) => NormalizedTraceEvent;
727
861
  } | {
728
862
  readonly id: "chrome";
729
863
  readonly title: "Chrome";
730
- readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile"];
864
+ readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile", "trace-event"];
731
865
  readonly isMarkerEntry: ({ name, location }: {
732
- readonly id: number;
733
866
  readonly name?: string | undefined;
734
867
  readonly location?: {
735
868
  readonly type: `absolute`;
@@ -749,7 +882,6 @@ declare const originSpecs: ({
749
882
  } | undefined;
750
883
  }) => boolean;
751
884
  readonly categorizeEntry: (entry: {
752
- readonly id: number;
753
885
  readonly name?: string | undefined;
754
886
  readonly location?: {
755
887
  readonly type: `absolute`;
@@ -769,11 +901,13 @@ declare const originSpecs: ({
769
901
  } | undefined;
770
902
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
771
903
  readonly categorizeHeapSnapshotConstructor: (name: string) => HeapSnapshotNodeCategory | undefined;
904
+ readonly matchHeapSnapshotEdgeName: (name: string) => string | undefined;
905
+ readonly categorizeTraceEvent: ({ name, declaredCategories }: DeepReadonly<Pick<TraceEvent, `name` | `declaredCategories`>>) => TraceEventCategory | undefined;
906
+ readonly normalizeTraceEvent: (event: TraceEvent) => NormalizedTraceEvent;
772
907
  } | {
773
908
  readonly id: "node-pprof";
774
909
  readonly formats: ["pprof"];
775
910
  readonly isMarkerEntry: ({ name, location }: {
776
- readonly id: number;
777
911
  readonly name?: string | undefined;
778
912
  readonly location?: {
779
913
  readonly type: `absolute`;
@@ -793,7 +927,6 @@ declare const originSpecs: ({
793
927
  } | undefined;
794
928
  }) => boolean;
795
929
  readonly categorizeEntry: (entry: {
796
- readonly id: number;
797
930
  readonly name?: string | undefined;
798
931
  readonly location?: {
799
932
  readonly type: `absolute`;
@@ -817,7 +950,6 @@ declare const originSpecs: ({
817
950
  readonly id: "pprof-rs";
818
951
  readonly formats: ["pprof"];
819
952
  readonly isMarkerEntry: (entry: {
820
- readonly id: number;
821
953
  readonly name?: string | undefined;
822
954
  readonly location?: {
823
955
  readonly type: `absolute`;
@@ -837,7 +969,6 @@ declare const originSpecs: ({
837
969
  } | undefined;
838
970
  }) => boolean;
839
971
  readonly categorizeEntry: (entry: {
840
- readonly id: number;
841
972
  readonly name?: string | undefined;
842
973
  readonly location?: {
843
974
  readonly type: `absolute`;
@@ -857,12 +988,12 @@ declare const originSpecs: ({
857
988
  } | undefined;
858
989
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
859
990
  readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
991
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
860
992
  } | {
861
993
  readonly id: "go";
862
994
  readonly title: "pprof";
863
995
  readonly formats: ["pprof"];
864
996
  readonly isMarkerEntry: (entry: {
865
- readonly id: number;
866
997
  readonly name?: string | undefined;
867
998
  readonly location?: {
868
999
  readonly type: `absolute`;
@@ -881,8 +1012,8 @@ declare const originSpecs: ({
881
1012
  readonly column?: number | undefined;
882
1013
  } | undefined;
883
1014
  }) => boolean;
1015
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
884
1016
  readonly categorizeEntry: (entry: {
885
- readonly id: number;
886
1017
  readonly name?: string | undefined;
887
1018
  readonly location?: {
888
1019
  readonly type: `absolute`;
@@ -905,7 +1036,6 @@ declare const originSpecs: ({
905
1036
  readonly id: "pprof-jl";
906
1037
  readonly formats: ["pprof"];
907
1038
  readonly isMarkerEntry: (entry: {
908
- readonly id: number;
909
1039
  readonly name?: string | undefined;
910
1040
  readonly location?: {
911
1041
  readonly type: `absolute`;
@@ -925,7 +1055,6 @@ declare const originSpecs: ({
925
1055
  } | undefined;
926
1056
  }) => boolean;
927
1057
  readonly categorizeEntry: (entry: {
928
- readonly id: number;
929
1058
  readonly name?: string | undefined;
930
1059
  readonly location?: {
931
1060
  readonly type: `absolute`;
@@ -944,13 +1073,13 @@ declare const originSpecs: ({
944
1073
  readonly column?: number | undefined;
945
1074
  } | undefined;
946
1075
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1076
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
947
1077
  readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
948
1078
  } | {
949
1079
  readonly id: "profile-jl";
950
1080
  readonly title: "Profile";
951
1081
  readonly formats: ["v8-heap-snapshot"];
952
1082
  readonly isMarkerEntry: ({ name, location }: {
953
- readonly id: number;
954
1083
  readonly name?: string | undefined;
955
1084
  readonly location?: {
956
1085
  readonly type: `absolute`;
@@ -970,12 +1099,11 @@ declare const originSpecs: ({
970
1099
  } | undefined;
971
1100
  }) => boolean;
972
1101
  readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
973
- readonly categorizeHeapSnapshotDeclaredType: (declaredType: string) => HeapSnapshotNodeCategory | undefined;
1102
+ readonly categorizeHeapSnapshotDeclaredType: (declaredType: string) => "string" | "number" | "symbol" | "object" | "function" | "code" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "big-number" | "object-shape" | "internal" | "synthetic" | undefined;
974
1103
  } | {
975
1104
  readonly id: "pyinstrument";
976
1105
  readonly formats: ["speedscope"];
977
1106
  readonly isMarkerEntry: (entry: {
978
- readonly id: number;
979
1107
  readonly name?: string | undefined;
980
1108
  readonly location?: {
981
1109
  readonly type: `absolute`;
@@ -995,7 +1123,6 @@ declare const originSpecs: ({
995
1123
  } | undefined;
996
1124
  }) => boolean;
997
1125
  readonly categorizeEntry: (entry: {
998
- readonly id: number;
999
1126
  readonly name?: string | undefined;
1000
1127
  readonly location?: {
1001
1128
  readonly type: `absolute`;
@@ -1015,19 +1142,20 @@ declare const originSpecs: ({
1015
1142
  } | undefined;
1016
1143
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1017
1144
  readonly normalizeStackFrame: (input: StackFrame) => StackFrame | {
1018
- location: {
1145
+ definition: {
1019
1146
  type: `file`;
1020
1147
  urlOrPath: string;
1021
- column?: number;
1022
1148
  };
1023
1149
  name?: string;
1024
- line?: number;
1150
+ executing?: SourcePosition;
1151
+ callSite?: UnresolvedSourceReference & {
1152
+ position: SourcePosition;
1153
+ };
1025
1154
  } | null;
1026
1155
  } | {
1027
1156
  readonly id: "py-spy";
1028
1157
  readonly formats: ["collapsed", "speedscope"];
1029
1158
  readonly isMarkerEntry: (entry: {
1030
- readonly id: number;
1031
1159
  readonly name?: string | undefined;
1032
1160
  readonly location?: {
1033
1161
  readonly type: `absolute`;
@@ -1046,13 +1174,13 @@ declare const originSpecs: ({
1046
1174
  readonly column?: number | undefined;
1047
1175
  } | undefined;
1048
1176
  }) => boolean;
1177
+ readonly isOriginHint: (hint: string) => boolean;
1049
1178
  readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1050
- readonly normalizeStackFrame: (input: StackFrame, format: "callgrind" | "collapsed" | "hprof" | "jfr" | "memray" | "perf" | "pprof" | "systing" | "ghc-eventlog" | "ghc-json-profile" | "jsc-heap-snapshot" | "speedscope" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => StackFrame;
1179
+ readonly normalizeStackFrame: (input: StackFrame, format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => StackFrame;
1051
1180
  } | {
1052
1181
  readonly id: "tachyon";
1053
1182
  readonly formats: ["collapsed"];
1054
1183
  readonly isMarkerEntry: (entry: {
1055
- readonly id: number;
1056
1184
  readonly name?: string | undefined;
1057
1185
  readonly location?: {
1058
1186
  readonly type: `absolute`;
@@ -1071,13 +1199,30 @@ declare const originSpecs: ({
1071
1199
  readonly column?: number | undefined;
1072
1200
  } | undefined;
1073
1201
  }) => boolean;
1074
- readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1075
- readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1202
+ readonly categorizeEntry: (entry: {
1203
+ readonly name?: string | undefined;
1204
+ readonly location?: {
1205
+ readonly type: `absolute`;
1206
+ readonly url: URL;
1207
+ readonly line?: number | undefined;
1208
+ readonly column?: number | undefined;
1209
+ } | {
1210
+ readonly type: `relative`;
1211
+ readonly path: string;
1212
+ readonly line?: number | undefined;
1213
+ readonly column?: number | undefined;
1214
+ } | {
1215
+ readonly type: `logical`;
1216
+ readonly name: string;
1217
+ readonly line?: number | undefined;
1218
+ readonly column?: number | undefined;
1219
+ } | undefined;
1220
+ }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1221
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
1076
1222
  } | {
1077
1223
  readonly id: "async-profiler";
1078
1224
  readonly formats: ["jfr", "collapsed"];
1079
1225
  readonly isMarkerEntry: (entry: {
1080
- readonly id: number;
1081
1226
  readonly name?: string | undefined;
1082
1227
  readonly location?: {
1083
1228
  readonly type: `absolute`;
@@ -1098,7 +1243,7 @@ declare const originSpecs: ({
1098
1243
  }) => boolean;
1099
1244
  readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1100
1245
  readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1101
- readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1246
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
1102
1247
  } | {
1103
1248
  readonly id: "jdk";
1104
1249
  readonly title: "JDK";
@@ -1111,7 +1256,6 @@ declare const originSpecs: ({
1111
1256
  readonly id: "dotnet-trace";
1112
1257
  readonly formats: ["speedscope"];
1113
1258
  readonly isMarkerEntry: (entry: {
1114
- readonly id: number;
1115
1259
  readonly name?: string | undefined;
1116
1260
  readonly location?: {
1117
1261
  readonly type: `absolute`;
@@ -1130,8 +1274,8 @@ declare const originSpecs: ({
1130
1274
  readonly column?: number | undefined;
1131
1275
  } | undefined;
1132
1276
  }) => boolean;
1277
+ readonly isOriginHint: (hint: string) => boolean;
1133
1278
  readonly categorizeEntry: (entry: {
1134
- readonly id: number;
1135
1279
  readonly name?: string | undefined;
1136
1280
  readonly location?: {
1137
1281
  readonly type: `absolute`;
@@ -1150,12 +1294,12 @@ declare const originSpecs: ({
1150
1294
  readonly column?: number | undefined;
1151
1295
  } | undefined;
1152
1296
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1297
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1153
1298
  readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
1154
1299
  } | {
1155
1300
  readonly id: "eflambe";
1156
1301
  readonly formats: ["collapsed"];
1157
1302
  readonly isMarkerEntry: (entry: {
1158
- readonly id: number;
1159
1303
  readonly name?: string | undefined;
1160
1304
  readonly location?: {
1161
1305
  readonly type: `absolute`;
@@ -1174,9 +1318,8 @@ declare const originSpecs: ({
1174
1318
  readonly column?: number | undefined;
1175
1319
  } | undefined;
1176
1320
  }) => boolean;
1177
- readonly countMetric: (format: "callgrind" | "collapsed" | "hprof" | "jfr" | "memray" | "perf" | "pprof" | "systing" | "ghc-eventlog" | "ghc-json-profile" | "jsc-heap-snapshot" | "speedscope" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => Metric | undefined;
1321
+ readonly countMetric: (format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => Metric | undefined;
1178
1322
  readonly categorizeEntry: (entry: {
1179
- readonly id: number;
1180
1323
  readonly name?: string | undefined;
1181
1324
  readonly location?: {
1182
1325
  readonly type: `absolute`;
@@ -1197,13 +1340,10 @@ declare const originSpecs: ({
1197
1340
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1198
1341
  readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1199
1342
  } | {
1200
- readonly id: "valgrind";
1201
- readonly title: "Valgrind";
1202
- readonly formats: ["callgrind"];
1203
- readonly isMarkerEntry: () => false;
1204
- readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1205
- readonly hasRuntimeInsertedArcs: ({ name }: {
1206
- readonly id: number;
1343
+ readonly id: "nix";
1344
+ readonly title: "Nix";
1345
+ readonly formats: ["collapsed"];
1346
+ readonly isMarkerEntry: ({ name }: {
1207
1347
  readonly name?: string | undefined;
1208
1348
  readonly location?: {
1209
1349
  readonly type: `absolute`;
@@ -1222,11 +1362,32 @@ declare const originSpecs: ({
1222
1362
  readonly column?: number | undefined;
1223
1363
  } | undefined;
1224
1364
  }) => boolean;
1365
+ readonly categorizeEntry: (entry: {
1366
+ readonly name?: string | undefined;
1367
+ readonly location?: {
1368
+ readonly type: `absolute`;
1369
+ readonly url: URL;
1370
+ readonly line?: number | undefined;
1371
+ readonly column?: number | undefined;
1372
+ } | {
1373
+ readonly type: `relative`;
1374
+ readonly path: string;
1375
+ readonly line?: number | undefined;
1376
+ readonly column?: number | undefined;
1377
+ } | {
1378
+ readonly type: `logical`;
1379
+ readonly name: string;
1380
+ readonly line?: number | undefined;
1381
+ readonly column?: number | undefined;
1382
+ } | undefined;
1383
+ }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1384
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1385
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1386
+ readonly functionIdentity: "call-site";
1225
1387
  } | {
1226
1388
  readonly id: "rbspy";
1227
1389
  readonly formats: ["callgrind", "collapsed", "pprof", "speedscope"];
1228
1390
  readonly isMarkerEntry: (entry: {
1229
- readonly id: number;
1230
1391
  readonly name?: string | undefined;
1231
1392
  readonly location?: {
1232
1393
  readonly type: `absolute`;
@@ -1245,8 +1406,9 @@ declare const originSpecs: ({
1245
1406
  readonly column?: number | undefined;
1246
1407
  } | undefined;
1247
1408
  }) => boolean;
1409
+ readonly isOriginHint: (hint: string, format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => boolean;
1410
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1248
1411
  readonly categorizeEntry: (entry: {
1249
- readonly id: number;
1250
1412
  readonly name?: string | undefined;
1251
1413
  readonly location?: {
1252
1414
  readonly type: `absolute`;
@@ -1265,14 +1427,13 @@ declare const originSpecs: ({
1265
1427
  readonly column?: number | undefined;
1266
1428
  } | undefined;
1267
1429
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1268
- readonly normalizeStackFrame: (input: StackFrame, format: "callgrind" | "collapsed" | "hprof" | "jfr" | "memray" | "perf" | "pprof" | "systing" | "ghc-eventlog" | "ghc-json-profile" | "jsc-heap-snapshot" | "speedscope" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => StackFrame;
1430
+ readonly normalizeStackFrame: (input: StackFrame, format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => StackFrame;
1269
1431
  } | {
1270
1432
  readonly id: "safari";
1271
1433
  readonly title: "Safari";
1272
1434
  readonly formats: ["jsc-heap-snapshot", "webkit-timeline-recording"];
1273
1435
  readonly isMarkerEntry: ({ name, location }: DeepReadonly<ProfileEntry>) => boolean;
1274
1436
  readonly categorizeEntry: (entry: {
1275
- readonly id: number;
1276
1437
  readonly name?: string | undefined;
1277
1438
  readonly location?: {
1278
1439
  readonly type: `absolute`;
@@ -1291,12 +1452,12 @@ declare const originSpecs: ({
1291
1452
  readonly column?: number | undefined;
1292
1453
  } | undefined;
1293
1454
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1294
- readonly categorizeHeapSnapshotConstructor: (name: string) => "string" | "number" | "symbol" | "object" | "function" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "code" | "big-number" | "object-shape" | "internal" | "synthetic" | undefined;
1455
+ readonly categorizeHeapSnapshotConstructor: (name: string) => "string" | "number" | "symbol" | "object" | "function" | "code" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "big-number" | "object-shape" | "internal" | "synthetic" | undefined;
1456
+ readonly matchHeapSnapshotEdgeName: (name: string) => string | undefined;
1295
1457
  } | {
1296
1458
  readonly id: "systing";
1297
1459
  readonly formats: ["systing"];
1298
1460
  readonly isMarkerEntry: (entry: {
1299
- readonly id: number;
1300
1461
  readonly name?: string | undefined;
1301
1462
  readonly location?: {
1302
1463
  readonly type: `absolute`;
@@ -1316,7 +1477,6 @@ declare const originSpecs: ({
1316
1477
  } | undefined;
1317
1478
  }) => boolean;
1318
1479
  readonly categorizeEntry: (entry: {
1319
- readonly id: number;
1320
1480
  readonly name?: string | undefined;
1321
1481
  readonly location?: {
1322
1482
  readonly type: `absolute`;
@@ -1335,13 +1495,13 @@ declare const originSpecs: ({
1335
1495
  readonly column?: number | undefined;
1336
1496
  } | undefined;
1337
1497
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1498
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1338
1499
  readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1339
1500
  } | {
1340
- readonly id: "gperftools";
1341
- readonly formats: ["pprof"];
1342
- readonly isMarkerEntry: () => false;
1343
- readonly categorizeEntry: (entry: {
1344
- readonly id: number;
1501
+ readonly id: "excimer";
1502
+ readonly title: "Excimer";
1503
+ readonly formats: ["collapsed", "speedscope"];
1504
+ readonly isMarkerEntry: ({ name }: {
1345
1505
  readonly name?: string | undefined;
1346
1506
  readonly location?: {
1347
1507
  readonly type: `absolute`;
@@ -1359,13 +1519,9 @@ declare const originSpecs: ({
1359
1519
  readonly line?: number | undefined;
1360
1520
  readonly column?: number | undefined;
1361
1521
  } | undefined;
1362
- }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1363
- } | {
1364
- readonly id: "excimer";
1365
- readonly title: "Excimer";
1366
- readonly formats: ["collapsed", "speedscope"];
1367
- readonly isMarkerEntry: ({ name }: {
1368
- readonly id: number;
1522
+ }) => boolean;
1523
+ readonly isOriginHint: (hint: string) => hint is "Excimer";
1524
+ readonly categorizeEntry: (entry: {
1369
1525
  readonly name?: string | undefined;
1370
1526
  readonly location?: {
1371
1527
  readonly type: `absolute`;
@@ -1383,9 +1539,14 @@ declare const originSpecs: ({
1383
1539
  readonly line?: number | undefined;
1384
1540
  readonly column?: number | undefined;
1385
1541
  } | undefined;
1386
- }) => boolean;
1542
+ }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1543
+ readonly isTruncationMarker: ({ name }: StackFrame) => boolean;
1544
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1545
+ } | {
1546
+ readonly id: "gperftools";
1547
+ readonly formats: ["pprof"];
1548
+ readonly isMarkerEntry: () => false;
1387
1549
  readonly categorizeEntry: (entry: {
1388
- readonly id: number;
1389
1550
  readonly name?: string | undefined;
1390
1551
  readonly location?: {
1391
1552
  readonly type: `absolute`;
@@ -1404,7 +1565,58 @@ declare const originSpecs: ({
1404
1565
  readonly column?: number | undefined;
1405
1566
  } | undefined;
1406
1567
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1568
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1569
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1570
+ } | {
1571
+ readonly id: "clang";
1572
+ readonly title: "Clang";
1573
+ readonly formats: ["trace-event"];
1574
+ readonly isMarkerEntry: () => false;
1575
+ readonly isOriginHint: (hint: string) => boolean;
1576
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1577
+ readonly categorizeTraceEvent: ({ name }: {
1578
+ readonly name: string;
1579
+ readonly declaredCategories?: readonly string[] | undefined;
1580
+ }) => "parsing" | "compilation";
1581
+ readonly normalizeTraceEvent: (event: TraceEvent) => TraceEvent | null;
1582
+ } | {
1583
+ readonly id: "tsc";
1584
+ readonly title: "TypeScript compiler";
1585
+ readonly formats: ["trace-event"];
1586
+ readonly isMarkerEntry: () => false;
1587
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1588
+ readonly categorizeTraceEvent: ({ declaredCategories }: {
1589
+ readonly name: string;
1590
+ readonly declaredCategories?: readonly string[] | undefined;
1591
+ }) => "parsing" | "compilation";
1592
+ } | {
1593
+ readonly id: "valgrind";
1594
+ readonly title: "Valgrind";
1595
+ readonly formats: ["callgrind"];
1596
+ readonly isMarkerEntry: () => false;
1597
+ readonly isOriginHint: (hint: string) => boolean;
1598
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1599
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1407
1600
  readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1601
+ readonly hasRuntimeInsertedArcs: ({ name }: {
1602
+ readonly name?: string | undefined;
1603
+ readonly location?: {
1604
+ readonly type: `absolute`;
1605
+ readonly url: URL;
1606
+ readonly line?: number | undefined;
1607
+ readonly column?: number | undefined;
1608
+ } | {
1609
+ readonly type: `relative`;
1610
+ readonly path: string;
1611
+ readonly line?: number | undefined;
1612
+ readonly column?: number | undefined;
1613
+ } | {
1614
+ readonly type: `logical`;
1615
+ readonly name: string;
1616
+ readonly line?: number | undefined;
1617
+ readonly column?: number | undefined;
1618
+ } | undefined;
1619
+ }) => boolean;
1408
1620
  } | {
1409
1621
  readonly id: "memray";
1410
1622
  readonly formats: ["memray"];
@@ -1416,7 +1628,6 @@ declare const originSpecs: ({
1416
1628
  readonly formats: ["ghc-eventlog", "ghc-json-profile"];
1417
1629
  readonly isMarkerEntry: () => false;
1418
1630
  readonly categorizeEntry: (entry: {
1419
- readonly id: number;
1420
1631
  readonly name?: string | undefined;
1421
1632
  readonly location?: {
1422
1633
  readonly type: `absolute`;
@@ -1440,19 +1651,21 @@ declare const originSpecs: ({
1440
1651
  readonly formats: ["perf"];
1441
1652
  readonly isMarkerEntry: () => false;
1442
1653
  readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1654
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1655
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1443
1656
  } | {
1444
1657
  readonly id: "perf";
1445
1658
  readonly formats: ["perf"];
1446
1659
  readonly isMarkerEntry: () => false;
1447
1660
  readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1661
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1662
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1448
1663
  } | {
1449
1664
  readonly id: "unknown";
1450
1665
  readonly formats: [];
1451
1666
  readonly isMarkerEntry: () => false;
1452
1667
  readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1453
1668
  })[];
1454
- //#endregion
1455
- //#region src/origins/index.d.ts
1456
1669
  /**
1457
1670
  * The profiler tool or runtime that wrote an input (e.g. `node` for
1458
1671
  * Node's native V8 profiler, `node-pprof` for the `pprof` npm package,
@@ -1461,309 +1674,119 @@ declare const originSpecs: ({
1461
1674
  * Auto-detected from a profile's entries via {@link OriginDetector}, or
1462
1675
  * specified explicitly.
1463
1676
  */
1464
- type Origin = SpecificOriginSpec[`id`];
1465
- /** One of the concrete origin specs, with its literal {@link Origin} ID. */
1466
- type SpecificOriginSpec = (typeof originSpecs)[number];
1467
- //#endregion
1468
- //#region src/modalities/call-graph/aggregate.d.ts
1469
- /** One function's recorded costs during calls from a given direct caller. */
1470
- type AggregatedCallGraphCallerMetrics = {
1471
- /** The caller corresponding to the ID. */
1472
- caller: AggregatedCallGraphFunction;
1473
- /** The recorded number of calls, or `0` when the format records none. */
1474
- callCount: number;
1475
- /**
1476
- * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
1477
- * in the function and its callees during calls from this caller.
1478
- */
1479
- totalValues: Float64Array;
1480
- };
1481
- /** One function's recorded costs during its calls to a given direct callee. */
1482
- type AggregatedCallGraphCalleeMetrics = {
1483
- /** The callee corresponding to the ID. */
1484
- callee: AggregatedCallGraphFunction;
1485
- /** The recorded number of calls, or `0` when the format records none. */
1486
- callCount: number;
1677
+ type Origin = RegisteredOriginSpec[`id`];
1678
+ /**
1679
+ * Determines the origin of an input from its entries.
1680
+ *
1681
+ * Resolves to the origin a parser's origin hint names, or else tries each
1682
+ * origin that can emit the format in priority order, resolving to the
1683
+ * highest-priority one with a marker entry among the added entries, and
1684
+ * falling back to the format's fallback origin when none match.
1685
+ *
1686
+ * An explicit origin skips detection.
1687
+ */
1688
+ declare class OriginDetector {
1689
+ #private;
1690
+ constructor({ id: format, fallbackOrigin }: {
1691
+ id: Format;
1692
+ fallbackOrigin: Origin;
1693
+ }, origin?: Origin);
1487
1694
  /**
1488
- * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
1489
- * in the callee and its callees during this function's calls to it.
1695
+ * Whether the origin is already decided, so a caller may skip building
1696
+ * further entries to add.
1490
1697
  */
1491
- totalValues: Float64Array;
1492
- };
1493
- /** An aggregation of one function's recorded costs within a call graph. */
1494
- type AggregatedCallGraphFunction = {
1495
- type: `function`;
1496
- /** An index that uniquely identifies this function. */
1497
- id: number;
1498
- /** The name of the function in code. */
1499
- name: string;
1500
- /** Where the function was defined, if known. */
1501
- location?: SourceLocation;
1502
- /** The category of functions this function belongs to. */
1503
- category: FunctionCategory;
1698
+ get decided(): boolean;
1504
1699
  /**
1505
- * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
1506
- * directly in the function's body, excluding its callees.
1700
+ * Returns whether the origin is now decided, so a caller may stop adding
1701
+ * early. Adding further entries is harmless.
1507
1702
  */
1508
- selfValues: Float64Array;
1703
+ add(entry: DeepReadonly<ProfileEntry>): boolean;
1509
1704
  /**
1510
- * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
1511
- * in the function's body and all its callees: its self values plus its
1512
- * outgoing arcs' inclusive values, excluding the arcs to functions in its own
1513
- * recursion cycle, which re-count the same work.
1705
+ * Applies an origin hint set by a parser: format-level metadata (e.g. a
1706
+ * recorder's own event types or a writer's self-identification field)
1707
+ * pointing at an origin whose entries carry no marker.
1708
+ *
1709
+ * A hint outranks every marker entry, because it is the writer identifying
1710
+ * itself. A specified origin and an earlier hint ignore it, and so does a
1711
+ * hint no candidate for the format accepts.
1514
1712
  */
1515
- totalValues: Float64Array;
1516
- /** 1-based line number to the self values recorded at that line. */
1517
- lineToMetrics: Map<number, Float64Array>;
1518
- /** Direct caller ID to the costs recorded during that caller's calls. */
1519
- callerIdToMetrics: Map<number, AggregatedCallGraphCallerMetrics>;
1520
- /** Direct callee ID to the costs recorded during calls to that callee. */
1521
- calleeIdToMetrics: Map<number, AggregatedCallGraphCalleeMetrics>;
1713
+ hint(hint: string): void;
1714
+ addAll(entries: readonly DeepReadonly<ProfileEntry>[]): void;
1715
+ /** Resolves the detected origin from every entry added so far. */
1716
+ resolve(): Origin;
1717
+ /** The origin evidence {@link resolve} selects the origin by. */
1718
+ get evidence(): OriginEvidence;
1719
+ /** The IDs of the origins that can emit the format, in priority order. */
1720
+ get candidates(): Origin[];
1721
+ }
1722
+ type OriginEvidence = {
1723
+ type: `specified`;
1724
+ } | {
1725
+ type: `marker`;
1726
+ entry: DeepReadonly<ProfileEntry>;
1727
+ } | {
1728
+ type: `hint`;
1729
+ } | {
1730
+ type: `fallback`;
1731
+ };
1732
+ /** One of the concrete origin specs, with its literal {@link Origin} ID. */
1733
+ type RegisteredOriginSpec = (typeof originSpecs)[number];
1734
+ /** The caller's source maps, each keyed by the generated file it maps. */
1735
+ type NormalizedSourceMaps = readonly NormalizedSourceMap[];
1736
+ type NormalizedSourceMap = {
1737
+ consumer: SourceMapConsumer;
1738
+ fileReference: FileReference;
1522
1739
  };
1523
- //#endregion
1524
- //#region src/modalities/call-stack-profile/aggregate.d.ts
1525
1740
  /**
1526
- * An aggregation of observations recorded at a given line within a function's
1527
- * body.
1741
+ * Applies the caller's source maps to one conversion's locations, and records
1742
+ * each generated file's outcome for {@link SourceMapResolver.report}.
1528
1743
  */
1529
- type AggregatedCallStackProfileLineMetrics = {
1530
- /**
1531
- * The number of observations recorded directly within the function's body at
1532
- * this line.
1533
- */
1534
- count: number;
1744
+ declare class SourceMapResolver {
1745
+ #private;
1746
+ constructor(sourceMaps: NormalizedSourceMaps, logger: Logger);
1535
1747
  /**
1536
- * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
1537
- * values from observations recorded directly within the function's body at
1538
- * this line.
1748
+ * Records {@link location}'s generated file, so {@link report} counts it
1749
+ * whether or not formatting resolves a location in it.
1539
1750
  */
1540
- values: Float64Array;
1541
- };
1542
- /**
1543
- * An aggregation of observations recorded directly within a function's body
1544
- * with a given direct caller.
1545
- */
1546
- type AggregatedCallStackProfileCallerMetrics = {
1547
- /** The caller corresponding to the ID. */
1548
- caller: AggregatedCallStackProfileFunction;
1751
+ addGeneratedFile(location: SourceLocation): void;
1549
1752
  /**
1550
- * The number of observations recorded directly within the function's body
1551
- * with this caller.
1753
+ * Applies the matching source map, if any, to {@link location}.
1754
+ *
1755
+ * A mapped source that is a relative path resolves against the resolved
1756
+ * `baseURL`, including one inferred by `baseURL: 'auto'`. The resolved source
1757
+ * may then be outside the inferred directory and format with `../`
1758
+ * segments. Without a base URL the location stays unmapped.
1552
1759
  */
1553
- selfCount: number;
1760
+ resolve(location: SourceLocation, baseURL: URL | undefined): SourceLocation;
1554
1761
  /**
1555
- * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
1556
- * values from observations recorded directly within the function's body with
1557
- * this caller.
1762
+ * Logs what the source maps did across the generated files recorded so far:
1763
+ * a summary of the generated files at `info`, each supplied map that matched
1764
+ * no generated file at `warn`, and each generated file's outcome at `debug`.
1765
+ *
1766
+ * {@link baseURL} is the base URL formatting resolved relative sources
1767
+ * against, so the report states which relative sources stayed unmapped.
1558
1768
  */
1559
- selfValues: Float64Array;
1560
- };
1769
+ report(baseURL: URL | undefined): void;
1770
+ }
1771
+ /** Profile data that can be synchronously parsed and converted to Markdown. */
1772
+ type ProfileData = string | Uint8Array | Iterable<Uint8Array>;
1773
+ /** Profile data that can be asynchronously parsed and converted to Markdown. */
1774
+ type AsyncProfileData = Blob | ReadableStream<Uint8Array>;
1561
1775
  /**
1562
- * An aggregation of observations recorded within a function's body, _and_ all
1563
- * its callees, with a given direct callee.
1776
+ * Profile data with an optional explicit format and origin, and an optional
1777
+ * name for the data's source.
1778
+ *
1779
+ * The format and origin are auto-detected if not specified. The name is
1780
+ * reported with a failure the input causes, so a diff states which of its two
1781
+ * inputs failed.
1564
1782
  */
1565
- type AggregatedCallStackProfileCalleeMetrics = {
1566
- /** The callee corresponding to the ID. */
1567
- callee: AggregatedCallStackProfileFunction;
1568
- /**
1569
- * The number of observations recorded directly within the function's body,
1570
- * _and_ all its callees, with this callee.
1571
- */
1572
- totalCount: number;
1573
- /**
1574
- * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
1575
- * values from observations recorded directly within the function's body,
1576
- * _and_ all its callees, with this callee.
1577
- */
1578
- totalValues: Float64Array;
1579
- /**
1580
- * Internal aggregation bookkeeping: the epoch of the most recent call stack
1581
- * whose total this frame pair was counted into, so one that recurs within
1582
- * one call stack is counted just once.
1583
- */
1584
- lastSeenEpoch: number;
1585
- };
1586
- /**
1587
- * An aggregation of data from every observation involving a given function
1588
- * within a profile.
1589
- */
1590
- type AggregatedCallStackProfileFunction = {
1591
- type: `function`;
1592
- /** An index that uniquely identifies this function. */
1593
- id: number;
1594
- /** The name of the function in code. */
1595
- name: string;
1596
- /** Where the function was defined, if known. */
1597
- location?: SourceLocation;
1598
- /** The category of functions this function belongs to. */
1599
- category: FunctionCategory;
1600
- /**
1601
- * The number of observations recorded directly within the function's body,
1602
- * excluding its callees.
1603
- */
1604
- selfCount: number;
1605
- /**
1606
- * The number of observations recorded directly within the function's body
1607
- * _and_ all its callees.
1608
- */
1609
- totalCount: number;
1610
- /**
1611
- * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
1612
- * values from observations recorded directly within the function's body,
1613
- * excluding its callees.
1614
- */
1615
- selfValues: Float64Array;
1616
- /**
1617
- * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
1618
- * values from observations recorded directly within the function's body _and_
1619
- * all its callees.
1620
- */
1621
- totalValues: Float64Array;
1622
- /** 1-based line number to values and count for that line. */
1623
- lineToMetrics: Map<number, AggregatedCallStackProfileLineMetrics>;
1624
- /**
1625
- * Direct caller id to values and count with that caller's calls to
1626
- * this function.
1627
- */
1628
- callerIdToMetrics: Map<number, AggregatedCallStackProfileCallerMetrics>;
1629
- /**
1630
- * Direct callee id to values and count for that callee's calls where
1631
- * this function was a direct or transitive caller.
1632
- */
1633
- calleeIdToMetrics: Map<number, AggregatedCallStackProfileCalleeMetrics>;
1634
- };
1635
- //#endregion
1636
- //#region src/modalities/heap-snapshot/aggregate.d.ts
1637
- type AggregatedHeapSnapshotNode = {
1638
- type: `node`;
1639
- /** Unique ID for this node that can also be used as an index. */
1640
- id: number;
1641
- /** A human readable label for this node. */
1642
- name?: string;
1643
- /**
1644
- * The file reference the {@link name} parses as, when it is URL-shaped
1645
- * (e.g. a V8 module namespace object named by its file URL). Formatting
1646
- * shows it relative to the base URL in place of the raw name.
1647
- */
1648
- nameLocation?: FileReference;
1649
- /** Bytes allocated directly for this node. */
1650
- selfSize: number;
1651
- /** What this node holds. */
1652
- category: HeapSnapshotNodeCategory;
1653
- /**
1654
- * Bytes allocated for this node, as well as all nodes that would be freed if
1655
- * the node were garbage collected.
1656
- */
1657
- retainedSize: number;
1658
- /** The exact location where the node was defined. */
1659
- location?: SourceLocation;
1660
- };
1661
- //#endregion
1662
- //#region src/source-map.d.ts
1663
- type NormalizedSourceMap = {
1664
- consumer: SourceMapConsumer;
1665
- fileReference: FileReference;
1666
- };
1667
- type NormalizedSourceMaps = NormalizedSourceMap[];
1668
- //#endregion
1669
- //#region src/options.d.ts
1670
- /** Profile data that can be synchronously parsed and converted to Markdown. */
1671
- type ProfileData = string | Uint8Array | Iterable<Uint8Array>;
1672
- /** Profile data that can be asynchronously parsed and converted to Markdown. */
1673
- type AsyncProfileData = Blob | ReadableStream<Uint8Array>;
1674
- /**
1675
- * Profile data with an optional explicit format and origin.
1676
- *
1677
- * The format and origin are auto-detected if not specified.
1678
- */
1679
- type ProfileInput<Data> = Data | {
1680
- data: Data;
1681
- format?: Format;
1682
- origin?: Origin;
1683
- };
1684
- /**
1685
- * The category of code a function originated from.
1686
- *
1687
- * A closed set, so a category names the same thing whichever origin wrote the
1688
- * input and formatting can partition by it. The first three record where the
1689
- * code came from, the next two what the profiler could determine about a frame
1690
- * with no source file, and the rest name a runtime activity.
1691
- *
1692
- * These boundaries decide most assignments:
1693
- *
1694
- * - `stdlib` requires positive evidence that the code is the language's or
1695
- * runtime's own library: a standard-library path, module specifier,
1696
- * namespace, or package prefix. A missing source file is never evidence for
1697
- * `stdlib`
1698
- * - `native` is compiled code the profiler attributed to no source file, plus
1699
- * code located in a shared library or in a runtime's own C/C++ sources.
1700
- * `unknown` is a frame the profiler could not identify, a weaker claim,
1701
- * because the code may be a function in the profiled language
1702
- * - `compiler` is the runtime producing executable code, and `jit` is a frame
1703
- * executing code the runtime generated. Where a frame both executes generated
1704
- * code and does the work of a named activity, the activity takes precedence,
1705
- * so a garbage collection write barrier compiled inline is
1706
- * `garbage-collector`
1707
- */
1708
- type FunctionCategory = (typeof FUNCTION_CATEGORIES)[number];
1709
- /** Every category {@link FunctionCategory} allows. */
1710
- declare const FUNCTION_CATEGORIES: readonly ["ours", "third-party", "stdlib", "native", "unknown", "garbage-collector", "compiler", "jit", "regexp", "kernel", "idle"];
1711
- /** A single entry in a formatted profile. */
1712
- type ProfileEntry = {
1713
- /** An index that uniquely identifies this entry. */
1714
- id: number;
1715
- /**
1716
- * The name of the entity corresponding to this entry (e.g. a function name)
1717
- * if it has one.
1718
- */
1719
- name?: string;
1720
- /**
1721
- * The location where the entity corresponding to this entry was defined: a
1722
- * file, or a logical name such as a JVM class or a BEAM module when the
1723
- * runtime reports no file. Undefined if unknown.
1724
- */
1725
- location?: SourceLocation;
1726
- };
1727
- /**
1728
- * Normalized entry fields used to match an entry across diffed profiles.
1729
- *
1730
- * Only affects matching; the entry's displayed name and location are
1731
- * unchanged.
1732
- */
1733
- type EntryMatch = {
1734
- /** The name to match by. Omit to match by the entry's name. */
1735
- name?: string;
1736
- /**
1737
- * The location to match by, as a URL, file path, or logical name string.
1738
- * Omit to match by the entry's location. An empty string matches by name
1739
- * alone.
1740
- */
1741
- location?: string;
1742
- };
1743
- /**
1744
- * The keys an entry is paired by across a diff's two sides, derived from its
1745
- * {@link EntryMatch}.
1746
- */
1747
- type EntryMatchKeys = {
1748
- /**
1749
- * The key pairing entries by normalized name alone, for entities whose
1750
- * location varies between profiles of the same program.
1751
- */
1752
- name: string;
1753
- /** The key pairing entries by normalized name and location. */
1754
- nameAndLocation: string;
1755
- };
1756
- /** An aggregated entry in a formatted profile. */
1757
- type AggregatedProfileEntry = AggregatedCallStackProfileFunction | AggregatedCallGraphFunction | AggregatedHeapSnapshotNode;
1758
- /** The context in which a profile is being converted to Markdown. */
1759
- type ProfileToMdContext = {
1760
- /** The format of the profile being converted. */
1761
- format: Format;
1762
- /** The origin of the profile being converted. */
1763
- origin: Origin;
1764
- };
1765
- /** Options for profile to Markdown converters. */
1766
- type ProfileToMdOptions = {
1783
+ type ProfileInput<Data> = Data | {
1784
+ data: Data;
1785
+ format?: Format;
1786
+ origin?: Origin;
1787
+ name?: string;
1788
+ };
1789
+ type ProfileToMdOptions = {
1767
1790
  /**
1768
1791
  * The number of entries to display when computing the "top N" by some metric.
1769
1792
  *
@@ -1771,9 +1794,10 @@ type ProfileToMdOptions = {
1771
1794
  * split into per-category subsections displays up to this many entries in
1772
1795
  * every one of them. See {@link minCategoryShare}.
1773
1796
  *
1774
- * This value, divided by a constant, also limits subsection entry count.
1797
+ * A quarter of this value, rounded up, limits the lists nested under each
1798
+ * entry, such as its hottest lines.
1775
1799
  *
1776
- * Defaults to 20.
1800
+ * Must be a positive integer. Defaults to 20.
1777
1801
  */
1778
1802
  topN?: number;
1779
1803
  /**
@@ -1798,12 +1822,14 @@ type ProfileToMdOptions = {
1798
1822
  /**
1799
1823
  * Base URL to show paths relative to in the Markdown output.
1800
1824
  *
1801
- * Accepts an absolute file path string or URL. File paths are converted to
1802
- * `file://` URLs internally.
1825
+ * Accepts an absolute file path string or URL.
1826
+ *
1827
+ * A value of `'auto'` infers a base URL from the locations of the program's
1828
+ * own code.
1803
1829
  *
1804
- * A value of `'auto'` infers the base URL as the common ancestor directory
1805
- * of the input's entries with absolute locations (`file:`, `http(s):`, etc.),
1806
- * across all profiles of an input and across both sides of a diff.
1830
+ * A path stays absolute when it goes up more than two directories from the
1831
+ * base URL. A `file:` path also stays absolute when it shares no directory
1832
+ * with the base URL, including when it is on another Windows drive.
1807
1833
  *
1808
1834
  * A value of `null` leaves URLs absolute.
1809
1835
  *
@@ -1822,13 +1848,41 @@ type ProfileToMdOptions = {
1822
1848
  */
1823
1849
  sourceMaps?: SourceMap[] | Record<string, SourceMap>;
1824
1850
  /**
1825
- * Returns a normalized name and location to match this entry by across
1826
- * diffed profiles, or `undefined` to match by the entry's own name and
1827
- * location.
1851
+ * Receive the conversion's diagnostics: at `warn`, an option or input that
1852
+ * had no effect; at `info`, each decision made on your behalf; and at
1853
+ * `debug`, the reasoning behind each decision.
1854
+ *
1855
+ * Only defined methods are called, so `console` qualifies. The logger
1856
+ * receives only the levels {@link logLevel} enables.
1857
+ */
1858
+ logger?: Logger;
1859
+ /**
1860
+ * The most verbose level {@link logger} receives.
1861
+ *
1862
+ * Defaults to `none`.
1863
+ */
1864
+ logLevel?: LogLevel;
1865
+ /**
1866
+ * Returns an entry match, the name and location to match this entry by
1867
+ * across diffed profiles, or `undefined` to match by the entry's own name
1868
+ * and location.
1828
1869
  *
1829
1870
  * Only affects which entries are considered the same entity when diffing
1830
1871
  * (e.g. profile functions); displayed names and locations, categorization,
1831
- * and source map resolution always use the entry's real name and location.
1872
+ * and source map resolution use the entry's real name and location, except
1873
+ * where a diff side merges functions.
1874
+ *
1875
+ * `profileToMd` and `profileToMdAsync` ignore it and log a warning.
1876
+ *
1877
+ * A call stack profile or call graph diff first pairs entries whose own names
1878
+ * and locations are equal, and pairs only the rest by their entry matches.
1879
+ * Where an entry match gives distinct entities one key, the diff still pairs
1880
+ * each entity whose identifier is unchanged with itself. Each side of a call
1881
+ * stack profile or heap snapshot diff merges its entities with no line that
1882
+ * share a match key and that the other side lacks into one entity, named and
1883
+ * located by the entry match, because the diff has no position to pair them
1884
+ * by. The entity it pairs with on the other side takes the same name and
1885
+ * location.
1832
1886
  *
1833
1887
  * Matched entries display the _current_ profile's name and location (not
1834
1888
  * _base_).
@@ -1840,20 +1894,15 @@ type ProfileToMdOptions = {
1840
1894
  * Returns a {@link FunctionCategory} per entry of a profile, as an array
1841
1895
  * aligned with {@link entries} (index `i` categorizes entry `i`).
1842
1896
  *
1843
- * The categories are a closed set, so a category names the same thing
1844
- * whichever origin wrote the input.
1845
- *
1846
1897
  * Used to compute:
1847
1898
  * - A category breakdown in the Markdown output
1848
1899
  * - The `baseURL` when using `baseURL: 'auto'`
1849
1900
  * - Which entries to show in {@link defaultShowEntry}
1850
1901
  *
1851
- * Called once per profile with all its {@link entries}. Receiving every entry
1852
- * up front lets the categorizer decide from the full set rather than per
1853
- * entry in isolation.
1902
+ * Called once per profile with all its {@link entries}.
1854
1903
  *
1855
- * Doesn't apply to heap snapshots because they record their own node
1856
- * categories.
1904
+ * Doesn't apply to heap snapshots, which record their own node categories,
1905
+ * or to traces, whose events the origin categorizes.
1857
1906
  *
1858
1907
  * Defaults to {@link defaultCategorizeFunctions}.
1859
1908
  */
@@ -1867,55 +1916,96 @@ type ProfileToMdOptions = {
1867
1916
  */
1868
1917
  showEntry?: (entry: DeepReadonly<AggregatedProfileEntry>, context: ProfileToMdContext) => boolean;
1869
1918
  };
1919
+ /**
1920
+ * The name and location overrides an entry's match key is built from, with the
1921
+ * identifiers that differ per run or build stripped.
1922
+ *
1923
+ * Only affects matching; the entry's displayed name and location are
1924
+ * unchanged.
1925
+ */
1926
+ type EntryMatch = {
1927
+ /** The name to match by. Omit to match by the entry's name. */
1928
+ name?: string;
1929
+ /**
1930
+ * The location to match by, as a URL, file path, or logical name string.
1931
+ * Omit to match by the entry's location. An empty string matches by name
1932
+ * alone.
1933
+ */
1934
+ location?: string;
1935
+ };
1870
1936
  /** {@link ProfileToMdOptions} with defaults applied. */
1871
1937
  type NormalizedProfileToMdOptions = {
1872
1938
  topN: number;
1873
1939
  minCategoryShare: number;
1874
1940
  baseURL: URL | `auto` | undefined;
1875
1941
  sourceMaps: NormalizedSourceMaps;
1942
+ logger: Logger;
1876
1943
  entryMatchKeys: (entry: ProfileEntry, context: ProfileToMdContext) => EntryMatchKeys;
1877
1944
  categorizeFunctions: (entries: readonly ProfileEntry[], context: ProfileToMdContext) => readonly FunctionCategory[];
1878
1945
  showEntry: (entry: DeepReadonly<AggregatedProfileEntry>, context: ProfileToMdContext) => boolean;
1879
1946
  };
1880
1947
  /**
1881
- * The options aggregation code receives.
1882
- *
1883
- * Everything except `baseURL`, which only affects formatting and, for `'auto'`,
1884
- * is resolvable only after aggregation (from the aggregated entries). The
1885
- * omission keeps aggregation logic from depending on it.
1948
+ * Omits the options that only affect formatting, so aggregation cannot depend
1949
+ * on them. `baseURL: 'auto'` resolves only from the aggregated entries.
1886
1950
  */
1887
- type AggregationProfileToMdOptions = Omit<NormalizedProfileToMdOptions, `baseURL`>;
1951
+ type AggregationProfileToMdOptions = Omit<NormalizedProfileToMdOptions, `baseURL` | `sourceMaps`>;
1888
1952
  /**
1889
- * The options formatting code receives.
1890
- *
1891
1953
  * {@link NormalizedProfileToMdOptions} with `'auto'` resolved to a concrete
1892
- * base URL (or `undefined` when nothing qualified for inference).
1954
+ * base URL (or `undefined` when nothing qualified for inference), and the
1955
+ * source maps wrapped in a resolver that records one conversion's outcomes.
1893
1956
  */
1894
1957
  type FormattingProfileToMdOptions = AggregationProfileToMdOptions & {
1895
1958
  baseURL: URL | undefined;
1959
+ /**
1960
+ * A diff's base side's own base URL, for the locations below it, when the
1961
+ * sides' base URLs differ only by what an entry match removes.
1962
+ * {@link baseURL} applies to every other location.
1963
+ */
1964
+ baseSideBaseURL?: URL;
1965
+ sourceMaps: SourceMapResolver;
1966
+ /**
1967
+ * Whether a diffed entity's base and current sources are one source.
1968
+ * Defaults to whether they are the same source reference.
1969
+ */
1970
+ isSameMatchedSource?: (base: SourceLocation, current: SourceLocation) => boolean;
1971
+ };
1972
+ /** A single entry in a formatted profile. */
1973
+ type ProfileEntry = {
1974
+ /** The name of the entity corresponding to this entry (e.g. a function name). */
1975
+ name?: string;
1976
+ /**
1977
+ * The location where the entity corresponding to this entry was defined: a
1978
+ * file, or a logical name such as a JVM class or a BEAM module when the
1979
+ * runtime reports no file. Undefined if unknown.
1980
+ */
1981
+ location?: SourceLocation;
1982
+ };
1983
+ type ProfileToMdContext = {
1984
+ format: Format;
1985
+ origin: Origin;
1896
1986
  };
1897
1987
  /**
1898
1988
  * The default {@link ProfileToMdOptions.matchEntry}.
1899
1989
  *
1900
- * Applies the origin's match normalization to the entry, stripping the origin's
1901
- * known run-varying identifiers (e.g. Rust build hashes for `pprof-rs`, JVM
1902
- * runtime addresses for `jdk`), or `undefined` if the entry contains none.
1990
+ * Builds the origin's entry match for the entry, stripping the origin's known
1991
+ * run-varying identifiers (e.g. Rust build hashes for `pprof-rs`, JVM runtime
1992
+ * addresses for `jdk`), or returns `undefined` if the entry contains none.
1903
1993
  */
1904
- declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>, { origin }: ProfileToMdContext) => EntryMatch | undefined;
1994
+ export declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>, { origin }: ProfileToMdContext) => EntryMatch | undefined;
1905
1995
  /**
1906
1996
  * The default {@link ProfileToMdOptions.categorizeFunctions}.
1907
1997
  *
1908
1998
  * Applies the library's origin-aware categorization to each entry.
1909
1999
  */
1910
- declare const defaultCategorizeFunctions: (entries: readonly DeepReadonly<ProfileEntry>[], { origin }: ProfileToMdContext) => FunctionCategory[];
2000
+ export declare const defaultCategorizeFunctions: (entries: readonly DeepReadonly<ProfileEntry>[], { origin }: ProfileToMdContext) => FunctionCategory[];
1911
2001
  /**
1912
- * Returns whether to include the given entry in the Markdown output.
2002
+ * The default {@link ProfileToMdOptions.showEntry}.
1913
2003
  *
1914
2004
  * Excludes synthetic entries, which correspond to nothing in the profiled
1915
2005
  * program. Every function it ran is shown, and each ranking breaks down by
1916
2006
  * category, so a reader chooses which code to read.
1917
2007
  */
1918
- declare const defaultShowEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
2008
+ export declare const defaultShowEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
1919
2009
  /**
1920
2010
  * Returns true if the entry is synthetic.
1921
2011
  *
@@ -1925,23 +2015,1823 @@ declare const defaultShowEntry: (entry: DeepReadonly<AggregatedProfileEntry>) =>
1925
2015
  * A heap snapshot node holding text takes the text as its name, so a string
1926
2016
  * whose value equals a synthetic name is not a synthetic entry.
1927
2017
  */
1928
- declare const isSyntheticEntry: ({ name, category }: DeepReadonly<AggregatedProfileEntry>) => boolean;
1929
- //#endregion
1930
- //#region src/formats/index.d.ts
2018
+ export declare const isSyntheticEntry: ({ name, category }: DeepReadonly<AggregatedProfileEntry>) => boolean;
2019
+ /**
2020
+ * The keys an entry is paired by across a diff's two sides, derived from its
2021
+ * {@link EntryMatch}.
2022
+ */
2023
+ type EntryMatchKeys = {
2024
+ /**
2025
+ * The key pairing entries by their entry match's name alone, for entities
2026
+ * whose location varies between profiles of the same program.
2027
+ */
2028
+ name: string;
2029
+ /**
2030
+ * The source reference ID the entry match pairs the entry by, or the
2031
+ * entry's own. Empty when the entry match pairs by name alone.
2032
+ */
2033
+ location: string | undefined;
2034
+ nameAndLocation: string;
2035
+ /**
2036
+ * The key built from the entry's own name and location, ignoring its
2037
+ * {@link EntryMatch}.
2038
+ */
2039
+ ownNameAndLocation: string;
2040
+ };
2041
+ type SourceLocation = SourceReference & {
2042
+ /** The 1-based line number in the referenced source. */
2043
+ line?: number;
2044
+ /** The 1-based column number in the referenced source. */
2045
+ column?: number;
2046
+ };
2047
+ /** A reference to where a function is defined. */
2048
+ type SourceReference = FileReference | LogicalReference;
2049
+ type FileReference = {
2050
+ type: `absolute`;
2051
+ url: URL;
2052
+ } | {
2053
+ type: `relative`;
2054
+ path: string;
2055
+ };
2056
+ /**
2057
+ * A named class, module, namespace, assembly, or native library (e.g.
2058
+ * `java.util.HashMap`).
2059
+ */
2060
+ type LogicalReference = {
2061
+ type: `logical`;
2062
+ name: string;
2063
+ };
2064
+ /**
2065
+ * A source reference as the parser records it, before resolution to a
2066
+ * {@link SourceReference}.
2067
+ */
2068
+ type UnresolvedSourceReference = {
2069
+ type: `file`;
2070
+ urlOrPath: string;
2071
+ } | {
2072
+ type: `logical`;
2073
+ /**
2074
+ * The name of a class, module, namespace, assembly, or native library.
2075
+ */
2076
+ name: string;
2077
+ };
2078
+ type SourcePosition = {
2079
+ /** The 1-based line number in the referenced source. */
2080
+ line: number;
2081
+ /** The 1-based column number in the referenced source. */
2082
+ column?: number;
2083
+ };
2084
+ type InputAggregator<Aggregated> = {
2085
+ /**
2086
+ * Passes this input's origin-detection entries to the raw input's shared
2087
+ * detector.
2088
+ *
2089
+ * May be skipped when the detector decides early.
2090
+ */
2091
+ detectOrigin: (detector: OriginDetector) => void;
2092
+ /**
2093
+ * Aggregates the input under the raw input's resolved context. On a side of
2094
+ * a diff, {@link otherSide} is the other side's input that the diff pairs
2095
+ * with this one.
2096
+ */
2097
+ aggregate: (options: AggregationProfileToMdOptions, context: ProfileToMdContext, otherSide?: OtherSideInput) => Aggregated;
2098
+ };
2099
+ /** An input's aggregator, under the context of the raw input it is part of. */
2100
+ type OtherSideInput = {
2101
+ aggregator: InputAggregator<unknown>;
2102
+ context: ProfileToMdContext;
2103
+ };
2104
+ /** An aggregation of all observations within a call stack profile. */
2105
+ type AggregatedCallStackProfile = {
2106
+ type: `call-stack-profile`;
2107
+ /**
2108
+ * The context (format and resolved origin) this profile was aggregated under.
2109
+ * Match keys vary by origin, so build each diffed side's keys under that
2110
+ * side's own context. Sides that resolved different origins can normalize
2111
+ * match keys differently and miss matches.
2112
+ */
2113
+ context: ProfileToMdContext;
2114
+ /** Metrics recorded in this profile. */
2115
+ metrics: Metric[];
2116
+ /**
2117
+ * What one unit of {@link Observation.count} measures: a periodic sample of
2118
+ * the call stack, an entry into a function, an allocated object, a
2119
+ * microsecond of traced time.
2120
+ *
2121
+ * With a count metric, the output formats the count as a count and states a
2122
+ * rate per one of the things counted. With a time or size metric, the output
2123
+ * formats the count as that quantity and states no rate, since a quantity
2124
+ * has no unit to state a rate per.
2125
+ *
2126
+ * `null` when the counts measure nothing, so the profile reports its metrics
2127
+ * alone.
2128
+ */
2129
+ countMetric: Metric | null;
2130
+ /** The number of counted units recorded within this profile. */
2131
+ totalCount: number;
2132
+ /**
2133
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
2134
+ * values from observations recorded within this profile.
2135
+ */
2136
+ totalValues: Float64Array;
2137
+ /**
2138
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the average
2139
+ * metric value per counted unit (total value ÷ total count).
2140
+ *
2141
+ * Meaningless, and unreported, for a profile whose counts measure nothing or
2142
+ * that counted nothing.
2143
+ */
2144
+ rates: Float64Array;
2145
+ /**
2146
+ * Function category to values and count for calls of functions with
2147
+ * that category.
2148
+ */
2149
+ categoryToMetrics: Map<FunctionCategory, AggregatedCallStackProfileCategoryMetrics>;
2150
+ /** Aggregated data for all functions called in this profile. */
2151
+ functions: AggregatedCallStackProfileFunction[];
2152
+ /** Aggregated data for all call stacks encountered in this profile. */
2153
+ callStacks: AggregatedCallStackProfileCallStack[];
2154
+ };
2155
+ declare class CallStackProfileAggregator implements InputAggregator<AggregatedCallStackProfile> {
2156
+ #private;
2157
+ constructor(profile: CallStackProfile);
2158
+ detectOrigin(detector: OriginDetector): void;
2159
+ /** The identity keys of the input's functions with no line. */
2160
+ linelessFunctionKeys(context: ProfileToMdContext): ReadonlySet<string>;
2161
+ aggregate(options: AggregationProfileToMdOptions, context: ProfileToMdContext, otherSide?: OtherSideInput): AggregatedCallStackProfile;
2162
+ }
2163
+ /**
2164
+ * An aggregation of data from every observation of functions with a given
2165
+ * category within a profile.
2166
+ */
2167
+ type AggregatedCallStackProfileCategoryMetrics = {
2168
+ /** The number of observations recorded for functions with this category. */
2169
+ count: number;
2170
+ /**
2171
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
2172
+ * values from observations recorded for functions with this category.
2173
+ */
2174
+ values: Float64Array;
2175
+ };
2176
+ /**
2177
+ * An aggregation of data from every observation involving a given function
2178
+ * within a profile.
2179
+ */
2180
+ type AggregatedCallStackProfileFunction = {
2181
+ type: `function`;
2182
+ /** An index that uniquely identifies this function. */
2183
+ id: number;
2184
+ name: string;
2185
+ /** Where the function was defined, if known. */
2186
+ location?: SourceLocation;
2187
+ /**
2188
+ * Whether the function merges several functions of a diff side that have no
2189
+ * line and share a match key, so the entry match names and locates it.
2190
+ */
2191
+ merged?: boolean;
2192
+ category: FunctionCategory;
2193
+ /**
2194
+ * The number of observations recorded directly within the function's body,
2195
+ * excluding its callees.
2196
+ */
2197
+ selfCount: number;
2198
+ /**
2199
+ * The number of observations recorded directly within the function's body
2200
+ * _and_ all its callees.
2201
+ */
2202
+ totalCount: number;
2203
+ /**
2204
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
2205
+ * values from observations recorded directly within the function's body,
2206
+ * excluding its callees.
2207
+ */
2208
+ selfValues: Float64Array;
2209
+ /**
2210
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
2211
+ * values from observations recorded directly within the function's body _and_
2212
+ * all its callees.
2213
+ */
2214
+ totalValues: Float64Array;
2215
+ /** 1-based line number to values and count for that line. */
2216
+ lineToMetrics: Map<number, AggregatedCallStackProfileLineMetrics>;
2217
+ /**
2218
+ * Direct caller id to values and count with that caller's calls to
2219
+ * this function.
2220
+ */
2221
+ callerIdToMetrics: Map<number, AggregatedCallStackProfileCallerMetrics>;
2222
+ /**
2223
+ * Direct callee id to values and count for that callee's calls where
2224
+ * this function was a direct or transitive caller.
2225
+ */
2226
+ calleeIdToMetrics: Map<number, AggregatedCallStackProfileCalleeMetrics>;
2227
+ };
2228
+ /**
2229
+ * An aggregation of observations recorded at a given line within a function's
2230
+ * body.
2231
+ */
2232
+ type AggregatedCallStackProfileLineMetrics = {
2233
+ /**
2234
+ * The number of observations recorded directly within the function's body at
2235
+ * this line.
2236
+ */
2237
+ count: number;
2238
+ /**
2239
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
2240
+ * values from observations recorded directly within the function's body at
2241
+ * this line.
2242
+ */
2243
+ values: Float64Array;
2244
+ };
2245
+ /**
2246
+ * An aggregation of observations recorded directly within a function's body
2247
+ * with a given direct caller.
2248
+ */
2249
+ type AggregatedCallStackProfileCallerMetrics = {
2250
+ /** The caller corresponding to the ID. */
2251
+ caller: AggregatedCallStackProfileFunction;
2252
+ /**
2253
+ * The number of observations recorded directly within the function's body
2254
+ * with this caller.
2255
+ */
2256
+ selfCount: number;
2257
+ /**
2258
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
2259
+ * values from observations recorded directly within the function's body with
2260
+ * this caller.
2261
+ */
2262
+ selfValues: Float64Array;
2263
+ };
2264
+ /**
2265
+ * An aggregation of observations recorded within a function's body, _and_ all
2266
+ * its callees, with a given direct callee.
2267
+ */
2268
+ type AggregatedCallStackProfileCalleeMetrics = {
2269
+ /** The callee corresponding to the ID. */
2270
+ callee: AggregatedCallStackProfileFunction;
2271
+ /**
2272
+ * The number of observations recorded directly within the function's body,
2273
+ * _and_ all its callees, with this callee.
2274
+ */
2275
+ totalCount: number;
2276
+ /**
2277
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
2278
+ * values from observations recorded directly within the function's body,
2279
+ * _and_ all its callees, with this callee.
2280
+ */
2281
+ totalValues: Float64Array;
2282
+ /**
2283
+ * Internal aggregation bookkeeping: the epoch of the most recent call stack
2284
+ * whose total this frame pair was counted into, so one that recurs within
2285
+ * one call stack is counted just once.
2286
+ */
2287
+ lastSeenEpoch: number;
2288
+ };
2289
+ /**
2290
+ * An aggregation of data from every observation involving a given function call
2291
+ * stack within a profile.
2292
+ */
2293
+ type AggregatedCallStackProfileCallStack = {
2294
+ /** The functions on the call stack in callee to caller order. */
2295
+ frames: AggregatedCallStackProfileFunction[];
2296
+ /** @see {@link Observation.truncated} */
2297
+ truncated: boolean;
2298
+ /** The number of observations recorded with this exact call stack. */
2299
+ selfCount: number;
2300
+ /**
2301
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
2302
+ * values from observations recorded with this exact call stack.
2303
+ */
2304
+ selfValues: Float64Array;
2305
+ };
2306
+ // ## Interfaces
2307
+ /**
2308
+ * Info associated with nodes by the ecosystem.
2309
+ *
2310
+ * This space is guaranteed to never be specified by unist or specifications
2311
+ * implementing unist.
2312
+ * But you can use it in utilities and plugins to store data.
2313
+ *
2314
+ * This type can be augmented to register custom data.
2315
+ * For example:
2316
+ *
2317
+ * ```ts
2318
+ * declare module 'unist' {
2319
+ * interface Data {
2320
+ * // `someNode.data.myId` is typed as `number | undefined`
2321
+ * myId?: number | undefined
2322
+ * }
2323
+ * }
2324
+ * ```
2325
+ */
2326
+ interface Data$1 {}
2327
+ /**
2328
+ * One place in a source file.
2329
+ */
2330
+ interface Point {
2331
+ /**
2332
+ * Line in a source file (1-indexed integer).
2333
+ */
2334
+ line: number;
2335
+ /**
2336
+ * Column in a source file (1-indexed integer).
2337
+ */
2338
+ column: number;
2339
+ /**
2340
+ * Character in a source file (0-indexed integer).
2341
+ */
2342
+ offset?: number | undefined;
2343
+ }
2344
+ /**
2345
+ * Position of a node in a source document.
2346
+ *
2347
+ * A position is a range between two points.
2348
+ */
2349
+ interface Position {
2350
+ /**
2351
+ * Place of the first character of the parsed source region.
2352
+ */
2353
+ start: Point;
2354
+ /**
2355
+ * Place of the first character after the parsed source region.
2356
+ */
2357
+ end: Point;
2358
+ }
2359
+ /**
2360
+ * Abstract unist node.
2361
+ *
2362
+ * The syntactic unit in unist syntax trees are called nodes.
2363
+ *
2364
+ * This interface is supposed to be extended.
2365
+ * If you can use {@link Literal} or {@link Parent}, you should.
2366
+ * But for example in markdown, a `thematicBreak` (`***`), is neither literal
2367
+ * nor parent, but still a node.
2368
+ */
2369
+ interface Node$1 {
2370
+ /**
2371
+ * Node type.
2372
+ */
2373
+ type: string;
2374
+ /**
2375
+ * Info from the ecosystem.
2376
+ */
2377
+ data?: Data$1 | undefined;
2378
+ /**
2379
+ * Position of a node in a source document.
2380
+ *
2381
+ * Nodes that are generated (not in the original source document) must not
2382
+ * have a position.
2383
+ */
2384
+ position?: Position | undefined;
2385
+ }
2386
+ // ## Enumeration
2387
+ /**
2388
+ * How phrasing content is aligned
2389
+ * ({@link https://drafts.csswg.org/css-text/ | [CSSTEXT]}).
2390
+ *
2391
+ * * `'left'`: See the
2392
+ * {@link https://drafts.csswg.org/css-text/#valdef-text-align-left | left}
2393
+ * value of the `text-align` CSS property
2394
+ * * `'right'`: See the
2395
+ * {@link https://drafts.csswg.org/css-text/#valdef-text-align-right | right}
2396
+ * value of the `text-align` CSS property
2397
+ * * `'center'`: See the
2398
+ * {@link https://drafts.csswg.org/css-text/#valdef-text-align-center | center}
2399
+ * value of the `text-align` CSS property
2400
+ * * `null`: phrasing content is aligned as defined by the host environment
2401
+ *
2402
+ * Used in GFM tables.
2403
+ */
2404
+ type AlignType = "center" | "left" | "right" | null;
2405
+ /**
2406
+ * Explicitness of a reference.
2407
+ *
2408
+ * `'shortcut'`: the reference is implicit, its identifier inferred from its
2409
+ * content
2410
+ * `'collapsed'`: the reference is explicit, its identifier inferred from its
2411
+ * content
2412
+ * `'full'`: the reference is explicit, its identifier explicitly set
2413
+ */
2414
+ type ReferenceType = "shortcut" | "collapsed" | "full";
2415
+ // ## Mixin
2416
+ /**
2417
+ * Node with a fallback.
2418
+ */
2419
+ interface Alternative {
2420
+ /**
2421
+ * Equivalent content for environments that cannot represent the node as
2422
+ * intended.
2423
+ */
2424
+ alt?: string | null | undefined;
2425
+ }
2426
+ /**
2427
+ * Internal relation from one node to another.
2428
+ *
2429
+ * Whether the value of `identifier` is expected to be a unique identifier or
2430
+ * not depends on the type of node including the Association.
2431
+ * An example of this is that they should be unique on {@link Definition},
2432
+ * whereas multiple {@link LinkReference}s can be non-unique to be associated
2433
+ * with one definition.
2434
+ */
2435
+ interface Association {
2436
+ /**
2437
+ * Relation of association.
2438
+ *
2439
+ * `identifier` is a source value: character escapes and character
2440
+ * references are not parsed.
2441
+ *
2442
+ * It can match another node.
2443
+ *
2444
+ * Its value must be normalized.
2445
+ * To normalize a value, collapse markdown whitespace (`[\t\n\r ]+`) to a space,
2446
+ * trim the optional initial and/or final space, and perform Unicode-aware
2447
+ * case-folding.
2448
+ */
2449
+ identifier: string;
2450
+ /**
2451
+ * Relation of association, in parsed form.
2452
+ *
2453
+ * `label` is a `string` value: it works just like `title` on {@link Link}
2454
+ * or a `lang` on {@link Code}: character escapes and character references
2455
+ * are parsed.
2456
+ *
2457
+ * It can match another node.
2458
+ */
2459
+ label?: string | null | undefined;
2460
+ }
2461
+ /**
2462
+ * Marker that is associated to another node.
2463
+ */
2464
+ interface Reference extends Association {
2465
+ /**
2466
+ * Explicitness of the reference.
2467
+ */
2468
+ referenceType: ReferenceType;
2469
+ }
2470
+ /**
2471
+ * Reference to resource.
2472
+ */
2473
+ interface Resource {
2474
+ /**
2475
+ * URL to the referenced resource.
2476
+ */
2477
+ url: string;
2478
+ /**
2479
+ * Advisory information for the resource, such as would be appropriate for
2480
+ * a tooltip.
2481
+ */
2482
+ title?: string | null | undefined;
2483
+ }
2484
+ // ## Interfaces
2485
+ /**
2486
+ * Info associated with mdast nodes by the ecosystem.
2487
+ *
2488
+ * This space is guaranteed to never be specified by unist or mdast.
2489
+ * But you can use it in utilities and plugins to store data.
2490
+ *
2491
+ * This type can be augmented to register custom data.
2492
+ * For example:
2493
+ *
2494
+ * ```ts
2495
+ * declare module 'mdast' {
2496
+ * interface Data {
2497
+ * // `someNode.data.myId` is typed as `number | undefined`
2498
+ * myId?: number | undefined
2499
+ * }
2500
+ * }
2501
+ * ```
2502
+ */
2503
+ interface Data extends Data$1 {}
2504
+ // ## Content maps
2505
+ /**
2506
+ * Union of registered mdast nodes that can occur where block content is
2507
+ * expected.
2508
+ *
2509
+ * To register custom mdast nodes, add them to {@link BlockContentMap}.
2510
+ * They will be automatically added here.
2511
+ */
2512
+ type BlockContent = BlockContentMap[keyof BlockContentMap];
2513
+ /**
2514
+ * Registry of all mdast nodes that can occur where {@link BlockContent} is
2515
+ * expected.
2516
+ *
2517
+ * This interface can be augmented to register custom node types:
2518
+ *
2519
+ * ```ts
2520
+ * declare module 'mdast' {
2521
+ * interface BlockContentMap {
2522
+ * // Allow using MDX ESM nodes defined by `remark-mdx`.
2523
+ * mdxjsEsm: MdxjsEsm;
2524
+ * }
2525
+ * }
2526
+ * ```
2527
+ *
2528
+ * For a union of all block content, see {@link RootContent}.
2529
+ */
2530
+ interface BlockContentMap {
2531
+ blockquote: Blockquote;
2532
+ code: Code;
2533
+ heading: Heading;
2534
+ html: Html;
2535
+ list: List;
2536
+ paragraph: Paragraph;
2537
+ table: Table;
2538
+ thematicBreak: ThematicBreak;
2539
+ }
2540
+ /**
2541
+ * Union of registered mdast nodes that can occur where definition content is
2542
+ * expected.
2543
+ *
2544
+ * To register custom mdast nodes, add them to {@link DefinitionContentMap}.
2545
+ * They will be automatically added here.
2546
+ */
2547
+ type DefinitionContent = DefinitionContentMap[keyof DefinitionContentMap];
2548
+ /**
2549
+ * Registry of all mdast nodes that can occur where {@link DefinitionContent}
2550
+ * is expected.
2551
+ *
2552
+ * This interface can be augmented to register custom node types:
2553
+ *
2554
+ * ```ts
2555
+ * declare module 'mdast' {
2556
+ * interface DefinitionContentMap {
2557
+ * custom: Custom;
2558
+ * }
2559
+ * }
2560
+ * ```
2561
+ *
2562
+ * For a union of all definition content, see {@link RootContent}.
2563
+ */
2564
+ interface DefinitionContentMap {
2565
+ definition: Definition;
2566
+ footnoteDefinition: FootnoteDefinition;
2567
+ }
2568
+ /**
2569
+ * Union of registered mdast nodes that can occur where list content is
2570
+ * expected.
2571
+ *
2572
+ * To register custom mdast nodes, add them to {@link ListContentMap}.
2573
+ * They will be automatically added here.
2574
+ */
2575
+ type ListContent = ListContentMap[keyof ListContentMap];
2576
+ /**
2577
+ * Registry of all mdast nodes that can occur where {@link ListContent}
2578
+ * is expected.
2579
+ *
2580
+ * This interface can be augmented to register custom node types:
2581
+ *
2582
+ * ```ts
2583
+ * declare module 'mdast' {
2584
+ * interface ListContentMap {
2585
+ * custom: Custom;
2586
+ * }
2587
+ * }
2588
+ * ```
2589
+ *
2590
+ * For a union of all list content, see {@link RootContent}.
2591
+ */
2592
+ interface ListContentMap {
2593
+ listItem: ListItem;
2594
+ }
2595
+ /**
2596
+ * Union of registered mdast nodes that can occur where phrasing content is
2597
+ * expected.
2598
+ *
2599
+ * To register custom mdast nodes, add them to {@link PhrasingContentMap}.
2600
+ * They will be automatically added here.
2601
+ */
2602
+ type PhrasingContent = PhrasingContentMap[keyof PhrasingContentMap];
2603
+ /**
2604
+ * Registry of all mdast nodes that can occur where {@link PhrasingContent}
2605
+ * is expected.
2606
+ *
2607
+ * This interface can be augmented to register custom node types:
2608
+ *
2609
+ * ```ts
2610
+ * declare module 'mdast' {
2611
+ * interface PhrasingContentMap {
2612
+ * // Allow using MDX JSX (text) nodes defined by `remark-mdx`.
2613
+ * mdxJsxTextElement: MDXJSXTextElement;
2614
+ * }
2615
+ * }
2616
+ * ```
2617
+ *
2618
+ * For a union of all phrasing content, see {@link RootContent}.
2619
+ */
2620
+ interface PhrasingContentMap {
2621
+ break: Break;
2622
+ delete: Delete;
2623
+ emphasis: Emphasis;
2624
+ footnoteReference: FootnoteReference;
2625
+ html: Html;
2626
+ image: Image;
2627
+ imageReference: ImageReference;
2628
+ inlineCode: InlineCode;
2629
+ link: Link;
2630
+ linkReference: LinkReference;
2631
+ strong: Strong;
2632
+ text: Text;
2633
+ }
2634
+ /**
2635
+ * Union of registered mdast nodes that can occur in {@link Root}.
2636
+ *
2637
+ * To register custom mdast nodes, add them to {@link RootContentMap}.
2638
+ * They will be automatically added here.
2639
+ */
2640
+ type RootContent = RootContentMap[keyof RootContentMap];
2641
+ /**
2642
+ * Registry of all mdast nodes that can occur as children of {@link Root}.
2643
+ *
2644
+ * > **Note**: {@link Root} does not need to be an entire document.
2645
+ * > it can also be a fragment.
2646
+ *
2647
+ * This interface can be augmented to register custom node types:
2648
+ *
2649
+ * ```ts
2650
+ * declare module 'mdast' {
2651
+ * interface RootContentMap {
2652
+ * // Allow using toml nodes defined by `remark-frontmatter`.
2653
+ * toml: TOML;
2654
+ * }
2655
+ * }
2656
+ * ```
2657
+ *
2658
+ * For a union of all {@link Root} children, see {@link RootContent}.
2659
+ */
2660
+ interface RootContentMap {
2661
+ blockquote: Blockquote;
2662
+ break: Break;
2663
+ code: Code;
2664
+ definition: Definition;
2665
+ delete: Delete;
2666
+ emphasis: Emphasis;
2667
+ footnoteDefinition: FootnoteDefinition;
2668
+ footnoteReference: FootnoteReference;
2669
+ heading: Heading;
2670
+ html: Html;
2671
+ image: Image;
2672
+ imageReference: ImageReference;
2673
+ inlineCode: InlineCode;
2674
+ link: Link;
2675
+ linkReference: LinkReference;
2676
+ list: List;
2677
+ listItem: ListItem;
2678
+ paragraph: Paragraph;
2679
+ strong: Strong;
2680
+ table: Table;
2681
+ tableCell: TableCell;
2682
+ tableRow: TableRow;
2683
+ text: Text;
2684
+ thematicBreak: ThematicBreak;
2685
+ yaml: Yaml;
2686
+ }
2687
+ /**
2688
+ * Union of registered mdast nodes that can occur where row content is
2689
+ * expected.
2690
+ *
2691
+ * To register custom mdast nodes, add them to {@link RowContentMap}.
2692
+ * They will be automatically added here.
2693
+ */
2694
+ type RowContent = RowContentMap[keyof RowContentMap];
2695
+ /**
2696
+ * Registry of all mdast nodes that can occur where {@link RowContent}
2697
+ * is expected.
2698
+ *
2699
+ * This interface can be augmented to register custom node types:
2700
+ *
2701
+ * ```ts
2702
+ * declare module 'mdast' {
2703
+ * interface RowContentMap {
2704
+ * custom: Custom;
2705
+ * }
2706
+ * }
2707
+ * ```
2708
+ *
2709
+ * For a union of all row content, see {@link RootContent}.
2710
+ */
2711
+ interface RowContentMap {
2712
+ tableCell: TableCell;
2713
+ }
2714
+ /**
2715
+ * Union of registered mdast nodes that can occur where table content is
2716
+ * expected.
2717
+ *
2718
+ * To register custom mdast nodes, add them to {@link TableContentMap}.
2719
+ * They will be automatically added here.
2720
+ */
2721
+ type TableContent = TableContentMap[keyof TableContentMap];
2722
+ /**
2723
+ * Registry of all mdast nodes that can occur where {@link TableContent}
2724
+ * is expected.
2725
+ *
2726
+ * This interface can be augmented to register custom node types:
2727
+ *
2728
+ * ```ts
2729
+ * declare module 'mdast' {
2730
+ * interface TableContentMap {
2731
+ * custom: Custom;
2732
+ * }
2733
+ * }
2734
+ * ```
2735
+ *
2736
+ * For a union of all table content, see {@link RootContent}.
2737
+ */
2738
+ interface TableContentMap {
2739
+ tableRow: TableRow;
2740
+ }
2741
+ // ## Abstract nodes
2742
+ /**
2743
+ * Abstract mdast node that contains the smallest possible value.
2744
+ *
2745
+ * This interface is supposed to be extended if you make custom mdast nodes.
2746
+ *
2747
+ * For a union of all registered mdast literals, see {@link Literals}.
2748
+ */
2749
+ interface Literal extends Node {
2750
+ /**
2751
+ * Plain-text value.
2752
+ */
2753
+ value: string;
2754
+ }
2755
+ /**
2756
+ * Abstract mdast node.
2757
+ *
2758
+ * This interface is supposed to be extended.
2759
+ * If you can use {@link Literal} or {@link Parent}, you should.
2760
+ * But for example in markdown, a thematic break (`***`) is neither literal nor
2761
+ * parent, but still a node.
2762
+ *
2763
+ * To register custom mdast nodes, add them to {@link RootContentMap} and other
2764
+ * places where relevant (such as {@link ElementContentMap}).
2765
+ *
2766
+ * For a union of all registered mdast nodes, see {@link Nodes}.
2767
+ */
2768
+ interface Node extends Node$1 {
2769
+ /**
2770
+ * Info from the ecosystem.
2771
+ */
2772
+ data?: Data | undefined;
2773
+ }
2774
+ /**
2775
+ * Abstract mdast node that contains other mdast nodes (*children*).
2776
+ *
2777
+ * This interface is supposed to be extended if you make custom mdast nodes.
2778
+ *
2779
+ * For a union of all registered mdast parents, see {@link Parents}.
2780
+ */
2781
+ interface Parent extends Node {
2782
+ /**
2783
+ * List of children.
2784
+ */
2785
+ children: RootContent[];
2786
+ }
2787
+ // ## Concrete nodes
2788
+ /**
2789
+ * Markdown block quote.
2790
+ */
2791
+ interface Blockquote extends Parent {
2792
+ /**
2793
+ * Node type of mdast block quote.
2794
+ */
2795
+ type: "blockquote";
2796
+ /**
2797
+ * Children of block quote.
2798
+ */
2799
+ children: Array<BlockContent | DefinitionContent>;
2800
+ /**
2801
+ * Data associated with the mdast block quote.
2802
+ */
2803
+ data?: BlockquoteData | undefined;
2804
+ }
2805
+ /**
2806
+ * Info associated with mdast block quote nodes by the ecosystem.
2807
+ */
2808
+ interface BlockquoteData extends Data {}
2809
+ /**
2810
+ * Markdown break.
2811
+ */
2812
+ interface Break extends Node {
2813
+ /**
2814
+ * Node type of mdast break.
2815
+ */
2816
+ type: "break";
2817
+ /**
2818
+ * Data associated with the mdast break.
2819
+ */
2820
+ data?: BreakData | undefined;
2821
+ }
2822
+ /**
2823
+ * Info associated with mdast break nodes by the ecosystem.
2824
+ */
2825
+ interface BreakData extends Data {}
2826
+ /**
2827
+ * Markdown code (flow) (block).
2828
+ */
2829
+ interface Code extends Literal {
2830
+ /**
2831
+ * Node type of mdast code (flow).
2832
+ */
2833
+ type: "code";
2834
+ /**
2835
+ * Language of computer code being marked up.
2836
+ */
2837
+ lang?: string | null | undefined;
2838
+ /**
2839
+ * Custom information relating to the node.
2840
+ *
2841
+ * If the lang field is present, a meta field can be present.
2842
+ */
2843
+ meta?: string | null | undefined;
2844
+ /**
2845
+ * Data associated with the mdast code (flow).
2846
+ */
2847
+ data?: CodeData | undefined;
2848
+ }
2849
+ /**
2850
+ * Info associated with mdast code (flow) (block) nodes by the ecosystem.
2851
+ */
2852
+ interface CodeData extends Data {}
2853
+ /**
2854
+ * Markdown definition.
2855
+ */
2856
+ interface Definition extends Node, Association, Resource {
2857
+ /**
2858
+ * Node type of mdast definition.
2859
+ */
2860
+ type: "definition";
2861
+ /**
2862
+ * Data associated with the mdast definition.
2863
+ */
2864
+ data?: DefinitionData | undefined;
2865
+ }
2866
+ /**
2867
+ * Info associated with mdast definition nodes by the ecosystem.
2868
+ */
2869
+ interface DefinitionData extends Data {}
2870
+ /**
2871
+ * Markdown GFM delete (strikethrough).
2872
+ */
2873
+ interface Delete extends Parent {
2874
+ /**
2875
+ * Node type of mdast GFM delete.
2876
+ */
2877
+ type: "delete";
2878
+ /**
2879
+ * Children of GFM delete.
2880
+ */
2881
+ children: PhrasingContent[];
2882
+ /**
2883
+ * Data associated with the mdast GFM delete.
2884
+ */
2885
+ data?: DeleteData | undefined;
2886
+ }
2887
+ /**
2888
+ * Info associated with mdast GFM delete nodes by the ecosystem.
2889
+ */
2890
+ interface DeleteData extends Data {}
2891
+ /**
2892
+ * Markdown emphasis.
2893
+ */
2894
+ interface Emphasis extends Parent {
2895
+ /**
2896
+ * Node type of mdast emphasis.
2897
+ */
2898
+ type: "emphasis";
2899
+ /**
2900
+ * Children of emphasis.
2901
+ */
2902
+ children: PhrasingContent[];
2903
+ /**
2904
+ * Data associated with the mdast emphasis.
2905
+ */
2906
+ data?: EmphasisData | undefined;
2907
+ }
2908
+ /**
2909
+ * Info associated with mdast emphasis nodes by the ecosystem.
2910
+ */
2911
+ interface EmphasisData extends Data {}
2912
+ /**
2913
+ * Markdown GFM footnote definition.
2914
+ */
2915
+ interface FootnoteDefinition extends Parent, Association {
2916
+ /**
2917
+ * Node type of mdast GFM footnote definition.
2918
+ */
2919
+ type: "footnoteDefinition";
2920
+ /**
2921
+ * Children of GFM footnote definition.
2922
+ */
2923
+ children: Array<BlockContent | DefinitionContent>;
2924
+ /**
2925
+ * Data associated with the mdast GFM footnote definition.
2926
+ */
2927
+ data?: FootnoteDefinitionData | undefined;
2928
+ }
2929
+ /**
2930
+ * Info associated with mdast GFM footnote definition nodes by the ecosystem.
2931
+ */
2932
+ interface FootnoteDefinitionData extends Data {}
2933
+ /**
2934
+ * Markdown GFM footnote reference.
2935
+ */
2936
+ interface FootnoteReference extends Association, Node {
2937
+ /**
2938
+ * Node type of mdast GFM footnote reference.
2939
+ */
2940
+ type: "footnoteReference";
2941
+ /**
2942
+ * Data associated with the mdast GFM footnote reference.
2943
+ */
2944
+ data?: FootnoteReferenceData | undefined;
2945
+ }
2946
+ /**
2947
+ * Info associated with mdast GFM footnote reference nodes by the ecosystem.
2948
+ */
2949
+ interface FootnoteReferenceData extends Data {}
2950
+ /**
2951
+ * Markdown heading.
2952
+ */
2953
+ interface Heading extends Parent {
2954
+ /**
2955
+ * Node type of mdast heading.
2956
+ */
2957
+ type: "heading";
2958
+ /**
2959
+ * Heading rank.
2960
+ *
2961
+ * A value of `1` is said to be the highest rank and `6` the lowest.
2962
+ */
2963
+ depth: 1 | 2 | 3 | 4 | 5 | 6;
2964
+ /**
2965
+ * Children of heading.
2966
+ */
2967
+ children: PhrasingContent[];
2968
+ /**
2969
+ * Data associated with the mdast heading.
2970
+ */
2971
+ data?: HeadingData | undefined;
2972
+ }
2973
+ /**
2974
+ * Info associated with mdast heading nodes by the ecosystem.
2975
+ */
2976
+ interface HeadingData extends Data {}
2977
+ /**
2978
+ * Markdown HTML.
2979
+ */
2980
+ interface Html extends Literal {
2981
+ /**
2982
+ * Node type of mdast HTML.
2983
+ */
2984
+ type: "html";
2985
+ /**
2986
+ * Data associated with the mdast HTML.
2987
+ */
2988
+ data?: HtmlData | undefined;
2989
+ }
2990
+ /**
2991
+ * Info associated with mdast HTML nodes by the ecosystem.
2992
+ */
2993
+ interface HtmlData extends Data {}
2994
+ /**
2995
+ * Markdown image.
2996
+ */
2997
+ interface Image extends Alternative, Node, Resource {
2998
+ /**
2999
+ * Node type of mdast image.
3000
+ */
3001
+ type: "image";
3002
+ /**
3003
+ * Data associated with the mdast image.
3004
+ */
3005
+ data?: ImageData | undefined;
3006
+ }
3007
+ /**
3008
+ * Info associated with mdast image nodes by the ecosystem.
3009
+ */
3010
+ interface ImageData extends Data {}
3011
+ /**
3012
+ * Markdown image reference.
3013
+ */
3014
+ interface ImageReference extends Alternative, Node, Reference {
3015
+ /**
3016
+ * Node type of mdast image reference.
3017
+ */
3018
+ type: "imageReference";
3019
+ /**
3020
+ * Data associated with the mdast image reference.
3021
+ */
3022
+ data?: ImageReferenceData | undefined;
3023
+ }
3024
+ /**
3025
+ * Info associated with mdast image reference nodes by the ecosystem.
3026
+ */
3027
+ interface ImageReferenceData extends Data {}
3028
+ /**
3029
+ * Markdown code (text) (inline).
3030
+ */
3031
+ interface InlineCode extends Literal {
3032
+ /**
3033
+ * Node type of mdast code (text).
3034
+ */
3035
+ type: "inlineCode";
3036
+ /**
3037
+ * Data associated with the mdast code (text).
3038
+ */
3039
+ data?: InlineCodeData | undefined;
3040
+ }
3041
+ /**
3042
+ * Info associated with mdast code (text) (inline) nodes by the ecosystem.
3043
+ */
3044
+ interface InlineCodeData extends Data {}
3045
+ /**
3046
+ * Markdown link.
3047
+ */
3048
+ interface Link extends Parent, Resource {
3049
+ /**
3050
+ * Node type of mdast link.
3051
+ */
3052
+ type: "link";
3053
+ /**
3054
+ * Children of link.
3055
+ */
3056
+ children: PhrasingContent[];
3057
+ /**
3058
+ * Data associated with the mdast link.
3059
+ */
3060
+ data?: LinkData | undefined;
3061
+ }
3062
+ /**
3063
+ * Info associated with mdast link nodes by the ecosystem.
3064
+ */
3065
+ interface LinkData extends Data {}
3066
+ /**
3067
+ * Markdown link reference.
3068
+ */
3069
+ interface LinkReference extends Parent, Reference {
3070
+ /**
3071
+ * Node type of mdast link reference.
3072
+ */
3073
+ type: "linkReference";
3074
+ /**
3075
+ * Children of link reference.
3076
+ */
3077
+ children: PhrasingContent[];
3078
+ /**
3079
+ * Data associated with the mdast link reference.
3080
+ */
3081
+ data?: LinkReferenceData | undefined;
3082
+ }
3083
+ /**
3084
+ * Info associated with mdast link reference nodes by the ecosystem.
3085
+ */
3086
+ interface LinkReferenceData extends Data {}
3087
+ /**
3088
+ * Markdown list.
3089
+ */
3090
+ interface List extends Parent {
3091
+ /**
3092
+ * Node type of mdast list.
3093
+ */
3094
+ type: "list";
3095
+ /**
3096
+ * Whether the items have been intentionally ordered (when `true`), or that
3097
+ * the order of items is not important (when `false` or not present).
3098
+ */
3099
+ ordered?: boolean | null | undefined;
3100
+ /**
3101
+ * The starting number of the list, when the `ordered` field is `true`.
3102
+ */
3103
+ start?: number | null | undefined;
3104
+ /**
3105
+ * Whether one or more of the children are separated with a blank line from
3106
+ * its siblings (when `true`), or not (when `false` or not present).
3107
+ */
3108
+ spread?: boolean | null | undefined;
3109
+ /**
3110
+ * Children of list.
3111
+ */
3112
+ children: ListContent[];
3113
+ /**
3114
+ * Data associated with the mdast list.
3115
+ */
3116
+ data?: ListData | undefined;
3117
+ }
3118
+ /**
3119
+ * Info associated with mdast list nodes by the ecosystem.
3120
+ */
3121
+ interface ListData extends Data {}
3122
+ /**
3123
+ * Markdown list item.
3124
+ */
3125
+ interface ListItem extends Parent {
3126
+ /**
3127
+ * Node type of mdast list item.
3128
+ */
3129
+ type: "listItem";
3130
+ /**
3131
+ * Whether the item is a tasklist item (when `boolean`).
3132
+ *
3133
+ * When `true`, the item is complete.
3134
+ * When `false`, the item is incomplete.
3135
+ */
3136
+ checked?: boolean | null | undefined;
3137
+ /**
3138
+ * Whether one or more of the children are separated with a blank line from
3139
+ * its siblings (when `true`), or not (when `false` or not present).
3140
+ */
3141
+ spread?: boolean | null | undefined;
3142
+ /**
3143
+ * Children of list item.
3144
+ */
3145
+ children: Array<BlockContent | DefinitionContent>;
3146
+ /**
3147
+ * Data associated with the mdast list item.
3148
+ */
3149
+ data?: ListItemData | undefined;
3150
+ }
3151
+ /**
3152
+ * Info associated with mdast list item nodes by the ecosystem.
3153
+ */
3154
+ interface ListItemData extends Data {}
3155
+ /**
3156
+ * Markdown paragraph.
3157
+ */
3158
+ interface Paragraph extends Parent {
3159
+ /**
3160
+ * Node type of mdast paragraph.
3161
+ */
3162
+ type: "paragraph";
3163
+ /**
3164
+ * Children of paragraph.
3165
+ */
3166
+ children: PhrasingContent[];
3167
+ /**
3168
+ * Data associated with the mdast paragraph.
3169
+ */
3170
+ data?: ParagraphData | undefined;
3171
+ }
3172
+ /**
3173
+ * Info associated with mdast paragraph nodes by the ecosystem.
3174
+ */
3175
+ interface ParagraphData extends Data {}
3176
+ /**
3177
+ * Markdown strong.
3178
+ */
3179
+ interface Strong extends Parent {
3180
+ /**
3181
+ * Node type of mdast strong.
3182
+ */
3183
+ type: "strong";
3184
+ /**
3185
+ * Children of strong.
3186
+ */
3187
+ children: PhrasingContent[];
3188
+ /**
3189
+ * Data associated with the mdast strong.
3190
+ */
3191
+ data?: StrongData | undefined;
3192
+ }
3193
+ /**
3194
+ * Info associated with mdast strong nodes by the ecosystem.
3195
+ */
3196
+ interface StrongData extends Data {}
3197
+ /**
3198
+ * Markdown GFM table.
3199
+ */
3200
+ interface Table extends Parent {
3201
+ /**
3202
+ * Node type of mdast GFM table.
3203
+ */
3204
+ type: "table";
3205
+ /**
3206
+ * How cells in columns are aligned.
3207
+ */
3208
+ align?: AlignType[] | null | undefined;
3209
+ /**
3210
+ * Children of GFM table.
3211
+ */
3212
+ children: TableContent[];
3213
+ /**
3214
+ * Data associated with the mdast GFM table.
3215
+ */
3216
+ data?: TableData | undefined;
3217
+ }
3218
+ /**
3219
+ * Info associated with mdast GFM table nodes by the ecosystem.
3220
+ */
3221
+ interface TableData extends Data {}
3222
+ /**
3223
+ * Markdown GFM table row.
3224
+ */
3225
+ interface TableRow extends Parent {
3226
+ /**
3227
+ * Node type of mdast GFM table row.
3228
+ */
3229
+ type: "tableRow";
3230
+ /**
3231
+ * Children of GFM table row.
3232
+ */
3233
+ children: RowContent[];
3234
+ /**
3235
+ * Data associated with the mdast GFM table row.
3236
+ */
3237
+ data?: TableRowData | undefined;
3238
+ }
3239
+ /**
3240
+ * Info associated with mdast GFM table row nodes by the ecosystem.
3241
+ */
3242
+ interface TableRowData extends Data {}
3243
+ /**
3244
+ * Markdown GFM table cell.
3245
+ */
3246
+ interface TableCell extends Parent {
3247
+ /**
3248
+ * Node type of mdast GFM table cell.
3249
+ */
3250
+ type: "tableCell";
3251
+ /**
3252
+ * Children of GFM table cell.
3253
+ */
3254
+ children: PhrasingContent[];
3255
+ /**
3256
+ * Data associated with the mdast GFM table cell.
3257
+ */
3258
+ data?: TableCellData | undefined;
3259
+ }
3260
+ /**
3261
+ * Info associated with mdast GFM table cell nodes by the ecosystem.
3262
+ */
3263
+ interface TableCellData extends Data {}
3264
+ /**
3265
+ * Markdown text.
3266
+ */
3267
+ interface Text extends Literal {
3268
+ /**
3269
+ * Node type of mdast text.
3270
+ */
3271
+ type: "text";
3272
+ /**
3273
+ * Data associated with the mdast text.
3274
+ */
3275
+ data?: TextData | undefined;
3276
+ }
3277
+ /**
3278
+ * Info associated with mdast text nodes by the ecosystem.
3279
+ */
3280
+ interface TextData extends Data {}
3281
+ /**
3282
+ * Markdown thematic break (horizontal rule).
3283
+ */
3284
+ interface ThematicBreak extends Node {
3285
+ /**
3286
+ * Node type of mdast thematic break.
3287
+ */
3288
+ type: "thematicBreak";
3289
+ /**
3290
+ * Data associated with the mdast thematic break.
3291
+ */
3292
+ data?: ThematicBreakData | undefined;
3293
+ }
3294
+ /**
3295
+ * Info associated with mdast thematic break nodes by the ecosystem.
3296
+ */
3297
+ interface ThematicBreakData extends Data {}
3298
+ /**
3299
+ * Markdown YAML.
3300
+ */
3301
+ interface Yaml extends Literal {
3302
+ /**
3303
+ * Node type of mdast YAML.
3304
+ */
3305
+ type: "yaml";
3306
+ /**
3307
+ * Data associated with the mdast YAML.
3308
+ */
3309
+ data?: YamlData | undefined;
3310
+ }
3311
+ /**
3312
+ * Info associated with mdast YAML nodes by the ecosystem.
3313
+ */
3314
+ interface YamlData extends Data {}
3315
+ /**
3316
+ * Reports what a parsed input's records yield to the conversion pipeline, so it
3317
+ * classifies an error the parser throws while aggregation consumes them the
3318
+ * same way as one it throws before returning, and rejects an input with no
3319
+ * records.
3320
+ */
3321
+ type RecordReader = {
3322
+ /** Returns the lazily consumed {@link records}, noting each it yields. */
3323
+ records: <Value>(records: Iterable<Value>) => Iterable<Value>;
3324
+ /** Returns a lazily consumed {@link iterable} that yields no records. */
3325
+ iterable: <Value>(iterable: Iterable<Value>) => Iterable<Value>;
3326
+ /** Notes {@link count} records the parser read before returning. */
3327
+ parsed: (count: number) => void;
3328
+ };
3329
+ type EntityLocation = {
3330
+ location: SourceLocation;
3331
+ inferable: boolean;
3332
+ };
3333
+ type AggregatedCallGraph = {
3334
+ type: `call-graph`;
3335
+ /** @see {@link AggregatedCallStackProfile.context} */
3336
+ context: ProfileToMdContext;
3337
+ metrics: Metric[];
3338
+ /**
3339
+ * For each metric in {@link AggregatedCallGraph.metrics}, the whole
3340
+ * input's recorded cost: the sum of every function's self values.
3341
+ */
3342
+ totalValues: Float64Array;
3343
+ /** Function category to the summed self values of that category. */
3344
+ categoryToMetrics: Map<FunctionCategory, AggregatedCallGraphCategoryMetrics>;
3345
+ functions: AggregatedCallGraphFunction[];
3346
+ };
3347
+ type AggregatedCallGraphCategoryMetrics = {
3348
+ /**
3349
+ * For each metric in {@link AggregatedCallGraph.metrics}, the summed self
3350
+ * values of functions with this category.
3351
+ */
3352
+ values: Float64Array;
3353
+ };
3354
+ type AggregatedCallGraphFunction = {
3355
+ type: `function`;
3356
+ /** An index that uniquely identifies this function. */
3357
+ id: number;
3358
+ name: string;
3359
+ /** Where the function was defined. */
3360
+ location?: SourceLocation;
3361
+ category: FunctionCategory;
3362
+ /**
3363
+ * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
3364
+ * directly in the function's body, excluding its callees.
3365
+ */
3366
+ selfValues: Float64Array;
3367
+ /**
3368
+ * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
3369
+ * in the function's body and all its callees: its self values plus its
3370
+ * outgoing arcs' total values, excluding the arcs to functions in its own
3371
+ * recursion cycle, which re-count the same work.
3372
+ */
3373
+ totalValues: Float64Array;
3374
+ /** 1-based line number to the self values recorded at that line. */
3375
+ lineToMetrics: Map<number, Float64Array>;
3376
+ /** Direct caller ID to the costs recorded during that caller's calls. */
3377
+ callerIdToMetrics: Map<number, AggregatedCallGraphCallerMetrics>;
3378
+ /** Direct callee ID to the costs recorded during calls to that callee. */
3379
+ calleeIdToMetrics: Map<number, AggregatedCallGraphCalleeMetrics>;
3380
+ };
3381
+ /** One function's recorded costs during calls from a given direct caller. */
3382
+ type AggregatedCallGraphCallerMetrics = {
3383
+ caller: AggregatedCallGraphFunction;
3384
+ /** The recorded number of calls, or `0` when the format records none. */
3385
+ callCount: number;
3386
+ /**
3387
+ * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
3388
+ * in the function and its callees during calls from this caller.
3389
+ */
3390
+ totalValues: Float64Array;
3391
+ };
3392
+ /** One function's recorded costs during its calls to a given direct callee. */
3393
+ type AggregatedCallGraphCalleeMetrics = {
3394
+ callee: AggregatedCallGraphFunction;
3395
+ /** The recorded number of calls, or `0` when the format records none. */
3396
+ callCount: number;
3397
+ /**
3398
+ * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
3399
+ * in the callee and its callees during this function's calls to it.
3400
+ */
3401
+ totalValues: Float64Array;
3402
+ };
3403
+ declare class CallGraphAggregator implements InputAggregator<AggregatedCallGraph> {
3404
+ #private;
3405
+ constructor(graph: CallGraph);
3406
+ detectOrigin(detector: OriginDetector): void;
3407
+ aggregate(options: AggregationProfileToMdOptions, context: ProfileToMdContext): AggregatedCallGraph;
3408
+ }
3409
+ /** What an entity's instances retain, alone or together. */
3410
+ type EntityRetention = {
3411
+ /**
3412
+ * The summed self size of every node that becomes unreachable from the GC
3413
+ * root once every instance of the entity is garbage collected.
3414
+ */
3415
+ retainedSize: number;
3416
+ /**
3417
+ * The instances no other node the entity retains dominates. Their retained
3418
+ * nodes are disjoint, and contain those of the entity's instances not listed.
3419
+ */
3420
+ outermostInstanceOrdinals: number[];
3421
+ /**
3422
+ * The nodes other than instances that the entity retains and whose immediate
3423
+ * dominators it does not. No single instance dominates one, so at least two
3424
+ * instances are on the paths to it.
3425
+ */
3426
+ jointlyRetainedOrdinals: number[];
3427
+ };
3428
+ type AggregatedHeapSnapshot = {
3429
+ type: `heap-snapshot`;
3430
+ /**
3431
+ * The context this snapshot was aggregated under. Diffed sides that resolved
3432
+ * different origins can normalize match keys differently and miss matches.
3433
+ */
3434
+ context: ProfileToMdContext;
3435
+ /** The summed self sizes of every node in the snapshot. */
3436
+ heldSize: number;
3437
+ nodeCount: number;
3438
+ edgeCount: number;
3439
+ nodeCategoryToStats: Map<HeapSnapshotNodeCategory, NodeCategoryStats>;
3440
+ constructors: AggregatedHeapSnapshotConstructor[];
3441
+ functions: AggregatedHeapSnapshotFunction[];
3442
+ strings: AggregatedHeapSnapshotString[];
3443
+ /**
3444
+ * What each given set of distinct instance ordinals retains, alone or
3445
+ * together. No node may be in two sets.
3446
+ */
3447
+ retentionsOf: (instanceOrdinalSets: readonly (readonly number[])[]) => EntityRetention[];
3448
+ /**
3449
+ * The first hop of a node's retainer path along its dominators, or
3450
+ * `undefined` for the GC root, a node without predecessors, and an
3451
+ * unreachable node. Following each hop's
3452
+ * {@link RetainerHop.dominatorOrdinal} ends at one of them.
3453
+ */
3454
+ retainerHopOf: (nodeOrdinal: number) => RetainerHop | undefined;
3455
+ /** The node as a retainer path step shows it. */
3456
+ retainerOf: (nodeOrdinal: number) => RetainerNode;
3457
+ nodeOf: (nodeOrdinal: number, options: FormattingProfileToMdOptions) => AggregatedHeapSnapshotNode;
3458
+ /** The nodes the node dominates. */
3459
+ retainedNodesOf: (nodeOrdinal: number, options: FormattingProfileToMdOptions) => AggregatedHeapSnapshotNode[];
3460
+ /** Whether the node is a bookkeeping node that never points to user code. */
3461
+ isInternalNode: (nodeOrdinal: number) => boolean;
3462
+ };
3463
+ type NodeCategoryStats = {
3464
+ /** Bytes allocated directly for nodes in this category. */
3465
+ size: number;
3466
+ nodeCount: number;
3467
+ };
3468
+ type AggregatedHeapSnapshotConstructor = AggregatedHeapSnapshotEntity & {
3469
+ name: string;
3470
+ /**
3471
+ * What this constructor's instances hold: the category the origin assigns to
3472
+ * its class, falling back to the category holding the most of their self
3473
+ * size.
3474
+ */
3475
+ category: HeapSnapshotNodeCategory;
3476
+ instances: AggregatedHeapSnapshotNode[];
3477
+ } & EntityRetention;
3478
+ type AggregatedHeapSnapshotFunction = AggregatedHeapSnapshotEntity & {
3479
+ /**
3480
+ * The ordinal of the instance with the largest individual retained size,
3481
+ * which is the instance the function's rows show.
3482
+ */
3483
+ id: number;
3484
+ name: string;
3485
+ /** What this function holds, taken from the instance {@link id} identifies. */
3486
+ category: HeapSnapshotNodeCategory;
3487
+ instanceOrdinals: number[];
3488
+ } & EntityRetention;
3489
+ type AggregatedHeapSnapshotString = AggregatedHeapSnapshotEntity & {
3490
+ /** What this string holds: its representation in the heap. */
3491
+ category: HeapSnapshotNodeCategory;
3492
+ };
3493
+ /** A constructor, function, or string, aggregating the nodes it identifies. */
3494
+ type AggregatedHeapSnapshotEntity = {
3495
+ type: `node`;
3496
+ /** The ordinal of one of the entity's nodes. */
3497
+ id: number;
3498
+ name?: string;
3499
+ /**
3500
+ * The file reference the {@link name} parses as, when it is URL-shaped
3501
+ * (e.g. a V8 module namespace object named by its file URL). Formatting
3502
+ * shows it relative to the base URL in place of the raw name.
3503
+ */
3504
+ nameLocation?: FileReference;
3505
+ /** Bytes allocated directly for the entity's nodes. */
3506
+ selfSize: number;
3507
+ category: HeapSnapshotNodeCategory;
3508
+ /**
3509
+ * Bytes allocated for the entity's nodes, as well as all nodes that would be
3510
+ * freed if they were garbage collected. A lower bound on a graph that exhausts
3511
+ * the budget of {@link computeEntityRetentions}.
3512
+ */
3513
+ retainedSize: number;
3514
+ location?: SourceLocation;
3515
+ };
3516
+ /** A constructor's instance, or a node an instance retains. */
3517
+ type AggregatedHeapSnapshotNode = {
3518
+ type: `node`;
3519
+ /** The node's ordinal. */
3520
+ id: number;
3521
+ /** The node's label, which for an instance is its constructor's name. */
3522
+ name: string;
3523
+ /** Bytes allocated directly for this node. */
3524
+ selfSize: number;
3525
+ category: HeapSnapshotNodeCategory;
3526
+ /**
3527
+ * Bytes allocated for this node, as well as all nodes that would be freed if
3528
+ * the node were garbage collected.
3529
+ */
3530
+ retainedSize: number;
3531
+ /** The location of the constructor or function the node is an instance of. */
3532
+ location?: SourceLocation;
3533
+ };
3534
+ /**
3535
+ * A retainer path step's edge. A path that groups the elements of an array
3536
+ * records an element edge as any element. A step whose retainer holds no edge
3537
+ * to the node, which it retains through the node's several retainers, records
3538
+ * several retainers. On a step to a node that an entity's instances retain only
3539
+ * together, it records that every path passes through an instance of the entity.
3540
+ */
3541
+ type RetainerPathEdge = RetainerEdge | {
3542
+ type: `any-element`;
3543
+ } | {
3544
+ type: `several-retainers`;
3545
+ } | {
3546
+ type: `several-instance-paths`;
3547
+ entityName: string;
3548
+ };
3549
+ /**
3550
+ * Aggregates one {@link HeapSnapshot}.
3551
+ *
3552
+ * The constructor computes everything that needs no origin, including the
3553
+ * entries origin detection reads. {@link aggregate} categorizes under the
3554
+ * resolved origin.
3555
+ */
3556
+ declare class HeapSnapshotAggregator implements InputAggregator<AggregatedHeapSnapshot> {
3557
+ #private;
3558
+ constructor(snapshot: HeapSnapshot);
3559
+ detectOrigin(detector: OriginDetector): void;
3560
+ aggregate(options: AggregationProfileToMdOptions, context: ProfileToMdContext): AggregatedHeapSnapshot;
3561
+ }
3562
+ /** A node's immediate dominator, and the dominator's edge to the node. */
3563
+ type RetainerHop = {
3564
+ dominatorOrdinal: number;
3565
+ edge: RetainerPathEdge;
3566
+ /** Whether the dominator is an internal node. */
3567
+ internal: boolean;
3568
+ };
3569
+ type AggregatedTrace = {
3570
+ type: `trace`;
3571
+ /** @see {@link AggregatedCallStackProfile.context} */
3572
+ context: ProfileToMdContext;
3573
+ /** The number of spans and instants recorded. */
3574
+ eventCount: number;
3575
+ /**
3576
+ * The milliseconds from the earliest time any event or reading records to
3577
+ * the latest, or `undefined` when the input times none of them.
3578
+ */
3579
+ duration: number | undefined;
3580
+ /**
3581
+ * Whether any thread span is nested in another, so self and total time
3582
+ * differ.
3583
+ */
3584
+ hasNesting: boolean;
3585
+ hasCpuTime: boolean;
3586
+ threads: AggregatedTraceThread[];
3587
+ /**
3588
+ * Category to the summed self time and count of that category's events. A
3589
+ * span nested in a span of an exclusive category counts toward that
3590
+ * category.
3591
+ */
3592
+ categoryToStats: Map<TraceEventCategory, AggregatedTraceStats>;
3593
+ spans: AggregatedTraceSpan[];
3594
+ instants: AggregatedTraceInstant[];
3595
+ gauges: AggregatedTraceGauge[];
3596
+ };
3597
+ /** A number of events and the milliseconds of span time they account for. */
3598
+ type AggregatedTraceStats = {
3599
+ time: number;
3600
+ count: number;
3601
+ };
3602
+ /**
3603
+ * The events sharing one of an entity's breakdown keys, with the longest one's
3604
+ * milliseconds.
3605
+ */
3606
+ type AggregatedTraceBreakdownStats = AggregatedTraceStats & {
3607
+ max: number;
3608
+ };
3609
+ type AggregatedTraceThread = AggregatedTraceStats & {
3610
+ /** An index that uniquely identifies this thread. */
3611
+ id: number;
3612
+ name: string;
3613
+ };
3614
+ /** Every span sharing a name. */
3615
+ type AggregatedTraceSpan = {
3616
+ type: `span`;
3617
+ /** An index that uniquely identifies this entity among spans and instants. */
3618
+ id: number;
3619
+ name: string;
3620
+ location?: undefined;
3621
+ category: TraceEventCategory;
3622
+ /**
3623
+ * Whether the spans are async spans, whose time is the time that elapsed.
3624
+ * An async span and a thread span sharing a name are two entities.
3625
+ */
3626
+ async: boolean;
3627
+ /** The number of spans, including those the input never ends. */
3628
+ count: number;
3629
+ /** The number of spans with a duration. */
3630
+ timedCount: number;
3631
+ cpuTimedCount: number;
3632
+ /**
3633
+ * The summed milliseconds within the spans, excluding their children. An
3634
+ * async span adds nothing, because its time is not a thread's.
3635
+ */
3636
+ selfTime: number;
3637
+ /** The milliseconds of the span with the most self time. */
3638
+ maxSelfTime: number;
3639
+ /**
3640
+ * The summed milliseconds within the spans, including their children. A
3641
+ * span nested in another of the same name adds nothing, because the outer
3642
+ * span's duration already includes it.
3643
+ */
3644
+ totalTime: number;
3645
+ /** The summed milliseconds of every span's duration, nested or not. */
3646
+ summedTime: number;
3647
+ /** The longest span's milliseconds. */
3648
+ maxTime: number;
3649
+ /** @see {@link selfTime}, in milliseconds of CPU time. */
3650
+ selfCpuTime: number;
3651
+ /** @see {@link maxSelfTime}, in milliseconds of CPU time. */
3652
+ maxSelfCpuTime: number;
3653
+ /** @see {@link summedTime}, in milliseconds of CPU time. */
3654
+ summedCpuTime: number;
3655
+ /** @see {@link maxTime}, in milliseconds of CPU time. */
3656
+ maxCpuTime: number;
3657
+ /** @see {@link totalTime}, in milliseconds of CPU time. */
3658
+ totalCpuTime: number;
3659
+ /** Attribute key to each of its string values' share of the spans. */
3660
+ attributeToValues: Map<string, Map<string, AggregatedTraceBreakdownStats>>;
3661
+ /** Attribute key to the amounts the spans record under it. */
3662
+ attributeToAmount: Map<string, AggregatedTraceAmount>;
3663
+ /** Thread ID to the spans recorded on that thread. */
3664
+ threadIdToStats: Map<number, AggregatedTraceBreakdownStats>;
3665
+ /** Parent span ID to the spans nested directly in a span of that name. */
3666
+ parentIdToStats: Map<number, AggregatedTraceBreakdownStats>;
3667
+ /**
3668
+ * Parent span ID to the spans nested directly in a span of that name, with
3669
+ * their self time.
3670
+ */
3671
+ parentIdToSelfStats: Map<number, AggregatedTraceBreakdownStats>;
3672
+ /** Child span ID to the spans of that name nested directly in these. */
3673
+ childIdToStats: Map<number, AggregatedTraceBreakdownStats>;
3674
+ instances: AggregatedTraceInstance[];
3675
+ };
3676
+ /** One span with a duration. */
3677
+ type AggregatedTraceInstance = {
3678
+ /** Milliseconds from the trace's start, or `undefined` for an untimed span. */
3679
+ start: number | undefined;
3680
+ time: number;
3681
+ /** The span's CPU time in milliseconds, when recorded. */
3682
+ cpuTime: number | undefined;
3683
+ threadId: number | undefined;
3684
+ attributes: readonly TraceAttribute[] | undefined;
3685
+ };
3686
+ /** The amounts events record under one attribute key. */
3687
+ type AggregatedTraceAmount = {
3688
+ metric: Metric;
3689
+ /** The number of events recording an amount, and their summed time. */
3690
+ count: number;
3691
+ time: number;
3692
+ total: number;
3693
+ max: number;
3694
+ };
3695
+ /** Every instant sharing a name. */
3696
+ type AggregatedTraceInstant = {
3697
+ type: `instant`;
3698
+ /** An index that uniquely identifies this entity among spans and instants. */
3699
+ id: number;
3700
+ name: string;
3701
+ location?: undefined;
3702
+ category: TraceEventCategory;
3703
+ count: number;
3704
+ /** Attribute key to the number of instants with each of its string values. */
3705
+ attributeToValues: Map<string, Map<string, AggregatedTraceBreakdownStats>>;
3706
+ /** Attribute key to the amounts the instants record under it. */
3707
+ attributeToAmount: Map<string, AggregatedTraceAmount>;
3708
+ /** Thread ID to the instants recorded on that thread. */
3709
+ threadIdToStats: Map<number, AggregatedTraceBreakdownStats>;
3710
+ };
3711
+ type AggregatedTraceEntity = AggregatedTraceSpan | AggregatedTraceInstant;
3712
+ type AggregatedTraceGaugeTiming = {
3713
+ /**
3714
+ * The milliseconds from the trace's start to the earliest reading at the
3715
+ * gauge's minimum.
3716
+ */
3717
+ minTime: number;
3718
+ /** @see {@link minTime}, for the earliest reading at the gauge's maximum. */
3719
+ maxTime: number;
3720
+ /** The mean weighted by the time from each reading to the next. */
3721
+ mean: number;
3722
+ };
3723
+ type AggregatedTraceGauge = {
3724
+ /** Unique among the gauges of its {@link thread}. */
3725
+ name: string;
3726
+ /** The name of the thread the gauge is a quantity of, if it is one's. */
3727
+ thread: string | undefined;
3728
+ metric: Metric;
3729
+ /** The number of readings. */
3730
+ count: number;
3731
+ min: number;
3732
+ max: number;
3733
+ /** The earliest reading's value, or the first one's when none is timed. */
3734
+ first: number;
3735
+ /** The latest reading's value, or the last one's when none is timed. */
3736
+ last: number;
3737
+ /** What the readings' times state, or `undefined` when they are untimed. */
3738
+ timing: AggregatedTraceGaugeTiming | undefined;
3739
+ /**
3740
+ * The gauge's level across the trace: the highest reading within each equal
3741
+ * part of the recorded duration, or of the readings' order when they are
3742
+ * untimed. A part with no reading holds the level of the reading before it,
3743
+ * and is `undefined` before the first reading.
3744
+ */
3745
+ trend: (number | undefined)[];
3746
+ };
3747
+ declare class TraceAggregator implements InputAggregator<AggregatedTrace> {
3748
+ #private;
3749
+ constructor(trace: Trace);
3750
+ detectOrigin(detector: OriginDetector): void;
3751
+ aggregate(_options: AggregationProfileToMdOptions, context: ProfileToMdContext): AggregatedTrace;
3752
+ }
3753
+ declare const modalitySpecs: readonly [{
3754
+ readonly categorySet: {
3755
+ readonly title: "Function categories";
3756
+ readonly noun: "function";
3757
+ readonly categories: readonly ["ours", "third-party", "stdlib", "native", "unknown", "garbage-collector", "compiler", "jit", "regexp", "kernel", "idle"];
3758
+ };
3759
+ readonly locations: ({ functions }: {
3760
+ functions: readonly AggregatedCallStackProfileFunction[];
3761
+ }) => Iterable<EntityLocation>;
3762
+ readonly entries: ({ functions }: {
3763
+ functions: readonly AggregatedCallStackProfileFunction[];
3764
+ }) => Iterable<AggregatedCallStackProfileFunction>;
3765
+ readonly categories: ({ functions }: {
3766
+ functions: readonly AggregatedCallStackProfileFunction[];
3767
+ }) => ("ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle")[];
3768
+ readonly id: "call-stack-profile";
3769
+ readonly aggregator: (profile: CallStackProfile, reader: RecordReader) => CallStackProfileAggregator;
3770
+ readonly format: (profile: AggregatedCallStackProfile, options: FormattingProfileToMdOptions) => RootContent[];
3771
+ readonly formatDiff: (base: AggregatedCallStackProfile, current: AggregatedCallStackProfile, options: FormattingProfileToMdOptions) => RootContent[];
3772
+ }, {
3773
+ readonly categorySet: {
3774
+ readonly title: "Function categories";
3775
+ readonly noun: "function";
3776
+ readonly categories: readonly ["ours", "third-party", "stdlib", "native", "unknown", "garbage-collector", "compiler", "jit", "regexp", "kernel", "idle"];
3777
+ };
3778
+ readonly locations: ({ functions }: {
3779
+ functions: readonly AggregatedCallGraphFunction[];
3780
+ }) => Iterable<EntityLocation>;
3781
+ readonly entries: ({ functions }: {
3782
+ functions: readonly AggregatedCallGraphFunction[];
3783
+ }) => Iterable<AggregatedCallGraphFunction>;
3784
+ readonly categories: ({ functions }: {
3785
+ functions: readonly AggregatedCallGraphFunction[];
3786
+ }) => ("ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle")[];
3787
+ readonly id: "call-graph";
3788
+ readonly aggregator: (graph: CallGraph, reader: RecordReader) => CallGraphAggregator;
3789
+ readonly format: (graph: AggregatedCallGraph, options: FormattingProfileToMdOptions) => RootContent[];
3790
+ readonly formatDiff: (base: AggregatedCallGraph, current: AggregatedCallGraph, options: FormattingProfileToMdOptions) => RootContent[];
3791
+ }, {
3792
+ readonly id: "heap-snapshot";
3793
+ readonly categorySet: {
3794
+ readonly title: "Heap snapshot categories";
3795
+ readonly noun: "heap snapshot node";
3796
+ readonly categories: readonly ["object", "array", "string", "concatenated-string", "sliced-string", "function", "code", "regexp", "number", "big-number", "symbol", "native", "object-shape", "internal", "synthetic", "unknown"];
3797
+ };
3798
+ readonly aggregator: (snapshot: HeapSnapshot, reader: RecordReader) => HeapSnapshotAggregator;
3799
+ readonly format: (snapshot: AggregatedHeapSnapshot, options: FormattingProfileToMdOptions) => RootContent[];
3800
+ readonly formatDiff: (base: AggregatedHeapSnapshot, current: AggregatedHeapSnapshot, options: FormattingProfileToMdOptions) => RootContent[];
3801
+ readonly locations: (snapshot: AggregatedHeapSnapshot) => Iterable<EntityLocation>;
3802
+ readonly entries: ({ constructors, functions }: AggregatedHeapSnapshot) => Iterable<AggregatedHeapSnapshotEntity>;
3803
+ readonly categories: (snapshot: AggregatedHeapSnapshot) => MapIterator<"string" | "number" | "symbol" | "object" | "function" | "code" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "big-number" | "object-shape" | "internal" | "synthetic">;
3804
+ }, {
3805
+ readonly id: "trace";
3806
+ readonly categorySet: {
3807
+ readonly title: "Trace event categories";
3808
+ readonly noun: "trace event";
3809
+ readonly categories: readonly ["script", "parsing", "compilation", "garbage-collection-pause", "garbage-collection", "style", "layout", "paint", "io", "other"];
3810
+ };
3811
+ readonly aggregator: (trace: Trace, reader: RecordReader) => TraceAggregator;
3812
+ readonly format: (trace: AggregatedTrace, options: FormattingProfileToMdOptions) => RootContent[];
3813
+ readonly formatDiff: (base: AggregatedTrace, current: AggregatedTrace, options: FormattingProfileToMdOptions) => RootContent[];
3814
+ readonly locations: () => never[];
3815
+ readonly entries: ({ spans, instants }: AggregatedTrace) => Iterable<AggregatedTraceEntity>;
3816
+ readonly categories: (trace: AggregatedTrace) => MapIterator<"script" | "parsing" | "compilation" | "garbage-collection-pause" | "garbage-collection" | "style" | "layout" | "paint" | "io" | "other">;
3817
+ }];
3818
+ type RegisteredModalitySpec = (typeof modalitySpecs)[number];
3819
+ /** An entry of an aggregated input, which `showEntry` filters. */
3820
+ type AggregatedProfileEntry = ReturnType<RegisteredModalitySpec[`entries`]> extends Iterable<infer Entry> ? Entry : never;
1931
3821
  /**
1932
3822
  * Converts the given profile data to Markdown.
1933
3823
  *
1934
3824
  * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
1935
3825
  * for supported formats and generation instructions.
1936
3826
  */
1937
- declare const profileToMd: (input: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
3827
+ export declare const profileToMd: (input: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
1938
3828
  /**
1939
3829
  * Asynchronously converts the given profile data to Markdown.
1940
3830
  *
1941
3831
  * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
1942
3832
  * for supported formats and generation instructions.
1943
3833
  */
1944
- declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
3834
+ export declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
1945
3835
  /**
1946
3836
  * Diffs the given base and current profile data, returning the difference as
1947
3837
  * Markdown.
@@ -1951,7 +3841,7 @@ declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?
1951
3841
  * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
1952
3842
  * for supported formats and generation instructions.
1953
3843
  */
1954
- declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
3844
+ export declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
1955
3845
  /**
1956
3846
  * Asynchronously diffs the given base and current profile data, returning the
1957
3847
  * difference as Markdown.
@@ -1961,9 +3851,7 @@ declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileIn
1961
3851
  * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
1962
3852
  * for supported formats and generation instructions.
1963
3853
  */
1964
- declare const diffProfilesAsync: (base: ProfileInput<AsyncProfileData>, current: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
1965
- //#endregion
1966
- //#region src/error.d.ts
3854
+ export declare const diffProfilesAsync: (base: ProfileInput<AsyncProfileData>, current: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
1967
3855
  /**
1968
3856
  * Thrown when a caller's input or options are unusable: an unrecognized
1969
3857
  * format, a malformed profile, an invalid option.
@@ -1974,8 +3862,7 @@ declare const diffProfilesAsync: (base: ProfileInput<AsyncProfileData>, current:
1974
3862
  * a way the parser does not check or a parser bug. That failure throws a
1975
3863
  * `ProfilerMdError` too, and `mayBeParserBug` identifies it.
1976
3864
  */
1977
- declare class ProfilerMdError extends Error {
3865
+ export declare class ProfilerMdError extends Error {
1978
3866
  constructor(message: string, options?: ErrorOptions);
1979
3867
  }
1980
- //#endregion
1981
- export { type AggregatedProfileEntry, type AsyncProfileData, type EntryMatch, type FileReference, type Format, type FunctionCategory, type LogicalReference, type Origin, type ProfileData, type ProfileEntry, type ProfileInput, type ProfileToMdContext, type ProfileToMdOptions, ProfilerMdError, type SourceLocation, type SourceMap, type SourceReference, defaultCategorizeFunctions, defaultMatchEntry, defaultShowEntry, diffProfiles, diffProfilesAsync, isSyntheticEntry, profileToMd, profileToMdAsync };
3868
+ export type { AggregatedProfileEntry, AsyncProfileData, EntryMatch, FileReference, Format, FunctionCategory, LogLevel, Logger, LogicalReference, Origin, ProfileData, ProfileEntry, ProfileInput, ProfileToMdContext, ProfileToMdOptions, SourceLocation, SourceMap, SourceReference };