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

package/dist/rules/sqlpg112.ts

@@ -0,0 +1,25 @@
+import { checkOf, tablesOf } from "./postgres-helpers";
+
+const SENSITIVE = /(^|_)(password|passwd|pwd|secret|token|api_?key|ssn|social_security|tax_id|credit_card|card_number|cvv|iban|passport|date_of_birth|dob|email|phone|address)(_|$)/i;
+
+/**
+ * SQLPG112: a secret- or PII-named column in a table with no comment.
+ *
+ * Doc: https://www.postgresql.org/docs/18/sql-comment.html. A COMMENT on the
+ * table or the column is where the retention, encryption or masking rule is
+ * written down, and where pg_dump, anonymizers and catalog scanners read it.
+ * A column or a table comment satisfies the check.
+ */
+export const sqlpg112 = checkOf({ id: "SQLPG112", description: "A secret- or PII-named column with no comment on it or its table" }, (ctx, report) => {
+  for (const t of tablesOf(ctx)) {
+    if (t.comment) continue;
+    for (const c of t.columns) {
+      if (c.comment || !SENSITIVE.test(c.name)) continue;
+      report({
+        severity: "warning",
+        message: `${t.export}.${c.name} looks like a secret or personal data and neither it nor ${t.sqlName} has a COMMENT; say what it holds and how it is protected`,
+        entity: t.export,
+      });
+    }
+  }
+});

package/dist/rules/sqlpg113.ts

@@ -0,0 +1,28 @@
+import { checkOf } from "./postgres-helpers";
+import { postgresObjects } from "./sql-helpers";
+
+const PLACED = new Set(["Postgres::Table", "Postgres::View", "Postgres::MaterializedView", "Postgres::Sequence", "Postgres::Enum", "Postgres::Domain"]);
+
+/**
+ * SQLPG113: an object in the public schema while the project declares schemas.
+ *
+ * Doc: https://www.postgresql.org/docs/18/ddl-schemas.html#DDL-SCHEMAS-PUBLIC
+ * and https://www.postgresql.org/docs/18/ddl-schemas.html#DDL-SCHEMAS-PATTERNS
+ * (the usage patterns recommend that applications not share `public`). An
+ * unqualified name is created in the first schema of search_path, usually
+ * public. Silent for a project that declares no schema.
+ */
+export const sqlpg113 = checkOf({ id: "SQLPG113", description: "An object is in the public schema though the project declares schemas" }, (ctx, report) => {
+  const objects = postgresObjects(ctx);
+  if (!objects.some((o) => o.type === "Postgres::Schema")) return;
+  for (const o of objects) {
+    if (!PLACED.has(o.type)) continue;
+    const schema = (o.schema as string | undefined) ?? "public";
+    if (schema !== "public") continue;
+    report({
+      severity: "warning",
+      message: `${o.export} (${o.sqlName}) is in the public schema; qualify it with one of the declared schemas`,
+      entity: o.export,
+    });
+  }
+});

package/dist/rules/sqlpg114.ts

