122 lines
4.8 KiB
Markdown
122 lines
4.8 KiB
Markdown
---
|
|
id: PLN-0076
|
|
ticket: pbs-lsp-editor-assistance-wave-1
|
|
title: LSP Completion, Hover, and Signature Help over Editorial Resolution
|
|
status: open
|
|
created: 2026-05-08
|
|
completed:
|
|
tags: [studio, lsp, protocol, completion, hover, signature-help, editor]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Expose `completion`, real `hover`, and `signature help` through the project-scoped LSP stack by projecting the compiler-backed editorial resolution surface into explicit protocol capabilities and request handlers.
|
|
|
|
## Background
|
|
|
|
`DEC-0035` requires `studio/lsp` to be the operational owner of these editor features while remaining faithful to compiler-backed symbol, member, and signature resolution. The current LSP path only handles diagnostics, semantic tokens, and a placeholder hover.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
|
|
- Extend the internal bridge/API with completion and signature-help operations.
|
|
- Replace placeholder hover with symbol-resolved hover.
|
|
- Announce LSP capabilities for completion and signature help.
|
|
- Add message models/mappers/tests for the new request/response paths.
|
|
|
|
### Excluded
|
|
|
|
- Creation of the underlying compiler editorial model itself.
|
|
- Authored documentation syntax.
|
|
- VS Code-specific UI behavior beyond normal LSP consumption.
|
|
|
|
## Non-Goals
|
|
|
|
- `go to definition`, `references`, `rename`, formatter, code actions, or quick fixes.
|
|
- Rich workspace-wide indexing beyond what the shared editorial surface already provides.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Extend the LSP bridge contract
|
|
|
|
**What:** Add compiler-backed editor-assistance operations to the bridge.
|
|
**How:** Evolve `LanguageServiceBridge` and related internal messages to support at minimum:
|
|
|
|
1. completion requests;
|
|
2. symbol-resolved hover payloads;
|
|
3. signature-help requests.
|
|
|
|
The bridge contract must align structurally with the shared editorial resolution surface rather than inventing a second feature-specific abstraction.
|
|
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/**`, `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/**`.
|
|
|
|
### Step 2 - Implement compiler-backed request handling
|
|
|
|
**What:** Wire LSP requests to compiler-backed editorial resolution.
|
|
**How:** Update `CompilerLanguageServiceBridge` so it:
|
|
|
|
1. resolves completion candidates from local/import/member contexts;
|
|
2. resolves hover payloads from symbol identity, origin, and signatures;
|
|
3. resolves active call signatures for `signature help`.
|
|
|
|
This step must remove the current fixed hover placeholder.
|
|
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/**`.
|
|
|
|
### Step 3 - Announce and map protocol capabilities
|
|
|
|
**What:** Make the server advertise the new feature set and map payloads into lsp4j types.
|
|
**How:** Update protocol mappers and text-document service so the server announces:
|
|
|
|
1. `completionProvider`;
|
|
2. `signatureHelpProvider`;
|
|
3. improved `hoverProvider` backed by real payloads.
|
|
|
|
Map completion items, hover markdown, and signature-help structures into concrete LSP responses.
|
|
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/**`, `.../mapping/**`.
|
|
|
|
### Step 4 - Add transport and conformance tests
|
|
|
|
**What:** Prevent regression to placeholder/editor-local behavior.
|
|
**How:** Add tests that verify:
|
|
|
|
1. capabilities are announced correctly;
|
|
2. completion returns compiler-backed candidates;
|
|
3. hover no longer returns the baseline placeholder;
|
|
4. signature-help returns deterministic active-signature information.
|
|
|
|
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`.
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
|
|
- DTO/model invariants for completion, hover, and signature-help payloads.
|
|
- Mapper tests for lsp4j conversion.
|
|
|
|
### Integration Tests
|
|
|
|
- LSP request/response tests using realistic PBS snippets with locals, imports, and member access.
|
|
|
|
### Manual Verification
|
|
|
|
- Connect the VS Code extension and confirm server capabilities include completion and signature help.
|
|
- Confirm hover content changes with the hovered symbol rather than returning static baseline text.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] The LSP bridge exposes completion and signature-help operations in addition to diagnostics, hover, and semantic tokens.
|
|
- [ ] Hover is symbol-resolved and no longer hardcoded placeholder text.
|
|
- [ ] The server advertises completion and signature-help capabilities.
|
|
- [ ] Completion, hover, and signature help all derive from the same compiler-backed editorial surface.
|
|
|
|
## Dependencies
|
|
|
|
- `DEC-0035` accepted and normatively locked.
|
|
- `PLN-0075` for the shared compiler-backed editorial resolution surface.
|
|
|
|
## Risks
|
|
|
|
- Protocol mapping can drift from compiler payload shape if feature-specific shortcuts are added.
|
|
- Active parameter/signature calculation may be brittle around incomplete syntax unless request handling is conservative.
|
|
- Completion can feel noisy if candidate ranking or filtering is too weak in wave 1.
|