pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/dev_manifest.py

@@ -0,0 +1,522 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from types import MappingProxyType
+from typing import Literal, cast
+
+from pz_core.project_sources import resolve_sources_manifest_path
+from pz_core.runtime.errors import PzError
+
+
+MANIFEST_SCHEMA_VERSION = 5
+MANIFEST_ERROR_CODE = "PZ_DEV_MANIFEST_INVALID"
+_OBJECT_KEY = re.compile(r"^[a-z][a-z0-9_]*$")
+_JSON_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_TOP_LEVEL_FIELDS = ("schema_version", "business_app_id", "repos", "bindings")
+_REPO_FIELDS = ("source", "checkout", "base_branch", "branch")
+_BINDING_FIELDS = (
+    "kind",
+    "source_kind",
+    "repo_key",
+    "source",
+    "link",
+    "subpath",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class DevRepo:
+    source: str
+    checkout: PurePosixPath
+    base_branch: Literal["develop", "main"]
+    branch: str
+
+
+@dataclass(frozen=True, slots=True)
+class DevBinding:
+    kind: Literal["directory", "app"]
+    source_kind: Literal["git", "link"]
+    repo_key: str | None
+    source: str
+    link: PurePosixPath
+    subpath: PurePosixPath
+
+
+@dataclass(frozen=True, slots=True)
+class DevManifest:
+    schema_version: Literal[5]
+    business_app_id: str
+    repos: Mapping[str, DevRepo]
+    bindings: Mapping[str, DevBinding]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "repos", MappingProxyType(dict(self.repos)))
+        object.__setattr__(self, "bindings", MappingProxyType(dict(self.bindings)))
+
+
+def _json_child(path: str, key: str) -> str:
+    if _JSON_IDENTIFIER.fullmatch(key):
+        return f"{path}.{key}"
+    return f"{path}[{json.dumps(key, ensure_ascii=True)}]"
+
+
+def _invalid(path: str, reason: str, *, action: str) -> PzError:
+    return PzError(
+        code=MANIFEST_ERROR_CODE,
+        message=f"{path}: {reason}",
+        stage="dev",
+        owner="pz_core.authoring.dev_manifest",
+        action=action,
+    )
+
+
+def _require_object(
+    value: object,
+    path: str,
+    expected_fields: tuple[str, ...],
+    *,
+    action: str,
+) -> dict[str, object]:
+    if not isinstance(value, dict) or not all(isinstance(key, str) for key in value):
+        raise _invalid(path, "expected an object", action=action)
+    expected = set(expected_fields)
+    unknown = sorted(set(value) - expected)
+    if unknown:
+        raise _invalid(_json_child(path, unknown[0]), "unknown field", action=action)
+    for field in expected_fields:
+        if field not in value:
+            raise _invalid(
+                _json_child(path, field), "required field is missing", action=action
+            )
+    return cast(dict[str, object], value)
+
+
+def _require_mapping(value: object, path: str, *, action: str) -> dict[str, object]:
+    if not isinstance(value, dict) or not all(isinstance(key, str) for key in value):
+        raise _invalid(path, "expected an object with string keys", action=action)
+    return cast(dict[str, object], value)
+
+
+def _require_nonempty_string(value: object, path: str, *, action: str) -> str:
+    if not isinstance(value, str) or not value.strip() or value != value.strip():
+        raise _invalid(path, "expected a non-empty normalized string", action=action)
+    if any(ord(character) < 0x20 for character in value):
+        raise _invalid(path, "control characters are not allowed", action=action)
+    return value
+
+
+def _require_object_key(value: str, path: str, *, action: str) -> str:
+    if not _OBJECT_KEY.fullmatch(value):
+        raise _invalid(
+            path,
+            "expected lowercase letters, digits, and underscores starting with a letter",
+            action=action,
+        )
+    return value
+
+
+def _require_posix_path(
+    value: object,
+    path: str,
+    *,
+    allow_dot: bool,
+    action: str,
+) -> PurePosixPath:
+    raw = _require_nonempty_string(value, path, action=action)
+    if "\\" in raw:
+        raise _invalid(path, "expected POSIX separators", action=action)
+    candidate = PurePosixPath(raw)
+    if candidate.is_absolute() or ".." in candidate.parts:
+        raise _invalid(
+            path, "expected a project-relative path without traversal", action=action
+        )
+    if candidate == PurePosixPath("."):
+        if allow_dot and raw == ".":
+            return candidate
+        raise _invalid(path, "path must identify a project child", action=action)
+    if candidate.as_posix() != raw:
+        raise _invalid(path, "path must be normalized POSIX form", action=action)
+    return candidate
+
+
+def _parse_repo(key: str, raw: object, *, action: str) -> DevRepo:
+    path = _json_child("$.repos", key)
+    _require_object_key(key, path, action=action)
+    record = _require_object(raw, path, _REPO_FIELDS, action=action)
+    source = _require_nonempty_string(
+        record["source"], _json_child(path, "source"), action=action
+    )
+    checkout_path = _json_child(path, "checkout")
+    checkout = _require_posix_path(
+        record["checkout"], checkout_path, allow_dot=False, action=action
+    )
+    if checkout.parts[:2] != ("apps", ".sources") or len(checkout.parts) < 3:
+        raise _invalid(
+            checkout_path,
+            "checkout must be below apps/.sources",
+            action=action,
+        )
+    base_branch = record["base_branch"]
+    if base_branch not in {"develop", "main"}:
+        raise _invalid(
+            _json_child(path, "base_branch"),
+            "expected 'develop' or 'main'",
+            action=action,
+        )
+    branch = _require_nonempty_string(
+        record["branch"], _json_child(path, "branch"), action=action
+    )
+    return DevRepo(
+        source=source,
+        checkout=checkout,
+        base_branch=cast(Literal["develop", "main"], base_branch),
+        branch=branch,
+    )
+
+
+def _parse_binding(key: str, raw: object, *, action: str) -> DevBinding:
+    path = _json_child("$.bindings", key)
+    _require_object_key(key, path, action=action)
+    record = _require_object(raw, path, _BINDING_FIELDS, action=action)
+    kind = record["kind"]
+    if kind not in {"directory", "app"}:
+        raise _invalid(
+            _json_child(path, "kind"),
+            "expected 'directory' or 'app'",
+            action=action,
+        )
+    source_kind = record["source_kind"]
+    if source_kind not in {"git", "link"}:
+        raise _invalid(
+            _json_child(path, "source_kind"),
+            "expected 'git' or 'link'",
+            action=action,
+        )
+    repo_key = record["repo_key"]
+    if repo_key is not None and not isinstance(repo_key, str):
+        raise _invalid(
+            _json_child(path, "repo_key"),
+            "expected a repo key or null",
+            action=action,
+        )
+    source = _require_nonempty_string(
+        record["source"], _json_child(path, "source"), action=action
+    )
+    link_path = _json_child(path, "link")
+    link = _require_posix_path(
+        record["link"], link_path, allow_dot=False, action=action
+    )
+    if link.parts[0] != "apps" or len(link.parts) < 2:
+        raise _invalid(link_path, "link must be below apps", action=action)
+    if link.parts[:2] == ("apps", ".sources"):
+        raise _invalid(
+            link_path,
+            "link cannot occupy the physical source checkout tree",
+            action=action,
+        )
+    subpath = _require_posix_path(
+        record["subpath"],
+        _json_child(path, "subpath"),
+        allow_dot=True,
+        action=action,
+    )
+    return DevBinding(
+        kind=cast(Literal["directory", "app"], kind),
+        source_kind=cast(Literal["git", "link"], source_kind),
+        repo_key=repo_key,
+        source=source,
+        link=link,
+        subpath=subpath,
+    )
+
+
+def _paths_overlap(first: PurePosixPath, second: PurePosixPath) -> bool:
+    return first == second or first in second.parents or second in first.parents
+
+
+def _absolute_paths_overlap(first: Path, second: Path) -> bool:
+    return first == second or first in second.parents or second in first.parents
+
+
+def _binding_source_path(
+    project_dir: Path,
+    binding: DevBinding,
+    repos: Mapping[str, DevRepo],
+) -> Path:
+    if binding.source_kind == "git":
+        assert binding.repo_key is not None
+        base = project_dir / Path(*repos[binding.repo_key].checkout.parts)
+    else:
+        base = Path(binding.source)
+    if binding.subpath == PurePosixPath("."):
+        return base.resolve(strict=False)
+    return (base / Path(*binding.subpath.parts)).resolve(strict=False)
+
+
+def _validate_normalized_manifest(
+    project_dir: Path,
+    manifest: DevManifest,
+    *,
+    action: str,
+) -> None:
+    project_root = project_dir.expanduser().resolve(strict=False)
+    repos = manifest.repos
+    bindings = manifest.bindings
+
+    ordered_repos = sorted(repos.items())
+    for index, (repo_key, repo) in enumerate(ordered_repos):
+        repo_path = _json_child("$.repos", repo_key)
+        expected_checkout = PurePosixPath("apps/.sources") / repo_key
+        if repo.checkout != expected_checkout:
+            raise _invalid(
+                _json_child(repo_path, "checkout"),
+                f"checkout must be {expected_checkout.as_posix()!r}",
+                action=action,
+            )
+        if repo.branch != manifest.business_app_id:
+            raise _invalid(
+                _json_child(repo_path, "branch"),
+                "branch must equal the manifest business_app_id",
+                action=action,
+            )
+        for previous_key, previous in ordered_repos[:index]:
+            if _paths_overlap(repo.checkout, previous.checkout):
+                raise _invalid(
+                    _json_child(repo_path, "checkout"),
+                    f"checkout overlaps repo {previous_key!r}",
+                    action=action,
+                )
+            if repo.source == previous.source:
+                raise _invalid(
+                    _json_child(repo_path, "source"),
+                    f"source duplicates repo {previous_key!r}",
+                    action=action,
+                )
+
+    ordered_bindings = sorted(bindings.items())
+    for index, (binding_key, binding) in enumerate(ordered_bindings):
+        binding_path = _json_child("$.bindings", binding_key)
+        if binding.source_kind == "git":
+            if not binding.repo_key:
+                raise _invalid(
+                    _json_child(binding_path, "repo_key"),
+                    "git binding requires a repo key",
+                    action=action,
+                )
+            resolved_repo = repos.get(binding.repo_key)
+            if resolved_repo is None:
+                raise _invalid(
+                    _json_child(binding_path, "repo_key"),
+                    "binding references an unknown repo",
+                    action=action,
+                )
+            if binding.source != resolved_repo.source:
+                raise _invalid(
+                    _json_child(binding_path, "source"),
+                    "git binding source must match its repo source",
+                    action=action,
+                )
+        else:
+            if binding.repo_key is not None:
+                raise _invalid(
+                    _json_child(binding_path, "repo_key"),
+                    "direct-link binding requires a null repo key",
+                    action=action,
+                )
+            source = Path(binding.source).expanduser()
+            if not source.is_absolute() or source.resolve(strict=False) != source:
+                raise _invalid(
+                    _json_child(binding_path, "source"),
+                    "direct-link source must be an absolute canonical path",
+                    action=action,
+                )
+            for repo_key, repo in ordered_repos:
+                checkout = (project_root / Path(*repo.checkout.parts)).resolve(
+                    strict=False
+                )
+                if _absolute_paths_overlap(source, checkout):
+                    raise _invalid(
+                        _json_child(binding_path, "source"),
+                        f"direct-link source overlaps repo {repo_key!r}",
+                        action=action,
+                    )
+
+        source_path = _binding_source_path(project_root, binding, repos)
+        for previous_key, previous_binding in ordered_bindings[:index]:
+            previous_path = _json_child("$.bindings", previous_key)
+            if _paths_overlap(binding.link, previous_binding.link):
+                raise _invalid(
+                    _json_child(binding_path, "link"),
+                    f"link overlaps {previous_path}",
+                    action=action,
+                )
+            previous_source = _binding_source_path(
+                project_root, previous_binding, repos
+            )
+            if _absolute_paths_overlap(source_path, previous_source):
+                raise _invalid(
+                    _json_child(binding_path, "subpath"),
+                    f"source overlaps {previous_path}",
+                    action=action,
+                )
+
+
+def _parse_manifest(
+    project_dir: Path,
+    raw: object,
+    *,
+    action: str,
+) -> DevManifest:
+    payload = _require_object(raw, "$", _TOP_LEVEL_FIELDS, action=action)
+    if type(payload["schema_version"]) is not int or payload["schema_version"] != 5:
+        raise _invalid("$.schema_version", "expected schema version 5", action=action)
+    business_app_id = _require_nonempty_string(
+        payload["business_app_id"], "$.business_app_id", action=action
+    )
+    _require_object_key(business_app_id, "$.business_app_id", action=action)
+    raw_repos = _require_mapping(payload["repos"], "$.repos", action=action)
+    raw_bindings = _require_mapping(payload["bindings"], "$.bindings", action=action)
+    repos = {
+        key: _parse_repo(key, value, action=action) for key, value in raw_repos.items()
+    }
+    bindings = {
+        key: _parse_binding(key, value, action=action)
+        for key, value in raw_bindings.items()
+    }
+    manifest = DevManifest(
+        schema_version=5,
+        business_app_id=business_app_id,
+        repos=repos,
+        bindings=bindings,
+    )
+    _validate_normalized_manifest(project_dir, manifest, action=action)
+    return manifest
+
+
+def _manifest_payload(manifest: DevManifest, *, action: str) -> dict[str, object]:
+    if not isinstance(manifest, DevManifest):
+        raise _invalid("$", "expected a DevManifest", action=action)
+    repos: dict[str, object] = {}
+    for key, repo in manifest.repos.items():
+        path = _json_child("$.repos", str(key))
+        if not isinstance(key, str) or not isinstance(repo, DevRepo):
+            raise _invalid(path, "expected a DevRepo", action=action)
+        if not isinstance(repo.checkout, PurePosixPath):
+            raise _invalid(
+                _json_child(path, "checkout"),
+                "expected a PurePosixPath",
+                action=action,
+            )
+        repos[key] = {
+            "source": repo.source,
+            "checkout": repo.checkout.as_posix(),
+            "base_branch": repo.base_branch,
+            "branch": repo.branch,
+        }
+    bindings: dict[str, object] = {}
+    for key, binding in manifest.bindings.items():
+        path = _json_child("$.bindings", str(key))
+        if not isinstance(key, str) or not isinstance(binding, DevBinding):
+            raise _invalid(path, "expected a DevBinding", action=action)
+        if not isinstance(binding.link, PurePosixPath):
+            raise _invalid(
+                _json_child(path, "link"),
+                "expected a PurePosixPath",
+                action=action,
+            )
+        if not isinstance(binding.subpath, PurePosixPath):
+            raise _invalid(
+                _json_child(path, "subpath"),
+                "expected a PurePosixPath",
+                action=action,
+            )
+        bindings[key] = {
+            "kind": binding.kind,
+            "source_kind": binding.source_kind,
+            "repo_key": binding.repo_key,
+            "source": binding.source,
+            "link": binding.link.as_posix(),
+            "subpath": binding.subpath.as_posix(),
+        }
+    return {
+        "schema_version": manifest.schema_version,
+        "business_app_id": manifest.business_app_id,
+        "repos": repos,
+        "bindings": bindings,
+    }
+
+
+def validate_dev_manifest(project_dir: Path, manifest: DevManifest) -> DevManifest:
+    payload = _manifest_payload(manifest, action="validate_dev_manifest")
+    _parse_manifest(project_dir, payload, action="validate_dev_manifest")
+    return manifest
+
+
+def manifest_bytes(manifest: DevManifest) -> bytes:
+    payload = _manifest_payload(manifest, action="manifest_bytes")
+    return (
+        json.dumps(payload, ensure_ascii=True, indent=2, sort_keys=True) + "\n"
+    ).encode("utf-8")
+
+
+def load_dev_manifest(project_dir: Path) -> DevManifest | None:
+    path = resolve_sources_manifest_path(project_dir)
+    if not path.exists():
+        return None
+    if not path.is_file():
+        raise _invalid("$", "manifest path is not a file", action="load_dev_manifest")
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise _invalid(
+            "$", f"cannot parse manifest JSON: {exc}", action="load_dev_manifest"
+        ) from exc
+    return _parse_manifest(project_dir, raw, action="load_dev_manifest")
+
+
+def save_dev_manifest(project_dir: Path, manifest: DevManifest) -> None:
+    validate_dev_manifest(project_dir, manifest)
+    encoded = manifest_bytes(manifest)
+    path = resolve_sources_manifest_path(project_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(
+        dir=path.parent,
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+    )
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(encoded)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+        directory_descriptor = os.open(
+            path.parent,
+            os.O_RDONLY | getattr(os, "O_DIRECTORY", 0),
+        )
+        try:
+            os.fsync(directory_descriptor)
+        finally:
+            os.close(directory_descriptor)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+__all__ = [
+    "DevBinding",
+    "DevManifest",
+    "DevRepo",
+    "MANIFEST_ERROR_CODE",
+    "MANIFEST_SCHEMA_VERSION",
+    "load_dev_manifest",
+    "manifest_bytes",
+    "save_dev_manifest",
+    "validate_dev_manifest",
+]