@metaobjectsdev/metadata 1.0.5-rc.1 → 1.0.5-rc.11

package/src/loader/validation-passes.ts

@@ -134,6 +134,10 @@ import {
   resolveRelationshipReference,
 } from "../core/relationship/resolve-relationship-reference.js";
 import type { MetaRoot } from "../shared/meta-root.js";
+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,
@@ -2250,6 +2254,115 @@ export function validateOneSideReferenceResolution(root: MetaRoot): ParseError[]
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// Rule (f) — a M:N junction must PAIR: one identity.reference resolving to the
+// navigating entity, one to the @objectRef target.
+//
+// Rule (d) already checks that the junction declares exactly TWO references. It
+// never checked WHAT they point at, so a junction whose two references name some
+// other pair of entities loaded perfectly clean and then failed — differently —
+// in every port's codegen: TypeScript and C# warned and emitted no traversal
+// route (the endpoint simply 404s, with nothing in the build output a CI gate
+// would fail on), while Java, Kotlin and Python threw and failed the build. One
+// input, five contracts, and the quiet arm is the dangerous one.
+//
+// The check belongs HERE because the model is what is wrong, and because a
+// loader error is the only answer every port already agrees on. Both codegen
+// branches become unreachable for a model that loaded.
+//
+// It runs the REAL derivation (deriveM2MFields) rather than reimplementing the
+// pairing, so the loader and the FK derivation cannot drift apart — the same
+// reason _junctionReferences above shares referenceIdentities() with codegen. A
+// parallel check would be a second opinion, and the defect class being closed
+// here is precisely "two parts of the pipeline disagree".
+//
+// SCOPE mirrors codegen's own iteration exactly (relation-resolver.ts): every
+// CONCRETE, non-projection object crossed with its EFFECTIVE relationships.
+// That is not incidental —
+//   * per (entity, relationship), NOT deduped by declaration like rule (d):
+//     pairing is a property of the NAVIGATING entity. deriveM2MFields accepts a
+//     junction reference naming either the declaring entity or the navigating
+//     one, so an inherited M:N can pair from one subtype and not another, and
+//     checking the declaration alone would both miss that and reject models
+//     codegen accepts.
+//   * abstract levels are skipped because their own declarations do not file —
+//     an abstract base's FK reaches a table only through a concrete descendant,
+//     whose own walk reaches this same relationship.
+//   * projections are skipped because they never emit a relations() block.
+// Widening past that set would fail builds codegen never had a problem with.
+// ---------------------------------------------------------------------------
+
+/** codegen-ts's isProjection, reproduced here: that module is not reachable from
+ * the loader, and the two source guards it is built from live in this package.
+ * ADR-0039: own — projection-ness is the entity's OWN declared source @kind. */
+function isProjectionObject(obj: MetaObject): boolean {
+  const own = obj.ownChildren();
+  return own.some(isReadOnlySource) && !own.some(isWritableSource);
+}
+
+export function validateM2MJunctionPairing(root: MetaRoot): ParseError[] {
+  const errors: ParseError[] = [];
+  for (const obj of root.objects()) {
+    if (obj.isAbstract === true) continue;
+    if (isProjectionObject(obj)) continue;
+    // ADR-0039: resolving — an M:N relationship may be reached only via extends.
+    for (const rel of obj.relationships()) {
+      if (rel.attr(RELATIONSHIP_ATTR_CARDINALITY) !== CARDINALITY_MANY) continue;
+      if (rel.attr(RELATIONSHIP_ATTR_THROUGH) === undefined) continue;
+      try {
+        deriveM2MFields(rel, obj, root);
+      } catch (err) {
+        if (!(err instanceof M2MDerivationError)) throw err;
+        // Rule (d) reports the malformed-junction cases it owns (missing
+        // @through, unresolvable @through, a reference count other than two, an
+        // @sourceRefField matching no FK) against the DECLARING entity, and the
+        // derivation re-checks them. Reporting them again here — once per
+        // concrete subtype — would bury the pairing finding under duplicates of
+        // a diagnosis the author already has, so those are left to rule (d) and
+        // this rule speaks only where it is the sole witness.
+        if (isJunctionShapeErrorOwnedByRuleD(rel, root)) continue;
+        errors.push(
+          new ParseError(
+            `relationship "${obj.name}.${rel.name}" cannot be resolved through its ` +
+              `@${RELATIONSHIP_ATTR_THROUGH} junction: ${err.message}. Without a reference to ` +
+              `"${obj.name}" the junction rows cannot be filtered to this entity, so no ` +
+              `traversal is derivable.`,
+            { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
+          ),
+        );
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * True when the derivation's failure is one rule (d) already reports — a
+ * junction that is missing, unresolvable, or does not declare exactly two
+ * identity.reference children. Keyed on the SHAPE rather than on the message
+ * text: matching strings would make this silently stop de-duplicating the first
+ * time a message is reworded, and a gate keyed to prose breaks on the rewrite.
+ */
+function isJunctionShapeErrorOwnedByRuleD(rel: MetaRelationship, root: MetaRoot): boolean {
+  const through = rel.attr(RELATIONSHIP_ATTR_THROUGH);
+  if (typeof through !== "string" || through === "") return true;
+  // Resolve exactly as rule (d) and deriveM2MFields do — ADR-0042 via the single
+  // resolveObjectRef matcher, referred from the DECLARING entity's package. A
+  // second resolution rule here is what made this helper disagree with the
+  // derivation and emit rule (d)'s finding a second time.
+  const declaring = rel.parent;
+  const referrerPkg = declaring?.package ?? declaring?.fileDefaultPackage ?? "";
+  const junction = _findObject(root, through, referrerPkg) as MetaObject | undefined;
+  if (junction === undefined) return true;
+  if (junction.subType !== OBJECT_SUBTYPE_ENTITY) return true;
+  if (_countJunctionReferences(junction) !== 2) return true;
+  const sourceRefField = rel.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
+  if (typeof sourceRefField === "string" && sourceRefField !== "") {
+    if (!_junctionReferenceFkFields(junction).includes(sourceRefField)) return true;
+  }
+  return false;
+}
+
 /**
  * Render a candidate reference as `name(fkField)`, or `name(fieldA, fieldB)`
  * for a composite reference — so two composite references sharing a first

package/src/parser-core.ts

@@ -302,6 +302,24 @@ function isAbstractAnchorFor(type: string, registry: TypeRegistry): boolean {
   return registry.allSubTypesOf(type).some((sub) => sub !== SUBTYPE_BASE);
 }
 
+/**
+ * How a (type, subType) pair is named back to the author in an error.
+ *
+ * A bare wrapper key for an UNREGISTERED type has no subType to resolve, so the naive
+ * `${type}.${subType}` renders `"madeup."` — a trailing dot that reads like the author
+ * wrote one. Print the type alone in that case; it is what they actually wrote.
+ */
+function typeDisplayName(type: string, subType: string): string {
+  return subType === "" ? type : `${type}${TYPE_SUBTYPE_SEPARATOR}${subType}`;
+}
+
+/** The JSON kind of a value, for an error that has to say what the author wrote instead. */
+function describeJsonKind(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return `a ${typeof value}`;
+}
+
 function abstractSubtypeMessage(type: string): string {
   return (
     `"${type}.${SUBTYPE_BASE}" may not be authored — every "${SUBTYPE_BASE}" subtype is an ` +
@@ -596,19 +614,6 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
     const rootKey = wrapperKeys[0]!;
     const rootData = topLevel[rootKey];
 
-    if (typeof rootData !== "object" || rootData === null || Array.isArray(rootData)) {
-      // The error context references the rootKey wrapper; push it so the
-      // envelope's jsonPath includes it (matches the legacy `path` slot).
-      _currentPath!.pushKey(rootKey);
-      const src = errSource();
-      _currentPath!.pop();
-      throw new ParseError(
-        `Top-level wrapper "${rootKey}" must contain an object`,
-        { code: "ERR_TOP_LEVEL_NOT_OBJECT", source: src },
-      );
-    }
-
-    const rootDataObj = rootData as Record<string, unknown>;
     const { type: rootType, subType: rootSubType, explicit: rootExplicit } =
       splitTypeKey(rootKey, opts.registry);
 
@@ -649,7 +654,7 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
       // other" is how a rule ends up half-true and passing every probe.
       const retiredRoot = retiredSubType(rootType, rootSubType);
       throw new ParseError(
-        `Unknown root type "${rootType}.${rootSubType}" — ` +
+        `Unknown root type "${typeDisplayName(rootType, rootSubType)}" — ` +
           (retiredRoot !== undefined ? retirementHint(retiredRoot) : "not registered"),
         {
           code: rootTypeCode,
@@ -661,6 +666,26 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
       );
     }
 
+    // --- The root wrapper's BODY must be an object ---
+    // AFTER the key resolves — the same order as the CHILD door (see processChildren).
+    // One rule, both doors, in the same order at both: until 1.0.5 this door ran the body
+    // check first, the child door ran it first too but under a DIFFERENT code, and the JVM
+    // root door ran it last with no error code at all.
+    if (typeof rootData !== "object" || rootData === null || Array.isArray(rootData)) {
+      // The error context references the rootKey wrapper; push it so the
+      // envelope's jsonPath includes it (matches the legacy `path` slot).
+      _currentPath!.pushKey(rootKey);
+      const src = errSource();
+      _currentPath!.pop();
+      throw new ParseError(
+        `Top-level wrapper "${rootKey}" must contain an object, and holds ` +
+          `${describeJsonKind(rootData)}`,
+        { code: "ERR_TOP_LEVEL_NOT_OBJECT", source: src },
+      );
+    }
+
+    const rootDataObj = rootData as Record<string, unknown>;
+
     // FR5a — push the wrapper-key segment onto the JSONPath stack so all
     // descendants emit jsonPath strings rooted at "$.<rootKey>". The merge-mode
     // path keeps the existing root's source untouched; only NEW children get
@@ -762,7 +787,7 @@ function parseNodeFresh(
     if (registry.has(type, SUBTYPE_BASE)) {
       subType = SUBTYPE_BASE;
     } else {
-      const msg = `Unknown type "${type}.${subType}" — not registered`;
+      const msg = `Unknown type "${typeDisplayName(type, subType)}" — not registered`;
       errors.push(new ParseError(msg, { code: "ERR_UNKNOWN_TYPE", source: errSource() }));
       const rawName = nodeData[RESERVED_KEY_NAME];
       const name = typeof rawName === "string" ? rawName : "";
@@ -1666,18 +1691,6 @@ function processChildren(
       _currentYamlPosition = getYamlPosition(childRecord, childKey);
     }
 
-    if (typeof childData !== "object" || childData === null || Array.isArray(childData)) {
-      reportProblem(
-        `Child wrapper "${childKey}" at ${childNodePath} must contain an object`,
-        strict, warnings, "ERR_TOP_LEVEL_NOT_OBJECT",
-      );
-      _currentPath?.pop(); // pop child wrapper key
-      _currentPath?.pop(); // pop array index
-      _currentYamlPosition = savedYamlPosition; // FR5b — restore parent's pos
-      continue;
-    }
-
-    const childDataObj = childData as Record<string, unknown>;
     const { type: childType, subType: childSubTypeRaw, explicit } = splitTypeKey(childKey, registry);
 
     let childSubType = childSubTypeRaw;
@@ -1687,8 +1700,17 @@ function processChildren(
     // (identity, index, requirement) falls into that check's else-arm first and is reported as
     // an UNKNOWN TYPE — a message asserting the type does not exist, about a type that does,
     // with its name mangled to `"identity."`. Order is the whole rule here.
-    if ((childSubType === SUBTYPE_BASE && isAbstractAnchorFor(childType, registry))
-      || (!explicit && childSubType === "")) {
+    //
+    // Registration first, exactly as the ROOT door does it: an UNREGISTERED type has no
+    // declared default either, so without this guard a typo'd child key (`madeup`) lands in
+    // this branch and is told to "write the full `madeup.<subType>`" — advice about a type
+    // that does not exist. The root door has carried the guard since FR5a and Java pins it
+    // with a root-door test; the child door never got it, so one rule was true at one of its
+    // two doors in TypeScript, C# and Java, while Python reported ERR_UNKNOWN_TYPE. The
+    // registration check below owns the unregistered case and phrases it correctly.
+    if (registry.allSubTypesOf(childType).length > 0
+      && ((childSubType === SUBTYPE_BASE && isAbstractAnchorFor(childType, registry))
+        || (!explicit && childSubType === ""))) {
       errors.push(
         explicit
           ? new ParseError(abstractSubtypeMessage(childType), {
@@ -1723,7 +1745,7 @@ function processChildren(
         const retiredChild = retiredSubType(childType, childSubType);
         errors.push(
           new ParseError(
-            `Unknown type "${childType}.${childSubType}" — ` +
+            `Unknown type "${typeDisplayName(childType, childSubType)}" — ` +
               (retiredChild !== undefined ? retirementHint(retiredChild) : "not registered"),
             { code: childTypeCode, source: errSource() },
           ),
@@ -1735,6 +1757,35 @@ function processChildren(
       }
     }
 
+    // --- The wrapper's BODY must be an object ---
+    // AFTER the key resolves, deliberately. A child is one `{ "<type>.<subType>": { …body… } }`
+    // pair, so a string/number/boolean/array/null body carries no node to read — but running
+    // this check FIRST answers `{ "$comment": "prose" }` with "must contain an object", which
+    // sends the author to wrap prose that was never a node in the first place. Key first, body
+    // second: each mistake gets the message about itself.
+    //
+    // A hard ERROR, not `reportProblem`'s lax warning (1.0.5). Under a warning the child was
+    // DROPPED from the tree on every port and the load still succeeded — a declared field
+    // simply not there, with `meta gen` emitting a table without its column. Four ports
+    // disagreed about it besides: TypeScript and C# warned, Java logged to slf4j and put
+    // nothing in the envelope at all, and Python dropped a registered type's bad body in
+    // silence. See docs/compatibility-policy.md, "Correcting input we wrongly accepted".
+    if (typeof childData !== "object" || childData === null || Array.isArray(childData)) {
+      errors.push(
+        new ParseError(
+          `Child wrapper "${childKey}" at ${childNodePath} must contain an object — ` +
+            `a child is one { "<type>.<subType>": { …node body… } } pair, and this one holds ` +
+            `${describeJsonKind(childData)}. Give it a node body, or remove the entry.`,
+          { code: "ERR_CHILD_NOT_OBJECT", source: errSource() },
+        ),
+      );
+      _currentPath?.pop(); // pop child wrapper key
+      _currentPath?.pop(); // pop array index
+      _currentYamlPosition = savedYamlPosition; // FR5b — restore parent's pos
+      continue; // skip this child
+    }
+    const childDataObj = childData as Record<string, unknown>;
+
     // A `<type>.base` child may not be AUTHORED — the CHILD door (the root door is above).
     // Gated on `explicit`, deliberately: `base` is also this parser's fallback for an
     // OMITTED subtype whose registry default is unregistered (the branch directly above),