prometeu-runtime/docs/pull-requests/PR-015-[QUALITY]-burn-down-clippy-warnings.md

PR-015 [QUALITY]: Burn Down Clippy Warnings

Briefing

O workspace compila e a suite principal de testes esta saudavel, mas cargo clippy --workspace --all-features ainda retorna uma quantidade relevante de warnings. Isso nao e detalhe cosmetico: warnings recorrentes enfraquecem o valor do lint e escondem sinais novos que deveriam chamar atencao imediata.

Esta PR fecha a divida de lint com foco em warnings claros, mecanicos e de baixo risco. A meta e tornar clippy um gate com alta relacao sinal/ruido.

Problema

• cargo clippy --workspace --all-features termina com warnings em multiplas crates;
• ha uma mistura de problemas triviais e repetitivos:
  • new_without_default;
  • collapsible_if;
  • redundant_closure;
  • clone_on_copy;
  • needless_borrow;
  • unnecessary_cast;
  • too_many_arguments;
  • module_inception;
• enquanto o baseline permanecer ruidoso, novos warnings entram sem friccao.

Alvo

• crates do workspace que hoje emitem warnings de clippy;
• principalmente prometeu-vm, prometeu-system, prometeu-host-desktop-winit, prometeu-drivers e pbxgen-stress.

Escopo

• Eliminar warnings de clippy que tenham correcao local, objetiva e de baixo risco.
• Introduzir Default onde a recomendacao fizer sentido sem distorcer o modelo de construcao.
• Simplificar fluxo de controle e remocoes de ruido sintatico.
• Decidir explicitamente o tratamento de warnings que indiquem tradeoff arquitetural real.

Fora de Escopo

• Grandes refactors de design apenas para satisfazer lint.
• Mudancas arquiteturais em API publica sem discussao previa.
• Reescrever modulos inteiros por motivos esteticos.
• Alterar a taxonomia arquitetural do runtime.

Abordagem

1. Classificar warnings em dois grupos:
   • mecanicos e sem risco;
   • warnings que tocam modelagem publica ou ergonomia de API.
2. Corrigir primeiro o grupo mecanico.
3. Para warnings que implicarem decisao de design, escolher uma de duas saidas:
   • corrigir com justificativa clara;
   • silenciar localmente com comentario curto e motivo tecnico defensavel.
4. Reexecutar cargo clippy --workspace --all-features ate baseline limpo ou explicitamente justificado.

Criterios de Aceite

• cargo clippy --workspace --all-features termina sem warnings, ou com excecoes locais raras e justificadas no codigo.
• Nenhuma mudanca amplia API ou comportamento sem necessidade.
• O resultado final aumenta, e nao reduz, a legibilidade do codigo.
• Warnings mecanicos recorrentes deixam de existir no baseline.

Tests

• Rodar cargo clippy --workspace --all-features.
• Rodar cargo test --workspace --all-targets --all-features --no-fail-fast.
• Se alguma correcao tocar caminho quente do runtime, rodar tambem os testes da crate afetada de forma isolada para facilitar triagem.

Risco

Medio. O risco nao esta no clippy; esta em usar o lint como desculpa para refatorar demais. Esta PR deve ser conservadora: eliminar ruido sem inventar arquitetura nova.