/understand-diff

Analysez les modifications de code actuelles par rapport au graphe de connaissances du répertoire de données du projet (.ua/knowledge-graph.json, ou l'ancien .understand-anything/knowledge-graph.json quand ce répertoire est présent).

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 a {id, type, name, filePath?, summary, tags[], complexity, languageNotes?}
  • Types de nœuds 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 en préfixe, p. ex. file:path, function:path:name, config:path, article:path
• edges[] — chacun a {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 a {id, name, description, nodeIds[]}
• tour[] — chacun a {order, title, description, nodeIds[]}

Comment lire efficacement

1. Utilisez Grep pour rechercher dans le JSON les entrées pertinentes AVANT de lire le fichier complet
2. Ne lisez que les sections dont vous avez besoin — ne videz pas le graphe entier en contexte
3. Les noms de nœud et les résumés sont les champs les plus utiles pour la compréhension
4. Les edges vous indiquent comment les composants se connectent — suivez les imports et les appels pour 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 l'ancien .understand-anything/ quand il existe déjà, sinon le nouveau .ua/. Vérifiez que $UA_DIR/knowledge-graph.json existe. Sinon, indiquez à l'utilisateur d'exécuter /understand d'abord.

2. Obtenez la liste des fichiers modifiés (ne lisez PAS le graphe pour l'instant) :

   • Si sur une branche avec des modifications non commitées : git diff --name-only
   • Si sur une branche de développement : git diff main...HEAD --name-only (ou la branche de base)
   • Si l'utilisateur spécifie un numéro de PR : obtenez la diff de cette PR

3. Lisez les métadonnées du projet et vérifiez la fraîcheur du graphe — utilisez Grep ou Read avec une limite de lignes pour extraire la section "project", y compris gitCommitHash en tant que GRAPH_COMMIT_RAW, puis :

   • Résolvez-le en tant que commit avant de l'utiliser dans une diff Git. Depuis la racine du projet, comparez le commit résolu avec git rev-parse HEAD et inspectez les modifications committées et d'arborescence de travail au niveau 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 monorepo frère ne doivent pas rendre ce graphe obsolète. Une divergence de hash seule n'est pas obsolète quand la diff du projet est vide.
   • Ignorez le répertoire de données sélectionné (.ua/ ou l'ancien .understand-anything/) dans la sortie de chaque commande car il contient des artefacts de graphe générés, pas des dérives de code source du projet.
   • Si la diff committée ou une commande d'arborescence de travail signale des fichiers projet, avertissez avant l'analyse d'impact que le graphe peut omettre ces modifications. Suggérez : Exécutez /understand pour actualiser le graphe.
   • Exécutez la diff de commit uniquement quand GRAPH_COMMIT_RAW est résolu avec succès. Si le commit du graphe ou les métadonnées Git sont manquants, invalides ou indisponibles, donnez un bref avertissement de meilleur effort et continuez au lieu de bloquer.

4. Trouvez les nœuds pour les fichiers modifiés — pour chaque chemin de fichier modifié, utilisez Grep pour rechercher dans le graphe de connaissances :

   • Les nœuds avec des valeurs "filePath" correspondantes (p. ex., grep "changed/file/path")
   • Ceci trouve les nœuds au niveau fichier (y compris les types non-code) ET les nœuds fonction/classe définis dans ces fichiers
   • Notez les valeurs id de tous les nœuds trouvés

5. Trouvez les edges connectées (1-hop) — pour chaque ID de nœud trouvé, utilisez Grep pour chercher cet ID dans les edges afin de trouver :

   • Ce qui importe ou dépend des nœuds modifiés (appelants en amont)
   • Ce que les nœuds modifiés importent ou appellent (dépendances en aval)
   • Ce sont les « composants affectés » — les choses qui pourraient casser ou avoir besoin de mise à jour

6. Identifiez les couches affectées — Utilisez Grep pour chercher les IDs de nœuds trouvés dans la section "layers" pour déterminer quelles couches architecturales sont touchées.

7. Fournissez une analyse structurée :

   • Composants modifiés : Ce qui a été directement modifié (avec résumés des nœuds trouvés)
   • Composants affectés : Ce qui pourrait être impacté (à partir des edges 1-hop)
   • Couches affectées : Quelles couches architecturales sont touchées et les préoccupations trans-couches
   • Évaluation des risques : En fonction des valeurs de complexity des nœuds, du nombre d'edges trans-couches, et de la portée de blast (nombre de composants affectés)
   • Suggérez ce qu'il faut examiner attentivement et tout problème potentiel

8. Écrivez le diff overlay pour le tableau de bord — après avoir produit l'analyse, écrivez les données de diff dans $UA_DIR/diff-overlay.json pour que le tableau de bord puisse visualiser les composants modifiés et affectés. Le fichier contient :

   {
     "version": "1.0.0",
     "baseBranch": "<la branche de base utilisée>",
     "generatedAt": "<timestamp ISO>",
     "changedFiles": ["<liste des chemins de fichiers modifiés>"],
     "changedNodeIds": ["<IDs de nœud de l'étape 4>"],
     "affectedNodeIds": ["<IDs de nœud de l'étape 5, excluant changedNodeIds>"]
   }

   Après écriture, informez l'utilisateur qu'il peut exécuter /understand-anything:understand-dashboard pour voir le diff overlay visuellement.