Skip to content

Chrome DevTools for coding agents

13.3 KB
Raw Blame
/**
 * @license
 * Copyright 2026 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */

import type {
  HeapSnapshotAggregate,
  HeapSnapshotClassDiff,
  HeapSnapshotClassDiffTotals,
  HeapSnapshotDiffObject,
  DuplicateStringGroup,
} from '../processors/HeapSnapshotManager.js';
import {DevTools} from '../third_party/index.js';
import type {ByteSizeRange} from '../utils/bytes.js';
import {truncateText} from '../utils/text.js';

const {formatBytesToKb} = DevTools.I18n.ByteUtilities;

export const MAX_NAME_LENGTH = 100;

export interface HeapSnapshotFormatOptions {
  /**
   * Values longer than this are truncated. Defaults to `MAX_NAME_LENGTH`. Pass
   * a large value to get untruncated values.
   */
  maxNameLength?: number;
}

/**
 * Renders a name for single-line output: the name is truncated to
 * `maxNameLength` and line breaks are always escaped.
 */
export function formatName(
  name: string,
  options: HeapSnapshotFormatOptions,
): string {
  return truncateValue(name, options.maxNameLength)
    .replaceAll('\r', '\\r')
    .replaceAll('\n', '\\n');
}

/**
 * Truncates `value` to `maxLength`, appending an ellipsis if it was cut off.
 */
function truncateValue(value: string, maxLength = MAX_NAME_LENGTH): string {
  return truncateText(value, maxLength);
}

export interface ContextAnalysisReport {
  contexts: readonly ScopedContext[];
  scriptsWithoutScopes: readonly DevTools.HeapSnapshotModel.HeapSnapshotModel.ScriptWithoutScopes[];
}

/** A context paired with the scope that declares it. */
export interface ScopedContext {
  scope: DevTools.HeapSnapshotModel.HeapSnapshotModel.ScopeAnalysis;
  context: DevTools.HeapSnapshotModel.HeapSnapshotModel.ContextAnalysis;
}

export interface ContextFilterOptions {
  /** Inclusive dead-field retained-size score range a context must fall into. */
  retainedSize?: ByteSizeRange;
  /** Restricts the result to contexts declared by this scope. */
  scopeInfoNodeId?: number;
}

/**
 * Flattens the analysis into the contexts matching `options`, ranked descending
 * by their dead-field retained-size score across all scopes.
 */
export function collectRankedContexts(
  analysis: DevTools.HeapSnapshotModel.HeapSnapshotModel.ContextAnalysisResult,
  options: ContextFilterOptions = {},
): ScopedContext[] {
  const {min = 0, max} = options.retainedSize ?? {};
  const contexts: ScopedContext[] = [];
  for (const scope of analysis.scopes) {
    if (
      options.scopeInfoNodeId !== undefined &&
      scope.scopeInfoNodeId !== options.scopeInfoNodeId
    ) {
      continue;
    }
    for (const context of scope.contexts) {
      const score = context.deadFieldsRetainedSizeSum;
      if (score < min || (max !== undefined && score > max)) {
        continue;
      }
      contexts.push({scope, context});
    }
  }
  contexts.sort(
    (left, right) =>
      right.context.deadFieldsRetainedSizeSum -
      left.context.deadFieldsRetainedSizeSum,
  );
  return contexts;
}

export function isNodeLike(
  item: unknown,
): item is DevTools.HeapSnapshotModel.HeapSnapshotModel.Node {
  return (
    typeof item === 'object' && item !== null && 'id' in item && 'name' in item
  );
}

export function isEdgeLike(
  item: unknown,
): item is DevTools.HeapSnapshotModel.HeapSnapshotModel.Edge {
  return (
    typeof item === 'object' &&
    item !== null &&
    'name' in item &&
    'node' in item &&
    'type' in item &&
    typeof item.node === 'object' &&
    item.node !== null &&
    'id' in item.node &&
    'name' in item.node
  );
}

export class HeapSnapshotFormatter {
  static formatNodes(
    items: ReadonlyArray<
      | DevTools.HeapSnapshotModel.HeapSnapshotModel.Node
      | DevTools.HeapSnapshotModel.HeapSnapshotModel.Edge
    >,
    options: HeapSnapshotFormatOptions,
  ): string {
    const lines: string[] = [];

    if (items.length > 0) {
      const firstItem = items[0];
      if (isNodeLike(firstItem)) {
        lines.push('nodeId,nodeName,type,distance,selfSize,retainedSize');
      } else if (isEdgeLike(firstItem)) {
        lines.push('name,type,nodeId,nodeName,selfSize,retainedSize');
      }
    }

    for (const item of items) {
      if (isNodeLike(item)) {
        lines.push(
          `${item.id},${formatName(item.name, options)},${item.type},${item.distance},${formatBytesToKb(item.selfSize)},${formatBytesToKb(item.retainedSize)}`,
        );
      } else if (isEdgeLike(item)) {
        lines.push(
          `${formatName(item.name, options)},${item.type},${item.node.id},${formatName(item.node.name, options)},${formatBytesToKb(item.node.selfSize)},${formatBytesToKb(item.node.retainedSize)}`,
        );
      }
    }

    return lines.join('\n');
  }

