@intentius/sql-yodeler 0.0.0-stage → 0.1.0

package/dist/commands/rebase.js

@@ -0,0 +1,167 @@
+import { parseArgs } from "node:util";
+import { guarded } from "../env-args.js";
+import { loadProject, resolveEnvironment, YodelError } from "../project.js";
+import { MigrationDirectoryError, refusedSteps, scanMigrations } from "../migrations/index.js";
+import { closeVersioned, migrationsDir, openVersioned } from "../versioned/index.js";
+import { planRebase, REBASE_REFUSED, writeRebase } from "../rebase/index.js";
+const usage = "usage: yodel rebase [<id>] [--onto <parent-id>] [--env <env>]... [--force] [--json] [--dir <project>]";
+const help = `${usage}
+
+Moves a migration onto another parent and rewrites it, so two branches that
+each added a migration can both merge. With no <id>, the directory's one
+fork (two migrations that follow the same parent) is resolved: the newer of
+the two (by the timestamp in its id) moves onto the end of the other's
+branch. Name <id> to move another one, and --onto to choose its new parent.
+Migrations that follow the moved one move with it.
+
+Each moved migration's change (its recorded schema against its old
+parent's) is applied to its new parent's recorded schema, giving its new
+recorded schema; its statements are diffed again from the new parent's, and
+its migration.sql, migration.json and checksum are written again. When both
+branches change the same object, differently, nothing is written and the
+object is named: resolve it by hand (delete the migration, then yodel new).
+Each -- yodel:allow line is carried over to the same statement in the new
+migration.sql; when that statement is gone or changed, nothing is written
+and the line is named.
+Offline: no database is read, except the histories --env names.
+
+Ids do not change. The order is the chain of parent ids, not the ids'
+timestamps, so a rebased migration runs after its new parent whatever its
+timestamp says, and anything that names it still does.
+
+Options:
+  --onto <id>      the new parent (default: the end of the other branch)
+  --env <env>      refuse if this environment's history records a migration
+                   the rebase would rewrite; repeat for more environments.
+                   Without it, no history is checked: never rebase a
+                   migration that ran somewhere
+  --force          rewrite migrations whose files were edited by hand (the
+                   edits are dropped; well-formed -- yodel:allow lines are
+                   still carried over)
+  --json           print what was rewritten as JSON
+  -C, --dir <dir>  the project directory (default: the working directory)
+
+Exit codes:
+  0  rebased, or no fork to rebase
+  4  refused, nothing written: both branches change the same object, a
+     migration to rewrite was edited by hand (without --force), a
+     yodel:allow line's statement is gone or changed, a history records one
+     of them, or the moved migration adds nothing on its new parent
+  1  the rebase could not be worked out: no such migration, a fork the
+     defaults cannot settle, a bad config, a server that does not answer
+`;
+function parseRebaseArgs(args) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                onto: { type: "string" },
+                env: { type: "string", multiple: true },
+                force: { type: "boolean" },
+                json: { type: "boolean" },
+                dir: { type: "string", short: "C" },
+            },
+        });
+    }
+    catch (e) {
+        throw new YodelError(`${e instanceof Error ? e.message : String(e)}\n${usage}`);
+    }
+    const { values, positionals } = parsed;
+    if (positionals.length > 1)
+        throw new YodelError(usage);
+    const envs = Array.isArray(values.env) ? values.env.filter((e) => typeof e === "string") : [];
+    return {
+        id: positionals[0],
+        onto: typeof values.onto === "string" ? values.onto : undefined,
+        envs,
+        force: values.force === true,
+        json: values.json === true,
+        dir: typeof values.dir === "string" ? values.dir : process.cwd(),
+    };
+}
+/** Refuses when an environment's history names a migration the rebase would rewrite. */
+async function checkHistories(project, envs, plan) {
+    for (const name of envs) {
+        const env = resolveEnvironment(project, name);
+        const venv = await openVersioned(project, env);
+        const state = await venv.store.state().finally(() => closeVersioned(venv));
+        const ran = plan.rewritten.flatMap((m) => {
+            const rec = state.byId.get(m.id);
+            return rec ? [`${m.id} (${rec.status === "succeeded" ? "applied" : `ran part way, ${rec.status}`})`] : [];
+        });
+        if (ran.length > 0) {
+            throw new YodelError(`refused: ${name}'s history records ${ran.join(", ")}. Nothing was written. A migration that ran is never rebased: ` +
+                `its statements already ran in that order. Rebase the other branch onto it instead (yodel rebase <the other> --onto <the end of this one>).`, REBASE_REFUSED);
+        }
+    }
+}
+function report(io, json, plan, envs) {
+    if (json) {
+        io.out(`${JSON.stringify({
+            rebased: true,
+            moved: plan.moved,
+            from: plan.from,
+            onto: plan.onto,
+            historiesChecked: envs,
+            rewritten: plan.rewritten.map((m) => ({
+                id: m.id,
+                path: m.dir,
+                oldParent: m.oldParent,
+                parent: m.parent,
+                oldChecksum: m.oldChecksum,
+                checksum: m.checksum,
+                statements: m.statements.steps.length - refusedSteps(m.statements.steps).length,
+                refused: m.statements.refused,
+                silences: m.silences.map((x) => ({ step: x.step, rule: x.rule, reason: x.reason, line: x.line })),
+                handEdited: m.handEdited,
+            })),
+        }, null, 2)}\n`);
+        return;
+    }
+    const lines = [`Rebased ${plan.moved} onto ${plan.onto} (it followed ${plan.from ?? "nothing"}).`];
+    for (const m of plan.rewritten) {
+        const n = m.statements.steps.length - refusedSteps(m.statements.steps).length;
+        lines.push(`  ${m.id}: follows ${m.parent}; ${String(n)} statement${n === 1 ? "" : "s"}${m.statements.refused ? " and an Op or manual step" : ""}${m.silences.length > 0 ? `; ${String(m.silences.length)} yodel:allow line${m.silences.length === 1 ? "" : "s"} carried over` : ""}; checksum ${m.oldChecksum} -> ${m.checksum}`);
+        for (const h of m.statements.hints)
+            lines.push(`    hint: ${h}`);
+    }
+    lines.push(envs.length > 0
+        ? `Checked against the history of ${envs.join(", ")}: none of them had run.`
+        : "No history was checked (--env): make sure none of these ran anywhere before merging.");
+    io.out(`${lines.join("\n")}\n`);
+}
+/** `yodel rebase`; the exit codes are in `help`. */
+export const rebase = {
+    name: "rebase",
+    summary: "move a migration onto a new parent and recompute its schema",
+    implemented: true,
+    run: (args, io) => guarded("rebase", io, args, help, async () => {
+        const options = parseRebaseArgs(args);
+        const project = await loadProject(options.dir);
+        const scan = scanMigrations(migrationsDir(project));
+        const structural = scan.problems.filter((p) => p.kind === "unreadable" || p.kind === "id-mismatch" || p.kind === "missing-parent");
+        if (structural.length > 0)
+            throw new MigrationDirectoryError(scan.dir, structural);
+        const plan = planRebase(scan.migrations, { id: options.id, onto: options.onto });
+        if (plan.moved === undefined) {
+            if (options.json)
+                io.out(`${JSON.stringify({ rebased: false }, null, 2)}\n`);
+            else
+                io.out("No fork: every migration follows a different parent. Nothing to rebase.\n");
+            return 0;
+        }
+        const edited = plan.rewritten.filter((m) => m.handEdited);
+        if (edited.length > 0 && !options.force) {
+            throw new YodelError(`refused: ${edited.map((m) => m.id).join(", ")} ${edited.length === 1 ? "has" : "have"} files that differ from what yodel wrote (an edit by hand, or a checksum that no longer matches). ` +
+                `Rebasing writes them again from their recorded schema and drops that edit. Nothing was written; pass --force to rebase anyway, then make the edit again.`, REBASE_REFUSED);
+        }
+        await checkHistories(project, options.envs, plan);
+        writeRebase(plan);
+        report(io, options.json, plan, options.envs);
+        return 0;
+    }),
+};
+//# sourceMappingURL=rebase.js.map

