profiler-md 0.3.0 → 0.5.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 (225) hide show
  1. package/dist/cli/index.mjs +5331 -2044
  2. package/dist/index.d.mts +738 -229
  3. package/dist/index.js +2 -2
  4. package/docs/formats/collapsed.md +12 -0
  5. package/docs/formats/jfr.md +16 -0
  6. package/docs/formats/jsc-heap-snapshot.md +2 -2
  7. package/docs/languages/c.md +31 -7
  8. package/docs/languages/cpp.md +160 -0
  9. package/docs/languages/csharp.md +52 -0
  10. package/docs/languages/elixir.md +46 -0
  11. package/docs/languages/erlang.md +46 -0
  12. package/docs/languages/fsharp.md +52 -0
  13. package/docs/languages/go.md +11 -6
  14. package/docs/languages/java.md +110 -57
  15. package/docs/languages/javascript.md +69 -12
  16. package/docs/languages/julia.md +54 -0
  17. package/docs/languages/kotlin.md +170 -0
  18. package/docs/languages/php.md +64 -20
  19. package/docs/languages/python.md +13 -68
  20. package/docs/languages/ruby.md +17 -27
  21. package/docs/languages/typescript.md +276 -0
  22. package/examples/output/c.gperftools.cpu.base.pprof.md +324 -0
  23. package/examples/output/c.gperftools.cpu.current.pprof.md +271 -0
  24. package/examples/output/c.gperftools.cpu.diff.pprof.md +98 -0
  25. package/examples/output/c.gperftools.heap.base.pprof.md +362 -0
  26. package/examples/output/c.gperftools.heap.current.pprof.md +362 -0
  27. package/examples/output/c.gperftools.heap.diff.pprof.md +28 -0
  28. package/examples/output/cpp.gperftools.cpu.base.pprof.md +557 -0
  29. package/examples/output/cpp.gperftools.cpu.current.pprof.md +573 -0
  30. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +122 -0
  31. package/examples/output/cpp.gperftools.heap.base.pprof.md +67 -0
  32. package/examples/output/cpp.gperftools.heap.current.pprof.md +67 -0
  33. package/examples/output/cpp.gperftools.heap.diff.pprof.md +19 -0
  34. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +411 -0
  35. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +412 -0
  36. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +122 -0
  37. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +399 -0
  38. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +398 -0
  39. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +92 -0
  40. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +147 -0
  41. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +147 -0
  42. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +18 -0
  43. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +324 -0
  44. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +314 -0
  45. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +119 -0
  46. package/examples/output/go.pprof.block.base.pprof.md +86 -0
  47. package/examples/output/go.pprof.block.current.pprof.md +83 -0
  48. package/examples/output/go.pprof.block.diff.pprof.md +42 -0
  49. package/examples/output/go.pprof.cpu.base.pprof.md +81 -0
  50. package/examples/output/go.pprof.cpu.current.pprof.md +70 -0
  51. package/examples/output/go.pprof.cpu.diff.pprof.md +52 -0
  52. package/examples/output/go.pprof.goroutine.base.pprof.md +43 -0
  53. package/examples/output/go.pprof.goroutine.current.pprof.md +43 -0
  54. package/examples/output/go.pprof.goroutine.diff.pprof.md +13 -0
  55. package/examples/output/go.pprof.heap-alloc.base.pprof.md +154 -0
  56. package/examples/output/go.pprof.heap-alloc.current.pprof.md +146 -0
  57. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +67 -0
  58. package/examples/output/go.pprof.heap.base.pprof.md +154 -0
  59. package/examples/output/go.pprof.heap.current.pprof.md +146 -0
  60. package/examples/output/go.pprof.heap.diff.pprof.md +67 -0
  61. package/examples/output/go.pprof.mutex.base.pprof.md +55 -0
  62. package/examples/output/go.pprof.mutex.current.pprof.md +41 -0
  63. package/examples/output/go.pprof.mutex.diff.pprof.md +31 -0
  64. package/examples/output/go.pprof.threadcreate.base.pprof.md +55 -0
  65. package/examples/output/go.pprof.threadcreate.current.pprof.md +55 -0
  66. package/examples/output/go.pprof.threadcreate.diff.pprof.md +19 -0
  67. package/examples/output/java.async-profiler.all.base.jfr.md +1071 -0
  68. package/examples/output/java.async-profiler.all.current.jfr.md +1007 -0
  69. package/examples/output/java.async-profiler.all.diff.jfr.md +268 -0
  70. package/examples/output/java.async-profiler.alloc.base.jfr.md +425 -0
  71. package/examples/output/java.async-profiler.alloc.current.jfr.md +413 -0
  72. package/examples/output/java.async-profiler.alloc.diff.jfr.md +99 -0
  73. package/examples/output/java.async-profiler.cpu.base.collapsed.md +367 -0
  74. package/examples/output/java.async-profiler.cpu.base.jfr.md +485 -0
  75. package/examples/output/java.async-profiler.cpu.current.collapsed.md +355 -0
  76. package/examples/output/java.async-profiler.cpu.current.jfr.md +488 -0
  77. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +117 -0
  78. package/examples/output/java.async-profiler.cpu.diff.jfr.md +118 -0
  79. package/examples/output/java.async-profiler.live.base.jfr.md +697 -0
  80. package/examples/output/java.async-profiler.live.current.jfr.md +684 -0
  81. package/examples/output/java.async-profiler.live.diff.jfr.md +191 -0
  82. package/examples/output/java.async-profiler.lock.base.jfr.md +140 -0
  83. package/examples/output/java.async-profiler.lock.current.jfr.md +108 -0
  84. package/examples/output/java.async-profiler.lock.diff.jfr.md +44 -0
  85. package/examples/output/java.async-profiler.nativemem.base.jfr.md +222 -0
  86. package/examples/output/java.async-profiler.nativemem.current.jfr.md +222 -0
  87. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +65 -0
  88. package/examples/output/java.async-profiler.wall.base.jfr.md +400 -0
  89. package/examples/output/java.async-profiler.wall.current.jfr.md +420 -0
  90. package/examples/output/java.async-profiler.wall.diff.jfr.md +94 -0
  91. package/examples/output/java.jdk.all.base.jfr.md +1024 -0
  92. package/examples/output/java.jdk.all.current.jfr.md +1010 -0
  93. package/examples/output/java.jdk.all.diff.jfr.md +311 -0
  94. package/examples/output/java.jdk.alloc.base.jfr.md +1024 -0
  95. package/examples/output/java.jdk.alloc.current.jfr.md +1046 -0
  96. package/examples/output/java.jdk.alloc.diff.jfr.md +312 -0
  97. package/examples/output/java.jdk.cpu.base.jfr.md +1023 -0
  98. package/examples/output/java.jdk.cpu.current.jfr.md +1039 -0
  99. package/examples/output/java.jdk.cpu.diff.jfr.md +285 -0
  100. package/examples/output/java.jdk.live.base.jfr.md +1029 -0
  101. package/examples/output/java.jdk.live.current.jfr.md +1035 -0
  102. package/examples/output/java.jdk.live.diff.jfr.md +289 -0
  103. package/examples/output/java.jdk.lock.base.jfr.md +1040 -0
  104. package/examples/output/java.jdk.lock.current.jfr.md +1051 -0
  105. package/examples/output/java.jdk.lock.diff.jfr.md +339 -0
  106. package/examples/output/javascript.bun.base.cpuprofile.md +73 -0
  107. package/examples/output/javascript.bun.base.heapsnapshot.md +608 -0
  108. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +480 -0
  109. package/examples/output/javascript.bun.current.cpuprofile.md +73 -0
  110. package/examples/output/javascript.bun.current.heapsnapshot.md +608 -0
  111. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +480 -0
  112. package/examples/output/javascript.bun.diff.cpuprofile.md +54 -0
  113. package/examples/output/javascript.bun.diff.heapsnapshot.md +48 -0
  114. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +62 -0
  115. package/examples/output/javascript.chrome.base.cpuprofile.md +163 -0
  116. package/examples/output/javascript.chrome.base.heapprofile.md +32 -0
  117. package/examples/output/javascript.chrome.base.heapsnapshot.md +649 -0
  118. package/examples/output/javascript.chrome.current.cpuprofile.md +149 -0
  119. package/examples/output/javascript.chrome.current.heapprofile.md +32 -0
  120. package/examples/output/javascript.chrome.current.heapsnapshot.md +647 -0
  121. package/examples/output/javascript.chrome.diff.cpuprofile.md +65 -0
  122. package/examples/output/javascript.chrome.diff.heapprofile.md +50 -0
  123. package/examples/output/javascript.chrome.diff.heapsnapshot.md +73 -0
  124. package/examples/output/javascript.deno.base.cpuprofile.md +122 -0
  125. package/examples/output/javascript.deno.current.cpuprofile.md +114 -0
  126. package/examples/output/javascript.deno.diff.cpuprofile.md +66 -0
  127. package/examples/output/javascript.node.base.cpuprofile.md +136 -0
  128. package/examples/output/javascript.node.base.heapprofile.md +56 -0
  129. package/examples/output/javascript.node.base.heapsnapshot.md +660 -0
  130. package/examples/output/javascript.node.current.cpuprofile.md +119 -0
  131. package/examples/output/javascript.node.current.heapprofile.md +52 -0
  132. package/examples/output/javascript.node.current.heapsnapshot.md +660 -0
  133. package/examples/output/javascript.node.diff.cpuprofile.md +70 -0
  134. package/examples/output/javascript.node.diff.heapprofile.md +34 -0
  135. package/examples/output/javascript.node.diff.heapsnapshot.md +39 -0
  136. package/examples/output/javascript.pprof.cpu.base.pprof.md +104 -0
  137. package/examples/output/javascript.pprof.cpu.current.pprof.md +120 -0
  138. package/examples/output/javascript.pprof.cpu.diff.pprof.md +63 -0
  139. package/examples/output/javascript.pprof.heap.base.pprof.md +86 -0
  140. package/examples/output/javascript.pprof.heap.current.pprof.md +57 -0
  141. package/examples/output/javascript.pprof.heap.diff.pprof.md +42 -0
  142. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +388 -0
  143. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +378 -0
  144. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +122 -0
  145. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +124 -0
  146. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +126 -0
  147. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +30 -0
  148. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +177 -0
  149. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +179 -0
  150. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +64 -0
  151. package/examples/output/kotlin.async-profiler.all.base.jfr.md +920 -0
  152. package/examples/output/kotlin.async-profiler.all.current.jfr.md +925 -0
  153. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +247 -0
  154. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +467 -0
  155. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +473 -0
  156. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +122 -0
  157. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +371 -0
  158. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +472 -0
  159. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +370 -0
  160. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +445 -0
  161. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +124 -0
  162. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +125 -0
  163. package/examples/output/kotlin.async-profiler.live.base.jfr.md +934 -0
  164. package/examples/output/kotlin.async-profiler.live.current.jfr.md +917 -0
  165. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +245 -0
  166. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +1 -0
  167. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +1 -0
  168. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +1 -0
  169. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +234 -0
  170. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +234 -0
  171. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +65 -0
  172. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +452 -0
  173. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +457 -0
  174. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +125 -0
  175. package/examples/output/kotlin.jdk.all.base.jfr.md +1442 -0
  176. package/examples/output/kotlin.jdk.all.current.jfr.md +1343 -0
  177. package/examples/output/kotlin.jdk.all.diff.jfr.md +392 -0
  178. package/examples/output/kotlin.jdk.alloc.base.jfr.md +1418 -0
  179. package/examples/output/kotlin.jdk.alloc.current.jfr.md +1389 -0
  180. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +383 -0
  181. package/examples/output/kotlin.jdk.cpu.base.jfr.md +1406 -0
  182. package/examples/output/kotlin.jdk.cpu.current.jfr.md +1374 -0
  183. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +380 -0
  184. package/examples/output/kotlin.jdk.live.base.jfr.md +1378 -0
  185. package/examples/output/kotlin.jdk.live.current.jfr.md +1311 -0
  186. package/examples/output/kotlin.jdk.live.diff.jfr.md +381 -0
  187. package/examples/output/kotlin.jdk.lock.base.jfr.md +1427 -0
  188. package/examples/output/kotlin.jdk.lock.current.jfr.md +1374 -0
  189. package/examples/output/kotlin.jdk.lock.diff.jfr.md +386 -0
  190. package/examples/output/php.excimer.wall.base.speedscope.json.md +25 -0
  191. package/examples/output/php.excimer.wall.current.speedscope.json.md +25 -0
  192. package/examples/output/php.excimer.wall.diff.speedscope.json.md +29 -0
  193. package/examples/output/python.py-spy.cpu.base.collapsed.md +526 -0
  194. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +37 -0
  195. package/examples/output/python.py-spy.cpu.current.collapsed.md +514 -0
  196. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +37 -0
  197. package/examples/output/python.py-spy.cpu.diff.collapsed.md +122 -0
  198. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +31 -0
  199. package/examples/output/python.py-spy.wall.base.collapsed.md +527 -0
  200. package/examples/output/python.py-spy.wall.current.collapsed.md +518 -0
  201. package/examples/output/python.py-spy.wall.diff.collapsed.md +122 -0
  202. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +90 -0
  203. package/examples/output/ruby.rbspy.cpu.base.pprof.md +105 -0
  204. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +105 -0
  205. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +90 -0
  206. package/examples/output/ruby.rbspy.cpu.current.pprof.md +115 -0
  207. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +115 -0
  208. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +32 -0
  209. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +44 -0
  210. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +44 -0
  211. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +60 -0
  212. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +60 -0
  213. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +24 -0
  214. package/package.json +27 -20
  215. package/readme.md +201 -87
  216. package/examples/bun.cpuprofile.md +0 -475
  217. package/examples/deno.cpuprofile.md +0 -481
  218. package/examples/jsc-heap-snapshot.json.md +0 -509
  219. package/examples/node.cpuprofile.md +0 -485
  220. package/examples/node.heapprofile.md +0 -281
  221. package/examples/node.heapsnapshot.md +0 -694
  222. package/examples/node.pprof.md +0 -441
  223. package/examples/node.speedscope.json.md +0 -408
  224. package/examples/rust.pprof.md +0 -477
  225. package/examples/webkit-timeline-recording.json.md +0 -434
