vouchington-tooling 0.0.9 → 0.0.11

package/dist/pg-schema-snapshot/catalog-objects.d.mts

@@ -0,0 +1,34 @@
+import type { CatalogQuery } from './types.mts';
+export type CatalogEnumValueRow = {
+    enum_name: string;
+    value: string;
+    sort_order: number;
+};
+export declare function readEnums(query: CatalogQuery): Promise<CatalogEnumValueRow[]>;
+export type CatalogViewRow = {
+    view_name: string;
+    materialized: boolean;
+    definition: string;
+    comment: string | null;
+};
+export declare function readViews(query: CatalogQuery): Promise<CatalogViewRow[]>;
+export type CatalogExtensionRow = {
+    extension_name: string;
+    version: string;
+};
+export declare function readExtensions(query: CatalogQuery): Promise<CatalogExtensionRow[]>;
+export type CatalogFunctionRow = {
+    function_name: string;
+    identity_arguments: string;
+    definition: string;
+};
+export declare function readFunctions(query: CatalogQuery): Promise<CatalogFunctionRow[]>;
+export type CatalogPolicyRow = {
+    table_name: string;
+    policy_name: string;
+    command: string;
+    pg_roles: string[];
+    using_expression: string | null;
+    with_check_expression: string | null;
+};
+export declare function readPolicies(query: CatalogQuery): Promise<CatalogPolicyRow[]>;

package/dist/pg-schema-snapshot/catalog-objects.mjs

@@ -0,0 +1,64 @@
+import { EXCLUDE_EXTENSION_OWNED } from './catalog-shared.mjs';
+export async function readEnums(query) {
+    const { rows } = await query(`/* readSchemaSnapshotEnums */
+      SELECT
+        target.typname AS enum_name,
+        pg_enum.enumlabel AS value,
+        pg_enum.enumsortorder AS sort_order
+      FROM pg_enum
+      JOIN pg_type target ON target.oid = pg_enum.enumtypid
+      JOIN pg_namespace ON pg_namespace.oid = target.typnamespace
+      WHERE pg_namespace.nspname = 'public'
+        AND ${EXCLUDE_EXTENSION_OWNED}
+      ORDER BY enum_name, sort_order`);
+    return rows;
+}
+export async function readViews(query) {
+    const { rows } = await query(`/* readSchemaSnapshotViews */
+      SELECT
+        target.relname AS view_name,
+        target.relkind = 'm' AS materialized,
+        pg_get_viewdef(target.oid) AS definition,
+        obj_description(target.oid, 'pg_class') AS comment
+      FROM pg_class target
+      JOIN pg_namespace ON pg_namespace.oid = target.relnamespace
+      WHERE pg_namespace.nspname = 'public'
+        AND target.relkind = ANY($1)
+        AND ${EXCLUDE_EXTENSION_OWNED}
+      ORDER BY view_name`, [['v', 'm']]);
+    return rows;
+}
+export async function readExtensions(query) {
+    const { rows } = await query(`/* readSchemaSnapshotExtensions */
+      SELECT extname AS extension_name, extversion AS version
+      FROM pg_extension
+      ORDER BY extension_name`);
+    return rows;
+}
+export async function readFunctions(query) {
+    const { rows } = await query(`/* readSchemaSnapshotFunctions */
+      SELECT
+        target.proname AS function_name,
+        pg_get_function_identity_arguments(target.oid) AS identity_arguments,
+        pg_get_functiondef(target.oid) AS definition
+      FROM pg_proc target
+      JOIN pg_namespace ON pg_namespace.oid = target.pronamespace
+      WHERE pg_namespace.nspname = 'public'
+        AND ${EXCLUDE_EXTENSION_OWNED}
+      ORDER BY function_name, identity_arguments`);
+    return rows;
+}
+export async function readPolicies(query) {
+    const { rows } = await query(`/* readSchemaSnapshotPolicies */
+      SELECT
+        tablename AS table_name,
+        policyname AS policy_name,
+        cmd AS command,
+        roles AS pg_roles,
+        qual AS using_expression,
+        with_check AS with_check_expression
+      FROM pg_policies
+      WHERE schemaname = 'public'
+      ORDER BY table_name, policy_name`);
+    return rows;
+}

