[api] Add getSymbol(decl)

[Andrew Branch (andrewbranch)]

Follow-up to #64518. This was going to be the last, but I decided to split it up further.

This PR exposes the direct analog of TS 6’s declaration.symbol property—i.e., access from a Declaration node to its unmerged, binder-produced symbol. Previously, checker.getSymbolAtLocation was kind of the only way to get a declaration's symbol, and that has some weird, unintuitive behavior.

Being able to access binder symbols without a type checker means you can now access symbols from files created with api.createSourceFile:

const { sourceFile } = api.createSourceFile(text);
const moduleSymbol = api.getSymbol(sourceFile);

For convenient access in utility functions, there's also a top-level getSymbol export so you can do this without passing around the api:

import type { Declaration } from "typescript/ast";
import { getSymbol } from "typescript/async";

async function getDeclarationSymbolName(decl: Declaration): Promise<string> {
  return (await getSymbol(decl)).name;
}

Why not decl.getSymbol()?

I really wanted (and really tried) to do this, but because there's a sync Symbol type and an async Symbol type, tying that into the AST types directly would mean generating three parallel AST definitions¹:

• The base, sync/async-independent AST types, as they are today
• Sync remoteable AST definitions
• Async remoteable AST definitions

This is possible, and it would fix #64483 at the same time. It might be worth it, but has some rough edges. Mainly, it means you would need dedicated is node guard variants for sync and async remote nodes per-kind. When you use a normal guard, that removes the “remoteness” narrowing already applied:

import { isClassDeclaration } from "typescript/ast";

const remoteNode = program.getSourceFile(fileName).statements[0];
//    ^? Remote<Node>

if (isClassDeclaration(remoteNode)) {
  remoteNode.getSymbol();
//           ^^^^^^^^^ 'getSymbol' does not exist on type 'ClassDeclaration'
}

You need instead to import the guard from the sync or async module and use the .Remote refinement guard:

import { isClassDeclaration } from "typescript/async";

const remoteNode = program.getSourceFile(fileName).statements[0];

if (isClassDeclaration.Remote(remoteNode)) {
  remoteNode.getSymbol();
}

If you try to make the guard signatures more clever, to preserve narrowings already applied, they tend to break in confusing ways in higher order.

This may all be worth doing, still, but I wanted to separate it out for further discussion. A version of this PR with the sync/async remote specializations applied can be viewed at https://github.com/microsoft/TypeScript/compare/main...andrewbranch:remote-ast-types?expand=1

---

¹ Using a complicated conditional type also works, but makes errors and hover info completely unreadable.

[Copilot]

Copilot review overview

🟡 Changes recommended

Several tests enforce reference equality after disposal or cache clearing despite the newly documented absence of that guarantee.

Review effort: Balanced
Findings: 2

Open (2)

• Avoid requiring wrapper identity after lease disposal · New
• Avoid requiring wrapper identity after lease disposal · New

What changed in this PR

Adds binder-symbol lookup for remote declarations without requiring a type checker.

Changes:

• Adds the getSymbol(declaration) protocol and sync/async APIs.
• Associates source files and symbol caches with their owning API.
• Adds symbol lookup, caching, lifecycle, and batching tests.

File	Description
.github/​skills/​api-client/​SKILL.md	Documents cache-lifetime identity guarantees.
tsc/​internal/​api/​session.go	Handles declaration-symbol requests.
tsc/​internal/​api/​session_createsourcefile_test.go	Tests server-side lookup.
tsc/​internal/​api/​proto.go	Defines the protocol method and parameters.
packages/​typescript/​src/​api/​async/​api.ts	Implements the async API and ownership changes.
packages/​typescript/​src/​api/​sync/​api.ts	Implements the sync and generator APIs.
packages/​typescript/​src/​api/​node/​node.ts	Records source-file API ownership.
packages/​typescript/​src/​api/​sourceFileCache.ts	Adds declaration-symbol caches.
packages/​typescript/​src/​api/​proto.generated.ts	Updates generated protocol types.
packages/​typescript/​test/​async/​api.test.ts	Tests async behavior and lifetimes.
packages/​typescript/​test/​sync/​api.test.ts	Tests sync behavior and lifetimes.
packages/​typescript/​test/​sync/​api-generators.test.ts	Tests generator and batching parity.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Wesley Wigham (weswigham)]

Pretty sure we need to expose Checker.getMergedSymbol alongside this (well, also for API compat since we used to export it in TS6), since binder symbols are inherently unmerged, so not-so-useful for globals, unless you're only looking for the globals made in a single file. Do you wanna do that as another followup?