feat(codegen-ts): FR-017 Tier 1 — TPH discriminated union + per-subtype Zod pin

dmealing · claude · dmealing · commit 7ac54a351c7f · 2026-06-02T17:31:53.000-04:00
First implementation tier of FR-017 (spec at b312e5b): TS types-only TPH codegen. Subsequent tiers (Drizzle TPH table, polymorphic queries, per-subtype REST routes, TanStack hooks, per-port fan-out) are deferred and tracked in the FR-017 spec's §Tiered delivery table. What ships in this commit: 1. **New template `tph-discriminator.ts`** — for an entity carrying @Discriminator AND at least one concrete subtype declaring @discriminatorValue extending it, emits three artifacts: - `export type <Base> = <Sub1> | <Sub2> | ...` discriminated union. - One `is<Subtype>(value): value is <Subtype>` type guard per subtype. - `parse<Base>(row: unknown): <Base>` dispatcher that reads the discriminator off the raw row (via `z.object({ <field>: z.enum([...]) })`) and parses with the matching subtype's Zod schema. Returns null when the entity is not a discriminator-bearing base, or has no concrete subtypes (the FR-014 "string-no-subtypes" refactor-in-progress shape is unaffected). 2. **`zod-validators.ts` discriminator pin** — when an entity carries @discriminatorValue, its Zod schema replaces the discriminator field's type expression with `z.literal("<value>")`. The pin lives on the Insert schema only; the Update schema omits the discriminator entirely (clients never change a Bridge into a Copay). 3. **`entity-file.ts` wires the union block** — runs after the entity's own sections (Drizzle, inferred types, Zod, constants, allowlists, filter type). The section is omitted cleanly when the helper returns null. Tests: 5 new tests in test/templates/tph-discriminator.test.ts. Full codegen-ts: 565 pass / 0 fail. No regressions in metadata (1514/2 — both fails pre-existing template-doc fixtures from upstream commit 40c39a3). What does NOT ship in this commit (per FR-017 §Tiered delivery): - Drizzle TPH table union-of-columns emission (Tier 2). - Polymorphic queriesFile + per-subtype query helpers (Tier 2). - Per-subtype REST routes POST /auths/bridge (Tier 2). - TanStack hooks / forms / grids (Tier 3). - Java / Kotlin / C# / Python (Tier 4). - API-contract + persistence-conformance scenarios (Tier 5). No new stable-name generator added under ADR-0021 — the union block lives inside the existing `entity` generator. The canonical manifest is unchanged. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
diff --git a/server/typescript/packages/codegen-ts/src/templates/entity-file.ts b/server/typescript/packages/codegen-ts/src/templates/entity-file.ts
@@ -15,6 +15,7 @@ import { renderZodValidators } from "./zod-validators.js";
 import { renderEntityConstants } from "./entity-constants.js";
 import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
 import { renderFilterType } from "./filter-type.js";
+import { renderTphDiscriminatorUnion } from "./tph-discriminator.js";
 import { GENERATED_HEADER } from "../constants.js";
 import { isProjection } from "../projection/projection-detector.js";
 import { renderProjectionDecl } from "./projection-decl.js";
