prometeu-studio/discussion/workflow/agendas/AGD-0042-pbs-lsp-go-to-definition.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0042	pbs-lsp-go-to-definition	PBS LSP Go to Definition	open	2026-07-15			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.