Référence › Commandes › Code and model

Référence › Commandes

Code et modèle

Les commandes qui comparent du code existant au modèle.

Commandes : archec recover · archec conform · archec arch-diff · archec impact · archec brief · archec agent-context

Commande Ce qu’elle fait
archec recover <src-dir> [-o recovered.arche] [--lang ts,js,go,py,c,rust] [--depth N] [--min-imports N] [--std] [--json] [--graph gitnexus] L’architecture d’un code, en arche-lang, pour du code que personne n’a dessiné (ou qu’une IA a écrit). Un petit analyseur par langage lit les imports de chaque fichier : en TS/JS, import, export … from, require, import() ; en Go, import avec le chemin de module de go.mod ; en Python, import et from … import, relatifs ou par paquet ; en C/C++, #include "…" (le dossier, puis include/, puis le nom) ; en Rust, mod, use crate::/super::/self::. Les dossiers de dépendances et de build (node_modules, vendor, dist, build, target…) et les fichiers qui se déclarent générés sont ignorés. Une part est un dossier. Les dossiers s’imbriquent jusqu’à --depth niveaux (2). Quand un dossier contient plus de 12 fichiers à lui, ils sont répartis en groupes. D’abord, les fichiers que la plupart des autres importent sont mis à part (common). Puis viennent les familles de noms qui s’importent entre eux (websim*, parser* : un radical de 4 lettres ou plus). Le reste est placé selon le couplage (modularité, une famille ne rejoignant jamais une autre). Un groupe de plus de 20 fichiers est découpé à nouveau. Les fichiers qui n’importent que les fichiers communs sont chacun seuls au premier niveau, ou réunis (others) dans un dossier. Un groupe porte le nom de son radical, sinon celui du fichier que les autres importent le plus. Un dossier d’un ou deux fichiers qu’un seul voisin importe, quand les voisins sont nombreux, est fusionné dans ce voisin. Chaque paquet extérieur est une part de kind external (prop package). Les bibliothèques standard (les modules de Node, ceux de Python, ceux de Go, la libc, std de Rust) sont ignorées et comptées dans une note. --std les garde, une part chacune (node, python, go, libc, std). Chaque part indique ses fichiers avec source (un dossier src/gen/**, ou des fichiers). Les fonctions de son port api sont les noms que les autres importent d’elle. Il y a un lien par paire de parts, avec le nombre d’imports. Dans un bloc de plus de 12 liens, ceux de moins de 3 imports sont faibles : ils sont listés dans la prop weak_links du bloc et ne sont pas dessinés (--min-imports N fixe le seuil, dans tous les blocs ; 1 les dessine tous). Un cycle est signalé par les liens légers dont le retrait le casse (un ensemble d’arcs de retour pondéré par les imports), chacun avec le fichier et la ligne d’un import, ou, pour un grand cycle, par ce qu’il faut couper en premier. Les imports non résolus et les imports d’un nom calculé deviennent aussi des commentaires // recovered:, tout comme huit noms de plus au-delà des dix fn d’une part. Le système indique prop recovered (la commande) : archec diagram dessine alors ses 30 liens les plus lourds. Le résultat passe la vérification sans erreur et archec diagram le dessine. --json donne les parts, leurs fichiers, les liens avec le fichier et la ligne de chaque import, les cycles et leurs coupures. --graph gitnexus compte sur les liens les appels entre fichiers d’un index GitNexus (sans le programme ou sans index, une note en donne la raison et seuls les imports servent).
archec conform <main.arche> [--src dir] [--lang …] [--system S] [--directed] [--json] [--junit file] Le modèle confronté au code : le modèle de réflexion (Murphy et Notkin). Les fichiers d’une part sont ceux que nomme sa source (la source la plus précise l’emporte : un fichier avant un glob, un dossier plus long avant un plus court). Les imports du code sont ramenés aux deux parts situées sous leur part commune la plus proche. Chacun est alors une convergence (un lien du modèle les relie), une divergence (aucun lien : une erreur au fichier et à la ligne de l’import) ou, pour un lien sans aucun import, une absence (un avertissement sur le lien). Un lien autorise les imports dans les deux sens (les données et les imports vont souvent en sens opposés). --directed exige qu’ils suivent son sens. Les fichiers qu’aucune part ne nomme, et ceux que deux parts nomment, donnent des avertissements. Un paquet extérieur est comparé quand une part déclare être ce paquet (prop package = "yaml"). Une paire de parts qu’un bloc liste dans prop weak_links ("a -> b: 1 import", comme l’écrit archec recover) est autorisée, et ses imports sont comptés à part (avec --directed, dans son sens seulement). Le code est lu dans le dossier du fichier principal, ou dans --src. Code de sortie 1 en cas de divergence. archec ci lance cette commande comme étape conform quand une source nomme un fichier du code.
archec arch-diff <src-dir> <rev-a>[..<rev-b>] [<rev-b>] [--model main.arche] [--lang …] [--depth N] [--std] [--json] [--md] Compare l’architecture de deux révisions git. Chacune est reconstruite à partir des blobs de git (rien n’est extrait). La seconde est groupée comme la première, pour qu’un fichier reste dans son groupe, et un dossier est découpé en groupes ou gardé entier comme dans la première (un dossier qui a franchi les 12 fichiers est signalé sous Folders, et non comme des fichiers déplacés). Sans seconde révision, c’est l’arbre de travail qui sert. La commande donne les parts ajoutées, supprimées et renommées, les fichiers passés d’une part à une autre, le nombre de fichiers, les liens ajoutés, supprimés ou avec plus ou moins d’imports, les cycles apparus et disparus. --model donne les divergences à chaque révision par rapport à ce modèle, et les nouvelles (avec alors le code de sortie 1). --md donne du Markdown pour un commentaire de pull request.
archec impact <rev-a>..<rev-b> | <rev-a> <rev-b> | --staged [--model main.arche] [--src dir] [--md|--json] [--no-arch] Pourquoi chaque morceau d’un diff existe. Chaque bloc de modification de la plage (ou de ce qui est indexé) est placé dans sa part, d’après la source des parts (comme archec conform place les fichiers). Puis dans les fonctions qu’il touche : ajoutées, modifiées ou supprimées, lues lexicalement en TS/JS, Go, Python, C/C++ et Rust (une méthode s’écrit Class.name). Puis dans les exigences qui y sont tracées : satisfies sur le fn de la part qui porte ce nom (ou ce libellé), sinon sur la part ou sur une part au-dessus. Chaque exigence liste les tests qui la vérifient. Les blocs dans des fichiers qu’aucune part ne nomme sont listés à part, de même que les fichiers qui ne sont pas du code. Les fonctions auxquelles aucune exigence ne mène sont listées. Vient ensuite le changement d’architecture, tel que le donne archec arch-diff, sur les dossiers que nomme la source des parts (--no-arch : laissé de côté). Le modèle est --model, sinon le main.arche du dossier courant ; sans modèle, seulement les fichiers et les fonctions. Rien n’est envoyé nulle part. --md : du Markdown pour une pull request.
archec brief <main.arche> <System.part> [--md|--json] [--task] [--src dir] [-o file] Le contexte d’une part, pour un assistant IA (ou un collègue) qui va la modifier, tiré du modèle et des fichiers à côté, hors ligne. Son interface (ports et fonctions, tels qu’écrits). Ses voisines, les parts qui lui sont reliées dans son bloc, par leur interface et jamais par leur code. Les exigences qui lui sont tracées (à la part, à sa définition, à un de leurs ports ou de leurs fonctions) et les cas qui vérifient chacune, ou le fait qu’aucun ne le fait encore. Les parts dont elle peut dépendre, comme archec conform remonte un import : un lien de son propre bloc, ou d’une part qui la contient, et les weak_links. Les fichiers qui lui appartiennent (source, la plus précise l’emportant, comme archec conform les associe). Dans les dossiers qu’archec gen a écrits (leur .archec/genmap.json), ses fichiers générés et les régions USER CODE qu’elle peut modifier. Les budgets des parts qui la contiennent et ce qu’elle consomme, les chaînes qui la traversent. Les règles du projet sur ce qu’elle a. Ce que check et vet disent maintenant de ses déclarations. Ses approbations. Pour finir, une empreinte du modèle : ce que le modèle dit de la part (pas des lignes, des fichiers ou des constats), pour voir qu’un brief a changé pendant une tâche. Une part est désignée par son chemin (Car.brakes, Toolchain.compiler.parser), ou par un nom qu’une seule part porte. Markdown par défaut ; --json donne la même chose en données. --task écrit aussi .arche/task à côté du modèle, { "part", "fingerprint", "files" } (fichiers relatifs au dossier du modèle), que lit archec guard ; --clear-task le supprime. L’outil MCP brief d’archec mcp fait la même chose. Code de sortie 1 quand le modèle a des erreurs ou ne nomme pas une telle part.
archec agent-context <main.arche> [-o CLAUDE.md|AGENTS.md] [--check] Le contexte du projet pour un assistant IA, tiré du modèle seul : l’architecture (les parts de chaque système, sur trois niveaux, avec leur rôle et leur source), les dépendances autorisées (les liens de chaque bloc, et ses weak_links), où va le code écrit à la main (les fichiers propres d’une part ; dans le code généré, seulement entre les marqueurs USER CODE), et les conventions (archec brief … --task avant de modifier une part, l’exigence et le test d’abord, archec check et archec conform après chaque modification, l’approbation d’un élément approuvé se périme quand il change, expliquer chaque morceau d’un diff), avec une empreinte. C’est écrit entre deux marqueurs, <!-- archec agent-context: begin --> et <!-- archec agent-context: end --> : le texte autour est à vous et il est gardé ; sans marqueurs, le bloc va après votre texte. Sans -o, il est affiché. --check : code de sortie 1 quand le bloc du fichier n’est pas ce que dit maintenant le modèle. archec ci la lance comme étape agent-context sur le CLAUDE.md et l’AGENTS.md à côté du modèle.