repoviz

Que fait repoviz ?

Transformez une base de code en URL de diagrammes prêts à être rendus. Chaque diagramme est une simple URL https://x-cmd.com/draw (paramètres plats, encodés en pourcentage) qui affiche du SVG dans les navigateurs, les README GitHub et tout visualiseur Markdown. Le mode par défaut n'écrit aucun fichier local ; l'export local n'a lieu que sur demande explicite via scripts/.

Rendu ≠ vérité : chaque nœud et arête porte une preuve source (vérifié / déduit / inconnu) — le résultat est un actif vérifiable, pas un croquis IA.

Étape 1 — Analyse d'intention & routage des diagrammes

Choisissez le(s) type(s) de diagramme à partir de l'intention et de la forme du dépôt. Lisez uniquement le(s) fichier(s) references/ correspondant(s) avant de construire ce diagramme.

Intention utilisateur	Diagramme	Référence
Vue d'ensemble du système, hiérarchie des dossiers, microservices, pile technique	Carte d'architecture (/draw/archmap)	references/architecture.md
Cycle de vie des requêtes, chaînes d'appels de fonctions, échanges API	Diagramme de séquence (/draw/seq)	references/flowchart.md
Logique conditionnelle, algorithmes, étapes d'authentification/pipeline	Organigramme (/draw/mermaid)	references/flowchart.md
Machines d'état, statuts, tentatives/rollback	Cycle de vie (/draw/lifecycle)	references/flowchart.md
Pipelines de données, poids des dépendances/bundles, routage du trafic	Sankey (?type=sankey)	references/sankey.md
Arbres de fonctionnalités, taxonomie des modules	Carte mentale (/draw/mindmap)	references/general-charts.md
Roadmaps, plannings, plans de version	Gantt (/draw/gantt)	references/general-charts.md
Métriques quantitatives du dépôt (répartition des langages, couverture, croissance)	Graphiques de données (`?type=pie	hbar
« Visualise ce dépôt » au sens large	Suite multi-diagrammes : 1 vue d'ensemble archmap + 1 Sankey (flux de données/dépendances) ou seq (flux de requêtes principal)	les deux références correspondantes

Frères de même grammaire d'archmap (voir references/architecture.md) : arch2 (autre apparence). Modélisation de données/comportement : uc, dataflow, erd, class — grammaires et exemples vivants dans references/technical-diagrams.md. Diagrammes longue traîne (treemap, funnel, graph, ...) : /draw/echarts?d=<option JSON echarts encodée en URL>.

Modes d'analyse — délimitez l'analyse avant de lire le code (l'utilisateur peut choisir ; par défaut selon l'intention) :

Mode	Périmètre	Résultat typique
quick	manifestes, arborescence jusqu'à profondeur 2, points d'entrée	1 diagramme d'ensemble
architecture	modules, services, graphe de dépendances	archmap (+ Sankey par poids)
deep-dive	chaînes d'appels, flux de données, machines d'état	seq / organigramme / suite Sankey
impact	git diff vs base : fichiers modifiés et leurs dépendants	diagramme de flux de changement
full	tout ce qui précède	Rapport de dépôt (suite + rapport qualité)

Le mode impact charge references/architecture-diff.md (flux de travail des différences git) ; le mode full charge references/codebase-report.md (structure de rapport standard) ; les analyses répétées du même dépôt peuvent charger references/incremental-scan.md (protocole de cache optionnel) ; le travail multi-diagrammes ou sensible aux preuves charge references/repository-ir.md.

Étape 2 — Analyse du code avec discipline de jetons

1. Lisez d'abord les manifestes racine : package.json, go.mod, Cargo.toml, pyproject.toml, docker-compose.yml, plus une arborescence des répertoires jusqu'à profondeur 3 et les points d'entrée déclarés.
2. Ne lisez jamais chaque fichier source. Échantillonnez les fichiers de points d'entrée et les tables de routage ; résumez les composants en nœuds et arêtes à fort signal.
3. Dérivez les poids Sankey à partir de quantités réelles lorsque c'est possible : tailles de fichiers (du -sh), nombres d'imports/références, ou chiffres de trafic/coût fournis par l'utilisateur.
4. Garde-fou de longueur d'URL : limitez un diagramme à ~15–20 nœuds (~60 liens pour Sankey) pour que les URL restent lisibles et dans les limites du CDN. Pour les grands dépôts, émettez un diagramme d'ensemble de haut niveau + un diagramme par sous-système, jamais un seul méga-diagramme dense.
5. Détectez le langage et la pile à partir des manifestes et analysez avec cette optique : Go → packages/interfaces/goroutines ; TypeScript → modules/graphe d'imports/routes API ; Rust → crates/traits/fonctionnalités ; Python → packages/décorateurs/points d'entrée.
6. Enregistrez les preuves au fur et à mesure de l'analyse : chaque nœud/arête reçoit fichier[:symbole[:lignes]] et un niveau — vérifié (vu dans le code), déduit (dérivé de la structure), ou inconnu (hypothèse de motif). Ne marquez jamais vérifié sans avoir ouvert le fichier.

Étape 3 — Construisez l'URL

• Construisez d'abord l'IR léger du dépôt pour les suites (un inventaire de nœuds partagé, un document par diagramme) ; mappez IR → URL au moment de l'encodage. Schéma et protocole de validation : references/repository-ir.md.
• Chaque URL que vous construisez porte ses libellés vers le moteur de rendu — appliquez la règle de confidentialité de l'Étape 4 avant de la construire, la valider ou l'exporter.
• Grammaire (nœuds/arêtes/limites), table d'encodage, exemples détaillés et limites par type se trouvent dans les fichiers de référence. Suivez-les exactement ; chaque exemple qui s'y trouve est testé en direct.
• Les essentiels d'encodage : espace %20, + %2B, & %26, # %23, </> %3C/%3E, saut de ligne %0A ; les séparateurs ; = , : / @ restent littéraux. Pas de Base64.
• Modificateurs courants : title=, scheme=dark|light, t=<style> (familles par type dans les références — arch2/seq rendent mieux avec t=shadcn ; les nœuds arch2 prennent un champ icon optionnel en 6e position, par ex. n=api;be;API;ECS;r2c0;aws:ecs), w=/h=, v=N pour épingler une version mise en cache, num=all|peak|none (graphiques).
• La sortie PNG intègre un sous-ensemble CJK de niveau 1 GB2312 : les caractères rares (par ex. 渲) deviennent tofu dans PNG. SVG n'a pas cette limite — préférez des synonymes courants pour les libellés chinois en PNG.
• En cas de 4xx, le corps de la réponse est en texte brut avec un exemple de correction — lisez-le, corrigez le paramètre fautif, réessayez. Ne devinez jamais deux fois.

Étape 4 — Remise du résultat

Mode par défaut — aucun fichier écrit. Répondez avec, par diagramme :

### <Titre du diagramme>
![<titre>](<draw-url>)
*[Aperçu interactif](<draw-url>)* · [Ouvrir dans l'éditeur](<explore-url>)

- <puce : ce que montre le diagramme — niveaux, chemin critique, flux les plus lourds>
- <puce : couplage notable / points uniques de défaillance / limites de propriété>

• <explore-url> réécrit /draw?type=X&q → /draw/explore?type=X&q et /draw/<nom>?q → /draw/explore/<nom>?q — l'éditeur interactif intégré de draw ; liez-le, ne le reconstruisez pas.
• 2 à 5 puces serrées par diagramme. L'image est le livrable ; les puces ajoutent du jugement.
• Confidentialité : le rendu — ainsi que la validation L1 et les téléchargements export.sh — envoie les libellés du diagramme (pour les organigrammes, tout le texte du programme) au moteur de rendu x-cmd.com comme paramètres d'URL ; ils peuvent apparaître dans les journaux d'accès du serveur (l'encodage en pourcentage n'est pas un chiffrement), et les images Markdown intégrées peuvent être récupérées automatiquement par les clients ou les proxies. L'export local n'évite pas cela — le rendu est toujours demandé à x-cmd.com. Pour les dépôts confidentiels, prévenez l'utilisateur et obtenez une approbation explicite avant de rendre, valider ou exporter — ou effectuez le rendu complètement hors ligne via un CLI draw installé localement.

Clôturez une suite avec le rapport qualité (comptes réels uniquement — n'inventez jamais) :

Analyse du dépôt — <repo> (<scan_mode>, <commit>)
Fichiers inspectés : N | Modules : N | Relations : N
Preuve : vérifié N · déduit N · inconnu N
Validation : L1 réussi|ignoré (confidentialité) · L2 réussi · L3 : N non résolus (signalés ci-dessous)

L1 n'est pas automatique — elle récupère l'URL, c'est-à-dire qu'elle envoie le diagramme à x-cmd.com. Pour les dépôts confidentiels, exécutez-la uniquement avec l'approbation explicite de l'utilisateur (règle de confidentialité de l'Étape 4) ; sinon, signalez L1 ignoré (confidentialité). Signalez chaque inconnu sous son diagramme. Pour les demandes explicites de « validation » ou les vérifications avant export : bash scripts/validate.sh <urls...> (rendu L1) et bash scripts/validate.sh --ir <ir.json> (structure L2). L3 est votre relecture des fichiers cités.

Mode export — uniquement lorsque l'utilisateur dit explicitement « sauvegarde locale », « télécharge SVG/PNG », « exporte l'image », « lien court », « mets ceci dans mon README », ou « génère un rapport HTML » :

bash scripts/export.sh "<draw-url>" "<out.svg|png>"        # téléchargement unique
bash scripts/export.sh --batch <manifest.tsv>              # plusieurs : "<url>\t<sortie>" par ligne, # commentaires
bash scripts/shorten.sh <type> '<d-schema json>' [titre]   # /draw/c/<hash> permanent (?type= graphiques uniquement)
bash scripts/build_html.sh "<titre>" "<out.html>" '<json>' # rapport autonome (+ preuves ev optionnelles)
bash scripts/inject_readme.sh "<README.md>" '<json>'       # insérer/mettre à jour les diagrammes entre les marqueurs repoviz

• export.sh télécharge via curl (solution de repli : CLIs déjà installés localement — il ne récupère ni n'installe jamais de paquets) ; les cibles .png obtiennent automatiquement &format=png (ajoutez &scale=2|3 pour une résolution plus élevée ; passez scheme=dark — PNG utilise par défaut le clair). Mode batch : une url<TAB>sortie par ligne, les # commentaires sont autorisés ; sortie non nulle si un élément échoue.
• shorten.sh POSTe la définition du graphique (le schéma JSON ?d=) vers x-cmd.com — limite de débit ~30/min/IP. Seule la famille ?type= accepte POST ; les diagrammes nœuds/arêtes (/draw/archmap, /draw/seq, ...) renvoient 405 — conservez leurs URL complètes. Le /draw/c/<hash> renvoyé se rend avec GET et est permanent. Exécutez-le uniquement sur demande explicite de l'utilisateur : la définition stockée est permanente et publique pour quiconque possède le lien (règle de confidentialité de l'Étape 4).
• build_html.sh prend un tableau JSON d'objets {"title","url","note"[,"ev"]} (url restreint aux URL de rendu draw de https://x-cmd.com / https://www.x-cmd.com ; ev optionnel, encodé "node|file|symbol|lines|level;..." — affiche un tableau de preuves Source filtrable) et émet un rapport autonome responsive clair/sombre : navigation latérale, zoom, plein écran, boutons de copie d'URL, compatible impression en PDF. Toutes les valeurs sont échappées HTML. Exemple de charge utile : [{"title":"Architecture","url":"https://x-cmd.com/draw/archmap?...","note":"3 niveaux ; la passerelle est l'entrée unique","ev":"api|src/api.ts|createServer|12-40|verified"}]
• inject_readme.sh est idempotent : ajoute un bloc <!-- repoviz:start --> … <!-- repoviz:end --> (image Markdown + note par diagramme) lors de la première utilisation, le remplace sur place lors des exécutions ultérieures — les diagrammes deviennent des actifs vivants dans le dépôt.
• Après l'exportation, affichez le(s) chemin(s) sauvegardé(s) et continuez à produire le bloc Markdown pour le chat afin que l'utilisateur obtienne les deux.

Règles

• Neutre en marque : présentez les résultats comme des diagrammes repoviz ; ne renommez ni n'encapsulez jamais les URL de rendu.
• Une analyse, plusieurs diagrammes : réutilisez l'inventaire des nœuds dans toute la suite au lieu de relire le dépôt pour chaque diagramme.
• Préférez moins de nœuds, bien choisis, plutôt que l'exhaustivité ; réduisez les détails dans des légendes sub et des boîtes de limites.
• Pas de preuve, pas de résultat : chaque nœud/arête est vérifié, déduit ou marqué inconnu — jamais fabriqué. Maintenez la séparation IR/moteur de rendu afin que les suites, les rapports et les futures différences d'architecture partagent un seul inventaire ; le rendu reste un adaptateur remplaçable.
• Modifications incrémentielles via URL comme données : un diagramme repoviz existant est entièrement défini par son URL — n'utilisez jamais d'outils de vision ou de lecture d'image pour l'inspecter. Décodez l'URL depuis le Markdown, comparez son ensemble nœuds/arêtes avec le code actuel, et émettez l'URL mise à jour en place, en préservant les identifiants de nœuds, les libellés et les conventions de disposition.