@nodefony/drizzle 10.0.0-alpha.1

package/dist/types/nodefony/src/migrator/appSchema.d.ts

@@ -0,0 +1,223 @@
+import type { SqlDialect } from "../../interfaces/IDrizzleConfig.js";
+/** Une table trouvée dans un fichier d'entité de l'application. */
+export interface IDiscoveredTable {
+    /** Chemin absolu du fichier qui l'exporte. */
+    file: string;
+    /** Nom sous lequel le fichier l'exporte (`postTable`, `PostEntity`…). */
+    exportName: string;
+    /** Nom de la table en base — c'est lui qui compte, pas l'identifiant JS. */
+    tableName: string;
+    /** Moteur pour lequel elle est écrite — `null` si aucun des trois. */
+    dialect: SqlDialect | null;
+}
+/** Ce qu'un fichier d'entité a refusé de livrer. */
+export interface IUnreadableEntityFile {
+    /** Chemin absolu du fichier. */
+    file: string;
+    /** La cause, telle que l'import l'a rendue. */
+    cause: string;
+}
+/** Résultat d'une découverte : ce qui a été lu, et ce qui a résisté. */
+export interface IDiscoveredSchema {
+    tables: IDiscoveredTable[];
+    unreadable: IUnreadableEntityFile[];
+}
+/**
+ * Fichiers d'entités d'une cible (l'application, ou l'un de ses modules).
+ *
+ * Les `*.schema.ts` sont écartés : c'est la convention du générateur pour les
+ * contrats d'entrée (Zod), qui n'ont rien à faire dans un schéma de base.
+ *
+ * @param targetDir - dossier d'une cible (contient `index.ts` + `nodefony/`).
+ * @returns les chemins absolus, triés — l'ordre doit être le même partout.
+ */
+export declare function entityFilesOf(targetDir: string): Promise<string[]>;
+/**
+ * Importe des fichiers d'entités et relève les tables qu'ils exportent.
+ *
+ * L'import est la seule façon HONNÊTE de savoir ce qu'un fichier fournit : lire
+ * un nom d'export au motif qu'il finit par `Table` marcherait sur le code que
+ * le générateur écrit, et sur rien d'autre — or ces fichiers sont faits pour
+ * être modifiés à la main, c'est même écrit dans leur en-tête.
+ *
+ * Un fichier qui refuse de s'importer n'est PAS ignoré : il est rendu à
+ * l'appelant avec sa cause. C'est presque toujours le même défaut — un accès au
+ * kernel à l'évaluation du module — et le taire produirait une migration
+ * amputée là où il faut une phrase.
+ *
+ * @param files - chemins absolus des fichiers d'entités.
+ * @returns les tables trouvées et les fichiers illisibles.
+ */
+export declare function collectTables(files: readonly string[]): Promise<IDiscoveredSchema>;
+/**
+ * Moteur pour lequel une table est écrite.
+ *
+ * Une entité d'application est du Drizzle **natif** : `sqliteTable`, `pgTable` et
+ * `mysqlTable` produisent trois objets différents, et une table écrite pour un
+ * moteur est simplement IGNORÉE par l'outil quand il en génère un autre — sans
+ * un mot, comme d'habitude. Constaté sur une application témoin : six tables
+ * découvertes, quatre écrites, et un message qui annonçait six.
+ *
+ * @param table - table relevée dans un fichier d'entité.
+ * @returns le dialecte, ou `null` si ce n'est aucun des trois.
+ */
+export declare function dialectOf(table: unknown): SqlDialect | null;
+/**
+ * Spécificateur d'import de `from` vers `to`, écrit pour VOYAGER.
+ *
+ * Un spécificateur s'écrit en `/` sur les trois systèmes — c'est du texte que
+ * lit un outil, pas un accès disque. L'extension est explicite : le module
+ * temporaire est compilé par l'outil, qui doit savoir quoi ouvrir sans deviner.
+ *
+ * @param fromFile - fichier qui contiendra l'import.
+ * @param toFile - fichier visé.
+ * @returns un spécificateur relatif, toujours préfixé `./` ou `../`.
+ */
+export declare function importSpecifier(fromFile: string, toFile: string): string;
+/**
+ * Écrit le module temporaire que `drizzle-kit` lira comme « le schéma ».
+ *
+ * Chaque table reçoit un alias unique et neutre : deux fichiers peuvent très
+ * bien exporter deux tables sous le même identifiant JS, et un ré-export en
+ * étoile les rendrait AMBIGUËS — l'ambiguïté n'est pas une erreur en ESM, c'est
+ * une absence silencieuse. Le nom de la table en base, lui, n'est pas touché :
+ * il vit dans l'appel `…Table("nom")`, pas dans l'identifiant.
+ *
+ * @param file - chemin du module à écrire.
+ * @param tables - tables à ré-exporter, dans l'ordre de découverte.
+ * @returns le contenu écrit (rendu pour les bancs).
+ */
+export declare function writeSchemaModule(file: string, tables: readonly IDiscoveredTable[]): Promise<string>;
+/**
+ * Schéma PostgreSQL réellement visé par une URL de connexion.
+ *
+ * 🔴 L'outil d'introspection ne suit PAS le `search_path` porté par l'URL : il
+ * lit `public`, quoi qu'on lui donne. Sans cette dérivation, adopter une
+ * application logée dans un schéma dédié — le montage habituel d'une base
+ * mutualisée — écrivait la référence des tables de `public`, c'est-à-dire
+ * celles de quelqu'un d'autre, et déclarait absentes les siennes. Constaté sur
+ * un serveur réel : la référence décrivait trois tables étrangères au projet.
+ *
+ * Deux formes sont reconnues, parce que les deux circulent : le `search_path`
+ * passé dans `options`, et le paramètre `schema` que posent certains outils.
+ * Une URL sans rien rend `null` — l'appelant laisse alors le défaut de l'outil,
+ * qui est le bon.
+ *
+ * @param url - URL de connexion, telle que le connecteur la porte.
+ * @returns le premier schéma du chemin de recherche, ou `null`.
+ */
+export declare function postgresSchemaOf(url: string): string | null;
+/**
+ * Écrit la configuration `drizzle-kit` d'une génération d'application.
+ *
+ * 🔴 **Les chemins y sont RELATIFS, et ce n'est pas un style.** L'outil préfixe
+ * son dossier de sortie par `./` : un chemin absolu devient `.//Users/…`, la
+ * lecture échoue — et l'échec se présente comme un succès, puisque l'outil rend
+ * 0 quand il rate. La configuration est donc écrite pour être lue depuis la
+ * racine de l'application, qui est le dossier d'exécution.
+ *
+ * `tablesFilter` exclut ce que l'application ne possède pas : les tables du
+ * framework et la table d'historique. Sans lui, une entité d'application qui
+ * référence une table du framework la ferait entrer dans le diff, et la
+ * migration porterait un second `CREATE TABLE` de cette table — qui échoue en
+ * production, sur toute base déjà migrée.
+ *
+ * @param options - où écrire, quoi lire, où sortir, quoi exclure.
+ * @returns le contenu écrit (rendu pour les bancs).
+ */
+export declare function writeKitConfig({ file, projectRoot, schemaFile, outDir, dialect, excludedTables, dbUrl, }: {
+    file: string;
+    projectRoot: string;
+    schemaFile: string;
+    outDir: string;
+    dialect: SqlDialect;
+    excludedTables: readonly string[];
+    /**
+     * Coordonnées de connexion — posées UNIQUEMENT pour l'introspection.
+     *
+     * La génération, elle, ne touche aucune base : son diff se calcule entre les
+     * instantanés du dossier et les entités. Écrire des coordonnées dans sa
+     * configuration laisserait croire le contraire à qui relit le fichier, et
+     * ferait porter à une commande de lecture pure le risque d'une connexion.
+     */
+    dbUrl?: string;
+}): Promise<string>;
+/**
+ * Écrit une migration LIBRE et son entrée de journal, sans `drizzle-kit`.
+ *
+ * C'est la porte de sortie du modèle déclaratif : une vue, un déclencheur, une
+ * clé étrangère réelle, un remplissage de données ne se DÉDUISENT d'aucun
+ * schéma. Sans elle, on n'aurait le choix qu'entre renoncer et écrire un
+ * fichier à la main dans un journal dont le format n'est pas documenté — deux
+ * façons de casser l'historique.
+ *
+ * Le fichier est vide de toute instruction : un squelette qui « propose » du
+ * SQL est un squelette qu'on applique sans le lire.
+ *
+ * @param options - dossier de sortie, dialecte, nom de la migration.
+ * @returns le tag attribué et le chemin du fichier écrit.
+ * @throws Error si le journal existant est illisible — on n'en réécrit JAMAIS
+ *   un par-dessus : il porte l'historique déjà appliqué en production.
+ */
+export declare function writeCustomMigration({ outDir, dialect, name, now, }: {
+    outDir: string;
+    dialect: SqlDialect;
+    name: string;
+    now?: number;
+}): Promise<{
+    tag: string;
+    file: string;
+}>;
+/** Une entité que le registre connaît, et la table qu'elle vise. */
+export interface IExpectedEntity {
+    /** Nom logique de l'entité, tel qu'il est enregistré. */
+    entity: string;
+    /** Nom de la table en base. */
+    table: string;
+}
+/**
+ * Ce que le registre attend et que les fichiers ne fournissent PAS.
+ *
+ * C'est le seul contrôle qu'un registre puisse rendre et qu'aucun outil de
+ * génération ne rendra jamais : `drizzle-kit` ne sait pas ce qu'une application
+ * a déclaré, il ne voit que ce qu'on lui donne à lire. Sans cette confrontation,
+ * une entité dont le fichier a été déplacé, renommé, ou rendu illisible
+ * disparaît de la migration **sans un mot** — et une migration ne se corrige
+ * pas : elle est immuable dès qu'une base l'a reçue.
+ *
+ * Les tables du framework sont écartées des deux côtés : elles sont fournies par
+ * une autre source, appliquée avant.
+ *
+ * @param expected - entités du registre, sur le connecteur visé.
+ * @param providedTables - noms des tables que les fichiers découverts fournissent.
+ * @param frameworkTables - noms des tables construites par le framework.
+ * @returns les entités sans fournisseur, dans l'ordre reçu.
+ */
+export declare function missingProviders(expected: readonly IExpectedEntity[], providedTables: ReadonlySet<string>, frameworkTables: ReadonlySet<string>): IExpectedEntity[];
+/**
+ * Les tables de l'application qui usurpent une table du framework.
+ *
+ * Deux `CREATE TABLE` pour un même nom : la migration passe sur une base vierge
+ * et échoue sur toute base déjà migrée — c'est-à-dire en production, et nulle
+ * part ailleurs. C'est le pire endroit pour découvrir la faute, donc on la dit
+ * avant d'écrire quoi que ce soit.
+ *
+ * @param tables - tables fournies par les fichiers de l'application.
+ * @param frameworkTables - noms des tables construites par le framework.
+ * @returns les tables en conflit, avec le fichier qui les exporte.
+ */
+export declare function usurpedTables(tables: readonly IDiscoveredTable[], frameworkTables: ReadonlySet<string>): IDiscoveredTable[];
+/**
+ * Tables attendues sur un connecteur, telles que le REGISTRE les connaît.
+ *
+ * Le registre est la seule source qui sache ce que l'application DÉCLARE :
+ * les fichiers disent ce qu'elle fournit, la base ce qu'elle porte, et c'est
+ * le croisement des trois qui fait les verdicts. Deux commandes en dépendent —
+ * la génération pour repérer une entité sans fichier, l'adoption pour ne lire
+ * QUE les tables de l'application — et une seconde copie divergerait en
+ * silence.
+ *
+ * @param connector - connecteur visé.
+ * @returns les entités et leur table, dans l'ordre du registre.
+ */
+export declare function registeredTables(connector: string): IExpectedEntity[];

