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

package/src/clickhouse.ts

@@ -0,0 +1,63 @@
+/**
+ * `@intentius/chant-lexicon-sql/clickhouse`: the ClickHouse dialect.
+ *
+ * Everything here is spec-true to ClickHouse at the pinned server release
+ * (`CLICKHOUSE_VERSION`), not a database-agnostic model: the engine names,
+ * column type families, codecs, skip index types and settings are the pinned
+ * server's own, read from its `system.*` tables, and the argument grammar the
+ * catalog does not carry comes from the overlays beside them.
+ */
+
+export {
+  database,
+  table,
+  view,
+  literal,
+  SqlLiteral,
+  SqlTemplateError,
+  ClickHouseObject,
+  CLICKHOUSE_ENTITY_TYPES,
+  isClickHouseObject,
+  isColumnRef,
+  quoteIdentifier,
+  type ClickHouseEntityType,
+  type ClickHouseDatabase,
+  type ClickHouseRelation,
+  type ClickHouseTable,
+  type ClickHouseView,
+  type ColumnDef,
+  type DatabaseProps,
+  type EngineDef,
+  type LineageEdge,
+  type TableProps,
+  type ViewProps,
+} from "./clickhouse/entities";
+export * from "./generated/clickhouse";
+export * from "./composites/clickhouse";
+export type * from "./clickhouse/catalog-types";
+export { ENGINE_ARGUMENTS } from "./clickhouse/overlays/engines";
+export { SKIP_INDEX_PARAMETERS } from "./clickhouse/overlays/skip-indexes";
+export { CODEC_OVERLAY, type CodecOverlay } from "./clickhouse/overlays/codecs";
+export { TYPE_PARAMETERS, WRAPPER_TYPES, type TypeParameter } from "./clickhouse/overlays/types";
+export {
+  TTL_ACTIONS,
+  COLUMN_TTL_ACTIONS,
+  TTL_RESULT_TYPES,
+  TTL_SETTINGS,
+  type TtlAction,
+} from "./clickhouse/overlays/ttl";
+export {
+  PROJECTION_FORMS,
+  PROJECTION_SETTINGS,
+  PROJECTION_FORBIDDEN_CLAUSES,
+  type ProjectionForm,
+} from "./clickhouse/overlays/projections";
+export { CLICKHOUSE_IMAGE_DIGEST, CLICKHOUSE_IMAGE_REPOSITORY, clickhouseImage } from "./spec/pin";
+export {
+  ClickHouseRebuildOp,
+  type ClickHouseRebuildOpConfig,
+  type ClickHouseRebuildOpResources,
+  type ClickHouseRebuildArgs,
+} from "./clickhouse/rebuild/op";
+export type { DualWrite } from "./clickhouse/rebuild/observe";
+export { RECEIPTS_DATABASE, RECEIPTS_TABLE } from "./clickhouse/rebuild/receipts";

package/src/codegen/classifier-page.test.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { expect, test } from "vitest";
+import { renderClassifierPage } from "./classifier-page";
+import { renderPostgresClassifierPage } from "./postgres-classifier-page";
+
+test("the committed classifier page is what the rules render (run npm run docs)", () => {
+  const committed = readFileSync(join(import.meta.dirname, "..", "..", "docs", "pages", "change-classifier.mdx"), "utf-8");
+  expect(committed).toBe(renderClassifierPage());
+});
+
+
+test("the committed Postgres classifier page is what the rules render (run npm run docs)", () => {
+  const committed = readFileSync(join(import.meta.dirname, "..", "..", "docs", "pages", "postgres-change-classifier.mdx"), "utf-8");
+  expect(committed).toBe(renderPostgresClassifierPage());
+});

package/src/codegen/classifier-page.ts

