Guides pratiques › Comprendre du code existant

Guides pratiques

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 provenance indique qui a écrit chaque ligne ;
  • archec observe indique ce que fait le code, à partir de ses traces ;
  • archec recover indique quelle est son architecture, à partir de ses imports, et archec conform garde 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 gen l’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: ou AI-assisted: ;
    • le commit porte l’adresse d’un assistant ;
    • un marqueur dans .arche/provenance.jsonl l’indique.
  • 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 source ou code, 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 file du 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 une loop.
// 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 deadline d’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 } lie b ;
  • import x.y lie x.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 std de Rust) est laissée de côté, car toutes les parts y seraient liées. --std la 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"
  …
}
Diagramme : arche-lang
Ce qu’archec dessine depuis ce code : arche-lang

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 N fixe le seuil dans tous les blocs ; --min-imports 1 dessine 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 diagram dessine 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 recovered marque un modèle comme reconstitué. --max-links N fixe ce nombre pour tout modèle dont les liens donnent leur poids (« 12 imports »). --max-links 0 dessine 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 gitnexus ajoute 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.