@sylad/cadence 1.1.0 → 1.2.0

package/dist/orchestrate/spec.js

@@ -5,9 +5,9 @@ import { parse } from 'yaml';
 import { checkFiche, fichesDuDossier, LARGEURS } from '../spec.js';
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const list = (v) => (Array.isArray(v) ? v.filter(isObj) : []);
-/** Chemin (relatif au dépôt) de la fiche du lot sous `<dir>/<écran>/fiche.yaml`, ou null : sert à ne pas rejouer une spec déjà écrite. */
+/** Chemin (relatif au dépôt) de la fiche du lot sous `<dir>/<écran ou sujet>/fiche.yaml` (`ecran.lot` ou `sujet.lot`), ou null : sert à ne pas rejouer une spec déjà écrite. */
 export function findFiche(repo, dir, lot) {
-    const hit = fichesDuDossier(repo, dir).find(({ doc }) => isObj(doc.ecran) && doc.ecran.lot === lot);
+    const hit = fichesDuDossier(repo, dir).find(({ doc }) => (isObj(doc.ecran) && doc.ecran.lot === lot) || (isObj(doc.sujet) && doc.sujet.lot === lot));
     return hit ? `${dir}/${hit.name}/fiche.yaml` : null;
 }
 /** Texte sans accents ni majuscules, pour les mots-clés. */
@@ -40,9 +40,19 @@ export function costlyHypotheses(doc) {
     }
     return out;
 }
+/** La fiche écrite porte une partie back (un bloc `sujet`) : c'est ce qui fait d'un lot à `screen:` un lot mixte (L188), jamais un champ `spec: true` à côté de `screen:`. */
+export function ficheHasBack(repo, fiche) {
+    try {
+        const doc = parse(readFileSync(join(repo, fiche), 'utf8'));
+        return isObj(doc) && 'sujet' in doc;
+    }
+    catch {
+        return false;
+    }
+}
 /** Une fiche déjà écrite ne dispense de la spec que si elle passe les contrôles du programme et ne porte aucune hypothèse coûteuse. */
