@sylad/cadence 1.8.0 → 1.9.0

package/dist/migrate.js

@@ -0,0 +1,166 @@
+import { execFileSync } from 'node:child_process';
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { docSyncSet } from './docsync.js';
+import { PLAN_DEFAULT, PLAN_LEGACY, readMigrateConfig } from './config.js';
+import { gitRoot, isTracked } from './git.js';
+import { RafError } from './plan.js';
+/** L'historique n'est pas un lecteur : journaux de commits, journaux ndjson et fichiers d'exécution de `.cadence/`. */
+const HISTORY = ['**/CHANGELOG*', '**/*.ndjson', '.cadence/**'];
+/** Une référence à l'ancien emplacement que `raf migrate` sait réécrire : le chemin complet, pas suivi d'un nom plus long. */
+const REWRITABLE = /docs\/plan\/raf\.yaml(?![\w-]|\.\w)/g;
+/** Le chemin construit morceau par morceau : `'docs', 'plan'` (join, éventuellement sur plusieurs lignes) ou `Path('docs') / 'plan'` (pathlib). */
+const BUILT = /['"`]docs['"`]\s*\)?\s*[,/]\s*['"`]plan['"`]/;
+/** Toute autre façon de désigner docs/plan : un autre fichier du dossier, un dossier, un chemin construit morceau par morceau. */
+const OTHER = new RegExp(`docs/plan(?!/raf\\.yaml(?![\\w-]|\\.\\w))|${BUILT.source}`, 'g');
+const MAX_BYTES = 2 * 1024 * 1024;
+const BLOCK = 1024 * 1024;
+/** Le recouvrement entre deux blocs : un chemin construit (`'docs',\n  'plan'`) ne doit pas passer entre deux. */
+const OVERLAP = 4096;
+/** Un gros fichier cite-t-il le chemin ? Lu par blocs d'octets (latin1, un octet par caractère) : jamais décodé en une seule chaîne. */
+function citesPath(path) {
+    const fd = openSync(path, 'r');
+    try {
+        const buf = Buffer.alloc(BLOCK + OVERLAP);
+        let kept = 0;
+        for (;;) {
+            const n = readSync(fd, buf, kept, BLOCK, null);
+            if (n === 0)
+                return false;
+            const text = buf.toString('latin1', 0, kept + n);
+            if (text.includes('docs/plan') || BUILT.test(text))
+                return true;
+            const total = kept + n;
+            kept = Math.min(OVERLAP, total);
+            buf.copy(buf, 0, total - kept, total);
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Les fichiers à lire : ceux que git suit, ou tout le dossier (sans .git ni node_modules) hors d'un dépôt. */
+function candidates(root) {
+    if (gitRoot(root) === root) {
+        return execFileSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], { cwd: root, encoding: 'utf8', maxBuffer: 1 << 30 })
+            .split('\0')
+            .filter((f) => f !== '' && existsSync(join(root, f)));
+    }
+    const files = [];
+    const walk = (dir) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            if (e.name === '.git' || e.name === 'node_modules')
+                continue;
+            if (e.isDirectory())
+                walk(join(dir, e.name));
+            else if (e.isFile())
+                files.push(relative(root, join(dir, e.name)).split('\\').join('/'));
+        }
+    };
+    walk(root);
+    return files;
+}
+/** Ce que la migration ferait, sans rien modifier. Rejouable : un plan déjà déplacé ne laisse que les lecteurs restants. */
+export function planMigration(root) {
+    const hasLegacy = existsSync(join(root, PLAN_LEGACY));
+    const hasDefault = existsSync(join(root, PLAN_DEFAULT));
+    if (hasLegacy && hasDefault)
+        throw new RafError(`${PLAN_LEGACY} et ${PLAN_DEFAULT} existent tous deux : migration refusée, fusionner ou supprimer l'un des deux d'abord`);
+    if (!hasLegacy && !hasDefault)
+        throw new RafError(`aucun plan à migrer : ni ${PLAN_LEGACY} ni ${PLAN_DEFAULT} sous ${root}`);
+    const config = readMigrateConfig(join(root, 'cadence.yaml'));
+    const isKept = docSyncSet(config.keep);
+    const isHistory = docSyncSet(HISTORY);
+    const result = { move: hasLegacy ? (gitRoot(root) && isTracked(root, PLAN_LEGACY) ? 'git mv' : 'mv') : null, readers: [], kept: [], unhandled: [] };
+    for (const file of candidates(root).sort()) {
+        if (file === PLAN_LEGACY || file === PLAN_DEFAULT || isHistory(file))
+            continue;
+        const path = join(root, file);
+        // ni lien symbolique (sa cible est lue sous son propre nom), ni dossier (sous-module), ni fichier hors du commun
+        const stat = lstatSync(path);
+        if (!stat.isFile())
+            continue;
+        // un gros fichier n'est jamais lu en entier ni décodé : cherché par blocs, signalé s'il cite le chemin, ignoré sinon
+        if (stat.size > MAX_BYTES) {
+            if (!citesPath(path))
+                continue;
+            if (isKept(file))
+                result.kept.push(file);
+            else
+                result.unhandled.push({ file, text: 'fichier de plus de 2 Mio qui cite le chemin : trop gros pour être réécrit' });
+            continue;
+        }
+        const buffer = readFileSync(path);
+        const text = buffer.toString('utf8');
+        if (!text.includes('docs/plan') && !BUILT.test(text))
+            continue;
+        if (isKept(file)) {
+            result.kept.push(file);
+            continue;
+        }
+        if (buffer.includes(0)) {
+            result.unhandled.push({ file, text: 'fichier binaire : le chemin ne peut pas y être réécrit' });
+            continue;
+        }
+        if (!Buffer.from(text, 'utf8').equals(buffer)) {
+            result.unhandled.push({ file, text: 'fichier non UTF-8 : le réécrire en altérerait les octets' });
+            continue;
+        }
+        // le texte entier, pas ligne par ligne : un chemin construit peut s'étendre sur plusieurs lignes ; signalé à la ligne où il commence
+        const lines = text.split('\n');
+        const seen = new Set();
+        for (const m of text.matchAll(OTHER)) {
+            const line = text.slice(0, m.index).split('\n').length;
+            if (seen.has(line))
+                continue;
+            seen.add(line);
+            result.unhandled.push({ file, line, text: lines[line - 1].trim().slice(0, 160) });
+        }
+        const count = text.match(REWRITABLE)?.length ?? 0;
+        if (count > 0)
+            result.readers.push({ file, count });
+    }
+    return result;
+}
+/** La sortie lisible de la migration (aussi pour --dry-run) : le déplacement, chaque fichier touché, ce qui est épargné. */
+export function describeMigration(m, dryRun) {
+    const out = [];
+    if (dryRun)
+        out.push('raf migrate --dry-run : rien n\'est modifié');
+    if (!m.move && m.readers.length === 0)
+        out.push(`rien à migrer : le plan est déjà à ${PLAN_DEFAULT} et aucun lecteur ne cite ${PLAN_LEGACY}`);
+    out.push(m.move ? `plan : ${m.move} ${PLAN_LEGACY} ${PLAN_DEFAULT}` : `plan : déjà à ${PLAN_DEFAULT}`);
+    if (m.readers.length === 0)
+        out.push('lecteurs : rien à mettre à jour');
+    else {
+        const refs = m.readers.reduce((n, r) => n + r.count, 0);
+        out.push(`lecteurs mis à jour : ${m.readers.length} fichiers, ${refs} références`);
+        for (const r of m.readers)
+            out.push(`  ${r.file} (${r.count})`);
+    }
+    if (m.kept.length > 0) {
+        out.push(`laissés tels quels (migrate.keep) : ${m.kept.length} fichiers`);
+        for (const f of m.kept)
+            out.push(`  ${f}`);
+    }
+    return out;
+}
+/** Le refus : un lecteur reste non traité. */
+export function unhandledError(m) {
+    const rows = m.unhandled.map((u) => `  ${u.file}${u.line === undefined ? '' : `:${u.line}`}  ${u.text}`);
+    return new RafError(`migration refusée, aucun fichier modifié : ${m.unhandled.length} lecteur(s) non traité(s) (à corriger à la main, ou à déclarer sous migrate.keep dans cadence.yaml s'ils ne lisent pas le plan) :\n${rows.join('\n')}`);
+}
+/** Déplace le plan puis réécrit les lecteurs. L'appelant a vérifié qu'aucun lecteur n'est non traité. */
+export function applyMigration(root, m) {
+    if (m.move) {
+        mkdirSync(join(root, dirname(PLAN_DEFAULT)), { recursive: true });
+        if (m.move === 'git mv')
+            execFileSync('git', ['mv', '--', PLAN_LEGACY, PLAN_DEFAULT], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
+        else
+            renameSync(join(root, PLAN_LEGACY), join(root, PLAN_DEFAULT));
+    }
+    for (const r of m.readers) {
+        const path = join(root, r.file);
+        writeFileSync(path, readFileSync(path, 'utf8').replace(REWRITABLE, PLAN_DEFAULT));
+    }
+}

package/dist/orchestrate/briefs.js

@@ -24,20 +24,35 @@ export function reposText(role, lot, repos) {
         `\`raf commits ${lot}\` lists them all; read the diff of the neighbouring ones with \`git -C <path> log\` / \`git -C <path> show\` (${repos.map((r) => `git -C ${r.path} log`).join(' ; ')}), and review them like the rest. You are read-only there too.`,
     ].join('\n');
 }
