ADR-024 — Workflow de gestion des dépendances

Statut : Accepté. Document fondateur de la phase 0.

Catégorie : Méthode (gouvernance technique).

Contexte

Le Principe d’ingénierie 6 d’Air énonce la “règle des 80 %” : si moins de 80 % du code d’une crate de dépendance est effectivement utilisé par Air, la dépendance est refusée et le code nécessaire est intégré (vendoré partiellement) au lieu d’être consommé comme dépendance externe.

Cette règle est claire dans son intention mais demande un workflow opérationnel pour être appliquée systématiquement. Sans processus explicite, les contributions vont naturellement vers la solution facile (ajouter une dépendance) plutôt que vers l’évaluation rigoureuse de chaque ajout.

Décision

Air met en place un workflow explicite de gestion des dépendances qui opérationnalise le Principe 6. Le workflow comprend trois éléments :

1. Un format standardisé de documentation des dépendances (DEPENDENCIES.md).
2. Un format de documentation des exceptions (EXCEPTIONS.md).
3. Un processus d’ajout encadré par revue.
4. Un audit régulier en fin de phase.

Format DEPENDENCIES.md par crate

Chaque crate Air contient à sa racine un fichier DEPENDENCIES.md qui liste exhaustivement ses dépendances directes. Chaque entrée documente :

• Nom et version (avec range de compatibilité).
• Objectif fonctionnel.
• Pourcentage estimé d’API utilisée.
• Justification de l’inclusion.
• Coût estimé de désengagement (faible, moyen, élevé, catastrophique).
• Statut d’audit (date de dernière revue, identité du reviewer).
• Statut éventuel (temporaire, en cours de désengagement, etc.).

Exemple :

# Dependencies of air-sys-syscall

## Direct dependencies

### bitflags

- **Version:** 2.4 (range: 2.4, <3.0)
- **Purpose:** Macro to define type-safe bitmask types (CloneFlags, OpenFlags, etc.).
- **API usage estimated:** 100% (the `bitflags!` macro is used as-is for ~15 types).
- **Justification:** Defining bitmask types manually involves ~150 lines of boilerplate per type. The macro generates equivalent code that follows Rust conventions and is well-tested.
- **Disengagement cost:** Low (2-3 days). Each `bitflags!` invocation expands to deterministic Rust code that can be written manually.
- **Audit status:** Reviewed 2026-01-15 by [reviewer]. No security or licensing concerns.
- **Last reviewed:** 2026-01-15

Le format est standardisé pour permettre l’agrégation et l’analyse à l’échelle du workspace.

Format EXCEPTIONS.md au workspace

Un fichier EXCEPTIONS.md à la racine du workspace Air liste les dépendances qui bénéficient d’une exception explicite à la règle des 80 %. Chaque exception documente :

• Le nom de la dépendance.
• L’usage estimé (qui ne respecte pas le seuil).
• La justification détaillée de l’exception.
• L’autorité qui a approuvé (avec date).
• La fréquence de révision prévue.

Exemple :

# Dependency exceptions to the 80% rule

## icu4x (cf. ADR-016)

- **API usage:** Variable (~30-50% across Air components).
- **Exception justification:** icu4x is the worldwide reference implementation
  for Unicode and internationalization. Reproducing it would be a multi-year
  project with high risk of subtle bugs in character handling. The cost of
  inclusion (even partial) is outweighed by the benefits of correct
  internationalization from day one.
- **Approved by:** [Founder], 2026-01-15.
- **Review frequency:** End of every major phase.

Les exceptions sont rares et délibérées. La première exception inscrite est icu4x (cf. ADR-016).

Processus d’ajout d’une dépendance

Toute nouvelle dépendance dans un PR doit faire l’objet d’une analyse explicite documentée dans la description du PR. L’analyse comprend :

1. Le besoin fonctionnel précis.
2. Les alternatives évaluées (autres crates, implémentation maison, fonctionnalité standard).
3. L’estimation du pourcentage d’API utilisée.
4. L’estimation du coût de désengagement.
5. Une entrée correspondante dans DEPENDENCIES.md du PR.
6. Si exception nécessaire, une entrée dans EXCEPTIONS.md également.

Le mainteneur qui revoit le PR valide la nécessité, la justification, et les estimations. Une dépendance ne peut pas être ajoutée sans cette analyse.

Audit en fin de phase

À chaque fin de phase majeure (phase 0, phase 1, etc.), un audit complet des dépendances est conduit. L’audit consiste à :

1. Revoir chaque entrée DEPENDENCIES.md de chaque crate.
2. Vérifier que l’usage estimé reste cohérent avec l’usage réel (mesurable via les outils Rust).
3. Vérifier les mises à jour disponibles et les vulnérabilités annoncées (cargo audit).
4. Réévaluer le coût de désengagement.
5. Pour les dépendances temporaires (statut explicite), décider de la migration ou de la prolongation.
6. Pour les exceptions, vérifier que la justification reste valide.

L’audit produit un rapport public qui documente les décisions prises.

Outillage CI

Le pipeline CI Air intègre dès le démarrage :

• cargo audit à chaque PR pour détecter les vulnérabilités.
• cargo deny configuré pour appliquer les règles Air (licences acceptables, versions interdites, etc.).
• cargo machete pour détecter les dépendances déclarées mais non utilisées.
• Un script Air spécifique qui vérifie que chaque dépendance déclarée dans Cargo.toml a une entrée correspondante dans DEPENDENCIES.md. Un PR qui ajoute une dépendance sans entrée correspondante est rejeté en CI.

Échelle de coût de désengagement

Le coût de désengagement est estimé sur une échelle à quatre niveaux, documentée pour assurer la cohérence des estimations entre contributeurs :

Faible (jours) : la dépendance fournit une fonctionnalité bien définie qui pourrait être réimplémentée manuellement en moins d’une semaine de travail. Exemples typiques : macros utilitaires, helpers de bas niveau.

Moyen (semaines) : la dépendance fournit une fonctionnalité substantielle dont la réimplémentation prendrait plusieurs semaines mais reste accessible. Exemples typiques : crates de parsing, wrappers d’API système modérément complexes.

Élevé (mois) : la dépendance est structurelle, son remplacement représente plusieurs mois de travail d’un développeur expérimenté. Exemples typiques : crates de cryptographie, bibliothèques d’internationalisation.

Catastrophique (année+) : la dépendance est intégrée à un niveau si profond que son remplacement représenterait une refonte majeure du projet. Aucune dépendance Air ne devrait avoir ce niveau ; si une analyse identifie un coût catastrophique, c’est un signal d’alarme qui demande une revue architecturale.

Conséquences

Le workflow ajoute du surcoût à chaque ajout de dépendance (rédaction de l’entrée DEPENDENCIES.md, analyse formelle). Ce surcoût est intentionnel : il décourage les ajouts de dépendances réflexes et force une réflexion proportionnée à l’engagement de long terme que représente une dépendance.

Le bénéfice est triple : la qualité du stack technique reste maîtrisée sur la durée, les contributeurs comprennent les engagements pris, et les audits de fin de phase ont une base documentaire structurée.

Statut futur

ADR immuable dans ses principes. Les détails de format (DEPENDENCIES.md, EXCEPTIONS.md) peuvent évoluer par convention sans amendement ADR, tant que les principes de transparence, justification, et révision périodique sont préservés.

Licence du document : MPL 2.0 Statut : Document fondateur immuable.