@intentius/sql-yodeler 0.0.0-stage → 0.1.0

package/dist/pr/comment.js

@@ -0,0 +1,99 @@
+/**
+ * One comment per environment on the pull request: found by its marker and
+ * updated, else created. The three forges' REST APIs:
+ *
+ *   GitHub   GET/POST {api}/repos/{owner}/{repo}/issues/{n}/comments
+ *            PATCH    {api}/repos/{owner}/{repo}/issues/comments/{id}
+ *   GitLab   GET/POST {api}/projects/{id}/merge_requests/{iid}/notes
+ *            PUT      {api}/projects/{id}/merge_requests/{iid}/notes/{note_id}
+ *   Forgejo  GET/POST {api}/repos/{owner}/{repo}/issues/{n}/comments   (Gitea's API, /api/v1)
+ *            PATCH    {api}/repos/{owner}/{repo}/issues/comments/{id}
+ */
+import { YodelError } from "../project.js";
+const PAGE = 100;
+const MAX_PAGES = 50;
+function client(t, f, shape) {
+    const call = async (method, url, body) => {
+        let res;
+        try {
+            res = await f(url, { method, headers: { ...shape.headers, ...(body ? { "Content-Type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+        }
+        catch (e) {
+            throw new YodelError(`${t.forge}: ${method} ${url} failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const text = await res.text();
+        if (!res.ok)
+            throw new YodelError(`${t.forge}: ${method} ${url} answered ${String(res.status)}: ${text.slice(0, 300).replaceAll(t.token, "[token]")}`);
+        return text ? JSON.parse(text) : {};
+    };
+    const toComment = (c) => ({ id: Number(c.id), body: typeof c.body === "string" ? c.body : "", url: shape.webUrl?.(c) ?? (typeof c.html_url === "string" ? c.html_url : undefined) });
+    return {
+        async list() {
+            const all = [];
+            for (let page = 1; page <= MAX_PAGES; page++) {
+                const got = (await call("GET", shape.list(page)));
+                if (!Array.isArray(got))
+                    throw new YodelError(`${t.forge}: listing comments did not return a list`);
+                all.push(...got.filter((c) => shape.keep?.(c) ?? true).map(toComment));
+                if (got.length < PAGE)
+                    break;
+            }
+            return all;
+        },
+        async create(body) {
+            return toComment((await call("POST", shape.create, { body })));
+        },
+        async update(id, body) {
+            return toComment((await call(shape.updateMethod, shape.update(id), { body })));
+        },
+    };
+}
+const repoPath = (repo) => repo.split("/").map(encodeURIComponent).join("/");
+export function commentClient(t, f = fetch) {
+    if (t.forge === "gitlab") {
+        const base = `${t.apiUrl}/projects/${encodeURIComponent(t.repo)}/merge_requests/${String(t.pr)}/notes`;
+        return client(t, f, {
+            headers: { "PRIVATE-TOKEN": t.token, Accept: "application/json" },
+            list: (page) => `${base}?per_page=${String(PAGE)}&page=${String(page)}&sort=asc&order_by=created_at`,
+            create: base,
+            update: (id) => `${base}/${String(id)}`,
+            updateMethod: "PUT",
+            // System notes ("added 1 commit") are the forge's own, never ours.
+            keep: (c) => c.system !== true,
+        });
+    }
+    if (t.forge === "forgejo") {
+        const base = `${t.apiUrl}/repos/${repoPath(t.repo)}/issues`;
+        return client(t, f, {
+            headers: { Authorization: `token ${t.token}`, Accept: "application/json" },
+            list: (page) => `${base}/${String(t.pr)}/comments?limit=${String(PAGE)}&page=${String(page)}`,
+            create: `${base}/${String(t.pr)}/comments`,
+            update: (id) => `${base}/comments/${String(id)}`,
+            updateMethod: "PATCH",
+        });
+    }
+    const base = `${t.apiUrl}/repos/${repoPath(t.repo)}/issues`;
+    return client(t, f, {
+        headers: { Authorization: `Bearer ${t.token}`, Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" },
+        list: (page) => `${base}/${String(t.pr)}/comments?per_page=${String(PAGE)}&page=${String(page)}`,
+        create: `${base}/${String(t.pr)}/comments`,
+        update: (id) => `${base}/comments/${String(id)}`,
+        updateMethod: "PATCH",
+    });
+}
+/** The comment carrying `marker`, the newest when several do. */
+export async function findComment(c, marker) {
+    return (await c.list()).filter((x) => x.body.includes(marker)).at(-1);
+}
+/** Updates the comment carrying `marker`, or creates one. */
+export async function upsertComment(c, marker, body, existing) {
+    if (!body.includes(marker))
+        throw new YodelError("the comment body has no marker; it could never be found again to update");
+    const found = existing ?? (await findComment(c, marker));
+    if (!found)
+        return { action: "created", comment: await c.create(body) };
+    if (found.body === body)
+        return { action: "unchanged", comment: found };
+    return { action: "updated", comment: await c.update(found.id, body) };
+}
+//# sourceMappingURL=comment.js.map

package/dist/pr/comment.js.map

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

package/dist/pr/forge.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Where `yodel plan <env> --comment` posts: the forge, the repository, the
+ * pull (merge) request and the token, from the CI job's environment, each
+ * overridden by a flag.
+ *
+ * - GitHub Actions: `GITHUB_ACTIONS=true`. `GITHUB_REPOSITORY`, the PR number
+ *   from the event payload (`GITHUB_EVENT_PATH`: `pull_request.number`, or
+ *   `refs/pull/<n>/merge` in `GITHUB_REF`), `GITHUB_API_URL` (default
+ *   https://api.github.com), token `GITHUB_TOKEN`.
+ * - GitLab CI: `GITLAB_CI=true`. `CI_API_V4_URL`, `CI_PROJECT_ID`,
+ *   `CI_MERGE_REQUEST_IID` (a merge request pipeline), token `GITLAB_TOKEN`
+ *   (a project or personal access token with `api` scope: `CI_JOB_TOKEN`
+ *   cannot write merge request notes).
+ * - Forgejo Actions: `FORGEJO_ACTIONS=true` (runner 7 and later), or
+ *   `GITEA_ACTIONS=true`, or a GitHub-style job whose API URL ends in
+ *   `/api/v1`. `FORGEJO_REPOSITORY` / `GITHUB_REPOSITORY`, the PR number from
+ *   `FORGEJO_EVENT_PATH` / `GITHUB_EVENT_PATH` or the ref, `FORGEJO_API_URL` /
+ *   `GITHUB_API_URL` (else `<server>/api/v1`), token `FORGEJO_TOKEN` /
+ *   `GITHUB_TOKEN`.
+ *
+ * `--token-env <NAME>` names the variable the token is read from; the token
+ * itself is never a flag, never printed and never put in an error.
+ */
+export type ForgeKind = "github" | "gitlab" | "forgejo";
+export declare const FORGES: readonly ForgeKind[];
+export interface ForgeTarget {
+    forge: ForgeKind;
+    /** `owner/name` (GitHub, Forgejo), or the project id or path (GitLab). */
+    repo: string;
+    /** The PR number (GitHub, Forgejo) or MR iid (GitLab). */
+    pr: number;
+    /** The REST API's base, e.g. https://api.github.com, https://gitlab.com/api/v4, https://codeberg.org/api/v1. */
+    apiUrl: string;
+    token: string;
+    /** The variable the token came from, for messages. */
+    tokenEnv: string;
+}
+export interface ForgeFlags {
+    forge?: string | undefined;
+    repo?: string | undefined;
+    pr?: string | undefined;
+    apiUrl?: string | undefined;
+    tokenEnv?: string | undefined;
+}
+/** Which forge the job runs on, from its environment; `undefined` outside a known CI. */
+export declare function detectForge(env: NodeJS.ProcessEnv): ForgeKind | undefined;
+/** The PR number from a GitHub-style event payload, or from the ref. */
+export declare function prFromEvent(eventPath: string | undefined, ref: string | undefined): number | undefined;
+/** Resolves the target from flags and the environment, or says what is missing. */
+export declare function resolveForgeTarget(flags: ForgeFlags, env: NodeJS.ProcessEnv): ForgeTarget;

package/dist/pr/forge.js

@@ -0,0 +1,105 @@
+/**
+ * Where `yodel plan <env> --comment` posts: the forge, the repository, the
+ * pull (merge) request and the token, from the CI job's environment, each
+ * overridden by a flag.
+ *
+ * - GitHub Actions: `GITHUB_ACTIONS=true`. `GITHUB_REPOSITORY`, the PR number
+ *   from the event payload (`GITHUB_EVENT_PATH`: `pull_request.number`, or
+ *   `refs/pull/<n>/merge` in `GITHUB_REF`), `GITHUB_API_URL` (default
+ *   https://api.github.com), token `GITHUB_TOKEN`.
+ * - GitLab CI: `GITLAB_CI=true`. `CI_API_V4_URL`, `CI_PROJECT_ID`,
+ *   `CI_MERGE_REQUEST_IID` (a merge request pipeline), token `GITLAB_TOKEN`
+ *   (a project or personal access token with `api` scope: `CI_JOB_TOKEN`
+ *   cannot write merge request notes).
+ * - Forgejo Actions: `FORGEJO_ACTIONS=true` (runner 7 and later), or
+ *   `GITEA_ACTIONS=true`, or a GitHub-style job whose API URL ends in
+ *   `/api/v1`. `FORGEJO_REPOSITORY` / `GITHUB_REPOSITORY`, the PR number from
+ *   `FORGEJO_EVENT_PATH` / `GITHUB_EVENT_PATH` or the ref, `FORGEJO_API_URL` /
+ *   `GITHUB_API_URL` (else `<server>/api/v1`), token `FORGEJO_TOKEN` /
+ *   `GITHUB_TOKEN`.
+ *
+ * `--token-env <NAME>` names the variable the token is read from; the token
+ * itself is never a flag, never printed and never put in an error.
+ */
+import { readFileSync } from "node:fs";
+import { YodelError } from "../project.js";
+export const FORGES = ["github", "gitlab", "forgejo"];
+const truthy = (v) => v === "true" || v === "1";
+/** Which forge the job runs on, from its environment; `undefined` outside a known CI. */
+export function detectForge(env) {
+    if (truthy(env.GITLAB_CI))
+        return "gitlab";
+    if (truthy(env.FORGEJO_ACTIONS) || truthy(env.GITEA_ACTIONS))
+        return "forgejo";
+    if (truthy(env.GITHUB_ACTIONS))
+        return /\/api\/v1\/?$/.test(env.GITHUB_API_URL ?? "") ? "forgejo" : "github";
+    return undefined;
+}
+/** The PR number from a GitHub-style event payload, or from the ref. */
+export function prFromEvent(eventPath, ref) {
+    if (eventPath) {
+        try {
+            const event = JSON.parse(readFileSync(eventPath, "utf8"));
+            const n = event.pull_request?.number ?? (event.issue?.pull_request ? event.issue.number : undefined) ?? (event.pull_request ? event.number : undefined);
+            if (typeof n === "number" && Number.isInteger(n) && n > 0)
+                return n;
+        }
+        catch {
+            // Unreadable payload: fall back to the ref.
+        }
+    }
+    const m = /^refs\/pull\/(\d+)\/(?:merge|head)$/.exec(ref ?? "");
+    return m ? Number(m[1]) : undefined;
+}
+const DEFAULT_TOKEN_ENV = {
+    github: ["GITHUB_TOKEN"],
+    gitlab: ["GITLAB_TOKEN"],
+    forgejo: ["FORGEJO_TOKEN", "GITHUB_TOKEN"],
+};
+/** Resolves the target from flags and the environment, or says what is missing. */
+export function resolveForgeTarget(flags, env) {
+    if (flags.forge !== undefined && !FORGES.includes(flags.forge))
+        throw new YodelError(`--forge must be one of ${FORGES.join(", ")}, got ${JSON.stringify(flags.forge)}`);
+    const forge = flags.forge ?? detectForge(env);
+    if (!forge)
+        throw new YodelError("--comment cannot tell the forge: not a GitHub Actions, GitLab CI or Forgejo Actions job; pass --forge github|gitlab|forgejo with --repo, --pr and --api-url");
+    const pick = (...names) => names.map((n) => env[n]).find((v) => v !== undefined && v !== "");
+    let repo = flags.repo;
+    let pr = flags.pr !== undefined ? Number(flags.pr) : undefined;
+    let apiUrl = flags.apiUrl;
+    if (forge === "gitlab") {
+        repo ??= pick("CI_PROJECT_ID", "CI_PROJECT_PATH");
+        pr ??= pick("CI_MERGE_REQUEST_IID") !== undefined ? Number(pick("CI_MERGE_REQUEST_IID")) : undefined;
+        apiUrl ??= pick("CI_API_V4_URL");
+    }
+    else {
+        const p = forge === "forgejo" ? "FORGEJO_" : "GITHUB_";
+        repo ??= pick(`${p}REPOSITORY`, "GITHUB_REPOSITORY");
+        pr ??= prFromEvent(pick(`${p}EVENT_PATH`, "GITHUB_EVENT_PATH"), pick(`${p}REF`, "GITHUB_REF"));
+        apiUrl ??= pick(`${p}API_URL`, "GITHUB_API_URL");
+        if (!apiUrl && forge === "forgejo") {
+            const server = pick("FORGEJO_SERVER_URL", "GITHUB_SERVER_URL");
+            if (server)
+                apiUrl = `${server.replace(/\/+$/, "")}/api/v1`;
+        }
+        if (!apiUrl && forge === "github")
+            apiUrl = "https://api.github.com";
+    }
+    const missing = [];
+    if (!repo)
+        missing.push(forge === "gitlab" ? "the project (--repo, or CI_PROJECT_ID)" : "the repository (--repo owner/name, or GITHUB_REPOSITORY)");
+    if (pr === undefined || !Number.isInteger(pr) || pr <= 0) {
+        missing.push(forge === "gitlab" ? "the merge request (--pr, or CI_MERGE_REQUEST_IID in a merge request pipeline)" : "the pull request (--pr, or a pull_request event)");
+    }
+    if (!apiUrl)
+        missing.push(forge === "gitlab" ? "the API URL (--api-url, or CI_API_V4_URL)" : "the API URL (--api-url, or FORGEJO_API_URL / GITHUB_API_URL)");
+    const names = flags.tokenEnv ? [flags.tokenEnv] : DEFAULT_TOKEN_ENV[forge];
+    const tokenEnv = names.find((n) => env[n]) ?? names[0] ?? "";
+    const token = env[tokenEnv] ?? "";
+    if (!token)
+        missing.push(`a token (${names.join(" or ")} is not set${flags.tokenEnv ? "" : "; name another variable with --token-env"})`);
+    if (missing.length > 0)
+        throw new YodelError(`--comment on ${forge} needs ${missing.join(", ")}`);
+    return { forge, repo: repo, pr: pr, apiUrl: apiUrl.replace(/\/+$/, ""), token, tokenEnv };
+}
+//# sourceMappingURL=forge.js.map

package/dist/pr/forge.js.map

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

package/dist/pr/model.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The versioned plan (#16): what `yodel plan <env>` shows for a project
+ * with migrations, and what the pull request comment renders. Collected once,
+ * rendered as text, markdown or JSON (`./render.ts`).
+ *
+ * The digest is `statusReport`'s, the value `yodel apply <env> --digest` (the
+ * migrations Op's Plan step) prints and the gate binds, so the
+ * `chant approve <op> <gate> --plan <digest>` the comment prints is the one
+ * the post-merge apply needs. Nothing here writes: no lock, no history row,
+ * no ledger entry.
+ */
+import type { MigrationStep } from "@intentius/chant-lexicon-sql/migration-statements";
+import type { GateLedgerPort } from "@intentius/chant/op/gate";
+import { type Environment, type Project, type SqlDialect } from "../project.js";
+import { type MigrateOpRef, type VersionedEnv } from "../versioned/index.js";
+import { type LatestApproval, type MoveExplanation } from "../versioned/explain.js";
+import type { DigestSubject } from "../versioned/digest.js";
+export interface StepView {
+    index: number;
+    step: MigrationStep;
+    /** Succeeded in an earlier run; not sent again. */
+    done: boolean;
+    /** An Op or manual step apply does not run, and why; any of them refuses the run. */
+    refused?: string | undefined;
+    /** A backfill step's module, as the migration's directory holds it. */
+    source?: {
+        file: string;
+        text: string;
+    } | undefined;
+}
+export interface PendingView {
+    id: string;
+    outOfOrder: boolean;
+    /** Where a migration that ran part way resumes. */
+    resumeAt?: number | undefined;
+    steps: StepView[];
+}
+export type ApprovalView = {
+    kind: "no-op";
+    message: string;
+} | {
+    kind: "op";
+    op: string;
+    gate: string;
+    /** The command that approves this plan; absent when there is no digest. */
+    command?: string | undefined;
+    /** The newest approval of the gate in chant's ledger, when it could be read. */
+    latest?: (LatestApproval & {
+        moved?: MoveExplanation | undefined;
+    }) | undefined;
+    /** Why the ledger was not read. */
+    ledgerNote?: string | undefined;
+};
+export interface VersionedPlan {
+    environment: string;
+    dialect: SqlDialect;
+    /** `<database>.history (<topology> (<where it came from>))`; Postgres has no topology, so only `<database>.history`. */
+    history?: string | undefined;
+    appliedCount: number;
+    pending: PendingView[];
+    /** Directory problems, checksum mismatches, out-of-order migrations. */
+    problems: string[];
+    /** Why `yodel apply` would refuse, with its exit code. */
+    refusal?: {
+        exitCode: number;
+        message: string;
+    } | undefined;
+    /** The digest the gate binds; absent when apply would refuse or has nothing to do. */
+    digest?: string | undefined;
+    /** What the digest is taken over, carried in the comment so a later one can say what moved. */
+    subject?: DigestSubject | undefined;
+    approval?: ApprovalView | undefined;
+    /** The comment this one replaces showed another digest: what moved since. */
+    sinceLast?: MoveExplanation | undefined;
+    notes: string[];
+}
+export interface CollectOptions {
+    allowOutOfOrder?: boolean;
+    /** The subject the previous comment carried, when updating one. */
+    previous?: DigestSubject | undefined;
+    /** The gate ledger; default chant's, in the project's git checkout. `null` skips it. */
+    ledger?: GateLedgerPort | null;
+    /** The migrations Op; default discovered in the project. */
+    op?: MigrateOpRef | null;
+    opName?: string | undefined;
+    processEnv?: NodeJS.ProcessEnv;
+    /** For tests: the environment already bound. */
+    venv?: VersionedEnv;
+}
+/** Collects the plan; throws only when the project or the server cannot be read at all. */
+export declare function collectVersionedPlan(project: Project, env: Environment, options?: CollectOptions): Promise<VersionedPlan>;

package/dist/pr/model.js

@@ -0,0 +1,113 @@
+/**
+ * The versioned plan (#16): what `yodel plan <env>` shows for a project
+ * with migrations, and what the pull request comment renders. Collected once,
+ * rendered as text, markdown or JSON (`./render.ts`).
+ *
+ * The digest is `statusReport`'s, the value `yodel apply <env> --digest` (the
+ * migrations Op's Plan step) prints and the gate binds, so the
+ * `chant approve <op> <gate> --plan <digest>` the comment prints is the one
+ * the post-merge apply needs. Nothing here writes: no lock, no history row,
+ * no ledger entry.
+ */
+import { YodelError } from "../project.js";
+import { scanMigrations } from "../migrations/index.js";
+import { describeTopology } from "../history/index.js";
+import { asBackfill } from "../steps/kinds.js";
+import { findMigrateOp, gitLedger, migrateOpExample, migrationsDir, closeVersioned, openVersioned, outOfOrder, planDigest, sameDigest, statusReport, } from "../versioned/index.js";
+import { currentSubject, explainAgainst, explainMove, latestApproval } from "../versioned/explain.js";
+const viewOf = (m, done = [], outOfOrder = false, resumeAt, refused = []) => ({
+    id: m.id,
+    outOfOrder,
+    resumeAt,
+    steps: m.document.steps.map((step, index) => {
+        const file = asBackfill(step)?.options.file;
+        const text = file === undefined ? undefined : m.files.extra?.[file];
+        return { index, step, done: done.includes(index), refused: refused.find((r) => r.index === index)?.reason, ...(file !== undefined && text !== undefined ? { source: { file, text } } : {}) };
+    }),
+});
+/** Collects the plan; throws only when the project or the server cannot be read at all. */
+export async function collectVersionedPlan(project, env, options = {}) {
+    const dir = migrationsDir(project);
+    const scan = scanMigrations(dir);
+    const problems = scan.problems.map((p) => p.message);
+    const base = { environment: env.name, dialect: project.dialect, problems, notes: [] };
+    if (!scan.ordered) {
+        return { ...base, appliedCount: 0, pending: [], refusal: { exitCode: 1, message: "the migrations directory is not one unbroken chain; nothing can be applied until it is" } };
+    }
+    const ordered = scan.ordered;
+    const venv = options.venv ?? (await openVersioned(project, env, options.processEnv));
+    try {
+        return await collectWith(project, env, options, venv, ordered, base, problems);
+    }
+    finally {
+        if (!options.venv)
+            await closeVersioned(venv);
+    }
+}
+async function collectWith(project, env, options, venv, ordered, base, problems) {
+    const report = await statusReport(venv, ordered, { allowOutOfOrder: options.allowOutOfOrder === true, sync: false });
+    const { status } = report;
+    for (const m of status.mismatches)
+        if (!problems.includes(m.message))
+            problems.push(m.message);
+    const late = outOfOrder(status);
+    if (late.length > 0)
+        problems.push(`out of order: ${late.map((p) => p.id).join(", ")} (the chain puts ${late.length === 1 ? "it" : "them"} before a migration already applied)`);
+    let subject;
+    if (report.digest) {
+        subject = await currentSubject(venv, status, status.pending);
+        // Read twice (the report's, then here): if the server moved in between, carry no subject rather than a wrong one.
+        if (!(await sameDigest(await planDigest(subject), report.digest)))
+            subject = undefined;
+    }
+    const plan = {
+        ...base,
+        history: venv.dialect === "postgres" ? `${venv.location.database}.history` : `${venv.location.database}.history (${report.topology ?? describeTopology(venv.location.topology)})`,
+        appliedCount: status.applied.length,
+        pending: status.pending.map((p) => viewOf(p.migration, p.partWay?.done ?? [], p.outOfOrder, p.partWay?.resumeAt, p.refusedSteps)),
+        refusal: report.refusal,
+        digest: report.digest,
+        subject,
+    };
+    if (options.previous && subject) {
+        const prev = await planDigest(options.previous);
+        if (!(await sameDigest(prev, report.digest)))
+            plan.sinceLast = await explainMove({ approvedDigest: prev, now: subject, previous: options.previous, ordered, applied: status.applied });
+    }
+    plan.approval = await approvalView(project, env, venv, ordered, plan, options);
+    return plan;
+}
+async function approvalView(project, env, venv, ordered, plan, options) {
+    let op;
+    try {
+        op = options.op ?? (await findMigrateOp(project, env, options.opName));
+    }
+    catch (e) {
+        if (!(e instanceof YodelError))
+            throw e;
+        return { kind: "no-op", message: e.message.includes("no Op applies") ? `no Op applies the migrations to ${env.name}; declare one, for example:\n\n${migrateOpExample(env.name)}` : e.message };
+    }
+    const view = {
+        kind: "op",
+        op: op.name,
+        gate: op.gate,
+        command: plan.digest ? `chant approve ${op.name} ${op.gate} --plan ${plan.digest}` : undefined,
+    };
+    if (options.ledger === null)
+        return view;
+    try {
+        const ledger = options.ledger ?? (await gitLedger(project.dir));
+        const latest = await latestApproval(ledger, op, plan.digest);
+        if (!latest)
+            return view;
+        view.latest = latest;
+        if (!latest.holds && !latest.sameDigest && latest.digest && plan.subject) {
+            view.latest.moved = await explainAgainst(venv, ordered, { approvedDigest: latest.digest, approvedAt: latest.at, now: plan.subject, previous: options.previous });
+        }
+    }
+    catch (e) {
+        view.ledgerNote = `chant's gate ledger could not be read (${e instanceof Error ? (e.message.split("\n")[0] ?? "") : String(e)}); fetch the chant/lifecycle branch to see approvals here`;
+    }
+    return view;
+}
+//# sourceMappingURL=model.js.map

package/dist/pr/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/pr/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,UAAU,EAAmD,MAAM,eAAe,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAkB,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EACL,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,aAAa,EACb,UAAU,EACV,UAAU,EACV,UAAU,EACV,YAAY,GAIb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAA6C,MAAM,yBAAyB,CAAC;AAuEjJ,MAAM,MAAM,GAAG,CAAC,CAAY,EAAE,OAA0B,EAAE,EAAE,UAAU,GAAG,KAAK,EAAE,QAAiB,EAAE,UAA4C,EAAE,EAAe,EAAE,CAAC,CAAC;IAClK,EAAE,EAAE,CAAC,CAAC,EAAE;IACR,UAAU;IACV,QAAQ;IACR,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC1C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC;QACpE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC/L,CAAC,CAAC;CACH,CAAC,CAAC;AAEH,2FAA2F;AAC3F,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAgB,EAAE,GAAgB,EAAE,UAA0B,EAAE;IACzG,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,EAAE,WAAW,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAc,EAAE,CAAC;IAElG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,wFAAwF,EAAE,EAAE,CAAC;IAChL,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAE7B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,MAAM,aAAa,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IACrF,IAAI,CAAC;QACH,OAAO,MAAM,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACjF,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,OAAO,CAAC,IAAI;YAAE,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;AACH,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,OAAgB,EAChB,GAAgB,EAChB,OAAuB,EACvB,IAAkB,EAClB,OAA6B,EAC7B,IAA+F,EAC/F,QAAkB;IAElB,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,KAAK,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACrH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,UAAU;QAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC/F,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,sCAAsC,CAAC,CAAC;IAEjL,IAAI,OAAkC,CAAC;IACvC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC7D,kHAAkH;QAClH,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;YAAE,OAAO,GAAG,SAAS,CAAC;IACzF,CAAC;IAED,MAAM,IAAI,GAAkB;QAC1B,GAAG,IAAI;QACP,OAAO,EAAE,IAAI,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,aAAa,MAAM,CAAC,QAAQ,IAAI,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG;QACjL,YAAY,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM;QACnC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC;QACjI,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO;KACR,CAAC;IAEF,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAChD,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;YAAE,IAAI,CAAC,SAAS,GAAG,MAAM,WAAW,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACzL,CAAC;IAED,IAAI,CAAC,QAAQ,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC/E,OAAO,IAAI,CAAC;AACd,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,OAAgB,EAAE,GAAgB,EAAE,IAAkB,EAAE,OAA6B,EAAE,IAAmB,EAAE,OAAuB;IAC7J,IAAI,EAAgB,CAAC;IACrB,IAAI,CAAC;QACH,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,CAAC,MAAM,aAAa,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACzE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,CAAC,CAAC,YAAY,UAAU,CAAC;YAAE,MAAM,CAAC,CAAC;QACxC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,mCAAmC,GAAG,CAAC,IAAI,kCAAkC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACjM,CAAC;IACD,MAAM,IAAI,GAA0C;QAClD,IAAI,EAAE,IAAI;QACV,EAAE,EAAE,EAAE,CAAC,IAAI;QACX,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,WAAW,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS;KAC/F,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QAChE,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7D,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACzE,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QACnK,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,UAAU,GAAG,0CAA0C,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,2DAA2D,CAAC;IAC3L,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/pr/render.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The versioned plan as text (`yodel plan <env>`), as the pull request
+ * comment's markdown (`--format markdown`, `--comment`) and as JSON.
+ *
+ * The comment starts with a hidden marker, `<!-- yodel:plan env=<env> -->`,
+ * by which `--comment` finds the comment it posted before and updates it,
+ * and ends with the digest's subject, hidden, so the next comment can say
+ * what moved. Neither holds a secret: migration ids, checksums, a hash of
+ * the live catalog. Server addresses and tokens are never rendered.
+ */
+import type { VersionedPlan } from "./model.js";
+/** The marker that identifies one environment's plan comment. */
+export declare const commentMarker: (env: string) => string;
+/** The subject a comment body carries, encoded. */
+export declare const subjectIn: (body: string) => string | undefined;
+/** GitHub refuses a comment over 65536 characters; GitLab and Forgejo allow more. */
+export declare const COMMENT_LIMIT = 65000;
+/** Values a statement may quote that do not belong in a comment, though the file is in the repo. */
+export declare function redact(sql: string): string;
+/** `yodel plan <env>` for a project with migrations. */
+export declare function renderPlanText(plan: VersionedPlan): string;
+/** The pull request comment body. */
+export declare function renderPlanMarkdown(plan: VersionedPlan, options?: {
+    sql?: boolean;
+}): string;
+/** `yodel plan <env> --json` for a project with migrations. */
+export declare function planJsonVersioned(plan: VersionedPlan): Record<string, unknown>;