@intentius/sql-yodeler 0.0.0-stage → 0.1.0

package/dist/migrations/create.js.map

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

package/dist/migrations/directory.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 { YodelError } from "../project.js";
+import { type ChecksumCheck } from "./checksum.js";
+import { type MigrationDocument, type MigrationFiles } from "./document.js";
+/** Where a project keeps its migrations, relative to the project directory. */
+export declare const MIGRATIONS_DIR = "migrations";
+/** `<YYYYMMDDTHHMM>-<name>`; a name is lowercase letters and digits, words joined by `-` or `_`. */
+export declare const MIGRATION_ID: RegExp;
+export declare const MIGRATION_NAME: RegExp;
+/** One migration as read from disk. */
+export interface Migration {
+    id: string;
+    /** Its directory, absolute. */
+    dir: string;
+    parent: string | null;
+    /** The checksum `migration.json` records (not recomputed; see {@link verifyChecksum}). */
+    checksum: string;
+    document: MigrationDocument;
+    /** The files' text exactly as read. */
+    files: MigrationFiles;
+}
+export type MigrationProblem = {
+    kind: "unreadable";
+    path: string;
+    message: string;
+} | {
+    kind: "id-mismatch";
+    id: string;
+    recorded: string;
+    message: string;
+} | {
+    kind: "missing-parent";
+    id: string;
+    parent: string;
+    message: string;
+} | {
+    kind: "fork";
+    parent: string | null;
+    children: string[];
+    message: string;
+} | {
+    kind: "unreachable";
+    ids: string[];
+    message: string;
+} | {
+    kind: "checksum";
+    id: string;
+    check: ChecksumCheck;
+    message: string;
+};
+export interface MigrationScan {
+    /** The migrations directory, absolute. */
+    dir: string;
+    /** Every migration that could be read, sorted by id. */
+    migrations: Migration[];
+    /** From the first migration to the newest, when there is no structural problem; else `undefined`. */
+    ordered: Migration[] | undefined;
+    /** Every problem found. Checksum mismatches are listed here but never stop {@link MigrationScan.ordered} being computed. */
+    problems: MigrationProblem[];
+}
+/** A migrations directory that is not one unbroken chain, or (when asked) whose checksums do not match. */
+export declare class MigrationDirectoryError extends YodelError {
+    readonly dir: string;
+    readonly problems: MigrationProblem[];
+    constructor(dir: string, problems: MigrationProblem[]);
+}
+/**
+ * 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 declare function readExtraFiles(at: string): Record<string, string>;
+/** Every migration in `dir` and every problem with the directory. A missing `dir` is an empty directory. */
+export declare function scanMigrations(dir: string): MigrationScan;
+/**
+ * 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 declare function readMigrations(dir: string, options?: {
+    verify?: boolean;
+}): Migration[];
+/** The newest migration of an ordered list (the end of the chain), or `undefined` for none. */
+export declare const newestMigration: (ordered: readonly Migration[]) => Migration | undefined;
+/**
+ * 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 declare function writeMigration(dir: string, migration: {
+    id: string;
+    files: MigrationFiles;
+}): string;

package/dist/migrations/directory.js

@@ -0,0 +1,225 @@
+/**
+ * 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 { 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");
+    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,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`).
+ */
+import type { MigrationStep, SchemaStatements } from "@intentius/chant-lexicon-sql/migration-statements";
+import type { BuildOutput } from "../chant/build.js";
+export type { MigrationStep, SchemaStatements };
+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[];
+    /** 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,82 @@
+/**
+ * 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",
+    "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,20 @@
+/**
+ * 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 "./checksum.js";
+export * from "./create.js";
+export * from "./directory.js";
+export * from "./document.js";

package/dist/migrations/index.js

@@ -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 "./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,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 {};