package/dist/pg-schema-snapshot/catalog-queries.d.mts

@@ -0,0 +1,20 @@
+import { type CatalogEnumValueRow, type CatalogExtensionRow, type CatalogFunctionRow, type CatalogPolicyRow, type CatalogViewRow, readEnums, readExtensions, readFunctions, readPolicies, readViews } from './catalog-objects.mts';
+import { type CatalogConstraintRow, readConstraints } from './catalog-table-constraints.mts';
+import { type CatalogIndexRow, type CatalogTriggerRow, readIndexes, readTriggers } from './catalog-table-indexes.mts';
+import { type CatalogColumnRow, type CatalogTableRow, readColumns, readTables } from './catalog-tables.mts';
+import type { CatalogQuery } from './types.mts';
+export { readColumns, readConstraints, readEnums, readExtensions, readFunctions, readIndexes, readPolicies, readTables, readTriggers, readViews, };
+export type { CatalogColumnRow, CatalogConstraintRow, CatalogEnumValueRow, CatalogExtensionRow, CatalogFunctionRow, CatalogIndexRow, CatalogPolicyRow, CatalogTableRow, CatalogTriggerRow, CatalogViewRow, };
+export type SchemaCatalog = {
+    tables: CatalogTableRow[];
+    columns: CatalogColumnRow[];
+    constraints: CatalogConstraintRow[];
+    indexes: CatalogIndexRow[];
+    triggers: CatalogTriggerRow[];
+    enums: CatalogEnumValueRow[];
+    views: CatalogViewRow[];
+    extensions: CatalogExtensionRow[];
+    functions: CatalogFunctionRow[];
+    policies: CatalogPolicyRow[];
+};
+export declare function readSchemaCatalog(query: CatalogQuery): Promise<SchemaCatalog>;

package/dist/pg-schema-snapshot/catalog-queries.mjs

@@ -0,0 +1,31 @@
+import { readEnums, readExtensions, readFunctions, readPolicies, readViews, } from './catalog-objects.mjs';
+import { readConstraints } from './catalog-table-constraints.mjs';
+import { readIndexes, readTriggers, } from './catalog-table-indexes.mjs';
+import { readColumns, readTables, } from './catalog-tables.mjs';
+export { readColumns, readConstraints, readEnums, readExtensions, readFunctions, readIndexes, readPolicies, readTables, readTriggers, readViews, };
+export async function readSchemaCatalog(query) {
+    const [tables, columns, constraints, indexes, triggers, enums, views, extensions, functions, policies,] = await Promise.all([
+        readTables(query),
+        readColumns(query),
+        readConstraints(query),
+        readIndexes(query),
+        readTriggers(query),
+        readEnums(query),
+        readViews(query),
+        readExtensions(query),
+        readFunctions(query),
+        readPolicies(query),
+    ]);
+    return {
+        tables,
+        columns,
+        constraints,
+        indexes,
+        triggers,
+        enums,
+        views,
+        extensions,
+        functions,
+        policies,
+    };
+}

package/dist/pg-schema-snapshot/catalog-shared.d.mts

@@ -0,0 +1,3 @@
+export declare const TABLE_RELKINDS: string[];
+export declare const EXCLUDE_EXTENSION_OWNED = "NOT EXISTS (\n        SELECT 1 FROM pg_depend\n        WHERE pg_depend.objid = target.oid AND pg_depend.deptype = 'e'\n      )";
+export declare const EXCLUDE_PARTITION_CHILDREN = "NOT EXISTS (\n        SELECT 1 FROM pg_inherits\n        WHERE pg_inherits.inhrelid = target.oid\n      )";

