@intentius/chant-lexicon-sql 0.124.30 → 0.124.32

package/dist/receipts.js

@@ -0,0 +1,207 @@
+/**
+ * The sql lexicon's `effect()` receipt store (#3657): where the receipts of a
+ * project that uses only the sql lexicon are kept, on the database server the
+ * environment names.
+ *
+ *     ClickHouse   chant_receipts.receipts
+ *     Postgres     chant_receipts.receipts   (or <receiptsSchema>.__chant_receipts)
+ *
+ * The op activities module binds it as `receiptRead`, `receiptWrite` and
+ * `receiptStaleness` (`./op/activities/index.ts`), listed as fallbacks: a
+ * project that also configures aws or k8s keeps its receipts in that
+ * lexicon's receipt row, in whichever order `lexicons` lists them.
+ *
+ * Which server: the environment is the one `chant run --env` sets
+ * (`CHANT_ENV`), else a literal `ownership.env`. Its `sql.profiles.<env>`
+ * binds the server, a `postgres://` URL making it Postgres; with no profile,
+ * `CLICKHOUSE_URL` or `POSTGRES_URL`, picked by `sql.dialect`. A receipt's
+ * address is `<stack>/<env>/<effect>`, from `ownership.stack` and that
+ * environment, the same identity the rebuild's and the column migration's
+ * receipts carry (`./core/receipts.ts`).
+ *
+ * Both tables carry chant's ownership trailer with the `receipts` key in their
+ * comment (the Postgres schema too), so plan, import and prune leave them out.
+ *
+ * A caller that runs its own Op over a server it has already bound (a
+ * migration runner, say) passes that server instead: a ClickHouse endpoint,
+ * or a Postgres connection, whose receipt writes then commit or roll back
+ * with whatever transaction the caller has open on it.
+ */
+import { receiptActivities } from "@intentius/chant/op/receipt-store";
+import { OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import { COMMENT_OWNERSHIP_KEYS, RECEIPTS_TRAILER_KEY } from "./core/ownership.js";
+/** The database (ClickHouse) or schema (Postgres) the receipts are kept in. */
+export const SQL_RECEIPTS_SCHEMA = "chant_receipts";
+/** The table in it. */
+export const SQL_RECEIPTS_TABLE = "receipts";
+/** The table's name in a schema of the user's own (`receiptsSchema`), as the column migration names it. */
+export const SQL_RECEIPTS_TABLE_BESIDE = "__chant_receipts";
+async function loadConfig(cwd) {
+    try {
+        const { loadChantConfig } = await import("@intentius/chant/config");
+        return (await loadChantConfig(cwd)).config;
+    }
+    catch {
+        return undefined;
+    }
+}
+const isPostgresUrl = (url) => /^postgres(ql)?:\/\//i.test(url);
+/** The dialect an environment's receipts are kept in: its profile's URL, else `sql.dialect`, else whichever server variable is set. */
+export function receiptDialect(config, environment, env) {
+    const profile = environment !== undefined ? config?.sql?.profiles?.[environment] : undefined;
+    if (profile)
+        return isPostgresUrl(profile.url) ? "postgres" : "clickhouse";
+    const dialects = config?.sql?.dialect === undefined ? [] : Array.isArray(config.sql.dialect) ? config.sql.dialect : [config.sql.dialect];
+    if (dialects.length === 1)
+        return dialects[0] === "postgres" ? "postgres" : "clickhouse";
+    if (!env.CLICKHOUSE_URL && env.POSTGRES_URL)
+        return "postgres";
+    return "clickhouse";
+}
+/** The run's environment: the option, `CHANT_ENV`, or a literal `ownership.env`. */
+export function environmentOf(options, config, env) {
+    if (options.environment)
+        return options.environment;
+    if (env.CHANT_ENV)
+        return env.CHANT_ENV;
+    const literal = config?.ownership?.env;
+    return typeof literal === "string" ? literal : undefined;
+}
+async function currentRunId() {
+    try {
+        const { currentOpRun } = await import("@intentius/chant/op");
+        return currentOpRun()?.runId;
+    }
+    catch {
+        return undefined;
+    }
+}
+const receiptsComment = `chant effect receipts [chant ${COMMENT_OWNERSHIP_KEYS.managedBy}=${OWNERSHIP_MANAGED_BY_VALUE} ${RECEIPTS_TRAILER_KEY}=effects]`;
+async function resolve(options) {
+    const env = options.env ?? process.env;
+    const needsConfig = options.config === undefined && (!options.stack || (!options.clickhouse && !options.postgres) || !(options.environment || env.CHANT_ENV));
+    const config = options.config ?? (needsConfig ? await loadConfig(options.cwd ?? process.cwd()) : undefined);
+    const environment = environmentOf(options, config, env);
+    const stack = options.stack ?? (config?.ownership && config.ownership.enabled !== false ? config.ownership.stack : undefined);
+    const identity = { ...(stack ? { stack } : {}), ...(environment ? { env: environment } : {}) };
+    const runId = options.runId ?? (await currentRunId());
+    const dialect = options.postgres ? "postgres" : options.clickhouse ? "clickhouse" : receiptDialect(config, environment, env);
+    if (dialect === "clickhouse") {
+        const { clickhouseReceiptStore } = await import("./clickhouse/rebuild/receipts.js");
+        let endpoint;
+        let topology;
+        let source;
+        if (options.clickhouse) {
+            endpoint = options.clickhouse.endpoint;
+            topology = options.clickhouse.topology;
+            source = endpoint.url;
+        }
+        else {
+            const { bindClickHouse } = await import("./clickhouse/live/bind.js");
+            const target = await bindClickHouse({ ...(environment !== undefined ? { environment } : {}), config: config ?? {}, env });
+            endpoint = target.endpoint;
+            topology = target.topology;
+            source = target.source;
+        }
+        // Created for the environment's topology: ON CLUSTER on a cluster, a Replicated database in the replicated one.
+        const store = clickhouseReceiptStore(endpoint, identity, { ...(runId ? { runId } : {}), ...(topology ? { topology } : {}) });
+        return {
+            identity,
+            dialect,
+            table: `${SQL_RECEIPTS_SCHEMA}.${SQL_RECEIPTS_TABLE}`,
+            source,
+            open: async () => ({ store, close: async () => undefined }),
+        };
+    }
+    const { postgresReceiptStore } = await import("./postgres/migrate/receipts.js");
+    const profile = environment !== undefined ? config?.sql?.profiles?.[environment] : undefined;
+    const schema = options.schema ?? profile?.receiptsSchema ?? SQL_RECEIPTS_SCHEMA;
+    const own = schema === SQL_RECEIPTS_SCHEMA;
+    const table = own ? SQL_RECEIPTS_TABLE : SQL_RECEIPTS_TABLE_BESIDE;
+    const storeOver = (client) => {
+        const store = postgresReceiptStore(client, schema, identity, { ...(runId ? { runId } : {}), table });
+        let ensured = false;
+        return {
+            ...store,
+            async ensure() {
+                if (ensured)
+                    return;
+                // chant's own schema is made here, marked so the catalog leaves it out; a schema of the user's must exist.
+                if (own) {
+                    const [present] = await client.query("SELECT count(*)::int AS n FROM pg_catalog.pg_namespace WHERE nspname = $1", [SQL_RECEIPTS_SCHEMA]);
+                    if (!present?.n) {
+                        await client.query(`CREATE SCHEMA IF NOT EXISTS ${SQL_RECEIPTS_SCHEMA}`);
+                        await client.query(`COMMENT ON SCHEMA ${SQL_RECEIPTS_SCHEMA} IS '${receiptsComment.replace(/'/g, "''")}'`);
+                    }
+                }
+                await store.ensure();
+                ensured = true;
+            },
+        };
+    };
+    if (options.postgres) {
+        const client = options.postgres;
+        const store = storeOver(client);
+        return { identity, dialect, table: `${schema}.${table}`, source: "the caller's connection", open: async () => ({ store, close: async () => undefined }) };
+    }
+    const { resolveBoundTarget } = await import("./postgres/live/bind.js");
+    const { connectPostgres } = await import("./postgres/live/client.js");
+    const target = await resolveBoundTarget({ ...(environment !== undefined ? { environment } : {}), config: config ?? {}, env });
+    return {
+        identity,
+        dialect,
+        table: `${schema}.${table}`,
+        source: target.source,
+        // One connection per read or write: a run's process holds no connection open between steps, and exits when the run ends.
+        open: async () => {
+            const client = await connectPostgres(target.endpoint, { applicationName: "chant receipts" });
+            return { store: storeOver(client), close: () => client.end() };
+        },
+    };
+}
+/**
+ * The receipt store on the environment's database server. Nothing is read or
+ * connected until the first read or write; the environment, the server and
+ * the identity are resolved then, once.
+ */
+export function sqlReceiptStore(options = {}) {
+    let resolved;
+    const resolvedOnce = () => (resolved ?? (resolved = resolve(options)));
+    const using = async (fn) => {
+        const r = await resolvedOnce();
+        const { store, close } = await r.open();
+        try {
+            return await fn(store, r);
+        }
+        finally {
+            await close();
+        }
+    };
+    return {
+        read: (receipt) => using((s) => s.read(receipt)),
+        readAll: (prefix) => using((s) => s.readAll(prefix)),
+        async write(receipt, expectation) {
+            await using(async (s) => {
+                // Made on the first write when it is not there. A caller writing
+                // inside its own transaction calls ensure() before opening it, so a
+                // rolled-back batch does not take the table with it.
+                await s.ensure?.();
+                await s.write(receipt, expectation);
+            });
+        },
+        ensure: () => using(async (s) => s.ensure?.()),
+        async location() {
+            const r = await resolvedOnce();
+            const { receiptAddress } = await import("./core/receipts.js");
+            return { dialect: r.dialect, table: r.table, source: r.source, address: receiptAddress(r.identity, "<effect>") };
+        },
+    };
+}
+/**
+ * The `receiptRead`, `receiptWrite` and `receiptStaleness` activities over
+ * {@link sqlReceiptStore}: what the op activities module exports, and what a
+ * caller running an Op of `effect()` steps with its own activity map binds.
+ */
+export function sqlReceiptActivities(options = {}, activityOptions) {
+    return receiptActivities(sqlReceiptStore(options), activityOptions);
+}

package/dist/serializer.js

@@ -0,0 +1,172 @@
+/**
+ * The sql serializer.
+ *
+ * A build writes two things:
+ *
+ * - The primary output, one JSON document: the dialect, the order objects
+ *   must be created in, and each object filed under its export name (its
+ *   identity in chant) with its type, its parsed definition, the references it
+ *   makes and its DDL. Post-synth checks, planning and the applier read this.
+ * - `clickhouse.sql` (or `postgres.sql`) beside it: every statement, in that
+ *   order, as it will be sent. Written verbatim.
+ *
+ * The order is the dependency order of the references: a view after the
+ * tables it reads, a materialized view after its target, a table after its
+ * database. An object read from a `.sql` file (`./sql-files.ts`) that a
+ * template names in its text counts as referenced too. Ties break by export name, so the output is the same however the
+ * files were discovered. A reference cycle is an error naming the cycle.
+ *
+ * One build holds one dialect: the dialect is the document's, and a project
+ * whose declarations are ClickHouse and Postgres both is refused, naming one
+ * of each. Two databases of different dialects are two projects (two
+ * workspace members, #3047 question 1).
+ *
+ * A Postgres document also carries `postgresMajor`, the major the project
+ * targets (`sql.postgresMajor`, else the newest pinned major). Post-synth
+ * checks and the lock classifier read it; ClickHouse output has no such field.
+ *
+ * A clause chant's parser does not know (#3872) is kept in the statement as
+ * written and named in a build warning ({@link unparsedWarnings}).
+ *
+ * Rule ids: `SQL` for rules that hold in every dialect, `SQLCH` for the
+ * ClickHouse dialect's (#3199), `SQLPG` for Postgres's (#3289).
+ */
+import { isAttrRefLike } from "@intentius/chant/utils";
+import { isClickHouseObject } from "./clickhouse/entities.js";
+import { isPostgresObject } from "./postgres/entities.js";
+import { POSTGRES_LATEST_MAJOR } from "./spec/postgres-pin.js";
+import { applyOrder, lineageJson, referenceName } from "./core/references.js";
+import { sqlFileLineOf, sqlFileOf, sqlFileReferences } from "./sql-files.js";
+import { relative } from "node:path";
+import { getProvenance } from "@intentius/chant/provenance";
+export { applyOrder } from "./core/references.js";
+/**
+ * A warning for each clause chant's parser does not know (#3872): where it
+ * is (the `.sql` file and line, or the template's file and the line in its
+ * statement), which object, and what follows from it. The statement is sent
+ * as written; the server decides.
+ */
+export function unparsedWarnings(objects) {
+    const out = [];
+    for (const [name, entity] of objects) {
+        const unparsed = entity.props?.unparsed;
+        if (!unparsed || unparsed.length === 0)
+            continue;
+        const file = sqlFileOf(entity);
+        const start = sqlFileLineOf(entity);
+        const source = getProvenance(entity)?.sourceFile;
+        for (const u of unparsed) {
+            const where = file !== undefined ? `${file}:${start !== undefined ? start + u.line - 1 : u.line}` : `${source ? relative(process.cwd(), source) : "?"}: ${name}, line ${u.line} of its statement`;
+            const on = u.column !== undefined ? ` on column ${u.column}` : "";
+            out.push(`${where}: ${entity.sqlName ?? name} has a clause chant does not read, ${u.clause}${on}. ` +
+                "It is sent as written and the server checks it; a plan reads the rest of the object, and classes any change to the clause as one to review");
+        }
+    }
+    return out;
+}
+/** The file the statements are written to, beside the primary output. */
+export const CLICKHOUSE_DDL_FILE = "clickhouse.sql";
+/** The Postgres statements' file, beside the primary output. */
+export const POSTGRES_DDL_FILE = "postgres.sql";
+function objectJson(name, obj, names, extra = []) {
+    const props = { ...obj.props };
+    delete props.source;
+    const ddl = props.ddl;
+    delete props.ddl;
+    if (props.reads)
+        props.reads = props.reads.map((r) => referenceName(r, names) ?? null);
+    if (props.to !== undefined && typeof props.to !== "string")
+        props.to = referenceName(props.to, names) ?? null;
+    if (props.lineage) {
+        props.lineage = lineageJson(props.lineage, names);
+    }
+    const dependsOn = [...new Set([...obj.dependsOn.map((r) => referenceName(r, names)).filter((n) => n !== undefined), ...extra])];
+    return JSON.parse(JSON.stringify({ export: name, type: obj.entityType, sqlName: obj.sqlName, ...props, dependsOn, ddl }));
+}
+/** A props value with every entity and column reference in it written as its export name (`users`, `users.id`). */
+function postgresJsonValue(v, names) {
+    if (isPostgresObject(v) || isAttrRefLike(v))
+        return referenceName(v, names) ?? null;
+    if (Array.isArray(v))
+        return v.map((x) => postgresJsonValue(x, names));
+    if (v !== null && typeof v === "object")
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, postgresJsonValue(x, names)]));
+    return v;
+}
+function postgresObjectJson(name, obj, names, extra = []) {
+    const props = { ...obj.props };
+    delete props.source;
+    const ddl = props.ddl;
+    delete props.ddl;
+    const dependsOn = [...new Set([...obj.dependsOn.map((r) => referenceName(r, names)).filter((n) => n !== undefined), ...extra])];
+    return JSON.parse(JSON.stringify({ export: name, type: obj.entityType, sqlName: obj.sqlName, ...postgresJsonValue(props, names), dependsOn, ddl }));
+}
+/** The Postgres major the build targets: `sql.postgresMajor`, else the newest pinned major. */
+function targetMajor(config) {
+    const m = config?.sql?.postgresMajor;
+    return typeof m === "number" ? m : POSTGRES_LATEST_MAJOR;
+}
+function serializePostgres(objects, entities, config) {
+    const names = new Map();
+    for (const [name, entity] of entities)
+        names.set(entity, name);
+    // A template names an object read from a `.sql` file as text: that is an edge too.
+    const extra = sqlFileReferences("postgres", objects);
+    const order = applyOrder(objects, names, extra);
+    const doc = {
+        dialect: "postgres",
+        postgresMajor: targetMajor(config),
+        applyOrder: order,
+        objects: order.map((n) => postgresObjectJson(n, objects.get(n), names, extra.get(n))),
+    };
+    const ddl = order.map((n) => `${objects.get(n).props.ddl};`).join("\n\n");
+    const warnings = unparsedWarnings(objects);
+    return {
+        primary: `${JSON.stringify(doc, null, 2)}\n`,
+        files: { [POSTGRES_DDL_FILE]: `${ddl}\n` },
+        verbatimFiles: [POSTGRES_DDL_FILE],
+        ...(warnings.length > 0 ? { warnings } : {}),
+    };
+}
+export const sqlSerializer = {
+    name: "sql",
+    rulePrefix: "SQL",
+    serialize(entities, _outputs, context) {
+        const objects = new Map();
+        const postgres = new Map();
+        for (const [name, entity] of entities) {
+            if (isClickHouseObject(entity))
+                objects.set(name, entity);
+            else if (isPostgresObject(entity))
+                postgres.set(name, entity);
+        }
+        if (objects.size > 0 && postgres.size > 0) {
+            throw new Error(`sql: one build holds one dialect, and this one declares ClickHouse (${[...objects.keys()][0]}) and Postgres (${[...postgres.keys()][0]}) objects; ` +
+                "declare each database in its own project");
+        }
+        if (postgres.size > 0)
+            return serializePostgres(postgres, entities, context?.config);
+        if (objects.size === 0)
+            return "";
+        const names = new Map();
+        for (const [name, entity] of entities)
+            names.set(entity, name);
+        const extra = sqlFileReferences("clickhouse", objects);
+        const order = applyOrder(objects, names, extra);
+        const doc = {
+            dialect: "clickhouse",
+            applyOrder: order,
+            objects: order.map((n) => objectJson(n, objects.get(n), names, extra.get(n))),
+        };
+        const ddl = order
+            .map((n) => `${objects.get(n).props.ddl};`)
+            .join("\n\n");
+        const warnings = unparsedWarnings(objects);
+        return {
+            primary: `${JSON.stringify(doc, null, 2)}\n`,
+            files: { [CLICKHOUSE_DDL_FILE]: `${ddl}\n` },
+            verbatimFiles: [CLICKHOUSE_DDL_FILE],
+            ...(warnings.length > 0 ? { warnings } : {}),
+        };
+    },
+};