  static formatRetainingPaths(
    retainingPaths: readonly DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainingEdge[],
    options: HeapSnapshotFormatOptions,
  ): string {
    const lines: string[] = [];

    function formatEdge(
      edge: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainingEdge,
      depth: number,
    ): void {
      const indent = '  '.repeat(depth);
      lines.push(
        `${indent}<- @${edge.nodeId} ${formatName(edge.nodeName, options)} via ${edge.edgeType} ${formatName(edge.edgeName, options)} (distance: ${edge.distance})`,
      );
      for (const child of edge.children) {
        formatEdge(child, depth + 1);
      }
    }

    for (const path of retainingPaths) {
      formatEdge(path, 0);
    }

    return lines.join('\n');
  }

  static formatDominators(
    dominators: DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain,
    options: HeapSnapshotFormatOptions,
  ): string {
    const lines: string[] = [];
    lines.push('nodeId,nodeName,selfSize,retainedSize');
    for (const node of dominators) {
      lines.push(
        `${node.nodeId},${formatName(node.nodeName, options)},${formatBytesToKb(node.selfSize)},${formatBytesToKb(node.retainedSize)}`,
      );
    }
    return lines.join('\n');
  }

  static formatDuplicateStrings(
    groups: readonly DuplicateStringGroup[],
    options: HeapSnapshotFormatOptions,
  ): string {
    const lines: string[] = [];
    lines.push('value,count,totalSelfSize,totalRetainedSize,truncated,nodeIds');
    for (const group of groups) {
      const nodeIds = group.nodes.map(n => `@${n.id}`).join(' ');
      const truncated = group.truncated ?? false;
      const displayValue = truncateValue(group.value, options.maxNameLength);
      lines.push(
        `${JSON.stringify(displayValue)},${group.count},${formatBytesToKb(group.totalSelfSize)},${formatBytesToKb(group.totalRetainedSize)},${truncated},${nodeIds}`,
      );
    }
    return lines.join('\n');
  }

  static formatNativeContextSizes(
    sizes: DevTools.HeapSnapshotModel.HeapSnapshotModel.NativeContextSizes,
    options: HeapSnapshotFormatOptions,
  ): string {
    const lines: string[] = [];
    lines.push('nodeId,nodeName,selfSize,retainedSize,attributedSize');
    const sortedContexts = [...sizes.nativeContexts].sort(
      (a, b) => b.attributedSize - a.attributedSize,
    );
    for (const nc of sortedContexts) {
      lines.push(
        `${nc.nodeId},${formatName(nc.nodeName, options)},${formatBytesToKb(nc.selfSize)},${formatBytesToKb(nc.retainedSize)},${formatBytesToKb(nc.attributedSize)}`,
      );
    }
    lines.push(`Shared Size: ${formatBytesToKb(sizes.sharedSize)}`);
    lines.push(
      `Unattributed Size: ${formatBytesToKb(sizes.noAttributionSize)}`,
    );
    return lines.join('\n');
  }

  static formatRetainedByContextSummary(
    summary: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary,
  ): string {
    const lines: string[] = [];
    lines.push(`Context count: ${summary.contextCount}`);
    lines.push(
      `Retained by context size: ${formatBytesToKb(summary.retainedByContextSize)} (${summary.retainedByContextCount} objects)`,
    );
    lines.push(
      `Not retained by context size: ${formatBytesToKb(summary.notRetainedByContextSize)} (${summary.notRetainedByContextCount} objects)`,
    );
    lines.push(`Total size: ${formatBytesToKb(summary.totalSize)}`);
    return lines.join('\n');
  }

  static formatAggregates(
    aggregates: readonly HeapSnapshotAggregate[],
    options: HeapSnapshotFormatOptions,
  ): string {
    const lines: string[] = [];
    lines.push('id,className,count,selfSize,retainedSize');

    for (const info of aggregates) {
      lines.push(
        `${info.id},${formatName(info.className, options)},${info.count},${formatBytesToKb(info.selfSize)},${formatBytesToKb(info.retainedSize)}`,
      );
    }

    return lines.join('\n');
  }

  static formatDiffSummary(
    diffs: readonly HeapSnapshotClassDiff[],
    options: HeapSnapshotFormatOptions,
  ): string {
    const lines: string[] = [];
    lines.push(
      'index,className,addedCount,removedCount,countDelta,addedSize,removedSize,sizeDelta',
    );

    for (const diff of diffs) {
      lines.push(
        `${diff.index},${formatName(diff.className, options)},${diff.addedCount},${diff.removedCount},${diff.countDelta},${formatBytesToKb(diff.addedSize)},${formatBytesToKb(diff.removedSize)},${formatBytesToKb(diff.sizeDelta)}`,
      );
    }

    return lines.join('\n');
  }

