devtools-tracing 1.0.1 → 1.1.1

package/lib/front_end/models/source_map_scopes/ScopeChainModel.ts

@@ -0,0 +1,84 @@
+// Copyright 2024 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as Common from '../../core/common/common.js';
+import * as SDK from '../../core/sdk/sdk.js';
+
+import {resolveScopeChain} from './NamesResolver.js';
+
+/**
+ * This class is responsible for resolving / updating the scope chain for a specific {@link SDK.DebuggerModel.CallFrame}
+ * instance.
+ *
+ * There are several sources that can influence the scope view:
+ *   - Debugger plugins can provide the whole scope info (e.g. from DWARF)
+ *   - Source Maps can provide OR augment scope info
+ *
+ * Source maps can be enabled/disabled dynamically and debugger plugins can attach debug info after the fact.
+ *
+ * This class tracks all that and sends events with the latest scope chain for a specific call frame.
+ */
+export class ScopeChainModel extends Common.ObjectWrapper.ObjectWrapper<EventTypes> {
+  readonly #callFrame: SDK.DebuggerModel.CallFrame;
+
+  /** We use the `Throttler` here to make sure that `#boundUpdate` is not run multiple times simultanously */
+  readonly #throttler = new Common.Throttler.Throttler(5);
+  readonly #boundUpdate = this.#update.bind(this);
+
+  constructor(callFrame: SDK.DebuggerModel.CallFrame) {
+    super();
+    this.#callFrame = callFrame;
+    this.#callFrame.debuggerModel.addEventListener(
+        SDK.DebuggerModel.Events.DebugInfoAttached, this.#debugInfoAttached, this);
+    this.#callFrame.debuggerModel.sourceMapManager().addEventListener(
+        SDK.SourceMapManager.Events.SourceMapAttached, this.#sourceMapAttached, this);
+
+    void this.#throttler.schedule(this.#boundUpdate);
+  }
+
+  dispose(): void {
+    this.#callFrame.debuggerModel.removeEventListener(
+        SDK.DebuggerModel.Events.DebugInfoAttached, this.#debugInfoAttached, this);
+    this.#callFrame.debuggerModel.sourceMapManager().removeEventListener(
+        SDK.SourceMapManager.Events.SourceMapAttached, this.#sourceMapAttached, this);
+    this.listeners?.clear();
+  }
+
+  async #update(): Promise<void> {
+    const scopeChain = await resolveScopeChain(this.#callFrame);
+    this.dispatchEventToListeners(Events.SCOPE_CHAIN_UPDATED, new ScopeChain(scopeChain));
+  }
+
+  #debugInfoAttached(event: Common.EventTarget.EventTargetEvent<SDK.Script.Script>): void {
+    if (event.data === this.#callFrame.script) {
+      void this.#throttler.schedule(this.#boundUpdate);
+    }
+  }
+
+  #sourceMapAttached(event: Common.EventTarget
+                         .EventTargetEvent<{client: SDK.Script.Script, sourceMap: SDK.SourceMap.SourceMap}>): void {
+    if (event.data.client === this.#callFrame.script) {
+      void this.#throttler.schedule(this.#boundUpdate);
+    }
+  }
+}
+
+export const enum Events {
+  SCOPE_CHAIN_UPDATED = 'ScopeChainUpdated',
+}
+
+export interface EventTypes {
+  [Events.SCOPE_CHAIN_UPDATED]: ScopeChain;
+}
+
+/**
+ * A scope chain ready to be shown in the UI with debugging info applied.
+ */
+export class ScopeChain {
+  readonly scopeChain: SDK.DebuggerModel.ScopeChainEntry[];
+
+  constructor(scopeChain: SDK.DebuggerModel.ScopeChainEntry[]) {
+    this.scopeChain = scopeChain;
+  }
+}

package/lib/front_end/models/source_map_scopes/source_map_scopes.ts

@@ -0,0 +1,11 @@
+// Copyright 2022 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as NamesResolver from './NamesResolver.js';
+import * as ScopeChainModel from './ScopeChainModel.js';
+
+export {
+  NamesResolver,
+  ScopeChainModel,
+};

package/lib/front_end/models/stack_trace/StackTrace.ts

