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

package/src/spec/postgres-pin.ts

@@ -0,0 +1,101 @@
+/**
+ * The pinned Postgres servers the Postgres dialect's types come from.
+ *
+ * Postgres publishes no schema for its DDL either. Types, access methods,
+ * operator classes, settings, keywords, function names and extensions are read
+ * from a running server's catalog (chant #3277), so a pin is a server image.
+ * One snapshot per supported major, 14 to 18 (14 leaves community support in
+ * November 2026, and dropping it is deleting its entry and its snapshot), and
+ * the generated types are the union of the five with a `since` and an `until`
+ * major on every entry that is not in all of them.
+ *
+ * Each entry pins an exact minor by tag and by digest. The type surface does
+ * not move between minors (17.9 against 17.11 differs by one setting), but a
+ * floating `18` tag would change generated output with no commit, and a
+ * re-pushed tag must not change it unseen either: generation runs
+ * `image@digest` and refuses a server whose `server_version` is not the
+ * entry's version. The digest is the multi-arch manifest list's.
+ *
+ * Moving a pin: change that major's `version` and `digest` on its one line,
+ * then `chant dev generate` (or `npm run generate`). The committed snapshot no
+ * longer matches, so generation starts that image, rewrites
+ * `src/spec/postgres-catalog-<major>.snapshot.json`, and the pull request's
+ * diff of that file is the surface change. Read its `-` lines: a removed
+ * setting or function is what breaks declarations. Adding a major is one more
+ * line here and one more snapshot.
+ *
+ * The lines are written one per major, in this exact shape, because
+ * {@link postgresUpstreamPin} finds a major's version with a regular
+ * expression over its line.
+ */
+
+import type { UpstreamPin } from "@intentius/chant/lexicon";
+
+export interface PostgresPin {
+  /** The major, as `server_version_num / 10000`. */
+  major: number;
+  /** The exact minor, as `server_version` reports it with the Debian build suffix removed, and the docker tag. */
+  version: string;
+  /** The image digest of `postgres:<version>`. Move it with the version. */
+  digest: string;
+}
+
+/** The official server image. */
+export const POSTGRES_IMAGE_REPOSITORY = "postgres";
+
+/** One pin per supported major, oldest first. */
+export const POSTGRES_PINS: readonly PostgresPin[] = [
+  { major: 14, version: "14.24", digest: "sha256:c2427de38f998489d36de7ca3553db2134872c400f2b08be4b824e5c50e4d619" },
+  { major: 15, version: "15.19", digest: "sha256:724292da1f2e50bdccfc3302ce75bbba7f4a6076701b588cc795fcac65683550" },
+  { major: 16, version: "16.15", digest: "sha256:1a6ab3f5345eb6dbe04a1349529caabdb0ab09293a09590fad07b2246bfa4b54" },
+  { major: 17, version: "17.11", digest: "sha256:d74eeac9a635390a49bc21bd49fccd973de707e2a53a76ac49b552b8712ec46f" },
+  { major: 18, version: "18.6", digest: "sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722" },
+];
+
+/** The supported majors, oldest first. */
+export const POSTGRES_MAJORS: readonly number[] = POSTGRES_PINS.map((p) => p.major);
+
+/** The latest supported major: the emulator image and the default for a project that names no version. */
+export const POSTGRES_LATEST_MAJOR = POSTGRES_MAJORS[POSTGRES_MAJORS.length - 1]!;
+
+export function postgresPin(major: number): PostgresPin {
+  const pin = POSTGRES_PINS.find((p) => p.major === major);
+  if (!pin) throw new Error(`Postgres ${major} is not a supported major (${POSTGRES_MAJORS.join(", ")})`);
+  return pin;
+}
+
+/** The full image reference generation runs: tag for the reader, digest for the runtime. */
+export function postgresImage(major: number): string {
+  const pin = postgresPin(major);
+  return `${POSTGRES_IMAGE_REPOSITORY}:${pin.version}@${pin.digest}`;
+}
+
+/**
+ * `postgres/postgres` publishes no GitHub releases, only tags: `REL_18_6`,
+ * `REL_18_BETA1`, `REL_18_RC1`, `REL9_6_24`, `Release_2_0`. A stable release
+ * maps to `18.6`; every other spelling is skipped.
+ */
+export function versionFromReleaseTag(tag: string): string | null {
+  const m = /^REL_(\d+)_(\d+)$/.exec(tag);
+  return m ? `${m[1]}.${m[2]}` : null;
+}
+
+/**
+ * The upstream pin descriptor for one major's line in this file, labelled
+ * `postgres-<major>`. The sql plugin lists all five in `upstreamPins` beside
+ * ClickHouse's `upstreamPin`, so `chant dev pinned-upgrade` and the upgrade Op
+ * report each. Each tracks only its own major (`trackMajor`), so the 17 pin
+ * reports `17.12` and never `18.6`.
+ */
+export function postgresUpstreamPin(major: number): UpstreamPin & { readonly label: string } {
+  postgresPin(major);
+  return {
+    label: `postgres-${major}`,
+    file: "src/spec/postgres-pin.ts",
+    pattern: new RegExp(`\\{ major: ${major}, version: "([^"]+)"`),
+    replace: (v: string, line: string) =>
+      line.replace(/version: "[^"]+"/, `version: "${versionFromReleaseTag(v) ?? v}"`),
+    alsoMoves: `the digest on the same line of src/spec/postgres-pin.ts moves with the version: set version to the new minor, set digest to that tag's image digest (docker buildx imagetools inspect postgres:<version>), then run \`chant dev generate\` and read the diff of src/spec/postgres-catalog-${major}.snapshot.json. A git tag lands a few days before its image tag, so the report can name a version that has no image yet.`,
+    upstream: { owner: "postgres", repo: "postgres", kind: "tags", tagVersion: versionFromReleaseTag, trackMajor: true },
+  };
+}

