@metaobjectsdev/codegen-ts 0.9.0-rc.1 → 0.10.0

package/dist/generator-registry.js

@@ -0,0 +1,161 @@
+// 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 { entityFile, queriesFile, callableFile, routesFile, routesFileHono, barrel, mermaidErDiagram, promptRender, outputParser, extractor, outputPrompt, renderHelper, apiDocsFile, docsFile, templateGenerator, traceHelperFile, } from "./generators/index.js";
+// 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() {
+    return templateGenerator({
+        name: "template",
+        template: "",
+        walk: () => [],
+    });
+}
+export const generatorRegistry = {
+    // ----- 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() {
+    const entries = Object.values(generatorRegistry);
+    const byName = (a, b) => 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) {
+    return generatorRegistry[id];
+}
+//# sourceMappingURL=generator-registry.js.map

package/dist/generator-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator-registry.js","sourceRoot":"","sources":["../src/generator-registry.ts"],"names":[],"mappings":"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"}

package/dist/generator.d.ts

@@ -44,6 +44,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 ? () => Generator : (opts?: TOpts) => Generator;
 /** One-file-per-entity convenience. Async-safe. */

package/dist/generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,UAAU,EAAE,QAAQ,CAAC;IACrB;;oBAEgB;IAChB,OAAO,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;gEAG4D;IAC5D,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;;4DAOwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACxB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,QAAQ,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,WAAW,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACtE,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;iFAC6E;IAC7E,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,gBAAgB,CAAC,KAAK,GAAG,IAAI,IAAI,KAAK,SAAS,IAAI,GAC3D,MAAM,SAAS,GACf,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,SAAS,CAAC;AAEhC,mDAAmD;AACnD,wBAAgB,SAAS,CACvB,EAAE,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,KACpC,WAAW,GACX,WAAW,EAAE,GACb,OAAO,CAAC,WAAW,GAAG,WAAW,EAAE,CAAC,GACvC,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAM7C;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CACxB,EAAE,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,UAAU,KACxC,WAAW,GACX,WAAW,EAAE,GACb,OAAO,CAAC,WAAW,GAAG,WAAW,EAAE,CAAC,GACvC,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAM7C"}
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,UAAU,EAAE,QAAQ,CAAC;IACrB;;oBAEgB;IAChB,OAAO,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;gEAG4D;IAC5D,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;;4DAOwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACxB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,QAAQ,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,WAAW,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACtE,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;iFAC6E;IAC7E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;oFAIgF;IAChF,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,MAAM,gBAAgB,CAAC,KAAK,GAAG,IAAI,IAAI,KAAK,SAAS,IAAI,GAC3D,MAAM,SAAS,GACf,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,SAAS,CAAC;AAEhC,mDAAmD;AACnD,wBAAgB,SAAS,CACvB,EAAE,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,KACpC,WAAW,GACX,WAAW,EAAE,GACb,OAAO,CAAC,WAAW,GAAG,WAAW,EAAE,CAAC,GACvC,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAM7C;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CACxB,EAAE,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,UAAU,KACxC,WAAW,GACX,WAAW,EAAE,GACb,OAAO,CAAC,WAAW,GAAG,WAAW,EAAE,CAAC,GACvC,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAM7C"}

package/dist/generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"generator.js","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAuDA,mDAAmD;AACnD,MAAM,UAAU,SAAS,CACvB,EAGwC;IAExC,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE;QACnB,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QAClE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,UAAU,CACxB,EAGwC;IAExC,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE;QACnB,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACtC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AA6DA,mDAAmD;AACnD,MAAM,UAAU,SAAS,CACvB,EAGwC;IAExC,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE;QACnB,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QAClE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,UAAU,CACxB,EAGwC;IAExC,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE;QACnB,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACtC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC,CAAC;AACJ,CAAC"}

package/dist/generators/api-doc-render.d.ts

