GitNexus — navigation et analyse d'impact

GitNexus est un outil d’indexation du graphe de code utilisé par arka-deck. Il indexe le projet en clusters, processes d’exécution et symboles, et permet de naviguer ou d’évaluer l’impact d’une modification avant de la faire.

---

Quand utiliser GitNexus

• Avant de modifier un symbole (fonction, classe, port) : connaître l’impact en amont.
• Pour comprendre un flux d’exécution (par exemple “que se passe-t-il lors d’un purge projet ?”).
• Pour explorer un domaine inconnu (par exemple première contribution sur la mémoire).
• Pour un refactor sûr (rename, extract, split).

---

Commandes principales

gitnexus impact — analyse d’impact

npx gitnexus impact --target <symbolName> --repo arka-deck --direction upstream

Affiche les callers directs (d=1, vont casser si la signature change) et indirects (d=2, à tester). À lancer avant toute modification d’une fonction ou d’un port.

gitnexus query — recherche par concept

npx gitnexus query "auth validation"

Retourne les flux d’exécution liés au concept, classés par pertinence. Utile pour explorer sans connaître le nom exact.

gitnexus context — vue 360° d’un symbole

npx gitnexus context --name validateUser

Liste tous les callers, callees et processes auxquels appartient le symbole.

gitnexus rename — renommage sûr

# Dry-run d'abord
npx gitnexus rename --symbol-name old --new-name new --dry-run

# Une fois validé
npx gitnexus rename --symbol-name old --new-name new

Comprend le graphe d’appels et renomme dans tous les call sites, pas juste un find-and-replace textuel.

gitnexus detect_changes — vérification de scope

npx gitnexus detect-changes --scope staged

Avant un commit : vérifie que les changements n’affectent que les symboles et flux attendus.

gitnexus analyze — réindexer

npx gitnexus analyze

Après un commit, l’index devient stale. Réindexer pour conserver des résultats fiables. Préserver les embeddings : --embeddings.

---

Niveaux de risque d’impact

Profondeur	Signification	Action
d=1	Va casser — appelants directs	Mettre à jour ces fichiers
d=2	Probablement affecté	Tester
d=3	À tester si chemin critique	Tester ciblé

Ne jamais ignorer un risque HIGH ou CRITICAL. Pauser et expliquer la blast radius avant de procéder.

---

Workflow type

Avant modification

1. gitnexus impact <target> --direction upstream → callers directs et indirects.
2. Lire les fichiers d=1 — ils vont casser.
3. Décider : modifier la signature avec les sites d’appels, ou créer une nouvelle fonction et migrer progressivement.

Pendant la modification

• Garder le périmètre annoncé.
• Tester localement les sites d=1 modifiés.

Avant commit

npx gitnexus detect-changes

Confirme que les changements correspondent au scope attendu.

Après commit (mainteneur)

npx gitnexus analyze --embeddings

Réindexer pour les prochaines analyses.

---

Limites

• L’index peut devenir stale après une session intense. Réindexer en cas de doute.
• Les analyses sémantiques (sur des chaînes de caractères, par exemple) demandent les embeddings — vérifier .gitnexus/meta.json (stats.embeddings > 0).
• GitNexus voit le graphe TypeScript ; les déclarations dynamiques ou les eval ne sont pas couvertes.

---

Voir aussi

• Guide agent IA : ./working-rules
• Conventions : ./conventions