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

package/src/column-mapper.ts

@@ -37,6 +37,12 @@ import {
   DB_COLUMN_TYPE_UUID,
   DB_COLUMN_TYPE_JSONB,
   FIELD_ATTR_LOCAL_TIME,
+  TYPE_ORIGIN,
+  ORIGIN_SUBTYPE_AGGREGATE,
+  ORIGIN_AGGREGATE_ATTR_AGG,
+  AGG_ANY,
+  AGG_ALL,
+  AGG_COLLECT,
 } from "@metaobjectsdev/metadata";
 import { columnNameFromField } from "./naming.js";
 import { enumValues } from "./enum-meta.js";
@@ -307,6 +313,25 @@ export function isRequired(field: MetaField): boolean {
   return field.validators().some((child) => child.subType === VALIDATOR_SUBTYPE_REQUIRED);
 }
 
+/**
+ * #195 — a field whose value is derived by an origin.aggregate `@agg:any|all|collect`
+ * is COALESCE-guaranteed non-null in the synthesized view (any→false, all→true,
+ * collect→[]), so its read type is non-null even when the field is not `@required`.
+ * Drives `.notNull()` below so the Drizzle view column AND the Zod read schema agree
+ * (projection-decl derives its `.nullable()` from these modifiers). origin.first is
+ * deliberately NOT here — an empty related set selects no row (→ null); origin.computed
+ * nullability is expression-dependent, so it stays the conservative nullable default.
+ */
+export function originGuaranteedNonNull(field: MetaField): boolean {
+  // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
+  const origin = field
+    .ownChildren()
+    .find((c) => c.type === TYPE_ORIGIN && c.subType === ORIGIN_SUBTYPE_AGGREGATE);
+  if (origin === undefined) return false;
+  const agg = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_AGG);
+  return agg === AGG_ANY || agg === AGG_ALL || agg === AGG_COLLECT;
+}
+
 /** The bare (package-stripped) @objectRef name on a field.object, or undefined
  *  when unset. Used as the `.$type<VO>()` target + its sibling-module import.
  *  A fully-qualified ref (acme::ai::SourceLens) strips to the short name. */
