codesight : cartographier un dépôt pour les assistants de code, sans appel LLM

Le problème visé : un assistant qui redécouvre le dépôt à chaque session

Un assistant de code démarre souvent une conversation sans savoir où se trouvent les routes, les modèles ou la couche d'authentification. Il lit des fichiers un par un, puis reconstruit mentalement une architecture déjà écrite dans le dépôt. Le README de codesight chiffre ce gaspillage : environ 12 000 tokens pour répondre à une question comme « comment fonctionne l'authentification », parce que l'assistant ouvre huit fichiers ou plus. codesight se présente comme la réponse à ce coût de redécouverte. La cible est l'équipe qui utilise Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Windsurf, Cline ou Aider, et qui veut fournir à l'outil un résumé stable du dépôt plutôt que de laisser l'assistant explorer au hasard. Le paquet s'installe par npx, sans clé d'API ni fichier de configuration initial, ce qui abaisse la barrière d'entrée. Le projet est écrit en TypeScript, publié sous licence MIT, et la branche par défaut est main.

Comment le contexte est fabriqué : AST pour TypeScript, expressions régulières ailleurs

La mécanique repose sur deux moteurs distincts. Pour TypeScript, le README annonce une précision AST complète. Pour JavaScript, Python, Go, Ruby, Elixir, Java, Kotlin, Rust, PHP, Dart, Swift, C# et BrightScript, la détection passe par des expressions régulières appliquées aux mêmes détecteurs de frameworks. Cette asymétrie est le point le plus important du projet. Un AST comprend la structure du code, une expression régulière reconnaît des motifs textuels. Sur un projet TypeScript, la carte produite devrait donc refléter les imports, les exports et les relations entre fichiers. Sur un projet Python ou Go, le résultat dépend de la régularité du code : une convention inhabituelle peut passer inaperçue. Le README mentionne 30 détecteurs de frameworks et 14 analyseurs d'ORM, sans détailler lesquels. Il existe une option --native-ast présentée comme un opt-in vers des plugins AST pour davantage de langages, documentée dans docs/wasm-plugins.md. Autrement dit, la précision multi-langages est un chantier ouvert, pas un acquis. Le mode wiki ajoute une couche narrative : les articles sont compilés depuis l'AST, sans appel LLM, et le README cite le « LLM wiki pattern » de Karpathy comme inspiration tout en précisant que la compilation est structurelle. Le fichier .codesight/wiki/log.md conserve un journal des opérations, ce qui rend les régénérations traçables.

Mise en route : une commande, puis des modes optionnels

L'installation tient en une ligne, à exécuter à la racine du dépôt : npx codesight. Aucune configuration n'est requise selon le README. Les modes se découvrent ensuite par des drapeaux. npx codesight --init génère CLAUDE.md, .cursorrules, codex.md et AGENTS.md, c'est-à-dire les fichiers que lisent les assistants concernés. npx codesight --wiki produit un dossier .codesight/wiki/ contenant index.md, overview.md, puis des articles thématiques comme auth.md, payments.md, database.md, users.md, ui.md et log.md. Le README indique que index.md fait environ 200 tokens et overview.md environ 500, et recommande de lire index.md au démarrage de session. npx codesight --mcp démarre un serveur MCP exposant 14 outils, dont trois dédiés au wiki : codesight_get_wiki_index, codesight_get_wiki_article et codesight_lint_wiki. npx codesight --blast src/lib/db.ts affiche le rayon d'impact d'un fichier. npx codesight --profile claude-code produit une configuration optimisée pour un outil précis. npx codesight --benchmark détaille les économies de tokens. npx codesight --open ouvre un rapport HTML. Le mode connaissance se lance par npx codesight --mode knowledge, éventuellement suivi d'un chemin comme ~/vault ou ./docs, et écrit .codesight/KNOWLEDGE.md. La mise à jour du wiki en continu passe par --watch, et --hook régénère à chaque commit. Ces deux derniers drapeaux sont mentionnés sans détail d'implémentation dans le README.

Le wiki comme couche de lecture ciblée

L'intérêt du wiki tient à la granularité. Au lieu de charger une carte complète d'environ 5 000 tokens à chaque conversation, l'assistant lit un article correspondant à la question. Le README donne trois ordres de grandeur : environ 300 tokens pour auth.md contre environ 12 000 pour une exploration fichier par fichier, environ 400 tokens pour database.md contre environ 5 000 pour CODESIGHT.md, et environ 200 tokens pour index.md au démarrage d'une nouvelle session contre environ 5 000 pour un rechargement complet. Ces chiffres proviennent du projet et n'ont pas été reproduits ici. Ils décrivent un ordre de grandeur plausible si la carte complète est effectivement évitée, mais ils dépendent de la taille du dépôt et de la discipline de l'assistant à consulter l'index avant d'ouvrir des fichiers. Le wiki est versionné dans .codesight/wiki/ et committé, ce qui signifie qu'il devient un artefact partagé : une régénération produit un diff relisible, et une carte obsolète peut induire l'assistant en erreur si personne ne relance la génération. L'outil codesight_lint_wiki existe précisément pour signaler articles orphelins, liens croisés manquants et contenu périmé, ce qui suggère que le projet anticipe cette dérive.

Mode connaissance : cartographier les décisions, pas seulement le code

