@metaobjectsdev/codegen-ts 0.5.0 → 0.6.0-rc.1

package/src/templates/mermaid-er.ts

@@ -0,0 +1,120 @@
+// Mermaid ER renderer — produces a docs/model.md body with:
+//   1. A top-level ```mermaid erDiagram block of entities + identity.reference relationships.
+//   2. A per-entity prose section consuming the 6 user-facing doc attrs (notes excluded).
+//
+// D5: the notes attr is NEVER emitted. Per the Documentation Provider design.
+
+import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
+import { DOC_ATTR_DESCRIPTION } from "@metaobjectsdev/metadata";
+import { readDocAttrs } from "./jsdoc.js";
+
+/** Render a docs/model.md body: Mermaid erDiagram + per-entity prose. Abstract
+ *  entities are excluded — they have no physical table to put in a diagram
+ *  (matches migrate-ts/expected-schema.ts's same filter). */
+export function renderMermaidModel(root: MetaRoot): string {
+  const entities = root
+    .objects()
+    .filter((o) => o.isEntity() && !o.isAbstract);
+  const parts: string[] = [];
+
+  parts.push("# Data Model");
+  parts.push("");
+  parts.push("```mermaid");
+  parts.push("erDiagram");
+  for (const line of renderRelationships(entities)) parts.push(`    ${line}`);
+  for (const entity of entities) {
+    parts.push("");
+    for (const line of renderEntityBlock(entity)) parts.push(`    ${line}`);
+  }
+  parts.push("```");
+  parts.push("");
+
+  for (const entity of entities) {
+    for (const line of renderEntityProse(entity)) parts.push(line);
+    parts.push("");
+  }
+
+  return parts.join("\n");
+}
+
+function renderRelationships(entities: MetaObject[]): string[] {
+  const lines: string[] = [];
+  for (const entity of entities) {
+    for (const ref of entity.referenceIdentities()) {
+      const refTo = ref.targetEntity;
+      if (typeof refTo !== "string" || refTo.length === 0) continue;
+      // One-to-many by default — a foreign key on `entity` references one row on `refTo`.
+      lines.push(`${refTo} ||--o{ ${entity.name} : "references"`);
+    }
+  }
+  return lines;
+}
+
+function renderEntityBlock(entity: MetaObject): string[] {
+  const out: string[] = [`${entity.name} {`];
+  const pkFields = pkFieldNames(entity);
+  const fkFields = fkFieldNames(entity);
+  for (const field of entity.fields()) {
+    let marker = "";
+    if (pkFields.has(field.name)) marker = " PK";
+    else if (fkFields.has(field.name)) marker = " FK";
+    const desc = field.attr(DOC_ATTR_DESCRIPTION);
+    const comment =
+      typeof desc === "string" && desc.length > 0
+        ? ` "${escapeMermaidComment(desc.split("\n")[0]!)}"`
+        : "";
+    out.push(`    ${field.subType} ${field.name}${marker}${comment}`);
+  }
+  out.push("}");
+  return out;
+}
+
+function pkFieldNames(entity: MetaObject): Set<string> {
+  const out = new Set<string>();
+  const primary = entity.primaryIdentity();
+  if (primary) {
+    for (const f of primary.fields) out.add(f);
+  }
+  return out;
+}
+
+function fkFieldNames(entity: MetaObject): Set<string> {
+  const out = new Set<string>();
+  for (const ref of entity.referenceIdentities()) {
+    for (const f of ref.fields) out.add(f);
+  }
+  return out;
+}
+
+function escapeMermaidComment(s: string): string {
+  return s.replace(/"/g, '\\"');
+}
+
+function renderEntityProse(entity: MetaObject): string[] {
+  // readDocAttrs handles the typeof-string / Array.isArray guards and intentionally
+  // omits `notes` (D5 contract — never read, never emitted).
+  const docs = readDocAttrs(entity);
+  const out: string[] = [];
+  out.push(`## ${docs.title ?? entity.name}`);
+  if (docs.description) {
+    out.push("");
+    out.push(docs.description);
+  }
+  if (docs.aliases && docs.aliases.length > 0) {
+    out.push("");
+    out.push(`*Aliases:* ${docs.aliases.join(", ")}`);
+  }
+  // Truthy check (not !== undefined): an empty deprecated value is the same
+  // signal as none (no reason ⇒ nothing meaningful to render in the prose callout).
+  if (docs.deprecated) {
+    const replaced = docs.replacedBy ? ` Replaced by **${docs.replacedBy}**.` : "";
+    out.push("");
+    out.push(`> ⚠️ **Deprecated:** ${docs.deprecated}${replaced}`);
+  }
+  if (docs.seeAlso && docs.seeAlso.length > 0) {
+    out.push("");
+    out.push("**See also:**");
+    for (const url of docs.seeAlso) out.push(`- <${url}>`);
+  }
+  return out;
+}

package/src/templates/zod-validators.ts

@@ -9,6 +9,7 @@ import {
   FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_CURRENCY,
   FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT,
   FIELD_SUBTYPE_DATE, FIELD_SUBTYPE_TIME, FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_ENUM,
   VALIDATOR_SUBTYPE_REQUIRED, VALIDATOR_SUBTYPE_LENGTH, VALIDATOR_SUBTYPE_REGEX,
   IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION,
   FIELD_ATTR_REQUIRED, FIELD_ATTR_MAX_LENGTH, FIELD_ATTR_DEFAULT,
@@ -16,6 +17,8 @@ import {
   VALIDATOR_ATTR_MAX, VALIDATOR_ATTR_MIN, VALIDATOR_ATTR_PATTERN,
   GENERATION_INCREMENT, GENERATION_UUID,
 } from "@metaobjectsdev/metadata";
+import { enumValues, zodEnumExpr } from "../enum-meta.js";
+import { renderDocsFor } from "./jsdoc.js";
 
 export function renderZodValidators(obj: MetaObject): Code {
   const z = imp("z@zod");
@@ -66,12 +69,15 @@ export function renderZodValidators(obj: MetaObject): Code {
   const insertSchemaName = `${obj.name}InsertSchema`;
   const updateSchemaName = `${obj.name}UpdateSchema`;
 
+  const docs = renderDocsFor(obj);
+  const docsPrefix = docs ? `${docs}\n` : "";
+
   return code`
-export const ${insertSchemaName} = ${z}.object({
+${docsPrefix}export const ${insertSchemaName} = ${z}.object({
 ${insertFieldLines.join(",\n")}
 });
 
-export const ${updateSchemaName} = ${z}.object({
+${docsPrefix}export const ${updateSchemaName} = ${z}.object({
 ${updateFieldLines.join(",\n")}
 });
 `;
@@ -97,6 +103,11 @@ function zodFieldExpr(field: MetaField): string {
     case FIELD_SUBTYPE_TIMESTAMP:
       base = "z.string()";
       break;
+    case FIELD_SUBTYPE_ENUM: {
+      const values = enumValues(field);
+      base = values !== undefined ? zodEnumExpr(values) : "z.string()";
+      break;
+    }
     case FIELD_SUBTYPE_STRING:
     default:
       base = "z.string()";