Mirofy

Que fait Mirofy ?

Créez un diagramme HTML interactif et autonome à partir d'une spécification JSON typée de petite taille. La sortie statique est la valeur par défaut ; n'activez l'animation que lorsque l'utilisateur demande une démonstration ou une présentation.

Parcours d'analyse : dériver le diagramme d'un dépôt réel

Lorsque le diagramme doit décrire du code existant, ne l'écrivez pas de mémoire. Dérivez-le :

npm run scan      # dépôt -> graphe de preuves (faits et lacunes)
npm run model     # preuves + documents -> un modèle système
npm run compile   # modèle -> une vue délimitée avec intention

Chaque étape rapporte ce qu'elle n'a PAS pu déterminer. scan enregistre une lacune pour chaque fichier qu'il n'a pas pu analyser, compile enregistre chaque objet qu'il a omis et la raison. Transmettez ces informations à l'utilisateur ; un diagramme qui omet silencieusement la moitié d'un système est pire que celui qui indique ce qu'il a laissé de côté.

Utilisez le parcours rapide ci-dessous lorsque l'utilisateur décrit quelque chose qui n'existe pas encore, ou lorsqu'aucun dépôt n'est disponible.

Parcours de création rapide

Utilisez ce parcours délimité pour la génération courante. Ne lisez pas la référence optionnelle du Runtime Visualiseur sauf si l'utilisateur demande des fonctionnalités spécifiques.

1. Choisissez architecture, workflow, sequence, dataflow ou lifecycle à partir de la question.

2. Lisez un schéma correspondant dans schemas/, schemas/common.schema.json, et un exemple JSON correspondant dans examples/. Lisez uniquement ces fichiers. Une création originale implique de nouveaux ID stables, une terminologie de domaine et une disposition ; utilisez l'exemple pour la forme des champs, pas pour les faits. Lorsque l'identité d'un produit réel est importante, exécutez node bin/mirofy.mjs brands "<nom>" --json ; lisez references/brand-marks.md uniquement pour une marque inconnue avec une URL fournie par l'utilisateur.

3. Artefact d'abord : la prochaine action de l'outil doit écrire le candidat. Écrivez le candidat avant d'inspecter les composants internes du rendu. Ne planifiez pas de coordonnées exactes en prose. Commencez par un chemin principal clair, des branches secondaires courtes, des étiquettes clairsemées et au maximum 12 nœuds principaux. Définissez meta.quality_profile sur "showcase" sauf si l'utilisateur demande explicitement une carte standard dense. Commencez avec des routes et des étiquettes automatiques. N'ajoutez pas via, channelX, channelY ou labelAt avant qu'un diagnostic ne le demande ; appliquez au plus un contrôle géométrique diagnostiqué par réparation.

4. Validez après chaque modification du candidat et immédiatement avant la remise :

   node bin/mirofy.mjs validate <type> <candidat.json> --quality showcase --json
   

   Un reçu avec seulement 4 vérifications d'artefact est une validation de base, jamais une acceptation showcase. Un passage showcase doit rapporter les 9 vérifications d'artefact avec 0 erreur de composition et 0 avertissement. Si le candidat omet ou orthographie mal le champ meta.quality_profile, corrigez-le avant la géométrie. Une validation finale réussie fige le candidat : ne l'éditez jamais ensuite.

5. Pour un HTML livré, deliver est la commande d'acceptation finale :

   node bin/mirofy.mjs deliver <type> <candidat.json> <sortie.html> --quality showcase --json
   

   Un code de sortie non nul ne peut jamais être décrit comme un succès. Si la validation échoue, modifiez uniquement le subject diagnostiqué, vérifiez evidence, choisissez parmi supportedFixes, et relancez. Continuez les corrections ciblées tant que le nombre d'erreurs objectives atteint un nouveau minimum. Si deux tours consécutifs n'améliorent pas ce meilleur compte, arrêtez-vous et rapportez les diagnostics non résolus de manière honnête.

Ne lisez pas renderers/shared/geometry.mjs, le code source du rendu, le code source du validateur, les tests ou les benchmarks avant le premier candidat. Inspectez l'implémentation uniquement pour un diagnostic interne non pris en charge ou après deux réparations ciblées infructueuses.

