@intentius/sql-yodeler 0.2.0 → 0.4.0

package/dist/commands/ci.d.ts

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

package/dist/commands/ci.js

@@ -0,0 +1,130 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { guarded } from "../env-args.js";
+import { loadProject, YodelError } from "../project.js";
+const usage = "usage: yodel ci [--check] [--dir <project>]\n       yodel ci --replay [--dir <project>] [-- <yodel lint options>]";
+const help = `${usage}
+
+Renders the project's CI pipelines for GitHub Actions, GitLab CI and
+Forgejo Actions from chant.config.ts (the environments, in profile order),
+yodel.config.ts (waves, ci) and ops/ (each environment's migrate and watch
+Ops), each declared with chant's lexicons:
+
+  yodel-pr      on a pull request: yodel ci --check, yodel lint, the replay
+                check into a throwaway server, and the plan comment per
+                environment
+  yodel-apply   on a push to main: one job per wave (yodel-waves.json)
+  yodel-apply-plans
+                on a pull request, when a wave's approval is pr-review:
+                chant run wave --record-plans records the plan each wave
+                makes at the head, for the review to approve (on GitLab, the
+                merge request job yodel-apply-record-plans)
+  watch-<env>   each environment's drift watch, on its schedule
+
+The pipelines come from the installed yodel, so upgrading yodel and running
+yodel ci again brings its fixes to the project; yodel ci --check then fails
+until the new files are committed.
+
+yodel.config.ts ci:
+  forges   the forges to render for (default github, gitlab and forgejo)
+  jobs     a module (such as "ci/jobs.ts") exporting the project's own jobs,
+           declared with chant: actions (github lexicon Jobs, for GitHub and
+           Forgejo) and gitlab (gitlab lexicon Jobs). They are added to the
+           pull request pipeline after yodel's jobs, on every render.
+  image    the CI image every job runs in, pinned by its digest
+  resume   { schedule: "<cron>" }: a scheduled yodel-apply-resume job that
+           starts again an apply wave whose approval has arrived (chant run
+           resume); it approves nothing. GitHub uses the job's token
+           (actions: write), Forgejo the CHANT_FORGE_TOKEN secret
+           (write:repository), GitLab a pipeline schedule you create, with
+           GITLAB_TOKEN (api scope, Developer)
+
+Options:
+  --check          write nothing; exit 1 naming each file that differs from
+                   what yodel ci renders
+  --replay         the lint job's replay check on this machine: a throwaway
+                   server started with Docker from the job's image, the
+                   replay profile pointed at it, yodel lint --replay replay
+                   --reset, and the server removed. Options after -- go to
+                   yodel lint. The exit code is yodel lint's
+  -C, --dir <dir>  the project directory (default: the working directory)
+
+Exit codes:
+  0  written, or (--check) every file is up to date
+  1  (--check) a file is stale or missing; anything else failed
+`;
+function parseCiArgs(args) {
+    const out = { dir: process.cwd(), check: false, replay: false, rest: [] };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--") {
+            out.rest = args.slice(i + 1);
+            break;
+        }
+        if (a === "--check")
+            out.check = true;
+        else if (a === "--replay")
+            out.replay = true;
+        else if (a === "--dir" || a === "-C") {
+            const v = args[++i];
+            if (v === undefined)
+                throw new YodelError(`${a} needs a directory\n${usage}`);
+            out.dir = v;
+        }
+        else if (a?.startsWith("--dir="))
+            out.dir = a.slice("--dir=".length);
+        else
+            throw new YodelError(`unknown argument ${String(a)}\n${usage}`);
+    }
+    if (out.check && out.replay)
+        throw new YodelError(`--check and --replay are two things; give one\n${usage}`);
+    if (out.rest.length > 0 && !out.replay)
+        throw new YodelError(`options after -- are for --replay\n${usage}`);
+    return out;
+}
+/** `yodel ci`; the exit codes are in `help`. */
+export const ci = {
+    name: "ci",
+    summary: "render the project's CI pipelines (GitHub, GitLab, Forgejo)",
+    implemented: true,
+    run: (args, io) => guarded("ci", io, args, help, async () => {
+        const a = parseCiArgs(args);
+        // The project, as every command reads it: chant.config.ts and a checked yodel.config.ts.
+        const dir = (await loadProject(resolve(a.dir))).dir;
+        if (a.replay) {
+            const { replayLocally } = await import("../ci/replay.js");
+            return replayLocally(dir, a.rest);
+        }
+        // Loaded here: the forge lexicons are for this command alone.
+        const { render } = await import("../ci/render.js");
+        let files;
+        try {
+            files = await render(dir);
+        }
+        catch (e) {
+            throw new YodelError(e instanceof Error ? e.message : String(e));
+        }
+        const stale = [];
+        for (const file of files) {
+            const abs = join(dir, file.path);
+            const current = existsSync(abs) ? readFileSync(abs, "utf8") : undefined;
+            if (current === file.content)
+                continue;
+            if (a.check) {
+                stale.push(file.path);
+                continue;
+            }
+            mkdirSync(dirname(abs), { recursive: true });
+            writeFileSync(abs, file.content);
+            io.out(`wrote ${file.path}\n`);
+        }
+        if (a.check && stale.length > 0) {
+            io.err(`stale, run yodel ci: ${stale.join(", ")}\n`);
+            return 1;
+        }
+        if (a.check)
+            io.out(`${String(files.length)} CI files are up to date\n`);
+        return 0;
+    }),
+};
+//# sourceMappingURL=ci.js.map