package/dist/index.d.mts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { RawSourceMap as SourceMap } from "source-map-js";
2
+
2
3
  //#region src/helpers/types.d.ts
3
4
  type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float16Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
4
5
  /**
@@ -8,14 +9,613 @@ type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint
8
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;
9
10
  //#endregion
10
11
  //#region src/location.d.ts
11
- /** A {@link URL} to a file, potentially with line and column information. */
12
- type ProfileLocation = {
13
- url: URL; /** The 1-based line number in the file at {@link ProfileLocation.url}. */
14
- line?: number; /** The 1-based column number in the file at {@link ProfileLocation.url}. */
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. */
15
15
  column?: number;
16
16
  };
17
+ declare const fileReferenceId: (fileReference: DeepReadonly<FileReference>) => string;
18
+ type FileReference = {
19
+ type: `absolute`;
20
+ url: URL;
21
+ } | {
22
+ type: `relative`;
23
+ path: string;
24
+ };
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}. */
28
+ column?: number;
29
+ };
30
+ //#endregion
31
+ //#region src/profile/type.d.ts
32
+ /**
33
+ * A function occurrence at an executing position.
34
+ *
35
+ * Its {@link name} and {@link location} (the function's *definition* location)
36
+ * identify the function; frames sharing them are the same function.
37
+ *
38
+ * {@link line} is the *executing* line and feeds the per-line breakdown, not
39
+ * identity.
40
+ *
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.
44
+ */
45
+ type ProfileStackFrame = {
46
+ /** The function's name, if known. */name?: string; /** Where the function was defined, if known. */
47
+ location?: SourceLocationInput;
48
+ /**
49
+ * The 1-based line at which this frame was sampled, if known.
50
+ *
51
+ * Distinct from {@link location}'s line (the definition line): this is the
52
+ * executing line, which the aggregator forwards to the leaf function's
53
+ * per-line breakdown. Never a function-identity component.
54
+ */
55
+ line?: number;
56
+ };
57
+ //#endregion
58
+ //#region src/origins/index.d.ts
59
+ /**
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`).
62
+ *
63
+ * Auto-detected from a profile's entries via {@link determineOrigin}, or
64
+ * specified explicitly.
65
+ */
66
+ type Origin = SpecificOriginSpec[`id`];
67
+ /**
68
+ * Returns the category of {@link entry} as the given {@link origin} categorizes
69
+ * it (see {@link OriginSpec.categorize}).
70
+ *
71
+ * The origin-aware categorization the library applies by default. Exposed so a
72
+ * custom `categorizeEntries` can reuse the library's categorization for an
73
+ * origin it didn't special-case, rather than reimplementing it.
74
+ */
75
+ declare const categorizeEntryForOrigin: (entry: DeepReadonly<ProfileEntry>, origin: Origin) => EntryCategory;
76
+ /**
77
+ * All origin specs in global detection-priority order.
78
+ *
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).
83
+ */
84
+ declare const originSpecs: ({
85
+ readonly id: "deno";
86
+ readonly language: "javascript";
87
+ readonly formats: ["v8-cpu-profile"];
88
+ readonly matchesEntry: ({
89
+ location
90
+ }: {
91
+ readonly id: number;
92
+ readonly name?: string | undefined;
93
+ readonly location?: {
94
+ readonly type: `absolute`;
95
+ readonly url: URL;
96
+ readonly line?: number | undefined;
97
+ readonly column?: number | undefined;
98
+ } | {
99
+ readonly type: `relative`;
100
+ readonly path: string;
101
+ readonly line?: number | undefined;
102
+ readonly column?: number | undefined;
103
+ } | undefined;
104
+ }) => boolean;
105
+ readonly categorize: (entry: {
106
+ readonly id: number;
107
+ readonly name?: string | undefined;
108
+ readonly location?: {
109
+ readonly type: `absolute`;
110
+ readonly url: URL;
111
+ readonly line?: number | undefined;
112
+ readonly column?: number | undefined;
113
+ } | {
114
+ readonly type: `relative`;
115
+ readonly path: string;
116
+ readonly line?: number | undefined;
117
+ readonly column?: number | undefined;
118
+ } | undefined;
119
+ }) => EntryCategory;
120
+ } | {
121
+ readonly id: "bun";
122
+ readonly language: "javascript";
123
+ readonly formats: ["v8-cpu-profile"];
124
+ readonly matchesEntry: ({
125
+ name,
126
+ location
127
+ }: {
128
+ readonly id: number;
129
+ readonly name?: string | undefined;
130
+ readonly location?: {
131
+ readonly type: `absolute`;
132
+ readonly url: URL;
133
+ readonly line?: number | undefined;
134
+ readonly column?: number | undefined;
135
+ } | {
136
+ readonly type: `relative`;
137
+ readonly path: string;
138
+ readonly line?: number | undefined;
139
+ readonly column?: number | undefined;
140
+ } | undefined;
141
+ }) => boolean;
142
+ readonly categorize: (entry: {
143
+ readonly id: number;
144
+ readonly name?: string | undefined;
145
+ readonly location?: {
146
+ readonly type: `absolute`;
147
+ readonly url: URL;
148
+ readonly line?: number | undefined;
149
+ readonly column?: number | undefined;
150
+ } | {
151
+ readonly type: `relative`;
152
+ readonly path: string;
153
+ readonly line?: number | undefined;
154
+ readonly column?: number | undefined;
155
+ } | undefined;
156
+ }) => EntryCategory;
157
+ } | {
158
+ readonly id: "node";
159
+ readonly language: "javascript";
160
+ readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile"];
161
+ readonly matchesEntry: ({
162
+ location
163
+ }: {
164
+ readonly id: number;
165
+ readonly name?: string | undefined;
166
+ readonly location?: {
167
+ readonly type: `absolute`;
168
+ readonly url: URL;
169
+ readonly line?: number | undefined;
170
+ readonly column?: number | undefined;
171
+ } | {
172
+ readonly type: `relative`;
173
+ readonly path: string;
174
+ readonly line?: number | undefined;
175
+ readonly column?: number | undefined;
176
+ } | undefined;
177
+ }) => boolean;
178
+ readonly categorize: (entry: {
179
+ readonly id: number;
180
+ readonly name?: string | undefined;
181
+ readonly location?: {
182
+ readonly type: `absolute`;
183
+ readonly url: URL;
184
+ readonly line?: number | undefined;
185
+ readonly column?: number | undefined;
186
+ } | {
187
+ readonly type: `relative`;
188
+ readonly path: string;
189
+ readonly line?: number | undefined;
190
+ readonly column?: number | undefined;
191
+ } | undefined;
192
+ }) => EntryCategory;
193
+ } | {
194
+ readonly id: "node-pprof";
195
+ readonly language: "javascript";
196
+ readonly formats: ["pprof"];
197
+ readonly matchesEntry: ({
198
+ name,
199
+ location
200
+ }: {
201
+ readonly id: number;
202
+ readonly name?: string | undefined;
203
+ readonly location?: {
204
+ readonly type: `absolute`;
205
+ readonly url: URL;
206
+ readonly line?: number | undefined;
207
+ readonly column?: number | undefined;
208
+ } | {
209
+ readonly type: `relative`;
210
+ readonly path: string;
211
+ readonly line?: number | undefined;
212
+ readonly column?: number | undefined;
213
+ } | undefined;
214
+ }) => boolean;
215
+ readonly categorize: (entry: {
216
+ readonly id: number;
217
+ readonly name?: string | undefined;
218
+ readonly location?: {
219
+ readonly type: `absolute`;
220
+ readonly url: URL;
221
+ readonly line?: number | undefined;
222
+ readonly column?: number | undefined;
223
+ } | {
224
+ readonly type: `relative`;
225
+ readonly path: string;
226
+ readonly line?: number | undefined;
227
+ readonly column?: number | undefined;
228
+ } | undefined;
229
+ }) => EntryCategory;
230
+ readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
231
+ } | {
232
+ readonly id: "pprof-rs";
233
+ readonly language: "rust";
234
+ readonly formats: ["pprof"];
235
+ readonly matchesEntry: (entry: {
236
+ readonly id: number;
237
+ readonly name?: string | undefined;
238
+ readonly location?: {
239
+ readonly type: `absolute`;
240
+ readonly url: URL;
241
+ readonly line?: number | undefined;
242
+ readonly column?: number | undefined;
243
+ } | {
244
+ readonly type: `relative`;
245
+ readonly path: string;
246
+ readonly line?: number | undefined;
247
+ readonly column?: number | undefined;
248
+ } | undefined;
249
+ }) => boolean;
250
+ readonly categorize: (entry: {
251
+ readonly id: number;
252
+ readonly name?: string | undefined;
253
+ readonly location?: {
254
+ readonly type: `absolute`;
255
+ readonly url: URL;
256
+ readonly line?: number | undefined;
257
+ readonly column?: number | undefined;
258
+ } | {
259
+ readonly type: `relative`;
260
+ readonly path: string;
261
+ readonly line?: number | undefined;
262
+ readonly column?: number | undefined;
263
+ } | undefined;
264
+ }) => EntryCategory;
265
+ } | {
266
+ readonly id: "go";
267
+ readonly language: "go";
268
+ readonly formats: ["pprof"];
269
+ readonly matchesEntry: (entry: {
270
+ readonly id: number;
271
+ readonly name?: string | undefined;
272
+ readonly location?: {
273
+ readonly type: `absolute`;
274
+ readonly url: URL;
275
+ readonly line?: number | undefined;
276
+ readonly column?: number | undefined;
277
+ } | {
278
+ readonly type: `relative`;
279
+ readonly path: string;
280
+ readonly line?: number | undefined;
281
+ readonly column?: number | undefined;
282
+ } | undefined;
283
+ }) => boolean;
284
+ readonly categorize: (entry: {
285
+ readonly id: number;
286
+ readonly name?: string | undefined;
287
+ readonly location?: {
288
+ readonly type: `absolute`;
289
+ readonly url: URL;
290
+ readonly line?: number | undefined;
291
+ readonly column?: number | undefined;
292
+ } | {
293
+ readonly type: `relative`;
294
+ readonly path: string;
295
+ readonly line?: number | undefined;
296
+ readonly column?: number | undefined;
297
+ } | undefined;
298
+ }) => EntryCategory;
299
+ } | {
300
+ readonly id: "pprof-jl";
301
+ readonly language: "julia";
302
+ readonly formats: ["pprof"];
303
+ readonly matchesEntry: (entry: {
304
+ readonly id: number;
305
+ readonly name?: string | undefined;
306
+ readonly location?: {
307
+ readonly type: `absolute`;
308
+ readonly url: URL;
309
+ readonly line?: number | undefined;
310
+ readonly column?: number | undefined;
311
+ } | {
312
+ readonly type: `relative`;
313
+ readonly path: string;
314
+ readonly line?: number | undefined;
315
+ readonly column?: number | undefined;
316
+ } | undefined;
317
+ }) => boolean;
318
+ readonly categorize: (entry: {
319
+ readonly id: number;
320
+ readonly name?: string | undefined;
321
+ readonly location?: {
322
+ readonly type: `absolute`;
323
+ readonly url: URL;
324
+ readonly line?: number | undefined;
325
+ readonly column?: number | undefined;
326
+ } | {
327
+ readonly type: `relative`;
328
+ readonly path: string;
329
+ readonly line?: number | undefined;
330
+ readonly column?: number | undefined;
331
+ } | undefined;
332
+ }) => EntryCategory;
333
+ readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame | null;
334
+ } | {
335
+ readonly id: "py-spy";
336
+ readonly language: "python";
337
+ readonly formats: ["collapsed", "speedscope"];
338
+ readonly matchesEntry: (entry: {
339
+ readonly id: number;
340
+ readonly name?: string | undefined;
341
+ readonly location?: {
342
+ readonly type: `absolute`;
343
+ readonly url: URL;
344
+ readonly line?: number | undefined;
345
+ readonly column?: number | undefined;
346
+ } | {
347
+ readonly type: `relative`;
348
+ readonly path: string;
349
+ readonly line?: number | undefined;
350
+ readonly column?: number | undefined;
351
+ } | undefined;
352
+ }) => 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;
355
+ } | {
356
+ readonly id: "tachyon";
357
+ readonly language: "python";
358
+ readonly formats: ["collapsed"];
359
+ readonly matchesEntry: (entry: {
360
+ readonly id: number;
361
+ readonly name?: string | undefined;
362
+ readonly location?: {
363
+ readonly type: `absolute`;
364
+ readonly url: URL;
365
+ readonly line?: number | undefined;
366
+ readonly column?: number | undefined;
367
+ } | {
368
+ readonly type: `relative`;
369
+ readonly path: string;
370
+ readonly line?: number | undefined;
371
+ readonly column?: number | undefined;
372
+ } | undefined;
373
+ }) => boolean;
374
+ readonly categorize: (entry: DeepReadonly<ProfileEntry>) => EntryCategory;
375
+ readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
376
+ } | {
377
+ readonly id: "jvm";
378
+ readonly language: "java";
379
+ readonly formats: ["jfr", "collapsed"];
380
+ readonly matchesEntry: (entry: {
381
+ readonly id: number;
382
+ readonly name?: string | undefined;
383
+ readonly location?: {
384
+ readonly type: `absolute`;
385
+ readonly url: URL;
386
+ readonly line?: number | undefined;
387
+ readonly column?: number | undefined;
388
+ } | {
389
+ readonly type: `relative`;
390
+ readonly path: string;
391
+ readonly line?: number | undefined;
392
+ readonly column?: number | undefined;
393
+ } | undefined;
394
+ }) => boolean;
395
+ readonly categorize: (entry: {
396
+ readonly id: number;
397
+ readonly name?: string | undefined;
398
+ readonly location?: {
399
+ readonly type: `absolute`;
400
+ readonly url: URL;
401
+ readonly line?: number | undefined;
402
+ readonly column?: number | undefined;
403
+ } | {
404
+ readonly type: `relative`;
405
+ readonly path: string;
406
+ readonly line?: number | undefined;
407
+ readonly column?: number | undefined;
408
+ } | undefined;
409
+ }) => EntryCategory;
410
+ readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
411
+ } | {
412
+ readonly id: "dotnet-trace";
413
+ readonly language: null;
414
+ readonly formats: ["speedscope"];
415
+ readonly matchesEntry: (entry: {
416
+ readonly id: number;
417
+ readonly name?: string | undefined;
418
+ readonly location?: {
419
+ readonly type: `absolute`;
420
+ readonly url: URL;
421
+ readonly line?: number | undefined;
422
+ readonly column?: number | undefined;
423
+ } | {
424
+ readonly type: `relative`;
425
+ readonly path: string;
426
+ readonly line?: number | undefined;
427
+ readonly column?: number | undefined;
428
+ } | undefined;
429
+ }) => boolean;
430
+ readonly categorize: (entry: {
431
+ readonly id: number;
432
+ readonly name?: string | undefined;
433
+ readonly location?: {
434
+ readonly type: `absolute`;
435
+ readonly url: URL;
436
+ readonly line?: number | undefined;
437
+ readonly column?: number | undefined;
438
+ } | {
439
+ readonly type: `relative`;
440
+ readonly path: string;
441
+ readonly line?: number | undefined;
442
+ readonly column?: number | undefined;
443
+ } | undefined;
444
+ }) => EntryCategory;
445
+ readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame | null;
446
+ } | {
447
+ readonly id: "beam";
448
+ readonly language: null;
449
+ readonly formats: ["collapsed"];
450
+ readonly matchesEntry: (entry: {
451
+ readonly id: number;
452
+ readonly name?: string | undefined;
453
+ readonly location?: {
454
+ readonly type: `absolute`;
455
+ readonly url: URL;
456
+ readonly line?: number | undefined;
457
+ readonly column?: number | undefined;
458
+ } | {
459
+ readonly type: `relative`;
460
+ readonly path: string;
461
+ readonly line?: number | undefined;
462
+ readonly column?: number | undefined;
463
+ } | undefined;
464
+ }) => boolean;
465
+ readonly categorize: (entry: {
466
+ readonly id: number;
467
+ readonly name?: string | undefined;
468
+ readonly location?: {
469
+ readonly type: `absolute`;
470
+ readonly url: URL;
471
+ readonly line?: number | undefined;
472
+ readonly column?: number | undefined;
473
+ } | {
474
+ readonly type: `relative`;
475
+ readonly path: string;
476
+ readonly line?: number | undefined;
477
+ readonly column?: number | undefined;
478
+ } | undefined;
479
+ }) => EntryCategory;
480
+ readonly normalizeFrame: (input: ProfileStackFrame) => ProfileStackFrame;
481
+ } | {
482
+ readonly id: "rbspy";
483
+ readonly language: "ruby";
484
+ readonly formats: ["collapsed", "pprof", "speedscope"];
485
+ readonly matchesEntry: (entry: {
486
+ readonly id: number;
487
+ readonly name?: string | undefined;
488
+ readonly location?: {
489
+ readonly type: `absolute`;
490
+ readonly url: URL;
491
+ readonly line?: number | undefined;
492
+ readonly column?: number | undefined;
493
+ } | {
494
+ readonly type: `relative`;
495
+ readonly path: string;
496
+ readonly line?: number | undefined;
497
+ readonly column?: number | undefined;
498
+ } | undefined;
499
+ }) => boolean;
500
+ readonly categorize: (entry: {
501
+ readonly id: number;
502
+ readonly name?: string | undefined;
503
+ readonly location?: {
504
+ readonly type: `absolute`;
505
+ readonly url: URL;
506
+ readonly line?: number | undefined;
507
+ readonly column?: number | undefined;
508
+ } | {
509
+ readonly type: `relative`;
510
+ readonly path: string;
511
+ readonly line?: number | undefined;
512
+ readonly column?: number | undefined;
513
+ } | 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;
516
+ } | {
517
+ readonly id: "safari";
518
+ readonly language: "javascript";
519
+ readonly formats: ["jsc-heap-snapshot", "webkit-timeline-recording"];
520
+ readonly matchesEntry: ({
521
+ name,
522
+ location
523
+ }: DeepReadonly<ProfileEntry>) => boolean;
524
+ readonly categorize: (entry: {
525
+ readonly id: number;
526
+ readonly name?: string | undefined;
527
+ readonly location?: {
528
+ readonly type: `absolute`;
529
+ readonly url: URL;
530
+ readonly line?: number | undefined;
531
+ readonly column?: number | undefined;
532
+ } | {
533
+ readonly type: `relative`;
534
+ readonly path: string;
535
+ readonly line?: number | undefined;
536
+ readonly column?: number | undefined;
537
+ } | undefined;
538
+ }) => EntryCategory;
539
+ } | {
540
+ readonly id: "unknown";
541
+ readonly language: null;
542
+ readonly formats: [];
543
+ readonly matchesEntry: () => false;
544
+ readonly categorize: (entry: {
545
+ readonly id: number;
546
+ readonly name?: string | undefined;
547
+ readonly location?: {
548
+ readonly type: `absolute`;
549
+ readonly url: URL;
550
+ readonly line?: number | undefined;
551
+ readonly column?: number | undefined;
552
+ } | {
553
+ readonly type: `relative`;
554
+ readonly path: string;
555
+ readonly line?: number | undefined;
556
+ readonly column?: number | undefined;
557
+ } | undefined;
558
+ }) => EntryCategory;
559
+ })[];
560
+ /** One of the concrete origin specs, with its literal {@link Origin} ID. */
561
+ type SpecificOriginSpec = (typeof originSpecs)[number];
562
+ /** Every supported origin ID. */
17
563
  //#endregion
18
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 = {
567
+ /**
568
+ * The number of samples taken directly within the function's body at this
569
+ * line.
570
+ */
571
+ sampleCount: number;
572
+ /**
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.
575
+ */
576
+ values: Float64Array;
577
+ };
578
+ /**
579
+ * An aggregation of samples taken directly within a function's body with a
580
+ * given direct caller.
581
+ */
582
+ type AggregatedProfileCallerMetrics = {
583
+ /** The caller corresponding to the ID. */caller: AggregatedProfileFunction;
584
+ /**
585
+ * The number of samples taken directly within the function's body with this
586
+ * caller.
587
+ */
588
+ selfSampleCount: number;
589
+ /**
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.
592
+ */
593
+ selfValues: Float64Array;
594
+ };
595
+ /**
596
+ * An aggregation of samples taken within a function's body, _and_ all its
597
+ * callees, with a given direct callee.
598
+ */
599
+ type AggregatedProfileCalleeMetrics = {
600
+ /** The callee corresponding to the ID. */callee: AggregatedProfileFunction;
601
+ /**
602
+ * The number of samples taken directly within the function's body, _and_
603
+ * all its callees, with this callee.
604
+ */
605
+ totalSampleCount: number;
606
+ /**
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.
610
+ */
611
+ totalValues: Float64Array;
612
+ /**
613
+ * 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
615
+ * one call stack is counted just once.
616
+ */
617
+ lastSeenEpoch: number;
618
+ };
19
619
  /**
20
620
  * An aggregation of data from every sample involving a given function within a
21
621
  * profile.
@@ -24,7 +624,7 @@ type AggregatedProfileFunction = {
24
624
  type: `function`; /** An index that uniquely identifies this function. */
25
625
  id: number; /** The name of the function in code. */
26
626
  name: string; /** Where the function was defined, if known. */
27
- location?: ProfileLocation; /** A string describing the category of functions this function belongs to.*/
627
+ location?: SourceLocation; /** The category of functions this function belongs to. */
28
628
  category: string;
29
629
  /**
30
630
  * The number of samples taken directly within the function's body, excluding
@@ -46,53 +646,17 @@ type AggregatedProfileFunction = {
46
646
  * taken directly within the function's body _and_ all its callees.
47
647
  */
48
648
  totalValues: Float64Array; /** 1-based line number to values and sample count for that line. */
49
- lineToMetrics: Map<number, {
50
- /**
51
- * The number of samples taken directly within the function's body at this
52
- * line.
53
- */
54
- sampleCount: number;
55
- /**
56
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
57
- * samples taken directly within the function's body at this line.
58
- */
59
- values: Float64Array;
60
- }>;
649
+ lineToMetrics: Map<number, AggregatedProfileLineMetrics>;
61
650
  /**
62
651
  * Direct caller id to values and sample count with that caller's calls to
63
652
  * this function.
64
653
  */
65
- callerIdToMetrics: Map<number, {
66
- /** The caller corresponding to the ID. */caller: AggregatedProfileFunction;
67
- /**
68
- * The number of samples taken directly within the function's body with
69
- * this caller.
70
- */
71
- selfSampleCount: number;
72
- /**
73
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
74
- * samples taken directly within the function's body with this caller.
75
- */
76
- selfValues: Float64Array;
77
- }>;
654
+ callerIdToMetrics: Map<number, AggregatedProfileCallerMetrics>;
78
655
  /**
79
656
  * Direct callee id to values and sample count for that callee's calls where
80
657
  * this function was a direct or transitive caller.
81
658
  */
82
- calleeIdToMetrics: Map<number, {
83
- /** The callee corresponding to the ordinal. */callee: AggregatedProfileFunction;
84
- /**
85
- * The number of samples taken directly within the function's, _and_ all
86
- * its callees, with this callee.
87
- */
88
- totalSampleCount: number;
89
- /**
90
- * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
91
- * samples taken directly within the function's body, _and_ all its
92
- * callees. with this callee.
93
- */
94
- totalValues: Float64Array;
95
- }>;
659
+ calleeIdToMetrics: Map<number, AggregatedProfileCalleeMetrics>;
96
660
  };
97
661
  //#endregion
98
662
  //#region src/snapshot/aggregate.d.ts
@@ -106,21 +670,27 @@ type AggregatedSnapshotNode = {
106
670
  * the node were garbage collected.
107
671
  */
108
672
  retainedSize: number; /** The exact location where the node was defined. */
109
- location?: ProfileLocation;
673
+ location?: SourceLocation;
110
674
  };
111
675
  //#endregion
112
676
  //#region src/options.d.ts
113
677
  /** Profile data that can be synchronously parsed and converted to Markdown. */
114
- type BinaryProfileData = Uint8Array | Iterable<Uint8Array>;
115
- /**
116
- * JSON profile data that can be synchronously parsed and converted to Markdown.
117
- */
118
- type JsonProfileData = string | BinaryProfileData;
678
+ type ProfileData = string | Uint8Array | Iterable<Uint8Array>;
119
679
  /** Profile data that can be asynchronously parsed and converted to Markdown. */
120
680
  type AsyncProfileData = Blob | ReadableStream<Uint8Array>;
681
+ /**
682
+ * Profile data with an optional explicit format and origin.
683
+ *
684
+ * The format and origin are auto-detected if not specified.
685
+ */
686
+ type ProfileInput<Data> = Data | {
687
+ data: Data;
688
+ format?: Format;
689
+ origin?: Origin;
690
+ };
121
691
  /** The category of code an entry originated from. */
122
- type EntryOrigin = `ours` | `stdlib` | `third-party`;
123
- /** A single entry in a rendered profile. */
692
+ type EntryCategory = `ours` | `native` | `stdlib` | `third-party` | (string & {});
693
+ /** A single entry in a formatted profile. */
124
694
  type ProfileEntry = {
125
695
  /** An index that uniquely identifies this entry. */id: number;
126
696
  /**
@@ -132,10 +702,32 @@ type ProfileEntry = {
132
702
  * The location where the entity corresponding to this entry was defined, or
133
703
  * undefined if it's unknown.
134
704
  */
135
- location?: ProfileLocation;
705
+ location?: SourceLocation;
136
706
  };
137
- /** A aggregated entry in a rendered profile. */
707
+ /**
708
+ * Normalized entry fields used to match an entry across diffed profiles.
709
+ *
710
+ * Only affects matching; the entry's displayed name and location are
711
+ * unchanged.
712
+ */
713
+ type NormalizedEntry = {
714
+ /** The name to match by. Omit to match by the entry's name. */name?: string;
715
+ /**
716
+ * The location to match by, as a URL or file path string. Omit to match by
717
+ * the entry's location.
718
+ */
719
+ location?: string;
720
+ };
721
+ /** A aggregated entry in a formatted profile. */
138
722
  type AggregatedProfileEntry = AggregatedProfileFunction | AggregatedSnapshotNode;
723
+ /**
724
+ * The context in which a single profile or snapshot is being converted to
725
+ * Markdown.
726
+ */
727
+ 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. */
729
+ origin: Origin;
730
+ };
139
731
  /** Options for profile to Markdown converters. */
