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

package/src/lint/post-synth/clickhouse-checks.test.ts

@@ -0,0 +1,278 @@
+import { describe, expect, test } from "vitest";
+import { makePostSynthCtx } from "@intentius/chant-test-utils";
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { sqlSerializer } from "../../serializer";
+import { database, table, view } from "../../clickhouse/entities";
+import { sqlAuditCatalog } from "../audit-catalog";
+import { postSynthChecks } from "./index";
+
+type Entities = Record<string, unknown>;
+
+function run(id: string, entities: Entities) {
+  const check = postSynthChecks.find((c: PostSynthCheck) => c.id === id)!;
+  const out = sqlSerializer.serialize(new Map(Object.entries(entities)) as never) as SerializerResult;
+  return check.check(makePostSynthCtx("sql", out.primary));
+}
+
+const flagged = (id: string, entities: Entities, text: RegExp) => {
+  const diags = run(id, entities);
+  expect(diags.length).toBeGreaterThan(0);
+  expect(diags[0]).toMatchObject({ checkId: id, lexicon: "sql" });
+  expect(diags[0]!.message).toMatch(text);
+  return diags;
+};
+
+describe("registration", () => {
+  test("at least 15 ClickHouse post-synth checks, each with an audit entry", () => {
+    const ids = postSynthChecks.map((c) => c.id).filter((id) => /^SQLCH1\d\d$/.test(id));
+    expect(ids.length).toBeGreaterThanOrEqual(15);
+    for (const id of ids) expect(sqlAuditCatalog[id], id).toBeDefined();
+  });
+
+  test("the audit categories cover security and correctness and best practice", () => {
+    const cats = new Set(Object.values(sqlAuditCatalog).filter((m) => m.yamlBased).map((m) => m.category));
+    expect(cats).toEqual(new Set(["security", "correctness", "best-practice"]));
+  });
+});
+
+describe("SQLCH102: PRIMARY KEY not a prefix of ORDER BY", () => {
+  test("flags a primary key outside the sort key", () => {
+    const t = table`CREATE TABLE t (a UInt8, b UInt8) ENGINE = MergeTree PRIMARY KEY b ORDER BY (a, b)`;
+    flagged("SQLCH102", { t }, /not a prefix/);
+  });
+  test("a prefix, and no primary key, are clean", () => {
+    const a = table`CREATE TABLE a (a UInt8, b UInt8) ENGINE = MergeTree PRIMARY KEY a ORDER BY (a, b)`;
+    const b = table`CREATE TABLE b (a UInt8) ENGINE = MergeTree ORDER BY a`;
+    expect(run("SQLCH102", { a, b })).toEqual([]);
+  });
+});
+
+describe("SQLCH103: engine special column types", () => {
+  test("flags a String version column", () => {
+    const t = table`CREATE TABLE t (a UInt8, v String) ENGINE = ReplacingMergeTree(v) ORDER BY a`;
+    flagged("SQLCH103", { t }, /version column v is String/);
+  });
+  test("flags a sign that is not Int8", () => {
+    const t = table`CREATE TABLE t (a UInt8, s UInt8) ENGINE = CollapsingMergeTree(s) ORDER BY a`;
+    flagged("SQLCH103", { t }, /sign column s/);
+  });
+  test("accepts a DateTime version and an Int8 sign", () => {
+    const a = table`CREATE TABLE a (k UInt8, v DateTime) ENGINE = ReplacingMergeTree(v) ORDER BY k`;
+    const b = table`CREATE TABLE b (k UInt8, s Int8) ENGINE = CollapsingMergeTree(s) ORDER BY k`;
+    expect(run("SQLCH103", { a, b })).toEqual([]);
+  });
+});
+
+describe("SQLCH104: engine argument names a missing column", () => {
+  test("flags a version column the table lacks", () => {
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = ReplacingMergeTree(ver) ORDER BY a`;
+    flagged("SQLCH104", { t }, /names column ver/);
+  });
+  test("a declared column is clean", () => {
+    const t = table`CREATE TABLE t (a UInt8, ver UInt32) ENGINE = ReplacingMergeTree(ver) ORDER BY a`;
+    expect(run("SQLCH104", { t })).toEqual([]);
+  });
+});
+
+describe("SQLCH105: key clause names a missing column", () => {
+  test("flags ORDER BY and PARTITION BY names", () => {
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = MergeTree PARTITION BY month ORDER BY (a, missing)`;
+    const diags = run("SQLCH105", { t });
+    expect(diags.map((d) => d.message).join("\n")).toMatch(/ORDER BY names column missing[\s\S]*PARTITION BY names column month/);
+  });
+  test("expressions and declared columns are clean", () => {
+    const t = table`CREATE TABLE t (a UInt8, d Date) ENGINE = MergeTree PARTITION BY toYYYYMM(d) ORDER BY (a, d)`;
+    expect(run("SQLCH105", { t })).toEqual([]);
+  });
+});
+
+describe("SQLCH106: skip index names a missing column", () => {
+  test("flags a column the table lacks", () => {
+    const t = table`CREATE TABLE t (a String, INDEX i lower(nope) TYPE bloom_filter GRANULARITY 1) ENGINE = MergeTree ORDER BY a`;
+    flagged("SQLCH106", { t }, /names nope/);
+  });
+  test("a declared column inside a call is clean", () => {
+    const t = table`CREATE TABLE t (a String, INDEX i lower(a) TYPE bloom_filter GRANULARITY 1) ENGINE = MergeTree ORDER BY a`;
+    expect(run("SQLCH106", { t })).toEqual([]);
+  });
+});
+
+describe("SQLCH107: TTL on a non-date column", () => {
+  test("flags a table TTL on a String column", () => {
+    const t = table`CREATE TABLE t (a UInt8, s String) ENGINE = MergeTree ORDER BY a TTL s + INTERVAL 1 DAY`;
+    flagged("SQLCH107", { t }, /table TTL is built on s/);
+  });
+  test("flags a column TTL on an integer", () => {
+    const t = table`CREATE TABLE t (a UInt8, n UInt32 TTL n DELETE) ENGINE = MergeTree ORDER BY a`;
+    expect(run("SQLCH107", { t }).length).toBeGreaterThan(0);
+  });
+  test("DateTime with an interval and an action is clean", () => {
+    const t = table`CREATE TABLE t (a UInt8, d DateTime) ENGINE = MergeTree ORDER BY a TTL d + INTERVAL 1 DAY DELETE`;
+    expect(run("SQLCH107", { t })).toEqual([]);
+  });
+});
+
+describe("SQLCH108: OR REPLACE outside an Atomic database", () => {
+  test("flags a replace in an Ordinary database", () => {
+    const db = database`CREATE DATABASE app ENGINE = Ordinary`;
+    const t = table`CREATE OR REPLACE TABLE app.t (a UInt8) ENGINE = MergeTree ORDER BY a`;
+    flagged("SQLCH108", { db, t }, /Atomic or Replicated/);
+  });
+  test("Atomic is clean", () => {
+    const db = database`CREATE DATABASE app ENGINE = Atomic`;
+    const t = table`CREATE OR REPLACE TABLE app.t (a UInt8) ENGINE = MergeTree ORDER BY a`;
+    expect(run("SQLCH108", { db, t })).toEqual([]);
+  });
+});
+
+describe("SQLCH109: materialized view selects *", () => {
+  test("flags a star", () => {
+    const src = table`CREATE TABLE src (a UInt8) ENGINE = MergeTree ORDER BY a`;
+    const mv = view`CREATE MATERIALIZED VIEW mv ENGINE = MergeTree ORDER BY a AS SELECT * FROM ${src}`;
+    flagged("SQLCH109", { src, mv }, /selects \*/);
+  });
+  test("a column list is clean", () => {
+    const src = table`CREATE TABLE src (a UInt8) ENGINE = MergeTree ORDER BY a`;
+    const mv = view`CREATE MATERIALIZED VIEW mv ENGINE = MergeTree ORDER BY a AS SELECT ${src.columns.a} FROM ${src}`;
+    expect(run("SQLCH109", { src, mv })).toEqual([]);
+  });
+});
+
+describe("SQLCH110: view column missing from its TO target", () => {
+  test("flags a selected column the target lacks", () => {
+    const src = table`CREATE TABLE src (a UInt8, b UInt8) ENGINE = MergeTree ORDER BY a`;
+    const tgt = table`CREATE TABLE tgt (a UInt8) ENGINE = MergeTree ORDER BY a`;
+    const mv = view`CREATE MATERIALIZED VIEW mv TO ${tgt} AS SELECT ${src.columns.a}, ${src.columns.b} FROM ${src}`;
+    flagged("SQLCH110", { src, tgt, mv }, /selects b/);
+  });
+  test("matching columns are clean", () => {
+    const src = table`CREATE TABLE src (a UInt8, b UInt8) ENGINE = MergeTree ORDER BY a`;
+    const tgt = table`CREATE TABLE tgt (a UInt8, b UInt8) ENGINE = MergeTree ORDER BY a`;
+    const mv = view`CREATE MATERIALIZED VIEW mv TO ${tgt} AS SELECT ${src.columns.a}, ${src.columns.b} FROM ${src}`;
+    expect(run("SQLCH110", { src, tgt, mv })).toEqual([]);
+  });
+});
+
+describe("SQLCH111: String limited to a few values", () => {
+  test("flags a CHECK ... IN on a String", () => {
+    const t = table`CREATE TABLE t (s String, CONSTRAINT c CHECK s IN ('a', 'b')) ENGINE = MergeTree ORDER BY s`;
+    flagged("SQLCH111", { t }, /LowCardinality/);
+  });
+  test("LowCardinality is clean", () => {
+    const t = table`CREATE TABLE t (s LowCardinality(String), CONSTRAINT c CHECK s IN ('a', 'b')) ENGINE = MergeTree ORDER BY s`;
+    expect(run("SQLCH111", { t })).toEqual([]);
+  });
+});
+
+describe("SQLCH112: PARTITION BY finer than a day", () => {
+  test("flags a bare DateTime and an hourly truncation", () => {
+    const a = table`CREATE TABLE a (d DateTime) ENGINE = MergeTree PARTITION BY d ORDER BY d`;
+    const b = table`CREATE TABLE b (d DateTime) ENGINE = MergeTree PARTITION BY toStartOfHour(d) ORDER BY d`;
+    expect(run("SQLCH112", { a, b })).toHaveLength(2);
+  });
+  test("a month is clean", () => {
+    const t = table`CREATE TABLE t (d DateTime) ENGINE = MergeTree PARTITION BY toYYYYMM(d) ORDER BY d`;
+    expect(run("SQLCH112", { t })).toEqual([]);
+  });
+});
+
+describe("SQLCH113: MergeTree with no sort key", () => {
+  test("flags a missing ORDER BY", () => {
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = MergeTree`;
+    flagged("SQLCH113", { t }, /no ORDER BY/);
+  });
+  test("ORDER BY tuple() and a non-MergeTree engine are clean", () => {
+    const a = table`CREATE TABLE a (a UInt8) ENGINE = MergeTree ORDER BY tuple()`;
+    const b = table`CREATE TABLE b (a UInt8) ENGINE = Memory`;
+    expect(run("SQLCH113", { a, b })).toEqual([]);
+  });
+});
+
+describe("SQLCH114: unknown codec", () => {
+  test("flags a codec the pin lacks", () => {
+    const t = table`CREATE TABLE t (a UInt8 CODEC(Snappy)) ENGINE = MergeTree ORDER BY a`;
+    flagged("SQLCH114", { t }, /Snappy/);
+  });
+  test("known codecs with parameters are clean", () => {
+    const t = table`CREATE TABLE t (a UInt8 CODEC(Delta, ZSTD(3))) ENGINE = MergeTree ORDER BY a`;
+    expect(run("SQLCH114", { t })).toEqual([]);
+  });
+});
+
+describe("SQLCH115: secret-named columns", () => {
+  test("flags a password column with no marker", () => {
+    const t = table`CREATE TABLE t (a UInt8, password String) ENGINE = MergeTree ORDER BY a`;
+    flagged("SQLCH115", { t }, /password/);
+  });
+  test("a comment, a TTL or an encryption codec clears it", () => {
+    const a = table`CREATE TABLE a (k UInt8, api_key String COMMENT 'hashed') ENGINE = MergeTree ORDER BY k`;
+    const b = table`CREATE TABLE b (k UInt8, secret String CODEC(AES_256_GCM_SIV)) ENGINE = MergeTree ORDER BY k`;
+    const c = table`CREATE TABLE c (k UInt8, d DateTime, token String) ENGINE = MergeTree ORDER BY k TTL d + INTERVAL 7 DAY`;
+    expect(run("SQLCH115", { a, b, c })).toEqual([]);
+  });
+  test("an ordinary name is clean", () => {
+    const t = table`CREATE TABLE t (a UInt8, tokens_used UInt32, passwords_reset UInt8) ENGINE = MergeTree ORDER BY a`;
+    expect(run("SQLCH115", { t })).toEqual([]);
+  });
+});
+
+describe("SQLCH116: DEFINER view without a definer", () => {
+  test("flags SQL SECURITY DEFINER alone", () => {
+    const v = view`CREATE VIEW v SQL SECURITY DEFINER AS SELECT 1 AS a`;
+    flagged("SQLCH116", { v }, /no DEFINER/);
+  });
+  test("a named definer is clean", () => {
+    const v = view`CREATE VIEW v DEFINER = reporter SQL SECURITY DEFINER AS SELECT 1 AS a`;
+    expect(run("SQLCH116", { v })).toEqual([]);
+  });
+});
+
+describe("SQLCH117: obsolete MergeTree setting", () => {
+  test("flags a setting the pin marks obsolete", () => {
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = MergeTree ORDER BY a SETTINGS min_rows_for_compact_part = 10`;
+    flagged("SQLCH117", { t }, /obsolete/);
+  });
+  test("a current setting is clean", () => {
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = MergeTree ORDER BY a SETTINGS index_granularity = 4096`;
+    expect(run("SQLCH117", { t })).toEqual([]);
+  });
+});
+
+describe("SQLCH118: unknown MergeTree setting", () => {
+  test("flags a misspelled setting", () => {
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = MergeTree ORDER BY a SETTINGS index_granularty = 4096`;
+    flagged("SQLCH118", { t }, /index_granularty/);
+  });
+  test("a known setting is clean", () => {
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = MergeTree ORDER BY a SETTINGS storage_policy = 'default'`;
+    expect(run("SQLCH118", { t })).toEqual([]);
+  });
+});
+
+describe("SQLCH119: deprecated or experimental engine", () => {
+  test("flags the Ordinary database engine", () => {
+    const db = database`CREATE DATABASE d ENGINE = Ordinary`;
+    flagged("SQLCH119", { db }, /deprecated engine Ordinary/);
+  });
+  test("flags an experimental table engine", () => {
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = WindowView`;
+    flagged("SQLCH119", { t }, /experimental engine WindowView/);
+  });
+  test("Atomic and MergeTree are clean", () => {
+    const db = database`CREATE DATABASE d ENGINE = Atomic`;
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = MergeTree ORDER BY a`;
+    expect(run("SQLCH119", { db, t })).toEqual([]);
+  });
+});
+
+describe("SQLCH120: legacy MergeTree arguments", () => {
+  test("flags the positional form", () => {
+    const t = table`CREATE TABLE t (d Date, a UInt8) ENGINE = MergeTree(d, (a, d), 8192)`;
+    flagged("SQLCH120", { t }, /positional/);
+  });
+  test("a bare MergeTree is clean", () => {
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = MergeTree ORDER BY a`;
+    expect(run("SQLCH120", { t })).toEqual([]);
+  });
+});