package/src/typecheck.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Type-level guarantees of the ClickHouse dialect: the tags' return types, what
+ * an entity exposes, and the name unions generated from the pinned server's
+ * catalog. Each `@ts-expect-error` line must fail to compile:
+ * `tsconfig.typecheck.json` (scripts/typecheck.ts in CI) fails on an unused one,
+ * so a type that starts accepting what it used to reject breaks the build. The
+ * invalid code sits in functions that are never called, so nothing here throws
+ * at runtime.
+ */
+import type { AttrRef } from "@intentius/chant/attrref";
+import { describe, expectTypeOf, test } from "vitest";
+import {
+  database,
+  literal,
+  table,
+  view,
+  type ClickHouseDatabase,
+  type ClickHouseTable,
+  type ClickHouseView,
+  type CodecName,
+  type DatabaseEngineName,
+  type MergeTreeSettings,
+  type SkipIndexType,
+  type SqlLiteral,
+  type TableEngineName,
+} from "./clickhouse";
+
+describe("the tags", () => {
+  test("each returns its entity, and a table and a view expose their columns by name", () => {
+    const db = database`CREATE DATABASE analytics ENGINE = Atomic`;
+    const events = table`CREATE TABLE ${db}.events (user_id UUID) ENGINE = MergeTree ORDER BY user_id`;
+    const recent = view`CREATE VIEW ${db}.recent AS SELECT ${events.columns.user_id} FROM ${events}`;
+
+    expectTypeOf(db).toEqualTypeOf<ClickHouseDatabase>();
+    expectTypeOf(events).toEqualTypeOf<ClickHouseTable>();
+    expectTypeOf(recent).toEqualTypeOf<ClickHouseView>();
+    expectTypeOf(events.columns.user_id).toEqualTypeOf<AttrRef>();
+    expectTypeOf(events.entityType).toEqualTypeOf<"ClickHouse::Table">();
+    expectTypeOf(db.entityType).toEqualTypeOf<"ClickHouse::Database">();
+    expectTypeOf(recent.entityType).toEqualTypeOf<"ClickHouse::View" | "ClickHouse::MaterializedView">();
+    expectTypeOf(events.props.columns[0]!.name).toBeString();
+
+    const rejected = () => [
+      // @ts-expect-error a tag takes a template, not a string
+      table("CREATE TABLE t (a UInt8) ENGINE = Log"),
+      // @ts-expect-error a database has no columns to reference
+      db.columns,
+      // @ts-expect-error the column record is read-only
+      (events.columns.user_id = events.columns.user_id),
+      // @ts-expect-error a table's props carry no SELECT; that is a view's
+      events.props.select,
+    ];
+    void rejected;
+  });
+
+  test("literal renders a value, and only a scalar", () => {
+    expectTypeOf(literal("free")).toEqualTypeOf<SqlLiteral>();
+    literal(42);
+    literal(null);
+
+    const rejected = () => [
+      // @ts-expect-error an object is not a scalar value
+      literal({ a: 1 }),
+      // @ts-expect-error undefined is not a value either
+      literal(undefined),
+    ];
+    void rejected;
+  });
+});
+
+describe("names generated from the pinned server's catalog", () => {
+  test("engines, codecs and skip index types are the server's own", () => {
+    const engine: TableEngineName = "ReplacingMergeTree";
+    const dbEngine: DatabaseEngineName = "Atomic";
+    const codec: CodecName = "ZSTD";
+    const index: SkipIndexType = "bloom_filter";
+    void [engine, dbEngine, codec, index];
+
+    const rejected = () => [
+      // @ts-expect-error not a ClickHouse table engine
+      "InnoDB" satisfies TableEngineName,
+      // @ts-expect-error a table engine is not a database engine
+      "MergeTree" satisfies DatabaseEngineName,
+      // @ts-expect-error not a ClickHouse codec
+      "SNAPPY" satisfies CodecName,
+      // @ts-expect-error not a skip index type
+      "btree" satisfies SkipIndexType,
+    ];
+    void rejected;
+  });
+
+  test("a MergeTree setting is typed by what the server reports", () => {
+    const settings: MergeTreeSettings = { index_granularity: 8192, min_bytes_for_wide_part: 0 };
+    expectTypeOf(settings.index_granularity).toEqualTypeOf<number | undefined>();
+
+    const rejected = () => [
+      // @ts-expect-error a granularity is a number
+      { index_granularity: "8192" } satisfies MergeTreeSettings,
+      // @ts-expect-error not a MergeTree setting at the pin
+      { no_such_setting: 1 } satisfies MergeTreeSettings,
+    ];
+    void rejected;
+  });
+});

