@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/import-generator.js

@@ -0,0 +1,14 @@
+/**
+ * The import generator for every dialect: an IR whose resources are Postgres
+ * types goes to the Postgres generator, any other to ClickHouse's. A build
+ * holds one dialect, and so does an import.
+ */
+import { ClickHouseGenerator } from "./clickhouse/import/generator.js";
+import { PostgresGenerator } from "./postgres/import/generator.js";
+export const sqlTemplateGenerator = {
+    ownsLayout: true,
+    generate(ir) {
+        const postgres = ir.resources.some((r) => r.type.startsWith("Postgres::"));
+        return (postgres ? new PostgresGenerator() : new ClickHouseGenerator()).generate(ir);
+    },
+};

package/dist/import-parser.js

@@ -0,0 +1,71 @@
+/**
+ * `chant import schema.sql`: a file of DDL into the import IR, in either
+ * dialect. `--parser-option dialect=postgres` (or `clickhouse`) names it;
+ * without one it is read off the statements: an `ENGINE =` clause, a
+ * `CREATE DATABASE`, a `CREATE DICTIONARY` or a lambda `CREATE FUNCTION f AS
+ * (x) -> ...` is ClickHouse, a statement
+ * only Postgres has (`CREATE SCHEMA`, `CREATE INDEX`, `COMMENT ON`, `ALTER
+ * TABLE`, `GRANT`, ...) or a `CREATE TABLE` with no engine is Postgres, and
+ * anything else is ClickHouse.
+ *
+ * A statement that declares nothing, or does not parse, is an error naming
+ * it (`./sql-files.ts`); none is left out. So is a `CREATE` of a kind chant
+ * cannot declare (#3911, `./coverage.ts`): `--parser-option
+ * skipUndeclarable` imports the rest and lists those as warnings. A clause the parser does not know
+ * (#3872) is kept in the template as written.
+ */
+import { SQL_DIALECTS } from "./dialects.js";
+import { readClickHouse } from "./files/clickhouse.js";
+import { readPostgres } from "./files/postgres.js";
+import { SqlFileError } from "./files/common.js";
+import { objectsToIR as chObjectsToIR } from "./clickhouse/import/ir.js";
+import { objectsToIR as pgObjectsToIR } from "./postgres/import/ir.js";
+const CLICKHOUSE_ONLY = [
+    /\bENGINE\s*=/i,
+    /^\s*CREATE\s+(?:DATABASE|(?:OR\s+REPLACE\s+)?DICTIONARY)\b/im,
+    // A SQL function: CREATE FUNCTION f AS (x) -> ...
+    /^\s*CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+[^\s(]+(?:\s+ON\s+CLUSTER\s+\S+)?\s+AS\s*\(/im,
+    // A row policy (#3711): Postgres says CREATE POLICY.
+    /^\s*CREATE\s+(?:OR\s+REPLACE\s+)?ROW\s+POLICY\b/im,
+];
+const POSTGRES_ONLY = [
+    /^\s*CREATE\s+(?:OR\s+REPLACE\s+)?(?:SCHEMA|EXTENSION|TYPE|DOMAIN|SEQUENCE|(?:UNIQUE\s+)?INDEX|(?:CONSTRAINT\s+)?TRIGGER|POLICY|ROLE|FUNCTION|PROCEDURE|(?:UNLOGGED|TEMP|TEMPORARY)\s+TABLE)\b/im,
+    /^\s*(?:COMMENT\s+ON|ALTER\s+TABLE|ALTER\s+DEFAULT\s+PRIVILEGES|GRANT|REVOKE|BEGIN)\b/im,
+    /^\s*CREATE\s+TABLE\b/im,
+];
+/** The dialect a file of DDL is written in, read off its statements. */
+export function guessDialect(content) {
+    const text = content.replace(/--[^\n]*/g, "");
+    if (CLICKHOUSE_ONLY.some((re) => re.test(text)))
+        return "clickhouse";
+    if (POSTGRES_ONLY.some((re) => re.test(text)))
+        return "postgres";
+    return "clickhouse";
+}
+/** The `dialect` parser option, checked. */
+export function dialectOption(options) {
+    const d = options?.dialect;
+    if (d === undefined)
+        return undefined;
+    if (typeof d !== "string" || !SQL_DIALECTS.includes(d))
+        throw new Error(`--parser-option dialect: expected ${SQL_DIALECTS.join(" or ")}, got ${String(d)}`);
+    return d;
+}
+export class SqlFileParser {
+    constructor(dialect, options = {}) {
+        this.dialect = dialect;
+        this.options = options;
+    }
+    parse(content) {
+        const dialect = this.dialect ?? guessDialect(content);
+        const problems = [];
+        const skipped = [];
+        const read = { origin: "the DDL", ...(this.options.skipUndeclarable ? { undeclarable: skipped } : {}) };
+        const ir = dialect === "postgres" ? pgObjectsToIR(readPostgres(content, read, problems)) : chObjectsToIR(readClickHouse(content, read, problems));
+        if (problems.length > 0)
+            throw new SqlFileError(`the ${dialect === "postgres" ? "Postgres" : "ClickHouse"} DDL`, problems);
+        if (skipped.length === 0)
+            return ir;
+        return { ...ir, warnings: [...(ir.warnings ?? []), ...skipped.map((s) => `left out (skipUndeclarable): ${s}`)] };
+    }
+}

package/dist/index.js

@@ -0,0 +1,24 @@
+// The sql lexicon. Each database dialect is a subpath:
+//   @intentius/chant-lexicon-sql/clickhouse
+//   @intentius/chant-lexicon-sql/postgres
+// The root exports the plugin, the serializer and the dialect list.
+export { sqlPlugin } from "./plugin.js";
+export { sqlSerializer } from "./serializer.js";
+export { SQL_DIALECTS } from "./dialects.js";
+export { sqlConfigSchema } from "./config.js";
+// The ClickHouse tags, also exported at the root because the plugin registers
+// them as intrinsics (check-lexicon resolves a registered intrinsic against the
+// root's exports). Declarations import them from the dialect subpath,
+// `@intentius/chant-lexicon-sql/clickhouse`.
+export { database, table, view, dictionary, user, role, policy, quota, settingsProfile, grant, literal } from "./clickhouse/entities.js";
+// The Postgres tags whose names ClickHouse does not export, for the same reason.
+// A tag folds as the function its file imports, so `table` imported from
+// `@intentius/chant-lexicon-sql/postgres` is Postgres's. Declarations import
+// them from the dialect subpath.
+export { schema, index, sequence, type, domain, extension, func, procedure, aggregate, trigger, eventTrigger, collation, cast } from "./postgres/entities.js";
+// A schema change's statements between two builds, rendered offline for a
+// migration file (#3644); also at `@intentius/chant-lexicon-sql/migration-statements`.
+export { diffStatements, renderStatements, } from "./migration-statements.js";
+// Plain `.sql` files as a schema source (#3646): DDL read into the declarations
+// the tagged templates make; also at `@intentius/chant-lexicon-sql/sql-files`.
+export { readSqlFile, sqlFileDeclarations, sqlFileEntities, sqlFileOf, SqlFileError, } from "./sql-files.js";

package/dist/init-templates.js

@@ -0,0 +1,290 @@
+const DATABASE = (name, comment) => `import { database } from "@intentius/chant-lexicon-sql/clickhouse";
+
+export const ${name} = database\`
+  CREATE DATABASE ${name}
+  ENGINE = Atomic
+  COMMENT '${comment}'\`;
+`;
+// ── default ────────────────────────────────────────────────────────────
+const DEFAULT_TABLES = `import { table } from "@intentius/chant-lexicon-sql/clickhouse";
+import { shop } from "./database";
+
+// Orders land here. The sort key is the on-disk order of every part, and it
+// cannot be changed in place later, so choose it for the queries you run.
+export const orders = table\`
+  CREATE TABLE \${shop}.orders (
+    id          UInt64,
+    customer_id UInt64,
+    status      LowCardinality(String),
+    total       Decimal(18, 2),
+    created_at  DateTime
+  )
+  ENGINE = MergeTree
+  PARTITION BY toYYYYMM(created_at)
+  ORDER BY (customer_id, created_at, id)\`;
+`;
+const DEFAULT_VIEWS = `import { view } from "@intentius/chant-lexicon-sql/clickhouse";
+import { shop } from "./database";
+import { orders } from "./orders";
+
+// Columns are referenced through .columns, which records the view's lineage.
+export const openOrders = view\`
+  CREATE VIEW \${shop}.open_orders AS
+  SELECT
+    \${orders.columns.id} AS id,
+    \${orders.columns.customer_id} AS customer_id,
+    \${orders.columns.total} AS total
+  FROM \${orders}
+  WHERE \${orders.columns.status} = 'open'\`;
+`;
+export const DEFAULT_TEMPLATE = {
+    src: {
+        "database.ts": DATABASE("shop", "Orders and customers"),
+        "orders.ts": DEFAULT_TABLES,
+        "views.ts": DEFAULT_VIEWS,
+    },
+};
+// ── events ─────────────────────────────────────────────────────────────
+const EVENTS_TABLE = `import { table } from "@intentius/chant-lexicon-sql/clickhouse";
+import { analytics } from "./database";
+
+// Raw events, kept 90 days. The TTL is a background rewrite when changed
+// (chant sql plan reports it as SQLCH205).
+export const events = table\`
+  CREATE TABLE \${analytics}.events (
+    user_id  UUID,
+    kind     LowCardinality(String),
+    ts       DateTime CODEC(Delta, ZSTD(3)),
+    props    Map(String, String)
+  )
+  ENGINE = MergeTree
+  PARTITION BY toYYYYMM(ts)
+  ORDER BY (kind, user_id, ts)
+  TTL ts + INTERVAL 90 DAY\`;
+`;
+const EVENTS_ROLLUP = `import { table, view } from "@intentius/chant-lexicon-sql/clickhouse";
+import { analytics } from "./database";
+import { events } from "./events";
+
+// Hourly counts and distinct users per kind. The rollup outlives the raw
+// events: it has no TTL.
+export const hourly = table\`
+  CREATE TABLE \${analytics}.events_hourly (
+    hour   DateTime,
+    kind   LowCardinality(String),
+    n      SimpleAggregateFunction(sum, UInt64),
+    users  AggregateFunction(uniq, UUID)
+  )
+  ENGINE = AggregatingMergeTree
+  PARTITION BY toYYYYMM(hour)
+  ORDER BY (kind, hour)\`;
+
+// The target of a materialized view is fixed when the view is created.
+export const hourlyMv = view\`
+  CREATE MATERIALIZED VIEW \${analytics}.events_hourly_mv TO \${hourly} AS
+  SELECT
+    toStartOfHour(\${events.columns.ts}) AS hour,
+    \${events.columns.kind} AS kind,
+    count() AS n,
+    uniqState(\${events.columns.user_id}) AS users
+  FROM \${events}
+  GROUP BY hour, kind\`;
+`;
+export const EVENTS_TEMPLATE = {
+    src: {
+        "database.ts": DATABASE("analytics", "Product analytics"),
+        "events.ts": EVENTS_TABLE,
+        "rollup.ts": EVENTS_ROLLUP,
+    },
+};
+// ── cdc ────────────────────────────────────────────────────────────────
+const CDC_TABLE = `import { table, view } from "@intentius/chant-lexicon-sql/clickhouse";
+import { mirror } from "./database";
+
+// A mirror of an upstream customers table. The CDC feed inserts a row per
+// change with a rising _version, and a delete as a row with _deleted = 1.
+// ReplacingMergeTree keeps the highest _version per sort key at merge time,
+// and the engine arguments cannot be changed in place later.
+export const customers = table\`
+  CREATE TABLE \${mirror}.customers (
+    id          UInt64,
+    email       String,
+    plan        LowCardinality(String) DEFAULT 'free',
+    _version    UInt64,
+    _deleted    UInt8 DEFAULT 0
+  )
+  ENGINE = ReplacingMergeTree(_version, _deleted)
+  ORDER BY id\`;
+
+// Merges are eventual, so read through FINAL (or this view) for the current rows.
+export const customersCurrent = view\`
+  CREATE VIEW \${mirror}.customers_current AS
+  SELECT
+    \${customers.columns.id} AS id,
+    \${customers.columns.email} AS email,
+    \${customers.columns.plan} AS plan
+  FROM \${customers} FINAL\`;
+`;
+export const CDC_TEMPLATE = {
+    src: {
+        "database.ts": DATABASE("mirror", "Replicated from the upstream database"),
+        "customers.ts": CDC_TABLE,
+    },
+};
+// ── Postgres ───────────────────────────────────────────────────────────
+//
+// `--template postgres`, `postgres-tenant` and `postgres-events`. Each builds
+// with the sql lexicon alone and lints clean.
+const PG_SCHEMA = (name, comment) => `import { schema } from "@intentius/chant-lexicon-sql/postgres";
+
+export const ${name} = schema\`
+  CREATE SCHEMA ${name};
+  COMMENT ON SCHEMA ${name} IS '${comment}'\`;
+`;
+const PG_USERS = `import { table } from "@intentius/chant-lexicon-sql/postgres";
+import { app } from "./schema";
+
+export const users = table\`
+  CREATE TABLE \${app}.users (
+    id         bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    email      text NOT NULL UNIQUE,
+    created_at timestamptz NOT NULL DEFAULT now()
+  );
+  COMMENT ON TABLE \${app}.users IS 'One row per account'\`;
+`;
+const PG_ORDERS = `import { index, table } from "@intentius/chant-lexicon-sql/postgres";
+import { app } from "./schema";
+import { users } from "./users";
+
+// The foreign key is a reference: orders is created after users.
+export const orders = table\`
+  CREATE TABLE \${app}.orders (
+    id         bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    user_id    bigint NOT NULL REFERENCES \${users} (\${users.columns.id}) ON DELETE CASCADE,
+    status     text NOT NULL DEFAULT 'placed',
+    amount     numeric(12, 2) NOT NULL CHECK (amount >= 0),
+    placed_at  timestamptz NOT NULL DEFAULT now()
+  )\`;
+
+// Postgres does not index a foreign key for you. An index needs a name: the
+// name is its identity on the server.
+export const ordersUser = index\`
+  CREATE INDEX orders_user_id_idx ON \${orders} (\${orders.columns.user_id}, \${orders.columns.placed_at} DESC)\`;
+`;
+const PG_VIEWS = `import { view } from "@intentius/chant-lexicon-sql/postgres";
+import { app } from "./schema";
+import { orders } from "./orders";
+import { users } from "./users";
+
+// Columns are referenced through .columns, which records the view's lineage.
+export const orderTotals = view\`
+  CREATE VIEW \${app}.order_totals WITH (security_invoker = true) AS
+  SELECT u.\${users.columns.id} AS user_id,
+         count(o.\${orders.columns.id}) AS order_count,
+         coalesce(sum(o.\${orders.columns.amount}), 0) AS total
+  FROM \${users} u
+  LEFT JOIN \${orders} o ON o.\${orders.columns.user_id} = u.\${users.columns.id}
+  GROUP BY u.\${users.columns.id}\`;
+`;
+export const POSTGRES_TEMPLATE = {
+    src: {
+        "schema.ts": PG_SCHEMA("app", "Accounts and orders"),
+        "users.ts": PG_USERS,
+        "orders.ts": PG_ORDERS,
+        "views.ts": PG_VIEWS,
+    },
+};
+const TENANT_TABLES = `import { table } from "@intentius/chant-lexicon-sql/postgres";
+import { app } from "./schema";
+
+export const tenants = table\`
+  CREATE TABLE \${app}.tenants (
+    id   bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    slug text NOT NULL UNIQUE
+  )\`;
+
+// Every tenant-owned table carries tenant_id and leads its primary key with it,
+// so a tenant's rows sit together and the key doubles as the tenant's index.
+export const projects = table\`
+  CREATE TABLE \${app}.projects (
+    tenant_id  bigint NOT NULL REFERENCES \${tenants} (\${tenants.columns.id}) ON DELETE CASCADE,
+    id         bigint GENERATED ALWAYS AS IDENTITY,
+    name       text NOT NULL,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (tenant_id, id)
+  )\`;
+`;
+const TENANT_TASKS = `import { index, table } from "@intentius/chant-lexicon-sql/postgres";
+import { app } from "./schema";
+import { projects } from "./tables";
+
+// The foreign key carries the tenant too, so a task cannot point at another
+// tenant's project.
+export const tasks = table\`
+  CREATE TABLE \${app}.tasks (
+    tenant_id  bigint NOT NULL,
+    id         bigint GENERATED ALWAYS AS IDENTITY,
+    project_id bigint NOT NULL,
+    title      text NOT NULL,
+    done       boolean NOT NULL DEFAULT false,
+    PRIMARY KEY (tenant_id, id),
+    FOREIGN KEY (tenant_id, project_id) REFERENCES \${projects} (\${projects.columns.tenant_id}, \${projects.columns.id}) ON DELETE CASCADE
+  )\`;
+
+// Every index leads with the tenant key.
+export const tasksProject = index\`
+  CREATE INDEX tasks_project_idx ON \${tasks} (\${tasks.columns.tenant_id}, \${tasks.columns.project_id})\`;
+
+export const tasksOpen = index\`
+  CREATE INDEX tasks_open_idx ON \${tasks} (\${tasks.columns.tenant_id}, \${tasks.columns.id}) WHERE NOT \${tasks.columns.done}\`;
+`;
+export const POSTGRES_TENANT_TEMPLATE = {
+    src: {
+        "schema.ts": PG_SCHEMA("app", "Multi-tenant application data"),
+        "tables.ts": TENANT_TABLES,
+        "tasks.ts": TENANT_TASKS,
+    },
+};
+const PG_EVENTS_TABLE = `import { index, table } from "@intentius/chant-lexicon-sql/postgres";
+import { analytics } from "./schema";
+
+// Partitioned by month. A primary key on a partitioned table must include the
+// partition key, hence (id, occurred_at).
+export const events = table\`
+  CREATE TABLE \${analytics}.events (
+    id          bigint GENERATED ALWAYS AS IDENTITY,
+    occurred_at timestamptz NOT NULL,
+    kind        text NOT NULL,
+    payload     jsonb NOT NULL DEFAULT '{}',
+    PRIMARY KEY (id, occurred_at)
+  ) PARTITION BY RANGE (occurred_at)\`;
+
+// An index on the parent is created on every partition.
+export const eventsKind = index\`
+  CREATE INDEX events_kind_idx ON \${events} (\${events.columns.kind}, \${events.columns.occurred_at})\`;
+`;
+const PG_EVENTS_PARTITIONS = `import { table } from "@intentius/chant-lexicon-sql/postgres";
+import { analytics } from "./schema";
+import { events } from "./events";
+
+// One partition per month, bounds [from, to). Add the next month ahead of time:
+// a row with no partition is an error.
+export const events202601 = table\`
+  CREATE TABLE \${analytics}.events_2026_01 PARTITION OF \${events}
+  FOR VALUES FROM ('2026-01-01') TO ('2026-02-01')\`;
+
+export const events202602 = table\`
+  CREATE TABLE \${analytics}.events_2026_02 PARTITION OF \${events}
+  FOR VALUES FROM ('2026-02-01') TO ('2026-03-01')\`;
+
+export const events202603 = table\`
+  CREATE TABLE \${analytics}.events_2026_03 PARTITION OF \${events}
+  FOR VALUES FROM ('2026-03-01') TO ('2026-04-01')\`;
+`;
+export const POSTGRES_EVENTS_TEMPLATE = {
+    src: {
+        "schema.ts": PG_SCHEMA("analytics", "Product analytics"),
+        "events.ts": PG_EVENTS_TABLE,
+        "partitions.ts": PG_EVENTS_PARTITIONS,
+    },
+};

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "df5c358d8382253ad577b461a81167e208a9fcb804524e8535b35efebe82aef6",
+    "manifest.json": "6d7e2a30284000b1667c910443a5ab73ed2944fb54df48a182652d2a2a3e4549",
     "meta.json": "59ca03876cce0d293e15a7f0a90ef7f250d133e46773c73fedede4a2ec792119",
     "types/index.d.ts": "0286ebb367773e84c76818b0f69cb14cff8328fd2f8c65ed87563c8d5815458c",
     "rules/postgres-templates.ts": "082da542239ab9f9627026972281102a61ca269cb79e2514f402dfc400ccdcde",
@@ -79,5 +79,5 @@
     "rules/sqlpg125.ts": "cc7411c57c525613dc720ba00e986bbc4e5a84b8b0bcfa7a6ce0d058f039f025",
     "rules/sqlpg126.ts": "d57b82a5842273876510131d67bf4418cbd61eff821e245edebc644dafd502bb"
   },
-  "composite": "785ccb05885083f9fb1cab0c4c8042d34b27bce38ece2de492dae3ad0eaae27f"
+  "composite": "248cf32e3f60e2998233ca8e6d9d1ca29b5555fae247163559b4359bd67e4f4c"
 }

