Raven Lsp Debug

Raven LSP Debugging

Use this skill for language service and editor failures.

Required Logs

Capture both sides:

• server logs from logs/raven-lsp.log
• client lifecycle and request logs from the VS Code Raven output channel

Include relevant excerpts when reporting or fixing hover, completion, or definition failures.

Workflow

For large or multi-surface investigations, work as a planned task sequence: define the current slice, keep one step active, verify it before moving on, and re-evaluate the next slice after each result. Tell the user what the next step is after each verified slice. Prefer reduced compiler-level repros before broad LSP or sample-project coverage, then add editor-level tests only when request scheduling, workspace loading, or presentation behavior is part of the bug.

1. Reduce the issue to a minimal source example.

2. Record the exact editor action that fails.

3. Reproduce the request with the headless language-server harness when possible:

   dotnet run --project tools/Raven.LanguageServer.Headless/Raven.LanguageServer.Headless.csproj /property:WarningLevel=0

   The default run opens samples/projects/efcore-vehicle-costs/src/Api/Main.rvn and simulates hovers for the current EF Core sample. Pass a project directory, source file, and optional target names to narrow the run:

   dotnet run --project tools/Raven.LanguageServer.Headless/Raven.LanguageServer.Headless.csproj /property:WarningLevel=0 -- samples/projects/efcore-vehicle-costs samples/projects/efcore-vehicle-costs/src/Api/Main.rvn UseNpgsql

   There are three useful replay modes:

   # Replay hover positions from logs/raven-lsp-performance.txt.
   dotnet run --project tools/Raven.LanguageServer.Headless/Raven.LanguageServer.Headless.csproj /property:WarningLevel=0 -- samples/projects/efcore-vehicle-costs samples/projects/efcore-vehicle-costs/src/Api/Main.rvn --replay-performance-report --replay-count 10
   
   # Hover random syntax targets in a file.
   dotnet run --project tools/Raven.LanguageServer.Headless/Raven.LanguageServer.Headless.csproj /property:WarningLevel=0 -- samples/projects/efcore-vehicle-costs samples/projects/efcore-vehicle-costs/src/Api/Main.rvn --random-hover --random-count 50 --random-seed 1729
   
   # Replay exact LSP positions, using zero-based line:character coordinates.
   dotnet run --project tools/Raven.LanguageServer.Headless/Raven.LanguageServer.Headless.csproj /property:WarningLevel=0 -- samples/projects/efcore-vehicle-costs samples/projects/efcore-vehicle-costs/src/Api/Main.rvn --position 15:29

   Use this harness to simulate hover behavior without VS Code, gather timings, and inspect semantic performance counters such as symbol-info fallback, type-info fallback, and bound-node bind fallback. For edit recovery regressions, use headless edit probes to model the way developers actually reshape code: type an opening wrapper such as func Main() {, later add the closing }, or create func Main() { } and paste existing top-level statements into the body. Compare the first semantic query after the edit with a cold one-shot compilation and with a follow-up edit inside the stabilized owner. For deterministic regression coverage, use the language-server unit-test hover replay helpers to load inline Raven source, open it through the mock workspace/document store, and orchestrate hovers at exact positions or marker-derived positions.

4. Check the client log to confirm the request lifecycle and parameters.

5. Check the server log to see request handling, failures, or missing symbol results.

6. Correlate the failing request with syntax, symbol lookup, binding, diagnostics behavior, compiler API caching, and language service code.

7. Add focused regression coverage if the failure is fixed in code.

When comparing editor behavior with command-line behavior, use the current tool split: rvnc / Raven.Compiler is the compiler driver for one-shot compile and project build repros, while rvn / Raven is for developer commands such as syntax, pretty dump, and bound-tree views.

Compiler Boundary

• Use docs/compiler/architecture/live-semantic-model.md as the shared reference for how compiler-owned semantic state, analyzer scheduling, diagnostic lanes, and LSP request prioritization should fit together.
• The language server should present compiler answers. It should not own semantic invalidation, symbol inference, overload selection, binder selection, or cache policy.
• First verify the Roslyn-shaped compiler APIs: GetSymbolInfo, GetTypeInfo, GetDeclaredSymbol, diagnostics, operations, and available public semantic entry points.
• If those APIs are wrong, slow, or cache-dependent, fix Raven.CodeAnalysis. Keep LSP-side semantic inference temporary and remove it once the compiler can answer.
• Binders are the compiler execution units. Method binders own parameters; block binders own immediate locals, statement/expression binding state, and binder-produced diagnostics.
• Compilation and SemanticModel are the semantic service boundary for the language server. LSP handlers should obtain the compiler-owned semantic model for the requested document snapshot and then call public semantic APIs rather than reading or composing internal cache state.
• Lazy binding is expected. A hover, inlay, completion, or diagnostics request may be the first path to trigger binding; once it does, later paths should observe the same compiler-owned cached symbols, types, and diagnostics.
• Prefer correctness and deterministic compiler-owned answers over cold-start speed. Cold first queries may bind; optimize later without changing semantic meaning.
• Treat available-state APIs as opportunistic fast paths. If available state is incomplete or context-sensitive, use the authoritative semantic API that can bind instead of presenting a guessed answer.
• Do not make editor features intentionally incomplete just to avoid binding. If a result is semantically required, ask the compiler for it; optimize the compiler path or request scheduling if the cold path is too slow.
• Inlays should use the same semantic model answers as hover and diagnostics. They may skip tooltips or stale background work for UX reasons, but type/parameter annotations should not disappear because a separate LSP policy refused to bind. Type annotation text should stay source-friendly; do not show fully qualified names merely as a performance shortcut.
• The LSP may coordinate request cancellation, prioritize interactive requests, skip stale background work, and avoid monopolizing semantic access, but it should not change semantic meaning.
• Foreground semantic requests such as hover, completion, signature help, definition, and rename should not wait behind broad background work unless they need the exact same semantic model state. Background diagnostics, analyzers, semantic tokens, and full-document inlays should be cancellable and may be skipped/requeued for a newer document version.
• LSP-side caches should be presentation-only and versioned, such as rendered hover markdown or inlay labels. Symbol/type/diagnostic truth belongs to Raven.CodeAnalysis.
• Cross-file edits are normal. After adding or changing another source file, a hover in the original file should resolve symbols through the current project compilation snapshot rather than stale per-document state.