profiler-md 0.5.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 (235) hide show
  1. package/dist/cli/index.mjs +14155 -5081
  2. package/dist/index.d.mts +1312 -263
  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 +3 -3
  11. package/docs/formats/jsc-heap-snapshot.md +11 -5
  12. package/docs/formats/memray.md +30 -0
  13. package/docs/formats/perf.md +74 -0
  14. package/docs/formats/pprof.md +10 -6
  15. package/docs/formats/speedscope.md +7 -5
  16. package/docs/formats/systing.md +27 -0
  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 +10 -5
  20. package/docs/formats/webkit-timeline-recording.md +6 -0
  21. package/docs/languages/c.md +138 -18
  22. package/docs/languages/csharp.md +7 -7
  23. package/docs/languages/elixir.md +22 -15
  24. package/docs/languages/fortran.md +141 -0
  25. package/docs/languages/go.md +36 -13
  26. package/docs/languages/haskell.md +134 -0
  27. package/docs/languages/java.md +89 -34
  28. package/docs/languages/javascript.md +37 -31
  29. package/docs/languages/julia.md +96 -14
  30. package/docs/languages/php.md +10 -4
  31. package/docs/languages/python.md +121 -15
  32. package/docs/languages/ruby.md +19 -22
  33. package/docs/languages/rust.md +40 -10
  34. package/docs/languages/swift.md +135 -0
  35. package/docs/languages/zig.md +155 -0
  36. package/package.json +47 -46
  37. package/readme.md +306 -242
  38. package/skills/profile-optimize/SKILL.md +162 -0
  39. package/docs/languages/cpp.md +0 -160
  40. package/docs/languages/erlang.md +0 -46
  41. package/docs/languages/fsharp.md +0 -52
  42. package/docs/languages/kotlin.md +0 -170
  43. package/docs/languages/typescript.md +0 -276
  44. package/examples/output/c.gperftools.cpu.base.pprof.md +0 -324
  45. package/examples/output/c.gperftools.cpu.current.pprof.md +0 -271
  46. package/examples/output/c.gperftools.cpu.diff.pprof.md +0 -98
  47. package/examples/output/c.gperftools.heap.base.pprof.md +0 -362
  48. package/examples/output/c.gperftools.heap.current.pprof.md +0 -362
  49. package/examples/output/c.gperftools.heap.diff.pprof.md +0 -28
  50. package/examples/output/cpp.gperftools.cpu.base.pprof.md +0 -557
  51. package/examples/output/cpp.gperftools.cpu.current.pprof.md +0 -573
  52. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +0 -122
  53. package/examples/output/cpp.gperftools.heap.base.pprof.md +0 -67
  54. package/examples/output/cpp.gperftools.heap.current.pprof.md +0 -67
  55. package/examples/output/cpp.gperftools.heap.diff.pprof.md +0 -19
  56. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +0 -411
  57. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +0 -412
  58. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +0 -122
  59. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +0 -399
  60. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +0 -398
  61. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +0 -92
  62. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +0 -147
  63. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +0 -147
  64. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +0 -18
  65. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +0 -324
  66. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +0 -314
  67. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +0 -119
  68. package/examples/output/go.pprof.block.base.pprof.md +0 -86
  69. package/examples/output/go.pprof.block.current.pprof.md +0 -83
  70. package/examples/output/go.pprof.block.diff.pprof.md +0 -42
  71. package/examples/output/go.pprof.cpu.base.pprof.md +0 -81
  72. package/examples/output/go.pprof.cpu.current.pprof.md +0 -70
  73. package/examples/output/go.pprof.cpu.diff.pprof.md +0 -52
  74. package/examples/output/go.pprof.goroutine.base.pprof.md +0 -43
  75. package/examples/output/go.pprof.goroutine.current.pprof.md +0 -43
  76. package/examples/output/go.pprof.goroutine.diff.pprof.md +0 -13
  77. package/examples/output/go.pprof.heap-alloc.base.pprof.md +0 -154
  78. package/examples/output/go.pprof.heap-alloc.current.pprof.md +0 -146
  79. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +0 -67
  80. package/examples/output/go.pprof.heap.base.pprof.md +0 -154
  81. package/examples/output/go.pprof.heap.current.pprof.md +0 -146
  82. package/examples/output/go.pprof.heap.diff.pprof.md +0 -67
  83. package/examples/output/go.pprof.mutex.base.pprof.md +0 -55
  84. package/examples/output/go.pprof.mutex.current.pprof.md +0 -41
  85. package/examples/output/go.pprof.mutex.diff.pprof.md +0 -31
  86. package/examples/output/go.pprof.threadcreate.base.pprof.md +0 -55
  87. package/examples/output/go.pprof.threadcreate.current.pprof.md +0 -55
  88. package/examples/output/go.pprof.threadcreate.diff.pprof.md +0 -19
  89. package/examples/output/java.async-profiler.all.base.jfr.md +0 -1071
  90. package/examples/output/java.async-profiler.all.current.jfr.md +0 -1007
  91. package/examples/output/java.async-profiler.all.diff.jfr.md +0 -268
  92. package/examples/output/java.async-profiler.alloc.base.jfr.md +0 -425
  93. package/examples/output/java.async-profiler.alloc.current.jfr.md +0 -413
  94. package/examples/output/java.async-profiler.alloc.diff.jfr.md +0 -99
  95. package/examples/output/java.async-profiler.cpu.base.collapsed.md +0 -367
  96. package/examples/output/java.async-profiler.cpu.base.jfr.md +0 -485
  97. package/examples/output/java.async-profiler.cpu.current.collapsed.md +0 -355
  98. package/examples/output/java.async-profiler.cpu.current.jfr.md +0 -488
  99. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +0 -117
  100. package/examples/output/java.async-profiler.cpu.diff.jfr.md +0 -118
  101. package/examples/output/java.async-profiler.live.base.jfr.md +0 -697
  102. package/examples/output/java.async-profiler.live.current.jfr.md +0 -684
  103. package/examples/output/java.async-profiler.live.diff.jfr.md +0 -191
  104. package/examples/output/java.async-profiler.lock.base.jfr.md +0 -140
  105. package/examples/output/java.async-profiler.lock.current.jfr.md +0 -108
  106. package/examples/output/java.async-profiler.lock.diff.jfr.md +0 -44
  107. package/examples/output/java.async-profiler.nativemem.base.jfr.md +0 -222
  108. package/examples/output/java.async-profiler.nativemem.current.jfr.md +0 -222
  109. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +0 -65
  110. package/examples/output/java.async-profiler.wall.base.jfr.md +0 -400
  111. package/examples/output/java.async-profiler.wall.current.jfr.md +0 -420
  112. package/examples/output/java.async-profiler.wall.diff.jfr.md +0 -94
  113. package/examples/output/java.jdk.all.base.jfr.md +0 -1024
  114. package/examples/output/java.jdk.all.current.jfr.md +0 -1010
  115. package/examples/output/java.jdk.all.diff.jfr.md +0 -311
  116. package/examples/output/java.jdk.alloc.base.jfr.md +0 -1024
  117. package/examples/output/java.jdk.alloc.current.jfr.md +0 -1046
  118. package/examples/output/java.jdk.alloc.diff.jfr.md +0 -312
  119. package/examples/output/java.jdk.cpu.base.jfr.md +0 -1023
  120. package/examples/output/java.jdk.cpu.current.jfr.md +0 -1039
  121. package/examples/output/java.jdk.cpu.diff.jfr.md +0 -285
  122. package/examples/output/java.jdk.live.base.jfr.md +0 -1029
  123. package/examples/output/java.jdk.live.current.jfr.md +0 -1035
  124. package/examples/output/java.jdk.live.diff.jfr.md +0 -289
  125. package/examples/output/java.jdk.lock.base.jfr.md +0 -1040
  126. package/examples/output/java.jdk.lock.current.jfr.md +0 -1051
  127. package/examples/output/java.jdk.lock.diff.jfr.md +0 -339
  128. package/examples/output/javascript.bun.base.cpuprofile.md +0 -73
  129. package/examples/output/javascript.bun.base.heapsnapshot.md +0 -608
  130. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +0 -480
  131. package/examples/output/javascript.bun.current.cpuprofile.md +0 -73
  132. package/examples/output/javascript.bun.current.heapsnapshot.md +0 -608
  133. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +0 -480
  134. package/examples/output/javascript.bun.diff.cpuprofile.md +0 -54
  135. package/examples/output/javascript.bun.diff.heapsnapshot.md +0 -48
  136. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +0 -62
  137. package/examples/output/javascript.chrome.base.cpuprofile.md +0 -163
  138. package/examples/output/javascript.chrome.base.heapprofile.md +0 -32
  139. package/examples/output/javascript.chrome.base.heapsnapshot.md +0 -649
  140. package/examples/output/javascript.chrome.current.cpuprofile.md +0 -149
  141. package/examples/output/javascript.chrome.current.heapprofile.md +0 -32
  142. package/examples/output/javascript.chrome.current.heapsnapshot.md +0 -647
  143. package/examples/output/javascript.chrome.diff.cpuprofile.md +0 -65
  144. package/examples/output/javascript.chrome.diff.heapprofile.md +0 -50
  145. package/examples/output/javascript.chrome.diff.heapsnapshot.md +0 -73
  146. package/examples/output/javascript.deno.base.cpuprofile.md +0 -122
  147. package/examples/output/javascript.deno.current.cpuprofile.md +0 -114
  148. package/examples/output/javascript.deno.diff.cpuprofile.md +0 -66
  149. package/examples/output/javascript.node.base.cpuprofile.md +0 -136
  150. package/examples/output/javascript.node.base.heapprofile.md +0 -56
  151. package/examples/output/javascript.node.base.heapsnapshot.md +0 -660
  152. package/examples/output/javascript.node.current.cpuprofile.md +0 -119
  153. package/examples/output/javascript.node.current.heapprofile.md +0 -52
  154. package/examples/output/javascript.node.current.heapsnapshot.md +0 -660
  155. package/examples/output/javascript.node.diff.cpuprofile.md +0 -70
  156. package/examples/output/javascript.node.diff.heapprofile.md +0 -34
  157. package/examples/output/javascript.node.diff.heapsnapshot.md +0 -39
  158. package/examples/output/javascript.pprof.cpu.base.pprof.md +0 -104
  159. package/examples/output/javascript.pprof.cpu.current.pprof.md +0 -120
  160. package/examples/output/javascript.pprof.cpu.diff.pprof.md +0 -63
  161. package/examples/output/javascript.pprof.heap.base.pprof.md +0 -86
  162. package/examples/output/javascript.pprof.heap.current.pprof.md +0 -57
  163. package/examples/output/javascript.pprof.heap.diff.pprof.md +0 -42
  164. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +0 -388
  165. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +0 -378
  166. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +0 -122
  167. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +0 -124
  168. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +0 -126
  169. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +0 -30
  170. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +0 -177
  171. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +0 -179
  172. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +0 -64
  173. package/examples/output/kotlin.async-profiler.all.base.jfr.md +0 -920
  174. package/examples/output/kotlin.async-profiler.all.current.jfr.md +0 -925
  175. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +0 -247
  176. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +0 -467
  177. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +0 -473
  178. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +0 -122
  179. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +0 -371
  180. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +0 -472
  181. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +0 -370
  182. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +0 -445
  183. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +0 -124
  184. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +0 -125
  185. package/examples/output/kotlin.async-profiler.live.base.jfr.md +0 -934
  186. package/examples/output/kotlin.async-profiler.live.current.jfr.md +0 -917
  187. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +0 -245
  188. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +0 -1
  189. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +0 -1
  190. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +0 -1
  191. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +0 -234
  192. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +0 -234
  193. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +0 -65
  194. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +0 -452
  195. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +0 -457
  196. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +0 -125
  197. package/examples/output/kotlin.jdk.all.base.jfr.md +0 -1442
  198. package/examples/output/kotlin.jdk.all.current.jfr.md +0 -1343
  199. package/examples/output/kotlin.jdk.all.diff.jfr.md +0 -392
  200. package/examples/output/kotlin.jdk.alloc.base.jfr.md +0 -1418
  201. package/examples/output/kotlin.jdk.alloc.current.jfr.md +0 -1389
  202. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +0 -383
  203. package/examples/output/kotlin.jdk.cpu.base.jfr.md +0 -1406
  204. package/examples/output/kotlin.jdk.cpu.current.jfr.md +0 -1374
  205. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +0 -380
  206. package/examples/output/kotlin.jdk.live.base.jfr.md +0 -1378
  207. package/examples/output/kotlin.jdk.live.current.jfr.md +0 -1311
  208. package/examples/output/kotlin.jdk.live.diff.jfr.md +0 -381
  209. package/examples/output/kotlin.jdk.lock.base.jfr.md +0 -1427
  210. package/examples/output/kotlin.jdk.lock.current.jfr.md +0 -1374
  211. package/examples/output/kotlin.jdk.lock.diff.jfr.md +0 -386
  212. package/examples/output/php.excimer.wall.base.speedscope.json.md +0 -25
  213. package/examples/output/php.excimer.wall.current.speedscope.json.md +0 -25
  214. package/examples/output/php.excimer.wall.diff.speedscope.json.md +0 -29
  215. package/examples/output/python.py-spy.cpu.base.collapsed.md +0 -526
  216. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +0 -37
  217. package/examples/output/python.py-spy.cpu.current.collapsed.md +0 -514
  218. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +0 -37
  219. package/examples/output/python.py-spy.cpu.diff.collapsed.md +0 -122
  220. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +0 -31
  221. package/examples/output/python.py-spy.wall.base.collapsed.md +0 -527
  222. package/examples/output/python.py-spy.wall.current.collapsed.md +0 -518
  223. package/examples/output/python.py-spy.wall.diff.collapsed.md +0 -122
  224. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +0 -90
  225. package/examples/output/ruby.rbspy.cpu.base.pprof.md +0 -105
  226. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +0 -105
  227. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +0 -90
  228. package/examples/output/ruby.rbspy.cpu.current.pprof.md +0 -115
  229. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +0 -115
  230. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +0 -32
  231. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +0 -44
  232. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +0 -44
  233. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +0 -60
  234. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +0 -60
  235. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +0 -24
