@nodefony/drizzle 10.0.0-alpha.1

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

@@ -0,0 +1,88 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+//#region nodefony/src/migrator/paths.ts
+/** Nom logique RÉSERVÉ de la source livrée par le framework. */
+const FRAMEWORK_SOURCE = "framework";
+/** Nom logique RÉSERVÉ de la source livrée par l'application. */
+const APP_SOURCE = "app";
+/** Rang de la source framework : première appliquée, toujours. */
+const FRAMEWORK_RANK = 0;
+/**
+* Rang de la source application : dernière appliquée, toujours.
+*
+* Les entités d'une application peuvent référencer les tables du framework et
+* celles des modules ; l'inverse n'arrive jamais.
+*/
+const APP_RANK = 1e6;
+/** Dossier de migrations, mémoïsé — la remontée ne se fait qu'une fois. */
+let cachedDir = null;
+/**
+* Dossier des migrations livrées par ce paquet.
+*
+* **Trouvé en remontant jusqu'au `package.json` du paquet**, jamais par un
+* nombre de niveaux codé en dur : la profondeur diffère entre les sources
+* (`nodefony/src/migrator/`) et le paquet bâti (`dist/nodefony/src/migrator/`),
+* et un compte figé serait juste d'un côté, faux de l'autre — sans que rien ne
+* le signale avant l'exécution chez un utilisateur.
+*
+* @returns le chemin absolu du dossier `migrations` du paquet.
+* @throws Error si la racine du paquet est introuvable.
+*/
+async function frameworkMigrationsDir() {
+	if (cachedDir !== null) return cachedDir;
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	for (;;) {
+		const manifest = path.join(dir, "package.json");
+		try {
+			const raw = await fs.readFile(manifest, "utf8");
+			if (JSON.parse(raw).name === "@nodefony/drizzle") {
+				cachedDir = path.join(dir, "migrations");
+				return cachedDir;
+			}
+		} catch {}
+		const parent = path.dirname(dir);
+		if (parent === dir) throw new Error("Migrations : racine du paquet `@nodefony/drizzle` introuvable — le dossier `migrations` livré ne peut pas être résolu.");
+		dir = parent;
+	}
+}
+/**
+* Registre de sources standard : le framework, puis l'application.
+*
+* L'espace de noms reste OUVERT — un module tiers ajoute la sienne au même
+* registre, avec son propre rang. `framework` et `app` sont deux valeurs
+* réservées, pas une énumération.
+*
+* **Le framework ne fournit ses migrations que s'il déclare ses entités.** Un
+* module réglé `frameworkEntities: false` est data-only : il n'enregistre ni
+* entité ni fabrique, et le démarrage en mode dérivé ne crée donc aucune table
+* de session, de jeton, d'audit ni de webhook. Les inclure ici quand même
+* faisait fabriquer DEUX bases différentes à la même application selon qu'elle
+* démarrait en développement ou qu'on la migrait en production — et rien ne le
+* disait, le verdict de divergence ignorant par construction ce que la base a
+* en TROP.
+*
+* La règle vit ICI, à l'endroit unique où les sources se composent : ses deux
+* appelants (le service au démarrage, les commandes) la recopieraient sinon, et
+* deux copies divergent en silence.
+*
+* @param appDir - dossier de migrations de l'application, s'il y en a un.
+* @param options.framework - `false` quand le module est data-only.
+* @returns le registre, prêt pour l'applicateur.
+*/
+async function defaultMigrationSources(appDir, options = {}) {
+	const sources = [];
+	if (options.framework !== false) sources.push({
+		name: FRAMEWORK_SOURCE,
+		dir: await frameworkMigrationsDir(),
+		rank: 0
+	});
+	if (appDir) sources.push({
+		name: "app",
+		dir: appDir,
+		rank: APP_RANK
+	});
+	return sources;
+}
+//#endregion
+export { APP_RANK, APP_SOURCE, FRAMEWORK_RANK, FRAMEWORK_SOURCE, defaultMigrationSources, frameworkMigrationsDir };

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

