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

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

@@ -0,0 +1,98 @@
+// 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";
+
+/** Walk up from `start` until we find a `package.json` (i.e., the codegen-ts
+ *  package root), then return `<pkg-root>/templates`. Works the same way
+ *  from `src/render-engine/framework-provider.ts` (during dev) and
+ *  `dist/render-engine/framework-provider.js` (after `npm install`) because
+ *  in both cases we shipped at the package root. */
+function findFrameworkTemplatesDir(start: string): string {
+  let dir = start;
+  for (let i = 0; i < 12; i++) {
+    const pkgJson = join(dir, "package.json");
+    if (existsSync(pkgJson)) {
+      return join(dir, "templates");
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Last resort — caller will get an unresolved-ref error when it tries to
+  // use a framework template that isn't on disk.
+  return join(start, "templates");
+}
+
+const SELF_DIR = (() => {
+  try {
+    return dirname(fileURLToPath(import.meta.url));
+  } catch {
+    return process.cwd();
+  }
+})();
+
+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.
@@ -163,9 +201,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 +232,5 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     }
   }
 
-  return { files: writes, warnings };
+  return { files: writes, warnings, conflicts };
 }