package/dist/lint/audit-catalog.js

@@ -0,0 +1,31 @@
+/**
+ * The sql lexicon's chant audit catalog, contributed via `auditCatalog()`.
+ *
+ * Post-synth checks read the build's JSON output, so they are `yamlBased`. The
+ * source-level rules read TypeScript and are constructed with
+ * `yamlBased: false`; they are listed for a reader who meets them in a report.
+ */
+import { applyLineage, auditRule } from "@intentius/chant/audit/catalog";
+import { sqlPostSynthAuditEntries } from "./post-synth/audit-entries.js";
+import { postgresPostSynthAuditEntries } from "./post-synth/postgres-audit-entries.js";
+import { sqlAuditLineage } from "./audit-lineage.js";
+function sourceRule(id, category, title, remediation) {
+    return { id, tier: "merge-worthy", fixKind: "guidance", category, title, remediation, yamlBased: false };
+}
+export const sqlAuditCatalog = {
+    SQLCH001: sourceRule("SQLCH001", "correctness", "ClickHouse DDL in a database, table or view template does not parse", "Fix the statement at the token the message names."),
+    SQLCH002: sourceRule("SQLCH002", "correctness", "A Nullable column in a ClickHouse sort key or primary key", "Make the column non-Nullable, drop it from the key, or set allow_nullable_key = 1 on the table."),
+    SQLCH003: sourceRule("SQLCH003", "correctness", "A column interpolated without .columns reads the entity's own field instead", "Write ${table.columns.name}."),
+    SQLCH004: sourceRule("SQLCH004", "correctness", "A typed ClickHouse tag's type argument does not name the object its template declares, or is not in sql-types.d.ts", "Make the type argument the qualified name the template declares, then run chant sql types."),
+    SQLPG001: sourceRule("SQLPG001", "correctness", "Postgres DDL in a tagged template does not parse, or holds another statement than its tag", "Fix the statement at the token the message names, or use the tag for the statement it holds; name every index."),
+    SQLPG002: sourceRule("SQLPG002", "correctness", "A column interpolated without .columns reads the entity's own field instead", "Write ${table.columns.name}."),
+    SQLPG003: sourceRule("SQLPG003", "correctness", "A sequence or relation named in a regclass string makes no reference", "Interpolate the declared object: nextval(${sequence}) or ${relation}::regclass."),
+    SQLPG004: sourceRule("SQLPG004", "correctness", "A declared extension the configured Postgres provider does not allow", "Use an extension the provider lists, or set sql.provider to the service the project deploys to."),
+    SQLPG005: sourceRule("SQLPG005", "correctness", "A typed Postgres tag's type argument does not name the object its template declares, or is not in sql-types.d.ts", "Make the type argument the qualified name the template declares, then run chant sql types."),
+    SQLCH101: auditRule("SQLCH101", "merge-worthy", "guidance", "A ClickHouse object names an engine the pinned server does not have", "Use an engine from the pinned server's system.table_engines (or system.database_engines for a database).", { category: "correctness" }),
+    SQL101: auditRule("SQL101", "merge-worthy", "guidance", "Two exports declare the same object", "Keep one declaration of the object and import it where the other was used.", { category: "correctness" }),
+    SQL102: auditRule("SQL102", "merge-worthy", "guidance", "sql-types.d.ts differs from what the build declares", "Run chant sql types to rewrite the file.", { category: "correctness" }),
+    ...sqlPostSynthAuditEntries,
+    ...postgresPostSynthAuditEntries,
+};
+applyLineage(sqlAuditCatalog, sqlAuditLineage);

