docs(language-server): spec for lazy document state + pull diagnostics

[SevInf]

Specification-only PR for the lsp-document-state project. No implementation here — this commits the Drive project artifacts (spec, plan, slice spec) so the design can be reviewed before any code lands.

What this is

A settled design for reworking the language server's document-state lifecycle from eager, defensive reparse to invalidate-on-change + lazily materialize-on-read, synchronously, plus a move from push to pull diagnostics.

didChange  ──▶  mark the document's project dirty            (cheap; no parse)
read req   ──▶  await project load (only while uncached)      (async: config eval, cached)
            ──▶  ensureCurrent(project, uri)                  (SYNC: reparse iff version changed)
            ──▶  derive (completion / diagnostics / …)        (SYNC: no await before deriving)

Why

• Today every edit parses twice (eager publish + currentDocumentArtifact per-request reparse with a whole-document text compare) to dodge a stale-buffer race the LSP spec says we should not have to fight.
• We are single-threaded and synchronous, so tsserver's version-keyed lazy recompute fits; rust-analyzer's snapshot/cancellation machinery exists only because its reads run on background threads.
• Async is confined to project/config load (executable prisma-next.config.ts, evaluated via dynamic import); parse/derive stays synchronous so a derived result is always internally consistent for one version.

Scope

• One slice: lazy-state-and-pull-diagnostics (lazy lifecycle + pull diagnostics ship together — dropping eager compute requires the pull transport to exist).
• TextDocuments is kept (demoted to text mirror / lifecycle / version source).
• Diagnostics flags ship as { interFileDependencies: false, workspaceDiagnostics: false } with an honest scope-comment; the multi-input table flip is deferred.

Non-goals

Removing TextDocuments, the multi-input symbol table, multi-project membership, and any behavioural changes to completion/semantic-tokens/folding. See projects/lsp-document-state/spec.md § Non-goals.

Sequencing

Stacked on lsp-autocomplete (#871); base is lsp-autocomplete, not main. Merges after #871.

Artifacts

• projects/lsp-document-state/spec.md
• projects/lsp-document-state/plan.md
• projects/lsp-document-state/slices/lazy-state-and-pull-diagnostics/spec.md

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 69d57542-6492-4ef8-aa62-8d5eecc2059f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch lsp-document-state

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}