profiler-md 0.3.0 → 0.4.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 (38) hide show
  1. package/dist/cli/index.mjs +2607 -1927
  2. package/dist/index.d.mts +157 -219
  3. package/dist/index.js +2 -2
  4. package/docs/formats/collapsed.md +12 -0
  5. package/docs/languages/cpp.md +136 -0
  6. package/docs/languages/csharp.md +49 -0
  7. package/docs/languages/elixir.md +42 -0
  8. package/docs/languages/erlang.md +42 -0
  9. package/docs/languages/fsharp.md +49 -0
  10. package/docs/languages/java.md +10 -7
  11. package/docs/languages/javascript.md +35 -0
  12. package/docs/languages/julia.md +42 -0
  13. package/docs/languages/kotlin.md +120 -0
  14. package/docs/languages/python.md +10 -4
  15. package/docs/languages/typescript.md +254 -0
  16. package/examples/bun.cpuprofile.md +33 -33
  17. package/examples/deno.cpuprofile.md +9 -9
  18. package/examples/jsc-heap-snapshot.base.json.md +507 -0
  19. package/examples/jsc-heap-snapshot.current.json.md +504 -0
  20. package/examples/jsc-heap-snapshot.diff.json.md +119 -0
  21. package/examples/node.base.cpuprofile.md +451 -0
  22. package/examples/node.current.cpuprofile.md +449 -0
  23. package/examples/node.diff.cpuprofile.md +82 -0
  24. package/examples/node.heapprofile.md +33 -33
  25. package/examples/node.heapsnapshot.md +46 -46
  26. package/examples/node.pprof.md +3 -3
  27. package/examples/python.base.collapsed.md +116 -0
  28. package/examples/python.current.collapsed.md +125 -0
  29. package/examples/python.diff.collapsed.md +51 -0
  30. package/examples/{rust.pprof.md → rust.base.pprof.md} +199 -199
  31. package/examples/rust.current.pprof.md +480 -0
  32. package/examples/rust.diff.pprof.md +117 -0
  33. package/examples/webkit-timeline-recording.json.md +296 -296
  34. package/package.json +21 -18
  35. package/readme.md +106 -80
  36. package/examples/jsc-heap-snapshot.json.md +0 -509
  37. package/examples/node.cpuprofile.md +0 -485
  38. package/examples/node.speedscope.json.md +0 -408
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "profiler-md",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "author": {
5
5
  "name": "Tomer Aberbach",
6
6
  "email": "tomer@aberba.ch",
@@ -34,7 +34,10 @@
34
34
  "v8"
35
35
  ],
36
36
  "homepage": "https://github.com/TomerAberbach/profiler-md",
37
- "repository": "TomerAberbach/profiler-md",
37
+ "repository": {
38
+ "type": "git",
39
+ "url": "TomerAberbach/profiler-md"
40
+ },
38
41
  "bugs": {
39
42
  "url": "https://github.com/TomerAberbach/profiler-md/issues"
40
43
  },
@@ -64,13 +67,13 @@
64
67
  },
65
68
  "prettier": "@tomer/prettier-config",
66
69
  "dependencies": {
67
- "@optique/core": "^1.0.2",
68
- "@optique/run": "^1.0.2",
69
- "@shikijs/core": "^4.0.2",
70
- "@shikijs/engine-oniguruma": "^4.0.2",
71
- "@shikijs/langs": "^4.0.2",
72
- "@shikijs/themes": "^4.0.2",
73
- "ansis": "^4.3.0",
70
+ "@optique/core": "^1.1.0",
71
+ "@optique/run": "^1.1.0",
72
+ "@shikijs/core": "^4.2.0",
73
+ "@shikijs/engine-oniguruma": "^4.2.0",
74
+ "@shikijs/langs": "^4.2.0",
75
+ "@shikijs/themes": "^4.2.0",
76
+ "ansis": "^4.3.1",
74
77
  "convert-source-map": "^2.0.0",
75
78
  "globals": "^17.6.0",
76
79
  "jumbo-json": "^0.2.0",
@@ -82,27 +85,27 @@
82
85
  "source-map-js": "^1.2.1"
83
86
  },
