@metaobjectsdev/metadata 1.0.13 → 1.1.0

package/src/loader/resolve-references.ts

@@ -0,0 +1,144 @@
+// ADR-0059 R5 — resolve every reference once, after validation and before freeze.
+//
+// Sources do not interpret references (R1): YAML and canonical JSON hand the loader
+// each reference string exactly as written. The validation passes resolve those
+// authored strings through the shared resolver and report failures with their own
+// codes. This pass then walks the physical tree once and, for every reference that
+// resolves, records the target and rewrites the value to its canonical spelling (R6),
+// keeping the authored string beside it. After the pass every consumer reads values
+// that mean the same thing whatever package they are read from, and the serializer
+// writes them as they are.
+//
+// A reference that does not resolve is left exactly as written: validation has
+// already reported it.
+
+import type { MetaData, AttrValue } from "../shared/meta-data.js";
+import { MetaAttr } from "../core/attr/meta-attr.js";
+import { TYPE_DIMENSION } from "../shared/base-types.js";
+import { REPORTING_ATTR_OF, REPORTING_ATTR_VIA } from "../core/reporting/reporting-constants.js";
+import {
+  OBJECT_REPORT_ATTR_FROM,
+  OBJECT_REPORT_ATTR_SPINE,
+  OBJECT_SUBTYPE_REPORT,
+} from "../core/object/object-constants.js";
+import { TYPE_OBJECT } from "../shared/base-types.js";
+import {
+  REF_BEARING_ATTR_NAMES,
+  effectivePackageOf,
+  resolveObjectRef,
+  spellRef,
+  splitChildTail,
+  topLevelNodeOf,
+} from "../naming-refs.js";
+import { resolveSuperRef } from "../super-resolve.js";
+import { dimensionViaTerminal } from "./reporting-validation.js";
+
+/** One resolved reference: its owner object and the canonical spelling. */
+interface Resolved {
+  readonly target: MetaData;
+  readonly canonical: string;
+}
+
+/** Resolve one reference string's owner in `refPkg`, and spell it canonically. Root-level
+ *  targets are spelled `::Name` unless both the resolution package and the declaring
+ *  package are root-level, so a consumer reading from either package binds the same node. */
+function resolveOne(root: MetaData, value: string, refPkg: string, declPkg: string): Resolved | undefined {
+  const { owner, tail } = splitChildTail(value);
+  const target = resolveObjectRef(root, owner, refPkg).node;
+  if (target === undefined) return undefined;
+  return { target, canonical: spellRef(target, refPkg !== "" ? refPkg : declPkg, tail) };
+}
+
+/** R3 — the package an own reference attribute of `node` resolves in. */
+function referrerPackage(root: MetaData, node: MetaData, attr: string, declPkg: string): string {
+  // `@of` on a dimension that walks `@via`: the package of the entity the walk reaches.
+  if (node.type === TYPE_DIMENSION && attr === REPORTING_ATTR_OF) {
+    // ADR-0039: resolving — the @via that governs this @of may be inherited.
+    const via = node.attr(REPORTING_ATTR_VIA);
+    const declaring = node.parent;
+    if (typeof via === "string" && via !== "" && declaring !== undefined) {
+      const terminal = dimensionViaTerminal(root, declaring, via);
+      return terminal !== undefined ? effectivePackageOf(terminal) : declPkg;
+    }
+  }
+  // `@spine` on a report: the package of the `@from` entity.
+  if (node.type === TYPE_OBJECT && node.subType === OBJECT_SUBTYPE_REPORT && attr === OBJECT_REPORT_ATTR_SPINE) {
+    // ADR-0039: resolving — @from may be inherited.
+    const from = node.attr(OBJECT_REPORT_ATTR_FROM);
+    if (typeof from === "string" && from !== "") {
+      const fromNode = resolveObjectRef(root, from, declPkg).node;
+      if (fromNode !== undefined) return effectivePackageOf(fromNode);
+    }
+  }
+  return declPkg;
+}
+
+function resolveAttr(root: MetaData, node: MetaData, attr: MetaAttr, declPkg: string): void {
+  const value = attr.value;
+  const refPkg = referrerPackage(root, node, attr.name, declPkg);
+  if (typeof value === "string") {
+    if (value === "") return;
+    const r = resolveOne(root, value, refPkg, declPkg);
+    if (r === undefined) return;
+    attr.resolvedTarget = r.target;
+    if (r.canonical !== value) {
+      attr.authoredValue ??= value;
+      node.setAttr(attr.name, r.canonical);
+    }
+    return;
+  }
+  if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+    const items = value as readonly string[];
+    const resolved = items.map((v) => (v === "" ? undefined : resolveOne(root, v, refPkg, declPkg)));
+    if (resolved.every((r) => r === undefined)) return;
+    attr.resolvedTarget = resolved.map((r) => r?.target);
+    const canonical: AttrValue = items.map((v, i) => resolved[i]?.canonical ?? v);
+    if (canonical.some((v, i) => v !== items[i])) {
+      attr.authoredValue ??= [...items];
+      node.setAttr(attr.name, canonical);
+    }
+  }
+}
+
+/** Canonical `extends`: the owner spelled from the declaring node's package, tail kept. */
+function resolveExtends(root: MetaData, node: MetaData): void {
+  const ref = node.superRef;
+  if (ref === undefined || node.superResolved === undefined) return;
+  const pkg = effectivePackageOf(node);
+  const { owner, tail } = splitChildTail(ref);
+  let ownerNode: MetaData | undefined;
+  try {
+    ownerNode = resolveSuperRef(owner, pkg, root);
+  } catch {
+    return; // an over-drop never resolved, so superResolved would be unset
+  }
+  if (ownerNode === undefined) return;
+  const canonical = spellRef(ownerNode, pkg, tail);
+  if (canonical === ref) return;
+  node.authoredSuperRef ??= ref;
+  node.setSuper(canonical);
+}
+
+/**
+ * Resolve every own reference attribute (ADR-0059 R4) and every `extends` in the
+ * tree, record the targets, and rewrite resolved values to their canonical spelling.
+ * Must run after the last validation pass and before `freeze()`.
+ */
+export function resolveReferences(root: MetaData): void {
+  const visit = (node: MetaData): void => {
+    if (node !== root) {
+      resolveExtends(root, node);
+      // R3 default: the effective package of the top-level node that physically
+      // declares the attribute. Own attributes are declared here, by definition.
+      const declPkg = effectivePackageOf(topLevelNodeOf(node));
+      // ADR-0039: own — this pass rewrites the declared-here layer; an inherited
+      // attribute is resolved once, on the node that declares it.
+      for (const attr of node.ownMetaAttrs()) {
+        if (REF_BEARING_ATTR_NAMES.has(attr.name)) resolveAttr(root, node, attr, declPkg);
+      }
+    }
+    // ADR-0039: own — structural walk over the physical declaration tree.
+    for (const child of node.ownChildren()) visit(child);
+  };
+  visit(root);
+}

