@nodefony/drizzle 10.0.0-alpha.1

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

@@ -0,0 +1,553 @@
+import { openMigrationDriver } from "./drivers/index.js";
+import { runIntrospect } from "./kit.js";
+import { postgresSchemaOf, writeKitConfig } from "./appSchema.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+//#region nodefony/src/migrator/adopt.ts
+/**
+* Les coordonnées de connexion, dans la forme que l'outil d'introspection lit.
+*
+* SQLite désigne un FICHIER, les autres une URL — et c'est le seul endroit où
+* cette distinction se fait, pour qu'elle ne se redécide pas à chaque appelant.
+*
+* @param target - cible résolue du connecteur.
+* @returns l'URL de connexion, ou `null` si la cible n'en porte aucune.
+*/
+function introspectionUrl(target) {
+	if (target.dialect === "sqlite") return target.filename ?? null;
+	return target.url ?? null;
+}
+/** L'en-tête que l'outil pose devant un corps commenté. */
+const INTROSPECTION_HEADER = /^\s*--[^\n]*generated after introspecting[^\n]*\n(?:\s*--[^\n]*\n)*/u;
+/**
+* Rend exécutable le corps qu'une introspection a mis en commentaire.
+*
+* Fonction PURE — c'est ce qui la rend éprouvable sans base et sans outil
+* tiers : une règle qui exige un sous-processus pour être vue rouge n'est
+* jamais vue rouge.
+*
+* Ne touche à RIEN si la forme attendue n'est pas là : rendre `null` laisse
+* l'appelant dire ce qu'il a constaté, au lieu de publier un fichier tronqué
+* par une expression écrite pour une autre version de l'outil.
+*
+* @param sql - le fichier tel que l'outil l'a écrit.
+* @returns le SQL exécutable, ou `null` si aucun bloc commenté n'a été trouvé.
+*/
+function uncommentIntrospection(sql) {
+	const withoutHeader = sql.replace(INTROSPECTION_HEADER, "");
+	const debut = withoutHeader.indexOf("/*");
+	const fin = withoutHeader.lastIndexOf("*/");
+	if (debut === -1 || fin === -1 || fin < debut) return null;
+	const body = withoutHeader.slice(debut + 2, fin);
+	if (`${withoutHeader.slice(0, debut)}${withoutHeader.slice(fin + 2)}`.trim() !== "") return null;
+	return `${body.trim()}\n`;
+}
+/**
+* Lit le journal des FICHIERS d'un dossier de migrations.
+*
+* ⚠️ Ce journal n'est pas l'historique. Il vit dans le dépôt, il est versionné,
+* et il dit ce que le code CONNAÎT. L'historique, lui, vit dans la base et dit
+* ce qu'ELLE a reçu. Les confondre fait conclure « tout est appliqué » sur une
+* base qui n'a rien vu.
+*
+* @param outDir - dossier `<migrations>/<dialecte>`.
+* @returns le journal, ou `null` s'il n'y en a pas encore.
+*/
+async function readJournal(outDir) {
+	try {
+		const raw = await fs.readFile(path.join(outDir, "meta", "_journal.json"), "utf8");
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+/**
+* Donne à la migration de référence le nom que l'utilisateur a choisi.
+*
+* L'outil d'introspection tire un nom au hasard (`0000_futuristic_spectrum`) et
+* n'accepte pas qu'on le lui impose. Or ce tag est une IDENTITÉ : il est
+* enregistré dans chaque base qui reçoit la migration, et il ne se renomme plus
+* ensuite. Le fixer ici, une fois, avant que quiconque l'ait vu.
+*
+* @param outDir - dossier `<migrations>/<dialecte>`.
+* @param oldTag - tag tiré par l'outil.
+* @param newTag - tag voulu.
+* @returns le chemin du fichier SQL, sous son nom final.
+*/
+async function renameTag(outDir, oldTag, newTag) {
+	const targetFile = path.join(outDir, `${newTag}.sql`);
+	if (oldTag !== newTag) {
+		await fs.rename(path.join(outDir, `${oldTag}.sql`), targetFile);
+		const journal = await readJournal(outDir);
+		if (journal) {
+			for (const entry of journal.entries) if (entry.tag === oldTag) entry.tag = newTag;
+			await fs.writeFile(path.join(outDir, "meta", "_journal.json"), `${JSON.stringify(journal, null, 2)}\n`, "utf8");
+		}
+	}
+	return targetFile;
+}
+/**
+* Retire les modules que l'introspection dépose à côté de sa migration.
+*
+* `schema.ts` et `relations.ts` décrivent la base en TypeScript — utile à qui
+* repart de zéro, hors sujet ici : les entités de l'application sont déjà la
+* source du schéma. Les laisser dans le dossier des migrations y mettrait deux
+* descriptions du même schéma, dont une que personne ne met à jour.
+*
+* @param outDir - dossier `<migrations>/<dialecte>`.
+*/
+async function dropIntrospectionModules(outDir) {
+	await Promise.all(["schema.ts", "relations.ts"].map((f) => fs.rm(path.join(outDir, f), { force: true })));
+}
+/**
+* Les tables que l'instantané fraîchement écrit décrit.
+*
+* Lues sur l'instantané et non sur le SQL : c'est lui qui sert de référence au
+* prochain diff, donc c'est lui qui dit ce qui a réellement été adopté. Le
+* fichier `.sql`, lui, n'est qu'un rendu.
+*
+* @param outDir - dossier `<migrations>/<dialecte>`.
+* @returns les noms de tables, ou `[]` si l'instantané est illisible.
+*/
+async function snapshotTables(outDir) {
+	try {
+		const raw = await fs.readFile(path.join(outDir, "meta", "0000_snapshot.json"), "utf8");
+		const snapshot = JSON.parse(raw);
+		return Object.values(snapshot.tables ?? {}).map((t, i) => t.name ?? Object.keys(snapshot.tables ?? {})[i] ?? "");
+	} catch {
+		return [];
+	}
+}
+/**
+* Rend utilisable une référence que l'introspection vient d'écrire.
+*
+* L'outil rend ce qu'il a LU, fidèlement. Deux fidélités rendent pourtant le
+* fichier inutilisable, et il faut les défaire — c'est la même famille de
+* geste que le décommentage du corps : l'artefact est exact, personne ne peut
+* s'en servir.
+*
+* ## 1. Les objets d'une table EXCLUE
+*
+* L'exclusion porte sur les tables, jamais sur ce qui gravite autour. La table
+* d'historique est écartée — c'est le framework qui la crée —, mais sa
+* SÉQUENCE, elle, entre dans la référence. Deux conséquences, toutes deux
+* constatées sur un serveur : la référence rejouée sur un environnement neuf
+* échoue (la séquence existe déjà, posée par les migrations du framework), et
+* la génération suivante propose de la SUPPRIMER — ce que la base refuse,
+* puisque la table d'historique en dépend. L'adoption se retrouve alors dans
+* l'état qu'elle existe pour éviter : un historique en place, et plus aucune
+* commande qui passe.
+*
+* ## 2. La qualification de schéma
+*
+* Une application peut vivre dans un schéma autre que `public` — le montage
+* habituel d'une base mutualisée, obtenu par le chemin de recherche de la
+* connexion. Les entités, elles, ne portent aucun schéma : `pgTable("article")`
+* désigne `public.article` pour l'outil de comparaison, quand l'introspection
+* rend `nf_app.article`. Au premier champ ajouté, l'outil voit une table qui
+* disparaît et une autre qui apparaît, et demande s'il s'agit d'un RENOMMAGE :
+* sans terminal la commande s'arrête, avec un terminal répondre « oui » écrit
+* un `ALTER TABLE … RENAME` qui déplacerait les données.
+*
+* On retire donc la qualification, ce qui rétablit la symétrie avec les
+* entités. À l'exécution, le chemin de recherche de la connexion place les
+* tables là où elles doivent être : c'est déjà lui qui décide, l'adoption
+* cesse simplement de le contredire.
+*
+* ## 3. Le booléen de MySQL
+*
+* `BOOLEAN` est un SYNONYME de `TINYINT(1)` en MySQL : le serveur ne garde que
+* la forme physique, et l'introspection ne peut donc rendre que `tinyint(1)`.
+* L'outil de comparaison, lui, compare des noms de type : il voit une
+* différence là où la base n'en a aucune, et propose un `MODIFY COLUMN` sur
+* chaque booléen — refusé ensuite comme destructif. Une application MySQL qui
+* adopte sa base se retrouve donc bloquée au premier champ ajouté, pour une
+* table qu'elle n'a jamais touchée.
+*
+* La forme déclarée est rétablie. Elle ne peut écraser aucune intention : dans
+* une entité, `tinyint()` rend `tinyint` sans largeur — vérifié au source
+* (`drizzle-orm/mysql-core/columns/tinyint.js`) —, et seul `boolean()` produit
+* `tinyint(1)`. Sur un DDL écrit à la main hors de l'ORM, la réécriture reste
+* exacte : les deux formes désignent la même colonne.
+*
+* @param outDir - dossier `<migrations>/<dialecte>`.
+* @param options.dialect - dialecte lu ; seul MySQL a le synonyme booléen.
+* @param file - fichier SQL de la référence.
+* @param options.schema - schéma effectivement lu, ou `null` (hors PostgreSQL,
+*   ou lecture dans `public` : il n'y a alors rien à déqualifier).
+* @param options.excludedTables - tables écartées de la lecture, dont les
+*   objets satellites doivent l'être aussi.
+* @param options.stripTables - tables que l'outil a LUES faute de pouvoir les
+*   exclure, et qu'il faut retirer du résultat (cf `lectureSansExclusion`).
+*/
+async function normalizeIntrospection(outDir, file, options) {
+	const { schema, excludedTables } = options;
+	const stripTables = options.stripTables ?? [];
+	const qualifie = schema !== null && schema !== "public";
+	/** Une séquence appartient-elle à une table qu'on a écartée ? */
+	const satellite = (objectName) => excludedTables.some((t) => objectName.startsWith(`${t}_`));
+	const snapshotFile = path.join(outDir, "meta", "0000_snapshot.json");
+	const removedSequences = [];
+	/** Colonnes booléennes rendues à leur forme déclarée (MySQL). */
+	let booleans = 0;
+	let brut = null;
+	try {
+		brut = await fs.readFile(snapshotFile, "utf8");
+	} catch {
+		brut = null;
+	}
+	if (brut !== null) {
+		const doc = JSON.parse(brut);
+		let changed = false;
+		if (doc.sequences !== void 0) {
+			const sequences = {};
+			for (const [key, seq] of Object.entries(doc.sequences)) {
+				const sequenceName = seq.name ?? key.split(".").pop() ?? key;
+				if (satellite(sequenceName)) {
+					removedSequences.push(sequenceName);
+					changed = true;
+					continue;
+				}
+				const publicKey = qualifie && key.startsWith(`${schema}.`) ? `public.${key.slice(schema.length + 1)}` : key;
+				sequences[publicKey] = qualifie ? {
+					...seq,
+					schema: "public"
+				} : seq;
+				if (publicKey !== key) changed = true;
+			}
+			doc.sequences = sequences;
+		}
+		if (qualifie && doc.tables !== void 0) {
+			const tables = {};
+			for (const [key, table] of Object.entries(doc.tables)) {
+				const publicKey = key.startsWith(`${schema}.`) ? `public.${key.slice(schema.length + 1)}` : key;
+				tables[publicKey] = {
+					...table,
+					schema: ""
+				};
+				if (publicKey !== key) changed = true;
+			}
+			doc.tables = tables;
+			if (doc.schemas !== void 0) doc.schemas = {};
+		}
+		if (options.dialect === "mysql" && doc.tables !== void 0) {
+			for (const table of Object.values(doc.tables)) for (const column of Object.values(table.columns ?? {})) if (column.type === "tinyint(1)") {
+				column.type = "boolean";
+				booleans += 1;
+				changed = true;
+			}
+		}
+		if (stripTables.length > 0 && doc.tables !== void 0) {
+			const toRemove = new Set(stripTables);
+			const kept = {};
+			for (const [key, table] of Object.entries(doc.tables)) {
+				if (toRemove.has(key.split(".").pop() ?? key)) {
+					changed = true;
+					continue;
+				}
+				kept[key] = table;
+			}
+			doc.tables = kept;
+		}
+		if (changed) await fs.writeFile(snapshotFile, JSON.stringify(doc, null, 2), "utf8");
+	}
+	if (!qualifie && removedSequences.length === 0 && stripTables.length === 0 && booleans === 0) return;
+	let sql = await fs.readFile(file, "utf8");
+	if (booleans > 0) sql = sql.replace(/\btinyint\(1\)/giu, "boolean");
+	if (qualifie) sql = sql.replace(new RegExp(`^CREATE SCHEMA "${schema}";\\s*(?:-->[^\\n]*\\n)?`, "gmu"), "").replaceAll(`"${schema}".`, "");
+	for (const removedSequence of removedSequences) sql = sql.replace(new RegExp(`^CREATE SEQUENCE "${removedSequence}"[^;]*;(?:\\s*-->[^\\n]*)?\\n?`, "gmu"), "");
+	for (const tableName of stripTables) {
+		const ident = `[\`"]?${tableName.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}[\`"]?`;
+		sql = sql.replace(new RegExp(`^CREATE TABLE ${ident} \\([\\s\\S]*?^\\);(?:\\s*-->[^\\n]*)?\\n?`, "gmu"), "").replace(new RegExp(`^CREATE (?:UNIQUE )?INDEX [^;]*? ON ${ident}[^;]*;(?:\\s*-->[^\\n]*)?\\n?`, "gmu"), "").replace(new RegExp(`^ALTER TABLE ${ident}[^;]*;(?:\\s*-->[^\\n]*)?\\n?`, "gmu"), "");
+	}
+	await fs.writeFile(file, sql, "utf8");
+}
+/**
+* Parmi les tables qu'on s'apprête à CRÉER, celles que la base porte déjà.
+*
+* 🔴 **La base est la seule source, et elle est INTERROGÉE.** Il serait tentant
+* de déduire la présence d'une table de son absence dans une comparaison au
+* code : c'est ce que faisait la première version, et le raccourci a produit un
+* refus mensonger. La comparaison ne connaît que le REGISTRE — les entités
+* qu'une application enregistre à son démarrage — alors que la génération part
+* des FICHIERS, qui en contiennent d'autres : celles d'un module désactivé,
+* d'un connecteur différent, ou d'un module pas encore câblé. Une table hors
+* registre n'est ni manquante ni présente : elle est INCONNUE, et déduire sa
+* présence faisait refuser la première migration d'une application en nommant
+* sept tables qui n'existaient nulle part — puis renvoyait vers une adoption
+* qui échouait pour la raison inverse. Deux commandes qui se prescrivent l'une
+* l'autre en se refusant : une impasse, exactement celle que ce chantier
+* existe pour fermer.
+*
+* Le lecteur est INJECTÉ plutôt que construit ici : c'est ce qui rend la règle
+* éprouvable sans kernel ni serveur, et une règle qu'on ne peut pas voir rouge
+* n'est pas une règle.
+*
+* Le coût est d'une requête de catalogue par table, et l'appelant ne s'en sert
+* que lorsque le journal est vide — une fois dans la vie d'une application.
+*
+* @param reader - lecteur de catalogue ouvert sur la base visée.
+* @param tables - tables que la migration créerait.
+* @returns les tables déjà en base, dans l'ordre reçu.
+*/
+async function tablesPresentIn(reader, tables) {
+	const presentTables = [];
+	for (const candidateTable of tables) if (await reader.tableExists(candidateTable)) presentTables.push(candidateTable);
+	return presentTables;
+}
+/**
+* Ce que le serveur dit de LUI-MÊME — constaté, jamais déduit d'un port.
+*
+* Sert uniquement à expliquer un échec : c'est le seul moment où la question
+* se pose, et le coût d'une requête est alors sans importance.
+*
+* @param target - cible du connecteur.
+* @returns la bannière de version, ou `null` si le serveur n'a pas répondu.
+*/
+async function serverVersion(target) {
+	try {
+		const driver = await openMigrationDriver(target);
+		try {
+			return (await driver.query("SELECT VERSION() AS v"))[0]?.v ?? null;
+		} finally {
+			await driver.close();
+		}
+	} catch {
+		return null;
+	}
+}
+/**
+* Explique l'échec d'une lecture de schéma, avec ce qu'on en SAIT.
+*
+* L'outil meurt sans un mot — code non nul, sortie d'erreur vide. Le laisser
+* remonter tel quel enverrait chercher du côté des identifiants ou du réseau,
+* là où il n'y a rien. Une cause est connue et reproductible, elle mérite
+* d'être nommée.
+*
+* @param target - cible du connecteur.
+* @param cause - l'erreur telle que l'outil l'a produite.
+* @returns l'erreur à lever.
+*/
+async function explainFailure(target, cause) {
+	const version = await serverVersion(target);
+	if (version !== null && /mariadb/i.test(version)) return new Error(`La lecture du schéma a échoué sur ce serveur (MariaDB ${version}).\n\n  MariaDB ne porte pas de type JSON natif : il l'écrit en « longtext »\n  assorti d'une contrainte « CHECK (json_valid(…)) ». L'outil qui lit les\n  schémas ne sait pas lire ces contraintes, et il s'arrête sans rien dire —\n  y compris quand les tables concernées ne sont PAS celles qu'on adopte :\n  il lit la base ENTIÈRE avant de filtrer. Les tables du framework en\n  portent, donc le cas est systématique ici.\n\n  Le repli, sur ce serveur : écrire la référence à la main.\n    1. relever le schéma existant  — SHOW CREATE TABLE <table>\n    2. nodefony orm:generate --custom --name base_existante\n    3. coller ce schéma dans le fichier produit\n    4. nodefony orm:migrate:baseline\n\n  Sur MySQL Community, PostgreSQL et SQLite, « --from-database » fait ces\n  quatre gestes seul.`, { cause });
+	return cause;
+}
+/**
+* Les contraintes d'unicité de COLONNE que l'introspection n'a pas rendues.
+*
+* 🔴 En SQLite, `col text UNIQUE` ne crée pas d'index nommé : le moteur pose un
+* index INTERNE (`sqlite_autoindex_…`) que l'outil d'introspection ne liste
+* pas. La référence adoptée sortait donc SANS la contrainte, alors que la base
+* la porte — et un index unique COMPOSITE, lui, survivait, ce qui rendait
+* l'écart d'autant plus difficile à voir.
+*
+* La perte ne se constate pas sur la base adoptée : elle a déjà sa contrainte.
+* Elle frappe la base SUIVANTE — un environnement de test, un exemplaire neuf —
+* recréée depuis ce fichier, qui accepte alors des doublons que le schéma
+* interdisait. Aucune erreur n'est levée : c'est la donnée qui devient fausse.
+*
+* On les rend sous forme de `CREATE UNIQUE INDEX`, et non en réécrivant le
+* `CREATE TABLE` : un index séparé est portable, s'ajoute sans toucher au corps
+* produit par l'outil, et porte exactement la même garantie.
+*
+* Les autres moteurs n'ont pas ce défaut — leur catalogue expose la contrainte,
+* et l'introspection la rend (vérifié : PostgreSQL et MySQL passent le cas qui
+* fait tomber SQLite).
+*
+* @param target - cible du connecteur adopté.
+* @param tables - tables retenues par l'adoption.
+* @param sql - la référence telle que l'outil l'a écrite.
+* @returns les instructions à ajouter, vides s'il n'en manque aucune.
+*/
+/**
+* Les colonnes d'index, telles que PostgreSQL les RÉÉCRIT lui-même.
+*
+* 🔴 L'introspection rend UNE classe d'opérateur pour tout l'index et
+* l'applique à CHAQUE colonne. Sur un index composite dont les colonnes n'ont
+* pas le même type, le résultat est du SQL qui ne s'exécute pas :
+* `("author" timestamptz_ops, "created_at" timestamptz_ops)` quand `author`
+* est un `uuid` — « operator class "timestamptz_ops" does not accept data
+* type uuid ».
+*
+* La perte ne se constate pas sur la base adoptée : elle a déjà son index.
+* Elle frappe l'exemplaire SUIVANT — et elle frappe mal, car la migration
+* s'arrête sur ce `CREATE INDEX` : aucune table suivante n'est créée, et les
+* erreurs que l'on voit ensuite ne parlent plus que de tables absentes, à
+* l'autre bout de la chaîne. Même famille que les contraintes d'unicité
+* perdues : l'outil est fidèle à ce qu'il croit avoir lu, pas à la base.
+*
+* On ne DEVINE pas la bonne classe, on la demande au moteur. `pg_indexes`
+* rend la définition que PostgreSQL écrirait lui-même pour recréer l'index,
+* et il n'y nomme que les classes qui ne sont PAS celles du type — ce qui
+* préserve une classe volontaire (`varchar_pattern_ops`) sans jamais en
+* inventer une.
+*
+* @param target - coordonnées de la base visée.
+* @param schema - schéma PostgreSQL où les tables ont été lues.
+* @param tables - tables adoptées, dont on relit les index.
+* @returns pour chaque nom d'index, la liste de colonnes que le moteur écrit.
+*/
+async function actualIndexColumns(target, schema, tables) {
+	const byName = /* @__PURE__ */ new Map();
+	if (target.dialect !== "postgres" || tables.length === 0) return byName;
+	const driver = await openMigrationDriver(target);
+	try {
+		const placeholders = tables.map(() => "?").join(",");
+		const rows = await driver.query(`SELECT indexname, indexdef FROM pg_indexes
+        WHERE schemaname = ? AND tablename IN (${placeholders})`, [schema, ...tables]);
+		for (const row of rows) {
+			const columns = /\(([^()]*(?:\([^()]*\)[^()]*)*)\)\s*$/u.exec(row.indexdef);
+			if (columns?.[1] !== void 0) byName.set(row.indexname, columns[1].trim());
+		}
+	} finally {
+		await driver.close();
+	}
+	return byName;
+}
+/**
+* Réécrit les listes de colonnes d'index que l'outil a rendues fausses.
+*
+* Agit sur les DEUX artefacts, et c'est nécessaire : le fichier SQL est ce
+* qu'on applique, l'instantané est ce à quoi la génération SUIVANTE compare.
+* Ne corriger que le premier laisserait un instantané qui décrit un index que
+* la base n'a pas — la génération d'après proposerait de le refaire, sans que
+* personne comprenne pourquoi.
+*
+* @param sql - corps exécutable de la référence.
+* @param outDir - dossier de sortie, qui porte `meta/0000_snapshot.json`.
+* @param actual - listes de colonnes rendues par le moteur, par nom d'index.
+* @returns le SQL corrigé.
+*/
+async function rewriteCompositeIndexes(sql, outDir, actual) {
+	if (actual.size === 0) return sql;
+	let fixed = sql;
+	for (const [indexName, columns] of actual) {
+		const echappe = indexName.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+		fixed = fixed.replace(new RegExp(`(CREATE\\s+(?:UNIQUE\\s+)?INDEX\\s+"${echappe}"[^;]*?USING\\s+\\w+\\s*)\\([^;]*?\\)`, "giu"), `$1(${columns})`);
+	}
+	const snapshotFile = path.join(outDir, "meta", "0000_snapshot.json");
+	try {
+		const doc = JSON.parse(await fs.readFile(snapshotFile, "utf8"));
+		let changed = false;
+		for (const table of Object.values(doc.tables ?? {})) for (const [key, index] of Object.entries(table.indexes ?? {})) {
+			const columns = actual.get(index.name ?? key);
+			if (columns === void 0) continue;
+			for (const column of index.columns ?? []) {
+				const columnName = column.expression;
+				const named = columnName === void 0 || column.isExpression === true ? void 0 : new RegExp(`(?:^|,)\\s*"?${columnName.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}"?\\s+(\\w+_ops)\\b`, "u").exec(columns)?.[1];
+				if (named === void 0) {
+					if (column.opclass !== void 0) {
+						delete column.opclass;
+						changed = true;
+					}
+				} else if (column.opclass !== named) {
+					column.opclass = named;
+					changed = true;
+				}
+			}
+		}
+		if (changed) await fs.writeFile(snapshotFile, JSON.stringify(doc, null, 2), "utf8");
+	} catch {}
+	return fixed;
+}
+async function lostColumnUniques(target, tables, sql) {
+	if (target.dialect !== "sqlite") return [];
+	const additions = [];
+	const driver = await openMigrationDriver(target);
+	try {
+		for (const table of tables) {
+			const ident = `"${table.replace(/"/gu, "\"\"")}"`;
+			const index = await driver.query(`PRAGMA index_list(${ident})`);
+			for (const idx of index) {
+				if (Number(idx.unique) !== 1 || idx.origin !== "u") continue;
+				const names = (await driver.query(`PRAGMA index_info("${String(idx.name).replace(/"/gu, "\"\"")}")`)).map((c) => c.name).filter((n) => n !== null);
+				if (names.length === 0) continue;
+				const constraintName = `${table}_${names.join("_")}_key`;
+				if (sql.includes(constraintName)) continue;
+				const quotedNames = names.map((n) => `\`${n}\``).join(",");
+				additions.push(`CREATE UNIQUE INDEX \`${constraintName}\` ON \`${table}\` (${quotedNames});`);
+			}
+		}
+	} finally {
+		await driver.close();
+	}
+	return additions;
+}
+/**
+* Fabrique la migration de RÉFÉRENCE d'une base déjà en place.
+*
+* Orchestration complète du côté fichiers — la connexion est lue, rien n'est
+* écrit dans la base : c'est l'appelant qui décide ensuite d'inscrire cette
+* migration dans l'historique.
+*
+* Le dossier de travail ne survit à rien, ni au succès ni à l'échec : un module
+* temporaire laissé derrière serait relu par le prochain outil qui balaie les
+* sources, et personne ne saurait d'où il sort.
+*
+* @param options - racine du projet, dossier de sortie, cible, tables exclues,
+*   tables déclarées, nom voulu pour la migration, dossier de travail.
+* @returns le tag final, le fichier, et si son corps est exécutable.
+* @throws Error si la base ne porte aucune table à adopter, ou si l'outil échoue.
+*/
+async function adoptFromDatabase({ projectRoot, outDir, dialect, target, excludedTables, declaredTables, name, workDir }) {
+	if (declaredTables.length === 0) throw new Error("Cette application ne déclare aucune table sur ce connecteur : il n'y a rien à adopter.");
+	const url = introspectionUrl(target);
+	if (url === null) throw new Error("La base visée n'a pas de coordonnées de connexion : impossible de lire son schéma.");
+	const configFile = path.join(workDir, `introspect.${dialect}.config.ts`);
+	const relatif = (targetFile) => path.relative(projectRoot, targetFile).split(path.sep).join("/");
+	const lectureSansExclusion = dialect === "mysql" && excludedTables.length > 0;
+	try {
+		await writeKitConfig({
+			file: configFile,
+			projectRoot,
+			schemaFile: path.join(workDir, `schema.${dialect}.ts`),
+			outDir,
+			dialect,
+			excludedTables: lectureSansExclusion ? [] : excludedTables,
+			dbUrl: url
+		});
+		try {
+			runIntrospect({
+				cwd: projectRoot,
+				configRel: relatif(configFile),
+				label: `la base du connecteur (${dialect})`
+			});
+		} catch (e) {
+			throw await explainFailure(target, e);
+		}
+	} finally {
+		await fs.rm(workDir, {
+			recursive: true,
+			force: true
+		});
+	}
+	const premiere = (await readJournal(outDir))?.entries[0];
+	if (!premiere) throw new Error(`La lecture du schéma n'a produit aucune migration : cette base ne porte aucune des tables de l'application (${declaredTables.join(", ")}).`);
+	const tag = `0000_${name}`;
+	const file = await renameTag(outDir, premiere.tag, tag);
+	await dropIntrospectionModules(outDir);
+	const schema = dialect === "postgres" ? postgresSchemaOf(url) : null;
+	await normalizeIntrospection(outDir, file, {
+		schema,
+		excludedTables,
+		stripTables: lectureSansExclusion ? excludedTables : [],
+		dialect
+	});
+	const readTables = await snapshotTables(outDir);
+	const declarees = new Set(declaredTables);
+	const executable = uncommentIntrospection(await fs.readFile(file, "utf8"));
+	if (executable !== null) {
+		const missing = await lostColumnUniques(target, readTables, executable);
+		const fixed = await rewriteCompositeIndexes(missing.length === 0 ? executable : `${executable.trimEnd()}\n--> statement-breakpoint\n${missing.join("\n--> statement-breakpoint\n")}\n`, outDir, await actualIndexColumns(target, schema ?? "public", readTables));
+		await fs.writeFile(file, fixed, "utf8");
+	}
+	return {
+		tag,
+		file,
+		runnable: executable !== null,
+		extraTables: readTables.filter((t) => !declarees.has(t))
+	};
+}
+//#endregion
+export { adoptFromDatabase, dropIntrospectionModules, introspectionUrl, normalizeIntrospection, readJournal, renameTag, snapshotTables, tablesPresentIn, uncommentIntrospection };