@intentius/chant-lexicon-sql 0.124.12 → 0.124.14

package/src/read/clickhouse.ts

@@ -0,0 +1,137 @@
+/**
+ * The ClickHouse half of the public read API (`../read.ts`): the build's
+ * tables, columns, sort keys, skip indexes, engines and views as typed values,
+ * built from the serialized output. The lexicon's post-synth checks read the
+ * same values (`../lint/post-synth/clickhouse-helpers.ts`).
+ */
+
+import { relationKey } from "../core/typed";
+import type { ColumnDef } from "../clickhouse/entities";
+import { bareName, baseEngineName, isMergeTree, isNullableType, keyElements, typeFamily, unwrapType } from "../clickhouse/expressions";
+import { dialectObjects, type ClickHouseTableJson, type ClickHouseViewJson, type SqlObjectJson, type SqlReadSource } from "./objects";
+
+/** A column of a ClickHouse table or view, as declared, with what follows from the declaration. */
+export interface ClickHouseColumnInfo extends ColumnDef {
+  /** Whether the column can hold NULL: its type is `Nullable(...)` (inside `LowCardinality` too), or it is declared `NULL`. */
+  nullable: boolean;
+  /** `LowCardinality(...)`. */
+  lowCardinality: boolean;
+  /** The type without its `Nullable` and `LowCardinality` wrappers, as written: `DateTime64(3, 'UTC')`. */
+  baseType?: string;
+  /** The type family's canonical name, as the pinned server's catalog has it: `BIGINT UNSIGNED` is `UInt64`, `DateTime64(3)` is `DateTime64`. */
+  family?: string;
+  /** A bare element of the table's sort key (`ORDER BY`). */
+  inSortKey: boolean;
+}
+
+/** A ClickHouse table, as declared: its columns, engine, keys and skip indexes. */
+export interface ClickHouseTableInfo extends Omit<ClickHouseTableJson, "columns"> {
+  /** `database.name` when the DDL qualifies it, else the name: the table's key in `SqlSchema`. */
+  qualifiedName: string;
+  columns: ClickHouseColumnInfo[];
+  /** The engine without a `Replicated` prefix: `ReplicatedReplacingMergeTree` is `ReplacingMergeTree`. */
+  engineFamily?: string;
+  /** A MergeTree family engine, replicated or not. */
+  mergeTree: boolean;
+  /** The `ORDER BY` elements, as written, without `ASC`/`DESC`; empty for `tuple()` or none. */
+  sortKey: string[];
+  /** The `PRIMARY KEY` elements, else the sort key's, which is what ClickHouse uses when none is written. */
+  primaryKeyElements: string[];
+  /** The column named `name`, if the table declares one. */
+  column(name: string): ClickHouseColumnInfo | undefined;
+}
+
+/** A view or materialized view, with the names of its output columns. */
+export interface ClickHouseViewInfo extends Omit<ClickHouseViewJson, "columns"> {
+  qualifiedName: string;
+  materialized: boolean;
+  columns: ClickHouseColumnInfo[];
+  /** The declared columns, else the outputs of the query's select list. */
+  outputs: string[];
+}
+
+/** What a ClickHouse build declares. */
+export interface ClickHouseRead {
+  dialect: "clickhouse";
+  tables: ClickHouseTableInfo[];
+  views: ClickHouseViewInfo[];
+  /** Every serialized object, databases, dictionaries, users and grants included, in apply order. */
+  objects: SqlObjectJson[];
+  /** A table by export name, `database.name`, or name. */
+  table(ref: string): ClickHouseTableInfo | undefined;
+}
+
+function columnInfo(c: ColumnDef, sortKey: ReadonlySet<string>): ClickHouseColumnInfo {
+  const inner = /^LowCardinality\s*\(/i.test((c.type ?? "").trim());
+  const nullable = c.nullable === true || isNullableType(c.type) || (inner && isNullableType(unwrapLowCardinality(c.type!)));
+  return {
+    ...c,
+    nullable,
+    lowCardinality: inner,
+    ...(c.type !== undefined ? { baseType: unwrapType(c.type), family: typeFamily(c.type) } : {}),
+    inSortKey: sortKey.has(c.name),
+  };
+}
+
+function unwrapLowCardinality(type: string): string {
+  return type.trim().replace(/^LowCardinality\s*\(([\s\S]*)\)$/i, "$1").trim();
+}
+
+function build(objects: SqlObjectJson[]): ClickHouseRead {
+  const tables = objects
+    .filter((o) => o.type === "ClickHouse::Table")
+    .map((o): ClickHouseTableInfo => {
+      const t = o as unknown as ClickHouseTableJson;
+      const sortKey = t.orderBy ? keyElements(t.orderBy) : [];
+      const bare = new Set(sortKey.map(bareName).filter((n): n is string => n !== undefined));
+      const columns = (t.columns ?? []).map((c) => columnInfo(c, bare));
+      return {
+        ...t,
+        qualifiedName: relationKey(t),
+        columns,
+        ...(t.engine ? { engineFamily: baseEngineName(t.engine) } : {}),
+        mergeTree: isMergeTree(t.engine),
+        sortKey,
+        primaryKeyElements: t.primaryKey ? keyElements(t.primaryKey) : sortKey,
+        column: (name) => columns.find((c) => c.name === name),
+      };
+    });
+  const views = objects
+    .filter((o) => o.type === "ClickHouse::View" || o.type === "ClickHouse::MaterializedView")
+    .map((o): ClickHouseViewInfo => {
+      const v = o as unknown as ClickHouseViewJson;
+      const columns = (v.columns ?? []).map((c) => columnInfo(c, new Set()));
+      return {
+        ...v,
+        qualifiedName: relationKey(v),
+        materialized: v.type === "ClickHouse::MaterializedView",
+        columns,
+        outputs: columns.length > 0 ? columns.map((c) => c.name) : (v.lineage ?? []).map((e) => e.output),
+      };
+    });
+  return {
+    dialect: "clickhouse",
+    tables,
+    views,
+    objects,
+    table: (ref) => tables.find((t) => t.export === ref) ?? tables.find((t) => t.qualifiedName === ref) ?? tables.find((t) => t.name === ref),
+  };
+}
+
+const cache = new WeakMap<object, ClickHouseRead>();
+
+/**
+ * What a ClickHouse build declares, read from a post-synth context's `docs`
+ * (a `lint.policies` check's `ctx`), or from the serialized output document
+ * itself. Empty when the build has no ClickHouse output. The result is cached
+ * per context; treat it as read-only.
+ */
+export function readClickHouse(source: SqlReadSource | { dialect: string; objects: unknown[] }): ClickHouseRead {
+  if ("objects" in source) return build(source.dialect === "clickhouse" ? (source.objects as SqlObjectJson[]) : []);
+  const key = source.docs;
+  const hit = key ? cache.get(key) : undefined;
+  if (hit) return hit;
+  const read = build(dialectObjects(source, "clickhouse"));
+  if (key) cache.set(key, read);
+  return read;
+}

package/src/read/objects.ts

@@ -0,0 +1,137 @@
+/**
+ * The sql build output as the serializer writes it (`../serializer.ts`): one
+ * JSON document per build with `dialect`, `applyOrder` and `objects`, each
+ * object its entity's props with the template source dropped, the DDL moved
+ * to the end, and every reference to another declared object written as that
+ * object's export name.
+ *
+ * This is the one place that finds those documents in a post-synth context.
+ * The public read API (`../read.ts`) and the lexicon's own post-synth checks
+ * (`../lint/post-synth/sql-helpers.ts`) both start here.
+ */
+
+import type { OutputDoc } from "@intentius/chant/lint/post-synth";
+import type * as ch from "../clickhouse/entities";
+import type * as pg from "../postgres/entities";
+
+/** What a reader takes: a post-synth context, or anything else carrying its `docs`. */
+export interface SqlReadSource {
+  readonly docs?: readonly OutputDoc[];
+}
+
+/** One build output document, as the serializer writes it. */
+export interface SqlOutputDocument {
+  dialect: "clickhouse" | "postgres";
+  /** Postgres only: the major the build targets (`sql.postgresMajor`, else the newest pinned). */
+  postgresMajor?: number;
+  applyOrder?: string[];
+  objects: SqlObjectJson[];
+}
+
+/** A reference to another declared object: its export name, or null when it is not one the build declares. */
+export type RefJson = string | null;
+
+/** The fields every serialized object has. */
+export interface SqlObjectBase {
+  /** The export name of the declaration. */
+  export: string;
+  /** The entity type: `Postgres::Table`, `ClickHouse::MaterializedView`, ... */
+  type: string;
+  /** The object's name in the database, unquoted. */
+  name: string;
+  /** The name it is referred to by in SQL: `name`, or `schema.name` / `database.name`. */
+  sqlName?: string;
+  /** The export names it must be created after. */
+  dependsOn?: string[];
+  /** The statements as they will be sent. */
+  ddl?: string;
+}
+
+/** Any serialized object: the common fields, and the rest of its props as written. */
+export interface SqlObjectJson extends SqlObjectBase {
+  [key: string]: unknown;
+}
+
+type Serialized<P> = Omit<P, "source" | "ddl"> & Omit<SqlObjectBase, "type"> & { sqlName: string; dependsOn: string[]; ddl: string };
+
+/** A lineage edge as written: the output column, its expression, and the `export.column` names it reads. */
+export interface LineageJson {
+  output: string;
+  expr: string;
+  from: Array<string | null>;
+}
+
+// ── Postgres ──────────────────────────────────────────────────────────
+
+export interface PostgresForeignKeyJson extends Omit<pg.ForeignKeyDef, "references"> {
+  /** The referenced table's export name, or null when the build does not declare it. */
+  references: RefJson;
+}
+
+export interface PostgresTableJson
+  extends Omit<Serialized<pg.TableProps>, "partitionOf" | "ofType" | "inherits" | "foreignKeys"> {
+  type: "Postgres::Table";
+  partitionOf?: RefJson;
+  ofType?: RefJson;
+  inherits: RefJson[];
+  foreignKeys: PostgresForeignKeyJson[];
+}
+
+export interface PostgresIndexJson extends Omit<Serialized<pg.IndexProps>, "table"> {
+  type: "Postgres::Index";
+  /** The indexed table's export name, or null when the build does not declare it. */
+  table: RefJson;
+}
+
+export interface PostgresViewJson extends Omit<Serialized<pg.ViewProps>, "reads" | "lineage"> {
+  type: "Postgres::View" | "Postgres::MaterializedView";
+  reads: RefJson[];
+  lineage: LineageJson[];
+}
+
+// ── ClickHouse ────────────────────────────────────────────────────────
+
+export interface ClickHouseTableJson extends Serialized<ch.TableProps> {
+  type: "ClickHouse::Table";
+}
+
+export interface ClickHouseViewJson extends Omit<Serialized<ch.ViewProps>, "to" | "reads" | "lineage"> {
+  type: "ClickHouse::View" | "ClickHouse::MaterializedView";
+  /** A materialized view's target: its export name when declared, else the name as written. */
+  to?: RefJson;
+  reads: RefJson[];
+  lineage: LineageJson[];
+}
+
+// ── Finding the documents ─────────────────────────────────────────────
+
+/** True for a value shaped like the serializer's document. */
+export function isSqlOutputDocument(value: unknown): value is SqlOutputDocument {
+  const v = value as { dialect?: unknown; objects?: unknown } | null;
+  return v !== null && typeof v === "object" && (v.dialect === "clickhouse" || v.dialect === "postgres") && Array.isArray(v.objects);
+}
+
+/** Every sql output document in the context, in output order. */
+export function sqlDocuments(source: SqlReadSource): SqlOutputDocument[] {
+  const out: SqlOutputDocument[] = [];
+  for (const doc of source.docs ?? []) {
+    if (doc.error || doc.lexicon !== "sql" || doc.format !== "json") continue;
+    if (isSqlOutputDocument(doc.value)) out.push(doc.value);
+  }
+  return out;
+}
+
+/** Every serialized object of one dialect, across the context's sql documents. */
+export function dialectObjects(source: SqlReadSource, dialect: SqlOutputDocument["dialect"]): SqlObjectJson[] {
+  const out: SqlObjectJson[] = [];
+  for (const doc of sqlDocuments(source)) if (doc.dialect === dialect) out.push(...doc.objects);
+  return out;
+}
+
+/** The Postgres major the build output records, else `fallback`. */
+export function recordedPostgresMajor(source: SqlReadSource, fallback: number): number {
+  for (const doc of sqlDocuments(source)) {
+    if (doc.dialect === "postgres" && typeof doc.postgresMajor === "number") return doc.postgresMajor;
+  }
+  return fallback;
+}

package/src/read/postgres.ts

@@ -0,0 +1,180 @@
+/**
+ * The Postgres half of the public read API (`../read.ts`): the build's
+ * tables, columns, keys, indexes and views as typed values, built from the
+ * serialized output. The lexicon's post-synth checks read the same values
+ * (`../lint/post-synth/postgres-helpers.ts`).
+ */
+
+import { POSTGRES_MAJORS } from "../generated/postgres";
+import { relationKey } from "../core/typed";
+import { parseType, projectFromObjects, resolveType, typeLabel, type PgProject } from "../lint/post-synth/postgres-names";
+import {
+  dialectObjects,
+  recordedPostgresMajor,
+  type PostgresIndexJson,
+  type PostgresTableJson,
+  type PostgresViewJson,
+  type SqlObjectJson,
+  type SqlReadSource,
+} from "./objects";
+import type { ColumnDef } from "../postgres/entities";
+
+/** A column of a Postgres table, as declared, with what follows from the declaration. */
+export interface PostgresColumnInfo extends ColumnDef {
+  /**
+   * Whether the column can hold NULL: false when it is `NOT NULL`, in the
+   * primary key, an identity column or a `serial`, true otherwise.
+   */
+  nullable: boolean;
+  /**
+   * The type's canonical name, without modifiers or array brackets: a
+   * built-in as Postgres's `format_type()` spells it (`timestamptz` is
+   * `timestamp with time zone`, `int8` and `bigserial` are `bigint`), a type
+   * the project declares by its SQL name, anything else as written, lower
+   * case. Undefined when the column has no type of its own (a partition, a
+   * typed table) or the type is not a plain name.
+   */
+  typeName?: string;
+  /** `text[]`, `integer ARRAY`. */
+  array: boolean;
+  /** One of the primary key's columns. */
+  inPrimaryKey: boolean;
+}
+
+/** A `CREATE INDEX`, with its table's export name and the columns it leads with. */
+export interface PostgresIndexInfo extends PostgresIndexJson {
+  /** The elements that are bare columns, in order, up to the first expression. */
+  columns: string[];
+}
+
+/** A Postgres table, as declared: its columns, keys, constraints and the indexes declared on it. */
+export interface PostgresTableInfo extends Omit<PostgresTableJson, "columns"> {
+  /** `schema.name` when the DDL qualifies it, else the name: the table's key in `SqlSchema`. */
+  qualifiedName: string;
+  columns: PostgresColumnInfo[];
+  /** The `CREATE INDEX` statements on this table (constraints' own indexes are `primaryKey` and `uniques`). */
+  indexes: PostgresIndexInfo[];
+  /** The column named `name`, if the table declares one. */
+  column(name: string): PostgresColumnInfo | undefined;
+}
+
+/** A view or materialized view, with the names of its output columns. */
+export interface PostgresViewInfo extends PostgresViewJson {
+  qualifiedName: string;
+  materialized: boolean;
+  /** The declared column list, else the outputs of the query's select list. */
+  outputs: string[];
+}
+
+/** What a Postgres build declares. */
+export interface PostgresRead {
+  dialect: "postgres";
+  /** The major the build targets. */
+  major: number;
+  tables: PostgresTableInfo[];
+  views: PostgresViewInfo[];
+  indexes: PostgresIndexInfo[];
+  /** Every serialized object, sequences, functions, roles and grants included, in apply order. */
+  objects: SqlObjectJson[];
+  /** A table by export name, `schema.name`, or name. */
+  table(ref: string): PostgresTableInfo | undefined;
+}
+
+const PINNED_MAJOR: number = POSTGRES_MAJORS[POSTGRES_MAJORS.length - 1]!;
+
+/** A column type's canonical name, array-ness and serial-ness against a project. */
+function typeOf(p: PgProject, text: string | undefined): { typeName?: string; array: boolean; serial: boolean } {
+  const t = parseType(text);
+  if (!t) return { ...(text ? { typeName: text.trim().toLowerCase() } : {}), array: false, serial: false };
+  const r = resolveType(p, t, { serial: true });
+  const typeName =
+    r.kind === "builtin" || r.kind === "absent" ? r.canonical : r.kind === "declared" ? String(r.object.sqlName ?? r.object.name) : typeLabel(t);
+  return { typeName, array: t.array, serial: r.kind === "builtin" && r.serial === true };
+}
+
+/**
+ * The canonical name of a Postgres type as written: `timestamptz` and
+ * `TIMESTAMP WITH TIME ZONE` are both `timestamp with time zone`, `int4` is
+ * `integer`. Compare a column's {@link PostgresColumnInfo.typeName} with it,
+ * so a rule does not depend on how the DDL spelled the type.
+ */
+export function canonicalPostgresType(text: string): string | undefined {
+  return typeOf(projectFromObjects([], PINNED_MAJOR), text).typeName;
+}
+
+function columnInfo(p: PgProject, c: ColumnDef, pk: ReadonlySet<string>): PostgresColumnInfo {
+  const { typeName, array, serial } = typeOf(p, c.type);
+  const inPrimaryKey = pk.has(c.name);
+  const nullable = !(c.notNull === true || inPrimaryKey || c.generated?.kind === "identity" || serial);
+  return { ...c, nullable, ...(typeName !== undefined ? { typeName } : {}), array, inPrimaryKey };
+}
+
+function indexInfo(i: PostgresIndexJson): PostgresIndexInfo {
+  const columns: string[] = [];
+  for (const e of i.elements ?? []) {
+    if (!e.column) break;
+    columns.push(e.column);
+  }
+  return { ...i, columns };
+}
+
+function build(objects: SqlObjectJson[], major: number): PostgresRead {
+  const p = projectFromObjects(objects, major);
+  const indexes = objects.filter((o) => o.type === "Postgres::Index").map((o) => indexInfo(o as unknown as PostgresIndexJson));
+  const tables = objects
+    .filter((o) => o.type === "Postgres::Table")
+    .map((o): PostgresTableInfo => {
+      const t = o as unknown as PostgresTableJson;
+      const pk = new Set(t.primaryKey?.columns ?? []);
+      const columns = (t.columns ?? []).map((c) => columnInfo(p, c, pk));
+      return {
+        ...t,
+        qualifiedName: relationKey(t),
+        columns,
+        indexes: indexes.filter((i) => i.table === t.export || i.tableName === t.sqlName),
+        column: (name) => columns.find((c) => c.name === name),
+      };
+    });
+  const views = objects
+    .filter((o) => o.type === "Postgres::View" || o.type === "Postgres::MaterializedView")
+    .map((o): PostgresViewInfo => {
+      const v = o as unknown as PostgresViewJson;
+      const declared = v.columns ?? [];
+      return {
+        ...v,
+        qualifiedName: relationKey(v),
+        materialized: v.type === "Postgres::MaterializedView",
+        outputs: declared.length > 0 ? [...declared] : (v.lineage ?? []).map((e) => e.output),
+      };
+    });
+  return {
+    dialect: "postgres",
+    major,
+    tables,
+    views,
+    indexes,
+    objects,
+    table: (ref) => tables.find((t) => t.export === ref) ?? tables.find((t) => t.qualifiedName === ref) ?? tables.find((t) => t.name === ref),
+  };
+}
+
+const cache = new WeakMap<object, PostgresRead>();
+
+/**
+ * What a Postgres build declares, read from a post-synth context's `docs`
+ * (a `lint.policies` check's `ctx`), or from the serialized output document
+ * itself. Empty when the build has no Postgres output. The result is cached
+ * per context; treat it as read-only.
+ */
+export function readPostgres(source: SqlReadSource | { dialect: string; objects: unknown[]; postgresMajor?: number }): PostgresRead {
+  if ("objects" in source) {
+    const objects = source.dialect === "postgres" ? (source.objects as SqlObjectJson[]) : [];
+    return build(objects, typeof source.postgresMajor === "number" ? source.postgresMajor : PINNED_MAJOR);
+  }
+  const key = source.docs;
+  const hit = key ? cache.get(key) : undefined;
+  if (hit) return hit;
+  const read = build(dialectObjects(source, "postgres"), recordedPostgresMajor(source, PINNED_MAJOR));
+  if (key) cache.set(key, read);
+  return read;
+}

package/src/read-policies.e2e.test.ts

@@ -0,0 +1,144 @@
+/**
+ * #3870: a project's own `lint.policies`, written against
+ * `@intentius/chant-lexicon-sql/read`, fail `chant lint` and `chant build` on
+ * a table that breaks them, and `tsc` checks the policy itself.
+ *
+ * Each case copies `examples/postgres-policies` into a temporary project that
+ * reaches the workspace packages through a `node_modules` link, as an
+ * installed project would.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { lintCommand } from "@intentius/chant/cli/commands/lint";
+import { buildCommand } from "@intentius/chant/cli/commands/build";
+import { ts } from "@intentius/chant/lint/typescript";
+import { sqlPlugin, sqlSerializer } from "@intentius/chant-lexicon-sql";
+
+const here = import.meta.dirname;
+const example = resolve(here, "..", "examples", "postgres-policies");
+const repoNodeModules = resolve(here, "..", "..", "..", "node_modules");
+
+let root: string;
+
+beforeEach(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), "chant-3870-")));
+  for (const f of ["chant.config.ts", "policies", "src"]) cpSync(join(example, f), join(root, f), { recursive: true });
+  symlinkSync(repoNodeModules, join(root, "node_modules"), "dir");
+  process.env.NO_COLOR = "1";
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+  delete process.env.NO_COLOR;
+});
+
+/** Drop `sessions.created_at` from the example's schema. */
+function breakSessions(): void {
+  const file = join(root, "src", "app.ts");
+  const text = readFileSync(file, "utf-8").replace(
+    "    account_id bigint NOT NULL REFERENCES ${accounts} (id),\n    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()\n",
+    "    account_id bigint NOT NULL REFERENCES ${accounts} (id)\n",
+  );
+  expect(text).not.toContain("TIMESTAMP WITH TIME ZONE");
+  writeFileSync(file, text);
+}
+
+const policyIds = (diags: Array<{ ruleId: string }>) => diags.map((d) => d.ruleId).filter((id) => id.startsWith("ORG-"));
+
+describe("project policies over the sql read API (#3870)", () => {
+  test("chant lint: the example is clean, and a table without created_at fails", async () => {
+    const clean = await lintCommand({ path: join(root, "src"), format: "stylish" });
+    expect(policyIds(clean.diagnostics), clean.output).toEqual([]);
+
+    breakSessions();
+    const result = await lintCommand({ path: join(root, "src"), format: "stylish" });
+    expect(result.success).toBe(false);
+    const diag = result.diagnostics.find((d) => d.ruleId === "ORG-CREATED-AT");
+    expect(diag, result.output).toBeDefined();
+    expect(diag!.severity).toBe("error");
+    expect(diag!.message).toContain("app.sessions has no created_at column");
+    expect(diag!.file).toBe(join(root, "src", "app.ts"));
+  });
+
+  test("chant lint applies lint.rules to a policy's id", async () => {
+    breakSessions();
+    writeFileSync(
+      join(root, "chant.config.ts"),
+      readFileSync(join(root, "chant.config.ts"), "utf-8").replace(
+        'lint: { policies: ["policies/columns.ts"] }',
+        'lint: { policies: ["policies/columns.ts"], rules: { "ORG-CREATED-AT": "off" } }',
+      ),
+    );
+    const result = await lintCommand({ path: join(root, "src"), format: "stylish" });
+    expect(policyIds(result.diagnostics), result.output).toEqual([]);
+  });
+
+  test("chant build fails on the same table", async () => {
+    breakSessions();
+    const result = await buildCommand({ path: join(root, "src"), format: "json", serializers: [sqlSerializer], plugins: [sqlPlugin] });
+    expect(result.success).toBe(false);
+    expect(result.errors.join("\n")).toContain("[policy:ORG-CREATED-AT] [sessions]");
+  });
+
+  // The first case above lints the same files with no env and gets no ORG-COLUMN-COMMENTS finding.
+  // (The config is written before any lint here: a loaded chant.config.ts is cached for the process.)
+  test("an env-aware policy fires in prod", async () => {
+    writeFileSync(
+      join(root, "chant.config.ts"),
+      readFileSync(join(root, "chant.config.ts"), "utf-8").replace('sql: { dialect: "postgres" },', 'sql: { dialect: "postgres" },\n  ownership: { env: "prod" },'),
+    );
+    const prod = await lintCommand({ path: join(root, "src"), format: "stylish" });
+    expect(prod.diagnostics.filter((d) => d.ruleId === "ORG-COLUMN-COMMENTS").map((d) => d.message), prod.output).toEqual([
+      "[accounts] app.accounts.created_at has no comment",
+      "[sessions] app.sessions.account_id has no comment",
+      "[sessions] app.sessions.created_at has no comment",
+    ]);
+  });
+
+  test("the ClickHouse policy flags a MergeTree table without created_at, and a Nullable sort key column", async () => {
+    rmSync(join(root, "src"), { recursive: true });
+    mkdirSync(join(root, "src"));
+    writeFileSync(
+      join(root, "chant.config.ts"),
+      'import type { ChantConfig } from "@intentius/chant";\n' +
+        'export default { lexicons: ["sql"], sql: { dialect: "clickhouse" }, lint: { policies: ["policies/clickhouse.ts"], rules: { SQLCH113: "off" } } } satisfies ChantConfig;\n',
+    );
+    writeFileSync(
+      join(root, "src", "schema.ts"),
+      'import { database, table } from "@intentius/chant-lexicon-sql/clickhouse";\n' +
+        "export const shop = database`CREATE DATABASE shop ENGINE = Atomic`;\n" +
+        "export const events = table`CREATE TABLE ${shop}.events (id UInt64, created_at DateTime) ENGINE = MergeTree ORDER BY id`;\n" +
+        "export const visits = table`CREATE TABLE ${shop}.visits (id UInt64, ref Nullable(String)) ENGINE = MergeTree ORDER BY (id, ref) SETTINGS allow_nullable_key = 1`;\n",
+    );
+    const result = await lintCommand({ path: join(root, "src"), format: "stylish" });
+    expect(result.diagnostics.filter((d) => d.ruleId === "ORG-CH-CREATED-AT").map((d) => d.message), result.output).toEqual([
+      "[visits] shop.visits needs created_at DateTime, not Nullable",
+      "[visits] shop.visits.ref is Nullable and in the sort key",
+    ]);
+  });
+
+  test("tsc checks a policy against the read API's types", () => {
+    const policy = join(root, "policies", "columns.ts");
+    const check = () => {
+      const program = ts.createProgram([policy], {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        strict: true,
+        noEmit: true,
+        skipLibCheck: true,
+        types: [],
+      });
+      return ts
+        .getPreEmitDiagnostics(program)
+        .filter((d) => d.file?.fileName === policy)
+        .map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n"));
+    };
+    expect(check()).toEqual([]);
+    writeFileSync(policy, readFileSync(policy, "utf-8").replace("c.typeName === TIMESTAMPTZ", "c.typeNmae === TIMESTAMPTZ"));
+    expect(check().join("\n")).toMatch(/Property 'typeNmae' does not exist on type 'PostgresColumnInfo'/);
+  }, 60_000);
+});