Mirofy

¿Qué hace Mirofy?

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

Escaneo primero: deriva el diagrama de un repositorio real

Cuando el diagrama debe describir código existente, no lo crees de memoria. Derívalo:

npm run scan      # repositorio -> grafo de evidencia (hechos y brechas)
npm run model     # evidencia + documentos -> un modelo del sistema
npm run compile   # modelo -> una vista acotada con intención

Cada paso informa lo que NO pudo determinar. scan registra una brecha por cada archivo que no pudo analizar, compile registra cada objeto que omitió y por qué. Transmite eso al usuario; un diagrama que omite silenciosamente la mitad de un sistema es peor que uno que dice lo que dejó fuera.

Usa la ruta rápida a continuación cuando el usuario describa algo que aún no existe, o cuando no haya un repositorio disponible.

Ruta de creación rápida

Usa esta ruta acotada para la generación ordinaria. No leas la Referencia Opcional del Visor 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 fresca significa nuevos IDs estables, redacción del dominio y diseño; usa el ejemplo para la forma de los campos, no para los hechos. Cuando la identidad real del producto sea importante, consulta node bin/mirofy.mjs brands "<nombre>" --json; lee references/brand-marks.md solo para una marca desconocida con una URL proporcionada por el usuario.

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 laterales cortas, etiquetas dispersas y como máximo 12 nodos primarios. Establece meta.quality_profile en "showcase" a menos que el usuario solicite explícitamente un mapa denso standard. Comienza con rutas y etiquetas automáticas. No agregues via, channelX, channelY ni 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/mirofy.mjs validate <tipo> <candidato.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 informar 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/mirofy.mjs deliver <tipo> <candidato.json> <salida.html> --quality showcase --json
   

   Una salida distinta de cero nunca puede describirse como éxito. Si la validación falla, cambia solo el sujeto diagnosticado, verifica la evidencia, elige entre supportedFixes y vuelve a ejecutar. Continúa la corrección enfocada mientras el número 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 de manera veraz.

No leas renderers/shared/geometry.mjs, el código fuente del renderizador, el código del 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.

Enrutador de tipos

Tipo	Uso para
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	Tuberías, ETL/ELT, linaje, gobernanza, consumidores
lifecycle	Transiciones de estado/estatus, reintentos, estados de espera y terminales

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

Entrada Mermaid

node bin/mirofy.mjs import mermaid <entrada.mmd> [salida.json] [--json]

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

El importador nunca adivina: cualquier línea que no pueda leer se convierte en una brecha con su número de línea, así que informa lo que no se transfirió en lugar de llamar al resultado completo. Tampoco asigna posiciones: una arquitectura convertida usa layout.mode: "grid", y una bifurcación puede poner un borde a través de un nodo, lo que falla la compuerta clean-flow siempre activa. Siempre valida después de importar. Lee el código fuente para el significado también: el importador transporta topología, no juicio de dominio, por lo que las etiquetas y los tipos a menudo merecen ser reescritos.

Reparación de geometría

Cuando la validación informa componentes superpuestos, no edites las coordenadas manualmente una por una:

node bin/mirofy.mjs repair <tipo> <entrada.json> [salida.json] --safe

--safe es obligatorio porque esto sobrescribe las coordenadas creadas. Repara solo los componentes involucrados en una superposición, cada uno con la corrección más pequeña que despeje el espacio de 8px del validador, imprime un recibo de cada ajuste y toca solo la geometría y nada más: nunca una etiqueta, tipo, conexión o id. Vuelve a validar y nombra lo que el desplazamiento no puede arreglar (enrutamiento, colocación de etiquetas) en lugar de dejarlo para que lo redescubra la siguiente ejecución.

Invariantes de autoría

