Was macht truepath?
Eine spec.json beschreibt den Prozess (Knoten, Kanten), die Szenarien (Pfad,
Nachrichten, Bildunterschriften, Eingaben) und wo die Entscheidungen (Verdikte) herkommen. build.py
berechnet die Entscheidungen, legt den Graphen aus, führt die Prüfungen durch und schreibt eine Offline-
.html – oder gar nichts.
spec.json ──┐
oracle/port ├─► build.py ──► checks C1–C13 ─► sim.html (oder nichts)
layout.py ──┘ └► fixture.json (--export)
Arbeitsablauf
-
Kopiere das nächstgelegene Beispiel neben die Notizen des Themas (siehe Dateien), benenne
spec.jsonin<thema>.spec.jsonum. -
Beschreibe Knoten und Kanten. Jeder Senkenknoten (ein Ergebnis) erhält einen
kind; die Kinds sind die einzigen Farben, jede mit einer Legendenbeschriftung. -
Wähle, woher die Entscheidungen kommen (siehe unten): ein
oracle, wenn die Regel im Code existiert, andernfalls ein JSport. -
Schreibe die Szenarien. Jedes deklariert seinen
origin, seineinputs, die erwarteten Entscheidungsfelder (expect) und seinestepsentlang echter Kanten. -
Baue und öffne die Datei:
python3 <skill-verz>/scripts/build.py <thema>.spec.json -
Lies die Verstöße, korrigiere die Spezifikation – niemals die Prüfung.
spec.json erstellt sim.html, <thema>.spec.json erstellt
<thema>.sim.html; -o benennt eine andere Datei.
Die Seite öffnet sich im ersten Tab mit geöffnetem Detailpanel. Einklappen des Panels wechselt zur Übersicht: der gesamte Pfad gezeichnet, ein Punkt durchläuft ihn in einer Schleife.
Wo Entscheidungen herkommen
| Quelle | Spec-Schlüssel | Verwenden, wenn ... | Markiert im Panel |
|---|---|---|---|
| Oracle | oracle | die Regel in einem Repository existiert | ✓ Code |
| Port | port: "decide.js" | noch kein Code vorhanden, eine Regel in Diskussion, ein Prozess ohne Code | ⚠ portiert |
Oracle-Protokoll. build.py führt git archive von oracle.ref aus (niemals
den Live-Checkout: ein Zweig in Arbeit könnte sich während des Builds verschieben), extrahiert
oracle.paths, verlinkt oracle.link (typischerweise node_modules) und kopiert
oracle.files hinein, führt dann oracle.cmd in oracle.cwd aus mit:
TRUEPATH_ORACLE_IN: ein JSON-Array aller Szenarien-inputs;TRUEPATH_ORACLE_OUT: wohin ein JSON-Array von Entscheidungen geschrieben werden soll, gleiche Reihenfolge.
oracle.repo wird aus dem Ordner der Spezifikation gelesen, wenn es relativ ist. link und
files werden beide als {Pfad im Snapshot: woher er kommt} geschrieben:
ein Pfad im Repository für link, eine Datei neben der Spezifikation für files.
Eine Entscheidung ist ein Objekt mit Feldern. outcome ist erforderlich: es benennt den Knoten, an dem
der Pfad enden muss, und verbindet so ein Szenario mit der Logik. basis gibt optional
an, pro Feld, ob echter Code es berechnet hat ("code: …"), der Kleber ein Verhalten
kopiert hat ("port: …"), oder die Simulation es definiert (jeder andere Text, angezeigt
◇ Definition). Die Seite zeigt dieses Zeichen neben jedem Panelwert, dessen Feld eine Basis hat,
den vollständigen Text beim Hovern, und --export behauptet nur Felder, deren Basis Code ist:
ein Feld ohne Basis zählt als Code unter einem Oracle, als portiert unter einem port. Ein Oracle kann
sie mischen: eine noch in Diskussion befindliche Regel ist portiert neben den Regeln, die der Code bereits ausführt. Jeder
Runner funktioniert: eine Testdatei des
projekteigenen Frameworks, ein Skript, ein JUnit-Test für Java. Die Fußzeile nennt die Referenz
und den kurzen SHA, der die Entscheidungen produziert hat.
Eine Oracle-Testdatei kann auch als Regressionstestsuite dienen: wenn
TRUEPATH_ORACLE_IN gesetzt ist, schreibt sie die Entscheidungen, andernfalls liest sie die
exportierte Fixture und bestätigt sie. Die Szenarien leben dann einmal, in der Spec,
und laufen in CI. examples/loyalty-tier/src/oracle.js macht beides.
Spec-Referenz
| Schlüssel | Form | Hinweise |
|---|---|---|
title, subtitle, source | Zeichenketten | source landet in der Fußzeile; wie jeder Text der Spec werden sie als Text angezeigt, niemals als HTML gelesen |
lang | en (Standard) oder fr | Sprache der Seitenwörter; der Spec-Text ist in dieser Sprache verfasst |
kinds | {id: {label, color}} | maximal 4 |
nodes | [{id, label, role?, kind?}] | role: "decision" markiert einen Verzweigungspunkt; wo ein Pfad beginnt, wird gefunden und rund gezeichnet; Senken benötigen kind |
edges | [[from, to, label]] | label "" für keine |
panel | [{label, value, at, labels?, digits?, compared?}] | value liest inputs.x oder verdict.y; wird ab Schritt at angezeigt (0 ist der erste); labels bildet einen Wert auf das ab, was die Seite zeigt ("true", "false", "null", "[]" für diese Werte); digits füllt einen numerischen Code auf diese Länge mit Nullen auf; compared: true für die Zeile, die benennt, was ein Paar vergleicht (der Fix, die Regel), ausgenommen von der Suche nach der ersten Abweichung |
scenarios | [{id, tab, summary, origin, inputs, expect, steps, undecided?, caseName?}] | origin: `{kind: real |
pairs | [{before, after, tab, summary}] | zwei Szenarien-IDs, nebeneinander als − und + abgespielt; gleiche Anzahl Schritte |
grid | `{baseline, questions | variants, cases, steps, expect?, show?, hover, summary?}` |
oracle | {repo, ref, paths, link?, files?, cwd, cmd} | siehe oben |
port | Pfad zu einer CommonJS-Datei, die decide(inputs) exportiert | wird verwendet, wenn es kein Oracle gibt |
export | {dir, fixture, assert} | --export <worktree> schreibt die Fixture dort hin |
Mehrere Regeln vergleichen: das Grid
Wenn die Frage lautet „Was macht jede mögliche Antwort mit jedem Fall?“, deklariere
ein grid. Bevorzuge Fragen gegenüber einer flachen Liste von Regeln: der Leser entscheidet
Frage für Frage, daher sollte die Seite so aufgebaut sein.
baseline:{id, label, short?, inputs}, was heute passiert;questions:[{id, text, options: [{id, label, inputs}], cases, if?}].caseslistet die Fälle auf, über die diese Frage entscheidet;if: {"Q1": "1A"}stellt sie nur nach dieser Antwort.build.pyleitet eine Variante pro kohärentem Satz von Antworten ab (1A+2A,1A+2B,1B), indem es dieinputsder Optionen zusammenführt;cases:[{id, label, summary, origin, inputs, steps?}];labelbenennt die Zeile in Worten, die ein Leser kennt, nicht als Fall-Code;steps: von allen Zellen geteilt, es sei denn, ein Fall bringt eigene;expect:{Fall: {Variante: {Feld: Wert}}}, von C3 geprüft;show: die eine Panelzeile, die eine Matrixzelle anzeigt (standardmäßig die erste vonhover);hover: die Zeilen, die eine Zelle beim Hovern anzeigt;summary: eine Zeile über der Matrix.
Eine flache variants: [{id, label, short?, note?, inputs}] mit baseline als
ID funktioniert immer noch: die Matrix hat dann einen Abschnitt, jeder Fall gegen jede Variante.
Die Seite öffnet sich auf der Matrix: eine Tabelle pro Frage, ihre Fälle gegen heute
und jede Antwort, die Zellenlinie mit ≠ markiert, wo sie sich von heute unterscheidet. Es gibt
keinen Tab pro Fall: ein Klick auf eine Zelle öffnet sie, heute neben dieser Antwort,
mit der ersten Abweichung markiert. Zwei Schaltflächenreihen, − und +, wählen
jeweils eine Seite aus den Antworten des Abschnitts (1A neben 1B, nicht nur neben heute), jede
benannt, wie ihre Frage sie nennt; ← Matrix geht zurück. Im Panel benennt eine Zeile
mit "value": "answer" und "compared": true die abgespielte Antwort.
Schrittvorlagen. message, caption und hop können {inputs.x} oder
{verdict.y} zitieren: sie werden gefüllt, nachdem die Logik gelaufen ist, formatiert wie die Panelzeile,
die denselben Pfad liest. Ein Sprung zu {verdict.outcome} lässt eine Schrittliste für jede Regel dienen.
Prüfungen
| ID | Verweigert |
|---|---|
| C1 | einen Schritt, dessen Sprung keine Kante ist |
| C2 | einen Pfad, der abbricht, nicht an einem Quellknoten beginnt oder keinen Schritt hat |
| C3 | ein expect-Feld, das die Logik widerspricht |
| C4 | einen Pfad, der woanders als am outcome der Logik endet, oder eine Logik, die keinen liefert |
| C5 | ein Ergebnis ohne Kind, ein Kind ohne Legende, mehr als 4 Kinds |
| C6 | eine Beschriftung, die breiter als ihre Box ist (13px Monospace) |
| C7 | ein Szenario ohne Ursprung, der real oder illustrativ sagt und woher |
| C8 | ein Paar, dessen Szenarien nicht gemeinsam voranschreiten können oder unbekannt sind |
| C9 | eine Panelzeile, die ein Feld liest, das einem Szenario fehlt |
| C10 | eine Matrixzelle, die eine nicht existierende Panelzeile benennt |
| C11 | einen Fall, der unter einer Frage angezeigt wird, dessen Zelle noch von einer anderen Frage abhängt |
| C12 | einen Fall in keinem Matrixabschnitt oder einen Abschnitt, der einen unbekannten Fall benennt |
| C13 | eine Panelzeile, die so eingestellt ist, dass sie bei einem Schritt erscheint, den das Szenario nicht hat |
C3 und C4 sind der Punkt: Ein Szenario, das etwas sagt, was der Code nicht tut, kann nicht
veröffentlicht werden. C6 schützt eher das Layout als die Spezifikation: Boxen sind
auf ihre Beschriftungen dimensioniert, also feuert es nur, wenn layout.py damit aufhört. Beweise
dass eine neue Prüfung zubeißt, indem du ihre Eingabe einmal brichst, in tests/. Jede Prüfung ist eine
Funktion in build.py, aufgelistet in CHECKS unter der ID dieser Tabelle.
Eine Spezifikation, die der Build überhaupt nicht lesen kann (ein fehlender Schlüssel, eine Kante zu einem unbekannten Knoten, ein Port, der wirft), wird genauso abgelehnt, in einfachen Worten, bevor die Prüfungen laufen.
Gestaltungsregeln
- Ein sich bewegendes Element pro Diagramm: ein einzelner Punkt, konstante Geschwindigkeit, ein Sprung nach dem anderen. Zwei Diagramme nebeneinander bewegen sich synchron.
- Begangene Kanten sind durchgehend, nicht begangene gestrichelt und grau; Knoten außerhalb des Pfades verblassen.
- Farbe kodiert nur die Art des Ergebnisses. In einem Paar wird die erste Abweichung (der
erste Schritt, bei dem sich ein Panelwert unterscheidet) bernsteinfarben umrandet und auf beiden
Seiten mit
≠markiert, und das Panel zeigt−/+Spalten. - Illustrative Szenarien nur, wenn kein realer Fall dieses Ergebnis erreicht; sage, woher der reale Fall kommt (Ticket, Datensatz, Messung, Datum).
- Ein Grid zeigt ein Feld pro Zelle; drei Felder pro Zelle machten die Matrix unlesbar.
- Helles Design standardmäßig, dunkles unter
prefers-color-scheme; keine Web-Schriftart, damit die Datei offline funktioniert.
Dateien
| Pfad | Rolle |
|---|---|
scripts/build.py | liest die Spec, holt die Entscheidungen, führt die Prüfungen durch, schreibt die Seite und den Export |
scripts/runtime.html | die Seite; build.py gibt ihr das, was sie anzeigt, bereits formatiert, und nichts weiter von der Spec |
scripts/layout.py | geschichtetes Layout: Boxen auf ihre Beschriftung dimensioniert, orthogonale Kanten |
examples/refund-window/ | ein JS-Port und ein Vorher/Nachher-Paar |
examples/free-shipping/ | ein Grid: zwei offene Fragen, jede entschieden über die Fälle, die sie ändert |
examples/loyalty-tier/ | ein Oracle im eigenen Ordner src/, dessen Kleber und die Fixture, die --export schreibt |
Generierte Dateien (.truepath/, wo die Schnappschüsse eines Oracles leben, und *.html
neben einer Spec) sind Build-Ausgabe. Die Port-Beispiele behalten ihre sim.html,
so dass das Skill ohne Ausführung gesehen werden kann. loyalty-tier behält keine: seine
Fußzeile nennt den Commit, der die Entscheidungen produziert hat, also ändert sich die Seite mit jedem
Commit, und es baut nur innerhalb eines Git-Repositorys, das es enthält.
Grenzen
- Ein Diagrammtyp: der Prozessablauf. Sequenz- und Architekturansichten werden nicht gebaut.
C6wird auf macOS gemessen (ui-monospace); eine schmalere Windows-Schriftart fügt nur Luft hinzu.- Schritte werden deklariert, nicht aus der Logik abgeleitet: C3 und C4 fangen ein falsches Ergebnis ab, nicht eine falsche Zwischennachricht.