package/dist/commands/ci.js.map

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

package/dist/commands/cleanup.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from "../command.js";
+import { type Retained } from "../cleanup/index.js";
+/** `yodel cleanup --json` (schemas/cleanup.schema.json). */
+export declare function cleanupJson(r: {
+    environment: string;
+    now: string;
+    retained: readonly Retained[];
+    planDigest?: string | undefined;
+    approve?: string | undefined;
+    dropped: readonly string[];
+}): Record<string, unknown>;
+/** `yodel cleanup <env>`; the exit codes are in `help`. */
+export declare const cleanup: Command;

package/dist/commands/cleanup.js

@@ -0,0 +1,138 @@
+import { parseArgs } from "node:util";
+import { guarded } from "../env-args.js";
+import { loadProject, resolveEnvironment, YodelError } from "../project.js";
+import { appliedBy, withLock } from "../history/index.js";
+import { closeVersioned, findMigrateOp, gitLedger, NOT_APPROVED, openVersioned, verifyApproval } from "../versioned/index.js";
+import { cleanupDigest, describeRetained, dropRetained, findRetained, retainedServer } from "../cleanup/index.js";
+const usage = "usage: yodel cleanup <env> [--list] [--op <name>] [--json] [--dir <project>]";
+const help = `${usage}
+
+Lists what steps kept in <env> on purpose, and drops what is past its
+retention date, behind the environment's approval:
+
+- a ClickHouse rebuild's old table, <table>__chant_old, kept after the swap
+  (7 days, or the step's retain);
+- a Postgres rename's or type change's old column, kept after the switch
+  when the step set retain (yodel new --retain), with the trigger and
+  function that keep a renamed column written.
+
+Each one's date is in its own comment, and the server's clock decides
+whether it has passed. Nothing is dropped before its date.
+
+When something is due, the drop is a plan like an apply's: its digest
+covers each due object (a table by its UUID, a column by its table and
+attribute number) and its date. Without an approval of the environment's
+migrations Op gate for that digest, yodel cleanup lists what it would drop,
+prints the digest and the chant approve command, and drops nothing (exit
+3). Approve it, run yodel cleanup <env> again, and it drops them under the
+apply lock, after reading them again: if anything due changed, the digest
+differs and the approval does not count.
+
+Options:
+  --list           list only; never drop, even with an approval
+  --op <name>      the migrations Op, when more than one applies <env>
+  --json           print the list (and what was dropped) as JSON
+  -C, --dir <dir>  the project directory (default: the working directory)
+
+Exit codes:
+  0  nothing is due (and nothing was dropped), the due objects were dropped,
+     or --list
+  3  something is due and waits for an approval; nothing was dropped
+  5  another apply holds the lock
+  1  an error: a bad config, an unknown environment, a server it cannot read
+`;
+function parseCleanupArgs(args) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args, allowPositionals: true, strict: true, options: { list: { type: "boolean" }, op: { 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 [env, ...rest] = parsed.positionals;
+    if (env === undefined || rest.length > 0)
+        throw new YodelError(usage);
+    const v = parsed.values;
+    return { env, list: v.list === true, op: typeof v.op === "string" ? v.op : undefined, json: v.json === true, dir: typeof v.dir === "string" ? v.dir : process.cwd() };
+}
+/** `yodel cleanup --json` (schemas/cleanup.schema.json). */
+export function cleanupJson(r) {
+    return {
+        environment: r.environment,
+        now: r.now,
+        retained: r.retained.map((x) => ({ kind: x.kind, name: x.name, of: x.of, ...(x.retainUntil ? { retainUntil: x.retainUntil } : {}), due: x.due, identity: x.identity, ...(x.trigger ? { trigger: x.trigger } : {}) })),
+        due: r.retained.filter((x) => x.due).length,
+        ...(r.planDigest ? { planDigest: r.planDigest } : {}),
+        ...(r.approve ? { approve: r.approve } : {}),
+        dropped: r.dropped,
+    };
+}
+/** `yodel cleanup <env>`; the exit codes are in `help`. */
+export const cleanup = {
+    name: "cleanup",
+    summary: "drop the old tables and columns steps kept, once past their date",
+    implemented: true,
+    run: (args, io) => guarded("cleanup", io, args, help, async () => {
+        const a = parseCleanupArgs(args);
+        const project = await loadProject(a.dir);
+        const env = resolveEnvironment(project, a.env);
+        const venv = await openVersioned(project, env);
+        try {
+            return await cleanupWith(project, env, venv, a, io);
+        }
+        finally {
+            await closeVersioned(venv);
+        }
+    }),
+};
+async function cleanupWith(project, env, venv, a, io) {
+    const server = retainedServer(venv);
+    const { now, retained } = await findRetained(server);
+    const dueCount = retained.filter((r) => r.due).length;
+    const lines = [`Kept by steps in ${env.name} (server time ${now}):`];
+    if (retained.length === 0)
+        lines[0] = `Nothing kept by steps in ${env.name}: no old table or old column waits for its retention date.`;
+    for (const r of retained)
+        lines.push(`  ${describeRetained(r)}`);
+    const report = (extra, tail = []) => {
+        if (a.json)
+            io.out(`${JSON.stringify(cleanupJson({ environment: env.name, now, retained, dropped: [], ...extra }), null, 2)}\n`);
+        else
+            io.out(`${[...lines, ...tail].join("\n")}\n`);
+    };
+    if (dueCount === 0 || a.list) {
+        report({}, retained.length > 0 && dueCount === 0 ? ["", "Nothing is due: nothing dropped."] : []);
+        return 0;
+    }
+    const digest = await cleanupDigest(env.name, retained);
+    const op = await findMigrateOp(project, env, a.op);
+    const ledger = await gitLedger(project.dir);
+    const approve = `chant approve ${op.name} ${op.gate} --plan ${digest}`;
+    try {
+        await verifyApproval(ledger, op, digest);
+    }
+    catch (e) {
+        if (!(e instanceof YodelError) || e.exitCode !== NOT_APPROVED)
+            throw e;
+        report({ planDigest: digest, approve }, ["", `Plan digest: ${digest}`, `${String(dueCount)} due; nothing dropped without an approval. Approve it with:`, `  ${approve}`, `then run yodel cleanup ${env.name} again.`]);
+        return NOT_APPROVED;
+    }
+    const lock = await venv.driver.acquireLock(appliedBy());
+    if (lock.notice && !a.json)
+        io.err(`lock: ${lock.notice}\n`);
+    const dropped = await withLock(lock, venv.lockTtlMs, async () => {
+        // Read again under the lock: the approval counts only for what is due now.
+        const again = await findRetained(server);
+        const now = await cleanupDigest(env.name, again.retained);
+        const by = await verifyApproval(ledger, op, now);
+        if (!a.json)
+            io.err(`approval: ${op.name} / ${op.gate} for ${now}, by ${by.resolvedBy} at ${by.timestamp}\n`);
+        return dropRetained(server, again.retained, (l) => {
+            if (!a.json)
+                io.err(`${l}\n`);
+        });
+    });
+    report({ planDigest: digest, dropped }, ["", `Dropped ${String(dropped.length)}: ${dropped.join(", ")}`]);
+    return 0;
+}
+//# sourceMappingURL=cleanup.js.map

package/dist/commands/cleanup.js.map

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

package/dist/commands/config.d.ts

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

package/dist/commands/config.js

@@ -0,0 +1,136 @@
+import { parseArgs } from "node:util";
+import { environmentSettings } from "../config/settings.js";
+import { CONFIG_FILE } from "../config/load.js";
+import { credentialsOf, describePassword, roleOf, ROLES } from "../credentials.js";
+import { guarded } from "../env-args.js";
+import { EXIT_REFUSED } from "../exit.js";
+import { writeProbe } from "../probe.js";
+import { loadProject, resolveEnvironment, YodelError } from "../project.js";
+import { serverAddress } from "../server.js";
+const USAGE = "usage: yodel config check [<env>...] [--write-probe] [--dir <project>]";
+const help = `${USAGE}
+
+Prints each environment's settings and where each came from: the server,
+the role this process connects as (YODEL_CREDENTIALS), the reader's and the
+writer's user and password (the variable each is read from and whether it
+is set here, or the token source that mints it), the history's database,
+the topology, and the lock's TTL and wait. Every environment, or the ones
+named. Never prints a password.
+
+A profile made with credentials() in chant.config.ts carries a reader and a
+writer. Every yodel command refuses the project, exit 4, when an
+environment's reader and writer read their user or password from the same
+variable, or their users are the same name.
+
+Options:
+  --write-probe    try a write in each environment with the credentials this
+                   process holds, and exit 4 when the server lets one
+                   through: run in a pull request job, it shows the job
+                   holds no writer. The write is rolled back (Postgres) or
+                   dropped at once (ClickHouse).
+  -C, --dir <dir>  the project directory (default: the working directory)
+
+Exit codes:
+  0  printed; with --write-probe, no environment let the write through
+  4  refused: an environment's reader and writer are one identity, or with
+     --write-probe, a write went through
+  1  an error: a bad config, an unknown environment, a server that does not
+     answer, or a probe that could not tell
+`;
+const isEnvRef = (v) => typeof v === "object" && v !== null && typeof v.env === "string";
+function roleView(c, role, env) {
+    const r = c[role];
+    const value = env[r.user.env];
+    const set = value !== undefined && value !== "";
+    return {
+        user: { variable: r.user.env, set, ...(set ? { value } : {}) },
+        password: isEnvRef(r.password) ? { source: r.password.env, set: (env[r.password.env] ?? "") !== "" } : { source: describePassword(r.password) },
+    };
+}
+function view(project, name, env) {
+    const e = resolveEnvironment(project, name);
+    const profile = e.profile;
+    const c = credentialsOf(profile);
+    const settings = environmentSettings(project, name, env);
+    const own = project.yodel?.config.environments?.[name];
+    const historySource = own?.history?.database !== undefined ? CONFIG_FILE : env.YODEL_HISTORY_DATABASE ? "YODEL_HISTORY_DATABASE" : "default";
+    const ys = env.YODEL_CREDENTIALS;
+    const user = profile.user;
+    const password = profile.password;
+    return {
+        environment: name,
+        server: serverAddress(project.dialect, String(profile.url)),
+        role: roleOf(name, ys),
+        roleSource: ys ? `YODEL_CREDENTIALS=${ys}` : "YODEL_CREDENTIALS unset",
+        credentials: c
+            ? { split: true, reader: roleView(c, "reader", env), writer: roleView(c, "writer", env) }
+            : { split: false, ...(isEnvRef(user) ? { user: user.env } : {}), ...(password ? { password: describePassword(password) } : {}) },
+        history: { database: settings.historyDatabase, source: historySource },
+        ...(project.dialect === "clickhouse" ? { topology: { value: describeTopology(settings.topology), source: settings.topologySource } } : {}),
+        lockTtlSeconds: settings.lockTtlMs / 1000,
+        lockWaitSeconds: settings.lockWaitMs / 1000,
+    };
+}
+const describeTopology = (t) => (t.cluster ? `${t.kind}:${t.cluster}` : t.kind);
+function render(v) {
+    const lines = [`${v.environment} (${v.server})`, `  connects as   ${v.role} (${v.roleSource})`];
+    const c = v.credentials;
+    if (c.split) {
+        for (const role of ROLES) {
+            const r = c[role];
+            const user = `${r.user.variable} (${r.user.set ? `set: ${r.user.value ?? ""}` : "not set here"})`;
+            const password = r.password.set === undefined ? r.password.source : `${r.password.source} (${r.password.set ? "set" : "not set here"})`;
+            lines.push(`  ${role.padEnd(13)} user ${user}, password ${password}`);
+        }
+    }
+    else {
+        lines.push(`  credentials   user ${c.user ?? "none"}, password ${c.password ?? "none"}: one set for every job; credentials() in chant.config.ts gives a reader and a writer`);
+    }
+    lines.push(`  history       ${v.history.database} (${v.history.source})`);
+    if (v.topology)
+        lines.push(`  topology      ${v.topology.value} (${v.topology.source})`);
+    lines.push(`  lock          ttl ${String(v.lockTtlSeconds)}s, wait ${String(v.lockWaitSeconds)}s`);
+    if (v.probe)
+        lines.push(`  write probe   ${v.probe.wrote ? "WROTE" : "cannot write"}: ${v.probe.detail}`);
+    return `${lines.join("\n")}\n`;
+}
+async function check(args, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args, allowPositionals: true, strict: true, options: { "write-probe": { 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 project = await loadProject(typeof values.dir === "string" ? values.dir : process.cwd());
+    const names = positionals.length > 0 ? positionals : Object.keys(project.config.sql?.profiles ?? {});
+    const views = [];
+    for (const name of names) {
+        const v = view(project, name, process.env);
+        if (values["write-probe"] === true)
+            v.probe = await writeProbe(project, resolveEnvironment(project, name));
+        views.push(v);
+    }
+    io.out(views.map(render).join("\n"));
+    const wrote = views.filter((v) => v.probe?.wrote);
+    if (wrote.length === 0)
+        return 0;
+    for (const v of wrote) {
+        io.err(`yodel config: refused: ${v.environment}: the credentials this process holds can write (${v.probe?.detail ?? ""}). A pull request job must hold the reader only: check which secrets it maps, and the reader's grants.\n`);
+    }
+    return EXIT_REFUSED;
+}
+/** `yodel config check`; the exit codes are in `help`. */
+export const config = {
+    name: "config",
+    summary: "print each environment's settings, and prove a job cannot write",
+    implemented: true,
+    run: (args, io) => guarded("config", io, args, help, async () => {
+        const [sub, ...rest] = args;
+        if (sub !== "check")
+            throw new YodelError(USAGE);
+        return check(rest, io);
+    }),
+};
+//# sourceMappingURL=config.js.map

package/dist/commands/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,EAAE,KAAK,EAA+B,MAAM,mBAAmB,CAAC;AAChH,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAoB,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,UAAU,EAAgB,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,KAAK,GAAG,wEAAwE,CAAC;AAEvF,MAAM,IAAI,GAAG,GAAG,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BpB,CAAC;AAqBF,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAwB,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,OAAQ,CAAuB,CAAC,GAAG,KAAK,QAAQ,CAAC;AAE/I,SAAS,QAAQ,CAAC,CAAc,EAAE,IAAU,EAAE,GAAsB;IAClE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IAClB,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC;IAChD,OAAO;QACL,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;QAC9D,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE;KAChJ,CAAC;AACJ,CAAC;AAED,SAAS,IAAI,CAAC,OAAgB,EAAE,IAAY,EAAE,GAAsB;IAClE,MAAM,CAAC,GAAG,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,CAAC,CAAC,OAA6C,CAAC;IAChE,MAAM,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACzD,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,aAAa,GAAG,GAAG,EAAE,OAAO,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7I,MAAM,EAAE,GAAG,GAAG,CAAC,iBAAiB,CAAC;IACjC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAA8D,CAAC;IACxF,OAAO;QACL,WAAW,EAAE,IAAI;QACjB,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3D,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QACtB,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,yBAAyB;QACtE,WAAW,EAAE,CAAC;YACZ,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE;YACzF,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;QAClI,OAAO,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE;QACtE,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,YAAY,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1I,cAAc,EAAE,QAAQ,CAAC,SAAS,GAAG,IAAI;QACzC,eAAe,EAAE,QAAQ,CAAC,UAAU,GAAG,IAAI;KAC5C,CAAC;AACJ,CAAC;AAED,MAAM,gBAAgB,GAAG,CAAC,CAAqC,EAAU,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAE5H,SAAS,MAAM,CAAC,CAAU;IACxB,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,MAAM,GAAG,EAAE,mBAAmB,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC;IAChG,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC;IACxB,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;QACZ,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;YAClB,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC;YAClG,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC;YACxI,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,SAAS,IAAI,cAAc,QAAQ,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CACR,wBAAwB,CAAC,CAAC,IAAI,IAAI,MAAM,cAAc,CAAC,CAAC,QAAQ,IAAI,MAAM,uFAAuF,CAClK,CAAC;IACJ,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,OAAO,CAAC,QAAQ,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1E,IAAI,CAAC,CAAC,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,QAAQ,CAAC,KAAK,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IACzF,KAAK,CAAC,IAAI,CAAC,uBAAuB,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,WAAW,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IACnG,IAAI,CAAC,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1G,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC;AAED,KAAK,UAAU,KAAK,CAAC,IAAc,EAAE,EAAM;IACzC,IAAI,MAAoC,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3J,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,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC/F,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC;IACrG,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,IAAI;YAAE,CAAC,CAAC,KAAK,GAAG,MAAM,UAAU,CAAC,OAAO,EAAE,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC3G,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChB,CAAC;IACD,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAClD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACjC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,EAAE,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC,WAAW,mDAAmD,CAAC,CAAC,KAAK,EAAE,MAAM,IAAI,EAAE,0GAA0G,CAAC,CAAC;IACpO,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,MAAM,MAAM,GAAY;IAC7B,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,iEAAiE;IAC1E,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,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QAC5B,IAAI,GAAG,KAAK,OAAO;YAAE,MAAM,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;QACjD,OAAO,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACzB,CAAC,CAAC;CACL,CAAC"}

package/dist/commands/docs.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "../command.js";
+import { type Project } from "../project.js";
+import { type DocsInput } from "../schema-docs/render.js";
+/** Where `yodel docs` writes, relative to the project, without --out. */
+export declare const DOCS_DIR = "schema-docs";
+export declare const DOCS_HTML = "index.html";
+export declare const DOCS_ERD = "erd.md";
+/** What `yodel docs` documents for the project: the build, or a migration's recorded schema. */
+export declare function docsInput(project: Project, migration?: string): Promise<DocsInput>;
+/** `yodel docs`; the exit codes are in `help`. */
+export declare const docs: Command;

package/dist/commands/docs.js

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { guarded } from "../env-args.js";
+import { loadProject, YodelError } from "../project.js";
+import { buildSchema } from "../chant/build.js";
+import { migrationsDir, readChain } from "../versioned/index.js";
+import { erdMarkdown, schemaHtml } from "../schema-docs/render.js";
+/** Where `yodel docs` writes, relative to the project, without --out. */
+export const DOCS_DIR = "schema-docs";
+export const DOCS_HTML = "index.html";
+export const DOCS_ERD = "erd.md";
+const usage = "usage: yodel docs [--out <dir>] [--migration <id>] [--dir <project>]";
+const help = `${usage}
+
+Writes a reference of the schema, offline: no server is read.
+
+  <out>/index.html  every table, view, index and database or schema: its
+                    columns, keys, relations, comments, ClickHouse engine,
+                    sort key, partition key and TTL, its DDL, and the
+                    migrations in migrations/ that changed it. One file
+                    with its styles inline and no scripts.
+  <out>/erd.md      a Mermaid entity-relationship diagram of the tables and
+                    views, which GitHub, GitLab and Forgejo render: foreign
+                    keys, what a view reads, the table a materialized view
+                    writes to, the table a Distributed table serves.
+
+The schema is the build of the declared schema (chant build), or with
+--migration <id> the schema that migration recorded. The same schema gives
+the same files, so they can be committed and reviewed in a pull request.
+
+Options:
+  --out <dir>       where to write (default: ${DOCS_DIR} in the project)
+  --migration <id>  document the schema migration <id> recorded, and its
+                    history up to it
+  -C, --dir <dir>   the project directory (default: the working directory)
+
+Exit codes:
+  0  written
+  1  nothing written: a bad config, a declaration chant cannot build, an
+     unknown migration id
+  4  refused: the migrations directory is not one chain (a fork, a missing
+     parent)
+`;
+function parseDocsArgs(args) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args, strict: true, options: { out: { type: "string" }, migration: { type: "string" }, dir: { type: "string", short: "C" } } });
+    }
+    catch (e) {
+        throw new YodelError(`${e instanceof Error ? e.message : String(e)}\n${usage}`);
+    }
+    const s = (v) => (typeof v === "string" ? v : undefined);
+    return { out: s(parsed.values.out), migration: s(parsed.values.migration), dir: s(parsed.values.dir) ?? process.cwd() };
+}
+/** The project's name for the title: package.json's name, else the directory's. */
+function projectTitle(project) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(project.dir, "package.json"), "utf8"));
+        if (typeof pkg.name === "string" && pkg.name && !pkg.name.includes("{{"))
+            return pkg.name;
+    }
+    catch {
+        // no package.json: the directory's name
+    }
+    return basename(project.dir);
+}
+/** What `yodel docs` documents for the project: the build, or a migration's recorded schema. */
+export async function docsInput(project, migration) {
+    const chain = existsSync(migrationsDir(project)) ? readChain(project) : [];
+    const steps = chain.map((m) => ({ id: m.id, steps: m.document.steps }));
+    const title = projectTitle(project);
+    if (migration !== undefined) {
+        const at = chain.findIndex((m) => m.id === migration);
+        const found = chain[at];
+        if (!found)
+            throw new YodelError(`no migration ${migration} in ${relative(process.cwd(), migrationsDir(project)) || migrationsDir(project)}`);
+        return { title, output: found.document.schema, source: `the schema migration ${migration} recorded`, migrations: steps.slice(0, at + 1) };
+    }
+    const build = await buildSchema(project);
+    try {
+        return { title, output: build.output, source: "chant build of the declared schema", migrations: steps };
+    }
+    finally {
+        build.dispose();
+    }
+}
+/** `yodel docs`; the exit codes are in `help`. */
+export const docs = {
+    name: "docs",
+    summary: "write an HTML reference and a Mermaid ERD of the schema",
+    implemented: true,
+    run: (args, io) => guarded("docs", io, args, help, async () => {
+        const { out, migration, dir } = parseDocsArgs(args);
+        const project = await loadProject(dir);
+        const input = await docsInput(project, migration);
+        const outDir = resolve(out ?? join(project.dir, DOCS_DIR));
+        mkdirSync(outDir, { recursive: true });
+        writeFileSync(join(outDir, DOCS_HTML), schemaHtml(input));
+        writeFileSync(join(outDir, DOCS_ERD), erdMarkdown(input));
+        const rel = relative(project.dir, outDir);
+        const where = rel === "" ? "." : rel.startsWith("..") ? outDir : rel;
+        const count = input.output.objects.length;
+        io.out(`Wrote ${join(where, DOCS_HTML)} and ${join(where, DOCS_ERD)} (${String(count)} object${count === 1 ? "" : "s"}, from ${input.source})\n`);
+        return 0;
+    }),
+};
+//# sourceMappingURL=docs.js.map

