Que fait truepath ?
Un spec.json décrit le processus (nœuds, arêtes), les scénarios (chemin, messages, légendes, entrées) et l'origine des verdicts. build.py calcule les verdicts, dispose le graphe, exécute les vérifications et écrit un .html hors ligne — ou rien.
spec.json ──┐
oracle/port ├─► build.py ──► checks C1–C13 ─► sim.html (ou rien)
layout.py ──┘ └► fixture.json (--export)
Flux de travail
-
Copier l'exemple le plus proche à côté des notes du sujet (voir Fichiers), renommer
spec.jsonen<sujet>.spec.json. -
Décrire les nœuds et les arêtes. Chaque nœud puits (un résultat) reçoit un
kind; leskindsont les seules couleurs, chacune avec une étiquette de légende. -
Choisir l'origine des verdicts (voir ci-dessous) : un
oraclelorsque la règle existe dans le code, unportJS sinon. -
Écrire les scénarios. Chacun déclare son
origin, sesinputs, les champs de verdictexpectés, et sesstepsle long des arêtes réelles. -
Construire, puis ouvrir le fichier :
python3 <skill-dir>/scripts/build.py <sujet>.spec.json -
Lire les violations, corriger la spécification — jamais la vérification.
spec.json construit sim.html, <sujet>.spec.json construit <sujet>.sim.html ; -o nomme un autre fichier.
La page s'ouvre sur le premier onglet avec le panneau de détail ouvert. Replier le panneau passe à la vue d'ensemble : le chemin complet dessiné, un point qui boucle dessus.
D'où viennent les verdicts
| Source | Clé du spec | Quand l'utiliser | Marquage dans le panneau |
|---|---|---|---|
| Oracle | oracle | la règle existe dans un dépôt | ✓ code |
| Port | port: "decide.js" | pas encore de code, règle en discussion, processus sans code | ⚠ porté |
Protocole de l'oracle. build.py prend git archive de oracle.ref (jamais la copie de travail vivante : une branche en cours de modification peut bouger pendant la construction), extrait oracle.paths, lie oracle.link (typiquement node_modules) et copie oracle.files dedans, puis exécute oracle.cmd dans oracle.cwd avec :
TRUEPATH_ORACLE_IN: un tableau JSON de tous lesinputsde chaque scénario ;TRUEPATH_ORACLE_OUT: où écrire un tableau JSON de verdicts, dans le même ordre.
oracle.repo est lu depuis le dossier du spec lorsqu'il est relatif. link et files sont écrits {chemin dans le snapshot : d'où il vient} : un chemin dans le dépôt pour link, un fichier à côté du spec pour files.
Un verdict est un objet de champs. outcome est obligatoire : il nomme le nœud où le chemin doit se terminer, et c'est ce qui relie un scénario à la logique. basis dit optionnellement, par champ, si le code réel l'a calculé ("code: …"), si le glue a copié un comportement ("port: …"), ou si la simulation le définit (tout autre texte, affiché ◇ definition). La page montre cette marque à côté de chaque valeur du panneau dont le champ a une base, son texte complet au survol, et --export n'affirme que les champs dont la base est code : un champ sans base compte comme code sous un oracle, comme porté sous un port. Un oracle peut mélanger les deux : une règle encore en discussion est portée à côté des règles que le code exécute déjà. N'importe quel exécuteur fonctionne : un fichier de test du framework du projet, un script, un test JUnit pour Java. Le pied de page nomme la ref et le sha court qui ont produit les verdicts.
Un oracle-fichier de test peut servir de suite de régression : lorsque TRUEPATH_ORACLE_IN est défini, il écrit les verdicts, sinon il lit le fixture exporté et l'affirme. Les scénarios vivent alors une fois, dans le spec, et s'exécutent en CI. examples/loyalty-tier/src/oracle.js fait les deux.
Référence du spec
| Clé | Forme | Notes |
|---|---|---|
title, subtitle, source | chaînes | source atterrit dans le pied de page ; comme tout texte du spec, ils sont affichés comme texte, jamais lus comme HTML |
lang | en (défaut) ou fr | langue des mots de la page ; le texte du spec est écrit dans cette langue |
kinds | {id: {label, color}} | au maximum 4 |
nodes | [{id, label, role?, kind?}] | role: "decision" marque un point de branchement ; le début d'un chemin est trouvé et dessiné rond ; les puits ont besoin de kind |
edges | [[from, to, label]] | label "" pour aucun |
panel | [{label, value, at, labels?, digits?, compared?}] | value lit inputs.x ou verdict.y ; affiché à partir de l'étape at (0 est la première) ; labels mappe une valeur à ce que la page montre ("true", "false", "null", "[]" pour ces valeurs) ; digits remplit un code numérique avec des zéros jusqu'à cette longueur ; compared: true pour la ligne qui nomme ce qu'une paire compare (le correctif, la règle), exclue de la recherche de première divergence |
scenarios | [{id, tab, summary, origin, inputs, expect, steps, undecided?, caseName?}] | origin : `{kind: real |
pairs | [{before, after, tab, summary}] | deux identifiants de scénarios, joués côte à côte comme − et + ; même nombre d'étapes |
grid | `{baseline, questions | variants, cases, steps, expect?, show?, hover, summary?}` |
oracle | {repo, ref, paths, link?, files?, cwd, cmd} | voir ci-dessus |
port | chemin vers un fichier CommonJS exportant decide(inputs) | utilisé quand il n'y a pas d'oracle |
export | {dir, fixture, assert} | --export <worktree> écrit le fixture là-bas |
Comparer plusieurs règles : la grille
Lorsque la question est « que fait chaque réponse possible à chaque cas », déclarez une grid. Préférez les questions à une liste plate de règles : le lecteur décide question par question, donc la page doit être disposée ainsi.
baseline:{id, label, short?, inputs}, ce qui se passe aujourd'hui ;questions:[{id, text, options: [{id, label, inputs}], cases, if?}].casesliste les cas sur lesquels cette question est décidée ;if: {"Q1": "1A"}ne la pose qu'après cette réponse.build.pydérive une variante par ensemble cohérent de réponses (1A+2A,1A+2B,1B), en fusionnant lesinputsdes options ;cases:[{id, label, summary, origin, inputs, steps?}];labelnomme la ligne avec des mots que le lecteur connaît, pas un code de cas ;steps: partagé par toutes les cellules sauf si un cas apporte les siennes ;expect:{case: {variant: {field: value}}}, vérifié par C3 ;show: la seule ligne du panneau qu'une cellule de matrice affiche (par défaut la première dehover) ;hover: les lignes qu'une cellule affiche au survol ;summary: une ligne au-dessus de la matrice.
Un variants: [{id, label, short?, note?, inputs}] plat avec baseline comme id fonctionne toujours : la matrice a alors une section, chaque cas contre chaque variante.
La page s'ouvre sur la matrice : un tableau par question, ses cas contre aujourd'hui et chaque réponse, la ligne de la cellule marquée ≠ là où elle diffère d'aujourd'hui. Il n'y a pas d'onglet par cas : un clic sur une cellule l'ouvre, aujourd'hui à côté de cette réponse, avec la première divergence marquée. Deux rangées de boutons, − et +, choisissent chaque côté parmi les réponses de la section (1A à côté de 1B, pas seulement à côté d'aujourd'hui), chacune nommée comme la question la nomme ; ← matrix revient. Dans le panneau, une ligne avec "value": "answer" et "compared": true nomme la réponse jouée.
Modèles d'étapes. message, caption et hop peuvent citer {inputs.x} ou {verdict.y} : ils sont remplis après l'exécution de la logique, formatés comme la ligne du panneau lisant le même chemin. Un hop vers {verdict.outcome} permet à une seule liste d'étapes de servir pour chaque règle.
Vérifications
| Id | Refuse |
|---|---|
| C1 | une étape dont le saut n'est pas une arête |
| C2 | un chemin qui casse, ne commence pas à un nœud source, ou n'a pas d'étape |
| C3 | un champ expect que la logique contredit |
| C4 | un chemin qui se termine ailleurs que le outcome de la logique, ou une logique qui n'en donne pas |
| C5 | un résultat sans kind, un kind sans légende, plus de 4 kinds |
| C6 | une étiquette plus large que sa boîte (13px monospace) |
| C7 | un scénario sans origin indiquant réel ou illustratif, et d'où |
| C8 | une paire dont les scénarios ne peuvent pas avancer ensemble, ou sont inconnus |
| C9 | une ligne du panneau qui lit un champ qu'un scénario n'a pas |
| C10 | une cellule de matrice nommant une ligne du panneau qui n'existe pas |
| C11 | un cas affiché sous une question dont la cellule dépend encore d'une autre question |
| C12 | un cas dans aucune section de matrice, ou une section nommant un cas inconnu |
| C13 | une ligne du panneau définie pour apparaître à une étape que le scénario n'a pas |
C3 et C4 sont le point : un scénario qui dit quelque chose que le code ne fait pas ne peut pas être publié. C6 protège la disposition plutôt que le spec : les boîtes sont dimensionnées à leurs étiquettes, donc cela ne se déclenche que si layout.py cesse de le faire. Prouvez qu'une nouvelle vérification mord en cassant une fois son entrée, dans tests/. Chaque vérification est une fonction dans build.py, listée dans CHECKS sous l'id de ce tableau.
Un spec que la construction ne peut pas lire du tout (une clé manquante, une arête vers un nœud inconnu, un port qui lève une exception) est refusé de la même manière, en termes simples, avant que les vérifications ne s'exécutent.
Règles de conception
- Un seul élément mobile par diagramme : un point unique, vitesse constante, un saut à la fois. Deux diagrammes côte à côte bougent en synchronisation.
- Les arêtes empruntées sont pleines, celles non empruntées sont en pointillés et grises ; les nœuds hors du chemin s'estompent.
- La couleur encode uniquement le type de résultat. Dans une paire, la première divergence (la première étape où une valeur du panneau diffère) est soulignée en ambre et marquée
≠des deux côtés, et le panneau montre les colonnes−/+. - Scénarios illustratifs uniquement là où aucun cas réel n'atteint ce résultat ; dites d'où vient le cas réel (ticket, enregistrement, mesure, date).
- Une grille montre un champ par cellule ; trois champs par cellule rendaient la matrice illisible.
- Thème clair par défaut, sombre sous
prefers-color-scheme; aucune police web, pour que le fichier fonctionne hors ligne.
Fichiers
| Chemin | Rôle |
|---|---|
scripts/build.py | lit le spec, obtient les verdicts, exécute les vérifications, écrit la page et l'export |
scripts/runtime.html | la page ; build.py lui donne ce qu'elle affiche, déjà formaté, et rien d'autre du spec |
scripts/layout.py | disposition en couches : boîtes dimensionnées à leur étiquette, arêtes orthogonales |
examples/refund-window/ | un port JS et une paire avant/après |
examples/free-shipping/ | une grille : deux questions ouvertes, chacune décidée sur les cas qu'elle modifie |
examples/loyalty-tier/ | un oracle sur le propre src/ du dossier, son glue et le fixture que --export écrit |
Les fichiers générés (.truepath/, où vivent les snapshots d'un oracle, et *.html à côté d'un spec) sont des produits de construction. Les exemples de port conservent leur sim.html pour que la compétence puisse être vue sans l'exécuter. loyalty-tier n'en conserve aucun : son pied de page nomme le commit qui a produit les verdicts, donc la page change à chaque commit, et elle se construit uniquement dans un dépôt git qui la contient.
Limites
- Un seul type de diagramme : le flux de processus. Les vues de séquence et d'architecture ne sont pas construites.
C6est mesuré sur macOS (ui-monospace) ; une police Windows plus étroite ajoute seulement de l'air.- Les étapes sont déclarées, pas dérivées de la logique : C3 et C4 attrapent un mauvais résultat, pas un mauvais message intermédiaire.