@intentius/chant-lexicon-sql 0.124.46 → 0.124.48

package/dist/clickhouse/plan/stream.js

@@ -0,0 +1,107 @@
+/**
+ * Stream engines (#4396): Kafka, S3Queue, AzureQueue, RabbitMQ, NATS and
+ * FileLog. A table on one of them stores no rows. It is a consumer: the
+ * materialized views that read it pull messages (or files) through it into a
+ * target, and the position it has reached lives outside the table, in the
+ * broker's committed offsets or in Keeper.
+ *
+ * What follows from that, and what this file holds:
+ *
+ * - There is no ALTER for the engine's arguments, and nothing to copy to a
+ *   new table, so a change is neither `metadata` nor a `rebuild`: the table is
+ *   replaced, with the views that read it detached around the replacement
+ *   (SQLCH225, `./rules.ts`).
+ * - A replacement can lose the table's position. The two changes that do
+ *   are found here and reported on the change as a note.
+ */
+/** The stream engines, as `system.tables.engine` names them. */
+export const STREAM_ENGINES = new Set(["Kafka", "S3Queue", "AzureQueue", "RabbitMQ", "NATS", "FileLog"]);
+/** Whether an engine name is a stream engine. */
+export const isStreamEngine = (engine) => engine !== undefined && STREAM_ENGINES.has(engine);
+/** Whether a canonical table is on a stream engine. */
+export const isStreamTable = (o) => o.kind === "table" && isStreamEngine(o.engineName);
+/** The arguments inside an engine's parentheses, split at top-level commas, string quotes removed. Empty when it has none. */
+export function streamEngineArguments(engine) {
+    const open = engine?.indexOf("(") ?? -1;
+    if (engine === undefined || open < 0 || !engine.endsWith(")"))
+        return [];
+    const inner = engine.slice(open + 1, -1);
+    const out = [];
+    let depth = 0;
+    let quote;
+    let cur = "";
+    for (let i = 0; i < inner.length; i++) {
+        const ch = inner[i];
+        if (quote) {
+            cur += ch;
+            if (ch === "\\")
+                cur += inner[++i] ?? "";
+            else if (ch === quote)
+                quote = undefined;
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === "`")
+            quote = ch;
+        if (ch === "(" || ch === "[")
+            depth++;
+        if (ch === ")" || ch === "]")
+            depth--;
+        if (ch === "," && depth === 0) {
+            out.push(cur.trim());
+            cur = "";
+        }
+        else
+            cur += ch;
+    }
+    if (cur.trim())
+        out.push(cur.trim());
+    return out.map((a) => (/^'.*'$/.test(a) ? a.slice(1, -1) : a));
+}
+/** Kafka's positional arguments, in the order the engine takes them. */
+const KAFKA_POSITIONAL = ["kafka_broker_list", "kafka_topic_list", "kafka_group_name", "kafka_format"];
+/** A Kafka setting, from SETTINGS or from the engine's positional arguments. */
+function kafkaSetting(o, name) {
+    const at = KAFKA_POSITIONAL.indexOf(name);
+    return o.settings[name] ?? (at >= 0 ? streamEngineArguments(o.engine)[at] : undefined);
+}
+/**
+ * What a replacement would lose, in a sentence each (#4396):
+ *
+ * - a different `kafka_group_name` is a different consumer group: it starts
+ *   from the group's committed offsets, or from the topic's start when the
+ *   group has none (`auto.offset.reset`);
+ * - a different S3Queue `keeper_path` is a different place for the table's
+ *   record of processed files, so every file already seen is processed again.
+ *
+ * Neither is a refusal: a new group or path is sometimes the point.
+ */
+export function positionWarnings(before, after) {
+    const out = [];
+    if (before.engineName === "Kafka" && after.engineName === "Kafka") {
+        const b = kafkaSetting(before, "kafka_group_name");
+        const a = kafkaSetting(after, "kafka_group_name");
+        if (b !== a) {
+            out.push(`kafka_group_name changes from ${b ?? "none"} to ${a ?? "none"}: the new group starts from its own committed offsets, or from the start of the topic when it has none, ` +
+                "so messages already consumed may be read again or skipped");
+        }
+    }
+    if (before.engineName === "S3Queue" && after.engineName === "S3Queue") {
+        const b = before.settings.keeper_path;
+        const a = after.settings.keeper_path;
+        if (b !== a) {
+            out.push(`keeper_path changes from ${b ?? "none"} to ${a ?? "none"}: the new path holds no record of processed files, so every file already seen is processed again`);
+        }
+    }
+    return out;
+}
+/** Whether a materialized view reads from the table: its SELECT names the table, qualified or, in the table's own database, bare. */
+export function readsTable(view, table) {
+    if (view.kind !== "materializedView" || view.select === undefined)
+        return false;
+    const escaped = table.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const sameDatabase = view.database === table.database;
+    const database = table.database?.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // The canonical SELECT drops the view's own database from a name, so a bare name is a table in the view's database.
+    const names = [...(sameDatabase ? [escaped] : []), ...(database ? [`${database}\\s*\\.\\s*${escaped}`] : [])];
+    return names.some((n) => new RegExp(`(?:^|[^\\w.])${n}(?![\\w.])`).test(view.select));
+}

