SamiKhan43/commit-and-pr-writer

Commit and PR writer

Transformez un ensemble de modifications en un message de commit clair et une description de pull request qu'un relecteur peut exploiter. La valeur réside dans le fait d'expliquer pourquoi le changement existe et ce qui pourrait mal se passer, et non pas de reformuler le diff.

Règles de sécurité (à lire en premier)

• Ne pas commit, push ou ouvrir une PR sauf si l'utilisateur le demande explicitement. Proposez les commandes et laissez l'utilisateur les exécuter. Les commits et les pushes sont visibles par les autres et difficiles à annuler.
• Ne jamais écrire de valeurs secrètes dans un message ou une PR. Si le scan détecte un secret potentiel, arrêtez-vous et prévenez l'utilisateur avant d'écrire quoi que ce soit : le secret doit être révoqué, et le supprimer du prochain commit ne suffit pas.
• N'inventez pas de faits. Pas de numéros d'issue, de résultats de test, de chiffres de performance ou de motivations que vous n'avez pas vus. Si la raison du changement n'est pas claire, posez une question courte ou énoncez votre hypothèse.

Workflow

1. Récupérer les modifications

Si vous pouvez exécuter des commandes dans le dépôt de l'utilisateur, utilisez d'abord le scanneur fourni, puis lisez le diff réel :

python scripts/scan_diff.py                  # modifications staged (utilise unstaged si absent)
python scripts/scan_diff.py main...HEAD      # branche entière, pour une PR
git diff --staged                            # lire le diff réel (utilisez --stat d'abord s'il est volumineux)
git log --oneline main..HEAD                 # commits déjà sur la branche, pour une PR

scripts/scan_diff.py regroupe les fichiers par domaine (code, tests, migrations, dépendances, config, CI, docs) et signale les secrets potentiels, les artefacts de débogage, les tests manquants, les migrations, les chemins sensibles pour la sécurité, les changements d'API possibles et les modifications surdimensionnées. C'est une heuristique, confirmez donc chaque alerte par rapport au diff.

Si vous ne pouvez pas exécuter de commandes, demandez à l'utilisateur de coller git diff --staged (ou git diff main...HEAD pour une PR) et, le cas échéant, le texte de l'issue ou du ticket. Vous pouvez toujours rediriger le texte collé vers le scanneur avec python scripts/scan_diff.py - lorsque l'exécution de code est disponible.

2. Comprendre l'intention

Déterminez quel comportement a changé et pourquoi. Preuves, dans l'ordre : nom de branche et identifiant de ticket, messages de commit déjà sur la branche, tests nouveaux ou modifiés, commentaires près de la modification, puis les mots de l'utilisateur. Voir references/guidelines.md section 4.

3. Vérifier la portée

Si le diff mélange des préoccupations indépendantes (une fonctionnalité avec un refactor et du formatage, ou des modules non liés), proposez une division au lieu d'écrire un message vague : listez les groupes, les fichiers appartenant à chacun, et un message par groupe, ainsi que les étapes git add -p. Gardez un changement logique par commit. S'il s'agit déjà d'un seul changement logique, écrivez un seul commit.

4. Écrire le message de commit

Format : type(portée): sujet, puis un corps optionnel, puis des pieds de page optionnels.

• Types : feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
• Sujet : impératif ("ajoute", "corrige"), minuscule, pas de point final, environ 50 caractères et jamais plus de 72. Décrivez le changement de comportement, pas les fichiers.
• Corps : seulement lorsque la raison n'est pas évidente. Laissez une ligne vide après le sujet, expliquez pourquoi, coupez à environ 72 caractères.
• Pieds de page : Closes #123 (uniquement pour les numéros que vous connaissez) et BREAKING CHANGE: ... lorsque les clients ou les déploiements seront cassés. Un ! après le type ou la portée marque également un changement cassant.

Ensuite, vérifiez-le. Sauvegardez le message dans un fichier temporaire et exécutez :

python scripts/lint_commit_message.py message.txt

