prometeu-studio/discussion/workflow/plans/PLN-0137-pbs-lsp-remaining-editor-surface.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0137	pbs-lsp-remaining-editor-surface	PBS LSP remaining editor surface	in_progress	2026-09-22	DEC-0058	studio lsp vscode compiler-pbs editor

Briefing

DEC-0058 locks one PBS LSP wave on top of the editor surface that already ships. Seven steps run in order on dev/pbs-lsp-remaining-editor-surface. Each step is one commit. The frontend produces the editorial result. The LSP transports it and does not invent a second policy.

Objective

Land diagnostic source, physical import document links, folding and selection ranges, full-document formatting, a semantic-token overlay, module-ref completion, and function/method call hierarchy. Leave snapshot cache, type hierarchy, auto-import, and resolve completion out.

Dependencies

Shipped and unchanged by this plan: request-local analysis, physical definition and references, rename, document symbols, workspace symbols, quick fix (LSN-0073), PBSSemanticTokenProvider, and eager completion in PbsEditorialSupportService. Spec 23 §8.3 is the only normative doc updated, one paragraph in the commit of the step that introduces that rule.

Scope

Local to studio LSP and the PBS frontend. Shared compiler entry points do not gain a cache or a new pipeline phase. New LSP capabilities follow the code-action pattern: FrontendLanguageService defaults to unsupported, PBS overrides support, BaselineServerDescription advertises only that flag, and a missing flag is an empty list.

Step 1. Diagnostic source

In CompilerLanguageServiceBridge.toBaselineIssue, set BaselineDocumentIssue.source from LspProjectContext.languageId. Keep code as the trimmed compiler code, empty when the compiler code is null or blank. Do not special-case "Prometeu Studio". Lsp4jProtocolMessageMapper.mapDiagnostic already copies source and code and must stay without relatedInformation or data.

Spec 23 §8.3 gains one paragraph: published editor diagnostic source is the bound frontend languageId; code is the stable compiler code or empty; tooling must not copy the code into source and must not publish related locations, phase, or a repair payload.

Step 2. Document links

Add a frontend document-link result: span of a ModuleRef plus a physical file target. Default on FrontendLanguageService is an empty list and documentLinksSupported false. PBS returns a link only when the resolver the compiler already uses yields a regular file. No link for virtual stdlib, assets, docs, or an unresolved module. Do not add a second module resolver.

LSP: baseline message, documentLinkProvider, PrometeuTextDocumentService.documentLink, mapper. Unsupported stays unadvertised and returns an empty list.

Step 3. Folding and selection ranges

Frontend produces both lists from the recovered AST when the node has a span: top-level fn, struct, service, contract, enum, error, callback, and host; their bodies; parameter lists; Doc text blocks. Token fallback covers only a brace, parenthesis, or text-block delimiter the tree does not cover. Selection order, inner to outer: identifier, argument or parameter list, block or text block, declaration. Empty when there is nothing. Do not build either list from document symbols.

LSP advertises foldingRangeProvider and selectionRangeProvider only when the frontend flags are true.

Step 4. Full-document formatting

Frontend formatter reprints the token stream. It does not reorder declarations, join lines, or split lines to beautify. Indent is four spaces and changes only where brace, parenthesis, or block nesting changes. Doc text-block interiors are copied unchanged. A comment stays on the token line it already belongs to. No AST pretty-printer. No range formatting. No on-type formatting. Do not read .studio/setup.json or LSN-0033.

LSP advertises documentFormattingProvider only.

Step 5. Semantic-token overlay

Keep PBSSemanticTokenProvider as the lexical baseline. After that pass, where the same resolution hover uses names a symbol and an existing PbsSemanticKind matches it, replace the weaker key. On resolution failure, a broken file, or a symbol with no existing key, keep the provider token. Add no PbsSemanticKind constant. The server already advertises semantic tokens; do not add a second provider.

Step 6. Module-ref completion

When the completion offset sits inside a ModuleRef, return project and stdlib modules the current resolver can already name. Every other offset keeps today's member or general completion. Items stay eager. CompletionOptions.resolveProvider stays false. No snippets. No new rank score. No new trigger-character policy beyond what module-ref detection needs inside the existing completion request.

Step 7. Call hierarchy

