@intentius/chant-lexicon-sql 0.124.18 → 0.124.21

package/src/coverage/postgres-commands.json

@@ -0,0 +1,245 @@
+{
+  "source": "doc/src/sgml/ref/create_*.sgml <refname>, at each pinned major's tag",
+  "majors": {
+    "14": {
+      "version": "14.24",
+      "tag": "REL_14_24",
+      "commands": [
+        "CREATE ACCESS METHOD",
+        "CREATE AGGREGATE",
+        "CREATE CAST",
+        "CREATE COLLATION",
+        "CREATE CONVERSION",
+        "CREATE DATABASE",
+        "CREATE DOMAIN",
+        "CREATE EVENT TRIGGER",
+        "CREATE EXTENSION",
+        "CREATE FOREIGN DATA WRAPPER",
+        "CREATE FOREIGN TABLE",
+        "CREATE FUNCTION",
+        "CREATE GROUP",
+        "CREATE INDEX",
+        "CREATE LANGUAGE",
+        "CREATE MATERIALIZED VIEW",
+        "CREATE OPERATOR",
+        "CREATE OPERATOR CLASS",
+        "CREATE OPERATOR FAMILY",
+        "CREATE POLICY",
+        "CREATE PROCEDURE",
+        "CREATE PUBLICATION",
+        "CREATE ROLE",
+        "CREATE RULE",
+        "CREATE SCHEMA",
+        "CREATE SEQUENCE",
+        "CREATE SERVER",
+        "CREATE STATISTICS",
+        "CREATE SUBSCRIPTION",
+        "CREATE TABLE",
+        "CREATE TABLE AS",
+        "CREATE TABLESPACE",
+        "CREATE TEXT SEARCH CONFIGURATION",
+        "CREATE TEXT SEARCH DICTIONARY",
+        "CREATE TEXT SEARCH PARSER",
+        "CREATE TEXT SEARCH TEMPLATE",
+        "CREATE TRANSFORM",
+        "CREATE TRIGGER",
+        "CREATE TYPE",
+        "CREATE USER",
+        "CREATE USER MAPPING",
+        "CREATE VIEW"
+      ]
+    },
+    "15": {
+      "version": "15.19",
+      "tag": "REL_15_19",
+      "commands": [
+        "CREATE ACCESS METHOD",
+        "CREATE AGGREGATE",
+        "CREATE CAST",
+        "CREATE COLLATION",
+        "CREATE CONVERSION",
+        "CREATE DATABASE",
+        "CREATE DOMAIN",
+        "CREATE EVENT TRIGGER",
+        "CREATE EXTENSION",
+        "CREATE FOREIGN DATA WRAPPER",
+        "CREATE FOREIGN TABLE",
+        "CREATE FUNCTION",
+        "CREATE GROUP",
+        "CREATE INDEX",
+        "CREATE LANGUAGE",
+        "CREATE MATERIALIZED VIEW",
+        "CREATE OPERATOR",
+        "CREATE OPERATOR CLASS",
+        "CREATE OPERATOR FAMILY",
+        "CREATE POLICY",
+        "CREATE PROCEDURE",
+        "CREATE PUBLICATION",
+        "CREATE ROLE",
+        "CREATE RULE",
+        "CREATE SCHEMA",
+        "CREATE SEQUENCE",
+        "CREATE SERVER",
+        "CREATE STATISTICS",
+        "CREATE SUBSCRIPTION",
+        "CREATE TABLE",
+        "CREATE TABLE AS",
+        "CREATE TABLESPACE",
+        "CREATE TEXT SEARCH CONFIGURATION",
+        "CREATE TEXT SEARCH DICTIONARY",
+        "CREATE TEXT SEARCH PARSER",
+        "CREATE TEXT SEARCH TEMPLATE",
+        "CREATE TRANSFORM",
+        "CREATE TRIGGER",
+        "CREATE TYPE",
+        "CREATE USER",
+        "CREATE USER MAPPING",
+        "CREATE VIEW"
+      ]
+    },
+    "16": {
+      "version": "16.15",
+      "tag": "REL_16_15",
+      "commands": [
+        "CREATE ACCESS METHOD",
+        "CREATE AGGREGATE",
+        "CREATE CAST",
+        "CREATE COLLATION",
+        "CREATE CONVERSION",
+        "CREATE DATABASE",
+        "CREATE DOMAIN",
+        "CREATE EVENT TRIGGER",
+        "CREATE EXTENSION",
+        "CREATE FOREIGN DATA WRAPPER",
+        "CREATE FOREIGN TABLE",
+        "CREATE FUNCTION",
+        "CREATE GROUP",
+        "CREATE INDEX",
+        "CREATE LANGUAGE",
+        "CREATE MATERIALIZED VIEW",
+        "CREATE OPERATOR",
+        "CREATE OPERATOR CLASS",
+        "CREATE OPERATOR FAMILY",
+        "CREATE POLICY",
+        "CREATE PROCEDURE",
+        "CREATE PUBLICATION",
+        "CREATE ROLE",
+        "CREATE RULE",
+        "CREATE SCHEMA",
+        "CREATE SEQUENCE",
+        "CREATE SERVER",
+        "CREATE STATISTICS",
+        "CREATE SUBSCRIPTION",
+        "CREATE TABLE",
+        "CREATE TABLE AS",
+        "CREATE TABLESPACE",
+        "CREATE TEXT SEARCH CONFIGURATION",
+        "CREATE TEXT SEARCH DICTIONARY",
+        "CREATE TEXT SEARCH PARSER",
+        "CREATE TEXT SEARCH TEMPLATE",
+        "CREATE TRANSFORM",
+        "CREATE TRIGGER",
+        "CREATE TYPE",
+        "CREATE USER",
+        "CREATE USER MAPPING",
+        "CREATE VIEW"
+      ]
+    },
+    "17": {
+      "version": "17.11",
+      "tag": "REL_17_11",
+      "commands": [
+        "CREATE ACCESS METHOD",
+        "CREATE AGGREGATE",
+        "CREATE CAST",
+        "CREATE COLLATION",
+        "CREATE CONVERSION",
+        "CREATE DATABASE",
+        "CREATE DOMAIN",
+        "CREATE EVENT TRIGGER",
+        "CREATE EXTENSION",
+        "CREATE FOREIGN DATA WRAPPER",
+        "CREATE FOREIGN TABLE",
+        "CREATE FUNCTION",
+        "CREATE GROUP",
+        "CREATE INDEX",
+        "CREATE LANGUAGE",
+        "CREATE MATERIALIZED VIEW",
+        "CREATE OPERATOR",
+        "CREATE OPERATOR CLASS",
+        "CREATE OPERATOR FAMILY",
+        "CREATE POLICY",
+        "CREATE PROCEDURE",
+        "CREATE PUBLICATION",
+        "CREATE ROLE",
+        "CREATE RULE",
+        "CREATE SCHEMA",
+        "CREATE SEQUENCE",
+        "CREATE SERVER",
+        "CREATE STATISTICS",
+        "CREATE SUBSCRIPTION",
+        "CREATE TABLE",
+        "CREATE TABLE AS",
+        "CREATE TABLESPACE",
+        "CREATE TEXT SEARCH CONFIGURATION",
+        "CREATE TEXT SEARCH DICTIONARY",
+        "CREATE TEXT SEARCH PARSER",
+        "CREATE TEXT SEARCH TEMPLATE",
+        "CREATE TRANSFORM",
+        "CREATE TRIGGER",
+        "CREATE TYPE",
+        "CREATE USER",
+        "CREATE USER MAPPING",
+        "CREATE VIEW"
+      ]
+    },
+    "18": {
+      "version": "18.6",
+      "tag": "REL_18_6",
+      "commands": [
+        "CREATE ACCESS METHOD",
+        "CREATE AGGREGATE",
+        "CREATE CAST",
+        "CREATE COLLATION",
+        "CREATE CONVERSION",
+        "CREATE DATABASE",
+        "CREATE DOMAIN",
+        "CREATE EVENT TRIGGER",
+        "CREATE EXTENSION",
+        "CREATE FOREIGN DATA WRAPPER",
+        "CREATE FOREIGN TABLE",
+        "CREATE FUNCTION",
+        "CREATE GROUP",
+        "CREATE INDEX",
+        "CREATE LANGUAGE",
+        "CREATE MATERIALIZED VIEW",
+        "CREATE OPERATOR",
+        "CREATE OPERATOR CLASS",
+        "CREATE OPERATOR FAMILY",
+        "CREATE POLICY",
+        "CREATE PROCEDURE",
+        "CREATE PUBLICATION",
+        "CREATE ROLE",
+        "CREATE RULE",
+        "CREATE SCHEMA",
+        "CREATE SEQUENCE",
+        "CREATE SERVER",
+        "CREATE STATISTICS",
+        "CREATE SUBSCRIPTION",
+        "CREATE TABLE",
+        "CREATE TABLE AS",
+        "CREATE TABLESPACE",
+        "CREATE TEXT SEARCH CONFIGURATION",
+        "CREATE TEXT SEARCH DICTIONARY",
+        "CREATE TEXT SEARCH PARSER",
+        "CREATE TEXT SEARCH TEMPLATE",
+        "CREATE TRANSFORM",
+        "CREATE TRIGGER",
+        "CREATE TYPE",
+        "CREATE USER",
+        "CREATE USER MAPPING",
+        "CREATE VIEW"
+      ]
+    }
+  }
+}

