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

package/src/render-engine/framework-provider.ts

@@ -0,0 +1,107 @@
+// FrameworkTemplateProvider — resolves template refs (e.g. "docs/entity-page.md")
+// against the codegen-ts package's `templates/` directory. Adopters who want
+// to override a framework template create their own `templates/<ref>.mustache`
+// file in their project; `ProviderChain` (below) consults the project first
+// and falls back to the framework defaults.
+//
+// Decision D1 from the template-driven-codegen design — hybrid: framework
+// ships defaults, adopters override by file-system convention.
+//
+// The framework Provider is filesystem-backed so it works identically whether
+// codegen-ts runs from source (bun, dev) or from `dist/` (npm install). The
+// `templates/` directory is included in the published tarball via
+// package.json `files: ["dist", "src", "templates", ...]`.
+
+import type { Provider } from "@metaobjectsdev/render";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Canonical shipped template — used to verify a candidate framework
+ *  templates directory actually contains our defaults. Without this check a
+ *  hoisted-install layout (pnpm/bun workspaces) can walk up to a CONSUMER
+ *  package.json and silently return a templates dir that doesn't exist. */
+const CANONICAL_TEMPLATE_REL = "docs/entity-page.md.mustache";
+
+/** Walk up from `start` until we find a `package.json` whose neighbour
+ *  `templates/` directory contains our canonical shipped template (i.e., the
+ *  codegen-ts package root). Works the same way from
+ *  `src/render-engine/framework-provider.ts` (during dev) and
+ *  `dist/render-engine/framework-provider.js` (after `npm install`). */
+function findFrameworkTemplatesDir(start: string): string {
+  let dir = start;
+  while (true) {
+    const pkgJson = join(dir, "package.json");
+    if (existsSync(pkgJson)) {
+      const templatesDir = join(dir, "templates");
+      // Assert we landed at the codegen-ts package root, not a consumer's.
+      if (existsSync(join(templatesDir, CANONICAL_TEMPLATE_REL))) {
+        return templatesDir;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `framework templates dir unresolved: walked up from ${start} without finding a package.json ` +
+    `whose templates/${CANONICAL_TEMPLATE_REL} exists. This usually means codegen-ts was installed ` +
+    `via a hoisted layout (pnpm/bun workspaces) into an unexpected location, or the published ` +
+    `tarball is missing the templates/ directory.`,
+  );
+}
+
+// In ESM (CLAUDE.md: "ESM only. No CommonJS."), `import.meta.url` is
+// guaranteed to be a file: URL; no defensive try/catch needed.
+const SELF_DIR = dirname(fileURLToPath(import.meta.url));
+
+const FRAMEWORK_TEMPLATES_DIR = findFrameworkTemplatesDir(SELF_DIR);
+
+/** Provider backed by an arbitrary on-disk template directory. References
+ *  resolve as `<dir>/<ref>.mustache`. Used by both the framework default
+ *  and adopter override paths. */
+export class FileSystemProvider implements Provider {
+  constructor(private readonly root: string) {}
+  resolve(ref: string): string | undefined {
+    const path = join(this.root, `${ref}.mustache`);
+    if (!existsSync(path)) return undefined;
+    return readFileSync(path, "utf-8");
+  }
+}
+
+/** The framework defaults provider — resolves refs against codegen-ts's own
+ *  `templates/` directory. */
+export const frameworkTemplatesProvider: Provider = new FileSystemProvider(
+  FRAMEWORK_TEMPLATES_DIR,
+);
+
+/** Compose providers: first match wins. Adopters typically chain
+ *  `[projectProvider, frameworkTemplatesProvider]` so their own templates
+ *  override the framework defaults. */
+export class ProviderChain implements Provider {
+  constructor(private readonly providers: readonly Provider[]) {}
+  resolve(ref: string): string | undefined {
+    for (const p of this.providers) {
+      const text = p.resolve(ref);
+      if (text !== undefined) return text;
+    }
+    return undefined;
+  }
+}
+
+/** Build a project-scoped Provider: layers an optional project `templates/`
+ *  directory over the framework defaults. Returns just the framework provider
+ *  when `projectRoot` is undefined / its `templates/` dir doesn't exist. */
+export function projectProvider(projectRoot?: string): Provider {
+  if (projectRoot === undefined) return frameworkTemplatesProvider;
+  const projTemplates = resolve(projectRoot, "templates");
+  if (!existsSync(projTemplates)) return frameworkTemplatesProvider;
+  return new ProviderChain([
+    new FileSystemProvider(projTemplates),
+    frameworkTemplatesProvider,
+  ]);
+}
+
+/** Exposed for tests that want to inspect / clear the resolved framework
+ *  templates directory (don't use outside tests). */
+export const __frameworkTemplatesDirForTests = FRAMEWORK_TEMPLATES_DIR;

package/src/runner.ts

@@ -1,4 +1,5 @@
-import { join } from "node:path";
+import { join, relative, resolve, isAbsolute } from "node:path";
+import { tmpdir } from "node:os";
 import type { MetaData, MetaObject } from "@metaobjectsdev/metadata";
 import { MetaRoot } from "@metaobjectsdev/metadata";
 import type { Generator, GenContext, EmittedFile } from "./generator.js";
@@ -8,7 +9,12 @@ import type { ResolvedTarget } from "./import-path.js";
 import { buildPkMap } from "./pk-resolver.js";
 import { buildRelationMap } from "./relation-resolver.js";
 import { makeRenderContext } from "./render-context.js";
-import { decideAndWrite, type WriteResult, type MergeStrategy } from "./overwrite-policy.js";
+import {
+  decideAndWrite,
+  type WriteResult,
+  type MergeStrategy,
+  type BaselineMode,
+} from "./overwrite-policy.js";
 
 /** JS-identifier-shape only. Prevents filesystem traversal when metadata comes
  *  from untrusted sources (e.g. MCP). Mirrors the guard in legacy generate.ts. */
@@ -21,16 +27,48 @@ export interface RunGenOpts {
   entityFilter?: string[];
   /** Overwrite strategy passed to decideAndWrite. Defaults to "overwrite". */
   mergeStrategy?: MergeStrategy;
+  /** Project root (used to derive the .gen-state/ snapshot directory and to
+   *  key snapshots by project-relative output path). When omitted, falls back
+   *  to process.cwd(). */
+  projectRoot?: string;
+  /** Override the snapshot directory location. Defaults to
+   *  `<projectRoot>/.metaobjects/.gen-state/`. */
+  genStateDir?: string;
+  /** First-time-on-existing-file behavior. Defaults to "default" (write-if-
+   *  different). "fresh" → overwrite and re-baseline (the `--baseline=fresh`
+   *  CLI flag). */
+  baseline?: BaselineMode;
 }
 
 export interface RunGenResult {
   files: WriteResult[];
   warnings: string[];
+  /** Subset of `files` with status "conflict" — surfaced separately so the
+   *  CLI can print the end-of-run summary. */
+  conflicts: WriteResult[];
 }
 
 export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   const warnings: string[] = [];
   const strategy = opts.mergeStrategy ?? "overwrite";
+  const baseline = opts.baseline ?? "default";
+  // When projectRoot is not supplied we DON'T fall back to process.cwd() —
+  // that would leak .gen-state/ into whatever directory happens to be cwd
+  // (e.g. the package dir during a unit-test run). Instead, fall back to a
+  // process-isolated tmpdir, which gives the new-write semantics every call
+  // (the snapshot exists only for the current process). The CLI's
+  // `genCommand` always passes a real projectRoot, so this fallback only
+  // affects programmatic callers (tests, library embedding).
+  const projectRoot = opts.projectRoot !== undefined
+    ? (isAbsolute(opts.projectRoot) ? opts.projectRoot : resolve(opts.projectRoot))
+    : undefined;
+  const genStateDir = opts.genStateDir !== undefined
+    ? (isAbsolute(opts.genStateDir)
+        ? opts.genStateDir
+        : resolve(projectRoot ?? process.cwd(), opts.genStateDir))
+    : (projectRoot !== undefined
+        ? join(projectRoot, ".metaobjects", ".gen-state")
+        : join(tmpdir(), `meta-gen-state-${process.pid}`));
 
   // loadMemory now returns MetaRoot; guard here also covers callers that pass a
   // plain MetaData (e.g. test helpers that build trees programmatically).
@@ -50,7 +88,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       ? "no object children match the provided entityFilter"
       : "root has no object children";
     warnings.push(`No entities to generate — ${reason}.`);
-    return { files: [], warnings };
+    return { files: [], warnings, conflicts: [] };
   }
 
   const safeEntities: MetaObject[] = [];
@@ -64,7 +102,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     safeEntities.push(entity);
   }
   if (safeEntities.length === 0) {
-    return { files: [], warnings };
+    return { files: [], warnings, conflicts: [] };
   }
 
   // 2. Resolve targets + entity-module target.
