@metaobjectsdev/codegen-ts 1.0.5-rc.1 → 1.0.5-rc.3

package/src/templates/routes-file.ts

@@ -31,6 +31,7 @@ import type { RelationEntry } from "../relation-resolver.js";
 import { isTphDiscriminatorBase, tphPlan } from "./tph-discriminator.js";
 import { authSeamJsDoc, type CrudVerb, exposeLine, intersectExpose, TPH_POLYMORPHIC_VERBS } from "../routes-expose.js";
 import { effectivePackage } from "../docs-paths.js";
+import { tphDiscriminatorPin, tphStorageObject } from "./zod-validators.js";
 
 export function renderRoutesFile(
   entity: MetaObject,
@@ -166,9 +167,7 @@ export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
   // FK columns were derived from the junction's identity.reference children (the
   // SSOT) by the relation-resolver pre-pass; here we resolve them to physical
   // column names for the Drizzle two-stage join.
-  const m2mEntries = (ctx.relationMap.get(entityName) ?? []).filter(
-    (e): e is RelationEntry & { junctionEntity: string } => e.junctionEntity !== undefined,
-  );
+  const m2mEntries = m2mEntriesOf(ctx, entityName);
   // Two fastify-scope variants: under an apiPrefix the mounts live inside the
   // register-block (`instance`); otherwise they bind directly to `fastify`.
   const m2mMountsPrefixed = renderM2mMounts(m2mEntries, entity, ctx, "instance");
@@ -241,6 +240,21 @@ ${m2mMountsFlat}}
   return header + literalImports.toString() + body.toString();
 }
 