@@ -0,0 +1,17 @@
+import type { Provider } from "@metaobjectsdev/render";
+import type { ApiModel, ApiUnitDoc } from "./api-model.js";
+import type { OutputLayout } from "../import-path.js";
+/** Render ONE per-unit human reference page from an ApiUnitDoc, via the shared
+ *  render() engine + the canonical `api/entity-api.md` template. `modelPageHref`
+ *  (when given) cross-links the page back to the entity's model/metadata page. */
+export declare function renderEntityApiPage(unit: ApiUnitDoc, provider: Provider, modelPageHref?: string): string;
+/** Render the consolidated human API index (links to each unit page, grouped
+ *  entity vs template) via the shared render() engine + `api/index.md`. */
+export declare function renderApiIndex(model: ApiModel, layout: OutputLayout, provider: Provider): string;
+/** Render the condensed agent/LLM form: per unit, symbols grouped under a single
+ *  `import { … } from "<module>"` header then one compact `signature — usage`
+ *  line each (with a `[throws: …]` marker when it throws), NO prose/examples
+ *  (token budget). Units keep their ApiModel order; symbols keep their per-unit
+ *  order (the canonical generator emission order). */
+export declare function renderAgentApi(model: ApiModel, provider: Provider): string;
+//# sourceMappingURL=api-doc-render.d.ts.map

package/dist/generators/api-doc-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-doc-render.d.ts","sourceRoot":"","sources":["../../src/generators/api-doc-render.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAyC,MAAM,gBAAgB,CAAC;AAGlG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AA8StD;;kFAEkF;AAClF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,QAAQ,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CASR;AAyDD;2EAC2E;AAC3E,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAehG;AA+GD;;;;sDAIsD;AACtD,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CA8B1E"}

package/dist/generators/api-doc-render.js