package/src/coverage/postgres.json

@@ -0,0 +1,51 @@
+{
+  "dialect": "postgres",
+  "kinds": [
+    { "command": "CREATE ACCESS METHOD", "kind": "access method", "status": "refused", "reason": "no tag declares an access method; an extension usually installs one, and the extension is declared instead" },
+    { "command": "CREATE AGGREGATE", "kind": "aggregate", "status": "declared", "entity": "Postgres::Aggregate" },
+    { "command": "CREATE CAST", "kind": "cast", "status": "declared", "entity": "Postgres::Cast", "note": "the database's, named by its two types; read where a type or its function is in scope" },
+    { "command": "CREATE COLLATION", "kind": "collation", "status": "declared", "entity": "Postgres::Collation" },
+    { "command": "CREATE CONVERSION", "kind": "conversion", "status": "refused", "reason": "no tag declares an encoding conversion" },
+    { "command": "CREATE DATABASE", "kind": "database", "status": "out-of-scope", "reason": "a project's schema lives in one database, which the environment provides (sql.profiles.<env>)" },
+    { "command": "CREATE DOMAIN", "kind": "domain", "status": "declared", "entity": "Postgres::Domain" },
+    { "command": "CREATE EVENT TRIGGER", "kind": "event trigger", "status": "declared", "entity": "Postgres::EventTrigger", "note": "the database's, not a schema's; creating one takes a superuser" },
+    { "command": "CREATE EXTENSION", "kind": "extension", "status": "declared", "entity": "Postgres::Extension" },
+    { "command": "CREATE FOREIGN DATA WRAPPER", "kind": "foreign data wrapper", "status": "refused", "reason": "no tag declares a foreign data wrapper yet; one an extension installs comes with the extension" },
+    { "command": "CREATE FOREIGN TABLE", "kind": "foreign table", "status": "refused", "reason": "no tag declares a foreign table yet" },
+    { "command": "CREATE FUNCTION", "kind": "function", "status": "declared", "entity": "Postgres::Function" },
+    { "command": "CREATE FUNCTION", "form": "RETURN or BEGIN ATOMIC body", "match": "\\b(?:RETURN|BEGIN\\s+ATOMIC)\\b", "kind": "routine with a SQL-standard body", "status": "refused", "reason": "the server stores a SQL-standard body parsed and prints it back rewritten, so a declaration cannot be compared with it; declare the routine with a string body (AS $$ ... $$)" },
+    { "command": "CREATE GROUP", "kind": "group", "status": "declared", "entity": "Postgres::Role", "note": "an alias of CREATE ROLE" },
+    { "command": "CREATE INDEX", "kind": "index", "status": "declared", "entity": "Postgres::Index" },
+    { "command": "CREATE LANGUAGE", "kind": "procedural language", "status": "refused", "reason": "no tag declares a procedural language; an extension installs one, and the extension is declared instead" },
+    { "command": "CREATE MATERIALIZED VIEW", "kind": "materialized view", "status": "declared", "entity": "Postgres::MaterializedView" },
+    { "command": "CREATE OPERATOR", "kind": "operator", "status": "refused", "reason": "no tag declares an operator yet" },
+    { "command": "CREATE OPERATOR CLASS", "kind": "operator class", "status": "refused", "reason": "no tag declares an operator class yet" },
+    { "command": "CREATE OPERATOR FAMILY", "kind": "operator family", "status": "refused", "reason": "no tag declares an operator family yet" },
+    { "command": "CREATE POLICY", "kind": "policy", "status": "declared", "entity": "Postgres::Policy", "note": "read where the profile manages access (sql.profiles.<env>.access)" },
+    { "command": "CREATE PROCEDURE", "kind": "procedure", "status": "declared", "entity": "Postgres::Procedure" },
+    { "command": "CREATE PUBLICATION", "kind": "publication", "status": "refused", "reason": "no tag declares a publication yet" },
+    { "command": "CREATE ROLE", "kind": "role", "status": "declared", "entity": "Postgres::Role", "note": "import reads only the roles a build declares, since a role is the cluster's" },
+    { "command": "CREATE RULE", "kind": "rule", "status": "refused", "reason": "no tag declares a rewrite rule; a view's own rule is the view's" },
+    { "command": "CREATE SCHEMA", "kind": "schema", "status": "declared", "entity": "Postgres::Schema" },
+    { "command": "CREATE SEQUENCE", "kind": "sequence", "status": "declared", "entity": "Postgres::Sequence" },
+    { "command": "CREATE SERVER", "kind": "foreign server", "status": "refused", "reason": "no tag declares a foreign server yet" },
+    { "command": "CREATE STATISTICS", "kind": "extended statistics", "status": "refused", "reason": "no tag declares extended statistics yet" },
+    { "command": "CREATE SUBSCRIPTION", "kind": "subscription", "status": "refused", "reason": "no tag declares a subscription yet" },
+    { "command": "CREATE TABLE", "kind": "table", "status": "declared", "entity": "Postgres::Table" },
+    { "command": "CREATE TABLE AS", "kind": "table from a query", "status": "declared", "entity": "Postgres::Table", "note": "the server keeps no query, so the table it made reads as a CREATE TABLE" },
+    { "command": "CREATE TABLESPACE", "kind": "tablespace", "status": "out-of-scope", "reason": "a tablespace is the cluster's, a directory on the server; a table's TABLESPACE clause is kept" },
+    { "command": "CREATE TEXT SEARCH CONFIGURATION", "kind": "text search configuration", "status": "refused", "reason": "no tag declares a text search configuration yet" },
+    { "command": "CREATE TEXT SEARCH DICTIONARY", "kind": "text search dictionary", "status": "refused", "reason": "no tag declares a text search dictionary yet" },
+    { "command": "CREATE TEXT SEARCH PARSER", "kind": "text search parser", "status": "refused", "reason": "no tag declares a text search parser; one is C code an extension installs" },
+    { "command": "CREATE TEXT SEARCH TEMPLATE", "kind": "text search template", "status": "refused", "reason": "no tag declares a text search template; one is C code an extension installs" },
+    { "command": "CREATE TRANSFORM", "kind": "transform", "status": "refused", "reason": "no tag declares a transform; an extension installs one" },
+    { "command": "CREATE TRIGGER", "kind": "trigger", "status": "declared", "entity": "Postgres::Trigger" },
+    { "command": "CREATE TYPE", "form": "AS ENUM", "match": "\\bAS\\s+ENUM\\b", "kind": "enum type", "status": "declared", "entity": "Postgres::Enum" },
+    { "command": "CREATE TYPE", "form": "AS (...)", "match": "\\bAS\\s*\\(", "kind": "composite type", "status": "declared", "entity": "Postgres::CompositeType" },
+    { "command": "CREATE TYPE", "form": "AS RANGE", "match": "\\bAS\\s+RANGE\\b", "kind": "range type", "status": "declared", "entity": "Postgres::RangeType", "note": "its multirange type comes with it (MULTIRANGE_TYPE_NAME)" },
+    { "command": "CREATE TYPE", "form": "INPUT, OUTPUT, or a shell type", "kind": "base type", "status": "refused", "reason": "no tag declares a base type; its input and output functions are C code an extension installs" },
+    { "command": "CREATE USER", "kind": "user", "status": "declared", "entity": "Postgres::Role", "note": "an alias of CREATE ROLE ... LOGIN" },
+    { "command": "CREATE USER MAPPING", "kind": "user mapping", "status": "refused", "reason": "no tag declares a user mapping yet" },
+    { "command": "CREATE VIEW", "kind": "view", "status": "declared", "entity": "Postgres::View" }
+  ]
+}

