Examen de code façon humaine

Examinez une pull request GitHub avec l'esprit d'un examen de code et produisez un fichier markdown convivial pour copier/coller contenant vos retours. Les résultats sont l'élément central : priorisez les bugs, les régressions comportementales, les problèmes de sécurité et les tests manquants, ordonnés par gravité. Ne modifiez pas le code à moins que l'utilisateur ne vous le demande explicitement.

Entrée

L'utilisateur doit fournir une URL de pull request GitHub (par ex. https://github.com/n8n-io/n8n/pull/1234).

Si elle n'est pas fournie, demandez-la avant de continuer.

Extraire le numéro de PR et le repository de l'URL et utiliser le CLI gh pour récupérer le diff et les métadonnées de la PR.

Flux de travail

1. Parser l'URL de la PR pour obtenir le propriétaire, le repo et le numéro de PR.
2. Récupérer le diff de la PR : gh pr diff <number> --repo <owner>/<repo>
3. Récupérer les métadonnées de la PR : gh pr view <number> --repo <owner>/<repo>
4. Récupérer les commentaires d'examen existants : gh api repos/<owner>/<repo>/pulls/<number>/comments
5. Examiner le diff en détail avec un esprit critique d'examen de code.
6. Produire un nouveau fichier .md nommé review-<repo>-<number>.md dans le dossier tmp/ du repo ignoré par git, afin qu'il ne soit jamais commité (le dossier tmp est listé dans .gitignore). Créer le dossier si nécessaire (mkdir -p tmp) et écrire dans tmp/review-<repo>-<number>.md. Afficher le chemin du fichier une fois terminé pour que l'utilisateur puisse l'ouvrir.
7. Si un point a déjà été soulevé dans les commentaires existants de la PR, vérifier s'il est toujours valide - s'il est résolu, confirmer qu'il est corrigé ; s'il est encore ouvert, élargir le commentaire ou ajouter du contexte au lieu de le répéter.
8. Avant de terminer, nettoyer tous les fichiers temporaires créés lors de l'examen. Le seul fichier qui doit rester dans tmp/ à la suite de cette exécution est le fichier d'examen final tmp/review-<repo>-<number>.md.

Hygiène des fichiers temporaires

Préférer lire la sortie de gh directement au lieu d'écrire des fichiers supplémentaires. Si vous avez besoin de fichiers temporaires pour un examen complexe (par exemple, un diff sauvegardé ou des contenus de fichiers extraits), les supprimer avant de terminer. Ne pas laisser de tmp/pr-*.diff, fichiers sources extraits, ou fichiers temporaires vides.

Éléments à prioriser

Les résultats doivent être l'élément central, ordonnés par gravité (du plus grave au moins grave) :

1. Bugs - erreurs de logique, décalage d'un, gestion des null/undefined, conditions incorrectes.
2. Régressions comportementales - modifications qui cassent ou altèrent le comportement existant.
3. Problèmes de sécurité - injection, lacunes d'authentification/autorisation, gestion non sécurisée des entrées, exposition de secrets.
4. Tests manquants - la modification réelle n'est pas couverte, ou les cas limites ne sont pas testés.

Le style, la dénomination et les petites remarques viennent en dernier, et seulement s'ils importent vraiment.

Compatibilité rétroactive

Notamment lorsque des nœuds sont modifiés, vérifier que la modification ne casse pas la compatibilité rétroactive pour les workflows des utilisateurs existants (paramètres renommés/supprimés, modifications des valeurs par défaut, forme de sortie altérée, comportement différent pour la même entrée).

S'il y a un risque de rupture de compatibilité rétroactive, envisager la versionnage des nœuds et laisser cela dans les commentaires - pointer le risque et suggérer une nouvelle version de nœud (ou une valeur par défaut versionnée) au lieu de modifier le comportement existant sur place.

Format de sortie

Le fichier markdown doit contenir :

• Un en-tête avec le titre de la PR, l'URL et la date d'examen.
• Une section ## Hints for a reviewer (voir ci-dessous).
• Une section ## General (voir ci-dessous).
• Une section ## Comments avec une liste de commentaires d'examen dans ce format :

nom du fichier + numéro de ligne + commentaire

Les commentaires doivent être faciles à copier/coller. Ne pas citer les commentaires en utilisant > - simplement les écrire directement.

C'est tout à fait acceptable d'avoir aucun commentaire de ligne. Ne pas forcer les résultats ou signaler des choses mineures juste pour avoir quelque chose à dire. Dans ces cas, préférer une liste de commentaires vide et un court commentaire positif dans ## General.

