@mostajs/kind-catalog 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 **Auteur** : Dr Hamid MADANI <drmdh@msn.com>
 
+## 0.2.0 — 2026-09-03
+
+### Ajouté — `enrichir()` : projeter pour CRÉER, enrichir pour EXPLOITER
+
+Le passage à qatrax a rendu visible une faute de modèle, et le critère qui la tranche :
+
+> **Dans le RÉFÉRENTIEL, une même règle deux fois est une duplication. Dans une APPLICATION, la
+> même règle appliquée à un objet précis est une OCCURRENCE d'exploitation — et il en faut autant
+> qu'il y a d'objets.**
+
+`toDevtest` projetait la règle **générique** dans le plan de l'application : ni référentiel, ni
+occurrence — **la règle recopiée**. ATC portait déjà **quatre** occurrences du périmètre (le
+portail, le coaching, l'e-learning, le cumul de rôles) et recevait une cinquième exigence qui ne
+parlait de rien. RestoTrax de même, avec `PIL-10` à `PIL-13`.
+
+```js
+enrichir(plan, { kind, specRefs: ['SPEC-POR-01', 'SPEC-COA-01', 'SPEC-ELE-01', 'SPEC-ROL-02'] })
+```
+
+Les erreurs connues de la fiche descendent dans les exigences **que l'application a déjà**.
+**Aucune exigence, aucun essai n'est ajouté** — ce qui referme *par construction* le défaut que
+qatrax avait signalé : des cas de plan que rien ne peut exécuter, parce qu'ils prétendaient qu'un
+essai portant un autre nom les couvrait.
+
+`toDevtest` garde son emploi : une application **neuve**, sans aucune exigence, à qui la fiche
+donne les siennes.
+
+**Rejouable** (`T-KC-14`) : le bloc est borné par un marqueur et se remplace au lieu de s'empiler —
+le script d'une application se relance à chaque montée du catalogue.
+
+**Refuse plutôt que de faire semblant** (`T-KC-15`) : une exigence introuvable — renommée, le plus
+souvent — est une erreur, pas un avertissement ; et enrichir sans rien désigner est refusé, parce
+que c'est ne rien faire tout en croyant l'avoir fait.
+
+`retirerProjection()` reprend ce qu'une projection avait posé, pour les applications qui basculent.
+
+27 essais.
+
 ## 0.1.1 — 2026-09-03
 
 ### Ajouté — `bind` : lier une épreuve à l'essai qui la couvre DÉJÀ

package/docs/DEVTEST-PLAN.kind-catalog.json

@@ -41,6 +41,12 @@
       "title": "Le corpus livré est valide, sourcé et lisible",
       "priority": "critical",
       "status": "verified"
+    },
+    {
+      "ref": "SPEC-KC-08",
+      "title": "ENRICHIR les occurrences existantes plutôt que RECOPIER la règle dans le plan de l'application",
+      "priority": "critical",
+      "status": "verified"
     }
   ],
   "realisations": [
@@ -97,6 +103,15 @@
       "artifact": "src/",
       "progress": 100,
       "status": "done"
+    },
+    {
+      "ref": "REL-KC-08",
+      "specRef": "SPEC-KC-08",
+      "kind": "feature",
+      "title": "enrichir() · retirerProjection()",
+      "artifact": "src/enrichir.js",
+      "progress": 100,
+      "status": "done"
     }
   ],
   "tests": [
@@ -421,6 +436,62 @@
           "expected": "la liée est `automated` avec son renvoi ; l'autre est `manual` sans renvoi — la déclarer automatisée prétendrait qu'un essai la couvre, et ouvrirait un trou dans la porte qualité de l'application"
         }
       ]