140
732
  type ProfileToMdOptions = {
141
733
  /**
@@ -148,29 +740,19 @@ type ProfileToMdOptions = {
148
740
  */
149
741
  topN?: number;
150
742
  /**
151
- * Returns an arbitrary category string for this entry.
743
+ * Base URL to show paths relative to in the Markdown output.
152
744
  *
153
- * Used to compute a category breakdown in the Markdown output.
154
- */
155
- categorizeEntry?: (entry: DeepReadonly<ProfileEntry>) => EntryOrigin | (string & {});
156
- /**
157
- * Whether to include the given entry in the Markdown output.
745
+ * Accepts an absolute file path string or URL. File paths are converted to
746
+ * `file://` URLs internally.
158
747
  *
159
- * Not showing an entry does not exclude it from metric computations.
160
- */
161
- showEntry?: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
162
- /**
163
- * The current working directory to use to make file paths relative in the
164
- * Markdown output.
165
- *
166
- * A value of `null` indicates that the paths should be absolute.
748
+ * A value of `null` indicates that URLs should be absolute.
167
749
  *
168
750
  * Defaults to `process.cwd()` when available. Otherwise leaves paths
169
751
  * absolute.
170
752
  */
171
- cwd?: string | null;
753
+ baseURL?: string | URL | null;
172
754
  /**
173
- * Source maps to apply when rendering profile locations.
755
+ * Source maps to apply when formatting profile locations.
174
756
  *
175
757
  * Accepts either a list of raw source map objects, or a record mapping
176
758
  * generated file URLs or absolute/relative paths to raw source map objects.
@@ -179,14 +761,66 @@ type ProfileToMdOptions = {
179
761
  * map's `file` field (and optionally `sourceRoot`).
180
762
  */
181
763
  sourceMaps?: SourceMap[] | Record<string, SourceMap>;
764
+ /**
765
+ * Returns a normalized name and location to match this entry by across
766
+ * diffed profiles, or `undefined` to match by the entry's own name and
767
+ * location.
768
+ *
769
+ * 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.
774
+ *
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.
778
+ */
779
+ matchEntry?: (entry: DeepReadonly<ProfileEntry>) => NormalizedEntry | undefined;
780
+ /**
781
+ * Returns a category string per entry of a single profile or snapshot, as an
782
+ * array aligned with {@link entries} (index `i` categorizes entry `i`).
783
+ *
784
+ * Used to compute a category breakdown in the Markdown output.
785
+ *
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}).
789
+ *
790
+ * Receiving every entry up front lets the categorizer decide from the full
791
+ * set rather than per entry in isolation.
792
+ *
793
+ * Defaults to {@link defaultCategorizeEntries}, which applies the library's
794
+ * origin-aware categorization ({@link categorizeEntryForOrigin}).
795
+ */
796
+ categorizeEntries?: (entries: readonly DeepReadonly<ProfileEntry>[], context: ProfileToMdContext) => readonly EntryCategory[];
797
+ /**
798
+ * Whether to include the given entry in the Markdown output.
799
+ *
800
+ * Not showing an entry does not exclude it from metric computations.
801
+ */
802
+ showEntry?: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
182
803
  };
