@metaobjectsdev/codegen-ts 0.12.5 → 0.13.0-rc.1

package/src/reference/queries.ts

@@ -0,0 +1,124 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/queries.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts:
+//   import { queriesFile } from "./codegen/generators/queries";
+//
+// use-when:      you want generated typed CRUD finders (find<E>ById, list<E>s, create/update/delete)
+//                over Drizzle. Drop it if you hand-write your data access.
+// emits:         <target>/<Entity>.queries.ts per write-through entity.
+// customize:     the vanilla CRUD assembly below is OWNED — reorder, drop verbs (e.g. no delete),
+//                change the Db type alias, add your own finders. The render<Verb>Fn primitives emit
+//                each block; call your own instead to change a verb's body.
+// composes-with: entity.ts (imports the table + InsertSchema it emits).
+//
+// NOTE: the advanced TPH-base + projection variants delegate to the engine's composer
+// (`renderQueriesFile`) — they're rarely customized. To own those too, copy their branches
+// out of the package source. The vanilla path here is byte-identical to the built-in.
+
+import { code, joinCode, type Code } from "ts-poet";
+import { OBJECT_SUBTYPE_VALUE, type MetaObject } from "@metaobjectsdev/metadata";
+import {
+  perEntity,
+  type Generator,
+  type GeneratorFactory,
+  type RenderContext,
+  entityModuleSpecifier,
+  renderFindByIdFn,
+  renderListFn,
+  renderCreateFn,
+  renderUpdateFn,
+  renderDeleteByIdFn,
+  isTphDiscriminatorBase,
+  isProjection,
+  isTphSubtype,
+  renderQueriesFile, // engine composer — used for the delegated variants
+  formatTs,
+  entityOutputPath,
+  GENERATED_HEADER,
+} from "@metaobjectsdev/codegen-ts";
+
+// --- composition (OWNED for the common case) ---
+function renderQueries(obj: MetaObject, ctx: RenderContext): string {
+  // Advanced variants delegate to the engine (byte-identical). Own them by copying their source.
+  if (isTphDiscriminatorBase(obj, ctx.loadedRoot) || isProjection(obj)) {
+    return renderQueriesFile(obj, ctx);
+  }
+
+  const entityName = obj.name;
+  const entityFileName = entityModuleSpecifier(
+    ctx.selfTarget,
+    ctx.entityModuleTarget,
+    obj.package,
+    entityName,
+    ctx.extStyle,
+  );
+  const varName = ctx.collectionName(entityName);
+
+  // `db` is parameter-passed into every finder (ADR-0008). Emit the dialect-correct
+  // Drizzle type alias so signatures typecheck without the consumer constructing one.
+  const dbTypeImport =
+    ctx.dialect === "postgres"
+      ? `import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";`
+      : `import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";`;
+  const dbTypeAlias =
+    ctx.dialect === "postgres"
+      ? `type Db = PgDatabase<PgQueryResultHKT, Record<string, never>>;`
+      : `type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;`;
+
+  const literalImports = code`
+${dbTypeImport}
+${dbTypeAlias}
+
+import { ${varName}, type ${entityName}, ${entityName}InsertSchema } from ${JSON.stringify(entityFileName)};
+`;
+
+  const sections: Code[] = [
+    literalImports,
+    renderFindByIdFn(obj, ctx),
+    renderListFn(obj, ctx),
+    renderCreateFn(obj, ctx),
+    renderUpdateFn(obj, ctx),
+    renderDeleteByIdFn(obj, ctx),
+  ];
+
+  const body = joinCode(sections, { on: "\n" }).toString();
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Source metadata: ${entityName} (${obj.fqn()})\n` +
+    `// Customize via ${entityName}.extra.ts in this directory (additional queries, custom logic).\n`;
+  return header + body;
+}
+
+export interface QueriesFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+// value objects have no identity (findById/updateById would target a non-existent column),
+// and TPH subtypes emit no standalone queries file — both are skipped unconditionally.
+const skipNonQueryable = (e: MetaObject): boolean =>
+  e.subType !== OBJECT_SUBTYPE_VALUE && !isTphSubtype(e);
+
+export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generator {
+  const userFilter = opts?.filter;
+  const filter: (e: MetaObject) => boolean = userFilter
+    ? (e) => skipNonQueryable(e) && userFilter(e)
+    : skipNonQueryable;
+
+  const generator: Generator = {
+    name: "queries-file",
+    filter,
+    generate: perEntity(async (entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error("queries-file: renderContext is required (provided by runGen)");
+      }
+      return {
+        path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.queries.ts`),
+        content: await formatTs(renderQueries(entity, ctx.renderContext)),
+      };
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<QueriesFileOpts>;

package/src/reference/routes.ts

@@ -0,0 +1,58 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/routes.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts:
+//   import { routesFile } from "./codegen/generators/routes";
+//
+// use-when:      you want generated Fastify REST routes per entity. Drop it and hand-write routes
+//                if you need bespoke endpoints — or keep it and add handlers via <Entity>.extra.ts.
+// emits:         <target>/<Entity>.routes.ts — full CRUD for write-through entities, read-only
+//                (GET list + GET :id) for projections, polymorphic + per-subtype for TPH bases.
+// customize:     this generator (filter, output path, per-entity @emitRoutes opt-out, target) is
+//                YOURS — edit it freely. The route *composition* itself is richer than the others
+//                (M:N junction traversal, TPH per-subtype route sets), so it stays in the engine via
+//                `renderRoutesFile`. To own the composition too, copy `renderRoutesFile`'s body out
+//                of the package source — it dispatches projection → mountReadOnlyCrudRoutes,
+//                write-through → mountCrudRoutes (+ M:N mounts). For per-verb control, import the
+//                mount* helpers from `@metaobjectsdev/runtime-ts/drizzle-fastify` and mix with your
+//                own handlers (auth, side effects).
+// composes-with: entity.ts (imports the table/schemas/allowlists), queries.ts.
+
+import { type MetaObject } from "@metaobjectsdev/metadata";
+import {
+  perEntity,
+  type Generator,
+  type GeneratorFactory,
+  renderRoutesFile,
+  isTphSubtype,
+  formatTs,
+  entityOutputPath,
+  CODEGEN_ATTR_EMIT_ROUTES,
+} from "@metaobjectsdev/codegen-ts";
+
+export interface RoutesFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator {
+  const userFilter = opts?.filter ?? (() => true);
+  const generator: Generator = {
+    name: "routes-file",
+    // per-entity opt-out via `@emitRoutes: false`; TPH subtypes get no standalone routes
+    // file (their routes live in the discriminator base's); AND-composed with your filter.
+    filter: (e: MetaObject) =>
+      e.ownAttr(CODEGEN_ATTR_EMIT_ROUTES) !== false && !isTphSubtype(e) && userFilter(e),
+    generate: perEntity(async (entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error("routes-file: renderContext is required (provided by runGen)");
+      }
+      return {
+        path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.routes.ts`),
+        content: await formatTs(renderRoutesFile(entity, ctx.renderContext)),
+      };
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<RoutesFileOpts>;

package/src/reference-templates.ts

@@ -0,0 +1,49 @@
+// ADR-0034 scaffold-and-own — locate + read the copyable reference generators that
+// live (as raw source assets) in `src/reference/*.ts`. `meta init` reads them through
+// here and writes them into the consumer's repo (e.g. `codegen/generators/*.ts`), which
+// the consumer then OWNS. The templates import only `@metaobjectsdev/codegen-ts` (the
+// stable engine), so a copied file works verbatim with no rewriting.
+//
+// The reference files are excluded from the tsc build (they are scaffold assets, not
+// package source — see tsconfig.json). They ship to npm via the package `files: ["src"]`
+// entry, so they are present at `<pkg>/src/reference/*.ts` in a published install.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Basenames (no extension) of the copyable reference generators shipped in `src/reference/`. */
+export const REFERENCE_GENERATOR_NAMES = ["entity", "queries", "routes", "barrel"] as const;
+export type ReferenceGeneratorName = (typeof REFERENCE_GENERATOR_NAMES)[number];
+
+/** A directory is the reference root iff it holds the entity reference template. */
+function isReferenceRoot(dir: string): boolean {
+  return existsSync(join(dir, "entity.ts"));
+}
+
+/**
+ * Resolve the `src/reference/` directory holding the copyable reference generators.
+ * Works in dev (this module runs from `src/`, templates at `./reference/`) and in a
+ * published install (this module runs from `dist/`, templates at `../src/reference/`,
+ * since `src/` ships alongside `dist/`). Walks up checking both layouts at each level.
+ */
+export function resolveReferenceRoot(): string {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i++) {
+    for (const candidate of [join(dir, "reference"), join(dir, "src", "reference")]) {
+      if (isReferenceRoot(candidate)) return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "codegen-ts reference templates not found — looked for `reference/` and `src/reference/` " +
+      "walking up from the codegen-ts module.",
+  );
+}
+
+/** Read the raw source of one reference generator (e.g. `"entity"` → the text of `entity.ts`). */
+export function readReferenceTemplate(name: ReferenceGeneratorName): string {
+  return readFileSync(join(resolveReferenceRoot(), `${name}.ts`), "utf8");
+}

package/src/template-codegen/output-pattern.ts

@@ -0,0 +1,36 @@
+// Expands the tiny, fixed output-pattern grammar shared cross-port (SP-1 §3.3).
+// Placeholders: {name}, {Name} (PascalCase of name), {package} (:: → /).
+// An empty {package} collapses its trailing slash so `{package}/{name}` with no
+// package yields just `{name}`. Unknown placeholders are a hard error.
+
+const KNOWN = new Set(["name", "Name", "package"]);
+
+function pascalCase(s: string): string {
+  return s
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("");
+}
+
+export function expandOutputPattern(
+  pattern: string,
+  vars: { name?: string; package?: string },
+): string {
+  let pkgWasEmpty = false;
+  const out = pattern.replace(/\{(\w+)\}/g, (_m, token: string) => {
+    if (!KNOWN.has(token)) {
+      throw new Error(`unknown placeholder {${token}} in output pattern '${pattern}'`);
+    }
+    if (token === "package") {
+      const p = (vars.package ?? "").replaceAll("::", "/");
+      if (p === "") pkgWasEmpty = true;
+      return p;
+    }
+    if (vars.name === undefined) {
+      throw new Error(`output pattern '${pattern}' uses {${token}} but no entity name is in scope`);
+    }
+    return token === "Name" ? pascalCase(vars.name) : vars.name;
+  });
+  return pkgWasEmpty ? out.replace(/^\/+/, "").replace(/\/{2,}/g, "/") : out;
+}

package/src/template-codegen/template-data.ts

@@ -0,0 +1,87 @@
+// The NEUTRAL, structural codegen template data dict (SP-1 §3.2). Distinct from
+// the Markdown-flavored EntityDocData — this carries raw structural facts only,
+// so a consumer's Mustache template can emit any language's code from it. The
+// field names here are a byte-gated cross-port contract; change them only via the
+// spec (and the conformance corpus).
+import type { MetaObject, MetaRoot, MetaField } from "@metaobjectsdev/metadata";
+import { FIELD_ATTR_VALUES, FIELD_SUBTYPE_ENUM } from "@metaobjectsdev/metadata";
+import { effectivePackage } from "../docs-paths.js";
+
+/** The effective package of an object — its own package OR the file-default
+ *  folded into `resolutionKey()`. `entity.package` alone is usually undefined
+ *  (object fqn() stays bare), so all package reads go through here. */
+export function packageOf(entity: MetaObject): string {
+  return effectivePackage(entity) ?? "";
+}
+
+export interface FieldTemplateData {
+  name: string;
+  /** Neutral field subtype, e.g. "string" | "int" | "currency" | "enum".
+   *  Arrayness is carried by `isArray`, NOT appended here. */
+  type: string;
+  required: boolean;
+  isArray: boolean;
+  maxLength?: number;
+  enumValues?: string[];
+}
+export interface IdentityTemplateData { kind: string; fields: string[]; }
+export interface RelationshipTemplateData { name: string; cardinality: string; targetRef: string; }
+export interface EntityTemplateData {
+  name: string;
+  package: string;
+  fields: FieldTemplateData[];
+  identities: IdentityTemplateData[];
+  relationships: RelationshipTemplateData[];
+}
+export interface PackageTemplateData { package: string; entities: EntityTemplateData[]; }
+export interface ModelTemplateData { packages: PackageTemplateData[]; }
+
+function fieldData(field: MetaField): FieldTemplateData {
+  const d: FieldTemplateData = {
+    name: field.name,
+    type: field.subType,
+    required: field.isRequired,
+    isArray: field.isArray === true,
+  };
+  if (typeof field.maxLength === "number") d.maxLength = field.maxLength;
+  if (field.subType === FIELD_SUBTYPE_ENUM) {
+    const vals = field.attr(FIELD_ATTR_VALUES);
+    if (Array.isArray(vals)) d.enumValues = vals.map((v) => String(v));
+  }
+  return d;
+}
+
+export function buildEntityTemplateData(entity: MetaObject): EntityTemplateData {
+  return {
+    name: entity.name,
+    package: packageOf(entity),
+    fields: entity.fields().map(fieldData),
+    identities: entity.identities().map((i) => ({ kind: i.subType, fields: [...i.fields] })),
+    relationships: entity.relationships().map((r) => ({
+      name: r.name,
+      cardinality: r.cardinality ?? "",
+      targetRef: r.objectRef ?? "",
+    })),
+  };
+}
+
+export function buildPackageTemplateData(pkg: string, entities: MetaObject[]): PackageTemplateData {
+  return { package: pkg, entities: entities.map(buildEntityTemplateData) };
+}
+
+/** Groups concrete (non-abstract) objects by package — packages ascending,
+ *  entities in `root.objects()` order. Abstract objects never emit instance
+ *  artifacts, so they are excluded. */
+export function buildModelTemplateData(root: MetaRoot): ModelTemplateData {
+  const concrete = root.objects().filter((o) => o.isAbstract !== true);
+  const byPkg = new Map<string, MetaObject[]>();
+  for (const o of concrete) {
+    const pkg = packageOf(o);
+    let bucket = byPkg.get(pkg);
+    if (bucket === undefined) { bucket = []; byPkg.set(pkg, bucket); }
+    bucket.push(o);
+  }
+  return {
+    packages: [...byPkg.keys()].sort().map((pkg) => buildPackageTemplateData(pkg, byPkg.get(pkg)!)),
+  };
+}

package/src/template-codegen/template-spec.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://metaobjects.dev/schema/template-spec.json",
+  "title": "MetaObjects template-codegen spec",
+  "description": "Declarative Mustache template-generator spec (SP-1). Consumed by the CLI ports (C#/Python) and TS.",
+  "type": "object",
+  "required": ["generators"],
+  "additionalProperties": false,
+  "properties": {
+    "generators": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "template", "scope", "outputPattern"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "template": { "type": "string", "minLength": 1 },
+          "scope": { "enum": ["perEntity", "perPackage", "perModel"] },
+          "outputPattern": { "type": "string", "minLength": 1 },
+          "format": { "enum": ["text", "html", "xml", "csv", "json", "markdown", "spreadsheet"] },
+          "target": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/src/template-codegen/template-spec.ts

@@ -0,0 +1,75 @@
+// The declarative JSON template-spec the CLI ports (C#/Python) consume, and TS
+// can spread into `generators`. The JSON shape is the cross-port contract
+// (SP-1 §4); a JSON Schema (template-spec.schema.json) sits beside it.
+import { ESCAPERS, type RenderFormat } from "@metaobjectsdev/render";
+import type { Generator } from "../generator.js";
+import { templateGenerator, type TemplateScope } from "../generators/template-generator.js";
+
+const SCOPES = ["perEntity", "perPackage", "perModel"] as const satisfies readonly TemplateScope[];
+const FORMATS = Object.keys(ESCAPERS) as readonly RenderFormat[];
+
+export interface TemplateSpecEntry {
+  name: string;
+  template: string;
+  scope: TemplateScope;
+  outputPattern: string;
+  format?: RenderFormat;
+  target?: string;
+}
+export interface TemplateSpecFile { generators: TemplateSpecEntry[]; }
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Validate + narrow an untyped JSON value into a TemplateSpecFile. Throws on
+ *  any shape violation (missing/empty required string, bad scope, non-object). */
+export function parseTemplateSpec(json: unknown): TemplateSpecFile {
+  if (!isRecord(json) || !Array.isArray(json.generators)) {
+    throw new Error("template-spec: expected an object with a `generators` array");
+  }
+  const generators = json.generators.map((raw, i): TemplateSpecEntry => {
+    if (!isRecord(raw)) throw new Error(`template-spec generators[${i}]: expected an object`);
+    for (const key of ["name", "template", "scope", "outputPattern"] as const) {
+      if (typeof raw[key] !== "string" || raw[key] === "") {
+        throw new Error(`template-spec generators[${i}]: missing or empty required string '${key}'`);
+      }
+    }
+    if (!SCOPES.includes(raw.scope as TemplateScope)) {
+      throw new Error(
+        `template-spec generators[${i}]: scope must be one of ${SCOPES.join(" | ")}, got '${String(raw.scope)}'`,
+      );
+    }
+    const entry: TemplateSpecEntry = {
+      name: raw.name as string,
+      template: raw.template as string,
+      scope: raw.scope as TemplateScope,
+      outputPattern: raw.outputPattern as string,
+    };
+    if (raw.format !== undefined) {
+      if (typeof raw.format !== "string" || !FORMATS.includes(raw.format as RenderFormat)) {
+        throw new Error(
+          `template-spec generators[${i}]: format must be one of ${FORMATS.join(" | ")}, got '${String(raw.format)}'`,
+        );
+      }
+      entry.format = raw.format as RenderFormat;
+    }
+    if (typeof raw.target === "string") entry.target = raw.target;
+    return entry;
+  });
+  return { generators };
+}
+
+/** Map a parsed spec into runnable Generators (one templateGenerator per entry). */
+export function templateSpecToGenerators(spec: TemplateSpecFile): Generator[] {
+  return spec.generators.map((e) =>
+    templateGenerator({
+      name: e.name,
+      template: e.template,
+      scope: e.scope,
+      outputPattern: e.outputPattern,
+      ...(e.format !== undefined ? { format: e.format } : {}),
+      ...(e.target !== undefined ? { target: e.target } : {}),
+    }),
+  );
+}