@metaobjectsdev/codegen-ts 0.24.4 → 0.25.0

package/src/generators/agent-requirements-page.ts

@@ -0,0 +1,199 @@
+// `agent/requirements.md` — the ledger, plus the index that answers the question an agent
+// actually asks.
+//
+// The `requirements` docs surface is REQUIREMENT-KEYED: it lists entries and, under each,
+// what the entry claims. That is the right shape for reading a ledger and the wrong shape
+// for the question that arises while editing code — *"I am about to change this node; does
+// anything claim it?"* Answering that from the requirement-keyed page means reading all of
+// it, which for this repository's own ledger is 175 rows.
+//
+// So this page carries the same index PLUS a NODE index: every claimed node → the
+// requirements claiming it, at every grain. It is an inversion of `walkRequirements`, not
+// a second walk — the same resolution, read the other way, so the two indexes cannot
+// disagree about what resolves.
+//
+// LITERAL FQNs ON EVERY LINE, deliberately and even where it is repetitive. An agent
+// retrieving over a long context finds a node by matching the token it is holding; a row
+// that says "the field above" is unreachable to it. This is also why the node index is
+// FLAT rather than nested under its owning object.
+//
+// A CLAIM THAT DOES NOT RESOLVE IS OMITTED, silently, exactly as `walkRequirements` omits
+// it. Resolution severity depends on `@status` and belongs to `meta verify`; a docs page
+// that rendered a dangling reference as though it pointed somewhere would be asserting
+// the opposite of what the gate says.
+//
+// THE LEDGER IS EMBEDDED BELOW THE INDEX, and that duplication is deliberate rather than
+// an oversight — the same content also lives at `requirements.md` when that surface is on.
+// The node index alone would omit exactly the entries the mechanism is MEASURED on: a
+// `retired` capability may carry no `@implementedBy` at all (FR-039 forbids it), so it
+// resolves to no node and appears in no node index. The one controlled finding behind this
+// whole vocabulary is that a retired capability goes unnoticed without a ledger — 0 of 24
+// against 19 of 40 — and the page an agent is told to read *before adding a capability* is
+// the last place to drop it. The cost is bytes on a large estate; the alternative is a page
+// that silently loses the only part with evidence behind it.
+
+import { REQUIREMENT_ATTR_STATEMENT } from "@metaobjectsdev/metadata";
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { GENERATED_HEADER } from "../constants.js";
+import { concernOf, walkRequirements } from "../requirement-walk.js";
+import { requirementRows } from "./requirements-view.js";
+import { renderRequirementsMarkdown } from "./requirements-markdown.js";
+
+const GENERATED_MARKER = `<!-- ${GENERATED_HEADER} — DO NOT EDIT. -->`;
+
+/**
+ * The address of any claimed node: the ROOT node's `resolutionKey()` (which carries the
+ * effective package), then the child-name path down to it.
+ *
+ * Built by walking parents rather than read off the node, because only a root-level node
+ * has a resolution key — a claimed FIELD has a bare name, and `Subscriber.status` and
+ * `Order.status` would collide in this index if the owner were dropped.
+ */
+function nodeAddress(node: MetaData): string {
+  const segments: string[] = [];
+  let cur: MetaData | undefined = node;
+  while (cur !== undefined) {
+    const parent: MetaData | undefined = cur.parent;
+    // The last node with a parent is the root-level one; the metadata ROOT itself has no
+    // name worth printing, so the walk stops when the next step would leave the model.
+    if (parent === undefined || parent.parent === undefined) {
+      segments.push(cur.resolutionKey());
+      break;
+    }
+    segments.push(cur.name);
+    cur = parent;
+  }
+  return segments.reverse().join(".");
+}
+
+interface NodeIndexEntry {
+  readonly address: string;
+  readonly concern: string;
+  readonly claims: { path: string; subType: string; level: number | undefined; status: string | undefined; statement: string | undefined }[];
+}
+
+/** Invert the walk: claimed node → the requirements that claim it. */
+export function buildNodeIndex(root: MetaData): NodeIndexEntry[] {
+  const byAddress = new Map<string, NodeIndexEntry>();
+  for (const walked of walkRequirements(root)) {
+    const statement = walked.node.attr(REQUIREMENT_ATTR_STATEMENT);
+    for (const target of walked.targets) {
+      const address = nodeAddress(target.node);
+      let entry = byAddress.get(address);
+      if (entry === undefined) {
+        entry = { address, concern: concernOf(target.node), claims: [] };
+        byAddress.set(address, entry);
+      }
+      entry.claims.push({
+        path: walked.view.path,
+        subType: walked.view.subType,
+        level: walked.view.level,
+        status: walked.view.status,
+        statement: typeof statement === "string" && statement !== "" ? statement : undefined,
+      });
+    }
+  }
+  return [...byAddress.values()].sort((a, b) => a.address.localeCompare(b.address));
+}
+
+function mdCell(text: string): string {
+  return text.replace(/\|/g, "\\|");
+}
+
+/** Collapse to one line — a statement with a newline in it would end the table row. */
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Render the page. Returns "" for a model declaring no requirements — the same contract
+ * `requirementsFile()` keeps, and the only reason a surface that is on by default is a
+ * no-op for a project without a ledger.
+ */
+export function renderAgentRequirementsPage(root: MetaData): string {
+  const rows = requirementRows(root);
+  if (rows.length === 0) return "";
+
+  const index = buildNodeIndex(root);
+  const out: string[] = [];
+  out.push(GENERATED_MARKER);
+  out.push("");
+  out.push("# Requirements");
+  out.push("");
+  out.push(
+    "Read this before adding a capability, and before extending anything that looks like " +
+      "it already does what you were asked for.",
+  );
+  out.push("");
+  out.push(
+    "- A requirement is **prescriptive**: it states what should be true, never what " +
+      "happened. `status: retired` means the capability was BUILT and deliberately " +
+      "REMOVED — that entry is a prohibition, not history, and the right response to it " +
+      "is to stop, not to rebuild.",
+  );
+  out.push(
+    "- The **node index** below answers *\"does anything claim the thing I am about to " +
+      "change?\"*. Match the literal FQN.",
+  );
+  out.push(
+    "- **The ledger under it is not the same list.** A retired capability carries no " +
+      "`@implementedBy` — there is nothing left to point at — so it appears there and " +
+      "in no index. Read it before you conclude a capability does not exist yet.",
+  );
+  out.push("");
+
+  if (index.length > 0) {
+    out.push("## Node index");
+    out.push("");
+    out.push("| Node | Kind | Claimed by |");
+    out.push("|---|---|---|");
+    for (const entry of index) {
+      const claims = entry.claims
+        .map((c) => {
+          const level = c.level === undefined ? "" : ` L${c.level}`;
+          const status = c.status === undefined ? "" : ` (${c.status})`;
+          return `\`${c.path}\`${level}${status}`;
+        })
+        .join("<br>");
+      out.push(`| \`${entry.address}\` | \`${entry.concern}\` | ${claims} |`);
+    }
+    out.push("");
+    // The statements ride below the table: they are prose, they repeat across nodes a
+    // shared architectural entry claims, and putting one in a cell forces the table wide.
+    const stated = new Map<string, { subType: string; statement: string }>();
+    for (const entry of index) {
+      for (const c of entry.claims) {
+        if (c.statement !== undefined) stated.set(c.path, { subType: c.subType, statement: c.statement });
+      }
+    }
+    if (stated.size > 0) {
+      out.push("### What those requirements say");
+      out.push("");
+      for (const [path, { subType, statement }] of [...stated.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        out.push(`- \`${path}\` (\`${subType}\`) — ${mdCell(oneLine(statement))}`);
+      }
+      out.push("");
+    }
+  } else {
+    out.push("## Node index");
+    out.push("");
+    out.push(
+      "No requirement resolves to a model node. The common reason is the ordinary one: an " +
+        "entry at L4 or L5 that simply declares no `@implementedBy` yet, which is legal " +
+        "and is what a `planned` entry looks like. The others are an entry sitting ABOVE " +
+        "the L4 link floor (where a claim is not permitted), a `retired` entry (where it " +
+        "is forbidden outright), and a claim that names a node nothing resolves — " +
+        "`meta verify` is what says which.",
+    );
+    out.push("");
+  }
+
+  out.push("## The ledger");
+  out.push("");
+  // The SAME renderer the `requirements` surface uses. A second rendering of the ledger
+  // would be a second thing to keep true. `embedded` drops its own H1 and demotes every
+  // heading one level, so the entries nest under this section instead of escaping it.
+  out.push(renderRequirementsMarkdown(rows, { embedded: true }).replace(/\n+$/, ""));
+
+  return `${out.join("\n").replace(/\n+$/, "")}\n`;
+}

package/src/generators/agent-schema-input.ts

@@ -0,0 +1,88 @@
+// The `agent/schema.md` surface's INPUT contract — the physical schema, supplied by
+// whoever owns it.
+//
+// codegen-ts does not compute any of this and must not. The expected schema, the
+// dialect SQL type of a column, and the qualified name a table is keyed by are all
+// `@metaobjectsdev/migrate-ts`'s answers: it builds the snapshot the diff compares, it
+// renders the DDL, and its `qualifiedDbName` is the one key three separate suppression
+// sets already agree on. Re-deriving any of them here would give an adopter a page
+// describing a schema the tool does not produce — and the disagreement would be
+// invisible, because a documentation page looks authoritative and nothing compares it
+// to the migration.
+//
+// So the surface takes the schema as an ARGUMENT, with the resolvers injected. The
+// types below are structural on purpose: `migrate-ts`'s own `SchemaSnapshot`,
+// `TableDescriptor` and `ColumnDescriptor` satisfy them without codegen-ts taking a
+// dependency on that package (it has none today, and the docs surface is not a reason
+// to add one — `meta docs` in the CLI depends on both and is where they meet).
+//
+// ABSENT INPUT IS A SUPPORTED STATE, not a failure. `meta docs` runs without a gen
+// config, and a project with no dialect has no physical schema to describe; the surface
+// then emits nothing rather than a page full of unknowns.
+
+/** A canonical SQL type as `migrate-ts` models it. Opaque here — only `columnType` reads it. */
+export interface SchemaColumnLike {
+  readonly name: string;
+  readonly nullable: boolean;
+  readonly default?: { readonly kind: "literal" | "expr"; readonly value: string } | undefined;
+  readonly identity?: "increment" | "uuid" | undefined;
+  /** Threaded from the field's `@description` — the business semantics beside the column. */
+  readonly description?: string | undefined;
+}
+
+export interface SchemaIndexLike {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+  readonly where?: string | undefined;
+  readonly expr?: string | undefined;
+  readonly using?: string | undefined;
+}
+
+export interface SchemaFkLike {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly refTable: string;
+  readonly refColumns: readonly string[];
+  readonly onDelete?: string | undefined;
+  readonly onUpdate?: string | undefined;
+}
+
+export interface SchemaCheckLike {
+  readonly name: string;
+  readonly expression: string;
+}
+
+export interface SchemaTableLike {
+  readonly name: string;
+  readonly schema?: string | undefined;
+  readonly columns: readonly SchemaColumnLike[];
+  readonly indexes: readonly SchemaIndexLike[];
+  readonly foreignKeys: readonly SchemaFkLike[];
+  readonly checks: readonly SchemaCheckLike[];
+  readonly primaryKey: readonly string[];
+  /** Threaded from the entity's `@description`. */
+  readonly description?: string | undefined;
+}
+
+export interface SchemaViewLike {
+  readonly name: string;
+  readonly schema?: string | undefined;
+  readonly columns?: readonly { readonly name: string }[] | undefined;
+}
+
+/**
+ * Everything `agent/schema.md` renders from, plus the two resolvers it refuses to own.
+ */
+export interface AgentSchemaInput {
+  /** `postgres` | `sqlite` | `d1` — named on the page so a reader knows which SQL they are reading. */
+  readonly dialect: string;
+  readonly tables: readonly SchemaTableLike[];
+  readonly views: readonly SchemaViewLike[];
+  /** Qualified physical name → the declaring object's `resolutionKey()`. */
+  readonly provenance: ReadonlyMap<string, string>;
+  /** `migrate-ts`'s `columnTypeSql`, bound to `dialect`. */
+  readonly columnType: (column: SchemaColumnLike) => string;
+  /** `migrate-ts`'s `qualifiedDbName` — the ONE key the provenance map is built with. */
+  readonly qualify: (obj: { name: string; schema?: string | undefined }) => string;
+}

package/src/generators/agent-schema-page.ts

@@ -0,0 +1,297 @@
+// `agent/schema.md` — the physical schema, for an agent about to touch persistence.
+//
+// WHY THIS PAGE EXISTS AND WHY IT LOOKS LIKE THIS
+//
+// The strongest measured finding behind this surface is not about format: roughly 2K
+// tokens of BUSINESS SEMANTICS beside the schema is worth an order of magnitude more
+// than any table-versus-YAML-versus-DDL choice. So every table and column carries its
+// `@description`, and the descriptions come from the snapshot itself — `migrate-ts`
+// already threads them there to emit `COMMENT ON`, which means the page and the database
+// comment cannot disagree.
+//
+// IT DOES NOT RESTATE THE DDL. The migration files ARE the DDL, they are generated, and
+// they are what actually runs. A page that reproduces `CREATE TABLE` is a second spelling
+// of the same fact that goes stale the first time someone regenerates without it — so
+// this page describes the schema and CITES the migrations for the statements.
+//
+// It is TABLE-DRIVEN, not entity-driven, and that is deliberate: a TPH hierarchy folds
+// several entities into one table, an abstract base has none, and an `@unmanaged` object
+// is excluded — all rules `buildExpectedSchema`'s Pass 1 already owns. Walking entities
+// here would mean re-implementing those skip rules and drifting from them. The declaring
+// object is named per table from the provenance map instead.
+
+import { GENERATION_INCREMENT, GENERATION_UUID } from "@metaobjectsdev/metadata";
+import { GENERATED_HEADER } from "../constants.js";
+import type {
+  AgentSchemaInput,
+  SchemaColumnLike,
+  SchemaFkLike,
+  SchemaIndexLike,
+  SchemaTableLike,
+} from "./agent-schema-input.js";
+
+const GENERATED_MARKER = `<!-- ${GENERATED_HEADER} — DO NOT EDIT. -->`;
+
+/** Markdown-escape a cell whose text may contain a `|` (a CHECK expression can). */
+function mdCell(text: string): string {
+  return text.replace(/\|/g, "\\|");
+}
+
+/** Collapse a description to one line — a newline inside a table cell ends the row. */
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+/** `` `a`, `b` `` — a column list, or an em-dash when empty. */
+function cols(list: readonly string[]): string {
+  return list.length === 0 ? "—" : list.map((c) => `\`${c}\``).join(", ");
+}
+
+/**
+ * The KEY cell: primary / foreign / unique / indexed, most-specific first.
+ *
+ * A COMPOSITE index is labelled as one. A bare `unique` on a column that is merely one
+ * member of a two-column unique index asserts that the column alone is unique — which is
+ * false, and false in the direction that makes a reader write a lookup that returns more
+ * than one row. The Indexes section below carries the full key; this cell only has to stop
+ * being wrong about it.
+ */
+function keyCell(table: SchemaTableLike, column: SchemaColumnLike): string {
+  const roles: string[] = [];
+  if (table.primaryKey.includes(column.name)) {
+    roles.push(table.primaryKey.length > 1 ? "PK (composite)" : "PK");
+  }
+  const fk = table.foreignKeys.find((f) => f.columns.includes(column.name));
+  if (fk !== undefined) roles.push(`FK → \`${fk.refTable}\``);
+  const covering = table.indexes.filter((i) => i.columns.includes(column.name));
+  const unique = covering.find((i) => i.unique);
+  const index = unique ?? covering[0];
+  if (index !== undefined) {
+    const label = unique !== undefined ? "unique" : "indexed";
+    roles.push(index.columns.length > 1 ? `${label} (composite)` : label);
+  }
+  return roles.length === 0 ? "" : roles.join(" · ");
+}
+
+/** The DEFAULT cell. An `expr` default is shown as SQL; a literal as a literal. */
+function defaultCell(column: SchemaColumnLike): string {
+  if (column.identity === GENERATION_INCREMENT) return "auto-increment";
+  if (column.identity === GENERATION_UUID) return "generated uuid";
+  if (column.default === undefined) return "";
+  return `\`${mdCell(column.default.value)}\``;
+}
+
+function indexLine(ix: SchemaIndexLike): string {
+  const key = ix.expr !== undefined ? `\`${mdCell(ix.expr)}\`` : cols(ix.columns);
+  const parts = [`\`${ix.name}\``, ix.unique ? "unique" : "index", `on ${key}`];
+  if (ix.using !== undefined && ix.using !== "" && ix.using !== "btree") parts.push(`using \`${ix.using}\``);
+  if (ix.where !== undefined && ix.where !== "") parts.push(`where \`${mdCell(ix.where)}\``);
+  return `- ${parts.join(" · ")}`;
+}
+
+function fkLine(fk: SchemaFkLike): string {
+  const parts = [
+    `\`${fk.name}\``,
+    `${cols(fk.columns)} → \`${fk.refTable}\`(${cols(fk.refColumns)})`,
+  ];
+  if (fk.onDelete !== undefined && fk.onDelete !== "") parts.push(`on delete \`${fk.onDelete}\``);
+  if (fk.onUpdate !== undefined && fk.onUpdate !== "") parts.push(`on update \`${fk.onUpdate}\``);
+  return `- ${parts.join(" · ")}`;
+}
+
+/**
+ * One table's section: the declaring object, its description, the column table, then
+ * whichever of indexes / foreign keys / checks the table actually has.
+ *
+ * `declaredBy` maps a physical column name back to the FIELD that declared it — the
+ * mapping an agent needs to go from a query it is reading to the metadata it must edit,
+ * and the one thing the snapshot alone cannot supply.
+ */
+function tableSection(
+  table: SchemaTableLike,
+  input: AgentSchemaInput,
+  fqn: string | undefined,
+  declaredBy: ReadonlyMap<string, { field: string; type: string }>,
+): string[] {
+  const out: string[] = [];
+  const qualified = table.schema === undefined ? `\`${table.name}\`` : `\`${table.schema}.${table.name}\``;
+  out.push(`### ${qualified}`);
+  out.push("");
+  if (fqn !== undefined) out.push(`Declared by \`${fqn}\`.`);
+  if (table.description !== undefined && table.description !== "") {
+    out.push("");
+    out.push(`> ${oneLine(table.description)}`);
+  }
+  out.push("");
+  out.push("| Column | Field | Declared | SQL type | Null | Default | Key |");
+  out.push("|---|---|---|---|---|---|---|");
+  for (const c of table.columns) {
+    const declared = declaredBy.get(c.name);
+    out.push(
+      `| \`${c.name}\` | ${declared === undefined ? "" : `\`${declared.field}\``} | ` +
+        `${declared === undefined ? "" : `\`${declared.type}\``} | \`${mdCell(input.columnType(c))}\` | ` +
+        `${c.nullable ? "yes" : "no"} | ${defaultCell(c)} | ${keyCell(table, c)} |`,
+    );
+  }
+  // Column descriptions ride BELOW the table rather than as an eighth cell: a sentence
+  // in a cell forces the whole table wide, and most columns have none.
+  const described = table.columns.filter((c) => c.description !== undefined && c.description !== "");
+  if (described.length > 0) {
+    out.push("");
+    for (const c of described) out.push(`- \`${c.name}\` — ${oneLine(c.description ?? "")}`);
+  }
+  if (table.indexes.length > 0) {
+    out.push("");
+    out.push("**Indexes**");
+    out.push("");
+    for (const ix of table.indexes) out.push(indexLine(ix));
+  }
+  if (table.foreignKeys.length > 0) {
+    out.push("");
+    out.push("**Foreign keys**");
+    out.push("");
+    for (const fk of table.foreignKeys) out.push(fkLine(fk));
+  }
+  if (table.checks.length > 0) {
+    out.push("");
+    out.push("**Checks**");
+    out.push("");
+    for (const ck of table.checks) out.push(`- \`${ck.name}\` — \`${mdCell(ck.expression)}\``);
+  }
+  out.push("");
+  return out;
+}
+
+export interface AgentSchemaPageOptions {
+  /** Column → declaring field, per QUALIFIED table name. Supplied by the generator, which
+   *  holds the loaded model; see `agentDocsFile`. */
+  readonly declaredBy: ReadonlyMap<string, ReadonlyMap<string, { field: string; type: string }>>;
+  /** Per-projection lineage lines, keyed by QUALIFIED view name. */
+  readonly viewLineage: ReadonlyMap<string, readonly string[]>;
+  /** Relationship lines, already rendered from the model. */
+  readonly relationships: readonly string[];
+  /** Enum lines, already rendered from the model. */
+  readonly enums: readonly string[];
+}
+
+/**
+ * Render the whole page. Returns "" when there is no physical schema at all, which is
+ * what lets the surface emit no FILE rather than a page describing nothing.
+ */
+export function renderAgentSchemaPage(
+  input: AgentSchemaInput,
+  opts: AgentSchemaPageOptions,
+): string {
+  if (input.tables.length === 0 && input.views.length === 0) return "";
+
+  const out: string[] = [];
+  out.push(GENERATED_MARKER);
+  out.push("");
+  out.push("# Schema");
+  out.push("");
+  out.push(
+    `The physical shape of the \`${input.dialect}\` database this model generates. ` +
+      "Read it before writing a query, a migration, or anything that names a table or a column.",
+  );
+  out.push("");
+  out.push(
+    "- The **DDL is not repeated here.** The migration files are the DDL, they are " +
+      "generated, and they are what runs — this page describes the schema they produce.",
+  );
+  out.push(
+    "- Change the schema by changing the **metadata** and running `meta migrate`. Never " +
+      "hand-apply SQL to a live database: it drifts from the migration history and " +
+      "collides at the next migrate.",
+  );
+  out.push(
+    "- `Field` and `Declared` are the METADATA names. Edit those; the column name follows.",
+  );
+  out.push("");
+
+  // The semantics nudge. A schema page carrying business meaning beside the columns is
+  // worth more to a reader working from it than any format choice this page could make —
+  // and those sentences come from `@description` on the entity and the field, which the
+  // snapshot already threads here to emit `COMMENT ON`. A model declaring none renders a
+  // page of names with nothing to disambiguate them, and says so, because silently
+  // omitting the highest-value content teaches an adopter that it does not exist.
+  const anyDescription =
+    input.tables.some(
+      (t) =>
+        (t.description !== undefined && t.description !== "") ||
+        t.columns.some((c) => c.description !== undefined && c.description !== ""),
+    );
+  if (!anyDescription && input.tables.length > 0) {
+    out.push(
+      "> **Nothing in this model declares a `description`.** The tables and columns below " +
+        "are named but not explained. Adding `description` to an entity or a field is the " +
+        "single highest-value change to this page: it is what tells a reader *which* of " +
+        "two plausible columns to use, and it is the same text `meta migrate` emits as a " +
+        "`COMMENT ON`, so it lands in the database too.",
+    );
+    out.push("");
+  }
+
+  if (input.tables.length > 0) {
+    out.push("## Tables");
+    out.push("");
+    for (const table of [...input.tables].sort((a, b) => a.name.localeCompare(b.name))) {
+      const key = input.qualify(table);
+      out.push(
+        ...tableSection(
+          table,
+          input,
+          input.provenance.get(key),
+          opts.declaredBy.get(key) ?? new Map(),
+        ),
+      );
+    }
+  }
+
+  if (input.views.length > 0) {
+    out.push("## Views");
+    out.push("");
+    out.push(
+      "A view is generated from its projection's `origin.*` children — it is derived, " +
+        "never hand-written. Editing the view SQL directly is drift the tool cannot see.",
+    );
+    out.push("");
+    for (const view of [...input.views].sort((a, b) => a.name.localeCompare(b.name))) {
+      const key = input.qualify(view);
+      const qualified = view.schema === undefined ? `\`${view.name}\`` : `\`${view.schema}.${view.name}\``;
+      out.push(`### ${qualified}`);
+      out.push("");
+      const fqn = input.provenance.get(key);
+      if (fqn !== undefined) out.push(`Declared by \`${fqn}\`.`);
+      const lineage = opts.viewLineage.get(key) ?? [];
+      if (lineage.length > 0) {
+        out.push("");
+        out.push("| Column | Lineage |");
+        out.push("|---|---|");
+        out.push(...lineage);
+      }
+      out.push("");
+    }
+  }
+
+  if (opts.relationships.length > 0) {
+    out.push("## Relationships");
+    out.push("");
+    out.push(...opts.relationships);
+    out.push("");
+  }
+
+  if (opts.enums.length > 0) {
+    out.push("## Enums");
+    out.push("");
+    out.push(
+      "Members are the values the wire and the generated types use. Whether the DATABASE " +
+        "also refuses a value outside the set is that table's **Checks** above — an " +
+        "`@isArray` enum carries none, and neither does a view column.",
+    );
+    out.push("");
+    out.push(...opts.enums);
+    out.push("");
+  }
+
+  return `${out.join("\n").replace(/\n+$/, "")}\n`;
+}