136 lines
5.5 KiB
Markdown
136 lines
5.5 KiB
Markdown
---
|
|
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.
|