+    },
+    {
+      "ref": "T-KC-13",
+      "specRef": "SPEC-KC-08",
+      "type": "automated",
+      "priority": "critical",
+      "title": "T-KC-13 — enrichir dépose les erreurs dans les exigences EXISTANTES, sans rien ajouter",
+      "autoRef": "test-scripts/unit/catalogue.test.mjs::T-KC-13",
+      "steps": [
+        {
+          "action": "enrichir deux exigences d'un plan",
+          "expected": "les descriptions reçoivent les erreurs connues ; aucune exigence ni aucun essai n'est ajouté — c'est ce qui referme le défaut des cas que rien ne peut exécuter"
+        }
+      ]
+    },
+    {
+      "ref": "T-KC-14",
+      "specRef": "SPEC-KC-08",
+      "type": "automated",
+      "priority": "critical",
+      "title": "T-KC-14 — enrichir deux fois ne DOUBLE pas le bloc",
+      "autoRef": "test-scripts/unit/catalogue.test.mjs::T-KC-14",
+      "steps": [
+        {
+          "action": "rejouer l'enrichissement",
+          "expected": "description inchangée — le script d'une application se rejoue à chaque montée du catalogue"
+        }
+      ]
+    },
+    {
+      "ref": "T-KC-15",
+      "specRef": "SPEC-KC-08",
+      "type": "automated",
+      "priority": "critical",
+      "title": "T-KC-15 — enrichir REFUSE une exigence introuvable, et refuse de ne rien désigner",
+      "autoRef": "test-scripts/unit/catalogue.test.mjs::T-KC-15",
+      "steps": [
+        {
+          "action": "exigence renommée, puis liste vide",
+          "expected": "refus des deux — une exigence renommée ferait partir l'enrichissement dans le vide, en silence"
+        }
+      ]
+    },
+    {
+      "ref": "T-KC-16",
+      "specRef": "SPEC-KC-08",
+      "type": "automated",
+      "priority": "critical",
+      "title": "T-KC-16 — `retirerProjection` reprend ce qu'une projection avait posé",
+      "autoRef": "test-scripts/unit/catalogue.test.mjs::T-KC-16",
+      "steps": [
+        {
+          "action": "projeter puis retirer",
+          "expected": "les entrées projetées disparaissent, celles de l'application survivent"
+        }
+      ]
     }
   ]
 }

package/llms.txt