package/dist/commands/rebase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebase.js","sourceRoot":"","sources":["../../src/commands/rebase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,UAAU,EAAgB,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,uBAAuB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC/F,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AAE9F,MAAM,KAAK,GAAG,uGAAuG,CAAC;AAEtH,MAAM,IAAI,GAAG,GAAG,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CpB,CAAC;AAWF,SAAS,eAAe,CAAC,IAAc;IACrC,IAAI,MAAoC,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC;YACjB,IAAI;YACJ,gBAAgB,EAAE,IAAI;YACtB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE;gBACP,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACxB,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;gBACvC,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;gBAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;gBACzB,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE;aACpC;SACF,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,UAAU,CAAC,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IACvC,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3G,OAAO;QACL,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC;QAClB,IAAI,EAAE,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QAC/D,IAAI;QACJ,KAAK,EAAE,MAAM,CAAC,KAAK,KAAK,IAAI;QAC5B,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,IAAI;QAC1B,GAAG,EAAE,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;KACjE,CAAC;AACJ,CAAC;AAED,wFAAwF;AACxF,KAAK,UAAU,cAAc,CAAC,OAAgB,EAAE,IAAuB,EAAE,IAAgB;IACvF,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC9C,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3E,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;YACvC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACjC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5G,CAAC,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,UAAU,CAClB,YAAY,IAAI,sBAAsB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,gEAAgE;gBAClH,4IAA4I,EAC9I,cAAc,CACf,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CAAC,EAAM,EAAE,IAAa,EAAE,IAAgB,EAAE,IAAuB;IAC9E,IAAI,IAAI,EAAE,CAAC;QACT,EAAE,CAAC,GAAG,CACJ,GAAG,IAAI,CAAC,SAAS,CACf;YACE,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,gBAAgB,EAAE,IAAI;YACtB,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACpC,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,IAAI,EAAE,CAAC,CAAC,GAAG;gBACX,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM;gBAC/E,OAAO,EAAE,CAAC,CAAC,UAAU,CAAC,OAAO;gBAC7B,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBACjG,UAAU,EAAE,CAAC,CAAC,UAAU;aACzB,CAAC,CAAC;SACJ,EACD,IAAI,EACJ,CAAC,CACF,IAAI,CACN,CAAC;QACF,OAAO;IACT,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,WAAW,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,IAAI,iBAAiB,IAAI,CAAC,IAAI,IAAI,SAAS,IAAI,CAAC,CAAC;IACnG,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;QAC9E,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,WAAW,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QACnU,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,MAAM,GAAG,CAAC;QACb,CAAC,CAAC,kCAAkC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,yBAAyB;QAC5E,CAAC,CAAC,sFAAsF,CAC3F,CAAC;IACF,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,oDAAoD;AACpD,MAAM,CAAC,MAAM,MAAM,GAAY;IAC7B,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,6DAA6D;IACtE,WAAW,EAAE,IAAI;IACjB,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAChB,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,IAAI,EAAE;QAC3C,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,cAAc,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;QACpD,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,CAAC,IAAI,KAAK,gBAAgB,CAAC,CAAC;QACnI,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,uBAAuB,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QAEnF,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACjF,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,OAAO,CAAC,IAAI;gBAAE,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;;gBACxE,EAAE,CAAC,GAAG,CAAC,2EAA2E,CAAC,CAAC;YACzF,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QAC1D,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACxC,MAAM,IAAI,UAAU,CAClB,YAAY,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,oGAAoG;gBACxL,0JAA0J,EAC5J,cAAc,CACf,CAAC;QACJ,CAAC;QACD,MAAM,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAClD,WAAW,CAAC,IAAI,CAAC,CAAC;QAClB,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7C,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;CACL,CAAC"}

