@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/src/generators/api-docs-file.ts

@@ -0,0 +1,146 @@
+// apiDocsFile() — the `api-docs` GENERATOR (ADR-0022 Part 3, Tier-1 NATIVE).
+//
+// It documents the PUBLIC API surface the OTHER generators emit for a model —
+// the generated code's own API, in two forms (a human reference + a condensed
+// agent form). It is a thin wiring layer: it REUSES, without re-derivation,
+//   • Task-1's buildApiModel() — the accurate-by-construction IR, and
+//   • Task-2's renderEntityApiPage / renderApiIndex / renderAgentApi renderers,
+//   • the shared docs-paths placement (collision-safe, layout-aware) that
+//     docsFile() uses — so multi-package models never silently overwrite a page.
+//
+// Output (all under `docs/api/`):
+//   • one `<Node>.md` per entity + template.output unit (the human page),
+//   • `README.md` — the consolidated human index (GitHub treats it as landing),
+//   • `AGENT-API.md` — the token-frugal agent form.
+//
+// Unlike `docs`/`mermaid-er` (Tier-2 neutral, owned by `meta docs`), `api-docs`
+// is a NATIVE generator: it is REGISTERED in the generator registry (ADR-0022
+// Part 3) — so it appears in `gen --list` and is selectable by its stable name
+// `api-docs`. It is NOT a `meta docs` mode.
+//
+// It is NOT (yet) part of the default `meta gen` scaffold suite: it is
+// registry-listed but not auto-run. Turning it on by default in the scaffold,
+// and surfacing the agent form (AGENT-API.md) to a coding agent via a pointer
+// from the installed `.metaobjects/` context, are tracked as agent-context-
+// coordination follow-ups — deliberately deferred here to avoid colliding with
+// the live agent-context work.
+
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import type { Generator, GeneratorFactory, EmittedFile } from "../generator.js";
+import {
+  docPageOutputPath,
+  surfaceCrossHref,
+  assertNoDuplicateDocPaths,
+  type DocPageNode,
+  type DocPagePlacement,
+} from "../docs-paths.js";
+import { projectProvider } from "../render-engine/framework-provider.js";
+import { buildApiModel } from "./api-model.js";
+import {
+  renderEntityApiPage,
+  renderApiIndex,
+  renderAgentApi,
+} from "./api-doc-render.js";
+
+// All api-docs artifacts live under this sub-directory of the codegen out dir.
+// Per-unit pages fold further under their package path (package layout); the
+// index + agent form stay at the api root (their links are computed relative to
+// it via the same docPageHref the renderers use).
+//
+// The DEFAULT prefix is `docs/api` — byte-identical to the historical `meta gen`
+// behaviour + goldens. The unified `meta docs` command (which writes everything
+// under one docs root, `./docs`) overrides it via `subDir:'api'` so the api
+// surface emits `api/<Node>.md` rather than doubling to `./docs/docs/api`.
+const DEFAULT_API_DIR = "docs/api";
+
+export interface ApiDocsFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+  /** Output prefix for all api-docs artifacts. Default `docs/api`. */
+  subDir?: string;
+  /** When true, the model surface is emitted alongside the api surface (at the
+   *  docs root), so each api entity page cross-links back to its model page. The
+   *  href is computed via the shared `surfaceCrossHref` so it resolves in BOTH
+   *  layouts. ABSENT/false ⇒ default api output byte-identical. */
+  modelSurface?: boolean;
+}
+
+/**
+ * @deprecated ADR-0025: `meta docs` is the single door for ALL docs. `apiDocsFile()`
+ * stays as the INTERNAL engine of the docs door's api surface — do NOT add it to a
+ * `meta gen` config / the generators array. Use `meta docs` (it emits the api surface
+ * alongside the model surface). A `meta gen` config that lists it is warned + skipped.
+ */
+export const apiDocsFile = function apiDocsFile(opts?: ApiDocsFileOpts): Generator {
+  const generator: Generator = {
+    name: "api-docs",
+    generate(ctx) {
+      const provider = projectProvider(ctx.projectRoot ?? process.cwd());
+      const layout = ctx.config.outputLayout ?? "flat";
+
+      // Per-call output prefix. Default `docs/api`; `meta docs` passes `api`.
+      const apiDir = opts?.subDir ?? DEFAULT_API_DIR;
+      const indexFilename = `${apiDir}/README.md`;
+      const agentFilename = `${apiDir}/AGENT-API.md`;
+
+      // ONE ApiModel feeds every form (Task-1 builder; Task-2 renderers). The
+      // pkMap is reused from the run's renderContext when present (the real gen
+      // run always provides it) and derived otherwise.
+      // Auto-detect: document the OPT-IN Hono CRUD surface iff the Hono routes
+      // generator is actually in the run. The runner aggregates each generator's
+      // `emitsHonoRoutes` marker into ctx.config.includeHonoRoutes, so api-docs
+      // "just works" — it documents Hono exactly when `routesFileHono` is wired,
+      // and omits it (Fastify-only) otherwise. No explicit opt needed.
+      const model = buildApiModel(ctx.loadedRoot, {
+        loadedRoot: ctx.loadedRoot,
+        outputLayout: layout,
+        includeHonoRoutes: ctx.config.includeHonoRoutes ?? false,
+        ...(ctx.renderContext?.pkMap !== undefined && { pkMap: ctx.renderContext.pkMap }),
+      });
+
+      // Track (path, fqn) for the SAME hard collision backstop docsFile() uses —
+      // two units that resolve to one path (flat, cross-package short-name clash)
+      // throw rather than silently overwrite.
+      const placements: DocPagePlacement[] = [];
+
+      // Per-unit human page. Placement is collision-safe via docPageOutputPath
+      // off {name, effective package}, prefixed under the api dir; the index
+      // (renderApiIndex) computes its links from the SAME {name, package}, so a
+      // link always points at the page's real location in BOTH layouts.
+      const files: EmittedFile[] = model.units.map((unit) => {
+        const node: DocPageNode = { name: unit.node, package: unit.package };
+        const path = `${apiDir}/${docPageOutputPath(layout, node)}`;
+        placements.push({ path, fqn: unit.package ? `${unit.package}::${unit.node}` : unit.node });
+        // Cross-link back to the sibling model page, when emitted. The model page
+        // lives at the docs root at `<placement>`; this api page lives at
+        // `<apiDir>/<placement>`. The href is derived from the SAME
+        // docPageOutputPath placement via surfaceCrossHref so it resolves in both
+        // layouts. ABSENT otherwise.
+        const modelPageHref = opts?.modelSurface
+          ? surfaceCrossHref(path, docPageOutputPath(layout, node))
+          : undefined;
+        return { path, content: renderEntityApiPage(unit, provider, modelPageHref) };
+      });
+
+      // The consolidated human index (README.md) + the condensed agent form,
+      // both at the api root. Only emitted when at least one unit page exists.
+      if (files.length > 0) {
+        placements.push({ path: indexFilename, fqn: "<the api-docs index page>" });
+        placements.push({ path: agentFilename, fqn: "<the api-docs agent form>" });
+        files.unshift(
+          { path: indexFilename, content: renderApiIndex(model, layout, provider) },
+          { path: agentFilename, content: renderAgentApi(model, provider) },
+        );
+      }
+
+      // Hard backstop against silent overwrite (ALL layouts): throw naming both
+      // colliding FQNs + the path. Same guard docsFile() reuses.
+      assertNoDuplicateDocPaths(placements);
+
+      return files;
+    },
+  };
+  if (opts?.filter) generator.filter = opts.filter;
+  if (opts?.target) generator.target = opts.target;
+  return generator;
+} as GeneratorFactory<ApiDocsFileOpts>;

