@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/src/generators/output-parser-file.ts

@@ -9,7 +9,8 @@
 // Custom output directory:
 //   generators: [..., outputParser({ outDir: "src/generated/outputs" })]
 
-import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_OUTPUT } from "@metaobjectsdev/metadata";
+import { TEMPLATE_SUBTYPE_OUTPUT } from "@metaobjectsdev/metadata";
+import { findTemplates } from "../templates/find-templates.js";
 import {
   type EmittedFile,
   type Generator,
@@ -30,9 +31,7 @@ export const outputParser = function outputParser(opts?: OutputParserOpts): Gene
   const generator: Generator = {
     name: "output-parser",
     generate: oncePerRun((_entities, ctx) => {
-      const outputs = ctx.loadedRoot
-        .ownChildren()
-        .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_OUTPUT);
+      const outputs = findTemplates(ctx.loadedRoot, TEMPLATE_SUBTYPE_OUTPUT);
       const files: EmittedFile[] = [];
       for (const t of outputs) {
         files.push({

package/src/generators/output-prompt-file.ts

@@ -17,6 +17,7 @@ import {
   TYPE_TEMPLATE,
   TEMPLATE_SUBTYPE_OUTPUT,
   TEMPLATE_ATTR_PAYLOAD_REF,
+  refMatchesObject,
 } from "@metaobjectsdev/metadata";
 import {
   type EmittedFile,
@@ -49,7 +50,7 @@ export const outputPrompt = function outputPrompt(opts?: OutputPromptOpts): Gene
         // @payloadRef must resolve to a value-object (same contract as the parser).
         const payloadRef = t.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
         if (typeof payloadRef !== "string") continue;
-        const vo = root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === payloadRef);
+        const vo = root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, payloadRef));
         if (!vo) continue;
         files.push({
           path: `${dirPrefix}${t.name}.prompt.ts`,

package/src/generators/prompt-render-file.ts

@@ -9,7 +9,8 @@
 // Custom output path:
 //   generators: [..., promptRender({ outFile: "src/render/generated/prompts.ts" })]
 
-import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_PROMPT, OBJECT_SUBTYPE_VALUE } from "@metaobjectsdev/metadata";
+import { TEMPLATE_SUBTYPE_PROMPT, OBJECT_SUBTYPE_VALUE } from "@metaobjectsdev/metadata";
+import { findTemplates } from "../templates/find-templates.js";
 import {
   type Generator,
   type GeneratorFactory,
@@ -45,9 +46,7 @@ export const promptRender = function promptRender(opts?: PromptRenderOpts): Gene
     name: "prompt-render",
     generate: oncePerRun((entities, ctx) => {
       const payloads = entities.filter((e) => e.subType === OBJECT_SUBTYPE_VALUE);
-      const prompts = ctx.loadedRoot
-        .ownChildren()
-        .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_PROMPT);
+      const prompts = findTemplates(ctx.loadedRoot, TEMPLATE_SUBTYPE_PROMPT);
 
       if (payloads.length === 0 && prompts.length === 0) {
         return [];

package/src/generators/queries-file.ts

@@ -1,6 +1,7 @@
 import { OBJECT_SUBTYPE_VALUE, type MetaObject } from "@metaobjectsdev/metadata";
 import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
 import { renderQueriesFile } from "../templates/queries-file.js";
+import { isTphSubtype } from "../templates/zod-validators.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
 
@@ -13,13 +14,18 @@ export interface QueriesFileOpts {
 // emits findById/updateById/deleteById against a non-existent column. Skipping
 // value subtypes is unconditional — the user-supplied filter (if any) is applied
 // on top via boolean AND.
-const skipValueTypes = (e: MetaObject): boolean => e.subType !== OBJECT_SUBTYPE_VALUE;
+//
+// FR-017 Tier 2: TPH subtypes are ALSO skipped — they emit no standalone
+// queries file. Their per-subtype CRUD helpers live in the discriminator
+// base's queries file (which targets the single shared table).
+const skipNonQueryable = (e: MetaObject): boolean =>
+  e.subType !== OBJECT_SUBTYPE_VALUE && !isTphSubtype(e);
 
 export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generator {
   const userFilter = opts?.filter;
   const filter: (e: MetaObject) => boolean = userFilter
-    ? (e) => skipValueTypes(e) && userFilter(e)
-    : skipValueTypes;
+    ? (e) => skipNonQueryable(e) && userFilter(e)
+    : skipNonQueryable;
 
   const generator: Generator = {
     name: "queries-file",

package/src/generators/render-helper-file.ts

@@ -20,6 +20,7 @@ import {
   TYPE_TEMPLATE,
   TEMPLATE_SUBTYPE_OUTPUT,
   TEMPLATE_ATTR_PAYLOAD_REF,
+  refMatchesObject,
 } from "@metaobjectsdev/metadata";
 import {
   type EmittedFile,
@@ -55,7 +56,7 @@ export const renderHelper = function renderHelper(opts?: RenderHelperOpts): Gene
         // @payloadRef must resolve to a value-object (same contract as the parser).
         const payloadRef = t.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
         if (typeof payloadRef !== "string") continue;
-        const vo = root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === payloadRef);
+        const vo = root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, payloadRef));
         if (!vo) continue;
         files.push({
           // renderRenderHelper THROWS (fails codegen) on a mustache↔VO drift —

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

@@ -3,6 +3,7 @@ import { perEntity, type Generator, type GeneratorFactory } from "../generator.j
 import { renderRoutesFileHono } from "../templates/routes-file-hono.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
+import { CODEGEN_ATTR_EMIT_ROUTES } from "../constants.js";
 
 export interface RoutesFileHonoOpts {
   filter?: (entity: MetaObject) => boolean;
@@ -26,7 +27,10 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
   const userFilter = opts?.filter ?? (() => true);
   const generator: Generator = {
     name: "routes-file-hono",
-    filter: (e: MetaObject) => e.ownAttr("emitRoutes") !== false && userFilter(e),
+    // Marks this as the Hono routes generator so the runner can aggregate
+    // `ctx.config.includeHonoRoutes` and api-docs auto-documents the Hono surface.
+    emitsHonoRoutes: true,
+    filter: (e: MetaObject) => e.ownAttr(CODEGEN_ATTR_EMIT_ROUTES) !== false && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {
         throw new Error("routes-file-hono: renderContext is required (provided by runGen)");

package/src/generators/routes-file.ts

@@ -1,8 +1,10 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
 import { renderRoutesFile } from "../templates/routes-file.js";
+import { isTphSubtype } from "../templates/zod-validators.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
+import { CODEGEN_ATTR_EMIT_ROUTES } from "../constants.js";
 
 export interface RoutesFileOpts {
   filter?: (entity: MetaObject) => boolean;
@@ -12,13 +14,17 @@ export interface RoutesFileOpts {
 /**
  * Per-entity opt-out via `@emitRoutes: false` is honored. If the user supplies
  * their own filter, both must pass (AND).
+ *
+ * FR-017 Tier 2: TPH subtypes get no standalone routes file — their per-subtype
+ * route set lives in the discriminator base's routes file.
  */
 export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator {
   const userFilter = opts?.filter ?? (() => true);
   const generator: Generator = {
     name: "routes-file",
     // Always set: AND-composes metadata opt-out with optional user filter.
-    filter: (e: MetaObject) => e.ownAttr("emitRoutes") !== false && userFilter(e),
+    filter: (e: MetaObject) =>
+      e.ownAttr(CODEGEN_ATTR_EMIT_ROUTES) !== false && !isTphSubtype(e) && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {
         throw new Error("routes-file: renderContext is required (provided by runGen)");

package/src/generators/template-doc-builder.ts

@@ -0,0 +1,306 @@
+// Walk one `template.output` node (+ root) into the NEUTRAL TemplateDocData
+// shape the `docs/template-page.md` Mustache template consumes. The attr reads
+// MIRROR render-helper-file.ts / templates/render-helper.ts (@kind, @payloadRef,
+// @textRef, @format, @maxChars, @requiredTags; for email @subjectRef /
+// @htmlBodyRef / @textBodyRef) — but this builder emits DESCRIPTION, never code:
+// no helper signatures, no language types. `capability` is a FIXED, neutral
+// sentence per @kind.
+
+import {
+  type MetaData,
+  type MetaRoot,
+  TEMPLATE_ATTR_PAYLOAD_REF,
+  TEMPLATE_ATTR_TEXT_REF,
+  TEMPLATE_ATTR_FORMAT,
+  TEMPLATE_ATTR_MAX_CHARS,
+  TEMPLATE_ATTR_KIND,
+  TEMPLATE_KIND_EMAIL,
+  TEMPLATE_KIND_DOCUMENT,
+  TEMPLATE_KIND_DEFAULT,
+  TEMPLATE_ATTR_SUBJECT_REF,
+  TEMPLATE_ATTR_HTML_BODY_REF,
+  TEMPLATE_ATTR_TEXT_BODY_REF,
+  TEMPLATE_ATTR_REQUIRED_TAGS,
+  DOC_ATTR_DESCRIPTION,
+  stripPackage,
+} from "@metaobjectsdev/metadata";
+import {
+  TYPE_TEMPLATE,
+  TEMPLATE_SUBTYPE_OUTPUT,
+} from "@metaobjectsdev/metadata";
+import type { Provider } from "@metaobjectsdev/render";
+import { GENERATED_HEADER } from "../constants.js";
+import type { OutputLayout } from "../import-path.js";
+import { docPageHref, docPageNode, type DocPageNode } from "../docs-paths.js";
+import { fieldAnchorSlug } from "./field-anchor.js";
+import type { TemplateDocData, TemplateOutputPart } from "./template-doc-data.js";
+import { buildEnrichedPayloadTree } from "./template-payload-tree.js";
+import { annotateTemplate, type AnnotatePayloadField } from "./template-source-annotate.js";
+import {
+  renderSourceBlock,
+  renderVariablesTable,
+  renderRichLinkedHtml,
+} from "./template-source-render.js";
+
+export interface BuildTemplateDocDataOpts {
+  /** Page-placement layout. Defaults to "flat" (back-compat: same-dir links). */
+  layout?: OutputLayout;
+  /** Root used to resolve the @payloadRef target's package for a correct
+   *  cross-link in package layout. Optional: flat layout never needs it. */
+  loadedRoot?: MetaRoot;
+  /** The page provider — the SAME one the render-helper drift gate / page
+   *  rendering use (e.g. `projectProvider(projectRoot)`). Used to resolve each
+   *  referenced mustache's SOURCE TEXT for the "## Template source" section.
+   *  Optional: when absent (or a ref doesn't resolve) the section is omitted. */
+  provider?: Provider;
+}
+
+// FIXED, language-NEUTRAL capability sentences. NO type names, NO signatures.
+const CAPABILITY_DOCUMENT =
+  "A render helper is generated for this template: it takes the payload and " +
+  "returns the rendered output as a single string.";
+const CAPABILITY_EMAIL =
+  "A render helper is generated for this template: it takes the payload and " +
+  "returns the rendered email — subject, HTML body, and an optional text body.";
+
+/** Read an attr that may be a string or string[] (string-array attrs come back
+ *  as string[]; a bare comma string is split defensively). Returns a trimmed,
+ *  non-empty string list. */
+function attrStringList(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((v): v is string => typeof v === "string" && v.length > 0);
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    return value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  }
+  return [];
+}
+
+function readMaxChars(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+  }
+  return undefined;
+}
+
+function templateDescription(t: MetaData): string | undefined {
+  const v = t.attr(DOC_ATTR_DESCRIPTION);
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/** Page-placement node for a metadata object resolved by short name, with the
+ *  SAME package-less fallback the Payload cross-link and field hrefs share: when
+ *  the object can't be resolved off the root, fall back to a root-level node so a
+ *  link is still emitted. Keeps every inbound href routing through the one
+ *  `docPageHref(layout, …)` placement. */
+function pageNodeByName(root: MetaRoot | undefined, name: string): DocPageNode {
+  const obj = root?.findObject(name);
+  return obj !== undefined ? docPageNode(obj) : { name };
+}
+
+/** Build the TemplateDocData for one `template.output` node. */
+export function buildTemplateDocData(
+  template: MetaData,
+  opts?: BuildTemplateDocDataOpts,
+): TemplateDocData {
+  const layout = opts?.layout ?? "flat";
+  const root = opts?.loadedRoot;
+  const kindRaw = ((template.ownAttr(TEMPLATE_ATTR_KIND) as string | undefined) ??
+    TEMPLATE_KIND_DEFAULT).toLowerCase();
+  const isEmail = kindRaw === TEMPLATE_KIND_EMAIL;
+  const kind: "document" | "email" = isEmail ? TEMPLATE_KIND_EMAIL : TEMPLATE_KIND_DOCUMENT;
+
+  const payloadRefRaw = template.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  const payloadName =
+    typeof payloadRefRaw === "string" && payloadRefRaw.length > 0
+      ? stripPackage(payloadRefRaw)
+      : "unknown";
+
+  const requiredTags = attrStringList(template.ownAttr(TEMPLATE_ATTR_REQUIRED_TAGS));
+  const maxChars = readMaxChars(template.ownAttr(TEMPLATE_ATTR_MAX_CHARS));
+
+  let format = "";
+  let parts: TemplateOutputPart[] | undefined;
+  const sourceRefs: string[] = [];
+
+  if (isEmail) {
+    const subjectRef = template.ownAttr(TEMPLATE_ATTR_SUBJECT_REF);
+    const htmlBodyRef = template.ownAttr(TEMPLATE_ATTR_HTML_BODY_REF);
+    const textBodyRef = template.ownAttr(TEMPLATE_ATTR_TEXT_BODY_REF);
+    parts = [];
+    if (typeof subjectRef === "string") {
+      parts.push({ label: "Subject", ref: subjectRef, format: "text", escaped: false });
+      sourceRefs.push(subjectRef);
+    }
+    if (typeof htmlBodyRef === "string") {
+      parts.push({ label: "HTML body", ref: htmlBodyRef, format: "html", escaped: true });
+      sourceRefs.push(htmlBodyRef);
+    }
+    if (typeof textBodyRef === "string") {
+      parts.push({ label: "Text body", ref: textBodyRef, format: "text", escaped: false });
+      sourceRefs.push(textBodyRef);
+    }
+  } else {
+    format = ((template.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
+    const textRef = template.ownAttr(TEMPLATE_ATTR_TEXT_REF);
+    if (typeof textRef === "string") sourceRefs.push(textRef);
+  }
+
+  // Cross-link to the payload entity's page. The href is derived from the SAME
+  // page-placement function used to write that entity page, so it resolves in
+  // BOTH layouts (package layout folds the correct relative path).
+  const payloadLink = docPageHref(
+    layout,
+    docPageNode(template),
+    pageNodeByName(root, payloadName),
+  );
+
+  const data: TemplateDocData = {
+    generatedMarker: `<!-- ${GENERATED_HEADER} — DO NOT EDIT. -->`,
+    name: template.name,
+    kind,
+    isEmail,
+    format,
+    payload: { name: payloadName, link: payloadLink },
+    sourceRefs,
+    capability: isEmail ? CAPABILITY_EMAIL : CAPABILITY_DOCUMENT,
+  };
+
+  if (parts !== undefined) data.parts = parts;
+  if (requiredTags.length > 0) {
+    data.requiredTags = requiredTags;
+    data.hasRequiredTags = true;
+  }
+  if (maxChars !== undefined) data.maxChars = maxChars;
+
+  // ── "## Template source" section (Task 4) ────────────────────────────────
+  // Resolve each referenced mustache's SOURCE TEXT via the page provider, then
+  // annotate it against the ENRICHED payload tree (owner/type/required per node)
+  // and pre-render the three doc forms. Only when a provider + a resolvable
+  // payload VO are available; a ref that doesn't resolve is skipped (no crash).
+  if (opts?.provider !== undefined && root !== undefined && payloadName !== "unknown") {
+    const section = buildTemplateSourceSection({
+      provider: opts.provider,
+      root,
+      layout,
+      template,
+      payloadName,
+      // Document: the single @textRef (unlabeled). Email: one labeled part each.
+      refs:
+        parts !== undefined
+          ? parts.map((p) => ({ label: p.label, ref: p.ref }))
+          : sourceRefs.map((ref) => ({ ref })),
+    });
+    if (section !== undefined) data.templateSourceSection = section;
+  }
+
+  const desc = templateDescription(template);
+  if (desc !== undefined) {
+    data.descriptionQuote = desc.split("\n").map((l) => `> ${l}`.trimEnd()).join("\n");
+  }
+
+  return data;
+}
+
+// One referenced template source to document: an optional human label (email
+// part name) + the logical mustache ref (`@textRef` / `@subjectRef` / …).
+interface SourceRefSpec {
+  label?: string;
+  ref: string;
+}
+
+interface BuildSectionArgs {
+  provider: Provider;
+  root: MetaRoot;
+  /** Page-placement layout — threaded so field/partial hrefs route through the
+   *  SAME docPageHref the Payload cross-link uses (resolves under package layout). */
+  layout: OutputLayout;
+  /** The `template.output` node whose page is being built — the FROM page for
+   *  every relative href on this section. */
+  template: MetaData;
+  payloadName: string;
+  refs: SourceRefSpec[];
+}
+
+/**
+ * Build the PRE-RENDERED "## Template source" section markdown. For each ref:
+ * resolve its mustache source via the provider, annotate it against the enriched
+ * payload tree, and emit the fenced source block + the linked variables table +
+ * the rich `<details>` linked view. A document template yields one block; an
+ * email yields one `### <label>` sub-section per part. Refs whose source the
+ * provider can't resolve are skipped (graceful — the build-time drift gate
+ * already errors on a truly unresolved ref). Returns `undefined` when NOTHING
+ * resolved, so the caller omits the section entirely.
+ */
+function buildTemplateSourceSection(args: BuildSectionArgs): string | undefined {
+  const { provider, root, layout, template, payloadName, refs } = args;
+  const tree: AnnotatePayloadField[] = buildEnrichedPayloadTree(root, payloadName);
+  const fromNode = docPageNode(template);
+
+  // Layout-aware field href: route through the SAME docPageHref the Payload
+  // cross-link uses, so the link lands on the owner VO's REAL page in BOTH
+  // layouts (flat → `./Owner.md`, package → `../<pkg>/Owner.md`).
+  const fieldHref = (owner: string, name: string): string =>
+    `${docPageHref(layout, fromNode, pageNodeByName(root, owner))}#${fieldAnchorSlug(name)}`;
+
+  const resolvePartialHref = makePartialHrefResolver(root, layout, fromNode);
+  const isMultipart = refs.length > 1 || refs.some((r) => r.label !== undefined);
+
+  const blocks: string[] = [];
+  for (const spec of refs) {
+    const source = provider.resolve(spec.ref);
+    if (source === undefined) continue; // missing source → skip this part.
+    const tokens = annotateTemplate(source, tree, {
+      ownerVoName: payloadName,
+      resolvePartialHref,
+      fieldHref,
+    });
+    const parts: string[] = [];
+    if (isMultipart && spec.label !== undefined) parts.push(`### ${spec.label}`);
+    parts.push(renderSourceBlock(tokens));
+    const table = renderVariablesTable(tokens);
+    if (table !== "") parts.push(table);
+    parts.push(renderRichLinkedHtml(tokens));
+    blocks.push(parts.join("\n\n"));
+  }
+
+  if (blocks.length === 0) return undefined;
+  return ["## Template source", "", blocks.join("\n\n")].join("\n");
+}
+
+/**
+ * A `{{>ref}}` partial-href resolver: returns a relative href to the page of the
+ * `template.output` node that documents `ref` (it is one of that template's
+ * source refs — @textRef or an email part ref), else undefined (the partial is
+ * highlight-only). The href routes through the SAME `docPageHref(layout, …)` the
+ * field/Payload links use, so it resolves in BOTH layouts (flat → `./Name.md`,
+ * package → a correct relative path like `../comms/OrderEmail.md`).
+ */
+function makePartialHrefResolver(
+  root: MetaRoot,
+  layout: OutputLayout,
+  fromNode: DocPageNode,
+): (ref: string) => string | undefined {
+  // Map each documented source ref → the template node that documents it.
+  const refToTemplate = new Map<string, MetaData>();
+  for (const child of root.ownChildren()) {
+    if (child.type !== TYPE_TEMPLATE || child.subType !== TEMPLATE_SUBTYPE_OUTPUT) continue;
+    for (const attr of [
+      TEMPLATE_ATTR_TEXT_REF,
+      TEMPLATE_ATTR_SUBJECT_REF,
+      TEMPLATE_ATTR_HTML_BODY_REF,
+      TEMPLATE_ATTR_TEXT_BODY_REF,
+    ]) {
+      const v = child.ownAttr(attr);
+      if (typeof v === "string" && v.length > 0 && !refToTemplate.has(v)) {
+        refToTemplate.set(v, child);
+      }
+    }
+  }
+  return (ref: string) => {
+    const node = refToTemplate.get(ref);
+    return node !== undefined ? docPageHref(layout, fromNode, docPageNode(node)) : undefined;
+  };
+}

package/src/generators/template-doc-data.ts

@@ -0,0 +1,85 @@
+// Data-dict shape for the NEUTRAL template.output doc page (the "render
+// contract" page). Sibling of EntityDocData (docs-data.ts) — same public-API
+// stability contract: template authors who write a custom Mustache file for
+// `docs/template-page.md` reference these keys.
+//
+// CRITICAL — NEUTRALITY: this shape carries NO language assumptions. There are
+// no generated-helper signatures, no language type names, no SDK tokens. The
+// `capability` field is a FIXED, language-neutral English sentence per @kind
+// (see template-doc-builder.ts). The page describes the RENDER CONTRACT (what
+// the template references, validates, and produces), not any one port's code.
+//
+// Markdown-flavored, like EntityDocData: a few fields are pre-rendered (the
+// parts table is structural, but escaping / raw-vs-escaped wording lives in the
+// builder so the template stays trivial and cross-port walks don't re-derive it).
+
+/** One part of a multipart (email) template — a single rendered source ref with
+ *  its format and whether the renderer escapes its output for that format. */
+export interface TemplateOutputPart {
+  /** Human-readable part label, e.g. "Subject", "HTML body", "Text body". */
+  label: string;
+  /** The logical text ref rendered for this part (e.g. "email/welcome.html"). */
+  ref: string;
+  /** Render format for this part: "text" | "html" (subject/text = text, html = html). */
+  format: string;
+  /** True iff the renderer escapes output for this part's format (html → true). */
+  escaped: boolean;
+}
+
+export interface TemplateDocData {
+  /** @markdown — the generated-by marker, echoed at the top of the page. */
+  generatedMarker: string;
+
+  /** Raw template node name — also the emitted filename (`<name>.md`). */
+  name: string;
+
+  /** @kind — "document" | "email". */
+  kind: "document" | "email";
+  /** Convenience flag for the Mustache template (no "is X" primitive). */
+  isEmail: boolean;
+
+  /** @markdown — description as a blockquote (one `> ` per line). Present iff
+   *  the template declares a @description. Mirrors EntityDocData. */
+  descriptionQuote?: string;
+
+  /** Document: the @format (e.g. "html"). Email: "" — the parts carry format. */
+  format: string;
+
+  /** Email only: the ordered multipart parts (subject, html body, text body?). */
+  parts?: TemplateOutputPart[];
+
+  /** The payload object the template renders from. `link` is `./<rawName>.md` —
+   *  the payload entity's own doc page (raw-name convention, matching the
+   *  entity-page filename + the entity's Used-by back-link). */
+  payload: { name: string; link: string };
+
+  /** @requiredTags, if declared. Drives both the Input "Required fields" line
+   *  and the Render-contract "Required tags" bullet. */
+  requiredTags?: string[];
+  /** Present-and-non-empty flag for @requiredTags (Mustache has no "non-empty
+   *  array" primitive; same idiom as EntityDocData's `has*` flags). */
+  hasRequiredTags?: boolean;
+
+  /** @maxChars, if declared (document only in practice). */
+  maxChars?: number;
+
+  /** The template refs this page renders: [@textRef] for a document, or the
+   *  2–3 email part refs. Drives the Source section. */
+  sourceRefs: string[];
+
+  /** FIXED, language-NEUTRAL capability sentence per @kind. No type names, no
+   *  function signatures. See template-doc-builder.ts. */
+  capability: string;
+
+  /**
+   * @markdown — the PRE-RENDERED "## Template source" section body (linked-
+   * template-source-docs, Task 4). Present iff at least one referenced mustache
+   * resolved to source via the page provider. For a document template it is one
+   * block; for an email it is one `### <part>` sub-section per part. Each carries
+   * the fenced ```mustache source, a linked variables table, and the rich
+   * `<details>` linked view — ALL pre-rendered in the builder (the page template
+   * just emits this markdown verbatim, like `descriptionQuote`), so the mustache
+   * page never re-parses the embedded `{{field}}` tokens. Absent when no
+   * referenced source resolved (the section is omitted, not empty). */
+  templateSourceSection?: string;
+}

package/src/generators/template-payload-tree.ts

@@ -0,0 +1,71 @@
+// Enriched payload-field tree for the template-source annotator
+// (linked-template-source-docs, Task 4).
+//
+// The render-helper drift gate walks the payload VO into a bare `PayloadField[]`
+// (name + nested fields) — enough to VERIFY that a `{{field}}` exists. The doc
+// page needs MORE per node: which VO OWNS the field (so the link points at the
+// right entity page), the field's NEUTRAL type, and whether it's required — the
+// exact same facts the entity Constraints table shows.
+//
+// This walk produces that `AnnotatePayloadField[]`. It is the same recursion the
+// render-helper's `derivePayloadFieldTree` does (object-ref fields recurse into
+// their referenced VO; a `seen` set guards a reference cycle) — but it carries
+// owner/type/required and SWITCHES owner to the nested VO when it descends, so a
+// `{{address.city}}` resolves to `Address.city` and links to `./Address.md`.
+//
+// Reuse, not reimplementation:
+//   • isFieldRequired / neutralTypeStr — the SAME helpers the entity Constraints
+//     table uses, so the documented type/required can never drift from the
+//     entity page.
+
+import {
+  type MetaObject,
+  type MetaRoot,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_ATTR_OBJECT_REF,
+  stripPackage,
+} from "@metaobjectsdev/metadata";
+import { isFieldRequired, neutralTypeStr } from "./docs-data-builder.js";
+import type { AnnotatePayloadField } from "./template-source-annotate.js";
+
+/**
+ * Walk the payload VO `voName` into an enriched `AnnotatePayloadField[]`. Each
+ * node carries `owner` (the short name of the VO that DECLARES the field — the
+ * link target), `type` (the neutral logical type), and `required`. Object-ref
+ * fields recurse into their referenced VO with `owner` switched to that nested
+ * VO; a `seen` set guards a (pathological) reference cycle (returns `[]` rather
+ * than recursing forever).
+ *
+ * Returns `[]` when the VO can't be resolved — the annotator then leaves the
+ * referencing variables unresolved (flagged "not on payload"), never throws.
+ */
+export function buildEnrichedPayloadTree(
+  root: MetaRoot,
+  voName: string,
+  seen: ReadonlySet<string> = new Set(),
+): AnnotatePayloadField[] {
+  if (seen.has(voName)) return [];
+  const vo: MetaObject | undefined = root.findObject(voName);
+  if (vo === undefined) return [];
+  const owner = stripPackage(vo.name);
+  const nextSeen = new Set(seen).add(voName);
+  const out: AnnotatePayloadField[] = [];
+  for (const f of vo.fields()) {
+    const node: AnnotatePayloadField = {
+      name: f.name,
+      owner,
+      type: neutralTypeStr(f),
+      required: isFieldRequired(f),
+    };
+    if (f.subType === FIELD_SUBTYPE_OBJECT) {
+      const ref = f.ownAttr(FIELD_ATTR_OBJECT_REF);
+      if (typeof ref === "string" && ref.length > 0) {
+        // Owner switches to the nested VO for its fields (the recursion below
+        // re-derives `owner` from the resolved VO's own name).
+        node.fields = buildEnrichedPayloadTree(root, stripPackage(ref), nextSeen);
+      }
+    }
+    out.push(node);
+  }
+  return out;
+}