@@ -0,0 +1,53 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import type * as Common from '../../core/common/common.js';
+import type * as SDK from '../../core/sdk/sdk.js';
+import type * as Workspace from '../workspace/workspace.js';
+
+export interface StackTrace extends Common.EventTarget.EventTarget<EventTypes> {
+  readonly syncFragment: Fragment;
+  readonly asyncFragments: readonly AsyncFragment[];
+}
+
+export interface Fragment {
+  readonly frames: readonly Frame[];
+}
+
+export interface AsyncFragment extends Fragment {
+  readonly description: string;
+}
+
+export interface Frame {
+  readonly url?: string;
+  readonly uiSourceCode?: Workspace.UISourceCode.UISourceCode;
+  readonly name?: string;
+  readonly line: number;
+  readonly column: number;
+
+  readonly missingDebugInfo?: MissingDebugInfo;
+}
+
+export const enum MissingDebugInfoType {
+  /** No debug information at all for the call frame */
+  NO_INFO = 'NO_INFO',
+
+  /** Some debug information available, but it references files with debug information we were not able to retrieve */
+  PARTIAL_INFO = 'PARTIAL_INFO',
+}
+
+export type MissingDebugInfo = {
+  type: MissingDebugInfoType.NO_INFO,
+}|{
+  type: MissingDebugInfoType.PARTIAL_INFO,
+  missingDebugFiles: SDK.DebuggerModel.MissingDebugFiles[],
+};
+
+export const enum Events {
+  UPDATED = 'UPDATED',
+}
+
+export interface EventTypes {
+  [Events.UPDATED]: void;
+}

package/lib/front_end/models/stack_trace/StackTraceImpl.ts

@@ -0,0 +1,85 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as Common from '../../core/common/common.js';
+import type * as Workspace from '../workspace/workspace.js';
+
+import type * as StackTrace from './stack_trace.js';
+import type {FrameNode} from './Trie.js';
+
+export class StackTraceImpl extends Common.ObjectWrapper.ObjectWrapper<StackTrace.StackTrace.EventTypes> implements
+    StackTrace.StackTrace.StackTrace {
+  readonly syncFragment: FragmentImpl;
+  readonly asyncFragments: readonly AsyncFragmentImpl[];
+
+  constructor(syncFragment: FragmentImpl, asyncFragments: AsyncFragmentImpl[]) {
+    super();
+    this.syncFragment = syncFragment;
+    this.asyncFragments = asyncFragments;
+
+    syncFragment.stackTraces.add(this);
+    this.asyncFragments.forEach(asyncFragment => asyncFragment.fragment.stackTraces.add(this));
+  }
+}
+
+export class FragmentImpl implements StackTrace.StackTrace.Fragment {
+  readonly node: FrameNode;
+  readonly stackTraces = new Set<StackTraceImpl>();
+
+  /**
+   * Fragments are deduplicated based on the node.
+   *
+   * In turn, each fragment can be part of multiple stack traces.
+   */
+  static getOrCreate(node: FrameNode): FragmentImpl {
+    if (!node.fragment) {
+      node.fragment = new FragmentImpl(node);
+    }
+    return node.fragment;
+  }
+
+  private constructor(node: FrameNode) {
+    this.node = node;
+  }
+
+  get frames(): FrameImpl[] {
+    const frames: FrameImpl[] = [];
+
+    for (const node of this.node.getCallStack()) {
+      frames.push(...node.frames);
+    }
+
+    return frames;
+  }
+}
+
+export class AsyncFragmentImpl implements StackTrace.StackTrace.AsyncFragment {
+  constructor(readonly description: string, readonly fragment: FragmentImpl) {
+  }
+
+  get frames(): StackTrace.StackTrace.Frame[] {
+    return this.fragment.frames;
+  }
+}
+
+export class FrameImpl implements StackTrace.StackTrace.Frame {
+  readonly url?: string;
+  readonly uiSourceCode?: Workspace.UISourceCode.UISourceCode;
+  readonly name?: string;
+  readonly line: number;
+  readonly column: number;
+
+  readonly missingDebugInfo?: StackTrace.StackTrace.MissingDebugInfo;
+
+  constructor(
+      url: string|undefined, uiSourceCode: Workspace.UISourceCode.UISourceCode|undefined, name: string|undefined,
+      line: number, column: number, missingDebugInfo?: StackTrace.StackTrace.MissingDebugInfo) {
+    this.url = url;
+    this.uiSourceCode = uiSourceCode;
+    this.name = name;
+    this.line = line;
+    this.column = column;
+    this.missingDebugInfo = missingDebugInfo;
+  }
+}

