Add definition scopes to builder

Author: szuend

src/builder/builder.test.ts

@@ -125,6 +125,25 @@ describe("ScopeInfoBuilder", () => {
     assertStrictEquals(info.ranges[0], info.ranges[0].children[0].parent);
   });
 
+  describe("startRange", () => {
+    it("sets the definition scope when it's provided as a number", () => {
+      const info = builder.startScope(0, 0).endScope(10, 0).startRange(0, 0, {
+        scope: 0,
+      }).endRange(0, 10).build();
+
+      assertStrictEquals(info.scopes[0], info.ranges[0].originalScope);
+    });
+
+    it("sets the definition scope when it's provided directly", () => {
+      const scope = builder.startScope(0, 0).endScope(10, 0).lastScope();
+      const info = builder.startRange(0, 0, { scope: scope! }).endRange(0, 10)
+        .build();
+
+      assertStrictEquals(info.scopes[0], info.ranges[0].originalScope);
+      assertStrictEquals(info.ranges[0].originalScope, scope);
+    });
+  });
+
   describe("endRange", () => {
     it("does nothing when no range is open", () => {
       builder.endRange(0, 20);

src/builder/builder.ts

@@ -23,6 +23,7 @@ export class ScopeInfoBuilder {
 
   #scopeCounter = 0;
   #scopeToCount = new Map<OriginalScope, number>();
+  #countToScope = new Map<number, OriginalScope>();
   #lastScope: OriginalScope | null = null;
 
   addNullScope(): this {
@@ -50,7 +51,8 @@ export class ScopeInfoBuilder {
       scope.parent = this.#scopeStack.at(-1);
     }
     this.#scopeStack.push(scope);
-    this.#scopeToCount.set(scope, this.#scopeCounter++);
+    this.#scopeToCount.set(scope, this.#scopeCounter);
+    this.#countToScope.set(this.#scopeCounter++, scope);
 
     return this;
   }
@@ -103,7 +105,16 @@ export class ScopeInfoBuilder {
     return this.#lastScope;
   }
 
-  startRange(line: number, column: number): this {
+  /**
+   * @param option The definition 'scope' of this range can either be the "OriginalScope" directly
+   * (produced by this builder) or the scope's number.
+   * If a scope was started with the n-th call to `startScope` then n is the scope's number.
+   */
+  startRange(
+    line: number,
+    column: number,
+    options?: { scope?: number | OriginalScope },
+  ): this {
     const range: GeneratedRange = {
       start: { line, column },
       end: { line, column },
@@ -117,6 +128,12 @@ export class ScopeInfoBuilder {
       range.parent = this.#rangeStack.at(-1);
     }
 
+    if (typeof options?.scope === "number") {
+      range.originalScope = this.#countToScope.get(options.scope);
+    } else if (options?.scope !== undefined) {
+      range.originalScope = options.scope;
+    }
+
     this.#rangeStack.push(range);
 
     return this;
@@ -142,7 +159,9 @@ export class ScopeInfoBuilder {
 
     this.#scopes = [];
     this.#ranges = [];
+    this.#scopeCounter = 0;
     this.#scopeToCount.clear();
+    this.#countToScope.clear();
 
     return info;
   }
@@ -162,4 +181,12 @@ export class ScopeInfoBuilder {
   protected get ranges(): ReadonlyArray<GeneratedRange> {
     return this.#ranges;
   }
+
+  protected isValidScopeNumber(n: number): boolean {
+    return this.#countToScope.has(n);
+  }
+
+  protected isKnownScope(scope: OriginalScope): boolean {
+    return this.#scopeToCount.has(scope);
+  }
 }

src/builder/safe_builder.test.ts

@@ -4,7 +4,7 @@
 
 import { beforeEach, describe, it } from "jsr:@std/testing/bdd";
 import { SafeScopeInfoBuilder } from "./safe_builder.ts";
-import { assertThrows } from "jsr:@std/assert";
+import { assert, assertThrows } from "jsr:@std/assert";
 
 describe("SafeScopeInfoBuilder", () => {
   let builder: SafeScopeInfoBuilder;
@@ -141,6 +141,24 @@ describe("SafeScopeInfoBuilder", () => {
 
       builder.startRange(10, 5);
     });
+
+    it("throws when the definition scope doesnt point to a valid scope", () => {
+      assertThrows(() => builder.startRange(0, 0, { scope: 0 }));
+    });
+
+    it("throws when the definition scope is not known to the builder", () => {
+      assertThrows(() =>
+        builder.startRange(0, 0, {
+          scope: {
+            start: { line: 0, column: 0 },
+            end: { line: 10, column: 10 },
+            isStackFrame: false,
+            variables: [],
+            children: [],
+          },
+        })
+      );
+    });
   });
 
   describe("endRange", () => {

src/builder/safe_builder.ts

@@ -92,7 +92,11 @@ export class SafeScopeInfoBuilder extends ScopeInfoBuilder {
     return this;
   }
 
-  override startRange(line: number, column: number): this {
+  override startRange(
+    line: number,
+    column: number,
+    options?: { scope?: number | OriginalScope },
+  ): this {
     this.#verifyEmptyScopeStack("starRange");
 
     const parent = this.rangeStack.at(-1);
@@ -114,7 +118,23 @@ export class SafeScopeInfoBuilder extends ScopeInfoBuilder {
       );
     }
 
-    super.startRange(line, column);
+    if (
+      typeof options?.scope === "number" &&
+      !this.isValidScopeNumber(options.scope)
+    ) {
+      throw new Error(
+        `${options.scope} does not reference a valid OriginalScope`,
+      );
+    }
+    if (
+      typeof options?.scope === "object" && !this.isKnownScope(options.scope)
+    ) {
+      throw new Error(
+        "The provided definition scope was not produced by this builder!",
+      );
+    }
+
+    super.startRange(line, column, options);
     return this;
   }