prometeu-studio/discussion/workflow/decisions/DEC-0035-pbs-lsp-editor-assistance-wave-1.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0035	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	AGD-0038	PLN-0075 PLN-0076 PLN-0077	studio lsp vscode compiler compiler-pbs editor completion hover signature-help

Context

O stack atual de PBS no VS Code ja entrega diagnostics basicos e semantic highlighting frontend-owned, mas ainda nao oferece assistencia editorial minima para escrita cotidiana de codigo.

Hoje:

1. nao existe completion;
2. hover existe apenas como placeholder;
3. nao existe signature help;
4. o servidor ainda nao anuncia capabilities correspondentes para essas superficies;
5. o compiler e o frontend PBS ja possuem informacao semantica, de linking, stdlib e metadata suficiente para nao precisarmos inventar uma segunda semantica local na extensao.

Esta decisao trata apenas da primeira wave de assistencia editorial para PBS no VS Code. Ela nao cobre formatter, identacao automatica robusta, quick fixes, go to definition, references, rename nem code actions gerais.

Decision

O repositório SHALL entregar uma wave 1 de assistencia editorial via LSP para PBS no VS Code com tres superfícies funcionais:

1. completion;
2. hover;
3. signature help.

Esta wave SHALL ser considerada valida quando essas tres superfícies permitirem:

1. descoberta minima de API;
2. leitura de assinatura em simbolos e chamadas;
3. ajuda de chamada sem dependencia de conhecimento semantico local na extensao VS Code.

Esta decisao ALSO locks que:

1. completion, hover e signature help MUST nascer sobre uma mesma base editorial compiler-backed;
2. o LSP MUST ser o owner operacional da assistencia editorial;
3. a extensao VS Code MUST atuar apenas como cliente/adaptador do protocolo, e MUST NOT reconstruir semantica propria para simbolos, members ou assinaturas;
4. heuristicas locais no LSP MAY existir apenas como complemento temporario e estritamente limitado para lacunas nao resolvidas, mas MUST NOT virar uma segunda semantica canônica;
5. go to definition, formatter, identacao automatica robusta, quick fixes, references, rename e code actions amplas MUST ficar fora desta wave.

Rationale

As tres features desta wave respondem essencialmente ao mesmo conjunto de perguntas:

1. que simbolo eh este?
2. quais members ele expõe?
3. qual assinatura ele tem?
4. de onde ele vem?

Implementa-las por caminhos tecnicos diferentes introduziria:

1. duplicacao entre parser local, heuristicas e linking;
2. incoerencia entre o que aparece em completion, hover e signature help;
3. retrabalho na wave seguinte.

Portanto, a primeira entrega precisa nascer sobre uma base editorial unificada, reaproveitando o que o compiler e o frontend PBS ja sabem sobre:

1. escopo local;
2. imports e aliases;
3. stdlib;
4. builtin types;
5. services, hosts, structs, enums, constructors, functions e methods.

Technical Specification

1. Shared Editorial Resolution Surface

compiler/pbs e studio/lsp MUST introduzir uma superficie editorial resolvida comum para uso de completion, hover e signature help.

Essa superficie MUST ser capaz de responder, de forma compiler-backed:

1. identidade do simbolo;
2. kind do simbolo;
3. modulo/origem quando relevante;
4. assinatura ou shape quando aplicavel;
5. members disponíveis para receivers reconhecidos;
6. documentacao opcional quando existir, sem bloquear esta wave.

Essa superficie MAY ser exposta por novos modelos internos do compiler, novos adapters no bridge do LSP, ou ambos. Mas ela MUST permanecer derivada do compiler e MUST NOT ser reautoriada na extensao.

2. Completion Scope

completion MUST ser entregue como superfície minima utilizavel.

Na wave 1, isso MUST cobrir pelo menos:

1. keywords da linguagem;
2. nomes locais em escopo;
3. simbolos importados/publicos relevantes;
4. members apos . para superfícies reconhecidas, incluindo service, host, builtin type, struct, e call surfaces relacionadas.

completion SHOULD expor labels, kinds e detalhes coerentes com a mesma base usada por hover.

completion MUST NOT depender de tabela hardcoded na extensao para stdlib ou members de PBS.

3. Hover Scope

hover MUST deixar de ser placeholder e passar a ser simbolo-resolved.

Na wave 1, o hover MUST incluir quando disponivel:

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

hover MAY incluir documentacao textual opcional. Mas a autoria de documentacao em PBS, incluindo eventual anotacao como Document(...), MUST seguir discussao separada e MUST NOT bloquear esta wave.

4. Signature Help Scope

signature help MUST ser implementado para chamadas de:

1. funcao;
2. metodo;
3. construtor.

Na wave 1, ele MUST informar:

1. a assinatura ativa;
2. o parametro ativo;
3. labels coerentes com a mesma representacao de assinatura usada no hover.

signature help MUST usar a mesma base editorial de resolucao usada por completion e hover.

5. Boundary Responsibilities

compiler/pbs:

1. MUST continuar sendo a fonte de verdade de semantica, linking e metadata relevante para simbolos e call surfaces;
2. MUST fornecer a base necessaria para resolucao editorial de simbolos, members e assinaturas.

studio/lsp:

1. MUST projetar essa base editorial em endpoints/protocol features adequados;
2. MUST anunciar as capabilities LSP necessarias para completion, hover e signature help;
3. MUST manter o transporte fiel ao modelo compiler-backed.

tools/vscode-extension:

1. MUST consumir o protocolo como cliente;
2. MUST NOT carregar tabelas paralelas de membros, stdlib ou assinaturas como fonte principal;
3. MAY conter apenas a logica estrutural normal de integração exigida pelo VS Code.

6. Documentation Preparation Rule

Esta wave MUST preparar um campo ou superfície opcional para documentacao editorial resolvida por simbolo.

Mas esta decisao ALSO locks que:

1. a surface de autoria dessa documentacao em PBS nao faz parte desta wave;
2. a sintaxe ou contrato de linguagem para documentacao authored deve ser discutido separadamente;
3. a ausencia dessa autoria nao bloqueia completion, hover nem signature help da wave 1.

7. Explicit Non-Goals

Esta decisao MUST NOT:

1. incluir formatter completo;
2. incluir identacao automatica robusta de documento;
3. incluir go to definition;
4. incluir references;
5. incluir rename;
6. incluir quick fixes;
7. incluir code actions mais amplas;
8. definir o modelo de autoria de documentacao em PBS.

Constraints

1. A wave 1 MUST priorizar coerencia entre completion, hover e signature help sobre cobertura enciclopedica de todos os casos.
2. A extensao VS Code MUST permanecer thin; a inteligencia editorial MUST ficar no compiler/LSP.
3. A implementacao MUST favorecer evolucao futura para definition, references, documentation, e outras editor features sem exigir reescrita conceitual da base editorial.
4. A implementacao MUST evitar surfaces duplicadas para stdlib, aliases, members e signatures.
5. Qualquer plan derivado desta decisao MUST separar claramente:
   • base editorial compiler-backed;
   • projeção LSP/protocolo;
   • integração VS Code.

Revision Log

• 2026-05-08: Initial draft from AGD-0038.
• 2026-05-08: Accepted and decomposed into PLN-0075, PLN-0076, and PLN-0077.