package/dist/index.d.mts CHANGED
@@ -1,20 +1,22 @@
1
- import { RawSourceMap as SourceMap } from "source-map-js";
2
-
1
+ import { RawSourceMap as SourceMap, SourceMapConsumer } from "source-map-js";
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
  };
17
- declare const fileReferenceId: (fileReference: DeepReadonly<FileReference>) => string;
18
+ /** A reference to where a function is defined: a file or a logical name. */
19
+ type SourceReference = FileReference | LogicalReference;
18
20
  type FileReference = {
19
21
  type: `absolute`;
20
22
  url: URL;
@@ -22,31 +24,102 @@ type FileReference = {
22
24
  type: `relative`;
23
25
  path: string;
24
26
  };
25
- type SourceLocationInput = {
26
- /** A string parseable into a {@link URL} or file path. */urlOrPath: string; /** The 1-based line number in the file at {@link urlOrPath}. */
27
- 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. */
28
49
  column?: number;
29
50
  };
30
51
  //#endregion
31
- //#region src/profile/type.d.ts
52
+ //#region src/modalities/metric.d.ts
53
+ /** Phrases that can be used in prose related to a metric. */
54
+ type MetricPhrases = {
55
+ /** A noun to use in headings, like "CPU", "heap", etc. */
56
+ titleNoun: string;
57
+ /** A noun to use in columns like "time", "size", etc. */
58
+ columnNoun: string;
59
+ /** A verb to use in prose like "took", "allocated", etc. */
60
+ pastTenseVerb: string;
61
+ /** A verb phrase to use in prose like "time spent", "bytes allocated", etc. */
62
+ pastParticipleVerbPhrase: string;
63
+ };
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`;
74
+ /** A metric measured in a profile. */
75
+ type Metric = ({
76
+ type: `time`;
77
+ /** The number of milliseconds this time unit takes up. */
78
+ milliseconds: number;
79
+ } | {
80
+ type: `size`;
81
+ /** The number of bytes this space unit takes up. */
82
+ bytes: number;
83
+ } | {
84
+ /**
85
+ * A metric in a unit with no known scale, formatted as a bare count.
86
+ * {@link MetricPhrases.columnNoun} (a plural noun, e.g. `instructions`)
87
+ * names the unit in table headers.
88
+ */
89
+ type: `count`;
90
+ /**
91
+ * The singular noun following a count in prose, pluralized by the count
92
+ * (e.g. `cycle` → "84 cycles"). For a metric counting occurrences of the
93
+ * event its verb already names, use `time` → "slept 84 times".
94
+ */
95
+ proseUnit: string;
96
+ }) & {
97
+ phrases: MetricPhrases;
98
+ /** Which direction of change in this metric's value is an improvement. */
99
+ improvement: MetricImprovement;
100
+ };
101
+ //#endregion
102
+ //#region src/modalities/stack-frame.d.ts
32
103
  /**
33
104
  * A function occurrence at an executing position.
34
105
  *
35
106
  * Its {@link name} and {@link location} (the function's *definition* location)
36
107
  * identify the function; frames sharing them are the same function.
37
108
  *
38
- * {@link line} is the *executing* line and feeds the per-line breakdown, not
39
- * identity.
109
+ * {@link line} is the *executing* line and is used for the per-line breakdown,
110
+ * not identity.
40
111
  *
41
- * A converter produces these raw (typically just a {@link name}); the resolved
42
- * origin's `normalizeFrame` then splits out the location and line for variants
43
- * that pack them into the frame string.
112
+ * A converter produces these raw; the resolved origin's `normalizeStackFrame` then
113
+ * splits out the location and line for variants that pack them into the frame
114
+ * string.
44
115
  */
45
- type ProfileStackFrame = {
46
- /** 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. */
47
120
  location?: SourceLocationInput;
48
121
  /**
49
- * The 1-based line at which this frame was sampled, if known.
122
+ * The 1-based line where this frame was sampled, if known.
50
123
  *
51
124
  * Distinct from {@link location}'s line (the definition line): this is the
52
125
  * executing line, which the aggregator forwards to the leaf function's
@@ -55,39 +128,473 @@ type ProfileStackFrame = {
55
128
  line?: number;
56
129
  };
57
130
  //#endregion
58
- //#region src/origins/index.d.ts
131
+ //#region src/modalities/call-graph/type.d.ts
59
132
  /**
60
- * A profile or snapshot origin: the thing that generated it, i.e. a profiler
61
- * paired with a runtime (e.g. `node`, `deno`, `safari`).
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.
62
136
  *
63
- * Auto-detected from a profile's entries via {@link determineOrigin}, or
64
- * specified explicitly.
137
+ * Origin detection, frame normalization, and aggregation run uniformly from
138
+ * here, so a format's only custom logic is parsing into this.
65
139
  */
66
- type Origin = SpecificOriginSpec[`id`];
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[];
149
+ /**
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
67
182
  /**
68
- * Returns the category of {@link entry} as the given {@link origin} categorizes
69
- * it (see {@link OriginSpec.categorize}).
183
+ * A profile parsed into the uniform structure containing the distinct frames
184
+ * and the observations that reference them.
70
185
  *
71
- * The origin-aware categorization the library applies by default. Exposed so a
72
- * custom `categorizeEntries` can reuse the library's categorization for an
73
- * origin it didn't special-case, rather than reimplementing it.
186
+ * A format that yields several profiles returns one of these per profile,
187
+ * typically sharing the same {@link CallStackProfile.frames} array reference.
74
188
  */
75
- declare const categorizeEntryForOrigin: (entry: DeepReadonly<ProfileEntry>, origin: Origin) => EntryCategory;
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
231
+ * format that references stacks by a constant-pool index).
232
+ *
233
+ * When provided, the aggregator memoizes the resolved call stack by this ID.
234
+ */
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;
248
+ };
249
+ /**
250
+ * Per-line metrics for one frame, added after the observations.
251
+ *
252
+ * Used by formats that report a function's self time broken down by line
253
+ * separately from its observations.
254
+ */
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. */
259
+ lines: {
260
+ line: number;
261
+ count: number;
262
+ values: number[];
263
+ }[];
264
+ };
265
+ //#endregion
266
+ //#region src/modalities/heap-snapshot/graph.d.ts
267
+ /**
268
+ * A successor and predecessor graph between heap snapshot nodes in CSR format.
269
+ *
270
+ * @see https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format)
271
+ */
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
76
583
  /**
77
584
  * All origin specs in global detection-priority order.
78
585
  *
79
- * Within a format, the detector tries candidates in the order they appear
80
- * here, so origins that share a format and whose signals overlap must be
81
- * ordered carefully (e.g. Deno before Node, since Deno supports `node:`
82
- * specifiers).
586
+ * Within a format, the detector tries candidates in this order, so origins that
587
+ * share a format and whose marker entries overlap must be ordered carefully
588
+ * (e.g. Deno before Node, since Deno supports `node:` specifiers). A parser
589
+ * origin hint loses to a marker entry of a higher-priority origin, so a
590
+ * markerless origin detected by a hint must also precede the origins whose
591
+ * markers it should outrank.
83
592
  */
84
593
  declare const originSpecs: ({
85
594
  readonly id: "deno";
86
- readonly language: "javascript";
595
+ readonly title: "Deno";
87
596
  readonly formats: ["v8-cpu-profile"];
88
- readonly matchesEntry: ({
89
- location
90
- }: {
597
+ readonly isMarkerEntry: ({ location }: {
91
598
  readonly id: number;
92
599
  readonly name?: string | undefined;
93
600
  readonly location?: {
@@ -100,9 +607,14 @@ declare const originSpecs: ({
100
607
  readonly path: string;
101
608
  readonly line?: number | undefined;
102
609
  readonly column?: number | undefined;
610
+ } | {
611
+ readonly type: `logical`;
612
+ readonly name: string;
613
+ readonly line?: number | undefined;
614
+ readonly column?: number | undefined;
103
615
  } | undefined;
104
616
  }) => boolean;
105
- readonly categorize: (entry: {
617
+ readonly categorizeEntry: (entry: {
106
618
  readonly id: number;
107
619
  readonly name?: string | undefined;
108
620
  readonly location?: {
@@ -115,16 +627,18 @@ declare const originSpecs: ({
115
627
  readonly path: string;
116
628
  readonly line?: number | undefined;
117
629
  readonly column?: number | undefined;
630
+ } | {
631
+ readonly type: `logical`;
632
+ readonly name: string;
633
+ readonly line?: number | undefined;
634
+ readonly column?: number | undefined;
118
635
  } | undefined;
119
- }) => EntryCategory;
636
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
120
637
  } | {
121
638
  readonly id: "bun";
122
- readonly language: "javascript";
123
- readonly formats: ["v8-cpu-profile"];
124
- readonly matchesEntry: ({
125
- name,
126
- location
127
- }: {
639
+ readonly title: "Bun";
640
+ readonly formats: ["v8-cpu-profile", "jsc-heap-snapshot", "v8-heap-snapshot"];
641
+ readonly isMarkerEntry: ({ name, location }: {
128
642
  readonly id: number;
129
643
  readonly name?: string | undefined;
130
644
  readonly location?: {
@@ -137,9 +651,14 @@ declare const originSpecs: ({
137
651
  readonly path: string;
138
652
  readonly line?: number | undefined;
139
653
  readonly column?: number | undefined;
654
+ } | {
655
+ readonly type: `logical`;
656
+ readonly name: string;
657
+ readonly line?: number | undefined;
658
+ readonly column?: number | undefined;
140
659
  } | undefined;
141
660
  }) => boolean;
142
- readonly categorize: (entry: {
661
+ readonly categorizeEntry: (entry: {
143
662
  readonly id: number;
144
663
  readonly name?: string | undefined;
145
664
  readonly location?: {
@@ -152,15 +671,64 @@ declare const originSpecs: ({
152
671
  readonly path: string;
153
672
  readonly line?: number | undefined;
154
673
  readonly column?: number | undefined;
674
+ } | {
675
+ readonly type: `logical`;
676
+ readonly name: string;
677
+ readonly line?: number | undefined;
678
+ readonly column?: number | undefined;
155
679
  } | undefined;
156
- }) => 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;
157
682
  } | {
158
683
  readonly id: "node";
159
- readonly language: "javascript";
684
+ readonly title: "Node.js";
685
+ readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile"];
686
+ readonly isMarkerEntry: ({ location }: {
687
+ readonly id: number;
688
+ readonly name?: string | undefined;
689
+ readonly location?: {
690
+ readonly type: `absolute`;
691
+ readonly url: URL;
692
+ readonly line?: number | undefined;
693
+ readonly column?: number | undefined;
694
+ } | {
695
+ readonly type: `relative`;
696
+ readonly path: string;
697
+ readonly line?: number | undefined;
698
+ readonly column?: number | undefined;
699
+ } | {
700
+ readonly type: `logical`;
701
+ readonly name: string;
702
+ readonly line?: number | undefined;
703
+ readonly column?: number | undefined;
704
+ } | undefined;
705
+ }) => boolean;
706
+ readonly categorizeEntry: (entry: {
707
+ readonly id: number;
708
+ readonly name?: string | undefined;
709
+ readonly location?: {
710
+ readonly type: `absolute`;
711
+ readonly url: URL;
712
+ readonly line?: number | undefined;
713
+ readonly column?: number | undefined;
714
+ } | {
715
+ readonly type: `relative`;
716
+ readonly path: string;
717
+ readonly line?: number | undefined;
718
+ readonly column?: number | undefined;
719
+ } | {
720
+ readonly type: `logical`;
721
+ readonly name: string;
722
+ readonly line?: number | undefined;
723
+ readonly column?: number | undefined;
724
+ } | undefined;
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";
160
730
  readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile"];
161
- readonly matchesEntry: ({
162
- location
163
- }: {
731
+ readonly isMarkerEntry: ({ name, location }: {
164
732
  readonly id: number;
165
733
  readonly name?: string | undefined;
166
734
  readonly location?: {
@@ -173,9 +741,14 @@ declare const originSpecs: ({
173
741
  readonly path: string;
174
742
  readonly line?: number | undefined;
175
743
  readonly column?: number | undefined;
744
+ } | {
745
+ readonly type: `logical`;
746
+ readonly name: string;
747
+ readonly line?: number | undefined;
748
+ readonly column?: number | undefined;
176
749
  } | undefined;
177
750
  }) => boolean;
178
- readonly categorize: (entry: {
751
+ readonly categorizeEntry: (entry: {
179
752
  readonly id: number;
180
753
  readonly name?: string | undefined;
181
754
  readonly location?: {
@@ -188,16 +761,18 @@ declare const originSpecs: ({
188
761
  readonly path: string;
189
762
  readonly line?: number | undefined;
190
763
  readonly column?: number | undefined;
764
+ } | {
765
+ readonly type: `logical`;
766
+ readonly name: string;
767
+ readonly line?: number | undefined;
768
+ readonly column?: number | undefined;
191
769
  } | undefined;
192
- }) => EntryCategory;
770
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
771
+ readonly categorizeHeapSnapshotConstructor: (name: string) => HeapSnapshotNodeCategory | undefined;
193
772
  } | {
194
773
  readonly id: "node-pprof";
195
- readonly language: "javascript";
196
774
  readonly formats: ["pprof"];
197
- readonly matchesEntry: ({
198
- name,
199
- location
200
- }: {
775
+ readonly isMarkerEntry: ({ name, location }: {
201
776
  readonly id: number;
202
777
  readonly name?: string | undefined;
203
778
  readonly location?: {
@@ -210,9 +785,14 @@ declare const originSpecs: ({
210
785
  readonly path: string;
211
786
  readonly line?: number | undefined;
212
787
  readonly column?: number | undefined;
788
+ } | {
789
+ readonly type: `logical`;
790
+ readonly name: string;
791
+ readonly line?: number | undefined;
792
+ readonly column?: number | undefined;
213
793
  } | undefined;
214
794
  }) => boolean;
215
- readonly categorize: (entry: {
795
+ readonly categorizeEntry: (entry: {
216
796
  readonly id: number;
217
797
  readonly name?: string | undefined;
218
798
  readonly location?: {
@@ -225,14 +805,18 @@ declare const originSpecs: ({
225
805
  readonly path: string;
226
806
  readonly line?: number | undefined;
227
807
  readonly column?: number | undefined;
808
+ } | {
809
+ readonly type: `logical`;
810
+ readonly name: string;
811
+ readonly line?: number | undefined;
812
+ readonly column?: number | undefined;
228
813
  } | undefined;
229
- }) => EntryCategory;
230
- 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;
231
816
  } | {
232
817
  readonly id: "pprof-rs";
233
- readonly language: "rust";
234
818
  readonly formats: ["pprof"];
235
- readonly matchesEntry: (entry: {
819
+ readonly isMarkerEntry: (entry: {
236
820
  readonly id: number;
237
821
  readonly name?: string | undefined;
238
822
  readonly location?: {
@@ -245,9 +829,14 @@ declare const originSpecs: ({
245
829
  readonly path: string;
246
830
  readonly line?: number | undefined;
247
831
  readonly column?: number | undefined;
832
+ } | {
833
+ readonly type: `logical`;
834
+ readonly name: string;
835
+ readonly line?: number | undefined;
836
+ readonly column?: number | undefined;
248
837
  } | undefined;
249
838
  }) => boolean;
250
- readonly categorize: (entry: {
839
+ readonly categorizeEntry: (entry: {
251
840
  readonly id: number;
252
841
  readonly name?: string | undefined;
253
842
  readonly location?: {
@@ -260,13 +849,19 @@ declare const originSpecs: ({
260
849
  readonly path: string;
261
850
  readonly line?: number | undefined;
262
851
  readonly column?: number | undefined;
852
+ } | {
853
+ readonly type: `logical`;
854
+ readonly name: string;
855
+ readonly line?: number | undefined;
856
+ readonly column?: number | undefined;
263
857
  } | undefined;
264
- }) => EntryCategory;
858
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
859
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
265
860
  } | {
266
861
  readonly id: "go";
267
- readonly language: "go";
862
+ readonly title: "pprof";
268
863
  readonly formats: ["pprof"];
269
- readonly matchesEntry: (entry: {
864
+ readonly isMarkerEntry: (entry: {
270
865
  readonly id: number;
271
866
  readonly name?: string | undefined;
272
867
  readonly location?: {
@@ -279,9 +874,14 @@ declare const originSpecs: ({
279
874
  readonly path: string;
280
875
  readonly line?: number | undefined;
281
876
  readonly column?: number | undefined;
877
+ } | {
878
+ readonly type: `logical`;
879
+ readonly name: string;
880
+ readonly line?: number | undefined;
881
+ readonly column?: number | undefined;
282
882
  } | undefined;
283
883
  }) => boolean;
284
- readonly categorize: (entry: {
884
+ readonly categorizeEntry: (entry: {
285
885
  readonly id: number;
286
886
  readonly name?: string | undefined;
287
887
  readonly location?: {
@@ -294,13 +894,17 @@ declare const originSpecs: ({
294
894
  readonly path: string;
295
895
  readonly line?: number | undefined;
296
896
  readonly column?: number | undefined;
897
+ } | {
898
+ readonly type: `logical`;
899
+ readonly name: string;
900
+ readonly line?: number | undefined;
901
+ readonly column?: number | undefined;
297
902
  } | undefined;
298
- }) => EntryCategory;
903
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
299
904
  } | {
300
905
  readonly id: "pprof-jl";
301
- readonly language: "julia";
302
906
  readonly formats: ["pprof"];
303
- readonly matchesEntry: (entry: {
907
+ readonly isMarkerEntry: (entry: {
304
908
  readonly id: number;
305
909
  readonly name?: string | undefined;
306
910
  readonly location?: {
@@ -313,9 +917,14 @@ declare const originSpecs: ({
313
917
  readonly path: string;
314
918
  readonly line?: number | undefined;
315
919
  readonly column?: number | undefined;
920
+ } | {
921
+ readonly type: `logical`;
922
+ readonly name: string;
923
+ readonly line?: number | undefined;
924
+ readonly column?: number | undefined;
316
925
  } | undefined;
317
926
  }) => boolean;
318
- readonly categorize: (entry: {
927
+ readonly categorizeEntry: (entry: {
319
928
  readonly id: number;
320
929
  readonly name?: string | undefined;
321
930
  readonly location?: {
@@ -328,14 +937,19 @@ declare const originSpecs: ({
328
937
  readonly path: string;
329
938
  readonly line?: number | undefined;
330
939
  readonly column?: number | undefined;
940
+ } | {
941
+ readonly type: `logical`;
942
+ readonly name: string;
943
+ readonly line?: number | undefined;
944
+ readonly column?: number | undefined;
331
945
  } | undefined;
332
- }) => EntryCategory;
333
- 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;
334
948
  } | {
335
- readonly id: "py-spy";
336
- readonly language: "python";
337
- readonly formats: ["collapsed", "speedscope"];
338
- readonly matchesEntry: (entry: {
949
+ readonly id: "profile-jl";
950
+ readonly title: "Profile";
951
+ readonly formats: ["v8-heap-snapshot"];
952
+ readonly isMarkerEntry: ({ name, location }: {
339
953
  readonly id: number;
340
954
  readonly name?: string | undefined;
341
955
  readonly location?: {
@@ -348,15 +962,39 @@ declare const originSpecs: ({
348
962
  readonly path: string;
349
963
  readonly line?: number | undefined;
350
964
  readonly column?: number | undefined;
965
+ } | {
966
+ readonly type: `logical`;
967
+ readonly name: string;
968
+ readonly line?: number | undefined;
969
+ readonly column?: number | undefined;
351
970
  } | undefined;
352
971
  }) => boolean;
353
- readonly categorize: (entry: DeepReadonly<ProfileEntry>) => EntryCategory;
354
- readonly normalizeFrame: (input: ProfileStackFrame, format: "collapsed" | "jfr" | "jsc-heap-snapshot" | "pprof" | "speedscope" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => ProfileStackFrame;
972
+ readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
973
+ readonly categorizeHeapSnapshotDeclaredType: (declaredType: string) => HeapSnapshotNodeCategory | undefined;
355
974
  } | {
356
- readonly id: "tachyon";
357
- readonly language: "python";
358
- readonly formats: ["collapsed"];
359
- readonly matchesEntry: (entry: {
975
+ readonly id: "pyinstrument";
976
+ readonly formats: ["speedscope"];
977
+ readonly isMarkerEntry: (entry: {
978
+ readonly id: number;
979
+ readonly name?: string | undefined;
980
+ readonly location?: {
981
+ readonly type: `absolute`;
982
+ readonly url: URL;
983
+ readonly line?: number | undefined;
984
+ readonly column?: number | undefined;
985
+ } | {
986
+ readonly type: `relative`;
987
+ readonly path: string;
988
+ readonly line?: number | undefined;
989
+ readonly column?: number | undefined;
990
+ } | {
991
+ readonly type: `logical`;
992
+ readonly name: string;
993
+ readonly line?: number | undefined;
994
+ readonly column?: number | undefined;
995
+ } | undefined;
996
+ }) => boolean;
997
+ readonly categorizeEntry: (entry: {
360
998
  readonly id: number;
361
999
  readonly name?: string | undefined;
362
1000
  readonly location?: {
@@ -369,15 +1007,51 @@ declare const originSpecs: ({
369
1007
  readonly path: string;
370
1008
  readonly line?: number | undefined;
371
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;
1026
+ } | {
1027
+ readonly id: "py-spy";
1028
+ readonly formats: ["collapsed", "speedscope"];
1029
+ readonly isMarkerEntry: (entry: {
1030
+ readonly id: number;
1031
+ readonly name?: string | undefined;
1032
+ readonly location?: {
1033
+ readonly type: `absolute`;
1034
+ readonly url: URL;
1035
+ readonly line?: number | undefined;
1036
+ readonly column?: number | undefined;
1037
+ } | {
1038
+ readonly type: `relative`;
1039
+ readonly path: string;
1040
+ readonly line?: number | undefined;
1041
+ readonly column?: number | undefined;
1042
+ } | {
1043
+ readonly type: `logical`;
1044
+ readonly name: string;
1045
+ readonly line?: number | undefined;
1046
+ readonly column?: number | undefined;
372
1047
  } | undefined;
373
1048
  }) => boolean;
374
- readonly categorize: (entry: DeepReadonly<ProfileEntry>) => EntryCategory;
375
- 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;
376
1051
  } | {
377
- readonly id: "jvm";
378
- readonly language: "java";
379
- readonly formats: ["jfr", "collapsed"];
380
- readonly matchesEntry: (entry: {
1052
+ readonly id: "tachyon";
1053
+ readonly formats: ["collapsed"];
1054
+ readonly isMarkerEntry: (entry: {
381
1055
  readonly id: number;
382
1056
  readonly name?: string | undefined;
383
1057
  readonly location?: {
@@ -390,9 +1064,19 @@ declare const originSpecs: ({
390
1064
  readonly path: string;
391
1065
  readonly line?: number | undefined;
392
1066
  readonly column?: number | undefined;
1067
+ } | {
1068
+ readonly type: `logical`;
1069
+ readonly name: string;
1070
+ readonly line?: number | undefined;
1071
+ readonly column?: number | undefined;
393
1072
  } | undefined;
394
1073
  }) => boolean;
395
- readonly categorize: (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: {
396
1080
  readonly id: number;
397
1081
  readonly name?: string | undefined;
398
1082
  readonly location?: {
@@ -405,14 +1089,28 @@ declare const originSpecs: ({
405
1089
  readonly path: string;
406
1090
  readonly line?: number | undefined;
407
1091
  readonly column?: number | undefined;
1092
+ } | {
1093
+ readonly type: `logical`;
1094
+ readonly name: string;
1095
+ readonly line?: number | undefined;
1096
+ readonly column?: number | undefined;
408
1097
  } | undefined;
409
- }) => EntryCategory;
410
- readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
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;
1109
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
411
1110
  } | {
412
1111
  readonly id: "dotnet-trace";
413
- readonly language: null;
414
1112
  readonly formats: ["speedscope"];
415
- readonly matchesEntry: (entry: {
1113
+ readonly isMarkerEntry: (entry: {
416
1114
  readonly id: number;
417
1115
  readonly name?: string | undefined;
418
1116
  readonly location?: {
@@ -425,9 +1123,14 @@ declare const originSpecs: ({
425
1123
  readonly path: string;
426
1124
  readonly line?: number | undefined;
427
1125
  readonly column?: number | undefined;
1126
+ } | {
1127
+ readonly type: `logical`;
1128
+ readonly name: string;
1129
+ readonly line?: number | undefined;
1130
+ readonly column?: number | undefined;
428
1131
  } | undefined;
429
1132
  }) => boolean;
430
- readonly categorize: (entry: {
1133
+ readonly categorizeEntry: (entry: {
431
1134
  readonly id: number;
432
1135
  readonly name?: string | undefined;
433
1136
  readonly location?: {
@@ -440,14 +1143,18 @@ declare const originSpecs: ({
440
1143
  readonly path: string;
441
1144
  readonly line?: number | undefined;
442
1145
  readonly column?: number | undefined;
1146
+ } | {
1147
+ readonly type: `logical`;
1148
+ readonly name: string;
1149
+ readonly line?: number | undefined;
1150
+ readonly column?: number | undefined;
443
1151
  } | undefined;
444
- }) => EntryCategory;
445
- 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;
446
1154
  } | {
447
- readonly id: "beam";
448
- readonly language: null;
1155
+ readonly id: "eflambe";
449
1156
  readonly formats: ["collapsed"];
450
- readonly matchesEntry: (entry: {
1157
+ readonly isMarkerEntry: (entry: {
451
1158
  readonly id: number;
452
1159
  readonly name?: string | undefined;
453
1160
  readonly location?: {
@@ -460,9 +1167,15 @@ declare const originSpecs: ({
460
1167
  readonly path: string;
461
1168
  readonly line?: number | undefined;
462
1169
  readonly column?: number | undefined;
1170
+ } | {
1171
+ readonly type: `logical`;
1172
+ readonly name: string;
1173
+ readonly line?: number | undefined;
1174
+ readonly column?: number | undefined;
463
1175
  } | undefined;
464
1176
  }) => boolean;
465
- readonly categorize: (entry: {
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;
1178
+ readonly categorizeEntry: (entry: {
466
1179
  readonly id: number;
467
1180
  readonly name?: string | undefined;
468
1181
  readonly location?: {
@@ -475,14 +1188,44 @@ declare const originSpecs: ({
475
1188
  readonly path: string;
476
1189
  readonly line?: number | undefined;
477
1190
  readonly column?: number | undefined;
1191
+ } | {
1192
+ readonly type: `logical`;
1193
+ readonly name: string;
1194
+ readonly line?: number | undefined;
1195
+ readonly column?: number | undefined;
478
1196
  } | undefined;
479
- }) => EntryCategory;
480
- 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;
481
1225
  } | {
482
1226
  readonly id: "rbspy";
483
- readonly language: "ruby";
484
- readonly formats: ["collapsed", "pprof", "speedscope"];
485
- readonly matchesEntry: (entry: {
1227
+ readonly formats: ["callgrind", "collapsed", "pprof", "speedscope"];
1228
+ readonly isMarkerEntry: (entry: {
486
1229
  readonly id: number;
487
1230
  readonly name?: string | undefined;
488
1231
  readonly location?: {
@@ -495,9 +1238,14 @@ declare const originSpecs: ({
495
1238
  readonly path: string;
496
1239
  readonly line?: number | undefined;
497
1240
  readonly column?: number | undefined;
1241
+ } | {
1242
+ readonly type: `logical`;
1243
+ readonly name: string;
1244
+ readonly line?: number | undefined;
1245
+ readonly column?: number | undefined;
498
1246
  } | undefined;
499
1247
  }) => boolean;
500
- readonly categorize: (entry: {
1248
+ readonly categorizeEntry: (entry: {
501
1249
  readonly id: number;
502
1250
  readonly name?: string | undefined;
503
1251
  readonly location?: {
@@ -510,18 +1258,20 @@ declare const originSpecs: ({
510
1258
  readonly path: string;
511
1259
  readonly line?: number | undefined;
512
1260
  readonly column?: number | undefined;
1261
+ } | {
1262
+ readonly type: `logical`;
1263
+ readonly name: string;
1264
+ readonly line?: number | undefined;
1265
+ readonly column?: number | undefined;
513
1266
  } | undefined;
514
- }) => EntryCategory;
515
- readonly normalizeFrame: (input: ProfileStackFrame, format: "collapsed" | "jfr" | "jsc-heap-snapshot" | "pprof" | "speedscope" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => ProfileStackFrame;
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;
516
1269
  } | {
517
1270
  readonly id: "safari";
518
- readonly language: "javascript";
1271
+ readonly title: "Safari";
519
1272
  readonly formats: ["jsc-heap-snapshot", "webkit-timeline-recording"];
520
- readonly matchesEntry: ({
521
- name,
522
- location
523
- }: DeepReadonly<ProfileEntry>) => boolean;
524
- readonly categorize: (entry: {
1273
+ readonly isMarkerEntry: ({ name, location }: DeepReadonly<ProfileEntry>) => boolean;
1274
+ readonly categorizeEntry: (entry: {
525
1275
  readonly id: number;
526
1276
  readonly name?: string | undefined;
527
1277
  readonly location?: {
@@ -534,14 +1284,18 @@ declare const originSpecs: ({
534
1284
  readonly path: string;
535
1285
  readonly line?: number | undefined;
536
1286
  readonly column?: number | undefined;
1287
+ } | {
1288
+ readonly type: `logical`;
1289
+ readonly name: string;
1290
+ readonly line?: number | undefined;
1291
+ readonly column?: number | undefined;
537
1292
  } | undefined;
538
- }) => 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;
539
1295
  } | {
540
- readonly id: "unknown";
541
- readonly language: null;
542
- readonly formats: [];
543
- readonly matchesEntry: () => false;
544
- readonly categorize: (entry: {
1296
+ readonly id: "systing";
1297
+ readonly formats: ["systing"];
1298
+ readonly isMarkerEntry: (entry: {
545
1299
  readonly id: number;
546
1300
  readonly name?: string | undefined;
547
1301
  readonly location?: {
@@ -554,125 +1308,325 @@ declare const originSpecs: ({
554
1308
  readonly path: string;
555
1309
  readonly line?: number | undefined;
556
1310
  readonly column?: number | undefined;
1311
+ } | {
1312
+ readonly type: `logical`;
1313
+ readonly name: string;
1314
+ readonly line?: number | undefined;
1315
+ readonly column?: number | undefined;
1316
+ } | undefined;
1317
+ }) => boolean;
1318
+ readonly categorizeEntry: (entry: {
1319
+ readonly id: number;
1320
+ readonly name?: string | undefined;
1321
+ readonly location?: {
1322
+ readonly type: `absolute`;
1323
+ readonly url: URL;
1324
+ readonly line?: number | undefined;
1325
+ readonly column?: number | undefined;
1326
+ } | {
1327
+ readonly type: `relative`;
1328
+ readonly path: string;
1329
+ readonly line?: number | undefined;
1330
+ readonly column?: number | undefined;
1331
+ } | {
1332
+ readonly type: `logical`;
1333
+ readonly name: string;
1334
+ readonly line?: number | undefined;
1335
+ readonly column?: number | undefined;
557
1336
  } | undefined;
558
- }) => EntryCategory;
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;
1361
+ } | undefined;
1362
+ }) => "unknown" | "ours" | "third-party" | "stdlib" | "native" | "garbage collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1363
+ } | {
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"];
1378
+ readonly isMarkerEntry: () => false;
1379
+ readonly categorizeEntry: (entry: {
1380
+ readonly id: number;
1381
+ readonly name?: string | undefined;
1382
+ readonly location?: {
1383
+ readonly type: `absolute`;
1384
+ readonly url: URL;
1385
+ readonly line?: number | undefined;
1386
+ readonly column?: number | undefined;
1387
+ } | {
1388
+ readonly type: `relative`;
1389
+ readonly path: string;
1390
+ readonly line?: number | undefined;
1391
+ readonly column?: number | undefined;
1392
+ } | {
1393
+ readonly type: `logical`;
1394
+ readonly name: string;
1395
+ readonly line?: number | undefined;
1396
+ readonly column?: number | undefined;
1397
+ } | undefined;
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;
559
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`];
560
1426
  /** One of the concrete origin specs, with its literal {@link Origin} ID. */