@@ -0,0 +1,37 @@
+import { STORAGE_PARAMETERS } from "../../generated/postgres";
+import { checkOf, rangeOf, storageParams, storageTarget, targetMajor } from "./postgres-helpers";
+import { postgresObjects } from "./sql-helpers";
+
+/**
+ * SQLPG114: a storage parameter the object's kind does not accept at the
+ * target major (`postgresMajor` in the output).
+ *
+ * Doc: https://www.postgresql.org/docs/18/sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS
+ * (and the CREATE INDEX, CREATE VIEW and CREATE MATERIALIZED VIEW pages). The
+ * server refuses an unrecognized parameter at CREATE. The accepted names and
+ * the relation kinds they apply to come from the generated catalog, whose
+ * since/until data says which majors have each one: a parameter removed
+ * before the target major is reported as removed.
+ */
+export const sqlpg114 = checkOf({ id: "SQLPG114", description: "A storage parameter the object's kind or the target major does not accept" }, (ctx, report) => {
+  const major = targetMajor(ctx);
+  const specs = STORAGE_PARAMETERS as Record<string, { targets: readonly string[] } | undefined>;
+  for (const o of postgresObjects(ctx)) {
+    const target = storageTarget(o);
+    if (!target) continue;
+    for (const raw of storageParams(o.with as string | undefined).keys()) {
+      if (raw.startsWith("toast.")) continue;
+      const spec = specs[raw];
+      if (!spec) {
+        report({ severity: "error", message: `${o.export} (${o.sqlName}) sets ${raw}, which is not a Postgres ${major} storage parameter`, entity: o.export });
+        continue;
+      }
+      const range = rangeOf("storageParameters", `${target}.${raw}`);
+      if (!spec.targets.includes(target)) {
+        report({ severity: "error", message: `${o.export} (${o.sqlName}) sets ${raw}, which applies to ${spec.targets.join(", ")} and not to a ${target}`, entity: o.export });
+      } else if (range?.until !== undefined && range.until < major) {
+        report({ severity: "error", message: `${o.export} (${o.sqlName}) sets ${raw}, which Postgres removed after ${range.until}`, entity: o.export });
+      }
+    }
+  }
+});

package/dist/rules/sqlpg115.ts

@@ -0,0 +1,38 @@
+import { checkOf, rangeOf, storageParams, storageTarget, tablesOf, targetMajor } from "./postgres-helpers";
+import { indexesOf } from "./postgres-helpers";
+import { postgresObjects } from "./sql-helpers";
+
+/**
+ * SQLPG115: a feature newer than the target major.
+ *
+ * Doc: https://www.postgresql.org/docs/18/release-18.html (NOT ENFORCED
+ * constraints and virtual generated columns arrive in 18),
+ * https://www.postgresql.org/docs/15/release-15.html (NULLS NOT DISTINCT). Storage parameters read the generated catalog's
+ * `since` data. The target is `sql.postgresMajor`
+ * (recorded as `postgresMajor` in the output), else the newest pinned major;
+ * a feature is reported as a warning only when it is newer than the target,
+ * naming the first major that has it.
+ */
+export const sqlpg115 = checkOf({ id: "SQLPG115", description: "A feature newer than the target major" }, (ctx, report) => {
+  const major = targetMajor(ctx);
+  const note = (entity: string, what: string, since: number) =>
+    report({ severity: "warning", message: `${entity} uses ${what}, which needs Postgres ${since}; Postgres ${major} refuses it`, entity });
+  for (const o of postgresObjects(ctx)) {
+    const target = storageTarget(o);
+    if (!target) continue;
+    for (const name of storageParams(o.with as string | undefined).keys()) {
+      // SQLPG117 asks every view for security_invoker (15), so it is not also a portability finding.
+      if (name === "security_invoker") continue;
+      const since = rangeOf("storageParameters", `${target}.${name}`)?.since;
+      if (since !== undefined && since > major) note(o.export, `the storage parameter ${name}`, since);
+    }
+  }
+  for (const t of tablesOf(ctx)) {
+    for (const c of t.checks) if (c.notEnforced !== undefined && major < 18) note(t.export, `a NOT ENFORCED / ENFORCED constraint${c.name ? ` ${c.name}` : ""}`, 18);
+    for (const fk of t.foreignKeys as Array<{ notEnforced?: boolean; name?: string }>) if (fk.notEnforced !== undefined && major < 18) note(t.export, `a NOT ENFORCED / ENFORCED foreign key${fk.name ? ` ${fk.name}` : ""}`, 18);
+    for (const c of t.columns) if (c.generated?.kind === "virtual" && major < 18) note(t.export, `the virtual generated column ${c.name}`, 18);
+    const nulls = [...t.uniques, ...(t.primaryKey ? [t.primaryKey] : [])].some((k) => k.nullsNotDistinct);
+    if (nulls && major < 15) note(t.export, "NULLS NOT DISTINCT", 15);
+  }
+  for (const i of indexesOf(ctx)) if ((i as { nullsNotDistinct?: boolean }).nullsNotDistinct && major < 15) note(i.export, "NULLS NOT DISTINCT", 15);
+});

