amirtaherkhani/diago

Archify

Crea un diagrama HTML interactivo y autocontenido a partir de una pequeña especificación JSON tipada. La salida estática es la opción predeterminada; habilita la animación solo cuando el usuario solicite una demostración o presentación.

Ruta de autoría rápida

Usa esta ruta acotada para la generación ordinaria. No leas la referencia opcional del Visor (Viewer Runtime) a menos que el usuario pregunte sobre esas funcionalidades.

1. Elige architecture, workflow, sequence, dataflow o lifecycle según la pregunta.

2. Lee un esquema coincidente en schemas/, schemas/common.schema.json y un ejemplo JSON coincidente en examples/. Lee solo esos archivos. La autoría fresca significa nuevos IDs estables, redacción de dominio y diseño; usa el ejemplo para la forma de los campos, no para los hechos.

3. Artefacto primero: la siguiente acción de herramienta debe escribir el candidato. Escribe el candidato antes de inspeccionar los detalles internos del renderizador. No planifiques coordenadas exactas en prosa. Comienza con una ruta principal clara, ramas secundarias cortas, etiquetas dispersas y un máximo de 12 nodos primarios. Establece meta.quality_profile en "showcase" a menos que el usuario solicite explícitamente un mapa standard denso. Comienza con rutas y etiquetas automáticas. No agregues via, channelX, channelY o labelAt antes de que un diagnóstico lo requiera; aplica como máximo un control de geometría diagnosticado por reparación.

4. Valida después de cada edición del candidato e inmediatamente antes de la entrega:

   node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
   

   Un recibo con solo 4 comprobaciones de artefacto es validación básica, nunca aceptación de showcase. Una aprobación de showcase debe reportar las 9 comprobaciones de artefacto con 0 errores de composición y 0 advertencias. Si el candidato omite o escribe incorrectamente el campo exacto meta.quality_profile, corrígelo antes de la geometría. Una validación final exitosa congela el candidato: nunca lo edites después.

5. Para un HTML entregado, deliver es el comando de aceptación final:

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

   Una salida distinta de cero nunca puede describirse como éxito. Si la validación falla, cambia solo el subject diagnosticado, verifica evidence, elige entre supportedFixes y vuelve a ejecutar. Continúa la corrección enfocada mientras el conteo de errores objetivo alcance un nuevo mínimo. Si dos rondas consecutivas no mejoran ese mejor conteo, detente e informa los diagnósticos no resueltos con honestidad.

No leas renderers/shared/geometry.mjs, el código fuente del renderizador, el validador, las pruebas o los benchmarks antes del primer candidato. Inspecciona la implementación solo para un diagnóstico interno no soportado o después de que dos reparaciones enfocadas fallen.

Nota sobre el ciclo de vida: las columnas de fase 0..4 ocupan el carril principal; las columnas de evento/resultado 0..2 se alinean debajo de las fases posteriores. Un estado recuperable usa type: "failure" más una transición real de regreso al estado activo.

Enrutador de tipos

Tipo	Uso
architecture	Componentes, servicios, límites de nube/seguridad, infraestructura
workflow	Procesos, puertas de aprobación, llamadas a herramientas, runbooks, CI/CD
sequence	Cadenas de llamadas API, ciclos de vida de solicitudes, trazas asíncronas, retornos
dataflow	Pipelines, ETL/ELT, linaje, gobernanza, consumidores
lifecycle	Transiciones de estado/estatus, reintentos, estados de espera y terminales

Cuando sea ambiguo, ejecuta node bin/archify.mjs guide "<escenario>" --json. Los ejemplos de prueba de escenario son referencias estructurales, no hechos para copiar.

Entrada Mermaid

Lee Mermaid para topología y significado, luego crea un nuevo JSON de Archify; no renderices mecánicamente el estilo de Mermaid.

