¿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
-
Copia el ejemplo más cercano junto a las notas del tema (ver Archivos), renombra
spec.jsona<subject>.spec.json. -
Describe los nodos y aristas. Cada nodo sumidero (un resultado) recibe un
kind; loskindson los únicos colores, cada uno con una etiqueta de leyenda. -
Elige de dónde provienen los veredictos (ver más abajo): un
oraclecuando la regla existe en el código, unportJS en caso contrario. -
Escribe los escenarios. Cada uno declara su
origin, susinputs, los camposexpectdel veredicto y susstepsa lo largo de aristas reales. -
Compila y luego abre el archivo:
python3 <skill-dir>/scripts/build.py <subject>.spec.json -
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
| Fuente | Clave del spec | Cuándo usarla | Marcado en el panel |
|---|---|---|---|
| Oráculo | oracle | la regla existe en un repositorio | ✓ código |
| Puerto | port: "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 losinputsde 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
| Clave | Forma | Notas |
|---|---|---|
title, subtitle, source | cadenas | source va al pie de página; como todo texto del spec se muestra como texto, nunca se lee como HTML |
lang | en (predeterminado) o fr | idioma 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, questions | variants, cases, steps, expect?, show?, hover, summary?}` |
oracle | {repo, ref, paths, link?, files?, cwd, cmd} | ver más arriba |
port | ruta 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?}].casesenumera los casos sobre los que se decide esa pregunta;if: {"Q1": "1A"}la pregunta solo después de esa respuesta.build.pyderiva una variante por cada conjunto coherente de respuestas (1A+2A,1A+2B,1B), fusionando losinputsde las opciones;cases:[{id, label, summary, origin, inputs, steps?}];labelnombra 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 dehover);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
| Id | Rechaza |
|---|---|
| C1 | un paso cuyo salto no es una arista |
| C2 | una ruta que se rompe, no comienza en un nodo fuente o no tiene pasos |
| C3 | un campo expect que la lógica contradice |
| C4 | una ruta que termina en otro lugar que no sea el outcome de la lógica, o una lógica que no da ninguno |
| C5 | un resultado sin un kind, un kind sin leyenda, más de 4 kinds |
| C6 | una etiqueta más ancha que su caja (13px monoespaciada) |
| C7 | un escenario sin un origen que diga real o ilustrativo, y de dónde |
| C8 | un par cuyos escenarios no pueden avanzar juntos, o son desconocidos |
| C9 | una fila del panel que lee un campo que le falta a un escenario |
| C10 | una celda de la matriz que nombra una fila del panel que no existe |
| C11 | un caso mostrado bajo una pregunta cuya celda aún depende de otra pregunta |
| C12 | un caso en ninguna sección de la matriz, o una sección que nombra un caso desconocido |
| C13 | una 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
| Ruta | Rol |
|---|---|
scripts/build.py | lee el spec, obtiene los veredictos, ejecuta las comprobaciones, escribe la página y la exportación |
scripts/runtime.html | la página; build.py le da lo que muestra, ya formateado, y nada más del spec |
scripts/layout.py | distribució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.
C6se 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.