whiteboard

Que fait whiteboard ?

Transformez une explication en un diagramme que l'utilisateur peut voir, conserver et coller partout. Vous écrivez le code source du diagramme ; scripts/render.mjs le rend avec l'outil CLI installé localement par l'utilisateur et vous indique exactement ce qui ne va pas lorsqu'il ne parvient pas à l'analyser.

Flux de travail

1. Choisissez le type de diagramme et le langage. Utilisez Mermaid par défaut. Utilisez D2 pour les grands diagrammes d'architecture avec des conteneurs imbriqués, PlantUML uniquement lorsque l'utilisateur le demande ou que le projet l'utilise déjà. Consultez references/syntax.md pour la syntaxe de chaque type.

2. Lisez avant de dessiner. Lorsque le diagramme décrit du code, lisez le code d'abord. Dessinez ce qui existe, avec des noms réels, pas une image générique. Pour les demandes concernant l'ensemble du projet (architecture, flux de contrôle, modèle de données), suivez references/modes.md.

3. Écrivez le code source et effectuez le rendu. Transmettez-le sur l'entrée standard avec un titre court (80 caractères maximum). Le titre nomme les fichiers, donc réutilisez-le lorsque vous redessinez le même diagramme :

   node <dossier-compétence>/scripts/render.mjs --title "Séquence de paiement" <<'EOF'
   sequenceDiagram
     Browser->>API: POST /checkout
     API->>Payments: charge(carte)
     Payments-->>API: ok
     API-->>Browser: 201 Created
   EOF
   

   <dossier-compétence> est le dossier où se trouve ce fichier. Ajoutez --language d2 ou --language plantuml pour ces langages. Sous Windows, ou lorsque les heredocs sont maladroits, écrivez le code source dans un fichier temporaire et passez --file <chemin> à la place.

4. Corrigez et relancez en cas d'échec. Un code de sortie 1 signifie que le moteur de rendu a rejeté le code source ; le message indique la ligne. Corrigez cette ligne et exécutez la même commande à nouveau. Ne remettez pas à l'utilisateur un diagramme qui n'a pas été rendu. Les corrections courantes sont listées à la fin de references/syntax.md.

5. Faites un rapport concis. Dites ce que montre le diagramme et donnez les chemins de fichiers imprimés par le script (par exemple diagrams/sequence-paiement.svg). Si l'utilisateur souhaite le coller dans un README, un ticket ou un wiki, donnez le code source dans un bloc ```mermaid : GitHub, GitLab et Notion le rendent.

Référence du script

Option	Utilisation
--title <texte>	Obligatoire. Nomme les fichiers : diagrams/<slug>.svg et le code source à côté.
--language <nom>	mermaid (par défaut), d2 ou plantuml.
--file <chemin>	Lit le code source depuis un fichier au lieu de l'entrée standard.
--out <dossier>	Dossier de sortie ; par défaut diagrams dans le dossier courant.
--png	Écrit également un PNG (diaporamas, applications de chat, terminaux qui affichent des images).
--theme <nom>	default, neutral, dark ou forest.
--config <fichier>	Un fichier de configuration JSON pour Mermaid, pour les couleurs et polices de l'équipe.
--check	Validation uniquement ; n'écrit rien.
--open	Ouvre le SVG dans le visualiseur par défaut de l'utilisateur. Utilisez-le lorsque l'utilisateur veut voir le diagramme immédiatement.
--share	Téléverse le code source dans un secret GitHub Gist et imprime le lien. Exécutez-le uniquement après que l'utilisateur a demandé à partager et a accepté le téléversement.
--json	Résultat lisible par machine.
--doctor	Vérifie Node, chaque moteur de rendu et la CLI GitHub, et indique quoi installer.

Codes de sortie : 0 rendu effectué, 1 code source rejeté (corrigez et relancez), 2 mauvais arguments, 3 moteur de rendu non installé.

Les diagrammes ne lisent jamais de fichiers locaux, de variables d'environnement ou d'URL dans l'image :

• Mermaid effectue le rendu dans une page navigateur isolée qui ne peut rien charger depuis le réseau ou le disque. Toute syntaxe Mermaid fonctionne, mais les images distantes ou locales et les ressources CSS restent vides ; incorporez une image sous forme d'URL data: si elle doit apparaître.
• PlantUML : les directives autres que les simples (!define, !if, !procedure, !$var, !theme <nom>, !include <stdlib> …), %getenv et les fonctions intégrées similaires, ainsi que <img:…> sont refusées. Incorporez plutôt le contenu.
• D2 : les importations @ sont refusées. Les diagrammes avec des icônes, des chaînes de blocs, du HTML ou des URL sont rendus uniquement en SVG, où ils restent des liens.

Uniquement si l'utilisateur souhaite explicitement des inclusions ou des images externes, relancez avec WHITEBOARD_ALLOW_INCLUDES=1.

Redessiner avec le même titre conserve les fichiers précédents dans diagrams/.versions/<slug>/<n>/, donc itérer sur un diagramme ne perd jamais la version précédente.

Lorsqu'un moteur de rendu est manquant

Le code de sortie 3 imprime la commande d'installation. Dites à l'utilisateur quoi exécuter et n'installez pas vous-même des paquets globaux sauf s'il le demande :

• Mermaid : npm i -g @mermaid-js/mermaid-cli
• D2 : brew install d2, ou voir https://d2lang.com/tour/install
• PlantUML : brew install plantuml ou apt install plantuml (nécessite Java)

Si un moteur de rendu est installé mais pas trouvé (courant dans les applications de bureau qui démarrent sans le PATH du shell de connexion), définissez WHITEBOARD_MMDC, WHITEBOARD_D2 ou WHITEBOARD_PLANTUML avec son chemin complet. Le rendu Mermaid utilise le navigateur et le bundle Mermaid fournis avec mermaid-cli ; si le script trouve mmdc mais pas son paquet, définissez WHITEBOARD_MODEL_MERMAID_CLI_DIR sur le dossier @mermaid-js/mermaid-cli. Lorsque rien ne peut être installé, donnez le code source Mermaid dans un bloc de code délimité pour qu'il soit tout de même rendu sur GitHub, et précisez qu'il n'a pas été vérifié par un moteur de rendu.

Bons diagrammes

• Une idée par diagramme. Divisez tout ce qui dépasse environ 15 nœuds ou 20 messages en un diagramme d'ensemble plus des diagrammes de détail.
• Étiquetez chaque arête avec ce qui circule ou se produit (HTTP, publie OrderPlaced, 1..*).
• Utilisez les noms du code : noms de classes, de modules et de services, points d'accès réels, tables réelles.
• Choisissez le type qui correspond à la question : qui appelle qui dans le temps → séquence ; quelles sont les parties → architecture/organigramme ; à quoi ressemblent les données → ER ou classes ; comment quelque chose change dans le temps → état.
• Gardez le texte court à l'intérieur des nœuds ; mettez les détails dans les étiquettes d'arêtes ou les notes.