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

package/src/routes-expose.ts

@@ -0,0 +1,86 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+
+/**
+ * The five CRUD verbs a generated routes file can mount.
+ *
+ * Mirrors `CrudVerb` in `@metaobjectsdev/runtime-ts` — both the fastify and hono mount
+ * modules declare it identically. It is RESTATED rather than imported because codegen-ts
+ * does not depend on runtime-ts: codegen emits a call to that helper, it never links
+ * against it. Pinned against both runtime declarations by test/routes-expose.test.ts, so
+ * the two cannot drift the way the cell-renderer keys drifted from the view registry.
+ */
+export const CRUD_VERBS = ["list", "get", "create", "update", "delete"] as const;
+
+/**
+ * The verbs a TPH discriminator BASE serves at its own path.
+ *
+ * Read-only BY CONSTRUCTION: the discriminated union has no single writable shape, so the
+ * base mount can never carry `create`/`update`/`delete` — an author-supplied `expose`
+ * INTERSECTS with this set rather than replacing it, and may narrow to just `list`.
+ * Writes live on the per-subtype mounts at `<base path>/<segment>`.
+ *
+ * Named here because two places need it and a second literal would be a second answer:
+ * `routes-file.ts` emits the mount, and `api-model.ts` documents it. They disagreed —
+ * the api surface documented POST/PATCH/DELETE on a base path that serves none, under a
+ * comment claiming the documented paths "match the generated routes exactly".
+ */
+export const TPH_POLYMORPHIC_VERBS = ["list", "get"] as const;
+export type CrudVerb = (typeof CRUD_VERBS)[number];
+
+/**
+ * Which CRUD verbs a generated routes file mounts (#348).
+ *
+ * A `filter` cannot express this. `filter` decides whether the file emits AT ALL, per
+ * entity, so it can only remove the whole surface; restricting to a SUBSET of verbs is a
+ * different axis. That is why this is a generator option rather than the "narrow it with
+ * `filter`" remedy that answered the retired `@emit*` attributes — the same reasoning that
+ * made a TPH subtype's opt-IN grid `tphSubtypeGrids` rather than a filter.
+ *
+ * It is deliberately NOT metadata. Which verbs a deployment exposes is a property of the
+ * app, not of the model: the same entity is read-only in one service and writable in
+ * another, and an attribute would force one answer into the shared spine.
+ *
+ * Absent — or a function returning `undefined` for an entity — means all five, and emits
+ * output byte-identical to before this option existed.
+ */
+export type ExposeOption =
+  | readonly CrudVerb[]
+  | ((entity: MetaObject) => readonly CrudVerb[] | undefined);
+
+/** Resolve the option for one entity. `undefined` means "mount all five". */
+export function resolveExpose(
+  entity: MetaObject,
+  expose: ExposeOption | undefined,
+): readonly CrudVerb[] | undefined {
+  if (expose === undefined) return undefined;
+  return typeof expose === "function" ? expose(entity) : expose;
+}
+
+/**
+ * Narrow a mount whose verb set is already fixed by construction.
+ *
+ * A TPH polymorphic mount is read-only (`["list", "get"]`) because the discriminated union
+ * has no single writable shape. An author-supplied `expose` may narrow that further but
+ * must never widen it, so this INTERSECTS rather than replaces: mounting `create` on a
+ * surface that cannot serve it would emit a route that fails at runtime, and a wrong
+ * endpoint is worse than a missing one.
+ */
+export function intersectExpose(
+  fixed: readonly CrudVerb[],
+  requested: readonly CrudVerb[] | undefined,
+): readonly CrudVerb[] {
+  if (requested === undefined) return fixed;
+  const want = new Set<string>(requested);
+  return fixed.filter((v) => want.has(v));
+}
+
+/**
+ * The `expose: [...]` line for a mount call, or "" when every verb mounts.
+ *
+ * Emitting nothing rather than the full list keeps output byte-identical for every
+ * project that does not use the option.
+ */
+export function exposeLine(verbs: readonly CrudVerb[] | undefined, indent: string): string {
+  if (verbs === undefined) return "";
+  return `\n${indent}expose: [${verbs.map((v) => JSON.stringify(v)).join(", ")}],`;
+}

package/src/runner.ts

@@ -1,5 +1,6 @@
 import { join, relative, resolve, isAbsolute, dirname } from "node:path";
 import { warnMissingPromptGenerators } from "./prompt-generator-gate.js";
