@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/migrations/directory.js

@@ -0,0 +1,229 @@
+/**
+ * Reading and writing a project's `migrations/` directory.
+ *
+ * Order is the chain of parent ids, as in Alembic and pgroll: the first
+ * migration has `parent: null`, every other names the one it follows, and
+ * the list runs from the first to the newest. The ids' timestamps never
+ * decide the order. A directory is well formed when the parent links make
+ * one unbroken chain:
+ *
+ * - every directory under `migrations/` is named like an id and holds a
+ *   readable `migration.sql` and `migration.json` whose `id` is that name
+ *   (plain files directly under `migrations/`, such as a README, are
+ *   ignored; files inside a migration's directory are its own and count in
+ *   its checksum);
+ * - every parent names a migration in the directory;
+ * - no two migrations have the same parent, `null` included. Two branches
+ *   that each added a migration give one parent two children: a fork. It is
+ *   reported naming both, never ordered by timestamp or by name;
+ * - every migration is reachable from the first (no cycles).
+ *
+ * {@link scanMigrations} reports every problem and never throws on one, for
+ * `yodel lint`. {@link readMigrations} returns the ordered chain or throws a
+ * {@link MigrationDirectoryError} listing the problems, for the verbs that
+ * act on the chain (`new`, `apply`, `rebase`).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { YodelError } from "../project.js";
+import { verifyChecksum } from "./checksum.js";
+import { checksProblem } from "./checks.js";
+import { MIGRATION_JSON, MIGRATION_SQL } from "./document.js";
+/** Where a project keeps its migrations, relative to the project directory. */
+export const MIGRATIONS_DIR = "migrations";
+/** `<YYYYMMDDTHHMM>-<name>`; a name is lowercase letters and digits, words joined by `-` or `_`. */
+export const MIGRATION_ID = /^(\d{8}T\d{4})-([a-z0-9]+(?:[-_][a-z0-9]+)*)$/;
+export const MIGRATION_NAME = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/;
+/** A migrations directory that is not one unbroken chain, or (when asked) whose checksums do not match. */
+export class MigrationDirectoryError extends YodelError {
+    dir;
+    problems;
+    constructor(dir, problems) {
+        super(`${dir}:\n${problems.map((p) => `  ${p.message}`).join("\n")}`);
+        this.dir = dir;
+        this.problems = problems;
+        this.name = "MigrationDirectoryError";
+    }
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * A migration's files besides migration.sql and migration.json, by path
+ * relative to its directory (`/` separators): every regular file at any
+ * depth, except those two and anything whose name starts with `.`.
+ */
+export function readExtraFiles(at) {
+    const out = {};
+    const walk = (rel) => {
+        for (const entry of readdirSync(rel ? join(at, rel) : at).sort()) {
+            if (entry.startsWith("."))
+                continue;
+            const path = rel ? `${rel}/${entry}` : entry;
+            if (!rel && (entry === MIGRATION_SQL || entry === MIGRATION_JSON))
+                continue;
+            const st = statSync(join(at, path));
+            if (st.isDirectory())
+                walk(path);
+            else if (st.isFile())
+                out[path] = readFileSync(join(at, path), "utf8");
+        }
+    };
+    walk("");
+    return out;
+}
+function readOne(dir, id) {
+    const at = join(dir, id);
+    let sql;
+    let json;
+    let extra;
+    try {
+        sql = readFileSync(join(at, MIGRATION_SQL), "utf8");
+        json = readFileSync(join(at, MIGRATION_JSON), "utf8");
+        extra = readExtraFiles(at);
+    }
+    catch (e) {
+        return { kind: "unreadable", path: at, message: `${id}: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    let doc;
+    try {
+        doc = JSON.parse(json);
+    }
+    catch (e) {
+        return { kind: "unreadable", path: join(at, MIGRATION_JSON), message: `${id}/${MIGRATION_JSON} is not JSON: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    const bad = (what) => ({ kind: "unreadable", path: join(at, MIGRATION_JSON), message: `${id}/${MIGRATION_JSON}: ${what}` });
+    if (!isRecord(doc))
+        return bad("not an object");
+    if (typeof doc.id !== "string")
+        return bad("no id");
+    if (doc.parent !== null && typeof doc.parent !== "string")
+        return bad("parent is neither an id nor null");
+    if (typeof doc.checksum !== "string")
+        return bad("no checksum");
+    if (!Array.isArray(doc.steps))
+        return bad("no steps");
+    if (!isRecord(doc.schema))
+        return bad("no recorded schema");
+    const checks = checksProblem(doc.checks);
+    if (checks)
+        return bad(checks);
+    if (doc.id !== id) {
+        return { kind: "id-mismatch", id, recorded: doc.id, message: `${id}/${MIGRATION_JSON} records id ${doc.id}; a migration's id is its directory's name` };
+    }
+    return { id, dir: at, parent: doc.parent, checksum: doc.checksum, document: doc, files: { sql, json, ...(Object.keys(extra).length > 0 ? { extra } : {}) } };
+}
+/** Every migration in `dir` and every problem with the directory. A missing `dir` is an empty directory. */
+export function scanMigrations(dir) {
+    const problems = [];
+    const migrations = [];
+    if (!existsSync(dir))
+        return { dir, migrations, ordered: [], problems };
+    for (const entry of readdirSync(dir).sort()) {
+        if (entry.startsWith("."))
+            continue; // a write in progress, editor and OS files
+        if (!statSync(join(dir, entry)).isDirectory())
+            continue;
+        if (!MIGRATION_ID.test(entry)) {
+            problems.push({ kind: "unreadable", path: join(dir, entry), message: `${entry}: not a migration directory name (expected <YYYYMMDDTHHMM>-<name>)` });
+            continue;
+        }
+        const read = readOne(dir, entry);
+        if ("kind" in read)
+            problems.push(read);
+        else
+            migrations.push(read);
+    }
+    const byId = new Map(migrations.map((m) => [m.id, m]));
+    const children = new Map();
+    for (const m of migrations) {
+        if (m.parent !== null && !byId.has(m.parent)) {
+            problems.push({ kind: "missing-parent", id: m.id, parent: m.parent, message: `${m.id} follows ${m.parent}, which is not in the directory` });
+        }
+        const list = children.get(m.parent) ?? [];
+        list.push(m);
+        children.set(m.parent, list);
+    }
+    for (const [parent, kids] of children) {
+        if (kids.length < 2)
+            continue;
+        const ids = kids.map((k) => k.id);
+        problems.push({
+            kind: "fork",
+            parent,
+            children: ids,
+            message: parent === null
+                ? `fork: ${ids.join(" and ")} are each a first migration (parent null); rebase all but one onto the chain`
+                : `fork: ${ids.join(" and ")} both follow ${parent}; rebase one onto the other`,
+        });
+    }
+    let ordered;
+    const structural = problems.length > 0;
+    if (!structural) {
+        ordered = [];
+        for (let next = children.get(null)?.[0]; next; next = children.get(next.id)?.[0])
+            ordered.push(next);
+        if (ordered.length !== migrations.length) {
+            const reached = new Set(ordered.map((m) => m.id));
+            const ids = migrations.filter((m) => !reached.has(m.id)).map((m) => m.id);
+            problems.push({ kind: "unreachable", ids, message: `${ids.join(", ")} cannot be reached from the first migration (their parents form a cycle)` });
+            ordered = undefined;
+        }
+    }
+    for (const m of migrations) {
+        const check = verifyChecksum(m);
+        if (!check.ok) {
+            problems.push({ kind: "checksum", id: m.id, check, message: `${m.id}: its files hash to ${check.actual}, but ${MIGRATION_JSON} records ${check.recorded || "no checksum"}` });
+        }
+    }
+    return { dir, migrations, ordered, problems };
+}
+/**
+ * The migrations in `dir`, from the first to the newest. Throws a
+ * {@link MigrationDirectoryError} on any structural problem (unreadable,
+ * id mismatch, missing parent, fork, cycle), and, with `verify`, on a
+ * checksum mismatch too. A missing `dir` has no migrations.
+ */
+export function readMigrations(dir, options = {}) {
+    const scan = scanMigrations(dir);
+    const fatal = scan.problems.filter((p) => options.verify === true || p.kind !== "checksum");
+    if (fatal.length > 0 || !scan.ordered)
+        throw new MigrationDirectoryError(dir, fatal);
+    return scan.ordered;
+}
+/** The newest migration of an ordered list (the end of the chain), or `undefined` for none. */
+export const newestMigration = (ordered) => ordered[ordered.length - 1];
+/**
+ * Writes a migration's directory, `<dir>/<id>/`, creating `dir` as needed.
+ * The files go into a hidden directory first and are renamed into place, so
+ * a reader never sees half a migration. An existing `<id>` is an error.
+ * Returns the directory written.
+ */
+export function writeMigration(dir, migration) {
+    const target = join(dir, migration.id);
+    for (const path of Object.keys(migration.files.extra ?? {})) {
+        const parts = path.split("/");
+        if (parts.some((p) => p === "" || p.startsWith(".") || p.includes("\\")) || path === MIGRATION_SQL || path === MIGRATION_JSON) {
+            throw new YodelError(`${migration.id}: ${JSON.stringify(path)} is not a path a migration's own file can have (relative, "/"-separated, no part starting with ".")`);
+        }
+    }
+    if (existsSync(target))
+        throw new YodelError(`${target} already exists; a migration's directory is never overwritten`);
+    mkdirSync(dir, { recursive: true });
+    const staging = join(dir, `.${migration.id}.writing`);
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(staging);
+    try {
+        writeFileSync(join(staging, MIGRATION_SQL), migration.files.sql);
+        writeFileSync(join(staging, MIGRATION_JSON), migration.files.json);
+        for (const [path, text] of Object.entries(migration.files.extra ?? {})) {
+            mkdirSync(dirname(join(staging, path)), { recursive: true });
+            writeFileSync(join(staging, path), text);
+        }
+        renameSync(staging, target);
+    }
+    catch (e) {
+        rmSync(staging, { recursive: true, force: true });
+        throw e;
+    }
+    return target;
+}
+//# sourceMappingURL=directory.js.map

package/dist/migrations/directory.js.map

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

package/dist/migrations/document.d.ts

@@ -0,0 +1,106 @@
+/**
+ * What one migration directory holds, and how its `migration.json` is
+ * written so that the same migration always serializes to the same bytes.
+ *
+ *   migrations/<id>/migration.sql   the statements, each after a comment naming
+ *                                   its object, rule and class (chant's
+ *                                   `renderStatements`); an Op or manual step
+ *                                   is a comment only
+ *   migrations/<id>/migration.json  a {@link MigrationDocument}
+ *   migrations/<id>/<other files>   only when a step names one, such as a
+ *                                   backfill step's `backfill.ts`
+ *
+ * `<id>` is `<UTC timestamp YYYYMMDDTHHMM>-<name>`, e.g.
+ * `20261009T1412-add-country`. The timestamp is for people reading a
+ * directory listing; the order migrations run in is the chain of parent ids,
+ * never the ids' sort order (see `./directory.ts`).
+ */
+import type { MigrationStep, SchemaStatements } from "@intentius/chant-lexicon-sql/migration-statements";
+import type { BuildOutput } from "../chant/build.js";
+export type { MigrationStep, SchemaStatements };
+/**
+ * One pre-migration check: a read-only query and what its result must be.
+ *
+ *   expect "empty" (the default)  the query returns no rows
+ *   expect "true"                 one row, whose first column is true (or 1)
+ *   expect { min?, max? }         one row, whose first column is a number within the bounds (inclusive)
+ */
+export interface MigrationCheck {
+    /** Names the check in output, in a refusal and in the history. Unique within the migration. */
+    name: string;
+    sql: string;
+    expect?: "empty" | "true" | {
+        min?: number;
+        max?: number;
+    };
+}
+export declare const MIGRATION_SQL = "migration.sql";
+export declare const MIGRATION_JSON = "migration.json";
+/** The version of the `migration.json` layout. Bumped only on a change older readers cannot read. */
+export declare const MIGRATION_FORMAT = 1;
+/**
+ * `migration.json`. Every value is plain JSON. Keys are written in the
+ * order listed here, and every nested object (a step, the schema) with its
+ * keys sorted, except that a step starts with `kind, object, type, name`.
+ */
+export interface MigrationDocument {
+    /** {@link MIGRATION_FORMAT}. */
+    format: number;
+    /** The directory's name: `<YYYYMMDDTHHMM>-<name>`. */
+    id: string;
+    /** The id of the migration this one follows, or `null` for the first. */
+    parent: string | null;
+    /** `sha256:<hex>` over this migration's own files; see `./checksum.ts`. */
+    checksum: string;
+    /** When `yodel new` wrote it, ISO 8601 in UTC, to the second. */
+    createdAt?: string;
+    dialect: SchemaStatements["dialect"];
+    /** ClickHouse: the database a bare name in the statements means. */
+    defaultDatabase?: string;
+    /** Postgres: the schema a bare name means; an applier sets `search_path` to it. */
+    defaultSchema?: string;
+    /** Postgres: the major the changes were classified for. */
+    major?: number;
+    /** ClickHouse: unset (or `single`): yodel writes migrations topology-neutral and renders them per environment at apply time. */
+    topology?: string;
+    /** True when a step is an Op or a manual step: the migration is more than its SQL. */
+    refused: boolean;
+    /** What the diff pointed out besides the changes, e.g. a likely rename written as a drop and an add. */
+    hints: string[];
+    /**
+     * Pre-migration checks (#52): read-only queries `yodel apply` runs against
+     * the environment before the migration's first statement; one that fails
+     * refuses the run (exit 4). Absent when there are none. In the checksum,
+     * so in the plan digest. See `./checks.ts`.
+     */
+    checks?: MigrationCheck[];
+    /** In the order they run. An Op step carries the Op's declaration; it has no SQL. */
+    steps: MigrationStep[];
+    /** The recorded schema: the `chant build` output after this migration. The next `yodel new` diffs from it. */
+    schema: BuildOutput;
+}
+/** A migration's files as text, before or after they are on disk. */
+export interface MigrationFiles {
+    /** `migration.sql`. */
+    sql: string;
+    /** `migration.json`. */
+    json: string;
+    /**
+     * The migration's other files, by path relative to its directory with `/`
+     * separators: a backfill step's module, for one. Absent or empty for a
+     * migration that has only the two. They count in the checksum.
+     */
+    extra?: Record<string, string>;
+}
+/** `value` with every object's keys sorted, `head` first in that order; `undefined` members dropped. */
+export declare function sortKeys(value: unknown, head?: readonly string[]): unknown;
+/**
+ * The document in its written key order. Keys outside
+ * {@link MigrationDocument} (a newer yodel's) are kept, sorted, after `hints`
+ * and before `steps`, so a rewrite never drops them.
+ */
+export declare function orderDocument(doc: Record<string, unknown>): Record<string, unknown>;
+/** `migration.json` as written: two-space indent, the key order above, `\n` line endings and a trailing newline. */
+export declare function serializeDocument(doc: MigrationDocument | Record<string, unknown>): string;
+/** Line endings as `\n`: CRLF and lone CR both become LF. */
+export declare const normalizeLineEndings: (text: string) => string;

package/dist/migrations/document.js

@@ -0,0 +1,83 @@
+/**
+ * What one migration directory holds, and how its `migration.json` is
+ * written so that the same migration always serializes to the same bytes.
+ *
+ *   migrations/<id>/migration.sql   the statements, each after a comment naming
+ *                                   its object, rule and class (chant's
+ *                                   `renderStatements`); an Op or manual step
+ *                                   is a comment only
+ *   migrations/<id>/migration.json  a {@link MigrationDocument}
+ *   migrations/<id>/<other files>   only when a step names one, such as a
+ *                                   backfill step's `backfill.ts`
+ *
+ * `<id>` is `<UTC timestamp YYYYMMDDTHHMM>-<name>`, e.g.
+ * `20261009T1412-add-country`. The timestamp is for people reading a
+ * directory listing; the order migrations run in is the chain of parent ids,
+ * never the ids' sort order (see `./directory.ts`).
+ */
+export const MIGRATION_SQL = "migration.sql";
+export const MIGRATION_JSON = "migration.json";
+/** The version of the `migration.json` layout. Bumped only on a change older readers cannot read. */
+export const MIGRATION_FORMAT = 1;
+const STEP_HEAD = ["kind", "object", "type", "name"];
+const DOCUMENT_ORDER = [
+    "format",
+    "id",
+    "parent",
+    "checksum",
+    "createdAt",
+    "dialect",
+    "defaultDatabase",
+    "defaultSchema",
+    "major",
+    "topology",
+    "refused",
+    "hints",
+    "checks",
+    "steps",
+    "schema",
+];
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** `value` with every object's keys sorted, `head` first in that order; `undefined` members dropped. */
+export function sortKeys(value, head = []) {
+    if (Array.isArray(value))
+        return value.map((v) => sortKeys(v));
+    if (!isRecord(value))
+        return value;
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined);
+    const first = head.filter((k) => keys.includes(k));
+    const rest = keys.filter((k) => !head.includes(k)).sort();
+    return Object.fromEntries([...first, ...rest].map((k) => [k, sortKeys(value[k])]));
+}
+/**
+ * The document in its written key order. Keys outside
+ * {@link MigrationDocument} (a newer yodel's) are kept, sorted, after `hints`
+ * and before `steps`, so a rewrite never drops them.
+ */
+export function orderDocument(doc) {
+    const known = new Set(DOCUMENT_ORDER);
+    const out = {};
+    const put = (k) => {
+        const v = doc[k];
+        if (v === undefined)
+            return;
+        if (k === "steps" && Array.isArray(v))
+            out[k] = v.map((s) => sortKeys(s, STEP_HEAD));
+        else
+            out[k] = sortKeys(v);
+    };
+    for (const k of DOCUMENT_ORDER) {
+        if (k === "steps")
+            for (const extra of Object.keys(doc).filter((x) => !known.has(x)).sort())
+                put(extra);
+        put(k);
+    }
+    return out;
+}
+/** `migration.json` as written: two-space indent, the key order above, `\n` line endings and a trailing newline. */
+export function serializeDocument(doc) {
+    return `${JSON.stringify(orderDocument(doc), null, 2)}\n`;
+}
+/** Line endings as `\n`: CRLF and lone CR both become LF. */
+export const normalizeLineEndings = (text) => text.replace(/\r\n?/g, "\n");
+//# sourceMappingURL=document.js.map

package/dist/migrations/document.js.map

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

package/dist/migrations/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The migration directory (#7): what `yodel new` writes and what `apply`
+ * (#8), the replay check (#11), `lint` (#14) and `rebase` / `repair` (#15)
+ * read.
+ *
+ *   readMigrations(dir, { verify? })  the chain, first to newest; throws on a fork, a missing parent, a cycle
+ *   scanMigrations(dir)               every migration and every problem, never throws on one (for lint)
+ *   newestMigration(ordered)          the end of the chain
+ *   computeChecksum(files)            the checksum of one migration's files
+ *   verifyChecksum(m)                 recorded against recomputed
+ *   createMigration(options)          the next migration from a build, offline (pure)
+ *   writeMigration(dir, migration)    puts it on disk
+ *
+ * The file layout is in `./document.ts`, the checksum's exact definition in
+ * `./checksum.ts`, the ordering rules in `./directory.ts`.
+ */
+export * from "./checks.js";
+export * from "./checksum.js";
+export * from "./create.js";
+export * from "./directory.js";
+export * from "./document.js";

package/dist/migrations/index.js

@@ -0,0 +1,22 @@
+/**
+ * The migration directory (#7): what `yodel new` writes and what `apply`
+ * (#8), the replay check (#11), `lint` (#14) and `rebase` / `repair` (#15)
+ * read.
+ *
+ *   readMigrations(dir, { verify? })  the chain, first to newest; throws on a fork, a missing parent, a cycle
+ *   scanMigrations(dir)               every migration and every problem, never throws on one (for lint)
+ *   newestMigration(ordered)          the end of the chain
+ *   computeChecksum(files)            the checksum of one migration's files
+ *   verifyChecksum(m)                 recorded against recomputed
+ *   createMigration(options)          the next migration from a build, offline (pure)
+ *   writeMigration(dir, migration)    puts it on disk
+ *
+ * The file layout is in `./document.ts`, the checksum's exact definition in
+ * `./checksum.ts`, the ordering rules in `./directory.ts`.
+ */
+export * from "./checks.js";
+export * from "./checksum.js";
+export * from "./create.js";
+export * from "./directory.js";
+export * from "./document.js";
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC"}

package/dist/pr/comment.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 type { ForgeTarget } from "./forge.js";
+export interface ForgeComment {
+    id: number;
+    body: string;
+    url?: string | undefined;
+}
+export interface CommentClient {
+    list(): Promise<ForgeComment[]>;
+    create(body: string): Promise<ForgeComment>;
+    update(id: number, body: string): Promise<ForgeComment>;
+}
+type Fetch = typeof fetch;
+export declare function commentClient(t: ForgeTarget, f?: Fetch): CommentClient;
+/** The comment carrying `marker`, the newest when several do. */
+export declare function findComment(c: CommentClient, marker: string): Promise<ForgeComment | undefined>;
+/** Updates the comment carrying `marker`, or creates one. */
+export declare function upsertComment(c: CommentClient, marker: string, body: string, existing?: ForgeComment): Promise<{
+    action: "created" | "updated" | "unchanged";
+    comment: ForgeComment;
+}>;
+export {};

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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"}