Git Student Analysis Skill

Analyse les contributions Git d'un repo et produit un rapport pédagogique structuré par étudiant.

Ce que ce skill produit

Rapport Markdown : synthèse lisible dans le chat, par étudiant
Fichier Excel : tableau exportable, un onglet résumé + un onglet détail des commits

Étape 0 — Collecter les infos manquantes

Si l'utilisateur n'a pas précisé, demander :

Source : URL GitHub ou chemin local ?
Branche(s) à analyser (défaut : main ou branche par défaut)
Mapping identités : y a-t-il une liste nom/email des étudiants ? (optionnel, améliore le regroupement)
Convention de messages (optionnel, informatif / conversationnel) : message_convention: conventional | free | custom
- Important : ce paramètre n'est pas appliqué automatiquement comme filtre strict ; il sert à cadrer la demande et peut être mentionné dans le rapport. La détection automatique des conventions alternatives et des verbes français est intégrée au scoring.
- conventional (défaut) : valorise Conventional Commits en EN et FR, accepte les conventions alternatives cohérentes
- free : valorise tout message clair et informatif, quelle que soit la convention
- custom : l'enseignant précise sa convention attendue (ex: [TYPE] description, #ref - message) pour contexte

Étape 1 — Préparer le repo

Cas A — URL GitHub fournie

# Clone léger (sans fichiers binaires, historique complet)
git clone --filter=blob:none <URL> /tmp/repo_analyse
cd /tmp/repo_analyse

Si le clone échoue (repo privé, réseau), signaler à l'utilisateur qu'il doit fournir un chemin local cloné manuellement.

Cas B — Chemin local fourni

cd <chemin_fourni>
git fetch --all   # s'assurer d'avoir tous les commits distants

Étape 2 — Extraire les données brutes

Le skill utilise automatiquement un environnement Python isolé (venv) qui est créé au premier lancement. Vous n'avez rien à installer manuellement.

Utiliser le script principal qui gère tout le workflow :

bash scripts/run_analysis.sh <chemin_repo> [<branche>]

Ce script :

Configure automatiquement le venv Python (si nécessaire)
Extrait tous les commits
Analyse et déduplique les auteurs
Génère le rapport Markdown à la racine du repo analysé
Génère le fichier Excel à la racine du repo analysé

Outputs (générés à la racine du projet) :

git-analysis-report-YYYY-MM-DD.md - Rapport Markdown
git-analysis-report-YYYY-MM-DD.xlsx - Fichier Excel

Étape 3 — Regrouper les auteurs (déduplication)

Règle critique : un même étudiant peut avoir poussé avec des noms différents ou des emails différents.

Stratégie de déduplication :

Email non-générique → La clé de regroupement est l'email (peu importe le nom affiché)
- Ex: "John Doe" + "JohnD" avec email john@epitech.eu → fusionnés en 1 seul auteur
- Le nom le plus fréquent parmi les commits est choisi comme nom canonique
- Les noms alternatifs sont listés dans le rapport avec une alerte
Email générique (noreply, etc.) → Grouper par nom normalisé (minuscules, sans accents)
Mapping manuel (mapping.csv) → Priorité absolue : email,nom_canonique

Co-authorship (pair programming) : Le script extract_commits.sh détecte automatiquement les trailers Co-authored-by: dans les messages de commit. Lorsqu'un co-auteur est détecté :

Les statistiques du commit (insertions, deletions) sont également attribuées au co-auteur
Le rapport mentionne explicitement : 🤝 Co-auteur sur N commits (pair programming détecté)
Les commits ne sont comptabilisés qu'une fois dans le total global (row_type=author) ; les lignes row_type=coauthor s'ajoutent sans gonfler total_commits

Signaler dans le rapport :

Les fusions réalisées (noms alternatifs détectés)
Le nom canonique choisi (le plus fréquent)
Les contributions en co-authorship détectées

Étape 4 — Calculer les métriques par étudiant

Métrique	Calcul
Nombre de commits	Count
% de commits	commits_étudiant / total_commits × 100
Lignes ajoutées / supprimées	Somme insertions / deletions
Fichiers modifiés (distincts)	Union des fichiers touchés
Fréquence	commits / durée_projet_jours ; détecter les rushes
Qualité messages	Score 0–3 (voir `references/scoring.md`)
Pertinence modifications	Appréciation qualitative (voir `references/scoring.md`)
Ratio insertions/deletions	si `deletions > 0` : `insertions / deletions` ; si `deletions == 0` : afficher `∞` ou `N/A` et interpréter comme “ajout net, aucune suppression”

Analyse temporelle par phase

Diviser la durée du projet en 3 phases égales (tiers du temps total) et calculer la contribution de chaque étudiant par phase :

Phase	Période	Commits étudiant	% de ses commits	% du total phase
Phase 1 (début)	`date_debut` → `t_plus_1_tiers`	N	X%	Y%
Phase 2 (milieu)	`t_plus_1_tiers` → `t_plus_2_tiers`	N	X%	Y%
Phase 3 (fin)	`t_plus_2_tiers` → `date_fin`	N	X%	Y%