package/dist/rules/sqlpg116.ts

@@ -0,0 +1,25 @@
+import { checkOf, rangeOf, targetMajor } from "./postgres-helpers";
+import { postgresObjects } from "./sql-helpers";
+
+/**
+ * SQLPG116: an extension the target major no longer ships.
+ *
+ * Doc: https://www.postgresql.org/docs/18/contrib.html and the release notes
+ * of the major that dropped it (adminpack and old_snapshot are gone after 16,
+ * https://www.postgresql.org/docs/17/release-17.html). The target is `postgresMajor` in the output. The extension names
+ * and their since/until majors come from the generated catalog, read from
+ * pg_available_extensions of each major's server image.
+ */
+export const sqlpg116 = checkOf({ id: "SQLPG116", description: "An extension the target major no longer ships" }, (ctx, report) => {
+  const major = targetMajor(ctx);
+  for (const o of postgresObjects(ctx)) {
+    if (o.type !== "Postgres::Extension") continue;
+    const until = rangeOf("extensions", o.name)?.until;
+    if (until === undefined || until >= major) continue;
+    report({
+      severity: "error",
+      message: `${o.export} installs the ${o.name} extension, which Postgres ${major} does not ship (last in ${until})`,
+      entity: o.export,
+    });
+  }
+});

package/dist/rules/sqlpg117.ts

@@ -0,0 +1,24 @@
+import { checkOf, isView, storageParams } from "./postgres-helpers";
+import { postgresObjects } from "./sql-helpers";
+
+/**
+ * SQLPG117: a view that runs with its owner's privileges.
+ *
+ * Doc: https://www.postgresql.org/docs/18/sql-createview.html ("by default,
+ * access to the underlying base relations referenced in the view is determined
+ * by the permissions of the view owner"; with security_invoker = true it is the
+ * caller's, and the base tables' row-level security applies to the caller).
+ * A view over tables with RLS otherwise hands the owner's view of the rows to
+ * every role that can select from it.
+ */
+export const sqlpg117 = checkOf({ id: "SQLPG117", description: "A view without security_invoker runs with its owner's privileges" }, (ctx, report) => {
+  for (const v of postgresObjects(ctx).filter(isView)) {
+    const flag = storageParams(v.with).get("security_invoker");
+    if (flag === "true" || flag === "on" || flag === "1" || flag === "'true'" || flag === "'on'") continue;
+    report({
+      severity: "warning",
+      message: `${v.export} (${v.sqlName}) does not set security_invoker = true, so it reads its tables as its owner and skips the caller's row-level security`,
+      entity: v.export,
+    });
+  }
+});

package/dist/rules/sqlpg118.ts

@@ -0,0 +1,22 @@
+import { checkOf, tablesOf } from "./postgres-helpers";
+
+/**
+ * SQLPG118: a table that uses INHERITS.
+ *
+ * Doc: https://www.postgresql.org/docs/18/ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE-BEST-PRACTICES
+ * and https://www.postgresql.org/docs/18/ddl-inherit.html#DDL-INHERIT-CAVEATS
+ * (indexes, unique constraints and foreign keys are not inherited, so a
+ * constraint on the parent does not cover the children). Declarative
+ * partitioning (PARTITION BY ... / PARTITION OF) replaced inheritance for
+ * splitting a table; INHERITS is kept for its other uses.
+ */
+export const sqlpg118 = checkOf({ id: "SQLPG118", description: "A table uses INHERITS where declarative partitioning replaced it" }, (ctx, report) => {
+  for (const t of tablesOf(ctx)) {
+    if (t.inherits.length === 0) continue;
+    report({
+      severity: "warning",
+      message: `${t.export} (${t.sqlName}) uses INHERITS; its parent's unique and foreign keys do not cover it, so use PARTITION OF for a split table`,
+      entity: t.export,
+    });
+  }
+});

