prometeu-studio/discussion/workflow/agendas/AGD-0038-pbs-lsp-editor-assistance-wave-1.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0038	pbs-lsp-editor-assistance-wave-1	Wave 1 de assistencia editorial via LSP para PBS no VS Code	accepted	2026-05-08	2026-05-08	DEC-0035	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?
• 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?
• 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?
• 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?
• 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?
• 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?
• 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?
• 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.