---
id: AGD-0042
ticket: pbs-lsp-go-to-definition
title: PBS LSP Go to Definition
status: open
created: 2026-07-15
resolved:
decision:
tags: [studio, lsp, vscode, compiler-pbs, editor, definition]
---

## Pain

Domain owner: `studio/lsp`

PBS users cannot jump from a symbol use to its declaration, which makes navigation across source files, stdlib imports, services, and generated/editorial surfaces slow and error-prone.

## Context

The current LSP exposes diagnostics, hover, completion, signature help, and semantic tokens. The compiler already builds semantic read surfaces and editorial symbol resolution for hover/completion, but there is no LSP definition capability or stable location mapping exposed to VS Code.

## Open Questions

- [ ] Which symbol categories must be supported in the first definition wave?
- [ ] Should stdlib and generated/supplemental declarations navigate to source files, virtual documents, or remain hover-only?
- [ ] What identity model should connect an editor token to the canonical declaration without relying on text search?

## Options

### Option A - Syntactic location lookup

- **Approach:** Use parser spans and local AST traversal to map the token under cursor to a declaration with matching text.
- **Pro:** Fast to implement and useful for same-file declarations.
- **Con:** Breaks on overloads, imports, stdlib, aliases, and same-name symbols.
- **Maintainability:** Weak; it creates a second navigation model separate from semantic resolution.

### Option B - Semantic identity lookup

- **Approach:** Extend the compiler/editorial surface with resolved declaration locations keyed by symbol identity, then expose `textDocument/definition`.
- **Pro:** Correct for imports, overloads, methods, stdlib-backed declarations, and future references/rename.
- **Con:** Requires explicit location metadata in semantic/editorial surfaces.
- **Maintainability:** Strong; it becomes shared infrastructure for references, rename, hierarchy, and code actions.

## Tradeoffs

The syntactic option is tempting for speed, but it would likely be thrown away once references and rename arrive. The main tradeoff is whether stdlib/supplemental declarations must navigate to physical files immediately or can initially return no location while still supporting project symbols.

## Recommendation

Prefer Option B. Build a reusable semantic location index and implement the first wave for project source declarations, then define a policy for stdlib/supplemental targets.

## Discussion

This should probably be the first navigation agenda to resolve because references, rename, workspace symbols, and hierarchy depend on the same symbol identity/location model.

## Resolution

Ainda em aberto.

## Next Step

Decide the first-wave symbol categories and whether stdlib/supplemental declarations require virtual document support.