pyoq-sql 1.0.2__py3-none-any.whl

pyoq/generation/manifest.py

@@ -0,0 +1,114 @@
+"""Strict deterministic ownership manifest storage."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path, PurePosixPath
+from typing import cast
+
+from pyoq.errors import GenerationManifestError, GenerationValidationError
+from pyoq.generation.contracts import (
+    MANIFEST_FORMAT_VERSION,
+    MANIFEST_NAME,
+    OwnedFile,
+    OwnershipManifest,
+)
+
+
+class JsonManifestStore:
+    def load(self, package_root: Path) -> OwnershipManifest | None:
+        manifest_path = package_root / MANIFEST_NAME
+        if not manifest_path.exists() and not manifest_path.is_symlink():
+            return None
+        if not manifest_path.is_file() or manifest_path.is_symlink():
+            message = "ownership manifest must be a regular file"
+            raise GenerationManifestError(message)
+        try:
+            document = json.loads(manifest_path.read_text(encoding="utf-8"))
+            return _decode_manifest(document)
+        except (OSError, UnicodeError, json.JSONDecodeError) as error:
+            message = f"unable to read ownership manifest: {error}"
+            raise GenerationManifestError(message) from error
+
+    def encode(self, manifest: OwnershipManifest) -> bytes:
+        document = {
+            "files": [
+                {"digest": owned_file.digest, "path": str(owned_file.path)}
+                for owned_file in manifest.files
+            ],
+            "format": manifest.format_version,
+            "package": manifest.package,
+        }
+        content = json.dumps(
+            document,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+        return f"{content}\n".encode()
+
+
+def _decode_manifest(document: object) -> OwnershipManifest:
+    mapping = _require_mapping(document, "manifest")
+    _require_fields(mapping, {"files", "format", "package"}, "manifest")
+    format_version = _require_integer(mapping["format"], "manifest format")
+    if format_version != MANIFEST_FORMAT_VERSION:
+        message = f"unsupported ownership manifest version: {format_version}"
+        raise GenerationManifestError(message)
+    package = _require_string(mapping["package"], "manifest package")
+    file_documents = _require_list(mapping["files"], "manifest files")
+    try:
+        files = tuple(
+            _decode_owned_file(file_document) for file_document in file_documents
+        )
+        return OwnershipManifest(package, files, format_version)
+    except GenerationValidationError as error:
+        message = f"invalid ownership manifest: {error}"
+        raise GenerationManifestError(message) from error
+
+
+def _decode_owned_file(document: object) -> OwnedFile:
+    mapping = _require_mapping(document, "manifest file")
+    _require_fields(mapping, {"digest", "path"}, "manifest file")
+    path = PurePosixPath(_require_string(mapping["path"], "manifest file path"))
+    digest = _require_string(mapping["digest"], "manifest file digest")
+    return OwnedFile(path, digest)
+
+
+def _require_mapping(value: object, label: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        message = f"{label} must be an object"
+        raise GenerationManifestError(message)
+    return cast(dict[str, object], value)
+
+
+def _require_list(value: object, label: str) -> list[object]:
+    if not isinstance(value, list):
+        message = f"{label} must be an array"
+        raise GenerationManifestError(message)
+    return cast(list[object], value)
+
+
+def _require_string(value: object, label: str) -> str:
+    if not isinstance(value, str):
+        message = f"{label} must be a string"
+        raise GenerationManifestError(message)
+    return value
+
+
+def _require_integer(value: object, label: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        message = f"{label} must be an integer"
+        raise GenerationManifestError(message)
+    return value
+
+
+def _require_fields(
+    mapping: dict[str, object],
+    expected: set[str],
+    label: str,
+) -> None:
+    actual = set(mapping)
+    if actual != expected:
+        message = f"{label} fields must be exactly {sorted(expected)!r}"
+        raise GenerationManifestError(message)