• Una ruta principal obvia; las ramas laterales salen del nodo de ruta principal más cercano. Elimina los bordes de bajo valor antes de agregar controles de enrutamiento.
• Omite meta.visual_preset por defecto para que cada diagrama se abra en classic, independientemente de si su modo de color resuelto es claro u oscuro. El modo de color y el preset visual son independientes: cambiar Claro/Oscuro debe preservar el preset actual. Establece signal-flow, blueprint o editorial solo cuando el usuario solicite explícitamente ese estilo visual.
• Omite meta.subtitle por defecto. Nunca inventes un subtítulo que repita el título, los nodos o las tarjetas; incluye una línea corta de apoyo solo cuando el usuario lo solicite explícitamente.
• Trata el visor de escritorio independiente como un artefacto de primera pantalla por defecto, no una franja superficial. Genera un artefacto receptivo para portátiles y pantallas externas, nunca HTML específico del dispositivo ni topología alternativa. El visor puede adaptar solo el ancho de lectura externo desde la altura del viewport en vivo; debe preservar el SVG/viewBox creado, las proporciones, la geometría semántica y el flujo normal del documento. En un escritorio ancho o alto, usa suficiente ritmo vertical creado para que el panel de diagrama y sus tarjetas de conclusión necesarias ocupen la pantalla como un todo equilibrado; el escalado en tiempo de ejecución no puede reparar un diseño Y sobrecomprimido o un meta.viewBox explícito subdimensionado. Antes de la entrega, abre el HTML real en 1440×900, 1600×1000 y 1920×1080; además verifica en 2048×1320 siempre que la composición esté destinada a una pantalla de escritorio grande. Requiere document.documentElement.scrollWidth <= window.innerWidth y scrollHeight <= window.innerHeight en cada tamaño verificado, mientras verificas visualmente que el diagrama siga siendo cómodamente legible y equilibrado verticalmente en el viewport más grande verificado. Repara el desbordamiento eliminando solo contenido genuinamente redundante o compactando el espaciado antes de reducir nodos, etiquetas o el panel principal. Si el viewport más grande aún tiene una banda inferior vacía notable en el límite de ancho del visor, redistribuye las posiciones Y creadas y aumenta la altura de viewBox proporcionalmente; no agregues texto de relleno ni tarjetas decorativas. Nunca falsifiques una pasada con overflow: hidden, contenido recortado, un desplazador de diagrama interno, altura SVG estirada o tipografía más pequeña. Los diseños estrechos/móviles pueden desplazarse verticalmente cuando el contenido lo requiera.
• Omite meta.legend para el valor predeterminado 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.
• Elige un idioma principal de autoría a partir de una elección explícita del usuario; de lo contrario, sigue la solicitud o el idioma dominante de la conversación. meta.locale controla solo la interfaz de usuario del visor propiedad del renderizador: usa "en" o "zh-CN" para el idioma principal soportado correspondiente. Para cualquier otro idioma, omite meta.locale y divulga explícitamente que la interfaz de usuario fija del visor y <html lang> vuelven al inglés. El renderizador nunca traduce el contenido creado. Consulta references/authoring-contract.md para más detalles.
• Preserva los nombres exactos de productos, identificadores de código, comandos, protocolos, rutas de API y nombres de entorno. Pueden permanecer en inglés dentro de texto localizado, pero nunca justifiques dejar la prosa explicativa circundante en otro idioma.
• La identidad de marca es opcional y explícita. Coloca un ID integrado canónico en brand cuando los nodos nombren ese producto real. Si no hay un preset coincidente y el usuario proporcionó la URL HTTP(S) oficial, primero ejecuta node bin/mirofy.mjs brands capture "<url>" --json, luego crea el objeto brand con digest-pinned devuelto. Renderizar y validar nunca realizan una captura sin pin. De lo contrario, omite brand. Nunca infieras una marca de un rol vago como "base de datos", y nunca dejes que una insignia reemplace el type, la etiqueta o los hechos de relación semánticos.
• Para diagramas de secuencia, omite meta.column_fit para el diseño fixed estable. Establécelo en "spread" cuando un viewBox ancho dejaría espacio horizontal sin usar o cuando las etiquetas de participantes significativas no quepan en los cuadros fijos; no acortes etiquetas semánticas antes de probar spread.
• Los tipos de componentes son frontend, backend, database, cloud, security, messagebus y external; las variantes son default, emphasis, security y dashed.
• Las etiquetas de relación son datos semánticos. Cuando una colisiona, mueve la etiqueta, ajusta la ruta o el espaciado, luego acorta el texto preservando el significado. Solo elimina una etiqueta cuando ambos extremos impliquen completamente la relación y no contenga protocolo, acción, dirección, comportamiento síncrono/asíncrono o mecanismo entre límites; explica por qué la etiqueta eliminada es redundante. Nunca elimines una etiqueta significativa solo para aprobar showcase.
• Omite meta.engineering_profile por defecto. La redacción de región, clúster y límite de seguridad no lo habilita por sí sola. Habilita deployment-ownership solo cuando el usuario solicite explícitamente una topología de despliegue de producción, transferencia de propiedad o revisión de despliegue de fail-closed y los hechos fuente sean conocidos. Una vez habilitado, no debes eliminar el perfil de ingeniería solo para pasar la validación; repara los hechos o informa los diagnósticos de manera veraz.
• El espaciado significa espacio libre, no distancia central. Para una etiqueta de relación, el espacio libre debe exceder su ancho de máscara medido; usa el orden de reparación que preserva etiquetas antes de considerar la eliminación.
• Las rutas automáticas son dueñas de sus lados de punto final. Un lado es un contrato de dirección: el primer y el último segmento deben salir/ingresar perpendiculares a ese lado.
• La Distribución de Puertos Automática es un comportamiento predeterminado del renderizador para architecture, workflow, data-flow y lifecycle. Omite relaciones individuales 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 menor de 8px o un giro interior menor de 16px. Architecture mantiene por separado puertos automáticos enfrentados sin obstrucción (left/right o top/bottom) en un eje compartido cuando su desplazamiento es inferior a 16px y ambos puertos conservan espacio libre en las esquinas. Si exactamente un punto final se distribuyó, solo el punto final no compartido puede moverse a ese eje; si ambos puntos finales se distribuyeron, mantén el puente exterior para que los puertos competidores permanezcan distintos.
• 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, colocación automática de puertos, reglas de reparación de geometría, evidencia de repositorio o colocación específica de 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 y recuentos de bytes tanto para la especificación como para el artefacto.

