@metaobjectsdev/codegen-ts 0.24.5 → 1.0.0-rc.1

package/src/templates/entity-constants.ts

@@ -12,9 +12,7 @@
 //       name:        "email",
 //       label:       "Email Address",      // from @label on the view, falls back to humanized field name
 //       view:        "text",                // MetaView subtype
-//       htmlType:    "email",               // optional; only when it maps to a real HTML input type
-//       placeholder: "you@example.com",     // optional; only when @placeholder is set on the view
-//       helpText:    "We never share this.", // optional; only when @helpText is set
+//       htmlType:    "email",               // optional; only when the view maps to a real HTML input type
 //       rules: {                             // optional; derived from validator children
 //         required:  "Email is required",
 //         maxLength: { value: 255, message: "Must be 255 characters or fewer" },
@@ -28,205 +26,110 @@
 // per-attribute access (placeholder, rules, etc.) by hand — the helper
 // picks them up from this object automatically.
 
-import { code, type Code } from "ts-poet";
-import type { MetaData } from "@metaobjectsdev/metadata";
-import { MetaObject, MetaField } from "@metaobjectsdev/metadata";
+import { code, joinCode, type Code } from "ts-poet";
+import { MetaObject } from "@metaobjectsdev/metadata";
+import { resolveTableName } from "@metaobjectsdev/metadata";
+import { physicalNameExpr } from "../names.js";
 import {
-  VIEW_SUBTYPE_TEXT,
-  VIEW_SUBTYPE_TEXTAREA,
-  VIEW_SUBTYPE_NUMBER,
-  VIEW_SUBTYPE_CHECKBOX,
-  VIEW_SUBTYPE_DATE,
-  VIEW_SUBTYPE_PASSWORD,
-  VIEW_SUBTYPE_HIDDEN,
-  VIEW_SUBTYPE_DROPDOWN,
-  VIEW_SUBTYPE_RADIO,
-  VALIDATOR_SUBTYPE_REQUIRED,
-  VALIDATOR_SUBTYPE_LENGTH,
-  VALIDATOR_SUBTYPE_REGEX,
-  VALIDATOR_ATTR_MIN,
-  VALIDATOR_ATTR_MAX,
-  VALIDATOR_ATTR_PATTERN,
-  FIELD_ATTR_MAX_LENGTH,
-  FIELD_ATTR_REQUIRED,
-} from "@metaobjectsdev/metadata";
-import { resolveTableName, pluralize, toSnakeCase } from "@metaobjectsdev/metadata";
-import { inferViewKind, currencyMetaFor, labelFor } from "./field-meta.js";
+  buildEntityUiDescriptor,
+  resourcePath,
+  type UiFieldDescriptor,
+  type UiRule,
+} from "./entity-ui-descriptor.js";
 
