@nodefony/drizzle 10.0.0-alpha.1

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

@@ -0,0 +1,81 @@
+import type { IMigrationDriver } from "../types.js";
+import { toDollarParams } from "../catalog.js";
+export { toDollarParams };
+/**
+ * Clé du verrou consultatif PostgreSQL — **figée à vie**.
+ *
+ * Elle est dérivée par une RÈGLE, pas choisie : les huit premiers octets de
+ * `sha256("nodefony:migrations")`, lus en entier signé big-endian. Une identité
+ * « gravée » dont la valeur serait tirée au hasard d'un commit ne serait pas
+ * gravée du tout — on ne pourrait plus la recalculer pour la vérifier.
+ *
+ * La changer ferait que deux versions du framework ne s'excluent plus
+ * mutuellement : exactement pendant un déploiement, le seul moment qui compte.
+ */
+export declare const PG_LOCK_KEY: bigint;
+/**
+ * Pilote PostgreSQL de l'applicateur — **une seule connexion**, pas un pool.
+ *
+ * `pg_advisory_lock` est un verrou de SESSION : avec un pool, il serait pris
+ * sur une connexion, le DDL exécuté sur une autre et la libération faite sur
+ * une troisième — le verrou ne protégerait rien. D'où une connexion tenue du
+ * verrou à sa libération.
+ *
+ * Le verrou s'auto-libère à la mort de la connexion : un process tué en plein
+ * vol ne laisse **aucun verrou zombie** à lever à la main. C'est l'argument qui
+ * a fait écarter une table de verrou.
+ */
+export declare class PostgresMigrationDriver implements IMigrationDriver {
+    #private;
+    readonly dialect: "postgres";
+    readonly transactionalDdl = true;
+    /**
+     * @param url - URL de connexion DIRECTE au serveur.
+     */
+    constructor(url: string);
+    /**
+     * Ouvre la connexion dédiée.
+     *
+     * @throws Error si le pilote `pg` n'est pas installé.
+     */
+    connect(): Promise<void>;
+    /** 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 consultatif, en attente BORNÉE.
+     *
+     * `pg_advisory_lock` attend sans limite : un pod bloqué derrière un job mort
+     * attendrait pour toujours, sans rien dire. On sonde donc avec
+     * `pg_try_advisory_lock` jusqu'au délai imparti, ce qui rend l'attente
+     * observable et l'échec explicite.
+     *
+     * `lock_timeout` est posé pour son VRAI rôle, distinct : borner l'attente des
+     * verrous de TABLE que prennent les `ALTER` — sans lui, un `ALTER` coincé
+     * derrière une transaction longue bloque toute la table en file d'attente.
+     *
+     * @param timeoutMs - délai maximal d'attente du verrou.
+     * @returns une promesse résolue une fois le verrou tenu.
+     * @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>;
+}

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

@@ -0,0 +1,53 @@
+import { type IMigrationDriver } from "../types.js";
+/**
+ * Pilote SQLite de l'applicateur — connexion `better-sqlite3` dédiée.
+ *
+ * **Pas de verrou explicite** : SQLite est à écrivain unique par nature. Ce
+ * n'est pas un manque à combler, c'est la description exacte de la situation —
+ * la sérialisation est faite par le moteur, et une table de verrou maison ne
+ * ferait qu'ajouter une pièce à déverrouiller à la main le jour où un process
+ * meurt.
+ */
+export declare class SqliteMigrationDriver implements IMigrationDriver {
+    #private;
+    readonly dialect: "sqlite";
+    readonly transactionalDdl = true;
+    /**
+     * @param filename - fichier de la base, ou `:memory:`.
+     */
+    constructor(filename: string);
+    /**
+     * Ouvre la base, en chargeant le pilote à la demande.
+     *
+     * Même patron que `PostgresMigrationDriver.connect()` : `openMigrationDriver`
+     * enchaîne `new` puis `await connect()` pour les trois dialectes, et aucune
+     * application n'embarque un pilote qu'elle n'ouvre pas.
+     *
+     * @throws Error si le pilote `better-sqlite3` n'est pas installé.
+     */
+    connect(): Promise<void>;
+    /** @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>;
+    /** @inheritdoc */
+    lock(): Promise<void>;
+    /** @inheritdoc */
+    unlock(): Promise<void>;
+    /** @inheritdoc */
+    close(): Promise<void>;
+    /** Table d'historique servie par ce pilote — pour les diagnostics. */
+    get historyTable(): string;
+}

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

@@ -0,0 +1,424 @@
+import type { DivergenceMode, SqlDialect } from "../../config/config.js";
+import type { IMigrationAction, IMigrationPlan, IMigrationVerdict } from "./types.js";
+import type { ISchemaComparison } from "./schemaDiff.js";
+import type { IDestructiveFinding } from "./destructive.js";
+import type { IDiscoveryFacts } from "./refusals.js";
+/**
+ * Le RENDU des migrations : un seul producteur, quatre destinataires.
+ *
+ * La ligne de commande, la sortie `--json`, le plan d'administration et
+ * l'assistance affichée dans un corps d'erreur disent tous la même chose. Écrire
+ * la phrase pour l'humain d'un côté et l'objet pour la machine de l'autre
+ * ferait deux implémentations d'une même règle — et elles divergeraient, comme
+ * toutes les copies.
+ *
+ * ## Ce que ce fichier garantit, et qui n'est pas cosmétique
+ *
+ * **Aucune sortie ne laisse l'utilisateur sans geste suivant.** Chaque situation
+ * — succès, attente, refus, panne — produit trois choses :
+ *
+ * 1. **le FAIT**, en français, sans terme d'art (« le fichier `0002_x.sql` a
+ *    changé après avoir été appliqué ») ;
+ * 2. **ce que ça veut dire**, c'est-à-dire la cause la plus probable ;
+ * 3. **la commande exacte à copier**, jamais une allusion à une option qu'il
+ *    faudrait deviner.
+ *
+ * Un agent lit `nextActions[0].command` et sait quoi faire sans comprendre le
+ * français ; un humain lit les mêmes mots sous une forme lisible. C'est la même
+ * donnée.
+ */
+/**
+ * Version de la charge utile `--json` **et** du plan d'administration.
+ *
+ * Contrat public : ajouter un champ est une évolution mineure, en retirer ou en
+ * renommer un est interdit sur toute la série majeure. Un `jq` écrit par un
+ * utilisateur ne doit jamais casser sur une mise à jour de correctif.
+ */
+export declare const MIGRATION_FORMAT_VERSION = 1;
+/**
+ * Verdicts possibles — **énumération GELÉE** avec {@link MIGRATION_FORMAT_VERSION}.
+ *
+ * Y ajouter une valeur après publication casserait tout consommateur qui les
+ * traite exhaustivement (`case` sans `default`, `match` d'un agent). Une
+ * situation nouvelle se range donc dans la famille existante qui lui convient,
+ * et se détaille dans les champs — jamais dans un huitième mot.
+ */
+export type MigrationVerdictName = 
+/** Rien à faire : l'historique est complet et les fichiers concordent. */
+"up-to-date"
+/** Des migrations restent à appliquer. */
+ | "pending"
+/**
+ * Les fichiers ne correspondent plus à ce que l'historique enregistre :
+ * empreinte changée après application, ou fichier disparu. Le cas du fichier
+ * disparu se range ici — l'énumération est gelée, et c'est bien la même
+ * famille : ce qui est écrit dans l'historique ne se retrouve plus sur le
+ * disque. Le détail reste lisible dans `sources[].drifted` et `[].missing`.
+ */
+ | "drift"
+/** Une migration a échoué, ou n'a jamais fini : réparation requise. */
+ | "failed"
+/** La base a déjà les tables mais aucun historique : adoption requise. */
+ | "adopt"
+/**
+ * L'historique est complet, rien n'est en attente — et la base ne correspond
+ * pourtant pas au schéma déclaré dans le code.
+ */
+ | "divergent";
+/** Ce qu'une source de migrations donne à voir. */
+export interface IMigrationSourceReport {
+    /** Nom logique de la source (`framework`, `app`, un module tiers). */
+    name: string;
+    /** Migrations appliquées avec succès. */
+    applied: number;
+    /** Migrations restant à appliquer. */
+    pending: number;
+    /** Marqueurs d'échec à lever. */
+    failed: number;
+    /** Identités en attente, dans l'ordre d'application. */
+    pendingTags: string[];
+    /** Fichiers modifiés après avoir été appliqués. */
+    drifted: {
+        tag: string;
+        expected: string;
+        actual: string;
+    }[];
+    /** Identités enregistrées dont le fichier a disparu. */
+    missing: string[];
+    /**
+     * UNE LIGNE PAR MIGRATION, dans l'ordre d'application — ce que les compteurs
+     * ci-dessus agrègent.
+     *
+     * Ajoutée pour l'écran d'administration, qui doit montrer QUAND chaque
+     * migration est passée, en combien de temps et sous quel déploiement.
+     * L'applicateur le savait déjà : le plan porte `startedAt`, `executionMs`,
+     * `appliedBy` et `runId` depuis toujours, et le rapport les jetait à un pas
+     * de la sortie — l'exploitant devait alors ouvrir un client SQL sur
+     * l'historique pour une réponse que le produit avait calculée.
+     *
+     * Ajout ADDITIF : les lecteurs du format 1 qui ne la connaissent pas
+     * l'ignorent, aucun champ existant ne change de sens.
+     */
+    entries: IMigrationEntryReport[];
+}
+/** Une migration, telle que l'historique et les fichiers la décrivent. */
+export interface IMigrationEntryReport {
+    /** Identité immuable une fois publiée. */
+    tag: string;
+    /** Où en est cette migration pour CE connecteur. */
+    status: "applied" | "pending" | "failed" | "drifted" | "missing";
+    /** Début de l'application, en millisecondes — absent si jamais appliquée. */
+    appliedAt?: number;
+    /** Durée de l'application, en millisecondes. */
+    durationMs?: number;
+    /** Ce qui l'a appliquée, tel que l'historique l'a retenu. */
+    appliedBy?: string;
+    /** Déploiement qui l'a portée — groupe les migrations d'un même passage. */
+    runId?: string;
+    /** Motif de l'échec, quand elle a échoué. */
+    error?: string;
+}
+/**
+ * La charge utile figée — cœur NEUTRE au premier niveau, spécifique du pilote
+ * sous `driver`.
+ *
+ * Ce découpage est la seule chose qui permettra à un second ORM de remplir la
+ * même structure sans casser un `jq` d'utilisateur. Si `dialect` vivait au
+ * premier niveau, chaque script le graverait — et un ORM sans dialecte n'aurait
+ * plus de place dans la structure.
+ */
+export interface IMigrationReport {
+    formatVersion: typeof MIGRATION_FORMAT_VERSION;
+    /** Connecteur observé. */
+    connector: string;
+    /** Situation d'ensemble — énumération gelée. */
+    verdict: MigrationVerdictName;
+    /** Code de sortie que cette situation produit sur la ligne de commande. */
+    exitCode: 0 | 1 | 2;
+    /** Le fait constaté, en une phrase française. */
+    summary: string;
+    /** Ce qu'il faut faire, du plus direct au plus assumé. Peut être vide. */
+    nextActions: IMigrationAction[];
+    /** Une source par entrée, dans l'ordre d'application. */
+    sources: IMigrationSourceReport[];
+    /**
+     * CE QUI diverge, nommé — présent au seul verdict `divergent`, absent
+     * partout ailleurs.
+     *
+     * Le verdict dit qu'il y a un écart ; cette clé dit LEQUEL. Sans elle,
+     * l'exploitant ouvre un client SQL et compare table par table, sur une base
+     * de production, au pire moment — alors que le produit connaissait déjà la
+     * réponse. Elle vit au premier niveau, dans le cœur NEUTRE : un second ORM
+     * remplira la même structure, et un `jq` d'utilisateur ne doit pas avoir
+     * gravé un chemin qui passe par le nom d'un pilote.
+     *
+     * Son ABSENCE est un fait, pas un oubli : sur une base conforme, il n'y a
+     * rien à nommer.
+     */
+    divergence?: ISchemaComparison;
+    /**
+     * Ce que le passage a DÉTRUIT, nommé — présent au seul run réel qui a
+     * appliqué une migration destructive, absent partout ailleurs.
+     *
+     * L'essai à blanc publiait déjà cette liste ; le run réel ne la publiait pas,
+     * et l'avertissement n'existait qu'en mode humain. Un agent — le mode que le
+     * produit lui prescrit — appliquait donc une perte de données sans qu'un seul
+     * octet de ce qu'il relit ne la mentionne. Son absence est un fait : rien
+     * n'a été détruit.
+     */
+    destructive?: IDestructiveFinding[];
+    /** Tout ce qui est propre au pilote SQL vit ici, et nulle part ailleurs. */
+    driver: {
+        kind: "sql";
+        dialect: SqlDialect;
+        ddl: string;
+        historyTable: string;
+        /** La base visée, sans identifiant ni mot de passe. */
+        target?: string;
+        /** `true` quand la cible vient de `NF_MIGRATE_DATABASE_URL`. */
+        fromMigrateUrl?: boolean;
+    };
+}
+/** Grille des codes de sortie — **figée, jamais réaffectée**. */
+export declare const EXIT: {
+    /** À jour, ou appliqué avec succès. */
+    readonly ok: 0;
+    /** Une action humaine est requise sur la base ou sur les fichiers. */
+    readonly actionRequired: 1;
+    /** La commande n'a pas pu faire son travail (verrou, connexion, usage). */
+    readonly error: 2;
+};
+/** Fabrique une action affichable et exécutable. */
+export declare function action(command: string): IMigrationAction;
+/**
+ * Situation d'ensemble d'un plan, dans l'ordre de gravité.
+ *
+ * L'ordre n'est pas esthétique : il dit quel geste vient EN PREMIER. Une
+ * migration en échec doit être réparée avant qu'on parle de ce qui reste à
+ * appliquer, sinon l'utilisateur lance une commande qui va refuser.
+ *
+ * @param plan - plan calculé en lecture seule.
+ * @param divergent - la base a-t-elle divergé du schéma déclaré ?
+ * @returns le verdict, énumération gelée.
+ */
+export declare function verdictOf(plan: IMigrationPlan, divergent?: boolean): MigrationVerdictName;
+/**
+ * L'historique porte-t-il des migrations que CE code ne connaît pas, et rien
+ * d'autre ne cloche-t-il ?
+ *
+ * C'est l'état NORMAL de deux moments qu'on ne peut pas éviter : une mise à jour
+ * progressive, où les anciens exemplaires servent encore pendant que le travail
+ * de migration a déjà appliqué la suite ; et un retour arrière, où le code
+ * revient en arrière et la base reste en avance. Dans les deux cas, l'exemplaire
+ * n'a rien à appliquer, et tout ce qu'il connaît concorde.
+ *
+ * **Le verdict, lui, reste `drift` — et c'est juste** : ce qui est écrit dans
+ * l'historique ne se retrouve pas sur le disque. L'énumération des verdicts est
+ * GELÉE avec {@link MIGRATION_FORMAT_VERSION}, et un huitième mot casserait tout
+ * consommateur qui les traite exhaustivement. Ce qui était faux n'était pas le
+ * constat, c'était ce que la sonde de disponibilité en DÉDUISAIT : retenir le
+ * trafic sortait du service tous les anciens exemplaires dès la fin du travail
+ * de migration, avant que le premier nouveau soit prêt — une coupure totale sur
+ * un déploiement nominal, et l'impossibilité de revenir en arrière.
+ *
+ * Ce que cette fonction ne couvre PAS, et qui doit continuer de retenir : une
+ * empreinte qui a changé (`drifted`), une migration en attente ou en échec, une
+ * adoption requise. Une base en avance n'a rien de commun avec un fichier
+ * réécrit après coup.
+ *
+ * @param plan - plan calculé par le migrateur.
+ * @returns vrai si le seul écart est un historique en avance sur ce code.
+ */
+export declare function isAheadOnly(plan: IMigrationPlan): boolean;
+/**
+ * Une divergence RETIENT-elle un déploiement ?
+ *
+ * ## Pourquoi ce n'est pas un simple « le mode vaut-il `fail` »
+ *
+ * Le défaut est l'observation, et pour une bonne raison : une application qui
+ * écrit des migrations libres — vues, déclencheurs, colonnes ajoutées à la main
+ * — a une base légitimement différente du schéma déclaré, en permanence. Faire
+ * tomber ses déploiements là-dessus rendrait le constat inutilisable, et la
+ * première chose qu'on ferait serait de l'éteindre.
+ *
+ * **Mais ce raisonnement ne couvre pas une TABLE d'entité absente.** Aucune
+ * migration libre ne fait disparaître une table que le code déclare comme
+ * entité ; quand elle manque, c'est que le schéma applicatif n'a jamais été
+ * posé — la migration n'a pas été générée, pas commitée, ou pas appliquée. Ce
+ * n'est pas une base « différente », c'est une base sur laquelle l'application
+ * ne peut RIEN faire : chacune de ses routes rendra 500, et le pod se serait
+ * déclaré prêt.
+ *
+ * C'est exactement le constat qui a ouvert ce chantier : les onze tables du
+ * framework posées, zéro table applicative, et toutes les routes d'entités en
+ * erreur — sans qu'aucun verdict ne le dise assez fort pour arrêter quoi que
+ * ce soit.
+ *
+ * La graduation tient donc en trois lignes, et chaque lecteur y trouve son
+ * seuil : `off` ne retient jamais, `fail` retient tout écart, `report` — le
+ * défaut — retient ce qu'aucune main légitime ne produit.
+ *
+ * @param divergence - les écarts nommés, ou `null` quand il n'y en a pas.
+ * @param mode - `migrations.divergence`, tel que la configuration le déclare.
+ * @returns `true` si la situation doit retenir la mise en service.
+ */
+export declare function divergenceIsBlocking(divergence: ISchemaComparison | null | undefined, mode?: DivergenceMode): boolean;
+/**
+ * Le code de sortie d'un verdict.
+ *
+ * **`divergent` ne fait pas tomber un déploiement** quand la configuration le
+ * laisse en observation : superviser n'est pas bloquer. C'est ce qui rend le
+ * constat utilisable — une application qui écrit des migrations libres a une
+ * base légitimement différente du schéma déclaré, en permanence.
+ *
+ * @param verdict - situation d'ensemble.
+ * @param divergenceBlocks - `true` quand la divergence doit retenir la mise en
+ *   service, tel que {@link divergenceIsBlocking} en décide.
+ * @returns `0`, `1` ou `2`.
+ */
+export declare function exitCodeOf(verdict: MigrationVerdictName, divergenceBlocks?: boolean): 0 | 1 | 2;
+/** Ce que le rendu doit savoir en plus du plan lui-même. */
+export interface IReportContext {
+    /** Mode de schéma effectif du connecteur. */
+    ddl: string;
+    /**
+     * Les écarts NOMMÉS entre la base et le schéma déclaré, tels que
+     * `describeDivergence` les rend — `null` ou absent quand il n'y en a pas.
+     *
+     * C'est le détail qui décide du verdict, pas un booléen posé à côté : deux
+     * champs pour un même fait finissent par se contredire.
+     */
+    divergence?: ISchemaComparison | null;
+    /**
+     * `migrations.divergence`, tel que la configuration le déclare.
+     *
+     * Le MODE, jamais un booléen calculé par l'appelant : le seuil qui décide
+     * qu'un écart retient un déploiement est une règle du produit
+     * ({@link divergenceIsBlocking}), pas une décision que chaque appelant
+     * reprendrait à son compte — deux copies finiraient par ne plus retenir les
+     * mêmes situations.
+     */
+    divergenceMode?: DivergenceMode;
+    /**
+     * `orm:reset` est-elle acceptée dans cet environnement ?
+     *
+     * Elle efface : la règle est une liste blanche que porte `resetAllowed`, et
+     * elle est lue ici pour ne JAMAIS proposer un geste qui va refuser. Une
+     * action rendue puis rejetée détruit la confiance dans toutes les autres.
+     * Défaut prudent : `false` — on ne suppose pas le droit d'effacer.
+     */
+    canReset?: boolean;
+    /**
+     * La base RÉELLEMENT visée, telle que {@link describeTargetSafely} la
+     * désigne — sans identifiant ni mot de passe.
+     *
+     * Absente quand l'appelant ne la connaît pas ; jamais devinée ici.
+     */
+    target?: string;
+    /**
+     * La cible vient-elle de `NF_MIGRATE_DATABASE_URL` plutôt que de la
+     * configuration du connecteur ?
+     *
+     * C'est le fait qui manquait, et son absence coûtait cher : une variable
+     * oubliée dans un terminal détourne SILENCIEUSEMENT chaque commande de
+     * migration vers une autre base, qui rend « appliqué » et le code du succès
+     * pendant que la vraie ne reçoit rien. Le seul symptôme arrivait plus tard,
+     * au démarrage d'une application sur un schéma qui n'avait pas bougé.
+     *
+     * Publié à côté de la cible, et pas à sa place : savoir QUELLE base ne dit
+     * pas POURQUOI c'est celle-là.
+     */
+    fromMigrateUrl?: boolean;
+}
+/**
+ * Compose la charge utile complète d'un état de migration.
+ *
+ * @param plan - plan calculé en lecture seule.
+ * @param ctx - mode de schéma et conduite face à la divergence.
+ * @returns la charge utile, identique pour la ligne de commande, `--json`, le
+ *   plan d'administration et la sonde.
+ */
+export declare function buildReport(plan: IMigrationPlan, ctx: IReportContext): IMigrationReport;
+/**
+ * Ce que le verdict veut dire — la CAUSE, entre le fait et le geste.
+ *
+ * C'est le bloc qu'on omet d'habitude, et c'est celui qui évite l'appel au
+ * collègue : l'utilisateur sait ce qui s'est passé, donc il sait si le geste
+ * proposé lui convient.
+ *
+ * @param verdict - situation d'ensemble.
+ * @returns une ou deux phrases, ou une chaîne vide si le fait se suffit.
+ */
+export declare function meaningOf(verdict: MigrationVerdictName): string;
+/** Codes ANSI, neutralisés hors terminal (un `| jq` ne doit rien recevoir). */
+export interface IStyle {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    red: (s: string) => string;
+}
+/**
+ * Construit le styliste : couleurs en terminal, texte nu ailleurs.
+ *
+ * @param tty - la sortie est-elle un terminal ?
+ * @returns les fonctions de mise en forme.
+ */
+export declare function styleFor(tty: boolean): IStyle;
+/**
+ * Rendu humain d'un état de migration — l'écran que voit celui qui tape
+ * `orm:migrate:status`.
+ *
+ * @param report - charge utile complète.
+ * @param style - mise en forme (couleurs ou texte nu).
+ * @returns le texte prêt à écrire sur la sortie standard.
+ */
+export declare function renderStatus(report: IMigrationReport, style: IStyle): string;
+/**
+ * Rendu humain de ce que la DÉCOUVERTE des entités a vu.
+ *
+ * Bloc court, posé sous les refus dont la cause peut être un schéma déclaré
+ * amputé : un fichier illisible, une table écrite pour un autre moteur, un
+ * dossier d'entités qui ne rend rien. L'outil de diff ne distingue pas une
+ * table absente d'une table SUPPRIMÉE — sans ces trois nombres, la correction
+ * naturelle porte sur la base, qui n'y est pour rien.
+ *
+ * @param facts - ce que la découverte a relevé.
+ * @param style - mise en forme.
+ * @returns le bloc, prêt à concaténer ; vide si rien n'appelle l'attention.
+ */
+export declare function describeDiscovery(facts: IDiscoveryFacts, style: IStyle): string;
+/**
+ * Rendu humain d'un REFUS de l'applicateur.
+ *
+ * Un refus est un contrat, pas un message : il énonce le fait, ce qu'il
+ * signifie, et donne la commande exacte à copier. L'utilisateur ne doit jamais
+ * avoir eu connaissance d'une option à l'avance.
+ *
+ * @param verdict - verdict structuré porté par le refus.
+ * @param message - phrase française déjà composée par l'applicateur.
+ * @param style - mise en forme.
+ * @param ddl - mode de schéma effectif, quand il change la cause (cf {@link refusalInMode}).
+ * @returns le texte prêt à écrire sur la sortie d'erreur.
+ */
+export declare function renderRefusal(verdict: IMigrationVerdict, message: string, style: IStyle, ddl?: string): string;
+/**
+ * Ce qu'un refus veut dire QUAND ON CONNAÎT LE MODE DE SCHÉMA.
+ *
+ * Le même fait mécanique n'a pas la même cause selon le mode, et le geste
+ * change avec la cause. Constaté en exécutant la commande pour de vrai : sur une
+ * base parfaitement NEUVE, en développement, `orm:migrate` refuse en disant que
+ * la base « porte déjà les tables ». C'est exact — et c'est le DÉMARRAGE
+ * lui-même qui vient de les créer, quelques millisecondes plus tôt, parce que le
+ * mode `auto` dérive le schéma du code. Sans cette précision, l'utilisateur
+ * cherche une base ancienne qui n'existe pas.
+ *
+ * @param code - code du refus.
+ * @param ddl - mode de schéma effectif du connecteur.
+ * @param connector - connecteur concerné, pour composer les gestes.
+ * @returns l'explication et les gestes, ou `null` si le refus se suffit.
+ */
+export declare function refusalInMode(code: IMigrationVerdict["code"], ddl: string, connector: string): {
+    meaning: string;
+    actions: IMigrationAction[];
+} | null;

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

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