package/src/lint/post-synth/clickhouse-helpers.ts

@@ -0,0 +1,206 @@
+/**
+ * Reading the ClickHouse objects in the sql build output for post-synth
+ * checks: typed views of the serialized objects and a few scanners for the
+ * expression text the parser keeps as written (sort keys, TTLs, index
+ * expressions). The scanners are deliberately small: they answer "is this a
+ * bare column name" and "which names does this expression mention", not "what
+ * does this expression evaluate to".
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { TABLE_ENGINES, TYPE_FAMILIES } from "../../generated/clickhouse";
+import type { ColumnDef, EngineDef } from "../../clickhouse/entities";
+import { clickhouseObjects, type OutputObject } from "./sql-helpers";
+
+export interface TableObject extends OutputObject {
+  columns: ColumnDef[];
+  indexes: Array<{ name: string; expr: string; type: string; granularity?: string }>;
+  constraints: Array<{ name: string; kind: "CHECK" | "ASSUME"; expr: string }>;
+  orderBy?: string;
+  primaryKey?: string;
+  partitionBy?: string;
+  sampleBy?: string;
+  ttl?: string;
+  settings?: Record<string, string>;
+  orReplace?: boolean;
+}
+
+export interface ViewObject extends OutputObject {
+  columns: ColumnDef[];
+  to?: string;
+  select: string;
+  lineage: Array<{ output: string; expr: string; from: Array<string | null> }>;
+  security?: string;
+}
+
+export const isTable = (o: OutputObject): o is TableObject => o.type === "ClickHouse::Table";
+export const isMaterializedView = (o: OutputObject): o is ViewObject => o.type === "ClickHouse::MaterializedView";
+export const isAnyView = (o: OutputObject): o is ViewObject =>
+  o.type === "ClickHouse::View" || o.type === "ClickHouse::MaterializedView";
+
+export function tablesOf(ctx: PostSynthContext): TableObject[] {
+  return clickhouseObjects(ctx).filter(isTable);
+}
+
+export function viewsOf(ctx: PostSynthContext): ViewObject[] {
+  return clickhouseObjects(ctx).filter(isAnyView);
+}
+
+/** 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;
+}
+
+/**
+ * The engine's own arguments, after the ZooKeeper path and replica name a
+ * `Replicated*` engine may lead with.
+ */
+export function engineArguments(engine: EngineDef): string[] {
+  const args = engine.args ?? [];
+  if (baseEngineName(engine) !== engine.name && args.length >= 2 && /^['{]/.test(args[0]!.trim())) return args.slice(2);
+  return args;
+}
+
+/** 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;
+}
+
+const WORDS = new Set(
+  (
+    "AS AND OR NOT IN IS NULL LIKE ILIKE BETWEEN CASE WHEN THEN ELSE END ASC DESC INTERVAL DISTINCT TRUE FALSE " +
+    "SECOND MINUTE HOUR DAY WEEK MONTH QUARTER YEAR NANOSECOND MICROSECOND MILLISECOND CAST"
+  ).split(" "),
+);
+
+/** Names an expression mentions as columns: identifiers that are not calls, literals or keywords. */
+export function mentionedNames(expr: string): string[] {
+  const names: string[] = [];
+  const re = /'(?:[^'\\]|\\.)*'|`((?:[^`]|``)*)`|"((?:[^"]|"")*)"|\b([A-Za-z_][A-Za-z0-9_]*)\b(\s*\()?|\d[\w.]*/g;
+  let m: RegExpExecArray | null;
+  let afterDot = false;
+  let last = 0;
+  while ((m = re.exec(expr)) !== null) {
+    afterDot = /\.\s*$/.test(expr.slice(last, m.index));
+    last = m.index + m[0].length;
+    const name = m[1] ?? m[2] ?? m[3];
+    if (name === undefined || m[4] !== undefined || afterDot) continue;
+    if (m[3] !== undefined && WORDS.has(m[3].toUpperCase())) continue;
+    names.push(name.replace(/``|""/g, (x) => x[0]!));
+  }
+  return names;
+}
+
+/** 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());
+
+export function columnByName(table: { columns: ColumnDef[] }, name: string): ColumnDef | undefined {
+  return table.columns.find((c) => c.name === name);
+}
+
+/** A check over the build's ClickHouse objects, so each check file holds its rule. */
+export function checkOf(
+  meta: { id: string; description: string },
+  run: (ctx: PostSynthContext, report: (d: Omit<PostSynthDiagnostic, "checkId" | "lexicon">) => void) => void,
+): PostSynthCheck {
+  return {
+    ...meta,
+    check(ctx) {
+      const out: PostSynthDiagnostic[] = [];
+      run(ctx, (d) => out.push({ checkId: meta.id, lexicon: "sql", ...d }));
+      return out;
+    },
+  };
+}
+
+/** The objects by export name and by SQL name, to resolve a `TO` target. */
+export function resolveObject(ctx: PostSynthContext, ref: string): OutputObject | undefined {
+  const all = clickhouseObjects(ctx);
+  return all.find((o) => o.export === ref) ?? all.find((o) => o.sqlName === ref || o.name === ref);
+}
+
+/** The codec names in a CODEC(...) list: `Delta, ZSTD(3)` is Delta and ZSTD. */
+export function codecNames(codec: string): string[] {
+  return splitTop(codec)
+    .map((c) => /^[A-Za-z_][\w]*/.exec(c.trim())?.[0])
+    .filter((n): n is string => n !== undefined);
+}

