@metaobjectsdev/codegen-ts 1.0.0-rc.4 → 1.0.0-rc.6

package/src/templates/queries-file.ts

@@ -26,6 +26,7 @@ import { GENERATED_HEADER } from "../constants.js";
 import { isTphDiscriminatorBase, tphConcreteSubtypes } from "./tph-discriminator.js";
 import { isProjection, isWriteThrough } from "../projection/projection-detector.js";
 import { hasAutoSetFields } from "./zod-validators.js";
+import { effectivePackage } from "../docs-paths.js";
 
 /**
  * The dialect-correct Drizzle `Db` type alias + its import — parameter-passed into every
@@ -94,7 +95,7 @@ export function renderQueriesFile(obj: MetaObject, ctx: RenderContext): string {
   const entityFileName = entityModuleSpecifier(
     ctx.selfTarget,
     ctx.entityModuleTarget,
-    obj.package,
+    effectivePackage(obj),
     entityName,
     ctx.extStyle,
   );
@@ -163,7 +164,7 @@ function renderProjectionQueriesFile(obj: MetaObject, ctx: RenderContext): strin
   const camelName = entityName.charAt(0).toLowerCase() + entityName.slice(1);
   const viewVar = `${camelName}View`;
   const entityFileName = entityModuleSpecifier(
-    ctx.selfTarget, ctx.entityModuleTarget, obj.package, entityName, ctx.extStyle,
+    ctx.selfTarget, ctx.entityModuleTarget, effectivePackage(obj), entityName, ctx.extStyle,
   );
   const { fieldName: pkField, tsType: pkType } = getPkInfo(obj, ctx);
   const eqSym = imp("eq@drizzle-orm");
@@ -215,7 +216,7 @@ function renderWriteThroughQueriesFile(obj: MetaObject, ctx: RenderContext): str
   const tableVar = ctx.collectionName(entityName);
   const singularVar = camelName;
   const entityFileName = entityModuleSpecifier(
-    ctx.selfTarget, ctx.entityModuleTarget, obj.package, entityName, ctx.extStyle,
+    ctx.selfTarget, ctx.entityModuleTarget, effectivePackage(obj), entityName, ctx.extStyle,
   );
   const { fieldName: pkField, tsType: pkType } = getPkInfo(obj, ctx);
   const pkFields = getPkFields(obj);
@@ -309,7 +310,7 @@ function renderTphQueriesFile(base: MetaObject, ctx: RenderContext): string {
   const { fieldName: pkField, tsType: pkType } = getPkInfo(base, ctx);
 
   const baseFileSpec = entityModuleSpecifier(
-    ctx.selfTarget, ctx.entityModuleTarget, base.package, baseName, ctx.extStyle,
+    ctx.selfTarget, ctx.entityModuleTarget, effectivePackage(base), baseName, ctx.extStyle,
   );
   const tableSym = imp(`${tableVar}@${baseFileSpec}`);
   const baseTypeSym = imp(`t:${baseName}@${baseFileSpec}`);
@@ -342,7 +343,7 @@ export async function list${pluralize(baseName)}(db: Db, opts?: { limit?: number
     const value = sub.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE) as string;
     const valueLit = JSON.stringify(value);
     const subFileSpec = entityModuleSpecifier(
-      ctx.selfTarget, ctx.entityModuleTarget, sub.package, sub.name, ctx.extStyle,
+      ctx.selfTarget, ctx.entityModuleTarget, effectivePackage(sub), sub.name, ctx.extStyle,
     );
     const subTypeSym = imp(`t:${sub.name}@${subFileSpec}`);
     const subSchemaSym = imp(`${sub.name}Schema@${subFileSpec}`);

package/src/templates/relations-block.ts

@@ -7,6 +7,7 @@ import { CARDINALITY_ONE, CARDINALITY_MANY } from "@metaobjectsdev/metadata";
 import { type RenderContext } from "../render-context.js";
 import { crossEntitySpecifier } from "../import-path.js";
 import type { RelationEntry } from "../relation-resolver.js";
+import { effectivePackage } from "../docs-paths.js";
 
 /**
  * Render the relations() block for one entity.
@@ -28,7 +29,7 @@ export function renderRelationsBlock(entity: MetaObject, ctx: RenderContext): Co
   if (hasMany) paramParts.push("many");
   const params = `{ ${paramParts.join(", ")} }`;
 
-  const thisEntityPackage = entity.package;
+  const thisEntityPackage = effectivePackage(entity);
   const lines: Code[] = entries.map((entry) =>
     renderRelationEntry(entry, ctx, varName, thisEntityPackage),
   );

package/src/templates/render-helper.ts

@@ -53,6 +53,8 @@ import {
   type VerifyError,
 } from "@metaobjectsdev/render";
 import { templateSymbolBase } from "../naming.js";
+import { GENERATED_HEADER } from "../constants.js";
+import type { ExtStyle } from "../metaobjects-config.js";
 
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
 // ADR-0042: package-local — resolveObjectRef binds a bare @objectRef in `referrerPkg` first (else root-level), an FQN exactly.
@@ -65,6 +67,20 @@ function findTemplate(root: MetaData, name: string): MetaData | undefined {
   return root.children().find((c) => c.type === TYPE_TEMPLATE && c.name === name);
 }
 
+/**
+ * The three lines every emitted render-helper module opens with: the generated-file
+ * marker, the `render()` import, and the typed payload import. Identical between the
+ * email and document kinds below — only the `@metaobjectsdev/render` type import
+ * differs (email additionally needs `EmailDocument`), so that piece is a parameter
+ * rather than a second near-copy of this block.
+ */
+function renderHelperHeader(typeImports: string, payloadTypeName: string, ext: string): string {
+  return `// ${GENERATED_HEADER} — DO NOT EDIT.
+import { render } from "@metaobjectsdev/render";
+import type { ${typeImports} } from "@metaobjectsdev/render";
+import type { ${payloadTypeName} } from "./${payloadTypeName}${ext}";`;
+}
+
 /**
  * Walk an `object.value` view-object into a render `PayloadField[]`. Object-ref
  * fields recurse into their referenced view-object; a `seen` set guards a
@@ -150,6 +166,16 @@ export function renderRenderHelper(
   root: MetaData,
   templateName: string,
   provider: Provider,
+  /**
+   * The project's import-extension style, as every other emitter honours it.
+   * Defaults to "js" — the engine default — so an existing caller is unchanged.
+   *
+   * This file used to hardcode `.js` regardless. Both spellings happen to resolve
+   * under nodenext AND bundler, so nothing broke; it was simply the one emitter
+   * that did not read the setting, which is how a project with `extStyle: "none"`
+   * ended up with one file spelling its imports differently from every other.
+   */
+  extStyle: ExtStyle = "js",
 ): string {
   const tmpl = findTemplate(root, templateName);
   if (!tmpl) {
@@ -186,6 +212,9 @@ export function renderRenderHelper(
   // resolution above (findObject/derivePayloadFieldTree) intentionally keeps
   // using the raw `payloadRef`.
   const payloadTypeName = stripPackage(payloadRef);
+  // The emitted relative import's extension, from the project's setting rather than
+  // hardcoded — see the `extStyle` parameter doc.
+  const ext = extStyle === "none" ? "" : ".js";
 
   // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
   const kind = ((tmpl.attr(TEMPLATE_ATTR_KIND) as string | undefined) ?? TEMPLATE_KIND_DEFAULT)
@@ -215,9 +244,7 @@ export function renderRenderHelper(
         ? `\n    textBody: render({ ref: ${JSON.stringify(textBodyRef)}, payload, format: "text", provider, verify: ${ft} }),`
         : "";
 
-    return `import { render } from "@metaobjectsdev/render";
-import type { Provider, EmailDocument } from "@metaobjectsdev/render";
-import type { ${payloadTypeName} } from "./${payloadTypeName}.js";
+    return `${renderHelperHeader("Provider, EmailDocument", payloadTypeName, ext)}
 
 /**
  * Render the ${templateName} email (subject + html body${typeof textBodyRef === "string" ? " + text body" : ""}) from a
@@ -255,9 +282,7 @@ export function ${fnName}(payload: ${payloadTypeName}, provider: Provider): Emai
   const maxCharsArg =
     maxChars !== undefined && Number.isFinite(maxChars) ? `, maxChars: ${maxChars}` : "";
 
-  return `import { render } from "@metaobjectsdev/render";
-import type { Provider } from "@metaobjectsdev/render";
-import type { ${payloadTypeName} } from "./${payloadTypeName}.js";
+  return `${renderHelperHeader("Provider", payloadTypeName, ext)}
 
 /**
  * Render the ${templateName} document from a typed ${payloadTypeName} payload. Wraps the

package/src/templates/routes-file-hono.ts

@@ -31,6 +31,7 @@ import { entityModuleSpecifier } from "../import-path.js";
 import { GENERATED_HEADER } from "../constants.js";
 import { isProjection, isWriteThrough } from "../projection/projection-detector.js";
 import { type CrudVerb, exposeLine } from "../routes-expose.js";
+import { effectivePackage } from "../docs-paths.js";
 
 export function renderRoutesFileHono(
   entity: MetaObject,
@@ -49,7 +50,7 @@ export function renderRoutesFileHono(
   const entityFileSpec = entityModuleSpecifier(
     ctx.selfTarget,
     ctx.entityModuleTarget,
-    entity.package,
+    effectivePackage(entity),
     entityName,
     ctx.extStyle,
   );

package/src/templates/routes-file.ts

@@ -30,6 +30,7 @@ import { isProjection, isWriteThrough } from "../projection/projection-detector.
 import type { RelationEntry } from "../relation-resolver.js";
 import { isTphDiscriminatorBase, tphPlan } from "./tph-discriminator.js";
 import { type CrudVerb, exposeLine, intersectExpose, TPH_POLYMORPHIC_VERBS } from "../routes-expose.js";
+import { effectivePackage } from "../docs-paths.js";
 
 export function renderRoutesFile(
   entity: MetaObject,
@@ -49,16 +50,17 @@ export function renderRoutesFile(
 
   const entityName = entity.name;
   const handlerName = routesHandlerName(entityName);
+  const entityPkg = effectivePackage(entity);
   // Import the entity's own file. Same target → relative "./Entity"; cross
   // target → importBase-qualified package path.
   const entityFileSpec = entityModuleSpecifier(
     ctx.selfTarget,
     ctx.entityModuleTarget,
-    entity.package,
+    entityPkg,
     entityName,
     ctx.extStyle,
   );
-  const dbImportSpec = relativeModuleSpecifier(ctx.outputLayout, entity.package, ctx.dbImport, ctx.extStyle);
+  const dbImportSpec = relativeModuleSpecifier(ctx.outputLayout, entityPkg, ctx.dbImport, ctx.extStyle);
 
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
@@ -260,10 +262,15 @@ function renderM2mMount(
   ctx: RenderContext,
   fastifyVar: string,
 ): Code {
+  // `source` never changes across this function, so its effective package is computed
+  // once and reused below (both crossEntitySpecifier calls, and the three
+  // resolveJunctionColumn calls' `fromPackage` — see that comment for why it must be
+  // SOURCE's package rather than the junction/target entity's own).
+  const sourcePkg = effectivePackage(source);
   const junctionVarSym = imp(
     `${ctx.collectionName(entry.junctionEntity)}@${crossEntitySpecifier(
       ctx.outputLayout,
-      source.package,
+      sourcePkg,
       ctx.packageOf.get(entry.junctionEntity),
       entry.junctionEntity,
       ctx.extStyle,
@@ -272,7 +279,7 @@ function renderM2mMount(
   const targetVarSym = imp(
     `${ctx.collectionName(entry.targetEntity)}@${crossEntitySpecifier(
       ctx.outputLayout,
-      source.package,
+      sourcePkg,
       ctx.packageOf.get(entry.targetEntity),
       entry.targetEntity,
       ctx.extStyle,
@@ -284,13 +291,13 @@ function renderM2mMount(
   // fromPackage = source.package: this routes file is SOURCE's own module, never the
   // junction's or the target's — see resolveJunctionColumn's doc comment (B1).
   const sourceColumn: Code = junction
-    ? resolveJunctionColumn(junction, entry.sourceJoinField!, ctx, source.package)
+    ? resolveJunctionColumn(junction, entry.sourceJoinField!, ctx, sourcePkg)
     : code`${JSON.stringify(entry.sourceJoinField!)}`;
   const targetColumn: Code = junction
-    ? resolveJunctionColumn(junction, entry.targetJoinField!, ctx, source.package)
+    ? resolveJunctionColumn(junction, entry.targetJoinField!, ctx, sourcePkg)
     : code`${JSON.stringify(entry.targetJoinField!)}`;
   const targetPkColumn: Code = target
-    ? resolveJunctionColumn(target, ctx.pkMap.get(entry.targetEntity)?.fieldName ?? "id", ctx, source.package)
+    ? resolveJunctionColumn(target, ctx.pkMap.get(entry.targetEntity)?.fieldName ?? "id", ctx, sourcePkg)
     : code`${JSON.stringify("id")}`;
 
   return code`  ${mountM2mRouteSym}({
@@ -368,10 +375,11 @@ function renderTphRoutesFile(
   const discField = plan.discriminatorField;
   const tableVar = ctx.collectionName(baseName);
 
+  const basePkg = effectivePackage(base);
   const baseFileSpec = entityModuleSpecifier(
-    ctx.selfTarget, ctx.entityModuleTarget, base.package, baseName, ctx.extStyle,
+    ctx.selfTarget, ctx.entityModuleTarget, basePkg, baseName, ctx.extStyle,
   );
-  const dbImportSpec = relativeModuleSpecifier(ctx.outputLayout, base.package, ctx.dbImport, ctx.extStyle);
+  const dbImportSpec = relativeModuleSpecifier(ctx.outputLayout, basePkg, ctx.dbImport, ctx.extStyle);
 
   const FastifyInstanceSym = imp("t:FastifyInstance@fastify");
   const mountCrudRoutesSym = imp("mountCrudRoutes@@metaobjectsdev/runtime-ts/drizzle-fastify");
@@ -405,7 +413,7 @@ function renderTphRoutesFile(
 
   const subtypeMounts: Code[] = plan.subtypes.map(({ entity: sub, value, routeSegment: segment }) => {
     const subFileSpec = entityModuleSpecifier(
-      ctx.selfTarget, ctx.entityModuleTarget, sub.package, sub.name, ctx.extStyle,
+      ctx.selfTarget, ctx.entityModuleTarget, effectivePackage(sub), sub.name, ctx.extStyle,
     );
     const subInsertSym = imp(`${sub.name}InsertSchema@${subFileSpec}`);
     // FR-036 Program B: the per-subtype UPDATE must carry the FR-035 present-key

package/src/templates/zod-validators.ts

@@ -42,6 +42,7 @@ import { valueObjectModuleSpecifier } from "../import-path.js";
 // FR-035: the SAME required-predicate that drives the Drizzle column's .notNull()
 // drives the UpdateSchema's .nullable() exclusion — shared so they cannot drift.
 import { isRequired } from "../column-mapper.js";
+import { effectivePackage } from "../docs-paths.js";
 
 /**
  * FR-017 Tier 1 — when this object is a TPH subtype (@discriminatorValue set
@@ -593,9 +594,10 @@ function zodFieldExpr(
       // layout/package/extStyle-aware helper (the SAME one the field's TS type +
       // Drizzle .$type<> use) so all three agree. Without owner/ctx (bare
       // unit-test calls) fall back to the bare name + flat same-dir.
-      const refName = (ctx && owner) ? ctx.resolveValueObjectName(ref, fieldDeclaringPackage(field, owner.package)) : stripPackage(ref);
+      const ownerPkg = (ctx && owner) ? effectivePackage(owner) : undefined;
+      const refName = (ctx && owner) ? ctx.resolveValueObjectName(ref, fieldDeclaringPackage(field, ownerPkg)) : stripPackage(ref);
       const moduleSpec = (ctx && owner)
-        ? valueObjectModuleSpecifier(refName, ctx.packageOf, owner.package, ctx.outputLayout, ctx.extStyle)
+        ? valueObjectModuleSpecifier(refName, ctx.packageOf, ownerPkg, ctx.outputLayout, ctx.extStyle)
         : `./${refName}.js`;
       const refImp = imp(`${refName}InsertSchema@${moduleSpec}`);
       let base: Code = code`${refImp}`;
@@ -614,9 +616,10 @@ function zodFieldExpr(
   if (field.subType === FIELD_SUBTYPE_MAP) {
     const ref = field.attr(FIELD_ATTR_OBJECT_REF);
     if (typeof ref === "string" && ref.length > 0) {
-      const refName = (ctx && owner) ? ctx.resolveValueObjectName(ref, fieldDeclaringPackage(field, owner.package)) : stripPackage(ref);
+      const ownerPkg = (ctx && owner) ? effectivePackage(owner) : undefined;
+      const refName = (ctx && owner) ? ctx.resolveValueObjectName(ref, fieldDeclaringPackage(field, ownerPkg)) : stripPackage(ref);
       const moduleSpec = (ctx && owner)
-        ? valueObjectModuleSpecifier(refName, ctx.packageOf, owner.package, ctx.outputLayout, ctx.extStyle)
+        ? valueObjectModuleSpecifier(refName, ctx.packageOf, ownerPkg, ctx.outputLayout, ctx.extStyle)
         : `./${refName}.js`;
       const refImp = imp(`${refName}InsertSchema@${moduleSpec}`);
       return appendValidatorChain(code`z.record(z.string(), ${refImp})`, field, forceRequired);

package/src/ui-tier-gate.ts

@@ -0,0 +1,79 @@
+import type { Generator } from "./generator.js";
+
+/**
+ * Generators that emit a CLIENT UI artifact — a form, a hook, a grid or its columns.
+ *
+ * Names, not identities, for the same reason `PROMPT_GENERATOR_NAMES` uses names: under
+ * ADR-0034 scaffold-and-own an adopter runs their OWN copy, and `meta eject` copies the
+ * template verbatim, so the name survives the copy while the object identity does not.
+ *
+ * This set exists ONLY as a compatibility path for a copy ejected before `emitsUiTier`
+ * existed. The marker is the mechanism; a name match makes the run behave as it did
+ * before AND says the marker is missing (see {@link warnUnmarkedUiGenerators}), because
+ * a page silently disappearing is exactly the kind of degradation that must announce
+ * itself.
+ */
+export const UI_TIER_GENERATOR_NAMES: ReadonlySet<string> = new Set([
+  "form-file",
+  "tanstack-query",
+  "tanstack-grid",
+  "tanstack-grid-hook",
+  "angular-form",
+  "angular-grid",
+  "angular-service",
+]);
+
+/** Generators in the suite that emit a UI artifact but carry no `emitsUiTier` marker. */
+function unmarked(generators: readonly Generator[]): Generator[] {
+  return generators.filter(
+    (g) => g.emitsUiTier !== true && UI_TIER_GENERATOR_NAMES.has(g.name),
+  );
+}
+
+/**
+ * Does this run emit a client UI tier?
+ *
+ * The declared marker OR the legacy name. `agent/ui.md` gates on the answer: its own
+ * predicate was metadata-only (`servesReadApi`), which says a UI *could* be generated
+ * for an object and never that this run generates one — so a project with
+ * `generators: []` was handed a confident page naming endpoints nothing serves.
+ */
+export function runEmitsUiTier(generators: readonly Generator[]): boolean {
+  return generators.some((g) => g.emitsUiTier === true) || unmarked(generators).length > 0;
+}
+
+/**
+ * A generator ejected before `emitsUiTier` existed still emits its tier, so the run is
+ * NOT degraded — the name match above keeps `agent/ui.md` emitting. It is warned about
+ * anyway: an adopter who renames their copy loses the page with no signal at all, and
+ * the one-line fix belongs where the fact is known rather than in a migration note
+ * nobody re-reads. Self-extinguishing — adding the marker silences it forever.
+ */
+export function warnUnmarkedUiGenerators(
+  generators: readonly Generator[],
+  warn: (msg: string) => void,
+): void {
+  const stale = unmarked(generators);
+  if (stale.length === 0) return;
+  const names = stale.map((g) => `'${g.name}'`).join(", ");
+  warn(
+    `${names} emit${stale.length === 1 ? "s" : ""} a UI artifact but carr${stale.length === 1 ? "ies" : "y"} no ` +
+      `'emitsUiTier: true' marker — an owned copy ejected before the marker existed. ` +
+      `agent/ui.md still emits (matched by name), but a renamed copy would not: add ` +
+      `'emitsUiTier: true' beside 'name:' in your copy, or re-eject it.`,
+  );
+}
+
+/**
+ * Does this run emit the OPT-IN Hono routes surface?
+ *
+ * Lives beside `runEmitsUiTier` for one reason: both are "aggregate a marker across the
+ * suite", and both were being re-derived at the `meta docs` door — which read the RAW
+ * config, where a generator wired by stable name (`generators: ["routes-hono"]`, legal
+ * under ADR-0021 #1) is a string carrying no marker at all. So `api-docs` omitted the
+ * Hono surface for a project that had wired it. One helper, called after the strings are
+ * resolved, is what stops the two doors disagreeing again.
+ */
+export function runEmitsHonoRoutes(generators: readonly Generator[]): boolean {
+  return generators.some((g) => g.emitsHonoRoutes === true);
+}