@sylad/cadence 1.7.0 → 1.9.0

package/dist/ref/measure.js

@@ -0,0 +1,330 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { RafError } from '../plan.js';
+import { SLUG } from './add.js';
+import { decodePng, encodePng } from './png.js';
+import { readDocument } from './store.js';
+import { requireTools } from './tools.js';
+export const QUOI = ['couleurs', 'contraste', 'boites', 'texte'];
+/** Largeur d'écran de référence, en pixels, à laquelle les mesures sont ramenées. */
+export const REFERENCE_WIDTH = 1440;
+/** Écart d'un canal (0-255) après arrondi de la moyenne d'un carré. */
+const COLOR_TOLERANCE = 1;
+/** Part de la taille de police due à la forme des lettres : la hauteur de capitale n'est pas la même dans toutes les polices (0,70 à 0,73 em). */
+const FONT_TOLERANCE = 5;
+/** Hauteur de capitale, en part de la taille de police (Helvetica / Arial : 0,716 ; la valeur sert de repère, la tolérance couvre l'écart des autres polices). */
+const CAP_HEIGHT = 0.72;
+/** Distance (RVB, euclidienne) au fond à partir de laquelle un pixel n'est plus du fond ; en dessous de cette distance maximale, la zone est unie. Un seul seuil : une zone non unie a toujours un pixel de contenu. */
+const FLAT_DISTANCE = 24;
+/** Une boîte de moins de pixels que cela est de la poussière. */
+const MIN_BOX_AREA = 16;
+const MAX_BOXES = 20;
+/** Une couleur qui couvre moins de cette part de la zone n'est pas dominante. */
+const MIN_SHARE = 0.01;
+const MAX_DOMINANT = 5;
+/** Part minimale des pixels non-fond pour qu'une couleur soit une couleur de texte, et non un dégradé d'anticrénelage. */
+const MIN_INK_SHARE = 0.1;
+/** Confiance tesseract (0-100) à partir de laquelle la hauteur d'un mot sert à estimer la police. */
+const FONT_CONFIDENCE = 60;
+const hex2 = (n) => n.toString(16).padStart(2, '0');
+const color = (r, g, b) => ({ hex: `#${hex2(r)}${hex2(g)}${hex2(b)}`, rgb: [r, g, b] });
+const round1 = (n) => Math.round(n * 10) / 10;
+const round2 = (n) => Math.round(n * 100) / 100;
+/** Luminance relative WCAG 2.2 (sRGB). */
+function luminance([r, g, b]) {
+    const lin = (v) => {
+        const c = v / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+/** Rapport de contraste WCAG 2.2, non arrondi. */
+export function contrastRatio(a, b) {
+    const la = luminance(a);
+    const lb = luminance(b);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+/** `page`, `x,y` (un point) ou `x,y,l,h` (un carré), en pixels de la page rendue. */
+export function parseZone(text, raster) {
+    if (text === 'page')
+        return { zone: { x: 0, y: 0, l: raster.width, h: raster.height }, point: false };
+    const parts = text.split(',');
+    const nums = parts.map((p) => (/^\d+$/.test(p.trim()) ? Number(p) : NaN));
+    if ((parts.length !== 2 && parts.length !== 4) || nums.some(Number.isNaN) || (nums.length === 4 && (nums[2] < 1 || nums[3] < 1))) {
+        throw new RafError(`ref : zone invalide : « ${text} » (attendu : page, x,y pour un point ou x,y,l,h pour un carré, en pixels de la page rendue)`);
+    }
+    const [x, y, l, h] = nums.length === 2 ? [nums[0], nums[1], 1, 1] : nums;
+    if (x + l > raster.width || y + h > raster.height)
+        throw new RafError(`ref : zone ${text} hors de la page (${raster.width} × ${raster.height} px)`);
+    return { zone: { x, y, l, h }, point: nums.length === 2 };
+}
+/** Pixel (r, g, b) d'une image, l'alpha composé sur du blanc. */
+function pixel(r, x, y) {
+    const o = (y * r.width + x) * 4;
+    const a = r.data[o + 3];
+    const mix = (c) => (a === 255 ? c : Math.round((c * a + 255 * (255 - a)) / 255));
+    return [mix(r.data[o]), mix(r.data[o + 1]), mix(r.data[o + 2])];
+}
+function pixelsOf(r, z) {
+    const out = [];
+    for (let y = z.y; y < z.y + z.h; y++)
+        for (let x = z.x; x < z.x + z.l; x++)
+            out.push(pixel(r, x, y));
+    return out;
+}
+const distance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+function meanOf(px) {
+    const s = [0, 0, 0];
+    for (const p of px)
+        for (let i = 0; i < 3; i++)
+            s[i] += p[i];
+    return [Math.round(s[0] / px.length), Math.round(s[1] / px.length), Math.round(s[2] / px.length)];
+}
+/** Couleurs regroupées par 8 niveaux par canal, de la plus étendue à la moins étendue (celles sous `minShare` de la zone sont écartées) ; chacune est la moyenne de son groupe. */
+function dominant(px, minShare = MIN_SHARE) {
+    const groups = new Map();
+    for (const p of px) {
+        const key = ((p[0] >> 3) << 10) | ((p[1] >> 3) << 5) | (p[2] >> 3);
+        const g = groups.get(key);
+        if (g)
+            g.push(p);
+        else
+            groups.set(key, [p]);
+    }
+    return [...groups.entries()]
+        .sort((a, b) => b[1].length - a[1].length || a[0] - b[0])
+        .filter(([, g]) => g.length / px.length >= minShare)
+        .slice(0, MAX_DOMINANT)
+        .map(([, g]) => ({ ...color(...meanOf(g)), part: round2(g.length / px.length) }));
+}
+function measureColors(r, z, point) {
+    if (point)
+        return { point: color(...pixel(r, z.x, z.y)) };
+    const px = pixelsOf(r, z);
+    return { moyenne: color(...meanOf(px)), dominantes: dominant(px) };
+}
+/** Texte et fond d'une zone : le fond est la couleur dominante, le texte la moyenne des pixels les plus éloignés du fond. */
+function inkAndBackground(r, z) {
+    const px = pixelsOf(r, z);
+    const bg = dominant(px, 0)[0].rgb;
+    let far = 0;
+    for (const p of px)
+        far = Math.max(far, distance(p, bg));
+    if (far < FLAT_DISTANCE)
+        return null;
+    const ink = px.filter((p) => distance(p, bg) >= far * 0.75);
+    return { bg: color(...bg), fg: color(...meanOf(ink)), px, ink: px.filter((p) => distance(p, bg) >= FLAT_DISTANCE) };
+}
+/** Le texte peut avoir plusieurs couleurs : chaque couleur portée par au moins `MIN_INK_SHARE` des pixels non-fond est un texte, et le verdict est celui de la moins contrastée (jamais une moyenne, qui n'existe pas dans l'image), sauf si aucune couleur n'en porte autant (dégradé, photo) : le texte est alors la moyenne des pixels les plus éloignés du fond et la sortie le signale (`texte.moyenne`). */
+function measureContrast(r, z) {
+    const found = inkAndBackground(r, z);
+    if (!found)
+        return null;
+    const texts = dominant(found.ink, MIN_INK_SHARE);
+    // repli (dégradé, photo) : aucune couleur ne domine, le texte est la moyenne des pixels les plus éloignés du fond, et la sortie le dit
+    const repli = texts.length === 0;
+    if (repli)
+        texts.push({ ...found.fg, part: 1 });
+    const ratios = texts.map((t) => contrastRatio(t.rgb, found.bg.rgb));
+    const worst = ratios.indexOf(Math.min(...ratios));
+    const ratio = ratios[worst];
+    const { part: _part, ...couleur } = texts[worst];
+    const texte = repli ? { ...couleur, moyenne: true } : couleur;
+    // les seuils se lisent sur le rapport non arrondi : 4,499 n'atteint pas 4,5
+    return { texte, fond: found.bg, rapport: round2(ratio), aa: ratio >= 4.5, aaGrand: ratio >= 3, aaa: ratio >= 7 };
+}
+const scaleBox = (b, f) => {
+    const x0 = Math.round(b.x * f);
+    const y0 = Math.round(b.y * f);
+    return { x: x0, y: y0, l: Math.round((b.x + b.l) * f) - x0, h: Math.round((b.y + b.h) * f) - y0 };
+};
+function measureBoxes(r, z, f) {
+    const found = inkAndBackground(r, z);
+    if (!found)
+        return { fond: { hex: dominant(pixelsOf(r, z), 0)[0].hex }, contenu: null, boites: [], total: 0 };
+    const { bg, px } = found;
+    const mask = new Uint8Array(z.l * z.h);
+    let x0 = z.l, y0 = z.h, x1 = -1, y1 = -1;
+    px.forEach((p, i) => {
+        if (distance(p, bg.rgb) < FLAT_DISTANCE)
+            return;
+        mask[i] = 1;
+        const x = i % z.l;
+        const y = (i - x) / z.l;
+        x0 = Math.min(x0, x);
+        y0 = Math.min(y0, y);
+        x1 = Math.max(x1, x);
+        y1 = Math.max(y1, y);
+    });
+    // composantes connexes (8 voisins), chacune avec sa boîte englobante
+    const boxes = [];
+    const stack = [];
+    for (let start = 0; start < mask.length; start++) {
+        if (mask[start] !== 1)
+            continue;
+        mask[start] = 2;
+        stack.push(start);
+        let bx0 = z.l, by0 = z.h, bx1 = -1, by1 = -1, area = 0;
+        while (stack.length > 0) {
+            const i = stack.pop();
+            const x = i % z.l;
+            const y = (i - x) / z.l;
+            area++;
+            bx0 = Math.min(bx0, x);
+            by0 = Math.min(by0, y);
+            bx1 = Math.max(bx1, x);
+            by1 = Math.max(by1, y);
+            for (let dy = -1; dy <= 1; dy++) {
+                for (let dx = -1; dx <= 1; dx++) {
+                    const nx = x + dx, ny = y + dy;
+                    if (nx < 0 || ny < 0 || nx >= z.l || ny >= z.h)
+                        continue;
+                    const n = ny * z.l + nx;
+                    if (mask[n] === 1) {
+                        mask[n] = 2;
+                        stack.push(n);
+                    }
+                }
+            }
+        }
+        if (area >= MIN_BOX_AREA)
+            boxes.push({ x: z.x + bx0, y: z.y + by0, l: bx1 - bx0 + 1, h: by1 - by0 + 1, area });
+    }
+    boxes.sort((a, b) => b.area - a.area || a.y - b.y || a.x - b.x);
+    return {
+        fond: { hex: bg.hex },
+        contenu: scaleBox({ x: z.x + x0, y: z.y + y0, l: x1 - x0 + 1, h: y1 - y0 + 1 }, f),
+        boites: boxes.slice(0, MAX_BOXES).map((b) => scaleBox(b, f)),
+        total: boxes.length,
+    };
+}
+/** Mots de tesseract (tsv) sur le recadrage de la zone, en pixels de la page puis ramenés à l'échelle ; la hauteur de capitale en pixels de la page sert à la police. */
+function readWords(tools, r, z, f) {
+    const work = mkdtempSync(join(tmpdir(), 'cadence-ref-'));
+    try {
+        const crop = Buffer.alloc(z.l * z.h * 4);
+        for (let y = 0; y < z.h; y++)
+            r.data.copy(crop, y * z.l * 4, ((z.y + y) * r.width + z.x) * 4, ((z.y + y) * r.width + z.x + z.l) * 4);
+        const file = join(work, 'zone.png');
+        writeFileSync(file, encodePng(z.l, z.h, crop));
+        let tsv;
+        try {
+            tsv = execFileSync(tools.tesseract, [file, 'stdout', '--psm', '6', '-l', 'eng', 'tsv'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 1024 * 1024 * 64 });
+        }
+        catch (e) {
+            throw new RafError(`ref : tesseract a échoué : ${String(e.stderr ?? e.message).trim().split('\n')[0]}`);
+        }
+        const words = [];
+        const caps = [];
+        for (const row of tsv.split('\n').slice(1)) {
+            const c = row.split('\t');
+            const texte = (c[11] ?? '').trim();
+            if (c[0] !== '5' || texte === '')
+                continue;
+            const confiance = Math.round(Number(c[10]));
+            const [left, top, width, height] = [Number(c[6]), Number(c[7]), Number(c[8]), Number(c[9])];
+            words.push({ texte, confiance, ...scaleBox({ x: z.x + left, y: z.y + top, l: width, h: height }, f) });
+            // hauteur de capitale : un mot sans jambage (g j p q y), dont une lettre monte à la hauteur de capitale (majuscule, chiffre, b d f h k l)
+            if (confiance >= FONT_CONFIDENCE && /^[A-Za-z0-9]+$/.test(texte) && /[A-Zbdfhkl0-9]/.test(texte) && !/[gjpqy]/.test(texte))
+                caps.push(height);
+        }
+        return { words, caps };
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}
+function measureText(tools, r, z, f) {
+    const { words, caps } = readWords(tools, r, z, f);
+    if (caps.length === 0)
+        return { mots: words, police: null };
+    const sorted = [...caps].sort((a, b) => a - b);
+    const cap = sorted.length % 2 ? sorted[(sorted.length - 1) / 2] : (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2;
+    // un pixel de hauteur de capitale mal lu pèse 1/cap de la taille
+    return { mots: words, police: { px: round1((cap / CAP_HEIGHT) * f), tolerancePourcent: Math.ceil(FONT_TOLERANCE + 100 / cap), mots: caps.length } };
+}
+const pct = (n) => `${Math.round(n * 100)} %`;
+/** `cadence ref measure <slug> <page> <zone>` : mesures d'une zone d'une page rendue, ramenées à la largeur de référence. */
+export function measure(o) {
+    const tools = requireTools(o.env);
+    if (!SLUG.test(o.slug))
+        throw new RafError(`ref : document inconnu : « ${o.slug} »`);
+    const docDir = join(o.refsDir(), o.slug);
+    const doc = readDocument(docDir);
+    if (!doc)
+        throw new RafError(`ref : document inconnu : « ${o.slug} » (cadence ref add <document.pdf> --slug ${o.slug})`);
+    if (!/^\d+$/.test(o.page) || Number(o.page) < 1)
+        throw new RafError(`ref : page invalide : « ${o.page} » (un numéro à partir de 1)`);
+    const n = Number(o.page);
+    if (n > doc.pages.length)
+        throw new RafError(`ref : page ${n} absente : « ${o.slug} » a ${doc.pages.length} pages`);
+    const file = join(docDir, 'pages', `page-${n}.png`);
+    if (!existsSync(file))
+        throw new RafError(`ref : page ${n} non rendue : cadence ref add ${doc.source} --slug ${o.slug} --sections ${n}`);
+    if (o.quoi !== undefined && !QUOI.includes(o.quoi))
+        throw new RafError(`ref : --quoi invalide : « ${o.quoi} » (couleurs, contraste, boites ou texte)`);
+    const largeur = o.largeur === undefined ? REFERENCE_WIDTH : Number(o.largeur);
+    if (!(largeur > 0) || !Number.isFinite(largeur))
+        throw new RafError(`ref : --largeur invalide : « ${o.largeur} » (un nombre de pixels > 0)`);
+    const raster = decodePng(readFileSync(file), file);
+    const { zone, point } = parseZone(o.zone, raster);
+    if (point && o.quoi !== undefined && o.quoi !== 'couleurs')
+        throw new RafError('ref : un point ne se mesure qu\'en couleurs (donner un carré x,y,l,h ou page)');
+    const wanted = o.quoi !== undefined ? [o.quoi] : point ? ['couleurs'] : [...QUOI];
+    const f = largeur / raster.width;
+    const result = {
+        document: o.slug,
+        page: n,
+        zone,
+        echelle: { largeur, facteur: round2(f) },
+        tolerance: { couleurs: COLOR_TOLERANCE, boitesPx: Math.max(1, Math.ceil(f)), policePourcent: FONT_TOLERANCE },
+    };
+    if (wanted.includes('couleurs'))
+        result.couleurs = measureColors(raster, zone, point);
+    if (wanted.includes('contraste'))
+        result.contraste = measureContrast(raster, zone);
+    if (wanted.includes('boites'))
+        result.boites = measureBoxes(raster, zone, f);
+    if (wanted.includes('texte'))
+        result.texte = measureText(tools, raster, zone, f);
+    if (o.json) {
+        o.out(JSON.stringify(result, null, 2));
+        return;
+    }
+    for (const line of render(result, point))
+        o.out(line);
+}
+function render(m, point) {
+    const z = m.zone;
+    const lines = [`${m.document} p.${m.page} · zone ${point ? `${z.x},${z.y}` : `${z.x},${z.y},${z.l},${z.h}`} px de la page · ramené à ${m.echelle.largeur} px (×${m.echelle.facteur})`];
+    const c = m.couleurs;
+    if (c?.point)
+        lines.push(`couleurs : ${c.point.hex} rgb(${c.point.rgb.join(', ')})`);
+    else if (c)
+        lines.push(`couleurs : moyenne ${c.moyenne.hex} ; dominantes ${c.dominantes.length === 0 ? 'aucune' : c.dominantes.map((d) => `${d.hex} ${pct(d.part)}`).join(', ')}`);
+    if ('contraste' in m) {
+        const k = m.contraste;
+        const ok = (b) => (b ? '✓' : '✗');
+        lines.push(k ? `contraste : ${k.rapport}:1 (texte ${k.texte.hex}${k.texte.moyenne ? ', moyenne des pixels les plus éloignés du fond : aucune couleur de texte ne domine' : ''} sur fond ${k.fond.hex}) · AA ${ok(k.aa)} · AA grand texte et composants ${ok(k.aaGrand)} · AAA ${ok(k.aaa)}` : 'contraste : zone d\'une seule couleur, rien à mesurer');
+    }
+    if (m.boites) {
+        const b = m.boites;
+        const box = (q) => `${q.x},${q.y} ${q.l}×${q.h}`;
+        lines.push(b.contenu ? `boîtes : fond ${b.fond.hex} · contenu ${box(b.contenu)} · ${b.total} boîte(s)${b.boites.length < b.total ? ` (${b.boites.length} plus grandes)` : ''}` : 'boîtes : zone d\'une seule couleur, aucune boîte');
+        for (const q of b.boites)
+            lines.push(`  ${box(q)}`);
+    }
+    if (m.texte) {
+        const t = m.texte;
+        lines.push(t.mots.length === 0 ? 'texte : aucun mot lu' : `texte : ${t.mots.map((w) => w.texte).join(' ')}`);
+        for (const w of t.mots)
+            lines.push(`  « ${w.texte} » ${w.x},${w.y} ${w.l}×${w.h} (confiance ${w.confiance})`);
+        if (t.mots.length > 0)
+            lines.push(t.police ? `police : ≈ ${t.police.px} px (±${t.police.tolerancePourcent} %, ${t.police.mots} mot(s) à hauteur de capitale)` : 'police : aucun mot exploitable pour estimer la taille');
+    }
+    const tol = m.tolerance;
+    lines.push(`tolérance : couleurs ±${tol.couleurs}/255 par canal, boîtes ±${tol.boitesPx} px, police ±${tol.policePourcent} % plus un pixel de hauteur de capitale`);
+    return lines;
+}

package/dist/ref/pdf.js

@@ -0,0 +1,104 @@
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { RafError } from '../plan.js';
+/** Résolution du rendu des pages (points PDF → pixels). */
+export const DPI = 200;
+const SCALE = DPI / 72;
+const px = (pt) => Math.round(pt * SCALE);
+function exec(file, args, cwd) {
+    return execFileSync(file, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 1024 * 1024 * 512, env: { ...process.env, LC_ALL: 'C' } });
+}
+/** Nombre de pages ; un PDF chiffré, abîmé ou sans page est refusé avec la raison. */
+export function pageCount(tools, file) {
+    let out;
+    try {
+        out = exec(tools.pdfinfo, [file]);
+    }
+    catch (e) {
+        const err = String(e.stderr ?? '');
+        if (/password/i.test(err))
+            throw new RafError(`ref : ${file} est un PDF chiffré (mot de passe demandé), il n'est pas lu`);
+        throw new RafError(`ref : ${file} est un PDF abîmé ou n'est pas un PDF (${err.split('\n')[0]?.replace(/^Syntax Error[^:]*: /, '') || 'pdfinfo refuse de le lire'})`);
+    }
+    if (/^Encrypted:\s+yes/m.test(out) && /copy:no/.test(out))
+        throw new RafError(`ref : ${file} est un PDF chiffré dont la copie est interdite, il n'est pas lu`);
+    const pages = Number(/^Pages:\s+(\d+)/m.exec(out)?.[1] ?? 0);
+    if (pages < 1)
+        throw new RafError(`ref : ${file} n'a aucune page`);
+    return pages;
+}
+const attr = (tag, name) => new RegExp(`${name}="([^"]*)"`).exec(tag)?.[1] ?? '';
+const unescapeXml = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+/** Texte positionné de tout le document (`pdftotext -bbox-layout` : mots regroupés en lignes), en pixels de la page rendue. */
+export function textLayout(tools, file) {
+    const xml = exec(tools.pdftotext, ['-bbox-layout', file, '-']);
+    const pages = [];
+    for (const chunk of xml.split('<page ').slice(1)) {
+        const head = chunk.slice(0, chunk.indexOf('>'));
+        const page = { n: pages.length + 1, width: px(Number(attr(head, 'width'))), height: px(Number(attr(head, 'height'))), lines: [] };
+        for (const m of chunk.matchAll(/<line ([^>]*)>([\s\S]*?)<\/line>/g)) {
+            const words = [...m[2].matchAll(/<word [^>]*>([^<]*)<\/word>/g)].map((w) => unescapeXml(w[1]));
+            if (words.length === 0)
+                continue;
+            const x0 = Number(attr(m[1], 'xMin'));
+            const y0 = Number(attr(m[1], 'yMin'));
+            page.lines.push({ text: words.join(' '), x: px(x0), y: px(y0), l: px(Number(attr(m[1], 'xMax')) - x0), h: px(Number(attr(m[1], 'yMax')) - y0) });
+        }
+        pages.push(page);
+    }
+    return pages;
+}
+/** Images embarquées (masques de transparence exclus), page par page, dans l'ordre du document. */
+export function listImages(tools, file) {
+    const out = [];
+    const slots = new Map();
+    const ranks = new Map();
+    for (const row of exec(tools.pdfimages, ['-list', file]).split('\n').slice(2)) {
+        const c = row.trim().split(/\s+/);
+        if (c.length < 5)
+            continue;
+        const page = Number(c[0]);
+        const slot = slots.get(page) ?? 0;
+        slots.set(page, slot + 1);
+        if (c[2] === 'smask')
+            continue;
+        const rank = (ranks.get(page) ?? 0) + 1;
+        ranks.set(page, rank);
+        out.push({ page, rank, slot, pixelsW: Number(c[3]), pixelsH: Number(c[4]) });
+    }
+    return out;
+}
+/** Rend les pages à 200 dpi dans `dir/page-<n>.png`. */
+export function renderPages(tools, file, pages, dir) {
+    mkdirSync(dir, { recursive: true });
+    for (const n of pages)
+        exec(tools.pdftoppm, ['-r', String(DPI), '-png', '-singlefile', '-f', String(n), '-l', String(n), file, join(dir, `page-${n}`)]);
+}
+/** Résolution des vignettes de toutes les pages (à parcourir pour repérer les planches d'un document sans texte). */
+export const THUMB_DPI = 40;
+/** Vignettes basse résolution de toutes les pages dans `dir/page-<n>.png`. */
+export function renderThumbnails(tools, file, total, dir) {
+    mkdirSync(dir, { recursive: true });
+    for (let n = 1; n <= total; n++)
+        exec(tools.pdftoppm, ['-r', String(THUMB_DPI), '-png', '-singlefile', '-f', String(n), '-l', String(n), file, join(dir, `page-${n}`)]);
+}
+/** Extrait les images d'une page dans `dir/p<page>-<slot sur 3 chiffres>.png`. */
+export function extractImages(tools, file, page, dir) {
+    mkdirSync(dir, { recursive: true });
+    exec(tools.pdfimages, ['-png', '-f', String(page), '-l', String(page), file, join(dir, `p${page}`)]);
+}
+export const imageFile = (page, slot) => `p${page}-${String(slot).padStart(3, '0')}.png`;
+/** Régions des images d'une page (ordre du document), en pixels de la page rendue : `pdftohtml -xml` au zoom 200/72. */
+export function imageRegions(tools, file, page) {
+    const work = mkdtempSync(join(tmpdir(), 'cadence-ref-'));
+    try {
+        exec(tools.pdftohtml, ['-xml', '-q', '-nodrm', '-zoom', String(SCALE), '-f', String(page), '-l', String(page), file, join(work, 'p')]);
+        const xml = readFileSync(join(work, 'p.xml'), 'utf8');
+        return [...xml.matchAll(/<image ([^>]*)\/>/g)].map((m) => ({ page, x: Number(attr(m[1], 'left')), y: Number(attr(m[1], 'top')), l: Number(attr(m[1], 'width')), h: Number(attr(m[1], 'height')) }));
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}

package/dist/ref/png.js

@@ -0,0 +1,125 @@
+import { inflateSync, deflateSync } from 'node:zlib';
+import { RafError } from '../plan.js';
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** Type de couleur PNG → nombre de canaux (0 gris, 2 RVB, 4 gris + alpha, 6 RVBA). La palette (3) n'est pas lue. */
+const CHANNELS = { 0: 1, 2: 3, 4: 2, 6: 4 };
+/**
+ * Décode un PNG 8 bits non entrelacé (ce que `pdftoppm` écrit) en RVBA. Un PNG d'un autre genre est refusé avec la raison :
+ * `measure` mesure les pixels, il ne les devine pas.
+ */
+export function decodePng(buf, what) {
+    if (buf.length < 33 || !buf.subarray(0, 8).equals(SIGNATURE))
+        throw new RafError(`ref : ${what} n'est pas un PNG`);
+    let width = 0;
+    let height = 0;
+    let type = -1;
+    const idat = [];
+    for (let at = 8; at + 8 <= buf.length;) {
+        const len = buf.readUInt32BE(at);
+        const name = buf.toString('latin1', at + 4, at + 8);
+        const body = buf.subarray(at + 8, at + 8 + len);
+        if (name === 'IHDR') {
+            width = body.readUInt32BE(0);
+            height = body.readUInt32BE(4);
+            type = body[9];
+            if (body[8] !== 8)
+                throw new RafError(`ref : ${what} : PNG à ${body[8]} bits par canal, seuls les PNG 8 bits sont lus`);
+            if (body[12] !== 0)
+                throw new RafError(`ref : ${what} : PNG entrelacé, non lu`);
+        }
+        else if (name === 'IDAT')
+            idat.push(body);
+        else if (name === 'IEND')
+            break;
+        at += 12 + len;
+    }
+    const channels = CHANNELS[type];
+    if (channels === undefined || width < 1 || height < 1)
+        throw new RafError(`ref : ${what} : PNG de type de couleur ${type} non lu (gris, RVB, avec ou sans alpha)`);
+    let raw;
+    try {
+        raw = inflateSync(Buffer.concat(idat));
+    }
+    catch {
+        throw new RafError(`ref : ${what} : PNG abîmé (données illisibles)`);
+    }
+    const stride = width * channels;
+    if (raw.length < (stride + 1) * height)
+        throw new RafError(`ref : ${what} : PNG tronqué`);
+    const data = Buffer.alloc(width * height * 4);
+    const line = Buffer.alloc(stride);
+    let prev = Buffer.alloc(stride);
+    for (let y = 0; y < height; y++) {
+        const filter = raw[y * (stride + 1)];
+        for (let i = 0; i < stride; i++) {
+            const x = raw[y * (stride + 1) + 1 + i];
+            const a = i >= channels ? line[i - channels] : 0;
+            const b = prev[i];
+            const c = i >= channels ? prev[i - channels] : 0;
+            let v;
+            if (filter === 0)
+                v = x;
+            else if (filter === 1)
+                v = x + a;
+            else if (filter === 2)
+                v = x + b;
+            else if (filter === 3)
+                v = x + ((a + b) >> 1);
+            else if (filter === 4) {
+                const p = a + b - c;
+                const pa = Math.abs(p - a);
+                const pb = Math.abs(p - b);
+                const pc = Math.abs(p - c);
+                v = x + (pa <= pb && pa <= pc ? a : pb <= pc ? b : c);
+            }
+            else
+                throw new RafError(`ref : ${what} : PNG abîmé (filtre ${filter})`);
+            line[i] = v & 0xff;
+        }
+        for (let x = 0; x < width; x++) {
+            const o = (y * width + x) * 4;
+            const s = x * channels;
+            if (channels <= 2)
+                data.set([line[s], line[s], line[s], channels === 2 ? line[s + 1] : 255], o);
+            else
+                data.set([line[s], line[s + 1], line[s + 2], channels === 4 ? line[s + 3] : 255], o);
+        }
+        prev = Buffer.from(line);
+    }
+    return { width, height, data };
+}
+const CRC = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (const b of buf)
+        c = CRC[(c ^ b) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(name, body) {
+    const head = Buffer.alloc(8);
+    head.writeUInt32BE(body.length, 0);
+    head.write(name, 4, 'latin1');
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), body])), 0);
+    return Buffer.concat([head, body, crc]);
+}
+/** Encode du RVBA en PNG RVBA 8 bits (sans filtre) : le recadrage que tesseract lit, et les images générées des tests. */
+export function encodePng(width, height, rgba) {
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr.set([8, 6, 0, 0, 0], 8);
+    const rows = Buffer.alloc((width * 4 + 1) * height);
+    for (let y = 0; y < height; y++)
+        rgba.copy(rows, y * (width * 4 + 1) + 1, y * width * 4, (y + 1) * width * 4);
+    return Buffer.concat([SIGNATURE, chunk('IHDR', ihdr), chunk('IDAT', deflateSync(rows)), chunk('IEND', Buffer.alloc(0))]);
+}

package/dist/ref/store.js

@@ -0,0 +1,40 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { readReferencesConfig } from '../config.js';
+import { gitRoot } from '../git.js';
+import { RafError } from '../plan.js';
+/**
+ * Dossier des documents : `references.dir` de cadence.yaml (relatif à son dossier), sinon `$XDG_DATA_HOME/cadence/references`.
+ * Un `references.dir` dans un dépôt Git est refusé : les documents de référence peuvent être privés, ils ne se commitent pas.
+ */
+export function referencesDir(root, configPath, env) {
+    const dir = readReferencesConfig(configPath).dir;
+    if (dir === undefined)
+        return join(env.XDG_DATA_HOME || join(env.HOME || homedir(), '.local', 'share'), 'cadence', 'references');
+    const abs = resolve(dirname(configPath), dir);
+    let probe = abs;
+    while (!existsSync(probe) && dirname(probe) !== probe)
+        probe = dirname(probe);
+    if (gitRoot(probe))
+        throw new RafError(`ref : references.dir (${abs}) est dans un dépôt Git : les documents de référence restent hors du dépôt (choisir un dossier ailleurs, ou retirer la clé pour $XDG_DATA_HOME/cadence/references)`);
+    return abs;
+}
+export const documentFile = (docDir) => join(docDir, 'document.json');
+export function readDocument(docDir) {
+    const file = documentFile(docDir);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new RafError(`ref : ${file} illisible : ${e.message.split('\n')[0]}`);
+    }
+}
+export function writeDocument(docDir, doc) {
+    mkdirSync(docDir, { recursive: true });
+    const tmp = `${documentFile(docDir)}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`);
+    renameSync(tmp, documentFile(docDir));
+}