Routeur de types

Type	Utilisation pour
architecture	Composants, services, limites cloud/sécurité, infrastructure
workflow	Processus, points d'approbation, appels d'outils, runbooks, CI/CD
sequence	Chaînes d'appels API, cycles de vie des requêtes, traces asynchrones, retours
dataflow	Pipelines, ETL/ELT, lignage, gouvernance, consommateurs
lifecycle	Transitions d'état/statut, tentatives, états d'attente et terminaux

En cas d'ambiguïté, exécutez node bin/mirofy.mjs guide "<scénario>" --json. Les exemples de scénarios sont des références structurelles, pas des faits à copier.

Entrée Mermaid

node bin/mirofy.mjs import mermaid <entrée.mmd> [sortie.json] [--json]

flowchart/graph → architecture, sequenceDiagram → sequence, stateDiagram(-v2) → lifecycle.

L'importateur ne devine jamais : toute ligne qu'il ne peut pas lire devient une lacune avec son numéro de ligne, alors signalez ce qui n'a pas été transféré plutôt que de considérer le résultat comme complet. Il n'attribue pas non plus de positions — une architecture convertie utilise layout.mode: "grid", et un éventail peut placer une arête à travers un nœud, ce qui échoue à la porte toujours active clean-flow. Validez toujours après l'importation. Lisez également la source pour le sens : l'importateur transporte la topologie, pas le jugement de domaine, donc les étiquettes et les types méritent souvent d'être réécrits.

Réparation de la géométrie

Lorsque la validation signale des composants qui se chevauchent, ne modifiez pas les coordonnées une par une à la main :

node bin/mirofy.mjs repair <type> <entrée.json> [sortie.json] --safe

