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

package/src/templates/entity-ui-descriptor.ts

@@ -0,0 +1,305 @@
+// The per-field FORM descriptor — the one derivation of "what does this field look like
+// in a UI", shared by everything that answers that question.
+//
+// Two consumers, and the reason they must share:
+//
+//   • `renderEntityConstants()` emits it as the `<Entity>` const in `<Entity>.meta.ts`,
+//     which `useEntityForm` reads at RUNTIME to render the form;
+//   • the `agent/ui.md` docs surface renders it as a table, which is what an agent reads
+//     BEFORE it writes code against that form.
+//
+// If those two were derived separately, the page describing the form and the descriptor
+// driving it could disagree — and the disagreement would be invisible, because the page
+// looks authoritative and nothing compares them. That is the same "a name resolved twice
+// is a name that can disagree with itself" rule `names.ts` states for physical names, one
+// tier up.
+//
+// #356 — THE SURFACE IS THE FORM. `view` resolves through `inferViewKind(field, "form")`,
+// which selects the view named for the form context, so a field declaring several views is
+// described by the one the generated `<Entity>.form.tsx` actually renders. The grid tiers
+// compute their own view kind at codegen time and never read this.
+//
+// RULES ARE AN ORDERED LIST, NOT A KEYED OBJECT, and that is load-bearing rather than
+// stylistic: the emitted `rules: { ... }` object preserves the order the field's validator
+// children were declared in, so a field whose `validator.regex` precedes its
+// `validator.required` emits `pattern` first. A keyed shape would impose one fixed order
+// and silently rewrite every such entity's descriptor.
+//
+// The pattern is carried RAW. Escaping it into a `/.../` literal is a TypeScript-emission
+// concern and belongs to the emitter, not to the description of the field.
+
+import type { MetaData, MetaField, MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
+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,
+  pluralize,
+  toSnakeCase,
+} from "@metaobjectsdev/metadata";
+import { inferViewKind, currencyMetaFor, labelFor, humanize, valueObjectFor } from "./field-meta.js";
+import { VIEW_CONTEXT_FORM } from "../view-context.js";
+import { isProjection } from "../projection/projection-detector.js";
+// `restPath` lives HERE rather than in api-surface.ts, which is where it used to sit and
+// which now re-exports it. The descriptor is what emits `$path`, so the composition has to
+// be reachable from this module; importing it back from `api-surface.js` would be a cycle,
+// since that module imports `resourcePath` from this one. Neither of these two imports
+// reaches back here, so moving the function down is the acyclic direction.
+import { tphDiscriminatorBase, tphDiscriminatorPin } from "./zod-validators.js";
+import { tphRouteSegment } from "./tph-discriminator.js";
+
+/** One validation rule, in the order its source was declared. */
+export type UiRule =
+  | { readonly kind: "required"; readonly message: string }
+  | { readonly kind: "minLength"; readonly value: number; readonly message: string }
+  | { readonly kind: "maxLength"; readonly value: number; readonly message: string }
+  /** `pattern` is the RAW authored regex source — never pre-escaped. */
+  | { readonly kind: "pattern"; readonly pattern: string; readonly message: string };
+
+export interface UiFieldDescriptor {
+  readonly name: string;
+  readonly label: string;
+  /** The MetaView subtype resolved for the FORM context. */
+  readonly view: string;
+  /** Present only when the view maps to a real HTML `<input type=…>`. Derived from the
+   *  view subtype — there is no authored override (see `htmlTypeFromView`). */
+  readonly htmlType?: string | undefined;
+  /** Empty when the field declares nothing to validate. */
+  readonly rules: readonly UiRule[];
+  /** Present only for a `field.currency`. */
+  readonly currency?: { readonly currency: string; readonly locale: string } | undefined;
+  /**
+   * Present when the generated FORM renders this field as a nested value-object
+   * sub-form rather than an input — a `field.object` whose `@objectRef` resolves (see
+   * `valueObjectFor`). Computed only when `buildEntityUiDescriptor` is given the loaded
+   * root; `renderEntityConstants` does not pass one and emits nothing for it, so the
+   * `<Entity>` const is byte-identical either way.
+   */
+  readonly nested?: { readonly objectRef: string; readonly isArray: boolean } | undefined;
+}
+
+export interface EntityUiDescriptor {
+  readonly entity: string;
+  /** The address the generated routes SERVE this object at — `/subscribers`, and
+   *  `/vehicles/car` for a TPH subtype. Emitted as `$path`. See {@link restPath}. */
+  readonly path: string;
+  /** Every field, INHERITED INCLUDED (ADR-0039 resolving `fields()`). */
+  readonly fields: readonly UiFieldDescriptor[];
+}
+
+/**
+ * An object's OWN pluralized resource path — the one derivation of that spelling, and the
+ * input {@link restPath} composes an address from. It is NOT `$path` on its own.
+ *
+ * A projection is KEBAB-cased and an entity is SNAKE-cased, and that split is not a
+ * style choice: both spellings are already mounted. `renderProjectionDecl` emits
+ * `$path: "/order-summaries"` and `renderEntityConstants` emits `$path:
+ * "/order_summaries"`, and `routes-file.ts` mounts whichever const belongs to the object
+ * — so an address computed without the split is wrong for every multi-word projection.
+ * It used to live in a second function inside `projection-decl.ts`, which is exactly how
+ * `agent/ui.md` and `api/AGENT-API.md` both came to print `/order_summaries` for a
+ * projection served at `/order-summaries`.
+ *
+ *   "Subscriber"     → "/subscribers"
+ *   "WorkoutEvent"   → "/workout_events"
+ *   "ProgramSummary" → "/program-summaries"   (projection)
+ *
+ * A TPH SUBTYPE is not addressed by this path — it is mounted under its base — so this is
+ * an INPUT to {@link restPath}, not the answer. `$path` carries `restPath`; call this only
+ * when you specifically want an object's own pluralized name, never to build an address.
+ */
+export function resourcePath(entity: MetaData): string {
+  // The two compositions differ in ORDER as well as separator, and both are load-bearing:
+  // pluralize-then-snake is what the projection const has always emitted, snake-then-
+  // pluralize is what the entity const has. Neither may be "tidied" into the other.
+  return isProjection(entity)
+    ? `/${toSnakeCase(pluralize(entity.name)).replace(/_/g, "-")}`
+    : `/${pluralize(toSnakeCase(entity.name))}`;
+}
+
+/**
+ * THE address the generated routes serve this object at — and therefore what the
+ * `<Entity>` const emits as `$path`.
+ *
+ * `resourcePath` answers a different question: an object's own pluralized name. The two
+ * agree for everything EXCEPT a TPH subtype, which emits no routes file of its own —
+ * `routes-file.ts` mounts the whole hierarchy from the discriminator BASE, giving the
+ * union read-only routes at the base path and each subtype a full CRUD set at
+ * `<base path>/<route segment>`.
+ *
+ * `$path` used to carry `resourcePath`, so a subtype's own `$path` named an endpoint that
+ * did not exist. That was not confined to prose: `agent/ui.md` printed it as fact, and the
+ * TanStack `grid-hook-file.ts` builds its fetch URL from `<Entity>.$path` with no TPH
+ * branch at all, so an opted-in per-subtype grid requested an address nothing served.
+ * Fixing it here fixes every consumer, because every consumer reads the const.
+ *
+ * The composition is the same one `routes-file.ts` and `hooks-file.ts` emit as CODE
+ * (`Base.$path + "/car"`); they reference the const rather than a computed string, so this
+ * is the one place it can be evaluated. The SEGMENT rule is not restated —
+ * `tphRouteSegment` owns it, and all three read it from there.
+ */
+export function restPath(entity: MetaObject): string {
+  const pin = tphDiscriminatorPin(entity);
+  const base = tphDiscriminatorBase(entity);
+  if (pin === undefined || base === undefined) return resourcePath(entity);
+  return `${resourcePath(base)}/${tphRouteSegment(pin.value)}`;
+}
+
+/**
+ * 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) — consumers render the
+ * right element type themselves.
+ *
+ * THE MAPPING IS THE ONLY SOURCE. An `@htmlType` override used to be read off the view
+ * node ahead of this switch; nothing registers that attribute, so the override was
+ * unreachable and this mapping was always the answer. A consumer needing a different
+ * `type=` edits the emitted `<Entity>.meta.ts`, whose hand edits the merge preserves.
+ */
+function htmlTypeFromView(view: string): string | undefined {
+  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;
+  }
+}
+
+/**
+ * The field's validation rules, in DECLARATION ORDER — see the ordering note at the top
+ * of this file.
+ *
+ * The field-level `@required` / `@maxLength` attrs append only when no validator child
+ * already supplied that rule, so the two authoring spellings never double up.
+ */
+function buildFieldRules(field: MetaField): UiRule[] {
+  const rules: UiRule[] = [];
+  let hasRequired = false;
+  let hasMaxLength = false;
+
+  // ADR-0039: resolving — a validator may inherit its config attrs (@min/@max/@pattern)
+  // via extends.
+  //
+  // THE MESSAGES ARE DERIVED, NOT AUTHORED. `@message` / `@minMessage` / `@maxMessage`
+  // used to be read here as overrides; no provider registers any of them, so the reads
+  // were unreachable and the defaults below were always what shipped. A consumer wanting
+  // different wording edits the emitted `rules` object in `<Entity>.meta.ts`, which is a
+  // generated file whose hand edits the three-way merge preserves. See ADR-0023.
+  for (const child of field.validators()) {
+    if (child.subType === VALIDATOR_SUBTYPE_REQUIRED) {
+      rules.push({ kind: "required", message: `${humanize(field.name)} is required` });
+      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") {
+        rules.push({ kind: "minLength", value: min, message: `Must be at least ${min} characters` });
+      }
+      if (typeof max === "number") {
+        rules.push({ kind: "maxLength", value: max, message: `Must be ${max} characters or fewer` });
+        hasMaxLength = true;
+      }
+    } else if (child.subType === VALIDATOR_SUBTYPE_REGEX) {
+      const pattern = child.attr(VALIDATOR_ATTR_PATTERN);
+      if (typeof pattern === "string") {
+        rules.push({ kind: "pattern", pattern, message: "Invalid format" });
+      }
+    }
+  }
+
+  // Field-level @required attr (if not already covered by validator).
+  if (!hasRequired && field.attr(FIELD_ATTR_REQUIRED) === true) {
+    rules.push({ kind: "required", message: `${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") {
+    rules.push({
+      kind: "maxLength",
+      value: maxLenAttr,
+      message: `Must be ${maxLenAttr} characters or fewer`,
+    });
+  }
+
+  return rules;
+}
+
+/**
+ * Describe one field's form presentation.
+ *
+ * `root` is OPTIONAL and only decides whether `nested` is filled in: resolving a
+ * `field.object`'s `@objectRef` needs the run's other objects, and the two callers differ
+ * — `renderEntityConstants` has no root (it is also ejected into adopter repos with a
+ * fixed signature) while the docs surface does. Passing one adds a member the const
+ * emitter ignores; it never changes any member the const emits.
+ */
+export function buildUiFieldDescriptor(field: MetaField, root?: MetaRoot): UiFieldDescriptor {
+  // `inferViewKind` IS the resolution: the view child declared for the FORM (own or
+  // inherited) wins, else the field subtype's default. This module used to keep a
+  // `resolveView` that returned the same string plus the view NODE, and the node existed
+  // only to read `@placeholder` / `@helpText` / `@htmlType` off it — none of which any
+  // provider registers, so all three reads were unreachable. With them gone the node has
+  // no reader and the two functions were the same function.
+  const view = inferViewKind(field, VIEW_CONTEXT_FORM);
+  const currencyMeta = currencyMetaFor(field, VIEW_CONTEXT_FORM);
+  const vo = root === undefined ? undefined : valueObjectFor(field, root);
+  return {
+    name: field.name,
+    label: labelFor(field, VIEW_CONTEXT_FORM),
+    view,
+    htmlType: htmlTypeFromView(view),
+    rules: buildFieldRules(field),
+    currency: currencyMeta === null
+      ? undefined
+      : { currency: currencyMeta.currency, locale: currencyMeta.locale },
+    nested: vo === undefined
+      ? undefined
+      : { objectRef: vo.name, isArray: field.resolvedIsArray() },
+  };
+}
+
+/** Describe one object's whole form surface. See {@link buildUiFieldDescriptor} for `root`. */
+export function buildEntityUiDescriptor(obj: MetaObject, root?: MetaRoot): EntityUiDescriptor {
+  return {
+    entity: obj.name,
+    // `restPath`, not `resourcePath`: `$path` is the address this object is SERVED at.
+    // They differ only for a TPH subtype, and for that one case `resourcePath` names an
+    // endpoint nothing mounts (see restPath's note).
+    path: restPath(obj),
+    // ADR-0039: resolving `fields()` so inherited fields appear, exactly as the emitted
+    // descriptor has always done.
+    fields: obj.fields().map((f) => buildUiFieldDescriptor(f, root)),
+  };
+}

package/src/templates/field-meta.ts

@@ -4,6 +4,8 @@
 // All helpers take a MetaField node.
 
 import { MetaField } from "@metaobjectsdev/metadata";
+import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
+import { stripPackage } from "@metaobjectsdev/metadata";
 import {
   FIELD_SUBTYPE_STRING,
   FIELD_SUBTYPE_INT,
@@ -20,6 +22,8 @@ import {
   FIELD_SUBTYPE_UUID,
   FIELD_SUBTYPE_URI,
   FIELD_SUBTYPE_INET,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_ATTR_OBJECT_REF,
   FIELD_ATTR_STRING_FORMAT,
   FIELD_ATTR_LENIENT,
   STRING_FORMAT_EMAIL,
@@ -29,12 +33,14 @@ import {
   VIEW_SUBTYPE_NUMBER,
   VIEW_SUBTYPE_CHECKBOX,
   VIEW_SUBTYPE_CURRENCY,
+  VIEW_SUBTYPE_DROPDOWN,
   FIELD_ATTR_CURRENCY,
   FIELD_ATTR_CURRENCY_DEFAULT,
   VIEW_CURRENCY_ATTR_LOCALE,
   VIEW_CURRENCY_ATTR_LOCALE_DEFAULT,
 } from "@metaobjectsdev/metadata";
 import { enumValues, zodEnumExpr } from "../enum-meta.js";
+import { viewForContext } from "../view-context.js";
 import { ZOD_INET_EXPR } from "./net-regex.js";
 
 // ---------------------------------------------------------------------------
@@ -42,12 +48,16 @@ import { ZOD_INET_EXPR } from "./net-regex.js";
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve the cell-renderer key (view kind) for a field.
- * Explicit view child wins; field subType determines default.
+ * Resolve the cell-renderer key (view kind) for a field, for the surface named
+ * by `context`.
+ *
+ * An explicit view declared for THAT surface wins; field subType determines the
+ * default. #356: `context` is required rather than defaulting, because a caller
+ * that omits it is exactly the caller that renders somebody else's view.
  */
-export function inferViewKind(field: MetaField): string {
-  // Explicit view (own or inherited via extends) has highest priority.
-  const viewChild = field.views()[0];
+export function inferViewKind(field: MetaField, context: string): string {
+  // Explicit view for this surface (own or inherited via extends) has highest priority.
+  const viewChild = viewForContext(field, context);
   if (viewChild) return viewChild.subType;
   // Field subtype → default view.
   return defaultViewForSubType(field.subType);
@@ -69,6 +79,22 @@ function defaultViewForSubType(subType: string): string {
       return VIEW_SUBTYPE_DATE;
     case FIELD_SUBTYPE_CURRENCY:
       return VIEW_SUBTYPE_CURRENCY;
+    case FIELD_SUBTYPE_ENUM:
+      // A closed member set is a CHOICE, and the generated form has always rendered it as
+      // one: `codegen-ts-react`'s `viewKindFor` returns `dropdown` for an enum declaring no
+      // view, and emits a `<select>` with an `<option>` per member.
+      //
+      // This branch was missing, so the same question had two answers. The emitted
+      // `<Entity>` descriptor — which `useEntityForm` reads at RUNTIME — fell through to
+      // `text` and told every consumer the control was a free-text input, for the one field
+      // subtype where free text is exactly what the model forbids. The form was right and
+      // the descriptor describing it was wrong.
+      //
+      // Fixed HERE rather than in the react tier because this is the shared resolver: the
+      // descriptor, the `agent/ui.md` page and the form must give one answer, and pinning
+      // the agreement in the tier that renders it would leave the two other readers still
+      // computing their own.
+      return VIEW_SUBTYPE_DROPDOWN;
     default:
       return VIEW_SUBTYPE_TEXT;
   }
@@ -152,14 +178,25 @@ export function zodTypeFor(field: MetaField, timestampMode: "date" | "string" =
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve currency code + locale for a currency-subtype field.
- * Returns null for non-currency fields.
+ * Resolve currency code + locale for a currency-subtype field, for the surface
+ * named by `context`. Returns null for non-currency fields.
  */
-export function currencyMetaFor(field: MetaField): { currency: string; locale: string } | null {
+export function currencyMetaFor(
+  field: MetaField,
+  context: string,
+): { currency: string; locale: string } | null {
   if (field.subType !== FIELD_SUBTYPE_CURRENCY) return null;
   const currency =
     (field.attr(FIELD_ATTR_CURRENCY) as string | undefined) ?? FIELD_ATTR_CURRENCY_DEFAULT;
-  const viewChild = field.views().find((c) => c.subType === VIEW_SUBTYPE_CURRENCY);
+  // #356: the surface's own view carries the @locale for that surface — two
+  // currency views with different locales must not be resolved by position.
+  // When the surface's view is NOT a currency view (or there is none), keep the
+  // pre-#356 scan: an authored @locale anywhere on the field beats the default.
+  const contextView = viewForContext(field, context);
+  const viewChild =
+    contextView?.subType === VIEW_SUBTYPE_CURRENCY
+      ? contextView
+      : field.views().find((c) => c.subType === VIEW_SUBTYPE_CURRENCY);
   // ADR-0039: resolving — a view may inherit @locale via extends.
   const locale =
     (viewChild?.attr(VIEW_CURRENCY_ATTR_LOCALE) as string | undefined) ??
@@ -167,20 +204,58 @@ export function currencyMetaFor(field: MetaField): { currency: string; locale: s
   return { currency, locale };
 }
 
+// ---------------------------------------------------------------------------
+// valueObjectFor
+// ---------------------------------------------------------------------------
+
+/**
+ * The `object.value` a `field.object`'s `@objectRef` names, or `undefined` when the
+ * field is not an object field, declares no ref, or names one that is not in the run.
+ *
+ * THIS IS THE "DOES THE FORM NEST THIS FIELD?" PREDICATE, and it lives here because two
+ * tiers have to give one answer: `codegen-ts-react`'s form generator recurses into the
+ * referenced value object as a `<fieldset>` sub-form (or a `useFieldArray` repeatable
+ * group when the field is an array) instead of emitting an input at all, and
+ * `agent/ui.md` documents what that form renders. When they answered separately the page
+ * printed `text` — the field's resolved `view.*` subtype, which the form never consults
+ * for a nested field — as if it were the control.
+ *
+ * The resolution is BARE-NAME on purpose: it is the same lookup the Zod and
+ * inferred-type templates perform, and changing it here would change what the generated
+ * form nests. A package-aware resolution is a separate decision with its own blast
+ * radius (ADR-0042).
+ */
+export function valueObjectFor(field: MetaField, root: MetaRoot): MetaObject | undefined {
+  if (field.subType !== FIELD_SUBTYPE_OBJECT) return undefined;
+  // ADR-0039: resolving — @objectRef may be inherited via extends.
+  const ref = field.attr(FIELD_ATTR_OBJECT_REF);
+  if (typeof ref !== "string" || ref.length === 0) return undefined;
+  const base = stripPackage(ref);
+  return root.objects().find((o) => o.name === base);
+}
+
 // ---------------------------------------------------------------------------
 // labelFor
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve the human-readable label for a field.
- * Uses @label attr on a view child if present; otherwise humanizes the field name.
+ * Resolve the human-readable label for a field, for the surface named by `context`.
+ * Uses the registered `@title` common attr — on that surface's view first, else on the
+ * field itself; otherwise humanizes the field name.
+ *
+ * #353 — this read `@label`, which no provider registers on any `view.*` subtype, so the
+ * override branch was unreachable: authoring it fails the strict load `meta verify` runs
+ * (ERR_UNKNOWN_ATTR). `title` is already a registered common attr on every node and
+ * already means "a noun phrase", so nothing was registered for this (ADR-0037 step 0).
  */
-export function labelFor(field: MetaField): string {
-  for (const child of field.views()) {
-    // ADR-0039: resolving — a view may inherit @label via extends.
-    const label = child.attr("label");
-    if (typeof label === "string" && label.length > 0) return label;
-  }
+export function labelFor(field: MetaField, context: string): string {
+  // #356: the label reads the view for THIS surface, not whichever view was
+  // declared first — a grid header must not retitle the form's field.
+  // ADR-0039: resolving — a view may inherit @title via extends.
+  const title = viewForContext(field, context)?.attr("title");
+  if (typeof title === "string" && title.length > 0) return title;
+  const fieldTitle = field.attr("title");
+  if (typeof fieldTitle === "string" && fieldTitle.length > 0) return fieldTitle;
   return humanize(field.name);
 }
 
@@ -188,8 +263,14 @@ export function labelFor(field: MetaField): string {
 // Internal
 // ---------------------------------------------------------------------------
 
-/** Convert a camelCase or PascalCase field name to a human-friendly label. */
-function humanize(s: string): string {
+/**
+ * Convert a camelCase or PascalCase field name to a human-friendly label.
+ *
+ * THE one copy in this package: `entity-ui-descriptor.ts` re-exports this rather than
+ * keeping a second body, because two spellings of "humanize" is two answers to what a
+ * field is CALLED — the label a form renders and the label the docs page prints.
+ */
+export function humanize(s: string): string {
   return s
     .replace(/([a-z])([A-Z])/g, "$1 $2")
     .replace(/_/g, " ")

package/src/templates/names-decl.ts

@@ -0,0 +1,165 @@
+/**
+ * §A1/§A2 — `<Entity>Names`: the physical database names for one object, as constants a
+ * hand-written consumer references instead of a string literal.
+ *
+ * Shape copied from the FR-009 filter allowlist, which is the same problem (a per-entity
+ * name artifact) already solved in all five ports. Deliberately NOT folded into the entity
+ * descriptor: four of five ports have no descriptor to extend, and merging in TypeScript
+ * alone would make TS the odd port out on the axis this project protects hardest.
+ *
+ * An artifact whose object EXTENDS another one that has an artifact of its own spreads it
+ * rather than restating what it inherits — "extend from the parent, do not redo all the
+ * names". Two shapes, decided structurally:
+ *
+ *   - the object declares its OWN source: spread only the super's `fields`, because the
+ *     physical name, kind, schema and read-only-ness are this object's own. Spreading the
+ *     whole super here would leak its `schema` onto a child that declares none.
+ *   - the object INHERITS its source (a TPH subtype sharing its base's single table):
+ *     spread the WHOLE super, so the table name is stated once, on the base.
+ */
+import type { ColumnNamingStrategy, MetaObject } from "@metaobjectsdev/metadata";
+import { GENERATED_HEADER } from "../constants.js";
+import { PHYSICAL_NAME_ATTR_BY_KIND, primaryRdbSource } from "@metaobjectsdev/metadata";
+
+/** The physical-name alias keys, in the metamodel's own order. */
+const PHYSICAL_NAME_ALIASES = [...PHYSICAL_NAME_ATTR_BY_KIND.values()] as const;
+import {
+  resolveObjectNames, resolveSuperFragmentNames,
+  type FieldNames, type KeyNames, type ObjectNames, type SourceNames,
+} from "../names.js";
+
+export interface NamesDeclOpts {
+  readonly strategy?: ColumnNamingStrategy | undefined;
+  /**
+   * Module specifier for the super's names module (e.g. `"./BaseEntity.names"`), when this
+   * artifact extends one. Computed by the CALLER, which is the only place that knows the
+   * project's output layout and extension style. Omitted ⇒ the flat shape: every inherited
+   * column restated, which is what an ejected reference template that has not been updated
+   * still produces. Correct, just not deduplicated.
+   */
+  readonly superSpecifier?: string | undefined;
+  /**
+   * Render the FRAGMENT form — an abstract base that a sourced object extends, carrying
+   * columns and no physical name. See `resolveSuperFragmentNames`.
+   */
+  readonly fragment?: boolean | undefined;
+}
+
+/** Back-compat: the second argument was the naming strategy, and an ejected copy still passes it. */
+function normalize(opts?: ColumnNamingStrategy | NamesDeclOpts): NamesDeclOpts {
+  return typeof opts === "string" || opts === undefined ? { strategy: opts } : opts;
+}
+
+export function renderNamesDecl(
+  obj: MetaObject,
+  opts?: ColumnNamingStrategy | NamesDeclOpts,
+): string {
+  const o = normalize(opts);
+  // `fragment` says "this is an ANCESTOR render" — emit even though the walk reached this
+  // object by climbing rather than by matching. It does NOT say which shape to render, and
+  // it must not: a caller that hardcodes `true` is correct for an abstract base with
+  // columns and no table, and wrong for the other ancestor this walk reaches — a TPH BASE
+  // under `meta gen --entities <Subtype>`, which owns the shared table. Rendered as a
+  // fragment it emits no source at all while the subtype still spreads it.
+  //
+  // Derived HERE rather than at the call site because the call sites are plural and one of
+  // them is EJECTED: `src/reference/names.ts` is copied into an adopter's repo by
+  // `meta init` and thereafter owned by them. Deciding it in the engine makes every copy
+  // already on disk correct without an edit, and leaves no caller able to get it wrong.
+  const n: ObjectNames | undefined = o.fragment === true && primaryRdbSource(obj) === undefined
+    ? resolveSuperFragmentNames(obj, o.strategy)
+    : resolveObjectNames(obj, o.strategy);
+  if (n === undefined) return "";
+
+  const superSym = n.superNames === undefined || o.superSpecifier === undefined
+    ? undefined
+    : `${n.superNames.name}Names`;
+
+  const q = (v: string): string => JSON.stringify(v);
+  // A key is emitted bare only when it is a valid identifier. Field names always are;
+  // an index name is author-chosen and routinely is not (`uq_cust_email` is, `2fa-idx`
+  // is not), so quoting is decided per key rather than per collection — an unquoted
+  // non-identifier key is a file that does not parse.
+  const key = (k: string): string => (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) ? k : q(k));
+
+  /**
+   * One `name`-keyed collection — `fields`, `identities`, `indexes`.
+   *
+   * With a super to spread, only what THIS object declares is emitted and the rest is
+   * reached through the parent's artifact, so a physical name is stated once. Without one,
+   * every member must be here: a consumer looks a column up by field name and an inherited
+   * miss falls back to a literal, which is the defect the artifact exists to remove.
+   *
+   * The collection key is always emitted, even when empty, because a child spreads
+   * `...Super.identities` unconditionally.
+   */
+  const collection = (
+    label: string,
+    all: Readonly<Record<string, unknown>>,
+    own: Readonly<Record<string, unknown>>,
+    render: (v: never) => string,
+  ): string => {
+    const rows = superSym === undefined ? all : own;
+    const body = Object.keys(rows).sort()
+      .map((k) => `    ${key(k)}: ${render(rows[k] as never)},`)
+      .join("\n");
+    const spread = superSym === undefined ? "" : `    ...${superSym}.${label},\n`;
+    if (spread === "" && body === "") return `  ${label}: {},`;
+    return `  ${label}: {\n${spread}${body}${body === "" ? "" : "\n"}  },`;
+  };
+
+  const fieldsBlock = collection("fields", n.fields, n.ownFields,
+    (f: FieldNames) => `{ name: ${q(f.name)}, column: ${q(f.column)} }`);
+
+  // `type` and `subType` on every entry, because the artifact mirrors the metadata tree
+  // and because on these two collections the subType is the only thing that says whether
+  // an index is unique — ADR-0040 put that in the type rather than in an attribute.
+  const renderKey = (k: KeyNames): string =>
+    `{ type: ${q(k.type)}, subType: ${q(k.subType)}, name: ${q(k.name)}` +
+    (k.index === undefined ? " }" : `, index: ${q(k.index)} }`);
+  const identitiesBlock = collection("identities", n.identities, n.ownIdentities, renderKey);
+  const indexesBlock = collection("indexes", n.indexes, n.ownIndexes, renderKey);
+
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Source metadata: ${obj.name}\n` +
+    (superSym === undefined ? "" : `import { ${superSym} } from ${q(o.superSpecifier as string)};\n\n`);
+
+  // The object's own identity. `name` is the METAMODEL name — it held the physical name
+  // until 0.25.0, and that key changing meaning without changing shape is the one thing
+  // here a hand-written consumer adopts without a compile error.
+  const identity =
+    `  type: ${q(n.type)},\n` +
+    `  subType: ${q(n.subType)},\n` +
+    `  name: ${q(n.name)},\n`;
+
+  /** One source, under its role. The physical name sits under the alias for its `@kind`. */
+  const renderSource = (role: string, src: SourceNames): string => {
+    const parts = [`type: ${q(src.type)}`, `subType: ${q(src.subType)}`, `kind: ${q(src.kind)}`];
+    if (src.schema !== undefined) parts.push(`schema: ${q(src.schema)}`);
+    for (const alias of PHYSICAL_NAME_ALIASES) {
+      const v = src[alias as keyof SourceNames];
+      if (typeof v === "string") parts.push(`${alias}: ${q(v)}`);
+    }
+    return `    ${key(role)}: { ${parts.join(", ")} },`;
+  };
+
+  // A fragment declares no source and must never acquire one; a TPH subtype INHERITS its
+  // base's, so it spreads rather than restating — structural (the two resolve to the SAME
+  // node), never an equality test on the resolved strings.
+  const sourceRows = Object.keys(n.ownSources).sort()
+    .map((role) => renderSource(role, n.ownSources[role] as SourceNames)).join("\n");
+  const spreadSources = superSym !== undefined && n.inheritsSource ? `    ...${superSym}.sources,\n` : "";
+  const sourcesBlock =
+    spreadSources === "" && sourceRows === ""
+      ? "  sources: {},"
+      : `  sources: {\n${spreadSources}${sourceRows}${sourceRows === "" ? "" : "\n"}  },`;
+
+  return `${header}export const ${obj.name}Names = {
+${identity}${sourcesBlock}
+${fieldsBlock}
+${identitiesBlock}
+${indexesBlock}
+} as const;
+`;
+}