package/src/generators/api-field-shape.ts

@@ -0,0 +1,114 @@
+// 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 type { MetaObject, MetaField, MetaRoot } from "@metaobjectsdev/metadata";
+import { fieldTsTypeString } from "../templates/inferred-types.js";
+import {
+  insertSchemaFields,
+  updateSchemaFields,
+  type SchemaFieldShape,
+} from "../templates/zod-validators.js";
+import { isFieldRequired } from "./docs-data-builder.js";
+
+/** One documented field in a model / payload shape. Structured so BOTH renderers
+ *  (the human field table + the agent inline shape) format it without re-deriving. */
+export interface FieldShape {
+  /** The field name (the property key). */
+  name: string;
+  /** The TS type expression, e.g. `string`, `number`, `"active" | "archived"`,
+   *  `Address[]`. Enum unions are inlined (self-contained for an agent). */
+  type: string;
+  /** Whether the property is optional in this shape (`name?: T`). */
+  optional: boolean;
+  /** A short note, e.g. `pinned "Bridge"` (TPH discriminator) or `server-set`
+   *  (@autoSet). Undefined when there is nothing extra to say. */
+  note?: string;
+}
+
+/**
+ * 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: MetaObject): FieldShape[] {
+  const pkNames = new Set<string>(obj.primaryIdentity()?.fields ?? []);
+  return obj.fields().map((field: MetaField): FieldShape => {
+    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: MetaObject, walk: SchemaFieldShape[]): FieldShape[] {
+  const fieldByName = new Map<string, MetaField>(obj.fields().map((f) => [f.name, f]));
+  return walk.map((sf): FieldShape => {
+    const field = fieldByName.get(sf.name);
+    let type = field !== undefined ? fieldTsTypeString(obj.name, field) : "unknown";
+    let note: string | undefined;
+    if (sf.pinnedLiteral !== undefined) {
+      type = JSON.stringify(sf.pinnedLiteral);
+      note = `pinned ${type}`;
+    } else if (sf.autoSet === true) {
+      note = "server-set";
+    }
+    const shape: FieldShape = { 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: MetaObject): FieldShape[] {
+  return shapesFromSchemaFields(obj, insertSchemaFields(obj));
+}
+
+/** The update-payload (UpdateSchema) field shape — what `update<Name>` / PATCH
+ *  accepts (typically all-optional partial). */
+export function updateFieldShapes(obj: MetaObject): FieldShape[] {
+  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: MetaRoot, payloadRef: string): FieldShape[] | undefined {
+  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: FieldShape[]): string {
+  if (fields.length === 0) return "{}";
+  const parts = fields.map((f) => `${f.name}${f.optional ? "?" : ""}: ${f.type}`);
+  return `{ ${parts.join("; ")} }`;
+}

package/src/generators/api-label.ts

@@ -0,0 +1,7 @@
+const LABELS: Record<string, string> = {
+  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: string): string {
+  return LABELS[lang] ?? (lang.length ? lang[0]!.toUpperCase() + lang.slice(1) : lang);
+}