package/dist/clickhouse/rebuild/observe.d.ts

@@ -27,7 +27,9 @@
  *
  * Anything else is refused with a {@link RebuildRefusal}: a database that is
  * neither Atomic nor Replicated, a table that is not there, a change that is
- * not a rebuild, a working object chant did not make.
+ * not a rebuild, a working object chant did not make, a table on a stream
+ * engine (Kafka, S3Queue, AzureQueue, RabbitMQ, NATS, FileLog), which holds no
+ * rows to copy and is replaced by the applier instead (#4396).
  *
  * A Replicated database (#3249) is Atomic on every replica, with its DDL run
  * on each through Keeper, so the same EXCHANGE swaps the table everywhere.

package/dist/clickhouse/rebuild/observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/rebuild/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAGlE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAe,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAKxD,OAAO,EAAE,KAAK,EAAwC,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEvG,gFAAgF;AAChF,MAAM,MAAM,SAAS,GACjB;IACE;;;;;;;;;;;;;;OAcG;IACH,IAAI,EAAE,mBAAmB,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACD;IACE;;;;;OAKG;IACH,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEN,iGAAiG;AACjG,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAgBzE;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IACtC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,cAAc,CAAC;IACzB,oCAAoC;IACpC,IAAI,EAAE,YAAY,CAAC;IACnB,mEAAmE;IACnE,aAAa,EAAE,eAAe,CAAC;IAC/B,yEAAyE;IACzE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,wGAAwG;IACxG,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,uGAAuG;IACvG,SAAS,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB;AAID,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAO9F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,eAAe,GAAG,YAAY,EAAE,CAS9F;AAED,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOrE;AAgBD,4EAA4E;AAC5E,wBAAsB,UAAU,CAAC,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAGtG;AAED,2HAA2H;AAC3H,wBAAsB,cAAc,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAGzI;AAmBD,+DAA+D;AAC/D,wBAAsB,cAAc,CAAC,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2EzJ;AAoCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,kBAAkB,EAAE,SAAS,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASvG;AAED,eAAO,MAAM,iBAAiB,GAAI,GAAG,kBAAkB,EAAE,WAAW,SAAS,KAAG,MAAmF,CAAC;AAEpK,mEAAmE;AACnE,OAAO,EAAE,KAAK,EAAE,CAAC"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/rebuild/observe.ts"],"names":[],"mappings":"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"}

package/dist/clickhouse/rebuild/observe.js

@@ -27,7 +27,9 @@
  *
  * Anything else is refused with a {@link RebuildRefusal}: a database that is
  * neither Atomic nor Replicated, a table that is not there, a change that is
