[api] Give standalone created files a tracked identity and incorporate with the parse cache

[Andrew Branch (andrewbranch)]

Changes api.createSourceFile and api.createSourceFileFromFile to acquire from the global parse cache (on both client and server) and return a disposable lease:

- const sourceFile = api.createSourceFile(fileName, text);
+ using lease = api.createSourceFile(fileName, text);
+ lease.sourceFile;

api.createSourceFile(fileName, text).sourceFile === api.createSourceFile(fileName, text);
// true

api.createProgram([fileName], {}).getSourceFile(fileName) === api.createSourceFile(fileName, text).sourceFile;
// true, assuming host's readFile returns same text as `text`

This does few things:

1. Immediately reduces parsing cost for a program creation that sees the same file + options as one that's already been parsed (something David Sherret (@dsherret) asked about)
2. Opens the door to providing specific file handles to program construction, like jakebailey@c3b4130 (possible follow-up)
3. Opens the door to attaching binder Symbols to SourceFiles with proper lifetime and identity (definite follow-up)

[Copilot]

Copilot review overview

🔵 Needs a closer look

Cross-language protocol, cache identity, and reference-lifetime changes warrant final human validation.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Include fileName in client cache key to prevent identity collisions

[Jake Bailey (jakebailey)]

What if you just want a throwaway AST and don't care about equality or reuse?

[Andrew Branch (andrewbranch)]

Then using it or otherwise dispose it when you're ready to throw it away, or don't and it will get released when you close the API

[Andrew Branch (andrewbranch)]

The problem is the binder symbol follow-up. With server identities, you can do things like

sourceFile.getSymbol();         // fetches if not already cached
api.bindSourceFile(sourceFile); // fetches and assigns all binder symbols

You can't do that with an untracked, throwaway SourceFile, which makes for a confusing bifurcation of types/capabilities.