-/** Convert a camelCase or PascalCase field name to a human-friendly label. */
-function humanize(s: string): string {
-  return s
-    .replace(/([a-z])([A-Z])/g, "$1 $2")
-    .replace(/_/g, " ")
-    .replace(/\b\w/g, (c) => c.toUpperCase())
-    .trim();
-}
-
-/**
- * REST resource path for an entity. Pluralized + snake_cased + lowercased.
- *   "Subscriber" → "/subscribers"
- *   "WorkoutEvent" → "/workout_events"
- */
-export function resourcePath(entity: MetaData): string {
-  // ADR-0039: resolving — a concrete entity may inherit @routePath via extends.
-  const overrideAttr = entity.attr("routePath");
-  if (typeof overrideAttr === "string" && overrideAttr.length > 0) {
-    return overrideAttr.startsWith("/") ? overrideAttr : `/${overrideAttr}`;
-  }
-  return `/${pluralize(toSnakeCase(entity.name))}`;
-}
-
-/** Resolve the view subtype: explicit `view` child (own or inherited) wins, else inferred from field subType. */
-function resolveView(field: MetaField): { view: string; viewNode?: MetaData } {
-  const viewChild = field.views()[0];
-  if (viewChild) {
-    return { view: viewChild.subType, viewNode: viewChild };
-  }
-  return { view: inferViewKind(field) };
-}
-
-/**
- * Map a MetaView subtype to a real HTML <input type=...> value. Returns
- * undefined for views that don't map to <input> at all (textarea, dropdown,
- * radio) — consumers render the right element type themselves.
- */
-function htmlTypeFromView(view: string, override?: string): string | undefined {
-  if (typeof override === "string" && override.length > 0) return override;
-  switch (view) {
-    case VIEW_SUBTYPE_TEXT:
-      return "text";
-    case VIEW_SUBTYPE_NUMBER:
-      return "number";
-    case VIEW_SUBTYPE_DATE:
-      return "date";
-    case VIEW_SUBTYPE_PASSWORD:
-      return "password";
-    case VIEW_SUBTYPE_CHECKBOX:
-      return "checkbox";
-    case VIEW_SUBTYPE_HIDDEN:
-      return "hidden";
-    case VIEW_SUBTYPE_RADIO:
-      return "radio";
-    case "month":
-      return "month";
-    case "email":
-      return "email";
-    case VIEW_SUBTYPE_TEXTAREA:
-    case VIEW_SUBTYPE_DROPDOWN:
-      return undefined;
-    default:
-      return undefined;
-  }
-}
+// `resourcePath` moved to entity-ui-descriptor.ts with the rest of the form derivation.
+// Re-exported here because it is part of this module's published surface (the package
+// barrel re-exports it from this path, and api-model.ts imports it from here).
+export { resourcePath };
 
 /**
- * Build RHF rules JSON-ish code from a field's validator children plus
- * field-level attrs (`@required`, `@maxLength`). Returns the code string
- * (e.g. `{ required: "X", maxLength: { value: 255, message: "..." } }`)
- * or undefined when there are no rules to emit.
+ * Render one rule entry as the RHF-shaped code fragment the descriptor emits.
+ *
+ * Order is the descriptor's, which is declaration order — see the ordering note in
+ * entity-ui-descriptor.ts for why that is not incidental.
  */
