---
id: AGD-0038
ticket: pbs-lsp-editor-assistance-wave-1
title: Wave 1 de assistencia editorial via LSP para PBS no VS Code
status: accepted
created: 2026-05-08
resolved: 2026-05-08
decision: DEC-0035
tags: [studio, lsp, vscode, compiler, compiler-pbs, editor, completion, hover, signature-help]
---

## Pain

O stack atual de PBS no VS Code ja entrega duas capacidades relevantes:

- diagnostics basicos;
- semantic highlighting com tema frontend-owned.

Mas ele ainda nao entrega o minimo de assistencia editorial para um fluxo real de escrita de codigo:

- nao existe `completion`;
- `hover` ainda eh placeholder;
- nao existe `signature help`.

Sem isso, o editor continua servindo mais como viewer colorido com erros do que como ambiente minimamente utilizavel para escrever PBS com conforto.

## Context

Domain owner: `studio`

Subdomains touched:

- `studio/lsp`
- `compiler/pbs`
- `compiler/general`

Estado atual observado no codigo:

- o servidor anuncia `hover` e `semanticTokens`, mas nao anuncia `completionProvider`, `signatureHelpProvider` ou `documentFormattingProvider`;
- o bridge interno do LSP so expõe `describeServer`, `analyzeDocument`, `hover`, `semanticTokens` e `onSave`;
- `hover` hoje retorna texto fixo, sem usar simbolo, assinatura, tipo ou docs;
- o pipeline do compiler ja consegue analisar overlay do documento e possui superficies semanticas e de linking relevantes no PBS;
- o highlighting recente ja resolve bastante informacao lexical e parte da superficie stdlib/imports.

Esta agenda trata apenas da wave 1 de assistencia editorial.
Ela nao tenta fechar todo o problema de IDE features.

## Open Questions

- Qual deve ser o escopo minimo de `completion` para chamarmos essa wave de utilizavel?
- [x] Qual deve ser o escopo minimo de `completion` para chamarmos essa wave de utilizavel?
  R: keywords, nomes locais em escopo, simbolos importados/publicos, e members apos `.` para superfícies reconhecidas (`service`, `host`, `builtin type`, `struct` e constructors/funcoes relacionados). Sem isso, a feature ainda nao ajuda na descoberta real da API.
- `completion` deve nascer apenas com heuristicas lexicais/sintaticas, ou ja deve usar semantica e linking do compiler onde isso for viavel?
- [x] `completion` deve nascer apenas com heuristicas lexicais/sintaticas, ou ja deve usar semantica e linking do compiler onde isso for viavel?
  R: deve nascer compiler-backed sempre que a informacao ja existir de forma confiavel no pipeline semantico/linking. Heuristica local pode existir apenas como complemento estritamente limitado para casos ainda nao resolvidos, nunca como segunda semantica canônica.
- Em `hover`, quais informacoes sao obrigatorias na primeira entrega:
  assinatura, kind, modulo de origem, tipo inferido, documentacao?
- [x] Em `hover`, quais informacoes sao obrigatorias na primeira entrega:
  assinatura, kind, modulo de origem, tipo inferido, documentacao?
  R: obrigatorios: `kind`, assinatura quando aplicavel, modulo/origem quando relevante, e tipo/shape basico quando houver. Documentacao textual eh desejavel para stdlib e builtins, mas nao deve bloquear a wave 1 se a infraestrutura de docstring ainda nao existir. Se a linguagem vier a adotar algo como `Document(...)` com markdown pronto para hover, isso deve nascer em discussao propria; nesta wave atual, basta preparar o local de consumo para documentacao opcional quando ela existir.
- `signature help` deve usar a mesma fonte semantica de `hover/completion`, ou pode nascer numa implementacao mais local para chamadas conhecidas?
- [x] `signature help` deve usar a mesma fonte semantica de `hover/completion`, ou pode nascer numa implementacao mais local para chamadas conhecidas?
  R: deve usar a mesma base semantica. O objetivo da wave eh justamente evitar tres caminhos tecnicos diferentes para responder "qual assinatura esta sendo chamada?".
- Como tratar membros de stdlib, aliases importados, services, hosts, builtin types e metodos de struct sem criar uma segunda semantica paralela no LSP?
- [x] Como tratar membros de stdlib, aliases importados, services, hosts, builtin types e metodos de struct sem criar uma segunda semantica paralela no LSP?
  R: o LSP deve perguntar ao compiler por uma superficie editorial/resolutiva unica, derivada das mesmas fontes usadas para analise, linking, stdlib e metadata do frontend. O LSP nao deve reconstruir manualmente tabelas paralelas de membros.
- Esta wave deve incluir `go to definition`, ou isso deve ficar explicitamente fora do escopo para nao diluir a entrega?
- [x] Esta wave deve incluir `go to definition`, ou isso deve ficar explicitamente fora do escopo para nao diluir a entrega?
  R: deve ficar fora do escopo desta wave. Ele eh um proximo passo natural, mas nao eh requisito para chamar `completion + hover + signature help` de minimamente utilizaveis.
- Formatacao e identacao automatica devem ficar fora desta agenda como non-goal explicito?
- [x] Formatacao e identacao automatica devem ficar fora desta agenda como non-goal explicito?
  R: sim. Podem virar discussao/plan posterior. Nesta wave, elas seriam custo adicional sem impacto proporcional comparado a completion/hover/signature help.

## Options

### Option A - Completion e hover por heuristica leve, com signature help posterior

