metaobjects 0.9.0__py3-none-any.whl

metaobjects/loader/validate_field_readonly.py

@@ -0,0 +1,146 @@
+"""FR-013 — field-level ``@readOnly`` cross-attribute rules.
+
+Codes:
+    * ``ERR_READONLY_ASSIGNED_PRIMARY`` — ``@readOnly: true`` on a field that is
+      the target of an ``identity.primary`` with ``@generation: "assigned"``.
+      The application has no path to populate the identity value.
+    * ``ERR_READONLY_DOWNGRADE`` — a concrete subtype declares ``@readOnly:
+      false`` on a field whose extends-chain parent declares ``@readOnly: true``.
+      Read-only-ness can only be upgraded, never downgraded.
+    * ``WARN_READONLY_VALUE_OBJECT`` — ``@readOnly: true`` on a field child of an
+      ``object.value``. No persistence semantics apply; advisory only.
+
+Mirrors the TS reference
+``packages/metadata/src/core/field/validate-field-readonly.ts``.
+"""
+from __future__ import annotations
+
+from ..errors import ErrorCode, MetaError
+from ..meta.meta_data import MetaData
+from ..meta.core.field.field_constants import FIELD_ATTR_READ_ONLY
+from ..meta.core.identity.identity_constants import (
+    GENERATION_ASSIGNED,
+    IDENTITY_ATTR_FIELDS,
+    IDENTITY_ATTR_GENERATION,
+    IDENTITY_SUBTYPE_PRIMARY,
+)
+from ..meta.core.object.object_constants import OBJECT_SUBTYPE_VALUE
+from ..shared.base_types import TYPE_FIELD, TYPE_IDENTITY, TYPE_OBJECT
+from ..source.error_source import LoaderWarning
+
+WARN_READONLY_VALUE_OBJECT = "WARN_READONLY_VALUE_OBJECT"
+
+
+def _read_only_flag(field: MetaData) -> bool | None:
+    """The explicit ``@readOnly`` value (True/False) or None when absent."""
+    v = field.attr(FIELD_ATTR_READ_ONLY)
+    return v if isinstance(v, bool) else None
+
+
+def _inherited_field(obj: MetaData, name: str) -> MetaData | None:
+    """Walk the extends chain for a field with ``name``; return its declaring
+    node (own attrs intact) if found."""
+    cursor = obj.super_data
+    while cursor is not None:
+        for c in cursor.own_children():
+            if c.type == TYPE_FIELD and c.name == name:
+                return c
+        cursor = cursor.super_data
+    return None
+
+
+def _primary_assigned_field_names(obj: MetaData) -> set[str]:
+    """Names of fields participating in any ``identity.primary`` with
+    ``@generation: "assigned"`` on ``obj`` or its extends chain (effective)."""
+    out: set[str] = set()
+    for ident in obj.children():
+        if ident.type != TYPE_IDENTITY:
+            continue
+        if ident.sub_type != IDENTITY_SUBTYPE_PRIMARY:
+            continue
+        if ident.attr(IDENTITY_ATTR_GENERATION) != GENERATION_ASSIGNED:
+            continue
+        fields = ident.attr(IDENTITY_ATTR_FIELDS)
+        if isinstance(fields, (list, tuple)):
+            for f_name in fields:
+                if isinstance(f_name, str):
+                    out.add(f_name)
+        elif isinstance(fields, str):
+            out.add(fields)
+    return out
+
+
+def validate_field_readonly(
+    root: MetaData,
+    errors: list[MetaError],
+    envelope_warnings: list[LoaderWarning] | None = None,
+    legacy_warnings: list[str] | None = None,
+) -> None:
+    for obj in root.own_children():
+        if obj.type != TYPE_OBJECT:
+            continue
+        is_value_object = obj.sub_type == OBJECT_SUBTYPE_VALUE
+
+        # 1) WARN_READONLY_VALUE_OBJECT — any @readOnly field child of object.value.
+        if is_value_object:
+            for child in obj.own_children():
+                if child.type == TYPE_FIELD and _read_only_flag(child) is True:
+                    msg = (
+                        f'field "{child.name}" on object.value "{obj.name}" '
+                        "declares @readOnly: true; value-objects have no "
+                        "persistence semantics so the read-only contract is "
+                        "advisory (codegen may use it for record/struct treatment)."
+                    )
+                    if envelope_warnings is not None:
+                        envelope_warnings.append(
+                            LoaderWarning(
+                                code=WARN_READONLY_VALUE_OBJECT,
+                                message=msg,
+                                source=child.source,
+                            )
+                        )
+                    if legacy_warnings is not None:
+                        legacy_warnings.append(WARN_READONLY_VALUE_OBJECT)
+
+        # 2) ERR_READONLY_DOWNGRADE — read-only-ness can only be upgraded across
+        #    extends. Only the explicit own @readOnly: false case matters.
+        for own_field in obj.own_children():
+            if own_field.type != TYPE_FIELD:
+                continue
+            if _read_only_flag(own_field) is not False:
+                continue
+            inherited = _inherited_field(obj, own_field.name)
+            if inherited is not None and _read_only_flag(inherited) is True:
+                errors.append(
+                    MetaError(
+                        f'field "{own_field.name}" on "{obj.name}" sets @readOnly: '
+                        "false, but the extends-chain parent declares @readOnly: "
+                        "true. Read-only-ness can only be upgraded, not downgraded "
+                        "(FR-013).",
+                        ErrorCode.ERR_READONLY_DOWNGRADE,
+                        envelope=own_field.source,
+                    )
+                )
+
+        # 3) ERR_READONLY_ASSIGNED_PRIMARY — @readOnly: true on a field used in an
+        #    identity.primary whose @generation is "assigned" (effective tree).
+        if not is_value_object:
+            assigned = _primary_assigned_field_names(obj)
+            if assigned:
+                for field in obj.children():
+                    if field.type != TYPE_FIELD:
+                        continue
+                    if field.name not in assigned:
+                        continue
+                    if _read_only_flag(field) is not True:
+                        continue
+                    errors.append(
+                        MetaError(
+                            f'field "{field.name}" on "{obj.name}" is @readOnly: '
+                            "true AND the target of identity.primary with "
+                            '@generation: "assigned"; the application has no path '
+                            "to populate the identity value (FR-013).",
+                            ErrorCode.ERR_READONLY_ASSIGNED_PRIMARY,
+                            envelope=field.source,
+                        )
+                    )

