/understand-explain

Fournir une explication détaillée et approfondie d'un composant de code spécifique.

Référence de la structure du graphe

Le graphe de connaissances JSON a cette structure :

• project — {name, description, languages, frameworks, analyzedAt, gitCommitHash}
• nodes[] — chacun avec {id, type, name, filePath?, summary, tags[], complexity, languageNotes?}
  • Types de nœuds de code : file, function, class, module, concept
  • Types de nœuds non-code : config, document, service, table, endpoint, pipeline, schema, resource
  • Types de nœuds domaine/connaissance : domain, flow, step, article, entity, topic, claim, source
  • Les IDs utilisent le type de nœud comme préfixe, ex. file:path, function:path:name, config:path, article:path
• edges[] — chacun avec {source, target, type, direction, weight}
  • Types clés : imports, contains, calls, depends_on, configures, documents, deploys, triggers, contains_flow, flow_step, related, cites
• layers[] — chacun avec {id, name, description, nodeIds[]}
• tour[] — chacun avec {order, title, description, nodeIds[]}

Comment lire efficacement

1. Utilisez Grep pour chercher dans le JSON les entrées pertinentes AVANT de lire le fichier entier
2. Ne lisez que les sections dont vous avez besoin — ne chargez pas le graphe entier en contexte
3. Les noms de nœuds et résumés sont les champs les plus utiles pour comprendre
4. Les edges vous montrent comment les composants se connectent — suivez les imports et appels pour tracer les chaînes de dépendances

Instructions

1. Résolvez le répertoire de données $UA_DIR. Exécutez UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua) — c'est le legacy .understand-anything/ quand il existe déjà, sinon le nouveau .ua/. Vérifiez que $UA_DIR/knowledge-graph.json existe. Si ce n'est pas le cas, demandez à l'utilisateur d'exécuter /understand d'abord.

2. Vérifiez la fraîcheur du graphe avant d'utiliser le contexte dérivé du graphe :

   • Lisez project.gitCommitHash depuis les métadonnées du graphe en tant que GRAPH_COMMIT_RAW. Résolvez-le comme un commit avant de l'utiliser dans tout diff Git, puis comparez-le avec git rev-parse HEAD et inspectez les changements commités et répertoire de travail au niveau du projet depuis la racine du projet :

     GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
     git rev-parse HEAD
     git diff --name-only "$GRAPH_COMMIT" HEAD -- .
     git diff --cached --name-only -- .
     git diff --name-only -- .
     git ls-files --others --exclude-standard -- .

   • Le pathspec -- . est obligatoire : les commits qui ne touchent qu'un projet sibling du monorepo ne doivent pas rendre ce graphe obsolète. Une discordance de hash seule n'est pas obsolète quand le diff du projet est vide.
   • Ignorez le répertoire de données sélectionné (.ua/ ou legacy .understand-anything/) dans la sortie de chaque commande car il contient des artefacts de graphe générés, pas une dérive de source du projet.
   • Si le diff commité ou toute commande répertoire de travail signale des fichiers du projet, avertissez avant d'expliquer que le contexte dérivé du graphe peut omettre ces changements. Suggérez : Exécutez /understand pour rafraîchir le graphe.
   • Exécutez le diff de commit uniquement quand GRAPH_COMMIT_RAW se résout avec succès. Si le commit du graphe ou les métadonnées Git sont manquants, invalides ou indisponibles, donnez un bref avertissement au meilleur effort et continuez plutôt que de bloquer.

3. Trouvez le nœud cible — utilisez Grep pour chercher le graphe de connaissances du composant : "$ARGUMENTS"

   • Pour les chemins de fichiers (ex. src/auth/login.ts) : cherchez les correspondances "filePath"
   • Pour la notation fonction (ex. src/auth/login.ts:verifyToken) : cherchez le nom de fonction dans les champs "name" filtrés par le chemin de fichier
   • Notez l'ID exact du nœud, le type, le summary, les tags, et la complexity

4. Trouvez tous les edges connectés — Grep pour l'ID du nœud cible dans la section edges :

   • Les correspondances "source" → choses que ce nœud appelle/importe/dépend (sortantes)
   • Les correspondances "target" → choses qui appellent/importent/dépendent ce nœud (entrantes)
   • Notez les IDs de nœuds connectés et types d'edges

5. Lisez les nœuds connectés — pour chaque ID de nœud connecté de l'étape 4, Grep pour ces IDs dans la section nodes pour obtenir leur name, summary, et type. Cela construit le voisinage du composant.

6. Identifiez la couche — Grep pour l'ID du nœud cible dans la section "layers" pour trouver la couche architecturale à laquelle il appartient et la description de cette couche.

7. Lisez le fichier source réel — Lisez le fichier source au filePath du nœud pour l'analyse approfondie.

8. Expliquez le composant en contexte :

   • Son rôle dans l'architecture (quelle couche, pourquoi il existe)
   • Structure interne (fonctions, classes qu'il contient — depuis les edges contains)
   • Connexions externes (ce qu'il importe, ce qui l'appelle, ce dont il dépend — depuis les edges)
   • Flux de données (entrées → traitement → sorties — depuis le code source)
   • Expliquez clairement, en supposant que le lecteur peut ne pas connaître le langage de programmation
   • Mettez en évidence les patterns, idiomes, ou complexités qui valent la peine d'être compris