• flowchart / graph → workflow, o architecture para un mapa de componentes.
• sequenceDiagram → sequence; los participantes se convierten en participantes semánticos y las flechas en mensajes.
• stateDiagram → lifecycle; los estados y transiciones conservan el significado, no el estilo de Mermaid.

Invariantes de autoría

• Una ruta principal obvia; las ramas secundarias salen del nodo de la ruta principal más cercano. Elimina bordes de bajo valor antes de agregar controles de enrutamiento.
• Omite meta.legend para el valor predeterminado veraz auto. Cuando sea necesario, usa solo mode: auto|all|hidden y entries.<kind>.label|visible soportados por el renderizador; las etiquetas nunca cambian la semántica.
• Los tipos de componente son frontend, backend, database, cloud, security, messagebus y external; las variantes son default, emphasis, security y dashed.
• Espaciado significa espacio libre claro, no distancia al centro. Para una etiqueta de relación, el espacio libre debe exceder su ancho de máscara medido; de lo contrario, omite la etiqueta o muévela deliberadamente.
• Las rutas automáticas poseen sus lados de punto final. Un lado es un contrato de dirección: el primer y último segmento deben salir/llegar perpendiculares a ese lado.
• La distribución automática de puertos (Automatic Port Spread) es un comportamiento predeterminado del renderizador para arquitectura, flujo de trabajo, flujo de datos y ciclo de vida. Omite relaciones únicas y via, channelX, channelY, labelAt o rutas que no sean auto. Los puertos casi paralelos usan un puente externo para que el enrutamiento automático no pueda crear un segmento de menos de 8 px o un giro interior de menos de 16 px.
• Nunca aceptes un borde que cruce un nodo opaco no relacionado, un corredor compartido ambiguo o una etiqueta de relación que enmascare otra ruta.

Lee references/authoring-contract.md solo cuando necesites enumeraciones de campos, matemáticas de espaciado, reglas de reparación de geometría, evidencia del repositorio o ubicación específica del modo.

Entrega

Usa validate durante la reparación y deliver una vez para la aceptación final. La entrega congela los bytes exactos de la especificación en una instantánea privada del mismo directorio, renderiza y verifica esa instantánea, confirma atómicamente el HTML e informa SHA-256 más recuentos de bytes tanto para la especificación como para el artefacto.

Agrega --open solo cuando el usuario quiera una vista previa local inmediata. Para un bucle de autoría de escritorio activo, el comando opcional es:

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

Nunca inicies la vista previa por defecto. Lee references/delivery-contract.md cuando uses vista previa, evidencia del repositorio, recibos de exportación, revisión visual o apertura posterior a la confirmación.

Capacidades opcionales del visor

El HTML generado ya contiene cambio de tema, panorámica/zoom, búsqueda, enfoque, trazado de relaciones, vistas semánticas, presentación y exportaciones veraces. Estas son capacidades del lector, no trabajo de autoría adicional. meta.animation: "trace" es optativo; meta.views es opcional y debe contener como máximo cinco capítulos seleccionados.

Lee references/viewer-runtime.md solo cuando el usuario pregunte explícitamente sobre Tarjetas Compartidas (Share Cards), Tarjetas de Ruta/Alcance (Route/Reach cards), animación, historias guiadas, enlaces profundos, presentación, búsqueda/enfoque u otra funcionalidad del Entorno de Ejecución del Visor (Viewer Runtime).

Configuración y alternativa

No se requiere instalación dentro del paquete de la habilidad. Verifica con:

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

Cuando no se disponga de acceso al shell, coloca manualmente el SVG de arquitectura en assets/template.html, usa clases semánticas CSS en lugar de colores en línea y sigue el contrato de revisión visual en references/delivery-contract.md.

Salida

Devuelve la ruta HTML verificada, el tipo de diagrama, el resumen de validación, el recibo de especificación/artefacto y el estado veraz de la revisión visual. No afirmes éxito para un comando con salida distinta de cero ni afirmes una inspección visual que no realizaste.