@metaobjectsdev/codegen-ts 0.7.0-rc.11 → 0.7.0-rc.13

package/dist/generators/docs-file.js

@@ -1,52 +1,77 @@
 // docsFile() — emits `<Entity>.md` next to each generated entity module.
 //
-// Markdown is port-agnostic: the same metadata produces the same documentation
-// page regardless of dialect, output layout, or runtime target. The page covers
-// description / type / source / package preamble; storage table + identity +
-// relationships for table-backed entities; validation entry points; "used by"
-// template cross-references; and the generated-code surface (which sibling
-// files codegen produces). See `templates/docs-file.ts` for the body.
-import { perEntity } from "../generator.js";
-import { renderDocsFile } from "../templates/docs-file.js";
+// 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 { render } from "@metaobjectsdev/render";
 import { entityOutputPath } from "../import-path.js";
+import { projectProvider } from "../render-engine/framework-provider.js";
+import { buildEntityDocData } from "./docs-data-builder.js";
+/** 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) {
     const generator = {
         name: "docs-file",
-        generate: perEntity((entity, ctx) => {
+        async generate(ctx) {
             if (!ctx.renderContext) {
                 throw new Error("docs-file: renderContext is required (provided by runGen)");
             }
             const rc = ctx.renderContext;
-            const generatorNames = readGeneratorNames(ctx);
-            return {
-                path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.md`),
-                content: renderDocsFile(entity, {
+            const provider = projectProvider(ctx.projectRoot ?? process.cwd());
+            const layout = ctx.config.outputLayout ?? "flat";
+            return ctx.loadedRoot.objects().filter(ctx.matches).map((entity) => {
+                const path = entityOutputPath(layout, entity.package, `${entity.name}.md`);
+                const payload = buildEntityDocData(entity, {
                     dialect: rc.dialect,
-                    columnNamingStrategy: rc.columnNamingStrategy,
+                    ...(rc.columnNamingStrategy !== undefined && {
+                        columnNamingStrategy: rc.columnNamingStrategy,
+                    }),
                     loadedRoot: rc.loadedRoot,
-                    generatorNames,
-                }),
-            };
-        }),
+                    generatorNames: KNOWN_SIBLING_GENERATORS,
+                });
+                let content;
+                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) {
+    if (opts?.filter)
         generator.filter = opts.filter;
-    }
-    if (opts?.target) {
+    if (opts?.target)
         generator.target = opts.target;
-    }
     return generator;
 };
-/**
- * `GenContext` does not currently carry the full generator list — that lives on
- * the resolved config inside the runner. Rather than thread a new field through
- * just to populate one optional markdown section, we always list every
- * potential companion. The "Generated code" section becomes "files that may be
- * generated alongside this one" — adopters cross-reference their own
- * `metaobjects.config.ts` to confirm which they actually wired in. This matches
- * the spec guidance "list them all and let the reader figure out which exist."
- */
-function readGeneratorNames(_ctx) {
-    return new Set(["queries-file", "routes-file", "routes-file-hono"]);
-}
 //# sourceMappingURL=docs-file.js.map

