Communitygithub.com

truepath

Genera una simulación HTML autocontenida que explica un proceso o la ruta de un error paso a paso: un punto recorre la ruta real, un panel de datos muestra qué cambia en cada paso y los escenarios «antes/después» se reproducen lado a lado con su primera divergencia marcada.

¿Qué es truepath?

truepath es una herramienta de simulación visual para desarrolladores y agentes de IA que necesitan explicar procesos, reglas de decisión o bugs complejos mediante un diagrama de flujo interactivo y autocontenido. La herramienta permite definir un flujo (nodos y aristas), cargar uno o varios escenarios con entradas específicas y obtener un veredicto calculado por el propio código del repositorio (un 'oráculo' ejecutado sobre una instantánea congelada de git) o por un puerto JavaScript declarado. El resultado es un único archivo HTML offline que muestra un punto animado recorriendo la ruta, un panel detallado con los valores de cada paso, y la capacidad de comparar escenarios «antes/después» con la primera divergencia resaltada. La compilación (mediante `build.py`) verifica 13 comprobaciones de consistencia y se niega a escribir cualquier simulación que contradiga los veredictos, garantizando que la representación visual coincide exactamente con la lógica real del código fuente.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bastien-gallay/truepath/tree/HEAD/skills/truepath

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace truepath?

Un único spec.json describe el proceso (nodos, aristas), los escenarios (ruta, mensajes, leyendas, entradas) y de dónde provienen los veredictos. build.py calcula los veredictos, distribuye el grafo, ejecuta las comprobaciones y escribe un único .html sin conexión, o no escribe nada.

spec.json ──┐
oracle/port ├─► build.py ──► checks C1–C13 ─► sim.html   (o nada)
layout.py ──┘                                └► fixture.json (--export)

Flujo de trabajo

  1. Copia el ejemplo más cercano junto a las notas del tema (ver Archivos), renombra spec.json a <subject>.spec.json.

  2. Describe los nodos y aristas. Cada nodo sumidero (un resultado) recibe un kind; los kind son los únicos colores, cada uno con una etiqueta de leyenda.

  3. Elige de dónde provienen los veredictos (ver más abajo): un oracle cuando la regla existe en el código, un port JS en caso contrario.

  4. Escribe los escenarios. Cada uno declara su origin, sus inputs, los campos expect del veredicto y sus steps a lo largo de aristas reales.

  5. Compila y luego abre el archivo:

    python3 <skill-dir>/scripts/build.py <subject>.spec.json
    
  6. Lee las violaciones, corrige el spec — nunca la comprobación.

spec.json compila sim.html, <subject>.spec.json compila <subject>.sim.html; -o nombra otro archivo.

La página se abre en la primera pestaña con el panel de detalle abierto. Plegar el panel cambia a la vista general: toda la ruta dibujada, un punto recorriéndola en bucle.

De dónde provienen los veredictos

FuenteClave del specCuándo usarlaMarcado en el panel
Oráculooraclela regla existe en un repositorio✓ código
Puertoport: "decide.js"aún no hay código, una regla en discusión, un proceso sin código⚠ portado

Protocolo del oráculo. build.py ejecuta git archive de oracle.ref (nunca el checkout activo: una rama en desarrollo puede moverse durante la compilación), extrae oracle.paths, vincula oracle.link (normalmente node_modules) y copia oracle.files dentro, luego ejecuta oracle.cmd en oracle.cwd con:

  • TRUEPATH_ORACLE_IN: un array JSON de los inputs de cada escenario;
  • TRUEPATH_ORACLE_OUT: dónde escribir un array JSON de veredictos, en el mismo orden.

oracle.repo se lee desde la carpeta del spec cuando es relativo. link y files se escriben ambos como {ruta en la instantánea: de dónde viene}: una ruta en el repositorio para link, un archivo junto al spec para files.

Un veredicto es un objeto de campos. outcome es obligatorio: nombra el nodo en el que debe terminar la ruta, y es lo que vincula un escenario con la lógica. basis indica opcionalmente, por campo, si el código real lo calculó ("code: …"), el pegamento copió un comportamiento ("port: …") o la simulación lo define (cualquier otro texto, mostrado ◇ definición). La página muestra esa marca junto a cada valor del panel cuyo campo tiene una base, su texto completo al pasar el ratón, y --export afirma solo los campos cuya base es código: un campo sin base cuenta como código bajo un oráculo, como portado bajo un port. Un mismo oráculo puede mezclarlos: una regla aún en discusión está portada junto a las reglas que el código ya ejecuta. Cualquier lanzador funciona: un archivo de prueba del propio framework del proyecto, un script, una prueba JUnit para Java. El pie de página nombra la referencia y el SHA corto que produjo los veredictos.