  static formatDiffTotals(totals: HeapSnapshotClassDiffTotals): string {
    return `Total: ${formatDiffCounts(totals)}`;
  }

  static formatDetailedClassDiffHeader(
    diff: HeapSnapshotClassDiff,
    options: HeapSnapshotFormatOptions,
  ): string {
    return `${formatName(diff.className, options)}: ${formatDiffCounts(diff)}`;
  }

  static formatDetailedClassDiffObjects(
    objects: readonly HeapSnapshotDiffObject[],
  ): string {
    const lines = ['Objects:'];
    for (const object of objects) {
      const sign = object.change === 'added' ? '+' : '-';
      lines.push(
        `  ${sign} @${object.id} (self_size: ${formatBytesToKb(object.selfSize)})`,
      );
    }
    return lines.join('\n');
  }

  static formatObjectInfo(
    info: DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo,
    options: HeapSnapshotFormatOptions,
  ): string {
    const lines = [
      `id: @${info.id}`,
      `name: ${formatName(info.name, options)}`,
      `type: ${info.type}`,
      `detachedness: ${formatDOMLinkState(info.detachedness)}`,
      `selfSize: ${formatBytesToKb(info.selfSize)}`,
      `retainedSize: ${formatBytesToKb(info.retainedSize)}`,
      `distance: ${info.distance}`,
      `edgeCount: ${info.edgeCount}`,
      `retainerCount: ${info.retainerCount}`,
    ];
    return lines.join('\n');
  }

  static formatContextAnalysis(
    report: ContextAnalysisReport,
    options: HeapSnapshotFormatOptions,
  ): string {
    const lines: string[] = [];

    if (report.contexts.length === 0) {
      lines.push('No live contexts with dead fields were found.');
    }

    for (const {scope, context} of report.contexts) {
      if (lines.length > 0) {
        lines.push('');
      }
      lines.push(
        `#### Context @${context.contextNodeId} in \`${formatScopeName(scope, options)}\` — ${formatBytesToKb(context.deadFieldsRetainedSizeSum)}`,
        `Script @${scope.scriptNodeId}, ScopeInfo @${scope.scopeInfoNodeId}, offsets ${scope.scopeStart}-${scope.scopeEnd}, ${formatCount(scope.contextFieldCount, 'context field')}`,
      );
      for (const field of context.deadFields) {
        lines.push(
          `- \`${formatName(field.name, options)}\` (${formatName(field.valueName, options)} @${field.valueNodeId}) — ${formatBytesToKb(field.retainedSize)}`,
        );
      }
    }

    if (report.scriptsWithoutScopes.length > 0) {
      lines.push('', 'Scripts without scope metadata could not be analyzed:');
      for (const script of report.scriptsWithoutScopes) {
        const scriptName = script.scriptName
          ? formatName(script.scriptName, options)
          : `script @${script.scriptNodeId}`;
        lines.push(
          `- \`${scriptName}\` (@${script.scriptNodeId}) — ${formatCount(script.contextCount, 'context')}`,
        );
      }
    }

    return lines.join('\n');
  }
}

function formatCount(count: number, singular: string): string {
  return `${count} ${singular}${count === 1 ? '' : 's'}`;
}

function formatScopeName(
  scope: DevTools.HeapSnapshotModel.HeapSnapshotModel.ScopeAnalysis,
  options: HeapSnapshotFormatOptions,
): string {
  const scriptName = scope.scriptName
    ? formatName(scope.scriptName, options)
    : `script @${scope.scriptNodeId}`;
  return scope.scopeName
    ? `${formatName(scope.scopeName, options)} (${scriptName})`
    : scriptName;
}

function formatDOMLinkState(
  state: DevTools.HeapSnapshotModel.HeapSnapshotModel.DOMLinkState,
): string {
  switch (state) {
    case DevTools.HeapSnapshotModel.HeapSnapshotModel.DOMLinkState.ATTACHED:
      return 'attached';
    case DevTools.HeapSnapshotModel.HeapSnapshotModel.DOMLinkState.DETACHED:
      return 'detached';
    case DevTools.HeapSnapshotModel.HeapSnapshotModel.DOMLinkState.UNKNOWN:
    default:
      return 'unknown';
  }
}

function formatSignedCount(n: number): string {
  return n > 0 ? `+${n}` : `${n}`;
}

function formatSignedSize(bytes: number): string {
  const formatted = formatBytesToKb(bytes);
  return bytes > 0 ? `+${formatted}` : formatted;
}

function formatDiffCounts(counts: HeapSnapshotClassDiffTotals): string {
  return `# new: ${counts.addedCount}, # deleted: ${counts.removedCount}, # delta: ${formatSignedCount(counts.countDelta)}, alloc size: ${formatSignedSize(counts.addedSize)}, freed size: ${formatSignedSize(counts.removedSize)}, size delta: ${formatSignedSize(counts.sizeDelta)}`;
}