Adopter sur un projet existant

Le reste de cette documentation s'adresse aux projets qui n'existent pas encore. Celle-ci s'adresse aux autres, qui sont la majorité : personne n'adopte une architecture en repartant de zéro.

Savoir ce que ça coûte, avant de décider

npx maedow-arch check

La commande ne modifie rien, n'installe rien, et n'a besoin ni des node_modules ni d'un projet qui compile. C'est délibéré : un audit qu'il faudrait préparer ne serait jamais lancé par l'équipe qui hésite encore, c'est-à-dire par la seule à qui il s'adresse.

Elle lit votre code et rend un rapport par règle du registre.

Ce que l'audit examine, et ce qu'il laisse de côté

L'en-tête du rapport le dit avant tout le reste :

  37 fichiers lus, 32 dans une couche du standard
  5 hors des couches, non examinés (scripts, configuration, actifs)

Seuls les fichiers appartenant à une couche du standard sont examinés. Un fichier qui ne vit ni dans app/, ni dans features/, ni dans core/, ni dans components/, ni dans lib/ n'est pas du code Maedow Arch : vos scripts de build, vos tests de bout en bout, vos fichiers de configuration et ce que vos outils déposent dans public/ ne reçoivent aucun reproche.

C'est une liste blanche, et le choix est délibéré. Une liste d'exclusions laisserait passer par défaut et ne pourrait être complète qu'après coup : elle signalerait le prochain dossier que personne n'avait prévu. La liste blanche, elle, ne se périme pas, puisque c'est celle que le corpus énonce.

Le second chiffre est un renseignement, pas un reproche. Sur un projet en migration, savoir combien de fichiers vivent hors des couches vous dit où en est le découpage, et cela n'a rien à voir avec une dette à corriger.

Ce que la migration coûte, et ce qu'on ne peut pas vous dire

C'est la première question d'une équipe qui évalue, et elle n'a pas de réponse générale : le coût dépend de ce que l'audit trouve chez vous, pas de la taille du projet. Ce qu'on peut dire, c'est quelle part se corrige mécaniquement et quelle part demande une décision.

Les trois règles de frontière sont les seules qui ne se corrigent pas en série. Une violation vous dit qu'un fichier est au mauvais endroit ; elle ne dit pas où il doit aller, et cette décision-là ne se délègue ni à un outil ni à un stagiaire.

Le premier geste utile est de lancer l'audit et de lire le total, pas cette page. Il chiffre votre dette réelle en quelques secondes, sans rien installer :

npx maedow-arch check --json > audit.json

Un projet qui rend beaucoup de TS-STRICT et peu de frontières s'adapte en quelques jours. Un projet qui range tout dans app/ n'a pas une dette à corriger : il a un découpage à concevoir, et c'est un autre travail.

Ce que nous n'avons pas. Aucun retour public de migration complète chiffrée à ce jour. Le standard a été éprouvé sur dix-neuf lots d'un projet réel construit avec lui depuis le départ, ce qui valide les règles mais ne dit rien du coût d'une reprise d'existant. Si vous conduisez cette migration, le dépôt est l'endroit où le dire, et ce serait le premier.

Lire le rapport

Il est ordonné par ce qui débloque le reste, jamais par gravité, et chaque section dit ce que la correction rend possible.

  1. Activer le typage strict  ·  TS-STRICT  ·  2 violations
     Sans strict, les couches basses ne peuvent pas garantir ce qu'elles
     annoncent, et les corrections suivantes reposeraient sur des types
     qui mentent.

       tsconfig.json
         noUncheckedIndexedAccess absent ou faux

Un projet qui découvre deux cents violations doit voir un chemin, pas un verdict. Le total n'apparaît qu'à la fin, une fois que vous savez par où commencer.

L'ordre de migration, et sa raison

Si le rapport ne signale aucune frontière

Il vous le dira explicitement :

  Ce projet n'a pas de features ni de core. Les règles de frontière
  n'ont donc rien pu vérifier : leur silence ci-dessus ne dit pas
  qu'elles sont respectées, mais qu'il n'y avait rien à examiner.

C'est le cas le plus fréquent sur un projet qui range tout dans app/ et components/. Le découpage en couches est alors le premier geste, avant tout le reste.

Si le rapport ne signale rien sur le typage

