@metaobjectsdev/docs-site 0.15.8-rc.1

package/src/builders/object-data.ts

@@ -0,0 +1,261 @@
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { LinkGraph, fqnOf, type Ref } from "../link-graph";
+import type { CoverageTracker } from "../coverage";
+import { esc, badge } from "../badges";
+import { inheritanceTree, erDiagramRich, flowchartDomain, RICH_MAX, type ErEdge, type ErNode, type ErAttr } from "../mermaid";
+
+// capped box attributes for the rich neighborhood ERD: PK → FKs(target) → enums → required, ≤6 + overflow count
+function neighborAttrs(o: MetaData): { attrs: ErAttr[]; more: number } {
+  const pk = new Set<string>(), fk = new Map<string, string>();
+  for (const id of o.childrenOfType("identity")) {
+    const flds = id.attr("fields");
+    const names = Array.isArray(flds) ? flds.map(String) : flds !== undefined ? [String(flds)] : [];
+    if (id.subType === "primary") names.forEach((n) => pk.add(n));
+    if (id.subType === "reference") { const tgt = String(id.attr("references") ?? "").split("::").pop() ?? ""; names.forEach((n) => fk.set(n, tgt)); }
+  }
+  const fields = o.childrenOfType("field");
+  const isEnum = (f: MetaData) => Array.isArray(f.attr("values"));
+  const isReq = (f: MetaData) => f.attr("required") === true || f.attr("required") === "true";
+  const attrs: ErAttr[] = []; const seen = new Set<string>();
+  const push = (f: MetaData, key: ErAttr["key"], note: string) => { if (seen.has(f.name) || attrs.length >= 6) return; seen.add(f.name); attrs.push({ type: f.subType, name: f.name, key, note }); };
+  for (const f of fields) if (pk.has(f.name)) push(f, "PK", "");
+  for (const f of fields) if (fk.has(f.name)) push(f, "FK", fk.get(f.name)!);
+  for (const f of fields) if (isEnum(f)) push(f, "", "enum");
+  for (const f of fields) if (isReq(f)) push(f, "", "req");
+  const relevant = fields.filter((f) => pk.has(f.name) || fk.has(f.name) || isEnum(f) || isReq(f)).length;
+  return { attrs, more: Math.max(0, relevant - attrs.length) };
+}
+
+export interface EnumValue { value: string; deflt: boolean; desc: string; }
+export interface FieldRow { name: string; type: string; isArray: boolean; required: boolean; badgesHtml: string; desc: string; enumValues: EnumValue[]; refHref?: string | undefined; refName?: string | undefined; inheritedFrom?: { name: string; href: string } | undefined; anchor: string; }
+export interface IndexRow { name: string; kind: string; fields: string; extra: string; unique: boolean; }
+export interface ValidatorRow { scope: "field" | "object"; subject: string; rule: string; // human-readable, HTML-escaped
+}
+export interface RelationRow { name: string; toName: string; toHref: string; cardinality: string; }
+export interface OriginRow { field: string; from: string; via: string; }
+export interface HierRow { name: string; href: string; level: number; self: boolean; }
+export interface ObjectPageData {
+  name: string; kindBadge: string; isAbstract: boolean; isView: boolean; generation: string;
+  pkg: string; href: string; breadcrumbHtml: string; desc: string; tableName?: string | undefined; pkHtml?: string | undefined;
+  ownFields: FieldRow[]; inheritedFields: FieldRow[]; indexes: IndexRow[]; validators: ValidatorRow[];
+  relations: RelationRow[]; origins: OriginRow[]; hierarchy: HierRow[]; inheritanceMermaid?: string | undefined;
+  neighborhoodMermaid?: string | undefined; neighborhoodLegend?: { pkg: string; fill: string; stroke: string }[] | undefined; neighborhoodMore?: number | undefined;
+  referencedBy: { name: string; href: string; via: string }[];
+  references: { name: string; href: string; via: string }[]; usedByTemplates: { name: string; href: string }[];
+  sourceFile: string;
+}
+
+function fieldRow(f: MetaData, ownerHref: string, g: LinkGraph, cov: CoverageTracker, ctxPkg: string): FieldRow {
+  cov.consumeNode(f);
+  const a = (n: string) => { const v = f.attr(n); if (v !== undefined) cov.consumeAttr(f, n); return v; };
+  const bits: string[] = [];
+  const reqVal = a("required"); const required = reqVal === true || reqVal === "true";
+  if (required) bits.push(badge({ text: "required", cls: "badge-soft badge-error" }));
+  if (a("deprecated") !== undefined) bits.push(badge({ text: "deprecated", cls: "badge-soft badge-warning" }));
+  const len = a("maxLength"); if (len !== undefined) bits.push(badge({ text: `≤${len}`, cls: "badge-soft badge-neutral" }));
+  const dbt = a("dbColumnType"); if (dbt !== undefined) bits.push(badge({ text: String(dbt), cls: "badge-soft badge-neutral" }));
+  const def = a("default"); if (def !== undefined) bits.push(badge({ text: `default ${def}`, cls: "badge-soft badge-neutral" }));
+  if (a("xmlText") !== undefined) bits.push(badge({ text: "@xmlText", cls: "badge-soft badge-neutral" }));
+  // enum values as data (rendered per-value in the template)
+  const valuesAttr = a("values");
+  const enumValues: EnumValue[] = Array.isArray(valuesAttr)
+    ? valuesAttr.map((v) => ({ value: esc(String(v)), deflt: String(def ?? "") === String(v), desc: "" }))
+    : [];
+  if (enumValues.length) bits.push(badge({ text: "enum", cls: "badge-soft badge-accent" }));
+  // field-level validators as badges
+  for (const v of f.childrenOfType("validator")) {
+    cov.consumeNode(v);
+    if (v.subType === "regex") { cov.consumeAttr(v, "pattern"); bits.push(badge({ text: `regex ${v.attr("pattern")}`, cls: "badge-soft badge-neutral" })); }
+    if (v.subType === "numeric") {
+      const mm = ["min", "max"].filter((k) => v.attr(k) !== undefined).map((k) => { cov.consumeAttr(v, k); return `${k}=${v.attr(k)}`; });
+      if (mm.length) bits.push(badge({ text: mm.join(" "), cls: "badge-soft badge-neutral" }));
+    }
+  }
+  // reference vs containment badge. A field of subType `object` with an objectRef CONTAINS a nested
+  // object (composition); a scalar field with an objectRef REFERENCES another object by id.
+  let refHref: string | undefined, refName: string | undefined;
+  const oref = a("objectRef");
+  if (typeof oref === "string") {
+    const t = g.byFqn(oref.includes("::") ? oref : `${ctxPkg}::${oref}`) ?? g.byFqn(oref);
+    if (t) {
+      refHref = g.relHref(ownerHref, t.href); refName = t.name;
+      const contains = f.subType === "object";
+      bits.push(badge({
+        text: contains ? `⊃ ${t.name}` : `→ ${t.name}`,
+        cls: contains ? "badge-soft badge-secondary" : "badge-soft badge-info",
+        href: refHref,
+        title: contains ? "contains (nested object)" : "reference",
+      }));
+    }
+  }
+  const desc = esc(a("description") ?? "");
+  return { name: f.name, type: f.subType, isArray: f.resolvedIsArray(), required, badgesHtml: bits.join(" "), desc, enumValues, refHref, refName, inheritedFrom: undefined, anchor: `f-${f.name}` };
+}
+
+// Neighborhood edge label: relationship edges show their name + (M:N) junction + onDelete; extends/others show via.
+function edgeLabelFor(r: Ref): string {
+  if (r.kind === "extends") return "extends";
+  if (r.kind === "relationship") {
+    const junction = r.through ? ` · M:N via ${r.through.split("::").pop()}` : "";
+    const od = r.onDelete ? ` · ${r.onDelete}` : "";
+    return `${r.via}${junction}${od}`;
+  }
+  return r.via;
+}
+
+export function buildObjectPage(fqn: string, g: LinkGraph, cov: CoverageTracker): ObjectPageData {
+  const dn = g.byFqn(fqn);
+  if (!dn || dn.kind !== "object") throw new Error(`not an object: ${fqn}`);
+  const o = dn.node;
+  cov.consumeNode(o);
+  cov.consumeAttr(o, "description");
+
+  // inheritance hierarchy rows (ancestors nearest-last so level increases downward) + self + direct children
+  const anc = g.ancestors(fqn);            // nearest-first
+  const hierarchy: HierRow[] = [];
+  anc.slice().reverse().forEach((n, i) => hierarchy.push({ name: n.name, href: g.relHref(dn.href, n.href), level: i, self: false }));
+  const selfLevel = anc.length;
+  hierarchy.push({ name: dn.name, href: "", level: selfLevel, self: true });
+  const kids = g.extendedBy(fqn).slice().sort((a, b) => a.name.localeCompare(b.name));
+  for (const k of kids) hierarchy.push({ name: k.name, href: g.relHref(dn.href, k.href), level: selfLevel + 1, self: false });
+  const inheritanceMermaid = hierarchy.length > 1
+    ? inheritanceTree(hierarchy.map((h) => ({ name: h.name, level: h.level, self: h.self }))) : undefined;
+
+  // storage: table vs view, generation, pk
+  let tableName: string | undefined, isView = false, pkHtml: string | undefined, generation = "";
+  for (const s of o.childrenOfType("source")) {
+    cov.consumeNode(s);
+    const t = s.attr("table"); if (t !== undefined) { cov.consumeAttr(s, "table"); tableName = String(t); }
+    const kind = s.attr("kind"); if (kind !== undefined) { cov.consumeAttr(s, "kind"); if (String(kind) === "view") isView = true; }
+  }
+  // indexes: identity (pk/secondary) + index.lookup with tuning detail
+  const indexes: IndexRow[] = [];
+  for (const id of o.childrenOfType("identity")) {
+    cov.consumeNode(id);
+    const flds = id.attr("fields"); if (flds !== undefined) cov.consumeAttr(id, "fields");
+    const fields = Array.isArray(flds) ? flds.join(", ") : String(flds ?? "");
+    if (id.subType === "primary") {
+      pkHtml = `<code>${esc(fields)}</code>`;
+      const gen = id.attr("generation"); if (gen !== undefined) { cov.consumeAttr(id, "generation"); generation = String(gen); }
+      indexes.push({ name: id.name, kind: "primary", fields, extra: "", unique: true });
+    } else if (id.subType === "secondary") {
+      indexes.push({ name: id.name, kind: "unique", fields, extra: "", unique: true });
+    } else if (id.subType === "reference") {
+      const ref = id.attr("references"); if (ref !== undefined) cov.consumeAttr(id, "references");
+      const enf = id.attr("enforce"); if (enf !== undefined) cov.consumeAttr(id, "enforce");
+      indexes.push({ name: id.name, kind: "fk", fields, extra: [ref ? `→ ${esc(String(ref))}` : "", enf === false || enf === "false" ? "logical" : ""].filter(Boolean).join(" · "), unique: false });
+    }
+  }
+  for (const ix of o.childrenOfType("index")) {
+    cov.consumeNode(ix);
+    const flds = ix.attr("fields"); if (flds !== undefined) cov.consumeAttr(ix, "fields");
+    const fields = Array.isArray(flds) ? flds.join(", ") : String(flds ?? "");
+    const extras: string[] = [];
+    for (const k of ["orders", "where", "expr", "using"]) {
+      const v = ix.attr(k); if (v !== undefined) { cov.consumeAttr(ix, k); extras.push(esc(`${k} ${Array.isArray(v) ? v.join(",") : v}`)); }
+    }
+    const uniq = ix.attr("unique"); if (uniq !== undefined) cov.consumeAttr(ix, "unique");
+    indexes.push({ name: ix.name, kind: "index", fields, extra: extras.join(" · "), unique: uniq === true || uniq === "true" });
+  }
+  indexes.sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
+
+  // validators: field-level shown as badges already; collect OBJECT-level here
+  const validators: ValidatorRow[] = [];
+  for (const v of o.childrenOfType("validator")) {
+    cov.consumeNode(v);
+    const at = (k: string) => { const x = v.attr(k); if (x !== undefined) cov.consumeAttr(v, k); return x; };
+    let rule = "";
+    if (v.subType === "comparison") rule = `${esc(String(at("left") ?? ""))} ${esc(String(at("op") ?? ""))} ${esc(String(at("right") ?? ""))}`;
+    else if (v.subType === "requiredWhen") rule = `${esc(String(at("field") ?? ""))} required when ${esc(String(at("when") ?? ""))} = ${esc(String(at("equals") ?? ""))}`;
+    else if (v.subType === "presentIff") rule = `${esc(String(at("field") ?? ""))} present iff ${esc(String(at("when") ?? ""))} = ${esc(String(at("equals") ?? ""))}`;
+    else if (v.subType === "atLeastOne") { const fs = at("fields"); rule = `at least one of ${esc(Array.isArray(fs) ? fs.map(String).join(", ") : String(fs ?? ""))}`; }
+    else rule = esc(v.subType);
+    validators.push({ scope: "object", subject: v.name || v.subType, rule });
+  }
+  validators.sort((a, b) => a.subject.localeCompare(b.subject));
+
+  // relationships
+  const relations: RelationRow[] = g.relationshipsOf(fqn).map((r) => {
+    const t = g.byFqn(r.toFqn);
+    return { name: r.name, toName: t?.name ?? r.toFqn, toHref: t ? g.relHref(dn.href, t.href) : "", cardinality: r.cardinality };
+  });
+  for (const rel of o.childrenOfType("relationship")) { cov.consumeNode(rel); cov.consumeAttr(rel, "objectRef"); cov.consumeAttr(rel, "cardinality"); }
+
+  // origin provenance
+  const origins: OriginRow[] = g.originsOf(fqn).map((r) => ({ field: r.field, from: esc(r.from), via: esc(r.via) }))
+    .sort((a, b) => a.field.localeCompare(b.field));
+  for (const f of o.childrenOfType("field")) for (const org of f.childrenOfType("origin")) { cov.consumeNode(org); cov.consumeAttr(org, "from"); cov.consumeAttr(org, "via"); }
+
+  // fields own vs inherited
+  const ownNames = new Set(o.ownChildren().filter((c) => c.type === "field").map((c) => c.name));
+  const ownFields: FieldRow[] = [], inheritedFields: FieldRow[] = [];
+  for (const f of o.childrenOfType("field")) {
+    const row = fieldRow(f, dn.href, g, cov, dn.pkg);
+    if (ownNames.has(f.name)) ownFields.push(row);
+    else {
+      for (let s = o.superResolved; s; s = s.superResolved) {
+        if (s.ownChildren().some((c) => c.type === "field" && c.name === f.name)) {
+          const t = g.byFqn(fqnOf(s));
+          row.inheritedFrom = t ? { name: t.name, href: g.relHref(dn.href, t.href) } : { name: s.name, href: "#" };
+          break;
+        }
+      }
+      inheritedFields.push(row);
+    }
+  }
+
+  // neighborhood diagram — rich (attrs + domain-fill/role-stroke) when small, simple domain map when large.
+  // Cap the neighbor count so hub entities (30+ neighbors) don't produce an unreadable megadiagram;
+  // the full set is always available in the Referenced-by / References sections below.
+  const NB_MAX = 16;
+  // include every traversal kind (fk, field.object, origin, relationship, extends) so projections and
+  // value objects are never orphaned; the dedicated Inheritance section still shows the full chain.
+  const nbCandidates = new Map<string, { node: typeof dn; edge: ErEdge }>();
+  for (const r of g.refsFrom(fqn)) { const t = g.byFqn(r.to); if (t && !nbCandidates.has(r.to)) nbCandidates.set(r.to, { node: t, edge: { parent: t.name, child: dn.name, label: edgeLabelFor(r), cardinality: r.cardinality } }); }
+  for (const r of g.refsTo(fqn)) { const s = g.byFqn(r.from); if (s && s.kind === "object" && !nbCandidates.has(r.from)) nbCandidates.set(r.from, { node: s, edge: { parent: dn.name, child: s.name, label: edgeLabelFor(r), cardinality: r.cardinality } }); }
+  const sortedNeighbors = [...nbCandidates.entries()].sort(([, a], [, b]) => a.node.name.localeCompare(b.node.name));
+  const neighborhoodMore = Math.max(0, sortedNeighbors.length - NB_MAX);
+  const nbNodes = new Map<string, typeof dn>(); const nbEdges: ErEdge[] = [];
+  nbNodes.set(fqn, dn);
+  for (const [k, { node, edge }] of sortedNeighbors.slice(0, NB_MAX)) { nbNodes.set(k, node); nbEdges.push(edge); }
+  const roleOf = (n: typeof dn): ErNode["role"] =>
+    fqnOf(n.node) === fqn ? "focal"
+      : n.node.childrenOfType("source").some((s) => String(s.attr("kind") ?? "") === "view") ? "view"
+      : n.pkg !== dn.pkg ? "external" : "normal";
+  let neighborhoodMermaid: string | undefined;
+  let neighborhoodLegend: { pkg: string; fill: string; stroke: string }[] | undefined;
+  if (nbEdges.length > 0) {
+    if (nbNodes.size <= RICH_MAX) {
+      const erNodes: ErNode[] = [...nbNodes.values()].map((n) => { const { attrs, more } = neighborAttrs(n.node); return { name: n.name, pkg: n.pkg, role: roleOf(n), kind: n.node.subType, attrs, more }; });
+      neighborhoodMermaid = erDiagramRich(erNodes, nbEdges);
+    } else {
+      const r = flowchartDomain([...nbNodes.values()].map((n) => ({ name: n.name, pkg: n.pkg, kind: n.node.subType })), nbEdges.map((e) => ({ from: e.parent, to: e.child, label: e.label, ...(e.cardinality === "many" ? { style: "dashed" as const } : {}) })));
+      neighborhoodMermaid = r.mermaid; neighborhoodLegend = r.legend;
+    }
+  }
+
+  // backlinks / forward refs (non-extends)
+  const referencedBy = g.refsTo(fqn).filter((r) => r.kind !== "extends").map((r) => { const s = g.byFqn(r.from)!; return { name: s.name, href: g.relHref(dn.href, s.href), via: r.via }; }).sort((a, b) => a.name.localeCompare(b.name) || a.via.localeCompare(b.via));
+  const references = g.refsFrom(fqn).filter((r) => r.kind !== "extends").map((r) => { const t = g.byFqn(r.to)!; return { name: t.name, href: g.relHref(dn.href, t.href), via: r.via }; }).sort((a, b) => a.name.localeCompare(b.name) || a.via.localeCompare(b.via));
+
+  // used-by templates (unchanged BFS)
+  const usedByTemplates: { name: string; href: string }[] = [];
+  for (const t of g.nodes().filter((n) => n.kind !== "object")) {
+    const seen = new Set<string>(); const q = g.refsFrom(fqnOf(t.node)).filter((r) => r.kind === "payload").map((r) => r.to); let hit = false;
+    while (q.length && seen.size < 100) { const cur = q.shift()!; if (seen.has(cur)) continue; seen.add(cur); if (cur === fqn) { hit = true; break; } for (const r of g.refsFrom(cur)) if (r.kind === "field") q.push(r.to); }
+    if (hit) usedByTemplates.push({ name: t.name, href: g.relHref(dn.href, t.href) });
+  }
+
+  const src = (o.source as { files?: string[] }).files?.[0] ?? "";
+  const crumbs = [
+    `<a href="${esc(g.relHref(dn.href, "index.html"))}">index</a>`,
+    `<a href="${esc(g.relHref(dn.href, `${dn.pkgPath}/index.html`))}">${esc(dn.pkg)}</a>`,
+    esc(dn.name),
+  ];
+  return {
+    name: dn.name, kindBadge: o.subType, isAbstract: o.isAbstract, isView, generation,
+    pkg: dn.pkg, href: dn.href, breadcrumbHtml: crumbs.join(" / "), desc: esc(o.attr("description") ?? ""),
+    tableName, pkHtml, ownFields, inheritedFields, indexes, validators, relations, origins,
+    hierarchy, inheritanceMermaid, neighborhoodMermaid, neighborhoodLegend, neighborhoodMore, referencedBy, references, usedByTemplates, sourceFile: src,
+  };
+}