package/dist/types/nodefony/src/migrator/catalog.d.ts

@@ -0,0 +1,100 @@
+import type { SqlDialect } from "../../config/config.js";
+/**
+ * Lecture du catalogue du serveur — quelles tables existent, quelles colonnes
+ * elles portent —, écrite UNE fois par dialecte et partagée par ses deux
+ * porteurs.
+ *
+ * ## Pourquoi ce fichier existe
+ *
+ * Deux composants ont besoin de la même réponse, depuis deux connexions
+ * différentes : le pilote de l'applicateur de migrations, qui tient sa propre
+ * connexion, et l'ORM, qui compare son schéma déclaré à la base **sur la
+ * connexion qu'il a déjà**. Recopier les trois requêtes chez le second les
+ * ferait diverger en silence — chacune passant ses propres tests — et la
+ * divergence ne se verrait qu'à travers un verdict FAUX rendu à un exploitant.
+ *
+ * ## Pourquoi l'ORM n'ouvre pas simplement un pilote de migration
+ *
+ * Parce qu'une seconde connexion sur `:memory:` désigne une base **différente
+ * et vide**. Le diff y annoncerait toutes les tables manquantes et un
+ * rattrapage y écrirait dans une base que personne ne lit. Le lecteur est donc
+ * paramétré par l'exécuteur de requêtes de son porteur, jamais par une
+ * connexion à lui.
+ */
+/**
+ * Exécute une requête paramétrée et rend ses lignes.
+ *
+ * Les paramètres s'écrivent `?` dans tous les dialectes ; c'est au porteur de
+ * traduire s'il le faut (PostgreSQL attend `$1`).
+ */
+export type SqlQuery = <T extends Record<string, unknown>>(sql: string, params?: readonly unknown[]) => Promise<T[]>;
+/** Ce dont la comparaison de schéma a besoin, et rien de plus. */
+export interface ISchemaReader {
+    /**
+     * Deux noms de COLONNE désignent-ils la même, pour ce moteur ?
+     *
+     * 🔴 **La sémantique est celle du MOTEUR** : si le serveur sait résoudre ce
+     * nom dans un `SELECT`, la colonne existe pour l'application ; sinon la
+     * requête du code échouerait vraiment, et l'annoncer manquante est JUSTE.
+     *
+     * - **SQLite** — sans distinction de casse, comme sa résolution de noms.
+     * - **MySQL** — sans distinction de casse, sur **toutes** les plateformes :
+     *   contrairement aux tables, les noms de colonnes ne dépendent pas de
+     *   `lower_case_table_names`.
+     * - **PostgreSQL** — EXACT : les identifiants sont cités (Drizzle cite tout),
+     *   donc `SELECT "createdAt"` sur une colonne `createdat` échoue pour de bon.
+     *
+     * ⚠️ **Il n'y a délibérément PAS d'équivalent synchrone pour les TABLES.**
+     * Leur sensibilité à la casse dépend de la MACHINE — `lower_case_table_names`
+     * vaut `0` sur Linux (sensible, constaté sur MySQL 8.4) et `1` ou `2`
+     * ailleurs. Une règle déduite du seul dialecte serait donc fausse une fois
+     * sur deux, sans que rien ne le dise. Elle se **CONSTATE** par
+     * {@link ISchemaReader.tableExists}, qui interroge le catalogue du serveur et
+     * hérite de sa collation — jamais elle ne se déduit.
+     *
+     * @param declared - nom tel que le code le déclare.
+     * @param actual - nom tel que la base le rend.
+     * @returns `true` si le moteur les résoudrait vers la même colonne.
+     */
+    sameColumnName(declared: string, actual: string): boolean;
+    /** La table existe-t-elle dans le schéma courant de la connexion ? */
+    tableExists(table: string): Promise<boolean>;
+    /** Colonnes de la table, telles que la base les déclare. */
+    columnsOf(table: string): Promise<string[]>;
+}
+/**
+ * Compare deux noms de COLONNE selon la résolution du moteur.
+ *
+ * Exportée parce qu'elle porte une RÈGLE : la recopier ailleurs la ferait
+ * diverger, et une divergence de casse ne se voit que sur une base adoptée,
+ * c'est-à-dire chez l'utilisateur.
+ *
+ * Elle ne vaut PAS pour les tables — voir {@link ISchemaReader.sameColumnName},
+ * qui dit pourquoi leur sensibilité se constate au lieu de se déduire.
+ *
+ * @param dialect - moteur qui résoudrait le nom.
+ * @param declared - nom tel que le code le déclare.
+ * @param actual - nom tel que la base le rend.
+ * @returns `true` si le moteur les résoudrait vers la même colonne.
+ */
+export declare function sameColumnName(dialect: SqlDialect, declared: string, actual: string): boolean;
+/**
+ * Compose un lecteur de catalogue au-dessus d'un exécuteur de requêtes.
+ *
+ * @param dialect - dialecte du serveur interrogé.
+ * @param query - exécuteur du porteur (pilote de migration, ou ORM connecté).
+ * @returns le lecteur, sans état ni connexion propre.
+ */
+export declare function schemaReader(dialect: SqlDialect, query: SqlQuery): ISchemaReader;
+/**
+ * Traduit les paramètres `?` du dialecte commun en `$n` PostgreSQL.
+ *
+ * L'applicateur écrit ses requêtes une seule fois, avec la forme la plus
+ * répandue ; chaque pilote l'adapte. Aucune des requêtes de l'applicateur ne
+ * contient de littéral `?` — les valeurs, elles, sont bindées, jamais
+ * concaténées.
+ *
+ * @param sql - requête écrite avec des `?`.
+ * @returns la même requête, paramètres numérotés.
+ */
+export declare function toDollarParams(sql: string): string;