@@ -527,7 +552,7 @@ export function mapColumnType(
   // Note: dollarTypeRef is read alongside (and rendered ahead of) `modifiers`
   // by `renderColumn` — see drizzle-schema.ts.
 
-  if (isRequired(field)) {
+  if (isRequired(field) || originGuaranteedNonNull(field)) {
     modifiers.push(".notNull()");
   }
 

package/src/naming.ts

@@ -111,6 +111,13 @@ export function createFnName(entityName: string): string {
   return `create${entityName}`;
 }
 
+/** Generated insert-preserving helper name: `insertPreserving<Entity>` (#203 —
+ *  the import/restore/replication escape hatch that writes @autoSet columns
+ *  verbatim). Emitted only for entities that declare @autoSet fields. */
+export function insertPreservingFnName(entityName: string): string {
+  return `insertPreserving${entityName}`;
+}
+
 /** Generated update helper name: `update<Entity>`. */
 export function updateFnName(entityName: string): string {
   return `update${entityName}`;

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

@@ -21,10 +21,10 @@ import {
   resolveTableName,
   resolveTableSchema,
 } from "@metaobjectsdev/metadata";
-import { isProjection } from "./projection-detector.js";
-import { extractViewSpec } from "./extract-view-spec.js";
+import { isProjection, isWriteThrough } from "./projection-detector.js";
+import { extractViewSpec, refNamedOwner } from "./extract-view-spec.js";
 import { emitViewDdl } from "./view-ddl-emit.js";
-import type { JoinNode, JoinTree, ViewSpec } from "./view-spec.js";
+import type { JoinNode, ViewSpec } from "./view-spec.js";
 import type { ColumnNamingStrategy } from "../metaobjects-config.js";
 
 /** Structurally matches migrate-ts's `ViewDescriptor` (name + body sql + optional schema). */
@@ -64,8 +64,12 @@ export interface ExpectedView {
    * 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.)
+   *
+   * OMITTED for an `@sql` (#208) view: the body is opaque — the tool never parses it,
+   * so its output columns are unknown. migrate-ts reads absent columns as "unknown"
+   * and fails safe to a gated drop+create instead of an illegal CREATE OR REPLACE.
    */
-  columns: ExpectedViewColumn[];
+  columns?: ExpectedViewColumn[];
 }
 
 export interface BuildProjectionViewsOptions {
@@ -89,54 +93,193 @@ export function buildProjectionViews(
 
   const out: ExpectedView[] = [];
   for (const projection of root.objects().filter(isProjection)) {
-    // Only PLAIN-VIEW projections produce managed CREATE VIEW DDL. The other
-    // read-only kinds must be skipped, not fed to extractViewSpec:
-    //   - storedProc / tableFunction (FR-015) are CALLABLES, not views. They are
-    //     base-less (no extends-bound identity), so extractViewSpec THROWS for
-    //     them — and the CLI calls this function unconditionally, so one proc
-    //     projection used to crash `meta migrate` outright.
-    //   - materializedView cannot be managed by the migrate pipeline today:
-    //     there is no CREATE MATERIALIZED VIEW emit, and PG introspection cannot
-    //     even see matviews (information_schema.views excludes them), so a
-    //     "managed" matview would re-propose create-view on every run and the
-    //     apply would collide with the existing object. Worse, feeding it
-    //     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;
+    // #208 §6 — classify DDL ownership BEFORE viewIsDerived (see classifyReadOnlySource),
+    // so an escape-valve view carrying extends-bound identity/fields (pure shape / row
+    // identity) is never mis-synthesized into a wrong base-table passthrough SELECT.
+    const cls = classifyReadOnlySource(projection);
+    if (cls.kind === "skip") continue;
+    if (cls.kind === "sql") {
+      emitSqlView(projection, cls.source, root, joinTables, out);
+      continue;
+    }
+    // A plain-view projection with no extends anchor and no origin.* is a STANDALONE
+    // read-model that hand-authors its own SQL — viewIsDerived returns false and we skip
+    // it (feeding it to extractViewSpec throws "cannot derive the base entity", and the
+    // CLI calls this unconditionally, so ONE such projection would abort `meta migrate`
+    // for the whole model). Codegen already treats this shape as intended in
+    // projection-decl.ts ("standalone views hand-author their SQL").
     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 } : {}),
-    });
+    emitViewFor(projection, root, joinTables, dialect, columnNamingStrategy, out);
+  }
+
+  // #213 hole 2 — a write-through ENTITY (FR-024 §7 read-view: a writable table
+  // source PLUS a non-primary read-only view source, with derived origin.* fields)
+  // hosts its OWN view. Emit it through the SAME canonical emitter — "one emitter,
+  // two hosts". `isWriteThrough` had zero call sites, so this replica view was never
+  // generated or owned by migrate. Unlike a projection there is no extends anchor
+  // and no viewIsDerived gate: the entity IS the base (extractViewSpec detects the
+  // write-through host), and it always has a derived view to emit. Only a plain
+  // `view` read source synthesizes CREATE VIEW DDL — a matview/proc/tableFunction
+  // read source is hand-managed, exactly as for projections above.
+  for (const entity of root.objects().filter(isWriteThrough)) {
+    // #208 §6 — same DDL-ownership classification as the projection loop. Unlike a
+    // projection there is no viewIsDerived gate: a write-through entity IS the base and
+    // always has a derived view to emit (extractViewSpec detects the write-through host).
+    const cls = classifyReadOnlySource(entity);
+    if (cls.kind === "skip") continue;
+    if (cls.kind === "sql") {
+      emitSqlView(entity, cls.source, root, joinTables, out);
+      continue;
+    }
+    emitViewFor(entity, root, joinTables, dialect, columnNamingStrategy, out);
   }
   return out;
 }
 
