refactor(codegen-ts): apply pre-merge review findings to templateGenerator

Acts on the consensus findings from the code-review and code-simplifier
passes on the rc.12 templateGenerator() factory + docsFile() refactor.
All 497 codegen-ts tests still green; docs-file-basic byte-identity
gate preserved.

Findings applied (numbered per the agent reports):

#1 — drop the walk-mutation cleverness in docs-file.ts.
The rc.12 docsFile() wrapped templateGenerator() and mutated
tgOpts.walk per generate() call. Concurrency-unsafe (two docs-file
generators against different targets would race) and obscured the
intent. Replaced with a direct render() + projectProvider() call,
which is shorter than the wrapper anyway. The cross-port pillar of
"templateGenerator for ctx-free walks" is unaffected — other adopters
still use the factory; docs-file is a peer that needs ctx for the
outputLayout-driven path.

#2 — thread project root through GenContext.
Adds `projectRoot?: string` to GenContext, populated by the runner
from opts.projectRoot. templateGenerator() and docsFile() now read
ctx.projectRoot instead of process.cwd(). Falls back to cwd with a
ctx.warn() naming the problem ("running `meta gen` from a sub-dir
breaks project-template overrides"). Critical reviewer finding — a
silent foot-gun in the rc.12 release.

#3 — wrap render() with error context.
Both templateGenerator() and docsFile() now wrap render() in
try/catch that prepends `${generator name} on ${output path}: …` so
template-resolution failures surface a useful breadcrumb. Preserves
the original error as `cause`.

#4 — assert canonical template exists in findFrameworkTemplatesDir.
The walk-up to find codegen-ts's package.json could land on a
CONSUMER's package.json under hoisted pnpm/bun installs and silently
return a templates dir that doesn't exist. Now asserts the canonical
docs/entity-page.md.mustache lives at the candidate templates dir
before returning; throws with SELF_DIR in the message if not.

#7 — collapse three field.validators() loops into one.
constraintsCell in docs-data-builder.ts walked field.validators()
three times to bucket regex / length / numeric. One pass into three
local arrays, then emit in the original order (regex → maxLength-attr
→ length → numeric) to keep byte-identity with docs-file-basic.

#8 — drop the defensive try/catch around fileURLToPath in
framework-provider.ts. Per CLAUDE.md the project is ESM-only;
import.meta.url is guaranteed to be a file: URL. Defensive code for
an impossible state was muddying the contract.

#9 — drop the magic `for (let i = 0; i < 12; i++)` loop cap in
findFrameworkTemplatesDir. The parent-equals-self guard is the right
termination; the 12-iteration cap was arbitrary and would silently
return the wrong dir in deeply-nested workspaces.

#10 — clean test imports in template-generator.test.ts. Drop the
`void TYPE_OBJECT; void OBJECT_SUBTYPE_ENTITY;` dead-code suppressors
that were masking unused imports; consolidate two separate import
statements from @metaobjectsdev/metadata into one.

Held for separate follow-up (not in this commit):

- Finding #5: EntityDocData over-exposing Markdown-flavored fields as
  "public contract" — wants a deliberate split into structural +
  Markdown layers. API-surface decision worth a moment of design
  thought.
- Finding #6: the `as unknown as { referencesRaw?: string }` cast on
  MetaIdentity — would benefit from properly exposing referencesRaw
  on the typed interface.
- Finding #11: test gaps for missing-template error, provider override
  precedence, and conformance-perf single-render-per-fixture.

Verification:
  bun run --filter '@metaobjectsdev/codegen-ts' typecheck — clean
  bun test packages/codegen-ts — 497/497 pass, 1809 expect() calls
  (includes templateGenerator unit tests, conformance harness,
  docs-file-basic byte-identity golden gate)

Author: dmealing

server/typescript/packages/codegen-ts/src/generator.ts

@@ -24,6 +24,15 @@ export interface GenContext {
    *  present at run time when invoked via runGen(); optional in the type
    *  so tests and custom callers don't need a placeholder. */
   renderContext?: RenderContext;
+  /** Resolved absolute project root — what the runner derives from
+   *  `opts.projectRoot` (the directory holding `.metaobjects/config.json`).
+   *  Generators that resolve project-scoped resources (e.g.
+   *  `templateGenerator` looking up the project's `templates/` directory)
+   *  should read this rather than `process.cwd()`, which is whatever
+   *  directory the CLI was invoked from and breaks when `meta gen` runs
+   *  in a sub-directory. Undefined only when the runner was driven
+   *  programmatically without an explicit projectRoot. */
+  projectRoot?: string;
   warn: (msg: string) => void;
 }
 

server/typescript/packages/codegen-ts/src/generators/docs-data-builder.ts

@@ -188,36 +188,37 @@ function constraintsCell(
     }
   }
 
