metaobjects 0.9.0__py3-none-any.whl

metaobjects/source/json_path.py

@@ -0,0 +1,106 @@
+"""FR5a / ADR-0009 — Canonical JSONPath builder.
+
+Construction rules (cross-port-aligned; every port emits this canonical form
+byte-identically):
+    * Root is ``$``.
+    * Object keys matching ``^[A-Za-z_][A-Za-z0-9_]*$`` use dot notation: ``.foo``.
+    * All other keys use single-quoted bracket form: ``['my-key']``,
+      ``['@attr']``. Embedded single quotes are escaped with ``\\'``.
+    * Array indices use bracket form: ``[N]`` (zero-based).
+    * No trailing dots, no whitespace.
+
+Mirrors:
+    * TS  — `server/typescript/packages/metadata/src/json-path.ts`
+    * C#  — `server/csharp/MetaObjects/Source/JsonPath.cs`
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional, Union
+
+# Identifier regex shared with the static :class:`JsonPath` helpers. Compiled
+# once at module load.
+_IDENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _render_key_segment(key: str) -> str:
+    """Render a single object-key segment: dot notation if identifier-safe, else bracket form."""
+    if _IDENT_RE.match(key):
+        return f".{key}"
+    escaped = key.replace("'", "\\'")
+    return f"['{escaped}']"
+
+
+def _render_index_segment(idx: int) -> str:
+    """Render a single array-index segment: ``[N]``."""
+    return f"[{idx}]"
+
+
+class JsonPathBuilder:
+    """Builds the canonical JSONPath string for a node as the parser walks the
+    JSON tree. Push a key or index when descending; pop when returning.
+
+    Mirrors ``JsonPathBuilder`` in
+    ``typescript/packages/metadata/src/json-path.ts`` and the C# implementation.
+    """
+
+    __slots__ = ("_segments",)
+
+    def __init__(self) -> None:
+        # Each segment is (kind, payload): kind is "key" or "index".
+        self._segments: list[tuple[str, Union[str, int]]] = []
+
+    def push_key(self, key: str) -> None:
+        """Push an object key segment (e.g. ``.foo`` or ``['my-key']``)."""
+        self._segments.append(("key", key))
+
+    def push_index(self, idx: int) -> None:
+        """Push an array-index segment (e.g. ``[2]``)."""
+        self._segments.append(("index", idx))
+
+    def pop(self) -> None:
+        """Pop the most recently pushed segment."""
+        if self._segments:
+            self._segments.pop()
+
+    @property
+    def depth(self) -> int:
+        """Number of segments currently on the stack (root is segment 0; not counted)."""
+        return len(self._segments)
+
+    def to_string(self) -> str:
+        """Render the current stack as a canonical JSONPath string."""
+        parts: list[str] = ["$"]
+        for kind, payload in self._segments:
+            if kind == "index":
+                # mypy-friendly: cast not needed; assignment ensures int.
+                parts.append(_render_index_segment(int(payload)))
+            else:
+                parts.append(_render_key_segment(str(payload)))
+        return "".join(parts)
+
+    def __str__(self) -> str:  # pragma: no cover — convenience
+        return self.to_string()
+
+
+class JsonPath:
+    """Static helpers for one-shot JSONPath rendering when a builder is overkill.
+
+    Equivalent to the C# ``JsonPath`` static helpers; namespaced as a class so
+    the call sites read identically in Python (``JsonPath.segment_for_key(...)``).
+    """
+
+    @staticmethod
+    def segment_for_key(key: str) -> str:
+        """Render a single object-key segment as it would appear in canonical
+        form, without the leading ``$`` — i.e. ``.foo`` or ``['my-key']``.
+        """
+        return _render_key_segment(key)
+
+    @staticmethod
+    def segment_for_index(idx: int) -> str:
+        """Render a single array-index segment: ``[N]``."""
+        return _render_index_segment(idx)
+
+
+__all__ = ["JsonPath", "JsonPathBuilder"]

metaobjects/source/semantic_diff.py

@@ -0,0 +1,98 @@
+"""FR5a / ADR-0009 — Cross-port-aligned semantic-equality compare for metadata
+trees. Returns ``True`` if the two inputs differ in any semantically-meaningful
+way (excluding ``source``, which is loader output).
+
+Algorithm (ADR-0009 §semantic_diff):
+
+    1. Sort attrs lexicographically; compare attr-by-attr; values by canonical
+       structural equality (key-order independent, whitespace-insensitive).
+    2. Children are compared as ordered sequences.
+    3. Reserved structural keys (``name``, ``package``, ``extends``,
+       ``abstract``, ``overlay``, ``isArray``, ``value``) participate like attrs.
+    4. ``source`` excluded from the diff.
+
+FR5a does not exercise this — FR5c will consume the boolean to drive the
+duplicate-with-no-change ``WARN_DUPLICATE_DECLARATION`` path. We ship the
+skeleton + tests now so the port is ready when FR5c lands.
+
+Mirrors:
+    * TS  — `server/typescript/packages/metadata/src/semantic-diff.ts`
+    * C#  — `server/csharp/MetaObjects/Source/SemanticDiff.cs`
+"""
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, Union
+
+if TYPE_CHECKING:  # avoid an import cycle (MetaData imports `..source`).
+    from ..meta.meta_data import MetaData
+
+# Keys excluded from the structural diff: ``source`` is loader output, not
+# metadata. Documented for parity with the C# constant set.
+_EXCLUDED_KEYS: frozenset[str] = frozenset({"source"})
+
+JsonValue = Union[None, bool, int, float, str, list[Any], dict[str, Any]]
+
+
+def semantic_diff(a: "Union[MetaData, JsonValue]", b: "Union[MetaData, JsonValue]") -> bool:
+    """Return ``True`` when *a* and *b* differ in any semantically-meaningful
+    way; otherwise ``False``.
+
+    Inputs may be:
+        * Two :class:`MetaData` instances — both are serialized to canonical
+          JSON and the resulting trees are compared. Useful for the
+          overlay-merge consumer in FR5c.
+        * Two raw JSON values (dict / list / scalar) — compared directly.
+    """
+    # Lazy import to break the meta_data ↔ source cycle: MetaData imports
+    # `..source` at module load to default `_source` to CodeSource.DEFAULT.
+    from ..meta.meta_data import MetaData as _MetaData
+    from ..serializer_json import canonical_serialize
+
+    if isinstance(a, _MetaData) and isinstance(b, _MetaData):
+        serialized_a = canonical_serialize(a)
+        serialized_b = canonical_serialize(b)
+        # Fast path: byte-identical canonical output → no diff.
+        if serialized_a == serialized_b:
+            return False
+        return not _equal(json.loads(serialized_a), json.loads(serialized_b))
+    # Raw-value path.
+    return not _equal(a, b)
+
+
+def _equal(a: Any, b: Any) -> bool:  # noqa: ANN401 — recursive JSON value compare
+    """Structural equality with the ADR-0009 rules: key-order independent for
+    dicts; ordered for lists; ``source`` excluded; values compared via Python
+    equality (which collapses ``True == 1`` etc. — matches the TS/C# behaviour
+    where canonical-JSON output is the comparison substrate).
+    """
+    if a is None and b is None:
+        return True
+    if a is None or b is None:
+        return False
+
+    if isinstance(a, dict) and isinstance(b, dict):
+        a_keys = sorted(k for k in a if k not in _EXCLUDED_KEYS)
+        b_keys = sorted(k for k in b if k not in _EXCLUDED_KEYS)
+        if a_keys != b_keys:
+            return False
+        for k in a_keys:
+            if not _equal(a[k], b[k]):
+                return False
+        return True
+
+    if isinstance(a, list) and isinstance(b, list):
+        if len(a) != len(b):
+            return False
+        for ai, bi in zip(a, b):
+            if not _equal(ai, bi):
+                return False
+        return True
+
+    # Scalars / mismatched container types fall through to value equality.
+    # bool / int collapse the way Python does (True == 1) — matches what the TS
+    # / C# canonical-JSON byte-compare produces on whole-number floats etc.
+    return bool(a == b)
+
+
+__all__ = ["semantic_diff"]

metaobjects/source/yaml_positions.py

@@ -0,0 +1,174 @@
+"""FR5b — YAML authoring source-position carrier + walker (per ADR-0009).
+
+Mirrors the TS reference split across:
+    * server/typescript/packages/metadata/src/core/yaml-positions.ts
+      (pure types + Symbol carrier + accessors)
+    * server/typescript/packages/metadata/src/core/yaml-positions-walker.ts
+      (YAML AST → JS walker that attaches position-by-key maps)
+
+The TS reference splits these for browser-bundle safety (the walker imports
+``yaml``, which is Node-only). Python has no such boundary — both layers live
+here in one module.
+
+Source-map carrier (the FR5b spec's "open question" §2): TS uses a Symbol-keyed,
+non-enumerable property on each mapping object. Python's equivalent is a
+``dict`` subclass (:class:`YamlPositionMap`) with a private ``_yaml_positions``
+slot. Rationale:
+
+    * ``isinstance(d, dict)`` is still ``True`` — code that walks the parsed
+      structure as plain dicts is unaffected.
+    * ``json.dumps`` and ``for k in d`` ignore non-key attributes (the
+      slot is invisible to standard iteration/serialization, matching the
+      "non-enumerable" property of the TS Symbol-keyed prop).
+    * No parallel ``id(obj) → positions`` sidecar to keep in sync — the
+      position rides with the dict it describes.
+
+On desugar-synthesized nodes (Rule 2's scalar-body lift): the synthesized body
+``{ name: rawScalar }`` inherits the wrapper key's position from the parent's
+position map. On any other synthesis (Rule 4's isArray stamping, Rule 5's
+``@``-prefix rewrite), the position survives because the desugar carries the
+position map across the rewrite.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import yaml  # type: ignore[import-untyped]  # PyYAML ships no type stubs
+
+from .error_source import YamlPosition
+
+
+class YamlPositionMap(dict):
+    """A ``dict`` subclass that carries a sidecar position-by-key map.
+
+    The carrier of FR5b YAML positions. Instances of this class behave as
+    plain ``dict`` for every consumer that does not know to look (iteration,
+    ``in``, ``json.dumps``, ``isinstance`` checks), but expose a private
+    ``_yaml_positions`` slot that the loader reads to surface
+    :class:`YamlPosition` data on ``node.source``.
+
+    Key (string) → :class:`YamlPosition` (line, col, 1-based).
+    """
+
+    __slots__ = ("_yaml_positions",)
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._yaml_positions: dict[str, YamlPosition] = {}
+
+
+def get_position_map(obj: Any) -> Optional[dict[str, YamlPosition]]:
+    """Read the position-by-key map from a value, if present.
+
+    Returns ``None`` for primitives, lists, ``None``, and untagged dicts.
+    Only :class:`YamlPositionMap` instances carry a map.
+    """
+    if isinstance(obj, YamlPositionMap):
+        return obj._yaml_positions
+    return None
+
+
+def get_yaml_position(obj: Any, key: str) -> Optional[YamlPosition]:
+    """Read the position for a specific key on a mapping object.
+
+    Returns ``None`` when the mapping is not a :class:`YamlPositionMap` or
+    the key has no recorded position.
+    """
+    pmap = get_position_map(obj)
+    if pmap is None:
+        return None
+    return pmap.get(key)
+
+
+def set_position_map(
+    obj: YamlPositionMap,
+    positions: dict[str, YamlPosition],
+) -> None:
+    """Attach (or replace) the position-by-key map on a mapping object.
+
+    Mirrors TS ``setPositionMap`` — the map is stored on the dict's private
+    slot, invisible to ``for k in d`` / ``json.dumps``.
+    """
+    obj._yaml_positions = positions
+
+
+# ---------------------------------------------------------------------------
+# Walker — YAML AST → Python dict tree with positions attached
+# ---------------------------------------------------------------------------
+
+
+def parse_yaml_with_positions(text: str) -> Any:
+    """Parse YAML text and return a Python structure with positions attached.
+
+    Mirrors the contract of :func:`yaml.safe_load` for the shapes the
+    metaobjects authoring grammar uses (mappings, sequences, scalars). Aliases
+    are resolved via the underlying SafeLoader pipeline — i.e. they resolve
+    as the library normally would.
+
+    Every mapping in the resulting structure is a :class:`YamlPositionMap`
+    with a populated ``_yaml_positions`` sidecar; the (1-based) line/col is
+    the position of the KEY token in the YAML source.
+
+    Raises:
+        :class:`yaml.YAMLError`: on YAML syntax errors (same as
+            ``yaml.safe_load``).
+    """
+    loader = yaml.SafeLoader(text)
+    try:
+        node = loader.get_single_node()
+        if node is None:
+            return None
+        return _yaml_node_to_py(node, loader)
+    finally:
+        loader.dispose()
+
+
+def _yaml_node_to_py(node: Any, loader: Any) -> Any:
+    """Walk a yaml AST node into a Python structure.
+
+    For each :class:`yaml.MappingNode`, attach a position-by-key map (via
+    :class:`YamlPositionMap`) onto the resulting dict — the position of each
+    key is the (line, col) of the KEY token in the YAML source.
+
+    Scalar nodes are constructed via the SafeLoader's constructor pipeline,
+    so YAML 1.1's typed scalars (null, bool, int, float) coerce exactly the
+    way :func:`yaml.safe_load` produces them. The desugar's D2 coercion
+    guard fires on those coerced values, matching TS / Java / C# behavior.
+    """
+    if isinstance(node, yaml.ScalarNode):
+        return loader.construct_object(node, deep=True)
+    if isinstance(node, yaml.SequenceNode):
+        return [_yaml_node_to_py(item, loader) for item in node.value]
+    if isinstance(node, yaml.MappingNode):
+        out = YamlPositionMap()
+        positions: dict[str, YamlPosition] = {}
+        for key_node, value_node in node.value:
+            # Only string-keyed entries are valid in metaobjects authoring;
+            # ignore exotic keys (numeric / complex) — they would already
+            # break the desugar.
+            if not isinstance(key_node, yaml.ScalarNode):
+                continue
+            key_text = str(key_node.value)
+            value = _yaml_node_to_py(value_node, loader)
+            out[key_text] = value
+            # start_mark is 0-indexed; FR5b positions are 1-indexed.
+            mark = key_node.start_mark
+            if mark is not None:
+                positions[key_text] = YamlPosition(
+                    line=mark.line + 1, col=mark.column + 1
+                )
+        if positions:
+            set_position_map(out, positions)
+        return out
+    # Tags / unsupported — fall back to None. The metaobjects authoring
+    # grammar does not use them.
+    return None
+
+
+__all__ = [
+    "YamlPositionMap",
+    "get_position_map",
+    "get_yaml_position",
+    "set_position_map",
+    "parse_yaml_with_positions",
+]

metaobjects/super_resolve.py

@@ -0,0 +1,128 @@
+"""Deferred super/extends resolution over the merged tree (2nd pass, pre-freeze).
+
+Mirrors TS ``resolveDeferredSupers`` in super-resolve.ts:
+- Walk the tree over own_children(), tracking an inherited context package.
+- Build the FQN index keyed by node.fqn() (own).
+- For each node with an unresolved super_ref, resolve using
+  ``effective_pkg = node.package or inherited_context_pkg``.
+"""
+from __future__ import annotations
+
+from .errors import ErrorCode, MetaError
+from .meta.meta_data import MetaData
+from .shared.separators import PACKAGE_SEP
+from .source import resolved_source
+
+
+def resolve_supers(root: MetaData, errors: list[MetaError]) -> None:
+    """Walk every node in the merged tree; for each unresolved super_ref, resolve it.
+
+    Resolved → sets node.super_data.
+    Unresolved → appends ERR_UNRESOLVED_SUPER to errors.
+    Already-resolved nodes (super_data is not None) are skipped (idempotent).
+    """
+    index = _build_index(root)
+    _walk(root, "", index, errors)
+
+
+def _walk(
+    node: MetaData,
+    ctx_pkg: str,
+    index: dict[str, MetaData],
+    errors: list[MetaError],
+) -> None:
+    """Visit *node* then recurse over own_children(), carrying an inherited context package."""
+    if node.super_ref and node.super_data is None:
+        # Referrer context package: own ``package`` if declared, else the
+        # file-default package captured at parse time, else the inherited
+        # walk context. Using file_default_package (not just the threaded
+        # ctx_pkg) is what lets a bare / same-package / cross-package
+        # ``extends`` resolve over the MERGED tree, where object nodes carry
+        # no own package and the parent chain no longer reaches the per-file
+        # root. Mirrors TS ``resolveDeferredSupers``
+        # (``node.package ?? node.fileDefaultPackage``).
+        effective_pkg = node.package or node.file_default_package or ctx_pkg or None
+        target = _resolve(node.super_ref, effective_pkg, index)
+        if target is None:
+            # FR5d / ADR-0009: emit a ResolvedSource envelope carrying the
+            # referrer's files / json_path plus the referrer FQN + unresolved
+            # target. Mirrors TS resolveDeferredSupers in meta-data-loader.ts.
+            errors.append(MetaError(
+                f"the SuperClass '{node.super_ref}' does not exist "
+                f"(referenced by {node.fqn()})",
+                ErrorCode.ERR_UNRESOLVED_SUPER,
+                path=node.fqn(),
+                envelope=resolved_source(node.source, node.fqn(), node.super_ref),
+            ))
+        else:
+            node.super_data = target
+
+    # The context package for children is this node's own package, if set, else inherit.
+    next_ctx = node.package or ctx_pkg
+    for child in node.own_children():
+        _walk(child, next_ctx, index, errors)
+
+
+def _build_index(root: MetaData) -> dict[str, MetaData]:
+    """Build a lookup index over the whole merged tree (own_children walk).
+
+    Each named node is registered under its own ``fqn()`` AND — when it has no
+    own ``package`` but a file-default package was captured at parse time —
+    under the package-folded key ``<file_default_package>::<name>``. The second
+    key is what makes a cross-package fully-qualified ``extends`` resolve over
+    the merged tree (object ``fqn()`` stays bare because the parser does not
+    fold the file-default package onto the object's own package). Mirrors the
+    TS ``findInTree`` matcher (own ``fqn()`` OR ``resolutionKey()``).
+    """
+    idx: dict[str, MetaData] = {}
+    _index_walk(root, idx)
+    return idx
+
+
+def _index_walk(node: MetaData, idx: dict[str, MetaData]) -> None:
+    if node.name:
+        idx.setdefault(node.fqn(), node)
+        if not node.package and node.file_default_package:
+            folded = f"{node.file_default_package}{PACKAGE_SEP}{node.name}"
+            idx.setdefault(folded, node)
+    for child in node.own_children():
+        _index_walk(child, idx)
+
+
+def _resolve(
+    ref: str, context_pkg: str | None, index: dict[str, MetaData]
+) -> MetaData | None:
+    """Resolve a super_ref string against the FQN index.
+
+    Resolution forms:
+    - absolute ``::pkg::Name``  → strip leading ``::``, look up ``pkg::Name``.
+    - relative ``..::rest``     → count leading ``..::`` levels; if levels exceed
+                                  context depth or remainder is empty → ``None``
+                                  (→ ERR_UNRESOLVED_SUPER); else look up
+                                  ``reducedCtx::rest`` (mirrors TS exactly).
+    - bare/qualified ``Name``   → try ``context::ref`` first, then bare ``ref``.
+    """
+    abs_prefix = PACKAGE_SEP  # "::"
+    rel_prefix = ".." + PACKAGE_SEP  # "..::
+
+    if ref.startswith(abs_prefix):                          # absolute ::pkg::Name
+        return index.get(ref[len(abs_prefix):])
+
+    if ref.startswith(rel_prefix):                          # relative ..::rest
+        parts = ref.split(PACKAGE_SEP)
+        levels = 0
+        while levels < len(parts) and parts[levels] == "..":
+            levels += 1
+        pkg_parts = context_pkg.split(PACKAGE_SEP) if context_pkg else []
+        remainder = parts[levels:]
+        if len(pkg_parts) < levels or len(remainder) == 0:
+            return None
+        all_parts = pkg_parts[: len(pkg_parts) - levels] + remainder
+        return index.get(PACKAGE_SEP.join(all_parts))
+
+    # bare or pkg-qualified (no leading :: / ..)
+    if context_pkg:
+        hit = index.get(f"{context_pkg}{PACKAGE_SEP}{ref}")
+        if hit is not None:
+            return hit
+    return index.get(ref)