package/src/validate-cli.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env tsx
+import { printValidationResult } from "@intentius/chant/codegen/validate";
+import { validate } from "./validate";
+
+// printValidationResult throws when a check failed, so `npm run validate` (and prepack) exits non-zero.
+printValidationResult(await validate());

package/src/validate.ts

@@ -0,0 +1,149 @@
+/**
+ * Validate the sql lexicon's generated artifacts.
+ *
+ * The core checks (the registry parses, `index.d.ts` exists and compiles), plus
+ * the ClickHouse catalog's own: the generated tables exist, the committed
+ * snapshot is at the pin, and the names a schema leans on hardest are still
+ * in it. A pin move that drops one of those would otherwise surface as lint
+ * going quiet, not as a failure.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts, type ValidateCheck, type ValidateResult } from "@intentius/chant/codegen/validate";
+import { CLICKHOUSE_VERSION } from "./spec/pin";
+import { parseCatalog } from "./spec/catalog";
+import { POSTGRES_PINS } from "./spec/postgres-pin";
+import { parseCatalog as parsePostgresCatalog } from "./spec/postgres-catalog";
+
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+
+/** The entity kinds the registry must carry. */
+const REQUIRED_ENTITIES = [
+  "Database",
+  "Table",
+  "View",
+  "MaterializedView",
+  "PostgresSchema",
+  "PostgresTable",
+  "PostgresIndex",
+  "PostgresView",
+  "PostgresMaterializedView",
+  "PostgresSequence",
+  "PostgresEnum",
+  "PostgresDomain",
+  "PostgresExtension",
+];
+
+/** Engines a ClickHouse schema declares most: the MergeTree family and the engines beside it. */
+const REQUIRED_ENGINES = [
+  "MergeTree",
+  "ReplacingMergeTree",
+  "SummingMergeTree",
+  "AggregatingMergeTree",
+  "CollapsingMergeTree",
+  "VersionedCollapsingMergeTree",
+  "ReplicatedMergeTree",
+  "ReplicatedReplacingMergeTree",
+  "Distributed",
+  "Buffer",
+  "Memory",
+  "Null",
+  "MaterializedView",
+  "View",
+];
+
+/** Column type families the parser and the sort-key rules reason about. */
+const REQUIRED_TYPE_FAMILIES = [
+  "String",
+  "UInt64",
+  "Int64",
+  "Float64",
+  "DateTime",
+  "DateTime64",
+  "Date",
+  "UUID",
+  "Decimal",
+  "Nullable",
+  "LowCardinality",
+  "Array",
+  "Map",
+  "Tuple",
+  "Enum8",
+  "AggregateFunction",
+  "SimpleAggregateFunction",
+];
+
+/** Codecs the codec overlay types parameters for. */
+const REQUIRED_CODECS = ["ZSTD", "LZ4", "LZ4HC", "Delta", "DoubleDelta", "Gorilla", "T64"];
+
+export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+
+  const core = await validateLexiconArtifacts({
+    lexiconJsonFilename: "lexicon-sql.json",
+    requiredNames: REQUIRED_ENTITIES,
+    basePath,
+    // Generation reads the committed catalog snapshot, so the surface is deterministic: a pin move that
+    // changes it fails here until `chant dev surface-diff lexicons/sql --update-snapshot --bump` accepts it.
+    checkSurfaceSnapshot: "always",
+  });
+  const checks: ValidateCheck[] = [...core.checks];
+
+  const tables = join(basePath, "src", "generated", "clickhouse.ts");
+  checks.push(
+    existsSync(tables)
+      ? { name: "clickhouse-tables-exist", ok: true }
+      : { name: "clickhouse-tables-exist", ok: false, error: "src/generated/clickhouse.ts not found; run npm run generate" },
+  );
+
+  try {
+    const catalog = parseCatalog(readFileSync(join(basePath, "src", "spec", "clickhouse-catalog.snapshot.json"), "utf-8"));
+    checks.push(
+      catalog.version === CLICKHOUSE_VERSION
+        ? { name: "clickhouse-snapshot-at-pin", ok: true }
+        : {
+            name: "clickhouse-snapshot-at-pin",
+            ok: false,
+            error: `the snapshot is ${catalog.version}, the pin is ${CLICKHOUSE_VERSION}; run npm run generate to refresh it`,
+          },
+    );
+    const missing = (names: readonly string[], have: Iterable<string>) => {
+      const set = new Set(have);
+      return names.filter((n) => !set.has(n));
+    };
+    const gaps = [
+      ...missing(REQUIRED_ENGINES, catalog.tableEngines.map((e) => e.name)).map((n) => `engine ${n}`),
+      ...missing(REQUIRED_TYPE_FAMILIES, catalog.typeFamilies.map((t) => t.name)).map((n) => `type ${n}`),
+      ...missing(REQUIRED_CODECS, catalog.codecs.map((c) => c.name)).map((n) => `codec ${n}`),
+    ];
+    checks.push(
+      gaps.length === 0
+        ? { name: "clickhouse-required-names", ok: true }
+        : { name: "clickhouse-required-names", ok: false, error: `missing at the pin: ${gaps.join(", ")}` },
+    );
+  } catch (err) {
+    checks.push({
+      name: "clickhouse-snapshot-readable",
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  try {
+    const behind = POSTGRES_PINS.flatMap((pin) => {
+      const snapshot = parsePostgresCatalog(readFileSync(join(basePath, "src", "spec", `postgres-catalog-${pin.major}.snapshot.json`), "utf-8"));
+      return snapshot.version === pin.version ? [] : [`${pin.major}: snapshot ${snapshot.version}, pin ${pin.version}`];
+    });
+    checks.push(
+      behind.length === 0
+        ? { name: "postgres-snapshots-at-pins", ok: true }
+        : { name: "postgres-snapshots-at-pins", ok: false, error: `${behind.join("; ")}; run npm run generate to refresh` },
+    );
+  } catch (err) {
+    checks.push({ name: "postgres-snapshots-readable", ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+
+  return { success: checks.every((c) => c.ok), checks };
+}