@intentius/sql-yodeler 0.2.0 → 0.4.0

package/dist/report/model.js

@@ -0,0 +1,127 @@
+/**
+ * `yodel report` (#57): every environment's migrations side by side, the
+ * audit log derived from each environment's history and chant's gate ledger
+ * (`./audit.ts`), and the gaps those sources show. Read only: it takes no
+ * lock and writes nothing to a server or the ledger.
+ */
+import { deriveState } from "../history/index.js";
+import { resolveEnvironment } from "../project.js";
+import { closeVersioned, findMigrateOp, gitLedger, openVersioned } from "../versioned/index.js";
+import { WAVES_PIPELINE } from "../waves/record.js";
+import { baseEnvironment } from "../tenants/target.js";
+import { approvalOf, byTime, deriveAudit, isoTime } from "./audit.js";
+export const REPORT_VERSION = 1;
+export const liveSources = {
+    async rows(project, name) {
+        const venv = await openVersioned(project, resolveEnvironment(project, name));
+        try {
+            return { rows: await venv.store.rows({ sync: false }), history: `${venv.location.database}.history` };
+        }
+        finally {
+            await closeVersioned(venv);
+        }
+    },
+    op: (project, name) => findMigrateOp(project, resolveEnvironment(project, name)),
+    ledger: (project) => gitLedger(project.dir),
+};
+const firstLine = (e) => (e instanceof Error ? (e.message.split("\n")[0] ?? "") : String(e));
+/** Reads every environment in `names` and derives the report. An environment that cannot be read is reported with its error. */
+export async function collectReport(project, chain, names, sources = liveSources, now = new Date()) {
+    const { samePlanDigest } = await import("@intentius/chant/lifecycle/plan-digest");
+    const { gateLedgerPath } = await import("@intentius/chant/lifecycle/gate-ledger");
+    let port;
+    let portError;
+    try {
+        port = await sources.ledger(project);
+    }
+    catch (e) {
+        portError = firstLine(e);
+    }
+    const environments = [];
+    const audit = [];
+    const gaps = [];
+    const known = new Set(chain.map((m) => m.id));
+    const extra = [];
+    for (const name of names) {
+        const env = { name, notes: [], migrations: [] };
+        environments.push(env);
+        let rows;
+        try {
+            const read = await sources.rows(project, name);
+            rows = read.rows;
+            env.history = read.history;
+        }
+        catch (e) {
+            env.error = `the history could not be read: ${firstLine(e)}`;
+            continue;
+        }
+        let ledger;
+        try {
+            const op = await sources.op(project, name);
+            env.op = { name: op.name, gate: op.gate };
+            if (!port)
+                throw new Error(portError ?? "no ledger");
+            const lines = await port.read(op.name);
+            ledger = { op: op.name, gate: op.gate, path: gateLedgerPath(op.name), pending: lines.pending, resolutions: lines.resolutions };
+        }
+        catch (e) {
+            env.notes.push(env.op ? `chant's gate ledger could not be read (${firstLine(e)}); approvals are not shown and not checked` : `no migrations Op for ${name} (${firstLine(e)}); approvals are not shown and not checked`);
+        }
+        // The apply pipeline's waves (#87): their gates are on the waves' op's ledger, not the migrations Op's.
+        let waves;
+        const k = (project.yodel?.config.waves ?? []).findIndex((w) => w.env === baseEnvironment(name)) + 1;
+        if (port && (k > 0 || rows.some((r) => r.kind === "migration" && r.note.includes('"wave"')))) {
+            try {
+                const { waveGateName } = await import("@intentius/chant/gated-waves");
+                const lines = await port.read(WAVES_PIPELINE);
+                waves = { op: WAVES_PIPELINE, path: gateLedgerPath(WAVES_PIPELINE), ...(k > 0 ? { gate: waveGateName(WAVES_PIPELINE, k) } : {}), pending: lines.pending, resolutions: lines.resolutions };
+            }
+            catch (e) {
+                env.notes.push(`the waves' gate ledger could not be read (${firstLine(e)}); wave approvals are not shown and not checked`);
+            }
+        }
+        const derived = deriveAudit({ environment: name, history: env.history ?? "history", rows, ledger, waves, sameDigest: samePlanDigest });
+        audit.push(...derived.entries);
+        gaps.push(...derived.gaps);
+        const state = deriveState(rows);
+        const listed = [...chain.map((m) => m.id), ...state.migrations.map((m) => m.id).filter((id) => !known.has(id))];
+        for (const id of state.migrations.map((m) => m.id)) {
+            if (!known.has(id) && !extra.includes(id))
+                extra.push(id);
+        }
+        for (const id of listed) {
+            const rec = state.byId.get(id);
+            if (!rec) {
+                env.migrations.push({ id, state: "pending", inDirectory: true });
+                continue;
+            }
+            const appliedEntry = derived.entries.filter((e) => e.kind === "applied" && e.migration === id).at(-1);
+            const approval = appliedEntry
+                ? approvalOf(appliedEntry, derived.entries, samePlanDigest)
+                : rec.planDigest
+                    ? derived.entries.filter((a) => a.kind === "approved" && samePlanDigest(a.digest, rec.planDigest)).at(-1)
+                    : undefined;
+            env.migrations.push({
+                id,
+                state: rec.status === "succeeded" ? "applied" : rec.status,
+                inDirectory: known.has(id),
+                ...(rec.recordedAt ? { at: isoTime(rec.recordedAt) } : {}),
+                ...(rec.appliedBy ? { by: rec.appliedBy } : {}),
+                ...(rec.planDigest ? { digest: rec.planDigest } : {}),
+                ...(approval?.by ? { approvedBy: approval.by, approvedAt: approval.at } : {}),
+            });
+        }
+    }
+    audit.sort(byTime);
+    return {
+        version: REPORT_VERSION,
+        generatedAt: now.toISOString(),
+        project: project.dir,
+        dialect: project.dialect,
+        migrations: [...chain.map((m) => m.id), ...extra],
+        environments,
+        audit,
+        gaps,
+    };
+}
+//# sourceMappingURL=model.js.map