package/dist/pg-schema-snapshot/catalog-shared.mjs

@@ -0,0 +1,19 @@
+// Ordinary tables ('r') and partitioned-table parents ('p'). Partition children always inherit
+// from a parent (pg_inherits), so every query below excludes rows owned by an inhrelid — that is
+// what keeps date-derived partition children (e.g. `items__p_2026_07`) out of a snapshot that must
+// be identical regardless of when it was generated. Constraints need the additional conparentid
+// filter in catalog-table-constraints.mts because PostgreSQL can derive a row that remains owned
+// by a logical parent while referencing a physical child.
+export const TABLE_RELKINDS = ['r', 'p'];
+// `NOT EXISTS (SELECT 1 FROM pg_depend WHERE objid = <oid> AND deptype = 'e')` excludes objects
+// owned by an extension (e.g. the `pg_stat_statements`/`pg_stat_statements_info` views created by
+// the pg_stat_statements extension in the public schema). Without it, extension upgrades would
+// move the snapshot even though no application DDL changed.
+export const EXCLUDE_EXTENSION_OWNED = `NOT EXISTS (
+        SELECT 1 FROM pg_depend
+        WHERE pg_depend.objid = target.oid AND pg_depend.deptype = 'e'
+      )`;
+export const EXCLUDE_PARTITION_CHILDREN = `NOT EXISTS (
+        SELECT 1 FROM pg_inherits
+        WHERE pg_inherits.inhrelid = target.oid
+      )`;

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

@@ -0,0 +1,14 @@
+import type { CatalogQuery } from './types.mts';
+export type CatalogConstraintRow = {
+    table_name: string;
+    constraint_name: string;
+    contype: 'c' | 'f' | 'p' | 'u';
+    definition: string;
+    columns: string[];
+    referenced_table: string | null;
+    referenced_columns: string[];
+    on_update: 'no action' | 'restrict' | 'cascade' | 'set null' | 'set default' | null;
+    on_delete: 'no action' | 'restrict' | 'cascade' | 'set null' | 'set default' | null;
+    validated: boolean;
+};
+export declare function readConstraints(query: CatalogQuery): Promise<CatalogConstraintRow[]>;

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

@@ -0,0 +1,54 @@
+import { EXCLUDE_EXTENSION_OWNED, EXCLUDE_PARTITION_CHILDREN, TABLE_RELKINDS, } from './catalog-shared.mjs';
+export async function readConstraints(query) {
+    const { rows } = await query(`/* readSchemaSnapshotConstraints */
+      SELECT
+        target.relname AS table_name,
+        pg_constraint.conname AS constraint_name,
+        pg_constraint.contype AS contype,
+        pg_get_constraintdef(pg_constraint.oid) AS definition,
+        to_jsonb(ARRAY(
+          SELECT pg_attribute.attname
+          FROM unnest(pg_constraint.conkey) WITH ORDINALITY AS key_column(attnum, position)
+          JOIN pg_attribute
+            ON pg_attribute.attrelid = target.oid AND pg_attribute.attnum = key_column.attnum
+          ORDER BY key_column.position
+        )) AS columns,
+        referenced.relname AS referenced_table,
+        to_jsonb(ARRAY(
+          SELECT pg_attribute.attname
+          FROM unnest(pg_constraint.confkey) WITH ORDINALITY AS key_column(attnum, position)
+          JOIN pg_attribute
+            ON pg_attribute.attrelid = referenced.oid
+            AND pg_attribute.attnum = key_column.attnum
+          ORDER BY key_column.position
+        )) AS referenced_columns,
+        CASE pg_constraint.confupdtype
+          WHEN 'a' THEN 'no action'
+          WHEN 'r' THEN 'restrict'
+          WHEN 'c' THEN 'cascade'
+          WHEN 'n' THEN 'set null'
+          WHEN 'd' THEN 'set default'
+          ELSE NULL
+        END AS on_update,
+        CASE pg_constraint.confdeltype
+          WHEN 'a' THEN 'no action'
+          WHEN 'r' THEN 'restrict'
+          WHEN 'c' THEN 'cascade'
+          WHEN 'n' THEN 'set null'
+          WHEN 'd' THEN 'set default'
+          ELSE NULL
+        END AS on_delete,
+        pg_constraint.convalidated AS validated
+      FROM pg_constraint
+      JOIN pg_class target ON target.oid = pg_constraint.conrelid
+      JOIN pg_namespace ON pg_namespace.oid = target.relnamespace
+      LEFT JOIN pg_class referenced ON referenced.oid = pg_constraint.confrelid
+      WHERE pg_namespace.nspname = 'public'
+        AND target.relkind = ANY($1)
+        AND pg_constraint.contype = ANY($2)
+        AND pg_constraint.conparentid = 0
+        AND ${EXCLUDE_PARTITION_CHILDREN}
+        AND ${EXCLUDE_EXTENSION_OWNED}
+      ORDER BY table_name, contype, constraint_name`, [TABLE_RELKINDS, ['p', 'u', 'c', 'f']]);
+    return rows;
+}

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

