Poltergit : comprendre le code avec une IA locale

Le vrai manque : relier une ligne à ses raisons

Poltergit traite la ligne comme un point d'entrée vers plusieurs niveaux d'historique. Il suit les modifications de cette ligne, regarde les différences introduites par les commits, et, quand c'est possible, relie ces changements à des demandes de fusion, des revues ou des tickets GitHub.

Il y a un point important : le but n'est pas de « deviner » l'intention à partir de l'apparence du code. Le modèle reçoit des éléments issus du dépôt, puis reformule ce qu'on peut étayer. L'objectif est de réduire le temps perdu à reconstituer le contexte, pas de transformer une supposition en décision prouvée.

Un outil d'exploration, pas une documentation magique

Une réponse générée ne remplace ni une documentation de conception, ni une conversation avec les personnes qui connaissent le système. En revanche, ça peut accélérer une première enquête : retrouver le commit pertinent, comprendre le changement associé, puis repérer rapidement là où les traces sont trop faibles.

Le bénéfice dépend donc de la qualité de l'historique. Des messages de commit clairs et des discussions conservées donnent à l'outil plus de matière. Un historique lacunaire le restera, même avec un modèle de langage. La promesse utile n'est pas « l'IA connaît les raisons oubliées », mais « l'IA rend les indices existants plus faciles à retrouver et à examiner ».

Suivre la ligne dans les commits

Le projet s'appuie sur git log -L, qui remonte l'historique d'une ligne ou d'une fonction même quand sa position change dans le fichier. Poltergit récupère les commits concernés, leurs messages et leurs différences. Il travaille sur la révision validée dans HEAD, et il prévient s'il y a des modifications non validées, pour éviter de mélanger le code enregistré et l'état de votre espace de travail.

Concrètement, ça donne un enchaînement assez pragmatique : l'outil commence par les preuves trouvées dans le dépôt, au lieu de demander au modèle d'inventer une explication « de tête ». Et si l'utilisateur l'autorise et que l'accès est configuré, Poltergit peut intégrer aussi le contexte des demandes de fusion, des revues et des tickets liés aux commits.

Demander une réponse qui parle comme le code

Le modèle Gemma 4 E4B, exécuté avec Ollama sur la machine de l'utilisateur, reçoit la ligne, le code autour, et l'historique pertinent. En sortie, il doit produire des affirmations structurées, chacune associée à une source et à une citation exacte, ou alors dire clairement quand le dépôt ne permet pas de conclure.

Faire « parler le code » plutôt que l'auteur est une convention d'interface. Une réponse du type « Mon existence est liée à la prévention d'une tempête de reconnexions » rend l'explication lisible, mais ça ne prétend pas sonder la psychologie de quelqu'un. La citation et le commit restent ce qu'il faut vérifier.

Présenter le silence comme un résultat valide

Dans une démo reproductible, la ligne time.sleep(3) est reliée à un commit expliquant qu'une session fermée restait réservée pendant deux secondes. Le délai de trois secondes devient alors cohérent : une marge avant reconnexion. La réponse pointe ce commit et affiche une citation vérifiée.

À l'inverse, une constante modifiée par un commit nommé « update » peut ne pas fournir assez d'éléments. Dans ce cas, Poltergit indique que l'historique ne dit rien. Lors d'un test, le modèle a tenté de proposer une raison en s'appuyant sur une citation non valide : la validation a rejeté la réponse et a montré les extraits disponibles.

Le projet propose aussi poltergit ofrenda, qui génère un mémorial de fichiers et de fonctions supprimés. Les fiches précisent quand un élément est apparu, combien de temps il a vécu et quel commit l'a retiré. Ce n'est pas une réponse directe à « pourquoi cette ligne existe ? », mais ça donne une vue utile sur le cycle de vie du logiciel et sur la logique des suppressions.

Vérifier les citations avant d'afficher la réponse

Le modèle doit produire des citations d'au moins douze caractères qui correspondent mot pour mot à une source disponible. Le programme vérifie cette correspondance avant d'afficher la réponse. Si une citation ne matche pas, la réponse complète est rejetée et les extraits sont affichés tels quels.

