Wave 1 de assistencia editorial via LSP para PBS no VS Code

This commit is contained in:
2026-05-08 09:48:14 +01:00
parent ef814b2420
commit 240525286b
7 changed files with 898 additions and 1 deletions
@@ -0,0 +1,135 @@
---
id: PLN-0075
ticket: pbs-lsp-editor-assistance-wave-1
title: PBS Editorial Resolution Surface for Symbols, Members, and Signatures
status: open
created: 2026-05-08
completed:
tags: [compiler, compiler-pbs, editor, completion, hover, signature-help, semantics]
---
## Objective
Introduce a compiler-backed editorial resolution surface in `compiler/pbs` that can answer symbol identity, kind, origin, signature/shape, callable details, and receiver members for use by LSP `completion`, `hover`, and `signature help`.
## Background
`DEC-0035` requires all three editor-assistance features to be built over one shared compiler-backed base. The current repository already has useful pieces:
- parser and AST for PBS;
- semantic validation and flow analysis;
- stdlib and import visibility rules;
- semantic token classification;
- builder-pipeline overlay analysis.
What is still missing is an explicit editorial surface designed for interactive symbol resolution instead of only diagnostics or coloring.
## Scope
### Included
- Define internal compiler-side models for editorial symbol resolution.
- Resolve local names, imported/public symbols, and recognized member surfaces.
- Resolve callable signatures for functions, methods, and constructors.
- Provide optional documentation slot(s) in the model without defining authored PBS documentation syntax.
- Add PBS-focused tests for symbol/member/signature resolution.
### Excluded
- LSP protocol capability changes.
- VS Code client behavior.
- Authored documentation syntax such as `Document(...)`.
- `go to definition`, `references`, `rename`, formatter, or code actions.
## Non-Goals
- Rebuilding the full compiler around IDE concerns.
- Solving every ambiguous or partial parse state in wave 1.
- Designing a generic multi-language IDE framework before PBS proves the model.
## Execution Steps
### Step 1 - Define editorial resolution models in compiler-owned surfaces
**What:** Introduce explicit models for resolved symbols, member candidates, callable signatures, and optional documentation payload.
**How:** Add compiler-owned DTO/model types that can express:
1. symbol identity and kind;
2. declared/imported origin;
3. callable label/signature shape;
4. receiver member entries;
5. optional documentation text field.
The model must be expressive enough for `completion`, `hover`, and `signature help` without forcing each consumer to reinterpret raw AST nodes.
**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/**` and/or `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/**` depending on final ownership split.
### Step 2 - Build PBS symbol resolution for local and imported surfaces
**What:** Resolve names in editorial contexts.
**How:** Reuse parser, name/linking, stdlib import knowledge, and any existing semantic tables to resolve:
1. local bindings in scope;
2. declared top-level PBS symbols;
3. imported/public symbols and aliases;
4. stdlib-owned surfaces currently recognized by the frontend.
The implementation must avoid duplicating semantic truth already present in compiler/linking logic.
**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/**`.
### Step 3 - Build member and callable resolution
**What:** Resolve members and callable signatures for recognized receiver and call surfaces.
**How:** Support at minimum:
1. member lookup after `.` for services, hosts, builtin types, and structs;
2. direct callable lookup for functions and constructors;
3. active-call signature resolution for later `signature help` use.
This step must produce stable labels/details that can be reused unchanged by LSP features.
**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/**`.
### Step 4 - Add editorial conformance tests
**What:** Lock the compiler-backed editorial contract before LSP integration.
**How:** Add tests for:
1. local variable and parameter resolution;
2. imported service/host/builtin-type resolution;
3. member lookup after `.` on recognized surfaces;
4. callable signature extraction for function/method/constructor cases;
5. optional documentation field stability when absent.
**File(s):** PBS/compiler test suites under `prometeu-compiler/**/src/test/java/**`.
## Test Requirements
### Unit Tests
- Model invariants for symbol/member/signature payloads.
- Resolver tests covering locals, imports, aliases, members, and constructors.
### Integration Tests
- Compiler-backed overlay/editorial tests using representative PBS snippets and stdlib imports.
### Manual Verification
- Inspect resolved payloads in tests or debug output and confirm they are sufficient to drive all three editor features without ad hoc reinterpretation.
## Acceptance Criteria
- [ ] Compiler-side editorial models exist for symbols, members, signatures, and optional documentation.
- [ ] PBS can resolve local names, imported/public symbols, and recognized member surfaces.
- [ ] Function, method, and constructor signatures are available through the shared editorial surface.
- [ ] No consumer is required to reconstruct signature/member meaning from raw AST-only data.
## Dependencies
- `DEC-0035` accepted and normatively locked.
- Existing PBS semantic and import/linking infrastructure remains the truth source.
## Risks
- Overfitting the first resolver to the current stdlib shape may hurt future fronts or future PBS growth.
- Mixing diagnostics-only semantics with editorial semantics carelessly may produce partial or contradictory answers.
- Incomplete member resolution can make `completion` appear flaky even if `hover` works.
@@ -0,0 +1,121 @@
---
id: PLN-0076
ticket: pbs-lsp-editor-assistance-wave-1
title: LSP Completion, Hover, and Signature Help over Editorial Resolution
status: open
created: 2026-05-08
completed:
tags: [studio, lsp, protocol, completion, hover, signature-help, editor]
---
## Objective
Expose `completion`, real `hover`, and `signature help` through the project-scoped LSP stack by projecting the compiler-backed editorial resolution surface into explicit protocol capabilities and request handlers.
## Background
`DEC-0035` requires `studio/lsp` to be the operational owner of these editor features while remaining faithful to compiler-backed symbol, member, and signature resolution. The current LSP path only handles diagnostics, semantic tokens, and a placeholder hover.
## Scope
### Included
- Extend the internal bridge/API with completion and signature-help operations.
- Replace placeholder hover with symbol-resolved hover.
- Announce LSP capabilities for completion and signature help.
- Add message models/mappers/tests for the new request/response paths.
### Excluded
- Creation of the underlying compiler editorial model itself.
- Authored documentation syntax.
- VS Code-specific UI behavior beyond normal LSP consumption.
## Non-Goals
- `go to definition`, `references`, `rename`, formatter, code actions, or quick fixes.
- Rich workspace-wide indexing beyond what the shared editorial surface already provides.
## Execution Steps
### Step 1 - Extend the LSP bridge contract
**What:** Add compiler-backed editor-assistance operations to the bridge.
**How:** Evolve `LanguageServiceBridge` and related internal messages to support at minimum:
1. completion requests;
2. symbol-resolved hover payloads;
3. signature-help requests.
The bridge contract must align structurally with the shared editorial resolution surface rather than inventing a second feature-specific abstraction.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/**`, `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/**`.
### Step 2 - Implement compiler-backed request handling
**What:** Wire LSP requests to compiler-backed editorial resolution.
**How:** Update `CompilerLanguageServiceBridge` so it:
1. resolves completion candidates from local/import/member contexts;
2. resolves hover payloads from symbol identity, origin, and signatures;
3. resolves active call signatures for `signature help`.
This step must remove the current fixed hover placeholder.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/**`.
### Step 3 - Announce and map protocol capabilities
**What:** Make the server advertise the new feature set and map payloads into lsp4j types.
**How:** Update protocol mappers and text-document service so the server announces:
1. `completionProvider`;
2. `signatureHelpProvider`;
3. improved `hoverProvider` backed by real payloads.
Map completion items, hover markdown, and signature-help structures into concrete LSP responses.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/**`, `.../mapping/**`.
### Step 4 - Add transport and conformance tests
**What:** Prevent regression to placeholder/editor-local behavior.
**How:** Add tests that verify:
1. capabilities are announced correctly;
2. completion returns compiler-backed candidates;
3. hover no longer returns the baseline placeholder;
4. signature-help returns deterministic active-signature information.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`.
## Test Requirements
### Unit Tests
- DTO/model invariants for completion, hover, and signature-help payloads.
- Mapper tests for lsp4j conversion.
### Integration Tests
- LSP request/response tests using realistic PBS snippets with locals, imports, and member access.
### Manual Verification
- Connect the VS Code extension and confirm server capabilities include completion and signature help.
- Confirm hover content changes with the hovered symbol rather than returning static baseline text.
## Acceptance Criteria
- [ ] The LSP bridge exposes completion and signature-help operations in addition to diagnostics, hover, and semantic tokens.
- [ ] Hover is symbol-resolved and no longer hardcoded placeholder text.
- [ ] The server advertises completion and signature-help capabilities.
- [ ] Completion, hover, and signature help all derive from the same compiler-backed editorial surface.
## Dependencies
- `DEC-0035` accepted and normatively locked.
- `PLN-0075` for the shared compiler-backed editorial resolution surface.
## Risks
- Protocol mapping can drift from compiler payload shape if feature-specific shortcuts are added.
- Active parameter/signature calculation may be brittle around incomplete syntax unless request handling is conservative.
- Completion can feel noisy if candidate ranking or filtering is too weak in wave 1.
@@ -0,0 +1,103 @@
---
id: PLN-0077
ticket: pbs-lsp-editor-assistance-wave-1
title: VS Code Consumption and Wave 1 Editor Assistance Validation
status: open
created: 2026-05-08
completed:
tags: [vscode, extension, editor, completion, hover, signature-help, validation]
---
## Objective
Keep the VS Code extension thin while validating that the new LSP-delivered `completion`, `hover`, and `signature help` features actually produce a minimally usable PBS editing experience end to end.
## Background
`DEC-0035` explicitly requires the extension to remain a client/adaptor rather than a second semantic engine. Because VS Code already knows how to consume LSP completion, hover, and signature-help responses, the extension work should be small and mostly about ensuring transport, configuration, and real validation are correct.
## Scope
### Included
- Confirm the extension does not need or gain local semantic tables for stdlib, members, or signatures.
- Adjust only the minimal extension/bootstrap behavior needed for the new LSP features to flow correctly.
- Add verification coverage and manual validation guidance for the full wave.
### Excluded
- Compiler-side editorial resolution logic.
- LSP-side protocol feature implementation.
- Formatter/indentation, code actions, or non-wave-1 IDE features.
## Non-Goals
- Turning the extension into a feature-rich semantic client.
- Adding hardcoded completion/signature content for PBS inside TypeScript runtime code.
## Execution Steps
### Step 1 - Verify thin-client integration boundaries
**What:** Confirm the extension remains a pure LSP consumer for the new features.
**How:** Review and adjust the extension only where necessary so completion, hover, and signature help are obtained from the LSP session without client-side semantic fallback tables.
**File(s):** `tools/vscode-extension/src/**`, `tools/vscode-extension/package.json`.
### Step 2 - Add any minimal structural configuration required by VS Code
**What:** Keep static contribution surfaces minimal and structural.
**How:** If VS Code requires additional structural contribution metadata for the new features, add only that metadata. Do not add curated PBS semantic or signature data into the extension package.
**File(s):** `tools/vscode-extension/package.json`.
### Step 3 - Add validation coverage for end-to-end editor assistance
**What:** Lock the no-local-semantics rule and the end-to-end feature expectations.
**How:** Add tests or deterministic verification steps that ensure:
1. the extension connects and receives the feature set from the server;
2. no local completion/signature tables were introduced;
3. the user-facing wave can be exercised end to end.
**File(s):** `tools/vscode-extension/**`, existing validation harnesses if present, and related docs/test notes.
### Step 4 - Define manual smoke scenarios for wave 1 usability
**What:** Make the wave verifiable as a product experience rather than only a protocol exercise.
**How:** Document and run manual checks for:
1. keyword and local-name completion;
2. imported stdlib/member completion after `.`;
3. hover on locals, imported services, builtin types, and methods;
4. signature help during function/method/constructor calls.
**File(s):** extension verification notes or adjacent implementation docs/tests as appropriate.
## Test Requirements
### Unit Tests
- Any extension-side helpers introduced for structural integration only.
### Integration Tests
- End-to-end or near-end-to-end validation that VS Code consumes the server feature set without local semantic duplication.
### Manual Verification
- Open representative PBS files in VS Code and verify `completion`, `hover`, and `signature help` behavior matches the expected wave-1 scope.
## Acceptance Criteria
- [ ] The extension remains thin and contains no new hardcoded PBS semantic tables for members or signatures.
- [ ] VS Code can consume the new LSP completion, hover, and signature-help responses without extension-side semantic authorship.
- [ ] Wave-1 smoke scenarios are documented and manually verifiable.
## Dependencies
- `DEC-0035` accepted and normatively locked.
- `PLN-0076` for the actual LSP feature delivery.
## Risks
- It is easy to accidentally patch around server gaps with client-local logic; this plan must resist that.
- Validation can become too protocol-centric and miss real usability failures if manual smoke scenarios are weak.