package/src/lint/post-synth/index.ts

@@ -0,0 +1,81 @@
+// Code generated by chant generate. DO NOT EDIT.
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import { sqlch101 } from "./sqlch101";
+import { sqlch102 } from "./sqlch102";
+import { sqlch103 } from "./sqlch103";
+import { sqlch104 } from "./sqlch104";
+import { sqlch105 } from "./sqlch105";
+import { sqlch106 } from "./sqlch106";
+import { sqlch107 } from "./sqlch107";
+import { sqlch108 } from "./sqlch108";
+import { sqlch109 } from "./sqlch109";
+import { sqlch110 } from "./sqlch110";
+import { sqlch111 } from "./sqlch111";
+import { sqlch112 } from "./sqlch112";
+import { sqlch113 } from "./sqlch113";
+import { sqlch114 } from "./sqlch114";
+import { sqlch115 } from "./sqlch115";
+import { sqlch116 } from "./sqlch116";
+import { sqlch117 } from "./sqlch117";
+import { sqlch118 } from "./sqlch118";
+import { sqlch119 } from "./sqlch119";
+import { sqlch120 } from "./sqlch120";
+import { sqlpg101 } from "./sqlpg101";
+import { sqlpg102 } from "./sqlpg102";
+import { sqlpg103 } from "./sqlpg103";
+import { sqlpg104 } from "./sqlpg104";
+import { sqlpg105 } from "./sqlpg105";
+import { sqlpg106 } from "./sqlpg106";
+import { sqlpg107 } from "./sqlpg107";
+import { sqlpg108 } from "./sqlpg108";
+import { sqlpg109 } from "./sqlpg109";
+import { sqlpg110 } from "./sqlpg110";
+import { sqlpg111 } from "./sqlpg111";
+import { sqlpg112 } from "./sqlpg112";
+import { sqlpg113 } from "./sqlpg113";
+import { sqlpg114 } from "./sqlpg114";
+import { sqlpg115 } from "./sqlpg115";
+import { sqlpg116 } from "./sqlpg116";
+import { sqlpg117 } from "./sqlpg117";
+import { sqlpg118 } from "./sqlpg118";
+
+export const postSynthChecks: PostSynthCheck[] = [
+  sqlch101,
+  sqlch102,
+  sqlch103,
+  sqlch104,
+  sqlch105,
+  sqlch106,
+  sqlch107,
+  sqlch108,
+  sqlch109,
+  sqlch110,
+  sqlch111,
+  sqlch112,
+  sqlch113,
+  sqlch114,
+  sqlch115,
+  sqlch116,
+  sqlch117,
+  sqlch118,
+  sqlch119,
+  sqlch120,
+  sqlpg101,
+  sqlpg102,
+  sqlpg103,
+  sqlpg104,
+  sqlpg105,
+  sqlpg106,
+  sqlpg107,
+  sqlpg108,
+  sqlpg109,
+  sqlpg110,
+  sqlpg111,
+  sqlpg112,
+  sqlpg113,
+  sqlpg114,
+  sqlpg115,
+  sqlpg116,
+  sqlpg117,
+  sqlpg118,
+];

