[stack_trace] Add scaffolding and some types for the fragment trie

Get the boiler plate out of the way to keep CL size small.

The root node of the trie holds on to it's children via WeakRef.
This allows the GC to cleanup unused stack trace fragments.

In theory, we could use WeakRefs for all child references, to allow
the GC pruning of unused branches. But WeakRefs are not cheap from a
GC perspective so WeakRef-ing the whole Trie would come at a
significant performance cost with questionable benefit.

[email protected]

Bug: 433162438
Change-Id: If57cf52301c958ebb3cedbd27bb9fef807fbb5ee
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6837823
Commit-Queue: Simon Zünd <[email protected]>
Reviewed-by: Philip Pfaffe <[email protected]>

Author: szuend

config/gni/devtools_grd_files.gni

@@ -592,6 +592,7 @@ grd_files_bundled_sources = [
   "front_end/models/project_settings/project_settings.js",
   "front_end/models/source_map_scopes/source_map_scopes.js",
   "front_end/models/stack_trace/stack_trace.js",
+  "front_end/models/stack_trace/stack_trace_impl.js",
   "front_end/models/text_utils/text_utils.js",
   "front_end/models/trace/extras/extras.js",
   "front_end/models/trace/handlers/handlers.js",
@@ -1121,6 +1122,7 @@ grd_files_unbundled_sources = [
   "front_end/models/source_map_scopes/ScopeChainModel.js",
   "front_end/models/source_map_scopes/ScopeTreeCache.js",
   "front_end/models/stack_trace/StackTrace.js",
+  "front_end/models/stack_trace/Trie.js",
   "front_end/models/text_utils/CodeMirrorUtils.js",
   "front_end/models/text_utils/ContentData.js",
   "front_end/models/text_utils/ContentProvider.js",

front_end/BUILD.gn

@@ -143,6 +143,7 @@ group("unittests") {
     "models/persistence:unittests",
     "models/project_settings:unittests",
     "models/source_map_scopes:unittests",
+    "models/stack_trace:unittests",
     "models/text_utils:unittests",
     "models/trace:unittests",
     "models/trace/extras:unittests",

front_end/models/bindings/BUILD.gn

@@ -37,6 +37,7 @@ devtools_module("bindings") {
     "../../core/sdk:bundle",
     "../../generated:protocol",
     "../../models/stack_trace:bundle",
+    "../../models/stack_trace:impl",
     "../../models/text_utils:bundle",
     "../../models/workspace:bundle",
   ]

front_end/models/stack_trace/BUILD.gn

@@ -23,3 +23,37 @@ devtools_entrypoint("bundle") {
 
   visibility = [ "*" ]
 }
+
+devtools_module("stack_trace_impl") {
+  sources = [ "Trie.ts" ]
+
+  deps = [
+    ":bundle",
+    "../../generated",
+  ]
+}
+
+devtools_entrypoint("impl") {
+  entrypoint = "stack_trace_impl.ts"
+
+  deps = [ ":stack_trace_impl" ]
+
+  # IMPORTANT: Besides tests and bindings, no other module is allowed access.
+  #            If you have a use-case where you need access to stack trace internals,
+  #            consult one of the OWNERS before drilling holes.
+  visibility = [
+    ":unittests",
+    "../bindings",
+  ]
+}
+
+ts_library("unittests") {
+  testonly = true
+
+  sources = [ "Trie.test.ts" ]
+
+  deps = [
+    ":bundle",
+    ":impl",
+  ]
+}

front_end/models/stack_trace/Trie.test.ts

@@ -0,0 +1,15 @@
+// Copyright 2025 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as StackTraceImpl from './stack_trace_impl.js';
+
+describe('Trie', () => {
+  describe('insert', () => {
+    it('throws for empty stack traces', () => {
+      const trie = new StackTraceImpl.Trie.Trie();
+
+      assert.throws(() => trie.insert([]));
+    });
+  });
+});

front_end/models/stack_trace/Trie.ts

@@ -0,0 +1,48 @@
+// Copyright 2025 The Chromium Authors. All rights reserved.
+// 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 * as StackTrace from './stack_trace.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;
+}
+
+interface FrameNodeBase<ChildT, ParentT> {
+  readonly parent: ParentT;
+  readonly children: ChildT[];
+}
+
+type RootFrameNode = FrameNodeBase<WeakRef<FrameNode>, null>;
+type AnyFrameNode = FrameNode|RootFrameNode;
+
+export interface FrameNode extends FrameNodeBase<FrameNode, AnyFrameNode> {
+  readonly rawFrame: RawFrame;
+  frames: StackTrace.StackTrace.Frame[];
+}
+
+/**
+ * Stores stack trace fragments in a trie, but does not own them/keep them alive.
+ */
+export class Trie {
+  // eslint-disable-next-line no-unused-private-class-members
+  readonly #root: RootFrameNode = {parent: null, children: []};
+
+  insert(frames: RawFrame[]): FrameNode {
+    if (frames.length === 0) {
+      throw new Error('Trie.insert called with an empty frames array.');
+    }
+
+    // TODO(crbug.com/433162438): Implement it.
+    throw new Error('Not implemented');
+  }
+}

front_end/models/stack_trace/stack_trace_impl.ts

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