@metaobjectsdev/codegen-ts 0.23.2 → 0.24.0

package/src/generators/api-model.ts

@@ -107,6 +107,7 @@ import {
   variableNameFromEntity,
 } from "../naming.js";
 import { getPkInfo } from "../templates/queries.js";
+import { responseShape } from "../templates/find-inbound.js";
 import { isTphSubtype } from "../templates/zod-validators.js";
 import { isTphDiscriminatorBase } from "../templates/tph-discriminator.js";
 import { isCallableEntity } from "../templates/callable-file.js";
@@ -823,50 +824,21 @@ function templateOutputs(root: MetaRoot): MetaData[] {
 function buildTemplateUnit(tmpl: MetaData, root: MetaRoot, _layout: OutputLayout): ApiUnitDoc {
   const name = tmpl.name;
   const symbols: ApiSymbol[] = [];
-  // extractor + render-helper generators emit FLAT `<Name>.extractor.ts` /
-  // `<Name>.render.ts` (no package folding), so importPath ignores layout.
-  const extractorMod = templateModulePath(`${name}.extractor`);
+  // The render-helper generator emits a FLAT `<Name>.render.ts` (no package
+  // folding), so importPath ignores layout.
   const renderMod = templateModulePath(`${name}.render`);
 
-  // ADR-0039: resolving — a template may inherit @payloadRef/@format/@kind via extends.
+  // ADR-0039: resolving — a template may inherit @payloadRef/@kind via extends.
   const payloadRef = tmpl.attr(TEMPLATE_ATTR_PAYLOAD_REF);
   const payload = typeof payloadRef === "string" ? payloadRef : undefined;
-  const format = ((tmpl.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
   const kind = ((tmpl.attr(TEMPLATE_ATTR_KIND) as string | undefined) ?? TEMPLATE_KIND_DEFAULT).toLowerCase();
 
-  // --- extractor: only json/xml output-parsers expose the extract API (matches
-  //     extractor-file.ts's `if (format !== "json" && format !== "xml") continue`). ---
-  if (payload && (format === "json" || format === "xml")) {
-    const extract = `extract${name}`;
-    const extractLenient = `extractLenient${name}`;
-    // The extractor's strict return IS the @payloadRef value-object's interface —
-    // document its field shape (same VO field walk the payload interface emitter
-    // uses) so an agent sees what `extract<Name>` yields, not just the type name.
-    const payloadShape = payloadFieldShapes(root, payload);
-    const extractSym: ApiSymbol = {
-      name: extract,
-      kind: "extractor",
-      importPath: extractorMod,
-      signature: `${extract}(root: MetaRoot, text: string): ${payload}`,
-      params: [`root: MetaRoot`, `text: string`],
-      returns: payload,
-      throws: `Error when a @required field is lost (the strict opt-in gate).`,
-      usage: `Parse dirty LLM ${format} text into a strict, fully-typed ${payload} graph.`,
-    };
-    if (payloadShape !== undefined) extractSym.fields = payloadShape;
-    symbols.push(
-      extractSym,
-      {
-        name: extractLenient,
-        kind: "extractor",
-        importPath: extractorMod,
-        signature: `${extractLenient}(root: MetaRoot, text: string): ExtractionResult<${name}Extracted>`,
-        params: [`root: MetaRoot`, `text: string`],
-        returns: `ExtractionResult<${name}Extracted>`,
-        usage: `Never-throwing extract; inspect report for lost/defaulted fields.`,
-      },
-    );
-  }
+  // ADR-0052: a template.output documents its RENDER and nothing else. The
+  // extractor symbols used to be built here, gated on @format ∈ {json,xml} and
+  // typed on @payloadRef — so the reference documented functions this subtype no
+  // longer emits, named the REQUEST shape as the parse result, and said nothing
+  // about the prompts that actually do emit them. They now live in
+  // buildPromptUnit, keyed on @responseRef.
 
   // --- render: render<Name>; document → string, email → EmailDocument
   //     (matches render-helper.ts's @kind branch). Render is emitted for any
@@ -875,7 +847,7 @@ function buildTemplateUnit(tmpl: MetaData, root: MetaRoot, _layout: OutputLayout
     const render = `render${name}`;
     const isEmail = kind === TEMPLATE_KIND_EMAIL;
     const returns = isEmail ? "EmailDocument" : "string";
-    symbols.push({
+    const renderSym: ApiSymbol = {
       name: render,
       kind: "render",
       importPath: renderMod,
@@ -885,7 +857,14 @@ function buildTemplateUnit(tmpl: MetaData, root: MetaRoot, _layout: OutputLayout
       usage: isEmail
         ? `Render the ${name} email (subject + bodies) from a typed ${payload} payload.`
         : `Render the ${name} document from a typed ${payload} payload.`,
-    });
+    };
+    // The payload shape used to reach this unit only via the extractor symbol.
+    // ADR-0052 moved that away, which left the render example with no field shape
+    // to build from — it degraded to `render<Name>({}, provider)`. Attach it here,
+    // where it always belonged: this is the payload the render handle takes.
+    const renderShape = payloadFieldShapes(root, payload);
+    if (renderShape !== undefined) renderSym.fields = renderShape;
+    symbols.push(renderSym);
   }
 
   const unit: ApiUnitDoc = {
@@ -950,12 +929,57 @@ function buildPromptUnit(tmpl: MetaData, root: MetaRoot): ApiUnitDoc {
     symbols.push(sym);
   }
 
-  return {
+  // --- ADR-0052 inbound half: a prompt declaring @responseRef also owns the
+  //     parser-on-receipt and the tolerant extract. Gated on @responseRef
+  //     PRESENCE, matching extractor-file.ts / output-parser-file.ts — never on
+  //     a format value, and never on @payloadRef, which types the REQUEST. ---
+  const shape = responseShape(root, tmpl);
+  if (shape) {
+    const { vo, ref: responseRef, format } = shape;
+    // The extractor generator emits a FLAT `<Name>.extractor.ts`.
+    const extractorMod = templateModulePath(`${name}.extractor`);
+    const extract = `extract${name}`;
+    const extractLenient = `extractLenient${name}`;
+    // The strict return IS the @responseRef value-object's interface — document
+    // its field shape so an agent sees what `extract<Name>` yields, not just a
+    // type name. `vo` is the resolved node; `responseRef` is the authored ref.
+    void vo;
+    const responseFieldShape = payloadFieldShapes(root, responseRef);
+    const extractSym: ApiSymbol = {
+      name: extract,
+      kind: "extractor",
+      importPath: extractorMod,
+      signature: `${extract}(root: MetaRoot, text: string): ${responseRef}`,
+      params: [`root: MetaRoot`, `text: string`],
+      returns: responseRef,
+      throws: `Error when a @required field is lost (the strict opt-in gate).`,
+      usage: `Parse the model's ${format} reply to ${name} into a strict, fully-typed ${responseRef} graph.`,
+    };
+    if (responseFieldShape !== undefined) extractSym.fields = responseFieldShape;
+    symbols.push(extractSym, {
+      name: extractLenient,
+      kind: "extractor",
+      importPath: extractorMod,
+      signature: `${extractLenient}(root: MetaRoot, text: string): ExtractionResult<${name}Extracted>`,
+      params: [`root: MetaRoot`, `text: string`],
+      returns: `ExtractionResult<${name}Extracted>`,
+      usage: `Never-throwing extract of the ${name} reply; inspect report for lost/defaulted fields.`,
+    });
+  }
+
+  const unit: ApiUnitDoc = {
     node: name,
     package: effectivePackage(tmpl),
     nodeKind: "template",
     symbols,
   };
+  // ADR-0052: the extractor symbols moved here, so their worked example must move
+  // with them. Without this the page documents `extract<Name>(root, …)` but the
+  // setup preamble never introduces `root`, because the preamble derives its
+  // handles from the rendered EXAMPLE text.
+  const example = templateExample(name, symbols);
+  if (example !== undefined) unit.example = example;
+  return unit;
 }
 
 // ---------------------------------------------------------------------------
@@ -1069,9 +1093,10 @@ function templateExample(name: string, symbols: ApiSymbol[]): UnitExample | unde
   if (renderSym !== undefined) {
     picks.push({ name: renderSym.name, importPath: renderSym.importPath });
     // Render's payload object literal comes from the @payloadRef VO shape the
-    // render symbol returns/consumes; reuse the extractor's documented payload
-    // fields when present so the example body is real.
-    const payloadFields = extract?.fields;
+    // render symbol consumes. Prefer the render symbol's OWN fields — it borrowed
+    // the extractor's before ADR-0052, which silently degraded the example to
+    // `render<Name>({}, provider)` the moment the extractor moved to the prompt.
+    const payloadFields = renderSym.fields ?? extract?.fields;
     const payloadLit = objectLiteralFromFields(payloadFields);
     body.push(`const output = ${renderSym.name}(${payloadLit}, provider);`);
   }

package/src/generators/docs-data-builder.ts

@@ -11,7 +11,9 @@ import {
   type MetaRoot,
   TYPE_TEMPLATE,
   TEMPLATE_ATTR_PAYLOAD_REF,
+  REQUIREMENT_ATTR_STATEMENT,
   OBJECT_SUBTYPE_VALUE,
+  OBJECT_SUBTYPE_ENTITY,
   IDENTITY_SUBTYPE_PRIMARY,
   IDENTITY_SUBTYPE_SECONDARY,
   IDENTITY_SUBTYPE_REFERENCE,
@@ -52,6 +54,9 @@ import { enumValues } from "../enum-meta.js";
 import { hasWritableRdbSource } from "../source-detect.js";
 import { GENERATED_HEADER } from "../constants.js";
 import { renderEntityNeighborhoodErBlock } from "../templates/mermaid-er.js";
+// Shape C reuses the SAME walk the stub generator and the requirements index use, so
+// all three agree about what the ledger contains by construction.
+import { walkRequirements } from "../requirement-walk.js";
 import type {
   EntityDocData,
   StorageFieldDoc,
@@ -684,6 +689,34 @@ export function buildEntityDocData(
   }
   const usedBy = usedByMatches.length > 0 ? usedByMatches : undefined;
 
+  // ---- ClaimedBy (shape C) — the requirements whose `@implementedBy` resolves HERE.
+  //
+  // Matched on the RESOLVED NODE, never on the reference string: `@implementedBy` may
+  // be authored fully-qualified or bare, and a bare ref binds package-locally under
+  // ADR-0042. `walkRequirements` already did that resolution (it is what the stub
+  // generator uses), so comparing nodes inherits the correct binding rather than
+  // re-deriving it here and drifting from it.
+  //
+  // ENTITY-GRAIN. Object coverage is entity-grain, so a claimed value/projection gets
+  // nothing — surfacing one would imply a coverage rule the ledger does not have.
+  const claimedByMatches: UsedByDoc[] = [];
+  if (entity.subType === OBJECT_SUBTYPE_ENTITY) {
+    for (const walked of walkRequirements(root)) {
+      if (!walked.targets.some((t) => t.node === entity)) continue;
+      const v = walked.view;
+      const level = v.level === undefined ? "" : ` · **L${v.level}**`;
+      const status = v.status === undefined ? "" : ` · status: \`${v.status}\``;
+      const statement = walked.node.attr(REQUIREMENT_ATTR_STATEMENT);
+      const said = typeof statement === "string" && statement.length > 0 ? ` — ${statement}` : "";
+      claimedByMatches.push({
+        bullet: `\`requirement.${v.subType} ${v.path}\`${level}${status}${said}`,
+      });
+    }
+  }
+  // ABSENT, not empty: the Mustache gate must not render for an unclaimed entity, so
+  // its page stays byte-identical to its pre-feature output.
+  const claimedBy = claimedByMatches.length > 0 ? claimedByMatches : undefined;
+
   // Preamble header — built up exactly as the legacy emitter did.
   const preambleLines: string[] = [];
   const typeStr = `${entity.type}.${entity.subType}`;
@@ -761,6 +794,10 @@ export function buildEntityDocData(
     data.usedBy = usedBy;
     data.hasUsedBy = true;
   }
+  if (claimedBy !== undefined) {
+    data.claimedBy = claimedBy;
+    data.hasClaimedBy = true;
+  }
   // Cross-link to the api surfaces — present ONLY when the caller computed the
   // hrefs (api surfaces emitted alongside model); model-only runs stay identical.
   // `last` flags the final ref so the template renders an inline ` · ` separator.

package/src/generators/docs-data.ts

@@ -256,6 +256,21 @@ export interface EntityDocData {
   /** Present-and-non-empty flag for the usedBy section. */
   hasUsedBy?: boolean;
 
+  /** "Required by" (shape C) — the `requirement.*` nodes whose `@implementedBy`
+   *  resolves to THIS entity. Same list+flag pattern as `usedBy`.
+   *
+   *  ABSENT — not empty, not false — when nothing claims the entity, so the
+   *  Mustache section does not render and an unclaimed entity's page stays
+   *  BYTE-IDENTICAL to its pre-feature output. That is the no-churn contract:
+   *  a project with no ledger, or an entity nothing claims, must see no diff.
+   *
+   *  ENTITY-GRAIN ONLY. Object coverage is entity-grain (`spec/capability-ledger.md`),
+   *  so a claimed `object.value` / `object.projection` gets nothing here — surfacing
+   *  one would imply a coverage rule the ledger does not actually have. */
+  claimedBy?: UsedByDoc[];
+  /** Present-and-non-empty flag for the claimedBy section. */
+  hasClaimedBy?: boolean;
+
   /** Present flag for the storage section. */
   hasStorage?: boolean;
 

package/src/generators/docs-file.ts

@@ -19,7 +19,7 @@
 // breaks, the refactor is the bug, not the fixture.
 
 import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
-import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_OUTPUT } from "@metaobjectsdev/metadata";
+import { TYPE_TEMPLATE } from "@metaobjectsdev/metadata";
 import { render } from "@metaobjectsdev/render";
 import type { Provider } from "@metaobjectsdev/render";
 import type { Generator, GeneratorFactory, EmittedFile } from "../generator.js";
@@ -132,12 +132,21 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
           return { path, content: renderDocPage(TEMPLATE_REF, payload, provider, path) };
         });
 
-      // ALSO emit one NEUTRAL render-contract page per `template.output` node —
-      // a sibling artifact, distinct from the entity page. Raw node name → file
+      // ALSO emit one NEUTRAL render-contract page per top-level `template.*` node
+      // — a sibling artifact, distinct from the entity page. Raw node name → file
       // (`<name>.md`), agreeing with the entity Used-by back-link target.
+      //
+      // EVERY template subtype, not just `template.output`: the api-docs surface
+      // has always emitted `api/<lang>/<pkg>/<Prompt>.md` for a top-level
+      // `template.prompt` (it documents the prompt-render handle), and that page
+      // carries a "Model / metadata" back-link to `<pkg>/<Prompt>.md`. While this
+      // loop filtered to outputs, that link pointed at a page nothing wrote — a
+      // broken link in every shipped doc tree containing a prompt. ADR-0052 makes
+      // it worse rather than better: a responding prompt now carries the whole
+      // inbound tier, so it is the LAST node a doc tree should omit.
       // ADR-0039: resolving — root has no super (children()==ownChildren()).
       for (const child of ctx.loadedRoot.children()) {
-        if (child.type !== TYPE_TEMPLATE || child.subType !== TEMPLATE_SUBTYPE_OUTPUT) continue;
+        if (child.type !== TYPE_TEMPLATE) continue;
         const node = docPageNode(child);
         templateNodes.push(node);
         const path = docPageOutputPath(layout, node);

package/src/generators/extractor-file.ts

@@ -4,7 +4,7 @@
 // node whose @format is json/xml. Wraps renderExtractor() from templates/extractor.ts.
 //
 // The emitted extractor sits over the output-parser's nested-capable extract and turns dirty LLM
-// text into the strict typed payload graph. It imports from the sibling <Name>.output.ts (the
+// text into the strict typed payload graph. It imports from the sibling <Name>.response.ts (the
 // output-parser) and from each payload value-object's own entity module (<VO>.ts, emitted by
 // entityFile), so run it alongside outputParser() + entityFile().
 //
@@ -14,13 +14,13 @@
 // Custom output directory:
 //   generators: [..., extractor({ outDir: "src/generated/outputs" })]
 
-import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_OUTPUT, TEMPLATE_ATTR_FORMAT } from "@metaobjectsdev/metadata";
 import {
   type EmittedFile,
   type Generator,
   type GeneratorFactory,
   oncePerRun,
 } from "../generator.js";
+import { inboundTemplates, responseShape } from "../templates/find-inbound.js";
 import { renderExtractor } from "../templates/extractor.js";
 
 export interface ExtractorOpts {
@@ -35,16 +35,12 @@ export const extractor = function extractor(opts?: ExtractorOpts): Generator {
   const generator: Generator = {
     name: "extractor",
     generate: oncePerRun((_entities, ctx) => {
-      // ADR-0039: resolving — root has no super (children()==ownChildren()).
-      const outputs = ctx.loadedRoot
-        .children()
-        .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_OUTPUT);
       const files: EmittedFile[] = [];
-      for (const t of outputs) {
-        // The extract tier requires the extract API, which only json/xml output-parsers emit.
-        // ADR-0039: resolving — a template may inherit @format via extends.
-        const format = ((t.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
-        if (format !== "json" && format !== "xml") continue;
+      for (const t of inboundTemplates(ctx.loadedRoot)) {
+        // The extract tier sits over the parser's extract API. Since ADR-0052 every
+        // responding prompt emits one (@responseFormat is a closed json|xml set), so
+        // the only remaining skip is an unresolvable @responseRef.
+        if (!responseShape(ctx.loadedRoot, t)) continue;
         files.push({
           path: `${dirPrefix}${t.name}.extractor.ts`,
           // ADR-0044/#228: thread ctx.renderContext (when present — runGen always supplies it;

package/src/generators/index.ts

@@ -44,3 +44,14 @@ export type {
 export { buildEntityDocData } from "./docs-data-builder.js";
 export type { TemplateDocData, TemplateOutputPart } from "./template-doc-data.js";
 export { buildTemplateDocData } from "./template-doc-builder.js";
+
+// FR-038 — requirement-derived test stubs. The factory is a convenience; the
+// primitives beside it are the real escape hatch, so an app needing different
+// behaviour composes its own generator instead of filing an issue here.
+export { requirementTests } from "./requirement-tests.js";
+export { requirementsFile } from "./requirements-file.js";
+export type { RequirementRow } from "./requirements-view.js";
+export type {
+  RequirementTestsOpts,
+  RequirementTestRenderer,
+} from "./requirement-tests.js";

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

@@ -1,7 +1,13 @@
 // server/typescript/packages/codegen-ts/src/generators/output-parser-file.ts
 //
-// Stock generator that emits one <TemplateName>.output.ts file per declared
-// template.output node. Wraps renderOutputParser() from templates/output-parser.ts.
+// Stock generator that emits one <PromptName>.response.ts file per declared
+// `template.prompt` carrying `@responseRef`. Wraps renderOutputParser() from
+// templates/output-parser.ts.
+//
+// ADR-0052: this tier is INBOUND — it reads a model's reply. It used to key on
+// `template.output` with no `@kind` filter at all, so an email template generated
+// a parser for text the system had just rendered. `template.output` is outbound
+// only and emits nothing here.
 //
 // Consumer wiring (metaobjects.config.ts):
 //   generators: [..., promptRender(), outputParser()]
@@ -9,8 +15,7 @@
 // Custom output directory:
 //   generators: [..., outputParser({ outDir: "src/generated/outputs" })]
 
-import { TEMPLATE_SUBTYPE_OUTPUT } from "@metaobjectsdev/metadata";
-import { findTemplates } from "../templates/find-templates.js";
+import { inboundTemplates } from "../templates/find-inbound.js";
 import {
   type EmittedFile,
   type Generator,
@@ -31,11 +36,11 @@ export const outputParser = function outputParser(opts?: OutputParserOpts): Gene
   const generator: Generator = {
     name: "output-parser",
     generate: oncePerRun((_entities, ctx) => {
-      const outputs = findTemplates(ctx.loadedRoot, TEMPLATE_SUBTYPE_OUTPUT);
+      const responders = inboundTemplates(ctx.loadedRoot);
       const files: EmittedFile[] = [];
-      for (const t of outputs) {
+      for (const t of responders) {
         files.push({
-          path: `${dirPrefix}${t.name}.output.ts`,
+          path: `${dirPrefix}${t.name}.response.ts`,
           // ADR-0044/#228: thread ctx.renderContext (when present — runGen always supplies it;
           // a hand-rolled GenContext in a unit test may omit it, falling back to bare naming) so
           // a payload/nested value-object whose bare name collides across packages emits the

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

@@ -1,10 +1,13 @@
 // server/typescript/packages/codegen-ts/src/generators/output-prompt-file.ts
 //
-// FR-010 stock generator that emits one <TemplateName>.prompt.ts file per json/xml
-// template.output node — the output-format prompt fragment ("produce your answer
-// like this"). Wraps renderOutputPrompt() from templates/output-prompt.ts. Skips
-// text-format outputs and outputs whose @payloadRef doesn't resolve to a value-object
-// (same contract as the output-parser generator).
+// FR-010 stock generator that emits one <PromptName>.responseFormat.ts file per
+// responding `template.prompt` — the response-format fragment ("produce your answer
+// like this"). Wraps renderOutputPrompt() from templates/output-prompt.ts.
+//
+// ADR-0052: gated on `@responseRef` presence, like every other inbound generator.
+// It previously keyed on `template.output` + a json/xml `@format` gate, which is
+// how a fragment that instructs an LLM came to be emitted from the subtype defined
+// as "every rendered artifact other than an LLM prompt".
 //
 // Consumer wiring (metaobjects.config.ts):
 //   generators: [..., promptRender(), outputParser(), outputPrompt()]
@@ -12,19 +15,14 @@
 // Custom output directory:
 //   generators: [..., outputPrompt({ outDir: "src/generated/outputs" })]
 
-import {
-  TYPE_TEMPLATE,
-  TEMPLATE_SUBTYPE_OUTPUT,
-  TEMPLATE_ATTR_PAYLOAD_REF,
-  resolveObjectRef,
-} from "@metaobjectsdev/metadata";
 import {
   type EmittedFile,
   type Generator,
   type GeneratorFactory,
   oncePerRun,
 } from "../generator.js";
-import { renderOutputPrompt, templateSupportsPrompt } from "../templates/output-prompt.js";
+import { inboundTemplates, responseShape } from "../templates/find-inbound.js";
+import { renderOutputPrompt } from "../templates/output-prompt.js";
 
 export interface OutputPromptOpts {
   /** Output directory prefix relative to the target's outDir. Default: "" (root). */
@@ -39,23 +37,12 @@ export const outputPrompt = function outputPrompt(opts?: OutputPromptOpts): Gene
     name: "output-prompt",
     generate: oncePerRun((_entities, ctx) => {
       const root = ctx.loadedRoot;
-      // ADR-0039: resolving — root has no super (children()==ownChildren()).
-      const outputs = root
-        .children()
-        .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_OUTPUT);
       const files: EmittedFile[] = [];
-      for (const t of outputs) {
-        // Only json/xml outputs get a renderable prompt fragment.
-        if (!templateSupportsPrompt(t)) continue;
-        // @payloadRef must resolve to a value-object (same contract as the parser).
-        // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
-        const payloadRef = t.attr(TEMPLATE_ATTR_PAYLOAD_REF);
-        if (typeof payloadRef !== "string") continue;
-        // ADR-0042: a bare @payloadRef resolves in the template's package.
-        const vo = resolveObjectRef(root, payloadRef, t.package ?? t.fileDefaultPackage ?? "").node;
-        if (!vo) continue;
+      for (const t of inboundTemplates(root)) {
+        // @responseRef must resolve to a value-object (same contract as the parser).
+        if (!responseShape(root, t)) continue;
         files.push({
-          path: `${dirPrefix}${t.name}.prompt.ts`,
+          path: `${dirPrefix}${t.name}.responseFormat.ts`,
           content: renderOutputPrompt(root, t.name),
         });
       }