Annotation de revue de code

Nouveau dans la v2.4.0

Évaluer les modifications de code produites par des agents de coding IA demande plus qu'un jugement binaire réussite/échec. Chercheurs et équipes d'ingénierie ont besoin d'apprécier la qualité du code à plusieurs granularités : une ligne isolée peut contenir un bug ou une entorse au style, un fichier entier peut être modifié à bon escient ou l'être pour rien, et l'ensemble des changements peut résoudre le problème tout en créant de la dette technique. C'est le déroulé que suivent les relecteurs humains quand ils relisent des pull requests sur GitHub.

Le mode d'annotation de revue de code de Potato fait entrer l'expérience de revue de PR GitHub dans l'évaluation d'agents. Les annotateurs voient des diffs unifiés pour chaque fichier modifié par l'agent. Ils peuvent cliquer sur n'importe quelle ligne du diff pour laisser un commentaire en ligne assorti d'une catégorie. Chaque fichier reçoit une note de justesse et une note de qualité. L'annotateur rend un verdict final : approuver, demander des modifications ou commenter seulement. Tout cela est consigné dans des données d'annotation structurées, prêtes pour l'entraînement de modèles de qualité de code.

Commentaires en ligne

Les annotateurs cliquent sur une ligne du diff pour ouvrir un formulaire de commentaire en ligne. Chaque commentaire porte une catégorie, une gravité et un contenu en texte libre. Le commentaire apparaît ancré à la ligne concernée, comme les commentaires de revue de PR sur GitHub.

Catégories de commentaires

Les catégories de commentaires par défaut couvrent les types de retour les plus courants en revue de code :

Configuration

annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Click any diff line to add an inline comment"
 
    # Categories offered on each inline comment
    comment_categories:
      - bug
      - logic
      - security
      - performance
      - style
      - suggestion
      - question

Modifications de code suggérées

Quand allow_suggestions est activé, les annotateurs peuvent proposer un remplacement pour le bloc de code qu'ils commentent. Cela reprend la fonction « suggestion » de GitHub. La suggestion apparaît dans un bloc de code sous le commentaire et peut servir à entraîner des modèles de réparation de code.

# In inline comment output:
{
  "file": "src/parser.py",
  "line_start": 42,
  "line_end": 44,
  "category": "bug",
  "severity": "critical",
  "comment": "Off-by-one error: range should be inclusive of end",
  "suggestion": "for i in range(start, end + 1):\n    process(tokens[i])"
}

Notes par fichier

Chaque fichier modifié par l'agent reçoit deux notes indépendantes : la justesse et la qualité du code.

Configuration

annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Rate each modified file"
 
    # One 1-5 rating per dimension, per file touched by the diff
    file_rating_dimensions:
      - correctness
      - quality

Format de sortie

{
  "file_ratings": {
    "src/parser.py": {
      "correctness": 4,
      "quality": 3
    },
    "tests/test_parser.py": {
      "correctness": 5,
      "quality": 4
    },
    "src/utils.py": {
      "correctness": 2,
      "quality": 2
    }
  }
}

Verdict global

Après avoir relu tous les fichiers et laissé ses commentaires en ligne, l'annotateur rend un verdict global sur l'ensemble des changements.

Configuration

annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Give an overall verdict on the code changes"
 
    verdict_options:
      - approve
      - request_changes
      - comment_only

Référence de configuration

Voici une configuration complète pour une tâche d'annotation de revue de code :

task_name: "Coding Agent Code Review"
task_dir: "."
 
data_files:
  - "data/coding_traces.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified
    diff_context_lines: 5
    syntax_highlight: true
    show_line_numbers: true
    terminal_theme: dark
    file_tree:
      enabled: true
      position: left
      show_operation_icons: true
      click_to_navigate: true
 
annotation_schemes:
  # Inline comments, file ratings and the overall verdict are all one scheme
  - annotation_type: code_review
    name: review
    description: "Review the agent's code changes"
    comment_categories:
      - bug
      - logic
      - security
      - performance
      - style
      - suggestion
      - question
      - praise
    file_rating_dimensions:
      - correctness
      - quality
    verdict_options:
      - approve
      - request_changes
      - comment_only
 
  # A free-text summary is a separate scheme
  - annotation_type: text
    name: summary
    description: "Summarize your review"
    rows: 4
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Le déroulé de l'annotation

