supaschema 0.1.0-rc.1

package/dist/sql/facts.js

@@ -0,0 +1,392 @@
+import { deparseSync } from "pgsql-deparser";
+import { diagnostic } from "../diagnostics.js";
+import { asRecord, astStatements, readArray, readBoolean, readNumber, readString, stringList, stringValue, typeNameToSql, } from "./ast.js";
+import { canonicalPolicyNode, canonicalViewNode } from "./canonical-nodes.js";
+import { normalizeObjectSql } from "./normalize-deparse.js";
+import { astObjectHash, shapeHash } from "./object-hash.js";
+import { parseSqlAst } from "./parser.js";
+import { canonicalConstraintShape, canonicalSequenceShape, canonicalTableShape, } from "./table-shape.js";
+const ifNotExistsSteps = {
+    CreateExtensionStmt: [{ words: ["CREATE"] }, { words: ["EXTENSION"] }],
+    CreateForeignServerStmt: [{ words: ["CREATE"] }, { words: ["SERVER"] }],
+    CreateForeignTableStmt: [{ words: ["CREATE"] }, { words: ["FOREIGN"] }, { words: ["TABLE"] }],
+    CreateSchemaStmt: [{ words: ["CREATE"] }, { words: ["SCHEMA"] }],
+    CreateSeqStmt: [
+        { words: ["CREATE"] },
+        { optional: true, words: ["UNLOGGED", "TEMP", "TEMPORARY"] },
+        { words: ["SEQUENCE"] },
+    ],
+    CreateStmt: [
+        { words: ["CREATE"] },
+        { optional: true, words: ["GLOBAL", "LOCAL"] },
+        { optional: true, words: ["UNLOGGED", "TEMP", "TEMPORARY"] },
+        { words: ["TABLE"] },
+    ],
+    CreateTableAsStmt: [{ words: ["CREATE"] }, { words: ["MATERIALIZED"] }, { words: ["VIEW"] }],
+    IndexStmt: [
+        { words: ["CREATE"] },
+        { optional: true, words: ["UNIQUE"] },
+        { words: ["INDEX"] },
+        { optional: true, words: ["CONCURRENTLY"] },
+    ],
+};
+const orReplaceTags = new Set(["CreateFunctionStmt", "ViewStmt"]);
+const finalizeConcurrency = 8;
+export async function finalizeObjects(objects, options = {}) {
+    const diagnostics = [];
+    for (let start = 0; start < objects.length; start += finalizeConcurrency) {
+        const batch = objects.slice(start, start + finalizeConcurrency);
+        const results = await Promise.all(batch.map((object) => finalizeObject(object, options)));
+        for (const result of results) {
+            diagnostics.push(...result);
+        }
+    }
+    return diagnostics;
+}
+export async function finalizeObject(object, options = {}) {
+    const parsed = await parseSqlAst(object.sql, object.file);
+    let statements = parsed.ast === undefined ? [] : astStatements(parsed.ast, object.sql);
+    if (!statements[0]) {
+        return [
+            ...parsed.diagnostics,
+            diagnostic("SUPA_OBJECT_PARSE_FAILED", "error", `object SQL for ${object.key} did not parse; object identity fell back to text`, { file: object.file, ref: object.ref, statement: object.sql }),
+        ];
+    }
+    const diagnostics = [];
+    if (options.normalize === true) {
+        // Deparse-normalization is fidelity-gated: the canonical text is used
+        // only when it reparses to the identical location-stripped tree, so
+        // hashes are unchanged and a deparser gap degrades to the source text.
+        const normalized = await normalizeObjectSql(object, parsed.ast);
+        diagnostics.push(...normalized.diagnostics);
+        if (normalized.sql !== undefined && normalized.statements !== undefined) {
+            object.sql = normalized.sql;
+            statements = normalized.statements;
+        }
+    }
+    const first = statements[0];
+    if (!first) {
+        return diagnostics;
+    }
+    object.hash = canonicalHash(object, statements);
+    Object.assign(object.metadata, statementFacts(first.tag, first.node, object.sql));
+    return diagnostics;
+}
+function canonicalHash(object, statements) {
+    const first = statements[0];
+    if (first?.tag === "CreateStmt") {
+        const createStmt = asRecord(first.node.CreateStmt);
+        if (createStmt) {
+            const shape = canonicalTableShape(createStmt);
+            // Carried so the planner can diff per-column instead of replacing the
+            // whole table when only column facts change.
+            object.metadata.canonicalShape = shape;
+            return shapeHash(shape, object.key, object.ref);
+        }
+    }
+    if (first?.tag === "CreateSeqStmt") {
+        const createSeqStmt = asRecord(first.node.CreateSeqStmt);
+        if (createSeqStmt) {
+            const shape = canonicalSequenceShape(createSeqStmt);
+            // Carried so a standalone ALTER SEQUENCE ... OWNED BY (the pg_dump
+            // serial decomposition) can fold into the sequence's identity.
+            object.metadata.canonicalShape = shape;
+            return shapeHash(shape, object.key, object.ref);
+        }
+    }
+    if (object.ref.kind === "constraint" && first?.tag === "AlterTableStmt") {
+        const constraintNode = addConstraintNode(asRecord(first.node.AlterTableStmt));
+        if (constraintNode) {
+            return shapeHash(canonicalConstraintShape(constraintNode, {
+                name: object.ref.table ?? "",
+                schema: object.ref.schema ?? "public",
+            }), object.key, object.ref);
+        }
+    }
+    if (object.ref.kind === "default-privilege") {
+        // Hash from the builder-normalized shape, not the statement AST: the
+        // FOR ROLE clause names the executing role and must not affect identity
+        // or content equality across lanes.
+        return shapeHash({
+            grantee: String(object.metadata.grantee ?? ""),
+            objectType: String(object.metadata.objectType ?? ""),
+            privileges: Array.isArray(object.metadata.privileges) ? object.metadata.privileges : [],
+            schema: String(object.metadata.schema ?? ""),
+            verb: String(object.metadata.verb ?? ""),
+        }, object.key, object.ref);
+    }
+    if (object.ref.kind === "rls") {
+        // ALTER TABLE [ONLY] for RLS flags does not recurse to children, so the
+        // ONLY spelling (relation.inh) is semantically inert and must not split
+        // cross-lane identity: catalogs reconstruct without ONLY while trees
+        // often write it.
+        return astObjectHash(statements.map((item) => {
+            const cloned = structuredClone(item.node);
+            const alterTable = asRecord(cloned.AlterTableStmt);
+            const relation = asRecord(alterTable?.relation);
+            if (relation) {
+                relation.inh = true;
+            }
+            return cloned;
+        }), object.key, object.ref);
+    }
+    if (object.ref.kind === "policy") {
+        // pg_get_expr renders ANALYZED expressions: subquery targets gain
+        // auto-aliases (`SELECT auth.uid() AS uid`) and constants gain implicit
+        // casts (`(0)::numeric`) that raw declarative text lacks. Both are
+        // semantically inert inside a policy expression, so hashing strips them
+        // on both lanes.
+        return astObjectHash(statements.map((item) => canonicalPolicyNode(item.node)), object.key, object.ref);
+    }
+    if (object.ref.kind === "view" || object.ref.kind === "materialized-view") {
+        // pg_get_viewdef qualifies every column with its relation name on PG 15
+        // (`upper(accounts.name)`) where PG 16+ and declarative sources write the
+        // bare column (`upper(name)`). Stripping the qualifier is provably safe
+        // only when it names the sole plain relation of the innermost SELECT
+        // scope, so both lanes converge to that form and everything else (joins,
+        // correlated outer refs) keeps its written qualification.
+        return astObjectHash(statements.map((item) => canonicalViewNode(item.node, [])), object.key, object.ref);
+    }
+    return astObjectHash(statements.map((item) => item.node), object.key, object.ref);
+}
+function addConstraintNode(alterTableStmt) {
+    for (const item of readArray(alterTableStmt?.cmds)) {
+        const command = asRecord(asRecord(item)?.AlterTableCmd);
+        if (readString(command?.subtype) !== "AT_AddConstraint") {
+            continue;
+        }
+        const constraint = asRecord(asRecord(command?.def)?.Constraint);
+        if (constraint) {
+            return constraint;
+        }
+    }
+    return undefined;
+}
+export function statementFacts(tag, statementNode, sql) {
+    const node = asRecord(statementNode[tag]) ?? {};
+    const facts = {};
+    const render = renderGuardFacts(tag, node, sql);
+    if (render) {
+        facts.render = render;
+    }
+    if (tag === "CreateFunctionStmt") {
+        Object.assign(facts, functionFacts(node));
+    }
+    if (tag === "ViewStmt") {
+        Object.assign(facts, viewFacts(node));
+    }
+    if (tag === "CommentStmt") {
+        const dropSql = commentDropSql(node);
+        if (dropSql !== undefined) {
+            facts.commentDropSql = dropSql;
+        }
+    }
+    return facts;
+}
+/**
+ * A comment drop is the same statement with a NULL value; deparsing the
+ * comment-stripped node quotes the target correctly (descriptor text is an
+ * identity label, not renderable SQL — `extension uuid-ossp` must render as
+ * `COMMENT ON EXTENSION "uuid-ossp"`).
+ */
+function commentDropSql(node) {
+    try {
+        const stripped = structuredClone(node);
+        delete stripped.comment;
+        return deparseSync({
+            stmts: [{ stmt: { CommentStmt: stripped } }],
+            version: 170004,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function renderGuardFacts(tag, node, sql) {
+    if (tag === "CreateTableAsStmt" && readString(node.objtype) !== "OBJECT_MATVIEW") {
+        return undefined;
+    }
+    const steps = ifNotExistsSteps[tag];
+    if (steps) {
+        // CreateForeignTableStmt nests the flag on its embedded base CreateStmt.
+        const flagNode = tag === "CreateForeignTableStmt" ? (asRecord(node.base) ?? node) : node;
+        const facts = {
+            guard: "ifNotExists",
+            present: readBoolean(flagNode.if_not_exists),
+        };
+        const offset = keywordOffset(sql, steps);
+        if (offset !== undefined) {
+            facts.offset = offset;
+        }
+        return facts;
+    }
+    if (orReplaceTags.has(tag)) {
+        const facts = {
+            guard: "orReplace",
+            present: readBoolean(node.replace),
+        };
+        const offset = keywordOffset(sql, [{ words: ["CREATE"] }]);
+        if (offset !== undefined) {
+            facts.offset = offset;
+        }
+        return facts;
+    }
+    return undefined;
+}
+function functionFacts(node) {
+    const facts = {};
+    const returnType = asRecord(node.returnType);
+    if (returnType) {
+        const returns = {
+            setof: readBoolean(returnType.setof),
+            type: typeNameToSql(node.returnType),
+        };
+        facts.returns = returns;
+    }
+    const outParams = [];
+    for (const item of readArray(node.parameters)) {
+        const parameter = asRecord(asRecord(item)?.FunctionParameter);
+        if (!parameter) {
+            continue;
+        }
+        const mode = readString(parameter.mode) ?? "FUNC_PARAM_DEFAULT";
+        if (mode !== "FUNC_PARAM_OUT" && mode !== "FUNC_PARAM_INOUT" && mode !== "FUNC_PARAM_TABLE") {
+            continue;
+        }
+        outParams.push({
+            mode,
+            name: readString(parameter.name) ?? "",
+            type: typeNameToSql(parameter.argType),
+        });
+    }
+    if (outParams.length > 0) {
+        facts.outParams = outParams;
+    }
+    return facts;
+}
+function viewFacts(node) {
+    const facts = {};
+    const aliases = stringList(node.aliases);
+    const columns = aliases.length > 0 ? aliases : viewTargetColumns(node.query);
+    if (columns !== undefined) {
+        facts.viewColumns = columns;
+    }
+    const securityInvoker = viewSecurityInvoker(node.options);
+    if (securityInvoker !== undefined) {
+        facts.securityInvoker = securityInvoker;
+    }
+    return facts;
+}
+function viewTargetColumns(query) {
+    const select = asRecord(asRecord(query)?.SelectStmt);
+    if (!select || asRecord(select.larg) || asRecord(select.rarg)) {
+        return undefined;
+    }
+    const columns = [];
+    for (const item of readArray(select.targetList)) {
+        const target = asRecord(asRecord(item)?.ResTarget);
+        if (!target) {
+            return undefined;
+        }
+        const explicit = readString(target.name);
+        if (explicit) {
+            columns.push(explicit);
+            continue;
+        }
+        const fields = readArray(asRecord(asRecord(target.val)?.ColumnRef)?.fields);
+        const name = stringValue(fields.at(-1));
+        if (!name) {
+            return undefined;
+        }
+        columns.push(name);
+    }
+    return columns;
+}
+function viewSecurityInvoker(options) {
+    for (const item of readArray(options)) {
+        const defElem = asRecord(asRecord(item)?.DefElem);
+        if (readString(defElem?.defname)?.toLowerCase() !== "security_invoker") {
+            continue;
+        }
+        return defElemBoolean(defElem?.arg);
+    }
+    return undefined;
+}
+function defElemBoolean(arg) {
+    if (arg === undefined || arg === null) {
+        return true;
+    }
+    if (readBoolean(arg)) {
+        return true;
+    }
+    const integer = asRecord(asRecord(arg)?.Integer);
+    if (integer) {
+        return (readNumber(integer.ival) ?? 0) !== 0;
+    }
+    const text = (stringValue(arg) ?? "").toLowerCase();
+    return text === "true" || text === "on" || text === "1" || text === "yes";
+}
+/**
+ * Walks the leading keyword sequence of a statement (skipping whitespace and
+ * comments) and returns the offset of the token that follows it — the splice
+ * point for a replay guard. Character scanning only; classification stays AST.
+ */
+export function keywordOffset(sql, steps) {
+    let index = skipNonTokens(sql, 0);
+    for (const step of steps) {
+        const word = readWord(sql, index);
+        if (word && step.words.some((candidate) => candidate === word.text.toUpperCase())) {
+            index = skipNonTokens(sql, word.end);
+            continue;
+        }
+        if (step.optional) {
+            continue;
+        }
+        return undefined;
+    }
+    return index;
+}
+function isWordStartChar(char) {
+    return (char >= "a" && char <= "z") || (char >= "A" && char <= "Z") || char === "_";
+}
+function isWordContinuationChar(char) {
+    return (char >= "0" && char <= "9") || char === "$";
+}
+function readWord(sql, start) {
+    let end = start;
+    while (end < sql.length) {
+        const char = sql[end] ?? "";
+        if (!(isWordStartChar(char) || (end > start && isWordContinuationChar(char)))) {
+            break;
+        }
+        end += 1;
+    }
+    if (end === start) {
+        return undefined;
+    }
+    return { end, text: sql.slice(start, end) };
+}
+function skipNonTokens(sql, start) {
+    let index = start;
+    while (index < sql.length) {
+        const char = sql[index] ?? "";
+        const next = sql[index + 1] ?? "";
+        if (char === " " || char === "\t" || char === "\n" || char === "\r") {
+            index += 1;
+            continue;
+        }
+        if (char === "-" && next === "-") {
+            while (index < sql.length && sql[index] !== "\n") {
+                index += 1;
+            }
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            const close = sql.indexOf("*/", index + 2);
+            index = close === -1 ? sql.length : close + 2;
+            continue;
+        }
+        break;
+    }
+    return index;
+}

package/dist/sql/identifiers.d.ts

@@ -0,0 +1,13 @@
+import type { ObjectRef } from "../core.js";
+export declare function splitQualifiedIdentifier(input: string): string[];
+export declare function parseQualifiedIdentifier(input: string, defaultSchema?: string): {
+    name: string;
+    schema: string;
+};
+export declare function normalizeIdentifier(input: string): string;
+export declare function quoteIdent(identifier: string): string;
+export declare function stripOuterDoubleQuotes(value: string): string;
+export declare function formatQualifiedName(schema: string | undefined, name: string): string;
+export declare function objectKey(ref: ObjectRef): string;
+export declare function normalizeSql(sql: string): string;
+//# sourceMappingURL=identifiers.d.ts.map

package/dist/sql/identifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../../src/sql/identifiers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BhE;AACD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,aAAa,SAAW,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAYlC;AACD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMzD;AACD,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAErD;AACD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG5D;AACD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpF;AACD,wBAAgB,SAAS,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAKhD;AACD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAiBhD"}

package/dist/sql/identifiers.js

@@ -0,0 +1,83 @@
+export function splitQualifiedIdentifier(input) {
+    const parts = [];
+    let start = 0;
+    let inQuote = false;
+    for (let index = 0; index < input.length; index += 1) {
+        const char = input[index] ?? "";
+        const next = input[index + 1] ?? "";
+        if (inQuote) {
+            if (char === '"' && next === '"') {
+                index += 1;
+                continue;
+            }
+            if (char === '"') {
+                inQuote = false;
+            }
+            continue;
+        }
+        if (char === '"') {
+            inQuote = true;
+            continue;
+        }
+        if (char === ".") {
+            parts.push(input.slice(start, index).trim());
+            start = index + 1;
+        }
+    }
+    parts.push(input.slice(start).trim());
+    return parts.filter(Boolean);
+}
+export function parseQualifiedIdentifier(input, defaultSchema = "public") {
+    const parts = splitQualifiedIdentifier(input);
+    if (parts.length === 1) {
+        return {
+            name: normalizeIdentifier(parts[0] ?? ""),
+            schema: defaultSchema,
+        };
+    }
+    return {
+        name: normalizeIdentifier(parts.at(-1) ?? ""),
+        schema: normalizeIdentifier(parts.at(-2) ?? defaultSchema),
+    };
+}
+export function normalizeIdentifier(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1).replaceAll('""', '"');
+    }
+    return trimmed.toLowerCase();
+}
+export function quoteIdent(identifier) {
+    return `"${identifier.replaceAll('"', '""')}"`;
+}
+export function stripOuterDoubleQuotes(value) {
+    const withoutLeading = value.startsWith('"') ? value.slice(1) : value;
+    return withoutLeading.endsWith('"') ? withoutLeading.slice(0, -1) : withoutLeading;
+}
+export function formatQualifiedName(schema, name) {
+    return schema ? `${quoteIdent(schema)}.${quoteIdent(name)}` : quoteIdent(name);
+}
+export function objectKey(ref) {
+    const schema = ref.schema ? `${ref.schema}.` : "";
+    const table = ref.table ? `:${ref.table}` : "";
+    const signature = ref.signature !== undefined ? `(${ref.signature})` : "";
+    return `${ref.kind}:${schema}${ref.name}${signature}${table}`;
+}
+export function normalizeSql(sql) {
+    const lines = sql.replaceAll("\r\n", "\n").split("\n");
+    const collapsed = [];
+    let blankRun = 0;
+    for (const line of lines) {
+        const trimmedEnd = line.trimEnd();
+        blankRun = trimmedEnd.length === 0 ? blankRun + 1 : 0;
+        if (blankRun <= 1) {
+            collapsed.push(trimmedEnd);
+        }
+    }
+    const text = collapsed.join("\n").trim();
+    let end = text.length;
+    while (end > 0 && text[end - 1] === ";") {
+        end -= 1;
+    }
+    return text.slice(0, end).trimEnd();
+}

package/dist/sql/normalize-deparse.d.ts

@@ -0,0 +1,25 @@
+import type { Diagnostic, SchemaObject } from "../core.js";
+import type { AstStatement } from "./ast.js";
+export interface NormalizeResult {
+    diagnostics: Diagnostic[];
+    sql?: string;
+    statements?: AstStatement[];
+}
+/**
+ * Canonical-output normalization: the parse tree supaschema already computed
+ * is deparsed back to SQL through PostgreSQL's grammar (pgsql-deparser, the
+ * pure-TypeScript companion of the installed libpg-query binding). The
+ * normalized text is accepted only when reparsing it yields a
+ * location-stripped parse tree identical to the original — a deparser
+ * infidelity therefore falls back to the author's text with a warning
+ * instead of silently changing semantics.
+ */
+export declare function normalizeObjectSql(object: SchemaObject, ast: unknown): Promise<NormalizeResult>;
+/**
+ * Round-trip fidelity proof over rendered migration SQL: every statement
+ * must deparse and reparse back to an identical location-stripped parse
+ * tree. This is the always-on telemetry that makes `normalize: "deparse"`
+ * trustworthy exactly where it would be used.
+ */
+export declare function deparseFidelityDiagnostics(sql: string): Promise<Diagnostic[]>;
+//# sourceMappingURL=normalize-deparse.d.ts.map

package/dist/sql/normalize-deparse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-deparse.d.ts","sourceRoot":"","sources":["../../src/sql/normalize-deparse.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAM7C,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,eAAe,CAAC,CAgC1B;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAsCnF"}

package/dist/sql/normalize-deparse.js

@@ -0,0 +1,96 @@
+import { deparseSync } from "pgsql-deparser";
+import { diagnostic } from "../diagnostics.js";
+import { sha256, stableJson } from "../hash.js";
+import { astStatements } from "./ast.js";
+import { normalizeSql } from "./identifiers.js";
+import { stripLocations } from "./object-hash.js";
+import { parseSqlAst } from "./parser.js";
+/**
+ * Canonical-output normalization: the parse tree supaschema already computed
+ * is deparsed back to SQL through PostgreSQL's grammar (pgsql-deparser, the
+ * pure-TypeScript companion of the installed libpg-query binding). The
+ * normalized text is accepted only when reparsing it yields a
+ * location-stripped parse tree identical to the original — a deparser
+ * infidelity therefore falls back to the author's text with a warning
+ * instead of silently changing semantics.
+ */
+export async function normalizeObjectSql(object, ast) {
+    let text;
+    try {
+        text = deparseSync(ast);
+    }
+    catch (error) {
+        return {
+            diagnostics: [
+                diagnostic("SUPA_NORMALIZE_UNSUPPORTED", "warning", `deparser cannot render ${object.key}; keeping the source text (${errorMessage(error)})`, { file: object.file, ref: object.ref }),
+            ],
+        };
+    }
+    const cleaned = normalizeSql(text);
+    const reparsed = await parseSqlAst(cleaned, object.file);
+    const statements = reparsed.ast === undefined ? [] : astStatements(reparsed.ast, cleaned);
+    if (statements.length === 0 || !astEquals(ast, reparsed.ast)) {
+        return {
+            diagnostics: [
+                diagnostic("SUPA_NORMALIZE_FIDELITY", "warning", `deparsed SQL for ${object.key} does not reparse to the same parse tree; keeping the source text`, { file: object.file, ref: object.ref }),
+            ],
+        };
+    }
+    return { diagnostics: [], sql: cleaned, statements };
+}
+/**
+ * Round-trip fidelity proof over rendered migration SQL: every statement
+ * must deparse and reparse back to an identical location-stripped parse
+ * tree. This is the always-on telemetry that makes `normalize: "deparse"`
+ * trustworthy exactly where it would be used.
+ */
+export async function deparseFidelityDiagnostics(sql) {
+    const parsed = await parseSqlAst(sql);
+    if (parsed.ast === undefined) {
+        return [];
+    }
+    const diagnostics = [];
+    for (const statement of astStatements(parsed.ast, sql)) {
+        let text;
+        try {
+            text = deparseSync({
+                stmts: [{ stmt: statement.node }],
+                version: 170004,
+            });
+        }
+        catch (error) {
+            diagnostics.push(diagnostic("SUPA_CHECK_DEPARSE_UNSUPPORTED", "warning", `statement cannot be deparsed for round-trip proof (${errorMessage(error)})`, { statement: statement.text }));
+            continue;
+        }
+        const reparsed = await parseSqlAst(text);
+        const second = reparsed.ast === undefined ? [] : astStatements(reparsed.ast, text);
+        if (second.length !== 1 || !nodeEquals(statement.node, second[0]?.node)) {
+            diagnostics.push(diagnostic("SUPA_CHECK_DEPARSE_MISMATCH", "warning", "statement does not round-trip through the deparser to an identical parse tree", { statement: statement.text }));
+        }
+    }
+    return diagnostics;
+}
+function astEquals(left, right) {
+    const leftStatements = statementNodes(left);
+    const rightStatements = statementNodes(right);
+    if (leftStatements.length !== rightStatements.length) {
+        return false;
+    }
+    return leftStatements.every((node, index) => nodeEquals(node, rightStatements[index]));
+}
+function nodeEquals(left, right) {
+    return sha256(stableJson(stripLocations(left))) === sha256(stableJson(stripLocations(right)));
+}
+function statementNodes(ast) {
+    if (typeof ast !== "object" || ast === null) {
+        return [];
+    }
+    const stmts = ast.stmts;
+    if (!Array.isArray(stmts)) {
+        return [];
+    }
+    return stmts.map((item) => item.stmt);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/sql/object-hash.d.ts

@@ -0,0 +1,5 @@
+import type { ObjectRef } from "../core.js";
+export declare function stripLocations(value: unknown): unknown;
+export declare function astObjectHash(statementNodes: unknown[], key: string, ref: ObjectRef): string;
+export declare function shapeHash(shape: unknown, key: string, ref: ObjectRef): string;
+//# sourceMappingURL=object-hash.d.ts.map

package/dist/sql/object-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-hash.d.ts","sourceRoot":"","sources":["../../src/sql/object-hash.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK5C,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAetD;AAED,wBAAgB,aAAa,CAAC,cAAc,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,CAE5F;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,CAE7E"}

package/dist/sql/object-hash.js

@@ -0,0 +1,24 @@
+import { sha256, stableJson } from "../hash.js";
+const strippedKeys = new Set(["if_not_exists", "location", "replace", "stmt_len", "stmt_location"]);
+export function stripLocations(value) {
+    if (Array.isArray(value)) {
+        return value.map(stripLocations);
+    }
+    if (value && typeof value === "object") {
+        const result = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (strippedKeys.has(key)) {
+                continue;
+            }
+            result[key] = stripLocations(child);
+        }
+        return result;
+    }
+    return value;
+}
+export function astObjectHash(statementNodes, key, ref) {
+    return shapeHash(stripLocations(statementNodes), key, ref);
+}
+export function shapeHash(shape, key, ref) {
+    return sha256(stableJson({ ast: shape, key, ref }));
+}

package/dist/sql/parser.d.ts

@@ -0,0 +1,8 @@
+import type { Diagnostic } from "../core.js";
+export type ParsedSqlAst = {
+    ast?: unknown;
+    diagnostics: Diagnostic[];
+};
+export declare function parseSql(sql: string, file?: string): Promise<Diagnostic[]>;
+export declare function parseSqlAst(sql: string, file?: string): Promise<ParsedSqlAst>;
+//# sourceMappingURL=parser.d.ts.map

package/dist/sql/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/sql/parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAa7C,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,CAAC;AAMF,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAEhF;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAYnF"}