bQUARKz
a62ddb0f74
Some checks are pending
Intrepid/Prometeu/Studio/pipeline/head Build started...
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 61.73% (17588/28493)
* Branch Coverage: 52.44% (6777/12924)
* Lines of Code: 28493
* Cyclomatic Complexity: 11423
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 616
93 lines
4.4 KiB
Markdown
93 lines
4.4 KiB
Markdown
---
|
|
id: LSN-0058
|
|
ticket: multi-frontend-remove-pbs-branches
|
|
title: Generic Frontend Editorial Contract for LSP
|
|
created: 2026-07-15
|
|
tags: [compiler, compiler-general, compiler-pbs, studio, frontend, lsp, coupling, multi-frontend]
|
|
---
|
|
|
|
## Original Problem
|
|
|
|
Prometeu was preparing for multiple compiler frontends while the LSP bridge still knew too much about PBS internals. The first framing was broad: remove explicit PBS checks from common code. After inspection, that was too blunt.
|
|
|
|
PBS was already mostly centered in `prometeu-frontend-pbs`. Defaults, templates, `.pbs` fixtures, VS Code language registration, semantic keys, and composition-root bootstrap were legitimate PBS references. The real architectural problem was narrower: common LSP code imported and called PBS-specific editorial types and services for semantic tokens, completion, hover, signature help, and semantic read preparation.
|
|
|
|
## Consolidated Decision
|
|
|
|
The common LSP/editorial path must consume frontend-provided editorial capabilities through generic contracts exposed by `prometeu-frontend-api`.
|
|
|
|
The provider contract remains stable:
|
|
|
|
1. `FrontendProvider.compiler()` is mandatory.
|
|
2. `FrontendProvider.languageService()` is optional.
|
|
3. Compile-only frontends are valid.
|
|
4. Unknown `languageId` values fail explicitly.
|
|
5. PBS may be the product default only when the user has not chosen a language.
|
|
|
|
PBS is not the shared editor model. PBS implements the generic contract from inside its frontend boundary.
|
|
|
|
## Final Implementation Shape
|
|
|
|
The implementation introduced generic frontend editorial DTOs and default methods in `FrontendLanguageService`:
|
|
|
|
1. `FrontendDocumentRequest`
|
|
2. `FrontendEditorialContext`
|
|
3. `FrontendCompletionCandidate`
|
|
4. `FrontendHover`
|
|
5. `FrontendSignatureHelp`
|
|
6. `FrontendSignature`
|
|
7. `FrontendSymbolKind`
|
|
8. `FrontendDocumentation`
|
|
|
|
`CompilerLanguageServiceBridge` now resolves the selected provider and calls generic `FrontendLanguageService` methods for semantic tokens, completion, hover, and signature help.
|
|
|
|
PBS-specific analysis setup moved behind `PBSFrontendLanguageService.prepareEditorialContext(...)`. The bridge no longer imports `p.studio.compiler.pbs.*`, no longer knows `PbsAst.File`, and no longer calls `PBSFrontendPhaseService.semanticReadSurface(...)` directly.
|
|
|
|
An architectural test now protects the common LSP code from reintroducing PBS implementation imports.
|
|
|
|
## Examples
|
|
|
|
A frontend with no language service remains valid:
|
|
|
|
```java
|
|
public final class CompileOnlyFrontendProvider implements FrontendProvider {
|
|
@Override
|
|
public FrontendSpec specification() {
|
|
return SPEC;
|
|
}
|
|
|
|
@Override
|
|
public FrontendPhaseService compiler() {
|
|
return compiler;
|
|
}
|
|
}
|
|
```
|
|
|
|
An LSP consumer should resolve the selected provider, ask for `languageService()`, and fall back deterministically when editorial capability is absent.
|
|
|
|
PBS can still keep rich internal models such as `PbsEditorialResolvedSymbol`, but those models must be mapped to generic `FrontendHover`, `FrontendCompletionCandidate`, or `FrontendSignatureHelp` before common LSP consumes them.
|
|
|
|
## Pitfalls
|
|
|
|
Do not remove legitimate PBS defaults just because they mention PBS. PBS remains the product default when the user has not chosen another language.
|
|
|
|
Do not use PBS as a fallback for unknown `languageId`. Unknown language identity is a configuration error and must fail explicitly.
|
|
|
|
Do not make editor assistance mandatory. Compilation and editor support are separate frontend capabilities.
|
|
|
|
Do not move frontend semantic ownership into LSP or Studio. The LSP bridge transports frontend-owned editorial results; it does not author language semantics.
|
|
|
|
Do not reintroduce PBS imports in common LSP code for convenience. If a capability needs PBS-specific state, create or extend a frontend-owned generic boundary and keep the PBS mapping inside `prometeu-frontend-pbs`.
|
|
|
|
## References
|
|
|
|
- `DEC-0042` locked the generic frontend editorial language-service contract.
|
|
- `PLN-0111` introduced generic frontend editorial DTOs and defaults.
|
|
- `PLN-0112` migrated semantic tokens.
|
|
- `PLN-0113` migrated completion.
|
|
- `PLN-0114` migrated hover and documentation.
|
|
- `PLN-0115` migrated signature help.
|
|
- `PLN-0116` removed PBS imports from common LSP and added boundary coverage.
|
|
- Related lesson: `LSN-0055` Static frontend providers before plugin architecture.
|
|
- Related lesson: `LSN-0056` Compile-first frontends with optional editorial capabilities.
|