vouchington-tooling 0.0.9 → 0.0.11

package/dist/pg-schema-snapshot/index-rename-detect.mjs

@@ -0,0 +1,71 @@
+/**
+ * Removes the index name from a `pg_get_indexdef()` definition, leaving a byte-exact "shape key"
+ * for comparing two index definitions on identity (uniqueness, table, `ON ONLY`, access method,
+ * key columns, `INCLUDE`, opclasses, `WHERE`) while ignoring only the name.
+ *
+ * Locates the name by offset rather than by regex: it finds the first ` INDEX ` (present exactly
+ * once, since nothing before it in `CREATE [UNIQUE] INDEX ...` can contain that substring), then
+ * confirms the token immediately after is exactly `name` or `"name"`. Throws if neither matches —
+ * a caller that silently skipped an unrecognized definition would mask a real collision instead of
+ * reporting one.
+ */
+export function indexShapeKey(name, definition) {
+    const marker = ' INDEX ';
+    const markerIndex = definition.indexOf(marker);
+    if (markerIndex === -1) {
+        throw new Error(`indexShapeKey: could not find ${JSON.stringify(marker)} in index definition: ${definition}`);
+    }
+    const nameStart = markerIndex + marker.length;
+    const quotedName = `"${name}"`;
+    const bareNameEnd = nameStart + name.length;
+    const nameEnd = definition.startsWith(quotedName, nameStart)
+        ? nameStart + quotedName.length
+        : definition.startsWith(name, nameStart) &&
+            (bareNameEnd === definition.length || !/[a-zA-Z0-9_"]/.test(definition[bareNameEnd]))
+            ? bareNameEnd
+            : null;
+    if (nameEnd === null) {
+        throw new Error(`indexShapeKey: index name ${JSON.stringify(name)} does not match the token following ${JSON.stringify(marker)} in: ${definition}`);
+    }
+    return `${definition.slice(0, nameStart)}<name>${definition.slice(nameEnd)}`;
+}
+/**
+ * Detects indexes present at `base` whose name is gone at `head` but whose physical shape
+ * reappears under a different name — the cross-revision rename case that a single-revision
+ * shape scan structurally cannot see.
+ *
+ * Scope is renames only: a base index whose name simply disappears with no shape match at head
+ * (dropped outright, not renamed) is not reported.
+ *
+ * Index names are schema-unique in PostgreSQL, so a flat name set (rather than a per-table one)
+ * is sufficient to know whether a name survived into head.
+ */
+export function detectRenamedIndexes({ base, head, }) {
+    const headNames = new Set();
+    const headNamesByShape = new Map();
+    for (const table of Object.values(head.tables)) {
+        for (const [name, index] of Object.entries(table.indexes)) {
+            headNames.add(name);
+            const shapeKey = indexShapeKey(name, index.definition);
+            const namesForShape = headNamesByShape.get(shapeKey);
+            if (namesForShape)
+                namesForShape.push(name);
+            else
+                headNamesByShape.set(shapeKey, [name]);
+        }
+    }
+    const renames = [];
+    for (const [tableName, table] of Object.entries(base.tables)) {
+        for (const [retiredName, retiredIndex] of Object.entries(table.indexes)) {
+            if (headNames.has(retiredName))
+                continue;
+            const retiredDefinition = retiredIndex.definition;
+            const shapeKey = indexShapeKey(retiredName, retiredDefinition);
+            const renamedCandidates = headNamesByShape.get(shapeKey) ?? [];
+            for (const renamedTo of renamedCandidates) {
+                renames.push({ table: tableName, retiredName, retiredDefinition, renamedTo });
+            }
+        }
+    }
+    return renames;
+}

package/dist/pg-schema-snapshot/index.d.mts

@@ -0,0 +1,10 @@
+export { buildSchemaSnapshot, buildTableSnapshots } from './build-snapshot.mts';
+export { readColumns, readConstraints, readEnums, readExtensions, readFunctions, readIndexes, readPolicies, readSchemaCatalog, readTables, readTriggers, readViews, } from './catalog-queries.mts';
+export type { CatalogColumnRow, CatalogConstraintRow, CatalogEnumValueRow, CatalogExtensionRow, CatalogFunctionRow, CatalogIndexRow, CatalogPolicyRow, CatalogTableRow, CatalogTriggerRow, CatalogViewRow, SchemaCatalog, } from './catalog-queries.mts';
+export { generateSchemaSnapshot, stableStringify, writeSchemaSnapshot } from './generate.mts';
+export { detectRenamedIndexes, indexShapeKey } from './index-rename-detect.mts';
+export type { RenamedIndex, SchemaIndexRenameSnapshot } from './index-rename-detect.mts';
+export { renderSchemaMarkdown } from './render-markdown.mts';
+export type { SchemaMarkdownFiles } from './render-markdown.mts';
+export { renderTableDocument } from './render-tables.mts';
+export type { CatalogQuery, PartitionPolicy, SchemaColumnSnapshot, SchemaEnumSnapshot, SchemaExtensionSnapshot, SchemaForeignKeySnapshot, SchemaFunctionSnapshot, SchemaGrowthMaps, SchemaIndexKeySnapshot, SchemaIndexSnapshot, SchemaKeyConstraintSnapshot, SchemaPhysicalPartitionSnapshot, SchemaPolicySnapshot, SchemaSnapshot, SchemaTableSnapshot, SchemaViewSnapshot, } from './types.mts';

package/dist/pg-schema-snapshot/index.mjs

@@ -0,0 +1,6 @@
+export { buildSchemaSnapshot, buildTableSnapshots } from './build-snapshot.mjs';
+export { readColumns, readConstraints, readEnums, readExtensions, readFunctions, readIndexes, readPolicies, readSchemaCatalog, readTables, readTriggers, readViews, } from './catalog-queries.mjs';
+export { generateSchemaSnapshot, stableStringify, writeSchemaSnapshot } from './generate.mjs';
+export { detectRenamedIndexes, indexShapeKey } from './index-rename-detect.mjs';
+export { renderSchemaMarkdown } from './render-markdown.mjs';
+export { renderTableDocument } from './render-tables.mjs';

package/dist/pg-schema-snapshot/markdown-files.d.mts

@@ -0,0 +1 @@
+export declare function markdownFilesOnDisk(root: string): Promise<string[]>;

package/dist/pg-schema-snapshot/markdown-files.mjs

@@ -0,0 +1,26 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { lstatOrNull } from './file-safety.mjs';
+function unsafeSchemaSnapshotPath(path) {
+    return new Error(`Unsafe generated PostgreSQL schema snapshot path: ${path}`);
+}
+async function collectMarkdownFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const paths = await Promise.all(entries.map(async (entry) => {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory())
+            return collectMarkdownFiles(path);
+        return entry.isFile() || entry.isSymbolicLink() ? [path] : [];
+    }));
+    return paths.flat();
+}
+export async function markdownFilesOnDisk(root) {
+    const markdownRoot = join(root, 'markdown');
+    const markdownRootStats = await lstatOrNull(markdownRoot);
+    if (markdownRootStats === null)
+        return [];
+    if (markdownRootStats.isSymbolicLink() || !markdownRootStats.isDirectory()) {
+        throw unsafeSchemaSnapshotPath(markdownRoot);
+    }
+    return (await collectMarkdownFiles(markdownRoot)).toSorted((left, right) => left.localeCompare(right));
+}