package/src/loader/validation-passes.ts

@@ -15,7 +15,7 @@ import type { MetaObject } from "../core/object/meta-object.js";
 import type { MetaReferenceIdentity } from "../core/identity/meta-identity.js";
 import { contradictionHint, contradictionsFor } from "../attr-contradictions.js";
 import { ParseError, type ErrorCode } from "../errors.js";
-import { resolveObjectRef, didYouMeanHint } from "../naming-refs.js";
+import { resolveObjectRef, didYouMeanHint, refTarget } from "../naming-refs.js";
 import { PACKAGE_SEPARATOR, CHILD_REF_SEPARATOR } from "../shared/structural.js";
 import { resolvedSource, type ErrorSource } from "../source.js";
 import {
@@ -138,7 +138,6 @@ import type { MetaRelationship } from "../core/relationship/meta-relationship.js
 // Rule (f) runs the REAL M:N derivation so the loader and codegen cannot drift.
 import { deriveM2MFields, M2MDerivationError } from "../core/relationship/derive-m2m-fields.js";
 import { isReadOnlySource, isWritableSource } from "../shared/node-guards.js";
-import { stripPackage } from "../naming.js";
 import {
   FILTER_COMPOSE_OR,
   FILTER_COMPOSE_AND,
@@ -957,8 +956,8 @@ function _inferViaSingleHop(
     .filter((c) => c.type === TYPE_RELATIONSHIP)
     .filter((rel) => {
       // ADR-0039: resolving — a relationship may inherit @objectRef via extends.
-      const ref = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF);
-      return typeof ref === "string" && stripPackage(ref) === targetEntity.name;
+      // ADR-0059 R7: compare the bound target, never a short name.
+      return refTarget(rel, RELATIONSHIP_ATTR_OBJECT_REF) === targetEntity;
     });
   // FR5d — referrer is `<host-FQN>::<fieldName>`, target is the from/of ref
   // whose implicit path could not be resolved.
@@ -2207,7 +2206,11 @@ export function validateOneSideReferenceResolution(root: MetaRoot): ParseError[]
       const objectRef = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF);
       if (typeof objectRef !== "string" || objectRef === "") continue;
 
-      const candidates = referenceCandidatesFor(obj, objectRef);
+      // ADR-0059 R7: match references by the bound target node. An unresolved
+      // @objectRef is reported by its own pass.
+      const targetNode = refTarget(rel, RELATIONSHIP_ATTR_OBJECT_REF);
+      if (targetNode === undefined) continue;
+      const candidates = referenceCandidatesFor(obj, targetNode);
 
       const sourceRefField = rel.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
       const declared = typeof sourceRefField === "string" && sourceRefField !== ""
@@ -2237,7 +2240,7 @@ export function validateOneSideReferenceResolution(root: MetaRoot): ParseError[]
       // No @sourceRefField declared: ambiguity only exists with 2+ candidates —
       // resolveRelationshipReference's name-pairing step (ladder step 3) decides.
       if (candidates.length <= 1) continue;
-      const resolved = resolveRelationshipReference(obj, rel.name, objectRef);
+      const resolved = resolveRelationshipReference(obj, rel.name, targetNode);
       if (resolved) continue;
 
       errors.push(
@@ -2706,9 +2709,10 @@ function checkProjectionFilterRefs(
 //      Resolution of the reference itself is `verify`'s job (it owns every other
 //      @implementedBy-style resolution) — the loader owns the shape.
 //
-// Runs in every port. `requirement.*` gate logic otherwise lives only in the TS
-// CLI, which is exactly why THIS rule belongs in the loader: a Java or Python
-// estate would otherwise be free to author the shape the rule exists to prevent.
+// Runs in every port. The requirement gate runs in every port's `verify` since
+// ADR-0057 (when this rule was written it ran only in the TS CLI), yet the rule
+// stays in the loader: a shape the loader refuses is unreachable in every port
+// and in every program that loads the model, whether or not anyone runs `verify`.
 //
 // ADR-0039: children()/attr() throughout — never own* — so a requirement that
 // inherits its status through `extends` is judged on its EFFECTIVE status.

package/src/loader/validation-registry.ts

@@ -8,9 +8,13 @@
 
 import type { MetaData } from "../shared/meta-data.js";
 import { ParseError } from "../errors.js";
-import { didYouMeanHint } from "../naming-refs.js";
+import {
+  didYouMeanHint,
+  ownerCandidateKeys,
+  referrerPackageFor,
+  RefOverDropError,
+} from "../naming-refs.js";
 import { TYPE_OBJECT } from "../shared/base-types.js";
-import { PACKAGE_SEPARATOR } from "../shared/structural.js";
 import type { TypeRegistry } from "../registry.js";
 import type { LoaderCode, SymbolTable, ValidationContext } from "../validation-types.js";
 
@@ -38,15 +42,25 @@ class SymbolTableImpl implements SymbolTable {
     return t;
   }
 
-  /** ADR-0042 package-local resolution within the `type` bucket: FQN → exact
-   *  resolution-key match; bare → the referrer's own package (`<referrerPkg>::<ref>`),
-   *  else a root-level node of that type. */
+  /** ADR-0059 R2 resolution within the `type` bucket: `::Rest` root-absolute,
+   *  `..::Rest` parent-relative, `pkg::Name` exact, bare `Name` in the referrer's own
+   *  package then root-level. Exact keys only. An over-dropping `..::` resolves to
+   *  nothing here; the walk reports it as ERR_BAD_ATTR_VALUE. */
   resolve(type: string, ref: string, referrerPkg: string): MetaData | undefined {
     const bucket = this.byType.get(type);
     if (bucket === undefined) return undefined;
-    if (ref.includes(PACKAGE_SEPARATOR)) return bucket.get(ref);
-    const localKey = referrerPkg !== "" ? `${referrerPkg}${PACKAGE_SEPARATOR}${ref}` : ref;
-    return bucket.get(localKey) ?? bucket.get(ref);
+    let keys: readonly string[];
+    try {
+      keys = ownerCandidateKeys(ref, referrerPkg);
+    } catch (e) {
+      if (e instanceof RefOverDropError) return undefined;
+      throw e;
+    }
+    for (const key of keys) {
+      const hit = bucket.get(key);
+      if (hit !== undefined) return hit;
+    }
+    return undefined;
   }
 
   resolveObject(ref: string, referrerPkg: string): MetaData | undefined {
@@ -94,7 +108,21 @@ export function runRegisteredValidation(root: MetaData, registry: TypeRegistry):
         const raw = node.attr(desc.attr);
         if (typeof raw !== "string" || raw === "") continue; // absence is the required-attr pass's job
         const entityRef = desc.dottedFieldPath ? (raw.split(".")[0] ?? raw) : raw;
-        const target = ctx.symbols.resolve(desc.targetType, entityRef, pkg);
+        // ADR-0059 R3: an inherited reference resolves in the package of the
+        // top-level node that physically declares it, not the inheritor's.
+        const refPkg = referrerPackageFor(node, desc.attr);
+        try {
+          ownerCandidateKeys(entityRef, refPkg);
+        } catch (e) {
+          if (!(e instanceof RefOverDropError)) throw e;
+          ctx.error(
+            "ERR_BAD_ATTR_VALUE",
+            node,
+            `${node.type}.${node.subType} "${node.name}" @${desc.attr} "${raw}" climbs above the root package — each '..::' drops one segment of the declaring package.`,
+          );
+          continue;
+        }
+        const target = ctx.symbols.resolve(desc.targetType, entityRef, refPkg);
         // Qualify the node name with its owning entity (e.g. "Order.items") so the error is
         // locatable from the message alone, not just the source envelope.
         const qname = node.parent?.name ? `${node.parent.name}.${node.name}` : node.name;

package/src/metamodel-docs/index.ts

@@ -1,10 +1,10 @@
 // FR-033 S3 — metamodel doc-gen public surface.
 //
 // Documents the METAMODEL ITSELF (the type/subtype/attr vocabulary of the strict
-// registry) as tiered, LLM-readable markdown — distinct from `meta docs --model`
+// registry) as tiered, LLM-readable markdown — distinct from the `docs` generator
 // (which documents a user's entities). The renderer is a pure, deterministic
-// function over the composed registry + a provenance lens; file I/O lives in the
-// CLI.
+// function over the composed registry + a provenance lens; the `metamodel-docs`
+// generator in codegen-ts writes its pages.
 
 import type { TypeRegistry } from "../registry.js";
 import { coreProviders } from "../core-types.js";

package/src/metamodel-docs/render.ts

@@ -1,8 +1,8 @@
 // FR-033 S3 — the metamodel doc renderer (pure, deterministic, byte-stable).
 //
 // Documents the METAMODEL ITSELF — the type/subtype/attr vocabulary of the
-// strict registry — for an LLM (and humans). This is distinct from `meta docs
-// --model`, which documents a USER's entities. The output is a tiered markdown
+// strict registry — for an LLM (and humans). This is distinct from the `docs`
+// generator (`docsFile()`), which documents a USER's entities. The output is a tiered markdown
 // tree:
 //
 //   INDEX.md          every type.subType + one-liner + link  (always-on map)
@@ -24,7 +24,7 @@ import { CHILD_RULE_WILDCARD } from "../shared/structural.js";
 import { SUBTYPE_BASE } from "../shared/base-types.js";
 
 /** The regeneration command, named in every file's DO-NOT-EDIT header. */
-const REGEN_COMMAND = "meta docs --metamodel";
+const REGEN_COMMAND = "meta gen (the metamodel-docs generator, metamodelDocsFile())";
 
 /** ASCII codepoint compare — locale-independent, byte-stable. */
 function compare(a: string, b: string): number {
@@ -196,7 +196,7 @@ function renderIndex(defs: readonly TypeDefinition[]): string {
     "# MetaObjects Metamodel — Index\n",
     "This documents the **metamodel itself** — the type / subtype / attribute",
     "vocabulary the loader accepts — generated from the strict registry. It is",
-    "NOT documentation of a user's entities (that is `meta docs --model`).\n",
+    "NOT documentation of a user's entities (that is the `docs` generator, `docsFile()`).\n",
     "Follow a link into `types/<family>.md` for the full attribute table, allowed",
     "children, and cardinality of a subtype. Universal documentation attributes",
     "(`@description`/`@title`/…) apply to every node and are listed once in",