+  // Walk validators once, bucket by subtype. We re-emit in the original
+  // emission order to preserve byte-identity with the docs-file-basic
+  // conformance fixture: regex pattern → maxLength-from-@maxLength →
+  // length-validator (min/max) → numeric-validator (min/max).
+  const maxLenAttr = field.ownAttr(FIELD_ATTR_MAX_LENGTH);
+  const regexParts: string[] = [];
+  const lengthParts: string[] = [];
+  const numericParts: string[] = [];
   for (const v of field.validators()) {
     if (v.subType === VALIDATOR_SUBTYPE_REGEX) {
       const pattern = v.ownAttr(VALIDATOR_ATTR_PATTERN);
       if (typeof pattern === "string" && pattern.length > 0) {
-        parts.push(`pattern \`${pattern}\``);
+        regexParts.push(`pattern \`${pattern}\``);
       }
-    }
-  }
-
-  const maxLenAttr = field.ownAttr(FIELD_ATTR_MAX_LENGTH);
-  if (typeof maxLenAttr === "number") {
-    parts.push(`maxLength: ${maxLenAttr}`);
-  }
-  for (const v of field.validators()) {
-    if (v.subType === VALIDATOR_SUBTYPE_LENGTH) {
+    } else if (v.subType === VALIDATOR_SUBTYPE_LENGTH) {
       const min = v.ownAttr(VALIDATOR_ATTR_MIN);
       const max = v.ownAttr(VALIDATOR_ATTR_MAX);
-      if (typeof min === "number") parts.push(`minLength: ${min}`);
-      if (typeof max === "number" && typeof maxLenAttr !== "number") parts.push(`maxLength: ${max}`);
-    }
-  }
-
-  for (const v of field.validators()) {
-    if (v.subType === VALIDATOR_SUBTYPE_NUMERIC) {
+      if (typeof min === "number") lengthParts.push(`minLength: ${min}`);
+      if (typeof max === "number" && typeof maxLenAttr !== "number") lengthParts.push(`maxLength: ${max}`);
+    } else if (v.subType === VALIDATOR_SUBTYPE_NUMERIC) {
       const min = v.ownAttr(VALIDATOR_ATTR_MIN);
       const max = v.ownAttr(VALIDATOR_ATTR_MAX);
-      if (typeof min === "number") parts.push(`min: ${min}`);
-      if (typeof max === "number") parts.push(`max: ${max}`);
+      if (typeof min === "number") numericParts.push(`min: ${min}`);
+      if (typeof max === "number") numericParts.push(`max: ${max}`);
     }
   }
