@mostajs/kind-catalog 0.1.0

package/src/instance.js

@@ -0,0 +1,85 @@
+/**
+ * L'INSTANCIATION — une application reprend une fiche, telle quelle ou AFFINÉE.
+ *
+ * ⚠️ CE QUI FAIT VIVRE UN CATALOGUE, CE N'EST PAS LA RÉUTILISATION À L'IDENTIQUE : c'est
+ * **l'écart tracé**. L'agronomie adapte l'itinéraire technique au terroir et relève l'écart ; le
+ * bâtiment reprend le DTU et amende **par clause dérogatoire écrite** ; le raisonnement à partir de
+ * cas fait de la révision une étape du cycle, pas un accident. Les trois disent la même chose.
+ *
+ * Sans cette trace, « réutiliser » se dégrade en « recopier », et l'on revient à l'état d'avant le
+ * module : des plans qui se ressemblent sans jamais se parler.
+ *
+ * Author: Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import { validateKind } from './kind.js';
+
+const propre = (v) => String(v ?? '').trim();
+
+/** Les champs qu'une application peut affiner. Le reste appartient à la fiche. */
+export const AFFINABLES = ['enonce', 'besoins', 'utilisation', 'succes', 'erreurs', 'test', 'seProsePose'];
+
+/**
+ * Instancie une fiche pour une application.
+ *
+ * @param {object} kind
+ * @param {object} o
+ * @param {string} o.app     l'application qui reprend
+ * @param {string} o.prefix  préfixe de ses références
+ * @param {object} [o.affine]  UNIQUEMENT les champs affinés, chacun avec son motif
+ *   `{ succes: { valeur: [...], motif: '…' } }`
+ */
+export function instantiate(kind, { app, prefix, affine = {} } = {}) {
+  if (!kind?.ref) throw new Error('instantiate: fiche requise');
+  if (!propre(app)) throw new Error('instantiate: `app` requise — une instance sans application ne se retrouve pas');
+
+  const affinages = [];
+  const resultat = { ...kind };
+  for (const [champ, val] of Object.entries(affine)) {
+    if (!AFFINABLES.includes(champ)) {
+      throw new Error(`instantiate(${kind.ref}) : « ${champ} » n’est pas affinable — affinables : ${AFFINABLES.join(', ')}`);
+    }
+    // ⚠️ LE MOTIF EST EXIGÉ. Un affinage sans motif est une recopie qui s'ignore : six mois plus
+    // tard, personne ne sait si l'écart était une nécessité du métier ou une facilité du moment —
+    // et c'est justement cet écart qui doit nourrir la version suivante de la fiche.
+    if (!propre(val?.motif)) {
+      throw new Error(`instantiate(${kind.ref}) : affinage de « ${champ} » sans \`motif\` — sans lui, « réutiliser » se dégrade en « recopier »`);
+    }
+    affinages.push({ champ, motif: propre(val.motif) });
+    resultat[champ] = val.valeur;
+  }
+
+  // L'instance AFFINÉE doit rester une fiche valide : on n'affine pas jusqu'à casser l'exigence.
+  const refus = validateKind(resultat);
+  if (refus.length) throw new Error(`instantiate(${kind.ref}) : l’affinage casse la fiche — ${refus.join(' · ')}`);
+
+  return Object.freeze({
+    kind: kind.ref,
+    kindVersion: kind.version,
+    app: propre(app),
+    prefix: propre(prefix) || propre(app).toUpperCase(),
+    affinages,
+    fiche: Object.freeze(resultat),
+  });
+}
+
+/** Ce que cette application a changé, et pourquoi — lisible d'un coup d'œil. */
+export function diffInstance(instance) {
+  if (!instance?.affinages?.length) return [];
+  return instance.affinages.map((a) => `${a.champ} : ${a.motif}`);
+}
+
+/**
+ * QUI EMPLOIE QUOI — l'index inverse.
+ * C'est ce qui rend l'affinage sûr dans les deux sens : on sait qui prévenir quand une fiche
+ * change, et on lit, en face de chaque fiche, tout ce que le terrain a dû lui faire dire.
+ */
+export function emplois(instances = []) {
+  const par = new Map();
+  for (const i of instances) {
+    const e = par.get(i.kind) || { kind: i.kind, apps: [], affinages: [] };
+    e.apps.push(i.app);
+    for (const a of i.affinages) e.affinages.push({ app: i.app, ...a });
+    par.set(i.kind, e);
+  }
+  return [...par.values()].sort((a, b) => b.apps.length - a.apps.length);
+}

package/src/kind.js

