Skip to content

Chrome DevTools for coding agents

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

import fsSync from 'node:fs';
import path from 'node:path';

import {DevTools} from '../third_party/index.js';
import {createIdGenerator} from '../utils/id.js';
import type {TaskQueue, TaskRunner} from '../utils/TaskRunner.js';

export interface HeapSnapshotAggregate {
  id: number;
  className: string;
  count: number;
  selfSize: number;
  retainedSize: number;
}

export interface HeapSnapshotAggregateData {
  aggregates: HeapSnapshotAggregate[];
  objectCount: number;
  totalSelfSize: number;
}

export interface HeapSnapshotDiff {
  classDiffs: HeapSnapshotClassDiff[];
  totals: HeapSnapshotClassDiffTotals;
}

export interface HeapSnapshotClassDiff {
  /** Position in the full sorted diff list. Use as `classIndex`. */
  index: number;
  className: string;
  addedCount: number;
  removedCount: number;
  countDelta: number;
  addedSize: number;
  removedSize: number;
  sizeDelta: number;
}

export interface HeapSnapshotDetailedClassDiff {
  classDiff: HeapSnapshotClassDiff;
  objects: readonly HeapSnapshotDiffObject[];
}

export interface HeapSnapshotDiffObject {
  id: number;
  selfSize: number;
  change: 'added' | 'deleted';
}

export interface HeapSnapshotClassDiffTotals {
  addedCount: number;
  removedCount: number;
  countDelta: number;
  addedSize: number;
  removedSize: number;
  sizeDelta: number;
}

export type DuplicateStringGroup =
  DevTools.HeapSnapshotModel.HeapSnapshotModel.DuplicateStringGroup;

export type HeapQueryOptions =
  DevTools.HeapSnapshotModel.HeapSnapshotModel.HeapQueryOptions;

export type HeapEdgesQueryOptions =
  DevTools.HeapSnapshotModel.HeapSnapshotModel.HeapEdgesQueryOptions;

function toClassDiff(
  index: number,
  rawDiff: DevTools.HeapSnapshotModel.HeapSnapshotModel.Diff,
): HeapSnapshotClassDiff {
  return {
    index,
    className: rawDiff.name,
    addedCount: rawDiff.addedCount,
    removedCount: rawDiff.removedCount,
    countDelta: rawDiff.countDelta,
    addedSize: rawDiff.addedSize,
    removedSize: rawDiff.removedSize,
    sizeDelta: rawDiff.sizeDelta,
  };
}

export class HeapSnapshot {
  proxy: DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotProxy;
  worker: DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotWorkerProxy;
  // 1-indexed array where index is the class ID.
  #idToClassKey: string[] = [''];
  #classKeyToId = new Map<string, number>();

  constructor(
    proxy: DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotProxy,
    worker: DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotWorkerProxy,
    aggregates: Record<
      string,
      DevTools.HeapSnapshotModel.HeapSnapshotModel.AggregatedInfo
    >,
  ) {
    this.proxy = proxy;
    this.worker = worker;

    for (const key of Object.keys(aggregates)) {
      const id = this.#idToClassKey.length;
      this.#classKeyToId.set(key, id);
      this.#idToClassKey.push(key);
    }
  }

  resolveIdFromClassKey(classKey: string): number | undefined {
    return this.#classKeyToId.get(classKey);
  }

  resolveClassKeyFromId(id: number): string | undefined {
    return this.#idToClassKey[id];
  }
}

const VALID_EXTENSIONS: readonly string[] = ['.heapsnapshot', '.heaptimeline'];

function hasValidHeapSnapshotExtension(filePath: string): boolean {
  return VALID_EXTENSIONS.some(ext => filePath.endsWith(ext));
}

export class HeapSnapshotManager {
  #snapshotIdGenerator = createIdGenerator();
  #snapshots = new Map<string, Promise<HeapSnapshot>>();
  /**
   * Queue for all heap snapshot work, with one child queue per absolute file
   * path. A read of one file holds the file queue, so reads of different
   * files run at the same time. A read of several files holds this queue.
   * `disposeSnapshot()` holds the file queue, so it waits for in-flight
   * reads of the file, and a read that starts after it loads the file again.
   */
  #taskQueue: TaskQueue;
  #taskRunner: TaskRunner;
  #fileTaskQueues = new Map<string, TaskQueue>();

