@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/src/constants.ts

@@ -8,3 +8,21 @@ export const EXTRA_SUFFIX = ".extra";
 
 /** Default outDir used by tests + as a sane default for generate(). */
 export const DEFAULT_OUT_DIR = "./src/db/entities";
+
+// ---------------------------------------------------------------------------
+// Codegen-control attributes.
+//
+// These are per-entity opt-in/opt-out flags read by generators (NOT metamodel
+// vocabulary — they tune codegen, not the model). Named here so the literals
+// aren't scattered as magic strings across the generator packages (compile-time
+// typo safety), matching the metadata package's constants discipline.
+// ---------------------------------------------------------------------------
+
+/** `@emitTanstack: false` — skip the TanStack hooks + grid generators for an entity. */
+export const CODEGEN_ATTR_EMIT_TANSTACK = "emitTanstack";
+/** `@emitGrid: true` — opt a TPH subtype IN to its own per-subtype grid (default: the polymorphic base grid is the single source). */
+export const CODEGEN_ATTR_EMIT_GRID = "emitGrid";
+/** `@emitForm: false` — skip the React form generator for an entity. */
+export const CODEGEN_ATTR_EMIT_FORM = "emitForm";
+/** `@emitRoutes: false` — skip the Fastify routes generator for an entity. */
+export const CODEGEN_ATTR_EMIT_ROUTES = "emitRoutes";

package/src/docs-paths.ts

