@mtharrison/pkg-profiler 2.1.0 → 2.2.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/logo.svg" width="120" height="120" alt="where-you-at logo">
+  <img src="assets/logo.png" width="120" height="120" alt="where-you-at logo">
 </p>
 
 <h1 align="center">@mtharrison/pkg-profiler</h1>
@@ -22,7 +22,7 @@
 ## Quick Start
 
 ```typescript
-import { start, stop } from '@mtharrison/pkg-profiler';
+import { start, stop } from "@mtharrison/pkg-profiler";
 
 await start();
 // ... your code here ...
@@ -33,7 +33,7 @@ result.writeHtml(); // writes an HTML report to cwd
 Or use the convenience wrapper:
 
 ```typescript
-import { profile } from '@mtharrison/pkg-profiler';
+import { profile } from "@mtharrison/pkg-profiler";
 
 const result = await profile(async () => {
   await build();
@@ -51,8 +51,8 @@ A self-contained HTML report that shows exactly which npm packages are eating yo
 
 Start the V8 CPU sampling profiler. Safe no-op if already profiling.
 
-| Option     | Type     | Default | Description                        |
-|------------|----------|---------|------------------------------------|
+| Option     | Type     | Default    | Description                       |
+| ---------- | -------- | ---------- | --------------------------------- |
 | `interval` | `number` | V8 default | Sampling interval in microseconds |
 
 ### `stop()`
@@ -91,13 +91,13 @@ app.listen(3000);
 
 Returned by `stop()` and `profile()`. Contains aggregated profiling data.
 
-| Property      | Type             | Description                                    |
-|---------------|------------------|------------------------------------------------|
-| `timestamp`   | `string`         | When the profile was captured                  |
-| `totalTimeUs` | `number`         | Total sampled wall time in microseconds        |
-| `packages`    | `PackageEntry[]` | Package breakdown sorted by time descending    |
-| `otherCount`  | `number`         | Number of packages below reporting threshold   |
-| `projectName` | `string`         | Project name from package.json                 |
+| Property      | Type             | Description                                  |
+| ------------- | ---------------- | -------------------------------------------- |
+| `timestamp`   | `string`         | When the profile was captured                |
+| `totalTimeUs` | `number`         | Total sampled wall time in microseconds      |
+| `packages`    | `PackageEntry[]` | Package breakdown sorted by time descending  |
+| `otherCount`  | `number`         | Number of packages below reporting threshold |
+| `projectName` | `string`         | Project name from package.json               |
 
 #### `writeHtml(path?)`
 

package/dist/index.cjs

@@ -364,6 +364,10 @@ function escapeHtml(str) {
 
 //#endregion
 //#region src/reporter/html.ts
+function formatDepChain(depChain) {
+	if (!depChain || depChain.length === 0) return "";
+	return `<span class="dep-chain">via ${depChain.map((n) => escapeHtml(n)).join(" &gt; ")}</span>`;
+}
 function generateCss() {
 	return `
     :root {
@@ -507,6 +511,7 @@ function generateCss() {
     }
 
     td.pkg-name { font-family: var(--font-mono); font-size: 0.85rem; }
+    .dep-chain { display: block; font-size: 0.7rem; color: var(--muted); font-family: var(--font-sans); }
     td.numeric { text-align: right; font-family: var(--font-mono); font-size: 0.85rem; }
     td.async-col { color: var(--bar-fill-async); }
 
@@ -735,6 +740,11 @@ function generateJs() {
       .replace(/'/g, '&#39;');
   }
 
+  function depChainHtml(depChain) {
+    if (!depChain || depChain.length === 0) return '';
+    return '<span class="dep-chain">via ' + depChain.map(function(n) { return escapeHtml(n); }).join(' &gt; ') + '</span>';
+  }
+
   var sortBy = 'cpu';
 
   function metricTime(entry) {
@@ -805,6 +815,7 @@ function generateJs() {
         pct: pkg.pct,
         isFirstParty: pkg.isFirstParty,
         sampleCount: pkg.sampleCount,
+        depChain: pkg.depChain,
         asyncTimeUs: pkg.asyncTimeUs,
         asyncPct: pkg.asyncPct,
         asyncOpCount: pkg.asyncOpCount,
@@ -826,7 +837,7 @@ function generateJs() {
       var barVal = isAsync ? (pkg.asyncTimeUs || 0) : pkg.timeUs;
       var pctVal = barTotal > 0 ? (barVal / barTotal) * 100 : 0;
       rows += '<tr class="' + cls + '">' +
-        '<td class="pkg-name">' + escapeHtml(pkg.name) + '</td>' +
+        '<td class="pkg-name">' + escapeHtml(pkg.name) + depChainHtml(pkg.depChain) + '</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>' +
@@ -880,6 +891,7 @@ function generateJs() {
       html += '<details class="level-0' + fpCls + '"><summary>';
       html += '<span class="tree-label pkg">pkg</span>';
       html += '<span class="tree-name">' + escapeHtml(pkg.name) + '</span>';
+      html += depChainHtml(pkg.depChain);
       html += '<span class="tree-stats">' + escapeHtml(formatTime(pkgTime)) + ' &middot; ' + escapeHtml(formatPct(pkgTime, pctTotal)) + ' &middot; ' + pkg.sampleCount + ' samples</span>';
       html += asyncStats(pkg);
       html += '</summary>';
@@ -980,7 +992,7 @@ function renderSummaryTable(packages, otherCount, totalTimeUs, hasAsync) {
 		const pctVal = totalTimeUs > 0 ? pkg.timeUs / totalTimeUs * 100 : 0;
 		rows += `
       <tr class="${cls}">
-        <td class="pkg-name">${escapeHtml(pkg.name)}</td>
+        <td class="pkg-name">${escapeHtml(pkg.name)}${formatDepChain(pkg.depChain)}</td>
         <td class="numeric">${escapeHtml(formatTime(pkg.timeUs))}</td>
         <td class="bar-cell">
           <div class="bar-container">
@@ -1032,6 +1044,7 @@ function renderTree(packages, otherCount, totalTimeUs, hasAsync) {
 		html += `<summary>`;
 		html += `<span class="tree-label pkg">pkg</span>`;
 		html += `<span class="tree-name">${escapeHtml(pkg.name)}</span>`;
+		html += formatDepChain(pkg.depChain);
 		html += `<span class="tree-stats">${escapeHtml(formatTime(pkg.timeUs))} &middot; ${escapeHtml(formatPct(pkg.timeUs, totalTimeUs))} &middot; ${pkg.sampleCount} samples</span>`;
 		if (hasAsync) html += formatAsyncStats(pkg);
 		html += `</summary>`;
@@ -1181,6 +1194,73 @@ var PkgProfile = class {
 	}
 };
 
+//#endregion
+//#region src/dep-chain.ts
+/**
+* Resolve dependency chains for transitive npm packages.
+*
+* BFS through node_modules package.json files starting from the project's
+* direct dependencies to find the shortest path to each profiled package.
+*/
+function readPkgJson(dir, cache) {
+	if (cache.has(dir)) return cache.get(dir);
+	try {
+		const raw = (0, node_fs.readFileSync)((0, node_path.join)(dir, "package.json"), "utf-8");
+		const parsed = JSON.parse(raw);
+		cache.set(dir, parsed);
+		return parsed;
+	} catch {
+		cache.set(dir, null);
+		return null;
+	}
+}
+function depsOf(pkg) {
+	return [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.optionalDependencies ?? {})];
+}
+/**
+* Resolve the shortest dependency chain from the project's direct deps
+* to each of the given package names.
+*
+* @param projectRoot - Absolute path to the project root (contains package.json and node_modules/)
+* @param packageNames - Set of package names that appeared in profiling data
+* @param maxDepth - Maximum BFS depth to search (default 5)
+* @returns Map from package name to chain array (e.g. `["express", "qs"]` means project -> express -> qs)
+*/
+function resolveDependencyChains(projectRoot, packageNames, maxDepth = 5) {
+	const result = /* @__PURE__ */ new Map();
+	const cache = /* @__PURE__ */ new Map();
+	const rootPkg = readPkgJson(projectRoot, cache);
+	if (!rootPkg) return result;
+	const directDeps = new Set(depsOf(rootPkg));
+	for (const name of packageNames) if (directDeps.has(name)) {}
+	const targets = /* @__PURE__ */ new Set();
+	for (const name of packageNames) if (!directDeps.has(name)) targets.add(name);
+	if (targets.size === 0) return result;
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [];
+	for (const dep of directDeps) {
+		queue.push([dep, [dep]]);
+		visited.add(dep);
+	}
+	let qi = 0;
+	while (qi < queue.length && targets.size > 0) {
+		const [pkgName, chain] = queue[qi++];
+		if (chain.length > maxDepth) continue;
+		if (targets.has(pkgName)) {
+			result.set(pkgName, chain.slice(0, -1));
+			targets.delete(pkgName);
+			if (targets.size === 0) break;
+		}
+		const pkg = readPkgJson((0, node_path.join)(projectRoot, "node_modules", pkgName), cache);
+		if (!pkg) continue;
+		for (const child of depsOf(pkg)) if (!visited.has(child)) {
+			visited.add(child);
+			queue.push([child, [...chain, child]]);
+		}
+	}
+	return result;
+}
+
 //#endregion
 //#region src/reporter/aggregate.ts
 /**
@@ -1199,7 +1279,7 @@ function sumStore(store) {
 * @param asyncStore - Optional SampleStore with async wait time data
 * @returns ReportData with all packages sorted desc by time, no threshold applied
 */
-function aggregate(store, projectName, asyncStore, globalAsyncTimeUs, wallTimeUs) {
+function aggregate(store, projectName, asyncStore, globalAsyncTimeUs, wallTimeUs, projectRoot) {
 	const totalTimeUs = sumStore(store);
 	const totalAsyncTimeUs = asyncStore ? sumStore(asyncStore) : 0;
 	const headerAsyncTimeUs = globalAsyncTimeUs ?? totalAsyncTimeUs;
@@ -1299,6 +1379,16 @@ function aggregate(store, projectName, asyncStore, globalAsyncTimeUs, wallTimeUs
 		}
 		packages.push(pkgEntry);
 	}
+	if (projectRoot) {
+		const thirdPartyNames = new Set(packages.filter((p) => !p.isFirstParty).map((p) => p.name));
+		if (thirdPartyNames.size > 0) {
+			const chains = resolveDependencyChains(projectRoot, thirdPartyNames);
+			for (const pkg of packages) {
+				const chain = chains.get(pkg.name);
+				if (chain && chain.length > 0) pkg.depChain = chain;
+			}
+		}
+	}
 	packages.sort((a, b) => b.timeUs - a.timeUs);
 	const result = {
 		timestamp: (/* @__PURE__ */ new Date()).toLocaleString(),
@@ -1462,7 +1552,8 @@ function stopSync() {
 		asyncTracker = null;
 	}
 	processProfile(profile);
-	const data = aggregate(store, readProjectName(process.cwd()), asyncStore.packages.size > 0 ? asyncStore : void 0, globalAsyncTimeUs, wallTimeUs);
+	const cwd = process.cwd();
+	const data = aggregate(store, readProjectName(cwd), asyncStore.packages.size > 0 ? asyncStore : void 0, globalAsyncTimeUs, wallTimeUs, cwd);
 	store.clear();
 	asyncStore.clear();
 	return new PkgProfile(data);