[api] Add various merged symbol checker methods (#64598)

Author: andrewbranch

packages/typescript/src/api/async/api.ts

@@ -2231,6 +2231,50 @@ export class Checker {
         this.objectRegistry.clear();
     }
 
+    /** Get the merged symbol, or the original symbol if it has not been merged. */
+    async getMergedSymbol(symbol: Symbol): Promise<Symbol> {
+        const data = await this.client.apiRequest("getMergedSymbol", {
+            snapshot: this.snapshotId,
+            project: this.project.id,
+            symbol: symbol.reference,
+        });
+        return this.objectRegistry.getOrCreateSymbol(data);
+    }
+
+    /**
+     * Get a node's merged symbol. For a declaration, prefer
+     * {@link Checker.getSymbolOfDeclaration} for a non-nullable result.
+     */
+    async getSymbolOfNode(node: Node): Promise<Symbol | undefined> {
+        const data = await this.client.apiRequest("getSymbolOfNode", {
+            snapshot: this.snapshotId,
+            project: this.project.id,
+            location: getNodeId(node),
+        });
+        return data ? this.objectRegistry.getOrCreateSymbol(data) : undefined;
+    }
+
+    /** Get a declaration's merged symbol. */
+    async getSymbolOfDeclaration(node: Declaration): Promise<Symbol> {
+        const data = await this.client.apiRequest("getSymbolOfDeclarationForChecker", {
+            snapshot: this.snapshotId,
+            project: this.project.id,
+            location: getNodeId(node),
+        });
+        // Declarations normally have symbols, but preserve unexpected null results at runtime.
+        return (data && this.objectRegistry.getOrCreateSymbol(data))!;
+    }
+
+    /** Get a symbol's merged parent, if any. */
+    async getParentOfSymbol(symbol: Symbol): Promise<Symbol | undefined> {
+        const data = await this.client.apiRequest("getParentOfSymbolForChecker", {
+            snapshot: this.snapshotId,
+            project: this.project.id,
+            symbol: symbol.reference,
+        });
+        return data ? this.objectRegistry.getOrCreateSymbol(data) : undefined;
+    }
+
     getSymbolAtLocation(node: Node): Promise<Symbol | undefined>;
     getSymbolAtLocation(nodes: readonly Node[]): Promise<(Symbol | undefined)[]>;
     async getSymbolAtLocation(nodeOrNodes: Node | readonly Node[]): Promise<Symbol | (Symbol | undefined)[] | undefined> {

packages/typescript/src/api/proto.generated.ts

@@ -145,6 +145,10 @@ export interface APIMethodInfo {
     getAliasedSymbol: APIMethod<CheckerSymbolParams, SymbolResponse>;
     getImmediateAliasedSymbol: APIMethod<CheckerSymbolParams, SymbolResponse | null>;
     getTargetSymbol: APIMethod<CheckerSymbolParams, SymbolResponse>;
+    getMergedSymbol: APIMethod<CheckerSymbolParams, SymbolResponse>;
+    getSymbolOfNode: APIMethod<CheckerNodeParams, SymbolResponse | null>;
+    getSymbolOfDeclarationForChecker: APIMethod<CheckerNodeParams, SymbolResponse | null>;
+    getParentOfSymbolForChecker: APIMethod<CheckerSymbolParams, SymbolResponse | null>;
     getExportSymbolOfSymbolForChecker: APIMethod<CheckerSymbolParams, SymbolResponse>;
     getFullyQualifiedName: APIMethod<CheckerSymbolParams, string>;
     getExportsOfModule: APIMethod<CheckerSymbolParams, SymbolResponse[] | null>;
@@ -1193,6 +1197,7 @@ export interface BatchRequest {
         | "getLocalTypeParametersOfType"
         | "getMemberInModuleExports"
         | "getMembersOfSymbol"
+        | "getMergedSymbol"
         | "getModeForResolutionAtIndex"
         | "getModeForUsageLocation"
         | "getNameTypeOfMappedType"
@@ -1207,6 +1212,7 @@ export interface BatchRequest {
         | "getParameterType"
         | "getParametersOfSignature"
         | "getParentOfSymbol"
+        | "getParentOfSymbolForChecker"
         | "getProgramDiagnostics"
         | "getPropertiesOfType"
         | "getPropertyOfType"
@@ -1234,6 +1240,8 @@ export interface BatchRequest {
         | "getSymbolAtLocation"
         | "getSymbolAtPosition"
         | "getSymbolOfDeclaration"
+        | "getSymbolOfDeclarationForChecker"
+        | "getSymbolOfNode"
         | "getSymbolOfSourceFile"
         | "getSymbolOfType"
         | "getSymbolsAtLocations"
@@ -1371,6 +1379,7 @@ export interface BatchResponse {
         | "getLocalTypeParametersOfType"
         | "getMemberInModuleExports"
         | "getMembersOfSymbol"
+        | "getMergedSymbol"
         | "getModeForResolutionAtIndex"
         | "getModeForUsageLocation"
         | "getNameTypeOfMappedType"
@@ -1385,6 +1394,7 @@ export interface BatchResponse {
         | "getParameterType"
         | "getParametersOfSignature"
         | "getParentOfSymbol"
+        | "getParentOfSymbolForChecker"
         | "getProgramDiagnostics"
         | "getPropertiesOfType"
         | "getPropertyOfType"
@@ -1412,6 +1422,8 @@ export interface BatchResponse {
         | "getSymbolAtLocation"
         | "getSymbolAtPosition"
         | "getSymbolOfDeclaration"
+        | "getSymbolOfDeclarationForChecker"
+        | "getSymbolOfNode"
         | "getSymbolOfSourceFile"
         | "getSymbolOfType"
         | "getSymbolsAtLocations"

packages/typescript/src/api/sync/api.ts

@@ -4068,6 +4068,123 @@ export class Checker {
         this.objectRegistry.clear();
     }
 
+    /** Get the merged symbol, or the original symbol if it has not been merged. */
+    get getMergedSymbol(): {
+        (symbol: Symbol): Symbol;
+        gen(symbol: Symbol): Generator<ProtocolRequest, Symbol, ProtocolResponse["result"]>;
+    } {
+        const owner = this;
+        return cacheGeneratorMethod(
+            owner,
+            "getMergedSymbol",
+            function (symbol: Symbol): Symbol {
+                const data = owner.client.apiRequest("getMergedSymbol", {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    symbol: symbol.reference,
+                });
+                return owner.objectRegistry.getOrCreateSymbol(data);
+            },
+            function* (symbol: Symbol): Generator<ProtocolRequest, Symbol, ProtocolResponse["result"]> {
+                const data = yield* apiRequest("getMergedSymbol", {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    symbol: symbol.reference,
+                });
+                return owner.objectRegistry.getOrCreateSymbol(data);
+            },
+        );
+    }
+
+    /**
+     * Get a node's merged symbol. For a declaration, prefer
+     * {@link Checker.getSymbolOfDeclaration} for a non-nullable result.
+     */
+    get getSymbolOfNode(): {
+        (node: Node): Symbol | undefined;
+        gen(node: Node): Generator<ProtocolRequest, Symbol | undefined, ProtocolResponse["result"]>;
+    } {
+        const owner = this;
+        return cacheGeneratorMethod(
+            owner,
+            "getSymbolOfNode",
+            function (node: Node): Symbol | undefined {
+                const data = owner.client.apiRequest("getSymbolOfNode", {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    location: getNodeId(node),
+                });
+                return data ? owner.objectRegistry.getOrCreateSymbol(data) : undefined;
+            },
+            function* (node: Node): Generator<ProtocolRequest, Symbol | undefined, ProtocolResponse["result"]> {
+                const data = yield* apiRequest("getSymbolOfNode", {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    location: getNodeId(node),
+                });
+                return data ? owner.objectRegistry.getOrCreateSymbol(data) : undefined;
+            },
+        );
+    }
+
+    /** Get a declaration's merged symbol. */
+    get getSymbolOfDeclaration(): {
+        (node: Declaration): Symbol;
+        gen(node: Declaration): Generator<ProtocolRequest, Symbol, ProtocolResponse["result"]>;
+    } {
+        const owner = this;
+        return cacheGeneratorMethod(
+            owner,
+            "getSymbolOfDeclaration",
+            function (node: Declaration): Symbol {
+                const data = owner.client.apiRequest("getSymbolOfDeclarationForChecker", {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    location: getNodeId(node),
+                });
+                // Declarations normally have symbols, but preserve unexpected null results at runtime.
+                return (data && owner.objectRegistry.getOrCreateSymbol(data))!;
+            },
+            function* (node: Declaration): Generator<ProtocolRequest, Symbol, ProtocolResponse["result"]> {
+                const data = yield* apiRequest("getSymbolOfDeclarationForChecker", {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    location: getNodeId(node),
+                });
+                // Declarations normally have symbols, but preserve unexpected null results at runtime.
+                return (data && owner.objectRegistry.getOrCreateSymbol(data))!;
+            },
+        );
+    }
+
+    /** Get a symbol's merged parent, if any. */
+    get getParentOfSymbol(): {
+        (symbol: Symbol): Symbol | undefined;
+        gen(symbol: Symbol): Generator<ProtocolRequest, Symbol | undefined, ProtocolResponse["result"]>;
+    } {
+        const owner = this;
+        return cacheGeneratorMethod(
+            owner,
+            "getParentOfSymbol",
+            function (symbol: Symbol): Symbol | undefined {
+                const data = owner.client.apiRequest("getParentOfSymbolForChecker", {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    symbol: symbol.reference,
+                });
+                return data ? owner.objectRegistry.getOrCreateSymbol(data) : undefined;
+            },
+            function* (symbol: Symbol): Generator<ProtocolRequest, Symbol | undefined, ProtocolResponse["result"]> {
+                const data = yield* apiRequest("getParentOfSymbolForChecker", {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    symbol: symbol.reference,
+                });
+                return data ? owner.objectRegistry.getOrCreateSymbol(data) : undefined;
+            },
+        );
+    }
+
     get getSymbolAtLocation(): {
         (node: Node): Symbol | undefined;
         (nodes: readonly Node[]): (Symbol | undefined)[];

packages/typescript/test/async/api.test.ts

@@ -21,6 +21,7 @@ import {
     isNamedImports,
     isObjectLiteralExpression,
     isPropertyAssignment,
+    isPropertyDeclaration,
     isReturnStatement,
     isShorthandPropertyAssignment,
     isStringLiteral,
@@ -505,7 +506,7 @@ describe("API", { concurrency }, () => {
     });
 
     test("remote declarations lazily fetch and cache binder symbols", async () => {
-        const sourceText = "function present() {}\nimport {} from './missing';";
+        const sourceText = "function present() {}";
         await using api = spawnAPI({
             "/symbols.ts": sourceText,
         });
@@ -514,9 +515,7 @@ describe("API", { concurrency }, () => {
         const sourceFile = await project.program.getSourceFile("/symbols.ts");
         assert.ok(sourceFile);
         const declaration = sourceFile.statements[0];
-        const withoutSymbol = sourceFile.statements[1];
         assert.ok(isFunctionDeclaration(declaration));
-        assert.ok(isImportDeclaration(withoutSymbol));
         const checkerSymbol = await project.checker.getSymbolAtPosition("/symbols.ts", sourceText.indexOf("present")); // @sync: const checkerSymbol = project.checker.getSymbolAtPosition("/symbols.ts", sourceText.indexOf("present"));
         assert.ok(checkerSymbol);
 
@@ -537,11 +536,6 @@ describe("API", { concurrency }, () => {
         assert.strictEqual(await getSymbol(declaration), first); // @sync: assert.strictEqual(getSymbol(declaration), first);
         assert.equal(symbolRequests, 1);
 
-        symbolRequests = 0;
-        await assert.rejects(getSymbol(withoutSymbol), /has no binder symbol/); // @sync: assert.throws(() => getSymbol(withoutSymbol), /has no binder symbol/);
-        await assert.rejects(api.getSymbol(withoutSymbol), /has no binder symbol/); // @sync: assert.throws(() => api.getSymbol(withoutSymbol), /has no binder symbol/);
-        assert.equal(symbolRequests, 2);
-
         await snapshot.dispose();
     });
 
@@ -563,7 +557,7 @@ describe("API", { concurrency }, () => {
 
     test("source files own separate declaration result and request caches", async () => {
         await using api = spawnAPI();
-        await using lease = await api.createSourceFile("/symbols.ts", "function present() {}\nimport {} from './missing';");
+        await using lease = await api.createSourceFile("/symbols.ts", "function present() {}");
         const file = lease.sourceFile;
         assert.ok(file instanceof RemoteSourceFile);
         const cache = file.symbolCache;
@@ -578,11 +572,6 @@ describe("API", { concurrency }, () => {
         assert.strictEqual(cache.symbolsByDeclarationNodeIndex.get(index), symbol);
         assert.strictEqual(cache.symbolsById.get(symbol.reference.id), symbol);
         assert.equal(cache.declarationSymbolRequests.has(index), false);
-        const withoutSymbol = cast(file.statements[1], isImportDeclaration);
-        const absentIndex = parseNodeHandle(getNodeId(withoutSymbol)).index;
-        await assert.rejects(getSymbol(withoutSymbol), /has no binder symbol/); // @sync: assert.throws(() => getSymbol(withoutSymbol), /has no binder symbol/);
-        assert.equal(cache.symbolsByDeclarationNodeIndex.has(absentIndex), false);
-        assert.equal(cache.declarationSymbolRequests.has(absentIndex), false);
         api.clearSourceFileCache();
         assert.strictEqual(file.symbolCache, cache);
     });
@@ -3953,6 +3942,69 @@ export const value = 1;
         assert.notStrictEqual(second, first);
     });
 
+    test("checker symbol methods merge declarations and parents in their project", async () => {
+        await using api = spawnAPI({
+            "/tsconfig.json": JSON.stringify({ files: ["/src/a.ts", "/src/b.ts"] }),
+            "/single/tsconfig.json": JSON.stringify({ files: ["/src/a.ts"] }),
+            "/src/a.ts": "namespace Merged { export const a = 1; }",
+            "/src/b.ts": "namespace Merged { export const b = 1; }",
+        });
+        const snapshot = await api.createSnapshot({ openProjects: ["/tsconfig.json", "/single/tsconfig.json"] });
+        const project = snapshot.getConfiguredProject("/tsconfig.json")!;
+        const singleProject = snapshot.getConfiguredProject("/single/tsconfig.json")!;
+        const fileA = await project.program.getSourceFile("/src/a.ts");
+        const fileB = await project.program.getSourceFile("/src/b.ts");
+        assert.ok(fileA && fileB);
+        const declarationA = cast(fileA.statements[0], isModuleDeclaration);
+        const declarationB = cast(fileB.statements[0], isModuleDeclaration);
+        const rawA = await getSymbol(declarationA);
+        const rawB = await getSymbol(declarationB);
+        assert.notStrictEqual(rawA, rawB);
+
+        const merged = await project.checker.getSymbolOfDeclaration(declarationA);
+        assert.strictEqual(await project.checker.getSymbolOfDeclaration(declarationB), merged);
+        assert.strictEqual(await project.checker.getSymbolOfNode(declarationA), merged);
+        assert.strictEqual(await project.checker.getMergedSymbol(rawA), merged);
+        assert.strictEqual(await project.checker.getMergedSymbol(rawB), merged);
+        assert.strictEqual(await project.checker.getMergedSymbol(merged), merged);
+        assert.strictEqual(await singleProject.checker.getMergedSymbol(rawA), rawA);
+        assert.strictEqual(await singleProject.checker.getSymbolOfDeclaration(declarationA), rawA);
+        assert.equal(await project.checker.getSymbolOfNode(declarationA.name), undefined);
+        assert.equal(await project.checker.getSymbolOfNode(fileA), undefined);
+        assert.equal(await project.checker.getParentOfSymbol(merged), undefined);
+
+        const member = (await rawA.getExports()).get("a" as __String);
+        assert.ok(member);
+        assert.strictEqual(await member.getParent(), rawA);
+        assert.strictEqual(await project.checker.getParentOfSymbol(member), merged);
+        assert.strictEqual(await singleProject.checker.getParentOfSymbol(member), rawA);
+    });
+
+    test("checker symbol methods late-bind computed members", async () => {
+        await using api = spawnAPI({
+            "/src/computed.ts": "declare const key: unique symbol;\nclass Container { [key] = 1; ordinary = 2; }\nimport {} from './missing';",
+        });
+        const snapshot = await api.createSnapshot({ openFiles: ["/src/computed.ts"] });
+        const project = snapshot.getProjects()[0];
+        const file = await project.program.getSourceFile("/src/computed.ts");
+        assert.ok(file);
+        const declaration = cast(file.statements[1], isClassDeclaration);
+        const memberDeclaration = cast(declaration.members[0], isPropertyDeclaration);
+        const raw = await getSymbol(memberDeclaration);
+        const lateBound = await project.checker.getSymbolOfDeclaration(memberDeclaration);
+        assert.notStrictEqual(lateBound, raw);
+        assert.strictEqual(await project.checker.getSymbolOfNode(memberDeclaration), lateBound);
+        const container = await project.checker.getSymbolOfDeclaration(declaration);
+        assert.strictEqual(await project.checker.getParentOfSymbol(lateBound), container);
+        const type = await project.checker.getDeclaredTypeOfSymbol(container);
+        const property = (await type.getProperties()).find(symbol => symbol.escapedName === lateBound.escapedName);
+        assert.ok(property);
+        assert.strictEqual(await project.checker.getTargetSymbol(property), lateBound);
+        const ordinary = cast(declaration.members[1], isPropertyDeclaration);
+        assert.strictEqual(await project.checker.getSymbolOfDeclaration(ordinary), await getSymbol(ordinary));
+        assert.equal(await project.checker.getSymbolOfNode(file.statements[2]), undefined);
+    });
+
     test("snapshot-owned symbols resolve cached file-owned parents", async () => {
         const source = `interface Box<T> { value: T; }\ndeclare const box: Box<string>;\nbox;`;
         await using api = spawnAPI({