@@ -0,0 +1,30 @@
+import type { CatalogQuery } from './types.mts';
+export type CatalogIndexRow = {
+    table_name: string;
+    index_name: string;
+    definition: string;
+    access_method: string;
+    unique: boolean;
+    primary: boolean;
+    constraint_backed: boolean;
+    valid: boolean;
+    ready: boolean;
+    keys: CatalogIndexKeyRow[];
+    included_columns: string[];
+    predicate: string | null;
+};
+type CatalogIndexKeyRow = {
+    column: string | null;
+    expression: string;
+    opclass: string;
+    descending: boolean;
+    nulls_first: boolean;
+};
+export declare function readIndexes(query: CatalogQuery): Promise<CatalogIndexRow[]>;
+export type CatalogTriggerRow = {
+    table_name: string;
+    trigger_name: string;
+    definition: string;
+};
+export declare function readTriggers(query: CatalogQuery): Promise<CatalogTriggerRow[]>;
+export {};

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

@@ -0,0 +1,81 @@
+import { EXCLUDE_EXTENSION_OWNED, EXCLUDE_PARTITION_CHILDREN, TABLE_RELKINDS, } from './catalog-shared.mjs';
+export async function readIndexes(query) {
+    const { rows } = await query(`/* readSchemaSnapshotIndexes */
+      SELECT
+        target.relname AS table_name,
+        index_relation.relname AS index_name,
+        pg_get_indexdef(pg_index.indexrelid) AS definition,
+        pg_am.amname AS access_method,
+        pg_index.indisunique AS unique,
+        pg_index.indisprimary AS primary,
+        EXISTS (
+          SELECT 1 FROM pg_constraint WHERE pg_constraint.conindid = pg_index.indexrelid
+        ) AS constraint_backed,
+        pg_index.indisvalid AS valid,
+        pg_index.indisready AS ready,
+        COALESCE(
+          jsonb_agg(
+            jsonb_build_object(
+              'column', pg_attribute.attname,
+              'expression', pg_get_indexdef(pg_index.indexrelid, key_column.position::integer, true),
+              'opclass', pg_opclass.opcname,
+              'descending', (pg_index.indoption[(key_column.position - 1)::integer] & 1) <> 0,
+              'nulls_first', (pg_index.indoption[(key_column.position - 1)::integer] & 2) <> 0
+            )
+            ORDER BY key_column.position
+          ) FILTER (WHERE key_column.position <= pg_index.indnkeyatts),
+          '[]'::jsonb
+        ) AS keys,
+        COALESCE(
+          jsonb_agg(pg_attribute.attname ORDER BY key_column.position)
+            FILTER (WHERE key_column.position > pg_index.indnkeyatts),
+          '[]'::jsonb
+        ) AS included_columns,
+        pg_get_expr(pg_index.indpred, pg_index.indrelid) AS predicate
+      FROM pg_index
+      JOIN pg_class index_relation ON index_relation.oid = pg_index.indexrelid
+      JOIN pg_class target ON target.oid = pg_index.indrelid
+      JOIN pg_namespace ON pg_namespace.oid = target.relnamespace
+      JOIN pg_am ON pg_am.oid = index_relation.relam
+      LEFT JOIN LATERAL unnest(pg_index.indkey) WITH ORDINALITY AS key_column(attnum, position)
+        ON true
+      LEFT JOIN pg_attribute
+        ON pg_attribute.attrelid = target.oid AND pg_attribute.attnum = key_column.attnum
+      LEFT JOIN pg_opclass
+        ON pg_opclass.oid = pg_index.indclass[(key_column.position - 1)::integer]
+      WHERE pg_namespace.nspname = 'public'
+        AND target.relkind = ANY($1)
+        AND ${EXCLUDE_PARTITION_CHILDREN}
+        AND ${EXCLUDE_EXTENSION_OWNED}
+      GROUP BY
+        target.relname,
+        index_relation.relname,
+        pg_index.indexrelid,
+        pg_am.amname,
+        pg_index.indisunique,
+        pg_index.indisprimary,
+        pg_index.indisvalid,
+        pg_index.indisready,
+        pg_index.indnkeyatts,
+        pg_index.indpred,
+        pg_index.indrelid
+      ORDER BY table_name, index_name`, [TABLE_RELKINDS]);
+    return rows;
+}
+export async function readTriggers(query) {
+    const { rows } = await query(`/* readSchemaSnapshotTriggers */
+      SELECT
+        target.relname AS table_name,
+        pg_trigger.tgname AS trigger_name,
+        pg_get_triggerdef(pg_trigger.oid) AS definition
+      FROM pg_trigger
+      JOIN pg_class target ON target.oid = pg_trigger.tgrelid
+      JOIN pg_namespace ON pg_namespace.oid = target.relnamespace
+      WHERE pg_namespace.nspname = 'public'
+        AND target.relkind = ANY($1)
+        AND NOT pg_trigger.tgisinternal
+        AND ${EXCLUDE_PARTITION_CHILDREN}
+        AND ${EXCLUDE_EXTENSION_OWNED}
+      ORDER BY table_name, trigger_name`, [TABLE_RELKINDS]);
+    return rows;
+}

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