@@ -0,0 +1,431 @@
+// api-doc-render.ts — the two documentation FORMS that an ApiModel feeds:
+//   • a per-unit HUMAN reference page  (renderEntityApiPage)
+//   • a consolidated HUMAN index       (renderApiIndex)
+//   • a condensed AGENT/LLM form        (renderAgentApi)
+//
+// ADR-0022 Part 3: one ApiModel, two forms — the human prose page and the
+// token-frugal agent form derive from the SAME IR, never re-derived. Rendering
+// goes through the SHARED `render()` Mustache engine against canonical templates
+// under `templates/api/` (resolved via the framework/project provider chain —
+// the same mechanism docs-file.ts uses), so adopters can override a template by
+// dropping their own `templates/api/<ref>.mustache` into their project root.
+//
+// The view-models are pre-rendered here (mirroring docs-data-builder) so the
+// Mustache templates stay logic-light: section grouping, symbol counts, and the
+// collision-safe index hrefs (docPageHref) are computed in TS.
+import { render } from "@metaobjectsdev/render";
+import { inlineShape } from "./api-field-shape.js";
+import { docPageHref } from "../docs-paths.js";
+import { GENERATED_HEADER } from "../constants.js";
+// Template refs (resolved as `templates/api/<ref-tail>.mustache`).
+const ENTITY_PAGE_REF = "api/entity-api.md";
+const INDEX_REF = "api/index.md";
+const AGENT_REF = "api/agent-api.md";
+const GENERATED_MARKER = `<!-- ${GENERATED_HEADER} — DO NOT EDIT. -->`;
+// ---------------------------------------------------------------------------
+// Relative-import RENDER prefix.
+//
+// An `ApiSymbol.importPath` is the generated module's path RELATIVE TO the
+// codegen output dir (flat → `Product.queries`; package → the package-folded
+// `acme/shop/Product.queries`). It is the DATA the accuracy gate verifies
+// against the emitted file, so it stays a bare module path.
+//
+// The generated files import each OTHER with `./`-prefixed RELATIVE specifiers
+// (`from "./Product"`), so a copy-paste consumer co-located in the generated
+// output dir must do the same — a BARE specifier (`from "Product.queries"`)
+// only resolves with a non-default `baseUrl` and otherwise fails TS2307. The
+// renderers therefore `./`-prefix the importPath in every rendered `from "…"`
+// (the human page, the agent group headers, AND the example import blocks),
+// without touching the underlying importPath data. A consumer importing from
+// elsewhere adjusts the prefix (stated once in the page's import note).
+// ---------------------------------------------------------------------------
+/** The `./`-prefixed RELATIVE specifier for a documented module path (the form a
+ *  co-located consumer copy-pastes). Already-relative paths pass through. */
+function relSpecifier(importPath) {
+    return importPath.startsWith("./") || importPath.startsWith("../")
+        ? importPath
+        : `./${importPath}`;
+}
+/** Rewrite the `from "<module>"` tail of an example `import { … } from "<module>";`
+ *  line to the `./`-prefixed relative specifier — the example imports are
+ *  pre-composed in the ApiModel (reusing each symbol's bare importPath), so the
+ *  `./` prefix is applied at render time alongside the section/header imports. */
+function relImportLine(line) {
+    return line.replace(/(\bfrom\s+")([^"]+)(")/, (_m, pre, mod, post) => `${pre}${relSpecifier(mod)}${post}`);
+}
+// The human-facing section ORDER + HEADING per ApiSymbolKind. A unit's page
+// renders only the kinds it actually carries, always in this canonical order
+// (so two runs over the same model are byte-stable regardless of symbol order).
+const KIND_ORDER = [
+    "model",
+    "relation",
+    "data-access",
+    "callable",
+    "rest",
+    "rest-hono",
+    "validation",
+    "extractor",
+    "render",
+    "prompt",
+];
+const KIND_HEADING = {
+    model: "Model",
+    relation: "Relations",
+    "data-access": "Data access",
+    callable: "Callable",
+    rest: "REST",
+    "rest-hono": "REST (Hono)",
+    validation: "Validation",
+    extractor: "Extractor",
+    render: "Render",
+    prompt: "Prompt",
+};
+/** A docs-page name for the index href helper. The API index lives at the docs
+ *  ROOT, so its links to per-unit pages are computed via the same docPageHref
+ *  used elsewhere (resolves in flat AND package layout). */
+const INDEX_NODE = { name: "index" };
+/** The full set of handles a unit's example may reference. The per-unit page
+ *  shows only the handles that unit's example actually uses; the agent + index
+ *  forms show the full set once. */
+/** Build a setup row, deriving the single-line agent snippet from the block one
+ *  (newlines → `; `, collapsing any blank lines / double semicolons). */
+function setupHandle(handle, note, snippet) {
+    const snippetInline = snippet
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .map((l) => (l.endsWith(";") ? l.slice(0, -1) : l))
+        .join("; ");
+    return { handle, note, snippet, snippetInline };
+}
+const SETUP_HANDLES = {
+    db: setupHandle("db", "your Drizzle connection — the generated queries take `db: Db` (a `NodePgDatabase` / `BaseSQLiteDatabase` alias). Construct one over your own driver and pass any compatible Drizzle instance:", `import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+const db = drizzle(new Pool({ connectionString: process.env.DATABASE_URL }));`),
+    provider: setupHandle("provider", "the render `Provider` (resolves a template ref to text) — import it from `@metaobjectsdev/render`; `InMemoryProvider` is built in (or supply your own filesystem-backed `Provider`):", `import { InMemoryProvider } from "@metaobjectsdev/render";
+const provider = new InMemoryProvider({ "group/source": "Hello {{name}}" });`),
+    root: setupHandle("root", "the loaded `MetaRoot` `extract<Name>` parses against — load your metadata via `@metaobjectsdev/metadata` (the result carries `.root`):", `import { loadDirectory } from "@metaobjectsdev/metadata";
+const { root } = await loadDirectory("./metadata");`),
+};
+/** Which handles a unit's example references (so the page shows only those). */
+function setupHandlesFor(unit) {
+    const text = unit.example ? unit.example.body.join("\n") : "";
+    const out = [];
+    if (/\bdb\b/.test(text))
+        out.push(SETUP_HANDLES.db);
+    if (/\bprovider\b/.test(text))
+        out.push(SETUP_HANDLES.provider);
+    if (/\broot\b/.test(text))
+        out.push(SETUP_HANDLES.root);
+    return out;
+}
+/** A human-page caption for a symbol's field table, by kind + signature shape. */
+function fieldsCaptionFor(s) {
+    if (s.kind === "model")
+        return "Fields";
+    if (s.kind === "validation")
+        return "Accepted fields";
+    if (s.kind === "prompt")
+        return "Payload";
+    if (s.kind === "extractor")
+        return "Returns";
+    if (s.kind === "relation")
+        return "Navigations";
+    if (s.kind === "callable")
+        return "Returns";
+    if (s.kind === "rest" || s.kind === "rest-hono") {
+        return s.name.startsWith("GET ") ? "Response body" : "Request body";
+    }
+    // data-access: a create/update takes a body; reads return the model.
+    return s.name.startsWith("create") || s.name.startsWith("update") ? "Request body (data)" : "Returns";
+}
+/** Markdown-escape a cell whose text may contain a `|` (TS union types do). */
+function mdCell(text) {
+    return text.replace(/\|/g, "\\|");
+}
+/** Build the Field / Type / Required / Notes rows from a field shape. */
+function fieldRows(fields) {
+    return fields.map((f) => ({
+        field: f.name,
+        type: mdCell(f.type),
+        required: f.optional ? "" : "yes",
+        notes: f.note ?? "",
+    }));
+}
+/** The exact `import { … } from "<importPath>"` an adopter writes for a symbol.
+ *  REST endpoints aren't importable functions — the import is the entity's route
+ *  registrar (`<entity>Routes`) from the routes module; the symbol's `name` is a
+ *  "METHOD /path", not an identifier, so we import the registrar instead. Import
+ *  paths are RELATIVE to the adopter's generated-output dir (a note at the top of
+ *  the page states this once). */
+function importLineFor(s) {
+    // REST + Hono endpoints aren't importable functions — import the route
+    // registrar named on the symbol instead of the "METHOD /path" name.
+    const isRouteKind = s.kind === "rest" || s.kind === "rest-hono";
+    const imported = isRouteKind ? s.registrar ?? s.name : s.name;
+    return `import { ${imported} } from "${relSpecifier(s.importPath)}"`;
+}
+/** Group a unit's symbols into ordered sections (one per present kind), each a
+ *  list of {signature, usage, import, throws, example}. Empty kinds are omitted. */
+function entityPageVM(unit) {
+    const sections = [];
+    for (const kind of KIND_ORDER) {
+        const ofKind = unit.symbols.filter((s) => s.kind === kind);
+        if (ofKind.length === 0)
+            continue;
+        sections.push({
+            heading: KIND_HEADING[kind],
+            symbols: ofKind.map(symbolVM),
+        });
+    }
+    const setup = setupHandlesFor(unit);
+    const vm = {
+        generatedMarker: GENERATED_MARKER,
+        node: unit.node,
+        hasSetup: setup.length > 0,
+        setup,
+        sections,
+    };
+    const ex = unitExampleBlock(unit.example);
+    if (ex !== undefined)
+        vm.unitExample = ex;
+    return vm;
+}
+/** The full worked-example block for a unit (imports + body), as one ```ts body
+ *  string. Undefined when the unit has no runnable example. */
+function unitExampleBlock(example) {
+    if (example === undefined)
+        return undefined;
+    // The example imports are pre-composed in the ApiModel from the symbols' bare
+    // importPaths; `./`-prefix each at render time so the copy-paste block resolves.
+    const lines = example.imports.map(relImportLine);
+    if (example.imports.length > 0 && example.body.length > 0)
+        lines.push("");
+    lines.push(...example.body);
+    return lines.join("\n");
+}
+function symbolVM(s) {
+    const vm = { signature: s.signature, usage: s.usage, importLine: importLineFor(s) };
+    // REST: tell the agent how to actually wire the endpoints once imported.
+    if (s.kind === "rest" && s.registrar !== undefined) {
+        vm.mountNote = `\`await ${s.registrar}(fastify)\``;
+    }
+    // Hono: the registrar mounts onto the Hono app with a per-request deps object.
+    if (s.kind === "rest-hono" && s.registrar !== undefined) {
+        vm.mountNote = `\`${s.registrar}(app, { db })\``;
+    }
+    if (s.throws !== undefined)
+        vm.throws = s.throws;
+    if (s.example !== undefined)
+        vm.example = s.example;
+    // Field shape → a Field / Type / Required / Notes table (only when there is at
+    // least one field; a shape with no fields is omitted to keep the page clean).
+    if (s.fields !== undefined && s.fields.length > 0) {
+        vm.hasFields = true;
+        vm.fieldsCaption = fieldsCaptionFor(s);
+        vm.fieldRows = fieldRows(s.fields);
+    }
+    return vm;
+}
+/** Render ONE per-unit human reference page from an ApiUnitDoc, via the shared
+ *  render() engine + the canonical `api/entity-api.md` template. `modelPageHref`
+ *  (when given) cross-links the page back to the entity's model/metadata page. */
+export function renderEntityApiPage(unit, provider, modelPageHref) {
+    const payload = entityPageVM(unit);
+    if (modelPageHref !== undefined)
+        payload.modelPageHref = modelPageHref;
+    return render({
+        ref: ENTITY_PAGE_REF,
+        payload,
+        provider,
+        format: "markdown",
+    });
+}
+/** Lowercase summary label per kind (keeps the proper-noun acronym "REST"
+ *  intact rather than ".toLowerCase()"-ing it to "rest"). */
+const KIND_SUMMARY_LABEL = {
+    model: "model",
+    relation: "relations",
+    "data-access": "data access",
+    callable: "callable",
+    rest: "REST",
+    "rest-hono": "REST (Hono)",
+    validation: "validation",
+    extractor: "extractor",
+    render: "render",
+    prompt: "prompt",
+};
+/** A one-line summary for a unit's index row: the count of each present kind,
+ *  in canonical order (e.g. "model, 5 data access, 5 REST, 2 validation"). */
+function unitSummary(unit) {
+    const parts = [];
+    for (const kind of KIND_ORDER) {
+        const n = unit.symbols.filter((s) => s.kind === kind).length;
+        if (n === 0)
+            continue;
+        const label = KIND_SUMMARY_LABEL[kind];
+        parts.push(n === 1 ? label : `${n} ${label}`);
+    }
+    return parts.length > 0 ? parts.join(", ") : "no public symbols";
+}
+function indexRow(layout, unit) {
+    // The per-unit page is placed by {name, effective package} (see Task-3
+    // emission); link to it via the same docPageHref used for doc pages so it
+    // resolves in BOTH layouts — flat (`./Product.md`) and package
+    // (`./acme/shop/Product.md`), folding under the package path.
+    const href = docPageHref(layout, INDEX_NODE, { name: unit.node, package: unit.package });
+    return {
+        node: unit.node,
+        href,
+        summary: unitSummary(unit),
+        symbolCount: unit.symbols.length,
+        one: unit.symbols.length === 1,
+    };
+}
+/** Render the consolidated human API index (links to each unit page, grouped
+ *  entity vs template) via the shared render() engine + `api/index.md`. */
+export function renderApiIndex(model, layout, provider) {
+    const byName = (a, b) => a.node.localeCompare(b.node);
+    const entities = model.units.filter((u) => u.nodeKind === "entity").sort(byName);
+    const templates = model.units.filter((u) => u.nodeKind === "template").sort(byName);
+    const payload = {
+        generatedMarker: GENERATED_MARKER,
+        title: "API Reference",
+        intro: "Generated public API surface, one page per entity and output template.",
+        hasEntities: entities.length > 0,
+        entities: entities.map((u) => indexRow(layout, u)),
+        hasTemplates: templates.length > 0,
+        templates: templates.map((u) => indexRow(layout, u)),
+    };
+    return render({ ref: INDEX_REF, payload, provider, format: "markdown" });
+}
+/**
+ * The agent-form signature WITH the field shape inlined — so an LLM sees exactly
+ * what to pass / what it gets, not an opaque `unknown` / `ZodType` / type NAME.
+ * Token-frugal but complete. Shaping is per kind:
+ *   • model            → `interface <Name> <inlineShape>`;
+ *   • data-access      → swap the `data: unknown` param for `data: <inlineShape>`
+ *                        (create/update only; reads have no body shape);
+ *   • validation       → `<Name>InsertSchema: ZodType<<inlineShape>>`;
+ *   • REST             → append ` body: <inlineShape>` (write) / ` -> <inlineShape>`
+ *                        (GET response);
+ *   • extractor        → append ` // <Payload>: <inlineShape>`.
+ * Falls back to the bare signature when the symbol carries no field shape.
+ */
+function agentSignature(s) {
+    if (s.fields === undefined || s.fields.length === 0)
+        return s.signature;
+    const shape = inlineShape(s.fields);
+    switch (s.kind) {
+        case "model":
+            return `interface ${s.name} ${shape}`;
+        case "data-access":
+            // create/update carry a `data: unknown` body param to specialize.
+            return s.signature.includes("data: unknown")
+                ? s.signature.replace("data: unknown", `data: ${shape}`)
+                : s.signature;
+        case "validation":
+            return s.signature.replace("ZodType", `ZodType<${shape}>`);
+        case "rest":
+        case "rest-hono":
+            return s.name.startsWith("GET ") ? `${s.signature} -> ${shape}` : `${s.signature} body: ${shape}`;
+        case "extractor":
+        case "prompt":
+            return `${s.signature} // ${s.returns ?? "payload"}: ${shape}`;
+        case "relation":
+            // The navigations ride in the shape; show them inline after the const decl.
+            return `const ${s.name} ${shape}`;
+        case "callable":
+            // Callable returns a typed row array; the model shape isn't its param, so
+            // keep the bare signature (its `args` shape is the @parameterRef VO, shown
+            // on that VO's own unit).
+            return s.signature;
+        default:
+            return s.signature;
+    }
+}
+/** Group a unit's symbols by their import MODULE (first-appearance order),
+ *  emitting ONE `import { … } from "<module>"` header per module then the
+ *  symbols under it. This is the token-frugal form that still tells the agent the
+ *  exact import for EVERY symbol (one header amortized over N symbols, vs. an
+ *  import line per symbol). REST endpoints aren't importable identifiers — they
+ *  collapse under their entity's single route-registrar import (the registrar is
+ *  the imported name; the endpoints list the verbs/paths it mounts). */
+function agentGroups(unit) {
+    const order = [];
+    const byModule = new Map();
+    for (const s of unit.symbols) {
+        let g = byModule.get(s.importPath);
+        if (!g) {
+            g = { names: [], symbols: [] };
+            byModule.set(s.importPath, g);
+            order.push(s.importPath);
+        }
+        // The identifier an adopter imports: the symbol name, or — for REST / Hono —
+        // the shared route registrar (deduped across the entity's endpoints).
+        const isRouteKind = s.kind === "rest" || s.kind === "rest-hono";
+        const imported = isRouteKind ? s.registrar ?? s.name : s.name;
+        if (!g.names.includes(imported))
+            g.names.push(imported);
+        const sym = { signature: agentSignature(s), usage: s.usage };
+        if (s.throws !== undefined)
+            sym.throwsMarker = `[throws: ${s.throws}]`;
+        g.symbols.push(sym);
+    }
+    return order.map((mod) => {
+        const g = byModule.get(mod);
+        return {
+            importHeader: `import { ${g.names.join(", ")} } from "${relSpecifier(mod)}"`,
+            symbols: g.symbols,
+        };
+    });
+}
+/** Render the condensed agent/LLM form: per unit, symbols grouped under a single
+ *  `import { … } from "<module>"` header then one compact `signature — usage`
+ *  line each (with a `[throws: …]` marker when it throws), NO prose/examples
+ *  (token budget). Units keep their ApiModel order; symbols keep their per-unit
+ *  order (the canonical generator emission order). */
+export function renderAgentApi(model, provider) {
+    const units = model.units
+        .filter((u) => u.symbols.length > 0)
+        .map((u) => {
+        const vm = { node: u.node, groups: agentGroups(u) };
+        // The compact agent example: body statements only (the imports are already
+        // amortized into the group headers above the example).
+        if (u.example !== undefined && u.example.body.length > 0) {
+            vm.example = u.example.body.join("\n");
+        }
+        return vm;
+    });
+    // The handles ANY unit's example references — shown once at the top so an agent
+    // knows where db / provider / root come from before the call sites below.
+    const setup = setupHandlesForModel(model);
+    const payload = {
+        generatedMarker: GENERATED_MARKER,
+        title: "Agent API Reference",
+        // The ApiModel carries no package itself, so the model-only entry point uses
+        // a generic, self-contained project label. (A richer label off the loaded
+        // root's package can be layered in by the Task-3 emission entrypoint, which
+        // has the root.)
+        project: "this project",
+        // Import paths are RELATIVE to the adopter's generated-output dir.
+        importNote: "Imports are relative to your generated-output directory.",
+        hasSetup: setup.length > 0,
+        setup,
+        units,
+    };
+    return render({ ref: AGENT_REF, payload, provider, format: "markdown" });
+}
+/** The union of setup handles referenced by ANY unit's example, in canonical
+ *  db→provider→root order (shown once at the top of the agent form). */
+function setupHandlesForModel(model) {
+    const used = new Set();
+    for (const u of model.units) {
+        for (const h of setupHandlesFor(u))
+            used.add(h.handle);
+    }
+    return ["db", "provider", "root"]
+        .filter((h) => used.has(h))
+        .map((h) => SETUP_HANDLES[h]);
+}
+//# sourceMappingURL=api-doc-render.js.map