@@ -0,0 +1,152 @@
+/**
+ * @mostajs/kind-catalog — LA FICHE D'EXIGENCE RÉUTILISABLE.
+ *
+ * ── CE QU'EST UN KIND ──────────────────────────────────────────────────────
+ * Une **question qu'un métier se pose**, avec ce qu'il faut pour y répondre, comment on l'éprouve,
+ * à quoi on reconnaît une bonne réponse, et **les façons connues de se tromper**.
+ *
+ * ⚠️ UN KIND N'EST PAS UN ALGORITHME. `@mostajs/ro-pla` porte 23 dialectes pour 12 familles :
+ * plusieurs questions métier partagent le même moteur, et un moteur ne dit rien de la question.
+ * Ce qu'un exploitant active, c'est une question ; ce qu'un développeur choisit, c'est un moteur.
+ *
+ * ── CE QUE CE MODULE NE FAIT PAS ───────────────────────────────────────────
+ * Il **n'exécute rien** (ni solveur, ni essai, ni règle) et **ne stocke rien** (aucun schéma,
+ * aucun dépôt). Il décrit, valide et PROJETTE. Un essai le compte (`T-KC-12`).
+ *
+ * ── LA PROVENANCE, ET POURQUOI ELLE N'INTERDIT RIEN ────────────────────────
+ * Les grands catalogues du monde n'admettent que des faits : ATT&CK ne consigne que des techniques
+ * OBSERVÉES, CWE naît de vulnérabilités RÉELLES. Mais « fait » ne veut pas dire « incident chez
+ * nous » : un DTU, une fiche HACCP, un itinéraire technique sont des faits établis par un métier
+ * entier, et les ignorer laisserait le catalogue vide là où le savoir existe depuis des décennies.
+ *
+ * D'où la règle réelle : **toute fiche déclare d'où elle vient**, et son VERDICT dit ce qu'elle a
+ * traversé.
+ *
+ *   `reference` → tirée d'un corpus établi (norme, guide de bonnes pratiques, littérature)
+ *   `terrain`   → tirée du dire d'un praticien, nommé et daté
+ *   `incident`  → tirée d'un défaut CONSTATÉ, avec sa date et son fichier
+ *
+ * Une fiche `propose` peut n'avoir qu'une `reference` — et elle a toute sa place au catalogue.
+ * Une fiche `eprouve` ou `retenu` exige au moins un `incident` ou un `terrain` : **on ne se
+ * décerne pas l'expérience**. La contrainte ne porte donc pas sur l'ENTRÉE au catalogue, elle
+ * porte sur le GALON qu'on s'y donne.
+ *
+ * Author: Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+
+/**
+ * Les états d'une fiche.
+ * ⚠️ `ecarte` RESTE au catalogue, avec son motif : une fiche écartée qui disparaît est une fiche
+ * qui sera réinventée, avec les mêmes espoirs et le même échec.
+ */
+export const VERDICTS = ['propose', 'eprouve', 'retenu', 'ecarte'];
+
+/** Ce qui atteste qu'une fiche décrit quelque chose de réel. */
+export const PROVENANCES = ['reference', 'terrain', 'incident'];
+
+/** Les provenances qui autorisent à se dire ÉPROUVÉ : on ne se décerne pas l'expérience. */
+const PROVENANCES_EPROUVANTES = new Set(['incident', 'terrain']);
+
+/**
+ * Les domaines déclarés. Vocabulaire OUVERT — mais déclaré : un domaine surgi sans déclaration
+ * échappe à la revue, et le catalogue se fragmente en synonymes (`acces`, `access`, `droits`…).
+ * Tenu au §5.bis de `docs/PLAN-DEV-KIND-CATALOG.md`.
+ */
+export const DOMAINES = [
+  // transverses — nés d'incidents de l'écosystème
+  'acces', 'donnees', 'apprentissage', 'decision', 'integration',
+  // métier
+  'btp', 'alimentaire', 'elevage', 'apiculture', 'agronomie', 'electronique',
+];
+
+const propre = (v) => String(v ?? '').trim();
+const liste = (v) => (Array.isArray(v) ? v : v == null ? [] : [v]);
+
+/**
+ * Déclare une fiche. Refuse au montage ce qui la rendrait inutilisable, et NOMME tout ce qui
+ * manque d'un seul coup : corriger un manque pour en découvrir un autre fait abandonner.
+ */
+export function defineKind(f = {}) {
+  const k = {
+    ref: propre(f.ref),
+    enonce: propre(f.enonce),
+    domaine: propre(f.domaine) || 'decision',
+    version: propre(f.version) || '1',
+    besoins: liste(f.besoins),
+    utilisation: propre(f.utilisation),
+    succes: liste(f.succes).map(propre).filter(Boolean),
+    erreurs: liste(f.erreurs),
+    test: liste(f.test),
+    // Renvois — jamais recalculés ici : l'efficacité appartient à @mostajs/skill-library, et
+    // deux mémoires d'efficacité finiraient par se contredire.
+    efficacite: f.efficacite ?? null,
+    evaluation: f.evaluation ?? null,
+    verdict: propre(f.verdict) || 'propose',
+    motif: propre(f.motif) || null,
+    origine: liste(f.origine),
+    // OÙ la question se pose, quand ce n'est pas là où elle se calcule. Le corpus transverse n'en
+    // avait pas besoin ; le BTP (sur chantier) et l'électronique (sur l'embarqué) l'exigent.
+    seProsePose: propre(f.seProsePose) || null,
+  };
+  const refus = validateKind(k);
+  if (refus.length) throw new Error(`defineKind(${k.ref || '?'}) : ${refus.join(' · ')}`);
+  return Object.freeze(k);
+}
+
+/**
+ * Tout ce qui cloche, en une fois.
+ *
+ * ⚠️ APPLIQUE LES MÊMES DÉFAUTS QUE `defineKind`. Sans cela, valider un objet BRUT — celui qu'on
+ * vient d'écrire, avant de le passer à `defineKind` — reprochait un `verdict` manquant alors que
+ * le champ est facultatif. L'auteur corrigeait un reproche qui n'en était pas un, et la fonction
+ * mentait sur son propre contrat (constat du 02/09/2026, par la démonstration `demo-epreuve.mjs`).
+ */
+export function validateKind(brut = {}) {
+  const k = { verdict: 'propose', domaine: 'decision', ...brut };
+  if (!propre(k.verdict)) k.verdict = 'propose';
+  if (!propre(k.domaine)) k.domaine = 'decision';
+  const out = [];
+  if (!propre(k.ref)) out.push('`ref` requise');
+  else if (!/^KIND-[A-Z0-9-]+$/.test(k.ref)) out.push(`\`ref\` doit valoir KIND-… (reçu « ${k.ref} »)`);
+  if (!propre(k.enonce)) out.push('`enonce` requis — une fiche sans question n’est pas une exigence');
+
+  if (!DOMAINES.includes(k.domaine)) {
+    out.push(`\`domaine\` non déclaré : ${k.domaine} — déclarés : ${DOMAINES.join(', ')}`);
+  }
+
+  // ⚠️ `succes` et `erreurs` sont les deux seuls champs exigés en plus de l'énoncé, et c'est
+  // délibéré : ce sont ceux qu'on omet, et ce sont ceux qui servent.
+  if (!liste(k.succes).length) out.push('`succes` requis — sans critère écrit, tout résultat paraît bon');
+  if (!liste(k.erreurs).length) out.push('`erreurs` requis — une fiche sans façon connue de se tromper n’apprend rien, et c’est la seule raison d’en reprendre une');
+
+  for (const [i, e] of liste(k.erreurs).entries()) {
+    if (!propre(e?.titre)) out.push(`erreurs[${i}] : \`titre\` requis`);
+    // La CONSÉQUENCE distingue un avertissement d'une consigne : « ne pas oublier le périmètre »
+    // ne se retient pas ; « sans lui, tout parent lit le dossier de tous » se retient. CWE/OWASP.
+    if (!propre(e?.consequence)) out.push(`erreurs[${i}] : \`consequence\` requise — un avertissement sans sa conséquence ne se retient pas`);
+  }
+  for (const [i, t] of liste(k.test).entries()) {
+    if (!propre(t?.action)) out.push(`test[${i}] : \`action\` requise`);
+    if (!propre(t?.attendu)) out.push(`test[${i}] : \`attendu\` requis`);
+  }
+
+  if (!VERDICTS.includes(k.verdict)) out.push(`\`verdict\` inconnu : ${k.verdict} — attendus : ${VERDICTS.join(', ')}`);
+  if (k.verdict === 'ecarte' && !propre(k.motif)) {
+    out.push('`motif` requis pour un verdict `ecarte` — une fiche écartée sans motif sera réinventée');
+  }
+
+  // ── LA PROVENANCE ────────────────────────────────────────────────────────
+  const origines = liste(k.origine);
+  if (!origines.length) out.push('`origine` requise — une fiche sans provenance est une idée déguisée');
+  for (const [i, o] of origines.entries()) {
+    if (!PROVENANCES.includes(propre(o?.type))) {
+      out.push(`origine[${i}] : \`type\` inconnu — attendus : ${PROVENANCES.join(', ')}`);
+    }
+    if (!propre(o?.source)) out.push(`origine[${i}] : \`source\` requise — norme, praticien ou fichier`);
+  }
+  if (['eprouve', 'retenu'].includes(k.verdict)
+      && !origines.some((o) => PROVENANCES_EPROUVANTES.has(propre(o?.type)))) {
+    out.push(`verdict \`${k.verdict}\` exige une origine \`incident\` ou \`terrain\` — on ne se décerne pas l’expérience`);
+  }
+  return out;
+}