Un oráculo con archivo de prueba puede funcionar como suite de regresión: cuando TRUEPATH_ORACLE_IN está definido escribe los veredictos, de lo contrario lee el fixture exportado y lo afirma. Los escenarios viven entonces una vez, en el spec, y se ejecutan en CI. examples/loyalty-tier/src/oracle.js hace ambas cosas.

Referencia del spec

ClaveFormaNotas
title, subtitle, sourcecadenassource va al pie de página; como todo texto del spec se muestra como texto, nunca se lee como HTML
langen (predeterminado) o fridioma de las palabras propias de la página; el texto del spec se escribe en ese idioma
kinds{id: {label, color}}máximo 4
nodes[{id, label, role?, kind?}]role: "decision" marca un punto de bifurcación; dónde comienza un camino se encuentra y se dibuja redondo; los sumideros necesitan kind
edges[[from, to, label]]label "" para ninguno
panel[{label, value, at, labels?, digits?, compared?}]value lee inputs.x o verdict.y; se muestra desde el paso at (0 es el primero); labels mapea un valor a lo que la página muestra ("true", "false", "null", "[]" para esos valores); digits rellena con ceros un código numérico hasta esa longitud; compared: true para la fila que nombra lo que un par compara (la corrección, la regla), excluida de la búsqueda de primera divergencia
scenarios[{id, tab, summary, origin, inputs, expect, steps, undecided?, caseName?}]origin: `{kind: real
pairs[{before, after, tab, summary}]dos IDs de escenario, reproducidos lado a lado como − y +; mismo número de pasos
grid`{baseline, questionsvariants, cases, steps, expect?, show?, hover, summary?}`
oracle{repo, ref, paths, link?, files?, cwd, cmd}ver más arriba
portruta a un archivo CommonJS que exporta decide(inputs)se usa cuando no hay oráculo
export{dir, fixture, assert}--export <worktree> escribe el fixture allí

Comparación de varias reglas: la cuadrícula

Cuando la pregunta es «qué hace cada posible respuesta a cada caso», declara una grid. Prefiere preguntas a una lista plana de reglas: el lector decide pregunta por pregunta, así que la página debería organizarse de esa manera.

  • baseline: {id, label, short?, inputs}, lo que sucede hoy;
  • questions: [{id, text, options: [{id, label, inputs}], cases, if?}]. cases enumera los casos sobre los que se decide esa pregunta; if: {"Q1": "1A"} la pregunta solo después de esa respuesta. build.py deriva una variante por cada conjunto coherente de respuestas (1A+2A, 1A+2B, 1B), fusionando los inputs de las opciones;
  • cases: [{id, label, summary, origin, inputs, steps?}]; label nombra la fila en palabras que el lector conoce, no un código de caso;
  • steps: compartido por todas las celdas a menos que un caso traiga el suyo;
  • expect: {case: {variant: {field: value}}}, comprobado por C3;
  • show: la única fila del panel que muestra una celda de la matriz (por defecto la primera de hover); hover: las filas que una celda muestra al pasar el ratón;
  • summary: una línea encima de la matriz.

Una variante plana variants: [{id, label, short?, note?, inputs}] con baseline como ID aún funciona: la matriz entonces tiene una sección, cada caso contra cada variante.

La página se abre en la matriz: una tabla por pregunta, sus casos contra hoy y cada respuesta, la línea de la celda marcada ≠ donde difiere de hoy. No hay pestaña por caso: un clic en una celda la abre, hoy junto a esa respuesta, con la primera divergencia marcada. Dos filas de botones, − y +, eligen cualquier lado entre las respuestas de la sección (1A junto a 1B, no solo junto a hoy), cada una nombrada como la pregunta la nombra; ← matriz vuelve atrás. En el panel, una fila con "value": "answer" y "compared": true nombra la respuesta reproducida.

Plantillas de pasos. message, caption y hop pueden citar {inputs.x} o {verdict.y}: se completan después de que la lógica se haya ejecutado, formateados como la fila del panel que lee la misma ruta. Un salto a {verdict.outcome} permite que una lista de pasos sirva para cada regla.

Comprobaciones

IdRechaza
C1un paso cuyo salto no es una arista
C2una ruta que se rompe, no comienza en un nodo fuente o no tiene pasos
C3un campo expect que la lógica contradice
C4una ruta que termina en otro lugar que no sea el outcome de la lógica, o una lógica que no da ninguno
C5un resultado sin un kind, un kind sin leyenda, más de 4 kinds
C6una etiqueta más ancha que su caja (13px monoespaciada)
C7un escenario sin un origen que diga real o ilustrativo, y de dónde
C8un par cuyos escenarios no pueden avanzar juntos, o son desconocidos
C9una fila del panel que lee un campo que le falta a un escenario
C10una celda de la matriz que nombra una fila del panel que no existe
C11un caso mostrado bajo una pregunta cuya celda aún depende de otra pregunta
C12un caso en ninguna sección de la matriz, o una sección que nombra un caso desconocido
C13una fila del panel configurada para aparecer en un paso que el escenario no tiene

C3 y C4 son el punto: un escenario que dice algo que el código no hace no puede publicarse. C6 protege la distribución en lugar del spec: las cajas se dimensionan según sus etiquetas, por lo que se activa solo si layout.py deja de hacerlo. Prueba que una nueva comprobación funciona rompiendo su entrada una vez, en tests/. Cada comprobación es una función en build.py, enumerada en CHECKS bajo el ID de esta tabla.

Un spec que la compilación no puede leer en absoluto (una clave faltante, una arista a un nodo desconocido, un puerto que lanza una excepción) se rechaza de la misma manera, en palabras claras, antes de que se ejecuten las comprobaciones.

Reglas de diseño

  • Un elemento en movimiento por diagrama: un único punto, velocidad constante, un salto a la vez. Dos diagramas lado a lado se mueven al mismo ritmo.
  • Las aristas tomadas son sólidas, las no tomadas son discontinuas y grises; los nodos fuera de la ruta se atenúan.
  • El color codifica solo el tipo de resultado. En un par, la primera divergencia (el primer paso donde un valor del panel difiere) se resalta en ámbar y se marca ≠ en ambos lados, y el panel muestra columnas − / +.
  • Escenarios ilustrativos solo cuando ningún caso real alcanza ese resultado; indica de dónde proviene el caso real (ticket, registro, medida, fecha).
  • Una cuadrícula muestra un campo por celda; tres campos por celda hicieron la matriz ilegible.
  • Tema claro por defecto, oscuro bajo prefers-color-scheme; sin tipografía web, para que el archivo funcione sin conexión.

Archivos

RutaRol
scripts/build.pylee el spec, obtiene los veredictos, ejecuta las comprobaciones, escribe la página y la exportación
scripts/runtime.htmlla página; build.py le da lo que muestra, ya formateado, y nada más del spec
scripts/layout.pydistribución por capas: cajas dimensionadas según su etiqueta, aristas ortogonales
examples/refund-window/un puerto JS y un par antes/después
examples/free-shipping/una cuadrícula: dos preguntas abiertas, cada una decidida sobre los casos que cambia
examples/loyalty-tier/un oráculo sobre el src/ de la propia carpeta, su pegamento y el fixture que --export escribe

Los archivos generados (.truepath/, donde viven las instantáneas de un oráculo, y *.html junto a un spec) son salida de la compilación. Los ejemplos de puerto mantienen su sim.html para que la habilidad pueda verse sin ejecutarla. loyalty-tier no mantiene ninguno: su pie de página nombra el commit que produjo los veredictos, por lo que la página cambia con cada commit, y compila solo dentro de un repositorio git que lo contenga.

Límites

  • Un tipo de diagrama: el flujo de proceso. Las vistas de secuencia y arquitectura no están implementadas.
  • C6 se mide en macOS (ui-monospace); una fuente Windows más estrecha solo añade espacio.
  • Los pasos se declaran, no se derivan de la lógica: C3 y C4 detectan un resultado incorrecto, no un mensaje intermedio incorrecto.

Skills relacionados