@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.0

package/src/core/core.test.ts

@@ -0,0 +1,254 @@
+/**
+ * The shared core, exercised with a toy dialect so nothing here depends on
+ * ClickHouse: whatever a second dialect reuses has to work without it.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { Declarable } from "@intentius/chant";
+import {
+  SqlLiteral,
+  SqlObject,
+  SqlTemplateError,
+  applyOrder,
+  changedEntries,
+  changesByObject,
+  classifiedChange,
+  classifierRule,
+  classifyDisruptionWith,
+  interpolationLine,
+  isColumnRefOf,
+  isSqlObjectOf,
+  lineageJson,
+  makeSqlEntity,
+  matchByIdentity,
+  migrationOpName,
+  missingDependencies,
+  notAttemptedOutcome,
+  previouslyIn,
+  readBuildObjects,
+  receiptAddress,
+  renderChangeSet,
+  renderMigrationOps,
+  resolveOwnershipMarker,
+  spliceText,
+  splitTopLevel,
+  SqlApplyError,
+  templateParts,
+  toApplyResult,
+  type ChangeClasses,
+  type Keyed,
+} from "./index";
+
+// ── A toy dialect ────────────────────────────────────────────────────────
+
+abstract class ToyObject extends SqlObject {
+  declare readonly entityType: "Toy::Table";
+}
+const toy = (sqlName: string, columns: string[], dependsOn: unknown[] = []) =>
+  makeSqlEntity(ToyObject.prototype as ToyObject, "Toy::Table", sqlName, { name: sqlName }, columns, dependsOn) as ToyObject & {
+    columns: Record<string, unknown>;
+  };
+
+type ToyClass = "safe" | "locks" | "create" | "drop";
+const CLASSES: ChangeClasses<ToyClass> = {
+  order: ["create", "safe", "locks", "drop"],
+  label: { create: "create", safe: "safe", locks: "TAKES A LOCK", drop: "drop" },
+  disruption: { create: "in-place", safe: "in-place", locks: "replace", drop: "destroy" },
+};
+const RULES = {
+  TOY200: classifierRule("TOY200", "create" as ToyClass, "Create", "Nothing existing changes.", "https://example.test/create"),
+  TOY201: classifierRule("TOY201", "safe" as ToyClass, "Add a column", "Metadata only.", "https://example.test/add"),
+  TOY202: classifierRule("TOY202", "locks" as ToyClass, "Change a type", "Rewrites under a lock.", "https://example.test/type"),
+  TOY250: classifierRule("TOY250", "drop" as ToyClass, "Drop", "Not undone.", "https://example.test/drop"),
+};
+
+describe("entities", () => {
+  test("hide everything but dependsOn, and hand out column references", () => {
+    const users = toy("users", ["id", "email"]);
+    const orders = toy("orders", ["user_id"], [users]);
+    expect(Object.keys(orders)).toEqual(["dependsOn"]);
+    expect(orders).toBeInstanceOf(ToyObject);
+    expect(orders.lexicon).toBe("sql");
+    expect(isSqlObjectOf(orders, "Toy::")).toBe(true);
+    expect(isSqlObjectOf(orders, "ClickHouse::")).toBe(false);
+    expect(isColumnRefOf(users.columns.id, (p) => isSqlObjectOf(p, "Toy::"))).toBe(true);
+    expect(isColumnRefOf("id", (p) => isSqlObjectOf(p, "Toy::"))).toBe(false);
+  });
+
+  test("order by references, ties by export name, and refuse a cycle", () => {
+    const users = toy("users", ["id"]);
+    const orders = toy("orders", ["user_id"], [users.columns.id]);
+    const names = new Map<Declarable, string>([
+      [users, "users"],
+      [orders, "orders"],
+    ]);
+    expect(applyOrder(new Map([["orders", orders], ["users", users]]), names)).toEqual(["users", "orders"]);
+    expect(lineageJson([{ output: "id", expr: "id", from: [users.columns.id as never] }], names)).toEqual([{ output: "id", expr: "id", from: ["users.id"] }]);
+    const a = { dependsOn: [] as unknown[] };
+    const b = { dependsOn: [a] };
+    a.dependsOn.push(b);
+    expect(() => applyOrder(new Map([["a", a], ["b", b]]), new Map<Declarable, string>([[a as never, "a"], [b as never, "b"]]))).toThrow(/reference cycle.*a -> b -> a/);
+  });
+});
+
+describe("templates", () => {
+  test("splice values, and undo the two forced escapes", () => {
+    expect(spliceText("x + 1")).toBe("x + 1");
+    expect(spliceText(2n)).toBe("2");
+    expect(spliceText(null)).toBe("NULL");
+    expect(spliceText(new SqlLiteral("'a'"))).toBe("'a'");
+    expect(spliceText(undefined)).toMatchObject({ error: expect.stringMatching(/\.columns/) });
+    expect(spliceText({})).toMatchObject({ error: expect.stringMatching(/an object/) });
+    expect(templateParts(Object.assign(["a \\` b \\${c}"], { raw: ["a \\` b \\${c}"] }) as unknown as TemplateStringsArray)).toEqual(["a ` b ${c}"]);
+    expect(interpolationLine(["a\nb", "c"], 0)).toBe(2);
+    expect(new SqlTemplateError("table", "bad", 0, 0).message).toBe("table`...`: bad");
+  });
+});
+
+describe("identity, diff and the classifier", () => {
+  type O = { name: string; schema: string; type: string; previously?: string };
+  const keyed = (key: string, o: O): Keyed<O> => ({ key, canonical: o });
+  const rules = {
+    qualified: (o: O) => `${o.schema}.${o.name}`,
+    previously: (o: O) => o.previously,
+    previousNames: (o: O, prev: string) => [prev, `${o.schema}.${prev}`],
+  };
+
+  test("match by key, then by a rename hint, and list the rest as created and dropped", () => {
+    const before = [keyed("public.users", { name: "users", schema: "public", type: "int" }), keyed("public.old", { name: "old", schema: "public", type: "int" })];
+    const after = [
+      keyed("public.users", { name: "users", schema: "public", type: "bigint" }),
+      keyed("public.accounts", { name: "accounts", schema: "public", type: "int", previously: "old" }),
+      keyed("public.fresh", { name: "fresh", schema: "public", type: "int" }),
+    ];
+    expect(matchByIdentity(before, after, rules).map((m) => [m.kind, m.kind === "dropped" ? m.before.key : m.after.key])).toEqual([
+      ["matched", "public.users"],
+      ["matched", "public.accounts"],
+      ["created", "public.fresh"],
+    ]);
+    expect(matchByIdentity(before, after.slice(0, 1), rules).map((m) => m.kind)).toEqual(["matched", "dropped"]);
+    expect(changedEntries({ a: "1", b: "2" }, { b: "3", c: "4" })).toEqual(["a", "b", "c"]);
+  });
+
+  test("class each change from its rule, report it, and map it onto classifyDisruption", () => {
+    const changes = [
+      classifiedChange(RULES, "users", "columns.id.type", "TOY202", "int", "bigint"),
+      classifiedChange(RULES, "users", "columns.email", "TOY201", undefined, "email text"),
+    ];
+    expect(changes[0]).toEqual({ object: "users", field: "columns.id.type", before: "int", after: "bigint", rule: "TOY202", class: "locks" });
+    expect(changesByObject(changes).get("users")).toHaveLength(2);
+    const text = renderChangeSet({ changes, hints: ["a hint"] }, { title: "base -> head", rules: RULES, classes: CLASSES, trailer: ["", "Refused."] });
+    expect(text.split("\n")).toEqual([
+      "base -> head",
+      "",
+      "users",
+      "  [TAKES A LOCK] columns.id.type: int -> bigint",
+      "      TOY202 Change a type. Rewrites under a lock. https://example.test/type",
+      "  [safe] columns.email: email text",
+      "      TOY201 Add a column. Metadata only. https://example.test/add",
+      "",
+      "1 safe, 1 TAKES A LOCK",
+      "hint: a hint",
+      "",
+      "Refused.",
+    ]);
+    expect(renderChangeSet({ changes: [], hints: [] }, { rules: RULES, classes: CLASSES, trailer: ["never"] })).toBe("No changes.");
+
+    const ruleFor = (path: string) => (path.startsWith("type") ? "TOY202" : path.startsWith("add") ? "TOY201" : path === "?" ? "ambiguous" : undefined) as "TOY201" | "TOY202" | "ambiguous" | undefined;
+    const classify = (paths: string[], type = "Toy::Table") =>
+      classifyDisruptionWith(
+        { typePrefix: "Toy::", rules: RULES, classes: CLASSES, ruleFor, ambiguousDetail: "needs the plan" },
+        { environment: "e", changes: [{ name: "t", type, deltas: paths.map((path) => ({ path })) } as never] },
+      );
+    expect(classify(["add", "type"]).t).toEqual({ disruption: "replace", because: ["type"], detail: "TOY201 Add a column; TOY202 Change a type" });
+    expect(classify(["add", "?"]).t).toEqual({ disruption: "unknown", because: ["add", "?"], detail: "needs the plan" });
+    expect(classify(["add"], "Other::Thing")).toEqual({});
+  });
+});
+
+describe("normalization helpers", () => {
+  test("read the rename hint, and split on top-level commas", () => {
+    expect(previouslyIn(["-- previously: old_name"])).toBe("old_name");
+    expect(previouslyIn(['-- previously: "Old"'])).toBe("Old");
+    expect(previouslyIn(["-- a comment"])).toBeUndefined();
+    expect(splitTopLevel("a , f ( b , c ) , [ d , e ]")).toEqual(["a", "f ( b , c )", "[ d , e ]"]);
+  });
+});
+
+describe("apply plumbing", () => {
+  const doc = (dialect: string, objects: unknown[]) => JSON.stringify({ sql: { dialect, objects } });
+
+  test("reads a build's objects for one dialect, nested or not", () => {
+    const objects = readBuildObjects(doc("toy", [{ export: "t", type: "Toy::Table", ddl: "CREATE TABLE t ()", dependsOn: ["s", "s.id", 3] }]), "toy", (o) => o);
+    expect(objects).toEqual([{ export: "t", type: "Toy::Table", ddl: "CREATE TABLE t ()", dependsOn: ["s"] }]);
+    expect(() => readBuildObjects(doc("other", []), "toy", (o) => o)).toThrow('expected { dialect: "toy", objects: [...] }');
+    expect(() => readBuildObjects(doc("toy", [{ export: "t" }]), "toy", (o) => o)).toThrow("objects[0] has no export, type or ddl");
+  });
+
+  test("keeps the tri-state, projects it onto the envelope, and names the dialect in its error", () => {
+    const outcome = notAttemptedOutcome([{ kind: "Toy::Table", name: "t" }], "no-binding", "nothing bound");
+    expect(toApplyResult(outcome).notAttempted).toEqual([{ kind: "Toy::Table", name: "t", reason: "no-binding", detail: "nothing bound" }]);
+    const failed = { ...outcome, target: "toy://x", notAttempted: [], failed: [{ kind: "Toy::Table", name: "t", error: "refused", statements: [] }] };
+    const err = new SqlApplyError("Toy", failed);
+    expect(err.message).toBe("Toy apply to toy://x: 1 object(s) failed (Toy::Table/t: refused); 0 applied, 0 pruned, 0 not attempted before and after");
+    expect(err.outcome).toBe(failed);
+    expect(missingDependencies("v", ["t", "v", "external"], new Set(["t", "v"]), new Set())).toEqual(["t"]);
+  });
+
+  test("resolves the ownership marker from args, then config", () => {
+    expect(resolveOwnershipMarker({ stack: "a" }, { ownership: { stack: "b", env: "prod" } }, "toy apply")).toEqual({ stack: "a", env: "prod" });
+    expect(resolveOwnershipMarker({}, { ownership: { stack: "b", enabled: false } }, "toy apply")).toBeUndefined();
+    expect(() => resolveOwnershipMarker({}, { ownership: { stack: "b", env: { param: "env" } } as never }, "toy apply")).toThrow(/^toy apply: ownership.env/);
+  });
+});
+
+describe("receipts and the migration hand-off", () => {
+  test("address receipts by stack, env and effect", () => {
+    expect(receiptAddress({ stack: "shop", env: "prod" }, "migrate/users/1")).toBe("shop/prod/migrate/users/1");
+    expect(receiptAddress({}, "e")).toBe("-/-/e");
+  });
+
+  test("name and render the Op to run instead", () => {
+    expect(migrationOpName("migrate", "public.Users")).toBe("migrate-public-users");
+    const op = { table: "public.users", name: "migrate-public-users", env: "prod", declaration: "export const { op } = ToyOp({});" };
+    expect(renderMigrationOps([op], { what: "the toy Op", exportName: "ToyOp", importPath: "toy" })).toEqual([
+      "",
+      'Run it as the toy Op, declared in an *.op.ts file (import { ToyOp } from "toy"), then `chant run <name>` until it is done:',
+      "  export const { op } = ToyOp({});",
+    ]);
+    expect(renderMigrationOps([], { what: "x", exportName: "X", importPath: "x" })).toEqual([]);
+  });
+});
+
+describe("tokens, cursor and template finding", () => {
+  test("a dialect's lexical rules decide quotes and punctuation", async () => {
+    const { tokenizeText } = await import("./tokens");
+    const rules = { identQuotes: '"', backslashEscapes: false, punct: "(),;.", opChars: /[=<>]/ };
+    expect(tokenizeText('"a""b" = \'x\\\'', 0, rules).map((t) => [t.kind, t.text])).toEqual([
+      ["qident", '"a""b"'],
+      ["ws", " "],
+      ["op", "="],
+      ["ws", " "],
+      ["string", "'x\\'"],
+    ]);
+  });
+
+  test("a tag is a dialect's by the module it is imported from", async () => {
+    const ts = await import("typescript");
+    const { findSqlTemplates } = await import("./find-templates");
+    const source = ts.createSourceFile(
+      "f.ts",
+      'import { table } from "toy-a";\nimport { table as t2 } from "toy-b";\nexport const x = table`CREATE TABLE x (a int)`;\nexport const y = t2`CREATE TABLE y (${x}) b`;',
+      ts.ScriptTarget.Latest,
+      true,
+    );
+    const found = findSqlTemplates(source, [
+      { dialect: "a", modules: ["toy-a"], tags: ["table"] },
+      { dialect: "b", modules: ["toy-b"], tags: ["table"] },
+    ]);
+    expect(found.map((f) => [f.dialect, f.tag, f.parts])).toEqual([
+      ["a", "table", ["CREATE TABLE x (a int)"]],
+      ["b", "table", ["CREATE TABLE y (", ") b"]],
+    ]);
+  });
+});

package/src/core/cursor.ts

@@ -0,0 +1,189 @@
+/**
+ * The dialect-neutral half of a hand-written CREATE parser (chant #3196,
+ * #3278): a cursor over a statement's significant tokens, keyword and
+ * punctuation tests, spans, and expressions kept as balanced token spans.
+ *
+ * Statement structure is a dialect's to parse; expressions are not parsed. An
+ * expression (a default, a key, a view's SELECT) is a span of tokens: its
+ * source text, verbatim, and the interpolations inside it. A dialect parser
+ * extends {@link SqlCursor} with its statements, and says where an expression
+ * stops ({@link SqlCursor.stopsAt}) and how a token nests
+ * ({@link SqlCursor.depthChange}).
+ */
+
+import { isTrivia, SqlSyntaxError, type Token } from "./tokens";
+
+/** A run of tokens [from, to) in the token list, trivia included. */
+export interface Span {
+  from: number;
+  to: number;
+  /** Value indexes of the interpolations inside the span. */
+  refs: number[];
+}
+
+/** Whether `t` is a bare word, any of `words`, case-insensitively. */
+export const kw = (t: Token | undefined, ...words: string[]): boolean =>
+  t !== undefined && t.kind === "ident" && words.includes(t.text.toUpperCase());
+
+/** `name` with its identifier quotes taken off and doubled quotes undone; `quotes` are the dialect's identifier quotes. */
+export const unquoteWith = (text: string, quotes: string): string => {
+  if (text.length < 2 || !quotes.includes(text[0]!) || !quotes.includes(text[text.length - 1]!)) return text;
+  let inner = text.slice(1, -1);
+  for (const q of quotes) inner = inner.split(q + q).join(q);
+  return inner;
+};
+
+export class SqlCursor {
+  /** Indexes of the significant (non-trivia) tokens. */
+  protected readonly sig: number[];
+  protected p = 0;
+
+  constructor(protected readonly tokens: Token[]) {
+    this.sig = tokens.map((t, i) => (isTrivia(t) ? -1 : i)).filter((i) => i >= 0);
+  }
+
+  protected peek(n = 0): Token | undefined {
+    const idx = this.sig[this.p + n];
+    return idx === undefined ? undefined : this.tokens[idx];
+  }
+
+  /** Token-list index of the significant token `n` ahead. */
+  protected idx(n = 0): number {
+    return this.sig[this.p + n] ?? this.tokens.length;
+  }
+
+  protected next(): Token {
+    const t = this.peek();
+    if (!t) this.fail("unexpected end of statement");
+    this.p++;
+    return t;
+  }
+
+  fail(message: string, t: Token | undefined = this.peek()): never {
+    const at = t ?? this.lastToken();
+    const shown = t ? ` at '${t.kind === "ref" ? "${...}" : t.text}'` : "";
+    throw new SqlSyntaxError(`${message}${shown}`, at?.part ?? 0, t ? at!.start : (at?.end ?? 0), at);
+  }
+
+  protected lastToken(): Token | undefined {
+    const last = this.sig[this.sig.length - 1];
+    return last === undefined ? undefined : this.tokens[last];
+  }
+
+  protected accept(...words: string[]): boolean {
+    if (kw(this.peek(), ...words)) {
+      this.p++;
+      return true;
+    }
+    return false;
+  }
+
+  protected expect(...words: string[]): void {
+    if (!this.accept(...words)) this.fail(`expected ${words.join(" or ")}`);
+  }
+
+  /** Whether the next significant tokens are the bare words `words`, in order. */
+  protected is(...words: string[]): boolean {
+    return words.every((w, n) => kw(this.peek(n), w));
+  }
+
+  /** Accept a sequence of bare words, all of them or none. */
+  protected acceptSeq(...words: string[]): boolean {
+    if (!this.is(...words)) return false;
+    this.p += words.length;
+    return true;
+  }
+
+  protected isPunct(c: string, n = 0): boolean {
+    const t = this.peek(n);
+    return t !== undefined && t.kind === "punct" && t.text === c;
+  }
+
+  protected acceptPunct(c: string): boolean {
+    if (this.isPunct(c)) {
+      this.p++;
+      return true;
+    }
+    return false;
+  }
+
+  protected expectPunct(c: string): void {
+    if (!this.acceptPunct(c)) this.fail(`expected '${c}'`);
+  }
+
+  protected atEnd(): boolean {
+    return this.peek() === undefined || this.isPunct(";");
+  }
+
+  protected span(from: number, refs: number[]): Span {
+    return { from, to: this.idx(-1) + 1, refs };
+  }
+
+  /**
+   * Whether the expression being read stops at the current token, a top-level
+   * bare word: by default when it is one of `stop`. A dialect overrides this
+   * for its multi-word stops (ClickHouse stops at `ORDER` only before `BY`).
+   */
+  protected stopsAt(stop: readonly string[]): boolean {
+    const t = this.peek();
+    return t !== undefined && t.kind === "ident" && stop.includes(t.text.toUpperCase());
+  }
+
+  /** How `t` changes the nesting depth of an expression: `(` opens and `)` closes. */
+  protected depthChange(t: Token): number {
+    if (t.kind === "punct" && t.text === "(") return 1;
+    if (t.kind === "punct" && t.text === ")") return -1;
+    return 0;
+  }
+
+  /**
+   * An expression as a token span: everything up to a top-level `,` (unless
+   * `stopAtComma` is false), `)` or `;`, or a top-level stop word. Nesting is
+   * balanced, not parsed.
+   */
+  protected expr(stop: readonly string[] = [], stopAtComma = true): Span {
+    const from = this.idx();
+    const refs: number[] = [];
+    let depth = 0;
+    const startP = this.p;
+    for (;;) {
+      const t = this.peek();
+      if (t === undefined) break;
+      if (depth === 0) {
+        if (t.kind === "punct" && (t.text === ")" || t.text === ";" || (stopAtComma && t.text === ","))) break;
+        if (this.stopsAt(stop)) break;
+      }
+      depth += this.depthChange(t);
+      if (t.kind === "ref") refs.push(t.part);
+      this.p++;
+    }
+    if (this.p === startP) this.fail("expected an expression");
+    return this.span(from, refs);
+  }
+
+  /** `( ... )` balanced: the span between the parentheses. */
+  protected parenthesized(): Span {
+    this.expectPunct("(");
+    if (this.isPunct(")")) {
+      const at = this.idx();
+      this.p++;
+      return { from: at, to: at, refs: [] };
+    }
+    const inner = this.exprList();
+    this.expectPunct(")");
+    return inner;
+  }
+
+  /** A comma-separated expression list as one span. */
+  protected exprList(stop: readonly string[] = []): Span {
+    const first = this.expr(stop);
+    let last = first;
+    const refs = [...first.refs];
+    while (this.isPunct(",")) {
+      this.p++;
+      last = this.expr(stop);
+      refs.push(...last.refs);
+    }
+    return { from: first.from, to: last.to, refs };
+  }
+}

