---
id: AGD-0044
ticket: pbs-lsp-document-symbols-outline
title: PBS LSP Document Symbols and Outline
status: open
created: 2026-07-15
resolved:
decision:
tags: [studio, lsp, vscode, compiler-pbs, editor, outline, document-symbols]
---

## Pain

Domain owner: `studio/lsp`

PBS files do not populate a reliable VS Code outline, forcing users to navigate long source files manually instead of scanning declarations and members structurally.

## Context

The parser and semantic surfaces know top-level declarations and many member declarations. The LSP currently does not announce documentSymbolProvider and does not map PBS declarations to DocumentSymbol or SymbolInformation payloads.

## Open Questions

- [ ] Should the first outline be syntactic, semantic, or hybrid?
- [ ] Which hierarchy should be shown for structs, services, hosts, contracts, builtin types, enums, and methods?
- [ ] How should invalid or partially parsed files contribute to outline during editing?

## Options

### Option A - AST-only outline

- **Approach:** Map parsed declarations and member spans directly to LSP `DocumentSymbol`.
- **Pro:** Works even when semantic analysis is incomplete and gives immediate editor value.
- **Con:** Cannot classify every symbol with semantic precision.
- **Maintainability:** Good if kept as structural outline, not overloaded with semantic behavior.

### Option B - Semantic outline

- **Approach:** Build outline from semantic symbols after analysis.
- **Pro:** More accurate kinds and can hide invalid/unresolved surfaces.
- **Con:** More fragile during active editing and depends on full semantic success.
- **Maintainability:** Good for final precision, but heavier than needed for outline.

## Tradeoffs

Outline should remain available during broken intermediate edits. Semantic precision is useful, but not at the cost of disappearing structure while typing.

## Recommendation

Prefer Option A with semantic enrichment where available. Use AST spans as the stable backbone.

## Discussion

Document symbols are relatively independent and can be implemented before definition/references.

## Resolution

Ainda em aberto.

## Next Step

Decide hierarchy and symbol kinds for PBS declarations and members.