@metaobjectsdev/codegen-ts 0.7.0-rc.9 → 0.8.0-rc.1

package/src/generators/docs-file.ts

@@ -0,0 +1,87 @@
+// docsFile() — emits `<Entity>.md` next to each generated entity module.
+//
+// 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 — 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 { render } from "@metaobjectsdev/render";
+import type { Generator, GeneratorFactory } from "../generator.js";
+import { entityOutputPath } from "../import-path.js";
+import { projectProvider } from "../render-engine/framework-provider.js";
+import { buildEntityDocData } from "./docs-data-builder.js";
+
+export interface DocsFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+/** The names of the generators that may emit sibling files for an entity.
+ *  We always list them in the "Generated code" section — adopters cross-
+ *  reference their own metaobjects.config.ts to confirm which are wired in.
+ *  Matches the rc.11 behavior. */
+const KNOWN_SIBLING_GENERATORS = new Set([
+  "queries-file",
+  "routes-file",
+  "routes-file-hono",
+]);
+
+const TEMPLATE_REF = "docs/entity-page.md";
+
+export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
+  const generator: Generator = {
+    name: "docs-file",
+    async generate(ctx) {
+      if (!ctx.renderContext) {
+        throw new Error("docs-file: renderContext is required (provided by runGen)");
+      }
+      const rc = ctx.renderContext;
+      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,
+          }),
+          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;
+  if (opts?.target) generator.target = opts.target;
+  return generator;
+} as GeneratorFactory<DocsFileOpts>;

package/src/generators/entity-file.ts

@@ -3,6 +3,7 @@ import { perEntity, type Generator, type GeneratorFactory } from "../generator.j
 import { renderEntityFile } from "../templates/entity-file.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
