implements PLN-0107
This commit is contained in:
parent
6fdb4828c3
commit
6cd24bf14f
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -1,4 +1,4 @@
|
||||
{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":41,"PLN":107,"LSN":56,"CLSN":1}}
|
||||
{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":42,"PLN":111,"LSN":56,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0065","status":"open","ticket":"multi-frontend-avoid-premature-abstractions","title":"Evitar abstracoes prematuras na preparacao multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","multi-frontend","simplicity"],"agendas":[{"id":"AGD-0068","file":"AGD-0068-multi-frontend-avoid-premature-abstractions.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0064","status":"open","ticket":"multi-frontend-architectural-tests","title":"Testes arquiteturais para fronteiras multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","tests","multi-frontend"],"agendas":[{"id":"AGD-0067","file":"AGD-0067-multi-frontend-architectural-tests.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0063","status":"open","ticket":"multi-frontend-synthetic-test-frontend","title":"Frontend sintetico de teste para provar neutralidade do pipeline","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","frontend","tests","backend","multi-frontend"],"agendas":[{"id":"AGD-0066","file":"AGD-0066-multi-frontend-synthetic-test-frontend.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
@ -9,7 +9,7 @@
|
||||
{"type":"discussion","id":"DSC-0058","status":"open","ticket":"multi-frontend-serializable-ir","title":"Manter a IR comum serializavel por design","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","ir","backend","serialization","multi-frontend"],"agendas":[{"id":"AGD-0061","file":"AGD-0061-multi-frontend-serializable-ir.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0057","status":"open","ticket":"multi-frontend-frontend-backend-contract","title":"Estabilizar contrato entre frontend e backend comum","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","ir","backend","multi-frontend"],"agendas":[{"id":"AGD-0060","file":"AGD-0060-multi-frontend-frontend-backend-contract.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0056","status":"open","ticket":"multi-frontend-remove-pbs-branches","title":"Remover verificacoes explicitas de PBS do codigo comum","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","studio","frontend","coupling","multi-frontend"],"agendas":[{"id":"AGD-0059","file":"AGD-0059-multi-frontend-remove-pbs-branches.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0055","status":"open","ticket":"multi-frontend-compiler-vs-language-services","title":"Separar compilacao de servicos editoriais de frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","lsp","editor","frontend","multi-frontend"],"agendas":[{"id":"AGD-0058","file":"AGD-0058-multi-frontend-compiler-vs-language-services.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0055","status":"in_progress","ticket":"multi-frontend-compiler-vs-language-services","title":"Separar compilacao de servicos editoriais de frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","lsp","editor","frontend","multi-frontend"],"agendas":[{"id":"AGD-0058","file":"AGD-0058-multi-frontend-compiler-vs-language-services.md","status":"accepted","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[{"id":"DEC-0041","file":"DEC-0041-separate-frontend-compilation-from-editorial-language-services.md","status":"accepted","created_at":"2026-07-15","updated_at":"2026-07-15","ref_agenda":"AGD-0058"}],"plans":[{"id":"PLN-0107","file":"PLN-0107-specify-frontend-compiler-and-editorial-capability-boundary.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0041"]},{"id":"PLN-0108","file":"PLN-0108-move-pbs-editor-assistance-behind-optional-language-service.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0041"]},{"id":"PLN-0109","file":"PLN-0109-make-lsp-editorial-calls-capability-aware.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0041"]},{"id":"PLN-0110","file":"PLN-0110-add-compile-only-frontend-and-absent-capability-conformance-coverage.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0041"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0054","status":"done","ticket":"multi-frontend-provider-contract","title":"Introduzir provider completo de frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","registry","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0055","file":"discussion/lessons/DSC-0054-multi-frontend-provider-contract/LSN-0055-static-frontend-providers-before-plugin-architecture.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||
{"type":"discussion","id":"DSC-0053","status":"open","ticket":"pbs-lsp-call-and-type-hierarchy","title":"PBS LSP Call and Type Hierarchy","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","call-hierarchy","type-hierarchy"],"agendas":[{"id":"AGD-0056","file":"AGD-0056-pbs-lsp-call-and-type-hierarchy.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0052","status":"open","ticket":"pbs-lsp-document-links","title":"PBS LSP Document Links","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","document-links","imports"],"agendas":[{"id":"AGD-0055","file":"AGD-0055-pbs-lsp-document-links.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
id: AGD-0058
|
||||
ticket: multi-frontend-compiler-vs-language-services
|
||||
title: Separar compilacao de servicos editoriais de frontend
|
||||
status: open
|
||||
status: accepted
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
|
||||
@ -0,0 +1,104 @@
|
||||
---
|
||||
id: DEC-0041
|
||||
ticket: multi-frontend-compiler-vs-language-services
|
||||
title: Separate frontend compilation from editorial language services
|
||||
status: accepted
|
||||
created: 2026-07-15
|
||||
ref_agenda: AGD-0058
|
||||
tags: [compiler, compiler-general, studio, lsp, editor, frontend, multi-frontend]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Prometeu is preparing the compiler and editor stack for multiple frontends. PBS currently provides compilation and rich editor assistance, and existing LSP/Studio paths can still assume that diagnostics, semantic tokens, completion, hover, and signature help are all backed by the PBS frontend implementation.
|
||||
|
||||
This decision belongs to domain owner `compiler/general`.
|
||||
|
||||
Touched subdomains:
|
||||
|
||||
- `studio/lsp`
|
||||
- `compiler/pbs`
|
||||
|
||||
The existing API already points in the right direction: `FrontendProvider` exposes mandatory compiler behavior through `compiler()` and optional editor behavior through `languageService()`. However, the LSP bridge still contains PBS-specific editorial logic, so the boundary needs to be made normative before implementation plans migrate consumers.
|
||||
|
||||
This decision resolves `AGD-0058`.
|
||||
|
||||
## Decision
|
||||
|
||||
Frontend compilation and editorial language services MUST be separate contracts.
|
||||
|
||||
Every frontend MUST provide a compiler contract. A frontend MAY provide editorial language services. A frontend that can compile but does not provide completion, hover, definition, signature help, semantic tokens, or other editor assistance MUST still be considered a valid frontend.
|
||||
|
||||
`FrontendProvider.compiler()` is the required frontend capability. It MUST remain sufficient for build, analyze, compile, and backend-facing pipeline flows.
|
||||
|
||||
`FrontendProvider.languageService()` is the optional editorial capability boundary. The absence of a language service MUST NOT prevent compilation, project analysis, or backend execution.
|
||||
|
||||
The first common editorial contract SHOULD remain aggregated as `FrontendLanguageService` plus explicit capabilities, rather than immediately splitting every feature into separate top-level service interfaces. Smaller feature interfaces MAY be introduced later when implementation pressure proves that independent ownership, testing, or lifecycle is needed.
|
||||
|
||||
LSP and Studio consumers MUST query editorial capability availability before invoking editor-specific behavior. They MUST NOT assume that a frontend with a compiler also supports completion, hover, definition, semantic tokens, signature help, formatting, rename, code actions, or similar editor features.
|
||||
|
||||
When an editorial capability is absent, LSP and Studio MUST degrade gracefully:
|
||||
|
||||
- collection-shaped responses SHOULD be empty;
|
||||
- scalar optional responses SHOULD be absent or use a documented neutral response;
|
||||
- protocol-level unsupported behavior SHOULD be explicit when the host protocol supports that distinction;
|
||||
- absence MUST NOT be reported as a compiler failure.
|
||||
|
||||
PBS MAY continue to expose the rich editorial behavior it has today. That behavior is a PBS-provided capability, not a requirement imposed on all future frontends.
|
||||
|
||||
Compiler diagnostics and editorial diagnostics MUST remain distinct concepts. Build/analyze diagnostics belong to the compiler contract. Editorial diagnostics MAY reuse compiler analysis results, but a frontend MUST NOT be required to provide a separate editor diagnostics service in order to compile.
|
||||
|
||||
Semantic presentation metadata, such as frontend-owned semantic token vocabularies and visual themes, remains frontend-owned presentation data. Producing semantic tokens for a live document is an editorial capability and MUST be optional unless a future decision narrows that requirement for a specific host.
|
||||
|
||||
The LSP implementation SHOULD migrate from direct PBS editorial calls toward resolving the active frontend provider and consulting its optional language-service capabilities. Until that migration is planned and implemented, PBS-specific bridge code is tolerated as legacy coupling, not as the normative architecture.
|
||||
|
||||
## Rationale
|
||||
|
||||
Multi-frontend support requires a low floor: a new language frontend should be able to join the build pipeline before it has IDE-grade assistance. Requiring all editor features up front would turn frontend adoption into a large all-or-nothing task and would couple compiler correctness to UX completeness.
|
||||
|
||||
Keeping the first editorial boundary aggregated avoids premature interface explosion. The codebase already has a marker `FrontendLanguageService`, while the real uncertainty is how LSP/Studio should discover and handle absent capabilities. Capability negotiation solves that problem without forcing a final taxonomy before there is enough implementation evidence.
|
||||
|
||||
Separating compiler diagnostics from editorial diagnostics protects latency and ownership boundaries. Build diagnostics can be produced as part of normal analysis, while editor diagnostics may need live overlays, partial results, cancellation, caching, or host-specific behavior.
|
||||
|
||||
PBS should remain the reference rich frontend, but it should not define the minimum contract for all future languages. Treating PBS editor support as optional capability data makes the current implementation useful without freezing PBS assumptions into the common compiler API.
|
||||
|
||||
## Implications
|
||||
|
||||
- Common compiler code MUST depend on the compiler capability, not on PBS-specific frontend services.
|
||||
- LSP/Studio code that invokes editor behavior MUST handle absent capabilities deterministically.
|
||||
- Existing PBS editor assistance should be preserved while being moved behind the common optional language-service boundary over time.
|
||||
- Future frontend tests should include at least one compile-capable frontend with no language service.
|
||||
- Future LSP/Studio tests should prove that absent capabilities produce empty or unsupported responses rather than build failures.
|
||||
- Introducing smaller editorial interfaces is allowed later, but only after a plan identifies real feature lifecycle boundaries.
|
||||
- Plans derived from this decision MUST NOT reinterpret optional editorial services as required for frontend validity.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
- specs:
|
||||
- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
|
||||
- A future compiler/frontend provider contract spec if one is created.
|
||||
- LSP/editor-facing specs if/when a dedicated Studio/LSP spec surface exists.
|
||||
- plans:
|
||||
- Create a plan to specify the frontend provider/editorial capability boundary.
|
||||
- Create a plan to migrate LSP/Studio consumers away from direct PBS editorial assumptions.
|
||||
- code:
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/FrontendProvider.java`
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/FrontendLanguageService.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java`
|
||||
- PBS frontend editorial support classes.
|
||||
- tests:
|
||||
- Frontend provider tests proving compilation works without a language service.
|
||||
- LSP/Studio tests for absent completion, hover, signature help, semantic tokens, and future editorial capabilities.
|
||||
- Regression tests proving PBS still exposes current editorial behavior.
|
||||
- docs:
|
||||
- Specs updated by implementation plans.
|
||||
- Lessons generated after implementation and housekeeping.
|
||||
|
||||
## References
|
||||
|
||||
- Agenda: AGD-0058
|
||||
- Source discussion: DSC-0055
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-07-15: Initial decision drafted from accepted `AGD-0058`.
|
||||
@ -0,0 +1,68 @@
|
||||
---
|
||||
id: PLN-0107
|
||||
ticket: multi-frontend-compiler-vs-language-services
|
||||
title: Specify frontend compiler and editorial capability boundary
|
||||
status: done
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0041]
|
||||
tags: [compiler, compiler-general, studio, lsp, editor, frontend, multi-frontend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0041` makes compilation mandatory and editorial language services optional for every frontend. This plan updates the normative compiler-facing documentation so future implementation work has a precise boundary to follow.
|
||||
|
||||
## Objective
|
||||
|
||||
Document the frontend provider contract: compiler capability is required, editorial capabilities are optional, and absent editorial support must not invalidate build, analyze, compile, or backend flows.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Accepted decision: `DEC-0041`.
|
||||
- Existing `FrontendProvider.compiler()` and `FrontendProvider.languageService()` API shape.
|
||||
- Existing compiler pipeline entrypoint specification.
|
||||
|
||||
## Scope
|
||||
|
||||
- Update compiler specs to state that `FrontendProvider.compiler()` is the required frontend capability.
|
||||
- Define `FrontendProvider.languageService()` as the optional editorial capability boundary.
|
||||
- Document expected fallback behavior for absent editorial capabilities at the compiler/LSP boundary.
|
||||
- Document that build/analyze diagnostics are compiler diagnostics, while editor diagnostics are optional editorial behavior.
|
||||
- Add a short capability vocabulary for completion, hover, definition, signature help, semantic tokens, formatting, rename, and code actions without requiring all of them to exist now.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Implement Java API changes.
|
||||
- Migrate PBS editor assistance.
|
||||
- Change LSP behavior.
|
||||
- Split `FrontendLanguageService` into many top-level interfaces.
|
||||
- Choose a plugin or process model for external frontends.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Update `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md` with a subsection for frontend provider capability boundaries.
|
||||
2. State that compiler entrypoints must depend on the compiler capability only and must not require editorial services.
|
||||
3. Define optional editorial capabilities as host-facing editor assistance, not backend-facing compilation requirements.
|
||||
4. Record fallback semantics: absent collection-shaped editorial results are empty, absent scalar results are neutral/absent, and protocol unsupported states are explicit where available.
|
||||
5. Document diagnostics ownership: build/analyze diagnostics are compiler contract output; editor diagnostics may reuse compiler analysis but are not required for frontend validity.
|
||||
6. Add cross-references to `DEC-0041` and existing frontend provider docs or lessons where appropriate.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- The compiler spec explicitly separates required compiler capability from optional editorial capability.
|
||||
- The spec states that compile-capable frontends with no language service are valid.
|
||||
- The spec states that absent editorial capability is not a compiler failure.
|
||||
- The spec does not require JSON, RPC, plugin loading, out-of-process frontends, or a wire format.
|
||||
- The spec keeps `FrontendLanguageService` aggregated for now and does not mandate premature feature-interface splitting.
|
||||
|
||||
## Tests
|
||||
|
||||
- Documentation-only plan: run `discussion validate` after updates.
|
||||
- If markdown/spec linting exists locally, run the relevant docs validation task.
|
||||
- Future implementation tests are delegated to `PLN-0110`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
|
||||
- `discussion/workflow/decisions/DEC-0041-separate-frontend-compilation-from-editorial-language-services.md`
|
||||
- This plan.
|
||||
@ -0,0 +1,71 @@
|
||||
---
|
||||
id: PLN-0108
|
||||
ticket: multi-frontend-compiler-vs-language-services
|
||||
title: Move PBS editor assistance behind optional language service
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0041]
|
||||
tags: [compiler, compiler-general, studio, lsp, editor, frontend, multi-frontend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0041` allows PBS to keep rich editor assistance, but that behavior must become a PBS-provided optional capability instead of a common frontend requirement. This plan moves PBS completion, hover, signature help, semantic token production, and related editorial behavior behind the optional language-service boundary.
|
||||
|
||||
## Objective
|
||||
|
||||
Expose PBS editor assistance through `FrontendProvider.languageService()` while preserving current PBS behavior and keeping `FrontendProvider.compiler()` sufficient for compilation.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Accepted decision: `DEC-0041`.
|
||||
- `PLN-0107` should define the documented boundary before final implementation review.
|
||||
- Existing PBS editorial support classes and LSP bridge behavior.
|
||||
|
||||
## Scope
|
||||
|
||||
- Introduce or extend PBS language-service implementation under the PBS frontend module.
|
||||
- Make `PBSFrontendProvider.languageService()` return a PBS language service.
|
||||
- Keep `PBSFrontendProvider.compiler()` unchanged as the required compiler path.
|
||||
- Move PBS-specific editorial calls into the PBS language-service implementation or adapter.
|
||||
- Preserve existing completion, hover, signature help, semantic token, and documentation behavior for PBS.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Change PBS language semantics.
|
||||
- Add new editor features.
|
||||
- Rewrite the LSP protocol layer.
|
||||
- Implement capability-aware LSP fallbacks; that belongs to `PLN-0109`.
|
||||
- Split every editor feature into independent top-level service interfaces unless strictly required by local implementation shape.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Inspect `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/FrontendLanguageService.java` and define the minimum capability accessors needed by current PBS editor behavior.
|
||||
2. Add a PBS language-service implementation in the PBS frontend module, colocated with existing PBS editorial support classes.
|
||||
3. Move or delegate completion, hover, signature help, and semantic token behavior from PBS-specific bridge code into the PBS language-service implementation without changing output models unless the boundary requires neutral compiler-facing DTOs.
|
||||
4. Update `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSFrontendProvider.java` to return `Optional.of(pbsLanguageService)`.
|
||||
5. Keep compile/analyze/build paths independent of `languageService()`.
|
||||
6. Preserve current PBS editorial tests by redirecting setup to the new PBS language-service surface where appropriate.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- PBS provider exposes a non-empty optional language service.
|
||||
- PBS compilation still works when only `compiler()` is used.
|
||||
- PBS completion, hover, signature help, semantic tokens, and documentation behavior remain equivalent to current behavior.
|
||||
- Common compiler modules do not instantiate PBS editorial implementation directly.
|
||||
- No new requirement is introduced for non-PBS frontends to implement editor assistance.
|
||||
|
||||
## Tests
|
||||
|
||||
- Run PBS frontend tests covering editorial support.
|
||||
- Run LSP tests that currently assert PBS completion, hover, signature help, semantic tokens, and documentation behavior.
|
||||
- Add or update provider tests proving PBS has a language service while a compile-only provider can omit it.
|
||||
- Run targeted Gradle tasks for changed compiler frontend and LSP modules.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/FrontendLanguageService.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSFrontendProvider.java`
|
||||
- PBS editorial support classes under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java`
|
||||
- Related PBS frontend tests.
|
||||
- Related LSP bridge tests.
|
||||
@ -0,0 +1,74 @@
|
||||
---
|
||||
id: PLN-0109
|
||||
ticket: multi-frontend-compiler-vs-language-services
|
||||
title: Make LSP editorial calls capability aware
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0041]
|
||||
tags: [compiler, compiler-general, studio, lsp, editor, frontend, multi-frontend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0041` requires LSP and Studio consumers to query editorial capability availability before invoking editor-specific behavior. The current LSP bridge still contains PBS-specific editorial logic. This plan migrates LSP editorial calls to capability-aware provider lookup and graceful fallbacks.
|
||||
|
||||
## Objective
|
||||
|
||||
Make LSP completion, hover, signature help, semantic tokens, and future editorial calls resolve the active frontend provider, consult optional language-service capabilities, and return deterministic neutral responses when capabilities are absent.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Accepted decision: `DEC-0041`.
|
||||
- `PLN-0108` should expose PBS editor assistance through `FrontendProvider.languageService()`.
|
||||
- Existing `FrontendRegistryService` frontend lookup.
|
||||
- Existing LSP baseline messages and tests.
|
||||
|
||||
## Scope
|
||||
|
||||
- Update LSP bridge code to resolve frontend providers rather than hard-coding PBS editorial paths.
|
||||
- Add fallback behavior for absent completion, hover, signature help, and semantic token capability.
|
||||
- Preserve compiler-backed diagnostics through analyze/build paths.
|
||||
- Keep PBS editorial behavior stable when its language service is present.
|
||||
- Document or encode unsupported/neutral responses according to existing LSP baseline message shapes.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Add new LSP features.
|
||||
- Change VSCode extension behavior beyond consuming existing baseline responses.
|
||||
- Remove all PBS-specific code in one step if adapter compatibility still requires local mapping.
|
||||
- Make semantic presentation metadata optional; only live semantic token production is optional.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Inspect `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java` and identify all direct PBS editorial calls.
|
||||
2. Add a provider-resolution path using `FrontendRegistryService` or the existing registry abstraction for `context.languageId()`.
|
||||
3. For each editorial endpoint, query `provider.languageService()` and then the relevant capability before invoking implementation behavior.
|
||||
4. Return neutral fallbacks when absent:
|
||||
- completion: incomplete `false` with empty items;
|
||||
- hover: absent/neutral hover content according to current baseline message constraints;
|
||||
- signature help: empty signatures with stable active indices;
|
||||
- semantic tokens: frontend legend/presentation where available and empty token list when live tokenization is absent.
|
||||
5. Keep `analyzeDocument` compiler-diagnostic behavior on the compiler pipeline and do not require `languageService()`.
|
||||
6. Update tests to cover both PBS-present and capability-absent frontends.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- LSP editorial endpoints do not assume every compiler frontend has editor assistance.
|
||||
- Absent editorial capabilities produce deterministic empty or neutral responses, not compiler failures.
|
||||
- Compiler diagnostics still work without a language service.
|
||||
- PBS editor assistance remains unchanged when PBS language service is available.
|
||||
- Any remaining PBS-specific code is adapter-local and documented as temporary if not removed.
|
||||
|
||||
## Tests
|
||||
|
||||
- Add LSP tests for a compile-only frontend or stub provider with no language service.
|
||||
- Preserve existing `CompilerLanguageServiceBridgeTest` coverage for PBS completion, hover, signature help, and semantic tokens.
|
||||
- Add regression coverage that `analyzeDocument` returns compiler diagnostics independently of editorial services.
|
||||
- Run targeted LSP module tests.
|
||||
|
||||
## 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`
|
||||
- LSP baseline message types only if neutral response representation is currently insufficient.
|
||||
- Frontend registry integration points used by LSP.
|
||||
@ -0,0 +1,72 @@
|
||||
---
|
||||
id: PLN-0110
|
||||
ticket: multi-frontend-compiler-vs-language-services
|
||||
title: Add compile only frontend and absent capability conformance coverage
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0041]
|
||||
tags: [compiler, compiler-general, studio, lsp, editor, frontend, multi-frontend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0041` requires proof that a frontend can compile without editor assistance and that LSP/Studio behavior remains deterministic when editorial capabilities are absent. This plan adds focused conformance coverage so future changes cannot accidentally make language services mandatory again.
|
||||
|
||||
## Objective
|
||||
|
||||
Add tests and lightweight fixtures proving compile-only frontends are valid, compiler diagnostics remain available, and absent editorial capabilities produce graceful fallback responses.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Accepted decision: `DEC-0041`.
|
||||
- `PLN-0107` for documented contract language.
|
||||
- `PLN-0109` for capability-aware LSP behavior before all fallback tests can pass.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add a compile-only test frontend/provider fixture that implements compiler behavior and omits `languageService()`.
|
||||
- Add provider boundary tests proving build/analyze/compile flows do not require editor services.
|
||||
- Add LSP fallback tests for absent completion, hover, signature help, semantic tokens, and future editorial capability slots when present in the API.
|
||||
- Add PBS regression tests proving rich PBS editor behavior remains available.
|
||||
- Add architecture tests that prevent common compiler modules from depending on PBS-specific editor services.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Build a production non-PBS frontend.
|
||||
- Add a plugin loader.
|
||||
- Add new editor features.
|
||||
- Replace all PBS tests with generic frontend tests.
|
||||
- Test external process or wire-format behavior.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Locate existing provider and boundary tests, including `FrontendProviderBoundaryTest`.
|
||||
2. Add a compile-only provider fixture in the narrowest test source set that can exercise the provider contract without production registration churn.
|
||||
3. Write compiler-side tests asserting the fixture has a compiler, has no language service, and can participate in the relevant build/analyze/compile path selected for the fixture.
|
||||
4. Add LSP tests using the compile-only or stub frontend path to assert neutral responses for absent editorial capabilities.
|
||||
5. Preserve or extend PBS regression tests to show PBS still exposes completion, hover, signature help, semantic tokens, and documentation.
|
||||
6. Add architecture assertions that common compiler/pipeline modules do not instantiate PBS editorial services directly.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- At least one test frontend is compile-capable with `languageService()` empty.
|
||||
- Compiler/pipeline tests prove editor services are not required for compilation or analysis.
|
||||
- LSP tests prove absent editorial capabilities are handled without exceptions or compiler failures.
|
||||
- PBS tests prove existing editorial behavior is still available.
|
||||
- Tests do not depend on JSON, RPC, plugin loading, external processes, or future wire formats.
|
||||
|
||||
## Tests
|
||||
|
||||
- Run compiler frontend API/provider tests.
|
||||
- Run build pipeline boundary tests.
|
||||
- Run targeted LSP tests.
|
||||
- Run any architecture/reflection tests added for the no-PBS-editorial-dependency rule.
|
||||
- Run `discussion validate` after plan status or workflow updates.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/FrontendProviderBoundaryTest.java`
|
||||
- Relevant frontend provider tests under `prometeu-compiler`.
|
||||
- Relevant LSP tests under `prometeu-lsp/prometeu-lsp-v1/src/test/java`
|
||||
- Test fixtures for a compile-only frontend/provider.
|
||||
- This plan and linked workflow metadata.
|
||||
@ -241,7 +241,37 @@ At minimum, each provider MUST expose:
|
||||
2. `compiler()`, returning the compiler-facing frontend service used by the shared build pipeline;
|
||||
3. `languageService()`, returning an optional editor-facing language-service capability for tooling consumers.
|
||||
|
||||
`languageService()` MUST be optional. A frontend that supports compilation but does not provide editor services MUST remain a valid provider.
|
||||
`compiler()` is the only required executable frontend capability. It MUST be sufficient for `analyze`, `compile`, `build`, and backend-facing pipeline flows.
|
||||
|
||||
`languageService()` MUST be optional. A frontend that supports compilation but does not provide editor services MUST remain a valid provider. Absence of `languageService()` MUST NOT prevent project analysis, compilation, backend lowering, bytecode emission, verification, or artifact writing.
|
||||
|
||||
The first shared editor-facing contract SHOULD remain an aggregated language-service capability surface. The common compiler contract MUST NOT require separate top-level service interfaces for each editor feature until a future accepted decision and plan identify a real lifecycle, ownership, or testing boundary that requires that split.
|
||||
|
||||
When exposed, editor-facing capabilities MAY include:
|
||||
|
||||
1. diagnostics intended for live editor sessions,
|
||||
2. completion,
|
||||
3. hover,
|
||||
4. definition and navigation,
|
||||
5. signature help,
|
||||
6. semantic tokens for a live document,
|
||||
7. formatting,
|
||||
8. rename,
|
||||
9. code actions,
|
||||
10. and other host-facing editor assistance.
|
||||
|
||||
These capabilities are optional unless a future frontend- or host-specific decision makes one of them mandatory for a narrower surface. Tooling consumers MUST query capability availability before invoking editor-specific behavior.
|
||||
|
||||
Absent editor capabilities MUST have deterministic fallback behavior at tooling boundaries:
|
||||
|
||||
1. collection-shaped responses SHOULD be empty;
|
||||
2. scalar optional responses SHOULD be absent or use a documented neutral response;
|
||||
3. host protocols that can represent unsupported operations SHOULD do so explicitly;
|
||||
4. and absent editor capability MUST NOT be reported as a compiler failure.
|
||||
|
||||
Compiler diagnostics and editor diagnostics are distinct ownership surfaces. Diagnostics returned by `analyze`, `compile`, and `build` are compiler contract output. Editor diagnostics MAY reuse compiler analysis results, live overlays, caches, or cancellation-aware tooling state, but a frontend MUST NOT be required to provide editor diagnostics in order to compile.
|
||||
|
||||
`FrontendSpec` remains the source of static frontend-owned presentation metadata such as semantic vocabularies, host projections, and visual themes. Producing semantic tokens for a live document is an optional editor-facing capability; the existence of static presentation metadata MUST NOT imply that every frontend can provide live semantic-token results.
|
||||
|
||||
The frontend registry MUST resolve providers by `languageId`. A lookup for an unknown `languageId` MUST fail explicitly with a diagnostic-friendly error. Unknown languages MUST NOT silently fall back to PBS or to any other frontend.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user