supaschema 0.1.0-rc.1

package/dist/source-normalize.js

@@ -0,0 +1,420 @@
+import { diagnostic } from "./diagnostics.js";
+import { finalizeObject } from "./sql/facts.js";
+import { shapeHash, stripLocations } from "./sql/object-hash.js";
+import { buildDefaultPrivilegeObject, buildGrantObject, builtinPublicDefault, isBuiltinDefaultGrant, } from "./sql/privileges.js";
+import { makeObject } from "./sql/statements.js";
+import { canonicalizeRegclassLiterals } from "./sql/table-shape.js";
+export async function normalizeSourceObjects(objects, diagnostics, options = {}) {
+    const afterDefaults = applyColumnDefaultAmendments(objects, diagnostics);
+    const afterOwnedBy = applySequenceOwnedByAmendments(afterDefaults, diagnostics);
+    const afterRls = await mergeRlsFacets(afterOwnedBy, options);
+    const merged = await mergeSplitPrivileges(afterRls, options);
+    return suppressDefaultAclImpliedGrants(suppressDefaultEqualPrivileges(merged));
+}
+const kindPhraseToDefaultObjectType = new Map([
+    ["DOMAIN", "TYPES"],
+    ["FUNCTION", "FUNCTIONS"],
+    ["PROCEDURE", "FUNCTIONS"],
+    ["SCHEMA", "SCHEMAS"],
+    ["SEQUENCE", "SEQUENCES"],
+    ["TABLE", "TABLES"],
+    ["TYPE", "TYPES"],
+]);
+/**
+ * Postgres applies in-model ALTER DEFAULT PRIVILEGES to every later object,
+ * and the resulting ACL entry is indistinguishable from an explicit GRANT.
+ * A grant fully implied by an in-model default-privilege entry is therefore
+ * suppressed on BOTH lanes (catalog models route through this too): trees
+ * declare the default once, catalogs materialize it per object.
+ */
+export function suppressDefaultAclImpliedGrants(objects) {
+    const defaults = new Map();
+    for (const object of objects) {
+        if (object.ref.kind !== "default-privilege" || object.metadata.verb !== "GRANT") {
+            continue;
+        }
+        const key = [
+            String(object.metadata.objectType ?? ""),
+            String(object.metadata.schema ?? ""),
+            String(object.metadata.grantee ?? ""),
+        ].join("|");
+        const privileges = defaults.get(key) ?? new Set();
+        for (const privilege of Array.isArray(object.metadata.privileges)
+            ? object.metadata.privileges
+            : []) {
+            privileges.add(privilege);
+        }
+        defaults.set(key, privileges);
+    }
+    if (defaults.size === 0) {
+        return objects;
+    }
+    return objects.filter((object) => {
+        if (object.ref.kind !== "grant" || object.metadata.verb !== "GRANT") {
+            return true;
+        }
+        const objectType = kindPhraseToDefaultObjectType.get(String(object.metadata.kindPhrase ?? ""));
+        if (!objectType) {
+            return true;
+        }
+        const implied = defaults.get([objectType, String(object.ref.schema ?? ""), String(object.metadata.grantee ?? "")].join("|"));
+        if (!implied) {
+            return true;
+        }
+        const privileges = Array.isArray(object.metadata.privileges)
+            ? object.metadata.privileges
+            : [];
+        return !privileges.every((privilege) => implied.has(privilege) || implied.has("ALL"));
+    });
+}
+/**
+ * acldefault delta on the source lane, mirroring the catalog lane: a GRANT
+ * that restates PostgreSQL's built-in default (PUBLIC EXECUTE on routines,
+ * PUBLIC USAGE on types) and a REVOKE aimed at a grantee that holds neither
+ * a built-in default nor a granted privilege in this model are semantic
+ * no-ops the catalog can never reproduce; keeping them would be permanent
+ * false drift.
+ */
+function suppressDefaultEqualPrivileges(objects) {
+    const grantsByTarget = new Map();
+    for (const object of objects) {
+        if ((object.ref.kind === "grant" || object.ref.kind === "default-privilege") &&
+            object.metadata.verb === "GRANT") {
+            const key = privilegeTargetKey(object);
+            const group = grantsByTarget.get(key) ?? [];
+            group.push(object);
+            grantsByTarget.set(key, group);
+        }
+    }
+    // Statement order decides the net ACL: a revoke superseded by a later grant
+    // vanishes, and a trailing full-coverage revoke nets the pair to nothing.
+    // Two passes — netting decisions must complete before any object is kept.
+    const nettedAway = new Set();
+    for (const object of objects) {
+        if ((object.ref.kind !== "grant" && object.ref.kind !== "default-privilege") ||
+            object.metadata.verb !== "REVOKE") {
+            continue;
+        }
+        const meta = object.metadata;
+        const kindPhrase = typeof meta.kindPhrase === "string"
+            ? meta.kindPhrase
+            : typeof meta.objectType === "string"
+                ? meta.objectType
+                : "";
+        const grantee = typeof meta.grantee === "string" ? meta.grantee : "";
+        if (builtinPublicDefault(kindPhrase) !== undefined && grantee === "PUBLIC") {
+            continue;
+        }
+        const privileges = Array.isArray(meta.privileges) ? meta.privileges : [];
+        const counterparts = grantsByTarget.get(privilegeTargetKey(object)) ?? [];
+        if (counterparts.length === 0) {
+            nettedAway.add(object);
+            continue;
+        }
+        const latestGrant = Math.max(...counterparts.map((item) => item.ordinal));
+        if (object.ordinal < latestGrant) {
+            nettedAway.add(object);
+            continue;
+        }
+        if (privileges.includes("ALL") || coversAllGrants(privileges, counterparts)) {
+            nettedAway.add(object);
+            for (const counterpart of counterparts) {
+                nettedAway.add(counterpart);
+            }
+        }
+    }
+    return objects.filter((object) => {
+        if (nettedAway.has(object)) {
+            return false;
+        }
+        if (object.ref.kind !== "grant" && object.ref.kind !== "default-privilege") {
+            return true;
+        }
+        const meta = object.metadata;
+        const kindPhrase = typeof meta.kindPhrase === "string"
+            ? meta.kindPhrase
+            : typeof meta.objectType === "string"
+                ? meta.objectType
+                : "";
+        const grantee = typeof meta.grantee === "string" ? meta.grantee : "";
+        const privileges = Array.isArray(meta.privileges) ? meta.privileges : [];
+        if (meta.verb === "GRANT") {
+            return !isBuiltinDefaultGrant(kindPhrase, grantee, privileges);
+        }
+        return true;
+    });
+}
+function coversAllGrants(revoked, grants) {
+    const revokedSet = new Set(revoked);
+    return grants.every((grant) => {
+        const granted = Array.isArray(grant.metadata.privileges)
+            ? grant.metadata.privileges
+            : [];
+        return granted.every((privilege) => revokedSet.has(privilege) || privilege === "ALL");
+    });
+}
+function privilegeTargetKey(object) {
+    const meta = object.metadata;
+    return [
+        object.ref.kind,
+        typeof meta.kindPhrase === "string" ? meta.kindPhrase : String(meta.objectType ?? ""),
+        typeof meta.targetIdentity === "string" ? meta.targetIdentity : String(meta.schema ?? ""),
+        typeof meta.forRole === "string" ? meta.forRole : "",
+        typeof meta.grantee === "string" ? meta.grantee : "",
+    ].join("|");
+}
+function columnDefaultAmendment(object) {
+    const raw = object.metadata.columnDefaultAmendment;
+    if (typeof raw !== "object" || raw === null) {
+        return undefined;
+    }
+    const column = raw.column;
+    if (typeof column !== "string" || column.length === 0) {
+        return undefined;
+    }
+    return { column, expression: raw.expression ?? null };
+}
+function applyColumnDefaultAmendments(objects, diagnostics) {
+    const markers = objects.filter((object) => columnDefaultAmendment(object) !== undefined);
+    if (markers.length === 0) {
+        return objects;
+    }
+    const tablesByKey = new Map();
+    for (const object of objects) {
+        if (object.ref.kind === "table" && columnDefaultAmendment(object) === undefined) {
+            tablesByKey.set(object.key, object);
+        }
+    }
+    for (const marker of markers) {
+        const amendment = columnDefaultAmendment(marker);
+        const table = tablesByKey.get(marker.key);
+        const shape = table?.metadata.canonicalShape;
+        const column = shape?.columns?.find((item) => item.name === amendment?.column);
+        if (!(table && shape && column && amendment)) {
+            diagnostics.push(diagnostic("SUPA_EXTRACT_UNSUPPORTED", "error", "ALTER COLUMN DEFAULT targets a table or column not present in the source model", { file: marker.file, ref: marker.ref, statement: marker.sql }));
+            continue;
+        }
+        if (amendment.expression === null) {
+            delete column.default;
+        }
+        else {
+            column.default = canonicalizeRegclassLiterals(stripLocations(amendment.expression));
+        }
+        table.hash = shapeHash(shape, table.key, table.ref);
+        table.sql = `${table.sql};\n${marker.sql}`;
+        table.dependencies = mergedDependencies([table, marker]);
+    }
+    return objects.filter((object) => columnDefaultAmendment(object) === undefined);
+}
+function sequenceOwnedByAmendment(object) {
+    const raw = object.metadata.sequenceOwnedByAmendment;
+    if (typeof raw !== "object" || raw === null) {
+        return undefined;
+    }
+    const ownedBy = raw.ownedBy;
+    if (ownedBy !== null && typeof ownedBy !== "string") {
+        return undefined;
+    }
+    return { ownedBy };
+}
+function applySequenceOwnedByAmendments(objects, diagnostics) {
+    const markers = objects.filter((object) => sequenceOwnedByAmendment(object) !== undefined);
+    if (markers.length === 0) {
+        return objects;
+    }
+    const sequencesByKey = new Map();
+    for (const object of objects) {
+        if (object.ref.kind === "sequence" && sequenceOwnedByAmendment(object) === undefined) {
+            sequencesByKey.set(object.key, object);
+        }
+    }
+    for (const marker of markers) {
+        const amendment = sequenceOwnedByAmendment(marker);
+        const sequence = sequencesByKey.get(marker.key);
+        const shape = sequence?.metadata.canonicalShape;
+        if (!(sequence && shape && amendment)) {
+            diagnostics.push(diagnostic("SUPA_EXTRACT_UNSUPPORTED", "error", "ALTER SEQUENCE ... OWNED BY targets a sequence not present in the source model", { file: marker.file, ref: marker.ref, statement: marker.sql }));
+            continue;
+        }
+        if (amendment.ownedBy === null) {
+            delete shape.ownedBy;
+        }
+        else {
+            shape.ownedBy = amendment.ownedBy;
+        }
+        sequence.hash = shapeHash(shape, sequence.key, sequence.ref);
+        sequence.sql = `${sequence.sql};\n${marker.sql}`;
+        sequence.dependencies = mergedDependencies([sequence, marker]);
+    }
+    return objects.filter((object) => sequenceOwnedByAmendment(object) === undefined);
+}
+const rlsSubtypeOrder = new Map([
+    ["AT_EnableRowSecurity", 0],
+    ["AT_DisableRowSecurity", 1],
+    ["AT_ForceRowSecurity", 2],
+    ["AT_NoForceRowSecurity", 3],
+]);
+/**
+ * ENABLE and FORCE ROW LEVEL SECURITY are facets of one table's RLS state
+ * sharing one identity; the catalog lane emits them as one multi-statement
+ * object, so split source statements merge the same way.
+ */
+async function mergeRlsFacets(objects, options) {
+    const groups = new Map();
+    for (const object of objects) {
+        if (object.ref.kind !== "rls" || typeof object.metadata.rlsSubtype !== "string") {
+            continue;
+        }
+        const group = groups.get(object.key) ?? [];
+        group.push(object);
+        groups.set(object.key, group);
+    }
+    const replacements = new Map();
+    const removed = new Set();
+    for (const [key, group] of groups) {
+        if (group.length < 2) {
+            continue;
+        }
+        const ordered = [...group].sort((left, right) => (rlsSubtypeOrder.get(String(left.metadata.rlsSubtype)) ?? 9) -
+            (rlsSubtypeOrder.get(String(right.metadata.rlsSubtype)) ?? 9));
+        const first = ordered[0];
+        if (!first) {
+            continue;
+        }
+        const merged = makeObject(first.ref, ordered.map((member) => member.sql).join(";\n"), first.ordinal, first.file);
+        merged.dependencies = mergedDependencies(ordered);
+        await finalizeObject(merged, { normalize: options.normalize === true });
+        replacements.set(key, merged);
+        for (const member of group) {
+            removed.add(member);
+        }
+    }
+    return replaceMembers(objects, removed, replacements);
+}
+function replaceMembers(objects, removed, replacements) {
+    if (replacements.size === 0) {
+        return objects;
+    }
+    const result = [];
+    for (const object of objects) {
+        if (!removed.has(object)) {
+            result.push(object);
+            continue;
+        }
+        const replacement = replacements.get(object.key);
+        if (replacement) {
+            result.push(replacement);
+            replacements.delete(object.key);
+        }
+    }
+    return result;
+}
+async function mergeSplitPrivileges(objects, options) {
+    const groups = new Map();
+    for (const object of objects) {
+        if (object.ref.kind !== "grant" && object.ref.kind !== "default-privilege") {
+            continue;
+        }
+        const group = groups.get(object.key) ?? [];
+        group.push(object);
+        groups.set(object.key, group);
+    }
+    const replacements = new Map();
+    const removed = new Set();
+    for (const [key, group] of groups) {
+        if (group.length < 2) {
+            continue;
+        }
+        const merged = await mergePrivilegeGroup(group, options);
+        if (!merged) {
+            continue;
+        }
+        replacements.set(key, merged);
+        for (const member of group) {
+            removed.add(member);
+        }
+    }
+    return replaceMembers(objects, removed, replacements);
+}
+async function mergePrivilegeGroup(group, options) {
+    const first = group[0];
+    if (!first) {
+        return undefined;
+    }
+    const privileges = unionPrivileges(group);
+    if (!privileges) {
+        return undefined;
+    }
+    const meta = first.metadata;
+    let merged;
+    if (first.ref.kind === "grant") {
+        const grantOptions = new Set(group.map((item) => item.metadata.withGrantOption === true));
+        if (grantOptions.size > 1) {
+            return undefined;
+        }
+        if (typeof meta.grantee !== "string" ||
+            typeof meta.kindPhrase !== "string" ||
+            typeof meta.target !== "string" ||
+            typeof meta.targetIdentity !== "string" ||
+            (meta.verb !== "GRANT" && meta.verb !== "REVOKE")) {
+            return undefined;
+        }
+        merged = buildGrantObject({
+            file: first.file,
+            grantee: meta.grantee,
+            kindPhrase: meta.kindPhrase,
+            ordinal: first.ordinal,
+            privileges,
+            schema: first.ref.schema,
+            targetIdentity: meta.targetIdentity,
+            targetRendered: meta.target,
+            verb: meta.verb,
+            withGrantOption: meta.withGrantOption === true,
+        });
+    }
+    else {
+        if (typeof meta.grantee !== "string" ||
+            typeof meta.objectType !== "string" ||
+            (meta.verb !== "GRANT" && meta.verb !== "REVOKE")) {
+            return undefined;
+        }
+        merged = buildDefaultPrivilegeObject({
+            file: first.file,
+            forRole: typeof meta.forRole === "string" ? meta.forRole : undefined,
+            grantee: meta.grantee,
+            objectType: meta.objectType,
+            ordinal: first.ordinal,
+            privileges,
+            schema: typeof meta.schema === "string" ? meta.schema : undefined,
+            verb: meta.verb,
+        });
+    }
+    merged.dependencies = mergedDependencies(group);
+    await finalizeObject(merged, { normalize: options.normalize === true });
+    return merged;
+}
+function unionPrivileges(group) {
+    const union = new Set();
+    for (const member of group) {
+        const privileges = member.metadata.privileges;
+        if (!Array.isArray(privileges) || privileges.some((item) => typeof item !== "string")) {
+            return undefined;
+        }
+        for (const privilege of privileges) {
+            if (privilege === "ALL") {
+                return ["ALL"];
+            }
+            union.add(privilege);
+        }
+    }
+    return [...union].sort((left, right) => left.localeCompare(right));
+}
+function mergedDependencies(group) {
+    const union = new Set();
+    for (const member of group) {
+        for (const dependency of member.dependencies) {
+            union.add(dependency);
+        }
+    }
+    return [...union].sort((left, right) => left.localeCompare(right));
+}

