modelable 1.0.0__py3-none-any.whl

modelable/parser/wire.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from modelable.parser.ir import Annotation, AnnWire, WireTargetHint
+
+
+def wire_targets_from_annotations(annotations: list[Annotation]) -> dict[str, WireTargetHint]:
+    targets: dict[str, WireTargetHint] = {}
+    for annotation in annotations:
+        if isinstance(annotation, AnnWire):
+            for target, hint in annotation.targets.items():
+                merged = targets.get(target, WireTargetHint())
+                if hint.encoding is not None:
+                    if merged.encoding is not None and merged.encoding != hint.encoding:
+                        raise ValueError(
+                            f"conflicting wire encodings for target '{target}': "
+                            f"{merged.encoding!r} vs {hint.encoding!r}"
+                        )
+                    merged.encoding = hint.encoding
+                if hint.type is not None:
+                    if merged.type is not None and merged.type != hint.type:
+                        raise ValueError(
+                            f"conflicting wire types for target '{target}': {merged.type!r} vs {hint.type!r}"
+                        )
+                    merged.type = hint.type
+                if hint.case is not None:
+                    if merged.case is not None and merged.case != hint.case:
+                        raise ValueError(
+                            f"conflicting wire cases for target '{target}': {merged.case!r} vs {hint.case!r}"
+                        )
+                    merged.case = hint.case
+                if hint.overrides:
+                    overlap = sorted(set(merged.overrides) & set(hint.overrides))
+                    for key in overlap:
+                        if merged.overrides[key] != hint.overrides[key]:
+                            raise ValueError(
+                                f"conflicting wire override for target '{target}' member '{key}': "
+                                f"{merged.overrides[key]!r} vs {hint.overrides[key]!r}"
+                            )
+                    merged.overrides.update(hint.overrides)
+                if hint.field_case is not None:
+                    if merged.field_case is not None and merged.field_case != hint.field_case:
+                        raise ValueError(
+                            f"conflicting wire field cases for target '{target}': "
+                            f"{merged.field_case!r} vs {hint.field_case!r}"
+                        )
+                    merged.field_case = hint.field_case
+                targets[target] = merged
+    return targets
+
+
+def render_wire_annotation(annotation: AnnWire) -> str:
+    parts: list[str] = []
+    for target in sorted(annotation.targets):
+        hint = annotation.targets[target]
+        if hint.encoding is not None:
+            parts.append(f'{target}: "{hint.encoding}"')
+        if hint.type is not None:
+            parts.append(f'{target}.type: "{hint.type}"')
+        if hint.case is not None:
+            parts.append(f'{target}.case: "{hint.case}"')
+        if hint.overrides:
+            overrides = ", ".join(f'{key}: "{value}"' for key, value in sorted(hint.overrides.items()))
+            parts.append(f"{target}.overrides: {{ {overrides} }}")
+        if hint.field_case is not None:
+            parts.append(f'{target}.fieldCase: "{hint.field_case}"')
+    if not parts:
+        raise ValueError("AnnWire must contain at least one wire option")
+    return f"@wire({', '.join(parts)})"

modelable/planner/lineage.py

