@mtharrison/pkg-profiler 1.0.1

package/dist/index.cjs

@@ -0,0 +1,752 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let node_inspector_promises = require("node:inspector/promises");
+let node_url = require("node:url");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+
+//#region src/frame-parser.ts
+/**
+* Classify a V8 CPU profiler call frame and convert its URL to a filesystem path.
+*
+* Every sampled frame from the V8 profiler passes through this function first.
+* It determines the frame kind (user code, internal, eval, wasm) and for user
+* frames converts the URL to a filesystem path and builds a human-readable
+* function identifier.
+*/
+function parseFrame(frame) {
+	const { url, functionName, lineNumber } = frame;
+	if (url === "") return { kind: "internal" };
+	if (url.startsWith("node:")) return {
+		kind: "user",
+		filePath: url,
+		functionId: `${functionName || "<anonymous>"}:${lineNumber + 1}`
+	};
+	if (url.startsWith("wasm:")) return { kind: "wasm" };
+	if (url.includes("eval")) return { kind: "eval" };
+	return {
+		kind: "user",
+		filePath: url.startsWith("file://") ? (0, node_url.fileURLToPath)(url) : url,
+		functionId: `${functionName || "<anonymous>"}:${lineNumber + 1}`
+	};
+}
+
+//#endregion
+//#region src/package-resolver.ts
+/**
+* Resolves an absolute file path to a package name and relative path.
+*
+* For node_modules paths: extracts the package name from the last /node_modules/
+* segment (critical for pnpm virtual store compatibility). Handles scoped packages.
+*
+* For first-party files: walks up directory tree looking for package.json,
+* falls back to 'app' if none found.
+*/
+var PackageResolver = class {
+	projectRoot;
+	packageJsonCache = /* @__PURE__ */ new Map();
+	constructor(projectRoot) {
+		this.projectRoot = projectRoot;
+	}
+	resolve(absoluteFilePath) {
+		const nodeModulesSeg = `${node_path.sep}node_modules${node_path.sep}`;
+		const lastIdx = absoluteFilePath.lastIndexOf(nodeModulesSeg);
+		if (lastIdx !== -1) {
+			const segments = absoluteFilePath.substring(lastIdx + nodeModulesSeg.length).split(node_path.sep);
+			let packageName;
+			let fileStartIdx;
+			if (segments[0].startsWith("@")) {
+				packageName = `${segments[0]}/${segments[1]}`;
+				fileStartIdx = 2;
+			} else {
+				packageName = segments[0];
+				fileStartIdx = 1;
+			}
+			const relativePath = segments.slice(fileStartIdx).join("/");
+			return {
+				packageName,
+				relativePath
+			};
+		}
+		return {
+			packageName: this.findPackageName(absoluteFilePath),
+			relativePath: (0, node_path.relative)(this.projectRoot, absoluteFilePath).split(node_path.sep).join("/")
+		};
+	}
+	/**
+	* Walk up from the file's directory looking for package.json.
+	* Cache results to avoid repeated filesystem reads.
+	*/
+	findPackageName(absoluteFilePath) {
+		let dir = (0, node_path.dirname)(absoluteFilePath);
+		while (true) {
+			const cached = this.packageJsonCache.get(dir);
+			if (cached !== void 0) {
+				if (cached !== null) return cached;
+			} else try {
+				const raw = (0, node_fs.readFileSync)((0, node_path.join)(dir, "package.json"), "utf-8");
+				const name = JSON.parse(raw).name ?? null;
+				this.packageJsonCache.set(dir, name);
+				if (name !== null) return name;
+			} catch {
+				this.packageJsonCache.set(dir, null);
+			}
+			const parent = (0, node_path.dirname)(dir);
+			if (parent === dir) return "app";
+			dir = parent;
+		}
+	}
+};
+
+//#endregion
+//#region src/reporter/aggregate.ts
+const THRESHOLD_PCT = .05;
+/**
+* Aggregate SampleStore data into a ReportData structure.
+*
+* @param store - SampleStore with accumulated microseconds and sample counts
+* @param projectName - Name of the first-party project (for isFirstParty flag)
+* @returns ReportData with packages sorted desc by time, thresholded at 5%
+*/
+function aggregate(store, projectName) {
+	let totalTimeUs = 0;
+	for (const fileMap of store.packages.values()) for (const funcMap of fileMap.values()) for (const us of funcMap.values()) totalTimeUs += us;
+	if (totalTimeUs === 0) return {
+		timestamp: (/* @__PURE__ */ new Date()).toLocaleString(),
+		totalTimeUs: 0,
+		packages: [],
+		otherCount: 0
+	};
+	const threshold = totalTimeUs * THRESHOLD_PCT;
+	const packages = [];
+	let topLevelOtherCount = 0;
+	for (const [packageName, fileMap] of store.packages) {
+		let packageTimeUs = 0;
+		for (const funcMap of fileMap.values()) for (const us of funcMap.values()) packageTimeUs += us;
+		if (packageTimeUs < threshold) {
+			topLevelOtherCount++;
+			continue;
+		}
+		let packageSampleCount = 0;
+		const countFileMap = store.sampleCountsByPackage.get(packageName);
+		if (countFileMap) for (const countFuncMap of countFileMap.values()) for (const count of countFuncMap.values()) packageSampleCount += count;
+		const files = [];
+		let fileOtherCount = 0;
+		for (const [fileName, funcMap] of fileMap) {
+			let fileTimeUs = 0;
+			for (const us of funcMap.values()) fileTimeUs += us;
+			if (fileTimeUs < threshold) {
+				fileOtherCount++;
+				continue;
+			}
+			let fileSampleCount = 0;
+			const countFuncMap = countFileMap?.get(fileName);
+			if (countFuncMap) for (const count of countFuncMap.values()) fileSampleCount += count;
+			const functions = [];
+			let funcOtherCount = 0;
+			for (const [funcName, funcTimeUs] of funcMap) {
+				if (funcTimeUs < threshold) {
+					funcOtherCount++;
+					continue;
+				}
+				const funcSampleCount = countFuncMap?.get(funcName) ?? 0;
+				functions.push({
+					name: funcName,
+					timeUs: funcTimeUs,
+					pct: funcTimeUs / totalTimeUs * 100,
+					sampleCount: funcSampleCount
+				});
+			}
+			functions.sort((a, b) => b.timeUs - a.timeUs);
+			files.push({
+				name: fileName,
+				timeUs: fileTimeUs,
+				pct: fileTimeUs / totalTimeUs * 100,
+				sampleCount: fileSampleCount,
+				functions,
+				otherCount: funcOtherCount
+			});
+		}
+		files.sort((a, b) => b.timeUs - a.timeUs);
+		packages.push({
+			name: packageName,
+			timeUs: packageTimeUs,
+			pct: packageTimeUs / totalTimeUs * 100,
+			isFirstParty: packageName === projectName,
+			sampleCount: packageSampleCount,
+			files,
+			otherCount: fileOtherCount
+		});
+	}
+	packages.sort((a, b) => b.timeUs - a.timeUs);
+	return {
+		timestamp: (/* @__PURE__ */ new Date()).toLocaleString(),
+		totalTimeUs,
+		packages,
+		otherCount: topLevelOtherCount
+	};
+}
+
+//#endregion
+//#region src/reporter/format.ts
+/**
+* Format utilities for the HTML reporter.
+* Pure functions with defined input/output contracts.
+*/
+/**
+* Convert microseconds to adaptive human-readable time string.
+*
+* - >= 1s: shows seconds with 2 decimal places (e.g. "1.24s")
+* - < 1s:  shows rounded milliseconds (e.g. "432ms")
+* - Sub-millisecond values round up to 1ms (never shows "0ms" for nonzero input)
+* - Zero returns "0ms"
+*/
+function formatTime(us) {
+	if (us === 0) return "0ms";
+	const ms = us / 1e3;
+	if (ms >= 1e3) return `${(ms / 1e3).toFixed(2)}s`;
+	const rounded = Math.round(ms);
+	return `${rounded < 1 ? 1 : rounded}ms`;
+}
+/**
+* Convert microseconds to percentage of total with one decimal place.
+* Returns "0.0%" when totalUs is zero (avoids division by zero).
+*/
+function formatPct(us, totalUs) {
+	if (totalUs === 0) return "0.0%";
+	return `${(us / totalUs * 100).toFixed(1)}%`;
+}
+/**
+* Escape HTML-special characters to prevent broken markup.
+* Handles: & < > " '
+* Ampersand is replaced first to avoid double-escaping.
+*/
+function escapeHtml(str) {
+	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+//#endregion
+//#region src/reporter/html.ts
+function generateCss() {
+	return `
+    :root {
+      --bg: #fafbfc;
+      --text: #1a1a2e;
+      --muted: #8b8fa3;
+      --border: #e2e4ea;
+      --first-party-accent: #3b6cf5;
+      --first-party-bg: #eef2ff;
+      --dep-bg: #ffffff;
+      --bar-track: #e8eaed;
+      --bar-fill: #5b8def;
+      --bar-fill-fp: #3b6cf5;
+      --other-text: #a0a4b8;
+      --table-header-bg: #f4f5f7;
+      --shadow: 0 1px 3px rgba(0,0,0,0.06);
+      --radius: 6px;
+      --font-mono: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, monospace;
+      --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    }
+
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+
+    body {
+      font-family: var(--font-sans);
+      background: var(--bg);
+      color: var(--text);
+      line-height: 1.5;
+      padding: 2rem;
+      max-width: 960px;
+      margin: 0 auto;
+    }
+
+    h1 {
+      font-size: 1.5rem;
+      font-weight: 600;
+      margin-bottom: 0.25rem;
+    }
+
+    .meta {
+      color: var(--muted);
+      font-size: 0.85rem;
+      margin-bottom: 2rem;
+    }
+
+    h2 {
+      font-size: 1.1rem;
+      font-weight: 600;
+      margin-bottom: 0.75rem;
+      margin-top: 2rem;
+    }
+
+    /* Summary table */
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      background: #fff;
+      border-radius: var(--radius);
+      box-shadow: var(--shadow);
+      overflow: hidden;
+      margin-bottom: 1rem;
+    }
+
+    th {
+      text-align: left;
+      background: var(--table-header-bg);
+      padding: 0.6rem 0.75rem;
+      font-size: 0.8rem;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+      color: var(--muted);
+      border-bottom: 1px solid var(--border);
+    }
+
+    td {
+      padding: 0.55rem 0.75rem;
+      border-bottom: 1px solid var(--border);
+      font-size: 0.9rem;
+    }
+
+    tr:last-child td { border-bottom: none; }
+
+    tr.first-party td:first-child {
+      border-left: 3px solid var(--first-party-accent);
+      padding-left: calc(0.75rem - 3px);
+    }
+
+    td.pkg-name { font-family: var(--font-mono); font-size: 0.85rem; }
+    td.numeric { text-align: right; font-family: var(--font-mono); font-size: 0.85rem; }
+
+    .bar-cell {
+      width: 30%;
+      padding-right: 1rem;
+    }
+
+    .bar-container {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+    }
+
+    .bar-track {
+      flex: 1;
+      height: 8px;
+      background: var(--bar-track);
+      border-radius: 4px;
+      overflow: hidden;
+    }
+
+    .bar-fill {
+      height: 100%;
+      border-radius: 4px;
+      background: var(--bar-fill);
+      min-width: 1px;
+    }
+
+    tr.first-party .bar-fill {
+      background: var(--bar-fill-fp);
+    }
+
+    .bar-pct {
+      font-family: var(--font-mono);
+      font-size: 0.8rem;
+      min-width: 3.5em;
+      text-align: right;
+    }
+
+    tr.other-row td {
+      color: var(--other-text);
+      font-style: italic;
+    }
+
+    /* Tree */
+    .tree {
+      background: #fff;
+      border-radius: var(--radius);
+      box-shadow: var(--shadow);
+      overflow: hidden;
+    }
+
+    details {
+      border-bottom: 1px solid var(--border);
+    }
+
+    details:last-child { border-bottom: none; }
+
+    details details { border-bottom: 1px solid var(--border); }
+    details details:last-child { border-bottom: none; }
+
+    summary {
+      cursor: pointer;
+      list-style: none;
+      padding: 0.6rem 0.75rem;
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      font-size: 0.9rem;
+      user-select: none;
+    }
+
+    summary::-webkit-details-marker { display: none; }
+
+    summary::before {
+      content: '\\25B6';
+      font-size: 0.6rem;
+      color: var(--muted);
+      transition: transform 0.15s ease;
+      flex-shrink: 0;
+    }
+
+    details[open] > summary::before {
+      transform: rotate(90deg);
+    }
+
+    .tree-name {
+      font-family: var(--font-mono);
+      font-size: 0.85rem;
+      flex: 1;
+    }
+
+    .tree-label {
+      font-family: var(--font-sans);
+      font-size: 0.65rem;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+      padding: 0.1rem 0.35rem;
+      border-radius: 3px;
+      flex-shrink: 0;
+    }
+
+    .tree-label.pkg { background: #e8eaed; color: #555; }
+    .tree-label.file { background: #e8f0fe; color: #3b6cf5; }
+    .tree-label.fn { background: #f0f0f0; color: #777; }
+
+    .tree-stats {
+      font-family: var(--font-mono);
+      font-size: 0.8rem;
+      color: var(--muted);
+      flex-shrink: 0;
+    }
+
+    /* Level indentation */
+    .level-0 > summary { padding-left: 0.75rem; }
+    .level-1 > summary { padding-left: 2rem; }
+    .level-2 { padding: 0.45rem 0.75rem 0.45rem 3.25rem; font-size: 0.85rem; display: flex; align-items: center; gap: 0.5rem; }
+
+    /* First-party package highlight */
+    .fp-pkg > summary {
+      background: var(--first-party-bg);
+      border-left: 3px solid var(--first-party-accent);
+    }
+
+    .other-item {
+      padding: 0.45rem 0.75rem;
+      color: var(--other-text);
+      font-style: italic;
+      font-size: 0.85rem;
+    }
+
+    .other-item.indent-1 { padding-left: 2rem; }
+    .other-item.indent-2 { padding-left: 3.25rem; }
+
+    @media (max-width: 600px) {
+      body { padding: 1rem; }
+      .bar-cell { width: 25%; }
+    }
+  `;
+}
+function renderSummaryTable(packages, otherCount, totalTimeUs) {
+	let rows = "";
+	for (const pkg of packages) {
+		const cls = pkg.isFirstParty ? "first-party" : "dependency";
+		const pctVal = totalTimeUs > 0 ? pkg.timeUs / totalTimeUs * 100 : 0;
+		rows += `
+      <tr class="${cls}">
+        <td class="pkg-name">${escapeHtml(pkg.name)}</td>
+        <td class="numeric">${escapeHtml(formatTime(pkg.timeUs))}</td>
+        <td class="bar-cell">
+          <div class="bar-container">
+            <div class="bar-track"><div class="bar-fill" style="width:${pctVal.toFixed(1)}%"></div></div>
+            <span class="bar-pct">${escapeHtml(formatPct(pkg.timeUs, totalTimeUs))}</span>
+          </div>
+        </td>
+        <td class="numeric">${pkg.sampleCount}</td>
+      </tr>`;
+	}
+	if (otherCount > 0) rows += `
+      <tr class="other-row">
+        <td class="pkg-name">Other (${otherCount} items)</td>
+        <td class="numeric"></td>
+        <td class="bar-cell"></td>
+        <td class="numeric"></td>
+      </tr>`;
+	return `
+    <table>
+      <thead>
+        <tr>
+          <th>Package</th>
+          <th>Wall Time</th>
+          <th>% of Total</th>
+          <th>Samples</th>
+        </tr>
+      </thead>
+      <tbody>${rows}
+      </tbody>
+    </table>`;
+}
+function renderTree(packages, otherCount, totalTimeUs) {
+	let html = "<div class=\"tree\">";
+	for (const pkg of packages) {
+		const fpCls = pkg.isFirstParty ? " fp-pkg" : "";
+		html += `<details class="level-0${fpCls}">`;
+		html += `<summary>`;
+		html += `<span class="tree-label pkg">pkg</span>`;
+		html += `<span class="tree-name">${escapeHtml(pkg.name)}</span>`;
+		html += `<span class="tree-stats">${escapeHtml(formatTime(pkg.timeUs))} &middot; ${escapeHtml(formatPct(pkg.timeUs, totalTimeUs))} &middot; ${pkg.sampleCount} samples</span>`;
+		html += `</summary>`;
+		for (const file of pkg.files) {
+			html += `<details class="level-1">`;
+			html += `<summary>`;
+			html += `<span class="tree-label file">file</span>`;
+			html += `<span class="tree-name">${escapeHtml(file.name)}</span>`;
+			html += `<span class="tree-stats">${escapeHtml(formatTime(file.timeUs))} &middot; ${escapeHtml(formatPct(file.timeUs, totalTimeUs))} &middot; ${file.sampleCount} samples</span>`;
+			html += `</summary>`;
+			for (const fn of file.functions) {
+				html += `<div class="level-2">`;
+				html += `<span class="tree-label fn">fn</span> `;
+				html += `<span class="tree-name">${escapeHtml(fn.name)}</span>`;
+				html += ` <span class="tree-stats">${escapeHtml(formatTime(fn.timeUs))} &middot; ${escapeHtml(formatPct(fn.timeUs, totalTimeUs))} &middot; ${fn.sampleCount} samples</span>`;
+				html += `</div>`;
+			}
+			if (file.otherCount > 0) html += `<div class="other-item indent-2">Other (${file.otherCount} items)</div>`;
+			html += `</details>`;
+		}
+		if (pkg.otherCount > 0) html += `<div class="other-item indent-1">Other (${pkg.otherCount} items)</div>`;
+		html += `</details>`;
+	}
+	if (otherCount > 0) html += `<div class="other-item">Other (${otherCount} packages)</div>`;
+	html += "</div>";
+	return html;
+}
+/**
+* Render a complete self-contained HTML report from aggregated profiling data.
+*/
+function renderHtml(data) {
+	const summaryTable = renderSummaryTable(data.packages, data.otherCount, data.totalTimeUs);
+	const tree = renderTree(data.packages, data.otherCount, data.totalTimeUs);
+	const totalFormatted = escapeHtml(formatTime(data.totalTimeUs));
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>where-you-at report</title>
+  <style>${generateCss()}
+  </style>
+</head>
+<body>
+  <h1>where-you-at</h1>
+  <div class="meta">Generated ${escapeHtml(data.timestamp)} &middot; Total wall time: ${totalFormatted}</div>
+
+  <h2>Summary</h2>
+  ${summaryTable}
+
+  <h2>Details</h2>
+  ${tree}
+</body>
+</html>`;
+}
+
+//#endregion
+//#region src/reporter.ts
+/**
+* Reporter orchestrator.
+*
+* Aggregates SampleStore data, renders HTML, writes file to cwd,
+* and returns the file path.
+*/
+function generateFilename() {
+	const now = /* @__PURE__ */ new Date();
+	const pad = (n) => String(n).padStart(2, "0");
+	return `where-you-at-${`${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`}-${`${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`}.html`;
+}
+function readProjectName(cwd) {
+	try {
+		const raw = (0, node_fs.readFileSync)((0, node_path.join)(cwd, "package.json"), "utf-8");
+		return JSON.parse(raw).name ?? "app";
+	} catch {
+		return "app";
+	}
+}
+function generateReport(store, cwd) {
+	const resolvedCwd = cwd ?? process.cwd();
+	const html = renderHtml(aggregate(store, readProjectName(resolvedCwd)));
+	const filename = generateFilename();
+	const filepath = (0, node_path.join)(resolvedCwd, filename);
+	(0, node_fs.writeFileSync)(filepath, html, "utf-8");
+	console.log(`Report written to ./${filename}`);
+	return filepath;
+}
+
+//#endregion
+//#region src/sample-store.ts
+/**
+* Accumulates per-package wall time (microseconds) from the V8 CPU profiler.
+*
+* Data structure: nested Maps -- package -> file -> function -> microseconds.
+* This naturally matches the package-first tree output that the reporter
+* needs in Phase 3. O(1) lookups at each level, no serialization overhead.
+*
+* A parallel sampleCounts structure tracks raw sample counts (incremented by 1
+* per record() call) for the summary table's "Sample count" column.
+*/
+var SampleStore = class {
+	data = /* @__PURE__ */ new Map();
+	counts = /* @__PURE__ */ new Map();
+	internalCount = 0;
+	internalSamples = 0;
+	/**
+	* Record a sample for a user-code frame.
+	* Accumulates deltaUs microseconds for the given (package, file, function) triple,
+	* and increments the parallel sample count by 1.
+	*/
+	record(packageName, relativePath, functionId, deltaUs) {
+		let fileMap = this.data.get(packageName);
+		if (fileMap === void 0) {
+			fileMap = /* @__PURE__ */ new Map();
+			this.data.set(packageName, fileMap);
+		}
+		let funcMap = fileMap.get(relativePath);
+		if (funcMap === void 0) {
+			funcMap = /* @__PURE__ */ new Map();
+			fileMap.set(relativePath, funcMap);
+		}
+		funcMap.set(functionId, (funcMap.get(functionId) ?? 0) + deltaUs);
+		let countFileMap = this.counts.get(packageName);
+		if (countFileMap === void 0) {
+			countFileMap = /* @__PURE__ */ new Map();
+			this.counts.set(packageName, countFileMap);
+		}
+		let countFuncMap = countFileMap.get(relativePath);
+		if (countFuncMap === void 0) {
+			countFuncMap = /* @__PURE__ */ new Map();
+			countFileMap.set(relativePath, countFuncMap);
+		}
+		countFuncMap.set(functionId, (countFuncMap.get(functionId) ?? 0) + 1);
+	}
+	/** Record an internal/filtered frame (empty URL, eval, wasm, idle, etc). */
+	recordInternal(deltaUs) {
+		this.internalCount += deltaUs;
+		this.internalSamples += 1;
+	}
+	/** Reset all accumulated data to a clean state. */
+	clear() {
+		this.data = /* @__PURE__ */ new Map();
+		this.counts = /* @__PURE__ */ new Map();
+		this.internalCount = 0;
+		this.internalSamples = 0;
+	}
+	/** Read-only access to the accumulated sample data (microseconds). */
+	get packages() {
+		return this.data;
+	}
+	/** Count of internal/filtered microseconds recorded. */
+	get internal() {
+		return this.internalCount;
+	}
+	/** Read-only access to the parallel sample counts. */
+	get sampleCountsByPackage() {
+		return this.counts;
+	}
+	/** Count of internal/filtered samples (raw count, not microseconds). */
+	get internalSampleCount() {
+		return this.internalSamples;
+	}
+};
+
+//#endregion
+//#region src/sampler.ts
+let session = null;
+let profiling = false;
+const store = new SampleStore();
+const resolver = new PackageResolver(process.cwd());
+/**
+* Start the V8 CPU profiler. If already profiling, this is a safe no-op.
+*/
+async function track(options) {
+	if (profiling) return;
+	if (session === null) {
+		session = new node_inspector_promises.Session();
+		session.connect();
+	}
+	await session.post("Profiler.enable");
+	if (options?.interval !== void 0) await session.post("Profiler.setSamplingInterval", { interval: options.interval });
+	await session.post("Profiler.start");
+	profiling = true;
+}
+/**
+* Stop the profiler (if running) and reset all accumulated sample data.
+*/
+async function clear() {
+	if (profiling && session) {
+		await session.post("Profiler.stop");
+		await session.post("Profiler.disable");
+		profiling = false;
+	}
+	store.clear();
+}
+/**
+* Stop the profiler, process collected samples through the data pipeline
+* (parseFrame -> PackageResolver -> SampleStore), generate an HTML report,
+* and return the file path. Resets the store after reporting (clean slate
+* for next cycle).
+*
+* Returns the absolute path to the generated HTML file, or empty string
+* if no samples were collected.
+*/
+async function report() {
+	if (!profiling || !session) {
+		console.log("no samples collected");
+		return "";
+	}
+	const { profile } = await session.post("Profiler.stop");
+	await session.post("Profiler.disable");
+	profiling = false;
+	processProfile(profile);
+	let filepath = "";
+	if (store.packages.size > 0) filepath = generateReport(store);
+	else console.log("no samples collected");
+	store.clear();
+	return filepath;
+}
+/**
+* Process a V8 CPUProfile: walk each sample, parse the frame, resolve
+* the package, and record into the store. Uses timeDeltas for wall-time
+* microsecond accumulation.
+*/
+function processProfile(profile) {
+	const nodeMap = new Map(profile.nodes.map((n) => [n.id, n]));
+	const samples = profile.samples ?? [];
+	const timeDeltas = profile.timeDeltas ?? [];
+	for (let i = 0; i < samples.length; i++) {
+		const node = nodeMap.get(samples[i]);
+		if (!node) continue;
+		const deltaUs = timeDeltas[i] ?? 0;
+		const parsed = parseFrame(node.callFrame);
+		if (parsed.kind === "user") if (parsed.filePath.startsWith("node:")) {
+			const relativePath = parsed.filePath.slice(5);
+			store.record("node (built-in)", relativePath, parsed.functionId, deltaUs);
+		} else {
+			const { packageName, relativePath } = resolver.resolve(parsed.filePath);
+			store.record(packageName, relativePath, parsed.functionId, deltaUs);
+		}
+		else store.recordInternal(deltaUs);
+	}
+}
+
+//#endregion
+exports.clear = clear;
+exports.report = report;
+exports.track = track;
+//# sourceMappingURL=index.cjs.map