@elliemae/encw-heap-doctor 26.2.1

package/README.md

@@ -0,0 +1,371 @@
+# heap-doctor
+
+Analyzes Chrome V8 heap snapshots to help developers find and fix memory leaks in web applications. It parses `.heapsnapshot` files, groups leaked objects by type, walks retainer paths to identify the root JS reference holding objects in memory, matches known leak patterns, and generates prioritized fix suggestions — plus a ready-to-use AI prompt you can send to any LLM of your choice.
+
+## Key Features
+
+- **Parses multi-GB heap snapshots** using off-heap typed arrays (handles files up to 8 GB)
+- **Detects common leak types** — detached DOM nodes, large closures, stale cache references
+- **Traces retainer chains** to the exact JS reference preventing garbage collection
+- **Pattern matching** for known leak causes (GTM data layer, AngularJS scope/watchers, React fiber trees, event listeners, timers, observers)
+- **Snapshot comparison** — diff two snapshots to find growth in leaked objects
+- **Scenario runner** — automate browser flows with Playwright to capture and compare snapshots
+- **Fix priority ranking** across leak groups sharing the same root cause
+- **AI prompt generation** — `generateAiPrompt()` produces a self-contained prompt from the analysis report that you can send to any LLM (Claude, GPT-4, Gemini, etc.)
+- **Markdown reports** as the sole output format — clean, shareable, version-controllable
+
+## Architecture
+
+HeapDoctor exposes a single public class that composes all internal services. Three methods cover every use case: analyse a single snapshot, compare two snapshots, or run an automated browser scenario.
+
+```mermaid
+flowchart TD
+    subgraph publicAPI [HeapDoctor Public API]
+        analyse["analyse(filePath)"]
+        compare["compare(before, after)"]
+        runScenario["runScenario(scenario)"]
+    end
+
+    subgraph core [Core]
+        SnapshotParser["SnapshotParser"]
+        Snapshot["Snapshot"]
+    end
+
+    subgraph analysis [Analysis]
+        LeakDetector["LeakDetector"]
+        RetainerTracer["RetainerTracer"]
+        PatternMatcher["PatternMatcher"]
+        SuggestionGenerator["SuggestionGenerator"]
+        SnapshotComparer["SnapshotComparer"]
+    end
+
+    subgraph scenario [Scenario]
+        PlaywrightRunner["PlaywrightScenarioRunner"]
+        Playwright["Playwright Page"]
+    end
+
+    subgraph prompts [AI Prompt]
+        PromptGenerator["generateAiPrompt()"]
+        Consumer["Your LLM (Claude / GPT-4 / Gemini)"]
+    end
+
+    subgraph reporting [Reporting]
+        MarkdownGen["MarkdownReportGenerator"]
+    end
+
+    analyse --> SnapshotParser
+    SnapshotParser --> Snapshot
+    Snapshot --> LeakDetector
+    LeakDetector --> RetainerTracer
+    RetainerTracer --> PatternMatcher
+    PatternMatcher --> SuggestionGenerator
+    SuggestionGenerator --> MarkdownGen
+    SuggestionGenerator --> PromptGenerator
+    PromptGenerator --> Consumer
+
+    compare --> SnapshotParser
+    compare --> SnapshotComparer
+    SnapshotComparer --> LeakDetector
+
+    runScenario --> PlaywrightRunner
+    PlaywrightRunner --> Playwright
+    PlaywrightRunner --> compare
+```
+
+### Analysis Pipeline
+
+| Stage         | Class                      | What it does                                                                                |
+| ------------- | -------------------------- | ------------------------------------------------------------------------------------------- |
+| **Parse**     | `SnapshotParser`           | Reads `.heapsnapshot` as raw Buffer into off-heap typed arrays for multi-GB files           |
+| **Detect**    | `LeakDetector`             | Finds detached DOM, large closures, large arrays; groups by tag, ranks by retained size     |
+| **Trace**     | `RetainerTracer`           | Walks retainer edges via priority BFS to build JS-level chains to GC roots                  |
+| **Match**     | `PatternMatcher`           | Matches chains against known leak patterns (GTM, AngularJS, React, event listeners, timers) |
+| **Suggest**   | `SuggestionGenerator`      | Generates severity-ranked fix suggestions from patterns and chain context                   |
+| **Compare**   | `SnapshotComparer`         | Diffs two snapshots: new/removed nodes, retained size delta, new leak groups                |
+| **Scenario**  | `PlaywrightScenarioRunner` | Runs a Playwright browser scenario, captures before/after heap snapshots via CDP            |
+| **Report**    | `MarkdownReportGenerator`  | Renders structured results as a markdown report                                             |
+| **AI Prompt** | `generateAiPrompt()`       | Serializes all findings into a self-contained prompt for any LLM                            |
+
+### File Structure
+
+```
+lib/
+  index.ts                          Re-exports HeapDoctor and public types
+  heapDoctor.ts                     Public HeapDoctor facade class
+  types/
+    index.ts                        Result<T>, branded IDs, common types
+    report.ts                       AnalysisReport, ComparisonReport, ScenarioReport
+    leak.ts                         LeakGroup, RetainerChain, Suggestion, etc.
+    scenario.ts                     HeapDoctorScenario (uses Playwright Page)
+  errors/
+    domainError.ts                  Base DomainError class
+    parseError.ts                   Snapshot parsing errors
+    scenarioError.ts                Scenario execution errors
+  core/
+    snapshot.ts                     Snapshot class (typed V8 heap representation)
+    snapshotParser.ts               SnapshotParser class (Buffer-based parser)
+  analysis/
+    leakDetector.ts                 LeakDetector (detached DOM, closures, arrays)
+    retainerTracer.ts               RetainerTracer (BFS retainer path walking)
+    patternMatcher.ts               PatternMatcher (known leak pattern detection)
+    suggestionGenerator.ts          SuggestionGenerator (fix generation)
+    snapshotComparer.ts             SnapshotComparer (diff two snapshots)
+  scenario/
+    playwrightScenarioRunner.ts     PlaywrightScenarioRunner (CDP snapshot capture)
+  prompts/
+    promptGenerator.ts              generateAiPrompt() (LLM-ready prompt builder)
+  reporting/
+    markdownReportGenerator.ts      MarkdownReportGenerator (markdown output)
+  utils/
+    formatUtils.ts                  FormatUtils (formatBytes, truncate, escapeHtml)
+bin/
+  heap-doctor.ts                    CLI entry point (composition root)
+```
+
+## Installation
+
+```bash
+npm install @elliemae/encw-heap-doctor
+```
+
+For scenario support (automated browser flows):
+
+```bash
+npm install playwright
+```
+
+## Programmatic API
+
+HeapDoctor is designed as a library-first API. All methods return `Result<T>` for type-safe error handling.
+
+### 1. Single Snapshot Analysis
+
+Analyse a `.heapsnapshot` file for memory leaks:
+
+```typescript
+import { HeapDoctor } from '@elliemae/encw-heap-doctor';
+
+const doctor = new HeapDoctor({ topN: 5 });
+const result = await doctor.analyse('app.heapsnapshot');
+
+if (result.ok) {
+  console.log(result.value.markdown); // full markdown report
+  console.log(result.value.leakResults); // structured leak data
+  console.log(result.value.fixPriority); // ranked fix priorities
+} else {
+  console.error(result.error.code, result.error.message);
+}
+```
+
+### 2. Snapshot Comparison
+
+Compare two snapshots to find what grew between them:
+
+```typescript
+import { HeapDoctor } from '@elliemae/encw-heap-doctor';
+
+const doctor = new HeapDoctor();
+const result = await doctor.compare(
+  'before.heapsnapshot',
+  'after.heapsnapshot',
+);
+
+if (result.ok) {
+  const { delta } = result.value;
+  console.log(`New nodes: +${delta.newNodeCount}`);
+  console.log(`Removed:   -${delta.removedNodeCount}`);
+  console.log(`Size delta: ${delta.retainedSizeDelta} bytes`);
+
+  for (const group of delta.newLeakGroups) {
+    console.log(`New leak: ${group.label} x${group.count}`);
+  }
+
+  // Full markdown comparison report
+  console.log(result.value.markdown);
+}
+```
+
+### 3. Automated Scenario (Playwright)
+
+Define a browser scenario and let HeapDoctor capture + compare snapshots automatically:
+
+```typescript
+import { HeapDoctor } from '@elliemae/encw-heap-doctor';
+import type { HeapDoctorScenario } from '@elliemae/encw-heap-doctor';
+
+const scenario: HeapDoctorScenario = {
+  url() {
+    return 'https://myapp.com';
+  },
+
+  async setup(page) {
+    await page.goto('https://myapp.com/login');
+    await page.getByPlaceholder('Email').fill('user@example.com');
+    await page.getByPlaceholder('Password').fill('password');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+    await page.waitForURL('**/dashboard/**');
+  },
+
+  async action(page) {
+    await page.getByRole('button', { name: 'Open Modal' }).click();
+    await page.waitForSelector('.modal-content');
+  },
+
+  async back(page) {
+    await page.getByRole('button', { name: 'Close' }).click();
+    await page.waitForSelector('.modal-content', { state: 'hidden' });
+  },
+
+  repeat() {
+    return 3; // repeat action->back cycle 3 times
+  },
+};
+
+const doctor = new HeapDoctor();
+const result = await doctor.runScenario(scenario);
+
+if (result.ok) {
+  console.log(`Snapshots: ${result.value.snapshotPaths.join(', ')}`);
+  console.log(result.value.markdown);
+}
+```
+
+The runner captures a "before" snapshot after `setup()`, executes `action()` -> `back()` for `repeat()` cycles, then captures an "after" snapshot. Both are compared and a full report is generated.
+
+### 4. AI Prompt Generation
+
+`generateAiPrompt()` converts any analysis or comparison report into a self-contained prompt string. Paste it into Claude, GPT-4, Gemini, or any LLM — no API keys or registry access required on heap-doctor's side.
+
+```typescript
+import { HeapDoctor, generateAiPrompt } from '@elliemae/encw-heap-doctor';
+
+const doctor = new HeapDoctor({ topN: 5 });
+const result = await doctor.analyse('app.heapsnapshot');
+
+if (result.ok) {
+  const prompt = generateAiPrompt(result.value);
+
+  // Option A: print to stdout and copy-paste into any chat UI
+  console.log(prompt);
+
+  // Option B: write to a file and attach to your LLM of choice
+  writeFileSync('heap-doctor-prompt.txt', prompt);
+
+  // Option C: pass directly to your own AI integration
+  const aiResponse = await myLlmClient.complete(prompt);
+}
+```
+
+Works identically for comparison reports:
+
+```typescript
+const result = await doctor.compare(
+  'before.heapsnapshot',
+  'after.heapsnapshot',
+);
+if (result.ok) {
+  const prompt = generateAiPrompt(result.value);
+  // prompt includes the delta summary (new nodes, size change) as context
+}
+```
+
+The generated prompt includes:
+
+- Full context header instructing the LLM to act as a memory leak specialist
+- Per-leak sections: label, count, retained size, matched pattern, root cause, retainer chains, edge paths, existing suggestions
+- Structured output format requesting `LEAK #N` sections with specific action items
+
+## CLI Usage
+
+```bash
+# Build first
+npm run build
+
+# Analyse a single snapshot
+heap-doctor analyse app.heapsnapshot
+
+# Compare two snapshots
+heap-doctor compare before.heapsnapshot after.heapsnapshot
+
+# Run a scenario file
+heap-doctor scenario my-scenario.ts
+
+# Write report to file instead of stdout
+heap-doctor analyse app.heapsnapshot -o report.md
+```
+
+### CLI Options
+
+| Flag                  | Description                                     | Default |
+| --------------------- | ----------------------------------------------- | ------- |
+| `-n, --top <number>`  | Number of top leak groups to report             | `5`     |
+| `-o, --output <path>` | Write markdown report to file (default: stdout) | stdout  |
+| `-V, --version`       | Print the version number                        | --      |
+| `-h, --help`          | Show help                                       | --      |
+
+### Subcommands
+
+| Command                    | Description                                              |
+| -------------------------- | -------------------------------------------------------- |
+| `analyse <file>`           | Analyse a single heap snapshot                           |
+| `compare <before> <after>` | Compare two heap snapshots                               |
+| `scenario <scenario-file>` | Run a Playwright scenario and compare captured snapshots |
+
+## Headed Mode (Scenario)
+
+To watch the browser during scenario execution:
+
+```bash
+HEADLESS=false npx tsx demo/scenario-run.ts
+```
+
+## Example Report Output
+
+Below is a single leak section from a generated markdown report:
+
+---
+
+### MEMORY LEAK DETECTED
+
+**Node**
+`Detached <span>`
+
+**Retained Memory**
+1370.16 MB
+
+**Retaining Function**
+`gtmDataLayer in Array`
+
+**Leak Pattern**
+Google Tag Manager Data Layer
+
+**Retainer Chain**
+
+```text
+(GC roots)
+└ (Eternal handles)
+   └ 307
+      └ DOMStringMap()
+         └ context
+            └ extension
+               └ gtmDataLayer in Array
+                  └ [42] in Object
+                     └ gtm.element in <button id="header-app-switcher" ...>
+                        └ __reactFiber$kau10t4ajn9 in nd
+                           └ return in nd
+                              └ memoizedState in Object
+                                 └ <span class="em-ds-popover__arrow" ...>
+```
+
+**Suggested Fix**
+
+- Configure GTM to not capture element references in click/form triggers
+- Periodically trim stale entries: `window.dataLayer = window.dataLayer.slice(-50)`
+- Use CSS selectors or element IDs in GTM triggers instead of element references
+- Add cleanup that nullifies `gtm.element` on stale dataLayer entries
+
+---
+
+## License
+
+MIT