Frontend walks CallExpr callsites for incoming and outgoing calls of functions and methods. Do not query the references index. A cursor that is not on a callable returns empty. No type hierarchy and no separate host or intrinsic graph.

LSP advertises call hierarchy only. This commit also writes the English lesson, runs discussion housekeep DSC-0066 --lesson <path>, and discussion validate.

Non-Goals

• Project snapshot cache, cancellation, and background reanalysis.
• Type hierarchy, contract implementation hierarchy, and a separate host or intrinsic graph.
• completionItem/resolve, snippets, and a ranking model.
• Range formatting and on-type formatting.
• Organize imports and a missing-import quick fix.
• relatedInformation, compiler phase on the diagnostic, and repair data.
• New semantic-token keys.
• Document links for assets, addressables, docs, or virtual stdlib URIs.
• Reusing document symbols as folding ranges.
• Pushing the branch.

Execution Method

1. Work on dev/pbs-lsp-remaining-editor-surface. Do not commit on master.
2. Mark this plan in_progress before step 1 code.
3. Implement one step, then run the tests listed for that step.
4. Commit that step before starting the next. Subject: implements PLN-0137 (k/7) <slug>.
5. Stage discussion, docs, prometeu-compiler, and prometeu-lsp as the step touches them. Do not stage AGENTS.md.
6. Spec 23 §8.3 is edited in the same commit as the step whose rule it states.
7. Steps are not reordered and are not parallel. A later step may use the capability flags introduced earlier; it must not reopen a closed step.
8. The seventh commit includes the lesson and housekeep. Earlier commits keep DEC-0058 and this plan in the tree.

Commit slugs:

1. diagnostic-source
2. document-links
3. folding-and-selection-ranges
4. document-formatting
5. semantic-token-overlay
6. module-ref-completion
7. call-hierarchy

Acceptance Criteria

• Step 1: every issue from analyzeDocument on a PBS project has source equal to pbs, code is the stable compiler code, and source is not that code. No related information is mapped.
• Step 2: a ModuleRef that resolves to a regular file becomes one document link on that span. Virtual stdlib and unresolved modules produce no link. The provider is advertised only when supported.
• Step 3: a well-formed declaration, body, parameter list, and Doc text block fold from AST spans. An unmatched brace still produces a token fallback range. Selection nests in the decided order. Document symbols are unchanged.
• Step 4: formatting a document does not change Doc text-block interiors, does not move a comment off its token line, does not reorder declarations, and only changes indent by four spaces at nesting changes. Range and on-type providers stay off.
• Step 5: an identifier hover can resolve changes to an existing semantic key; a broken file still returns the lexical tokens; PbsSemanticKind gains no constant.
• Step 6: completion inside a ModuleRef lists resolver-known modules; completion after . is unchanged; resolveProvider is false.
• Step 7: incoming and outgoing calls report function and method callsites found in the AST. A non-callable cursor is empty. Type hierarchy is not advertised. discussion validate passes after housekeep, and the lesson states the seven rules.

Tests

• CompilerLanguageServiceBridgeTest for diagnostic source, and for each new bridge method as it lands.
• Lsp4jProtocolMessageMapperTest for capability advertisement of each new provider, and for the absence of range formatting, on-type formatting, resolve, related information, and type hierarchy.
• PBS frontend tests for links, folding, selection, formatting, the token overlay, module-ref completion, and call hierarchy. Include one broken-file case for tokens and one unmatched-delimiter case for folding.
• Do not require a running VS Code instance. Bridge and mapper tests are the protocol gate.

Affected Artifacts

• discussion/workflow/agendas/AGD-0069-pbs-lsp-remaining-editor-surface.md
• discussion/workflow/decisions/DEC-0058-pbs-lsp-remaining-editor-surface.md
• discussion/workflow/plans/PLN-0137-pbs-lsp-remaining-editor-surface.md
• discussion/index.ndjson
• docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md
• prometeu-compiler/prometeu-frontend-api (FrontendLanguageService and new result types)
• prometeu-compiler/frontends/prometeu-frontend-pbs (PBS implementations)
• prometeu-lsp/prometeu-lsp-v1 (bridge, baseline messages, text document service, mapper)
• Lesson, only in the step 7 commit: discussion/lessons/DSC-0066-pbs-lsp-remaining-editor-surface/