package/dist/report/model.js.map

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

package/dist/report/render.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The report as text, and as a self-contained HTML page (the run view): one
+ * row per migration (each merge that added one), one column per
+ * environment, in the order they were asked for, so a change's progress from
+ * dev to prod reads left to right. Then the gaps and the audit log.
+ */
+import type { AuditEntry } from "./audit.js";
+import type { Report } from "./model.js";
+export declare function renderReportText(r: Report, extra?: {
+    check?: {
+        file: string;
+        missing: readonly string[];
+        appended: number;
+    };
+}): string;
+export declare function auditLine(a: AuditEntry): string;
+/** The run view: a page with no external resources, safe to upload as a CI artifact and open from disk. */
+export declare function renderReportHtml(r: Report): string;

package/dist/report/render.js

@@ -0,0 +1,127 @@
+/**
+ * The report as text, and as a self-contained HTML page (the run view): one
+ * row per migration (each merge that added one), one column per
+ * environment, in the order they were asked for, so a change's progress from
+ * dev to prod reads left to right. Then the gaps and the audit log.
+ */
+const short = (d) => (d ? (d.length > 24 ? `${d.slice(0, 24)}...` : d) : "");
+const day = (t) => (t ? t.slice(0, 16).replace("T", " ") : "");
+function cell(m) {
+    if (!m)
+        return "-";
+    if (m.state === "applied")
+        return `applied ${day(m.at)}`;
+    return m.state;
+}
+export function renderReportText(r, extra = {}) {
+    const lines = [`Report for ${r.project} (${r.dialect}, ${String(r.environments.length)} environment${r.environments.length === 1 ? "" : "s"})`, ""];
+    const head = ["migration", ...r.environments.map((e) => e.name)];
+    const rows = r.migrations.map((id) => [id, ...r.environments.map((e) => (e.error ? "unread" : cell(e.migrations.find((m) => m.id === id))))]);
+    const widths = head.map((h, i) => Math.max(h.length, ...rows.map((row) => (row[i] ?? "").length)));
+    const fmt = (row) => row.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ").trimEnd();
+    lines.push(fmt(head), ...rows.map(fmt));
+    if (r.migrations.length === 0)
+        lines.push("(no migrations)");
+    for (const e of r.environments) {
+        if (e.error)
+            lines.push("", `${e.name}: ${e.error}`);
+        for (const n of e.notes)
+            lines.push("", `${e.name}: ${n}`);
+    }
+    lines.push("", r.gaps.length === 0 ? "Gaps: none. Every applied migration has its approval on the ledger, and no history row is missing." : `Gaps (${String(r.gaps.length)}):`);
+    for (const g of r.gaps)
+        lines.push(`  ${g.environment}: ${g.detail}`);
+    if (extra.check) {
+        const c = extra.check;
+        if (c.missing.length === 0)
+            lines.push("", `${c.file}: every entry is still in the sources${c.appended > 0 ? `; ${String(c.appended)} new entr${c.appended === 1 ? "y" : "ies"} appended` : ""}.`);
+        else
+            lines.push("", `${c.file}: ${String(c.missing.length)} entr${c.missing.length === 1 ? "y is" : "ies are"} no longer in the history or the ledger:`, ...c.missing.map((m) => `  ${m}`));
+    }
+    lines.push("", `Audit (${String(r.audit.length)} entries):`);
+    for (const a of r.audit)
+        lines.push(`  ${auditLine(a)}`);
+    return `${lines.join("\n")}\n`;
+}
+export function auditLine(a) {
+    return [a.at, a.environment, a.kind, a.migration ?? "", a.by ? `by ${a.by}` : "", a.digest ? short(a.digest) : "", a.detail ? `(${a.detail})` : ""].filter(Boolean).join("  ");
+}
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/** The run view: a page with no external resources, safe to upload as a CI artifact and open from disk. */
+export function renderReportHtml(r) {
+    const th = r.environments.map((e) => `<th scope="col">${esc(e.name)}${e.op ? `<br><small>${esc(e.op.name)}</small>` : ""}</th>`).join("");
+    const body = r.migrations
+        .map((id) => {
+        const tds = r.environments
+            .map((e) => {
+            if (e.error)
+                return `<td class="unread">unread</td>`;
+            const m = e.migrations.find((x) => x.id === id);
+            if (!m)
+                return `<td class="none">-</td>`;
+            const lines = [m.state];
+            if (m.at)
+                lines.push(day(m.at));
+            if (m.by)
+                lines.push(`by ${m.by}`);
+            if (m.approvedBy)
+                lines.push(`approved by ${m.approvedBy}`);
+            const title = m.digest ? ` title="${esc(m.digest)}"` : "";
+            return `<td class="${m.state}"${title}>${lines.map((l, i) => (i === 0 ? `<b>${esc(l)}</b>` : `<small>${esc(l)}</small>`)).join("<br>")}</td>`;
+        })
+            .join("");
+        return `<tr><th scope="row"><code>${esc(id)}</code></th>${tds}</tr>`;
+    })
+        .join("\n");
+    const notes = r.environments.flatMap((e) => [...(e.error ? [`${e.name}: ${e.error}`] : []), ...e.notes.map((n) => `${e.name}: ${n}`)]);
+    const gaps = r.gaps.length === 0 ? `<p class="ok">No gaps: every applied migration has its approval on the ledger, and no history row is missing.</p>` : `<ul class="gaps">${r.gaps.map((g) => `<li><b>${esc(g.environment)}</b> ${esc(g.detail)}</li>`).join("")}</ul>`;
+    const audit = r.audit
+        .map((a) => `<tr class="k-${a.kind}"><td>${esc(day(a.at))}</td><td>${esc(a.environment)}</td><td>${esc(a.kind)}</td><td><code>${esc(a.migration ?? "")}</code></td><td>${esc(a.by ?? "")}</td><td title="${esc(a.digest ?? "")}"><code>${esc(short(a.digest))}</code></td><td>${esc(a.detail ?? "")}</td></tr>`)
+        .join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Migrations report</title>
+<style>
+:root { --bg: #fff; --fg: #1d1d1f; --muted: #6e6e73; --line: #d2d2d7; --applied: #e3f4e8; --pending: #fff6db; --failed: #fde4e1; --started: #fde4e1; }
+@media (prefers-color-scheme: dark) { :root { --bg: #161618; --fg: #ececf0; --muted: #a1a1a6; --line: #3a3a3c; --applied: #1f3a29; --pending: #3d3317; --failed: #4a2420; --started: #4a2420; } }
+body { background: var(--bg); color: var(--fg); font: 14px/1.45 system-ui, sans-serif; margin: 0; padding: 24px 16px; }
+main { max-width: 1200px; margin: 0 auto; }
+h1 { font-size: 20px; margin: 0 0 4px; } h2 { font-size: 16px; margin: 28px 0 8px; }
+.meta, small { color: var(--muted); }
+.scroll { overflow-x: auto; }
+table { border-collapse: collapse; width: 100%; }
+th, td { border-bottom: 1px solid var(--line); padding: 6px 8px; text-align: left; vertical-align: top; }
+td.applied { background: var(--applied); } td.pending { background: var(--pending); } td.failed, td.started { background: var(--failed); }
+code { font: 12px ui-monospace, monospace; }
+.gaps li { color: #c0392b; } .ok { color: var(--muted); }
+</style>
+</head>
+<body>
+<main>
+<h1>Migrations report</h1>
+<p class="meta">${esc(r.project)} (${esc(r.dialect)}), generated ${esc(r.generatedAt)}. One row per migration, one column per environment.</p>
+${notes.length > 0 ? `<ul>${notes.map((n) => `<li>${esc(n)}</li>`).join("")}</ul>` : ""}
+<div class="scroll"><table>
+<thead><tr><th scope="col">migration</th>${th}</tr></thead>
+<tbody>
+${body}
+</tbody>
+</table></div>
+<h2>Gaps</h2>
+${gaps}
+<h2>Audit log (${String(r.audit.length)} entries)</h2>
+<div class="scroll"><table>
+<thead><tr><th>when</th><th>environment</th><th>what</th><th>migration</th><th>by</th><th>digest</th><th>detail</th></tr></thead>
+<tbody>
+${audit}
+</tbody>
+</table></div>
+</main>
+</body>
+</html>
+`;
+}
+//# sourceMappingURL=render.js.map

package/dist/report/render.js.map

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

package/dist/schema-docs/render.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `yodel docs` (#62): the declared schema as a static reference, from the
+ * sql lexicon's build output (or a migration's recorded schema), with no
+ * server read and nothing to run in the browser.
+ *
+ * - {@link schemaHtml}: one self-contained HTML page (inline CSS, no
+ *   scripts): every object with its columns, keys, relations, ClickHouse
+ *   engine and sort key, comments, DDL, and the migrations that changed it.
+ * - {@link erdMermaid}: a Mermaid `erDiagram` of the tables and views and
+ *   how they relate: Postgres foreign keys, what a view or materialized view
+ *   reads, the table a materialized view writes to, and the local table a
+ *   ClickHouse `Distributed` table serves.
+ *
+ * Both are deterministic: the same input gives the same bytes, so the
+ * output can be committed and compared.
+ */
+import type { BuildOutput } from "../chant/build.js";
+import type { MigrationStep } from "../migrations/index.js";
+/** A migration as far as the reference needs it: its id and its steps. */
+export interface DocsMigration {
+    id: string;
+    steps: readonly MigrationStep[];
+}
+export interface DocsInput {
+    /** The page's title, e.g. the project's name. */
+    title: string;
+    output: BuildOutput;
+    /** Where the schema came from, said under the title: "the declared schema (chant build)", "migration <id>". */
+    source: string;
+    /** The migrations directory's chain, oldest first, for each object's history. */
+    migrations?: readonly DocsMigration[];
+}
+/** One relation between two objects, by export name. */
+export interface Relation {
+    from: string;
+    to: string;
+    kind: "foreign key" | "reads" | "writes to" | "distributes";
+    label: string;
+    /** Foreign keys only: the referencing columns may be null. */
+    optional?: boolean;
+}
+/** Every relation between the objects the ERD draws, in a stable order. */
+export declare function relations(output: BuildOutput): Relation[];
+/** The Mermaid `erDiagram`: one entity per table or view, one line per relation. */
+export declare function erdMermaid(output: BuildOutput): string;
+/** The ERD as Markdown, which GitHub, GitLab and Forgejo render. */
+export declare function erdMarkdown(input: DocsInput): string;
+/** The self-contained HTML reference. */
+export declare function schemaHtml(input: DocsInput): string;