Construire et tester
Les commandes qui construisent le projet Arche, lancent ses tests et le simulent.
Commandes : archec build · archec pull · archec test · archec sim · archec physics · archec fit · archec difftest · archec where · archec ci · archec validate · archec diff
Sur cette page : En savoir plus sur ces commandes
| Commande | Ce qu’elle fait |
|---|---|
archec build <main.arche> [-o <dir>] [--force] |
Le dossier du projet Arche (par défaut ./arche-out) ; ouvrez-le avec arche --project <dir>. La commande refuse d’écraser du code modifié dans Arche et pas encore récupéré. |
archec pull <main.arche> [-o <dir>] [--write] |
Le code modifié dans l’application Arche, renvoyé dans les définitions .py et les blocs de code d’où il vient (un essai à blanc sans --write). |
archec test <main.arche> [-o <dir>] [--plan <id>]… [--case <PLAN/CASE>]… [--coverage] [--allow <file>] [--sim web|python] [--python <exe>] [--no-python] [--ui-golden [--tolerance 0.1]] [--timeout 600] |
Construit le projet, puis lance les plans de test dans le simulateur d’Arche (arche-cli) : chaque cas, les exigences qu’il vérifie et, avec --coverage, les états, transitions, messages et fonctions par lesquels l’exécution est passée. --allow : les échecs connus, un PLAN/CASE par ligne. Un cas qui a une étape d’interface (do press hmi.engage, expect hmi.mode.text == "…" : ui) tourne sur le simulateur du navigateur — celui d’Arche n’a pas d’interface —, dans le même rapport, et n’a pas besoin d’arche-cli. --sim web y lance tous les cas, --sim python aucun. Là, le Python que le langage d’action ne sait pas exprimer tourne dans python3 (--python <exe> le désigne). Avec --no-python, ou sans python3, un cas qui l’atteint est non concluant : ni réussi ni échoué, et l’exécution sort avec le code 1 (sim). --ui-golden : chaque écran est ensuite comparé à sa référence, comme avec archec ui snapshot. Chaque cas exécuté est enregistré comme preuve pour archec status, avec l’endroit où il a tourné et les empreintes de ce dont il dépendait (.arche/evidence/test.jsonl ; --no-record : pas d’enregistrement). |
archec test <main.arche> --ladder [--plan <id>]… [--case <PLAN/CASE>]… [--board <probe>] [--hook <script>] [--deployment D] [--sim python] [-o <dir>] [--json] [--verbose] [--timeout 3600] |
L’échelle de test : les cas sur le simulateur, puis le firmware dans Renode, puis sur la carte, avec un arrêt au premier échelon qui échoue. Une ligne par échelon. Les deux échelons du haut sont le hook du projet (board.sh à côté du modèle, --hook, ou ARCHE_LADDER_HOOK) : hook --renode quand le déploiement a un binaire sur une carte et que renode est installé, hook seulement avec --board <probe> (il flashe) et un outil de flash de la puce installé. Un outil ou un hook manquant donne un échelon sauté, avec la raison, pas un échec. Un hook qui sort avec le code 2 est sauté aussi. La sortie de chaque échelon est dans <out>/.archec/ladder/, l’échelle dans <out>/.archec/ladder.json (--json : affichée). Ce que les échelons enregistrent dit où cela a tourné : archec status montre l’échelon le plus haut atteint par chaque exigence. Code de sortie 1 quand un échelon échoue. |
archec test <main.arche> --target vhdl [--plan <id>]… [--case <PLAN/CASE>]… [-o <dir>] [--deployment D] [--json] [--verbose] [--timeout 600] |
Les cas de test sur le VHDL d’un FPGA : le VHDL et un banc de test par cas écrits sous <dir>/vhdl, analysés et exécutés dans GHDL. Chaque cas exécuté est une preuve au lieu ghdl, et laisse une trace dans <dir>/vhdl/trace/ pour archec why, why-not et timing. Code de sortie 0 : tous les cas ont passé ; 1 : un cas a échoué ; 2 : impossible de l’exécuter (pas de GHDL ici : rien n’est téléchargé, le message dit d’où il vient). Extension : fpga. |
archec test <main.arche> --against <git-ref> [--plan <id>]… [--case <PLAN/CASE>]… [--sim python] [-o <dir>] [--json] |
Un test qui prouve un correctif : les cas (si aucun n’est nommé, ceux qui sont nouveaux ou modifiés depuis la référence) sur une extraction de la référence — un worktree git dans un dossier temporaire, les cas tels qu’ils sont maintenant ajoutés au modèle tel qu’il était —, puis sur l’arbre de travail, sur le simulateur. Un cas qui échoue là-bas et réussit ici prouve le correctif (un enregistrement fix pour archec status). Un cas qui réussit des deux côtés n’attrape pas le bogue. Code de sortie 0 seulement quand chaque cas prouve le correctif ; 2 quand les deux builds ne peuvent pas être comparés (pas de dépôt, pas de telle référence, un cas que l’ancien modèle n’accepte pas). |
archec run <main.arche> [-o <dir>] |
Construit et lance la simulation ; chaque erreur Python s’affiche à sa ligne dans vos sources. |
archec sim <main.arche> [--for 10s] [--system S] [--deployment D] [--seed 1] [--keyframe K] [--json] [--html out.html] [--plant plant_bridge.py [--test [TP|TC]]] [--python <exe>] [--no-python] [--py-timeout 5s]archec sim <main.arche> --doctest [--json] [--python <exe>]archec sim <main.arche> --batch N [--seed 1] [--vary part.var=lo..hi]… [--threads k] [--print a,b] [--csv file] [--json] |
Exécute le comportement du modèle sans rien installer — ni Arche, ni Python, sauf si un corps est du Python que le langage d’action ne sait pas exprimer : machines à états (sur un message, sur "after 500ms"), échéances et chiens de garde, corps ```arche et le Python que le langage d’action sait exprimer, ports et liens, threads périodiques d’un déploiement, le tout sur une horloge virtuelle. Affiche la trace (chaque message avec son port d’origine, son port de destination et sa charge utile, chaque changement d’état) ; --json donne la même chose en JSON. --html : une seule page autonome qui l’exécute en direct dans un navigateur — le schéma de blocs, chaque message comme un point qui suit son lien, l’état de chaque part dans sa boîte ; Lecture/Pause, Pas (l’événement suivant) et Pas de (une durée fixe), une vitesse de 0,1× à 10×, un curseur pour revenir sur ce qui a tourné, Réinitialiser ; un formulaire par port d’entrée qui envoie tout de suite l’un de ses messages, une poussée (échelon ou impulsion) sur les sources d’un réseau physique (le réseau intégré dans la page), des courbes en direct des états, variables, champs de messages et grandeurs physiques ; les raccourcis (espace, →, Maj+→, ←, + / −, Début, R) sont listés sur la page. Ce qui n’est pas simulé est indiqué, jamais deviné : les corps en Python que le langage d’action ne sait pas exprimer sont listés une fois au début, et tournent dans python3 (--python <exe>), ou ne sont pas simulés avec --no-python ou sans python3. --plant : face à un environnement physique simulé ailleurs, en pas à pas synchronisé — le mujoco/plant_bridge.py de archec gen --target mujoco (lancé avec MUJOCO_PYTHON, sinon python3), ou toute commande qui parle ses lignes JSON. À chaque période qu’indique l’environnement physique, les messages de ses capteurs arrivent comme si leurs parts les envoyaient, le modèle exécute une période, et ce qu’il a envoyé aux parts de l’environnement physique repart vers elle. Sont simulés : le noise, la resolution et l’étendue d’un capteur, l’étendue de commande, le gain, le lag et le force-range d’un actionneur, et la latency d’un port (la trace montre chaque commande que prend un actionneur et sa sortie à ce moment-là). Le bruit est tiré de --seed (simulation { seed }, sinon 1). --keyframe K démarre de cette keyframe du système (et l’environnement physique aussi). Le Python que le langage d’action ne sait pas exprimer tourne dans un seul python3 pour toute l’exécution (--python, ARCHE_PYTHON, le .venv du modèle, sinon python3) : chaque appel est synchrone, avec une graine, sur l’horloge simulée, et un délai maximal (--py-timeout, 5 s). Ses paquets (pip "numpy") sont vérifiés et la commande pip affichée ; rien n’est installé. --doctest : les doctests de chaque fichier .py que nomme le modèle, dans ce Python. Voir le simulateur dans le navigateur et les corps Python. --batch N : N exécutions réparties sur des threads de travail ; une variable numérique d’une part est tirée dans chaque plage --vary (sa première valeur). Pour chaque exécution, les messages, changements d’état et erreurs sont comptés, et les variables numériques de chaque part relevées à la fin (--print en garde certaines), puis leur moyenne, min, max et σ — les mêmes exécutions pour une graine donnée, quel que soit le nombre de threads. |
archec physics <main.arche> <System|Def> [--for 1s] [--step 1ms] [--every 100ms] [--integrator rk4|euler|implicit|trapezoid] [--tol 1e-6] [--print a,b] [--csv file] [--json] [--set name=value] [--keyframe K] [--seed 1] [--equations]archec physics <main.arche> <System> --linearize [--at start|2s|x=1,…] [--inputs a,b] [--outputs y,z] [--lqr Q,R] [--json]archec physics <main.arche> <System> --batch N [--seed 1] [--vary name=lo..hi]… [--threads k] [--print a,b] [--csv file] [--json] |
Un réseau physique exécuté sans rien installer : des parts dont les ports ont un potential et un flow (include "std/physics"), liées sans sens. Le réseau est aplati (potentiels égaux et flux de somme nulle à chaque nœud), vérifié (autant d’équations que d’inconnues, chaque inconnue donnée une seule fois — sinon les parts en cause sont nommées), trié en blocs, chacun résolu dans l’ordre — une boucle linéaire en une fois, une boucle non linéaire déchirée et résolue par la méthode de Newton sur ses variables de déchirure —, puis les états sont intégrés à pas fixe (RK4, --euler). --integrator implicit (Euler implicite) et --integrator trapezoid (ordre deux) résolvent chaque pas par la méthode de Newton, la jacobienne par différences finies : sur un réseau raide (une constante de temps rapide à côté d’une lente), ils tiennent un pas sur lequel RK4 diverge. --tol rend le pas adaptatif, l’erreur de chaque pas restant dans cette tolérance (relative et absolue) : Dormand–Prince 5(4) pour RK4, doublement du pas pour les autres ; le nombre de pas s’affiche sur la sortie d’erreur. La commande affiche les variables de --print (par défaut : les états) tous les --every (un dixième de l’exécution) ; --csv écrit chaque variable à chaque pas ; --set donne sa valeur à une entrée (un signal in relié à rien) ou au paramètre d’une part (motor.ra.r=2) ; --equations affiche les équations triées sans rien exécuter. Index 0 seulement : des états liés par une équation sont signalés, pas réduits. --linearize : le réseau autour d’un point de fonctionnement, dx/dt = A·x + B·u, y = C·x + D·u, par différences finies centrées des dérivées des états (comme mjd_transitionFD de MuJoCo), à 7 chiffres. Le point est le départ (--at start), l’endroit où une exécution le laisse (--at 2s) ou des états donnés (--at c.v=5). Les entrées sont celles du réseau, ou des paramètres des parts dont les équations les utilisent (--inputs supply.v : le paramètre d’un composite est transmis, nommez donc la part qui l’utilise) ; les sorties, n’importe quelles variables du réseau (par défaut : les états). Viennent ensuite les valeurs propres de A — chacune une constante de temps, ou la fréquence et l’amortissement d’une paire — et la stabilité : stable, marginalement stable (un intégrateur : une position, un angle) ou instable. --lqr Q,R : le gain K de u = -K·(x - x0) qui minimise ∫ xᵀQx + uᵀRu, avec Q et R diagonales (un poids pour tous, ou un chacun : 10:1:1,0.1), par l’équation de Riccati continue, et les modes de la boucle fermée. --batch N : N exécutions, chacune avec les paramètres (motor.r) ou les entrées que nomme --vary tirés dans leur plage, réparties sur des threads de travail (--threads, par défaut autant que de cœurs, 8 au plus) ; les variables de --print (par défaut : les états) de chaque exécution à la fin, puis leur moyenne, min, max et σ. L’exécution i tire à partir de la graine et de i seulement : une graine donne donc les mêmes exécutions quel que soit le nombre de threads. --csv : une ligne par exécution ; --json : les exécutions et le résumé. Le signal in d’un actionneur qui a un gain, un lag ou un force-range (ou un type avec une plage) prend sa commande sur <port>.command et agit à travers eux, le retard devenant un état du réseau ; le signal out d’un capteur est affiché tel qu’il le lit (son noise tiré de --seed, la plage de son type, sa resolution, sa latency). --keyframe K démarre d’une keyframe du système (ses états, les commandes de ses actionneurs) ; --linearize --at K linéarise à cet endroit. |
archec fit <main.arche> <System|Def> <data.csv|log>… --params a,b[=lo..hi] [--signals x[=series],…] [--inputs u=series] [--step 1ms] [--method lm|nelder-mead] [--json] [--html report.html] [--write]archec fit <main.arche> --pass [TP|TC] [--params A,B=lo..hi] [--plant plant_bridge.py] [--method coordinate|grid|nelder-mead] [--tries 40] [--seed 1] [--propose ai] [--task \"…\"] [--write] [--no-tries] [--json] |
Les paramètres d’un réseau physique tirés de mesures (identification de système). Les données : un CSV (une ligne d’en-tête, le temps en premier ou dans une colonne t, un signal dans chaque autre colonne, une unité entre crochets convertie en SI : t (ms), w (rpm) ; une cellule vide n’est pas un échantillon), ou un journal que lit archec replay (candump, ASC, BLF, MCAP, lignes JSON), décodé par le modèle, chaque champ numérique formant une série MSG.field. Une série pilote l’entrée (un signal in relié à rien) ou est comparée à la variable dont elle porte le nom : load.w, son nom aplati load_w, ou MSG.load_w ; --signals load.w=MOTOR.speed et --inputs src.u=PROBE.u l’indiquent quand les noms diffèrent. Un paramètre est celui d’une part (motor.r : son argument, sinon la valeur par défaut de sa définition), celui du système lui-même ou une déclaration parameter ; ses bornes sont sa tolérance (ou min/max), sinon son signe, ou name=lo..hi dans son unité. Le réseau est exécuté (RK4, les entrées mesurées interpolées linéairement entre échantillons) à partir des valeurs initiales du modèle, et les paramètres sont trouvés par moindres carrés — chaque signal mis à l’échelle de sa dispersion — par Levenberg–Marquardt sur une jacobienne en différences finies, ou par Nelder–Mead quand celui-ci ne progresse plus (ou avec --method nelder-mead). La commande affiche chaque valeur dans son unité avec son incertitude (1σ, tirée de s²·(JᵀJ)⁻¹), et l’erreur RMS de chaque signal avant et après. Elle émet l’avertissement fit-no-influence pour un paramètre que les signaux ne font pas varier (non ajusté), et fit-correlated pour deux paramètres qui les font varier de la même façon (corrélation au-dessus de 0,999). --html trace la mesure, l’avant et l’après pour chaque signal ; --write met les valeurs ajustées dans la source (l’argument d’une part remplacé ou ajouté, une valeur par défaut ou la value d’un parameter), vérifiées d’abord comme le fait archec edit. --pass : les constantes réglables d’un contrôleur (une const avec une range, ou nommées par --params KP=5..80) essayées jusqu’à ce que chaque cas de test et chaque exigence vérifiée pendant l’exécution réussissent, sur le simulateur ou face à --plant (réglage). La recherche a une graine et est bornée par --tries : des pas par coordonnée par défaut, une grille, ou Nelder–Mead. Chaque comparaison en échec reçoit un score selon son écart. --propose ai laisse une IA proposer les valeurs, à travers la passerelle (hors ligne : refusé) ; c’est toujours l’exécution qui décide. Chaque essai va dans .arche/tries/ (valeurs, verdicts, une trace échantillonnée) ; --no-tries n’en garde aucun. --write écrit les valeurs qui réussissent ; celles d’une IA sont marquées dans .arche/provenance.jsonl. Code de sortie 1 quand aucun essai ne réussit. |
archec difftest <main.arche> [System] [--seed 1] [--steps 50] [--for 2s] [--target c] [--deployment D] [-o dir] [--json] |
Le test différentiel : le simulateur (le moteur d’exécution d’archec sim) et le code qu’écrit archec gen --target c, pilotés avec les mêmes entrées, doivent faire la même chose. Les entrées sont aléatoires mais reproductibles (--seed) : --steps messages venus de l’extérieur, chacun vers un port d’une part qui le reçoit, avec des valeurs de champs aléatoires, espacés de 1 à 20 ms. Le C de chaque composant est compilé avec un harnais (CC, sinon gcc, sinon cc) qui les rejoue sur une horloge virtuelle, les transmet le long des liens du système avec leur latence, et traite ce qui arrive au même instant dans l’ordre du simulateur. Les deux traces — entrées, changements d’état, messages envoyés avec leur charge utile (celle du C décodée à partir de ses octets), messages envoyés sur un port relié à rien — sont ensuite comparées dans l’ordre et dans le temps, et la première divergence s’affiche avec les événements qui la précèdent. Ce qu’un côté ne sait pas traduire (du Python que le langage d’action ne sait pas exprimer, du TypeScript hors du sous-ensemble portable, un corps qui attend) est listé comme non comparé. -o : où vont le C et son harnais (un dossier temporaire par défaut) ; --json : les entrées, les deux traces et la divergence. Code de sortie 1 en cas de divergence, 2 quand le test ne peut pas tourner (pas de compilateur, le C ne compile pas). Le bruit d’un capteur est tiré de la même graine des deux côtés (le C compilé avec -DARCHE_SIM), et chaque commande que prend un actionneur, avec sa sortie à ce moment-là (gain, retard, force-range), est comparée aussi. |
archec where <main.arche> [-o <dir>] "<error text>" |
L’endroit des sources où se trouve une erreur que signale Arche : (Controller › Control loop, line 4) → ctrl.py:32. |
archec where <main.arche> [--gen generated] [--from <dir>] "<compiler output>" | - |
L’erreur d’un compilateur C, Rust ou Go (gcc, clang, rustc, go) dans du code écrit par archec gen → l’élément du modèle dont il vient et sa ligne .arche, grâce à generated/.archec/genmap.json ; une ligne dans une région USER CODE est signalée comme telle. --from : le dossier où a tourné le compilateur (make dans c/<binary>). Avec -, la sortie est lue sur l’entrée standard, l’élément s’affichant sous chaque ligne (régénération). |
archec ci <main.arche> [-o <dir>] [--strict] [--coverage-min <percent>] [--require-tests] [--require-approval] [--debt-max <percent>] [--tests-first [--range a..b] [--prove-red] [--test-cmd "… {file}"]] [--junit <report.xml>] [--sarif <report.sarif>] |
Ce que vérifie une chaîne d’intégration, en une seule commande : lint, format, interface (une liaison, un appui ou une étape de test d’interface qui ne tient pas — un bouton qui envoie un message renommé depuis), temps, TARA, construction, tests et couverture. Une ligne par étape, un rapport JUnit avec --junit, chaque diagnostic (y compris les constats de style) en SARIF avec --sarif, code de sortie 1 quand une étape échoue. Sans arche-cli, les cas qui ont une étape d’interface tournent quand même (sur le simulateur du navigateur), les autres sont sautés, sauf avec --require-tests. --require-approval : une étape approval, chaque exigence approuvée dans sa formulation actuelle (archec approve). --tests-first : une étape tests-first sur --range (par défaut, depuis l’endroit où la branche a quitté son amont, origin/main, main ou master). Chaque fonction que la plage ajoute, hors des fichiers de test, a besoin d’une exigence (sur son fn ou sur sa part) et d’un cas de test qui la vérifie, dans le modèle et dans git, au commit de la fonction ou avant. Le fichier d’un cas est sa source, ou son libellé quand c’est un chemin ("test/add.test.js", "test/gen.test.js › embassy"). --prove-red lance chacun de ces tests sur le commit qui précède celui de la fonction, dans un worktree git temporaire supprimé ensuite, avec le fichier de test tel qu’il était au commit de la fonction : il doit y échouer. La commande dépend du langage du fichier (node --test, pytest, go test, cargo test), ou c’est --test-cmd avec {file} et {name}. Les fonctions écrites par un assistant IA sans exigence ou sans test sont signalées à part. L’étape agent-context échoue quand CLAUDE.md ou AGENTS.md à côté du modèle contient un bloc d’archec agent-context que le modèle ne donne plus (pas d’étape de ce genre sans bloc). |
archec validate <arche-project-dir> |
Le YAML d’un projet Arche vérifié par rapport au schéma. |
archec diff <a> <b> |
Deux projets (des dossiers, ou un point d’entrée .arche) comparés en tant que données. |
En savoir plus sur ces commandes#
archec sim main.arche --html sim.html écrit une page qui exécute le modèle en direct dans n’importe quel navigateur,
comme la visionneuse de MuJoCo exécute une scène. La page propose :
- lecture et pause, un pas jusqu’à l’événement suivant ou d’une durée fixe, et une vitesse de 0,1× à 10× ;
- un curseur pour revenir sur ce qui a tourné (l’exécution rejouée, avec ce que vous avez envoyé) ;
- un formulaire par port d’entrée qui envoie tout de suite l’un de ses messages, avec le type, la plage et les valeurs d’énumération de chaque champ ;
- une poussée (un échelon ou une impulsion) sur les sources d’un réseau physique ;
- des courbes en direct des états, variables, champs de messages et grandeurs physiques de votre choix.
Les raccourcis clavier sont listés sur la page (docs/sim.md).