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

package/src/import-generator.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 type { GeneratedFile, TypeScriptGenerator } from "@intentius/chant/import/generator";
+import type { TemplateIR } from "@intentius/chant/import/parser";
+import { ClickHouseGenerator } from "./clickhouse/import/generator";
+import { PostgresGenerator } from "./postgres/import/generator";
+
+export const sqlTemplateGenerator: TypeScriptGenerator = {
+  ownsLayout: true,
+  generate(ir: TemplateIR): GeneratedFile[] {
+    const postgres = ir.resources.some((r) => r.type.startsWith("Postgres::"));
+    return (postgres ? new PostgresGenerator() : new ClickHouseGenerator()).generate(ir);
+  },
+};

package/src/index.ts

@@ -0,0 +1,21 @@
+// 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";
+export { sqlSerializer } from "./serializer";
+export { SQL_DIALECTS, type SqlDialect } from "./dialects";
+export { sqlConfigSchema, type SqlConfig } from "./config";
+
+// 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, literal } from "./clickhouse/entities";
+
+// 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 } from "./postgres/entities";

package/src/init-templates.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { build } from "@intentius/chant/build";
+import { lintCommand } from "@intentius/chant/cli/commands/lint";
+import { runPostSynthChecks } from "@intentius/chant/lint/post-synth";
+import { sqlPlugin } from "./plugin";
+import { postSynthChecks } from "./lint/post-synth";
+import { detectTemplate } from "./detect";
+
+const cases: Array<[string | undefined, string[]]> = [
+  [undefined, ["shop", "orders", "openOrders"]],
+  ["events", ["analytics", "events", "hourly", "hourlyMv"]],
+  ["cdc", ["mirror", "customers", "customersCurrent"]],
+  ["postgres", ["app", "users", "orders", "ordersUser", "orderTotals"]],
+  ["postgres-tenant", ["app", "tenants", "projects", "tasks", "tasksProject", "tasksOpen"]],
+  ["postgres-events", ["analytics", "events", "eventsKind", "events202601", "events202602", "events202603"]],
+];
+
+describe("init templates", () => {
+  test.each(cases)("%s builds, lints clean and passes every check", async (name, exports) => {
+    const set = sqlPlugin.initTemplates!(name);
+    const dir = mkdtempSync(join(import.meta.dirname, "..", ".init-template-"));
+    try {
+      mkdirSync(join(dir, "src"));
+      for (const [file, text] of Object.entries(set.src)) writeFileSync(join(dir, "src", file), text);
+      for (const [file, text] of Object.entries(set.root ?? {})) writeFileSync(join(dir, file), text);
+      const result = await build(join(dir, "src"), [sqlPlugin.serializer]);
+      expect(result.errors).toEqual([]);
+
+      const out = result.outputs.get("sql") as { primary: string; files: Record<string, string> };
+      expect(out).toBeTruthy();
+      const doc = JSON.parse(out.primary) as { applyOrder: string[] };
+      expect([...doc.applyOrder].sort()).toEqual([...exports].sort());
+      // Every template's own output is recognized as a sql project.
+      expect(detectTemplate(doc)).toBe(true);
+
+      expect(runPostSynthChecks(postSynthChecks, result)).toEqual([]);
+
+      const lint = await lintCommand({ path: join(dir, "src"), format: "stylish", fix: false });
+      expect(lint.errorCount + lint.warningCount, lint.output).toBe(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("an unknown template name falls back to the default", () => {
+    expect(sqlPlugin.initTemplates!("nope")).toBe(sqlPlugin.initTemplates!());
+  });
+
+  test("the events template carries a TTL and a rollup written by a materialized view", () => {
+    const src = sqlPlugin.initTemplates!("events").src;
+    expect(src["events.ts"]).toContain("TTL ts + INTERVAL 90 DAY");
+    expect(src["rollup.ts"]).toContain("CREATE MATERIALIZED VIEW");
+  });
+
+  test("the postgres templates declare a dialect-true document", async () => {
+    for (const name of ["postgres", "postgres-tenant", "postgres-events"]) {
+      const set = sqlPlugin.initTemplates!(name);
+      for (const text of Object.values(set.src)) expect(text).toContain("@intentius/chant-lexicon-sql/postgres");
+    }
+    expect(sqlPlugin.initTemplates!("postgres-events").src["events.ts"]).toContain("PARTITION BY RANGE (occurred_at)");
+    expect(sqlPlugin.initTemplates!("postgres-tenant").src["tasks.ts"]).toContain("(\${tasks.columns.tenant_id}, \${tasks.columns.project_id})");
+  });
+
+  test("the cdc template is a ReplacingMergeTree with a version column", () => {
+    expect(sqlPlugin.initTemplates!("cdc").src["customers.ts"]).toContain("ReplacingMergeTree(_version, _deleted)");
+  });
+});
+
+describe("detectTemplate", () => {
+  const build = {
+    dialect: "clickhouse",
+    applyOrder: ["a", "t"],
+    objects: [{ export: "a", type: "ClickHouse::Database" }, { export: "t", type: "ClickHouse::Table" }],
+  };
+
+  test("recognizes a sql build output", () => {
+    expect(sqlPlugin.detectTemplate!(build)).toBe(true);
+  });
+
+  test("recognizes a Postgres build output", () => {
+    expect(
+      sqlPlugin.detectTemplate!({
+        dialect: "postgres",
+        applyOrder: ["app", "users"],
+        objects: [{ export: "app", type: "Postgres::Schema" }, { export: "users", type: "Postgres::Table" }],
+      }),
+    ).toBe(true);
+  });
+
+  test("a document whose types are another dialect's is not claimed", () => {
+    expect(sqlPlugin.detectTemplate!({ dialect: "postgres", applyOrder: ["t"], objects: [{ type: "ClickHouse::Table" }] })).toBe(false);
+    expect(sqlPlugin.detectTemplate!({ dialect: "mysql", applyOrder: ["t"], objects: [{ type: "MySql::Table" }] })).toBe(false);
+  });
+
+  test.each([
+    ["null", null],
+    ["an array", []],
+    ["no objects", { dialect: "clickhouse", applyOrder: [], objects: [] }],
+    ["no dialect", { applyOrder: ["t"], objects: [{ type: "ClickHouse::Table" }] }],
+    ["an untyped object", { dialect: "clickhouse", applyOrder: ["t"], objects: [{ export: "t" }] }],
+    ["a dashboard", { panels: [], schemaVersion: 39 }],
+    ["a prometheus rule file", { groups: [{ name: "g", rules: [{ record: "r", expr: "up" }] }] }],
+  ])("does not claim %s", (_name, data) => {
+    expect(sqlPlugin.detectTemplate!(data)).toBe(false);
+  });
+});

package/src/init-templates.ts

@@ -0,0 +1,327 @@
+/**
+ * `chant init --lexicon sql` scaffolds, all ClickHouse.
+ *
+ * - default: a database, one MergeTree table and a view that reads it.
+ * - `events`: an events table with a partition key and a TTL, and a rollup
+ *   (an AggregatingMergeTree target and the materialized view that fills it).
+ * - `cdc`: a mirror of an upstream table kept by a CDC feed: a
+ *   ReplacingMergeTree table with a version column and a delete flag, and a
+ *   view of the current rows.
+ *
+ * Each builds with the sql lexicon alone and passes its post-synth checks.
+ */
+import type { InitTemplateSet } from "@intentius/chant/lexicon";
+
+const DATABASE = (name: string, comment: string) => `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: InitTemplateSet = {
+  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: InitTemplateSet = {
+  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: InitTemplateSet = {
+  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: string, comment: string) => `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: InitTemplateSet = {
+  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: InitTemplateSet = {
+  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: InitTemplateSet = {
+  src: {
+    "schema.ts": PG_SCHEMA("analytics", "Product analytics"),
+    "events.ts": PG_EVENTS_TABLE,
+    "partitions.ts": PG_EVENTS_PARTITIONS,
+  },
+};

package/src/lint/audit-catalog.ts

@@ -0,0 +1,73 @@
+/**
+ * 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, type RuleMeta } from "@intentius/chant/audit/catalog";
+import { sqlPostSynthAuditEntries } from "./post-synth/audit-entries";
+import { postgresPostSynthAuditEntries } from "./post-synth/postgres-audit-entries";
+import { sqlAuditLineage } from "./audit-lineage";
+
+function sourceRule(id: string, category: RuleMeta["category"], title: string, remediation: string): RuleMeta {
+  return { id, tier: "merge-worthy", fixKind: "guidance", category, title, remediation, yamlBased: false };
+}
+
+export const sqlAuditCatalog: Record<string, RuleMeta> = {
+  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}.",
+  ),
+  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.",
+  ),
+  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" },
+  ),
+  ...sqlPostSynthAuditEntries,
+  ...postgresPostSynthAuditEntries,
+};
+
+applyLineage(sqlAuditCatalog, sqlAuditLineage);

package/src/lint/audit-lineage.ts

@@ -0,0 +1,47 @@
+/**
+ * Prior art for the sql lexicon's audit rules: the tools whose checks cover the
+ * same condition, credited per rule. See packages/core/src/audit/prior-art.ts
+ * for the registry and the relation vocabulary. Kept by hand.
+ *
+ * Mapped against #3285's seed list (squawk, strong_migrations,
+ * django-pg-zero-downtime-migrations). Those tools are migration linters: the
+ * rules that overlap a schema-level check are the type preferences.
+ *
+ * - squawk (https://squawkhq.com/docs/rules) prefer-identity,
+ *   prefer-timestamptz, ban-char-field and prefer-text-field.
+ * - strong_migrations "Adding a json column": the json type has no equality
+ *   operator, the same reason SQLPG105 prefers jsonb.
+ * - django-pg-zero-downtime-migrations has no rule on a column's type or an
+ *   index's shape; its rules are about locks, which the lock classifier
+ *   (SQLPG2xx) covers, so it is not credited here.
+ * - The Postgres wiki "Don't Do This" page names serial, timestamp, char(n),
+ *   money and varchar(n) as types to avoid.
+ *
+ * SQLPG101-102, 109-118 have no tool credit: the checks come from the
+ * Postgres documentation each one cites.
+ */
+import type { Lineage } from "@intentius/chant/audit/catalog";
+
+const squawk = (rule: string, relation: Lineage["relation"]): Lineage => ({ tool: "squawk", rule, url: `https://squawkhq.com/docs/${rule}`, relation });
+const wiki = (rule: string, anchor: string): Lineage => ({
+  tool: "postgres-wiki-dont-do-this",
+  rule,
+  url: `https://wiki.postgresql.org/wiki/Don%27t_Do_This#${anchor}`,
+  relation: "overlaps",
+});
+
+export const sqlAuditLineage: Record<string, Lineage[]> = {
+  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/src/lint/post-synth/audit-entries.ts

@@ -0,0 +1,29 @@
+/**
+ * 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, type RuleMeta } from "@intentius/chant/audit/catalog";
+
+export const sqlPostSynthAuditEntries: Record<string, RuleMeta> = {
+  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" }),
+};