implements PLN-0129
JaCoCo Coverage #### Project Overview No changes detected, that affect the code coverage. * Line Coverage: 62.10% (17811/28682) * Branch Coverage: 52.81% (6878/13025) * Lines of Code: 28682 * Cyclomatic Complexity: 11494 #### Quality Gates Summary Output truncated.
Test / Build skipped: 15, passed: 654
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good

Add ArchUnit guards for Java multi-frontend boundaries in a test-only
module. Identify PBS by frontend-module origin, allow only the registry
as composition root, and lock the wording in specs 19, 20, and 22.

Housekeep DSC-0064 with LSN-0066.
This commit is contained in:
2026-09-19 03:32:43 +01:00
parent 59c0d0c3b4
commit e809ce63d3
21 changed files with 500 additions and 290 deletions
+2 -2
View File
@@ -1,6 +1,6 @@
{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":50,"PLN":129,"LSN":66,"CLSN":1}}
{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":51,"PLN":130,"LSN":67,"CLSN":1}}
{"type":"discussion","id":"DSC-0065","status":"open","ticket":"multi-frontend-avoid-premature-abstractions","title":"Evitar abstracoes prematuras na preparacao multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","multi-frontend","simplicity"],"agendas":[{"id":"AGD-0068","file":"AGD-0068-multi-frontend-avoid-premature-abstractions.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0064","status":"open","ticket":"multi-frontend-architectural-tests","title":"Testes arquiteturais para fronteiras multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","tests","multi-frontend"],"agendas":[{"id":"AGD-0067","file":"AGD-0067-multi-frontend-architectural-tests.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0064","status":"done","ticket":"multi-frontend-architectural-tests","title":"Testes arquiteturais para fronteiras multi-frontend","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","studio","frontend","architecture","tests","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0066","file":"discussion/lessons/DSC-0064-multi-frontend-architectural-tests/LSN-0066-archunit-guards-java-multi-frontend-boundaries.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
{"type":"discussion","id":"DSC-0063","status":"done","ticket":"multi-frontend-synthetic-test-frontend","title":"Frontend sintetico de teste para provar neutralidade do pipeline","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","frontend","tests","backend","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0065","file":"discussion/lessons/DSC-0063-multi-frontend-synthetic-test-frontend/LSN-0065-synthetic-test-frontend-proves-pipeline-neutrality.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
{"type":"discussion","id":"DSC-0062","status":"done","ticket":"multi-frontend-pvm-neutrality","title":"Neutralidade da PVM e identificacao PBX independente de PBS","created_at":"2026-07-15","updated_at":"2026-09-18","tags":["vm-arch","runtime","pvm","pbx","compiler","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0061","file":"discussion/lessons/DSC-0062-multi-frontend-pvm-neutrality/LSN-0061-pbx-runtime-boundary.md","status":"done","created_at":"2026-09-18","updated_at":"2026-09-18"}]}
{"type":"discussion","id":"DSC-0061","status":"done","ticket":"multi-frontend-sdk-canonical-definition","title":"Auditoria e centralizacao gradual da definicao canonica do SDK","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","sdk","stdlib","hostcalls","intrinsics","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0064","file":"discussion/lessons/DSC-0061-multi-frontend-sdk-canonical-definition/LSN-0064-runtime-owns-console-abi-pbs-is-delivery.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
@@ -0,0 +1,151 @@
---
id: LSN-0066
ticket: multi-frontend-architectural-tests
title: ArchUnit guards Java multi-frontend boundaries
created: 2026-09-19
tags: [compiler, compiler-general, studio, frontend, architecture, tests, multi-frontend]
---
# ArchUnit guards Java multi-frontend boundaries
## Original Problem
The multi-frontend boundaries already existed in specs and lessons: common
code selects a frontend by `languageId`, `IRBackend` is language-neutral,
lifecycle assembly is common, and PBS is one provider. The automated
protection did not match that model.
The old guards walked Java source and searched for substrings:
- `import p.studio.compiler.pbs`
- `new PBSFrontendPhaseService(`
- `new PbsEditorialSupportService(`
Those checks missed field, signature, and constructor coupling. They also
treated `p.studio.compiler.pbs` as the whole PBS surface. Facades such as
`PBSFrontendProvider`, `PBSDefinitions`, and `PBSFrontendPhaseService` live
in the PBS module but not in that package. `prometeu-app` and
`prometeu-lsp-v1` declared an `implementation` dependency on PBS without
importing any PBS type.
## Consolidated Decision
Java multi-frontend boundaries are enforced by **ArchUnit + JUnit 5**, not by
source substring search, except for the `__pbs.` literal scan that bytecode
cannot see.
Durable locks from DEC-0050:
- ArchUnit is test-only, pinned in `gradle/libs.versions.toml`.
- Rules live in the test-only Gradle project `:prometeu-architecture-tests`.
That project has no production sources. It is not a plugin loader.
- A PBS type is a class whose bytecode originates from
`:prometeu-compiler:frontends:prometeu-frontend-pbs`. Package
`p.studio.compiler.pbs` is not the complete boundary. Name prefixes
`PBS*` / `Pbs*` are not the identity.
- Production may depend on PBS types only in:
- the PBS module itself;
- `prometeu-frontend-registry` / `FrontendRegistryService`, and only on
`PBSFrontendProvider` and `PBSDefinitions`.
- `AppContainer` is not a PBS composition root. It may call
`FrontendRegistryService.bootstrapDefaults()`. It must not instantiate PBS
types.
- `synth` is not in the production allowlist and must not be registered in
`bootstrapDefaults()`.
- Runtime, PVM, and the Rust repository stay out of this discussion
(LSN-0061).
- `IRBackendExecutableContractTest` remains the public-contract shape audit.
ArchUnit covers module-origin dependence.
Do not migrate PBS facades into another package just to make the test
easier. Do not ban the word `PBS` in docs, fixtures, or comments.
## Final Implementation
`:prometeu-architecture-tests` imports production classes under `p.studio`
with `ImportOption.DoNotIncludeTests` and applies three ArchUnit rules:
1. classes outside the PBS module and the registry must not depend on
PBS-module types;
2. registry production may depend only on `PBSFrontendProvider` and
`PBSDefinitions` from that module;
3. frontend-api `p.studio.compiler.models` must not depend on PBS-module
types.
A separate JUnit test walks `build.gradle.kts` files and allows the PBS
project dependency only for:
- `:prometeu-compiler:prometeu-frontend-registry` as `implementation`/`api`;
- `:prometeu-architecture-tests` as `testImplementation` (needed to classify
class origin).
The `__pbs.` source scan moved to
`CommonBackendPbsPrefixScanTest` and still covers `backend/`, `lifecycle/`,
and `workspaces/stages/`.
Gradle graph cleanup:
- `prometeu-app` and `prometeu-lsp-v1` no longer `implementation` PBS.
Runtime classloading of `PBSFrontendProvider` still comes through the
registry's implementation dependency.
- `prometeu-studio` no longer `testImplementation` PBS. No studio test
compiled against PBS types.
Source-walk import/constructor tests were deleted.
`FrontendProviderBoundaryTest` keeps only
`compileOnlyFrontendProviderMayOmitLanguageService`.
Specs 19 §11 and 20 now say common/platform code must not depend on types
from the PBS frontend module. Matrix rows G19-11.6, G20-4.1.2, and G20-4.3.3
point at the ArchUnit rules and the `__pbs.` scan.
## Examples
Good:
- ArchUnit failure names the class that depends on a PBS-module type,
including a facade in package `p.studio.compiler`.
- Registry `bootstrapDefaults()` constructs `PBSFrontendProvider`. That is
the allowed composition root.
- App calls `FrontendRegistryService.bootstrapDefaults()` and has no PBS
project dependency.
Bad:
- Searching source for `import p.studio.compiler.pbs` and calling the
boundary protected.
- Treating `AppContainer` as the place that may `new PBSFrontendProvider()`.
- Identifying PBS by class name prefix, so a future `PbsLike` helper in
common code is banned or a PBS facade is missed.
- Adding ArchUnit to `java-common-conventions` for every module.
## Pitfalls
- Same Java package does not mean same Gradle module.
`FrontendRegistryService` and `PBSFrontendProvider` both sit in
`p.studio.compiler`. Origin is the module path or JAR name.
- `@AnalyzeClasses` classes must not mix `@ArchTest` and Jupiter `@Test` on
the same class. The ArchUnit engine owns `@ArchTest`.
- `DoNotIncludeTests` is required. The architecture-test sources themselves
reference PBS types in order to name the allowlist.
- Removing PBS from app/lsp compile classpath is safe only because registry
still `implementation`s PBS, which is runtime-transitive.
- `testImplementation` of PBS on studio is not a production leak, but if no
studio test needs PBS types it is still a lying graph. The allowlist test
rejects it.
- Do not point ArchUnit at the Rust runtime. `__pbs.` in Java source is a
string contract, not a type dependency.
## References
- Decision: `DEC-0050`
- Plan: `PLN-0129`
- Related lessons: `LSN-0055`, `LSN-0059`, `LSN-0062`, `LSN-0063`,
`LSN-0061`, `LSN-0065`
- `docs/specs/compiler/19. Verification and Safety Checks Specification.md`
- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
- `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`
- `prometeu-architecture-tests/src/test/java/p/studio/architecture/PbsModuleBoundaryArchTest.java`
- `prometeu-architecture-tests/src/test/java/p/studio/architecture/PbsGradleDependencyAllowlistTest.java`
- `prometeu-compiler/prometeu-frontend-registry/src/main/java/p/studio/compiler/FrontendRegistryService.java`
- `prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java`
@@ -1,79 +0,0 @@
---
id: AGD-0067
ticket: multi-frontend-architectural-tests
title: Testes arquiteturais para fronteiras multi-frontend
status: open
created: 2026-07-15
resolved:
decision:
tags: [compiler, compiler-general, studio, frontend, architecture, tests, multi-frontend]
---
# Agenda - Criar testes arquiteturais
## Objetivo
Domain owner: `compiler/general`, com impacto em `studio` e `vm-arch`.
Definir testes que protejam fronteiras: backend comum sem PBS, IR comum sem AST PBS, Studio comum sem instanciacao PBS fora do composition root e runtime neutro.
## Contexto atual
O repo ja tem testes Java para backend, bytecode e IRVM. ArchUnit pode ser util, mas o alinhamento proibe adicionar biblioteca arquitetural quando testes simples bastarem.
## Escopo
- Escolher ferramenta minima.
- Definir regras por pacote.
- Adicionar testes que sejam baratos e claros.
## Fora de escopo
- Cobrir toda arquitetura do monorepo.
- Adicionar ArchUnit sem justificativa concreta.
- Bloquear referencias PBS em testes PBS ou no frontend PBS.
## Arquivos e componentes a inspecionar
- `build.gradle.kts` e version catalog se houver.
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/...`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/...`
- `prometeu-studio/src/test/java/...`
- pacotes runtime/PVM quando presentes
## Alteracoes propostas
Opcao A: testes Java/reflection simples para imports, nomes de tipos e packages publicos.
Opcao B: ArchUnit caso a quantidade de regras e modulos justifique.
Recomendacao inicial: comecar com testes simples; reavaliar ArchUnit se as regras virarem frageis.
## Estrategia de implementacao
Definir allowlist de packages PBS, composition root e testes PBS. Escrever verificacoes independentes por dominio para falhas legiveis.
## Testes necessarios
- Backend/common nao importa `frontend.pbs`, `parser.pbs` ou `semantic.pbs`.
- IR comum nao expoe tipos PBS.
- Studio comum nao instancia servicos PBS fora da allowlist.
- Runtime nao usa nomenclatura ou semantica PBS.
## Criterios de aceitacao
- Regras rodam no build local.
- Falhas apontam arquivo/pacote responsavel.
- Excecoes autorizadas estao documentadas.
## Riscos
- Teste textual produzir falso positivo por docs ou fixtures.
- Criar barreira rigida antes de definir provider e lifecycle.
## Decisoes que devem ser registradas
- Ferramenta escolhida.
- Allowlist de packages.
- Ordem de introducao das regras.