+  parts.push(...regexParts);
+  if (typeof maxLenAttr === "number") {
+    parts.push(`maxLength: ${maxLenAttr}`);
+  }
+  parts.push(...lengthParts, ...numericParts);
 
   const fk = fkMap.get(field.name);
   if (fk !== undefined) {

server/typescript/packages/codegen-ts/src/generators/docs-file.ts

@@ -1,23 +1,28 @@
 // docsFile() — emits `<Entity>.md` next to each generated entity module.
 //
-// rc.12+: refactored to use templateGenerator(). The Markdown structure now
-// lives in `templates/docs/entity-page.md.mustache`; the data extraction lives
-// in `buildEntityDocData()`. Adopters can override the framework template by
-// dropping their own `templates/docs/entity-page.md.mustache` into the project
-// root (resolved via the project-then-framework provider chain).
+// rc.12+: structured around a shared Mustache template at
+// `templates/docs/entity-page.md.mustache` + a data builder at
+// `docs-data-builder.ts`. Adopters can override the framework template by
+// dropping their own `templates/docs/entity-page.md.mustache` into the
+// project root (resolved via the project-then-framework provider chain).
+//
+// docsFile() calls `render()` directly rather than wrapping
+// `templateGenerator()` because the per-entity output path depends on
+// `GenContext.config.outputLayout`, which the generic templateGenerator
+// `walk(root)` signature doesn't expose. Other future docs-style adopters
+// with ctx-free walks (single-file aggregators, etc.) compose
+// `templateGenerator()` directly.
 //
 // The conformance fixture (`fixtures/conformance/docs-file-basic`) gates
-// byte-identity through the refactor — the codegen output must match the
-// hand-coded rc.11 byte-for-byte. If you're hacking on this and the
-// conformance test breaks, the refactor is the bug, not the fixture.
+// byte-identity — the codegen output must match the hand-coded rc.11
+// byte-for-byte. If you're hacking on this and the conformance test
+// breaks, the refactor is the bug, not the fixture.
 
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import type { Generator, GeneratorFactory, GenContext } from "../generator.js";
+import { render } from "@metaobjectsdev/render";
+import type { Generator, GeneratorFactory } from "../generator.js";
 import { entityOutputPath } from "../import-path.js";
-import {
-  templateGenerator,
-  type TemplateGeneratorOpts,
-} from "./template-generator.js";
+import { projectProvider } from "../render-engine/framework-provider.js";
 import { buildEntityDocData } from "./docs-data-builder.js";
 
 export interface DocsFileOpts {
@@ -35,48 +40,45 @@ const KNOWN_SIBLING_GENERATORS = new Set([
   "routes-file-hono",
 ]);
 
-export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
-  // We can't fully delegate to templateGenerator's `walk(root)` because the
-  // per-entity output path depends on the runtime `outputLayout` (flat /
-  // package), which only lives on `GenContext.config`. So docsFile wraps
-  // templateGenerator and threads ctx through.
-  const tgOpts: TemplateGeneratorOpts = {
-    name: "docs-file",
-    template: "docs/entity-page.md",
-    format: "markdown",
-    walk: () => [], // placeholder — real walk happens inside generate() below
-  };
-  const inner = templateGenerator(tgOpts);
+const TEMPLATE_REF = "docs/entity-page.md";
 
+export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
   const generator: Generator = {
     name: "docs-file",
-    async generate(ctx: GenContext) {
+    async generate(ctx) {
       if (!ctx.renderContext) {
         throw new Error("docs-file: renderContext is required (provided by runGen)");
       }
       const rc = ctx.renderContext;
-      // Drive the templateGenerator by populating its walk via closure.
-      const realWalk = (root: typeof ctx.loadedRoot) =>
-        root.objects().filter(ctx.matches).map((entity: MetaObject) => ({
-          data: buildEntityDocData(entity, {
-            dialect: rc.dialect,
-            ...(rc.columnNamingStrategy !== undefined
-              ? { columnNamingStrategy: rc.columnNamingStrategy }
-              : {}),
-            loadedRoot: rc.loadedRoot,
-            generatorNames: KNOWN_SIBLING_GENERATORS,
+      const provider = projectProvider(ctx.projectRoot ?? process.cwd());
+      const layout = ctx.config.outputLayout ?? "flat";
+      return ctx.loadedRoot.objects().filter(ctx.matches).map((entity: MetaObject) => {
+        const path = entityOutputPath(layout, entity.package, `${entity.name}.md`);
+        const payload = buildEntityDocData(entity, {
+          dialect: rc.dialect,
+          ...(rc.columnNamingStrategy !== undefined && {
+            columnNamingStrategy: rc.columnNamingStrategy,
           }),
-          outputPath: entityOutputPath(
-            ctx.config.outputLayout ?? "flat",
-            entity.package,
-            `${entity.name}.md`,
-          ),
-        }));
-      // Hot-swap walk on the underlying templateGenerator. (The factory
-      // closes over `opts.walk`, so we mutate the options object's walk
-      // reference here.)
-      (tgOpts as { walk: typeof realWalk }).walk = realWalk;
-      return inner.generate(ctx);
+          loadedRoot: rc.loadedRoot,
+          generatorNames: KNOWN_SIBLING_GENERATORS,
+        });
+        let content: string;
+        try {
+          content = render({
+            ref: TEMPLATE_REF,
+            payload,
+            provider,
+            format: "markdown",
+          });
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          throw new Error(
+            `docs-file: failed rendering '${TEMPLATE_REF}' for '${path}': ${msg}`,
+            { cause: err instanceof Error ? err : undefined },
+          );
+        }
+        return { path, content };
+      });
     },
   };
   if (opts?.filter) generator.filter = opts.filter;

server/typescript/packages/codegen-ts/src/generators/template-generator.ts

@@ -47,10 +47,11 @@ export interface TemplateGeneratorOpts {
    *  default `walk` — adopters apply filters inside their walk function. */
   filter?: (entity: MetaObject) => boolean;
   /** Override the Provider used for template resolution. When omitted the
-   *  generator resolves via `projectProvider(<projectRoot>)`, which layers
+   *  generator resolves via `projectProvider(ctx.projectRoot)`, which layers
    *  the project's `templates/` over the framework defaults. (The project
-   *  root is taken from `process.cwd()` at run time — adopters needing a
-   *  different lookup chain can pass an explicit provider.) */
+   *  root is the directory holding `.metaobjects/config.json`, threaded
+   *  through `GenContext` by the runner. Adopters needing a different
+   *  lookup chain can pass an explicit provider.) */
   provider?: Provider;
   /** Optional named target — same as the other generators. */
   target?: string;
@@ -63,16 +64,37 @@ export const templateGenerator = function templateGenerator(
   const generator: Generator = {
     name: opts.name,
     async generate(ctx: GenContext): Promise<EmittedFile[]> {
-      const provider = opts.provider ?? projectProvider(process.cwd());
+      let provider: Provider;
+      if (opts.provider !== undefined) {
+        provider = opts.provider;
+      } else if (ctx.projectRoot !== undefined) {
+        provider = projectProvider(ctx.projectRoot);
+      } else {
+        ctx.warn(
+          "templateGenerator: ctx.projectRoot is undefined; falling back to process.cwd() for project-template resolution. " +
+          "Project-scoped template overrides will resolve relative to the current working directory, which is fragile under " +
+          "`meta gen` invoked from a sub-directory. Drive via runGen(opts.projectRoot) to remove this warning.",
+        );
+        provider = projectProvider(process.cwd());
+      }
       const walkRes = await opts.walk(ctx.loadedRoot);
       const files: EmittedFile[] = [];
       for (const { data, outputPath } of walkRes) {
-        const content = render({
-          ref: opts.template,
-          payload: data,
-          provider,
-          format: fmt,
-        });
+        let content: string;
+        try {
+          content = render({
+            ref: opts.template,
+            payload: data,
+            provider,
+            format: fmt,
+          });
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          throw new Error(
+            `templateGenerator(${opts.name}) failed rendering '${opts.template}' for '${outputPath}': ${msg}`,
+            { cause: err instanceof Error ? err : undefined },
+          );
+        }
         files.push({ path: outputPath, content });
       }
       return files;

server/typescript/packages/codegen-ts/src/render-engine/framework-provider.ts

@@ -17,34 +17,43 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** Walk up from `start` until we find a `package.json` (i.e., the codegen-ts
- *  package root), then return `<pkg-root>/templates`. Works the same way
- *  from `src/render-engine/framework-provider.ts` (during dev) and
- *  `dist/render-engine/framework-provider.js` (after `npm install`) because
- *  in both cases we shipped at the package root. */
+/** Canonical shipped template — used to verify a candidate framework
+ *  templates directory actually contains our defaults. Without this check a
+ *  hoisted-install layout (pnpm/bun workspaces) can walk up to a CONSUMER
+ *  package.json and silently return a templates dir that doesn't exist. */
+const CANONICAL_TEMPLATE_REL = "docs/entity-page.md.mustache";
+
+/** Walk up from `start` until we find a `package.json` whose neighbour
+ *  `templates/` directory contains our canonical shipped template (i.e., the
+ *  codegen-ts package root). Works the same way from
+ *  `src/render-engine/framework-provider.ts` (during dev) and
+ *  `dist/render-engine/framework-provider.js` (after `npm install`). */
 function findFrameworkTemplatesDir(start: string): string {
   let dir = start;
-  for (let i = 0; i < 12; i++) {
+  while (true) {
     const pkgJson = join(dir, "package.json");
     if (existsSync(pkgJson)) {
-      return join(dir, "templates");
+      const templatesDir = join(dir, "templates");
+      // Assert we landed at the codegen-ts package root, not a consumer's.
+      if (existsSync(join(templatesDir, CANONICAL_TEMPLATE_REL))) {
+        return templatesDir;
+      }
     }
     const parent = dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  // Last resort — caller will get an unresolved-ref error when it tries to
-  // use a framework template that isn't on disk.
-  return join(start, "templates");
+  throw new Error(
+    `framework templates dir unresolved: walked up from ${start} without finding a package.json ` +
+    `whose templates/${CANONICAL_TEMPLATE_REL} exists. This usually means codegen-ts was installed ` +
+    `via a hoisted layout (pnpm/bun workspaces) into an unexpected location, or the published ` +
+    `tarball is missing the templates/ directory.`,
+  );
 }
 
-const SELF_DIR = (() => {
-  try {
-    return dirname(fileURLToPath(import.meta.url));
-  } catch {
-    return process.cwd();
-  }
-})();
+// In ESM (CLAUDE.md: "ESM only. No CommonJS."), `import.meta.url` is
+// guaranteed to be a file: URL; no defensive try/catch needed.
+const SELF_DIR = dirname(fileURLToPath(import.meta.url));
 
 const FRAMEWORK_TEMPLATES_DIR = findFrameworkTemplatesDir(SELF_DIR);
 

server/typescript/packages/codegen-ts/src/runner.ts

@@ -174,6 +174,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         outputLayout: selfTarget.outputLayout,
       },
       renderContext,
+      ...(projectRoot !== undefined && { projectRoot }),
       warn: (msg) => warnings.push(`[${generator.name}] ${msg}`),
     };
 

server/typescript/packages/codegen-ts/test/generators/template-generator.test.ts

@@ -9,20 +9,14 @@ import { InMemoryProvider } from "@metaobjectsdev/render";
 import { templateGenerator } from "../../src/generators/template-generator.js";
 import { buildEntityDocData } from "../../src/generators/docs-data-builder.js";
 import {
-  TYPE_OBJECT, OBJECT_SUBTYPE_ENTITY,
-} from "@metaobjectsdev/metadata";
-import { metaRoot, metaObject, metaField } from "../_meta-build.js";
-import {
+  OBJECT_SUBTYPE_ENTITY,
   FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_STRING,
   TypeId, TYPE_IDENTITY, IDENTITY_SUBTYPE_PRIMARY, IDENTITY_ATTR_FIELDS,
   IDENTITY_ATTR_GENERATION, GENERATION_INCREMENT,
 } from "@metaobjectsdev/metadata";
-import { meta } from "../_meta-build.js";
+import { metaRoot, metaObject, metaField, meta } from "../_meta-build.js";
 import type { GenContext } from "../../src/generator.js";
 
-void TYPE_OBJECT;
-void OBJECT_SUBTYPE_ENTITY;
-
 function buildRoot() {
   const root = metaRoot("root", "demo");
   const e = metaObject(OBJECT_SUBTYPE_ENTITY, "Post");