561
1427
  type SpecificOriginSpec = (typeof originSpecs)[number];
562
- /** Every supported origin ID. */
563
1428
  //#endregion
564
- //#region src/profile/aggregate.d.ts
565
- /** An aggregation of samples taken at a given line within a function's body. */
566
- 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;
1436
+ /**
1437
+ * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
1438
+ * in the function and its callees during calls from this caller.
1439
+ */
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;
1448
+ /**
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.
1451
+ */
1452
+ totalValues: Float64Array;
1453
+ };
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;
1465
+ /**
1466
+ * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
1467
+ * directly in the function's body, excluding its callees.
1468
+ */
1469
+ selfValues: Float64Array;
1470
+ /**
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.
1475
+ */
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>;
1483
+ };
1484
+ //#endregion
1485
+ //#region src/modalities/call-stack-profile/aggregate.d.ts
1486
+ /**
1487
+ * An aggregation of observations recorded at a given line within a function's
1488
+ * body.
1489
+ */
1490
+ type AggregatedCallStackProfileLineMetrics = {
567
1491
  /**
568
- * The number of samples taken directly within the function's body at this
569
- * line.
1492
+ * The number of observations recorded directly within the function's body at
1493
+ * this line.
570
1494
  */
571
- sampleCount: number;
1495
+ count: number;
572
1496
  /**
573
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
574
- * samples taken directly within the function's body at this line.
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.
575
1500
  */
576
1501
  values: Float64Array;
577
1502
  };