84
87
  "devDependencies": {
85
- "@fast-check/vitest": "^0.4.0",
88
+ "@fast-check/vitest": "^0.4.1",
86
89
  "@rollup/plugin-terser": "^1.0.0",
87
- "@tomer/eslint-config": "^5.0.0",
90
+ "@tomer/eslint-config": "^5.1.1",
88
91
  "@tomer/prettier-config": "^4.0.1",
89
92
  "@types/convert-source-map": "^2.0.3",
90
93
  "@types/mdast": "^4.0.4",
91
94
  "@types/picomatch": "^4.0.3",
92
- "@vitest/coverage-v8": "^4.1.5",
95
+ "@vitest/coverage-v8": "^4.1.9",
93
96
  "dedent": "^1.7.2",
94
97
  "diff": "^9.0.0",
95
- "eslint": "^10.2.1",
96
- "jsdom": "^29.0.2",
98
+ "eslint": "^10.5.0",
99
+ "jsdom": "^29.1.1",
97
100
  "mdast-util-from-markdown": "^2.0.3",
98
101
  "mdast-util-gfm": "^3.1.0",
99
102
  "micromark-extension-gfm": "^3.0.0",
100
- "prettier": "^3.8.3",
101
- "publint": "^0.3.18",
103
+ "prettier": "^3.8.4",
104
+ "publint": "^0.3.21",
102
105
  "rollup-plugin-tree-shakeable": "^2.0.0",
103
- "tsdown": "^0.21.10",
106
+ "tsdown": "^0.22.2",
104
107
  "typescript": "^6.0.3",
105
- "vitest": "^4.1.5"
108
+ "vitest": "^4.1.9"
106
109
  },
