@intentius/chant-lexicon-sql 0.124.12 → 0.124.13

package/src/clickhouse/expressions.ts

@@ -0,0 +1,108 @@
+/**
+ * Small scanners over ClickHouse expression text as the parser keeps it
+ * (sort keys, engine arguments, column types), shared by the post-synth
+ * checks (`../lint/post-synth/clickhouse-helpers.ts`) and the public read API
+ * (`../read/clickhouse.ts`). They answer narrow questions ("is this a bare
+ * column name", "what family is this type"), not what an expression
+ * evaluates to.
+ */
+
+import { TABLE_ENGINES, TYPE_FAMILIES } from "../generated/clickhouse";
+import type { EngineDef } from "./entities";
+
+/** The engine's catalog entry, when the pinned server has the engine. */
+export function engineSpec(engine: EngineDef | undefined) {
+  return engine ? (TABLE_ENGINES as Record<string, (typeof TABLE_ENGINES)[keyof typeof TABLE_ENGINES]>)[engine.name] : undefined;
+}
+
+/** A MergeTree family engine, replicated or not. */
+export function isMergeTree(engine: EngineDef | undefined): boolean {
+  return engineSpec(engine)?.mergeTree === true;
+}
+
+/** The engine without its `Replicated` prefix: `ReplicatedReplacingMergeTree` is `ReplacingMergeTree`. */
+export function baseEngineName(engine: EngineDef): string {
+  const spec = engineSpec(engine) as { replicates?: string } | undefined;
+  return spec?.replicates ?? engine.name;
+}
+
+
+
+/** Split on commas that are not inside parentheses, brackets or quotes. */
+export function splitTop(text: string, separator = ","): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let quote: string | undefined;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (quote) {
+      if (c === "\\") i++;
+      else if (c === quote) quote = undefined;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === "`") quote = c;
+    else if (c === "(" || c === "[") depth++;
+    else if (c === ")" || c === "]") depth--;
+    else if (c === separator && depth === 0) {
+      parts.push(text.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  const last = text.slice(start).trim();
+  if (last !== "" || parts.length > 0) parts.push(last);
+  return parts.filter((p) => p !== "");
+}
+
+/** `(a, b)` is the list `a`, `b`; `a, b` is the same; `tuple()` and `()` are empty. */
+export function keyElements(expr: string): string[] {
+  let text = expr.trim();
+  if (/^tuple\s*\(\s*\)$/i.test(text) || text === "()") return [];
+  if (text.startsWith("(") && closingParen(text, 0) === text.length - 1) text = text.slice(1, -1);
+  return splitTop(text).map((e) => e.replace(/\s+(ASC|DESC)$/i, "").replace(/\s+/g, " ").trim());
+}
+
+function closingParen(text: string, open: number): number {
+  let depth = 0;
+  let quote: string | undefined;
+  for (let i = open; i < text.length; i++) {
+    const c = text[i]!;
+    if (quote) {
+      if (c === "\\") i++;
+      else if (c === quote) quote = undefined;
+    } else if (c === "'" || c === '"' || c === "`") quote = c;
+    else if (c === "(") depth++;
+    else if (c === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/** The column a bare name refers to: `a` or `` `a b` ``, else undefined. */
+export function bareName(element: string): string | undefined {
+  const text = element.trim();
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(text)) return text;
+  const quoted = /^`((?:[^`]|``)*)`$/.exec(text) ?? /^"((?:[^"]|"")*)"$/.exec(text);
+  return quoted ? quoted[1]!.replace(/``|""/g, (m) => m[0]!) : undefined;
+}
+
+
+
+/** A type with its `Nullable(...)` and `LowCardinality(...)` wrappers removed. */
+export function unwrapType(type: string | undefined): string {
+  let t = (type ?? "").trim();
+  for (;;) {
+    const m = /^(Nullable|LowCardinality)\s*\(([\s\S]*)\)$/i.exec(t);
+    if (!m) return t;
+    t = m[2]!.trim();
+  }
+}
+
+/** The canonical family of a column's type (`BIGINT UNSIGNED` is `UInt64`), or its leading word when unknown. */
+export function typeFamily(type: string | undefined): string {
+  const head = /^[A-Za-z_][A-Za-z0-9_ ]*?(?=\s*\(|$)/.exec(unwrapType(type))?.[0]?.trim() ?? "";
+  const table = TYPE_FAMILIES as Record<string, { canonical: string } | undefined>;
+  return (table[head] ?? table[head.toUpperCase()])?.canonical ?? head;
+}
+
+export const isNullableType = (type: string | undefined): boolean => /^Nullable\s*\(/i.test((type ?? "").trim());
+

package/src/clickhouse/parser.ts

@@ -20,9 +20,9 @@
  */
 
 import type { Token } from "./tokens";
-import { kw, SqlCursor, unquoteWith, type Span } from "../core/cursor";
+import { kw, SqlCursor, unquoteWith, type Span, type UnknownClause } from "../core/cursor";
 
-export type { Span } from "../core/cursor";
+export type { Span, UnknownClause } from "../core/cursor";
 
 export interface ColumnNode {
   /** The name as written, unquoted. Empty when the name is an interpolation. */
@@ -73,6 +73,8 @@ export interface StorageNode {
 
 export interface DatabaseNode {
   statement: "database";
+  /** Clauses the parser does not know (#3872), kept in the DDL as written; absent when there are none. */
+  unknown?: UnknownClause[];
   ifNotExists: boolean;
   name: Span;
   onCluster?: Span;
@@ -83,6 +85,8 @@ export interface DatabaseNode {
 
 export interface TableNode extends StorageNode {
   statement: "table";
+  /** Clauses the parser does not know (#3872), kept in the DDL as written; absent when there are none. */
+  unknown?: UnknownClause[];
   orReplace: boolean;
   ifNotExists: boolean;
   name: Span;
@@ -96,6 +100,8 @@ export interface TableNode extends StorageNode {
 
 export interface ViewNode extends StorageNode {
   statement: "view";
+  /** Clauses the parser does not know (#3872), kept in the DDL as written; absent when there are none. */
+  unknown?: UnknownClause[];
   materialized: boolean;
   orReplace: boolean;
   ifNotExists: boolean;
@@ -128,6 +134,8 @@ export interface DictionaryAttributeNode {
 
 export interface DictionaryNode {
   statement: "dictionary";
+  /** Clauses the parser does not know (#3872), kept in the DDL as written; absent when there are none. */
+  unknown?: UnknownClause[];
   orReplace: boolean;
   ifNotExists: boolean;
   name: Span;
@@ -151,6 +159,8 @@ export interface DictionaryNode {
 /** A SQL user-defined function: `CREATE FUNCTION name AS (x, y) -> expr`. It lives outside any database. */
 export interface FunctionNode {
   statement: "function";
+  /** Clauses the parser does not know (#3872), kept in the DDL as written; absent when there are none. */
+  unknown?: UnknownClause[];
   orReplace: boolean;
   ifNotExists: boolean;
   name: Span;
@@ -177,18 +187,75 @@ export const unquote = (text: string): string => unquoteWith(text, '`"');
 
 const countOf = (text: string, c: string): number => text.split(c).length - 1;
 
+/**
+ * Words an expression in a DDL clause holds between two operands, or right
+ * after one: operators, `CASE`, `INTERVAL` and its units, a TTL's actions.
+ * Any other key word right after an operand starts a new clause (#3872).
+ */
+const EXPRESSION_WORDS = new Set(
+  (
+    "AND OR NOT IN IS NULL LIKE ILIKE BETWEEN ASC DESC NULLS FIRST LAST COLLATE CASE WHEN THEN ELSE END AS INTERVAL GLOBAL ANY ALL " +
+    "DISTINCT FROM TO IF EXISTS DISK VOLUME DELETE RECOMPRESS CODEC WHERE GROUP BY SET WITH FILL STEP TRUE FALSE " +
+    "NANOSECOND MICROSECOND MILLISECOND SECOND MINUTE HOUR DAY WEEK MONTH QUARTER YEAR"
+  ).split(" "),
+);
+
 const STORAGE_KEYWORDS = ["ENGINE", "ORDER", "PRIMARY", "PARTITION", "SAMPLE", "TTL", "SETTINGS", "COMMENT"];
 
+/** A column's own clause words: an unknown one stops at the next of these (#3872). */
+const COLUMN_WORDS = ["DEFAULT", "MATERIALIZED", "ALIAS", "EPHEMERAL", "NULL", "NOT", "COMMENT", "CODEC", "TTL", "STATISTICS", "SETTINGS", "PRIMARY"];
+
 class Parser extends SqlCursor {
-  /** `ORDER`, `PARTITION`, `SAMPLE` and `GROUP` stop only before `BY`, `PRIMARY` only before `KEY`. */
+  /** Where the clause-aware expression being read started (#3872); undefined outside one. */
+  private clauseFrom: number | undefined;
+
+  /**
+   * `ORDER`, `PARTITION`, `SAMPLE` and `GROUP` stop only before `BY`, `PRIMARY`
+   * only before `KEY`. In a clause-aware expression, a clause the parser does
+   * not know stops it too.
+   */
   protected override stopsAt(stop: readonly string[]): boolean {
-    if (!super.stopsAt(stop)) return false;
+    if (!super.stopsAt(stop)) return this.startsUnknownClause();
     const word = this.peek()!.text.toUpperCase();
     const two = ["ORDER", "PARTITION", "SAMPLE", "GROUP"].includes(word) ? kw(this.peek(1), "BY") : true;
     const key = word === "PRIMARY" ? kw(this.peek(1), "KEY") : true;
     return two && key;
   }
 
+  /**
+   * Whether a clause the parser does not know starts here, inside a
+   * clause-aware expression (#3872): a bare key word right after a complete
+   * operand (a name, a literal, a closing parenthesis), which no expression
+   * puts side by side unless the word is one of an expression's own.
+   */
+  private startsUnknownClause(): boolean {
+    if (this.clauseFrom === undefined || this.p <= this.clauseFrom) return false;
+    const t = this.peek();
+    const prev = this.peek(-1);
+    if (t?.kind !== "ident" || !/^[A-Za-z_]{3,}$/.test(t.text) || EXPRESSION_WORDS.has(t.text.toUpperCase())) return false;
+    if (prev === undefined) return false;
+    // A query read into the expression (`ORDER BY id AS SELECT ...`, which the server takes as CREATE TABLE ... AS) is the query's, as it always was.
+    for (let n = this.clauseFrom; n < this.p; n++) if (kw(this.tokens[this.sig[n]!], "SELECT")) return false;
+    return (
+      prev.kind === "number" ||
+      prev.kind === "string" ||
+      prev.kind === "qident" ||
+      (prev.kind === "punct" && prev.text === ")") ||
+      (prev.kind === "ident" && !EXPRESSION_WORDS.has(prev.text.toUpperCase()))
+    );
+  }
+
+  /** An expression a clause the parser does not know can follow (#3872): it ends where that clause starts. */
+  private clauseExpr(stop: readonly string[] = [], stopAtComma = true): Span {
+    const saved = this.clauseFrom;
+    this.clauseFrom = this.p;
+    try {
+      return this.expr(stop, stopAtComma);
+    } finally {
+      this.clauseFrom = saved;
+    }
+  }
+
   /** Array and map literals: `[` and `]` arrive inside operator runs. */
   protected override depthChange(t: Token): number {
     if (t.kind === "op") return countOf(t.text, "[") + countOf(t.text, "{") - countOf(t.text, "]") - countOf(t.text, "}");
@@ -255,20 +322,20 @@ class Parser extends SqlCursor {
         col.nullable = false;
       } else if (kw(this.peek(), "DEFAULT", "MATERIALIZED", "ALIAS")) {
         const kind = this.next().text.toUpperCase() as "DEFAULT" | "MATERIALIZED" | "ALIAS";
-        col.default = { kind, expr: this.expr(STOP) };
+        col.default = { kind, expr: this.clauseExpr(STOP) };
       } else if (this.accept("EPHEMERAL")) {
         const t = this.peek();
         const hasExpr = t && !(t.kind === "punct" && (t.text === "," || t.text === ")")) && !kw(t, ...STOP);
-        col.default = { kind: "EPHEMERAL", expr: hasExpr ? this.expr(STOP) : undefined };
-      } else if (this.accept("COMMENT")) col.comment = this.expr(STOP);
+        col.default = { kind: "EPHEMERAL", expr: hasExpr ? this.clauseExpr(STOP) : undefined };
+      } else if (this.accept("COMMENT")) col.comment = this.clauseExpr(STOP);
       else if (this.accept("CODEC")) col.codec = this.parenthesized();
       else if (this.accept("STATISTICS")) col.statistics = this.parenthesized();
-      else if (this.accept("TTL")) col.ttl = this.expr(STOP);
+      else if (this.accept("TTL")) col.ttl = this.clauseExpr(STOP);
       else if (this.accept("SETTINGS")) col.settings = this.parenthesized();
       else if (kw(this.peek(), "PRIMARY") && kw(this.peek(1), "KEY")) {
         this.p += 2;
         col.primaryKey = true;
-      } else break;
+      } else if (!this.unknownClause(COLUMN_WORDS, { inList: true, column: text || undefined })) break;
     }
     return col;
   }
