@sylad/cadence 0.2.0 → 0.6.0

package/dist/deliver.js

@@ -1,7 +1,7 @@
 import { execFileSync, spawnSync } from 'node:child_process';
 import { parse } from 'yaml';
-import { headSha, isAncestor, onRemote, readCommits, repoStatus } from './git.js';
-import { extractRefs, RafError } from './plan.js';
+import { headSha, isAncestor, onRemote, readCommits, repoStatus, resolveCommit } from './git.js';
+import { RafError } from './plan.js';
 import { appendDelivery, lastDelivery, lockAlive, lockPath, readLock, releaseLock, removeStaleLock, writeLock } from './state.js';
 const POLL_CI = 15_000;
 const CI_APPEAR = 300_000;
@@ -23,6 +23,14 @@ export function parseDeliverConfig(text, file) {
         throw new RafError(`${file} : clé deliver absente`);
     const cfg = d;
     const bad = (what) => new RafError(`${file} : deliver.${what}`);
+    let script;
+    if (cfg.script !== undefined) {
+        if (typeof cfg.script !== 'string' || !cfg.script.trim())
+            throw bad('script : commande non vide attendue');
+        if (cfg.ci !== undefined || cfg.deploy !== undefined)
+            throw bad('script remplace ci et deploy : garder l\'un ou les autres');
+        script = cfg.script.trim();
+    }
     let ci = 'none';
     if (cfg.ci === 'github' || cfg.ci === 'none')
         ci = cfg.ci;
@@ -33,6 +41,8 @@ export function parseDeliverConfig(text, file) {
     }
     else if (cfg.ci !== undefined)
         throw bad('ci : attendu github, none ou { command: "…" }');
+    if (cfg.allowDirty !== undefined && typeof cfg.allowDirty !== 'boolean')
+        throw bad('allowDirty : true ou false attendu');
     const seconds = (key, dflt) => {
         const v = cfg[key];
         if (v === undefined)
@@ -45,7 +55,8 @@ export function parseDeliverConfig(text, file) {
     if (!Array.isArray(deploy) || !deploy.every((c) => typeof c === 'string' && c.trim()))
         throw bad('deploy : liste de commandes non vides attendue');
     const verify = cfg.verify ?? [];
-    if (!Array.isArray(verify) || verify.length === 0) {
+    // Avec un script de projet, les contrôles métier sont les siens : ceux de cadence deviennent facultatifs.
+    if (!Array.isArray(verify) || (verify.length === 0 && script === undefined)) {
         throw bad('verify : au moins une vérification (une livraison se prouve par son effet)');
     }
     const checks = verify.map((v, i) => {
@@ -68,7 +79,16 @@ export function parseDeliverConfig(text, file) {
             throw bad(`${where}.contains : texte attendu`);
         return { url, ...(status === undefined ? {} : { status: status }), ...(contains === undefined ? {} : { contains }) };
     });
-    return { ci, ciTimeout: seconds('ciTimeout', 1800), deploy: deploy, verify: checks, verifyTimeout: seconds('verifyTimeout', 300), deployTimeout: seconds('deployTimeout', 1800) };
+    return {
+        ci,
+        ...(script === undefined ? {} : { script }),
+        ...(cfg.allowDirty ? { allowDirty: true } : {}),
+        ciTimeout: seconds('ciTimeout', 1800),
+        deploy: deploy,
+        verify: checks,
+        verifyTimeout: seconds('verifyTimeout', 300),
+        deployTimeout: seconds('deployTimeout', 1800),
+    };
 }
 /** Dépendances réelles : sh, gh, fetch, horloge. */
 export function realDeps(root) {
@@ -119,6 +139,10 @@ export function realDeps(root) {
 function substitute(text, sha) {
     return text.replaceAll('${SHA}', sha).replaceAll('${SHORT}', sha.slice(0, 7));
 }
+/** Argument rendu tel quel au script par sh, quels que soient ses espaces, guillemets ou jokers. */
+function shellQuote(arg) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+}
 function describeCheck(c, sha) {
     if (c.command !== undefined)
         return c.command;
@@ -131,12 +155,19 @@ export async function deliver(ctx, deps) {
         err(`deliver : ${msg}`);
         return 2;
     };
-    const sha = headSha(ctx.root);
+    const head0 = headSha(ctx.root);
+    const sha = ctx.sha === undefined ? head0 : resolveCommit(ctx.root, ctx.sha);
     if (!sha)
-        return refuse('aucun commit à livrer');
+        return refuse(ctx.sha === undefined ? 'aucun commit à livrer' : `--sha ${ctx.sha} : commit introuvable`);
+    if (ctx.args.length && config.script === undefined) {
+        return refuse('des arguments ne se passent qu\'à un script de projet (deliver.script dans cadence.yaml)');
+    }
+    const script = config.script === undefined ? null : [config.script, ...ctx.args.map(shellQuote)].join(' ');
     const repo = repoStatus(ctx.root);
-    if (repo.dirty)
+    if (repo.dirty && !config.allowDirty)
         return refuse(`${repo.dirty} fichier(s) suivi(s) modifié(s) : commiter et pousser d'abord`);
+    if (repo.dirty)
+        err(`deliver : ${repo.dirty} fichier(s) suivi(s) modifié(s) : non livré(s), seul ${sha.slice(0, 7)} l'est (allowDirty)`);
     if (!onRemote(ctx.root, sha))
         return refuse(`${sha.slice(0, 7)} non poussé : la CI n'a rien construit (git push)`);
     const lock = readLock(ctx.state);
@@ -149,16 +180,25 @@ export async function deliver(ctx, deps) {
         if (why)
             return refuse(`ci: github exige gh authentifié — ${why}`);
     }
-    const branch = repo.branch ?? 'HEAD détachée';
-    const env = { CADENCE_SHA: sha, CADENCE_SHORT: sha.slice(0, 7), CADENCE_BRANCH: repo.branch ?? '' };
+    // Un sha choisi n'est pas forcément sur la branche courante : ne pas lui en prêter une.
+    const atHead = sha === head0;
+    const branch = atHead ? (repo.branch ?? 'HEAD détachée') : 'sha choisi, antérieur ou étranger à la tête';
+    const env = { CADENCE_SHA: sha, CADENCE_SHORT: sha.slice(0, 7), CADENCE_BRANCH: atHead ? (repo.branch ?? '') : '' };
     if (ctx.dryRun) {
         out(`Livraison de ${env.CADENCE_SHORT} (${branch}) — simulation, rien n'est exécuté`);
-        out(`  CI : ${typeof config.ci === 'string' ? config.ci : config.ci.command}${config.ci === 'none' ? '' : ` (délai ${config.ciTimeout} s)`}`);
-        out('  Déploiement :');
-        if (config.deploy.length === 0)
-            out('    (aucune commande)');
-        config.deploy.forEach((c, i) => out(`    ${i + 1}. ${c}`));
-        out(`  Vérifications (réessayées pendant ${config.verifyTimeout} s) :`);
+        if (script !== null) {
+            out(`  Script du projet : ${script}`);
+            out(`    (CI, déploiement et contrôles métier sont les siens ; délai ${config.deployTimeout} s)`);
+        }
+        else {
+            out(`  CI : ${typeof config.ci === 'string' ? config.ci : config.ci.command}${config.ci === 'none' ? '' : ` (délai ${config.ciTimeout} s)`}`);
+            out('  Déploiement :');
+            if (config.deploy.length === 0)
+                out('    (aucune commande)');
+            config.deploy.forEach((c, i) => out(`    ${i + 1}. ${c}`));
+        }
+        if (config.verify.length)
+            out(`  Vérifications (réessayées pendant ${config.verifyTimeout} s) :`);
         config.verify.forEach((c, i) => out(`    ${i + 1}. ${describeCheck(c, sha)}`));
         out(`  Variables : ${Object.entries(env).map(([k, v]) => `${k}=${v}`).join(' ')}`);
         return 0;
@@ -175,21 +215,37 @@ export async function deliver(ctx, deps) {
             return 1;
         };
         out(`Livraison de ${env.CADENCE_SHORT} (${branch})`);
-        const ci = await waitCi(ctx, deps, sha, env);
-        if (ci)
-            return fail(ci);
-        for (const [i, cmd] of config.deploy.entries()) {
-            out(`→ déploiement ${i + 1}/${config.deploy.length} : ${cmd}`);
-            const code = deps.exec(cmd, env, config.deployTimeout * 1000);
+        if (script !== null) {
+            out(`→ script du projet : ${script}`);
+            const code = deps.exec(script, env, config.deployTimeout * 1000);
             if (code !== 0)
-                return fail(`déploiement en échec (${codeText(code)}) : ${cmd}`);
+                return fail(`script de livraison en échec (${codeText(code)}) : ${script}`);
+        }
+        else {
+            const ci = await waitCi(ctx, deps, sha, env);
+            if (ci)
+                return fail(ci);
+            for (const [i, cmd] of config.deploy.entries()) {
+                out(`→ déploiement ${i + 1}/${config.deploy.length} : ${cmd}`);
+                const code = deps.exec(cmd, env, config.deployTimeout * 1000);
+                if (code !== 0)
+                    return fail(`déploiement en échec (${codeText(code)}) : ${cmd}`);
+            }
         }
         const failed = await verifyAll(ctx, deps, sha, env);
         if (failed)
             return fail(failed);
-        const delivered = deliveredLots(ctx, lastDelivery(ctx.state), sha);
-        appendDelivery(ctx.state, ctx.today, sha);
-        out(`✓ livré et vérifié : ${env.CADENCE_SHORT}`);
+        // Un script de projet peut commiter pendant la livraison (horodatage d'une entrée Nouveautés) :
+        // ce qu'il a livré est alors la nouvelle tête, pas le sha de départ.
+        const head = script === null || !atHead ? sha : (headSha(ctx.root) ?? sha);
+        const moved = head !== sha && isAncestor(ctx.root, sha, head);
+        const final = moved ? head : sha;
+        const delivered = deliveredLots(ctx, lastDelivery(ctx.state), final);
+        appendDelivery(ctx.state, ctx.today, final);
+        if (moved)
+            out(`✓ livré : ${final.slice(0, 7)} (tête déplacée par le script depuis ${env.CADENCE_SHORT})`);
+        else
+            out(`✓ livré${config.verify.length ? ' et vérifié' : ''} : ${env.CADENCE_SHORT}`);
         if (delivered)
             out(delivered);
         return 0;
@@ -278,9 +334,11 @@ async function verifyAll(ctx, deps, sha, env) {
             const reason = await tryCheck(c, deps, sha, env, deadline - deps.now());
             if (reason === null)
                 break;
-            if (deps.now() >= deadline)
+            const left = deadline - deps.now();
+            if (left <= 0)
                 return `vérification en échec après ${ctx.config.verifyTimeout} s : ${label} — ${reason}`;
-            await deps.sleep(POLL_VERIFY);
+            // jamais au-delà du délai : une commande tuée « à l'échéance » peut rendre la main un rien avant elle
+            await deps.sleep(Math.min(POLL_VERIFY, left));
         }
     }
     return null;
@@ -295,11 +353,11 @@ function deliveredLots(ctx, prev, sha) {
     const known = new Set(ctx.plan.lots().map((l) => l.id));
     const ids = new Set();
     for (const c of readCommits(ctx.root, { range: `${prev}..${sha}` })) {
-        for (const r of extractRefs(`${c.subject}\n${c.body}`, ctx.plan.prefix))
+        for (const r of ctx.plan.refs(`${c.subject}\n${c.body}`))
             if (known.has(r.lot))
                 ids.add(r.lot);
     }
     if (ids.size === 0)
         return null;
-    return `livré : ${[...ids].sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).join(', ')} — raf done si l'effet est celui attendu`;
+    return `livré : ${[...ids].sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).join(', ')} — ${ctx.plan.readonly ? "à fermer avec l'outil du projet" : 'raf done'} si l'effet est celui attendu`;
 }

package/dist/git.js

@@ -1,7 +1,8 @@
 import { execFileSync } from 'node:child_process';
 import { basename, dirname, resolve } from 'node:path';
 function git(cwd, args) {
-    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    // Le journal complet d'un gros dépôt dépasse le Mo par défaut : sans marge, il serait lu comme vide.
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 1024 * 1024 * 1024 });
 }
 export function gitRoot(cwd) {
     try {
@@ -60,6 +61,10 @@ function tryGit(cwd, args) {
 export function headSha(cwd) {
     return tryGit(cwd, ['rev-parse', '--verify', '-q', 'HEAD']);
 }
+/** Sha complet du commit que désigne `rev` (sha abrégé, branche, tag), null s'il n'existe pas. */
+export function resolveCommit(cwd, rev) {
+    return tryGit(cwd, ['rev-parse', '--verify', '-q', `${rev}^{commit}`]);
+}
 export function repoStatus(cwd) {
     const lines = git(cwd, ['status', '--porcelain']).split('\n').filter(Boolean);
     const untracked = lines.filter((l) => l.startsWith('??')).length;
@@ -89,3 +94,31 @@ export function gitCommonDir(cwd) {
 export function isAncestor(cwd, a, b) {
     return tryGit(cwd, ['merge-base', '--is-ancestor', a, b]) !== null;
 }
+/**
+ * Instant (ms), date d'auteur (conservée par rebase, amend, cherry-pick), du commit qui a ajouté chaque fichier
+ * de `dir` SOUS CE NOM (--no-renames : un renommage compte comme un ajout, l'historique antérieur n'est pas suivi),
+ * clé = chemin relatif à `dir`.
+ * Vide hors d'un dépôt git ; un fichier jamais commité en est absent.
+ */
+export function addedTimes(dir) {
+    const times = new Map();
+    let out;
+    try {
+        // quotepath=off + -z : noms accentués tels quels, sans guillemets ni échappement octal.
+        out = git(dir, ['-c', 'core.quotepath=off', 'log', '-z', '--diff-filter=A', '--no-renames', '--relative', '--name-only', `--format=${RECORD}%aI`, '--', '.']);
+    }
+    catch {
+        return times;
+    }
+    // Enregistrement = RECORD date \0 \n nom \0 nom \0 … ; le plus ancien ajout l'emporte.
+    for (const record of out.split(RECORD).filter(Boolean)) {
+        const [stamp, ...files] = record.split('\0');
+        const t = Date.parse(stamp);
+        for (const [i, f] of files.entries()) {
+            const name = i === 0 ? f.replace(/^\n/, '') : f;
+            if (name)
+                times.set(name, Math.min(t, times.get(name) ?? Infinity));
+        }
+    }
+    return times;
+}

package/dist/link.js

@@ -1,15 +1,15 @@
-import { extractRefs } from './plan.js';
 export function isMerge(c) {
     return /^Merge\b/.test(c.subject);
 }
-export function linkCommits(lots, commits, prefix) {
+/** `refs` lit les références d'un message : `plan.refs`. */
+export function linkCommits(lots, commits, refsOf) {
     const ids = new Set(lots.map((l) => l.id));
     const tasks = new Set(lots.flatMap((l) => l.tasks.map((t) => `${l.id}/${t.id}`)));
     const byLot = new Map();
     const orphans = [];
     const unknown = [];
     for (const c of commits) {
-        const refs = extractRefs(`${c.subject}\n${c.body}`, prefix);
+        const refs = refsOf(`${c.subject}\n${c.body}`);
         if (refs.length === 0) {
             if (!isMerge(c))
                 orphans.push(c);

package/dist/news.js

@@ -1,10 +1,20 @@
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { parse, stringify } from 'yaml';
-import { isDay } from './dates.js';
+import { isDay, toStamp } from './dates.js';
+import { addedTimes } from './git.js';
 import { RafError } from './plan.js';
+const CREATED_EMPTY = 'created vide — cadence news stamp';
+const CREATED = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2})?(?:Z|[+-]\d{2}:\d{2})?$/;
+const OFFSET = /(?:Z|[+-]\d{2}:\d{2})$/;
 const CAPTURE = /^[\w./-]+\.(?:png|jpe?g|webp|gif)$/i;
 const FRONT = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/** Bien formée ET réelle : Date.parse accepte le 30 février (et rend NaN pour 25:70). */
+function validStamp(s) {
+    const [y, mo, d, h, mi, sec = 0] = s.match(/\d+/g).slice(0, 6).map(Number);
+    const day = new Date(Date.UTC(y, mo - 1, d));
+    return (!Number.isNaN(Date.parse(s.replace(' ', 'T'))) && day.getUTCMonth() === mo - 1 && day.getUTCDate() === d && h < 24 && mi < 60 && sec < 60);
+}
 const list = (v) => (v == null ? [] : Array.isArray(v) ? v.map(String) : [String(v)]);
 export function parseEntry(file, text) {
     const entry = { file, slug: basename(file).replace(/\.md$/, ''), title: '', date: '', lots: [], captures: [], body: '', problems: [] };
@@ -23,6 +33,20 @@ export function parseEntry(file, text) {
     }
     entry.title = String(head.title ?? '').trim();
     entry.date = String(head.date ?? '');
+    if ('created' in head) {
+        const created = String(head.created ?? '').trim();
+        if (!created)
+            entry.problems.push(CREATED_EMPTY);
+        else if (!CREATED.test(created))
+            entry.problems.push(`created « ${created} » n'est pas une heure AAAA-MM-JJTHH:MM±hh:mm`);
+        // Sans fuseau, l'heure serait lue dans celui de la machine : l'ordre changerait entre le poste et la CI.
+        else if (!OFFSET.test(created))
+            entry.problems.push(`created « ${created} » sans fuseau : ajouter ±hh:mm ou Z`);
+        else if (!validStamp(created))
+            entry.problems.push(`created « ${created} » n'est pas une heure valide`);
+        else
+            entry.created = created.replace(' ', 'T');
+    }
     entry.lots = list(head.lots);
     entry.captures = list(head.captures);
     if (head.nocapture != null && String(head.nocapture).trim())
@@ -42,14 +66,29 @@ export function parseEntry(file, text) {
         entry.problems.push(`date « ${entry.date} » n'est pas une date AAAA-MM-JJ`);
     return entry;
 }
-/** Entrées du dossier, plus récentes d'abord (à date égale, par nom de fichier décroissant). */
-export function loadEntries(dir) {
+/**
+ * Entrées du dossier, plus récentes d'abord : par date, puis à date égale par instant de création
+ * (`created` de l'en-tête, sinon date d'auteur du commit qui a ajouté le fichier sous ce nom — un renommage
+ * compte comme un ajout — ; pas encore commité = le plus récent), puis par nom de fichier décroissant.
+ * `added` (historique git) n'est appelé que si une entrée n'a pas de `created`.
+ */
+export function loadEntries(dir, added = () => addedTimes(dir)) {
     if (!existsSync(dir))
         return [];
-    return readdirSync(dir, { withFileTypes: true })
+    const entries = readdirSync(dir, { withFileTypes: true })
         .filter((f) => f.isFile() && f.name.endsWith('.md') && f.name.toLowerCase() !== 'readme.md')
-        .map((f) => parseEntry(f.name, readFileSync(join(dir, f.name), 'utf8')))
-        .sort((a, b) => (a.date === b.date ? b.file.localeCompare(a.file) : b.date.localeCompare(a.date)));
+        .map((f) => parseEntry(f.name, readFileSync(join(dir, f.name), 'utf8')));
+    const history = entries.some((e) => !e.created) ? added() : new Map();
+    const created = (e) => (e.created ? Date.parse(e.created) : history.get(e.file) ?? Infinity);
+    return entries.sort((a, b) => {
+        if (a.date !== b.date)
+            return b.date.localeCompare(a.date);
+        const ta = created(a);
+        const tb = created(b);
+        if (ta !== tb)
+            return ta < tb ? 1 : -1;
+        return b.file.localeCompare(a.file);
+    });
 }
 export function newsIssues(lots, entries, dir) {
     const issues = [];
@@ -66,6 +105,9 @@ export function newsIssues(lots, entries, dir) {
             if (!existsSync(path) || !statSync(path).isFile())
                 issues.push({ kind: 'missing-capture', message: `${e.file} : capture absente ${c}` });
         }
+        if (e.problems.length === 0 && !e.created) {
+            issues.push({ kind: 'no-time', message: `${e.file} sans heure de création (created: AAAA-MM-JJTHH:MM±hh:mm) — cadence news stamp` });
+        }
         if (e.problems.length === 0 && e.captures.length === 0 && !e.nocapture) {
             issues.push({ kind: 'no-capture', message: `${e.file} sans capture (ou « nocapture: raison »)` });
         }
@@ -87,16 +129,47 @@ export function slugify(title) {
         .slice(0, 60)
         .replace(/-+$/, '') || 'entree');
 }
-/** Crée le squelette d'une entrée ; refuse d'écraser un fichier existant. */
-export function newEntry(dir, lots, rawTitle, today) {
+/** Crée le squelette d'une entrée, horodatée de `now` ; refuse d'écraser un fichier existant. */
+export function newEntry(dir, lots, rawTitle, today, now) {
     const title = rawTitle.replace(/\s+/g, ' ').trim(); // un saut de ligne casserait l'en-tête
     const path = join(dir, `${today}-${slugify(title)}.md`);
     if (existsSync(path))
         throw new RafError(`${path} existe déjà`);
     mkdirSync(dir, { recursive: true });
-    writeFileSync(path, `---\ntitle: ${stringify(title).trimEnd()}\ndate: ${today}\nlots: [${lots.join(', ')}]\ncaptures: []\n# nocapture: raison, quand une capture n'a pas de sens\n---\nCe qui change pour l'utilisateur.\n`);
+    writeFileSync(path, `---\ntitle: ${stringify(title).trimEnd()}\ndate: ${today}\ncreated: ${toStamp(now)}\nlots: [${lots.join(', ')}]\ncaptures: []\n# nocapture: raison, quand une capture n'a pas de sens\n---\nCe qui change pour l'utilisateur.\n`);
     return path;
 }
+/**
+ * Migration : écrit `created:` dans les entrées lisibles qui n'en ont pas (ou l'ont vide), d'après la date
+ * d'auteur du commit qui a ajouté le fichier sous ce nom — un renommage n'est pas suivi — (`now` s'il n'est pas
+ * encore commité). Le reste du fichier est laissé tel quel.
+ */
+export function stampEntries(dir, now) {
+    let history;
+    const added = () => (history ??= addedTimes(dir)); // un seul git log, et seulement s'il sert
+    const done = [];
+    for (const e of loadEntries(dir, added)) {
+        // Seule une clé created vide est réparée ici ; une heure fausse reste à corriger à la main.
+        if (e.created || !e.problems.every((p) => p === CREATED_EMPTY))
+            continue;
+        const created = toStamp(new Date(added().get(e.file) ?? now.getTime()));
+        const path = join(dir, e.file);
+        const text = readFileSync(path, 'utf8');
+        const lines = text.split('\n');
+        const end = lines.findIndex((l, i) => i > 0 && l.trimEnd() === '---');
+        const key = (name) => lines.findIndex((l, i) => i > 0 && i < end && new RegExp(`^${name}\\s*:`).test(l));
+        const existing = key('created');
+        const dateLine = key('date');
+        const eol = lines[dateLine >= 0 ? dateLine : 0].endsWith('\r') ? '\r' : '';
+        if (existing >= 0)
+            lines[existing] = `created: ${created}${eol}`; // clé vide : remplacée, jamais dupliquée
+        else
+            lines.splice(dateLine >= 0 ? dateLine + 1 : end, 0, `created: ${created}${eol}`);
+        writeFileSync(path, lines.join('\n'));
+        done.push({ file: e.file, created });
+    }
+    return done;
+}
 function escapeText(s) {
     return s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 }