@@ -28,6 +28,10 @@ PIÈGES
   - Les fiches sont des FICHIERS VERSIONNES (kinds/*.kind.mjs). Ce qui va en base, c'est l'USAGE —
     et cela appartient a @mostajs/skill-library et au journal d'@mostajs/assistant-pilote.
   - AUCUN FORMAT NOUVEAU : la projection produit du mostajs-devtest/1, valide par le parseur officiel.
+  - PROJETER POUR CREER, ENRICHIR POUR EXPLOITER. Dans le REFERENTIEL, une regle deux fois = duplication ;
+    dans une APPLICATION, la regle appliquee a un objet = OCCURRENCE, et il en faut autant qu'il y a d'objets.
+    toDevtest = app NEUVE (elle recoit ses exigences) · enrichir = app EXISTANTE (ses occurrences recoivent
+    les erreurs connues). enrichir n'AJOUTE ni exigence ni essai — sinon qatrax porte des cas inexecutables.
   - loadCatalogue() fait un import() : charger un corpus, c'est EXECUTER du code. Une fiche se revoit
     comme du code, jamais comme un document (docs/15-REVUE-SECURITE).
   - validateKind() applique les memes defauts que defineKind : on peut lui passer un objet BRUT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/kind-catalog",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Catalogue de KINDS — fiches d'exigence réutilisables, projetables en plan mostajs-devtest/1 lisible par qatrax. N'exécute rien, ne stocke rien.",
   "type": "module",
   "license": "AGPL-3.0-or-later",

package/src/enrichir.js

@@ -0,0 +1,91 @@
+/**
+ * ENRICHIR — faire descendre les erreurs connues d'une fiche dans les exigences QUE
+ * L'APPLICATION A DÉJÀ.
+ *
+ * ── PROJETER POUR CRÉER, ENRICHIR POUR EXPLOITER ───────────────────────────
+ * `toDevtest` sert à une application NEUVE : elle n'a aucune exigence, la fiche lui donne les
+ * siennes. `enrichir` sert à une application qui EN A DÉJÀ — et c'est le cas courant, puisqu'une
+ * fiche naît précisément de ce que des applications ont éprouvé.
+ *
+ * ⚠️ LE CRITÈRE QUI SÉPARE LES DEUX (décision du 03/09/2026, après un passage à qatrax qui l'a
+ * rendu visible) :
+ *
+ *   · dans le RÉFÉRENTIEL, une même règle deux fois est une DUPLICATION ;
+ *   · dans une APPLICATION, la même règle appliquée à un objet précis est une OCCURRENCE
+ *     d'exploitation, et il en faut autant qu'il y a d'objets.
+ *
+ * D'où la faute que cette fonction répare : projeter la règle GÉNÉRIQUE dans le plan d'une
+ * application ajoutait une exigence qui n'était appliquée à rien. Ni référentiel, ni occurrence :
+ * la règle recopiée. ATC portait déjà QUATRE occurrences du périmètre — le portail, le coaching,
+ * l'e-learning, le cumul de rôles — et recevait une cinquième exigence qui ne parlait de rien.
+ *
+ * ⚠️ ELLE N'AJOUTE NI EXIGENCE NI ESSAI. C'est ce qui referme, par construction, le défaut que
+ * qatrax avait signalé : des cas de plan que rien ne peut exécuter, parce qu'ils prétendaient
+ * qu'un essai portant un autre nom les couvrait.
+ *
+ * Author: Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+const propre = (v) => String(v ?? '').trim();
+
+/** La borne du bloc ajouté — elle rend l'enrichissement REJOUABLE sans empiler. */
+export const marqueur = (ref) => `⟦${ref}⟧`;
+
+/** Le bloc que la fiche dépose dans une exigence de l'application. */
+export function blocDeFiche(k) {
+  return [
+    marqueur(k.ref),
+    `Fiche ${k.ref} v${k.version} (${k.verdict}) — ce que d'autres projets ont payé :`,
+    ...k.erreurs.map((e) => `⚠ ${e.titre} — ${e.consequence}`),
+  ].join('\n');
+}
+
+/**
+ * Enrichit des exigences EXISTANTES avec les erreurs connues d'une fiche.
+ *
+ * @param {object} plan     plan `mostajs-devtest/1` de l'application — modifié en place
+ * @param {object} o
+ * @param {object} o.kind      la fiche (ou son instance affinée)
+ * @param {string[]} o.specRefs les exigences de l'application qui sont des OCCURRENCES de la règle
+ * @returns {{ enrichies: string[], bloc: string }}
+ */
+export function enrichir(plan, { kind, specRefs = [] } = {}) {
+  if (!plan?.specs) throw new Error('enrichir: plan `mostajs-devtest/1` requis');
+  if (!kind?.ref) throw new Error('enrichir: fiche requise');
+  if (!specRefs.length) {
+    // ⚠️ ENRICHIR SANS DIRE QUOI, C'EST NE RIEN FAIRE — et croire l'avoir fait. On refuse plutôt
+    // que de rendre un rapport vide qui passerait pour un succès.
+    throw new Error(`enrichir(${kind.ref}) : aucune exigence désignée — une fiche s’applique à des OCCURRENCES, nommez-les`);
+  }
+
+  const bloc = blocDeFiche(kind);
+  const enrichies = [];
+  for (const ref of specRefs) {
+    const s = plan.specs.find((x) => x.ref === propre(ref));
+    // ⚠️ UNE EXIGENCE INTROUVABLE EST UNE ERREUR, pas un avertissement : le plus probable est
+    // qu'elle a été renommée, et l'enrichissement partirait alors dans le vide en silence.
+    if (!s) throw new Error(`enrichir(${kind.ref}) : exigence introuvable — ${ref}`);
+    const tete = String(s.description ?? '').split(marqueur(kind.ref))[0].trimEnd();
+    s.description = tete ? `${tete}\n\n${bloc}` : bloc;
+    enrichies.push(s.ref);
+  }
+  return { enrichies, bloc };
+}
+
+/**
+ * Retire d'un plan ce qu'une PROJECTION y avait posé — exigences, réalisations et essais.
+ * Utile une fois : quand une application passe de `toDevtest` à `enrichir`.
+ */
+export function retirerProjection(plan, { kind, prefix } = {}) {
+  const corps = propre(kind?.ref ?? kind).replace(/^KIND-/, '');
+  const p = propre(prefix).toUpperCase();
+  const cible = { specs: `SPEC-${p}-${corps}`, realisations: `REL-${p}-${corps}`, tests: `T-${p}-${corps}-` };
+  const retires = [];
+  for (const [cle, debut] of Object.entries(cible)) {
+    const reste = [];
+    for (const l of plan[cle] ?? []) {
+      if (l.ref === debut || String(l.ref).startsWith(debut)) retires.push(l.ref); else reste.push(l);
+    }
+    plan[cle] = reste;
+  }
+  return retires;
+}

package/src/index.js

@@ -1,4 +1,5 @@
 export { defineKind, validateKind, VERDICTS, PROVENANCES, DOMAINES } from './kind.js';
 export { toDevtest, PLAN_VERSION } from './projection.js';
+export { enrichir, retirerProjection, blocDeFiche, marqueur } from './enrichir.js';
 export { instantiate, diffInstance, emplois, AFFINABLES } from './instance.js';
 export { loadCatalogue, findKinds, auditCatalogue, statsCatalogue } from './catalogue.js';