metaobjects 0.9.0__py3-none-any.whl

metaobjects/loader/meta_data_loader.py

@@ -0,0 +1,245 @@
+"""MetaDataLoader: source-polymorphic loader.
+
+The cross-language Tier-1 loader: takes a list of MetaDataSource impls,
+runs parse -> merge -> super-resolve -> validate -> freeze, and returns a
+LoadResult { root, errors, warnings }.
+
+Source format (JSON vs YAML) is declared by the source, not sniffed by the
+loader. This replaces both the per-file extension switch from the old
+free function and the TS FileMetaDataLoader.parseSource override.
+
+The three class-method factories (from_directory / from_uris / from_string)
+cover the 99% case; module-level shortcuts in `metaobjects.__init__` wrap
+them with Pythonic ergonomics.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ..core_types import core_providers
+from ..errors import ErrorCode, MetaError, ParseError
+from ..meta.meta_data import MetaData
+from ..meta.meta_root import MetaRoot
+from ..parser import ParseResult, parse_document
+from ..parser_yaml import parse_yaml
+from ..provider import Provider, compose_registry
+from ..registry import TypeRegistry
+from ..shared.base_types import SUBTYPE_ROOT, TYPE_METADATA
+from ..source import CodeSource, ErrorSource, JsonSource, LoaderWarning
+from ..super_resolve import resolve_supers
+from .merge import merge_roots
+from .sources import (
+    DirectorySource,
+    InMemoryStringSource,
+    MetaDataFormat,
+    MetaDataSource,
+    UriSource,
+)
+from .validation_passes import run_validations
+
+
+@dataclass
+class LoadResult:
+    """The Tier-1 load result. Same field shape across all four ports."""
+
+    root: MetaData
+    errors: list[MetaError] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    # FR5c — envelope-shaped warnings (e.g. ``WARN_DUPLICATE_DECLARATION``)
+    # produced during parse / merge. Distinct from the legacy
+    # ``warnings: list[str]`` channel: those flow through the parser /
+    # validator surface as plain strings and get wrapped at the loader
+    # boundary (or surfaced verbatim by the conformance runner for the
+    # expected-warnings.json check); envelope warnings already carry their
+    # own ``code`` + ``source``. Mirrors TS ``LoadResult.warnings`` (whose
+    # singular channel ships ``LoaderWarning`` envelopes after the FR5c
+    # WARN_LEGACY-wrapping pass).
+    envelope_warnings: list[LoaderWarning] = field(default_factory=list)
+
+    def get_envelope_warnings(self) -> list[LoaderWarning]:
+        """FR5c — accessor mirroring TS ``loader.envelopeWarnings`` /
+        Java ``loader.getEnvelopeWarnings()``.
+
+        Returns the in-order list of envelope-shaped warnings (typed with a
+        ``code`` + ``source`` envelope) produced during parse / merge. The
+        legacy string channel (``self.warnings``) is unchanged.
+        """
+        return list(self.envelope_warnings)
+
+
+class MetaDataLoader:
+    """Source-polymorphic metadata loader.
+
+    Construct once with a provider list (defaults to ``core_providers`` —
+    core types + DB-domain + documentation + template/output domain);
+    call ``.load(sources)`` for arbitrary source combinations, or use the
+    ``from_*`` class-method factories for the common cases.
+    """
+
+    def __init__(
+        self,
+        providers: list[Provider] | None = None,
+        strict: bool = False,
+    ) -> None:
+        self._registry: TypeRegistry = compose_registry(
+            providers if providers is not None else list(core_providers)
+        )
+        # ADR-0023 — strict load closes the open-attr policy: an authored own
+        # @-attr matching no per-type schema and no commonAttr → ERR_UNKNOWN_ATTR
+        # (alongside Python's always-on unknown TYPE/SUBTYPE rejection). Defaults
+        # False so a downstream app keeps the legacy open-attr behavior; the
+        # library's own conformance corpora load strict.
+        self._strict: bool = strict
+
+    @property
+    def registry(self) -> TypeRegistry:
+        return self._registry
+
+    # --- core API ------------------------------------------------------
+
+    def load(self, sources: list[MetaDataSource]) -> LoadResult:
+        """Parse -> merge -> super-resolve -> validate -> freeze."""
+        # Canonical empty root (matches parse_document's seed).
+        result = LoadResult(root=MetaRoot(TYPE_METADATA, SUBTYPE_ROOT, ""))
+        roots: list[MetaData] = []
+
+        for src in sources:
+            parsed = self._parse_source(src, result.errors)
+            if parsed is None:
+                continue
+            result.errors.extend(parsed.errors)
+            result.warnings.extend(parsed.warnings)
+            # FR5c — collect envelope-shaped warnings from each parse pass.
+            # Today these only arrive from merge sites (see merge_roots);
+            # the channel is exposed here for future parser-emitted ones.
+            result.envelope_warnings.extend(parsed.envelope_warnings)
+            if not parsed.errors:
+                roots.append(parsed.root)
+
+        if roots:
+            # FR5c — merge_roots is the site that emits ERR_MERGE_CONFLICT
+            # into errors and WARN_DUPLICATE_DECLARATION into both channels
+            # (legacy string + envelope) so the conformance runner's
+            # expected-warnings.json check sees the string forms while
+            # downstream tooling can consume the envelope shape.
+            result.root = merge_roots(
+                roots,
+                result.errors,
+                result.warnings,
+                result.envelope_warnings,
+            )
+            resolve_supers(result.root, result.errors)
+
+        run_validations(
+            result.root,
+            self._registry,
+            result.errors,
+            result.warnings,
+            envelope_warnings=result.envelope_warnings,
+            strict=self._strict,
+        )
+        result.root.freeze()
+        return result
+
+    # --- static factories (the 99% case, cross-language consistent) ----
+
+    @classmethod
+    def from_directory(
+        cls,
+        directory: Path | str,
+        providers: list[Provider] | None = None,
+        exclude: list[str] | None = None,
+        recurse: bool = True,
+        strict: bool = False,
+    ) -> LoadResult:
+        """Load every JSON/YAML file under ``directory`` (recursive by default).
+
+        ``strict`` (ADR-0023) — when True, an undeclared own ``@-attr`` →
+        ``ERR_UNKNOWN_ATTR``. Defaults False (downstream-friendly open policy).
+        """
+        loader = cls(providers=providers, strict=strict)
+        sources = list(
+            DirectorySource(directory, exclude=exclude, recurse=recurse).expand()
+        )
+        return loader.load(sources)
+
+    @classmethod
+    def from_uris(
+        cls,
+        uris: list[str],
+        providers: list[Provider] | None = None,
+        strict: bool = False,
+    ) -> LoadResult:
+        """Load metadata from a list of URIs (file:// or http(s)://).
+
+        ``strict`` (ADR-0023) — see :meth:`from_directory`.
+        """
+        loader = cls(providers=providers, strict=strict)
+        return loader.load([UriSource(u) for u in uris])
+
+    @classmethod
+    def from_string(
+        cls,
+        content: str,
+        format: MetaDataFormat = MetaDataFormat.JSON,
+        providers: list[Provider] | None = None,
+        strict: bool = False,
+    ) -> LoadResult:
+        """Load metadata from an in-memory string (defaults to JSON).
+
+        ``strict`` (ADR-0023) — see :meth:`from_directory`.
+        """
+        loader = cls(providers=providers, strict=strict)
+        return loader.load([InMemoryStringSource(content, format=format)])
+
+    # --- internals -----------------------------------------------------
+
+    def _parse_source(
+        self, src: MetaDataSource, errors: list[MetaError]
+    ) -> ParseResult | None:
+        """Read a source's content and dispatch to the JSON or YAML parser.
+
+        Returns ``None`` if the source could not be read or its syntax was
+        malformed; the caller appends an error and skips this source from
+        the merge set.
+        """
+        # FR5a / ADR-0009 — top-level envelope for the source. Until the parser
+        # walk descends, the offending location is the root (`$`). Matches C#
+        # Parser.cs:140 — only fall back to CodeSource when there is no source
+        # id at all; "<inline>" is a valid source identifier and must yield a
+        # JsonSource so envelope formats remain consistent across error sites.
+        envelope: ErrorSource = (
+            JsonSource(files=(src.id,), json_path="$")
+            if src.id
+            else CodeSource.DEFAULT
+        )
+
+        try:
+            text = src.read()
+        except OSError as exc:
+            errors.append(MetaError(
+                str(exc), ErrorCode.ERR_UNKNOWN, src.id, envelope=envelope,
+            ))
+            return None
+
+        match src.format:
+            case MetaDataFormat.YAML:
+                try:
+                    return parse_yaml(text, self._registry, source=src.id)
+                except ParseError as exc:
+                    errors.append(MetaError(
+                        str(exc), exc.code, src.id, envelope=envelope,
+                    ))
+                    return None
+            case MetaDataFormat.JSON:
+                try:
+                    doc = json.loads(text)
+                except json.JSONDecodeError as exc:
+                    errors.append(MetaError(
+                        str(exc), ErrorCode.ERR_MALFORMED_JSON, src.id,
+                        envelope=envelope,
+                    ))
+                    return None
+                return parse_document(doc, self._registry, source=src.id)

metaobjects/loader/sources/__init__.py

@@ -0,0 +1,24 @@
+"""Polymorphic MetaDataSource implementations.
+
+The cross-language Tier-1 contract: every source declares an identity (for
+error locations), a format (json | yaml), and a read() returning the decoded
+text content. File / directory / URI / in-memory sources are all just
+implementations of that contract — the loader is source-agnostic.
+
+See `docs/superpowers/specs/2026-05-25-cross-language-loader-architecture-unification.md`.
+"""
+from __future__ import annotations
+
+from .directory_source import DirectorySource
+from .file_source import FileSource
+from .meta_data_source import InMemoryStringSource, MetaDataFormat, MetaDataSource
+from .uri_source import UriSource
+
+__all__ = [
+    "MetaDataFormat",
+    "MetaDataSource",
+    "InMemoryStringSource",
+    "FileSource",
+    "DirectorySource",
+    "UriSource",
+]

metaobjects/loader/sources/directory_source.py

@@ -0,0 +1,50 @@
+"""Directory expander -> sorted list of FileSource.
+
+Walks the directory (recursively by default), filters to supported authoring
+extensions (``.json`` / ``.yaml`` / ``.yml``), honors a name-based exclude
+list, and yields FileSource instances in deterministic ordinal-filename
+order. Deterministic order is required because overlay merging is
+order-sensitive (last-writer-wins on attr conflicts).
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+
+from .file_source import FileSource
+
+_SUPPORTED_SUFFIXES = (".json", ".yaml", ".yml")
+
+
+class DirectorySource:
+    """Expands a directory into a sorted, filtered list of FileSource objects."""
+
+    def __init__(
+        self,
+        directory: Path | str,
+        exclude: Iterable[str] | None = None,
+        recurse: bool = True,
+    ) -> None:
+        self._directory = Path(directory)
+        self._exclude = set(exclude or ())
+        self._recurse = recurse
+
+    @property
+    def directory(self) -> Path:
+        return self._directory
+
+    def expand(self) -> Iterator[FileSource]:
+        candidates = (
+            self._directory.rglob("*") if self._recurse else self._directory.iterdir()
+        )
+        files = sorted(
+            (
+                p
+                for p in candidates
+                if p.is_file()
+                and p.suffix.lower() in _SUPPORTED_SUFFIXES
+                and p.name not in self._exclude
+            ),
+            key=lambda p: p.name,
+        )
+        yield from (FileSource(p) for p in files)

metaobjects/loader/sources/file_source.py

@@ -0,0 +1,41 @@
+"""Single-file MetaDataSource.
+
+Format defaults to extension-derived (``.yaml`` / ``.yml`` -> YAML; otherwise
+JSON). Reads with ``utf-8-sig`` so a leading UTF-8 BOM is silently stripped —
+matches the prior `load_directory` behavior.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .meta_data_source import MetaDataFormat, MetaDataSource
+
+
+def _infer_format(path: Path) -> MetaDataFormat:
+    suffix = path.suffix.lower()
+    if suffix in (".yaml", ".yml"):
+        return MetaDataFormat.YAML
+    return MetaDataFormat.JSON
+
+
+class FileSource(MetaDataSource):
+    """A single on-disk file, decoded eagerly via ``utf-8-sig``."""
+
+    def __init__(self, path: Path | str, format: MetaDataFormat | None = None) -> None:
+        self._path = Path(path)
+        self._format = format if format is not None else _infer_format(self._path)
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @property
+    def id(self) -> str:
+        return self._path.name
+
+    @property
+    def format(self) -> MetaDataFormat:
+        return self._format
+
+    def read(self) -> str:
+        return self._path.read_text(encoding="utf-8-sig")

metaobjects/loader/sources/meta_data_source.py

@@ -0,0 +1,67 @@
+"""MetaDataSource abstract base + InMemoryStringSource impl.
+
+Tier-1 contract: identity (for MetaError.location), declared format, and a
+read() that returns decoded UTF-8 content.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import Enum
+
+
+class MetaDataFormat(str, Enum):
+    """Authoring format vocabulary. Cross-language Tier 1: lowercase strings."""
+
+    JSON = "json"
+    YAML = "yaml"
+
+
+class MetaDataSource(ABC):
+    """A source of metadata content.
+
+    Implementations declare identity + format up front; bytes may be read
+    eagerly or lazily (the loader treats `read()` as decoded text).
+    """
+
+    @property
+    @abstractmethod
+    def id(self) -> str:
+        """Stable identity used in MetaError.location (e.g. file name, URI, ``<inline>``)."""
+
+    @property
+    @abstractmethod
+    def format(self) -> MetaDataFormat:
+        """Declared authoring format. Source-declared, never sniffed by the loader."""
+
+    @abstractmethod
+    def read(self) -> str:
+        """Return the decoded text content."""
+
+
+class InMemoryStringSource(MetaDataSource):
+    """In-memory string source; no I/O.
+
+    Default identity is ``<inline>``; callers may pass a more descriptive id
+    (e.g. ``<test:foo>``) — it surfaces in MetaError.location.
+    """
+
+    def __init__(
+        self,
+        content: str,
+        id: str = "<inline>",
+        format: MetaDataFormat = MetaDataFormat.JSON,
+    ) -> None:
+        self._content = content
+        self._id = id
+        self._format = format
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def format(self) -> MetaDataFormat:
+        return self._format
+
+    def read(self) -> str:
+        return self._content

metaobjects/loader/sources/uri_source.py

@@ -0,0 +1,56 @@
+"""URI-backed MetaDataSource.
+
+Supports ``file://``, ``http://``, and ``https://`` schemes. Format defaults to
+extension-derived from the URI path; callers may override.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import urlparse
+from urllib.request import urlopen
+
+from .meta_data_source import MetaDataFormat, MetaDataSource
+
+
+def _infer_format(uri: str) -> MetaDataFormat:
+    path = urlparse(uri).path
+    suffix = Path(path).suffix.lower()
+    if suffix in (".yaml", ".yml"):
+        return MetaDataFormat.YAML
+    return MetaDataFormat.JSON
+
+
+class UriSource(MetaDataSource):
+    """A URI-backed source. Lazily fetched on ``read()``."""
+
+    def __init__(
+        self,
+        uri: str,
+        format: MetaDataFormat | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._uri = uri
+        self._format = format if format is not None else _infer_format(uri)
+        self._timeout = timeout
+
+    @property
+    def id(self) -> str:
+        return self._uri
+
+    @property
+    def format(self) -> MetaDataFormat:
+        return self._format
+
+    def read(self) -> str:
+        parsed = urlparse(self._uri)
+        if parsed.scheme == "file":
+            # urlparse splits the leading slashes off the path on file:// URIs.
+            return Path(parsed.path).read_text(encoding="utf-8-sig")
+        if parsed.scheme in ("http", "https"):
+            # Schemes are explicitly allowlisted (file/http/https) above; arbitrary
+            # URI handlers (ftp, etc.) reject with ValueError before urlopen is called.
+            with urlopen(self._uri, timeout=self._timeout) as resp:  # noqa: S310
+                return resp.read().decode("utf-8")
+        raise ValueError(
+            f"UriSource: unsupported scheme '{parsed.scheme}' on {self._uri}"
+        )

metaobjects/loader/validate_discriminator.py

@@ -0,0 +1,181 @@
+"""FR-014 — TPH discriminator cross-attribute rules.
+
+Codes (all errors):
+    * ``ERR_DISCRIMINATOR_FIELD_NOT_FOUND``     — ``@discriminator`` names a field
+      that does not exist on the entity (own or via extends chain).
+    * ``ERR_DISCRIMINATOR_VALUE_DUPLICATE``     — two subtypes of the same
+      ``@discriminator``-bearing root claim the same ``@discriminatorValue``.
+    * ``ERR_DISCRIMINATOR_VALUE_MISSING``       — a concrete (non-abstract) entity
+      extends a chain whose root carries ``@discriminator`` but lacks
+      ``@discriminatorValue``.
+    * ``ERR_DISCRIMINATOR_VALUE_TYPE_MISMATCH`` — ``@discriminatorValue`` cannot be
+      coerced to the discriminator field's subtype (enum: not in ``@values``;
+      integer-family: not numeric; string: always OK).
+
+Mirrors the TS reference
+``packages/metadata/src/core/object/validate-discriminator.ts``.
+"""
+from __future__ import annotations
+
+import re
+
+from ..errors import ErrorCode, MetaError
+from ..meta.meta_data import MetaData
+from ..meta.core.field.field_constants import (
+    FIELD_ATTR_VALUES,
+    FIELD_SUBTYPE_ENUM,
+    FIELD_SUBTYPE_INT,
+    FIELD_SUBTYPE_LONG,
+    FIELD_SUBTYPE_STRING,
+)
+from ..meta.core.object.object_constants import (
+    OBJECT_ATTR_DISCRIMINATOR,
+    OBJECT_ATTR_DISCRIMINATOR_VALUE,
+    OBJECT_SUBTYPE_ENTITY,
+)
+from ..shared.base_types import TYPE_FIELD, TYPE_OBJECT
+
+_NUMERIC_DISCRIMINATOR_SUBTYPES = frozenset(
+    {FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG}
+)
+_INT_RE = re.compile(r"^-?\d+$")
+
+
+def _find_field_on_entity(entity: MetaData, name: str) -> MetaData | None:
+    """A field with ``name`` on ``entity`` — own first, then via extends chain."""
+    for child in entity.own_children():
+        if child.type == TYPE_FIELD and child.name == name:
+            return child
+    cursor = entity.super_data
+    while cursor is not None:
+        for child in cursor.own_children():
+            if child.type == TYPE_FIELD and child.name == name:
+                return child
+        cursor = cursor.super_data
+    return None
+
+
+def _find_discriminator_root(entity: MetaData) -> tuple[MetaData | None, str | None]:
+    """First ancestor (or self) carrying ``@discriminator``: (root, fieldName)."""
+    cursor: MetaData | None = entity
+    while cursor is not None:
+        v = cursor.attr(OBJECT_ATTR_DISCRIMINATOR)
+        if isinstance(v, str) and v != "":
+            return cursor, v
+        cursor = cursor.super_data
+    return None, None
+
+
+def validate_discriminator(root: MetaData, errors: list[MetaError]) -> None:
+    entities = [
+        c
+        for c in root.own_children()
+        if c.type == TYPE_OBJECT and c.sub_type == OBJECT_SUBTYPE_ENTITY
+    ]
+
+    # Pass 1: @discriminator name resolution (own + inherited fields).
+    for obj in entities:
+        disc = obj.attr(OBJECT_ATTR_DISCRIMINATOR)
+        if not isinstance(disc, str) or disc == "":
+            continue
+        if _find_field_on_entity(obj, disc) is None:
+            errors.append(
+                MetaError(
+                    f'object.entity "{obj.name}" @discriminator: "{disc}" does not '
+                    "name a field on this entity (checked own children and the "
+                    "extends chain)",
+                    ErrorCode.ERR_DISCRIMINATOR_FIELD_NOT_FOUND,
+                    envelope=obj.source,
+                )
+            )
+
+    # Pass 2: @discriminatorValue type-check + collect bindings per root.
+    bindings_by_root: list[tuple[MetaData, list[tuple[MetaData, str]]]] = []
+    _root_index: dict[int, list[tuple[MetaData, str]]] = {}
+
+    for obj in entities:
+        value = obj.attr(OBJECT_ATTR_DISCRIMINATOR_VALUE)
+        if not isinstance(value, str) or value == "":
+            continue
+
+        disc_root, field_name = _find_discriminator_root(obj)
+        if disc_root is None or field_name is None:
+            continue
+        field = _find_field_on_entity(disc_root, field_name)
+        if field is None:
+            continue  # root's own ERR_DISCRIMINATOR_FIELD_NOT_FOUND already fires
+
+        if field.sub_type == FIELD_SUBTYPE_ENUM:
+            enum_values = field.attr(FIELD_ATTR_VALUES)
+            members = [str(v) for v in enum_values] if isinstance(enum_values, (list, tuple)) else []
+            if value not in members:
+                errors.append(
+                    MetaError(
+                        f'object.entity "{obj.name}" @discriminatorValue: "{value}" '
+                        f'is not a member of the discriminator enum field '
+                        f'"{field_name}" @values [{", ".join(members)}]',
+                        ErrorCode.ERR_DISCRIMINATOR_VALUE_TYPE_MISMATCH,
+                        envelope=obj.source,
+                    )
+                )
+        elif field.sub_type in _NUMERIC_DISCRIMINATOR_SUBTYPES:
+            if _INT_RE.match(value) is None:
+                errors.append(
+                    MetaError(
+                        f'object.entity "{obj.name}" @discriminatorValue: "{value}" '
+                        f'does not coerce to numeric discriminator field '
+                        f'"{field_name}" (field.{field.sub_type})',
+                        ErrorCode.ERR_DISCRIMINATOR_VALUE_TYPE_MISMATCH,
+                        envelope=obj.source,
+                    )
+                )
+        elif field.sub_type != FIELD_SUBTYPE_STRING:
+            # Non-{enum, integer-family, string} discriminators accepted silently.
+            pass
+
+        existing = _root_index.get(id(disc_root))
+        if existing is None:
+            existing = []
+            _root_index[id(disc_root)] = existing
+            bindings_by_root.append((disc_root, existing))
+        existing.append((obj, value))
+
+    # Pass 3: ERR_DISCRIMINATOR_VALUE_DUPLICATE within each root's subtypes.
+    for _disc_root, bindings in bindings_by_root:
+        seen: dict[str, MetaData] = {}
+        for subtype, value in bindings:
+            prev = seen.get(value)
+            if prev is not None:
+                errors.append(
+                    MetaError(
+                        f'object.entity "{subtype.name}" @discriminatorValue: '
+                        f'"{value}" duplicates the value already claimed by '
+                        f'"{prev.name}"',
+                        ErrorCode.ERR_DISCRIMINATOR_VALUE_DUPLICATE,
+                        envelope=subtype.source,
+                    )
+                )
+            else:
+                seen[value] = subtype
+
+    # Pass 4: ERR_DISCRIMINATOR_VALUE_MISSING — every concrete entity that extends
+    # a @discriminator-bearing root must declare a value.
+    for obj in entities:
+        if obj.is_abstract is True:
+            continue
+        if isinstance(obj.attr(OBJECT_ATTR_DISCRIMINATOR_VALUE), str):
+            continue
+        if isinstance(obj.attr(OBJECT_ATTR_DISCRIMINATOR), str):
+            continue  # a root, not a subtype
+        disc_root, _ = _find_discriminator_root(obj)
+        if disc_root is None or disc_root is obj:
+            continue
+        errors.append(
+            MetaError(
+                f'object.entity "{obj.name}" extends the @discriminator-bearing '
+                f'root "{disc_root.name}" but is missing @discriminatorValue '
+                "(required on every concrete subtype)",
+                ErrorCode.ERR_DISCRIMINATOR_VALUE_MISSING,
+                envelope=obj.source,
+            )
+        )