Ce contrôle est plus robuste qu'une simple consigne dans un prompt : il est appliqué par le code. Il garantit que les citations renvoient à des mots réellement présents dans les éléments consultés. Par contre, ça ne garantit pas que l'interprétation de ces mots est juste. Une citation exacte peut soutenir une conclusion trop large, ou ignorer une contrainte présente dans le dépôt. La vérification des sources est donc un garde-fou, pas un certificat de vérité.

Retrouver du contexte au-delà de l'historique direct

Se limiter aux commits qui touchent directement une ligne peut faire passer à côté d'une explication. Dans l'exemple du projet, une boucle de tentatives n'avait été modifiée que lors de l'ajout du client. L'explication utile se trouvait ailleurs : dans un commit qui avait augmenté la valeur maximale de trois à sept.

Pour élargir la recherche, Poltergit peut indexer l'historique avec EmbeddingGemma, puis stocker les vecteurs dans PostgreSQL via pgvector. Une recherche hybride combine similarité vectorielle et recherche plein texte. Les résultats sont fusionnés par classement réciproque, pour équilibrer les passages proches « par le sens » et les correspondances lexicales plus directes.

Cette indexation est distincte du parcours de base. Le modèle peut tourner localement, tandis que le stockage des vecteurs peut utiliser un service distant (Tiger Cloud dans la démonstration). Les périmètres (dépôt, révision, modèle) sont séparés pour éviter de mélanger les historiques. Une équipe doit quand même décider clairement où résident les données d'indexation et quelles règles internes s'appliquent.

Mesurer les lenteurs au lieu de les attribuer au modèle

Le projet instrumente chaque séance avec Sentry : parcours de l'historique, appel au modèle et validation des preuves. D'après l'implémentation décrite, les prompts et le code ne sont pas envoyés ; les traces portent sur des informations opérationnelles comme les durées, le modèle et le nombre de jetons.

Ces mesures ont aidé à distinguer « modèle défaillant » et « modèle lent ». Sur une machine sans GPU, une génération a pris presque trois minutes. Le premier délai d'attente, fixé à 180 secondes, interrompait donc une inférence encore en cours. La trace a permis d'identifier la cause et de rendre le délai configurable. Elle a aussi révélé des spans IA mal rattachés à la transaction et des traces perdues quand la commande se terminait avant leur envoi.

Cette partie rappelle une règle saine pour les projets d'IA : mesurez l'ensemble du parcours. Sans instrumentation, une latence peut sembler venir de Git, du réseau ou du modèle. Mais l'observabilité elle-même doit être configurée avec soin, pour éviter d'inclure du code ou des données sensibles dans les événements envoyés.

Un coût marginal faible, mais une latence à anticiper

L'inférence locale n'entraîne pas de facturation par requête à un fournisseur de modèle. Résultat : une consultation fréquente reste envisageable, surtout pour des équipes qui ne veulent pas transformer chaque question en coût d'API variable.

En contrepartie, la machine doit avoir de quoi tourner, et l'expérience peut être lente sans accélération matérielle. Le coût en argent peut être faible, mais le coût en temps, en ressources et en maintenance ne disparaît pas.

Le projet est distribué sous licence MIT, avec une interface locale, une commande en ligne de commande et un export statique pour les mémoriaux de code supprimé. La démonstration repose sur un dépôt fictif reproductible, ce qui facilite la vérification des réponses. L'approche rend l'expérimentation plus accessible, mais rien ne remplace le test sur vos propres dépôts et vos conventions de sécurité.

Ce que l'outil ne peut pas savoir

Poltergit ne reconstitue pas une intention absente des traces. Un commit trop vague, une revue supprimée ou une discussion tenue hors du dépôt peuvent laisser le modèle sans matière. Et même quand le modèle trouve une explication, des commentaires, des tests ou des changements plus récents peuvent contredire ce qui était vrai au départ.

Une réponse citée doit donc être traitée comme une piste de recherche, pas comme une permission de modifier le comportement.

Avant un déploiement, ça vaut le coup de vérifier :

• quelles données quittent le poste, y compris les embeddings et les événements de télémétrie ;
• comment les droits d'accès aux dépôts et aux discussions sont appliqués ;
• si la latence locale est compatible avec vos usages ;
• si les équipes comprennent qu'une citation exacte ne garantit pas une interprétation exacte.

Poltergit est le plus utile quand il accélère une enquête humaine et montre clairement ses preuves. Il devient plus risqué si ses formulations sont recopiées comme des décisions « définitives », sans retour aux commits et aux discussions d'origine.