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

package/src/column-mapper.ts

@@ -16,16 +16,17 @@ import {
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_CLASS,
+  FIELD_SUBTYPE_ENUM,
   VALIDATOR_SUBTYPE_REQUIRED,
   VALIDATOR_SUBTYPE_LENGTH,
   FIELD_ATTR_MAX_LENGTH,
   FIELD_ATTR_REQUIRED,
-  FIELD_ATTR_DB_COLUMN,
   FIELD_ATTR_UNIQUE,
   FIELD_ATTR_DEFAULT,
   VALIDATOR_ATTR_MAX,
 } from "@metaobjectsdev/metadata";
 import { columnNameFromField } from "./naming.js";
+import { enumValues } from "./enum-meta.js";
 import type { Dialect, ColumnNamingStrategy } from "./metaobjects-config.js";
 
 export type { Dialect };
@@ -75,7 +76,7 @@ function canonicalizeSqlExpr(value: string): string {
 export interface ColumnSpec {
   /** Drizzle function name, e.g., "text", "integer", "varchar". */
   fnName: string;
-  /** DB column name (snake_case from field name, or @dbColumn override). */
+  /** DB column name (snake_case from field name, or @column override). */
   dbName: string;
   /** Positional args after dbName (currently always empty; reserved). */
   fnArgs: unknown[];
@@ -89,6 +90,8 @@ export interface ColumnSpec {
   importModule: string;
   /** Optional leading line-comment for the generated column (e.g., type-fallback notice). */
   leadingComment?: string;
+  /** Optional CHECK constraint expression for the column (e.g., `status IN ('A', 'B')`). */
+  checkConstraint?: string;
 }
 
 /** Resolve max length from validator.length child or @maxLength attr.
@@ -117,7 +120,7 @@ export function mapColumnType(
   dialect: Dialect,
   strategy: ColumnNamingStrategy = "snake_case",
 ): ColumnSpec {
-  const dbName = (field.ownAttr(FIELD_ATTR_DB_COLUMN) as string | undefined) ?? columnNameFromField(field.name, strategy);
+  const dbName = field.column ?? columnNameFromField(field.name, strategy);
   const importModule = dialect === "sqlite" ? "drizzle-orm/sqlite-core" : "drizzle-orm/pg-core";
   const subType = field.subType;
   const isArray = field.isArray;
@@ -157,6 +160,7 @@ export function mapColumnType(
         case FIELD_SUBTYPE_TIME:
         case FIELD_SUBTYPE_TIMESTAMP:
         case FIELD_SUBTYPE_STRING:
+        case FIELD_SUBTYPE_ENUM:
         case FIELD_SUBTYPE_CLASS:
         case FIELD_SUBTYPE_OBJECT:
         default:
@@ -206,6 +210,7 @@ export function mapColumnType(
         }
         break;
       }
+      case FIELD_SUBTYPE_ENUM:
       case FIELD_SUBTYPE_CLASS:
       case FIELD_SUBTYPE_OBJECT:
       default:
@@ -262,5 +267,20 @@ export function mapColumnType(
   if (fnOptions !== undefined) result.fnOptions = fnOptions;
   if (defaultExpr !== undefined) result.defaultExpr = defaultExpr;
   if (leadingComment !== undefined) result.leadingComment = leadingComment;
+
+  // Enum fields: emit a CHECK constraint listing the valid member values.
+  if (subType === FIELD_SUBTYPE_ENUM && !isArray) {
+    const values = enumValues(field);
+    if (values !== undefined && values.length > 0) {
+      // Single-quote escaping is belt-and-suspenders: the loader's
+      // ENUM_MEMBER_PATTERN already rejects quote-bearing members (members are
+      // validated to be identifier-safe), so this never fires in practice.
+      const list = values
+        .map((v) => `'${v.replace(/'/g, "''")}'`)
+        .join(", ");
+      result.checkConstraint = `${dbName} IN (${list})`;
+    }
+  }
+
   return result;
 }

package/src/enum-meta.ts

@@ -0,0 +1,26 @@
+// Shared field.enum metadata helpers — consumed by zod-validators.ts,
+// field-meta.ts, inferred-types.ts, and column-mapper.ts so the @values
+// extraction and the z.enum([...]) expression are derived in exactly one place.
+
+import type { MetaField } from "@metaobjectsdev/metadata";
+import { FIELD_ATTR_VALUES } from "@metaobjectsdev/metadata";
+
+/**
+ * Effective enum member values (`@values`) for a field, as strings.
+ * Returns undefined when the field declares no `@values` array — callers then
+ * fall back to the untyped `z.string()` / `text` representation.
+ *
+ * `attr()` already returns the effective (own-winning-else-inherited) value, so
+ * a field that inherits `@values` from an abstract `field.enum` super resolves
+ * here too.
+ */
+export function enumValues(field: MetaField): string[] | undefined {
+  const values = field.attr(FIELD_ATTR_VALUES);
+  if (!Array.isArray(values)) return undefined;
+  return values.map((v) => String(v));
+}
+
+/** Build the Zod expression for a set of enum members, e.g. `z.enum(["A", "B"])`. */
+export function zodEnumExpr(values: string[]): string {
+  return `z.enum([${values.map((v) => JSON.stringify(v)).join(", ")}])`;
+}

package/src/generators/index.ts

@@ -2,3 +2,4 @@ export { entityFile, type EntityFileOpts } from "./entity-file.js";
 export { queriesFile, type QueriesFileOpts } from "./queries-file.js";
 export { routesFile, type RoutesFileOpts } from "./routes-file.js";
 export { barrel, type BarrelOpts } from "./barrel.js";
+export { mermaidErDiagram, type MermaidErOptions } from "./mermaid-er.js";

package/src/generators/mermaid-er.ts

@@ -0,0 +1,29 @@
+import { oncePerRun, type Generator, type GeneratorFactory } from "../generator.js";
+import { renderMermaidModel } from "../templates/mermaid-er.js";
+
+export interface MermaidErOptions {
+  /** Output path relative to the target's outDir. Defaults to "docs/model.md". */
+  outFile?: string;
+  /** Named output target. */
+  target?: string;
+}
+
+/**
+ * Emit a single Markdown file containing a Mermaid `erDiagram` plus per-entity
+ * prose sections. The renderer walks the loaded root for all entities; the
+ * default outFile is "docs/model.md".
+ */
+export const mermaidErDiagram = function mermaidErDiagram(
+  opts?: MermaidErOptions,
+): Generator {
+  const outFile = opts?.outFile ?? "docs/model.md";
+  const generator: Generator = {
+    name: "mermaid-er-diagram",
+    generate: oncePerRun((_entities, ctx) => ({
+      path: outFile,
+      content: renderMermaidModel(ctx.loadedRoot),
+    })),
+  };
+  if (opts?.target) generator.target = opts.target;
+  return generator;
+} as GeneratorFactory<MermaidErOptions>;

package/src/index.ts

@@ -43,3 +43,5 @@ export type { ExtractContext } from "./projection/extract-view-spec.js";
 export { emitViewDdl } from "./projection/view-ddl-emit.js";
 export type { EmitOptions as ViewDdlEmitOptions } from "./projection/view-ddl-emit.js";
 export type { JoinNode, JoinTree, SelectColumn, SelectSpec, ViewSpec } from "./projection/view-spec.js";
+// Prompt construction (FR-004): typed payload + render-handle codegen.
+export { generatePayloadInterfaces, generateRenderHandle } from "./payload-codegen.js";

package/src/naming.ts

@@ -35,6 +35,13 @@ export function toCamelCase(s: string): string {
   return s.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
 }
 
+/**
+ * Capitalize the first character of a string (camelCase → PascalCase).
+ */
+export function toPascalCase(s: string): string {
+  return s.length > 0 ? s[0]!.toUpperCase() + s.slice(1) : s;
+}
+
 /**
  * Simple English pluralization. Documented imperfection per design §13 #1:
  * irregular plurals (Person → Persons, not People) are not handled.

package/src/payload-codegen.ts

@@ -0,0 +1,106 @@
+// Payload-type + render-handle codegen for prompt construction (FR-004 Plan #3, B).
+//
+// Emits the TYPED PAYLOAD as a language-idiomatic type (a TS `interface` here;
+// a record/POJO when this ports to Java) and a typed render handle. Types only —
+// no class, no runtime ValueObject; the render engine consumes a plain object,
+// and structural typing gives the caller-side compile-time guarantee.
+//
+// NOTE (slice): the field→TS-type map is local here; the production generator
+// should reuse codegen-ts's canonical field mapping + ts-poet emit + the
+// Generator/runner integration. Assembler (RDB materialization + host overlay)
+// is out of scope — this only emits the contract.
+
+import {
+  type MetaData,
+  TYPE_OBJECT,
+  TYPE_FIELD,
+  TYPE_TEMPLATE,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_ATTR_OBJECT_REF,
+  TEMPLATE_ATTR_PAYLOAD_REF,
+  TEMPLATE_ATTR_TEXT_REF,
+  TEMPLATE_ATTR_FORMAT,
+} from "@metaobjectsdev/metadata";
+
+const SCALAR_TS: Record<string, string> = {
+  string: "string",
+  class: "string",
+  int: "number",
+  short: "number",
+  byte: "number",
+  long: "number",
+  double: "number",
+  float: "number",
+  decimal: "number",
+  currency: "number",
+  boolean: "boolean",
+  date: "string",
+  time: "string",
+  timestamp: "string",
+};
+
+function findObject(root: MetaData, name: string): MetaData | undefined {
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+}
+
+function fieldTsType(field: MetaData): { type: string; refVo?: string } {
+  if (field.subType === FIELD_SUBTYPE_OBJECT) {
+    const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+    const refName = typeof ref === "string" ? ref : "unknown";
+    // isArray is a structural property on MetaData, not an attr.
+    const isArray = field.isArray;
+    const result: { type: string; refVo?: string } = {
+      type: isArray ? `${refName}[]` : refName,
+    };
+    if (typeof ref === "string") result.refVo = ref;
+    return result;
+  }
+  return { type: SCALAR_TS[field.subType] ?? "unknown" };
+}
+
+function emitInterface(root: MetaData, voName: string, emitted: Set<string>, out: string[]): void {
+  if (emitted.has(voName)) return;
+  const vo = findObject(root, voName);
+  if (!vo) return;
+  emitted.add(voName);
+  const lines: string[] = [`export interface ${voName} {`];
+  const refs: string[] = [];
+  for (const f of vo.children().filter((c) => c.type === TYPE_FIELD)) {
+    const { type, refVo } = fieldTsType(f);
+    lines.push(`  ${f.name}: ${type};`);
+    if (refVo) refs.push(refVo);
+  }
+  lines.push("}");
+  out.push(lines.join("\n"));
+  for (const r of refs) emitInterface(root, r, emitted, out);
+}
+
+/** Emit the payload `interface` (+ nested element interfaces) for an object.value view-object. */
+export function generatePayloadInterfaces(root: MetaData, voName: string): string {
+  const out: string[] = [];
+  emitInterface(root, voName, new Set<string>(), out);
+  return out.join("\n\n") + "\n";
+}
+
+function pascal(s: string): string {
+  return s.length > 0 ? s[0]!.toUpperCase() + s.slice(1) : s;
+}
+
+/** Emit a typed render handle binding a template's @textRef + @format and typing its payload. */
+export function generateRenderHandle(root: MetaData, templateName: string): string {
+  const tmpl = root.ownChildren().find((c) => c.type === TYPE_TEMPLATE && c.name === templateName);
+  if (!tmpl) throw new Error(`template "${templateName}" not found`);
+  const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  const textRef = tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF);
+  const format = (tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text";
+  const fn = `render${pascal(templateName)}`;
+  return [
+    `import { render, type Provider } from "@metaobjectsdev/render";`,
+    `import type { ${payloadRef} } from "./payloads.js";`,
+    ``,
+    `export function ${fn}(payload: ${payloadRef}, provider: Provider): string {`,
+    `  return render({ ref: ${JSON.stringify(textRef)}, payload, format: ${JSON.stringify(format)}, provider });`,
+    `}`,
+    ``,
+  ].join("\n");
+}

package/src/projection/extract-view-spec.ts

@@ -2,9 +2,7 @@ import {
   TYPE_FIELD,
   TYPE_ORIGIN,
   TYPE_RELATIONSHIP,
-  TYPE_SOURCE,
-  SOURCE_SUBTYPE_DB_VIEW,
-  SOURCE_DB_VIEW_ATTR_NAME,
+  MetaSource,
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
   ORIGIN_PASSTHROUGH_ATTR_FROM,
@@ -15,7 +13,7 @@ import {
   RELATIONSHIP_ATTR_OBJECT_REF,
   RELATIONSHIP_ATTR_CARDINALITY,
   CARDINALITY_ONE,
-  FIELD_ATTR_DB_COLUMN,
+  FIELD_ATTR_COLUMN,
   findReferenceBetween,
   type AggregateFunction,
 } from "@metaobjectsdev/metadata";
@@ -48,10 +46,11 @@ function findRelationship(obj: MetaData, name: string): MetaData | undefined {
 }
 
 function viewName(projection: MetaObject, ctx: ExtractContext): string {
-  const dbView = projection.ownChildren().find(
-    (c) => c.type === TYPE_SOURCE && c.subType === SOURCE_SUBTYPE_DB_VIEW,
+  // The read-only source carries the physical view name (@table).
+  const viewSource = projection.ownChildren().find(
+    (c): c is MetaSource => c instanceof MetaSource && c.isReadOnly(),
   );
-  const explicit = dbView?.ownAttr(SOURCE_DB_VIEW_ATTR_NAME) as string | undefined;
+  const explicit = viewSource?.tableName;
   return explicit ?? viewNameFromProjection(projection.name, ctx.columnNamingStrategy);
 }
 
@@ -81,8 +80,9 @@ function sourceColumnNameFor(
   entityField: MetaData,
   ctx: ExtractContext,
 ): string {
-  const explicit = entityField.ownAttr(FIELD_ATTR_DB_COLUMN) as string | undefined;
-  return explicit ?? columnNameFromField(entityField.name, ctx.columnNamingStrategy);
+  const col = entityField.ownAttr(FIELD_ATTR_COLUMN);
+  if (typeof col === "string" && col !== "") return col;
+  return columnNameFromField(entityField.name, ctx.columnNamingStrategy);
 }
 
 function shortAliasFor(entityName: string, used: Set<string>): string {

package/src/projection/projection-detector.ts

@@ -1,26 +1,22 @@
-import {
-  TYPE_SOURCE,
-  SOURCE_SUBTYPE_DB_TABLE,
-  SOURCE_SUBTYPE_DB_VIEW,
-} from "@metaobjectsdev/metadata";
+import { MetaSource } from "@metaobjectsdev/metadata";
 import type { MetaData } from "@metaobjectsdev/metadata";
 
-function hasSource(entity: MetaData, subType: string): boolean {
+function hasReadOnlyKindSource(entity: MetaData): boolean {
   return entity.ownChildren().some(
-    (c) => c.type === TYPE_SOURCE && c.subType === subType,
+    (c) => c instanceof MetaSource && c.isReadOnly(),
   );
 }
 
-export function isProjection(entity: MetaData): boolean {
-  return (
-    hasSource(entity, SOURCE_SUBTYPE_DB_VIEW) &&
-    !hasSource(entity, SOURCE_SUBTYPE_DB_TABLE)
+function hasWritableKindSource(entity: MetaData): boolean {
+  return entity.ownChildren().some(
+    (c) => c instanceof MetaSource && c.isWritable(),
   );
 }
 
+export function isProjection(entity: MetaData): boolean {
+  return hasReadOnlyKindSource(entity) && !hasWritableKindSource(entity);
+}
+
 export function isWriteThrough(entity: MetaData): boolean {
-  return (
-    hasSource(entity, SOURCE_SUBTYPE_DB_VIEW) &&
-    hasSource(entity, SOURCE_SUBTYPE_DB_TABLE)
-  );
+  return hasReadOnlyKindSource(entity) && hasWritableKindSource(entity);
 }

package/src/templates/drizzle-schema.ts

@@ -12,9 +12,10 @@ import {
 } from "@metaobjectsdev/metadata";
 import { type RenderContext } from "../render-context.js";
 import { crossEntitySpecifier } from "../import-path.js";
-import { mapColumnType } from "../column-mapper.js";
+import { mapColumnType, type ColumnSpec } from "../column-mapper.js";
 import { tableNameFromEntity, variableNameFromEntity, columnNameFromField } from "../naming.js";
 import { renderRelationsBlock } from "./relations-block.js";
+import { renderDocsFor } from "./jsdoc.js";
 
 /**
  * Render the Drizzle table definition for one entity, including:
@@ -62,11 +63,24 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   }
 
   const columnLines: Code[] = [];
+  // Collect CHECK constraints for enum columns; emitted as table-level check() callbacks.
+  const checkConstraints: Array<{ name: string; expr: string }> = [];
   for (const child of obj.fields()) {
     const isPk = pkFieldNames.has(child.name);
     const isUnique = uniqueFieldNames.has(child.name) && !isPk;
     const fkInfo = fkMap.get(child.name);
-    columnLines.push(renderColumn(child, ctx, isPk, pkGeneration, fkInfo, isComposite, isUnique, obj.package));
+    // Compute the column spec once per field and reuse it for both the column
+    // line and the CHECK collection.
+    const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy);
+    const fieldDocs = renderDocsFor(child);
+    const columnLine = renderColumn(spec, child, ctx, isPk, pkGeneration, fkInfo, isComposite, isUnique, obj.package);
+    columnLines.push(fieldDocs ? code`  ${fieldDocs}\n${columnLine}` : columnLine);
+    if (spec.checkConstraint !== undefined) {
+      checkConstraints.push({
+        name: `chk_${tableName}_${spec.dbName}`,
+        expr: spec.checkConstraint,
+      });
+    }
   }
 
   // Build all table callback entries
@@ -93,6 +107,13 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
     callbackEntries.push(code`${indexSym}(${JSON.stringify(indexName)}).on(${cols})`);
   }
 
+  // Emit table-level CHECK constraints for enum fields.
+  for (const { name, expr } of checkConstraints) {
+    const checkSym = imp(`check@${importModule}`);
+    const sqlSym = imp("sql@drizzle-orm");
+    callbackEntries.push(code`${checkSym}(${JSON.stringify(name)}, ${sqlSym}\`${expr}\`)`);
+  }
+
   let tableBlock: Code;
   if (callbackEntries.length > 0) {
     tableBlock = code`
@@ -174,6 +195,7 @@ function inlineObjectLiteral(obj: Record<string, unknown>): string {
 
 /** Render one column line (field name + Drizzle column expression). */
 function renderColumn(
+  spec: ColumnSpec,
   field: MetaField,
   ctx: RenderContext,
   isPk: boolean,
@@ -183,7 +205,6 @@ function renderColumn(
   isUnique: boolean = false,
   entityPackage: string | undefined = undefined,
 ): Code {
-  const spec = mapColumnType(field, ctx.dialect, ctx.columnNamingStrategy);
   const fnSym = imp(`${spec.fnName}@${spec.importModule}`);
 
   const dbNameLit = JSON.stringify(spec.dbName);

package/src/templates/entity-file.ts

@@ -9,7 +9,7 @@ import { joinCode, type Code } from "ts-poet";
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import type { RenderContext } from "../render-context.js";
 import { renderDrizzleSchema } from "./drizzle-schema.js";
-import { renderInferredTypes } from "./inferred-types.js";
+import { renderInferredTypes, renderEnumTypeAliases } from "./inferred-types.js";
 import { renderZodValidators } from "./zod-validators.js";
 import { renderEntityConstants } from "./entity-constants.js";
 import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
@@ -20,6 +20,8 @@ import { renderProjectionDecl } from "./projection-decl.js";
 
 export function renderEntityFile(entity: MetaObject, ctx: RenderContext): string {
   // --- Projection path (read-only: view-backed entity with no table source) ---
+  // Projections intentionally get the z.enum() validator but NOT a named enum
+  // type alias — emitting aliases here is a deliberate v1 scope decision.
   if (isProjection(entity)) {
     return renderProjectionDecl(entity, ctx.loadedRoot, {
       columnNamingStrategy: ctx.columnNamingStrategy,
@@ -29,9 +31,11 @@ export function renderEntityFile(entity: MetaObject, ctx: RenderContext): string
   }
 
   // --- Vanilla / write-through entity path ---
+  const enumAliases = renderEnumTypeAliases(entity);
   const sections: Code[] = [
     renderDrizzleSchema(entity, ctx),
     renderInferredTypes(entity),
+    ...(enumAliases !== null ? [enumAliases] : []),
     renderZodValidators(entity),
     renderEntityConstants(entity, ctx.apiPrefix),
     renderFilterAllowlist(entity),

package/src/templates/field-meta.ts

@@ -18,6 +18,7 @@ import {
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_CURRENCY,
+  FIELD_SUBTYPE_ENUM,
   VIEW_SUBTYPE_TEXT,
   VIEW_SUBTYPE_DATE,
   VIEW_SUBTYPE_NUMBER,
@@ -28,6 +29,7 @@ import {
   VIEW_CURRENCY_ATTR_LOCALE,
   VIEW_CURRENCY_ATTR_LOCALE_DEFAULT,
 } from "@metaobjectsdev/metadata";
+import { enumValues, zodEnumExpr } from "../enum-meta.js";
 
 // ---------------------------------------------------------------------------
 // inferViewKind
@@ -96,6 +98,10 @@ export function zodTypeFor(field: MetaField): string {
     case FIELD_SUBTYPE_FLOAT:
     case FIELD_SUBTYPE_DECIMAL:
       return "z.number()";
+    case FIELD_SUBTYPE_ENUM: {
+      const values = enumValues(field);
+      return values !== undefined ? zodEnumExpr(values) : "z.string()";
+    }
     default:
       return "z.unknown()";
   }

package/src/templates/inferred-types.ts

@@ -1,16 +1,55 @@
-// Inferred types template — emits Drizzle's InferSelectModel / InferInsertModel type aliases.
+// Inferred types template — emits Drizzle's InferSelectModel / InferInsertModel type aliases,
+// plus named union types for field.enum fields.
 
 import { code, imp, type Code } from "ts-poet";
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { variableNameFromEntity } from "../naming.js";
+import { FIELD_SUBTYPE_ENUM } from "@metaobjectsdev/metadata";
+import { variableNameFromEntity, toPascalCase } from "../naming.js";
+import { enumValues } from "../enum-meta.js";
+import { renderDocsFor } from "./jsdoc.js";
 
 export function renderInferredTypes(entity: MetaObject): Code {
   const varName = variableNameFromEntity(entity.name);
   const selectSym = imp("InferSelectModel@drizzle-orm");
   const insertSym = imp("InferInsertModel@drizzle-orm");
+  const docs = renderDocsFor(entity);
+  const docsPrefix = docs ? `${docs}\n` : "";
   return code`
-export type ${entity.name} = ${selectSym}<typeof ${varName}>;
+${docsPrefix}export type ${entity.name} = ${selectSym}<typeof ${varName}>;
 export type ${entity.name}Insert = ${insertSym}<typeof ${varName}>;
 export type ${entity.name}Update = Partial<${entity.name}Insert>;
 `;
 }
+
+/**
+ * Emit one `export type <Name> = "A" | "B";` line per field.enum field on the entity.
+ * - If the field extends an abstract field.enum (super), use the super field's PascalCase name.
+ * - Otherwise use `<Entity><FieldPascal>` for inline enums.
+ * Returns null if the entity has no enum fields.
+ */
+export function renderEnumTypeAliases(entity: MetaObject): Code | null {
+  // De-duplicate by type-alias name — multiple fields can extend the same abstract enum.
+  const seen = new Set<string>();
+  const lines: string[] = [];
+
+  for (const field of entity.fields()) {
+    if (field.subType !== FIELD_SUBTYPE_ENUM) continue;
+
+    const values = enumValues(field);
+    if (values === undefined) continue;
+
+    // Derive the type-alias name.
+    const superField = field.resolveSuper();
+    const typeName = superField !== undefined
+      ? toPascalCase(superField.name)
+      : `${entity.name}${toPascalCase(field.name)}`;
+
+    if (seen.has(typeName)) continue;
+    seen.add(typeName);
+
+    const union = values.map((v) => JSON.stringify(v)).join(" | ");
+    lines.push(`export type ${typeName} = ${union};`);
+  }
+
+  return lines.length > 0 ? code`${lines.join("\n")}` : null;
+}

package/src/templates/jsdoc.ts

@@ -0,0 +1,88 @@
+import {
+  DOC_ATTR_ALIASES,
+  DOC_ATTR_DEPRECATED,
+  DOC_ATTR_DESCRIPTION,
+  DOC_ATTR_REPLACED_BY,
+  DOC_ATTR_SEE_ALSO,
+  DOC_ATTR_TITLE,
+} from "@metaobjectsdev/metadata";
+
+export interface DocAttrs {
+  description?: string;
+  title?: string;
+  /** Internal-only; NEVER emitted by this helper (D5 contract). */
+  notes?: string;
+  deprecated?: string;
+  replacedBy?: string;
+  seeAlso?: string[];
+  aliases?: string[];
+}
+
+/**
+ * Render the seven doc common attrs as a JSDoc block. Returns "" if no
+ * relevant attrs are set. `notes` is intentionally NEVER emitted — it is
+ * the internal-only rationale slot per the Documentation Provider design
+ * (D5).
+ */
+export function renderJsDocBlock(attrs: DocAttrs): string {
+  const bodyLines: string[] = [];
+
+  // Description (primary text), falling back to title-only if no description.
+  if (attrs.description) {
+    bodyLines.push(...attrs.description.split("\n"));
+  } else if (attrs.title) {
+    bodyLines.push(attrs.title);
+  }
+
+  // Tags
+  const tagLines: string[] = [];
+  if (attrs.deprecated !== undefined) {
+    const replaced = attrs.replacedBy ? ` Replaced by ${attrs.replacedBy}.` : "";
+    tagLines.push(`@deprecated ${attrs.deprecated}${replaced}`);
+  }
+  for (const url of attrs.seeAlso ?? []) tagLines.push(`@see ${url}`);
+  for (const alias of attrs.aliases ?? []) tagLines.push(`@alias ${alias}`);
+
+  if (bodyLines.length === 0 && tagLines.length === 0) return "";
+
+  // One-line shorthand: single body line + no tags
+  if (bodyLines.length === 1 && tagLines.length === 0) {
+    return `/** ${bodyLines[0]} */`;
+  }
+
+  const out: string[] = ["/**"];
+  for (const line of bodyLines) out.push(line === "" ? " *" : ` * ${line}`);
+  if (bodyLines.length > 0 && tagLines.length > 0) out.push(" *");
+  for (const line of tagLines) out.push(` * ${line}`);
+  out.push(" */");
+  return out.join("\n");
+}
+
+/** Read the seven doc attrs from a MetaData node's `.attrs()` (effective). */
+export function readDocAttrs(node: { attr: (n: string) => unknown }): DocAttrs {
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" ? v : undefined;
+  const arr = (v: unknown): string[] | undefined =>
+    Array.isArray(v) && v.every((x) => typeof x === "string") ? (v as string[]) : undefined;
+
+  const description = str(node.attr(DOC_ATTR_DESCRIPTION));
+  const title = str(node.attr(DOC_ATTR_TITLE));
+  const deprecated = str(node.attr(DOC_ATTR_DEPRECATED));
+  const replacedBy = str(node.attr(DOC_ATTR_REPLACED_BY));
+  const seeAlso = arr(node.attr(DOC_ATTR_SEE_ALSO));
+  const aliases = arr(node.attr(DOC_ATTR_ALIASES));
+  // notes intentionally NOT read here — codegen consumers should never receive it
+  return {
+    ...(description !== undefined && { description }),
+    ...(title !== undefined && { title }),
+    ...(deprecated !== undefined && { deprecated }),
+    ...(replacedBy !== undefined && { replacedBy }),
+    ...(seeAlso !== undefined && { seeAlso }),
+    ...(aliases !== undefined && { aliases }),
+  };
+}
+
+/** Convenience: `renderJsDocBlock(readDocAttrs(node))`. Returns "" if no doc attrs. */
+export function renderDocsFor(node: { attr: (n: string) => unknown }): string {
+  return renderJsDocBlock(readDocAttrs(node));
+}