prometeu-studio/docs/compiler/pbs/pull-requests/PR-10.3-pbs-parser-top-level-declaration-decomposition.md

PR-10.3 - PBS Parser Top-Level Declaration Decomposition

Briefing

O maior concentrador de branching restante em PbsParser e a montagem de topo de arquivo e o dispatch de declare ....

Esta PR extrai o parsing de declaracoes top-level e de corpos declarativos para colaboradores especificos, mantendo a mesma gramatica e o mesmo comportamento observavel.

Motivation

Dor atual que esta PR resolve

1. parseFile e parseDeclareTopDecl acumulam roteamento de muitas formas de declaracao.
2. Declaracoes como host, builtin type, struct, contract, service, enum e implements convivem no mesmo arquivo e elevam acoplamento.
3. Essa parte do parser muda com frequencia e hoje tem custo alto de manutencao.

Target

Separar a camada de declaracoes top-level:

1. parsing de imports,
2. dispatch de declare,
3. parsing de corpos declarativos,
4. roteamento por ParseMode.

Dependencies

Prerequisitos diretos:

1. PR-10.1
2. PR-10.2

Scope

1. Extrair parseFile em conjunto com o dispatch de topo para um colaborador dedicado.
2. Extrair parseDeclareTopDecl e parsers correlatos (host, builtin type, struct, contract, service, error, enum, callback, const, implements).
3. Preservar o comportamento atual de atributos permitidos/proibidos por tipo de declaracao.

Non-Goals

1. Nao alterar a ordem de imports/declarations no AST.
2. Nao alterar as regras de INTERFACE_MODULE.
3. Nao reescrever PbsExprParser.

Method

O que deve ser feito explicitamente

1. Criar um PbsTopLevelParser e um PbsDeclarationParser, ou divisao equivalente.
2. Manter em PbsParser apenas a montagem final da fachada e o fio de chamada principal.
3. Extrair por familias coesas de declaracao, evitando uma nova classe monolitica.
4. Preservar sincronia/recovery de topo no mesmo fluxo observavel.

Acceptance Criteria

1. parseFile e parseDeclareTopDecl deixam de concentrar o dispatch completo de todas as declaracoes.
2. O parse de topo continua deterministico e equivalente ao estado anterior.
3. Testes de parser e frontend continuam verdes sem necessidade de atualizar fixtures por mudanca funcional.

Tests

1. :prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*
2. :prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsBarrelParserTest*
3. :prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsInterfaceModuleSemanticsTest*
4. :prometeu-compiler:frontends:prometeu-frontend-pbs:test

Affected Documents

1. Nenhum documento normativo.

Open Questions

1. implements deve ficar junto de declaracoes top-level gerais ou em um parser especializado de contract/service surfaces? A recomendacao e mantê-lo no parser top-level por depender fortemente do roteamento de arquivo.