+/**
+ * The M:N navigation entries of `name` — the ONE rule for which relationships get a
+ * traversal mount. The vanilla entity path and the TPH path both go through it, so
+ * they cannot drift apart: a rule change moves every mount at once, and the
+ * independent oracle's route rule stays checkable against both emit paths alike.
+ */
+function m2mEntriesOf(
+  ctx: RenderContext,
+  name: string,
+): Array<RelationEntry & { junctionEntity: string }> {
+  return (ctx.relationMap.get(name) ?? []).filter(
+    (e): e is RelationEntry & { junctionEntity: string } => e.junctionEntity !== undefined,
+  );
+}
+
 /**
  * Render the M:N traversal mounts for an entity as a single Code fragment to
  * interpolate INTO the handler-body code template (so the junction/target table
@@ -254,13 +268,38 @@ function renderM2mMounts(
   source: MetaObject,
   ctx: RenderContext,
   fastifyVar: string,
+  tphSource?: TphM2mSource,
 ): Code | string {
   if (entries.length === 0) return "";
-  const mounts = entries.map((e) => renderM2mMount(e, source, ctx, fastifyVar));
+  const mounts = entries.map((e) => renderM2mMount(e, source, ctx, fastifyVar, tphSource));
   return code`${joinCode(mounts, { on: "\n", trim: false })}
 `;
 }
 
+/**
+ * Where a TPH M:N mount hangs, and how it proves the source id is really ITS subtype's.
+ *
+ * Only `renderTphRoutesFile` supplies this, and only for a relationship declared ON a
+ * subtype. The path gains that subtype's segment, and `sourceDiscriminator` gets the
+ * check that makes the segment mean something: the junction FK points at the shared base
+ * table, so without it a sibling subtype's id reaches the same junction rows and the
+ * segment in the URL is decorative. A relationship declared on the BASE passes nothing
+ * here — every row of the table is a legitimate source — so its mount is byte-identical
+ * to a vanilla entity's.
+ */
+interface TphM2mSource {
+  /** Appended to the base entity's `$path`, e.g. `"/bridge"`. */
+  pathSuffix: string;
+  /** The base table const this subtype's rows live in. */
+  table: Code | string;
+  /** Physical PK column of the base table. */
+  pkColumn: Code;
+  /** Physical discriminator column of the base table. */
+  discriminatorColumn: Code;
+  /** This subtype's `@discriminatorValue`. */
+  value: string;
+}
+
 /**
  * Render one M:N traversal mount. The junction + target Drizzle table consts are
  * imported from their sibling entity files (imp() lets ts-poet track + emit the
@@ -273,6 +312,7 @@ function renderM2mMount(
   source: MetaObject,
   ctx: RenderContext,
   fastifyVar: string,
+  tphSource?: TphM2mSource,
 ): Code {
   // `source` never changes across this function, so its effective package is computed
   // once and reused below (both crossEntitySpecifier calls, and the three
@@ -288,18 +328,30 @@ function renderM2mMount(
       ctx.extStyle,
     )}`,
   );
-  const targetVarSym = imp(
-    `${ctx.collectionName(entry.targetEntity)}@${crossEntitySpecifier(
-      ctx.outputLayout,
-      sourcePkg,
-      ctx.packageOf.get(entry.targetEntity),
-      entry.targetEntity,
-      ctx.extStyle,
-    )}`,
-  );
+  // An M:N onto a TPH subtype traverses into its discriminator BASE's table — the
+  // subtype has no table const, and the junction FK can only point at the base table —
+  // and filters the rows to the subtype, because a Broker id in that FK column is not a
+  // Carrier. Every other target binds to itself, and emits no filter.
+  const declaredTarget = ctx.loadedRoot.findObject(entry.targetEntity);
+  const target = declaredTarget === undefined ? undefined : tphStorageObject(declaredTarget);
+  const targetTableEntity = target?.name ?? entry.targetEntity;
+  const pin = declaredTarget === undefined ? undefined : tphDiscriminatorPin(declaredTarget);
+  // A self-join's target table IS the source table, which this file already imports from
+  // the entity module; a second import of the same binding is TS2300, and a SyntaxError
+  // when Node loads the module.
+  const targetVarSym = targetTableEntity === source.name
+    ? ctx.collectionName(source.name)
+    : imp(
+      `${ctx.collectionName(targetTableEntity)}@${crossEntitySpecifier(
+        ctx.outputLayout,
+        sourcePkg,
+        ctx.packageOf.get(targetTableEntity),
+        targetTableEntity,
+        ctx.extStyle,
+      )}`,
+    );
   const mountM2mRouteSym = imp("mountM2mRoute@@metaobjectsdev/runtime-ts/drizzle-fastify");
   const junction = ctx.loadedRoot.findObject(entry.junctionEntity);
-  const target = ctx.loadedRoot.findObject(entry.targetEntity);
   // fromPackage = source.package: this routes file is SOURCE's own module, never the
   // junction's or the target's — see resolveJunctionColumn's doc comment (B1).
   const sourceColumn: Code = junction
@@ -309,12 +361,27 @@ function renderM2mMount(
     ? resolveJunctionColumn(junction, entry.targetJoinField!, ctx, sourcePkg)
     : code`${JSON.stringify(entry.targetJoinField!)}`;
   const targetPkColumn: Code = target
-    ? resolveJunctionColumn(target, ctx.pkMap.get(entry.targetEntity)?.fieldName ?? "id", ctx, sourcePkg)
+    ? resolveJunctionColumn(target, ctx.pkMap.get(targetTableEntity)?.fieldName ?? "id", ctx, sourcePkg)
     : code`${JSON.stringify("id")}`;
+  const discriminatorLine: Code | string = pin !== undefined && target !== undefined
+    ? code`
+    targetDiscriminator: { column: ${resolveJunctionColumn(target, pin.fieldName, ctx, sourcePkg)}, value: ${JSON.stringify(pin.value)} },`
+    : "";
+
+  // A subtype-declared M:N hangs under the subtype's segment; everything else hangs at
+  // the source entity's own path. `$path` is read from the BASE const either way — a TPH
+  // subtype's module exports no entity const of its own.
+  const pathExpr: Code = tphSource === undefined
+    ? code`${source.name}.$path`
+    : code`${source.name}.$path + ${JSON.stringify(tphSource.pathSuffix)}`;
+  const sourceDiscriminatorLine: Code | string = tphSource === undefined
+    ? ""
+    : code`
+    sourceDiscriminator: { table: ${tphSource.table}, pkColumn: ${tphSource.pkColumn}, column: ${tphSource.discriminatorColumn}, value: ${JSON.stringify(tphSource.value)} },`;
 
   return code`  ${mountM2mRouteSym}({
     fastify: ${fastifyVar},
-    path: ${source.name}.$path,
+    path: ${pathExpr},
     relationName: ${JSON.stringify(entry.name)},
     db,
     junctionTable: ${junctionVarSym},
@@ -322,7 +389,7 @@ function renderM2mMount(
     sourceColumn: ${sourceColumn},
     targetColumn: ${targetColumn},
     targetPkColumn: ${targetPkColumn},
-    symmetric: ${entry.symmetric ? "true" : "false"},
+    symmetric: ${entry.symmetric ? "true" : "false"},${discriminatorLine}${sourceDiscriminatorLine}
   });`;
 }
 
@@ -423,7 +490,20 @@ function renderTphRoutesFile(
       dialect: ${dialectLit},${polymorphicExposeLine}
     });`;
 
-  const subtypeMounts: Code[] = plan.subtypes.map(({ entity: sub, value, routeSegment: segment }) => {
+  // FR-018 x FR-017 — M:N traversal inside a TPH hierarchy. This file never consulted
+  // the relation map at all, so BOTH sides vanished from the generated API: a
+  // relationship declared on the base (every row of the table is a legitimate source)
+  // and one declared on a subtype (only that subtype's rows are). Neither is a compile
+  // error — a route that is never mounted is an absence — which is why the codegen
+  // compile gate stayed green while the endpoint 404'd.
+  //
+  // The physical columns stage 0 needs, resolved once against the base's own table.
+  const basePkField = ctx.pkMap.get(baseName)?.fieldName ?? "id";
+  const basePkColumn = resolveJunctionColumn(base, basePkField, ctx, basePkg);
+  const baseDiscColumn = resolveJunctionColumn(base, discField, ctx, basePkg);
+  const baseM2mMounts = renderM2mMounts(m2mEntriesOf(ctx, baseName), base, ctx, fastifyRef);
+
+  const subtypeMounts: Code[] = plan.subtypes.flatMap(({ entity: sub, value, routeSegment: segment }) => {
     const subFileSpec = entityModuleSpecifier(
       ctx.selfTarget, ctx.entityModuleTarget, effectivePackage(sub), sub.name, ctx.extStyle,
     );
@@ -440,7 +520,7 @@ function renderTphRoutesFile(
     // (discriminator excluded — it's pinned by this path).
     const subFilterSym = imp(`${sub.name}FilterAllowlist@${subFileSpec}`);
     const subSortSym = imp(`${sub.name}SortAllowlist@${subFileSpec}`);
-    return code`
+    const crud = code`
     ${mountCrudRoutesSym}({
       fastify: ${fastifyRef},
       path: ${baseConstSym}.$path + ${JSON.stringify("/" + segment)},
@@ -453,9 +533,32 @@ function renderTphRoutesFile(
       dialect: ${dialectLit},
       discriminator: { column: ${JSON.stringify(discField)}, value: ${JSON.stringify(value)} },${exposeLine(expose, "      ")}
     });`;
+    // This subtype's own M:N navigations, mounted beneath its segment and gated on the
+    // discriminator so a sibling's id yields [] instead of the sibling's relations.
+    //
+    // Every relationship this subtype RESOLVES, inherited ones included — not just the
+    // ones it declares. A subtype resource is a resource: `/auths/bridge/1` carries the
+    // same sub-resources as any other, so it carries the base's relationships too, and
+    // an abstract mid level's relationship has nowhere else to be served at all.
+    //
+    // The base mounts its own set separately, at its own path. The overlap is deliberate
+    // and not redundant: `/auths/1/tags` accepts any row of the table, while
+    // `/auths/bridge/1/tags` answers [] for a Copay id — the segment is a type
+    // assertion, which is exactly what sourceDiscriminator enforces below.
+    const subM2m = renderM2mMounts(m2mEntriesOf(ctx, sub.name), base, ctx, fastifyRef, {
+      pathSuffix: "/" + segment,
+      table: code`${tableSym}`,
+      pkColumn: basePkColumn,
+      discriminatorColumn: baseDiscColumn,
+      value,
+    });
+    return subM2m === "" ? [crud] : [crud, subM2m as Code];
   });
 
-  const mounts = joinCode([polymorphic, ...subtypeMounts], { on: "\n" });
+  const mounts = joinCode(
+    [polymorphic, ...(baseM2mMounts === "" ? [] : [baseM2mMounts as Code]), ...subtypeMounts],
+    { on: "\n" },
+  );
   // The base path is read-only by construction (TPH_POLYMORPHIC_VERBS), but the
   // per-subtype mounts below it are full CRUD — so `expose` does narrow this file.
   const tphAuthJsDoc = authSeamJsDoc({ framework: "fastify", handlerName, narrowable: true });

package/src/templates/zod-validators.ts

@@ -10,7 +10,7 @@
 // downstream (e.g. to LLM tool_use input_schema) lost the nested object shape.
 
 import { code, joinCode, imp, type Code } from "ts-poet";
-import { MetaObject, MetaField, stripPackage } from "@metaobjectsdev/metadata";
+import { MetaObject, MetaField, type MetaRoot, stripPackage } from "@metaobjectsdev/metadata";
 import {
   FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_CURRENCY,
   FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT,
@@ -75,6 +75,28 @@ export function tphDiscriminatorBase(obj: MetaObject): MetaObject | undefined {
   return tphDiscriminatorLevel(obj)?.base;
 }
 
+/**
+ * The object whose TABLE stores `obj`'s rows: the discriminator base for anything beneath
+ * a TPH base — a concrete subtype or an abstract level in between — otherwise `obj`.
+ *
+ * Neither a subtype's module nor an abstract level's emits a table const, so anything
+ * that binds to "the other side" of a reference or relationship — an FK's `.references()`,
+ * a `relations()` entry, an M:N traversal's target table — must bind here and never to the
+ * target's own name. Binding to the subtype imported `carriers` from a `Carrier.ts` that
+ * does not export it.
+ */
+export function tphStorageObject(obj: MetaObject): MetaObject {
+  if (declaresTphDiscriminator(obj)) return obj;
+  return tphDiscriminatorBase(obj) ?? obj;
+}
+
+/** {@link tphStorageObject} by entity name, for the name-keyed relation map. A name the
+ *  root does not resolve is returned unchanged. */
+export function tphStorageName(entityName: string, root: MetaRoot): string {
+  const obj = root.findObject(entityName);
+  return obj === undefined ? entityName : tphStorageObject(obj).name;
+}
+
 /**
  * True when this object itself DECLARES `@discriminator` — the level of a TPH hierarchy
  * that owns the discriminator, whether or not any concrete subtype extends it yet.
@@ -126,26 +148,46 @@ export function hasAutoSetFields(obj: MetaObject): boolean {
   return false;
 }
 
+/** Is this field's column one the TPH BASE declares, rather than a subtype-only one?
+ *
+ *  Resolving (ADR-0039) and compared by name against `base.fields()` — exactly the set
+ *  `collectTphSubtypeFields` treats as "already emitted" when it folds the subtype
+ *  columns into the base table, so the two answers cannot drift apart. A field declared
+ *  on an abstract level BETWEEN the base and the subtype is subtype-only: the base's own
+ *  field set does not carry it, and neither does the base's `.notNull()`. */
+function isTphBaseOwnField(obj: MetaObject, field: MetaField): boolean {
+  const base = tphDiscriminatorBase(obj);
+  if (base === undefined) return false;
+  return base.fields().some((f) => f.name === field.name);
+}
+
 /**
  * Is this field NULL-tolerant in a TPH subtype's READ shape?
  *
- * A TPH subtype shares one physical table with its siblings, so a column only one
- * subtype declares is NULL on every other subtype's row, and a non-`@required` column
- * of this subtype's own is NULL when unset. Either way the value read back is `null`,
- * not `undefined`. The PRIMARY KEY is the exception — it is the shared base table's
- * key and is present on every row.
+ * Answered from the PHYSICAL column, because that is the only thing a read can return.
+ * A TPH subtype shares one table with its siblings, so a column only some subtypes
+ * declare is NULL on every other subtype's row and `drizzle-schema.ts` drops its
+ * `.notNull()` whatever `@required` says (its `forceNullable` fold). A column the base
+ * itself declares carries `.notNull()` precisely when the field is required. The PRIMARY
+ * KEY is the shared base table's key and is present on every row.
+ *
+ * `@default` is deliberately NOT consulted, and that is the fix rather than an omission.
+ * A default decides whether an INSERT may leave the value out; it says nothing about what
+ * a READ can see. Asking `fieldWillBeOptional` here widened a `NOT NULL DEFAULT` column to
+ * `| null` and — through the `.optional()` that same predicate mirrors — to `| undefined`,
+ * which the declared interface did not admit: `parse<Base>()` returned a value not
+ * assignable to the base union and the generated module failed to compile (TS2322).
  *
  * ONE predicate, because TWO emitters answer this question about the same field: the
  * Zod read schema (`renderTphSubtypeReadSchema`) and the declared TS type
- * (`renderValueObjectInterface`). They answered it differently, so the value
- * `parse<Base>()` returns was not assignable to the base union and the generated
- * module did not compile (TS2322). A second answer to one question is the defect;
+ * (`renderValueObjectInterface`). A second answer to one question is the defect;
  * keeping the two call sites pointed here is the fix.
  */
 export function isTphReadNullTolerant(obj: MetaObject, field: MetaField): boolean {
   if (!isTphSubtype(obj)) return false;
-  if (!fieldWillBeOptional(field)) return false;
-  return !primaryIdentityFieldNames(obj).includes(field.name);
+  if (primaryIdentityFieldNames(obj).includes(field.name)) return false;
+  if (!isTphBaseOwnField(obj, field)) return true;
+  return !isRequired(field);
 }
 
 /**
@@ -169,10 +211,16 @@ export function renderTphSubtypeReadSchema(obj: MetaObject, ctx?: RenderContext)
       fieldLines.push(code`  ${child.name}: z.literal(${JSON.stringify(tphPin.value)})`);
       continue;
     }
-    const expr = zodFieldExpr(child, obj, ctx);
-    // zodFieldExpr already appends `.optional()` for non-required fields; add
-    // `.nullable()` on top so a NULL column value parses cleanly. The declared
-    // interface widens the SAME fields — see isTphReadNullTolerant.
+    // forceRequired: a row selected from the table carries every column as a KEY —
+    // a nullable one arrives as `null`, never absent — so nothing with a COLUMN in a
+    // read shape is `.optional()`. Letting zodFieldExpr append it made the inferred
+    // type `T | undefined` while the declared interface said `T`, and the two
+    // disagreed. A derived (origin-bearing) field is the one member of obj.fields()
+    // with no column — drizzle-schema.ts emits none, and the TPH queries path selects
+    // the bare base table — so its key is genuinely absent from every parsed row and
+    // it alone keeps `.optional()`, matching the interface's `?: T | null`.
+    // Null-tolerance is added below, from the column, by isTphReadNullTolerant.
+    const expr = zodFieldExpr(child, obj, ctx, !child.isDerived());
     fieldLines.push(
       isTphReadNullTolerant(obj, child)
         ? code`  ${child.name}: ${expr}.nullable()`
@@ -584,8 +632,9 @@ function zodFieldExpr(
   field: MetaField,
   owner?: MetaObject,
   ctx?: RenderContext,
-  /** Suppress the trailing `.optional()` — see assignedPkFieldNames. Set ONLY
-   *  by the insert-shape emitters; the update/read shapes must stay optional. */
+  /** Suppress the trailing `.optional()`. Set by the insert-shape emitters for an
+   *  assigned PK (see assignedPkFieldNames) and by the TPH read shape, where every
+   *  column is a present key. The UPDATE shape must stay optional (PATCH semantics). */
   forceRequired = false,
 ): Code {
   // `@dbColumnType: jsonb` on a scalar (legal only on field.string) is the