@everystack/cli 0.2.39 → 0.3.3

package/src/cli/schema-introspect.ts

@@ -0,0 +1,425 @@
+/**
+ * Whole-DB introspection — the data layer (the counterpart to authz-contract.ts).
+ *
+ * authz-contract reads RLS, policies, grants, and functions. This reads the rest
+ * of the database state drizzle-kit's pull would — columns and their pg-precise
+ * types, primary keys, uniques, checks, and foreign keys — into a structured
+ * SchemaSnapshot. That snapshot is what `db:generate` diffs the compiled Model
+ * against, and what `db:pull` reverses into `field()` declarations.
+ *
+ * Same contract as the authz introspection: the SQL runs through the ops Lambda
+ * (`db:query`); the mappers here are pure and unit-tested without a database.
+ * Types come from `format_type` (the canonical 'timestamp with time zone',
+ * 'numeric(12,2)', 'uuid' the Model compiler also emits), so the two sides diff.
+ */
+
+import { IGNORED_SCHEMAS, coerceBool, type QueryRunner } from './authz-contract.js';
+
+// ---------------------------------------------------------------------------
+// The data-layer snapshot — the structured shape both producers target.
+// ---------------------------------------------------------------------------
+
+export interface ColumnSchema {
+  /** SQL column name (snake_case). */
+  name: string;
+  /** `format_type` output — the pg-precise type, e.g. `timestamp with time zone`, `numeric(12,2)`. */
+  type: string;
+  notNull: boolean;
+  /** The DEFAULT expression (deparsed), or null. e.g. `now()`, `gen_random_uuid()`, `'draft'::text`. */
+  default: string | null;
+}
+
+export interface ForeignKey {
+  name: string;
+  columns: string[];
+  refTable: string;
+  refColumns: string[];
+  /** Lowercased referential actions, omitted when the Postgres default (`no action`). */
+  onDelete?: string;
+  onUpdate?: string;
+}
+
+export interface UniqueConstraint {
+  name: string;
+  columns: string[];
+}
+
+export interface CheckConstraint {
+  name: string;
+  /** The predicate text, as `pg_get_constraintdef` deparses it. */
+  expr: string;
+}
+
+/** A standalone index (NOT one backing a PK or UNIQUE constraint — those are excluded). */
+export interface IndexSchema {
+  name: string;
+  columns: string[];
+  unique: boolean;
+  /** Partial-index predicate (`WHERE …`), omitted when the index is total. */
+  where?: string;
+}
+
+export interface TableSchema {
+  /** Schema-qualified: `public.posts`. */
+  table: string;
+  /** Columns in ordinal position. */
+  columns: ColumnSchema[];
+  /** Primary-key column names (empty when the table has no PK). */
+  primaryKey: string[];
+  uniques: UniqueConstraint[];
+  checks: CheckConstraint[];
+  foreignKeys: ForeignKey[];
+  indexes: IndexSchema[];
+}
+
+/** A Postgres enum type — its name and its values in `enumsortorder` (the declared order). */
+export interface EnumType {
+  name: string;
+  values: string[];
+}
+
+export interface SchemaSnapshot {
+  tables: TableSchema[];
+  /** Enum types in the schema (`CREATE TYPE … AS ENUM`). Absent/empty when none. */
+  enums?: EnumType[];
+}
+
+// ---------------------------------------------------------------------------
+// Introspection SQL.
+// ---------------------------------------------------------------------------
+
+/**
+ * Every column of every base table, with its precise type (`format_type`),
+ * nullability, and default. Extension-owned tables are excluded via pg_depend,
+ * matching the authz queries.
+ */
+export const COLUMNS_SQL = `
+SELECT
+  n.nspname AS schema,
+  c.relname AS "table",
+  a.attname AS "column",
+  format_type(a.atttypid, a.atttypmod) AS type,
+  a.attnotnull AS not_null,
+  pg_get_expr(d.adbin, d.adrelid) AS "default",
+  a.attnum AS position
+FROM pg_attribute a
+JOIN pg_class c ON c.oid = a.attrelid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+WHERE c.relkind = 'r'
+  AND a.attnum > 0 AND NOT a.attisdropped
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend dep WHERE dep.objid = c.oid AND dep.deptype = 'e'
+  )
+ORDER BY n.nspname, c.relname, a.attnum;
+`.trim();
+
+/**
+ * Every table constraint — primary key, unique, check, foreign key — as its
+ * canonical `pg_get_constraintdef` text. The mapper parses that text (stable
+ * deparser output) into structured columns/refs, the same way pg_dump-class tools
+ * read it.
+ */
+export const CONSTRAINTS_SQL = `
+SELECT
+  n.nspname AS schema,
+  c.relname AS "table",
+  con.conname AS name,
+  con.contype AS type,
+  pg_get_constraintdef(con.oid) AS definition
+FROM pg_constraint con
+JOIN pg_class c ON c.oid = con.conrelid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE con.contype IN ('p', 'u', 'c', 'f')
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend dep WHERE dep.objid = c.oid AND dep.deptype = 'e'
+  )
+ORDER BY n.nspname, c.relname, con.conname;
+`.trim();
+
+/**
+ * Every enum type and its values, in `enumsortorder` (the order the values were declared,
+ * which `CREATE TYPE` must reproduce). Extension-owned types are excluded via pg_depend,
+ * matching the column/constraint queries.
+ */
+export const ENUMS_SQL = `
+SELECT
+  n.nspname AS schema,
+  t.typname AS name,
+  array_agg(e.enumlabel ORDER BY e.enumsortorder) AS values
+FROM pg_type t
+JOIN pg_enum e ON e.enumtypid = t.oid
+JOIN pg_namespace n ON n.oid = t.typnamespace
+WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend dep WHERE dep.objid = t.oid AND dep.deptype = 'e'
+  )
+GROUP BY n.nspname, t.typname
+ORDER BY n.nspname, t.typname;
+`.trim();
+
+/**
+ * Standalone indexes — `CREATE INDEX` the app declares, NOT the implicit indexes that back a
+ * primary key or unique constraint (those are excluded by the `conindid` check, since they're
+ * already represented as PK/unique). Columns come ordered by index position; a partial index
+ * carries its `WHERE` predicate. Expression indexes (no plain column list) fold to no columns
+ * and are skipped by the assembler.
+ */
+export const INDEXES_SQL = `
+SELECT
+  n.nspname AS schema,
+  t.relname AS "table",
+  i.relname AS name,
+  idx.indisunique AS is_unique,
+  (SELECT array_agg(a.attname ORDER BY k.ord)
+     FROM unnest(idx.indkey) WITH ORDINALITY k(attnum, ord)
+     JOIN pg_attribute a ON a.attrelid = idx.indrelid AND a.attnum = k.attnum) AS columns,
+  pg_get_expr(idx.indpred, idx.indrelid) AS predicate
+FROM pg_index idx
+JOIN pg_class i ON i.oid = idx.indexrelid
+JOIN pg_class t ON t.oid = idx.indrelid
+JOIN pg_namespace n ON n.oid = t.relnamespace
+WHERE t.relkind = 'r'
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (SELECT 1 FROM pg_constraint con WHERE con.conindid = idx.indexrelid)
+  AND NOT EXISTS (SELECT 1 FROM pg_depend dep WHERE dep.objid = t.oid AND dep.deptype = 'e')
+ORDER BY n.nspname, t.relname, i.relname;
+`.trim();
+
+// ---------------------------------------------------------------------------
+// Pure mappers.
+// ---------------------------------------------------------------------------
+
+export interface ColumnRow {
+  schema: string;
+  table: string;
+  column: string;
+  type: unknown;
+  not_null: unknown;
+  default: unknown;
+  position: unknown;
+}
+
+export function columnRowToDescriptor(row: ColumnRow): { table: string; column: ColumnSchema; position: number } {
+  const def = row.default == null ? null : String(row.default);
+  return {
+    table: `${row.schema}.${row.table}`,
+    position: Number(row.position),
+    column: {
+      name: row.column,
+      type: String(row.type),
+      notNull: coerceBool(row.not_null),
+      default: def && def.length > 0 ? def : null,
+    },
+  };
+}
+
+/** Column list inside `(...)`, unquoted and trimmed: `(a, "b")` -> `['a', 'b']`. */
+function parseColumnList(parenGroup: string): string[] {
+  const inner = parenGroup.replace(/^\(/, '').replace(/\)$/, '');
+  return inner.split(',').map((c) => c.trim().replace(/^"|"$/g, '')).filter(Boolean);
+}
+
+export type ConstraintKind = 'primaryKey' | 'unique' | 'check' | 'foreignKey';
+
+export interface ConstraintRow {
+  schema: string;
+  table: string;
+  name: string;
+  type: unknown;
+  definition: unknown;
+}
+
+export interface ConstraintDescriptor {
+  table: string;
+  name: string;
+  kind: ConstraintKind;
+  /** Local columns (PK / unique / FK). */
+  columns?: string[];
+  /** CHECK predicate text. */
+  expr?: string;
+  /** FK target. */
+  refTable?: string;
+  refColumns?: string[];
+  /** FK referential actions, lowercased; omitted when the Postgres default (`no action`). */
+  onDelete?: string;
+  onUpdate?: string;
+}
+
+/** Parse one `pg_get_constraintdef` row into a structured descriptor. */
+export function constraintRowToDescriptor(row: ConstraintRow): ConstraintDescriptor {
+  const table = `${row.schema}.${row.table}`;
+  const def = String(row.definition);
+  const type = String(row.type);
+
+  if (type === 'p' || type === 'u') {
+    const cols = def.match(/\(([^)]*)\)/);
+    return {
+      table, name: row.name,
+      kind: type === 'p' ? 'primaryKey' : 'unique',
+      columns: cols ? parseColumnList(cols[0]) : [],
+    };
+  }
+  if (type === 'f') {
+    // The ref table may be schema-qualified and/or double-quoted with embedded spaces
+    // ("My Schema"."Weird Table"), so match a quoted-or-bare token, not "up to whitespace".
+    const m = def.match(/FOREIGN KEY\s*(\([^)]*\))\s*REFERENCES\s+((?:"[^"]*"|[^\s("]+)(?:\.(?:"[^"]*"|[^\s("]+))?)\s*(\([^)]*\))/i);
+    const action = (clause: 'DELETE' | 'UPDATE'): string | undefined => {
+      const a = def.match(new RegExp(`ON ${clause}\\s+(CASCADE|RESTRICT|NO ACTION|SET NULL|SET DEFAULT)`, 'i'));
+      // `NO ACTION` is the default — Postgres omits it from constraintdef, so we omit it too.
+      return a && a[1].toUpperCase() !== 'NO ACTION' ? a[1].toLowerCase() : undefined;
+    };
+    return {
+      table, name: row.name, kind: 'foreignKey',
+      columns: m ? parseColumnList(m[1]) : [],
+      refTable: m ? m[2].replace(/"/g, '') : '',
+      refColumns: m ? parseColumnList(m[3]) : [],
+      onDelete: action('DELETE'),
+      onUpdate: action('UPDATE'),
+    };
+  }
+  // check — keep the predicate text inside the outer CHECK ( ... )
+  const m = def.match(/^CHECK\s*\((.*)\)$/s);
+  return { table, name: row.name, kind: 'check', expr: m ? m[1].trim() : def };
+}
+
+// ---------------------------------------------------------------------------
+// Assembly.
+// ---------------------------------------------------------------------------
+
+export interface IndexRow {
+  schema: string;
+  table: string;
+  name: string;
+  is_unique: unknown;
+  columns: unknown;
+  predicate: unknown;
+}
+
+export function indexRowToDescriptor(row: IndexRow): { table: string; index: IndexSchema } {
+  const columns = Array.isArray(row.columns) ? row.columns.map(String) : [];
+  const pred = row.predicate == null ? '' : String(row.predicate);
+  return {
+    table: `${row.schema}.${row.table}`,
+    index: { name: row.name, columns, unique: coerceBool(row.is_unique), ...(pred ? { where: pred } : {}) },
+  };
+}
+
+export interface EnumRow {
+  schema: string;
+  name: string;
+  values: unknown;
+}
+
+export function enumRowToDescriptor(row: EnumRow): EnumType {
+  const values = Array.isArray(row.values) ? row.values.map(String) : [];
+  return { name: row.name, values };
+}
+
+export interface SchemaRows {
+  columns: ColumnRow[];
+  constraints: ConstraintRow[];
+  enums?: EnumRow[];
+  indexes?: IndexRow[];
+}
+
+/**
+ * Fold introspected rows into the snapshot. Deterministic: tables sorted by name,
+ * columns by ordinal position, and each constraint list sorted by name — so a
+ * re-pull of an unchanged database is byte-stable.
+ */
+export function assembleSchema(rows: SchemaRows): SchemaSnapshot {
+  const tables = new Map<string, TableSchema>();
+  const positions = new Map<string, Map<string, number>>();
+
+  const ensure = (table: string): TableSchema => {
+    let t = tables.get(table);
+    if (!t) {
+      t = { table, columns: [], primaryKey: [], uniques: [], checks: [], foreignKeys: [], indexes: [] };
+      tables.set(table, t);
+      positions.set(table, new Map());
+    }
+    return t;
+  };
+
+  for (const row of rows.columns) {
+    if (IGNORED_SCHEMAS.has(row.schema)) continue;
+    const { table, column, position } = columnRowToDescriptor(row);
+    const t = ensure(table);
+    t.columns.push(column);
+    positions.get(table)!.set(column.name, position);
+  }
+
+  for (const t of tables.values()) {
+    const pos = positions.get(t.table)!;
+    t.columns.sort((a, b) => (pos.get(a.name) ?? 0) - (pos.get(b.name) ?? 0));
+  }
+
+  for (const row of rows.constraints) {
+    if (IGNORED_SCHEMAS.has(row.schema)) continue;
+    const d = constraintRowToDescriptor(row);
+    const t = tables.get(d.table);
+    if (!t) continue; // a constraint on a table we didn't enumerate (e.g. a view)
+    switch (d.kind) {
+      case 'primaryKey': t.primaryKey = d.columns ?? []; break;
+      case 'unique': t.uniques.push({ name: d.name, columns: d.columns ?? [] }); break;
+      case 'check': t.checks.push({ name: d.name, expr: d.expr ?? '' }); break;
+      case 'foreignKey':
+        t.foreignKeys.push({
+          name: d.name, columns: d.columns ?? [], refTable: d.refTable ?? '', refColumns: d.refColumns ?? [],
+          ...(d.onDelete ? { onDelete: d.onDelete } : {}),
+          ...(d.onUpdate ? { onUpdate: d.onUpdate } : {}),
+        });
+        break;
+    }
+  }
+
+  for (const row of rows.indexes ?? []) {
+    if (IGNORED_SCHEMAS.has(row.schema)) continue;
+    const { table, index } = indexRowToDescriptor(row);
+    const t = tables.get(table);
+    if (!t || index.columns.length === 0) continue; // unknown table, or an expression index (no plain columns)
+    t.indexes.push(index);
+  }
+
+  for (const t of tables.values()) {
+    t.uniques.sort((a, b) => a.name.localeCompare(b.name));
+    t.checks.sort((a, b) => a.name.localeCompare(b.name));
+    t.foreignKeys.sort((a, b) => a.name.localeCompare(b.name));
+    t.indexes.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  const enums = (rows.enums ?? [])
+    .filter((r) => !IGNORED_SCHEMAS.has(r.schema))
+    .map(enumRowToDescriptor)
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    tables: [...tables.values()].sort((a, b) => a.table.localeCompare(b.table)),
+    enums,
+  };
+}
+
+/**
+ * Introspect the live database into a SchemaSnapshot — the data-layer analog of
+ * `introspectContract`. Runs the two read-only SQL constants through the injected runner
+ * (the ops Lambda `db:query` in production, a fake in tests) and folds the rows with
+ * `assembleSchema`. This is the `current` side `db:generate` diffs the compiled Models against.
+ */
+export async function introspectSchema(run: QueryRunner): Promise<SchemaSnapshot> {
+  const [columns, constraints, enums, indexes] = await Promise.all([
+    run(COLUMNS_SQL), run(CONSTRAINTS_SQL), run(ENUMS_SQL), run(INDEXES_SQL),
+  ]);
+  return assembleSchema({
+    columns: columns as ColumnRow[],
+    constraints: constraints as ConstraintRow[],
+    enums: enums as EnumRow[],
+    indexes: indexes as IndexRow[],
+  });
+}