@intentius/chant-lexicon-sql 0.124.46 → 0.124.48

package/src/lint/post-synth/sqlch128.ts

@@ -0,0 +1,230 @@
+import { DATABASE_ENGINES, FORMATS, TABLE_ENGINES } from "../../generated/clickhouse";
+import { parseEngineSyntax } from "../../clickhouse/engine-syntax";
+import { COLLECTION_ENGINES, engineCollection } from "../../clickhouse/named-collections";
+import { isTrivia, tokenizeText, type Token } from "../../clickhouse/tokens";
+import { checkOf, splitTop } from "./clickhouse-helpers";
+import { clickhouseObjects, type OutputObject } from "./sql-helpers";
+
+/** A syntax-line argument that holds a secret: `password`, `secret_access_key`, `account_key`, `session_token`, `oauth_token`. */
+const SECRET_ARGUMENT = /password|secret|account_key|session_token|oauth_token/i;
+
+/** A `key = value` argument or a setting that holds a secret: the above, and `kafka_sasl_password`, `nats_token`. */
+const SECRET_KEY = /password|secret|account_key|session_token|oauth_token|(?:^|_)token$|private_key/i;
+
+/** Credentials written inside another value: a URL's `user:password@`, an Azure connection string's key or signature. */
+const EMBEDDED = [
+  { re: /^[a-z][a-z0-9+.-]*:\/\/[^/@:\s]+:[^/@\s]+@/i, what: "a URL with a password in it" },
+  { re: /(?:^|;)\s*(?:AccountKey|SharedAccessSignature)\s*=/i, what: "a connection string with an account key or signature in it" },
+];
+
+/** Compression methods the integration engines take after the format. */
+const COMPRESSION = new Set(["none", "auto", "gzip", "gz", "deflate", "br", "brotli", "xz", "lzma", "zstd", "zst", "lz4", "bz2", "snappy"]);
+const FORMAT_NAMES = new Set(FORMATS.map((f) => f.toLowerCase()));
+
+/** The table functions whose arguments follow an engine's syntax line, lower case, by engine. */
+const FUNCTION_ENGINE: Readonly<Record<string, string>> = {
+  s3: "S3",
+  gcs: "S3",
+  oss: "S3",
+  cosn: "S3",
+  url: "URL",
+  mysql: "MySQL",
+  postgresql: "PostgreSQL",
+  mongodb: "MongoDB",
+  azureblobstorage: "AzureBlobStorage",
+  iceberg: "Iceberg",
+  icebergs3: "IcebergS3",
+  icebergazure: "IcebergAzure",
+  deltalake: "DeltaLake",
+  deltalakes3: "DeltaLakeS3",
+  deltalakeazure: "DeltaLakeAzure",
+  hudi: "Hudi",
+  paimon: "Paimon",
+  paimons3: "PaimonS3",
+  arrowflight: "ArrowFlight",
+  ytsaurus: "YTsaurus",
+};
+
+/** `remote('addresses', db, table, 'user', 'password')`: no syntax line says it, so its password's position is written here. */
+const FUNCTION_SECRETS: Readonly<Record<string, Array<{ name: string; position: number }>>> = {
+  remote: [{ name: "password", position: 4 }],
+  remotesecure: [{ name: "password", position: 4 }],
+};
+
+const ENGINE_SYNTAX = { ...TABLE_ENGINES, ...DATABASE_ENGINES } as Readonly<Record<string, { syntax: string } | undefined>>;
+
+/** The secret arguments an engine's syntax line names, with their positions. */
+function secretPositions(engine: string): Array<{ name: string; position: number }> {
+  const syntax = ENGINE_SYNTAX[engine]?.syntax;
+  const parsed = syntax ? parseEngineSyntax(syntax) : undefined;
+  if (!parsed) return [];
+  return parsed.args
+    .filter((a) => !a.named && a.name.split("|").some((n) => SECRET_ARGUMENT.test(n)))
+    .map((a) => ({ name: a.name.split("|").find((n) => SECRET_ARGUMENT.test(n))!, position: a.position }));
+}
+
+/** The text of a string literal, or undefined for anything else. */
+function stringValue(text: string): string | undefined {
+  const t = text.trim();
+  if (!/^'(?:[^'\\]|\\.|'')*'$/.test(t)) return undefined;
+  return t.slice(1, -1).replace(/\\(.)/g, "$1").replace(/''/g, "'");
+}
+
+/**
+ * Whether the arguments before `position` leave it where the syntax line puts
+ * it. An optional group (`[, access_key_id, secret_access_key]`) may be left
+ * out, and the format and compression move up into its place:
+ * `S3('url', 'Parquet', 'gzip')`. When a format, a compression method or
+ * `NOSIGN` comes earlier, the position says nothing.
+ */
+function aligned(args: readonly string[], position: number): boolean {
+  for (const a of args.slice(1, position)) {
+    const t = a.trim();
+    if (t.toUpperCase() === "NOSIGN") return false;
+    const v = stringValue(t)?.toLowerCase();
+    if (v !== undefined && (FORMAT_NAMES.has(v) || COMPRESSION.has(v))) return false;
+  }
+  return true;
+}
+
+interface Finding {
+  where: string;
+  what: string;
+  masked: boolean;
+}
+
+/** The literal credentials in one engine's or table function's arguments. */
+function argumentFindings(label: string, args: readonly string[], secrets: ReadonlyArray<{ name: string; position: number }>, collection: boolean): Finding[] {
+  const out: Finding[] = [];
+  const add = (where: string, what: string, value: string) => out.push({ where, what, masked: value === "[HIDDEN]" });
+  // After a named collection, the arguments are `key = value` overrides, not positions.
+  if (!collection) {
+    for (const s of secrets) {
+      const arg = args[s.position];
+      const value = arg !== undefined ? stringValue(arg) : undefined;
+      if (value && aligned(args, s.position)) add(`${label} argument ${s.name}`, "a literal credential", value);
+    }
+  }
+  args.forEach((arg, i) => {
+    const kv = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*([\s\S]+)$/.exec(arg);
+    if (kv) {
+      const value = stringValue(kv[2]!);
+      if (value && SECRET_KEY.test(kv[1]!)) add(`${label} argument ${kv[1]}`, "a literal credential", value);
+      return;
+    }
+    const value = stringValue(arg);
+    if (!value) return;
+    for (const e of EMBEDDED) if (e.re.test(value)) add(`${label} argument ${i + 1}`, e.what, value);
+  });
+  return out;
+}
+
+/** Each table function call in a SQL text, with its arguments as written. */
+function functionCalls(text: string): Array<{ name: string; args: string[] }> {
+  let tokens: Token[];
+  try {
+    tokens = tokenizeText(text, 0);
+  } catch {
+    return [];
+  }
+  const sig = tokens.map((t, i) => ({ t, i })).filter(({ t }) => !isTrivia(t));
+  const out: Array<{ name: string; args: string[] }> = [];
+  for (let k = 0; k + 1 < sig.length; k++) {
+    const fn = sig[k]!.t;
+    const open = sig[k + 1]!;
+    if (fn.kind !== "ident" || open.t.kind !== "punct" || open.t.text !== "(") continue;
+    const lower = fn.text.toLowerCase();
+    const base = lower.endsWith("cluster") ? lower.slice(0, -"cluster".length) : lower;
+    if (!(base in FUNCTION_ENGINE) && !(base in FUNCTION_SECRETS)) continue;
+    let depth = 0;
+    let end = open.i;
+    for (let j = open.i; j < tokens.length; j++) {
+      const t = tokens[j]!;
+      if (t.kind === "punct" && t.text === "(") depth++;
+      else if (t.kind === "punct" && t.text === ")" && --depth === 0) {
+        end = j;
+        break;
+      }
+    }
+    const inner = tokens
+      .slice(open.i + 1, end)
+      .map((t) => t.text)
+      .join("");
+    out.push({ name: fn.text, args: inner.trim() === "" ? [] : splitTop(inner) });
+  }
+  return out;
+}
+
+/** The literal credentials in each table function call a SQL text makes. */
+function callFindings(text: string): Finding[] {
+  return functionCalls(text).flatMap((call) => {
+    const lower = call.name.toLowerCase();
+    const clustered = lower.endsWith("cluster") && !(lower in FUNCTION_ENGINE);
+    const base = clustered ? lower.slice(0, -"cluster".length) : lower;
+    // `s3Cluster(cluster, url, ...)`: the cluster comes first.
+    const args = clustered ? call.args.slice(1) : call.args;
+    const engine = FUNCTION_ENGINE[base];
+    const secrets = engine ? secretPositions(engine) : (FUNCTION_SECRETS[base] ?? []);
+    const collection = args[0] !== undefined && /^\s*(?:[A-Za-z_][A-Za-z0-9_]*|`[^`]+`)\s*$/.test(args[0]) && args[0].trim().toUpperCase() !== "NOSIGN";
+    return argumentFindings(`${call.name}()`, args, secrets, collection);
+  });
+}
+
+/** The literal credentials in a table's or database's engine and its settings. */
+function engineFindings(o: OutputObject & { settings?: Record<string, string> }): Finding[] {
+  const engine = o.engine;
+  if (!engine) return [];
+  const out = argumentFindings(`ENGINE = ${engine.name}`, engine.args ?? [], secretPositions(engine.name), engineCollection(engine) !== undefined);
+  if (COLLECTION_ENGINES.has(engine.name)) {
+    for (const [key, raw] of Object.entries(o.settings ?? {})) {
+      const value = stringValue(raw);
+      if (value && SECRET_KEY.test(key)) out.push({ where: `${engine.name} setting ${key}`, what: "a literal credential", masked: value === "[HIDDEN]" });
+    }
+  }
+  return out;
+}
+
+/** `PASSWORD 'secret'` in a dictionary's source. */
+function sourceFindings(dataSource: string): Finding[] {
+  const m = /\bPASSWORD\s+('(?:[^'\\]|\\.|'')*')/i.exec(dataSource);
+  const value = m ? stringValue(m[1]!) : undefined;
+  return value ? [{ where: "SOURCE PASSWORD", what: "a literal credential", masked: value === "[HIDDEN]" }] : [];
+}
+
+/**
+ * SQLCH128: an integration engine's or table function's argument holds a
+ * literal credential (#4395): `ENGINE = S3('https://...', 'AKIA...', 'secret')`,
+ * `mysql('db:3306', 'shop', 'orders', 'app', 'secret')`, a Kafka table's
+ * `kafka_sasl_password` setting, a dictionary source's `PASSWORD`.
+ *
+ * A credential is the environment's, so it does not belong in a declaration,
+ * the build output or `clickhouse.sql`, as `IDENTIFIED BY` does not on a
+ * user (`../../clickhouse/access.ts`). The secret arguments are found by name
+ * from each engine's syntax line in the pinned catalog (`password`,
+ * `secret_access_key`, `account_key`, `session_token`, `oauth_token`), as
+ * `key = value` overrides and settings by the same names, and inside a URL
+ * (`user:password@`) or an Azure connection string (`AccountKey=`). The fix
+ * is a named collection the environment creates, named in place of the
+ * arguments: `ENGINE = S3(lake_creds, format = 'Parquet')`.
+ */
+export const sqlch128 = checkOf({ id: "SQLCH128", description: "An integration engine or table function argument holds a literal credential" }, (ctx, report) => {
+  for (const o of clickhouseObjects(ctx)) {
+    const props = o as OutputObject & { settings?: Record<string, string>; asFunction?: string; select?: string; dataSource?: string };
+    const findings = [
+      ...engineFindings(props),
+      ...(props.asFunction ? callFindings(props.asFunction) : []),
+      ...(props.select ? callFindings(props.select) : []),
+      ...(props.dataSource ? sourceFindings(props.dataSource) : []),
+    ];
+    for (const f of findings) {
+      const held = f.masked ? "holds '[HIDDEN]', the server's mask for a credential, in place of one" : `holds ${f.what}, which is the environment's`;
+      report({
+        severity: "error",
+        message:
+          `${o.export} (${o.name}): ${f.where} ${held}. ` +
+          "Create a named collection with the credentials on the server and name it in place of the arguments (ENGINE = S3(lake_creds, format = 'Parquet'), s3(lake_creds), SOURCE(MYSQL(NAME mysql_creds))); chant sql plan checks that it exists",
+        entity: o.export,
+      });
+    }
+  }
+});