Voici ce que voient et font les annotateurs pendant une tâche d'annotation de revue de code :

1. Vue d'ensemble de la tâche : la description de la tâche apparaît en haut et montre ce qui a été demandé à l'agent (par exemple, « Corriger le test en échec dans test_parser.py »).

2. Navigation dans l'arborescence : la barre latérale de gauche liste tous les fichiers touchés par l'agent. Les fichiers ont un code couleur : vert pour les nouveaux fichiers, jaune pour les fichiers modifiés, rouge pour les fichiers supprimés.

3. Relecture des diffs : le panneau principal affiche les diffs unifiés de chaque fichier. Les annotateurs les parcourent et lisent chaque changement.

4. Ajout de commentaires en ligne : cliquer sur un numéro de ligne ouvre un formulaire de commentaire. L'annotateur choisit une catégorie (bug, suggestion, etc.), éventuellement une gravité, rédige son commentaire et peut y joindre une suggestion de code.

5. Notes par fichier : après avoir relu le diff de chaque fichier, l'annotateur le note sur la justesse (1-5) et la qualité du code (1-5) à l'aide des widgets de notation placés sous le diff du fichier.

6. Verdict global : en bas, l'annotateur choisit un verdict (approuver, demander des modifications ou commenter seulement) et rédige un résumé de sa revue.

7. Envoi : l'annotateur clique sur « Submit » pour enregistrer les commentaires en ligne, les notes par fichier et le verdict comme un seul enregistrement d'annotation.

Format des données

La sortie complète d'une annotation de revue de code :

{
  "id": "trace_042",
  "annotator": "reviewer_01",
  "timestamp": "2025-01-15T14:30:00Z",
  "annotations": {
    "inline_comments": [
      {
        "file": "src/parser.py",
        "line_start": 42,
        "line_end": 42,
        "category": "bug",
        "severity": "critical",
        "comment": "This will throw IndexError when tokens list is empty",
        "suggestion": "if tokens:\n    return tokens[0]\nreturn None"
      },
      {
        "file": "src/parser.py",
        "line_start": 15,
        "line_end": 15,
        "category": "style",
        "severity": "nit",
        "comment": "Variable name 'x' is not descriptive"
      },
      {
        "file": "tests/test_parser.py",
        "line_start": 28,
        "line_end": 30,
        "category": "praise",
        "comment": "Good edge case coverage for empty input"
      }
    ],
    "file_ratings": {
      "src/parser.py": { "correctness": 3, "quality": 2 },
      "tests/test_parser.py": { "correctness": 5, "quality": 4 }
    },
    "verdict": {
      "decision": "request_changes",
      "summary": "The core fix is on the right track but has an edge case bug with empty input. The test coverage is good. Fix the IndexError and clean up variable naming."
    }
  }
}

Exportation

Les annotations de revue de code s'exportent dans plusieurs formats :

# Export as structured code review JSON
python -m potato.export \
  -i output/ \
  -f code_review \
  -o results/reviews.jsonl
 
# Export inline comments only (for training code comment models)
python -m potato.export \
  -i output/ \
  -f code_review_comments \
  -o results/comments.jsonl
 
# Export file ratings as a CSV (for analysis)
python -m potato.export \
  -i output/ \
  -f code_review_file_ratings \
  -o results/file_ratings.csv
 
# Export verdict distribution summary
python -m potato.export \
  -i output/ \
  -f code_review_verdicts \
  -o results/verdicts.json

Le format code_review_comments est particulièrement utile pour entraîner des modèles qui génèrent des commentaires de revue de code ou qui prédisent l'emplacement et la catégorie des problèmes.

Voir aussi

• Annotation d'agent de coding -- afficher des traces d'agents de coding avec rendu des diffs et arborescences de fichiers
• Annotation de récompense de processus -- signaux de récompense par étape pour l'entraînement de PRM
• Observation d'un agent de coding en direct -- observer des agents de coding en temps réel et interagir avec eux
• Annotation agentique -- annotation générale de traces d'agents
• Formats d'exportation -- tous les formats d'exportation pris en charge

Pour les détails d'implémentation, consultez la documentation source.