TS-STRICT ne juge que ce qu'il a lu. Sans tsconfig.json, il ne compte rien, et distingue deux situations qui n'ont pas le même sens :

  Aucun tsconfig.json, et aucun fichier TypeScript : TS-STRICT ne
  s'applique pas à ce projet. Son silence ci-dessus ne dit pas que le
  typage est strict, mais qu'il n'y avait rien à examiner.

  Aucun tsconfig.json n'a été trouvé, alors que ce projet contient du
  TypeScript. TS-STRICT n'a donc rien pu vérifier, et c'est un problème
  en soi : sans fichier de configuration, rien ne garantit sous quelles
  options ce code est compilé.

Le second cas se corrige avant tout le reste : tant qu'aucun fichier ne dit sous quelles options ce code est compilé, aucune des corrections suivantes ne repose sur du solide.

Mesurer une progression, pas rougir un pipeline

npx maedow-arch check --seuil 50

Sans seuil, la commande réussit toujours. Avec un seuil, elle échoue au-delà. Une équipe en migration a besoin de voir sa dette baisser, pas d'un pipeline rouge au premier jour : posez le seuil au-dessus de votre compte actuel, puis descendez-le à mesure que vous corrigez.

npx maedow-arch check --json > audit.json

La sortie machine porte le total, l'ordre de migration et le détail par code, de quoi tracer une courbe dans votre intégration continue.

Découvrir avec npx, suivre avec une dépendance

Les deux commandes ci-dessus ne s'emploient pas dans le même contexte, et l'outil ne s'installe pas de la même façon selon le cas.

Pour découvrir ce que l'adoption coûterait, npx est le bon geste : rien à installer, rien à décider, et c'est précisément l'intérêt sur un projet qu'on hésite encore à migrer.

Pour suivre une migration lot après lot, épinglez-le :

npm install --save-dev maedow-arch

npx peut réutiliser une version mise en cache. Deux postes rendent alors deux rapports différents sur le même code, sans que rien n'explique l'écart, et c'est exactement ce qu'il ne faut pas quand le compte sert à mesurer une progression. Une dépendance épinglée fige la version pour toute l'équipe et pour l'intégration continue.

Ce que --fix corrige, et ce qu'il ne touche pas

npx maedow-arch check --fix

Il ajoute les options manquantes du tsconfig.json, en préservant vos commentaires. Rien d'autre.

Les déplacements de fichiers sont proposés, jamais appliqués : un outil qui déplace du code sans qu'on le lui demande ne se fait pardonner qu'une fois. Et les violations de frontière ne se corrigent pas mécaniquement, chacune demandant de décider où va le code, ce qu'un outil ne sait pas faire à votre place.

Ce que l'audit ne fait pas

Il dénombre, il ne garantit pas. Il lit les chemins d'import sans compiler le projet, ce qui lui permet de tourner sur une cible non installée qui ne compile pas encore. Le prix est quelques cas limites, et il est assumé.

Une fois la migration faite, c'est eslint-config-maedow-arch qui tient les frontières, à chaque commit :

npm install --save-dev eslint-config-maedow-arch eslint-plugin-boundaries eslint-plugin-import-x eslint-import-resolver-typescript

// eslint.config.mjs
import maedowArch from "eslint-config-maedow-arch";
export default [...maedowArch];

L'entrée par défaut porte les règles de frontière. Quand elles passent, l'entrée strict ajoute la discipline de typage :

import maedowArch from "eslint-config-maedow-arch";
import maedowArchStrict from "eslint-config-maedow-arch/strict";
export default [...maedowArch, ...maedowArchStrict];

L'ordre compte : adopter les deux d'un coup sur une base existante remonte tout en même temps, et c'est le meilleur moyen de tout désactiver le vendredi suivant.

Se dire conforme

Le registre définit les quatre conditions qu'un projet doit satisfaire, et ce qui constitue une rupture du standard. check en mesure deux : il ne décerne pas la conformité, il dit ce qui vous en sépare.

Ce qui aide vraiment ce standard

Les frictions rencontrées pendant une migration réelle. Une règle trop stricte, un cas limite qu'elle n'avait pas prévu, un rapport qui compte mal : ces retours passent par les issues du dépôt et alimentent FRICTIONS.md, le journal de ce qui a résisté en conditions réelles.