package/src/projection.js

@@ -0,0 +1,76 @@
+/**
+ * LA PROJECTION — une fiche devient des EXIGENCES et des ESSAIS au format `mostajs-devtest/1`.
+ *
+ * ⚠️ AUCUN FORMAT NOUVEAU, et c'est la décision structurante du module. `@mostajs/qa-engine` parse
+ * déjà `mostajs-devtest/1`, et qatrax l'importe déjà. Inventer un second format aurait demandé un
+ * second validateur, un second import, un second écran — et le jour où les deux divergent, c'est
+ * le catalogue qui aurait raison contre les faits.
+ *
+ * ⚠️ C'EST ICI QUE LE CATALOGUE DEVIENT UTILE. L'état de l'art le montre : CWE est branché aux
+ * scanners et s'applique ; le catalogue de patrons d'exigences de Withall n'est branché à rien et
+ * est resté un livre. **Une fiche qui ne descend pas dans le plan de test du projet ne sera pas
+ * appliquée**, quelle que soit sa qualité.
+ *
+ * Author: Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+export const PLAN_VERSION = 'mostajs-devtest/1';
+
+const propre = (v) => String(v ?? '').trim();
+/** `KIND-PERIMETRE-01` → `PERIMETRE-01` : la référence projetée porte le préfixe de l'application. */
+const corps = (ref) => propre(ref).replace(/^KIND-/, '');
+
+/**
+ * Projette des fiches en plan Dev+Test.
+ *
+ * @param {object[]} kinds
+ * @param {object} o
+ * @param {{key:string,name:string,description?:string}} o.project  le projet, au sens qatrax
+ * @param {string} o.prefix  préfixe des références — `ATC`, `RESTO`… ISOLE deux applications qui
+ *   reprennent la même fiche : sans lui, leurs plans se marcheraient dessus dans le même qatrax.
+ */
+export function toDevtest(kinds = [], { project, prefix = 'APP' } = {}) {
+  if (!project?.key || !project?.name) throw new Error('toDevtest: `project` { key, name } requis');
+  const p = propre(prefix).toUpperCase();
+  const plan = { plan: PLAN_VERSION, project: { ...project }, specs: [], realisations: [], tests: [] };
+
+  for (const k of kinds) {
+    const specRef = `SPEC-${p}-${corps(k.ref)}`;
+    plan.specs.push({
+      ref: specRef,
+      title: k.enonce,
+      priority: 'critical',
+      // Le verdict de la FICHE devient le statut de l'exigence : une fiche seulement `propose`
+      // ne doit pas apparaître comme vérifiée dans le suivi du projet.
+      status: k.verdict === 'eprouve' || k.verdict === 'retenu' ? 'verified' : 'draft',
+      // LA DESCRIPTION PORTE LES ERREURS CONNUES. C'est tout l'apport du catalogue : celui qui lit
+      // l'exigence dans qatrax reçoit AUSSI ce qui a mal tourné ailleurs, avec la conséquence.
+      description: [
+        k.utilisation ? `Emploi : ${k.utilisation}` : null,
+        k.succes.length ? `Réussi si : ${k.succes.join(' · ')}` : null,
+        ...k.erreurs.map((e) => `⚠ ${e.titre} — ${e.consequence}`),
+        `Fiche ${k.ref} v${k.version} (${k.verdict})`,
+      ].filter(Boolean).join('\n'),
+    });
+
+    plan.realisations.push({
+      ref: `REL-${p}-${corps(k.ref)}`,
+      specRef,
+      kind: 'feature',
+      title: `Reprise de la fiche ${k.ref}`,
+      progress: 0,
+      status: 'todo',
+    });
+
+    k.test.forEach((t, i) => {
+      plan.tests.push({
+        ref: `T-${p}-${corps(k.ref)}-${i + 1}`,
+        specRef,
+        title: `T-${p}-${corps(k.ref)}-${i + 1} — ${t.action}`,
+        type: 'automated',
+        priority: 'critical',
+        steps: [{ action: t.action, expected: t.attendu }],
+      });
+    });
+  }
+  return plan;
+}