-export function ficheReady(repo, fiche, lot) {
-    if (checkSpec(repo, fiche, lot).length)
+export function ficheReady(repo, fiche, lot, parts = { screen: true, back: false }) {
+    if (checkSpec(repo, fiche, lot, parts).length)
         return false;
     try {
         return costlyHypotheses(parse(readFileSync(join(repo, fiche), 'utf8'))).length === 0;
@@ -74,10 +84,10 @@ function tracked(repo, dir) {
  * elle est celle du lot et de son dossier, la maquette existe avec une section `#etat-<état>` par état et un
  * `data-testid` par champ, et chaque état a sa capture à chaque largeur — le tout commité.
  */
-export function checkSpec(repo, fiche, lot) {
+export function checkSpec(repo, fiche, lot, parts = { screen: true, back: false }) {
     const file = join(repo, fiche);
     if (!existsSync(file))
-        return [`${fiche} : fiche absente (écrire docs/specs/<écran>/fiche.yaml et la commiter)`];
+        return [`${fiche} : fiche absente (écrire ${fiche.replace(/[^/]+\/fiche\.yaml$/, parts.screen ? '<écran>' : '<sujet>')}/fiche.yaml et la commiter)`];
     let doc;
     try {
         doc = parse(readFileSync(file, 'utf8'));
@@ -86,9 +96,30 @@ export function checkSpec(repo, fiche, lot) {
         return [`${fiche} : YAML illisible (${e.message.split('\n')[0]})`];
     }
     const problems = checkFiche(doc).map((p) => `fiche : ${p}`);
-    if (!isObj(doc) || !isObj(doc.ecran))
+    if (!isObj(doc))
         return problems;
     const folder = fiche.replace(/\/fiche\.yaml$/, '');
+    // un lot back (`spec: true`, avec ou sans écran) écrit la partie sujet : sans elle, ni lot ni dossier ne seraient contrôlés
+    if (parts.back) {
+        if (!isObj(doc.sujet)) {
+            if (!('sujet' in doc) && 'ecran' in doc)
+                problems.push('fiche : sujet : bloc manquant (un lot qui change un comportement écrit la partie sujet, même si la fiche a aussi un écran)');
+        }
+        else {
+            const sujet = doc.sujet;
+            if (typeof sujet.lot === 'string' && sujet.lot !== lot)
+                problems.push(`sujet.lot : « ${sujet.lot} » au lieu de ${lot} (la fiche est celle du lot qui implémente le comportement)`);
+            if (typeof sujet.id === 'string' && !folder.endsWith(`/${sujet.id}`))
+                problems.push(`sujet.id : « ${sujet.id} » ne correspond pas au dossier ${folder}`);
+            if (!parts.screen && !tracked(repo, folder).has(fiche))
+                problems.push(`${fiche} : fiche non commité`);
+        }
+    }
+    if (!parts.screen)
+        return problems;
+    // un lot à écran écrit la partie écran : sans elle, ni lot, ni dossier, ni maquette, ni captures ne seraient contrôlés
+    if (!isObj(doc.ecran))
+        return [...problems.filter((p) => p !== 'fiche : ecran : bloc manquant'), 'fiche : ecran : bloc manquant (un lot à écran écrit la partie écran, même si la fiche a aussi un sujet)'];
     const ecran = doc.ecran;
     if (typeof ecran.lot === 'string' && ecran.lot !== lot)
         problems.push(`ecran.lot : « ${ecran.lot} » au lieu de ${lot} (la fiche est celle du lot qui implémente l'écran)`);
@@ -121,17 +152,43 @@ export function checkSpec(repo, fiche, lot) {
             need(`${folder}/maquette-${e}-${w}.png`, 'capture');
     return problems;
 }
+/** Première phrase d'un texte, ramenée à une longueur lisible dans une note. */
+const sentence = (t, max = 160) => {
+    const flat = t.replace(/\s+/g, ' ').trim();
+    const end = flat.search(/[.!?](\s|$)/);
+    const first = end > 0 ? flat.slice(0, end) : flat;
+    return first.length > max ? `${first.slice(0, max - 1).trimEnd()}…` : first;
+};
+/** Une ligne par règle `hypothese` de la fiche (`R3 : ce que la règle dit ; si faux : ce qui changerait`), pour la note du lot et le tableau de fin de vague (spec etape-spec-back § 7). */
+export function hypothesisLines(doc) {
+    if (!isObj(doc))
+        return [];
+    return list(doc.regles)
+        .filter((r) => r.statut === 'hypothese' && typeof r.id === 'string')
+        .map((r) => `${String(r.id)} : ${sentence(String(r.enonce ?? ''))} ; si faux : ${sentence(String(r.si_faux ?? ''))}`);
+}
+/** Texte de la note du lot pour une hypothèse (une note par règle). */
+export const hypothesisNote = (sujet, line) => `Hypothèses (fiche ${sujet}) — ${line}`;
 /** Consigne propre à l'étape spec dans le brief : dossier, largeurs, commande de rendu, et les écarts de la passe précédente. */
 export function specText(o) {
-    const lines = [
-        `The lot declares \`screen: ${o.screen ?? 'page'}\`. The specs of this project live in \`${o.dir}/<écran>/\` (one folder per screen, \`<écran>\` = the kebab-case \`ecran.id\` of the sheet).`,
-        `Render each state of the mockup at ${LARGEURS.map((w) => `${w}`).join(' and ')} px width: one capture per state and per width, named \`maquette-<état>-<largeur>.png\` (e.g. \`maquette-vide-1440.png\`).`,
-        o.render
+    const lines = [];
+    if (o.screen) {
+        lines.push(`The lot declares \`screen: ${o.screen}\`. The specs of this project live in \`${o.dir}/<écran>/\` (one folder per screen, \`<écran>\` = the kebab-case \`ecran.id\` of the sheet).`, `Render each state of the mockup at ${LARGEURS.map((w) => `${w}`).join(' and ')} px width: one capture per state and per width, named \`maquette-<état>-<largeur>.png\` (e.g. \`maquette-vide-1440.png\`).`, o.render
             ? `The project declares how to render mockups (\`orchestrate.spec.render\`): \`${o.render}\` (from the repository root). Use it; fall back on Playwright only if it cannot run, and say so under "nonVerifie".`
-            : 'No render command is declared (`orchestrate.spec.render`): render with Playwright (open `maquette.html` as a local file, resize to each width, open each `#etat-<état>`).',
-    ];
+            : 'No render command is declared (`orchestrate.spec.render`): render with Playwright (open `maquette.html` as a local file, resize to each width, open each `#etat-<état>`).');
+    }
+    if (o.back) {
+        lines.push(o.screen
+            ? `The sheet has both parts, \`sujet\`, \`cas\`, \`contrats\`, \`donnees\` next to \`ecran\`, in the same folder (\`sujet.id\` = \`ecran.id\` = the folder name, \`sujet.lot\` = \`ecran.lot\`); the API calls of the screen are listed once in \`contrats\`, and the actions point to them with \`contrat: Ax\`.`
+            : `The lot declares \`spec: true\` (it changes a behaviour, with no screen). The specs of this project live in \`${o.dir}/<sujet>/\` (one folder per subject, \`<sujet>\` = the kebab-case \`sujet.id\` of the sheet); the sheet has no screen part.`);
+    }
+    if (o.screen && !o.back) {
+        lines.push(`If the lot also changes a behaviour (an API call, a stored datum, a contract), add the back part to the same sheet: \`sujet\`, \`cas\`, \`contrats\`, \`donnees\` next to \`ecran\` (\`sujet.id\` = \`ecran.id\` = the folder name, \`sujet.lot\` = \`ecran.lot\`); the program then also has the sheet reviewed (rules sourced, contradictions, errors and limits, one test per rule), before the mockup. A lot that only draws a screen keeps a sheet without \`sujet\`.`);
+    }
     if (o.template)
-        lines.push('', 'Template of the sheet (`templates/fiche.yaml` of cadence; every key and invariant is checked by `cadence spec check`):', '```yaml', o.template.trimEnd(), '```');
+        lines.push('', 'Template of the screen part of the sheet (`templates/fiche.yaml` of cadence; every key and invariant is checked by `cadence spec check`):', '```yaml', o.template.trimEnd(), '```');
+    if (o.templateBack)
+        lines.push('', 'Template of the back part of the sheet (`templates/fiche-back.yaml` of cadence; every key and invariant is checked by `cadence spec check`):', '```yaml', o.templateBack.trimEnd(), '```');
     if (o.problems?.length)
         lines.push('', 'The program checked your previous spec and it did not pass; fix exactly these points (one more pass only, then the lot goes back to the lead):', ...o.problems.map((p) => `- ${p}`));
     if (o.review)

package/dist/orchestrate/state.js

@@ -11,8 +11,8 @@ export const lotRepoPaths = (l) => [l.repo, ...(l.repos ?? []).map((r) => r.path
 /** Les dépôts voisins du lot, donnés en `--add-dir` à ses sessions. */
 export const neighbourDirs = (l) => (l.repos ?? []).map((r) => r.path);
 export const lotKey = (project, lot) => `${project}:${lot}`;
-/** Nom de dossier d'un lot dans la vague : le « / » d'un id de sous-tâche (`Q4/accueil-4-ux12`) devient « __ » ; un id sans « / » est inchangé. */
-export const lotSlug = (project, lot) => `${project}--${lot.split('/').join('__')}`;
+/** Nom de dossier d'un lot dans la vague : le « / » d'un id de sous-tâche (`Q4/accueil-4-ux12`) ou d'un projet imbriqué (`groupe/gamma`) devient « __ » ; sans « / » le nom est inchangé. */
+export const lotSlug = (project, lot) => `${project.split('/').join('__')}--${lot.split('/').join('__')}`;
 const lotFile = (project, lot) => `${lotSlug(project, lot)}.json`;
 function atomicWrite(file, data) {
     const tmp = `${file}.${process.pid}.tmp`;

package/dist/orchestrate/table.js

@@ -123,6 +123,8 @@ export function renderTable(wave, lots, deps = {}) {
             out.push(`${l.project}:${l.lot} — ⚠ ${w}`);
         for (const x of l.choix ?? [])
             out.push(`${l.project}:${l.lot} — choix fait : ${x}`);
+        for (const h of l.hypotheses ?? [])
+            out.push(`${l.project}:${l.lot} — hypothèse de la fiche : ${h}`);
         for (const p of l.proposals)
             out.push(`${l.project}:${l.lot} — proposé : ${p}`);
         if (l.uxVerdict && l.visible)

package/dist/plan.js

@@ -5,7 +5,7 @@ import { isDay, toDay } from './dates.js';
 export const STATUSES = ['todo', 'doing', 'done', 'dropped'];
 export class RafError extends Error {
 }
-export const FIELDS = ['id', 'title', 'status', 'estimate', 'quickwin', 'visible', 'screen', 'public', 'every', 'last', 'after', 'created', 'started', 'finished', 'notes', 'repos', 'parent'];
+export const FIELDS = ['id', 'title', 'status', 'estimate', 'quickwin', 'visible', 'screen', 'spec', 'public', 'every', 'last', 'after', 'created', 'started', 'finished', 'notes', 'repos', 'parent'];
 /** Nature de l'écran d'un lot visible : nouvelle page, nouveau composant, parcours modifié. */
 export const SCREENS = ['page', 'component', 'journey'];
 export function isOpen(status) {
@@ -319,6 +319,8 @@ export class Plan {
             entry.visible = true;
         if (opts.screen)
             entry.screen = opts.screen;
+        if (opts.spec)
+            entry.spec = true;
         if (opts.every !== undefined)
             entry.every = opts.every;
         if (opts.after?.length)
@@ -414,6 +416,51 @@ export class Plan {
         const at = node.items.findIndex((p) => String(p.key?.value ?? p.key) === 'title');
         node.items.splice(at + 1, 0, this.doc.createPair('public', value));
     }
+    /** Pose, remplace (nature) ou retire (null) le `screen:` d'un lot existant ; exige `visible`, comme `add`. */
+    setScreen(ref, screen) {
+        this.writable();
+        if (ref.includes('/'))
+            throw new RafError(`l'écran se pose sur un lot, pas une sous-tâche : ${ref}`);
+        const node = this.lotNode(ref);
+        if (screen === null) {
+            node.delete('screen');
+            return;
+        }
+        if (!SCREENS.includes(screen))
+            throw new RafError(`screen inconnu : ${String(screen)} (${SCREENS.join(', ')}, none)`);
+        if (this.lot(ref).visible !== true)
+            throw new RafError(`${ref} n'est pas visible : un écran est un changement visible (raf add --visible)`);
+        if (node.has('screen')) {
+            node.set('screen', screen);
+            return;
+        }
+        const keys = node.items.map((p) => String(p.key?.value ?? p.key));
+        node.items.splice(keys.indexOf('visible') + 1, 0, this.doc.createPair('screen', screen));
+    }
+    /** Pose (true) ou retire (false) le `spec:` d'un lot existant ; `screen:` l'implique, donc on ne retire pas la spec d'un lot à écran. Renvoie false quand `screen:` rendait la pose sans objet. */
+    setSpec(ref, on) {
+        this.writable();
+        if (ref.includes('/'))
+            throw new RafError(`la spec se pose sur un lot, pas une sous-tâche : ${ref}`);
+        const node = this.lotNode(ref);
+        if (this.lot(ref).screen) {
+            if (!on)
+                throw new RafError(`${ref} a screen: — retirer d'abord screen: (raf screen ${ref} none), l'écran implique la spec`);
+            return false;
+        }
+        if (!on) {
+            node.delete('spec');
+            return true;
+        }
+        if (node.has('spec')) {
+            node.set('spec', true);
+            return true;
+        }
+        const keys = node.items.map((p) => String(p.key?.value ?? p.key));
+        const at = Math.max(...['screen', 'visible', 'quickwin', 'estimate'].map((k) => keys.indexOf(k)));
+        node.items.splice(at + 1, 0, this.doc.createPair('spec', true));
+        return true;
+    }
     /** Un lot récurrent a été refait : `last` passe à aujourd'hui, avec une note si `text` est donné. */
     did(ref, today, text) {
         this.writable();
@@ -483,6 +530,8 @@ function foreignLots(raw, format) {
             quickwin: pick('quickwin'),
             visible: pick('visible'),
             screen: pick('screen'),
+            // Le `spec:` d'un plan tenu par un autre outil n'est à nous que s'il est mappé, et seul `true` compte : ailleurs c'est souvent un chemin de document (L198).
+            spec: format.fields.spec && pick('spec') === true ? true : undefined,
             public: pick('public'),
             every: pick('every'),
             last: day('last'),
@@ -539,6 +588,13 @@ function normalizeLot(raw, problems = []) {
         if (screen && raw.visible !== true)
             problems.push(`screen « ${screen} » sans visible : un écran est un changement visible`);
     }
+    let spec;
+    if (raw.spec != null) {
+        if (raw.spec === true)
+            spec = true;
+        else if (raw.spec !== false)
+            problems.push(`spec : true ou false attendu (reçu « ${String(raw.spec)} »)`);
+    }
     return {
         id: String(raw.id),
         title: String(raw.title ?? ''),
@@ -547,6 +603,7 @@ function normalizeLot(raw, problems = []) {
         quickwin: raw.quickwin === true,
         visible: raw.visible === true,
         ...(screen ? { screen } : {}),
+        ...(spec ? { spec } : {}),
         ...(typeof raw.public === 'string' && raw.public.trim() !== '' ? { public: raw.public.trim() } : {}),
         ...(Number.isInteger(raw.every) && raw.every > 0 ? { every: raw.every } : {}),
         ...(last ? { last } : {}),