Progresso de Script Batch

Torne scripts batch gerados observáveis enquanto eles rodam, sem alterar seu contrato de processamento. Defina a saída de início, progresso periódico, falha por item e resumo final junto com fluxos de resultado e status de saída. Uma biblioteca de barra de progresso sozinha não estabelece este contrato.

1. Corrija o contrato existente

Leia o script, chamadores e testes próximos antes de editar. Identifique:

• Unidade de entrada, total conhecido ou desconhecido, e se a enumeração é preguiçosa.
• Formato e consumidores de stdout existentes, versão do runtime e execução interativa versus redirecionada.
• Política de continuar em caso de erro ou falhar rapidamente, regras de retentativa, regras de pular, limites de transação e comportamento de cancelamento.
• Códigos de saída existentes e o que os chamadores tratam como sucesso.

Preserve essas decisões. Não adicione retentativas, paralelismo, dependências ou uma nova política de falha apenas para adicionar saída de progresso. Se falhas parciais atualmente retornam zero, reporte o resultado parcial honestamente enquanto mantém esse contrato de saída. Se o contrato estiver ausente ou contraditório, peça a decisão que altera o comportamento; não a tome silenciosamente.

2. Defina o contrato de saída antes da implementação

Escolha um vocabulário e campos pequenos e estáveis, reutilizando o logger do repositório onde for adequado:

• Início: nome da operação, total ou desconhecido explícito, e contadores iniciais. Emita antes da enumeração cara; a descoberta em si pode precisar de progresso.
• Progresso: processado, bem-sucedido, falhou, pulado, total ou desconhecido, e tempo decorrido. Adicione um identificador de item atual sanitizado apenas quando for útil.
• Falha de item: identificador seguro, categoria de falha ou motivo sanitizado, e se o processamento continuará. Emita quando observado, independentemente do intervalo de progresso normal.
• Resumo: concluído, parcial, falhou ou cancelado; contadores finais; tempo decorrido; contagem conhecida de não processados, se disponível; e o status de saída exigido pelo contrato existente.

Defina processed = succeeded + failed + skipped para itens que atingiram um resultado terminal. Mantenha itens em andamento e não iniciados separados. Conte cada item uma vez; tentativas de retentativa não são itens processados adicionais. Não rotule um item como bem-sucedido antes de seu commit, gravação ou reconhecimento exigido. Se uma transação reverter, reporte o trabalho revertido em vez de reivindicar sucesso duradouro.

Para um total desconhecido, reporte contagens sem uma porcentagem fabricada, ETA ou contagem restante. Não materialize um fluxo apenas para contá-lo. Para zero itens, emita início e resumo com contagens zero; nunca divida por zero.

3. Escolha fluxos de saída e cadência

Reserve o stdout para o resultado estabelecido legível por máquina, objetos de pipeline ou protocolo. Coloque progresso e diagnósticos em um canal separado; stderr é o padrão portátil para scripts CLI autônomos. A saída de stderr sozinha não implica falha: os chamadores devem usar o código de saída e o contrato de resultado acordados. Verifique os chamadores que tratam qualquer stderr como falha antes de alterar sua saída. Se o stdout for reservado e o stderr for incompatível, use um logger ou sink compatível existente apenas quando o chamador já o suportar. Não mova o progresso para stdout ou outro fluxo com semântica alterada. Se nenhum canal compatível existir, pare e pergunte se o contrato de saída pode ser alterado, ou reporte que o progresso não pode ser adicionado com segurança.

Use uma cadência limitada, como a cada número configurado de itens ou intervalo decorrido, em vez de registrar incondicionalmente cada item. Emita início, falhas e resumo independentemente dessa cadência. Preserve registros de auditoria por item necessários separadamente. Evite listas de falhas ilimitadas na memória e rastros de pilha repetidos. Redija credenciais, parâmetros de consulta, dados pessoais e caminhos sensíveis antes da formatação; não despeje exceções brutas ou registros de entrada inteiros por padrão.

Use tempo monotônico para intervalos e duração. Garanta que a saída seja descarregada ou drenada para que as notificações cheguem antes da saída. Use registros simples delimitados por nova linha sob redirecionamento; habilite reescrita de terminal ou cores apenas para um TTY apropriado. Mantenha os significados dos campos de log consistentes entre as linguagens, não necessariamente sua formatação exata ou bibliotecas.

…