Debounce LSP inlay hints to stop width jitter while typing (#4145)

[anushamukka-dev]

Summary:

VS Code has no client-side inlay-hint debounce (microsoft/vscode#133730), so pyrefly recomputed and re-rendered inlay hints on every keystroke. Because a keystroke can change an inferred type, hint widths shift several times a second right where the user is editing, which is distracting and hard to track (#4138).

This debounces inlay hints server-side, the same way rust-analyzer responded to that VS Code issue: while a document is still being edited, inlay hint updates are held until editing pauses, so hints only settle once typing stops.

The mechanism reuses the existing LSP event queue. LspQueue records the wall-clock time of the most recent document edit and exposes time_since_last_edit. When an inlay hint request arrives within the debounce window, the request dispatch re-enqueues it on a short-lived timer thread instead of answering immediately. The sleep happens off the single event-loop thread, so it never blocks other requests, and the re-enqueued request composes with the existing "cancel stale queries on a subsequent mutation" logic — if more edits arrive, the deferred request is dropped and a fresh one takes its place.

The debounce clock is keyed strictly on genuine in-editor edits (didChange for text and notebook documents) via LspEvent::is_edit(), not on every mutation-class event. This matters for correctness: the event queue classifies saves, didOpen/didClose, configuration and workspace-folder changes, watched-file drains, and client responses all as "mutations". Keying the debounce on that broad class would let non-typing activity reset the window — in particular, watched-file-change notifications (fired on every external file change, e.g. during a build, rebase, or format-on-save) arriving faster than the debounce window could defer inlay hints indefinitely while the user sits idle. Confining the clock to real edits keeps the debounce scoped to actual typing, which is what the feature is for; as a side benefit didOpen no longer opens the window, so hints on a freshly opened file compute immediately.

The window is controlled by analysis.inlayHintDebounceMs (VS Code: python.analysis.inlayHintDebounceMs), defaulting to 150ms; 0 restores the previous immediate-update behavior.

Differential Revision: D111847562

[meta-codesync]

@anushamukka-dev has exported this pull request. If you are a Meta employee, you can view the originating Diff in D111847562.

[github-actions]

According to mypy_primer, this change doesn't affect type check results on a corpus of open source code. ✅