cubxxw/archify

Que fait archify ?

Créez un diagramme HTML autonome et interactif à 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.

Chemin de création rapide

Utilisez ce chemin limité pour la génération courante. Ne lisez pas la référence facultative du Runtime Visualiseur sauf si l'utilisateur pose des questions sur ces fonctionnalités.

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 signifie de nouveaux identifiants stables, un vocabulaire spécifique au domaine et une disposition différente ; 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 composants internes du moteur de 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 dense standard. Commencez par 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 basique, jamais une acceptation de type « showcase ». Un passage en mode « showcase » doit reporter 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 fige le candidat : ne le modifiez jamais après.

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

   node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
   

   Une sortie non nulle ne peut jamais être décrite comme un succès. Si la validation échoue, modifiez uniquement le « sujet » diagnostiqué, vérifiez les « preuves », choisissez parmi les supportedFixes et réexécutez. Continuez les corrections ciblées tant que le nombre d'erreurs objectives atteint un nouveau minimum. Si deux cycles 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 code source du moteur de rendu, celui 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.

Note sur le cycle de vie : les colonnes de phase 0..4 occupent le rail principal ; les colonnes d'événements/résultats 0..2 s'alignent sous les phases ultérieures. Un état récupérable utilise type: "failure" plus une transition réelle vers l'état actif.

Routeur de types

Type	Utilisation pour
architecture	Composants, services, limites cloud/sécurité, infrastructure
workflow	Processus, points de validation, 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, lignée, 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 scénarios sont des références structurelles, pas des faits à copier.

Entrée Mermaid

Lisez le code Mermaid pour la topologie et la signification, puis créez un nouveau fichier 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 signification, pas le style Mermaid.

Invariants de création

• Un seul chemin principal évident ; les branches secondaires partent du 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 honnête auto. Lorsque nécessaire, utilisez uniquement mode: auto|all|hidden et entries.<kind>.label|visible pris en charge par le moteur de 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 la largeur de son masque mesurée ; sinon, omettez l'étiquette ou déplacez-la délibérément.
• Les routes automatiques possèdent leurs côtés de point 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 moteur de rendu pour les diagrammes d'architecture, de workflow, de flux de données et de cycle de vie. Elle ignore les relations uniques et les routes explicites via, channelX, channelY, labelAt ou non auto. Les ports presque parallèles utilisent un pont extérieur afin que le routage automatique ne puisse pas créer un segment de moins de 8 px ou un virage intérieur de moins de 16 px.
• 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 d'énumérations de champs, de calculs d'espacement, de règles de réparation géométrique, de preuves de référentiel ou de placement spécifique à un mode.

Remise

Utilisez validate pendant la réparation et deliver une seule fois pour l'acceptation finale. La remise fige les octets exacts de la spécification dans un instantané privé dans le même répertoire, rend et vérifie cet instantané, valide atomiquement le HTML et rapporte SHA-256 ainsi que le nombre 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 création active sur le bureau, la commande facultative 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 lors de l'utilisation de l'aperçu, des preuves de référentiel, des reçus d'exportation, de l'examen visuel ou de l'ouverture post-validation.

Capacités facultatives du visualiseur

Le HTML généré contient déjà la commutation de thème, le zoom/panoramique, la recherche, la mise au point, le traçage des relations, les vues sémantiques, la présentation et les exportations fiables. Ce sont des capacités du lecteur, pas un travail de création supplémentaire. meta.animation: "trace" est optionnel ; meta.views est facultatif 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 d'itinéraire/de portée, l'animation, des histoires guidées, des liens profonds, la présentation, la recherche/la mise au point ou toute autre fonctionnalité du Runtime 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 est indisponible, 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 d'examen visuel 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 réel de l'examen visuel. Ne prétendez pas réussir pour une commande non nulle ou revendiquez une inspection visuelle que vous n'avez pas effectuée.