+import { isAbstract } from "../instance-artifacts.js";
 
 export interface EntityFileOpts {
   filter?: (entity: MetaObject) => boolean;
@@ -33,6 +34,12 @@ export const entityFile = function entityFile(opts?: EntityFileOpts): Generator
       if (!ctx.renderContext) {
         throw new Error("entity-file: renderContext is required (provided by runGen)");
       }
+      // Abstract entities contribute shape only. When emitAbstractShapes is off
+      // (cross-port knob; default on) the entity-file generator emits nothing for
+      // them. Instance/write generators skip abstract unconditionally elsewhere.
+      if (isAbstract(entity) && !ctx.renderContext.emitAbstractShapes) {
+        return [];
+      }
       return {
         path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.ts`),
         content: await formatTs(renderEntityFile(entity, ctx.renderContext, { allowlists })),

package/src/generators/index.ts

@@ -6,3 +6,20 @@ export { barrel, type BarrelOpts } from "./barrel.js";
 export { mermaidErDiagram, type MermaidErOptions } from "./mermaid-er.js";
 export { promptRender, type PromptRenderOpts } from "./prompt-render-file.js";
 export { outputParser, type OutputParserOpts } from "./output-parser-file.js";
+export { outputPrompt, type OutputPromptOpts } from "./output-prompt-file.js";
+export { docsFile, type DocsFileOpts } from "./docs-file.js";
+export {
+  templateGenerator,
+  type TemplateGeneratorOpts,
+  type TemplateWalkResult,
+  type TemplateFormat,
+} from "./template-generator.js";
+export type {
+  EntityDocData,
+  StorageFieldDoc,
+  IdentityDoc,
+  RelationshipDoc,
+  UsedByDoc,
+  GeneratedFileDoc,
+} from "./docs-data.js";
+export { buildEntityDocData } from "./docs-data-builder.js";

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

@@ -0,0 +1,66 @@
+// 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).
+//
+// Consumer wiring (metaobjects.config.ts):
+//   generators: [..., promptRender(), outputParser(), outputPrompt()]
+//
+// Custom output directory:
+//   generators: [..., outputPrompt({ outDir: "src/generated/outputs" })]
+
+import {
+  TYPE_OBJECT,
+  TYPE_TEMPLATE,
+  TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_ATTR_PAYLOAD_REF,
+} from "@metaobjectsdev/metadata";
+import {
+  type EmittedFile,
+  type Generator,
+  type GeneratorFactory,
+  oncePerRun,
+} from "../generator.js";
+import { renderOutputPrompt, templateSupportsPrompt } from "../templates/output-prompt.js";
+
+export interface OutputPromptOpts {
+  /** Output directory prefix relative to the target's outDir. Default: "" (root). */
+  outDir?: string;
+  /** Optional named output target (registry key). Defaults to "default". */
+  target?: string;
+}
+
+export const outputPrompt = function outputPrompt(opts?: OutputPromptOpts): Generator {
+  const dirPrefix = opts?.outDir ? `${opts.outDir.replace(/\/$/, "")}/` : "";
+  const generator: Generator = {
+    name: "output-prompt",
+    generate: oncePerRun((_entities, ctx) => {
+      const root = ctx.loadedRoot;
+      const outputs = root
+        .ownChildren()
+        .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).
+        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);
+        if (!vo) continue;
+        files.push({
+          path: `${dirPrefix}${t.name}.prompt.ts`,
+          content: renderOutputPrompt(root, t.name),
+        });
+      }
+      return files;
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<OutputPromptOpts>;

package/src/generators/template-generator.ts

@@ -0,0 +1,106 @@
+// templateGenerator() — the missing primitive identified by the
+// template-driven-codegen design (2026-05-28). Walks the loaded MetaRoot
+// → renders shared Mustache templates via @metaobjectsdev/render → emits
+// EmittedFile[]. Same Generator interface as the per-port hand-coded
+// generators; just adds the "Mustache template" + "walk that yields a
+// data dict per output" primitives.
+//
+// Design line we adopted (from the design doc):
+//   Code → hand-coded generators (ts-poet, idiomatic per-port).
+//   Documents → templateGenerator (shared Mustache templates).
+//
+// docsFile() is the first templateGenerator instance (rc.12). OpenAPI specs,
+// Mermaid diagrams, HTML doc sites, etc. follow as templates + a walk
+// function each.
+
+import type { MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
+import { render, type Provider, type RenderFormat } from "@metaobjectsdev/render";
+import type { Generator, GenContext, EmittedFile, GeneratorFactory } from "../generator.js";
+import { projectProvider } from "../render-engine/framework-provider.js";
+
+export type TemplateFormat = RenderFormat;
+
+export interface TemplateWalkResult {
+  /** The data dict to render against. Templates reference its keys; the
+   *  shape is the public-API contract template authors consume. */
+  data: object;
+  /** Output path RELATIVE to the generator's target outDir. */
+  outputPath: string;
+}
+
+export interface TemplateGeneratorOpts {
+  /** kebab-case identifier; surfaces in diagnostics and the overwrite-policy
+   *  per-file snapshot key. */
+  name: string;
+  /** Walk the loaded metadata tree and produce `{ data, outputPath }` tuples
+   *  — one per emitted file. Pattern A (per-entity), pattern B (single
+   *  aggregator), pattern C (mixed), pattern D (filter inline) all fit. */
+  walk: (root: MetaRoot) => TemplateWalkResult[] | Promise<TemplateWalkResult[]>;
+  /** Template reference. Resolved by the configured Provider chain — by
+   *  default the project's `templates/<ref>.mustache` first, then the
+   *  framework defaults at `codegen-ts/templates/<ref>.mustache`. */
+  template: string;
+  /** Drives the render engine's escaper. Defaults to "text". */
+  format?: TemplateFormat;
+  /** Optional per-entity filter for adopters who want to scope a generator
+   *  via the standard `Generator.filter` plumbing. Not consulted by the
+   *  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(ctx.projectRoot)`, which layers
+   *  the project's `templates/` over the framework defaults. (The project
+   *  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;
+}
+
+export const templateGenerator = function templateGenerator(
+  opts: TemplateGeneratorOpts,
+): Generator {
+  const fmt: TemplateFormat = opts.format ?? "text";
+  const generator: Generator = {
+    name: opts.name,
+    async generate(ctx: GenContext): Promise<EmittedFile[]> {
+      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) {
+        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;
+    },
+  };
+  if (opts.filter) generator.filter = opts.filter;
+  if (opts.target) generator.target = opts.target;
+  return generator;
+} as GeneratorFactory<TemplateGeneratorOpts>;

package/src/index.ts

@@ -24,8 +24,14 @@ export { buildRelationMap } from "./relation-resolver.js";
 export type { RenderContext } from "./render-context.js";
 export { makeRenderContext } from "./render-context.js";
 
-export type { WriteStatus, WriteResult, MergeStrategy } from "./overwrite-policy.js";
-export { decideAndWrite } from "./overwrite-policy.js";
+export type {
+  WriteStatus,
+  WriteResult,
+  MergeStrategy,
+  BaselineMode,
+  DecideAndWriteOpts,
+} from "./overwrite-policy.js";
+export { decideAndWrite, GitMissingError } from "./overwrite-policy.js";
 
 export { CodegenError } from "./errors.js";
 export { GENERATED_HEADER, EXTRA_SUFFIX, DEFAULT_OUT_DIR } from "./constants.js";
@@ -38,6 +44,7 @@ export { packageToPath, entityOutputPath, crossEntitySpecifier, barrelEntrySpeci
 export type { OutputLayout, ResolvedTarget } from "./import-path.js";
 
 export { isProjection, isWriteThrough } from "./projection/projection-detector.js";
+export { isAbstract, emitsInstanceArtifacts, emitsWriteArtifacts } from "./instance-artifacts.js";
 export { extractViewSpec } from "./projection/extract-view-spec.js";
 export type { ExtractContext } from "./projection/extract-view-spec.js";
 export { emitViewDdl } from "./projection/view-ddl-emit.js";
@@ -45,3 +52,28 @@ export type { EmitOptions as ViewDdlEmitOptions } from "./projection/view-ddl-em
 export type { JoinNode, JoinTree, SelectColumn, SelectSpec, ViewSpec } from "./projection/view-spec.js";
 // Prompt construction (FR-004): typed payload + render-handle codegen.
 export { generatePayloadInterfaces, generatePayloadInterfacesBatch, generateRenderHandle } from "./payload-codegen.js";
+
+// Template-driven codegen (rc.12). Factory + framework Provider for adopters
+// who want to wire their own templateGenerator instances. The default
+// docsFile() uses this internally.
+export {
+  templateGenerator,
+  type TemplateGeneratorOpts,
+  type TemplateWalkResult,
+  type TemplateFormat,
+} from "./generators/template-generator.js";
+export {
+  FileSystemProvider,
+  ProviderChain,
+  frameworkTemplatesProvider,
+  projectProvider,
+} from "./render-engine/framework-provider.js";
+export type {
+  EntityDocData,
+  StorageFieldDoc,
+  IdentityDoc,
+  RelationshipDoc,
+  UsedByDoc,
+  GeneratedFileDoc,
+} from "./generators/docs-data.js";
+export { buildEntityDocData } from "./generators/docs-data-builder.js";

package/src/instance-artifacts.ts

@@ -0,0 +1,61 @@
+// Framework-level guard shared by every generator that emits INSTANCE / WRITE
+// artifacts (write forms, CRUD hooks, grid columns, grid hooks, …).
+//
+// Two MetaData concepts make an entity *not* a source of instance artifacts:
+//
+//   1. Abstract (`@isAbstract: true`) — a fundamental MetaData concept: an
+//      abstract type contributes shape via inheritance ONLY. It never has an
+//      instantiable representation, so it must never produce a write form,
+//      CRUD hooks, columns, a grid, or any instance artifact. It still gets a
+//      type-only interface from the entity-file generator (so subclasses and
+//      consumers can reference its shape), but nothing that points at an
+//      `<E>Insert` schema / `$table` / mutation hook it does not have.
+//
+//   2. Projection (read-only view; see `isProjection`) — instantiable for READ
+//      but never for WRITE. It legitimately gets read models + read-only hooks
+//      + grids, but NOT a write form. WRITE-only generators (forms) reuse
+//      `emitsWriteArtifacts` to skip these; read-capable generators (tanstack
+//      hooks/grids) instead branch internally on `isProjection`.
+//
+// Centralizing these as `emitsInstanceArtifacts` / `emitsWriteArtifacts` keeps
+// the rule in one place: a generator composes the matching guard into its
+// `filter` rather than re-deriving "is this abstract / read-only" ad hoc.
+
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { isProjection } from "./projection/projection-detector.js";
+
+/**
+ * True when `entity` is abstract (`@isAbstract: true`).
+ *
+ * Thin, framework-level accessor so generators in sibling codegen packages
+ * have a single import surface for the abstract concept and don't reach into
+ * metadata internals (mirrors how `isProjection` is the shared read-only
+ * discriminator). Abstract types contribute shape via inheritance only.
+ */
+export function isAbstract(entity: MetaData): boolean {
+  return entity.isAbstract === true;
+}
+
+/**
+ * True when `entity` should produce INSTANCE artifacts of ANY kind (read OR
+ * write): CRUD/read hooks, grid columns, grid hooks. Abstract types are
+ * excluded — they have no instantiable representation.
+ *
+ * Read-capable generators (tanstack hooks/grids) compose this so they skip
+ * abstract bases while still serving projections via their own
+ * `isProjection` read-only branch.
+ */
+export function emitsInstanceArtifacts(entity: MetaData): boolean {
+  return !isAbstract(entity);
+}
+
+/**
+ * True when `entity` should produce WRITE artifacts (write forms, mutation
+ * surfaces). Excludes both abstract types (no instance at all) and projections
+ * (read-only views — instantiable for read, never for write).
+ *
+ * WRITE-only generators (e.g. the React form generator) compose this.
+ */
+export function emitsWriteArtifacts(entity: MetaData): boolean {
+  return !isAbstract(entity) && !isProjection(entity);
+}

package/src/metaobjects-config.ts

@@ -37,6 +37,15 @@ export interface MetaobjectsGenConfig extends ResolvedGenConfig {
   columnNamingStrategy?: ColumnNamingStrategy;
   /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
   apiPrefix?: string;
+  /**
+   * Whether abstract entities (`@isAbstract: true`) emit their shape artifact
+   * (the type-only interface / value-object file from the entity-file
+   * generator). Defaults to `true`. Instance/write artifacts (forms, CRUD/read
+   * hooks, grids) are NEVER emitted for abstract entities regardless of this
+   * flag — that invariant lives in `instance-artifacts.ts`. This knob only
+   * governs the shape, mirroring the cross-port `emitAbstractShapes` option.
+   */
+  emitAbstractShapes?: boolean;
   /** Named output destinations. Generators reference one via `target`. */
   targets?: Record<string, TargetConfig>;
   /** importBase for the default target (top-level outDir). */
@@ -57,6 +66,7 @@ export interface MetaobjectsGenConfig extends ResolvedGenConfig {
 export interface NormalizedMetaobjectsGenConfig extends Omit<MetaobjectsGenConfig, "targets"> {
   columnNamingStrategy: ColumnNamingStrategy;
   apiPrefix: string;
+  emitAbstractShapes: boolean;
   outputLayout: OutputLayout;
   targets: Record<string, ResolvedTarget>;
 }
@@ -98,6 +108,7 @@ export function normalizeConfig(config: MetaobjectsGenConfig): NormalizedMetaobj
     ...config,
     columnNamingStrategy: config.columnNamingStrategy ?? DEFAULT_COLUMN_NAMING_STRATEGY,
     apiPrefix: config.apiPrefix ?? "",
+    emitAbstractShapes: config.emitAbstractShapes ?? true,
     outputLayout: config.outputLayout ?? "flat",
     targets: resolveTargets(config),
   };