@@ -136,6 +174,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         outputLayout: selfTarget.outputLayout,
       },
       renderContext,
+      ...(projectRoot !== undefined && { projectRoot }),
       warn: (msg) => warnings.push(`[${generator.name}] ${msg}`),
     };
 
@@ -163,9 +202,29 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
 
   // 5. Write phase.
   const writes: WriteResult[] = [];
+  const conflicts: WriteResult[] = [];
   for (const file of emitted) {
-    const result = decideAndWrite(file.fullPath, file.content, strategy);
+    // Key the snapshot by project-relative path so multi-target projects keep
+    // distinct entries (e.g. `database/Post.ts` vs `web/Post.queries.ts`).
+    // Without an explicit projectRoot we let decideAndWrite derive a stable
+    // hash-of-path key — fine for ephemeral test runs.
+    const policyOpts: import("./overwrite-policy.js").DecideAndWriteOpts = {
+      strategy,
+      genStateDir,
+      baseline,
+    };
+    if (projectRoot !== undefined) {
+      policyOpts.outputRelPath = relative(projectRoot, file.fullPath);
+    }
+    const result = decideAndWrite(file.fullPath, file.content, policyOpts);
     writes.push(result);
+    if (result.status === "conflict") {
+      conflicts.push(result);
+      warnings.push(
+        `Merge conflict in ${file.fullPath}: resolve diff3 markers and re-run ` +
+        `'meta gen' to advance the canonical state.`,
+      );
+    }
     if (result.status === "refused") {
       warnings.push(
         `Refused to overwrite ${file.fullPath}: file exists without @generated header. ` +
@@ -174,5 +233,5 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     }
   }
 
-  return { files: writes, warnings };
+  return { files: writes, warnings, conflicts };
 }

