Codespaces — Découverte d'Architecture par Carte de Croyance

Que fait Codespaces — Découverte d'Architecture par Carte de Croyance ?

Interrogez .belief_map.sexp pour découvrir modules, frontières et dépendances avant de lire les fichiers source. Ne lisez jamais le code à l'aveugle — interrogez d'abord le graphe.

Scripts

Cette compétence regroupe des scripts Python. Lancez-les depuis le répertoire de base de la compétence :

• scripts/belief_search.py — interroger le graphe de la carte de croyance
• scripts/build_belief_map.py — générer la carte de croyance à partir du code source
• scripts/build_infra_topology.py — extraire les faits de topologie Kustomize, Helm et Terraform
• scripts/git_descendants.py — trouver tous les commits descendants de HEAD (ou d'une référence donnée)

N'utilisez jamais les copies locales de ces scripts dans le projet — elles peuvent être obsolètes et produire du JSON au lieu de sexp.

Prérequis

Localisez la carte de croyance. Si absente, construisez-la :

ls .belief_map.sexp belief_map.sexp 2>/dev/null
# Construction : pip3 install tree-sitter tree-sitter-typescript tree-sitter-python
python3 scripts/build_belief_map.py          # incrémental ~5s
python3 scripts/build_belief_map.py --full   # reconstruction complète ~30s

Flux de travail obligatoire : interroger avant le code

Pour un travail de code non trivial, lancez une requête sur la carte de croyance avant rg, find, sed, cat, nl, l'ouverture de répertoires ou la lecture de fichiers source. La compétence n'est utile que si elle est utilisée comme première étape de cadrage, pas comme confirmation après inspection du code source.

Première passe rapide quand la tâche a un mot-clé clair :

python3 scripts/belief_search.py quick "mot-clé"

quick recherche le premier module correspondant et exécute immédiatement analyze. Utilisez-la pour obtenir fichiers frontières, dépendances, dépendances inverses, couches et violations en une seule étape. Si quick renvoie le mauvais module ou aucune correspondance, utilisez le flux explicite search -> analyze ci-dessous.

Étape 1 — Trouver l'ID du module :

python3 scripts/belief_search.py search "mot-clé"
python3 scripts/belief_search.py entity NomEntité

Utilisez search ou entity pour localiser l'ID du module. Les ID de modules sont des chemins relatifs complets comme pki-service/src/modules/ca/ca.service, pas des codes courts comme ps34. La carte de croyance peut contenir en interne des IDs de chemins courts, mais ils sont résolus automatiquement — passez toujours des chaînes lisibles de type chemin. Ne DEVINEZ ni n'inventez les IDs de modules — confirmez toujours avec search d'abord.

Étape 2 — Analyser le module (faites-le IMMÉDIATEMENT, pas en option) :

python3 scripts/belief_search.py analyze <id-module>

analyze est la commande PRINCIPALE. Elle renvoie le contexte complet : fichiers frontières, dépendances, dépendances inverses, couche d'architecture et violations. Exécutez-la toujours avant de lire une source.

Étape 3 — Lire uniquement les fichiers frontières listés dans la sortie de analyze.

Étape 4 — Ne lisez PAS des répertoires entiers. Si la frontière montre 2-3 fichiers pertinents, lisez uniquement ces fichiers. Ignorez tout le reste du répertoire.

Référence des commandes

Commande	Objectif	Exemple
search "<pattern>"	Recherche regex dans le graphe (trouver ID de module)	search "operative.*service"
analyze <id>	Analyse complète du module (commande PRINCIPALE)	analyze drive/modules/drive/drive_schema
quick <mot-clé>	Recherche + analyse de la première correspondance (raccourci)	quick operatives
boundary <id>	Fichiers à lire pour un changement	boundary operatives.service
boundary <id> --files-only	Chemins de fichiers uniquement (compact)	boundary operatives.service --files-only
entity <Nom>	Trouver définitions + références	entity DrivePath
deps <id> [profondeur]	Arbre des dépendances sortantes	deps operatives.service 3
rdeps <id> [profondeur]	Rayon de souffle (qui dépend de ceci)	rdeps drive_schema 2
flow <id> <fn>	Tracer flux d'appel/données	flow drive_api fetchFiles
module <id>	Module unique avec ses arêtes	module operatives.controller
`boundaries [id	all]`	Vérifier les violations d'architecture
`invariants [id	all]`	Vérifier les violations de conventions de nommage
layers	Afficher tous les modules par couche	layers
find_function <nom>	Trouver les définitions de fonctions/méthodes	find_function createOrder
find_type <nom>	Trouver les définitions de types/classes/ifc/enum	find_type DriveDbCommitResponse
find_callchain <src> <tgt> [profondeur]	Tracer le chemin d'appel entre fonctions	find_callchain createOrder processPayment
find_callers <fn> [profondeur]	Qui appelle cette fonction	find_callers handleRequest 3
find_calls <fn> [profondeur]	Ce que cette fonction appelle	find_calls createOrder 2
grep_functions <pattern>	Rechercher dans les corps de fonctions dans le code source	grep_functions "validate.*input"
diff_functions [ref]	Fonctions modifiées dans le diff git	diff_functions HEAD~3
query '<sexp>'	Requête Scheme composable	query '(count (boundary "X"))'
repl	REPL Scheme interactif	repl

Référence rapide : requêtes rg

Quand vous avez besoin de recherches rapides et ciblées sans invoquer le script Python, interrogez la carte de croyance directement avec rg. Le constructeur fourni écrit .belief_map.sexp ; si un dépôt utilise encore l'ancien belief_map.sexp, remplacez ce nom de fichier dans les commandes ci-dessous :

# Tous les faits sur un module
rg 'drive/modules/drive_db/api ' .belief_map.sexp

# Qui importe un module
rg 'imports .* drive/modules/commons/result' .belief_map.sexp

# Ce qu'un module importe
rg 'imports drive/modules/drive_db/api' .belief_map.sexp

# Toutes les références à une entité
rg 'DriveDbCommitResponse' .belief_map.sexp

# Toutes les classes d'un dépôt
rg '^\(cls drive/' .belief_map.sexp

# Arêtes de flux de données
rg 'data-flow' .belief_map.sexp

Ces one-liners sont utiles pour des vérifications rapides. Pour une sortie structurée et une analyse complète, utilisez les commandes du script Python.

Notation de sortie

Toute sortie est constituée de faits S-expression, un par ligne. Voir references/sexp-notation.md pour le format complet.

Schémas clés :

(boundary <mod> :lang py :file <chemin> :purpose "<desc>")
(boundary-dep <mod> <dep> :lang ts :file <chemin> :relation imports)
(boundary-rdep <mod> <rdep> :lang tsx :file <chemin> :relation imports)
(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
(entity-def cls <mod> <Nom> <ligne> :lang py :file <chemin>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<raison>")
(result <module-ou-chemin>)
(result-count 42)

Valeurs de :lang : py = Python (snake_case), ts = TypeScript (camelCase), tsx = TSX (PascalCase).

Langage de requête Scheme

Composez des requêtes pour des analyses complexes. Voir references/scheme-queries.md pour la référence complète.

Essentiels :

(boundary "id")                ; cible + deps + rdeps (frontière de changement)
(entity "Nom")               ; modules définissant l'entité
(deps "id" profondeur)       ; dépendances sortantes
(rdeps "id" profondeur)      ; dépendances inverses
(find-function "nom")        ; modules avec des définitions de fonction correspondantes
(find-type "nom")            ; modules avec des définitions de type correspondantes
(find-callers "fn" profondeur)   ; modules appelant une fonction
(find-calls "fn" profondeur)     ; modules qu'une fonction appelle
(intersect A B)               ; intersection d'ensembles
(filter SET "pattern")       ; filtre regex
(files SET)                   ; résoudre en chemins de fichiers
(count SET)                   ; compter les membres
(violations)                  ; modules avec des violations de frontière
(layer "id")                 ; couche d'architecture d'un module

Schéma de plan d'analyse

Avant de modifier du code, composez un plan à partir de requêtes :

; 1. Cadrage
(boundary "operatives.service")
(count (boundary "operatives.service"))

; 2. Contraintes d'architecture
(violations "operatives.service")
(layer "operatives.service")

; 3. Frontières inter-langages
(filter (refs-to "DrivePath") "app-service")

; 4. Réduire aux fichiers actionnables
(filter (boundary "operatives.service") "dto")
(intersect (deps "controller" 2) (deps "service" 2))

; 5. Après les modifications : vérifier
(violations "operatives.service")

Exemples de déclenchement

Utilisez cette compétence avant de lire le code source pour :

• Des investigations de cause racine mentionnant des services, APIs, jobs, événements, flux UI ou comportements défaillants.
• Des questions inter-services ou inter-modules, par exemple "comment X appelle-t-il Y ?" et "où cela est-il stocké ?"
• Une clarification Redmine quand la réponse dépend du comportement du code.
• Des revues d'architecture, analyses d'impact, modifications de contrats publics ou vérifications de rayon de souffle.
• Des revues de changements non triviaux en staging quand la direction des dépendances ou la propriété des modules importe.

Ne forcez pas son utilisation pour des tâches de simple commit, des résumés git-log, des démos/serveurs manuels, des tests purement sur navigateur ou des analyses de logs de session.

Gestion des erreurs

Si une commande renvoie (error no-match ...) :

1. Ne réessayez PAS avec le même ID et ne devinez PAS un autre ID
2. Lancez search avec un mot-clé plus large pour trouver le bon ID de module
3. Utilisez le champ :suggestions s'il est présent — il liste des IDs de modules similaires

# Mauvais : deviner des IDs
python3 scripts/belief_search.py analyze ps34        # échoue : ps34 est un ID de chemin court
python3 scripts/belief_search.py analyze ca.service  # échoue : chemin incomplet

# Correct : d'abord search, puis utiliser le chemin complet depuis les résultats
python3 scripts/belief_search.py search "ca.*service"
# La sortie montre : pki-service/src/modules/ca/ca.service
python3 scripts/belief_search.py analyze pki-service/src/modules/ca/ca.service

Anti-patrons

• Deviner les IDs de modules. Les IDs de modules sont des chemins relatifs complets (ex. pki-service/src/modules/ca/ca.service). Les codes courts comme ps34 sont des IDs de chemins internes et ne doivent pas être utilisés directement. Faites toujours search d'abord.
• Construire mais ne jamais interroger. Construire la carte de croyance puis ne jamais lancer search, analyze ou boundary n'apporte aucune valeur.
• Interroger après avoir lu le code source. La première lecture de code source devrait provenir des lignes boundary-file dans la sortie de analyze.
• Lire .belief_map.sexp comme un fichier entier. Utilisez search, analyze ou rg pour interroger des faits spécifiques.
• Sauter la carte de croyance pour des tâches inter-modules. Interrogez toujours le graphe pour comprendre les frontières avant de lire les fichiers source.
• Lire tous les fichiers d'un répertoire. Quand la frontière montre 2-3 fichiers, lisez uniquement ceux-là.
• Utiliser des scripts locaux au projet. Utilisez toujours les scripts fournis par cette compétence. Les copies du projet peuvent produire du JSON au lieu de sexp.

Reconstruction du graphe

python3 scripts/build_belief_map.py          # incrémental (~5s)
python3 scripts/build_belief_map.py --full   # reconstruction complète (~30s)
python3 scripts/build_belief_map.py ./drive  # un seul sous-dépôt
python3 scripts/build_belief_map.py --lsp    # avec hiérarchie d'appels LSP (~1-5min)

Reconstruisez après des changements structurels (ajout/suppression de fichiers, modification d'imports, ajout de classes).

Topologie d'infrastructure

Extrayez la topologie des services depuis les fichiers Kustomize, Helm et Terraform. Ce script nécessite PyYAML (pip3 install pyyaml).

python3 scripts/build_infra_topology.py                    # auto-détection de tous les IaC
python3 scripts/build_infra_topology.py --kustomize .      # kustomize uniquement
python3 scripts/build_infra_topology.py --helm ./charts    # helm charts uniquement
python3 scripts/build_infra_topology.py --terraform ./infra # terraform uniquement
python3 scripts/build_infra_topology.py --append .belief_map.sexp  # fusionner dans le graphe

Émet les arêtes infra-node, k8s-depends, k8s-service, helm-depends, tf-depends et infra-maps. Interrogez avec :

rg 'infra-node' .belief_map.sexp                  # tous les services
rg 'k8s-depends' .belief_map.sexp                 # dépendances de services
rg 'infra-node.*:component database' .belief_map.sexp  # toutes les bases de données
rg 'infra-maps.*app-service' .belief_map.sexp     # mapping infrastructure -> code source