wingbox

Graphe de code pour les grands dépôts et monorepos. Utilisez-le, avant grep ou la lecture de fichiers, lorsque la question est ce qu'un changement va casser (rayon d'explosion, analyse d'impact), qui utilise un fichier, une fonction, un type ou un package, où une fonctionnalité est implémentée, quels fichiers lire en premier, ou comment les modules et packages dépendent les uns des autres ; avant une refactorisation, un changement entre packages ou toute modification non triviale ; et lors de l'exploration d'une base de code inconnue. Construit et interroge la recherche de code sensible à l'architecture, les graphes de dépendances, les flux d'appels, les limites de modules et les violations d'architecture pour Python, TypeScript, TSX, Rust, C#, Java, Go, Ruby, Ruby on Rails, PHP, Laravel, Blade, Livewire, Eloquent, Dart et Flutter.

Qu'est-ce que wingbox ?

Wingbox est une compétence IA spécialisée dans la découverte d'architecture de code, conçue pour les grands dépôts et monorepos. Elle fonctionne en construisant un graphe de code à partir des fichiers source du projet, puis en permettant des requêtes structurées via des commandes dédiées ou des scripts Python. L'objectif principal est de remplacer les méthodes de recherche et de lecture aveugles de code (grep, cat, ls) par une approche systématique : d'abord interroger le graphe pour comprendre l'architecture, les dépendances et l'impact des changements avant de lire les fichiers sources. Cette compétence est particulièrement utile avant une refactorisation, un changement impactant plusieurs packages, ou lors de l'exploration d'une nouvelle base de code. Wingbox prend en charge de nombreux langages et frameworks, dont Python, TypeScript, Rust, C#, Java, Go, Ruby, PHP, Dart et Flutter, et peut être installée en tant que compétence pour Claude Code, Cursor, Codex et d'autres assistants IA. Elle offre des commandes pour analyser un module (analyze), trouver l'impact d'un fichier (impact), rechercher des fonctions ou types (find_function, find_type), explorer les dépendances (deps, rdeps) et bien plus encore. Le graphe est construit avec la commande `wingbox build` et peut être mis à jour automatiquement en fonction des modifications de fichiers. La sortie est au format S-expressions, lisible à la fois par les humains et les machines, et peut être utilisée directement par d'autres outils comme grep pour des recherches rapides. Wingbox inclut également des fonctionnalités avancées telles que l'analyse d'architecture (boundaries, layers, invariants), l'apprentissage automatique des conventions de nommage et de placement (learn, align), et un serveur MCP (Model Context Protocol) pour intégration avec d'autres outils.

Compatible avec✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/aileron-tech/wingbox/tree/HEAD

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 :

  • /wingbox sans argument : trouver le graphe (.wingbox/index.sexp à la racine du projet ; chaque commande wingbox le trouve aussi depuis un sous-dossier). Construisez-le avec wingbox 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 -quit
    

    Une reconstruction ne réanalyse que les fichiers dont le contenu a changé. Ensuite, lisez .wingbox/REPORT.md et 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 open l'affiche dans un navigateur, hors ligne).

  • /wingbox <fichier> : exécutez wingbox impact <fichier> 2 et résumez ce qui dépend du fichier et quels fichiers lire en premier.

  • /wingbox <commande> ... : exécutez wingbox <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.

CommandeObjectif
`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-searchLe crochet PreToolUse de Claude Code ; lit l'entrée du crochet sur stdin ; rafraîchit le graphe avant de le lire
wingbox hook dirtyLe 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 code
  • scripts/build_code_graph.py -- générer le graphe de code à partir des sources
  • 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 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

CommandeObjectifExemple
search "<motif>"Recherche littérale/sécurisée/.* sur le graphesearch "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 moduleanalyze drive/modules/drive/drive_schema
quick <mot-clé>Rechercher + analyser la première correspondance (raccourci)quick operatives
boundary <id>Fichiers à lire pour un changementboundary operatives.service
boundary <id> --files-onlyChemins 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 colonneentity 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 candidatsusages src/billing/invoice.ts::Invoice
deps <id> [profondeur]Arbre des dépendances sortantesdeps operatives.service 3
rdeps <id> [profondeur]Rayon d'explosion (qui dépend de ceci)rdeps drive_schema 2
`impact <fichierid> [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'appelsflow drive_api fetchFiles
module <id>Module unique avec arêtesmodule 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 acceptreject [--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éeswingbox 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 importerwingbox 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éviewingbox 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 fichierwingbox learn --agent
`boundaries [idall]`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 [idall]`Vérifier les violations de conventions de nommage
layersAfficher tous les modules par couche, avec la partie, le style et la règle qui a défini chaque couchelayers
find_function <nom>Trouver les définitions de fonctions/méthodesfind_function createOrder
find_type <nom>Trouver les définitions de types/classes/modules/interfaces/énumérationsfind_type DriveDbCommitResponse
find_callchain <src> <cible> [profondeur]Tracer le chemin d'appels entre fonctionsfind_callchain createOrder processPayment
find_callers <fn> [profondeur]Qui appelle cette fonctionfind_callers handleRequest 3
find_calls <fn> [profondeur]Qu'est-ce que cette fonction appellefind_calls createOrder 2
grep_functions <motif>Rechercher dans les corps de fonctions dans le code sourcegrep_functions "valider.*entrée"
diff_functions [ref]Fonctions modifiées dans le diff gitdiff_functions HEAD~3
query '<sexp>'Requête Scheme composablequery '(count (boundary "X"))'
replREPL Scheme interactifrepl
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 MCPclaude 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).

Skills associés