@nodefony/drizzle 10.0.0-alpha.1

package/dist/nodefony/src/migrator/explain.js

@@ -0,0 +1,565 @@
+import { HISTORY_TABLE } from "./types.js";
+//#region nodefony/src/migrator/explain.ts
+/**
+* Le RENDU des migrations : un seul producteur, quatre destinataires.
+*
+* La ligne de commande, la sortie `--json`, le plan d'administration et
+* l'assistance affichée dans un corps d'erreur disent tous la même chose. Écrire
+* la phrase pour l'humain d'un côté et l'objet pour la machine de l'autre
+* ferait deux implémentations d'une même règle — et elles divergeraient, comme
+* toutes les copies.
+*
+* ## Ce que ce fichier garantit, et qui n'est pas cosmétique
+*
+* **Aucune sortie ne laisse l'utilisateur sans geste suivant.** Chaque situation
+* — succès, attente, refus, panne — produit trois choses :
+*
+* 1. **le FAIT**, en français, sans terme d'art (« le fichier `0002_x.sql` a
+*    changé après avoir été appliqué ») ;
+* 2. **ce que ça veut dire**, c'est-à-dire la cause la plus probable ;
+* 3. **la commande exacte à copier**, jamais une allusion à une option qu'il
+*    faudrait deviner.
+*
+* Un agent lit `nextActions[0].command` et sait quoi faire sans comprendre le
+* français ; un humain lit les mêmes mots sous une forme lisible. C'est la même
+* donnée.
+*/
+/**
+* Version de la charge utile `--json` **et** du plan d'administration.
+*
+* Contrat public : ajouter un champ est une évolution mineure, en retirer ou en
+* renommer un est interdit sur toute la série majeure. Un `jq` écrit par un
+* utilisateur ne doit jamais casser sur une mise à jour de correctif.
+*/
+const MIGRATION_FORMAT_VERSION = 1;
+/** Grille des codes de sortie — **figée, jamais réaffectée**. */
+const EXIT = {
+	/** À jour, ou appliqué avec succès. */
+	ok: 0,
+	/** Une action humaine est requise sur la base ou sur les fichiers. */
+	actionRequired: 1,
+	/** La commande n'a pas pu faire son travail (verrou, connexion, usage). */
+	error: 2
+};
+/** Fabrique une action affichable et exécutable. */
+function action(command) {
+	return {
+		command,
+		args: command.split(" ").slice(1)
+	};
+}
+/**
+* Situation d'ensemble d'un plan, dans l'ordre de gravité.
+*
+* L'ordre n'est pas esthétique : il dit quel geste vient EN PREMIER. Une
+* migration en échec doit être réparée avant qu'on parle de ce qui reste à
+* appliquer, sinon l'utilisateur lance une commande qui va refuser.
+*
+* @param plan - plan calculé en lecture seule.
+* @param divergent - la base a-t-elle divergé du schéma déclaré ?
+* @returns le verdict, énumération gelée.
+*/
+function verdictOf(plan, divergent = false) {
+	if (plan.failed.length > 0) return "failed";
+	if (plan.drifted.length > 0 || plan.missing.length > 0) return "drift";
+	if (plan.baselineRequired) return "adopt";
+	if (plan.pending.length > 0) return "pending";
+	return divergent ? "divergent" : "up-to-date";
+}
+/**
+* L'historique porte-t-il des migrations que CE code ne connaît pas, et rien
+* d'autre ne cloche-t-il ?
+*
+* C'est l'état NORMAL de deux moments qu'on ne peut pas éviter : une mise à jour
+* progressive, où les anciens exemplaires servent encore pendant que le travail
+* de migration a déjà appliqué la suite ; et un retour arrière, où le code
+* revient en arrière et la base reste en avance. Dans les deux cas, l'exemplaire
+* n'a rien à appliquer, et tout ce qu'il connaît concorde.
+*
+* **Le verdict, lui, reste `drift` — et c'est juste** : ce qui est écrit dans
+* l'historique ne se retrouve pas sur le disque. L'énumération des verdicts est
+* GELÉE avec {@link MIGRATION_FORMAT_VERSION}, et un huitième mot casserait tout
+* consommateur qui les traite exhaustivement. Ce qui était faux n'était pas le
+* constat, c'était ce que la sonde de disponibilité en DÉDUISAIT : retenir le
+* trafic sortait du service tous les anciens exemplaires dès la fin du travail
+* de migration, avant que le premier nouveau soit prêt — une coupure totale sur
+* un déploiement nominal, et l'impossibilité de revenir en arrière.
+*
+* Ce que cette fonction ne couvre PAS, et qui doit continuer de retenir : une
+* empreinte qui a changé (`drifted`), une migration en attente ou en échec, une
+* adoption requise. Une base en avance n'a rien de commun avec un fichier
+* réécrit après coup.
+*
+* @param plan - plan calculé par le migrateur.
+* @returns vrai si le seul écart est un historique en avance sur ce code.
+*/
+function isAheadOnly(plan) {
+	return plan.missing.length > 0 && plan.drifted.length === 0 && plan.pending.length === 0 && plan.failed.length === 0 && !plan.baselineRequired;
+}
+/**
+* Une divergence RETIENT-elle un déploiement ?
+*
+* ## Pourquoi ce n'est pas un simple « le mode vaut-il `fail` »
+*
+* Le défaut est l'observation, et pour une bonne raison : une application qui
+* écrit des migrations libres — vues, déclencheurs, colonnes ajoutées à la main
+* — a une base légitimement différente du schéma déclaré, en permanence. Faire
+* tomber ses déploiements là-dessus rendrait le constat inutilisable, et la
+* première chose qu'on ferait serait de l'éteindre.
+*
+* **Mais ce raisonnement ne couvre pas une TABLE d'entité absente.** Aucune
+* migration libre ne fait disparaître une table que le code déclare comme
+* entité ; quand elle manque, c'est que le schéma applicatif n'a jamais été
+* posé — la migration n'a pas été générée, pas commitée, ou pas appliquée. Ce
+* n'est pas une base « différente », c'est une base sur laquelle l'application
+* ne peut RIEN faire : chacune de ses routes rendra 500, et le pod se serait
+* déclaré prêt.
+*
+* C'est exactement le constat qui a ouvert ce chantier : les onze tables du
+* framework posées, zéro table applicative, et toutes les routes d'entités en
+* erreur — sans qu'aucun verdict ne le dise assez fort pour arrêter quoi que
+* ce soit.
+*
+* La graduation tient donc en trois lignes, et chaque lecteur y trouve son
+* seuil : `off` ne retient jamais, `fail` retient tout écart, `report` — le
+* défaut — retient ce qu'aucune main légitime ne produit.
+*
+* @param divergence - les écarts nommés, ou `null` quand il n'y en a pas.
+* @param mode - `migrations.divergence`, tel que la configuration le déclare.
+* @returns `true` si la situation doit retenir la mise en service.
+*/
+function divergenceIsBlocking(divergence, mode = "report") {
+	if (!divergence || mode === "off") return false;
+	return mode === "fail" || divergence.missingTables.length > 0;
+}
+/**
+* Le code de sortie d'un verdict.
+*
+* **`divergent` ne fait pas tomber un déploiement** quand la configuration le
+* laisse en observation : superviser n'est pas bloquer. C'est ce qui rend le
+* constat utilisable — une application qui écrit des migrations libres a une
+* base légitimement différente du schéma déclaré, en permanence.
+*
+* @param verdict - situation d'ensemble.
+* @param divergenceBlocks - `true` quand la divergence doit retenir la mise en
+*   service, tel que {@link divergenceIsBlocking} en décide.
+* @returns `0`, `1` ou `2`.
+*/
+function exitCodeOf(verdict, divergenceBlocks = false) {
+	if (verdict === "up-to-date") return EXIT.ok;
+	if (verdict === "divergent") return divergenceBlocks ? EXIT.actionRequired : EXIT.ok;
+	return EXIT.actionRequired;
+}
+/** Regroupe les entrées d'un plan par source, en gardant l'ordre. */
+function groupSources(plan) {
+	const byName = /* @__PURE__ */ new Map();
+	const ensure = (name) => {
+		let entry = byName.get(name);
+		if (!entry) {
+			entry = {
+				name,
+				applied: 0,
+				pending: 0,
+				failed: 0,
+				pendingTags: [],
+				drifted: [],
+				missing: [],
+				entries: []
+			};
+			byName.set(name, entry);
+		}
+		return entry;
+	};
+	const detail = (row) => ({
+		tag: row.tag,
+		status: row.success ? "applied" : "failed",
+		appliedAt: row.startedAt,
+		...row.executionMs !== null ? { durationMs: row.executionMs } : {},
+		...row.appliedBy !== null ? { appliedBy: row.appliedBy } : {},
+		runId: row.runId,
+		...row.error !== null ? { error: row.error } : {}
+	});
+	for (const row of plan.applied) {
+		const entry = ensure(row.source);
+		entry.applied += 1;
+		entry.entries.push(detail(row));
+	}
+	for (const file of plan.pending) {
+		const entry = ensure(file.source);
+		entry.pending += 1;
+		entry.pendingTags.push(file.tag);
+		entry.entries.push({
+			tag: file.tag,
+			status: "pending"
+		});
+	}
+	for (const row of plan.failed) {
+		const entry = ensure(row.source);
+		entry.failed += 1;
+		entry.entries.push(detail(row));
+	}
+	for (const d of plan.drifted) {
+		const entry = ensure(d.source);
+		entry.drifted.push({
+			tag: d.tag,
+			expected: d.expected,
+			actual: d.actual
+		});
+		const already = entry.entries.find((e) => e.tag === d.tag);
+		if (already) already.status = "drifted";
+		else entry.entries.push({
+			tag: d.tag,
+			status: "drifted"
+		});
+	}
+	for (const m of plan.missing) {
+		const entry = ensure(m.source);
+		entry.missing.push(m.tag);
+		entry.entries.push({
+			tag: m.tag,
+			status: "missing"
+		});
+	}
+	return [...byName.values()];
+}
+/**
+* Compose la charge utile complète d'un état de migration.
+*
+* @param plan - plan calculé en lecture seule.
+* @param ctx - mode de schéma et conduite face à la divergence.
+* @returns la charge utile, identique pour la ligne de commande, `--json`, le
+*   plan d'administration et la sonde.
+*/
+function buildReport(plan, ctx) {
+	const divergence = ctx.divergence ?? null;
+	const verdict = verdictOf(plan, divergence !== null);
+	const sources = groupSources(plan);
+	return {
+		formatVersion: 1,
+		connector: plan.connector,
+		verdict,
+		exitCode: exitCodeOf(verdict, divergenceIsBlocking(divergence, ctx.divergenceMode)),
+		summary: summaryOf(plan, verdict, divergence),
+		nextActions: actionsOf(plan, verdict, ctx.canReset === true && ctx.ddl === "auto", divergence),
+		sources,
+		...divergence ? { divergence } : {},
+		driver: {
+			kind: "sql",
+			dialect: plan.dialect,
+			ddl: ctx.ddl,
+			historyTable: HISTORY_TABLE,
+			...ctx.target === void 0 ? {} : { target: ctx.target },
+			...ctx.fromMigrateUrl === void 0 ? {} : { fromMigrateUrl: ctx.fromMigrateUrl }
+		}
+	};
+}
+/** Combien d'écarts par famille la PHRASE nomme avant de dire « et N de plus ». */
+const SUMMARY_GAPS = 3;
+/**
+* La phrase a-t-elle nommé TOUS les écarts, ou en a-t-elle tronqué ?
+*
+* Sert au seul rendu à l'écran : quand la phrase dit déjà tout, dérouler la
+* même chose juste au-dessus est du bruit — et le bruit est ce qui fait
+* arrêter de lire une sortie d'incident.
+*
+* @param d - les écarts.
+* @returns `true` si aucune famille n'a été tronquée.
+*/
+function namesEverything(d) {
+	return d.missingTables.length <= SUMMARY_GAPS && d.blocking.length <= SUMMARY_GAPS && d.additive.length <= SUMMARY_GAPS;
+}
+/**
+* Ce qui diverge, EN TOUTES LETTRES — tables et colonnes nommées.
+*
+* C'est la moitié utile du verdict `divergent`. Sans elle, « la base ne
+* correspond pas au schéma déclaré » envoie ouvrir un client SQL et comparer
+* table par table, sur une base de production, au pire moment — pour une
+* réponse que le produit avait déjà calculée.
+*
+* **Bornée à trois entrées par famille**, dans l'ordre de gravité : une phrase
+* qui déroule quarante colonnes n'est plus lue. Le compte total reste dit, et
+* `IMigrationReport.divergence` porte la liste ENTIÈRE pour qui la veut.
+*
+* @param d - les écarts, tels que la comparaison les a séparés.
+* @returns la phrase, sans point final ni majuscule initiale.
+*/
+function nameGaps(d) {
+	const parts = [];
+	const pushBounded = (names, singular, plural) => {
+		if (names.length === 0) return;
+		const remainder = names.length > SUMMARY_GAPS ? `, et ${names.length - SUMMARY_GAPS} de plus` : "";
+		parts.push(`${names.length > 1 ? plural : singular} ${names.slice(0, SUMMARY_GAPS).join(", ")}${remainder}`);
+	};
+	const col = (g) => `« ${g.table}.${g.column} »`;
+	pushBounded(d.missingTables.map((t) => `« ${t} »`), "table absente :", "tables absentes :");
+	pushBounded(d.blocking.map(col), "colonne manquante et OBLIGATOIRE :", "colonnes manquantes et OBLIGATOIRES :");
+	pushBounded(d.additive.map(col), "colonne manquante :", "colonnes manquantes :");
+	return parts.join(" ; ");
+}
+/** Le FAIT, en une phrase, sans terme d'art. */
+function summaryOf(plan, verdict, divergence = null) {
+	const c = plan.connector;
+	switch (verdict) {
+		case "up-to-date": return `Le connecteur « ${c} » est à jour : tout ce qui est enregistré a été appliqué, et les fichiers n'ont pas bougé depuis.`;
+		case "pending": {
+			const n = plan.pending.length;
+			const names = plan.pending.slice(0, 3).map((f) => `${f.source}/${f.tag}`).join(", ");
+			const remainder = n > 3 ? `, et ${n - 3} de plus` : "";
+			return `Le connecteur « ${c} » a ${n} migration${n > 1 ? "s" : ""} à appliquer : ${names}${remainder}.`;
+		}
+		case "drift": {
+			const parts = [];
+			if (plan.drifted.length > 0) {
+				const d = plan.drifted[0];
+				parts.push(`le fichier « ${d.source}/${d.tag} » a été modifié APRÈS avoir été appliqué (son empreinte a changé)`);
+			}
+			if (plan.missing.length > 0) {
+				const m = plan.missing[0];
+				parts.push(`la migration « ${m.source}/${m.tag} » est enregistrée comme appliquée mais son fichier n'existe plus`);
+			}
+			return `Le connecteur « ${c} » ne concorde plus avec son historique : ${parts.join(" ; ")}.`;
+		}
+		case "failed": {
+			const f = plan.failed[0];
+			const when = f.startedAt ? new Date(f.startedAt).toISOString() : "à une date inconnue";
+			const why = f.error ? ` (erreur : ${f.error})` : "";
+			return `Le connecteur « ${c} » porte ${plan.failed.length} migration${plan.failed.length > 1 ? "s" : ""} qui n'a pas abouti : « ${f.source}/${f.tag} », commencée le ${when}${why}.`;
+		}
+		case "adopt": return `La base du connecteur « ${c} » contient déjà des tables, mais aucune migration n'y est enregistrée. Nodefony ne devine pas : appliquer les migrations sur une base déjà peuplée écraserait peut-être une base qui n'est pas la bonne.`;
+		case "divergent": return `Le connecteur « ${c} » a son historique complet et rien en attente, et la base ne correspond pourtant pas au schéma déclaré dans le code${divergence ? ` — ${nameGaps(divergence)}` : ""}. ${divergence && divergence.missingTables.length > 0 ? `L'application ne peut PAS servir ces entités : leur migration n'a jamais été générée, commitée ou appliquée.` : `Quelqu'un a modifié la base directement, ou un correctif d'urgence n'a pas été reporté.`}`;
+	}
+}
+/**
+* Ce qu'il faut TAPER, du plus direct au plus assumé.
+*
+* @param plan - plan calculé en lecture seule.
+* @param verdict - situation d'ensemble.
+* @param canReset - `orm:reset` est-elle acceptée dans cet environnement ?
+* @param divergence - les écarts nommés : le geste n'est pas le même selon
+*   qu'il manque une colonne ou une table entière.
+* @returns les gestes, dans l'ordre où les tenter.
+*/
+function actionsOf(plan, verdict, canReset = false, divergence = null) {
+	const c = plan.connector;
+	const suffixe = c === "default" ? "" : ` --connector ${c}`;
+	switch (verdict) {
+		case "up-to-date": return [];
+		case "pending": return [action(`nodefony orm:migrate${suffixe}`), action(`nodefony orm:migrate${suffixe} --dry-run`)];
+		case "drift": {
+			const out = [];
+			if (plan.drifted.length > 0) {
+				out.push(action(`git checkout -- migrations/`));
+				out.push(action(`nodefony orm:migrate:repair${suffixe} --update-hashes`));
+			}
+			if (plan.missing.length > 0) out.push(action(`nodefony orm:migrate${suffixe} --ignore-missing`));
+			return out;
+		}
+		case "failed": return [
+			action(`nodefony orm:migrate:status${suffixe} --json`),
+			action(`nodefony orm:migrate:repair${suffixe}`),
+			action(`nodefony orm:migrate${suffixe}`)
+		];
+		case "adopt": return [action(`nodefony orm:migrate:baseline${suffixe}`), action(`nodefony orm:migrate:status${suffixe}`)];
+		case "divergent":
+			if (divergence && divergence.missingTables.length > 0) return [
+				action(`nodefony orm:generate${suffixe} --name rattrapage_schema`),
+				action(`nodefony orm:migrate${suffixe}`),
+				action(`nodefony orm:migrate:status${suffixe} --json`)
+			];
+			return canReset ? [action(`nodefony orm:migrate:status${suffixe} --json`), action(`nodefony orm:reset${suffixe}`)] : [
+				action(`nodefony orm:migrate:status${suffixe} --json`),
+				action(`nodefony orm:generate${suffixe} --custom --name rattrapage_schema`),
+				action(`nodefony orm:migrate${suffixe}`)
+			];
+	}
+}
+/**
+* Ce que le verdict veut dire — la CAUSE, entre le fait et le geste.
+*
+* C'est le bloc qu'on omet d'habitude, et c'est celui qui évite l'appel au
+* collègue : l'utilisateur sait ce qui s'est passé, donc il sait si le geste
+* proposé lui convient.
+*
+* @param verdict - situation d'ensemble.
+* @returns une ou deux phrases, ou une chaîne vide si le fait se suffit.
+*/
+function meaningOf(verdict) {
+	switch (verdict) {
+		case "up-to-date": return "";
+		case "pending": return "C'est la situation normale après avoir tiré du code qui change le schéma, ou avant un déploiement. Rien n'a encore été modifié dans la base.";
+		case "drift": return "Un fichier de migration ne se modifie jamais après avoir été appliqué : d'autres bases ont reçu l'ancienne version, et elles ne recevront jamais la nouvelle. Le geste normal est de restaurer le fichier et d'écrire une NOUVELLE migration. Ré-aligner les empreintes ne se fait que si l'on sait que la modification était sans effet.";
+		case "failed": return "La migration s'est arrêtée en cours de route. Selon la base, elle a pu laisser un état partiel : MySQL valide chaque instruction de schéma sans possibilité de retour, PostgreSQL et SQLite annulent la migration fautive entière. Regarde l'état réel de la base AVANT de lever le marqueur — c'est ce que « réparer » veut dire ici, et rien d'autre.";
+		case "adopt": return "Cela arrive quand on branche Nodefony sur une base qui existait déjà, ou quand on a créé les tables autrement (schéma dérivé du code en développement). Déclarer la base à niveau enregistre les migrations comme appliquées SANS les exécuter. Vérifie d'abord que c'est bien la base attendue.";
+		case "divergent": return "Aucun outil de migration ne regarde la base elle-même : ils comparent les fichiers à l'historique et concluent. Nodefony compare aussi au schéma déclaré dans le code, ce qui rend ce cas visible. Il n'est PAS bloquant par défaut, parce qu'une application qui écrit des migrations libres a légitimement une base différente du schéma déclaré.";
+	}
+}
+/**
+* Construit le styliste : couleurs en terminal, texte nu ailleurs.
+*
+* @param tty - la sortie est-elle un terminal ?
+* @returns les fonctions de mise en forme.
+*/
+function styleFor(tty) {
+	const wrap = (code) => (s) => tty ? `\x1b[${code}m${s}\x1b[0m` : s;
+	return {
+		bold: wrap("1"),
+		dim: wrap("2"),
+		green: wrap("32"),
+		yellow: wrap("33"),
+		red: wrap("31")
+	};
+}
+/** Rend les trois blocs — le fait, ce que ça veut dire, ce qu'il faut taper. */
+function renderBlocks(style, summary, meaning, actions, actionTitle = "À faire") {
+	let out = `${summary}\n`;
+	if (meaning) out += `\n${style.dim(meaning)}\n`;
+	if (actions.length > 0) {
+		out += `\n${style.bold(`${actionTitle} :`)}\n`;
+		for (const a of actions) out += `  ${style.green(a.command)}\n`;
+	}
+	return out;
+}
+/**
+* Rendu humain d'un état de migration — l'écran que voit celui qui tape
+* `orm:migrate:status`.
+*
+* @param report - charge utile complète.
+* @param style - mise en forme (couleurs ou texte nu).
+* @returns le texte prêt à écrire sur la sortie standard.
+*/
+function renderStatus(report, style) {
+	const badge = {
+		"up-to-date": style.green("✓ à jour"),
+		pending: style.yellow("→ en attente"),
+		drift: style.red("⚠ ne concorde plus"),
+		failed: style.red("✗ migration interrompue"),
+		adopt: style.yellow("? base à déclarer"),
+		divergent: style.yellow("≠ base différente du code")
+	};
+	let out = `${style.bold(`Connecteur ${report.connector}`)} ${style.dim(`(${report.driver.dialect}, schéma : ${report.driver.ddl}, historique : ${report.driver.historyTable})`)}\n`;
+	if (report.driver.fromMigrateUrl === true) out += `  ${style.yellow(`⚠ NF_MIGRATE_DATABASE_URL détourne ce connecteur vers ${report.driver.target ?? "une autre base"}`)}\n`;
+	out += `  ${badge[report.verdict]}\n\n`;
+	for (const s of report.sources) {
+		const bits = [`${s.applied} appliquée${s.applied > 1 ? "s" : ""}`, `${s.pending} en attente`];
+		if (s.failed > 0) bits.push(style.red(`${s.failed} interrompue(s)`));
+		if (s.drifted.length > 0) bits.push(style.red(`${s.drifted.length} modifiée(s) après coup`));
+		if (s.missing.length > 0) bits.push(style.red(`${s.missing.length} fichier(s) disparu(s)`));
+		out += `  ${style.bold(s.name.padEnd(12))} ${bits.join(" · ")}\n`;
+		if (s.pendingTags.length > 0) out += `  ${" ".repeat(12)} ${style.dim(`→ ${s.pendingTags.join(", ")}`)}\n`;
+	}
+	if (report.sources.length === 0) out += `  ${style.dim("aucune source de migrations")}\n`;
+	if (report.divergence && !namesEverything(report.divergence)) out += renderDivergence(report.divergence, style);
+	out += `\n${renderBlocks(style, report.summary, meaningOf(report.verdict), report.nextActions)}`;
+	return out;
+}
+/** Combien d'écarts on déroule à l'écran avant de renvoyer au `--json`. */
+const DIVERGENCE_LINES = 10;
+/**
+* La LISTE des écarts, à l'écran — ce que le résumé n'a pas la place de dire.
+*
+* Le résumé nomme les trois premiers de chaque famille, parce qu'une phrase
+* doit rester lisible ; ici on déroule, parce que c'est précisément la liste
+* que l'exploitant serait allé chercher à la main dans un client SQL. Au-delà
+* de {@link DIVERGENCE_LINES} entrées, on s'arrête et on dit où est le reste :
+* un écran de quarante lignes ne se lit pas davantage qu'une phrase de
+* quarante noms.
+*
+* @param d - les écarts, séparés selon qu'ils se rattrapent ou non.
+* @param style - mise en forme.
+* @returns le bloc, prêt à concaténer.
+*/
+function renderDivergence(d, style) {
+	const lines = [
+		...d.missingTables.map((t) => `${"table".padEnd(9)} ${t}`),
+		...d.blocking.map((g) => `${"colonne".padEnd(9)} ${g.table}.${g.column} ` + style.red(`(${g.type}, OBLIGATOIRE — ne se rattrape pas)`)),
+		...d.additive.map((g) => `${"colonne".padEnd(9)} ${g.table}.${g.column} ` + style.dim(`(${g.type}, se rattrape)`))
+	];
+	let out = `\n  ${style.bold("Ce qui manque dans la base :")}\n`;
+	for (const l of lines.slice(0, DIVERGENCE_LINES)) out += `    ${l}\n`;
+	if (lines.length > DIVERGENCE_LINES) out += `    ${style.dim(`… et ${lines.length - DIVERGENCE_LINES} autre(s) — la liste entière est dans « --json », sous « divergence »`)}\n`;
+	return out;
+}
+/**
+* Rendu humain de ce que la DÉCOUVERTE des entités a vu.
+*
+* Bloc court, posé sous les refus dont la cause peut être un schéma déclaré
+* amputé : un fichier illisible, une table écrite pour un autre moteur, un
+* dossier d'entités qui ne rend rien. L'outil de diff ne distingue pas une
+* table absente d'une table SUPPRIMÉE — sans ces trois nombres, la correction
+* naturelle porte sur la base, qui n'y est pour rien.
+*
+* @param facts - ce que la découverte a relevé.
+* @param style - mise en forme.
+* @returns le bloc, prêt à concaténer ; vide si rien n'appelle l'attention.
+*/
+function describeDiscovery(facts, style) {
+	let out = `\n${style.bold("Ce que la découverte a vu")} ${style.dim(`(${facts.filesScanned} fichier(s) d'entités examiné(s))`)} :\n  • ${facts.tables.length} table(s) de l'application retenue(s)${facts.tables.length > 0 ? ` : ${facts.tables.join(", ")}` : ""}\n`;
+	if (facts.otherDialect.length > 0) out += `  • ${facts.otherDialect.length} écartée(s), écrite(s) pour un autre moteur :\n` + facts.otherDialect.map((o) => `      ${o.table} (${o.dialect}) — ${o.file}\n`).join("");
+	if (facts.unreadable.length > 0) out += `  • ${facts.unreadable.length} fichier(s) que la découverte n'a PAS su lire :\n` + facts.unreadable.map((u) => `      ${u.file} — ${u.cause}\n`).join("");
+	if (facts.unreadable.length > 0 || facts.otherDialect.length > 0 || facts.tables.length === 0) out += `\n${style.dim("Une table qui n'entre pas dans cette découverte se présente à l'outil de diff comme une table SUPPRIMÉE. Avant de toucher à la base, vérifier que ces fichiers fournissent bien les tables attendues pour CE moteur : le défaut est alors dans le dossier d'entités, et la base n'y est pour rien.")}\n`;
+	return out;
+}
+/**
+* Rendu humain d'un REFUS de l'applicateur.
+*
+* Un refus est un contrat, pas un message : il énonce le fait, ce qu'il
+* signifie, et donne la commande exacte à copier. L'utilisateur ne doit jamais
+* avoir eu connaissance d'une option à l'avance.
+*
+* @param verdict - verdict structuré porté par le refus.
+* @param message - phrase française déjà composée par l'applicateur.
+* @param style - mise en forme.
+* @param ddl - mode de schéma effectif, quand il change la cause (cf {@link refusalInMode}).
+* @returns le texte prêt à écrire sur la sortie d'erreur.
+*/
+function renderRefusal(verdict, message, style, ddl) {
+	const enMode = ddl ? refusalInMode(verdict.code, ddl, verdict.connector) : null;
+	const meaning = enMode?.meaning ?? REFUSAL_MEANING[verdict.code] ?? "";
+	const actions = enMode?.actions ?? verdict.nextActions;
+	return `${style.red(style.bold("Migration refusée"))} ${style.dim(`[${verdict.code}]`)}\n\n` + renderBlocks(style, message, meaning, actions);
+}
+/**
+* Ce qu'un refus veut dire QUAND ON CONNAÎT LE MODE DE SCHÉMA.
+*
+* Le même fait mécanique n'a pas la même cause selon le mode, et le geste
+* change avec la cause. Constaté en exécutant la commande pour de vrai : sur une
+* base parfaitement NEUVE, en développement, `orm:migrate` refuse en disant que
+* la base « porte déjà les tables ». C'est exact — et c'est le DÉMARRAGE
+* lui-même qui vient de les créer, quelques millisecondes plus tôt, parce que le
+* mode `auto` dérive le schéma du code. Sans cette précision, l'utilisateur
+* cherche une base ancienne qui n'existe pas.
+*
+* @param code - code du refus.
+* @param ddl - mode de schéma effectif du connecteur.
+* @param connector - connecteur concerné, pour composer les gestes.
+* @returns l'explication et les gestes, ou `null` si le refus se suffit.
+*/
+function refusalInMode(code, ddl, connector) {
+	if (code !== "NF_MIGRATE_BASELINE_REQUIRED" || ddl !== "auto") return null;
+	const suffixe = connector === "default" ? "" : ` --connector ${connector}`;
+	return {
+		meaning: "Ce connecteur est en mode `auto` : c'est le DÉMARRAGE qui fabrique le schéma à partir du code, et il vient de le faire — les tables existent donc déjà, même sur une base créée à l'instant. Ne cherche pas une vieille base : les deux façons de fabriquer un schéma se croisent, c'est tout. Trois issues, selon ce que tu veux vraiment. Éprouver les migrations comme en production : repars d'une base vide avec le mode `none` — c'est un réglage du connecteur, pas une variable posée devant la commande. Repartir de zéro en développement : vide la base. Garder cette base et la déclarer à niveau : adopte-la (aucun SQL ne sera exécuté).",
+		actions: [action(`nodefony orm:reset${suffixe}`), action(`nodefony orm:migrate:baseline${suffixe}`)]
+	};
+}
+/**
+* Ce que chaque refus de l'applicateur veut dire, en clair.
+*
+* Table complète et exhaustive par construction : le type est indexé par
+* l'union des codes, donc en ajouter un sans écrire sa phrase ne compile pas.
+* C'est le seul moyen d'avoir la garantie qu'aucun refus ne sortira nu.
+*/
+const REFUSAL_MEANING = {
+	NF_MIGRATE_BASELINE_REQUIRED: "La base contient déjà des tables alors qu'aucune migration n'y est enregistrée. Appliquer les migrations maintenant exécuterait des créations de tables qui existent — souvent parce qu'on s'est trompé de base. Déclarer la base à niveau enregistre les migrations comme appliquées sans les exécuter ; à ne faire qu'après avoir vérifié que c'est la bonne base.",
+	NF_MIGRATE_FAILED_MARKER: "Une migration précédente s'est arrêtée en cours de route. Reprendre à l'aveugle par-dessus un état partiel est le meilleur moyen d'aggraver la situation. Regarde l'état réel de la base, corrige-le si besoin, puis lève le marqueur.",
+	NF_MIGRATE_HASH_MISMATCH: "Un fichier déjà appliqué a été modifié depuis. Les autres bases ont reçu l'ancienne version et ne recevront jamais la nouvelle : le fichier et la réalité ont divergé. Le geste normal est de restaurer le fichier et d'écrire une nouvelle migration.",
+	NF_MIGRATE_OUT_OF_ORDER: "Une migration en attente se range avant la dernière appliquée de sa source — c'est la trace d'une fusion de branches. L'appliquer quand même est souvent juste, mais c'est une décision : deux bases pourraient ne pas avoir reçu les mêmes changements dans le même ordre.",
+	NF_MIGRATE_MISSING_FILE: "Une migration enregistrée comme appliquée n'a plus de fichier, alors que sa source est bien présente. Soit le fichier a été supprimé par erreur, soit la base a connu une version du code que ce dépôt ne contient pas.",
+	NF_MIGRATE_UNKNOWN_FORMAT: "Un fichier ne porte pas le format que cet applicateur sait lire. Lire au mieux un fichier d'un format inconnu, c'est exécuter du SQL découpé au hasard — donc jamais.",
+	NF_MIGRATE_LOCK_TIMEOUT: "Un autre processus applique des migrations sur cette base, ou en a laissé le verrou pris. Le verrou est tenu par une connexion : il se libère tout seul quand la connexion meurt. Vérifie qu'aucun autre travail de migration ne tourne, puis relance.",
+	NF_MIGRATE_UNKNOWN_TAG: "Le tag demandé ne désigne aucune migration connue — une faute de frappe, ou une casse qui diffère. Le refus est là pour une raison précise : sans point d'arrêt, l'adoption déclare à niveau TOUTES les migrations, y compris celles que la base n'a jamais reçues. Elle ne les recevrait alors plus jamais.",
+	NF_MIGRATE_JOURNAL_MISMATCH: "Le journal d'une source annonce une migration dont le fichier n'est pas dans le dossier. La source est incohérente avec elle-même : une copie incomplète, un fichier ignoré par le gestionnaire de versions, ou un paquet publié sans ses migrations. Rien n'a été appliqué — l'applicateur ne devine jamais le contenu d'un fichier absent.",
+	NF_MIGRATE_UNKNOWN_SOURCE: "La source demandée n'est pas déclarée par cette application. Filtrer sur un nom inconnu ne touche aucune ligne et rend pourtant « rien à réparer » : le marqueur d'échec resterait en place, et la migration suivante échouerait pour la même raison."
+};
+//#endregion
+export { EXIT, MIGRATION_FORMAT_VERSION, action, buildReport, describeDiscovery, divergenceIsBlocking, exitCodeOf, isAheadOnly, meaningOf, refusalInMode, renderRefusal, renderStatus, styleFor, verdictOf };

package/dist/nodefony/src/migrator/hash.js

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+//#region nodefony/src/migrator/hash.ts
+/**
+* Empreinte d'un fichier de migration : **normalisée** et **auto-descriptive**.
+*
+* Deux gestes, deux raisons distinctes.
+*
+* **Normalisée** (CRLF → LF) : Windows est un impératif produit, et un checkout
+* sous `core.autocrlf` réécrit les `.sql`. Hacher les octets bruts ferait
+* diverger toutes les empreintes de celles posées par l'image Linux qui a migré
+* la base d'équipe — arrêt sur dérive permanent, pour un non-changement. Le
+* garde-fou reste entier : toute modification RÉELLE du SQL déclenche l'arrêt,
+* seule la représentation des fins de ligne cesse de compter.
+*
+* **Préfixée de son algorithme** (`sha256:<hex>`) : c'est la seule porte de
+* sortie pour introduire un jour un autre algorithme en RECONNAISSANT les
+* lignes anciennes, sans réécrire une seule base de production.
+*
+* @param content - contenu du fichier `.sql`, tel que lu sur le disque.
+* @returns l'empreinte préfixée, telle qu'elle est stockée en base.
+*/
+function migrationHash(content) {
+	return `sha256:${createHash("sha256").update(normalizeSql(content), "utf8").digest("hex")}`;
+}
+/**
+* Normalise un contenu SQL : marque d'ordre des octets retirée, fins de ligne en LF.
+*
+* Les deux gestes répondent au même fait — **le fichier a voyagé** — et doivent
+* donc vivre au même endroit, sous peine de ne corriger qu'une moitié du
+* problème.
+*
+* **La marque d'ordre des octets** (`U+FEFF`) est posée en tête par les
+* éditeurs Windows et par PowerShell (`>` et `Out-File` l'écrivent par défaut).
+* `fs.readFile(…, "utf8")` ne la retire pas : elle reste le premier caractère du
+* contenu. Sans ce nettoyage, la première ligne cesse d'être reconnue comme le
+* marqueur de format, et le refus affiche deux chaînes **visuellement
+* identiques** — « attendu ceci, lu cela », avec ceci et cela à l'œil pareils.
+* C'est le pire message d'erreur possible : celui qui n'apprend rien.
+*
+* @param content - contenu brut, tel que lu sur le disque.
+* @returns le même contenu, sans marque d'ordre des octets et en LF.
+*/
+function normalizeSql(content) {
+	return (content.charCodeAt(0) === 65279 ? content.slice(1) : content).replace(/\r\n/g, "\n");
+}
+//#endregion
+export { migrationHash, normalizeSql };