package/dist/rules/templates.ts

@@ -0,0 +1,35 @@
+/**
+ * Finding the ClickHouse tags in a source file, for the source-level rules
+ * (and the editor). A rule reads the template's raw parts straight from the
+ * TypeScript AST and parses them the way the tag does, with every
+ * interpolation left a reference: lint cannot know the values. The finder is
+ * the shared core's (`../../core/find-templates.ts`); a tag is ClickHouse's
+ * because of the module it is imported from.
+ */
+
+import type * as ts from "typescript";
+import { tokenize, type Token } from "../../clickhouse/tokens";
+import { findSqlTemplates, type FoundTemplate as SqlFoundTemplate, type TemplateSource } from "../../core/find-templates";
+
+export { templatePosition, tokenPosition } from "../../core/find-templates";
+
+export type SqlTag = "database" | "table" | "view";
+
+/**
+ * The ClickHouse tags, by the modules they are imported from. The package
+ * root still exports them, so it counts as ClickHouse too.
+ */
+export const CLICKHOUSE_TEMPLATE_SOURCE: TemplateSource<SqlTag> = {
+  dialect: "clickhouse",
+  modules: ["@intentius/chant-lexicon-sql", "@intentius/chant-lexicon-sql/clickhouse"],
+  tags: ["database", "table", "view"],
+};
+
+export type FoundTemplate = SqlFoundTemplate<SqlTag>;
+
+/** Every ClickHouse template in the file (the shared core's finder). */
+export function findTemplates(source: ts.SourceFile): FoundTemplate[] {
+  return findSqlTemplates(source, [CLICKHOUSE_TEMPLATE_SOURCE]);
+}
+
+export const tokensOf = (found: FoundTemplate): Token[] => tokenize(found.parts);

