@metaobjectsdev/docs-site 1.0.13 → 1.1.0

package/src/link-graph.ts

@@ -1,11 +1,17 @@
-import type { MetaData, MetaObject, MetaRelationship } from "@metaobjectsdev/metadata";
-import { deriveM2MFields, resolveRelationshipReference, stripPackage } from "@metaobjectsdev/metadata";
+import type { MetaData, MetaObject, MetaRelationship, MetaRoot } from "@metaobjectsdev/metadata";
+import {
+  deriveM2MFields, resolveRelationshipReference,
+  OBJECT_REPORT_ATTR_FROM, OBJECT_SUBTYPE_REPORT, TYPE_OBJECT,
+  RELATIONSHIP_ATTR_OBJECT_REF, RELATIONSHIP_ATTR_THROUGH, IDENTITY_REFERENCE_ATTR_REFERENCES,
+  FIELD_ATTR_OBJECT_REF, ORIGIN_PASSTHROUGH_ATTR_FROM, TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_RESPONSE_REF,
+  refTarget,
+} from "@metaobjectsdev/metadata";
 import { type LoadedModel, treeOf } from "./load.js";
 
 export interface DocNode { kind: "object" | "prompt" | "output"; name: string; pkg: string; pkgPath: string; href: string; node: MetaData; tree: string; }
 export interface Ref {
   from: string; to: string; via: string;
-  kind: "field" | "fk" | "extends" | "payload" | "response" | "relationship" | "origin";
+  kind: "field" | "fk" | "extends" | "payload" | "response" | "relationship" | "origin" | "report";
   cardinality?: "one" | "many" | undefined;
   through?: string | undefined;         // junction FQN (M:N)
   sourceJoinField?: string | undefined; // junction source FK (M:N)
@@ -30,8 +36,11 @@ export class LinkGraph {
   private _to = new Map<string, Ref[]>();
   private _extBy = new Map<string, DocNode[]>();
   private _origins = new Map<string, OriginRef[]>();
+  /** The loaded root the graph was built from (a report's derived columns resolve against it). */
+  readonly root: MetaRoot;
 
   constructor(model: LoadedModel) {
+    this.root = model.root;
     for (const o of model.root.ownChildren()) {
       let kind: DocNode["kind"] | undefined;
       if (o.type === "object") kind = "object";
@@ -48,16 +57,20 @@ export class LinkGraph {
       (this._from.get(r.from) ?? this._from.set(r.from, []).get(r.from)!).push(r);
       (this._to.get(r.to) ?? this._to.set(r.to, []).get(r.to)!).push(r);
     };
-    const resolveRef = (raw: string, ctxPkg: string): string | undefined => {
-      const cand = raw.includes("::") ? raw : `${ctxPkg}::${raw}`;
-      return this._nodes.has(cand) ? cand : (this._nodes.has(raw) ? raw : undefined);
+    // ADR-0059 R7 — an edge points at the object the reference attribute is bound to,
+    // resolved where the attribute was declared, never re-resolved in an inheritor's package.
+    const bound = (node: MetaData, attr: string): string | undefined => {
+      const target = refTarget(node, attr);
+      if (target === undefined) return undefined;
+      const key = fqnOf(target);
+      return this._nodes.has(key) ? key : undefined;
     };
     // M:N through-junction edge. Derives the junction FK fields via the metadata
     // SSOT (deriveM2MFields) — hetero, directed (@sourceRefField), or symmetric
     // (@symmetric). On a derivation failure (ambiguous self-join) the edge is
     // SKIPPED — generation never fails.
-    const addM2mEdge = (from: string, to: string, rel: MetaRelationship, obj: MetaObject, ctxPkg: string, onDelete: string | undefined, subtype: string | undefined): void => {
-      const through = rel.through ? (resolveRef(rel.through, ctxPkg) ?? rel.through) : undefined;
+    const addM2mEdge = (from: string, to: string, rel: MetaRelationship, obj: MetaObject, onDelete: string | undefined, subtype: string | undefined): void => {
+      const through = rel.through ? (bound(rel, RELATIONSHIP_ATTR_THROUGH) ?? rel.through) : undefined;
       let sourceJoinField: string | undefined, targetJoinField: string | undefined;
       try {
         const f = deriveM2MFields(rel, obj, model.root);
@@ -72,11 +85,8 @@ export class LinkGraph {
       const fqn = fqnOf(dn.node);
       if (dn.kind === "object") {
         for (const f of dn.node.childrenOfType("field")) {
-          const ref = f.attr("objectRef");
-          if (typeof ref === "string") {
-            const to = resolveRef(ref, dn.pkg);
-            if (to) addRef({ from: fqn, to, via: f.name, kind: "field" });
-          }
+          const to = bound(f, FIELD_ATTR_OBJECT_REF);
+          if (to) addRef({ from: fqn, to, via: f.name, kind: "field" });
         }
         // dn.node is typed MetaData; the enclosing dn.kind === "object" guard
         // guarantees it is a MetaObject at runtime. The `unknown` bridge is needed
@@ -88,15 +98,13 @@ export class LinkGraph {
         // reference whose (target, first-field) a belongs-to relationship covered.
         const coveredFk = new Set<string>();
         for (const rel of obj.relationships()) {
-          const objectRef = rel.objectRef;
-          if (typeof objectRef !== "string") continue;
-          const to = resolveRef(objectRef, dn.pkg);
+          const to = bound(rel, RELATIONSHIP_ATTR_OBJECT_REF);
           if (!to) continue;
           const cardinality = rel.cardinality === "many" ? "many" : rel.cardinality === "one" ? "one" : undefined;
           const onDelete = rel.onDelete;
           const subtype = rel.subType;
           if (cardinality === "many" && rel.through !== undefined) {
-            addM2mEdge(fqn, to, rel, obj, dn.pkg, onDelete, subtype);   // Task 3 helper
+            addM2mEdge(fqn, to, rel, obj, onDelete, subtype);   // Task 3 helper
             continue;
           }
           // belongs-to (1:N, one) — resolve the identity.reference this relationship
@@ -109,38 +117,39 @@ export class LinkGraph {
           // uses; ambiguous cases resolve to undefined and simply leave every candidate
           // reference to draw its own "fk" edge, which is the safe (extra-info, not
           // missing-edge) outcome for a docs graph.
-          const target = stripPackage(objectRef);
-          const match = resolveRelationshipReference(obj, rel.name, target, rel.sourceRefField);
+          const match = resolveRelationshipReference(
+            obj, rel.name, refTarget(rel, RELATIONSHIP_ATTR_OBJECT_REF), rel.sourceRefField,
+          );
           const fkField = match?.fields?.[0];
           if (fkField) coveredFk.add(`${to}::${fkField}`);
           addRef({ from: fqn, to, via: rel.name, kind: "relationship", cardinality, onDelete, subtype });
         }
         for (const id of dn.node.childrenOfType("identity")) {
           if (id.subType !== "reference") continue;
-          const ref = id.attr("references");
-          if (typeof ref === "string") {
-            const to = resolveRef(ref, dn.pkg);
-            if (to) {
-              const fieldsValue = id.attr("fields") ?? id.name;
-              const firstField = Array.isArray(fieldsValue) ? String(fieldsValue[0] ?? "") : String(fieldsValue);
-              if (coveredFk.has(`${to}::${firstField}`)) continue;   // superseded by a relationship edge
-              const via = Array.isArray(fieldsValue) ? fieldsValue.join(", ") : String(fieldsValue);
-              addRef({ from: fqn, to, via, kind: "fk" });
-            }
-          }
+          const to = bound(id, IDENTITY_REFERENCE_ATTR_REFERENCES);
+          if (!to) continue;
+          const fieldsValue = id.attr("fields") ?? id.name;
+          const firstField = Array.isArray(fieldsValue) ? String(fieldsValue[0] ?? "") : String(fieldsValue);
+          if (coveredFk.has(`${to}::${firstField}`)) continue;   // superseded by a relationship edge
+          const via = Array.isArray(fieldsValue) ? fieldsValue.join(", ") : String(fieldsValue);
+          addRef({ from: fqn, to, via, kind: "fk" });
         }
         for (const f of dn.node.childrenOfType("field")) {
           for (const org of f.childrenOfType("origin")) {
             const from = String(org.attr("from") ?? ""), via = String(org.attr("via") ?? "");
             (this._origins.get(fqn) ?? this._origins.set(fqn, []).get(fqn)!).push({ field: f.name, from, via });
             // connect a projection to its source object so it is not orphaned on diagrams:
-            // `from` is "pkg::Entity.field" — strip the trailing ".field" to get the source object ref.
-            const dot = from.lastIndexOf(".");
-            const srcRef = dot > 0 ? from.slice(0, dot) : "";
-            const to = srcRef ? resolveRef(srcRef, dn.pkg) : undefined;
+            // `from` is "pkg::Entity.field"; its bound target is the source object.
+            const to = bound(org, ORIGIN_PASSTHROUGH_ATTR_FROM);
             if (to && to !== fqn) addRef({ from: fqn, to, via: `${f.name} (origin)`, kind: "origin" });
           }
         }
+        // FR-044: a report reads from its @from entity. The edge is what puts the report on
+        // that entity's page and diagrams, and keeps a report from reading as an orphan.
+        if (dn.node.type === TYPE_OBJECT && dn.node.subType === OBJECT_SUBTYPE_REPORT) {
+          const to = bound(dn.node, OBJECT_REPORT_ATTR_FROM);
+          if (to) addRef({ from: fqn, to, via: OBJECT_REPORT_ATTR_FROM, kind: "report" });
+        }
         const sup = dn.node.superResolved;
         if (sup) {
           const supFqn = fqnOf(sup);
@@ -148,18 +157,12 @@ export class LinkGraph {
           (this._extBy.get(supFqn) ?? this._extBy.set(supFqn, []).get(supFqn)!).push(dn);
         }
       } else {
-        const p = dn.node.attr("payloadRef");
-        if (typeof p === "string") {
-          const to = resolveRef(p, dn.pkg);
-          if (to) addRef({ from: fqn, to, via: "payloadRef", kind: "payload" });
-        }
+        const toPayload = bound(dn.node, TEMPLATE_ATTR_PAYLOAD_REF);
+        if (toPayload) addRef({ from: fqn, to: toPayload, via: "payloadRef", kind: "payload" });
         // A prompt's @responseRef is the response value-object it PRODUCES — the
         // missing hop of the data-flow pipeline (prompt → response VO → entity).
-        const r = dn.node.attr("responseRef");
-        if (typeof r === "string") {
-          const to = resolveRef(r, dn.pkg);
-          if (to) addRef({ from: fqn, to, via: "responseRef", kind: "response" });
-        }
+        const toResponse = bound(dn.node, TEMPLATE_ATTR_RESPONSE_REF);
+        if (toResponse) addRef({ from: fqn, to: toResponse, via: "responseRef", kind: "response" });
       }
     }
   }

package/src/site.ts

@@ -189,6 +189,7 @@ export async function generateSite(opts: SiteOptions): Promise<SiteResult> {
   const objectTocHtml = (d: ObjectPageData): string => {
     const sections: { id: string; label: string; present: boolean }[] = [
       { id: "s-overview", label: "Overview", present: !!d.desc },
+      { id: "s-report", label: "Report", present: d.report !== undefined },
       { id: "s-fields", label: "Fields", present: d.ownFields.length > 0 },
       { id: "s-indexes", label: "Indexes &amp; keys", present: d.indexes.length > 0 },
       { id: "s-validators", label: "Validators", present: d.validators.length > 0 },
@@ -196,6 +197,7 @@ export async function generateSite(opts: SiteOptions): Promise<SiteResult> {
       { id: "s-provenance", label: "Field provenance", present: d.origins.length > 0 },
       { id: "s-inheritance", label: "Inheritance", present: !!d.inheritanceMermaid },
       { id: "s-neighborhood", label: "Neighborhood", present: !!d.neighborhoodMermaid },
+      { id: "s-reporting", label: "Reporting", present: d.reporting !== undefined },
       { id: "s-referenced-by", label: "Referenced by", present: d.referencedBy.length > 0 },
     ];
     return sections

package/templates/chrome-foot.mustache

@@ -11,7 +11,7 @@
   </div>
   <form method="dialog" class="modal-backdrop"><button>close</button></form>
 </dialog>
-<footer class="pl-footer text-xs opacity-40 px-10 pb-6">generated {{stamp}} · {{commit}} · metadata-docs</footer>
+<footer class="pl-footer text-xs opacity-40 px-10 pb-6">generated{{#stamp}} {{stamp}}{{/stamp}}{{#commit}} · {{commit}}{{/commit}} · metadata-docs</footer>
 <script>window.__REL_ROOT__ = "{{relRoot}}";</script>
 <script src="{{relRoot}}assets/site.js"></script>
 </body></html>

package/templates/object.html.mustache

@@ -8,8 +8,16 @@
   {{#pkHtml}} · pk {{{pkHtml}}}{{/pkHtml}}{{#generation}} · gen {{generation}}{{/generation}}{{#storageAttrs}} · {{name}} <code>{{value}}</code>{{/storageAttrs}}</div>
 {{#desc}}<section id="s-overview" class="mt-4"><p class="text-sm leading-relaxed">{{desc}}</p></section>{{/desc}}
 {{#objectAttrs.length}}<section id="s-attributes" class="mt-4 text-xs"><span class="opacity-50 mr-1">attributes</span>{{#objectAttrs}}<span class="badge badge-soft badge-ghost badge-xs mr-1 font-mono">@{{name}}={{value}}</span>{{/objectAttrs}}</section>{{/objectAttrs.length}}
+{{#report}}
+<section id="s-report" class="mt-6"><h2 class="text-lg font-semibold">Report</h2>
+<div class="font-mono text-xs opacity-70 mt-1">from <a class="link font-mono" href="{{fromHref}}">{{fromName}}</a>{{#viewName}} · view <code>{{viewName}}</code>{{/viewName}}{{#notServed}} · <span class="badge badge-soft badge-warning badge-xs">{{notServed}}</span>{{/notServed}}{{#rowsHtml}} · rows: {{{rowsHtml}}}{{/rowsHtml}}{{#scopeHtml}} · row scope {{{scopeHtml}}}{{/scopeHtml}}</div>
+<div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Column</th><th>Type</th><th>Nullable</th><th>Role</th><th>Definition</th></tr></thead><tbody>
+{{#columns}}<tr><td class="font-mono">{{name}}</td><td class="opacity-60">{{type}}</td><td class="opacity-60">{{nullable}}</td><td class="opacity-60">{{role}}</td><td class="text-xs">{{{definitionHtml}}}</td></tr>
+{{/columns}}
+</tbody></table></div></section>
+{{/report}}
 
-<section id="s-fields" class="mt-6"><h2 class="text-lg font-semibold">Fields</h2>
+{{^report}}<section id="s-fields" class="mt-6"><h2 class="text-lg font-semibold">Fields</h2>
 <div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Field</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody>
 {{#ownFields}}<tr id="{{anchor}}"><td class="font-mono">{{name}}{{#isArray}}[]{{/isArray}}</td><td class="opacity-60">{{type}}</td><td>{{{badgesHtml}}}</td><td class="text-xs">{{desc}}</td></tr>
 {{#enumValues.length}}<tr><td></td><td colspan="3" class="pl-4">{{#enumValues}}<span class="badge badge-soft badge-accent badge-xs mr-1">{{value}}{{#deflt}} ★{{/deflt}}</span>{{/enumValues}}</td></tr>{{/enumValues.length}}
@@ -18,7 +26,7 @@
 </tbody></table></div>
 {{#inheritedFields.length}}<div class="collapse collapse-arrow bg-base-100 border border-base-300 mt-2"><input type="checkbox"><div class="collapse-title text-sm font-semibold opacity-70">Inherited fields ({{inheritedFields.length}})</div><div class="collapse-content"><table class="table table-xs opacity-80"><tbody>
 {{#inheritedFields}}<tr id="{{anchor}}"><td class="font-mono">{{name}}{{#isArray}}[]{{/isArray}} <span class="text-[10px] opacity-50">↑ <a class="link" href="{{inheritedFrom.href}}">{{inheritedFrom.name}}</a></span></td><td class="opacity-60">{{type}}</td><td>{{{badgesHtml}}}</td></tr>{{/inheritedFields}}
-</tbody></table></div></div>{{/inheritedFields.length}}</section>
+</tbody></table></div></div>{{/inheritedFields.length}}</section>{{/report}}
 
 {{#indexes.length}}<section id="s-indexes" class="mt-6"><h2 class="text-lg font-semibold">Indexes &amp; keys</h2>
 <table class="table table-xs"><thead><tr><th>Name</th><th>Kind</th><th>Fields</th><th>Detail</th></tr></thead><tbody>
@@ -46,6 +54,14 @@
 <div class="text-[11px] opacity-50 mt-1"><span class="font-mono">▭</span> entity · <span class="font-mono">⬭</span> value object · <span class="font-mono">▱</span> view <span class="opacity-70">(ER boxes: dashed = value, dotted = view)</span></div>
 {{#neighborhoodMore}}<div class="text-xs opacity-50 mt-1">+{{neighborhoodMore}} more neighbor(s){{#referencedBy.length}} — see <a class="link" href="#s-referenced-by">Referenced by</a>{{/referencedBy.length}}.</div>{{/neighborhoodMore}}</section>{{/neighborhoodMermaid}}
 
-{{#referencedBy.length}}<section id="s-referenced-by" class="mt-6 text-sm"><span class="opacity-50">referenced by</span> {{#referencedBy}}<a class="link font-mono text-xs" href="{{href}}" title="{{via}}">{{name}}</a> {{/referencedBy}}</section>{{/referencedBy.length}}
+{{#reporting}}<section id="s-reporting" class="mt-6"><h2 class="text-lg font-semibold">Reporting</h2>
+<table class="table table-xs"><tbody>
+{{#dimensions}}<tr><td class="text-xs opacity-50">dimension</td><td class="font-mono">{{name}}</td><td class="text-xs opacity-60">{{kind}}</td><td class="text-xs">{{{definitionHtml}}}</td></tr>
+{{/dimensions}}{{#measures}}<tr><td class="text-xs opacity-50">measure</td><td class="font-mono">{{name}}</td><td class="text-xs opacity-60">{{kind}}</td><td class="text-xs">{{{definitionHtml}}}</td></tr>
+{{/measures}}{{#segments}}<tr><td class="text-xs opacity-50">segment</td><td class="font-mono">{{name}}</td><td class="text-xs opacity-60">{{kind}}</td><td class="text-xs">{{{definitionHtml}}}</td></tr>
+{{/segments}}</tbody></table>
+{{#reports.length}}<div class="text-sm mt-1"><span class="opacity-50">reports</span> {{#reports}}<a class="link font-mono text-xs" href="{{href}}">{{name}}</a> {{/reports}}</div>{{/reports.length}}</section>
+
+{{/reporting}}{{#referencedBy.length}}<section id="s-referenced-by" class="mt-6 text-sm"><span class="opacity-50">referenced by</span> {{#referencedBy}}<a class="link font-mono text-xs" href="{{href}}" title="{{via}}">{{name}}</a> {{/referencedBy}}</section>{{/referencedBy.length}}
 {{#usedByTemplates.length}}<div class="text-sm mt-1"><span class="opacity-50">used by templates</span> {{#usedByTemplates}}<a class="link font-mono text-xs" href="{{href}}">{{name}}</a> {{/usedByTemplates}}</div>{{/usedByTemplates.length}}
 <div class="text-[10px] opacity-40 mt-6 font-mono">{{sourceFile}}</div>