@@ -0,0 +1,128 @@
+// docs-paths.ts — the SINGLE source of truth for where a docs page is written
+// AND how one page links to another. The file location and every inbound link
+// href are derived from the SAME functions here, so they can never diverge.
+//
+// Why this matters: pages are placed by short name. In "flat" layout two nodes
+// that share a short name across different packages (e.g. `acme::sales::Order`
+// and `acme::billing::Order`) would both want `Order.md` and one would silently
+// overwrite the other. `assertNoDuplicateDocPaths()` is the hard backstop that
+// turns that data-loss into a clear error; "package" layout folds pages under
+// package-path subdirs (`acme/sales/Order.md`) so multi-package models work.
+
+import { PACKAGE_SEPARATOR } from "@metaobjectsdev/metadata";
+import { relative as posixRelative } from "node:path/posix";
+import { packageToPath, type OutputLayout } from "./import-path.js";
+
+/** The minimal shape needed to place a docs page / compute a link to it: a
+ *  short name and its EFFECTIVE package. Build one from a metadata node via
+ *  `docPageNode()`. */
+export interface DocPageNode {
+  readonly name: string;
+  readonly package?: string | undefined;
+}
+
+/** A metadata node enough to derive page placement. `resolutionKey()` carries
+ *  the EFFECTIVE package (own package OR the file-default captured at parse
+ *  time) folded as `<pkg>::<name>` — `.package` alone is often undefined for
+ *  objects (FR5d keeps object fqn() bare), so we read placement off the
+ *  resolution key instead. */
+interface PlaceableNode {
+  readonly name: string;
+  resolutionKey(): string;
+}
+
+/** Effective package of a placeable node: the prefix of `resolutionKey()`
+ *  before the trailing `::<name>`, or undefined when the node is package-less. */
+export function effectivePackage(node: PlaceableNode): string | undefined {
+  const key = node.resolutionKey();
+  const suffix = `${PACKAGE_SEPARATOR}${node.name}`;
+  if (key === node.name) return undefined;
+  if (key.endsWith(suffix)) {
+    const pkg = key.slice(0, key.length - suffix.length);
+    return pkg === "" ? undefined : pkg;
+  }
+  return undefined;
+}
+
+/** Build a placement node ({name, effective package}) from a metadata node. The
+ *  single bridge from a loaded node to the path/href helpers — so file location
+ *  and link href derive from the SAME effective package. */
+export function docPageNode(node: PlaceableNode): DocPageNode {
+  return { name: node.name, package: effectivePackage(node) };
+}
+
+/** Output path (relative to the docs out dir) for a node's `.md` page.
+ *  Flat → `<name>.md` (today's value, byte-identical). Package → folded under
+ *  the package path (`acme/sales/Order.md`); a package-less node stays at root. */
+export function docPageOutputPath(layout: OutputLayout, node: DocPageNode): string {
+  const filename = `${node.name}.md`;
+  if (layout === "flat") return filename;
+  const dir = packageToPath(node.package);
+  return dir === "" ? filename : `${dir}/${filename}`;
+}
+
+/** Relative href FROM `fromNode`'s page TO `toNode`'s page. Derived from the
+ *  same `docPageOutputPath()` placement, so a link always points at the file's
+ *  real location in BOTH layouts. Flat → `./<to>.md`; package → a correct
+ *  relative path (e.g. `../comms/OrderEmail.md`). */
+export function docPageHref(
+  layout: OutputLayout,
+  fromNode: DocPageNode,
+  toNode: DocPageNode,
+): string {
+  const toPath = docPageOutputPath(layout, toNode);
+  if (layout === "flat") return `./${toPath}`;
+  // Relative path from the FROM page's directory to the TO page — the same
+  // raw-path rule surfaceCrossHref uses, so the two can never diverge.
+  return surfaceCrossHref(docPageOutputPath(layout, fromNode), toPath);
+}
+
+/** Relative href between two doc pages whose output paths (relative to the shared
+ *  docs outDir) may sit under different surface sub-roots — e.g. model `Order.md`
+ *  and api `api/Order.md`. The shared relative-path rule, over raw paths;
+ *  docPageHref delegates its package-layout branch here. */
+export function surfaceCrossHref(fromOutputPath: string, toOutputPath: string): string {
+  const fromDir = fromOutputPath.includes("/") ? fromOutputPath.slice(0, fromOutputPath.lastIndexOf("/")) : "";
+  const rel = posixRelative(fromDir, toOutputPath);
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+
+/** Href FROM a page (at `fromOutputPath`, relative to the docs root) TO a page
+ *  (`page`, relative to the surface's own root) in an api surface. Relative via
+ *  `surfaceCrossHref` when the surface is in the same tree; absolute `baseUrl/page`
+ *  when the surface declares a baseUrl (federated / separate repo). */
+export function apiSurfaceHref(
+  fromOutputPath: string,
+  surface: { subDir: string; baseUrl?: string },
+  page: string,
+): string {
+  if (surface.baseUrl !== undefined && surface.baseUrl !== "") {
+    return `${surface.baseUrl.replace(/\/$/, "")}/${page}`;
+  }
+  return surfaceCrossHref(fromOutputPath, `${surface.subDir}/${page}`);
+}
+
+/** A page about to be emitted, paired with the FQN of the node that produced it
+ *  (for a precise collision diagnostic). */
+export interface DocPagePlacement {
+  path: string;
+  fqn: string;
+}
+
+/** Hard backstop against silent overwrite (ALL layouts): if two placements
+ *  resolve to the SAME output path, THROW naming both colliding node FQNs and
+ *  the path. Guarantees a docs run never silently drops a page. */
+export function assertNoDuplicateDocPaths(placements: DocPagePlacement[]): void {
+  const seen = new Map<string, string>();
+  for (const { path, fqn } of placements) {
+    const prior = seen.get(path);
+    if (prior !== undefined) {
+      throw new Error(
+        `docs: duplicate output path "${path}" from nodes ${prior} and ${fqn} — ` +
+          `use package layout (outputLayout: "package" / meta docs --layout package) ` +
+          `to disambiguate.`,
+      );
+    }
+    seen.set(path, fqn);
+  }
+}

package/src/enum-import.ts

@@ -0,0 +1,43 @@
+// FR-019 — import-specifier resolution for shared + provided enums.
+//
+// A consuming entity file references a shared enum `E` by importing it:
+//   • materialized (non-@provided) → from the generated shared enums module
+//     (`./enums`, at the entity-module target root, package-layout-aware).
+//   • @provided                    → from the per-port-configured module
+//     (`ctx.providedEnumModule`). Missing config ⇒ a codegen-time error naming
+//     the enum + the config key (ADR-0026: namespace is config, not metadata).
+
+import { withExt } from "./render-context.js";
+import type { RenderContext } from "./render-context.js";
+import { relativeModuleSpecifier } from "./import-path.js";
+import { SHARED_ENUMS_BASENAME } from "./templates/enums-file.js";
+
+/**
+ * Specifier to import a MATERIALIZED shared enum into an entity file in
+ * `entityPkg`. The shared module sits at the entity-module target root; in
+ * package layout the entity may be nested, so the `./enums` base is adjusted by
+ * package depth.
+ */
+export function sharedEnumImportSpecifier(
+  ctx: RenderContext,
+  entityPkg: string | undefined,
+): string {
+  const base = withExt(`./${SHARED_ENUMS_BASENAME}`, ctx.extStyle);
+  return relativeModuleSpecifier(ctx.selfTarget.outputLayout, entityPkg, base);
+}
+
+/**
+ * Specifier to import an externally-PROVIDED enum. Resolved from codegen config
+ * (`providedEnumModule`); throws a clear codegen-time error when unset.
+ */
+export function providedEnumImportSpecifier(ctx: RenderContext, enumName: string): string {
+  const mod = ctx.providedEnumModule;
+  if (mod === undefined || mod === "") {
+    throw new Error(
+      `provided enum "${enumName}" is marked @provided but no module is configured ` +
+      `to import it from. Set "providedEnumModule" in your codegen config (e.g. ` +
+      `providedEnumModule: "@your-app/enums") so the generated code can reference "${enumName}".`,
+    );
+  }
+  return mod;
+}

package/src/enum-shared.ts

@@ -0,0 +1,95 @@
+// FR-019 — shared + externally-provided enum resolution.
+//
+// A reusable enum is a ROOT/package-level abstract `field.enum` (a sibling of
+// object.entity) that concrete entity fields `extends`. Per ADR-0026 such a
+// declaration is materialized ONCE per port and referenced, instead of being
+// redeclared inline in every consuming entity file.
+//
+// Two cases on the abstract declaration:
+//   • non-@provided → metaobjects MATERIALIZES the type once (a shared module),
+//     and consuming fields reference it.
+//   • @provided: true → metaobjects emits NOTHING for the type; consuming fields
+//     reference an existing hand-written/third-party type, resolved via per-port
+//     codegen config (the namespace/module never lives in metadata — ADR-0001).
+//
+// The common inline case (a concrete `field.enum` with @values declared directly,
+// no root-extends) is UNCHANGED — it stays a per-entity `<Entity><Field>` union.
+
+import type { MetaField, MetaRoot } from "@metaobjectsdev/metadata";
+import {
+  FIELD_SUBTYPE_ENUM,
+  FIELD_ATTR_PROVIDED,
+  TYPE_METADATA,
+} from "@metaobjectsdev/metadata";
+import { toPascalCase } from "./naming.js";
+import { enumValues } from "./enum-meta.js";
+
+/** A shared (root-level abstract) enum declaration the codegen must reason about. */
+export interface SharedEnum {
+  /** The materialized type name — the abstract declaration's PascalCase name (cross-port identity). */
+  readonly name: string;
+  /** Member symbols (the @values SSOT). */
+  readonly values: string[];
+  /** True when the declaration carries `@provided: true` (reference, don't materialize). */
+  readonly provided: boolean;
+}
+
+/**
+ * The root-level abstract `field.enum` a concrete enum field resolves to via
+ * `extends`, or undefined when the field is an inline enum (no root-abstract
+ * super). A super qualifies only when it is (a) an abstract field, AND (b) a
+ * direct child of the metadata root (a package-level declaration) — NOT an
+ * abstract field nested inside another object.
+ */
+export function resolveSharedEnumDecl(field: MetaField): MetaField | undefined {
+  if (field.subType !== FIELD_SUBTYPE_ENUM) return undefined;
+  const sup = field.resolveSuper();
+  if (sup === undefined) return undefined;
+  if (!sup.isAbstract) return undefined;
+  // The declaration must sit at the package/root level (sibling of object.entity),
+  // i.e. its parent node is the metadata root.
+  const parent = sup.parent;
+  if (parent === undefined || parent.type !== TYPE_METADATA) return undefined;
+  return sup;
+}
+
+/** The shared-enum descriptor a field resolves to, or undefined for inline enums. */
+export function sharedEnumForField(field: MetaField): SharedEnum | undefined {
+  const decl = resolveSharedEnumDecl(field);
+  if (decl === undefined) return undefined;
+  const values = enumValues(field);
+  if (values === undefined) return undefined;
+  return {
+    name: toPascalCase(decl.name),
+    values,
+    provided: decl.ownAttr(FIELD_ATTR_PROVIDED) === true,
+  };
+}
+
+/**
+ * All shared (root-level abstract) enum declarations in the loaded root that are
+ * actually CONSUMED by at least one concrete entity field — keyed by the
+ * materialized type name. A declaration nobody extends is not materialized (no
+ * dangling type). Deterministic order: first-consumption order across entities.
+ */
+export function collectSharedEnums(root: MetaRoot): Map<string, SharedEnum> {
+  const out = new Map<string, SharedEnum>();
+  for (const entity of root.objects()) {
+    for (const field of entity.fields()) {
+      const shared = sharedEnumForField(field);
+      if (shared === undefined) continue;
+      if (!out.has(shared.name)) out.set(shared.name, shared);
+    }
+  }
+  return out;
+}
+
+/** The shared enums that metaobjects MATERIALIZES (non-@provided, consumed). */
+export function materializedSharedEnums(root: MetaRoot): SharedEnum[] {
+  return [...collectSharedEnums(root).values()].filter((e) => !e.provided);
+}
+
+/** Whether any shared enum (materialized or provided) is consumed in the model. */
+export function hasSharedEnums(root: MetaRoot): boolean {
+  return collectSharedEnums(root).size > 0;
+}

package/src/generator-registry.ts

@@ -0,0 +1,204 @@
+// ADR-0021 D3 — stable-name generator registry.
+//
+// Generators are identified by a STABLE string id (e.g. `entity`, `routes`,
+// `render-helper`) rather than by a language-specific factory import. The id is
+// the cross-port contract: the same logical generator carries the same stable
+// name in every port. This module is the discoverability + identity surface
+// behind `meta gen --list`.
+//
+// It is ADDITIVE. The existing `defineConfig({ generators: [entityFile(), ...] })`
+// factory-array config keeps working unchanged — the registry powers `--list`
+// and a stable identity, it does not replace the config path.
+//
+// Tiering (ADR-0020 / ADR-0021 D1):
+//   - "native"  — the recommended Tier-1 `meta gen` suite (idiomatic emission).
+//   - "neutral" — Tier-2 artifacts owned by the neutral docs engine. `docs` and
+//                 `mermaid-er` are present here for identity/discoverability but
+//                 are NOT part of the recommended native surface — the canonical
+//                 door for documentation is `meta docs` (D1).
+
+import type { Generator } from "./generator.js";
+import {
+  entityFile,
+  queriesFile,
+  callableFile,
+  routesFile,
+  routesFileHono,
+  barrel,
+  mermaidErDiagram,
+  promptRender,
+  outputParser,
+  extractor,
+  outputPrompt,
+  renderHelper,
+  apiDocsFile,
+  docsFile,
+  templateGenerator,
+  traceHelperFile,
+} from "./generators/index.js";
+
+export type GeneratorTier = "native" | "neutral";
+
+export interface GeneratorRegistryEntry {
+  /** Stable, cross-port-consistent id. Equals the registry map key. */
+  name: string;
+  /** One-line (no newline) human description for `--list`. */
+  description: string;
+  /** "native" = recommended `meta gen` suite; "neutral" = `meta docs`-owned. */
+  tier: GeneratorTier;
+  /** Constructs the generator with sensible defaults. Calling it must not throw. */
+  factory: () => Generator;
+  /** Optional one-line options summary for `--list`. */
+  options?: string;
+  /** Optional note — used to point neutral entries at their canonical door. */
+  note?: string;
+}
+
+// The `template` generator is a PRIMITIVE: callers supply { name, walk,
+// template }. For registry identity + `--list` we expose a no-op default so the
+// factory constructs a valid Generator without throwing; real use passes opts
+// via the config factory-array path. (docsFile() is the first instance of this
+// primitive — see template-generator.ts.)
+function templatePrimitive(): Generator {
+  return templateGenerator({
+    name: "template",
+    template: "",
+    walk: () => [],
+  });
+}
+
+export const generatorRegistry: Record<string, GeneratorRegistryEntry> = {
+  // ----- Tier-1 native suite (idiomatic per-port emission) -----------------
+  entity: {
+    name: "entity",
+    description: "Per-entity Drizzle table + typed model module (the entity module).",
+    tier: "native",
+    factory: () => entityFile(),
+    options: "filter?, target?",
+  },
+  queries: {
+    name: "queries",
+    description: "Per-entity typed query helpers (findById/create/...).",
+    tier: "native",
+    factory: () => queriesFile(),
+    options: "filter?, target?",
+  },
+  callable: {
+    name: "callable",
+    description: "Per-entity callable/service surface wrapping the query helpers.",
+    tier: "native",
+    factory: () => callableFile(),
+    options: "filter?, target?",
+  },
+  routes: {
+    name: "routes",
+    description: "Per-entity Fastify CRUD routes (drizzle-fastify mountCrudRoutes).",
+    tier: "native",
+    factory: () => routesFile(),
+    options: "filter?, target?",
+  },
+  "routes-hono": {
+    name: "routes-hono",
+    description: "Per-entity Hono CRUD routes (runtime-ts/hono mountCrudRoutes).",
+    tier: "native",
+    factory: () => routesFileHono(),
+    options: "filter?, target?",
+  },
+  barrel: {
+    name: "barrel",
+    description: "Single index.ts re-exporting every generated entity module.",
+    tier: "native",
+    factory: () => barrel(),
+    options: "target?",
+  },
+  "prompt-render": {
+    name: "prompt-render",
+    description: "Per-template prompt-render helper over the render engine.",
+    tier: "native",
+    factory: () => promptRender(),
+    options: "filter?, target?",
+  },
+  "output-parser": {
+    name: "output-parser",
+    description: "Per-template tolerant output parser (recover-on-receipt).",
+    tier: "native",
+    factory: () => outputParser(),
+    options: "filter?, target?",
+  },
+  extractor: {
+    name: "extractor",
+    description: "Per-template typed extract<Name> helper (strict payload extraction).",
+    tier: "native",
+    factory: () => extractor(),
+    options: "filter?, target?",
+  },
+  "output-prompt": {
+    name: "output-prompt",
+    description: "Per-template output-format prompt fragment generator.",
+    tier: "native",
+    factory: () => outputPrompt(),
+    options: "filter?, target?",
+  },
+  "render-helper": {
+    name: "render-helper",
+    description: "Per-template.output render helper (document/email typed wrappers).",
+    tier: "native",
+    factory: () => renderHelper(),
+    options: "filter?, target?",
+  },
+  template: {
+    name: "template",
+    description: "Generic Mustache template primitive (walk + template → files).",
+    tier: "native",
+    factory: () => templatePrimitive(),
+    options: "name, walk, template, format?, filter?, provider?, target?",
+  },
+  "api-docs": {
+    name: "api-docs",
+    description:
+      "Per-entity/template SDK API reference (the generated code's API, human + agent forms).",
+    tier: "native",
+    factory: () => apiDocsFile(),
+    options: "filter?, target?",
+  },
+
+  "trace-helper": {
+    name: "trace-helper",
+    description: "Per-entity typed record<Entity>/call<Entity> trace helpers (extract + buildLlmCallRow + persist; LlmCallBase-derived entities only).",
+    tier: "native",
+    factory: () => traceHelperFile(),
+    options: "outDir?, target?",
+  },
+
+  // ----- Tier-2 neutral (owned by the `meta docs` engine — D1 / ADR-0020) ---
+  docs: {
+    name: "docs",
+    description: "Neutral per-entity / per-template Markdown documentation pages.",
+    tier: "neutral",
+    factory: () => docsFile(),
+    note: "neutral artifact — use `meta docs` (the single docs door, ADR-0021 D1); not part of the recommended `meta gen` native suite.",
+  },
+  "mermaid-er": {
+    name: "mermaid-er",
+    description: "Mermaid ER diagram of the entity/relationship model.",
+    tier: "neutral",
+    factory: () => mermaidErDiagram(),
+    note: "neutral artifact owned by the docs engine (ADR-0020); surfaced via `meta docs`, not the recommended `meta gen` native suite.",
+  },
+};
+
+/** All registry entries, native first then neutral, alphabetical within tier. */
+export function listGenerators(): GeneratorRegistryEntry[] {
+  const entries = Object.values(generatorRegistry);
+  const byName = (a: GeneratorRegistryEntry, b: GeneratorRegistryEntry) =>
+    a.name.localeCompare(b.name);
+  return [
+    ...entries.filter((e) => e.tier === "native").sort(byName),
+    ...entries.filter((e) => e.tier === "neutral").sort(byName),
+  ];
+}
+
+/** Resolve a generator entry by its stable id, or undefined if unknown. */
+export function getGenerator(id: string): GeneratorRegistryEntry | undefined {
+  return generatorRegistry[id];
+}

package/src/generator.ts

@@ -47,6 +47,12 @@ export interface Generator {
   /** Marks the generator that produces entity modules — the runner uses its
    *  target as the entity-module target for cross-target import resolution. */
   emitsEntityModule?: boolean;
+  /** Marks the OPT-IN Hono routes generator (routesFileHono). The runner
+   *  aggregates this across the active suite into `ctx.config.includeHonoRoutes`,
+   *  so a generator that documents the API surface (api-docs) can AUTO-DETECT
+   *  that Hono routes are actually being emitted and document them — rather than
+   *  silently omitting the Hono CRUD registrars whenever the variant is wired. */
+  emitsHonoRoutes?: boolean;
 }
 
 export type GeneratorFactory<TOpts = void> = TOpts extends void