package/src/lint/rules/postgres-templates.ts

@@ -17,12 +17,12 @@ export const POSTGRES_TEMPLATE_SOURCES: readonly TemplateSource<PostgresTag>[] =
   {
     dialect: "postgres",
     modules: ["@intentius/chant-lexicon-sql/postgres"],
-    tags: ["schema", "table", "index", "view", "sequence", "type", "domain", "extension", "func", "procedure", "aggregate", "trigger", "eventTrigger", "collation", "cast", "policy", "role", "grant"],
+    tags: ["schema", "table", "index", "view", "sequence", "type", "domain", "extension", "func", "procedure", "aggregate", "trigger", "eventTrigger", "operator", "statistics", "foreignDataWrapper", "foreignServer", "publication", "collation", "cast", "policy", "role", "grant"],
   },
   {
     dialect: "postgres",
     modules: ["@intentius/chant-lexicon-sql"],
-    tags: ["schema", "index", "sequence", "type", "domain", "extension", "func", "procedure", "aggregate", "trigger", "eventTrigger", "collation", "cast", "policy", "role", "grant"],
+    tags: ["schema", "index", "sequence", "type", "domain", "extension", "func", "procedure", "aggregate", "trigger", "eventTrigger", "operator", "statistics", "foreignDataWrapper", "foreignServer", "publication", "collation", "cast", "policy", "role", "grant"],
   },
 ];
 

