Que fait xylem ?
Vous allez transformer un dépôt en une carte ancrée dans le code source. Elle propose quatre vues, dans un site statique de deux fichiers (index.html et deep-view.json) :
| Vue | Montre |
|---|---|
| Explorer | Les composants (les parties du système) et les connexions entre eux, regroupés en couches |
| Parcours clients | Chaque parcours qu'un utilisateur peut emprunter, animé sur l'architecture : requêtes, réponses et transferts étiquetés |
| Carte d'état | Chaque dimension d'état déclarée dans le périmètre cartographié, ses états, et les transitions que les parcours empruntent réellement |
| Code | Chaque fonction cartographiée sous forme de tuile dans sa région, avec ses décisions, ses appels et ses appelants, et les chemins de parcours tracés au niveau de la fonction |
La méthode importe plus que la page. Chaque affirmation est liée à un fichier:ligne. Chaque connexion est réelle. Là où le code ne peut pas trancher, la carte le dit au lieu de deviner.
Règles fondamentales (à appliquer à chaque phase)
- Preuve ou rien. Tout composant, unité, décision, arête, état et action doit citer un
fichier:ligne. Si vous ne pouvez pas le citer, marquez-leNON_VÉRIFIÉou omettez-le. C'est une obligation de l'auteur/relecteur : les portes automatisées imposent la preuve pour l'architecture et les emplacements source profonds, mais pas pour chaque citation d'état/action ou explication ? - Attribuer des IDs ; ne jamais inventer d'entités ou de connexions. Utilisez les IDs de position de fichier de l'échafaudage ; les IDs créés manuellement doivent également être uniques et stables. Les arêtes inter-régions doivent emprunter une connexion d'architecture déclarée. Si elle manque, enregistrez un
diagram_gapet vérifiez-le dans le code avant de l'ajouter, avec preuve. - Les lacunes honnêtes valent mieux que des chemins impossibles. Si un résultat de parcours ne peut pas être retracé distinctement à partir de la source, écrivez
{"unavailable": "<raison spécifique>"}. Ne copiez jamais le chemin de réussite dans un résultat d'échec. N'enchaînez jamais des branches qui ne peuvent pas être vraies simultanément. - Dites ce que c'est. Les traces sont des chemins source statiques, pas des enregistrements d'exécutions réelles. Étiquetez-les ainsi dans la page.
- Lecture seule. Ne modifiez jamais le dépôt cible. Écrivez tout dans
.xylem/(ou un dossier nommé par l'utilisateur). - Confidentialité. N'envoyez pas le contenu du dépôt à un service externe sauf si l'utilisateur le demande. Le site ne fait que des requêtes de même origine pour ses données et les vidéos optionnelles. Il ne fait aucune requête externe ; servez-le en boucle locale pour une utilisation hors-ligne.
Structure de sortie
.xylem/
census.json # chaque définition trouvée dans le code (scripts/census.py)
architecture.json # phase 1
journeys.json # phase 2
deep.json # phase 3 (carte au niveau fonction)
validation.json # sortie de scripts/validate.py
reviews/ # rapports de relecture croisée (phase 6)
site/ # index.html + deep-view.json (+ videos/) (scripts/build_site.py)
Les formats de chaque fichier sont dans references/schemas.md. Lisez-le avant d'écrire du JSON.
Phases et portes
Effectuez les phases dans l'ordre. Chaque phase se termine par une porte. Ne continuez pas tant que la porte n'est pas passée, ou que l'utilisateur n'a pas accepté une lacune documentée. Dans un essai explicitement autorisé, conservez les artefacts défaillants et les journaux inchangés et continuez uniquement dans le cadre de cet essai ; étiquetez les sorties ultérieures comme provisoires. Un passage structurel n'établit pas une couverture sémantique complète.
Phase 0 : Recensement (déterministe)
python scripts/census.py <repo> --out .xylem/census.json [--exclude dir ...]
Ceci inventorie les définitions nommées avec AST Python, un token walker JS/TS de la bibliothèque standard, et des regex approximatives pour les autres langages pris en charge. scannedFiles inclut les fichiers source sans définition. JS/TS couvre les flèches génériques, les méthodes concrètes multilignes/computées, les signatures surchargées, les propriétaires lexicaux de fonctions/classes, les littéraux regex et les interpolations de templates ; les callbacks anonymes ne sont pas des unités de recensement. Il s'agit d'un inventaire mesuré, pas d'une preuve de toute la syntaxe du langage. Qualifiez-le avec un analyseur indépendant ou un échantillon source avant de revendiquer l'exhaustivité. Les pourcentages ultérieurs décrivent uniquement cet inventaire.
Porte : les comptes de recensement sont plausibles par rapport à la taille du dépôt. Les chemins exclus sont justifiés, par exemple le code généré ou node_modules.
Phase 1 : Architecture
Lisez les points d'entrée, les fichiers de construction, les modules principaux et les limites de processus. Écrivez ensuite architecture.json :
- couches : par exemple shell, UI, serveur, domaine, stockage, workers, externe ;
- composants : chacun avec
id,layer,files[], une responsabilité simple, etprocessType; - connexions : chacune
{from, to, label, kind}, oùkindest spawn, ipc, http, file, data ou uses ; - flux : les principaux flux de bout en bout sous forme d'étapes ordonnées des composants.
Porte : python scripts/validate.py .xylem --only architecture passe. Chaque entrée de scannedFiles appartient à un composant, ou a une entrée architecture.meta.fileExclusions motivée. Les chemins et lignes de preuve doivent exister sous la racine de preuve.
Phase 2 : Parcours et états
Écrivez journeys.json. Élaborez-les à partir de l'UI, des routes, des commandes CLI, des tâches et des chemins d'erreur :
- stateDimensions : chaque machine d'état indépendante ;
- screens : chaque écran ;
- actions : chaque action utilisateur et transition système, avec ses résultats, le texte exact que l'utilisateur voit, et l'annulation ;
- journeys : états de départ plus étapes.
Chaque action porte une trace d'architecture ordonnée (alternance composant et connexion). Les trajets de retour utilisent {"connection": [a, b], "direction": "reply"}. Lorsque l'étape suivante ne commence pas là où la précédente s'est terminée, l'étape porte transition.handoff, avec un type et une étiquette : user, timer, queue, continuation, lifecycle ou download. Couvrez les parcours heureux, malheureux, de récupération et limites.
Porte : validate.py --only journeys passe :
- chaque parcours se rejoue via des résultats valides ;
- zéro saut silencieux (chaque illumination est atteinte par un fil, une réponse ou un transfert étiqueté) ;
- aucun état orphelin.
Phase 3 : Carte au niveau fonction (résolution finale)
- Générez une carte provisoire à partir du recensement :
python scripts/scaffold_deep.py .xylem
Il écrit deep.json. Le brouillon contient les unités de recensement attribuées, les décisions Python d'AST, et les points if, while, for, switch et catch parenthésés heuristiques JS/TS. JS/TS ne prétend pas à un inventaire complet des ternaires, calculs ou décisions court-circuitées. Les commentaires, le contenu des littéraux et les déclarations enfants sont exclus de chaque corps. Les appels génériques conservent des positions d'appel distinctes. Les arêtes d'appel utilisent source: heuristic et confidence: name-resolved ; les noms non résolus ne sont pas des liens inventés. Affinez par rapport à la source ; la résolution de nom n'est pas une résolution de type.
2. Affinez le brouillon en lisant le code :
summarylisible métier par unité, écrite à partir du corps, pas du nom ;- pour chaque décision, une question
plain(« Ce fichier est-il plus grand que 16 Mo ? ») plus letestexact du code, unkind(branch, calculation, loop ou unconditional) et les successeurs corrects. Unreturnouraisetermine le chemin. Les continuations normales et d'erreur d'un bloc try sont séparées, et une exception en attente exécutefinallypuis se propage. En cas d'incertitude, marquez le successeurunresolved; jamaisverified; - les étiquettes
riskuniquement sur les décisions qui implémentent directement un défaut connu.
- Écrivez
actionTraces: pour chaque action et résultat de parcours, les événements d'exécution ordonnés{component, unit, event, decision?, line, note?, callsite?, returnTo?, precondition?, boundary?}.eventest l'un de call, return, branch, async, spawn, ipc, http, file, render, unknown, throw, finally ou resume. Voir les schémas pour les trames d'activation, les événements terminaux et les limites de rejeu prise en charge.- Commencez par l'initiateur réel, comme un gestionnaire d'UI, une route ou une tâche.
- Suivez les appels, les retours et les limites de processus. Un refus doit suivre le chemin d'erreur réel jusqu'à l'utilisateur. Il ne doit jamais continuer vers « enregistré » ou « succès ».
- Là où le chemin est inconnaissable, émettez
{"event": "unknown", "note": "..."}, ou marquez l'ensemble du résultat comme indisponible.
Grands dépôts : divisez la phase 3 par zone de code entre plusieurs agents, chacun écrivant deep-<part>.json dans le même format, puis fusionnez-les avec scripts/merge_deep.py. Réconciliez les IDs par fichier et ligne de définition, jamais par similarité de nom.
Porte : validate.py passe l'ensemble complet :
- chaque définition du recensement émise ou explicitement exclue avec une raison ; la couverture émise et la comptabilité d'exclusion sont des compteurs séparés ;
- chaque point d'extrémité d'arête résout ;
- chaque arête inter-région emprunte une connexion ;
- les successeurs de décision résolvent ;
- les références de trace sont valides ;
- cohérence des sélecteurs : aucune activation ne prend de choix mutuellement exclusifs pour des valeurs inchangées. Les écritures source peuvent changer une valeur ; une étiquette d'itération seule ne peut pas réinitialiser des contraintes. La grammaire et les limites prises en charge sont dans le schéma. Par exemple,
x==='a'oui puisx==='b'oui, ou une valeur exclue puis requise parincludes(). Corrigez la trace, ou retirez-la versunavailable, en nommant le conflit.
Phase 4 : Construction de la page
python scripts/build_site.py .xylem
Ceci écrit site/index.html et site/deep-view.json. Les vidéos sont optionnelles : déposez videos/<journeyId>.mp4 plus videos/manifest.json dans .xylem/ d'abord (voir les schémas). Servez site/ via HTTP pour le visualiser, par exemple python -m http.server -d .xylem/site. Une page file:// ne peut pas charger les données de la vue Code.
Porte : ouvrez la page et vérifiez chaque mode une fois :
- aucune erreur dans la console ;
- la largeur téléphone (420 px) n'a pas de défilement horizontal ;
- le clavier et le mode sombre fonctionnent.
Phase 5 : Enregistrements d'écran réels (optionnels)
Si l'application a une UI que vous pouvez exécuter localement, enregistrez les parcours avec Playwright. Un starter est scripts/record_journey.example.mjs. Règles pour les enregistrements :
- pilotez l'UI réelle, sans réponses simulées ;
- ajoutez une légende par étape ;
- accélérez les attentes inactives, et légendez l'accélération ;
- enregistrez
atSecpar étape dansmanifest.json; - marquez les enregistrements partiels comme partiels.
Le visualiseur synchronise une vidéo avec la carte, de sorte que la vidéo devient l'horloge.
Phase 6 : Conseil de relecture croisée
Utilisez deux relecteurs indépendants si possible : deux modèles ou agents différents, ou au moins un contexte frais sans accès au raisonnement de l'auteur. Suivez references/protocol.md :
- l'auteur ne note jamais son propre travail ;
- le relecteur reçoit les fichiers et le code, jamais les conclusions de l'auteur ;
- le relecteur exécute le vérificateur indépendant et échantillonne les affirmations par rapport à la source : la règle d'échantillonnage unique dans protocol.md (tous les éléments disponibles en dessous de ses minima) ;
- les résultats vont dans
reviews/<relecteur>-<tour>.mdavec sévérité, preuve et un correctif concret ; - porte d'acceptation : un ACCEPT, REJECT ou BLOCKED explicite pour l'architecture, les parcours, le deep, la page/données et le bundle figé. Seuls les défauts matériels justifient REJECT : une conclusion erronée, un chemin impossible, ou une tâche centrale bloquée. Les limites déclarées, les marqueurs honnêtes
unavailableet la nature statique des traces ne sont pas des motifs de rejet ; - utilisez un budget de relecture limité ; arrêtez-vous avec REJECT/BLOCKED et preuve conservée si non résolu. Re-relisez l'artefact construit exactement, pas une description de celui-ci.
Porte : tous les artefacts du bundle figé sont acceptés par une relecture indépendante. Ne fabriquez jamais de chemins pour atteindre un quota d'échantillonnage.
Phase 7 : Publication et rapport
Dites à l'utilisateur ce qu'il y a dans la page, avec des comptes réels :
- fonctions, décisions, parcours et résultats tracés ;
- combien de résultats sont indisponibles, et pourquoi ;
- ce qui a été relu en croisé.
Rapportez les limites clairement.
Scripts
| Script | Objectif |
|---|---|
census.py | Recensement des définitions multi-langages (le dénominateur de couverture) |
scaffold_deep.py | Carte provisoire au niveau fonction à partir du recensement et de l'architecture |
merge_deep.py | Fusionner les cartes partielles ; réconcilier les IDs par fichier et ligne |
validate.py | Chaque porte : schéma, références, couverture, sauts silencieux, successeurs, cohérence des sélecteurs |
build_site.py | Exporter les données compactes de la vue Code et construire le site d'une seule page |
record_journey.example.mjs | Starter Playwright pour les vidéos de parcours d'écran réel |
Les scripts Python nécessitent Python 3.9+ et uniquement la bibliothèque standard. Les assistants .mjs optionnels pour navigateur/enregistrement nécessitent un Playwright disponible séparément. La page n'utilise pas de frameworks ni de requêtes externes.