Comprendre le code : qui l’a écrit, ce qu’il fait, quelle est son architecture
Cette page traite du code qui existe déjà. Il a pu être écrit par des personnes,
par archec gen ou par un assistant d’IA. archec le lit de trois façons :
archec provenanceindique qui a écrit chaque ligne ;archec observeindique ce que fait le code, à partir de ses traces ;archec recoverindique quelle est son architecture, à partir de ses imports, etarchec conformgarde le code fidèle à cette architecture.
Un premier aperçu#
Trois fichiers TypeScript : src/main.ts importe src/core/engine.ts, qui
importe src/util/log.ts.
archec recover src -o recovered.arche
✓ recovered.arche — 3 files, 3 parts, 0 outside packages, 2 links, 0 cycle(s), 0 unresolved import(s)
recovered.arche contient une part par dossier, et un lien par import entre ces
dossiers :
system Src "src" {
prop recovered = "archec recover src"
part main: Main
part core: Core
part util: Util
core.uses -> util.api "1 import"
main.uses -> core.api "1 import"
}
archec conform vérifie que le code correspond toujours à ce modèle :
archec conform recovered.arche
Src: 3 of 3 files mapped; 2 link(s) converge, 0 import(s) diverge, 0 link(s) absent
✓ every dependency of the code is in the model
Supprimez la ligne core.uses -> util.api et relancez. L’import de engine.ts
n’a plus de lien dans le modèle : la commande échoue avec le code de sortie 1.
Divergences: imports the model has no link for (1, between 1 pair(s) of parts)
error Src.core → Src.util: 1 import(s)
src/core/engine.ts:1 imports '../util/log' (Src.util)
Src: 3 of 3 files mapped; 1 link(s) converge, 1 import(s) diverge, 0 link(s) absent
✗ the code does what the model does not say
Qui a écrit le code : le modèle, un assistant d’IA ou une personne#
Quand une IA écrit du code, le relecteur doit savoir qui a écrit quoi.
archec provenance main.arche (ou archec audit main.arche --authors) attribue
une origine à chaque ligne de code :
- generated :
archec genl’a écrite, et elle n’a pas changé. gen laisse un.archegen.jsonà côté de ce qu’il produit, avec une empreinte par ligne. - AI : un assistant d’IA l’a écrite. archec le sait par l’un de ces moyens :
- le commit porte un trailer
Co-Authored-By: Claude…,Generated-by:ouAI-assisted:; - le commit porte l’adresse d’un assistant ;
- un marqueur dans
.arche/provenance.jsonll’indique.
- le commit porte un trailer
- edited after gen : gen a écrit le fichier, puis une personne a modifié la ligne.
- human : tout le reste.
La commande lit git blame : chaque ligne compte pour le commit qui l’a modifiée
en dernier.
Ce qu’elle rapporte :
- les lignes, totalisées par fichier et par part du modèle. Les fichiers d’une
part sont ceux qu’elle nomme avec
sourceoucode, plus ceux de ses parts. - les fichiers écrits par un assistant et sur lesquels aucune personne n’a commité depuis.
archec diagram main.arche Car --overlay provenance colore chaque bloc selon
l’auteur de la plus grande partie de son code. archec doc --html --provenance
ajoute les tableaux à la spécification.
Pour Claude Code, ajoutez ce hook à .claude/settings.json. Il marque les lignes
que Claude écrit, au moment où il les écrit.
{ "hooks": { "PostToolUse": [ { "matcher": "Edit|MultiEdit|Write",
"hooks": [ { "type": "command", "command": "archec provenance hook" } ] } ] } }
Les autres assistants peuvent appeler
archec provenance mark <file> --lines 10-40 --tool <name>.
Voir les commandes.
archec debt main.arche va un pas plus loin : pour chaque partie, la part des
lignes écrites par un assistant que personne n’a validées
(archec approve <Part> --code), ou qui sont dans une fonction à laquelle aucune
exigence ne mène, et combien de personnes connaissent la partie. Voir
la dette de compréhension.
Le comportement d’après les traces : ce que fait vraiment le code#
Le code écrit vite, ou par une IA, fait des choses que personne n’a consignées.
archec observe lit ce que le code a fait et l’écrit sous forme de modèle, à lire
et à dessiner.
La commande lit :
- les traces OpenTelemetry, au format OTLP JSON. C’est ce qu’écrit l’exporteur
filedu SDK ou du collecteur. - un export Jaeger ou Zipkin.
cd test/fixtures/observe
archec observe shop.otlp.jsonl --states -o observed.arche
archec diagram observed.arche post-checkout-error # a sequence diagram
archec diagram observed.arche Observed.orders.states # a state diagram
Ce que contient le modèle :
- Chaque service est une part.
- Chaque appel d’un service vers un autre est un message sur un lien. Le lien indique combien d’appels ont été vus, leur durée (p50, p95) et combien ont échoué.
- Une base de données ou un cache appelé, mais sans trace propre, est aussi une part.
- Les traces sont regroupées selon le chemin qu’elles ont suivi : un scénario par forme, avec sa fréquence.
- Les appels qui se chevauchent sont dessinés dans un
par. Un même appel répété à la suite est dessiné dans uneloop.
// observed: 9 of 64 trace(s) went this way (14%)
scenario post-checkout-error "POST /checkout (payment declined)" {
sequence post-checkout-error-steps "POST /checkout (payment declined)" {
Observed.outside -> Observed.gateway : POST_CHECKOUT
Observed.gateway -> Observed.orders : POST_ORDERS
Observed.orders -> Observed.orders : validate_cart
par {
when "RESERVE" { … }
when "CHARGE" {
Observed.orders -> Observed.payments : CHARGE
Observed.payments -> Observed.orders : CHARGE "error: card declined" { reply }
}
}
Observed.orders -> Observed.inventory : RELEASE
…
--states ajoute une machine à états à chaque service qui en attend un autre.
Ses états sont les réponses qu’il attend. Un commentaire indique dans combien de
traces chaque transition a été prise :
// observed: in 9 of 64 trace(s)
AwaitingCharge -> AwaitingRelease on CHARGE when "the reply is an error" / "sends RELEASE"
Avec --model main.arche, la commande compare plutôt les traces à votre modèle.
Elle signale :
- les services qui ne sont pas une part du modèle ;
- les appels pour lesquels le modèle n’a ni lien ni message ;
- les liens jamais vus ;
- la
deadlined’un lien, comparée au temps mesuré sur le fil ; - les vérifications d’
archec replay.
archec replay lit les mêmes traces. Voir les commandes.
Du code au modèle#
Le reste d’arche-lang va du modèle vers le code. archec recover fait le chemin
inverse. Il sert pour le code que personne n’a dessiné, écrit au fil des années
ou par une IA en un après-midi :
archec recover src -o recovered.arche # TypeScript, JavaScript, Go, Python, C/C++, Rust
archec diagram recovered.arche --md # see it
Comment il lit le code#
Il lit les imports de chaque fichier avec un petit analyseur par langage. Il n’a
besoin d’aucun compilateur ni de rien d’installé. Il lit aussi ce que le fichier
fait de chaque nom importé : combien de fois il l’utilise, et comment. Une
utilisation est un appel, un new X (un littéral de struct en Go et en Rust), un
type, ou une autre valeur.
Chaque import reçoit un poids :
- un import très utilisé pèse plus : environ 1 + log₂ de ses utilisations ;
- un import qui ne prend que des types pèse moitié moins ;
- une réexportation (
export … from) pèse ½ ; - un import jamais utilisé pèse de ¼ à ½.
TypeScript et JavaScript sont lus avec l’analyseur du compilateur TypeScript quand
il est disponible (celui d’archec, ou celui du node_modules du dossier de
travail). Sinon, ils sont lus de façon lexicale, comme les autres langages. La
lecture lexicale saute les chaînes et les commentaires du fichier, et fait
correspondre les noms restants avec ce que lie chaque import :
import { a as b }lieb;import x.yliex.y;- en Go, le nom du paquet est utilisé sous la forme
pkg.Name; - un en-tête C lie ce qu’il déclare.
En Go, les fichiers d’un même paquet s’utilisent les uns les autres sans aucun import. Quand un fichier utilise un nom déclaré par un autre fichier de son paquet, il y a une référence entre les deux fichiers. Une référence est pesée de la même façon qu’un import.
Comment il regroupe les fichiers en parts#
- Il fait une part de chaque dossier.
- Il découpe en groupes un dossier qui contient beaucoup de fichiers. Viennent
d’abord les familles de noms qui s’importent entre eux (
websim*,parser*). Les autres fichiers sont regroupés selon leur couplage, avec les poids ci-dessus. Un fichier importé par beaucoup d’autres pèse moins dans le choix de leur place. Chaque groupe porte le nom de son radical, ou celui du fichier que les autres importent le plus. - Il écrit un lien par paire de parts, avec le nombre d’imports (et de références).
- Un fichier importé par beaucoup d’autres, et qui importe au plus deux fichiers
de son dossier, est une bibliothèque. Il est mis à part, sous le nom
common. - Un fichier importé par beaucoup d’autres et qui importe lui-même beaucoup (le centre d’un programme) est placé selon son couplage, comme les autres.
- Un fichier situé à côté de dossiers, utilisé par l’un d’eux et qui a la plupart
de ses liens avec lui, rejoint la part de ce dossier. Un commentaire
// recovered:indique lequel. - Parmi des parts sœurs, l’une peut être utilisée par les deux tiers des autres,
tout en les utilisant quatre fois moins, voire moins encore. Elle est écrite
kind library. Ce qu’elle importe en retour est noté sur elle et exclu des cycles. Ainsi, un cycle montre le nœud de la conception, et non un utilitaire importé en retour. - Les cycles sont rompus à leurs liens les plus légers, selon le poids. Un import de types seuls passe en premier.
- La bibliothèque standard (les modules propres à Node, ceux de Python, de Go, la
libc, le
stdde Rust) est laissée de côté, car toutes les parts y seraient liées.--stdla conserve.
Chaque part liste ses fichiers avec source. Les noms que les autres importent
depuis elle sont ses fonctions. Ce qu’archec a dû deviner figure dans un
commentaire // recovered: :
/// 14 files, 3 996 lines.
component Importer "importer" {
kind module
source "src/importer/**"
in api: call
out uses: call
fn import_project "importProject"
fn import_sysml "importSysml"
…
/// 4 files, 1 182 lines.
component sysml "importer/sysml*" {
kind module
source "src/importer/sysml.ts"
…
}
sysml.uses -> ir.api "8 imports"
}
system ArcheLang "arche-lang" {
prop recovered = "archec recover src"
…
// recovered: a cycle: 25 parts import one another; 53 light links break it (archec recover --json lists them). To shrink it first, cut:
// recovered: what common imports from generics, libraries, parser (+2) (11 imports, src/program.ts:18…): 22 parts left in a cycle
// recovered: 107 weak links (fewer than 3 imports) not drawn: weak_links lists them, archec conform allows them (--min-imports 1 draws all)
prop weak_links = [
"board -> gen: 1 import",
…
]
cli.uses -> importer.api "8 imports"
…
}Liens faibles et cycles#
- Dans un bloc de plus de 12 liens, seuls les liens d’au moins 3 imports sont
gardés comme liens. Les plus faibles sont listés dans
prop weak_links: rien n’est perdu.--min-imports Nfixe le seuil dans tous les blocs ;--min-imports 1dessine tous les liens. - Un cycle est décrit par les liens légers qui le rompent, chacun avec le fichier et la ligne d’un import. (C’est un ensemble d’arcs de rétroaction, pondéré par les imports.) Pour un grand cycle, archec indique quoi couper en premier.
archec diagramdessine au plus les 30 liens les plus lourds de chaque bloc d’un modèle reconstitué, du plus lourd au plus léger, et indique combien il en a laissé de côté.prop recoveredmarque un modèle comme reconstitué.--max-links Nfixe ce nombre pour tout modèle dont les liens donnent leur poids (« 12 imports »).--max-links 0dessine tout.
archec recover --json donne pour chaque lien ses imports, ses références, son
poids et ses utilisations.
Pour mesurer à quel point le regroupement s’approche d’un modèle dessiné à la
main, lancez node tools/recover-score.mjs. Le script compare
archec recover src au modèle d’arche-lang lui-même (examples/arche-lang). Il
compte les paires de fichiers que les deux placent ensemble, en précision et en
rappel.
Garder le code fidèle au modèle#
Renommez les parts, regroupez-les et supprimez les liens dont vous ne voulez pas.
Le résultat est désormais l’architecture que vous voulez. archec conform veille
à ce qu’elle reste vraie. Il suit le modèle de réflexion (reflexion model) :
- chaque import du code entre deux parts doit être un lien du modèle. Sinon, c’est une erreur, signalée au fichier et à la ligne de l’import.
- chaque lien devrait avoir des imports qui le justifient. Sinon, c’est un avertissement.
- chaque fichier devrait appartenir à une part.
Une paire de parts listée dans weak_links est autorisée. Ses imports sont
comptés à part : ce ne sont ni des convergences ni des divergences. Supprimez la
ligne pour les interdire.
Divergences: imports the model has no link for (1, between 1 pair(s) of parts)
error Code.core → Code.util: 1 import(s)
src/core/engine.ts:1 imports '../util/log' (Code.util)
Code: 5 of 5 files mapped; 4 link(s) converge, 1 import(s) diverge, 0 link(s) absent
✗ the code does what the model does not say
archec ci l’exécute comme un contrôle bloquant, dès qu’un source nomme un
fichier du code.
archec arch-diff src main..HEAD --md reconstitue deux révisions depuis git. Pour
la pull request, il écrit :
- les parts et les liens que la branche a ajoutés ou supprimés ;
- les fichiers qu’elle a déplacés d’une part à une autre ;
- avec
--model, les divergences qu’elle a introduites.
La seconde révision est regroupée comme l’a été la première. Un dossier passé à plus de 12 fichiers est découpé en groupes, ou gardé entier, comme avant. Il apparaît sous Folders plutôt que comme des fichiers déplacés.
Limites#
- Ce sont les imports qui sont lus, pas les types ni les appels.
--graph gitnexusajoute les appels tirés d’un index GitNexus. - Un import dont le nom est calculé est seulement signalé.
- Le regroupement est une première proposition, pas une conception.