package/src/lsp/postgres-template.ts

@@ -152,6 +152,17 @@ export function postgresDeclarations(content: string, fileName = "file.ts"): Pos
           sqlName = text(node.name.span);
           kind = "event trigger";
           break;
+        case "operator":
+          sqlName = text(node.name.span);
+          kind = "operator";
+          break;
+        case "statistics":
+        case "foreignDataWrapper":
+        case "foreignServer":
+        case "publication":
+          sqlName = text(node.name.span);
+          kind = { statistics: "statistics", foreignDataWrapper: "foreign data wrapper", foreignServer: "foreign server", publication: "publication" }[node.statement];
+          break;
         case "index":
           sqlName = node.name ? text(node.name.span) : undefined;
           break;

package/src/mcp/postgres.ts

@@ -81,7 +81,7 @@ export function postgresSearch(params: Record<string, unknown>): unknown {
   };
 }
 
-const TAGS = { schema: pg.schema, table: pg.table, index: pg.index, view: pg.view, sequence: pg.sequence, type: pg.type, domain: pg.domain, extension: pg.extension, func: pg.func, procedure: pg.procedure, aggregate: pg.aggregate, trigger: pg.trigger, eventTrigger: pg.eventTrigger, collation: pg.collation, cast: pg.cast, policy: pg.policy, role: pg.role, grant: pg.grant } as const;
+const TAGS = { schema: pg.schema, table: pg.table, index: pg.index, view: pg.view, sequence: pg.sequence, type: pg.type, domain: pg.domain, extension: pg.extension, func: pg.func, procedure: pg.procedure, aggregate: pg.aggregate, trigger: pg.trigger, eventTrigger: pg.eventTrigger, operator: pg.operator, statistics: pg.statistics, foreignDataWrapper: pg.foreignDataWrapper, foreignServer: pg.foreignServer, publication: pg.publication, collation: pg.collation, cast: pg.cast, policy: pg.policy, role: pg.role, grant: pg.grant } as const;
 export const POSTGRES_TAGS = Object.keys(TAGS);
 
 /** Parse one statement with the Postgres tag; an error comes back as SQLPG001 with its line and column. */