package/dist/generators/docs-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"docs-file.js","sourceRoot":"","sources":["../../src/generators/docs-file.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,6EAA6E;AAC7E,8EAA8E;AAC9E,2EAA2E;AAC3E,sEAAsE;AAGtE,OAAO,EAAE,SAAS,EAAyC,MAAM,iBAAiB,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAOrD,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,QAAQ,CAAC,IAAmB;IAC3D,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,WAAW;QACjB,QAAQ,EAAE,SAAS,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;YAClC,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;YAC/E,CAAC;YACD,MAAM,EAAE,GAAG,GAAG,CAAC,aAAa,CAAC;YAC7B,MAAM,cAAc,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;YAC/C,OAAO;gBACL,IAAI,EAAE,gBAAgB,CACpB,GAAG,CAAC,MAAM,CAAC,YAAY,IAAI,MAAM,EACjC,MAAM,CAAC,OAAO,EACd,GAAG,MAAM,CAAC,IAAI,KAAK,CACpB;gBACD,OAAO,EAAE,cAAc,CAAC,MAAM,EAAE;oBAC9B,OAAO,EAAE,EAAE,CAAC,OAAO;oBACnB,oBAAoB,EAAE,EAAE,CAAC,oBAAoB;oBAC7C,UAAU,EAAE,EAAE,CAAC,UAAU;oBACzB,cAAc;iBACf,CAAC;aACH,CAAC;QACJ,CAAC,CAAC;KACH,CAAC;IACF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAmC,CAAC;AAEpC;;;;;;;;GAQG;AACH,SAAS,kBAAkB,CAAC,IAAa;IACvC,OAAO,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,aAAa,EAAE,kBAAkB,CAAC,CAAC,CAAC;AACtE,CAAC"}
+{"version":3,"file":"docs-file.js","sourceRoot":"","sources":["../../src/generators/docs-file.ts"],"names":[],"mappings":"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"}

package/dist/generators/index.d.ts