package/lib/front_end/models/stack_trace/StackTraceModel.ts

@@ -0,0 +1,128 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as SDK from '../../core/sdk/sdk.js';
+import type * as Protocol from '../../generated/protocol.js';
+
+// eslint-disable-next-line @devtools/es-modules-import
+import * as StackTrace from './stack_trace.js';
+import {AsyncFragmentImpl, FragmentImpl, FrameImpl, StackTraceImpl} from './StackTraceImpl.js';
+import {type FrameNode, type RawFrame, Trie} from './Trie.js';
+
+/**
+ * A stack trace translation function.
+ *
+ * Any implementation must return an array with the same length as `frames`.
+ */
+export type TranslateRawFrames = (frames: readonly RawFrame[], target: SDK.Target.Target) => Promise<
+    Array<Array<Pick<StackTrace.StackTrace.Frame, 'url'|'uiSourceCode'|'name'|'line'|'column'|'missingDebugInfo'>>>>;
+
+/**
+ * The {@link StackTraceModel} is a thin wrapper around a fragment trie.
+ *
+ * We want to store stack trace fragments per target so a SDKModel is the natural choice.
+ */
+export class StackTraceModel extends SDK.SDKModel.SDKModel<unknown> {
+  readonly #trie = new Trie();
+
+  /** @returns the {@link StackTraceModel} for the target, or the model for the primaryPageTarget when passing null/undefined */
+  static #modelForTarget(target: SDK.Target.Target|null|undefined): StackTraceModel {
+    const model = (target ?? SDK.TargetManager.TargetManager.instance().primaryPageTarget())?.model(StackTraceModel);
+    if (!model) {
+      throw new Error('Unable to find StackTraceModel');
+    }
+    return model;
+  }
+
+  async createFromProtocolRuntime(stackTrace: Protocol.Runtime.StackTrace, rawFramesToUIFrames: TranslateRawFrames):
+      Promise<StackTrace.StackTrace.StackTrace> {
+    const translatePromises: Array<Promise<unknown>> = [];
+
+    const fragment = this.#createFragment(stackTrace.callFrames);
+    translatePromises.push(this.#translateFragment(fragment, rawFramesToUIFrames));
+
+    const asyncFragments: AsyncFragmentImpl[] = [];
+    const debuggerModel = this.target().model(SDK.DebuggerModel.DebuggerModel);
+    if (debuggerModel) {
+      for await (const {stackTrace: asyncStackTrace, target} of debuggerModel.iterateAsyncParents(stackTrace)) {
+        const model = StackTraceModel.#modelForTarget(target);
+        const asyncFragment = model.#createFragment(asyncStackTrace.callFrames);
+        translatePromises.push(model.#translateFragment(asyncFragment, rawFramesToUIFrames));
+        asyncFragments.push(new AsyncFragmentImpl(asyncStackTrace.description ?? '', asyncFragment));
+      }
+    }
+
+    await Promise.all(translatePromises);
+
+    return new StackTraceImpl(fragment, asyncFragments);
+  }
+
+  /** Trigger re-translation of all fragments with the provide script in their call stack */
+  async scriptInfoChanged(script: SDK.Script.Script, translateRawFrames: TranslateRawFrames): Promise<void> {
+    const translatePromises: Array<Promise<unknown>> = [];
+    let stackTracesToUpdate = new Set<StackTraceImpl>();
+
+    for (const fragment of this.#affectedFragments(script)) {
+      // We trigger re-translation only for fragments of leaf-nodes. Any fragment along the ancestor-chain
+      // is re-translated as a side-effect.
+      // We just need to remember the stack traces of the skipped over fragments, so we can send the
+      // UPDATED event also to them.
+      if (fragment.node.children.length === 0) {
+        translatePromises.push(this.#translateFragment(fragment, translateRawFrames));
+      }
+      stackTracesToUpdate = stackTracesToUpdate.union(fragment.stackTraces);
+    }
+
+    await Promise.all(translatePromises);
+
+    for (const stackTrace of stackTracesToUpdate) {
+      stackTrace.dispatchEventToListeners(StackTrace.StackTrace.Events.UPDATED);
+    }
+  }
+
+  #createFragment(frames: RawFrame[]): FragmentImpl {
+    return FragmentImpl.getOrCreate(this.#trie.insert(frames));
+  }
+
+  async #translateFragment(fragment: FragmentImpl, rawFramesToUIFrames: TranslateRawFrames): Promise<void> {
+    const rawFrames = fragment.node.getCallStack().map(node => node.rawFrame).toArray();
+    const uiFrames = await rawFramesToUIFrames(rawFrames, this.target());
+    console.assert(rawFrames.length === uiFrames.length, 'Broken rawFramesToUIFrames implementation');
+
+    let i = 0;
+    for (const node of fragment.node.getCallStack()) {
+      node.frames = uiFrames[i++].map(
+          frame => new FrameImpl(
+              frame.url, frame.uiSourceCode, frame.name, frame.line, frame.column, frame.missingDebugInfo));
+    }
+  }
+
+  #affectedFragments(script: SDK.Script.Script): Set<FragmentImpl> {
+    // 1. Collect branches with the matching script.
+    const affectedBranches = new Set<FrameNode>();
+    this.#trie.walk(null, node => {
+      // scriptId has precedence, but if the frame does not have one, check the URL.
+      if (node.rawFrame.scriptId === script.scriptId ||
+          (!node.rawFrame.scriptId && node.rawFrame.url === script.sourceURL)) {
+        affectedBranches.add(node);
+        return false;
+      }
+      return true;
+    });
+
+    // 2. For each branch collect all the fragments.
+    const fragments = new Set<FragmentImpl>();
+    for (const branch of affectedBranches) {
+      this.#trie.walk(branch, node => {
+        if (node.fragment) {
+          fragments.add(node.fragment);
+        }
+        return true;
+      });
+    }
+    return fragments;
+  }
+}
+
+SDK.SDKModel.SDKModel.register(StackTraceModel, {capabilities: SDK.Target.Capability.NONE, autostart: false});