+/** Revue courte du diff rebasé (L279, R17) : la branche du lot vient d'être rebasée sur celle du dépôt et son diff n'est plus celui que la revue a lu. */
+export function integrationText(base) {
+    return `Integration re-review: this lot's branch was just rebased onto \`${base}\`, which moved while the lot was being written, and the diff of the lot is no longer the one an earlier review read (context changed or a conflict was resolved). Review the rebased diff only (\`git diff ${base}...HEAD\`): report a finding only for what the rebase changed or broke in the lot's own change. The program has already re-run the tests and the build on the rebased tip.`;
+}
+/** Consigne du dossier temporaire (L242) : les sessions y rangent journaux de tests, dumps et exports, jamais dans le dépôt (4 « dépôt sale » le 18-10). */
+export function tmpText(dir) {
+    return `Temporary files: this session's \`TMPDIR\` is \`${dir}\` (short and outside the repository, never tracked by git, already created and exported; removed when the pass ends). Write test logs, dumps, exports and any scratch file there (\`> $TMPDIR/suite.txt\`), never inside the repository: not in its \`tmp/\`, not at its root. Leave the working tree with only the files of the lot.`;
+}
 /** Consigne d'implémentation d'un lot `visible` : son entrée Nouveautés (convention de `cadence news`, voir docs/news.md du paquet @sylad/cadence). */
 export function newsText(lot, captureDir) {
     return [
         `This lot is visible: write its News entry. Run \`cadence news new ${lot}\` (it creates \`docs/nouveautes/<date>-<slug>.md\`), then write the text in terms of what changes for the user, factual (what the user sees or can now do, no implementation detail, no promise).`,
         `The entry's title is user-side: \`cadence news new\` takes the lot's public title when it has one; otherwise rewrite the title in the user's words with \`--title\` (never the internal title of the lot).`,
         captureDir
-            ? `Add a screenshot of the result: copy it into \`docs/nouveautes/captures/\` and list it under \`captures:\` (a Playwright capture lands in the wave's output directory, outside the repository: \`${captureDir}\`, which this session may read; the file you keep for the entry is the one exception, copied into \`docs/nouveautes/captures/\`); if a screenshot makes no sense (or the app cannot be run), write \`nocapture: <reason>\` instead.`
+            ? `Add a screenshot of the result: copy it into \`docs/nouveautes/captures/\` and list it under \`captures:\` (a capture taken with the absolute path given above lands in the wave's output directory, outside the repository: \`${captureDir}\`, which this session may read; the file you keep for the entry is the one exception, copied into \`docs/nouveautes/captures/\`); if a screenshot makes no sense (or the app cannot be run), write \`nocapture: <reason>\` instead.`
             : `Add a screenshot of the result: save it under the OS temp directory (never inside the repository), then copy it into \`docs/nouveautes/captures/\` and list it under \`captures:\` (the file you keep for the entry is the one exception to "nothing inside the repository"); if a screenshot makes no sense (or the app cannot be run), write \`nocapture: <reason>\` instead.`,
         'Commit the entry with the lot (`cadence news check` must pass).',
     ].join('\n');
 }
 /** Consigne des briefs de correction d'un lot `visible` : où la vague range les captures Playwright (même dossier que l'étape implement). */
 export function capturesText(captureDir) {
-    return `Playwright captures of this wave land in \`${captureDir}\` (outside the repository; this session may read it): a screenshot a finding asks for is copied from there into \`docs/nouveautes/captures/\`.`;
+    return `A Playwright capture taken with the absolute path given above lands in \`${captureDir}\` (outside the repository; this session may read it): a screenshot a finding asks for is copied from there into \`docs/nouveautes/captures/\`.`;
+}
+/**
+ * Consigne de nommage des captures Playwright (L249). Mesuré sur @playwright/mcp 0.0.83 : `--output-dir` ne sert qu'aux fichiers que le serveur nomme lui-même ;
+ * un nom donné par la session est résolu sur la racine de travail du serveur (le dépôt), d'où cinq lots sur cinq le 23-10 avec des captures à la racine. La session donne donc le chemin absolu du dossier de la vague, que le serveur autorise.
+ */
+export function shotsText(captureDir) {
+    return `The Playwright server resolves a file name you give it against the repository, not against its output directory: a bare name such as page-home.png lands at the repository root. Give every screenshot, snapshot and trace the absolute path of the wave's capture directory, \`${captureDir}/\`, followed by the name (e.g. \`${captureDir}/page-home.png\`): the server allows it, and the repository stays clean. Never the \`--output-dir\` option (the server's launch argument, which a session cannot set).`;
 }
 const FILES = {
     precheck: 'precheck.md',
@@ -50,6 +65,7 @@ const FILES = {
     implement: 'implement.md',
     fix: 'fix.md',
     'fix-minors': 'fix-minors.md',
+    'fix-docs': 'fix-docs.md',
     review: 'review.md',
     ux: 'ux.md',
     'review-small': 'review-small.md',
@@ -75,7 +91,7 @@ export function loadTemplates(dir = TEMPLATES_DIR) {
 export function renderBrief(kind, vars, source = TEMPLATES_DIR) {
     const text = typeof source === 'string' ? loadTemplates(source)[kind] : source[kind];
     const out = text.replace(/\{\{(\w+)\}\}/g, (_m, name) => {
-        const v = { ...vars, repos: vars.repos ?? '', docs: vars.docs ?? '', spec: vars.spec ?? '', accept: vars.accept ?? '', maquette: vars.maquette ?? '', fiche: vars.fiche ?? '' }[name];
+        const v = { ...vars, repos: vars.repos ?? '', integration: vars.integration ?? '', docs: vars.docs ?? '', elsewhere: vars.elsewhere ?? '', spec: vars.spec ?? '', accept: vars.accept ?? '', maquette: vars.maquette ?? '', tmp: vars.tmp ?? '', shots: vars.shots ?? '', fiche: vars.fiche ?? '' }[name];
         if (v === undefined)
             throw new RafError(`gabarit ${FILES[kind]} : valeur manquante pour {{${name}}}`);
         return v;
@@ -83,9 +99,15 @@ export function renderBrief(kind, vars, source = TEMPLATES_DIR) {
     // Un marqueur vide ne laisse pas de trou : lignes vides en double ramenées à une.
     return `${out.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim()}\n`;
 }
-/** `{{objectif}}` : le titre du lot, ses notes et ses sous-tâches — Sylvain n'écrit rien d'autre. */
-export function objective(lot) {
-    const lines = [`${lot.title}`];
+/**
+ * L'objectif d'un lot (L258) : celui gardé dans l'état du lot (`LotState.goal`, fixé au lancement : `--goal`, sinon la clé `goal:` du plan),
+ * sinon son titre. Une seule source pour les briefs, la simulation et le tableau : la clé `goal:` du plan n'est pas relue en cours de vague,
+ * donc une reprise rejoue l'objectif du lancement.
+ */
+export const headline = (lot, goal) => goal ?? lot.title;
+/** `{{objectif}}` : l'objectif du lot (`headline`, le titre faute d'autre), ses notes et ses sous-tâches — Sylvain n'écrit rien d'autre. */
+export function objective(lot, goal) {
+    const lines = [headline(lot, goal)];
     if (lot.notes.length)
         lines.push('', 'Notes of the lot (decisions included):', ...lot.notes.map((n) => `- ${n.date}: ${n.text}`));
     if (lot.tasks.length)