  constructor(taskRunner: TaskRunner) {
    this.#taskRunner = taskRunner;
    this.#taskQueue = taskRunner.createQueue();
  }

  /**
   * Holds the queue of `filePath`, or the heap queue without a path, until
   * the guard is disposed.
   */
  async #scheduleTask(filePath?: string): Promise<Disposable> {
    if (filePath === undefined) {
      return await this.#taskQueue.scheduleTask();
    }
    const absolutePath = path.resolve(filePath);
    let queue = this.#fileTaskQueues.get(absolutePath);
    if (!queue) {
      queue = this.#taskRunner.createQueue(this.#taskQueue);
      this.#fileTaskQueues.set(absolutePath, queue);
    }
    return await queue.scheduleTask();
  }

  async getSnapshot(filePath: string): Promise<HeapSnapshot> {
    if (!hasValidHeapSnapshotExtension(filePath)) {
      throw new Error(
        `File ${filePath} must have a .heapsnapshot or .heaptimeline extension.`,
      );
    }
    const absolutePath = path.resolve(filePath);
    let cached = this.#snapshots.get(absolutePath);
    if (!cached) {
      const uid = this.#snapshotIdGenerator();
      cached = this.#loadSnapshot(absolutePath, uid);
      this.#snapshots.set(absolutePath, cached);
    }

    return await cached;
  }

  async #applyNodeFilter(
    snapshot: DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotProxy,
    filter: DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter,
    filterName?: string,
    objectId?: number,
  ): Promise<void> {
    if (filterName === 'attributedToSpecificNativeContext') {
      if (objectId === undefined) {
        throw new Error(
          'objectId is required when filterName is attributedToSpecificNativeContext',
        );
      }
      const nodeIndex = await snapshot.nodeIndexForId(objectId);
      if (nodeIndex === undefined) {
        throw new Error(`Node with ID ${objectId} not found`);
      }
      filter.filterName = `nativeContext_${nodeIndex}`;
    } else if (filterName) {
      filter.filterName = filterName;
    }
  }

  async getAggregates(
    filePath: string,
    filterName?: string,
    objectId?: number,
  ): Promise<HeapSnapshotAggregateData> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    const filter =
      new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
    await this.#applyNodeFilter(snapshot.proxy, filter, filterName, objectId);
    const rawAggregates = await snapshot.proxy.aggregatesWithFilter(filter);
    let objectCount = 0;
    let totalSelfSize = 0;
    const aggregates: HeapSnapshotAggregate[] = [];

    for (const [key, aggregate] of Object.entries(rawAggregates)) {
      const id = snapshot.resolveIdFromClassKey(key);
      if (id === undefined) {
        throw new Error(`No class ID found for class key ${key}`);
      }
      objectCount += aggregate.count;
      totalSelfSize += aggregate.self;
      aggregates.push({
        id,
        className: aggregate.name,
        count: aggregate.count,
        selfSize: aggregate.self,
        retainedSize: aggregate.maxRet,
      });
    }

    aggregates.sort((a, b) => b.retainedSize - a.retainedSize);

    return {
      aggregates,
      objectCount,
      totalSelfSize,
    };
  }

  async getStats(
    filePath: string,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.Statistics> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    return await snapshot.proxy.getStatistics();
  }

  async getStaticData(
    filePath: string,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.StaticData | null> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    return snapshot.proxy.staticData;
  }

  async getNativeContextSizes(
    filePath: string,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.NativeContextSizes> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    return await snapshot.proxy.getNativeContextSizes();
  }

  async getRetainedByContextSummary(
    filePath: string,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    return await snapshot.proxy.getRetainedByContextSummary();
  }

  async getNodesById(
    filePath: string,
    id: number,
    filterName?: string,
    objectId?: number,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    const filter =
      new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
    await this.#applyNodeFilter(snapshot.proxy, filter, filterName, objectId);
    const className = snapshot.resolveClassKeyFromId(id);
    if (!className) {
      throw new Error(`Class with ID ${id} not found in heap snapshot`);
    }
    const provider = snapshot.proxy.createNodesProviderForClass(
      className,
      filter,
    );

    return await provider.serializeItemsRange(0, Infinity);
  }

  async getRetainers(
    filePath: string,
    nodeId: number,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    const nodeIndex = await snapshot.proxy.nodeIndexForId(nodeId);
    if (nodeIndex === undefined) {
      throw new Error(`Node with ID ${nodeId} not found`);
    }
    const provider = snapshot.proxy.createRetainingEdgesProvider(nodeIndex);
    return await provider.serializeItemsRange(0, Infinity);
  }

  async getObjectInfo(
    filePath: string,
    nodeId: number,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    const nodeIndex = await snapshot.proxy.nodeIndexForId(nodeId);
    if (nodeIndex === undefined) {
      throw new Error(`Node with ID ${nodeId} not found`);
    }
    return await snapshot.proxy.getObjectInfo(nodeIndex);
  }

  async analyzeContexts(
    filePath: string,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ContextAnalysisResult> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    return await snapshot.proxy.analyzeContexts();
  }

  async getRetainingPaths(
    filePath: string,
    nodeId: number,
    maxDepth?: number,
    maxNodes?: number,
    maxSiblings?: number,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainingPaths> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    const nodeIndex = await snapshot.proxy.nodeIndexForId(nodeId);
    if (nodeIndex === undefined) {
      throw new Error(`Node with ID ${nodeId} not found`);
    }
    return await snapshot.proxy.getRetainingPaths(
      nodeIndex,
      maxDepth,
      maxNodes,
      maxSiblings,
    );
  }

  async getDominatorsOf(
    filePath: string,
    nodeId: number,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    const nodeIndex = await snapshot.proxy.nodeIndexForId(nodeId);
    if (nodeIndex === undefined) {
      throw new Error(`Node with ID ${nodeId} not found`);
    }
    return await snapshot.proxy.getDominatorsOf(nodeIndex);
  }

  async getEdges(
    filePath: string,
    nodeId: number,
    options?: HeapEdgesQueryOptions,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    const nodeIndex = await snapshot.proxy.nodeIndexForId(nodeId);
    if (nodeIndex === undefined) {
      throw new Error(`Node with ID ${nodeId} not found`);
    }
    const provider = snapshot.proxy.createEdgesProvider(nodeIndex, options);
    return await provider.serializeItemsRange(0, Infinity);
  }

  async getClassDiffs(
    baseFilePath: string,
    currentFilePath: string,
  ): Promise<HeapSnapshotDiff> {
    const rawDiffs = await this.#getSortedRawClassDiffs(
      baseFilePath,
      currentFilePath,
    );
    const classDiffs: HeapSnapshotClassDiff[] = [];
    const totals: HeapSnapshotClassDiffTotals = {
      addedCount: 0,
      removedCount: 0,
      countDelta: 0,
      addedSize: 0,
      removedSize: 0,
      sizeDelta: 0,
    };
    for (const [index, rawDiff] of rawDiffs.entries()) {
      classDiffs.push(toClassDiff(index, rawDiff));
      totals.addedCount += rawDiff.addedCount;
      totals.removedCount += rawDiff.removedCount;
      totals.countDelta += rawDiff.countDelta;
      totals.addedSize += rawDiff.addedSize;
      totals.removedSize += rawDiff.removedSize;
      totals.sizeDelta += rawDiff.sizeDelta;
    }
    return {classDiffs, totals};
  }

  async getDetailedClassDiff(
    baseFilePath: string,
    currentFilePath: string,
    classIndex: number,
  ): Promise<HeapSnapshotDetailedClassDiff> {
    const classDiffs = await this.#getSortedRawClassDiffs(
      baseFilePath,
      currentFilePath,
    );
    const rawDiff = classDiffs[classIndex];
    if (!rawDiff) {
      throw new Error(
        `Invalid classIndex: ${classIndex}. Total classes with changes: ${classDiffs.length}`,
      );
    }
    const objects: HeapSnapshotDiffObject[] = [];
    const addedIds = rawDiff.addedIds ?? [];
    const addedSelfSizes = rawDiff.addedSelfSizes ?? [];
    for (const [i, id] of addedIds.entries()) {
      objects.push({id, selfSize: addedSelfSizes[i], change: 'added'});
    }
    const deletedIds = rawDiff.deletedIds ?? [];
    const deletedSelfSizes = rawDiff.deletedSelfSizes ?? [];
    for (const [i, id] of deletedIds.entries()) {
      objects.push({id, selfSize: deletedSelfSizes[i], change: 'deleted'});
    }
    // Largest objects first so that the first page of paginated output shows
    // the most significant changes.
    objects.sort((a, b) => b.selfSize - a.selfSize);
    return {classDiff: toClassDiff(classIndex, rawDiff), objects};
  }

  async #getSortedRawClassDiffs(
    baseFilePath: string,
    currentFilePath: string,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.Diff[]> {
    using guard = await this.#scheduleTask();
    const [baseSnapshot, currentSnapshot] = await Promise.all([
      this.getSnapshot(baseFilePath),
      this.getSnapshot(currentFilePath),
    ]);

    const interfaceDefinitions =
      await currentSnapshot.proxy.interfaceDefinitions();
    const aggregatesForDiff =
      await baseSnapshot.proxy.aggregatesForDiff(interfaceDefinitions);
    const baseSnapshotId = baseSnapshot.proxy.uid;
    if (baseSnapshotId === undefined) {
      throw new Error('Base snapshot UID is undefined');
    }
    // DevTools calculateSnapshotDiff uses the first parameter (baseSnapshotId)
    // as a cache key. We pass the unique UID of the base snapshot.
    const rawDiffs = await currentSnapshot.proxy.calculateSnapshotDiff(
      baseSnapshotId,
      aggregatesForDiff,
    );

    // Return a filtered and sorted array here to ensure that
    // compare_heapsnapshot_summary and compare_heapsnapshot_details agree
    // on indices.
    return Object.values(rawDiffs)
      .filter(diff => diff.addedCount > 0 || diff.removedCount > 0)
      .sort((a, b) => b.sizeDelta - a.sizeDelta);
  }

  async #loadSnapshot(
    absolutePath: string,
    uid: number,
  ): Promise<HeapSnapshot> {
    const workerProxy =
      new DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotWorkerProxy(
        () => {
          /* noop */
        },
        DevTools.Common.Console.Console.instance(),
        import.meta.resolve('../third_party/devtools-heap-snapshot-worker.js'),
      );

    try {
      const {promise: snapshotPromise, resolve: resolveSnapshot} =
        Promise.withResolvers<DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotProxy>();

      const loaderProxy = workerProxy.createLoader(uid, snapshotProxy => {
        resolveSnapshot(snapshotProxy);
      });

      const fileStream = fsSync.createReadStream(absolutePath, {
        encoding: 'utf-8',
        highWaterMark: 1024 * 1024,
      });

      for await (const chunk of fileStream) {
        await loaderProxy.write(chunk);
      }

      await loaderProxy.close();

      const snapshot = await snapshotPromise;
      // Assign ids to all aggregates of this snapshot. This ensures ids are available
      // even without calling getAggregates() and deterministic (do not depend on
      // the filter used on the getAggregates() call).
      const aggregates = await snapshot.aggregatesWithFilter(
        new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter(),
      );
      return new HeapSnapshot(snapshot, workerProxy, aggregates);
    } catch (error) {
      // Remove the rejected promise from #snapshots and dispose the worker to
      // avoid leaking it on a failed load (e.g. a missing or invalid
      // .heapsnapshot path).
      this.#snapshots.delete(absolutePath);
      workerProxy.dispose();
      throw error;
    }
  }

  async getDuplicateStrings(filePath: string): Promise<DuplicateStringGroup[]> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    return await snapshot.proxy.getDuplicateStrings();
  }

  async queryObjects(
    filePath: string,
    options: HeapQueryOptions,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
    using guard = await this.#scheduleTask(filePath);
    const snapshot = await this.getSnapshot(filePath);
    const provider = snapshot.proxy.queryObjects(options);
    return await provider.serializeItemsRange(0, Infinity);
  }

  hasSnapshots(): boolean {
    return this.#snapshots.size > 0;
  }

  async disposeSnapshot(filePath: string): Promise<boolean> {
    using guard = await this.#scheduleTask(filePath);
    const absolutePath = path.resolve(filePath);
    const cached = this.#snapshots.get(absolutePath);
    if (cached) {
      this.#snapshots.delete(absolutePath);
      const {worker} = await cached;
      worker.dispose();
      return true;
    }
    return false;
  }

  dispose(): void {
    void Promise.allSettled(
      this.#snapshots.values().map(async cached => {
        const {worker} = await cached;
        worker.dispose();
      }),
    );
    this.#snapshots.clear();
  }
}