package/dist/source.d.ts

@@ -0,0 +1,4 @@
+import type { ExtractOptions, SchemaModel } from "./core.js";
+export declare function extractSourceModel(source: string, options?: ExtractOptions): Promise<SchemaModel>;
+export declare function filterModelBySchemas(model: SchemaModel, schemas: Set<string>): SchemaModel;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAEV,cAAc,EACd,WAAW,EAGZ,MAAM,WAAW,CAAC;AAoBnB,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAItB;AA8CD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,WAAW,CAmB1F"}

package/dist/source.js

@@ -0,0 +1,233 @@
+import { execFile } from "node:child_process";
+import { readdir, readFile } from "node:fs/promises";
+import { extname, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { extractCatalogModel } from "./catalog.js";
+import { resolveConfig } from "./config.js";
+import { diagnostic } from "./diagnostics.js";
+import { fingerprintObjects, MODEL_FORMAT_VERSION } from "./hash.js";
+import { normalizeSourceObjects } from "./source-normalize.js";
+import { extractObjectsFromSql } from "./sql/extract.js";
+const execFileAsync = promisify(execFile);
+export async function extractSourceModel(source, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const config = resolveConfig(options.config);
+    return applyConfigModelFilters(await extractRawModel(source, cwd, config), config);
+}
+async function extractRawModel(source, cwd, config) {
+    if (source.startsWith("catalog:")) {
+        return readCatalogSource(source.slice("catalog:".length), cwd, source);
+    }
+    if (source.startsWith("database:")) {
+        const databaseUrl = resolveDatabaseUrl(source.slice("database:".length));
+        return extractCatalogModel({
+            databaseUrl,
+            normalize: config.normalize === "deparse",
+            source,
+        });
+    }
+    if (source.startsWith("dump:")) {
+        const target = source.slice("dump:".length);
+        if (target === "-") {
+            const sql = await readAllStdin();
+            return modelFromSqlFiles([{ path: "<stdin>", sql }], source, config);
+        }
+        const path = resolve(cwd, target);
+        const sql = await readFile(path, "utf8");
+        return modelFromSqlFiles([{ path, sql }], source, config);
+    }
+    if (source.startsWith("dir:")) {
+        const root = resolve(cwd, source.slice("dir:".length));
+        const files = await readSqlFiles(root);
+        return modelFromSqlFiles(files, source, config);
+    }
+    if (source.startsWith("git:")) {
+        const ref = source.slice("git:".length) || "HEAD";
+        const files = await readGitSqlFiles(ref, cwd, config.schemaPaths);
+        return modelFromSqlFiles(files, source, config);
+    }
+    throw new Error(`unsupported source "${source}"`);
+}
+const schemaScopedDiagnosticCodes = new Set([
+    "SUPA_EXTRACT_SIDE_EFFECT_UNSUPPORTED",
+    "SUPA_EXTRACT_UNSUPPORTED",
+]);
+export function filterModelBySchemas(model, schemas) {
+    if (schemas.size === 0) {
+        return model;
+    }
+    // An include list defines the contract scope: extraction findings for
+    // statements that reference no in-scope schema (managed-schema bootstrap,
+    // out-of-contract partition wiring) must not block in-scope diffs.
+    const filtered = withObjects(model, model.objects.filter((object) => schemas.has(objectSchema(object))));
+    return {
+        ...filtered,
+        diagnostics: filtered.diagnostics.filter((item) => !schemaScopedDiagnosticCodes.has(item.code) ||
+            (item.schemas ?? []).some((schema) => schemas.has(schema))),
+    };
+}
+function applyConfigModelFilters(model, config) {
+    let current = model;
+    if (config.schemas.include.length > 0) {
+        current = filterModelBySchemas(current, new Set(config.schemas.include));
+    }
+    if (config.schemas.exclude.length > 0) {
+        const excluded = new Set(config.schemas.exclude);
+        current = withObjects(current, current.objects.filter((object) => !excluded.has(objectSchema(object))));
+        current = {
+            ...current,
+            diagnostics: current.diagnostics.filter((item) => !schemaScopedDiagnosticCodes.has(item.code) ||
+                (item.schemas ?? []).length === 0 ||
+                (item.schemas ?? []).some((schema) => !excluded.has(schema))),
+        };
+    }
+    if (config.excludedGrantRoles.length > 0) {
+        const roles = new Set(config.excludedGrantRoles);
+        current = withObjects(current, current.objects.filter((object) => !isExcludedGrant(object, roles)));
+    }
+    return current;
+}
+function withObjects(model, objects) {
+    if (objects.length === model.objects.length) {
+        return model;
+    }
+    return { ...model, fingerprint: fingerprintObjects(objects), objects };
+}
+function objectSchema(object) {
+    if (object.ref.kind === "schema") {
+        return object.ref.name;
+    }
+    if (object.ref.kind === "extension" && typeof object.metadata.schema === "string") {
+        return object.metadata.schema;
+    }
+    return object.ref.schema ?? "public";
+}
+function isExcludedGrant(object, roles) {
+    if (object.ref.kind !== "grant" && object.ref.kind !== "default-privilege") {
+        return false;
+    }
+    const grantee = typeof object.metadata.grantee === "string" ? object.metadata.grantee : undefined;
+    const forRole = typeof object.metadata.forRole === "string" ? object.metadata.forRole : undefined;
+    return ((grantee !== undefined && roles.has(grantee)) || (forRole !== undefined && roles.has(forRole)));
+}
+async function readCatalogSource(path, cwd, source) {
+    const fullPath = resolve(cwd, path);
+    const raw = JSON.parse(await readFile(fullPath, "utf8"));
+    const objects = Array.isArray(raw.objects) ? raw.objects : [];
+    const diagnostics = Array.isArray(raw.diagnostics) ? raw.diagnostics : [];
+    if (raw.formatVersion !== MODEL_FORMAT_VERSION) {
+        diagnostics.push(diagnostic("SUPA_CATALOG_SNAPSHOT_VERSION", "warning", `catalog snapshot model version ${raw.formatVersion ?? "unknown"} does not match this supaschema model version ${MODEL_FORMAT_VERSION}`, {
+            file: fullPath,
+            hint: "Object hashes are version-specific; regenerate the snapshot with `supaschema inspect` to avoid false replacements.",
+        }));
+    }
+    const model = {
+        diagnostics,
+        fingerprint: raw.fingerprint ?? fingerprintObjects(objects),
+        objects,
+        source,
+    };
+    if (raw.formatVersion !== undefined) {
+        model.formatVersion = raw.formatVersion;
+    }
+    return model;
+}
+async function modelFromSqlFiles(files, source, config) {
+    const extractedObjects = [];
+    const diagnostics = [];
+    let ordinal = 0;
+    for (const file of files.sort((left, right) => left.path.localeCompare(right.path))) {
+        const extracted = await extractObjectsFromSql(file.sql, {
+            config,
+            file: file.path,
+            startOrdinal: ordinal,
+        });
+        extractedObjects.push(...extracted.objects);
+        diagnostics.push(...extracted.diagnostics);
+        ordinal = extracted.nextOrdinal;
+    }
+    const objects = await normalizeSourceObjects(extractedObjects, diagnostics, {
+        normalize: config.normalize === "deparse",
+    });
+    diagnostics.push(...duplicateKeyDiagnostics(objects));
+    return {
+        diagnostics,
+        fingerprint: fingerprintObjects(objects),
+        formatVersion: MODEL_FORMAT_VERSION,
+        objects: objects.sort((left, right) => left.ordinal - right.ordinal),
+        source,
+    };
+}
+async function readAllStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function readSqlFiles(root) {
+    const files = [];
+    async function walk(directory) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            const fullPath = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+                continue;
+            }
+            if (entry.isFile() && extname(entry.name) === ".sql") {
+                files.push({
+                    path: relative(root, fullPath),
+                    sql: await readFile(fullPath, "utf8"),
+                });
+            }
+        }
+    }
+    await walk(root);
+    return files;
+}
+async function readGitSqlFiles(ref, cwd, schemaPaths) {
+    const files = [];
+    for (const schemaPath of schemaPaths) {
+        const { stdout } = await execFileAsync("git", ["-C", cwd, "ls-tree", "-r", "--name-only", ref, "--", schemaPath], { maxBuffer: 1024 * 1024 * 10 });
+        const paths = stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.endsWith(".sql"));
+        for (const path of paths) {
+            const { stdout: sql } = await execFileAsync("git", ["-C", cwd, "show", `${ref}:${path}`], {
+                maxBuffer: 1024 * 1024 * 20,
+            });
+            files.push({ path, sql });
+        }
+    }
+    return files;
+}
+function resolveDatabaseUrl(value) {
+    if (value.startsWith("$")) {
+        const envName = value.slice(1);
+        const resolved = process.env[envName];
+        if (!resolved) {
+            throw new Error(`environment variable ${envName} is not set`);
+        }
+        return resolved;
+    }
+    return value;
+}
+function duplicateKeyDiagnostics(objects) {
+    const diagnostics = [];
+    const seen = new Map();
+    for (const object of objects) {
+        const previous = seen.get(object.key);
+        if (previous) {
+            diagnostics.push(diagnostic("SUPA_EXTRACT_DUPLICATE_OBJECT", "error", "duplicate object identity", {
+                file: object.file,
+                hint: `first seen in ${previous.file ?? "unknown source"}`,
+                ref: object.ref,
+            }));
+            continue;
+        }
+        seen.set(object.key, object);
+    }
+    return diagnostics;
+}