pz-cli 5.0.0__py3-none-any.whl

pz_core/assembly/diagnostics/dev_sources.py

@@ -0,0 +1,569 @@
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING
+
+from pz_core.core.errors import PzError
+
+from .checks import CheckItem
+
+if TYPE_CHECKING:
+    from pz_core.assembly.app_discovery import VisibleAppProjection
+    from pz_core.authoring.dev_git import DevGitService
+    from pz_core.authoring.dev_manifest import DevBinding, DevManifest
+
+
+BLOCKING_DEV_SOURCE_CODES = frozenset(
+    {
+        "PZ_CHECK_DEV_MANIFEST_INVALID",
+        "PZ_CHECK_DEV_CHECKOUT_MISSING",
+        "PZ_CHECK_DEV_BINDING_LINK_INVALID",
+        "PZ_CHECK_DEV_BINDING_OVERLAP",
+        "PZ_CHECK_DEV_APP_DUPLICATE",
+    }
+)
+
+_BINDING_OWNER = re.compile(r"\$\.bindings\.([a-z][a-z0-9_]*)")
+_RESOLUTION_ERRORS = (OSError, RuntimeError)
+
+
+@dataclass(frozen=True, slots=True)
+class _UvExpectation:
+    distribution: str
+    owner: str
+
+
+def _item(
+    *,
+    code: str,
+    severity: str,
+    owner: str,
+    scope: str,
+    message: str,
+    expected: str | None,
+    actual: str | None,
+    repair_command: str | None,
+    ok: bool = False,
+) -> CheckItem:
+    return CheckItem(
+        severity=severity,
+        code=code,
+        owner=owner,
+        scope=scope,
+        message=message,
+        ok=ok,
+        expected=expected,
+        actual=actual,
+        repair_command=repair_command,
+    )
+
+
+def _binding_key_from_manifest_error(message: str) -> str | None:
+    match = _BINDING_OWNER.search(message)
+    return None if match is None else match.group(1)
+
+
+def _manifest_error_item(exc: PzError) -> CheckItem:
+    if "overlaps" in exc.message:
+        binding_key = _binding_key_from_manifest_error(exc.message) or "unknown"
+        return _item(
+            code="PZ_CHECK_DEV_BINDING_OVERLAP",
+            severity="error",
+            owner=f"dev.binding.{binding_key}",
+            scope="dev.bindings",
+            message="Development bindings overlap in the typed v5 manifest.",
+            expected="non-overlapping binding links and sources",
+            actual=exc.message,
+            repair_command=f"pz dev unlink {binding_key} --project-dir .",
+        )
+    return _item(
+        code="PZ_CHECK_DEV_MANIFEST_INVALID",
+        severity="error",
+        owner="dev.manifest",
+        scope="dev.manifest",
+        message="Development source manifest is not a valid typed v5 manifest.",
+        expected="typed schema_version=5 manifest",
+        actual=exc.message,
+        repair_command="pz dev init --project-dir .",
+    )
+
+
+def _checkout_state_name(path: Path) -> str:
+    if path.is_symlink():
+        return "shared-symlink" if path.is_dir() else "broken-symlink"
+    if not path.exists():
+        return "missing"
+    if not path.is_dir():
+        return "not-directory"
+    return "unreadable"
+
+
+def _repo_items(
+    project_dir: Path,
+    manifest: DevManifest,
+    git_service: DevGitService,
+) -> tuple[list[CheckItem], frozenset[str]]:
+    items: list[CheckItem] = []
+    unavailable: set[str] = set()
+    for repo_key, repo in sorted(manifest.repos.items()):
+        checkout = project_dir / Path(*repo.checkout.parts)
+        owner = f"dev.repo.{repo_key}"
+        shared_checkout = checkout.is_symlink()
+        if not checkout.is_dir():
+            unavailable.add(repo_key)
+            items.append(
+                _item(
+                    code="PZ_CHECK_DEV_CHECKOUT_MISSING",
+                    severity="error",
+                    owner=owner,
+                    scope="dev.repo",
+                    message=f"Managed checkout {repo_key!r} is unavailable.",
+                    expected=repo.checkout.as_posix(),
+                    actual=_checkout_state_name(checkout),
+                    repair_command=f"pz dev add {repo_key} --project-dir .",
+                )
+            )
+            continue
+        try:
+            state = (
+                git_service.inspect_shared(
+                    checkout,
+                    expected_source=repo.source,
+                )
+                if shared_checkout
+                else git_service.inspect(checkout)
+            )
+        except PzError:
+            unavailable.add(repo_key)
+            items.append(
+                _item(
+                    code="PZ_CHECK_DEV_CHECKOUT_MISSING",
+                    severity="error",
+                    owner=owner,
+                    scope="dev.repo",
+                    message=f"Managed checkout {repo_key!r} is not a readable Git checkout.",
+                    expected=repo.checkout.as_posix(),
+                    actual="not-git",
+                    repair_command=f"pz dev add {repo_key} --project-dir .",
+                )
+            )
+            continue
+        if shared_checkout:
+            continue
+        if state.branch != repo.branch:
+            items.append(
+                _item(
+                    code="PZ_CHECK_DEV_BRANCH_DRIFT",
+                    severity="error",
+                    owner=owner,
+                    scope="dev.repo",
+                    message=f"Managed checkout {repo_key!r} is on the wrong branch.",
+                    expected=repo.branch,
+                    actual=state.branch or "detached HEAD",
+                    repair_command=f"pz dev branch {repo_key} --project-dir .",
+                )
+            )
+        if state.dirty:
+            items.append(
+                _item(
+                    code="PZ_CHECK_DEV_WORKTREE_DIRTY",
+                    severity="warning",
+                    owner=owner,
+                    scope="dev.repo",
+                    message=f"Managed checkout {repo_key!r} has local changes.",
+                    expected="clean",
+                    actual="dirty",
+                    repair_command=(
+                        f"git -C {repo.checkout.as_posix()} status --short"
+                    ),
+                )
+            )
+    return items, frozenset(unavailable)
+
+
+def _join_binding_source(
+    project_dir: Path,
+    manifest: DevManifest,
+    binding: DevBinding,
+) -> Path:
+    if binding.source_kind == "link":
+        source = Path(binding.source)
+    else:
+        assert binding.repo_key is not None
+        source = project_dir / Path(*manifest.repos[binding.repo_key].checkout.parts)
+    if binding.subpath == PurePosixPath("."):
+        return source
+    return source / Path(*binding.subpath.parts)
+
+
+def _relative_link_target(link: Path, target: Path) -> str:
+    return Path(os.path.relpath(target, start=link.parent)).as_posix()
+
+
+def _link_actual_state(link: Path, expected: Path, expected_target: str) -> str | None:
+    if not os.path.lexists(link):
+        return "missing"
+    if not link.is_symlink():
+        return "not-symlink"
+    try:
+        stored_target = os.readlink(link)
+        actual = link.resolve(strict=True)
+        expected_realpath = expected.resolve(strict=True)
+    except _RESOLUTION_ERRORS:
+        return "broken"
+    if (
+        Path(stored_target).is_absolute()
+        or "\\" in stored_target
+        or stored_target != expected_target
+        or actual != expected_realpath
+    ):
+        return "misdirected"
+    return None
+
+
+def _binding_link_items(
+    project_dir: Path,
+    manifest: DevManifest,
+    unavailable_repos: frozenset[str],
+) -> list[CheckItem]:
+    items: list[CheckItem] = []
+    for binding_key, binding in sorted(manifest.bindings.items()):
+        if binding.repo_key in unavailable_repos:
+            continue
+        link = project_dir / Path(*binding.link.parts)
+        expected = _join_binding_source(project_dir, manifest, binding)
+        expected_target = _relative_link_target(link, expected)
+        actual = _link_actual_state(link, expected, expected_target)
+        if actual is None:
+            continue
+        items.append(
+            _item(
+                code="PZ_CHECK_DEV_BINDING_LINK_INVALID",
+                severity="error",
+                owner=f"dev.binding.{binding_key}",
+                scope="dev.binding",
+                message=f"Managed binding {binding_key!r} does not match its v5 declaration.",
+                expected=expected_target,
+                actual=actual,
+                repair_command=f"pz dev add {binding_key} --project-dir .",
+            )
+        )
+    return items
+
+
+def _duplicate_binding_key(
+    project_dir: Path,
+    manifest: DevManifest,
+    message: str,
+) -> str | None:
+    for binding_key, binding in sorted(manifest.bindings.items()):
+        link = project_dir / Path(*binding.link.parts)
+        if str(link) in message:
+            return binding_key
+    return None
+
+
+def _projection_error_item(
+    project_dir: Path,
+    manifest: DevManifest | None,
+    exc: PzError,
+) -> CheckItem:
+    if exc.code == "PZ_VISIBLE_APP_DUPLICATE":
+        app_id = exc.owner
+        binding_key = (
+            None
+            if manifest is None
+            else _duplicate_binding_key(project_dir, manifest, exc.message)
+        )
+        repair = (
+            f"pz dev unlink {binding_key} --project-dir ."
+            if binding_key is not None
+            else f"find apps -path '*/{app_id}/apps.py' -print"
+        )
+        return _item(
+            code="PZ_CHECK_DEV_APP_DUPLICATE",
+            severity="error",
+            owner=f"dev.app.{app_id}",
+            scope="dev.apps",
+            message=f"Visible app {app_id!r} is exposed more than once.",
+            expected="one visible projection per app_id",
+            actual=f"duplicate app_id={app_id}",
+            repair_command=repair,
+        )
+    binding_key = exc.owner
+    return _item(
+        code="PZ_CHECK_DEV_BINDING_LINK_INVALID",
+        severity="error",
+        owner=f"dev.binding.{binding_key}",
+        scope="dev.binding",
+        message=f"Managed binding {binding_key!r} does not expose a formal visible app.",
+        expected="formal visible projection matching the v5 binding",
+        actual="invalid-projection",
+        repair_command=f"pz dev add {binding_key} --project-dir .",
+    )
+
+
+def _read_distribution_name(path: Path) -> str | None:
+    try:
+        payload = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError):
+        return None
+    project = payload.get("project")
+    if not isinstance(project, dict):
+        return None
+    name = project.get("name")
+    if not isinstance(name, str) or not name.strip():
+        return None
+    return name.strip()
+
+
+def _bootstrap_expectations(
+    manifest: DevManifest,
+) -> list[_UvExpectation]:
+    from pz_core.project_sources import load_official_source_catalog
+
+    expectations: list[_UvExpectation] = []
+    catalog = load_official_source_catalog()
+    for repo_key, repo in sorted(manifest.repos.items()):
+        root = catalog.get(repo_key)
+        if root is None or not root.bootstrap:
+            continue
+        for distribution, child in sorted(root.children.items()):
+            if child.kind != "project":
+                continue
+            expectations.append(
+                _UvExpectation(
+                    distribution=distribution,
+                    owner=f"dev.repo.{repo_key}",
+                )
+            )
+    return expectations
+
+
+def _binding_expectations(
+    project_dir: Path,
+    projections: tuple[VisibleAppProjection, ...],
+) -> list[_UvExpectation]:
+    expectations: list[_UvExpectation] = []
+    for projection in projections:
+        if projection.binding_key is None:
+            continue
+        distribution = _read_distribution_name(
+            projection.source_root / "pyproject.toml"
+        )
+        if distribution is None:
+            continue
+        expectations.append(
+            _UvExpectation(
+                distribution=distribution,
+                owner=f"dev.binding.{projection.binding_key}",
+            )
+        )
+    return expectations
+
+
+def _read_uv_sources(project_dir: Path) -> dict[str, object]:
+    path = project_dir / "pyproject.toml"
+    try:
+        payload = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError):
+        return {}
+    tool = payload.get("tool")
+    if not isinstance(tool, dict):
+        return {}
+    uv = tool.get("uv")
+    if not isinstance(uv, dict):
+        return {}
+    sources = uv.get("sources")
+    if not isinstance(sources, dict):
+        return {}
+    return {str(key): value for key, value in sources.items()}
+
+
+def _uv_source_state(value: object) -> tuple[str | None, bool | None]:
+    if not isinstance(value, dict):
+        return None, None
+    path = value.get("path")
+    editable = value.get("editable")
+    return (
+        path.strip() if isinstance(path, str) and path.strip() else None,
+        editable if type(editable) is bool else None,
+    )
+
+
+def _format_uv_state(path: str | None, editable: bool | None) -> str:
+    if path is None:
+        return "missing"
+    editable_value = (
+        "true" if editable is True else "false" if editable is False else "missing"
+    )
+    return f"path={path}; editable={editable_value}"
+
+
+def _display_uv_path(project_dir: Path, raw_path: str | None) -> str | None:
+    if raw_path is None:
+        return None
+    candidate = Path(raw_path).expanduser()
+    if not candidate.is_absolute():
+        return raw_path
+    try:
+        return candidate.relative_to(project_dir).as_posix()
+    except ValueError:
+        return "<absolute-path>"
+
+
+def _uv_items(
+    project_dir: Path,
+    manifest: DevManifest,
+    projections: tuple[VisibleAppProjection, ...],
+) -> list[CheckItem]:
+    from pz_core.authoring.app_init_service import build_app_init_source_plan
+
+    owners = {
+        item.distribution: item
+        for item in (
+            *_bootstrap_expectations(manifest),
+            *_binding_expectations(project_dir, projections),
+        )
+    }
+    actual = _read_uv_sources(project_dir)
+    try:
+        plan = build_app_init_source_plan(
+            project_dir,
+            current_sources=actual,
+            action="check_dev_sources",
+        )
+    except PzError as exc:
+        return [
+            _item(
+                code="PZ_CHECK_DEV_UV_SOURCE_DRIFT",
+                severity="error",
+                owner="dev.uv.plan",
+                scope="dev.uv_sources",
+                message="uv sources cannot be compiled from the v5 source bindings.",
+                expected="valid app-init source plan",
+                actual=f"{exc.code}: {exc.message}",
+                repair_command="pz app init --project-dir .",
+            )
+        ]
+    items: list[CheckItem] = []
+    for distribution, binding in sorted(plan.desired_sources.items()):
+        actual_path, editable = _uv_source_state(actual.get(distribution))
+        expected_path = binding.path
+        if actual_path == expected_path and editable is True:
+            continue
+        expectation = owners.get(distribution)
+        items.append(
+            _item(
+                code="PZ_CHECK_DEV_UV_SOURCE_DRIFT",
+                severity="error",
+                owner=(
+                    expectation.owner
+                    if expectation is not None
+                    else f"dev.uv.{distribution}"
+                ),
+                scope="dev.uv_sources",
+                message=f"uv source {distribution!r} does not match its v5 source binding.",
+                expected=_format_uv_state(expected_path, True),
+                actual=_format_uv_state(
+                    _display_uv_path(project_dir, actual_path),
+                    editable,
+                ),
+                repair_command="pz app init --project-dir .",
+            )
+        )
+    for distribution in plan.stale_source_keys:
+        value = actual.get(distribution)
+        actual_path, editable = _uv_source_state(value)
+        items.append(
+            _item(
+                code="PZ_CHECK_DEV_UV_SOURCE_DRIFT",
+                severity="error",
+                owner=f"dev.uv.{distribution}",
+                scope="dev.uv_sources",
+                message=f"uv source {distribution!r} has no v5 source owner.",
+                expected="absent",
+                actual=_format_uv_state(
+                    _display_uv_path(project_dir, actual_path),
+                    editable,
+                ),
+                repair_command="pz app init --project-dir .",
+            )
+        )
+    return items
+
+
+def build_dev_source_check_items(
+    project_dir: str | Path,
+    *,
+    git_service: DevGitService | None = None,
+) -> tuple[CheckItem, ...]:
+    from pz_core.assembly.app_discovery import iter_visible_app_projections
+    from pz_core.authoring.dev_git import DevGitService
+    from pz_core.authoring.dev_manifest import load_dev_manifest
+
+    project_root = Path(project_dir).expanduser().resolve(strict=False)
+    try:
+        manifest = load_dev_manifest(project_root)
+    except PzError as exc:
+        return (_manifest_error_item(exc),)
+
+    items: list[CheckItem] = []
+    service = git_service or DevGitService()
+    if manifest is not None:
+        repo_items, unavailable_repos = _repo_items(
+            project_root,
+            manifest,
+            service,
+        )
+        items.extend(repo_items)
+        link_items = _binding_link_items(
+            project_root,
+            manifest,
+            unavailable_repos,
+        )
+        items.extend(link_items)
+        if link_items or unavailable_repos:
+            return tuple(items)
+
+    try:
+        projections = iter_visible_app_projections(project_root)
+    except PzError as exc:
+        items.append(_projection_error_item(project_root, manifest, exc))
+        return tuple(items)
+
+    if manifest is None:
+        return tuple(items)
+    items.extend(_uv_items(project_root, manifest, projections))
+    if items:
+        return tuple(items)
+    return (
+        _item(
+            code="PZ_CHECK_DEV_SOURCES_VALID",
+            severity="info",
+            owner="dev.sources",
+            scope="dev.sources",
+            message="Development source manifest, checkouts, links, apps, and uv sources are aligned.",
+            expected="all v5 development sources aligned",
+            actual="valid",
+            repair_command=None,
+            ok=True,
+        ),
+    )
+
+
+def has_blocking_dev_source_failures(checks: tuple[CheckItem, ...]) -> bool:
+    return any(
+        not item.ok and item.code in BLOCKING_DEV_SOURCE_CODES for item in checks
+    )
+
+
+__all__ = [
+    "BLOCKING_DEV_SOURCE_CODES",
+    "build_dev_source_check_items",
+    "has_blocking_dev_source_failures",
+]

pz_core/assembly/events/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .compiler import EventDeclarationSource, collect_event_declarations, compile_event_registry
+
+__all__ = ["EventDeclarationSource", "collect_event_declarations", "compile_event_registry"]