package/src/core/diff.ts

@@ -0,0 +1,72 @@
+/**
+ * Identity and renames between two schemas, the same in every dialect
+ * (#3047 question 3).
+ *
+ * An object is identified by its key: its export name between two revisions
+ * of the declarations, its qualified name against a live server, which has no
+ * export names. An `after` object whose key is new but whose `previously` hint
+ * (`-- previously: <old name>`) names a `before` object with no `after`
+ * counterpart is that object, renamed. What changed inside a matched pair,
+ * and how each change is classed, is the dialect's.
+ */
+
+/** One side of a comparison: an object's identity and its canonical definition. */
+export interface Keyed<O> {
+  /** The object's identity in the comparison: an export name, or a qualified name against live. */
+  key: string;
+  canonical: O;
+}
+
+export type IdentityMatch<O> =
+  | { kind: "created"; after: Keyed<O> }
+  | { kind: "matched"; before: Keyed<O>; after: Keyed<O> }
+  | { kind: "dropped"; before: Keyed<O> };
+
+export interface IdentityRules<O> {
+  /** The object's qualified name, which a `previously` hint may name. */
+  qualified(o: O): string;
+  /** The `-- previously: <old name>` hint on the object, if any. */
+  previously(o: O): string | undefined;
+  /**
+   * The qualified names a hint may mean, tried in order after the hint as a
+   * key: the hint itself, and for a dialect with schemas or databases the hint
+   * qualified with the object's own.
+   */
+  previousNames(o: O, previously: string): readonly string[];
+}
+
+/**
+ * Match `after` to `before` by key, then by rename hint. Returns every `after`
+ * object in order, created or matched, then every `before` object no `after`
+ * object matched, dropped.
+ */
+export function matchByIdentity<O>(before: readonly Keyed<O>[], after: readonly Keyed<O>[], rules: IdentityRules<O>): IdentityMatch<O>[] {
+  const out: IdentityMatch<O>[] = [];
+  const byKey = new Map(before.map((o) => [o.key, o]));
+  const byQualified = new Map(before.map((o) => [rules.qualified(o.canonical), o]));
+  const afterKeys = new Set(after.map((o) => o.key));
+  const matched = new Set<string>();
+
+  for (const a of after) {
+    let b = byKey.get(a.key);
+    const prev = rules.previously(a.canonical);
+    if (!b && prev) {
+      let candidate = byKey.get(prev);
+      for (const name of rules.previousNames(a.canonical, prev)) candidate ??= byQualified.get(name);
+      if (candidate && !afterKeys.has(candidate.key)) b = candidate;
+    }
+    if (!b) {
+      out.push({ kind: "created", after: a });
+      continue;
+    }
+    matched.add(b.key);
+    out.push({ kind: "matched", before: b, after: a });
+  }
+  for (const b of before) if (!matched.has(b.key)) out.push({ kind: "dropped", before: b });
+  return out;
+}
+
+/** The names whose values differ between two records, sorted. */
+export function changedEntries(before: Readonly<Record<string, string>>, after: Readonly<Record<string, string>>): string[] {
+  return [...new Set([...Object.keys(before), ...Object.keys(after)])].sort().filter((name) => before[name] !== after[name]);
+}

