Wingbox -- Découverte d'Architecture par Graphe de Code
Interrogez .wingbox/index.sexp pour découvrir les modules, les limites et les dépendances avant de lire les fichiers sources. Ne lisez jamais le code à l'aveugle -- interrogez d'abord le graphe.
/wingbox
Lorsque l'utilisateur tape /wingbox (dans Codex $wingbox), faites ceci avant toute autre chose :
-
/wingboxsans argument : trouver le graphe (.wingbox/index.sexpà la racine du projet ; chaque commandewingboxle trouve aussi depuis un sous-dossier). Construisez-le avecwingbox build .lorsqu'il est manquant ou obsolète. Le graphe est obsolète lorsqu'un fichier du projet a été modifié après le fichier du graphe ; cette vérification le trouve :G=.wingbox/index.sexp [ ! -f "$G" ] || find . -type f -newer "$G" -not -path './.git/*' \ -not -path './.wingbox/*' -not -path '*/node_modules/*' -print -quitUne reconstruction ne réanalyse que les fichiers dont le contenu a changé. Ensuite, lisez
.wingbox/REPORT.mdet donnez à l'utilisateur ses « résultats clés », les modules les plus dépendus et par où commencer la lecture, et dites que la carte est.wingbox/map.html(wingbox openl'affiche dans un navigateur, hors ligne). -
/wingbox <fichier>: exécutezwingbox impact <fichier> 2et résumez ce qui dépend du fichier et quels fichiers lire en premier. -
/wingbox <commande> ...: exécutezwingbox <commande> ...(par exemple/wingbox quick "upload de fichier",/wingbox analyze src/billing/invoice).
Exécution des commandes
Lorsque la commande wingbox est installée (command -v wingbox), exécutez wingbox <commande> ... pour chaque requête ci-dessous et wingbox build CHEMIN pour construire ; elles prennent les mêmes arguments que les scripts. Une compétence installée par wingbox install n'a pas de dossier scripts/ et utilise toujours la commande.
| Commande | Objectif |
|---|---|
| `wingbox install [--global | --project] [--assistant NOM ...] [--dry-run]` |
| `wingbox uninstall [--global | --project] [--assistant NOM ...]` |
wingbox open [CHEMIN] | Ouvrir .wingbox/map.html du projet dans le navigateur (affiche son chemin lorsqu'il n'y a pas de navigateur) |
wingbox update [--check] [--dry-run] | Mettre à niveau avec pipx, uv ou pip, puis rafraîchir les compétences, blocs et crochets installés ; avertit des fichiers laissés par une version antérieure (.code_graph*, wingbox-out/) |
wingbox hook pre-search | Le crochet PreToolUse de Claude Code ; lit l'entrée du crochet sur stdin ; rafraîchit le graphe avant de le lire |
wingbox hook dirty | Le crochet PostToolUse de Claude Code sur Edit et Write : marque le fichier modifié pour que le graphe soit rafraîchi avant sa prochaine utilisation |
Chacune de ces commandes affiche des faits sous forme de texte ; ajoutez --sexp pour des S-expressions.
Scripts
Cette compétence intègre des scripts Python. Résolvez les racines de la compétence et de la cible avant de les exécuter pour que le projet scanné soit toujours explicite :
scripts/code_graph_search.py-- interroger le graphe de codescripts/build_code_graph.py-- générer le graphe de code à partir des sourcesscripts/build_infra_topology.py-- extraire les faits de topologie Kustomize, Helm et Terraformscripts/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 pourraient être obsolètes et produire du JSON au lieu de sexp.
Prérequis
Localisez le graphe de code. S'il est absent, construisez-le :
ls .wingbox/index.sexp 2>/dev/null
SKILL_ROOT="$(pwd -P)"
TARGET_ROOT="$(cd /chemin/absolu/vers/le/projet && pwd -P)"
python3 "$SKILL_ROOT/scripts/build_code_graph.py" --root "$TARGET_ROOT"
python3 "$SKILL_ROOT/scripts/build_code_graph.py" --root "$TARGET_ROOT" --full
L'indexation Python n'a pas de dépendance de parseur externe. Pour les autres langages détectés, la première construction échoue avant publication lorsqu'un parseur est absent ou a la mauvaise version et imprime la commande exacte par langue à exécuter, comme :
python3 -m pip install -r "$SKILL_ROOT/requirements/typescript.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/csharp.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/ruby.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/php.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/dart.txt"
Installez uniquement les fichiers d'exigences nommés par le constructeur, puis réexécutez-le. requirements.txt est réservé à la dépendance de topologie de l'infrastructure.
Flux de travail obligatoire : interroger avant le code
Pour un travail de code non trivial, exécutez une requête de graphe de code avant rg, find, sed, cat, nl, l'ouverture de répertoires ou la lecture de fichiers sources. La compétence n'est utile que lorsqu'elle est utilisée comme première étape de cadrage, et non comme confirmation après que la source a déjà été inspectée.
Premier passage rapide lorsque la tâche a un mot-clé clair :
python3 scripts/code_graph_search.py quick "mot-clé"
quick recherche le premier module correspondant et exécute immédiatement analyze. Utilisez-le pour obtenir les fichiers limites, les dépendances, les dépendances inverses, les couches et les violations en une seule étape. Si quick retourne le mauvais module ou aucune correspondance, utilisez le flux explicite search -> analyze ci-dessous.
Étape 1 -- Trouver l'ID du module :
python3 scripts/code_graph_search.py search "mot-clé"
python3 scripts/code_graph_search.py entity NomEntité
Utilisez search ou entity pour localiser l'ID du module. Les ID de modules sont des chemins relatifs complets comme billing-service/src/modules/invoice/invoice.service, et non des codes courts comme bs34. Le graphe de code peut contenir des ID de mappage de chemin courts en interne, mais ils sont résolus automatiquement -- passez toujours des chaînes de type chemin lisibles par l'homme. Ne devinez NI n'inventez les ID de modules -- confirmez toujours avec search d'abord.
Étape 2 -- Analyser le module (faites-le IMMÉDIATEMENT, pas optionnellement) :
python3 scripts/code_graph_search.py analyze <id-du-module>
analyze est la commande PRINCIPALE. Elle retourne le contexte complet : fichiers limites, dépendances, dépendances inverses, couche d'architecture et violations. Exécutez-la toujours avant de lire une source.
Étape 3 -- Lisez uniquement les fichiers limites listés dans la sortie de analyze.
Étape 4 -- Ne lisez PAS des répertoires entiers. Si la limite montre 2-3 fichiers pertinents, lisez uniquement ces fichiers. Ignorez tout le reste dans le répertoire.
Référence des commandes
| Commande | Objectif | Exemple |
|---|---|---|
search "<motif>" | Recherche littérale/sécurisée/.* sur le graphe | search "operative.*service" |
analyze <id> [--all] | Analyse complète du module (commande PRINCIPALE) ; nomme au plus 200 dépendants sauf --all ; se termine par le (advice ...) qui concerne le module | analyze drive/modules/drive/drive_schema |
quick <mot-clé> | Rechercher + analyser 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> [--positions] | Trouver les définitions + les modules qui les utilisent ; --positions : chaque utilisation avec ligne et colonne | entity DrivePath --positions |
usages <symbole> [--sexp] [--all] | Chaque utilisation d'un symbole (Nom, <fichier>::Nom, <fichier>::Classe.méthode) via les réexportations et alias, par fichier, ligne:col et type (import, réexportation, appel, type, extends, référence ; unresolved-call pour un appel de méthode dont le type du récepteur n'est pas en vue) ; au plus 200 sauf --all ; un nom défini dans plusieurs fichiers liste les candidats | usages src/billing/invoice.ts::Invoice |
deps <id> [profondeur] | Arbre des dépendances sortantes | deps operatives.service 3 |
rdeps <id> [profondeur] | Rayon d'explosion (qui dépend de ceci) | rdeps drive_schema 2 |
| `impact <fichier | id> [profondeur] --sexp [--all]` | Rayon d'explosion d'un fichier : dépendants par profondeur la plus courte + fichiers à lire en premier ; liste au plus 200 sauf --all, les comptes sont toujours complets ; se termine par l'avis qui concerne le fichier |
flow <id> <fn> | Tracer le flux de données/d'appels | flow drive_api fetchFiles |
module <id> | Module unique avec arêtes | module operatives.controller |
wingbox init [CHEMIN] [--force] [--sexp] [--synonyms] | Diviser le dépôt en parties, juger le style d'architecture de chacune (avec score, preuves et sources) et écrire .wingbox/config.yaml (conservé sauf --force) ; --synonyms mappe également les noms de dossiers via les vecteurs de mots intégrés ; dans un dossier vide --language L --style S --yes [--scaffold] démarre un nouveau projet (sans eux, il imprime les choix et quitte avec le code 2) | wingbox init --sexp |
wingbox advice [--sexp] [--learned] / `wingbox advice accept | reject [--reason TEXTE]` | Ouvrir les recommandations de la dernière construction (déplacer, corriger-violation, dossier-manquant) sans celles rejetées ou ignorées depuis longtemps ; enregistrer une décision dans .wingbox/decisions.sexp |
wingbox align [PARTIE] [--to STYLE] [--learn] [--sexp] | Écarts de chaque partie par rapport à son style (fichiers placés, règles suivies, dossiers non placés, règles enfreintes) ; --to contre un autre style ; --learn écrit les dossiers appris et une base de référence pour que seules les nouvelles violations soient signalées | wingbox align --sexp |
wingbox place "<quoi>" [--part PARTIE] [--sexp] | Couche et dossier pour un nouveau code selon les règles de placement du style de la partie (:new lorsque le dossier n'existe pas encore) et ce qu'il peut importer | wingbox place "référentiel pour factures" --sexp |
wingbox compare [--sexp] | Parties d'un monorepo par langue : style, couches, différences (couches manquantes, un nom de dossier signifiant une autre couche, un style différent de la majorité) et avis pour la partie qui dévie | wingbox compare --sexp |
wingbox learn --agent [PARTIE] [--sexp] / wingbox learn --apply [FICHIER] | /wingbox learn : exécutez wingbox learn --agent, lisez les fichiers qu'il nomme, répondez uniquement dans son format ((layer <partie> <dossier> <couche> :because "..."), (unknown ...), au plus un (style ...)), pipez la réponse vers wingbox learn --apply, affichez le résultat ; en cas d'erreurs, corrigez les lignes nommées et renvoyez la réponse entière. Lorsque le code ne décide pas d'un dossier, demandez à l'utilisateur dans le chat et répondez avec :because "opérateur : <ses mots>" ; ne devinez jamais. Pour modifier .wingbox/config.yaml, suivez les instructions en haut de ce fichier | wingbox learn --agent |
| `boundaries [id | all]` | Vérifier les règles de limite de chaque style de partie (ou des règles que la partie déclare) ; chaque ligne nomme :part, :style et :rule ; les imports de type uniquement et les couches devinées sont signalés séparément ; puis les fichiers qui font ce que leur couche ne peut pas faire (capability-violation : SQL en dehors des référentiels, HTTP sortant en dehors de l'infrastructure, le framework dans le domaine, avec :line et :evidence) et les vérifications de motif du style (pattern-violation). boundaries-ok uniquement lorsque chaque partie a été vérifiée ; une partie dont les règles déclarées n'ont pas été lues, ou sans style déterminé, est boundaries-not-checked avec boundaries-partial au lieu de ok. Code de sortie : 2 non vérifié (règles déclarées non lues), 1 violations, 0 sinon - ne signalez jamais une réussite sur le code de sortie 2 |
| `invariants [id | all]` | Vérifier les violations de conventions de nommage |
layers | Afficher tous les modules par couche, avec la partie, le style et la règle qui a défini chaque 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/modules/interfaces/énumérations | find_type DriveDbCommitResponse |
find_callchain <src> <cible> [profondeur] | Tracer le chemin d'appels entre fonctions | find_callchain createOrder processPayment |
find_callers <fn> [profondeur] | Qui appelle cette fonction | find_callers handleRequest 3 |
find_calls <fn> [profondeur] | Qu'est-ce que cette fonction appelle | find_calls createOrder 2 |
grep_functions <motif> | Rechercher dans les corps de fonctions dans le code source | grep_functions "valider.*entrée" |
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 |
wingbox mcp [--root DOSSIER] | Exécuter ces commandes en tant qu'outils d'un serveur MCP sur stdio (build, impact, usages, analyze, quick, boundary, deps, ...) pour les clients MCP | claude mcp add wingbox -- wingbox mcp |
impact accepte un chemin de fichier ordinaire. Sans --sexp, il imprime un texte lisible pour les humains ; les agents passent --sexp pour obtenir les mêmes faits sous la forme compacte S-expression, qui est le format que toutes les autres commandes utilisent.
Référence rapide : requêtes rg
Lorsque vous avez besoin de recherches rapides et ciblées sans invoquer le script Python, interrogez directement le graphe de code avec rg. Le constructeur écrit le graphe dans .wingbox/index.sexp :
# Tous les faits sur un module
rg 'drive/modules/drive_db/api ' .wingbox/index.sexp
# Qui importe un module
rg 'imports .* drive/modules/commons/result' .wingbox/index.sexp
# Qu'importe un module
rg 'imports drive/modules/drive_db/api' .wingbox/index.sexp
# Toutes les références à une entité
rg 'DriveDbCommitResponse' .wingbox/index.sexp
# Toutes les classes dans un dépôt
rg '^\(cls drive/' .wingbox/index.sexp
# Arêtes de flux de données
rg 'data-flow' .wingbox/index.sexp
# Modules Python chargés par un nom lu depuis un fichier de configuration
rg 'registry-wires' .wingbox/index.sexp
Ces one-liners sont utiles pour des vérifications rapides. Pour une sortie structurée et une analyse complète, utilisez les commandes de script Python.
Notation de sortie
Toute la sortie est constituée de faits S-expression, un par ligne. Voir references/sexp-notation.md pour le format complet.
Motifs 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> <cible> :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), cs = C#, java = Java, go = Go, rb = Ruby (snake_case), php = PHP, dart = Dart.
Codes des couches : domain, application, infrastructure, presentation, api, data, config, lib, test, unknown.
Codes des vérifications de motif : pattern-violation (nom de fichier, nom de dossier, contenu de fichier qui ne correspond pas au motif attendu), capability-violation (une couche fait ce qu'elle ne devrait pas), avec :line et :evidence.
Des sections détaillées suivent pour chaque commande. Les options incluent --min-confidence (utilisez la sortie avec analyze pour sa hotspot et ne nommez pas plus de 10 violations), --bypass (ne pas propager hors de la couche indiquée, par défaut infrastructure), --threat-model (insérez les entrées dans la sortie comme assume-breach infiltration, assume-breach exfiltration).