package/lib/front_end/models/stack_trace/Trie.ts

@@ -0,0 +1,163 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import type * as Protocol from '../../generated/protocol.js';
+
+import type {FragmentImpl, FrameImpl} from './StackTraceImpl.js';
+
+/**
+ * Intentionally very close to a {@link Protocol.Runtime.CallFrame} but with optional `scriptId`.
+ */
+export interface RawFrame {
+  readonly scriptId?: Protocol.Runtime.ScriptId;
+  readonly url?: string;
+  readonly functionName?: string;
+  readonly lineNumber: number;
+  readonly columnNumber: number;
+}
+
+/**
+ * @returns whether the frame is a V8 builtin frame e.g. Array.map. Builtin frames
+ * have neither source position nor script or URL. They only have a name.
+ */
+export function isBuiltinFrame(rawFrame: RawFrame): boolean {
+  return rawFrame.lineNumber === -1 && rawFrame.columnNumber === -1 && !Boolean(rawFrame.scriptId) &&
+      !Boolean(rawFrame.url);
+}
+
+interface FrameNodeBase<ChildT, ParentT> {
+  readonly parent: ParentT;
+  readonly children: ChildT[];
+}
+
+type RootFrameNode = FrameNodeBase<WeakRef<FrameNode>, null>;
+type AnyFrameNode = FrameNode|RootFrameNode;
+
+export class FrameNode implements FrameNodeBase<FrameNode, AnyFrameNode> {
+  readonly parent: AnyFrameNode;
+  readonly children: FrameNode[] = [];
+
+  readonly rawFrame: RawFrame;
+  frames: FrameImpl[] = [];
+
+  fragment?: FragmentImpl;
+
+  constructor(rawFrame: RawFrame, parent: AnyFrameNode) {
+    this.rawFrame = rawFrame;
+    this.parent = parent;
+  }
+
+  /**
+   * Produces the ancestor chain. Including `this` but excluding the `RootFrameNode`.
+   */
+  * getCallStack(): Generator<FrameNode> {
+    // The `RootFrameNode` doesn't have an actual frame attached, that's why we check for `node.parent` instead of `node`.
+    for (let node: AnyFrameNode|null = this; node.parent; node = node.parent) {
+      yield node;
+    }
+  }
+}
+
+/**
+ * Stores stack trace fragments in a trie, but does not own them/keep them alive.
+ */
+export class Trie {
+  readonly #root: RootFrameNode = {parent: null, children: []};
+
+  /**
+   * Most sources produce stack traces in "top-to-bottom" order, so that is what this method expects.
+   *
+   * @returns The {@link FrameNode} corresponding to the top-most stack frame.
+   */
+  insert(frames: RawFrame[]): FrameNode {
+    if (frames.length === 0) {
+      throw new Error('Trie.insert called with an empty frames array.');
+    }
+
+    let currentNode: AnyFrameNode = this.#root;
+    for (let i = frames.length - 1; i >= 0; --i) {
+      currentNode = this.#insert(currentNode, frames[i]);
+    }
+    return currentNode as FrameNode;
+  }
+
+  /**
+   * Inserts `rawFrame` into the children of the provided node if not already there.
+   *
+   * @returns the child node corresponding to `rawFrame`.
+   */
+  #insert(node: AnyFrameNode, rawFrame: RawFrame): FrameNode {
+    let i = 0;
+    for (; i < node.children.length; ++i) {
+      const maybeChild = node.children[i];
+      const child = maybeChild instanceof WeakRef ? maybeChild.deref() : maybeChild;
+      if (!child) {
+        continue;
+      }
+
+      const compareResult = compareRawFrames(child.rawFrame, rawFrame);
+      if (compareResult === 0) {
+        return child;
+      }
+      if (compareResult > 0) {
+        break;
+      }
+    }
+
+    const newNode = new FrameNode(rawFrame, node);
+    if (node.parent) {
+      node.children.splice(i, 0, newNode);
+    } else {
+      node.children.splice(i, 0, new WeakRef(newNode));
+    }
+    return newNode;
+  }
+
+  /**
+   * Traverses the trie in pre-order.
+   *
+   * @param node Start at `node` or `null` to start with the children of the root.
+   * @param visit Called on each node in the trie. Return `true` if the visitor should descend into child nodes of the provided node.
+   */
+  walk(node: FrameNode|null, visit: (node: FrameNode) => boolean): void {
+    const stack =
+        node ? [node] : [...this.#root.children].map(ref => ref.deref()).filter(node => Boolean(node)) as FrameNode[];
+
+    for (let node = stack.pop(); node; node = stack.pop()) {
+      const visitChildren = visit(node);
+      if (visitChildren) {
+        // Pushing the children in reverse means the "left-most" child is visited first (i.e. pre-order).
+        for (let i = node.children.length - 1; i >= 0; --i) {
+          stack.push(node.children[i]);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * @returns a number < 0, 0 or > 0, if the `a` is smaller then, equal or greater then `b`.
+ */
+export function compareRawFrames(a: RawFrame, b: RawFrame): number {
+  const scriptIdCompare = (a.scriptId ?? '').localeCompare(b.scriptId ?? '');
+  if (scriptIdCompare !== 0) {
+    return scriptIdCompare;
+  }
+
+  const urlCompare = (a.url ?? '').localeCompare(b.url ?? '');
+  if (urlCompare !== 0) {
+    return urlCompare;
+  }
+
+  const nameCompare = (a.functionName ?? '').localeCompare(b.functionName ?? '');
+  if (nameCompare !== 0) {
+    return nameCompare;
+  }
+
+  if (a.lineNumber !== b.lineNumber) {
+    return a.lineNumber - b.lineNumber;
+  }
+
+  return a.columnNumber - b.columnNumber;
+}

package/lib/front_end/models/stack_trace/stack_trace.ts

@@ -0,0 +1,9 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as StackTrace from './StackTrace.js';
+
+export {
+  StackTrace,
+};

package/lib/front_end/models/stack_trace/stack_trace_impl.ts

@@ -0,0 +1,13 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as StackTraceImpl from './StackTraceImpl.js';
+import * as StackTraceModel from './StackTraceModel.js';
+import * as Trie from './Trie.js';
+
+export {
+  StackTraceImpl,
+  StackTraceModel,
+  Trie,
+};