metaobjects 0.15.6__tar.gz → 0.15.8__tar.gz

{metaobjects-0.15.6 → metaobjects-0.15.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaobjects
-Version: 0.15.6
+Version: 0.15.8
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects

{metaobjects-0.15.6 → metaobjects-0.15.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.15.6"
+version = "0.15.8"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"

{metaobjects-0.15.6 → metaobjects-0.15.8}/src/metaobjects/errors.py

@@ -132,6 +132,17 @@ class ErrorCode(str, Enum):
     # emit this yet (the T6 guard is deferred — like TS, it belongs in the parser);
     # the enum tracks the shared corpus code so resolution/desugar stay aligned.
     ERR_RELATIVE_REF_IN_CANONICAL = "ERR_RELATIVE_REF_IN_CANONICAL"
+    # ADR-0041 — cross-package reference resolution contract. A BARE object
+    # reference (no ``::``) that names an object present in MORE THAN ONE package,
+    # with NO match in the referrer's own package, is ambiguous — the author must
+    # qualify it with the package (FQN). Applies to every object-ref-bearing attr
+    # (@objectRef / @references / @from / @of / @via heads / @parameterRef /
+    # @payloadRef / @responseRef). An FQN ref resolves exactly and is never
+    # ambiguous; a bare ref that matches the referrer's own package, or exactly one
+    # package anywhere, resolves fine. ``extends`` is intentionally NOT covered
+    # (its same-package/root-strict super-resolver yields ERR_UNRESOLVED_SUPER on a
+    # bare cross-package miss, not ambiguity).
+    ERR_AMBIGUOUS_REF = "ERR_AMBIGUOUS_REF"
     # FR-033 — strict structural-placement vocabulary. ERR_CHILD_NOT_ALLOWED: a
     # structural child (field/identity/source/validator/… — not an attr) is placed
     # under a parent whose registered childRules do not admit it (the structural

{metaobjects-0.15.6 → metaobjects-0.15.8}/src/metaobjects/loader/merge.py

@@ -67,12 +67,33 @@ def merge_roots(
         warnings = []
     if envelope_warnings is None:
         envelope_warnings = []
+    # #160 — an overlay-ONLY root (every object child is `overlay: true`) re-opens
+    # objects declared in OTHER files; it must not become the merge accumulator
+    # (`roots[0]`) or the base declarations get appended AFTER the overlaid nodes,
+    # leaving a projection ahead of its base entities so the order-dependent super-
+    # resolution can't resolve its `extends`/`@via`. Directory discovery order is
+    # not guaranteed to present base files first (Python `rglob` can yield a top-
+    # level overlay file before a subdir base file), so stable-partition base roots
+    # ahead of overlay-only roots here — making the merge order-independent and
+    # matching the TS loader's result. Stable within each group preserves the
+    # existing last-writer-wins overlay semantics.
+    roots = [r for r in roots if not _is_overlay_only_root(r)] + [
+        r for r in roots if _is_overlay_only_root(r)
+    ]
     target = roots[0]
     for src in roots[1:]:
         _merge_into(target, src, errors, warnings, envelope_warnings)
     return target
 
 
+def _is_overlay_only_root(root: MetaData) -> bool:
+    """True when every object child of *root* is an `overlay: true` re-open (and
+    there is at least one) — i.e. the root declares no base objects of its own, so
+    it must merge after the base-declaring roots (#160)."""
+    kids = list(root.own_children())
+    return bool(kids) and all(getattr(c, "is_overlay", False) for c in kids)
+
+
 def _source_files(env: ErrorSource) -> tuple[str, ...]:
     """Extract the ``files`` tuple from any envelope that carries one.
 

{metaobjects-0.15.6 → metaobjects-0.15.8}/src/metaobjects/loader/validation_passes.py

@@ -107,6 +107,7 @@ from ..meta.core.object.object_constants import (
 from ..meta.core.identity.identity_constants import IDENTITY_ATTR_FIELDS
 from ..meta.core.index.index_constants import INDEX_ATTR_FIELDS, INDEX_SUBTYPE_LOOKUP
 from ..source import resolved_source
+from ..naming_refs import CHILD_REF_SEP, REF_BEARING_ATTR_NAMES, resolve_object_ref
 
 # A subtype-specific template attr is valid ONLY on the subtype it is registered
 # for. The metamodel registers these per-subtype (see the core_types template block),
@@ -179,6 +180,8 @@ def run_validations(
     # @valueType (when set) must name a known scalar subtype.
     _validate_field_map(root, errors)
     _validate_templates(root, errors)
+    # ADR-0041 — cross-package bare-reference ambiguity (the object-ref contract).
+    _validate_cross_package_refs(root, errors)
     _validate_subtype_rules(root, errors, warnings)
     # FR-024 B3 — projection identity pass-through + key correspondence.
     _validate_identity_passthrough(root, errors)
@@ -208,6 +211,68 @@ def _walk(root: MetaData) -> list[MetaData]:
     return result
 
 
+# ---------------------------------------------------------------------------
+# Pass: cross-package reference ambiguity (the object-ref contract, ADR-0041)
+# ---------------------------------------------------------------------------
+
+
+def _validate_cross_package_refs(root: MetaData, errors: list[MetaError]) -> None:
+    """ADR-0041 — a BARE object reference (no ``::``) that names an object present
+    in MORE THAN ONE package, with NO match in the referrer's own package, is
+    ambiguous → ERR_AMBIGUOUS_REF (the author must qualify it with the package).
+
+    An FQN ref is exact (never ambiguous); a bare ref matching the referrer's own
+    package, or exactly one package anywhere, resolves fine. Covers every
+    object-ref-bearing attr in ``REF_BEARING_ATTR_NAMES`` (@objectRef / @references
+    / @from / @of / @via / @parameterRef / @payloadRef / @responseRef) — the dotted
+    ``.child`` tail of the origin heads is stripped to the entity OWNER. ``extends``
+    is intentionally NOT covered: its same-package/root-strict super-resolver never
+    matches a packaged object by bare name, so a bare cross-package ``extends`` is
+    unresolved (ERR_UNRESOLVED_SUPER), not ambiguous. Mirrors the TS reference
+    ``validateCrossPackageRefs``.
+    """
+
+    def _visit(node: MetaData, obj: MetaData, referrer_pkg: str) -> None:
+        for attr_name in REF_BEARING_ATTR_NAMES:
+            # ADR-0039 sanctioned own: judge the ref AUTHORED on THIS node; an
+            # inherited ref was judged on its declaring node. Mirrors the TS
+            # `node.ownAttr(attrName)`.
+            raw = node.attr(attr_name)
+            if not isinstance(raw, str):
+                continue
+            # Owner = the object part; strip any FR-024 dotted `.child` tail. An FQN
+            # owner (has `::`) is resolved exactly and can never be ambiguous.
+            dot = raw.find(CHILD_REF_SEP)
+            owner = raw if dot == -1 else raw[:dot]
+            if PACKAGE_SEP in owner or owner == "":
+                continue
+            if not resolve_object_ref(root, owner, referrer_pkg).ambiguous:
+                continue
+            pkgs = [
+                c.resolution_key()
+                for c in root.children()
+                if c.type == TYPE_OBJECT and c.name == owner
+            ]
+            errors.append(
+                MetaError(
+                    f'@{attr_name} "{raw}" on {obj.fqn()}: bare reference "{owner}" '
+                    f"is ambiguous — it names an object in multiple packages "
+                    f"({', '.join(pkgs)}) and none is in the referrer's package "
+                    f'"{referrer_pkg}". Qualify it with the package (FQN).',
+                    ErrorCode.ERR_AMBIGUOUS_REF,
+                    envelope=resolved_source(node.source, obj.fqn(), owner),
+                )
+            )
+        for c in node.own_children():
+            _visit(c, obj, referrer_pkg)
+
+    for obj in root.children():
+        if obj.type != TYPE_OBJECT:
+            continue
+        referrer_pkg = obj.package or obj.file_default_package or ""
+        _visit(obj, obj, referrer_pkg)
+
+
 # ---------------------------------------------------------------------------
 # Pass: attr-schema validation
 # ---------------------------------------------------------------------------

{metaobjects-0.15.6 → metaobjects-0.15.8}/src/metaobjects/naming_refs.py

@@ -29,6 +29,8 @@ NEVER expanded — it is the node's identity.
 """
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, NamedTuple, Optional
+
 from .meta.core.field.field_constants import FIELD_ATTR_OBJECT_REF
 from .meta.core.identity.identity_constants import IDENTITY_REFERENCE_ATTR_REFERENCES
 from .meta.core.relationship.relationship_constants import RELATIONSHIP_ATTR_OBJECT_REF
@@ -42,8 +44,12 @@ from .meta.template.template_constants import (
     TEMPLATE_ATTR_PAYLOAD_REF,
     TEMPLATE_ATTR_RESPONSE_REF,
 )
+from .shared.base_types import TYPE_OBJECT
 from .shared.separators import PACKAGE_SEP
 
+if TYPE_CHECKING:
+    from .meta.meta_data import MetaData
+
 # Structural separator literals (Python has no PACKAGE_PARENT / CHILD_REF_SEPARATOR
 # constant module; the TS values are "::" / "." / ".." — PACKAGE_SEP already
 # carries "::"). Defined here to mirror TS naming-refs.ts.
@@ -139,3 +145,64 @@ def expand_ref(raw: str, package_context: str) -> str:
     """
     owner, tail = _split_child_tail(raw)
     return _expand_owner(owner, package_context) + tail
+
+
+# ---------------------------------------------------------------------------
+# ADR-0041 — cross-package OBJECT reference resolution contract
+# ---------------------------------------------------------------------------
+# The SINGLE resolver every object-ref site shares so the same-package-preference
+# contract is uniform. Mirrors the TS reference ``resolveObjectRef`` /
+# ``objectPackage`` in naming-refs.ts.
+
+
+class ObjectRefResolution(NamedTuple):
+    """Result of :func:`resolve_object_ref` — mirrors the TS ``{ node?, ambiguous? }``.
+
+    * ``node`` — the uniquely-resolved object (``None`` when nothing matched, or
+      when a bare ref is cross-package-ambiguous).
+    * ``ambiguous`` — True ONLY for a BARE ref that names an object in more than
+      one OTHER package with none in the referrer's own package.
+    """
+
+    node: Optional["MetaData"]
+    ambiguous: bool
+
+
+def _object_package(node: "MetaData") -> str:
+    """The effective package of a root-level object — its ``resolution_key()`` minus
+    the trailing ``::<name>`` ("" for a root-level/empty-package object). Mirrors
+    the TS ``objectPackage``.
+    """
+    key = node.resolution_key()
+    i = key.rfind(PACKAGE_SEP)
+    return "" if i == -1 else key[:i]
+
+
+def resolve_object_ref(
+    root: "MetaData", ref: str, referrer_pkg: str
+) -> ObjectRefResolution:
+    """Resolve a metadata OBJECT reference under the ADR-0041 cross-package contract.
+
+    * **FQN** (``ref`` contains ``::``) → EXACT match on ``resolution_key()``/
+      ``fqn()``. Never a bare-tail fallback, so an FQN pointing at one package never
+      binds a same-named object in another (the cross-port bug ADR-0041 closes).
+    * **bare** (no ``::``) → prefer an object of that name in the REFERRER's own
+      package; else a UNIQUE object of that name across all packages; else (>1
+      across OTHER packages, none in the referrer's) → ``ambiguous``.
+
+    *referrer_pkg* is the effective package of the node carrying the ref. Returns an
+    :class:`ObjectRefResolution`. Mirrors the TS ``resolveObjectRef``.
+    """
+    objects = [c for c in root.children() if c.type == TYPE_OBJECT]
+    if PACKAGE_SEP in ref:
+        for c in objects:
+            if c.resolution_key() == ref or c.fqn() == ref:
+                return ObjectRefResolution(c, False)
+        return ObjectRefResolution(None, False)
+    matches = [c for c in objects if c.name == ref]
+    if len(matches) <= 1:
+        return ObjectRefResolution(matches[0] if matches else None, False)
+    for c in matches:
+        if _object_package(c) == referrer_pkg:
+            return ObjectRefResolution(c, False)
+    return ObjectRefResolution(None, True)