package/dist/types/nodefony/src/migrator/destructive.d.ts

@@ -0,0 +1,123 @@
+import type { IMigrationFile } from "./types.js";
+/**
+ * Ce qu'une migration s'apprête à DÉTRUIRE — constaté avant d'appliquer.
+ *
+ * ## Pourquoi ce garde existe, alors qu'aucun outil de migration n'en a
+ *
+ * La question posée était : « faut-il sauvegarder la base avant une
+ * migration ? ». La réponse honnête est **non, et personne ne le fait** —
+ * Flyway, Liquibase, Rails, Django, Alembic, Prisma : aucun ne sauvegarde. Les
+ * raisons tiennent :
+ *
+ * - l'outil n'a **ni les droits, ni la place, ni le temps**. Le compte qui migre
+ *   a le droit de modifier le schéma, pas d'exporter toutes les données — et
+ *   c'est exactement ce qu'on veut ;
+ * - la sauvegarde est un **métier d'exploitation** (instantané de volume,
+ *   restauration à un instant donné, réplica), déjà outillé et déjà froid ;
+ * - un instantané pris par l'outil donnerait une **fausse assurance**.
+ *   Restaurer une base de production est une décision et une interruption de
+ *   service, jamais un drapeau qu'on tape par réflexe. Le pire des scénarios
+ *   est celui où quelqu'un migre sans précaution *parce que « l'outil
+ *   sauvegarde »*.
+ *
+ * Mais il restait un vrai trou, et c'est lui qu'on ferme ici : **appliquer un
+ * `DROP COLUMN` en production sans un mot**. L'outil ne sauvegarde pas — il
+ * **empêche d'appliquer sans savoir**. C'est ce que fait l'analyse de Atlas, et
+ * ce qu'aucun applicateur de l'écosystème Node ne propose.
+ *
+ * ## Ce que ce scan N'EST PAS
+ *
+ * Ce n'est pas un analyseur syntaxique SQL, et il ne prétend pas à
+ * l'exhaustivité : il reconnaît des formes. Une instruction destructive écrite
+ * d'une façon qu'il ne connaît pas passera. **Il ne remplace donc jamais la
+ * lecture du SQL** (`--dry-run`), et surtout pas la règle qui protège vraiment :
+ * ne jamais faire un changement destructif dans la même version que le code qui
+ * s'en sert (étendre, déployer, migrer les données, retirer une version plus
+ * tard). Le retour arrière porte alors sur le CODE, jamais sur la base.
+ *
+ * Un faux positif coûte une lecture et un drapeau ; un faux négatif coûte des
+ * données. Le scan penche donc toujours du côté du signalement.
+ */
+/** Gravité d'une trouvaille — elles ne se traitent pas pareil. */
+export type DestructiveSeverity = 
+/** Des données existantes disparaissent. Refusé hors développement. */
+"data-loss"
+/**
+ * Rien ne disparaît, mais l'instruction peut échouer sur des données
+ * existantes, ou casser le code de la version précédente. Signalé, jamais
+ * bloquant : c'est le lot normal d'une migration qui fait évoluer un schéma.
+ */
+ | "breaking";
+/** Une instruction qui mérite d'être vue avant d'être exécutée. */
+export interface IDestructiveFinding {
+    source: string;
+    tag: string;
+    /** Chemin du fichier — pour aller le lire. */
+    path: string;
+    severity: DestructiveSeverity;
+    /** Étiquette courte et stable, lisible par une machine. */
+    kind: string;
+    /** Ce qui est perdu ou risqué, en français. */
+    what: string;
+    /** L'instruction elle-même, bornée pour rester lisible. */
+    statement: string;
+}
+/**
+ * Cherche, dans les migrations en attente, ce qui détruit ou casse.
+ *
+ * @param files - migrations qui vont être appliquées.
+ * @returns une trouvaille par instruction reconnue, dans l'ordre d'application.
+ */
+export declare function scanDestructive(files: readonly IMigrationFile[]): IDestructiveFinding[];
+/** Les trouvailles qui font vraiment disparaître des données. */
+export declare function dataLoss(findings: readonly IDestructiveFinding[]): IDestructiveFinding[];
+/**
+ * Rend le bilan lisible par un humain — le fait, puis ce qu'il faut faire.
+ *
+ * @param findings - trouvailles à présenter.
+ * @param bloquant - la commande refuse-t-elle d'appliquer ?
+ * @returns le texte, sans mise en forme (l'appelant colore s'il le veut).
+ */
+export declare function renderDestructive(findings: readonly IDestructiveFinding[], bloquant: boolean): string;
+/** Les gestes proposés face à un refus destructif. */
+export declare function destructiveActions(connector: string): string[];
+/** Résumé d'une ligne, pour un message ou un journal. */
+export declare function summarizeDestructive(findings: readonly IDestructiveFinding[], connector: string): string;
+/**
+ * Ce lot de migrations touche-t-il des lignes qui existaient déjà ?
+ *
+ * @param files - migrations sur le point d'être appliquées.
+ * @returns vrai dès qu'une instruction modifie une table existante.
+ */
+export declare function touchesExistingRows(files: readonly {
+    statements: readonly string[];
+}[]): boolean;
+/**
+ * Comment vérifier qu'une migration a préservé les données — **en UN geste**.
+ *
+ * Cette phrase existe parce que la sortie de SUCCÈS ne disait rien. Le produit
+ * annonçait « ✓ 1 migration appliquée » et s'arrêtait là ; l'agent à qui l'on
+ * demandait de prouver que les données avaient suivi n'avait aucun moyen sous
+ * les yeux, et celui qu'il inventait — repartir d'une base vide — détruit
+ * précisément ce qu'il fallait observer.
+ *
+ * 🔴 Elle NOMME la base, et c'est ce qui manquait au premier jet. Dire « une
+ * copie de la base » sans dire laquelle laisse deviner un chemin : mesuré au
+ * banc, l'agent a suivi le conseil, visé le mauvais fichier, vu son `cp`
+ * échouer en silence, puis FABRIQUÉ une base au client SQL — avec une table
+ * d'historique inventée. La migration a été refusée sur cette base bancale, et
+ * c'est ce refus qui l'a renvoyé détruire la vraie. Le produit connaissait
+ * pourtant l'emplacement : il le publie dans sa propre sortie.
+ *
+ * Elle nomme aussi les deux interpréteurs : « VAR=x commande » est de la
+ * syntaxe POSIX, que celui de Windows refuse.
+ *
+ * @param connector - connecteur visé, pour composer la commande.
+ * @param target - la base telle que le rapport la publie (`driver.target`),
+ *   et son dialecte : on copie un FICHIER en sqlite, on exporte ailleurs.
+ * @returns la phrase à rendre après une application réussie.
+ */
+export declare function checkDataAdvice(connector: string, target?: {
+    dialect: string;
+    target?: string;
+}): string;

