Architecture

Ce chapitre s’adresse aux contributeurs : comment le code est organisé, et pourquoi. Les décisions qui le sous-tendent, avec leur contexte et les alternatives envisagées, sont consignées sous forme d’ADR dans _codev/decisions/ — codev est développé avec codev. Ce chapitre les résume et les relie entre elles.

Un cœur pur, une coquille impérative

codev suit un principe : décider n’est pas exécuter.

• Tout ce qui est pur vit dans codev-core : le modèle du domaine, les schémas, le graphe des artefacts, les analyseurs, les règles de validation, la fusion et le calcul des plans. Ni std::fs, ni std::env, ni horloge, ni réseau.
• Tout ce qui a besoin du monde extérieur vit au-dessus, derrière un port.

La règle de dépendance n’est pas une convention de dossiers : c’est le graphe des crates, et Cargo refuse de compiler un cycle. Le compilateur la fait respecter, sans interfaces de façade ni conteneur d’injection de dépendances.

Le graphe des crates

codev-cli ──▶ codev-agents ──▶ codev-engine ──▶ codev-core
    │                               ▲                ▲
    ├───────────────────────────────┘                │
    └────────────────────────────────────────────────┘

codev-agents dépend aussi de codev-core, et codev-cli de toutes les crates.

Un module ne devient une crate que lorsqu’il l’a mérité — une frontière de test nette, ou un consommateur externe. Découper plus tôt ne produit que des refactorisations inutiles.

Des plans, pas des effets de bord

Le cœur ne touche jamais au disque. Il renvoie un plan d’effets — fichiers à créer ou à écraser, fichiers à supprimer, dossiers à déplacer — que la coquille exécute. init, new change, sync, archive, l’installation des skills et les commandes de décision fonctionnent tous ainsi.

On y gagne plusieurs choses à la fois : le plan complet est validé avant la première écriture, les fusions se testent sans fichiers temporaires, et les exécutions à blanc ou les aperçus viennent sans effort supplémentaire.

Les ports

Il existe quatre ports, réservés aux effets :

Ce que codev s’interdit : pas de trait de dépôt masquant std::fs, pas de structures *UseCase à méthode unique, pas d’Arc<dyn Trait> par défaut. Les traits servent les frontières réellement ouvertes (AgentTarget, Rule), les génériques servent le reste, et les enums modélisent les ensembles fermés.

Les deux risques dont l’architecture protège

1. Une réécriture destructrice du Markdown. Un delta MODIFIED qui reformate le fichier ou perd du contenu qu’il ne mentionne pas. Les analyseurs conservent donc les plages d’octets d’origine de chaque bloc, afin que la fusion réécrive un bloc sans toucher au reste.
2. La dérive du contrat JSON. La sortie JSON est une API publique, consommée par des skills déjà installées sur les machines des utilisateurs. Les types du domaine ne dérivent donc pas Serialize : codev-cli dispose d’un module contract dédié, dont les types traduisent le domaine, avec des tests qui figent les noms des champs. C’est la seule frontière DTO du projet, et elle a une raison d’être.

Points d’extension

1. AgentTarget — une implémentation par outil d’agent. Claude Code aujourd’hui ; un autre outil peut être ajouté sans toucher au cœur.
2. Rule — une règle de validation par implémentation, enregistrée dans une liste.
3. Schémas, templates et workflows sous forme de données — schema.yaml, les templates et le corps des skills vivent dans assets/ et sont embarqués à la compilation. Améliorer une instruction ne demande jamais de toucher au code Rust.

Où se trouvent les choses

Décisions d’architecture

Conventions de code

• Erreurs. thiserror et des erreurs typées dans les crates de bibliothèque ; anyhow uniquement dans codev-cli, où les erreurs sont traduites dans le tableau status du contrat JSON.
• Commentaires. Ils sont rédigés en anglais et expliquent le pourquoi. Un commentaire qui paraphrase le code n’est que du bruit.
• Tests. Le cœur est testé par des tests unitaires purs ; le moteur, avec un FileSystem en mémoire et des Clock et Env figés ; le contrat JSON, par des tests sur les noms et la forme de ses champs.