metaobjects 0.15.7__tar.gz → 0.15.9__tar.gz

{metaobjects-0.15.7 → metaobjects-0.15.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaobjects
-Version: 0.15.7
+Version: 0.15.9
 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.7 → metaobjects-0.15.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.15.7"
+version = "0.15.9"
 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.7 → metaobjects-0.15.9}/src/metaobjects/codegen/generators/render_helper_generator.py

@@ -26,10 +26,10 @@ build fail when a mustache references a field the payload VO doesn't declare.
 Reuse, not reimplementation: ``render`` (the emitted runtime call), ``verify`` (the
 build-time gate), ``FilesystemProvider`` (build-time ref resolution), and
 ``EmailDocument`` (email return type). The payload field tree is walked from the VO
-the same way the other generators walk it — but a nested ``field.object``'s
-``@objectRef`` is resolved by BARE short-name (cross-port render-helper consensus:
-TS ``findObject`` / Java ``resolveNestedObjectRef`` / C# ``ResolveNestedObjectRef``),
-only recursing into ``object.value`` targets, cycle-guarded.
+the same way the other generators walk it — a nested ``field.object``'s ``@objectRef``
+is resolved FQN-exact when fully-qualified (ADR-0041) else by short name (cross-port
+render-helper consensus: TS ``refMatchesObject`` / Java+Kotlin ``resolveNestedObjectRef``
+/ C# ``ResolveNestedObjectRef``), only recursing into ``object.value`` targets, cycle-guarded.
 
 Python divergence vs TS / Java / C#: Python's ``RenderRequest`` has NO ``verify``
 field — the Python render engine does not run a runtime drift pass — so the emitted
@@ -75,19 +75,24 @@ def _py_str(s: str) -> str:
 
 
 # ---------------------------------------------------------------------------
-# Payload field-tree walk — nested @objectRef resolved by BARE short-name
-# (cross-port render-helper consensus). Object-ref fields recurse into their
-# target object.value (SUBTYPE_VALUE only); a `seen` set guards reference cycles.
+# Payload field-tree walk — nested @objectRef resolved FQN-exact (ADR-0041).
+# Object-ref fields recurse into their target object.value (SUBTYPE_VALUE only);
+# a `seen` set guards reference cycles.
 # ---------------------------------------------------------------------------
 
 
 def _resolve_nested_object_ref(root: MetaData, reference: str) -> MetaObject | None:
-    """Resolve a ``field.object``'s ``@objectRef`` to its target ``object.value`` by BARE
-    short-name — mirroring the C# ``ResolveNestedObjectRef`` / TS ``findObject`` / Java
-    ``resolveNestedObjectRef``. If the ref carries a package, only the segment after the
-    last ``::`` is compared, against each ``object.value``'s own short name."""
+    """Resolve a ``field.object``'s ``@objectRef`` to its target ``object.value``.
+
+    ADR-0041: a FULLY-QUALIFIED ref (contains ``::``) resolves EXACTLY on the
+    package-qualified name (``resolution_key()``/``fqn()``) — never a bare-tail
+    fallback that would bind a same-named ``object.value`` in the WRONG package on a
+    cross-package short-name collision. A bare ref still matches by short name
+    (first-wins). Mirrors the Java/Kotlin ``resolveNestedObjectRef`` + TS
+    ``refMatchesObject``."""
     if not reference:
         return None
+    fqn = PACKAGE_SEP in reference
     ref_short = reference.rsplit(PACKAGE_SEP, 1)[-1]
     # ADR-0039 sanctioned own: top-level scan on the loader ROOT (never extended, own == effective)
     for child in root.own_children():
@@ -95,7 +100,10 @@ def _resolve_nested_object_ref(root: MetaData, reference: str) -> MetaObject | N
             continue
         if child.sub_type != OBJECT_SUBTYPE_VALUE:
             continue
-        if child.name.rsplit(PACKAGE_SEP, 1)[-1] == ref_short:
+        if fqn:
+            if child.resolution_key() == reference or child.fqn() == reference:
+                return child
+        elif child.name.rsplit(PACKAGE_SEP, 1)[-1] == ref_short:
             return child
     return None
 
@@ -107,9 +115,9 @@ def _derive_payload_field_tree(
     resolvable ``@objectRef`` to an ``object.value`` becomes a context-pushing node whose
     children are the target VO's tree (recursed, cycle-guarded). Every other field is a
     leaf."""
-    if vo is None or vo.name in seen:
+    if vo is None or vo.resolution_key() in seen:
         return []
-    next_seen = seen | {vo.name}
+    next_seen = seen | {vo.resolution_key()}
     fields: list[PayloadField] = []
     for f in vo.children():
         if f.type != TYPE_FIELD or not isinstance(f, MetaField):

{metaobjects-0.15.7 → metaobjects-0.15.9}/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.7 → metaobjects-0.15.9}/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.7 → metaobjects-0.15.9}/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)

{metaobjects-0.15.7 → metaobjects-0.15.9}/tests/codegen/test_render_helper_conformance.py

@@ -27,7 +27,7 @@ from pathlib import Path
 import pytest
 
 import metaobjects.core_types  # noqa: F401  — side-effect: registers attr classes
-from metaobjects import MetaDataLoader
+from metaobjects import InMemoryStringSource, MetaDataLoader
 from metaobjects.codegen.config import GenConfig
 from metaobjects.codegen.generator import GenContext
 from metaobjects.codegen.generators.render_helper_generator import RenderHelperGenerator
@@ -45,6 +45,15 @@ def _load_root(meta_json: Path):
     return res.root
 
 
+def _load_root_from_files(*meta_jsons: Path):
+    # Multi-file (multi-package) load — one InMemoryStringSource per file, merged into a
+    # single root (mirrors fixtures/conformance/loader-same-name-distinct-packages).
+    sources = [InMemoryStringSource(p.read_text()) for p in meta_jsons]
+    res = MetaDataLoader().load(sources)
+    assert res.errors == [], res.errors
+    return res.root
+
+
 def _ctx(root) -> GenContext:
     return GenContext(
         entities=[],
@@ -156,6 +165,35 @@ def test_email_order_email_renders_nested_array_loop_and_partial(tmp_path) -> No
     assert "<hr/>Sent by Acme" in doc.html_body
 
 
+# ---------------------------------------------------------------------------
+# xpkg-collision/ — cross-package short-name collision (ADR-0041). Two packages
+# each declare an object.value `Note` (alpha: alphaText, beta: betaText); the
+# payload `Digest` references BOTH by FULLY-QUALIFIED @objectRef. A bare-tail
+# resolver binds both refs to whichever Note loads first → one field lands on the
+# wrong element type → the drift gate raises. FQN-exact resolution renders both.
+# ---------------------------------------------------------------------------
+
+
+def test_document_digest_doc_resolves_fqn_nested_object_ref_across_collision(tmp_path) -> None:
+    dir_root = CORPUS / "xpkg-collision"
+    root = _load_root_from_files(
+        dir_root / "meta.alpha.json",
+        dir_root / "meta.beta.json",
+        dir_root / "meta.app.json",
+    )
+    templates = str(CORPUS / "templates")
+    # Must NOT raise: the FQN refs resolve to their own package's Note.
+    files = [f for f in RenderHelperGenerator(templates).generate(_ctx(root))
+             if f.path == "digest_doc_render_helper.py"]
+    assert len(files) == 1
+    _materialize_and_import(files, tmp_path)
+    helper = import_module("_rh_conf_pkg.digest_doc_render_helper")
+
+    payload = {"fromAlpha": {"alphaText": "AA"}, "fromBeta": {"betaText": "BB"}}
+    out = helper.render_digest_doc(payload, FilesystemProvider(templates))
+    assert out == "Alpha=AA Beta=BB"
+
+
 # ---------------------------------------------------------------------------
 # drift/ → codegen FAILS (ValueError) with ERR_VAR_NOT_ON_PAYLOAD.
 # ---------------------------------------------------------------------------