@shapecraft/core 1.0.0

package/src/shape/transforms/sql/parser/create-table.ts

@@ -0,0 +1,809 @@
+import { ReferentialAction } from "../../../annotation";
+import { annotate, shapes } from "../../../shape";
+import { SQLDialect } from "../options";
+import { checkExprToSql, decodeCheck } from "./check-decoder";
+import { ParseError, TokenCursor } from "./cursor";
+import { decodeDefault } from "./default-decoder";
+import { Token } from "./lexer";
+import { Registries, resolvePgType } from "./pg-types";
+import { resolveSqliteType } from "./sqlite-types";
+import { parseTypeSpec, ParsedTypeSpec } from "./type-spec";
+
+export type ParsedTable = {
+  schema?: string;
+  name: string;
+  columns: Array<{ key: string; shape: shapes.Shape }>;
+  uniqueConstraints?: Array<{ columns: string[]; name?: string }>;
+  mappingAnno: {
+    title: string;
+    schema?: string;
+    check?: string;
+    description?: string;
+  };
+};
+
+export type ParseTableOptions = {
+  registries: Registries;
+  dialect: SQLDialect;
+};
+
+const qualifiedName = (parts: string[]): { schema?: string; name: string } => {
+  if (parts.length === 1) return { name: parts[0]! };
+  return { schema: parts[0]!, name: parts.slice(1).join(".") };
+};
+
+const splitAtTopLevelCommas = (tokens: Token[]): Token[][] => {
+  const out: Token[][] = [];
+  let buf: Token[] = [];
+  let depth = 0;
+  for (const t of tokens) {
+    if (t.kind === "punct" && t.value === "(") depth += 1;
+    else if (t.kind === "punct" && t.value === ")") depth -= 1;
+    if (t.kind === "punct" && t.value === "," && depth === 0) {
+      if (buf.length > 0) out.push(buf);
+      buf = [];
+      continue;
+    }
+    buf.push(t);
+  }
+  if (buf.length > 0) out.push(buf);
+  return out;
+};
+
+const REF_ACTION_MAP: Record<string, ReferentialAction> = {
+  cascade: "cascade",
+  restrict: "restrict",
+  // "set null" / "set default" are two-word — handled in parsing
+};
+
+const parseReferentialAction = (c: TokenCursor): ReferentialAction | null => {
+  if (c.consumeIdent("cascade")) return "cascade";
+  if (c.consumeIdent("restrict")) return "restrict";
+  if (c.consumeIdent("no")) {
+    c.consumeIdent("action");
+    return "noAction";
+  }
+  if (c.consumeIdent("set")) {
+    if (c.consumeIdent("null")) return "setNull";
+    if (c.consumeIdent("default")) return "setDefault";
+    return null;
+  }
+  return null;
+};
+
+// Read the type spec tokens up to where a column constraint keyword begins
+// (or end of column-def). Returns the consumed tokens.
+const readTypeTokens = (c: TokenCursor): Token[] => {
+  const out: Token[] = [];
+  // first ident (the base type or first part of qualified name)
+  if (c.peek().kind !== "ident") {
+    // unexpected — caller should error
+    return out;
+  }
+  out.push(c.consume());
+  // dotted continuation
+  while (c.isPunct(".")) {
+    out.push(c.consume()); // '.'
+    if (c.peek().kind !== "ident") break;
+    out.push(c.consume());
+  }
+  // multi-word types: peek for known continuations
+  const firstTwoExtend = (a: string, b: string): boolean => {
+    const combos = [
+      "double precision",
+      "character varying",
+      "bit varying",
+      "timestamp with",
+      "time with",
+      "timestamp without",
+      "time without",
+    ];
+    return combos.includes(`${a} ${b}`);
+  };
+  const first = out[0]?.value;
+  const next = c.peek();
+  if (
+    typeof first === "string" &&
+    next.kind === "ident" &&
+    !next.quoted &&
+    firstTwoExtend(first, next.value)
+  ) {
+    out.push(c.consume());
+    // possibly "time zone" suffix
+    if (c.isIdent("time") && c.peek(1).kind === "ident") {
+      const t1 = c.peek(1);
+      if (t1.kind === "ident" && t1.value === "zone") {
+        out.push(c.consume());
+        out.push(c.consume());
+      }
+    }
+  }
+  // optional (args)
+  if (c.isPunct("(")) {
+    out.push(c.consume());
+    let depth = 1;
+    while (!c.done() && depth > 0) {
+      const t = c.peek();
+      if (t.kind === "punct" && t.value === "(") depth += 1;
+      if (t.kind === "punct" && t.value === ")") depth -= 1;
+      out.push(c.consume());
+    }
+  }
+  // optional [] array suffix
+  while (
+    c.isPunct("[") &&
+    c.peek(1).kind === "punct" &&
+    c.peek(1).value === "]"
+  ) {
+    out.push(c.consume());
+    out.push(c.consume());
+  }
+  return out;
+};
+
+type ColMeta = {
+  notNull: boolean;
+  primary: boolean;
+  unique: boolean;
+  autoIncrement: boolean;
+  default?: { kind: "literal"; value: unknown } | { kind: "expr"; sql: string };
+  foreign?: {
+    table: string;
+    column: string;
+    onDelete?: ReferentialAction;
+    onUpdate?: ReferentialAction;
+  };
+  generated?: { expression: string; stored: boolean };
+  checks: Array<Token[]>;
+};
+
+// Convert generated-as-expression tokens to a clean SQL string.
+const tokensToExprSql = (tokens: Token[]): string => checkExprToSql(tokens);
+
+const parseColumnConstraints = (c: TokenCursor): ColMeta => {
+  const meta: ColMeta = {
+    notNull: false,
+    primary: false,
+    unique: false,
+    autoIncrement: false,
+    checks: [],
+  };
+  while (!c.done()) {
+    if (c.consumeIdent("constraint")) {
+      // anonymous constraint name — consume it
+      if (c.peek().kind === "ident") c.consume();
+      continue;
+    }
+    if (c.consumeIdent("not")) {
+      if (c.consumeIdent("null")) {
+        meta.notNull = true;
+        continue;
+      }
+      // unknown form — bail
+      break;
+    }
+    if (c.consumeIdent("null")) {
+      // explicit NULL — nothing to do
+      continue;
+    }
+    if (c.consumeIdent("primary")) {
+      c.consumeIdent("key");
+      meta.primary = true;
+      continue;
+    }
+    if (c.consumeIdent("autoincrement")) {
+      // SQLite-only keyword, but accepting it in any dialect is harmless.
+      meta.autoIncrement = true;
+      continue;
+    }
+    if (c.consumeIdent("unique")) {
+      meta.unique = true;
+      continue;
+    }
+    if (c.consumeIdent("default")) {
+      const defTokens = readDefaultExpr(c);
+      meta.default = decodeDefault(defTokens, null);
+      continue;
+    }
+    if (c.consumeIdent("references")) {
+      meta.foreign = parseReferencesClause(c);
+      continue;
+    }
+    if (c.consumeIdent("check")) {
+      const inner = c.skipParens();
+      meta.checks.push(inner);
+      continue;
+    }
+    if (c.consumeIdent("generated")) {
+      // GENERATED [ALWAYS|BY DEFAULT] AS (...) STORED
+      // GENERATED [ALWAYS|BY DEFAULT] AS IDENTITY [(seq opts)]
+      let byDefault = false;
+      if (c.consumeIdent("always")) {
+        /* */
+      } else if (c.consumeIdent("by")) {
+        c.consumeIdent("default");
+        byDefault = true;
+      }
+      c.expectIdent("as");
+      if (c.consumeIdent("identity")) {
+        meta.autoIncrement = true;
+        // optional (sequence options)
+        if (c.isPunct("(")) c.skipParens();
+        continue;
+      }
+      // expression
+      const inner = c.skipParens();
+      // STORED keyword (optional but typical)
+      let stored = true;
+      if (c.consumeIdent("stored")) stored = true;
+      if (c.consumeIdent("virtual")) stored = false;
+      meta.generated = { expression: tokensToExprSql(inner), stored };
+      if (byDefault) {
+        // not really meaningful for expression-generated columns; ignore
+      }
+      continue;
+    }
+    if (c.consumeIdent("collate")) {
+      // collate name — consume one ident
+      if (c.peek().kind === "ident") c.consume();
+      continue;
+    }
+    if (c.consumeIdent("deferrable")) continue;
+    if (c.consumeIdent("not") && c.consumeIdent("deferrable")) continue;
+    if (c.consumeIdent("initially")) {
+      if (c.peek().kind === "ident") c.consume();
+      continue;
+    }
+    // Unrecognized constraint — bail
+    break;
+  }
+  return meta;
+};
+
+const parseReferencesClause = (
+  c: TokenCursor,
+): {
+  table: string;
+  column: string;
+  onDelete?: ReferentialAction;
+  onUpdate?: ReferentialAction;
+} => {
+  const parts = c.readDottedName();
+  const qn = qualifiedName(parts);
+  let column = "id";
+  if (c.consumePunct("(")) {
+    const colTok = c.expectAnyIdent();
+    column = colTok.name;
+    c.expectPunct(")");
+  }
+  const out: {
+    table: string;
+    column: string;
+    onDelete?: ReferentialAction;
+    onUpdate?: ReferentialAction;
+  } = { table: qn.name, column };
+  while (c.consumeIdent("on")) {
+    if (c.consumeIdent("delete")) {
+      const a = parseReferentialAction(c);
+      if (a !== null) out.onDelete = a;
+    } else if (c.consumeIdent("update")) {
+      const a = parseReferentialAction(c);
+      if (a !== null) out.onUpdate = a;
+    } else break;
+  }
+  // MATCH FULL / SIMPLE / PARTIAL — consume
+  if (c.consumeIdent("match")) {
+    if (c.peek().kind === "ident") c.consume();
+  }
+  return out;
+};
+
+// Read a DEFAULT expression — terminate on a known constraint-start keyword
+// or end of input.
+const readDefaultExpr = (c: TokenCursor): Token[] => {
+  const out: Token[] = [];
+  let depth = 0;
+  const STOP = new Set([
+    "not",
+    "null",
+    "primary",
+    "unique",
+    "references",
+    "check",
+    "default",
+    "generated",
+    "constraint",
+    "collate",
+    "deferrable",
+    "initially",
+  ]);
+  while (!c.done()) {
+    const t = c.peek();
+    if (t.kind === "punct" && t.value === "(") depth += 1;
+    if (t.kind === "punct" && t.value === ")") depth -= 1;
+    if (depth === 0 && t.kind === "ident" && !t.quoted && STOP.has(t.value))
+      break;
+    out.push(t);
+    c.consume();
+  }
+  return out;
+};
+
+// Apply a column shape with the column metadata to produce a final shape with
+// annotations folded in. `ctx.isString/isInteger/isArray` are derived from the
+// resolved base shape.
+const applyColumnMeta = (
+  baseShape: shapes.Shape,
+  meta: ColMeta,
+  pgType: string,
+  columnName: string,
+): shapes.Shape => {
+  // First pass: collect all decoded CHECK updates and the leftover raw
+  // expressions. Aggregating before applying lets us swap the base shape
+  // (e.g. INTEGER → boolean, TEXT → array) based on the union of hints
+  // rather than the order they appeared.
+  const ctx = {
+    columnName,
+    isInteger: baseShape.type === "number",
+    isString: baseShape.type === "string",
+    isArray: baseShape.type === "array",
+  };
+  const combined: {
+    min?: number;
+    max?: number;
+    pattern?: string;
+    uniqueItems?: boolean;
+    unionLiterals?: string[];
+    isBooleanInt?: boolean;
+    isJsonValid?: boolean;
+    tupleLength?: number;
+  } = {};
+  const rawChecks: string[] = [];
+  for (const chkTokens of meta.checks) {
+    const dec = decodeCheck(chkTokens, ctx);
+    if (!dec.fullyDecoded) {
+      rawChecks.push(checkExprToSql(chkTokens));
+      continue;
+    }
+    const u = dec.updates;
+    if (u.min !== undefined) combined.min = u.min;
+    if (u.max !== undefined) combined.max = u.max;
+    if (u.pattern !== undefined) combined.pattern = u.pattern;
+    if (u.uniqueItems === true) combined.uniqueItems = true;
+    if (u.unionLiterals !== undefined) combined.unionLiterals = u.unionLiterals;
+    if (u.isBooleanInt === true) combined.isBooleanInt = true;
+    if (u.isJsonValid === true) combined.isJsonValid = true;
+    if (u.tupleLength !== undefined) combined.tupleLength = u.tupleLength;
+  }
+
+  // Swap the base shape if CHECKs reveal a different underlying type.
+  let shape: shapes.Shape = baseShape;
+  if (combined.isBooleanInt === true && baseShape.type === "number") {
+    shape = shapes.boolean();
+  } else if (combined.isJsonValid === true && baseShape.type === "string") {
+    if (combined.tupleLength !== undefined) {
+      const items: shapes.Shape[] = [];
+      for (let i = 0; i < combined.tupleLength; i += 1)
+        items.push(shapes.unknown());
+      shape = shapes.tuple(...items);
+    } else if (
+      combined.min !== undefined ||
+      combined.max !== undefined ||
+      combined.uniqueItems === true
+    ) {
+      shape = shapes.array(shapes.unknown());
+    } else {
+      shape = shapes.unknown();
+    }
+  } else if (
+    combined.unionLiterals !== undefined &&
+    baseShape.type === "string"
+  ) {
+    const literals = combined.unionLiterals.map((v) => shapes.literal(v));
+    shape = shapes.union(literals);
+  }
+
+  if (!meta.notNull && !meta.primary) {
+    shape = annotate.optional(shape);
+  }
+  if (meta.primary) {
+    shape = annotate.primary(shape);
+  }
+  if (meta.unique) {
+    shape = annotate.unique(shape);
+  }
+  if (meta.autoIncrement) {
+    shape = annotate.autoIncremented(shape);
+  }
+  if (meta.foreign !== undefined) {
+    shape = annotate.as(shape, { foreign: meta.foreign });
+  }
+  if (meta.generated !== undefined) {
+    shape = annotate.as(shape, { generated: meta.generated });
+  }
+  // On a date column, re-interpret a bare string literal as a Date (SQLite
+  // emits `DEFAULT '2024-01-01T…'` without a `::timestamptz` cast, so the
+  // base decoder leaves it as a string).
+  if (
+    meta.default !== undefined &&
+    meta.default.kind === "literal" &&
+    typeof meta.default.value === "string" &&
+    baseShape.type === "date"
+  ) {
+    const d = new Date(meta.default.value);
+    const t = d.getTime();
+    if (!isNaN(t) && isFinite(t)) {
+      meta.default = { kind: "literal", value: d };
+    }
+  }
+  // If the column was swapped to boolean (SQLite INTEGER + IN(0,1)),
+  // re-interpret 0/1 numeric defaults as boolean.
+  if (
+    meta.default !== undefined &&
+    meta.default.kind === "literal" &&
+    typeof meta.default.value === "number" &&
+    shape.type === "boolean" &&
+    (meta.default.value === 0 || meta.default.value === 1)
+  ) {
+    meta.default = { kind: "literal", value: meta.default.value === 1 };
+  }
+
+  if (meta.default !== undefined) {
+    if (meta.default.kind === "literal") {
+      shape = annotate.as(shape, { default: meta.default.value });
+    } else {
+      // decode might have given an empty string for malformed input — skip in that case
+      if (meta.default.sql.length > 0) {
+        shape = annotate.as(shape, { defaultExpr: meta.default.sql });
+      }
+    }
+  }
+  // Re-decode defaults that need the pg type context (specifically for `'{}'` on T[])
+  if (
+    meta.default !== undefined &&
+    meta.default.kind === "expr" &&
+    pgType.endsWith("[]") &&
+    /^'\{}'$/.test(meta.default.sql.trim())
+  ) {
+    shape = annotate.as(shape, { default: [] });
+  }
+
+  if (combined.min !== undefined) {
+    shape = annotate.as(shape, { min: combined.min });
+  }
+  if (combined.max !== undefined) {
+    shape = annotate.as(shape, { max: combined.max });
+  }
+  if (combined.pattern !== undefined) {
+    shape = annotate.as(shape, { pattern: combined.pattern });
+  }
+  if (combined.uniqueItems === true) {
+    shape = annotate.as(shape, { uniqueItems: true });
+  }
+  for (const raw of rawChecks) {
+    shape = annotate.as(shape, { check: raw });
+  }
+
+  return shape;
+};
+
+export const parseCreateTable = (
+  tokens: Token[],
+  opts: ParseTableOptions,
+): ParsedTable => {
+  const c = new TokenCursor(tokens);
+  c.expectIdent("create");
+  if (c.consumeIdent("or")) c.expectIdent("replace");
+  // optional UNLOGGED / TEMPORARY etc.
+  c.consumeIdent("global");
+  c.consumeIdent("local");
+  c.consumeIdent("temporary");
+  c.consumeIdent("temp");
+  c.consumeIdent("unlogged");
+  c.expectIdent("table");
+  if (c.consumeIdent("if")) {
+    c.expectIdent("not");
+    c.expectIdent("exists");
+  }
+  const nameParts = c.readDottedName();
+  const qn = qualifiedName(nameParts);
+
+  c.expectPunct("(");
+  // collect everything inside the outer parens as defs
+  const defsTokens: Token[] = [];
+  let depth = 1;
+  while (!c.done() && depth > 0) {
+    const t = c.peek();
+    if (t.kind === "punct" && t.value === "(") depth += 1;
+    if (t.kind === "punct" && t.value === ")") {
+      depth -= 1;
+      if (depth === 0) {
+        c.consume();
+        break;
+      }
+    }
+    defsTokens.push(t);
+    c.consume();
+  }
+  // anything after the closing paren (PARTITION BY, WITH, etc.) is dropped
+
+  const items = splitAtTopLevelCommas(defsTokens);
+
+  const columns: Array<{ key: string; shape: shapes.Shape }> = [];
+  // Maps to apply table constraints retroactively
+  const colIndex = new Map<string, number>();
+  const colMetas = new Map<string, ColMeta>();
+  const baseShapeByName = new Map<string, shapes.Shape>();
+  const pgTypeByName = new Map<string, string>();
+  let tableCheck: string | undefined;
+  const uniqueConstraints: Array<{ columns: string[]; name?: string }> = [];
+
+  for (const item of items) {
+    if (isTableConstraint(item)) continue; // process in second pass
+    const ic = new TokenCursor(item);
+    const ident = ic.peek();
+    if (ident.kind !== "ident") {
+      throw new ParseError(
+        `expected column definition but found ${ident.kind}`,
+        ident.pos,
+      );
+    }
+    const colTok = ic.expectAnyIdent();
+    const typeTokens = readTypeTokens(ic);
+    const spec = parseTypeSpec(typeTokens);
+    const resolved =
+      opts.dialect === "sqlite" ?
+        resolveSqliteType(spec)
+      : resolvePgType(spec, opts.registries);
+    let baseShape = resolved.shape;
+    const meta = parseColumnConstraints(ic);
+    if (resolved.autoIncrement === true) {
+      meta.autoIncrement = true;
+    }
+    const pgType = typeSpecToString(spec);
+    const finalShape = applyColumnMeta(baseShape, meta, pgType, colTok.name);
+    columns.push({ key: colTok.name, shape: finalShape });
+    colIndex.set(colTok.name, columns.length - 1);
+    colMetas.set(colTok.name, meta);
+    baseShapeByName.set(colTok.name, baseShape);
+    pgTypeByName.set(colTok.name, pgType);
+  }
+
+  // Second pass: table constraints
+  for (const item of items) {
+    if (!isTableConstraint(item)) continue;
+    applyTableConstraint(item, {
+      columns,
+      colIndex,
+      pgTypeByName,
+      setTableCheck: (chk) => {
+        tableCheck = chk;
+      },
+      pushUniqueConstraint: (entry) => {
+        uniqueConstraints.push(entry);
+      },
+    });
+  }
+
+  const mappingAnno: ParsedTable["mappingAnno"] = { title: qn.name };
+  // In SQLite, a `main.foo`/`temp.foo` prefix is a database alias, not a
+  // schema in the PG sense. Drop it so re-emission doesn't try to write a
+  // `CREATE SCHEMA` prelude (which SQLite doesn't have).
+  if (qn.schema !== undefined && opts.dialect !== "sqlite") {
+    mappingAnno.schema = qn.schema;
+  }
+  if (tableCheck !== undefined) mappingAnno.check = tableCheck;
+
+  const out: ParsedTable = {
+    name: qn.name,
+    columns,
+    mappingAnno,
+  };
+  if (qn.schema !== undefined && opts.dialect !== "sqlite") {
+    out.schema = qn.schema;
+  }
+  if (uniqueConstraints.length > 0) out.uniqueConstraints = uniqueConstraints;
+  return out;
+};
+
+const typeSpecToString = (spec: ParsedTypeSpec): string => {
+  const base = spec.qualified ?? spec.baseName;
+  const args = spec.args.length > 0 ? `(${spec.args.join(",")})` : "";
+  const arr = spec.isArray ? "[]" : "";
+  return `${base}${args}${arr}`;
+};
+
+const isTableConstraint = (item: Token[]): boolean => {
+  const t0 = item[0];
+  if (t0 === undefined || t0.kind !== "ident") return false;
+  if (t0.value === "constraint") return true;
+  if (
+    t0.value === "primary" &&
+    item[1]?.kind === "ident" &&
+    item[1].value === "key" &&
+    item[2]?.kind === "punct" &&
+    item[2].value === "("
+  )
+    return true;
+  if (
+    t0.value === "unique" &&
+    item[1]?.kind === "punct" &&
+    item[1].value === "("
+  )
+    return true;
+  if (
+    t0.value === "foreign" &&
+    item[1]?.kind === "ident" &&
+    item[1].value === "key"
+  )
+    return true;
+  if (
+    t0.value === "check" &&
+    item[1]?.kind === "punct" &&
+    item[1].value === "("
+  )
+    return true;
+  if (t0.value === "exclude") return true;
+  if (t0.value === "like" && item[1]?.kind === "ident") return true;
+  return false;
+};
+
+type ApplyTableConstraintCtx = {
+  columns: Array<{ key: string; shape: shapes.Shape }>;
+  colIndex: Map<string, number>;
+  pgTypeByName: Map<string, string>;
+  setTableCheck: (chk: string) => void;
+  pushUniqueConstraint: (entry: { columns: string[]; name?: string }) => void;
+};
+
+const applyTableConstraint = (
+  item: Token[],
+  ctx: ApplyTableConstraintCtx,
+): void => {
+  const c = new TokenCursor(item);
+  let constraintName: string | undefined;
+  if (c.consumeIdent("constraint")) {
+    if (c.peek().kind === "ident") {
+      constraintName = c.consume().value;
+    }
+  }
+  if (c.consumeIdent("primary")) {
+    c.consumeIdent("key");
+    c.expectPunct("(");
+    const cols = readColList(c);
+    for (const col of cols) {
+      const idx = ctx.colIndex.get(col);
+      if (idx === undefined) continue;
+      const entry = ctx.columns[idx]!;
+      entry.shape = annotate.primary(entry.shape);
+      // primary implies not-null; remove optional
+      entry.shape = { ...entry.shape, anno: stripOptional(entry.shape.anno) };
+    }
+    return;
+  }
+  if (c.consumeIdent("unique")) {
+    c.expectPunct("(");
+    const cols = readColList(c);
+    if (cols.length === 1) {
+      const col = cols[0]!;
+      const idx = ctx.colIndex.get(col);
+      if (idx !== undefined) {
+        const entry = ctx.columns[idx]!;
+        entry.shape = annotate.unique(entry.shape);
+      }
+      return;
+    }
+    const entry: { columns: string[]; name?: string } = { columns: cols };
+    if (constraintName !== undefined) entry.name = constraintName;
+    ctx.pushUniqueConstraint(entry);
+    return;
+  }
+  if (c.consumeIdent("foreign")) {
+    c.expectIdent("key");
+    c.expectPunct("(");
+    const localCols = readColList(c);
+    c.expectIdent("references");
+    const parts = c.readDottedName();
+    const qn = qualifiedName(parts);
+    let refCols: string[] = [];
+    if (c.consumePunct("(")) {
+      refCols = readColList(c);
+    }
+    if (refCols.length === 0) refCols = ["id"];
+    let onDelete: ReferentialAction | undefined;
+    let onUpdate: ReferentialAction | undefined;
+    while (c.consumeIdent("on")) {
+      if (c.consumeIdent("delete")) {
+        const a = parseReferentialAction(c);
+        if (a !== null) onDelete = a;
+      } else if (c.consumeIdent("update")) {
+        const a = parseReferentialAction(c);
+        if (a !== null) onUpdate = a;
+      } else break;
+    }
+    if (c.consumeIdent("match")) {
+      if (c.peek().kind === "ident") c.consume();
+    }
+    for (let i = 0; i < localCols.length; i += 1) {
+      const local = localCols[i]!;
+      const ref = refCols[i] ?? refCols[refCols.length - 1]!;
+      const idx = ctx.colIndex.get(local);
+      if (idx === undefined) continue;
+      const entry = ctx.columns[idx]!;
+      const foreign: {
+        table: string;
+        column: string;
+        onDelete?: ReferentialAction;
+        onUpdate?: ReferentialAction;
+      } = {
+        table: qn.name,
+        column: ref,
+      };
+      if (onDelete !== undefined) foreign.onDelete = onDelete;
+      if (onUpdate !== undefined) foreign.onUpdate = onUpdate;
+      entry.shape = annotate.as(entry.shape, { foreign });
+    }
+    return;
+  }
+  if (c.consumeIdent("check")) {
+    const inner = c.skipParens();
+    // Try to decode as a per-column constraint matching any column in this table
+    for (const col of ctx.columns) {
+      const base = col.shape;
+      const dec = decodeCheck(inner, {
+        columnName: col.key,
+        isInteger: base.type === "number",
+        isString: base.type === "string",
+        isArray: base.type === "array",
+      });
+      if (dec.fullyDecoded) {
+        const u = dec.updates;
+        if (u.min !== undefined)
+          col.shape = annotate.as(col.shape, { min: u.min });
+        if (u.max !== undefined)
+          col.shape = annotate.as(col.shape, { max: u.max });
+        if (u.pattern !== undefined)
+          col.shape = annotate.as(col.shape, { pattern: u.pattern });
+        if (u.uniqueItems === true)
+          col.shape = annotate.as(col.shape, { uniqueItems: true });
+        if (u.unionLiterals !== undefined && col.shape.type === "string") {
+          const preserved = col.shape.anno;
+          const literals = u.unionLiterals.map((v) => shapes.literal(v));
+          const u2 = shapes.union(literals);
+          col.shape = {
+            ...u2,
+            anno: { ...u2.anno, ...preserved },
+          } as shapes.Shape;
+        }
+        return;
+      }
+    }
+    ctx.setTableCheck(checkExprToSql(inner));
+    return;
+  }
+  // exclude, like — dropped
+};
+
+const stripOptional = (anno: shapes.Shape["anno"]): shapes.Shape["anno"] => {
+  const out = { ...anno };
+  delete out.optional;
+  return out;
+};
+
+const readColList = (c: TokenCursor): string[] => {
+  const out: string[] = [];
+  while (!c.isPunct(")")) {
+    const t = c.expectAnyIdent();
+    out.push(t.name);
+    // optional ordering / nulls clauses
+    if (c.consumeIdent("asc") || c.consumeIdent("desc")) {
+      /* */
+    }
+    if (c.consumeIdent("nulls")) {
+      if (c.peek().kind === "ident") c.consume();
+    }
+    if (!c.consumePunct(",")) break;
+  }
+  c.expectPunct(")");
+  return out;
+};