package/dist/lint/audit-lineage.js

@@ -0,0 +1,22 @@
+const squawk = (rule, relation) => ({ tool: "squawk", rule, url: `https://squawkhq.com/docs/${rule}`, relation });
+const wiki = (rule, anchor) => ({
+    tool: "postgres-wiki-dont-do-this",
+    rule,
+    url: `https://wiki.postgresql.org/wiki/Don%27t_Do_This#${anchor}`,
+    relation: "overlaps",
+});
+export const sqlAuditLineage = {
+    SQLPG103: [squawk("prefer-identity", "equivalent"), wiki("Don't use serial", "Don.27t_use_serial")],
+    SQLPG104: [squawk("prefer-timestamptz", "equivalent"), wiki("Don't use timestamp (without time zone)", "Don.27t_use_timestamp_.28without_time_zone.29")],
+    SQLPG105: [
+        {
+            tool: "strong_migrations",
+            rule: "Adding a json column",
+            url: "https://github.com/ankane/strong_migrations#adding-a-json-column",
+            relation: "overlaps",
+        },
+    ],
+    SQLPG106: [squawk("ban-char-field", "equivalent"), wiki("Don't use char(n)", "Don.27t_use_char.28n.29")],
+    SQLPG107: [wiki("Don't use money", "Don.27t_use_money")],
+    SQLPG108: [squawk("prefer-text-field", "overlaps"), wiki("Don't use varchar(n) by default", "Don.27t_use_varchar.28n.29_by_default")],
+};

