Node Perf Flamegraph Summarizer

What this skill does

Parses a Node.js flamegraph artifact (flame.html from clinic flame or the JSON from 0x --output-dir) and produces a short report that names the three hottest functions, their stack context, and a concrete fix suggestion per hotspot.

Inputs

• flame_artifact: path to flame.html (clinic) or the directory output by 0x.
• repo_dir: source root used to resolve stack frames to files.
• Optional min_self_pct: minimum self-time percentage to surface (default 2).

Steps

1. Detect format: clinic flame.html embeds a <script id="trace"> JSON blob; 0x emits <id>.0x/flamegraph.html plus stacks.<id>.txt.
2. For clinic, extract the JSON with node -e "const fs=require('fs'); const html=fs.readFileSync('<flame_artifact>','utf8'); const m=html.match(/<script id=\"trace\">([\s\S]*?)<\/script>/); console.log(m[1])".
3. For 0x, parse stacks.*.txt: each line is a folded stack frame1;frame2;... <samples>.
4. Compute self-time per leaf: sum samples where the leaf is the topmost frame.
5. Compute total-time per function: sum samples where the function appears anywhere in the stack.
6. Sort by self-time descending; pick top 3 above min_self_pct.
7. For each hotspot, resolve the source: stack frames look like <fn> /abs/path:line:col. Use awk or node regex to extract the file:line.
8. Read 20 lines around the hotspot from the source. Tag the suggestion family: hot loop -> precompute or memoize; sync I/O -> async API; JSON.parse on hot path -> streaming or schema-less alt; regex -> precompile.
9. Emit a markdown report with three numbered sections, each with a fenced source snippet and the suggested fix.

Output

A markdown report flame-summary.md with a header table (total samples, sample interval, top-3 self %) and three hotspot sections. Each section cites file:line and includes one paragraph of fix rationale.

Verification

Re-parse the artifact and recompute the top-3 self-time list; the report's order must match. Open the cited file:line for each hotspot and confirm the function name in the report matches the source token at that line. If samples are below 1000 total, prepend a warning to the report — short profiles are statistically noisy and rankings should be treated as advisory.

Edge cases

• Anonymous functions in stack: use the parent function plus offset (<anonymous>:line is acceptable).
• Native frames (V8, libuv) dominating self time: report them but mark as "out-of-userspace" with no fix suggestion.
• Source maps: if frames point at bundled code (e.g., dist/bundle.js:1:12345), apply the source map via source-map package before reporting.
• Empty profile (zero samples): exit early with "no profile data" — do not invent hotspots.