@apso/cli 0.43.3 → 0.44.0

package/dist/lib/ddl/index.js

@@ -0,0 +1,309 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemaDdl = exports.createTableSql = exports.addConstraintSql = exports.createIndexSql = exports.createTypeSql = exports.schemaModel = exports.columnSpec = exports.enumTypeName = exports.tableName = exports.literal = exports.q = exports.constraintName = void 0;
+/**
+ * Apso's own DDL writer: the CREATE statements for a whole .apsorc schema.
+ *
+ * Column rules mirror the TypeScript entity templates (templates/entities),
+ * and names follow TypeORM's DefaultNamingStrategy (a prefix plus a sha1 of
+ * "table_columns"). A database built from this SQL therefore matches the one
+ * TypeORM builds for the generated entities, and services already deployed
+ * see no drift. test/lib/ddl/project-parity.test.ts checks that against a
+ * real scaffolded service.
+ */
+const crypto_1 = require("crypto");
+const field_1 = require("../utils/field");
+const casing_1 = require("../utils/casing");
+const relationships_1 = require("../utils/relationships");
+// TypeORM's own casing, used for join table and join column names.
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const typeormCase = require("typeorm/util/StringUtils");
+const sha1 = (s) => (0, crypto_1.createHash)("sha1").update(s).digest("hex");
+const key = (table, columns) => `${table.replace(".", "_")}_${[...columns].sort().join("_")}`;
+exports.constraintName = {
+    primaryKey: (t, cols) => "PK_" + sha1(key(t, cols)).slice(0, 27),
+    unique: (t, cols) => "UQ_" + sha1(key(t, cols)).slice(0, 27),
+    relation: (t, cols) => "REL_" + sha1(key(t, cols)).slice(0, 26),
+    foreignKey: (t, cols) => "FK_" + sha1(key(t, cols)).slice(0, 27),
+    index: (t, cols) => "IDX_" + sha1(key(t, cols)).slice(0, 26),
+};
+const q = (name) => `"${name.replace(/"/g, '""')}"`;
+exports.q = q;
+const literal = (v) => `'${v.replace(/'/g, "''")}'`;
+exports.literal = literal;
+const tableName = (e) => e.table || (0, casing_1.snakeCase)(e.name);
+exports.tableName = tableName;
+const enumTypeName = (table, column) => `${table}_${column}_enum`;
+exports.enumTypeName = enumTypeName;
+const hasDefault = (f) => f.default !== null && f.default !== undefined;
+// TypeORM quotes every default it is given except booleans.
+const quoted = (f) => hasDefault(f) ? (0, exports.literal)(String(f.default)) : undefined;
+/** One column as its entity template declares it. */
+function columnSpec(table, f) {
+    const textLike = (type) => [
+        type,
+        quoted(f),
+        Boolean(f.unique),
+    ];
+    const { length: size } = f;
+    let type;
+    let def;
+    let unique = false;
+    switch (f.type) {
+        case "text":
+        case "string":
+            [type, def, unique] = textLike("text");
+            break;
+        case "varchar":
+            [type, def, unique] = textLike(`character varying(${size || 255})`);
+            break;
+        case "char":
+            [type, def, unique] = textLike(`character(${size || 1})`);
+            break;
+        case "enum":
+            type = `"public".${(0, exports.q)((0, exports.enumTypeName)(table, f.name))}`;
+            def = quoted(f);
+            break;
+        case "integer":
+        case "bigint":
+        case "smallint":
+            type = f.type;
+            def = quoted(f);
+            break;
+        case "decimal":
+        case "numeric":
+            type = `numeric(${f.precision || 10},${f.scale || 2})`;
+            def = quoted(f);
+            break;
+        case "float":
+            type = "numeric";
+            def = quoted(f);
+            break;
+        case "double":
+            type = "double precision";
+            def = quoted(f);
+            break;
+        case "boolean":
+            type = "boolean";
+            def = String(String(f.default).toLowerCase() === "true");
+            break;
+        case "uuid":
+            type = "uuid";
+            def = hasDefault(f) ? String(f.default) : undefined;
+            break;
+        case "date":
+            type = "date";
+            break;
+        case "timestamp":
+            type = "TIMESTAMP";
+            break;
+        case "timestamptz":
+            type = "TIMESTAMP WITH TIME ZONE";
+            break;
+        case "json":
+        case "jsonb":
+            type = "jsonb";
+            break;
+        case "json-plain":
+            type = "json";
+            break;
+        default:
+            // ponytail: spatial, range and other special templates; add each with a parity case.
+            throw new Error(`The DDL writer does not support field type "${f.type}" yet (${table}.${f.name}).`);
+    }
+    let sql = `${(0, exports.q)(f.name)} ${type}`;
+    if (!f.nullable)
+        sql += " NOT NULL";
+    if (def !== undefined)
+        sql += ` DEFAULT ${def}`;
+    return {
+        sql,
+        type,
+        notNull: !f.nullable,
+        default: def,
+        unique,
+        index: Boolean(f.index),
+    };
+}
+exports.columnSpec = columnSpec;
+const cols = (c) => c.map((x) => (0, exports.q)(x)).join(", ");
+const column = (name, type, notNull, def, serial) => ({
+    name,
+    sql: `${(0, exports.q)(name)} ${serial ? "SERIAL" : type}${notNull ? " NOT NULL" : ""}${def && !serial ? ` DEFAULT ${def}` : ""}`,
+    type,
+    notNull,
+    default: def,
+    serial,
+});
+const pkColumn = (e) => { var _a, _b, _c; return (_c = (_b = ((_a = e.fields) !== null && _a !== void 0 ? _a : []).find((f) => f.primary)) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : "id"; };
+const fkType = (target) => (target === null || target === void 0 ? void 0 : target.primaryKeyType) === "uuid" ? "uuid" : "integer";
+function schemaModel(input) {
+    var _a, _b, _c, _d, _e;
+    const { entities, relationshipMap } = input;
+    const byName = new Map(entities.map((e) => [e.name, e]));
+    const model = {
+        extensions: [],
+        enums: [],
+        tables: [],
+        constraints: [],
+        indexes: [],
+    };
+    const entityTables = [];
+    const joinTables = [];
+    const inline = [];
+    const foreignKeys = [];
+    const index = (table, columns, unique = false) => model.indexes.push({
+        key: `index:${table}(${columns.join(",")})`,
+        name: exports.constraintName.index(table, columns),
+        table,
+        columns,
+        unique,
+    });
+    const unique = (table, columns, name, list = inline) => list.push({
+        key: `unique:${table}(${columns.join(",")})`,
+        name,
+        table,
+        kind: "unique",
+        columns,
+        body: `UNIQUE (${cols(columns)})`,
+    });
+    const primaryKey = (table, columns, list = inline) => list.push({
+        key: `pk:${table}`,
+        name: exports.constraintName.primaryKey(table, columns),
+        table,
+        kind: "pk",
+        columns,
+        body: `PRIMARY KEY (${cols(columns)})`,
+    });
+    const foreignKey = (table, col, target, targetCol, actions) => foreignKeys.push({
+        key: `fk:${table}(${col})->${target}`,
+        name: exports.constraintName.foreignKey(table, [col]),
+        table,
+        kind: "fk",
+        columns: [col],
+        references: target,
+        body: `FOREIGN KEY (${(0, exports.q)(col)}) REFERENCES ${(0, exports.q)(target)}(${(0, exports.q)(targetCol)}) ${actions}`,
+    });
+    for (const e of entities) {
+        const table = (0, exports.tableName)(e);
+        const t = { name: table, columns: [] };
+        const customPk = ((_a = e.fields) !== null && _a !== void 0 ? _a : []).some((f) => f.primary);
+        if (!customPk) {
+            const pkType = e.primaryKeyType || "serial";
+            if (pkType === "uuid") {
+                model.extensions.push(`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`);
+                t.columns.push(column("id", "uuid", true, "uuid_generate_v4()"));
+            }
+            else if (pkType === "text")
+                t.columns.push(column("id", "text", true));
+            else
+                t.columns.push(column("id", "integer", true, `nextval('${table}_id_seq'::regclass)`, true));
+        }
+        if (e.created_at)
+            t.columns.push(column("created_at", "TIMESTAMP", true, "now()"));
+        if (e.updated_at)
+            t.columns.push(column("updated_at", "TIMESTAMP", true, "now()"));
+        for (const f of (0, field_1.getFieldForTemplate)((_b = e.fields) !== null && _b !== void 0 ? _b : [], e.name)) {
+            if (!customPk && f.name === "id")
+                continue;
+            if (e.created_at && f.name === "created_at")
+                continue;
+            if (e.updated_at && f.name === "updated_at")
+                continue;
+            if (f.type === "enum" && f.values)
+                model.enums.push({
+                    name: (0, exports.enumTypeName)(table, f.name),
+                    values: [...f.values],
+                });
+            const spec = columnSpec(table, f);
+            t.columns.push(column(f.name, spec.type, spec.notNull, spec.default));
+            if (spec.unique)
+                unique(table, [f.name], exports.constraintName.unique(table, [f.name]));
+            if (spec.index)
+                index(table, [f.name]);
+        }
+        for (const i of (_c = e.indexes) !== null && _c !== void 0 ? _c : [])
+            index(table, i.fields, i.unique);
+        for (const u of (_d = e.uniques) !== null && _d !== void 0 ? _d : [])
+            unique(table, u.fields, u.name || exports.constraintName.unique(table, u.fields));
+        for (const r of (0, relationships_1.getRelationshipForTemplate)(e.name, relationshipMap[e.name] || [], entities)) {
+            const target = byName.get(r.name);
+            if (!target)
+                continue;
+            const targetTable = (0, exports.tableName)(target);
+            // The template gives OneToOne onDelete CASCADE and a nullable join column.
+            const oneToOne = r.type === "OneToOne";
+            const onDelete = r.cascadeDelete || oneToOne ? "CASCADE" : "NO ACTION";
+            if (r.type === "ManyToOne" || (oneToOne && r.joinTable)) {
+                const col = r.type === "ManyToOne"
+                    ? r.camelCasedId
+                    : typeormCase.camelCase(`${r.relationshipName}_id`);
+                t.columns.push(column(col, fkType(target), !(r.nullable || oneToOne)));
+                if (oneToOne)
+                    unique(table, [col], exports.constraintName.relation(table, [col]));
+                if (r.type === "ManyToOne" && r.index)
+                    index(table, [col]);
+                foreignKey(table, col, targetTable, pkColumn(target), `ON DELETE ${onDelete} ON UPDATE NO ACTION`);
+            }
+            if (r.type === "ManyToMany" && r.joinTable) {
+                const join = r.joinTableName ||
+                    typeormCase.snakeCase(`${table}_${r.pluralizedRelationshipName}_${targetTable}`);
+                const ownCol = r.joinColumnName || typeormCase.camelCase(`${table}_${pkColumn(e)}`);
+                const otherCol = r.inverseJoinColumnName ||
+                    typeormCase.camelCase(`${targetTable}_${pkColumn(target)}`);
+                joinTables.push({
+                    name: join,
+                    columns: [
+                        column(ownCol, fkType(e), true),
+                        column(otherCol, fkType(target), true),
+                    ],
+                });
+                primaryKey(join, [ownCol, otherCol]);
+                index(join, [ownCol]);
+                index(join, [otherCol]);
+                // TypeORM cascades the inverse key only when no inverse relation exists.
+                const inverse = r.biDirectional ? "NO ACTION" : "CASCADE";
+                foreignKey(join, ownCol, table, pkColumn(e), "ON DELETE CASCADE ON UPDATE CASCADE");
+                foreignKey(join, otherCol, targetTable, pkColumn(target), `ON DELETE ${inverse} ON UPDATE ${inverse}`);
+            }
+        }
+        primaryKey(table, customPk
+            ? ((_e = e.fields) !== null && _e !== void 0 ? _e : []).filter((f) => f.primary).map((f) => f.name)
+            : ["id"]);
+        entityTables.unshift(t);
+    }
+    model.extensions = [...new Set(model.extensions)];
+    model.tables = [...entityTables, ...joinTables];
+    model.constraints = [...inline, ...foreignKeys];
+    return model;
+}
+exports.schemaModel = schemaModel;
+const createTypeSql = (e) => `CREATE TYPE "public".${(0, exports.q)(e.name)} AS ENUM(${e.values
+    .map((v) => (0, exports.literal)(v))
+    .join(", ")})`;
+exports.createTypeSql = createTypeSql;
+const createIndexSql = (i) => `CREATE ${i.unique ? "UNIQUE " : ""}INDEX ${(0, exports.q)(i.name)} ON ${(0, exports.q)(i.table)} (${cols(i.columns)})`;
+exports.createIndexSql = createIndexSql;
+const addConstraintSql = (c) => `ALTER TABLE ${(0, exports.q)(c.table)} ADD CONSTRAINT ${(0, exports.q)(c.name)} ${c.body}`;
+exports.addConstraintSql = addConstraintSql;
+const createTableSql = (t, constraints) => `CREATE TABLE ${(0, exports.q)(t.name)} (${[
+    ...t.columns.map((c) => c.sql),
+    ...constraints
+        .filter((c) => c.table === t.name && c.kind !== "fk")
+        .map((c) => `CONSTRAINT ${(0, exports.q)(c.name)} ${c.body}`),
+].join(", ")})`;
+exports.createTableSql = createTableSql;
+/** CREATE statements for every enum type, table, index and foreign key. */
+function schemaDdl(input) {
+    const m = schemaModel(input);
+    return [
+        ...m.extensions,
+        ...m.enums.map((e) => (0, exports.createTypeSql)(e)),
+        ...m.tables.map((t) => (0, exports.createTableSql)(t, m.constraints)),
+        ...m.indexes.map((i) => (0, exports.createIndexSql)(i)),
+        ...m.constraints
+            .filter((c) => c.kind === "fk")
+            .map((c) => (0, exports.addConstraintSql)(c)),
+    ];
+}
+exports.schemaDdl = schemaDdl;

package/dist/lib/ddl/migration-file.d.ts

@@ -0,0 +1,42 @@
+import { ApsorcType } from "../apsorc-parser";
+import { Question } from "../plan";
+import { Finding } from "../verify/review";
+import { DownDdl } from "./change";
+export declare function typeormMigration(className: string, up: string[], down: DownDdl): string;
+/**
+ * A Python string literal for any SQL. A JSON string is one (same escapes),
+ * where """...""" breaks on SQL that ends in a quoted identifier (#148).
+ */
+export declare const pyString: (s: string) => string;
+export declare function alembicMigration(revision: string, downRevision: string | undefined, up: string[], down: DownDdl): string;
+/**
+ * Statements for a goose SQL file. goose splits on lines ending in ";", so a
+ * statement with a ";" of its own is fenced with StatementBegin/End.
+ */
+export declare const gooseStatements: (statements: string[]) => string;
+export declare function gooseMigration(up: string[], down: DownDdl): string;
+/** The newest Alembic revision: the one no other revision names as its down_revision. */
+export declare function alembicHead(dir: string): string | undefined;
+/**
+ * The up and down SQL of an Alembic or goose migration, for running it on a
+ * database without the framework. down is undefined when it refuses to run.
+ */
+export declare function migrationSql(file: string, source: string): {
+    up: string;
+    down?: string;
+};
+export interface PlannedMigration {
+    ok: boolean;
+    needed: boolean;
+    /** Questions still open in the plan; nothing is written while any are. */
+    open?: Question[];
+    file?: string;
+    planFile?: string;
+    findings?: Finding[];
+    steps: {
+        name: string;
+        ok: boolean;
+        output?: string;
+    }[];
+}
+export declare function writePlannedMigration(projectDir: string, before: ApsorcType, name: string, planPath: string, now?: number): PlannedMigration;

package/dist/lib/ddl/migration-file.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writePlannedMigration = exports.migrationSql = exports.alembicHead = exports.gooseMigration = exports.gooseStatements = exports.alembicMigration = exports.pyString = exports.typeormMigration = void 0;
+const tslib_1 = require("tslib");
+/**
+ * Write a migration from an answered plan: up is Apso's change DDL, down the
+ * reverse, and the plan is saved beside the migration so the answers that
+ * produced it stay with it. The SQL is the same for every language; only the
+ * wrapper differs: a TypeORM class, an Alembic revision, or a goose SQL file.
+ */
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const plan_1 = require("../plan");
+const baseline_1 = require("../plan/baseline");
+const casing_1 = require("../utils/casing");
+const review_1 = require("../verify/review");
+const change_1 = require("./change");
+const _1 = require(".");
+const template = (sql) => "`" +
+    sql.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\${/g, "\\${") +
+    "`";
+const queries = (statements) => statements
+    .map((s) => `        await queryRunner.query(${template(s)});`)
+    .join("\n");
+function typeormMigration(className, up, down) {
+    const downBody = "down" in down
+        ? queries(down.down)
+        : `        throw new Error(${JSON.stringify(irreversible(down))});`;
+    return `import { MigrationInterface, QueryRunner } from "typeorm";
+
+// Generated by apso migrate generate from the answered migration plan saved beside this file.
+export class ${className} implements MigrationInterface {
+    name = '${className}'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+${queries(up)}
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+${downBody}
+    }
+
+}
+`;
+}
+exports.typeormMigration = typeormMigration;
+const irreversible = (down) => `This migration can't be reversed automatically: ${down.irreversible.join("; ")}`;
+/**
+ * A Python string literal for any SQL. A JSON string is one (same escapes),
+ * where """...""" breaks on SQL that ends in a quoted identifier (#148).
+ */
+const pyString = (s) => JSON.stringify(s);
+exports.pyString = pyString;
+const executes = (statements) => statements.map((s) => `    op.execute(${(0, exports.pyString)(s)})`).join("\n");
+function alembicMigration(revision, downRevision, up, down) {
+    const downBody = "down" in down
+        ? executes(down.down) || "    pass"
+        : `    raise NotImplementedError(${(0, exports.pyString)(irreversible(down))})`;
+    return `"""Generated by apso migrate generate from the answered migration plan saved beside this file."""
+from alembic import op
+
+revision = ${(0, exports.pyString)(revision)}
+down_revision = ${downRevision === undefined ? "None" : (0, exports.pyString)(downRevision)}
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+${executes(up)}
+
+
+def downgrade() -> None:
+${downBody}
+`;
+}
+exports.alembicMigration = alembicMigration;
+/**
+ * Statements for a goose SQL file. goose splits on lines ending in ";", so a
+ * statement with a ";" of its own is fenced with StatementBegin/End.
+ */
+const gooseStatements = (statements) => statements
+    .map((s) => s.includes(";")
+    ? `-- +goose StatementBegin\n${s};\n-- +goose StatementEnd`
+    : `${s};`)
+    .join("\n");
+exports.gooseStatements = gooseStatements;
+function gooseMigration(up, down) {
+    // goose has no way to refuse a down, so the SQL refuses it instead.
+    const downBody = "down" in down
+        ? (0, exports.gooseStatements)(down.down)
+        : (0, exports.gooseStatements)([
+            `DO $$ BEGIN RAISE EXCEPTION ${(0, _1.literal)(irreversible(down).replace(/%/g, "%%"))}; END $$`,
+        ]);
+    return `-- Generated by apso migrate generate from the answered migration plan saved beside this file.
+-- +goose Up
+${(0, exports.gooseStatements)(up)}
+
+-- +goose Down
+${downBody}
+`;
+}
+exports.gooseMigration = gooseMigration;
+/** The newest Alembic revision: the one no other revision names as its down_revision. */
+function alembicHead(dir) {
+    var _a;
+    if (!fs.existsSync(dir))
+        return undefined;
+    const revisions = [];
+    const downs = new Set();
+    for (const f of fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".py"))
+        .sort()) {
+        const source = fs.readFileSync(path.join(dir, f)).toString();
+        const rev = source.match(/^revision\b[^\n=]*=\s*["']([^"']+)["']/m);
+        if (rev)
+            revisions.push(rev[1]);
+        const down = source.match(/^down_revision\b[^\n=]*=(.*)$/m);
+        for (const d of (_a = down === null || down === void 0 ? void 0 : down[1].matchAll(/["']([^"']+)["']/g)) !== null && _a !== void 0 ? _a : [])
+            downs.add(d[1]);
+    }
+    return revisions.filter((r) => !downs.has(r)).pop();
+}
+exports.alembicHead = alembicHead;
+const calls = (body) => [...body.matchAll(/^\s*op\.execute\((".*")\)\s*$/gm)]
+    .map((m) => JSON.parse(m[1]))
+    .join(";\n");
+/**
+ * The up and down SQL of an Alembic or goose migration, for running it on a
+ * database without the framework. down is undefined when it refuses to run.
+ */
+function migrationSql(file, source) {
+    if (file.endsWith(".sql")) {
+        const [up, down = ""] = source
+            .split(/^-- \+goose Down\b.*$/m)
+            .map((s) => s.replace(/^[\S\s]*?^-- \+goose Up\b.*$/m, ""));
+        return { up, down: /RAISE EXCEPTION/.test(down) ? undefined : down };
+    }
+    const [upBody, downBody = ""] = source.split(/^def downgrade\b/m);
+    return {
+        up: calls(upBody),
+        down: /raise NotImplementedError/.test(downBody) ? undefined : calls(downBody),
+    };
+}
+exports.migrationSql = migrationSql;
+function writePlannedMigration(projectDir, before, name, planPath, now = Date.now()) {
+    const after = JSON.parse(fs.readFileSync(path.join(projectDir, ".apsorc")).toString());
+    const previous = fs.existsSync(planPath)
+        ? JSON.parse(fs.readFileSync(planPath).toString())
+        : undefined;
+    const plan = (0, plan_1.planMigration)(before, after, previous);
+    fs.mkdirSync(path.dirname(planPath), { recursive: true });
+    fs.writeFileSync(planPath, JSON.stringify({ ...plan, before }, null, 2) + "\n");
+    const open = (0, plan_1.openQuestions)(plan);
+    if (open.length > 0)
+        return {
+            ok: false,
+            needed: true,
+            open,
+            steps: [
+                {
+                    name: "plan",
+                    ok: false,
+                    output: `${open.length} question(s) in ${path.relative(projectDir, planPath)} are open. Answer them with apso migrate plan --answer, then generate again.`,
+                },
+            ],
+        };
+    let up;
+    let down;
+    try {
+        up = (0, change_1.changeDdl)(before, after, plan).up;
+        down = (0, change_1.downDdl)(before, after, plan);
+    }
+    catch (error) {
+        const output = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            needed: true,
+            steps: [
+                {
+                    name: "render",
+                    ok: false,
+                    output: `${output}\nTo use TypeORM's generator instead, rerun with --typeorm.`,
+                },
+            ],
+        };
+    }
+    if (up.length === 0)
+        return { ok: true, needed: false, steps: [{ name: "render", ok: true }] };
+    const className = `${(0, casing_1.pascalCase)(name)}Migration${now}`;
+    const dir = (0, baseline_1.migrationsDir)(projectDir, after);
+    fs.mkdirSync(dir, { recursive: true });
+    // goose orders by the number before "_", and its own files use
+    // YYYYMMDDHHMMSS, so Python and Go use that too.
+    const stamp = new Date(now).toISOString().replace(/\D/g, "").slice(0, 14);
+    const base = after.language === "python" || after.language === "go"
+        ? `${stamp}_${(0, casing_1.snakeCase)(name)}`
+        : `${now}-${name}-migration`;
+    const file = base + (0, baseline_1.migrationExtension)(after);
+    const source = after.language === "python"
+        ? alembicMigration(stamp, alembicHead(dir), up, down)
+        : after.language === "go"
+            ? gooseMigration(up, down)
+            : typeormMigration(className, up, down);
+    fs.writeFileSync(path.join(dir, file), source);
+    fs.writeFileSync(path.join(dir, `${base}.plan.json`), 
+    // The schemas let later runs find the baseline without being told.
+    JSON.stringify({ ...plan, before, after }, null, 2) + "\n");
+    // The answers now live beside the migration; the next change starts fresh.
+    fs.rmSync(planPath, { force: true });
+    const rel = (f) => path.relative(projectDir, path.join(dir, f));
+    return {
+        ok: true,
+        needed: true,
+        file: rel(file),
+        planFile: rel(`${base}.plan.json`),
+        // The review reads TypeORM's wrapper; the SQL is the same in all three.
+        findings: (0, review_1.reviewMigration)(typeormMigration(className, up, down)),
+        steps: [{ name: "render", ok: true }],
+    };
+}
+exports.writePlannedMigration = writePlannedMigration;