package/dist/ref/tools.js

@@ -0,0 +1,51 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { RafError } from '../plan.js';
+const POPPLER = 'sudo apt install poppler-utils';
+/** Les outils du système dont `cadence ref` dépend, dans l'ordre où l'erreur les nomme. */
+export const TOOLS = [
+    { name: 'pdftoppm', commands: ['pdftoppm'], install: POPPLER },
+    { name: 'pdftotext', commands: ['pdftotext'], install: POPPLER },
+    { name: 'pdfimages', commands: ['pdfimages'], install: POPPLER },
+    { name: 'pdfinfo', commands: ['pdfinfo'], install: POPPLER },
+    { name: 'pdftohtml', commands: ['pdftohtml'], install: POPPLER },
+    { name: 'magick', commands: ['magick', 'convert'], install: 'sudo apt install imagemagick' },
+    { name: 'tesseract', commands: ['tesseract'], install: 'sudo apt install tesseract-ocr' },
+];
+function executable(file) {
+    try {
+        if (!statSync(file).isFile())
+            return false;
+        accessSync(file, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function which(command, path) {
+    for (const dir of path.split(delimiter)) {
+        if (dir && executable(join(dir, command)))
+            return join(dir, command);
+    }
+    return null;
+}
+/**
+ * Chemin absolu de chaque outil, cherché dans le PATH de l'environnement de la commande. Un outil absent est nommé avec sa
+ * commande d'installation (une ligne par outil), la commande sort en 2 : rien n'est installé d'office.
+ */
+export function requireTools(env) {
+    const path = env.PATH ?? '';
+    const found = {};
+    const missing = [];
+    for (const t of TOOLS) {
+        const hit = t.commands.map((c) => which(c, path)).find((p) => p !== null);
+        if (hit)
+            found[t.name] = hit;
+        else
+            missing.push(`  ${t.commands.join(' ou ')} : ${t.install}`);
+    }
+    if (missing.length > 0)
+        throw new RafError(`ref : outil absent du PATH, à installer (rien n'est installé d'office) :\n${missing.join('\n')}`);
+    return found;
+}