Écrire et vérifier
Les commandes que vous utilisez pendant que vous écrivez un modèle : le vérifier, le corriger et le formater.
Commandes : archec check · archec fix · archec explain · archec suggest · archec vet · archec fmt · archec edit · archec review · archec live-fix · archec mcp · archec convert-handlers · archec stubs · archec patterns · archec ast
Sur cette page : Analyse de code (SARIF) · Plus de détails sur ces commandes
| Commande | Ce qu’elle fait |
|---|---|
archec check <main.arche>… [--json] [--strict] [--quiet] [--beginner] [--core] [--sarif <report.sarif>] |
Lint : erreurs, avertissements et indications, chacun avec son code ([unresolved], [suspect], [rule]…). Code de sortie 1 en cas d’erreur ; avec --strict, aussi en cas d’avertissement. --sarif : les mêmes diagnostics au format SARIF 2.1.0, pour l’analyse de code (plus bas). Les rule propres au projet et les liens rendus suspects par une exigence reformulée en font partie. --beginner (ou ARCHE_LEVEL=beginner) : les messages courants en mots simples, avec ce qui existe (« You used bar but b has no port called that. Its ports are: cmd, st. »), et le nombre d’erreurs qu’archec fix peut corriger (correctifs). --core : aussi une erreur (not-core) pour chaque déclaration ou propriété des fichiers du projet hors du cœur 1.0, avec le nom de l’extension à laquelle elle appartient (cœur). S’il n’y en a aucune, la commande dit combien de concepts du cœur le modèle utilise. |
archec fix <main.arche> [--dry-run] [--only code,…] [--vet] [--json] |
Les erreurs qui se corrigent seules. Pour chaque diagnostic, le correctif préféré est appliqué (le nom, la propriété, la valeur ou l’unité la plus proche, les extrémités du lien inversées, la direction d’un port, un ; avant une propriété collée, un fichier que nomme un include…), un par endroit. Le modèle est ensuite vérifié de nouveau, jusqu’à ce qu’aucun correctif ne s’applique (5 passes au plus). La commande affiche chaque correctif et le diff. --dry-run n’écrit rien. Les correctifs qui devinent du contenu ou qui suppriment quelque chose (une déclaration inutilisée, un texte provisoire) sont proposés par l’éditeur, mais pas appliqués, sauf si --only nomme leur code. Les remarques de style ne sont traitées qu’avec --vet. Une passe qui ajoute des erreurs est refaite correctif par correctif, en ne gardant que ceux qui n’en ajoutent aucune. Voir les correctifs. |
archec explain [<code>| <area>] |
Ce que signifie un code de diagnostic ([naming], [unresolved]…), et la section du guide de style qui en parle. Sans code : les domaines auxquels appartiennent les codes (analyse syntaxique, noms, types, liens, timing, sûreté, style…). archec explain timing liste les codes d’un domaine, un par ligne. Une faute de frappe proche donne une suggestion. Dans le terminal, les messages longs sont coupés après leur première phrase ; --long les affiche en entier. La dernière ligne donne la page du code sur arche-lang.xyz (/docs/errors/<code>/), celle vers laquelle pointe l’éditeur. --json affiche tout le catalogue : chaque code avec son domaine, sa gravité, son résumé et son correctif automatique. |
archec review <main.arche> [--threshold 0.3] [--suggest] [--dry-run] [--json] [--model id] |
Des conseils de Claude (claude-opus-5-5) sur les traces. Le vérificateur sait que les deux extrémités d’une trace existent, mais pas si le lien a du sens. Cette commande pose la question : un jugement par trace, à partir de ce que les deux éléments disent d’eux-mêmes (et de la justification de la trace). Elle liste celles qui sont sous le seuil. --suggest liste aussi les parts qui satisfont très probablement une exigence sans qu’aucune trace ne le dise. Ce sont des conseils, tenus à part : rien n’en parvient à check, à ci ou à un build, et les réponses ne sont pas reproductibles. Du texte du modèle part à l’extérieur : le type, l’id, le nom et les textes de chaque élément tracé sont envoyés à l’API Anthropic, uniquement quand cette commande s’exécute. --dry-run affiche les requêtes et n’envoie rien. Identifiants : ANTHROPIC_API_KEY, ou ant auth login. Une requête refusée bascule sur un autre modèle côté serveur. Hors ligne par défaut : archec config ai online (ou ai local-ai) l’autorise à envoyer (ai-engineering.md). |
archec live-fix <ID> [main.arche] [--state .arche/live.json | --replay <trace>… [--deployment D]] [--dry-run] [--json] [--model id] |
Expliquer et corriger : pourquoi une exigence, une chaîne, un thread ou un conteneur qu’archec live voit en échec échoue, et les modifications des fichiers .arche qui le corrigeraient, selon Claude (claude-opus-5-5). La commande lit le dernier état en direct (.arche/live.json à côté du fichier principal, qu’archec live réécrit à chaque rafraîchissement ; --state en désigne un autre ; --replay lance archec live --replay sur les traces jusqu’à leur fin). Elle envoie l’élément, ses preuves, ce qui a été mesuré, ce qu’archec analyze prévoit pour les chaînes, threads et conteneurs concernés, et leurs déclarations avec le fichier et la ligne. Chaque modification proposée remplace un texte trouvé à sa ligne (ou à 5 lignes près). Les autres sont écartées avec leur raison. --json : {explanation, edits: [{file, line, col, endLine, endCol, old, new, why}], rejected, notes}, que l’extension VS Code applique sous forme de modification avec aperçu. Ce sont des conseils, comme pour review : du texte du modèle part à l’extérieur, uniquement quand cette commande s’exécute. --dry-run affiche la requête et n’envoie rien. Hors ligne par défaut : archec config ai online (ou ai local-ai) l’autorise à envoyer (ai-engineering.md). |
archec mcp |
Le compilateur comme serveur Model Context Protocol sur stdio, pour les agents IA. Ses outils correspondent un à un aux commandes : check (les diagnostics en JSON), fix (les correctifs de chaque diagnostic, sous forme de modifications par ligne et colonne ; apply: true applique les correctifs préférés comme archec fix), explain, describe (la référence du langage pour un mot-clé), outline (les déclarations, imbriquées, avec le fichier et la ligne), brief (le contexte d’une part avant de la modifier, comme archec brief ; task: true écrit .arche/task), analyze, format, diff, generate, build. Pour un système en marche, il y a aussi live_status (ce que voit archec live : .arche/live.json, ou un rejeu des traces fournies) et live_explain (la requête qu’enverrait archec live-fix, ou, avec send: true, la réponse de Claude). Pour régler un contrôleur sur le simulateur (réglage) : scenario_list (les cas de test et les réglables), sim_run (les cas lancés : réussite ou échec, un score, les vérifications en échec avec leurs valeurs ; values essaie des réglables sans les écrire ; chaque exécution est un essai dans .arche/tries/), sim_observe (des signaux échantillonnés à des instants donnés), params_get et params_set (écrits dans la source, vérifiés, marqués comme modification d’une IA). Les chemins sont relatifs au dossier où il tourne. L’agent modifie lui-même les fichiers .arche et appelle check : le compilateur reste le juge. Dans Claude Code : claude mcp add archec -- archec mcp. |
archec suggest <main.arche> [--json] |
Ce que les rayons du store ont déjà pour ce que le modèle écrit à la main. Pour chaque proposition : où, à quoi elle ressemble, pourquoi, et les lignes exactes à ajouter (uses, include). Une fonction ou un composant dont le nom ou le corps ressemble à l’un des algorithmes : pid dans le nom, ou integral avec kp/ki ; debounce ; moving_average, ou une somme sur une window ; y += a * (x - y) (passe-bas) ; un polynôme de CRC (0x1021, 0xEDB88320) ; et les autres par leur nom. Un message ou une struct dont les champs forment un type d’arche-types : x, y, z donne Vec3 (Point3 en m), w, x, y, z Quaternion, lat/lon GeoPoint, r, g, b RgbColor… La proposition donne le remplacement (message ACCEL: Vec3) quand les noms et les types des champs sont exactement les mêmes. Un composant qui porte le nom d’un périphérique du store (Bme280Sensor). Ce qui requiert déjà l’interface de l’algorithme, ou étend le composant d’une bibliothèque, est laissé tel quel. Rien n’est modifié : archec shelf add ou archec device add ajoute une pièce. L’éditeur montre la même chose sous forme d’indications discrètes (l’éditeur). |
archec vet <main.arche>… [--json] |
Le style, comme go vet : formes longues, ordre et groupes des propriétés, déclarations hors de leur ensemble, nommage. archec check les laisse de côté (--vet les y montre aussi). Code de sortie 1 s’il y a une remarque. archec fmt --write corrige celles de mise en page. |
archec fmt <file.arche>… [--write|--check] [--simplify] [--extract-code[=file.ts|file.py]] |
Formate (vers la sortie standard, ou sur place avec --write ; --check échoue quand un fichier n’est pas formaté). --simplify réécrit les formes longues en formes courtes, avec le même sens. --extract-code déplace les blocs ```ts (ou ```python) dans des fichiers .ts (.py) : un par composant, dans son langage, ou tous dans le fichier nommé. --edition 0.12 : le projet indique alors l’édition dans laquelle il est écrit (edition "0.12"), où les anciennes écritures sont des erreurs. |
archec edit <main.arche> <element-id> [--set <key> <value>]… [--unset <key>]… [--label "…"] [--dry-run] |
Modifie les propriétés ou le libellé d’un élément dans son fichier .arche, désigné par son id tel que le donne archec export (REQ-BRK-3, Vehicle.ctrl, BRAKE_STATUS). La valeur est écrite en arche-lang (--set period 20ms, --set satisfies REQ-1). Rien n’est écrit si le modèle a plus d’erreurs qu’avant. C’est ce que lance Element.set dans le paquet Python. |
archec convert-handlers <main.arche> --to typescript|python|arche [--component X] [--dry-run] |
Réécrit sur place les handlers du modèle dans un autre langage : les blocs (leur délimiteur et leur indentation conservés), les fichiers `code` (`code "x.py"` devient `"x.ts"`, un nouveau fichier à côté de l’ancien, qui est gardé ; vers `arche`, chaque fonction devient un bloc ````arche sur son élément), les gardes des transitions et les `handlers` du projet (ceux du composant, avec `--component`). Depuis ```arche ````, la conversion est exacte. Depuis Python et TypeScript, elle se fait instruction par instruction, à travers ce que dit le langage d’actions (handlers.md). Une instruction qui ne se traduit pas reste en commentaire // TODO(convert): <original> (# en Python), listée avec la raison ([convert-todo]) et signalée par archec check tant qu’elle n’est pas écrite. Les champs d’un message : des noms nus en Python, msg.field en TypeScript (message ↔ msg.name). Rien n’est écrit si le résultat a plus d’erreurs que le modèle. --dry-run indique ce qui le serait. |
archec stubs <main.arche> [--out <dir>] [--beside] [-o arche.d.ts|arche.py] |
Ce dont les éditeurs ont besoin pour connaître l’API d’Arche et les noms du modèle, dans .arche/typings dans le dossier du fichier principal : un paquet arche typé pour les fichiers .py du modèle (arche/__init__.pyi, arche/_model.pyi) et arche.d.ts pour ses fichiers .ts. Rien n’est écrit à côté du code. Un fichier principal qui ne s’appelle pas main.arche a .arche/typings/<name>. Le dossier a son propre .gitignore. --out <dir> écrit dans un autre dossier. --beside écrit un arche.py et un arche.d.ts (avec un tsconfig.json s’il n’y en a pas) à côté des fichiers de code, comme le faisaient les versions précédentes. Pour pyright en ligne de commande : extraPaths = [".arche/typings"] sous [tool.pyright] dans pyproject.toml ; pour mypy : mypy_path = ".arche/typings" (python.md, handlers.md, editor.md). |
archec patterns [-o patterns.md] |
La référence de toutes les déclarations (patterns.md). |
archec ast <file.arche> |
L’arbre syntaxique (pour le débogage). |
Analyse de code (SARIF)#
--sarif report.sarif écrit les diagnostics au format SARIF 2.1.0,
que lisent l’analyse de code de GitHub, GitLab et les visionneuses SARIF. Chaque code de diagnostic est une règle : son id est le
code (unresolved), son aide est ce qu’affiche archec explain <code>. Chaque diagnostic est un résultat situé à son
fichier, sa ligne et sa colonne, le fichier étant relatif au dossier courant : lancez archec depuis la racine du dépôt.
Les niveaux : error → error, warning → warning, info → note, hint → none.
Un job GitHub Actions qui les affiche sur la pull request :
name: model
on: [push, pull_request]
permissions:
contents: read
security-events: write # to upload the report
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npm install -g arche-lang
- run: archec check main.arche --sarif archec.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always() # upload even when archec check fails
with:
sarif_file: archec.sarif
category: archec
Plus de détails sur ces commandes#
archec review main.arche demande à Claude si chaque trace est plausible d’après ce que disent ses deux extrémités, et
liste celles qui sont douteuses (--suggest : aussi celles qui manquent). Ce sont des conseils, jamais intégrés à check ni à ci,
et la commande envoie les textes des éléments tracés à l’API Anthropic. --dry-run montre ce qui serait envoyé et n’envoie rien.
Pour les agents IA, archec mcp est le compilateur comme serveur Model Context Protocol
sur stdio. Ses outils sont les commandes : check, explain, describe (la syntaxe d’un mot-clé),
outline, brief (à appeler avant de modifier une part), analyze, format, diff, generate, build. L’agent modifie les fichiers .arche et appelle
check. Dans Claude Code : claude mcp add archec -- archec mcp.