@@ -0,0 +1,22 @@
+import type { CatalogQuery } from './types.mts';
+export type CatalogTableRow = {
+    table_name: string;
+    relkind: 'p' | 'r';
+    partition_strategy: '' | 'h' | 'l' | 'r';
+    partition_key: string | null;
+    comment: string | null;
+};
+export declare function readTables(query: CatalogQuery): Promise<CatalogTableRow[]>;
+export type CatalogColumnRow = {
+    table_name: string;
+    column_name: string;
+    data_type: string;
+    nullable: boolean;
+    default_expression: string | null;
+    identity: '' | 'a' | 'd';
+    generated: '' | 's' | 'v';
+    collation: string | null;
+    comment: string | null;
+    ordinal_position: number;
+};
+export declare function readColumns(query: CatalogQuery): Promise<CatalogColumnRow[]>;

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

@@ -0,0 +1,48 @@
+import { EXCLUDE_EXTENSION_OWNED, EXCLUDE_PARTITION_CHILDREN, TABLE_RELKINDS, } from './catalog-shared.mjs';
+export async function readTables(query) {
+    const { rows } = await query(`/* readSchemaSnapshotTables */
+      SELECT
+        target.relname AS table_name,
+        target.relkind AS relkind,
+        COALESCE(pg_partitioned_table.partstrat, '') AS partition_strategy,
+        pg_get_partkeydef(pg_partitioned_table.partrelid) AS partition_key,
+        obj_description(target.oid, 'pg_class') AS comment
+      FROM pg_class target
+      JOIN pg_namespace ON pg_namespace.oid = target.relnamespace
+      LEFT JOIN pg_partitioned_table ON pg_partitioned_table.partrelid = target.oid
+      WHERE pg_namespace.nspname = 'public'
+        AND target.relkind = ANY($1)
+        AND ${EXCLUDE_PARTITION_CHILDREN}
+        AND ${EXCLUDE_EXTENSION_OWNED}
+      ORDER BY table_name`, [TABLE_RELKINDS]);
+    return rows;
+}
+export async function readColumns(query) {
+    const { rows } = await query(`/* readSchemaSnapshotColumns */
+      SELECT
+        target.relname AS table_name,
+        pg_attribute.attname AS column_name,
+        format_type(pg_attribute.atttypid, pg_attribute.atttypemod) AS data_type,
+        NOT pg_attribute.attnotnull AS nullable,
+        pg_get_expr(pg_attrdef.adbin, pg_attrdef.adrelid) AS default_expression,
+        pg_attribute.attidentity AS identity,
+        pg_attribute.attgenerated AS generated,
+        pg_collation.collname AS collation,
+        col_description(target.oid, pg_attribute.attnum) AS comment,
+        pg_attribute.attnum AS ordinal_position
+      FROM pg_attribute
+      JOIN pg_class target ON target.oid = pg_attribute.attrelid
+      JOIN pg_namespace ON pg_namespace.oid = target.relnamespace
+      LEFT JOIN pg_attrdef
+        ON pg_attrdef.adrelid = pg_attribute.attrelid AND pg_attrdef.adnum = pg_attribute.attnum
+      LEFT JOIN pg_collation
+        ON pg_collation.oid = pg_attribute.attcollation AND pg_collation.collname <> 'default'
+      WHERE pg_namespace.nspname = 'public'
+        AND target.relkind = ANY($1)
+        AND pg_attribute.attnum > 0
+        AND NOT pg_attribute.attisdropped
+        AND ${EXCLUDE_PARTITION_CHILDREN}
+        AND ${EXCLUDE_EXTENSION_OWNED}
+      ORDER BY table_name, ordinal_position`, [TABLE_RELKINDS]);
+    return rows;
+}

