From 5cde30f502d8d0e08f5d0a8ce7eb6bbf3aee4124 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 8 May 2026 16:09:18 +0100 Subject: [PATCH] Housekeeping --- README.md | 20 +- discussion/index.ndjson | 4 +- ...D-0038-pbs-lsp-editor-assistance-wave-1.md | 207 ------------------ ...C-0035-pbs-lsp-editor-assistance-wave-1.md | 192 ---------------- ...face-for-symbols-members-and-signatures.md | 135 ------------ ...ignature-help-over-editorial-resolution.md | 121 ---------- ...and-wave-1-editor-assistance-validation.md | 103 --------- 7 files changed, 3 insertions(+), 779 deletions(-) delete mode 100644 discussion/workflow/agendas/AGD-0038-pbs-lsp-editor-assistance-wave-1.md delete mode 100644 discussion/workflow/decisions/DEC-0035-pbs-lsp-editor-assistance-wave-1.md delete mode 100644 discussion/workflow/plans/PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md delete mode 100644 discussion/workflow/plans/PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md delete mode 100644 discussion/workflow/plans/PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md diff --git a/README.md b/README.md index 748f1020..25ad11c8 100644 --- a/README.md +++ b/README.md @@ -76,22 +76,4 @@ Important reference surfaces: - `docs/specs/packer/`: packer specifications - `docs/vm-arch/`: VM and ISA architecture references -These documents are the long-term normative source for behavior and contracts. When code and docs diverge, fix the divergence explicitly instead of relying on tribal knowledge. - -## Discussion Workflow - -This repository uses a disciplined discussion workflow under `discussion/`: - -- `discussion/workflow/agendas/` -- `discussion/workflow/decisions/` -- `discussion/workflow/plans/` -- `discussion/lessons/` -- `discussion/index.ndjson` - -The expected execution flow is: - -```text -agenda -> decision -> plan -> implement -> lesson -``` - -Do not create new workflow artifacts in legacy `docs/**/agendas`, `docs/**/decisions`, `docs/**/pull-requests`, or `docs/**/learn` paths. +These documents are the long-term normative source for behavior and contracts. When code and docs diverge, fix the divergence explicitly instead of relying on tribal knowledge. \ No newline at end of file diff --git a/discussion/index.ndjson b/discussion/index.ndjson index f52fcf37..062e221d 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,6 +1,6 @@ -{"type":"meta","next_id":{"DSC":37,"AGD":40,"DEC":36,"PLN":78,"LSN":51,"CLSN":1}} +{"type":"meta","next_id":{"DSC":37,"AGD":40,"DEC":36,"PLN":78,"LSN":52,"CLSN":1}} {"type":"discussion","id":"DSC-0036","status":"open","ticket":"pbs-symbol-documentation-and-hover-markdown","title":"Modelo de documentacao de simbolos em PBS e consumo markdown no hover","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["compiler","compiler-pbs","studio","lsp","vscode","editor","hover","documentation","markdown"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-pbs-symbol-documentation-and-hover-markdown.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08"}],"decisions":[],"plans":[],"lessons":[]} -{"type":"discussion","id":"DSC-0035","status":"in_progress","ticket":"pbs-lsp-editor-assistance-wave-1","title":"Wave 1 de assistencia editorial via LSP para PBS no VS Code","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["studio","lsp","vscode","compiler","compiler-pbs","editor","completion","hover","signature-help"],"agendas":[{"id":"AGD-0038","file":"AGD-0038-pbs-lsp-editor-assistance-wave-1.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-05-08"}],"decisions":[{"id":"DEC-0035","file":"DEC-0035-pbs-lsp-editor-assistance-wave-1.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-05-08","ref_agenda":"AGD-0038"}],"plans":[{"id":"PLN-0075","file":"PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0035"]},{"id":"PLN-0076","file":"PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0035"]},{"id":"PLN-0077","file":"PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0035"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0035","status":"done","ticket":"pbs-lsp-editor-assistance-wave-1","title":"Wave 1 de assistencia editorial via LSP para PBS no VS Code","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["studio","lsp","vscode","compiler","compiler-pbs","editor","completion","hover","signature-help"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0035-pbs-lsp-editor-assistance-wave-1/LSN-0051-compiler-backed-editor-assistance-for-pbs.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]} {"type":"discussion","id":"DSC-0034","status":"done","ticket":"frontend-semantic-host-projection-flexibility","title":"Frontend semantic vocabulary flexibility and declarative host projection","created_at":"2026-05-06","updated_at":"2026-05-07","tags":["compiler","compiler-general","frontend","semantics","vscode","host-projection","lsp"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0034-frontend-semantic-host-projection-flexibility/LSN-0048-frontend-owned-semantic-vocabularies-with-declarative-host-projection.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]} {"type":"discussion","id":"DSC-0033","status":"done","ticket":"frontend-visual-theme-spec-and-css-retirement","title":"Frontend visual theme spec and retirement of host-consumed semantic CSS","created_at":"2026-05-06","updated_at":"2026-05-08","tags":["compiler","compiler-general","frontend","presentation","theming","studio","vscode","lsp","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0050","file":"discussion/lessons/DSC-0033-frontend-visual-theme-spec-and-css-retirement/LSN-0050-frontend-owned-visual-themes-with-structured-contract-and-host-adapters.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]} {"type":"discussion","id":"DSC-0032","status":"done","ticket":"studio-new-lsp-api-and-v1-boundary","title":"Novo boundary entre lsp-api, lsp-v1 e a extensao VS Code","created_at":"2026-05-05","updated_at":"2026-05-07","tags":["studio","lsp","vscode","protocol","api","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0032-studio-new-lsp-api-and-v1-boundary/LSN-0047-project-scoped-lsp-boundary-and-protocol-containment.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]} diff --git a/discussion/workflow/agendas/AGD-0038-pbs-lsp-editor-assistance-wave-1.md b/discussion/workflow/agendas/AGD-0038-pbs-lsp-editor-assistance-wave-1.md deleted file mode 100644 index f31beaf2..00000000 --- a/discussion/workflow/agendas/AGD-0038-pbs-lsp-editor-assistance-wave-1.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -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. diff --git a/discussion/workflow/decisions/DEC-0035-pbs-lsp-editor-assistance-wave-1.md b/discussion/workflow/decisions/DEC-0035-pbs-lsp-editor-assistance-wave-1.md deleted file mode 100644 index 9991f391..00000000 --- a/discussion/workflow/decisions/DEC-0035-pbs-lsp-editor-assistance-wave-1.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -id: DEC-0035 -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 -accepted: 2026-05-08 -agenda: AGD-0038 -plans: [PLN-0075, PLN-0076, PLN-0077] -tags: [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. diff --git a/discussion/workflow/plans/PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md b/discussion/workflow/plans/PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md deleted file mode 100644 index de592972..00000000 --- a/discussion/workflow/plans/PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -id: PLN-0075 -ticket: pbs-lsp-editor-assistance-wave-1 -title: PBS Editorial Resolution Surface for Symbols, Members, and Signatures -status: open -created: 2026-05-08 -completed: -tags: [compiler, compiler-pbs, editor, completion, hover, signature-help, semantics] ---- - -## Objective - -Introduce a compiler-backed editorial resolution surface in `compiler/pbs` that can answer symbol identity, kind, origin, signature/shape, callable details, and receiver members for use by LSP `completion`, `hover`, and `signature help`. - -## Background - -`DEC-0035` requires all three editor-assistance features to be built over one shared compiler-backed base. The current repository already has useful pieces: - -- parser and AST for PBS; -- semantic validation and flow analysis; -- stdlib and import visibility rules; -- semantic token classification; -- builder-pipeline overlay analysis. - -What is still missing is an explicit editorial surface designed for interactive symbol resolution instead of only diagnostics or coloring. - -## Scope - -### Included - -- Define internal compiler-side models for editorial symbol resolution. -- Resolve local names, imported/public symbols, and recognized member surfaces. -- Resolve callable signatures for functions, methods, and constructors. -- Provide optional documentation slot(s) in the model without defining authored PBS documentation syntax. -- Add PBS-focused tests for symbol/member/signature resolution. - -### Excluded - -- LSP protocol capability changes. -- VS Code client behavior. -- Authored documentation syntax such as `Document(...)`. -- `go to definition`, `references`, `rename`, formatter, or code actions. - -## Non-Goals - -- Rebuilding the full compiler around IDE concerns. -- Solving every ambiguous or partial parse state in wave 1. -- Designing a generic multi-language IDE framework before PBS proves the model. - -## Execution Steps - -### Step 1 - Define editorial resolution models in compiler-owned surfaces - -**What:** Introduce explicit models for resolved symbols, member candidates, callable signatures, and optional documentation payload. -**How:** Add compiler-owned DTO/model types that can express: - -1. symbol identity and kind; -2. declared/imported origin; -3. callable label/signature shape; -4. receiver member entries; -5. optional documentation text field. - -The model must be expressive enough for `completion`, `hover`, and `signature help` without forcing each consumer to reinterpret raw AST nodes. -**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/**` and/or `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/**` depending on final ownership split. - -### Step 2 - Build PBS symbol resolution for local and imported surfaces - -**What:** Resolve names in editorial contexts. -**How:** Reuse parser, name/linking, stdlib import knowledge, and any existing semantic tables to resolve: - -1. local bindings in scope; -2. declared top-level PBS symbols; -3. imported/public symbols and aliases; -4. stdlib-owned surfaces currently recognized by the frontend. - -The implementation must avoid duplicating semantic truth already present in compiler/linking logic. -**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/**`. - -### Step 3 - Build member and callable resolution - -**What:** Resolve members and callable signatures for recognized receiver and call surfaces. -**How:** Support at minimum: - -1. member lookup after `.` for services, hosts, builtin types, and structs; -2. direct callable lookup for functions and constructors; -3. active-call signature resolution for later `signature help` use. - -This step must produce stable labels/details that can be reused unchanged by LSP features. -**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/**`. - -### Step 4 - Add editorial conformance tests - -**What:** Lock the compiler-backed editorial contract before LSP integration. -**How:** Add tests for: - -1. local variable and parameter resolution; -2. imported service/host/builtin-type resolution; -3. member lookup after `.` on recognized surfaces; -4. callable signature extraction for function/method/constructor cases; -5. optional documentation field stability when absent. - -**File(s):** PBS/compiler test suites under `prometeu-compiler/**/src/test/java/**`. - -## Test Requirements - -### Unit Tests - -- Model invariants for symbol/member/signature payloads. -- Resolver tests covering locals, imports, aliases, members, and constructors. - -### Integration Tests - -- Compiler-backed overlay/editorial tests using representative PBS snippets and stdlib imports. - -### Manual Verification - -- Inspect resolved payloads in tests or debug output and confirm they are sufficient to drive all three editor features without ad hoc reinterpretation. - -## Acceptance Criteria - -- [ ] Compiler-side editorial models exist for symbols, members, signatures, and optional documentation. -- [ ] PBS can resolve local names, imported/public symbols, and recognized member surfaces. -- [ ] Function, method, and constructor signatures are available through the shared editorial surface. -- [ ] No consumer is required to reconstruct signature/member meaning from raw AST-only data. - -## Dependencies - -- `DEC-0035` accepted and normatively locked. -- Existing PBS semantic and import/linking infrastructure remains the truth source. - -## Risks - -- Overfitting the first resolver to the current stdlib shape may hurt future fronts or future PBS growth. -- Mixing diagnostics-only semantics with editorial semantics carelessly may produce partial or contradictory answers. -- Incomplete member resolution can make `completion` appear flaky even if `hover` works. diff --git a/discussion/workflow/plans/PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md b/discussion/workflow/plans/PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md deleted file mode 100644 index 064f7d7d..00000000 --- a/discussion/workflow/plans/PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -id: PLN-0076 -ticket: pbs-lsp-editor-assistance-wave-1 -title: LSP Completion, Hover, and Signature Help over Editorial Resolution -status: open -created: 2026-05-08 -completed: -tags: [studio, lsp, protocol, completion, hover, signature-help, editor] ---- - -## Objective - -Expose `completion`, real `hover`, and `signature help` through the project-scoped LSP stack by projecting the compiler-backed editorial resolution surface into explicit protocol capabilities and request handlers. - -## Background - -`DEC-0035` requires `studio/lsp` to be the operational owner of these editor features while remaining faithful to compiler-backed symbol, member, and signature resolution. The current LSP path only handles diagnostics, semantic tokens, and a placeholder hover. - -## Scope - -### Included - -- Extend the internal bridge/API with completion and signature-help operations. -- Replace placeholder hover with symbol-resolved hover. -- Announce LSP capabilities for completion and signature help. -- Add message models/mappers/tests for the new request/response paths. - -### Excluded - -- Creation of the underlying compiler editorial model itself. -- Authored documentation syntax. -- VS Code-specific UI behavior beyond normal LSP consumption. - -## Non-Goals - -- `go to definition`, `references`, `rename`, formatter, code actions, or quick fixes. -- Rich workspace-wide indexing beyond what the shared editorial surface already provides. - -## Execution Steps - -### Step 1 - Extend the LSP bridge contract - -**What:** Add compiler-backed editor-assistance operations to the bridge. -**How:** Evolve `LanguageServiceBridge` and related internal messages to support at minimum: - -1. completion requests; -2. symbol-resolved hover payloads; -3. signature-help requests. - -The bridge contract must align structurally with the shared editorial resolution surface rather than inventing a second feature-specific abstraction. -**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/**`, `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/**`. - -### Step 2 - Implement compiler-backed request handling - -**What:** Wire LSP requests to compiler-backed editorial resolution. -**How:** Update `CompilerLanguageServiceBridge` so it: - -1. resolves completion candidates from local/import/member contexts; -2. resolves hover payloads from symbol identity, origin, and signatures; -3. resolves active call signatures for `signature help`. - -This step must remove the current fixed hover placeholder. -**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/**`. - -### Step 3 - Announce and map protocol capabilities - -**What:** Make the server advertise the new feature set and map payloads into lsp4j types. -**How:** Update protocol mappers and text-document service so the server announces: - -1. `completionProvider`; -2. `signatureHelpProvider`; -3. improved `hoverProvider` backed by real payloads. - -Map completion items, hover markdown, and signature-help structures into concrete LSP responses. -**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/**`, `.../mapping/**`. - -### Step 4 - Add transport and conformance tests - -**What:** Prevent regression to placeholder/editor-local behavior. -**How:** Add tests that verify: - -1. capabilities are announced correctly; -2. completion returns compiler-backed candidates; -3. hover no longer returns the baseline placeholder; -4. signature-help returns deterministic active-signature information. - -**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`. - -## Test Requirements - -### Unit Tests - -- DTO/model invariants for completion, hover, and signature-help payloads. -- Mapper tests for lsp4j conversion. - -### Integration Tests - -- LSP request/response tests using realistic PBS snippets with locals, imports, and member access. - -### Manual Verification - -- Connect the VS Code extension and confirm server capabilities include completion and signature help. -- Confirm hover content changes with the hovered symbol rather than returning static baseline text. - -## Acceptance Criteria - -- [ ] The LSP bridge exposes completion and signature-help operations in addition to diagnostics, hover, and semantic tokens. -- [ ] Hover is symbol-resolved and no longer hardcoded placeholder text. -- [ ] The server advertises completion and signature-help capabilities. -- [ ] Completion, hover, and signature help all derive from the same compiler-backed editorial surface. - -## Dependencies - -- `DEC-0035` accepted and normatively locked. -- `PLN-0075` for the shared compiler-backed editorial resolution surface. - -## Risks - -- Protocol mapping can drift from compiler payload shape if feature-specific shortcuts are added. -- Active parameter/signature calculation may be brittle around incomplete syntax unless request handling is conservative. -- Completion can feel noisy if candidate ranking or filtering is too weak in wave 1. diff --git a/discussion/workflow/plans/PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md b/discussion/workflow/plans/PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md deleted file mode 100644 index 5dfd483c..00000000 --- a/discussion/workflow/plans/PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -id: PLN-0077 -ticket: pbs-lsp-editor-assistance-wave-1 -title: VS Code Consumption and Wave 1 Editor Assistance Validation -status: open -created: 2026-05-08 -completed: -tags: [vscode, extension, editor, completion, hover, signature-help, validation] ---- - -## Objective - -Keep the VS Code extension thin while validating that the new LSP-delivered `completion`, `hover`, and `signature help` features actually produce a minimally usable PBS editing experience end to end. - -## Background - -`DEC-0035` explicitly requires the extension to remain a client/adaptor rather than a second semantic engine. Because VS Code already knows how to consume LSP completion, hover, and signature-help responses, the extension work should be small and mostly about ensuring transport, configuration, and real validation are correct. - -## Scope - -### Included - -- Confirm the extension does not need or gain local semantic tables for stdlib, members, or signatures. -- Adjust only the minimal extension/bootstrap behavior needed for the new LSP features to flow correctly. -- Add verification coverage and manual validation guidance for the full wave. - -### Excluded - -- Compiler-side editorial resolution logic. -- LSP-side protocol feature implementation. -- Formatter/indentation, code actions, or non-wave-1 IDE features. - -## Non-Goals - -- Turning the extension into a feature-rich semantic client. -- Adding hardcoded completion/signature content for PBS inside TypeScript runtime code. - -## Execution Steps - -### Step 1 - Verify thin-client integration boundaries - -**What:** Confirm the extension remains a pure LSP consumer for the new features. -**How:** Review and adjust the extension only where necessary so completion, hover, and signature help are obtained from the LSP session without client-side semantic fallback tables. -**File(s):** `tools/vscode-extension/src/**`, `tools/vscode-extension/package.json`. - -### Step 2 - Add any minimal structural configuration required by VS Code - -**What:** Keep static contribution surfaces minimal and structural. -**How:** If VS Code requires additional structural contribution metadata for the new features, add only that metadata. Do not add curated PBS semantic or signature data into the extension package. -**File(s):** `tools/vscode-extension/package.json`. - -### Step 3 - Add validation coverage for end-to-end editor assistance - -**What:** Lock the no-local-semantics rule and the end-to-end feature expectations. -**How:** Add tests or deterministic verification steps that ensure: - -1. the extension connects and receives the feature set from the server; -2. no local completion/signature tables were introduced; -3. the user-facing wave can be exercised end to end. - -**File(s):** `tools/vscode-extension/**`, existing validation harnesses if present, and related docs/test notes. - -### Step 4 - Define manual smoke scenarios for wave 1 usability - -**What:** Make the wave verifiable as a product experience rather than only a protocol exercise. -**How:** Document and run manual checks for: - -1. keyword and local-name completion; -2. imported stdlib/member completion after `.`; -3. hover on locals, imported services, builtin types, and methods; -4. signature help during function/method/constructor calls. - -**File(s):** extension verification notes or adjacent implementation docs/tests as appropriate. - -## Test Requirements - -### Unit Tests - -- Any extension-side helpers introduced for structural integration only. - -### Integration Tests - -- End-to-end or near-end-to-end validation that VS Code consumes the server feature set without local semantic duplication. - -### Manual Verification - -- Open representative PBS files in VS Code and verify `completion`, `hover`, and `signature help` behavior matches the expected wave-1 scope. - -## Acceptance Criteria - -- [ ] The extension remains thin and contains no new hardcoded PBS semantic tables for members or signatures. -- [ ] VS Code can consume the new LSP completion, hover, and signature-help responses without extension-side semantic authorship. -- [ ] Wave-1 smoke scenarios are documented and manually verifiable. - -## Dependencies - -- `DEC-0035` accepted and normatively locked. -- `PLN-0076` for the actual LSP feature delivery. - -## Risks - -- It is easy to accidentally patch around server gaps with client-local logic; this plan must resist that. -- Validation can become too protocol-centric and miss real usability failures if manual smoke scenarios are weak.