@@ -0,0 +1,143 @@
+import { MIGRATE_URL_ENV } from "./types.js";
+import { action } from "./explain.js";
+import { knownConnectors } from "./resolve.js";
+//#region nodefony/src/migrator/refusals.ts
+/**
+* Les refus de RÉSOLUTION, rendus en VALEUR — la prose qu'un connecteur non
+* migrable mérite, sans supposer qui la lira.
+*
+* **Pourquoi ce fichier existe** : ces quatre messages étaient écrits dans la
+* commande, mêlés à l'écriture sur la sortie et au code de sortie. Ils ont
+* pourtant DEUX lecteurs — la ligne de commande, et le plan d'administration
+* qui alimente l'écran de la console. Les recopier de l'autre côté aurait posé
+* deux vérités sur la même question ; les laisser dans la commande aurait
+* obligé l'écran à réinventer les siennes, plus courtes, donc plus fausses.
+*
+* Aucune entrée-sortie ici, aucun style, aucun code de sortie : une fonction
+* reçoit une résolution et rend ce qu'il y a à en dire. C'est ce qui la rend
+* éprouvable sans base, sans kernel et sans terminal.
+*/
+/** Nom du module qui porte la configuration des connecteurs SQL. */
+const MODULE_NAME = "drizzle";
+/**
+* L'outil qui ÉCRIT les migrations n'est pas installé.
+*
+* Refus À PART, et c'est tout son intérêt : sans lui, cette cause tombait dans
+* le fourre-tout des commandes de migration, qui habille toute exception non
+* typée d'un `meaning` écrit pour la base injoignable. La charge utile portait
+* alors DEUX explications qui se contredisent — le fait disait « l'outil
+* manque », l'explication disait « vérifie que la base est démarrée » — et ses
+* deux gestes interrogeaient une base qui n'y était pour rien.
+*
+* @returns le refus, avec le geste qui répare.
+*/
+function generationToolMissing() {
+	return {
+		code: "NF_GENERATE_TOOL_MISSING",
+		summary: "L'outil qui écrit les migrations (`drizzle-kit`) n'est pas installé : rien n'a été écrit.",
+		meaning: "Écrire une migration demande un outil de DÉVELOPPEMENT, que l'application déclare mais qui n'est pas dans « node_modules » — un `npm install` manque, ou l'installation s'est faite sans les dépendances de développement (`--omit=dev`). La base n'est pas en cause : appliquer des migrations, lui, ne réclame aucun outil tiers.",
+		nextActions: [action("npm install"), action("npm install --save-dev drizzle-kit")],
+		exitCode: 2
+	};
+}
+/**
+* Erreur portant un {@link IResolutionRefusal} déjà composé.
+*
+* Elle existe pour que la CAUSE porte son propre remède jusqu'à la sortie de la
+* commande : reconnaître une cause au texte de son message serait une garde qui
+* se casse au premier reformulage.
+*/
+var MigrationToolError = class extends Error {
+	refusal;
+	/**
+	* @param refusal - refus complet, seule source de la décision.
+	*/
+	constructor(refusal) {
+		super(refusal.summary);
+		this.refusal = refusal;
+		this.name = "MigrationToolError";
+	}
+};
+/**
+* Le module qui porte les connecteurs n'est pas chargé par l'application.
+*
+* @returns le refus, prêt pour la ligne de commande comme pour l'écran.
+*/
+function moduleAbsent() {
+	return {
+		code: "NF_MIGRATE_UNAVAILABLE",
+		summary: `Le module « @nodefony/${MODULE_NAME} » n'est pas chargé par cette application : il n'y a aucun connecteur SQL à migrer.`,
+		meaning: "Les migrations sont portées par le module qui déclare les connecteurs. Sans lui, la commande n'a ni base, ni fichiers, ni historique à consulter.",
+		nextActions: [action("nodefony inspect modules")],
+		exitCode: 2
+	};
+}
+/**
+* Le connecteur est une base SQL, mais la configuration du module ne le déclare
+* pas — cas d'un ORM construit directement dans du code.
+*
+* ⚠️ Ne JAMAIS lui répondre « ne porte pas de migrations » : c'est faux d'un
+* connecteur SQL, et un message faux publié est appris par les scripts qui le
+* lisent.
+*
+* @param connector - nom du connecteur.
+* @param driver - base sous-jacente, telle que l'ORM la nomme.
+* @returns le refus, prêt pour la ligne de commande comme pour l'écran.
+*/
+function notConfigured(connector, driver) {
+	return {
+		code: "NF_MIGRATE_NOT_CONFIGURED",
+		summary: `Le connecteur « ${connector} » est bien une base SQL (${driver}), mais il n'est pas déclaré dans la configuration de « @nodefony/${MODULE_NAME} » : il n'y a ni fichiers ni coordonnées pour lire son état.`,
+		meaning: "Un connecteur créé directement dans du code (un banc de test, un module qui instancie son ORM lui-même) est enregistré au moment où il se connecte, mais l'état des migrations se lit dans la configuration — c'est elle qui porte le dossier des fichiers et le mode de schéma. Déclare-le dans `connectors` pour pouvoir le suivre.",
+		nextActions: [action("nodefony inspect config --json")],
+		exitCode: 2
+	};
+}
+/**
+* Traduit une résolution qui n'est PAS `ready` en refus lisible.
+*
+* @param wanted - nom demandé par l'appelant.
+* @param resolution - ce que la résolution a rendu.
+* @param config - configuration validée du module (nomme les connecteurs réels).
+* @returns le refus correspondant, jamais `null` : chaque cas a sa prose.
+*/
+function describeResolutionRefusal(wanted, resolution, config) {
+	const premier = knownConnectors(config)[0] ?? "default";
+	if (resolution.kind === "unknown") return {
+		code: "NF_MIGRATE_UNKNOWN_CONNECTOR",
+		summary: `Aucun connecteur ne s'appelle « ${wanted} ». Ceux que cette application déclare : ${resolution.known.length > 0 ? resolution.known.map((n) => `« ${n} »`).join(", ") : "aucun"}.`,
+		meaning: "Le nom attendu est celui d'une clé de `connectors` dans la configuration, pas un nom de base ni un dialecte. Sans `--connector`, la commande travaille sur « default ».",
+		nextActions: [action("nodefony orm:migrate:status"), action("nodefony inspect config --json")],
+		exitCode: 2
+	};
+	if (resolution.kind === "url-mismatch") {
+		const vise = resolution.urlDialect === null ? "une base que cette commande ne sait pas lire" : `une base ${resolution.urlDialect}`;
+		return {
+			code: "NF_MIGRATE_URL_MISMATCH",
+			summary: `${MIGRATE_URL_ENV} désigne ${vise}, alors que le connecteur « ${wanted} » est déclaré en ${resolution.dialect}. Rien n'a été appliqué.`,
+			meaning: "Les deux ne peuvent pas être vraies en même temps : le SQL d'un dialecte ne s'applique pas avec le pilote d'un autre, et deviner laquelle des deux bases tu vises reviendrait à migrer la mauvaise en annonçant un succès. Soit la variable pointe la base du connecteur, soit c'est le connecteur qu'il faut choisir — la variable ne sert qu'à changer le COMPTE et l'hôte, jamais la nature de la base. Sous PowerShell, retirer la variable s'écrit `Remove-Item Env:" + MIGRATE_URL_ENV + "`.",
+			nextActions: [
+				action(`unset ${MIGRATE_URL_ENV}`),
+				action(`nodefony orm:migrate:status --connector ${wanted}`),
+				action("nodefony inspect config --json")
+			],
+			exitCode: 2
+		};
+	}
+	if (resolution.sqlLike) return {
+		code: "NF_MIGRATE_NOT_CONFIGURED",
+		summary: `Le connecteur « ${wanted} » est bien une base SQL (${resolution.driver}), mais il n'est pas déclaré dans la configuration de « @nodefony/${MODULE_NAME} » : la commande n'a pas ses coordonnées de connexion.`,
+		meaning: "Un connecteur créé directement dans du code (un banc de test, un module qui instancie son ORM lui-même) est enregistré au moment où il se connecte, mais la commande, elle, lit la configuration — c'est elle qui porte le fichier ou l'URL, et un secret ne se lit pas dans un objet déjà connecté. Déclare-le dans `connectors` pour pouvoir le migrer.",
+		nextActions: [action("nodefony inspect config --json"), action(`nodefony orm:migrate:status --connector ${premier}`)],
+		exitCode: 2
+	};
+	return {
+		code: "NF_MIGRATE_NO_MIGRATIONS",
+		summary: `Le connecteur « ${wanted} » est porté par ${resolution.owner}, dont la base ne se met pas à jour par des migrations de schéma.`,
+		meaning: "Les migrations par fichiers versionnés sont une mécanique SQL. Les autres bases résorbent l'écart entre le code et le schéma autrement — la question est la même, la réponse n'est pas la même. Aucune commande ne peut migrer ce connecteur aujourd'hui.",
+		nextActions: [action(`nodefony orm:migrate:status --connector ${premier}`)],
+		exitCode: 2
+	};
+}
+//#endregion
+export { MigrationToolError, describeResolutionRefusal, generationToolMissing, moduleAbsent, notConfigured };

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

