prometeu-studio/discussion/lessons/DSC-0035-pbs-lsp-editor-assistance-wave-1/LSN-0051-compiler-backed-editor-assistance-for-pbs.md

id	ticket	title	created	tags
LSN-0051	pbs-lsp-editor-assistance-wave-1	Compiler-Backed Editor Assistance for PBS	2026-05-08	studio lsp vscode compiler compiler-pbs editor completion hover signature-help

Original Problem

PBS editing in VS Code already had basic diagnostics and frontend-owned semantic highlighting, but it still lacked the minimum assistance expected during everyday code authoring:

1. no completion;
2. placeholder-only hover;
3. no signature help.

Without those features, the editor behaved more like a colored diagnostic viewer than a practical PBS authoring surface.

Consolidated Decision

Wave 1 of PBS editor assistance is completion, symbol-resolved hover, and signature help.

These features must be built on one compiler-backed editorial resolution surface. The VS Code extension remains a thin LSP client, and the LSP layer projects compiler knowledge into protocol responses instead of inventing editor-local semantic tables.

The shared surface must be able to describe:

1. symbol identity and kind;
2. module or origin when relevant;
3. signature or shape when applicable;
4. available members for recognized receivers;
5. optional documentation when available.

The wave explicitly excludes formatter work, robust automatic indentation, go to definition, references, rename, quick fixes, broad code actions, and the PBS authored-documentation syntax.

Final Implementation Shape

The work was decomposed into three execution fronts:

1. compiler/pbs owns the editorial resolution model for symbols, members, signatures, and optional documentation.
2. studio/lsp exposes completion, hover, and signature-help request handling over that model and advertises the corresponding LSP capabilities.
3. tools/vscode-extension consumes the LSP responses as a thin client and must not add hardcoded PBS semantic tables for members, stdlib, or signatures.

This split keeps semantic truth in the compiler, protocol ownership in the LSP server, and UI integration in the extension.

Examples

Completion should cover at least:

1. language keywords;
2. local names in scope;
3. relevant imported or public symbols;
4. members after . for recognized surfaces such as services, hosts, builtin types, structs, and related callable surfaces.

Hover should include, when available:

1. symbol kind;
2. signature;
3. module or origin;
4. basic type or shape.

Signature help should cover function, method, and constructor calls with active signature and active parameter information.

Pitfalls

Do not implement completion, hover, and signature help as three independent semantic paths. That duplicates parser, linking, stdlib, and member knowledge, then makes the editor inconsistent.

Do not patch around missing server behavior in the VS Code extension. Client-local tables for PBS members, stdlib, or signatures turn the extension into a second semantic engine.

Do not block this wave on authored PBS documentation syntax. The editorial model should have an optional documentation slot, but the language feature for authoring that documentation belongs to a separate discussion.

Do not broaden this wave into general IDE support. Definition, references, rename, formatter, quick fixes, and broad code actions are later work.

References

• DEC-0035 captured the normative decision for wave 1.
• PLN-0075 covered the compiler-side editorial resolution surface.
• PLN-0076 covered LSP projection and protocol capabilities.
• PLN-0077 covered VS Code thin-client consumption and validation.