183
804
  /**
184
- * Returns an arbitrary category string for this entry.
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.
810
+ */
811
+ declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>) => NormalizedEntry | undefined;
812
+ /**
813
+ * The default {@link ProfileToMdOptions.categorizeEntries}.
814
+ *
815
+ * Applies the library's origin-aware categorization to each entry (see
816
+ * {@link categorizeEntryForOrigin}).
185
817
  *
186
- * Categorizes into `ours`, `stdlib`, `third-party`, and a few other categories
187
- * by default.
818
+ * Exposed so a custom categorizer can reuse it as a base (e.g. override a few
819
+ * entries and delegate the rest).
188
820
  */
189
- declare const defaultCategorizeEntry: (entry: DeepReadonly<ProfileEntry>) => EntryOrigin | (string & {});
821
+ declare const defaultCategorizeEntries: (entries: readonly DeepReadonly<ProfileEntry>[], {
822
+ origin
823
+ }: ProfileToMdContext) => EntryCategory[];
190
824
  /**
191
825
  * Returns whether to include the given entry in the Markdown output.
192
826
  *
@@ -204,178 +838,53 @@ declare const isSyntheticEntry: ({
204
838
  name
205
839
  }: DeepReadonly<AggregatedProfileEntry>) => boolean;
206
840
  /**
207
- * Returns true if the entry corresponds to an external function (`stdlib` or
208
- * `third-party`) that's never directly called by `ours` code.
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.
209
843
  *
210
844
  * These entries are typically implementation details of external code that your
211
845
  * own code cannot directly call. Excluding these entries from the Markdown
212
- * leaves only your code and the public API surface of stdlib and third-pary
213
- * code.
846
+ * leaves only your code and the public API surface of `stdlib` and
847
+ * `third-party` code.
214
848
  */
