187 lines
8.7 KiB
Markdown
187 lines
8.7 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 dedicated semantic surface used for structural anchors and guide-aware editor structure,
|
|
- 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.
|
|
|
|
The phase may ship the dedicated structural-anchor surface after the baseline capability set is stable, but Studio and frontend implementations must treat that surface as the canonical source of exact scope-indicator anchoring once it exists.
|
|
|
|
The phase may also ship a dedicated inline-hint semantic surface.
|
|
|
|
Once shipped, frontend and Studio implementations must treat that surface as the canonical source of decorative inline hint payloads.
|
|
|
|
## 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.
|
|
|
|
## Inline Hint Ownership Rules
|
|
|
|
- frontend inline hints must come from semantic information provided through `prometeu-lsp`;
|
|
- frontend hint existence and hint payload semantics remain frontend-owned;
|
|
- `prometeu-lsp` must expose a dedicated transport contract for inline hints rather than relying on Studio-local inference;
|
|
- `prometeu-lsp` must preserve deterministic anchor information required for host rendering;
|
|
- `prometeu-lsp` must not invent host-owned hint policy when a frontend does not publish hints;
|
|
- Studio must render transported hints mechanically as host decorations rather than as document text;
|
|
- valid inline hint spans must survive partial degradation when the frontend can still produce them;
|
|
- invalid or missing hint spans may be omitted locally;
|
|
- Studio must not disable all inline hints for a document solely because some hint spans are unavailable.
|
|
|
|
## Structural Anchor Semantic Surface
|
|
|
|
Exact structural anchoring for editor scope indicators must not be overloaded into `documentSymbols`.
|
|
|
|
`documentSymbols` remains the outline and navigation surface.
|
|
|
|
Guide-oriented structure must be exposed through a dedicated semantic surface for structural anchors and related guide metadata.
|
|
|
|
That dedicated surface must be frontend-owned and language-agnostic.
|
|
|
|
The contract must describe generic structural positions rather than PBS-specific brace semantics.
|
|
|
|
The surface must be able to represent structures whose boundaries are expressed by:
|
|
|
|
- braces;
|
|
- keywords;
|
|
- indentation-derived blocks;
|
|
- or mixed delimiter schemes.
|
|
|
|
At minimum, the dedicated structural-anchor surface must be able to communicate:
|
|
|
|
- structural ranges that can participate in active-scope selection;
|
|
- immediate parentage or equivalent information needed to recover the nearest ancestor relationship;
|
|
- exact structural anchor positions used for guide start and end placement;
|
|
- enough structural identity to distinguish the active structural range from its immediate container.
|
|
|
|
The semantic-read contract must not require Studio to scan source text in order to discover the final structural anchor positions.
|
|
|
|
Temporary local heuristics may exist only as development aids. They must not become the canonical production contract.
|
|
|
|
The exact serialized schema of this dedicated surface may evolve in implementation plans, but any accepted schema must preserve the invariants above.
|
|
|
|
## 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
|
|
- Studio-owned semantic hint generation
|
|
|
|
## 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.
|