- * not a rebuild, a working object chant did not make.
+ * not a rebuild, a working object chant did not make, a table on a stream
+ * engine (Kafka, S3Queue, AzureQueue, RabbitMQ, NATS, FileLog), which holds no
+ * rows to copy and is replaced by the applier instead (#4396).
  *
  * A Replicated database (#3249) is Atomic on every replica, with its DDL run
  * on each through Keeper, so the same EXCHANGE swaps the table everywhere.
@@ -44,6 +46,7 @@ import { dropFormattingOnly } from "../plan/server-format.js";
 import { CLASSIFIER_RULES } from "../plan/rules.js";
 import { CLICKHOUSE_ENTITY_TYPES } from "../entities.js";
 import { carriesMarker, readTrailerPairs, REBUILD_TRAILER_KEY, stripMarkerFromStatement } from "../ownership.js";
+import { isStreamEngine } from "../plan/stream.js";
 import { ident, isRebuild, qualifiedIdent, sqlString } from "../apply/statements.js";
 /** A refusal: the rebuild cannot start, or cannot go on, for a reason a person has to act on. */
 export class RebuildRefusal extends Error {
@@ -140,10 +143,18 @@ function ownWorkingObject(o, names, role, marker) {
     }
     return o;
 }
+/** The refusal for a stream-engine table, naming the engine and where its change goes instead (#4396). */
+function streamRefusal(key, engine, side) {
+    return new RebuildRefusal(`${key} is ${side === "declared" ? "declared on" : "on the server as"} the ${engine} engine, a stream engine: it stores no rows, so there is nothing to backfill, and a direct SELECT from it either fails ` +
+        `or consumes messages. A change to it is SQLCH225 (replace a stream table), which the applier makes in place: it detaches the materialized views that read the table, drops and creates it, and attaches the views again ` +
+        `(ApplyOp with target "clickhouse").`);
+}
 /** Observe the rebuild of the declared table on the server. */
 export async function observeRebuild(target, declared, marker) {
     const database = declared.canonical.database ?? target.defaultDatabase;
     const names = rebuildNames(database, declared.canonical.name);
+    if (isStreamEngine(declared.canonical.engineName))
+        throw streamRefusal(names.key, declared.canonical.engineName, "declared");
     const [db] = await clickhouseQuery(target.endpoint, `SELECT engine FROM system.databases WHERE name = ${sqlString(database)}`);
     if (!db)
         throw new RebuildRefusal(`database ${database} is not on the server, so there is no ${names.key} to rebuild; the applier creates it`);
@@ -160,6 +171,8 @@ export async function observeRebuild(target, declared, marker) {
     // Between EXCHANGE and the end of the swap, the table's own name holds the
     // new table, still carrying role=new, and the new table's name holds the
     // old table until it is renamed; the swap step finishes that.
+    if (isStreamEngine(liveRow.engine))
+        throw streamRefusal(names.key, liveRow.engine, "live");
     const exchanged = liveRow.pairs?.get(REBUILD_TRAILER_KEY) === names.key && liveRow.pairs.get("role") === "new";
     const newTable = exchanged ? undefined : ownWorkingObject(objects.get(names.newName), names, "new", marker);
     const exchangedOld = exchanged ? objects.get(names.newName) : undefined;

package/dist/clickhouse/review-catalog.d.ts

@@ -0,0 +1,213 @@
+/**
+ * The needs-review catalog: the judgment calls that turn a table from another
+ * database into a ClickHouse table, each as a finding with the evidence it
+ * used. A source reader (`chant import` of SQL Server, #4398; `chant migrate`
+ * of Postgres, #4399) does the mechanical work, a type map and a rename,
+ * and asks this module for everything that is a decision.
+ *
+ * Nothing here knows a source dialect. A reader describes its table in the
+ * neutral facts below (a candidate sort key, a column's nullability, a
+ * constraint) and gets back the ClickHouse choice, a finding to report, and
+ * for a constraint the comment lines to keep in the DDL. The rules are the
+ * same whichever database the table came from.
+ *
+ * ## API
+ *
+ * - {@link sortKeyReview}: `ORDER BY` from the candidates the source offers,
+ *   in the priority `explicit-order`, `clustering-key`, `primary-key`,
+ *   `unique-key`, then `tuple()`. Returns `orderBy`, the `settings` the key
+ *   needs (`allow_nullable_key` when a key column is `Nullable`), and a
+ *   finding that names the chosen candidate and the others it passed over.
+ * - {@link engineReview}: `MergeTree` for an append-only table;
+ *   `ReplacingMergeTree(_version, _deleted)` for a CDC mirror, with the two
+ *   columns it adds in `extraColumns`. `cdcColumns` names them otherwise
+ *   (the Postgres pair uses the `CdcMirror` composite's `_is_deleted`).
+ * - {@link nullableReview}: a column's final type. A `NOT NULL` column keeps
+ *   its type with no finding. A nullable column becomes `Nullable(T)` with a
+ *   finding; when it has a default the finding says the default could
+ *   replace `Nullable`.
+ * - {@link lowCardinalityReview}: a finding for a `String` column whose name
+ *   and declared length suggest few distinct values. It never changes the
+ *   type; offline, the name and the type are all there is to read.
+ * - {@link constraintReview}: foreign keys, checks, unique and exclusion
+ *   constraints, which ClickHouse does not enforce. Returns `comments` (SQL `--` lines to
+ *   put before the `CREATE`) and one finding per constraint.
+ * - {@link REVIEW_RULES}: every rule id with its summary and the ClickHouse
+ *   documentation it rests on, for report metadata.
+ * - {@link findingText}: a finding as one line (object, message, evidence,
+ *   suggestion), the form a SARIF `message` takes.
+ *
+ * A finding's `severity` is `warning` for a decision the author must confirm
+ * and `info` for a note that changes nothing. The caller maps findings to its
+ * own diagnostic type; `at` carries the source line and column when the
+ * reader knows them.
+ *
+ * Every ClickHouse type and engine this module writes is checked against the
+ * pinned catalog (`src/generated/clickhouse.ts`, ClickHouse 26.8) in
+ * `review-catalog.test.ts`, so a pin move that drops one fails there.
+ *
+ * Sources: the MergeTree sorting key and `allow_nullable_key`
+ * (https://clickhouse.com/docs/engines/table-engines/mergetree-family/mergetree),
+ * `ReplacingMergeTree(ver, is_deleted)`
+ * (https://clickhouse.com/docs/engines/table-engines/mergetree-family/replacingmergetree),
+ * `Nullable` (https://clickhouse.com/docs/sql-reference/data-types/nullable),
+ * `LowCardinality`
+ * (https://clickhouse.com/docs/sql-reference/data-types/lowcardinality).
+ */
+export type ReviewSeverity = "warning" | "info";
+export type ReviewRuleId = "SQLRV001" | "SQLRV002" | "SQLRV003" | "SQLRV004" | "SQLRV005" | "SQLRV006" | "SQLRV007" | "SQLRV008" | "SQLRV009" | "SQLRV010" | "SQLRV011" | "SQLRV012";
+export interface ReviewRule {
+    id: ReviewRuleId;
+    name: string;
+    summary: string;
+    docs: readonly string[];
+}
+/**
+ * The rules. SQLRV001 to SQLRV005 are the shared ones; the rest are raised by
+ * a source reader for what only its dialect has, and live here so a report
+ * lists one catalog.
+ */
+export declare const REVIEW_RULES: Readonly<Record<ReviewRuleId, ReviewRule>>;
+export interface SourcePosition {
+    /** 1-based. */
+    line: number;
+    /** 1-based. */
+    column: number;
+}
+export interface ReviewFinding {
+    ruleId: ReviewRuleId;
+    severity: ReviewSeverity;
+    /** The table or view the finding is about, as the source names it. */
+    object: string;
+    /** The column, when the finding is about one. */
+    column?: string;
+    message: string;
+    /** What the decision was read from: each entry is a fact in the source. */
+    evidence: readonly string[];
+    suggestion?: string;
+    at?: SourcePosition;
+}
+/** A finding as one line. */
+export declare function findingText(f: ReviewFinding): string;
+/**
+ * Where a candidate sort key came from, strongest first. `explicit-order` is
+ * an ordering the author declared for storage (a columnstore `ORDER`),
+ * `clustering-key` the key the source stores rows in (a clustered index),
+ * then the primary key and the first unique key.
+ */
+export type SortKeyKind = "explicit-order" | "clustering-key" | "primary-key" | "unique-key";
+export interface SortKeyCandidate {
+    kind: SortKeyKind;
+    /** The index or constraint name, for the evidence. */
+    name?: string;
+    columns: readonly string[];
+    /** Columns the source sorts descending; ClickHouse's `ORDER BY` drops the direction. */
+    descending?: readonly string[];
+    /** The fact this candidate was read from, e.g. `CREATE CLUSTERED INDEX CX_t`. */
+    source: string;
+}
+export interface SortKeyInput {
+    object: string;
+    candidates: readonly SortKeyCandidate[];
+    /** Each column's ClickHouse type, by name; `Nullable(...)` marks a nullable key column. */
+    columnTypes: Readonly<Record<string, string>>;
+    at?: SourcePosition;
+}
+export interface SortKeyResult {
+    orderBy: string[];
+    /** MergeTree settings the key needs. */
+    settings: Record<string, string>;
+    finding: ReviewFinding;
+}
+export declare function sortKeyReview(input: SortKeyInput): SortKeyResult;
+export interface EngineInput {
+    object: string;
+    /**
+     * `append` for a table that is loaded and queried, `cdc` for a mirror of a
+     * table that changes in place (#4399): rows arrive as new versions and a
+     * delete arrives as a marker row.
+     */
+    mode: "append" | "cdc";
+    /** Facts about the source table that bear on the choice, as plain sentences. */
+    facts?: readonly string[];
+    /** The columns the source enforces unique, when it does. */
+    uniqueKey?: readonly string[];
+    /**
+     * For `cdc`, the names of the version and deleted columns, when the pipeline
+     * or the `CdcMirror` composite names them other than `_version` and
+     * `_deleted`. The names are the caller's; the catalog only writes them.
+     */
+    cdcColumns?: {
+        version: string;
+        deleted: string;
+    };
+    at?: SourcePosition;
+}
+export interface EngineResult {
+    /** The text after `ENGINE =`. */
+    engine: string;
+    /** Columns the engine needs and the source does not have. */
+    extraColumns: Array<{
+        name: string;
+        type: string;
+    }>;
+    finding: ReviewFinding;
+}
+export declare const CDC_VERSION_COLUMN: {
+    readonly name: "_version";
+    readonly type: "UInt64";
+};
+export declare const CDC_DELETED_COLUMN: {
+    readonly name: "_deleted";
+    readonly type: "UInt8";
+};
+export declare function engineReview(input: EngineInput): EngineResult;
+export interface NullableInput {
+    object: string;
+    column: string;
+    /** The column's ClickHouse type before `Nullable`. */
+    type: string;
+    sourceNullable: boolean;
+    /** The default as the ClickHouse expression it became, or the source text when it did not translate. */
+    defaultExpr?: string;
+    at?: SourcePosition;
+}
+export interface NullableResult {
+    type: string;
+    finding?: ReviewFinding;
+}
+export declare function nullableReview(input: NullableInput): NullableResult;
+export interface LowCardinalityInput {
+    object: string;
+    column: string;
+    /** The ClickHouse type as emitted. Only `String` and `Nullable(String)` are candidates. */
+    type: string;
+    /** The source's declared maximum length, when it has one. */
+    maxLength?: number;
+    at?: SourcePosition;
+}
+/** The longest declared length that still counts as supporting evidence. */
+export declare const LOW_CARDINALITY_MAX_LENGTH = 50;
+export declare function lowCardinalityReview(input: LowCardinalityInput): ReviewFinding | undefined;
+export interface ConstraintFact {
+    kind: "foreign-key" | "check" | "unique" | "exclusion";
+    name?: string;
+    columns?: readonly string[];
+    references?: {
+        table: string;
+        columns: readonly string[];
+    };
+    /** A check's expression, or an exclusion's `USING method (element WITH operator, ...)`, as the source wrote it. */
+    expression?: string;
+    at?: SourcePosition;
+}
+export interface ConstraintResult {
+    /** `-- ` lines to put before the `CREATE`; never contain a line break. */
+    comments: string[];
+    findings: ReviewFinding[];
+}
+export declare function constraintReview(input: {
+    object: string;
+    constraints: readonly ConstraintFact[];
+}): ConstraintResult;
+//# sourceMappingURL=review-catalog.d.ts.map

package/dist/clickhouse/review-catalog.d.ts.map

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