package/dist/pg-schema-snapshot/file-safety.d.mts

@@ -0,0 +1,4 @@
+export declare function lstatOrNull(path: string): Promise<import("node:fs").Stats | null>;
+export declare function assertSafeExistingFilePath(root: string, path: string): Promise<void>;
+export declare function ensureSafeParentDirectory(root: string, path: string): Promise<void>;
+export declare function writeGeneratedFile(root: string, path: string, content: string): Promise<void>;

package/dist/pg-schema-snapshot/file-safety.mjs

@@ -0,0 +1,71 @@
+import { lstat, mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+function unsafeSchemaSnapshotPath(path) {
+    return new Error(`Unsafe generated PostgreSQL schema snapshot path: ${path}`);
+}
+export async function lstatOrNull(path) {
+    return lstat(path).catch((error) => 
+    /* v8 ignore next -- non-ENOENT stat failures are host-specific */
+    error.code === 'ENOENT' ? null : Promise.reject(error));
+}
+async function assertSafeDirectory(path, create) {
+    let stats = await lstatOrNull(path);
+    if (stats === null && create) {
+        await mkdir(path).catch((error) => error.code === 'EEXIST' ? undefined : Promise.reject(error));
+        stats = await lstatOrNull(path);
+    }
+    if (stats === null || stats.isSymbolicLink() || !stats.isDirectory()) {
+        throw unsafeSchemaSnapshotPath(path);
+    }
+}
+function relativeSnapshotPath(root, path) {
+    const relativePath = relative(resolve(root), resolve(path));
+    if (relativePath === '' ||
+        relativePath === '..' ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath)) {
+        throw unsafeSchemaSnapshotPath(path);
+    }
+    return relativePath;
+}
+async function assertSafePathComponents(directory, components, create) {
+    const [component, ...remaining] = components;
+    if (component === undefined)
+        return;
+    const path = join(directory, component);
+    const stats = await lstatOrNull(path);
+    if (stats === null && !create)
+        return;
+    await assertSafeDirectory(path, create);
+    await assertSafePathComponents(path, remaining, create);
+}
+async function assertSafeParentDirectories(root, path, create) {
+    const resolvedRoot = resolve(root);
+    const relativePath = relativeSnapshotPath(resolvedRoot, path);
+    await assertSafeDirectory(resolvedRoot, false);
+    await assertSafePathComponents(resolvedRoot, relativePath.split(sep).slice(0, -1), create);
+}
+async function assertSafeFilePath(root, path, create) {
+    await assertSafeParentDirectories(root, path, create);
+    const leaf = await lstatOrNull(path);
+    if (leaf?.isSymbolicLink())
+        throw unsafeSchemaSnapshotPath(path);
+}
+export async function assertSafeExistingFilePath(root, path) {
+    await assertSafeFilePath(root, path, false);
+}
+export async function ensureSafeParentDirectory(root, path) {
+    await assertSafeFilePath(root, path, true);
+}
+export async function writeGeneratedFile(root, path, content) {
+    await ensureSafeParentDirectory(root, path);
+    const temporaryDirectory = await mkdtemp(join(dirname(path), '.schema-snapshot-'));
+    const temporaryPath = join(temporaryDirectory, 'contents');
+    try {
+        await writeFile(temporaryPath, content);
+        await rename(temporaryPath, path);
+    }
+    finally {
+        await rm(temporaryDirectory, { force: true, recursive: true });
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { CatalogQuery, SchemaGrowthMaps, SchemaSnapshot } from './types.mts';
+export declare function stableStringify(value: unknown): string;
+export declare function writeSchemaSnapshot({ snapshot, markdown, root, check, format, stringify, }: {
+    snapshot: SchemaSnapshot;
+    markdown: Map<string, string>;
+    root: string;
+    check?: boolean;
+    format?: (path: string, raw: string) => Promise<string>;
+    stringify?: (value: unknown) => string;
+}): Promise<void>;
+export declare function generateSchemaSnapshot({ query, growth, root, check, format, stringify, }: {
+    query: CatalogQuery;
+    growth: SchemaGrowthMaps;
+    root: string;
+    check?: boolean;
+    format?: (path: string, raw: string) => Promise<string>;
+    stringify?: (value: unknown) => string;
+}): Promise<void>;

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

@@ -0,0 +1,95 @@
+import { readFile, rm } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { buildSchemaSnapshot } from './build-snapshot.mjs';
+import { readSchemaCatalog } from './catalog-queries.mjs';
+import { assertSafeExistingFilePath, ensureSafeParentDirectory, lstatOrNull, writeGeneratedFile, } from './file-safety.mjs';
+import { markdownFilesOnDisk } from './markdown-files.mjs';
+import { renderSchemaMarkdown } from './render-markdown.mjs';
+export function stableStringify(value) {
+    return `${JSON.stringify(sortKeys(value), null, 2)}\n`;
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([key, nested]) => [key, sortKeys(nested)]));
+    }
+    return value;
+}
+async function identityFormat(_path, raw) {
+    return raw;
+}
+function assertSafeMarkdownPath(markdownRoot, path) {
+    const outputPath = resolve(markdownRoot, path);
+    const relativePath = relative(markdownRoot, outputPath);
+    if (isAbsolute(path) ||
+        !path.endsWith('.md') ||
+        relativePath === '' ||
+        relativePath === '..' ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath)) {
+        throw new Error(`Unsafe generated PostgreSQL schema Markdown path: ${path}`);
+    }
+    return outputPath;
+}
+async function schemaSnapshotFiles(snapshot, markdown, root, format, stringify) {
+    const jsonPath = join(root, 'schema.json');
+    const markdownRoot = join(root, 'markdown');
+    const [json, ...formattedMarkdown] = await Promise.all([
+        format(jsonPath, stringify(snapshot)),
+        ...[...markdown].map(async ([path, content]) => {
+            const outputPath = assertSafeMarkdownPath(markdownRoot, path);
+            return [outputPath, await format(outputPath, content)];
+        }),
+    ]);
+    return new Map([[jsonPath, json], ...formattedMarkdown]);
+}
+async function staleSchemaSnapshotFiles(files, root) {
+    const results = await Promise.all([...files].map(async ([path, content]) => {
+        await assertSafeExistingFilePath(root, path);
+        const actual = await readFile(path, 'utf8').catch((err) => 
+        /* v8 ignore next -- non-ENOENT read failures are host-specific */
+        err.code === 'ENOENT' ? null : Promise.reject(err));
+        return actual === content ? null : path;
+    }));
+    return results.filter((path) => path !== null);
+}
+async function extraMarkdownPaths(files, root) {
+    const expected = new Set(files.keys());
+    const orphaned = (await markdownFilesOnDisk(root)).filter((path) => !expected.has(path));
+    const legacyPath = join(root, 'schema.md');
+    const legacyExists = (await lstatOrNull(legacyPath)) !== null;
+    return [...orphaned, ...(legacyExists ? [legacyPath] : [])];
+}
+export async function writeSchemaSnapshot({ snapshot, markdown, root, check = false, format = identityFormat, stringify = stableStringify, }) {
+    const files = await schemaSnapshotFiles(snapshot, markdown, root, format, stringify);
+    if (!check) {
+        await Promise.all([...files.keys()].map((path) => ensureSafeParentDirectory(root, path)));
+        await Promise.all([...files].map(([path, content]) => writeGeneratedFile(root, path, content)));
+        await Promise.all((await extraMarkdownPaths(files, root)).map((path) => rm(path)));
+        return;
+    }
+    const stale = [
+        ...(await staleSchemaSnapshotFiles(files, root)),
+        ...(await extraMarkdownPaths(files, root)),
+    ].toSorted((left, right) => left.localeCompare(right));
+    if (stale.length > 0) {
+        throw new Error([
+            'PostgreSQL schema snapshot is stale. Regenerate it and commit:',
+            ...stale.map((path) => `- ${path}`),
+        ].join('\n'));
+    }
+}
+export async function generateSchemaSnapshot({ query, growth, root, check = false, format = identityFormat, stringify = stableStringify, }) {
+    const snapshot = buildSchemaSnapshot(await readSchemaCatalog(query), growth);
+    await writeSchemaSnapshot({
+        snapshot,
+        markdown: renderSchemaMarkdown(snapshot),
+        root,
+        check,
+        format,
+        stringify,
+    });
+}

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

@@ -0,0 +1,40 @@
+export type SchemaIndexRenameSnapshot = {
+    tables: Record<string, {
+        indexes: Record<string, {
+            definition: string;
+        }>;
+    }>;
+};
+/**
+ * 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 declare function indexShapeKey(name: string, definition: string): string;
+export type RenamedIndex = {
+    table: string;
+    retiredName: string;
+    retiredDefinition: string;
+    renamedTo: string;
+};
+/**
+ * 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 declare function detectRenamedIndexes({ base, head, }: {
+    base: SchemaIndexRenameSnapshot;
+    head: SchemaIndexRenameSnapshot;
+}): RenamedIndex[];