profiler-md 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/dist/cli/index.mjs +5789 -5181
  2. package/dist/index.d.mts +478 -137
  3. package/dist/index.js +2 -2
  4. package/docs/formats/jfr.md +1 -1
  5. package/docs/formats/jsc-heap-snapshot.md +1 -1
  6. package/docs/formats/pprof.md +8 -6
  7. package/docs/formats/speedscope.md +5 -4
  8. package/docs/formats/systing.md +25 -0
  9. package/docs/formats/v8-heap-snapshot.md +2 -2
  10. package/docs/languages/c.md +35 -2
  11. package/docs/languages/csharp.md +2 -4
  12. package/docs/languages/elixir.md +4 -5
  13. package/docs/languages/go.md +6 -6
  14. package/docs/languages/java.md +13 -13
  15. package/docs/languages/javascript.md +7 -7
  16. package/docs/languages/julia.md +92 -13
  17. package/docs/languages/php.md +3 -4
  18. package/docs/languages/python.md +28 -13
  19. package/docs/languages/ruby.md +4 -6
  20. package/docs/languages/rust.md +37 -8
  21. package/examples/output/c.gperftools.heap.base.pprof.md +151 -151
  22. package/examples/output/c.gperftools.heap.current.pprof.md +151 -151
  23. package/examples/output/c.gperftools.heap.diff.pprof.md +3 -3
  24. package/examples/output/c.systing.cpu.base.systing.md +824 -0
  25. package/examples/output/c.systing.cpu.current.systing.md +825 -0
  26. package/examples/output/c.systing.cpu.diff.systing.md +238 -0
  27. package/examples/output/cpp.gperftools.heap.base.pprof.md +24 -24
  28. package/examples/output/cpp.gperftools.heap.current.pprof.md +24 -24
  29. package/examples/output/cpp.gperftools.heap.diff.pprof.md +2 -2
  30. package/examples/output/go.pprof.block.base.pprof.md +40 -40
  31. package/examples/output/go.pprof.block.current.pprof.md +37 -37
  32. package/examples/output/go.pprof.block.diff.pprof.md +14 -14
  33. package/examples/output/go.pprof.goroutine.base.pprof.md +16 -16
  34. package/examples/output/go.pprof.goroutine.current.pprof.md +16 -16
  35. package/examples/output/go.pprof.heap-alloc.base.pprof.md +79 -79
  36. package/examples/output/go.pprof.heap-alloc.current.pprof.md +72 -72
  37. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +25 -25
  38. package/examples/output/go.pprof.heap.base.pprof.md +79 -79
  39. package/examples/output/go.pprof.heap.current.pprof.md +72 -72
  40. package/examples/output/go.pprof.heap.diff.pprof.md +25 -25
  41. package/examples/output/go.pprof.mutex.base.pprof.md +26 -26
  42. package/examples/output/go.pprof.mutex.current.pprof.md +15 -15
  43. package/examples/output/go.pprof.mutex.diff.pprof.md +10 -10
  44. package/examples/output/java.async-profiler.all.base.jfr.md +192 -192
  45. package/examples/output/java.async-profiler.all.current.jfr.md +181 -181
  46. package/examples/output/java.async-profiler.all.diff.jfr.md +72 -72
  47. package/examples/output/java.async-profiler.alloc.base.jfr.md +189 -189
  48. package/examples/output/java.async-profiler.alloc.current.jfr.md +183 -183
  49. package/examples/output/java.async-profiler.alloc.diff.jfr.md +70 -70
  50. package/examples/output/java.async-profiler.live.base.jfr.md +303 -303
  51. package/examples/output/java.async-profiler.live.current.jfr.md +313 -313
  52. package/examples/output/java.async-profiler.live.diff.jfr.md +132 -132
  53. package/examples/output/java.async-profiler.nativemem.base.jfr.md +141 -141
  54. package/examples/output/java.async-profiler.nativemem.current.jfr.md +141 -141
  55. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +48 -48
  56. package/examples/output/java.jdk.all.base.jfr.md +281 -281
  57. package/examples/output/java.jdk.all.current.jfr.md +267 -267
  58. package/examples/output/java.jdk.all.diff.jfr.md +103 -103
  59. package/examples/output/java.jdk.alloc.base.jfr.md +254 -254
  60. package/examples/output/java.jdk.alloc.current.jfr.md +293 -293
  61. package/examples/output/java.jdk.alloc.diff.jfr.md +102 -102
  62. package/examples/output/java.jdk.cpu.base.jfr.md +256 -256
  63. package/examples/output/java.jdk.cpu.current.jfr.md +276 -276
  64. package/examples/output/java.jdk.cpu.diff.jfr.md +93 -93
  65. package/examples/output/java.jdk.live.base.jfr.md +256 -256
  66. package/examples/output/java.jdk.live.current.jfr.md +250 -250
  67. package/examples/output/java.jdk.live.diff.jfr.md +78 -78
  68. package/examples/output/java.jdk.lock.base.jfr.md +285 -285
  69. package/examples/output/java.jdk.lock.current.jfr.md +285 -285
  70. package/examples/output/java.jdk.lock.diff.jfr.md +121 -121
  71. package/examples/output/javascript.bun.base.cpuprofile.md +36 -36
  72. package/examples/output/javascript.bun.base.heapsnapshot.md +215 -215
  73. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +218 -218
  74. package/examples/output/javascript.bun.current.cpuprofile.md +34 -34
  75. package/examples/output/javascript.bun.current.heapsnapshot.md +215 -215
  76. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +220 -220
  77. package/examples/output/javascript.bun.diff.cpuprofile.md +19 -19
  78. package/examples/output/javascript.bun.diff.heapsnapshot.md +23 -23
  79. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +35 -35
  80. package/examples/output/javascript.chrome.base.heapprofile.md +17 -17
  81. package/examples/output/javascript.chrome.base.heapsnapshot.md +202 -202
  82. package/examples/output/javascript.chrome.current.heapprofile.md +17 -17
  83. package/examples/output/javascript.chrome.current.heapsnapshot.md +200 -200
  84. package/examples/output/javascript.chrome.diff.heapprofile.md +21 -21
  85. package/examples/output/javascript.chrome.diff.heapsnapshot.md +27 -27
  86. package/examples/output/javascript.deno.base.cpuprofile.md +63 -63
  87. package/examples/output/javascript.deno.current.cpuprofile.md +56 -56
  88. package/examples/output/javascript.deno.diff.cpuprofile.md +28 -28
  89. package/examples/output/javascript.node.base.cpuprofile.md +73 -73
  90. package/examples/output/javascript.node.base.heapprofile.md +32 -32
  91. package/examples/output/javascript.node.base.heapsnapshot.md +269 -269
  92. package/examples/output/javascript.node.current.cpuprofile.md +61 -61
  93. package/examples/output/javascript.node.current.heapprofile.md +28 -28
  94. package/examples/output/javascript.node.current.heapsnapshot.md +269 -269
  95. package/examples/output/javascript.node.diff.cpuprofile.md +32 -32
  96. package/examples/output/javascript.node.diff.heapprofile.md +17 -17
  97. package/examples/output/javascript.node.diff.heapsnapshot.md +19 -19
  98. package/examples/output/javascript.pprof.cpu.base.pprof.md +50 -50
  99. package/examples/output/javascript.pprof.cpu.current.pprof.md +66 -66
  100. package/examples/output/javascript.pprof.cpu.diff.pprof.md +28 -28
  101. package/examples/output/javascript.pprof.heap.base.pprof.md +46 -46
  102. package/examples/output/javascript.pprof.heap.current.pprof.md +34 -34
  103. package/examples/output/javascript.pprof.heap.diff.pprof.md +18 -18
  104. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +1 -1
  105. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +83 -83
  106. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +85 -85
  107. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +18 -18
  108. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +107 -107
  109. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +109 -109
  110. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +29 -29
  111. package/examples/output/julia.pprof-jl.wall.base.pprof.md +181 -0
  112. package/examples/output/julia.pprof-jl.wall.current.pprof.md +193 -0
  113. package/examples/output/julia.pprof-jl.wall.diff.pprof.md +64 -0
  114. package/examples/output/julia.profile.base.heapsnapshot.md +590 -0
  115. package/examples/output/julia.profile.current.heapsnapshot.md +590 -0
  116. package/examples/output/julia.profile.diff.heapsnapshot.md +288 -0
  117. package/examples/output/kotlin.async-profiler.all.base.jfr.md +193 -193
  118. package/examples/output/kotlin.async-profiler.all.current.jfr.md +218 -218
  119. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +93 -93
  120. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +212 -212
  121. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +183 -183
  122. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +93 -93
  123. package/examples/output/kotlin.async-profiler.live.base.jfr.md +343 -343
  124. package/examples/output/kotlin.async-profiler.live.current.jfr.md +336 -336
  125. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +186 -186
  126. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +150 -150
  127. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +150 -150
  128. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +48 -48
  129. package/examples/output/kotlin.jdk.all.base.jfr.md +402 -402
  130. package/examples/output/kotlin.jdk.all.current.jfr.md +413 -413
  131. package/examples/output/kotlin.jdk.all.diff.jfr.md +169 -169
  132. package/examples/output/kotlin.jdk.alloc.base.jfr.md +418 -418
  133. package/examples/output/kotlin.jdk.alloc.current.jfr.md +405 -405
  134. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +160 -160
  135. package/examples/output/kotlin.jdk.cpu.base.jfr.md +418 -418
  136. package/examples/output/kotlin.jdk.cpu.current.jfr.md +413 -413
  137. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +148 -148
  138. package/examples/output/kotlin.jdk.live.base.jfr.md +420 -420
  139. package/examples/output/kotlin.jdk.live.current.jfr.md +411 -411
  140. package/examples/output/kotlin.jdk.live.diff.jfr.md +148 -148
  141. package/examples/output/kotlin.jdk.lock.base.jfr.md +417 -417
  142. package/examples/output/kotlin.jdk.lock.current.jfr.md +398 -398
  143. package/examples/output/kotlin.jdk.lock.diff.jfr.md +156 -156
  144. package/examples/output/php.excimer.wall.base.speedscope.json.md +6 -6
  145. package/examples/output/php.excimer.wall.current.speedscope.json.md +6 -6
  146. package/examples/output/php.excimer.wall.diff.speedscope.json.md +6 -6
  147. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +14 -14
  148. package/examples/output/ruby.rbspy.cpu.base.pprof.md +14 -14
  149. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +14 -14
  150. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +12 -12
  151. package/examples/output/ruby.rbspy.cpu.current.pprof.md +21 -21
  152. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +21 -21
  153. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +5 -5
  154. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +12 -12
  155. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +12 -12
  156. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +32 -32
  157. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +32 -32
  158. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +7 -7
  159. package/package.json +11 -10
  160. package/readme.md +53 -31
  161. package/skills/profile-optimize/SKILL.md +160 -0
  162. package/docs/languages/cpp.md +0 -160
  163. package/docs/languages/erlang.md +0 -46
  164. package/docs/languages/fsharp.md +0 -52
  165. package/docs/languages/kotlin.md +0 -170
  166. package/docs/languages/typescript.md +0 -276
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { RawSourceMap as SourceMap } from "source-map-js";
1
+ import { RawSourceMap as SourceMap, SourceMapConsumer } from "source-map-js";
2
2
 
