générateur-de-diagrammes

Générateur de Diagrammes

ACTION REQUISE (à lire et exécuter immédiatement)

1. MAINTENANT : Confirmer si la tâche actuelle correspond au champ d'application de cette compétence.
2. MAINTENANT : Lire ../tool-index.md pour vérifier la disponibilité et le chemin réel des outils.
3. SUIVANT : Si un outil manque, appeler le bootstrap, ne pas deviner le chemin.
4. AGIR : Entrer dans la première étape du "workflow" et l'exécuter, ne pas rester dans l'état de confirmation.

Objectif

Créer des diagrammes clairs et modifiables à partir d'entrées désordonnées ou structurées. Privilégier d'abord une source de diagramme textuelle afin que le résultat puisse être révisé, versionné et affiné. Ne générer des fichiers que lorsque l'utilisateur demande une image/PDF ou qu'un artefact téléchargeable serait réellement utile.

Workflow par défaut

1. Identifier l'intention, le public et le matériel source de l'utilisateur.
2. Choisir la famille de diagrammes et le langage à l'aide du tableau de décision ci-dessous.
3. Normaliser les entités, relations, étiquettes, états, branches et informations de temps/ordre avant d'écrire le code du diagramme.
4. Générer un code de diagramme concis et lisible.
5. Valider la syntaxe mentalement et, lors de la création de fichiers, exécuter scripts/render_diagram.py.
6. Renvoyer le code source du diagramme ainsi qu'une brève note sur les hypothèses. Lorsque des fichiers sont générés, inclure des liens vers les fichiers de sortie.

Ne pas trop demander de clarifications. Si la demande est sous-spécifiée, faire des hypothèses raisonnables et les étiqueter brièvement.

Tableau de décision du langage de diagramme

Utiliser Mermaid sauf si un autre langage est clairement meilleur.

L'utilisateur veut	Langage préféré	Pourquoi
flux de processus, arbre de décision, couloir simple	Mermaid flowchart	lisible et facile à coller dans le Markdown
séquence d'interactions système/utilisateur	Mermaid sequenceDiagram ou PlantUML sequence	Mermaid pour la documentation ; PlantUML pour le formalisme UML
cycle de vie, machine à états, transitions	Mermaid stateDiagram-v2 ou PlantUML state	syntaxe de transition compacte
schéma de base de données, entités, relations	Mermaid erDiagram	notation ER portable
modèle de classes/interfaces/objets	Mermaid classDiagram ou PlantUML class	Mermaid pour la documentation ; PlantUML pour l'UML détaillé
planning de projet	Mermaid gantt	syntaxe concise pour les chronologies
hiérarchie, idées, notes	Mermaid mindmap	bon défaut pour les cartes d'idées
parcours client/produit	Mermaid journey	notation de parcours intégrée
historique git	Mermaid gitGraph	notation git intégrée
graphe de dépendances, graphe de paquets, grand réseau	Graphviz DOT	meilleurs moteurs de disposition pour les graphes denses
architecture avec couches, clusters, limites	Mermaid flowchart avec sous-graphes, Graphviz clusters, ou PlantUML style C4	choisir en fonction de la fidélité demandée
flux pondéré/relation type Sankey	Mermaid sankey-beta si pris en charge, sinon SVG ou Graphviz	la prise en charge de Mermaid peut varier selon le moteur de rendu
visuel personnalisé où les langages source s'adaptent mal	SVG	contrôle précis de la disposition et du style

Politique de sortie

