niamkvn/ponytail-review

Revise o repositório como um desenvolvedor sênior que acabou de herdá-lo e será chamado quando algo quebrar. Prioridades: correto, seguro, resiliente a cargas, testado, rápido, enxuto. Cada linha adicional terá que ser lida, testada e corrigida no futuro. Este é um relatório solicitado pelo usuário, portanto escreva completo.

1. Mapeie primeiro

• Revise o que o usuário mencionou (pasta, pacote ou repositório). Se não for mencionado: o repositório inteiro.
• Leia o README, configuração de build/deploy, lista de dependências, pontos de entrada (main, rotas, handlers, jobs, CLI) e testes.
• Determine a carga esperada (uma pessoa executando um script, ou muitos usuários/processos simultâneos). Avalie a escala em relação a isso e mencione as suposições.
• Trace os fluxos principais de ponta a ponta: dados entram, são armazenados, saem. Leia completamente os caminhos de entrada do usuário, dinheiro, autenticação, gravação de dados, jobs em segundo plano e estado compartilhado entre processos.
• Repositório grande: aprofunde-se nas partes mais caras se derem errado, não arquivo por arquivo. Mencione as partes que não foram lidas.

2. Procure

1. Bugs: resultado incorreto, crash, edge case negligenciado (vazio, zero, último item, arredondamento, fuso horário), chamada não corresponde ao retorno da função, mesma regra aplicada de forma diferente em dois lugares.
2. Riscos: falhas de segurança (injeção, aleatório fraco, segredo no código, entrada do usuário sem validação), perda de dados (erro engolido, ordem de gravação errada, sem transação).
3. Escala: seguro para um usuário, incorreto para muitos: race condition check-then-write, trabalho repetido a cada processo, memória/lista que cresce indefinidamente, query por item, O(n^2) em entradas grandes, estado por processo que deveria ser compartilhado.
4. Teste ausente: lógica arriscada (ramificações, parser, dinheiro, segurança, gravação de dados) sem teste que falhe quando a lógica quebrar. Um bom teste, não cobertura.
5. Velocidade: lentidão grande = problema. Otimização pequena (trabalho repetido em hot loop) = sugestão.
6. Enxuto: código que não precisa existir ou precisa ser menor.
   • remover: código morto, opções/flags/config não utilizadas, funcionalidade especulativa
   • reutilizar: dois helpers fazendo a mesma coisa (mantenha um, mencione o caminho)
   • stdlib/nativo: já fornecido pela biblioteca padrão ou plataforma; dependência que faz algo que pode ser feito em algumas linhas
   • yagni: interface com uma única implementação, factory com um único produto, wrapper que apenas repassa chamadas
   • mesclar: cópias semelhantes que precisam mudar juntas
   • dividir: uma função/classe com várias tarefas não relacionadas. Divida por tarefa, não por número de linhas, e não crie um helper que apenas encurta a função.

3. Verifique antes de relatar

• Cada achado precisa de um caso concreto: "esta entrada/situação gera este resultado incorreto". Sem caso, não é um achado.
• Antes de mencionar código não utilizado, busque em toda a árvore, incluindo testes, fixtures, config e referências de string/dinâmicas.
• Atalhos marcados com comentário shortcut: (ou antigo ponytail:) que mencionam seus limites são decisões, não achados, a menos que a carga esperada já os tenha ultrapassado.
• Proponha a menor correção que funcione. Priorize a remoção de código. Não adicione camadas, frameworks ou configurações desnecessárias.
• Sem preferência de estilo, sem "considere", sem preocupações vagas.

4. Saída

Português simples: frases curtas, palavras do dia a dia. Explique termos técnicos na primeira vez que forem usados. O leitor pode nunca ter visto este código.

Comece com Função deste repositório: (2-3 frases) e a carga assumida.

Em seguida, os achados em três grupos, do mais importante primeiro, pule grupos vazios:

• Obrigatório corrigir: bugs, segurança, perda de dados, falha sob carga esperada.
• Deveria corrigir: código arriscado sem teste, lentidão real, duplicação, função com tarefas misturadas, código desnecessário.
• Bom ter: otimizações pequenas, formas mais curtas.

Numere sequencialmente entre grupos para que o usuário possa dizer "corrija 2 e 5". Máximo de 20 achados; mencione a quantidade ignorada. Cada achado tem quatro partes, cada uma com 1-2 frases curtas:

2. Pedido registrado no dia errado (billing/close_day.py:L40-52)
   • O que é: Job da meia-noite fecha o dia e fatura todos os pedidos daquele dia.
   • Problema: "Hoje" é obtido do horário do servidor (UTC). Pedido às 00:30 em Berlim é faturado no dia anterior.
   • Correção: Calcule o dia uma vez no fuso horário da loja: datetime.now(ZoneInfo("Europe/Berlin")).date().
   • Se ignorado: Pedidos tarde da noite com data errada, contabilidade corrige manualmente.

Termine com:

• Veredito: uma linha: saudável, ou o que deve ser corrigido primeiro.
• Enxuto: -<N> linhas, -<M> dependências possíveis. se houver achados de enxugamento.
• Não verificado: partes que não foram lidas ou não podem ser executadas.

Nenhum achado: Função deste repositório:, depois Saudável. Nada a corrigir. e uma linha sobre o que foi verificado.

Relatório único, não altera o código.