140 lines
5.3 KiB
Markdown
140 lines
5.3 KiB
Markdown
---
|
|
id: PLN-0027
|
|
ticket: studio-frontend-owned-semantic-editor-presentation
|
|
title: Add frontend semantic presentation contract to FrontendSpec and expose it through LSP
|
|
status: review
|
|
created: 2026-04-02
|
|
completed:
|
|
tags:
|
|
- compiler
|
|
- frontend
|
|
- lsp
|
|
- contract
|
|
- semantic-highlighting
|
|
---
|
|
|
|
## Objective
|
|
|
|
Implement the frontend-owned semantic presentation contract in `FrontendSpec` and expose a derived descriptor through LSP without collapsing frontend semantics into host-owned categories.
|
|
|
|
## Background
|
|
|
|
`DEC-0012` requires:
|
|
|
|
- static contract data in `FrontendSpec`;
|
|
- a simple descriptor containing `semanticKeys + resources`;
|
|
- frontend-owned semantic vocabulary using stable `semanticKey` values;
|
|
- LSP as a hub that derives and exposes the descriptor to Studio;
|
|
- no generic semantic-key reduction such as `fe-keyword`.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- `FrontendSpec` contract model additions.
|
|
- FE-specific publication of semantic keys and semantic presentation resources.
|
|
- Replacement of generic LSP semantic key emission with frontend-owned keys.
|
|
- LSP descriptor derivation and API exposure.
|
|
- FE-side tests covering contract presence and consistency.
|
|
|
|
### Excluded
|
|
- Studio CSS application changes.
|
|
- Studio presentation registry migration.
|
|
- Removal of legacy Studio stylesheets, except where required to avoid compile/runtime conflicts.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Extend FrontendSpec with semantic presentation contract
|
|
|
|
**What:**
|
|
Add a static semantic presentation contract to `FrontendSpec`.
|
|
|
|
**How:**
|
|
Introduce a dedicated descriptor type that carries frontend-owned `semanticKeys + resources`, wire it into `FrontendSpec`, and keep `FrontendSpec` static and frontend-owned.
|
|
|
|
**File(s):**
|
|
- `prometeu-compiler/prometeu-frontend-api/src/main/java/.../FrontendSpec.java`
|
|
- any adjacent model files needed for the new descriptor type
|
|
|
|
### Step 2 - Publish PBS semantic vocabulary and resources through FrontendSpec
|
|
|
|
**What:**
|
|
Make PBS publish frontend-owned semantic keys and highlight resources.
|
|
|
|
**How:**
|
|
Add a frontend-owned semantic vocabulary model such as `PbsSemanticKind -> semanticKey`, publish the resulting semantic presentation contract from PBS frontend definitions, and point the descriptor to FE-owned resources.
|
|
|
|
**File(s):**
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSDefinitions.java`
|
|
- PBS semantic analysis/indexing files that currently assign generic `fe-*` categories
|
|
- FE resource directory under the PBS frontend module
|
|
|
|
### Step 3 - Remove generic semantic key collapse in LSP
|
|
|
|
**What:**
|
|
Stop translating frontend semantics into host-owned generic semantic keys.
|
|
|
|
**How:**
|
|
Replace `fe-keyword`, `fe-type`, and similar outputs with frontend-owned semantic keys coming from frontend semantic vocabulary and/or `FrontendSpec` contract data.
|
|
|
|
**File(s):**
|
|
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java`
|
|
- any LSP DTO/message models that need to surface the descriptor
|
|
|
|
### Step 4 - Expose descriptor from analysis to Studio-facing LSP results
|
|
|
|
**What:**
|
|
Expose a Studio-consumable descriptor derived from the resolved `FrontendSpec`.
|
|
|
|
**How:**
|
|
Derive the descriptor during analysis/session creation and include it in the LSP surface that Studio consumes for semantic highlight application.
|
|
|
|
**File(s):**
|
|
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticReadPhase.java`
|
|
- `prometeu-lsp/prometeu-lsp-api/src/main/java/...` messages/DTOs
|
|
- any semantic session models involved in transport
|
|
|
|
### Step 5 - Add FE contract tests
|
|
|
|
**What:**
|
|
Verify the FE contract is present and coherent.
|
|
|
|
**How:**
|
|
Add frontend tests that fail when semantic presentation contract data is missing, when semantic keys are not published, or when published resources do not match the FE contract shape expectations.
|
|
|
|
**File(s):**
|
|
- PBS frontend tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/...`
|
|
- frontend-api tests if `FrontendSpec` invariants are enforced there
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- `FrontendSpec` tests for semantic presentation descriptor presence and shape.
|
|
- PBS frontend tests for semantic key publication.
|
|
- LSP tests for transport of frontend-owned semantic keys and descriptor data.
|
|
|
|
### Integration Tests
|
|
- Analyze a PBS file through LSP and assert that returned semantic highlights use PBS-owned semantic keys.
|
|
- Assert that the descriptor surfaced to the consumer contains the expected `semanticKeys + resources`.
|
|
|
|
### Manual Verification
|
|
- Inspect LSP payloads/logs to confirm there is no remaining `fe-*` semantic key collapse for PBS.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `FrontendSpec` exposes a static semantic presentation contract.
|
|
- [ ] PBS publishes semantic keys and resources through that contract.
|
|
- [ ] LSP no longer emits generic host-owned semantic keys for PBS.
|
|
- [ ] LSP exposes a descriptor derived from resolved `FrontendSpec`.
|
|
- [ ] FE tests cover missing contract data and contract consistency.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `DEC-0012`.
|
|
- Should land before Studio consumption changes in `PLN-0028`.
|
|
|
|
## Risks
|
|
|
|
- Existing semantic indexing code is currently host-owned and may require a larger refactor than expected.
|
|
- DTO surface changes can ripple through Studio and tests.
|
|
- Resource publication conventions may be inconsistent across future frontends if not modeled cleanly now.
|