prometeu-studio/docs/compiler/pbs/pull-requests/PR-10.1-pbs-parser-shared-context-and-safe-delegation.md

PR-10.1 - PBS Parser Shared Context and Safe Delegation

Briefing

PbsParser concentra estado compartilhado (cursor, diagnostics, fileId, parseMode, loopDepth) e responsabilidades de parsing em uma unica classe.

Esta PR introduz uma fundacao estrutural para decomposicao, sem alterar comportamento: um contexto compartilhado e pontos de delegacao seguros, mantendo PbsParser como fachada publica.

Motivation

Dor atual que esta PR resolve

1. Extracoes futuras dependem de copiar estado ou expor detalhes internos do parser.
2. O acoplamento entre navegação, diagnostico e parse impede quebrar a classe sem risco alto.
3. A refatoracao fica mais segura se a infraestrutura de compartilhamento vier antes da movimentacao de logica.

Target

Estabelecer a base de refactor sem mudar funcionalidade:

1. Introduzir um contexto compartilhado para parser.
2. Encapsular helpers comuns de span/report/consume no contexto ou utilitarios proximos.
3. Permitir delegacao gradual para subparsers mantendo PbsParser.parse(...) como API unica.

Dependencies

Nenhuma.

Scope

1. Criar ParserContext ou equivalente com acesso a cursor, diagnostics, fileId, parseMode e loopDepth.
2. Mover helpers estruturais triviais para o contexto onde isso nao altere semantica.
3. Adaptar PbsExprParser bootstrap para consumir o mesmo contexto, ou uma visao compatível, sem mudar seu comportamento.

Non-Goals

1. Nao alterar gramatica PBS.
2. Nao mover ainda parsing de tipos, atributos, blocos ou declaracoes para classes separadas.
3. Nao alterar mensagens, codigos de erro ou spans.

Method

O que deve ser feito explicitamente

1. Introduzir um objeto de contexto pequeno e explicito.
2. Manter PbsParser como orquestrador/fachada durante toda a PR.
3. Preservar o contrato de parse(...) e a ordem de consumo de tokens.
4. Validar que a nova camada e puramente estrutural.

Acceptance Criteria

1. PbsParser continua sendo o unico entrypoint publico de parse.
2. Nenhum teste de parser, semantica ou frontend muda comportamento esperado.
3. Nao ha alteracao observavel em AST, spans ou diagnosticos.
4. A PR reduz acoplamento e prepara extracoes futuras sem mover regras complexas ainda.

Tests

1. :prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*
2. :prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*
3. :prometeu-compiler:frontends:prometeu-frontend-pbs:test

Affected Documents

1. Nenhum documento normativo.

Open Questions

1. O loopDepth deve viver no contexto mutavel compartilhado ou em um helper especializado de block parsing? Esta PR pode manter no contexto; a decisao final pode vir na PR-10.4.