prometeu-studio/discussion/workflow/plans/PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md

id	ticket	title	status	created	completed	tags
PLN-0076	pbs-lsp-editor-assistance-wave-1	LSP Completion, Hover, and Signature Help over Editorial Resolution	open	2026-05-08		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.