-function renderFieldRules(field: MetaField): string | undefined {
-  const ruleParts: string[] = [];
-
-  let hasRequired = false;
-  let hasMaxLength = false;
-
-  // ADR-0039: resolving — a validator may inherit its config attrs (@min/@max/
-  // @pattern/@message/…) via extends.
-  for (const child of field.validators()) {
-    if (child.subType === VALIDATOR_SUBTYPE_REQUIRED) {
-      const msg = (child.attr("message") as string | undefined) ?? `${humanize(field.name)} is required`;
-      ruleParts.push(`required: ${JSON.stringify(msg)}`);
-      hasRequired = true;
-    } else if (child.subType === VALIDATOR_SUBTYPE_LENGTH) {
-      const min = child.attr(VALIDATOR_ATTR_MIN);
-      const max = child.attr(VALIDATOR_ATTR_MAX);
-      if (typeof min === "number") {
-        const msg = (child.attr("minMessage") as string | undefined) ?? `Must be at least ${min} characters`;
-        ruleParts.push(`minLength: { value: ${min}, message: ${JSON.stringify(msg)} }`);
-      }
-      if (typeof max === "number") {
-        const msg = (child.attr("maxMessage") as string | undefined) ?? `Must be ${max} characters or fewer`;
-        ruleParts.push(`maxLength: { value: ${max}, message: ${JSON.stringify(msg)} }`);
-        hasMaxLength = true;
-      }
-    } else if (child.subType === VALIDATOR_SUBTYPE_REGEX) {
-      const pattern = child.attr(VALIDATOR_ATTR_PATTERN);
-      if (typeof pattern === "string") {
-        const msg = (child.attr("message") as string | undefined) ?? "Invalid format";
-        // Emit as RegExp literal /.../ — `as const` preserves the value-ref.
-        // Forward-slash inside the pattern is escaped so the literal closes correctly.
-        const safe = pattern.replace(/\\/g, "\\\\").replace(/\//g, "\\/");
-        ruleParts.push(`pattern: { value: /${safe}/, message: ${JSON.stringify(msg)} }`);
-      }
+function renderRule(r: UiRule): string {
+  switch (r.kind) {
+    case "required":
+      return `required: ${JSON.stringify(r.message)}`;
+    case "minLength":
+      return `minLength: { value: ${r.value}, message: ${JSON.stringify(r.message)} }`;
+    case "maxLength":
+      return `maxLength: { value: ${r.value}, message: ${JSON.stringify(r.message)} }`;
+    case "pattern": {
+      // Emit as a RegExp literal /.../ — `as const` preserves the value-ref. The
+      // descriptor carries the RAW pattern; forward-slash and backslash are escaped
+      // HERE, because closing a TypeScript regex literal is an emission concern.
+      const safe = r.pattern.replace(/\\/g, "\\\\").replace(/\//g, "\\/");
+      return `pattern: { value: /${safe}/, message: ${JSON.stringify(r.message)} }`;
     }
   }
-
-  // Field-level @required attr (if not already covered by validator).
-  if (!hasRequired && field.attr(FIELD_ATTR_REQUIRED) === true) {
-    ruleParts.push(`required: ${JSON.stringify(`${humanize(field.name)} is required`)}`);
-  }
-
-  // Field-level @maxLength attr (if not already covered).
-  const maxLenAttr = field.attr(FIELD_ATTR_MAX_LENGTH);
-  if (!hasMaxLength && typeof maxLenAttr === "number") {
-    ruleParts.push(
-      `maxLength: { value: ${maxLenAttr}, message: ${JSON.stringify(`Must be ${maxLenAttr} characters or fewer`)} }`,
-    );
-  }
-
-  if (ruleParts.length === 0) return undefined;
-  return `{ ${ruleParts.join(", ")} }`;
 }
 
 /** Build one nested field-object entry like `email: { name, label, ... },`. */
-function renderFieldEntry(field: MetaField): string {
-  const { view, viewNode } = resolveView(field);
-  const label = labelFor(field);
-  // ADR-0039: resolving — a view node may inherit @placeholder/@helpText/@htmlType via extends.
-  const placeholder = viewNode?.attr("placeholder") as string | undefined;
-  const helpText = viewNode?.attr("helpText") as string | undefined;
-  const htmlType = htmlTypeFromView(view, viewNode?.attr("htmlType") as string | undefined);
-  const rules = renderFieldRules(field);
-
+function renderFieldEntry(f: UiFieldDescriptor): string {
   const entries: string[] = [
-    `name: ${JSON.stringify(field.name)}`,
-    `label: ${JSON.stringify(label)}`,
-    `view: ${JSON.stringify(view)}`,
+    `name: ${JSON.stringify(f.name)}`,
+    `label: ${JSON.stringify(f.label)}`,
+    `view: ${JSON.stringify(f.view)}`,
   ];
-  if (htmlType !== undefined) entries.push(`htmlType: ${JSON.stringify(htmlType)}`);
-  if (placeholder !== undefined) entries.push(`placeholder: ${JSON.stringify(placeholder)}`);
-  if (helpText !== undefined) entries.push(`helpText: ${JSON.stringify(helpText)}`);
-  if (rules !== undefined) entries.push(`rules: ${rules}`);
+  if (f.htmlType !== undefined) entries.push(`htmlType: ${JSON.stringify(f.htmlType)}`);
+  if (f.rules.length > 0) entries.push(`rules: { ${f.rules.map(renderRule).join(", ")} }`);
 
   // Currency-specific keys: only emitted for currency-subtype fields.
-  const currencyMeta = currencyMetaFor(field);
-  if (currencyMeta !== null) {
-    entries.push(`currency: ${JSON.stringify(currencyMeta.currency)}`);
-    entries.push(`locale: ${JSON.stringify(currencyMeta.locale)}`);
+  if (f.currency !== undefined) {
+    entries.push(`currency: ${JSON.stringify(f.currency.currency)}`);
+    entries.push(`locale: ${JSON.stringify(f.currency.locale)}`);
   }
 
-  return `  ${field.name}: {\n    ${entries.join(",\n    ")},\n  }`;
+  return `  ${f.name}: {\n    ${entries.join(",\n    ")},\n  }`;
 }
 
-export function renderEntityConstants(obj: MetaObject, apiPrefix = ""): Code {
-  const entityName = obj.name;
+export function renderEntityConstants(
+  obj: MetaObject,
+  /**
+   * @deprecated Accepted and IGNORED. The API base URL left the descriptor: generated
+   * client artifacts emit entity-relative paths and the base is supplied once at the
+   * client provider (`baseUrl`), because where the browser sends a request is a
+   * deployment fact rather than something to freeze at `meta gen` time.
+   *
+   * It must STAY in the signature: `src/reference/entity.ts` is copied verbatim into
+   * adopter repos (ADR-0034) and calls this positionally, so removing the parameter
+   * would fail to compile in every ejected copy. Removal is a separate later break.
+   */
+  _apiPrefix = "",
+  // §A6. OPTIONAL, and it must stay optional: `src/reference/entity.ts` is copied
+  // verbatim into adopter repos by ADR-0034 scaffold-and-own and calls this with two
+  // arguments. A required parameter would fail to compile in every ejected copy.
+  names?: { readonly name: string; readonly symbol: Code } | undefined,
+): Code {
+  // ONE derivation of the form surface, shared with the `agent/ui.md` docs page — see
+  // entity-ui-descriptor.ts. The descriptor already walks the RESOLVING fields(), so
+  // inherited fields (from extends:/super:) appear here as they always have.
+  const descriptor = buildEntityUiDescriptor(obj);
+  const entityName = descriptor.entity;
   const tableName = resolveTableName(obj);
-  const path = resourcePath(obj);
-
-  const fieldEntries: string[] = [];
-  // Use fields() so inherited fields (from extends:/super:) appear in constants.
-  for (const child of obj.fields()) {
-    fieldEntries.push(renderFieldEntry(child));
-  }
-
-  const body = [
-    `  $entity: ${JSON.stringify(entityName)}`,
-    `  $table: ${JSON.stringify(tableName)}`,
-    `  $path: ${JSON.stringify(path)}`,
-    `  $apiPrefix: ${JSON.stringify(apiPrefix)}`,
-    ...fieldEntries,
-  ].join(",\n");
+  const path = descriptor.path;
+
+  const fieldEntries: string[] = descriptor.fields.map(renderFieldEntry);
+
+  // A6/B2 — reference the constant whenever the artifact is in the run. No equality
+  // guard: primaryRdbSource (@metaobjectsdev/metadata) refuses any object whose
+  // @role: primary sources disagree on a physical name, and both the constant and the
+  // literal below resolve through it, so a reference here is the single spelling. `physicalNameExpr` accepts
+  // any `{ symbol }`-shaped value, so it works with this function's `{ name, symbol }`
+  // parameter as well as `namesRef`'s own `{ resolved, symbol }`.
+  const tableLine: Code = code`  $table: ${physicalNameExpr(names, tableName, obj)}`;
+
+  const body = joinCode(
+    [
+      code`  $entity: ${JSON.stringify(entityName)}`,
+      tableLine,
+      code`  $path: ${JSON.stringify(path)}`,
+      ...fieldEntries.map((e) => code`${e}`),
+    ],
+    { on: ",\n" },
+  );
 
   return code`
 /**
@@ -234,9 +137,17 @@ export function renderEntityConstants(obj: MetaObject, apiPrefix = ""): Code {
  *
  * Use these instead of magic strings so TS catches typos and refactors stay
  * coherent. Each non-dollar-prefixed key is a per-field object carrying
- * name, label, view, optional htmlType/placeholder/helpText, and the
+ * name, label, view, an htmlType where the field's view maps to one, and the
  * RHF-shaped validation rules derived from the field's validator children.
  *
+ * placeholder and helpText are NOT emitted — no provider registers an attribute
+ * for them, so nothing here could derive one. (htmlType is emitted, but derived
+ * from the view subtype; the @htmlType override was removed for the same reason.)
+ * useEntityForm still honours placeholder if you add it: this file is generated,
+ * hand edits inside it survive regeneration through the three-way merge, and the
+ * consumers read this const rather than the metadata. That is the intended way
+ * to set it.
+ *
  * Typical usage with the metaobjects React form helper:
  *
  *   import { useEntityForm } from '@metaobjectsdev/react';

package/src/templates/entity-file.ts

@@ -8,7 +8,7 @@
 
 import { code, imp, joinCode, type Code } from "ts-poet";
 import type { MetaObject, MetaField } from "@metaobjectsdev/metadata";
-import { FIELD_ATTR_OBJECT_REF } from "@metaobjectsdev/metadata";
+import { FIELD_ATTR_OBJECT_REF, SOURCE_ROLE_REPLICA } from "@metaobjectsdev/metadata";
 import { fieldDeclaringPackage, type RenderContext } from "../render-context.js";
 import { renderDrizzleSchema } from "./drizzle-schema.js";
 import { renderInferredTypes, renderEnumTypeAliases } from "./inferred-types.js";
@@ -20,10 +20,13 @@ import { renderTphDiscriminatorUnion, isTphDiscriminatorBase } from "./tph-discr
 import { GENERATED_HEADER } from "../constants.js";
 import { isProjection, isWriteThrough } from "../projection/projection-detector.js";
 import { renderProjectionDecl } from "./projection-decl.js";
-import { projectionViewName } from "../projection/extract-view-spec.js";
+import {
+  projectionViewName, projectionViewSchema, projectionViewRole,
+} from "../projection/extract-view-spec.js";
 import { renderExistingViewDecl, renderViewReadZodObject } from "./view-decl.js";
 import { renderDocsFor } from "./jsdoc.js";
 import { valueObjectModuleSpecifier } from "../import-path.js";
+import { namesRef, namesConstArg, physicalNameExpr, sourceSchemaExpr } from "../names.js";
 import { hasWritableRdbSource } from "../source-detect.js";
 import { renderValueObjectFile } from "./value-object-file.js";
 import { isAbstract } from "../instance-artifacts.js";
@@ -76,6 +79,10 @@ export function renderEntityFile(
   // 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)) {
+    // §A6/§B2 — same `namesRef` pair drizzle-schema.ts builds, so the projection's view
+    // name + per-field dbCol reference the exact constant the names artifact exports
+    // (undefined when the artifact is not in this run — see names.ts). `namesRef`'s
+    // `{ resolved, symbol }` return is exactly the shape `ProjectionDeclOpts.names` wants.
     return renderProjectionDecl(entity, ctx.loadedRoot, {
       columnNamingStrategy: ctx.columnNamingStrategy,
       dialect: ctx.dialect,
@@ -85,6 +92,7 @@ export function renderEntityFile(
       ctx,
       // Contract target drops the Drizzle .existing() view decl + drizzle-orm import.
       includeViewDecl: runtime,
+      names: namesRef(entity, ctx),
     });
   }
 
@@ -141,17 +149,46 @@ export function renderEntityFile(
       const module = valueObjectModuleSpecifier(name, ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle);
       return { name, module };
     };
+    // ONE selection of the replica source: `projectionViewName` names it, and this is the
+    // role its entry has in <Entity>Names.sources. Hardcoding "replica" here would be a
+    // second derivation of the very thing extract-view-spec.ts exists to decide once.
+    const viewRole = projectionViewRole(entity) ?? SOURCE_ROLE_REPLICA;
+    const entityNames = namesRef(entity, ctx);
     const viewOpts = {
       dialect: ctx.dialect, columnNamingStrategy: ctx.columnNamingStrategy, timestampMode: ctx.timestampMode, voRef,
       // PK fields type non-null in the replica-view decl + read schema even
       // without @required (a PK is never NULL; see ViewDeclOpts.pkFieldNames).
       pkFieldNames: new Set(primaryIdentityFieldNames(entity)) as ReadonlySet<string>,
+      // §A6 — the entity's names artifact supplies this view's COLUMN constants. A
+      // replica view exposes the entity's own fields, so `<Entity>Names.fields.<f>.column`
+      // is the same physical name the table side binds; a derived field the artifact
+      // does not carry falls back to the literal via `columnExpr`. The view's own NAME
+      // is passed separately below and stays a literal — the artifact holds the primary
+      // (table) source's name, not this one.
+      names: entityNames,
+      // The replica view's OWN @schema, from the same source node projectionViewName picks
+      // — never the entity's, which is the WRITE TABLE's and would qualify this view with a
+      // schema that belongs to something else. A view and the table it replicates need not
+      // live in the same schema, and a name paired with someone else's schema is worse than
+      // no schema at all.
+      //
+      // Both this and the view's NAME are now CONSTANTS. They were literals for a real
+      // reason that has stopped being true: <Entity>Names carried the primary source only,
+      // so a write-through entity's two physical names had one slot between them and the
+      // second was emitted in full — the same escape C#'s AppDbContext had, in a different
+      // language, which is what showed it was the artifact's shape and not the binding.
+      schema: sourceSchemaExpr(entityNames, viewRole) ?? projectionViewSchema(entity),
     };
     const z = imp("z@zod");
     const docs = renderDocsFor(entity);
     const docsPrefix = docs ? `${docs}\n` : "";
     viewSections.push(
-      renderExistingViewDecl(fields, projectionViewName(entity, ctx.columnNamingStrategy), `${camel}View`, viewOpts),
+      renderExistingViewDecl(
+        fields,
+        physicalNameExpr(entityNames, projectionViewName(entity, ctx.columnNamingStrategy), entity, viewRole),
+        `${camel}View`,
+        viewOpts,
+      ),
       code`
 export const ${entity.name}Schema = ${renderViewReadZodObject(fields, viewOpts)};
 `,
@@ -161,13 +198,18 @@ ${docsPrefix}export type ${entity.name} = ${z}.infer<typeof ${entity.name}Schema
     );
   }
 
+  // §A6/§B2 — same `namesRef` pair drizzle-schema.ts (and this file's own projection
+  // branch above) build, so the descriptor's $table references the exact constant the
+  // names artifact exports (undefined when the artifact is not in this run).
+  const constantsNames = namesRef(entity, ctx);
+
   const sections: Code[] = [
     renderDrizzleSchema(entity, ctx),
     ...viewSections,
     renderInferredTypes(entity, tphBase, ctx, writeThrough /* skipRow — read type is the view schema */),
     ...(enumAliases !== null ? [enumAliases] : []),
     renderZodValidators(entity, ctx),
-    renderEntityConstants(entity, ctx.apiPrefix),
+    renderEntityConstants(entity, ctx.apiPrefix, namesConstArg(constantsNames)),
     ...(allowlists ? [renderFilterAllowlist(entity, undefined, ctx), renderSortAllowlist(entity)] : []),
     renderFilterType(entity),
     ...(tphBlock !== null ? [tphBlock] : []),

package/src/templates/entity-meta-file.ts

@@ -20,7 +20,7 @@
 // consumer having wired an extra generator, since the entity generator is
 // scaffold-and-own (ADR-0034) and cannot be changed from the package.
 
-import { code } from "ts-poet";
+import { code, type Code } from "ts-poet";
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import { GENERATED_HEADER } from "../constants.js";
 import { renderEntityConstants } from "./entity-constants.js";
@@ -35,7 +35,20 @@ export function entityMetaSpecifier(entityName: string, extStyle: string | undef
   return `./${entityName}.meta${extStyle === "js" ? ".js" : ""}`;
 }
 
-export function renderEntityMetaFile(entity: MetaObject, apiPrefix = ""): string {
+export function renderEntityMetaFile(
+  entity: MetaObject,
+  /**
+   * @deprecated Accepted and IGNORED — see `renderEntityConstants`. The API base URL
+   * left the descriptor; the client provider's `baseUrl` supplies it at runtime.
+   *
+   * §A6 fix round 3. OPTIONAL, and it must stay optional: this function is called
+   * from codegen-ts-tanstack's reference/hooks.ts and reference/grid-hook.ts, both
+   * copied verbatim into adopter repos (ADR-0034). A required parameter would fail
+   * to compile in every ejected copy.
+   */
+  _apiPrefix = "",
+  names?: { readonly name: string; readonly symbol: Code } | undefined,
+): string {
   const body = code`
 // ${GENERATED_HEADER} — DO NOT EDIT.
 // Source metadata: ${entity.name}
@@ -45,7 +58,7 @@ export function renderEntityMetaFile(entity: MetaObject, apiPrefix = ""): string
 // from here so a client bundle never pulls the ORM in. \`${entity.name}.ts\` also
 // exports this descriptor, for server-side and pre-existing consumers.
 
-${renderEntityConstants(entity, apiPrefix)}
+${renderEntityConstants(entity, "", names)}
 `;
   return body.toString();
 }