Guides pratiques › Corriger les erreurs courantes

Guides pratiques

Correctifs et niveau débutant

archec sait corriger les erreurs que font le plus souvent les nouveaux venus. Un correctif est un ensemble de modifications de texte qu’archec calcule à partir du modèle vérifié (dans src/fixes.ts). Une fois le correctif appliqué, son diagnostic disparaît. Les tests appliquent chaque sorte de correctif, puis vérifient de nouveau le modèle.

Un premier correctif#

Ce modèle contient une faute de frappe : le lien aboutit sur lamp.cdm, mais le port s’appelle cmd.

message GO: bool

component Lamp "Lamp" {
  in cmd: can receives GO
}

component Button "Button" {
  out click: can sends GO
}

system Room "Room" {
  part lamp: Lamp
  part button: Button
  button.click -> lamp.cdm
}

Enregistrez-le sous main.arche et vérifiez-le :

archec check main.arche
main.arche:14:19 error Cannot find 'lamp.cdm' in Room. Did you mean 'lamp'? [unresolved]
  |   button.click -> lamp.cdm
  |                   ^^^^^^^^
✗ 1 error(s), 0 warning(s)

Laissez maintenant archec le corriger :

archec fix main.arche
main.arche:14 [unresolved] Change to 'cmd'

--- main.arche
@@ line 14 @@
   part button: Button
+  button.click -> lamp.cmd
-  button.click -> lamp.cdm
 }

1 fix(es) applied in 1 file(s)

archec check main.arche affiche maintenant ✓ no errors.

Où trouver les correctifs#

  • Dans VS Code : l’ampoule sur un diagnostic (Ctrl+. ou Cmd+.). Le premier correctif de la liste est le correctif préféré. C’est celui qu’appliquent Fix all et Auto Fix. Chaque diagnostic propose aussi Explain [code], qui ouvre, à côté de l’éditeur, ce que dit archec explain <code>.
  • archec fix <main.arche> : applique le correctif préféré de chaque diagnostic, un correctif par endroit. Puis il vérifie de nouveau, et recommence jusqu’à ce qu’aucun correctif ne s’applique. Il affiche chaque correctif et le diff. Options :
    • --dry-run montre les correctifs et n’écrit rien ;
    • --only unresolved,missing-unit n’applique que les correctifs de ces codes ;
    • --vet applique aussi les correctifs des remarques de style (celles d’archec vet).
  • Le serveur MCP (archec mcp) : son outil fix donne les correctifs de chaque diagnostic sous forme de modifications, par ligne et par colonne. Un assistant d’IA applique donc le correctif au lieu de le deviner. Avec apply: true, l’outil fait ce que fait archec fix.

Ce qui est corrigé#

Certains correctifs sont proposés, et non appliqués. Ce sont ceux qui devinent quoi écrire, ou qui suppriment quelque chose. L’éditeur les propose, et archec fix n’y touche pas. Lisez un tel correctif avant de le choisir.