package/dist/skill-defs.js

@@ -0,0 +1,93 @@
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+/** The sql lexicon's AI skills, read from src/skills/. */
+export const sqlSkills = createSkillsLoader(import.meta.url, [
+    {
+        file: "chant-sql.md",
+        name: "chant-sql",
+        description: "Declare ClickHouse databases, tables, views and materialized views as SQL-shaped tagged templates, with references, lineage and the checks that run on them",
+        triggers: [
+            { type: "context", value: "clickhouse" },
+            { type: "context", value: "clickhouse schema" },
+            { type: "context", value: "materialized view" },
+        ],
+        examples: [
+            {
+                title: "A table and a view that reads it",
+                output: 'export const analytics = database`CREATE DATABASE analytics ENGINE = Atomic`;\n' +
+                    "export const events = table`CREATE TABLE ${analytics}.events (user_id UUID, ts DateTime) ENGINE = MergeTree ORDER BY (user_id, ts)`;\n" +
+                    "export const recent = view`CREATE VIEW ${analytics}.recent AS SELECT ${events.columns.user_id} AS user_id FROM ${events}`;",
+            },
+        ],
+    },
+    {
+        file: "chant-sql-plan.md",
+        name: "chant-sql-plan",
+        description: "Plan ClickHouse schema changes with chant sql diff and chant sql plan, and read the three change classes (metadata only, background rewrite, rebuild) with the ALTER restriction behind each",
+        triggers: [
+            { type: "context", value: "clickhouse schema change" },
+            { type: "context", value: "sql plan" },
+            { type: "context", value: "alter table" },
+        ],
+        examples: [
+            {
+                title: "Classify a pull request's schema change offline",
+                output: "chant sql diff base.json head.json",
+            },
+        ],
+    },
+    {
+        file: "chant-sql-rebuild.md",
+        name: "chant-sql-rebuild",
+        description: "Run a ClickHouse table rebuild (a sorting key, primary key, partition key, engine or key column type change) with ClickHouseRebuildOp, a gated Op with backfill receipts, verification, an exchange swap and onFailure cleanup",
+        triggers: [
+            { type: "context", value: "clickhouse rebuild" },
+            { type: "context", value: "change sorting key" },
+            { type: "context", value: "clickhouse migration" },
+        ],
+    },
+    {
+        file: "chant-sql-postgres.md",
+        name: "chant-sql-postgres",
+        description: "Declare Postgres schemas, tables, constraints, indexes, views, sequences, enum, composite, range and domain types, collations, casts, aggregates, event triggers, extensions, functions, procedures, triggers, policies, roles and grants as SQL-shaped tagged templates, with references, lineage and the SQLPG lint rules",
+        triggers: [
+            { type: "context", value: "postgres" },
+            { type: "context", value: "postgres schema" },
+            { type: "context", value: "postgresql" },
+        ],
+        examples: [
+            {
+                title: "A table with a foreign key and an index",
+                output: 'export const app = schema`CREATE SCHEMA app`;\n' +
+                    "export const users = table`CREATE TABLE ${app}.users (id bigint PRIMARY KEY)`;\n" +
+                    "export const orders = table`CREATE TABLE ${app}.orders (id bigint PRIMARY KEY, user_id bigint NOT NULL REFERENCES ${users} (${users.columns.id}))`;\n" +
+                    "export const ordersUser = index`CREATE INDEX orders_user_id_idx ON ${orders} (${orders.columns.user_id})`;",
+            },
+        ],
+    },
+    {
+        file: "chant-sql-postgres-plan.md",
+        name: "chant-sql-postgres-plan",
+        description: "Plan Postgres schema changes with chant sql diff and chant sql plan, and read the change classes (metadata only, validates, needs CONCURRENTLY, ACCESS EXCLUSIVE rewrite, expand and contract) as the lock each takes in production",
+        triggers: [
+            { type: "context", value: "postgres schema change" },
+            { type: "context", value: "postgres lock" },
+            { type: "context", value: "postgres migration" },
+        ],
+        examples: [
+            {
+                title: "Classify a pull request's Postgres schema change offline",
+                output: "chant sql diff base.json head.json",
+            },
+        ],
+    },
+    {
+        file: "chant-sql-postgres-migration.md",
+        name: "chant-sql-postgres-migration",
+        description: "Run a Postgres column rename or type change with PostgresMigrationOp, a gated expand-and-contract Op with a dual-write trigger, a batched backfill with receipts, verification, a switch, replication lag handling and onFailure cleanup",
+        triggers: [
+            { type: "context", value: "postgres column rename" },
+            { type: "context", value: "postgres expand and contract" },
+            { type: "context", value: "postgres backfill" },
+        ],
+    },
+]);