package/src/builders/output-data.ts

@@ -0,0 +1,35 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { LinkGraph } from "../link-graph";
+import type { CoverageTracker } from "../coverage";
+import type { CommentDocs } from "../yaml-comments";
+import { esc } from "../badges";
+
+export interface OutputPageData { name: string; pkg: string; href: string; breadcrumbHtml: string; format: string; kind: string; textRef: string; textRefResolves: boolean; payloadName: string; payloadHref: string; desc: string; fields: { name: string; type: string; isArray: boolean; wire: string; note: string; refHtml: string }[]; }
+
+export function buildOutputPage(fqn: string, g: LinkGraph, cov: CoverageTracker, docs: CommentDocs, sourceDirs: string[] = []): OutputPageData {
+  const dn = g.byFqn(fqn)!;
+  const t = dn.node;
+  cov.consumeNode(t); cov.consumeAttr(t, "payloadRef"); cov.consumeAttr(t, "textRef"); cov.consumeAttr(t, "format");
+  const format = String(t.attr("format") ?? "text");
+  const pRef = g.refsFrom(fqn).find((r) => r.kind === "payload");
+  const payload = pRef ? g.byFqn(pRef.to) : undefined;
+  const fields = (payload?.node.childrenOfType("field") ?? []).map((f) => {
+    const ref = f.attr("objectRef");
+    const target = typeof ref === "string" ? (g.byFqn(ref.includes("::") ? ref : `${dn.pkg}::${ref}`) ?? g.byFqn(ref)) : undefined;
+    const hasXmlText = f.attr("xmlText") !== undefined;
+    const wire = hasXmlText ? "@xmlText body" : target ? "nested" : format === "xml" ? (f.resolvedIsArray() ? "element" : "attr") : "property";
+    const noteAttr = f.attr("description");
+    const note = esc(noteAttr ?? docs.fieldNote.get(`${payload!.name}.${f.name}`) ?? "");
+    if (noteAttr !== undefined) cov.consumeAttr(f, "description");
+    return { name: f.name, type: f.subType, isArray: f.resolvedIsArray(), wire, note,
+      refHtml: target ? `<a href="${esc(g.relHref(dn.href, target.href))}" class="link">${esc(target.name)}</a>` : "" };
+  });
+  const textRef = String(t.attr("textRef") ?? "");
+  const textRefResolves = sourceDirs.some((d) => existsSync(join(d, ...textRef.split("/")) + ".mustache"));
+  return { name: dn.name, pkg: dn.pkg, href: dn.href,
+    breadcrumbHtml: `<a href="${esc(g.relHref(dn.href, "index.html"))}">index</a> / <a href="${esc("index.html")}">${esc(dn.pkg)}</a> / ${esc(dn.name)}`,
+    format, kind: String(t.attr("kind") ?? "document"), textRef, textRefResolves,
+    payloadName: payload?.name ?? "", payloadHref: payload ? esc(g.relHref(dn.href, payload.href)) : "",
+    desc: payload ? esc(payload.node.attr("description") ?? docs.objectDesc.get(payload.name) ?? "") : "", fields };
+}

