implements PLN-0111

This commit is contained in:
2026-07-15 11:22:38 +01:00
parent 3ee0da3c0a
commit b1e75973f9
19 changed files with 1154 additions and 45 deletions
@@ -0,0 +1,71 @@
---
id: PLN-0111
ticket: multi-frontend-remove-pbs-branches
title: Define generic frontend editorial DTOs and capability surface
status: done
created: 2026-07-15
completed: 2026-07-15
ref_decisions: [DEC-0042]
tags: [compiler, compiler-general, compiler-pbs, studio, frontend, coupling, multi-frontend]
---
## Briefing
`DEC-0042` requires the common LSP/editorial path to consume frontend-provided editorial capabilities through generic contracts exposed from `prometeu-frontend-api`. This plan creates the shared model surface before any LSP capability is migrated.
## Objective
Define the minimal generic frontend editorial API needed by LSP v1 without changing the provider contract: `FrontendProvider.compiler()` remains mandatory, `FrontendProvider.languageService()` remains optional, and compile-only frontends remain valid.
## Dependencies
- Requires accepted decision `DEC-0042`.
- Must complete before migrating completion, hover, signature help, or final PBS import removal.
## Scope
- Add generic editorial DTOs and capability methods under `prometeu-compiler/prometeu-frontend-api`.
- Keep the surface aggregated behind optional `FrontendProvider.languageService()`.
- Model empty/fallback behavior for unsupported capabilities.
- Keep frontend API independent from `prometeu-lsp`.
## Non-Goals
- Migrating `CompilerLanguageServiceBridge` behavior in this plan.
- Removing PBS imports from LSP in this plan.
- Adding plugin discovery, dynamic loading, RPC, sandboxing, or service locator infrastructure.
- Making `languageService()` mandatory.
## Execution Method
1. Inspect `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/FrontendProvider.java` and current `PBSFrontendLanguageService` to identify existing method shapes.
2. Add generic models under `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services` or a nearby frontend editorial package:
- `FrontendCompletionCandidate`
- `FrontendHover`
- `FrontendSignatureHelp`
- `FrontendSignature`
- `FrontendSymbolKind`
- `FrontendDocumentation`, only if documentation format must be explicit.
3. Add or update the frontend language service interface so the optional language-service surface can expose semantic tokens, completion, hover, and signature help using generic types.
4. Define deterministic defaults for missing capabilities, such as empty completion lists, empty semantic tokens, no hover, and empty signature help.
5. Keep DTOs free of LSP4J, PBS AST, PBS semantic, and Studio UI dependencies.
6. Add API-level tests or compile fixtures proving a provider can omit `languageService()`.
## Acceptance Criteria
- `prometeu-frontend-api` exposes generic editorial DTOs for current LSP v1 needs.
- The API does not import `prometeu-lsp`, LSP4J, or `p.studio.compiler.pbs.*`.
- `FrontendProvider.languageService()` remains optional.
- A compile-only provider still compiles without implementing editorial methods.
- The generic model can represent labels, details, kinds, Markdown/documentation, signatures, active signature, active parameter, and semantic token keys needed by PBS.
## Tests
- Frontend API compile/test task.
- Existing provider boundary tests.
- Compile-only provider fixture tests proving no language service remains valid.
## Affected Artifacts
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/...`
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/FrontendProviderBoundaryTest.java`
@@ -0,0 +1,98 @@
---
id: PLN-0112
ticket: multi-frontend-remove-pbs-branches
title: Migrate semantic tokens to generic frontend language service
status: open
created: 2026-07-15
ref_decisions: [DEC-0042]
tags: [compiler, compiler-general, compiler-pbs, studio, frontend, coupling, multi-frontend]
---
## Briefing
`DEC-0042` requires the LSP common path to project semantic token behavior from the selected frontend through generic frontend contracts. Semantic presentation already lives mostly in `FrontendSpec`, so this is the lowest-risk capability migration.
## Objective
Make LSP semantic token handling consume generic frontend language-service APIs while preserving frontend-owned semantic presentation and PBS semantic token behavior.
## Dependencies
- Depends on `PLN-0111` for the generic frontend editorial surface.
- Requires accepted decision `DEC-0042`.
## Scope
- Route semantic token requests through the provider's optional generic language service.
- Preserve `FrontendSpec.getSemanticPresentation()` as the source of token keys, host projections, themes, and default theme.
- Keep deterministic empty semantic tokens when a frontend has no language service or no semantic-token capability.
## Non-Goals
- Changing PBS semantic classification rules.
- Implementing semantic-token improvements from PBS-specific agendas.
- Migrating completion, hover, or signature help.
- Removing every PBS import from `CompilerLanguageServiceBridge`.
## Execution Method
1. Inspect `CompilerLanguageServiceBridge.semanticTokens(...)` and `PBSFrontendLanguageService.semanticTokens(...)`.
2. Add a generic semantic-token method to the frontend language-service surface if not already introduced by `PLN-0111`.
3. Adapt `PBSFrontendLanguageService` to return generic frontend semantic token records or a compatible generic token model.
4. Update `CompilerLanguageServiceBridge.semanticTokens(...)` to resolve `FrontendProvider` by `context.languageId()`, read presentation from `provider.specification()`, and call the generic semantic-token capability when present.
5. Ensure missing capability returns an empty token list with the frontend presentation legend.
6. Keep VS Code/LSP4J mapping inside `prometeu-lsp`.
## Acceptance Criteria
- LSP semantic token handling no longer needs PBS-specific language-service casts.
- Frontend semantic presentation remains frontend-owned.
- PBS semantic token regression tests continue to pass.
- Compile-only or no-language-service providers return deterministic empty semantic tokens.
## Tests
- Existing LSP semantic token tests.
- PBS frontend semantic presentation tests.
- Missing language-service fallback tests in `CompilerLanguageServiceBridgeTest`.
## Affected Artifacts
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSFrontendLanguageService.java`
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/...`
- LSP semantic-token tests.
TBD.
## Objective
TBD.
## Dependencies
TBD.
## Scope
TBD.
## Non-Goals
TBD.
## Execution Method
TBD.
## Acceptance Criteria
TBD.
## Tests
TBD.
## Affected Artifacts
TBD.
@@ -0,0 +1,98 @@
---
id: PLN-0113
ticket: multi-frontend-remove-pbs-branches
title: Migrate completion to generic frontend models
status: open
created: 2026-07-15
ref_decisions: [DEC-0042]
tags: [compiler, compiler-general, compiler-pbs, studio, frontend, coupling, multi-frontend]
---
## Briefing
`DEC-0042` requires completion to move from PBS-specific editorial models to generic frontend models while preserving PBS completion behavior and deterministic fallback for frontends without completion support.
## Objective
Migrate LSP completion handling to generic frontend completion models exposed through the selected provider's optional language service.
## Dependencies
- Depends on `PLN-0111`.
- Should run after `PLN-0112` so the bridge already has the provider/capability lookup pattern.
## Scope
- Map PBS completion candidates to generic `FrontendCompletionCandidate` values.
- Update LSP completion mapping to consume generic models.
- Preserve labels, details, kinds, origin/documentation fallback, and existing PBS behavior.
## Non-Goals
- Changing completion ranking or filtering.
- Expanding PBS completion depth.
- Migrating hover or signature help in this plan.
- Removing all PBS imports from LSP if hover/signature still depend on them.
## Execution Method
1. Inspect `PbsEditorialCompletionCandidate`, `PbsEditorialSymbolKind`, and LSP `mapCompletionItem(...)`.
2. Ensure `FrontendCompletionCandidate` can represent label, kind, detail, documentation, and origin or equivalent text.
3. Add PBS adapter code inside `PBSFrontendLanguageService` or the PBS frontend boundary to return generic completion candidates.
4. Update `CompilerLanguageServiceBridge.completion(...)` to call the generic completion capability through `FrontendProvider.languageService()`.
5. Replace PBS-specific completion-kind mapping with mapping from `FrontendSymbolKind` to `BaselineCompletionItemKind`.
6. Preserve empty completion fallback when language service or completion capability is absent.
## Acceptance Criteria
- LSP completion no longer consumes `PbsEditorialCompletionCandidate`.
- Completion kind mapping uses generic frontend kinds.
- Existing PBS completion tests pass without user-visible behavior changes.
- Missing capability returns a valid empty `BaselineCompletion`.
## Tests
- Existing PBS completion/editorial tests.
- `CompilerLanguageServiceBridgeTest` completion cases.
- Compile-only provider completion fallback test.
## Affected Artifacts
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/...`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSFrontendLanguageService.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java`
- Completion-related tests.
TBD.
## Objective
TBD.
## Dependencies
TBD.
## Scope
TBD.
## Non-Goals
TBD.
## Execution Method
TBD.
## Acceptance Criteria
TBD.
## Tests
TBD.
## Affected Artifacts
TBD.
@@ -0,0 +1,106 @@
---
id: PLN-0114
ticket: multi-frontend-remove-pbs-branches
title: Migrate hover and documentation to generic frontend models
status: open
created: 2026-07-15
ref_decisions: [DEC-0042]
tags: [compiler, compiler-general, compiler-pbs, studio, frontend, coupling, multi-frontend]
---
## Briefing
`DEC-0042` requires hover and documentation Markdown to be represented through generic frontend models so LSP does not know PBS semantic or documentation internals.
## Objective
Migrate LSP hover handling to generic frontend hover models while preserving PBS signature, kind, origin, detail, and Markdown documentation behavior.
## Dependencies
- Depends on `PLN-0111`.
- Should run after `PLN-0113` so generic symbol kinds and documentation fields are established.
## Scope
- Define or finalize generic hover/documentation DTOs.
- Map `PbsEditorialResolvedSymbol` to generic hover output inside the PBS boundary.
- Update LSP hover composition to consume generic values.
- Preserve Markdown output and existing no-symbol fallback.
## Non-Goals
- Changing the PBS `[Doc]` language feature.
- Reformatting authored Markdown.
- Implementing go-to-definition or references.
- Migrating signature help request handling, except for shared signature DTOs used in hover.
## Execution Method
1. Inspect `PbsEditorialResolvedSymbol`, `PbsEditorialSignature`, and `formatHoverMarkdown(...)`.
2. Ensure generic `FrontendHover` can represent:
- display name;
- symbol kind;
- detail;
- origin;
- signatures;
- documentation Markdown.
3. Add PBS mapping from `PbsEditorialResolvedSymbol` to `FrontendHover` inside the frontend language service.
4. Update `CompilerLanguageServiceBridge.hover(...)` to call generic hover capability and format generic hover values.
5. Keep Markdown composition deterministic: signature block, kind/origin metadata, then documentation.
6. Preserve empty/no-symbol fallback when hover capability is absent.
## Acceptance Criteria
- LSP hover no longer consumes `PbsEditorialResolvedSymbol`.
- PBS documentation Markdown appears unchanged in hover.
- Authored Markdown is not reflowed or reparsed by LSP.
- Missing capability returns deterministic no-symbol hover behavior.
## Tests
- PBS hover/editorial tests.
- LSP hover mapping tests asserting Markdown payloads.
- Documentation Markdown regression tests from `DEC-0039` coverage.
- Missing hover capability fallback test.
## Affected Artifacts
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/...`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSFrontendLanguageService.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java`
- Hover-related tests.
TBD.
## Objective
TBD.
## Dependencies
TBD.
## Scope
TBD.
## Non-Goals
TBD.
## Execution Method
TBD.
## Acceptance Criteria
TBD.
## Tests
TBD.
## Affected Artifacts
TBD.
@@ -0,0 +1,99 @@
---
id: PLN-0115
ticket: multi-frontend-remove-pbs-branches
title: Migrate signature help to generic frontend models
status: open
created: 2026-07-15
ref_decisions: [DEC-0042]
tags: [compiler, compiler-general, compiler-pbs, studio, frontend, coupling, multi-frontend]
---
## Briefing
`DEC-0042` requires signature help to be exposed through generic frontend models rather than PBS-specific editorial models.
## Objective
Migrate LSP signature help handling to generic frontend signature-help models while preserving PBS callable labels, parameter labels, active signature, and active parameter behavior.
## Dependencies
- Depends on `PLN-0111`.
- Should run after `PLN-0114` because hover and signature help may share generic signature DTOs.
## Scope
- Map PBS signature help to generic `FrontendSignatureHelp` and `FrontendSignature`.
- Update LSP signature-help mapping to consume generic models.
- Preserve deterministic empty signature help when unsupported.
## Non-Goals
- Changing PBS callable resolution.
- Changing parameter-name semantics.
- Adding parameter documentation beyond existing behavior.
- Removing all PBS imports from LSP if other capabilities are still pending.
## Execution Method
1. Inspect current `PBSFrontendLanguageService.signatureHelp(...)` and `PbsEditorialSignatureHelp`.
2. Ensure generic `FrontendSignatureHelp` represents signatures, active signature, active parameter, labels, and parameter labels.
3. Add PBS mapping to generic signature help inside the PBS frontend boundary.
4. Update `CompilerLanguageServiceBridge.signatureHelp(...)` to call generic signature-help capability.
5. Preserve empty response behavior for absent language service or absent signature-help capability.
6. Verify completion/hover shared signature models still satisfy their tests.
## Acceptance Criteria
- LSP signature help no longer consumes PBS-specific signature-help types.
- PBS signature-help output remains stable.
- Active signature and active parameter are preserved.
- Compile-only providers receive deterministic empty signature help.
## Tests
- PBS signature-help/editorial tests.
- LSP signature-help bridge tests.
- Missing capability fallback tests.
- Regression tests for callable parameter labels.
## Affected Artifacts
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/...`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSFrontendLanguageService.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java`
- Signature-help tests.
TBD.
## Objective
TBD.
## Dependencies
TBD.
## Scope
TBD.
## Non-Goals
TBD.
## Execution Method
TBD.
## Acceptance Criteria
TBD.
## Tests
TBD.
## Affected Artifacts
TBD.
@@ -0,0 +1,101 @@
---
id: PLN-0116
ticket: multi-frontend-remove-pbs-branches
title: Remove PBS imports from common LSP and add boundary coverage
status: open
created: 2026-07-15
ref_decisions: [DEC-0042]
tags: [compiler, compiler-general, compiler-pbs, studio, frontend, coupling, multi-frontend]
---
## Briefing
After generic editorial DTOs and LSP capabilities are migrated, `DEC-0042` requires the common LSP path to stop importing PBS implementation packages and to propagate enforcement to the architectural-tests track.
## Objective
Remove remaining PBS implementation imports from common LSP code and add regression coverage proving LSP uses frontend/provider contracts instead of PBS internals.
## Dependencies
- Depends on `PLN-0111` through `PLN-0115`.
- Coordinates with `AGD-0067` for broader architectural-test policy.
## Scope
- Remove `p.studio.compiler.pbs.*` imports from the common `CompilerLanguageServiceBridge` path.
- Remove direct use of `PbsAst.File`, `PbsEditorial*`, and `PBSFrontendPhaseService.semanticReadSurface(...)` from common LSP code.
- Add local boundary tests or feed the final rule into the architectural-tests discussion.
- Preserve PBS default/fallback behavior for no explicit language choice.
## Non-Goals
- Removing PBS from composition root, templates, fixtures, VS Code `.pbs` registration, semantic keys, or PBS frontend internals.
- Changing unknown `languageId` failure behavior.
- Introducing ArchUnit unless `AGD-0067` chooses it.
- Implementing new LSP features.
## Execution Method
1. Search `prometeu-lsp/prometeu-lsp-v1/src/main/java` for `p.studio.compiler.pbs`, `PbsAst`, `PbsEditorial`, and `PBSFrontendPhaseService`.
2. Replace remaining common-path dependencies with generic frontend language-service calls.
3. If any PBS adapter remains, move it behind an explicitly local adapter boundary and document why it is temporary.
4. Add or update tests using a compile-only or fake provider to prove semantic tokens, completion, hover, and signature help do not require PBS.
5. Add a simple import-boundary test if one can be implemented without new infrastructure; otherwise update `AGD-0067`/derived plan with the exact rule.
6. Run relevant LSP and PBS regression tests.
## Acceptance Criteria
- Common LSP production code does not import `p.studio.compiler.pbs.*`.
- Common LSP production code does not know `PbsAst.File`, `PbsEditorial*`, or `PBSFrontendPhaseService`.
- Unknown `languageId` still fails explicitly.
- PBS remains product default/fallback when no language is chosen.
- Tests prove missing language-service capabilities produce deterministic fallback responses.
- Architectural-test follow-up is recorded for any repository-wide import rule not implemented locally.
## Tests
- `prometeu-lsp` tests.
- PBS frontend editorial regression tests.
- Provider boundary tests with compile-only/fake providers.
- Import-boundary test for common LSP code if feasible.
## Affected Artifacts
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java`
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridgeTest.java`
- Architectural-test discussion or future plan from `AGD-0067`
TBD.
## Objective
TBD.
## Dependencies
TBD.
## Scope
TBD.
## Non-Goals
TBD.
## Execution Method
TBD.
## Acceptance Criteria
TBD.
## Tests
TBD.
## Affected Artifacts
TBD.