@rawsql-ts/ddl-docs-cli 0.2.2

package/dist/src/parser/snapshotTableDocs.js

@@ -0,0 +1,1001 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshotTableDocs = snapshotTableDocs;
+const rawsql_ts_1 = require("rawsql-ts");
+const typeNormalization_1 = require("../analyzer/typeNormalization");
+const slug_1 = require("../utils/slug");
+const formatter = new rawsql_ts_1.SqlFormatter({
+    preset: 'postgres',
+    keywordCase: 'lower',
+    indentSize: 2,
+    indentChar: ' ',
+    newline: '\n',
+    commaBreak: 'after',
+    exportComment: 'none',
+    identifierEscape: 'quote',
+});
+function snapshotTableDocs(sources, schemaSettings, options) {
+    const registry = new Map();
+    const comments = {
+        tableComments: new Map(),
+        columnComments: new Map(),
+    };
+    const triggerAccumulator = { items: [] };
+    const warnings = [];
+    for (const source of sources) {
+        // Strip psql meta-commands (\connect, \restrict, etc.) that pg_dump emits
+        const cleanedSql = source.sql
+            .split('\n')
+            .map(line => (/^\s*\\/.test(line) ? '' : line))
+            .join('\n');
+        const statements = rawsql_ts_1.MultiQuerySplitter.split(cleanedSql).queries;
+        for (let statementIndex = 0; statementIndex < statements.length; statementIndex += 1) {
+            const statement = statements[statementIndex];
+            if (statement.isEmpty) {
+                continue;
+            }
+            const sql = statement.sql.trim();
+            if (!sql) {
+                continue;
+            }
+            // Silently skip statements that are intentionally out of scope
+            const sqlLower = sql.toLowerCase().replace(/\/\*[\s\S]*?\*\//g, '').replace(/--[^\n]*/g, '').trim();
+            if (sqlLower.startsWith('grant ') || sqlLower.startsWith('revoke ')) {
+                continue;
+            }
+            // Silently skip DDL that is outside table structure scope:
+            // - Ownership (OWNER TO) from pg_dump
+            // - Session settings (SET, SELECT set_config) from pg_dump
+            // - Object types not tracked in table docs (SEQUENCE, FUNCTION, VIEW, SCHEMA, TYPE, DOMAIN, EXTENSION)
+            if (sqlLower.startsWith('set ') ||
+                sqlLower.startsWith('select pg_catalog.set_config(') ||
+                sqlLower.startsWith('create sequence ') ||
+                sqlLower.startsWith('alter sequence ') ||
+                sqlLower.startsWith('create schema ') ||
+                sqlLower.startsWith('create function ') ||
+                sqlLower.startsWith('create or replace function ') ||
+                sqlLower.startsWith('create procedure ') ||
+                sqlLower.startsWith('create or replace procedure ') ||
+                sqlLower.startsWith('create view ') ||
+                sqlLower.startsWith('create or replace view ') ||
+                sqlLower.startsWith('create materialized view ') ||
+                sqlLower.startsWith('create type ') ||
+                sqlLower.startsWith('create or replace type ') ||
+                sqlLower.startsWith('create domain ') ||
+                sqlLower.startsWith('create extension ') ||
+                sqlLower.startsWith('alter function ') ||
+                sqlLower.startsWith('alter procedure ') ||
+                sqlLower.startsWith('alter view ') ||
+                sqlLower.startsWith('alter materialized view ') ||
+                sqlLower.startsWith('alter schema ') ||
+                sqlLower.startsWith('alter type ') ||
+                sqlLower.startsWith('alter default privileges ')) {
+                continue;
+            }
+            // ALTER TABLE/SEQUENCE ... OWNER TO ... (pg_dump ownership statement)
+            if (sqlLower.includes(' owner to ')) {
+                continue;
+            }
+            // ALTER TABLE ... ATTACH PARTITION (partitioned table child attachment)
+            if (sqlLower.includes(' attach partition ')) {
+                continue;
+            }
+            // ALTER TABLE ... ENABLE [ALWAYS] TRIGGER (trigger state management)
+            if (sqlLower.startsWith('alter table ') && sqlLower.includes(' enable ') && sqlLower.includes(' trigger ')) {
+                continue;
+            }
+            // NOTE: CREATE TRIGGER is handled here via regex as an intentional exception.
+            // Ideally, trigger parsing should be implemented in the rawsql-ts core parser
+            // (SqlParser + DDLStatements model), but that work has not been done yet.
+            // Regex parsing is used as a pragmatic workaround until core support is added.
+            if (sqlLower.startsWith('create trigger ') ||
+                sqlLower.startsWith('create or replace trigger ') ||
+                sqlLower.startsWith('create constraint trigger ')) {
+                collectTrigger(sql, source.instance, schemaSettings, triggerAccumulator);
+                continue;
+            }
+            // Silently skip DROP/ALTER TRIGGER
+            if (sqlLower.startsWith('drop trigger ') || sqlLower.startsWith('alter trigger ')) {
+                continue;
+            }
+            const commentState = applyCommentStatement(sql, schemaSettings, comments);
+            if (commentState === 'handled') {
+                continue;
+            }
+            if (commentState === 'ambiguous') {
+                const w = {
+                    kind: 'AMBIGUOUS',
+                    message: 'COMMENT ON statement could not be fully resolved.',
+                    statementPreview: previewStatement(sql),
+                    source: { filePath: source.path, statementIndex: statementIndex + 1 },
+                };
+                console.warn(`  [WARN] ${w.kind}: ${w.message} (${w.source.filePath}#${w.source.statementIndex})`);
+                warnings.push(w);
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = rawsql_ts_1.SqlParser.parse(sql);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const w = {
+                    kind: 'PARSE_FAILED',
+                    message,
+                    statementPreview: previewStatement(sql),
+                    source: { filePath: source.path, statementIndex: statementIndex + 1 },
+                };
+                console.warn(`  [WARN] ${w.kind}: ${w.message} (${w.source.filePath}#${w.source.statementIndex})\n         ${w.statementPreview}`);
+                warnings.push(w);
+                continue;
+            }
+            if (parsed instanceof rawsql_ts_1.CreateTableQuery) {
+                applyCreateTable(parsed, source, schemaSettings, registry);
+                continue;
+            }
+            if (parsed instanceof rawsql_ts_1.AlterTableStatement) {
+                applyAlterTable(parsed, source, schemaSettings, registry);
+                continue;
+            }
+            if (parsed instanceof rawsql_ts_1.CommentOnStatement) {
+                applyParsedCommentOn(parsed, schemaSettings, comments);
+                continue;
+            }
+            if (parsed instanceof rawsql_ts_1.CreateIndexStatement) {
+                applyCreateIndex(parsed, source, schemaSettings, registry);
+                continue;
+            }
+            const w = {
+                kind: 'UNSUPPORTED_DDL',
+                message: `Unsupported statement type: ${resolveConstructorName(parsed)}`,
+                statementPreview: previewStatement(sql),
+                source: { filePath: source.path, statementIndex: statementIndex + 1 },
+            };
+            console.warn(`  [WARN] ${w.kind}: ${w.message} (${w.source.filePath}#${w.source.statementIndex})`);
+            warnings.push(w);
+        }
+    }
+    applyCommentsToRegistry(registry, comments);
+    applyTriggersToRegistry(registry, triggerAccumulator);
+    const tables = finalizeTables(registry, options);
+    inferSuggestedReferences(tables);
+    resolveIncomingReferences(tables);
+    return {
+        tables,
+        warnings: warnings.sort(sortWarnings),
+    };
+}
+function applyCreateTable(query, source, schemaSettings, registry) {
+    var _a, _b;
+    const tableKey = buildTableKey((_a = query.namespaces) !== null && _a !== void 0 ? _a : [], query.tableName.name, schemaSettings);
+    const registryKey = buildRegistryKey(source.instance, tableKey);
+    const table = (_b = registry.get(registryKey)) !== null && _b !== void 0 ? _b : createWorkingTable(tableKey, source.instance);
+    table.sourceFiles.add(source.path);
+    const definition = (0, rawsql_ts_1.createTableDefinitionFromCreateTableQuery)(query);
+    const definitionColumns = new Map(definition.columns.map((column) => [column.name, column]));
+    for (const column of query.columns) {
+        const definitionColumn = definitionColumns.get(column.name.name);
+        const typeName = normalizeTypeName(column.dataType, definitionColumn === null || definitionColumn === void 0 ? void 0 : definitionColumn.typeName);
+        const normalizedType = (0, typeNormalization_1.normalizePostgresType)(typeName);
+        const nullable = !column.constraints.some((constraint) => constraint.kind === 'not-null' || constraint.kind === 'primary-key');
+        const defaultConstraint = column.constraints.find((constraint) => constraint.kind === 'default');
+        const workingColumn = {
+            ordinal: columnIndex(table, column.name.name),
+            name: column.name.name,
+            concept: normalizeIdentifier(column.name.name),
+            conceptSlug: (0, slug_1.slugifyIdentifier)(normalizeIdentifier(column.name.name)),
+            typeName,
+            canonicalType: normalizedType.canonicalType,
+            typeKey: normalizedType.typeKey,
+            unknownType: normalizedType.unknown,
+            nullable,
+            defaultValue: (defaultConstraint === null || defaultConstraint === void 0 ? void 0 : defaultConstraint.defaultValue) ? renderExpression(defaultConstraint.defaultValue) : '',
+            isPrimaryKey: column.constraints.some((constraint) => constraint.kind === 'primary-key'),
+            comment: '',
+        };
+        table.columns.set(workingColumn.name, workingColumn);
+        applyColumnConstraints(table, tableKey, column.name.name, column.constraints, schemaSettings);
+    }
+    for (const constraint of query.tableConstraints) {
+        applyTableConstraint(table, tableKey, constraint, schemaSettings);
+    }
+    table.constraints = dedupeConstraints(table.constraints);
+    table.outgoingReferences = dedupeReferences(table.outgoingReferences);
+    registry.set(registryKey, table);
+}
+function applyAlterTable(statement, source, schemaSettings, registry) {
+    var _a, _b;
+    const tableKey = buildTableKey((_a = statement.table.namespaces) !== null && _a !== void 0 ? _a : [], statement.table.name, schemaSettings);
+    const registryKey = buildRegistryKey(source.instance, tableKey);
+    const table = (_b = registry.get(registryKey)) !== null && _b !== void 0 ? _b : createWorkingTable(tableKey, source.instance);
+    table.sourceFiles.add(source.path);
+    for (const action of statement.actions) {
+        if (action instanceof rawsql_ts_1.AlterTableAlterColumnDefault && action.setDefault !== null) {
+            const columnName = normalizeIdentifier(action.columnName);
+            const column = table.columns.get(columnName);
+            if (column) {
+                column.defaultValue = renderExpression(action.setDefault);
+            }
+            continue;
+        }
+        if (action instanceof rawsql_ts_1.AlterTableAlterColumnDefault && action.dropDefault) {
+            const columnName = normalizeIdentifier(action.columnName);
+            const column = table.columns.get(columnName);
+            if (column) {
+                column.defaultValue = '';
+            }
+            continue;
+        }
+        if (!(action instanceof rawsql_ts_1.AlterTableAddConstraint)) {
+            continue;
+        }
+        applyTableConstraint(table, tableKey, action.constraint, schemaSettings);
+    }
+    table.constraints = dedupeConstraints(table.constraints);
+    table.outgoingReferences = dedupeReferences(table.outgoingReferences);
+    registry.set(registryKey, table);
+}
+function applyColumnConstraints(table, tableKey, columnName, constraints, schemaSettings) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    for (const constraint of constraints) {
+        if (constraint.kind === 'primary-key') {
+            const column = table.columns.get(columnName);
+            if (column) {
+                column.isPrimaryKey = true;
+                column.nullable = false;
+            }
+            table.constraints.push({
+                kind: 'PK',
+                name: (_b = (_a = constraint.constraintName) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : '',
+                expression: `${columnName}`,
+            });
+            continue;
+        }
+        if (constraint.kind === 'unique') {
+            table.constraints.push({
+                kind: 'UK',
+                name: (_d = (_c = constraint.constraintName) === null || _c === void 0 ? void 0 : _c.name) !== null && _d !== void 0 ? _d : '',
+                expression: `${columnName}`,
+            });
+            continue;
+        }
+        if (constraint.kind === 'check' && constraint.checkExpression) {
+            table.constraints.push({
+                kind: 'CHECK',
+                name: (_f = (_e = constraint.constraintName) === null || _e === void 0 ? void 0 : _e.name) !== null && _f !== void 0 ? _f : '',
+                expression: renderExpression(constraint.checkExpression),
+            });
+            continue;
+        }
+        if (constraint.kind === 'references' && constraint.reference) {
+            const targetSchema = resolveTargetSchema((_g = constraint.reference.targetTable.namespaces) !== null && _g !== void 0 ? _g : [], schemaSettings);
+            const targetTable = normalizeIdentifier(constraint.reference.targetTable.name);
+            const targetColumns = ((_h = constraint.reference.columns) !== null && _h !== void 0 ? _h : []).map((entry) => normalizeIdentifier(entry.name));
+            const onDeleteAction = (_j = constraint.reference.onDelete) !== null && _j !== void 0 ? _j : null;
+            const onUpdateAction = (_k = constraint.reference.onUpdate) !== null && _k !== void 0 ? _k : null;
+            table.constraints.push({
+                kind: 'FK',
+                name: (_m = (_l = constraint.constraintName) === null || _l === void 0 ? void 0 : _l.name) !== null && _m !== void 0 ? _m : '',
+                expression: formatReferenceExpression([columnName], `${targetSchema}.${targetTable}`, targetColumns, onDeleteAction, onUpdateAction),
+            });
+            table.outgoingReferences.push({
+                fromTableKey: tableKey,
+                fromColumns: [columnName],
+                targetTableKey: `${targetSchema}.${targetTable}`,
+                targetColumns,
+                onDeleteAction,
+                onUpdateAction,
+            });
+        }
+    }
+}
+function applyTableConstraint(table, tableKey, constraint, schemaSettings) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
+    if (constraint.kind === 'primary-key') {
+        for (const identifier of (_a = constraint.columns) !== null && _a !== void 0 ? _a : []) {
+            const column = table.columns.get(identifier.name);
+            if (!column) {
+                continue;
+            }
+            column.isPrimaryKey = true;
+            column.nullable = false;
+        }
+        table.constraints.push({
+            kind: 'PK',
+            name: (_c = (_b = constraint.constraintName) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : '',
+            expression: ((_d = constraint.columns) !== null && _d !== void 0 ? _d : []).map((entry) => entry.name).sort().join(', '),
+        });
+        return;
+    }
+    if (constraint.kind === 'unique') {
+        table.constraints.push({
+            kind: 'UK',
+            name: (_f = (_e = constraint.constraintName) === null || _e === void 0 ? void 0 : _e.name) !== null && _f !== void 0 ? _f : '',
+            expression: ((_g = constraint.columns) !== null && _g !== void 0 ? _g : []).map((entry) => entry.name).sort().join(', '),
+        });
+        return;
+    }
+    if (constraint.kind === 'check' && constraint.checkExpression) {
+        table.constraints.push({
+            kind: 'CHECK',
+            name: (_j = (_h = constraint.constraintName) === null || _h === void 0 ? void 0 : _h.name) !== null && _j !== void 0 ? _j : '',
+            expression: renderExpression(constraint.checkExpression),
+        });
+        return;
+    }
+    if (constraint.kind === 'foreign-key' && constraint.reference) {
+        const fromColumns = ((_k = constraint.columns) !== null && _k !== void 0 ? _k : []).map((entry) => entry.name);
+        const targetSchema = resolveTargetSchema((_l = constraint.reference.targetTable.namespaces) !== null && _l !== void 0 ? _l : [], schemaSettings);
+        const targetTable = normalizeIdentifier(constraint.reference.targetTable.name);
+        const targetColumns = ((_m = constraint.reference.columns) !== null && _m !== void 0 ? _m : []).map((entry) => normalizeIdentifier(entry.name));
+        const onDeleteAction = (_o = constraint.reference.onDelete) !== null && _o !== void 0 ? _o : null;
+        const onUpdateAction = (_p = constraint.reference.onUpdate) !== null && _p !== void 0 ? _p : null;
+        table.constraints.push({
+            kind: 'FK',
+            name: (_r = (_q = constraint.constraintName) === null || _q === void 0 ? void 0 : _q.name) !== null && _r !== void 0 ? _r : '',
+            expression: formatReferenceExpression(fromColumns, `${targetSchema}.${targetTable}`, targetColumns, onDeleteAction, onUpdateAction),
+        });
+        table.outgoingReferences.push({
+            fromTableKey: tableKey,
+            fromColumns,
+            targetTableKey: `${targetSchema}.${targetTable}`,
+            targetColumns,
+            onDeleteAction,
+            onUpdateAction,
+        });
+    }
+}
+function createWorkingTable(tableKey, instance = '') {
+    const [schema, table] = tableKey.split('.');
+    return {
+        schema,
+        table,
+        schemaSlug: (0, slug_1.slugifyIdentifier)(schema),
+        tableSlug: (0, slug_1.slugifyIdentifier)(table),
+        instance,
+        tableComment: '',
+        sourceFiles: new Set(),
+        columns: new Map(),
+        constraints: [],
+        triggers: [],
+        outgoingReferences: [],
+    };
+}
+function normalizeTypeName(dataType, fallbackType) {
+    if (dataType instanceof rawsql_ts_1.TypeValue) {
+        return dataType.getTypeName();
+    }
+    if (dataType instanceof rawsql_ts_1.RawString) {
+        return dataType.value;
+    }
+    return fallbackType !== null && fallbackType !== void 0 ? fallbackType : '';
+}
+function renderExpression(component) {
+    return formatter.format(component).formattedSql.trim();
+}
+function applyCreateIndex(statement, source, schemaSettings, registry) {
+    var _a;
+    const tableKey = buildTableKey((_a = statement.tableName.namespaces) !== null && _a !== void 0 ? _a : [], statement.tableName.name, schemaSettings);
+    const registryKey = buildRegistryKey(source.instance, tableKey);
+    const table = registry.get(registryKey);
+    if (!table) {
+        return;
+    }
+    const kind = statement.unique ? 'UK' : 'INDEX';
+    const name = normalizeIdentifier(statement.indexName.name);
+    const expression = statement.columns.map((col) => renderExpression(col.expression)).join(', ');
+    table.constraints.push({ kind, name, expression, isIndex: true });
+    table.constraints = dedupeConstraints(table.constraints);
+}
+/**
+ * Parses a CREATE TRIGGER statement using regex and stores it in the accumulator.
+ *
+ * NOTE: This is an intentional exception to the design philosophy of this package,
+ * which normally delegates all SQL parsing to the rawsql-ts core (SqlParser).
+ * CREATE TRIGGER is not yet supported by the core parser, so regex is used here
+ * as a pragmatic workaround. Once core support is added, this function should be
+ * replaced with a proper SqlParser-based approach.
+ */
+function collectTrigger(sql, instance, schemaSettings, accumulator) {
+    const normalized = sql.replace(/\s+/g, ' ').trim();
+    const nameMatch = normalized.match(/\btrigger\s+"?(\w+)"?\s/i);
+    if (!nameMatch)
+        return;
+    const name = nameMatch[1].toLowerCase();
+    const timingMatch = normalized.match(/\b(before|after|instead\s+of)\b/i);
+    const timing = timingMatch ? timingMatch[1].toUpperCase().replace(/\s+/g, ' ') : '';
+    const onMatch = normalized.match(/\bon\s+([\w."]+(?:\.[\w."]+)*)/i);
+    if (!onMatch)
+        return;
+    const rawTableRef = onMatch[1].replace(/"/g, '').toLowerCase();
+    const parts = rawTableRef.split('.');
+    const tableKey = parts.length >= 2
+        ? `${parts[parts.length - 2]}.${parts[parts.length - 1]}`
+        : `${schemaSettings.defaultSchema}.${parts[0]}`;
+    const registryKey = buildRegistryKey(instance, tableKey);
+    const eventsMatch = normalized.match(/\b(?:before|after|instead\s+of)\b\s+(.*?)\s+\bon\b/i);
+    const events = [];
+    if (eventsMatch) {
+        const eventsStr = eventsMatch[1];
+        if (/\binsert\b/i.test(eventsStr))
+            events.push('INSERT');
+        if (/\bupdate\b/i.test(eventsStr))
+            events.push('UPDATE');
+        if (/\bdelete\b/i.test(eventsStr))
+            events.push('DELETE');
+        if (/\btruncate\b/i.test(eventsStr))
+            events.push('TRUNCATE');
+    }
+    const forEachMatch = normalized.match(/\bfor\s+(?:each\s+)?(row|statement)\b/i);
+    const forEach = forEachMatch ? forEachMatch[1].toUpperCase() : 'ROW';
+    const funcMatch = normalized.match(/\bexecute\s+(?:function|procedure)\s+([\w."]+(?:\.[\w."]+)*\s*\([^)]*\))/i);
+    const functionName = funcMatch ? funcMatch[1].replace(/"/g, '').toLowerCase().replace(/\s+/g, '') : '';
+    const rawSql = normalized.endsWith(';') ? normalized : `${normalized};`;
+    accumulator.items.push({ tableKey: registryKey, trigger: { name, timing, events, forEach, functionName, rawSql } });
+}
+function applyTriggersToRegistry(registry, accumulator) {
+    for (const { tableKey, trigger } of accumulator.items) {
+        const table = registry.get(tableKey);
+        if (!table)
+            continue;
+        const already = table.triggers.some((t) => t.name === trigger.name);
+        if (!already) {
+            table.triggers.push(trigger);
+        }
+    }
+}
+function buildTableKey(namespaces, tableName, schemaSettings) {
+    const normalizedTable = normalizeIdentifier(tableName);
+    if (namespaces.length > 0) {
+        const schema = normalizeIdentifier(namespaces[namespaces.length - 1]);
+        return `${schema}.${normalizedTable}`;
+    }
+    return `${schemaSettings.defaultSchema}.${normalizedTable}`;
+}
+function buildRegistryKey(instance, tableKey) {
+    return `${instance !== null && instance !== void 0 ? instance : ''}\u0000${tableKey}`;
+}
+function normalizeIdentifier(value) {
+    const token = typeof value === 'string' ? value : 'name' in value ? value.name : value.value;
+    return token.replace(/^"|"$/g, '').toLowerCase();
+}
+function resolveTargetSchema(namespaces, schemaSettings) {
+    if (!namespaces || namespaces.length === 0) {
+        return schemaSettings.defaultSchema;
+    }
+    return normalizeIdentifier(namespaces[namespaces.length - 1]);
+}
+function applyParsedCommentOn(statement, schemaSettings, comments) {
+    var _a;
+    const commentText = statement.comment !== null
+        ? parseCommentLiteral(renderExpression(statement.comment))
+        : null;
+    if (commentText === null)
+        return;
+    const namespaces = (_a = statement.target.namespaces) !== null && _a !== void 0 ? _a : [];
+    const name = normalizeIdentifier(statement.target.name);
+    if (statement.targetKind === 'table') {
+        const schema = namespaces.length > 0
+            ? normalizeIdentifier(namespaces[namespaces.length - 1])
+            : schemaSettings.defaultSchema;
+        comments.tableComments.set(`${schema}.${name}`, commentText);
+    }
+    else {
+        // column: namespaces = [schema, table] or [table]
+        if (namespaces.length >= 2) {
+            const schema = normalizeIdentifier(namespaces[namespaces.length - 2]);
+            const table = normalizeIdentifier(namespaces[namespaces.length - 1]);
+            comments.columnComments.set(`${schema}.${table}.${name}`, commentText);
+        }
+        else if (namespaces.length === 1) {
+            const table = normalizeIdentifier(namespaces[0]);
+            comments.columnComments.set(`${schemaSettings.defaultSchema}.${table}.${name}`, commentText);
+        }
+    }
+}
+/** Returns true if the lowercase COMMENT ON statement targets an object type we don't track. */
+function isUnsupportedCommentOnTarget(lower) {
+    return (lower.startsWith('comment on constraint ') ||
+        lower.startsWith('comment on view ') ||
+        lower.startsWith('comment on materialized view ') ||
+        lower.startsWith('comment on index ') ||
+        lower.startsWith('comment on sequence ') ||
+        lower.startsWith('comment on function ') ||
+        lower.startsWith('comment on procedure ') ||
+        lower.startsWith('comment on type ') ||
+        lower.startsWith('comment on schema ') ||
+        lower.startsWith('comment on extension '));
+}
+function applyCommentStatement(sql, schemaSettings, comments) {
+    const normalized = sql.trim();
+    const lower = normalized.toLowerCase();
+    if (!lower.startsWith('comment on ')) {
+        // The SQL may have pg_dump section-header comments (-- -- Name: ...) prepended.
+        // Strip them to detect the actual statement type, but only for classification.
+        // TABLE/COLUMN handling is left to SqlParser (via the 'ignored' return path) so
+        // that multi-line comment values and keyword column names are handled correctly.
+        const strippedLower = normalized.replace(/^(?:--[^\n]*\n)+/g, '').trim().toLowerCase();
+        if (!strippedLower.startsWith('comment on ')) {
+            return 'ignored';
+        }
+        // Silently skip COMMENT ON for object types we don't track in table docs.
+        if (isUnsupportedCommentOnTarget(strippedLower)) {
+            return 'handled';
+        }
+        // TABLE/COLUMN COMMENT with pg_dump headers → let SqlParser handle it.
+        return 'ignored';
+    }
+    // Direct COMMENT ON (no pg_dump headers).
+    // Silently skip unsupported object types.
+    if (isUnsupportedCommentOnTarget(lower)) {
+        return 'handled';
+    }
+    const tableMatch = normalized.match(/^comment\s+on\s+table\s+(.+?)\s+is\s+(.+?);?$/i);
+    if (tableMatch) {
+        const parsedComment = parseCommentLiteral(tableMatch[2]);
+        if (parsedComment === null) {
+            return 'handled';
+        }
+        const target = parseTableTarget(tableMatch[1], schemaSettings);
+        comments.tableComments.set(target, parsedComment);
+        return 'handled';
+    }
+    const columnMatch = normalized.match(/^comment\s+on\s+column\s+(.+?)\s+is\s+(.+?);?$/i);
+    if (!columnMatch) {
+        return 'ambiguous';
+    }
+    const parsedComment = parseCommentLiteral(columnMatch[2]);
+    if (parsedComment === null) {
+        return 'handled';
+    }
+    const target = parseColumnTarget(columnMatch[1], schemaSettings);
+    if (!target) {
+        return 'ambiguous';
+    }
+    comments.columnComments.set(target, parsedComment);
+    return 'handled';
+}
+function parseCommentLiteral(rawValue) {
+    const trimmed = rawValue.trim().replace(/;$/, '');
+    if (/^null$/i.test(trimmed)) {
+        return null;
+    }
+    if (!trimmed.startsWith("'") || !trimmed.endsWith("'")) {
+        return trimmed;
+    }
+    const body = trimmed.slice(1, -1);
+    return body.replace(/''/g, "'");
+}
+function parseTableTarget(rawTarget, schemaSettings) {
+    var _a;
+    const parts = parseQualifiedParts(rawTarget);
+    if (parts.length >= 2) {
+        return `${parts[parts.length - 2]}.${parts[parts.length - 1]}`;
+    }
+    return `${schemaSettings.defaultSchema}.${(_a = parts[0]) !== null && _a !== void 0 ? _a : 'unknown'}`;
+}
+function parseColumnTarget(rawTarget, schemaSettings) {
+    const parts = parseQualifiedParts(rawTarget);
+    if (parts.length < 2) {
+        return null;
+    }
+    if (parts.length >= 3) {
+        return `${parts[parts.length - 3]}.${parts[parts.length - 2]}.${parts[parts.length - 1]}`;
+    }
+    return `${schemaSettings.defaultSchema}.${parts[0]}.${parts[1]}`;
+}
+function parseQualifiedParts(input) {
+    const parts = [];
+    let current = '';
+    let inQuote = false;
+    for (let index = 0; index < input.length; index += 1) {
+        const char = input[index];
+        if (char === '"') {
+            inQuote = !inQuote;
+            continue;
+        }
+        if (char === '.' && !inQuote) {
+            if (current.trim().length > 0) {
+                parts.push(normalizeIdentifier(current.trim()));
+            }
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim().length > 0) {
+        parts.push(normalizeIdentifier(current.trim()));
+    }
+    return parts;
+}
+function applyCommentsToRegistry(registry, comments) {
+    for (const [tableKey, comment] of comments.tableComments.entries()) {
+        const [schema, tableName] = tableKey.split('.');
+        if (!schema || !tableName) {
+            continue;
+        }
+        const tables = findTablesBySchemaAndName(registry, schema, tableName);
+        for (const table of tables) {
+            table.tableComment = comment;
+        }
+    }
+    for (const [columnKey, comment] of comments.columnComments.entries()) {
+        const [schema, tableName, columnName] = columnKey.split('.');
+        if (!schema || !tableName || !columnName) {
+            continue;
+        }
+        const tables = findTablesBySchemaAndName(registry, schema, tableName);
+        for (const table of tables) {
+            const column = table.columns.get(columnName);
+            if (!column) {
+                continue;
+            }
+            column.comment = comment;
+        }
+    }
+}
+function finalizeTables(registry, options) {
+    return Array.from(registry.values())
+        .map((entry) => {
+        const columns = Array.from(entry.columns.values())
+            .sort((a, b) => sortColumns(a, b, options.columnOrder))
+            .map((column) => ({
+            name: column.name,
+            concept: column.concept,
+            conceptSlug: column.conceptSlug,
+            typeName: column.typeName,
+            canonicalType: column.canonicalType,
+            typeKey: column.typeKey,
+            nullable: column.nullable,
+            defaultValue: column.defaultValue,
+            isPrimaryKey: column.isPrimaryKey,
+            comment: column.comment,
+            checks: [],
+            unknownType: column.unknownType,
+        }));
+        const primaryKey = columns.filter((column) => column.isPrimaryKey).map((column) => column.name).sort();
+        const outgoingReferences = entry.outgoingReferences
+            .map((reference) => {
+            var _a, _b, _c, _d, _e, _f;
+            return ({
+                direction: 'outgoing',
+                source: 'ddl',
+                fromTableKey: reference.fromTableKey,
+                fromTableComment: entry.tableComment,
+                targetTableKey: reference.targetTableKey,
+                targetTableComment: (_b = (_a = findTableByTableKey(registry, reference.targetTableKey, entry.instance)) === null || _a === void 0 ? void 0 : _a.tableComment) !== null && _b !== void 0 ? _b : '',
+                fromColumns: [...reference.fromColumns],
+                targetColumns: [...reference.targetColumns],
+                onDeleteAction: reference.onDeleteAction,
+                onUpdateAction: reference.onUpdateAction,
+                fromSchemaSlug: (0, slug_1.slugifyIdentifier)((_c = reference.fromTableKey.split('.')[0]) !== null && _c !== void 0 ? _c : ''),
+                fromTableSlug: (0, slug_1.slugifyIdentifier)((_d = reference.fromTableKey.split('.')[1]) !== null && _d !== void 0 ? _d : ''),
+                targetSchemaSlug: (0, slug_1.slugifyIdentifier)((_e = reference.targetTableKey.split('.')[0]) !== null && _e !== void 0 ? _e : ''),
+                targetTableSlug: (0, slug_1.slugifyIdentifier)((_f = reference.targetTableKey.split('.')[1]) !== null && _f !== void 0 ? _f : ''),
+                expression: formatReferenceExpression(reference.fromColumns, reference.targetTableKey, reference.targetColumns),
+            });
+        })
+            .sort(sortReferences);
+        return {
+            schema: entry.schema,
+            table: entry.table,
+            schemaSlug: entry.schemaSlug,
+            tableSlug: entry.tableSlug,
+            instance: entry.instance,
+            tableComment: entry.tableComment,
+            sourceFiles: Array.from(entry.sourceFiles).sort(),
+            columns,
+            primaryKey,
+            constraints: [...entry.constraints].sort(sortConstraints),
+            triggers: [...entry.triggers].sort((a, b) => a.name.localeCompare(b.name)),
+            outgoingReferences,
+            incomingReferences: [],
+            normalizedSql: buildNormalizedSql(entry, columns),
+        };
+    })
+        .sort((a, b) => `${a.schema}.${a.table}`.localeCompare(`${b.schema}.${b.table}`));
+}
+function findTablesBySchemaAndName(registry, schema, tableName) {
+    return Array.from(registry.values()).filter((table) => table.schema === schema && table.table === tableName);
+}
+function findTableByTableKey(registry, tableKey, instance) {
+    const [schema, tableName] = tableKey.split('.');
+    if (!schema || !tableName) {
+        return undefined;
+    }
+    const sameInstanceMatch = Array.from(registry.values()).find((table) => table.schema === schema && table.table === tableName && table.instance === instance);
+    if (sameInstanceMatch) {
+        return sameInstanceMatch;
+    }
+    return Array.from(registry.values()).find((table) => table.schema === schema && table.table === tableName);
+}
+function sortColumns(left, right, mode) {
+    if (mode === 'name') {
+        const byName = left.name.localeCompare(right.name);
+        if (byName !== 0) {
+            return byName;
+        }
+    }
+    return left.ordinal - right.ordinal;
+}
+function columnIndex(table, columnName) {
+    const existing = table.columns.get(columnName);
+    if (existing) {
+        return existing.ordinal;
+    }
+    return table.columns.size;
+}
+function buildNormalizedSql(entry, columns) {
+    // --- Definition block: CREATE TABLE + ALTER TABLE constraints + CREATE [UNIQUE] INDEX ---
+    const defStatements = [];
+    const columnLines = columns.map((column) => {
+        const segments = [`  ${column.name} ${column.typeName || 'text'}`];
+        if (!column.nullable) {
+            segments.push('NOT NULL');
+        }
+        if (column.defaultValue.trim()) {
+            segments.push(`DEFAULT ${column.defaultValue}`);
+        }
+        return segments.join(' ');
+    });
+    defStatements.push(`CREATE TABLE ${entry.schema}.${entry.table} (\n${columnLines.join(',\n')}\n);`);
+    const constraints = [...entry.constraints].sort(sortConstraints);
+    for (const constraint of constraints) {
+        const prefix = constraint.name ? `CONSTRAINT ${constraint.name} ` : '';
+        if (constraint.kind === 'PK') {
+            defStatements.push(`ALTER TABLE ${entry.schema}.${entry.table} ADD ${prefix}PRIMARY KEY (${constraint.expression});`);
+            continue;
+        }
+        if (constraint.kind === 'UK' && !constraint.isIndex) {
+            defStatements.push(`ALTER TABLE ${entry.schema}.${entry.table} ADD ${prefix}UNIQUE (${constraint.expression});`);
+            continue;
+        }
+        if (constraint.kind === 'UK' && constraint.isIndex) {
+            defStatements.push(`CREATE UNIQUE INDEX ${constraint.name} ON ${entry.schema}.${entry.table} (${constraint.expression});`);
+            continue;
+        }
+        if (constraint.kind === 'CHECK') {
+            defStatements.push(`ALTER TABLE ${entry.schema}.${entry.table} ADD ${prefix}CHECK (${constraint.expression});`);
+            continue;
+        }
+        if (constraint.kind === 'FK') {
+            const [left, right] = constraint.expression.split('->').map((part) => part.trim());
+            if (left && right) {
+                defStatements.push(`ALTER TABLE ${entry.schema}.${entry.table} ADD ${prefix}FOREIGN KEY (${left}) REFERENCES ${right};`);
+            }
+            continue;
+        }
+        if (constraint.kind === 'INDEX') {
+            defStatements.push(`CREATE INDEX ${constraint.name} ON ${entry.schema}.${entry.table} (${constraint.expression});`);
+            continue;
+        }
+    }
+    const defLines = ['-- normalized: v1 dialect=postgres'];
+    for (const statement of defStatements) {
+        const formattedStatement = formatNormalizedStatement(statement);
+        if (formattedStatement) {
+            defLines.push(formattedStatement);
+        }
+    }
+    // --- Comments block: COMMENT ON TABLE + COMMENT ON COLUMN ---
+    const commentStatements = [];
+    if (entry.tableComment.trim()) {
+        commentStatements.push(`COMMENT ON TABLE ${entry.schema}.${entry.table} IS '${entry.tableComment.replace(/'/g, "''")}';`);
+    }
+    for (const column of columns) {
+        if (!column.comment.trim()) {
+            continue;
+        }
+        commentStatements.push(`COMMENT ON COLUMN ${entry.schema}.${entry.table}.${column.name} IS '${column.comment.replace(/'/g, "''")}';`);
+    }
+    let comments = '';
+    if (commentStatements.length > 0) {
+        const commentLines = ['-- normalized: v1 dialect=postgres'];
+        for (const statement of commentStatements) {
+            const formattedStatement = formatNormalizedStatement(statement);
+            if (formattedStatement) {
+                commentLines.push(formattedStatement);
+            }
+        }
+        comments = commentLines.join('\n');
+    }
+    // --- Triggers block: raw CREATE TRIGGER statements (not normalized) ---
+    let triggers = '';
+    if (entry.triggers.length > 0) {
+        const triggerLines = ['-- raw (not normalized)'];
+        for (const trigger of entry.triggers) {
+            triggerLines.push(trigger.rawSql);
+        }
+        triggers = triggerLines.join('\n');
+    }
+    return {
+        definition: defLines.join('\n'),
+        comments,
+        triggers,
+    };
+}
+function formatNormalizedStatement(statement) {
+    const trimmed = statement.trim();
+    if (!trimmed) {
+        return '';
+    }
+    try {
+        const parsed = rawsql_ts_1.SqlParser.parse(trimmed);
+        const formatted = formatter.format(parsed).formattedSql.trim().replace(/;$/, '');
+        return `${formatted};`;
+    }
+    catch {
+        return trimmed.endsWith(';') ? trimmed : `${trimmed};`;
+    }
+}
+function resolveIncomingReferences(tables) {
+    var _a, _b;
+    const incomingMap = new Map();
+    for (const table of tables) {
+        for (const outgoing of table.outgoingReferences) {
+            const incoming = (_a = incomingMap.get(outgoing.targetTableKey)) !== null && _a !== void 0 ? _a : [];
+            incoming.push({
+                direction: 'incoming',
+                source: outgoing.source,
+                fromTableKey: outgoing.fromTableKey,
+                fromTableComment: outgoing.fromTableComment,
+                targetTableKey: outgoing.targetTableKey,
+                targetTableComment: outgoing.targetTableComment,
+                fromColumns: [...outgoing.fromColumns],
+                targetColumns: [...outgoing.targetColumns],
+                onDeleteAction: outgoing.onDeleteAction,
+                onUpdateAction: outgoing.onUpdateAction,
+                fromSchemaSlug: outgoing.fromSchemaSlug,
+                fromTableSlug: outgoing.fromTableSlug,
+                targetSchemaSlug: outgoing.targetSchemaSlug,
+                targetTableSlug: outgoing.targetTableSlug,
+                matchRule: outgoing.matchRule,
+                expression: `${outgoing.fromTableKey}: ${formatReferenceExpression(outgoing.fromColumns, outgoing.targetTableKey, outgoing.targetColumns)}`,
+            });
+            incomingMap.set(outgoing.targetTableKey, incoming);
+        }
+    }
+    for (const table of tables) {
+        table.incomingReferences = ((_b = incomingMap.get(`${table.schema}.${table.table}`)) !== null && _b !== void 0 ? _b : []).sort(sortReferences);
+    }
+}
+function inferSuggestedReferences(tables) {
+    var _a, _b, _c, _d;
+    const tableByKey = new Map(tables.map((table) => [`${table.schema}.${table.table}`, table]));
+    const definedKeys = new Set();
+    for (const table of tables) {
+        for (const reference of table.outgoingReferences) {
+            if (reference.source !== 'ddl') {
+                continue;
+            }
+            definedKeys.add(referenceIdentity(reference.fromTableKey, reference.fromColumns, reference.targetTableKey, reference.targetColumns));
+        }
+    }
+    const pkTargets = tables
+        .filter((table) => table.primaryKey.length === 1)
+        .map((table) => ({
+        tableKey: `${table.schema}.${table.table}`,
+        pkColumn: table.primaryKey[0],
+        schemaSlug: table.schemaSlug,
+        tableSlug: table.tableSlug,
+        instance: table.instance,
+    }))
+        .sort((a, b) => `${a.tableKey}|${a.pkColumn}`.localeCompare(`${b.tableKey}|${b.pkColumn}`));
+    for (const table of tables) {
+        const fromTableKey = `${table.schema}.${table.table}`;
+        for (const column of table.columns) {
+            if (column.isPrimaryKey) {
+                continue;
+            }
+            for (const target of pkTargets) {
+                if (column.name !== target.pkColumn) {
+                    continue;
+                }
+                // Skip cross-instance suggestions: tables from different DB instances
+                // should not be suggested as FK candidates.
+                if (table.instance && target.instance && table.instance !== target.instance) {
+                    continue;
+                }
+                const identity = referenceIdentity(fromTableKey, [column.name], target.tableKey, [target.pkColumn]);
+                if (definedKeys.has(identity)) {
+                    continue;
+                }
+                if (tableByKey.get(target.tableKey) == null) {
+                    continue;
+                }
+                const suggested = {
+                    direction: 'outgoing',
+                    source: 'suggested',
+                    fromTableKey,
+                    fromTableComment: (_b = (_a = tableByKey.get(fromTableKey)) === null || _a === void 0 ? void 0 : _a.tableComment) !== null && _b !== void 0 ? _b : '',
+                    targetTableKey: target.tableKey,
+                    targetTableComment: (_d = (_c = tableByKey.get(target.tableKey)) === null || _c === void 0 ? void 0 : _c.tableComment) !== null && _d !== void 0 ? _d : '',
+                    fromColumns: [column.name],
+                    targetColumns: [target.pkColumn],
+                    onDeleteAction: null,
+                    onUpdateAction: null,
+                    fromSchemaSlug: table.schemaSlug,
+                    fromTableSlug: table.tableSlug,
+                    targetSchemaSlug: target.schemaSlug,
+                    targetTableSlug: target.tableSlug,
+                    matchRule: 'exact',
+                    expression: formatReferenceExpression([column.name], target.tableKey, [target.pkColumn]),
+                };
+                table.outgoingReferences.push(suggested);
+            }
+        }
+        table.outgoingReferences = dedupeDocReferences(table.outgoingReferences).sort(sortReferences);
+    }
+}
+function dedupeDocReferences(references) {
+    var _a, _b;
+    const map = new Map();
+    for (const reference of references) {
+        const key = `${reference.source}|${reference.fromTableKey}|${reference.fromColumns.join(',')}|${reference.targetTableKey}|${reference.targetColumns.join(',')}|${(_a = reference.onDeleteAction) !== null && _a !== void 0 ? _a : ''}|${(_b = reference.onUpdateAction) !== null && _b !== void 0 ? _b : ''}`;
+        map.set(key, reference);
+    }
+    return Array.from(map.values());
+}
+function referenceIdentity(fromTableKey, fromColumns, targetTableKey, targetColumns) {
+    return `${fromTableKey}|${fromColumns.join(',')}|${targetTableKey}|${targetColumns.join(',')}`;
+}
+function formatReferenceExpression(fromColumns, targetTableKey, targetColumns, onDeleteAction = null, onUpdateAction = null) {
+    const clauses = [];
+    if (onDeleteAction) {
+        clauses.push(`ON DELETE ${onDeleteAction.toUpperCase()}`);
+    }
+    if (onUpdateAction) {
+        clauses.push(`ON UPDATE ${onUpdateAction.toUpperCase()}`);
+    }
+    const actionSuffix = clauses.length > 0 ? ` ${clauses.join(' ')}` : '';
+    return `${fromColumns.join(', ')} -> ${targetTableKey}(${targetColumns.join(', ') || '?'})${actionSuffix}`;
+}
+function dedupeConstraints(constraints) {
+    const map = new Map();
+    for (const constraint of constraints) {
+        const key = `${constraint.kind}|${constraint.name}|${constraint.expression}`;
+        map.set(key, constraint);
+    }
+    return Array.from(map.values()).sort(sortConstraints);
+}
+function dedupeReferences(references) {
+    var _a, _b;
+    const map = new Map();
+    for (const reference of references) {
+        const key = `${reference.fromTableKey}|${reference.fromColumns.join(',')}|${reference.targetTableKey}|${reference.targetColumns.join(',')}|${(_a = reference.onDeleteAction) !== null && _a !== void 0 ? _a : ''}|${(_b = reference.onUpdateAction) !== null && _b !== void 0 ? _b : ''}`;
+        map.set(key, reference);
+    }
+    return Array.from(map.values()).sort((a, b) => {
+        var _a, _b, _c, _d;
+        const left = `${a.fromTableKey}|${a.fromColumns.join(',')}|${a.targetTableKey}|${a.targetColumns.join(',')}|${(_a = a.onDeleteAction) !== null && _a !== void 0 ? _a : ''}|${(_b = a.onUpdateAction) !== null && _b !== void 0 ? _b : ''}`;
+        const right = `${b.fromTableKey}|${b.fromColumns.join(',')}|${b.targetTableKey}|${b.targetColumns.join(',')}|${(_c = b.onDeleteAction) !== null && _c !== void 0 ? _c : ''}|${(_d = b.onUpdateAction) !== null && _d !== void 0 ? _d : ''}`;
+        return left.localeCompare(right);
+    });
+}
+function sortConstraints(left, right) {
+    return `${left.kind}|${left.name}|${left.expression}`.localeCompare(`${right.kind}|${right.name}|${right.expression}`);
+}
+function sortWarnings(left, right) {
+    var _a, _b;
+    const leftKey = `${left.source.filePath}|${(_a = left.source.statementIndex) !== null && _a !== void 0 ? _a : 0}|${left.kind}|${left.message}`;
+    const rightKey = `${right.source.filePath}|${(_b = right.source.statementIndex) !== null && _b !== void 0 ? _b : 0}|${right.kind}|${right.message}`;
+    return leftKey.localeCompare(rightKey);
+}
+function sortReferences(left, right) {
+    const leftOther = left.direction === 'outgoing' ? left.targetTableKey : left.fromTableKey;
+    const rightOther = right.direction === 'outgoing' ? right.targetTableKey : right.fromTableKey;
+    return `${left.direction}|${leftOther}`.localeCompare(`${right.direction}|${rightOther}`);
+}
+function previewStatement(sql) {
+    const compact = sql.replace(/\s+/g, ' ').trim();
+    return compact.length > 200 ? `${compact.slice(0, 200)}...` : compact;
+}
+function resolveConstructorName(value) {
+    var _a;
+    if (value && typeof value === 'object' && 'constructor' in value) {
+        const ctor = value.constructor;
+        return (_a = ctor === null || ctor === void 0 ? void 0 : ctor.name) !== null && _a !== void 0 ? _a : 'Unknown';
+    }
+    return typeof value;
+}
+//# sourceMappingURL=snapshotTableDocs.js.map