package/src/builders/package-data.ts

@@ -0,0 +1,134 @@
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { LinkGraph, fqnOf } from "../link-graph";
+import type { CoverageTracker } from "../coverage";
+import { esc } from "../badges";
+import { erDiagramRich, flowchartDomain, domainColor, RICH_MAX, type ErEdge, type ErAttr, type ErNode } from "../mermaid";
+import { harvestPackageDocs, keyEntities } from "../package-docs";
+
+// capped box attributes for the rich package ERD: PK → FKs(target) → enums → required, ≤6 + overflow count
+// (mirrors neighborAttrs in object-data.ts — kept local to avoid cross-builder coupling)
+function pkgAttrs(o: MetaData): { attrs: ErAttr[]; more: number } {
+  const pk = new Set<string>(), fk = new Map<string, string>();
+  for (const id of o.childrenOfType("identity")) {
+    const flds = id.attr("fields");
+    const names = Array.isArray(flds) ? flds.map(String) : flds !== undefined ? [String(flds)] : [];
+    if (id.subType === "primary") names.forEach((n) => pk.add(n));
+    if (id.subType === "reference") { const tgt = String(id.attr("references") ?? "").split("::").pop() ?? ""; names.forEach((n) => fk.set(n, tgt)); }
+  }
+  const fields = o.childrenOfType("field");
+  const isEnum = (f: MetaData) => Array.isArray(f.attr("values"));
+  const isReq = (f: MetaData) => f.attr("required") === true || f.attr("required") === "true";
+  const attrs: ErAttr[] = []; const seen = new Set<string>();
+  const push = (f: MetaData, key: ErAttr["key"], note: string) => { if (seen.has(f.name) || attrs.length >= 6) return; seen.add(f.name); attrs.push({ type: f.subType, name: f.name, key, note }); };
+  for (const f of fields) if (pk.has(f.name)) push(f, "PK", "");
+  for (const f of fields) if (fk.has(f.name)) push(f, "FK", fk.get(f.name)!);
+  for (const f of fields) if (isEnum(f)) push(f, "", "enum");
+  for (const f of fields) if (isReq(f)) push(f, "", "req");
+  const relevant = fields.filter((f) => pk.has(f.name) || fk.has(f.name) || isEnum(f) || isReq(f)).length;
+  return { attrs, more: Math.max(0, relevant - attrs.length) };
+}
+
+export interface ObjRow { name: string; href: string; kind: string; table: string; fieldCount: number; extendsName: string; }
+export interface TplRow { name: string; href: string; payloadName: string; payloadHref: string; format: string; textRef: string; }
+export interface PackagePageData {
+  pkg: string; pkgPath: string; tree: string; breadcrumbHtml: string;
+  title: string; descHtml: string;
+  keyCards: { name: string; href: string; inbound: number }[];
+  erdMermaid: string; erdLegend: { pkg: string; fill: string; stroke: string }[];
+  abstracts: ObjRow[]; objects: ObjRow[]; prompts: TplRow[]; outputs: TplRow[];
+  referencedBy: { pkg: string; href: string; n: number }[];
+}
+
+export function buildPackagePage(pkg: string, g: LinkGraph, cov: CoverageTracker, sourceDirs?: string[]): PackagePageData {
+  const dirs = sourceDirs ?? [];
+  const members = g.nodes().filter((n) => n.pkg === pkg);
+  const pageHref = `${members[0]!.pkgPath}/index.html`;
+  const objRow = (n: (typeof members)[0]): ObjRow => ({
+    name: n.name, href: `${n.name}.html`, kind: n.node.subType,
+    table: String(n.node.childrenOfType("source").map((s) => s.attr("table")).find((t) => t !== undefined) ?? ""),
+    fieldCount: n.node.childrenOfType("field").length,
+    extendsName: n.node.superResolved?.name ?? "",
+  });
+  const tplRow = (n: (typeof members)[0]): TplRow => {
+    cov.consumeNode(n.node); cov.consumeAttr(n.node, "payloadRef"); cov.consumeAttr(n.node, "textRef"); cov.consumeAttr(n.node, "format");
+    const p = g.refsFrom(fqnOf(n.node)).find((r) => r.kind === "payload");
+    const pt = p ? g.byFqn(p.to) : undefined;
+    return { name: n.name, href: `${n.name}.html`, payloadName: pt?.name ?? String(n.node.attr("payloadRef") ?? ""), payloadHref: pt ? g.relHref(pageHref, pt.href) : "", format: String(n.node.attr("format") ?? "text"), textRef: String(n.node.attr("textRef") ?? "") };
+  };
+  const objs = members.filter((m) => m.kind === "object");
+  const abstracts = objs.filter((m) => m.node.isAbstract).map(objRow).sort((a, b) => a.name.localeCompare(b.name));
+  const objects = objs.filter((m) => !m.node.isAbstract).map(objRow).sort((a, b) => a.name.localeCompare(b.name));
+  const prompts = members.filter((m) => m.kind === "prompt").map(tplRow).sort((a, b) => a.name.localeCompare(b.name));
+  const outputs = members.filter((m) => m.kind === "output").map(tplRow).sort((a, b) => a.name.localeCompare(b.name));
+
+  // authored prose + key-entity cards
+  const pd = harvestPackageDocs(dirs).get(pkg);
+  const title = esc(pd?.title ?? pkg.split("::").pop() ?? pkg);
+  const descHtml = esc(pd?.description ?? "");
+  const keyCards = keyEntities(pkg, g).map((k) => ({ name: k.name, href: g.relHref(pageHref, k.href), inbound: k.inbound }));
+
+  // package ERD — collect internal objects + external neighbor objects + edges
+  const extNodes = new Map<string, typeof members[0]>();
+  const erdEdges: ErEdge[] = [];
+  for (const m of objs) {
+    for (const r of g.refsFrom(fqnOf(m.node))) {
+      if (r.kind === "extends") continue;
+      const t = g.byFqn(r.to); if (!t || t.kind !== "object") continue;
+      erdEdges.push({ parent: t.name, child: m.name, label: r.via });
+      if (t.pkg !== pkg) extNodes.set(r.to, t);
+    }
+    for (const r of g.refsTo(fqnOf(m.node))) {
+      if (r.kind === "extends") continue;
+      const s = g.byFqn(r.from); if (!s || s.kind !== "object" || s.pkg === pkg) continue;
+      erdEdges.push({ parent: m.name, child: s.name, label: r.via });
+      extNodes.set(r.from, s);
+    }
+  }
+  // deduplicate edges
+  const deduped = erdEdges.filter((e, i) => erdEdges.findIndex((x) => x.parent === e.parent && x.child === e.child && x.label === e.label) === i);
+
+  // mode switch: rich (≤RICH_MAX) vs domain flowchart (large)
+  const totalNodes = objs.length + extNodes.size;
+  let erdMermaid: string;
+  let erdLegend: { pkg: string; fill: string; stroke: string }[] = [];
+  if (totalNodes <= RICH_MAX) {
+    const erNodes: ErNode[] = [
+      ...objs.map((m) => { const { attrs, more } = pkgAttrs(m.node); return { name: m.name, pkg: m.pkg, role: "normal" as ErNode["role"], kind: m.node.subType, attrs, more }; }),
+      ...[...extNodes.values()].map((m) => { const { attrs, more } = pkgAttrs(m.node); return { name: m.name, pkg: m.pkg, role: "external" as ErNode["role"], kind: m.node.subType, attrs, more }; }),
+    ];
+    erdMermaid = erDiagramRich(erNodes, deduped);
+    // build legend from unique packages
+    const pkgsSeen = new Map<string, typeof erdLegend[0]>();
+    for (const n of erNodes) {
+      if (!pkgsSeen.has(n.pkg)) {
+        const dc = domainColor(n.pkg);
+        pkgsSeen.set(n.pkg, { pkg: n.pkg, fill: dc.fill, stroke: dc.stroke });
+      }
+    }
+    erdLegend = [...pkgsSeen.values()].sort((a, b) => a.pkg.localeCompare(b.pkg));
+  } else {
+    const flowNodes = [
+      ...objs.map((m) => ({ name: m.name, pkg: m.pkg, kind: m.node.subType })),
+      ...[...extNodes.values()].map((m) => ({ name: m.name, pkg: m.pkg, kind: m.node.subType })),
+    ];
+    const r = flowchartDomain(flowNodes, deduped.map((e) => ({ from: e.parent, to: e.child, label: e.label })));
+    erdMermaid = r.mermaid;
+    erdLegend = r.legend;
+  }
+
+  // inbound package backlinks
+  const inbound = new Map<string, number>();
+  for (const m of objs) for (const r of g.refsTo(fqnOf(m.node))) {
+    const s = g.byFqn(r.from);
+    if (s && s.pkg !== pkg && r.kind !== "extends") inbound.set(s.pkg, (inbound.get(s.pkg) ?? 0) + 1);
+  }
+  const referencedBy = [...inbound.entries()].sort().map(([p, n]) => ({ pkg: p, href: g.relHref(pageHref, `${p.split("::").join("/")}/index.html`), n }));
+
+  return {
+    pkg, pkgPath: members[0]!.pkgPath, tree: members[0]!.tree,
+    breadcrumbHtml: `<a href="${g.relHref(pageHref, "index.html")}">index</a> / ${esc(pkg)}`,
+    title, descHtml, keyCards,
+    erdMermaid, erdLegend,
+    abstracts, objects, prompts, outputs, referencedBy,
+  };
+}