107
110
  "scripts": {
108
111
  "format:base": "prettier --cache --write",
package/readme.md CHANGED
@@ -20,33 +20,49 @@
20
20
 
21
21
  > [!NOTE]
22
22
  >
23
- > This package is in a **beta** state and I'm excited for you to try it out!
23
+ > This package is in **beta** and I'm excited for you to try it!
24
24
  >
25
- > I'd love your feedback! Share any suggestions, bug reports, feature requests,
26
- > or general thoughts by
25
+ > I'd love your feedback! Share suggestions, bug reports, feature requests, or
26
+ > other thoughts by
27
27
  > [filing an issue](https://github.com/TomerAberbach/profiler-md/issues/new).
28
28
 
29
29
  ## Features
30
30
 
31
- - **Polyglot:** supports many formats across many languages
31
+ - **Polyglot:** supports many profile and heap snapshot formats across many
32
+ languages
33
+ - **Diffing:** compare two profiles or two heap snapshots to see what changed
34
+ - **Heap analysis:** reports self and retained size with dominator-based
35
+ retention for heap snapshots
36
+ - **Source maps:** resolves minified and transpiled locations back to original
37
+ sources
38
+ - **Zero config:** auto-detects the format, transparently decompresses
39
+ gzip/brotli, and reads from stdin
40
+ - **Readable in the terminal:** ANSI syntax highlighting with heat-map coloring
41
+ and automatic paging
32
42
  - **Configurable:** control the number of top entries shown, working directory
33
43
  for relative paths, third-party detection, and entry filtering
34
- - **CLI and API:** usable on the command-line or programmatically
44
+ - **CLI and API:** use it from the command line or programmatically
35
45
 
36
46
  ## Languages and formats
37
47
 
48
+ We list a format for a language only if its ecosystem's tools natively generate
49
+ it. Third-party tools can often convert others, though.
50
+
38
51
  <!-- LANGUAGE_MATRIX START -->
39
52
 
40
- | Language | Formats |
41
- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
42
- | [C](docs/languages/c.md)⁠/⁠[C++](docs/languages/cpp.md) | [pprof](docs/formats/pprof.md) |
43
- | [Go](docs/languages/go.md) | [pprof](docs/formats/pprof.md) |
44
- | [Java](docs/languages/java.md)⁠/⁠[Kotlin](docs/languages/kotlin.md) | [pprof](docs/formats/pprof.md)<br>[Speedscope](docs/formats/speedscope.md) |
45
- | [JavaScript](docs/languages/javascript.md)⁠/⁠[TypeScript](docs/languages/typescript.md) | [JSC heap snapshot](docs/formats/jsc-heap-snapshot.md) ([Safari](examples/jsc-heap-snapshot.json.md))<br>[pprof](docs/formats/pprof.md) ([Node.js](examples/node.pprof.md))<br>[Speedscope](docs/formats/speedscope.md) ([Node.js](examples/node.speedscope.json.md))<br>[V8 CPU profile](docs/formats/v8-cpu-profile.md) ([Node.js](examples/node.cpuprofile.md), [Deno](examples/deno.cpuprofile.md), [Bun](examples/bun.cpuprofile.md))<br>[V8 heap profile](docs/formats/v8-heap-profile.md) ([Node.js](examples/node.heapprofile.md))<br>[V8 heap snapshot](docs/formats/v8-heap-snapshot.md) ([Node.js](examples/node.heapsnapshot.md))<br>[WebKit timeline recording](docs/formats/webkit-timeline-recording.md) ([example](examples/webkit-timeline-recording.json.md)) |
46
- | [PHP](docs/languages/php.md) | [Speedscope](docs/formats/speedscope.md) |
47
- | [Python](docs/languages/python.md) | [pprof](docs/formats/pprof.md)<br>[Speedscope](docs/formats/speedscope.md) |
48
- | [Ruby](docs/languages/ruby.md) | [Speedscope](docs/formats/speedscope.md) |
49
- | [Rust](docs/languages/rust.md) | [pprof](docs/formats/pprof.md) ([example](examples/rust.pprof.md))<br>[Speedscope](docs/formats/speedscope.md) |
53
+ | Language | Formats |
54
+ | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
55
+ | [C](docs/languages/c.md)⁠/⁠[C++](docs/languages/cpp.md) | [pprof](docs/formats/pprof.md) |
56
+ | [C#](docs/languages/csharp.md)⁠/⁠[F#](docs/languages/fsharp.md) | [Speedscope](docs/formats/speedscope.md) |
57
+ | [Elixir](docs/languages/elixir.md)⁠/⁠[Erlang](docs/languages/erlang.md) | [Collapsed stacks](docs/formats/collapsed.md) |
58
+ | [Go](docs/languages/go.md) | [pprof](docs/formats/pprof.md) |
59
+ | [Java](docs/languages/java.md)⁠/⁠[Kotlin](docs/languages/kotlin.md) | [Collapsed stacks](docs/formats/collapsed.md)<br>[pprof](docs/formats/pprof.md)<br>[Speedscope](docs/formats/speedscope.md) |
60
+ | [JavaScript](docs/languages/javascript.md)⁠/⁠[TypeScript](docs/languages/typescript.md) | [JSC heap snapshot](docs/formats/jsc-heap-snapshot.md) ([Safari](examples/jsc-heap-snapshot.base.json.md), [Safari diff](examples/jsc-heap-snapshot.diff.json.md))<br>[pprof](docs/formats/pprof.md) ([Node.js](examples/node.pprof.md))<br>[V8 CPU profile](docs/formats/v8-cpu-profile.md) ([Node.js](examples/node.base.cpuprofile.md), [Node.js diff](examples/node.diff.cpuprofile.md), [Deno](examples/deno.cpuprofile.md), [Bun](examples/bun.cpuprofile.md))<br>[V8 heap profile](docs/formats/v8-heap-profile.md) ([Node.js](examples/node.heapprofile.md))<br>[V8 heap snapshot](docs/formats/v8-heap-snapshot.md) ([Node.js](examples/node.heapsnapshot.md))<br>[WebKit timeline recording](docs/formats/webkit-timeline-recording.md) ([example](examples/webkit-timeline-recording.json.md)) |
61
+ | [Julia](docs/languages/julia.md) | [pprof](docs/formats/pprof.md) |
62
+ | [PHP](docs/languages/php.md) | [Speedscope](docs/formats/speedscope.md) |
63
+ | [Python](docs/languages/python.md) | [Collapsed stacks](docs/formats/collapsed.md) ([Tachyon](examples/python.base.collapsed.md), [Tachyon diff](examples/python.diff.collapsed.md))<br>[pprof](docs/formats/pprof.md)<br>[Speedscope](docs/formats/speedscope.md) |
64
+ | [Ruby](docs/languages/ruby.md) | [Speedscope](docs/formats/speedscope.md) |
65
+ | [Rust](docs/languages/rust.md) | [pprof](docs/formats/pprof.md) ([base](examples/rust.base.pprof.md), [diff](examples/rust.diff.pprof.md)) |
50
66
 
51
67
  <!-- LANGUAGE_MATRIX END -->
52
68
 
@@ -67,8 +83,9 @@ $ npm i -g profiler-md
67
83
  ```sh
68
84
  $ profiler-md --help
69
85
  Usage: profiler-md [(-h/--help [TOPIC])] [-f/--format FORMAT] [-o/--output FILE]
70
- [--top-n N] [--cwd PATH] [--third-party GLOB...] [--source-maps GLOB...]
71
- [--no-pager] [(--color | --no-color)] [FILE]
86
+ [--top-n N] [--base-url STRING] [--source-maps GLOB...] [--match
87
+ REGEX=REPLACEMENT...] [--third-party GLOB...] [--no-pager] [(--color |
88
+ --no-color)] ([FILE] | BASE CURRENT)
72
89
 
73
90
  Converts performance profiles to human and LLM friendly Markdown.
74
91
 
@@ -76,20 +93,25 @@ Converts performance profiles to human and LLM friendly Markdown.
76
93
  -f, --format FORMAT Input profile format (default: auto)
77
94
  -o, --output FILE Output file (default: - for stdout)
78
95
  --top-n N Number of top entries to show (default: 20)
79
- --cwd PATH Directory to show paths relative to (default: cwd)
80
- --third-party GLOB Additional URLs to consider third-party
81
- (repeatable)
96
+ --base-url STRING Base URL or path to show paths relative to
97
+ (default: cwd)
82
98
  --source-maps GLOB Source maps (JSON or inline) to apply to profile
83
99
  locations (repeatable)
100
+ --match REGEX=REPLACEMENT Treat locations matching REGEX as REPLACEMENT
101
+ when matching entries across diffed profiles
102
+ (repeatable)
103
+ --third-party GLOB Additional URLs or paths to consider third-party
104
+ (repeatable)
84
105
  --no-pager Disable stdout output paging (default: auto)
85
106
  --color Enable or disable ANSI syntax highlighting
86
107
  (default: auto)
87
108
  --no-color
88
- FILE Profile file to convert (reads from stdin if
89
- omitted)
109
+ FILE Profile to convert (reads from stdin if omitted)
110
+ BASE Base profile to diff
111
+ CURRENT Current profile to diff against the base
90
112
 
91
- Formats: jsc-heap-snapshot, pprof, speedscope, v8-cpu-profile, v8-heap-profile, v8-heap-snapshot, webkit-timeline-recording
92
- Languages: c, cpp, go, java, kotlin, javascript, typescript, php, python, ruby, rust
113
+ Formats: collapsed, jsc-heap-snapshot, pprof, speedscope, v8-cpu-profile, v8-heap-profile, v8-heap-snapshot, webkit-timeline-recording
114
+ Languages: c, cpp, csharp, fsharp, elixir, erlang, go, java, kotlin, javascript, typescript, julia, php, python, ruby, rust
93
115
  ```
94
116
 
95
117
  <!-- CLI_HELP END -->
@@ -99,39 +121,57 @@ Languages: c, cpp, go, java, kotlin, javascript, typescript, php, python, ruby,
99
121
  ### API
100
122
 
101
123
  ```js
102
- import { openAsBlob } from 'node:fs'
124
+ import { openAsBlob, readFileSync } from 'node:fs'
103
125
  import {
104
126
  defaultCategorizeEntry,
127
+ defaultMatchEntry,
105
128
  defaultShowEntry,
106
- pprofToMd,
107
- pprofToMdAsync,
108
- speedscopeProfileToMd,
109
- speedscopeProfileToMdAsync,
110
- v8CpuProfileToMd,
111
- v8CpuProfileToMdAsync,
112
- v8HeapProfileToMd,
113
- v8HeapProfileToMdAsync,
114
- v8HeapSnapshotToMd,
115
- v8HeapSnapshotToMdAsync,
116
- webkitTimelineRecordingToMd,
117
- webkitTimelineRecordingToMdAsync,
129
+ diffProfiles,
130
+ diffProfilesAsync,
131
+ profileToMd,
132
+ profileToMdAsync,
118
133
  } from 'profiler-md'
119
134
 
120
- // Basic usage
121
- console.log(await pprofToMdAsync(await openAsBlob(`example.pprof`)))
135
+ // Auto-detect format (async)
136
+ console.log(await profileToMdAsync(await openAsBlob(`example.cpuprofile`)))
137
+ console.log(await profileToMdAsync(await openAsBlob(`example.pprof`)))
138
+
139
+ // Explicit format
122
140
  console.log(
123
- await speedscopeProfileToMdAsync(await openAsBlob(`example.speedscope.json`)),
141
+ await profileToMdAsync({
142
+ data: await openAsBlob(`example.pprof`),
143
+ format: `pprof`,
144
+ }),
124
145
  )
125
- console.log(await v8CpuProfileToMdAsync(await openAsBlob(`example.cpuprofile`)))
146
+
147
+ // Synchronous usage (auto-detect)
148
+ console.log(profileToMd(readFileSync(`example.cpuprofile`, `utf8`)))
149
+ console.log(profileToMd(readFileSync(`example.pprof`)))
150
+
151
+ // Synchronous usage with explicit format
126
152
  console.log(
127
- await v8HeapProfileToMdAsync(await openAsBlob(`example.heapprofile`)),
153
+ profileToMd({ data: readFileSync(`example.pprof`), format: `pprof` }),
128
154
  )
155
+
156
+ // Diff two profiles or two heap snapshots (async, auto-detect)
129
157
  console.log(
130
- await v8HeapSnapshotToMdAsync(await openAsBlob(`example.heapsnapshot`)),
158
+ await diffProfilesAsync(
159
+ await openAsBlob(`base.cpuprofile`),
160
+ await openAsBlob(`current.cpuprofile`),
161
+ ),
131
162
  )
132
163
  console.log(
133
- await webkitTimelineRecordingToMdAsync(
134
- await openAsBlob(`example.webkit-timeline-recording.json`),
164
+ await diffProfilesAsync(
165
+ await openAsBlob(`base.heapsnapshot`),
166
+ await openAsBlob(`current.heapsnapshot`),
167
+ ),
168
+ )
169
+
170
+ // Synchronous diff with explicit format
171
+ console.log(
172
+ diffProfiles(
173
+ { data: readFileSync(`base.pprof`), format: `pprof` },
174
+ { data: readFileSync(`current.pprof`), format: `pprof` },
135
175
  ),
136
176
  )
137
177
 
@@ -139,8 +179,16 @@ console.log(
139
179
  const options = {
140
180
  // Show top 10 functions instead of the default 20.
141
181
  topN: 10,
142
- // Make paths relative to a custom directory.
143
- cwd: `/path/to/project`,
182
+ // Make paths relative to a custom base URL or directory.
183
+ baseURL: `/path/to/project`,
184
+ matchEntry: entry => {
185
+ if (entry.location?.url.pathname.includes(`/bundle.`)) {
186
+ // Match bundled entries when diffing by name only, ignoring
187
+ // content-hashed filenames.
188
+ return { name: entry.name }
189
+ }
190
+ return defaultMatchEntry(entry)
191
+ },
144
192
  categorizeEntry: entry => {
145
193
  if (entry.location?.url.pathname.includes(`/vendor/`)) {
146
194
  // Treat an additional vendor directory as third-party.
@@ -153,42 +201,20 @@ const options = {
153
201
  // Exclude entries from a specific file.
154
202
  !entry.location?.includes(`/path/to/project/src/noisy`),
155
203
  }
156
- console.log(await pprofToMdAsync(await openAsBlob(`example.pprof`), options))
204
+ console.log(await profileToMdAsync(await openAsBlob(`example.pprof`), options))
157
205
  console.log(
158
- await speedscopeProfileToMdAsync(
159
- await openAsBlob(`example.speedscope.json`),
160
- options,
161
- ),
162
- )
163
- console.log(
164
- await v8CpuProfileToMdAsync(await openAsBlob(`example.cpuprofile`), options),
165
- )
166
- console.log(
167
- await v8HeapProfileToMdAsync(
168
- await openAsBlob(`example.heapprofile`),
169
- options,
170
- ),
171
- )
172
- console.log(
173
- await v8HeapSnapshotToMdAsync(
174
- await openAsBlob(`example.heapsnapshot`),
175
- options,
176
- ),
206
+ await profileToMdAsync(await openAsBlob(`example.cpuprofile`), options),
177
207
  )
208
+
209
+ // The same options also apply to diffs. `matchEntry` only takes effect here,
210
+ // where it controls which entries are considered the same across the two sides.
178
211
  console.log(
179
- await webkitTimelineRecordingToMdAsync(
180
- await openAsBlob(`example.webkit-timeline-recording.json`),
212
+ await diffProfilesAsync(
213
+ await openAsBlob(`base.pprof`),
214
+ await openAsBlob(`current.pprof`),
181
215
  options,
182
216
  ),
183
217
  )
184
-
185
- // Synchronous usage
186
- console.log(pprofToMd(pprofData))
187
- console.log(speedscopeProfileToMd(speedscopeProfileData))
188
- console.log(v8CpuProfileToMd(v8CpuProfileData))
189
- console.log(v8HeapProfileToMd(v8HeapProfileData))
190
- console.log(v8HeapSnapshotToMd(v8HeapSnapshotData))
191
- console.log(webkitTimelineRecordingToMd(webkitTimelineRecordingData))
192
218
  ```
193
219
 
194
220
  ## Shell completions
@@ -212,7 +238,8 @@ $ profiler-md --completion pwsh >> $PROFILE.CurrentUserCurrentHost
212
238
 
213
239
  ## Skills
214
240
 
215
- Use this `profiler-md` skill to have an agent profile and optimize your code:
241
+ Use the [`profiler-md` skill](./skills/profile-optimize/SKILL.md) to have an
242
+ agent profile and optimize your code:
216
243
 
217
244
  ```sh
218
245
  $ npx skills add TomerAberbach/profiler-md --skill profile-optimize
@@ -220,8 +247,7 @@ $ npx skills add TomerAberbach/profiler-md --skill profile-optimize
220
247
 
221
248
  See [skills.sh](https://skills.sh/docs) for more info.
222
249
 
223
- Fun fact: the skill has been used to profile and optimize `profiler-md` using
224
- itself!
250
+ Fun fact: the skill has profiled and optimized `profiler-md` itself!
225
251
 
226
252
  ## Contributing
227
253