@metaobjectsdev/codegen-ts 1.0.2 → 1.0.4-rc.1

package/src/generator-registry.ts

@@ -10,6 +10,13 @@
 // factory-array config keeps working unchanged — the registry powers `--list`
 // and a stable identity, it does not replace the config path.
 //
+// **This is a SLICE, not the whole catalog.** `codegen-ts` cannot import
+// `codegen-ts-react` / `codegen-ts-tanstack` (dependency direction), so those two
+// packages export their own slices and the CLI unions all three
+// (`cli/src/lib/catalog.ts`). Set equality against the cross-port manifest is a
+// property of the COMPOSED catalog and is asserted there; this package's own
+// conformance test can only check one direction — no rogue names.
+//
 // 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
@@ -18,6 +25,8 @@
 //                 door for documentation is `meta docs` (D1).
 
 import type { Generator } from "./generator.js";
+import type { MetaobjectsGenConfig } from "./metaobjects-config.js";
+import { REFERENCE_GENERATOR_NAMES } from "./reference-templates.js";
 // The four ADR-0034 ownable generators are no longer exported from ./generators/index.js
 // (1.0 removed them — see that file's header). They remain the engine's internal composers
 // and the stable-name registry still constructs them, so import them from their own modules.
@@ -39,13 +48,56 @@ import {
   docsFile,
   templateGenerator,
   traceHelperFile,
+  sharedModelFile,
+  requirementTests,
 } from "./generators/index.js";
 
 export type GeneratorTier = "native" | "neutral";
 