package/src/builders/prompt-data.ts

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { LinkGraph } from "../link-graph";
+import type { CoverageTracker } from "../coverage";
+import { highlightMustache } from "../mustache-highlight";
+import { esc } from "../badges";
+
+export interface PayloadTreeRow { indent: number; name: string; type: string; isArray: boolean; anchor: string; desc: string; refHtml: string; }
+export interface PromptPageData { name: string; pkg: string; href: string; breadcrumbHtml: string; attrsHtml: string; desc: string; payloadName: string; payloadHref: string; payloadTree: PayloadTreeRow[]; sourceHtml?: string | undefined; sourceMissingNote?: string | undefined; tocHtml?: string | undefined; packageFiles: { file: string; html: string }[]; }
+
+export function buildPromptPage(fqn: string, g: LinkGraph, cov: CoverageTracker, sourceDirs: string[]): PromptPageData {
+  const dn = g.byFqn(fqn)!;
+  const t = dn.node;
+  cov.consumeNode(t);
+  const attrs: string[] = [];
+  for (const a of ["format", "maxTokens", "requiredSlots", "model", "responseRef", "maxChars", "promptStyle"]) {
+    const v = t.attr(a); if (v !== undefined) { cov.consumeAttr(t, a); attrs.push(`<span class="badge badge-ghost badge-sm">@${esc(a)} ${esc(v)}</span>`); }
+  }
+  cov.consumeAttr(t, "payloadRef"); cov.consumeAttr(t, "textRef");
+  // payload tree (root + one nested level)
+  const pRef = g.refsFrom(fqn).find((r) => r.kind === "payload");
+  const payload = pRef ? g.byFqn(pRef.to) : undefined;
+  const tree: PayloadTreeRow[] = [];
+  const fieldsOf = (o: NonNullable<typeof payload>, indent: number, prefix: string) => {
+    for (const f of o.node.childrenOfType("field")) {
+      const ref = f.attr("objectRef");
+      const target = typeof ref === "string" ? (g.byFqn(ref.includes("::") ? ref : `${o.pkg}::${ref}`) ?? g.byFqn(ref)) : undefined;
+      tree.push({ indent, name: prefix + f.name, type: f.subType, isArray: f.resolvedIsArray(), anchor: `f-${prefix}${f.name}`,
+        desc: esc(f.attr("description") ?? ""),
+        refHtml: target ? `<a href="${esc(g.relHref(dn.href, target.href))}" class="link">${esc(target.name)}</a>` : "" });
+      if (target && indent === 0) fieldsOf(target, 1, `${f.name}.`);
+    }
+  };
+  if (payload) fieldsOf(payload, 0, "");
+  const anchors = new Map(tree.map((r) => [r.name, `#${r.anchor}`]));
+  // source resolution
+  const textRef = String(t.attr("textRef") ?? "");
+  let sourceHtml: string | undefined, tocHtml: string | undefined, sourceMissingNote: string | undefined;
+  let pkgDir: string | undefined;
+  for (const d of sourceDirs) {
+    const p = join(d, ...textRef.split("/")) + ".mustache";
+    if (existsSync(p)) { pkgDir = dirname(p);
+      const r = highlightMustache(readFileSync(p, "utf8"), (path) => anchors.get(path));
+      sourceHtml = r.html;
+      tocHtml = r.toc.map((s) => `<a href="#${esc(s.anchor)}" class="link">${esc(s.name)}</a>`).join(" · ");
+      break;
+    }
+  }
+  if (!sourceHtml) sourceMissingNote = `text ref ${esc(textRef)} does not resolve under the metadata roots (forward-pointing ref).`;
+  // other mustache files in the template's package dir
+  const packageFiles: { file: string; html: string }[] = [];
+  if (pkgDir) for (const f of readdirSync(pkgDir).filter((f) => f.endsWith(".mustache")).sort()) {
+    if (join(pkgDir, f) === join(pkgDir, `${textRef.split("/").pop()}.mustache`)) continue;
+    packageFiles.push({ file: f, html: highlightMustache(readFileSync(join(pkgDir, f), "utf8"), (p) => anchors.get(p)).html });
+  }
+  return { name: dn.name, pkg: dn.pkg, href: dn.href,
+    breadcrumbHtml: `<a href="${esc(g.relHref(dn.href, "index.html"))}">index</a> / <a href="${esc("index.html")}">${esc(dn.pkg)}</a> / ${esc(dn.name)}`,
+    attrsHtml: attrs.join(" "), desc: esc(t.attr("description") ?? ""),
+    payloadName: payload?.name ?? "", payloadHref: payload ? esc(g.relHref(dn.href, payload.href)) : "",
+    payloadTree: tree, sourceHtml, sourceMissingNote, tocHtml, packageFiles };
+}

