@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/clickhouse/topology.js

@@ -0,0 +1,463 @@
+/**
+ * One ClickHouse statement rendered for the topology it runs on (#3645):
+ * a single node, a cluster (`ON CLUSTER`), a `Replicated` database, or
+ * ClickHouse Cloud.
+ *
+ * A migration source is written once. What differs between topologies is
+ * two things, and this module rewrites only those:
+ *
+ * - `ON CLUSTER`. A cluster's DDL carries it so every host runs the
+ *   statement. A single node has no cluster to name. A `Replicated`
+ *   database replicates its own DDL and refuses `ON CLUSTER` naming any
+ *   other cluster ("ON CLUSTER is not allowed for Replicated database",
+ *   code 80 on 26.8) unless `ignore_on_cluster_for_replicated_database` is
+ *   set (default 0). Cloud's databases are Replicated, so the same holds
+ *   there.
+ * - The table engine. A MergeTree-family table replicates its rows only as
+ *   `Replicated*MergeTree`. On a cluster that engine names its Keeper path
+ *   and replica; inside a `Replicated` database it takes no path arguments,
+ *   since `database_replicated_allow_replicated_engine_arguments` defaults to
+ *   0 (refuse them) and the database supplies its own. A single node has no
+ *   Keeper to replicate through, so it gets the plain family. Cloud converts
+ *   every MergeTree and `Replicated*` engine to its `Shared*` equivalent
+ *   itself ("You don't add a `Shared` or `Replicated` prefix yourself",
+ *   https://clickhouse.com/docs/whats-new/cloud-compatibility), so it gets
+ *   the plain family as well, with no path arguments to clash.
+ *
+ * Every function here is pure: SQL in, SQL out, nothing sent. Statements
+ * this module does not recognize (`INSERT`, `SELECT`, `SYSTEM`) come back
+ * unchanged, so a caller can pass every statement it sends.
+ */
+import { isTrivia, tokenizeText } from "./tokens.js";
+import { parseCreate, unquote } from "./parser.js";
+/**
+ * The Keeper path a cluster's `Replicated*MergeTree` gets: the server's own
+ * `default_replica_path`. `{uuid}` is the same on every host because the
+ * `CREATE` runs `ON CLUSTER`, and it does not change when the table is
+ * renamed or exchanged, so a rebuild's new table never shares the old one's
+ * path.
+ */
+export const DEFAULT_REPLICA_PATH = "/clickhouse/tables/{uuid}/{shard}";
+/** The replica name a cluster's `Replicated*MergeTree` gets: the server's `default_replica_name`. */
+export const DEFAULT_REPLICA_NAME = "{replica}";
+/** The Keeper path a `Replicated` database is created with in the `replicated` topology. */
+export const replicatedDatabasePath = (database) => `/clickhouse/databases/${database}`;
+/**
+ * Read a topology from its string form, as a command-line flag or an
+ * environment variable gives it: `single`, `cluster:<name>`, `replicated`,
+ * `replicated:<cluster>`, `cloud`.
+ */
+export function parseTopology(value) {
+    const at = value.indexOf(":");
+    const kind = (at < 0 ? value : value.slice(0, at)).trim();
+    const arg = at < 0 ? undefined : value.slice(at + 1).trim();
+    switch (kind) {
+        case "single":
+        case "cloud":
+            if (arg !== undefined)
+                throw new Error(`topology ${kind} takes no argument: ${JSON.stringify(value)}`);
+            return { kind };
+        case "cluster":
+            if (!arg)
+                throw new Error(`topology cluster needs the cluster's name: cluster:<name>, got ${JSON.stringify(value)}`);
+            return { kind, cluster: arg };
+        case "replicated":
+            return arg ? { kind, cluster: arg } : { kind };
+        default:
+            throw new Error(`unknown topology ${JSON.stringify(value)}: expected single, cluster:<name>, replicated or cloud`);
+    }
+}
+const FAMILY = /^(Replicated)?(\w*MergeTree)$/;
+const isStringLiteral = (arg) => arg !== undefined && /^'(?:[^'\\]|\\.)*'$/s.test(arg.trim());
+const sqlString = (value) => `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+/**
+ * A MergeTree-family engine split into its family and its own arguments,
+ * with the Keeper path and replica name a `Replicated*` engine names taken
+ * apart. Undefined for any other engine (`Log`, `Distributed`) and for a
+ * `Shared*` one, which only Cloud writes.
+ *
+ * As ClickHouse reads it, a `Replicated*MergeTree` names a path and replica
+ * when its first argument is a string literal; otherwise every argument is
+ * the family's own (`ReplicatedReplacingMergeTree(ver)`).
+ */
+function mergeTreeFamily(engine) {
+    const m = FAMILY.exec(engine.name);
+    if (!m || m[2].startsWith("Shared"))
+        return undefined;
+    const args = (engine.args ?? []).map((a) => a.trim());
+    if (m[1] && isStringLiteral(args[0]) && isStringLiteral(args[1])) {
+        return { family: m[2], replicated: true, replica: [args[0], args[1]], args: args.slice(2) };
+    }
+    return { family: m[2], replicated: m[1] !== undefined, args };
+}
+/**
+ * The engine a table gets on a topology. A MergeTree-family engine becomes
+ * `Replicated*` on a cluster (with the path and replica it declared, or the
+ * topology's) and in a Replicated database (with none); the plain family on
+ * a single node and on Cloud. Any other engine is returned as declared.
+ */
+export function renderEngine(engine, topology) {
+    const f = mergeTreeFamily(engine);
+    if (!f)
+        return engine;
+    const parens = engine.args !== undefined;
+    const withArgs = (name, args) => (args.length > 0 || parens ? { name, args } : { name });
+    switch (topology.kind) {
+        case "single":
+        case "cloud":
+            return withArgs(f.family, f.args);
+        case "replicated":
+            return withArgs(`Replicated${f.family}`, f.args);
+        case "cluster": {
+            const replica = f.replica ?? [sqlString(topology.replicaPath ?? DEFAULT_REPLICA_PATH), sqlString(topology.replicaName ?? DEFAULT_REPLICA_NAME)];
+            return { name: `Replicated${f.family}`, args: [...replica, ...f.args] };
+        }
+    }
+}
+const engineText = (e) => (e.args === undefined ? e.name : `${e.name}(${e.args.join(", ")})`);
+// ── statements ────────────────────────────────────────────────────────
+/** `ON CLUSTER` and the name after it: a backquoted identifier, or a string literal for a macro (`'{cluster}'`). */
+export function onClusterClause(cluster) {
+    return `ON CLUSTER ${/[{}]/.test(cluster) ? sqlString(cluster) : `\`${cluster.replace(/`/g, "``")}\``}`;
+}
+function applyEdits(tokens, edits) {
+    const sorted = [...edits].sort((a, b) => a.from - b.from);
+    let out = "";
+    let at = 0;
+    for (const e of sorted) {
+        out += tokens.slice(at, e.from).map((t) => t.text).join("") + e.text;
+        at = e.to;
+    }
+    return out + tokens.slice(at).map((t) => t.text).join("");
+}
+const word = (t, ...words) => t !== undefined && t.kind === "ident" && words.includes(t.text.toUpperCase());
+const isName = (t) => t !== undefined && (t.kind === "ident" || t.kind === "qident" || t.kind === "number" || t.kind === "ref");
+/** A walker over the significant tokens, which knows each one's index in the full list. */
+class Walk {
+    constructor(tokens) {
+        this.tokens = tokens;
+        this.p = 0;
+        this.sig = tokens.flatMap((t, i) => (isTrivia(t) ? [] : [i]));
+    }
+    peek(n = 0) {
+        const i = this.sig[this.p + n];
+        return i === undefined ? undefined : this.tokens[i];
+    }
+    /** Index in `tokens` of the significant token `n` ahead, or the end. */
+    index(n = 0) {
+        return this.sig[this.p + n] ?? this.tokens.length;
+    }
+    /** Index in `tokens` just past the last significant token consumed. */
+    end() {
+        return this.p === 0 ? 0 : this.sig[this.p - 1] + 1;
+    }
+    accept(...words) {
+        if (!word(this.peek(), ...words))
+            return false;
+        this.p++;
+        return true;
+    }
+    acceptSeq(...words) {
+        if (!words.every((w, i) => word(this.peek(i), w)))
+            return false;
+        this.p += words.length;
+        return true;
+    }
+    /** `name` or `db.name`. False when no name is here. */
+    name() {
+        if (!isName(this.peek()))
+            return false;
+        this.p++;
+        while (this.peek()?.text === "." && isName(this.peek(1)))
+            this.p += 2;
+        return true;
+    }
+    /** The significant token index of the last top-level `SETTINGS`, outside any parentheses, or undefined. */
+    topLevelSettings() {
+        let depth = 0;
+        let found;
+        for (let k = this.p; k < this.sig.length; k++) {
+            const t = this.tokens[this.sig[k]];
+            if (t.text === "(")
+                depth++;
+            else if (t.text === ")")
+                depth--;
+            else if (depth === 0 && word(t, "SETTINGS"))
+                found = k;
+        }
+        return found;
+    }
+    /** Index in `tokens` of the significant token `k` (absolute), or the end of the statement. */
+    at(k) {
+        return this.sig[k] ?? this.tokens.length;
+    }
+    /** Index in `tokens` past the last significant token, ignoring a trailing `;`. */
+    bodyEnd() {
+        let k = this.sig.length - 1;
+        if (k >= 0 && this.tokens[this.sig[k]].text === ";")
+            k--;
+        return k < 0 ? 0 : this.sig[k] + 1;
+    }
+}
+/**
+ * The edit that makes the `ON CLUSTER` at the walker's position what the
+ * topology wants: replaced with the topology's cluster, removed, or (when
+ * there is none and `cluster` is given) inserted at `insertAt`.
+ */
+function onClusterEdit(w, cluster, insertAt) {
+    if (word(w.peek(), "ON") && word(w.peek(1), "CLUSTER")) {
+        // Back to the end of the token before ON, so removing it takes its leading space too.
+        const from = w.end();
+        w.p += 2;
+        if (!w.name() && w.peek()?.kind === "string")
+            w.p++;
+        const to = w.end();
+        return { from, to, text: cluster === undefined ? "" : ` ${onClusterClause(cluster)}` };
+    }
+    return cluster === undefined ? undefined : { from: insertAt, to: insertAt, text: ` ${onClusterClause(cluster)}` };
+}
+/** The cluster a statement on a table or view carries on this topology, if any. */
+const objectCluster = (topology) => (topology.kind === "cluster" ? topology.cluster : undefined);
+/**
+ * The cluster a statement on a database itself carries on this topology, if
+ * any. In the replicated topology only creating and dropping the database
+ * reach every replica this way; an `ALTER` or `RENAME` of a Replicated
+ * database is replicated by the database.
+ */
+const databaseCluster = (topology, createOrDrop = false) => topology.kind === "cluster" ? topology.cluster : topology.kind === "replicated" && createOrDrop ? topology.cluster : undefined;
+const text = (tokens, span) => tokens
+    .slice(span.from, span.to)
+    .map((t) => t.text)
+    .join("")
+    .trim();
+/** The `ON CLUSTER` edit for a parsed `CREATE`: after the name and any `UUID '...'`. */
+function createClusterEdit(tokens, node, cluster) {
+    if (node.onCluster) {
+        let on = node.onCluster.from - 1;
+        // Back over the trivia and the CLUSTER and ON keywords, to the end of what came before.
+        let seen = 0;
+        while (on >= 0 && seen < 2) {
+            if (!isTrivia(tokens[on]))
+                seen++;
+            on--;
+        }
+        while (on >= 0 && isTrivia(tokens[on]))
+            on--;
+        return { from: on + 1, to: node.onCluster.to, text: cluster === undefined ? "" : ` ${onClusterClause(cluster)}` };
+    }
+    if (cluster === undefined)
+        return undefined;
+    const at = afterName(tokens, node);
+    return { from: at, to: at, text: ` ${onClusterClause(cluster)}` };
+}
+/** Index in `tokens` past a `CREATE`'s name and any `UUID '...'` after it: where `ON CLUSTER` goes. */
+function afterName(tokens, node) {
+    const w = new Walk(tokens.slice(node.name.to));
+    if (w.accept("UUID") && w.peek()?.kind === "string") {
+        w.p++;
+        return node.name.to + w.end();
+    }
+    return node.name.to;
+}
+function renderCreate(tokens, node, topology) {
+    const edits = [];
+    if (node.statement === "database") {
+        const cluster = createClusterEdit(tokens, node, databaseCluster(topology, true));
+        if (cluster)
+            edits.push(cluster);
+        const declared = node.engine?.name;
+        if (topology.kind === "replicated") {
+            if (declared !== "Replicated") {
+                const name = unquote(text(tokens, node.name));
+                const clause = `ENGINE = Replicated(${sqlString(replicatedDatabasePath(name))}, '{shard}', '{replica}')`;
+                if (node.engine)
+                    edits.push({ from: node.engine.span.from, to: node.engine.span.to, text: clause });
+                else {
+                    // After ON CLUSTER as declared, or where an inserted one goes; edits at one index apply in the order pushed.
+                    const at = node.onCluster ? node.onCluster.to : afterName(tokens, node);
+                    edits.push({ from: at, to: at, text: ` ${clause}` });
+                }
+            }
+        }
+        else if (declared === "Replicated" && node.engine) {
+            // Only the replicated topology runs a Replicated database; elsewhere the server's default (Atomic, or Cloud's own).
+            let from = node.engine.span.from;
+            while (from > 0 && isTrivia(tokens[from - 1]))
+                from--;
+            edits.push({ from, to: node.engine.span.to, text: "" });
+        }
+        return applyEdits(tokens, edits);
+    }
+    // A function belongs to no database, so in the replicated topology it reaches every replica only through the cluster.
+    const cluster = createClusterEdit(tokens, node, node.statement === "function" ? databaseCluster(topology, true) : objectCluster(topology));
+    if (cluster)
+        edits.push(cluster);
+    if ((node.statement === "table" || node.statement === "view") && node.engine) {
+        const declared = { name: node.engine.name, ...(node.engine.args ? { args: node.engine.args.map((a) => text(tokens, a)) } : {}) };
+        const rendered = renderEngine(declared, topology);
+        if (engineText(rendered) !== engineText(declared)) {
+            // From the engine's name to the end of its argument list; `ENGINE =` stays as written.
+            edits.push({ from: node.engine.nameSpan.from, to: node.engine.span.to, text: engineText(rendered) });
+        }
+    }
+    return applyEdits(tokens, edits);
+}
+/** A `CREATE` the parser does not take (`CREATE TABLE ... AS`, a dictionary): `ON CLUSTER` after the name, the rest as written. */
+function renderOtherCreate(tokens, topology) {
+    const w = new Walk(tokens);
+    w.accept("CREATE");
+    if (w.accept("OR"))
+        w.accept("REPLACE");
+    w.accept("TEMPORARY");
+    // Access control (`./access.ts`) belongs to no database: like a database's own DDL, it reaches every replica through the cluster.
+    if (w.accept("USER", "ROLE", "POLICY", "QUOTA", "PROFILE") || w.acceptSeq("ROW", "POLICY") || w.acceptSeq("SETTINGS", "PROFILE")) {
+        w.acceptSeq("IF", "NOT", "EXISTS") || w.acceptSeq("OR", "REPLACE");
+        if (!w.name())
+            return applyEdits(tokens, []);
+        const edit = onClusterEdit(w, databaseCluster(topology, true), w.end());
+        return applyEdits(tokens, edit ? [edit] : []);
+    }
+    let database = false;
+    if (w.accept("DATABASE"))
+        database = true;
+    else if (w.accept("MATERIALIZED", "LIVE", "WINDOW"))
+        w.accept("VIEW");
+    else if (!w.accept("TABLE", "VIEW", "DICTIONARY"))
+        return applyEdits(tokens, []);
+    w.acceptSeq("IF", "NOT", "EXISTS");
+    if (!w.name())
+        return applyEdits(tokens, []);
+    let at = w.end();
+    if (w.accept("UUID") && w.peek()?.kind === "string") {
+        w.p++;
+        at = w.end();
+    }
+    const edit = onClusterEdit(w, database ? databaseCluster(topology) : objectCluster(topology), at);
+    return applyEdits(tokens, edit ? [edit] : []);
+}
+/**
+ * The `ON CLUSTER` for a statement whose clause follows the object's name:
+ * `ALTER`, `DROP`, `TRUNCATE`, `OPTIMIZE`, `DETACH`, `ATTACH`.
+ */
+function renderAfterName(tokens, w, cluster) {
+    w.acceptSeq("IF", "NOT", "EXISTS") || w.acceptSeq("IF", "EXISTS");
+    if (!w.name())
+        return applyEdits(tokens, []);
+    const edit = onClusterEdit(w, cluster, w.end());
+    return applyEdits(tokens, edit ? [edit] : []);
+}
+/** `RENAME ... TO ...` and `EXCHANGE ... AND ...`: `ON CLUSTER` at the end, before any `SETTINGS`. */
+function renderAtEnd(tokens, w, cluster) {
+    // An `ON CLUSTER` already written, after the renames.
+    for (let n = 0; w.peek(n) !== undefined; n++) {
+        if (word(w.peek(n), "ON") && word(w.peek(n + 1), "CLUSTER")) {
+            w.p += n;
+            return applyEdits(tokens, [onClusterEdit(w, cluster, 0)]);
+        }
+    }
+    if (cluster === undefined)
+        return applyEdits(tokens, []);
+    const settings = w.topLevelSettings();
+    let at;
+    if (settings !== undefined) {
+        at = w.at(settings);
+        while (at > 0 && isTrivia(tokens[at - 1]))
+            at--;
+    }
+    else
+        at = w.bodyEnd();
+    return applyEdits(tokens, [{ from: at, to: at, text: ` ${onClusterClause(cluster)}` }]);
+}
+/**
+ * One statement as it runs on `topology`: `ON CLUSTER` added, replaced or
+ * removed, and in a `CREATE`, the engine the topology needs. Comments,
+ * spacing and everything else in the statement are kept as written.
+ * A statement that is not DDL on a database, table or view is returned
+ * unchanged, as is `KILL QUERY`/`KILL MUTATION` everywhere but a cluster,
+ * where it gains `ON CLUSTER` (inside a Replicated database
+ * `KILL QUERY ON CLUSTER '<db>'` names the database's own cluster and is kept).
+ */
+export function renderStatement(sql, topology) {
+    const tokens = tokenizeText(sql, 0);
+    const w = new Walk(tokens);
+    const head = w.peek();
+    if (word(head, "CREATE")) {
+        let node;
+        try {
+            node = parseCreate(tokens);
+        }
+        catch {
+            node = undefined;
+        }
+        return node ? renderCreate(tokens, node, topology) : renderOtherCreate(tokens, topology);
+    }
+    if (word(head, "ALTER", "DROP", "DETACH", "ATTACH", "TRUNCATE", "OPTIMIZE", "UNDROP")) {
+        w.p++;
+        if (word(head, "DROP", "DETACH", "ATTACH"))
+            w.accept("TEMPORARY");
+        if (w.accept("DATABASE"))
+            return renderAfterName(tokens, w, databaseCluster(topology, word(head, "DROP")));
+        // A function and access control belong to no database: like the database's own DDL, they reach every replica through the cluster.
+        if (w.accept("FUNCTION", "USER", "ROLE", "POLICY", "QUOTA", "PROFILE") || w.acceptSeq("ROW", "POLICY") || w.acceptSeq("SETTINGS", "PROFILE")) {
+            return renderAfterName(tokens, w, databaseCluster(topology, true));
+        }
+        // `TRUNCATE t` may leave out TABLE.
+        if (w.accept("TABLE", "VIEW", "DICTIONARY") || word(head, "TRUNCATE"))
+            return renderAfterName(tokens, w, objectCluster(topology));
+        return sql;
+    }
+    if (word(head, "GRANT", "REVOKE")) {
+        w.p++;
+        const edit = onClusterEdit(w, databaseCluster(topology, true), w.end());
+        return applyEdits(tokens, edit ? [edit] : []);
+    }
+    if (word(head, "RENAME")) {
+        w.p++;
+        if (w.accept("DATABASE"))
+            return renderAtEnd(tokens, w, databaseCluster(topology));
+        if (w.accept("TABLE", "DICTIONARY"))
+            return renderAtEnd(tokens, w, objectCluster(topology));
+        return sql;
+    }
+    if (word(head, "EXCHANGE")) {
+        w.p++;
+        if (w.accept("TABLES", "DICTIONARIES"))
+            return renderAtEnd(tokens, w, objectCluster(topology));
+        return sql;
+    }
+    if (word(head, "KILL") && topology.kind === "cluster") {
+        w.p++;
+        if (!w.accept("QUERY", "MUTATION"))
+            return sql;
+        const edit = onClusterEdit(w, topology.cluster, w.end());
+        return applyEdits(tokens, edit ? [edit] : []);
+    }
+    return sql;
+}
+/** Each step's statement rendered for `topology`; every other field of a step is kept. */
+export function renderSteps(steps, topology) {
+    return steps.map((s) => ({ ...s, sql: renderStatement(s.sql, topology) }));
+}
+/**
+ * A statement for a topology that may not be configured: with none, the
+ * statement as the source wrote it. The applier, the plan and the rebuild
+ * migration render only when an environment names its topology
+ * (`sql.profiles.<env>.topology`, `CLICKHOUSE_TOPOLOGY`), so a project that
+ * names none sends what it declared, as before.
+ */
+export const renderFor = (sql, topology) => (topology ? renderStatement(sql, topology) : sql);
+/** A topology from its string form or its object form (`sql.profiles.<env>.topology`). */
+export function toTopology(value) {
+    return typeof value === "string" ? parseTopology(value) : value;
+}
+/** The topology's string form, as `parseTopology` reads it. Replica path options are not part of it. */
+export function topologyLabel(topology) {
+    switch (topology.kind) {
+        case "cluster":
+            return `cluster:${topology.cluster}`;
+        case "replicated":
+            return topology.cluster ? `replicated:${topology.cluster}` : "replicated";
+        default:
+            return topology.kind;
+    }
+}

package/dist/clickhouse/type-syntax.js

@@ -0,0 +1,73 @@
+/**
+ * A column type, read into its family and parameters: `Nullable(String)` is
+ * the family `Nullable` with the one parameter `String`;
+ * `DateTime64(3, 'UTC')` is `DateTime64` with `3` and `'UTC'`.
+ *
+ * The reading is lexical, over the same tokenizer the parser uses, so a
+ * string literal holding a parenthesis (`Enum8('a(' = 1)`) or a comma does not
+ * split a parameter. What a parameter means (a type, a number, a name) is the
+ * caller's question, answered from `TYPE_PARAMETERS`.
+ */
+import { isTrivia, tokenizeText } from "./tokens.js";
+const textOf = (tokens) => tokens.map((t) => t.text).join("").trim();
+/** The significant tokens of a type, or undefined when it does not tokenize. */
+export function typeTokens(text) {
+    try {
+        return tokenizeText(text, 0);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read a type into its leading words and its parameters. Undefined when the
+ * text is not a type this can read: no leading name, or unbalanced parentheses.
+ * Anything after the closing parenthesis (`COLLATE utf8`) is ignored.
+ */
+export function readType(tokens) {
+    const sig = tokens.filter((t) => !isTrivia(t));
+    const words = [];
+    let i = 0;
+    // `String COLLATE utf8`: COLLATE ends the type's words.
+    while (i < sig.length && (sig[i].kind === "ident" || sig[i].kind === "qident") && sig[i].text.toUpperCase() !== "COLLATE")
+        words.push(sig[i++]);
+    if (words.length === 0)
+        return undefined;
+    if (i >= sig.length || !(sig[i].kind === "punct" && sig[i].text === "("))
+        return { words };
+    // Parameters: the tokens up to the matching parenthesis, split at top-level commas.
+    const start = tokens.indexOf(sig[i]);
+    const params = [];
+    let depth = 0;
+    let current = [];
+    for (let j = start; j < tokens.length; j++) {
+        const t = tokens[j];
+        if (t.kind === "punct" && t.text === "(") {
+            if (depth++ === 0)
+                continue;
+        }
+        else if (t.kind === "punct" && t.text === ")") {
+            if (--depth === 0) {
+                if (params.length > 0 || current.some((x) => !isTrivia(x)))
+                    params.push({ text: textOf(current), tokens: current });
+                return { words, params };
+            }
+        }
+        else if (depth === 1 && t.kind === "punct" && t.text === ",") {
+            params.push({ text: textOf(current), tokens: current });
+            current = [];
+            continue;
+        }
+        current.push(t);
+    }
+    return undefined;
+}
+/** A parameter that is a numeric literal, possibly negative: its value. */
+export function numericParam(param) {
+    const sig = param.tokens.filter((t) => !isTrivia(t));
+    const negative = sig.length === 2 && sig[0].kind === "op" && sig[0].text === "-";
+    const n = negative ? sig[1] : sig.length === 1 ? sig[0] : undefined;
+    if (!n || n.kind !== "number" || !/^\d+(\.\d+)?([eE][+-]?\d+)?$/.test(n.text))
+        return undefined;
+    return negative ? -Number(n.text) : Number(n.text);
+}

package/dist/clickhouse.js

@@ -0,0 +1,25 @@
+/**
+ * `@intentius/chant-lexicon-sql/clickhouse`: the ClickHouse dialect.
+ *
+ * Everything here is spec-true to ClickHouse at the pinned server release
+ * (`CLICKHOUSE_VERSION`), not a database-agnostic model: the engine names,
+ * column type families, codecs, skip index types and settings are the pinned
+ * server's own, read from its `system.*` tables, and the argument grammar the
+ * catalog does not carry comes from the overlays beside them.
+ */
+export { database, table, view, dictionary, func, user, role, policy, grant, quota, settingsProfile, literal, SqlLiteral, SqlTemplateError, ClickHouseObject, CLICKHOUSE_ENTITY_TYPES, isClickHouseObject, isColumnRef, quoteIdentifier, } from "./clickhouse/entities.js";
+export * from "./generated/clickhouse.js";
+export * from "./composites/clickhouse.js";
+export { ENGINE_ARGUMENTS } from "./clickhouse/overlays/engines.js";
+export { SKIP_INDEX_PARAMETERS } from "./clickhouse/overlays/skip-indexes.js";
+export { CODEC_OVERLAY } from "./clickhouse/overlays/codecs.js";
+export { TYPE_PARAMETERS, WRAPPER_TYPES } from "./clickhouse/overlays/types.js";
+export { TTL_ACTIONS, COLUMN_TTL_ACTIONS, TTL_RESULT_TYPES, TTL_SETTINGS, } from "./clickhouse/overlays/ttl.js";
+export { PROJECTION_FORMS, PROJECTION_SETTINGS, PROJECTION_FORBIDDEN_CLAUSES, } from "./clickhouse/overlays/projections.js";
+export { CLICKHOUSE_IMAGE_DIGEST, CLICKHOUSE_IMAGE_REPOSITORY, clickhouseImage } from "./spec/pin.js";
+export { ClickHouseRebuildOp, } from "./clickhouse/rebuild/op.js";
+export { RECEIPTS_DATABASE, RECEIPTS_TABLE } from "./clickhouse/rebuild/receipts.js";
+export { DEFAULT_REPLICA_NAME, DEFAULT_REPLICA_PATH, onClusterClause, parseTopology, renderEngine, renderFor, renderStatement, renderSteps, replicatedDatabasePath, topologyLabel, toTopology, } from "./clickhouse/topology.js";
+// The build's ClickHouse objects as typed values, for a project's own
+// `lint.policies` (#3870); also at `@intentius/chant-lexicon-sql/read`.
+export { readClickHouse, } from "./read/clickhouse.js";

package/dist/codegen/classifier-page.js

@@ -0,0 +1,93 @@
+/**
+ * `docs/pages/change-classifier.mdx`, written from the classifier's own rule
+ * table by `npm run docs`, so the page cannot disagree with the rules.
+ */
+import { CLASSIFIER_RULES } from "../clickhouse/plan/rules.js";
+const LABEL = {
+    create: "create",
+    drop: "drop",
+    metadata: "metadata only",
+    rewrite: "background rewrite",
+    rebuild: "rebuild",
+};
+const cell = (s) => s.replace(/\|/g, "\\|");
+export function renderClassifierPage() {
+    const rows = Object.values(CLASSIFIER_RULES).map((r) => `| ${r.id} | ${LABEL[r.class]} | ${cell(r.title)} | ${cell(r.restriction)} [ClickHouse docs](${r.cite}) |`);
+    return `---
+title: "Planning ClickHouse Changes"
+label: "Planning and the Change Classifier"
+description: "How a ClickHouse schema change is classified as metadata only, a background rewrite or a rebuild, each with the ALTER restriction behind it"
+diataxis: reference
+group: "ClickHouse"
+order: 1
+---
+
+{/* Written by src/codegen/classifier-page.ts from src/clickhouse/plan/rules.ts. Edit the rules, then run npm run docs. */}
+
+Every change between two ClickHouse schemas is classified before anything runs:
+
+| Class | Means |
+|---|---|
+| metadata only | the server records the change and touches no existing data |
+| background rewrite | a mutation rewrites existing parts in the background, with no rollback |
+| rebuild | ClickHouse cannot make the change to the existing table, and the data has to be copied into a new one; a plan refuses to make it in place |
+
+Two commands report the classification, and \`chant lifecycle plan\` reports it as each update's disruption (metadata only is \`in-place\`, a rewrite \`rolling\`, a rebuild \`replace\`):
+
+\`\`\`bash
+chant sql diff base.json head.json     # two chant build outputs, offline
+chant sql plan prod schema.json        # a build output against the prod server
+\`\`\`
+
+Both exit 2 when a change needs a rebuild. \`chant sql diff\` compares a pull request's base and head builds with no server. \`chant sql plan\` reads the server \`sql.profiles.<env>\` binds, and asks that server's formatter about any expression the normalization rules leave different, so the server's own rewriting (\`INTERVAL 1 DAY\` as \`toIntervalDay(1)\`, \`a+b*2\` as \`a + (b * 2)\`) is not reported as a change.
+
+\`chant sql plan\` also exits 2 when a declared database holds an object whose definition it cannot read. It names each one under \`Refused\` (\`unreadable\` in \`--json\`) instead of leaving it out. Dictionaries are read and planned like the other objects: any change but a comment replaces one (SQLCH245).
+
+A clause chant's parser does not know ([Plain .sql Files](../sql-files/#clauses-chant-does-not-read)) is compared as text, and the rest of its object is planned as usual. A change to one is SQLCH290, refused for review with no rebuild Op suggested, since chant cannot tell what the change takes. A clause only the server prints is a hint, not a change: a newer server printing a clause with its default looks the same as a clause removed from the declaration.
+
+## After the plan
+
+The plan only reports. [\`clickhouseApply\`](../applying/) makes the metadata-only and background-rewrite changes, and refuses a rebuild the same way the plan does, sending nothing for that object. A rebuild runs as \`ClickHouseRebuildOp\`, a gated migration Op that creates the new table, backfills it, verifies it and swaps it in: see [Rebuilding a Table](../rebuild/). Both commands print the Op declaration to start from for each refused table.
+
+\`chant migrate\` plays no part in any of this. It translates a file from one lexicon's format into another's, such as a GitHub Actions workflow into GitLab CI, and does not run schema migrations.
+
+## Statements for a migration file
+
+\`chant sql diff base.json head.json --statements\` prints the statements that take the base schema to the head one, offline: each one the applier would send for the same change, after a comment naming its object, rule and class. \`--json\` prints them as one document, which \`diffStatements(before, after)\` from \`@intentius/chant-lexicon-sql\` also returns:
+
+\`\`\`sql
+-- events (analytics.events): SQLCH201 metadata
+ALTER TABLE \`analytics\`.\`events\` ADD COLUMN region String DEFAULT 'eu' AFTER \`user_id\`;
+
+-- events (analytics.events): SQLCH210 rewrite, waits for its mutation
+ALTER TABLE \`analytics\`.\`events\` MODIFY COLUMN \`kind\` LowCardinality(String);
+
+-- sessions (analytics.sessions): SQLCH220 made by ClickHouseRebuildOp, not a statement:
+--   export const { op } = ClickHouseRebuildOp({ name: "rebuild-analytics-sessions", env: "<env>", table: "analytics.sessions", dualWrite: { mode: "materialized-view", cutoverColumn: "ts" } });
+\`\`\`
+
+A rebuild is never DDL: it is a step naming \`ClickHouseRebuildOp\`, or for a view or a database, which the Op does not rebuild, a manual step. A column or object drop is a statement marked destructive. Each \`CREATE\` carries the project's ownership marker, as the applier stamps it. The command exits 2 when a step is not a statement. A migration runner's history table (\`schema_migrations\`, \`goose_db_version\`; see [Importing a Live Server](../importing/)) is never dropped: the report names it in a hint. Two things the applier asks the server are left out: whether a difference is formatting only, and whether a database is empty before it is dropped.
+
+\`--topology\` renders the statements for where they will run: \`single\` (the default), \`cluster:<name>\`, \`replicated\` or \`cloud\`. On a cluster every statement carries \`ON CLUSTER\` and a MergeTree-family table becomes \`Replicated*MergeTree\` with its Keeper path; in a \`Replicated\` database the tables are \`Replicated*MergeTree\` with no path and no \`ON CLUSTER\`. \`diffStatements(before, after, { topology })\` takes the same choice; see [Applying to a Server](../applying/#topology).
+
+## Identity and renames
+
+An object is identified by its export name between two builds, so a changed name in the SQL under the same export is a rename. Against a server, which has no export names, an object is identified by \`database.name\`; a declaration renamed since the server last saw it says so with \`-- previously: <old name>\` before its CREATE.
+
+A column is identified by its name. A renamed column says so on its own line:
+
+\`\`\`sql
+CREATE TABLE events (
+  event_kind LowCardinality(String), -- previously: kind
+  ...
+\`\`\`
+
+Without the hint the change is a drop and an add, and the report points out a drop and an add with the same type in the same place.
+
+## The rules
+
+| Id | Class | Change | Restriction |
+|---|---|---|---|
+${rows.join("\n")}
+`;
+}