package/dist/serializer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The sql serializer.
+ *
+ * A build writes two things:
+ *
+ * - The primary output, one JSON document: the dialect, the order objects
+ *   must be created in, and each object filed under its export name (its
+ *   identity in chant) with its type, its parsed definition, the references it
+ *   makes and its DDL. Post-synth checks, planning and the applier read this.
+ * - `clickhouse.sql` (or `postgres.sql`) beside it: every statement, in that
+ *   order, as it will be sent. Written verbatim.
+ *
+ * The order is the dependency order of the references: a view after the
+ * tables it reads, a materialized view after its target, a table after its
+ * database. Ties break by export name, so the output is the same however the
+ * files were discovered. A reference cycle is an error naming the cycle.
+ *
+ * One build holds one dialect: the dialect is the document's, and a project
+ * whose declarations are ClickHouse and Postgres both is refused, naming one
+ * of each. Two databases of different dialects are two projects (two
+ * workspace members, #3047 question 1).
+ *
+ * A Postgres document also carries `postgresMajor`, the major the project
+ * targets (`sql.postgresMajor`, else the newest pinned major). Post-synth
+ * checks and the lock classifier read it; ClickHouse output has no such field.
+ *
+ * Rule ids: `SQL` for rules that hold in every dialect, `SQLCH` for the
+ * ClickHouse dialect's (#3199), `SQLPG` for Postgres's (#3289).
+ */
+import type { Serializer } from "@intentius/chant";
+export { applyOrder } from "./core/references.js";
+/** The file the statements are written to, beside the primary output. */
+export declare const CLICKHOUSE_DDL_FILE = "clickhouse.sql";
+/** The Postgres statements' file, beside the primary output. */
+export declare const POSTGRES_DDL_FILE = "postgres.sql";
+export declare const sqlSerializer: Serializer;
+//# sourceMappingURL=serializer.d.ts.map

package/dist/serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAc,UAAU,EAAoB,MAAM,kBAAkB,CAAC;AAQjF,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAiEhD,eAAO,MAAM,aAAa,EAAE,UAsC3B,CAAC"}

package/dist/skill-defs.d.ts

@@ -0,0 +1,3 @@
+/** The sql lexicon's AI skills, read from src/skills/. */
+export declare const sqlSkills: () => import("@intentius/chant").SkillDefinition[];
+//# sourceMappingURL=skill-defs.d.ts.map

package/dist/skill-defs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-defs.d.ts","sourceRoot":"","sources":["../src/skill-defs.ts"],"names":[],"mappings":"AAEA,0DAA0D;AAC1D,eAAO,MAAM,SAAS,oDAkGpB,CAAC"}

package/dist/spec/catalog.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The ClickHouse catalog: what generation reads from a pinned server's
+ * `system.*` tables, in the shape the committed snapshot stores.
+ *
+ * Every section is sorted by name, and the snapshot is written one entry per
+ * line, so a pin move is a line diff a reviewer can read. Nothing here depends
+ * on the host: the columns that reflect server config (`value`, `changed`) are
+ * never read, every query orders its rows, and `auto(<cores>)` defaults are
+ * written as `auto`.
+ */
+import { type ClickHouseEndpoint } from "../clickhouse/http.js";
+export interface EngineCapabilities {
+    settings: boolean;
+    skippingIndices: boolean;
+    projections: boolean;
+    sortOrder: boolean;
+    ttl: boolean;
+    replication: boolean;
+    deduplication: boolean;
+    parallelInsert: boolean;
+}
+export interface TableEngineRow {
+    name: string;
+    /** The server's one-line usage, e.g. `ENGINE = ReplacingMergeTree([ver [, is_deleted]]) ORDER BY expr`. */
+    syntax: string;
+    summary: string;
+    capabilities: EngineCapabilities;
+}
+export interface DatabaseEngineRow {
+    name: string;
+    syntax: string;
+    summary: string;
+}
+export interface TypeFamilyRow {
+    name: string;
+    caseInsensitive: boolean;
+    /** Set when the name is an alias (`BIGINT` for `Int64`). */
+    aliasOf?: string;
+}
+export interface CodecRow {
+    name: string;
+    compression: boolean;
+    generic: boolean;
+    encryption: boolean;
+    timeseries: boolean;
+    experimental: boolean;
+    summary: string;
+}
+export interface SkipIndexTypeRow {
+    name: string;
+    syntax: string;
+    summary: string;
+}
+export interface CombinatorRow {
+    name: string;
+    internal: boolean;
+}
+export interface FormatRow {
+    name: string;
+    input: boolean;
+    output: boolean;
+}
+export interface FunctionRow {
+    name: string;
+    aggregate: boolean;
+    caseInsensitive: boolean;
+    aliasOf?: string;
+}
+export interface SettingRow {
+    name: string;
+    /** The server's setting type, e.g. `UInt64`, `Bool`, `MergeSelectorAlgorithm`. */
+    type: string;
+    default: string;
+    min?: string;
+    max?: string;
+    /** `Production`, `Beta`, `Experimental` or `Obsolete`. */
+    tier: string;
+    obsolete: boolean;
+    readonly: boolean;
+    aliasFor?: string;
+    summary: string;
+}
+export interface ClickHouseCatalog {
+    dialect: "clickhouse";
+    /** `SELECT version()` on the server it was read from. */
+    version: string;
+    /** The image reference that server ran. */
+    image: string;
+    tableEngines: TableEngineRow[];
+    databaseEngines: DatabaseEngineRow[];
+    typeFamilies: TypeFamilyRow[];
+    codecs: CodecRow[];
+    skipIndexTypes: SkipIndexTypeRow[];
+    aggregateCombinators: CombinatorRow[];
+    tableFunctions: string[];
+    formats: FormatRow[];
+    functions: FunctionRow[];
+    keywords: string[];
+    mergeTreeSettings: SettingRow[];
+    querySettings: SettingRow[];
+}
+/** The section names, in the order the snapshot writes them. */
+export declare const CATALOG_SECTIONS: readonly ["tableEngines", "databaseEngines", "typeFamilies", "codecs", "skipIndexTypes", "aggregateCombinators", "tableFunctions", "formats", "functions", "keywords", "mergeTreeSettings", "querySettings"];
+/** `max_threads` and a few others default to `auto(<cores>)`; the core count is the host's, not the pin's. */
+export declare function normalizeDefault(value: unknown): string;
+/**
+ * The first prose line of a markdown description, at most 200 characters.
+ * Descriptions are multi-line markdown with headings and fenced examples; a
+ * summary is what a hover or a JSDoc line can carry.
+ */
+export declare function summaryOf(description: unknown): string;
+/**
+ * Read the catalog from a running server. Every query has an explicit
+ * `ORDER BY`: system tables have no stable row order.
+ */
+export declare function readCatalog(endpoint: ClickHouseEndpoint, image: string): Promise<ClickHouseCatalog>;
+/**
+ * Write the catalog with one array entry per line. A pretty-printed tree would
+ * spread one engine over a dozen lines; this keeps a pin move to one changed
+ * line per changed entry.
+ */
+export declare function stringifyCatalog(catalog: ClickHouseCatalog): string;
+/** Parse and shape-check a snapshot. Throws naming the first section that is missing or not a list. */
+export declare function parseCatalog(text: string): ClickHouseCatalog;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/spec/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/spec/catalog.ts"],"names":[],"mappings":"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"}

package/dist/spec/fetch.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Where generation gets the ClickHouse catalog.
+ *
+ * The committed snapshot, `clickhouse-catalog.snapshot.json`, is the source
+ * every ordinary run reads: a fresh clone, CI and `npm run prepack` generate
+ * from it with no Docker and no network. A server is read only when the
+ * snapshot cannot serve the pin:
+ *
+ * - the pin moved (`CLICKHOUSE_VERSION` differs from the snapshot's version),
+ * - `force` is set, or
+ * - `CHANT_SQL_CLICKHOUSE_URL` names a server to read instead of starting one.
+ *
+ * Reading a server means starting the pinned image in a throwaway container
+ * (or using the named one), checking that its `version()` is the pin, reading
+ * `system.*`, and rewriting the snapshot. A server at any other version is
+ * refused: a snapshot labelled with one pin and holding another's surface is
+ * the failure the pin exists to prevent.
+ */
+import { type ClickHouseCatalog } from "./catalog.js";
+import type { ClickHouseEndpoint } from "../clickhouse/http.js";
+export declare const SNAPSHOT_FILE: string;
+/** The key the single catalog document is filed under in the pipeline's schema map. */
+export declare const CATALOG_KEY = "ClickHouse::Catalog";
+export interface FetchCatalogOptions {
+    /** Read a server even when the snapshot matches the pin. */
+    force?: boolean;
+    /** A running server to read instead of starting the pinned image. Defaults to `CHANT_SQL_CLICKHOUSE_URL`. */
+    serverUrl?: string;
+    /** The snapshot to read and rewrite. Tests point it elsewhere. */
+    snapshotFile?: string;
+    /** Log a line saying which route was taken. */
+    log?: (line: string) => void;
+}
+/** Read the pinned catalog from a server and refuse any other version. */
+export declare function catalogFromServer(endpoint: ClickHouseEndpoint, image: string): Promise<ClickHouseCatalog>;
+/**
+ * The catalog for the current pin: the snapshot when it matches, otherwise a
+ * fresh read that also rewrites the snapshot.
+ */
+export declare function fetchCatalog(options?: FetchCatalogOptions): Promise<ClickHouseCatalog>;
+/** The pipeline's `fetchSchemas`: one document, the catalog, keyed {@link CATALOG_KEY}. */
+export declare function fetchSchemas(options?: FetchCatalogOptions): Promise<Map<string, Buffer>>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/spec/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/spec/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,EAA+C,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEhG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,eAAO,MAAM,aAAa,QAAoF,CAAC;AAE/G,uFAAuF;AACvF,eAAO,MAAM,WAAW,wBAAwB,CAAC;AAEjD,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6GAA6G;IAC7G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAUD,0EAA0E;AAC1E,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAU/G;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqChG;AAED,2FAA2F;AAC3F,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAGlG"}

package/dist/spec/pin.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The pinned ClickHouse server the ClickHouse dialect's types come from.
+ *
+ * ClickHouse publishes no schema for its DDL. The engine names, column type
+ * families, codecs, skip index types and both settings surfaces are read from a
+ * running server's `system.*` tables (chant #3195), so the pin is a server
+ * image, not a document.
+ *
+ * Pinned to an exact patch of the 26.8 LTS line. 26.3 LTS lacks the `syntax`
+ * column on `system.table_engines` and the `system.data_skipping_index_types`
+ * table the engine-argument and skip-index types are built from, and two
+ * patches of one line differ (26.8.5.13 and 26.8.15.10 differ by nine query
+ * settings), so a floating `26.8` tag would change generated output with no
+ * commit. The digest sits beside the tag so a re-pushed tag cannot change it
+ * unseen either: generation runs `image@digest` and refuses a server whose
+ * `version()` is not {@link CLICKHOUSE_VERSION}.
+ *
+ * Moving the pin: change both constants, then `chant dev generate` (or
+ * `npm run generate`). The committed snapshot no longer matches the pin, so
+ * generation starts the pinned server, rewrites
+ * `src/spec/clickhouse-catalog.snapshot.json`, and the pull request's diff of
+ * that file is the surface change. Read its `-` lines: a removed engine or
+ * function is what breaks a user's declarations.
+ */
+/** The pinned `clickhouse-server` release, as `SELECT version()` reports it. */
+export declare const CLICKHOUSE_VERSION = "26.8.15.10";
+/** The image digest of `clickhouse/clickhouse-server:<CLICKHOUSE_VERSION>`. Move it with the version. */
+export declare const CLICKHOUSE_IMAGE_DIGEST = "sha256:9716a352d25f538bd19d868b001141e7a60e4d035bc9b823658c6a071660aa61";
+/** The official server image. */
+export declare const CLICKHOUSE_IMAGE_REPOSITORY = "clickhouse/clickhouse-server";
+/** The full image reference generation runs: tag for the reader, digest for the runtime. */
+export declare function clickhouseImage(): string;
+/**
+ * ClickHouse tags its LTS releases `v<version>-lts` on GitHub. The upgrade
+ * tooling hands `replace` the raw tag; the constant holds the bare version,
+ * which is also the docker tag.
+ */
+export declare function versionFromReleaseTag(tag: string): string;
+//# sourceMappingURL=pin.d.ts.map

package/dist/spec/pin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pin.d.ts","sourceRoot":"","sources":["../../src/spec/pin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAE/C,yGAAyG;AACzG,eAAO,MAAM,uBAAuB,4EAA4E,CAAC;AAEjH,iCAAiC;AACjC,eAAO,MAAM,2BAA2B,iCAAiC,CAAC;AAE1E,4FAA4F;AAC5F,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/spec/postgres-catalog.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The Postgres catalog: what generation reads from one pinned server's
+ * catalog, in the shape the committed snapshot stores (one snapshot per major).
+ *
+ * Every section is sorted with an explicit `COLLATE "C"`, and the snapshot is
+ * written one entry per line, so a pin move is a line diff a reviewer can
+ * read. Nothing here depends on the host: `pg_settings.setting` and
+ * `reset_val` reflect the scratch server's configuration and are never read
+ * (`boot_val` is the compiled default), the Debian build suffix is stripped
+ * from `server_version`, and nothing is timestamped.
+ */
+/** Runs a SQL script whose last statement returns one JSON value. A server, or a stub in a test. */
+export interface PostgresReader {
+    query(sql: string): Promise<unknown>;
+}
+export interface TypeRow {
+    /** `pg_type.typname`: `int4`. */
+    name: string;
+    /** `format_type()`: `integer`. */
+    sqlName: string;
+    /** `typtype`: base `b`, domain `d`, enum `e`, multirange `m`, pseudo `p`, range `r`. */
+    kind: string;
+    category: string;
+    len: number;
+    byval: boolean;
+}
+export interface AccessMethodRow {
+    name: string;
+    /** `i` for an index access method, `t` for a table access method. */
+    type: string;
+    /** What `pg_indexam_has_property` reports for the method (`can_unique`, `can_include`...); index methods only. */
+    properties: string[] | null;
+}
+export interface OpClassRow {
+    am: string;
+    name: string;
+    inputType: string;
+    default: boolean;
+    family: string;
+}
+export interface FunctionRow {
+    name: string;
+    /** `prokind`s over the overloads, sorted: `f` function, `a` aggregate, `p` procedure, `w` window. */
+    kinds: string;
+    overloads: number;
+    /** `pg_*`, `binary_upgrade*`, `*support`, or only ever an aggregate's support function: not for a user to call. */
+    internal: boolean;
+}
+export interface OperatorRow {
+    name: string;
+    kinds: string;
+    overloads: number;
+}
+export interface SettingRow {
+    name: string;
+    /** `bool`, `integer`, `real`, `string` or `enum`. */
+    type: string;
+    context: string;
+    category: string;
+    unit: string | null;
+    /** The compiled default (`boot_val`). */
+    default: string | null;
+    min: string | null;
+    max: string | null;
+    enumvals: string[] | null;
+}
+export interface KeywordRow {
+    word: string;
+    /** `U` unreserved, `C` column name, `T` reserved as function or type name, `R` reserved. */
+    code: string;
+    description: string;
+}
+export interface ExtensionRow {
+    name: string;
+    defaultVersion: string;
+    description: string | null;
+}
+/** Storage parameter names the server accepts, by relation kind: `table`, `toast`, `view`, `materialized view`, `index:<method>`. */
+export type StorageParameters = Record<string, string[]>;
+export interface PostgresCatalog {
+    dialect: "postgres";
+    /** `server_version` without the build suffix: `18.6`. */
+    version: string;
+    /** `server_version_num`: `180006`. */
+    versionNum: number;
+    /** The image reference that server ran. */
+    image: string;
+    types: TypeRow[];
+    accessMethods: AccessMethodRow[];
+    opclasses: OpClassRow[];
+    functions: FunctionRow[];
+    operators: OperatorRow[];
+    settings: SettingRow[];
+    keywords: KeywordRow[];
+    extensions: ExtensionRow[];
+    storageParameters: StorageParameters;
+}
+/** The list sections, in the order the snapshot writes them; `storageParameters` follows. */
+export declare const CATALOG_SECTIONS: readonly ["types", "accessMethods", "opclasses", "functions", "operators", "settings", "keywords", "extensions"];
+/** The major of a version string: `18.6` is 18. */
+export declare function majorOf(version: string): number;
+/** Read the catalog from a server. The caller checks that its version is the pin. */
+export declare function readCatalog(reader: PostgresReader, image: string): Promise<PostgresCatalog>;
+/** Write the catalog with one array entry per line, so a pin move is one changed line per changed entry. */
+export declare function stringifyCatalog(catalog: PostgresCatalog): string;
+/** Parse and shape-check a snapshot. Throws naming the first section that is missing or not a list. */
+export declare function parseCatalog(text: string): PostgresCatalog;
+//# sourceMappingURL=postgres-catalog.d.ts.map

package/dist/spec/postgres-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-catalog.d.ts","sourceRoot":"","sources":["../../src/spec/postgres-catalog.ts"],"names":[],"mappings":"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"}