Después de la entrega, recopila evidencia de escritorio acotada sin modificar ni volver a renderizar el HTML confiable:

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

visual-check mide el contenido en 1440×900, 1600×1000, 1920×1080 y 2048×1320; captura capturas de pantalla en modo claro/oscuro en los tamaños más pequeño y más grande; y escribe una hoja de contacto de ruta relativa y sidecars JSON junto al artefacto. Su recibo automatizado siempre informa visualReview: "pending": las capturas de pantalla son evidencia para inspección, nunca una afirmación automática de pulido. La salida 0 significa que el contenido y las capturas pasaron, la salida 1 significa desbordamiento o fallo en la captura, y la salida 2 significa que Chrome/Chromium no estaba disponible y el recibo es skipped. El comando nunca cambia el HTML entregado. 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/mirofy.mjs preview <tipo> <entrada>.json <salida>.html --quality showcase

Nunca inicies la vista previa por defecto. Lee references/delivery-contract.md al usar vista previa, evidencia de 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 opt-in; meta.views es opcional y debe contener como máximo cinco capítulos seleccionados. Lee references/viewer-runtime.md solo cuando el usuario solicite explícitamente Tarjetas para Compartir, Tarjetas de Ruta/Alcance, animación, historias guiadas, enlaces profundos, presentación, búsqueda/enfoque u otra característica del Entorno de Ejecución del Visor.

Configuración y fallback

**La instalación de la habilidad es opcional.

…

[truncado para traducción]