3
3
  //#region src/helpers/types.d.ts
4
4
  type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float16Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
@@ -14,7 +14,6 @@ type SourceLocation = FileReference & {
14
14
  /** The 1-based line number in the file. */line?: number; /** The 1-based column number in the file. */
15
15
  column?: number;
16
16
  };
17
- declare const fileReferenceId: (fileReference: DeepReadonly<FileReference>) => string;
18
17
  type FileReference = {
19
18
  type: `absolute`;
20
19
  url: URL;
@@ -28,25 +27,81 @@ type SourceLocationInput = {
28
27
  column?: number;
29
28
  };
30
29
  //#endregion
31
- //#region src/profile/type.d.ts
30
+ //#region src/metric.d.ts
31
+ /** Phrases that can be used in prose related to a metric. */
32
+ type MetricPhrases = {
33
+ /** A noun to use in headings, like "CPU", "heap", etc. */titleNoun: string; /** A noun to use in columns like "time", "size", etc. */
34
+ columnNoun: string; /** A verb to use in prose like "took", "allocated", etc. */
35
+ pastTenseVerb: string; /** A verb phrase to use in prose like "time spent", "bytes allocated", etc. */
36
+ pastParticipleVerbPhrase: string;
37
+ };
38
+ /** A metric measured in a profile. */
39
+ type Metric = ({
40
+ type: `time`; /** The number of milliseconds this time unit takes up. */
41
+ milliseconds: number;
42
+ } | {
43
+ type: `size`; /** The number of bytes this space unit takes up. */
44
+ bytes: number;
45
+ } | {
46
+ /**
47
+ * A metric in a unit with no known scale, formatted as a bare count.
48
+ * {@link MetricPhrases.columnNoun} (a plural noun, e.g. `instructions`)
49
+ * names the unit in table headers.
50
+ */
51
+ type: `custom`;
52
+ /**
53
+ * The singular noun following a count in prose, pluralized by the count
54
+ * (e.g. `cycle` → "84 cycles"). For a metric counting occurrences of the
55
+ * event its verb already names, use `time` → "slept 84 times".
56
+ */
57
+ proseUnit: string;
58
+ }) & {
59
+ phrases: MetricPhrases;
60
+ };
61
+ //#endregion
62
+ //#region src/modalities/profile/type.d.ts
63
+ /**
64
+ * A profile parsed into the uniform structure containing the distinct frames
65
+ * and the samples that reference them.
66
+ *
67
+ * A format that yields several profiles returns one of these per profile,
68
+ * typically sharing the same {@link Profile.frames} array reference.
69
+ */
70
+ type Profile = {
71
+ type: `profile`;
72
+ /**
73
+ * The distinct frames the samples reference.
74
+ *
75
+ * A {@link Sample.frameIndices} entry is an index into this list.
76
+ */
77
+ frames: ProfileStackFrame[]; /** @see {@link AggregatedProfile.metrics} */
78
+ metrics: Metric[]; /** The samples as a lazily-consumed iterable. */
79
+ samples: Iterable<Sample>;
80
+ /**
81
+ * Per-line metrics added after the samples, so a format can break a
82
+ * function's self time down by line from data accumulated while iterating
83
+ * {@link Profile.samples}.
84
+ */
85
+ lineMetrics?: Iterable<SampleLineMetrics>;
86
+ };
32
87
  /**
33
88
  * A function occurrence at an executing position.
34
89
  *
35
90
  * Its {@link name} and {@link location} (the function's *definition* location)
36
91
  * identify the function; frames sharing them are the same function.
37
92
  *
38
- * {@link line} is the *executing* line and feeds the per-line breakdown, not
39
- * identity.
93
+ * {@link line} is the *executing* line and is used for the per-line breakdown,
94
+ * not identity.
40
95
  *
41
- * A converter produces these raw (typically just a {@link name}); the resolved
42
- * origin's `normalizeFrame` then splits out the location and line for variants
43
- * that pack them into the frame string.
96
+ * A converter produces these raw; the resolved origin's `normalizeFrame` then
97
+ * splits out the location and line for variants that pack them into the frame
98
+ * string.
44
99
  */
45
100
  type ProfileStackFrame = {
46
101
  /** The function's name, if known. */name?: string; /** Where the function was defined, if known. */
47
102
  location?: SourceLocationInput;
48
103
  /**
49
- * The 1-based line at which this frame was sampled, if known.
104
+ * The 1-based line where this frame was sampled, if known.
50
105
  *
51
106
  * Distinct from {@link location}'s line (the definition line): this is the
52
107
  * executing line, which the aggregator forwards to the leaf function's
@@ -54,38 +109,56 @@ type ProfileStackFrame = {
54
109
  */
55
110
  line?: number;
56
111
  };
112
+ /** A single sample within a profile. */
113
+ type Sample = {
114
+ /**
115
+ * An identifier for this sample's call stack, if the caller has one (e.g. a
116
+ * format that references stacks by a constant-pool index).
117
+ *
118
+ * When provided, the aggregator memoizes the resolved call stack by this ID.
119
+ */
120
+ id?: number; /** The values recorded for each metric. */
121
+ values: number[]; /** The call stack as indices into {@link Profile.frames}. */
122
+ frameIndices: number[]; /** The 1-based line number where the sample was taken, if known. */
123
+ line?: number; /** The number of identical occurrences of this sample, defaulting to `1`. */
124
+ sampleCount?: number;
125
+ };
126
+ /**
127
+ * Per-line metrics for one frame, added after sampling.
128
+ *
129
+ * Used by formats that report a function's self time broken down by line
130
+ * separately from its samples.
131
+ */
132
+ type SampleLineMetrics = {
133
+ /** The frame's index into {@link Profile.frames}. */frame: number; /** The sampled lines within the frame's function body. */
134
+ lines: {
135
+ line: number;
136
+ sampleCount: number;
137
+ values: number[];
138
+ }[];
139
+ };
57
140
  //#endregion
58
141
  //#region src/origins/index.d.ts
59
142
  /**
60
- * A profile or snapshot origin: the thing that generated it, i.e. a profiler
61
- * paired with a runtime (e.g. `node`, `deno`, `safari`).
143
+ * A profiling tool paired with the runtime it observed (e.g. `node` for Node's
144
+ * native V8 profiler, `node-pprof` for the `pprof` npm package, `jvm` for JFR
145
+ * producers).
62
146
  *
63
- * Auto-detected from a profile's entries via {@link determineOrigin}, or
147
+ * Auto-detected from a profile's entries via {@link OriginDetector}, or
64
148
  * specified explicitly.
65
149
  */
66
150
  type Origin = SpecificOriginSpec[`id`];
67
- /**
68
- * Returns the category of {@link entry} as the given {@link origin} categorizes
69
- * it (see {@link OriginSpec.categorize}).
70
- *
71
- * The origin-aware categorization the library applies by default. Exposed so a
72
- * custom `categorizeEntries` can reuse the library's categorization for an
73
- * origin it didn't special-case, rather than reimplementing it.
74
- */
75
- declare const categorizeEntryForOrigin: (entry: DeepReadonly<ProfileEntry>, origin: Origin) => EntryCategory;
76
151
  /**
77
152
  * All origin specs in global detection-priority order.
78
153
  *
79
- * Within a format, the detector tries candidates in the order they appear
80
- * here, so origins that share a format and whose signals overlap must be
81
- * ordered carefully (e.g. Deno before Node, since Deno supports `node:`
82
- * specifiers).
154
+ * Within a format, the detector tries candidates in this order, so origins that
155
+ * share a format and whose marker entries overlap must be ordered carefully
156
+ * (e.g. Deno before Node, since Deno supports `node:` specifiers).
83
157
  */
84
158
  declare const originSpecs: ({
85
159
  readonly id: "deno";
86
- readonly language: "javascript";
87
160
  readonly formats: ["v8-cpu-profile"];
88
- readonly matchesEntry: ({
161
+ readonly isMarkerEntry: ({
89
162
  location
90
163
  }: {
91
164
  readonly id: number;
@@ -102,7 +175,7 @@ declare const originSpecs: ({
102
175
  readonly column?: number | undefined;
103
176
  } | undefined;
104
177
  }) => boolean;
105
- readonly categorize: (entry: {
178
+ readonly categorizeEntry: (entry: {
106
179
  readonly id: number;
107
180
  readonly name?: string | undefined;
108
181
  readonly location?: {
@@ -119,9 +192,8 @@ declare const originSpecs: ({
119
192
  }) => EntryCategory;
120
193
  } | {
121
194
  readonly id: "bun";
122
- readonly language: "javascript";
123
195
  readonly formats: ["v8-cpu-profile"];
124
- readonly matchesEntry: ({
196
+ readonly isMarkerEntry: ({
125
197
  name,
126
198
  location
127
199
  }: {
@@ -139,7 +211,7 @@ declare const originSpecs: ({
139
211
  readonly column?: number | undefined;
140
212
  } | undefined;
141
213
  }) => boolean;
142
- readonly categorize: (entry: {
214
+ readonly categorizeEntry: (entry: {
143
215
  readonly id: number;
144
216
  readonly name?: string | undefined;
145
217
  readonly location?: {
@@ -156,9 +228,8 @@ declare const originSpecs: ({
156
228
  }) => EntryCategory;
157
229
  } | {
158
230
  readonly id: "node";
159
- readonly language: "javascript";
160
231
  readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile"];
161
- readonly matchesEntry: ({
232
+ readonly isMarkerEntry: ({
162
233
  location
163
234
  }: {
164
235
  readonly id: number;
@@ -175,7 +246,7 @@ declare const originSpecs: ({
175
246
  readonly column?: number | undefined;
176
247
  } | undefined;
177
248
  }) => boolean;
178
- readonly categorize: (entry: {
249
+ readonly categorizeEntry: (entry: {
179
250
  readonly id: number;
180
251
  readonly name?: string | undefined;
181
252
  readonly location?: {
@@ -192,9 +263,8 @@ declare const originSpecs: ({
192
263
  }) => EntryCategory;
193
264
  } | {
194
265
  readonly id: "node-pprof";
195
- readonly language: "javascript";
196
266
  readonly formats: ["pprof"];
197
- readonly matchesEntry: ({
267
+ readonly isMarkerEntry: ({
198
268
  name,
199
269
  location
200
270
  }: {
@@ -212,7 +282,7 @@ declare const originSpecs: ({
212
282
  readonly column?: number | undefined;
213
283
  } | undefined;
214
284
  }) => boolean;
215
- readonly categorize: (entry: {
285
+ readonly categorizeEntry: (entry: {
216
286
  readonly id: number;
217
287
  readonly name?: string | undefined;
218
288
  readonly location?: {
@@ -230,9 +300,8 @@ declare const originSpecs: ({
230
300
  readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
231
301
  } | {
232
302
  readonly id: "pprof-rs";
233
- readonly language: "rust";
234
303
  readonly formats: ["pprof"];
235
- readonly matchesEntry: (entry: {
304
+ readonly isMarkerEntry: (entry: {
236
305
  readonly id: number;
237
306
  readonly name?: string | undefined;
238
307
  readonly location?: {
@@ -247,7 +316,7 @@ declare const originSpecs: ({
247
316
  readonly column?: number | undefined;
248
317
  } | undefined;
249
318
  }) => boolean;
250
- readonly categorize: (entry: {
319
+ readonly categorizeEntry: (entry: {
251
320
  readonly id: number;
252
321
  readonly name?: string | undefined;
253
322
  readonly location?: {
@@ -262,11 +331,11 @@ declare const originSpecs: ({
262
331
  readonly column?: number | undefined;
263
332
  } | undefined;
264
333
  }) => EntryCategory;
334
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
265
335
  } | {
266
336
  readonly id: "go";
267
- readonly language: "go";
268
337
  readonly formats: ["pprof"];
269
- readonly matchesEntry: (entry: {
338
+ readonly isMarkerEntry: (entry: {
270
339
  readonly id: number;
271
340
  readonly name?: string | undefined;
272
341
  readonly location?: {
@@ -281,7 +350,7 @@ declare const originSpecs: ({
281
350
  readonly column?: number | undefined;
282
351
  } | undefined;
283
352
  }) => boolean;
284
- readonly categorize: (entry: {
353
+ readonly categorizeEntry: (entry: {
285
354
  readonly id: number;
286
355
  readonly name?: string | undefined;
287
356
  readonly location?: {
@@ -298,9 +367,8 @@ declare const originSpecs: ({
298
367
  }) => EntryCategory;
299
368
  } | {
300
369
  readonly id: "pprof-jl";
301
- readonly language: "julia";
302
370
  readonly formats: ["pprof"];
303
- readonly matchesEntry: (entry: {
371
+ readonly isMarkerEntry: (entry: {
304
372
  readonly id: number;
305
373
  readonly name?: string | undefined;
306
374
  readonly location?: {
@@ -315,7 +383,7 @@ declare const originSpecs: ({
315
383
  readonly column?: number | undefined;
316
384
  } | undefined;
317
385
  }) => boolean;
318
- readonly categorize: (entry: {
386
+ readonly categorizeEntry: (entry: {
319
387
  readonly id: number;
320
388
  readonly name?: string | undefined;
321
389
  readonly location?: {
@@ -333,9 +401,8 @@ declare const originSpecs: ({
333
401
  readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame | null;
334
402
  } | {
335
403
  readonly id: "py-spy";
336
- readonly language: "python";
337
404
  readonly formats: ["collapsed", "speedscope"];
338
- readonly matchesEntry: (entry: {
405
+ readonly isMarkerEntry: (entry: {
339
406
  readonly id: number;
340
407
  readonly name?: string | undefined;
341
408
  readonly location?: {
@@ -350,13 +417,12 @@ declare const originSpecs: ({
350
417
  readonly column?: number | undefined;
351
418
  } | undefined;
352
419
  }) => boolean;
353
- readonly categorize: (entry: DeepReadonly<ProfileEntry>) => EntryCategory;
354
- readonly normalizeFrame: (input: ProfileStackFrame, format: "collapsed" | "jfr" | "jsc-heap-snapshot" | "pprof" | "speedscope" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => ProfileStackFrame;
420
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => EntryCategory;
421
+ readonly normalizeFrame: (input: ProfileStackFrame, format: "collapsed" | "jfr" | "pprof" | "systing" | "jsc-heap-snapshot" | "speedscope" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => ProfileStackFrame;
355
422
  } | {
356
423
  readonly id: "tachyon";
357
- readonly language: "python";
358
424
  readonly formats: ["collapsed"];
359
- readonly matchesEntry: (entry: {
425
+ readonly isMarkerEntry: (entry: {
360
426
  readonly id: number;
361
427
  readonly name?: string | undefined;
362
428
  readonly location?: {
@@ -371,13 +437,12 @@ declare const originSpecs: ({
371
437
  readonly column?: number | undefined;
372
438
  } | undefined;
373
439
  }) => boolean;
374
- readonly categorize: (entry: DeepReadonly<ProfileEntry>) => EntryCategory;
440
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => EntryCategory;
375
441
  readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
376
442
  } | {
377
443
  readonly id: "jvm";
378
- readonly language: "java";
379
444
  readonly formats: ["jfr", "collapsed"];
380
- readonly matchesEntry: (entry: {
445
+ readonly isMarkerEntry: (entry: {
381
446
  readonly id: number;
382
447
  readonly name?: string | undefined;
383
448
  readonly location?: {
@@ -392,7 +457,7 @@ declare const originSpecs: ({
392
457
  readonly column?: number | undefined;
393
458
  } | undefined;
394
459
  }) => boolean;
395
- readonly categorize: (entry: {
460
+ readonly categorizeEntry: (entry: {
396
461
  readonly id: number;
397
462
  readonly name?: string | undefined;
398
463
  readonly location?: {
@@ -407,12 +472,12 @@ declare const originSpecs: ({
407
472
  readonly column?: number | undefined;
408
473
  } | undefined;
409
474
  }) => EntryCategory;
475
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
410
476
  readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
411
477
  } | {
412
478
  readonly id: "dotnet-trace";
413
- readonly language: null;
414
479
  readonly formats: ["speedscope"];
415
- readonly matchesEntry: (entry: {
480
+ readonly isMarkerEntry: (entry: {
416
481
  readonly id: number;
417
482
  readonly name?: string | undefined;
418
483
  readonly location?: {
@@ -427,7 +492,7 @@ declare const originSpecs: ({
427
492
  readonly column?: number | undefined;
428
493
  } | undefined;
429
494
  }) => boolean;
430
- readonly categorize: (entry: {
495
+ readonly categorizeEntry: (entry: {
431
496
  readonly id: number;
432
497
  readonly name?: string | undefined;
433
498
  readonly location?: {
@@ -445,9 +510,8 @@ declare const originSpecs: ({
445
510
  readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame | null;
446
511
  } | {
447
512
  readonly id: "beam";
448
- readonly language: null;
449
513
  readonly formats: ["collapsed"];
450
- readonly matchesEntry: (entry: {
514
+ readonly isMarkerEntry: (entry: {
451
515
  readonly id: number;
452
516
  readonly name?: string | undefined;
453
517
  readonly location?: {
@@ -462,7 +526,7 @@ declare const originSpecs: ({
462
526
  readonly column?: number | undefined;
463
527
  } | undefined;
464
528
  }) => boolean;
465
- readonly categorize: (entry: {
529
+ readonly categorizeEntry: (entry: {
466
530
  readonly id: number;
467
531
  readonly name?: string | undefined;
468
532
  readonly location?: {
@@ -480,9 +544,8 @@ declare const originSpecs: ({
480
544
  readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
481
545
  } | {
482
546
  readonly id: "rbspy";
483
- readonly language: "ruby";
484
547
  readonly formats: ["collapsed", "pprof", "speedscope"];
485
- readonly matchesEntry: (entry: {
548
+ readonly isMarkerEntry: (entry: {
486
549
  readonly id: number;
487
550
  readonly name?: string | undefined;
488
551
  readonly location?: {
@@ -497,7 +560,7 @@ declare const originSpecs: ({
497
560
  readonly column?: number | undefined;
498
561
  } | undefined;
499
562
  }) => boolean;
500
- readonly categorize: (entry: {
563
+ readonly categorizeEntry: (entry: {
501
564
  readonly id: number;
502
565
  readonly name?: string | undefined;
503
566
  readonly location?: {
@@ -512,16 +575,48 @@ declare const originSpecs: ({
512
575
  readonly column?: number | undefined;
513
576
  } | undefined;
514
577
  }) => EntryCategory;
515
- readonly normalizeFrame: (input: ProfileStackFrame, format: "collapsed" | "jfr" | "jsc-heap-snapshot" | "pprof" | "speedscope" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => ProfileStackFrame;
578
+ readonly normalizeFrame: (input: ProfileStackFrame, format: "collapsed" | "jfr" | "pprof" | "systing" | "jsc-heap-snapshot" | "speedscope" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => ProfileStackFrame;
516
579
  } | {
517
580
  readonly id: "safari";
518
- readonly language: "javascript";
519
581
  readonly formats: ["jsc-heap-snapshot", "webkit-timeline-recording"];
520
- readonly matchesEntry: ({
582
+ readonly isMarkerEntry: ({
521
583
  name,
522
584
  location
523
585
  }: DeepReadonly<ProfileEntry>) => boolean;
524
- readonly categorize: (entry: {
586
+ readonly categorizeEntry: (entry: {
587
+ readonly id: number;
588
+ readonly name?: string | undefined;
589
+ readonly location?: {
590
+ readonly type: `absolute`;
591
+ readonly url: URL;
592
+ readonly line?: number | undefined;
593
+ readonly column?: number | undefined;
594
+ } | {
595
+ readonly type: `relative`;
596
+ readonly path: string;
597
+ readonly line?: number | undefined;
598
+ readonly column?: number | undefined;
599
+ } | undefined;
600
+ }) => EntryCategory;
601
+ } | {
602
+ readonly id: "systing";
603
+ readonly formats: ["systing"];
604
+ readonly isMarkerEntry: (entry: {
605
+ readonly id: number;
606
+ readonly name?: string | undefined;
607
+ readonly location?: {
608
+ readonly type: `absolute`;
609
+ readonly url: URL;
610
+ readonly line?: number | undefined;
611
+ readonly column?: number | undefined;
612
+ } | {
613
+ readonly type: `relative`;
614
+ readonly path: string;
615
+ readonly line?: number | undefined;
616
+ readonly column?: number | undefined;
617
+ } | undefined;
618
+ }) => boolean;
619
+ readonly categorizeEntry: (entry: {
525
620
  readonly id: number;
526
621
  readonly name?: string | undefined;
527
622
  readonly location?: {
@@ -536,12 +631,12 @@ declare const originSpecs: ({
536
631
  readonly column?: number | undefined;
537
632
  } | undefined;
538
633
  }) => EntryCategory;
634
+ readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
539
635
  } | {
540
636
  readonly id: "unknown";
541
- readonly language: null;
542
637
  readonly formats: [];
543
- readonly matchesEntry: () => false;
544
- readonly categorize: (entry: {
638
+ readonly isMarkerEntry: () => false;
639
+ readonly categorizeEntry: (entry: {
545
640
  readonly id: number;
546
641
  readonly name?: string | undefined;
547
642
  readonly location?: {
@@ -561,7 +656,7 @@ declare const originSpecs: ({
561
656
  type SpecificOriginSpec = (typeof originSpecs)[number];
562
657
  /** Every supported origin ID. */
563
658
  //#endregion
564
- //#region src/profile/aggregate.d.ts
659
+ //#region src/modalities/profile/aggregate.d.ts
565
660
  /** An aggregation of samples taken at a given line within a function's body. */
566
661
  type AggregatedProfileLineMetrics = {
567
662
  /**
@@ -611,7 +706,7 @@ type AggregatedProfileCalleeMetrics = {
611
706
  totalValues: Float64Array;
612
707
  /**
613
708
  * Internal aggregation bookkeeping: the epoch of the most recent call stack
614
- * whose total this edge was counted into, so a frame pair that recurs within
709
+ * whose total this frame pair was counted into, so one that recurs within
615
710
  * one call stack is counted just once.
616
711
  */
617
712
  lastSeenEpoch: number;
@@ -659,11 +754,129 @@ type AggregatedProfileFunction = {
659
754
  calleeIdToMetrics: Map<number, AggregatedProfileCalleeMetrics>;
660
755
  };
661
756
  //#endregion
662
- //#region src/snapshot/aggregate.d.ts
757
+ //#region src/modalities/snapshot/graph.d.ts
758
+ /**
759
+ * A successor and predecessor graph between heap snapshot nodes in CSR format.
760
+ *
761
+ * @see https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format)
762
+ */
763
+ type NodeAdjacencyGraph = {
764
+ /**
765
+ * Start offset into
766
+ * {@link NodeAdjacencyGraph.offsetToSuccessorOrdinal} and
767
+ * {@link NodeAdjacencyGraph.offsetToSuccessorEdgeIndex} for each
768
+ * node's successors in the graph.
769
+ *
770
+ * Node `i`'s successor ordinals occupy:
771
+ * `[offsetToSuccessorOrdinal[i], offsetToSuccessorOrdinal[i + 1])`.
772
+ *
773
+ * Node `i`'s successor edges occupy:
774
+ * `[offsetToSuccessorEdgeIndex[i], offsetToSuccessorEdgeIndex[i + 1])`.
775
+ */
776
+ ordinalToSuccessorStartOffset: Int32Array;
777
+ /**
778
+ * Successor ordinals, packed contiguously and indexed via
779
+ * {@link NodeAdjacencyGraph.ordinalToSuccessorStartOffset}.
780
+ */
781
+ offsetToSuccessorOrdinal: Int32Array;
782
+ /**
783
+ * Successor edge indices, packed contiguously and indexed via
784
+ * {@link NodeAdjacencyGraph.ordinalToSuccessorStartOffset}.
785
+ */
786
+ offsetToSuccessorEdgeIndex: Int32Array;
787
+ /**
788
+ * Start offset into
789
+ * {@link NodeAdjacencyGraph.offsetToPredecessorOrdinal} and
790
+ * {@link NodeAdjacencyGraph.offsetToPredecessorEdgeIndex} for each
791
+ * node's predecessors in the graph.
792
+ *
793
+ * Node `i`'s predecessor ordinals occupy:
794
+ * `[offsetToPredecessorOrdinal[i], offsetToPredecessorOrdinal[i + 1])`.
795
+ *
796
+ * Node `i`'s predecessor edges occupy:
797
+ * `[offsetToPredecessorEdgeIndex[i], offsetToPredecessorEdgeIndex[i + 1])`.
798
+ */
799
+ ordinalToPredecessorStartOffset: Int32Array;
800
+ /**
801
+ * Predecessor ordinals, packed contiguously and indexed via
802
+ * {@link NodeAdjacencyGraph.ordinalToPredecessorStartOffset}.
803
+ */
804
+ offsetToPredecessorOrdinal: Int32Array;
805
+ /**
806
+ * Predecessor edge indices, packed contiguously and indexed via
807
+ * {@link NodeAdjacencyGraph.ordinalToPredecessorStartOffset}.
808
+ */
809
+ offsetToPredecessorEdgeIndex: Int32Array;
810
+ };
811
+ //#endregion
812
+ //#region src/modalities/snapshot/type.d.ts
813
+ /**
814
+ * A heap snapshot parsed into the uniform structure containing the node
815
+ * adjacency graph and each node's classification.
816
+ *
817
+ * A format that yields several snapshots returns one of these per snapshot.
818
+ */
819
+ type HeapSnapshot = {
820
+ type: `snapshot`; /** Number of nodes in the snapshot. */
821
+ nodeCount: number; /** Number of edges between nodes in the snapshot. */
822
+ edgeCount: number; /** The successor and predecessor graph between the snapshot's nodes. */
823
+ nodeAdjacencyGraph: NodeAdjacencyGraph; /** Bytes allocated directly for the node. */
824
+ selfSizeOf: (nodeOrdinal: number) => number;
825
+ /**
826
+ * One entry per node ordinal, in ordinal order, as a lazily-consumed
827
+ * iterable.
828
+ */
829
+ nodes: Iterable<SnapshotNode>;
830
+ /**
831
+ * Formats an edge label, which is computed lazily at formatting time, so it
832
+ * receives the resolved formatting options.
833
+ */
834
+ formatEdgeLabel: (retainerOrdinal: number, edgeIndex: number, options: FormattingProfileToMdOptions) => string;
835
+ /**
836
+ * Formats a node label, which is computed lazily at formatting time, so it
837
+ * receives the resolved formatting options.
838
+ */
839
+ formatNodeLabel: (nodeOrdinal: number, options: FormattingProfileToMdOptions) => string; /** Whether the node is a bookkeeping node that never points to user code. */
840
+ isInternalNode: (nodeOrdinal: number) => boolean;
841
+ };
842
+ /**
843
+ * A heap snapshot node's classification.
844
+ *
845
+ * Every node contributes to its {@link SnapshotNode.category}'s stats; a node
846
+ * with a `type` additionally aggregates into that type's entities.
847
+ */
848
+ type SnapshotNode = {
849
+ category: string;
850
+ } & ({
851
+ type?: undefined;
852
+ } | {
853
+ type: `constructor`; /** A human readable label for this constructor. */
854
+ name: string; /** The exact location where the node was defined. */
855
+ location?: SourceLocation;
856
+ /**
857
+ * The file reference the {@link name} parses as, when it is URL-shaped.
858
+ */
859
+ nameLocation?: FileReference;
860
+ } | {
861
+ type: `closure`; /** A human readable label for this closure. */
862
+ name: string; /** The exact location where the closure was defined. */
863
+ location?: SourceLocation;
864
+ } | {
865
+ type: `string`; /** The (truncated) string value, if known. */
866
+ name?: string;
867
+ });
868
+ //#endregion
869
+ //#region src/modalities/snapshot/aggregate.d.ts
663
870
  type AggregatedSnapshotNode = {
664
871
  type: `node`; /** Unique ID for this node that can also be used as an index. */
665
872
  id: number; /** A human readable label for this node. */
666
- name?: string; /** Bytes allocated directly for this node. */
873
+ name?: string;
874
+ /**
875
+ * The file reference the {@link name} parses as, when it is URL-shaped
876
+ * (e.g. a V8 module namespace object named by its file URL). Formatting
877
+ * shows it relative to the base URL in place of the raw name.
878
+ */
879
+ nameLocation?: FileReference; /** Bytes allocated directly for this node. */
667
880
  selfSize: number;
668
881
  /**
669
882
  * Bytes allocated for this node, as well as all nodes that would be freed if
@@ -673,6 +886,13 @@ type AggregatedSnapshotNode = {
673
886
  location?: SourceLocation;
674
887
  };
675
888
  //#endregion
889
+ //#region src/source-map.d.ts
890
+ type NormalizedSourceMap = {
891
+ consumer: SourceMapConsumer;
892
+ fileReference: FileReference;
893
+ };
894
+ type NormalizedSourceMaps = NormalizedSourceMap[];
895
+ //#endregion
676
896
  //#region src/options.d.ts
677
897
  /** Profile data that can be synchronously parsed and converted to Markdown. */
678
898
  type ProfileData = string | Uint8Array | Iterable<Uint8Array>;
@@ -700,7 +920,7 @@ type ProfileEntry = {
700
920
  name?: string;
701
921
  /**
702
922
  * The location where the entity corresponding to this entry was defined, or
703
- * undefined if it's unknown.
923
+ * undefined if unknown.
704
924
  */
705
925
  location?: SourceLocation;
706
926
  };
@@ -710,7 +930,7 @@ type ProfileEntry = {
710
930
  * Only affects matching; the entry's displayed name and location are
711
931
  * unchanged.
712
932
  */
713
- type NormalizedEntry = {
933
+ type EntryMatch = {
714
934
  /** The name to match by. Omit to match by the entry's name. */name?: string;
715
935
  /**
716
936
  * The location to match by, as a URL or file path string. Omit to match by
@@ -718,14 +938,11 @@ type NormalizedEntry = {
718
938
  */
719
939
  location?: string;
720
940
  };
721
- /** A aggregated entry in a formatted profile. */
941
+ /** An aggregated entry in a formatted profile. */
722
942
  type AggregatedProfileEntry = AggregatedProfileFunction | AggregatedSnapshotNode;
723
- /**
724
- * The context in which a single profile or snapshot is being converted to
725
- * Markdown.
726
- */
943
+ /** The context in which a profile is being converted to Markdown. */
727
944
  type ProfileToMdContext = {
728
- /** The format of the profile or snapshot being converted. */format: Format; /** The origin, given explicitly or detected up front from the frames. */
945
+ /** The format of the profile being converted. */format: Format; /** The origin of the profile being converted. */
729
946
  origin: Origin;
730
947
  };
731
948
  /** Options for profile to Markdown converters. */
@@ -733,8 +950,7 @@ type ProfileToMdOptions = {
733
950
  /**
734
951
  * The number of entries to display when computing the "top N" by some metric.
735
952
  *
736
- * This value is also be used to limit subsection entry count by dividing it
737
- * by a constant.
953
+ * This value, divided by a constant, also limits subsection entry count.
738
954
  *
739
955
  * Defaults to 20.
740
956
  */
@@ -745,14 +961,19 @@ type ProfileToMdOptions = {
745
961
  * Accepts an absolute file path string or URL. File paths are converted to
746
962
  * `file://` URLs internally.
747
963
  *
748
- * A value of `null` indicates that URLs should be absolute.
964
+ * A value of `'auto'` infers the base URL as the common ancestor directory
965
+ * of the input's `ours`-categorized entries with absolute `file:` locations,
966
+ * across all profiles of an input and across both sides of a diff. Falls back
967
+ * to absolute paths when no entry qualifies.
968
+ *
969
+ * A value of `null` leaves URLs absolute.
749
970
  *
750
971
  * Defaults to `process.cwd()` when available. Otherwise leaves paths
751
972
  * absolute.
752
973
  */
753
- baseURL?: string | URL | null;
974
+ baseURL?: `auto` | (string & {}) | URL | null;
754
975
  /**
755
- * Source maps to apply when formatting profile locations.
976
+ * Source maps to apply when formatting source locations.
756
977
  *
757
978
  * Accepts either a list of raw source map objects, or a record mapping
758
979
  * generated file URLs or absolute/relative paths to raw source map objects.
@@ -767,56 +988,80 @@ type ProfileToMdOptions = {
767
988
  * location.
768
989
  *
769
990
  * Only affects which entries are considered the same entity when diffing
770
- * (profile functions and snapshot closures); displayed names and locations,
771
- * categorization, and source map resolution always use the entry's real
772
- * name and location. Matched entries display the current profile's name and
773
- * location.
991
+ * (e.g. profile functions); displayed names and locations, categorization,
992
+ * and source map resolution always use the entry's real name and location.
774
993
  *
775
- * Defaults to {@link defaultMatchEntry}, which strips known build hashes from
776
- * locations so that the same function matches across profiles built from the
777
- * same source.
994
+ * Matched entries display the _current_ profile's name and location (not
995
+ * _base_).
996
+ *
997
+ * Defaults to {@link defaultMatchEntry}.
778
998
  */
779
- matchEntry?: (entry: DeepReadonly<ProfileEntry>) => NormalizedEntry | undefined;
999
+ matchEntry?: (entry: DeepReadonly<ProfileEntry>, context: ProfileToMdContext) => EntryMatch | undefined;
780
1000
  /**
781
- * Returns a category string per entry of a single profile or snapshot, as an
782
- * array aligned with {@link entries} (index `i` categorizes entry `i`).
783
- *
784
- * Used to compute a category breakdown in the Markdown output.
1001
+ * Returns a category string per entry of a profile, as an array aligned with
1002
+ * {@link entries} (index `i` categorizes entry `i`).
785
1003
  *
786
- * Called once per profile or snapshot with all its {@link entries} and the
787
- * conversion {@link ProfileToMdContext | context} (the {@link Format | format}
788
- * and the resolved {@link Origin | origin}).
1004
+ * Used to compute:
1005
+ * - A category breakdown in the Markdown output
1006
+ * - The `baseURL` when using `baseURL: 'auto'`
1007
+ * - Which entries to show in {@link defaultShowEntry}
789
1008
  *
790
- * Receiving every entry up front lets the categorizer decide from the full
791
- * set rather than per entry in isolation.
1009
+ * Called once per profile with all its {@link entries}. Receiving every entry
1010
+ * up front lets the categorizer decide from the full set rather than per
1011
+ * entry in isolation.
792
1012
  *
793
- * Defaults to {@link defaultCategorizeEntries}, which applies the library's
794
- * origin-aware categorization ({@link categorizeEntryForOrigin}).
1013
+ * Defaults to {@link defaultCategorizeEntries}.
795
1014
  */
796
1015
  categorizeEntries?: (entries: readonly DeepReadonly<ProfileEntry>[], context: ProfileToMdContext) => readonly EntryCategory[];
797
1016
  /**
798
1017
  * Whether to include the given entry in the Markdown output.
799
1018
  *
800
- * Not showing an entry does not exclude it from metric computations.
1019
+ * Hidden entries still count in metric computations.
1020
+ *
1021
+ * Defaults to {@link defaultShowEntry}.
801
1022
  */
802
1023
  showEntry?: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
803
1024
  };
1025
+ /** {@link ProfileToMdOptions} with defaults applied. */
1026
+ type NormalizedProfileToMdOptions = {
1027
+ topN: number;
1028
+ baseURL: URL | `auto` | undefined;
1029
+ sourceMaps: NormalizedSourceMaps;
1030
+ entryMatchKey: (entry: ProfileEntry, context: ProfileToMdContext) => string;
1031
+ categorizeEntries: (entries: readonly ProfileEntry[], context: ProfileToMdContext) => readonly EntryCategory[];
1032
+ showEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
1033
+ };
804
1034
  /**
805
- * Returns a name and location to match this entry by with known
806
- * run-varying identifiers stripped — build hashes (Cargo build-script and
807
- * rustc commit-hash directories) and JVM runtime addresses (`$$Lambda.0x…`
808
- * classes, `I2C/C2I adapters(0x…)` stubs) — or `undefined` if the entry
809
- * contains none.
1035
+ * The options aggregation code receives.
1036
+ *
1037
+ * Everything except `baseURL`, which only affects formatting and, for `'auto'`,
1038
+ * is resolvable only after aggregation (from the aggregated entries). The
1039
+ * omission keeps aggregation logic from depending on it.
810
1040
  */
811
- declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>) => NormalizedEntry | undefined;
1041
+ type AggregationProfileToMdOptions = Omit<NormalizedProfileToMdOptions, `baseURL`>;
812
1042
  /**
813
- * The default {@link ProfileToMdOptions.categorizeEntries}.
1043
+ * The options formatting code receives.
1044
+ *
1045
+ * {@link NormalizedProfileToMdOptions} with `'auto'` resolved to a concrete
1046
+ * base URL (or `undefined` when nothing qualified for inference).
1047
+ */
1048
+ type FormattingProfileToMdOptions = AggregationProfileToMdOptions & {
1049
+ baseURL: URL | undefined;
1050
+ };
1051
+ /**
1052
+ * The default {@link ProfileToMdOptions.matchEntry}.
814
1053
  *
815
- * Applies the library's origin-aware categorization to each entry (see
816
- * {@link categorizeEntryForOrigin}).
1054
+ * Applies the origin's match normalization to the entry, stripping the origin's
1055
+ * known run-varying identifiers (e.g. Rust build hashes for `pprof-rs`, JVM
1056
+ * runtime addresses for `jvm`), or `undefined` if the entry contains none.
1057
+ */
1058
+ declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>, {
1059
+ origin
1060
+ }: ProfileToMdContext) => EntryMatch | undefined;
1061
+ /**
1062
+ * The default {@link ProfileToMdOptions.categorizeEntries}.
817
1063
  *
818
- * Exposed so a custom categorizer can reuse it as a base (e.g. override a few
819
- * entries and delegate the rest).
1064
+ * Applies the library's origin-aware categorization to each entry.
820
1065
  */
821
1066
  declare const defaultCategorizeEntries: (entries: readonly DeepReadonly<ProfileEntry>[], {
822
1067
  origin
@@ -824,15 +1069,14 @@ declare const defaultCategorizeEntries: (entries: readonly DeepReadonly<ProfileE
824
1069
  /**
825
1070
  * Returns whether to include the given entry in the Markdown output.
826
1071
  *
827
- * Excludes synthetic and external-private entries.
1072
+ * Excludes synthetic and external implementation detail entries.
828
1073
  */
829
1074
  declare const defaultShowEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
830
1075
  /**
831
- * Returns true if the entry is a synthetic artifacts.
1076
+ * Returns true if the entry is synthetic.
832
1077
  *
833
- * These entries are artifacts generated by the profiler and don't correspond to
834
- * something that actually exists in code or at runtime. For example, a
835
- * synthetic `(root)` node is typically created for heap snapshots.
1078
+ * The profiler invents these entries; they correspond to nothing that exists
1079
+ * in code or at runtime (e.g. a synthetic `(root)` node for heap snapshots).
836
1080
  */
837
1081
  declare const isSyntheticEntry: ({
838
1082
  name
@@ -841,25 +1085,125 @@ declare const isSyntheticEntry: ({
841
1085
  * Returns true if the entry corresponds to an external function (`native`,
842
1086
  * `stdlib`, or `third-party`) that's never directly called by `ours` code.
843
1087
  *
844
- * These entries are typically implementation details of external code that your
845
- * own code cannot directly call. Excluding these entries from the Markdown
846
- * leaves only your code and the public API surface of `stdlib` and
847
- * `third-party` code.
1088
+ * These entries are typically implementation details of external code.
1089
+ * Excluding them from the Markdown leaves only your code and the public API
1090
+ * of `stdlib` and `third-party` code.
848
1091
  */
849
1092
  declare const isExternalImplementationDetailEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
850
1093
  //#endregion
1094
+ //#region src/formats/registry.d.ts
1095
+ /** Every supported format's converter, keyed by format ID. */
1096
+ declare const formatConverters: {
1097
+ readonly collapsed: {
1098
+ readonly title: "Collapsed stacks";
1099
+ readonly extension: "collapsed";
1100
+ readonly languages: readonly ["elixir", "java", "python", "ruby"];
1101
+ readonly fallbackOrigin: "unknown";
1102
+ readonly type: "binary";
1103
+ readonly matches: (bytes: Uint8Array) => boolean;
1104
+ readonly parse: (bytes: Uint8Array) => Profile[];
1105
+ readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<Profile[]>;
1106
+ };
1107
+ readonly jfr: {
1108
+ readonly title: "JFR";
1109
+ readonly extension: "jfr";
1110
+ readonly languages: readonly ["java"];
1111
+ readonly fallbackOrigin: "jvm";
1112
+ readonly type: "binary";
1113
+ readonly matches: (bytes: Uint8Array) => boolean;
1114
+ readonly parse: (bytes: Uint8Array) => Profile[];
1115
+ readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<Profile[]>;
1116
+ };
1117
+ readonly 'jsc-heap-snapshot': {
1118
+ readonly title: "JSC heap snapshot";
1119
+ readonly extension: "jsc-heap-snapshot.json";
1120
+ readonly languages: readonly ["javascript"];
1121
+ readonly fallbackOrigin: "safari";
1122
+ readonly type: "json";
1123
+ readonly matches: (json: unknown) => boolean;
1124
+ readonly parse: (json: unknown) => HeapSnapshot[];
1125
+ };
1126
+ readonly pprof: {
1127
+ readonly title: "pprof";
1128
+ readonly extension: "pprof";
1129
+ readonly languages: readonly ["c", "go", "javascript", "julia", "ruby", "rust"];
1130
+ readonly fallbackOrigin: "unknown";
1131
+ readonly type: "binary";
1132
+ readonly matches: (bytes: Uint8Array) => boolean;
1133
+ readonly parse: (bytes: Uint8Array<ArrayBufferLike>) => Profile[];
1134
+ readonly parseAsync: (stream: ReadableStream<Uint8Array<ArrayBufferLike>>) => Promise<Profile[]>;
1135
+ };
1136
+ readonly speedscope: {
1137
+ readonly title: "Speedscope";
1138
+ readonly extension: "speedscope.json";
1139
+ readonly languages: readonly ["csharp", "php", "python", "ruby"];
1140
+ readonly fallbackOrigin: "unknown";
1141
+ readonly type: "json";
1142
+ readonly matches: (json: unknown) => boolean;
1143
+ readonly parse: (json: unknown) => Profile[];
1144
+ };
1145
+ readonly systing: {
1146
+ readonly title: "systing profile export";
1147
+ readonly extension: "systing";
1148
+ readonly languages: readonly ["c", "python", "rust"];
1149
+ readonly fallbackOrigin: "systing";
1150
+ readonly type: "binary";
1151
+ readonly matches: (bytes: Uint8Array) => boolean;
1152
+ readonly parse: (bytes: Uint8Array) => Profile[];
1153
+ readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<Profile[]>;
1154
+ };
1155
+ readonly 'v8-cpu-profile': {
1156
+ readonly title: "V8 CPU profile";
1157
+ readonly extension: "cpuprofile";
1158
+ readonly languages: readonly ["javascript"];
1159
+ readonly fallbackOrigin: "unknown";
1160
+ readonly type: "json";
1161
+ readonly matches: (json: unknown) => boolean;
1162
+ readonly parse: (json: unknown) => Profile[];
1163
+ };
1164
+ readonly 'v8-heap-profile': {
1165
+ readonly title: "V8 heap profile";
1166
+ readonly extension: "heapprofile";
1167
+ readonly languages: readonly ["javascript"];
1168
+ readonly fallbackOrigin: "node";
1169
+ readonly type: "json";
1170
+ readonly matches: (json: unknown) => boolean;
1171
+ readonly parse: (json: unknown) => Profile[];
1172
+ };
1173
+ readonly 'v8-heap-snapshot': {
1174
+ readonly title: "V8 heap snapshot";
1175
+ readonly extension: "heapsnapshot";
1176
+ readonly languages: readonly ["javascript", "julia"];
1177
+ readonly fallbackOrigin: "node";
1178
+ readonly type: "json";
1179
+ readonly matches: (json: unknown) => boolean;
1180
+ readonly parse: (json: unknown) => HeapSnapshot[];
1181
+ };
1182
+ readonly 'webkit-timeline-recording': {
1183
+ readonly title: "WebKit timeline recording";
1184
+ readonly extension: "webkit-timeline-recording.json";
1185
+ readonly languages: readonly ["javascript"];
1186
+ readonly fallbackOrigin: "safari";
1187
+ readonly type: "json";
1188
+ readonly matches: (json: unknown) => boolean;
1189
+ readonly parse: (json: unknown) => Profile[];
1190
+ };
1191
+ };
1192
+ /** Supported profile format IDs. */
1193
+ type Format = keyof typeof formatConverters;
1194
+ //#endregion
851
1195
  //#region src/formats/index.d.ts
852
1196
  /**
853
1197
  * Converts the given profile data to Markdown.
854
1198
  *
855
- * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
1199
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
856
1200
  * for supported formats and generation instructions.
857
1201
  */
858
1202
  declare const profileToMd: (input: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
859
1203
  /**
860
1204
  * Asynchronously converts the given profile data to Markdown.
861
1205
  *
862
- * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
1206
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
863
1207
  * for supported formats and generation instructions.
864
1208
  */
865
1209
  declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
@@ -869,7 +1213,7 @@ declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?
869
1213
  *
870
1214
  * Each side accepts the same input as {@link profileToMd}.
871
1215
  *
872
- * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
1216
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
873
1217
  * for supported formats and generation instructions.
874
1218
  */
875
1219
  declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
@@ -879,12 +1223,9 @@ declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileIn
879
1223
  *
880
1224
  * Each side accepts the same input as {@link profileToMdAsync}.
881
1225
  *
882
- * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
1226
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
883
1227
  * for supported formats and generation instructions.
884
1228
  */
885
1229
  declare const diffProfilesAsync: (base: ProfileInput<AsyncProfileData>, current: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
886
- declare const formats: readonly ["collapsed", "jfr", "jsc-heap-snapshot", "pprof", "speedscope", "v8-cpu-profile", "v8-heap-profile", "v8-heap-snapshot", "webkit-timeline-recording"];
887
- /** Supported profile format IDs. */
888
- type Format = (typeof formats)[number];
889
1230
  //#endregion
890
- export { type AggregatedProfileEntry, type AsyncProfileData, type EntryCategory, type FileReference, type Format, type NormalizedEntry, type Origin, type ProfileData, type ProfileEntry, type ProfileInput, type ProfileToMdContext, type ProfileToMdOptions, type SourceLocation, type SourceMap, categorizeEntryForOrigin, defaultCategorizeEntries, defaultMatchEntry, defaultShowEntry, diffProfiles, diffProfilesAsync, fileReferenceId, isExternalImplementationDetailEntry, isSyntheticEntry, profileToMd, profileToMdAsync };
1231
+ export { type AggregatedProfileEntry, type AsyncProfileData, type EntryCategory, type EntryMatch, type FileReference, type Format, type Origin, type ProfileData, type ProfileEntry, type ProfileInput, type ProfileToMdContext, type ProfileToMdOptions, type SourceLocation, type SourceMap, defaultCategorizeEntries, defaultMatchEntry, defaultShowEntry, diffProfiles, diffProfilesAsync, isExternalImplementationDetailEntry, isSyntheticEntry, profileToMd, profileToMdAsync };