Wave 1 de assistencia editorial via LSP para PBS no VS Code
This commit is contained in:
+135
@@ -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.
|
||||
+121
@@ -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.
|
||||
+103
@@ -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.
|
||||
Reference in New Issue
Block a user