+/**
+ * #208 §6 — classify a host's read-only source by DDL OWNERSHIP, BEFORE any derivation
+ * decision. Shared by the projection and write-through loops so the ownership rules can
+ * never diverge between the two host kinds (the emit TAIL is already shared via emitViewFor).
+ *
+ *   - no read-only source, OR @unmanaged (external), OR a non-`view` read-only kind →
+ *     "skip". The non-view read-only kinds are hand-managed and MUST NOT reach
+ *     extractViewSpec:
+ *       · storedProc / tableFunction (FR-015) are CALLABLES, base-less → extractViewSpec
+ *         throws (and the CLI calls this unconditionally, so one proc crashed migrate);
+ *       · materializedView has no CREATE-MATVIEW emit and is invisible to
+ *         information_schema.views, so a "managed" matview re-proposes create every run;
+ *       · @unmanaged: Flyway / a hand-migration owns the DDL (§7).
+ *   - @sql read source → "sql": the author owns a verbatim body (emitSqlView).
+ *   - a plain `view` read source → "derive": a tool-synthesized body (the caller applies
+ *     its own viewIsDerived / standalone-read-model gate).
+ *
+ * ADR-0039: own — mirrors isProjection/viewName's own-source classification.
+ */
+type ReadOnlySourceClass =
+  | { kind: "skip" }
+  | { kind: "sql"; source: MetaSource }
+  | { kind: "derive"; source: MetaSource };
+
+function classifyReadOnlySource(host: MetaObject): ReadOnlySourceClass {
+  const source = host.ownChildren().find(
+    (c): c is MetaSource => c instanceof MetaSource && c.isReadOnly(),
+  );
+  if (source === undefined) return { kind: "skip" };
+  if (source.isUnmanaged) return { kind: "skip" }; // external — Flyway/hand-migration owns it
+  if (source.sqlBody !== undefined) return { kind: "sql", source }; // author-supplied body
+  if (source.effectiveKind !== SOURCE_KIND_VIEW) return { kind: "skip" }; // matview/proc/tableFunction
+  return { kind: "derive", source };
+}
+
+/** Extract + emit one host's (projection or write-through entity) view body and
+ *  push it onto `out`. The single tail shared by both walks in buildProjectionViews. */
+function emitViewFor(
+  host: MetaObject,
+  root: MetaRoot,
+  joinTables: Record<string, string>,
+  dialect: "postgres" | "sqlite",
+  columnNamingStrategy: ColumnNamingStrategy,
+  out: ExpectedView[],
+): void {
+  const spec = extractViewSpec(host, root, { columnNamingStrategy });
+  const baseTableName = joinTables[spec.joinTree.baseEntity];
+  if (!baseTableName) return; // unresolved base — skip (loader/codegen surface the error elsewhere)
+  const body = emitViewDdl(spec, { dialect, baseTableName, joinTables, bodyOnly: true });
+  const schema = resolveTableSchema(host);
+  const dependsOn = collectDependsOn(spec, baseTableName, joinTables);
+  const columns = collectViewColumns(spec, baseTableName, joinTables);
+  out.push({
+    name: spec.viewName,
+    sql: body,
+    dependsOn,
+    columns,
+    ...(schema !== undefined ? { schema } : {}),
+  });
+}
+
+/**
+ * #208 §7 — an `@sql` read source declares a hand-written view body. Push it VERBATIM
+ * into the exact same `ExpectedView` pipeline the synthesized body rides — almost no
+ * new machinery:
+ *   - buildExpectedSchema Pass 4 fingerprints `v.sql` (hash of the body);
+ *   - emit stamps the COMMENT marker; author re-indentation does not re-stamp;
+ *   - `columns` is OMITTED (the body is opaque — the tool never parses it), so the diff
+ *     fails safe to a gated drop+create instead of a wrong-but-confident OR REPLACE;
+ *   - a pre-existing unstamped view at this name → `replace-view` blocked pending
+ *     `migrate --allow adopt-view` (the one-time adoption ceremony).
+ * `dependsOn` is derived from the host's own writable table (a write-through host) plus
+ * its extends-bound anchor entities (a projection, D7) — no `@dependsOn` attr.
+ */
+function emitSqlView(
+  host: MetaObject,
+  source: MetaSource,
+  root: MetaRoot,
+  joinTables: Record<string, string>,
+  out: ExpectedView[],
+): void {
+  // D4 — v1 migrate lowering accepts @sql only on a plain @kind: view. matview / proc /
+  // tableFunction need genuinely new introspection (pg_matviews, pg_get_functiondef,
+  // COMMENT-on-matview, a REFRESH story) and stay hand-managed for now — an actionable
+  // hard error, same tiering as SQLite's @schema rejection.
+  if (source.effectiveKind !== SOURCE_KIND_VIEW) {
+    throw new Error(
+      `@sql is not yet migrate-managed on @kind: "${source.effectiveKind}" ` +
+        `(source of "${host.name}"). Mark the source @unmanaged, or track the ` +
+        `matview/callable managed path as a follow-up (#208 D4).`,
+    );
+  }
+  const schema = resolveTableSchema(host);
+  const dependsOn = collectSqlDependsOn(host, root, joinTables);
+  out.push({
+    name: source.physicalName, // FR-016 four-step physical name
+    sql: source.sqlBody!, // verbatim — never parsed, never re-wrapped
+    dependsOn,
+    // columns OMITTED → "unknown" → gated drop+create fail-safe.
+    ...(schema !== undefined ? { schema } : {}),
+  });
+}
+
+/**
+ * The physical tables an `@sql` view depends on. migrate-ts uses this to drop+recreate
+ * the view around a column-altering change on a source table (Postgres blocks ALTER on a
+ * column a view depends on). Two sources, no `@dependsOn` attr:
+ *
+ *   - A **write-through host** (a writable table source + an `@sql` read-view source)
+ *     reads from its OWN table — its one certain dependency. It has NO extends anchors
+ *     (an entity declares its own identity/fields), so without this its `@sql` view's
+ *     dependsOn would be empty and a column ALTER on the host table would fail at apply.
+ *   - A **projection** `@sql` view's dependencies are its extends-bound anchor tables
+ *     (D7 — the `extends` bindings that anchor the read model's shape ARE the dependency
+ *     declaration).
+ *
+ * Deduped. (A table the opaque body JOINs but neither hosts nor anchors is NOT tracked —
+ * the deferred `@dependsOn` escape, ADR-0043.)
+ */
+function collectSqlDependsOn(
+  host: MetaObject,
+  root: MetaRoot,
+  joinTables: Readonly<Record<string, string>>,
+): string[] {
+  const tables = new Set<string>();
+  // The write-through host's own writable table (keyed the way the diff keys descriptors).
+  const hasWritableSource = host.ownChildren().some(
+    (c) => c instanceof MetaSource && c.isWritable(),
+  );
+  if (hasWritableSource) {
+    const t = joinTables[host.name];
+    if (t !== undefined) tables.add(t);
+  }
+  // Extends-bound anchor tables (a projection's read-model base).
+  for (const child of host.ownChildren()) {
+    if (child.type !== TYPE_IDENTITY && child.type !== TYPE_FIELD) continue;
+    const owner = refNamedOwner(child, root);
+    if (owner === undefined) continue;
+    const t = joinTables[owner.name];
+    if (t !== undefined) tables.add(t);
+  }
+  return [...tables];
+}
+
 /**
  * The SELECT list as PHYSICAL (table, column) pairs, in emitted order.
  *
@@ -158,6 +301,14 @@ function collectViewColumns(
 
   const out: ExpectedViewColumn[] = [];
   for (const c of spec.selectSpec.columns) {
+    // #195: the four new origin column kinds (predicateAgg/collectAgg/computed/first) do
+    // not resolve to a single (table, column) SqlType via the prefix rule — computed is
+    // an expression, first is a correlated subquery, and the array/boolean aggregate
+    // result types are richer than the OR-REPLACE prefix check models. Per this module's
+    // fail-safe doctrine (unknown → drop+create, never a wrong-but-confident replace),
+    // an unknown column drops the whole list so migrate routes through a gated
+    // drop+create. Precise native typing is a later phase.
+    if (c.kind !== "passthrough" && c.kind !== "aggregate") return [];
     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.
@@ -217,9 +368,13 @@ function viewIsDerived(projection: MetaObject): boolean {
   );
 }
 
-/** The base table plus every joined table, deduped — the physical tables the view reads. */
+/** The base table plus every joined table AND every origin.first child table, deduped —
+ *  the physical tables the view reads. A `first` column is a correlated subquery, so its
+ *  child table is NOT in the join tree (#195) yet the view still depends on it: if the
+ *  child's columns change, the view must be dropped+recreated. Missing it would let a
+ *  column-altering change on that table fail at apply. */
 function collectDependsOn(
-  joinTree: JoinTree,
+  spec: ViewSpec,
   baseTableName: string,
   joinTables: Readonly<Record<string, string>>,
 ): string[] {
@@ -229,6 +384,12 @@ function collectDependsOn(
     if (t) tables.add(t);
     for (const child of node.children) walk(child);
   };
-  for (const j of joinTree.joins) walk(j);
+  for (const j of spec.joinTree.joins) walk(j);
+  for (const c of spec.selectSpec.columns) {
+    if (c.kind === "first") {
+      const t = joinTables[c.childEntity];
+      if (t) tables.add(t);
+    }
+  }
   return [...tables];
 }