[api] Ensure completion symbols returned to API always come from the current snapshot

[Andrew Branch (andrewbranch)]

Fixes #64518 (comment):

This is actually just a more obvious symptom of an existing bug. In main, every completion symbol from the temporary snapshot get registered by the parent snapshot's snapshotData record. That means the caller can get completions, assume the returned symbols belong to the current snapshot, and use the current snapshot's checker on them. If the symbol being operated on is transient, that will probably cause incorrect results or a crash.

If an API method is going to return objects from a new snapshot, that new snapshot must be returned to the client as well, so the objects can be operated on. getCompletionsAtPosition only optionally includes symbols, and only advances the snapshot if auto-imports are both needed for the position and not already prepared. Whether or not to include auto-imports ever should be configurable, but currently is not by the API.

A proper fix needs to address this from a few angles:

• Be able to configure auto-imports in the API (perhaps per call, definitely by applying user preferences to a snapshot)
• Be able to create a snapshot that is prepared to auto-import a file

I think with both of those, you can keep getCompletionsAtPosition's return value as is and not have it return a snapshot, or bifurcate the method into one variant that returns a snapshot and one that doesn't:

• If includeSymbols is false, use the same logic that exists today, with auto-import retry as needed.
• If includeSymbols is true, disable auto-import retry and return an error if the current snapshot isn't prepared. The caller either needs to disable auto-imports or explicitly create a prepared snapshot.

This PR adds exactly all of that. Since UserPreferences is now exposed to the API, the second commit generates both the Go and the TS from a schema. Rather than complicate the schema/generation to preserve the Go type exactly as it was, I had the field names and enum constants generated from the actual JSON properties/values that VS Code expects, which accounts for the renaming. I can add more metadata to the schema to undo that, but I kind of prefer the consistency.

[Jake Bailey (jakebailey)]

If I'm understanding this correctly, we're bringing back preferences sent along with requests? The LSP doesn't work this way so I'm at least moderately concerned we're creating a bad situation for ourselves by having multiple concepts here, but maybe I'm not understanding.

[Andrew Branch (andrewbranch)]

No, you're understanding. This isn't LSP so I don't see the need for that constraint here in the direct access language service. I can remove it, but it seems useful. The alternative is you have to do a whole extra round trip snapshot clone just to control the preferences for one completions request. The way LSP works makes sense because there's a single persistent state for preferences. I'm not sure it makes as much sense when state forks arbitrarily.

[Andrew Branch (andrewbranch)]

Removed. We can always add it later if there's a need.

[Copilot]

Copilot review overview

🟡 Changes recommended

The generated public preference contract rejects a valid organizeImportsCaseFirst: false value, and the symbol-ownership regression test does not exercise the returned symbol handle.

Review effort: Balanced
Findings: 1 · 1 · 1

Open (3)

• Preserve false sentinel in generated UserPreferences type · New
• Verify completion symbol usability with checker assertion · New
• Document prepareAutoImports requirement for includeSymbol · New

Resolved since last review (1)

• Export UserPreferences and CompletionPreferences from async and sync entrypoints

[Andrew Branch (andrewbranch)]

Ahaha oh no, I got caught doing code analysis with a regular expression. Someone take my compiler engineer license away 😦

Error in typescript:release in 2s
Error: Found external imports in .d.ts files:
  dist/api/userPreferences.generated.d.ts:20: external import declaration "fs"