@@ -0,0 +1,76 @@
+/**
+ * `docs/pages/change-classifier.mdx`, written from the classifier's own rule
+ * table by `npm run docs`, so the page cannot disagree with the rules.
+ */
+
+import { CLASSIFIER_RULES } from "../clickhouse/plan/rules";
+
+const LABEL: Record<string, string> = {
+  create: "create",
+  drop: "drop",
+  metadata: "metadata only",
+  rewrite: "background rewrite",
+  rebuild: "rebuild",
+};
+
+const cell = (s: string) => s.replace(/\|/g, "\\|");
+
+export function renderClassifierPage(): string {
+  const rows = Object.values(CLASSIFIER_RULES).map(
+    (r) => `| ${r.id} | ${LABEL[r.class]} | ${cell(r.title)} | ${cell(r.restriction)} [ClickHouse docs](${r.cite}) |`,
+  );
+  return `---
+title: "Planning ClickHouse Changes"
+label: "Planning and the Change Classifier"
+description: "How a ClickHouse schema change is classified as metadata only, a background rewrite or a rebuild, each with the ALTER restriction behind it"
+diataxis: reference
+group: "ClickHouse"
+order: 1
+---
+
+{/* Written by src/codegen/classifier-page.ts from src/clickhouse/plan/rules.ts. Edit the rules, then run npm run docs. */}
+
+Every change between two ClickHouse schemas is classified before anything runs:
+
+| Class | Means |
+|---|---|
+| metadata only | the server records the change and touches no existing data |
+| background rewrite | a mutation rewrites existing parts in the background, with no rollback |
+| rebuild | ClickHouse cannot make the change to the existing table, and the data has to be copied into a new one; a plan refuses to make it in place |
+
+Two commands report the classification, and \`chant lifecycle plan\` reports it as each update's disruption (metadata only is \`in-place\`, a rewrite \`rolling\`, a rebuild \`replace\`):
+
+\`\`\`bash
+chant sql diff base.json head.json     # two chant build outputs, offline
+chant sql plan prod schema.json        # a build output against the prod server
+\`\`\`
+
+Both exit 2 when a change needs a rebuild. \`chant sql diff\` compares a pull request's base and head builds with no server. \`chant sql plan\` reads the server \`sql.profiles.<env>\` binds, and asks that server's formatter about any expression the normalization rules leave different, so the server's own rewriting (\`INTERVAL 1 DAY\` as \`toIntervalDay(1)\`, \`a+b*2\` as \`a + (b * 2)\`) is not reported as a change.
+
+## After the plan
+
+The plan only reports. [\`clickhouseApply\`](../applying/) makes the metadata-only and background-rewrite changes, and refuses a rebuild the same way the plan does, sending nothing for that object. A rebuild runs as \`ClickHouseRebuildOp\`, a gated migration Op that creates the new table, backfills it, verifies it and swaps it in: see [Rebuilding a Table](../rebuild/). Both commands print the Op declaration to start from for each refused table.
+
+\`chant migrate\` plays no part in any of this. It translates a file from one lexicon's format into another's, such as a GitHub Actions workflow into GitLab CI, and does not run schema migrations.
+
+## Identity and renames
+
+An object is identified by its export name between two builds, so a changed name in the SQL under the same export is a rename. Against a server, which has no export names, an object is identified by \`database.name\`; a declaration renamed since the server last saw it says so with \`-- previously: <old name>\` before its CREATE.
+
+A column is identified by its name. A renamed column says so on its own line:
+
+\`\`\`sql
+CREATE TABLE events (
+  event_kind LowCardinality(String), -- previously: kind
+  ...
+\`\`\`
+
+Without the hint the change is a drop and an add, and the report points out a drop and an add with the same type in the same place.
+
+## The rules
+
+| Id | Class | Change | Restriction |
+|---|---|---|---|
+${rows.join("\n")}
+`;
+}

