Cpu Profile Analysis

# Analyze Performance Profiles

Analyze `.cpuprofile` files (V8 sampling profiler) and DevTools trace files (`Trace-*.json`, Chrome Trace Event Format) to find performance bottlenecks, compare code paths, and understand timing.

## When to Use
- User provides a `.cpuprofile` or `Trace-*.json` file and wants to understand performance
- Investigating why one code path is slower than another
- Finding what functions consume the most time
- Comparing "before/after" or "old/new" implementations in a single profile
- Investigating layout thrashing, long tasks, or rendering bottlenecks (trace files)
- Analyzing VS Code user timing marks like `code/didResolveTextFileEditorModel` (trace files)
- Understanding multi-process behavior (Browser, Renderer, GPU processes in trace files)

## Detecting File Type

- **`.cpuprofile`**: Top-level JSON with `nodes`, `samples`, `timeDeltas` keys. Created by the VS Code profiler.
- **`Trace-*.json`**: Top-level JSON with `traceEvents` array (and optional `metadata`). Created by Chrome/Electron DevTools (Performance tab). These are richer than `.cpuprofile` -- they contain CPU samples, layout/paint events, user timing marks, GC events, input events, and multi-process data.

## Key Concepts

- **Sampling profiler**: The profiler periodically snapshots the call stack. Not every function appears -- only those on the stack when the profiler sampled. Don't expect exact function names; look for patterns and nearby activity.
- **Self time**: Time spent in the function itself (the leaf/innermost frame).
- **Total time**: Time the function was anywhere on the stack (includes callees).
- **Idle samples**: Frames labeled `(idle)`, `(program)`, or `(garbage collector)` represent no user code running.

---

## Part 1: `.cpuprofile` Files

### Profile Format

A `.cpuprofile` is JSON with these top-level keys:
- `nodes`: Array of call frame nodes forming a tree (each has `id`, `callFrame`, `children`)
- `samples`: Array of node IDs -- one per profiler tick, referencing the leaf (innermost) frame
- `timeDeltas`: Array of microsecond deltas between consecutive samples
- `startTime` / `endTime`: Absolute timestamps in microseconds
- `$vscode`: Optional VS Code metadata

### Procedure

### 1. Check File Size and Parse

Profile and trace files can exceed V8's string limit (~512MB). Always check the file size first and choose the right parsing strategy:

```javascript
import { readFileSync, statSync } from 'fs';

const stat = statSync(profilePath);
const sizeMB = stat.size / (1024 * 1024);
console.log(`File size: ${sizeMB.toFixed(0)}MB`);

let data;
if (sizeMB < 400) {
    // Small enough for JSON.parse
    data = JSON.parse(readFileSync(profilePath, 'utf8'));
} else {
    // Too large -- use Buffer-based extraction (see "Handling Huge Files" section)
    data = parseProfileFromBuffer(readFileSync(profilePath));
}
```

For files under ~400MB, `JSON.parse(readFileSync(..., 'utf8'))` works fine. For larger files, see the **Handling Huge Files** section below.

### 2. Reformat the File (small files only)

Profiles are often single-line JSON. Reformat for inspection (only if small enough):

```javascript
if (sizeMB < 400) {
    const data = JSON.parse(fs.readFileSync(profilePath, 'utf8'));
    fs.writeFileSync(profilePath, JSON.stringify(data, null, 2));
}
```

### 3. Build Data Structures

Write a Node.js analysis script. Build these structures:

```javascript
// Node lookup
const nodeMap = new Map();       // id -> node
const parentMap = new Map();     // id -> parent id

// Absolute timestamps from deltas
const timestamps = [data.startTime]