amirtaherkhani/diago

Archify

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

Parcours de rédaction rapide

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

1. Choisissez architecture, workflow, sequence, dataflow ou lifecycle parmi 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 identifiants stables, une terminologie du domaine et une disposition ; utilisez l'exemple pour la forme des champs, pas pour les faits.

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

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

   node bin/archify.mjs validate <type> <candidate.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 écrit mal le champ exact meta.quality_profile, corrigez-le avant la géométrie. Une validation finale réussie gèle le candidat : ne le modifiez jamais ensuite.

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

   node bin/archify.mjs deliver <type> <candidate.json> <output.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 sujet diagnostiqué, vérifiez les preuves, 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 nombre, arrêtez-vous et rapportez honnêtement les diagnostics non résolus.

Ne lisez pas renderers/shared/geometry.mjs, le source du rendu, le 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 l'échec de deux réparations ciblées.

Note sur le cycle de vie : les colonnes de phase 0..4 occupent la voie principale ; les colonnes d'événement/résultat 0..2 s'alignent en dessous des phases ultérieures. Un état récupérable utilise type: "failure" plus une transition réelle vers l'état actif.

Routeur de type

Type	Utilisation pour
architecture	Composants, services, frontières cloud/sécurité, infrastructure
workflow	Processus, portes 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/archify.mjs guide "<scénario>" --json. Les exemples de preuve de scénario sont des références structurelles, pas des faits à copier.

Entrée Mermaid

Lisez Mermaid pour la topologie et le sens, puis créez un nouveau JSON Archify ; ne reproduisez pas mécaniquement le style Mermaid.

• flowchart / graph → workflow, ou architecture pour une carte de composants.
• sequenceDiagram → sequence ; les participants deviennent des participants sémantiques et les flèches deviennent des messages.
• stateDiagram → lifecycle ; les états et transitions conservent leur sens, pas le style Mermaid.

Invariants de rédaction

• Un chemin principal évident ; les branches secondaires quittent le nœud du chemin principal le plus proche. Supprimez les arêtes de faible valeur avant d'ajouter des contrôles de routage.
• Omettez meta.legend pour la valeur par défaut sincère auto. Si nécessaire, utilisez uniquement mode: auto|all|hidden et entries.<kind>.label|visible pris en charge par le rendu ; les étiquettes ne changent jamais la sémantique.
• Les types de composants sont frontend, backend, database, cloud, security, messagebus et external ; les variantes sont default, emphasis, security et dashed.
• L'espacement signifie un écart clair, pas une distance centrale. Pour une étiquette de relation, l'écart clair doit dépasser sa largeur de masque mesurée ; sinon, omettez l'étiquette ou déplacez-la délibérément.
• Les routes automatiques possèdent leurs côtés d'extrémité. Un côté est un contrat de direction : le premier et le dernier segment doivent quitter/entrer perpendiculairement à ce côté.
• La répartition automatique des ports est un comportement par défaut du rendu pour l'architecture, le workflow, le dataflow et le cycle de vie. Elle ignore les relations uniques et les via, channelX, channelY, labelAt ou routes non auto explicites. Les ports quasi parallèles utilisent un pont extérieur afin que le routage automatique ne puisse pas créer un segment inférieur à 8px ou un virage intérieur inférieur à 16px.
• N'acceptez jamais une arête traversant un nœud opaque non lié, un couloir partagé ambigu ou une étiquette de relation masquant une autre route.

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

Livraison

Utilisez validate pendant la réparation et deliver une seule fois pour l'acceptation finale. La livraison gèle les octets exacts de la spécification dans un instantané privé du même répertoire, rend et vérifie cet instantané, valide atomiquement le HTML et rapporte SHA-256 ainsi que les comptes d'octets pour la spécification et l'artefact.

Ajoutez --open uniquement lorsque l'utilisateur souhaite un aperçu local immédiat. Pour une boucle de rédaction active sur le bureau, la commande optionnelle est :

node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase

Ne démarrez jamais l'aperçu par défaut. Lisez references/delivery-contract.md lorsque vous utilisez l'aperçu, les preuves de dépôt, les reçus d'exportation, la revue visuelle ou l'ouverture après validation.

Capacités optionnelles du visualiseur

Le HTML généré contient déjà la commutation de thème, le panoramique/zoom, la recherche, le focus, le traçage des relations, les vues sémantiques, la présentation et les exportations sincères. Ce sont des capacités du lecteur, pas un travail de rédaction supplémentaire. meta.animation: "trace" est facultatif ; meta.views est optionnel et doit contenir au plus cinq chapitres organisés.

Lisez references/viewer-runtime.md uniquement lorsque l'utilisateur demande explicitement des cartes de partage, des cartes d'itinéraire/d'atteinte, l'animation, des histoires guidées, des liens profonds, la présentation, la recherche/focus ou une autre fonctionnalité du Runtime du visualiseur.

Configuration et repli

Aucune installation n'est requise à l'intérieur du package de compétence. Vérifiez avec :

node bin/archify.mjs doctor
node bin/archify.mjs demo <output-directory>

Lorsque l'accès au shell n'est pas disponible, placez manuellement le SVG d'architecture dans assets/template.html, utilisez des classes sémantiques CSS plutôt que des couleurs en ligne et suivez le contrat de revue visuelle dans references/delivery-contract.md.

Sortie

Retournez le chemin HTML vérifié, le type de diagramme, le résumé de validation, le reçu de spécification/artefact et l'état sincère de la revue visuelle. Ne revendiquez pas de succès pour une commande non nulle ou ne prétendez pas à une inspection visuelle que vous n'avez pas effectuée.