@typed-sql/compiler 1.0.0-rc.0 → 2.0.0-rc.1

package/dist/packages/compiler/src/compatibility.js

@@ -0,0 +1,786 @@
+import { createHash } from "node:crypto";
+import { calculateSchemaHash } from "@typed-sql/schema";
+import { parseQueryManifest, serializeQueryManifest } from "./manifest.js";
+export const SCHEMA_COMPATIBILITY_FORMAT_VERSION = 1;
+export const SCHEMA_COMPATIBILITY_ANALYZER_VERSION = "typed-sql-v1";
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+const relationKey = (key) => `relation:${key}`;
+const relationWriteKey = (key) => `relation-write:${key}`;
+const columnKey = (table, column) => `column:${table}.${column}`;
+const functionKey = (key) => `function:${key}`;
+const functionNameKey = (schema, name) => `function-name:${schema ?? ""}.${name}`;
+const typeKey = (kind, key) => `type:${kind}:${key}`;
+const changeKinds = new Set([
+    "relation-added",
+    "relation-removed",
+    "column-added",
+    "column-removed",
+    "column-database-type",
+    "column-typescript-type",
+    "column-nullability",
+    "column-array",
+    "column-default",
+    "enum-added",
+    "enum-removed",
+    "enum-values",
+    "domain-added",
+    "domain-removed",
+    "domain-database-type",
+    "domain-typescript-type",
+    "domain-nullability",
+    "function-added",
+    "function-removed",
+    "function-return-type",
+    "function-nullability",
+    "function-set-returning",
+    "function-volatility",
+    "dialect-version",
+    "server-version",
+    "query-contract",
+]);
+const targetKinds = new Set([
+    "schema",
+    "relation",
+    "column",
+    "enum",
+    "domain",
+    "function",
+    "query",
+]);
+const directions = new Set(["before-app-after-database", "after-app-before-database"]);
+const classifications = new Set([
+    "compatible",
+    "deployment-order-sensitive",
+    "source-breaking",
+    "runtime-breaking",
+    "unknown",
+]);
+const severities = new Set(["info", "warning", "error"]);
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertNonEmptyString(value, description) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new TypeError(`${description} must be a non-empty string`);
+}
+function assertOptionalString(value, description) {
+    if (value !== undefined)
+        assertNonEmptyString(value, description);
+}
+function assertHash(value, description) {
+    if (typeof value !== "string" || !/^sha256:[a-f\d]{64}$/u.test(value)) {
+        throw new TypeError(`${description} must be a sha256 fingerprint`);
+    }
+}
+function assertDigest(value, description) {
+    if (typeof value !== "string" || !/^[a-f\d]{64}$/u.test(value)) {
+        throw new TypeError(`${description} must be a sha256 digest`);
+    }
+}
+function assertRange(value, description) {
+    if (!record(value) ||
+        !Number.isSafeInteger(value.start) ||
+        value.start < 0 ||
+        !Number.isSafeInteger(value.end) ||
+        value.end < value.start ||
+        !Number.isSafeInteger(value.line) ||
+        value.line < 1 ||
+        !Number.isSafeInteger(value.column) ||
+        value.column < 1) {
+        throw new TypeError(`${description} must contain a valid source range`);
+    }
+}
+function assertLocation(value, description) {
+    if (!record(value))
+        throw new TypeError(`${description} must be an object`);
+    assertNonEmptyString(value.file, `${description}.file`);
+    if (/^(?:\/|\\|[A-Za-z]:[\\/])/u.test(value.file) || value.file.includes("\0")) {
+        throw new TypeError(`${description}.file must be a portable relative path`);
+    }
+    assertRange(value.range, `${description}.range`);
+}
+function assertEvidence(value, description) {
+    if (!record(value))
+        throw new TypeError(`${description} must be an object`);
+    for (const item of Object.values(value)) {
+        if (item !== null &&
+            typeof item !== "string" &&
+            typeof item !== "boolean" &&
+            !(Array.isArray(item) && item.every((entry) => typeof entry === "string"))) {
+            throw new TypeError(`${description} contains an unsupported evidence value`);
+        }
+    }
+}
+function assertQueryReference(value, description) {
+    if (!record(value))
+        throw new TypeError(`${description} must be an object`);
+    assertHash(value.queryId, `${description}.queryId`);
+    assertHash(value.variantFingerprint, `${description}.variantFingerprint`);
+    assertLocation(value.source, `${description}.source`);
+    if (value.dependencyRange !== undefined)
+        assertRange(value.dependencyRange, `${description}.dependencyRange`);
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (typeof value !== "object" || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => compareText(left, right))
+        .map(([key, item]) => [key, canonicalize(item)]));
+}
+function targetIdentity(target) {
+    return `${target.kind}\0${target.key}\0${target.schema ?? ""}\0${target.parent ?? ""}\0${target.name}`;
+}
+function change(kind, target, before, after) {
+    const identity = JSON.stringify(canonicalize({ kind, target, before, after }));
+    return {
+        id: `sha256:${sha256(identity)}`,
+        kind,
+        target,
+        ...(before === undefined ? {} : { before }),
+        ...(after === undefined ? {} : { after }),
+    };
+}
+function relationTarget(key, table) {
+    return {
+        kind: "relation",
+        key,
+        name: table.name,
+        ...(table.schema === undefined ? {} : { schema: table.schema }),
+    };
+}
+function columnTarget(tableKey, table, name) {
+    return {
+        kind: "column",
+        key: `${tableKey}.${name}`,
+        name,
+        parent: tableKey,
+        ...(table.schema === undefined ? {} : { schema: table.schema }),
+    };
+}
+function typeTarget(kind, key, name = key.split(".").at(-1) ?? key) {
+    const dot = key.lastIndexOf(".");
+    return {
+        kind,
+        key,
+        name,
+        ...(dot === -1 ? {} : { schema: key.slice(0, dot) }),
+    };
+}
+function functionTarget(key, value) {
+    return {
+        kind: "function",
+        key,
+        name: value.name,
+        ...(value.schema === undefined ? {} : { schema: value.schema }),
+    };
+}
+function defaultEvidence(value) {
+    return value === undefined ? { present: false, fingerprint: null } : { present: true, fingerprint: sha256(value) };
+}
+function enumChanges(before, after) {
+    const output = [];
+    const keys = [...new Set([...Object.keys(before.enums ?? {}), ...Object.keys(after.enums ?? {})])].sort(compareText);
+    for (const key of keys) {
+        const left = before.enums?.[key];
+        const right = after.enums?.[key];
+        const target = typeTarget("enum", key);
+        if (left === undefined && right !== undefined) {
+            const item = change("enum-added", target, undefined, { values: right });
+            output.push({ change: item, keys: [typeKey("enum", key)] });
+        }
+        else if (left !== undefined && right === undefined) {
+            const item = change("enum-removed", target, { values: left }, undefined);
+            output.push({ change: item, keys: [typeKey("enum", key)] });
+        }
+        else if (left !== undefined && right !== undefined && JSON.stringify(left) !== JSON.stringify(right)) {
+            const item = change("enum-values", target, { values: left }, { values: right });
+            output.push({ change: item, keys: [typeKey("enum", key)] });
+        }
+    }
+    return output;
+}
+function domainChanges(before, after) {
+    const output = [];
+    const keys = [...new Set([...Object.keys(before.domains ?? {}), ...Object.keys(after.domains ?? {})])].sort(compareText);
+    for (const key of keys) {
+        const left = before.domains?.[key];
+        const right = after.domains?.[key];
+        const target = typeTarget("domain", key, left?.name ?? right?.name);
+        if (left === undefined && right !== undefined) {
+            const item = change("domain-added", target, undefined, {
+                databaseType: right.databaseType,
+                tsType: right.tsType,
+                nullable: right.nullable,
+            });
+            output.push({ change: item, keys: [typeKey("domain", key)] });
+            continue;
+        }
+        if (left !== undefined && right === undefined) {
+            const item = change("domain-removed", target, { databaseType: left.databaseType, tsType: left.tsType, nullable: left.nullable }, undefined);
+            output.push({ change: item, keys: [typeKey("domain", key)] });
+            continue;
+        }
+        if (left === undefined || right === undefined)
+            continue;
+        for (const [kind, property] of [
+            ["domain-database-type", "databaseType"],
+            ["domain-typescript-type", "tsType"],
+            ["domain-nullability", "nullable"],
+        ]) {
+            if (left[property] === right[property])
+                continue;
+            const item = change(kind, target, { [property]: left[property] }, { [property]: right[property] });
+            output.push({ change: item, keys: [typeKey("domain", key)] });
+        }
+    }
+    return output;
+}
+function functionEvidence(value) {
+    return {
+        arguments: value.argumentTypes,
+        databaseReturnType: value.databaseReturnType ?? null,
+        returnType: value.returnType,
+        nullable: value.nullable,
+        setReturning: value.setReturning ?? false,
+        volatility: value.volatility ?? null,
+    };
+}
+function functionChanges(before, after) {
+    const output = [];
+    const keys = [...new Set([...Object.keys(before.functions ?? {}), ...Object.keys(after.functions ?? {})])].sort(compareText);
+    for (const key of keys) {
+        const left = before.functions?.[key];
+        const right = after.functions?.[key];
+        const value = left ?? right;
+        if (value === undefined)
+            continue;
+        const target = functionTarget(key, value);
+        const impactKeys = [functionKey(key), functionNameKey(value.schema, value.name)];
+        if (left === undefined && right !== undefined) {
+            output.push({ change: change("function-added", target, undefined, functionEvidence(right)), keys: impactKeys });
+            continue;
+        }
+        if (left !== undefined && right === undefined) {
+            output.push({ change: change("function-removed", target, functionEvidence(left), undefined), keys: impactKeys });
+            continue;
+        }
+        if (left === undefined || right === undefined)
+            continue;
+        for (const [kind, property, evidenceName] of [
+            ["function-return-type", "databaseReturnType", "databaseReturnType"],
+            ["function-return-type", "returnType", "returnType"],
+            ["function-nullability", "nullable", "nullable"],
+            ["function-set-returning", "setReturning", "setReturning"],
+            ["function-volatility", "volatility", "volatility"],
+        ]) {
+            const leftValue = left[property] ?? (property === "setReturning" ? false : null);
+            const rightValue = right[property] ?? (property === "setReturning" ? false : null);
+            if (leftValue === rightValue)
+                continue;
+            const item = change(kind, target, { [evidenceName]: leftValue }, { [evidenceName]: rightValue });
+            output.push({ change: item, keys: impactKeys });
+        }
+    }
+    return output;
+}
+function schemaChanges(before, after) {
+    const output = [
+        ...enumChanges(before, after),
+        ...domainChanges(before, after),
+        ...functionChanges(before, after),
+    ];
+    const tableKeys = [...new Set([...Object.keys(before.tables), ...Object.keys(after.tables)])].sort(compareText);
+    for (const tableKey of tableKeys) {
+        const leftTable = before.tables[tableKey];
+        const rightTable = after.tables[tableKey];
+        const table = leftTable ?? rightTable;
+        if (table === undefined)
+            continue;
+        if (leftTable === undefined && rightTable !== undefined) {
+            output.push({
+                change: change("relation-added", relationTarget(tableKey, rightTable), undefined, {}),
+                keys: [relationKey(tableKey)],
+            });
+            continue;
+        }
+        if (leftTable !== undefined && rightTable === undefined) {
+            output.push({
+                change: change("relation-removed", relationTarget(tableKey, leftTable), {}, undefined),
+                keys: [relationKey(tableKey)],
+            });
+            continue;
+        }
+        if (leftTable === undefined || rightTable === undefined)
+            continue;
+        const columnNames = [...new Set([...Object.keys(leftTable.columns), ...Object.keys(rightTable.columns)])].sort(compareText);
+        for (const name of columnNames) {
+            const left = leftTable.columns[name];
+            const right = rightTable.columns[name];
+            const target = columnTarget(tableKey, table, name);
+            if (left === undefined && right !== undefined) {
+                output.push({
+                    change: change("column-added", target, undefined, {
+                        databaseType: right.databaseType,
+                        tsType: right.tsType,
+                        nullable: right.nullable,
+                        ...defaultEvidence(right.defaultExpression),
+                    }),
+                    keys: [columnKey(tableKey, name)],
+                    relationWriteKey: relationWriteKey(tableKey),
+                    addedMandatoryColumn: !right.nullable && right.defaultExpression === undefined,
+                });
+                continue;
+            }
+            if (left !== undefined && right === undefined) {
+                output.push({
+                    change: change("column-removed", target, {
+                        databaseType: left.databaseType,
+                        tsType: left.tsType,
+                        nullable: left.nullable,
+                        ...defaultEvidence(left.defaultExpression),
+                    }, undefined),
+                    keys: [columnKey(tableKey, name)],
+                    relationWriteKey: relationWriteKey(tableKey),
+                    removedMandatoryColumn: !left.nullable && left.defaultExpression === undefined,
+                });
+                continue;
+            }
+            if (left === undefined || right === undefined)
+                continue;
+            for (const [kind, property] of [
+                ["column-database-type", "databaseType"],
+                ["column-typescript-type", "tsType"],
+                ["column-nullability", "nullable"],
+            ]) {
+                if (left[property] === right[property])
+                    continue;
+                output.push({
+                    change: change(kind, target, { [property]: left[property] }, { [property]: right[property] }),
+                    keys: [columnKey(tableKey, name)],
+                    relationWriteKey: relationWriteKey(tableKey),
+                });
+            }
+            if ((left.array ?? false) !== (right.array ?? false)) {
+                output.push({
+                    change: change("column-array", target, { array: left.array ?? false }, { array: right.array ?? false }),
+                    keys: [columnKey(tableKey, name)],
+                });
+            }
+            if (left.defaultExpression !== right.defaultExpression) {
+                output.push({
+                    change: change("column-default", target, defaultEvidence(left.defaultExpression), defaultEvidence(right.defaultExpression)),
+                    keys: [columnKey(tableKey, name)],
+                    relationWriteKey: relationWriteKey(tableKey),
+                });
+            }
+        }
+    }
+    if (before.version !== after.version) {
+        output.push({
+            change: change("server-version", { kind: "schema", key: before.dialect, name: before.dialect }, { version: before.version ?? null }, { version: after.version ?? null }),
+            keys: ["all-queries"],
+        });
+    }
+    if (before.dialectVersion !== after.dialectVersion) {
+        output.push({
+            change: change("dialect-version", { kind: "schema", key: before.dialect, name: before.dialect }, { version: before.dialectVersion ?? null }, { version: after.dialectVersion ?? null }),
+            keys: ["all-queries"],
+        });
+    }
+    return output.sort((left, right) => compareText(targetIdentity(left.change.target), targetIdentity(right.change.target)) ||
+        compareText(left.change.kind, right.change.kind));
+}
+function matchingTables(snapshot, name, schema) {
+    return Object.entries(snapshot.tables).filter(([key, table]) => (key === name || table.name === name || key.endsWith(`.${name}`)) &&
+        (schema === undefined || table.schema === schema));
+}
+function matchingColumns(tables, name) {
+    return tables.flatMap(([tableKey, table]) => Object.entries(table.columns)
+        .filter(([columnKey, column]) => columnKey === name || column.name === name)
+        .map(([columnKey]) => [tableKey, columnKey]));
+}
+function matchingTypes(values, name, schema) {
+    const matches = Object.keys(values).filter((key) => key === name || key.endsWith(`.${name}`));
+    if (schema === undefined)
+        return matches;
+    const qualified = matches.filter((key) => key === `${schema}.${name}`);
+    return qualified.length === 0 ? matches.filter((key) => !key.includes(".")) : qualified;
+}
+function addReference(map, key, reference) {
+    map.set(key, [...(map.get(key) ?? []), reference]);
+}
+function reference(entryId, variant, source, dependency) {
+    return {
+        queryId: entryId,
+        variantFingerprint: variant.fingerprint,
+        source,
+        ...(dependency === undefined ? {} : { dependencyRange: dependency.range }),
+    };
+}
+function manifestReferences(manifest, snapshot) {
+    const byKey = new Map();
+    const unknown = [];
+    for (const entry of manifest.queries) {
+        if (entry.status === "unresolved") {
+            unknown.push({ queryId: entry.id, variantFingerprint: entry.id, source: entry.source });
+            continue;
+        }
+        for (const variant of entry.variants) {
+            if (variant.semantics.operation.value === "unknown" ||
+                variant.semantics.cardinality.maximum === "unknown" ||
+                variant.semantics.volatility.value === "unknown" ||
+                variant.semantics.locking.value === "unknown" ||
+                variant.semantics.connectionAffinity.value === "unknown") {
+                unknown.push(reference(entry.id, variant, entry.source));
+            }
+            const relationMatches = new Map();
+            for (const dependency of variant.semantics.dependencies.filter((item) => item.kind === "relation")) {
+                const matches = matchingTables(snapshot, dependency.name, dependency.schema);
+                relationMatches.set(dependency, matches);
+                const item = reference(entry.id, variant, entry.source, dependency);
+                if (matches.length === 1) {
+                    addReference(byKey, relationKey(matches[0][0]), item);
+                    if (dependency.access === "write")
+                        addReference(byKey, relationWriteKey(matches[0][0]), item);
+                }
+                else
+                    unknown.push(item);
+            }
+            for (const dependency of variant.semantics.dependencies.filter((item) => item.kind !== "relation")) {
+                const item = reference(entry.id, variant, entry.source, dependency);
+                if (dependency.kind === "column") {
+                    let matches = dependency.parent === undefined ? [] : matchingTables(snapshot, dependency.parent);
+                    if (matches.length === 0) {
+                        matches = [...new Map([...relationMatches.values()].flat().map((value) => [value[0], value])).values()];
+                    }
+                    const columns = matchingColumns(matches, dependency.name);
+                    if (columns.length === 1) {
+                        addReference(byKey, columnKey(columns[0][0], columns[0][1]), item);
+                    }
+                    else
+                        unknown.push(item);
+                }
+                else if (dependency.kind === "function") {
+                    const matches = Object.entries(snapshot.functions ?? {}).filter(([, fn]) => fn.name === dependency.name && (dependency.schema === undefined || fn.schema === dependency.schema));
+                    if (matches.length === 1)
+                        addReference(byKey, functionKey(matches[0][0]), item);
+                    if (matches.length > 0)
+                        addReference(byKey, functionNameKey(dependency.schema ?? matches[0]?.[1].schema, dependency.name), item);
+                    else if (dependency.certainty === "resolved")
+                        unknown.push(item);
+                }
+                else if (dependency.kind === "type") {
+                    const enums = matchingTypes(snapshot.enums ?? {}, dependency.name, dependency.schema);
+                    const domains = matchingTypes(snapshot.domains ?? {}, dependency.name, dependency.schema);
+                    if (enums.length + domains.length === 1) {
+                        if (enums.length === 1)
+                            addReference(byKey, typeKey("enum", enums[0]), item);
+                        else
+                            addReference(byKey, typeKey("domain", domains[0]), item);
+                    }
+                    else if (enums.length + domains.length > 1 || dependency.certainty === "resolved")
+                        unknown.push(item);
+                }
+                else if (dependency.kind === "unknown" || dependency.kind === "sequence")
+                    unknown.push(item);
+            }
+            addReference(byKey, "all-queries", reference(entry.id, variant, entry.source));
+        }
+    }
+    return { byKey, unknown: uniqueReferences(unknown) };
+}
+function uniqueReferences(values) {
+    const unique = new Map();
+    for (const value of values) {
+        const key = `${value.queryId}\0${value.variantFingerprint}\0${value.dependencyRange?.start ?? -1}`;
+        unique.set(key, value);
+    }
+    return [...unique.values()].sort((left, right) => compareText(left.source.file, right.source.file) ||
+        left.source.range.start - right.source.range.start ||
+        compareText(left.variantFingerprint, right.variantFingerprint) ||
+        (left.dependencyRange?.start ?? -1) - (right.dependencyRange?.start ?? -1));
+}
+function affected(change, references, direction) {
+    const values = change.keys.flatMap((key) => references.byKey.get(key) ?? []);
+    if (change.relationWriteKey !== undefined &&
+        ((change.addedMandatoryColumn === true && direction === "before-app-after-database") ||
+            (change.removedMandatoryColumn === true && direction === "after-app-before-database") ||
+            change.change.kind === "column-default" ||
+            change.change.kind === "column-nullability")) {
+        values.push(...(references.byKey.get(change.relationWriteKey) ?? []));
+    }
+    return uniqueReferences(values);
+}
+function risk(item, direction, queries) {
+    const kind = item.change.kind;
+    if (queries.length === 0)
+        return {
+            classification: "compatible",
+            severity: "info",
+            reason: "No compiled query in this application version depends on the changed contract.",
+        };
+    if (kind === "server-version" || kind === "dialect-version")
+        return {
+            classification: "unknown",
+            severity: "warning",
+            reason: "Database-version compatibility requires live verification in a representative environment.",
+        };
+    if (kind === "column-typescript-type" || kind === "domain-typescript-type" || kind === "query-contract") {
+        return {
+            classification: "source-breaking",
+            severity: "error",
+            reason: "The inferred TypeScript query contract changes.",
+        };
+    }
+    if (kind === "function-volatility" || kind === "column-default") {
+        return {
+            classification: "deployment-order-sensitive",
+            severity: "warning",
+            reason: "The query can depend on changed execution or default-value semantics during a rolling deployment.",
+        };
+    }
+    if (kind.endsWith("-added")) {
+        if (direction === "after-app-before-database")
+            return {
+                classification: "runtime-breaking",
+                severity: "error",
+                reason: "The newer application references a contract that the older database does not provide.",
+            };
+        if (kind === "function-added" || item.addedMandatoryColumn === true)
+            return {
+                classification: "deployment-order-sensitive",
+                severity: "error",
+                reason: "The added contract can change overload resolution or make existing writes incomplete.",
+            };
+        return {
+            classification: "compatible",
+            severity: "info",
+            reason: "The older application does not require the additive contract.",
+        };
+    }
+    if (kind.endsWith("-removed")) {
+        if (direction === "before-app-after-database")
+            return {
+                classification: "runtime-breaking",
+                severity: "error",
+                reason: "The older application references a contract removed from the newer database.",
+            };
+        if (kind === "function-removed")
+            return {
+                classification: "deployment-order-sensitive",
+                severity: "warning",
+                reason: "An overload present only on the older database can change function resolution for the newer application.",
+            };
+        if (item.removedMandatoryColumn === true)
+            return {
+                classification: "deployment-order-sensitive",
+                severity: "error",
+                reason: "The newer application can omit a value still required by the older database.",
+            };
+        return {
+            classification: "compatible",
+            severity: "info",
+            reason: "The newer application does not require the removed contract.",
+        };
+    }
+    return {
+        classification: "runtime-breaking",
+        severity: "error",
+        reason: "The database contract used by the query changes incompatibly across deployment versions.",
+    };
+}
+function manifestHash(manifest) {
+    return `sha256:${sha256(serializeQueryManifest(manifest))}`;
+}
+function validateInputs(options) {
+    parseQueryManifest(options.beforeManifest);
+    parseQueryManifest(options.afterManifest);
+    const dialect = options.before.dialect;
+    if (options.after.dialect !== dialect ||
+        options.beforeManifest.dialect.id !== dialect ||
+        options.afterManifest.dialect.id !== dialect) {
+        throw new TypeError("Compatibility snapshots and manifests must use the same dialect");
+    }
+    const beforeHash = calculateSchemaHash(options.before);
+    const afterHash = calculateSchemaHash(options.after);
+    if (options.beforeManifest.schemaHash !== beforeHash)
+        throw new TypeError("Before manifest is stale for the before snapshot");
+    if (options.afterManifest.schemaHash !== afterHash)
+        throw new TypeError("After manifest is stale for the after snapshot");
+}
+function queryContractChanges(before, after) {
+    const output = [];
+    const afterEntries = new Map(after.queries
+        .filter((entry) => entry.status === "resolved")
+        .map((entry) => [`${entry.source.file}\0${entry.source.range.start}\0${entry.fingerprint}`, entry]));
+    for (const entry of before.queries) {
+        if (entry.status !== "resolved")
+            continue;
+        const other = afterEntries.get(`${entry.source.file}\0${entry.source.range.start}\0${entry.fingerprint}`);
+        if (other === undefined)
+            continue;
+        const otherVariants = new Map(other.variants.map((variant) => [variant.fingerprint, variant]));
+        for (const variant of entry.variants) {
+            const afterVariant = otherVariants.get(variant.fingerprint);
+            if (afterVariant === undefined ||
+                (variant.rowType === afterVariant.rowType && variant.parameterType === afterVariant.parameterType))
+                continue;
+            const target = { kind: "query", key: entry.id, name: entry.id };
+            const item = change("query-contract", target, { rowType: variant.rowType, parameterType: variant.parameterType }, { rowType: afterVariant.rowType, parameterType: afterVariant.parameterType });
+            output.push({
+                change: item,
+                keys: [`query:${item.id}`],
+                queryReferences: {
+                    "before-app-after-database": reference(entry.id, variant, entry.source),
+                    "after-app-before-database": reference(other.id, afterVariant, other.source),
+                },
+            });
+        }
+    }
+    return output;
+}
+export function analyzeSchemaCompatibility(options) {
+    validateInputs(options);
+    const beforeReferences = manifestReferences(options.beforeManifest, options.before);
+    const afterReferences = manifestReferences(options.afterManifest, options.after);
+    const changes = [
+        ...schemaChanges(options.before, options.after),
+        ...queryContractChanges(options.beforeManifest, options.afterManifest),
+    ].sort((left, right) => compareText(targetIdentity(left.change.target), targetIdentity(right.change.target)) ||
+        compareText(left.change.kind, right.change.kind));
+    const assessments = [];
+    for (const item of changes) {
+        for (const direction of ["before-app-after-database", "after-app-before-database"]) {
+            const references = direction === "before-app-after-database" ? beforeReferences : afterReferences;
+            const explicit = item.queryReferences?.[direction];
+            const queries = explicit === undefined ? affected(item, references, direction) : [explicit];
+            assessments.push({ direction, changeId: item.change.id, ...risk(item, direction, queries), queries });
+        }
+    }
+    for (const [direction, references] of [
+        ["before-app-after-database", beforeReferences],
+        ["after-app-before-database", afterReferences],
+    ]) {
+        for (const query of references.unknown) {
+            assessments.push({
+                direction,
+                classification: "unknown",
+                severity: "warning",
+                reason: "The manifest contains an unresolved query or dependency, so compatibility cannot be proven.",
+                queries: [query],
+            });
+        }
+    }
+    assessments.sort((left, right) => compareText(left.direction, right.direction) ||
+        compareText(left.changeId ?? "", right.changeId ?? "") ||
+        compareText(left.queries[0]?.source.file ?? "", right.queries[0]?.source.file ?? "") ||
+        (left.queries[0]?.source.range.start ?? -1) - (right.queries[0]?.source.range.start ?? -1));
+    const report = {
+        formatVersion: SCHEMA_COMPATIBILITY_FORMAT_VERSION,
+        analyzerVersion: SCHEMA_COMPATIBILITY_ANALYZER_VERSION,
+        dialect: options.before.dialect,
+        before: {
+            schemaHash: options.beforeManifest.schemaHash,
+            manifestHash: manifestHash(options.beforeManifest),
+            ...(options.before.version === undefined ? {} : { version: options.before.version }),
+        },
+        after: {
+            schemaHash: options.afterManifest.schemaHash,
+            manifestHash: manifestHash(options.afterManifest),
+            ...(options.after.version === undefined ? {} : { version: options.after.version }),
+        },
+        changes: changes.map((item) => item.change),
+        assessments,
+        summary: {
+            info: assessments.filter((item) => item.severity === "info").length,
+            warning: assessments.filter((item) => item.severity === "warning").length,
+            error: assessments.filter((item) => item.severity === "error").length,
+        },
+    };
+    return report;
+}
+export function serializeSchemaCompatibilityReport(report) {
+    return `${JSON.stringify(canonicalize(report), null, 2)}\n`;
+}
+export function parseSchemaCompatibilityReport(value) {
+    if (!record(value))
+        throw new TypeError("Compatibility report must be an object");
+    const report = value;
+    if (report.formatVersion !== SCHEMA_COMPATIBILITY_FORMAT_VERSION)
+        throw new TypeError(`Unsupported compatibility report format ${String(report.formatVersion)}`);
+    if (report.analyzerVersion !== SCHEMA_COMPATIBILITY_ANALYZER_VERSION)
+        throw new TypeError(`Unsupported compatibility analyzer ${String(report.analyzerVersion)}`);
+    assertNonEmptyString(report.dialect, "Compatibility report dialect");
+    for (const [name, artifact] of [
+        ["before", report.before],
+        ["after", report.after],
+    ]) {
+        if (!record(artifact))
+            throw new TypeError(`Compatibility report ${name} artifact is invalid`);
+        assertDigest(artifact.schemaHash, `Compatibility report ${name}.schemaHash`);
+        assertHash(artifact.manifestHash, `Compatibility report ${name}.manifestHash`);
+        assertOptionalString(artifact.version, `Compatibility report ${name}.version`);
+    }
+    if (!Array.isArray(report.changes))
+        throw new TypeError("Compatibility report changes must be an array");
+    const changeIds = new Set();
+    for (const [index, item] of report.changes.entries()) {
+        const description = `Compatibility report change ${index}`;
+        if (!record(item) || !changeKinds.has(item.kind) || !record(item.target)) {
+            throw new TypeError(`${description} is invalid`);
+        }
+        const target = item.target;
+        if (!targetKinds.has(target.kind)) {
+            throw new TypeError(`${description}.target.kind is invalid`);
+        }
+        assertNonEmptyString(target.key, `${description}.target.key`);
+        assertNonEmptyString(target.name, `${description}.target.name`);
+        assertOptionalString(target.schema, `${description}.target.schema`);
+        assertOptionalString(target.parent, `${description}.target.parent`);
+        if (item.before !== undefined)
+            assertEvidence(item.before, `${description}.before`);
+        if (item.after !== undefined)
+            assertEvidence(item.after, `${description}.after`);
+        assertHash(item.id, `${description}.id`);
+        const expected = change(item.kind, target, item.before, item.after).id;
+        if (item.id !== expected)
+            throw new TypeError(`${description}.id does not match its canonical evidence`);
+        if (changeIds.has(item.id))
+            throw new TypeError(`${description}.id is duplicated`);
+        changeIds.add(item.id);
+    }
+    if (!Array.isArray(report.assessments))
+        throw new TypeError("Compatibility report assessments must be an array");
+    const counted = { info: 0, warning: 0, error: 0 };
+    for (const [index, item] of report.assessments.entries()) {
+        const description = `Compatibility report assessment ${index}`;
+        if (!record(item) ||
+            !directions.has(item.direction) ||
+            !classifications.has(item.classification) ||
+            !severities.has(item.severity) ||
+            !Array.isArray(item.queries)) {
+            throw new TypeError(`${description} is invalid`);
+        }
+        assertNonEmptyString(item.reason, `${description}.reason`);
+        if (item.changeId !== undefined) {
+            assertHash(item.changeId, `${description}.changeId`);
+            if (!changeIds.has(item.changeId))
+                throw new TypeError(`${description}.changeId does not identify a report change`);
+        }
+        for (const [queryIndex, query] of item.queries.entries()) {
+            assertQueryReference(query, `${description}.queries[${queryIndex}]`);
+        }
+        counted[item.severity] += 1;
+    }
+    if (!record(report.summary))
+        throw new TypeError("Compatibility report summary is invalid");
+    for (const severity of ["info", "warning", "error"]) {
+        if (!Number.isSafeInteger(report.summary[severity]) || report.summary[severity] !== counted[severity])
+            throw new TypeError("Compatibility report summary is invalid");
+    }
+    return value;
+}
+//# sourceMappingURL=compatibility.js.map