108 lines
4.2 KiB
Markdown
108 lines
4.2 KiB
Markdown
---
|
|
id: PLN-0034
|
|
ticket: studio-editor-inline-type-hints-for-let-bindings
|
|
title: LSP inline hint transport contract
|
|
status: done
|
|
created: 2026-04-03
|
|
completed: 2026-04-03
|
|
tags: [lsp, studio, editor, inline-hints, dto, transport]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Implement the LSP transport contract that enforces and delivers frontend-owned inline hint payloads to Studio consumers.
|
|
|
|
## Background
|
|
|
|
DEC-0015 requires the LSP to fix and transport the inline hint contract while preserving frontend ownership of hint content and anchor semantics. The Studio must consume transported hints mechanically, and valid spans must survive partial degradation.
|
|
|
|
Current LSP surfaces carry diagnostics, symbols, structural anchors, and semantic highlighting, but no dedicated inline hint payload.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Add a dedicated inline hint DTO/message surface to `prometeu-lsp-api`.
|
|
- Extend semantic session and analyze-result transport to include inline hint payloads.
|
|
- Ensure partial valid hints survive transport even when analysis is partially degraded.
|
|
- Add LSP tests for contract shape and partial preservation.
|
|
|
|
### Excluded
|
|
- Frontend production of hint payloads.
|
|
- Studio rendering.
|
|
- Final editor substrate changes.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Define public DTOs for inline hint payloads
|
|
|
|
**What:** Add public API DTOs/messages for inline hint transport.
|
|
|
|
**How:** Introduce explicit payload shapes in `prometeu-lsp-api` that cover at minimum:
|
|
- anchor location or anchor span;
|
|
- display text;
|
|
- optional semantic category/styling fields if required by the contract;
|
|
- enough information for decorative-only host rendering.
|
|
|
|
The contract must remain frontend-content-preserving and must not encode Studio-owned hint policy.
|
|
|
|
**File(s):**
|
|
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/dtos/`
|
|
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/messages/`
|
|
|
|
### Step 2 - Extend semantic session construction and analyze responses
|
|
|
|
**What:** Make `prometeu-lsp-v1` collect and return inline hints in the semantic-read result.
|
|
|
|
**How:** Update semantic session building and analyze-result assembly so inline hints are returned alongside diagnostics, symbols, structural anchors, and semantic highlights.
|
|
|
|
Transport must preserve valid hint payloads even if some hint production fails locally elsewhere in the same document.
|
|
|
|
**File(s):**
|
|
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticReadPhase.java`
|
|
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticAnalyseService.java`
|
|
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/`
|
|
|
|
### Step 3 - Add transport contract tests
|
|
|
|
**What:** Lock the LSP contract behavior with focused tests.
|
|
|
|
**How:** Add tests that verify:
|
|
- analyze responses can carry inline hints;
|
|
- hint payloads preserve anchors and text deterministically;
|
|
- valid hints survive partial degradation;
|
|
- no host-owned inference is inserted by the LSP when the frontend does not publish hints.
|
|
|
|
**File(s):**
|
|
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/`
|
|
- `prometeu-lsp/prometeu-lsp-api/src/test/java/` if DTO/API conformance tests are needed
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- DTO invariants for inline hint payloads.
|
|
- Session/result assembly tests for non-empty and empty hint payloads.
|
|
|
|
### Integration Tests
|
|
- Analyze-document tests covering partial valid hints under degraded analysis.
|
|
|
|
### Manual Verification
|
|
- Inspect serialized/analyzed LSP results for a PBS document with inferred `let` types.
|
|
- Confirm no hint appears when the frontend publishes none.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [x] `prometeu-lsp-api` exposes a dedicated inline hint transport contract.
|
|
- [x] `prometeu-lsp-v1` returns inline hints through analyze results without inventing content.
|
|
- [x] Partial valid hints survive transport under degraded analysis.
|
|
- [x] Tests lock the contract shape and preservation rules.
|
|
|
|
## Dependencies
|
|
|
|
- Accepted decision `DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md`
|
|
- `PLN-0033-inline-hint-spec-and-contract-propagation.md`
|
|
|
|
## Risks
|
|
|
|
- DTO under-design may force churn once Studio rendering starts.
|
|
- Folding inline hints into an existing message surface without clear boundaries may create avoidable API ambiguity.
|