@mtharrison/pkg-profiler 1.0.1

package/src/reporter/html.ts

@@ -0,0 +1,373 @@
+/**
+ * HTML renderer for the profiling report.
+ *
+ * Generates a self-contained HTML file (inline CSS, no external dependencies)
+ * with a summary table and expandable Package > File > Function tree.
+ */
+
+import type { ReportData, PackageEntry, FileEntry } from '../types.js';
+import { formatTime, formatPct, escapeHtml } from './format.js';
+
+function generateCss(): string {
+  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: PackageEntry[],
+  otherCount: number,
+  totalTimeUs: number,
+): string {
+  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: PackageEntry[],
+  otherCount: number,
+  totalTimeUs: number,
+): string {
+  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.
+ */
+export function renderHtml(data: ReportData): string {
+  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>`;
+}

package/src/reporter.ts

@@ -0,0 +1,42 @@
+/**
+ * Reporter orchestrator.
+ *
+ * Aggregates SampleStore data, renders HTML, writes file to cwd,
+ * and returns the file path.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { SampleStore } from './sample-store.js';
+import { aggregate } from './reporter/aggregate.js';
+import { renderHtml } from './reporter/html.js';
+
+function generateFilename(): string {
+  const now = new Date();
+  const pad = (n: number) => String(n).padStart(2, '0');
+  const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+  const time = `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  return `where-you-at-${date}-${time}.html`;
+}
+
+function readProjectName(cwd: string): string {
+  try {
+    const raw = readFileSync(join(cwd, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw) as { name?: string };
+    return pkg.name ?? 'app';
+  } catch {
+    return 'app';
+  }
+}
+
+export function generateReport(store: SampleStore, cwd?: string): string {
+  const resolvedCwd = cwd ?? process.cwd();
+  const projectName = readProjectName(resolvedCwd);
+  const data = aggregate(store, projectName);
+  const html = renderHtml(data);
+  const filename = generateFilename();
+  const filepath = join(resolvedCwd, filename);
+  writeFileSync(filepath, html, 'utf-8');
+  console.log(`Report written to ./${filename}`);
+  return filepath;
+}

package/src/sample-store.ts

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+export class SampleStore {
+  private data = new Map<string, Map<string, Map<string, number>>>();
+  private counts = new Map<string, Map<string, Map<string, number>>>();
+  private internalCount = 0;
+  private 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: string, relativePath: string, functionId: string, deltaUs: number): void {
+    // Accumulate microseconds
+    let fileMap = this.data.get(packageName);
+    if (fileMap === undefined) {
+      fileMap = new Map<string, Map<string, number>>();
+      this.data.set(packageName, fileMap);
+    }
+
+    let funcMap = fileMap.get(relativePath);
+    if (funcMap === undefined) {
+      funcMap = new Map<string, number>();
+      fileMap.set(relativePath, funcMap);
+    }
+
+    funcMap.set(functionId, (funcMap.get(functionId) ?? 0) + deltaUs);
+
+    // Parallel sample count (always +1)
+    let countFileMap = this.counts.get(packageName);
+    if (countFileMap === undefined) {
+      countFileMap = new Map<string, Map<string, number>>();
+      this.counts.set(packageName, countFileMap);
+    }
+
+    let countFuncMap = countFileMap.get(relativePath);
+    if (countFuncMap === undefined) {
+      countFuncMap = new Map<string, number>();
+      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: number): void {
+    this.internalCount += deltaUs;
+    this.internalSamples += 1;
+  }
+
+  /** Reset all accumulated data to a clean state. */
+  clear(): void {
+    this.data = new Map<string, Map<string, Map<string, number>>>();
+    this.counts = new Map<string, Map<string, Map<string, number>>>();
+    this.internalCount = 0;
+    this.internalSamples = 0;
+  }
+
+  /** Read-only access to the accumulated sample data (microseconds). */
+  get packages(): ReadonlyMap<string, Map<string, Map<string, number>>> {
+    return this.data;
+  }
+
+  /** Count of internal/filtered microseconds recorded. */
+  get internal(): number {
+    return this.internalCount;
+  }
+
+  /** Read-only access to the parallel sample counts. */
+  get sampleCountsByPackage(): ReadonlyMap<string, Map<string, Map<string, number>>> {
+    return this.counts;
+  }
+
+  /** Count of internal/filtered samples (raw count, not microseconds). */
+  get internalSampleCount(): number {
+    return this.internalSamples;
+  }
+}

package/src/sampler.ts

@@ -0,0 +1,118 @@
+import { Session } from 'node:inspector/promises';
+import type { Profiler } from 'node:inspector';
+import { parseFrame } from './frame-parser.js';
+import { PackageResolver } from './package-resolver.js';
+import { generateReport } from './reporter.js';
+import { SampleStore } from './sample-store.js';
+import type { RawCallFrame } from './types.js';
+
+// Module-level state -- lazy initialization
+let session: Session | null = 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.
+ */
+export async function track(options?: { interval?: number }): Promise<void> {
+  if (profiling) return;
+
+  if (session === null) {
+    session = new Session();
+    session.connect();
+  }
+
+  await session.post('Profiler.enable');
+
+  if (options?.interval !== undefined) {
+    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.
+ */
+export async function clear(): Promise<void> {
+  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.
+ */
+export async function report(): Promise<string> {
+  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: Profiler.Profile): void {
+  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 as RawCallFrame);
+
+    if (parsed.kind === 'user') {
+      if (parsed.filePath.startsWith('node:')) {
+        // Node.js built-in: attribute to "node (built-in)" package
+        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);
+    }
+  }
+}
+
+/** @internal -- exposed for testing only */
+export function _getStore(): SampleStore {
+  return store;
+}

package/src/types.ts

@@ -0,0 +1,50 @@
+/**
+ * Raw V8 CPU profiler call frame matching Chrome DevTools Protocol Runtime.CallFrame.
+ */
+export interface RawCallFrame {
+  functionName: string;
+  scriptId: string;
+  url: string;
+  lineNumber: number;
+  columnNumber: number;
+}
+
+/**
+ * Parsed and classified stack frame.
+ * Discriminated union on the `kind` field.
+ */
+export type ParsedFrame =
+  | { kind: 'user'; filePath: string; functionId: string }
+  | { kind: 'internal' }
+  | { kind: 'eval' }
+  | { kind: 'wasm' };
+
+/**
+ * Report data types for the aggregate/HTML pipeline.
+ */
+export interface ReportEntry {
+  name: string;
+  timeUs: number;       // accumulated microseconds
+  pct: number;          // percentage of total (0-100)
+  sampleCount: number;  // number of samples attributed
+}
+
+export interface FunctionEntry extends ReportEntry {}
+
+export interface FileEntry extends ReportEntry {
+  functions: FunctionEntry[];
+  otherCount: number;
+}
+
+export interface PackageEntry extends ReportEntry {
+  isFirstParty: boolean;
+  files: FileEntry[];
+  otherCount: number;
+}
+
+export interface ReportData {
+  timestamp: string;
+  totalTimeUs: number;
+  packages: PackageEntry[];
+  otherCount: number;
+}