@@ -360,7 +427,7 @@ class Parser extends SqlCursor {
     for (;;) {
       const key = this.name("a setting name").text;
       this.expectPunct("=");
-      out.push({ key, value: this.expr(stop) });
+      out.push({ key, value: this.clauseExpr(stop) });
       if (!this.acceptPunct(",")) return out;
     }
   }
@@ -372,27 +439,33 @@ class Parser extends SqlCursor {
       if (this.accept("ENGINE")) into.engine = this.engine();
       else if (kw(this.peek(), "ORDER") && kw(this.peek(1), "BY")) {
         this.p += 2;
-        into.orderBy = this.expr(STOP, false);
+        into.orderBy = this.clauseExpr(STOP, false);
       } else if (kw(this.peek(), "PRIMARY") && kw(this.peek(1), "KEY")) {
         this.p += 2;
-        into.primaryKey = this.expr(STOP, false);
+        into.primaryKey = this.clauseExpr(STOP, false);
       } else if (kw(this.peek(), "PARTITION") && kw(this.peek(1), "BY")) {
         this.p += 2;
-        into.partitionBy = this.expr(STOP, false);
+        into.partitionBy = this.clauseExpr(STOP, false);
       } else if (kw(this.peek(), "SAMPLE") && kw(this.peek(1), "BY")) {
         this.p += 2;
-        into.sampleBy = this.expr(STOP, false);
-      } else if (this.accept("TTL")) into.ttl = this.expr(STOP, false);
+        into.sampleBy = this.clauseExpr(STOP, false);
+      } else if (this.accept("TTL")) into.ttl = this.clauseExpr(STOP, false);
       else if (kw(this.peek(), "SETTINGS")) {
         const from = this.idx();
         this.p++;
         into.settings = this.settingsList(STOP);
         into.settingsClause = this.span(from, into.settings.flatMap((s) => s.value.refs));
-      } else return;
+      } else if (!this.unknownClause(STOP)) return;
     }
   }
 
   parse(): CreateNode {
+    const node = this.statement();
+    if (this.unknownClauses.length > 0) node.unknown = [...this.unknownClauses];
+    return node;
+  }
+
+  private statement(): CreateNode {
     this.expect("CREATE");
     let orReplace = false;
     if (this.accept("OR")) {
@@ -429,7 +502,9 @@ class Parser extends SqlCursor {
     if (kw(this.peek(), "UUID") && this.peek(1)?.kind === "string") this.p += 2;
   }
 
-  private finish(what: string): void {
+  /** The statement's end, after any trailing clauses the parser does not know (#3872); `known` are the statement's own clause words. */
+  private finish(what: string, known: readonly string[] = []): void {
+    while (this.unknownClause(known));
     this.acceptPunct(";");
     if (this.peek() !== undefined) this.fail(`unexpected token after the ${what}`);
   }
@@ -438,10 +513,15 @@ class Parser extends SqlCursor {
     const node: DatabaseNode = { statement: "database", ifNotExists: this.ifNotExists(), name: this.qualifiedName() };
     this.uuid();
     node.onCluster = this.onCluster();
-    if (this.accept("ENGINE")) node.engine = this.engine();
-    if (this.accept("SETTINGS")) node.settings = this.settingsList(["COMMENT"]);
-    if (this.accept("COMMENT")) node.comment = this.expr();
-    this.finish("database definition");
+    const CLAUSES = ["ENGINE", "SETTINGS", "COMMENT"];
+    for (;;) {
+      // In the server's order: ENGINE, SETTINGS, COMMENT, with clauses chant does not know between them.
+      if (!node.engine && !node.settings && !node.comment && this.accept("ENGINE")) node.engine = this.engine();
+      else if (!node.settings && !node.comment && this.accept("SETTINGS")) node.settings = this.settingsList(CLAUSES);
+      else if (!node.comment && this.accept("COMMENT")) node.comment = this.clauseExpr();
+      else if (!this.unknownClause(CLAUSES)) break;
+    }
+    this.finish("database definition", CLAUSES);
     return node;
   }
 
@@ -463,8 +543,8 @@ class Parser extends SqlCursor {
     if (!this.isPunct("(")) this.fail("expected the column list (CREATE TABLE ... AS is not declared here)");
     this.tableElements(node, true);
     this.storage(node, []);
-    if (this.accept("COMMENT")) node.comment = this.expr();
-    this.finish("table definition");
+    if (this.accept("COMMENT")) node.comment = this.clauseExpr();
+    this.finish("table definition", STORAGE_KEYWORDS);
     return node;
   }
 
@@ -473,10 +553,10 @@ class Parser extends SqlCursor {
     const STOP = ["DEFAULT", "EXPRESSION", "HIERARCHICAL", "BIDIRECTIONAL", "INJECTIVE", "IS_OBJECT_ID"];
     const attr: DictionaryAttributeNode = { name: text, nameSpan: span, type: this.typeSpan(), flags: [] };
     for (;;) {
-      if (this.accept("DEFAULT")) attr.default = this.expr(STOP);
-      else if (this.accept("EXPRESSION")) attr.expression = this.expr(STOP);
+      if (this.accept("DEFAULT")) attr.default = this.clauseExpr(STOP);
+      else if (this.accept("EXPRESSION")) attr.expression = this.clauseExpr(STOP);
       else if (kw(this.peek(), "HIERARCHICAL", "BIDIRECTIONAL", "INJECTIVE", "IS_OBJECT_ID")) attr.flags.push(this.next().text.toUpperCase());
-      else return attr;
+      else if (!this.unknownClause(STOP, { inList: true, column: text || undefined })) return attr;
     }
   }
 
@@ -499,19 +579,19 @@ class Parser extends SqlCursor {
     for (;;) {
       if (kw(this.peek(), "PRIMARY") && kw(this.peek(1), "KEY")) {
         this.p += 2;
-        node.primaryKey = this.expr(CLAUSES, false);
+        node.primaryKey = this.clauseExpr(CLAUSES, false);
       } else if (this.accept("SOURCE")) node.source = this.parenthesized();
       else if (this.accept("LAYOUT")) node.layout = this.parenthesized();
       else if (this.accept("LIFETIME")) node.lifetime = this.parenthesized();
       else if (this.accept("RANGE")) node.range = this.parenthesized();
       else if (this.accept("SETTINGS")) node.settings = this.parenthesized();
-      else if (this.accept("COMMENT")) node.comment = this.expr();
-      else break;
+      else if (this.accept("COMMENT")) node.comment = this.clauseExpr();
+      else if (!this.unknownClause(CLAUSES)) break;
     }
     if (!node.primaryKey) this.fail("expected PRIMARY KEY: a dictionary needs its key columns");
     if (!node.source) this.fail("expected SOURCE(...): a dictionary needs a source");
     if (!node.layout) this.fail("expected LAYOUT(...): a dictionary needs a layout");
-    this.finish("dictionary definition");
+    this.finish("dictionary definition", CLAUSES);
     return node;
   }
 
@@ -573,10 +653,12 @@ class Parser extends SqlCursor {
       this.tableElements(holder, false);
       node.columnsSpan = this.span(from, []);
     }
-    this.storage(node, ["AS", "POPULATE", "EMPTY", "DEFINER", "SQL"]);
+    const BEFORE_AS = ["AS", "POPULATE", "EMPTY", "DEFINER", "SQL"];
+    this.storage(node, BEFORE_AS);
     if (this.accept("POPULATE")) node.populate = true;
     if (this.accept("EMPTY")) node.empty = true;
     if (kw(this.peek(), "DEFINER", "SQL")) node.security = this.expr(["AS"], false);
+    while (!kw(this.peek(), "AS") && this.unknownClause([...STORAGE_KEYWORDS, ...BEFORE_AS]));
     this.expect("AS");
     node.select = this.expr(["COMMENT"], false);
     if (this.accept("COMMENT")) node.comment = this.expr();

package/src/clickhouse/plan/diff.ts

@@ -129,7 +129,26 @@ function diffMap(key: string, field: string, before: Record<string, string>, aft
   for (const name of changedEntries(before, after)) out.push(change(key, `${field}.${name}`, rule, before[name], after[name]));
 }
 
+/**
+ * The clauses chant does not read (#3872), compared as text. One the
+ * declaration has and the server does not, or has differently, is a change
+ * to review (SQLCH290). One only the server prints is a hint, not a change: a
+ * clause a new server prints with its default cannot be told from one
+ * removed from the declaration.
+ */
+function diffUnparsed(key: string, before: CanonicalObject, after: CanonicalObject, out: Change[], hints: string[]): void {
+  const b = before.unparsed ?? {};
+  const a = after.unparsed ?? {};
+  for (const clause of Object.keys(a)) {
+    if (b[clause] !== a[clause]) out.push(change(key, `unparsed.${clause}`, "SQLCH290", b[clause], a[clause], { note: "chant does not read this clause; review the change" }));
+  }
+  for (const clause of Object.keys(b)) {
+    if (!(clause in a)) hints.push(`${key}: the current definition has ${clause} (${b[clause]}), a clause chant does not read and the declaration does not have; it is not compared`);
+  }
+}
+
 function diffObject(key: string, before: CanonicalObject, after: CanonicalObject, out: Change[], hints: string[]): void {
+  diffUnparsed(key, before, after, out, hints);
   if (before.kind !== after.kind) {
     out.push(change(key, "kind", "SQLCH224", before.kind, after.kind, { destructive: before.kind === "table" }));
     return;

package/src/clickhouse/plan/normalize.ts

@@ -19,7 +19,9 @@
  * - a codec's default level goes (`ZSTD(1)` is `ZSTD`, `Delta(4)` is `Delta`);
  * - a TTL rule's trailing `DELETE` goes;
  * - a setting at the pinned server's default goes;
- * - a view's column list is not compared: the server infers it.
+ * - a view's column list is not compared: the server infers it;
+ * - a clause the parser does not know (#3872) is kept as an expression, by
+ *   its name, and compared as one.
  *
  * What the rules cannot see is the server's own expression formatting
  * (`a+b*2` prints as `a + (b * 2)`). When a plan reads a live server it asks
@@ -32,7 +34,7 @@
  */
 
 import { isTrivia, tokenizeText, type Token } from "../tokens";
-import { parseCreate, unquote, type ColumnNode, type CreateNode, type DictionaryAttributeNode, type DictionaryNode, type Span } from "../parser";
+import { parseCreate, unquote, type ColumnNode, type CreateNode, type DictionaryAttributeNode, type DictionaryNode, type Span, type UnknownClause } from "../parser";
 import { MERGE_TREE_SETTINGS, TYPE_FAMILIES } from "../../generated/clickhouse";
 import { previouslyIn, splitTopLevel as splitTop } from "../../core/normalize";
 import { accessCanonical, grantsCanonical, isAccessStatement } from "../access";
@@ -100,6 +102,14 @@ export interface CanonicalObject {
   previously?: string;
   /** The tool that keeps a live table (a migration runner's history table): a plan never drops it. */
   foreign?: string;
+  /**
+   * Clauses the parser does not know (#3872), each canonical as an
+   * expression, keyed by the clause (`columns.<name>.<clause>` for a
+   * column's). Absent when there are none. The rest of the object is read
+   * as usual; these are compared as text, and a plan classes a change in
+   * one as a change to review.
+   */
+  unparsed?: Record<string, string>;
 }
 
 const KEYWORDS = new Set(
@@ -305,6 +315,8 @@ export function canonicalObject(ddl: string, defaultDatabase = "default"): Canon
   };
   const previously = previouslyIn(leading);
   if (previously) obj.previously = previously;
+  const unparsed = unparsedOf(tokens, node.unknown, database);
+  if (unparsed) obj.unparsed = unparsed;
 
   const comment0 = stringValue(spanText(tokens, node.comment));
   if (node.statement === "dictionary") {
@@ -379,6 +391,19 @@ export function canonicalObject(ddl: string, defaultDatabase = "default"): Canon
   return obj;
 }
 
+/** A statement's unknown clauses (#3872), by clause, each canonical as an expression; a second of the same name is `CLAUSE#2`. */
+function unparsedOf(tokens: Token[], unknown: readonly UnknownClause[] | undefined, database: string | undefined): Record<string, string> | undefined {
+  if (!unknown || unknown.length === 0) return undefined;
+  const out: Record<string, string> = {};
+  for (const u of unknown) {
+    const base = u.column !== undefined ? `columns.${u.column}.${u.clause}` : u.clause;
+    let key = base;
+    for (let n = 2; key in out; n++) key = `${base}#${n}`;
+    out[key] = canonicalExpression(spanText(tokens, u.span) ?? "", database);
+  }
+  return out;
+}
+
 // ── dictionaries ──────────────────────────────────────────────────────
 
 /**

package/src/clickhouse/plan/rebuild-handoff.ts

@@ -37,7 +37,8 @@ const TIME_TYPE = /^(?:Nullable\s*\(\s*)?(?:Date|Date32|DateTime|DateTime64)\b/;
  */
 export function rebuildOpSuggestions(diff: SchemaDiff, declared: ReadonlyMap<string, CanonicalObject>, env: string): RebuildOpSuggestion[] {
   const out: RebuildOpSuggestion[] = [];
-  for (const key of [...new Set(diff.rebuilds.map((c) => c.object))]) {
+  // A clause chant does not read (SQLCH290) is refused for review, not because a rebuild is known to be what it takes.
+  for (const key of [...new Set(diff.rebuilds.filter((c) => c.rule !== "SQLCH290").map((c) => c.object))]) {
     const c = declared.get(key);
     if (!c || c.kind !== "table") continue;
     const table = `${c.database ?? "default"}.${c.name}`;

package/src/clickhouse/plan/rules.ts

@@ -278,6 +278,13 @@ export const CLASSIFIER_RULES = {
     "REVOKE takes a privilege or a role away, including one granted by hand to a grantee the build declares grants for; queries that relied on it fail from then on.",
     `${DOCS}/revoke`,
   ),
+  SQLCH290: rule(
+    "SQLCH290",
+    "rebuild",
+    "Change a clause chant does not read",
+    "chant's parser does not know this clause, so it cannot tell whether ALTER can make the change in place; the plan refuses it rather than guess. Review it: make it by hand with the ALTER the server documents for the clause, or drop and create the object.",
+    `${DOCS}/create/table`,
+  ),
   SQLCH250: rule("SQLCH250", "drop", "Drop an object", "DROP removes the object and, for a table, its data; it is not undone.", `${DOCS}/drop`),
 } as const satisfies Record<string, ClassifierRule>;
 

package/src/clickhouse/testdata/server-ddl-baseline.json

@@ -0,0 +1,67 @@
+{
+  "release": "v26.8.15.10-lts",
+  "unknownClauses": [
+    "APPEND TO",
+    "AUTO_INCREMENT",
+    "CHAR",
+    "CHAR VARYING",
+    "CHARACTER",
+    "CHARACTER LARGE OBJECT",
+    "CHARACTER VARYING",
+    "DEFINER",
+    "DEPENDS ON",
+    "FORMAT",
+    "FORMAT NULL",
+    "HAVE",
+    "REFERENCES",
+    "SQL SECURITY INVOKER",
+    "SQL SECURITY NONE",
+    "STRING",
+    "UNIQUE KEY",
+    "UUID",
+    "YEARS"
+  ],
+  "failures": [
+    "expected ')' at 'WITH'",
+    "expected '='",
+    "expected '=' at '('",
+    "expected '=' at ','",
+    "expected -> and the function's expression at '('",
+    "expected AS at 'COMMENT'",
+    "expected AS at 'LANGUAGE'",
+    "expected AS at 'WASM'",
+    "expected PRIMARY KEY: a dictionary needs its key columns",
+    "expected TYPE at ')'",
+    "expected a clause (CREATE starts a query or a statement, which is not declared here) at 'CREATE'",
+    "expected a column name at '“'",
+    "expected a name at '{'",
+    "expected a setting name at ''John''",
+    "expected a setting name at ''val-''",
+    "expected a setting name at '*+'",
+    "expected a setting name at '1'",
+    "expected a setting name at '3628718300'",
+    "expected a type at '123'",
+    "expected a type at '`Int64`'",
+    "expected a type at '`Null`'",
+    "expected a type at '`a.b`'",
+    "expected a type at '`ab`'",
+    "expected an expression",
+    "expected an expression at ')'",
+    "expected an expression at 'TYPE'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'AS'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'CLONE'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'COMMENT'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'ENGINE'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'Engine'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'ORDER'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'SQL'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'TO'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'as'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'empty'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'engine'",
+    "unexpected end of statement",
+    "unexpected token after the table definition at 'AS'",
+    "unexpected token after the table definition at 'SETTINGS'",
+    "unexpected token after the table definition at 'as'"
+  ]
+}

package/src/clickhouse.ts

@@ -106,3 +106,13 @@ export {
   type Topology,
   type TopologyKind,
 } from "./clickhouse/topology";
+
+// 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,
+  type ClickHouseRead,
+  type ClickHouseTableInfo,
+  type ClickHouseColumnInfo,
+  type ClickHouseViewInfo,
+} from "./read/clickhouse";

package/src/codegen/classifier-page.ts

@@ -49,6 +49,8 @@ Both exit 2 when a change needs a rebuild. \`chant sql diff\` compares a pull re
 
 \`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.

package/src/codegen/postgres-classifier-page.ts

@@ -44,6 +44,8 @@ chant sql plan prod schema.json        # a build output against the prod server
 
 Both read the build's \`dialect\` and exit 2 when a change can only be made as expand and contract. \`--json\` prints the changes, the hints, the refused changes and the migration Op suggestions as one document. \`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 (else \`POSTGRES_URL\`), in the profile's \`schemas\` when it lists them, otherwise in the default schema and every schema the build declares an object in. Where the normalization rules leave an expression different, it asks that server: the declared view, or the table's column types, defaults, generated expressions and checks, are created as temporary objects in a transaction that is always rolled back, and read back with the same printers, so a view's \`SELECT *\` and the server's added parentheses are not reported as changes.
 
+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 SQLPG299, refused for review with no migration Op suggested, since chant cannot tell which lock the change takes. A clause only the server prints is a hint, not a change.
+
 ## 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, and whether it has to run outside a transaction block. \`--json\` prints them as one document, which \`diffStatements(before, after)\` from \`@intentius/chant-lexicon-sql\` also returns, each statement with \`transactional\` set: