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

package/dist/rules/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/dist/rules/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" }),
+};

package/dist/rules/postgres-helpers.ts

@@ -0,0 +1,126 @@
+/**
+ * Reading the Postgres objects in the sql build output for post-synth checks:
+ * typed views of the serialized objects and the small scanners the checks
+ * share. Expressions are kept as written; the scanners answer narrow questions
+ * ("is this a bare column"), not what an expression evaluates to.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { POSTGRES_MAJORS, VERSION_RANGES } from "../../generated/postgres";
+import type { VersionRange } from "../../postgres/catalog-types";
+import type { ColumnDef, KeyDef } from "../../postgres/entities";
+import { postgresMajorOf, postgresObjects, type OutputObject } from "./sql-helpers";
+
+export interface PgTable extends OutputObject {
+  sqlName: string;
+  like: string[];
+  schema?: string;
+  comment?: string;
+  columns: Array<ColumnDef & { comment?: string }>;
+  primaryKey?: KeyDef;
+  uniques: KeyDef[];
+  checks: Array<{ name?: string; expr: string; notEnforced?: boolean }>;
+  foreignKeys: Array<{ name?: string; columns: string[]; refTable: string; refColumns: string[] }>;
+  exclusions: unknown[];
+  inherits: unknown[];
+  partitionOf?: unknown;
+  ofType?: unknown;
+  persistence?: string;
+  with?: string;
+}
+
+export interface PgIndex extends OutputObject {
+  sqlName: string;
+  schema?: string;
+  table: string;
+  tableName: string;
+  unique?: boolean;
+  method?: string;
+  elements: Array<{ expr: string; column?: string }>;
+  include?: string;
+  where?: string;
+  with?: string;
+}
+
+export interface PgView extends OutputObject {
+  sqlName: string;
+  schema?: string;
+  query: string;
+  with?: string;
+}
+
+export const isTable = (o: OutputObject): o is PgTable => o.type === "Postgres::Table";
+export const isIndex = (o: OutputObject): o is PgIndex => o.type === "Postgres::Index";
+export const isView = (o: OutputObject): o is PgView => o.type === "Postgres::View";
+export const isMaterializedView = (o: OutputObject): o is PgView => o.type === "Postgres::MaterializedView";
+
+export const tablesOf = (ctx: PostSynthContext): PgTable[] => postgresObjects(ctx).filter(isTable);
+export const indexesOf = (ctx: PostSynthContext): PgIndex[] => postgresObjects(ctx).filter(isIndex);
+
+/** The major the build targets (`postgresMajor` in the output), else the newest pinned. */
+export const targetMajor = (ctx: PostSynthContext): number => postgresMajorOf(ctx, PINNED_MAJOR);
+
+/** The newest and oldest majors the lexicon carries a catalog for. */
+export const PINNED_MAJOR: number = POSTGRES_MAJORS[POSTGRES_MAJORS.length - 1]!;
+export const OLDEST_MAJOR: number = POSTGRES_MAJORS[0]!;
+
+/** The version range the generated catalog records for `name` in `table`, if it is not in every major. */
+export function rangeOf(table: keyof typeof VERSION_RANGES, name: string): VersionRange | undefined {
+  return (VERSION_RANGES[table] as Record<string, VersionRange | undefined>)[name];
+}
+
+/** A column type's leading words, lower-cased, without a length or array suffix: `timestamp(3)[]` is `timestamp`. */
+export function baseType(type: string | undefined): string {
+  return (type ?? "").toLowerCase().replace(/\[.*$/, "").replace(/\(.*?\)/g, "").replace(/\s+/g, " ").trim();
+}
+
+/** The `name = value` pairs of a `(a = 1, b)` storage parameter list, names lower-cased. */
+export function storageParams(text: string | undefined): Map<string, string> {
+  const out = new Map<string, string>();
+  const inner = (text ?? "").trim().replace(/^\(/, "").replace(/\)$/, "");
+  for (const part of inner.split(",")) {
+    const [k, ...v] = part.split("=");
+    const name = k!.trim().toLowerCase();
+    if (name) out.set(name, v.join("=").trim());
+  }
+  return out;
+}
+
+/** The leading bare-column elements of an index, in order; stops at the first expression. */
+export function leadingColumns(index: PgIndex): string[] {
+  const out: string[] = [];
+  for (const e of index.elements) {
+    if (!e.column) break;
+    out.push(e.column);
+  }
+  return out;
+}
+
+/** A check over the build's Postgres 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;
+    },
+  };
+}
+
+/** A table that owns its columns: not a partition, not typed (`OF type`), not temporary. */
+export const ownsColumns = (t: PgTable): boolean => t.partitionOf === undefined && t.ofType === undefined && t.persistence !== "temporary";
+
+/** The catalog's relation kind for a storage-parameter list on this object, as `STORAGE_PARAMETERS.targets` spells it. */
+export function storageTarget(o: OutputObject): string | undefined {
+  switch (o.type) {
+    case "Postgres::Table": return "table";
+    case "Postgres::View": return "view";
+    case "Postgres::MaterializedView": return "materialized view";
+    case "Postgres::Index": return `index:${(o.method as string | undefined) ?? "btree"}`;
+    default: return undefined;
+  }
+}

package/dist/rules/postgres-templates.ts

@@ -0,0 +1,36 @@
+/**
+ * Finding the Postgres tags in a source file, for the source-level rules. A
+ * tag is Postgres's because of the module it is imported from: the
+ * `/postgres` subpath, or the package root for the tags whose names
+ * ClickHouse does not export (the root's `table` and `view` are
+ * ClickHouse's).
+ */
+
+import type * as ts from "typescript";
+import { tokenize, type Token } from "../../postgres/tokens";
+import type { PostgresTag } from "../../postgres/entities";
+import { findSqlTemplates, type FoundTemplate, type TemplateSource } from "../../core/find-templates";
+
+export { templatePosition, tokenPosition } from "../../core/find-templates";
+
+export const POSTGRES_TEMPLATE_SOURCES: readonly TemplateSource<PostgresTag>[] = [
+  {
+    dialect: "postgres",
+    modules: ["@intentius/chant-lexicon-sql/postgres"],
+    tags: ["schema", "table", "index", "view", "sequence", "type", "domain", "extension"],
+  },
+  {
+    dialect: "postgres",
+    modules: ["@intentius/chant-lexicon-sql"],
+    tags: ["schema", "index", "sequence", "type", "domain", "extension"],
+  },
+];
+
+export type PostgresFoundTemplate = FoundTemplate<PostgresTag>;
+
+/** Every Postgres template in the file. */
+export function findPostgresTemplates(source: ts.SourceFile): PostgresFoundTemplate[] {
+  return findSqlTemplates(source, POSTGRES_TEMPLATE_SOURCES);
+}
+
+export const postgresTokensOf = (found: PostgresFoundTemplate): Token[] => tokenize(found.parts);

package/dist/rules/sql-helpers.ts

@@ -0,0 +1,53 @@
+/**
+ * Reading the sql lexicon's build output in a post-synth check: the JSON
+ * document the serializer writes (`dialect`, `applyOrder`, `objects`).
+ */
+
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+
+export interface OutputObject {
+  export: string;
+  type: string;
+  name: string;
+  database?: string;
+  engine?: { name: string; args?: string[] };
+  [key: string]: unknown;
+}
+
+/** Every schema object in the build's sql output, ClickHouse dialect. */
+export function clickhouseObjects(ctx: PostSynthContext): OutputObject[] {
+  const out: OutputObject[] = [];
+  for (const doc of ctx.docs ?? []) {
+    if (doc.error || doc.lexicon !== "sql" || doc.format !== "json") continue;
+    const value = doc.value as { dialect?: unknown; objects?: unknown };
+    if (value?.dialect !== "clickhouse" || !Array.isArray(value.objects)) continue;
+    out.push(...(value.objects as OutputObject[]));
+  }
+  return out;
+}
+
+/** Every schema object in the build's sql output, Postgres dialect. */
+export function postgresObjects(ctx: PostSynthContext): OutputObject[] {
+  const out: OutputObject[] = [];
+  for (const doc of ctx.docs ?? []) {
+    if (doc.error || doc.lexicon !== "sql" || doc.format !== "json") continue;
+    const value = doc.value as { dialect?: unknown; objects?: unknown };
+    if (value?.dialect !== "postgres" || !Array.isArray(value.objects)) continue;
+    out.push(...(value.objects as OutputObject[]));
+  }
+  return out;
+}
+
+/**
+ * The Postgres major the build targets, as the serializer recorded it
+ * (`sql.postgresMajor`, else the newest pinned major). `fallback` answers for
+ * output that carries none.
+ */
+export function postgresMajorOf(ctx: PostSynthContext, fallback: number): number {
+  for (const doc of ctx.docs ?? []) {
+    if (doc.error || doc.lexicon !== "sql" || doc.format !== "json") continue;
+    const value = doc.value as { dialect?: unknown; postgresMajor?: unknown };
+    if (value?.dialect === "postgres" && typeof value.postgresMajor === "number") return value.postgresMajor;
+  }
+  return fallback;
+}

package/dist/rules/sqlch001.ts

@@ -0,0 +1,53 @@
+import type { LintContext, LintDiagnostic, LintRule } from "@intentius/chant/lint/rule";
+import { parseCreate } from "../../clickhouse/parser";
+import { SqlSyntaxError } from "../../clickhouse/tokens";
+import { findTemplates, templatePosition, tokensOf } from "./templates";
+
+const STATEMENT: Record<string, string> = { database: "CREATE DATABASE", table: "CREATE TABLE", view: "CREATE VIEW" };
+
+/**
+ * SQLCH001: the DDL in a `database`, `table` or `view` template does not parse, or holds another statement than its tag.
+ *
+ * The same parse runs when the build calls the tag, and fails the build there.
+ * This rule reports it in the editor and in `chant lint`, at the token, before
+ * anything is built. Interpolations are references here, since lint cannot
+ * know their values, so an error inside text a string interpolation supplies
+ * is left to the build.
+ */
+export const sqlch001: LintRule = {
+  id: "SQLCH001",
+  severity: "error",
+  category: "correctness",
+  description: "ClickHouse DDL in a database, table or view template does not parse",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const source = context.sourceFile;
+    const out: LintDiagnostic[] = [];
+    for (const found of findTemplates(source)) {
+      let tokens;
+      try {
+        tokens = tokensOf(found);
+        const node = parseCreate(tokens);
+        if (node.statement !== found.tag) {
+          out.push({
+            ruleId: "SQLCH001",
+            severity: "error",
+            message: `${found.tag}\`...\` holds a ${STATEMENT[node.statement]}; use the ${node.statement} tag`,
+            file: context.filePath,
+            ...templatePosition(source, found, 0, 0),
+          });
+        }
+      } catch (err) {
+        if (!(err instanceof SqlSyntaxError)) throw err;
+        out.push({
+          ruleId: "SQLCH001",
+          severity: "error",
+          message: `ClickHouse DDL does not parse: ${err.message}`,
+          file: context.filePath,
+          ...templatePosition(source, found, err.part, err.offset),
+        });
+      }
+    }
+    return out;
+  },
+};