+/**
+ * The six layers a generator can belong to — the axis an adopter SELECTS BY.
+ *
+ * Cross-port: `layer` is gated by every port's registry-conformance test against
+ * `fixtures/generator-registry-conformance/registry.json`, exactly as `tier` is, so a
+ * polyglot agent groups the catalog by the same words everywhere.
+ *
+ * Six, not ten. The first four are app-shape decisions a builder makes; `docs` is on by
+ * default (`meta docs`); `capability` holds the ones the MODEL has already made — nobody
+ * picks `prompt-render` by browsing a taxonomy, they pick it because they declared a
+ * `template.prompt`, which `meta gen --list --probe` reports with a real file count. A
+ * layer with one member does no grouping work, so do not split `capability` to tidy it.
+ */
+export const GENERATOR_LAYERS = [
+  "model",
+  "persistence",
+  "api",
+  "client",
+  "docs",
+  "capability",
+] as const;
+export type Layer = (typeof GENERATOR_LAYERS)[number];
+
+/**
+ * The framework a generator's OUTPUT targets. Absent = framework-neutral.
+ *
+ * Exclusivity is an ADVISORY and only on the `api` layer (spec §8a): `routes` and
+ * `routes-hono` emit to different paths, so wiring both is legal and silently produces
+ * two HTTP surfaces — worth a warning, never an error, because migrating between them is
+ * legitimate. There is NO general per-layer rule: `@metaobjectsdev/tanstack` peers on
+ * `react`, so `form` (react) + `hooks`/`grid` (tanstack) is the intended composition.
+ */
+export type GeneratorFramework = "fastify" | "hono" | "react" | "tanstack";
+
 export interface GeneratorRegistryEntry {
   /** Stable, cross-port-consistent id. Equals the registry map key. */
   name: string;
+  /**
+   * Catalog discriminator. Today every entry is a generator; FR-043 adds
+   * `kind: "library"` rows to the same table rather than building a parallel one.
+   */
+  kind: "generator";
+  /** The selection axis — see {@link GENERATOR_LAYERS}. Gated cross-port. */
+  layer: Layer;
   /** One-line (no newline) human description for `--list`. */
   description: string;
   /** "native" = recommended `meta gen` suite; "neutral" = `meta docs`-owned. */
@@ -54,10 +106,55 @@ export interface GeneratorRegistryEntry {
   factory: () => Generator;
   /** Optional one-line options summary for `--list`. */
   options?: string;
+  /** The framework this generator's OUTPUT targets. Absent = framework-neutral. */
+  framework?: GeneratorFramework;
+  /**
+   * Stable names whose emitted output THIS generator's output imports.
+   *
+   * Resolved, not trusted: a gate dry-runs every generator, resolves each emitted
+   * RELATIVE import back to whichever generator emits that path, and asserts the result
+   * is a subset of this list — so a generator that quietly starts depending on `entity`
+   * cannot ship claiming it depends on nothing.
+   */
+  requires?: readonly string[];
+  /**
+   * The `@metaobjectsdev` runtime packages the EMITTED code imports.
+   *
+   * PLURAL, against the design's first sketch, because the emitted code is: an
+   * `output-parser` module imports `@metaobjectsdev/metadata`, `/render` AND
+   * `/runtime-ts`, and a `hooks` module imports `/runtime-web` and `/tanstack`. A
+   * singular field would have forced two of the three to go undeclared, which is the
+   * exact under-declaration the gate exists to catch. Resolved, not trusted — the
+   * emitted files are read back and every `@metaobjectsdev` import must appear here.
+   */
+  runtimePackages?: readonly string[];
+  /**
+   * Third-party packages the EMITTED code imports.
+   *
+   * Per generator rather than derived from {@link runtimePackages}, because
+   * `@metaobjectsdev/runtime-ts`'s peers are a union (drizzle-orm, fastify, hono, kysely,
+   * zod) — deriving per package would tell someone ejecting `entity` to install both
+   * Fastify and Hono. Version RANGES are read from the runtime package's own
+   * `peerDependencies`, never written here. Gated the same way `requires` is.
+   */
+  runtimePeers?: readonly string[];
+  /**
+   * Config keys this generator reads. Typed against the real config so a renamed key
+   * breaks the build instead of going quietly stale — the same "resolved, not trusted"
+   * doctrine as `requires`, obtained here for free from the type system.
+   */
+  configKeys?: readonly (keyof MetaobjectsGenConfig)[];
+  /** True iff this package ships a `src/reference/<name>.ts` for `meta eject`. */
+  ejectable: boolean;
   /** Optional note — used to point neutral entries at their canonical door. */
   note?: string;
 }
 
+/** True iff this package ships a copyable reference template for `name`. */
+function ejectable(name: string): boolean {
+  return (REFERENCE_GENERATOR_NAMES as readonly string[]).includes(name);
+}
+
 // 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
@@ -72,129 +169,244 @@ function templatePrimitive(): Generator {
 }
 
 export const generatorRegistry: Record<string, GeneratorRegistryEntry> = {
-  // ----- Tier-1 native suite (idiomatic per-port emission) -----------------
+  // ----- model ------------------------------------------------------------
   entity: {
     name: "entity",
+    kind: "generator",
+    layer: "model",
     description: "Per-entity Drizzle table + typed model module (the entity module).",
     tier: "native",
     factory: () => entityFile(),
     options: "filter?, target?",
+    requires: [],
+    runtimePackages: ["@metaobjectsdev/runtime-ts"],
+    runtimePeers: ["drizzle-orm", "zod"],
+    configKeys: ["dialect", "extStyle", "outputLayout", "columnNamingStrategy",
+      "pluralizeCollections", "collectionNameOverrides", "providedEnumModule", "apiPrefix"],
+    ejectable: ejectable("entity"),
+  },
+  names: {
+    name: "names",
+    kind: "generator",
+    layer: "model",
+    description: "Per-entity physical database name constants (table/view, schema, columns).",
+    tier: "native",
+    factory: () => namesFile(),
+    options: "filter?, target?",
+    configKeys: ["columnNamingStrategy"],
+    ejectable: ejectable("names"),
   },
+  barrel: {
+    name: "barrel",
+    kind: "generator",
+    layer: "model",
+    description: "Single index.ts re-exporting every generated entity module.",
+    tier: "native",
+    factory: () => barrel(),
+    options: "target?",
+    requires: ["entity"],
+    configKeys: ["extStyle"],
+    ejectable: ejectable("barrel"),
+  },
+
+  // ----- persistence ------------------------------------------------------
   queries: {
     name: "queries",
+    kind: "generator",
+    layer: "persistence",
     description: "Per-entity typed query helpers (findById/create/...).",
     tier: "native",
     factory: () => queriesFile(),
     options: "filter?, target?",
+    requires: ["entity"],
+    runtimePeers: ["drizzle-orm"],
+    configKeys: ["dialect", "extStyle", "pluralizeCollections", "collectionNameOverrides"],
+    ejectable: ejectable("queries"),
   },
-  callable: {
-    name: "callable",
-    description: "Per-entity callable/service surface wrapping the query helpers.",
-    tier: "native",
-    factory: () => callableFile(),
-    options: "filter?, target?",
-  },
+
+  // ----- api --------------------------------------------------------------
   routes: {
     name: "routes",
+    kind: "generator",
+    layer: "api",
     description: "Per-entity Fastify CRUD routes (drizzle-fastify mountCrudRoutes).",
     tier: "native",
     factory: () => routesFile(),
     options: "filter?, target?",
+    framework: "fastify",
+    requires: ["entity"],
+    runtimePackages: ["@metaobjectsdev/runtime-ts"],
+    runtimePeers: ["fastify"],
+    configKeys: ["dbImport", "apiPrefix", "dialect", "extStyle", "outputLayout", "columnNamingStrategy"],
+    ejectable: ejectable("routes"),
   },
   "routes-hono": {
     name: "routes-hono",
+    kind: "generator",
+    layer: "api",
     description: "Per-entity Hono CRUD routes (runtime-ts/hono mountCrudRoutes).",
     tier: "native",
     factory: () => routesFileHono(),
     options: "filter?, target?",
+    framework: "hono",
+    requires: ["entity"],
+    runtimePackages: ["@metaobjectsdev/runtime-ts"],
+    runtimePeers: ["hono"],
+    configKeys: ["dbImport", "apiPrefix", "dialect", "extStyle"],
+    ejectable: ejectable("routes-hono"),
   },
-  barrel: {
-    name: "barrel",
-    description: "Single index.ts re-exporting every generated entity module.",
+
+  // ----- docs -------------------------------------------------------------
+  "api-docs": {
+    name: "api-docs",
+    kind: "generator",
+    layer: "docs",
+    description:
+      "Per-entity/template SDK API reference (the generated code's API, human + agent forms).",
     tier: "native",
-    factory: () => barrel(),
-    options: "target?",
+    factory: () => apiDocsFile(),
+    options: "filter?, target?",
+    ejectable: ejectable("api-docs"),
   },
-  names: {
-    name: "names",
-    description: "Per-entity physical database name constants (table/view, schema, columns).",
+  docs: {
+    name: "docs",
+    kind: "generator",
+    layer: "docs",
+    description: "Neutral per-entity / per-template Markdown documentation pages.",
+    tier: "neutral",
+    factory: () => docsFile(),
+    ejectable: ejectable("docs"),
+    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",
+    kind: "generator",
+    layer: "docs",
+    description: "Mermaid ER diagram of the entity/relationship model.",
+    tier: "neutral",
+    factory: () => mermaidErDiagram(),
+    ejectable: ejectable("mermaid-er"),
+    note: "neutral artifact owned by the docs engine (ADR-0020); surfaced via `meta docs`, not the recommended `meta gen` native suite.",
+  },
+
+  // ----- capability -------------------------------------------------------
+  // Not chosen by browsing this list — chosen because the MODEL already asks for
+  // them. `meta gen --list --probe` reports a real file count per entry.
+  callable: {
+    name: "callable",
+    kind: "generator",
+    layer: "capability",
+    description: "Per-entity callable/service surface wrapping the query helpers.",
     tier: "native",
-    factory: () => namesFile(),
+    factory: () => callableFile(),
     options: "filter?, target?",
+    requires: ["entity"],
+    runtimePeers: ["drizzle-orm"],
+    configKeys: ["columnNamingStrategy"],
+    ejectable: ejectable("callable"),
   },
   "prompt-render": {
     name: "prompt-render",
+    kind: "generator",
+    layer: "capability",
     description: "Per-template prompt-render helper over the render engine.",
     tier: "native",
     factory: () => promptRender(),
     options: "filter?, target?",
+    runtimePackages: ["@metaobjectsdev/render"],
+    ejectable: ejectable("prompt-render"),
   },
   "output-parser": {
     name: "output-parser",
+    kind: "generator",
+    layer: "capability",
     description: "Per-template tolerant output parser (recover-on-receipt).",
     tier: "native",
     factory: () => outputParser(),
     options: "filter?, target?",
+    runtimePackages: ["@metaobjectsdev/metadata", "@metaobjectsdev/render", "@metaobjectsdev/runtime-ts"],
+    runtimePeers: ["zod"],
+    ejectable: ejectable("output-parser"),
   },
   extractor: {
     name: "extractor",
+    kind: "generator",
+    layer: "capability",
     description: "Per-template typed extract<Name> helper (strict payload extraction).",
     tier: "native",
     factory: () => extractor(),
     options: "filter?, target?",
+    requires: ["entity", "output-parser"],
+    runtimePackages: ["@metaobjectsdev/metadata", "@metaobjectsdev/render"],
+    ejectable: ejectable("extractor"),
   },
   "output-prompt": {
     name: "output-prompt",
+    kind: "generator",
+    layer: "capability",
     description: "Per-template output-format prompt fragment generator.",
     tier: "native",
     factory: () => outputPrompt(),
     options: "filter?, target?",
+    runtimePackages: ["@metaobjectsdev/render"],
+    ejectable: ejectable("output-prompt"),
   },
   "render-helper": {
     name: "render-helper",
+    kind: "generator",
+    layer: "capability",
     description: "Per-template.output render helper (document/email typed wrappers).",
     tier: "native",
     factory: () => renderHelper(),
     options: "filter?, target?",
+    runtimePackages: ["@metaobjectsdev/render"],
+    configKeys: ["extStyle"],
+    ejectable: ejectable("render-helper"),
   },
   template: {
     name: "template",
+    kind: "generator",
+    layer: "capability",
     description: "Generic Mustache template primitive (walk + template → files).",
     tier: "native",
     factory: () => templatePrimitive(),
     options: "name, walk, template, format?, filter?, provider?, target?",
+    ejectable: ejectable("template"),
   },
-  "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).",
+    kind: "generator",
+    layer: "capability",
+    description:
+      "Per-entity typed record<Entity>/call<Entity> trace helpers (extract + buildLlmCallRow + persist; LlmCallBase-derived entities only).",
     tier: "native",
     factory: () => traceHelperFile(),
     options: "outDir?, target?",
+    ejectable: ejectable("trace-helper"),
   },
-
-  // ----- 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.",
+  "requirement-tests": {
+    name: "requirement-tests",
+    kind: "generator",
+    layer: "capability",
+    description: "Per-requirement test stub, one per requirement.functional claim in the ledger.",
+    tier: "native",
+    factory: () => requirementTests(),
+    options: "filter?, target?",
+    ejectable: ejectable("requirement-tests"),
   },
-  "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.",
+  "shared-model": {
+    name: "shared-model",
+    kind: "generator",
+    layer: "capability",
+    description:
+      "FR-023: a publisher's flattened shared-model artifact + manifest for a consumer's `meta deps sync`.",
+    tier: "native",
+    // `name`/`include` are required at run time (an empty include matches
+    // everything, so a placeholder here constructs without throwing — real use
+    // always supplies both, same as `template`'s templatePrimitive() above).
+    factory: () => sharedModelFile({ name: "shared-model", include: [] }),
+    options: "name, include, exclude?, files?, version?, target?",
+    ejectable: ejectable("shared-model"),
   },
 };
 

package/src/generator.ts

@@ -1,4 +1,5 @@
-import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
+import type { MetaObject, MetaRoot, TypeRegistry } from "@metaobjectsdev/metadata";
+import type { LibraryManifest } from "@metaobjectsdev/metadata/library";
 import type { RenderContext } from "./render-context.js";
 import type { ResolvedGenConfig } from "./metaobjects-config.js";
 import type { OrphanPolicy } from "./reconcile-orphans.js";
@@ -20,6 +21,16 @@ export interface GenContext {
    *  filter is set). Always call this from helpers; do not call generator.filter
    *  directly. */
   matches: (entity: MetaObject) => boolean;
+  /** FR-023 §11.1 item 2 — the model-wide output-scope predicate over a node's
+   *  `resolutionKey()` (the runner's own `RunGenOpts.scope`, verbatim). A
+   *  DIFFERENT knob from `matches`: `matches` is the per-generator `filter`
+   *  (ANDed into what THIS generator emits), while `select` is the whole-model
+   *  scope every generator shares — for a template that renders once over
+   *  `ctx.loadedRoot` rather than per-entity (the shared-enums module is the
+   *  first such template), `matches` never runs at all, so that template must
+   *  read `select` directly to honour the same exclusion. Undefined ⇒ every
+   *  node is in scope, byte-identical to a project with no `scope` declared. */
+  select?: (fqn: string) => boolean;
   config: ResolvedGenConfig;
   /** Pre-built by the runner for built-in generators that wrap existing
    *  templates. Third-party generators typically don't need this. Always
@@ -35,6 +46,42 @@ export interface GenContext {
    *  in a sub-directory. Undefined only when the runner was driven
    *  programmatically without an explicit projectRoot. */
   projectRoot?: string;
+  /**
+   * FR-023 §4.3 — the run's composed registry (core providers plus whatever this
+   * project's `metaobjects.config.ts` `providers` adds), filled by the runner. The
+   * SAME vocabulary `opts.metadata` was loaded with. `sharedModelFile()`'s
+   * standalone re-loads of a `files` subset use this so a publisher project's own
+   * consumer-supplied vocabulary is honoured identically to the main load. Optional
+   * on the type so tests and custom callers don't need a placeholder; always
+   * present at run time when invoked via `runGen()`.
+   */
+  registry?: TypeRegistry;
+  /**
+   * FR-023 §4.3 — the collection's own source files (never a dependency's
+   * artifact), filled by the runner from `RunGenOpts.sourceFiles`. Distinct from
+   * `loadedRoot`, which is already fully loaded and merged: `sharedModelFile()`
+   * needs the raw file LIST so it can re-load a `files:`-narrowed subset of it
+   * standalone. Undefined when the caller never supplied `RunGenOpts.sourceFiles`
+   * (a generator relying on it should default sensibly, as `sharedModelFile()`'s
+   * own `files` option does).
+   */
+  sourceFiles?: readonly string[];
+  /**
+   * FR-043 §6 — the manifests of the libraries this project opted into, filled by the
+   * runner from `RunGenOpts.libraries`.
+   *
+   * What a generator reads it FOR is the `anchor`: the library node it keys on. That
+   * retires the hard-coded entity name a library-aware generator would otherwise carry
+   * (`trace-helper` compared `.name === "LlmCallBase"`, so ANY adopter entity of that
+   * name in ANY package triggered it) in favour of resolving the manifest's anchor to a
+   * node and comparing by node identity.
+   *
+   * Undefined means the caller never said — a programmatic `runGen()` rather than
+   * `meta gen`. A generator reading it should fall back to every SHIPPED manifest's
+   * anchors, which is still FQN-anchored and still not a bare name. An empty array is
+   * the opposite and is meaningful: the caller looked, and this project opted into none.
+   */
+  libraries?: readonly LibraryManifest[];
   warn: (msg: string) => void;
 }
 

package/src/generators/entity-file.ts

@@ -59,7 +59,13 @@ export const entityFile = function entityFile(opts?: EntityFileOpts): Generator
       // FR-019: emit the shared-enums module ONCE per run, into the entity-module
       // target root. Returns null (no file) when the model uses no materialized
       // shared enums — keeping the inline-enum default byte-identical (no new file).
-      const sharedEnums = renderSharedEnumsFile(ctx.loadedRoot);
+      // FR-023 §11.1 item 2: `select` (never `ctx.matches` — this renders from the
+      // WHOLE root, not this generator's filtered subset) excludes an enum used
+      // only by an imported, out-of-scope entity.
+      const sharedEnums = renderSharedEnumsFile(
+        ctx.loadedRoot,
+        ctx.select !== undefined ? { select: ctx.select } : undefined,
+      );
       if (sharedEnums !== null) {
         files.push({
           path: `${SHARED_ENUMS_BASENAME}.ts`,

package/src/generators/index.ts

@@ -35,6 +35,17 @@ export {
   type TemplateFormat,
 } from "./template-generator.js";
 export { traceHelperFile, type TraceHelperOpts } from "./trace-helper-file.js";
+// FR-023 §4.3 — the publisher's flattened shared-model artifact + manifest generator.
+// The three tool-file constants are re-exported alongside it purely so a `cli`
+// test can assert they stay byte-equal to sdk's canonical copies (see that
+// module's own comment for why codegen-ts can't just import sdk directly).
+export {
+  sharedModelFile,
+  type SharedModelFileOpts,
+  MANIFEST_FILE as SHARED_MODEL_MANIFEST_FILE,
+  ARTIFACT_SUFFIX as SHARED_MODEL_ARTIFACT_SUFFIX,
+  INTEGRITY_PREFIX as SHARED_MODEL_INTEGRITY_PREFIX,
+} from "./shared-model-file.js";
 export type {
   EntityDocData,
   StorageFieldDoc,