profiler-md 0.6.0 → 0.7.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 (239) hide show
  1. package/dist/cli/index.mjs +12685 -4219
  2. package/dist/index.d.mts +1140 -432
  3. package/dist/index.js +2 -2
  4. package/docs/api.md +138 -0
  5. package/docs/formats/callgrind.md +25 -0
  6. package/docs/formats/collapsed.md +5 -3
  7. package/docs/formats/ghc-eventlog.md +20 -0
  8. package/docs/formats/ghc-json-profile.md +23 -0
  9. package/docs/formats/hprof.md +21 -0
  10. package/docs/formats/jfr.md +2 -2
  11. package/docs/formats/jsc-heap-snapshot.md +10 -4
  12. package/docs/formats/memray.md +30 -0
  13. package/docs/formats/perf.md +74 -0
  14. package/docs/formats/pprof.md +4 -2
  15. package/docs/formats/speedscope.md +3 -2
  16. package/docs/formats/systing.md +17 -15
  17. package/docs/formats/v8-cpu-profile.md +4 -3
  18. package/docs/formats/v8-heap-profile.md +8 -5
  19. package/docs/formats/v8-heap-snapshot.md +8 -3
  20. package/docs/formats/webkit-timeline-recording.md +6 -0
  21. package/docs/languages/c.md +119 -32
  22. package/docs/languages/csharp.md +5 -3
  23. package/docs/languages/elixir.md +19 -11
  24. package/docs/languages/fortran.md +141 -0
  25. package/docs/languages/go.md +33 -10
  26. package/docs/languages/haskell.md +134 -0
  27. package/docs/languages/java.md +81 -26
  28. package/docs/languages/javascript.md +33 -27
  29. package/docs/languages/julia.md +21 -18
  30. package/docs/languages/php.md +7 -0
  31. package/docs/languages/python.md +105 -14
  32. package/docs/languages/ruby.md +15 -16
  33. package/docs/languages/rust.md +11 -10
  34. package/docs/languages/swift.md +135 -0
  35. package/docs/languages/zig.md +155 -0
  36. package/package.json +42 -42
  37. package/readme.md +301 -259
  38. package/skills/profile-optimize/SKILL.md +4 -2
  39. package/examples/output/c.gperftools.cpu.base.pprof.md +0 -324
  40. package/examples/output/c.gperftools.cpu.current.pprof.md +0 -271
  41. package/examples/output/c.gperftools.cpu.diff.pprof.md +0 -98
  42. package/examples/output/c.gperftools.heap.base.pprof.md +0 -362
  43. package/examples/output/c.gperftools.heap.current.pprof.md +0 -362
  44. package/examples/output/c.gperftools.heap.diff.pprof.md +0 -28
  45. package/examples/output/c.systing.cpu.base.systing.md +0 -824
  46. package/examples/output/c.systing.cpu.current.systing.md +0 -825
  47. package/examples/output/c.systing.cpu.diff.systing.md +0 -238
  48. package/examples/output/cpp.gperftools.cpu.base.pprof.md +0 -557
  49. package/examples/output/cpp.gperftools.cpu.current.pprof.md +0 -573
  50. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +0 -122
  51. package/examples/output/cpp.gperftools.heap.base.pprof.md +0 -67
  52. package/examples/output/cpp.gperftools.heap.current.pprof.md +0 -67
  53. package/examples/output/cpp.gperftools.heap.diff.pprof.md +0 -19
  54. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +0 -411
  55. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +0 -412
  56. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +0 -122
  57. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +0 -399
  58. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +0 -398
  59. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +0 -92
  60. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +0 -147
  61. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +0 -147
  62. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +0 -18
  63. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +0 -324
  64. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +0 -314
  65. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +0 -119
  66. package/examples/output/go.pprof.block.base.pprof.md +0 -86
  67. package/examples/output/go.pprof.block.current.pprof.md +0 -83
  68. package/examples/output/go.pprof.block.diff.pprof.md +0 -42
  69. package/examples/output/go.pprof.cpu.base.pprof.md +0 -81
  70. package/examples/output/go.pprof.cpu.current.pprof.md +0 -70
  71. package/examples/output/go.pprof.cpu.diff.pprof.md +0 -52
  72. package/examples/output/go.pprof.goroutine.base.pprof.md +0 -43
  73. package/examples/output/go.pprof.goroutine.current.pprof.md +0 -43
  74. package/examples/output/go.pprof.goroutine.diff.pprof.md +0 -13
  75. package/examples/output/go.pprof.heap-alloc.base.pprof.md +0 -154
  76. package/examples/output/go.pprof.heap-alloc.current.pprof.md +0 -146
  77. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +0 -67
  78. package/examples/output/go.pprof.heap.base.pprof.md +0 -154
  79. package/examples/output/go.pprof.heap.current.pprof.md +0 -146
  80. package/examples/output/go.pprof.heap.diff.pprof.md +0 -67
  81. package/examples/output/go.pprof.mutex.base.pprof.md +0 -55
  82. package/examples/output/go.pprof.mutex.current.pprof.md +0 -41
  83. package/examples/output/go.pprof.mutex.diff.pprof.md +0 -31
  84. package/examples/output/go.pprof.threadcreate.base.pprof.md +0 -55
  85. package/examples/output/go.pprof.threadcreate.current.pprof.md +0 -55
  86. package/examples/output/go.pprof.threadcreate.diff.pprof.md +0 -19
  87. package/examples/output/java.async-profiler.all.base.jfr.md +0 -1071
  88. package/examples/output/java.async-profiler.all.current.jfr.md +0 -1007
  89. package/examples/output/java.async-profiler.all.diff.jfr.md +0 -268
  90. package/examples/output/java.async-profiler.alloc.base.jfr.md +0 -425
  91. package/examples/output/java.async-profiler.alloc.current.jfr.md +0 -413
  92. package/examples/output/java.async-profiler.alloc.diff.jfr.md +0 -99
  93. package/examples/output/java.async-profiler.cpu.base.collapsed.md +0 -367
  94. package/examples/output/java.async-profiler.cpu.base.jfr.md +0 -485
  95. package/examples/output/java.async-profiler.cpu.current.collapsed.md +0 -355
  96. package/examples/output/java.async-profiler.cpu.current.jfr.md +0 -488
  97. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +0 -117
  98. package/examples/output/java.async-profiler.cpu.diff.jfr.md +0 -118
  99. package/examples/output/java.async-profiler.live.base.jfr.md +0 -697
  100. package/examples/output/java.async-profiler.live.current.jfr.md +0 -684
  101. package/examples/output/java.async-profiler.live.diff.jfr.md +0 -191
  102. package/examples/output/java.async-profiler.lock.base.jfr.md +0 -140
  103. package/examples/output/java.async-profiler.lock.current.jfr.md +0 -108
  104. package/examples/output/java.async-profiler.lock.diff.jfr.md +0 -44
  105. package/examples/output/java.async-profiler.nativemem.base.jfr.md +0 -222
  106. package/examples/output/java.async-profiler.nativemem.current.jfr.md +0 -222
  107. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +0 -65
  108. package/examples/output/java.async-profiler.wall.base.jfr.md +0 -400
  109. package/examples/output/java.async-profiler.wall.current.jfr.md +0 -420
  110. package/examples/output/java.async-profiler.wall.diff.jfr.md +0 -94
  111. package/examples/output/java.jdk.all.base.jfr.md +0 -1024
  112. package/examples/output/java.jdk.all.current.jfr.md +0 -1010
  113. package/examples/output/java.jdk.all.diff.jfr.md +0 -311
  114. package/examples/output/java.jdk.alloc.base.jfr.md +0 -1024
  115. package/examples/output/java.jdk.alloc.current.jfr.md +0 -1046
  116. package/examples/output/java.jdk.alloc.diff.jfr.md +0 -312
  117. package/examples/output/java.jdk.cpu.base.jfr.md +0 -1023
  118. package/examples/output/java.jdk.cpu.current.jfr.md +0 -1039
  119. package/examples/output/java.jdk.cpu.diff.jfr.md +0 -285
  120. package/examples/output/java.jdk.live.base.jfr.md +0 -1029
  121. package/examples/output/java.jdk.live.current.jfr.md +0 -1035
  122. package/examples/output/java.jdk.live.diff.jfr.md +0 -289
  123. package/examples/output/java.jdk.lock.base.jfr.md +0 -1040
  124. package/examples/output/java.jdk.lock.current.jfr.md +0 -1051
  125. package/examples/output/java.jdk.lock.diff.jfr.md +0 -339
  126. package/examples/output/javascript.bun.base.cpuprofile.md +0 -73
  127. package/examples/output/javascript.bun.base.heapsnapshot.md +0 -608
  128. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +0 -480
  129. package/examples/output/javascript.bun.current.cpuprofile.md +0 -73
  130. package/examples/output/javascript.bun.current.heapsnapshot.md +0 -608
  131. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +0 -480
  132. package/examples/output/javascript.bun.diff.cpuprofile.md +0 -54
  133. package/examples/output/javascript.bun.diff.heapsnapshot.md +0 -48
  134. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +0 -62
  135. package/examples/output/javascript.chrome.base.cpuprofile.md +0 -163
  136. package/examples/output/javascript.chrome.base.heapprofile.md +0 -32
  137. package/examples/output/javascript.chrome.base.heapsnapshot.md +0 -649
  138. package/examples/output/javascript.chrome.current.cpuprofile.md +0 -149
  139. package/examples/output/javascript.chrome.current.heapprofile.md +0 -32
  140. package/examples/output/javascript.chrome.current.heapsnapshot.md +0 -647
  141. package/examples/output/javascript.chrome.diff.cpuprofile.md +0 -65
  142. package/examples/output/javascript.chrome.diff.heapprofile.md +0 -50
  143. package/examples/output/javascript.chrome.diff.heapsnapshot.md +0 -73
  144. package/examples/output/javascript.deno.base.cpuprofile.md +0 -122
  145. package/examples/output/javascript.deno.current.cpuprofile.md +0 -114
  146. package/examples/output/javascript.deno.diff.cpuprofile.md +0 -66
  147. package/examples/output/javascript.node.base.cpuprofile.md +0 -136
  148. package/examples/output/javascript.node.base.heapprofile.md +0 -56
  149. package/examples/output/javascript.node.base.heapsnapshot.md +0 -660
  150. package/examples/output/javascript.node.current.cpuprofile.md +0 -119
  151. package/examples/output/javascript.node.current.heapprofile.md +0 -52
  152. package/examples/output/javascript.node.current.heapsnapshot.md +0 -660
  153. package/examples/output/javascript.node.diff.cpuprofile.md +0 -70
  154. package/examples/output/javascript.node.diff.heapprofile.md +0 -34
  155. package/examples/output/javascript.node.diff.heapsnapshot.md +0 -39
  156. package/examples/output/javascript.pprof.cpu.base.pprof.md +0 -104
  157. package/examples/output/javascript.pprof.cpu.current.pprof.md +0 -120
  158. package/examples/output/javascript.pprof.cpu.diff.pprof.md +0 -63
  159. package/examples/output/javascript.pprof.heap.base.pprof.md +0 -86
  160. package/examples/output/javascript.pprof.heap.current.pprof.md +0 -57
  161. package/examples/output/javascript.pprof.heap.diff.pprof.md +0 -42
  162. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +0 -388
  163. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +0 -378
  164. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +0 -122
  165. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +0 -124
  166. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +0 -126
  167. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +0 -30
  168. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +0 -177
  169. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +0 -179
  170. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +0 -64
  171. package/examples/output/julia.pprof-jl.wall.base.pprof.md +0 -181
  172. package/examples/output/julia.pprof-jl.wall.current.pprof.md +0 -193
  173. package/examples/output/julia.pprof-jl.wall.diff.pprof.md +0 -64
  174. package/examples/output/julia.profile.base.heapsnapshot.md +0 -590
  175. package/examples/output/julia.profile.current.heapsnapshot.md +0 -590
  176. package/examples/output/julia.profile.diff.heapsnapshot.md +0 -288
  177. package/examples/output/kotlin.async-profiler.all.base.jfr.md +0 -920
  178. package/examples/output/kotlin.async-profiler.all.current.jfr.md +0 -925
  179. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +0 -247
  180. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +0 -467
  181. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +0 -473
  182. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +0 -122
  183. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +0 -371
  184. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +0 -472
  185. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +0 -370
  186. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +0 -445
  187. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +0 -124
  188. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +0 -125
  189. package/examples/output/kotlin.async-profiler.live.base.jfr.md +0 -934
  190. package/examples/output/kotlin.async-profiler.live.current.jfr.md +0 -917
  191. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +0 -245
  192. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +0 -1
  193. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +0 -1
  194. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +0 -1
  195. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +0 -234
  196. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +0 -234
  197. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +0 -65
  198. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +0 -452
  199. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +0 -457
  200. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +0 -125
  201. package/examples/output/kotlin.jdk.all.base.jfr.md +0 -1442
  202. package/examples/output/kotlin.jdk.all.current.jfr.md +0 -1343
  203. package/examples/output/kotlin.jdk.all.diff.jfr.md +0 -392
  204. package/examples/output/kotlin.jdk.alloc.base.jfr.md +0 -1418
  205. package/examples/output/kotlin.jdk.alloc.current.jfr.md +0 -1389
  206. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +0 -383
  207. package/examples/output/kotlin.jdk.cpu.base.jfr.md +0 -1406
  208. package/examples/output/kotlin.jdk.cpu.current.jfr.md +0 -1374
  209. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +0 -380
  210. package/examples/output/kotlin.jdk.live.base.jfr.md +0 -1378
  211. package/examples/output/kotlin.jdk.live.current.jfr.md +0 -1311
  212. package/examples/output/kotlin.jdk.live.diff.jfr.md +0 -381
  213. package/examples/output/kotlin.jdk.lock.base.jfr.md +0 -1427
  214. package/examples/output/kotlin.jdk.lock.current.jfr.md +0 -1374
  215. package/examples/output/kotlin.jdk.lock.diff.jfr.md +0 -386
  216. package/examples/output/php.excimer.wall.base.speedscope.json.md +0 -25
  217. package/examples/output/php.excimer.wall.current.speedscope.json.md +0 -25
  218. package/examples/output/php.excimer.wall.diff.speedscope.json.md +0 -29
  219. package/examples/output/python.py-spy.cpu.base.collapsed.md +0 -526
  220. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +0 -37
  221. package/examples/output/python.py-spy.cpu.current.collapsed.md +0 -514
  222. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +0 -37
  223. package/examples/output/python.py-spy.cpu.diff.collapsed.md +0 -122
  224. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +0 -31
  225. package/examples/output/python.py-spy.wall.base.collapsed.md +0 -527
  226. package/examples/output/python.py-spy.wall.current.collapsed.md +0 -518
  227. package/examples/output/python.py-spy.wall.diff.collapsed.md +0 -122
  228. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +0 -90
  229. package/examples/output/ruby.rbspy.cpu.base.pprof.md +0 -105
  230. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +0 -105
  231. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +0 -90
  232. package/examples/output/ruby.rbspy.cpu.current.pprof.md +0 -115
  233. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +0 -115
  234. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +0 -32
  235. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +0 -44
  236. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +0 -44
  237. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +0 -60
  238. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +0 -60
  239. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +0 -24