package/src/coverage.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "vitest";
+import { KIND_COVERAGE, PINNED_COMMANDS, kindCoverageProblems, pinnedCommandsCurrent, statementKind } from "./coverage";
+import { POSTGRES_PROBES } from "./postgres/live/undeclarable";
+import { CLICKHOUSE_PROBES } from "./clickhouse/live/undeclarable";
+import { SQL_DIALECTS } from "./dialects";
+
+describe("the object coverage table (#3911)", () => {
+  test.each(SQL_DIALECTS)("%s: every CREATE command a pinned server has is marked, and nothing else", (dialect) => {
+    expect(kindCoverageProblems(dialect)).toEqual([]);
+  });
+
+  test.each(SQL_DIALECTS)("%s: the command lists are the pinned servers' (run scripts/sql-create-commands.ts after a pin move)", (dialect) => {
+    expect(pinnedCommandsCurrent(dialect)).toEqual([]);
+  });
+
+  test("a pinned server with a command no row covers fails the check", () => {
+    const pins = [{ version: "19.0", commands: [...PINNED_COMMANDS.postgres[0]!.commands, "CREATE PROPERTY GRAPH"] }];
+    expect(kindCoverageProblems("postgres", { pins })).toContain("postgres 19.0 has CREATE PROPERTY GRAPH, and no row in src/coverage/postgres.json covers it");
+  });
+
+  test("a row must say why it is not declared, and name its entity when it is", () => {
+    const rows = [
+      { command: "CREATE CAST", kind: "cast", status: "refused" as const },
+      { command: "CREATE TABLE", kind: "table", status: "declared" as const },
+    ];
+    expect(kindCoverageProblems("postgres", { pins: [{ version: "x", commands: ["CREATE CAST", "CREATE TABLE"] }], rows })).toEqual([
+      "cast is refused, and gives no reason",
+      "table is declared, and names no entity type",
+    ]);
+  });
+
+  test("every refused kind has the live query that finds it, and every query a refused-or-declared row", () => {
+    const probes = { postgres: POSTGRES_PROBES, clickhouse: CLICKHOUSE_PROBES };
+    for (const dialect of SQL_DIALECTS) {
+      const refused = KIND_COVERAGE[dialect].filter((r) => r.status === "refused").map((r) => r.kind);
+      for (const kind of refused) expect(Object.keys(probes[dialect]), `${dialect} ${kind}`).toContain(kind);
+      const kinds = KIND_COVERAGE[dialect].map((r) => r.kind);
+      for (const kind of Object.keys(probes[dialect])) expect(kinds, `${dialect} probe ${kind}`).toContain(kind);
+    }
+  });
+});
+
+describe("a statement's kind", () => {
+  test.each([
+    ["CREATE TYPE app.pair AS (a int, b text)", "composite type"],
+    ["CREATE TYPE app.r AS RANGE (subtype = float8)", "range type"],
+    ["CREATE TYPE app.mood AS ENUM ('ok')", "enum type"],
+    ["CREATE TYPE app.shell", "base type"],
+    ["CREATE AGGREGATE app.total(int) (sfunc = int4pl, stype = int)", "aggregate"],
+    ["CREATE CAST (app.pair AS text) WITH FUNCTION app.f(app.pair)", "cast"],
+    ["CREATE OR REPLACE TRUSTED PROCEDURAL LANGUAGE plx", "procedural language"],
+    ["CREATE DEFAULT CONVERSION c FOR 'LATIN1' TO 'UTF8' FROM f", "conversion"],
+    ["CREATE OPERATOR CLASS c FOR TYPE int USING btree AS OPERATOR 1 <", "operator class"],
+    ["CREATE TEXT SEARCH CONFIGURATION app.eng (COPY = english)", "text search configuration"],
+    ["CREATE USER MAPPING FOR app SERVER s", "user mapping"],
+    ["CREATE UNIQUE INDEX i ON app.t (a)", "index"],
+    // A body's RETURN is inside its string, not a SQL-standard body.
+    ["CREATE FUNCTION app.f() RETURNS int LANGUAGE plpgsql AS $$ BEGIN RETURN 1; END $$", "function"],
+    ["CREATE FUNCTION app.f(a int) RETURNS int LANGUAGE sql RETURN a + 1", "routine with a SQL-standard body"],
+  ])("postgres: %s is a %s", (sql, kind) => {
+    expect(statementKind("postgres", sql)?.kind).toBe(kind);
+  });
+
+  test.each([
+    ["CREATE TEMPORARY TABLE t (a Int8)", "temporary table"],
+    ["CREATE TABLE t (a Int8) ENGINE = Memory", "table"],
+    ["CREATE WINDOW VIEW w AS SELECT 1", "window view"],
+    ["CREATE SETTINGS PROFILE p SETTINGS max_threads = 1", "settings profile"],
+    ["CREATE OR REPLACE FUNCTION f AS (x) -> x + 1", "SQL function"],
+    ["CREATE QUOTA q FOR INTERVAL 1 hour MAX queries = 10", "quota"],
+  ])("clickhouse: %s is a %s", (sql, kind) => {
+    expect(statementKind("clickhouse", sql)?.kind).toBe(kind);
+  });
+
+  test("a statement that is not a CREATE has no kind", () => {
+    expect(statementKind("postgres", "ALTER TABLE t ADD COLUMN a int")).toBeUndefined();
+  });
+});