package/src/templates/docs-file.ts

@@ -0,0 +1,51 @@
+// Backward-compatible facade over the rc.12+ template-driven docsFile()
+// implementation. The Markdown structure now lives in
+// `templates/docs/entity-page.md.mustache`; this module preserves the
+// `renderDocsFile()` + `DocsRenderOpts` exports so the per-section unit
+// tests in `test/templates/docs-file.test.ts` keep working without
+// modification.
+//
+// Adopters writing custom docs templates should import the public surface
+// from `@metaobjectsdev/codegen-ts/generators` instead:
+//   - `buildEntityDocData(entity, opts)` for the typed data dict
+//   - `templateGenerator({ template: "docs/entity-page.md", ... })` for the
+//     standard end-to-end generator
+
+import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
+import type { Dialect } from "../column-mapper.js";
+import type { ColumnNamingStrategy } from "../metaobjects-config.js";
+import { render } from "@metaobjectsdev/render";
+import { buildEntityDocData } from "../generators/docs-data-builder.js";
+import { frameworkTemplatesProvider } from "../render-engine/framework-provider.js";
+
+export interface DocsRenderOpts {
+  dialect: Dialect;
+  columnNamingStrategy?: ColumnNamingStrategy;
+  loadedRoot: MetaRoot;
+  /** Names of generators present in the pipeline — drives the "Generated code"
+   *  section. Always includes "entity-file" implicitly. Recognized names:
+   *  "queries-file", "routes-file", "routes-file-hono". */
+  generatorNames?: ReadonlySet<string>;
+}
+
+/** Backward-compatible entry point: builds the EntityDocData payload and
+ *  renders it via the framework template. Byte-identical to the hand-coded
+ *  rc.11 output (gated by `docs-file-conformance.test.ts`). */
+export function renderDocsFile(entity: MetaObject, opts: DocsRenderOpts): string {
+  const data = buildEntityDocData(entity, {
+    dialect: opts.dialect,
+    ...(opts.columnNamingStrategy !== undefined
+      ? { columnNamingStrategy: opts.columnNamingStrategy }
+      : {}),
+    loadedRoot: opts.loadedRoot,
+    ...(opts.generatorNames !== undefined
+      ? { generatorNames: opts.generatorNames }
+      : {}),
+  });
+  return render({
+    ref: "docs/entity-page.md",
+    payload: data,
+    provider: frameworkTemplatesProvider,
+    format: "markdown",
+  });
+}

package/templates/docs/entity-page.md.mustache

@@ -0,0 +1,54 @@
+{{{generatedMarker}}}
+
+# {{entity.name}}
+{{#descriptionQuote}}
+
+{{{.}}}
+{{/descriptionQuote}}
+
+{{{preambleHeader}}}
+{{#hasStorage}}
+
+## Storage
+
+{{{storage.tableHeader}}}
+{{#storage.rows}}
+{{{rowLine}}}
+{{/storage.rows}}
+{{/hasStorage}}
+{{#hasIdentities}}
+
+## Identity
+
+{{#identities}}
+- {{{bullet}}}
+{{/identities}}
+{{/hasIdentities}}
+{{#hasRelationships}}
+
+## Relationships
+
+{{#relationships}}
+- {{{bullet}}}
+{{/relationships}}
+{{/hasRelationships}}
+
+## Validation
+
+- `{{validation.insertSchema}}` (Zod) — for creating new {{validation.lower}}s.
+- `{{validation.updateSchema}}` (Zod) — for partial updates.
+- See `{{validation.entityFile}}` for the exported schemas.
+{{#hasUsedBy}}
+
+## Used by
+
+{{#usedBy}}
+- {{{bullet}}}
+{{/usedBy}}
+{{/hasUsedBy}}
+
+## Generated code
+
+{{#generated}}
+- `{{filename}}` — {{{description}}}
+{{/generated}}