package/dist/index.d.mts CHANGED
@@ -1,19 +1,22 @@
1
1
  import { RawSourceMap as SourceMap, SourceMapConsumer } from "source-map-js";
2
-
3
2
  //#region src/helpers/types.d.ts
4
3
  type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float16Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
5
4
  /**
6
5
  * Recursively makes all properties of `T` readonly, including nested objects,
7
6
  * arrays, and `Map`/`Set` collections.
8
7
  */
9
- 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;
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;
10
9
  //#endregion
11
10
  //#region src/location.d.ts
12
- /** A file reference, potentially with line and column information. */
13
- type SourceLocation = FileReference & {
14
- /** The 1-based line number in the file. */line?: number; /** The 1-based column number in the file. */
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. */
15
16
  column?: number;
16
17
  };
18
+ /** A reference to where a function is defined: a file or a logical name. */
19
+ type SourceReference = FileReference | LogicalReference;
17
20
  type FileReference = {
18
21
  type: `absolute`;
19
22
  url: URL;
@@ -21,26 +24,61 @@ type FileReference = {
21
24
  type: `relative`;
22
25
  path: string;
23
26
  };
24
- type SourceLocationInput = {
25
- /** A string parseable into a {@link URL} or file path. */urlOrPath: string; /** The 1-based line number in the file at {@link urlOrPath}. */
26
- line?: number; /** The 1-based column number in the file at {@link urlOrPath}. */
27
+ /**
28
+ * A named class, module, namespace, assembly, or native library (e.g.
29
+ * `java.util.HashMap`).
30
+ */
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. */
27
49
  column?: number;
28
50
  };
29
51
  //#endregion
30
- //#region src/metric.d.ts
52
+ //#region src/modalities/metric.d.ts
31
53
  /** Phrases that can be used in prose related to a metric. */
32
54
  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. */
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. */
36
62
  pastParticipleVerbPhrase: string;
37
63
  };
64
+ /**
65
+ * Which direction of change in a metric's value is an improvement.
66
+ *
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.
72
+ */
73
+ type MetricImprovement = `decrease` | `increase` | `unknown`;
38
74
  /** A metric measured in a profile. */
39
75
  type Metric = ({
40
- type: `time`; /** The number of milliseconds this time unit takes up. */
76
+ type: `time`;
77
+ /** The number of milliseconds this time unit takes up. */
41
78
  milliseconds: number;
42
79
  } | {
43
- type: `size`; /** The number of bytes this space unit takes up. */
80
+ type: `size`;
81
+ /** The number of bytes this space unit takes up. */
44
82
  bytes: number;
45
83
  } | {
46
84
  /**
@@ -48,7 +86,7 @@ type Metric = ({
48
86
  * {@link MetricPhrases.columnNoun} (a plural noun, e.g. `instructions`)
49
87
  * names the unit in table headers.
50
88
  */
51
- type: `custom`;
89
+ type: `count`;
52
90
  /**
53
91
  * The singular noun following a count in prose, pluralized by the count
54
92
  * (e.g. `cycle` → "84 cycles"). For a metric counting occurrences of the
@@ -57,33 +95,11 @@ type Metric = ({
57
95
  proseUnit: string;
58
96
  }) & {
59
97
  phrases: MetricPhrases;
98
+ /** Which direction of change in this metric's value is an improvement. */
99
+ improvement: MetricImprovement;
60
100
  };
61
101
  //#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
- };
102
+ //#region src/modalities/stack-frame.d.ts
87
103
  /**
88
104
  * A function occurrence at an executing position.
89
105
  *
@@ -93,12 +109,14 @@ type Profile = {
93
109
  * {@link line} is the *executing* line and is used for the per-line breakdown,
94
110
  * not identity.
95
111
  *
96
- * A converter produces these raw; the resolved origin's `normalizeFrame` then
112
+ * A converter produces these raw; the resolved origin's `normalizeStackFrame` then
97
113
  * splits out the location and line for variants that pack them into the frame
98
114
  * string.
99
115
  */
