From 14eddbcbae6fcf5ae12c2edfcb25962d66cad9e5 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Thu, 5 Mar 2026 08:07:36 +0000 Subject: [PATCH] added PRs specs --- docs/pbs/pull-requests/INDEX.md | 17 +++++++++ .../PR-001-pbs-lexer-core-syntax-alignment.md | 38 +++++++++++++++++++ .../PR-002-pbs-ast-contract-v1.md | 35 +++++++++++++++++ ...R-003-pbs-parser-declarations-and-types.md | 35 +++++++++++++++++ ...-pbs-parser-statements-and-control-flow.md | 35 +++++++++++++++++ ...arser-expressions-optional-result-apply.md | 36 ++++++++++++++++++ ...PR-006-pbs-barrel-and-module-visibility.md | 35 +++++++++++++++++ ...static-semantics-declaration-validation.md | 35 +++++++++++++++++ ...atic-semantics-call-resolution-and-flow.md | 33 ++++++++++++++++ .../PR-009-pbs-diagnostics-contract-v1.md | 36 ++++++++++++++++++ .../PR-010-pbs-irbackend-lowering-contract.md | 35 +++++++++++++++++ .../PR-011-pbs-gate-u-conformance-fixtures.md | 35 +++++++++++++++++ 12 files changed, 405 insertions(+) create mode 100644 docs/pbs/pull-requests/INDEX.md create mode 100644 docs/pbs/pull-requests/PR-001-pbs-lexer-core-syntax-alignment.md create mode 100644 docs/pbs/pull-requests/PR-002-pbs-ast-contract-v1.md create mode 100644 docs/pbs/pull-requests/PR-003-pbs-parser-declarations-and-types.md create mode 100644 docs/pbs/pull-requests/PR-004-pbs-parser-statements-and-control-flow.md create mode 100644 docs/pbs/pull-requests/PR-005-pbs-parser-expressions-optional-result-apply.md create mode 100644 docs/pbs/pull-requests/PR-006-pbs-barrel-and-module-visibility.md create mode 100644 docs/pbs/pull-requests/PR-007-pbs-static-semantics-declaration-validation.md create mode 100644 docs/pbs/pull-requests/PR-008-pbs-static-semantics-call-resolution-and-flow.md create mode 100644 docs/pbs/pull-requests/PR-009-pbs-diagnostics-contract-v1.md create mode 100644 docs/pbs/pull-requests/PR-010-pbs-irbackend-lowering-contract.md create mode 100644 docs/pbs/pull-requests/PR-011-pbs-gate-u-conformance-fixtures.md diff --git a/docs/pbs/pull-requests/INDEX.md b/docs/pbs/pull-requests/INDEX.md new file mode 100644 index 00000000..ad614289 --- /dev/null +++ b/docs/pbs/pull-requests/INDEX.md @@ -0,0 +1,17 @@ +# PBS Frontend PR Sequence + +Este indice organiza uma sequencia de PRs atomicas para levar `frontends/pbs` ao contrato das specs. + +1. `PR-001-pbs-lexer-core-syntax-alignment.md` +2. `PR-002-pbs-ast-contract-v1.md` +3. `PR-003-pbs-parser-declarations-and-types.md` +4. `PR-004-pbs-parser-statements-and-control-flow.md` +5. `PR-005-pbs-parser-expressions-optional-result-apply.md` +6. `PR-006-pbs-barrel-and-module-visibility.md` +7. `PR-007-pbs-static-semantics-declaration-validation.md` +8. `PR-008-pbs-static-semantics-call-resolution-and-flow.md` +9. `PR-009-pbs-diagnostics-contract-v1.md` +10. `PR-010-pbs-irbackend-lowering-contract.md` +11. `PR-011-pbs-gate-u-conformance-fixtures.md` + +Cada documento e auto contido e inclui: `Briefing`, `Target`, `Method`, `Acceptance Criteria` e `Tests`. diff --git a/docs/pbs/pull-requests/PR-001-pbs-lexer-core-syntax-alignment.md b/docs/pbs/pull-requests/PR-001-pbs-lexer-core-syntax-alignment.md new file mode 100644 index 00000000..3dcff558 --- /dev/null +++ b/docs/pbs/pull-requests/PR-001-pbs-lexer-core-syntax-alignment.md @@ -0,0 +1,38 @@ +# PR-001 - PBS Lexer Core Syntax Alignment + +## Briefing +O lexer atual cobre apenas uma parte pequena da superficie definida em `3. Core Syntax Specification.md`. +Este PR fecha o contrato lexico minimo de v1 para que parser, semantica e diagnosticos trabalhem sobre um conjunto estavel de tokens. + +## Target +- Specs: + - `docs/pbs/specs/3. Core Syntax Specification.md` (secoes 4.1, 4.2, 4.4, 4.5, 10) + - `docs/pbs/specs/11. AST Specification.md` (secao 7: atribuicao estavel) +- Codigo: + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsTokenKind.java` + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsLexer.java` + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/LexErrors.java` + +## Method +1. Expandir `PbsTokenKind` para todos os keywords ativos de v1 e operadores/pontuacao usados na gramatica. +2. Adicionar tokens para `COMMENT` e para operadores compostos ausentes (`->`, `+=`, `-=`, `*=`, `/=`, `%=`). +3. Suportar aliases lexicos (`and/or/not`) sem quebrar `&&/||/!`. +4. Preservar spans estaveis em todos os tokens emitidos. +5. Manter rejeicao deterministica para caracteres invalidos e strings nao terminadas. + +## Acceptance Criteria +- Lexer emite classes obrigatorias: `identifiers`, `keywords`, `literals`, `punctuation`, `operators`, `comments`, `EOF`. +- Keywords reservados nao entram como `IDENTIFIER`. +- `and/or/not` e `&&/||/!` sao tokenizados de forma consistente. +- `->` nao e decomposto em dois tokens (`-` e `>`). +- Comentarios de linha sao representados como token e nao perdem a continuidade do stream. +- Todos os tokens carregam `start/end` corretos no arquivo. + +## Tests +- `PbsLexerTest`: + - caso feliz com arquivo contendo imports, declaracoes, controle de fluxo e operadores compostos; + - caso de comentarios em multiplas linhas; + - caso de palavras reservadas vs identificadores parecidos; + - caso de string nao terminada (`E_LEX_UNTERMINATED_STRING`); + - caso de caractere invalido (`E_LEX_INVALID_CHAR`). +- Fixtures de regressao para `->`, `and/or/not` e atribuicoes compostas. diff --git a/docs/pbs/pull-requests/PR-002-pbs-ast-contract-v1.md b/docs/pbs/pull-requests/PR-002-pbs-ast-contract-v1.md new file mode 100644 index 00000000..a0b82970 --- /dev/null +++ b/docs/pbs/pull-requests/PR-002-pbs-ast-contract-v1.md @@ -0,0 +1,35 @@ +# PR-002 - PBS AST Contract V1 + +## Briefing +Hoje o AST representa apenas funcoes, `let/return` e expressoes basicas. +A spec exige familias obrigatorias de declaracoes e metadados estaveis para parser, diagnosticos e lowering. +Este PR fecha o contrato estrutural do AST sem ainda resolver todas as regras semanticas. + +## Target +- Specs: + - `docs/pbs/specs/11. AST Specification.md` (secoes 6, 7, 8, 9, 10) + - `docs/pbs/specs/3. Core Syntax Specification.md` (secoes 6, 7, 8, 9, 10) +- Codigo: + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java` + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsParser.java` + +## Method +1. Remodelar o root para conter imports e uma lista de `TopDecl` em ordem de fonte. +2. Introduzir familias obrigatorias de declaracao (`fn`, `struct`, `contract`, `service`, `error`, `enum`, `callback`, `declare const`, `implements`). +3. Adicionar estruturas de tipo (unit, simple, optional, tuple nomeada, `Self`) e retorno (`plain`, `result`). +4. Garantir `file/start/end` em todos os nos consumidos por diagnostico/lowering. +5. Definir nos de erro/recovery explicitos para evitar AST permissivo. + +## Acceptance Criteria +- Existe exatamente um root por arquivo com filhos em ordem deterministica. +- AST preserva identidade de declaracoes sem colapsar overload cedo. +- Cada declaracao obrigatoria possui nome, assinatura/superficie e span. +- Parser recovery nao fabrica semantica valida; erros ficam marcados no AST. +- Precedencia e associatividade continuam observaveis pelo shape da arvore. + +## Tests +- `PbsParserTest`: + - validacao de shape do root (`imports + topDecls`); + - cobertura de todas as familias de declaracao obrigatorias no AST; + - asserts de spans (`file/start/end`) em nos principais; + - fixture com erro e recovery garantindo estrutura coerente. diff --git a/docs/pbs/pull-requests/PR-003-pbs-parser-declarations-and-types.md b/docs/pbs/pull-requests/PR-003-pbs-parser-declarations-and-types.md new file mode 100644 index 00000000..6f172d02 --- /dev/null +++ b/docs/pbs/pull-requests/PR-003-pbs-parser-declarations-and-types.md @@ -0,0 +1,35 @@ +# PR-003 - PBS Parser Declarations and Type Surfaces + +## Briefing +A sintaxe de declaracoes e tipos da spec e significativamente maior que o parser atual. +Este PR implementa a fatia de parser para declaracoes top-level e superficies de tipo/retorno, mantendo rejeicao deterministica das formas reservadas fora do contexto permitido. + +## Target +- Specs: + - `docs/pbs/specs/3. Core Syntax Specification.md` (secoes 6.2, 7.1-7.6, 8) + - `docs/pbs/specs/11. AST Specification.md` (secao 8) +- Codigo: + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsParser.java` + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/ParseErrors.java` + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java` + +## Method +1. Implementar parser de `declare struct/service/contract/error/enum/callback/const` e `implements`. +2. Trocar assinatura de funcao para retorno via `->` com normalizacao de unit e single-slot. +3. Implementar parser de `TypeRef` com `optional`, tuple nomeada e `Self`. +4. Rejeitar no parser formas reservadas de `declare host` e `declare builtin type` em modulos ordinarios. +5. Melhorar sincronizacao de recovery por contexto de declaracao. + +## Acceptance Criteria +- Top-level parseia todas as declaracoes previstas em `TopDecl`. +- Retornos seguem formato normativo (`->`, `result`, `void`/`()`). +- `optional` e tuple nomeada em tipo sao parseados com shape correto. +- Formas invalidas de declaracao geram erro deterministico e parser continua. +- `declare host`/`declare builtin type` em codigo comum sao rejeitados explicitamente. + +## Tests +- `PbsParserDeclarationsTest` novo cobrindo: + - cada declaracao valida (struct, service, contract, error, enum, callback, const, implements); + - erros de shape (enum misto implicito/explicito, retorno mal formado, optional invalido); + - rejeicao de `declare host` fora de superficie reservada; + - spans e recovery em declaracoes quebradas. diff --git a/docs/pbs/pull-requests/PR-004-pbs-parser-statements-and-control-flow.md b/docs/pbs/pull-requests/PR-004-pbs-parser-statements-and-control-flow.md new file mode 100644 index 00000000..630a2a07 --- /dev/null +++ b/docs/pbs/pull-requests/PR-004-pbs-parser-statements-and-control-flow.md @@ -0,0 +1,35 @@ +# PR-004 - PBS Parser Statements and Control Flow + +## Briefing +O parser atual cobre apenas `let`, `return` e expression statement. +Este PR implementa o bloco de statements exigido pela spec para viabilizar semantica de fluxo e validacoes posteriores. + +## Target +- Specs: + - `docs/pbs/specs/3. Core Syntax Specification.md` (secao 9) + - `docs/pbs/specs/11. AST Specification.md` (secao 9) +- Codigo: + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsParser.java` + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java` + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/ParseErrors.java` + +## Method +1. Adicionar parser para `assign`, `if`, `for`, `while`, `break`, `continue`. +2. Introduzir `let const` e modelagem de `LValue` (sem call chain em alvo de atribuicao). +3. Implementar validacao sintatica de forma de `for` (`from/until/step`). +4. Marcar uso invalido de `break/continue` fora de loop como erro deterministico. +5. Preservar recovery por fronteira de statement (`;` e fechamento de bloco). + +## Acceptance Criteria +- AST de bloco representa todas as formas de `Stmt` da secao 9. +- Atribuicao e statement, nao expressao. +- `break/continue` fora de loop emite diagnostico estavel. +- `for` e `while` parseiam com estrutura e spans corretos. +- Targets de atribuicao invalidos sao rejeitados no parser. + +## Tests +- `PbsParserStatementsTest` novo cobrindo: + - `let`, `let const`, `assign` simples e composta; + - `if/else`, `for` com e sem `step`, `while`; + - `break/continue` valido e invalido; + - recovery apos statements malformados. diff --git a/docs/pbs/pull-requests/PR-005-pbs-parser-expressions-optional-result-apply.md b/docs/pbs/pull-requests/PR-005-pbs-parser-expressions-optional-result-apply.md new file mode 100644 index 00000000..c54c8751 --- /dev/null +++ b/docs/pbs/pull-requests/PR-005-pbs-parser-expressions-optional-result-apply.md @@ -0,0 +1,36 @@ +# PR-005 - PBS Parser Expressions, Optional/Result, and Apply + +## Briefing +A gramatica de expressoes da spec inclui formas que ainda nao existem no frontend (`apply`, `else`, `switch`, `handle`, `new`, `bind`, `some/none/ok/err`, member/postfix avancado). +Este PR fecha a cobertura sintatica dessas expressoes e preserva as regras de precedencia/rejeicao. + +## Target +- Specs: + - `docs/pbs/specs/3. Core Syntax Specification.md` (secao 10, 13, 14) + - `docs/pbs/specs/11. AST Specification.md` (secoes 9, 10) +- Codigo: + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsExprParser.java` + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java` + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/ParseErrors.java` + +## Method +1. Implementar cadeia de precedencia completa incluindo `apply` right-associative. +2. Implementar `else` extraction, `if` expression, `switch`, `handle` e `as`. +3. Implementar postfixes: member access, call sugar, propagate `!`. +4. Suportar primarias: `this`, `new`, `bind`, `some`, `none`, `ok`, `err`, unit e tuple expr. +5. Rejeitar cadeias nao associativas e formas proibidas (`?` propagation, single-slot tuple literal). + +## Acceptance Criteria +- Parser respeita precedencia/associatividade normativa (incluindo `apply` e `else`). +- `a < b < c` e `a == b == c` continuam rejeitados deterministicamente. +- `if` expression exige `else` e bloco nos ramos. +- `switch` e `handle` parseiam mapa de arms e wildcard conforme a gramatica. +- Superficies `optional/result` sao parseadas sem inferir semantica indevida. + +## Tests +- `PbsExprParserTest` ampliado com: + - precedencia completa e associatividade; + - expressoes `apply` encadeadas; + - `switch`/`handle` validos e invalidos; + - `some/none/ok/err/bind/new`; + - cenarios negativos obrigatorios da secao 12 de syntax. diff --git a/docs/pbs/pull-requests/PR-006-pbs-barrel-and-module-visibility.md b/docs/pbs/pull-requests/PR-006-pbs-barrel-and-module-visibility.md new file mode 100644 index 00000000..00e79a80 --- /dev/null +++ b/docs/pbs/pull-requests/PR-006-pbs-barrel-and-module-visibility.md @@ -0,0 +1,35 @@ +# PR-006 - PBS Barrel and Module Visibility + +## Briefing +A spec define `mod.barrel` como fonte unica de visibilidade, mas o frontend atual ignora `.barrel`. +Este PR implementa parser/validacao de barrel e aplica regras minimas de visibilidade/exportacao em nivel de modulo. + +## Target +- Specs: + - `docs/pbs/specs/3. Core Syntax Specification.md` (secoes 5.1, 5.2, 5.3, 6.1) + - `docs/pbs/specs/12. Diagnostics Specification.md` (fases syntax/linking) +- Codigo: + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PBSFrontendPhaseService.java` + - novo parser/modelo para `mod.barrel` em `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/`. + +## Method +1. Adicionar parser dedicado para `mod.barrel` com itens e assinaturas de funcao. +2. Detectar `missing mod.barrel` por modulo e duplicatas no barrel. +3. Validar resolucao barrel -> declaracoes top-level da AST do modulo. +4. Garantir que `pub/mod` em `.pbs` continue proibido fora dos contextos permitidos. +5. Emitir diagnosticos com atribuicao primaria no arquivo/barrel que causou a falha. + +## Acceptance Criteria +- Compilacao de modulo sem `mod.barrel` falha deterministicamente. +- Duplicatas em barrel sao detectadas por regra correta (funcao por assinatura; outros por kind+nome). +- Cada item de barrel resolve para declaracao existente de modulo. +- Itens de barrel invalidos geram erro sem quebrar analise dos demais itens. +- Importacao cross-module usa somente simbolos `pub`. + +## Tests +- `PbsBarrelParserTest` novo para shape do barrel. +- `PbsModuleVisibilityTest` novo cobrindo: + - modulo sem barrel; + - duplicatas de simbolo/assinatura; + - entry nao resolvido; + - import de simbolo nao `pub`. diff --git a/docs/pbs/pull-requests/PR-007-pbs-static-semantics-declaration-validation.md b/docs/pbs/pull-requests/PR-007-pbs-static-semantics-declaration-validation.md new file mode 100644 index 00000000..8b7e9aca --- /dev/null +++ b/docs/pbs/pull-requests/PR-007-pbs-static-semantics-declaration-validation.md @@ -0,0 +1,35 @@ +# PR-007 - PBS Static Semantics Declaration Validation + +## Briefing +Depois da cobertura sintatica, falta a camada de semantica estatica para validar declaracoes, namespaces e invariantes de assinatura. +Este PR entrega a primeira fase semantica: sem resolver `apply` completo ainda. + +## Target +- Specs: + - `docs/pbs/specs/4. Static Semantics Specification.md` (secoes 2, 3.1-3.7, 3.18 subset de declaracao) + - `docs/pbs/specs/12. Diagnostics Specification.md` (phase = static semantics) +- Codigo: + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsFrontendCompiler.java` + - novo pacote de validadores semanticos em `.../pbs/semantics/`. + +## Method +1. Introduzir binder de simbolos por namespace (`type`, `value`, `callable`, `host-owner`). +2. Validar duplicatas de parametros, labels de retorno, enum/error cases e declaracoes. +3. Validar invariantes de retorno (`optional` vs `result`, `optional void`, etc.). +4. Validar superficies de declaracao (`ctor`, `service`, `callback`, `const`) conforme regras de forma. +5. Emitir diagnosticos deterministas por codigo estavel para cada classe de erro. + +## Acceptance Criteria +- Binder constroi tabelas por namespace sem colapsar overload cedo. +- Erros obrigatorios de declaracao aparecem com spans corretos e codigo estavel. +- Duplicata de funcao usa identidade por shape (nao por label). +- Regras de validade de `declare const` (tipo obrigatorio, init quando aplicavel) sao aplicadas. +- Nenhum arquivo valido passa a falhar por ruido de validacao. + +## Tests +- `PbsSemanticsDeclarationsTest` novo com casos positivos/negativos para: + - duplicatas por namespace; + - enum/error duplicados; + - retorno invalido (`optional/result`); + - declaracoes `const` invalidas; + - callback/service/ctor shape invalidos. diff --git a/docs/pbs/pull-requests/PR-008-pbs-static-semantics-call-resolution-and-flow.md b/docs/pbs/pull-requests/PR-008-pbs-static-semantics-call-resolution-and-flow.md new file mode 100644 index 00000000..223fe165 --- /dev/null +++ b/docs/pbs/pull-requests/PR-008-pbs-static-semantics-call-resolution-and-flow.md @@ -0,0 +1,33 @@ +# PR-008 - PBS Static Semantics Call Resolution and Flow + +## Briefing +A parte mais critica de semantica de execucao em compile-time ainda falta: resolucao de `apply`, overloading, member projection e fluxo de `optional/result`. +Este PR entrega essa segunda fase semantica com foco em determinismo. + +## Target +- Specs: + - `docs/pbs/specs/4. Static Semantics Specification.md` (secoes 3.8-3.17 e 3.18 subset de uso) + - `docs/pbs/specs/9. Dynamic Semantics Specification.md` (baseline de comportamento observavel) +- Codigo: + - validadores/resolvers em `.../pbs/semantics/` + - integracao em `PbsFrontendCompiler`. + +## Method +1. Implementar resolucao de callable para `apply` e call sugar. +2. Implementar regras de sobrecarga (unresolved/ambiguous) e tie-break por contexto esperado. +3. Validar member access/projection (`struct`, `service`, `tuple`, enum path) e proibir bare method extraction. +4. Validar fluxo de controle (`if/switch`, exaustividade, tipos de branch) e loops (`break/continue` contexto). +5. Validar regras de `optional`/`result`: `none` contextual, `else`, `!`, `handle`. + +## Acceptance Criteria +- `apply` em alvo nao chamavel gera erro deterministico. +- Casos `unresolved` e `ambiguous` de overload sao diferenciados. +- `switch` em contexto de valor exige exaustividade. +- `!` e `handle` respeitam tipo de erro do retorno `result` do escopo. +- Projecao invalida (`slot/label/method`) gera diagnostico com span do uso. + +## Tests +- `PbsSemanticsApplyResolutionTest` novo. +- `PbsSemanticsControlFlowTest` novo. +- `PbsSemanticsOptionalResultTest` novo. +- Fixtures de regressao para ambiguidades e mismatch de tipo. diff --git a/docs/pbs/pull-requests/PR-009-pbs-diagnostics-contract-v1.md b/docs/pbs/pull-requests/PR-009-pbs-diagnostics-contract-v1.md new file mode 100644 index 00000000..3ab3a7b2 --- /dev/null +++ b/docs/pbs/pull-requests/PR-009-pbs-diagnostics-contract-v1.md @@ -0,0 +1,36 @@ +# PR-009 - PBS Diagnostics Contract V1 + +## Briefing +O modelo atual de `Diagnostic` nao contem fase, template id nem placeholders estaveis, o que impede conformidade com o contrato de diagnosticos da spec. +Este PR eleva o contrato de diagnosticos para v1 sem acoplar a UI. + +## Target +- Specs: + - `docs/pbs/specs/12. Diagnostics Specification.md` (secoes 6, 7, 8, 9, 10) + - `docs/pbs/specs/13. Lowering IRBackend Specification.md` (secao 7) +- Codigo: + - `prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/source/diagnostics/Diagnostic.java` + - `prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/source/diagnostics/DiagnosticSink.java` + - emissores de diagnostico no frontend PBS. + +## Method +1. Estender `Diagnostic` com `phase`, `templateId` e `placeholders` nomeados. +2. Definir taxonomia minima de fases externas: `syntax`, `static-semantics`, `manifest-import-resolution`, `linking`, `host-admission`, `load-facing-rejection`. +3. Preservar `code`, `severity`, `span` e `related spans` como identidade estavel. +4. Introduzir helpers para emissao padronizada por fase/template. +5. Mapear erros atuais de lexer/parser/frontend para o novo contrato. + +## Acceptance Criteria +- Todo diagnostico PBS emitido tem `code`, `severity`, `phase`, `templateId`, `primary span` e mensagem renderizada. +- Duplicatas/conflitos incluem ao menos um `related span` quando aplicavel. +- Identidade de diagnostico independe do texto localizado. +- Nenhuma fase obrigatoria e colapsada de forma opaca para o usuario. +- Chamadas legadas continuam compilando com caminho de migracao claro. + +## Tests +- `DiagnosticSinkTest` e novos testes de contrato para: + - presenca obrigatoria de campos; + - estabilidade de `templateId/placeholders`; + - caso com `related span`; + - serializacao/`toString` com fase e codigo. +- Testes de integracao no frontend PBS garantindo fase correta por erro. diff --git a/docs/pbs/pull-requests/PR-010-pbs-irbackend-lowering-contract.md b/docs/pbs/pull-requests/PR-010-pbs-irbackend-lowering-contract.md new file mode 100644 index 00000000..73abd5d0 --- /dev/null +++ b/docs/pbs/pull-requests/PR-010-pbs-irbackend-lowering-contract.md @@ -0,0 +1,35 @@ +# PR-010 - PBS IRBackend Lowering Contract Alignment + +## Briefing +O lowering atual reduz tudo a `IRFunction(name, arity, hasReturnType)` e perde informacao exigida pela spec de lowering. +Este PR alinha o frontend boundary para preservar identidade, superficie de retorno e atribuicao de origem. + +## Target +- Specs: + - `docs/pbs/specs/13. Lowering IRBackend Specification.md` (secoes 5, 6, 7, 8) + - `docs/pbs/specs/11. AST Specification.md` (metadados obrigatorios) +- Codigo: + - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsFrontendCompiler.java` + - `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRFunction.java` + - `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackend*.java` + +## Method +1. Expandir modelos de IR para preservar categoria de callable e superficie de retorno. +2. Propagar atribuicao de origem estavel (`file + span`) de forma obrigatoria. +3. Diferenciar rejeicao de forma nao suportada vs erro interno. +4. Garantir determinismo de ordem de emissao conforme ordem de fonte. +5. Manter bridge de compatibilidade para consumidores atuais de IR. + +## Acceptance Criteria +- IRBackend preserva identidade e aridade de callables sem perda de categoria. +- Retorno (unit/plain/result) e mantido no boundary de frontend. +- Diagnosticos de lowering seguem contrato estavel (code/phase/template/span). +- Formas nao suportadas nao degradam silenciosamente para comportamento valido alternativo. +- Testes existentes de lowering continuam passando com adaptacao minima. + +## Tests +- `PbsFrontendCompilerTest` ampliado para: + - preservacao de metadata no IR; + - ordem deterministica de callables; + - casos de rejeicao de lowering com diagnostico estavel. +- Novos testes para serializacao/debug de `IRBackend`. diff --git a/docs/pbs/pull-requests/PR-011-pbs-gate-u-conformance-fixtures.md b/docs/pbs/pull-requests/PR-011-pbs-gate-u-conformance-fixtures.md new file mode 100644 index 00000000..d567971b --- /dev/null +++ b/docs/pbs/pull-requests/PR-011-pbs-gate-u-conformance-fixtures.md @@ -0,0 +1,35 @@ +# PR-011 - PBS Gate U Conformance Fixtures + +## Briefing +A spec exige evidencia de conformidade (Gate U), mas o frontend ainda tem poucos testes unitarios sem fixture matrix. +Este PR cria a infraestrutura e a bateria minima de fixtures para validar lexer, parser, semantica, diagnosticos e lowering. + +## Target +- Specs: + - `docs/pbs/specs/11. AST Specification.md` (secao 12) + - `docs/pbs/specs/13. Lowering IRBackend Specification.md` (secao 8) + - `docs/general/specs/13. Conformance Test Specification.md` +- Codigo: + - novo pacote de teste/fixtures em `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/`. + +## Method +1. Introduzir harness de fixture com entrada `.pbs/.barrel` + expectativa estruturada. +2. Cobrir casos validos das familias obrigatorias de AST e fluxo de parse. +3. Cobrir casos invalidos obrigatorios (missing closer, non-assoc chains, formas fora de slice). +4. Adicionar asserts de spans e identidade de diagnostico (code/phase/template). +5. Integrar suite no gradle test da frontend PBS. + +## Acceptance Criteria +- Existe fixture matrix positiva e negativa para lexer/parser/semantica/lowering. +- Gate U cobre familias obrigatorias de declaracao, statement e expressao. +- Casos de recovery garantem AST coerente mesmo com erro. +- Conformidade e verificavel de forma reproduzivel em CI. +- Falhas mostram diff util entre esperado e obtido. + +## Tests +- `PbsConformanceFixtureTest` novo com subconjuntos: + - `valid/` para parse e lowering; + - `invalid/syntax/`; + - `invalid/static-semantics/`; + - `invalid/lowering/`. +- Execucao via `./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test`.