Add simple value bindings to builders

Author: szuend

src/builder/builder.test.ts

@@ -202,6 +202,13 @@ describe("ScopeInfoBuilder", () => {
 
       assertStrictEquals(info.ranges[0]?.isHidden, true);
     });
+
+    it("can set simple values via option", () => {
+      const info = builder.startRange(0, 0, { values: ["a", null, "b"] })
+        .endRange(0, 10).build();
+
+      assertEquals(info.ranges[0]?.values, ["a", null, "b"]);
+    });
   });
 
   describe("setRangeDefinitionScope", () => {
@@ -256,6 +263,19 @@ describe("ScopeInfoBuilder", () => {
     });
   });
 
+  describe("setRangeValues", () => {
+    it("sets the values", () => {
+      const info = builder.startRange(0, 0).setRangeValues(["a", null, null])
+        .endRange(0, 10).build();
+
+      assertEquals(info.ranges[0]?.values, ["a", null, null]);
+    });
+
+    it("does nothing when no range is on the stack", () => {
+      builder.setRangeValues(["a", null, "b"]);
+    });
+  });
+
   describe("endRange", () => {
     it("does nothing when no range is open", () => {
       builder.endRange(0, 20);

src/builder/builder.ts

@@ -2,7 +2,12 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import type { GeneratedRange, OriginalScope, ScopeInfo } from "../scopes.d.ts";
+import type {
+  Binding,
+  GeneratedRange,
+  OriginalScope,
+  ScopeInfo,
+} from "../scopes.d.ts";
 
 /**
  * Small utility class to build scope and range trees.
@@ -129,14 +134,15 @@ export class ScopeInfoBuilder {
       scopeKey?: ScopeKey;
       isStackFrame?: boolean;
       isHidden?: boolean;
+      values?: Binding[];
     },
   ): this {
     const range: GeneratedRange = {
       start: { line, column },
       end: { line, column },
       isStackFrame: Boolean(options?.isStackFrame),
       isHidden: Boolean(options?.isHidden),
-      values: [],
+      values: options?.values ?? [],
       children: [],
     };
 
@@ -181,6 +187,13 @@ export class ScopeInfoBuilder {
     return this;
   }
 
+  setRangeValues(values: Binding[]): this {
+    const range = this.#rangeStack.at(-1);
+    if (range) range.values = values;
+
+    return this;
+  }
+
   endRange(line: number, column: number): this {
     const range = this.#rangeStack.pop();
     if (!range) return this;
@@ -221,6 +234,10 @@ export class ScopeInfoBuilder {
   protected isValidScopeKey(key: ScopeKey): boolean {
     return this.#keyToScope.has(key);
   }
+
+  protected getScopeByValidKey(key: ScopeKey): OriginalScope {
+    return this.#keyToScope.get(key)!;
+  }
 }
 
 /**

src/builder/safe_builder.test.ts

@@ -171,6 +171,31 @@ describe("SafeScopeInfoBuilder", () => {
         })
       );
     });
+
+    it("throws when 'values' is provided without a scope", () => {
+      assertThrows(() => builder.startRange(0, 0, { values: ["a", null] }));
+    });
+
+    it("throws when 'values' length does not match OriginalScope.variables length (via scope)", () => {
+      const scope = builder.startScope(0, 0, { variables: ["foo", "bar"] })
+        .endScope(10, 0).lastScope()!;
+
+      assertThrows(() =>
+        builder.startRange(0, 0, { scope, values: ["a", null, "b"] })
+      );
+    });
+
+    it("throws when 'values' length does not match OriginalScope.variables length (via scopeKey)", () => {
+      builder.startScope(0, 0, { variables: ["foo", "bar"], key: "my key" })
+        .endScope(10, 0);
+
+      assertThrows(() =>
+        builder.startRange(0, 0, {
+          scopeKey: "my key",
+          values: ["a", null, "b"],
+        })
+      );
+    });
   });
 
   describe("setRangeDefinitionScope", () => {
@@ -247,6 +272,32 @@ describe("SafeScopeInfoBuilder", () => {
     });
   });
 
+  describe("setRangeValues", () => {
+    it("throws when no range is on open", () => {
+      assertThrows(() => builder.setRangeValues(["a", null]));
+    });
+
+    it("throws while building a scope", () => {
+      builder.startScope(0, 0);
+
+      assertThrows(() => builder.setRangeValues(["a", null]));
+    });
+
+    it("throws when called without setting a scope prior", () => {
+      builder.startRange(0, 0);
+
+      assertThrows(() => builder.setRangeValues(["a", null]));
+    });
+
+    it("throws when 'values' length does not match OriginalScope.variables length (via scope)", () => {
+      const scope = builder.startScope(0, 0, { variables: ["foo", "bar"] })
+        .endScope(10, 0).lastScope()!;
+      builder.startRange(0, 0, { scope });
+
+      assertThrows(() => builder.setRangeValues(["a", null, "b"]));
+    });
+  });
+
   describe("endRange", () => {
     it("throws when the range stack is empty", () => {
       assertThrows(() => builder.endRange(5, 0));

src/builder/safe_builder.ts

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import type { OriginalScope, ScopeInfo } from "../scopes.d.ts";
+import type { Binding, OriginalScope, ScopeInfo } from "../scopes.d.ts";
 import { comparePositions } from "../util.ts";
 import { ScopeInfoBuilder, type ScopeKey } from "./builder.ts";
 
@@ -114,6 +114,7 @@ export class SafeScopeInfoBuilder extends ScopeInfoBuilder {
       scopeKey?: ScopeKey;
       isStackFrame?: boolean;
       isHidden?: boolean;
+      values?: Binding[];
     },
   ): this {
     this.#verifyEmptyScopeStack("starRange");
@@ -151,6 +152,27 @@ export class SafeScopeInfoBuilder extends ScopeInfoBuilder {
       );
     }
 
+    if (
+      options?.values?.length && options?.scope === undefined &&
+      options?.scopeKey === undefined
+    ) {
+      throw new Error("Provided bindings without providing an OriginalScope");
+    } else if (
+      options?.values?.length && options?.scope &&
+      options.values.length !== options.scope.variables.length
+    ) {
+      throw new Error(
+        "Provided bindings don't match up with OriginalScope.variables",
+      );
+    } else if (options?.values?.length && options?.scopeKey !== undefined) {
+      const scope = this.getScopeByValidKey(options.scopeKey);
+      if (options.values.length !== scope.variables.length) {
+        throw new Error(
+          "Provided bindings don't match up with OriginalScope.variables",
+        );
+      }
+    }
+
     super.startRange(line, column, options);
     return this;
   }
@@ -199,6 +221,25 @@ export class SafeScopeInfoBuilder extends ScopeInfoBuilder {
     return this;
   }
 
+  override setRangeValues(values: Binding[]): this {
+    this.#verifyEmptyScopeStack("setRangeValues");
+    this.#verifyRangePresent("setRangeValues");
+
+    const range = this.rangeStack.at(-1)!;
+    if (!range.originalScope) {
+      throw new Error(
+        "Setting an OriginalScope for a range is required before value bindings can be provided!",
+      );
+    } else if (range.originalScope.variables.length !== values.length) {
+      throw new Error(
+        "Provided bindings don't match up with OriginalScope.variables",
+      );
+    }
+
+    super.setRangeValues(values);
+    return this;
+  }
+
   override endRange(line: number, column: number): this {
     this.#verifyEmptyScopeStack("endRange");
 

src/scopes.d.ts

@@ -92,16 +92,18 @@ export interface GeneratedRange {
  *
  *   1) A single expression (valid for a full `GeneratedRange`).
  *
- *   2) `undefined` if this variable is unavailable in the whole range. This can
+ *   2) `null` if this variable is unavailable in the whole range. This can
  *      happen e.g. when the variable was optimized out and can't be recomputed.
  *
  *   3) A list of `SubRangeBinding`s. Used when computing the value requires different
  *      expressions throughout the `GeneratedRange` or if the variable is unavailable in
  *      parts of the `GeneratedRange`.
- *      The "from" of the first `SubRangeBinding` and the "to" of the last `SubRangeBinding`
- *      are qual to the `GeneratedRange`s "start" and "end" position respectively.
+ *
+ *      Note: The decoder produces `SubRangeBindings` where the "from" of the first `SubRangeBinding`
+ *      and the "to" of the last `SubRangeBinding` are equal to the `GeneratedRange`s "start" and "end"
+ *      position respectively.
  */
-export type Binding = string | undefined | SubRangeBinding[];
+export type Binding = string | null | SubRangeBinding[];
 
 export interface SubRangeBinding {
   value?: string;