metaobjects/loader/validate_source_parameter_ref.py

@@ -0,0 +1,159 @@
+"""FR-015 — ``source.rdb`` ``@parameterRef`` typed-input rules.
+
+Codes:
+    * ``ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND`` — ``@parameterRef`` set with a
+      non-callable ``@kind`` (only ``storedProc`` / ``tableFunction`` accept
+      parameters). Checked before resolution so authoring mistakes surface first.
+    * ``ERR_PARAMETER_REF_UNRESOLVED`` — ``@parameterRef`` names a non-existent
+      object.
+    * ``ERR_PARAMETER_REF_NOT_VALUE_OBJECT`` — ``@parameterRef`` points at an
+      object that is not an ``object.value``.
+    * ``ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH`` — a parameter field uses
+      ``origin.passthrough @from: "Entity.field"`` but its subtype does not match
+      the referenced field's subtype.
+
+Mirrors the TS reference
+``packages/metadata/src/persistence/source/validate-source-parameter-ref.ts``.
+"""
+from __future__ import annotations
+
+from ..errors import ErrorCode, MetaError
+from ..meta.meta_data import MetaData
+from ..meta.persistence.source.meta_source import MetaSource
+from ..meta.persistence.source.source_constants import (
+    SOURCE_ATTR_PARAMETER_REF,
+    SOURCE_KIND_STORED_PROC,
+    SOURCE_KIND_TABLE_FUNCTION,
+    SOURCE_SUBTYPE_RDB,
+)
+from ..meta.core.object.object_constants import (
+    OBJECT_SUBTYPE_ENTITY,
+    OBJECT_SUBTYPE_VALUE,
+)
+from ..meta.persistence.origin.origin_constants import (
+    ORIGIN_ATTR_FROM,
+    ORIGIN_SUBTYPE_PASSTHROUGH,
+)
+from ..shared.base_types import TYPE_FIELD, TYPE_OBJECT, TYPE_ORIGIN, TYPE_SOURCE
+from ..shared.separators import PACKAGE_SEP
+
+_CALLABLE_KINDS = frozenset({SOURCE_KIND_STORED_PROC, SOURCE_KIND_TABLE_FUNCTION})
+
+
+def validate_source_parameter_ref(root: MetaData, errors: list[MetaError]) -> None:
+    # Pre-index every object by name AND fqn so resolution costs O(1) per source.
+    object_index: dict[str, MetaData] = {}
+    for obj in root.own_children():
+        if obj.type != TYPE_OBJECT:
+            continue
+        object_index[obj.name] = obj
+        fqn = (
+            f"{obj.package}{PACKAGE_SEP}{obj.name}"
+            if obj.package
+            else obj.name
+        )
+        object_index[fqn] = obj
+
+    for obj in root.own_children():
+        if obj.type != TYPE_OBJECT:
+            continue
+        for source in obj.own_children():
+            if source.type != TYPE_SOURCE or source.sub_type != SOURCE_SUBTYPE_RDB:
+                continue
+            if not isinstance(source, MetaSource):
+                continue
+            ref = source.attr(SOURCE_ATTR_PARAMETER_REF)
+            if not isinstance(ref, str) or ref == "":
+                continue
+
+            # ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND — before resolution.
+            if source.effective_kind() not in _CALLABLE_KINDS:
+                errors.append(
+                    MetaError(
+                        f'source.rdb on object "{obj.name}" has @parameterRef but '
+                        f'@kind is "{source.effective_kind()}"; only "storedProc" '
+                        'or "tableFunction" accept parameters',
+                        ErrorCode.ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND,
+                        envelope=source.source,
+                    )
+                )
+                continue
+
+            target = object_index.get(ref)
+            if target is None:
+                errors.append(
+                    MetaError(
+                        f'source.rdb on object "{obj.name}" @parameterRef = "{ref}" '
+                        "does not resolve to any known object",
+                        ErrorCode.ERR_PARAMETER_REF_UNRESOLVED,
+                        envelope=source.source,
+                    )
+                )
+                continue
+
+            if target.sub_type != OBJECT_SUBTYPE_VALUE:
+                reason = (
+                    "an object.entity (entities have identity; parameter shapes "
+                    "are value-objects)"
+                    if target.sub_type == OBJECT_SUBTYPE_ENTITY
+                    else f"an object.{target.sub_type}"
+                )
+                errors.append(
+                    MetaError(
+                        f'source.rdb on object "{obj.name}" @parameterRef = "{ref}" '
+                        f"resolves to {reason}; use an object.value",
+                        ErrorCode.ERR_PARAMETER_REF_NOT_VALUE_OBJECT,
+                        envelope=source.source,
+                    )
+                )
+                continue
+
+            # ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH — each parameter field
+            # with origin.passthrough must match the referenced field's subtype.
+            for param_field in target.own_children():
+                if param_field.type != TYPE_FIELD:
+                    continue
+                passthrough = next(
+                    (
+                        c
+                        for c in param_field.own_children()
+                        if c.type == TYPE_ORIGIN
+                        and c.sub_type == ORIGIN_SUBTYPE_PASSTHROUGH
+                    ),
+                    None,
+                )
+                if passthrough is None:
+                    continue
+                frm = passthrough.attr(ORIGIN_ATTR_FROM)
+                if not isinstance(frm, str) or frm == "":
+                    continue
+                dot = frm.find(".")
+                if dot < 0:
+                    continue
+                target_entity_name = frm[:dot]
+                target_field_name = frm[dot + 1:]
+                target_entity = object_index.get(target_entity_name)
+                if target_entity is None:
+                    continue  # origin-paths pass surfaces this
+                target_field = next(
+                    (
+                        c
+                        for c in target_entity.own_children()
+                        if c.type == TYPE_FIELD and c.name == target_field_name
+                    ),
+                    None,
+                )
+                if target_field is None:
+                    continue
+                if param_field.sub_type != target_field.sub_type:
+                    errors.append(
+                        MetaError(
+                            f'parameter field "{param_field.name}" '
+                            f"(field.{param_field.sub_type}) on @parameterRef "
+                            f'"{ref}" uses origin.passthrough @from: "{frm}", but '
+                            f"{target_entity.name}.{target_field_name} is "
+                            f"field.{target_field.sub_type}; types must match",
+                            ErrorCode.ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH,
+                            envelope=param_field.source,
+                        )
+                    )