package/dist/rules/sqlch002.ts

@@ -0,0 +1,115 @@
+import type { LintContext, LintDiagnostic, LintRule } from "@intentius/chant/lint/rule";
+import { parseCreate, unquote, type ColumnNode, type CreateNode, type Span } from "../../clickhouse/parser";
+import { isTrivia, SqlSyntaxError, type Token } from "../../clickhouse/tokens";
+import { findTemplates, tokenPosition, tokensOf } from "./templates";
+
+/** The column's type, as written, reads `Nullable(...)`, also inside `LowCardinality(...)`. */
+function isNullable(tokens: Token[], c: ColumnNode): boolean {
+  if (c.nullable === true) return true;
+  if (!c.type) return false;
+  const words = tokens.slice(c.type.from, c.type.to).filter((t) => t.kind === "ident").map((t) => t.text.toLowerCase());
+  return words[0] === "nullable" || (words[0] === "lowcardinality" && words[1] === "nullable");
+}
+
+/**
+ * The column names a key names as a key part: bare, or inside the key's tuple
+ * parentheses, not an argument of a function (`ifNull(a, '')` makes a
+ * non-Nullable key part of a Nullable column) and not a qualified part.
+ */
+function keyColumns(tokens: Token[], span: Span): Array<{ name: string; token: Token }> {
+  const sig = tokens.slice(span.from, span.to).filter((t) => !isTrivia(t));
+  const out: Array<{ name: string; token: Token }> = [];
+  const frames: boolean[] = []; // true for a function call's parentheses
+  sig.forEach((t, i) => {
+    const prev = sig[i - 1];
+    if (t.kind === "punct" && t.text === "(") {
+      frames.push(prev !== undefined && (prev.kind === "ident" || prev.kind === "qident"));
+      return;
+    }
+    if (t.kind === "punct" && t.text === ")") {
+      frames.pop();
+      return;
+    }
+    if (t.kind !== "ident" && t.kind !== "qident") return;
+    if (frames.includes(true)) return;
+    const next = sig[i + 1];
+    if (next?.kind === "punct" && next.text === "(") return;
+    if (prev?.kind === "punct" && prev.text === ".") return;
+    out.push({ name: unquote(t.text), token: t });
+  });
+  return out;
+}
+
+function allowsNullableKey(tokens: Token[], node: CreateNode): boolean {
+  if (node.statement === "database" || !node.settings) return false;
+  const s = node.settings.find((x) => x.key === "allow_nullable_key");
+  if (!s) return false;
+  const v = tokens.slice(s.value.from, s.value.to).map((t) => t.text).join("").trim().toLowerCase().replace(/'/g, "");
+  return v === "1" || v === "true";
+}
+
+/**
+ * SQLCH002: a `Nullable` column in a table's sort key or primary key.
+ *
+ * ClickHouse refuses to create the table ("Sorting key contains nullable
+ * columns") unless the table sets `allow_nullable_key = 1`, and with it a
+ * `NULL` sorts as a value of its own. The rule reads the types written in the
+ * column list; a key over a column of an inferred type is left to the server.
+ */
+export const sqlch002: LintRule = {
+  id: "SQLCH002",
+  severity: "error",
+  category: "correctness",
+  description: "A Nullable column in a ClickHouse sort key or primary key",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const source = context.sourceFile;
+    const out: LintDiagnostic[] = [];
+    for (const found of findTemplates(source)) {
+      const tokens = tokensOf(found);
+      let node: CreateNode;
+      try {
+        node = parseCreate(tokens);
+      } catch (err) {
+        if (err instanceof SqlSyntaxError) continue; // SQLCH001 reports it
+        throw err;
+      }
+      if (node.statement === "database" || allowsNullableKey(tokens, node)) continue;
+      const nullable = new Set(node.columns.filter((c) => c.name && isNullable(tokens, c)).map((c) => c.name));
+      if (nullable.size === 0) continue;
+      const reported = new Set<string>();
+      for (const [clause, span] of [
+        ["sort key", node.orderBy],
+        ["primary key", node.primaryKey],
+      ] as const) {
+        if (!span) continue;
+        for (const { name, token } of keyColumns(tokens, span)) {
+          if (!nullable.has(name) || reported.has(`${clause}:${name}`)) continue;
+          reported.add(`${clause}:${name}`);
+          out.push({
+            ruleId: "SQLCH002",
+            severity: "error",
+            message:
+              `column "${name}" is Nullable and is in the ${clause}; ClickHouse refuses this unless the table ` +
+              "sets allow_nullable_key = 1. Make the column non-Nullable (a default such as '' or 0 in place of NULL), " +
+              "or drop it from the key",
+            file: context.filePath,
+            ...tokenPosition(source, found, token),
+          });
+        }
+      }
+      for (const c of node.columns) {
+        if (c.primaryKey && nullable.has(c.name)) {
+          out.push({
+            ruleId: "SQLCH002",
+            severity: "error",
+            message: `column "${c.name}" is Nullable and is declared PRIMARY KEY; ClickHouse refuses this unless the table sets allow_nullable_key = 1`,
+            file: context.filePath,
+            ...tokenPosition(source, found, tokens[c.nameSpan.from]!),
+          });
+        }
+      }
+    }
+    return out;
+  },
+};