package/dist/cjs/analysis/leakDetector.js

@@ -0,0 +1,195 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var leakDetector_exports = {};
+__export(leakDetector_exports, {
+  LeakDetector: () => LeakDetector
+});
+module.exports = __toCommonJS(leakDetector_exports);
+const DOM_TAG_RE = /^<(\w+)/;
+const DETACHED_TAG_RE = /^Detached <(\w+)/;
+const MAX_SINGLE_BFS = 2e5;
+const FOLLOW_TYPES = /* @__PURE__ */ new Set(["native", "hidden"]);
+class LeakDetector {
+  /**
+   * @param snapshot - Parsed heap snapshot to scan.
+   * @param topN - Maximum number of leak groups to return.
+   * @returns Leak groups sorted by retained size, limited to `topN`.
+   */
+  // eslint-disable-next-line max-statements, complexity
+  detect(snapshot, topN = 5) {
+    const nc = snapshot.nodeCount;
+    const explicitlyDetached = [];
+    const domElements = [];
+    for (let i = 0; i < nc; i += 1) {
+      const ni = i;
+      const name = snapshot.nodeName(ni);
+      const type = snapshot.nodeType(ni);
+      const det = snapshot.nodeDetachedness(ni);
+      if (name.startsWith("Detached <") || det > 0 && type === "native") {
+        explicitlyDetached.push(ni);
+        continue;
+      }
+      if (type === "native" && DOM_TAG_RE.test(name)) {
+        domElements.push(ni);
+      }
+    }
+    const attachedNodes = LeakDetector.buildAttachedSet(snapshot);
+    const detachedDomNodes = [...explicitlyDetached];
+    domElements.forEach((ni) => {
+      if (!attachedNodes.has(ni)) {
+        detachedDomNodes.push(ni);
+      }
+    });
+    const tagGroups = /* @__PURE__ */ new Map();
+    detachedDomNodes.forEach((ni) => {
+      const name = snapshot.nodeName(ni);
+      const tag = LeakDetector.extractTag(name) ?? "unknown";
+      if (!tagGroups.has(tag)) {
+        tagGroups.set(tag, {
+          reason: "detached-dom",
+          label: `Detached <${tag}>`,
+          tag,
+          nodeIndices: [],
+          count: 0,
+          totalSelfSize: 0,
+          topElements: [],
+          representativeIndex: ni,
+          retainedSize: 0
+        });
+      }
+      const group = tagGroups.get(tag);
+      group.nodeIndices.push(ni);
+      group.count += 1;
+      group.totalSelfSize += snapshot.nodeSelfSize(ni);
+    });
+    const visited = new Uint8Array(nc);
+    const domGroups = [...tagGroups.values()];
+    domGroups.forEach((group) => {
+      LeakDetector.rankGroupElements(group, snapshot, visited);
+    });
+    domGroups.sort((a, b) => b.retainedSize - a.retainedSize);
+    return domGroups.slice(0, topN);
+  }
+  static extractTag(name) {
+    const m = name.match(DETACHED_TAG_RE) ?? name.match(DOM_TAG_RE);
+    return m ? m[1] : null;
+  }
+  /**
+   * BFS from HTMLDocument nodes through DOM tree edges to find "attached" nodes.
+   * @param snapshot
+   */
+  // eslint-disable-next-line max-statements, complexity
+  static buildAttachedSet(snapshot) {
+    const nc = snapshot.nodeCount;
+    const attached = /* @__PURE__ */ new Set();
+    const docNodes = [];
+    for (let i = 0; i < nc; i += 1) {
+      const ni = i;
+      const name = snapshot.nodeName(ni);
+      if (name === "HTMLDocument" || name === "Document") {
+        docNodes.push(ni);
+      }
+    }
+    if (docNodes.length === 0) return attached;
+    const visited = new Uint8Array(nc);
+    const queue = [];
+    docNodes.forEach((ni) => {
+      if (!visited[ni]) {
+        visited[ni] = 1;
+        queue.push(ni);
+        attached.add(ni);
+      }
+    });
+    let head = 0;
+    while (head < queue.length) {
+      const ni = queue[head];
+      head += 1;
+      const nodeType = snapshot.nodeType(ni);
+      if (!FOLLOW_TYPES.has(nodeType)) continue;
+      for (const ei of snapshot.nodeEdges(ni)) {
+        const to = snapshot.edgeToNode(ei);
+        if (visited[to]) continue;
+        const toType = snapshot.nodeType(to);
+        const toName = snapshot.nodeName(to);
+        if (FOLLOW_TYPES.has(toType)) {
+          visited[to] = 1;
+          queue.push(to);
+          if (toType === "native" && DOM_TAG_RE.test(toName)) {
+            attached.add(to);
+          }
+        }
+      }
+    }
+    return attached;
+  }
+  static rankGroupElements(group, snapshot, visited) {
+    const { nodeIndices } = group;
+    const ranked = nodeIndices.map((ni) => ({
+      nodeIndex: ni,
+      edgeCount: snapshot.nodeRawEdgeCount(ni),
+      name: snapshot.nodeName(ni),
+      selfSize: snapshot.nodeSelfSize(ni),
+      retainedSize: 0
+    }));
+    ranked.sort((a, b) => (b.edgeCount ?? 0) - (a.edgeCount ?? 0));
+    const sampleSize = Math.min(ranked.length, 30);
+    const sampled = ranked.slice(0, sampleSize);
+    sampled.forEach((elem) => {
+      elem.retainedSize = LeakDetector.estimateSingleRetainedSize(
+        elem.nodeIndex,
+        snapshot,
+        visited
+      );
+    });
+    sampled.sort((a, b) => b.retainedSize - a.retainedSize);
+    group.topElements = sampled.slice(0, 5);
+    if (sampled.length > 0) {
+      group.representativeIndex = sampled[0].nodeIndex;
+      group.retainedSize = sampled.reduce((sum, e) => sum + e.retainedSize, 0);
+    } else {
+      group.representativeIndex = nodeIndices[0];
+      group.retainedSize = group.totalSelfSize;
+    }
+  }
+  static estimateSingleRetainedSize(startNi, snapshot, visited) {
+    const toClean = [];
+    const queue = [startNi];
+    visited[startNi] = 1;
+    toClean.push(startNi);
+    let total = snapshot.nodeSelfSize(startNi);
+    let visits = 0;
+    let head = 0;
+    while (head < queue.length && visits < MAX_SINGLE_BFS) {
+      const ni = queue[head];
+      head += 1;
+      visits += 1;
+      for (const ei of snapshot.nodeEdges(ni)) {
+        const to = snapshot.edgeToNode(ei);
+        if (!visited[to]) {
+          visited[to] = 1;
+          toClean.push(to);
+          total += snapshot.nodeSelfSize(to);
+          queue.push(to);
+        }
+      }
+    }
+    for (const idx of toClean) visited[idx] = 0;
+    return total;
+  }
+}