@everystack/cli 0.4.99 → 0.4.102

package/src/cli/model-map.ts

@@ -0,0 +1,255 @@
+/**
+ * The model map: `db/model-map.generated.json`, the association map the admin reads with no
+ * database and no credentials (U3; T2). db:generate writes it beside the generated drizzle schema
+ * and db:check regenerates it in memory and compares byte for byte, exactly as it does the schema.
+ *
+ * A pure function of the linked model set. It carries PUBLIC METADATA only: per model its schema,
+ * table and primary key, the NOT NULL field keys, the relations it declares and the foreign keys it
+ * owns. No column types, no abilities, grants or policies, nothing from a database, no timestamp, path or git reference.
+ *
+ * The foreign keys are read from `modelForeignKeys(model, relationDeleteActions(models))`, the one
+ * source the generated SQL and the diff IR read, so the map's ON DELETE / ON UPDATE (the action a
+ * parent's hasMany `dependent` derives included) cannot disagree with the DDL.
+ *
+ * Privacy, fail closed: what the API handler hides never appears. A `private: true` model is left
+ * out, and so is every relation or foreign key that points at one. A relation or foreign key that
+ * names a `.private()` field anywhere (its column, its key, an orderBy or where field), by field key
+ * or SQL column name, is left out whole. `where` values and `limit` are published verbatim. Withholding is additive to undo later; publishing a hidden name cannot be taken back.
+ *
+ * `mapVersion` versions the format. `modelRevision` is the sha256 of the map's own content, so it
+ * changes if and only if the map does (an ability or a plain column edit does not move it).
+ */
+
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { linkModels, relationDeleteActions, type ModelDescriptor, type Relation } from '@everystack/model';
+import { modelForeignKeys, toSnakeCase } from './schema-compile';
+
+export const MODEL_MAP_VERSION = 1;
+export const MODEL_MAP_FILE = 'model-map.generated.json';
+
+export interface ModelMapRelation {
+  /** The key the relation is declared under. */
+  name: string;
+  kind: 'belongsTo' | 'hasMany' | 'hasOne';
+  /** The target model's map key (`schema.table`). */
+  target: string;
+  /** The foreign-key field: on this model for belongsTo, on the target for hasMany / hasOne. */
+  column: string;
+  /** The declared key on the other side, or null for the default (the primary key). */
+  references: string | null;
+  dependent: 'restrict' | 'nullify' | 'cascade' | null;
+  /** Normalized: the target's primary key is the tie-breaker. Null for a hasMany with none. */
+  orderBy: Array<{ field: string; order: 'asc' | 'desc' }> | null;
+  limit: number | null;
+  where: Record<string, string | number | boolean | null> | null;
+}
+
+export interface ModelMapForeignKey {
+  /** The constraint name the DDL uses. */
+  name: string;
+  /** This model's field keys, and their SQL columns, in the same order. */
+  fields: string[];
+  columns: string[];
+  /** `external` is true for a table no model declares (`.references({ schema, table, column })`). */
+  target: { schema: string; table: string; columns: string[]; external: boolean };
+  onDelete: string;
+  onUpdate: string;
+}
+
+export interface ModelMapEntry {
+  schema: string;
+  table: string;
+  /** Field keys; null when a key field is `.private()`. */
+  primaryKey: string[] | null;
+  /**
+   * Field keys of the NOT NULL columns, in declaration order (a serial, an identity and a primary
+   * key column included: Postgres makes them NOT NULL). A `.private()` field is never named. The
+   * admin reads it to hide the clear control on a value the database cannot empty; it does NOT
+   * make the field required in a form, since a NOT NULL column with a default may be left blank.
+   */
+  notNull: string[];
+  /**
+   * The field key of the soft-delete column when the model declares `softDelete: true` (a DELETE
+   * marks the row, so no foreign-key rule fires); null when it hard-deletes, or when that field is
+   * `.private()` (a private name is never published).
+   */
+  softDelete: string | null;
+  /**
+   * Present (and true) only on a `lifecycle: true` model: the database soft-deletes it and a
+   * restore goes through `<t>_restore`, never an update. Omitted on every other model, so an
+   * absent key reads false and a map with no lifecycle model is unchanged.
+   */
+  lifecycle?: true;
+  relations: ModelMapRelation[];
+  foreignKeys: ModelMapForeignKey[];
+}
+
+export interface ModelMap {
+  mapVersion: typeof MODEL_MAP_VERSION;
+  modelRevision: string;
+  models: Record<string, ModelMapEntry>;
+}
+
+/** Where the map lives: beside the resolved drizzle schema (so it follows `--schema-out`). */
+export function modelMapPath(schemaOut: string): string {
+  return path.join(path.dirname(schemaOut), MODEL_MAP_FILE);
+}
+
+const keyOf = (m: { schema?: string; table: string }): string => `${m.schema ?? 'public'}.${m.table}`;
+
+/**
+ * True when `name` spells a `.private()` field of `model` by its field key OR its SQL column (a
+ * relation may name `author_id` for `authorId`). Compared on the snake_case form of both, so every
+ * spelling that reaches the same column matches. A name that matches no private field is not hidden.
+ */
+const hidden = (model: ModelDescriptor, name: string): boolean => {
+  const column = toSnakeCase(name);
+  return Object.entries(model.fields).some(([key, f]) => f.spec.isPrivate && (key === name || toSnakeCase(key) === column));
+};
+
+/** One foreign key as the declaration states it, in the order `modelForeignKeys` emits it. */
+interface DeclaredFk {
+  fields: string[];
+  target: { schema: string; table: string; external: boolean; model: ModelDescriptor | null };
+  /** Target field keys (model target) or PostgreSQL column names (external target). */
+  targetKeys: string[];
+}
+
+/**
+ * The declaration side of each FK, walked in the same order as `modelForeignKeys` (fields, then
+ * table-level foreignKey constraints). The caller checks it lines up with the DDL IR entry by entry,
+ * so the two walks can never silently drift.
+ */
+function declaredForeignKeys(model: ModelDescriptor): DeclaredFk[] {
+  const out: DeclaredFk[] = [];
+  for (const [name, f] of Object.entries(model.fields)) {
+    const external = f.spec.referencesExternal;
+    const ref = f.spec.references;
+    if (external) {
+      out.push({ fields: [name], target: { schema: external.schema, table: external.table, external: true, model: null }, targetKeys: [external.column] });
+    } else if (ref) {
+      const t = ref() as ModelDescriptor;
+      out.push({ fields: [name], target: { schema: t.schema ?? 'public', table: t.table, external: false, model: t }, targetKeys: [t.primaryKey[0] ?? 'id'] });
+    }
+  }
+  for (const c of model.constraints) {
+    if (c.kind !== 'foreignKey') continue;
+    if (c.external) {
+      out.push({ fields: [...c.columns], target: { schema: c.external.schema, table: c.external.table, external: true, model: null }, targetKeys: [...c.refColumns] });
+    } else {
+      const t = c.references!() as ModelDescriptor;
+      out.push({ fields: [...c.columns], target: { schema: t.schema ?? 'public', table: t.table, external: false, model: t }, targetKeys: [...c.refColumns] });
+    }
+  }
+  return out;
+}
+
+function mapRelation(model: ModelDescriptor, name: string, rel: Relation): ModelMapRelation | null {
+  const target = rel.target();
+  if (target.private) return null;
+  // Which side each carried name belongs to: belongsTo's column is ours and its key the target's;
+  // hasMany / hasOne the other way round. orderBy and where name target fields.
+  const [columnSide, referencesSide] = rel.kind === 'belongsTo' ? [model, target] : [target, model];
+  const names: Array<[ModelDescriptor, string]> = [
+    [columnSide, rel.column],
+    ...(rel.references !== undefined ? [[referencesSide, rel.references] as [ModelDescriptor, string]] : []),
+    ...(rel.orderBy ?? []).map((t) => [target, t.field] as [ModelDescriptor, string]),
+    ...Object.keys(rel.where ?? {}).map((k) => [target, k] as [ModelDescriptor, string]),
+  ];
+  if (names.some(([m, n]) => hidden(m, n))) return null;
+  return {
+    name,
+    kind: rel.kind,
+    target: keyOf(target),
+    column: rel.column,
+    references: rel.references ?? null,
+    dependent: rel.dependent ?? null,
+    orderBy: rel.orderBy ? rel.orderBy.map((t) => ({ field: t.field, order: t.order })) : null,
+    limit: rel.limit ?? null,
+    where: rel.where ? { ...rel.where } : null,
+  };
+}
+
+/** The soft-delete field, spelled as the model keys it (both spellings the model accepts). */
+function softDeleteField(model: ModelDescriptor): string | null {
+  if (!model.softDelete) return null;
+  const key = ['deletedAt', 'deleted_at'].find((k) => k in model.fields);
+  return key && !hidden(model, key) ? key : null;
+}
+
+/** The map for a model set. Links the set first (idempotent), so the orderBy is normalized. */
+export function compileModelMap(models: ModelDescriptor[]): ModelMap {
+  linkModels(models);
+  const dependents = relationDeleteActions(models);
+  const entries: Array<[string, ModelMapEntry]> = [];
+  const privateTables = new Set(models.filter((m) => m.private).map(keyOf));
+  // Table and schema names may hold a dot, so `schema.table` can collide ('x' + 'y.a' vs 'x.y' + 'a').
+  // A collision would silently drop a model from the map: fail loudly, naming both.
+  const owners = new Map<string, ModelDescriptor>();
+
+  for (const model of new Set(models)) {
+    if (model.private) continue;
+    const relations: ModelMapRelation[] = [];
+    for (const [name, rel] of Object.entries(model.relations) as Array<[string, Relation]>) {
+      const mapped = mapRelation(model, name, rel);
+      if (mapped) relations.push(mapped);
+    }
+
+    // The DDL IR (the SQL's own source) and the declaration, walked in lockstep.
+    const ir = modelForeignKeys(model, dependents);
+    const declared = declaredForeignKeys(model);
+    if (ir.length !== declared.length) {
+      throw new Error(`model map: ${keyOf(model)} has ${ir.length} foreign key(s) in the DDL but ${declared.length} declared`);
+    }
+    const foreignKeys: ModelMapForeignKey[] = [];
+    ir.forEach((fk, i) => {
+      const d = declared[i];
+      const expectedRef = d.target.schema !== 'public' ? `${d.target.schema}.${d.target.table}` : d.target.table;
+      if (fk.refTable !== expectedRef || fk.columns.join() !== d.fields.map(toSnakeCase).join()) {
+        throw new Error(`model map: ${keyOf(model)} foreign key ${fk.name} does not line up with its declaration`);
+      }
+      if (d.fields.some((f) => hidden(model, f))) return;
+      if (d.target.model && (d.target.model.private || d.targetKeys.some((k) => hidden(d.target.model!, k)))) return;
+      // An external target naming a private model's table: linkModels already refuses an external
+      // target any model declares ('use the model'); withheld here too, so this function alone holds.
+      if (d.target.external && privateTables.has(keyOf(d.target))) return;
+      foreignKeys.push({
+        name: fk.name,
+        fields: d.fields,
+        columns: [...fk.columns],
+        target: { schema: d.target.schema, table: d.target.table, columns: [...fk.refColumns], external: d.target.external },
+        onDelete: fk.onDelete ?? 'no action',
+        onUpdate: fk.onUpdate ?? 'no action',
+      });
+    });
+
+    const key = keyOf(model);
+    const clash = owners.get(key);
+    if (clash) {
+      const who = (m: ModelDescriptor): string => `schema '${m.schema ?? 'public'}', table '${m.table}'`;
+      throw new Error(`model map: two models share the key ${key} (${who(clash)} and ${who(model)}); rename one`);
+    }
+    owners.set(key, model);
+    entries.push([key, {
+      schema: model.schema ?? 'public',
+      table: model.table,
+      primaryKey: model.primaryKey.some((k) => hidden(model, k)) ? null : [...model.primaryKey],
+      notNull: Object.entries(model.fields).filter(([key, f]) => f.spec.isNotNull && !hidden(model, key)).map(([key]) => key),
+      softDelete: softDeleteField(model),
+      ...(model.lifecycle === true ? { lifecycle: true as const } : {}),
+      relations,
+      foreignKeys,
+    }]);
+  }
+
+  entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const body = { mapVersion: MODEL_MAP_VERSION, models: Object.fromEntries(entries) };
+  const modelRevision = createHash('sha256').update(JSON.stringify(body)).digest('hex');
+  return { mapVersion: MODEL_MAP_VERSION, modelRevision, models: body.models };
+}
+
+/** The committed file's exact text: two-space JSON and a trailing newline. */
+export function renderModelMap(models: ModelDescriptor[]): string {
+  return JSON.stringify(compileModelMap(models), null, 2) + '\n';
+}