@@ -0,0 +1,281 @@
+import { MIGRATE_URL_ENV } from "./types.js";
+import { resolveConnectorTarget } from "../connectorTarget.js";
+import { defaultMigrationSources } from "./paths.js";
+import { DrizzleMigrator } from "./DrizzleMigrator.js";
+import { parseDatabaseUrl, sqliteFilenameFromUrl } from "nodefony";
+import { ormRegistry } from "@nodefony/orm-core";
+import path from "node:path";
+//#region nodefony/src/migrator/resolve.ts
+/**
+* Résolution du décor d'une commande de migration : QUI possède le connecteur,
+* OÙ se trouve sa base, QUEL mode de schéma s'applique.
+*
+* **Pourquoi un fichier à part, et pourquoi il ne fait aucune entrée-sortie** :
+* ces règles sont lues par cinq commandes, par le démarrage du module et par la
+* sonde de disponibilité. Une seule d'entre elles recopiée ailleurs
+* divergerait — et une divergence de mode `ddl` entre le démarrage et la ligne
+* de commande, c'est une base que l'un croit à jour et que l'autre migre.
+*
+* Les fonctions de décision sont **pures** : on leur INJECTE l'environnement
+* constaté au lieu de le lire ici. C'est ce qui les rend éprouvables sans
+* kernel, sans base et sans variable d'environnement à poser.
+*/
+/**
+* Constate l'environnement depuis le kernel et le processus.
+*
+* @param kernel - kernel courant, ou `null` hors application.
+* @returns l'environnement constaté, prêt à être injecté aux règles pures.
+*/
+function readMigrationEnv(kernel) {
+	return {
+		runtime: kernel?.resolveRuntimeEnv() ?? "production",
+		nodeEnv: process.env.NODE_ENV
+	};
+}
+/**
+* L'effacement d'une base est-il ACCEPTÉ dans cet environnement ?
+*
+* **Liste blanche, jamais liste noire** : seul `development` passe. Un
+* `staging`, un `test`, un environnement que personne n'a pensé à nommer sont
+* refusés — c'est exactement ce qu'une garde écrite « si production » laisserait
+* passer, et c'est là que l'accident se produit.
+*
+* Écrite ici parce qu'elle a DEUX lecteurs qui doivent dire la même chose :
+* `orm:reset`, qui refuse ; et le rendu des migrations, qui ne doit pas proposer
+* un geste que l'autre va rejeter. Deux copies de cette règle divergeraient, et
+* la sortie promettrait alors une commande impossible.
+*
+* @param env - environnement constaté.
+* @returns `true` si `orm:reset` est recevable.
+*/
+function resetAllowed(env) {
+	return env.runtime === "development" && env.nodeEnv !== "test";
+}
+/**
+* Le mode de schéma qui s'applique à un connecteur.
+*
+* Règle des défauts, et son pourquoi : **appliquer des migrations au démarrage
+* n'est jamais un défaut**. C'est la norme unanime des outils de migration, et
+* elle tient à un fait simple — au démarrage, plusieurs exemplaires partent en
+* même temps. `migrate` est donc toujours un choix écrit, jamais une déduction.
+*
+* - développement et test → `auto` : le schéma suit le code, sans rien taper ;
+* - tout le reste → `none` : personne ne touche au schéma au démarrage, un
+*   travail externe applique les migrations avant que le trafic n'arrive.
+*
+* @param explicit - valeur écrite dans la configuration du connecteur, si elle l'est.
+* @param env - environnement constaté.
+* @returns le mode effectif.
+*/
+function resolveDdlMode(explicit, env) {
+	if (explicit) return explicit;
+	return env.runtime === "development" || env.nodeEnv === "test" ? "auto" : "none";
+}
+/**
+* La conduite de la sonde de disponibilité face à un schéma en retard.
+*
+* En production, un exemplaire dont le schéma est en retard ne doit pas
+* recevoir de trafic : il répondrait des erreurs de colonne inconnue à des
+* utilisateurs réels. Ailleurs, le retenir gênerait plus qu'il n'aiderait — un
+* avertissement suffit.
+*
+* @param explicit - valeur écrite dans `migrations.check`, si elle l'est.
+* @param env - environnement constaté.
+* @returns la conduite effective.
+*/
+function resolveCheckMode(explicit, env) {
+	if (explicit) return explicit;
+	return env.runtime === "production" ? "fail" : "warn";
+}
+/**
+* Décrit ce qui porte un connecteur, pour le nommer dans un refus.
+*
+* Un message qui dit seulement « ce connecteur ne porte pas de migrations »
+* laisse l'utilisateur sans recours : il ne sait ni ce que c'est, ni où
+* regarder. On nomme donc la classe qui le sert et la base qu'elle adresse.
+*
+* @param name - nom du connecteur dans le registre.
+* @returns une description courte (`mongoose (mongodb)`), ou le nom de classe seul.
+*/
+function describeOwner(name) {
+	let orm;
+	try {
+		orm = ormRegistry.get(name);
+	} catch {
+		return {
+			label: "un ORM inconnu",
+			driver: ""
+		};
+	}
+	const klass = orm?.constructor?.name;
+	let driver = "";
+	try {
+		driver = orm?.describeConnection?.().driver ?? "";
+	} catch {
+		driver = "";
+	}
+	return {
+		label: klass && driver ? `${klass} (${driver})` : klass || driver || "un ORM inconnu",
+		driver
+	};
+}
+/**
+* Bases SQL connues — celles dont le schéma se fait par migrations versionnées.
+*
+* La liste est CONSTATÉE sur ce que l'ORM dit de lui-même (`describeConnection`),
+* jamais déduite d'un test d'instance : à la frontière npm, deux copies du même
+* paquet font échouer `instanceof` sans un mot, et le repli serait ici un
+* message FAUX. Un nom absent de cette liste ne provoque aucune casse : il fait
+* seulement dire « pas de migrations pour cette base », ce qui reste vrai tant
+* qu'aucun applicateur ne la sert.
+*/
+const SQL_DRIVERS = /* @__PURE__ */ new Set([
+	"sqlite",
+	"sqlite3",
+	"postgres",
+	"postgresql",
+	"mysql",
+	"mariadb"
+]);
+/**
+* Tous les noms de connecteurs qui existent, tous ORM confondus.
+*
+* L'union du registre et de la configuration : le registre porte ce qui est
+* connecté, la configuration ce qui est déclaré. Un connecteur déclaré mais non
+* connecté doit apparaître dans la liste — sinon un utilisateur qui a fait une
+* faute de frappe se voit répondre que son connecteur n'existe pas ET ne le
+* voit pas dans la liste, alors qu'il est bien écrit dans son fichier.
+*
+* @param config - configuration validée du module drizzle.
+* @returns les noms, triés, sans doublon.
+*/
+function knownConnectors(config) {
+	const names = new Set(ormRegistry.list());
+	for (const name of Object.keys(config.connectors ?? {})) names.add(name);
+	return [...names].sort();
+}
+/**
+* Résout un nom de connecteur en l'une des **trois** réponses possibles.
+*
+* Ces trois réponses sont un contrat, pas un détail d'implémentation : le jour
+* où un second ORM apporte ses propres migrations, c'est `unsupported` qui doit
+* cesser de sortir pour ses connecteurs — et rien d'autre ne bouge. Répondre
+* « ne porte pas de migrations » à un connecteur qui en porterait serait un
+* message FAUX, appris par les scripts qui le lisent.
+*
+* La propriété se **constate** sur la configuration du module, jamais par un
+* test d'instance : à la frontière npm, deux copies du même paquet font échouer
+* `instanceof` sans un mot.
+*
+* @param connector - nom demandé.
+* @param config - configuration validée du module drizzle.
+* @param env - environnement constaté.
+* @param kernel - kernel courant, indispensable au chemin SQLite par défaut.
+* @param options - `allowMigrateUrl` autorise {@link MIGRATE_URL_ENV} à primer.
+* @returns la réponse, discriminée par `kind`.
+*/
+function resolveConnector(connector, config, env, kernel, options = {}) {
+	const declared = config.connectors?.[connector];
+	if (!declared) {
+		if (ormRegistry.has(connector)) {
+			const owner = describeOwner(connector);
+			return {
+				kind: "unsupported",
+				connector,
+				owner: owner.label,
+				sqlLike: SQL_DRIVERS.has(owner.driver.toLowerCase()),
+				driver: owner.driver
+			};
+		}
+		return {
+			kind: "unknown",
+			connector,
+			known: knownConnectors(config)
+		};
+	}
+	const base = resolveConnectorTarget(kernel, connector, declared);
+	const dialect = base.dialect;
+	const migrateUrl = options.allowMigrateUrl ? process.env[MIGRATE_URL_ENV] : void 0;
+	if (migrateUrl) {
+		const vise = describeMigrateUrl(migrateUrl);
+		if (vise === null || vise !== dialect) return {
+			kind: "url-mismatch",
+			connector,
+			dialect,
+			urlDialect: vise
+		};
+	}
+	const parsedUrl = migrateUrl ? parseDatabaseUrl(migrateUrl) : null;
+	const fromMigrateUrl = parsedUrl !== null;
+	return {
+		kind: "ready",
+		connector,
+		dialect,
+		target: {
+			dialect,
+			filename: fromMigrateUrl && dialect === "sqlite" ? sqliteFilenameFromUrl(parsedUrl.url) : base.filename,
+			url: fromMigrateUrl && dialect !== "sqlite" ? parsedUrl.url : base.url
+		},
+		fromMigrateUrl,
+		ddl: resolveDdlMode(declared.ddl, env)
+	};
+}
+/**
+* Dialecte que désigne une URL de migration, ou `null` si elle n'en désigne aucun.
+*
+* Ne jette jamais : une URL illisible est un cas d'usage à REFUSER avec une
+* phrase, pas une exception qui remonte en pile d'appels au milieu d'un
+* déploiement.
+*
+* @param url - valeur brute de la variable.
+* @returns le dialecte SQL visé, ou `null` (URL invalide, ou base non SQL).
+*/
+function describeMigrateUrl(url) {
+	try {
+		const vue = parseDatabaseUrl(url);
+		return vue.family === "sql" ? vue.dialect : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Dossier de migrations de l'application, résolu depuis la racine que le kernel
+* connaît.
+*
+* Jamais depuis le répertoire courant du processus : un espace de travail en a
+* plusieurs, et la commande serait juste ou fausse selon l'endroit d'où on la
+* tape — le pire des comportements, parce qu'il marche une fois sur deux.
+*
+* @param kernel - kernel courant.
+* @param dir - valeur de `migrations.dir` (relative, ou absolue si l'app le veut).
+* @returns le chemin absolu, ou `undefined` sans kernel.
+*/
+function appMigrationsDir(kernel, dir) {
+	const root = typeof kernel?.path === "string" ? kernel.path : void 0;
+	if (!root) return;
+	return path.isAbsolute(dir) ? dir : path.resolve(root, dir);
+}
+/**
+* Construit l'applicateur d'un connecteur résolu.
+*
+* @param resolution - réponse `ready` de {@link resolveConnector}.
+* @param config - configuration validée du module drizzle.
+* @param kernel - kernel courant (racine de l'application).
+* @returns l'applicateur, sources du framework et de l'application chargées.
+*/
+async function buildMigrator(resolution, config, kernel) {
+	const appDir = appMigrationsDir(kernel, config.migrations.dir);
+	const sources = await defaultMigrationSources(appDir, { framework: config.frameworkEntities !== false });
+	return new DrizzleMigrator({
+		connector: resolution.connector,
+		...resolution.target,
+		sources,
+		lockTimeoutMs: config.migrations.lockTimeoutMs
+	});
+}
+/** Conduite face à la divergence, telle que la configuration la déclare. */
+function resolveDivergenceMode(config) {
+	return config.migrations.divergence;
+}
+//#endregion
+export { MIGRATE_URL_ENV, appMigrationsDir, buildMigrator, knownConnectors, readMigrationEnv, resetAllowed, resolveCheckMode, resolveConnector, resolveDdlMode, resolveDivergenceMode };

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

@@ -0,0 +1,86 @@
+//#region nodefony/src/migrator/schemaDiff.ts
+/**
+* Nomme ce qui manque, en trois mots plutôt qu'en trois lignes.
+*
+* Un refus qui dit « la base diverge » sans dire OÙ oblige à rouvrir un client
+* SQL — c'est-à-dire exactement le geste que ces commandes existent pour éviter.
+*
+* Écrite ici parce qu'elle a DEUX lecteurs, et qu'ils doivent nommer l'écart de
+* la même façon : l'adoption d'une base existante, et le générateur quand il
+* n'a rien à écrire. Deux formulations pour un même fait apprendraient à leurs
+* lecteurs qu'il s'agit de deux problèmes.
+*
+* @param c - les écarts, tels que la comparaison les rend.
+* @returns une énumération courte, prête à entrer dans une phrase.
+*/
+function summarizeGap(c) {
+	const bouts = [];
+	if (c.missingTables.length > 0) bouts.push(`table(s) absente(s) : ${c.missingTables.join(", ")}`);
+	const columns = [...c.blocking, ...c.additive].map((g) => `${g.table}.${g.column}`);
+	if (columns.length > 0) bouts.push(`colonne(s) absente(s) : ${columns.join(", ")}`);
+	return bouts.join(" · ");
+}
+/** La base s'écarte-t-elle du code ? */
+function hasGap(c) {
+	return c.additive.length > 0 || c.blocking.length > 0 || c.missingTables.length > 0;
+}
+/**
+* Compare le schéma déclaré au schéma réel, table par table.
+*
+* Une requête par table, et **au démarrage uniquement** : rien de ceci n'existe
+* dans le chemin d'une requête.
+*
+* @param reader - lecteur de catalogue du porteur (ORM connecté, ou pilote).
+* @param expected - schéma attendu (cf `DrizzleOrm.describeTables`).
+* @returns les écarts, séparés selon qu'ils se rattrapent ou non.
+*/
+async function compareSchema(reader, expected) {
+	const additive = [];
+	const blocking = [];
+	const missingTables = [];
+	for (const expectedTable of expected) {
+		if (!await reader.tableExists(expectedTable.table)) {
+			missingTables.push(expectedTable.table);
+			continue;
+		}
+		const actualColumns = await reader.columnsOf(expectedTable.table);
+		for (const col of expectedTable.columns) {
+			if (actualColumns.some((actualColumn) => reader.sameColumnName(col.name, actualColumn))) continue;
+			const gap = {
+				table: expectedTable.table,
+				column: col.name,
+				type: col.type,
+				nullable: col.nullable
+			};
+			if (col.nullable && !col.primaryKey) additive.push(gap);
+			else blocking.push(gap);
+		}
+	}
+	return {
+		additive,
+		blocking,
+		missingTables
+	};
+}
+/** Échappe un identifiant dans le dialecte visé. */
+function ident(name, dialect) {
+	return dialect === "mysql" ? `\`${name.replace(/`/g, "``")}\`` : `"${name.replace(/"/g, "\"\"")}"`;
+}
+/**
+* Le `ALTER TABLE` qui pose une colonne manquante.
+*
+* Aucune valeur par défaut n'est émise, et aucune contrainte : la colonne est
+* ajoutée telle que le code la déclare, nullable. Ajouter un défaut ici
+* reviendrait à inventer la donnée des lignes existantes.
+*
+* @param gap - la colonne manquante (elle DOIT accepter le vide).
+* @param dialect - dialecte du connecteur.
+* @returns le SQL, prêt à exécuter.
+* @throws Error si l'on tente de rattraper une colonne obligatoire.
+*/
+function additiveSql(gap, dialect) {
+	if (!gap.nullable) throw new Error(`Rattrapage refusé : la colonne « ${gap.table}.${gap.column} » est obligatoire. La poser exigerait d'inventer une valeur pour les lignes déjà présentes — c'est une décision métier, pas une décision d'outil.`);
+	return `ALTER TABLE ${ident(gap.table, dialect)} ADD COLUMN ${ident(gap.column, dialect)} ${gap.type}`;
+}
+//#endregion
+export { additiveSql, compareSchema, hasGap, summarizeGap };