@metaobjectsdev/codegen-ts 0.15.21-rc.1 → 0.16.0-rc.1

package/src/projection/build-projection-views.ts

@@ -9,20 +9,43 @@
 // drift / snapshot as the `views` input. This is the ONE place view SQL is produced.
 
 import {
+  type AggregateFunction,
   type MetaData,
+  MetaObject,
   MetaRoot,
   MetaSource,
   SOURCE_KIND_VIEW,
+  TYPE_FIELD,
+  TYPE_IDENTITY,
+  TYPE_ORIGIN,
   resolveTableName,
   resolveTableSchema,
 } from "@metaobjectsdev/metadata";
 import { isProjection } from "./projection-detector.js";
 import { extractViewSpec } from "./extract-view-spec.js";
 import { emitViewDdl } from "./view-ddl-emit.js";
-import type { JoinNode, JoinTree } from "./view-spec.js";
+import type { JoinNode, JoinTree, ViewSpec } from "./view-spec.js";
 import type { ColumnNamingStrategy } from "../metaobjects-config.js";
 
 /** Structurally matches migrate-ts's `ViewDescriptor` (name + body sql + optional schema). */
+/**
+ * One output column of the view, in SELECT order, described PHYSICALLY (table +
+ * column, not entity + field).
+ *
+ * migrate-ts resolves each of these to a `SqlType` against its own expected table
+ * descriptors. Deliberately no SqlType here: codegen-ts stays ignorant of migrate
+ * concerns, and migrate-ts stays ignorant of metadata traversal — the existing
+ * layering (migrate-ts never imports codegen-ts; the CLI threads views in).
+ *
+ * Postgres allows a non-destructive `CREATE OR REPLACE VIEW` only when the existing
+ * output columns are a PREFIX of the new ones (same names, same types, same order).
+ * That decision cannot be made without knowing the column list, which is why it is
+ * carried here.
+ */
+export type ExpectedViewColumn =
+  | { kind: "passthrough"; name: string; sourceTable: string; sourceColumn: string }
+  | { kind: "aggregate"; name: string; sourceTable: string; sourceColumn: string; agg: AggregateFunction };
+
 export interface ExpectedView {
   name: string;
   schema?: string;
@@ -34,6 +57,15 @@ export interface ExpectedView {
    * so the view must be dropped before and recreated after.
    */
   dependsOn: string[];
+  /**
+   * The view's output columns, in SELECT order — i.e. DECLARATION order, since
+   * extractViewSpec walks the projection's children in order. That is exactly the
+   * order Postgres's OR-REPLACE prefix rule wants: a field appended to the
+   * projection lands last, so the change stays non-destructive. (Re-canonicalizing
+   * to, say, alphabetical order would be strictly WORSE — it would scatter an
+   * appended field into the middle and force a destructive drop+create.)
+   */
+  columns: ExpectedViewColumn[];
 }
 
 export interface BuildProjectionViewsOptions {
@@ -71,27 +103,120 @@ export function buildProjectionViews(
     //     through here silently created a PLAIN view under the matview's name.
     //     Matviews are hand-managed, like the documented custom-SQL-view
     //     exception: migrate neither creates nor drops them.
+    //   - a STANDALONE read-model — a plain view projection declaring its own
+    //     columns, with no origin.* children — is hand-authored SQL too. Codegen
+    //     already treats it that way on purpose (see projection-decl.ts: "lets a
+    //     standalone read-only view-entity — explicit columns, no `extends` —
+    //     generate its read model … standalone views hand-author their SQL").
+    //     The SCHEMA path never got that memo: extractViewSpec THREW on it
+    //     ("cannot derive the base entity"), and because the CLI calls this
+    //     function unconditionally, ONE such projection aborted `meta migrate`
+    //     for the ENTIRE model — every other entity included. Same crash class as
+    //     the proc projections above. Skip it instead.
     // ADR-0039: own — mirrors isProjection/viewName's own-source classification.
     const readOnlySource = projection.ownChildren().find(
       (c): c is MetaSource => c instanceof MetaSource && c.isReadOnly(),
     );
     if (readOnlySource?.effectiveKind !== SOURCE_KIND_VIEW) continue;
+    if (!viewIsDerived(projection)) continue;
     const spec = extractViewSpec(projection, root, { columnNamingStrategy });
     const baseTableName = joinTables[spec.joinTree.baseEntity];
     if (!baseTableName) continue; // unresolved base — skip (loader/codegen surface the error elsewhere)
     const body = emitViewDdl(spec, { dialect, baseTableName, joinTables, bodyOnly: true });
     const schema = resolveTableSchema(projection);
     const dependsOn = collectDependsOn(spec.joinTree, baseTableName, joinTables);
+    const columns = collectViewColumns(spec, baseTableName, joinTables);
     out.push({
       name: spec.viewName,
       sql: body,
       dependsOn,
+      columns,
       ...(schema !== undefined ? { schema } : {}),
     });
   }
   return out;
 }
 
+/**
+ * The SELECT list as PHYSICAL (table, column) pairs, in emitted order.
+ *
+ * SelectColumn carries a join ALIAS, which means nothing outside this module — so
+ * resolve every alias to its physical table first.
+ */
+function collectViewColumns(
+  spec: ViewSpec,
+  baseTableName: string,
+  joinTables: Readonly<Record<string, string>>,
+): ExpectedViewColumn[] {
+  const aliasToTable = new Map<string, string>([[spec.joinTree.baseAlias, baseTableName]]);
+  const walk = (node: JoinNode): void => {
+    const t = joinTables[node.targetEntity];
+    if (t) aliasToTable.set(node.alias, t);
+    for (const child of node.children) walk(child);
+  };
+  for (const j of spec.joinTree.joins) walk(j);
+
+  const out: ExpectedViewColumn[] = [];
+  for (const c of spec.selectSpec.columns) {
+    const sourceTable = aliasToTable.get(c.sourceAlias);
+    // An unresolvable alias would make the column list a lie, and a wrong list would
+    // make the diff propose an ILLEGAL `CREATE OR REPLACE VIEW` that fails at apply.
+    // Drop the whole list instead: migrate-ts treats an absent list as "unknown" and
+    // fails safe to a gated drop+create.
+    if (sourceTable === undefined) return [];
+    out.push(
+      c.kind === "aggregate"
+        ? { kind: "aggregate", name: c.dbColAlias, sourceTable, sourceColumn: c.sourceColumn, agg: c.agg }
+        : { kind: "passthrough", name: c.dbColAlias, sourceTable, sourceColumn: c.sourceColumn },
+    );
+  }
+  return out;
+}
+
+/**
+ * Is this projection's view DERIVED from the model — i.e. does migrate own its DDL?
+ *
+ * A derived view is synthesized from a BASE entity, and the base is anchored by an
+ * `extends` binding on the projection's own identity or one of its own fields (that is
+ * exactly what `baseEntityFor` resolves). So:
+ *
+ *   - ANCHORED (any own identity/field carries `extends`) → derived. Migrate generates
+ *     and owns the view. If the anchor is ambiguous, extractViewSpec throws — correctly,
+ *     that is a real authoring error.
+ *
+ *   - NOT anchored, but carries `origin.*` children → the author clearly MEANT a derived
+ *     view (an origin says "this column comes from that entity's column") but gave it
+ *     nothing to derive FROM. That is a malformed projection: fall through to
+ *     extractViewSpec so it throws its actionable message ("declare an extends-bound
+ *     identity to anchor the base"). Do NOT silently skip it.
+ *
+ *   - NOT anchored and NO origins → a STANDALONE read-model: it declares its own columns
+ *     and says nothing about where they come from, so there is nothing to synthesize a
+ *     body from. Its SQL is hand-authored. Codegen already treats this shape as
+ *     legitimate and intended (projection-decl.ts generates its read model and notes
+ *     "standalone views hand-author … their SQL") — the schema path simply never agreed,
+ *     and threw, which aborted `meta migrate` for the WHOLE model.
+ *
+ * Trade-off, stated plainly: a hand-authored view is UNMANAGED, so `meta verify --db`
+ * cannot drift-check it. That is the same bounded exception the docs already carve out
+ * for custom SQL views and matviews — not a new hole. What changes is only that ONE
+ * such view no longer blocks migration of every other entity in the tree.
+ *
+ * ADR-0039: own — a projection's derivation is declared locally; an inherited extends or
+ * origin belongs to the parent's own view.
+ */
+function viewIsDerived(projection: MetaObject): boolean {
+  const own = projection.ownChildren();
+  const anchored = own.some(
+    (c) => (c.type === TYPE_IDENTITY || c.type === TYPE_FIELD) && c.superRef !== undefined,
+  );
+  if (anchored) return true;
+  // Origins without an anchor = malformed, not standalone. Let extractViewSpec say so.
+  return own.some(
+    (f) => f.type === TYPE_FIELD && f.ownChildren().some((c) => c.type === TYPE_ORIGIN),
+  );
+}
+
 /** The base table plus every joined table, deduped — the physical tables the view reads. */
 function collectDependsOn(
   joinTree: JoinTree,

package/src/reference/queries.ts

@@ -70,7 +70,7 @@ function renderQueries(obj: MetaObject, ctx: RenderContext): string {
 ${dbTypeImport}
 ${dbTypeAlias}
 
-import { ${varName}, type ${entityName}, ${entityName}InsertSchema } from ${JSON.stringify(entityFileName)};
+import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}InsertSchema, ${entityName}UpdateSchema } from ${JSON.stringify(entityFileName)};
 `;
 
   const sections: Code[] = [

package/src/templates/queries-file.ts

@@ -80,7 +80,7 @@ export function renderQueriesFile(obj: MetaObject, ctx: RenderContext): string {
 ${dbTypeImport}
 ${dbTypeAlias}
 
-import { ${varName}, type ${entityName}, ${entityName}InsertSchema } from ${JSON.stringify(entityFileName)};
+import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}InsertSchema, ${entityName}UpdateSchema } from ${JSON.stringify(entityFileName)};
 `;
 
   const sections: Code[] = [

package/src/templates/queries.ts

@@ -91,12 +91,23 @@ export function renderUpdateFn(entity: MetaObject, ctx: RenderContext): Code {
   const singularVar = entityName.charAt(0).toLowerCase() + entityName.slice(1);
   const { fieldName: pkField, tsType: pkType } = getPkInfo(entity, ctx);
   const fnName = updateFnName(entityName);
-  const schemaName = `${entityName}InsertSchema`;
+  const findByIdFn = findByIdFnName(entityName);
+  // PATCH contract (FR-035): validate the caller's assignments against the
+  // UPDATE schema (all-optional, PK/@readOnly excluded, no insert-time transforms
+  // like @autoSet-onCreate → now() or the InsertSchema's discriminator handling)
+  // — NOT `InsertSchema.partial()`. The typed `<Entity>Patch` param makes a
+  // renamed/dropped field a compile error at every call site (PATCH-1..4);
+  // `.set()` writes ONLY the assigned columns, so an omitted field is untouched.
+  const updateSchemaName = `${entityName}UpdateSchema`;
+  const patchType = `${entityName}Patch`;
   const eqSym = imp("eq@drizzle-orm");
 
   return code`
-export async function ${fnName}(db: Db, ${pkField}: ${pkType}, data: unknown): Promise<${entityName} | null> {
-  const validated = ${schemaName}.partial().parse(data);
+export async function ${fnName}(db: Db, ${pkField}: ${pkType}, patch: ${patchType}): Promise<${entityName} | null> {
+  const validated = ${updateSchemaName}.parse(patch);
+  // PATCH-5: an empty patch is a no-op — return the current row rather than let
+  // Drizzle throw on an empty SET clause.
+  if (Object.keys(validated).length === 0) return ${findByIdFn}(db, ${pkField});
   const [${singularVar}] = await db.update(${varName}).set(validated).where(${eqSym}(${varName}.${pkField}, ${pkField})).returning();
   return ${singularVar} ?? null;
 }

package/src/templates/routes-file.ts

@@ -352,6 +352,14 @@ function renderTphRoutesFile(base: MetaObject, ctx: RenderContext): string {
       ctx.selfTarget, ctx.entityModuleTarget, sub.package, sub.name, ctx.extStyle,
     );
     const subInsertSym = imp(`${sub.name}InsertSchema@${subFileSpec}`);
+    // FR-036 Program B: the per-subtype UPDATE must carry the FR-035 present-key
+    // tristate (a non-@required subtype column accepts an explicit null → clears;
+    // a @required column's explicit null is rejected). The subtype's own
+    // UpdateSchema encodes exactly that (.optional() + .nullable() for non-required),
+    // whereas insertSchema.partial() only makes fields optional, not nullable — so a
+    // PATCH {col: null} on a nullable subtype column wrongly 400'd. The base
+    // polymorphic mount already uses the base UpdateSchema; this aligns the subtypes.
+    const subUpdateSym = imp(`${sub.name}UpdateSchema@${subFileSpec}`);
     // FR-017 Tier 3: each subtype carries its OWN filter/sort allowlist
     // (discriminator excluded — it's pinned by this path).
     const subFilterSym = imp(`${sub.name}FilterAllowlist@${subFileSpec}`);
@@ -363,7 +371,7 @@ function renderTphRoutesFile(base: MetaObject, ctx: RenderContext): string {
       db: ${dbSym},
       table: ${tableSym},
       insertSchema: ${subInsertSym}.omit({ ${discField}: true }),
-      updateSchema: ${subInsertSym}.omit({ ${discField}: true }).partial(),
+      updateSchema: ${subUpdateSym},
       filterAllowlist: ${subFilterSym},
       sortAllowlist: ${subSortSym},
       dialect: ${dialectLit},

package/src/templates/value-object-file.ts

@@ -14,6 +14,7 @@ import type { RenderContext } from "../render-context.js";
 import { renderValueObjectInterface, renderEnumTypeAliases } from "./inferred-types.js";
 import {
   renderInsertSchemaOnly,
+  renderZodValidators,
   isTphSubtype,
   renderTphSubtypeReadSchema,
   tphDiscriminatorPin,
@@ -49,7 +50,13 @@ export function renderValueObjectFile(obj: MetaObject, apiPrefix = "", ctx?: Ren
     renderValueObjectInterface(obj, ctx),
     ...(enumAliases !== null ? [enumAliases] : []),
     ...(tphReadSchema !== null ? [tphReadSchema] : []),
-    renderInsertSchemaOnly(obj, ctx),
+    // FR-036 Program B: a TPH subtype needs BOTH schemas — its per-subtype PATCH
+    // route must carry the FR-035 present-key tristate (a non-@required subtype
+    // column accepts an explicit null → clears), which lives in the UpdateSchema
+    // (.nullable() for non-required). renderZodValidators emits <Sub>InsertSchema +
+    // <Sub>UpdateSchema (the update omits the pinned discriminator). A pure value
+    // object stays insert-only (no PATCH semantics — an UpdateSchema would mislead).
+    tphSubtype ? renderZodValidators(obj, ctx) : renderInsertSchemaOnly(obj, ctx),
     ...(tphConstants !== null ? [tphConstants] : []),
     ...(tphFilterAllowlist !== null ? [tphFilterAllowlist] : []),
     ...(tphSortAllowlist !== null ? [tphSortAllowlist] : []),

package/src/templates/zod-validators.ts

@@ -36,6 +36,9 @@ import { sharedEnumImportSpecifier } from "../enum-import.js";
 import { sharedEnumZodConstName } from "./enums-file.js";
 import type { RenderContext } from "../render-context.js";
 import { valueObjectModuleSpecifier } from "../import-path.js";
+// FR-035: the SAME required-predicate that drives the Drizzle column's .notNull()
+// drives the UpdateSchema's .nullable() exclusion — shared so they cannot drift.
+import { isRequired } from "../column-mapper.js";
 
 /**
  * FR-017 Tier 1 — when this object is a TPH subtype (@discriminatorValue set
@@ -109,19 +112,34 @@ ${joinCode(fieldLines, { on: ",\n" })}
 `;
 }
 
+/** Field names participating in the object's PRIMARY identity, normalized to a
+ *  list. Empty when the object has no primary identity. */
+function primaryIdentityFieldNames(obj: MetaObject): string[] {
+  const primary = obj.primaryIdentity();
+  if (!primary) return [];
+  const fields = primary.attr(IDENTITY_ATTR_FIELDS);
+  if (Array.isArray(fields)) return fields.map(String);
+  if (typeof fields === "string") return [fields];
+  return [];
+}
+
 /** Auto-generated PK field names that should be omitted from InsertSchema. */
 function autoGenPkFieldNames(obj: MetaObject): Set<string> {
-  const out = new Set<string>();
-  const primary = obj.primaryIdentity();
-  if (primary) {
-    const generation = primary.attr(IDENTITY_ATTR_GENERATION);
-    if (generation === GENERATION_INCREMENT || generation === GENERATION_UUID) {
-      const fields = primary.attr(IDENTITY_ATTR_FIELDS);
-      const fieldsList = Array.isArray(fields) ? fields : (typeof fields === "string" ? [fields] : []);
-      for (const f of fieldsList) out.add(String(f));
-    }
-  }
-  return out;
+  const generation = obj.primaryIdentity()?.attr(IDENTITY_ATTR_GENERATION);
+  if (generation !== GENERATION_INCREMENT && generation !== GENERATION_UUID) return new Set();
+  return new Set(primaryIdentityFieldNames(obj));
+}
+
+/** ALL field names participating in the object's PRIMARY identity, regardless of
+ *  @generation. A PK column is never NULL (single-col via Drizzle `.primaryKey()`,
+ *  composite via `.notNull()`), so FR-035 PATCH-2 must NOT make a PK field
+ *  `.nullable()` in the UpdateSchema even when it carries no @required — otherwise
+ *  an explicit null typechecks into Drizzle's `.set()` (which rejects null on a
+ *  not-null column) and would violate NOT NULL at runtime. Unlike
+ *  autoGenPkFieldNames (which only lists increment/uuid PKs, already excluded from
+ *  the schema), this covers assigned + extended-identity projection PKs too. */
+function primaryKeyFieldNames(obj: MetaObject): Set<string> {
+  return new Set(primaryIdentityFieldNames(obj));
 }
 
 /**
@@ -259,6 +277,7 @@ export function updateSchemaFields(obj: MetaObject): SchemaFieldShape[] {
 export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code {
   const z = imp("z@zod");
   const autoGenPkFields = autoGenPkFieldNames(obj);
+  const pkFields = primaryKeyFieldNames(obj);
   const tphPin = tphDiscriminatorPin(obj);
 
   const insertFieldLines: Code[] = [];
@@ -305,9 +324,16 @@ export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code
       // zodFieldExpr already appends .optional() when the field is non-required
       // OR has a default; only append once more when it didn't.
       const baseExpr = zodFieldExpr(child, obj, ctx);
-      updateFieldLines.push(
-        fieldWillBeOptional(child) ? code`  ${child.name}: ${baseExpr}` : code`  ${child.name}: ${baseExpr}.optional()`,
-      );
+      let expr = fieldWillBeOptional(child) ? baseExpr : code`${baseExpr}.optional()`;
+      // FR-035 PATCH-2: a NON-@required field additionally accepts an explicit
+      // null — a present null CLEARS the column (`.set({field: null})` writes NULL).
+      // Keyed on required-ness, NOT fieldWillBeOptional: a required-with-@default
+      // field stays non-nullable so an explicit null on it is a 400 (validation),
+      // never a silent clear. PK fields are excluded: their Drizzle column is
+      // always not-null, so a nullable Zod type would fail `.set()`'s typecheck
+      // (and NOT NULL at runtime) — see primaryKeyFieldNames.
+      if (!isRequired(child) && !pkFields.has(child.name)) expr = code`${expr}.nullable()`;
+      updateFieldLines.push(code`  ${child.name}: ${expr}`);
     }
   }
 
@@ -325,6 +351,10 @@ ${joinCode(insertFieldLines, { on: ",\n" })}
 ${docsPrefix}export const ${updateSchemaName} = ${z}.object({
 ${joinCode(updateFieldLines, { on: ",\n" })}
 });
+
+/** Typed patch shape for ${obj.name}: every settable field, optional (FR-035 PATCH). A
+ * renamed/dropped field is a compile error at every \`update${obj.name}\` call site. */
+export type ${obj.name}Patch = ${z}.input<typeof ${updateSchemaName}>;
 `;
 }
 
@@ -488,12 +518,8 @@ function zodFieldExpr(field: MetaField, owner?: MetaObject, ctx?: RenderContext)
 /** Mirrors the optional-or-not decision inside appendValidatorChain so the update-schema
  *  caller can avoid stacking a second `.optional()` onto an already-optional expression. */
 function fieldWillBeOptional(field: MetaField): boolean {
-  let isRequired = field.attr(FIELD_ATTR_REQUIRED) === true;
-  for (const child of field.validators()) {
-    if (child.subType === VALIDATOR_SUBTYPE_REQUIRED) isRequired = true;
-  }
   const hasDefault = field.attr(FIELD_ATTR_DEFAULT) !== undefined;
-  return !isRequired || hasDefault;
+  return !isRequired(field) || hasDefault;
 }
 
 /** Numeric field subtypes whose Zod base is `z.number()` — value bounds apply. */
@@ -525,7 +551,10 @@ function appendValidatorChain(base: Code, field: MetaField): Code {
     if (child.subType === VALIDATOR_SUBTYPE_LENGTH) {
       const max = child.attr(VALIDATOR_ATTR_MAX);
       const min = child.attr(VALIDATOR_ATTR_MIN);
-      if (typeof max === "number") maxLen = max;
+      // FR-036 A3: @maxLength × validator.length @max = strictest-wins (min).
+      // maxLen already carries the field-level @maxLength; fold the validator's
+      // @max in as a lower bound so the effective cap is min(@maxLength, @max).
+      if (typeof max === "number") maxLen = maxLen === undefined ? max : Math.min(maxLen, max);
       if (typeof min === "number") minLen = min;
     }
     if (child.subType === VALIDATOR_SUBTYPE_REGEX) {
@@ -559,10 +588,19 @@ function appendValidatorChain(base: Code, field: MetaField): Code {
     if (arrMin !== undefined) chain = code`${chain}.min(${arrMin})`;
     if (arrMax !== undefined) chain = code`${chain}.max(${arrMax})`;
   } else if (field.subType === FIELD_SUBTYPE_STRING && !isJsonbBag) {
-    if (minLen !== undefined) chain = code`${chain}.min(${minLen})`;
-    else if (isRequired) chain = code`${chain}.min(1)`;
+    // FR-036 Pin 1: a @required string is non-empty. The floor is max(@min, 1) so an
+    // explicit `validator.length @min: 0` on a required field can't suppress it to
+    // `.min(0)` (which would accept ""). A non-required field keeps its authored @min.
+    const effectiveMin = Math.max(minLen ?? 0, isRequired ? 1 : 0);
+    if (effectiveMin > 0) chain = code`${chain}.min(${effectiveMin})`;
     if (maxLen !== undefined) chain = code`${chain}.max(${maxLen})`;
-    if (pattern !== undefined) chain = code`${chain}.regex(new RegExp(${JSON.stringify(pattern)}))`;
+    if (pattern !== undefined) {
+      // FR-036 Pin 2: validator.regex @pattern is FULL-MATCH — the whole value
+      // must match. JS RegExp.test searches, so anchor as ^(?:…)$ (always-wrap;
+      // a redundant anchor on an already-anchored pattern still matches identically).
+      const anchored = `^(?:${pattern})$`;
+      chain = code`${chain}.regex(new RegExp(${JSON.stringify(anchored)}))`;
+    }
   } else if (NUMERIC_FIELD_SUBTYPES.has(field.subType)) {
     if (numMin !== undefined) chain = code`${chain}.min(${numMin})`;
     if (numMax !== undefined) chain = code`${chain}.max(${numMax})`;