package/dist/types/nodefony/src/migrator/divergence.d.ts

@@ -0,0 +1,61 @@
+import type { IMigrationPlan } from "./types.js";
+import { type ISchemaComparison } from "./schemaDiff.js";
+/**
+ * Ce que la base porte face à ce que le code DÉCLARE, sans condition de verdict.
+ *
+ * Séparé de {@link describeDivergence} parce que les deux répondent à des
+ * questions différentes, et que la seconde REFUSE de répondre avant que le plan
+ * soit à jour — ce qui est juste pour un rapport d'état (un écart n'a de sens
+ * qu'une fois tout appliqué) et faux pour qui doit décider AVANT d'agir.
+ *
+ * Le cas qui a exigé cette séparation : l'adoption d'une base existante. Elle
+ * doit constater l'état RÉEL avant d'écrire quoi que ce soit dans l'historique
+ * — après, il est trop tard, l'affirmation est déjà gravée.
+ *
+ * Ne modifie jamais rien, et ne jette jamais : une base muette n'est pas une
+ * divergence, c'est une panne, qui a sa propre voie de signalement.
+ *
+ * @param connector - nom du connecteur à interroger.
+ * @returns les écarts nommés, ou `null` (rien à dire, ou rien d'interrogeable).
+ */
+export declare function gapAgainstDeclared(connector: string): Promise<ISchemaComparison | null>;
+/**
+ * La comparaison BRUTE — ce que la base porte face au code, écart ou non.
+ *
+ * Séparée de {@link gapAgainstDeclared}, qui ne rend que les écarts : il existe
+ * une question à laquelle « aucun écart » est une réponse pleine, et non un
+ * silence. Celle-ci : *la base porte-t-elle DÉJÀ les tables que je m'apprête à
+ * créer ?* Une base parfaitement conforme y répond « oui », et c'est justement
+ * le cas où il ne faut pas écrire un `CREATE TABLE`.
+ *
+ * Ne modifie jamais rien, et ne jette jamais : une base muette n'est pas une
+ * conformité, c'est une absence de réponse — rendue `null` pour que personne
+ * ne conclue à sa place.
+ *
+ * @param connector - nom du connecteur à interroger.
+ * @returns la comparaison, ou `null` si rien n'était interrogeable.
+ */
+export declare function comparisonAgainstDeclared(connector: string): Promise<ISchemaComparison | null>;
+/**
+ * Ce qui diverge, NOMMÉ — ou `null` quand il n'y a rien à dire.
+ *
+ * Producteur UNIQUE de la troisième source : le verdict, la phrase française,
+ * la charge utile `--json` et la sonde de disponibilité lisent tous ce même
+ * retour. Rendre un booléen ici et recalculer le détail ailleurs ferait deux
+ * lectures de la base pour une seule question, et deux réponses qui finiraient
+ * par se contredire.
+ *
+ * Répond `null` sans rien interroger dans tous les cas où la réponse ne
+ * changerait rien : plan déjà porteur d'un verdict, connecteur absent du
+ * registre, connecteur non connecté, ORM d'une autre nature (mongoose n'a pas
+ * de schéma déclaré à comparer). Répond `null` aussi quand la comparaison a eu
+ * lieu et n'a rien trouvé — l'absence d'écart ne garde pas d'objet vide en
+ * mémoire, et l'appelant n'a qu'un test à écrire.
+ *
+ * **Ne modifie jamais rien** — le rattrapage additif est le travail du mode de
+ * schéma dérivé, au démarrage, et de lui seul.
+ *
+ * @param plan - plan calculé par l'applicateur, en lecture seule.
+ * @returns les écarts nommés, ou `null` s'il n'y en a pas à publier.
+ */
+export declare function describeDivergence(plan: IMigrationPlan): Promise<ISchemaComparison | null>;