package/dist/commands/repair.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "../command.js";
+/** `yodel repair <id> --reason ... <env>`; the exit codes are in `help`. */
+export declare const repair: Command;

package/dist/commands/repair.js

@@ -0,0 +1,117 @@
+import { renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { guarded } from "../env-args.js";
+import { loadProject, resolveEnvironment, YodelError } from "../project.js";
+import { MIGRATION_JSON, scanMigrations, serializeDocument, verifyChecksum } from "../migrations/index.js";
+import { appliedBy, newRunContext, withLock } from "../history/index.js";
+import { closeVersioned, migrationsDir, openVersioned } from "../versioned/index.js";
+import { checkRepair, repairRow } from "../rebase/repair.js";
+const usage = 'usage: yodel repair <id> --reason "<text>" <env> [--json] [--dir <project>]';
+const help = `${usage}
+
+Records an intended edit to a migration that is already applied in <env>:
+appends a row to the environment's history table (yodel.config.ts
+history.database, else YODEL_HISTORY_DATABASE, default yodeler; on
+Postgres the schema of that name) with the
+checksum the migration's files have now and the reason, under the apply lock. After it, yodel status and yodel apply compare
+the files with the new checksum. Nothing is run on the server: the edit is
+recorded, not applied. Repair each environment the migration ran in.
+
+When migration.json's own checksum field is stale too (it is not part of
+what the checksum covers), it is written again to match.
+
+Options:
+  --reason <text>  why the files changed; required, and kept in the history
+  --json           print the repair as JSON
+  -C, --dir <dir>  the project directory (default: the working directory)
+
+Exit codes:
+  0  the new checksum is recorded
+  4  refused, nothing written: the migration is not applied in <env> (not
+     run, or part way), its files already match the history, or it is gone
+     from the directory
+  5  another apply holds the lock
+  1  anything else: no --reason, a bad config, a server that does not answer
+`;
+function parseRepairArgs(args) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args,
+            allowPositionals: true,
+            strict: true,
+            options: { reason: { type: "string" }, json: { type: "boolean" }, dir: { type: "string", short: "C" } },
+        });
+    }
+    catch (e) {
+        throw new YodelError(`${e instanceof Error ? e.message : String(e)}\n${usage}`);
+    }
+    const { values, positionals } = parsed;
+    const [id, env, ...rest] = positionals;
+    if (id === undefined || env === undefined || rest.length > 0)
+        throw new YodelError(usage);
+    const reason = typeof values.reason === "string" ? values.reason.trim() : "";
+    if (reason === "")
+        throw new YodelError(`a repair needs a reason: --reason "<why the files changed>"\n${usage}`);
+    return { id, env, reason, json: values.json === true, dir: typeof values.dir === "string" ? values.dir : process.cwd() };
+}
+/** Writes migration.json again with its checksum field matching its files, when it does not. Returns whether it wrote. */
+function syncRecordedChecksum(m) {
+    const check = verifyChecksum(m);
+    if (check.ok)
+        return false;
+    const path = join(m.dir, MIGRATION_JSON);
+    const tmp = join(m.dir, `.${MIGRATION_JSON}.repairing`);
+    writeFileSync(tmp, serializeDocument({ ...JSON.parse(m.files.json), checksum: check.actual }));
+    renameSync(tmp, path);
+    return true;
+}
+/** `yodel repair <id> --reason ... <env>`; the exit codes are in `help`. */
+export const repair = {
+    name: "repair",
+    summary: "record a new checksum for an applied migration, with a reason",
+    implemented: true,
+    run: (args, io) => guarded("repair", io, args, help, async () => {
+        const { id, env: name, reason, json, dir } = parseRepairArgs(args);
+        const project = await loadProject(dir);
+        const env = resolveEnvironment(project, name);
+        const m = scanMigrations(migrationsDir(project)).migrations.find((x) => x.id === id);
+        const venv = await openVersioned(project, env);
+        try {
+            return await repairWith(venv, m, { id, envName: env.name, reason, json, io });
+        }
+        finally {
+            await closeVersioned(venv);
+        }
+    }),
+};
+async function repairWith(venv, m, { id, envName, reason, json, io }) {
+    checkRepair(m, id, await venv.store.state(), envName); // refuse before taking the lock
+    const lock = await venv.driver.acquireLock(appliedBy());
+    if (lock.notice && !json)
+        io.err(`lock: ${lock.notice}\n`);
+    const row = await withLock(lock, venv.lockTtlMs, async () => {
+        const state = await venv.store.state();
+        const check = checkRepair(m, id, state, envName);
+        const r = repairRow({ migration: m, check, reason, run: newRunContext(check.record.planDigest), seq: state.maxSeq + 1 });
+        await venv.store.append([r]);
+        return { r, check };
+    });
+    const synced = syncRecordedChecksum(m);
+    if (json) {
+        io.out(`${JSON.stringify({ repaired: true, id, environment: envName, oldChecksum: row.check.oldChecksum, newChecksum: row.check.newChecksum, reason, seq: row.r.seq, runId: row.r.run_id, migrationJsonUpdated: synced }, null, 2)}\n`);
+    }
+    else {
+        io.out([
+            `Repaired ${id} in ${envName}'s history (${venv.location.database}).`,
+            `  old checksum: ${row.check.oldChecksum}`,
+            `  new checksum: ${row.check.newChecksum}`,
+            `  reason: ${reason}`,
+            ...(synced ? [`  ${MIGRATION_JSON}'s checksum field updated to match`] : []),
+            "",
+        ].join("\n"));
+    }
+    return 0;
+}
+//# sourceMappingURL=repair.js.map

