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

package/dist/generators/api-field-shape.js

@@ -0,0 +1,92 @@
+// api-field-shape.ts — the field SHAPES (name + TS type + optionality) the
+// api-docs renderers attach to a unit's model / create-payload / update-payload /
+// extractor-payload symbols. ACCURATE BY CONSTRUCTION: every shape REUSES the
+// real generators' own field walks so the documented fields can never drift from
+// the emitted code (the api-docs accuracy gate enforces the field-set match):
+//
+//   • model fields      → entity-file's inferred type. The TS type comes from
+//     `fieldTsTypeString` (the SINGLE source of truth the value-object interface
+//     emitter uses) and the optional/nullable rule from `isFieldRequired` (the
+//     SAME rule the docs Storage/Constraints nullable column uses).
+//   • create-payload     → `insertSchemaFields` (the EXACT field set + optionality
+//     the zod InsertSchema emitter walks: auto-gen PK omitted, @readOnly omitted,
+//     TPH discriminator pinned, @autoSet optional, else `fieldWillBeOptional`).
+//   • update-payload     → `updateSchemaFields` (the UpdateSchema walk: TPH
+//     discriminator + @autoSet-onCreate omitted, everything else optional).
+//   • extractor-payload  → the referenced @payloadRef value-object's field
+//     interface — the type `extract<Name>` returns — via the SAME
+//     `fieldTsTypeString` mapping the VO interface emitter uses.
+import { fieldTsTypeString } from "../templates/inferred-types.js";
+import { insertSchemaFields, updateSchemaFields, } from "../templates/zod-validators.js";
+import { isFieldRequired } from "./docs-data-builder.js";
+/**
+ * The entity MODEL field shape — every field, with the value-object interface's
+ * TS type and the docs nullable rule (optional iff not required and not the PK).
+ * Mirrors `InferSelectModel` field-presence; the PK is reported required.
+ */
+export function modelFieldShapes(obj) {
+    const pkNames = new Set(obj.primaryIdentity()?.fields ?? []);
+    return obj.fields().map((field) => {
+        const isPk = pkNames.has(field.name);
+        const required = isPk || isFieldRequired(field);
+        return {
+            name: field.name,
+            type: fieldTsTypeString(obj.name, field),
+            optional: !required,
+        };
+    });
+}
+/** Resolve a schema-field walk (insert/update) into a documented shape by
+ *  pairing each schema field with its TS type (same `fieldTsTypeString` map). A
+ *  TPH-pinned discriminator field documents the literal as its type. */
+function shapesFromSchemaFields(obj, walk) {
+    const fieldByName = new Map(obj.fields().map((f) => [f.name, f]));
+    return walk.map((sf) => {
+        const field = fieldByName.get(sf.name);
+        let type = field !== undefined ? fieldTsTypeString(obj.name, field) : "unknown";
+        let note;
+        if (sf.pinnedLiteral !== undefined) {
+            type = JSON.stringify(sf.pinnedLiteral);
+            note = `pinned ${type}`;
+        }
+        else if (sf.autoSet === true) {
+            note = "server-set";
+        }
+        const shape = { name: sf.name, type, optional: sf.optional };
+        if (note !== undefined)
+            shape.note = note;
+        return shape;
+    });
+}
+/** The create-payload (InsertSchema) field shape — what `create<Name>` / POST
+ *  accepts. */
+export function createFieldShapes(obj) {
+    return shapesFromSchemaFields(obj, insertSchemaFields(obj));
+}
+/** The update-payload (UpdateSchema) field shape — what `update<Name>` / PATCH
+ *  accepts (typically all-optional partial). */
+export function updateFieldShapes(obj) {
+    return shapesFromSchemaFields(obj, updateSchemaFields(obj));
+}
+/**
+ * The extractor PAYLOAD field shape — the field interface of the value object
+ * `extract<Name>` returns (the `@payloadRef` target). Same `fieldTsTypeString`
+ * mapping + `isFieldRequired` optionality the VO interface emitter uses, so it
+ * matches the emitted payload type. Returns undefined when the ref does not
+ * resolve to a loaded object.
+ */
+export function payloadFieldShapes(root, payloadRef) {
+    const vo = root.findObject(payloadRef);
+    if (vo === undefined)
+        return undefined;
+    return modelFieldShapes(vo);
+}
+/** Format a list of field shapes as a compact inline TS object type, e.g.
+ *  `{ name: string; status?: "active" | "archived" }`. Empty list → `{}`. */
+export function inlineShape(fields) {
+    if (fields.length === 0)
+        return "{}";
+    const parts = fields.map((f) => `${f.name}${f.optional ? "?" : ""}: ${f.type}`);
+    return `{ ${parts.join("; ")} }`;
+}
+//# sourceMappingURL=api-field-shape.js.map

