Wave 1 de assistencia editorial via LSP para PBS no VS Code
This commit is contained in:
@@ -0,0 +1,207 @@
|
||||
---
|
||||
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.
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
id: AGD-0039
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Modelo de documentacao de simbolos em PBS e consumo markdown no hover
|
||||
status: open
|
||||
created: 2026-05-08
|
||||
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
A wave atual de assistencia editorial quer `hover` util, mas ainda nao existe um modelo claro para documentacao authored dentro de PBS.
|
||||
|
||||
Sem esse modelo, o hover pode até mostrar:
|
||||
|
||||
- kind;
|
||||
- assinatura;
|
||||
- origem;
|
||||
- tipo/shape.
|
||||
|
||||
Mas continua sem uma superficie limpa para explicar intencao de uso, contrato semantico, detalhes de parametros ou observacoes de API.
|
||||
|
||||
Hoje a ideia proposta eh algo como:
|
||||
|
||||
- `Document(qualquer markdown aqui dentro...)`
|
||||
|
||||
como anotacao consumida diretamente pelo hover.
|
||||
|
||||
Isso parece simples no uso, mas toca em decisoes de linguagem e contrato editorial que merecem discussao propria.
|
||||
|
||||
## Context
|
||||
|
||||
Domain owner: `compiler/pbs`
|
||||
|
||||
Subdomains touched:
|
||||
|
||||
- `compiler/general`
|
||||
- `studio/lsp`
|
||||
- `tools/vscode-extension`
|
||||
|
||||
Esta agenda eh deliberadamente separada de `AGD-0038`.
|
||||
|
||||
Razao:
|
||||
|
||||
- `AGD-0038` trata da wave 1 de `completion`, `hover` e `signature help`;
|
||||
- esta nova agenda trata da autoria, armazenamento, propagacao e consumo de documentacao de simbolos.
|
||||
|
||||
O objetivo eh evitar que a primeira wave de assistencia editorial fique bloqueada por uma decisao de linguagem ainda nao fechada.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- A autoria da documentacao deve acontecer por anotacao explicita como `Document(...)`, por comentario estruturado, ou por outro mecanismo?
|
||||
- O payload authored deve aceitar markdown arbitrario como fonte canonica, ou deve haver alguma normalizacao/restricao?
|
||||
- Quais simbolos podem carregar documentacao na wave inicial:
|
||||
funcoes, methods, services, hosts, builtin types, structs, enums, fields, constructors?
|
||||
- A documentacao deve viver no AST/semantics como superficie compiler-backed explicita?
|
||||
- Como a documentacao authored em PBS se relaciona com documentacao de stdlib gerada ou importada de outras fontes?
|
||||
- O hover deve consumir markdown pronto sem transformacao, ou deve haver um pipeline intermediario de sanitizacao/normalizacao?
|
||||
- Como tratar multilinhas, escaping e ergonomia de escrita se a surface for `Document(...)`?
|
||||
- A agenda deve definir apenas o modelo de autoria, ou tambem o transporte LSP e a composicao final do hover?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Anotacao `Document(...)` com markdown como payload canonico
|
||||
|
||||
- **Approach:** introduzir uma anotacao explicita na linguagem PBS cujo conteudo ja eh markdown pronto para o hover.
|
||||
- **Pro:** autoria direta, intencao clara, pipeline simples de consumo no LSP e no hover.
|
||||
- **Con:** precisa desenhar sintaxe, escaping, multiline e regras de onde a anotacao eh permitida.
|
||||
- **Maintainability:** forte se a surface de linguagem ficar limpa.
|
||||
|
||||
### Option B - Comentarios estruturados como fonte de documentacao
|
||||
|
||||
- **Approach:** usar comentarios especiais ou doc-comments, com parser especifico para gerar documentacao de simbolo.
|
||||
- **Pro:** mais familiar para quem vem de outras linguagens e menos intrusivo no corpo semantico da linguagem.
|
||||
- **Con:** exige novo contrato de binding entre comentarios e simbolos, e pode aumentar ambiguidade editorial.
|
||||
- **Maintainability:** media.
|
||||
|
||||
### Option C - Nao definir autoria em PBS agora e suportar apenas docs de stdlib por metadata externa
|
||||
|
||||
- **Approach:** deixar a linguagem sem surface authored por enquanto e alimentar hover apenas com docs externas/geradas.
|
||||
- **Pro:** menor custo imediato de linguagem.
|
||||
- **Con:** resolve mal a autoria de codigo de usuario e deixa o modelo incompleto.
|
||||
- **Maintainability:** fraca.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Option C nao parece suficiente como direcao de produto se a intencao eh ter hover realmente util para APIs authored em PBS.
|
||||
|
||||
Option B eh plausivel, mas move o problema para um binding entre comentario e simbolo que tambem precisa ser projetado com cuidado. Isso costuma parecer mais barato do que realmente eh.
|
||||
|
||||
Option A tem um custo claro de sintaxe e modelo, mas pelo menos deixa explicito que documentacao eh metadado semantico e nao apenas texto solto ao redor do codigo.
|
||||
|
||||
Se a equipe realmente quer markdown authored pronto para consumo no hover, Option A parece a discussao mais direta e honesta.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Discutir esta agenda com viés inicial para **Option A**, mas sem fechar ainda a sintaxe final.
|
||||
|
||||
A recomendacao preliminar eh separar o problema em duas perguntas:
|
||||
|
||||
1. qual eh a surface canonical de autoria da documentacao em PBS?
|
||||
2. como essa documentacao vira um payload editorial resolvido para hover e futuros consumers?
|
||||
|
||||
Mesmo que `Document(...)` seja a direcao vencedora, a decisao deve deixar claro:
|
||||
|
||||
- onde ela pode ser usada;
|
||||
- qual formato textual aceita;
|
||||
- como ela eh preservada no compiler;
|
||||
- como chega ao LSP;
|
||||
- e como o hover deve compor isso com assinatura e metadados do simbolo.
|
||||
|
||||
## Discussion
|
||||
|
||||
Esta agenda nao deve ser reduzida a "mostrar markdown no hover".
|
||||
|
||||
O problema real eh definir ownership e boundary da documentacao:
|
||||
|
||||
- o author escreve onde?
|
||||
- o compiler preserva como?
|
||||
- o LSP transporta em qual shape?
|
||||
- o hover monta o resultado com qual ordem e responsabilidade?
|
||||
|
||||
Tambem vale observar que a escolha aqui pode influenciar mais do que hover:
|
||||
|
||||
- completions futuras podem querer `detail` e `documentation`;
|
||||
- signature help pode querer descricoes de parametros;
|
||||
- docs de stdlib podem querer surface unificada com docs authored.
|
||||
|
||||
Por isso, mesmo sendo uma agenda separada, ela conversa diretamente com a futura qualidade do editor.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Se o enquadramento fizer sentido, o proximo passo eh discutir as open questions e fechar uma `decision` propria para o modelo de documentacao de simbolos em PBS.
|
||||
Reference in New Issue
Block a user