package/dist/types/nodefony/src/migrator/drivers/index.d.ts

@@ -0,0 +1,26 @@
+import type { SqlDialect } from "../../../config/config.js";
+import type { IMigrationDriver } from "../types.js";
+export { SqliteMigrationDriver } from "./sqliteDriver.js";
+export { PostgresMigrationDriver, PG_LOCK_KEY } from "./postgresDriver.js";
+export { MysqlMigrationDriver, MYSQL_LOCK_NAME_SQL, MYSQL_LOCK_PREFIX, } from "./mysqlDriver.js";
+/** Cible de connexion de l'applicateur. */
+export interface IMigrationTarget {
+    /** Dialecte du connecteur. */
+    dialect: SqlDialect;
+    /** Fichier SQLite (dialecte `sqlite`). */
+    filename?: string;
+    /** URL de connexion DIRECTE (dialectes `postgres` et `mysql`). */
+    url?: string;
+}
+/**
+ * Ouvre le pilote à connexion unique du dialecte demandé.
+ *
+ * L'URL doit être une connexion **directe** au serveur : un répartiteur de
+ * connexions en mode transaction casse les verrous consultatifs de session, et
+ * le verrou de l'applicateur en est un.
+ *
+ * @param target - dialecte et coordonnées de la base.
+ * @returns le pilote, déjà connecté.
+ * @throws Error si les coordonnées manquent pour ce dialecte.
+ */
+export declare function openMigrationDriver(target: IMigrationTarget): Promise<IMigrationDriver>;