package/dist/lint/post-synth/audit-entries.js

@@ -0,0 +1,34 @@
+/**
+ * Audit metadata for the ClickHouse post-synth checks (SQLCH1xx). Spread into
+ * `sqlAuditCatalog` by ../audit-catalog.ts. Deprecation checks are filed under
+ * best-practice: the audit categories have no deprecation of their own.
+ */
+import { auditRule } from "@intentius/chant/audit/catalog";
+export const sqlPostSynthAuditEntries = {
+    SQLCH102: auditRule("SQLCH102", "merge-worthy", "guidance", "A PRIMARY KEY that is not a prefix of ORDER BY", "Make the primary key a leading prefix of the sort key, or drop it to use the sort key.", { category: "correctness" }),
+    SQLCH103: auditRule("SQLCH103", "merge-worthy", "guidance", "An engine's version, sign or is_deleted column has an unsupported type", "Use UInt*, Date, DateTime or DateTime64 for a version, Int8 for a sign, UInt8 for is_deleted.", { category: "correctness" }),
+    SQLCH104: auditRule("SQLCH104", "merge-worthy", "guidance", "A MergeTree engine argument names a column the table does not declare", "Declare the column, or fix the name in the engine arguments.", { category: "correctness" }),
+    SQLCH105: auditRule("SQLCH105", "merge-worthy", "guidance", "A table key clause names a column the table does not declare", "Declare the column, or fix the name in ORDER BY, PRIMARY KEY, PARTITION BY or SAMPLE BY.", { category: "correctness" }),
+    SQLCH106: auditRule("SQLCH106", "merge-worthy", "guidance", "A skip index expression names a column the table does not declare", "Declare the column, or fix the index expression.", { category: "correctness" }),
+    SQLCH107: auditRule("SQLCH107", "merge-worthy", "guidance", "A TTL expression is built on a column that is not a Date or DateTime", "Base the TTL on a Date or DateTime column, or convert it in the expression.", { category: "correctness" }),
+    SQLCH108: auditRule("SQLCH108", "merge-worthy", "guidance", "CREATE OR REPLACE TABLE in a database that is not Atomic", "Create the database with ENGINE = Atomic or Replicated, or drop OR REPLACE.", { category: "correctness" }),
+    SQLCH109: auditRule("SQLCH109", "report-only", "guidance", "A materialized view selects *", "List the columns the view writes.", { category: "best-practice" }),
+    SQLCH110: auditRule("SQLCH110", "report-only", "guidance", "A materialized view writes a column its TO target does not declare", "Add the column to the target table, or drop it from the SELECT.", { category: "correctness" }),
+    SQLCH111: auditRule("SQLCH111", "report-only", "guidance", "A String column limited to a few values is not LowCardinality", "Declare the column LowCardinality(String).", { category: "best-practice" }),
+    SQLCH112: auditRule("SQLCH112", "report-only", "guidance", "A PARTITION BY expression is finer than a day", "Partition by month (toYYYYMM) or day, and keep the finer time in ORDER BY.", { category: "best-practice" }),
+    SQLCH113: auditRule("SQLCH113", "merge-worthy", "guidance", "A MergeTree table declares no sort key", "Add ORDER BY, or ORDER BY tuple() for no sorting.", { category: "correctness" }),
+    SQLCH114: auditRule("SQLCH114", "merge-worthy", "guidance", "A column codec is not one the pinned server has", "Use a codec from the pinned server's system.codecs.", { category: "correctness" }),
+    SQLCH115: auditRule("SQLCH115", "report-only", "guidance", "A secret- or PII-named column carries no comment, TTL or encryption", "Add a COMMENT saying what it holds, a TTL that bounds retention, or an AES_*_GCM_SIV codec.", { category: "security" }),
+    SQLCH116: auditRule("SQLCH116", "report-only", "guidance", "A view is SQL SECURITY DEFINER with no DEFINER", "Write DEFINER = <user> before SQL SECURITY DEFINER.", { category: "security" }),
+    SQLCH117: auditRule("SQLCH117", "report-only", "guidance", "A MergeTree setting is obsolete at the pinned server", "Remove the setting; the server ignores it.", { category: "best-practice" }),
+    SQLCH118: auditRule("SQLCH118", "merge-worthy", "guidance", "A MergeTree setting is not one the pinned server has", "Fix the setting name, or pick a setting from the pinned server's system.merge_tree_settings.", { category: "correctness" }),
+    SQLCH119: auditRule("SQLCH119", "report-only", "guidance", "An object uses a deprecated or experimental engine", "Use the engine that replaced it (Atomic for Ordinary), or accept the experimental engine knowingly.", { category: "best-practice" }),
+    SQLCH120: auditRule("SQLCH120", "report-only", "guidance", "A MergeTree engine uses the deprecated positional arguments", "Write a bare MergeTree with ORDER BY, PARTITION BY and SETTINGS.", { category: "best-practice" }),
+    SQLCH121: auditRule("SQLCH121", "merge-worthy", "guidance", "A column type names a family the pinned server does not have", "Use a type family from the pinned server's system.data_type_families, in the case it lists unless it is case-insensitive.", { category: "correctness" }),
+    SQLCH122: auditRule("SQLCH122", "merge-worthy", "guidance", "A column type's parameters do not fit its family", "Give the family the parameters it takes, each within its range.", { category: "correctness" }),
+    SQLCH123: auditRule("SQLCH123", "merge-worthy", "guidance", "A Nullable wraps a type ClickHouse does not allow inside Nullable", "Move Nullable inside (Array(Nullable(T)), LowCardinality(Nullable(T))) or drop it.", { category: "correctness" }),
+    SQLCH124: auditRule("SQLCH124", "merge-worthy", "guidance", "A table declares a column twice", "Remove or rename one of the two columns.", { category: "correctness" }),
+    SQLCH125: auditRule("SQLCH125", "merge-worthy", "guidance", "A codec parameter is outside what the codec takes", "Give the codec a parameter within its range or set, or drop the parameter for the default.", { category: "correctness" }),
+    SQLCH126: auditRule("SQLCH126", "merge-worthy", "guidance", "A GRANT column list names a column the table does not declare", "Fix the column name, or declare the column on the table.", { category: "correctness" }),
+    SQLCH127: auditRule("SQLCH127", "merge-worthy", "guidance", "An expression calls a function the pinned server does not have", "Fix the function name, use one from the pinned server's system.functions, or declare it with func.", { category: "correctness" }),
+};

