208 lines
11 KiB
Markdown
208 lines
11 KiB
Markdown
---
|
|
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.
|