ultraindex — construire et naviguer dans une encyclopédie analysée par IA de l'ensemble d'un dépôt
Sur un dépôt volumineux, la fenêtre de contexte se sature avant que vous trouviez ce qui compte.
ultraindex corrige cela par une division du travail : le moteur déterministe
sans dépendance (node scripts/ultraindex.mjs <commande> — pas de
npm install, pas de clés API, lancez --help pour la surface complète) effectue le travail
mécanique — scanner le projet, construire le graphe de liens, organiser
l'encyclopédie ; vous faites la compréhension — une analyse fondée et citée —
et naviguez ensuite dans le résultat au lieu de lire le dépôt.
Les règles fondamentales :
- Le moteur possède la vue code et le graphe (régions
ui:gen) — régénérées à chaque construction ; ne les modifiez jamais à la main.- Vous possédez la vue métier (régions
ui:human).buildpréserve votre prose lors des reconstructions et des renommages.- Analysez à partir de preuves, pas de mémoire. Rédigez l'analyse uniquement à partir des sources réelles que
dossiervous montre, citez-les[fichier:ligne], etcheckéchoue sur toute citation qui ne résout pas — donc ne devinez pas.- Chargez le minimum. Lisez une entrée (ou un
dossier) à la fois — c'est le schéma prévu, et exactement ce que fait un sous-agent d'enrichissement par module. Ne chargez jamais en massegraph.jsonou tout le répertoireencyclopedia/dans le contexte — cela va à l'encontre du but.
La plupart des commandes acceptent --json — préférez-le chaque fois que vous
utilisez le résultat pour une branchement plutôt que de le lire comme du texte.
Router selon la situation
Déterminez dans quelle situation vous vous trouvez, dans cet ordre, et lisez la référence correspondante pour le workflow détaillé :
-
Pas encore d'index — aucun
.ultraindex/oudocs/ultraindex/à la racine du dépôt (cherchezgraph.jsonà l'intérieur). Construisez-le, puis enrichissez les modules principaux : lisez references/generate.md. -
L'index existe — vérifiez d'abord sa fraîcheur.
node scripts/ultraindex.mjs check --out <index-dir> --json. S'il signale des éléments obsolètes ou cassés, relancezbuild(votre prose survit), puis continuez. Si seuls des fichiers non pertinents pour la tâche ont changé, vous pouvez procéder et le noter. -
L'utilisateur a une tâche ou une question ("où est X", "comment fonctionne Z", "quels fichiers dois-je modifier") — naviguez dans l'index, ouvrez uniquement les fichiers qu'il pointe, fondez les réponses avec des citations vérifiées : lisez references/navigate.md.
-
La réponse doit être hautement fiable (audit, sécurité, affirmation critique pour l'exactitude), ou l'utilisateur vous demande de vérifier/trancher une réponse — après que
check --answera réussi (les citations résolvent), escaladez vers la porte de vérification sémantique pour que chaque extrait cité soit prouvé comme soutenant son affirmation, et non simplement existant : lisez references/verify.md. -
L'utilisateur a demandé d'indexer/analyser/documenter, ou
status --jsonmontre des hubs non enrichis et vous avez du budget — exécutez la boucle d'enrichissement pilotée par le statut (dossier → écrire une analyse citée → check). Sur un gros dépôt, cela se parallélise : un sous-agent par module depuis la file d'attente, si votre hôte supporte les sous-agents — lisez references/generate.md. -
findne trouve rien, ou l'utilisateur veut une meilleure recherche (sémantique) — mettez en place la couche d'embeddings optionnelle (docker compose,embed,findhybride) : lisez references/semantic.md.
Une première visite typique enchaîne 1 → 5 → 3 ; une visite de retour est habituellement 2 → 3 ; une réponse hautement fiable ajoute → 4.
Aide-mémoire des commandes
build --repo <dossier> [--out .ultraindex] [--include/--exclude <glob>] [--max-bytes <n>] [--max-files <n>] [--no-cache] [--no-mermaid]— scanner et (ré)écrire l'index. Idempotent ; conserve la prose enrichie. Incrémental (réutilise l'extraction des fichiers inchangés) ; avertit si--max-filestronque.--out docs/ultraindexpour un index commité et révisable par PR.map [--module <slug>] [--json]— afficher INDEX.md (ou une entrée, ou la table des modules).find "<requête>" [--k <n>]— classer les modules, afficher les fichiers exacts à ouvrir. Lexical par défaut (avec pondération IDF) ; hybride (+ sémantique) quand vectors.json existe.neighbors <fichier|module> [--depth <n>]— ce qui pointe vers / depuis lui.symbols "<nom>" [--json]— où un symbole est défini (fichier:ligne, type, module propriétaire) et quels fichiers le référencent. Flou par sous-jeton d'identifiant.impact <fichier|module> [--depth <n>] [--json]— la fermeture des dépendances inverses : tout ce qui importe ou utilise la cible. "Ce qui casse si je modifie ceci."status— la file d'attente d'enrichissement, dans l'ordre exact à enrichir.dossier <slug>— le paquet de preuves d'un module (code source réel + voisins ; un module de docs/config uniquement, e.g.root, n'affiche pas de code — enrichissez-le en citant son README/config à la place).ask "<question>"— assembler des preuves fondées pour répondre.check [--answer <fichier>] [--semantic]— fraîcheur + intégrité + fondement (les citations doivent résoudre). Code de sortie non nul ⇒ obsolète, cassé ou non fondé.--semanticintègre également la porte de vérification (échoue sur une affirmation dont l'extrait cité la réfute, ou qui est entièrement tranchée sans support) ; il réduit le verdict à partir desverdicts[]bruts et relit chaque extrait tranché depuis le dépôt réel — un résumé falsifié ou une source modifiée échoue, jamais ne passe.verify --answer <fichier> [--apply <verdicts.json>] [--max-verify <n>]— la porte de haute assurance au-dessus decheck --answer: émet une liste de travail affirmation↔citation pour une vérification contradictoire, puis--applyréduit vos verdicts en une porte passe/échoue. Voir references/verify.md.embed [--force]— construire/rafraîchir vectors.json pour la recherchefindsémantique (nécessite un fournisseur — voir references/semantic.md).
Notes de périmètre
- Pas de clés, pas de réseau, déterministe (la couche sémantique optionnelle est la
seule exception, et elle dégrade vers lexicale quand son fournisseur est absent). Deux
constructions d'un dépôt inchangé sont identiques octet pour octet sauf pour
manifest.json'sbuiltAt(horodatage de provenance) ;vectors.jsonest également exclu (ses flottants dépendent du fournisseur). - Symboles AST exacts grâce aux grammaires tree-sitter embarquées pour JS/TS/TSX,
Python, Go, Rust, Java, C, C++, C#, Ruby, PHP — imbrication réelle, types précis,
export structuré. Les autres langages utilisent des extracteurs regex (restent
recherchables). Les grammaires wasm sont livrées dans le bundle, donc toujours pas de
npm installau moment de l'utilisation du skill (l'installation est plus lourde — ~17 MiB de wasm). - Arêtes d'import pour JS/TS (tsconfig
paths, packageexportsmaps), Python, Go (multi-module +replace), Rust (mod/use), Java (packages), C/C++ (#include "..."), Ruby (require_relative/require), PHP (composer PSR-4 +requirerelatif), C# (using→namespace). Plus des arêtesusecode→code prudentes quand un fichier référence un symbole exporté unique d'un autre fichier sans l'importer. Les langages restants n'ont pas d'arêtes d'import. Le système de fichiers virtuel de Yarn PnP est hors périmètre (les noms d'espace de travail résolvent quand même). - Les arêtes pendantes indiquent généralement le dépôt lui-même qui a des imports cassés ou des liens de documentation obsolètes — c'est un constat à signaler, pas à dissimuler.