package/dist/commands/repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.js","sourceRoot":"","sources":["../../src/commands/repair.ts"],"names":[],"mappings":"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"}

package/dist/commands/status.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from "../command.js";
+/** Exit code: migrations are pending, and nothing is wrong. */
+export declare const STATUS_PENDING = 3;
+/** Exit code: a checksum mismatch, an applied migration gone from the directory, or an out-of-order migration. */
+export declare const STATUS_REFUSED = 4;
+/** `yodel status <env>`; the exit codes are in `help`. */
+export declare const status: Command;

package/dist/commands/status.js

@@ -0,0 +1,54 @@
+import { guarded, parseEnvArgs, usage } from "../env-args.js";
+import { loadProject, resolveEnvironment } from "../project.js";
+import { readMigrations } from "../migrations/index.js";
+import { closeVersioned, migrationsDir, openVersioned, renderStatus, statusJson, statusReport } from "../versioned/index.js";
+/** Exit code: migrations are pending, and nothing is wrong. */
+export const STATUS_PENDING = 3;
+/** Exit code: a checksum mismatch, an applied migration gone from the directory, or an out-of-order migration. */
+export const STATUS_REFUSED = 4;
+const help = `${usage("status")}
+
+Lists the environment's migrations against its history table
+(yodel.config.ts history.database, else YODEL_HISTORY_DATABASE, default
+yodeler) and its topology: applied, pending, out of order (pending, but before an applied migration in the chain), failed part way
+(with the statement it resumes at), and checksum mismatches (an applied
+migration whose files changed, or that is gone from the directory). When
+yodel apply would run, prints the plan digest it would ask approval for.
+Reads only; takes no lock.
+
+Options:
+  --json           print the status as JSON
+  -C, --dir <dir>  the project directory (default: the working directory)
+
+Exit codes:
+  0  every migration is applied
+  3  migrations are pending (failed part way included), and nothing is wrong
+  4  a checksum mismatch, an applied migration gone from the directory, or an
+     out-of-order migration (apply refuses it without --allow-out-of-order)
+  2  a pending migration has a manual step or an Op step yodel apply does not run
+  1  the status could not be read: a bad config, a malformed migrations
+     directory, a server that does not answer
+`;
+/** `yodel status <env>`; the exit codes are in `help`. */
+export const status = {
+    name: "status",
+    summary: "list applied, pending and out-of-order migrations",
+    implemented: true,
+    run: (args, io) => guarded("status", io, args, help, async () => {
+        const { env: name, json, dir } = parseEnvArgs("status", args);
+        const project = await loadProject(dir);
+        const env = resolveEnvironment(project, name);
+        const ordered = readMigrations(migrationsDir(project));
+        const venv = await openVersioned(project, env);
+        const report = await statusReport(venv, ordered, { sync: false }).finally(() => closeVersioned(venv));
+        if (json)
+            io.out(`${JSON.stringify(statusJson(report), null, 2)}\n`);
+        // The sections already say what is wrong; the refusal's wording is apply's.
+        else
+            io.out(renderStatus({ ...report, refusal: undefined }));
+        if (report.refusal)
+            return report.refusal.exitCode;
+        return report.status.pending.length > 0 ? STATUS_PENDING : 0;
+    }),
+};
+//# sourceMappingURL=status.js.map

