supaschema 0.1.0-rc.1

package/dist/sql/extract.js

@@ -0,0 +1,323 @@
+import { resolveConfig } from "../config.js";
+import { diagnostic } from "../diagnostics.js";
+import { asRecord, astStatements, collectReferences, functionIdentity, qualifiedName, rangeVarName, readArray, readBoolean, readString, stringList, } from "./ast.js";
+import { alterTableObjects, extensionSchemaOption, sequenceOwnedByOption, supabaseViewSecurityDiagnostics, withManagedSchemaDiagnostics, } from "./extract-helpers.js";
+import { finalizeObjects } from "./facts.js";
+import { parseSqlAst } from "./parser.js";
+import { commentObjectFromAst, defaultPrivilegesFromAst, grantObjectsFromAst, } from "./privileges.js";
+import { makeObject, tableMetadataFromAst } from "./statements.js";
+import { stripDeclaredConstraints, tableConstraintSyntheses } from "./table-constraints.js";
+const sideEffectTags = new Set([
+    "CallStmt",
+    "DeleteStmt",
+    "DoStmt",
+    "InsertStmt",
+    "RefreshMatViewStmt",
+    "SelectStmt",
+    "UpdateStmt",
+]);
+const ignoredTags = new Set(["TransactionStmt"]);
+export async function extractObjectsFromSql(sql, options = {}) {
+    const config = resolveConfig(options.config);
+    const parsedSql = await parseSqlAst(sql, options.file);
+    const diagnostics = [...parsedSql.diagnostics];
+    const objects = [];
+    let ordinal = options.startOrdinal ?? 0;
+    if (parsedSql.ast === undefined) {
+        if (!diagnostics.some((item) => item.severity === "error")) {
+            diagnostics.push(diagnostic("SUPA_EXTRACT_PARSER_REQUIRED", "error", "AST extraction requires the libpg-query parser", { file: options.file }));
+        }
+        return { diagnostics, nextOrdinal: ordinal, objects };
+    }
+    for (const statement of astStatements(parsedSql.ast, sql)) {
+        if (statement.text.length === 0 || ignoredTags.has(statement.tag)) {
+            continue;
+        }
+        const parsed = parseStatement(statement, ordinal, config, options.file);
+        diagnostics.push(...parsed.diagnostics);
+        if (parsed.objects.length > 0) {
+            const references = await statementReferences(statement);
+            for (const object of parsed.objects) {
+                object.dependencies = [...references]
+                    .filter((reference) => reference !== objectIdentity(object.ref))
+                    .sort((left, right) => left.localeCompare(right));
+            }
+            diagnostics.push(...(await finalizeObjects(parsed.objects, { normalize: config.normalize === "deparse" })));
+            diagnostics.push(...supabaseViewSecurityDiagnostics(parsed.objects, config));
+        }
+        objects.push(...parsed.objects);
+        ordinal += parsed.objects.length;
+    }
+    return {
+        diagnostics,
+        nextOrdinal: ordinal,
+        objects,
+    };
+}
+function parseStatement(statement, ordinal, config, file) {
+    if (sideEffectTags.has(statement.tag)) {
+        return {
+            diagnostics: [
+                diagnostic("SUPA_EXTRACT_SIDE_EFFECT_UNSUPPORTED", "error", "side-effect statements are not schema objects and cannot be rendered as replay-safe migrations", {
+                    file,
+                    hint: "Keep data/control-plane side effects in an explicit reviewed migration.",
+                    schemas: referencedSchemas(statement),
+                    statement: statement.text,
+                }),
+            ],
+            objects: [],
+        };
+    }
+    const objects = buildObjects(statement, ordinal, file);
+    if (objects === undefined) {
+        const head = statement.text.split("\n", 1)[0]?.slice(0, 100) ?? "";
+        return {
+            diagnostics: [
+                diagnostic("SUPA_EXTRACT_UNSUPPORTED", "error", `unsupported or ambiguous DDL statement (${statement.tag}): ${head}`, {
+                    file,
+                    hint: "Add support for this object kind or keep the change hand-authored.",
+                    schemas: referencedSchemas(statement),
+                    statement: statement.text,
+                }),
+            ],
+            objects: [],
+        };
+    }
+    return withManagedSchemaDiagnostics(objects, statement.text, config, file);
+}
+function buildObjects(statement, ordinal, file) {
+    const node = asRecord(statement.node[statement.tag]);
+    if (!node) {
+        return undefined;
+    }
+    switch (statement.tag) {
+        case "CreateSchemaStmt": {
+            const name = readString(node.schemaname);
+            return name
+                ? [makeObject({ kind: "schema", name }, statement.text, ordinal, file)]
+                : undefined;
+        }
+        case "CreateExtensionStmt": {
+            const name = readString(node.extname);
+            if (!name) {
+                return undefined;
+            }
+            const schema = extensionSchemaOption(node.options);
+            return [
+                makeObject({ kind: "extension", name }, statement.text, ordinal, file, schema ? { schema } : {}),
+            ];
+        }
+        case "CreateEnumStmt": {
+            const name = qualifiedName(node.typeName);
+            if (!name) {
+                return undefined;
+            }
+            const values = stringList(node.vals);
+            return [makeObject({ kind: "enum", ...name }, statement.text, ordinal, file, { values })];
+        }
+        case "CreateDomainStmt": {
+            const name = qualifiedName(node.domainname);
+            return name
+                ? [makeObject({ kind: "domain", ...name }, statement.text, ordinal, file)]
+                : undefined;
+        }
+        case "CompositeTypeStmt": {
+            const name = rangeVarName(node.typevar);
+            return name
+                ? [makeObject({ kind: "type", ...name }, statement.text, ordinal, file)]
+                : undefined;
+        }
+        case "CreateRangeStmt": {
+            const name = qualifiedName(node.typeName);
+            return name
+                ? [makeObject({ kind: "type", ...name }, statement.text, ordinal, file)]
+                : undefined;
+        }
+        case "CreateStmt": {
+            const name = rangeVarName(node.relation);
+            if (!name) {
+                return undefined;
+            }
+            const tableSql = stripDeclaredConstraints(node, statement.text, statement.byteStart) ?? statement.text;
+            const objects = [
+                makeObject({ kind: "table", ...name }, tableSql, ordinal, file, tableMetadataFromAst(node, statement.text, statement.byteStart)),
+            ];
+            // In-CREATE constraints surface as their own constraint objects so table
+            // identity stays independent of where a constraint is declared; the
+            // table object's SQL is rebuilt columns-only to match the catalog lane.
+            for (const [index, synthesized] of tableConstraintSyntheses(node, statement.text, statement.byteStart).entries()) {
+                objects.push(makeObject({ kind: "constraint", name: synthesized.name, schema: name.schema, table: name.name }, synthesized.sql, ordinal + 1 + index, file));
+            }
+            return objects;
+        }
+        case "CreateSeqStmt": {
+            const name = rangeVarName(node.sequence);
+            return name
+                ? [makeObject({ kind: "sequence", ...name }, statement.text, ordinal, file)]
+                : undefined;
+        }
+        case "AlterSeqStmt": {
+            const name = rangeVarName(node.sequence);
+            if (!name) {
+                return undefined;
+            }
+            const ownedBy = sequenceOwnedByOption(node.options);
+            if (ownedBy === undefined) {
+                return undefined;
+            }
+            // Folded into the owning sequence's canonical shape at model assembly.
+            return [
+                makeObject({ kind: "sequence", ...name }, statement.text, ordinal, file, {
+                    sequenceOwnedByAmendment: { ownedBy },
+                }),
+            ];
+        }
+        case "CreateFdwStmt": {
+            const name = readString(node.fdwname);
+            return name
+                ? [makeObject({ kind: "foreign-data-wrapper", name }, statement.text, ordinal, file)]
+                : undefined;
+        }
+        case "CreateForeignServerStmt": {
+            const name = readString(node.servername);
+            return name
+                ? [makeObject({ kind: "foreign-server", name }, statement.text, ordinal, file)]
+                : undefined;
+        }
+        case "CreateForeignTableStmt": {
+            const name = rangeVarName(asRecord(node.base)?.relation);
+            if (!name) {
+                return undefined;
+            }
+            const server = readString(node.servername);
+            return [
+                makeObject({ kind: "foreign-table", ...name }, statement.text, ordinal, file, server ? { server } : {}),
+            ];
+        }
+        case "IndexStmt": {
+            const tableName = rangeVarName(node.relation);
+            const indexName = readString(node.idxname);
+            if (!tableName || !indexName) {
+                return undefined;
+            }
+            return [
+                makeObject({
+                    kind: "index",
+                    name: indexName,
+                    schema: tableName.schema,
+                    table: tableName.name,
+                }, statement.text, ordinal, file, { concurrent: readBoolean(node.concurrent) }),
+            ];
+        }
+        case "CreateFunctionStmt": {
+            const identity = functionIdentity(node.funcname, node.parameters);
+            if (!identity) {
+                return undefined;
+            }
+            const kind = readBoolean(node.is_procedure) ? "procedure" : "function";
+            return [makeObject({ kind, ...identity }, statement.text, ordinal, file)];
+        }
+        case "ViewStmt": {
+            const name = rangeVarName(node.view);
+            return name
+                ? [makeObject({ kind: "view", ...name }, statement.text, ordinal, file)]
+                : undefined;
+        }
+        case "CreateTableAsStmt": {
+            if (readString(node.objtype) !== "OBJECT_MATVIEW") {
+                return undefined;
+            }
+            const into = asRecord(node.into);
+            const name = rangeVarName(into?.rel);
+            return name
+                ? [
+                    makeObject({ kind: "materialized-view", ...name }, statement.text, ordinal, file, {
+                        withNoData: readBoolean(into?.skipData),
+                    }),
+                ]
+                : undefined;
+        }
+        case "CreateTrigStmt": {
+            const tableName = rangeVarName(node.relation);
+            const triggerName = readString(node.trigname);
+            if (!tableName || !triggerName) {
+                return undefined;
+            }
+            return [
+                makeObject({
+                    kind: "trigger",
+                    name: triggerName,
+                    schema: tableName.schema,
+                    table: tableName.name,
+                }, statement.text, ordinal, file),
+            ];
+        }
+        case "CreatePolicyStmt": {
+            const tableName = rangeVarName(node.table);
+            const policyName = readString(node.policy_name);
+            if (!tableName || !policyName) {
+                return undefined;
+            }
+            return [
+                makeObject({
+                    kind: "policy",
+                    name: policyName,
+                    schema: tableName.schema,
+                    table: tableName.name,
+                }, statement.text, ordinal, file),
+            ];
+        }
+        case "AlterTableStmt":
+            return alterTableObjects(node, statement.text, ordinal, file);
+        case "GrantStmt":
+            return grantObjectsFromAst(node, statement.text, ordinal, file);
+        case "AlterDefaultPrivilegesStmt":
+            return defaultPrivilegesFromAst(node, statement.text, ordinal, file);
+        case "CommentStmt": {
+            const object = commentObjectFromAst(node, statement.text, ordinal, file);
+            return object ? [object] : undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+function referencedSchemas(statement) {
+    const schemas = new Set();
+    for (const reference of collectReferences(statement.node)) {
+        const separator = reference.indexOf(".");
+        if (separator > 0) {
+            schemas.add(reference.slice(0, separator));
+        }
+    }
+    return [...schemas].sort((left, right) => left.localeCompare(right));
+}
+async function statementReferences(statement) {
+    const references = collectReferences(statement.node);
+    if (statement.tag === "CreateFunctionStmt") {
+        const node = asRecord(statement.node.CreateFunctionStmt);
+        for (const body of functionBodyStrings(node?.options)) {
+            const parsedBody = await parseSqlAst(body);
+            if (parsedBody.ast !== undefined) {
+                collectReferences(parsedBody.ast, references);
+            }
+        }
+    }
+    return references;
+}
+function functionBodyStrings(options) {
+    const bodies = [];
+    for (const item of readArray(options)) {
+        const defElem = asRecord(asRecord(item)?.DefElem);
+        if (readString(defElem?.defname) !== "as") {
+            continue;
+        }
+        bodies.push(...stringList(defElem?.arg));
+    }
+    return bodies;
+}
+function objectIdentity(ref) {
+    if (ref.kind === "schema") {
+        return ref.name;
+    }
+    return `${ref.schema ?? "public"}.${ref.name}`;
+}

package/dist/sql/facts.d.ts

@@ -0,0 +1,34 @@
+import type { Diagnostic, SchemaObject } from "../core.js";
+import type { AstNode } from "./ast.js";
+export interface RenderGuardFacts {
+    guard: "ifNotExists" | "orReplace";
+    offset?: number;
+    present: boolean;
+}
+export interface RoutineReturnFacts {
+    setof: boolean;
+    type: string;
+}
+export interface RoutineOutParamFacts {
+    mode: string;
+    name: string;
+    type: string;
+}
+type KeywordStep = {
+    optional?: boolean;
+    words: string[];
+};
+export interface FinalizeOptions {
+    normalize?: boolean;
+}
+export declare function finalizeObjects(objects: SchemaObject[], options?: FinalizeOptions): Promise<Diagnostic[]>;
+export declare function finalizeObject(object: SchemaObject, options?: FinalizeOptions): Promise<Diagnostic[]>;
+export declare function statementFacts(tag: string, statementNode: AstNode, sql: string): Record<string, unknown>;
+/**
+ * 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 declare function keywordOffset(sql: string, steps: KeywordStep[]): number | undefined;
+export {};
+//# sourceMappingURL=facts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../../src/sql/facts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAsBxC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,aAAa,GAAG,WAAW,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,KAAK,WAAW,GAAG;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AA+B3D,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,UAAU,EAAE,CAAC,CAUvB;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,UAAU,EAAE,CAAC,CAiCvB;AAsHD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,OAAO,EACtB,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzB;AAuJD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,GAAG,SAAS,CAcnF"}