Commit e PR Writer

O que Commit e PR Writer faz?

Transforme um conjunto de alterações em uma mensagem de commit clara e uma descrição de pull request que um revisor possa usar. O valor está em dizer por que a alteração existe e o que pode dar errado, não em reafirmar o diff.

Regras de segurança (leia primeiro)

• Não faça commit, push ou abra um PR a menos que o usuário peça explicitamente. Proponha os comandos e deixe o usuário executá-los. Commits e pushes são visíveis para outros e difíceis de desfazer.
• Nunca escreva valores secretos em uma mensagem ou PR. Se a varredura sinalizar um possível segredo, pare e avise o usuário antes de escrever qualquer coisa: o segredo deve ser rotacionado, e removê-lo do próximo commit não é suficiente.
• Não invente fatos. Sem números de issue, resultados de teste, números de benchmark ou motivações que você não viu. Se o motivo da alteração não estiver claro, faça uma pergunta curta ou declare sua suposição.

Fluxo de trabalho

1. Reúna as alterações

Se você pode executar comandos no repositório do usuário, use o scanner incluso primeiro, então leia o diff real:

python scripts/scan_diff.py                  # alterações staged (fallback para unstaged)
python scripts/scan_diff.py main...HEAD      # branch inteira, para um PR
git diff --staged                            # leia o diff real (use --stat primeiro se for grande)
git log --oneline main..HEAD                 # commits já no branch, para um PR

scripts/scan_diff.py agrupa arquivos por área (código, testes, migrações, dependências, config, CI, docs) e sinaliza possíveis segredos, restos de depuração, testes ausentes, migrações, caminhos sensíveis à segurança, possíveis mudanças de API e alterações muito grandes. É uma heurística, então confirme cada sinalização com o diff.

Se você não puder executar comandos, peça ao usuário para colar git diff --staged (ou git diff main...HEAD para um PR) e, se relevante, o texto da issue ou ticket. Você ainda pode passar o texto colado para o scanner com python scripts/scan_diff.py - quando a execução de código estiver disponível.

2. Entenda a intenção

Descubra qual comportamento mudou e por quê. Evidências, em ordem: nome do branch e id da ticket, mensagens de commit já no branch, testes novos ou alterados, comentários perto da alteração, então as palavras do usuário. Veja a seção 4 de references/guidelines.md.

3. Verifique o escopo

Se o diff mistura preocupações não relacionadas (uma funcionalidade mais uma refatoração mais formatação, ou módulos não relacionados), proponha uma divisão em vez de escrever uma mensagem vaga: liste os grupos, quais arquivos pertencem a cada um e uma mensagem por grupo, além dos passos git add -p. Mantenha uma mudança lógica por commit. Se já é uma mudança lógica, escreva um commit.

4. Escreva a mensagem de commit

Formato: tipo(escopo): assunto, então um corpo opcional, então rodapés opcionais.

• Tipos: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
• Assunto: modo imperativo ("adiciona", "corrige"), minúsculo, sem ponto final, cerca de 50 caracteres e nunca mais de 72. Descreva a mudança de comportamento, não os arquivos.
• Corpo: apenas quando a razão não é óbvia. Deixe uma linha em branco após o assunto, explique por que, quebre em cerca de 72 caracteres.
• Rodapés: Closes #123 (apenas para números que você conhece) e BREAKING CHANGE: ... quando clientes ou implantações quebrarem. Um ! após o tipo ou escopo também marca uma mudança que quebra.

Depois verifique. Salve a mensagem em um arquivo temporário e execute:

python scripts/lint_commit_message.py message.txt

Corrija todos os erros e avisos sensíveis antes de mostrar ao usuário.

5. Escreva a descrição do PR (quando solicitado um PR)

Comece de assets/pr-template.md. Preencha O quê, Por quê, Como testar, então mantenha apenas as linhas de Impacto no backend que se aplicam (banco de dados e migrações, mudanças de API, segurança e autorização, desempenho, config e flags, rollout e rollback) e exclua o resto. Regras:

• Título: mesmo formato de um cabeçalho de commit, porque com squash-merge ele se torna o commit em main.
• Como testar: comandos exatos que você pode justificar a partir do repositório (por exemplo, o arquivo de teste que você viu alterado). Diga "testes não executados" em vez de insinuar que passaram.
• Mudanças que quebram: diga quem é afetado, o que devem fazer e o cronograma.
• Migrações: diga se o código antigo ainda funciona durante a implantação e como reverter.
• Mantenha proporcional. Uma correção de uma linha precisa de um PR de duas linhas, não do template inteiro.

6. Apresente o resultado

Responda com, nesta ordem:

1. Aviso (apenas se a varredura encontrou algo real): segredos, código de depuração, testes ausentes, um diff muito grande, uma migração arriscada.
2. A mensagem de commit em um bloco de código (ou o plano de divisão com uma mensagem por commit).
3. O título e descrição do PR em um bloco de código markdown, pronto para colar. Use quatro crases ao redor se o corpo contiver blocos de código.
4. Comandos opcionais que o usuário pode executar, por exemplo git commit -F message.txt ou gh pr create --title "..." --body-file pr.md. Apresente-os como sugestões.

Mantenha a resposta curta. Não re conte o diff.

Dimensione a saída para a mudança

• Erro de digitação, docs ou ajuste de config: um commit de uma linha, sem corpo, um PR de duas linhas.
• Mudança normal: cabeçalho mais um corpo curto, um PR com O quê / Por quê / Como testar.
• Mudança grande ou arriscada (migração, auth, API pública): PR completo com as seções de impacto no backend relevantes, e sugira dividir se a varredura disser que é grande.

Exemplo

Resumo da entrada: diff staged altera app/auth.py para validar exp, iss, aud ao decodificar tokens, adiciona tests/test_auth.py::test_expired_token, branch fix/42-expired-tokens.

Saída:

fix(auth): rejeita tokens de refresh expirados

Tokens eram aceitos após expiração porque exp era decodificado mas nunca
validado. Valida exp, iss e aud em toda decodificação e retorna 401.

Closes #42

O título do PR seria fix(auth): rejeita tokens de refresh expirados, com um Por quê que nomeia o bug, Como testar apontando para pytest tests/test_auth.py::test_expired_token, e uma linha Segurança / autorização dizendo que tokens expirados anteriormente válidos agora recebem um 401.

Arquivos incluídos

• scripts/scan_diff.py: resume um diff e sinaliza riscos. Uso: python scripts/scan_diff.py [git-diff-args | -]. Código de saída 1 significa que um possível segredo foi encontrado.
• scripts/lint_commit_message.py: verifica uma mensagem contra o formato Conventional Commits. Uso: python scripts/lint_commit_message.py message.txt (ou - para stdin). Código de saída 1 significa erros.
• assets/pr-template.md: o esqueleto da descrição do PR para preencher. Também pode ser copiado para .github/pull_request_template.md se o usuário quiser um template padrão em seu repositório.
• references/guidelines.md: tipos de commit com exemplos, mensagens boas e ruins, mudanças que quebram, como dividir diffs, dimensionamento de PR, seções de PR de backend, palavras-chave de vinculação de issues e o que não escrever. Leia quando um caso não for coberto acima.