package/dist/commands/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE7H,+DAA+D;AAC/D,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAChC,kHAAkH;AAClH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC;;;;;;;;;;;;;;;;;;;;;;CAsB9B,CAAC;AAEF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,MAAM,GAAY;IAC7B,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,mDAAmD;IAC5D,WAAW,EAAE,IAAI;IACjB,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAChB,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,IAAI,EAAE;QAC3C,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC9D,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,GAAG,GAAG,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC9C,MAAM,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;QACtG,IAAI,IAAI;YAAE,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACrE,4EAA4E;;YACvE,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAC7D,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC;QACnD,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC,CAAC;CACL,CAAC"}

package/dist/config/define.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `yodel.config.ts`: what yodel needs per environment that chant's
+ * `chant.config.ts` does not say. Optional; a project without one runs on
+ * the defaults below.
+ *
+ * ```ts
+ * // yodel.config.ts
+ * import { defineConfig } from "@intentius/sql-yodeler";
+ *
+ * export default defineConfig({
+ *   environments: {
+ *     dev: { topology: "single" },
+ *     prod: { topology: "cluster:main", history: { database: "yodeler" }, lockTtl: 1800 },
+ *   },
+ * });
+ * ```
+ */
+import type { Topology } from "@intentius/chant-lexicon-sql/clickhouse/topology";
+export type { Topology };
+/**
+ * A ClickHouse topology in its string form (`single`, `cluster:<name>`,
+ * `replicated`, `replicated:<cluster>`, `cloud`) or chant's object form,
+ * which also sets a cluster's Keeper path and replica name for the tables
+ * the migrations create.
+ */
+export type TopologySetting = string | Topology;
+export interface EnvironmentConfig {
+    /**
+     * The ClickHouse topology this environment runs. Every statement of every
+     * migration is rendered for it when it is sent (`ON CLUSTER`, the
+     * replicated engine), and the history table's engine follows it.
+     * Default: `sql.profiles.<env>.topology` in chant.config.ts, then
+     * `YODEL_TOPOLOGY`, then `single`.
+     */
+    topology?: TopologySetting;
+    history?: {
+        /** The database the history and lock tables live in. Default: `YODEL_HISTORY_DATABASE`, then `yodeler`. */
+        database?: string;
+    };
+    /** The apply lock's TTL, in seconds. Default: `YODEL_LOCK_TTL`, then 900. */
+    lockTtl?: number;
+}
+export interface YodelConfig {
+    /** Keyed by the environment's name in `sql.profiles`. */
+    environments?: Record<string, EnvironmentConfig>;
+    /** Reserved for `yodel lint`'s rule levels. */
+    lint?: Record<string, unknown>;
+}
+/** Returns `config` as is; it types the default export of `yodel.config.ts`. */
+export declare const defineConfig: (config: YodelConfig) => YodelConfig;