package/dist/generators/api-field-shape.js.map

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

package/dist/generators/api-label.d.ts

@@ -0,0 +1,3 @@
+/** Human label for an api-surface language key. Unknown → capitalized verbatim. */
+export declare function apiLabel(lang: string): string;
+//# sourceMappingURL=api-label.d.ts.map

package/dist/generators/api-label.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-label.d.ts","sourceRoot":"","sources":["../../src/generators/api-label.ts"],"names":[],"mappings":"AAGA,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C"}

package/dist/generators/api-label.js

@@ -0,0 +1,8 @@
+const LABELS = {
+    ts: "TypeScript", java: "Java", kotlin: "Kotlin", csharp: "C#", python: "Python",
+};
+/** Human label for an api-surface language key. Unknown → capitalized verbatim. */
+export function apiLabel(lang) {
+    return LABELS[lang] ?? (lang.length ? lang[0].toUpperCase() + lang.slice(1) : lang);
+}
+//# sourceMappingURL=api-label.js.map

package/dist/generators/api-label.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-label.js","sourceRoot":"","sources":["../../src/generators/api-label.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAA2B;IACrC,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ;CACjF,CAAC;AACF,mFAAmF;AACnF,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACvF,CAAC"}

package/dist/generators/api-model.d.ts

@@ -0,0 +1,122 @@
+import { type MetaRoot } from "@metaobjectsdev/metadata";
+import { type RelationMap } from "../relation-resolver.js";
+import { type OutputLayout } from "../import-path.js";
+import type { PkInfo } from "../pk-resolver.js";
+import { type FieldShape } from "./api-field-shape.js";
+export type ApiSymbolKind = "model" | "data-access" | "rest" | "validation" | "extractor" | "render" | "relation" | "callable" | "rest-hono" | "prompt";
+export interface ApiSymbol {
+    /** The exact symbol the real generator emits (function/type/schema name, or
+     *  a "METHOD /path" for a REST endpoint). Never invented. */
+    name: string;
+    kind: ApiSymbolKind;
+    /**
+     * The module specifier an adopter imports this symbol from — the generated
+     * file's path WITHOUT the `.ts` extension, exactly as the EMITTING generator
+     * writes it (so it can't drift): e.g. `Product.queries`, `Product`,
+     * `ProductSummary.extractor`, `ProductSummary.render`. Package layout folds
+     * entity-derived modules under the package path (`acme/shop/Product.queries`)
+     * iff the emitting generator does (it keys off the entity's OWN package).
+     *
+     * REST symbols are NOT importable functions — their importPath is the entity's
+     * routes MODULE; `registrar` carries the camelCase `<entity>Routes` handler an
+     * adopter mounts (`await <registrar>(fastify)`) to wire the endpoints.
+     */
+    importPath: string;
+    /** REST-only: the route-registrar function exported from `importPath` that an
+     *  adopter mounts to wire the endpoints (`<entity>Routes`). Undefined for
+     *  importable-symbol kinds (their `name` IS the import). */
+    registrar?: string;
+    /** A human-readable one-line signature (composed; the param/return SHAPE
+     *  mirrors the generated code). For REST symbols this is "METHOD /path". */
+    signature: string;
+    /** Parameter descriptions, when meaningful. */
+    params?: string[];
+    /** Return-type description (e.g. "Product | null", "string", "EmailDocument"). */
+    returns?: string;
+    /** When/why the symbol throws, if it does. */
+    throws?: string;
+    /** One-line "what you use this for" prose. */
+    usage: string;
+    /** Optional usage example snippet. */
+    example?: string;
+    /**
+     * The field SHAPE this symbol's payload carries — name + TS type + optionality
+     * per field — so both renderers (human field table + agent inline shape) can
+     * show WHAT fields to pass, not just the type NAME. Accurate by construction:
+     * derived by REUSING the real generators' field walks (api-field-shape.ts), so
+     * the api-docs accuracy gate can assert the documented field set == the emitted
+     * one. Attached to:
+     *   • model            → the entity's inferred fields (model line / GET response);
+     *   • create payload    → the InsertSchema field set (create<Name> / POST body);
+     *   • update payload    → the UpdateSchema field set (update<Name> / PATCH body);
+     *   • extractor payload → the @payloadRef VO interface (extract<Name>'s return).
+     * Undefined for symbols with no documented payload shape (e.g. deleteById, list).
+     */
+    fields?: FieldShape[];
+}
+export interface ApiUnitDoc {
+    /** The metadata node name (entity or template). */
+    node: string;
+    /** The node's EFFECTIVE package (own package OR the file-default captured at
+     *  parse time), used to place the unit's doc page + compute collision-safe
+     *  links to it in package layout. Undefined for a package-less node. */
+    package?: string | undefined;
+    nodeKind: "entity" | "template";
+    symbols: ApiSymbol[];
+    /**
+     * ONE worked, runnable example per unit — a concrete call site an agent (or a
+     * human) can copy. ACCURATE BY CONSTRUCTION: it is composed from the SAME
+     * symbol NAMES + importPaths this builder already documents (never invented)
+     * and the SAME field SHAPES (T2) attached to the unit's payload symbols, with
+     * example VALUES derived from each field's TS type (string→"…", number→1,
+     * enum→a real member, …) — not entity-hardcoded. The body lines (without
+     * imports) are what the agent form shows; the human page wraps the full block
+     * (imports + body) in a fenced ```ts.
+     *
+     * For an ENTITY: a create→find→update→delete flow over the entity's own
+     * CRUD helpers. For a TEMPLATE: an extract (parse LLM text) and/or render
+     * (produce the document) call. Undefined when a unit has no runnable surface
+     * (e.g. a bare value-object model with no queries/template).
+     */
+    example?: UnitExample;
+}
+/** A worked example for a unit: the imports it needs (one `import { … } from "…"`
+ *  per module, in first-appearance order) + the body statements. Split so the
+ *  human page can render a full fenced block and the agent form can show a tight
+ *  body. */
+export interface UnitExample {
+    /** `import { a, b } from "Mod"` lines, deduped by module, reusing the symbols'
+     *  own importPaths (never re-derived). */
+    imports: string[];
+    /** The worked-flow statements (no imports), e.g.
+     *  `const created = await createProduct(db, { name: "…" });`. */
+    body: string[];
+}
+export interface ApiModel {
+    units: ApiUnitDoc[];
+}
+/** Minimal context the builder needs. Accepts a full RenderContext OR just the
+ *  loaded root (pkMap is derived when absent). Keeping it structural means the
+ *  builder runs both inside a gen run and from a thin docs entrypoint. */
+export interface ApiModelContext {
+    loadedRoot: MetaRoot;
+    pkMap?: Map<string, PkInfo>;
+    /** The relation map (relation-resolver) the entity file's relations() block is
+     *  derived from. Derived from `loadedRoot` when absent — keeps the builder
+     *  callable from a thin docs entrypoint. */
+    relationMap?: RelationMap;
+    /** The output layout the codegen run uses. The per-symbol `importPath` mirrors
+     *  the emitting generator's own path computation under this layout (flat →
+     *  `Product.queries`; package → folded under the entity's package path iff the
+     *  generator folds). Defaults to "flat" (today's byte-identical placement). */
+    outputLayout?: OutputLayout;
+    /** Whether to ALSO document the OPT-IN Hono CRUD variant (routesFileHono).
+     *  Hono is not in the default generator suite — it is an alternative wired by
+     *  the adopter — so its symbols are documented ONLY when the adopter opts in
+     *  (mirrors "match the generator's filters": don't over-document a surface the
+     *  run didn't configure). The Fastify REST surface is always documented (it is
+     *  the default-suite routes generator). Defaults to false. */
+    includeHonoRoutes?: boolean;
+}
+export declare function buildApiModel(root: MetaRoot, ctx: ApiModelContext): ApiModel;
+//# sourceMappingURL=api-model.d.ts.map

package/dist/generators/api-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-model.d.ts","sourceRoot":"","sources":["../../src/generators/api-model.ts"],"names":[],"mappings":"AAkFA,OAAO,EACL,KAAK,QAAQ,EAed,MAAM,0BAA0B,CAAC;AAkBlC,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEjG,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,sBAAsB,CAAC;AAM9B,MAAM,MAAM,aAAa,GACrB,OAAO,GACP,aAAa,GACb,MAAM,GACN,YAAY,GACZ,WAAW,GACX,QAAQ,GAER,UAAU,GACV,UAAU,GACV,WAAW,GACX,QAAQ,CAAC;AAEb,MAAM,WAAW,SAAS;IACxB;iEAC6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;gEAE4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;gFAC4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb;;4EAEwE;IACxE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,QAAQ,GAAG,UAAU,CAAC;IAChC,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;;;YAGY;AACZ,MAAM,WAAW,WAAW;IAC1B;8CAC0C;IAC1C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;qEACiE;IACjE,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED;;0EAE0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,QAAQ,CAAC;IACrB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B;;gDAE4C;IAC5C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;mFAG+E;IAC/E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;;kEAK8D;IAC9D,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAMD,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,eAAe,GAAG,QAAQ,CAwB5E"}