@nodefony/drizzle 10.0.0-alpha.1

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

@@ -0,0 +1,219 @@
+import { HISTORY_TABLE } from "./types.js";
+//#region nodefony/src/migrator/history.ts
+/**
+* Étapes d'amorçage postérieures au format d'origine.
+*
+* **Vide dans cette version** — l'étape 0 est le `CREATE` lui-même. Ce tableau
+* est le point d'extension : ajouter une colonne à l'historique, aujourd'hui ou
+* dans cinq versions, se fait ICI et nulle part ailleurs.
+*/
+const HISTORY_STEPS = [];
+/** Colonnes du format d'origine, dans l'ordre du `CREATE`. */
+const BASE_COLUMNS = [
+	"source",
+	"tag",
+	"hash",
+	"run_id",
+	"started_at",
+	"finished_at",
+	"execution_ms",
+	"success",
+	"error",
+	"applied_by"
+];
+/**
+* Le moteur se plaint-il d'une COLONNE d'historique qu'il ne trouve pas ?
+*
+* Reconnaît la table d'historique d'une AUTRE provenance : la table porte le
+* bon nom, elle n'a pas les bonnes colonnes. `CREATE TABLE IF NOT EXISTS` ne
+* la répare pas — elle existe —, et la première lecture échoue sur un message
+* de moteur brut, que le fourre-tout des pannes habille alors de deux causes
+* FAUSSES : « la base n'a pas répondu » et « les droits manquent ». Mesuré au
+* banc : c'est ce message qui a renvoyé un agent détruire une base de
+* production après qu'il eut pourtant suivi le conseil de travailler sur une
+* copie — copie qu'il avait dû fabriquer à la main, avec un historique inventé.
+*
+* PURE, et une grammaire par moteur : les trois formulent la même panne dans
+* trois langues, et un motif écrit pour l'une est muet pour les deux autres.
+* Bornée aux colonnes que ce fichier déclare : une colonne APPLICATIVE
+* manquante est un tout autre incident, qui a déjà sa voie.
+*
+* @param message - message d'erreur rendu par le pilote.
+* @returns la colonne d'historique introuvable, ou `null`.
+*/
+function missingHistoryColumn(message) {
+	for (const pattern of [
+		/no such column:\s*(?:[\w."`]*\.)?[`"']?(\w+)[`"']?/i,
+		/column\s+[`"']?(?:[\w.]*\.)?[`"']?(\w+)[`"']?\s+does not exist/i,
+		/unknown column\s+[`"']?(?:[\w.]*\.)?[`"']?(\w+)[`"']?/i
+	]) {
+		const name = pattern.exec(message)?.[1]?.toLowerCase();
+		if (name !== void 0 && BASE_COLUMNS.includes(name)) return name;
+	}
+	return null;
+}
+/** DDL de création par dialecte, au format d'origine. */
+const CREATE_SQL = {
+	sqlite: `CREATE TABLE IF NOT EXISTS ${HISTORY_TABLE} (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  source TEXT NOT NULL,\n  tag TEXT NOT NULL,\n  hash TEXT NOT NULL,\n  run_id TEXT NOT NULL,\n  started_at INTEGER NOT NULL,\n  finished_at INTEGER,\n  execution_ms INTEGER,\n  success INTEGER NOT NULL DEFAULT 0,\n  error TEXT,\n  applied_by TEXT,\n  UNIQUE (source, tag)\n)`,
+	postgres: `CREATE TABLE IF NOT EXISTS ${HISTORY_TABLE} (\n  id BIGSERIAL PRIMARY KEY,\n  source TEXT NOT NULL,\n  tag TEXT NOT NULL,\n  hash TEXT NOT NULL,\n  run_id TEXT NOT NULL,\n  started_at BIGINT NOT NULL,\n  finished_at BIGINT,\n  execution_ms INTEGER,\n  success BOOLEAN NOT NULL DEFAULT FALSE,\n  error TEXT,\n  applied_by TEXT,\n  UNIQUE (source, tag)\n)`,
+	mysql: `CREATE TABLE IF NOT EXISTS ${HISTORY_TABLE} (\n  id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,\n  source VARCHAR(190) NOT NULL,\n  tag VARCHAR(190) NOT NULL,\n  hash VARCHAR(255) NOT NULL,\n  run_id VARCHAR(64) NOT NULL,\n  started_at BIGINT NOT NULL,\n  finished_at BIGINT NULL,\n  execution_ms INT NULL,\n  success TINYINT(1) NOT NULL DEFAULT 0,\n  error TEXT NULL,\n  applied_by VARCHAR(255) NULL,\n  UNIQUE KEY uq_${HISTORY_TABLE} (source, tag)\n)`
+};
+/**
+* Crée la table d'historique si besoin, puis l'amène au format courant.
+*
+* À appeler **juste après le verrou et AVANT la moindre lecture** : c'est
+* l'ordre qui rend l'évolution de la table possible sans outil de conversion
+* chez l'utilisateur.
+*
+* @param driver - pilote à connexion unique, verrou déjà tenu.
+* @returns les colonnes ajoutées par l'amorçage (vide dans le cas courant).
+*/
+async function ensureHistorySchema(driver) {
+	await driver.exec(CREATE_SQL[driver.dialect]);
+	const present = new Set((await driver.columnsOf(HISTORY_TABLE)).map((c) => c.toLowerCase()));
+	const added = [];
+	for (const step of HISTORY_STEPS) {
+		if (present.has(step.column.toLowerCase())) continue;
+		await driver.exec(step.ddl[driver.dialect]);
+		added.push(step.column);
+	}
+	return added;
+}
+/**
+* Lit l'historique complet, **colonnes nommées une par une**.
+*
+* Jamais `SELECT *` : c'est ce qui rend l'ajout d'une colonne inoffensif pour
+* un applicateur plus ancien, qui continue de lire exactement ce qu'il connaît.
+*
+* @param driver - pilote à connexion unique.
+* @returns les lignes, dans leur ordre d'insertion.
+*/
+async function readHistory(driver) {
+	return (await driver.query(`SELECT ${BASE_COLUMNS.join(", ")} FROM ${HISTORY_TABLE} ORDER BY id`)).map((row) => ({
+		source: String(row.source),
+		tag: String(row.tag),
+		hash: String(row.hash),
+		runId: String(row.run_id),
+		startedAt: Number(row.started_at),
+		finishedAt: row.finished_at === null ? null : Number(row.finished_at),
+		executionMs: row.execution_ms === null ? null : Number(row.execution_ms),
+		success: toBoolean(row.success),
+		error: row.error === null ? null : String(row.error),
+		appliedBy: row.applied_by === null ? null : String(row.applied_by)
+	}));
+}
+/**
+* `INSERT` d'une ligne d'historique — **jamais positionnel**.
+*
+* @param driver - pilote à connexion unique.
+* @param row - ligne à écrire.
+*/
+async function insertHistory(driver, row) {
+	await driver.query(`INSERT INTO ${HISTORY_TABLE} (${BASE_COLUMNS.join(", ")}) VALUES (${BASE_COLUMNS.map(() => "?").join(", ")})`, [
+		row.source,
+		row.tag,
+		row.hash,
+		row.runId,
+		row.startedAt,
+		row.finishedAt,
+		row.executionMs,
+		fromBoolean(row.success, driver.dialect),
+		row.error,
+		row.appliedBy
+	]);
+}
+/**
+* Marque une ligne d'historique terminée (chemin MySQL, DDL non transactionnel).
+*
+* @param driver - pilote à connexion unique.
+* @param row - ligne dont le résultat est connu.
+*/
+async function finishHistory(driver, row) {
+	await driver.query(`UPDATE ${HISTORY_TABLE} SET finished_at = ?, execution_ms = ?, success = ?, error = ?, hash = ? WHERE source = ? AND tag = ?`, [
+		row.finishedAt,
+		row.executionMs,
+		fromBoolean(row.success, driver.dialect),
+		row.error,
+		row.hash,
+		row.source,
+		row.tag
+	]);
+}
+/**
+* Supprime les marqueurs d'échec d'une source, ou de toutes.
+*
+* @param driver - pilote à connexion unique.
+* @param source - source à réparer ; toutes si omise.
+* @returns les migrations dont le marqueur a été levé.
+*/
+async function deleteFailed(driver, source) {
+	const failed = (await readHistory(driver)).filter((row) => (!row.success || row.finishedAt === null) && (source === void 0 || row.source === source));
+	for (const row of failed) await driver.query(`DELETE FROM ${HISTORY_TABLE} WHERE source = ? AND tag = ?`, [row.source, row.tag]);
+	return failed.map(({ source: s, tag }) => ({
+		source: s,
+		tag
+	}));
+}
+/**
+* Désinscrit UNE entrée nommée de l'historique, quel que soit son état.
+*
+* ## Pourquoi ce geste existe, alors qu'un interdit dit de ne pas y toucher
+*
+* L'interdit porte sur la modification À LA MAIN, dans un client SQL, sans
+* trace. Il existait pourtant un état dont AUCUNE commande ne sortait : une
+* migration inscrite `success` que personne n'a jamais exécutée — une adoption
+* mal bornée, une base héritée d'une version antérieure aux gardes. Le
+* générateur disait « c'est l'historique qu'il faut reprendre » et renvoyait
+* vers la réparation, qui ne sait lever que des marqueurs d'ÉCHEC : elle
+* répondait « rien à réparer », et l'on revenait au point de départ. Trois
+* messages vrais, aucun geste — et le seul chemin restant était de détruire la
+* base.
+*
+* Le geste est donc rendu au produit, où il laisse une trace et où il est
+* BORNÉ : une entrée précisément nommée, jamais un lot, jamais un motif.
+*
+* ⚠️ Ne touche pas la base : après cet oubli, la migration sera REJOUÉE au
+* prochain passage. Si elle avait réellement été appliquée, ce rejeu échouera
+* — bruyamment, ce qui est le comportement voulu.
+*
+* @param driver - pilote sous verrou.
+* @param entries - entrées à désinscrire, chacune nommée `source` et `tag`.
+* @returns celles qui existaient et ont été retirées.
+*/
+async function forgetEntries(driver, entries) {
+	const existing = await readHistory(driver);
+	const removed = [];
+	for (const target of entries) {
+		if (!existing.some((row) => row.source === target.source && row.tag === target.tag)) continue;
+		await driver.query(`DELETE FROM ${HISTORY_TABLE} WHERE source = ? AND tag = ?`, [target.source, target.tag]);
+		removed.push({
+			source: target.source,
+			tag: target.tag
+		});
+	}
+	return removed;
+}
+/**
+* Normalise un booléen tel que le rend la base.
+*
+* PostgreSQL rend `true`, SQLite et MySQL rendent `1` — et un `1` textuel
+* traverse certains pilotes. Les trois se lisent ici, une fois.
+*
+* @param value - valeur brute lue en base.
+* @returns le booléen correspondant.
+*/
+function toBoolean(value) {
+	return value === true || value === 1 || value === "1";
+}
+/**
+* Encode un booléen pour la base.
+*
+* @param value - booléen applicatif.
+* @param dialect - dialecte cible.
+* @returns la valeur à binder.
+*/
+function fromBoolean(value, dialect) {
+	return dialect === "postgres" ? value : value ? 1 : 0;
+}
+//#endregion
+export { HISTORY_STEPS, deleteFailed, ensureHistorySchema, finishHistory, forgetEntries, insertHistory, missingHistoryColumn, readHistory };

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

@@ -0,0 +1,16 @@
+import { FORMAT_MARKER, HISTORY_TABLE, MigrationVerdictError, STATEMENT_BREAKPOINT } from "./types.js";
+import { sameColumnName, schemaReader } from "./catalog.js";
+import { MYSQL_LOCK_NAME_SQL, MYSQL_LOCK_PREFIX, MysqlMigrationDriver } from "./drivers/mysqlDriver.js";
+import { PG_LOCK_KEY, PostgresMigrationDriver } from "./drivers/postgresDriver.js";
+import { SqliteMigrationDriver } from "./drivers/sqliteDriver.js";
+import { openMigrationDriver } from "./drivers/index.js";
+import { HISTORY_STEPS, ensureHistorySchema, readHistory } from "./history.js";
+import { APP_RANK, APP_SOURCE, FRAMEWORK_RANK, FRAMEWORK_SOURCE, defaultMigrationSources, frameworkMigrationsDir } from "./paths.js";
+import { migrationHash, normalizeSql } from "./hash.js";
+import { SUPPORTED_JOURNAL_VERSIONS, createdTables, frameworkTables, loadSources, orderSources, splitStatements } from "./sources.js";
+import { DEFAULT_LOCK_TIMEOUT_MS, DrizzleMigrator } from "./DrizzleMigrator.js";
+import { additiveSql, compareSchema, hasGap } from "./schemaDiff.js";
+import { comparisonAgainstDeclared, describeDivergence, gapAgainstDeclared } from "./divergence.js";
+import { MIGRATION_NAME_MAX, checkMigrationName, suggestMigrationName } from "./name.js";
+import { adoptFromDatabase, introspectionUrl, readJournal, snapshotTables, tablesPresentIn, uncommentIntrospection } from "./adopt.js";
+export { APP_RANK, APP_SOURCE, DEFAULT_LOCK_TIMEOUT_MS, DrizzleMigrator, FORMAT_MARKER, FRAMEWORK_RANK, FRAMEWORK_SOURCE, HISTORY_STEPS, HISTORY_TABLE, MIGRATION_NAME_MAX, MYSQL_LOCK_NAME_SQL, MYSQL_LOCK_PREFIX, MigrationVerdictError, MysqlMigrationDriver, PG_LOCK_KEY, PostgresMigrationDriver, STATEMENT_BREAKPOINT, SUPPORTED_JOURNAL_VERSIONS, SqliteMigrationDriver, additiveSql, adoptFromDatabase, checkMigrationName, compareSchema, comparisonAgainstDeclared, createdTables, defaultMigrationSources, describeDivergence, ensureHistorySchema, frameworkMigrationsDir, frameworkTables, gapAgainstDeclared, hasGap, introspectionUrl, loadSources, migrationHash, normalizeSql, openMigrationDriver, orderSources, readHistory, readJournal, sameColumnName, schemaReader, snapshotTables, splitStatements, suggestMigrationName, tablesPresentIn, uncommentIntrospection };

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

@@ -0,0 +1,296 @@
+import { FORMAT_MARKER } from "./types.js";
+import { MigrationToolError, generationToolMissing } from "./refusals.js";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+//#region nodefony/src/migrator/kit.ts
+/**
+* Plomberie `drizzle-kit` — la partie qui ne connaît NI le framework NI
+* l'application, et que les deux exécutent donc à l'identique.
+*
+* Elle vivait dans `scripts/`, qui n'est pas publié (`files` ne porte que
+* `dist`, `docs` et `migrations`). La commande `orm:generate`, elle, tourne chez
+* l'utilisateur : lui laisser dépendre de `scripts/` aurait été livrer un verbe
+* dont la moitié manque au paquet. Le socle a donc rejoint le code publié, et
+* `scripts/` le CONSOMME — une seule implémentation, celle qu'exécutent le dépôt
+* du framework et toute application.
+*
+* 🔴 **Le piège qui justifie ce fichier** : `drizzle-kit` **rend le code 0 quand
+* il échoue**. Une exception non rattrapée part sur la sortie d'erreur et le
+* process sort quand même à zéro. Tout appelant doit donc exiger une **preuve
+* positive** que la génération a eu lieu — c'est le rôle de {@link runGenerate}.
+* Un second piège en découle : le dossier de sortie ne peut pas être ABSOLU
+* (l'outil le préfixe par `./`, fabriquant `.//Users/…`), et l'échec de lecture
+* qui s'ensuit se présente lui aussi comme un succès.
+*/
+/**
+* Résout le binaire de `drizzle-kit` sans passer par un lanceur de shell.
+*
+* `npx` est un `.cmd` sous Windows, inexécutable sans `shell: true` — qui
+* rouvrirait une injection par le nom de migration. Le paquet n'exporte pas son
+* binaire (`exports` ne couvre que `.` et `./api`), donc on remonte les dossiers
+* `node_modules` comme le ferait Node.
+*
+* @param from - dossier de départ de la remontée (racine du paquet qui génère,
+*   ou racine de l'application).
+* @returns chemin absolu de `bin.cjs`.
+* @throws Error si `drizzle-kit` n'est pas installé au-dessus de `from`.
+*/
+function resolveDrizzleKitBin(from) {
+	let dir = from;
+	for (;;) {
+		const candidate = path.join(dir, "node_modules", "drizzle-kit", "bin.cjs");
+		if (fs.existsSync(candidate)) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) throw new MigrationToolError(generationToolMissing());
+		dir = parent;
+	}
+}
+/**
+* Lance `drizzle-kit generate` et EXIGE la preuve qu'il a tourné.
+*
+* @param options - `cwd` (dossier depuis lequel l'outil est lancé — les chemins
+*   de la configuration lui sont relatifs), `configRel` (configuration, chemin
+*   relatif à `cwd`), `name` (nom imposé de la migration), `label` (ce qui est
+*   cité dans l'erreur).
+* @returns la sortie complète de l'outil (sortie standard puis sortie d'erreur).
+* @throws Error si le code est non nul, ou si rien ne prouve que la génération a
+*   eu lieu — l'absence de preuve n'est JAMAIS lue comme « rien à faire ».
+*/
+function runGenerate({ cwd, configRel, name, label, regenerateCommand }) {
+	const result = spawnSync(process.execPath, [
+		resolveDrizzleKitBin(cwd),
+		"generate",
+		`--config=${configRel}`,
+		`--name=${name}`
+	], {
+		cwd,
+		encoding: "utf8"
+	});
+	const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+	if (result.status !== 0 || !generationHappened(output)) {
+		if (isInteractivePromptFailure(output)) {
+			const replay = regenerateCommand ?? `nodefony orm:generate --name ${name}`;
+			throw new Error(`Un RENOMMAGE probable a été détecté sur ${label}, et il faut trancher.\n\n  drizzle-kit ne peut pas deviner votre intention : une colonne qui\n  disparaît et une autre qui apparaît, c'est soit un renommage — les\n  données SUIVENT —, soit une suppression puis un ajout — les données\n  sont PERDUES. Il pose donc la question, et il n'y a pas de terminal\n  ici pour y répondre.\n\n  Rejouer la commande dans un terminal interactif :\n    ${replay}\n\n  ⚠️ Après avoir répondu « renamed », RELIRE le fichier produit : quand\n  une colonne est renommée ET que son type change, l'outil n'écrit que\n  le renommage et OUBLIE le changement de type (drizzle-orm#3826).`);
+		}
+		throw new Error(`La génération n'a pas eu lieu sur ${label} (code ${result.status}). Ne rien conclure de ce silence : l'outil rend 0 même en échec.\n` + output.trim());
+	}
+	return output;
+}
+/**
+* Lance `drizzle-kit introspect` et EXIGE la preuve qu'il a travaillé.
+*
+* C'est la seule commande de la chaîne qui LIT la base pour en tirer des
+* fichiers. Elle sert l'adoption d'une base qui existait avant les migrations :
+* l'instantané qu'elle dépose décrit l'état RÉEL, celui à partir duquel la
+* génération suivante produira un `ALTER` au lieu d'un `CREATE TABLE`.
+*
+* La preuve n'est pas cherchée dans le texte de l'outil mais dans ce qu'il
+* LAISSE : l'appelant relit le journal des fichiers. Ici on ne garde que le
+* refus le plus grossier — un code de sortie non nul —, parce que l'outil rend
+* `0` même en échec et qu'un marqueur de texte a déjà menti une fois (il change
+* avec la couleur du terminal).
+*
+* @param options - `cwd` (dossier depuis lequel l'outil est lancé), `configRel`
+*   (configuration, chemin relatif à `cwd`), `label` (ce qui est cité en cas
+*   d'échec).
+* @returns la sortie complète de l'outil.
+* @throws Error si le code est non nul.
+*/
+function runIntrospect({ cwd, configRel, label }) {
+	const result = spawnSync(process.execPath, [
+		resolveDrizzleKitBin(cwd),
+		"introspect",
+		`--config=${configRel}`
+	], {
+		cwd,
+		encoding: "utf8"
+	});
+	const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+	if (result.status !== 0) throw new Error(`La lecture du schéma de ${label} a échoué (code ${result.status}).\n` + output.trim());
+	return output;
+}
+/**
+* La génération a-t-elle EU LIEU ? — lue sur une sortie DÉCOLORÉE.
+*
+* L'outil ne rend pas de code d'échec (il sort 0 même quand il rate) : la seule
+* preuve disponible est un marqueur dans son texte. Encore faut-il le chercher
+* dans le texte, et non dans sa mise en forme.
+*
+* 🔴 **Le piège, payé en intégration continue** : la forge pose `FORCE_COLOR`,
+* l'outil colore alors sa coche — `[`, une séquence d'échappement, `✓`, une
+* autre séquence, `]` — et `"[✓]"` n'est plus une sous-chaîne. La génération
+* réussissait, le fichier était écrit, et l'appelant annonçait qu'elle n'avait
+* pas eu lieu. Vert sur un poste sans terminal, rouge à la forge : la sonde
+* mesurait la présentation.
+*
+* Fonction PURE, pour qu'elle s'éprouve sans lancer un process — une règle qui
+* exige un sous-processus pour être vue rouge n'est jamais vue rouge.
+*
+* @param output - sortie complète de l'outil, telle qu'elle a été capturée.
+* @returns `true` si l'outil dit avoir écrit, ou n'avoir rien eu à écrire.
+*/
+function generationHappened(output) {
+	const plain = output.replace(/\u001B\[[0-9;]*m/g, "");
+	return plain.includes("No schema changes") || plain.includes("[✓]");
+}
+/**
+* Instructions qui DÉTRUISENT des données, par dialecte.
+*
+* Sources : la documentation PostgreSQL sur les verrous d'`ALTER TABLE`, le
+* comportement constaté de `drizzle-kit`, et le fait — vérifié — que l'outil se
+* décrit lui-même comme une aide à la productivité, pas comme un dispositif de
+* sûreté de déploiement. Aucun générateur de diff ne peut distinguer seul un
+* renommage (les données suivent) d'une suppression suivie d'un ajout (les
+* données disparaissent) : c'est une intention, pas une différence de schéma.
+*
+* Chaque entrée porte le motif, ce qui se passe, et ce qu'il faut faire — le
+* message d'un refus doit dire quoi faire, pas seulement ce qui est refusé.
+*/
+const DESTRUCTIVE_PATTERNS = [
+	{
+		id: "drop-table",
+		pattern: /\bDROP\s+TABLE\b/i,
+		what: "supprime une table ET toutes ses lignes",
+		todo: "sauvegarder, puis appliquer en deux temps (cf expand/contract)"
+	},
+	{
+		id: "drop-column",
+		pattern: /\bDROP\s+COLUMN\b/i,
+		what: "supprime une colonne ET son contenu, sans retour possible",
+		todo: "s'il s'agissait d'un RENOMMAGE, regénérer dans un terminal interactif et répondre « renamed » : l'outil produit alors un RENAME, qui conserve les données"
+	},
+	{
+		id: "alter-column-type",
+		pattern: /\bALTER\s+(?:COLUMN\s+)?[`"\w]+\s+(?:SET\s+DATA\s+)?TYPE\b/i,
+		what: "convertit une colonne : les valeurs qui n'entrent pas dans le nouveau type sont perdues ou font échouer la migration à mi-parcours",
+		todo: "vérifier la conversion sur une copie des données de production avant d'appliquer"
+	},
+	{
+		id: "modify-column",
+		pattern: /\bMODIFY\s+COLUMN\b/i,
+		what: "réécrit une colonne MySQL (type, nullabilité) — mêmes risques",
+		todo: "vérifier la conversion sur une copie des données avant d'appliquer"
+	},
+	{
+		id: "truncate",
+		pattern: /\bTRUNCATE\b/i,
+		what: "vide une table entière",
+		todo: "ne jamais laisser une instruction de ce genre dans une migration"
+	}
+];
+/**
+* Ce qui ne détruit rien, mais doit être VU avant d'appliquer.
+*
+* Deux natures, et elles ne justifient ni l'une ni l'autre un refus — le
+* générateur ne lit pas la base, il ne peut donc pas trancher à la place de
+* celui qui la connaît.
+*
+* **Ce qui VERROUILLE.** Le scénario type, largement documenté : un
+* `ALTER TABLE` prend un verrou exclusif, se met en file derrière une requête
+* longue, et toutes les requêtes suivantes s'empilent derrière lui ; le parc de
+* connexions se vide en quelques dizaines de secondes, et l'application rend des
+* 503 alors que la migration, elle, n'a rien de lent.
+*
+* **Ce qui ÉCHOUE sur une table peuplée.** L'inapplicabilité est une propriété
+* du SQL écrit, pas de la donnée : une colonne obligatoire sans défaut, un index
+* unique posé sur une colonne qu'on vient d'ajouter. Elle se voit donc sans se
+* connecter — et ne pas la dire a déjà conduit un agent à supprimer une base
+* pour sortir de l'impasse (tâche 33 du banc de découvrabilité).
+*/
+const BLOCKING_PATTERNS = [
+	{
+		id: "create-index-not-concurrent",
+		dialects: ["postgres"],
+		pattern: /\bCREATE\s+(?:UNIQUE\s+)?INDEX\b(?!\s+CONCURRENTLY)/i,
+		what: "bloque les écritures de la table pendant toute la construction de l'index (minutes sur une grande table)",
+		todo: "sur une table déjà volumineuse en production, appliquer l'index à part, en `CREATE INDEX CONCURRENTLY` (hors transaction)"
+	},
+	{
+		id: "set-not-null",
+		dialects: ["postgres"],
+		pattern: /\bSET\s+NOT\s+NULL\b/i,
+		what: "scanne la table entière sous verrou exclusif pour valider chaque ligne",
+		todo: "ajouter d'abord une contrainte `CHECK … NOT VALID`, la valider à part, puis poser le `NOT NULL`"
+	},
+	{
+		id: "add-not-null-sans-defaut",
+		pattern: /\bADD\s+(?:COLUMN\s+)?[`"']?\w+[`"']?[^;\n]*?\bNOT\s+NULL\b(?![^;\n]*\bDEFAULT\b)/i,
+		what: "ajoute une colonne OBLIGATOIRE sans valeur par défaut : sur une table qui porte déjà des lignes, sqlite et PostgreSQL REFUSENT la migration, et MySQL/MariaDB la remplit de chaînes vides sans un avertissement",
+		todo: "donner un défaut à la déclaration du champ (`role:string=membre`), ou le déclarer facultatif (`department:string?`) ; s'il faut les deux, c'est en trois temps — ajouter avec défaut, remplir (`--custom`), retirer le défaut"
+	},
+	{
+		id: "colonne-neuve-puis-index-unique",
+		pattern: /\bCREATE\s+UNIQUE\s+INDEX\b/i,
+		detect: (code) => {
+			const added = [...code.matchAll(/\bADD\s+(?:COLUMN\s+)?[`"']?(\w+)[`"']?/gi)].map((m) => m[1].toLowerCase());
+			if (added.length === 0) return false;
+			return [...code.matchAll(/\bCREATE\s+UNIQUE\s+INDEX\b[^;\n]*?\(([^)]*)\)/gi)].some((m) => m[1].split(",").map((c) => c.trim().replace(/[`"']/g, "").toLowerCase()).some((c) => added.includes(c)));
+		},
+		what: "ajoute une colonne ET pose son index UNIQUE dans la même migration : toutes les lignes déjà présentes reçoivent la même valeur, et l'index échoue sur la deuxième — cet enchaînement ne réussit que sur une table vide",
+		todo: "séparer : ajouter la colonne sans contrainte d'unicité, remplir chaque ligne d'une valeur DISTINCTE (`nodefony orm:generate --custom`), puis poser l'index unique"
+	}
+];
+/**
+* Analyse le SQL d'une migration et rend ce qui mérite un refus ou un regard.
+*
+* Volontairement **textuelle** : il ne s'agit pas d'analyser du SQL, mais de
+* refuser de laisser passer sans un mot ce qui détruit des données. Un motif de
+* trop fait poser une question ; un motif de moins fait perdre une table.
+*
+* @param sql - contenu d'un fichier de migration.
+* @param dialect - dialecte concerné (certains risques lui sont propres).
+* @returns `{ destructive, blocking }`, chacun décrivant ce qui a été reconnu.
+*/
+function auditMigrationSql(sql, dialect) {
+	const code = sql.split("\n").filter((line) => !line.trimStart().startsWith("--")).join("\n");
+	const match = (list) => list.filter((rule) => !rule.dialects || rule.dialects.includes(dialect)).filter((rule) => rule.pattern.test(code)).filter((rule) => rule.detect === void 0 || rule.detect(code)).map(({ id, what, todo }) => ({
+		id,
+		what,
+		todo
+	}));
+	return {
+		destructive: match(DESTRUCTIVE_PATTERNS),
+		blocking: match(BLOCKING_PATTERNS)
+	};
+}
+/**
+* Reconnaît l'échec de `drizzle-kit` faute de terminal interactif.
+*
+* L'outil pose une question — « cette colonne a-t-elle été renommée, ou
+* supprimée puis ajoutée ? » — à laquelle lui seul ne peut pas répondre. Sans
+* terminal, il échoue, et **rend 0**. Sans reconnaissance explicite, l'utilisateur
+* reçoit une pile d'appels de l'outil au lieu de la seule chose qui compte : la
+* question qu'on lui pose, et où y répondre.
+*
+* @param output - sortie complète de l'outil.
+* @returns `true` si l'échec vient d'une question restée sans terminal.
+*/
+function isInteractivePromptFailure(output) {
+	return /Interactive prompts require a TTY/i.test(output);
+}
+/**
+* Pose le marqueur de format en tête des `.sql` d'un dossier qui ne l'ont pas.
+*
+* Écrit en fins de ligne `\n` quel que soit le système : le dépôt et le gabarit
+* d'application déclarent `* text=auto eol=lf`, sans quoi une copie de travail
+* Windows produirait une fausse dérive à chaque lecture.
+*
+* @param dir - dossier `<sortie>/<dialecte>` dont on marque les fichiers.
+* @returns le nombre de fichiers marqués.
+*/
+function stampFormatMarker(dir) {
+	if (!fs.existsSync(dir)) return 0;
+	let stamped = 0;
+	for (const name of fs.readdirSync(dir)) {
+		if (!name.endsWith(".sql")) continue;
+		const file = path.join(dir, name);
+		const body = fs.readFileSync(file, "utf8");
+		if (body.startsWith("-- nodefony:migration format=1")) continue;
+		fs.writeFileSync(file, `${FORMAT_MARKER}\n${body.replace(/\r\n/g, "\n")}`);
+		stamped++;
+	}
+	return stamped;
+}
+//#endregion
+export { FORMAT_MARKER, auditMigrationSql, generationHappened, isInteractivePromptFailure, resolveDrizzleKitBin, runGenerate, runIntrospect, stampFormatMarker };

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

@@ -0,0 +1,68 @@
+//#region nodefony/src/migrator/name.ts
+/**
+* Ce qu'un nom de migration a le droit d'être — et ce qu'on propose sinon.
+*
+* **Pourquoi une fonction pure, à part de la commande** : ce nom entre dans le
+* tag du fichier, et un tag ne se renomme plus une fois la migration appliquée
+* quelque part — c'est lui qui dit à chaque base ce qu'elle a déjà reçu. La
+* règle qui le garde mérite donc d'être exerçable sans démarrer une
+* application : un contrôle qui coûte trois minutes est un contrôle qu'on
+* saute.
+*/
+/**
+* Longueur maximale d'un nom de migration.
+*
+* Le tag complet vaut `NNNN_<nom>` et le fichier `<tag>.sql` : à 120
+* caractères, on reste très en deçà des 255 octets qu'un système de fichiers
+* accepte pour un nom, et loin des 260 caractères qu'un chemin Windows tolère
+* par défaut. La borne n'est pas là pour économiser des octets — elle est là
+* pour qu'un nom trop long échoue AVANT d'avoir écrit un fichier, avec une
+* phrase, plutôt qu'au moment de l'écriture avec un code d'erreur système.
+*/
+const MIGRATION_NAME_MAX = 120;
+/** Ce qu'un nom peut contenir : minuscules, chiffres et le trait bas. */
+const FORME = /^[a-z0-9_]+$/;
+/** Un nom doit porter au moins une lettre ou un chiffre — `___` n'en est pas un. */
+const SUBSTANCE = /[a-z0-9]/;
+/**
+* Dérive un nom acceptable d'une saisie qui ne l'est pas.
+*
+* @param input - ce que l'utilisateur a tapé.
+* @returns un nom conforme, ou `undefined` s'il n'en reste rien de sensé.
+*/
+function suggestMigrationName(input) {
+	const derive = input.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "").slice(0, 120);
+	return SUBSTANCE.test(derive) ? derive : void 0;
+}
+/**
+* Vérifie un nom de migration, et dit ce qu'il faudrait taper à la place.
+*
+* @param input - nom reçu de la ligne de commande, éventuellement absent.
+* @returns le verdict, avec sa raison et sa suggestion.
+*/
+function checkMigrationName(input) {
+	if (!input) return {
+		ok: false,
+		reason: "Il manque le nom de la migration."
+	};
+	if (input.length > 120) return {
+		ok: false,
+		reason: `Le nom fait ${input.length} caractères, la limite est 120 : il devient un nom de fichier, et un chemin trop long échoue à l'écriture sur certains systèmes.`,
+		suggestion: suggestMigrationName(input)
+	};
+	if (!FORME.test(input)) return {
+		ok: false,
+		reason: `Le nom « ${input} » ne convient pas : minuscules, chiffres et « _ » seulement.`,
+		suggestion: suggestMigrationName(input)
+	};
+	if (!SUBSTANCE.test(input)) return {
+		ok: false,
+		reason: `Le nom « ${input} » ne porte aucune lettre ni chiffre : il produirait un tag que personne ne saura relire.`
+	};
+	return {
+		ok: true,
+		name: input
+	};
+}
+//#endregion
+export { MIGRATION_NAME_MAX, checkMigrationName, suggestMigrationName };