package/src/codegen/clickhouse-module.test.ts

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, test } from "vitest";
+import { parseCatalog, type ClickHouseCatalog } from "../spec/catalog";
+import { SNAPSHOT_FILE } from "../spec/fetch";
+import { renderClickHouseModule, settingTsType } from "./clickhouse-module";
+
+const load = (): ClickHouseCatalog => parseCatalog(readFileSync(SNAPSHOT_FILE, "utf-8"));
+
+describe("rendering the generated ClickHouse module", () => {
+  const rendered = renderClickHouseModule(load());
+
+  test("is deterministic", () => {
+    expect(renderClickHouseModule(load())).toEqual(rendered);
+  });
+
+  test("declares the engine union and the settings interfaces", () => {
+    expect(rendered.declarations).toContain('export const CLICKHOUSE_VERSION = "26.8.15.10";');
+    expect(rendered.declarations).toMatch(/export type MergeTreeEngineName = [^;]*"ReplacingMergeTree"/);
+    expect(rendered.declarations).toContain("export interface MergeTreeSettings {");
+    expect(rendered.declarations).toMatch(/\n {2}index_granularity\?: number;/);
+  });
+
+  test("merges the overlay's argument kinds into the engine table", () => {
+    const line = rendered.tables.split("\n").find((l) => l.startsWith("  ReplacingMergeTree:"))!;
+    const spec = JSON.parse(line.slice(line.indexOf("{"), -1));
+    expect(spec.typed).toBe(true);
+    expect(spec.args.map((a: { name: string; kind: string; optional: boolean }) => [a.name, a.kind, a.optional])).toEqual([
+      ["ver", "column", true],
+      ["is_deleted", "column", true],
+    ]);
+  });
+
+  test("leaves every MergeTree engine typed", () => {
+    expect(rendered.notes.filter((n) => n.includes("MergeTree"))).toEqual([]);
+  });
+
+  test("refuses an overlay argument the syntax line no longer has", () => {
+    const catalog = load();
+    const engine = catalog.tableEngines.find((e) => e.name === "CollapsingMergeTree")!;
+    engine.syntax = "ENGINE = CollapsingMergeTree(sign_column) ORDER BY expr";
+    expect(() => renderClickHouseModule(catalog)).toThrow(/CollapsingMergeTree: overlay argument "sign"/);
+  });
+
+  test("refuses a codec the overlay has no entry for", () => {
+    const catalog = load();
+    catalog.codecs.push({ ...catalog.codecs[0]!, name: "Brand_New" });
+    expect(() => renderClickHouseModule(catalog)).toThrow(/codec Brand_New .* has no entry/);
+  });
+
+  test("refuses an overlay engine the pin no longer ships", () => {
+    const catalog = load();
+    catalog.tableEngines = catalog.tableEngines.filter((e) => e.name !== "Buffer");
+    expect(() => renderClickHouseModule(catalog)).toThrow(/engine Buffer is not in the catalog/);
+  });
+});
+
+describe("setting types", () => {
+  test("map to TypeScript, and an enum-typed setting is a string", () => {
+    expect(settingTsType("Bool")).toBe("boolean");
+    expect(settingTsType("UInt64Auto")).toBe('number | "auto"');
+    expect(settingTsType("MergeSelectorAlgorithm")).toBe("string");
+  });
+});

package/src/codegen/clickhouse-module.ts