Quand un commentaire suggère quelque chose de différent, être précis à ce sujet. Soit proposer la modification de code réelle (un court snippet ou un bloc suggestion que l'auteur peut appliquer directement), soit, si un snippet complet n'est pas pratique, indiquer la direction concrète (quelle fonction/valeur/approche utiliser) plutôt qu'une indication vague. Éviter les commentaires comme « cela pourrait être plus propre » sans prochaine étape actuelle.

Hints for a reviewer

Juste après l'en-tête, inclure une section ## Hints for a reviewer pour orienter l'examinateur humain avant qu'il lise le diff :

• Une courte raison pour laquelle la PR a été créée (le problème qu'elle résout ou l'objectif).
• Quelques mots basiques expliquant la solution, sans surcomplication.
• Si c'est une PR communautaire, le mentionner brièvement. Vous pouvez généralement le savoir à partir de authorAssociation ou d'une branche préfixée par un fork comme random-fork-owner:fix-node-option.

Limiter cela à quelques phrases. C'est pour faire gagner du temps à l'examinateur, pas une rédaction détaillée.

Commentaire de synthèse générale

Avant les commentaires ligne par ligne, inclure une section ## General qui peut être collée comme synthèse d'examen. Qu'elle sonne humaine et naturelle - c'est acceptable de commencer par quelque chose de court et sympathique comme « Hey, beau travail sur ça » quand la modification le mérite. Puis ajouter tout retour au niveau de la PR qui n'appartient pas à une seule ligne - par ex. préoccupations de conception ou d'architecture, un contrat implicite/non type-safe entre fichiers, motifs répétés, portée, ou couverture de test manquante de la modification réelle.

• Garder cela court et conversationnel. Ne pas répéter ou résumer les commentaires de ligne individuels ici.
• L'exception est un grand problème de conception avec la solution globale : quand toute l'approche est mauvaise ou a un problème structurel, expliquer l'idée globale ici plutôt que de la disperser sur plusieurs commentaires.
• S'il n'y a vraiment rien à soulever au niveau de la PR, écrire une courte synthèse d'examen positive et continuer - ne pas la remplir.

Règles de numérotation des lignes

Les numéros de ligne DOIVENT être les véritables numéros de ligne dans le fichier sur la branche de PR (le côté nouveau/droit du diff), PAS la position dans le chunk du diff.

Pour obtenir le numéro de ligne correct : regarder l'en-tête du chunk @@ (par ex. @@ -19,10 +19,9 @@). Le +19 signifie que le nouveau fichier commence à la ligne 19. Compter vers le bas à partir de là pour chaque ligne qui est une ligne de contexte (`) ou une ligne ajoutée (+). Ignorer les lignes supprimées (-`) - elles n'existent pas dans le nouveau fichier.

Exemple : si un chunk dit @@ -10,5 +10,6 @@ et vous voulez commenter la 3e ligne non supprimée dans ce chunk, le numéro de ligne est 10 + 2 = 12.

Ne jamais deviner les numéros de ligne. Toujours les calculer à partir des en-têtes de chunk.

Validation de cohérence

Avant de suggérer une modification à un motif (dénomination, structure, style), vérifier si le même motif est utilisé ailleurs dans la base de code ou dans des nœuds/fichiers similaires. Si c'est une convention établie, NE PAS le signaler. Commenter seulement si quelque chose dévie vraiment des motifs existants.

Règles de formatage

• Ne jamais utiliser de tirets longs ou de tirets cadratin. Utiliser - à la place.
• Garder les commentaires aussi courts que possible. Une phrase est idéale.
• Pour les commentaires de ligne, éviter les remplissages comme « Beau travail ! », « Ça a l'air super ! », ou « Bon travail ici. » - garder ceux-ci actionnables ou questionnants.

Ton

Écrire les commentaires d'examen naturellement, comme un examinateur humain sympathique.

N'hésiter pas à utiliser des phrases comme :

• Et si...
• Je me demande si...
• WDYT ?

Vous pouvez aussi insérer un emoji de temps en temps 🙂

Garder les commentaires sympathiques, courts et collaboratifs. Éviter le ton moralisateur comme « vous avez fait une erreur » ou quelque chose d'excessivement critique.

Important

Ne pas modifiez le code à moins que l'utilisateur ne vous le demande explicitement. Cette compétence produit un examen, pas un patch.

La toute dernière phrase de votre réponse doit être un lien Markdown cliquable vers le fichier d'examen, pour que l'utilisateur puisse l'ouvrir immédiatement depuis le chat de l'agent. Utiliser ce format : [tmp/review-<repo>-<number>.md](tmp/review-<repo>-<number>.md). Rien ne doit venir après le lien.