@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/pr/forge.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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;
+/** Where a job writes on its forge, without a pull request: the repository, the API and the token. */
+export type ForgeRepo = Omit<ForgeTarget, "pr">;
+/** Resolves the target from flags and the environment, or says what is missing. */
+export declare function resolveForgeTarget(flags: ForgeFlags, env: NodeJS.ProcessEnv): ForgeTarget;
+/** The repository a job writes to (`yodel drift --issue`), from flags and the environment, or says what is missing. */
+export declare function resolveForgeRepo(flags: Omit<ForgeFlags, "pr">, env: NodeJS.ProcessEnv, what?: string): ForgeRepo;

package/dist/pr/forge.js

@@ -0,0 +1,119 @@
+/**
+ * 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 repository, API and token from flags and the environment;
+ * `pr` also the pull (merge) request. `what` names the option that needs
+ * them, for messages (`--comment`, `--issue`).
+ */
+function resolve(flags, env, what, withPr) {
+    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(`${what} cannot tell the forge: not a GitHub Actions, GitLab CI or Forgejo Actions job; pass --forge github|gitlab|forgejo with --repo${withPr ? ", --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");
+        if (withPr)
+            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 (withPr && (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(`${what} on ${forge} needs ${missing.join(", ")}`);
+    const base = { forge, repo: repo, apiUrl: apiUrl.replace(/\/+$/, ""), token, tokenEnv };
+    return withPr ? { ...base, pr: pr } : base;
+}
+/** Resolves the target from flags and the environment, or says what is missing. */
+export function resolveForgeTarget(flags, env) {
+    return resolve(flags, env, "--comment", true);
+}
+/** The repository a job writes to (`yodel drift --issue`), from flags and the environment, or says what is missing. */
+export function resolveForgeRepo(flags, env, what = "--issue") {
+    return resolve(flags, env, what, false);
+}
+//# 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/issue.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The drift watch's tracking issue (#49): one open issue per project and
+ * environment, found by its marker, opened when drift is found, updated
+ * while it lasts, and closed, with a comment, when it is gone. The three
+ * forges' REST APIs:
+ *
+ *   GitHub   GET/POST {api}/repos/{owner}/{repo}/issues            (open ones; pull requests left out)
+ *            PATCH    {api}/repos/{owner}/{repo}/issues/{n}         body, or state closed
+ *            POST     {api}/repos/{owner}/{repo}/issues/{n}/comments
+ *   GitLab   GET/POST {api}/projects/{id}/issues                   (state opened)
+ *            PUT      {api}/projects/{id}/issues/{iid}              description, or state_event close
+ *            POST     {api}/projects/{id}/issues/{iid}/notes
+ *   Forgejo  as GitHub, under /api/v1, with type=issues and limit
+ *
+ * The client lists only open issues, so a closed one is never reopened:
+ * drift found again after a close opens a new issue.
+ */
+import type { ForgeRepo } from "./forge.js";
+export interface ForgeIssue {
+    number: number;
+    title: string;
+    body: string;
+    url?: string | undefined;
+}
+export interface IssueClient {
+    /** The open issues (not pull requests). */
+    open(): Promise<ForgeIssue[]>;
+    create(title: string, body: string): Promise<ForgeIssue>;
+    update(n: number, title: string, body: string): Promise<ForgeIssue>;
+    /** Comments `comment` on the issue, then closes it. */
+    close(n: number, comment: string): Promise<void>;
+}
+type Fetch = typeof fetch;
+export declare function issueClient(t: ForgeRepo, f?: Fetch): IssueClient;
+/**
+ * The marker an environment's tracking issue carries, so the next run finds
+ * it. Keyed by the project's directory in its repository (`.` at the root),
+ * so two projects in one repository keep their own issues.
+ */
+export declare function driftIssueMarker(project: string, environment: string): string;
+/** What the run found, as the tracking issue needs it. */
+export type DriftOutcome = {
+    kind: "drift";
+    title: string;
+    body: string;
+    fingerprint: string;
+} | {
+    kind: "clean";
+    comment: string;
+}
+/** The drift could not be read, or part of the environment could not: the issue is left as it is. */
+ | {
+    kind: "unknown";
+    why: string;
+};
+export type IssueAction = {
+    action: "opened" | "updated" | "unchanged" | "closed";
+    issue: ForgeIssue;
+} | {
+    action: "none";
+} | {
+    action: "left";
+    why: string;
+    issue?: ForgeIssue;
+};
+/** Brings the environment's tracking issue in line with the outcome; see the module comment. */
+export declare function trackDrift(client: IssueClient, marker: string, outcome: DriftOutcome): Promise<IssueAction>;
+export {};

package/dist/pr/issue.js

@@ -0,0 +1,107 @@
+/**
+ * The drift watch's tracking issue (#49): one open issue per project and
+ * environment, found by its marker, opened when drift is found, updated
+ * while it lasts, and closed, with a comment, when it is gone. The three
+ * forges' REST APIs:
+ *
+ *   GitHub   GET/POST {api}/repos/{owner}/{repo}/issues            (open ones; pull requests left out)
+ *            PATCH    {api}/repos/{owner}/{repo}/issues/{n}         body, or state closed
+ *            POST     {api}/repos/{owner}/{repo}/issues/{n}/comments
+ *   GitLab   GET/POST {api}/projects/{id}/issues                   (state opened)
+ *            PUT      {api}/projects/{id}/issues/{iid}              description, or state_event close
+ *            POST     {api}/projects/{id}/issues/{iid}/notes
+ *   Forgejo  as GitHub, under /api/v1, with type=issues and limit
+ *
+ * The client lists only open issues, so a closed one is never reopened:
+ * drift found again after a close opens a new issue.
+ */
+import { YodelError } from "../project.js";
+const PAGE = 100;
+const MAX_PAGES = 20;
+const repoPath = (repo) => repo.split("/").map(encodeURIComponent).join("/");
+export function issueClient(t, f = fetch) {
+    const gitlab = t.forge === "gitlab";
+    const headers = gitlab
+        ? { "PRIVATE-TOKEN": t.token, Accept: "application/json" }
+        : t.forge === "forgejo"
+            ? { Authorization: `token ${t.token}`, Accept: "application/json" }
+            : { Authorization: `Bearer ${t.token}`, Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" };
+    const base = gitlab ? `${t.apiUrl}/projects/${encodeURIComponent(t.repo)}/issues` : `${t.apiUrl}/repos/${repoPath(t.repo)}/issues`;
+    const call = async (method, url, body) => {
+        let res;
+        try {
+            res = await f(url, { method, headers: { ...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 toIssue = (r) => ({
+        number: Number(gitlab ? r.iid : r.number),
+        title: typeof r.title === "string" ? r.title : "",
+        body: typeof (gitlab ? r.description : r.body) === "string" ? String(gitlab ? r.description : r.body) : "",
+        url: typeof r.html_url === "string" ? r.html_url : typeof r.web_url === "string" ? r.web_url : undefined,
+    });
+    const list = (page) => gitlab
+        ? `${base}?state=opened&per_page=${String(PAGE)}&page=${String(page)}`
+        : t.forge === "forgejo"
+            ? `${base}?state=open&type=issues&limit=${String(PAGE)}&page=${String(page)}`
+            : `${base}?state=open&per_page=${String(PAGE)}&page=${String(page)}`;
+    return {
+        async open() {
+            const all = [];
+            for (let page = 1; page <= MAX_PAGES; page++) {
+                const got = (await call("GET", list(page)));
+                if (!Array.isArray(got))
+                    throw new YodelError(`${t.forge}: listing issues did not return a list`);
+                all.push(...got.filter((r) => r.pull_request === undefined || r.pull_request === null).map(toIssue));
+                if (got.length < PAGE)
+                    break;
+            }
+            return all;
+        },
+        async create(title, body) {
+            return toIssue((await call("POST", base, gitlab ? { title, description: body } : { title, body })));
+        },
+        async update(n, title, body) {
+            return toIssue((await call(gitlab ? "PUT" : "PATCH", `${base}/${String(n)}`, gitlab ? { title, description: body } : { title, body })));
+        },
+        async close(n, comment) {
+            await call("POST", `${base}/${String(n)}/${gitlab ? "notes" : "comments"}`, { body: comment });
+            await call(gitlab ? "PUT" : "PATCH", `${base}/${String(n)}`, gitlab ? { state_event: "close" } : { state: "closed" });
+        },
+    };
+}
+/**
+ * The marker an environment's tracking issue carries, so the next run finds
+ * it. Keyed by the project's directory in its repository (`.` at the root),
+ * so two projects in one repository keep their own issues.
+ */
+export function driftIssueMarker(project, environment) {
+    const clean = (s) => s.replace(/\s+/g, "_").replace(/-->/g, "");
+    return `<!-- yodel:drift project=${clean(project || ".")} env=${clean(environment)} -->`;
+}
+/** Brings the environment's tracking issue in line with the outcome; see the module comment. */
+export async function trackDrift(client, marker, outcome) {
+    const found = (await client.open()).filter((i) => i.body.includes(marker)).sort((a, b) => a.number - b.number);
+    const issue = found[0];
+    if (outcome.kind === "unknown")
+        return { action: "left", why: outcome.why, ...(issue ? { issue } : {}) };
+    if (outcome.kind === "clean") {
+        if (!issue)
+            return { action: "none" };
+        await client.close(issue.number, outcome.comment);
+        return { action: "closed", issue };
+    }
+    const body = `${marker}\n${outcome.body}`;
+    if (!issue)
+        return { action: "opened", issue: await client.create(outcome.title, body) };
+    if (issue.body.includes(outcome.fingerprint) && issue.title === outcome.title)
+        return { action: "unchanged", issue };
+    return { action: "updated", issue: await client.update(issue.number, outcome.title, body) };
+}
+//# sourceMappingURL=issue.js.map

package/dist/pr/issue.js.map

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

package/dist/pr/model.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 MigrationCheck } from "../migrations/index.js";
+import { type MigrateOpRef, type RuleResult, type VersionedEnv } from "../versioned/index.js";
+import { type LatestApproval, type MoveExplanation } from "../versioned/explain.js";
+import type { DigestSubject } from "../versioned/digest.js";
+import type { ServerInfo } from "../server.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;
+    /** Its pre-migration checks (#52), run before its first statement. */
+    checks?: MigrationCheck[] | 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;
+    /** The server the plan was read from (#11). */
+    server?: ServerInfo | undefined;
+    /** `<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;
+    /** Each policy rule's outcome over the plan (#53), with any override recorded for its digest; absent when yodel.config.ts declares no policy. */
+    policy?: RuleResult[] | 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,137 @@
+/**
+ * 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 { EXIT_REFUSED } from "../exit.js";
+import { BROKEN_CHAIN, findMigrateOp, inspect, gitLedger, judgePlan, 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,
+    checks: m.document.checks ?? [],
+    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: [] };
+    const venv = options.venv ?? (await openVersioned(project, env, options.processEnv));
+    try {
+        if (!scan.ordered) {
+            // Nothing can be planned, but the history still says what is applied.
+            const { status } = await inspect(venv, [], { sync: false });
+            return { ...base, appliedCount: status.applied.length, pending: [], refusal: { exitCode: EXIT_REFUSED, message: BROKEN_CHAIN } };
+        }
+        return await collectWith(project, env, options, venv, scan.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,
+        ...(report.server ? { server: report.server } : {}),
+        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);
+    if (project.yodel?.config.policy && !report.refusal) {
+        const approval = plan.approval;
+        plan.policy = await judgePlan({
+            policy: project.yodel.config.policy,
+            environment: env.name,
+            dialect: project.dialect,
+            toApply: status.pending,
+            digest: report.digest,
+            ledger: async () => {
+                if (approval.kind !== "op" || options.ledger === null)
+                    return undefined;
+                try {
+                    return { port: options.ledger ?? (await gitLedger(project.dir)), op: options.op ?? (await findMigrateOp(project, env, options.opName)) };
+                }
+                catch {
+                    return undefined;
+                }
+            },
+        });
+    }
+    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":"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"}