package/src/coverage.ts

@@ -1,4 +1,17 @@
 /**
+ * Coverage, two ways.
+ *
+ * Which kinds of object each dialect declares (#3911): every `CREATE` command
+ * a pinned server has (`./coverage/<dialect>-commands.json`, written by
+ * `scripts/sql-create-commands.ts` from the server's own sources) has a row
+ * in `./coverage/<dialect>.json` marking it declared, refused with a reason,
+ * or out of scope. A command with several forms that differ in what chant can
+ * hold (`CREATE TYPE ... AS ENUM` and `CREATE TYPE ... AS RANGE`) has a row
+ * per form. Import refuses an object of a refused kind by that row's `kind`
+ * (`./core/undeclarable.ts`), and the docs page is rendered from the rows
+ * (`./codegen/coverage-page.ts`). To declare a kind, flip its row to
+ * `declared` with the `entity` that holds it, and drop the reason.
+ *
  * How much of the pinned ClickHouse catalog the dialect types beyond its name.
  *
  * Every engine, type family, codec, skip index type and setting at the pin is
@@ -9,6 +22,135 @@
  */
 
 import { CODECS, SKIP_INDEX_TYPES, TABLE_ENGINES, CLICKHOUSE_VERSION } from "./generated/clickhouse";
+import { POSTGRES_PINS } from "./spec/postgres-pin";
+import type { SqlDialect } from "./dialects";
+import postgresKinds from "./coverage/postgres.json" with { type: "json" };
+import clickhouseKinds from "./coverage/clickhouse.json" with { type: "json" };
+import postgresCommands from "./coverage/postgres-commands.json" with { type: "json" };
+import clickhouseCommands from "./coverage/clickhouse-commands.json" with { type: "json" };
+
+// ── Object kinds ───────────────────────────────────────────────────────
+
+/** `declared`: a tag holds it. `refused`: import names it and stops. `out-of-scope`: the environment's, never imported. */
+export type KindStatus = "declared" | "refused" | "out-of-scope";
+
+/** One row of a dialect's coverage table: a `CREATE` command, or one form of it. */
+export interface KindRow {
+  /** The command as the server's reference names it: `CREATE TYPE`. */
+  command: string;
+  /** The form of the command the row is about, when the command has forms chant treats apart: `AS RANGE`. */
+  form?: string;
+  /**
+   * How a statement of the command is told to be this form: a regular
+   * expression, case-insensitive, over the statement with its comments and
+   * string literals taken out. The command's row without one is the rest.
+   */
+  match?: string;
+  /** The object kind, unique in the dialect, as messages name it: `range type`. */
+  kind: string;
+  status: KindStatus;
+  /** The entity type that declares it, when declared. */
+  entity?: string;
+  /** Why it is refused or out of scope. */
+  reason?: string;
+  /** Anything else a reader should know. */
+  note?: string;
+}
+
+/** Each dialect's coverage table. */
+export const KIND_COVERAGE: Record<SqlDialect, readonly KindRow[]> = {
+  postgres: postgresKinds.kinds as KindRow[],
+  clickhouse: clickhouseKinds.kinds as KindRow[],
+};
+
+/** The `CREATE` commands each pinned server has: per Postgres major, and the pinned ClickHouse release. */
+export const PINNED_COMMANDS: Record<SqlDialect, ReadonlyArray<{ version: string; commands: readonly string[] }>> = {
+  postgres: Object.values(postgresCommands.majors),
+  clickhouse: [{ version: clickhouseCommands.version, commands: clickhouseCommands.commands }],
+};
+
+/** A dialect's row for `kind`; throws for a kind the table does not have, so a probe cannot name one that is not there. */
+export function kindRow(dialect: SqlDialect, kind: string): KindRow {
+  const row = KIND_COVERAGE[dialect].find((r) => r.kind === kind);
+  if (!row) throw new Error(`no ${dialect} coverage row for the kind "${kind}" (src/coverage/${dialect}.json)`);
+  return row;
+}
+
+/**
+ * What is wrong with a dialect's coverage table, against its pinned servers'
+ * commands: a command a pinned server has and no row covers, a row for a
+ * command no pinned server has, a kind named twice, a declared row with no
+ * entity, a refused or out-of-scope row with no reason. Empty when complete.
+ */
+export function kindCoverageProblems(dialect: SqlDialect, opts: { pins?: ReadonlyArray<{ version: string; commands: readonly string[] }>; rows?: readonly KindRow[] } = {}): string[] {
+  const rows = opts.rows ?? KIND_COVERAGE[dialect];
+  const pins = opts.pins ?? PINNED_COMMANDS[dialect];
+  const problems: string[] = [];
+  const covered = new Set(rows.map((r) => r.command));
+  const listed = new Set(pins.flatMap((p) => p.commands));
+  for (const p of pins) {
+    for (const c of p.commands) if (!covered.has(c)) problems.push(`${dialect} ${p.version} has ${c}, and no row in src/coverage/${dialect}.json covers it`);
+  }
+  for (const c of covered) if (!listed.has(c)) problems.push(`src/coverage/${dialect}.json has a row for ${c}, which no pinned ${dialect} server has`);
+  const seen = new Set<string>();
+  for (const r of rows) {
+    if (seen.has(r.kind)) problems.push(`the kind "${r.kind}" has two rows`);
+    seen.add(r.kind);
+    if (!["declared", "refused", "out-of-scope"].includes(r.status)) problems.push(`${r.kind}: status "${r.status}" is not declared, refused or out-of-scope`);
+    if (r.status === "declared" && !r.entity) problems.push(`${r.kind} is declared, and names no entity type`);
+    if (r.status !== "declared" && !r.reason) problems.push(`${r.kind} is ${r.status}, and gives no reason`);
+  }
+  return problems;
+}
+
+/** A statement's words, upper case, with comments and string literals (quoted and dollar-quoted) taken out. */
+function bareStatement(sql: string): string {
+  return sql
+    .replace(/--[^\n]*/g, " ")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/\$([A-Za-z_][A-Za-z0-9_]*)?\$[\s\S]*?\$\1\$/g, " '' ")
+    .replace(/'(?:[^'\\]|''|\\.)*'/g, " '' ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toUpperCase();
+}
+
+/** Words a `CREATE` can carry before the command's own: `CREATE OR REPLACE TRUSTED PROCEDURAL LANGUAGE`, `CREATE DEFAULT CONVERSION`. */
+const MODIFIERS = new Set(["OR", "REPLACE", "TRUSTED", "PROCEDURAL", "DEFAULT", "UNIQUE", "UNLOGGED", "RECURSIVE", "CONSTRAINT", "GLOBAL", "LOCAL", "TEMP", "TEMPORARY"]);
+
+/**
+ * The coverage row a `CREATE` statement is of, by its command (the longest
+ * that its words start with) and, among the command's forms, the first whose
+ * `match` it matches; undefined for a statement no row covers.
+ */
+export function statementKind(dialect: SqlDialect, sql: string): KindRow | undefined {
+  const bare = bareStatement(sql);
+  const words = bare.split(/[\s(]+/);
+  if (words[0] !== "CREATE") return undefined;
+  const rest = words.slice(1).filter((w, i, all) => !MODIFIERS.has(w) || all.slice(0, i).some((x) => !MODIFIERS.has(x)));
+  const rows = KIND_COVERAGE[dialect];
+  let command: string | undefined;
+  for (const r of rows) {
+    const cmd = r.command.split(" ").slice(1);
+    if (cmd.every((w, i) => rest[i] === w) && (!command || cmd.length > command.split(" ").length - 1)) command = r.command;
+  }
+  if (!command) return undefined;
+  const forms = rows.filter((r) => r.command === command);
+  return forms.find((r) => r.match !== undefined && new RegExp(r.match, "i").test(bare)) ?? forms.find((r) => r.match === undefined);
+}
+
+/** Whether the commands file was written for the pinned servers: a list for each pinned version, and for no other. */
+export function pinnedCommandsCurrent(dialect: SqlDialect): string[] {
+  const have = PINNED_COMMANDS[dialect].map((p) => p.version);
+  const want = dialect === "postgres" ? POSTGRES_PINS.map((p) => p.version) : [CLICKHOUSE_VERSION];
+  const run = `run npx tsx scripts/sql-create-commands.ts ${dialect}`;
+  return [
+    ...want.filter((v) => !have.includes(v)).map((v) => `${dialect} ${v} is pinned, and src/coverage/${dialect}-commands.json has no command list for it: ${run}`),
+    ...have.filter((v) => !want.includes(v)).map((v) => `src/coverage/${dialect}-commands.json lists ${dialect} ${v}, which is no longer pinned: ${run}`),
+  ];
+}
+
+// ── ClickHouse argument typing ─────────────────────────────────────────
 
 export interface CoverageSection {
   section: string;

package/src/files/clickhouse.ts

@@ -2,7 +2,8 @@
  * A file of ClickHouse DDL as the objects it declares: one per `CREATE
  * DATABASE`, `TABLE`, `VIEW`, `MATERIALIZED VIEW`, `DICTIONARY` or `FUNCTION`, as `chant import
  * <file>.sql` reads them, and one per `CREATE USER`, `CREATE ROLE`, `CREATE
- * ROW POLICY` and `GRANT` (#3711), each read by its tag, so what the tag
+ * ROW POLICY`, `CREATE QUOTA`, `CREATE SETTINGS PROFILE` (#3911) and `GRANT`
+ * (#3711), each read by its tag, so what the tag
  * refuses (`IDENTIFIED BY`, a `REVOKE`) is refused with the tag's message.
  * Any other statement, and any statement the parser refuses, is a problem
  * naming it.
@@ -15,16 +16,22 @@
 import type { Declarable } from "@intentius/chant/declarable";
 import { isTrivia, tokenizeText } from "../clickhouse/tokens";
 import { parseCreate } from "../clickhouse/parser";
-import { CLICKHOUSE_ENTITY_TYPES, database, dictionary, func, grant, policy, role, table, user, view } from "../clickhouse/entities";
+import { CLICKHOUSE_ENTITY_TYPES, database, dictionary, func, grant, policy, quota, role, settingsProfile, table, user, view } from "../clickhouse/entities";
 import { isAccessStatement, parseAccess, type AccessNode } from "../clickhouse/access";
 import type { Token } from "../clickhouse/tokens";
 import { CLICKHOUSE_TAG_OF } from "../clickhouse/import/generator";
 import { describeStatement, type ImportedObject } from "../clickhouse/import/ir";
-import { fileUnparsed, firstLine, lineAt, quoteBare, splitTokens, tokensText, type FileLine, type ReadOptions } from "./common";
+import { fileUnparsed, firstLine, lineAt, quoteBare, splitTokens, tokensText, undeclarableStatement, type FileLine, type ReadOptions } from "./common";
 import { templateSafe, templateStrings } from "./postgres";
 
 type Tag = (strings: TemplateStringsArray, ...values: unknown[]) => Declarable;
-const TAGS: Record<string, Tag> = { database, table, view, dictionary, func, user, role, policy, grant };
+const TAGS: Record<string, Tag> = { database, table, view, dictionary, func, user, role, policy, quota, settingsProfile, grant };
+
+/** The tag an access statement's words name: `CREATE USER`, `CREATE SETTINGS PROFILE`, `GRANT`. */
+function accessTag(words: string[]): Tag {
+  if (words[0] !== "CREATE") return grant;
+  return words[1] === "USER" ? user : words[1] === "ROLE" ? role : words[1] === "QUOTA" ? quota : words[1] === "SETTINGS" || words[1] === "PROFILE" ? settingsProfile : policy;
+}
 
 /** Tokens with `[db.]name`'s bare name qualified with `schema`. A `*` (all tables) is left alone. */
 function qualifyBare(tokens: Token[], span: { from: number; to: number } | undefined, schema: string): string | undefined {
@@ -44,8 +51,7 @@ function readAccess(sql: string, options: ReadOptions): ImportedObject | string
     node = parseAccess(tokens);
   } catch (e) {
     // What the tag refuses (a password) is refused in the tag's words.
-    const words = sql.replace(/--[^\n]*\n/g, " ").trim().split(/\s+/, 2).map((w) => w.toUpperCase());
-    const tag = words[0] === "CREATE" ? (words[1] === "USER" ? user : words[1] === "ROLE" ? role : policy) : grant;
+    const tag = accessTag(sql.replace(/--[^\n]*\n/g, " ").trim().split(/\s+/, 2).map((w) => w.toUpperCase()));
     try {
       tag(templateStrings([templateSafe(sql)]));
     } catch (refused) {
@@ -61,7 +67,7 @@ function readAccess(sql: string, options: ReadOptions): ImportedObject | string
       node = parseAccess(tokens);
     }
   }
-  const tag = node.statement === "user" ? user : node.statement === "role" ? role : node.statement === "rowPolicy" ? policy : grant;
+  const tag = { user, role, rowPolicy: policy, quota, settingsProfile, grant }[node.statement];
   let props: { name: string; database?: string; table?: string };
   try {
     props = (tag(templateStrings([templateSafe(sql)])) as unknown as { props: typeof props }).props;
@@ -70,6 +76,8 @@ function readAccess(sql: string, options: ReadOptions): ImportedObject | string
   }
   if (node.statement === "user") return { type: CLICKHOUSE_ENTITY_TYPES.user, name: props.name, ddl: sql };
   if (node.statement === "role") return { type: CLICKHOUSE_ENTITY_TYPES.role, name: props.name, ddl: sql };
+  if (node.statement === "quota") return { type: CLICKHOUSE_ENTITY_TYPES.quota, name: props.name, ddl: sql };
+  if (node.statement === "settingsProfile") return { type: CLICKHOUSE_ENTITY_TYPES.settingsProfile, name: props.name, ddl: sql };
   if (node.statement === "rowPolicy") return { type: CLICKHOUSE_ENTITY_TYPES.rowPolicy, ...(props.database ? { database: props.database } : {}), name: props.name, ddl: sql };
   // A grant has no name of its own: what it grants, on what, to whom.
   return { type: CLICKHOUSE_ENTITY_TYPES.grant, name: `grant ${tokensText(tokens.slice(tokens.findIndex((t) => !isTrivia(t)) + 1)).replace(/\s+/g, " ").trim().toLowerCase()}`, ddl: sql };
@@ -87,6 +95,11 @@ export function readClickHouse(ddl: string, options: ReadOptions, problems: stri
   for (const stmt of splitTokens(tokenizeText(ddl, 0), isTrivia)) {
     let sql = tokensText(stmt);
     const line = lineAt(ddl, stmt[0]!.start);
+    const undeclarable = undeclarableStatement("clickhouse", sql);
+    if (undeclarable) {
+      (options.undeclarable ?? problems).push(undeclarable);
+      continue;
+    }
     if (isAccessStatement(sql)) {
       try {
         const read = readAccess(sql, options);

package/src/files/common.ts

@@ -2,6 +2,8 @@
 
 import type { Token } from "../core/tokens";
 import type { UnknownClause } from "../core/cursor";
+import type { SqlDialect } from "../dialects";
+import { statementKind } from "../coverage";
 
 export interface ReadOptions {
   /** Names the DDL in errors: a file's path, a command. */
@@ -11,6 +13,22 @@ export interface ReadOptions {
    * unqualified, as an ORM does when the schema comes from its connection.
    */
   schema?: string;
+  /**
+   * Where a statement of a kind chant cannot declare goes (#3911), as a line
+   * naming it, instead of among the problems: `chant import
+   * --parser-option skipUndeclarable` lists them as warnings.
+   */
+  undeclarable?: string[];
+}
+
+/**
+ * A `CREATE` of a kind the coverage table does not mark declared, as the line
+ * that names it with why, or undefined for any other statement.
+ */
+export function undeclarableStatement(dialect: SqlDialect, sql: string): string | undefined {
+  const row = statementKind(dialect, sql);
+  if (!row || row.status === "declared") return undefined;
+  return `${row.kind}: chant cannot declare it (${row.reason ?? row.status}): ${firstLine(sql)}`;
 }
 
 /** A file of DDL with statements that declare nothing chant can hold: each problem names its statement. */