housekeeping
This commit is contained in:
@@ -1,128 +0,0 @@
|
||||
---
|
||||
id: AGD-0035
|
||||
ticket: studio-new-lsp-api-and-v1-boundary
|
||||
title: Novo boundary entre lsp-api, lsp-v1 e a extensao VS Code
|
||||
status: accepted
|
||||
created: 2026-05-05
|
||||
resolved: 2026-05-05
|
||||
decision: DEC-0032
|
||||
tags: [studio, lsp, vscode, protocol, api, boundary]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
O stack legado de editor, `prometeu-lsp` e `prometeu-vfs` acabou de ser removido. O próximo passo natural é reconstruir o backend de linguagem, mas sem repetir o erro anterior de misturar engine semântica, transporte LSP, sessão editorial e host UI em um único desenho.
|
||||
|
||||
Ao mesmo tempo, já existe uma extensão em `tools/vscode-extension` que hoje sabe conectar via TCP em `127.0.0.1:7777` e falar LSP como cliente real. Isso reduz incerteza no lado do FE, mas aumenta a exigência arquitetural do backend: o servidor novo precisa nascer com boundary correto.
|
||||
|
||||
O risco central é reintroduzir acoplamento acidental entre:
|
||||
|
||||
- contratos internos de linguagem;
|
||||
- transporte externo LSP;
|
||||
- implementação concreta baseada em `LSP4J`;
|
||||
- e necessidades específicas do VS Code.
|
||||
|
||||
## Context
|
||||
|
||||
- O cleanup do stack legado foi fechado por `DEC-0031`.
|
||||
- A extensão VS Code já existe em `tools/vscode-extension`.
|
||||
- A extensão usa `vscode-languageclient` e conecta por socket TCP configurável.
|
||||
- O usuário quer explicitamente que `LSP4J` **não vaze** de `lsp-v1`.
|
||||
- A intenção geral do produto é que o Studio fale a própria língua internamente e exponha adapters externos para FEs, no mesmo espírito já discutido para integrações como Tiled.
|
||||
|
||||
Hoje, a pergunta não é "como implementar o LSP inteiro", mas sim:
|
||||
|
||||
- que módulos recriar;
|
||||
- qual boundary o `lsp-api` realmente deve carregar;
|
||||
- e qual responsabilidade cabe a `lsp-v1` como adapter concreto.
|
||||
|
||||
Também já existe um direcionamento adicional do produto:
|
||||
|
||||
- `lsp-v1` deve consumir serviços existentes de `compiler`;
|
||||
- `lsp-api` deve expor funcionalidades reutilizáveis por outras partes do sistema;
|
||||
- o bootstrap do servidor deve acontecer quando um projeto é aberto, e o shutdown quando o projeto é fechado;
|
||||
- a API pode começar mínima, por exemplo com `boot server` e `shutdown server`, e crescer só quando houver necessidade real.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [x] O `lsp-api` deve expor contratos próprios de domínio/serviço ou DTOs alinhados diretamente ao protocolo LSP?
|
||||
R: o lsp-api deve expor somente servicos que serao usados por outras partes do sistema, e nao ser um espelho do protocolo.
|
||||
- [x] O `lsp-v1` deve ser somente um adapter `LSP4J` sobre serviços internos de `compiler`, ou também pode carregar parte da orquestração de sessão?
|
||||
R: O lsp-v1 deve conter o servidor e todo o necessario para falar LSP, incluindo DTOs e dependencias de LSP4J (e fazer uso de compiler quando necessario). o start e o stop do servidor podem ser chamados via lsp-api, mas a logica de orquestracao de sessao deve ficar dentro do lsp-v1.
|
||||
- [x] O lifecycle de bootstrap/shutdown do servidor por projeto pertence ao `lsp-api`, ao `lsp-v1`, ou a outro serviço do Studio?
|
||||
R: o contrato fica no lsp-api, mas a logica de orquestracao fica no lsp-v1. o lsp-api pode expor um contrato como `bootServer(project)` e `shutdownServer(project)`, mas a implementacao concreta e a logica de associar o servidor ao projeto fica no lsp-v1.
|
||||
- [x] O canal de automação (`compile/build/run/debug`) deve viver fora do novo `lsp-api` desde o início?
|
||||
R: o canal de automacao deve viver fora do lsp-api. nesse primeiro momento o foco principal deve ser o LSP e o comportamento editorial/semantico. o canal de automacao pode ser discutido e implementado separadamente, sem misturar responsabilidades.
|
||||
- [x] O `tools/vscode-extension` deve continuar falando LSP puro em socket TCP, ou o produto precisa reservar outra estratégia de transporte já nesta fase?
|
||||
R: o vscode-extension deve continuar falando LSP puro em socket TCP. o lsp-api deve ser agnóstico ao transporte, mas ainda aceito recomendacoes q sejam mais faceis ou performaticas.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - `lsp-api` como API diretamente moldada pelo protocolo LSP
|
||||
- **Approach:** recriar `lsp-api` com tipos e serviços muito próximos da superfície do protocolo, deixando `lsp-v1` apenas como bootstrap `LSP4J` e roteamento para `compiler`.
|
||||
- **Pro:** acelera integração com o cliente existente e reduz tradução entre camadas.
|
||||
- **Con:** tende a tornar o protocolo externo dono do desenho interno; muda mal quando surgir outro FE ou outro adapter.
|
||||
- **Maintainability:** fraca. O risco de vazamento conceitual do protocolo para dentro do domínio é alto, mesmo sem importar classes `LSP4J` fora de `lsp-v1`.
|
||||
|
||||
### Option B - `lsp-api` mínima e operacional; `lsp-v1` como adapter LSP4J que consome `compiler`
|
||||
- **Approach:** `lsp-api` expõe uma surface mínima e reutilizável para o sistema, começando com operações como `boot server(project)` e `shutdown server(project)` e, no máximo, contratos estáveis que outras partes do Studio precisem enxergar. `lsp-v1` concentra a implementação concreta do servidor, depende exclusivamente de `LSP4J`, e consome os serviços do `compiler` para responder às capacidades LSP.
|
||||
- **Pro:** respeita a regra de não vazamento de `LSP4J`, evita inflar a API cedo demais e alinha o lifecycle do servidor ao projeto aberto, não ao processo global do Studio.
|
||||
- **Con:** exige disciplina para não transformar `lsp-api` em um espelho parcial do protocolo nem `lsp-v1` em um segundo backend semântico solto do `compiler`.
|
||||
- **Maintainability:** forte. O backend nasce hexagonal e o custo de evolução fica mais previsível.
|
||||
|
||||
### Option C - Sem `lsp-api`; expor apenas um servidor LSP concreto em `lsp-v1`
|
||||
- **Approach:** pular a separação e concentrar tudo em um único módulo novo de servidor, com contratos locais apenas package-private ou internos.
|
||||
- **Pro:** menor custo inicial de scaffolding.
|
||||
- **Con:** repete exatamente o tipo de colapso arquitetural que gerou o legado descartado; dificulta teste, substituição de transporte e integração com outros FEs.
|
||||
- **Maintainability:** ruim. A velocidade inicial é comprada com dívida estrutural imediata.
|
||||
|
||||
## Discussion
|
||||
|
||||
O dado novo mais importante é que o cliente VS Code já está funcional como cliente LSP puro. Isso elimina a necessidade de desenhar o protocolo "pensando no editor". O editor já sabe falar LSP; quem precisa de disciplina agora é o Studio.
|
||||
|
||||
Isso empurra a arquitetura para uma separação bem objetiva:
|
||||
|
||||
- `lsp-api` não deve ser "API pública do protocolo";
|
||||
- `lsp-api` deve ser uma API interna e mínima do backend de linguagem do Studio;
|
||||
- `lsp-v1` deve ser o adapter LSP concreto e consumidor dos serviços de `compiler`;
|
||||
- `LSP4J` deve existir exclusivamente em `lsp-v1`.
|
||||
|
||||
O ponto sensível é não confundir "API interna" com "engine concreta". Se `lsp-api` virar um lugar para pôr qualquer detalhe de sessão, thread, socket, `CompletableFuture` de transporte, ou estruturas do `LSP4J`, ele já nasce errado. Pelo direcionamento atual, a API deve começar deliberadamente estreita:
|
||||
|
||||
- boot do servidor por projeto;
|
||||
- shutdown do servidor por projeto;
|
||||
- e só depois crescer quando outro consumidor real do sistema exigir isso.
|
||||
|
||||
Também vale separar desde já o que não pertence ao LSP:
|
||||
|
||||
- `compile/build/run/debug` não devem entrar no `lsp-api` por conveniência;
|
||||
- esses fluxos pertencem a um contrato de automação paralelo;
|
||||
- o LSP deve se limitar ao que é comportamento editorial/semântico.
|
||||
|
||||
Outro ponto: o usuário já fixou que o Studio é o backend autoritativo e o cliente externo é só cliente. Isso reforça que o lifecycle do servidor precisa acompanhar o projeto aberto. Em outras palavras:
|
||||
|
||||
- abrir Studio não implica subir servidor LSP global;
|
||||
- abrir projeto pode implicar subir o servidor LSP daquele projeto;
|
||||
- fechar projeto deve encerrar o servidor correspondente.
|
||||
|
||||
As respostas atuais também fecharam um boundary operacional importante:
|
||||
|
||||
- quem "fala LSP" de verdade é o `lsp-v1`;
|
||||
- `lsp-api` não é adapter nem espelho do protocolo;
|
||||
- `lsp-api` existe para expor um boundary interno consumível pelo Studio;
|
||||
- o contrato mínimo inicial pode ser pequeno, desde que suficiente para boot/shutdown por projeto;
|
||||
- DTOs, tipos e dependências do protocolo podem existir em `lsp-v1` sem contaminar a API interna.
|
||||
|
||||
## Resolution
|
||||
|
||||
Direção recomendada para convergir:
|
||||
|
||||
1. recriar `lsp-api` como surface interna mínima e reutilizável do sistema, começando com bootstrap e shutdown por projeto;
|
||||
2. recriar `lsp-v1` como adapter LSP/JSON-RPC concreto, com dependência exclusiva de `LSP4J`;
|
||||
3. fazer `lsp-v1` consumir serviços existentes de `compiler`, em vez de reconstruir pipeline semântico próprio;
|
||||
4. deixar a lógica concreta de orquestração de sessão e associação `projeto -> servidor` dentro de `lsp-v1`, mesmo quando o bootstrap/shutdown for disparado através de `lsp-api`;
|
||||
5. tratar qualquer tipo `LSP4J` fora de `lsp-v1` como violação arquitetural;
|
||||
6. manter `tools/vscode-extension` como cliente LSP puro em socket TCP;
|
||||
7. discutir separadamente o contrato de automação para `compile/build/run/debug`, em vez de empurrá-lo para dentro do LSP.
|
||||
|
||||
Neste ponto, a agenda já tem direção clara o bastante para virar `decision`. O que ainda resta fechar depois disso é implementação, não escolha arquitetural principal.
|
||||
@@ -1,85 +0,0 @@
|
||||
---
|
||||
id: AGD-0037
|
||||
ticket: frontend-semantic-host-projection-flexibility
|
||||
title: Frontend Semantic Vocabulary Flexibility and Host Projection
|
||||
status: accepted
|
||||
created: 2026-05-06
|
||||
resolved: 2026-05-06
|
||||
decision: DEC-0034
|
||||
tags: [compiler, compiler-general, frontend, semantics, vscode, host-projection, lsp]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
The current discussion exposed an architectural tension:
|
||||
|
||||
- frontend semantic keys must remain frontend-owned and flexible,
|
||||
- but VS Code prefers host-shaped semantic token categories and modifiers,
|
||||
- and forcing frontend vocabularies into a rigid global taxonomy would collapse frontend ownership into host constraints.
|
||||
|
||||
If Prometeu treats VS Code semantic categories as the canonical semantic contract, the frontend loses semantic freedom and the wrong layer starts owning language meaning.
|
||||
|
||||
## Context
|
||||
|
||||
Domain owner: `compiler/general`
|
||||
|
||||
This discussion extends `DEC-0033` rather than replacing it.
|
||||
`DEC-0033` already locked that visual themes are frontend-owned and hosts are adapters.
|
||||
|
||||
What remained implicit was how a frontend-owned semantic vocabulary should adapt to host capabilities when the host prefers a different semantic model.
|
||||
|
||||
The key clarification is:
|
||||
|
||||
- the frontend semantic vocabulary remains canonical,
|
||||
- host adaptation is declarative projection,
|
||||
- host projection does not become the canonical semantic contract.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [x] Should Prometeu define a rigid global semantic token taxonomy shared by every frontend?
|
||||
R: no. Each frontend keeps its own vocabulary.
|
||||
- [x] How should VS Code consume flexible frontend vocabularies without becoming the owner of semantic meaning?
|
||||
R: through a frontend-authored host projection for VS Code.
|
||||
- [x] Does this revise `DEC-0033`?
|
||||
R: it complements `DEC-0033` by clarifying semantic vocabulary and host projection responsibilities.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Canonicalize around VS Code token types
|
||||
|
||||
- **Approach:** Force frontends to express semantic meaning in a shared VS Code-shaped taxonomy.
|
||||
- **Pro:** Simplifies host adaptation.
|
||||
- **Con:** Makes the host model canonical and removes frontend semantic freedom.
|
||||
- **Maintainability:** Poor. It solves adapter simplicity by weakening frontend ownership.
|
||||
|
||||
### Option B - Keep frontend vocabularies canonical and add declarative host projection
|
||||
|
||||
- **Approach:** Let each frontend define its own semantic keys and publish host projection metadata that explains how a host such as VS Code should adapt those keys.
|
||||
- **Pro:** Preserves frontend semantic ownership while keeping host adaptation mechanical.
|
||||
- **Con:** Requires an additional contract layer.
|
||||
- **Maintainability:** Strong. Ownership stays correct and adapters remain declarative.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Option A would make the current VS Code situation easier, but only by moving semantic authorship to the wrong layer.
|
||||
|
||||
Option B adds contract surface, but that surface is the correct one because it keeps the frontend canonical and makes host projection explicit rather than implicit.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Adopt Option B.
|
||||
|
||||
Frontend semantic keys remain canonical and flexible.
|
||||
Hosts such as VS Code consume a declarative projection authored by the frontend for that host.
|
||||
|
||||
## Discussion
|
||||
|
||||
This discussion is intentionally narrow.
|
||||
It does not reopen the frontend-owned visual theme decision.
|
||||
It only clarifies that semantic vocabulary itself must also remain frontend-owned, and that host adaptation must be expressed as projection rather than normalization into a rigid shared taxonomy.
|
||||
|
||||
## Resolution
|
||||
|
||||
Accepted on 2026-05-06.
|
||||
|
||||
Prometeu keeps frontend-owned semantic vocabularies flexible and introduces declarative host projection as the adaptation mechanism for hosts such as VS Code.
|
||||
Reference in New Issue
Block a user