@sylad/cadence 1.8.0 → 1.9.0

package/dist/plan.js

@@ -6,7 +6,18 @@ export const STATUSES = ['todo', 'doing', 'done', 'dropped'];
 export const GATE_INVALID = 'gate invalide : count: entier ≥ 1 et un critère spec: true ou screen: page attendus';
 export class RafError extends Error {
 }
-export const FIELDS = ['id', 'title', 'status', 'estimate', 'quickwin', 'visible', 'screen', 'spec', 'public', 'every', 'last', 'after', 'created', 'started', 'finished', 'notes', 'repos', 'parent', 'gate'];
+/** Un nom de ressource partagée (L251) : un mot de lettres minuscules, chiffres, « - » et « _ ». */
+export const RESOURCE_NAME = /^[a-z0-9_-]+$/;
+export const RESOURCES_BAD_LIST = 'doit être une liste de noms de ressources';
+export const invalidResource = (name) => `ressource invalide : ${name === '' ? '(vide)' : name} (lettres minuscules, chiffres, - et _)`;
+/** Les noms de ressources de `--uses` ou de `raf uses` : chacun valide (`RafError` sinon), sans doublon, dans l'ordre donné. */
+export function cleanUses(names) {
+    for (const n of names)
+        if (!RESOURCE_NAME.test(n))
+            throw new RafError(invalidResource(n));
+    return [...new Set(names)];
+}
+export const FIELDS = ['id', 'title', 'status', 'estimate', 'quickwin', 'visible', 'screen', 'spec', 'public', 'every', 'last', 'after', 'created', 'started', 'finished', 'notes', 'repos', 'parent', 'gate', 'goal'];
 /** Nature de l'écran d'un lot visible : nouvelle page, nouveau composant, parcours modifié. */
 export const SCREENS = ['page', 'component', 'journey'];
 export function isOpen(status) {
@@ -238,8 +249,8 @@ export class Plan {
         return this.enableGate('reviewSince', today);
     }
     /** `commit` : sha du dernier commit compté du lot (le plan ne lit pas git), null s'il n'en a aucun. */
-    recordReview(lotId, verdict, today, commit, repos) {
-        this.recordVerdict('review', 'la revue de code', lotId, { date: today, verdict, commit, ...(repos && Object.keys(repos).length ? { repos } : {}) });
+    recordReview(lotId, verdict, today, commit, repos, reporte) {
+        this.recordVerdict('review', 'la revue de code', lotId, { date: today, verdict, commit, ...(repos && Object.keys(repos).length ? { repos } : {}), ...(reporte ? { reporte } : {}) });
     }
     enableGate(key, today) {
         this.writable();
@@ -326,11 +337,15 @@ export class Plan {
             entry.every = opts.every;
         if (opts.after?.length)
             entry.after = opts.after;
+        if (opts.uses?.length)
+            entry.uses = cleanUses(opts.uses);
         entry.created = today;
         const node = this.doc.createNode(entry);
-        const after = node.get('after');
-        if (isSeq(after))
-            after.flow = true;
+        for (const key of ['after', 'uses']) {
+            const seq = node.get(key);
+            if (isSeq(seq))
+                seq.flow = true;
+        }
         this.doc.get('lots').add(node);
         return id;
     }
@@ -341,6 +356,28 @@ export class Plan {
         node.flow = true;
         this.lotNode(lotId).set('repos', node);
     }
+    /** Remplace les ressources partagées d'un lot de tout statut (clé `uses:` en flow, avant `created:`) ; sans nom, retire la clé. Jamais sur une sous-tâche. */
+    setUses(ref, names) {
+        this.writable();
+        if (ref.includes('/'))
+            throw new RafError(`uses se pose sur un lot, pas sur une sous-tâche : ${ref}`);
+        const node = this.lotNode(ref);
+        const uses = cleanUses(names);
+        if (uses.length === 0) {
+            node.delete('uses');
+            return;
+        }
+        const list = this.doc.createNode(uses);
+        list.flow = true;
+        if (node.has('uses')) {
+            node.set('uses', list);
+            return;
+        }
+        const keys = node.items.map((p) => String(p.key?.value ?? p.key));
+        const created = keys.indexOf('created');
+        const after = keys.indexOf('after');
+        node.items.splice(created >= 0 ? created : after >= 0 ? after + 1 : keys.length, 0, this.doc.createPair('uses', list));
+    }
     addTask(lotId, title) {
         this.writable();
         const lot = this.lotNode(lotId);
@@ -421,6 +458,21 @@ export class Plan {
         node.delete('started');
         this.note(ref, reason.trim() ? `remis en attente : ${reason.trim()}` : 'remis en attente', today);
     }
+    /** Remplace le titre d'un lot, de tout statut, et note l'ancien titre ; refuse un titre vide ou identique. */
+    setTitle(ref, text, today) {
+        this.writable();
+        if (ref.includes('/'))
+            throw new RafError(`raf title se pose sur un lot, pas une sous-tâche : ${ref}`);
+        const title = text.trim();
+        if (title === '')
+            throw new RafError('titre vide — raf title <id> "nouveau titre"');
+        const node = this.lotNode(ref);
+        const old = String(node.get('title') ?? '');
+        if (old === title)
+            throw new RafError(`${ref} porte déjà ce titre`);
+        node.set('title', title);
+        this.note(ref, `titre remplacé : « ${old} »`, today);
+    }
     /** Pose, remplace (texte) ou efface (null) le titre public d'un lot ; la clé suit `title`. */
     setPublic(ref, text) {
         this.writable();
@@ -460,6 +512,27 @@ export class Plan {
         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 `visible:` d'un lot existant ; retirer est refusé tant que le lot a un `screen:` (un écran est un changement visible). */
+    setVisible(ref, on) {
+        this.writable();
+        if (ref.includes('/'))
+            throw new RafError(`visible se pose sur un lot, pas une sous-tâche : ${ref}`);
+        const node = this.lotNode(ref);
+        const lot = this.lot(ref);
+        if (!on) {
+            if (lot.screen)
+                throw new RafError(`${ref} a screen: ${lot.screen} — retirer d'abord screen: (raf screen ${ref} none), un écran est un changement visible`);
+            node.delete('visible');
+            return;
+        }
+        if (node.has('visible')) {
+            node.set('visible', true);
+            return;
+        }
+        const keys = node.items.map((p) => String(p.key?.value ?? p.key));
+        const at = Math.max(...['quickwin', 'estimate', 'status'].map((k) => keys.indexOf(k)));
+        node.items.splice(at + 1, 0, this.doc.createPair('visible', true));
+    }
     /** Pose (true) ou retire (false) le `spec:` d'un lot existant ; `screen: page` l'implique, donc on ne retire pas la spec d'un lot à page (`component` et `journey` suivent le chemin ordinaire depuis L209 : leur `spec: true` est la spec back). Renvoie false quand `screen: page` rendait la pose sans objet. */
     setSpec(ref, on) {
         this.writable();
@@ -565,6 +638,7 @@ function foreignLots(raw, format) {
             notes: typeof notes === 'string' ? [{ text: notes }] : notes,
             repos: pick('repos'),
             gate: pick('gate'),
+            goal: pick('goal'),
         }, problems);
         const parent = pick('parent');
         return { lot, parent: parent == null ? undefined : String(parent) };
@@ -622,6 +696,13 @@ function normalizeLot(raw, problems = []) {
     };
     const after = raw.after == null ? [] : Array.isArray(raw.after) ? raw.after.map(String) : [String(raw.after)];
     const last = asDay('last');
+    let uses;
+    if (raw.uses != null) {
+        if (Array.isArray(raw.uses) && raw.uses.every((n) => typeof n === 'string' && RESOURCE_NAME.test(n)))
+            uses = [...new Set(raw.uses)];
+        else
+            problems.push(`uses ${RESOURCES_BAD_LIST}`);
+    }
     let screen;
     if (raw.screen != null) {
         if (SCREENS.includes(raw.screen))
@@ -650,9 +731,11 @@ function normalizeLot(raw, problems = []) {
         ...(spec ? { spec } : {}),
         ...(gate ? { gate } : {}),
         ...(typeof raw.public === 'string' && raw.public.trim() !== '' ? { public: raw.public.trim() } : {}),
+        ...(typeof raw.goal === 'string' && raw.goal.trim() !== '' ? { goal: raw.goal.trim() } : {}),
         ...(Number.isInteger(raw.every) && raw.every > 0 ? { every: raw.every } : {}),
         ...(last ? { last } : {}),
         after,
+        ...(uses?.length ? { uses } : {}),
         created: asDay('created'),
         started: asDay('started'),
         finished: asDay('finished'),
@@ -705,5 +788,8 @@ function asVerdict(raw) {
         if (repos.length)
             verdict.repos = Object.fromEntries(repos);
     }
+    const r = v.reporte;
+    if (r && typeof r === 'object' && !Array.isArray(r) && r.de != null && r.vers != null)
+        verdict.reporte = { de: String(r.de), vers: String(r.vers), patchId: String(r.patchId ?? '') };
     return verdict;
 }

package/dist/ready-free.js

@@ -0,0 +1,109 @@
+import { dirname, resolve } from 'node:path';
+import { nextUp } from './audit.js';
+import { planLoader } from './config.js';
+import { gitRoot } from './git.js';
+import { findProjects, readDepth } from './lead.js';
+import { decisionPending } from './orchestrate/continue.js';
+import { liveWaves } from './orchestrate/registry.js';
+import { readResources } from './resources.js';
+import { lotFinished, RunStore } from './orchestrate/state.js';
+/** Le dépôt d'un projet : sa racine git, ou son chemin absolu hors de git. */
+const repoOf = (dir) => gitRoot(dir) ?? resolve(dir);
+/**
+ * Un lot se reconnaît à son dépôt et à son id, pas au nom du projet : une vague lancée depuis un autre dossier l'enregistre sous `basename(dir)`
+ * (le tour d'un dossier parent le nomme par son chemin, `grp/alpha`), et deux projets de même nom de deux dossiers sont deux dépôts.
+ */
+const lotAt = (repo, lot) => `${repo}:${lot}`;
+/**
+ * Les projets qui partagent les ressources de `dir` : ceux que trouve `findProjects` sous le dossier du cadence.yaml qui déclare ses `resources:`
+ * (le plus proche en remontant, voir `readResources`), sur la profondeur `depth:` de ce fichier (un niveau à défaut) : `P/x` et `P/grp/alpha`
+ * partagent le banc que déclare `P/cadence.yaml` (`depth: 2`), d'où qu'on les interroge. Sans ressource déclarée, ou avec un cadence.yaml
+ * illisible ou une `depth:` invalide (que leur ligne de tour signale), ce sont les projets du dossier parent, sur un niveau.
+ */
+function sharingProjects(dir) {
+    try {
+        const { file, names } = readResources(repoOf(dir));
+        if (names.length)
+            return findProjects(dirname(file), readDepth(dirname(file)));
+    }
+    catch {
+        // cadence.yaml illisible ou depth: invalide
+    }
+    return findProjects(dirname(dir));
+}
+const plansOf = (dir) => planLoader(repoOf(dir))().lots();
+/**
+ * Les ressources prises à cet instant : celles des lots `doing` des projets `dirs` et de ceux qui partagent leurs ressources (`sharingProjects` : lancé depuis l'un d'eux,
+ * on voit aussi les autres), celles des lots non finis des vagues vivantes (un lot de vague n'est `doing` dans le plan qu'une fois sa session partie)
+ * et celles des lots `held` (le tirage d'une vague qui part). Avec leurs lots (`dépôt:lot`, voir `lotAt`), qui ne sont pas à proposer.
+ */
+function taken(dirs, home, held) {
+    const resources = new Set();
+    const running = new Set();
+    for (const dir of new Set([...dirs, ...dirs.flatMap(sharingProjects)])) {
+        try {
+            for (const l of nextUp(plansOf(dir)).doing)
+                for (const r of l.uses ?? [])
+                    resources.add(r);
+        }
+        catch {
+            // plan illisible : sa ligne de tour le dit, il ne tient aucune ressource connue
+        }
+    }
+    for (const w of liveWaves(home)) {
+        let live;
+        try {
+            live = RunStore.find(w.cwd, w.wave)?.lots().filter((l) => !lotFinished(l)) ?? [];
+        }
+        catch {
+            continue; // état de vague illisible : la vague ne tient aucune ressource connue
+        }
+        held = [...held, ...live];
+    }
+    for (const s of held) {
+        running.add(lotAt(repoOf(s.repo), s.lot));
+        try {
+            for (const r of plansOf(s.repo).find((l) => l.id === s.lot)?.uses ?? [])
+                resources.add(r);
+        }
+        catch {
+            // plan illisible : aucune ressource connue
+        }
+    }
+    return { resources, running };
+}
+/**
+ * Pour chaque dossier de projet de `dirs`, ses lots prêts (comme `nextUp`, hors « à décider » et hors lots d'une vague vivante) dont aucune ressource
+ * n'est prise par un lot `doing` d'un des projets (ou de ceux qui partagent leurs ressources, voir `sharingProjects`) ni par une vague vivante de `home` ni par les lots `held` d'une vague qui part. Un lot sans `uses:` n'en tient aucune : il est libre.
+ * Les projets sans lot libre n'ont pas d'entrée (clé : le dossier) ; un plan illisible est sauté.
+ */
+export function readyFree(dirs, home, held = []) {
+    const { resources, running } = taken(dirs, home, held);
+    const out = new Map();
+    for (const dir of dirs) {
+        let ready;
+        try {
+            ready = nextUp(plansOf(dir)).ready;
+        }
+        catch {
+            continue;
+        }
+        const repo = repoOf(dir);
+        const free = ready
+            .filter((l) => !decisionPending(l) && !running.has(lotAt(repo, l.id)) && !(l.uses ?? []).some((r) => resources.has(r)))
+            .map((l) => ({ id: l.id, title: l.title, ...(l.uses?.length ? { uses: l.uses } : {}) }));
+        if (free.length)
+            out.set(dir, free);
+    }
+    return out;
+}
+/** Lots listés par projet dans la ligne ; au-delà, « projet +K » (le --json donne tout). */
+const FREE_SHOWN = 3;
+/** « prêts, ressources libres : projet:L3 titre (banc) · … », au plus FREE_SHOWN lots par projet puis « projet +K », ou null quand aucun lot prêt n'est libre. */
+export function freeLine(entries, titleMax) {
+    const items = entries.flatMap((e) => [
+        ...e.free.slice(0, FREE_SHOWN).map((l) => `${e.project}:${l.id} ${l.title.length <= titleMax ? l.title : `${l.title.slice(0, titleMax - 1)}…`}${l.uses?.length ? ` (${l.uses.join(', ')})` : ''}`),
+        ...(e.free.length > FREE_SHOWN ? [`${e.project} +${e.free.length - FREE_SHOWN}`] : []),
+    ]);
+    return items.length ? `prêts, ressources libres : ${items.join(' · ')}` : null;
+}

package/dist/ref/add.js

@@ -0,0 +1,116 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
+import { RafError } from '../plan.js';
+import { attachRegions, citedPages, indexText } from './figures.js';
+import { DPI, extractImages, imageFile, imageRegions, listImages, pageCount, renderPages, renderThumbnails, textLayout } from './pdf.js';
+import { readDocument, writeDocument } from './store.js';
+import { requireTools } from './tools.js';
+/** Sans `--sections`, un document de cette taille ou plus petit est rendu en entier ; au-delà, seul l'index est construit. */
+export const WHOLE_DOCUMENT_MAX = 30;
+/** Une page de moins de 20 caractères de texte est tenue pour scannée (recette du skill norme-etude). */
+const SCANNED_MAX_CHARS = 20;
+/** [1, 2, 3, 6] → « 1-3, 6 ». */
+function ranges(pages) {
+    const out = [];
+    for (let i = 0; i < pages.length;) {
+        let j = i;
+        while (j + 1 < pages.length && pages[j + 1] === pages[j] + 1)
+            j++;
+        out.push(j > i ? `${pages[i]}-${pages[j]}` : String(pages[i]));
+        i = j + 1;
+    }
+    return out.join(', ');
+}
+/** `3-5,9` → [3, 4, 5, 9] (pages du PDF, 1 = première), sans doublon, dans l'ordre. */
+export function parseSections(text, pages) {
+    const out = new Set();
+    for (const part of text.split(',')) {
+        const m = /^\s*(\d+)(?:\s*-\s*(\d+))?\s*$/.exec(part);
+        if (!m)
+            throw new RafError(`ref : --sections invalide : « ${part.trim()} » (attendu : 3, 3-5 ou 3-5,9)`);
+        const from = Number(m[1]);
+        const to = m[2] === undefined ? from : Number(m[2]);
+        if (from < 1 || to < from)
+            throw new RafError(`ref : --sections invalide : « ${part.trim()} » (pages de 1 à ${pages}, début avant fin)`);
+        if (to > pages)
+            throw new RafError(`ref : --sections : page ${to} demandée, le document a ${pages} pages`);
+        for (let n = from; n <= to; n++)
+            out.add(n);
+    }
+    return [...out].sort((a, b) => a - b);
+}
+const slugOf = (file) => basename(file, extname(file)).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+export const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+/** `cadence ref add` : enregistre un PDF, rend les pages visées, garde le texte positionné et les images, construit l'index des figures. */
+export function add(o) {
+    // Les outils d'abord : sans eux, rien n'est lu ni écrit.
+    const tools = requireTools(o.env);
+    const file = resolve(o.cwd, o.document);
+    if (!existsSync(file) || !statSync(file).isFile())
+        throw new RafError(`ref : document introuvable : ${file}`);
+    const slug = o.slug ?? slugOf(file);
+    if (!SLUG.test(slug))
+        throw new RafError(`ref : slug invalide : « ${slug} » (lettres minuscules, chiffres et tirets ; --slug pour le choisir)`);
+    const total = pageCount(tools, file);
+    const wanted = o.sections === undefined ? (total <= WHOLE_DOCUMENT_MAX ? Array.from({ length: total }, (_, i) => i + 1) : []) : parseSections(o.sections, total);
+    const sha256 = createHash('sha256').update(readFileSync(file)).digest('hex');
+    const docDir = join(o.refsDir(), slug);
+    const before = readDocument(docDir);
+    if (before && before.sha256 !== sha256) {
+        throw new RafError(`ref : le slug « ${slug} » est déjà pris par un autre document (${before.source}, empreinte ${before.sha256.slice(0, 12)}) : choisir un autre nom avec --slug`);
+    }
+    const text = textLayout(tools, file);
+    const listed = listImages(tools, file);
+    const index = indexText(text, new Set(listed.map((i) => i.page)));
+    // pages à rendre : celles visées, celles déjà rendues par un appel précédent du même document, et celles des figures qu'elles citent
+    const keep = new Set(before?.pages.filter((p) => p.rendered).map((p) => p.n));
+    const visees = new Set([...wanted, ...keep]);
+    const rendered = new Set([...visees, ...citedPages(index, visees)]);
+    const ordered = [...rendered].sort((a, b) => a - b);
+    renderPages(tools, file, ordered, join(docDir, 'pages'));
+    renderThumbnails(tools, file, total, join(docDir, 'thumbs'));
+    const images = [];
+    const placed = [];
+    const regions = new Map();
+    for (const n of ordered) {
+        if (!listed.some((i) => i.page === n))
+            continue;
+        extractImages(tools, file, n, join(docDir, 'images'));
+        regions.set(n, imageRegions(tools, file, n));
+    }
+    for (const img of listed) {
+        const box = regions.get(img.page)?.[img.rank - 1];
+        const stored = box && rendered.has(img.page) ? { page: img.page, file: `images/${imageFile(img.page, img.slot)}`, x: box.x, y: box.y, l: box.l, h: box.h } : { page: img.page, file: null, x: null, y: null, l: null, h: null };
+        images.push(stored);
+        placed.push({ page: img.page, box: stored.x === null ? null : { x: stored.x, y: stored.y, l: stored.l, h: stored.h } });
+    }
+    attachRegions(index, placed);
+    const pages = text.map((p) => ({ ...p, rendered: rendered.has(p.n) }));
+    const doc = {
+        slug,
+        source: file,
+        sha256,
+        added: before?.added ?? o.now.toISOString(),
+        dpi: DPI,
+        sections: o.sections ?? before?.sections ?? null,
+        tools,
+        pages,
+        images,
+        figures: index.figures,
+        unresolved: index.unresolved,
+    };
+    writeDocument(docDir, doc);
+    o.out(`${slug} : ${basename(file)}`);
+    o.out(`pages : ${total}`);
+    const sansTexte = text.filter((p) => p.lines.reduce((n, l) => n + l.text.trim().length, 0) < SCANNED_MAX_CHARS).map((p) => p.n);
+    if (sansTexte.length > 0)
+        o.out(`pages sans texte : ${sansTexte.length} (${ranges(sansTexte)}) — scannées ou faites d'images : l'index n'en dit rien, parcourir ${join(docDir, 'thumbs')} pour choisir les pages à rendre (--sections)`);
+    o.out(`rendues : ${ordered.length}${ordered.length > 0 ? ` (${ordered.join(', ')})` : ''}`);
+    o.out(`images : ${images.length}`);
+    o.out(`figures : ${index.figures.length}`);
+    o.out(`liens non résolus : ${index.unresolved.length}`);
+    o.out(`dossier : ${docDir}`);
+    if (ordered.length === 0)
+        o.out(`aucune page rendue (grand document : seul l'index est construit) — cadence ref add ${o.document} --slug ${slug} --sections 3-5 pour rendre des pages`);
+}