SamiKhan43/commit-and-pr-writer

Escritor de commits y PRs

Convierte un conjunto de cambios en un mensaje de commit claro y una descripción de pull request que un revisor pueda usar. El valor está en decir por qué existe el cambio y qué podría salir mal, no en repetir el diff.

Reglas de seguridad (léase primero)

• No hacer commit, push ni abrir un PR a menos que el usuario lo solicite explícitamente. Propón los comandos y deja que el usuario los ejecute. Los commits y pushes son visibles para otros y difíciles de deshacer.
• Nunca escribir valores secretos en un mensaje o PR. Si el escaneo detecta un posible secreto, detente e informa al usuario antes de escribir nada: el secreto debe ser rotado, y eliminarlo del siguiente commit no es suficiente.
• No inventar hechos. Sin números de issue, resultados de pruebas, números de benchmark o motivaciones que no hayas visto. Si la razón del cambio no está clara, haz una pregunta breve o expresa tu suposición.

Flujo de trabajo

1. Reunir los cambios

Si puedes ejecutar comandos en el repositorio del usuario, usa primero el escáner incluido y luego lee el diff real:

python scripts/scan_diff.py                  # cambios staged (falla a unstaged)
python scripts/scan_diff.py main...HEAD      # rama completa, para un PR
git diff --staged                            # leer el diff real (usa --stat primero si es grande)
git log --oneline main..HEAD                 # commits ya en la rama, para un PR

scripts/scan_diff.py agrupa los archivos por área (código, pruebas, migraciones, dependencias, configuración, CI, documentos) y señala posibles secretos, restos de depuración, pruebas faltantes, migraciones, rutas sensibles de seguridad, posibles cambios de API y cambios de gran tamaño. Es heurístico, así que confirma cada marca contra el diff.

Si no puedes ejecutar comandos, pídele al usuario que pegue git diff --staged (o git diff main...HEAD para un PR) y, si es relevante, el texto del issue o ticket. Aún puedes pasar el texto pegado al escáner con python scripts/scan_diff.py - cuando la ejecución de código esté disponible.

2. Entender la intención

Determina qué comportamiento cambió y por qué. Evidencia, en orden: nombre de la rama e id del ticket, mensajes de commit ya en la rama, pruebas nuevas o modificadas, comentarios cerca del cambio, luego las palabras del usuario. Consulta la sección 4 de references/guidelines.md.

3. Verificar el alcance

Si el diff mezcla preocupaciones no relacionadas (una funcionalidad más una refactorización más formato, o módulos no relacionados), propón una división en lugar de escribir un mensaje vago: enumera los grupos, qué archivos pertenecen a cada uno y un mensaje por grupo, más los pasos de git add -p. Mantén un cambio lógico por commit. Si ya es un solo cambio lógico, escribe un solo commit.

4. Escribir el mensaje de commit

Formato: tipo(ámbito): asunto, luego un cuerpo opcional y luego pies opcionales.

• Tipos: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
• Asunto: modo imperativo ("añade", "corrige"), minúsculas, sin punto final, aproximadamente 50 caracteres y nunca más de 72. Describe el cambio de comportamiento, no los archivos.
• Cuerpo: solo cuando la razón no sea obvia. Deja una línea en blanco después del asunto, explica por qué, ajusta a unos 72 caracteres.
• Pies: Closes #123 (solo para números que conozcas) y BREAKING CHANGE: ... cuando los clientes o despliegues se rompan. Un ! después del tipo o ámbito también marca un cambio innovador.

Luego verifícalo. Guarda el mensaje en un archivo temporal y ejecuta:

python scripts/lint_commit_message.py message.txt

Corrige todos los errores y advertencias sensatas antes de mostrárselo al usuario.

5. Escribir la descripción del PR (cuando se solicite un PR)

Comienza desde assets/pr-template.md. Completa Qué, Por qué, Cómo probar, luego conserva solo las líneas de Impacto en el backend que apliquen (base de datos y migraciones, cambios de API, seguridad y autorización, rendimiento, configuración y flags, lanzamiento y reversión) y elimina el resto. Reglas:

• Título: mismo formato que un encabezado de commit, porque con squash-merge se convierte en el commit en main.
• Cómo probar: comandos exactos que puedas justificar desde el repositorio (por ejemplo, el archivo de prueba que viste cambiar). Di "pruebas no ejecutadas" en lugar de implicar que pasaron.
• Cambios innovadores: di quién está afectado, qué deben hacer y el cronograma.
• Migraciones: di si el código antiguo sigue funcionando durante el despliegue y cómo revertir.
• Mantén la proporción. Una corrección de una línea necesita un PR de dos líneas, no la plantilla completa.

6. Presentar el resultado

Responde con, en este orden:

1. Aviso (solo si el escaneo encontró algo real): secretos, código de depuración, pruebas faltantes, un diff muy grande, una migración riesgosa.
2. El mensaje de commit en un bloque de código (o el plan de división con un mensaje por commit).
3. El título y la descripción del PR en un bloque de código markdown, listo para pegar. Usa cuatro comillas invertidas alrededor si el cuerpo contiene bloques de código.
4. Comandos opcionales que el usuario puede ejecutar, por ejemplo git commit -F message.txt o gh pr create --title "..." --body-file pr.md. Preséntalos como sugerencias.

Mantén la respuesta breve. No vuelvas a contar el diff.

Escalar la salida al cambio

• Error tipográfico, docs o ajuste de configuración: un commit de una línea, sin cuerpo, un PR de dos líneas.
• Cambio normal: encabezado más un cuerpo corto, un PR con Qué / Por qué / Cómo probar.
• Cambio grande o riesgoso (migración, autenticación, API pública): PR completo con las secciones de impacto en el backend relevantes, y sugiere dividir si el escaneo dice que es grande.

Ejemplo

Resumen de entrada: diff staged cambia app/auth.py para validar exp, iss, aud al decodificar tokens, añade tests/test_auth.py::test_expired_token, rama fix/42-expired-tokens.

Salida:

fix(auth): rechazar tokens de actualización expirados

Los tokens se aceptaban después de su expiración porque exp se decodificaba
pero nunca se validaba. Validar exp, iss y aud en cada decodificación y devolver 401.

Closes #42

El título del PR sería fix(auth): rechazar tokens de actualización expirados, con un Por qué que nombre el bug, Cómo probar apuntando a pytest tests/test_auth.py::test_expired_token, y una línea de Seguridad / autorización que diga que los tokens expirados previamente válidos ahora reciben un 401.

Archivos incluidos

• scripts/scan_diff.py: resume un diff y señala riesgos. Uso: python scripts/scan_diff.py [git-diff-args | -]. Código de salida 1 significa que se encontró un posible secreto.
• scripts/lint_commit_message.py: verifica un mensaje contra el formato Conventional Commits. Uso: python scripts/lint_commit_message.py message.txt (o - para stdin). Código de salida 1 significa errores.
• assets/pr-template.md: el esqueleto de la descripción del PR a rellenar. También se puede copiar a .github/pull_request_template.md si el usuario quiere una plantilla predeterminada en su repositorio.
• references/guidelines.md: tipos de commit con ejemplos, mensajes buenos y malos, cambios innovadores, cómo dividir diffs, tamaño de PRs, secciones de PR de backend, palabras clave para enlazar issues, y qué no escribir. Léelo cuando un caso no esté cubierto arriba.