housekeeping
This commit is contained in:
@@ -1,196 +0,0 @@
|
||||
---
|
||||
id: DEC-0032
|
||||
ticket: studio-new-lsp-api-and-v1-boundary
|
||||
title: Boundary normativo entre lsp-api, lsp-v1 e a extensao VS Code
|
||||
status: accepted
|
||||
created: 2026-05-05
|
||||
accepted: 2026-05-05
|
||||
agenda: AGD-0035
|
||||
plans: [PLN-0065, PLN-0066, PLN-0067]
|
||||
tags: [studio, lsp, vscode, protocol, api, boundary, compiler]
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
O repositório SHALL reconstruir o stack de linguagem do Studio com separação explícita entre:
|
||||
|
||||
1. `lsp-api` como boundary interno do Studio;
|
||||
2. `lsp-v1` como adapter LSP/JSON-RPC concreto;
|
||||
3. `compiler` como owner dos serviços semânticos e de análise consumidos por esse adapter;
|
||||
4. `tools/vscode-extension` como cliente externo que continua falando LSP puro via socket TCP.
|
||||
|
||||
Esta decisão ALSO locks os seguintes pontos:
|
||||
|
||||
1. `lsp-api` MUST NOT ser espelho do protocolo LSP;
|
||||
2. `lsp-api` MUST expor apenas funcionalidades internas realmente consumíveis por outras partes do Studio;
|
||||
3. `lsp-api` MAY começar mínima, por exemplo com contratos como `bootServer(project)` e `shutdownServer(project)`;
|
||||
4. `lsp-v1` MUST concentrar o servidor LSP concreto, os DTOs de protocolo, o transporte e qualquer dependência de `LSP4J`;
|
||||
5. `LSP4J` MUST NOT vazar para fora de `lsp-v1`;
|
||||
6. `lsp-v1` MUST consumir serviços existentes de `compiler` em vez de reconstruir pipeline semântico próprio;
|
||||
7. o lifecycle do servidor LSP MUST ser associado à abertura e ao fechamento de projeto, não à abertura global do processo Studio;
|
||||
8. o atual `lsp-v1` presente hoje no repositório serve apenas como mock de conectividade VS Code ↔ Studio e MUST NOT ser tratado como padrão arquitetural, base estrutural ou referência de implementação do backend definitivo.
|
||||
9. a primeira onda de implementação desta decisão SHALL priorizar arquitetura, lifecycle e separação de responsabilidades, mesmo que o comportamento LSP permaneça deliberadamente simples ou "dumb" por um período controlado.
|
||||
|
||||
## Rationale
|
||||
|
||||
O stack legado anterior foi removido justamente porque misturava responsabilidades erradas e criou boundaries frágeis entre UI, sessão, semântica e transporte.
|
||||
|
||||
Ao mesmo tempo, o projeto já tem dois fatos importantes:
|
||||
|
||||
1. a extensão VS Code já existe e já sabe atuar como cliente LSP puro;
|
||||
2. o Studio já possui serviços de `compiler` que devem continuar sendo a fonte real de comportamento semântico.
|
||||
|
||||
Logo, o problema não é "inventar um cliente" nem "reescrever a semântica". O problema é definir corretamente:
|
||||
|
||||
1. o que é boundary interno reutilizável do Studio;
|
||||
2. o que é adapter concreto de protocolo;
|
||||
3. e onde termina a influência do protocolo externo.
|
||||
|
||||
Essa separação reduz acoplamento, melhora teste e evita que detalhes de `LSP4J` ou do transporte contaminem o restante da base.
|
||||
|
||||
Também existe uma prioridade explícita de rollout:
|
||||
|
||||
1. primeiro consolidar a arquitetura;
|
||||
2. depois adicionar capacidade semântica por camadas;
|
||||
3. sem obrigar a primeira implementação a já ser semanticamente rica.
|
||||
|
||||
Isso evita repetir o padrão anterior de crescer funcionalidade em cima de uma base estrutural errada.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### 1. Module Roles
|
||||
|
||||
`lsp-api` MUST ser tratado como módulo de boundary interno do Studio.
|
||||
|
||||
Ele SHALL:
|
||||
|
||||
1. expor somente contratos que façam sentido para outros consumidores internos do sistema;
|
||||
2. permanecer agnóstico ao protocolo LSP concreto;
|
||||
3. permanecer agnóstico a `LSP4J`;
|
||||
4. permanecer agnóstico ao transporte TCP ou a qualquer detalhe de socket;
|
||||
5. começar com surface mínima suficiente para o lifecycle do servidor por projeto.
|
||||
|
||||
`lsp-v1` MUST ser tratado como o primeiro adapter concreto do boundary acima.
|
||||
|
||||
Ele SHALL:
|
||||
|
||||
1. implementar o servidor LSP;
|
||||
2. carregar os DTOs e tipos de protocolo que forem necessários para falar LSP;
|
||||
3. carregar a dependência de `LSP4J`;
|
||||
4. realizar a tradução entre o mundo do protocolo e os serviços internos consumidos;
|
||||
5. concentrar a lógica concreta de sessão e associação `projeto -> servidor`.
|
||||
|
||||
### 2. LSP4J Containment
|
||||
|
||||
O repositório MUST tratar `LSP4J` como dependência exclusiva de `lsp-v1`.
|
||||
|
||||
Portanto:
|
||||
|
||||
1. nenhum tipo de `LSP4J` MAY aparecer em `lsp-api`;
|
||||
2. nenhum tipo de `LSP4J` MAY aparecer em outros módulos do Studio;
|
||||
3. nenhum contrato de `lsp-api` MAY depender semanticamente de tipos, nomes ou formas obrigadas pelo `LSP4J`;
|
||||
4. qualquer vazamento de `LSP4J` para fora de `lsp-v1` SHALL ser tratado como violação arquitetural.
|
||||
|
||||
### 3. Compiler Ownership
|
||||
|
||||
`lsp-v1` MUST consumir serviços existentes de `compiler` quando precisar responder capacidades editoriais e semânticas.
|
||||
|
||||
Isso implica:
|
||||
|
||||
1. `lsp-v1` MUST NOT reconstruir uma engine semântica paralela por conveniência;
|
||||
2. `lsp-v1` MUST preferir compor sobre entrypoints e serviços canônicos do `compiler`;
|
||||
3. qualquer lacuna percebida no `compiler` para servir o novo backend SHALL ser tratada como evolução explícita do `compiler`, e não como autorização para duplicação semântica dentro de `lsp-v1`.
|
||||
|
||||
### 4. Server Lifecycle
|
||||
|
||||
O lifecycle do servidor MUST ser project-scoped.
|
||||
|
||||
Regras:
|
||||
|
||||
1. abrir o processo Studio MUST NOT implicitamente significar "subir um servidor LSP global";
|
||||
2. abrir um projeto MAY disparar `bootServer(project)` através do boundary exposto por `lsp-api`;
|
||||
3. fechar um projeto MUST disparar `shutdownServer(project)` para o servidor correspondente;
|
||||
4. a implementação concreta desse bootstrap/shutdown e o vínculo entre projeto e instância do servidor MUST residir em `lsp-v1`.
|
||||
|
||||
### 5. Internal API Minimalism
|
||||
|
||||
`lsp-api` MUST nascer pequeno.
|
||||
|
||||
Ele SHALL:
|
||||
|
||||
1. expor apenas o que outro consumidor interno realmente precise enxergar;
|
||||
2. evitar DTOs de protocolo sem necessidade;
|
||||
3. evitar antecipar capacidades futuras sem consumidor real;
|
||||
4. crescer somente quando houver pressão concreta de uso interno.
|
||||
|
||||
O contrato inicial mínimo aceito por esta decisão é:
|
||||
|
||||
1. `bootServer(project)`
|
||||
2. `shutdownServer(project)`
|
||||
|
||||
Contratos adicionais MAY ser adicionados depois, mas não fazem parte do lock inicial desta decisão.
|
||||
|
||||
### 6. VS Code Transport
|
||||
|
||||
`tools/vscode-extension` SHALL permanecer cliente LSP puro via socket TCP nesta fase.
|
||||
|
||||
Isso implica:
|
||||
|
||||
1. a extensão atual pode continuar evoluindo nesse modelo;
|
||||
2. `lsp-api` MUST permanecer agnóstico a esse transporte;
|
||||
3. mudanças futuras de transporte MAY ser discutidas depois, mas não fazem parte do boundary normativo inicial.
|
||||
|
||||
### 7. Current Mock Status
|
||||
|
||||
O `lsp-v1` que existe hoje para testes de conectividade entre VS Code e Studio MUST ser tratado como mock transitório.
|
||||
|
||||
Ele MUST NOT:
|
||||
|
||||
1. servir de blueprint estrutural do novo servidor;
|
||||
2. servir de contrato implícito do sistema;
|
||||
3. servir de justificativa para manter responsabilidades colapsadas;
|
||||
4. contaminar o padrão de código alvo do backend definitivo.
|
||||
|
||||
O backend definitivo SHALL priorizar:
|
||||
|
||||
1. separação clara de responsabilidades;
|
||||
2. boundaries pequenos e explícitos;
|
||||
3. código fácil de manter;
|
||||
4. composição sobre serviços canônicos do `compiler`;
|
||||
5. isolamento rígido do adapter de protocolo.
|
||||
|
||||
### 8. Implementation Wave 1
|
||||
|
||||
A primeira onda de implementação derivada desta decisão MUST focar em transformar o mock atual em uma estrutura sólida de trabalho.
|
||||
|
||||
Essa onda SHALL incluir:
|
||||
|
||||
1. `lsp-api` mínimo com bootstrap e shutdown por projeto;
|
||||
2. `lsp-v1` organizado como adapter concreto limpo, mesmo que ainda responda um conjunto reduzido ou simplificado de capacidades;
|
||||
3. boot do servidor quando o projeto abrir;
|
||||
4. shutdown do servidor quando o projeto fechar;
|
||||
5. isolamento explícito entre boundary interno, adapter de protocolo e consumo de `compiler`.
|
||||
|
||||
Essa onda MUST NOT ser bloqueada pela ausência de "carne semântica" completa.
|
||||
|
||||
Em outras palavras:
|
||||
|
||||
1. é aceitável manter um comportamento LSP inicial deliberadamente simples;
|
||||
2. não é aceitável manter um padrão arquitetural improvisado só porque o comportamento ainda é simples;
|
||||
3. a evolução semântica futura SHALL acontecer por camadas sobre a estrutura consolidada.
|
||||
|
||||
## Constraints
|
||||
|
||||
1. Esta decisão MUST preservar a separação entre boundary interno e adapter externo.
|
||||
2. Esta decisão MUST preservar `compiler` como owner semântico do sistema.
|
||||
3. Esta decisão MUST impedir vazamento de `LSP4J` para fora de `lsp-v1`.
|
||||
4. Esta decisão MUST impedir que o mock atual de conectividade seja usado como padrão do produto.
|
||||
5. Esta decisão MUST manter `compile/build/run/debug` fora do escopo do `lsp-api` nesta fase.
|
||||
6. Qualquer plano derivado desta decisão MUST refletir explicitamente o lifecycle por projeto e a contenção de protocolo em `lsp-v1`.
|
||||
7. O primeiro plano derivado desta decisão MUST priorizar a consolidação estrutural do servidor antes do enriquecimento semântico.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-05-05: Initial draft from AGD-0035.
|
||||
- 2026-05-05: Added explicit phase-1 rollout guidance to solidify architecture before semantic depth.
|
||||
- 2026-05-05: Accepted and decomposed into PLN-0065, PLN-0066, and PLN-0067.
|
||||
-112
@@ -1,112 +0,0 @@
|
||||
---
|
||||
id: DEC-0034
|
||||
ticket: frontend-semantic-host-projection-flexibility
|
||||
title: Frontend semantic vocabularies remain canonical and hosts consume declarative projections
|
||||
status: accepted
|
||||
created: 2026-05-06
|
||||
accepted: 2026-05-06
|
||||
agenda: AGD-0037
|
||||
plans: [PLN-0072, PLN-0073, PLN-0074]
|
||||
tags: [compiler, compiler-general, frontend, semantics, vscode, host-projection, lsp]
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
Prometeu SHALL keep semantic vocabularies frontend-owned and canonical.
|
||||
Hosts such as VS Code SHALL consume declarative host projection data authored by the frontend instead of forcing frontend semantic keys into a rigid shared host taxonomy.
|
||||
|
||||
This decision locks the following normative points:
|
||||
|
||||
1. Each frontend MUST remain free to define its own semantic keys.
|
||||
2. Prometeu MUST NOT introduce a rigid global semantic token taxonomy as the canonical contract for all frontends.
|
||||
3. Host-facing semantic adaptation MUST happen through frontend-authored host projection metadata.
|
||||
4. Host projection metadata MUST be declarative and MUST NOT become the canonical semantic vocabulary.
|
||||
5. VS Code adaptation MUST consume the frontend semantic vocabulary plus its VS Code projection, not reinterpret semantic meaning ad hoc inside the extension.
|
||||
|
||||
## Rationale
|
||||
|
||||
The current stack already establishes frontend ownership over visual themes.
|
||||
Without this complementary rule, semantic vocabulary itself could still drift toward host ownership because VS Code prefers a different semantic model than a frontend may naturally publish.
|
||||
|
||||
If the repository made VS Code token categories canonical, it would:
|
||||
|
||||
1. collapse frontend semantic freedom,
|
||||
2. move semantic authorship into the host layer,
|
||||
3. and make frontend evolution hostage to one specific adapter model.
|
||||
|
||||
Declarative host projection preserves the correct ownership boundary:
|
||||
|
||||
1. frontend defines semantic meaning,
|
||||
2. frontend also defines how a given host should project that meaning,
|
||||
3. host adapters translate mechanically.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### 1. Canonical Semantic Vocabulary
|
||||
|
||||
The canonical semantic vocabulary for a document language MUST live in that frontend's contract surface.
|
||||
|
||||
This implies:
|
||||
|
||||
1. semantic keys remain frontend-owned,
|
||||
2. semantic keys MAY vary significantly between frontends,
|
||||
3. semantic keys MUST NOT be rewritten into a mandatory repository-wide host-shaped taxonomy.
|
||||
|
||||
### 2. Host Projection Contract
|
||||
|
||||
Frontend metadata MUST evolve to support host projection descriptors.
|
||||
|
||||
At minimum, a host projection descriptor for VS Code MUST be capable of expressing:
|
||||
|
||||
1. which canonical semantic key is being projected,
|
||||
2. which VS Code semantic token type should receive that key,
|
||||
3. which VS Code semantic token modifiers, if any, should accompany that projection,
|
||||
4. any fallback behavior needed when the host cannot represent the frontend key exactly.
|
||||
|
||||
The host projection descriptor MAY support other hosts later, but the first required host projection is VS Code.
|
||||
|
||||
### 3. Ownership Rules
|
||||
|
||||
Ownership SHALL be:
|
||||
|
||||
1. frontend owns semantic keys,
|
||||
2. frontend owns host projection metadata,
|
||||
3. LSP transports both,
|
||||
4. the host adapter translates both.
|
||||
|
||||
The extension MUST NOT become the place where semantic meaning is hand-mapped or reauthored as code-driven policy.
|
||||
|
||||
### 4. Relationship to DEC-0033
|
||||
|
||||
This decision complements `DEC-0033`.
|
||||
|
||||
`DEC-0033` remains normative for:
|
||||
|
||||
1. frontend-owned visual theme contracts,
|
||||
2. frontend-owned theme variants,
|
||||
3. host adapter responsibilities for visual rendering.
|
||||
|
||||
This decision adds the semantic vocabulary clarification that `DEC-0033` left implicit:
|
||||
|
||||
1. semantic vocabularies remain frontend-owned and flexible,
|
||||
2. host adaptation is projection, not normalization.
|
||||
|
||||
### 5. VS Code Adapter Rule
|
||||
|
||||
For VS Code specifically:
|
||||
|
||||
1. the extension MUST consume frontend-owned semantic keys,
|
||||
2. the extension MUST consume frontend-authored VS Code projection metadata,
|
||||
3. the extension MUST apply that projection mechanically,
|
||||
4. the extension MUST NOT force every frontend into a single rigid shared semantic taxonomy to satisfy VS Code.
|
||||
|
||||
## Constraints
|
||||
|
||||
1. No plan derived from this decision may replace frontend semantic keys with a mandatory global host taxonomy.
|
||||
2. Any plan touching VS Code semantic adaptation MUST include declarative host projection support.
|
||||
3. Any plan touching LSP transport for semantic vocabularies MUST preserve frontend canonical keys.
|
||||
4. This decision MUST be treated as complementary to `DEC-0033`, not as a rollback of frontend-owned theming.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-05-06: Initial accepted decision from AGD-0037.
|
||||
Reference in New Issue
Block a user