• Fournir toujours une source modifiable sauf si l'utilisateur demande explicitement uniquement une image.
• Par défaut, fournir un seul diagramme optimal. Proposer des alternatives uniquement si elles sont réellement utiles.
• Privilégier une syntaxe stable et simple plutôt que des fonctionnalités sophistiquées qui pourraient ne pas s'afficher correctement dans les anciennes versions de Mermaid/PlantUML.
• Utiliser des étiquettes courtes. Fractionner le texte long dans des notes en dehors du diagramme si nécessaire.
• Éviter les identifiants de nœuds ambigus. Utiliser des identifiants ASCII et des étiquettes lisibles par un humain.
• Préserver la terminologie de l'utilisateur, mais normaliser les majuscules à l'intérieur d'un diagramme.
• Pour les diagrammes techniques, inclure les limites telles que client, service, base de données, file d'attente, API externe et opérateur/utilisateur lorsqu'elles sont implicites.
• Pour les diagrammes de processus métier, distinguer le chemin heureux, les points de décision, les échecs, les tentatives et les étapes manuelles lorsqu'ils sont présents.
• Pour les diagrammes créés à partir d'un texte incertain, inclure une section Hypothèses après le code.

Règles de génération Mermaid

Consulter references/diagram-patterns.md pour des modèles compacts.

Règles générales pour Mermaid :

