agent-react-devtools 0.0.0 → 0.1.0

package/src/formatters.ts

@@ -0,0 +1,270 @@
+import type {
+  StatusInfo,
+  InspectedElement,
+  ComponentRenderReport,
+} from './types.js';
+import type { TreeNode } from './component-tree.js';
+import type { ProfileSummary, TimelineEntry, CommitDetail } from './profiler.js';
+
+// ── Abbreviations for component types ──
+const TYPE_ABBREV: Record<string, string> = {
+  function: 'fn',
+  class: 'cls',
+  host: 'host',
+  memo: 'memo',
+  forwardRef: 'fRef',
+  profiler: 'prof',
+  suspense: 'susp',
+  context: 'ctx',
+  other: '?',
+};
+
+function typeTag(type: string): string {
+  return TYPE_ABBREV[type] || type;
+}
+
+// ── Tree connector characters ──
+const PIPE = '│  ';
+const TEE = '├─ ';
+const ELBOW = '└─ ';
+const SPACE = '   ';
+
+export function formatTree(nodes: TreeNode[]): string {
+  if (nodes.length === 0) return 'No components (is a React app connected?)';
+
+  // Build tree structure from the flat list
+  const childrenMap = new Map<number | null, TreeNode[]>();
+  for (const node of nodes) {
+    const parentId = node.parentId;
+    let siblings = childrenMap.get(parentId);
+    if (!siblings) {
+      siblings = [];
+      childrenMap.set(parentId, siblings);
+    }
+    siblings.push(node);
+  }
+
+  const lines: string[] = [];
+
+  function walk(nodeId: number, prefix: string, isLast: boolean, isRoot: boolean): void {
+    const node = nodes.find((n) => n.id === nodeId);
+    if (!node) return;
+
+    const connector = isRoot ? '' : isLast ? ELBOW : TEE;
+    let line = `${node.label} [${typeTag(node.type)}] "${node.displayName}"`;
+    if (node.key) line += ` key="${node.key}"`;
+
+    lines.push(`${prefix}${connector}${line}`);
+
+    const children = childrenMap.get(node.id) || [];
+    const childPrefix = isRoot ? '' : prefix + (isLast ? SPACE : PIPE);
+
+    for (let i = 0; i < children.length; i++) {
+      walk(children[i].id, childPrefix, i === children.length - 1, false);
+    }
+  }
+
+  // Find root nodes
+  const roots = childrenMap.get(null) || [];
+  for (let i = 0; i < roots.length; i++) {
+    walk(roots[i].id, '', i === roots.length - 1, true);
+  }
+
+  return lines.join('\n');
+}
+
+export function formatComponent(element: InspectedElement, label?: string): string {
+  const lines: string[] = [];
+
+  const ref = label || `#${element.id}`;
+  let header = `${ref} [${typeTag(element.type)}] "${element.displayName}"`;
+  if (element.key) header += ` key="${element.key}"`;
+  lines.push(header);
+
+  // Props
+  if (element.props && Object.keys(element.props).length > 0) {
+    lines.push('props:');
+    for (const [key, value] of Object.entries(element.props)) {
+      lines.push(`  ${key}: ${formatCompactValue(value) ?? 'undefined'}`);
+    }
+  }
+
+  // State
+  if (element.state && Object.keys(element.state).length > 0) {
+    lines.push('state:');
+    for (const [key, value] of Object.entries(element.state)) {
+      lines.push(`  ${key}: ${formatCompactValue(value) ?? 'undefined'}`);
+    }
+  }
+
+  // Hooks
+  if (element.hooks && element.hooks.length > 0) {
+    lines.push('hooks:');
+    for (const h of element.hooks) {
+      const val = formatCompactValue(h.value);
+      lines.push(val !== undefined ? `  ${h.name}: ${val}` : `  ${h.name}`);
+      if (h.subHooks && h.subHooks.length > 0) {
+        for (const sh of h.subHooks) {
+          const sval = formatCompactValue(sh.value);
+          lines.push(sval !== undefined ? `    ${sh.name}: ${sval}` : `    ${sh.name}`);
+        }
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function formatSearchResults(results: TreeNode[]): string {
+  if (results.length === 0) return 'No components found';
+
+  return results
+    .map((n) => {
+      let line = `${n.label} [${typeTag(n.type)}] "${n.displayName}"`;
+      if (n.key) line += ` key="${n.key}"`;
+      return line;
+    })
+    .join('\n');
+}
+
+export function formatCount(counts: Record<string, number>): string {
+  const total = Object.values(counts).reduce((a, b) => a + b, 0);
+  const parts = Object.entries(counts)
+    .sort((a, b) => b[1] - a[1])
+    .map(([type, count]) => `${typeTag(type)}:${count}`)
+    .join(' ');
+  return `${total} components (${parts})`;
+}
+
+export function formatStatus(status: StatusInfo): string {
+  const lines: string[] = [];
+  lines.push(`Daemon: running (port ${status.port})`);
+  lines.push(
+    `Apps: ${status.connectedApps} connected, ${status.componentCount} components`,
+  );
+  if (status.profilingActive) {
+    lines.push('Profiling: active');
+  }
+  const upSec = Math.round(status.uptime / 1000);
+  lines.push(`Uptime: ${upSec}s`);
+  return lines.join('\n');
+}
+
+export function formatProfileSummary(summary: ProfileSummary): string {
+  const lines: string[] = [];
+  const durSec = (summary.duration / 1000).toFixed(1);
+  lines.push(
+    `Profile "${summary.name}" (${durSec}s, ${summary.commitCount} commits)`,
+  );
+
+  if (summary.componentRenderCounts.length > 0) {
+    lines.push('');
+    lines.push('Top renders:');
+    for (const c of summary.componentRenderCounts.slice(0, 10)) {
+      const name = c.displayName || `#${c.id}`;
+      lines.push(`  ${name}  ${c.count} renders`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function formatProfileReport(report: ComponentRenderReport, label?: string): string {
+  const lines: string[] = [];
+  const ref = label || `#${report.id}`;
+  lines.push(`${ref} "${report.displayName}"`);
+  lines.push(
+    `renders:${report.renderCount}  avg:${report.avgDuration.toFixed(1)}ms  max:${report.maxDuration.toFixed(1)}ms  total:${report.totalDuration.toFixed(1)}ms`,
+  );
+  if (report.causes.length > 0) {
+    lines.push(`causes: ${report.causes.join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
+export function formatSlowest(reports: ComponentRenderReport[]): string {
+  if (reports.length === 0) return 'No profiling data';
+
+  const lines: string[] = ['Slowest (by avg render time):'];
+  for (const r of reports) {
+    const cause = r.causes[0] || '?';
+    lines.push(
+      `  ${pad(r.displayName, 20)} avg:${r.avgDuration.toFixed(1)}ms  max:${r.maxDuration.toFixed(1)}ms  renders:${r.renderCount}  cause:${cause}`,
+    );
+  }
+  return lines.join('\n');
+}
+
+export function formatRerenders(reports: ComponentRenderReport[]): string {
+  if (reports.length === 0) return 'No profiling data';
+
+  const lines: string[] = ['Most re-renders:'];
+  for (const r of reports) {
+    const cause = r.causes[0] || '?';
+    lines.push(
+      `  ${pad(r.displayName, 20)} ${r.renderCount} renders — ${cause}`,
+    );
+  }
+  return lines.join('\n');
+}
+
+export function formatTimeline(entries: TimelineEntry[]): string {
+  if (entries.length === 0) return 'No profiling data';
+
+  const lines: string[] = ['Commit timeline:'];
+  for (const e of entries) {
+    lines.push(
+      `  #${e.index}  ${e.duration.toFixed(1)}ms  ${e.componentCount} components`,
+    );
+  }
+  return lines.join('\n');
+}
+
+export function formatCommitDetail(detail: CommitDetail): string {
+  const lines: string[] = [];
+  lines.push(`Commit #${detail.index}  ${detail.duration.toFixed(1)}ms  ${detail.totalComponents} components`);
+  lines.push('');
+  for (const c of detail.components) {
+    const causes = c.causes.length > 0 ? c.causes.join(', ') : '?';
+    lines.push(`  ${pad(c.displayName, 24)} self:${c.selfDuration.toFixed(1)}ms  total:${c.actualDuration.toFixed(1)}ms  ${causes}`);
+  }
+  const hidden = detail.totalComponents - detail.components.length;
+  if (hidden > 0) {
+    lines.push(`  ... ${hidden} more (use --limit to show more)`);
+  }
+  return lines.join('\n');
+}
+
+// ── Helpers ──
+
+function formatValue(obj: unknown): string {
+  try {
+    return JSON.stringify(obj, replacer, 0) || 'undefined';
+  } catch {
+    return String(obj);
+  }
+}
+
+function formatCompactValue(val: unknown): string | undefined {
+  if (val === undefined) return undefined;
+  if (val === null) return 'null';
+  if (typeof val === 'function') return 'ƒ';
+  if (typeof val === 'string') return `"${val}"`;
+  if (typeof val === 'number' || typeof val === 'boolean') return String(val);
+  try {
+    const s = JSON.stringify(val, replacer, 0);
+    if (s && s.length > 60) return s.slice(0, 57) + '...';
+    return s || String(val);
+  } catch {
+    return String(val);
+  }
+}
+
+function replacer(_key: string, value: unknown): unknown {
+  if (typeof value === 'function') return 'ƒ';
+  return value;
+}
+
+function pad(s: string, len: number): string {
+  return s.length >= len ? s : s + ' '.repeat(len - s.length);
+}

package/src/profiler.ts

@@ -0,0 +1,356 @@
+import type {
+  ProfilingSession,
+  ProfilingCommit,
+  ChangeDescription,
+  ComponentRenderReport,
+  RenderCause,
+} from './types.js';
+import type { ComponentTree } from './component-tree.js';
+
+export interface ProfileSummary {
+  name: string;
+  duration: number;
+  commitCount: number;
+  componentRenderCounts: { id: number; displayName: string; count: number }[];
+}
+
+export interface TimelineEntry {
+  index: number;
+  timestamp: number;
+  duration: number;
+  componentCount: number;
+}
+
+export interface CommitDetail {
+  index: number;
+  timestamp: number;
+  duration: number;
+  components: Array<{
+    id: number;
+    displayName: string;
+    actualDuration: number;
+    selfDuration: number;
+    causes: RenderCause[];
+  }>;
+  totalComponents: number;
+}
+
+export class Profiler {
+  private session: ProfilingSession | null = null;
+  /** Display names captured during profiling (survives unmounts) */
+  private displayNames = new Map<number, string>();
+
+  isActive(): boolean {
+    return this.session !== null && this.session.stoppedAt === null;
+  }
+
+  start(name?: string): void {
+    this.displayNames.clear();
+    this.session = {
+      name: name || `session-${Date.now()}`,
+      startedAt: Date.now(),
+      stoppedAt: null,
+      commits: [],
+    };
+  }
+
+  /** Cache a component's display name (call during profiling to survive unmounts) */
+  trackComponent(id: number, displayName: string): void {
+    this.displayNames.set(id, displayName);
+  }
+
+  stop(tree?: ComponentTree): ProfileSummary | null {
+    if (!this.session) return null;
+    this.session.stoppedAt = Date.now();
+
+    const duration = this.session.stoppedAt - this.session.startedAt;
+
+    // Count renders per component
+    const renderCounts = new Map<number, number>();
+    for (const commit of this.session.commits) {
+      for (const [id] of commit.fiberActualDurations) {
+        renderCounts.set(id, (renderCounts.get(id) || 0) + 1);
+      }
+    }
+
+    const componentRenderCounts = Array.from(renderCounts.entries())
+      .map(([id, count]) => ({
+        id,
+        displayName: tree?.getNode(id)?.displayName || this.displayNames.get(id) || '',
+        count,
+      }))
+      .sort((a, b) => b.count - a.count);
+
+    return {
+      name: this.session.name,
+      duration,
+      commitCount: this.session.commits.length,
+      componentRenderCounts,
+    };
+  }
+
+  /**
+   * Process profiling data sent from React DevTools.
+   *
+   * The data format varies between React versions. We handle the common
+   * format where each commit contains:
+   * - commitTime
+   * - duration
+   * - fiberActualDurations: [id, duration, ...]
+   * - fiberSelfDurations: [id, duration, ...]
+   * - changeDescriptions: Map<id, description>
+   */
+  processProfilingData(payload: unknown): void {
+    if (!this.session || this.session.stoppedAt !== null) return;
+
+    const data = payload as {
+      dataForRoots?: Array<{
+        commitData?: Array<{
+          changeDescriptions?: Array<[number, unknown]> | Map<number, unknown>;
+          duration?: number;
+          fiberActualDurations?: Array<[number, number]> | number[];
+          fiberSelfDurations?: Array<[number, number]> | number[];
+          timestamp?: number;
+        }>;
+        operations?: unknown[];
+      }>;
+      // Alternative flat format
+      commitData?: Array<{
+        changeDescriptions?: Array<[number, unknown]> | Map<number, unknown>;
+        duration?: number;
+        fiberActualDurations?: Array<[number, number]> | number[];
+        fiberSelfDurations?: Array<[number, number]> | number[];
+        timestamp?: number;
+      }>;
+    };
+
+    // Handle nested format (dataForRoots)
+    const roots = data?.dataForRoots;
+    if (roots) {
+      for (const root of roots) {
+        if (root.commitData) {
+          for (const commitData of root.commitData) {
+            this.processCommitData(commitData);
+          }
+        }
+      }
+      return;
+    }
+
+    // Handle flat format
+    if (data?.commitData) {
+      for (const commitData of data.commitData) {
+        this.processCommitData(commitData);
+      }
+    }
+  }
+
+  private processCommitData(commitData: {
+    changeDescriptions?: Array<[number, unknown]> | Map<number, unknown>;
+    duration?: number;
+    fiberActualDurations?: Array<[number, number]> | number[];
+    fiberSelfDurations?: Array<[number, number]> | number[];
+    timestamp?: number;
+  }): void {
+    const commit: ProfilingCommit = {
+      timestamp: commitData.timestamp || Date.now(),
+      duration: commitData.duration || 0,
+      fiberActualDurations: new Map(),
+      fiberSelfDurations: new Map(),
+      changeDescriptions: new Map(),
+    };
+
+    // Parse fiber durations (can be [id, duration, id, duration, ...] or [[id, duration], ...])
+    if (commitData.fiberActualDurations) {
+      parseDurations(commitData.fiberActualDurations, commit.fiberActualDurations);
+    }
+    if (commitData.fiberSelfDurations) {
+      parseDurations(commitData.fiberSelfDurations, commit.fiberSelfDurations);
+    }
+
+    // Parse change descriptions
+    if (commitData.changeDescriptions) {
+      const entries =
+        commitData.changeDescriptions instanceof Map
+          ? commitData.changeDescriptions.entries()
+          : commitData.changeDescriptions[Symbol.iterator]();
+      for (const [id, desc] of entries) {
+        const d = desc as {
+          didHooksChange?: boolean;
+          isFirstMount?: boolean;
+          props?: string[] | null;
+          state?: string[] | null;
+          hooks?: number[] | null;
+        };
+        commit.changeDescriptions.set(id as number, {
+          didHooksChange: d.didHooksChange || false,
+          isFirstMount: d.isFirstMount || false,
+          props: d.props || null,
+          state: d.state || null,
+          hooks: d.hooks || null,
+        });
+      }
+    }
+
+    this.session!.commits.push(commit);
+  }
+
+  getReport(
+    componentId: number,
+    tree: ComponentTree,
+  ): ComponentRenderReport | null {
+    if (!this.session) return null;
+
+    const node = tree.getNode(componentId);
+    let renderCount = 0;
+    let totalDuration = 0;
+    let maxDuration = 0;
+    const causeSet = new Set<RenderCause>();
+
+    for (const commit of this.session.commits) {
+      const duration = commit.fiberActualDurations.get(componentId);
+      if (duration !== undefined) {
+        renderCount++;
+        totalDuration += duration;
+        if (duration > maxDuration) maxDuration = duration;
+
+        const desc = commit.changeDescriptions.get(componentId);
+        if (desc) {
+          for (const cause of describeCauses(desc)) {
+            causeSet.add(cause);
+          }
+        }
+      }
+    }
+
+    if (renderCount === 0) return null;
+
+    return {
+      id: componentId,
+      displayName: node?.displayName || this.displayNames.get(componentId) || `Component#${componentId}`,
+      renderCount,
+      totalDuration,
+      avgDuration: totalDuration / renderCount,
+      maxDuration,
+      causes: Array.from(causeSet),
+    };
+  }
+
+  getSlowest(
+    tree: ComponentTree,
+    limit = 10,
+  ): ComponentRenderReport[] {
+    return this.getAllReports(tree)
+      .sort((a, b) => b.avgDuration - a.avgDuration)
+      .slice(0, limit);
+  }
+
+  getMostRerenders(
+    tree: ComponentTree,
+    limit = 10,
+  ): ComponentRenderReport[] {
+    return this.getAllReports(tree)
+      .sort((a, b) => b.renderCount - a.renderCount)
+      .slice(0, limit);
+  }
+
+  getCommitDetails(index: number, tree: ComponentTree, limit = 10): CommitDetail | null {
+    if (!this.session) return null;
+    if (index < 0 || index >= this.session.commits.length) return null;
+
+    const commit = this.session.commits[index];
+    const components: CommitDetail['components'] = [];
+
+    for (const [id, actualDuration] of commit.fiberActualDurations) {
+      const selfDuration = commit.fiberSelfDurations.get(id) || 0;
+      const desc = commit.changeDescriptions.get(id);
+      components.push({
+        id,
+        displayName: tree.getNode(id)?.displayName || this.displayNames.get(id) || `Component#${id}`,
+        actualDuration,
+        selfDuration,
+        causes: desc ? describeCauses(desc) : [],
+      });
+    }
+
+    components.sort((a, b) => b.selfDuration - a.selfDuration);
+
+    const totalCount = components.length;
+
+    return {
+      index,
+      timestamp: commit.timestamp,
+      duration: commit.duration,
+      components: limit > 0 ? components.slice(0, limit) : components,
+      totalComponents: totalCount,
+    };
+  }
+
+  getTimeline(limit?: number): TimelineEntry[] {
+    if (!this.session) return [];
+
+    const entries = this.session.commits.map((commit, index) => ({
+      index,
+      timestamp: commit.timestamp,
+      duration: commit.duration,
+      componentCount: commit.fiberActualDurations.size,
+    }));
+
+    if (limit) return entries.slice(0, limit);
+    return entries;
+  }
+
+  private getAllReports(tree: ComponentTree): ComponentRenderReport[] {
+    if (!this.session) return [];
+
+    // Collect all component IDs that appear in profiling data
+    const componentIds = new Set<number>();
+    for (const commit of this.session.commits) {
+      for (const id of commit.fiberActualDurations.keys()) {
+        componentIds.add(id);
+      }
+    }
+
+    const reports: ComponentRenderReport[] = [];
+    for (const id of componentIds) {
+      const report = this.getReport(id, tree);
+      if (report) reports.push(report);
+    }
+    return reports;
+  }
+}
+
+function parseDurations(
+  raw: Array<[number, number]> | number[],
+  target: Map<number, number>,
+): void {
+  if (raw.length === 0) return;
+
+  // Check if it's array of tuples or flat array
+  if (Array.isArray(raw[0])) {
+    // [[id, duration], ...]
+    for (const [id, duration] of raw as Array<[number, number]>) {
+      target.set(id, duration);
+    }
+  } else {
+    // [id, duration, id, duration, ...]
+    const flat = raw as number[];
+    for (let i = 0; i < flat.length; i += 2) {
+      target.set(flat[i], flat[i + 1]);
+    }
+  }
+}
+
+function describeCauses(desc: ChangeDescription): RenderCause[] {
+  const causes: RenderCause[] = [];
+  if (desc.isFirstMount) {
+    causes.push('first-mount');
+    return causes;
+  }
+  if (desc.props && desc.props.length > 0) causes.push('props-changed');
+  if (desc.state && desc.state.length > 0) causes.push('state-changed');
+  if (desc.didHooksChange) causes.push('hooks-changed');
+  // If no specific cause found, it was likely parent-triggered
+  if (causes.length === 0) causes.push('parent-rendered');
+  return causes;
+}