okmodel 0.8.0 → 0.9.0

package/dist/tooling/driver-run.js

@@ -20,12 +20,11 @@ import {
   compareText,
   enumType,
   domainType,
-  isDomain,
   sameEnumLabels,
   indexObjects,
   orderIndexed,
-  creationOrder2,
   quoteLiteral,
+  renderCatalog2,
   clientGenerator,
   readClientGenerator,
   definition,
@@ -46,7 +45,7 @@ import {
   jsonb,
   quote,
   primaryUrl
-} from "./shared/f9mphxej.js";
+} from "./shared/hfq3n3bd.js";
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
@@ -693,322 +692,6 @@ function assertForeignKeys(objects, keys) {
   }
 }
 
-// src/dialects/pg/ddl.ts
-function quoteIdent(name) {
-  return `"${name.replaceAll('"', '""')}"`;
-}
-function renderCatalog(source, schema) {
-  const folded = foldedKeys(source);
-  const statements = [];
-  const ordered = creationOrder2(source);
-  const created = uniqueBeforeForeignKey(ordered);
-  for (const object of ordered) {
-    if (object.kind !== "type" || object.owner === "ignored")
-      continue;
-    const sql = createObjectSql(object, schema);
-    if (sql !== undefined)
-      statements.push(sql);
-  }
-  for (const object of created) {
-    if (object.kind === "type" || object.kind === "function" || object.kind === "trigger" || object.kind === "view" || object.kind === "materializedView" || object.kind === "policy" || ownedByView(object)) {
-      continue;
-    }
-    if (object.owner === "ignored")
-      continue;
-    const key = identityKey(object.identity);
-    if (object.kind === "table") {
-      statements.push(createTableSql(object, source, schema));
-      continue;
-    }
-    if (folded.has(key))
-      continue;
-    const sql = createObjectSql(object, schema);
-    if (sql !== undefined)
-      statements.push(sql);
-  }
-  for (const object of created) {
-    if (object.kind !== "policy" || object.owner === "ignored")
-      continue;
-    for (const step of policyCreatePlan(object, schema))
-      statements.push(step.sql);
-  }
-  for (const kind of ["function", "trigger"]) {
-    for (const object of ordered) {
-      if (object.kind !== kind || object.owner === "ignored")
-        continue;
-      const sql = createObjectSql(object, schema);
-      if (sql !== undefined)
-        statements.push(sql);
-    }
-  }
-  for (const kind of ["view", "materializedView"]) {
-    for (const object of ordered) {
-      if (object.kind !== kind || object.owner === "ignored")
-        continue;
-      const sql = createObjectSql(object, schema);
-      if (sql !== undefined)
-        statements.push(sql);
-    }
-  }
-  for (const object of ordered) {
-    if (!ownedByView(object) || object.owner === "ignored")
-      continue;
-    const sql = createObjectSql(object, schema);
-    if (sql !== undefined)
-      statements.push(sql);
-  }
-  return statements;
-}
-function uniqueBeforeForeignKey(objects) {
-  const uniques = objects.filter((object) => object.kind === "constraint" && object.definition.constraintKind === "unique");
-  if (uniques.length === 0)
-    return objects;
-  const emitted = new Set;
-  const result = [];
-  for (const object of objects) {
-    if (emitted.has(object))
-      continue;
-    if (object.kind === "constraint" && object.definition.constraintKind === "foreignKey") {
-      const target = object.definition.references;
-      if (target !== undefined && !coveredByPrimary(objects, target.parent, target.columns)) {
-        const columns = target.columns.join("\x00");
-        for (const unique of uniques) {
-          if (emitted.has(unique))
-            continue;
-          if (!sameRef(unique.identity.parent, target.parent))
-            continue;
-          if (unique.definition.columns.join("\x00") !== columns)
-            continue;
-          result.push(unique);
-          emitted.add(unique);
-        }
-      }
-    }
-    result.push(object);
-    emitted.add(object);
-  }
-  return result;
-}
-function coveredByPrimary(objects, parent, columns) {
-  const key = columns.join("\x00");
-  return objects.some((object) => object.kind === "constraint" && object.definition.constraintKind === "primaryKey" && sameRef(object.identity.parent, parent) && object.definition.columns.join("\x00") === key);
-}
-function sameRef(left, right) {
-  if (left.name !== right.name || left.namespace.form !== right.namespace.form)
-    return false;
-  if (left.namespace.form === "static" && right.namespace.form === "static") {
-    return left.namespace.name === right.namespace.name;
-  }
-  return left.namespace.form === "template" && right.namespace.form === "template" ? left.namespace.pattern === right.namespace.pattern : false;
-}
-function ownedByView(object) {
-  if (object.kind !== "index")
-    return false;
-  return object.dependencies.some((edge) => edge.target.kind === "view" || edge.target.kind === "materializedView");
-}
-function createObjectSql(object, schema) {
-  switch (object.kind) {
-    case "column":
-      return `alter table ${qualify(schema, object.identity.parent.name)} add column ${columnSql(object)}`;
-    case "index":
-      return createIndexSql(object, schema);
-    case "constraint":
-      return `alter table ${qualify(schema, object.identity.parent.name)} add constraint ${quoteIdent(object.identity.name)} ${constraintBody(object, schema)}`;
-    case "sequence":
-      return createSequenceSql(object, schema);
-    case "type":
-      return createTypeSql(object, schema);
-    case "extension":
-      return createExtensionSql(object);
-    case "function":
-      return functionSql(object, schema, false);
-    case "trigger":
-      return triggerSql(object, schema);
-    case "view":
-      return viewSql(object, schema, false);
-    case "materializedView":
-      return materializedViewSql(object, schema);
-    case "table":
-      return;
-    default:
-      return;
-  }
-}
-function functionSql(object, schema, replace) {
-  const definition = object.definition;
-  const args = definition.arguments.map((argument) => `${quoteIdent(argument.name)} ${argument.type}`).join(", ");
-  const head = `${replace ? "create or replace" : "create"} function ${qualify(schema, object.identity.name)}(${args})`;
-  const security = ` security ${definition.security}`;
-  const path = definition.searchPath === undefined ? "" : ` set search_path to ${definition.searchPath}`;
-  const tail = `returns ${definition.returns} language ${definition.language} ${definition.volatility}${security}${path}`;
-  if (definition.atomic)
-    return `${head} ${tail} ${definition.body}`;
-  return `${head} ${tail} as ${dollarQuote(definition.body)}`;
-}
-function viewSql(object, schema, replace) {
-  const verb = replace ? "create or replace view" : "create view";
-  const invoker = object.definition.securityInvoker === true ? " with (security_invoker = true)" : "";
-  return `${verb} ${qualify(schema, object.identity.name)}${invoker} as ${object.definition.query}`;
-}
-function policyCreatePlan(object, schema) {
-  const table = qualify(schema, object.identity.parent.name);
-  const name = quoteIdent(object.identity.name);
-  const command = object.definition.command === "all" ? "all" : "select";
-  const check = object.definition.command === "all" ? ` with check ${object.definition.expression}` : "";
-  const create = {
-    sql: `create policy ${name} on ${table} as permissive for ${command} using ${object.definition.expression}${check}`,
-    kind: "create-policy"
-  };
-  if (object.definition.command !== "all")
-    return [create];
-  return [
-    { sql: `alter table ${table} enable row level security`, kind: "enable-rls" },
-    { sql: `alter table ${table} force row level security`, kind: "enable-rls" },
-    create
-  ];
-}
-function materializedViewSql(object, schema) {
-  return `create materialized view ${qualify(schema, object.identity.name)} as ${object.definition.query} with no data`;
-}
-function triggerSql(object, schema) {
-  const definition = object.definition;
-  const timing = definition.timing === "instead" ? "instead of" : definition.timing;
-  const events = definition.events.map((event) => {
-    if (event !== "update" || definition.updateOf === undefined)
-      return event;
-    return `update of ${definition.updateOf.map((column) => quoteIdent(column)).join(", ")}`;
-  }).join(" or ");
-  const when = definition.when === undefined ? "" : ` when (${definition.when})`;
-  const args = definition.calls.argTypes.join(", ");
-  const fn = `${qualify(schema, definition.calls.name)}(${args})`;
-  return `create trigger ${quoteIdent(object.identity.name)} ${timing} ${events} on ${qualify(schema, object.identity.parent.name)} for each ${definition.level}${when} execute function ${fn}`;
-}
-function dollarQuote(body) {
-  let tag = "okm";
-  while (body.includes(`$${tag}$`))
-    tag = `${tag}_`;
-  return `$${tag}$${body}$${tag}$`;
-}
-function identitySequence(sequence, source) {
-  const key = identityKey(sequence.identity);
-  return source.objects.some((object) => {
-    if (object.kind !== "column" || object.definition.identity === undefined)
-      return false;
-    return object.dependencies.some((edge) => identityKey(edge.target) === key);
-  });
-}
-function foldedKeys(source) {
-  const keys = new Set;
-  for (const object of source.objects) {
-    if (object.kind === "column")
-      keys.add(identityKey(object.identity));
-    if (object.kind === "constraint" && object.definition.constraintKind === "primaryKey") {
-      keys.add(identityKey(object.identity));
-    }
-    if (object.kind === "sequence" && identitySequence(object, source)) {
-      keys.add(identityKey(object.identity));
-    }
-  }
-  return keys;
-}
-function createTableSql(tableObject, source, schema) {
-  const parent = tableObject.identity.name;
-  const columns = source.objects.filter((object) => object.kind === "column" && object.identity.parent.name === parent);
-  const primary = source.objects.find((object) => object.kind === "constraint" && object.definition.constraintKind === "primaryKey" && object.identity.parent.name === parent);
-  const lines = columns.map((column) => columnSql(column));
-  if (primary !== undefined) {
-    const cols = primary.definition.columns.map((name) => quoteIdent(name)).join(", ");
-    lines.push(`constraint ${quoteIdent(primary.identity.name)} primary key (${cols})`);
-  }
-  const partition = tableObject.definition.partition;
-  const tail = partition === undefined ? "" : ` partition by ${partition.method} (${partition.columns.map((name) => quoteIdent(name)).join(", ")})`;
-  return `create table ${qualify(schema, parent)} (
-  ${lines.join(`,
-  `)}
-)${tail}`;
-}
-function collateSql(collation) {
-  if (collation === undefined)
-    return "";
-  return ` collate ${quoteIdent(collation)}`;
-}
-function createTypeSql(object, schema) {
-  if (isDomain(object.definition)) {
-    const name = object.identity.name;
-    const constraint = quoteIdent(fitIdentifier(`${name}_check`));
-    return `create domain ${qualify(schema, name)} as ${object.definition.base} constraint ${constraint} check (${object.definition.check})`;
-  }
-  const labels = object.definition.labels.map((label) => quoteLiteral(label)).join(", ");
-  return `create type ${qualify(schema, object.identity.name)} as enum (${labels})`;
-}
-function columnSql(column) {
-  const definition = column.definition;
-  let sql = `${quoteIdent(column.identity.name)} ${definition.dataType}${collateSql(definition.collation)}`;
-  if (definition.identity !== undefined) {
-    sql += definition.identity.always ? " generated always as identity" : " generated by default as identity";
-  } else if (definition.generated !== undefined) {
-    sql += ` generated always as (${definition.generated.expression}) stored`;
-  }
-  if (!definition.nullable)
-    sql += " not null";
-  if (definition.defaultExpression !== undefined)
-    sql += ` default ${definition.defaultExpression}`;
-  return sql;
-}
-function createIndexSql(object, schema) {
-  const unique = object.definition.unique ? "unique " : "";
-  const where = object.definition.predicate === undefined ? "" : ` where ${object.definition.predicate}`;
-  const expression = object.definition.expression;
-  const name = quoteIdent(object.identity.name);
-  const on = qualify(schema, object.identity.parent.name);
-  if (expression !== undefined && expression.startsWith("using ")) {
-    return `create ${unique}index ${name} on ${on} ${expression}${where}`;
-  }
-  const target = expression !== undefined ? `(${expression})` : object.definition.columns.map((column) => quoteIdent(column)).join(", ");
-  return `create ${unique}index ${name} on ${on} (${target})${where}`;
-}
-function createExtensionSql(object) {
-  const version = object.definition.version;
-  const pinned = version !== undefined && /^\d+(?:\.\d+)*$/.test(version) ? ` version ${quoteLiteral(version)}` : "";
-  return `create extension ${quoteIdent(object.identity.name)} schema ${quoteIdent(object.definition.schema)}${pinned}`;
-}
-function createSequenceSql(object, schema) {
-  const definition = object.definition;
-  const cycle = definition.cycle ? " cycle" : "";
-  return `create sequence ${qualify(schema, object.identity.name)} as ${definition.dataType} start ${definition.start} increment ${definition.increment}${cycle}`;
-}
-function constraintBody(object, schema) {
-  const definition = object.definition;
-  const columns = definition.columns.map((name) => quoteIdent(name)).join(", ");
-  switch (definition.constraintKind) {
-    case "primaryKey":
-      return `primary key (${columns})`;
-    case "unique": {
-      const nulls = definition.nullsNotDistinct ? " nulls not distinct" : "";
-      return `unique${nulls} (${columns})${deferClause(definition)}`;
-    }
-    case "check":
-      return `check (${definition.expression ?? "true"})${deferClause(definition)}`;
-    case "foreignKey": {
-      const references = definition.references;
-      const target = references === undefined ? "" : ` references ${qualify(schema, references.parent.name)} (${references.columns.map((name) => quoteIdent(name)).join(", ")})`;
-      const onDelete = references?.onDelete === undefined ? "" : ` on delete ${references.onDelete}`;
-      const onUpdate = references?.onUpdate === undefined ? "" : ` on update ${references.onUpdate}`;
-      return `foreign key (${columns})${target}${onDelete}${onUpdate}${deferClause(definition)}`;
-    }
-    default:
-      return definition.constraintKind;
-  }
-}
-function deferClause(definition) {
-  if (!definition.deferrable)
-    return "";
-  return ` deferrable initially ${definition.initially}`;
-}
-function qualify(schema, name) {
-  return `${quoteIdent(schema)}.${quoteIdent(name)}`;
-}
-
 // src/contracts/location.ts
 function callerLocation(skip) {
   const lines = new Error().stack?.split(`
@@ -1221,7 +904,7 @@ function openFilters(table, relations, spec, hiddenFields) {
   }
   return {
     parse(query) {
-      return import("./shared/03k6res6.js").then((mod) => mod.parseQuery(allow, sort, query, nested));
+      return import("./shared/zs9aymcp.js").then((mod) => mod.parseQuery(allow, sort, query, nested));
     }
   };
 }
@@ -3777,7 +3460,7 @@ function registerTxSuite(suite) {
         max: options.max ?? 4,
         ...options.url ? { url: options.url } : {}
       });
-      const ddl = [...renderCatalog(built.catalog, schemaName), ...options.sql ?? []];
+      const ddl = [...renderCatalog2(built.catalog, schemaName), ...options.sql ?? []];
       for (const statement of ddl)
         await (setup ?? pool).execute(statement);
       const db = await suite.connect(pool, {
@@ -4622,7 +4305,7 @@ function skipped(test, reason) {
   return skipFor(test, reason, (name) => `${name} (${reason})`);
 }
 async function openSuiteAdmin(url) {
-  const { openPostgres } = await import("./shared/pwsytxm5.js");
+  const { openPostgres } = await import("./shared/wezxf3h8.js");
   return openPostgres(url);
 }
 async function failure2(promise) {
@@ -4720,8 +4403,8 @@ async function loadTarget(driver, url) {
 }
 async function firstParty(driver, url) {
   if (driver === "pglite") {
-    const adapter = await import("./shared/dy672fz6.js");
-    const runtime = await import("./shared/9xzm7hjg.js");
+    const adapter = await import("./shared/s6qha57m.js");
+    const runtime = await import("./shared/5p8km5jb.js");
     return {
       name: "pglite",
       capabilities: adapter.capabilities,
@@ -4736,8 +4419,8 @@ async function firstParty(driver, url) {
   if (url === undefined)
     throw new Error(`okm driver test ${driver} needs --url or DATABASE_URL.`);
   if (driver === "postgresjs") {
-    const adapter = await import("./shared/y031jct9.js");
-    const runtime = await import("./shared/vraj6d74.js");
+    const adapter = await import("./shared/mw5npye0.js");
+    const runtime = await import("./shared/nxq95eb6.js");
     return networked("postgres.js", adapter.capabilities, true, url, (config) => adapter.open({
       url: config.url ?? url,
       max: config.max,
@@ -4746,8 +4429,8 @@ async function firstParty(driver, url) {
     }), (pool, options) => runtime.connect(pool, options));
   }
   if (driver === "pg") {
-    const adapter = await import("./shared/nf7jmhfa.js");
-    const runtime = await import("./shared/jne7b93p.js");
+    const adapter = await import("./shared/a4pzghha.js");
+    const runtime = await import("./shared/v6j1ep6w.js");
     return networked("node-postgres", adapter.capabilities, true, url, (config) => adapter.open({
       url: config.url ?? url,
       max: config.max,
@@ -4756,8 +4439,8 @@ async function firstParty(driver, url) {
     }), (pool, options) => runtime.connect(pool, options));
   }
   if (driver === "neon") {
-    const adapter = await import("./shared/7ae7rjmn.js");
-    const runtime = await import("./shared/8sqrsw3s.js");
+    const adapter = await import("./shared/68tf18v4.js");
+    const runtime = await import("./shared/9sfbtwsk.js");
     return networked("neon", adapter.capabilities, false, url, (config) => adapter.open({
       url: config.url ?? url,
       max: config.max,
@@ -4768,8 +4451,8 @@ async function firstParty(driver, url) {
   if (typeof Bun === "undefined" || typeof Bun.SQL !== "function") {
     throw new Error("bun runs only under Bun.");
   }
-  const adapter = await import("./shared/a7q7t4n3.js");
-  const runtime = await import("./shared/a6pp9d12.js");
+  const adapter = await import("./shared/m3xt8b1h.js");
+  const runtime = await import("./shared/1800eymw.js");
   return networked("bun.sql", adapter.capabilities, false, url, (config) => adapter.open({
     url: config.url ?? url,
     max: config.max,

package/dist/tooling/github/comment.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pull-request comment for `okm migrate plan --json` (D279).
+ *
+ * The text comes from the plan document. It does not read the human plan.
+ */
+import { type PlanDocument } from "../migrate/plan-json.js";
+/**
+ * Hidden marker that identifies the sticky comment.
+ *
+ * A later push updates the comment whose body contains this marker.
+ */
+export declare const PLAN_COMMENT_MARKER = "<!-- okmodel-migrate-plan -->";
+/** A comment the sticky update may replace. */
+export type StickyComment = {
+    readonly id: number;
+    readonly body: string;
+};
+/**
+ * Renders the plan comment.
+ *
+ * The first heading is the strictest class. Each step is one table row
+ * with its class and lock. The lock is the plan's lock line, including a
+ * row estimate when the plan printed one. Lint findings keep their codes.
+ *
+ * @param plan - Document from `okm migrate plan --json`
+ * @returns Markdown, including {@link PLAN_COMMENT_MARKER}
+ */
+export declare function renderPlanComment(plan: PlanDocument): string;
+/**
+ * Comment body for a plan file, or a status line when the file is not a document.
+ *
+ * The status line records exit codes only. It does not include command text.
+ *
+ * @param text - Stdout of `okm migrate plan --json`, when the file exists
+ * @param checkStatus - Exit code of `okm migrate check`
+ * @param planStatus - Exit code of `okm migrate plan --json`
+ * @returns The comment body
+ */
+export declare function planCommentBody(text: string | undefined, checkStatus: string, planStatus: string): string;
+/**
+ * The comment to update, when one already carries the marker.
+ *
+ * The first match wins. A missing match means the caller creates a comment.
+ *
+ * @param comments - Comments already on the pull request
+ * @returns The id to update, or `undefined` to create one
+ */
+export declare function stickyCommentTarget(comments: readonly StickyComment[]): {
+    readonly updateId: number;
+} | undefined;

package/dist/tooling/github/post-comment.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Creates or updates the sticky plan comment (D279).
+ *
+ * Uses `GITHUB_TOKEN` only. The workflow needs `pull-requests: write`.
+ * The token is not written to stdout or stderr.
+ */
+/**
+ * Posts the plan comment for one pull request.
+ *
+ * An existing comment that contains the marker is updated. Otherwise a
+ * comment is created. The body comes from {@link planCommentBody}.
+ *
+ * @param planPath - File written by `okm migrate plan --json`
+ * @param checkStatus - Exit code of `okm migrate check`
+ * @param planStatus - Exit code of `okm migrate plan --json`
+ */
+export declare function postPlanComment(planPath: string, checkStatus: string, planStatus: string): Promise<void>;

package/dist/tooling/migrate/commands.d.ts

@@ -22,7 +22,8 @@ export declare function formatFailure(error: unknown, verbose?: boolean): string
  * Runs one `okm` invocation.
  *
  * `--version` stays in the bin. This function handles `build`, `check`,
- * `generate`, `dev`, `push`, `seed`, `ext list`, `ext check`, `doctor`,
+ * `generate`, `dev`, `push`, `seed`, `ext list`, `ext check`, `ext scaffold`,
+ * `ext test`, `doctor`,
  * `driver test`, and `migrate plan`, `apply`, `status`, and `check`.
  *
  * @param argv - Arguments after the program name

package/dist/tooling/migrate/config.d.ts

@@ -45,6 +45,19 @@ export type MigrateConfig = {
      * migration.
      */
     readonly lintFrom?: string;
+    /**
+     * Postgres schema this catalog owns.
+     *
+     * Omitted means `public`. `schema()` still compiles `public`. Tooling
+     * places the catalog here before it plans, and stores `okm_meta` here.
+     */
+    readonly namespace?: string;
+    /**
+     * Snapshots from `okm catalog export`, one path per owning catalog.
+     *
+     * `external()` tables are verified against these files.
+     */
+    readonly external?: readonly string[];
     /**
      * Batched backfill (D195).
      *

package/dist/tooling/migrate/export.d.ts

@@ -0,0 +1,165 @@
+/**
+ * `okm catalog export` and the check that a dependent catalog runs.
+ *
+ * The snapshot is derived from the schema source. It stores the catalog
+ * hash and, separately, a logical identity. It has no function and no
+ * connection URL. Column names and types are what a dependent verifies.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import type { MigrateConfig } from "./config.js";
+import type { Finding } from "./lint.js";
+/** Snapshot file format. Not the logical schema format. */
+export declare const EXPORT_FORMAT = 1;
+/** Logical schema format. A hash change does not move this. */
+export declare const LOGICAL_FORMAT = 1;
+/** One column a dependent verifies. No default and no expression. */
+export type ExportColumn = {
+    readonly name: string;
+    readonly type: string;
+    readonly nullable: boolean;
+};
+/** One table in a snapshot. */
+export type ExportTable = {
+    readonly namespace: string;
+    readonly name: string;
+    readonly columns: readonly ExportColumn[];
+};
+/**
+ * Logical schema identity.
+ *
+ * `namespace` and `name` name the schema. `format` is {@link LOGICAL_FORMAT}.
+ * None of these is the catalog hash.
+ */
+export type LogicalIdentity = {
+    readonly namespace: string;
+    readonly name: string;
+    readonly format: typeof LOGICAL_FORMAT;
+};
+/**
+ * A catalog snapshot.
+ *
+ * `catalogHash` is the physical identity. `logical` is not that hash.
+ * `database` is the database name only, never a URL.
+ */
+export type CatalogSnapshot = {
+    readonly format: typeof EXPORT_FORMAT;
+    readonly logical: LogicalIdentity;
+    readonly catalogHash: string;
+    readonly database?: string;
+    readonly tables: readonly ExportTable[];
+};
+/**
+ * Builds a snapshot from a placed catalog.
+ *
+ * @param source - Catalog tooling plans, after namespace placement
+ * @param namespace - `defineConfig({ namespace })`, or `public`
+ * @param database - Database name, when the config has a target URL
+ * @returns A snapshot with no functions and no connection URL
+ */
+export declare function snapshotFromCatalog(source: Catalog, namespace: string, database?: string): CatalogSnapshot;
+/**
+ * Serializes a snapshot.
+ *
+ * The same catalog returns the same bytes, including the trailing newline.
+ *
+ * @param snapshot - Snapshot to write
+ * @returns UTF-8 JSON
+ */
+export declare function serializeSnapshot(snapshot: CatalogSnapshot): string;
+/**
+ * Reads a snapshot file.
+ *
+ * A missing file and a file that is not this format are OKM1841.
+ *
+ * @param path - Absolute or project-relative path, as the message should name it
+ * @param text - File contents
+ * @returns The snapshot
+ */
+export declare function parseSnapshot(path: string, text: string): CatalogSnapshot;
+/**
+ * Database name from a Postgres URL.
+ *
+ * The user, password, host, and query are not returned.
+ *
+ * @param url - Target URL
+ * @returns The path segment, or `undefined` when the URL has none
+ */
+export declare function databaseName(url: string): string | undefined;
+/**
+ * Namespace `defineConfig` asked for.
+ *
+ * Omitted means `public`.
+ *
+ * @param config - Project config
+ * @returns The schema name
+ */
+export declare function catalogNamespace(config: MigrateConfig): string;
+/**
+ * Loads the snapshots named by `defineConfig({ external })`.
+ *
+ * A missing path is OKM1841.
+ *
+ * @param cwd - Project directory
+ * @param config - Project config
+ * @returns One snapshot per path, in config order
+ */
+export declare function loadSnapshots(cwd: string, config: MigrateConfig): readonly LoadedSnapshot[];
+/** A snapshot and the config path that named it. */
+export type LoadedSnapshot = {
+    readonly path: string;
+    readonly snapshot: CatalogSnapshot;
+};
+/**
+ * SQL table name to the namespace recorded in a snapshot.
+ *
+ * @param snapshots - Loaded exports
+ * @returns The map `placeCatalog` reads
+ */
+export declare function externalNamespaceMap(snapshots: readonly LoadedSnapshot[]): ReadonlyMap<string, string>;
+/**
+ * Cross-catalog foreign keys, as `okm check` warnings.
+ *
+ * A key inside one namespace is not coupling. The warning does not fail the check.
+ *
+ * @param source - Placed catalog
+ * @returns One warning per foreign key whose namespaces differ
+ */
+export declare function couplingFindings(source: Catalog): readonly Finding[];
+/**
+ * Checks external tables against the snapshot files.
+ *
+ * This does not open a connection. With no `external` paths, a
+ * `withOwner(..., "external")` table stays hands-off and is not OKM1841.
+ * When paths are set, a missing file, a table the snapshots do not list,
+ * or columns that differ is OKM1841.
+ *
+ * @param cwd - Project directory
+ * @param config - Project config
+ * @param source - Placed catalog
+ */
+export declare function assertSnapshots(cwd: string, config: MigrateConfig, source: Catalog): void;
+/**
+ * Checks external tables against the connected database.
+ *
+ * A different database name on a cross-catalog foreign key is OKM1842.
+ * A hash or column mismatch is a stale snapshot. A missing relation is
+ * a missing object. Both are OKM1841.
+ *
+ * @param url - Target URL
+ * @param source - Placed catalog
+ * @param snapshots - Files {@link assertSnapshots} already read
+ */
+export declare function assertLiveExternal(url: string, source: Catalog, snapshots: readonly LoadedSnapshot[]): Promise<void>;
+/**
+ * Writes the snapshot for one project.
+ *
+ * `--json` prints the bytes. `--out` writes them. With neither, the bytes
+ * are printed.
+ *
+ * @param cwd - Project directory
+ * @param config - Project config
+ * @param source - Placed catalog
+ * @param args - Arguments after `export`
+ * @returns Stdout, including a trailing newline
+ */
+export declare function renderExport(cwd: string, config: MigrateConfig, source: Catalog, args: readonly string[]): string;