Le mode connaissance étend la même logique aux fichiers markdown. Il scanne un répertoire, par défaut le répertoire courant, ou un coffre Obsidian, ou un dossier de documentation, et produit .codesight/KNOWLEDGE.md. Le README montre un en-tête de sortie avec un décompte : 47 notes, 12 décisions, 8 questions ouvertes, sur une plage de dates. Les décisions sont listées avec leur date et leur justification, par exemple un choix de prestataire de paiement plutôt qu'un autre. Cette partie est la plus intéressante conceptuellement, parce qu'elle traite les décisions d'architecture et les comptes rendus de réunion comme du contexte de première classe. La limite est évidente : le classement d'une note comme décision, question ouverte ou simple documentation repose sur une analyse de texte, et le README ne décrit pas la méthode. Sur un coffre Obsidian désordonné, la sortie peut mélanger des notes personnelles et des décisions d'équipe. Il faut lire le KNOWLEDGE.md produit avant de le committer.

Ce que le README ne permet pas de vérifier

Plusieurs points restent ouverts. Le dépôt ne fournit aucune release publiée au moment de la consultation, ce qui rend difficile le suivi des changements entre versions. Les numéros de version cités dans le README (1.6.2 pour le wiki, 1.9.3 pour le mode connaissance) suggèrent un rythme de publication rapide, mais sans notes de version accessibles, la compatibilité entre versions n'est pas documentée. Le README affirme 149 tests et une validation sur 25 projets open source dans 14 langages, sans indiquer comment ces projets ont été choisis ni quels résultats ont été obtenus. Ces éléments ne constituent pas une preuve de qualité. Le nombre de téléchargements mis en avant ne dit rien non plus de la robustesse sur un dépôt donné. Le support de BrightScript et BrighterScript pour Roku est un signe que le projet vise des niches, mais il renforce aussi la question de la maintenance : chaque langage ajouté par expressions régulières est une surface de test supplémentaire. La licence MIT couvre le code de l'outil ; elle ne dit rien du contenu généré, qui reste soumis aux règles de votre dépôt.

Alternatives et différence d'approche

L'alternative la plus directe est un outil de cartographie par serveur de langage, qui s'appuie sur un index sémantique maintenu par un compilateur ou un serveur dédié. La différence est structurelle : un serveur de langage connaît les types et les références de manière fiable pour les langages qu'il supporte, mais il faut l'installer et le maintenir par langage, et il n'écrit pas de fichier de contexte lisible par un assistant. codesight fait l'inverse : un seul binaire Node.js, zéro dépendance annoncée, un fichier markdown en sortie, et une couverture large obtenue en acceptant une détection moins précise hors TypeScript. Une autre alternative consiste à écrire et maintenir à la main un fichier CLAUDE.md ou AGENTS.md. C'est plus fiable sur le fond, parce qu'un humain décrit l'architecture qu'il connaît, mais cela devient obsolète dès que le dépôt bouge, et personne ne met à jour ce fichier avec plaisir. Le mode --watch et le drapeau --hook de codesight visent précisément ce point faible. Le compromis est clair : automatisation et fraîcheur contre exactitude garantie.

Coût de maintenance et implications de licence

Le coût de maintenance se répartit en deux postes. Le premier est la régénération : si vous committez .codesight/wiki/, chaque changement de structure produit un diff, et le README propose --watch ou --hook pour l'automatiser. Sans cette automatisation, le wiki se périme et l'assistant travaille sur une carte fausse, ce qui est pire que pas de carte du tout. Le second poste est la montée de version : le projet évolue vite, avec des fonctionnalités ajoutées par version mineure, et l'absence de releases publiées complique le suivi. La licence MIT autorise l'usage commercial, la modification et la redistribution, avec conservation de la mention de copyright et de la licence. Elle ne impose aucune obligation sur les fichiers générés, qui décrivent votre propre dépôt. Le README mentionne des projets liés du même auteur, ultraship et claude-rank, ce qui indique un ensemble d'outils autour de Claude Code plutôt qu'un projet isolé. Pour un dépôt TypeScript, l'adoption se teste en une commande et se révoque en supprimant .codesight/. Pour les autres langages, la décision dépend de la qualité de la détection sur vos fichiers réels, et cette vérification ne peut pas être déléguée au README.

Conclusion éditoriale

codesight convient aux dépôts TypeScript et JavaScript, où l'analyse AST est annoncée comme complète, ainsi qu'aux équipes qui veulent un contexte de codebase reproductible sans appel à un LLM externe. Les projets Python, Go, Ruby ou Rust doivent d'abord vérifier la qualité de la détection par expressions régulières sur leurs propres fichiers avant de committer le résultat. Ce qu'il faut contrôler en premier : lancer npx codesight --benchmark pour comparer le nombre de tokens annoncé avec ce que votre assistant consomme réellement, puis npx codesight --blast sur un fichier central pour juger si le graphe de dépendances correspond à votre architecture. Le paquet reste sous licence MIT, donc la réutilisation du code généré ne pose pas de question de licence, mais le contenu produit reflète votre dépôt et doit être relu comme n'importe quel fichier versionné.

Sources officielles

1. Houseofmvps/codesight on GitHub
2. Issues
3. License: MIT
4. Project website
5. README