• Commencer par la directive de diagramme correcte, par exemple flowchart TD, sequenceDiagram, erDiagram, gantt, mindmap, ou journey.
• Pour les organigrammes, utiliser flowchart TD sauf si l'utilisateur demande de gauche à droite ; utiliser flowchart LR pour l'architecture et les pipelines.
• Utiliser des sous-graphes pour les couloirs ou les couches d'architecture. Nommer les sous-graphes avec des étiquettes lisibles.
• Garder les identifiants de nœuds stables et uniquement ASCII, par exemple ingest_service[Service d'Ingestion].
• Mettre entre guillemets les étiquettes contenant une ponctuation susceptible de dérouter l'analyseur syntaxique.
• Utiliser des losanges de décision pour les embranchements : decision{Condition ?}.
• Utiliser des étiquettes de arêtes cohérentes : -- oui -->, -- non -->, -. asynchrone .->, ou == critique ==> uniquement lorsqu'elles sont significatives.
• Dans les diagrammes de séquence, déclarer les participants avant les messages. Utiliser actor pour les humains et participant pour les systèmes.
• Utiliser les blocs alt/else/end, opt/end, loop/end, et par/and/end pour les flux conditionnels, optionnels, répétés et parallèles.

Règles de génération Graphviz DOT

Utiliser Graphviz pour les diagrammes de relations grands, denses ou sensibles à la disposition.

• Préférer digraph G pour les relations dirigées et graph G pour les réseaux non dirigés.
• Définir des attributs de graphe favorisant la disposition en haut : rankdir=LR, nodesep, ranksep, et splines=true si nécessaire.
• Utiliser subgraph cluster_nom pour les limites et sous-systèmes.
• Utiliser des étiquettes simples et une mise en forme sobre.
• Utiliser des étiquettes d'arêtes uniquement lorsqu'elles ajoutent du sens.
• Pour de nombreux nœuds, grouper par domaine avec des clusters et éviter les arêtes tous-à-tous qui créent des croisements.

Règles de génération PlantUML

Utiliser PlantUML lorsque l'utilisateur demande de l'UML ou a besoin de notation UML formelle.

• Encadrer les diagrammes avec @startuml et @enduml.
• Utiliser les stéréotypes actor, participant, database, queue, collections, ou component si nécessaire.
• Utiliser package, rectangle, ou node pour les limites d'architecture.
• Pour les diagrammes de classes, inclure uniquement les champs/méthodes importants sauf si l'utilisateur demande un niveau de détail exhaustif.
• Pour les diagrammes d'activités, utiliser des marqueurs de début/fin clairs et des étiquettes de branche explicites.

Règles de génération SVG

Utiliser SVG uniquement lorsque les langages de diagramme textuels ne peuvent pas exprimer de manière fiable le visuel demandé.

• Garder le SVG simple, accessible et modifiable.
• Inclure <title> et des étiquettes de texte significatives.
• Privilégier les rectangles, lignes, flèches et groupes plutôt que les chemins complexes.
• Ne pas intégrer de polices externes ou d'images distantes.

Génération de fichiers

Lorsque l'utilisateur demande un PNG/SVG/PDF, créer un fichier source et exécuter :

python "<RACINE_COMPETENCE>/diagram-generator/scripts/render_diagram.py" input.mmd --format svg --out output.svg
python "<RACINE_COMPETENCE>/diagram-generator/scripts/render_diagram.py" input.dot --format png --out output.png
python "<RACINE_COMPETENCE>/diagram-generator/scripts/render_diagram.py" input.puml --format svg --out output.svg

<RACINE_COMPETENCE> est le chemin réel du répertoire skills/ de ce package, que l'IA doit détecter automatiquement.

Le moteur de rendu est intentionnellement tolérant en matière de dépendances. Il essaie les outils locaux courants et signale des conseils d'installation exploitables si un moteur de rendu est indisponible. Ne pas prétendre qu'une image a été rendue à moins que le script ne se soit terminé avec succès et que le fichier de sortie existe.

Liste de validation

Avant de finaliser :

• Le type de diagramme correspond à la tâche de l'utilisateur.
• La source est syntaxiquement plausible pour le langage choisi.
• Les étiquettes sont suffisamment courtes pour tenir.
• L'ordre des arêtes et messages reflète fidèlement l'entrée.
• Les hypothèses sont mentionnées lorsque l'entrée était incomplète.
• Pour les fichiers générés, la sortie existe et s'ouvre ou a une taille non nulle.

Modèle de réponse courant

Utiliser cette structure pour la plupart des réponses de diagramme :

Voici la version modifiable en [langage] :

```[langage]
[source]

Hypothèses :

• [uniquement si nécessaire]

Fichier rendu : [lien] [uniquement si généré]

Pour les requêtes d'utilisateur en anglais, répondre en anglais. Pour les requêtes d'utilisateur en français, répondre en français sauf demande contraire.

---

## Bootstrap à la demande

### Capacités d'automatisation

| Outil | Installation automatique | Méthode d'installation | Description |
|------|-----------|---------|------|
| Mermaid CLI (mmdc) | ✓ | npm install -g @mermaid-js/mermaid-cli | Rendre Mermaid en PNG/SVG |
| Graphviz (dot) | ✗ | Installation manuelle | https://graphviz.org/download/ |
| PlantUML | ✗ | Nécessite Java + plantuml.jar | https://plantuml.com/download |
| Python (script de rendu) | ✓ | Déjà inclus dans le bootstrap | Dépend de `scripts/render_diagram.py` |

### Description

Cette compétence produit principalement du code source de diagramme textuel (Mermaid/DOT/PlantUML), et ne nécessite pas nécessairement d'outil de rendu local. Les moteurs de rendu ne sont nécessaires que lorsque l'utilisateur demande explicitement la génération d'un fichier PNG/SVG/PDF.

Si un moteur de rendu n'est pas disponible, `scripts/render_diagram.py` affiche un conseil d'installation plutôt qu'une erreur.

---

## Contexte de routage

**Entrée en amont** : `skills/SKILL.md` (contrôleur principal), `routing.md`
**Condition de déclenchement** : L'utilisateur dit "dessiner", "organigramme", "diagramme d'architecture", "diagramme de chemin d'attaque", "diagramme de séquence", "Mermaid", "Graphviz", "PlantUML"
**Sortie en aval** :
- Les diagrammes générés peuvent être intégrés dans les rapports de `docs-generator/`
- Les diagrammes de chemin d'attaque peuvent accompagner les rapports de pénétration de `pentest-tools/`

**Modules associés de même niveau** : `docs-generator/` (intégration de diagrammes dans les rapports)

## Auto-vérification de l'achèvement de la tâche (MUST réussir avant de prétendre avoir terminé)

- [ ] Ai-je exécuté chaque étape du workflow (pas seulement lu) ?
- [ ] Ai-je utilisé un chemin d'outil réel basé sur `tool-index` ?
- [ ] Ai-je produit des preuves reproductibles (commandes/scripts/captures d'écran/rapports) ?
- [ ] Ai-je complété et renseigné les éléments de la liste de contrôle demandés par RULES ?