velophex 0.2.0__py3-none-any.whl

velophex/contracts/package.py

@@ -0,0 +1,391 @@
+"""``velophex/package-manifest.json`` (manifest v2) and the package layout (ADR-P003).
+
+Mirrors ``VeloPhex.Platform.Contracts.Packages``. The manifest is a snapshot of the project
+plus the SHA-512 of every file under ``content/``; the Orchestrator inspector and the Runner
+re-verify both, so a package the Python CLI builds must agree with one Studio builds down to
+the byte - see :mod:`velophex._json` for why writing goes through an explicit member order.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable
+from typing import Any, Final
+
+from pydantic import ConfigDict, Field
+
+from velophex import _json
+from velophex.contracts._model import ContractModel, omit_none
+from velophex.contracts.diagnostics import Diagnostic
+from velophex.contracts.diagnostics import PackageDiagnosticCodes as Codes
+from velophex.contracts.project import (
+    ExpressionPolicy,
+    ExpressionPolicyValues,
+    ProjectManifest,
+    expression_fingerprint,
+    expression_policy_problems,
+    validate_project_manifest,
+)
+from velophex.contracts.runtimes import RuntimeKind
+from velophex.contracts.validation import is_safe_relative_path, is_sha512_hex
+
+__all__ = [
+    "CURRENT_MANIFEST_VERSION",
+    "FORMAT_NAME",
+    "MINIMUM_MANIFEST_VERSION",
+    "SCHEMA_URI",
+    "PackageFile",
+    "PackageLayout",
+    "PackageManifest",
+    "create_package_manifest",
+    "describe_file",
+    "read_package_manifest",
+    "sha512_hex",
+    "validate_package_manifest",
+    "write_package_manifest",
+]
+
+FORMAT_NAME: Final = "velophex.package-manifest"
+CURRENT_MANIFEST_VERSION: Final = 2
+#: The oldest manifest version a reader accepts: every version in [minimum, current] is read, a
+#: manifest minor is additive only and unknown members are ignored (ADR-P003, audit VER-01).
+MINIMUM_MANIFEST_VERSION: Final = 2
+SCHEMA_URI: Final = "https://schemas.velophex.com/platform/package-manifest/2/package-manifest.schema.json"
+
+
+class PackageLayout:
+    """Layout of a VeloPhex automation package: a ``.nupkg`` with ``content/`` and ``velophex/``."""
+
+    FORMAT: Final = "velophex-nupkg"
+    FILE_EXTENSION: Final = ".nupkg"
+    NUGET_PACKAGE_TYPE: Final = "VeloPhexAutomation"
+    CONTENT_ROOT: Final = "content/"
+    PROJECT_MANIFEST_PATH: Final = "content/project.json"
+    MANIFEST_PATH: Final = "velophex/package-manifest.json"
+    SIGNATURE_PATH: Final = "velophex/signature.json"
+    DEFAULT_MAXIMUM_PACKAGE_BYTES: Final = 512 * 1024 * 1024
+    MAXIMUM_MANIFEST_BYTES: Final = 4 * 1024 * 1024
+
+    @staticmethod
+    def to_package_path(project_relative_path: str) -> str:
+        """Convert ``Main.xaml`` to ``content/Main.xaml``."""
+        return PackageLayout.CONTENT_ROOT + project_relative_path
+
+    @staticmethod
+    def is_content_path(package_path: str) -> bool:
+        """True for a path under ``content/`` that names something."""
+        return package_path.startswith(PackageLayout.CONTENT_ROOT) and len(package_path) > len(
+            PackageLayout.CONTENT_ROOT
+        )
+
+    @staticmethod
+    def is_nuget_metadata_part(package_path: str) -> bool:
+        """True for the parts NuGet itself adds, which are ignored when verifying."""
+        return (
+            package_path in ("[Content_Types].xml", ".signature.p7s")
+            or package_path.startswith(("_rels/", "package/"))
+            or ("/" not in package_path and package_path.lower().endswith(".nuspec"))
+        )
+
+
+class PackageFile(ContractModel):
+    """One file under ``content/``: its package path, lower-case hex SHA-512 and size."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    path: str
+    sha512: str
+    size: int
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``PackageFile`` record."""
+        return {"path": self.path, "sha512": self.sha512, "size": self.size}
+
+
+class PackageManifest(ContractModel):
+    """A snapshot of the project and a hash of every content file."""
+
+    schema_: str | None = Field(default=None, alias="$schema")
+    format: str
+    manifest_version: int = Field(alias="manifestVersion")
+    package_id: str = Field(alias="packageId")
+    package_version: str = Field(alias="packageVersion")
+    runtime: str
+    required_runtimes: list[str] = Field(alias="requiredRuntimes")
+    created_by: str | None = Field(default=None, alias="createdBy")
+    project: ProjectManifest
+    files: list[PackageFile]
+    expression_policy: ExpressionPolicy | None = Field(default=None, alias="expressionPolicy")
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``PackageManifest`` record."""
+        return (
+            omit_none(
+                {
+                    "$schema": self.schema_,
+                    "format": self.format,
+                    "manifestVersion": self.manifest_version,
+                    "packageId": self.package_id,
+                    "packageVersion": self.package_version,
+                    "runtime": self.runtime,
+                    "requiredRuntimes": list(self.required_runtimes),
+                    "createdBy": self.created_by,
+                    "project": self.project.to_json_value(),
+                    "files": [file.to_json_value() for file in self.files],
+                    "expressionPolicy": (
+                        self.expression_policy.to_json_value() if self.expression_policy is not None else None
+                    ),
+                }
+            )
+            | self.extras()
+        )
+
+
+def sha512_hex(content: bytes) -> str:
+    """The platform hash rule for package files: lower-case hex SHA-512 of the raw bytes."""
+    return hashlib.sha512(content).hexdigest()
+
+
+def describe_file(package_path: str, content: bytes) -> PackageFile:
+    """Describe one content file for the manifest."""
+    return PackageFile(path=package_path, sha512=sha512_hex(content), size=len(content))
+
+
+def create_package_manifest(
+    project: ProjectManifest,
+    content_files: Iterable[PackageFile],
+    created_by: str | None,
+) -> PackageManifest:
+    """Build a manifest the same way ``PackageManifestFactory.Create`` does.
+
+    *content_files* must cover every file under ``content/``, including ``project.json``.
+    """
+    normalized = project.normalized()
+
+    return PackageManifest(
+        **{
+            "$schema": SCHEMA_URI,
+            "format": FORMAT_NAME,
+            "manifestVersion": CURRENT_MANIFEST_VERSION,
+            "packageId": normalized.name,
+            "packageVersion": normalized.version,
+            "runtime": normalized.runtime.kind,
+            "requiredRuntimes": normalized.required_runtimes(),
+            "createdBy": created_by,
+            "project": normalized,
+            "files": sorted(content_files, key=lambda file: file.path),
+        }
+    )
+
+
+def write_package_manifest(manifest: PackageManifest) -> bytes:
+    """Serialize *manifest* exactly as ``PackageManifestSerializer.WriteUtf8`` does."""
+    return (_json.dumps_document(manifest.to_json_value()) + "\n").encode("utf-8")
+
+
+def read_package_manifest(payload: bytes | str) -> tuple[PackageManifest | None, list[Diagnostic]]:
+    """Parse and validate ``velophex/package-manifest.json``."""
+    raw = payload if isinstance(payload, (bytes, bytearray)) else payload.encode("utf-8")
+
+    if len(raw) > PackageLayout.MAXIMUM_MANIFEST_BYTES:
+        message = f"The document is {len(raw)} bytes; the limit is {PackageLayout.MAXIMUM_MANIFEST_BYTES} bytes."
+        return None, [Diagnostic.error(Codes.DOCUMENT_TOO_LARGE, "$", message)]
+
+    try:
+        document = _json.loads(raw)
+    except ValueError as error:
+        return None, [Diagnostic.error(Codes.INVALID_JSON, "$", str(error))]
+
+    if not isinstance(document, dict):
+        return None, [Diagnostic.error(Codes.INVALID_JSON, "$", "The document is not a JSON object.")]
+
+    try:
+        manifest = PackageManifest.model_validate(document)
+    except Exception as error:
+        return None, [Diagnostic.error(Codes.INVALID_JSON, "$", str(error))]
+
+    return manifest, validate_package_manifest(manifest)
+
+
+def validate_package_manifest(manifest: PackageManifest) -> list[Diagnostic]:
+    """Apply the platform rules to *manifest*, mirroring ``PackageManifestValidator``.
+
+    Comparing the file list with the archive itself is the reader's job, not this function's.
+    """
+    diagnostics: list[Diagnostic] = []
+
+    if manifest.format != FORMAT_NAME:
+        diagnostics.append(Diagnostic.error(Codes.UNSUPPORTED_FORMAT, "$.format", f"Expected format '{FORMAT_NAME}'."))
+
+    if not MINIMUM_MANIFEST_VERSION <= manifest.manifest_version <= CURRENT_MANIFEST_VERSION:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.UNSUPPORTED_MANIFEST_VERSION,
+                "$.manifestVersion",
+                f"Manifest version {manifest.manifest_version} is not supported; "
+                f"this platform reads versions {MINIMUM_MANIFEST_VERSION} to {CURRENT_MANIFEST_VERSION}.",
+            )
+        )
+
+    diagnostics.extend(validate_project_manifest(manifest.project, "$.project"))
+    _validate_identity(manifest, diagnostics)
+    _validate_files(manifest, diagnostics)
+    _validate_expression_policy(manifest.expression_policy, diagnostics)
+
+    return diagnostics
+
+
+def _validate_expression_policy(policy: ExpressionPolicy | None, diagnostics: list[Diagnostic]) -> None:
+    """Mirrors ``PackageManifestValidator.ValidateExpressionPolicy``."""
+    if policy is None:
+        return
+
+    for problem in expression_policy_problems(policy.value, policy.extra_types, policy.tier_version):
+        diagnostics.append(Diagnostic.error(Codes.INVALID_EXPRESSION_POLICY, "$.expressionPolicy", problem))
+
+    if policy.tier_version is None:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_EXPRESSION_POLICY,
+                "$.expressionPolicy.tierVersion",
+                "A recorded expression policy names the tier version it was built under.",
+            )
+        )
+        return
+
+    if not ExpressionPolicyValues.is_known(policy.value):
+        return
+
+    extras = (
+        sorted({item.strip() for item in policy.extra_types if item.strip()})
+        if policy.value == ExpressionPolicyValues.DEFAULT_PLUS_TYPES
+        else []
+    )
+    expected = expression_fingerprint(policy.value, policy.tier_version, extras)
+
+    if list(policy.extra_types) != extras or policy.fingerprint != expected:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_EXPRESSION_POLICY,
+                "$.expressionPolicy.fingerprint",
+                "The recorded expression policy is not normalized or its fingerprint is not its own "
+                f"(expected {expected}).",
+            )
+        )
+
+
+def _validate_identity(manifest: PackageManifest, diagnostics: list[Diagnostic]) -> None:
+    project = manifest.project
+
+    if manifest.package_id.casefold() != project.name.casefold():
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.PACKAGE_ID_MISMATCH,
+                "$.packageId",
+                f"The package id must equal the project name '{project.name}'.",
+            )
+        )
+
+    if manifest.package_version != project.version:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.PACKAGE_VERSION_MISMATCH,
+                "$.packageVersion",
+                f"The package version must equal the project version '{project.version}'.",
+            )
+        )
+
+    if manifest.runtime != project.runtime.kind:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.RUNTIME_MISMATCH,
+                "$.runtime",
+                f"The runtime must equal the project runtime '{project.runtime.kind}'.",
+            )
+        )
+
+    expected = project.required_runtimes()
+
+    if sorted(manifest.required_runtimes) != expected:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.REQUIRED_RUNTIMES_MISMATCH,
+                "$.requiredRuntimes",
+                "Required runtimes must be the project runtime plus its automation dependencies: "
+                f"[{', '.join(expected)}].",
+            )
+        )
+
+
+def _validate_files(manifest: PackageManifest, diagnostics: list[Diagnostic]) -> None:
+    paths: set[str] = set()
+    previous: str | None = None
+
+    for index, file in enumerate(manifest.files):
+        path = f"$.files[{index}]"
+
+        if (
+            not PackageLayout.is_content_path(file.path)
+            or not is_safe_relative_path(file.path)
+            or not is_sha512_hex(file.sha512)
+            or file.size < 0
+        ):
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_FILE_ENTRY,
+                    path,
+                    "Files are listed as a safe 'content/...' path, a lowercase hex SHA-512 and a non-negative size.",
+                )
+            )
+
+        key = file.path.casefold()
+
+        if key in paths:
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.DUPLICATE_FILE,
+                    f"{path}.path",
+                    f"'{file.path}' is listed more than once (paths are case-insensitive).",
+                )
+            )
+        else:
+            paths.add(key)
+
+        if previous is not None and previous > file.path:
+            diagnostics.append(
+                Diagnostic.error(Codes.FILES_NOT_SORTED, f"{path}.path", "Files must be ordinally sorted by path.")
+            )
+
+        previous = file.path
+
+    if PackageLayout.PROJECT_MANIFEST_PATH.casefold() not in paths:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.MISSING_PROJECT_MANIFEST, "$.files", f"'{PackageLayout.PROJECT_MANIFEST_PATH}' is not listed."
+            )
+        )
+
+    for index, entry in enumerate(manifest.project.entry_points):
+        if PackageLayout.to_package_path(entry.path).casefold() not in paths:
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.MISSING_ENTRY_POINT_FILE,
+                    f"$.project.entryPoints[{index}].path",
+                    f"Entry point file '{entry.path}' is not in the package.",
+                )
+            )
+
+    lock_file = manifest.project.runtime.lock_file
+
+    if (
+        manifest.project.runtime.kind == RuntimeKind.PYTHON
+        and lock_file is not None
+        and PackageLayout.to_package_path(lock_file).casefold() not in paths
+    ):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.MISSING_PYTHON_LOCK_FILE,
+                "$.project.runtime.lockFile",
+                f"Lock file '{lock_file}' is not in the package.",
+            )
+        )