package/dist/lint/post-synth/clickhouse-helpers.js

@@ -0,0 +1,79 @@
+/**
+ * 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 { baseEngineName, splitTop } from "../../clickhouse/expressions.js";
+import { readClickHouse } from "../../read/clickhouse.js";
+import { clickhouseObjects } from "./sql-helpers.js";
+export { bareName, baseEngineName, engineSpec, isMergeTree, isNullableType, keyElements, splitTop, typeFamily, unwrapType, } from "../../clickhouse/expressions.js";
+export const isTable = (o) => o.type === "ClickHouse::Table";
+export const isMaterializedView = (o) => o.type === "ClickHouse::MaterializedView";
+export const isAnyView = (o) => o.type === "ClickHouse::View" || o.type === "ClickHouse::MaterializedView";
+/** The build's tables as the public read API types them (`@intentius/chant-lexicon-sql/read`), so a project policy reads what the checks read. */
+export function tablesOf(ctx) {
+    return readClickHouse(ctx).tables;
+}
+/** The build's views and materialized views, as the public read API types them. */
+export function viewsOf(ctx) {
+    return readClickHouse(ctx).views;
+}
+/**
+ * The engine's own arguments, after the ZooKeeper path and replica name a
+ * `Replicated*` engine may lead with.
+ */
+export function engineArguments(engine) {
+    const args = engine.args ?? [];
+    if (baseEngineName(engine) !== engine.name && args.length >= 2 && /^['{]/.test(args[0].trim()))
+        return args.slice(2);
+    return args;
+}
+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) {
+    const names = [];
+    const re = /'(?:[^'\\]|\\.)*'|`((?:[^`]|``)*)`|"((?:[^"]|"")*)"|\b([A-Za-z_][A-Za-z0-9_]*)\b(\s*\()?|\d[\w.]*/g;
+    let m;
+    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;
+}
+export function columnByName(table, name) {
+    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, run) {
+    return {
+        ...meta,
+        check(ctx) {
+            const out = [];
+            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, ref) {
+    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) {
+    return splitTop(codec)
+        .map((c) => /^[A-Za-z_][\w]*/.exec(c.trim())?.[0])
+        .filter((n) => n !== undefined);
+}