@cardinali-studio/adminkit 1.0.0

package/dist/prose.js

@@ -0,0 +1,205 @@
+/* La conversione fra il markdown salvato e il testo formattato che si vede nel pannello.
+ *
+ * ── Perché esiste ──────────────────────────────────────────────────────────────────────────
+ * Chi usa il pannello non scrive markdown e non deve vederlo: una parola in grassetto si vede
+ * in grassetto, non fra due asterischi. Il FILE però resta markdown — è il formato dei
+ * contenuti del sito, lo legge Hugo, e non cambia per far comodo a un'interfaccia.
+ *
+ * Queste due funzioni sono la cerniera, e sono l'unico punto in cui il testo cambia forma:
+ * `mdToHtml` per mostrarlo, `htmlToMd` per rimetterlo com'era.
+ *
+ * ── La regola che le tiene oneste ──────────────────────────────────────────────────────────
+ * **`htmlToMd(mdToHtml(x))` deve dare esattamente `x`**, per ogni testo che sta nei contenuti
+ * del sito. Non è un'aspirazione: è un test che gira sui file veri
+ * (`test/prose-roundtrip.test.js`). Senza, aprire una pagina e salvarla senza toccarla
+ * riscriverebbe i testi — cioè il difetto che la guardia di fedeltà del progetto esiste per
+ * impedire, spostato dentro l'editor.
+ *
+ * ── Cosa si converte, e perché solo questo ────────────────────────────────────────────────
+ * Grassetto, corsivo, collegamenti e paragrafi: esattamente ciò che la barra sa produrre e che
+ * i template rendono (`markdownify` per i campi, `.Content` per i corpi). Titoli, elenchi e
+ * citazioni NON si convertono: nei contenuti di questo sito non ce n'è nessuno, e ciò che non
+ * si riconosce resta testo letterale — quindi si rilegge e si riscrive identico invece di
+ * sparire. Meglio un `# ciao` mostrato com'è che un titolo che l'editor cancella.
+ *
+ * Nessuna delle due funzioni AGGIUNGE mai `\` di protezione. Un asterisco solitario scritto da
+ * chi usa il pannello resta un asterisco solitario nel file: proteggerlo vorrebbe dire
+ * cambiare i file esistenti al primo salvataggio, che è il male peggiore.
+ */
+/* ---- Markdown -> HTML ---------------------------------------------------------------------- */
+const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/* Un tokenizer solo, con le alternative in ordine di lunghezza: `***` prima di `**` prima di
+ * `*`, altrimenti un grassetto verrebbe letto come due corsivi vuoti. Le parti sono chiuse
+ * (niente asterischi dentro) di proposito: è il sottoinsieme che la barra produce, e allargarlo
+ * significherebbe scrivere un parser markdown accanto a Goldmark. */
+const INLINE = /\[([^\]]*)\]\(([^)\s]*)\)|\*\*\*([^*]+)\*\*\*|\*\*([^*]+)\*\*|\*([^*]+)\*/g;
+function inlineToHtml(md) {
+    let out = "";
+    let last = 0;
+    /* Un'istanza NUOVA a ogni chiamata, non `INLINE` con `lastIndex` azzerato: questa funzione
+       richiama sé stessa sull'etichetta di un link, e una regex globale condivisa fra chiamante e
+       chiamata si sposta il segnaposto a vicenda — il ciclo esterno riparte da capo e non finisce
+       più. Costa un oggetto per paragrafo, non un ciclo infinito. */
+    const inline = new RegExp(INLINE.source, "g");
+    for (let m = inline.exec(md); m; m = inline.exec(md)) {
+        out += escapeHtml(md.slice(last, m.index));
+        const [all, linkText, href, both, strong, em] = m;
+        if (href !== undefined) {
+            // L'etichetta può contenere a sua volta grassetto o corsivo.
+            out += `<a href="${escapeHtml(href)}">${inlineToHtml(linkText ?? "")}</a>`;
+        }
+        else if (both !== undefined) {
+            out += `<strong><em>${escapeHtml(both)}</em></strong>`;
+        }
+        else if (strong !== undefined) {
+            out += `<strong>${escapeHtml(strong)}</strong>`;
+        }
+        else if (em !== undefined) {
+            out += `<em>${escapeHtml(em)}</em>`;
+        }
+        else {
+            out += escapeHtml(all);
+        }
+        last = m.index + all.length;
+    }
+    return out + escapeHtml(md.slice(last));
+}
+/** Il markdown come lo mostra il campo: un `<p>` per paragrafo, `<br>` per l'a capo singolo. */
+export function mdToHtml(md) {
+    const paragraphs = String(md ?? "").split("\n\n");
+    return paragraphs
+        .map((paragraph) => {
+        const inner = paragraph.split("\n").map(inlineToHtml).join("<br>");
+        /* Un paragrafo vuoto ha comunque bisogno di un `<br>` dentro: un `<p></p>` non ha
+           altezza, quindi non si può nemmeno cliccarci dentro per scrivere. */
+        return `<p>${inner || "<br>"}</p>`;
+    })
+        .join("");
+}
+/* ---- HTML -> Markdown ---------------------------------------------------------------------- */
+/* Un mini-parser invece del DOM del browser: così la conversione si prova con `node --test` sui
+ * contenuti veri, che è dove sta il rischio. Il sottoinsieme è chiuso — i tag che produciamo noi
+ * più quelli che un contenteditable genera da sé — e tutto il resto viene attraversato: di un
+ * `<span style=…>` incollato da un altro programma resta il testo, che è ciò che si vuole. */
+const TAG = /<\/?([a-z0-9]+)((?:[^>"']|"[^"]*"|'[^']*')*)>/gi;
+const ATTR = /([a-z-]+)\s*=\s*("([^"]*)"|'([^']*)'|([^\s>]+))/gi;
+const unescapeHtml = (text) => text
+    .replace(/&nbsp;/g, " ")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+function attrOf(raw, name) {
+    ATTR.lastIndex = 0;
+    for (let m = ATTR.exec(raw); m; m = ATTR.exec(raw)) {
+        if (m[1]?.toLowerCase() === name)
+            return unescapeHtml(m[3] ?? m[4] ?? m[5] ?? "");
+    }
+    return "";
+}
+/** Gli indirizzi che si possono scrivere in un collegamento.
+ *
+ *  `javascript:` è la ragione per cui questo controllo esiste: il markdown dell'admin finisce in
+ *  pagine renderizzate con `unsafe = true`, quindi un indirizzo non è un dato inerte. Si
+ *  accettano gli schemi che servono e i percorsi interni; tutto il resto è rifiutato invece di
+ *  essere ripulito, perché "ripulire" un indirizzo ostile è un gioco che si perde. */
+export function isSafeHref(href) {
+    const value = href.trim();
+    if (!value)
+        return false;
+    if (/^(https?:|mailto:)/i.test(value))
+        return true;
+    // Interni: `/pagina/`, `#ancora`. Non `//host`, che è un indirizzo assoluto travestito.
+    return (value.startsWith("/") && !value.startsWith("//")) || value.startsWith("#");
+}
+/* Gli spazi ai bordi restano FUORI dai delimitatori: `**ciao **` non è grassetto per CommonMark
+   — la chiusura preceduta da uno spazio non chiude — e un doppio click si porta via lo spazio
+   dopo la parola senza che chi scrive se ne accorga. */
+function wrap(inner, mark) {
+    const core = inner.trim();
+    if (!core)
+        return inner;
+    const left = inner.slice(0, inner.length - inner.trimStart().length);
+    const right = inner.slice(inner.trimEnd().length);
+    return `${left}${mark}${core}${mark}${right}`;
+}
+/** Il testo del campo com'è da salvare: markdown. */
+export function htmlToMd(html) {
+    const blocks = [];
+    let current = "";
+    /* Cosa è aperto in questo momento, per sapere cosa chiudere. Solo la formattazione in linea:
+       i blocchi si chiudono da sé finendo. */
+    const open = [];
+    const emit = (text) => {
+        if (open.length)
+            open[open.length - 1].text += text;
+        else
+            current += text;
+    };
+    const closeBlock = () => {
+        // Mentre si chiude un blocco può restare della formattazione aperta (HTML malformato):
+        // si chiude anche quella, altrimenti il suo testo sparirebbe.
+        while (open.length)
+            closeInline(open[open.length - 1].tag);
+        const text = current.trim();
+        if (text)
+            blocks.push(text);
+        current = "";
+    };
+    function closeInline(tag) {
+        const index = open.map((item) => item.tag).lastIndexOf(tag);
+        if (index < 0)
+            return;
+        // Chiude anche ciò che è rimasto aperto dentro, dal più interno.
+        while (open.length > index) {
+            const item = open.pop();
+            let text = item.text;
+            if (item.tag === "strong")
+                text = wrap(text, "**");
+            else if (item.tag === "em")
+                text = wrap(text, "*");
+            else if (item.tag === "a") {
+                const href = item.href ?? "";
+                // Un indirizzo che non si può scrivere non diventa un link a metà: resta il testo.
+                text = isSafeHref(href) && text.trim() ? `[${text}](${href.trim()})` : text;
+            }
+            emit(text);
+        }
+    }
+    let last = 0;
+    TAG.lastIndex = 0;
+    const source = String(html ?? "");
+    for (let m = TAG.exec(source); m; m = TAG.exec(source)) {
+        emit(unescapeHtml(source.slice(last, m.index)));
+        last = m.index + m[0].length;
+        const closing = m[0].startsWith("</");
+        const name = (m[1] ?? "").toLowerCase();
+        const selfClosing = m[0].endsWith("/>");
+        if (name === "br") {
+            emit("\n");
+            continue;
+        }
+        if (name === "p" || name === "div" || name === "li") {
+            // `div` e `li` non li produciamo noi: li produce il contenteditable, o un incollaggio.
+            closeBlock();
+            continue;
+        }
+        if (selfClosing)
+            continue;
+        const tag = name === "b" ? "strong" : name === "i" ? "em" : name;
+        if (tag !== "strong" && tag !== "em" && tag !== "a")
+            continue; // attraversato: resta il testo
+        if (closing)
+            closeInline(tag);
+        else
+            open.push({ tag, text: "", href: tag === "a" ? attrOf(m[2] ?? "", "href") : undefined });
+    }
+    emit(unescapeHtml(source.slice(last)));
+    closeBlock();
+    /* I blocchi vuoti spariscono: nel pannello sono righe premute per sbaglio, e nel file
+       sarebbero righe vuote in più a ogni salvataggio. È la stessa regola già applicata dai campi
+       che salvano un elenco di paragrafi. */
+    return blocks.join("\n\n");
+}

package/dist/registries.d.ts

@@ -0,0 +1,43 @@
+import * as z from "zod";
+/** Come il campo si presenta nell'admin. */
+export interface UiMeta {
+    label: string;
+    hint?: string;
+    /** Raggruppamento visivo nel form (es. "identità", "visibilità"). */
+    group?: string;
+    widget: "text" | "textarea" | "paragraphs" | "number" | "boolean" | "select" | "menu" | "r2Image" | "r2Gallery" | "r2Curated" | "objectList" | "hidden";
+    placeholder?: string;
+    maxLength?: number;
+    /** Lo schema Zod del campo. Lo inietta SchemaForm; serve a `objectList` per rendere i
+     *  figli con lo stesso registro. Non va dichiarato a mano nello schema del sito. */
+    schema?: unknown;
+    /** Opzioni per `select`. */
+    options?: readonly {
+        value: string;
+        label: string;
+    }[];
+}
+/** Contesto passato a encode/decode. */
+export interface CodecCtx {
+    /** L'elemento intero: serve ai campi che dipendono da altri (es. il peso dentro `menu`). */
+    item: Record<string, unknown>;
+    /** Il front matter grezzo del file esistente. */
+    raw: Record<string, unknown>;
+}
+/** Come il campo vive nel file di contenuto. */
+export interface FmMeta {
+    /** Chiavi di primo livello che questo campo POSSIEDE. Da qui si deriva `MANAGED`. */
+    keys: readonly string[];
+    /** Righe di commento emesse sopra la chiave, quando il file non ne ha già di suoi. */
+    preamble?: readonly string[];
+    /** Valore -> righe YAML. Array vuoto = non emettere nulla. */
+    encode(value: unknown, ctx: CodecCtx): string[];
+    /** Front matter grezzo -> valore. */
+    decode(raw: Record<string, unknown>, ctx?: Partial<CodecCtx>): unknown;
+    merge?: "replace" | "keepIfAbsent";
+    /** Valore calcolato dal server, che vince su quello del client (es. peso dalla posizione). */
+    derived?: (item: Record<string, unknown>, index: number, all: Record<string, unknown>[]) => unknown;
+}
+export declare const ui: z.core.$ZodRegistry<UiMeta, z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+export declare const fm: z.core.$ZodRegistry<FmMeta, z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+export declare function retired(schema: z.ZodType, keys: readonly string[]): z.ZodType;

package/dist/registries.js

@@ -0,0 +1,29 @@
+/* I due registri che accompagnano uno schema Zod.
+ *
+ * Sono DUE e non uno di proposito. `ui` e `fm` hanno consumatori diversi — il form React da una
+ * parte, il serializzatore e il validatore di CI dall'altra — e unirli significherebbe
+ * trascinare vocabolario React dentro codice che gira in un Worker e in uno script di CI.
+ *
+ * L'idea di fondo: un campo si dichiara UNA volta, e porta con sé entrambe le facce. Come si
+ * mostra, e come si scrive su disco. Oggi quelle due facce vivono in file diversi che nessuno
+ * modifica insieme (l'interruttore in app.js, il blocco YAML in pages.js, il calcolo in
+ * index.json), ed è da lì che nasce la possibilità che divergano.
+ */
+import * as z from "zod";
+export const ui = z.registry();
+export const fm = z.registry();
+/* Campo RITIRATO: resta gestito — quindi il serializzatore lo toglie dai file — ma non emette
+ * più nulla. È il modo pulito per far sparire un campo che non serve più (`isHome`), perché i
+ * file si ripuliscono man mano che vengono salvati.
+ * È però un CANCELLATORE INVISIBILE: va usato in un commit dedicato, e il validatore di CI ha
+ * un report apposta che elenca cosa è ritirato e quali file lo contengono ancora. */
+export function retired(schema, keys) {
+    schema.register(ui, { label: "(ritirato)", widget: "hidden" });
+    schema.register(fm, {
+        keys,
+        encode: () => [],
+        decode: () => undefined,
+        merge: "replace",
+    });
+    return schema;
+}

package/dist/serialize.d.ts

@@ -0,0 +1,26 @@
+import type * as z from "zod";
+export type Shape = Record<string, z.ZodType>;
+export type Model = Record<string, unknown>;
+/** Le chiavi di front matter che lo schema possiede.
+ *
+ * Il valore non è la brevità: è che l'insieme delle chiavi gestite e l'insieme delle chiavi
+ * EMESSE nascono dalla stessa dichiarazione, quindi non possono divergere. I due modi di
+ * sbagliare, entrambi silenziosi, erano: una chiave in MANAGED che nessuno emette (viene
+ * cancellata da ogni file al salvataggio successivo) e una chiave emessa e non in MANAGED
+ * (chiave YAML duplicata, e Hugo tiene l'ultima). */
+export declare function managedKeys(shape: Shape): Set<string>;
+/** File markdown -> modello. */
+export declare function deserializeItem(md: string | null, shape: Shape, extra?: Model): Model;
+export interface SerializeOptions {
+    shape: Shape;
+    /** Testo del file esistente, o null se la pagina è nuova. */
+    oldMd?: string | null;
+    /** Corpo di ripiego per una pagina nuova. */
+    placeholderBody?: (model: Model) => string;
+}
+/** Modello -> file markdown. */
+export declare function serializeItem(model: Model, opts: SerializeOptions): string;
+export declare function checkFidelity(md: string, shape: Shape, extra?: Model): {
+    ok: boolean;
+    got?: string;
+};

package/dist/serialize.js

@@ -0,0 +1,136 @@
+import { fm } from "./registries.js";
+import { splitFrontMatter, keptBlocks, parseRawFm, parseBlocks, replaceKeyLine, } from "./frontmatter.js";
+/** Le chiavi di front matter che lo schema possiede.
+ *
+ * Il valore non è la brevità: è che l'insieme delle chiavi gestite e l'insieme delle chiavi
+ * EMESSE nascono dalla stessa dichiarazione, quindi non possono divergere. I due modi di
+ * sbagliare, entrambi silenziosi, erano: una chiave in MANAGED che nessuno emette (viene
+ * cancellata da ogni file al salvataggio successivo) e una chiave emessa e non in MANAGED
+ * (chiave YAML duplicata, e Hugo tiene l'ultima). */
+export function managedKeys(shape) {
+    const out = new Set();
+    for (const field of Object.values(shape)) {
+        for (const k of fm.get(field)?.keys ?? [])
+            out.add(k);
+    }
+    return out;
+}
+function metaOf(field, name) {
+    const m = fm.get(field);
+    if (!m)
+        throw new Error(`Campo "${name}" senza metadati fm: va registrato in schema/site.ts`);
+    return m;
+}
+/** File markdown -> modello. */
+export function deserializeItem(md, shape, extra = {}) {
+    const { fm: fmText, body } = splitFrontMatter(md);
+    const raw = parseRawFm(fmText);
+    const model = { ...extra };
+    for (const [name, field] of Object.entries(shape)) {
+        const v = metaOf(field, name).decode(raw, { raw });
+        if (v !== undefined)
+            model[name] = v;
+    }
+    if (body != null)
+        model.body = body;
+    return model;
+}
+/** Modello -> file markdown. */
+export function serializeItem(model, opts) {
+    const { shape, oldMd = null } = opts;
+    const { fm: fmText, body: oldBody } = splitFrontMatter(oldMd);
+    const raw = parseRawFm(fmText);
+    const managed = managedKeys(shape);
+    const oldBlocks = parseBlocks(fmText);
+    const ctx = { item: model, raw };
+    const lines = ["---"];
+    for (const [name, field] of Object.entries(shape)) {
+        const meta = metaOf(field, name);
+        const strategy = meta.merge ?? "keepIfAbsent";
+        // Assenza != cancellazione. Se il client non ha mandato il campo, si rilegge dal file.
+        const present = Object.prototype.hasOwnProperty.call(model, name);
+        const value = present ? model[name]
+            : strategy === "keepIfAbsent" ? meta.decode(raw, ctx)
+                : undefined;
+        const out = meta.encode(value, ctx);
+        if (!out.length)
+            continue;
+        // Se il file aveva già questa chiave, si riusa il SUO blocco sostituendo la riga del
+        // valore: così restano al loro posto i commenti che la spiegano e la posizione originale.
+        // Saltare il blocco e riemettere la chiave altrove è precisamente il bug che ha cancellato
+        // la documentazione di `r2Prefix` dalle quattro gallery.
+        const existing = meta.keys
+            .map((k) => oldBlocks.find((b) => b.key === k))
+            .find(Boolean);
+        if (existing) {
+            const keyRe = new RegExp(`^${existing.key}\\s*:`);
+            const keyIdx = existing.lines.findIndex((l) => keyRe.test(l));
+            // I commenti che precedono la chiave le APPARTENGONO (li ha attaccati parseBlocks) e
+            // vanno riemessi in entrambi i casi. Perderli quando il valore è su più righe era un
+            // secondo modo di ripetere il bug che aveva cancellato la documentazione di `r2Prefix`:
+            // stessa causa — riscrivere un blocco invece di modificarlo — in una forma diversa.
+            const comments = keyIdx > 0 ? existing.lines.slice(0, keyIdx) : [];
+            if (out.length === 1 && keyIdx >= 0) {
+                // Valore scalare: si sostituisce la RIGA dentro il blocco, così restano al loro posto
+                // sia i commenti sia eventuali righe indentate che seguono.
+                lines.push(...replaceKeyLine(existing.lines, existing.key, out[0]));
+            }
+            else {
+                // Blocco annidato: si riscrive per intero (la struttura può essere cambiata), ma
+                // commenti e righe vuote che lo circondano sopravvivono.
+                //
+                // Le righe vuote non sono estetica: senza conservarle, un file scritto a mano con le
+                // sezioni separate non si riprodurrebbe uguale, la guardia di fedeltà lo
+                // dichiarerebbe illeggibile e l'admin si RIFIUTEREBBE di salvarlo. Una spaziatura
+                // aggiunta da una persona non deve poter bloccare il pannello.
+                const trailing = [];
+                for (let k = existing.lines.length - 1; k >= 0 && /^\s*$/.test(existing.lines[k]); k--) {
+                    trailing.unshift(existing.lines[k]);
+                }
+                lines.push(...comments, ...out, ...trailing);
+            }
+        }
+        else {
+            if (meta.preamble)
+                lines.push(...meta.preamble);
+            lines.push(...out);
+        }
+    }
+    // Tutto ciò che lo schema non gestisce, verbatim.
+    for (const b of keptBlocks(fmText, managed))
+        lines.push(...b.lines);
+    lines.push("---");
+    const raw2 = typeof model.body === "string" && model.body !== ""
+        ? model.body
+        : (oldBody != null && oldBody.trim() !== ""
+            ? oldBody
+            : (opts.placeholderBody?.(model) ?? ""));
+    const testo = String(raw2).replace(/^\n+/, "").replace(/\s+$/, "");
+    // Senza corpo il file finisce con `---` e basta. Aggiungere comunque le due righe che
+    // separano front matter e testo lascerebbe due righe vuote in fondo, e il file non si
+    // riprodurrebbe uguale: per il singleton della home — che un corpo non ce l'ha — significa
+    // che la guardia di fedeltà lo dichiarerebbe illeggibile e il salvataggio verrebbe rifiutato.
+    const body = testo ? "\n" + testo + "\n" : "";
+    return lines.join("\n") + "\n" + body;
+}
+/* GUARDIA DI FEDELTÀ.
+ *
+ * Prima di sovrascrivere un file, si prova a riprodurlo partendo da se stesso. Se il risultato
+ * non combacia, vuol dire che quel file contiene qualcosa che non sappiamo rappresentare — un
+ * `---` dentro un valore quotato che tronca la regex del front matter, un `#` in colonna zero
+ * dentro un blocco di testo che finisce attaccato alla chiave sbagliata — e in quel caso NON lo
+ * si tocca.
+ *
+ * È la voce a più alto valore di tutto il progetto e costa venti righe: trasforma una
+ * corruzione silenziosa in un errore visibile, e sposta la sicurezza da "abbiamo controllato
+ * bene" a "non può succedere". */
+export function checkFidelity(md, shape, extra = {}) {
+    try {
+        const model = deserializeItem(md, shape, extra);
+        const got = serializeItem(model, { shape, oldMd: md });
+        return got === md ? { ok: true } : { ok: false, got };
+    }
+    catch (e) {
+        return { ok: false, got: `errore: ${e.message}` };
+    }
+}

package/dist/testing.d.ts

@@ -0,0 +1,26 @@
+/** Una pagina del sito, già decodificata con lo schema del sito. */
+export interface CheckedPage {
+    /** Come chiamarla nel messaggio d'errore: lo slug, o il percorso del file. */
+    label: string;
+    model: Record<string, unknown>;
+}
+export interface StabilityIssue {
+    page: string;
+    field: string;
+    detail: string;
+}
+/**
+ * I punti in cui normalizzare cambierebbe il contenuto già scritto.
+ *
+ * Un elenco vuoto è la risposta buona. Un elenco pieno significa che aprire quella pagina
+ * nell'editor e toccare un campo qualunque riscriverebbe in silenzio anche le voci che nessuno
+ * ha toccato — e nel diff comparirebbero righe inspiegabili.
+ */
+export declare function contentStabilityIssues(pages: CheckedPage[]): StabilityIssue[];
+/**
+ * Quante pagine hanno davvero qualcosa da verificare.
+ *
+ * Serve a non farsi ingannare da un elenco vuoto: un test che gira su zero pagine passa sempre
+ * e non protegge niente. Ogni sito dovrebbe asserire che questo numero è maggiore di zero.
+ */
+export declare function checkedFieldCount(pages: CheckedPage[]): number;

package/dist/testing.js

@@ -0,0 +1,66 @@
+/* L'INGRESSO `./testing`: le verifiche che ogni sito deve poter fare sui PROPRI contenuti veri.
+ *
+ * Perché sta nel pacchetto invece che in ogni repo. La domanda «normalizzare i miei contenuti
+ * li cambia?» è per-sito: la risposta dipende dai file di QUEL sito. Ma il modo di porla è
+ * identico ovunque, e un controllo identico riscritto a mano in cinque repository è cinque
+ * copie che divergono — con l'aggravante che un test divergente non si limita a sbagliare:
+ * smette di proteggere e non lo dice.
+ *
+ * Non è un'ipotesi. Prima che questo esistesse, `scripts/validate-content.mjs` era già stato
+ * copiato in due siti e i due file divergevano di oltre duecento righe: lo stesso problema che
+ * questo pacchetto risolve un livello sopra, ripetuto un livello sotto dove nessuno guardava.
+ *
+ * React-free di proposito: gira in `node --test`, e i normalizzatori vivono in `normalize.ts`
+ * apposta per non trascinare l'interfaccia dentro una suite di test.
+ */
+import { normalizeCredits, normalizeWorks, normalizeWorkshops, normalizeSections, } from "./normalize.js";
+/* I campi che un editor rimanda indietro NORMALIZZATI invece che com'erano. Aggiungerne uno qui
+ * lo fa verificare su tutti i siti insieme — che è tutto il punto di avere questo in un posto
+ * solo. */
+const CHECKS = [
+    { field: "credits", normalize: normalizeCredits },
+    { field: "works", normalize: normalizeWorks },
+    { field: "workshops", normalize: normalizeWorkshops },
+    { field: "sections", normalize: normalizeSections },
+];
+/**
+ * I punti in cui normalizzare cambierebbe il contenuto già scritto.
+ *
+ * Un elenco vuoto è la risposta buona. Un elenco pieno significa che aprire quella pagina
+ * nell'editor e toccare un campo qualunque riscriverebbe in silenzio anche le voci che nessuno
+ * ha toccato — e nel diff comparirebbero righe inspiegabili.
+ */
+export function contentStabilityIssues(pages) {
+    const issues = [];
+    for (const { label, model } of pages) {
+        for (const { field, normalize } of CHECKS) {
+            const original = model[field];
+            if (original === undefined)
+                continue;
+            const normalized = normalize(original);
+            if (JSON.stringify(normalized) !== JSON.stringify(original)) {
+                issues.push({
+                    page: label,
+                    field,
+                    detail: `normalizzare «${field}» cambia il contenuto già scritto`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Quante pagine hanno davvero qualcosa da verificare.
+ *
+ * Serve a non farsi ingannare da un elenco vuoto: un test che gira su zero pagine passa sempre
+ * e non protegge niente. Ogni sito dovrebbe asserire che questo numero è maggiore di zero.
+ */
+export function checkedFieldCount(pages) {
+    let n = 0;
+    for (const { model } of pages) {
+        for (const { field } of CHECKS)
+            if (model[field] !== undefined)
+                n++;
+    }
+    return n;
+}