package/dist/pg-schema-snapshot/render-markdown.d.mts

@@ -0,0 +1,8 @@
+import type { SchemaSnapshot } from './types.mts';
+export type SchemaMarkdownFiles = Map<string, string>;
+/**
+ * Renders deterministic, focused Markdown files from the same snapshot serialized to schema.json.
+ * Each table receives one safe filename and exactly one column table; the index directly links all
+ * generated leaves.
+ */
+export declare function renderSchemaMarkdown(snapshot: SchemaSnapshot): SchemaMarkdownFiles;

package/dist/pg-schema-snapshot/render-markdown.mjs

@@ -0,0 +1,113 @@
+import { renderTableDocument } from './render-tables.mjs';
+const SAFE_TABLE_FILENAME = /^[a-z][a-z0-9_]*$/;
+function heading(level, text) {
+    return `${'#'.repeat(level)} ${text}`;
+}
+function renderViewsDocument(snapshot) {
+    const names = Object.keys(snapshot.views).toSorted((left, right) => left.localeCompare(right));
+    const lines = [heading(1, 'Views'), '', '[Schema index](README.md).'];
+    if (names.length === 0)
+        return `${[...lines, '', '_none_'].join('\n')}\n`;
+    for (const name of names) {
+        const view = snapshot.views[name];
+        lines.push('', heading(2, `\`${name}\`${view.materialized ? ' (materialized)' : ''}`));
+        if (view.comment)
+            lines.push('', view.comment);
+        lines.push('', '```sql', view.definition, '```');
+    }
+    return `${lines.join('\n')}\n`;
+}
+function renderEnumsDocument(snapshot) {
+    const names = Object.keys(snapshot.enums).toSorted((left, right) => left.localeCompare(right));
+    const lines = [heading(1, 'Enums'), '', '[Schema index](README.md).'];
+    if (names.length === 0)
+        return `${[...lines, '', '_none_'].join('\n')}\n`;
+    for (const name of names) {
+        lines.push('', heading(2, `\`${name}\``), ...snapshot.enums[name].values.map((value) => `- \`${value}\``));
+    }
+    return `${lines.join('\n')}\n`;
+}
+function renderExtensionsDocument(snapshot) {
+    const names = Object.keys(snapshot.extensions).toSorted((left, right) => left.localeCompare(right));
+    const lines = [
+        heading(1, 'Extensions'),
+        '',
+        '[Schema index](README.md).',
+        '',
+        '| Extension | Version |',
+        '| --- | --- |',
+    ];
+    lines.push(...names.map((name) => `| \`${name}\` | ${snapshot.extensions[name].version} |`));
+    return `${lines.join('\n')}\n`;
+}
+function renderFunctionSignature(definition) {
+    const lines = definition.split('\n');
+    const bodyStart = lines.findIndex((line) => line.trim().startsWith('AS $'));
+    return (bodyStart === -1 ? lines : lines.slice(0, bodyStart)).join('\n');
+}
+function renderFunctionsDocument(snapshot) {
+    const names = Object.keys(snapshot.functions).toSorted((left, right) => left.localeCompare(right));
+    const lines = [heading(1, 'Functions'), '', '[Schema index](README.md).'];
+    if (names.length === 0)
+        return `${[...lines, '', '_none_'].join('\n')}\n`;
+    for (const name of names) {
+        lines.push('', heading(2, `\`${name}\``), '', '```sql', renderFunctionSignature(snapshot.functions[name].definition), '```');
+    }
+    return `${lines.join('\n')}\n`;
+}
+function renderPoliciesDocument(snapshot) {
+    const names = Object.keys(snapshot.policies).toSorted((left, right) => left.localeCompare(right));
+    const lines = [heading(1, 'Row-Level Security Policies'), '', '[Schema index](README.md).'];
+    if (names.length === 0)
+        return `${[...lines, '', '_none_'].join('\n')}\n`;
+    for (const name of names) {
+        const policy = snapshot.policies[name];
+        lines.push('', heading(2, `\`${name}\``), `- command: \`${policy.command}\``, `- roles: ${policy.pgRoles.map((role) => `\`${role}\``).join(', ')}`, `- using: ${policy.using ? `\`${policy.using}\`` : '_none_'}`, `- with check: ${policy.withCheck ? `\`${policy.withCheck}\`` : '_none_'}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function markdownTablePath(name) {
+    if (!SAFE_TABLE_FILENAME.test(name)) {
+        throw new Error(`Cannot generate a safe Markdown filename for PostgreSQL table ${JSON.stringify(name)}.`);
+    }
+    return `tables/${name}.md`;
+}
+function renderSchemaIndex(tableNames) {
+    const lines = [
+        '# PostgreSQL Schema Snapshot',
+        '',
+        'Generated schema snapshot. Do not hand-edit. Full function bodies live only in the companion [`schema.json`](../schema.json).',
+        '',
+        '## Tables',
+        '',
+        ...tableNames.map((name) => `- [\`${name}\`](tables/${name}.md)`),
+        '',
+        '## Other schema objects',
+        '',
+        '- [Views](views.md)',
+        '- [Enums](enums.md)',
+        '- [Extensions](extensions.md)',
+        '- [Functions](functions.md)',
+        '- [Row-Level Security Policies](policies.md)',
+    ];
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Renders deterministic, focused Markdown files from the same snapshot serialized to schema.json.
+ * Each table receives one safe filename and exactly one column table; the index directly links all
+ * generated leaves.
+ */
+export function renderSchemaMarkdown(snapshot) {
+    const tableNames = Object.keys(snapshot.tables).toSorted((left, right) => left.localeCompare(right));
+    const files = new Map();
+    files.set('README.md', renderSchemaIndex(tableNames));
+    for (const name of tableNames) {
+        files.set(markdownTablePath(name), renderTableDocument(name, snapshot.tables[name]));
+    }
+    files.set('views.md', renderViewsDocument(snapshot));
+    files.set('enums.md', renderEnumsDocument(snapshot));
+    files.set('extensions.md', renderExtensionsDocument(snapshot));
+    files.set('functions.md', renderFunctionsDocument(snapshot));
+    files.set('policies.md', renderPoliciesDocument(snapshot));
+    return files;
+}

package/dist/pg-schema-snapshot/render-tables.d.mts

@@ -0,0 +1,2 @@
+import type { SchemaTableSnapshot } from './types.mts';
+export declare function renderTableDocument(name: string, table: SchemaTableSnapshot): string;

package/dist/pg-schema-snapshot/render-tables.mjs

@@ -0,0 +1,55 @@
+function heading(level, text) {
+    return `${'#'.repeat(level)} ${text}`;
+}
+function renderPartitionLine(table) {
+    if (!table.partition)
+        return `Not partitioned — growth: ${table.growth}.`;
+    const { strategy, key, children, retentionOwner, accessClass } = table.partition;
+    const retention = retentionOwner ? `retention owner \`${retentionOwner}\`` : 'no retention owner';
+    return `${strategy} partitioned on \`${key}\` (children: ${children}, ${retention}, access class: ${accessClass}, growth: ${table.growth}).`;
+}
+function oneLine(value) {
+    return value.replaceAll(/\r?\n/g, ' ');
+}
+function renderColumnRow(name, column) {
+    const defaultValue = column.generatedExpression ?? column.defaultExpression;
+    const cells = [
+        `\`${name}\``,
+        `\`${column.type}\``,
+        column.nullable ? 'yes' : 'no',
+        defaultValue ? `\`${oneLine(defaultValue)}\`` : '',
+        column.identity ?? '',
+        column.generated ?? '',
+        column.collation ?? '',
+        column.comment ? oneLine(column.comment) : '',
+    ];
+    return `| ${cells.map((cell) => cell.replaceAll('|', '\\|')).join(' | ')} |`;
+}
+function renderNamedDefinitionList(entries, emptyText) {
+    const names = Object.keys(entries).toSorted((left, right) => left.localeCompare(right));
+    if (names.length === 0)
+        return [emptyText];
+    return names.map((name) => {
+        const entry = entries[name];
+        return `- \`${name}\`: \`${typeof entry === 'string' ? entry : entry.definition}\``;
+    });
+}
+export function renderTableDocument(name, table) {
+    const lines = [
+        heading(1, `Table \`${name}\``),
+        '',
+        'Generated schema snapshot. Do not hand-edit. [Schema index](../README.md).',
+    ];
+    if (table.comment)
+        lines.push('', table.comment);
+    lines.push('', renderPartitionLine(table));
+    const columnNames = Object.keys(table.columns).toSorted((left, right) => table.columns[left].ordinalPosition - table.columns[right].ordinalPosition);
+    lines.push('', '| Column | Type | Nullable | Default | Identity | Generated | Collation | Comment |', '| --- | --- | --- | --- | --- | --- | --- | --- |', ...columnNames.map((columnName) => renderColumnRow(columnName, table.columns[columnName])));
+    lines.push('', `**Primary key:** ${table.primaryKey ? `\`${table.primaryKey.definition}\`` : '_none_'}`);
+    lines.push('', '**Unique constraints:**', ...renderNamedDefinitionList(table.uniqueConstraints, '_none_'));
+    lines.push('', '**Check constraints:**', ...renderNamedDefinitionList(table.checkConstraints, '_none_'));
+    lines.push('', '**Foreign keys:**', ...renderNamedDefinitionList(table.foreignKeys, '_none_'));
+    lines.push('', '**Indexes:**', ...renderNamedDefinitionList(table.indexes, '_none_'));
+    lines.push('', '**Triggers:**', ...renderNamedDefinitionList(table.triggers, '_none_'));
+    return `${lines.join('\n')}\n`;
+}

package/dist/pg-schema-snapshot/snapshot-build-utils.d.mts

@@ -0,0 +1,2 @@
+export declare function groupBy<Row, Key>(rows: Row[], key: (row: Row) => Key): Map<Key, Row[]>;
+export declare function keyed<RecordValue>(entries: Iterable<[string, RecordValue]>): Record<string, RecordValue>;

package/dist/pg-schema-snapshot/snapshot-build-utils.mjs

@@ -0,0 +1,15 @@
+export function groupBy(rows, key) {
+    const groups = new Map();
+    for (const row of rows) {
+        const groupKey = key(row);
+        const group = groups.get(groupKey);
+        if (group)
+            group.push(row);
+        else
+            groups.set(groupKey, [row]);
+    }
+    return groups;
+}
+export function keyed(entries) {
+    return Object.fromEntries([...entries].toSorted(([left], [right]) => left.localeCompare(right)));
+}

package/dist/pg-schema-snapshot/snapshot.test-helpers.d.mts

@@ -0,0 +1,11 @@
+import type { SchemaCatalog } from './catalog-queries.mts';
+import type { PartitionPolicy, SchemaGrowthMaps, SchemaSnapshot, SchemaTableSnapshot } from './types.mts';
+export declare function emptyCatalog(): SchemaCatalog;
+export declare function catalog(overrides?: Partial<SchemaCatalog>): SchemaCatalog;
+export declare function emptyGrowth(): SchemaGrowthMaps;
+export declare const WIDGETS_RANGE_POLICY: PartitionPolicy;
+export declare function widgetsGrowth(overrides?: Partial<SchemaGrowthMaps>): SchemaGrowthMaps;
+export declare function emptySnapshot(): SchemaSnapshot;
+export declare function widgetsTable(overrides?: Partial<SchemaTableSnapshot>): SchemaTableSnapshot;
+export declare function widgetsCatalogTable(relkind?: 'p' | 'r'): SchemaCatalog['tables'][number];
+export declare function columnRow(tableName: string, columnName: string, overrides?: Partial<SchemaCatalog['columns'][number]>): SchemaCatalog['columns'][number];

package/dist/pg-schema-snapshot/snapshot.test-helpers.mjs

@@ -0,0 +1,101 @@
+export function emptyCatalog() {
+    return {
+        tables: [],
+        columns: [],
+        constraints: [],
+        indexes: [],
+        triggers: [],
+        enums: [],
+        views: [],
+        extensions: [],
+        functions: [],
+        policies: [],
+    };
+}
+export function catalog(overrides = {}) {
+    return { ...emptyCatalog(), ...overrides };
+}
+export function emptyGrowth() {
+    return {
+        partitionPolicies: new Map(),
+        unboundedUnpartitionedTables: new Set(),
+    };
+}
+export const WIDGETS_RANGE_POLICY = {
+    strategy: 'RANGE',
+    key: 'id',
+    children: 'monthly',
+    retentionOwner: 'cleanup',
+    accessClass: 'retention-window',
+};
+export function widgetsGrowth(overrides = {}) {
+    return {
+        partitionPolicies: new Map([['widgets', WIDGETS_RANGE_POLICY]]),
+        unboundedUnpartitionedTables: new Set(['events']),
+        ...overrides,
+    };
+}
+export function emptySnapshot() {
+    return {
+        formatVersion: 2,
+        tables: {},
+        views: {},
+        enums: {},
+        extensions: {},
+        functions: {},
+        policies: {},
+    };
+}
+export function widgetsTable(overrides = {}) {
+    return {
+        columns: {
+            id: {
+                type: 'uuid',
+                nullable: false,
+                defaultExpression: null,
+                generatedExpression: null,
+                identity: null,
+                generated: null,
+                collation: null,
+                comment: null,
+                ordinalPosition: 1,
+            },
+        },
+        relationKind: 'table',
+        primaryKey: null,
+        uniqueConstraints: {},
+        checkConstraints: {},
+        foreignKeys: {},
+        indexes: {},
+        triggers: {},
+        comment: null,
+        physicalPartition: null,
+        partition: null,
+        growth: 'bounded',
+        ...overrides,
+    };
+}
+export function widgetsCatalogTable(relkind = 'r') {
+    return {
+        table_name: 'widgets',
+        relkind,
+        partition_strategy: relkind === 'p' ? 'r' : '',
+        partition_key: relkind === 'p' ? 'RANGE (created_at)' : null,
+        comment: null,
+    };
+}
+export function columnRow(tableName, columnName, overrides = {}) {
+    return {
+        table_name: tableName,
+        column_name: columnName,
+        data_type: 'uuid',
+        nullable: false,
+        default_expression: null,
+        identity: '',
+        generated: '',
+        collation: null,
+        comment: null,
+        ordinal_position: 1,
+        ...overrides,
+    };
+}

package/dist/pg-schema-snapshot/table-snapshot-columns.d.mts

@@ -0,0 +1,3 @@
+import type { CatalogColumnRow } from './catalog-queries.mts';
+import type { SchemaColumnSnapshot } from './types.mts';
+export declare function buildTableColumns(rows: CatalogColumnRow[]): Record<string, SchemaColumnSnapshot>;

package/dist/pg-schema-snapshot/table-snapshot-columns.mjs

@@ -0,0 +1,33 @@
+function toIdentity(code) {
+    if (code === 'a')
+        return 'always';
+    if (code === 'd')
+        return 'by default';
+    return null;
+}
+function toGenerated(code) {
+    if (code === 's')
+        return 'stored';
+    if (code === 'v')
+        return 'virtual';
+    return null;
+}
+export function buildTableColumns(rows) {
+    const columns = {};
+    for (const column of rows.toSorted((left, right) => left.ordinal_position - right.ordinal_position ||
+        left.column_name.localeCompare(right.column_name))) {
+        const generated = toGenerated(column.generated);
+        columns[column.column_name] = {
+            type: column.data_type,
+            nullable: column.nullable,
+            defaultExpression: generated ? null : column.default_expression,
+            generatedExpression: generated ? column.default_expression : null,
+            identity: toIdentity(column.identity),
+            generated,
+            collation: column.collation,
+            comment: column.comment,
+            ordinalPosition: column.ordinal_position,
+        };
+    }
+    return columns;
+}

package/dist/pg-schema-snapshot/table-snapshot-constraints.d.mts

@@ -0,0 +1,7 @@
+import type { CatalogConstraintRow } from './catalog-queries.mts';
+import type { SchemaColumnSnapshot, SchemaTableSnapshot } from './types.mts';
+export declare function buildTableConstraints({ tableName, columns, constraints, }: {
+    tableName: string;
+    columns: Record<string, SchemaColumnSnapshot>;
+    constraints: CatalogConstraintRow[];
+}): Pick<SchemaTableSnapshot, 'primaryKey' | 'uniqueConstraints' | 'checkConstraints' | 'foreignKeys'>;

package/dist/pg-schema-snapshot/table-snapshot-constraints.mjs

@@ -0,0 +1,55 @@
+import { keyed } from './snapshot-build-utils.mjs';
+function assertConstraintColumns(tableName, columns, constraint) {
+    for (const column of constraint.columns) {
+        if (!columns[column]) {
+            throw new Error(`Constraint "${constraint.constraint_name}" on "${tableName}" references unknown column "${column}".`);
+        }
+    }
+}
+function foreignKeySnapshot(tableName, columns, constraint) {
+    assertConstraintColumns(tableName, columns, constraint);
+    if (!constraint.referenced_table || !constraint.on_update || !constraint.on_delete) {
+        throw new Error(`Foreign key "${constraint.constraint_name}" is missing referenced-table facts.`);
+    }
+    return {
+        definition: constraint.definition,
+        columns: constraint.columns,
+        referencedTable: constraint.referenced_table,
+        referencedColumns: constraint.referenced_columns,
+        onUpdate: constraint.on_update,
+        onDelete: constraint.on_delete,
+        validated: constraint.validated,
+    };
+}
+export function buildTableConstraints({ tableName, columns, constraints, }) {
+    const primaryConstraint = constraints.find((constraint) => constraint.contype === 'p');
+    if (primaryConstraint)
+        assertConstraintColumns(tableName, columns, primaryConstraint);
+    const primaryKey = primaryConstraint
+        ? { definition: primaryConstraint.definition, columns: primaryConstraint.columns }
+        : null;
+    const uniqueConstraints = {};
+    const checkConstraints = {};
+    const foreignKeys = {};
+    for (const constraint of constraints) {
+        if (constraint.contype === 'u') {
+            assertConstraintColumns(tableName, columns, constraint);
+            uniqueConstraints[constraint.constraint_name] = {
+                definition: constraint.definition,
+                columns: constraint.columns,
+            };
+        }
+        if (constraint.contype === 'c') {
+            checkConstraints[constraint.constraint_name] = constraint.definition;
+        }
+        if (constraint.contype === 'f') {
+            foreignKeys[constraint.constraint_name] = foreignKeySnapshot(tableName, columns, constraint);
+        }
+    }
+    return {
+        primaryKey,
+        uniqueConstraints: keyed(Object.entries(uniqueConstraints)),
+        checkConstraints: keyed(Object.entries(checkConstraints)),
+        foreignKeys: keyed(Object.entries(foreignKeys)),
+    };
+}

package/dist/pg-schema-snapshot/table-snapshot.d.mts

@@ -0,0 +1,10 @@
+import type { SchemaCatalog } from './catalog-queries.mts';
+import type { SchemaGrowthMaps, SchemaTableSnapshot } from './types.mts';
+export declare function buildTableSnapshots({ catalog, columnsByTable, constraintsByTable, indexesByTable, triggersByTable, growth, }: {
+    catalog: SchemaCatalog;
+    columnsByTable: Map<string, SchemaCatalog['columns']>;
+    constraintsByTable: Map<string, SchemaCatalog['constraints']>;
+    indexesByTable: Map<string, SchemaCatalog['indexes']>;
+    triggersByTable: Map<string, SchemaCatalog['triggers']>;
+    growth: SchemaGrowthMaps;
+}): Record<string, SchemaTableSnapshot>;

package/dist/pg-schema-snapshot/table-snapshot.mjs

@@ -0,0 +1,99 @@
+import { keyed } from './snapshot-build-utils.mjs';
+import { buildTableColumns } from './table-snapshot-columns.mjs';
+import { buildTableConstraints } from './table-snapshot-constraints.mjs';
+function physicalPartition({ partition_key: key, partition_strategy: strategy, }) {
+    if (strategy === '')
+        return null;
+    if (!key)
+        throw new Error('A physically partitioned table must have a partition key.');
+    if (strategy === 'h')
+        return { strategy: 'hash', key };
+    if (strategy === 'l')
+        return { strategy: 'list', key };
+    return { strategy: 'range', key };
+}
+function indexSnapshot(index) {
+    return {
+        definition: index.definition,
+        accessMethod: index.access_method,
+        unique: index.unique,
+        primary: index.primary,
+        constraintBacked: index.constraint_backed,
+        valid: index.valid,
+        ready: index.ready,
+        keys: index.keys.map((key) => ({
+            column: key.column,
+            expression: key.expression,
+            opclass: key.opclass,
+            descending: key.descending,
+            nullsFirst: key.nulls_first,
+        })),
+        includedColumns: index.included_columns,
+        predicate: index.predicate,
+    };
+}
+function triggersSnapshot(rows) {
+    return keyed(rows.map((trigger) => [trigger.trigger_name, trigger.definition]));
+}
+function assertKnownTableRows(catalog) {
+    const tableNames = new Set(catalog.tables.map((table) => table.table_name));
+    const rows = [...catalog.columns, ...catalog.constraints, ...catalog.indexes, ...catalog.triggers];
+    for (const row of rows) {
+        if (!tableNames.has(row.table_name)) {
+            throw new Error(`Catalog row references unknown table "${row.table_name}".`);
+        }
+    }
+}
+function assertNoDuplicateNames(rows, name) {
+    const names = new Set();
+    for (const row of rows) {
+        const key = `${row.table_name}.${String(row[name])}`;
+        if (names.has(key))
+            throw new Error(`Catalog contains duplicate ${String(name)} "${key}".`);
+        names.add(key);
+    }
+}
+function assertCatalogConsistency(catalog) {
+    assertKnownTableRows(catalog);
+    assertNoDuplicateNames(catalog.columns, 'column_name');
+    assertNoDuplicateNames(catalog.constraints, 'constraint_name');
+    assertNoDuplicateNames(catalog.indexes, 'index_name');
+    assertNoDuplicateNames(catalog.triggers, 'trigger_name');
+}
+export function buildTableSnapshots({ catalog, columnsByTable, constraintsByTable, indexesByTable, triggersByTable, growth, }) {
+    assertCatalogConsistency(catalog);
+    const tables = {};
+    for (const table of catalog.tables.toSorted((left, right) => left.table_name.localeCompare(right.table_name))) {
+        const partition = growth.partitionPolicies.get(table.table_name) ?? null;
+        if (table.relkind === 'p' && !partition) {
+            throw new Error(`Table "${table.table_name}" is partitioned (relkind = 'p') but has no partitionPolicies entry. ` +
+                'Every partitioned table must be classified.');
+        }
+        const physical = physicalPartition(table);
+        if ((table.relkind === 'p') !== (physical !== null)) {
+            throw new Error(`Table "${table.table_name}" has inconsistent relation kind and physical partition facts.`);
+        }
+        const columns = buildTableColumns(columnsByTable.get(table.table_name) ?? []);
+        tables[table.table_name] = {
+            relationKind: table.relkind === 'p' ? 'partitioned table' : 'table',
+            columns,
+            ...buildTableConstraints({
+                tableName: table.table_name,
+                columns,
+                constraints: constraintsByTable.get(table.table_name) ?? [],
+            }),
+            indexes: keyed((indexesByTable.get(table.table_name) ?? []).map((index) => [
+                index.index_name,
+                indexSnapshot(index),
+            ])),
+            triggers: triggersSnapshot(triggersByTable.get(table.table_name) ?? []),
+            comment: table.comment,
+            physicalPartition: physical,
+            partition,
+            growth: partition || growth.unboundedUnpartitionedTables.has(table.table_name)
+                ? 'unbounded'
+                : 'bounded',
+        };
+    }
+    return tables;
+}