135 lines
5.8 KiB
Markdown
135 lines
5.8 KiB
Markdown
# Integrated LSP Semantic Read Phase Specification
|
|
|
|
## Status
|
|
|
|
Active
|
|
|
|
## Applies To
|
|
|
|
- `prometeu-studio`
|
|
- `prometeu-vfs`
|
|
- `prometeu-lsp`
|
|
- the frontend read-only semantic phase in the Studio `Code Editor` workspace
|
|
|
|
## Purpose
|
|
|
|
Define the normative Studio contract for the integrated frontend semantic-read phase that arrives before any frontend editing release.
|
|
|
|
This specification stabilizes:
|
|
|
|
- the phase boundary between semantic read and frontend editing,
|
|
- the ownership relationship between `prometeu-vfs`, `prometeu-lsp`, and the Studio editor,
|
|
- the minimum semantic capability set for frontend documents,
|
|
- the packaging expectations for the public `prometeu-lsp` API surface,
|
|
- and the explicit exclusions that remain outside this phase.
|
|
|
|
## Authority and Precedence
|
|
|
|
This specification extends:
|
|
|
|
- [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md)
|
|
- [`6. Project Document VFS Specification.md`](6.%20Project%20Document%20VFS%20Specification.md)
|
|
|
|
If this document conflicts with shell-wide Studio rules, shell rules control shell behavior, the Code Editor specification controls workspace-local editor UX, the VFS specification controls document-boundary ownership, and this document controls the integrated semantic-read phase itself.
|
|
|
|
## Normative Inputs
|
|
|
|
The integrated semantic-read phase must assume:
|
|
|
|
- frontend-scoped documents remain hard `read-only`,
|
|
- editable non-frontend documents remain governed by the controlled write wave,
|
|
- `FrontendSpec.allowedExtensions` remains the source of truth for frontend scope,
|
|
- `FrontendSpec` is the canonical source of frontend semantic presentation contract data,
|
|
- `prometeu-vfs` owns document state, snapshots, persistence, and access policy,
|
|
- and semantic-read over editorial snapshots must remain separate from build-facing ownership.
|
|
|
|
## Phase Boundary
|
|
|
|
This phase is a semantic-read phase for frontend documents, not a frontend editing phase.
|
|
|
|
Rules:
|
|
|
|
- frontend documents must remain hard `read-only` throughout this phase;
|
|
- no capability in this phase may imply frontend save, mutation, or edit-right release;
|
|
- the future release of frontend editing requires a separate explicit decision;
|
|
- completion, rename, code actions, and formatting remain outside this phase.
|
|
|
|
## Ownership Rules
|
|
|
|
- `prometeu-vfs` owns document state, access policy, editorial snapshots, and persistence.
|
|
- `prometeu-lsp` is a semantic consumer above `prometeu-vfs`.
|
|
- the Studio `Code Editor` owns UX surfaces that render semantic-read output.
|
|
- each frontend owns its semantic vocabulary and semantic presentation resources.
|
|
- build-facing document ownership remains outside this phase.
|
|
|
|
`prometeu-lsp` must not become the owner of:
|
|
|
|
- save,
|
|
- persistence,
|
|
- document access policy,
|
|
- frontend semantic presentation assets,
|
|
- or frontend edit-right release.
|
|
|
|
## Document Source-of-Truth Rules
|
|
|
|
- opened frontend documents must be analyzed from the in-memory snapshot exposed by `prometeu-vfs`;
|
|
- unopened frontend documents may be analyzed from filesystem-backed state exposed through the same `prometeu-vfs` boundary;
|
|
- Studio UI code must not bypass `prometeu-vfs` with ad hoc file loading for semantic-read behavior;
|
|
- semantic-read over editorial snapshots must not be treated as canonical build input by implication.
|
|
|
|
## Minimum Capability Set
|
|
|
|
The minimum semantic capability set of this phase must include:
|
|
|
|
- diagnostics for frontend documents;
|
|
- document symbols for frontend documents;
|
|
- workspace symbols for frontend documents;
|
|
- outline-facing structural symbol data;
|
|
- go-to-definition for frontend documents;
|
|
- frontend semantic highlight.
|
|
|
|
## Highlight Ownership Rules
|
|
|
|
- frontend highlight must come from semantic information provided through `prometeu-lsp`;
|
|
- frontend highlight must use frontend-owned semantic presentation contract data derived from `FrontendSpec`;
|
|
- `prometeu-lsp` must expose a dedicated semantic presentation descriptor derived from the resolved `FrontendSpec`;
|
|
- that descriptor must remain simple and include frontend-owned `semanticKeys` plus frontend-owned `resources` in the same message surface;
|
|
- `prometeu-lsp` must not collapse frontend semantic keys into host-owned generic categories;
|
|
- Studio must project semantic keys mechanically to CSS classes without semantic translation;
|
|
- frontend semantic presentation resources must remain under frontend `resources/` and be resolved like ordinary Java resources;
|
|
- when semantic presentation descriptor data or usable resources are absent, Studio must continue without semantic highlight;
|
|
- this condition must not become a product-facing Studio error and may at most produce normal development logs;
|
|
- non-frontend highlight may remain on the existing Studio-local highlighting path in this phase.
|
|
|
|
## Packaging Rules
|
|
|
|
The public `prometeu-lsp` API should follow flat packaging similar to `prometeu-packer-api`.
|
|
|
|
Rules:
|
|
|
|
- public contract surfaces should remain shallow and explicit;
|
|
- packages such as `dtos`, `messages`, and `events` are the preferred shape for public API grouping where those surfaces exist;
|
|
- deep public packaging by internal implementation concern should be avoided;
|
|
- runtime or implementation layering may exist internally, but it must not leak into the public contract surface by default.
|
|
|
|
## Non-Goals
|
|
|
|
- frontend editing
|
|
- frontend save policy
|
|
- completion
|
|
- rename
|
|
- code actions
|
|
- formatting
|
|
- build participation inferred from editorial snapshots
|
|
- external-editor compatibility requirements
|
|
|
|
## Exit Criteria
|
|
|
|
This specification is complete enough when:
|
|
|
|
- the semantic-read versus frontend-editing phase boundary is explicit,
|
|
- `prometeu-vfs` and `prometeu-lsp` ownership remains unambiguous,
|
|
- the minimum semantic capability set is explicit,
|
|
- frontend and non-frontend highlight ownership is clearly separated,
|
|
- and the excluded editing and completion capabilities remain unambiguous.
|