metaobjects/loader/validate_source_physical_names.py

@@ -0,0 +1,140 @@
+"""FR-016 / ADR-0018 — per-kind physical-name aliases on source.rdb.
+
+Each ``source.rdb`` may declare at most one of
+``@table`` / ``@view`` / ``@materializedView`` / ``@proc`` / ``@function``. The
+chosen alias must match the source's ``@kind``, with one pre-1.0 legacy
+exception: ``@table`` is also accepted for non-table kinds (e.g.
+``@kind: "storedProc"`` + ``@table: "fn_x"``), which emits a
+``WARN_LEGACY_PHYSICAL_NAME_ALIAS``.
+
+Codes emitted by this pass:
+    * ``ERR_BAD_ATTR_VALUE``           — any kind-aware alias set to ``""``.
+    * ``ERR_PHYSICAL_NAME_MULTIPLE``   — two or more kind-aware aliases on one source.
+    * ``ERR_PHYSICAL_NAME_KIND_MISMATCH`` — alias other than ``@table`` set with
+      a non-matching ``@kind``.
+    * ``WARN_LEGACY_PHYSICAL_NAME_ALIAS`` — ``@table`` set with a non-table
+      ``@kind`` (legacy spelling). Loader accepts.
+
+Mirrors the TS reference
+``packages/metadata/src/persistence/source/validate-source-physical-names.ts``.
+"""
+from __future__ import annotations
+
+from ..errors import ErrorCode, MetaError
+from ..meta.meta_data import MetaData
+from ..meta.persistence.source.meta_source import MetaSource
+from ..meta.persistence.source.source_constants import (
+    ALL_PHYSICAL_NAME_ALIASES,
+    PHYSICAL_NAME_ATTR_BY_KIND,
+    SOURCE_ATTR_TABLE,
+    SOURCE_SUBTYPE_RDB,
+)
+from ..shared.base_types import TYPE_OBJECT, TYPE_SOURCE
+from ..source.error_source import (
+    LoaderWarning,
+    WARN_LEGACY_PHYSICAL_NAME_ALIAS,
+)
+
+
+def _kind_for_alias(alias: str) -> str:
+    for kind, attr in PHYSICAL_NAME_ATTR_BY_KIND.items():
+        if attr == alias:
+            return kind
+    return "(unknown)"
+
+
+def validate_source_physical_names(
+    root: MetaData,
+    errors: list[MetaError],
+    envelope_warnings: list[LoaderWarning] | None = None,
+    legacy_warnings: list[str] | None = None,
+) -> None:
+    """Run the FR-016 / ADR-0018 per-kind physical-name validation.
+
+    ``envelope_warnings`` collects the FR5c-style envelope warnings (today only
+    ``WARN_LEGACY_PHYSICAL_NAME_ALIAS``). ``legacy_warnings`` mirrors the
+    cross-port string warnings channel — populated with the same code string
+    so the legacy ``warnings: list[str]`` consumers see something too.
+    """
+    for obj in root.own_children():
+        if obj.type != TYPE_OBJECT:
+            continue
+        for source in obj.own_children():
+            if source.type != TYPE_SOURCE:
+                continue
+            if source.sub_type != SOURCE_SUBTYPE_RDB:
+                continue
+            if not isinstance(source, MetaSource):
+                continue
+
+            # Empty-string check first — explicit "" is meaningless and an
+            # authoring error regardless of which alias was used. Run before
+            # the multi/mismatch checks so an empty value can't slip through.
+            for attr in ALL_PHYSICAL_NAME_ALIASES:
+                v = source.attr(attr)
+                if isinstance(v, str) and v == "":
+                    errors.append(
+                        MetaError(
+                            f'source.rdb on object "{obj.name}" sets @{attr} '
+                            "to an empty string; physical name attrs require a "
+                            "non-empty value",
+                            ErrorCode.ERR_BAD_ATTR_VALUE,
+                            envelope=source.source,
+                        )
+                    )
+
+            set_aliases = [
+                a for a in ALL_PHYSICAL_NAME_ALIASES
+                if isinstance(source.attr(a), str) and source.attr(a)
+            ]
+
+            if len(set_aliases) > 1:
+                joined = ", ".join(f"@{a}" for a in set_aliases)
+                errors.append(
+                    MetaError(
+                        f'source.rdb on object "{obj.name}" declares multiple '
+                        f"physical-name aliases ({joined}); set exactly one",
+                        ErrorCode.ERR_PHYSICAL_NAME_MULTIPLE,
+                        envelope=source.source,
+                    )
+                )
+                continue
+
+            if not set_aliases:
+                continue
+
+            chosen = set_aliases[0]
+            expected = PHYSICAL_NAME_ATTR_BY_KIND.get(source.effective_kind())
+
+            if chosen == expected:
+                continue
+
+            # Legacy: @table is permitted for non-table kinds with a warning.
+            if chosen == SOURCE_ATTR_TABLE:
+                msg = (
+                    f'source.rdb on object "{obj.name}" uses @table with '
+                    f'@kind: "{source.effective_kind()}"; prefer the '
+                    f"kind-matching alias @{expected} (ADR-0018)"
+                )
+                if envelope_warnings is not None:
+                    envelope_warnings.append(
+                        LoaderWarning(
+                            code=WARN_LEGACY_PHYSICAL_NAME_ALIAS,
+                            message=msg,
+                            source=source.source,
+                        )
+                    )
+                if legacy_warnings is not None:
+                    legacy_warnings.append(WARN_LEGACY_PHYSICAL_NAME_ALIAS)
+                continue
+
+            # Any other mismatch is a hard error.
+            errors.append(
+                MetaError(
+                    f'source.rdb on object "{obj.name}" uses @{chosen} with '
+                    f'@kind: "{source.effective_kind()}"; @{chosen} is only '
+                    f'valid for @kind: "{_kind_for_alias(chosen)}"',
+                    ErrorCode.ERR_PHYSICAL_NAME_KIND_MISMATCH,
+                    envelope=source.source,
+                )
+            )