package/src/coverage.ts

@@ -0,0 +1,29 @@
+import type { MetaData, MetaRoot } from "@metaobjectsdev/metadata";
+
+export interface CoverageRow { key: string; count: number; consumed: boolean; }
+export interface CoverageReport { kinds: CoverageRow[]; attrs: CoverageRow[]; warnings: string[]; }
+
+export class CoverageTracker {
+  private kinds = new Set<string>();
+  private attrs = new Set<string>();
+  consumeNode(n: MetaData): void { this.kinds.add(`${n.type}.${n.subType}`); }
+  consumeAttr(n: MetaData, a: string): void { this.attrs.add(`${n.type}:@${a}`); }
+  report(root: MetaRoot): CoverageReport {
+    const kindCount = new Map<string, number>();
+    const attrCount = new Map<string, number>();
+    const walk = (n: MetaData) => {
+      kindCount.set(`${n.type}.${n.subType}`, (kindCount.get(`${n.type}.${n.subType}`) ?? 0) + 1);
+      for (const [name] of n.ownAttrs()) {
+        attrCount.set(`${n.type}:@${name}`, (attrCount.get(`${n.type}:@${name}`) ?? 0) + 1);
+      }
+      for (const c of n.ownChildren()) walk(c);
+    };
+    for (const c of root.ownChildren()) walk(c);
+    const rows = (m: Map<string, number>, seen: Set<string>) =>
+      [...m.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([key, count]) => ({ key, count, consumed: seen.has(key) }));
+    const kinds = rows(kindCount, this.kinds);
+    const attrs = rows(attrCount, this.attrs);
+    const warnings = [...kinds, ...attrs].filter((r) => !r.consumed).map((r) => `coverage: ${r.key} (${r.count}) not rendered by any page`);
+    return { kinds, attrs, warnings };
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { generateSite } from "./site";
+export type { SiteOptions, SiteResult } from "./site";
+export { SITE_TEMPLATE_NAMES, SITE_ASSET_NAMES, readSiteFile } from "./scaffold";

package/src/link-check.ts

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, normalize } from "node:path";
+
+export function checkLinks(outDir: string, pages: string[]): string[] {
+  const errs: string[] = [];
+  const idCache = new Map<string, Set<string>>();
+  const idsOf = (p: string) => {
+    if (!idCache.has(p)) idCache.set(p, new Set([...readFileSync(p, "utf8").matchAll(/id="([^"]+)"/g)].map((m) => m[1]!)));
+    return idCache.get(p)!;
+  };
+  for (const page of pages) {
+    const html = readFileSync(join(outDir, page), "utf8");
+    for (const m of html.matchAll(/href="([^"]+)"/g)) {
+      const href = m[1]!;
+      if (/^(https?:|mailto:|#$)/.test(href)) continue;
+      const [file = "", anchor] = href.split("#");
+      const target = file === "" ? page : normalize(join(dirname(page), file));
+      const abs = join(outDir, target);
+      if (!existsSync(abs)) { errs.push(`${page} -> ${href}`); continue; }
+      if (anchor && !idsOf(abs).has(anchor)) errs.push(`${page} -> ${href}`);
+    }
+  }
+  return errs;
+}