housekeep DSC-0055
JaCoCo Coverage #### Project Overview No changes detected, that affect the code coverage. * Line Coverage: 61.54% (17430/28323) * Branch Coverage: 52.41% (6739/12858) * Lines of Code: 28323 * Cyclomatic Complexity: 11353 #### Quality Gates Summary Output truncated.
Test / Build skipped: 15, passed: 611
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Studio/pipeline/head This commit looks good

This commit is contained in:
2026-07-15 09:55:08 +01:00
parent da00e9c50c
commit 4233b90b82
8 changed files with 90 additions and 469 deletions
@@ -1,68 +0,0 @@
---
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.
@@ -1,71 +0,0 @@
---
id: PLN-0108
ticket: multi-frontend-compiler-vs-language-services
title: Move PBS editor assistance behind optional language service
status: done
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.
@@ -1,74 +0,0 @@
---
id: PLN-0109
ticket: multi-frontend-compiler-vs-language-services
title: Make LSP editorial calls capability aware
status: done
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.
@@ -1,72 +0,0 @@
---
id: PLN-0110
ticket: multi-frontend-compiler-vs-language-services
title: Add compile only frontend and absent capability conformance coverage
status: done
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.