--safe est requis car cela réécrit les coordonnées créées. Repair ne déplace que les composants impliqués dans un chevauchement, chacun par la plus petite correction qui efface l'espacement de 8px du validateur, imprime un reçu de chaque ajustement, et ne touche que la géométrie et rien d'autre — jamais une étiquette, un type, une connexion ou un ID. Il revalide et nomme ce que le déplacement ne peut pas corriger (routage, placement d'étiquette) plutôt que de le laisser pour la prochaine exécution.

Invariants de création

• Un chemin principal évident ; les branches secondaires partent du nœud de chemin principal le plus proche. Supprimez les arêtes de faible valeur avant d'ajouter des contrôles de routage.
• Omettez meta.visual_preset par défaut pour que chaque diagramme s'ouvre en mode classic, quel que soit son mode de couleur résolu (clair ou sombre). Le mode de couleur et le préréglage visuel sont indépendants : le passage Clair / Sombre doit préserver le préréglage actuel. Définissez signal-flow, blueprint ou editorial uniquement lorsque l'utilisateur demande explicitement ce style visuel.
• Omettez meta.subtitle par défaut. N'inventez jamais un sous-titre qui répète le titre, les nœuds ou les cartes ; incluez une ligne de soutien courte uniquement lorsque l'utilisateur le demande explicitement.
• Traitez le visualiseur de bureau autonome comme un artefact par défaut sur un écran entier, pas comme une bande peu profonde. Générez un artefact réactif pour les ordinateurs portables et les écrans externes — jamais de HTML spécifique à un appareil ou de topologie alternative. Le visualiseur peut adapter uniquement la largeur de lecture externe à partir de la hauteur de la fenêtre d'affichage en direct ; il doit préserver le SVG/viewBox, les proportions, la géométrie sémantique et le flux de document normal créés. Sur un bureau large ou haut, utilisez suffisamment de rythme vertical créé pour que le panneau du diagramme et ses cartes de conclusion nécessaires occupent l'écran comme un tout équilibré ; la mise à l'échelle au moment de l'exécution ne peut pas réparer une disposition Y trop compressée ou un meta.viewBox explicite trop petit. Avant la remise, ouvrez le vrai HTML à 1440×900, 1600×1000 et 1920×1080 ; vérifiez également à 2048×1320 chaque fois que la composition est destinée à un grand écran de bureau. Exigez document.documentElement.scrollWidth <= window.innerWidth et scrollHeight <= window.innerHeight à chaque taille vérifiée, tout en vérifiant visuellement que le diagramme reste confortablement lisible et verticalement équilibré à la plus grande fenêtre vérifiée. Réparez le débordement en supprimant uniquement le contenu vraiment redondant ou en compressant l'espacement avant de réduire les nœuds, les étiquettes ou le panneau principal. Si la plus grande fenêtre a toujours une bande inférieure vide évidente à la limite de largeur du visualiseur, redistribuez les positions Y créées et augmentez la hauteur du viewBox proportionnellement ; n'ajoutez pas de contenu de remplissage ou de cartes décoratives. Ne falsifiez jamais un passage avec overflow: hidden, du contenu tronqué, un défileur de diagramme interne, une hauteur SVG étirée ou une typographie plus petite. Les mises en page étroites/mobiles peuvent défiler verticalement lorsque le confinement l'exige.
• Omettez meta.legend pour la valeur par défaut véridique auto. Lorsque nécessaire, utilisez uniquement mode: auto|all|hidden et les entries.<kind>.label|visible pris en charge par le rendu ; les étiquettes ne changent jamais la sémantique.
• Choisissez une langue principale créée à partir d'un choix explicite de l'utilisateur ; sinon, suivez la langue dominante de la demande ou de la conversation. meta.locale contrôle uniquement l'interface utilisateur du visualiseur appartenant au rendu : utilisez "en" ou "zh-CN" pour la langue principale prise en charge correspondante. Pour toute autre langue, omettez meta.locale et divulguez explicitement que l'interface utilisateur fixe du visualiseur et <html lang> reviennent à l'anglais. Le rendu ne traduit jamais le contenu créé. Voir references/authoring-contract.md pour les détails.
• Préservez les noms de produits exacts, les identifiants de code, les commandes, les protocoles, les chemins d'API et les noms d'environnement. Ils peuvent rester en anglais dans le texte localisé, mais ne justifiez jamais de laisser la prose explicative environnante dans une autre langue.
• L'identité de la marque est facultative et explicite. Mettez un ID intégré canonique dans brand lorsque le nœud nomme ce produit réel. Si aucun préréglage ne correspond et que l'utilisateur a fourni l'URL HTTP(S) officielle, exécutez d'abord node bin/mirofy.mjs brands capture "<url>" --json, puis créez l'objet brand avec digest retourné. Le rendu et la validation n'effectuent jamais de capture sans digest. Sinon, omettez brand. N'inférez jamais une marque à partir d'un rôle vague comme "base de données", et ne laissez jamais un badge remplacer le type, l'étiquette ou les faits relationnels sémantiques.
• Pour les diagrammes de séquence, omettez meta.column_fit pour la disposition fixed stable. Définissez-le sur "spread" lorsqu'un viewBox large laisserait autrement de l'espace horizontal inutilisé ou lorsque les étiquettes significatives des participants ne tiennent pas dans les zones fixes ; ne raccourcissez pas les étiquettes sémantiques avant d'essayer spread.
• Les types de composants sont frontend, backend, database, cloud, security, messagebus et external ; les variantes sont default, emphasis, security et dashed.
• Les étiquettes relationnelles sont des données sémantiques. Lorsque deux entrent en collision, déplacez l'étiquette, ajustez la route ou l'espacement, puis raccourcissez le libellé tout en préservant le sens. Supprimez une étiquette uniquement lorsque les deux points finaux impliquent pleinement la relation et qu'elle ne contient aucun protocole, action, direction, comportement synchrone/asynchrone ou mécanisme transfrontalier ; expliquez pourquoi l'étiquette supprimée est redondante. Ne supprimez jamais une étiquette significative simplement pour réussir showcase.
• Omettez meta.engineering_profile par défaut. Le libellé de région, de cluster et de limite de sécurité ne l'active pas en soi. Activez deployment-ownership uniquement lorsque l'utilisateur demande explicitement une topologie de déploiement en production, un transfert de propriété, ou une revue de déploiement à verrouillage en cas d'échec et que les faits sources sont connus. Une fois activé, ne doit pas supprimer le profil d'ingénierie simplement pour réussir la validation ; réparez les faits ou rapportez les diagnostics de manière honnête.
• L'espacement signifie un écart clair, pas une distance centrale. Pour une étiquette relationnelle, l'écart clair doit dépasser sa largeur de masque mesurée ; utilisez l'ordre de réparation préservant l'étiquette avant d'envisager la suppression.
• Les routes automatiques possèdent leurs propres côtés d'extrémité. Un côté est un contrat de direction : le premier et le dernier segment doivent partir/entrer perpendiculairement à ce côté.
• L'écartement automatique des ports est un comportement de rendu par défaut pour l'architecture, le workflow, le flux de données et le cycle de vie. Il ignore les relations uniques et les via, channelX, channelY, labelAt ou routes non-auto explicites. Les ports proches parallèles utilisent un pont extérieur afin que le routage automatique ne puisse pas créer un segment de moins de 8px ou un virage intérieur de moins de 16px. L'architecture maintient séparément les ports automatiques non obstrués en vis-à-vis (left/right ou top/bottom) sur un axe commun lorsque leur décalage est inférieur à 16px et que les deux ports conservent un dégagement d'angle. Si exactement une extrémité a été écartée, seule l'extrémité non partagée peut se déplacer sur cet axe ; si les deux extrémités ont été écartées, gardez le pont extérieur pour que les ports en concurrence restent distincts.
• N'acceptez jamais une arête traversant un nœud opaque non lié, un couloir partagé ambigu, ou une étiquette relationnelle masquant une autre route.

Lisez references/authoring-contract.md uniquement lorsque vous avez besoin d'énumérations de champs, de mathématiques d'espacement, de placement automatique des ports, de règles de réparation géométrique, de preuves de dépôt ou de placement spécifique au mode.

Livraison

Utilisez validate pendant la réparation et deliver une fois pour l'acceptation finale. La livraison fige les octets exacts de la spécification dans une capture instantanée privée dans le même répertoire, rend et vérifie cette capture, valide atomiquement le HTML, et rapporte le SHA-256 plus les comptes d'octets pour la spécification et l'artefact.

Après la livraison, collectez des preuves de bureau délimitées sans modifier ni re-rendre le HTML de confiance :

node bin/mirofy.mjs visual-check <sortie.html> --json

visual-check mesure le confinement à 1440×900, 1600×1000, 1920×1080 et 2048×1320 ; capture des captures d'écran en mode clair/sombre aux plus petites et plus grandes tailles ; et écrit une planche contact avec chemin relatif ainsi que des fichiers JSON à côté de l'artefact. Son reçu automatisé rapporte toujours visualReview: "pending" : les captures d'écran sont des preuves pour inspection, jamais une affirmation automatique de qualité. La sortie 0 signifie que le confinement et les captures ont réussi, 1 signifie un débordement ou un échec de capture, et 2 signifie que Chrome/Chromium n'était pas disponible et que le reçu est skipped. La commande ne modifie jamais le HTML livré. Ajoutez --open uniquement lorsque l'utilisateur souhaite un aperçu local immédiat. Pour une boucle de création de bureau active, la commande optionnelle est :

node bin/mirofy.mjs preview <type> <entrée>.json <sortie>.html --quality showcase

Ne démarrez jamais l'aperçu par défaut. Lisez references/delivery-contract.md lors de l'utilisation de l'aperçu, des preuves de dépôt, des reçus d'exportation, de la revue visuelle ou de l'ouverture post-commit.

Capacités facultatives du visualiseur

Le HTML généré contient déjà la commutation de thème, le panoramique/zoom, la recherche, la mise au point, le traçage des relations, les vues sémantiques, la présentation et les exports véridiques. Ce sont des capacités du lecteur, pas un travail de création supplémentaire. meta.animation: "trace" est facultatif ; meta.views est optionnel et doit contenir au maximum cinq chapitres organisés. Lisez references/viewer-runtime.md uniquement lorsque l'utilisateur demande explicitement des cartes de partage, des cartes de route/portée, de l'animation, des histoires guidées, des liens profonds, une présentation, une recherche/focus ou une autre fonctionnalité du Runtime du Visualiseur.

Configuration et repli

Installer la compétence est optionnel.

…

[tronqué pour la traduction]