package/dist/config/define.js

@@ -0,0 +1,20 @@
+/**
+ * `yodel.config.ts`: what yodel needs per environment that chant's
+ * `chant.config.ts` does not say. Optional; a project without one runs on
+ * the defaults below.
+ *
+ * ```ts
+ * // yodel.config.ts
+ * import { defineConfig } from "@intentius/sql-yodeler";
+ *
+ * export default defineConfig({
+ *   environments: {
+ *     dev: { topology: "single" },
+ *     prod: { topology: "cluster:main", history: { database: "yodeler" }, lockTtl: 1800 },
+ *   },
+ * });
+ * ```
+ */
+/** Returns `config` as is; it types the default export of `yodel.config.ts`. */
+export const defineConfig = (config) => config;
+//# sourceMappingURL=define.js.map

package/dist/config/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../src/config/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAsCH,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAmB,EAAe,EAAE,CAAC,MAAM,CAAC"}

package/dist/config/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `yodel.config.ts` (#9): per-environment settings chant.config.ts does not
+ * hold, the ClickHouse topology first.
+ *
+ *   defineConfig({ environments: { <env>: { topology, history, lockTtl } } })
+ *   loadYodelConfig(dir, profiles)          the file, checked; undefined when there is none
+ *   environmentSettings(project, env)       topology, history database, lock TTL, with their fallbacks
+ */
+export * from "./define.js";
+export * from "./load.js";
+export * from "./settings.js";

package/dist/config/index.js

@@ -0,0 +1,12 @@
+/**
+ * `yodel.config.ts` (#9): per-environment settings chant.config.ts does not
+ * hold, the ClickHouse topology first.
+ *
+ *   defineConfig({ environments: { <env>: { topology, history, lockTtl } } })
+ *   loadYodelConfig(dir, profiles)          the file, checked; undefined when there is none
+ *   environmentSettings(project, env)       topology, history database, lock TTL, with their fallbacks
+ */
+export * from "./define.js";
+export * from "./load.js";
+export * from "./settings.js";
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}