@@ -0,0 +1,91 @@
+"""Projection-level lineage: maps each output field to its source field(s)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from modelable.expressions.cel import extract_field_refs, parse_cel
+from modelable.parser.ir import ComputedMapping, DirectMapping, MdlFile, ProjectionVersion
+from modelable.registry.resolver import resolved_version_spec
+
+
+@dataclass
+class FieldLineage:
+    field_name: str
+    kind: str  # "direct" or "computed"
+    lineage: list[str] = field(default_factory=list)
+    expression: str | None = None
+
+
+@dataclass
+class ProjectionLineage:
+    domain: str
+    projection: str
+    version: int
+    fields: list[FieldLineage] = field(default_factory=list)
+
+
+def build_projection_lineage(
+    domain_name: str,
+    projection_name: str,
+    pv: ProjectionVersion,
+    mdl: MdlFile,
+) -> ProjectionLineage:
+    """Build field-level lineage for a single projection version."""
+    alias_map = _build_alias_map(pv, mdl)
+    fields: list[FieldLineage] = []
+
+    for proj_field in pv.fields:
+        mapping = proj_field.mapping
+
+        if isinstance(mapping, DirectMapping):
+            ref = alias_map.get(mapping.source_alias, mapping.source_alias)
+            lineage_refs = [f"{ref}.{mapping.source_field}"]
+            fields.append(
+                FieldLineage(
+                    field_name=proj_field.name,
+                    kind="direct",
+                    lineage=lineage_refs,
+                )
+            )
+
+        elif isinstance(mapping, ComputedMapping):
+            expr_ast, _ = parse_cel(mapping.expression)
+            cel_refs = extract_field_refs(expr_ast) if expr_ast is not None else []
+            lineage_refs = []
+            for alias, field_name in cel_refs:
+                model_ref = alias_map.get(alias, alias)
+                lineage_refs.append(f"{model_ref}.{field_name}")
+            fields.append(
+                FieldLineage(
+                    field_name=proj_field.name,
+                    kind="computed",
+                    lineage=lineage_refs,
+                    expression=mapping.expression,
+                )
+            )
+
+    return ProjectionLineage(
+        domain=domain_name,
+        projection=projection_name,
+        version=pv.version,
+        fields=fields,
+    )
+
+
+def _build_alias_map(pv: ProjectionVersion, mdl: MdlFile) -> dict[str, str]:
+    """Return alias -> 'domain.Model@resolved_version' mapping."""
+    alias_map: dict[str, str] = {}
+
+    all_sources = [(pv.source.model, pv.source.version, pv.source.alias)]
+    for join in pv.joins:
+        all_sources.append((join.model, join.version, join.alias))
+
+    for model_ref, version_spec, alias in all_sources:
+        try:
+            resolved = resolved_version_spec(mdl, model_ref, version_spec)
+            alias_map[alias] = f"{model_ref}@{resolved.version}"
+        except LookupError:
+            pass
+
+    return alias_map

modelable/planner/planner.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from modelable.parser.ir import (
+    AnnClassification,
+    Annotation,
+    AnnPii,
+    AnnServer,
+    AutoProjectionTarget,
+    DirectMapping,
+    DomainDef,
+    FieldDef,
+    MdlFile,
+    ModelVersion,
+    ProjectionField,
+    ProjectionVersion,
+    SourceRef,
+    VersionExact,
+)
+
+
+def expand_auto_projections(mdl: MdlFile) -> list[str]:
+    """Expand auto projection declarations into explicit projection versions.
+
+    Mutates ``mdl.domains`` in place, adding generated projections to each
+    domain's ``projections`` dict. Returns a list of error strings.
+    """
+    errors: list[str] = []
+    for domain in mdl.domains:
+        errors.extend(_expand_domain_auto_projections(domain))
+    return errors
+
+
+def _expand_domain_auto_projections(domain: DomainDef) -> list[str]:
+    errors: list[str] = []
+    for decl in domain.auto_projections:
+        model_versions = domain.models.get(decl.model)
+        if model_versions is None:
+            errors.append(f"{domain.name}: auto projections references unknown model '{decl.model}'")
+            continue
+
+        model_version = next((mv for mv in model_versions if mv.version == decl.version), None)
+        if model_version is None:
+            errors.append(
+                f"{domain.name}: auto projections references {decl.model}@{decl.version} which does not exist"
+            )
+            continue
+
+        for target in decl.targets:
+            projection_name = _generated_projection_name(decl.model, target.kind)
+            existing = domain.projections.get(projection_name)
+            if existing is not None:
+                # Skip if an explicit projection with the same name already exists.
+                # The workspace validator already checks for conflicts; this is
+                # just a safety guard.
+                continue
+
+            fields = _build_projection_fields(target, model_version, decl.model)
+            projection = ProjectionVersion(
+                version=decl.version,
+                source=SourceRef(
+                    model=f"{domain.name}.{decl.model}",
+                    version=VersionExact(version=decl.version),
+                    alias=_default_alias(decl.model),
+                ),
+                fields=fields,
+                auto_generated=True,
+            )
+            domain.projections.setdefault(projection_name, []).append(projection)
+
+    return errors
+
+
+def _generated_projection_name(model_name: str, kind: str) -> str:
+    suffixes = {
+        "db": "Db",
+        "request": "Request",
+        "reply": "Reply",
+        "event": "Event",
+    }
+    return f"{model_name}{suffixes[kind]}"
+
+
+def _default_alias(model_name: str) -> str:
+    return model_name[0].lower() + model_name[1:]
+
+
+def _build_projection_fields(
+    target: AutoProjectionTarget,
+    model_version: ModelVersion,
+    model_name: str,
+) -> list[ProjectionField]:
+    alias = _default_alias(model_name)
+    included = []
+    for field in model_version.fields:
+        if _is_excluded(field, target):
+            continue
+        included.append(
+            ProjectionField(
+                name=field.name,
+                mapping=DirectMapping(source_alias=alias, source_field=field.name),
+                annotations=list(field.annotations),
+            )
+        )
+    return included
+
+
+def _is_excluded(field: FieldDef, target: AutoProjectionTarget) -> bool:
+    # Explicit field name exclusions
+    if field.name in target.excluded_fields:
+        return True
+
+    # Implicit request exclusion: @server fields are excluded from request models
+    if target.kind == "request" and _has_annotation(field, AnnServer):
+        return True
+
+    # Check excluded annotations
+    return any(_annotation_matches(field, ann) for ann in target.excluded_annotations)
+
+
+def _has_annotation(field: FieldDef, annotation_type: type) -> bool:
+    return any(isinstance(a, annotation_type) for a in field.annotations)
+
+
+def _annotation_matches(field: FieldDef, excluded: Annotation) -> bool:
+    for ann in field.annotations:
+        if type(ann) is not type(excluded):
+            continue
+        if isinstance(ann, AnnPii) and isinstance(excluded, AnnPii):
+            return True
+        if isinstance(ann, AnnServer) and isinstance(excluded, AnnServer):
+            return True
+        if isinstance(ann, AnnClassification) and isinstance(excluded, AnnClassification):
+            return True
+    return False

modelable/planner/plans.py

@@ -0,0 +1,122 @@
+"""Build and write projection plan documents to .modelable/plans/."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from modelable.compiler.workspace import Workspace
+from modelable.governance.checker import build_projection_governance_findings
+from modelable.parser.ir import ComputedMapping, DirectMapping, MdlFile, ProjectionVersion
+from modelable.planner.lineage import ProjectionLineage, build_projection_lineage
+from modelable.registry.resolver import resolve_model_ref
+
+
+def build_plan(
+    domain_name: str,
+    projection_name: str,
+    pv: ProjectionVersion,
+    lineage: ProjectionLineage,
+    mdl: MdlFile,
+) -> dict:
+    """Return the plan document dict for a single projection version."""
+    source_block = _resolve_source_block(pv.source.model, pv.source.version, pv.source.alias, mdl)
+
+    joins_block = [_resolve_source_block(join.model, join.version, join.alias, mdl, on=join.on) for join in pv.joins]
+    revalidation_reasons = _collect_revalidation_reasons(source_block, joins_block)
+    governance_findings = [
+        finding.as_dict() for finding in build_projection_governance_findings(domain_name, projection_name, pv, mdl)
+    ]
+
+    lineage_by_field = {fl.field_name: fl for fl in lineage.fields}
+
+    fields_block = []
+    for proj_field in pv.fields:
+        mapping = proj_field.mapping
+        entry: dict = {"name": proj_field.name}
+        if isinstance(mapping, DirectMapping):
+            entry["kind"] = "direct"
+            entry["source_alias"] = mapping.source_alias
+            entry["source_field"] = mapping.source_field
+        elif isinstance(mapping, ComputedMapping):
+            entry["kind"] = "computed"
+            entry["expression"] = mapping.expression
+        fl = lineage_by_field.get(proj_field.name)
+        entry["lineage"] = fl.lineage if fl else []
+        fields_block.append(entry)
+
+    return {
+        "$schema": "modelable-plan/1.0",
+        "domain": domain_name,
+        "projection": projection_name,
+        "version": pv.version,
+        "auto_generated": pv.auto_generated,
+        "requires_revalidation": bool(revalidation_reasons),
+        "revalidation_reasons": revalidation_reasons,
+        "governance_findings": governance_findings,
+        "source": source_block,
+        "joins": joins_block,
+        "group_by": pv.group_by,
+        "fields": fields_block,
+        "planner_metadata": {
+            "modelable_schema": "1.0",
+        },
+    }
+
+
+def write_plans(workspace: Workspace, plans_dir: Path) -> list[Path]:
+    """Write a plan JSON file for every projection version in the workspace."""
+    plans_dir.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+
+    for domain in workspace.mdl.domains:
+        for projection_name, versions in domain.projections.items():
+            for pv in versions:
+                lineage = build_projection_lineage(domain.name, projection_name, pv, workspace.mdl)
+                plan = build_plan(domain.name, projection_name, pv, lineage, workspace.mdl)
+                filename = f"{domain.name}.{projection_name}.v{pv.version}.plan.json"
+                out_path = plans_dir / filename
+                out_path.write_text(
+                    json.dumps(plan, indent=2, ensure_ascii=False) + "\n",
+                    encoding="utf-8",
+                )
+                written.append(out_path)
+
+    return written
+
+
+def _resolve_source_block(
+    model_ref: str,
+    version_spec,
+    alias: str,
+    mdl: MdlFile,
+    on: str | None = None,
+) -> dict:
+    try:
+        resolved = resolve_model_ref(mdl, model_ref, version_spec)
+        resolved_version = resolved.version.version
+        change_kind = resolved.version.change_kind.value
+    except LookupError:
+        resolved_version = None
+        change_kind = None
+
+    block: dict = {
+        "model": model_ref,
+        "resolved_version": resolved_version,
+        "alias": alias,
+        "change_kind": change_kind,
+    }
+    if on is not None:
+        block["on"] = on
+    return block
+
+
+def _collect_revalidation_reasons(source_block: dict, joins_block: list[dict]) -> list[str]:
+    reasons: list[str] = []
+
+    for block in [source_block, *joins_block]:
+        if block.get("change_kind") == "breaking" and block.get("resolved_version") is not None:
+            relation = "source" if "on" not in block else f"join {block.get('alias')}"
+            reasons.append(f"{relation} {block['model']}@{block['resolved_version']} is marked breaking")
+
+    return reasons

