prometeu-studio/docs/compiler/pbs/pull-requests/PR-19.2-infra-dependencygraphanaliser-extraction-and-module-cutover.md

PR-19.2 - Infra DependencyGraphAnaliser Extraction and Module Cutover

Briefing

As decisions da familia 19 fixaram que modules e globals compartilham o mesmo kernel estrutural de analise de dependencias, vindo de um refactor do algoritmo atual de modules para DependencyGraphAnaliser em util.structures.

Esta PR faz somente esse corte de infra:

1. extrair o kernel estrutural reutilizavel;
2. migrar o uso atual de modules para esse novo componente;
3. deixar a superficie pronta para a futura aplicacao no graph de globals.

Target

Introduzir um analizador estrutural generico para:

1. topological ordering,
2. deterministic traversal,
3. cycle detection,
4. e, quando util, exposicao de SCC/path para diagnostics.

Dependencies

Prerequisitos diretos:

1. Globals Surface, Identity, and Module Boundaries Decision.md

Scope

1. Extrair o algoritmo atual de dependency ordering de modules para DependencyGraphAnaliser.
2. Definir uma API estrutural baseada em nos canonicos e edges preconstruidas.
3. Migrar a linha atual de modules para usar esse componente comum.
4. Preservar comportamento observavel dos diagnostics de modules.

Non-Goals

1. Nao introduzir ainda globals no pipeline semantico.
2. Nao misturar semantica de modules com semantica de globals.
3. Nao alterar parser ou AST.
4. Nao alterar diagnostics user-facing da linha de globals nesta PR.

Method

1. Extrair apenas o kernel estrutural; sem abstrair semantica de descoberta de edges.
2. Manter cada dominio responsavel por:
   • nos canonicos,
   • edges,
   • mapeamento para diagnostics.
3. Garantir regressao zero para a linha atual de dependency ordering de modules.

Acceptance Criteria

1. Existe um DependencyGraphAnaliser reutilizavel em infra util.structures.
2. Modules passam a usar esse componente sem mudar o contrato observavel atual.
3. O componente nao carrega conhecimento de modulo, global ou PBS-specific semantics.
4. A futura linha de globals consegue consumir o novo kernel sem novo refactor estrutural.

Tests

1. Testes atuais de dependency ordering e cycle detection de modules permanecem verdes.
2. Testes unitarios diretos do DependencyGraphAnaliser cobrem:
   • DAG simples,
   • ciclo,
   • ordering deterministico,
   • graph desconexo.

Affected Artifacts

1. prometeu-deps e/ou infra estrutural equivalente
2. fases atuais que usam o algoritmo de dependency ordering de modules

Open Questions

1. A exposicao de SCC/path pode ser minima nesta PR, desde que nao force novo refactor na PR-19.5.