package/src/lint/post-synth/post-synth.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "vitest";
+import { makePostSynthCtx } from "@intentius/chant-test-utils";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { sqlSerializer } from "../../serializer";
+import { database, table } from "../../clickhouse/entities";
+import { sqlch101 } from "./sqlch101";
+
+function ctxFor(entities: Array<[string, unknown]>) {
+  const out = sqlSerializer.serialize(new Map(entities as never)) as SerializerResult;
+  return makePostSynthCtx("sql", out.primary);
+}
+
+describe("SQLCH101: an engine the pinned server does not have", () => {
+  test("a misspelled table engine is reported against the object", () => {
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = MergTree ORDER BY a`;
+    const diags = sqlch101.check(ctxFor([["t", t]]));
+    expect(diags).toHaveLength(1);
+    expect(diags[0]).toMatchObject({ checkId: "SQLCH101", severity: "error", entity: "t" });
+    expect(diags[0]!.message).toMatch(/"MergTree"/);
+  });
+
+  test("a database engine is checked against the database engines", () => {
+    const db = database`CREATE DATABASE d ENGINE = MergeTree`;
+    expect(sqlch101.check(ctxFor([["d", db]]))).toHaveLength(1);
+  });
+
+  test("known engines, and an object with no engine, are clean", () => {
+    const t = table`CREATE TABLE t (a UInt8) ENGINE = ReplacingMergeTree ORDER BY a`;
+    const db = database`CREATE DATABASE d ENGINE = Atomic`;
+    const bare = database`CREATE DATABASE e`;
+    expect(sqlch101.check(ctxFor([["t", t], ["d", db], ["e", bare]]))).toEqual([]);
+  });
+});

package/src/lint/post-synth/postgres-audit-entries.ts

@@ -0,0 +1,29 @@
+/**
+ * Audit metadata for the Postgres post-synth checks (SQLPG1xx). Spread into
+ * `sqlAuditCatalog` by ../audit-catalog.ts. Deprecation checks are filed under
+ * best-practice or correctness: the audit categories have no deprecation of
+ * their own.
+ */
+
+import { auditRule, type RuleMeta } from "@intentius/chant/audit/catalog";
+
+export const postgresPostSynthAuditEntries: Record<string, RuleMeta> = {
+  SQLPG101: auditRule("SQLPG101", "merge-worthy", "guidance", "A table declares no primary key", "Add a primary key, or a UNIQUE constraint over NOT NULL columns.", { category: "best-practice" }),
+  SQLPG102: auditRule("SQLPG102", "report-only", "guidance", "A foreign key's referencing columns have no index", "Create an index whose leading columns are the foreign key's columns.", { category: "best-practice" }),
+  SQLPG103: auditRule("SQLPG103", "report-only", "guidance", "A serial column where an identity column is preferred", "Declare the column GENERATED ALWAYS AS IDENTITY.", { category: "best-practice" }),
+  SQLPG104: auditRule("SQLPG104", "report-only", "guidance", "A timestamp column without time zone", "Use timestamptz.", { category: "correctness" }),
+  SQLPG105: auditRule("SQLPG105", "report-only", "guidance", "A json column where jsonb fits", "Use jsonb unless the exact text must be kept.", { category: "best-practice" }),
+  SQLPG106: auditRule("SQLPG106", "report-only", "guidance", "A char(n) column", "Use text, or varchar(n) for a length rule.", { category: "best-practice" }),
+  SQLPG107: auditRule("SQLPG107", "report-only", "guidance", "A money column", "Use numeric(p, s) and a currency column.", { category: "correctness" }),
+  SQLPG108: auditRule("SQLPG108", "report-only", "guidance", "A varchar(n) column with a habitual length limit", "Use text, with a CHECK where the length is a rule.", { category: "best-practice" }),
+  SQLPG109: auditRule("SQLPG109", "report-only", "guidance", "An index duplicates a constraint or another index", "Drop the duplicate index.", { category: "best-practice" }),
+  SQLPG110: auditRule("SQLPG110", "report-only", "guidance", "A btree index is a prefix of another index", "Drop the prefix index; the wider one serves the same queries.", { category: "best-practice" }),
+  SQLPG111: auditRule("SQLPG111", "report-only", "guidance", "A materialized view has no unique index, so it cannot refresh concurrently", "Add a unique index over plain columns.", { category: "correctness" }),
+  SQLPG112: auditRule("SQLPG112", "report-only", "guidance", "A secret- or PII-named column with no comment on it or its table", "Add a COMMENT saying what it holds and how it is protected.", { category: "security" }),
+  SQLPG113: auditRule("SQLPG113", "report-only", "guidance", "An object is in the public schema though the project declares schemas", "Qualify the object with a declared schema.", { category: "best-practice" }),
+  SQLPG114: auditRule("SQLPG114", "merge-worthy", "guidance", "A storage parameter the object's kind or the target major does not accept", "Fix the parameter name, or use one from the target major's catalog.", { category: "correctness" }),
+  SQLPG115: auditRule("SQLPG115", "report-only", "guidance", "A feature newer than the target major", "Avoid the feature, or raise sql.postgresMajor.", { category: "correctness" }),
+  SQLPG116: auditRule("SQLPG116", "merge-worthy", "guidance", "An extension the target major no longer ships", "Remove the extension, or set sql.postgresMajor to an older major.", { category: "best-practice" }),
+  SQLPG117: auditRule("SQLPG117", "report-only", "guidance", "A view without security_invoker runs with its owner's privileges", "Set security_invoker = true in the view's WITH options.", { category: "security" }),
+  SQLPG118: auditRule("SQLPG118", "report-only", "guidance", "A table uses INHERITS where declarative partitioning replaced it", "Use PARTITION BY and PARTITION OF.", { category: "best-practice" }),
+};