+import { warnRetiredCodegenAttrs } from "./retired-codegen-attrs.js";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { existsSync, readFileSync } from "node:fs";
@@ -7,6 +8,7 @@ import type { MetaData, MetaObject } from "@metaobjectsdev/metadata";
 import { isMetaRoot, OBJECT_SUBTYPE_VALUE, FIELD_SUBTYPE_TIMESTAMP, FIELD_ATTR_FILTERABLE } from "@metaobjectsdev/metadata";
 import { assignEmittedNames } from "./naming/collision-names.js";
 import { isAbstract } from "./instance-artifacts.js";
+import { dbEmittingObjects, missingDialectMessage } from "./db-emitting.js";
 import { hasAnyRdbSource } from "./source-detect.js";
 import type { Generator, GenContext, EmittedFile } from "./generator.js";
 import type { MetaobjectsGenConfig } from "./metaobjects-config.js";
@@ -128,6 +130,50 @@ function engineVersion(): string | undefined {
   }
 }
 
+/** The release in which `$apiPrefix` left the generated entity descriptor. */
+const BASE_URL_MOVE_VERSION = "0.25.0";
+
+/** `N.N.N` only. Anything else — a prerelease tag, a sentinel — is deliberately unordered. */
+function orderable(v: string | undefined): [number, number, number] | undefined {
+  if (v === undefined) return undefined;
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v);
+  return m === null ? undefined : [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * True exactly on the FIRST gen after upgrading past the release that moved the API base
+ * URL out of the entity descriptor, and only for a project that actually had a prefix to
+ * move. Exported for test.
+ *
+ * Keyed on the #232 engine stamp rather than on `apiPrefix` alone so the note is
+ * self-extinguishing: whether the app passed `baseUrl` to its provider is runtime code
+ * `meta gen` cannot see, so a prefix-only trigger would nag for ever with no way to
+ * satisfy it — the cry-wolf failure that got the `timestampMode` warning deleted from
+ * this file (see `codegen-ts-tanstack/src/data-grid-gate.ts`).
+ *
+ * Silence is the default for an absent or unorderable recorded version. That is the
+ * OPPOSITE call to the 0.24.5 agent-context staleness nudge, and deliberately: there an
+ * unknown version meant "cannot prove it is fresh, so nudge"; here it means "no gen
+ * history, so nothing to migrate", and a false nag costs more than a missed one when the
+ * compile break already routes the adopter to the same line.
+ */
+export function shouldNoteBaseUrlMove(
+  apiPrefix: string,
+  recordedEngine: string | undefined,
+  moveVersion: string = BASE_URL_MOVE_VERSION,
+): boolean {
+  if (apiPrefix === "") return false;
+  const was = orderable(recordedEngine);
+  const move = orderable(moveVersion);
+  if (was === undefined || move === undefined) return false;
+  for (let i = 0; i < 3; i++) {
+    const a = was[i] as number;
+    const b = move[i] as number;
+    if (a !== b) return a < b;
+  }
+  return false;
+}
+
 export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   const warnings: string[] = [];
   const strategy = opts.mergeStrategy ?? "overwrite";
@@ -260,16 +306,9 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // projects — the error even told them their model "generates database code"
   // that in fact imported nothing. It is demanded below at the point of USE, by
   // the generator that reads it, which the runner names in the thrown message.
-  const dbEmittingObjects = safeEntities.filter(
-    (e) => !e.isAbstract && hasAnyRdbSource(e),
-  );
-  if (dbEmittingObjects.length > 0 && opts.config.dialect === undefined) {
-    const names = dbEmittingObjects.map((e) => e.name).join(", ");
-    throw new Error(
-      `codegen config is missing dialect — required because this model ` +
-        `generates database code for: ${names}. Set dialect in ` +
-        `metaobjects.config.ts. (A model of only value objects and/or sourceless projections may omit it.)`,
-    );
+  const dbEmitting = dbEmittingObjects(safeEntities);
+  if (dbEmitting.length > 0 && opts.config.dialect === undefined) {
+    throw new Error(missingDialectMessage(dbEmitting));
   }
 
   /** Did the AUTHOR declare a dbImport reachable by this target? Tracked, never
@@ -282,6 +321,19 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // 2. Resolve targets + entity-module target.
   const config = normalizeConfig(opts.config);
 
+  // The compile break (`value` → `fetcher` on the provider) sends an adopter to the right
+  // line; this names the value to put there, once, for the projects that had one.
+  if (shouldNoteBaseUrlMove(config.apiPrefix, recordedEngine)) {
+    warnings.push(
+      `apiPrefix ${JSON.stringify(config.apiPrefix)} no longer reaches the client — ` +
+        `generated hooks and services emit entity-relative paths. Supply it once at the ` +
+        `provider: <EntityFetcherProvider fetcher={...} baseUrl=${JSON.stringify(config.apiPrefix)}> ` +
+        `(Angular: provideEntityFetcher({ fetcher, baseUrl: ${JSON.stringify(config.apiPrefix)} })). ` +
+        `Server routes still mount under apiPrefix and are unaffected. ` +
+        `See docs/features/migrations/api-base-url-leaves-the-entity-descriptor.md`,
+    );
+  }
+
   // (Historical: a warning stood here for a @filterable timestamp under
   // timestampMode:"date", which used to throw at REQUEST time in runtime-ts's
   // filter parser. That limitation is fixed — the generated allowlist now carries
@@ -367,11 +419,36 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // CRUD surface it actually emits (rather than silently omitting it).
   const includeHonoRoutes = config.generators.some((g) => g.emitsHonoRoutes === true);
 
+  // §A6 — same auto-detection for the OPT-IN names generator. The entity tier may only
+  // REFERENCE `<Entity>Names` when something in this run actually emits it; the names
+  // generator is opt-in under ADR-0034 (meta gen runs the adopter's own copies), so an
+  // unconditional import would break every project that has not added it. Surfaced BOTH
+  // on ctx.config (the field reference/names.ts documents, and the shape a third-party
+  // generator reads) and on every RenderContext below (what the templates can actually
+  // see) — one aggregation, two consumers.
+  //
+  // Scoped BY TARGET, unlike includeHonoRoutes, because the two flags are read for
+  // different reasons: api-docs asks "is this surface in the run?", while a template
+  // referencing these constants emits a RELATIVE import at its own target's path. The
+  // names artifact is not a registered cross-target module (there is no importBase route
+  // to it), so `entityFile({ target: "db" })` beside a default-target `namesFile()` would
+  // otherwise emit `./<Entity>.names` from a directory that does not hold one.
+  const namesTargets = new Set(
+    config.generators.filter((g) => g.emitsNames === true).map((g) => targetOf(g).name),
+  );
+
   // A declared template.prompt with no prompt generator wired emits nothing and, before
   // this, said nothing — while `meta verify` reported the template "clean". See
   // prompt-generator-gate.ts. Self-extinguishing; warning only.
   warnMissingPromptGenerators(root, config.generators, (m) => warnings.push(m));
 
+  // A retired `@emit*` codegen flag still sitting in the metadata suppresses nothing now.
+  // Named here rather than left to be discovered as a file that reappeared. Scoped to
+  // the run's own entity set (the same set every generator sees), so `meta gen <entity>`
+  // reports on what it just generated rather than on objects it was told to skip.
+  // See retired-codegen-attrs.ts. Self-extinguishing; warning only.
+  warnRetiredCodegenAttrs(safeEntities, (m) => warnings.push(m));
+
   // 4. Run each generator with a per-target render context; collect with full path.
   const emitted: { fullPath: string; content: string; generatedBy: string }[] = [];
   // FR-038 §8 — generators that opted into orphan reconciliation, paired with the
@@ -421,6 +498,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       apiPrefix: config.apiPrefix,
       emitAbstractShapes: config.emitAbstractShapes,
       outputLayout: selfTarget.outputLayout,
+      includeNames: namesTargets.has(selfTarget.name),
       pkMap,
       relationMap,
       packageOf,
@@ -440,6 +518,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         dialect: config.dialect,
         outputLayout: selfTarget.outputLayout,
         includeHonoRoutes,
+        includeNames: namesTargets.has(selfTarget.name),
       },
       renderContext,
       ...(projectRoot !== undefined && { projectRoot }),
@@ -470,7 +549,11 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       files = await generator.generate(ctx);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      throw new Error(`[${generator.name}] ${msg}`);
+      // `cause` preserves the original throw. Without it a `runGen` caller sees a
+      // plain Error carrying only the prefixed message, so it cannot tell a
+      // CodegenError (a metadata/config problem it can report) from a genuine bug
+      // in a generator, and every stack trace stops at this line.
+      throw new Error(`[${generator.name}] ${msg}`, { cause: err });
     }
 
     for (const file of files) {
@@ -544,6 +627,34 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         `Refused to overwrite ${w.path}: ${w.conflictHint ?? "content differs and could not be verified as generated."}`,
       );
     }
+
+    // The recovery, ONCE — for the same reason the no-manifest branch above aggregates:
+    // it is the same three commands whether one file refused or sixteen, and repeating
+    // it per file buries it.
+    //
+    // It is stated as a SEQUENCE rather than a menu because there is exactly one way to
+    // keep an edit here and it is not obvious: a three-way merge needs a base, the
+    // `.gen-state` bodies are gitignored, and this machine has none — so the base has to
+    // be manufactured first. `--baseline=fresh` writes fresh output AND seeds the missing
+    // snapshot; restoring the file from git then puts the edit back with a base now
+    // present, and the next run merges it. Verified end to end (refused → overwrite →
+    // merged, edit intact).
+    //
+    // Two remedies were removed from the per-file hint and are not restored here as
+    // universal advice. "Move the edit into a non-generated file" holds only where the
+    // edit CAN live elsewhere — a `requirementTests()` stub's body cannot, because the
+    // test name is the link to the requirement and the stub's own header forbids renaming
+    // it. "--baseline=fresh" alone is a discard, and is named as one.
+    warnings.push(
+      `To KEEP your version of the file(s) above, the edit must be committed first — ` +
+      `then: 'meta gen --baseline=fresh' (writes fresh output over them and seeds the ` +
+      `missing .gen-state snapshot), 'git checkout -- <paths>' to bring your version back, ` +
+      `then 'meta gen' again — the snapshot now exists, so the edit merges. ` +
+      `To DISCARD your version instead, '--baseline=fresh' on its own is the whole answer. ` +
+      `Moving the edit into a non-generated file works only where the edit can live outside ` +
+      `the generated one; a requirementTests() stub's body cannot, since the test name is ` +
+      `its link to the requirement.`,
+    );
   };
 
   const sweep = (dryRun: boolean): void => {

package/src/templates/callable-file.ts

@@ -7,7 +7,7 @@
 //   import { PhaseSummarySchema, type PhaseSummary } from "./PhaseSummary.js";
 //
 //   export async function callPhaseSummary(
-//     db: PgDatabase<PgQueryResultHKT, Record<string, never>>,
+//     db: PgDatabase<PgQueryResultHKT, Record<string, unknown>>,
 //     args: PhaseSummaryArgs,
 //   ): Promise<PhaseSummary[]> {
 //     const r = await db.execute(
@@ -20,6 +20,7 @@
 // `args` parameter and calls `fn_x()`.
 
 import {
+  primaryRdbSource,
   type MetaObject,
   type MetaSource,
   isMetaSource,
@@ -31,6 +32,9 @@ import {
   OBJECT_SUBTYPE_VALUE,
 } from "@metaobjectsdev/metadata";
 import { GENERATED_HEADER } from "../constants.js";
+import { crossEntitySpecifier } from "../import-path.js";
+import { resolveObjectNames } from "../names.js";
+import type { RenderContext } from "../render-context.js";
 
 const CALLABLE_KINDS: ReadonlySet<string> = new Set([
   SOURCE_KIND_STORED_PROC,
@@ -57,8 +61,24 @@ function callableSource(entity: MetaObject): MetaSource | undefined {
 }
 
 /** Render the full file content for an entity's callable wrapper. Caller
- *  is responsible for formatting (prettier / biome) and writing to disk. */
-export function renderCallableFile(entity: MetaObject): string {
+ *  is responsible for formatting (prettier / biome) and writing to disk.
+ *
+ *  `ctx` is optional only so the pre-existing callers that render a wrapper in isolation
+ *  keep compiling; with it absent the physical name is spelled literally, which is the
+ *  same documented fallback as running with `namesFile()` out of the suite. */
+export function renderCallableFile(entity: MetaObject, ctx?: RenderContext): string {
+  // Run the primary-source DIVERGENCE refusal before resolving a physical name.
+  // `callableSource` selects by @kind with NO role filter, so it is a THIRD door into
+  // "what relation does this object name" — and it is reached by `callableFile()` alone,
+  // with no table-name resolver anywhere on the path. Without this an object whose
+  // @role: primary sources disagree emitted a wrapper bound to the inherited parent's
+  // procedure, on a model every other tier refuses. A refusal that depends on which
+  // generators ran is not a refusal.
+  //
+  // The SELECTION below is deliberately unchanged: divergence is about the NAME, while
+  // this function additionally asks "which source is callable?". Same shape as
+  // MetaObject.dbTable and the JVM/C# findPrimaryWritableSource.
+  primaryRdbSource(entity);
   const source = callableSource(entity);
   if (source === undefined) {
     throw new Error(
@@ -95,6 +115,30 @@ export function renderCallableFile(entity: MetaObject): string {
     ? ""
     : paramFieldNames.map((n) => `\${args.${n}}`).join(", ");
 
+  // §A6 — reference `<Entity>Names.sources.primary.proc` rather than spelling the
+  // procedure a SECOND time.
+  // This file is a raw string template rather than ts-poet, so the import is composed here
+  // instead of through `imp`; `crossEntitySpecifier` is the same helper `namesRef` uses, so
+  // the specifier (and its extension style) cannot drift from every other generator's.
+  const namesConst =
+    ctx !== undefined && ctx.includeNames &&
+    resolveObjectNames(entity, ctx.columnNamingStrategy) !== undefined
+      ? `${entity.name}Names`
+      : undefined;
+  const namesImport = namesConst === undefined
+    ? ""
+    : `import { ${namesConst} } from "${crossEntitySpecifier(
+        ctx!.selfTarget.outputLayout, entity.package, entity.package,
+        `${entity.name}.names`, ctx!.extStyle,
+      )}";\n`;
+  // The identifier must stay an IDENTIFIER. A bare interpolation into drizzle's `sql` tag
+  // binds a PARAMETER, so `sql`SELECT * FROM ${Names.sources.primary.proc}(…)`` would send the procedure
+  // name as a query argument and produce SQL that cannot execute. `sql.raw` splices text.
+  // `sql.identifier` is deliberately not used: it quotes, which changes the statement.
+  const procNameExpr = namesConst === undefined
+    ? procName
+    : `\${${"sql.raw"}(${namesConst}.name)}`;
+
   const fnName = `call${entity.name}`;
   const projectionType = entity.name;
   const projectionSchemaName = `${entity.name}Schema`;
@@ -105,23 +149,31 @@ export function renderCallableFile(entity: MetaObject): string {
     ? `import type { ${argsObjectName} } from "./${argsObjectName}.js";\n`
     : "";
 
+  // The `db` parameter type carries the same open-type-argument rule as the queries
+  // file's `Db` alias (see templates/queries-file.ts `dbTypeBlock`): `PgDatabase` is the
+  // base every PG driver extends, and the schema parameter stays at Drizzle's own bound
+  // `Record<string, unknown>` — NOT its `Record<string, never>` default, which rejects the
+  // idiomatic `drizzle(client, { schema })` db with TS2345 and makes this callable
+  // uninvokable. Uncompilable generated code is indistinguishable from unused generated
+  // code, so this parameter must never be narrowed back.
   const signature = argsObject
-    ? `db: PgDatabase<PgQueryResultHKT, Record<string, never>>, args: ${argsObjectName}`
-    : `db: PgDatabase<PgQueryResultHKT, Record<string, never>>`;
+    ? `db: PgDatabase<PgQueryResultHKT, Record<string, unknown>>, args: ${argsObjectName}`
+    : `db: PgDatabase<PgQueryResultHKT, Record<string, unknown>>`;
 
   return `// ${GENERATED_HEADER}
 import { sql } from "drizzle-orm";
 import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
-${argsImport}import { ${projectionSchemaName}, type ${projectionType} } from "./${entity.name}.js";
+${namesImport}${argsImport}import { ${projectionSchemaName}, type ${projectionType} } from "./${entity.name}.js";
 
 /**
- * FR-015: typed wrapper around the \`${procName}\` ${source.effectiveKind === SOURCE_KIND_STORED_PROC ? "stored procedure" : "table function"}.
+ * FR-015: typed wrapper around the ${source.effectiveKind === SOURCE_KIND_STORED_PROC ? "stored procedure" : "table function"} named by
+ * \`${namesConst === undefined ? procName : `${namesConst}.name`}\`.
  * Drizzle passes a parameterised SELECT — args bind in declaration order from
  * the @parameterRef value-object${argsObject ? `, here ${argsObjectName}` : ""}.
  */
 export async function ${fnName}(${signature}): Promise<${projectionType}[]> {
   const r = await db.execute(
-    sql\`SELECT * FROM ${procName}(${sqlArgList})\`,
+    sql\`SELECT * FROM ${procNameExpr}(${sqlArgList})\`,
   );
   return r.rows.map((row) => ${projectionSchemaName}.parse(row as unknown));
 }