agendas/decisions/plans for re-shape of compiler pipeline
This commit is contained in:
@@ -0,0 +1,127 @@
|
||||
---
|
||||
id: AGD-0009
|
||||
ticket: studio-debugger-workspace-integration
|
||||
title: Integrar ../debugger ao Studio como workspace dedicado
|
||||
status: open
|
||||
created: 2026-03-30
|
||||
resolved:
|
||||
decision:
|
||||
tags:
|
||||
- studio
|
||||
- debugger
|
||||
- workspace
|
||||
- integration
|
||||
- shell
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
O shell do Studio ja anuncia `WorkspaceId.DEBUG` e exibe `Debug` na workspace rail, mas nao registra nenhum workspace concreto para esse slot.
|
||||
|
||||
Hoje isso deixa o produto num estado inconsistente:
|
||||
|
||||
- a shell promete um `Debugger/Profiler` como workspace baseline;
|
||||
- `MainView` publica a opcao `Debug` na navegacao;
|
||||
- `WorkspaceHost` exige que o workspace esteja registrado;
|
||||
- a implementacao real do `Debug` continua fora do Studio, no sibling repo `../debugger`.
|
||||
|
||||
Sem uma discussion canonica, a integracao tende a cair em um de tres atalhos ruins:
|
||||
|
||||
- abrir o debugger como app externo e fingir que isso equivale a um workspace;
|
||||
- embutir a aplicacao JavaFX existente dentro do Studio sem alinhar ciclo de vida, eventos e theming;
|
||||
- reescrever tudo no Studio e perder o que o `../debugger` ja estabilizou em protocolo, controle de execucao e estado.
|
||||
|
||||
## Context
|
||||
|
||||
Domain owner: `studio`
|
||||
Owner surface: `docs/specs/studio`
|
||||
Cross-domain input: sibling repo `../debugger`
|
||||
|
||||
Superficies relevantes hoje:
|
||||
|
||||
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md` ja define `Debugger/Profiler` como parte do baseline workspace set;
|
||||
- `docs/specs/studio/2. Studio UI Foundations Specification.md` exige um modelo de workspaces orientado a eventos, com bus por workspace e republishing para o bus global;
|
||||
- `prometeu-studio/src/main/java/p/studio/window/MainView.java` ja inclui `WorkspaceId.DEBUG` na rail, mas o `register(...)` correspondente esta comentado;
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/Workspace.java` exige um contrato de `rootNode()`, `load()`, `unLoad()` e integra o workspace a um `StudioWorkspaceEventBus`;
|
||||
- `../debugger` ja existe como aplicacao JavaFX separada, com `Application`/`Stage`, FXML, Dagger, i18n, cliente DevTools, protocolo TCP/JSONL e controle de execucao.
|
||||
|
||||
O boundary de produto tambem ja aponta a direcao correta:
|
||||
|
||||
- o shell do Studio deve enquadrar workspaces sem absorver detalhe operacional;
|
||||
- logs e detalhe de execucao pertencem ao workspace que os possui;
|
||||
- o debugger e uma superficie de execucao, nao um detalhe lateral do painel global de utilidades.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] O objetivo da primeira integracao e hospedar a experiencia atual do `../debugger` quase inteira, ou abrir um primeiro wave menor sob o contrato nativo de workspace do Studio?
|
||||
- [ ] Quais partes do `../debugger` sao `core` reaproveitavel dentro do Studio, e quais sao shell/bootstrap de app standalone que nao devem atravessar a fronteira?
|
||||
- [ ] Qual deve ser a topologia de dependencia: composite build entre repositorios siblings, extracao para modulos compartilhados, ou migracao seletiva de codigo?
|
||||
- [ ] Quem passa a ser o owner do ciclo de vida da sessao de debug: o `DebugWorkspace`, a shell do Studio, ou um servico compartilhado com a run surface?
|
||||
- [ ] Como eventos, telemetria, logs e estados do debugger entram no bus de workspace e no bus global sem criar um segundo sistema paralelo de notificacao?
|
||||
- [ ] O primeiro corte deve incluir `profiler` junto com `debugger`, ou o baseline inicial fecha apenas `debugger` e deixa profiling como extensao posterior?
|
||||
- [ ] Como preservar tema, i18n e consistencia visual se parte da UI atual do `../debugger` ainda estiver em FXML e recursos proprios?
|
||||
- [ ] O app standalone `../debugger` continuara existindo como consumidor paralelo do mesmo core, ou a integracao no Studio passa a ser o destino primario?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Launcher externo a partir do Studio
|
||||
- **Approach:** O Studio oferece um ponto de entrada para abrir `../debugger` como processo/janela externa, mantendo a integracao dentro da shell apenas como acao de lancamento.
|
||||
- **Pro:** Menor custo inicial e reaproveitamento maximo da app atual.
|
||||
- **Con:** Nao entrega um workspace real do Studio, fragmenta estado/sessao e conflita com a baseline shell spec.
|
||||
- **Maintainability:** Fraca como arquitetura final. Pode servir no maximo como ponte temporaria, mas nao resolve o contrato de workspace.
|
||||
|
||||
### Option B - Embutir a UI atual do debugger quase inteira dentro de um workspace host
|
||||
- **Approach:** Reaproveitar FXML/controllers do `../debugger` e monta-los dentro de um `DebugWorkspace`, fazendo adaptacoes localizadas de DI, lifecycle e navegacao.
|
||||
- **Pro:** Reaproveita mais UI existente e acelera a primeira tela funcional.
|
||||
- **Con:** Carrega para dentro do Studio um bootstrap orientado a `Application`/`Stage`, com modelo proprio de lifecycle, theming e eventos que nao casa naturalmente com o contrato de workspace atual.
|
||||
- **Maintainability:** Media para baixa. Economiza reescrita imediata, mas cristaliza um boundary torto entre app standalone e workspace embutido.
|
||||
|
||||
### Option C - Workspace nativo do Studio apoiado em core extraido do debugger
|
||||
- **Approach:** Tratar o `../debugger` como fonte de servicos, protocolo, estado e controle de execucao reaproveitaveis, mas implementar o `DebugWorkspace` como composicao nativa do Studio sobre o contrato `Workspace` + bus tipado + lifecycle-managed controls.
|
||||
- **Pro:** Alinha shell spec, workspace framework e boundary de produto, sem descartar o investimento ja feito no debugger.
|
||||
- **Con:** Exige separar explicitamente o que e `core` reutilizavel e o que e shell standalone, entao a primeira onda precisa de mais desenho tecnico.
|
||||
- **Maintainability:** Forte. Preserva a direcao arquitetural correta e permite que Studio e app standalone compartilhem nucleo sem colapsarem num acoplamento acidental.
|
||||
|
||||
### Option D - Migracao integral do debugger para dentro do Studio
|
||||
- **Approach:** Absorver codigo e UI do `../debugger` para dentro dos modulos do Studio e tratar a aplicacao standalone como legado a ser aposentado.
|
||||
- **Pro:** Simplifica ownership futuro se o produto decidir convergir totalmente para uma unica shell.
|
||||
- **Con:** E a aposta mais cara e mais irreversivel, antes mesmo de fechar o contrato de integracao e o que ainda deve continuar independente.
|
||||
- **Maintainability:** Media. Pode ser boa no longo prazo, mas e prematura enquanto o boundary entre `workspace` e `app standalone` ainda nao esta fechado.
|
||||
|
||||
## Discussion
|
||||
|
||||
O ponto principal nao e "como mostrar alguma tela de debug no Studio". O ponto principal e decidir qual contrato queremos estabilizar entre:
|
||||
|
||||
- a shell do Studio, que ja assume workspaces independentes e orientados a eventos;
|
||||
- o `DebugWorkspace`, que precisa ser um workspace real, com ownership claro de detalhe operacional;
|
||||
- e o `../debugger`, que hoje concentra bootstrap de app, protocolo, estado e UI numa aplicacao separada.
|
||||
|
||||
O fato de a rail ja ter `Debug` e a spec ja falar em `Debugger/Profiler` indica que a integracao nao e trabalho especulativo.
|
||||
Ela ja faz parte da topologia esperada do Studio.
|
||||
|
||||
Por isso, as opcoes que preservam o debugger apenas como janela externa ou que arrastam a app inteira para dentro do host sem remodelar o boundary resolvem pouco:
|
||||
|
||||
- a primeira evita o trabalho agora, mas nao entrega o produto prometido pela shell;
|
||||
- a segunda reaproveita UI, mas importa um modelo arquitetural que nao conversa bem com `Workspace`, `StudioWorkspaceEventBus`, theming compartilhado e lifecycle-managed controls.
|
||||
|
||||
O caminho mais coerente parece ser separar o problema em duas camadas:
|
||||
|
||||
1. um `debugger core` reaproveitavel, com sessao, protocolo, telemetria, logs e controle de execucao;
|
||||
2. uma composicao de `DebugWorkspace` nativa do Studio, que consome esse core como mais um workspace do shell.
|
||||
|
||||
Isso nao obriga uma reescrita total imediata da logica do debugger.
|
||||
Obriga apenas que a UI e o bootstrap standalone parem de ser tratados como se fossem a fronteira certa de integracao.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recommended direction: seguir com **Option C**.
|
||||
|
||||
A agenda deve convergir para uma decisao com os seguintes fechamentos:
|
||||
|
||||
1. `Debug` no Studio deve virar um workspace real, nao apenas launcher de app externo;
|
||||
2. o boundary correto de reaproveitamento esta em servicos/protocolo/estado do debugger, nao no bootstrap `Application`/`Stage` como unidade de integracao;
|
||||
3. o workspace integrado deve obedecer ao contrato do Studio para lifecycle, event bus, theming e i18n;
|
||||
4. o destino do app standalone precisa ser explicitado: consumidor paralelo do mesmo core durante migracao, ou superficie secundaria apos a integracao;
|
||||
5. o primeiro corte deve declarar se `profiler` entra junto com `debugger` ou fica explicitamente fatiado para depois.
|
||||
|
||||
Next step suggestion: converter esta agenda em uma `decision` que feche o modelo de integracao, o boundary de ownership entre `studio` e `../debugger`, a topologia de dependencias entre repositorios e o escopo da primeira wave de `DebugWorkspace`.
|
||||
@@ -0,0 +1,178 @@
|
||||
---
|
||||
id: AGD-0010
|
||||
ticket: studio-code-editor-workspace-foundations
|
||||
title: Iniciar foundations do Code Editor no Studio sem LSP
|
||||
status: open
|
||||
created: 2026-03-30
|
||||
resolved:
|
||||
decision:
|
||||
tags:
|
||||
- studio
|
||||
- editor
|
||||
- workspace
|
||||
- multi-frontend
|
||||
- lsp-deferred
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
O shell do Studio ja assume `Code Editor` como parte do baseline workspace set, mas a implementacao atual do `EditorWorkspace` ainda e apenas um `CodeArea` com texto hardcoded e botoes sem modelo real de documento, tabs, arquivos, dirty state ou sessao de projeto.
|
||||
|
||||
Ao mesmo tempo, queremos iniciar os trabalhos do editor agora, com foco em UI e infraestrutura robusta para varios frontends, mas sem cair em uma dependencia prematura de LSP.
|
||||
|
||||
Sem fechar a boundary agora, a implementacao pode desviar para dois extremos ruins:
|
||||
|
||||
- o Studio virar uma casca quase vazia que depende de cada frontend ate para abrir, salvar e manter buffers;
|
||||
- ou o Studio absorver semantica demais e virar uma segunda autoridade sobre parsing, diagnosticos e modelo de compilacao.
|
||||
|
||||
## Context
|
||||
|
||||
Domain owner: `studio`
|
||||
Owner surface: `docs/specs/studio`
|
||||
Cross-domain input: `compiler`
|
||||
|
||||
Superficies relevantes hoje:
|
||||
|
||||
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md` ja define `Code Editor` como workspace baseline do shell;
|
||||
- `docs/specs/studio/2. Studio UI Foundations Specification.md` exige workspaces com composicao root, event bus tipado, lifecycle-managed controls e infra reutilizavel;
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java` hoje monta um `CodeArea` simples sem modelo de arquivos do projeto;
|
||||
- `prometeu-studio/src/main/java/p/studio/projects/ProjectLanguageCatalogService.java` ja consome `FrontendRegistryService` e `FrontendSpec`, o que mostra que o Studio ja reconhece multiplos frontends e source roots por linguagem;
|
||||
- `prometeu-compiler/.../FrontendSpec.java` ja modela `languageId`, `allowedExtensions`, `sourceRoots`, `caseSensitive` e versoes de stdlib;
|
||||
- o compiler hoje ainda descobre e le fontes diretamente do filesystem: `LoadSourcesPipelineStage` faz `walkFileTree(...)` nos `sourceRoots`, `BuilderPipelineContext.compilerContext(...)` instancia `SourceProviderFactory.filesystem()`, e `SourceHandle` le bytes com `Files.readAllBytes(path)`;
|
||||
- `docs/roadmaps/lsp/` ja existe como trilha separada, mas esta wave quer editor sem depender de LSP;
|
||||
- o precedente do packer fixa uma boa disciplina de ownership, mas ele nao deve ser copiado mecanicamente para o editor sem discutir a diferenca entre semantica de dominio e sessao generica de edicao.
|
||||
|
||||
O ponto mais sensivel desta agenda e justamente essa diferenca:
|
||||
|
||||
- no packer, Studio nao deve reinventar semantica de asset, snapshots operacionais ou write lanes de dominio;
|
||||
- no editor, leitura/escrita de arquivos fonte, dirty tracking, buffers em memoria e snapshots documentais fazem parte da propria experiencia do workspace e nao sao, por si so, semantica de linguagem.
|
||||
|
||||
Direcao adicional ja explicitada para a UX:
|
||||
|
||||
- o editor deve seguir um baseline proximo ao modelo do IntelliJ;
|
||||
- a ala esquerda deve ser um `Project Navigator` com arquivos/pastas relevantes do projeto;
|
||||
- a area central deve ter tabs de arquivos abertos no topo e o editor rico no corpo principal;
|
||||
- a regiao inferior deve ser um helper persistente para prompts, tips e feedback contextual sobre o codigo atual, funcionando mais como `advanced editor log` do que como console cru.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Qual e o seam normativo para ligar `document snapshots` do editor ao compiler: substituir `SourceProviderFactory.filesystem()` por provider de sessao, ou introduzir uma etapa explicita que materializa uma visao congelada de documentos antes do pipeline?
|
||||
- [ ] O primeiro wave do editor deve nascer com tabs multiplas e sessao multi-documento completa, ou tabs multiplas com uma politica mais simples de documentos ativos/carregados?
|
||||
- [ ] Como o `EditorWorkspace` descobre quais arquivos e source roots sao editaveis a partir de `ProjectReference.languageId` e `FrontendSpec`?
|
||||
- [ ] Quem detecta modificacoes externas em arquivos abertos e como o conflito entre disco e buffer em memoria deve aparecer para o usuario?
|
||||
- [ ] Alem do baseline ja aceito (`Project Navigator`, tabs, editor central, helper inferior), a primeira wave tambem deve incluir `outline` ou `status bar`, ou esses elementos ficam explicitamente para depois?
|
||||
- [ ] Como preservar uma UI consistente entre linguagens diferentes sem forcar cada frontend a carregar seu proprio mini-editor completo?
|
||||
- [ ] O que fica explicitamente fora desta wave por ausencia de LSP: autocomplete, go to definition, semantic diagnostics ao digitar, symbols, rename, code actions?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Studio como casca pura; frontend/backends fazem o resto
|
||||
- **Approach:** O Studio hospeda a area visual do editor, mas leitura, escrita, buffers, snapshots e demais operacoes relevantes ficam delegadas a adaptadores por linguagem ou a servicos externos.
|
||||
- **Pro:** Mantem o Studio "leve" e minimiza responsabilidade local.
|
||||
- **Con:** Duplica infraestrutura generica em cada frontend, acopla UX basica a backend de linguagem e torna dificil sustentar uma experiencia coerente multi-FE sem LSP.
|
||||
- **Maintainability:** Fraca. A boundary fica formalmente limpa, mas o custo reaparece como fragmentacao de sessao, inconsistencias de UX e adaptadores repetidos.
|
||||
|
||||
### Option B - Studio possui sessao generica de documentos; frontends possuem semantica
|
||||
- **Approach:** O Studio passa a possuir uma camada generica de editor para descoberta de arquivos, open/save, dirty tracking, tabs, estado ativo, deteccao de mudanca externa e snapshots imutaveis de documento em memoria; frontends consomem essa camada como entrada para highlighting, parsing, diagnosticos e outras features atuais ou futuras.
|
||||
- **Pro:** Cria uma base robusta para varios frontends mesmo sem LSP, evita duplicacao de infra generica e mantem a semantica de linguagem fora do workspace visual.
|
||||
- **Con:** Exige disciplina para nao confundir `snapshot documental` com `snapshot semantico` do compiler e para nao deixar a camada generica vazar regras de linguagem.
|
||||
- **Maintainability:** Forte. A separacao entre sessao de edicao e semantica de linguagem fica clara e expansivel.
|
||||
|
||||
### Option C - Cada frontend possui seu proprio stack de editor end-to-end
|
||||
- **Approach:** O Studio oferece apenas um host de workspace, e cada frontend implementa seu proprio editor, file model, snapshots e event wiring do zero.
|
||||
- **Pro:** Maxima liberdade por linguagem.
|
||||
- **Con:** Destrói a chance de um framework comum de editor, duplica problema de tabs/buffers/save/conflicts e torna a shell dependente de N mini-produtos locais.
|
||||
- **Maintainability:** Fraca. Funciona para prototipos isolados, mas nao para um Studio que quer suportar varios FEs sob uma UX comum.
|
||||
|
||||
### Option D - Esperar LSP e desenhar o editor em torno dele
|
||||
- **Approach:** Adiar a infra editorial mais seria ate que exista um backend LSP suficientemente funcional e modelar o editor a partir desse contrato.
|
||||
- **Pro:** Pode reduzir retrabalho se o LSP for a unica fronteira desejada.
|
||||
- **Con:** Conflita com o objetivo desta wave, atrasa o editor, e ainda nao resolve ownership de file IO, buffers e dirty state, que continuam existindo mesmo com LSP.
|
||||
- **Maintainability:** Media para baixa. O LSP ajuda na semantica, mas nao substitui a sessao generica de edicao.
|
||||
|
||||
## Discussion
|
||||
|
||||
O precedente do packer e util, mas ele nao responde sozinho a pergunta desta agenda.
|
||||
|
||||
No packer, a semantica de dominio e forte:
|
||||
|
||||
- identidade de asset;
|
||||
- validacao;
|
||||
- write lane;
|
||||
- snapshots operacionais;
|
||||
- causality de eventos.
|
||||
|
||||
Nessa area, faz sentido Studio atuar mais como adaptador editorial do que como autoridade.
|
||||
|
||||
No editor de codigo, porem, existe uma camada anterior a qualquer semantica de linguagem:
|
||||
|
||||
- abrir arquivo;
|
||||
- manter buffer em memoria;
|
||||
- controlar dirty state;
|
||||
- salvar em disco;
|
||||
- alternar tabs;
|
||||
- versionar snapshots documentais;
|
||||
- reagir a mudancas externas;
|
||||
- expor um modelo de sessao que qualquer FE consiga consumir.
|
||||
|
||||
Essas responsabilidades nao sao "semantica de compiler". Sao responsabilidades normais de um editor.
|
||||
Se o Studio se recusar a possui-las, cada frontend ou integracao futura precisara reinventar a mesma infraestrutura.
|
||||
|
||||
Do ponto de vista de UX, a direcao mais solida e assumir um baseline de tres regioes dentro do `EditorWorkspace`:
|
||||
|
||||
1. `Project Navigator` na esquerda
|
||||
2. `Editor Workarea` no centro, com tabs acima e editor no corpo
|
||||
3. `Editor Helper Panel` na base, para tips, prompts, hints e feedback contextual
|
||||
|
||||
Esse painel inferior merece cuidado de nomenclatura e ownership.
|
||||
Ele nao deve nascer como "console generico" nem como dumping ground de logs tecnicos.
|
||||
Melhor trata-lo como uma superficie editorial guiada pelo contexto do documento ativo.
|
||||
|
||||
Sugestao de papel para esse helper:
|
||||
|
||||
- mostrar hints sobre arquivo, linguagem e estado do documento;
|
||||
- receber mensagens de parse/local validation quando existirem;
|
||||
- explicar bloqueios de save, conflitos de disco e prompts do editor;
|
||||
- no futuro, acomodar saidas de LSP ou FE sem acoplar a shell global a isso.
|
||||
|
||||
Em outras palavras: ele deve ser um `assistant/log` de workspace, nao um substituto do painel global `Activity` e nao um terminal cru.
|
||||
|
||||
O boundary mais saudavel parece ser:
|
||||
|
||||
1. o Studio possui a sessao generica de documentos e a UX editorial comum;
|
||||
2. os frontends recebem snapshots documentais imutaveis como entrada;
|
||||
3. parsing, name resolution, diagnostics, semantic tokens, completions e afins continuam fora da camada generica do editor;
|
||||
4. LSP, quando existir, entra como um consumidor/provedor de semantica sobre essa base, nao como substituto da base.
|
||||
|
||||
O estado atual do compiler reforca essa necessidade.
|
||||
Hoje o build pipeline ainda assume filesystem como source of truth imediata:
|
||||
|
||||
- os arquivos sao descobertos por crawl direto nos `sourceRoots`;
|
||||
- o `BuilderPipelineContext` nasce com `SourceProviderFactory.filesystem()`;
|
||||
- cada `SourceHandle` le bytes do `Path` canonico.
|
||||
|
||||
Isso significa que, se quisermos uniformizar Studio, FE services e LSP futuro em torno de uma mesma visao documental, precisamos introduzir explicitamente uma camada de `document snapshot` antes do consumo pelo pipeline.
|
||||
O lado bom e que ja existe um seam util: `SourceProviderFactory` nao esta hardcoded em todos os callsites e ja sugere providers alternativos, inclusive `in-memory`.
|
||||
|
||||
Isso tambem ajuda com a meta de varios FEs:
|
||||
|
||||
- `FrontendSpec` ja informa roots e extensoes;
|
||||
- o `EditorWorkspace` pode montar a superficie a partir disso;
|
||||
- e cada linguagem fica livre para plugar servicos sem destruir o modelo editorial comum.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recommended direction: seguir com **Option B**.
|
||||
|
||||
A agenda deve convergir para uma decisao com os seguintes fechamentos:
|
||||
|
||||
1. o Studio deve possuir uma camada generica de `document/session` para o Code Editor;
|
||||
2. essa camada pode ler e escrever arquivos fonte e manter snapshots documentais em memoria;
|
||||
3. essa camada nao deve possuir semantica de linguagem, parsing autoritativo ou diagnosticos como responsabilidade primaria;
|
||||
4. frontends devem consumir snapshots documentais do editor por um contrato explicito, imutavel e versionado;
|
||||
5. como o compiler hoje ainda le do filesystem, a decisao precisa fechar uma etapa/seam concreta para injetar `document snapshots` antes do pipeline, uniformizando a entrada de Studio, FE services e LSP futuro;
|
||||
6. LSP fica explicitamente fora do primeiro wave, mas a modelagem precisa deixar caminho limpo para ele;
|
||||
7. a primeira wave do editor deve normatizar explicitamente o baseline visual do workspace: `Project Navigator` na esquerda, tabs no topo da area central, editor rico no corpo e `Editor Helper Panel` inferior reservado;
|
||||
8. o `Editor Helper Panel` nasce passivo na primeira wave, como espaco reservado para prompts, tips e feedback contextual, sem obrigar interatividade imediata.
|
||||
|
||||
Next step suggestion: converter esta agenda em uma `decision` que feche o boundary entre `EditorWorkspace`, sessao documental do Studio e servicos de frontend, incluindo o escopo exato da primeira wave de UI sem LSP.
|
||||
+194
@@ -0,0 +1,194 @@
|
||||
---
|
||||
id: AGD-0011
|
||||
ticket: compiler-analyze-compile-build-pipeline-split
|
||||
title: Desacoplar o pipeline do compiler em analyze, compile e build
|
||||
status: accepted
|
||||
created: 2026-03-30
|
||||
resolved: 2026-03-30
|
||||
decision: DEC-0007
|
||||
tags:
|
||||
- compiler
|
||||
- pipeline
|
||||
- artifacts
|
||||
- build
|
||||
- analysis
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Hoje o pipeline principal do compiler exposto por `BuilderPipelineService` e monolitico: ele resolve dependencias, carrega fontes, roda frontend, lowering, otimizacao, emissao, verificacao e sempre termina escrevendo `build/program.pbx`.
|
||||
|
||||
Isso acopla tres intencoes diferentes num unico fluxo:
|
||||
|
||||
- analisar codigo e produzir diagnosticos/estado semantico;
|
||||
- compilar ate um resultado executavel em memoria;
|
||||
- materializar artefato final em disco.
|
||||
|
||||
Esse acoplamento atrapalha diretamente o proximo wave do Studio editor e o futuro LSP:
|
||||
|
||||
- o editor precisa de `analyze` sem forcar emissao de PBX;
|
||||
- um consumidor de semantica pode precisar de `compile` em memoria sem write side effects;
|
||||
- `build` deve continuar existindo como fluxo de artefato, mas nao como unica forma de usar o compiler.
|
||||
|
||||
## Context
|
||||
|
||||
Domain owner: `compiler`
|
||||
Owner surface: `docs/specs/compiler`
|
||||
Cross-domain input: `studio`
|
||||
|
||||
Superficies relevantes hoje:
|
||||
|
||||
- `prometeu-compiler/prometeu-build-pipeline/.../BuilderPipelineService.java` registra uma lista fixa de stages e sempre inclui `WriteBytecodeArtifactPipelineStage` no fim;
|
||||
- `EmitBytecodePipelineStage` ja produz `ctx.bytecodeModule` e `ctx.bytecodeBytes` em memoria antes de qualquer write em disco;
|
||||
- `WriteBytecodeArtifactPipelineStage` apenas persiste `build/program.pbx`, o que mostra que a emissao de artefato ja e uma preocupacao separavel;
|
||||
- `docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md` normatiza a fronteira de emissao PBX/bytecode, mas nao exige que todo consumo do compiler materialize artefato em disco;
|
||||
- na discussion do editor (`DSC-0010`), ja ficou aceito que `SourceProviderFactory` sera mantido como boundary de leitura, com providers mais especificos no futuro para sessao documental do editor.
|
||||
- embora PBS seja hoje o frontend mais avancado nesse caminho, esta agenda pertence ao dominio `compiler` e precisa preservar um contrato de pipeline frontend-agnostico, reutilizavel por PBS e por futuros FEs sem regressao no comportamento de `compile`.
|
||||
|
||||
Boundary explicitamente fechado para esta agenda:
|
||||
|
||||
- `SourceProviderFactory` continua sendo a fronteira de leitura do compiler;
|
||||
- esta agenda NAO vai discutir ainda o novo provider do editor;
|
||||
- esta agenda vai discutir apenas como expor `analyze`, `compile` e `build` como entradas distintas do compiler.
|
||||
- o split do pipeline nao pode introduzir semantica especial de PBS na API operacional do compiler; compatibilidade com o `compile` atual de PBS deve ser tratada como restricao obrigatoria.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [x] Qual deve ser o corte exato entre `analyze` e `compile`: `analyze` para no frontend/diagnostics, ou inclui tambem lowering/backend facts uteis para tooling?
|
||||
Recomendacao: `analyze` deve terminar em `FrontendPhasePipelineStage`, isto e, `ResolveDeps + LoadSources + FrontendPhase`, expondo diagnosticos e facts semanticos orientados a tooling sem avancar para lowering ou emissao.
|
||||
- [x] `compile` deve ir ate `bytecodeModule`/`bytecodeBytes` em memoria sem write, ou deve parar em `IRVM` e deixar emissao para `build`?
|
||||
Recomendacao: `compile` deve terminar em `VerifyBytecodePipelineStage`, produzindo `bytecodeModule` e `bytecodeBytes` verificados em memoria sem write side effects; parar em `IRVM` deixaria a superficie incompleta para consumidores que precisam de resultado executavel sem persistencia.
|
||||
- [x] A verificacao (`VerifyBytecodePipelineStage`) pertence a `compile`, a `build`, ou a ambos conforme perfil?
|
||||
Recomendacao: `VerifyBytecodePipelineStage` e o stage terminal de `compile`, e `build` apenas adiciona `WriteBytecodeArtifactPipelineStage` depois disso; `compile` nao deve devolver bytes nao verificados.
|
||||
- [x] Como representar esses tres modos: services separados, perfis de pipeline, ou uma composicao explicita de stage groups?
|
||||
Recomendacao: expor tres chamadas canonicas no mesmo pipeline compartilhado, por exemplo `analyze`, `compile` e `build`, evitando tanto tres pipelines independentes quanto um unico `run` monolitico com semantica implicita.
|
||||
- [x] O resultado de `analyze` deve expor um `AnalysisSnapshot` estavel para editor/LSP, ou apenas diagnosticos + facts minimos no primeiro wave?
|
||||
Recomendacao: `analyze` deve expor um `AnalysisSnapshot` estavel ja no primeiro wave, mas com shape minimo e pragmatico, carregando apenas os facts e handles necessarios para editor/LSP.
|
||||
- [x] O CLI atual e os callsites existentes devem continuar mapeando `build` como comportamento default?
|
||||
Recomendacao: sim; a mudanca deve ampliar a superficie operacional do compiler sem quebrar o comportamento default atual de artefato em disco.
|
||||
- [x] Como evitar que `build` e `compile` passem a divergir semanticamente por ordem de stages ou gates diferentes?
|
||||
Recomendacao: `build` deve ser definido normativamente como o mesmo fluxo de `compile`, encerrado por `WriteBytecodeArtifactPipelineStage`, sem reorder ou gates semanticos exclusivos fora da persistencia terminal.
|
||||
- [x] LSP/editor devem usar outro pipeline, ou o mesmo pipeline com chamadas e contextos diferentes?
|
||||
Recomendacao: devem usar o mesmo pipeline canonico, mas atraves de chamadas diferentes e configs/contextos distintos por entrypoint; mudar inputs, sinks e shape de resultado e valido, mas mudar a semantica central dos stages canonicos nao.
|
||||
- [x] O `run` atual deve continuar existindo como alias, ou deve ser absorvido por `build`?
|
||||
Recomendacao: `run` nao deve permanecer como entrypoint publico; o comportamento default de hoje deve ser absorvido por `build`, com contexto/config de filesystem construido fora do pipeline em si.
|
||||
- [x] Quais contratos ou specs precisam receber propagacao quando o pipeline deixar de ter uma unica entrada monolitica?
|
||||
Recomendacao: a propagacao principal deve atingir a spec operacional do pipeline do compiler, os contratos de CLI/callsites e a documentacao de resultados intermediarios; a spec de PBX continua authority de emissao, nao de persistencia em disco.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Manter `BuilderPipelineService` monolitico e adicionar flags
|
||||
- **Approach:** Preservar o pipeline atual e usar flags condicionais para pular write de artefato ou parar em stages intermediarios.
|
||||
- **Pro:** Menor mudanca inicial.
|
||||
- **Con:** Esconde perfis diferentes dentro de um fluxo ad hoc, torna os cortes menos legiveis e aumenta risco de combinacoes invalidas.
|
||||
- **Maintainability:** Fraca. O comportamento fica implicito e espalhado por condicionais.
|
||||
|
||||
### Option B - Definir tres entrypoints normativos sobre um pipeline composavel
|
||||
- **Approach:** Modelar o pipeline como composicao reutilizavel de stage groups e expor tres modos canonicos: `analyze`, `compile` e `build`.
|
||||
- **Pro:** Torna o contrato explicito, reaproveita as mesmas stages onde fizer sentido e separa claramente analise, compilacao em memoria e emissao de artefato.
|
||||
- **Con:** Exige fechar com precisao o corte entre as fases e o shape dos resultados intermediarios.
|
||||
- **Maintainability:** Forte. O compiler ganha uma superficie operacional clara para CLI, Studio, testes e LSP.
|
||||
|
||||
### Option C - Separar services independentes por responsabilidade
|
||||
- **Approach:** Criar services distintos e quase autossuficientes para `AnalyzeService`, `CompileService` e `BuildService`, cada um com seu proprio encadeamento.
|
||||
- **Pro:** As responsabilidades ficam bem nomeadas.
|
||||
- **Con:** Se a composicao nao for rigorosamente compartilhada, o risco de drift entre os fluxos cresce rapido.
|
||||
- **Maintainability:** Media. Pode funcionar, mas so se a infraestrutura comum ficar bem centralizada.
|
||||
|
||||
## Discussion
|
||||
|
||||
O codigo atual ja mostra o seam principal que queremos aproveitar:
|
||||
|
||||
1. primeiro o pipeline resolve e analisa a workspace;
|
||||
2. depois produz artefatos executaveis em memoria;
|
||||
3. por fim escreve `program.pbx` em disco.
|
||||
|
||||
O problema nao e falta de separacao conceitual.
|
||||
O problema e que essa separacao ainda nao virou API normativa nem entrypoints distintos.
|
||||
|
||||
Para o editor e o LSP, isso importa muito:
|
||||
|
||||
- `analyze` precisa ser barato em side effects e orientado a snapshot;
|
||||
- `compile` precisa produzir um resultado coerente em memoria sem obrigar write de artefato;
|
||||
- `build` precisa continuar sendo o fluxo que materializa `program.pbx`.
|
||||
|
||||
Ao mesmo tempo, esta agenda nao deve misturar dois assuntos:
|
||||
|
||||
- como o compiler le fontes;
|
||||
- e como ele expõe seus perfis de execucao.
|
||||
|
||||
O primeiro assunto fica travado: `SourceProviderFactory` continua sendo o boundary.
|
||||
O segundo e o alvo desta discussion: desacoplar a intencao operacional do pipeline.
|
||||
|
||||
Tambem precisamos manter a classificacao correta do problema:
|
||||
|
||||
- PBS nao e o owner desta decisao; ele e um frontend consumidor importante;
|
||||
- o split precisa servir ao compiler como plataforma multi-frontend;
|
||||
- isso significa que a nova API de `analyze`/`compile`/`build` deve preservar o comportamento correto que o caminho atual ja entrega para PBS, sem acoplar o contrato a detalhes exclusivos desse frontend.
|
||||
|
||||
Tambem fica fechado que LSP/editor nao introduzem "outro pipeline" no dominio `compiler`.
|
||||
O que muda sao as chamadas e os contextos de execucao:
|
||||
|
||||
- o pipeline canonico permanece unico;
|
||||
- `analyze`, `compile` e `build` sao entrypoints distintos sobre esse mesmo pipeline;
|
||||
- configs/contextos diferentes podem ajustar leitura, coletores, sinks e shape de retorno por caso de uso;
|
||||
- esses contextos nao devem redefinir a semantica central dos stages canonicos.
|
||||
- o comportamento default atual deixa de se chamar `run` e passa a ser o `build` construido com config/contexto de filesystem montado pelo callsite, nao pelo pipeline em si.
|
||||
|
||||
A direcao mais saudavel parece ser explicitar tres perfis canonicos:
|
||||
|
||||
1. `analyze`
|
||||
termina em `FrontendPhasePipelineStage`, isto e, resolve deps, carrega fontes, roda frontend e produz `AnalysisSnapshot` com diagnosticos e facts semanticos sem executar lowering, emissao ou write de artefato.
|
||||
2. `compile`
|
||||
termina em `VerifyBytecodePipelineStage`, isto e, reaproveita o mesmo eixo semantico de `analyze`, avanca por lowering, otimizacao, emissao, link precheck e verificacao preload, e produz resultado executavel validado em memoria sem escrever arquivo.
|
||||
3. `build`
|
||||
termina em `WriteBytecodeArtifactPipelineStage`, isto e, e definido como `compile` seguido apenas da etapa terminal de materializacao do artefato em disco.
|
||||
|
||||
Isso preserva um unico eixo semantico e reduz o risco de o Studio ou o LSP precisarem inventar um "mini-compiler" paralelo.
|
||||
|
||||
Em termos de superficie de servico, o caminho recomendado elimina `run` como entrypoint normativo.
|
||||
O servico deve passar a expor entrypoints explicitos, por exemplo:
|
||||
|
||||
- `analyze(config, logs)` ou equivalente;
|
||||
- `compile(config, logs)` ou equivalente;
|
||||
- `build(config, logs)` ou equivalente.
|
||||
|
||||
Cada chamada pode receber config/contexto apropriado ao caso de uso, mas continua percorrendo o mesmo pipeline canonico ate o stage terminal definido para aquele entrypoint.
|
||||
O comportamento que hoje existe em `run` deve ser reexpresso como `build(filesystem-config, logs)` ou equivalente, com a construcao do contexto default acontecendo fora do pipeline itself.
|
||||
|
||||
Fechamentos recomendados para a decisao:
|
||||
|
||||
1. `analyze` termina em `FrontendPhasePipelineStage` e nao inclui lowering/backend execution artifacts.
|
||||
2. `compile` termina em `VerifyBytecodePipelineStage` e vai ate `bytecodeModule` e `bytecodeBytes` em memoria.
|
||||
3. `compile` inclui `LinkBytecode` e `VerifyBytecode` para que o resultado em memoria ja seja semanticamente confiavel.
|
||||
4. `build` termina em `WriteBytecodeArtifactPipelineStage`; ele nao recompila por outro caminho e apenas reaproveita `compile` com a persistencia terminal.
|
||||
5. a API publica deve expor snapshots/resultados estaveis por perfil, sem vazar `BuilderPipelineContext` como contrato externo.
|
||||
6. o CLI e os callsites existentes continuam apontando para `build` como comportamento default.
|
||||
7. a decisao deve preservar compatibilidade comportamental com o `compile` atual usado por PBS, tratando esse fluxo como baseline de corretude e nao como detalhe descartavel de um frontend especifico.
|
||||
8. a superficie nova deve permanecer frontend-agnostica, para que futuros FEs possam reutilizar o mesmo contrato sem herdar semantica acidental de PBS.
|
||||
9. `BuilderPipelineService` nao deve manter `run` como entrypoint publico; ele deve expor `analyze`, `compile` e `build` sobre o mesmo pipeline compartilhado.
|
||||
10. o comportamento atual de `run` deve ser absorvido por `build` com config/contexto de filesystem construido fora do pipeline em si.
|
||||
11. configs/contextos distintos por entrypoint sao permitidos para suportar CLI, editor e LSP, desde que nao alterem a semantica central dos stages canonicos.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recommended direction: seguir com **Option B**.
|
||||
|
||||
A agenda deve convergir para uma decisao com os seguintes fechamentos:
|
||||
|
||||
1. `SourceProviderFactory` permanece como boundary de leitura do compiler;
|
||||
2. o compiler deve expor tres entrypoints normativos: `analyze`, `compile` e `build`;
|
||||
3. `build` nao e mais sinonimo de "todo uso do compiler", mas apenas o perfil que materializa artefato;
|
||||
4. `analyze` deve ser definido como o perfil que termina em `FrontendPhasePipelineStage`, isto e, `ResolveDeps + LoadSources + FrontendPhase`, retornando `AnalysisSnapshot` estavel e sem write side effects;
|
||||
5. `compile` deve ser definido como o perfil que termina em `VerifyBytecodePipelineStage`, isto e, `analyze + LowerToIRVM + OptimizeIRVM + EmitBytecode + LinkBytecode + VerifyBytecode`, retornando resultado validado em memoria;
|
||||
6. `build` deve ser definido como o perfil que termina em `WriteBytecodeArtifactPipelineStage`, isto e, `compile + WriteBytecodeArtifact`, sem reorder semantico ou gates adicionais fora da persistencia terminal;
|
||||
7. a API publica deve retornar resultados estaveis por perfil em vez de expor o `BuilderPipelineContext` diretamente;
|
||||
8. o CLI/build atual deve continuar como comportamento default para compatibilidade;
|
||||
9. a decisao deve preservar compatibilidade comportamental com o `compile` atual de PBS como baseline de corretude, sem transformar PBS em detalhe normativo do contrato publico;
|
||||
10. a superficie `analyze`/`compile`/`build` deve permanecer frontend-agnostica para acomodar multiplos FEs no dominio `compiler`;
|
||||
11. `BuilderPipelineService` deve remover `run` como entrypoint publico e expor `analyze`, `compile` e `build`, cada um com config/contexto apropriado ao seu caso de uso;
|
||||
12. o comportamento default de hoje deve ser preservado como `build` com config/contexto de filesystem, construido fora do pipeline itself;
|
||||
13. configs/contextos diferentes por entrypoint sao parte do modelo, mas nao podem redefinir a semantica central dos stages canonicos;
|
||||
14. a propagacao deve atingir a spec operacional do pipeline, os contratos de CLI/callsites e a documentacao dos resultados intermediarios, preservando a spec de PBX como authority de emissao.
|
||||
|
||||
Next step suggestion: converter esta agenda em uma `decision` que feche o stage boundary de cada perfil, o contrato dos resultados intermediarios e a compatibilidade do CLI/build atual com o novo modelo.
|
||||
Reference in New Issue
Block a user