Extraction GitHub (DSH)

Que fait Extraction GitHub (DSH) ?

Le problème que cette compétence résout

Un utilisateur envoie un lien GitHub. En général, il ne veut pas un tas de fichiers, mais comprendre trois choses :

1. À quoi sert ce projet ?
2. Que cherche à résoudre cette modification ?
3. Pourquoi cette approche a-t-elle été choisie ?

Les fichiers, les diffs, les métadonnées ne sont que des preuves. Livrer les preuves comme conclusion, ce n'est pas extraire — le lecteur se retrouve avec un tableau sans pouvoir expliquer la raison d'être du dépôt.

Critère de complétude (en une phrase) : Une personne qui n'a jamais entendu parler de ce dépôt doit être capable, après avoir lu les 300 premiers mots, de reformuler dans ses propres mots « ce qu'il résout, ce qui a changé, et pourquoi ce changement ». Si ce n'est pas le cas, l'extraction n'est pas terminée.

Étape 0 : Lire d'abord le « projet », puis la « page »

Avant de récupérer une PR / issue, il faut d'abord comprendre le contenant. Sauter cette étape, c'est écrire dans le vide.

Question à répondre	Où la lire
Quel est ce projet ?	description du dépôt, topics, début du README
Quel vide comble-t-il / que remplace-t-il ?	Colonne « Pourquoi » de chaque package dans le README
Qui l'utilise, dans quel contexte ?	Section Install / Usage / Develop du README
Où se situe cette modification ?	Branche de base de la PR, rôle du package modifié dans la liste

Les monorepos / collections de plugins sont particulièrement importants : il faut d'abord dresser une correspondance « nom du package → responsabilité en une phrase », sinon le lecteur ne peut pas situer la modification. Si le README utilise beaucoup de jargon (ex. "lifecycle hooks", "ctx.web seam"), traduisez-le d'abord en langage simple, avant d'entrer dans le vif du sujet.

Étape 1 : Identifier le type d'URL

Forme de l'URL	Type	Source de données principale
github.com/{o}/{r}	dépôt	/readme + git/trees?recursive=1
…/issues/{n}	issue	issues/{n}
…/pull/{n}	PR	pulls/{n} + pulls/{n}/files + pull/{n}.diff
…/commit/{sha}	commit	commits/{sha}
…/blob/{ref}/{path}	fichier	contents/{path}?ref={ref} (base64)

#1 est un fragment, pas un chemin. Les issues et les PR partagent le même espace de numérotation : si /issues/1 redirige (302) vers /pull/1, alors c'est une PR, et il faut le dire explicitement.

Étape 2 : Récupérer le texte complet via l'API, ne pas lutter contre le HTML