- **Approach:** implementar `completion` usando contexto local, imports, keywords e alguns casos de member access, implementar `hover` com informacao minima, e deixar `signature help` para uma wave seguinte.
- **Pro:** menor custo inicial e menor risco de travar na arquitetura semantica.
- **Con:** pode criar uma primeira entrega inconsistente, especialmente em chamadas de stdlib e tipos importados, e pode forcar refactor cedo demais depois.
- **Maintainability:** media.

### Option B - Wave 1 coerente com completion, hover e signature help sobre uma mesma base semantica

- **Approach:** desenhar uma pequena superficie de assistencia editorial no LSP que use uma base comum para resolver simbolos, membros e assinaturas. Entregar juntos:
  - completion minimo utilizavel;
  - hover real;
  - signature help em chamadas.
- **Pro:** evita duplicacao conceitual e produz uma experiencia de editor mais consistente desde a primeira wave.
- **Con:** custo maior de desenho e implementacao agora.
- **Maintainability:** forte.

### Option C - Adiar assistencia semantica e depender do VS Code + snippets

- **Approach:** manter diagnostics e colors como estao, adicionar no maximo snippets ou pequenas ajudas na extensao.
- **Pro:** quase nenhum custo de backend.
- **Con:** nao resolve o problema real; o editor continua insuficiente para escrita cotidiana de PBS.
- **Maintainability:** fraca.

## Tradeoffs

Option C nao fecha a dor real e deve ser descartada.

Option A parece atraente para ganhar velocidade, mas carrega um risco ruim:

- introduzir `completion`, `hover` e depois `signature help` por caminhos tecnicos diferentes;
- duplicar logica entre parser local, heuristicas e linking;
- e transformar a wave 2 num retrabalho de consolidacao.

Option B custa mais, mas o custo eh justificavel porque estas tres features se apoiam nas mesmas perguntas:

- o que este simbolo representa?
- quais membros ele expõe?
- qual eh a assinatura desta chamada?
- qual o modulo/origem deste item?

Se essas perguntas forem respondidas por uma base comum, a wave 1 fica mais coerente e abre caminho natural para futuras features como `definition`, `references` e `inlay hints` via LSP.

## Recommendation

Seguir com **Option B**.

A recomendacao eh abrir uma wave 1 coerente de assistencia editorial com:

- `completion` minimo utilizavel;
- `hover` funcional;
- `signature help` funcional.

Escopo minimo recomendado para `completion`:

- keywords;
- simbolos locais em escopo;
- nomes importados/publicos relevantes;
- members apos `.` para stdlib, builtin types, structs e services/hosts reconhecidos.

Escopo minimo recomendado para `hover`:

- kind do simbolo;
- assinatura quando aplicavel;
- modulo/origem quando relevante;
- tipo ou shape basico quando isso existir de forma confiavel.

Escopo minimo recomendado para `signature help`:

- chamadas de funcao/metodo/construtor;
- parametro ativo;
- labels consistentes com a mesma representacao de assinatura usada no hover.

## Discussion

O ponto principal desta agenda nao eh “adicionar IDE features” genericamente.

O ponto principal eh definir a primeira wave de superfícies de assistencia que tiram o PBS no VS Code do estado de:

- diagnostics + coloracao

para um estado de:

- escrita assistida minima, com descoberta de API e leitura de assinatura.

Isso exige disciplina de boundary.

O VS Code extension nao deve inventar semantica local.
O servidor LSP deve continuar sendo o owner da assistencia editorial.

Da mesma forma, o LSP nao deve criar uma semantica paralela desconectada do compiler se ja existe informacao aproveitavel em parser, linking, stdlib e superficies semanticas do PBS.

Tambem vale explicitar o que fica fora desta agenda:

- formatter completo;
- identacao automatica robusta de documento;
- quick fixes;
- definition/references;
- rename;
- code actions mais amplas.

Esses itens podem virar agenda posterior.

Tambem fica registrado um criterio importante de arquitetura:

- o primeiro passo nao eh encher o protocolo de features;
- o primeiro passo eh criar uma base editorial coerente no lado `compiler/pbs` + `studio/lsp` que consiga responder simbolo, members e assinatura;
- `completion`, `hover` e `signature help` sao projeções diferentes sobre a mesma base.

E um criterio adicional de preparacao editorial:

- a wave 1 deve prever um campo/superficie opcional de documentacao no modelo editorial resolvido por simbolo;
- mas a autoria dessa documentacao na linguagem PBS, inclusive eventual anotacao `Document(...)` com markdown, fica fora desta agenda e pode seguir para discussao separada.

## Resolution

Resolucao preliminar:

- a wave 1 deve ser considerada valida quando o VS Code conseguir oferecer descoberta minima de API, leitura de assinatura e ajuda em chamadas sem depender de conhecimento local na extensao;
- `completion`, `hover` e `signature help` devem nascer sobre uma mesma base compiler-backed;
- `go to definition`, formatter e outras features de IDE ficam explicitamente fora do escopo.

Se esta leitura fizer sentido, o proximo passo eh aceitar a agenda e fechar uma `decision` que:

1. defina o escopo normativo exato de `completion`, `hover` e `signature help`;
2. fixe o boundary entre `compiler/pbs`, `studio/lsp` e `tools/vscode-extension`;
3. declare explicitamente os non-goals desta wave;
4. determine se a base deve nascer compiler-backed desde o inicio ou com alguma heuristica local estritamente limitada.

## Next Step

Se voce concordar com o enquadramento, eu converto esta agenda em `accepted` e escrevo a `decision` normativa da wave 1 de assistencia editorial para PBS no VS Code.