@@ -7,4 +7,7 @@ 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 { 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";
 //# sourceMappingURL=index.d.ts.map

package/dist/generators/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,SAAS,EACT,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/generators/index.js

@@ -7,4 +7,6 @@ export { mermaidErDiagram } from "./mermaid-er.js";
 export { promptRender } from "./prompt-render-file.js";
 export { outputParser } from "./output-parser-file.js";
 export { docsFile } from "./docs-file.js";
+export { templateGenerator, } from "./template-generator.js";
+export { buildEntityDocData } from "./docs-data-builder.js";
 //# sourceMappingURL=index.js.map

package/dist/generators/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/generators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAuB,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAwB,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAuB,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,cAAc,EAA2B,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAmB,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAyB,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAyB,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAyB,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAqB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/generators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAuB,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAwB,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAuB,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,cAAc,EAA2B,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAmB,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAyB,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAyB,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAyB,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAqB,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EACL,iBAAiB,GAIlB,MAAM,yBAAyB,CAAC;AASjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/generators/template-generator.d.ts

@@ -0,0 +1,41 @@
+import type { MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
+import { type Provider, type RenderFormat } from "@metaobjectsdev/render";
+import type { GeneratorFactory } from "../generator.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 declare const templateGenerator: GeneratorFactory<TemplateGeneratorOpts>;
+//# sourceMappingURL=template-generator.d.ts.map

package/dist/generators/template-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-generator.d.ts","sourceRoot":"","sources":["../../src/generators/template-generator.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAU,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAClF,OAAO,KAAK,EAAsC,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAG5F,MAAM,MAAM,cAAc,GAAG,YAAY,CAAC;AAE1C,MAAM,WAAW,kBAAkB;IACjC;qEACiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC;iCAC6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb;;6EAEyE;IACzE,IAAI,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,kBAAkB,EAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAC/E;;uEAEmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;8EAE0E;IAC1E,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC;;;;;uDAKmD;IACnD,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,iBAAiB,EA8CzB,gBAAgB,CAAC,qBAAqB,CAAC,CAAC"}

package/dist/generators/template-generator.js

@@ -0,0 +1,62 @@
+// 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 { render } from "@metaobjectsdev/render";
+import { projectProvider } from "../render-engine/framework-provider.js";
+export const templateGenerator = function templateGenerator(opts) {
+    const fmt = opts.format ?? "text";
+    const generator = {
+        name: opts.name,
+        async generate(ctx) {
+            let 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 = [];
+            for (const { data, outputPath } of walkRes) {
+                let content;
+                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;
+};
+//# sourceMappingURL=template-generator.js.map

package/dist/generators/template-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-generator.js","sourceRoot":"","sources":["../../src/generators/template-generator.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,yEAAyE;AACzE,yEAAyE;AACzE,qEAAqE;AACrE,sEAAsE;AACtE,oCAAoC;AACpC,EAAE;AACF,gDAAgD;AAChD,gEAAgE;AAChE,+DAA+D;AAC/D,EAAE;AACF,6EAA6E;AAC7E,sEAAsE;AACtE,iBAAiB;AAGjB,OAAO,EAAE,MAAM,EAAoC,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAyCzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,iBAAiB,CACzD,IAA2B;IAE3B,MAAM,GAAG,GAAmB,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC;IAClD,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,CAAC,QAAQ,CAAC,GAAe;YAC5B,IAAI,QAAkB,CAAC;YACvB,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAChC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC3B,CAAC;iBAAM,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;gBACzC,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,IAAI,CACN,kHAAkH;oBAClH,mHAAmH;oBACnH,qGAAqG,CACtG,CAAC;gBACF,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;YAC5C,CAAC;YACD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAChD,MAAM,KAAK,GAAkB,EAAE,CAAC;YAChC,KAAK,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,OAAO,EAAE,CAAC;gBAC3C,IAAI,OAAe,CAAC;gBACpB,IAAI,CAAC;oBACH,OAAO,GAAG,MAAM,CAAC;wBACf,GAAG,EAAE,IAAI,CAAC,QAAQ;wBAClB,OAAO,EAAE,IAAI;wBACb,QAAQ;wBACR,MAAM,EAAE,GAAG;qBACZ,CAAC,CAAC;gBACL,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAC7D,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,CAAC,IAAI,uBAAuB,IAAI,CAAC,QAAQ,UAAU,UAAU,MAAM,GAAG,EAAE,EACjG,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,CAClD,CAAC;gBACJ,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;YAC5C,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC;IACF,IAAI,IAAI,CAAC,MAAM;QAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAChD,IAAI,IAAI,CAAC,MAAM;QAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAChD,OAAO,SAAS,CAAC;AACnB,CAA4C,CAAC"}

package/dist/index.d.ts

@@ -12,8 +12,8 @@ export type { RelationEntry, RelationMap } from "./relation-resolver.js";
 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";
 export { formatTs } from "./format.js";
@@ -27,4 +27,8 @@ export { emitViewDdl } from "./projection/view-ddl-emit.js";
 export type { EmitOptions as ViewDdlEmitOptions } from "./projection/view-ddl-emit.js";
 export type { JoinNode, JoinTree, SelectColumn, SelectSpec, ViewSpec } from "./projection/view-spec.js";
 export { generatePayloadInterfaces, generatePayloadInterfacesBatch, generateRenderHandle } from "./payload-codegen.js";
+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";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE5D,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEvD,YAAY,EAAE,oBAAoB,EAAE,8BAA8B,EAAE,iBAAiB,EAAE,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACtL,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAExE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,YAAY,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjF,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1G,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACxM,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE,YAAY,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,YAAY,EAAE,WAAW,IAAI,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACvF,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAExG,OAAO,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -9,7 +9,7 @@ export { mapColumnType } from "./column-mapper.js";
 export { buildPkMap } from "./pk-resolver.js";
 export { buildRelationMap } from "./relation-resolver.js";
 export { makeRenderContext } from "./render-context.js";
-export { decideAndWrite } 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";
 export { formatTs } from "./format.js";
@@ -20,4 +20,10 @@ export { extractViewSpec } from "./projection/extract-view-spec.js";
 export { emitViewDdl } from "./projection/view-ddl-emit.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, } from "./generators/template-generator.js";
+export { FileSystemProvider, ProviderChain, frameworkTemplatesProvider, projectProvider, } from "./render-engine/framework-provider.js";
+export { buildEntityDocData } from "./generators/docs-data-builder.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,EAAE;AACF,yCAAyC;AACzC,wEAAwE;AAExE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIrC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAGxE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjF,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1G,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAGxM,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEpE,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAG5D,uEAAuE;AACvE,OAAO,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,EAAE;AACF,yCAAyC;AACzC,wEAAwE;AAExE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIrC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAGxE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AASxD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjF,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1G,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAGxM,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEpE,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAG5D,uEAAuE;AACvE,OAAO,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEvH,6EAA6E;AAC7E,sEAAsE;AACtE,mCAAmC;AACnC,OAAO,EACL,iBAAiB,GAIlB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,0BAA0B,EAC1B,eAAe,GAChB,MAAM,uCAAuC,CAAC;AAS/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/overwrite-policy.d.ts

@@ -1,8 +1,45 @@
-export type WriteStatus = "new" | "overwrite" | "refused" | "skipped";
+export type WriteStatus = "new" | "unchanged" | "overwrite" | "merged" | "conflict" | "refused" | "skipped";
+/**
+ * "overwrite" — default; three-way merge if .gen-state exists, else write-if-
+ *   different / first-time-existing flow.
+ * "skip-existing" — never write over an existing file; status "skipped".
+ *   Useful for `meta gen --dry-run` style flows.
+ */
 export type MergeStrategy = "overwrite" | "skip-existing";
+/** "default" — the standard three-way merge flow described in the file header.
+ *  "fresh" — opt-in via `meta gen --baseline=fresh`. When .gen-state is absent
+ *  but the file exists, OVERWRITE with fresh content and seed .gen-state from
+ *  the fresh content (caveat 3 escape hatch). */
+export type BaselineMode = "default" | "fresh";
+export interface DecideAndWriteOpts {
+    strategy?: MergeStrategy;
+    /** Absolute path to the .gen-state/ root for this project. When undefined,
+     *  we fall back to a process-isolated tmpdir — fine for tests but the CLI
+     *  always supplies the real project value via runGen(). */
+    genStateDir?: string;
+    /** Path the snapshot is keyed by — usually the path relative to the
+     *  project root, but ANY stable identifier works. When undefined, derived
+     *  from `path` (so unit tests can call without supplying it). */
+    outputRelPath?: string;
+    /** First-time-existing-file behavior. */
+    baseline?: BaselineMode;
+}
 export interface WriteResult {
     path: string;
     status: WriteStatus;
+    /** Present when status is "conflict" — human-readable hint identifying the
+     *  file the user must resolve. */
+    conflictHint?: string;
+}
+/** Thrown when git is unavailable. Surfaces as a clear CLI error rather than
+ *  a generic ENOENT halfway through a regen. */
+export declare class GitMissingError extends Error {
+    constructor();
 }
-export declare function decideAndWrite(path: string, content: string, strategy?: MergeStrategy): WriteResult;
+/**
+ * The main entry point. Backward-compatible with the rc.11 signature: passing
+ * a `MergeStrategy` string as the third argument continues to work; passing
+ * an options object opts into three-way merge.
+ */
+export declare function decideAndWrite(path: string, content: string, optsOrStrategy?: DecideAndWriteOpts | MergeStrategy): WriteResult;
 //# sourceMappingURL=overwrite-policy.d.ts.map

package/dist/overwrite-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overwrite-policy.d.ts","sourceRoot":"","sources":["../src/overwrite-policy.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,eAAe,CAAC;AAE1D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,aAA2B,GACpC,WAAW,CAmBb"}
+{"version":3,"file":"overwrite-policy.d.ts","sourceRoot":"","sources":["../src/overwrite-policy.ts"],"names":[],"mappings":"AAqCA,MAAM,MAAM,WAAW,GACnB,KAAK,GACL,WAAW,GACX,WAAW,GACX,QAAQ,GACR,UAAU,GACV,SAAS,GACT,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,eAAe,CAAC;AAE1D;;;iDAGiD;AACjD,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;+DAE2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;qEAEiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB;sCACkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAoED;gDACgD;AAChD,qBAAa,eAAgB,SAAQ,KAAK;;CAQzC;AAsFD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,kBAAkB,GAAG,aAAkB,GACtD,WAAW,CAgGb"}