Corrigez toutes les erreurs et les avertissements pertinents avant de les montrer à l'utilisateur.

5. Rédiger la description de la PR (lorsqu'une PR est demandée)

Partez de assets/pr-template.md. Remplissez Quoi, Pourquoi, Comment tester, puis ne conservez que les lignes Impact backend qui s'appliquent (base de données et migrations, changements d'API, sécurité et autorisation, performance, configuration et flags, déploiement et rollback) et supprimez les autres. Règles :

• Titre : même format qu'un en-tête de commit, car avec un squash-merge, il devient le commit sur main.
• Comment tester : commandes exactes que vous pouvez justifier à partir du dépôt (par exemple le fichier de test que vous avez vu modifié). Dites "tests non exécutés" plutôt que de laisser entendre qu'ils ont réussi.
• Changements cassants : dites qui est concerné, ce qu'ils doivent faire, et le calendrier.
• Migrations : dites si l'ancien code fonctionne toujours pendant le déploiement et comment revenir en arrière.
• Restez proportionné. Une correction d'une ligne nécessite une PR de deux lignes, pas le modèle complet.

6. Présenter le résultat

Répondez avec, dans cet ordre :

1. Alerte (uniquement si le scan a trouvé quelque chose de réel) : secrets, code de débogage, tests manquants, diff très volumineux, migration risquée.
2. Le message de commit dans un bloc de code (ou le plan de division avec un message par commit).
3. Le titre et la description de la PR dans un bloc de code markdown, prêts à être collés. Utilisez quatre backticks autour si le corps contient des blocs de code.
4. Commandes optionnelles que l'utilisateur peut exécuter, par exemple git commit -F message.txt ou gh pr create --title "..." --body-file pr.md. Présentez-les comme des suggestions.

Restez concis dans la réponse. Ne répétez pas le diff.

Adapter la sortie au changement

• Faute de frappe, documentation ou ajustement de configuration : un commit d'une ligne, pas de corps, une PR de deux lignes.
• Changement normal : en-tête plus un corps court, une PR avec Quoi / Pourquoi / Comment tester.
• Changement volumineux ou risqué (migration, authentification, API publique) : PR complète avec les sections d'impact backend pertinentes, et suggérez une division si le scan indique qu'il est volumineux.

Exemple

Résumé d'entrée : un diff staged modifie app/auth.py pour valider exp, iss, aud lors du décodage des jetons, ajoute tests/test_auth.py::test_expired_token, branche fix/42-expired-tokens.

Sortie :

fix(auth): rejeter les jetons de rafraîchissement expirés

Les jetons étaient acceptés après expiration car exp était décodé mais
jamais validé. Validez exp, iss et aud à chaque décodage et retournez 401.

Closes #42

Le titre de la PR serait fix(auth): rejeter les jetons de rafraîchissement expirés, avec un Pourquoi qui nomme le bogue, un Comment tester pointant vers pytest tests/test_auth.py::test_expired_token, et une ligne Sécurité / autorisation indiquant que les jetons expirés précédemment valides obtiennent désormais un 401.

Fichiers fournis

• scripts/scan_diff.py : résume un diff et signale les risques. Usage : python scripts/scan_diff.py [git-diff-args | -]. Code de sortie 1 signifie qu'un secret potentiel a été trouvé.
• scripts/lint_commit_message.py : vérifie un message par rapport au format Conventional Commits. Usage : python scripts/lint_commit_message.py message.txt (ou - pour l'entrée standard). Code de sortie 1 signifie des erreurs.
• assets/pr-template.md : le squelette de description de PR à remplir. Il peut également être copié vers .github/pull_request_template.md si l'utilisateur souhaite un modèle par défaut dans son dépôt.
• references/guidelines.md : types de commit avec exemples, bons et mauvais messages, changements cassants, comment diviser les diffs, taille des PR, sections des PR backend, mots-clés de liaison d'issues, et ce qu'il ne faut pas écrire. Lisez-le lorsqu'un cas n'est pas couvert ci-dessus.