cubxxw/archify

¿Qué hace archify?

Crea un diagrama HTML autocontenido e interactivo a partir de una especificación JSON pequeña y tipada. La salida estática es la opción predeterminada; habilita el movimiento 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 habitual. No leas la referencia opcional del Visor en Tiempo de Ejecución a menos que el usuario pregunte sobre esas características.

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 nueva significa nuevos IDs estables, redacción del 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 planees coordenadas exactas en prosa. Comienza con una ruta principal clara, ramas laterales 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 denso standard. Empieza 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 una validación básica, nunca una aceptación de calidad "showcase". Una validación "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
   

   Un código de salida distinto 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 recuento de errores objetivo alcance un nuevo mínimo. Si dos rondas consecutivas no mejoran ese mejor recuento, detente e informa los diagnósticos no resueltos con honestidad.

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

Nota sobre 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 a API, ciclos de vida de solicitudes, trazas asíncronas, retornos
dataflow	Tuberías, ETL/ELT, linaje, gobierno, consumidores
lifecycle	Transiciones de estado/estatus, reintentos, estados de espera y terminales

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

Entrada Mermaid

Lee Mermaid para obtener topología y significado, luego escribe un JSON Archify nuevo; 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 las transiciones conservan el significado, no el estilo de Mermaid.

Invariantes de autoría

• Una ruta principal obvia; las ramas laterales salen del nodo de la ruta principal más cercano. Elimina las aristas de bajo valor antes de agregar controles de enrutamiento.
• Omite meta.legend para el valor predeterminado verdadero auto. Cuando sea necesario, usa solo mode: auto|all|hidden y entries.<kind>.label|visible compatibles con el renderizador; las etiquetas nunca cambian la semántica.
• Los tipos de componentes son frontend, backend, database, cloud, security, messagebus y external; las variantes son default, emphasis, security y dashed.
• El espaciado significa espacio libre claro, no distancia al centro. Para una etiqueta de relación, el espacio libre claro debe superar 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 el último segmento deben salir/entrar perpendicularmente a ese lado.
• La Distribución Automática de Puertos 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 no auto explícitos. Los puertos casi paralelos usan un puente exterior 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 una arista 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 colocación específica por 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 desee una vista previa local inmediata. Para un bucle de autoría activo en escritorio, 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, desplazamiento panorámico/zoom, búsqueda, enfoque, seguimiento de relaciones, vistas semánticas, presentación y exportaciones fidedignas. Estas son capacidades del lector, no trabajo de autoría adicional. meta.animation: "trace" es opcional; 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, Tarjetas de Ruta/Alcance, movimiento, historias guiadas, enlaces profundos, presentación, búsqueda/enfoque u otra característica del Visor en Tiempo de Ejecución.

Configuración y fallback

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 haya 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 del HTML verificado, el tipo de diagrama, el resumen de validación, el recibo de especificación/artefacto y el estado de revisión visual veraz. No declares éxito para un comando con código de salida distinto de cero ni afirmes una inspección visual que no realizaste.