• Le HTML d'une page ne donne que la barre de navigation et un contenu tronqué. Pour le corps du texte, utilisez toujours api.github.com.
• Pour le patch, utilisez patch-diff.githubusercontent.com/raw/{o}/{r}/pull/{n}.diff (github.com/.../pull/n.diff fait une redirection inter-domaines, il faut se connecter directement à l'URL finale).
• raw.githubusercontent.com est souvent indisponible. Utilisez plutôt le décodage local du base64 de contents.
• Si la commande git / curl locale émet une erreur TLS SEC_E_NO_CREDENTIALS, ne réparez pas le shell, utilisez web_fetch du harness. Ne considérez pas un « échec de clone » comme un blocage de la tâche.

Étape 3 : Vérification croisée

additions/deletions/changed_files ↔ liste des files ↔ les hunk du .diff ; le SHA de la tête de la PR ↔ la référence du patch ; merged ne peut pas être déduit uniquement de state=closed. En cas d'incohérence, continuez à chercher (souvent dû à la pagination ou à un ancien patch). Ne rédigez pas un résultat contradictoire.

Étape 4 : Organiser en un résultat « lisible »

L'ordre est impératif : l'explication d'abord, les preuves ensuite. Le lecteur ne doit pas avoir à parcourir 200 lignes de tableau pour comprendre de quoi il s'agit.

1. Ce que c'est (150–300 mots, en langage simple) — La raison d'être du projet, le vide qu'il comble. Le premier terme technique doit être expliqué en une phrase : hookkit = transformer le fait d'« écrire un plugin pour accrocher des hooks de cycle de vie » en « écrire un fichier YAML ».
2. Ce que cette modification cherche à résoudre — Écrivez sous forme de comparaison « avant → après », n'utilisez pas une liste de fichiers comme explication.
3. Pourquoi cette approche — Extrayez de la description de la PR / du message de commit les compromis et la chaîne de causalité (pourquoi ne pas utiliser un déclencheur push, pourquoi considérer le registre comme un état).
4. Liste des modifications — Tableau : fichier / état / ajouts-suppressions / rôle en une phrase.
5. Texte original — Description de la PR, message de commit, cités textuellement, sans réécriture.
6. Contenu complet — Texte intégral de chaque fichier, sans « …le reste est omis ».
7. Pratiques transférables — Ne gardez que ce que le lecteur pourra vraiment réutiliser la prochaine fois.
8. Vérification et couverture — Placez en annexe : résultat de git apply --check, comparaison des SHA de blob, ce qui n'a pas été récupéré.

Règles d'écriture

• Conclusion d'abord : la première phrase de chaque paragraphe est la conclusion, le reste est l'argumentation.
• Les tableaux ne portent pas la charge de l'explication. Tout ce qui est « qu'est-ce que c'est » ou « pourquoi » doit être écrit en phrases complètes.
• N'utilisez pas un nom de fichier comme description fonctionnelle : « a modifié publish.yml » ❌ ; « a ajouté un workflow de publication manuelle, ne publie que sur bouton, par défaut simulation uniquement » ✅.
• Les chiffres doivent pouvoir être tracés jusqu'à leur source, mais ne placez pas les journaux de vérification au début.
• Écrivez dans la langue de l'utilisateur.
• Anti-patrons : accumulation de grands tableaux, copier-coller de diffs fichier par fichier comme corps du texte, commencer par les métadonnées, jargon non expliqué.

Étape 5 : Auto-vérification

• En lisant uniquement les 300 premiers mots (hors titres), peut-on répondre à « quoi / qu'est-ce qui a changé / pourquoi ce changement » ? Sinon, réécrivez.
• Y a-t-il des termes non expliqués ?
• Avez-vous présenté « les fichiers A, B, C ont changé » comme une explication de la modification ?
• Le patch passe-t-il le git apply --check ? Si non, mentionnez explicitement « non vérifié ».

Modes d'échec

Symptôme	Cause	Traitement
Le texte se coupe en plein milieu	Récupération du HTML	Utilisez l'API
404 sur raw.githubusercontent	Liste blanche réseau	Décodez le base64 de contents
403 limite de débit	Boucle non authentifiée	Par lots, ralentissez, signalez honnêtement les lacunes
cross-origin redirect not followed	Redirection .diff	Connectez-vous directement à patch-diff…
Le nombre de fichiers ne correspond pas à changed_files	Pagination	Récupérez avec ?per_page=100
L'utilisateur dit « je n'ai pas compris »	Seulement des preuves, pas d'explication	Revenez aux sections 1–3 de l'étape 4 et réécrivez

Limites

Priorité : instruction explicite de l'utilisateur > contraintes de cette section > comportement par défaut prudent.

Par défaut, extraction uniquement du contenu, pas de clone / build / install / exécution de tests. Pour un dépôt privé, demandez un token à l'utilisateur, n'en inventez pas. Si le dépôt est archivé, mentionnez-le — le contenu reste extractible, mais l'état influence l'interprétation.

Situations où il faut s'arrêter et demander (et non élargir ses droits)

• L'utilisateur dit « installe-le / exécute-le » mais l'objet est le dépôt de quelqu'un d'autre, ou cela modifie l'environnement global : confirmez d'abord le périmètre et le mode de retour en arrière.
• L'instruction est ambiguë (ex. « traite ce dépôt ») : proposez un plan par défaut + une phrase de confirmation, ne devinez pas.
• L'action est irréversible ou peut modifier l'environnement de l'utilisateur (pnpm install, packages globaux, modification de profil, soumission de PR, push, suppression de fichiers) : demandez toujours d'abord.
• Des identifiants sont nécessaires (dépôt privé, token, clé SSH) : demandez une fois ; si obtenu, utilisez-le ; sinon, ne sortez que les éléments vérifiables publiquement, et indiquez ce qui manque.

Cas où l'on peut assouplir les règles

• Le dépôt est celui de l'utilisateur, et il a explicitement dit « fais ce que tu veux / installe directement / ne demande pas » ;
• Ou l'action est effectuée dans un répertoire temporaire, sans toucher au dépôt d'origine ni à l'état global (dans ce cas, l'assouplissement porte uniquement sur « l'écriture », pas sur « l'exécution de code non fiable »).

En cas d'assouplissement, ajoutez à la fin du résultat une phrase comme « J'ai exécuté X selon votre autorisation », pour que le dépassement soit visible et réversible.