@@ -0,0 +1,269 @@
+/**
+ * Render `src/generated/clickhouse.ts`, the ClickHouse dialect's generated
+ * surface: string-literal unions for every named thing in the catalog, the two
+ * settings interfaces, and the tables lint and the LSP read (engines with
+ * their typed arguments, type families, codecs, skip index types, settings).
+ *
+ * The overlays are merged here, and checked against the catalog in both
+ * directions. An overlay key the pinned server does not have, or a codec at
+ * the pin with no overlay entry, is an error: a pin move that changes the
+ * grammar has to change the overlay in the same commit.
+ */
+
+import type { ClickHouseCatalog, SettingRow } from "../spec/catalog";
+import { parseEngineSyntax, type ParsedSyntax } from "../clickhouse/engine-syntax";
+import type { ArgumentOverlay } from "../clickhouse/overlays/kinds";
+import { ENGINE_ARGUMENTS } from "../clickhouse/overlays/engines";
+import { SKIP_INDEX_PARAMETERS } from "../clickhouse/overlays/skip-indexes";
+import { CODEC_OVERLAY } from "../clickhouse/overlays/codecs";
+import { TYPE_PARAMETERS } from "../clickhouse/overlays/types";
+import { TTL_SETTINGS } from "../clickhouse/overlays/ttl";
+import { PROJECTION_SETTINGS } from "../clickhouse/overlays/projections";
+import type { ArgumentSpec } from "../clickhouse/catalog-types";
+
+/** Setting types with a TypeScript form; every enum-typed setting (no member list in the catalog) is `string`. */
+const SETTING_TS_TYPES: Record<string, string> = {
+  Bool: "boolean",
+  BoolAuto: 'boolean | "auto"',
+  UInt64: "number",
+  Int64: "number",
+  UInt32: "number",
+  Int32: "number",
+  Float: "number",
+  Double: "number",
+  Seconds: "number",
+  Milliseconds: "number",
+  NonZeroUInt64: "number",
+  MaxThreads: 'number | "auto"',
+  UInt64Auto: 'number | "auto"',
+  FloatAuto: 'number | "auto"',
+};
+
+export function settingTsType(type: string): string {
+  return SETTING_TS_TYPES[type] ?? "string";
+}
+
+const lit = (names: readonly string[]): string =>
+  names.length > 0 ? names.map((n) => JSON.stringify(n)).join(" | ") : "never";
+
+const key = (name: string): string => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
+
+/** A JSDoc line cannot contain `*\/`. */
+const doc = (text: string): string => text.replace(/\*\//g, "*\\/");
+
+function mergeArguments(
+  owner: string,
+  parsed: ParsedSyntax | undefined,
+  overlay: Record<string, ArgumentOverlay> | undefined,
+  errors: string[],
+): { args?: ArgumentSpec[]; typed: boolean } {
+  if (!parsed) {
+    if (overlay) errors.push(`${owner}: the overlay types arguments, but the syntax line is not readable`);
+    return { typed: false };
+  }
+  const names = new Set(parsed.args.map((a) => a.name));
+  for (const name of Object.keys(overlay ?? {})) {
+    if (!names.has(name)) errors.push(`${owner}: overlay argument "${name}" is not in the syntax line at this pin`);
+  }
+  const args = parsed.args.map((a): ArgumentSpec => {
+    const o = overlay?.[a.name];
+    return {
+      name: a.name,
+      position: a.position,
+      optional: o?.optional ?? a.optional,
+      repeated: a.repeated,
+      named: a.named,
+      kind: o?.kind ?? (a.quoted ? "string" : "unknown"),
+      ...(o?.values ? { values: o.values } : {}),
+      ...(o?.range ? { range: o.range } : {}),
+      ...(o?.note ? { note: o.note } : {}),
+    };
+  });
+  return { args, typed: args.every((a) => a.kind !== "unknown") };
+}
+
+function settingsInterface(name: string, rows: readonly SettingRow[]): string {
+  const lines = [`export interface ${name} {`];
+  for (const r of rows) {
+    const tags = [doc(r.summary)];
+    if (r.obsolete || r.tier === "Obsolete") tags.push("@deprecated obsolete at this pin");
+    if (r.tier === "Experimental" || r.tier === "Beta") tags.push(`@tier ${r.tier}`);
+    if (r.aliasFor) tags.push(`@alias ${r.aliasFor}`);
+    tags.push(`@default ${doc(JSON.stringify(r.default))}`);
+    lines.push(`  /** ${tags.filter(Boolean).join(" | ")} */`);
+    lines.push(`  ${key(r.name)}?: ${settingTsType(r.type)};`);
+  }
+  lines.push("}");
+  return lines.join("\n");
+}
+
+function settingsTable(name: string, keyType: string, rows: readonly SettingRow[]): string {
+  const lines = [`export const ${name}: Readonly<Record<${keyType}, SettingSpec>> = {`];
+  for (const r of rows) {
+    lines.push(
+      `  ${key(r.name)}: ${JSON.stringify({ type: r.type, default: r.default, tier: r.tier, obsolete: r.obsolete, readonly: r.readonly })},`,
+    );
+  }
+  lines.push("};");
+  return lines.join("\n");
+}
+
+export interface RenderedModule {
+  /** `clickhouse-types.ts`: types only, compiles on its own (also written as the packaged `index.d.ts`). */
+  declarations: string;
+  /** `clickhouse.ts`: the runtime tables, re-exporting the declarations. */
+  tables: string;
+  /** Things worth a log line: engines left untyped. */
+  notes: string[];
+}
+
+export function renderClickHouseModule(catalog: ClickHouseCatalog): RenderedModule {
+  const errors: string[] = [];
+  const notes: string[] = [];
+
+  // ── Cross-checks of the overlays against the catalog ──────────────
+  const engineNames = new Set(catalog.tableEngines.map((e) => e.name));
+  for (const name of Object.keys(ENGINE_ARGUMENTS)) {
+    if (!engineNames.has(name)) errors.push(`overlays/engines.ts: engine ${name} is not in the catalog at ${catalog.version}`);
+  }
+  const indexNames = new Set(catalog.skipIndexTypes.map((e) => e.name));
+  for (const name of Object.keys(SKIP_INDEX_PARAMETERS)) {
+    if (!indexNames.has(name)) errors.push(`overlays/skip-indexes.ts: index type ${name} is not in the catalog`);
+  }
+  const codecNames = new Set(catalog.codecs.map((c) => c.name));
+  for (const name of Object.keys(CODEC_OVERLAY)) {
+    if (!codecNames.has(name)) errors.push(`overlays/codecs.ts: codec ${name} is not in the catalog`);
+  }
+  for (const name of codecNames) {
+    if (!CODEC_OVERLAY[name]) errors.push(`overlays/codecs.ts: codec ${name} at ${catalog.version} has no entry`);
+  }
+  const families = new Set(catalog.typeFamilies.filter((t) => !t.aliasOf).map((t) => t.name));
+  for (const name of Object.keys(TYPE_PARAMETERS)) {
+    if (!families.has(name)) errors.push(`overlays/types.ts: type family ${name} is not in the catalog`);
+  }
+  const mtSettings = new Set(catalog.mergeTreeSettings.map((s) => s.name));
+  for (const name of [...TTL_SETTINGS, ...PROJECTION_SETTINGS]) {
+    if (!mtSettings.has(name)) errors.push(`overlays: MergeTree setting ${name} is not in the catalog`);
+  }
+
+  // ── Engines ────────────────────────────────────────────────────────
+  const engineLines: string[] = [];
+  for (const e of catalog.tableEngines) {
+    const parsed = parseEngineSyntax(e.syntax);
+    const { args, typed } = mergeArguments(`engine ${e.name}`, parsed, ENGINE_ARGUMENTS[e.name], errors);
+    const mergeTree = /MergeTree$/.test(e.name);
+    const replicates = /^Replicated.+MergeTree$/.test(e.name) ? e.name.slice("Replicated".length) : undefined;
+    if (mergeTree && !typed) notes.push(`engine ${e.name}: arguments not fully typed`);
+    const spec = {
+      capabilities: e.capabilities,
+      syntax: e.syntax,
+      ...(args ? { args } : {}),
+      typed,
+      mergeTree,
+      ...(replicates ? { replicates } : {}),
+      summary: e.summary,
+    };
+    engineLines.push(`  ${key(e.name)}: ${JSON.stringify(spec)},`);
+  }
+
+  const indexLines: string[] = [];
+  for (const t of catalog.skipIndexTypes) {
+    const { args } = mergeArguments(`index ${t.name}`, parseEngineSyntax(t.syntax), SKIP_INDEX_PARAMETERS[t.name], errors);
+    indexLines.push(`  ${key(t.name)}: ${JSON.stringify({ syntax: t.syntax, ...(args ? { args } : {}), summary: t.summary })},`);
+  }
+
+  if (errors.length > 0) {
+    throw new Error(
+      `The ClickHouse overlays disagree with the catalog at ${catalog.version}:\n  ${errors.join("\n  ")}\n` +
+        "Update src/clickhouse/overlays/ for this pin.",
+    );
+  }
+
+  const canonical = catalog.typeFamilies.filter((t) => !t.aliasOf);
+  const aliases = catalog.typeFamilies.filter((t) => t.aliasOf);
+  const mergeTreeEngines = catalog.tableEngines.filter((e) => /MergeTree$/.test(e.name));
+
+  const header = (what: string) => [
+    `// Generated by \`npm run generate\` from the ClickHouse catalog at ${catalog.version}`,
+    `// (src/spec/clickhouse-catalog.snapshot.json) and the overlays in src/clickhouse/overlays/. Do not edit.`,
+    `// ${what}`,
+    "",
+  ];
+
+  const declarations = [
+    ...header("The type surface: unions of every named thing in the catalog, and the two settings interfaces."),
+    `/** The ClickHouse release these types were read from. */`,
+    `export const CLICKHOUSE_VERSION = ${JSON.stringify(catalog.version)};`,
+    "",
+    `export type TableEngineName = ${lit(catalog.tableEngines.map((e) => e.name))};`,
+    `export type MergeTreeEngineName = ${lit(mergeTreeEngines.map((e) => e.name))};`,
+    `export type DatabaseEngineName = ${lit(catalog.databaseEngines.map((e) => e.name))};`,
+    `export type ColumnTypeFamily = ${lit(canonical.map((t) => t.name))};`,
+    `export type ColumnTypeAlias = ${lit(aliases.map((t) => t.name))};`,
+    `export type ColumnTypeName = ColumnTypeFamily | ColumnTypeAlias;`,
+    `export type CodecName = ${lit(catalog.codecs.map((c) => c.name))};`,
+    `export type SkipIndexType = ${lit(catalog.skipIndexTypes.map((c) => c.name))};`,
+    `export type AggregateCombinator = ${lit(catalog.aggregateCombinators.filter((c) => !c.internal).map((c) => c.name))};`,
+    `export type TableFunctionName = ${lit(catalog.tableFunctions)};`,
+    `export type FormatName = ${lit(catalog.formats.map((f) => f.name))};`,
+    `export type InputFormatName = ${lit(catalog.formats.filter((f) => f.input).map((f) => f.name))};`,
+    `export type OutputFormatName = ${lit(catalog.formats.filter((f) => f.output).map((f) => f.name))};`,
+    `export type AggregateFunctionName = ${lit(catalog.functions.filter((f) => f.aggregate).map((f) => f.name))};`,
+    `export type ScalarFunctionName = ${lit(catalog.functions.filter((f) => !f.aggregate).map((f) => f.name))};`,
+    "",
+    settingsInterface("MergeTreeSettings", catalog.mergeTreeSettings),
+    "",
+    settingsInterface("QuerySettings", catalog.querySettings),
+    "",
+  ].join("\n");
+
+  const tables = [
+    ...header("The tables lint and the LSP read, typed by ./clickhouse-types."),
+    `import type { CodecSpec, DatabaseEngineSpec, SettingSpec, SkipIndexSpec, TableEngineSpec, TypeFamilySpec } from "../clickhouse/catalog-types";`,
+    `import type { CodecName, ColumnTypeName, DatabaseEngineName, MergeTreeSettings, QuerySettings, SkipIndexType, TableEngineName } from "./clickhouse-types";`,
+    "",
+    `export * from "./clickhouse-types";`,
+    "",
+    `export const TABLE_ENGINES: Readonly<Record<TableEngineName, TableEngineSpec>> = {`,
+    ...engineLines,
+    "};",
+    "",
+    `export const DATABASE_ENGINES: Readonly<Record<DatabaseEngineName, DatabaseEngineSpec>> = {`,
+    ...catalog.databaseEngines.map((e) => `  ${key(e.name)}: ${JSON.stringify({ syntax: e.syntax, summary: e.summary })},`),
+    "};",
+    "",
+    `export const TYPE_FAMILIES: Readonly<Record<ColumnTypeName, TypeFamilySpec>> = {`,
+    ...catalog.typeFamilies.map(
+      (t) => `  ${key(t.name)}: ${JSON.stringify({ canonical: t.aliasOf ?? t.name, caseInsensitive: t.caseInsensitive })},`,
+    ),
+    "};",
+    "",
+    `export const CODECS: Readonly<Record<CodecName, CodecSpec>> = {`,
+    ...catalog.codecs.map((c) => {
+      const o = CODEC_OVERLAY[c.name]!;
+      const spec = {
+        compression: c.compression,
+        generic: c.generic,
+        encryption: c.encryption,
+        timeseries: c.timeseries,
+        experimental: c.experimental,
+        role: o.role,
+        parameters: o.parameters,
+        summary: c.summary,
+      };
+      return `  ${key(c.name)}: ${JSON.stringify(spec)},`;
+    }),
+    "};",
+    "",
+    `export const SKIP_INDEX_TYPES: Readonly<Record<SkipIndexType, SkipIndexSpec>> = {`,
+    ...indexLines,
+    "};",
+    "",
+    settingsTable("MERGE_TREE_SETTINGS", "keyof MergeTreeSettings", catalog.mergeTreeSettings),
+    "",
+    settingsTable("QUERY_SETTINGS", "keyof QuerySettings", catalog.querySettings),
+    "",
+  ].join("\n");
+
+  return { declarations, tables, notes };
+}

package/src/codegen/docs-cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs";
+
+await generateDocs({ verbose: true });