100
- type ProfileStackFrame = {
101
- /** The function's name, if known. */name?: string; /** Where the function was defined, if known. */
116
+ type StackFrame = {
117
+ /** The function's name, if known. */
118
+ name?: string;
119
+ /** Where the function was defined, if known. */
102
120
  location?: SourceLocationInput;
103
121
  /**
104
122
  * The 1-based line where this frame was sampled, if known.
@@ -109,58 +127,474 @@ type ProfileStackFrame = {
109
127
  */
110
128
  line?: number;
111
129
  };
112
- /** A single sample within a profile. */
113
- type Sample = {
130
+ //#endregion
131
+ //#region src/modalities/call-graph/type.d.ts
132
+ /**
133
+ * 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
135
+ * 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
+ */
140
+ type CallGraph = {
141
+ type: `call-graph`;
142
+ /** @see {@link CallStackProfile.originHint} */
143
+ originHint?: string;
144
+ /**
145
+ * The metrics each cost vector is indexed by. Always at least one: unlike a
146
+ * call stack profile, a call graph has no count to fall back on.
147
+ */
148
+ metrics: Metric[];
114
149
  /**
115
- * An identifier for this sample's call stack, if the caller has one (e.g. a
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.
154
+ */
155
+ frames: StackFrame[];
156
+ /** The graph's function nodes, indexed by {@link CallGraphCall.callee}. */
157
+ functions: CallGraphFunction[];
158
+ };
159
+ /** A function node in a parsed call graph. */
160
+ type CallGraphFunction = {
161
+ /** The cost recorded directly in the function's body, per metric. */
162
+ selfValues: number[];
163
+ /** Each 1-based line to the self cost recorded at that line, per metric. */
164
+ lineToValues: Map<number, number[]>;
165
+ /** The function's outgoing calls. */
166
+ calls: CallGraphCall[];
167
+ };
168
+ /** One caller→callee arc: the recorded call count and inclusive cost. */
169
+ type CallGraphCall = {
170
+ /** The called function's index in {@link CallGraph.functions}. */
171
+ callee: number;
172
+ /** The recorded number of calls, or `0` when the format records none. */
173
+ callCount: number;
174
+ /**
175
+ * The calls' inclusive cost per metric: cost recorded in the callee and its
176
+ * callees during these calls.
177
+ */
178
+ totalValues: number[];
179
+ };
180
+ //#endregion
181
+ //#region src/modalities/call-stack-profile/type.d.ts
182
+ /**
183
+ * A profile parsed into the uniform structure containing the distinct frames
184
+ * and the observations that reference them.
185
+ *
186
+ * A format that yields several profiles returns one of these per profile,
187
+ * typically sharing the same {@link CallStackProfile.frames} array reference.
188
+ */
189
+ type CallStackProfile = {
190
+ type: `call-stack-profile`;
191
+ /**
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.
195
+ *
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.
199
+ */
200
+ originHint?: string;
201
+ /**
202
+ * The distinct frames the observations reference.
203
+ *
204
+ * A {@link Observation.frameIndices} entry is an index into this list.
205
+ */
206
+ frames: StackFrame[];
207
+ /** @see {@link AggregatedCallStackProfile.metrics} */
208
+ metrics: Metric[];
209
+ /**
210
+ * @see {@link AggregatedCallStackProfile.countMetric}
211
+ *
212
+ * Every parser states this, including `SAMPLES` for a profiler that samples
213
+ * the call stack periodically, so no format inherits an answer it was never
214
+ * checked against. An origin overrides it with `OriginSpec.countMetric`,
215
+ * where the format's emitters disagree.
216
+ */
217
+ countMetric: Metric | null;
218
+ /** The observations as a lazily-consumed iterable. */
219
+ observations: Iterable<Observation>;
220
+ /**
221
+ * Per-line metrics added after the observations, so a format can break a
222
+ * function's self time down by line from data summed while iterating
223
+ * {@link CallStackProfile.observations}.
224
+ */
225
+ lineMetrics?: Iterable<ObservationLineMetrics>;
226
+ };
227
+ /** One record of a profile: a call stack, its values, and how many it stands for. */
228
+ type Observation = {
229
+ /**
230
+ * An identifier for this record's call stack, if the caller has one (e.g. a
116
231
  * format that references stacks by a constant-pool index).
117
232
  *
118
233
  * When provided, the aggregator memoizes the resolved call stack by this ID.
119
234
  */
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;
235
+ id?: number;
236
+ /** The values recorded for each metric. */
237
+ values: number[];
238
+ /** The call stack as indices into {@link CallStackProfile.frames}. */
239
+ frameIndices: number[];
240
+ /** The 1-based line number the leaf frame was at, if known. */
241
+ line?: number;
242
+ /**
243
+ * How many identical occurrences this record stands for, defaulting to `1`.
244
+ *
245
+ * {@link CallStackProfile.countMetric} states what one of them is.
246
+ */
247
+ count?: number;
125
248
  };
126
249
  /**
127
- * Per-line metrics for one frame, added after sampling.
250
+ * Per-line metrics for one frame, added after the observations.
128
251
  *
129
252
  * Used by formats that report a function's self time broken down by line
130
- * separately from its samples.
253
+ * separately from its observations.
131
254
  */
132
- type SampleLineMetrics = {
133
- /** The frame's index into {@link Profile.frames}. */frame: number; /** The sampled lines within the frame's function body. */
255
+ type ObservationLineMetrics = {
256
+ /** The frame's index into {@link CallStackProfile.frames}. */
257
+ frame: number;
258
+ /** The lines recorded within the frame's function body. */
134
259
  lines: {
135
260
  line: number;
136
- sampleCount: number;
261
+ count: number;
137
262
  values: number[];
138
263
  }[];
139
264
  };
140
265
  //#endregion
141
- //#region src/origins/index.d.ts
266
+ //#region src/modalities/heap-snapshot/graph.d.ts
142
267
  /**
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).
268
+ * A successor and predecessor graph between heap snapshot nodes in CSR format.
146
269
  *
147
- * Auto-detected from a profile's entries via {@link OriginDetector}, or
148
- * specified explicitly.
270
+ * @see https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format)
149
271
  */
150
- type Origin = SpecificOriginSpec[`id`];
272
+ type NodeAdjacencyGraph = {
273
+ /**
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])`.
284
+ */
285
+ ordinalToSuccessorStartOffset: Int32Array;
286
+ /**
287
+ * Successor ordinals, packed contiguously and indexed via
288
+ * {@link NodeAdjacencyGraph.ordinalToSuccessorStartOffset}.
289
+ */
290
+ offsetToSuccessorOrdinal: Int32Array;
291
+ /**
292
+ * Successor edge indices, packed contiguously and indexed via
293
+ * {@link NodeAdjacencyGraph.ordinalToSuccessorStartOffset}.
294
+ */
295
+ offsetToSuccessorEdgeIndex: Int32Array;
296
+ /**
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])`.
307
+ */
308
+ ordinalToPredecessorStartOffset: Int32Array;
309
+ /**
310
+ * Predecessor ordinals, packed contiguously and indexed via
311
+ * {@link NodeAdjacencyGraph.ordinalToPredecessorStartOffset}.
312
+ */
313
+ offsetToPredecessorOrdinal: Int32Array;
314
+ /**
315
+ * Predecessor edge indices, packed contiguously and indexed via
316
+ * {@link NodeAdjacencyGraph.ordinalToPredecessorStartOffset}.
317
+ */
318
+ offsetToPredecessorEdgeIndex: Int32Array;
319
+ };
320
+ //#endregion
321
+ //#region src/modalities/heap-snapshot/type.d.ts
322
+ /**
323
+ * A heap snapshot parsed into the uniform structure containing the node
324
+ * adjacency graph and each node's unresolved category.
325
+ *
326
+ * A format that yields several snapshots returns one of these per snapshot.
327
+ */
328
+ type HeapSnapshot = {
329
+ type: `heap-snapshot`;
330
+ /** Number of nodes in the snapshot. */
331
+ nodeCount: number;
332
+ /** Number of edges between nodes in the snapshot. */
333
+ edgeCount: number;
334
+ /** The successor and predecessor graph between the snapshot's nodes. */
335
+ nodeAdjacencyGraph: NodeAdjacencyGraph;
336
+ /** Bytes allocated directly for the node. */
337
+ selfSizeOf: (nodeOrdinal: number) => number;
338
+ /**
339
+ * One entry per node ordinal, in ordinal order, as a lazily-consumed
340
+ * iterable.
341
+ */
342
+ nodes: Iterable<HeapSnapshotNode>;
343
+ /**
344
+ * Formats an edge label, which is computed lazily at formatting time, so it
345
+ * receives the resolved formatting options.
346
+ */
347
+ formatEdgeLabel: (retainerOrdinal: number, edgeIndex: number, options: FormattingProfileToMdOptions) => string;
348
+ /**
349
+ * Formats a node label, which is computed lazily at formatting time, so it
350
+ * receives the resolved formatting options.
351
+ */
352
+ formatNodeLabel: (nodeOrdinal: number, options: FormattingProfileToMdOptions) => string;
353
+ /** Whether the node is a bookkeeping node that never points to user code. */
354
+ isInternalNode: (nodeOrdinal: number) => boolean;
355
+ /**
356
+ * The node's category before the origin resolves it, computed from the node
357
+ * ordinal so formatting can categorize a node again after {@link nodes} is
358
+ * consumed.
359
+ */
360
+ unresolvedCategoryOf: (nodeOrdinal: number) => UnresolvedHeapSnapshotNodeCategory;
361
+ };
362
+ /**
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`.
374
+ */
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"];
378
+ /**
379
+ * What a heap snapshot node holds, as the format categorized it, before the
380
+ * origin resolves it.
381
+ *
382
+ * {@link category} is undefined when the format declared a type name this
383
+ * modality's categories don't name, in which case {@link declaredType} holds
384
+ * that name for an origin to map. Julia writes its own type names into V8's
385
+ * `meta.node_types`, so every node of its snapshots has a {@link declaredType}
386
+ * instead of a category.
387
+ */
388
+ type UnresolvedHeapSnapshotNodeCategory = {
389
+ category: HeapSnapshotNodeCategory | undefined;
390
+ declaredType?: string;
391
+ };
392
+ /**
393
+ * A heap snapshot node.
394
+ *
395
+ * Every node contributes to its category's stats. A node with a `type` also
396
+ * aggregates into that type's entities.
397
+ */
398
+ type HeapSnapshotNode = UnresolvedHeapSnapshotNodeCategory & ({
399
+ type?: undefined;
400
+ } | {
401
+ type: `constructor`;
402
+ /** A human readable label for this constructor. */
403
+ name: string;
404
+ /** The exact location where the node was defined. */
405
+ location?: SourceLocation;
406
+ /**
407
+ * The file reference the {@link name} parses as, when it is URL-shaped.
408
+ */
409
+ nameLocation?: FileReference;
410
+ } | {
411
+ type: `function`;
412
+ /** A human readable label for this function. */
413
+ 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", "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
+ };
579
+ /** Supported profile format IDs. */
580
+ type Format = keyof typeof formatConverters;
581
+ //#endregion
582
+ //#region src/origins/specs/index.d.ts
151
583
  /**
152
584
  * All origin specs in global detection-priority order.
153
585
  *
154
586
  * Within a format, the detector tries candidates in this order, so origins that
155
587
  * share a format and whose marker entries overlap must be ordered carefully
156
- * (e.g. Deno before Node, since Deno supports `node:` specifiers).
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.
157
592
  */
158
593
  declare const originSpecs: ({
159
594
  readonly id: "deno";
595
+ readonly title: "Deno";
160
596
  readonly formats: ["v8-cpu-profile"];
161
- readonly isMarkerEntry: ({
162
- location
163
- }: {
597
+ readonly isMarkerEntry: ({ location }: {
164
598
  readonly id: number;
165
599
  readonly name?: string | undefined;
166
600
  readonly location?: {
@@ -173,6 +607,11 @@ declare const originSpecs: ({
173
607
  readonly path: string;
174
608
  readonly line?: number | undefined;
175
609
  readonly column?: number | undefined;
610
+ } | {
611
+ readonly type: `logical`;
612
+ readonly name: string;
613
+ readonly line?: number | undefined;
614
+ readonly column?: number | undefined;
176
615
  } | undefined;
177
616
  }) => boolean;
178
617
  readonly categorizeEntry: (entry: {
@@ -188,15 +627,18 @@ declare const originSpecs: ({
188
627
  readonly path: string;
189
628
  readonly line?: number | undefined;
190
629
  readonly column?: number | undefined;
630
+ } | {
631
+ readonly type: `logical`;
632
+ readonly name: string;
633
+ readonly line?: number | undefined;
634
+ readonly column?: number | undefined;
191
635
  } | undefined;
192
- }) => EntryCategory;
636
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
193
637
  } | {
194
638
  readonly id: "bun";
195
- readonly formats: ["v8-cpu-profile"];
196
- readonly isMarkerEntry: ({
197
- name,
198
- location
199
- }: {
639
+ readonly title: "Bun";
640
+ readonly formats: ["v8-cpu-profile", "jsc-heap-snapshot", "v8-heap-snapshot"];
641
+ readonly isMarkerEntry: ({ name, location }: {
200
642
  readonly id: number;
201
643
  readonly name?: string | undefined;
202
644
  readonly location?: {
@@ -209,6 +651,11 @@ declare const originSpecs: ({
209
651
  readonly path: string;
210
652
  readonly line?: number | undefined;
211
653
  readonly column?: number | undefined;
654
+ } | {
655
+ readonly type: `logical`;
656
+ readonly name: string;
657
+ readonly line?: number | undefined;
658
+ readonly column?: number | undefined;
212
659
  } | undefined;
213
660
  }) => boolean;
214
661
  readonly categorizeEntry: (entry: {
@@ -224,14 +671,19 @@ declare const originSpecs: ({
224
671
  readonly path: string;
225
672
  readonly line?: number | undefined;
226
673
  readonly column?: number | undefined;
674
+ } | {
675
+ readonly type: `logical`;
676
+ readonly name: string;
677
+ readonly line?: number | undefined;
678
+ readonly column?: number | undefined;
227
679
  } | undefined;
228
- }) => EntryCategory;
680
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
681
+ readonly categorizeHeapSnapshotConstructor: (name: string) => "string" | "number" | "symbol" | "object" | "function" | "unknown" | "native" | "regexp" | "array" | "concatenated string" | "sliced string" | "code" | "big number" | "object shape" | "internal" | "synthetic" | undefined;
229
682
  } | {
230
683
  readonly id: "node";
684
+ readonly title: "Node.js";
231
685
  readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile"];
232
- readonly isMarkerEntry: ({
233
- location
234
- }: {
686
+ readonly isMarkerEntry: ({ location }: {
235
687
  readonly id: number;
236
688
  readonly name?: string | undefined;
237
689
  readonly location?: {
@@ -244,6 +696,11 @@ declare const originSpecs: ({
244
696
  readonly path: string;
245
697
  readonly line?: number | undefined;
246
698
  readonly column?: number | undefined;
699
+ } | {
700
+ readonly type: `logical`;
701
+ readonly name: string;
702
+ readonly line?: number | undefined;
703
+ readonly column?: number | undefined;
247
704
  } | undefined;
248
705
  }) => boolean;
249
706
  readonly categorizeEntry: (entry: {
@@ -259,15 +716,63 @@ declare const originSpecs: ({
259
716
  readonly path: string;
260
717
  readonly line?: number | undefined;
261
718
  readonly column?: number | undefined;
719
+ } | {
720
+ readonly type: `logical`;
721
+ readonly name: string;
722
+ readonly line?: number | undefined;
723
+ readonly column?: number | undefined;
262
724
  } | undefined;
263
- }) => EntryCategory;
725
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
726
+ readonly categorizeHeapSnapshotConstructor: (name: string) => HeapSnapshotNodeCategory | undefined;
727
+ } | {
728
+ readonly id: "chrome";
729
+ readonly title: "Chrome";
730
+ readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile"];
731
+ readonly isMarkerEntry: ({ name, location }: {
732
+ readonly id: number;
733
+ readonly name?: string | undefined;
734
+ readonly location?: {
735
+ readonly type: `absolute`;
736
+ readonly url: URL;
737
+ readonly line?: number | undefined;
738
+ readonly column?: number | undefined;
739
+ } | {
740
+ readonly type: `relative`;
741
+ readonly path: string;
742
+ readonly line?: number | undefined;
743
+ readonly column?: number | undefined;
744
+ } | {
745
+ readonly type: `logical`;
746
+ readonly name: string;
747
+ readonly line?: number | undefined;
748
+ readonly column?: number | undefined;
749
+ } | undefined;
750
+ }) => boolean;
751
+ readonly categorizeEntry: (entry: {
752
+ readonly id: number;
753
+ readonly name?: string | undefined;
754
+ readonly location?: {
755
+ readonly type: `absolute`;
756
+ readonly url: URL;
757
+ readonly line?: number | undefined;
758
+ readonly column?: number | undefined;
759
+ } | {
760
+ readonly type: `relative`;
761
+ readonly path: string;
762
+ readonly line?: number | undefined;
763
+ readonly column?: number | undefined;
764
+ } | {
765
+ readonly type: `logical`;
766
+ readonly name: string;
767
+ readonly line?: number | undefined;
768
+ readonly column?: number | undefined;
769
+ } | undefined;
770
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
771
+ readonly categorizeHeapSnapshotConstructor: (name: string) => HeapSnapshotNodeCategory | undefined;
264
772
  } | {
265
773
  readonly id: "node-pprof";
266
774
  readonly formats: ["pprof"];
267
- readonly isMarkerEntry: ({
268
- name,
269
- location
270
- }: {
775
+ readonly isMarkerEntry: ({ name, location }: {
271
776
  readonly id: number;
272
777
  readonly name?: string | undefined;
273
778
  readonly location?: {
@@ -280,6 +785,11 @@ declare const originSpecs: ({
280
785
  readonly path: string;
281
786
  readonly line?: number | undefined;
282
787
  readonly column?: number | undefined;
788
+ } | {
789
+ readonly type: `logical`;
790
+ readonly name: string;
791
+ readonly line?: number | undefined;
792
+ readonly column?: number | undefined;
283
793
  } | undefined;
284
794
  }) => boolean;
285
795
  readonly categorizeEntry: (entry: {
@@ -295,9 +805,14 @@ declare const originSpecs: ({
295
805
  readonly path: string;
296
806
  readonly line?: number | undefined;
297
807
  readonly column?: number | undefined;
808
+ } | {
809
+ readonly type: `logical`;
810
+ readonly name: string;
811
+ readonly line?: number | undefined;
812
+ readonly column?: number | undefined;
298
813
  } | undefined;
299
- }) => EntryCategory;
300
- readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
814
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
815
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
301
816
  } | {
302
817
  readonly id: "pprof-rs";
303
818
  readonly formats: ["pprof"];
@@ -314,6 +829,11 @@ declare const originSpecs: ({
314
829
  readonly path: string;
315
830
  readonly line?: number | undefined;
316
831
  readonly column?: number | undefined;
832
+ } | {
833
+ readonly type: `logical`;
834
+ readonly name: string;
835
+ readonly line?: number | undefined;
836
+ readonly column?: number | undefined;
317
837
  } | undefined;
318
838
  }) => boolean;
319
839
  readonly categorizeEntry: (entry: {
@@ -329,11 +849,17 @@ declare const originSpecs: ({
329
849
  readonly path: string;
330
850
  readonly line?: number | undefined;
331
851
  readonly column?: number | undefined;
852
+ } | {
853
+ readonly type: `logical`;
854
+ readonly name: string;
855
+ readonly line?: number | undefined;
856
+ readonly column?: number | undefined;
332
857
  } | undefined;
333
- }) => EntryCategory;
858
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
334
859
  readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
335
860
  } | {
336
861
  readonly id: "go";
862
+ readonly title: "pprof";
337
863
  readonly formats: ["pprof"];
338
864
  readonly isMarkerEntry: (entry: {
339
865
  readonly id: number;
@@ -348,6 +874,11 @@ declare const originSpecs: ({
348
874
  readonly path: string;
349
875
  readonly line?: number | undefined;
350
876
  readonly column?: number | undefined;
877
+ } | {
878
+ readonly type: `logical`;
879
+ readonly name: string;
880
+ readonly line?: number | undefined;
881
+ readonly column?: number | undefined;
351
882
  } | undefined;
352
883
  }) => boolean;
353
884
  readonly categorizeEntry: (entry: {
@@ -363,8 +894,13 @@ declare const originSpecs: ({
363
894
  readonly path: string;
364
895
  readonly line?: number | undefined;
365
896
  readonly column?: number | undefined;
897
+ } | {
898
+ readonly type: `logical`;
899
+ readonly name: string;
900
+ readonly line?: number | undefined;
901
+ readonly column?: number | undefined;
366
902
  } | undefined;
367
- }) => EntryCategory;
903
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
368
904
  } | {
369
905
  readonly id: "pprof-jl";
370
906
  readonly formats: ["pprof"];
@@ -381,6 +917,11 @@ declare const originSpecs: ({
381
917
  readonly path: string;
382
918
  readonly line?: number | undefined;
383
919
  readonly column?: number | undefined;
920
+ } | {
921
+ readonly type: `logical`;
922
+ readonly name: string;
923
+ readonly line?: number | undefined;
924
+ readonly column?: number | undefined;
384
925
  } | undefined;
385
926
  }) => boolean;
386
927
  readonly categorizeEntry: (entry: {
@@ -396,12 +937,43 @@ declare const originSpecs: ({
396
937
  readonly path: string;
397
938
  readonly line?: number | undefined;
398
939
  readonly column?: number | undefined;
940
+ } | {
941
+ readonly type: `logical`;
942
+ readonly name: string;
943
+ readonly line?: number | undefined;
944
+ readonly column?: number | undefined;
399
945
  } | undefined;
400
- }) => EntryCategory;
401
- readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame | null;
946
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
947
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
402
948
  } | {
403
- readonly id: "py-spy";
404
- readonly formats: ["collapsed", "speedscope"];
949
+ readonly id: "profile-jl";
950
+ readonly title: "Profile";
951
+ readonly formats: ["v8-heap-snapshot"];
952
+ readonly isMarkerEntry: ({ name, location }: {
953
+ readonly id: number;
954
+ readonly name?: string | undefined;
955
+ readonly location?: {
956
+ readonly type: `absolute`;
957
+ readonly url: URL;
958
+ readonly line?: number | undefined;
959
+ readonly column?: number | undefined;
960
+ } | {
961
+ readonly type: `relative`;
962
+ readonly path: string;
963
+ readonly line?: number | undefined;
964
+ readonly column?: number | undefined;
965
+ } | {
966
+ readonly type: `logical`;
967
+ readonly name: string;
968
+ readonly line?: number | undefined;
969
+ readonly column?: number | undefined;
970
+ } | undefined;
971
+ }) => boolean;
972
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
973
+ readonly categorizeHeapSnapshotDeclaredType: (declaredType: string) => HeapSnapshotNodeCategory | undefined;
974
+ } | {
975
+ readonly id: "pyinstrument";
976
+ readonly formats: ["speedscope"];
405
977
  readonly isMarkerEntry: (entry: {
406
978
  readonly id: number;
407
979
  readonly name?: string | undefined;
@@ -415,13 +987,45 @@ declare const originSpecs: ({
415
987
  readonly path: string;
416
988
  readonly line?: number | undefined;
417
989
  readonly column?: number | undefined;
990
+ } | {
991
+ readonly type: `logical`;
992
+ readonly name: string;
993
+ readonly line?: number | undefined;
994
+ readonly column?: number | undefined;
418
995
  } | undefined;
419
996
  }) => boolean;
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;
997
+ readonly categorizeEntry: (entry: {
998
+ readonly id: number;
999
+ readonly name?: string | undefined;
1000
+ readonly location?: {
1001
+ readonly type: `absolute`;
1002
+ readonly url: URL;
1003
+ readonly line?: number | undefined;
1004
+ readonly column?: number | undefined;
1005
+ } | {
1006
+ readonly type: `relative`;
1007
+ readonly path: string;
1008
+ readonly line?: number | undefined;
1009
+ readonly column?: number | undefined;
1010
+ } | {
1011
+ readonly type: `logical`;
1012
+ readonly name: string;
1013
+ readonly line?: number | undefined;
1014
+ readonly column?: number | undefined;
1015
+ } | undefined;
1016
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1017
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame | {
1018
+ location: {
1019
+ type: `file`;
1020
+ urlOrPath: string;
1021
+ column?: number;
1022
+ };
1023
+ name?: string;
1024
+ line?: number;
1025
+ } | null;
422
1026
  } | {
423
- readonly id: "tachyon";
424
- readonly formats: ["collapsed"];
1027
+ readonly id: "py-spy";
1028
+ readonly formats: ["collapsed", "speedscope"];
425
1029
  readonly isMarkerEntry: (entry: {
426
1030
  readonly id: number;
427
1031
  readonly name?: string | undefined;
@@ -435,13 +1039,18 @@ declare const originSpecs: ({
435
1039
  readonly path: string;
436
1040
  readonly line?: number | undefined;
437
1041
  readonly column?: number | undefined;
1042
+ } | {
1043
+ readonly type: `logical`;
1044
+ readonly name: string;
1045
+ readonly line?: number | undefined;
1046
+ readonly column?: number | undefined;
438
1047
  } | undefined;
439
1048
  }) => boolean;
440
- readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => EntryCategory;
441
- readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
1049
+ 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;
442
1051
  } | {
443
- readonly id: "jvm";
444
- readonly formats: ["jfr", "collapsed"];
1052
+ readonly id: "tachyon";
1053
+ readonly formats: ["collapsed"];
445
1054
  readonly isMarkerEntry: (entry: {
446
1055
  readonly id: number;
447
1056
  readonly name?: string | undefined;
@@ -455,9 +1064,19 @@ declare const originSpecs: ({
455
1064
  readonly path: string;
456
1065
  readonly line?: number | undefined;
457
1066
  readonly column?: number | undefined;
1067
+ } | {
1068
+ readonly type: `logical`;
1069
+ readonly name: string;
1070
+ readonly line?: number | undefined;
1071
+ readonly column?: number | undefined;
458
1072
  } | undefined;
459
1073
  }) => boolean;
460
- readonly categorizeEntry: (entry: {
1074
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1075
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1076
+ } | {
1077
+ readonly id: "async-profiler";
1078
+ readonly formats: ["jfr", "collapsed"];
1079
+ readonly isMarkerEntry: (entry: {
461
1080
  readonly id: number;
462
1081
  readonly name?: string | undefined;
463
1082
  readonly location?: {
@@ -470,10 +1089,24 @@ declare const originSpecs: ({
470
1089
  readonly path: string;
471
1090
  readonly line?: number | undefined;
472
1091
  readonly column?: number | undefined;
1092
+ } | {
1093
+ readonly type: `logical`;
1094
+ readonly name: string;
1095
+ readonly line?: number | undefined;
1096
+ readonly column?: number | undefined;
473
1097
  } | undefined;
474
- }) => EntryCategory;
1098
+ }) => boolean;
1099
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1100
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1101
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1102
+ } | {
1103
+ readonly id: "jdk";
1104
+ readonly title: "JDK";
1105
+ readonly formats: ["jfr", "hprof"];
1106
+ readonly isMarkerEntry: () => false;
1107
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1108
+ readonly categorizeHeapSnapshotConstructor: (name: string) => HeapSnapshotNodeCategory | undefined;
475
1109
  readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
476
- readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
477
1110
  } | {
478
1111
  readonly id: "dotnet-trace";
479
1112
  readonly formats: ["speedscope"];
@@ -490,6 +1123,11 @@ declare const originSpecs: ({
490
1123
  readonly path: string;
491
1124
  readonly line?: number | undefined;
492
1125
  readonly column?: number | undefined;
1126
+ } | {
1127
+ readonly type: `logical`;
1128
+ readonly name: string;
1129
+ readonly line?: number | undefined;
1130
+ readonly column?: number | undefined;
493
1131
  } | undefined;
494
1132
  }) => boolean;
495
1133
  readonly categorizeEntry: (entry: {
@@ -505,11 +1143,16 @@ declare const originSpecs: ({
505
1143
  readonly path: string;
506
1144
  readonly line?: number | undefined;
507
1145
  readonly column?: number | undefined;
1146
+ } | {
1147
+ readonly type: `logical`;
1148
+ readonly name: string;
1149
+ readonly line?: number | undefined;
1150
+ readonly column?: number | undefined;
508
1151
  } | undefined;
509
- }) => EntryCategory;
510
- readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame | null;
1152
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1153
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
511
1154
  } | {
512
- readonly id: "beam";
1155
+ readonly id: "eflambe";
513
1156
  readonly formats: ["collapsed"];
514
1157
  readonly isMarkerEntry: (entry: {
515
1158
  readonly id: number;
@@ -524,8 +1167,14 @@ declare const originSpecs: ({
524
1167
  readonly path: string;
525
1168
  readonly line?: number | undefined;
526
1169
  readonly column?: number | undefined;
1170
+ } | {
1171
+ readonly type: `logical`;
1172
+ readonly name: string;
1173
+ readonly line?: number | undefined;
1174
+ readonly column?: number | undefined;
527
1175
  } | undefined;
528
1176
  }) => 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;
529
1178
  readonly categorizeEntry: (entry: {
530
1179
  readonly id: number;
531
1180
  readonly name?: string | undefined;
@@ -539,12 +1188,43 @@ declare const originSpecs: ({
539
1188
  readonly path: string;
540
1189
  readonly line?: number | undefined;
541
1190
  readonly column?: number | undefined;
1191
+ } | {
1192
+ readonly type: `logical`;
1193
+ readonly name: string;
1194
+ readonly line?: number | undefined;
1195
+ readonly column?: number | undefined;
542
1196
  } | undefined;
543
- }) => EntryCategory;
544
- readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
1197
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1198
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1199
+ } | {
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;
1207
+ readonly name?: string | undefined;
1208
+ readonly location?: {
1209
+ readonly type: `absolute`;
1210
+ readonly url: URL;
1211
+ readonly line?: number | undefined;
1212
+ readonly column?: number | undefined;
1213
+ } | {
1214
+ readonly type: `relative`;
1215
+ readonly path: string;
1216
+ readonly line?: number | undefined;
1217
+ readonly column?: number | undefined;
1218
+ } | {
1219
+ readonly type: `logical`;
1220
+ readonly name: string;
1221
+ readonly line?: number | undefined;
1222
+ readonly column?: number | undefined;
1223
+ } | undefined;
1224
+ }) => boolean;
545
1225
  } | {
546
1226
  readonly id: "rbspy";
547
- readonly formats: ["collapsed", "pprof", "speedscope"];
1227
+ readonly formats: ["callgrind", "collapsed", "pprof", "speedscope"];
548
1228
  readonly isMarkerEntry: (entry: {
549
1229
  readonly id: number;
550
1230
  readonly name?: string | undefined;
@@ -558,6 +1238,11 @@ declare const originSpecs: ({
558
1238
  readonly path: string;
559
1239
  readonly line?: number | undefined;
560
1240
  readonly column?: number | undefined;
1241
+ } | {
1242
+ readonly type: `logical`;
1243
+ readonly name: string;
1244
+ readonly line?: number | undefined;
1245
+ readonly column?: number | undefined;
561
1246
  } | undefined;
562
1247
  }) => boolean;
563
1248
  readonly categorizeEntry: (entry: {
@@ -573,16 +1258,19 @@ declare const originSpecs: ({
573
1258
  readonly path: string;
574
1259
  readonly line?: number | undefined;
575
1260
  readonly column?: number | undefined;
1261
+ } | {
1262
+ readonly type: `logical`;
1263
+ readonly name: string;
1264
+ readonly line?: number | undefined;
1265
+ readonly column?: number | undefined;
576
1266
  } | undefined;
577
- }) => EntryCategory;
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;
1267
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "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;
579
1269
  } | {
580
1270
  readonly id: "safari";
1271
+ readonly title: "Safari";
581
1272
  readonly formats: ["jsc-heap-snapshot", "webkit-timeline-recording"];
582
- readonly isMarkerEntry: ({
583
- name,
584
- location
585
- }: DeepReadonly<ProfileEntry>) => boolean;
1273
+ readonly isMarkerEntry: ({ name, location }: DeepReadonly<ProfileEntry>) => boolean;
586
1274
  readonly categorizeEntry: (entry: {
587
1275
  readonly id: number;
588
1276
  readonly name?: string | undefined;
@@ -596,8 +1284,14 @@ declare const originSpecs: ({
596
1284
  readonly path: string;
597
1285
  readonly line?: number | undefined;
598
1286
  readonly column?: number | undefined;
1287
+ } | {
1288
+ readonly type: `logical`;
1289
+ readonly name: string;
1290
+ readonly line?: number | undefined;
1291
+ readonly column?: number | undefined;
599
1292
  } | undefined;
600
- }) => EntryCategory;
1293
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1294
+ readonly categorizeHeapSnapshotConstructor: (name: string) => "string" | "number" | "symbol" | "object" | "function" | "unknown" | "native" | "regexp" | "array" | "concatenated string" | "sliced string" | "code" | "big number" | "object shape" | "internal" | "synthetic" | undefined;
601
1295
  } | {
602
1296
  readonly id: "systing";
603
1297
  readonly formats: ["systing"];
@@ -614,6 +1308,11 @@ declare const originSpecs: ({
614
1308
  readonly path: string;
615
1309
  readonly line?: number | undefined;
616
1310
  readonly column?: number | undefined;
1311
+ } | {
1312
+ readonly type: `logical`;
1313
+ readonly name: string;
1314
+ readonly line?: number | undefined;
1315
+ readonly column?: number | undefined;
617
1316
  } | undefined;
618
1317
  }) => boolean;
619
1318
  readonly categorizeEntry: (entry: {
@@ -629,12 +1328,53 @@ declare const originSpecs: ({
629
1328
  readonly path: string;
630
1329
  readonly line?: number | undefined;
631
1330
  readonly column?: number | undefined;
1331
+ } | {
1332
+ readonly type: `logical`;
1333
+ readonly name: string;
1334
+ readonly line?: number | undefined;
1335
+ readonly column?: number | undefined;
1336
+ } | undefined;
1337
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1338
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1339
+ } | {
1340
+ readonly id: "gperftools";
1341
+ readonly formats: ["pprof"];
1342
+ readonly isMarkerEntry: () => false;
1343
+ readonly categorizeEntry: (entry: {
1344
+ readonly id: number;
1345
+ readonly name?: string | undefined;
1346
+ readonly location?: {
1347
+ readonly type: `absolute`;
1348
+ readonly url: URL;
1349
+ readonly line?: number | undefined;
1350
+ readonly column?: number | undefined;
1351
+ } | {
1352
+ readonly type: `relative`;
1353
+ readonly path: string;
1354
+ readonly line?: number | undefined;
1355
+ readonly column?: number | undefined;
1356
+ } | {
1357
+ readonly type: `logical`;
1358
+ readonly name: string;
1359
+ readonly line?: number | undefined;
1360
+ readonly column?: number | undefined;
632
1361
  } | undefined;
633
- }) => EntryCategory;
634
- readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
1362
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
635
1363
  } | {
636
- readonly id: "unknown";
637
- readonly formats: [];
1364
+ readonly id: "excimer";
1365
+ readonly title: "Excimer";
1366
+ readonly formats: ["speedscope"];
1367
+ readonly isMarkerEntry: () => false;
1368
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1369
+ } | {
1370
+ readonly id: "memray";
1371
+ readonly formats: ["memray"];
1372
+ readonly isMarkerEntry: () => false;
1373
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1374
+ } | {
1375
+ readonly id: "ghc";
1376
+ readonly title: "GHC";
1377
+ readonly formats: ["ghc-eventlog", "ghc-json-profile"];
638
1378
  readonly isMarkerEntry: () => false;
639
1379
  readonly categorizeEntry: (entry: {
640
1380
  readonly id: number;
@@ -649,240 +1389,234 @@ declare const originSpecs: ({
649
1389
  readonly path: string;
650
1390
  readonly line?: number | undefined;
651
1391
  readonly column?: number | undefined;
1392
+ } | {
1393
+ readonly type: `logical`;
1394
+ readonly name: string;
1395
+ readonly line?: number | undefined;
1396
+ readonly column?: number | undefined;
652
1397
  } | undefined;
653
- }) => EntryCategory;
1398
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1399
+ } | {
1400
+ readonly id: "simpleperf";
1401
+ readonly formats: ["perf"];
1402
+ readonly isMarkerEntry: () => false;
1403
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1404
+ } | {
1405
+ readonly id: "perf";
1406
+ readonly formats: ["perf"];
1407
+ readonly isMarkerEntry: () => false;
1408
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1409
+ } | {
1410
+ readonly id: "unknown";
1411
+ readonly formats: [];
1412
+ readonly isMarkerEntry: () => false;
1413
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
654
1414
  })[];
1415
+ //#endregion
1416
+ //#region src/origins/index.d.ts
1417
+ /**
1418
+ * The profiler tool or runtime that wrote an input (e.g. `node` for
1419
+ * Node's native V8 profiler, `node-pprof` for the `pprof` npm package,
1420
+ * `async-profiler` for async-profiler's JFR and collapsed output).
1421
+ *
1422
+ * Auto-detected from a profile's entries via {@link OriginDetector}, or
1423
+ * specified explicitly.
1424
+ */
1425
+ type Origin = SpecificOriginSpec[`id`];
655
1426
  /** One of the concrete origin specs, with its literal {@link Origin} ID. */
656
1427
  type SpecificOriginSpec = (typeof originSpecs)[number];
657
- /** Every supported origin ID. */
658
1428
  //#endregion
659
- //#region src/modalities/profile/aggregate.d.ts
660
- /** An aggregation of samples taken at a given line within a function's body. */
661
- type AggregatedProfileLineMetrics = {
1429
+ //#region src/modalities/call-graph/aggregate.d.ts
1430
+ /** One function's recorded costs during calls from a given direct caller. */
1431
+ type AggregatedCallGraphCallerMetrics = {
1432
+ /** The caller corresponding to the ID. */
1433
+ caller: AggregatedCallGraphFunction;
1434
+ /** The recorded number of calls, or `0` when the format records none. */
1435
+ callCount: number;
662
1436
  /**
663
- * The number of samples taken directly within the function's body at this
664
- * line.
1437
+ * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
1438
+ * in the function and its callees during calls from this caller.
665
1439
  */
666
- sampleCount: number;
1440
+ totalValues: Float64Array;
1441
+ };
1442
+ /** One function's recorded costs during its calls to a given direct callee. */
1443
+ type AggregatedCallGraphCalleeMetrics = {
1444
+ /** The callee corresponding to the ID. */
1445
+ callee: AggregatedCallGraphFunction;
1446
+ /** The recorded number of calls, or `0` when the format records none. */
1447
+ callCount: number;
667
1448
  /**
668
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
669
- * samples taken directly within the function's body at this line.
1449
+ * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
1450
+ * in the callee and its callees during this function's calls to it.
670
1451
  */
671
- values: Float64Array;
1452
+ totalValues: Float64Array;
672
1453
  };
673
- /**
674
- * An aggregation of samples taken directly within a function's body with a
675
- * given direct caller.
676
- */
677
- type AggregatedProfileCallerMetrics = {
678
- /** The caller corresponding to the ID. */caller: AggregatedProfileFunction;
1454
+ /** An aggregation of one function's recorded costs within a call graph. */
1455
+ type AggregatedCallGraphFunction = {
1456
+ type: `function`;
1457
+ /** An index that uniquely identifies this function. */
1458
+ id: number;
1459
+ /** The name of the function in code. */
1460
+ name: string;
1461
+ /** Where the function was defined, if known. */
1462
+ location?: SourceLocation;
1463
+ /** The category of functions this function belongs to. */
1464
+ category: FunctionCategory;
679
1465
  /**
680
- * The number of samples taken directly within the function's body with this
681
- * caller.
1466
+ * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
1467
+ * directly in the function's body, excluding its callees.
682
1468
  */
683
- selfSampleCount: number;
1469
+ selfValues: Float64Array;
684
1470
  /**
685
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
686
- * samples taken directly within the function's body with this caller.
1471
+ * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
1472
+ * in the function's body and all its callees: its self values plus its
1473
+ * outgoing arcs' inclusive values, excluding the arcs to functions in its own
1474
+ * recursion cycle, which re-count the same work.
687
1475
  */
688
- selfValues: Float64Array;
1476
+ totalValues: Float64Array;
1477
+ /** 1-based line number to the self values recorded at that line. */
1478
+ lineToMetrics: Map<number, Float64Array>;
1479
+ /** Direct caller ID to the costs recorded during that caller's calls. */
1480
+ callerIdToMetrics: Map<number, AggregatedCallGraphCallerMetrics>;
1481
+ /** Direct callee ID to the costs recorded during calls to that callee. */
1482
+ calleeIdToMetrics: Map<number, AggregatedCallGraphCalleeMetrics>;
689
1483
  };
1484
+ //#endregion
1485
+ //#region src/modalities/call-stack-profile/aggregate.d.ts
690
1486
  /**
691
- * An aggregation of samples taken within a function's body, _and_ all its
692
- * callees, with a given direct callee.
1487
+ * An aggregation of observations recorded at a given line within a function's
1488
+ * body.
693
1489
  */
694
- type AggregatedProfileCalleeMetrics = {
695
- /** The callee corresponding to the ID. */callee: AggregatedProfileFunction;
696
- /**
697
- * The number of samples taken directly within the function's body, _and_
698
- * all its callees, with this callee.
699
- */
700
- totalSampleCount: number;
1490
+ type AggregatedCallStackProfileLineMetrics = {
701
1491
  /**
702
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
703
- * samples taken directly within the function's body, _and_ all its
704
- * callees, with this callee.
1492
+ * The number of observations recorded directly within the function's body at
1493
+ * this line.
705
1494
  */
706
- totalValues: Float64Array;
1495
+ count: number;
707
1496
  /**
708
- * Internal aggregation bookkeeping: the epoch of the most recent call stack
709
- * whose total this frame pair was counted into, so one that recurs within
710
- * one call stack is counted just once.
1497
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
1498
+ * values from observations recorded directly within the function's body at
1499
+ * this line.
711
1500
  */
712
- lastSeenEpoch: number;
1501
+ values: Float64Array;
713
1502
  };
714
1503
  /**
715
- * An aggregation of data from every sample involving a given function within a
716
- * profile.
1504
+ * An aggregation of observations recorded directly within a function's body
1505
+ * with a given direct caller.
717
1506
  */
718
- type AggregatedProfileFunction = {
719
- type: `function`; /** An index that uniquely identifies this function. */
720
- id: number; /** The name of the function in code. */
721
- name: string; /** Where the function was defined, if known. */
722
- location?: SourceLocation; /** The category of functions this function belongs to. */
723
- category: string;
724
- /**
725
- * The number of samples taken directly within the function's body, excluding
726
- * its callees.
727
- */
728
- selfSampleCount: number;
1507
+ type AggregatedCallStackProfileCallerMetrics = {
1508
+ /** The caller corresponding to the ID. */
1509
+ caller: AggregatedCallStackProfileFunction;
729
1510
  /**
730
- * The number of samples taken directly within the function's body _and_ all
731
- * its callees.
1511
+ * The number of observations recorded directly within the function's body
1512
+ * with this caller.
732
1513
  */
733
- totalSampleCount: number;
1514
+ selfCount: number;
734
1515
  /**
735
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from samples
736
- * taken directly within the function's body, excluding its callees.
1516
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
1517
+ * values from observations recorded directly within the function's body with
1518
+ * this caller.
737
1519
  */
738
1520
  selfValues: Float64Array;
739
- /**
740
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from samples
741
- * taken directly within the function's body _and_ all its callees.
742
- */
743
- totalValues: Float64Array; /** 1-based line number to values and sample count for that line. */
744
- lineToMetrics: Map<number, AggregatedProfileLineMetrics>;
745
- /**
746
- * Direct caller id to values and sample count with that caller's calls to
747
- * this function.
748
- */
749
- callerIdToMetrics: Map<number, AggregatedProfileCallerMetrics>;
750
- /**
751
- * Direct callee id to values and sample count for that callee's calls where
752
- * this function was a direct or transitive caller.
753
- */
754
- calleeIdToMetrics: Map<number, AggregatedProfileCalleeMetrics>;
755
1521
  };
756
- //#endregion
757
- //#region src/modalities/snapshot/graph.d.ts
758
1522
  /**
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)
1523
+ * An aggregation of observations recorded within a function's body, _and_ all
1524
+ * its callees, with a given direct callee.
762
1525
  */
763
- type NodeAdjacencyGraph = {
1526
+ type AggregatedCallStackProfileCalleeMetrics = {
1527
+ /** The callee corresponding to the ID. */
1528
+ callee: AggregatedCallStackProfileFunction;
764
1529
  /**
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])`.
1530
+ * The number of observations recorded directly within the function's body,
1531
+ * _and_ all its callees, with this callee.
775
1532
  */
776
- ordinalToSuccessorStartOffset: Int32Array;
1533
+ totalCount: number;
777
1534
  /**
778
- * Successor ordinals, packed contiguously and indexed via
779
- * {@link NodeAdjacencyGraph.ordinalToSuccessorStartOffset}.
1535
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
1536
+ * values from observations recorded directly within the function's body,
1537
+ * _and_ all its callees, with this callee.
780
1538
  */
781
- offsetToSuccessorOrdinal: Int32Array;
1539
+ totalValues: Float64Array;
782
1540
  /**
783
- * Successor edge indices, packed contiguously and indexed via
784
- * {@link NodeAdjacencyGraph.ordinalToSuccessorStartOffset}.
1541
+ * Internal aggregation bookkeeping: the epoch of the most recent call stack
1542
+ * whose total this frame pair was counted into, so one that recurs within
1543
+ * one call stack is counted just once.
785
1544
  */
786
- offsetToSuccessorEdgeIndex: Int32Array;
1545
+ lastSeenEpoch: number;
1546
+ };
1547
+ /**
1548
+ * An aggregation of data from every observation involving a given function
1549
+ * within a profile.
1550
+ */
1551
+ type AggregatedCallStackProfileFunction = {
1552
+ type: `function`;
1553
+ /** An index that uniquely identifies this function. */
1554
+ id: number;
1555
+ /** The name of the function in code. */
1556
+ name: string;
1557
+ /** Where the function was defined, if known. */
1558
+ location?: SourceLocation;
1559
+ /** The category of functions this function belongs to. */
1560
+ category: FunctionCategory;
787
1561
  /**
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])`.
1562
+ * The number of observations recorded directly within the function's body,
1563
+ * excluding its callees.
798
1564
  */
799
- ordinalToPredecessorStartOffset: Int32Array;
1565
+ selfCount: number;
800
1566
  /**
801
- * Predecessor ordinals, packed contiguously and indexed via
802
- * {@link NodeAdjacencyGraph.ordinalToPredecessorStartOffset}.
1567
+ * The number of observations recorded directly within the function's body
1568
+ * _and_ all its callees.
803
1569
  */
804
- offsetToPredecessorOrdinal: Int32Array;
1570
+ totalCount: number;
805
1571
  /**
806
- * Predecessor edge indices, packed contiguously and indexed via
807
- * {@link NodeAdjacencyGraph.ordinalToPredecessorStartOffset}.
1572
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
1573
+ * values from observations recorded directly within the function's body,
1574
+ * excluding its callees.
808
1575
  */
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;
1576
+ selfValues: Float64Array;
825
1577
  /**
826
- * One entry per node ordinal, in ordinal order, as a lazily-consumed
827
- * iterable.
1578
+ * For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
1579
+ * values from observations recorded directly within the function's body _and_
1580
+ * all its callees.
828
1581
  */
829
- nodes: Iterable<SnapshotNode>;
1582
+ totalValues: Float64Array;
1583
+ /** 1-based line number to values and count for that line. */
1584
+ lineToMetrics: Map<number, AggregatedCallStackProfileLineMetrics>;
830
1585
  /**
831
- * Formats an edge label, which is computed lazily at formatting time, so it
832
- * receives the resolved formatting options.
1586
+ * Direct caller id to values and count with that caller's calls to
1587
+ * this function.
833
1588
  */
834
- formatEdgeLabel: (retainerOrdinal: number, edgeIndex: number, options: FormattingProfileToMdOptions) => string;
1589
+ callerIdToMetrics: Map<number, AggregatedCallStackProfileCallerMetrics>;
835
1590
  /**
836
- * Formats a node label, which is computed lazily at formatting time, so it
837
- * receives the resolved formatting options.
1591
+ * Direct callee id to values and count for that callee's calls where
1592
+ * this function was a direct or transitive caller.
838
1593
  */
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;
1594
+ calleeIdToMetrics: Map<number, AggregatedCallStackProfileCalleeMetrics>;
841
1595
  };
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
1596
  //#endregion
869
- //#region src/modalities/snapshot/aggregate.d.ts
870
- type AggregatedSnapshotNode = {
871
- type: `node`; /** Unique ID for this node that can also be used as an index. */
872
- id: number; /** A human readable label for this node. */
1597
+ //#region src/modalities/heap-snapshot/aggregate.d.ts
1598
+ type AggregatedHeapSnapshotNode = {
1599
+ type: `node`;
1600
+ /** Unique ID for this node that can also be used as an index. */
1601
+ id: number;
1602
+ /** A human readable label for this node. */
873
1603
  name?: string;
874
1604
  /**
875
1605
  * The file reference the {@link name} parses as, when it is URL-shaped
876
1606
  * (e.g. a V8 module namespace object named by its file URL). Formatting
877
1607
  * shows it relative to the base URL in place of the raw name.
878
1608
  */
879
- nameLocation?: FileReference; /** Bytes allocated directly for this node. */
1609
+ nameLocation?: FileReference;
1610
+ /** Bytes allocated directly for this node. */
880
1611
  selfSize: number;
1612
+ /** What this node holds. */
1613
+ category: HeapSnapshotNodeCategory;
881
1614
  /**
882
1615
  * Bytes allocated for this node, as well as all nodes that would be freed if
883
1616
  * the node were garbage collected.
884
1617
  */
885
- retainedSize: number; /** The exact location where the node was defined. */
1618
+ retainedSize: number;
1619
+ /** The exact location where the node was defined. */
886
1620
  location?: SourceLocation;
887
1621
  };
888
1622
  //#endregion
@@ -908,19 +1642,46 @@ type ProfileInput<Data> = Data | {
908
1642
  format?: Format;
909
1643
  origin?: Origin;
910
1644
  };
911
- /** The category of code an entry originated from. */
912
- type EntryCategory = `ours` | `native` | `stdlib` | `third-party` | (string & {});
1645
+ /**
1646
+ * The category of code a function originated from.
1647
+ *
1648
+ * A closed set, so a category names the same thing whichever origin wrote the
1649
+ * input and formatting can partition by it. The first three record where the
1650
+ * code came from, the next two what the profiler could determine about a frame
1651
+ * with no source file, and the rest name a runtime activity.
1652
+ *
1653
+ * These boundaries decide most assignments:
1654
+ *
1655
+ * - `stdlib` requires positive evidence that the code is the language's or
1656
+ * runtime's own library: a standard-library path, module specifier,
1657
+ * namespace, or package prefix. A missing source file is never evidence for
1658
+ * `stdlib`
1659
+ * - `native` is compiled code the profiler attributed to no source file, plus
1660
+ * code located in a shared library or in a runtime's own C/C++ sources.
1661
+ * `unknown` is a frame the profiler could not identify, a weaker claim,
1662
+ * because the code may be a function in the profiled language
1663
+ * - `compiler` is the runtime producing executable code, and `jit` is a frame
1664
+ * executing code the runtime generated. Where a frame both executes generated
1665
+ * code and does the work of a named activity, the activity takes precedence,
1666
+ * so a garbage collection write barrier compiled inline is
1667
+ * `garbage collector`
1668
+ */
1669
+ type FunctionCategory = (typeof FUNCTION_CATEGORIES)[number];
1670
+ /** Every category {@link FunctionCategory} allows. */
1671
+ declare const FUNCTION_CATEGORIES: readonly ["ours", "third-party", "stdlib", "native", "unknown", "garbage collector", "compiler", "jit", "regexp", "kernel", "idle"];
913
1672
  /** A single entry in a formatted profile. */
914
1673
  type ProfileEntry = {
915
- /** An index that uniquely identifies this entry. */id: number;
1674
+ /** An index that uniquely identifies this entry. */
1675
+ id: number;
916
1676
  /**
917
1677
  * The name of the entity corresponding to this entry (e.g. a function name)
918
1678
  * if it has one.
919
1679
  */
920
1680
  name?: string;
921
1681
  /**
922
- * The location where the entity corresponding to this entry was defined, or
923
- * undefined if unknown.
1682
+ * The location where the entity corresponding to this entry was defined: a
1683
+ * file, or a logical name such as a JVM class or a BEAM module when the
1684
+ * runtime reports no file. Undefined if unknown.
924
1685
  */
925
1686
  location?: SourceLocation;
926
1687
  };
@@ -931,18 +1692,35 @@ type ProfileEntry = {
931
1692
  * unchanged.
932
1693
  */
933
1694
  type EntryMatch = {
934
- /** The name to match by. Omit to match by the entry's name. */name?: string;
1695
+ /** The name to match by. Omit to match by the entry's name. */
1696
+ name?: string;
935
1697
  /**
936
- * The location to match by, as a URL or file path string. Omit to match by
937
- * the entry's location.
1698
+ * The location to match by, as a URL, file path, or logical name string.
1699
+ * Omit to match by the entry's location. An empty string matches by name
1700
+ * alone.
938
1701
  */
939
1702
  location?: string;
940
1703
  };
1704
+ /**
1705
+ * The keys an entry is paired by across a diff's two sides, derived from its
1706
+ * {@link EntryMatch}.
1707
+ */
1708
+ type EntryMatchKeys = {
1709
+ /**
1710
+ * The key pairing entries by normalized name alone, for entities whose
1711
+ * location varies between profiles of the same program.
1712
+ */
1713
+ name: string;
1714
+ /** The key pairing entries by normalized name and location. */
1715
+ nameAndLocation: string;
1716
+ };
941
1717
  /** An aggregated entry in a formatted profile. */
942
- type AggregatedProfileEntry = AggregatedProfileFunction | AggregatedSnapshotNode;
1718
+ type AggregatedProfileEntry = AggregatedCallStackProfileFunction | AggregatedCallGraphFunction | AggregatedHeapSnapshotNode;
943
1719
  /** The context in which a profile is being converted to Markdown. */
944
1720
  type ProfileToMdContext = {
945
- /** The format of the profile being converted. */format: Format; /** The origin of the profile being converted. */
1721
+ /** The format of the profile being converted. */
1722
+ format: Format;
1723
+ /** The origin of the profile being converted. */
946
1724
  origin: Origin;
947
1725
  };
948
1726
  /** Options for profile to Markdown converters. */
@@ -950,11 +1728,34 @@ type ProfileToMdOptions = {
950
1728
  /**
951
1729
  * The number of entries to display when computing the "top N" by some metric.
952
1730
  *
1731
+ * Applies to each ranking rather than to the output as a whole, so a ranking
1732
+ * split into per-category subsections displays up to this many entries in
1733
+ * every one of them. See {@link minCategoryShare}.
1734
+ *
953
1735
  * This value, divided by a constant, also limits subsection entry count.
954
1736
  *
955
1737
  * Defaults to 20.
956
1738
  */
957
1739
  topN?: number;
1740
+ /**
1741
+ * The share of a profile a category must account for to be broken down into
1742
+ * its own subsection, as a fraction between 0 and 1.
1743
+ *
1744
+ * A ranking splits into one subsection per category that meets this, each
1745
+ * ranking that category's own entries. A category below it is dropped from
1746
+ * the subsections, though the category breakdown still reports its totals.
1747
+ *
1748
+ * A category's share is measured over the self values of the entries
1749
+ * {@link showEntry} keeps, so the threshold applies to the entries the
1750
+ * subsections display rather than to every entry in the profile. Total values
1751
+ * include callees, so they double count and their shares add up to more
1752
+ * than 1.
1753
+ *
1754
+ * Pass 0 to break down every category.
1755
+ *
1756
+ * Defaults to 0.01.
1757
+ */
1758
+ minCategoryShare?: number;
958
1759
  /**
959
1760
  * Base URL to show paths relative to in the Markdown output.
960
1761
  *
@@ -962,9 +1763,8 @@ type ProfileToMdOptions = {
962
1763
  * `file://` URLs internally.
963
1764
  *
964
1765
  * 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.
1766
+ * of the input's entries with absolute locations (`file:`, `http(s):`, etc.),
1767
+ * across all profiles of an input and across both sides of a diff.
968
1768
  *
969
1769
  * A value of `null` leaves URLs absolute.
970
1770
  *
@@ -998,8 +1798,11 @@ type ProfileToMdOptions = {
998
1798
  */
999
1799
  matchEntry?: (entry: DeepReadonly<ProfileEntry>, context: ProfileToMdContext) => EntryMatch | undefined;
1000
1800
  /**
1001
- * Returns a category string per entry of a profile, as an array aligned with
1002
- * {@link entries} (index `i` categorizes entry `i`).
1801
+ * Returns a {@link FunctionCategory} per entry of a profile, as an array
1802
+ * aligned with {@link entries} (index `i` categorizes entry `i`).
1803
+ *
1804
+ * The categories are a closed set, so a category names the same thing
1805
+ * whichever origin wrote the input.
1003
1806
  *
1004
1807
  * Used to compute:
1005
1808
  * - A category breakdown in the Markdown output
@@ -1010,9 +1813,12 @@ type ProfileToMdOptions = {
1010
1813
  * up front lets the categorizer decide from the full set rather than per
1011
1814
  * entry in isolation.
1012
1815
  *
1013
- * Defaults to {@link defaultCategorizeEntries}.
1816
+ * Doesn't apply to heap snapshots because they record their own node
1817
+ * categories.
1818
+ *
1819
+ * Defaults to {@link defaultCategorizeFunctions}.
1014
1820
  */
1015
- categorizeEntries?: (entries: readonly DeepReadonly<ProfileEntry>[], context: ProfileToMdContext) => readonly EntryCategory[];
1821
+ categorizeFunctions?: (entries: readonly DeepReadonly<ProfileEntry>[], context: ProfileToMdContext) => readonly FunctionCategory[];
1016
1822
  /**
1017
1823
  * Whether to include the given entry in the Markdown output.
1018
1824
  *
@@ -1020,16 +1826,17 @@ type ProfileToMdOptions = {
1020
1826
  *
1021
1827
  * Defaults to {@link defaultShowEntry}.
1022
1828
  */
1023
- showEntry?: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
1829
+ showEntry?: (entry: DeepReadonly<AggregatedProfileEntry>, context: ProfileToMdContext) => boolean;
1024
1830
  };
1025
1831
  /** {@link ProfileToMdOptions} with defaults applied. */
1026
1832
  type NormalizedProfileToMdOptions = {
1027
1833
  topN: number;
1834
+ minCategoryShare: number;
1028
1835
  baseURL: URL | `auto` | undefined;
1029
1836
  sourceMaps: NormalizedSourceMaps;
1030
- entryMatchKey: (entry: ProfileEntry, context: ProfileToMdContext) => string;
1031
- categorizeEntries: (entries: readonly ProfileEntry[], context: ProfileToMdContext) => readonly EntryCategory[];
1032
- showEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
1837
+ entryMatchKeys: (entry: ProfileEntry, context: ProfileToMdContext) => EntryMatchKeys;
1838
+ categorizeFunctions: (entries: readonly ProfileEntry[], context: ProfileToMdContext) => readonly FunctionCategory[];
1839
+ showEntry: (entry: DeepReadonly<AggregatedProfileEntry>, context: ProfileToMdContext) => boolean;
1033
1840
  };
1034
1841
  /**
1035
1842
  * The options aggregation code receives.
@@ -1053,23 +1860,21 @@ type FormattingProfileToMdOptions = AggregationProfileToMdOptions & {
1053
1860
  *
1054
1861
  * Applies the origin's match normalization to the entry, stripping the origin's
1055
1862
  * 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.
1863
+ * runtime addresses for `jdk`), or `undefined` if the entry contains none.
1057
1864
  */
1058
- declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>, {
1059
- origin
1060
- }: ProfileToMdContext) => EntryMatch | undefined;
1865
+ declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>, { origin }: ProfileToMdContext) => EntryMatch | undefined;
1061
1866
  /**
1062
- * The default {@link ProfileToMdOptions.categorizeEntries}.
1867
+ * The default {@link ProfileToMdOptions.categorizeFunctions}.
1063
1868
  *
1064
1869
  * Applies the library's origin-aware categorization to each entry.
1065
1870
  */
1066
- declare const defaultCategorizeEntries: (entries: readonly DeepReadonly<ProfileEntry>[], {
1067
- origin
1068
- }: ProfileToMdContext) => EntryCategory[];
1871
+ declare const defaultCategorizeFunctions: (entries: readonly DeepReadonly<ProfileEntry>[], { origin }: ProfileToMdContext) => FunctionCategory[];
1069
1872
  /**
1070
1873
  * Returns whether to include the given entry in the Markdown output.
1071
1874
  *
1072
- * Excludes synthetic and external implementation detail entries.
1875
+ * Excludes synthetic entries, which correspond to nothing in the profiled
1876
+ * program. Every function it ran is shown, and each ranking breaks down by
1877
+ * category, so a reader chooses which code to read.
1073
1878
  */
1074
1879
  declare const defaultShowEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
1075
1880
  /**
@@ -1077,120 +1882,11 @@ declare const defaultShowEntry: (entry: DeepReadonly<AggregatedProfileEntry>) =>
1077
1882
  *
1078
1883
  * The profiler invents these entries; they correspond to nothing that exists
1079
1884
  * in code or at runtime (e.g. a synthetic `(root)` node for heap snapshots).
1080
- */
1081
- declare const isSyntheticEntry: ({
1082
- name
1083
- }: DeepReadonly<AggregatedProfileEntry>) => boolean;
1084
- /**
1085
- * Returns true if the entry corresponds to an external function (`native`,
1086
- * `stdlib`, or `third-party`) that's never directly called by `ours` code.
1087
1885
  *
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.
1886
+ * A heap snapshot node holding text takes the text as its name, so a string
1887
+ * whose value equals a synthetic name is not a synthetic entry.
1091
1888
  */
1092
- declare const isExternalImplementationDetailEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
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;
1889
+ declare const isSyntheticEntry: ({ name, category }: DeepReadonly<AggregatedProfileEntry>) => boolean;
1194
1890
  //#endregion
1195
1891
  //#region src/formats/index.d.ts
1196
1892
  /**
@@ -1228,4 +1924,16 @@ declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileIn
1228
1924
  */
1229
1925
  declare const diffProfilesAsync: (base: ProfileInput<AsyncProfileData>, current: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
1230
1926
  //#endregion
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 };
1927
+ //#region src/error.d.ts
1928
+ /**
1929
+ * Thrown when a caller's input or options are unusable: an unrecognized
1930
+ * format, a malformed profile, an invalid option.
1931
+ *
1932
+ * A failure the caller cannot fix throws a plain `Error` instead, because such
1933
+ * a failure is a bug in this package.
1934
+ */
1935
+ declare class ProfilerMdError extends Error {
1936
+ constructor(message: string, options?: ErrorOptions);
1937
+ }
1938
+ //#endregion
1939
+ 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 };