package/dist/lib/generators/go.js

@@ -9,6 +9,7 @@ const field_1 = require("../utils/field");
 const relationships_1 = require("../utils/relationships");
 const casing_1 = require("../utils/casing");
 const events_1 = require("../events");
+const migration_file_1 = require("../ddl/migration-file");
 const pluralize_1 = tslib_1.__importDefault(require("pluralize"));
 /**
  * Go/Gin generator that produces GORM models, DTOs, Gin handlers,
@@ -293,8 +294,8 @@ class GoGenerator extends base_1.BaseGenerator {
             .slice(0, 14);
         const name = migrationName || "auto";
         const filename = `${timestamp}_${name}.sql`;
-        const upStatements = upSql.map((sql) => `${sql};`).join("\n");
-        const downStatements = (downSql || []).map((sql) => `${sql};`).join("\n");
+        const upStatements = (0, migration_file_1.gooseStatements)(upSql);
+        const downStatements = (0, migration_file_1.gooseStatements)(downSql || []);
         const content = `-- +goose Up
 ${upStatements}
 

package/dist/lib/generators/python.js

@@ -9,6 +9,7 @@ const field_1 = require("../utils/field");
 const relationships_1 = require("../utils/relationships");
 const casing_1 = require("../utils/casing");
 const events_1 = require("../events");
+const migration_file_1 = require("../ddl/migration-file");
 const pluralize_1 = tslib_1.__importDefault(require("pluralize"));
 /**
  * Python/FastAPI generator that produces SQLAlchemy models, Pydantic schemas,
@@ -225,10 +226,10 @@ class PythonGenerator extends base_1.BaseGenerator {
         const name = migrationName || "auto";
         const filename = `${timestamp}_${name}.py`;
         const upStatements = upSql
-            .map((sql) => `    op.execute("""${sql}""")`)
+            .map((sql) => `    op.execute(${(0, migration_file_1.pyString)(sql)})`)
             .join("\n");
         const downStatements = (downSql || [])
-            .map((sql) => `    op.execute("""${sql}""")`)
+            .map((sql) => `    op.execute(${(0, migration_file_1.pyString)(sql)})`)
             .join("\n");
         const content = `"""${name}"""
 from alembic import op

package/dist/lib/plan/baseline.d.ts

@@ -0,0 +1,22 @@
+import { ApsorcType } from "../apsorc-parser";
+export interface SavedPlan {
+    before: ApsorcType;
+    after: ApsorcType;
+}
+export interface Baseline {
+    schema: ApsorcType;
+    /** Where the schema came from, for messages. */
+    source: string;
+}
+/** Where each language's migrations live, and the extension of one. */
+export declare const migrationsDir: (projectDir: string, apsorc?: ApsorcType) => string;
+export declare const migrationExtension: (apsorc?: ApsorcType) => ".ts" | ".py" | ".sql";
+/** The newest migration with a saved plan, by its timestamp prefix. */
+export declare function latestPlannedMigration(projectDir: string, apsorc?: ApsorcType): {
+    file: string;
+    planFile: string;
+    saved: SavedPlan;
+} | undefined;
+export declare function resolveBaseline(projectDir: string, apsorc: ApsorcType, explicit?: string, planPath?: string): Baseline;
+/** A baseline as a file, for steps that scaffold it into a project copy. */
+export declare function baselineFile(baseline: Baseline): string;