Convention de bornes à préciser explicitement dans le rapport : phase 1 = date_debut <= commit < t_plus_1_tiers, phase 2 = t_plus_1_tiers <= commit < t_plus_2_tiers, phase 3 = t_plus_2_tiers <= commit <= date_fin. Ainsi, un commit horodaté exactement à t_plus_1_tiers appartient à la phase 2, et un commit horodaté exactement à t_plus_2_tiers appartient à la phase 3. Mentionner explicitement dans le rapport les progressions significatives :

Alice : contribution faible en phase 1 (5%), forte en phase 3 (55%) — montée en puissance
Bob : contribution décroissante (40% → 15%) — vérifier la phase 3

Cas où l'analyse temporelle est particulièrement importante :

Étudiant avec peu de commits en global mais progression croissante → peut sous-représenter l'implication réelle
Étudiant avec beaucoup de commits mais uniquement en phase 3 → rush de dernière minute possible

Étape 5 — Générer le rapport Markdown

Le script run_analysis.sh génère automatiquement le rapport à la racine du projet analysé.

Emplacement : <repo_root>/git-analysis-report-YYYY-MM-DD.md

Important : Le générateur actuel commence par le titre du rapport. L'avertissement ci-dessous doit être intégré directement au template et apparaître en tête du contenu du rapport, avant les sections d'analyse détaillées, afin de rester cohérent avec le format réellement produit.

# 📊 Analyse Git — <nom_repo>

## ⚠️ Utilisation responsable de ce rapport
Ce rapport mesure l'activité Git observable, pas la qualité du travail ni l'apprentissage.
- Nombre de commits ≠ impact technique
- Lignes ajoutées ≠ fonctionnalités implémentées
- % de commits ≠ responsabilité du projet
Ne pas utiliser seul pour calculer une note.

## Résumé global
- Total commits : X  |  Période : <début> → <fin>
- Auteurs bruts : N  →  après déduplication : M

## Par étudiant

### 👤 <Prénom Nom> (<email_canonique>)
- Commits : X (Y%)
- Lignes : +Z / -W  |  Fichiers distincts : N
- Ratio insertions/deletions : X.X → [🔧 refactoring probable si ratio < 0.3] [📝 ajout net si ratio > 5.0] (voir `references/scoring.md` pour la grille détaillée)
- Fréquence : régulière / rush fin de projet / absente
- Qualité des messages : ⭐⭐⭐ / ⭐⭐ / ⭐ / ⚠️ inexistants
- Pertinence des modifications : <texte>
- ⚠️ Alertes : ex. "10 commits en 2h avant deadline", "messages vides", "❓ 5 commits consécutifs avec message identique — s'agit-il de 5 changements distincts ?"

[Identités fusionnées : ancien_email → email_canonique]

Patterns suspects à signaler (comme questions, jamais comme accusations) :

Messages identiques sur 3+ commits consécutifs → ❓ X commits avec le même message "..." — ce message décrit-il X changements distincts ?
Micro-commits (< 5 lignes modifiées en série) → ❓ N micro-commits détectés — s'agit-il d'un découpage intentionnel ?
Burst > 10 commits en < 30 minutes → ❓ N commits en M minutes — ce backlog correspond-il à du travail progressif ?

Étape 6 — Générer le fichier Excel

Utiliser openpyxl selon le skill xlsx. Structure du classeur :

Onglet "Résumé" : une ligne par étudiant, toutes métriques, en-têtes colorés
Onglet "Commits" : liste complète, auteur canonique, date, message, score qualité
Onglet "Alertes" : lignes surlignées en orange (commits suspects, étudiants inactifs)

Sauvegarder dans /mnt/user-data/outputs/analyse_git_<nom_repo>_<YYYYMMDD>.xlsx. Recalculer les formules avec scripts/recalc.py si des formules Excel sont utilisées.

Étape 7 — Présenter les résultats

Afficher le rapport Markdown complet dans le chat
Appeler present_files avec le .xlsx
Proposer des actions de suivi :
- Filtrer sur une période précise
- Ajouter un mapping manuel d'identités
- Exporter seulement certains étudiants

Références

references/scoring.md — Grilles de scoring détaillées
scripts/extract_commits.sh — Extraction Git brute
scripts/analyze.py — Analyse, déduplication, métriques
scripts/generate_xlsx.py — Génération du classeur Excel

Cas limites à gérer

Situation	Comportement attendu
Repo vide / 0 commits	Signaler et arrêter
Un seul auteur	Rapport simplifié, pas de %
Merge commits nombreux	Exclure des métriques LOA/count par défaut (évite double comptabilisation). Signaler : "Nombreux merge commits détectés — peut indiquer un workflow par branches (positif) ou des conflits fréquents (à vérifier)"
Commits vides (`--allow-empty`)	Compter + noter en alerte
Réseau bloqué (clone impossible)	Demander chemin local

git-student-analysis