modelable/registry/__init__.py

@@ -0,0 +1,9 @@
+__all__ = ["build_registry"]
+
+
+def __getattr__(name: str):
+    if name == "build_registry":
+        from modelable.registry.index import build_registry
+
+        return build_registry
+    raise AttributeError(name)

modelable/registry/apicurio.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+Transport = Callable[[str, str, dict[str, str], bytes | None, float], tuple[int, str]]
+
+
+class ApicurioRegistryError(RuntimeError):
+    """Raised when Apicurio Registry rejects or cannot complete a request."""
+
+
+@dataclass(frozen=True)
+class ApicurioArtifact:
+    artifact_id: str
+    version: str
+    content: dict[str, object]
+
+
+class ApicurioRegistryClient:
+    def __init__(
+        self,
+        url: str,
+        token: str | None = None,
+        transport: Transport | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = _registry_api_url(url)
+        self.token = token
+        self.transport = transport or _urllib_transport
+        self.timeout = timeout
+
+    def publish_json_schema(self, artifact: ApicurioArtifact, group: str = "default") -> None:
+        artifact_content = json.dumps(artifact.content, indent=2, ensure_ascii=False)
+        body = json.dumps(
+            {
+                "artifactId": artifact.artifact_id,
+                "artifactType": "JSON",
+                "firstVersion": {
+                    "version": artifact.version,
+                    "content": {
+                        "content": artifact_content,
+                        "contentType": "application/json",
+                    },
+                },
+            },
+            indent=2,
+            ensure_ascii=False,
+        ).encode("utf-8")
+        headers = self._headers(
+            {
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            }
+        )
+        status, response_text = self.transport(
+            "POST",
+            f"{self.base_url}/groups/{_url_part(group)}/artifacts",
+            headers,
+            body,
+            self.timeout,
+        )
+        _raise_for_status(status, response_text, f"publish {artifact.artifact_id}")
+
+    def pull_json_schema(self, ref: str, group: str = "default", out_dir: Path = Path(".")) -> Path:
+        artifact_id, version = artifact_id_from_ref(ref)
+        headers = self._headers({"Accept": "application/json"})
+        status, response_text = self.transport(
+            "GET",
+            (
+                f"{self.base_url}/groups/{_url_part(group)}/artifacts/"
+                f"{_url_part(artifact_id)}/versions/{_url_part(version)}/content"
+            ),
+            headers,
+            None,
+            self.timeout,
+        )
+        _raise_for_status(status, response_text, f"pull {artifact_id}")
+
+        try:
+            content = json.loads(response_text)
+        except json.JSONDecodeError as exc:
+            raise ApicurioRegistryError(f"Apicurio returned invalid JSON for {artifact_id}: {exc}") from exc
+
+        if not isinstance(content, dict):
+            raise ApicurioRegistryError(f"Apicurio returned non-object JSON for {artifact_id}")
+
+        domain, name = _split_domain_name(artifact_id)
+        path = out_dir / domain / f"{name}.v{version}.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(content, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        return path
+
+    def _headers(self, headers: dict[str, str]) -> dict[str, str]:
+        if self.token:
+            return {**headers, "Authorization": f"Bearer {self.token}"}
+        return headers
+
+
+def artifact_id_from_ref(ref: str) -> tuple[str, str]:
+    if "@" not in ref:
+        raise ApicurioRegistryError(f"expected ref in form domain.Name@version, got {ref!r}")
+    model_ref, version = ref.rsplit("@", 1)
+    if not model_ref or not version.isdigit():
+        raise ApicurioRegistryError(f"expected ref in form domain.Name@version, got {ref!r}")
+    domain, name = _split_model_ref(model_ref)
+    return f"{domain}.{name}.v{version}", version
+
+
+def _registry_api_url(url: str) -> str:
+    normalized = url.rstrip("/")
+    suffix = "/apis/registry/v3"
+    if normalized.endswith(suffix):
+        return normalized
+    return f"{normalized}{suffix}"
+
+
+def _split_model_ref(ref: str) -> tuple[str, str]:
+    try:
+        domain, name = ref.rsplit(".", 1)
+    except ValueError as exc:
+        raise ApicurioRegistryError(f"expected ref in form domain.Name@version, got {ref!r}") from exc
+    if not domain or not name:
+        raise ApicurioRegistryError(f"expected ref in form domain.Name@version, got {ref!r}")
+    return domain, name
+
+
+def _split_domain_name(artifact_id: str) -> tuple[str, str]:
+    stem = artifact_id.rsplit(".v", 1)[0]
+    return _split_model_ref(stem)
+
+
+def _url_part(value: str) -> str:
+    return quote(value, safe="")
+
+
+def _raise_for_status(status: int, response_text: str, action: str) -> None:
+    if 200 <= status < 300:
+        return
+    detail = response_text.strip()
+    suffix = f": {detail}" if detail else ""
+    raise ApicurioRegistryError(f"Apicurio {action} failed with HTTP {status}{suffix}")
+
+
+def _urllib_transport(
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    body: bytes | None = None,
+    timeout: float = 30.0,
+) -> tuple[int, str]:
+    request = Request(url, data=body, headers=headers, method=method)
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            payload = response.read().decode("utf-8")
+            return response.status, payload
+    except HTTPError as exc:
+        payload = exc.read().decode("utf-8", errors="replace")
+        return exc.code, payload
+    except URLError as exc:
+        raise ApicurioRegistryError(f"Apicurio request failed: {exc.reason}") from exc

modelable/registry/base.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class Registry(ABC):
+    """Abstract base class for a Modelable registry."""
+
+    @abstractmethod
+    def push(self, registry_path: Path) -> None:
+        """Push a registry index to the registry."""
+        ...
+
+    @abstractmethod
+    def pull(self, dest_path: Path) -> None:
+        """Pull a registry index from the registry."""
+        ...

modelable/registry/factory.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from modelable.registry.base import Registry
+from modelable.registry.local import LocalRegistry
+
+
+def get_registry(registry_path: Path) -> Registry:
+    """Return a Registry instance based on the registry path."""
+    # If path is a file, return LocalRegistry
+    # If path looks like an OCI URL (e.g., oci://), return OCIRegistry
+    if registry_path.as_posix().startswith("oci://"):
+        from modelable.registry.oci import OCIRegistry
+
+        return OCIRegistry(registry_path.as_posix())
+
+    return LocalRegistry(registry_path)