@mostajs/kind-catalog 0.2.0 → 0.4.0

package/src/diagnostic.js

@@ -0,0 +1,209 @@
+/**
+ * DIAGNOSTIQUER — lire le plan d'une application et lui dire ce qui lui MANQUE.
+ *
+ * ── LE TRANCHANT « AMÉLIORER » ─────────────────────────────────────────────
+ * Le catalogue sert deux fois : à BÂTIR (une application neuve reçoit ses exigences) et à
+ * AMÉLIORER (une application qui tourne reçoit ce que d'autres ont payé). Ce fichier est le
+ * second, et c'est celui qui se rend en une heure, sur un plan qu'on nous donne, sans toucher au
+ * code :
+ *
+ *   « Votre plan porte quatre exigences de périmètre. La fiche en connaît six erreurs.
+ *     Trois ne sont mentionnées nulle part chez vous — voici lesquelles, et ce qu'elles coûtent. »
+ *
+ * ⚠️ IL PROPOSE, IL N'APPLIQUE PAS. Un rapprochement automatique entre les exigences d'une
+ * application et les fiches SE TROMPERA : les intitulés varient, les métiers diffèrent, et une
+ * ressemblance de mots n'est pas une identité de règle. Un outil qui appliquerait ses
+ * rapprochements tout seul poserait des blocs d'erreurs sur des exigences sans rapport, et
+ * ruinerait la confiance dans les blocs justes. C'est `KIND-ECRITURE-GARDEE-01` appliqué à
+ * l'outil lui-même.
+ *
+ * ⚠️ LE RAPPROCHEMENT EST EXPLICABLE, ET C'EST SA SEULE DÉFENSE. Chaque candidat rend LES MOTS
+ * qui l'ont désigné : un score opaque serait pire que pas de score du tout — on ne peut ni le
+ * contester ni le corriger.
+ *
+ * Author: Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+
+/** Mots vides du français — ils apparaissent partout et ne désignent rien. */
+const VIDES = new Set(`le la les un une des du de d au aux et ou ni mais donc or car que qui quoi
+dont ou sur sous dans par pour avec sans vers chez entre est sont etre ete a ont avoir plus moins
+tres peu tout tous toute toutes meme aussi ainsi alors quand comme si ne pas non oui son sa ses
+leur leurs notre nos votre vos ce cet cette ces cela ceci il elle ils elles on nous vous je tu
+doit doivent peut peuvent faire fait fais rien jamais toujours deja encore apres avant lors
+chaque autre autres bien mal seul seule sauf selon sera seront soit soient afin ceux celui
+celle quel quels quelle telle tels deux puis nul nulle dune dun cest lune lun elles`.split(/\s+/).filter(Boolean));
+
+/** Normalise : minuscules, sans accents, sans ponctuation. */
+export const normaliser = (t) => String(t ?? '')
+  .toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '')
+  .replace(/[^a-z0-9]+/g, ' ').trim();
+
+/** Les mots qui DÉSIGNENT quelque chose — au moins cinq lettres, hors mots vides. */
+export function motsCles(texte) {
+  return new Set(normaliser(texte).split(' ').filter((m) => m.length >= 4 && !VIDES.has(m)));
+}
+
+const commun = (a, b) => [...a].filter((m) => b.has(m));
+
+/**
+ * Construit la CANONISATION d'une fiche : chaque groupe de synonymes déclaré ramène ses membres au
+ * premier d'entre eux. Deux textes qui emploient deux mots du même groupe se reconnaissent alors —
+ * c'est exactement le faux positif relevé par l'épreuve rétrospective n° 1 (06/09/2026), où la
+ * fiche disait « retrait / tombale » et le plan « désactivation / horodaté ».
+ *
+ * ⚠️ LES MEMBRES SONT DES RADICAUX, PAS DES MOTS, et le rapprochement se fait par PRÉFIXE. Écrit
+ * en mots entiers, ce champ demandait d'énumérer toutes les flexions du français — `supprimer`,
+ * `supprime`, `supprimée`, `supprimées`… — liste qu'on croit finie et qui ne l'est jamais : la
+ * première version de ce champ tenait neuf mots pour un seul groupe et laissait passer
+ * `supprimée`, ce qu'un essai a montré (T-KC-23). Un radical (`supprim`) les couvre tous.
+ *
+ * ⚠️ QUATRE LETTRES AU MOINS pour un radical. Plus court, il cesse de désigner : `dat` attraperait
+ * `datation` mais aussi `dattes`, et un rapprochement qu'on ne peut plus justifier est pire que
+ * pas de rapprochement — c'est la seule défense de cet outil (voir l'en-tête).
+ */
+function canonique(kind) {
+  const groupes = (kind.synonymes ?? []).map((groupe) => {
+    const radicaux = groupe.map((m) => normaliser(m).replace(/ /g, '')).filter(Boolean);
+    // La tête reste le PREMIER déclaré, même s'il est trop court pour servir de radical : c'est
+    // l'étiquette du groupe, pas un motif de recherche.
+    return { tete: radicaux[0], motifs: radicaux.filter((r) => r.length >= 4) };
+  }).filter((g) => g.tete && g.motifs.length > 0);
+
+  return (mots) => new Set([...mots].map((mot) => {
+    const g = groupes.find(({ motifs }) => motifs.some((r) => mot.startsWith(r)));
+    return g ? g.tete : mot;
+  }));
+}
+
+/** Tout le texte d'une exigence, épreuves comprises : c'est là que la règle se dit. */
+function texteDeSpec(plan, spec) {
+  const essais = (plan.tests ?? []).filter((t) => t.specRef === spec.ref);
+  return [spec.title, spec.description,
+    ...essais.flatMap((t) => [t.title, ...(t.steps ?? []).flatMap((s) => [s.action, s.expected])])]
+    .filter(Boolean).join(' ');
+}
+
+/**
+ * Les domaines TRANSVERSES : leurs règles valent pour tout logiciel, qu'on ait su rapprocher une
+ * exigence ou non. Les domaines MÉTIER, eux, ne concernent que les applications de ce métier.
+ */
+export const TRANSVERSES = new Set(['acces', 'donnees', 'apprentissage', 'decision', 'integration']);
+
+/**
+ * Diagnostique un plan contre un corpus.
+ *
+ * ⚠️ LES DEUX SORTIES SONT DÉCOUPLÉES, ET C'EST LE POINT. Elles n'ont pas le même seuil optimal,
+ * et les lier faisait taire l'une pour l'autre :
+ *
+ *   · les OCCURRENCES proposées demandent de la PRÉCISION — l'humain doit les confirmer, et
+ *     personne ne confirme vingt-sept lignes. Seuil haut, liste courte.
+ *   · les ERREURS NON COUVERTES demandent du RAPPEL — c'est le livrable, et taire celle qui
+ *     manque coûte bien plus que d'en proposer une déjà couverte. Elles sont calculées sur TOUT
+ *     le plan, et rendues même quand aucune exigence n'a pu être rapprochée.
+ *
+ * Une règle TRANSVERSE rend ses erreurs dans tous les cas ; une règle MÉTIER seulement si une
+ * exigence l'a désignée — sinon un plan universitaire recevrait les pièges de l'apiculture.
+ *
+ * @param {object} plan   plan `mostajs-devtest/1` — NON modifié
+ * @param {object[]} kinds
+ * @param {object} [o]
+ * @param {number} [o.minCommuns]  mots communs exigés pour PROPOSER une occurrence (défaut 5)
+ * @returns {object[]} un rapport par fiche
+ */
+export function diagnostiquer(plan, kinds = [], { minCommuns = 5 } = {}) {
+  if (!plan?.specs) throw new Error('diagnostiquer: plan `mostajs-devtest/1` requis');
+  const toutLePlan = motsCles([
+    ...plan.specs.map((s) => `${s.title} ${s.description ?? ''}`),
+    ...(plan.tests ?? []).flatMap((t) => [t.title, ...(t.steps ?? []).flatMap((x) => [x.action, x.expected])]),
+  ].join(' '));
+
+  return kinds.map((k) => {
+    const canon = canonique(k);
+    const cles = canon(motsCles(`${k.enonce} ${k.succes.join(' ')} ${k.erreurs.map((e) => e.titre).join(' ')}`));
+    // Le plan est canonisé AVEC LA TABLE DE CETTE FICHE : chaque fiche apporte son vocabulaire, et
+    // celui d'une fiche ne parasite pas la lecture d'une autre.
+    const planCanon = canon(toutLePlan);
+
+    // 1 · LES OCCURRENCES CANDIDATES — proposées, jamais posées.
+    const occurrences = [];
+    for (const s of plan.specs) {
+      const c = commun(cles, canon(motsCles(texteDeSpec(plan, s))));
+      if (c.length >= minCommuns) occurrences.push({ specRef: s.ref, titre: s.title, communs: c.sort() });
+    }
+    occurrences.sort((a, b) => b.communs.length - a.communs.length);
+
+    /**
+     * 2 · LES ERREURS QUE LE PLAN NE MENTIONNE NULLE PART — c'est le livrable.
+     *
+     * ⚠️ ON NE COMPARE QUE LE TITRE, PAS LA CONSÉQUENCE. Corrigé le 06/09/2026, après l'épreuve
+     * rétrospective n° 1. La conséquence est NOTRE prose — elle explique le coût de l'erreur à
+     * celui qui lit la fiche. **Un plan n'a aucune raison de la contenir.** L'inclure dans la
+     * comparaison rendait une erreur d'autant plus « non couverte » qu'elle était bien expliquée,
+     * et une exigence courte mais explicite ne pouvait JAMAIS couvrir une erreur verbeuse.
+     *
+     * ⚠️ Et le seuil porte sur DEUX mots du titre, pas sur une proportion. Une proportion pénalise
+     * les titres longs, ce qui est l'inverse du bon sens : un titre long est plus reconnaissable,
+     * pas moins.
+     */
+    const erreursNonCouvertes = k.erreurs.filter((e) => {
+      const mots = canon(motsCles(e.titre));
+      if (mots.size === 0) return false;
+      return commun(mots, planCanon).length < Math.min(2, mots.size);
+    });
+
+    const transverse = TRANSVERSES.has(k.domaine);
+    return {
+      kind: k.ref, domaine: k.domaine, verdict: k.verdict, enonce: k.enonce,
+      occurrences,
+      couverte: occurrences.length > 0,
+      transverse,
+      erreurs: k.erreurs.length,
+      // Une règle métier non rapprochée ne dit rien : elle ne concerne pas cette application.
+      erreursNonCouvertes: (transverse || occurrences.length) ? erreursNonCouvertes : [],
+    };
+  }).sort((a, b) => b.occurrences.length - a.occurrences.length);
+}
+
+/** Le rapport en texte — c'est lui qu'on présente. */
+export function rapportDiagnostic(diag, { titre = 'Diagnostic', maxOccurrences = 4 } = {}) {
+  const l = [`# ${titre}`, ''];
+  const aTrous = diag.filter((d) => d.erreursNonCouvertes.length);
+  const reconnues = diag.filter((d) => d.couverte);
+  const trous = aTrous.reduce((n, d) => n + d.erreursNonCouvertes.length, 0);
+
+  l.push(`**${trous}** erreur(s) connue(s) que ce plan ne mentionne nulle part, sur **${aTrous.length}** règle(s) · **${reconnues.length}** règle(s) rapprochée(s) d’au moins une exigence.`, '');
+  l.push('> ⚠️ Les rapprochements sont **proposés**, jamais appliqués : une ressemblance de mots n’est pas une identité de règle. Chaque candidat rend **les mots qui l’ont désigné**, pour qu’on puisse le contester.', '');
+  l.push('> Les erreurs, elles, sont cherchées dans **tout** le plan — titres, descriptions et épreuves. Une erreur signalée à tort s’écarte en dix secondes ; une erreur tue ne se cherche jamais.', '');
+
+  l.push('## Ce qui manque', '');
+  if (!aTrous.length) l.push('Aucune erreur connue du catalogue n’est absente de ce plan.', '');
+  for (const d of aTrous) {
+    l.push(`### ${d.kind} — ${d.enonce}`, '');
+    if (d.occurrences.length) {
+      l.push(`*Reconnue dans ${d.occurrences.length} exigence(s) :* ` + d.occurrences.slice(0, maxOccurrences).map((o) => `\`${o.specRef}\``).join(', ')
+        + (d.occurrences.length > maxOccurrences ? ` *(+${d.occurrences.length - maxOccurrences})*` : ''), '');
+    } else {
+      l.push(`*Règle transverse — aucune exigence de ce plan ne la porte explicitement.*`, '');
+    }
+    l.push(`**${d.erreursNonCouvertes.length} sur ${d.erreurs} erreur(s) connue(s) ne sont mentionnées nulle part :**`, '');
+    for (const e of d.erreursNonCouvertes) l.push(`- **${e.titre}** — ${e.consequence}`);
+    l.push('');
+  }
+
+  const propres = reconnues.filter((d) => !d.erreursNonCouvertes.length);
+  if (propres.length) {
+    l.push('## Ce qui est couvert', '');
+    l.push('Ces règles sont reconnues dans le plan, et **toutes** leurs erreurs connues y sont évoquées.', '');
+    for (const d of propres) {
+      l.push(`- \`${d.kind}\` — ${d.enonce}  *(${d.occurrences.slice(0, maxOccurrences).map((o) => o.specRef).join(', ')})*`);
+    }
+    l.push('');
+  }
+  const hors = diag.filter((d) => !d.couverte && !d.erreursNonCouvertes.length);
+  if (hors.length) {
+    l.push('## Hors périmètre apparent', '');
+    l.push('Aucune exigence ne les désigne — elles ne concernent probablement pas cette application.', '');
+    for (const d of hors) l.push(`- \`${d.kind}\` (${d.domaine})`);
+  }
+  return l.join('\n');
+}