@@ -77,6 +78,11 @@ export function renderEntityFile(
 
   // --- Vanilla / write-through entity path ---
   const enumAliases = renderEnumTypeAliases(entity);
+  // FR-017 Tier 1: when this entity carries @discriminator AND has concrete
+  // subtypes, append the discriminated-union type alias, type guards, and
+  // the parse<Base>(row) dispatcher. Returns null otherwise (no subtypes, or
+  // not a discriminator-bearing entity); the section is suppressed cleanly.
+  const tphBlock = renderTphDiscriminatorUnion(entity, ctx.loadedRoot);
   const sections: Code[] = [
     renderDrizzleSchema(entity, ctx),
     renderInferredTypes(entity),
@@ -85,6 +91,7 @@ export function renderEntityFile(
     renderEntityConstants(entity, ctx.apiPrefix),
     ...(allowlists ? [renderFilterAllowlist(entity), renderSortAllowlist(entity)] : []),
     renderFilterType(entity),
+    ...(tphBlock !== null ? [tphBlock] : []),
   ];
 
   // Render ts-poet body first (ts-poet hoists imp()-tracked imports to the top),
diff --git a/server/typescript/packages/codegen-ts/src/templates/tph-discriminator.ts b/server/typescript/packages/codegen-ts/src/templates/tph-discriminator.ts
@@ -0,0 +1,126 @@
+// FR-017 Tier 1 — TS discriminated-union + type guards + dispatcher emission.
+//
+// For an entity that carries `@discriminator`, this template emits:
+//   1. `export type <Base> = <Sub1> | <Sub2> | ...` — discriminated union of
+//      every concrete subtype declaring @discriminatorValue against this base.
+//   2. `export function is<Sub>(value: <Base>): value is <Sub>` — one type
+//      guard per subtype, checking the discriminator field's value.
+//   3. `export function parse<Base>(row: unknown): <Base>` — runtime dispatcher
+//      that reads the discriminator off the raw row and parses with the
+//      matching subtype's Zod schema.
+//
+// When the entity does NOT carry @discriminator, returns null. When the entity
+// carries @discriminator but has no concrete subtypes yet (refactor-in-progress
+// shape — covered by FR-014 fixture `tph-discriminator-string-no-subtypes`),
+// returns null too: there are no subtype names to union.
+
+import { code, joinCode, imp, type Code } from "ts-poet";
+import {
+  type MetaObject,
+  type MetaRoot,
+  OBJECT_ATTR_DISCRIMINATOR,
+  OBJECT_ATTR_DISCRIMINATOR_VALUE,
+  OBJECT_SUBTYPE_ENTITY,
+} from "@metaobjectsdev/metadata";
+
+interface SubtypeBinding {
+  subtype: MetaObject;
+  value: string;
+}
+
+/** Render the TPH union + guards + dispatcher block, or null when the entity
+ *  is not a discriminator-bearing base with at least one concrete subtype. */
+export function renderTphDiscriminatorUnion(
+  base: MetaObject,
+  root: MetaRoot,
+): Code | null {
+  const discFieldName = base.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
+  if (typeof discFieldName !== "string" || discFieldName === "") return null;
+
+  const subtypes = collectConcreteSubtypes(base, root);
+  if (subtypes.length === 0) return null;
+
+  const baseName = base.name;
+
+  // 1. Union type alias. Subtype names are imported lazily via ts-poet `imp()`
+  //    so they resolve cross-module without manual import wiring.
+  const unionMembers: Code[] = subtypes.map((b) => {
+    const sub = imp(`t:${b.subtype.name}@./${b.subtype.name}.js`);
+    return code`${sub}`;
+  });
+  const unionType = code`export type ${baseName} = ${joinCode(unionMembers, { on: " | " })};`;
+
+  // 2. Type guards.
+  const guards: Code[] = subtypes.map((b) => {
+    const sub = imp(`t:${b.subtype.name}@./${b.subtype.name}.js`);
+    return code`
+/** True when value is a ${b.subtype.name} (discriminated by ${discFieldName} === "${b.value}"). */
+export function is${b.subtype.name}(value: ${baseName}): value is ${sub} {
+  return value.${discFieldName} === "${b.value}";
+}`;
+  });
+
+  // 3. Dispatcher. The head-read uses z.object so the discriminator is read
+  //    without committing the row to any subtype yet.
+  const z = imp("z@zod");
+  const enumLiterals = subtypes.map((b) => JSON.stringify(b.value)).join(", ");
+
+  const caseBranches: Code[] = subtypes.map((b) => {
+    const schema = imp(`${b.subtype.name}Schema@./${b.subtype.name}.js`);
+    return code`    case ${JSON.stringify(b.value)}: return ${schema}.parse(row);`;
+  });
+
+  const dispatcher = code`
+/**
+ * Parse a row from the ${baseName} table, dispatching by the
+ * \`${discFieldName}\` discriminator value to the matching subtype's
+ * Zod schema. Throws on unknown discriminator values.
+ */
+export function parse${baseName}(row: unknown): ${baseName} {
+  const head = ${z}.object({ ${discFieldName}: ${z}.enum([${enumLiterals}]) }).parse(row);
+  switch (head.${discFieldName}) {
+${joinCode(caseBranches, { on: "\n" })}
+  }
+}
+`;
+
+  return code`
+${unionType}
+
+${joinCode(guards, { on: "\n" })}
+
+${dispatcher}
+`;
+}
+
+/** Walk every top-level object.entity in the root and return the concrete
+ *  subtypes whose @discriminatorValue is bound to this base via extends.
+ *  Abstract intermediates are skipped (they don't have polymorphic instances). */
+function collectConcreteSubtypes(base: MetaObject, root: MetaRoot): SubtypeBinding[] {
+  const bindings: SubtypeBinding[] = [];
+  for (const obj of root.objects()) {
+    if (obj.subType !== OBJECT_SUBTYPE_ENTITY) continue;
+    if (obj.isAbstract === true) continue;
+    if (obj === base) continue;
+
+    const value = obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE);
+    if (typeof value !== "string" || value === "") continue;
+
+    // Walk this entity's extends chain looking for `base`.
+    let cursor = obj.superResolved;
+    let found = false;
+    while (cursor !== undefined) {
+      if (cursor === base) {
+        found = true;
+        break;
+      }
+      cursor = cursor.superResolved;
+    }
+    if (!found) continue;
+
+    bindings.push({ subtype: obj, value });
+  }
+  // Stable order by subtype name so emission is deterministic.
+  bindings.sort((a, b) => a.subtype.name.localeCompare(b.subtype.name));
+  return bindings;
+}
diff --git a/server/typescript/packages/codegen-ts/src/templates/zod-validators.ts b/server/typescript/packages/codegen-ts/src/templates/zod-validators.ts
@@ -24,10 +24,34 @@ import {
   AUTO_SET_ON_CREATE, AUTO_SET_ON_UPDATE,
   VALIDATOR_ATTR_MAX, VALIDATOR_ATTR_MIN, VALIDATOR_ATTR_PATTERN,
   GENERATION_INCREMENT, GENERATION_UUID,
+  OBJECT_ATTR_DISCRIMINATOR, OBJECT_ATTR_DISCRIMINATOR_VALUE,
 } from "@metaobjectsdev/metadata";
 import { enumValues, zodEnumExpr } from "../enum-meta.js";
 import { renderDocsFor } from "./jsdoc.js";
 
+/**
+ * FR-017 Tier 1 — when this object is a TPH subtype (@discriminatorValue set
+ * and an ancestor carries @discriminator), return the discriminator-field-name
+ * → pinned-literal-value pair. Subtypes emit `<field>: z.literal("<value>")`
+ * instead of the inherited field's normal type expression. Returns undefined
+ * when the object is not a TPH subtype.
+ */
+function tphDiscriminatorPin(obj: MetaObject): { fieldName: string; value: string } | undefined {
+  const value = obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE);
+  if (typeof value !== "string" || value === "") return undefined;
+
+  // Walk the extends chain to find the root carrying @discriminator.
+  let cursor = obj.superResolved;
+  while (cursor !== undefined) {
+    const fieldName = cursor.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
+    if (typeof fieldName === "string" && fieldName !== "") {
+      return { fieldName, value };
+    }
+    cursor = cursor.superResolved;
+  }
+  return undefined;
+}
+
 /** Auto-generated PK field names that should be omitted from InsertSchema. */
 function autoGenPkFieldNames(obj: MetaObject): Set<string> {
   const out = new Set<string>();
@@ -55,6 +79,7 @@ function autoGenPkFieldNames(obj: MetaObject): Set<string> {
 export function renderInsertSchemaOnly(obj: MetaObject): Code {
   const z = imp("z@zod");
   const autoGenPkFields = autoGenPkFieldNames(obj);
+  const tphPin = tphDiscriminatorPin(obj);
 
   const insertFieldLines: Code[] = [];
   for (const child of obj.fields()) {
@@ -64,6 +89,14 @@ export function renderInsertSchemaOnly(obj: MetaObject): Code {
     // create-shape schema entirely.
     if (child.ownAttr(FIELD_ATTR_READ_ONLY) === true) continue;
 
+    // FR-017 Tier 1: TPH subtype pins its discriminator field to z.literal(...).
+    if (tphPin !== undefined && child.name === tphPin.fieldName) {
+      insertFieldLines.push(
+        code`  ${child.name}: z.literal(${JSON.stringify(tphPin.value)})`,
+      );
+      continue;
+    }
+
     const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
 
     if (autoSet === AUTO_SET_ON_CREATE || autoSet === AUTO_SET_ON_UPDATE) {
@@ -89,6 +122,7 @@ ${joinCode(insertFieldLines, { on: ",\n" })}
 export function renderZodValidators(obj: MetaObject): Code {
   const z = imp("z@zod");
   const autoGenPkFields = autoGenPkFieldNames(obj);
+  const tphPin = tphDiscriminatorPin(obj);
 
   const insertFieldLines: Code[] = [];
   const updateFieldLines: Code[] = [];
@@ -100,6 +134,17 @@ export function renderZodValidators(obj: MetaObject): Code {
     // contract at the boundary with a 400 response).
     if (child.ownAttr(FIELD_ATTR_READ_ONLY) === true) continue;
 
+    // FR-017 Tier 1: TPH subtype pins its discriminator field to z.literal(...).
+    // The discriminator is implicit on subtype rows (controlled by URL / insert
+    // path) — the app never writes it via the body and never updates it.
+    // Insert: pinned literal. Update: omitted entirely (clients can't change subtype).
+    if (tphPin !== undefined && child.name === tphPin.fieldName) {
+      insertFieldLines.push(
+        code`  ${child.name}: z.literal(${JSON.stringify(tphPin.value)})`,
+      );
+      continue;
+    }
+
     const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
 
     // Insert schema: @autoSet fields use transform (always override client input).
diff --git a/server/typescript/packages/codegen-ts/test/templates/tph-discriminator.test.ts b/server/typescript/packages/codegen-ts/test/templates/tph-discriminator.test.ts
@@ -0,0 +1,130 @@
+// FR-017 Tier 1 — TS discriminated union + per-subtype Zod emission.
+//
+// For an entity with @discriminator + concrete subtypes carrying
+// @discriminatorValue, entityFile additionally emits:
+//   - The union type `Auth = BridgeAuth | CopayAuth | ...`
+//   - Type guards `isBridgeAuth(a): a is BridgeAuth`
+//   - The `parseAuth(row)` dispatcher
+//
+// For each subtype, the subtype's Zod schema pins the discriminator field
+// via z.literal("<value>"), so a subtype schema rejects a row of a different
+// subtype.
+
+import { describe, expect, test } from "bun:test";
+import {
+  MetaDataLoader,
+  InMemoryStringSource,
+  type MetaObject,
+} from "@metaobjectsdev/metadata";
+import { renderTphDiscriminatorUnion } from "../../src/templates/tph-discriminator.js";
+import { renderZodValidators } from "../../src/templates/zod-validators.js";
+
+async function loadTph() {
+  const loader = new MetaDataLoader();
+  const { root, errors } = await loader.load([
+    new InMemoryStringSource(
+      JSON.stringify({
+        "metadata.root": {
+          package: "demo",
+          children: [
+            {
+              "object.entity": {
+                name: "Auth",
+                "@discriminator": "type",
+                children: [
+                  { "source.rdb": { "@table": "auths" } },
+                  {
+                    "field.enum": {
+                      name: "type",
+                      "@values": ["Bridge", "Copay"],
+                    },
+                  },
+                  { "field.long": { name: "id" } },
+                  { "identity.primary": { "@fields": "id" } },
+                ],
+              },
+            },
+            {
+              "object.entity": {
+                name: "BridgeAuth",
+                extends: "Auth",
+                "@discriminatorValue": "Bridge",
+                children: [{ "field.int": { name: "quantity" } }],
+              },
+            },
+            {
+              "object.entity": {
+                name: "CopayAuth",
+                extends: "Auth",
+                "@discriminatorValue": "Copay",
+                children: [
+                  {
+                    "field.decimal": {
+                      name: "copayAmount",
+                      "@precision": 10,
+                      "@scale": 2,
+                    },
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      }),
+      { id: "auth.json" },
+    ),
+  ]);
+  if (errors.length > 0) throw new Error(errors.map((e) => e.message).join("; "));
+  const base = root.objects().find((o) => o.name === "Auth")! as MetaObject;
+  const bridge = root.objects().find((o) => o.name === "BridgeAuth")! as MetaObject;
+  const copay = root.objects().find((o) => o.name === "CopayAuth")! as MetaObject;
+  return { root, base, bridge, copay };
+}
+
+describe("FR-017 Tier 1 — renderTphDiscriminatorUnion", () => {
+  test("emits the discriminated union + type guards + parser dispatcher on the base entity", async () => {
+    const { root, base } = await loadTph();
+    const out = renderTphDiscriminatorUnion(base, root).toString();
+
+    // Union type spans every concrete subtype, base does not appear in members.
+    expect(out).toContain("export type Auth = BridgeAuth | CopayAuth");
+
+    // Type guards per subtype.
+    expect(out).toContain("export function isBridgeAuth(value: Auth)");
+    expect(out).toContain("export function isCopayAuth(value: Auth)");
+    expect(out).toContain('value.type === "Bridge"');
+    expect(out).toContain('value.type === "Copay"');
+
+    // Dispatcher function reads the discriminator without committing to a
+    // subtype yet, then dispatches via switch.
+    expect(out).toContain("export function parseAuth(row: unknown): Auth");
+    expect(out).toContain('case "Bridge":');
+    expect(out).toContain('case "Copay":');
+  });
+
+  test("returns null for an entity that has no @discriminator", async () => {
+    const { root, bridge } = await loadTph();
+    // bridge is a subtype, not the discriminator-bearing root.
+    expect(renderTphDiscriminatorUnion(bridge, root)).toBeNull();
+  });
+});
+
+describe("FR-017 Tier 1 — subtype Zod pins discriminator via z.literal", () => {
+  test("BridgeAuth's Zod schema pins type to z.literal(\"Bridge\")", async () => {
+    const { bridge } = await loadTph();
+    const out = renderZodValidators(bridge).toString();
+    expect(out).toContain('z.literal("Bridge")');
+  });
+
+  test("CopayAuth's Zod schema pins type to z.literal(\"Copay\")", async () => {
+    const { copay } = await loadTph();
+    const out = renderZodValidators(copay).toString();
+    expect(out).toContain('z.literal("Copay")');
+  });
+
+  test("BridgeAuth's schema still emits the subtype-only field", async () => {
+    const { bridge } = await loadTph();
+    const out = renderZodValidators(bridge).toString();
+    expect(out).toContain("quantity:");
+  });
+});
