profiler-md 0.8.1 → 0.9.1

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