package/src/core/entity.ts

@@ -0,0 +1,85 @@
+/**
+ * The entity base every dialect's objects share: the Declarable fields core
+ * reads, the hidden-property construction that keeps them out of a build's
+ * props, and the column references (`${t.columns.x}`) a relation hands out.
+ *
+ * A dialect subclasses {@link SqlObject} with its own entity types
+ * (`ClickHouse::Table`), builds its entities with {@link makeSqlEntity} on its
+ * subclass's prototype, and recognizes its own objects by their type prefix.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { AttrRef } from "@intentius/chant/attrref";
+
+/** The lexicon every dialect's entities belong to. */
+export const SQL_LEXICON = "sql";
+
+/** The members a schema object has besides its props, in every dialect. */
+export abstract class SqlObject implements Declarable {
+  declare readonly [DECLARABLE_MARKER]: true;
+  declare readonly lexicon: "sql";
+  declare readonly entityType: string;
+  declare readonly kind: "resource";
+  /** The name the object is referred to by in SQL, qualified as the dialect writes it. */
+  declare readonly sqlName: string;
+  /** The parsed definition; each entity kind narrows it. */
+  declare readonly props: object;
+  /**
+   * Everything the DDL references, enumerable so core's dependency graph and
+   * `chant graph` see the edges.
+   */
+  declare readonly dependsOn: readonly unknown[];
+}
+
+const hidden = (target: object, key: string | symbol, value: unknown) =>
+  Object.defineProperty(target, key, { value, enumerable: false, writable: false, configurable: false });
+
+/**
+ * One entity on `prototype` (a dialect's {@link SqlObject} subclass). Every
+ * field but `dependsOn` is hidden, so a build's props are the parsed
+ * definition alone. With `columnNames`, the entity gets a frozen `columns`
+ * record holding one {@link AttrRef} per column.
+ */
+export function makeSqlEntity<T extends SqlObject>(
+  prototype: T,
+  entityType: string,
+  sqlName: string,
+  props: object,
+  columnNames: readonly string[] | undefined,
+  dependsOn: unknown[],
+): T {
+  const entity = Object.create(prototype) as T;
+  hidden(entity, DECLARABLE_MARKER, true);
+  hidden(entity, "lexicon", SQL_LEXICON);
+  hidden(entity, "entityType", entityType);
+  hidden(entity, "kind", "resource");
+  hidden(entity, "props", props);
+  hidden(entity, "sqlName", sqlName);
+  if (columnNames) {
+    const columns: Record<string, AttrRef> = {};
+    for (const name of columnNames) columns[name] = new AttrRef(entity, name);
+    hidden(entity, "columns", Object.freeze(columns));
+  }
+  Object.defineProperty(entity, "dependsOn", { value: dependsOn, enumerable: true });
+  return entity;
+}
+
+/** Whether `value` is a sql lexicon entity whose type starts with `typePrefix` (`ClickHouse::`). */
+export function isSqlObjectOf(value: unknown, typePrefix: string): value is SqlObject {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Declarable).lexicon === SQL_LEXICON &&
+    typeof (value as SqlObject).sqlName === "string" &&
+    typeof (value as Declarable).entityType === "string" &&
+    (value as Declarable).entityType.startsWith(typePrefix)
+  );
+}
+
+/** A column reference: an AttrRef whose parent `isOwner` accepts. */
+export function isColumnRefOf(value: unknown, isOwner: (parent: unknown) => boolean): value is AttrRef {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Partial<AttrRef>;
+  if (typeof v.attribute !== "string" || typeof v.parent?.deref !== "function") return false;
+  return isOwner(v.parent.deref());
+}