package/dist/commands/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/commands/docs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAgB,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAkB,MAAM,0BAA0B,CAAC;AAEnF,yEAAyE;AACzE,MAAM,CAAC,MAAM,QAAQ,GAAG,aAAa,CAAC;AACtC,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC;AACtC,MAAM,CAAC,MAAM,QAAQ,GAAG,QAAQ,CAAC;AAEjC,MAAM,KAAK,GAAG,sEAAsE,CAAC;AAErF,MAAM,IAAI,GAAG,GAAG,KAAK;;;;;;;;;;;;;;;;;;;+CAmB0B,QAAQ;;;;;;;;;;;CAWtD,CAAC;AAQF,SAAS,aAAa,CAAC,IAAc;IACnC,IAAI,MAAoC,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;IACvJ,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,CAAC,GAAG,CAAC,CAAU,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAClE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;AAC1H,CAAC;AAED,mFAAmF;AACnF,SAAS,YAAY,CAAC,OAAgB;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAuB,CAAC;QACtG,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,GAAG,CAAC,IAAI,CAAC;IAC5F,CAAC;IAAC,MAAM,CAAC;QACP,wCAAwC;IAC1C,CAAC;IACD,OAAO,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,gGAAgG;AAChG,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAgB,EAAE,SAAkB;IAClE,MAAM,KAAK,GAAG,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC;QACtD,MAAM,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,UAAU,CAAC,gBAAgB,SAAS,OAAO,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9I,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,wBAAwB,SAAS,WAAW,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;IAC5I,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,oCAAoC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC1G,CAAC;YAAS,CAAC;QACT,KAAK,CAAC,OAAO,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED,kDAAkD;AAClD,MAAM,CAAC,MAAM,IAAI,GAAY;IAC3B,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,yDAAyD;IAClE,WAAW,EAAE,IAAI;IACjB,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAChB,OAAO,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,IAAI,EAAE;QACzC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC3D,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACvC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1D,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;QACrE,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QAC1C,EAAE,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,QAAQ,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,UAAU,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,UAAU,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;QAClJ,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;CACL,CAAC"}

package/dist/commands/drift.d.ts

@@ -1,6 +1,9 @@
 import type { Command } from "../command.js";
+import { type Drift } from "../chant/drift.js";
 import { type BuildOutput } from "../chant/build.js";
-import type { Environment, Project } from "../project.js";
+import { type ServerInfo } from "../server.js";
+import type { Environment, Project, SqlDialect } from "../project.js";
+import { type IssueAction } from "../pr/issue.js";
 /**
  * The schema the environment's history says it has: the recorded schema
  * of the newest migration, in chain order, that the history records as
@@ -10,5 +13,14 @@ export declare function recordedSchema(project: Project, env: Environment): Prom
     migration: string;
     schema: BuildOutput;
 } | undefined>;
+/** The document `yodel drift --json` prints (schemas/drift.schema.json): the drift, and what the run made of it. */
+export declare function driftJson(result: Drift, parts: {
+    dialect: SqlDialect;
+    server?: ServerInfo | undefined;
+    drifted: boolean;
+    fingerprint: string;
+    issue?: IssueAction | undefined;
+    issueError?: string | undefined;
+}): Record<string, unknown>;
 /** `yodel drift <env>`; the exit codes are in `help`. */
 export declare const drift: Command;