Code Le correctif
unresolved (et unknown-porttype) Une définition, un type, une interface ou un autre nom déclaré dans un fichier du projet que le modèle n’inclut pas : le message dit quel fichier, et le correctif ajoute include "<file>". Quand plusieurs fichiers le déclarent, chacun est proposé, et aucun n’est appliqué. Un nom que le store possède (Pid, Bme280) : le correctif ajoute son uses et son include. Sinon, le nom le plus proche parmi ceux visibles, selon la distance d’édition. Pour une extrémité de lien, c’est une part, ou un port de cette part. Sinon, une définition, un type, un message ou un état. Le dernier choix consiste à déclarer le nom manquant.
unknown-property La propriété la plus proche pour ce genre de déclaration. La suppression de la propriété est proposée, pas appliquée.
property-value La valeur autorisée la plus proche : buffer smaple → sample. Un nom placé là où un texte est attendu est mis entre guillemets.
missing-unit / bad-unit L’unité de temps : 10 → 10ms, 10sec → 10s.
unknown-unit L’unité du catalogue la plus proche. La déclaration de l’unité est proposée.
direction La direction du port est changée pour correspondre à ce qu’il fait : un port in qui envoie devient inout.
link-direction Les deux extrémités du lien sont inversées, quand cela met chacune du bon côté. Sinon, le port devient inout.
wrong-side buffer, depth, overflow et stale-after passent du port out à l’unique lien qui en part.
duplicate Le second est renommé : cmd → cmd2.
missing-separator Un ; est ajouté avant une propriété collée au Python.
include-not-found Le fichier est créé, vide.
naming Le nom est mis à la convention de nommage, avec toutes ses utilisations (proposé). Le renommage de l’éditeur renomme aussi les utilisations dans le Python. archec fix --only naming renomme les utilisations dans le modèle.
unused Supprimé (proposé, pas appliqué).
no-system, empty-system Un système avec une part de chaque définition ; ou une part ; ou un composant et une part de ce composant (proposé, pas appliqué).
requirement-no-text text "The system shall …", à compléter par vous (proposé, pas appliqué).
arche-body Un corps Python qui ne dit que ce que le langage d’action sait dire est réécrit en corps ```arche. Par exemple self.state == "Ready" → state == Ready, await goto("Auto") → goto Auto, send(self.p, M(f=1)) → send p M { f: 1 }. Le correctif est refusé quand le corps en fait plus : une liste qui grandit, un appel de bibliothèque, un nom que le modèle n’a pas. C’est une remarque de style : seuls archec fix --vet ou --only arche-body l’appliquent.
advanced level full est ajouté au projet (proposé, pas appliqué).

archec fix ne laisse jamais le modèle en plus mauvais état. Une passe de correctifs peut ajouter des erreurs, par exemple un renommage qui oublie une utilisation. Dans ce cas, archec essaie chaque correctif de la passe isolément et écarte ceux qui ajoutent une erreur.

En termes simples#

Le niveau débutant reformule les messages courants en termes simples, et liste ce qui existe. Activez-le de l’une de ces trois façons :

  • archec check --beginner ;
  • la variable d’environnement ARCHE_LEVEL=beginner ;
  • le réglage VS Code arche.level mis à beginner.

Avec le modèle du premier correctif :

archec check --beginner main.arche
main.arche:14:19 error You used `cdm` but `lamp` has no port called that. Did you mean `cmd`? Its ports are: cmd. [unresolved]
  |   button.click -> lamp.cdm
  |                   ^^^^^^^^
✗ 1 error(s), 0 warning(s)
1 of them fix themselves: `archec fix main.arche` (`--dry-run` shows how first)

Le niveau simple#

Un projet peut indiquer quelle part du langage il utilise :

project "Pump" {
  level simple
}

Au niveau level simple, la complétion propose exactement le cœur 1.0 du langage (core.md), ses déclarations et leurs propriétés :

  • le projet, ses bibliothèques et include ;
  • les données, les messages et les unités, les exigences ;
  • system, component et part, les ports, les interfaces et les liens ;
  • fn, var, handler et states ;
  • les plans de test, et où tout tourne : un deployment, ses binaires, ses threads et ses chaînes.

Tout le reste se lit et se construit toujours. Une déclaration hors du cœur reçoit une indication, advanced. Celle-ci invite à mettre level full pour l’utiliser.

Quand le projet n’a pas de level, c’est le réglage VS Code arche.level qui décide : beginner correspond au niveau simple, et expert (la valeur par défaut) à tout le langage.

Limites#

  • Un correctif qui devine quoi écrire, ou qui supprime quelque chose, n’est jamais appliqué par archec fix. C’est vous qui le choisissez dans l’éditeur.
  • Le correctif arche-body ne réécrit qu’un corps Python simple. Un corps avec une liste, un appel de bibliothèque ou un nom que le modèle n’a pas reste en Python.
  • archec fix --only naming ne renomme les utilisations que dans le modèle. Le renommage de l’éditeur suit aussi le Python.

Tous les codes d’erreur#

Chaque code de diagnostic a sa page — ce qu’il signifie, comment le corriger, et sa correction automatique s’il y en a une : les codes d’erreur, par domaine.