dsh-plugin-dbgraph-catalog 0.0.0-stage → 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Catalog dialect plugin for `ctx.dbgraph`: registers one {@link DatabaseDialect} per database
+ * engine so the service can reach a server, snapshot its structure, and execute the single read a
+ * `find` call produces.
+ *
+ * **A table of dialects, not a switch.** {@link DIALECT_FACTORIES} is the whole extensibility
+ * story: adding PostgreSQL, MongoDB or Redis later is one entry that loads its driver and returns a
+ * `ManagedDialect`; `apply` needs no change, and the seam's "one dialect per engine" rule is
+ * enforced by `ctx.dbgraph.registerDialect` itself.
+ *
+ * **An unavailable driver disables one dialect, never the package.** SQLite lives in Node's builtins
+ * and MySQL's driver is an optional dependency, so either can be absent on a given installation. A
+ * failed load logs one line naming the engine and continues; a catalog package that refused to load
+ * because an unrelated driver was missing would take the working dialect down with it.
+ *
+ * **Disposal is ordered.** The plugin's connection caches are closed after the dialect
+ * registrations are withdrawn (effects dispose last-in-first-out), so no call can be routed to a
+ * dialect whose handles are already shut.
+ * @module dsh-plugin-dbgraph-catalog
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Engine } from 'dsh-plugin-dbgraph-service';
+import type { ManagedDialect } from './support.ts';
+export { createMysqlDialect, loadMysqlDriver, MYSQL_DRIVER_PACKAGE, mysqlIdentifier } from './mysql.ts';
+export type { MysqlModule } from './mysql.ts';
+export { createSqliteDialect, isStringishSqliteType, sqliteIdentifier } from './sqlite.ts';
+export type { SqliteModule } from './sqlite.ts';
+export { HandleCache } from './pool.ts';
+export { DBGRAPH_QUERY_FAILED_CODE, DBGRAPH_READ_ONLY_CODE, REDACTED_VALUE, assertReadOnlyStatement, clampRowLimit, describeWriteChannel, firstStatementKeyword, isReadStatement, messageOf, normalizeRows, renderBinary, throwIfAborted, toJsonSafe, } from './support.ts';
+export type { ManagedDialect } from './support.ts';
+/** Cordis plugin name for loader diagnostics. */
+export declare const name = "dbgraph-catalog";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** One engine's loader: resolves to a dialect, or rejects when its driver is unavailable. */
+export interface DialectFactory {
+    /** The engine the loaded dialect serves. */
+    readonly engine: Engine;
+    /** Load the driver and build the dialect. */
+    readonly load: () => Promise<ManagedDialect>;
+}
+/** Why one engine's dialect could not be loaded. */
+export interface DialectLoadFailure {
+    /** The engine whose driver was unavailable or whose dialect failed to construct. */
+    readonly engine: Engine;
+    /** Why it could not load, as the loader reported it. */
+    readonly error: string;
+}
+/** The outcome of trying every configured dialect. */
+export interface DialectLoadResult {
+    /** Dialects that loaded and should be registered. */
+    readonly dialects: readonly ManagedDialect[];
+    /** Engines that were skipped, one entry each. */
+    readonly failures: readonly DialectLoadFailure[];
+}
+/**
+ * Every dialect this package can provide, in registration order.
+ *
+ * The loaders are async because MySQL's driver is imported on demand; SQLite's builtin is imported
+ * the same way so an older Node simply reports itself unavailable instead of crashing the module.
+ */
+export declare const DIALECT_FACTORIES: readonly DialectFactory[];
+/**
+ * Load as many dialects as the installation supports.
+ *
+ * A failed loader is collected rather than thrown: one engine's missing optional driver must never
+ * prevent the other engines from registering. The split from {@link apply} exists so the
+ * availability decision can be tested (and reused by a deployment that mounts dialects itself)
+ * without constructing a Cordis context.
+ * @param factories - factories to try; defaults to {@link DIALECT_FACTORIES}.
+ * @returns the dialects that loaded, plus one failure per skipped engine.
+ */
+export declare function loadDialects(factories?: readonly DialectFactory[]): Promise<DialectLoadResult>;
+/**
+ * Register every dialect whose driver is available.
+ * @param ctx - the plugin context (must inject `dbgraph`).
+ * @returns a promise that settles after registration (and after every failed load was reported).
+ */
+export declare function apply(ctx: Context): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,111 @@
+/**
+ * Catalog dialect plugin for `ctx.dbgraph`: registers one {@link DatabaseDialect} per database
+ * engine so the service can reach a server, snapshot its structure, and execute the single read a
+ * `find` call produces.
+ *
+ * **A table of dialects, not a switch.** {@link DIALECT_FACTORIES} is the whole extensibility
+ * story: adding PostgreSQL, MongoDB or Redis later is one entry that loads its driver and returns a
+ * `ManagedDialect`; `apply` needs no change, and the seam's "one dialect per engine" rule is
+ * enforced by `ctx.dbgraph.registerDialect` itself.
+ *
+ * **An unavailable driver disables one dialect, never the package.** SQLite lives in Node's builtins
+ * and MySQL's driver is an optional dependency, so either can be absent on a given installation. A
+ * failed load logs one line naming the engine and continues; a catalog package that refused to load
+ * because an unrelated driver was missing would take the working dialect down with it.
+ *
+ * **Disposal is ordered.** The plugin's connection caches are closed after the dialect
+ * registrations are withdrawn (effects dispose last-in-first-out), so no call can be routed to a
+ * dialect whose handles are already shut.
+ * @module dsh-plugin-dbgraph-catalog
+ */
+import { createMysqlDialect, loadMysqlDriver } from "./mysql.js";
+import { createSqliteDialect } from "./sqlite.js";
+import { messageOf } from "./support.js";
+export { createMysqlDialect, loadMysqlDriver, MYSQL_DRIVER_PACKAGE, mysqlIdentifier } from "./mysql.js";
+export { createSqliteDialect, isStringishSqliteType, sqliteIdentifier } from "./sqlite.js";
+export { HandleCache } from "./pool.js";
+export { DBGRAPH_QUERY_FAILED_CODE, DBGRAPH_READ_ONLY_CODE, REDACTED_VALUE, assertReadOnlyStatement, clampRowLimit, describeWriteChannel, firstStatementKeyword, isReadStatement, messageOf, normalizeRows, renderBinary, throwIfAborted, toJsonSafe, } from "./support.js";
+/** Cordis plugin name for loader diagnostics. */
+export const name = 'dbgraph-catalog';
+/** Services required by this plugin. */
+export const inject = ['dbgraph'];
+/**
+ * Every dialect this package can provide, in registration order.
+ *
+ * The loaders are async because MySQL's driver is imported on demand; SQLite's builtin is imported
+ * the same way so an older Node simply reports itself unavailable instead of crashing the module.
+ */
+export const DIALECT_FACTORIES = [
+    {
+        engine: 'sqlite',
+        async load() {
+            const module = await import('node:sqlite');
+            return createSqliteDialect(module);
+        },
+    },
+    {
+        engine: 'mysql',
+        async load() {
+            return createMysqlDialect(await loadMysqlDriver());
+        },
+    },
+];
+/**
+ * Load as many dialects as the installation supports.
+ *
+ * A failed loader is collected rather than thrown: one engine's missing optional driver must never
+ * prevent the other engines from registering. The split from {@link apply} exists so the
+ * availability decision can be tested (and reused by a deployment that mounts dialects itself)
+ * without constructing a Cordis context.
+ * @param factories - factories to try; defaults to {@link DIALECT_FACTORIES}.
+ * @returns the dialects that loaded, plus one failure per skipped engine.
+ */
+export async function loadDialects(factories = DIALECT_FACTORIES) {
+    const dialects = [];
+    const failures = [];
+    for (const factory of factories) {
+        try {
+            dialects.push(await factory.load());
+        }
+        catch (error) {
+            failures.push({ engine: factory.engine, error: messageOf(error) });
+        }
+    }
+    return { dialects, failures };
+}
+/**
+ * Register every dialect whose driver is available.
+ * @param ctx - the plugin context (must inject `dbgraph`).
+ * @returns a promise that settles after registration (and after every failed load was reported).
+ */
+export async function apply(ctx) {
+    const { dialects, failures } = await loadDialects();
+    for (const failure of failures) {
+        // One line per unavailable engine: enough for an operator to fix it, quiet enough that a
+        // composition with SQLite only is not noisy.
+        console.error(`[dbgraph-catalog] the ${failure.engine} dialect is disabled: ${failure.error}`);
+    }
+    if (dialects.length === 0)
+        return;
+    ctx.effect(function* () {
+        // Yielded first, disposed last: registrations are withdrawn before their handles close.
+        yield () => closeAll(dialects);
+        for (const dialect of dialects)
+            yield ctx.dbgraph.registerDialect(dialect);
+    }, 'dbgraph-catalog');
+}
+/**
+ * Close every registered dialect's handles, reporting rather than propagating a close failure.
+ * @param dialects - the dialects this plugin registered.
+ */
+async function closeAll(dialects) {
+    for (const dialect of dialects) {
+        try {
+            await dialect.close();
+        }
+        catch (error) {
+            console.error(`[dbgraph-catalog] closing the ${dialect.engine} dialect failed: ${messageOf(error)}`);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `dsh-plugin-dbgraph-catalog`.
+ * @module dsh-plugin-dbgraph-catalog/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "dbgraph-catalog-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/invariant.js

@@ -0,0 +1,24 @@
+/**
+ * Package-owned invariant companion for `dsh-plugin-dbgraph-catalog`.
+ * @module dsh-plugin-dbgraph-catalog/invariant
+ */
+const PACKAGE_NAME = 'dsh-plugin-dbgraph-catalog';
+/** Cordis companion plugin name. */
+export const name = 'dbgraph-catalog-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: this package owns no cross-plugin relation. Its dialect registrations live
+ * in `ctx.dbgraph`'s private registry and its warm connection caches are private to each dialect
+ * instance, torn down by the plugin's own effect-scoped disposal. There is nothing another package
+ * could observe and compare against.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/mysql-map.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Pure `information_schema` row mapping for the MySQL dialect.
+ *
+ * Kept out of `mysql.ts` on purpose: the network half can only be exercised against a live server,
+ * while everything that decides "what does this row mean" is a plain function over plain data. That
+ * is what lets the mapping be tested without pretending a mocked query proves anything about MySQL.
+ *
+ * Rows arrive as `unknown` fields because `mysql2` types `information_schema` results as
+ * `RowDataPacket` (an index signature), and a driver upgrade may widen a column. Every reader
+ * narrows; nothing here trusts a field's shape.
+ * @module dsh-plugin-dbgraph-catalog/mysql-map
+ */
+import type { ConnectionConfig, RawColumn, RawEdge, RawObject } from 'dsh-plugin-dbgraph-service';
+/** One `information_schema.TABLES` row, restricted to the columns the dialect selects. */
+export interface MysqlTableRow {
+    readonly TABLE_SCHEMA?: unknown;
+    readonly TABLE_NAME?: unknown;
+    readonly TABLE_TYPE?: unknown;
+    readonly TABLE_COMMENT?: unknown;
+    readonly TABLE_ROWS?: unknown;
+}
+/** One `information_schema.COLUMNS` row, restricted to the columns the dialect selects. */
+export interface MysqlColumnRow {
+    readonly TABLE_NAME?: unknown;
+    readonly COLUMN_NAME?: unknown;
+    readonly ORDINAL_POSITION?: unknown;
+    readonly COLUMN_TYPE?: unknown;
+    readonly IS_NULLABLE?: unknown;
+    readonly COLUMN_DEFAULT?: unknown;
+    readonly COLUMN_KEY?: unknown;
+    readonly COLUMN_COMMENT?: unknown;
+}
+/** One `information_schema.KEY_COLUMN_USAGE` row for a foreign key, restricted to what is needed. */
+export interface MysqlForeignKeyRow {
+    readonly TABLE_NAME?: unknown;
+    readonly CONSTRAINT_NAME?: unknown;
+    readonly COLUMN_NAME?: unknown;
+    readonly ORDINAL_POSITION?: unknown;
+    readonly REFERENCED_TABLE_NAME?: unknown;
+    readonly REFERENCED_COLUMN_NAME?: unknown;
+}
+/** One `information_schema.STATISTICS` row, restricted to what is needed. */
+export interface MysqlIndexRow {
+    readonly TABLE_NAME?: unknown;
+    readonly INDEX_NAME?: unknown;
+    readonly NON_UNIQUE?: unknown;
+    readonly SEQ_IN_INDEX?: unknown;
+    readonly COLUMN_NAME?: unknown;
+}
+/** What a `TABLES` row contributes to an object, before its columns are attached. */
+export interface MysqlTableFacts {
+    /** Whether the row describes a base table or a view. */
+    readonly kind: 'table' | 'view';
+    /** Table comment, absent for a view's synthetic `VIEW` comment and for an empty comment. */
+    readonly comment?: string;
+    /** Approximate row count from catalog statistics; absent for views and unknown counts. */
+    readonly rowEstimate?: number;
+}
+/** Index edges and single-column uniqueness, both keyed by table name. */
+export interface MysqlIndexFacts {
+    /** One edge per named index, columns in index order. */
+    readonly edges: ReadonlyMap<string, readonly RawEdge[]>;
+    /** Columns covered by a single-column unique index, per table. */
+    readonly singleUnique: ReadonlyMap<string, ReadonlySet<string>>;
+}
+/**
+ * Whether a column's declared type is string-like, and therefore worth sampling for enum values.
+ * MySQL reports the declared type (`varchar(64)`, `enum('a','b')`), so the base word before any
+ * parenthesized modifier decides.
+ * @param columnType - `COLUMN_TYPE` as the server declared it.
+ * @returns true for character, text, enum and set types.
+ */
+export declare function isStringishMysqlType(columnType: string): boolean;
+/**
+ * Whether one column is a candidate for enum sampling.
+ *
+ * Three gates, each for its own reason: a view's sampling query executes its definition (unbounded
+ * work for a catalog enrichment), a non-string column's distinct values are numbers rather than
+ * vocabulary, and a sensitive column's literals must never reach the on-disk index.
+ * @param objectKind - the object's kind (`table`, `view`, …).
+ * @param connection - the connection whose masking configuration applies.
+ * @param column - the column to screen.
+ * @returns true when sampling this column is safe and useful.
+ */
+export declare function shouldSampleMysqlColumn(objectKind: string, connection: ConnectionConfig, column: RawColumn): boolean;
+/**
+ * The join key for a comment map: a column is identified by table plus column, never by column name
+ * alone (two tables routinely share `id`).
+ * @param table - table name.
+ * @param column - column name.
+ * @returns a key that cannot collide with an ordinary name.
+ */
+export declare function mysqlColumnKey(table: string, column: string): string;
+/**
+ * Interpret one `TABLES` row.
+ *
+ * `TABLE_COMMENT` is `VIEW` for every view in MySQL — that is a marker, not a description, so it is
+ * dropped rather than shown to a model as if a human wrote it. An empty string is also no comment.
+ * @param row - one `information_schema.TABLES` row.
+ * @returns the object's kind plus whatever comment and row estimate are real.
+ */
+export declare function mysqlTableFacts(row: MysqlTableRow): MysqlTableFacts;
+/**
+ * Group `COLUMNS` rows into per-table column lists, in declared order.
+ *
+ * `isUnique` is deliberately not derived from `COLUMN_KEY`: MySQL reports `UNI` for the first
+ * column of *any* unique index, including a multi-column one, which would claim a column is unique
+ * on its own when it is not. L2 computes uniqueness from `STATISTICS` instead.
+ * @param rows - `information_schema.COLUMNS` rows.
+ * @returns columns keyed by table name.
+ */
+export declare function groupMysqlColumns(rows: readonly MysqlColumnRow[]): Map<string, RawColumn[]>;
+/**
+ * Extract column comments, keyed by {@link mysqlColumnKey}.
+ * @param rows - `information_schema.COLUMNS` rows that selected `COLUMN_COMMENT`.
+ * @returns non-empty comments only.
+ */
+export declare function mysqlColumnComments(rows: readonly MysqlColumnRow[]): Map<string, string>;
+/**
+ * Group `KEY_COLUMN_USAGE` rows into one edge per foreign-key constraint.
+ *
+ * `refObject` is the referenced table's plain name: a catalog describes exactly one schema, and
+ * `RawEdge` has no `refSchema` field, so a schema-qualified name here would not match anything the
+ * writer stores.
+ * @param rows - foreign-key rows, in any order.
+ * @returns edges keyed by the referencing table name.
+ */
+export declare function groupMysqlForeignKeys(rows: readonly MysqlForeignKeyRow[]): Map<string, RawEdge[]>;
+/**
+ * Group `STATISTICS` rows into index edges and the set of singly-unique columns.
+ *
+ * A functional index (MySQL 8) reports a `NULL` `COLUMN_NAME` and an expression instead; the seam's
+ * edge shape only has column names, so such an index is skipped rather than recorded with a wrong
+ * or empty column list.
+ * @param rows - `information_schema.STATISTICS` rows, in any order.
+ * @returns edges and single-column uniqueness, both keyed by table name.
+ */
+export declare function groupMysqlIndexes(rows: readonly MysqlIndexRow[]): MysqlIndexFacts;
+/**
+ * Merge one table's L1 object with its L2 facts, without mutating the input.
+ *
+ * Column comments are applied here rather than in `groupMysqlColumns` so L1 stays a structural
+ * snapshot and L2 is the only level that reads `COLUMN_COMMENT`.
+ * @param object - the L1 object.
+ * @param facts - what the `TABLES` row says about it, when one still exists.
+ * @param columnComments - comments keyed by {@link mysqlColumnKey}.
+ * @param uniqueColumns - columns covered by a single-column unique index.
+ * @param edges - foreign-key and index edges leaving this object.
+ * @param enumSamples - sampled literals keyed by column name.
+ * @returns a new object carrying the enrichment.
+ */
+export declare function mergeMysqlObject(object: RawObject, facts: MysqlTableFacts | undefined, columnComments: ReadonlyMap<string, string>, uniqueColumns: ReadonlySet<string> | undefined, edges: readonly RawEdge[], enumSamples: ReadonlyMap<string, readonly string[]>): RawObject;
+//# sourceMappingURL=mysql-map.d.ts.map

package/lib/mysql-map.js

@@ -0,0 +1,266 @@
+/**
+ * Pure `information_schema` row mapping for the MySQL dialect.
+ *
+ * Kept out of `mysql.ts` on purpose: the network half can only be exercised against a live server,
+ * while everything that decides "what does this row mean" is a plain function over plain data. That
+ * is what lets the mapping be tested without pretending a mocked query proves anything about MySQL.
+ *
+ * Rows arrive as `unknown` fields because `mysql2` types `information_schema` results as
+ * `RowDataPacket` (an index signature), and a driver upgrade may widen a column. Every reader
+ * narrows; nothing here trusts a field's shape.
+ * @module dsh-plugin-dbgraph-catalog/mysql-map
+ */
+import { asFiniteNumber, asString, isSensitiveName } from "./support.js";
+/** Base type names whose values are worth sampling for enum literals. */
+const STRINGISH_MYSQL_TYPES = new Set([
+    'char',
+    'varchar',
+    'nchar',
+    'nvarchar',
+    'tinytext',
+    'text',
+    'mediumtext',
+    'longtext',
+    'enum',
+    'set',
+]);
+/**
+ * Whether a column's declared type is string-like, and therefore worth sampling for enum values.
+ * MySQL reports the declared type (`varchar(64)`, `enum('a','b')`), so the base word before any
+ * parenthesized modifier decides.
+ * @param columnType - `COLUMN_TYPE` as the server declared it.
+ * @returns true for character, text, enum and set types.
+ */
+export function isStringishMysqlType(columnType) {
+    const base = columnType.toLowerCase().split('(')[0]?.trim() ?? '';
+    const word = base.split(/\s+/)[0] ?? '';
+    return STRINGISH_MYSQL_TYPES.has(word);
+}
+/**
+ * Whether one column is a candidate for enum sampling.
+ *
+ * Three gates, each for its own reason: a view's sampling query executes its definition (unbounded
+ * work for a catalog enrichment), a non-string column's distinct values are numbers rather than
+ * vocabulary, and a sensitive column's literals must never reach the on-disk index.
+ * @param objectKind - the object's kind (`table`, `view`, …).
+ * @param connection - the connection whose masking configuration applies.
+ * @param column - the column to screen.
+ * @returns true when sampling this column is safe and useful.
+ */
+export function shouldSampleMysqlColumn(objectKind, connection, column) {
+    if (objectKind !== 'table')
+        return false;
+    if (!isStringishMysqlType(column.type))
+        return false;
+    return !isSensitiveName(connection, column.name);
+}
+/**
+ * The join key for a comment map: a column is identified by table plus column, never by column name
+ * alone (two tables routinely share `id`).
+ * @param table - table name.
+ * @param column - column name.
+ * @returns a key that cannot collide with an ordinary name.
+ */
+export function mysqlColumnKey(table, column) {
+    return `${table}\u0000${column}`;
+}
+/**
+ * Interpret one `TABLES` row.
+ *
+ * `TABLE_COMMENT` is `VIEW` for every view in MySQL — that is a marker, not a description, so it is
+ * dropped rather than shown to a model as if a human wrote it. An empty string is also no comment.
+ * @param row - one `information_schema.TABLES` row.
+ * @returns the object's kind plus whatever comment and row estimate are real.
+ */
+export function mysqlTableFacts(row) {
+    const tableType = (asString(row.TABLE_TYPE) ?? '').toUpperCase();
+    const kind = tableType.includes('VIEW') ? 'view' : 'table';
+    const rawComment = asString(row.TABLE_COMMENT)?.trim();
+    const comment = rawComment === undefined || rawComment === '' || (kind === 'view' && rawComment.toUpperCase() === 'VIEW')
+        ? undefined
+        : rawComment;
+    const rowEstimate = asFiniteNumber(row.TABLE_ROWS);
+    return {
+        kind,
+        ...(comment === undefined ? {} : { comment }),
+        ...(rowEstimate === undefined ? {} : { rowEstimate }),
+    };
+}
+/**
+ * Group `COLUMNS` rows into per-table column lists, in declared order.
+ *
+ * `isUnique` is deliberately not derived from `COLUMN_KEY`: MySQL reports `UNI` for the first
+ * column of *any* unique index, including a multi-column one, which would claim a column is unique
+ * on its own when it is not. L2 computes uniqueness from `STATISTICS` instead.
+ * @param rows - `information_schema.COLUMNS` rows.
+ * @returns columns keyed by table name.
+ */
+export function groupMysqlColumns(rows) {
+    const grouped = new Map();
+    for (const row of rows) {
+        const table = asString(row.TABLE_NAME);
+        const name = asString(row.COLUMN_NAME);
+        if (table === undefined || name === undefined)
+            continue;
+        const list = grouped.get(table) ?? [];
+        const defaultValue = asString(row.COLUMN_DEFAULT);
+        list.push({
+            name,
+            ordinal: asFiniteNumber(row.ORDINAL_POSITION) ?? list.length + 1,
+            type: asString(row.COLUMN_TYPE) ?? '',
+            nullable: (asString(row.IS_NULLABLE) ?? 'YES').toUpperCase() === 'YES',
+            isPrimaryKey: (asString(row.COLUMN_KEY) ?? '').toUpperCase() === 'PRI',
+            ...(defaultValue === undefined ? {} : { defaultValue }),
+        });
+        grouped.set(table, list);
+    }
+    for (const [table, columns] of grouped) {
+        grouped.set(table, [...columns].sort((left, right) => left.ordinal - right.ordinal));
+    }
+    return grouped;
+}
+/**
+ * Extract column comments, keyed by {@link mysqlColumnKey}.
+ * @param rows - `information_schema.COLUMNS` rows that selected `COLUMN_COMMENT`.
+ * @returns non-empty comments only.
+ */
+export function mysqlColumnComments(rows) {
+    const comments = new Map();
+    for (const row of rows) {
+        const table = asString(row.TABLE_NAME);
+        const column = asString(row.COLUMN_NAME);
+        const comment = asString(row.COLUMN_COMMENT)?.trim();
+        if (table === undefined || column === undefined || comment === undefined || comment === '')
+            continue;
+        comments.set(mysqlColumnKey(table, column), comment);
+    }
+    return comments;
+}
+/**
+ * Group `KEY_COLUMN_USAGE` rows into one edge per foreign-key constraint.
+ *
+ * `refObject` is the referenced table's plain name: a catalog describes exactly one schema, and
+ * `RawEdge` has no `refSchema` field, so a schema-qualified name here would not match anything the
+ * writer stores.
+ * @param rows - foreign-key rows, in any order.
+ * @returns edges keyed by the referencing table name.
+ */
+export function groupMysqlForeignKeys(rows) {
+    const groups = new Map();
+    for (const row of rows) {
+        const table = asString(row.TABLE_NAME);
+        const column = asString(row.COLUMN_NAME);
+        const referencedTable = asString(row.REFERENCED_TABLE_NAME);
+        const referencedColumn = asString(row.REFERENCED_COLUMN_NAME);
+        if (table === undefined || column === undefined)
+            continue;
+        if (referencedTable === undefined || referencedColumn === undefined)
+            continue;
+        const name = asString(row.CONSTRAINT_NAME);
+        const key = `${table}\u0000${name ?? ''}`;
+        const group = groups.get(key) ?? { table, name, referencedTable, parts: [] };
+        group.parts.push({
+            seq: asFiniteNumber(row.ORDINAL_POSITION) ?? group.parts.length + 1,
+            column,
+            referencedColumn,
+        });
+        groups.set(key, group);
+    }
+    const edges = new Map();
+    for (const group of groups.values()) {
+        const parts = [...group.parts].sort((left, right) => left.seq - right.seq);
+        const list = edges.get(group.table) ?? [];
+        list.push({
+            kind: 'fk',
+            ...(group.name === undefined ? {} : { name: group.name }),
+            columns: parts.map(part => part.column),
+            refObject: group.referencedTable,
+            refColumns: parts.map(part => part.referencedColumn),
+        });
+        edges.set(group.table, list);
+    }
+    return edges;
+}
+/**
+ * Group `STATISTICS` rows into index edges and the set of singly-unique columns.
+ *
+ * A functional index (MySQL 8) reports a `NULL` `COLUMN_NAME` and an expression instead; the seam's
+ * edge shape only has column names, so such an index is skipped rather than recorded with a wrong
+ * or empty column list.
+ * @param rows - `information_schema.STATISTICS` rows, in any order.
+ * @returns edges and single-column uniqueness, both keyed by table name.
+ */
+export function groupMysqlIndexes(rows) {
+    const groups = new Map();
+    for (const row of rows) {
+        const table = asString(row.TABLE_NAME);
+        const name = asString(row.INDEX_NAME);
+        if (table === undefined || name === undefined)
+            continue;
+        const key = `${table}\u0000${name}`;
+        const group = groups.get(key) ?? {
+            table,
+            name,
+            unique: asFiniteNumber(row.NON_UNIQUE) === 0,
+            parts: [],
+        };
+        group.parts.push({
+            seq: asFiniteNumber(row.SEQ_IN_INDEX) ?? group.parts.length + 1,
+            column: asString(row.COLUMN_NAME),
+        });
+        groups.set(key, group);
+    }
+    const edges = new Map();
+    const singleUnique = new Map();
+    for (const group of groups.values()) {
+        const parts = [...group.parts].sort((left, right) => left.seq - right.seq);
+        if (parts.some(part => part.column === undefined))
+            continue;
+        const columns = parts.map(part => part.column);
+        if (columns.length === 0)
+            continue;
+        const list = edges.get(group.table) ?? [];
+        list.push({ kind: 'index', name: group.name, columns, unique: group.unique });
+        edges.set(group.table, list);
+        const only = columns.length === 1 ? columns[0] : undefined;
+        if (group.unique && only !== undefined) {
+            const set = singleUnique.get(group.table) ?? new Set();
+            set.add(only);
+            singleUnique.set(group.table, set);
+        }
+    }
+    return { edges, singleUnique };
+}
+/**
+ * Merge one table's L1 object with its L2 facts, without mutating the input.
+ *
+ * Column comments are applied here rather than in `groupMysqlColumns` so L1 stays a structural
+ * snapshot and L2 is the only level that reads `COLUMN_COMMENT`.
+ * @param object - the L1 object.
+ * @param facts - what the `TABLES` row says about it, when one still exists.
+ * @param columnComments - comments keyed by {@link mysqlColumnKey}.
+ * @param uniqueColumns - columns covered by a single-column unique index.
+ * @param edges - foreign-key and index edges leaving this object.
+ * @param enumSamples - sampled literals keyed by column name.
+ * @returns a new object carrying the enrichment.
+ */
+export function mergeMysqlObject(object, facts, columnComments, uniqueColumns, edges, enumSamples) {
+    const columns = object.columns.map(column => {
+        const comment = columnComments.get(mysqlColumnKey(object.name, column.name));
+        const sampled = enumSamples.get(column.name);
+        return {
+            ...column,
+            isUnique: uniqueColumns?.has(column.name) ?? false,
+            ...(comment === undefined ? {} : { comment }),
+            ...(sampled === undefined ? {} : { enumValues: sampled }),
+        };
+    });
+    return {
+        ...object,
+        ...(facts?.comment === undefined ? {} : { comment: facts.comment }),
+        ...(facts?.rowEstimate === undefined ? {} : { rowEstimate: facts.rowEstimate }),
+        columns,
+        ...(edges.length === 0 ? {} : { edges }),
+    };
+}
+//# sourceMappingURL=mysql-map.js.map