system-diff

System Diff

Un system diff (diff del sistema) muestra qué hace un cambio en el sistema en ejecución: los componentes y flujos que agrega, elimina o modifica, los estados por los que algo puede ahora transitar, los hechos que cambian y la nueva forma en que puede fallar. El diff de líneas es la evidencia; el diff del sistema es la historia que un revisor necesita.

Modelas el cambio como una especificación, y el script renderiza la especificación como un video en viñetas: título, un antes y un después para cada diagrama, fallo, cierre. Abajo, <script> es la ruta absoluta de scripts/system-diff.mjs en la carpeta de esta habilidad.

1. Verificar configuración

Ejecuta node <script> doctor. Termina con Ready. en una máquina que está configurada.

En cualquier otro resultado, o cuando node falta, detente y pide al usuario que ejecute /setup-system-diff, que instala todo lo que esta habilidad necesita.

2. Recopilar el cambio

El cambio es un pull request, una rama o un rango de commits. Si no se nombra nada, toma la rama actual contra su base: la rama base del pull request cuando tiene una, de lo contrario la rama por defecto del repositorio. Pregunta al usuario cuando ninguna está clara.

Trabaja en un checkout que esté en la cabeza del cambio, porque el paso 4 verifica tu evidencia contra los archivos en disco.

• Lee el diff completo (gh pr diff <número>, o git diff <base>...<cabeza>), y la descripción del pull request cuando la haya, o los mensajes de commit cuando no.
• Para cada hunk que toque una llamada, una consulta, una programación, un valor de configuración, un esquema o un permiso, lee suficiente código alrededor, en la base y en la cabeza, para saber quién llama a quién en tiempo de ejecución.

Listo cuando puedas decir, para la base y para la cabeza: qué se ejecuta, con qué habla cada cosa, qué almacena y qué sucede cuando cada cosa de la que depende está caída.

3. Modelar el cambio del sistema

Enumera el cambio como afirmaciones, cada una con la ruta:línea que la muestra. Las afirmaciones se convierten en la especificación en el paso 4 y van al usuario en el paso 6.

• Componentes: cosas que se ejecutan o almacenan datos, como un servicio, un trabajo, una cola, una tabla o una API externa. Incluye los que no cambian y que un espectador necesita para seguir el flujo.
• Flujos: un componente llamando, leyendo o escribiendo en otro.
• Estados y transiciones: las etapas por las que algo se mueve, como un pedido, un trabajo, una sesión o una conexión, y los eventos que lo mueven de uno al siguiente.
• Hechos: una cosa sobre el sistema con un valor antes y después, como un valor de configuración, un límite, un esquema, quién puede hacer qué, o cuánto tiempo toma algo.
• Modo de fallo: la nueva forma más importante de fallar. Generalmente un nuevo componente o nueva dependencia se detiene; también puede ser uno existente cuyo fallo ahora cuesta más, o un estado en el que algo puede quedarse atascado. Di qué sucede entonces: qué hace cada otro componente, o dónde termina la cosa.

Cada afirmación cita la línea que la muestra. Una afirmación sin línea que citar es una suposición y se queda fuera del video.

Algunos cambios dejan el sistema como estaba: un refactor, formato, pruebas, comentarios, un renombre de algo que solo el código ve. Para esos, dile al usuario que el cambio no tiene diff del sistema y qué tipo de cambio es, y termina ahí sin video. Un renombre de algo que el sistema en ejecución ve, como una ruta, una tabla, una cola o una clave de configuración, es un cambio del sistema.

Las afirmaciones deciden qué diagrama dibuja el video:

• Vista de componentes, cuando cambia el cableado: se agrega o elimina un componente o flujo, o un flujo lleva algo diferente.
• Diagrama de estados, cuando cambia un ciclo de vida: un estado gana o pierde un valor, aparece un paso de reintento o cancelación, o un evento ahora lleva a otro lugar.
• Un valor que cambia mientras el cableado y el ciclo de vida permanecen iguales, como un tiempo de espera más largo, es un hecho, mostrado bajo el diagrama que le da contexto.
• Ambos, cuando ambos cambian y cada uno muestra algo que el otro no puede. Cada diagrama agrega dos viñetas, por lo que un cambio que un diagrama cuenta completamente obtiene uno.

Listo cuando cada hunk del diff está cubierto por una afirmación o apartado como que no cambia el sistema, y has elegido los diagramas.

4. Escribir la especificación

Convierte las afirmaciones en una especificación, siguiendo SPEC.md, que tiene todos los campos, las reglas de diseño y cómo escribir los pies de foto y la narración. Guárdala como system-diff.json en una carpeta temporal fuera del repositorio.

Ejecuta node <script> check <especificación> --repo <raíz del repositorio>.

Listo cuando imprime exactamente The spec is valid., sin advertencias. check confirma que cada línea citada existe; que la línea muestre la afirmación es tu responsabilidad.

5. Construir y leer la hoja de contacto

Ejecuta node <script> build <especificación> --repo <raíz del repositorio> --out <carpeta temporal>. Imprime la ruta del video, sus advertencias, una hoja de contacto (una imagen con un fotograma de cada viñeta) y una carpeta stills que contiene los mismos fotogramas a tamaño completo.

Lee la hoja de contacto para la visión general y los fotogramas individuales para el texto pequeño, y verifica cada fotograma:

• cada etiqueta, valor y pie de foto está completo y legible;
• cada línea de flujo corre limpia de las cajas y etiquetas a las que no conecta;
• cada fotograma de antes muestra solo lo que existía antes, y cada fotograma de después muestra todo lo que el cambio agregó;
• el punto de inicio de un diagrama de estados está en el estado en el que la cosa comienza;
• el fotograma de fallo marca el componente o estado correcto, y cada nota está en el borde inferior del que describe;
• cada pie de foto dice lo que muestra su fotograma.

Arregla la especificación y construye de nuevo hasta que la compilación imprima No warnings. y la hoja pase todas las verificaciones. La mayoría de los problemas de fotograma se solucionan acortando el texto o moviendo una caja a otra celda. Uno que sobrevive a ambos va en la entrega, nombrado.

6. Entrega

Dale al usuario la ruta del video, una frase sobre lo que muestra, las afirmaciones con su evidencia y cualquier cosa que hayas omitido o de la que no estés seguro. Publicar el video en cualquier lugar es decisión del usuario.