package/src/index.js

@@ -1,5 +1,6 @@
 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 { diagnostiquer, rapportDiagnostic, motsCles, normaliser, TRANSVERSES } from './diagnostic.js';
 export { instantiate, diffInstance, emplois, AFFINABLES } from './instance.js';
 export { loadCatalogue, findKinds, auditCatalogue, statsCatalogue } from './catalogue.js';

package/src/kind.js

@@ -84,6 +84,18 @@ export function defineKind(f = {}) {
     verdict: propre(f.verdict) || 'propose',
     motif: propre(f.motif) || null,
     origine: liste(f.origine),
+    /**
+     * LES SYNONYMES DU DOMAINE — groupes de mots qui désignent la MÊME chose.
+     *
+     * ⚠️ Ajoutés le 06/09/2026, après l'épreuve rétrospective n° 1. Le diagnostic avait signalé
+     * 5 erreurs sur 5 comme « non mentionnées » dans un plan qui les couvrait explicitement : la
+     * fiche disait *retrait*, *pierre tombale*, le plan disait *désactivation*, *horodatés*. Deux
+     * textes qui disent la même chose avec d'autres mots ne se reconnaissaient pas.
+     *
+     * Aucun rapprochement lexical ne peut deviner cette équivalence — elle est propre au domaine.
+     * Elle se DÉCLARE donc, comme tout le reste de la fiche.
+     */
+    synonymes: liste(f.synonymes).filter((g) => Array.isArray(g) && g.length > 1),
     // 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,