package/dist/config/load.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Finding, loading and checking `yodel.config.ts`. The file is optional; a
+ * project without one gets `undefined` and every setting's default.
+ */
+import type { YodelConfig } from "./define.js";
+export declare const CONFIG_FILE = "yodel.config.ts";
+/**
+ * Checks a loaded config's shape. `environments` names each environment by
+ * its `sql.profiles` name; one that chant.config.ts does not declare is an
+ * error, so a typo does not silently leave an environment on the defaults.
+ */
+export declare function checkYodelConfig(value: unknown, path: string, profiles?: readonly string[]): YodelConfig;
+/** Loads `<dir>/yodel.config.ts`, or `undefined` when there is none. */
+export declare function loadYodelConfig(dir: string, profiles?: readonly string[]): Promise<{
+    path: string;
+    config: YodelConfig;
+} | undefined>;

package/dist/config/load.js

@@ -0,0 +1,102 @@
+/**
+ * Finding, loading and checking `yodel.config.ts`. The file is optional; a
+ * project without one gets `undefined` and every setting's default.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseTopology } from "@intentius/chant-lexicon-sql/clickhouse/topology";
+import { YodelError } from "../project.js";
+export const CONFIG_FILE = "yodel.config.ts";
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const TOPOLOGY_KINDS = ["single", "cluster", "replicated", "cloud"];
+function checkTopology(value, where) {
+    if (typeof value === "string") {
+        try {
+            parseTopology(value);
+        }
+        catch (e) {
+            throw new YodelError(`${where}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return;
+    }
+    if (!isRecord(value) || typeof value.kind !== "string" || !TOPOLOGY_KINDS.includes(value.kind)) {
+        throw new YodelError(`${where}: expected single, cluster:<name>, replicated, replicated:<cluster>, cloud, or { kind: ... }`);
+    }
+    const allowed = { single: [], cloud: [], replicated: ["cluster"], cluster: ["cluster", "replicaPath", "replicaName"] };
+    for (const [k, v] of Object.entries(value)) {
+        if (k === "kind")
+            continue;
+        if (!(allowed[value.kind] ?? []).includes(k))
+            throw new YodelError(`${where}.${k}: a ${value.kind} topology takes no ${k}`);
+        if (typeof v !== "string" || v === "")
+            throw new YodelError(`${where}.${k}: expected a non-empty string`);
+    }
+    if (value.kind === "cluster" && typeof value.cluster !== "string")
+        throw new YodelError(`${where}.cluster: a cluster topology needs the cluster's name`);
+}
+function checkEnvironment(value, where) {
+    if (!isRecord(value))
+        throw new YodelError(`${where}: expected an object`);
+    for (const k of Object.keys(value)) {
+        if (!["topology", "history", "lockTtl"].includes(k))
+            throw new YodelError(`${where}.${k}: unknown setting (expected topology, history, lockTtl)`);
+    }
+    if (value.topology !== undefined)
+        checkTopology(value.topology, `${where}.topology`);
+    if (value.history !== undefined) {
+        if (!isRecord(value.history))
+            throw new YodelError(`${where}.history: expected an object`);
+        for (const k of Object.keys(value.history))
+            if (k !== "database")
+                throw new YodelError(`${where}.history.${k}: unknown setting (expected database)`);
+        const db = value.history.database;
+        if (db !== undefined && (typeof db !== "string" || db === ""))
+            throw new YodelError(`${where}.history.database: expected a database name`);
+    }
+    if (value.lockTtl !== undefined && !(typeof value.lockTtl === "number" && Number.isFinite(value.lockTtl) && value.lockTtl > 0)) {
+        throw new YodelError(`${where}.lockTtl: expected a number of seconds greater than 0`);
+    }
+    return value;
+}
+/**
+ * Checks a loaded config's shape. `environments` names each environment by
+ * its `sql.profiles` name; one that chant.config.ts does not declare is an
+ * error, so a typo does not silently leave an environment on the defaults.
+ */
+export function checkYodelConfig(value, path, profiles) {
+    if (!isRecord(value))
+        throw new YodelError(`${path}: the default export must be a config object (export default defineConfig({ ... }))`);
+    for (const k of Object.keys(value)) {
+        if (k !== "environments" && k !== "lint")
+            throw new YodelError(`${path}: unknown setting ${k} (expected environments, lint)`);
+    }
+    if (value.lint !== undefined && !isRecord(value.lint))
+        throw new YodelError(`${path}: lint: expected an object`);
+    if (value.environments !== undefined) {
+        if (!isRecord(value.environments))
+            throw new YodelError(`${path}: environments: expected an object keyed by environment`);
+        for (const [name, env] of Object.entries(value.environments)) {
+            checkEnvironment(env, `${path}: environments.${name}`);
+            if (profiles && !profiles.includes(name)) {
+                throw new YodelError(`${path}: environments.${name} is not an environment chant.config.ts declares` + (profiles.length > 0 ? ` (sql.profiles: ${profiles.join(", ")})` : " (it declares no sql.profiles)"));
+            }
+        }
+    }
+    return value;
+}
+/** Loads `<dir>/yodel.config.ts`, or `undefined` when there is none. */
+export async function loadYodelConfig(dir, profiles) {
+    const path = join(dir, CONFIG_FILE);
+    if (!existsSync(path))
+        return undefined;
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(path).href));
+    }
+    catch (e) {
+        throw new YodelError(`${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return { path, config: checkYodelConfig(mod.default, path, profiles) };
+}
+//# sourceMappingURL=load.js.map

package/dist/config/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,kDAAkD,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE7C,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAgC,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAExH,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;AAEpE,SAAS,aAAa,CAAC,KAAc,EAAE,KAAa;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,aAAa,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,OAAO;IACT,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/F,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,8FAA8F,CAAC,CAAC;IAC/H,CAAC;IACD,MAAM,OAAO,GAA6B,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,aAAa,CAAC,EAAE,CAAC;IACjJ,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,IAAI,CAAC,KAAK,MAAM;YAAE,SAAS;QAC3B,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,IAAI,CAAC,OAAO,KAAK,CAAC,IAAI,sBAAsB,CAAC,EAAE,CAAC,CAAC;QAC5H,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,IAAI,CAAC,+BAA+B,CAAC,CAAC;IAC5G,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;QAAE,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,uDAAuD,CAAC,CAAC;AAC3J,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc,EAAE,KAAa;IACrD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,sBAAsB,CAAC,CAAC;IAC3E,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,IAAI,CAAC,yDAAyD,CAAC,CAAC;IACpJ,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,aAAa,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,KAAK,WAAW,CAAC,CAAC;IACrF,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,8BAA8B,CAAC,CAAC;QAC3F,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,IAAI,CAAC,KAAK,UAAU;gBAAE,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,YAAY,CAAC,uCAAuC,CAAC,CAAC;QACrJ,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAClC,IAAI,EAAE,KAAK,SAAS,IAAI,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,6CAA6C,CAAC,CAAC;IAC7I,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC;QAC/H,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,uDAAuD,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc,EAAE,IAAY,EAAE,QAA4B;IACzF,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,qFAAqF,CAAC,CAAC;IACzI,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK,cAAc,IAAI,CAAC,KAAK,MAAM;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,qBAAqB,CAAC,gCAAgC,CAAC,CAAC;IAChI,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,4BAA4B,CAAC,CAAC;IACjH,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACrC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,yDAAyD,CAAC,CAAC;QAC1H,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7D,gBAAgB,CAAC,GAAG,EAAE,GAAG,IAAI,kBAAkB,IAAI,EAAE,CAAC,CAAC;YACvD,IAAI,QAAQ,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzC,MAAM,IAAI,UAAU,CAClB,GAAG,IAAI,kBAAkB,IAAI,iDAAiD,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,mBAAmB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,gCAAgC,CAAC,CACtL,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW,EAAE,QAA4B;IAC7E,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACpC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,GAA0B,CAAC;IAC/B,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAA0B,CAAC;IAC1E,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;AACzE,CAAC"}