package/dist/types/nodefony/src/migrator/drivers/mysqlDriver.d.ts

@@ -0,0 +1,83 @@
+import type { IMigrationDriver } from "../types.js";
+/**
+ * Préfixe de l'identité du verrou MySQL — **contrat inter-versions**.
+ *
+ * Au même titre que le nom de la table d'historique : deux versions du
+ * framework qui ne s'excluent plus, c'est pendant un déploiement que ça se
+ * paie.
+ */
+export declare const MYSQL_LOCK_PREFIX = "nodefony:migrations:";
+/**
+ * Expression SQL de l'identité du verrou — évaluée par le SERVEUR.
+ *
+ * **Pourquoi qualifier par `DATABASE()`** : `GET_LOCK` est global au SERVEUR,
+ * pas à la base. Sans cette qualification, deux applications sans aucun rapport
+ * hébergées sur la même instance se sérialiseraient — en silence, ce qui est le
+ * pire des symptômes.
+ *
+ * **Pourquoi un repli haché** : MySQL borne le nom d'un verrou à 64 caractères
+ * (MariaDB est plus permissif, mais c'est la contrainte la plus stricte qui
+ * fait règle). Le préfixe en consomme 20 ; au-delà de 44 caractères de nom de
+ * base, l'appel échouerait — et l'échec d'un verrou est un blocage total, avec
+ * un message que rien ne rattache au nom de la base. Le repli reste
+ * DÉTERMINISTE (fonction du seul nom de base), donc deux versions du framework
+ * calculent toujours la même identité : le contrat tient.
+ */
+export declare const MYSQL_LOCK_NAME_SQL: string;
+/**
+ * Pilote MySQL / MariaDB de l'applicateur — **une seule connexion**.
+ *
+ * `GET_LOCK` est un verrou de SESSION : un pool le rendrait inopérant. Il
+ * s'auto-libère à la mort de la connexion — aucun verrou zombie.
+ *
+ * 🔴 **Le DDL n'est PAS transactionnel ici** : un `CREATE TABLE` valide
+ * implicitement la transaction en cours. Un échec à mi-course laisse donc la
+ * base dans un état partiel, avec un marqueur d'échec persistant — et c'est
+ * exactement pourquoi il ne doit JAMAIS y avoir de reprise aveugle : c'est la
+ * réparation, après inspection humaine, qui tranche.
+ */
+export declare class MysqlMigrationDriver implements IMigrationDriver {
+    #private;
+    readonly dialect: "mysql";
+    readonly transactionalDdl = false;
+    /**
+     * @param url - URL de connexion DIRECTE au serveur.
+     */
+    constructor(url: string);
+    /**
+     * Ouvre la connexion dédiée.
+     *
+     * @throws Error si le pilote `mysql2` n'est pas installé.
+     */
+    connect(): Promise<void>;
+    /** Connexion ouverte, ou une erreur qui dit quoi faire. */
+    /** Motif de la perte de connexion, si elle a été constatée. */
+    get lostReason(): string | null;
+    /** @inheritdoc */
+    exec(sql: string): Promise<void>;
+    /** @inheritdoc */
+    query<T extends Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    /** @inheritdoc */
+    sameColumnName(declared: string, actual: string): boolean;
+    /** @inheritdoc */
+    tableExists(table: string): Promise<boolean>;
+    /** @inheritdoc */
+    columnsOf(table: string): Promise<string[]>;
+    /** @inheritdoc */
+    begin(): Promise<void>;
+    /** @inheritdoc */
+    commit(): Promise<void>;
+    /** @inheritdoc */
+    rollback(): Promise<void>;
+    /**
+     * Prend le verrou nommé, avec le délai natif de `GET_LOCK`.
+     *
+     * @param timeoutMs - délai maximal d'attente.
+     * @throws Error si le verrou n'est pas obtenu dans le délai.
+     */
+    lock(timeoutMs: number): Promise<void>;
+    /** @inheritdoc */
+    unlock(): Promise<void>;
+    /** @inheritdoc */
+    close(): Promise<void>;
+}