Aller au contenu

ADR 0004 — schema.js comme source de vérité

Contexte

La machine d'états du kit (méta-états, statuts par type, transitions, portes, préconditions, invariants, checks) doit être encodée quelque part. Ce « quelque part » devient la source de vérité — le lieu que la CLI lit, que la doc reflète, qu'un audit inspecte.

Le risque majeur : la divergence. Si la doc décrit une porte P5 avec telles préconditions, mais que le code de la CLI encode des préconditions différentes, on a un bug silencieux avec des conséquences longues.

Options envisagées

  1. Markdown structuré (SDLC.md avec tableaux canoniques parsés par la CLI).
  2. YAML (schema.yaml lu par la CLI, rendu en tableaux dans la doc).
  3. JSON Schema (schema.json avec validation externe).
  4. JavaScript (schema.js — un module Node exportant META, TYPES, STATES, TRANSITIONS).

Décision

Retenu : JavaScript (sdlc/schema.js).

Le fichier exporte quatre objets structurés :

  • META — les cinq méta-états (NOT_STARTED, IN_PROGRESS, BLOCKED, DONE, ARCHIVED) avec leur heat.
  • TYPES — les trois types d'objets (be, fe, us) avec leur label.
  • STATES — pour chaque type, la liste des statuts possibles avec leur méta-état associé.
  • TRANSITIONS — pour chaque type, chaque couple from → to, l'objet de porte (gate, preconditions, invariants, checks, freeze).

La CLI, l'evaluator, et les générateurs de doc importent directement ce module.

Conséquences

Positives :

  • Pas de divergence possible : la doc (générée par tools/docs/gen-portes.js) vient du même fichier que le code de la CLI.
  • Expressivité : les checks sont des fonctions JS. Elles peuvent lire le filesystem, faire des regex, accéder au registre. Un YAML ne permet pas cela.
  • Lisibilité : malgré le choix de JS, le fichier reste déclaratif à 95% (objets littéraux). Seuls les checks sont du code.
  • Testable : on peut écrire des tests unitaires sur chaque transition, chaque check, chaque invariant.

Négatives :

  • Un non-dev peut être intimidé par le fichier. Mitigé par le fait que 95% de son contenu reste déclaratif.
  • Le parsing pour les générateurs de doc exige un import Node, pas un simple parse de markdown.

Neutres :

  • Les projets qui préféreraient YAML peuvent maintenir une copie YAML générée depuis schema.js. La vérité reste le JS.

Règle dérivée

Toute modification de la machine d'états passe par schema.js en premier. La doc est régénérée dans la foulée (npm run docs:gen). Ne jamais modifier un fichier docs/portes/p*.md directement — il serait écrasé au prochain build.

Références