package/dist/spec/catalog.js

@@ -0,0 +1,191 @@
+/**
+ * The ClickHouse catalog: what generation reads from a pinned server's
+ * `system.*` tables, in the shape the committed snapshot stores.
+ *
+ * Every section is sorted by name, and the snapshot is written one entry per
+ * line, so a pin move is a line diff a reviewer can read. Nothing here depends
+ * on the host: the columns that reflect server config (`value`, `changed`) are
+ * never read, every query orders its rows, and `auto(<cores>)` defaults are
+ * written as `auto`.
+ */
+import { clickhouseQuery } from "../clickhouse/http.js";
+/** The section names, in the order the snapshot writes them. */
+export const CATALOG_SECTIONS = [
+    "tableEngines",
+    "databaseEngines",
+    "typeFamilies",
+    "codecs",
+    "skipIndexTypes",
+    "aggregateCombinators",
+    "tableFunctions",
+    "formats",
+    "functions",
+    "keywords",
+    "mergeTreeSettings",
+    "querySettings",
+];
+// ── Normalization ────────────────────────────────────────────────────
+/** `max_threads` and a few others default to `auto(<cores>)`; the core count is the host's, not the pin's. */
+export function normalizeDefault(value) {
+    return String(value ?? "").replace(/auto\(\d+\)/g, "auto");
+}
+/**
+ * The first prose line of a markdown description, at most 200 characters.
+ * Descriptions are multi-line markdown with headings and fenced examples; a
+ * summary is what a hover or a JSDoc line can carry.
+ */
+export function summaryOf(description) {
+    let fenced = false;
+    let line;
+    for (const raw of String(description ?? "").split("\n")) {
+        const l = raw.trim();
+        if (l.startsWith("```")) {
+            fenced = !fenced;
+            continue;
+        }
+        if (fenced || l.length === 0 || l.startsWith("#") || l.startsWith("|"))
+            continue;
+        line = l;
+        break;
+    }
+    if (!line)
+        return "";
+    return line.length > 200 ? `${line.slice(0, 197)}...` : line;
+}
+const optional = (value) => {
+    if (value === null || value === undefined)
+        return undefined;
+    const s = String(value);
+    return s === "" ? undefined : s;
+};
+const flag = (value) => value === 1 || value === true || value === "1";
+// ── Reading a server ─────────────────────────────────────────────────
+/**
+ * Read the catalog from a running server. Every query has an explicit
+ * `ORDER BY`: system tables have no stable row order.
+ */
+export async function readCatalog(endpoint, image) {
+    const q = (sql) => clickhouseQuery(endpoint, sql);
+    const [{ v: version }] = (await q("SELECT version() AS v"));
+    const engines = await q("SELECT name, supports_settings, supports_skipping_indices, supports_projections, supports_sort_order, " +
+        "supports_ttl, supports_replication, supports_deduplication, supports_parallel_insert, syntax, description " +
+        "FROM system.table_engines ORDER BY name");
+    const dbEngines = await q("SELECT name, syntax, description FROM system.database_engines ORDER BY name");
+    const types = await q("SELECT name, case_insensitive, alias_to FROM system.data_type_families ORDER BY name");
+    const codecs = await q("SELECT name, is_compression, is_generic_compression, is_encryption, is_timeseries_codec, is_experimental, description " +
+        "FROM system.codecs ORDER BY name");
+    const indexTypes = await q("SELECT name, syntax, description FROM system.data_skipping_index_types ORDER BY name");
+    const combinators = await q("SELECT name, is_internal FROM system.aggregate_function_combinators ORDER BY name");
+    const tableFunctions = await q("SELECT name FROM system.table_functions ORDER BY name");
+    const formats = await q("SELECT name, is_input, is_output FROM system.formats ORDER BY name");
+    const functions = await q("SELECT name, is_aggregate, case_insensitive, alias_to FROM system.functions WHERE origin = 'System' ORDER BY name");
+    const keywords = await q("SELECT keyword FROM system.keywords ORDER BY keyword");
+    const mtSettings = await q("SELECT name, type, default, min, max, readonly, is_obsolete, tier, description FROM system.merge_tree_settings ORDER BY name");
+    const settings = await q("SELECT name, type, default, min, max, readonly, is_obsolete, tier, alias_for, description FROM system.settings ORDER BY name");
+    const setting = (r) => ({
+        name: String(r.name),
+        type: String(r.type),
+        default: normalizeDefault(r.default),
+        ...(optional(r.min) !== undefined ? { min: optional(r.min) } : {}),
+        ...(optional(r.max) !== undefined ? { max: optional(r.max) } : {}),
+        tier: String(r.tier),
+        obsolete: flag(r.is_obsolete),
+        readonly: flag(r.readonly),
+        ...(optional(r.alias_for) !== undefined ? { aliasFor: optional(r.alias_for) } : {}),
+        summary: summaryOf(r.description),
+    });
+    return {
+        dialect: "clickhouse",
+        version,
+        image,
+        tableEngines: engines.map((e) => ({
+            name: String(e.name),
+            syntax: String(e.syntax ?? ""),
+            summary: summaryOf(e.description),
+            capabilities: {
+                settings: flag(e.supports_settings),
+                skippingIndices: flag(e.supports_skipping_indices),
+                projections: flag(e.supports_projections),
+                sortOrder: flag(e.supports_sort_order),
+                ttl: flag(e.supports_ttl),
+                replication: flag(e.supports_replication),
+                deduplication: flag(e.supports_deduplication),
+                parallelInsert: flag(e.supports_parallel_insert),
+            },
+        })),
+        databaseEngines: dbEngines.map((e) => ({
+            name: String(e.name),
+            syntax: String(e.syntax ?? ""),
+            summary: summaryOf(e.description),
+        })),
+        typeFamilies: types.map((t) => ({
+            name: String(t.name),
+            caseInsensitive: flag(t.case_insensitive),
+            ...(optional(t.alias_to) !== undefined ? { aliasOf: optional(t.alias_to) } : {}),
+        })),
+        codecs: codecs.map((c) => ({
+            name: String(c.name),
+            compression: flag(c.is_compression),
+            generic: flag(c.is_generic_compression),
+            encryption: flag(c.is_encryption),
+            timeseries: flag(c.is_timeseries_codec),
+            experimental: flag(c.is_experimental),
+            summary: summaryOf(c.description),
+        })),
+        skipIndexTypes: indexTypes.map((c) => ({
+            name: String(c.name),
+            syntax: String(c.syntax ?? ""),
+            summary: summaryOf(c.description),
+        })),
+        aggregateCombinators: combinators.map((c) => ({ name: String(c.name), internal: flag(c.is_internal) })),
+        tableFunctions: tableFunctions.map((f) => String(f.name)),
+        formats: formats.map((f) => ({ name: String(f.name), input: flag(f.is_input), output: flag(f.is_output) })),
+        functions: functions.map((f) => ({
+            name: String(f.name),
+            aggregate: flag(f.is_aggregate),
+            caseInsensitive: flag(f.case_insensitive),
+            ...(optional(f.alias_to) !== undefined ? { aliasOf: optional(f.alias_to) } : {}),
+        })),
+        keywords: keywords.map((k) => String(k.keyword)),
+        mergeTreeSettings: mtSettings.map(setting),
+        querySettings: settings.map(setting),
+    };
+}
+// ── The snapshot's text form ─────────────────────────────────────────
+/**
+ * Write the catalog with one array entry per line. A pretty-printed tree would
+ * spread one engine over a dozen lines; this keeps a pin move to one changed
+ * line per changed entry.
+ */
+export function stringifyCatalog(catalog) {
+    const lines = ["{"];
+    lines.push(`  "dialect": ${JSON.stringify(catalog.dialect)},`);
+    lines.push(`  "version": ${JSON.stringify(catalog.version)},`);
+    lines.push(`  "image": ${JSON.stringify(catalog.image)},`);
+    CATALOG_SECTIONS.forEach((section, i) => {
+        const rows = catalog[section];
+        const last = i === CATALOG_SECTIONS.length - 1;
+        if (rows.length === 0) {
+            lines.push(`  ${JSON.stringify(section)}: []${last ? "" : ","}`);
+            return;
+        }
+        lines.push(`  ${JSON.stringify(section)}: [`);
+        rows.forEach((row, j) => lines.push(`    ${JSON.stringify(row)}${j === rows.length - 1 ? "" : ","}`));
+        lines.push(`  ]${last ? "" : ","}`);
+    });
+    lines.push("}");
+    return `${lines.join("\n")}\n`;
+}
+/** Parse and shape-check a snapshot. Throws naming the first section that is missing or not a list. */
+export function parseCatalog(text) {
+    const value = JSON.parse(text);
+    if (value.dialect !== "clickhouse")
+        throw new Error(`not a ClickHouse catalog (dialect ${String(value.dialect)})`);
+    if (typeof value.version !== "string")
+        throw new Error("catalog has no version");
+    for (const section of CATALOG_SECTIONS) {
+        if (!Array.isArray(value[section]))
+            throw new Error(`catalog section ${section} is missing or not a list`);
+    }
+    return value;
+}

package/dist/spec/fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/spec/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,EAA+C,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEhG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,eAAO,MAAM,aAAa,QAAoF,CAAC;AAE/G,uFAAuF;AACvF,eAAO,MAAM,WAAW,wBAAwB,CAAC;AAEjD,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6GAA6G;IAC7G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAUD,0EAA0E;AAC1E,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAU/G;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqChG;AAED,2FAA2F;AAC3F,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAGlG"}
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/spec/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,EAA+C,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEhG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,eAAO,MAAM,aAAa,QAA6E,CAAC;AAExG,uFAAuF;AACvF,eAAO,MAAM,WAAW,wBAAwB,CAAC;AAEjD,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6GAA6G;IAC7G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAUD,0EAA0E;AAC1E,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAU/G;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqChG;AAED,2FAA2F;AAC3F,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAGlG"}