578
1503
  /**
579
- * An aggregation of samples taken directly within a function's body with a
580
- * given direct caller.
1504
+ * An aggregation of observations recorded directly within a function's body
1505
+ * with a given direct caller.
581
1506
  */
582
- type AggregatedProfileCallerMetrics = {
583
- /** The caller corresponding to the ID. */caller: AggregatedProfileFunction;
1507
+ type AggregatedCallStackProfileCallerMetrics = {
1508
+ /** The caller corresponding to the ID. */
1509
+ caller: AggregatedCallStackProfileFunction;
584
1510
  /**
585
- * The number of samples taken directly within the function's body with this
586
- * caller.
1511
+ * The number of observations recorded directly within the function's body
1512
+ * with this caller.
587
1513
  */
588
- selfSampleCount: number;
1514
+ selfCount: number;
589
1515
  /**
590
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
591
- * samples taken directly within the function's body with this caller.
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.
592
1519
  */
593
1520
  selfValues: Float64Array;
594
1521
  };
595
1522
  /**
596
- * An aggregation of samples taken within a function's body, _and_ all its
597
- * callees, with a given direct callee.
1523
+ * An aggregation of observations recorded within a function's body, _and_ all
1524
+ * its callees, with a given direct callee.
598
1525
  */
599
- type AggregatedProfileCalleeMetrics = {
600
- /** The callee corresponding to the ID. */callee: AggregatedProfileFunction;
1526
+ type AggregatedCallStackProfileCalleeMetrics = {
1527
+ /** The callee corresponding to the ID. */
1528
+ callee: AggregatedCallStackProfileFunction;
601
1529
  /**
602
- * The number of samples taken directly within the function's body, _and_
603
- * all its callees, with this callee.
1530
+ * The number of observations recorded directly within the function's body,
1531
+ * _and_ all its callees, with this callee.
604
1532
  */
605
- totalSampleCount: number;
1533
+ totalCount: number;
606
1534
  /**
607
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
608
- * samples taken directly within the function's body, _and_ all its
609
- * callees, with this callee.
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.
610
1538
  */
611
1539
  totalValues: Float64Array;
612
1540
  /**
613
1541
  * Internal aggregation bookkeeping: the epoch of the most recent call stack
614
- * whose total this edge was counted into, so a frame pair that recurs within
1542
+ * whose total this frame pair was counted into, so one that recurs within
615
1543
  * one call stack is counted just once.
616
1544
  */
617
1545
  lastSeenEpoch: number;
618
1546
  };
619
1547
  /**
620
- * An aggregation of data from every sample involving a given function within a
621
- * profile.
1548
+ * An aggregation of data from every observation involving a given function
1549
+ * within a profile.
622
1550
  */
623
- type AggregatedProfileFunction = {
624
- type: `function`; /** An index that uniquely identifies this function. */
625
- id: number; /** The name of the function in code. */
626
- name: string; /** Where the function was defined, if known. */
627
- location?: SourceLocation; /** The category of functions this function belongs to. */
628
- category: string;
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;
629
1561
  /**
630
- * The number of samples taken directly within the function's body, excluding
631
- * its callees.
1562
+ * The number of observations recorded directly within the function's body,
1563
+ * excluding its callees.
632
1564
  */
633
- selfSampleCount: number;
1565
+ selfCount: number;
634
1566
  /**
635
- * The number of samples taken directly within the function's body _and_ all
636
- * its callees.
1567
+ * The number of observations recorded directly within the function's body
1568
+ * _and_ all its callees.
637
1569
  */
638
- totalSampleCount: number;
1570
+ totalCount: number;
639
1571
  /**
640
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from samples
641
- * taken directly within the function's body, excluding its callees.
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.
642
1575
  */
643
1576
  selfValues: Float64Array;
644
1577
  /**
645
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from samples
646
- * taken directly within the function's body _and_ all its callees.
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.
647
1581
  */
648
- totalValues: Float64Array; /** 1-based line number to values and sample count for that line. */
649
- lineToMetrics: Map<number, AggregatedProfileLineMetrics>;
1582
+ totalValues: Float64Array;
1583
+ /** 1-based line number to values and count for that line. */
1584
+ lineToMetrics: Map<number, AggregatedCallStackProfileLineMetrics>;
650
1585
  /**
651
- * Direct caller id to values and sample count with that caller's calls to
1586
+ * Direct caller id to values and count with that caller's calls to
652
1587
  * this function.
653
1588
  */
654
- callerIdToMetrics: Map<number, AggregatedProfileCallerMetrics>;
1589
+ callerIdToMetrics: Map<number, AggregatedCallStackProfileCallerMetrics>;
655
1590
  /**
656
- * Direct callee id to values and sample count for that callee's calls where
1591
+ * Direct callee id to values and count for that callee's calls where
657
1592
  * this function was a direct or transitive caller.
658
1593
  */
659
- calleeIdToMetrics: Map<number, AggregatedProfileCalleeMetrics>;
1594
+ calleeIdToMetrics: Map<number, AggregatedCallStackProfileCalleeMetrics>;
660
1595
  };
661
1596
  //#endregion
662
- //#region src/snapshot/aggregate.d.ts
663
- type AggregatedSnapshotNode = {
664
- type: `node`; /** Unique ID for this node that can also be used as an index. */
665
- id: number; /** A human readable label for this node. */
666
- name?: string; /** Bytes allocated directly 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. */
1603
+ name?: string;
1604
+ /**
1605
+ * The file reference the {@link name} parses as, when it is URL-shaped
1606
+ * (e.g. a V8 module namespace object named by its file URL). Formatting
1607
+ * shows it relative to the base URL in place of the raw name.
1608
+ */
1609
+ nameLocation?: FileReference;
1610
+ /** Bytes allocated directly for this node. */
667
1611
  selfSize: number;
1612
+ /** What this node holds. */
1613
+ category: HeapSnapshotNodeCategory;
668
1614
  /**
669
1615
  * Bytes allocated for this node, as well as all nodes that would be freed if
670
1616
  * the node were garbage collected.
671
1617
  */
672
- retainedSize: number; /** The exact location where the node was defined. */
1618
+ retainedSize: number;
1619
+ /** The exact location where the node was defined. */
673
1620
  location?: SourceLocation;
674
1621
  };
675
1622
  //#endregion
1623
+ //#region src/source-map.d.ts
1624
+ type NormalizedSourceMap = {
1625
+ consumer: SourceMapConsumer;
1626
+ fileReference: FileReference;
1627
+ };
1628
+ type NormalizedSourceMaps = NormalizedSourceMap[];
1629
+ //#endregion
676
1630
  //#region src/options.d.ts
677
1631
  /** Profile data that can be synchronously parsed and converted to Markdown. */
678
1632
  type ProfileData = string | Uint8Array | Iterable<Uint8Array>;
@@ -688,19 +1642,46 @@ type ProfileInput<Data> = Data | {
688
1642
  format?: Format;
689
1643
  origin?: Origin;
690
1644
  };
691
- /** The category of code an entry originated from. */
692
- 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"];
693
1672
  /** A single entry in a formatted profile. */
694
1673
  type ProfileEntry = {
695
- /** An index that uniquely identifies this entry. */id: number;
1674
+ /** An index that uniquely identifies this entry. */
1675
+ id: number;
696
1676
  /**
697
1677
  * The name of the entity corresponding to this entry (e.g. a function name)
698
1678
  * if it has one.
699
1679
  */
700
1680
  name?: string;
701
1681
  /**
702
- * The location where the entity corresponding to this entry was defined, or
703
- * undefined if it's 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.
704
1685
  */
705
1686
  location?: SourceLocation;
706
1687
  };
@@ -710,22 +1691,36 @@ type ProfileEntry = {
710
1691
  * Only affects matching; the entry's displayed name and location are
711
1692
  * unchanged.
712
1693
  */
713
- type NormalizedEntry = {
714
- /** The name to match by. Omit to match by the entry's name. */name?: string;
1694
+ type EntryMatch = {
1695
+ /** The name to match by. Omit to match by the entry's name. */
1696
+ name?: string;
715
1697
  /**
716
- * The location to match by, as a URL or file path string. Omit to match by
717
- * 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.
718
1701
  */
719
1702
  location?: string;
720
1703
  };
721
- /** A aggregated entry in a formatted profile. */
722
- type AggregatedProfileEntry = AggregatedProfileFunction | AggregatedSnapshotNode;
723
1704
  /**
724
- * The context in which a single profile or snapshot is being converted to
725
- * Markdown.
1705
+ * The keys an entry is paired by across a diff's two sides, derived from its
1706
+ * {@link EntryMatch}.
726
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
+ };
1717
+ /** An aggregated entry in a formatted profile. */
1718
+ type AggregatedProfileEntry = AggregatedCallStackProfileFunction | AggregatedCallGraphFunction | AggregatedHeapSnapshotNode;
1719
+ /** The context in which a profile is being converted to Markdown. */
727
1720
  type ProfileToMdContext = {
728
- /** The format of the profile or snapshot being converted. */format: Format; /** The origin, given explicitly or detected up front from the frames. */
1721
+ /** The format of the profile being converted. */
1722
+ format: Format;
1723
+ /** The origin of the profile being converted. */
729
1724
  origin: Origin;
730
1725
  };
731
1726
  /** Options for profile to Markdown converters. */
@@ -733,26 +1728,52 @@ type ProfileToMdOptions = {
733
1728
  /**
734
1729
  * The number of entries to display when computing the "top N" by some metric.
735
1730
  *
736
- * This value is also be used to limit subsection entry count by dividing it
737
- * by a constant.
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
+ *
1735
+ * This value, divided by a constant, also limits subsection entry count.
738
1736
  *
739
1737
  * Defaults to 20.
740
1738
  */
741
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;
742
1759
  /**
743
1760
  * Base URL to show paths relative to in the Markdown output.
744
1761
  *
745
1762
  * Accepts an absolute file path string or URL. File paths are converted to
746
1763
  * `file://` URLs internally.
747
1764
  *
748
- * A value of `null` indicates that URLs should be absolute.
1765
+ * A value of `'auto'` infers the base URL as the common ancestor directory
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.
1768
+ *
1769
+ * A value of `null` leaves URLs absolute.
749
1770
  *
750
1771
  * Defaults to `process.cwd()` when available. Otherwise leaves paths
751
1772
  * absolute.
752
1773
  */
753
- baseURL?: string | URL | null;
1774
+ baseURL?: `auto` | (string & {}) | URL | null;
754
1775
  /**
755
- * Source maps to apply when formatting profile locations.
1776
+ * Source maps to apply when formatting source locations.
756
1777
  *
757
1778
  * Accepts either a list of raw source map objects, or a record mapping
758
1779
  * generated file URLs or absolute/relative paths to raw source map objects.
@@ -767,99 +1788,118 @@ type ProfileToMdOptions = {
767
1788
  * location.
768
1789
  *
769
1790
  * Only affects which entries are considered the same entity when diffing
770
- * (profile functions and snapshot closures); displayed names and locations,
771
- * categorization, and source map resolution always use the entry's real
772
- * name and location. Matched entries display the current profile's name and
773
- * location.
1791
+ * (e.g. profile functions); displayed names and locations, categorization,
1792
+ * and source map resolution always use the entry's real name and location.
1793
+ *
1794
+ * Matched entries display the _current_ profile's name and location (not
1795
+ * _base_).
774
1796
  *
775
- * Defaults to {@link defaultMatchEntry}, which strips known build hashes from
776
- * locations so that the same function matches across profiles built from the
777
- * same source.
1797
+ * Defaults to {@link defaultMatchEntry}.
778
1798
  */
779
- matchEntry?: (entry: DeepReadonly<ProfileEntry>) => NormalizedEntry | undefined;
1799
+ matchEntry?: (entry: DeepReadonly<ProfileEntry>, context: ProfileToMdContext) => EntryMatch | undefined;
780
1800
  /**
781
- * Returns a category string per entry of a single profile or snapshot, as an
782
- * array aligned with {@link entries} (index `i` categorizes entry `i`).
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.
783
1806
  *
784
- * Used to compute a category breakdown in the Markdown output.
1807
+ * Used to compute:
1808
+ * - A category breakdown in the Markdown output
1809
+ * - The `baseURL` when using `baseURL: 'auto'`
1810
+ * - Which entries to show in {@link defaultShowEntry}
785
1811
  *
786
- * Called once per profile or snapshot with all its {@link entries} and the
787
- * conversion {@link ProfileToMdContext | context} (the {@link Format | format}
788
- * and the resolved {@link Origin | origin}).
1812
+ * Called once per profile with all its {@link entries}. Receiving every entry
1813
+ * up front lets the categorizer decide from the full set rather than per
1814
+ * entry in isolation.
789
1815
  *
790
- * Receiving every entry up front lets the categorizer decide from the full
791
- * set rather than per entry in isolation.
1816
+ * Doesn't apply to heap snapshots because they record their own node
1817
+ * categories.
792
1818
  *
793
- * Defaults to {@link defaultCategorizeEntries}, which applies the library's
794
- * origin-aware categorization ({@link categorizeEntryForOrigin}).
1819
+ * Defaults to {@link defaultCategorizeFunctions}.
795
1820
  */
796
- categorizeEntries?: (entries: readonly DeepReadonly<ProfileEntry>[], context: ProfileToMdContext) => readonly EntryCategory[];
1821
+ categorizeFunctions?: (entries: readonly DeepReadonly<ProfileEntry>[], context: ProfileToMdContext) => readonly FunctionCategory[];
797
1822
  /**
798
1823
  * Whether to include the given entry in the Markdown output.
799
1824
  *
800
- * Not showing an entry does not exclude it from metric computations.
1825
+ * Hidden entries still count in metric computations.
1826
+ *
1827
+ * Defaults to {@link defaultShowEntry}.
801
1828
  */
802
- showEntry?: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
1829
+ showEntry?: (entry: DeepReadonly<AggregatedProfileEntry>, context: ProfileToMdContext) => boolean;
1830
+ };
1831
+ /** {@link ProfileToMdOptions} with defaults applied. */
1832
+ type NormalizedProfileToMdOptions = {
1833
+ topN: number;
1834
+ minCategoryShare: number;
1835
+ baseURL: URL | `auto` | undefined;
1836
+ sourceMaps: NormalizedSourceMaps;
1837
+ entryMatchKeys: (entry: ProfileEntry, context: ProfileToMdContext) => EntryMatchKeys;
1838
+ categorizeFunctions: (entries: readonly ProfileEntry[], context: ProfileToMdContext) => readonly FunctionCategory[];
1839
+ showEntry: (entry: DeepReadonly<AggregatedProfileEntry>, context: ProfileToMdContext) => boolean;
803
1840
  };
804
1841
  /**
805
- * Returns a name and location to match this entry by with known
806
- * run-varying identifiers stripped — build hashes (Cargo build-script and
807
- * rustc commit-hash directories) and JVM runtime addresses (`$$Lambda.0x…`
808
- * classes, `I2C/C2I adapters(0x…)` stubs) — or `undefined` if the entry
809
- * contains none.
1842
+ * The options aggregation code receives.
1843
+ *
1844
+ * Everything except `baseURL`, which only affects formatting and, for `'auto'`,
1845
+ * is resolvable only after aggregation (from the aggregated entries). The
1846
+ * omission keeps aggregation logic from depending on it.
1847
+ */
1848
+ type AggregationProfileToMdOptions = Omit<NormalizedProfileToMdOptions, `baseURL`>;
1849
+ /**
1850
+ * The options formatting code receives.
1851
+ *
1852
+ * {@link NormalizedProfileToMdOptions} with `'auto'` resolved to a concrete
1853
+ * base URL (or `undefined` when nothing qualified for inference).
810
1854
  */
811
- declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>) => NormalizedEntry | undefined;
1855
+ type FormattingProfileToMdOptions = AggregationProfileToMdOptions & {
1856
+ baseURL: URL | undefined;
1857
+ };
812
1858
  /**
813
- * The default {@link ProfileToMdOptions.categorizeEntries}.
1859
+ * The default {@link ProfileToMdOptions.matchEntry}.
814
1860
  *
815
- * Applies the library's origin-aware categorization to each entry (see
816
- * {@link categorizeEntryForOrigin}).
1861
+ * Applies the origin's match normalization to the entry, stripping the origin's
1862
+ * known run-varying identifiers (e.g. Rust build hashes for `pprof-rs`, JVM
1863
+ * runtime addresses for `jdk`), or `undefined` if the entry contains none.
1864
+ */
1865
+ declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>, { origin }: ProfileToMdContext) => EntryMatch | undefined;
1866
+ /**
1867
+ * The default {@link ProfileToMdOptions.categorizeFunctions}.
817
1868
  *
818
- * Exposed so a custom categorizer can reuse it as a base (e.g. override a few
819
- * entries and delegate the rest).
1869
+ * Applies the library's origin-aware categorization to each entry.
820
1870
  */
821
- declare const defaultCategorizeEntries: (entries: readonly DeepReadonly<ProfileEntry>[], {
822
- origin
823
- }: ProfileToMdContext) => EntryCategory[];
1871
+ declare const defaultCategorizeFunctions: (entries: readonly DeepReadonly<ProfileEntry>[], { origin }: ProfileToMdContext) => FunctionCategory[];
824
1872
  /**
825
1873
  * Returns whether to include the given entry in the Markdown output.
826
1874
  *
827
- * Excludes synthetic and external-private 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.
828
1878
  */
829
1879
  declare const defaultShowEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
830
1880
  /**
831
- * Returns true if the entry is a synthetic artifacts.
1881
+ * Returns true if the entry is synthetic.
832
1882
  *
833
- * These entries are artifacts generated by the profiler and don't correspond to
834
- * something that actually exists in code or at runtime. For example, a
835
- * synthetic `(root)` node is typically created for heap snapshots.
836
- */
837
- declare const isSyntheticEntry: ({
838
- name
839
- }: DeepReadonly<AggregatedProfileEntry>) => boolean;
840
- /**
841
- * Returns true if the entry corresponds to an external function (`native`,
842
- * `stdlib`, or `third-party`) that's never directly called by `ours` code.
1883
+ * The profiler invents these entries; they correspond to nothing that exists
1884
+ * in code or at runtime (e.g. a synthetic `(root)` node for heap snapshots).
843
1885
  *
844
- * These entries are typically implementation details of external code that your
845
- * own code cannot directly call. Excluding these entries from the Markdown
846
- * leaves only your code and the public API surface of `stdlib` and
847
- * `third-party` code.
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.
848
1888
  */
849
- declare const isExternalImplementationDetailEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
1889
+ declare const isSyntheticEntry: ({ name, category }: DeepReadonly<AggregatedProfileEntry>) => boolean;
850
1890
  //#endregion
851
1891
  //#region src/formats/index.d.ts
852
1892
  /**
853
1893
  * Converts the given profile data to Markdown.
854
1894
  *
855
- * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
1895
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
856
1896
  * for supported formats and generation instructions.
857
1897
  */
858
1898
  declare const profileToMd: (input: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
859
1899
  /**
860
1900
  * Asynchronously converts the given profile data to Markdown.
861
1901
  *
862
- * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
1902
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
863
1903
  * for supported formats and generation instructions.
864
1904
  */
865
1905
  declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
@@ -869,7 +1909,7 @@ declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?
869
1909
  *
870
1910
  * Each side accepts the same input as {@link profileToMd}.
871
1911
  *
872
- * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
1912
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
873
1913
  * for supported formats and generation instructions.
874
1914
  */
875
1915
  declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
@@ -879,12 +1919,21 @@ declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileIn
879
1919
  *
880
1920
  * Each side accepts the same input as {@link profileToMdAsync}.
881
1921
  *
882
- * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
1922
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
883
1923
  * for supported formats and generation instructions.
884
1924
  */
885
1925
  declare const diffProfilesAsync: (base: ProfileInput<AsyncProfileData>, current: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
886
- declare const formats: readonly ["collapsed", "jfr", "jsc-heap-snapshot", "pprof", "speedscope", "v8-cpu-profile", "v8-heap-profile", "v8-heap-snapshot", "webkit-timeline-recording"];
887
- /** Supported profile format IDs. */
888
- type Format = (typeof formats)[number];
889
1926
  //#endregion
890
- export { type AggregatedProfileEntry, type AsyncProfileData, type EntryCategory, type FileReference, type Format, type NormalizedEntry, type Origin, type ProfileData, type ProfileEntry, type ProfileInput, type ProfileToMdContext, type ProfileToMdOptions, type SourceLocation, type SourceMap, categorizeEntryForOrigin, defaultCategorizeEntries, defaultMatchEntry, defaultShowEntry, diffProfiles, diffProfilesAsync, fileReferenceId, isExternalImplementationDetailEntry, isSyntheticEntry, profileToMd, profileToMdAsync };
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 };