package/src/migrate/from-postgres/cli.test.ts

@@ -0,0 +1,165 @@
+/**
+ * `chant migrate --from sql/postgres --to sql/clickhouse` in-process, for the
+ * second Done-when box of #4399: every decision is a SARIF diagnostic, and
+ * `--strict` exits 1 while one is open. Also the naming of the two sides, the
+ * member directory as a source, and the workspace links written beside the
+ * output. `--validate` needs the emulator: `validate.e2e.test.ts`.
+ */
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, afterEach, describe, expect, test, vi } from "vitest";
+import { parseArgs } from "@intentius/chant/cli/parse-args";
+import { runMigrate } from "@intentius/chant/cli/handlers/migrate";
+
+const dir = mkdtempSync(join(tmpdir(), "migrate-pg-ch-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+afterEach(() => vi.restoreAllMocks());
+
+const SCHEMA = "CREATE TABLE users (id bigint PRIMARY KEY, email text NOT NULL, status text NOT NULL, bio text);\n";
+let n = 0;
+
+function write(path: string, text: string): string {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text);
+  return path;
+}
+
+async function migrate(argv: string[]) {
+  const args = parseArgs(["migrate", ...argv]);
+  const err = vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(console, "log").mockImplementation(() => {});
+  const out = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+  const code = await runMigrate({ args, plugins: [], serializers: [] });
+  return { code, stderr: err.mock.calls.map((c) => String(c[0])).join("\n"), stdout: out.mock.calls.map((c) => String(c[0])).join("") };
+}
+
+const input = write(join(dir, "schema.sql"), SCHEMA);
+const sides = ["--from", "sql/postgres", "--to", "sql/clickhouse"];
+
+describe("chant migrate --from sql/postgres --to sql/clickhouse", () => {
+  test("writes declarations, exits 0 and prints the review summary", async () => {
+    const out = join(dir, `plain-${++n}.ts`);
+    const r = await migrate([input, ...sides, "--output", out]);
+    expect(r.code).toBe(0);
+    expect(readFileSync(out, "utf8")).toContain("export const users = table`");
+    expect(r.stderr).toContain("## Migration report");
+    expect(r.stderr).toContain("SQLRV001");
+    // The GitLab pair's advice does not appear.
+    expect(r.stderr).not.toContain("GitLab");
+  });
+
+  test("--use-composites writes a CdcMirror call; --emit sql writes DDL; the default for this pair is ts", async () => {
+    const ts = join(dir, `c-${++n}.ts`);
+    expect((await migrate([input, ...sides, "--use-composites", "--output", ts])).code).toBe(0);
+    expect(readFileSync(ts, "utf8")).toContain('columns: "id Int64, email String, status String, bio Nullable(String)"');
+    const sql = join(dir, `c-${++n}.sql`);
+    expect((await migrate([input, ...sides, "--emit", "sql", "--output", sql])).code).toBe(0);
+    expect(readFileSync(sql, "utf8")).toMatch(/^CREATE TABLE users/);
+  });
+
+  test("--report writes every finding as SARIF with its rule id, entity and the source file", async () => {
+    const report = join(dir, `r-${++n}.sarif`);
+    const r = await migrate([input, ...sides, "--output", join(dir, `r-${n}.ts`), "--report", report]);
+    expect(r.code).toBe(0);
+    const sarif = JSON.parse(readFileSync(report, "utf8")) as { runs: Array<{ results: Array<{ ruleId: string; level: string; message: { text: string }; locations: Array<{ physicalLocation: { artifactLocation: { uri: string } } }> }> }> };
+    const results = sarif.runs[0]!.results;
+    expect(results.map((x) => x.ruleId).sort()).toEqual(["SQLRV001", "SQLRV002", "SQLRV003", "SQLRV004"]);
+    expect(results.every((x) => x.level === "warning")).toBe(true);
+    expect(results.every((x) => x.locations[0]!.physicalLocation.artifactLocation.uri.endsWith("schema.sql"))).toBe(true);
+    expect(results.find((x) => x.ruleId === "SQLRV003")!.message.text).toContain("users.bio");
+  });
+
+  test("the report describes each rule from the catalog, with the documentation it rests on", async () => {
+    const report = join(dir, `m-${++n}.sarif`);
+    await migrate([input, ...sides, "--output", join(dir, `m-${n}.ts`), "--report", report]);
+    const sarif = JSON.parse(readFileSync(report, "utf8")) as { runs: Array<{ tool: { driver: { rules: Array<{ id: string; shortDescription: { text: string }; helpUri: string }> } } }> };
+    const rule = sarif.runs[0]!.tool.driver.rules.find((r) => r.id === "SQLRV001")!;
+    expect(rule.shortDescription.text).toContain("sort-key");
+    expect(rule.helpUri).toContain("clickhouse.com/docs");
+  });
+
+  test("--strict exits 1 while a warning is open, and the report then marks them errors", async () => {
+    const report = join(dir, `s-${++n}.sarif`);
+    const r = await migrate([input, ...sides, "--strict", "--output", join(dir, `s-${n}.ts`), "--report", report]);
+    expect(r.code).toBe(1);
+    const sarif = JSON.parse(readFileSync(report, "utf8")) as { runs: Array<{ results: Array<{ level: string }> }> };
+    expect(sarif.runs[0]!.results.every((x) => x.level === "error")).toBe(true);
+  });
+
+  test("a side with a slash that the lexicon does not know is refused by name", async () => {
+    const r = await migrate([input, "--from", "sql/mysql", "--to", "sql/clickhouse"]);
+    expect(r.code).toBe(1);
+    expect(r.stderr).toContain('does not support migration from "sql/mysql"');
+    const back = await migrate([input, "--from", "sql/postgres", "--to", "sql/postgres"]);
+    expect(back.code).toBe(1);
+    expect(back.stderr).toContain('does not support migration from "sql/postgres"');
+  });
+
+  test("--emit sql is refused for a target that is not a sql lexicon", async () => {
+    const r = await migrate([input, "--emit", "sql"]);
+    expect(r.code).toBe(1);
+    expect(r.stderr).toContain("not a sql target");
+  });
+
+  test("a file that is not Postgres DDL is refused by name", async () => {
+    const ch = write(join(dir, "ch.sql"), "CREATE TABLE t (id UInt64) ENGINE = MergeTree ORDER BY id;\n");
+    const r = await migrate([ch, ...sides]);
+    expect(r.code).toBe(1);
+    expect(r.stderr).toContain("does not look like sql/postgres source");
+  });
+});
+
+describe("in a workspace", () => {
+  function workspace() {
+    const root = join(dir, `ws-${++n}`);
+    write(join(root, "chant.workspace.json"), JSON.stringify({ name: "shop", schema: 1, members: [{ name: "db", dir: "db", kind: "chant" }, { name: "mirror", dir: "mirror", kind: "chant" }] }, null, 2) + "\n");
+    write(join(root, "db/chant.config.ts"), "");
+    write(join(root, "mirror/chant.config.ts"), "");
+    return root;
+  }
+  const links = (root: string) => (JSON.parse(readFileSync(join(root, "chant.workspace.json"), "utf8")) as { members: Array<{ name: string; links?: Array<{ member: string; output: string }> }> }).members.find((m) => m.name === "mirror")!.links;
+
+  test("the mirror member links each mirrored column to the Postgres member's output, once", async () => {
+    const root = workspace();
+    const source = write(join(root, "db/schema.sql"), SCHEMA);
+    const out = join(root, "mirror/src/mirrors.ts");
+    const first = await migrate([source, ...sides, "--use-composites", "--output", out]);
+    expect(first.code).toBe(0);
+    expect(first.stderr).toContain("Workspace links: added 4 links from member mirror to db");
+    expect(links(root)).toEqual(["id", "email", "status", "bio"].map((c) => ({ member: "db", output: `public.users.${c}` })));
+    const again = await migrate([source, ...sides, "--use-composites", "--output", out]);
+    expect(again.stderr).toContain("already links every output");
+    expect(links(root)).toHaveLength(4);
+  });
+
+  test("a table added to the source adds only its links; stdout output writes none and says so", async () => {
+    const root = workspace();
+    const source = write(join(root, "db/schema.sql"), SCHEMA);
+    const out = join(root, "mirror/mirrors.ts");
+    await migrate([source, ...sides, "--output", out]);
+    write(source, `${SCHEMA}CREATE TABLE tags (id bigint PRIMARY KEY, label text NOT NULL);\n`);
+    const r = await migrate([source, ...sides, "--output", out]);
+    expect(r.stderr).toContain("added 2 links");
+    expect(links(root)).toHaveLength(6);
+    const toStdout = await migrate([source, ...sides]);
+    expect(toStdout.stderr).toContain("pass --output inside the ClickHouse member");
+    expect(toStdout.stdout).toContain("export const users");
+  });
+
+  test("a member directory or a TypeScript file is a source: its project is built and its tables translated", async () => {
+    const example = join(import.meta.dirname, "../../../examples/postgres-cdc-source");
+    for (const path of [example, join(example, "src/shop.ts")]) {
+      const out = join(dir, `ts-${++n}.ts`);
+      const r = await migrate([path, ...sides, "--use-composites", "--output", out]);
+      expect(r.code, r.stderr).toBe(0);
+      const text = readFileSync(out, "utf8");
+      expect(text).toContain("export const customers = CdcMirror({");
+      expect(text).toContain("export const orders = CdcMirror({");
+      expect(text).toContain("// FOREIGN KEY (customer_id) REFERENCES shop.customers (id)");
+      // The output sits in a temporary directory, outside any member of a workspace above the example: no link is written.
+      expect(r.stderr).not.toContain("added");
+    }
+  });
+});

package/src/migrate/from-postgres/detect.ts

@@ -0,0 +1,7 @@
+/** Kept apart from the translator so the plugin can ask it without loading the translator. */
+
+/** Text that looks like Postgres DDL or like a Postgres declaration, and not like ClickHouse or T-SQL. */
+export function looksLikePostgres(content: string): boolean {
+  if (/\bENGINE\s*=/i.test(content) || /^\s*GO\s*$/im.test(content)) return false;
+  return /\bCREATE\s+(?:UNLOGGED\s+|TEMP(?:ORARY)?\s+)?TABLE\b/i.test(content) || /@intentius\/chant-lexicon-sql\/postgres/.test(content);
+}

package/src/migrate/from-postgres/emit.ts

@@ -0,0 +1,96 @@
+/**
+ * A {@link Mirror} as text: ClickHouse DDL, the TypeScript declarations that
+ * write it, or the statements a server runs (#4399).
+ *
+ * With `composite`, a mirror is a `CdcMirror` call (`../../composites/cdc-mirror.ts`)
+ * that adds the version and deleted columns and the view of live rows
+ * itself. Without it, a mirror is a `table` declaration with the engine and
+ * the two columns written out, and no view.
+ */
+
+import { CdcMirror } from "../../composites/cdc-mirror";
+import { CLICKHOUSE_ENTITY_TYPES } from "../../clickhouse/entities";
+import type { ImportedObject } from "../../clickhouse/import/ir";
+import { engineReview } from "../../clickhouse/review-catalog";
+import { MIRROR_COLUMNS, type Mirror } from "./translate";
+
+const ident = (name: string): string => (/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : `\`${name.replace(/\\/g, "\\\\").replace(/`/g, "\\`")}\``);
+const chString = (s: string): string => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+const oneLine = (s: string): string => s.replace(/\s+/g, " ").trim();
+
+/** `id Int64`, `email String COMMENT '...'`. */
+export const columnSql = (c: Mirror["columns"][number]): string => `${ident(c.name)} ${c.type}${c.comment ? ` COMMENT ${chString(oneLine(c.comment))}` : ""}`;
+
+/** The sort key as `CdcMirror`'s `primaryKey` and `ORDER BY` write it. */
+export const orderBySql = (m: Mirror): string => (m.primaryKey.length === 0 ? "tuple()" : m.primaryKey.length === 1 ? ident(m.primaryKey[0]!) : `(${m.primaryKey.map(ident).join(", ")})`);
+
+/** The `columns` string of a `CdcMirror` call. */
+export const mirrorColumns = (m: Mirror): string => m.columns.map(columnSql).join(", ");
+
+/** The table as a bare `CREATE TABLE`, constraint comments first. */
+export function tableSql(m: Mirror): string {
+  const engine = engineReview({ object: m.name, mode: "cdc", cdcColumns: { version: MIRROR_COLUMNS.version, deleted: MIRROR_COLUMNS.deleted } });
+  const settings = Object.entries(m.settings).map(([k, v]) => `${k} = ${v}`);
+  return [
+    ...m.constraintComments,
+    `CREATE TABLE ${ident(m.name)}`,
+    "(",
+    [...m.columns.map(columnSql), ...engine.extraColumns.map((c) => `${c.name} ${c.type}`)].map((l) => `    ${l}`).join(",\n"),
+    ")",
+    `ENGINE = ${engine.engine}`,
+    `ORDER BY ${orderBySql(m)}`,
+    ...(settings.length > 0 ? [`SETTINGS ${settings.join(", ")}`] : []),
+    ...(m.comment ? [`COMMENT ${chString(oneLine(m.comment))}`] : []),
+  ].join("\n");
+}
+
+/** The call's props, for `CdcMirror` and for the TypeScript that writes it. */
+function callProps(m: Mirror) {
+  return { name: m.name, columns: mirrorColumns(m), primaryKey: orderBySql(m) };
+}
+
+/** The statements a server runs for the mirrors, in creation order. */
+export function mirrorObjects(mirrors: readonly Mirror[], composite: boolean): ImportedObject[] {
+  const out: ImportedObject[] = [];
+  for (const m of mirrors) {
+    if (!composite) {
+      out.push({ type: CLICKHOUSE_ENTITY_TYPES.table, name: m.name, ddl: tableSql(m) });
+      continue;
+    }
+    // The composite writes the DDL: what is validated is what `chant build` makes of the call.
+    const { table, current } = CdcMirror(callProps(m));
+    out.push({ type: CLICKHOUSE_ENTITY_TYPES.table, name: m.name, ddl: (table.props as { ddl: string }).ddl });
+    out.push({ type: CLICKHOUSE_ENTITY_TYPES.view, name: `${m.name}_current`, ddl: (current.props as { ddl: string }).ddl });
+  }
+  return out;
+}
+
+/** `--emit sql`: the statements, each ended with a semicolon. */
+export function emitSql(mirrors: readonly Mirror[], composite: boolean): string {
+  const objects = mirrorObjects(mirrors, composite);
+  // A constraint comment sits in the table's own text, so a statement is the object's ddl as it is.
+  const comments = composite ? new Map(mirrors.map((m) => [m.name, m.constraintComments])) : new Map<string, string[]>();
+  return `${objects.map((o) => `${(comments.get(o.name) ?? []).map((c) => `${c}\n`).join("")}${o.ddl.replace(/\s+$/, "")};`).join("\n\n")}\n`;
+}
+
+const str = (s: string): string => JSON.stringify(s);
+const templateSafe = (s: string): string => s.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+
+/** `--emit ts`: the declarations, as a file of `CdcMirror` calls or of `table` templates. */
+export function emitTs(mirrors: readonly Mirror[], composite: boolean): string {
+  const lines: string[] = [];
+  if (composite) {
+    lines.push(`import { CdcMirror } from "@intentius/chant-lexicon-sql/clickhouse";`, "");
+    for (const m of mirrors) {
+      for (const c of m.constraintComments) lines.push(`//${c.slice(2)}`);
+      const p = callProps(m);
+      lines.push(`export const ${m.export} = CdcMirror({`, `  name: ${str(p.name)},`, `  columns: ${str(p.columns)},`, `  primaryKey: ${str(p.primaryKey)},`, `});`, "");
+    }
+  } else {
+    lines.push(`import { table } from "@intentius/chant-lexicon-sql/clickhouse";`, "");
+    for (const m of mirrors) {
+      lines.push(`export const ${m.export} = table\``, ...tableSql(m).split("\n").map((l) => `  ${templateSafe(l)}`), "`;", "");
+    }
+  }
+  return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+}