215
- declare const isExternalPrivateEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
849
+ declare const isExternalImplementationDetailEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
216
850
  //#endregion
217
- //#region src/formats/jsc-heap-snapshot/index.d.ts
851
+ //#region src/formats/index.d.ts
218
852
  /**
219
- * Converts the given JSC heap snapshot to Markdown.
853
+ * Converts the given profile data to Markdown.
220
854
  *
221
- * It is assumed that {@link data} is a valid snapshot. The behavior of this
222
- * function is undefined for invalid snapshots.
223
- *
224
- * See the [JSC heap snapshot docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/jsc-heap-snapshot.md)
225
- * for supported runtimes and generation instructions
226
- * (`profiler-md --help jsc-heap-snapshot`).
855
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
856
+ * for supported formats and generation instructions.
227
857
  */
228
- declare const jscHeapSnapshotToMd: (data: JsonProfileData, options?: ProfileToMdOptions) => string;
858
+ declare const profileToMd: (input: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
229
859
  /**
230
- * Asynchronously converts the given JSC heap snapshot to Markdown.
231
- *
232
- * It is assumed that {@link data} is a valid snapshot. The behavior of this
233
- * function is undefined for invalid snapshots.
860
+ * Asynchronously converts the given profile data to Markdown.
234
861
  *
235
- * See the [JSC heap snapshot docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/jsc-heap-snapshot.md)
236
- * for supported runtimes and generation instructions
237
- * (`profiler-md --help jsc-heap-snapshot`).
862
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
863
+ * for supported formats and generation instructions.
238
864
  */
239
- declare const jscHeapSnapshotToMdAsync: (data: AsyncProfileData, options?: ProfileToMdOptions) => Promise<string>;
240
- //#endregion
241
- //#region src/formats/pprof/index.d.ts
242
- /**
243
- * Converts the given pprof to Markdown.
244
- *
245
- * It is assumed that {@link data} is a valid pprof (raw protobuf). The behavior
246
- * of this function is undefined for invalid profiles.
247
- *
248
- * See the [pprof docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/pprof.md)
249
- * for supported tools and generation instructions (`profiler-md --help pprof`).
250
- */
251
- declare const pprofToMd: (data: BinaryProfileData, options?: ProfileToMdOptions) => string;
252
- /**
253
- * Asynchronously converts the given pprof to Markdown.
254
- *
255
- * It is assumed that {@link data} is a valid pprof (raw protobuf). The behavior
256
- * of this function is undefined for invalid profiles.
257
- *
258
- * See the [pprof docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/pprof.md)
259
- * for supported tools and generation instructions (`profiler-md --help pprof`).
260
- */
261
- declare const pprofToMdAsync: (data: AsyncProfileData, options?: ProfileToMdOptions) => Promise<string>;
262
- //#endregion
263
- //#region src/formats/speedscope/index.d.ts
264
- /**
265
- * Converts the given Speedscope profile to Markdown.
266
- *
267
- * It is assumed that {@link data} is a valid Speedscope JSON file. The behavior
268
- * of this function is undefined for invalid profiles.
269
- *
270
- * See the [Speedscope docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/speedscope.md)
271
- * for supported tools and generation instructions
272
- * (`profiler-md --help speedscope`).
273
- */
274
- declare const speedscopeProfileToMd: (data: JsonProfileData, options?: ProfileToMdOptions) => string;
275
- /**
276
- * Asynchronously converts the given Speedscope profile to Markdown.
277
- *
278
- * It is assumed that {@link data} is a valid Speedscope JSON file. The behavior
279
- * of this function is undefined for invalid profiles.
280
- *
281
- * See the [Speedscope docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/speedscope.md)
282
- * for supported tools and generation instructions
283
- * (`profiler-md --help speedscope`).
284
- */
285
- declare const speedscopeProfileToMdAsync: (data: AsyncProfileData, options?: ProfileToMdOptions) => Promise<string>;
286
- //#endregion
287
- //#region src/formats/v8/cpu-profile/index.d.ts
288
- /**
289
- * Converts the given V8 CPU profile to Markdown.
290
- *
291
- * It is assumed that {@link data} is a valid profile. The behavior of this
292
- * function is undefined for invalid profiles.
293
- *
294
- * See the [V8 CPU profile docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/v8-cpu-profile.md)
295
- * for supported runtimes and generation instructions
296
- * (`profiler-md --help v8-cpu-profile`).
297
- */
298
- declare const v8CpuProfileToMd: (data: JsonProfileData, options?: ProfileToMdOptions) => string;
299
- /**
300
- * Asynchronously converts the given V8 CPU profile to Markdown.
301
- *
302
- * It is assumed that {@link data} is a valid profile. The behavior of this
303
- * function is undefined for invalid profiles.
304
- *
305
- * See the [V8 CPU profile docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/v8-cpu-profile.md)
306
- * for supported runtimes and generation instructions
307
- * (`profiler-md --help v8-cpu-profile`).
308
- */
309
- declare const v8CpuProfileToMdAsync: (data: AsyncProfileData, options?: ProfileToMdOptions) => Promise<string>;
310
- //#endregion
311
- //#region src/formats/v8/heap-profile/index.d.ts
312
- /**
313
- * Converts the given V8 sampling heap profile to Markdown.
314
- *
315
- * It is assumed that {@link data} is a valid profile. The behavior of this
316
- * function is undefined for invalid profiles.
317
- *
318
- * See the [V8 heap profile docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/v8-heap-profile.md)
319
- * for supported runtimes and generation instructions
320
- * (`profiler-md --help v8-heap-profile`).
321
- */
322
- declare const v8HeapProfileToMd: (data: JsonProfileData, options?: ProfileToMdOptions) => string;
323
- /**
324
- * Asynchronously converts the given V8 sampling heap profile to Markdown.
325
- *
326
- * It is assumed that {@link data} is a valid profile. The behavior of this
327
- * function is undefined for invalid profiles.
328
- *
329
- * See the [V8 heap profile docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/v8-heap-profile.md)
330
- * for supported runtimes and generation instructions
331
- * (`profiler-md --help v8-heap-profile`).
332
- */
333
- declare const v8HeapProfileToMdAsync: (data: AsyncProfileData, options?: ProfileToMdOptions) => Promise<string>;
334
- //#endregion
335
- //#region src/formats/v8/heap-snapshot/index.d.ts
336
- /**
337
- * Converts the given V8 heap snapshot to Markdown.
338
- *
339
- * It is assumed that {@link data} is a valid snapshot. The behavior of this
340
- * function is undefined for invalid snapshots.
341
- *
342
- * See the [V8 heap snapshot docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/v8-heap-snapshot.md)
343
- * for supported runtimes and generation instructions
344
- * (`profiler-md --help v8-heap-snapshot`).
345
- */
346
- declare const v8HeapSnapshotToMd: (data: JsonProfileData, options?: ProfileToMdOptions) => string;
347
- /**
348
- * Asynchronously converts the given V8 heap snapshot to Markdown.
349
- *
350
- * It is assumed that {@link data} is a valid snapshot. The behavior of this
351
- * function is undefined for invalid snapshots.
352
- *
353
- * See the [V8 heap snapshot docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/v8-heap-snapshot.md)
354
- * for supported runtimes and generation instructions
355
- * (`profiler-md --help v8-heap-snapshot`).
356
- */
357
- declare const v8HeapSnapshotToMdAsync: (data: AsyncProfileData, options?: ProfileToMdOptions) => Promise<string>;
358
- //#endregion
359
- //#region src/formats/webkit-timeline-recording/index.d.ts
865
+ declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
360
866
  /**
361
- * Converts the given WebKit timeline recording to Markdown.
867
+ * Diffs the given base and current profile data, returning the difference as
868
+ * Markdown.
362
869
  *
363
- * It is assumed that {@link data} is a valid recording. The behavior of this
364
- * function is undefined for invalid recordings.
870
+ * Each side accepts the same input as {@link profileToMd}.
365
871
  *
366
- * See the [WebKit timeline recording docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/webkit-timeline-recording.md)
367
- * for generation instructions (`profiler-md --help webkit-timeline-recording`).
872
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
873
+ * for supported formats and generation instructions.
368
874
  */
369
- declare const webkitTimelineRecordingToMd: (data: JsonProfileData, options?: ProfileToMdOptions) => string;
875
+ declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
370
876
  /**
371
- * Asynchronously converts the given WebKit timeline recording to Markdown.
877
+ * Asynchronously diffs the given base and current profile data, returning the
878
+ * difference as Markdown.
372
879
  *
373
- * It is assumed that {@link data} is a valid recording. The behavior of this
374
- * function is undefined for invalid recordings.
880
+ * Each side accepts the same input as {@link profileToMdAsync}.
375
881
  *
376
- * See the [WebKit timeline recording docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/webkit-timeline-recording.md)
377
- * for generation instructions (`profiler-md --help webkit-timeline-recording`).
882
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
883
+ * for supported formats and generation instructions.
378
884
  */
379
- declare const webkitTimelineRecordingToMdAsync: (data: AsyncProfileData, options?: ProfileToMdOptions) => Promise<string>;
885
+ 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];
380
889
  //#endregion
381
- export { type AggregatedProfileEntry, type AsyncProfileData, type BinaryProfileData, type EntryOrigin, type JsonProfileData, type ProfileEntry, type ProfileToMdOptions, type SourceMap, defaultCategorizeEntry, defaultShowEntry, isExternalPrivateEntry, isSyntheticEntry, jscHeapSnapshotToMd, jscHeapSnapshotToMdAsync, pprofToMd, pprofToMdAsync, speedscopeProfileToMd, speedscopeProfileToMdAsync, v8CpuProfileToMd, v8CpuProfileToMdAsync, v8HeapProfileToMd, v8HeapProfileToMdAsync, v8HeapSnapshotToMd, v8HeapSnapshotToMdAsync, webkitTimelineRecordingToMd, webkitTimelineRecordingToMdAsync };
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 };