resolvescript 0.1.2__py3-none-any.whl

resolve_script/manifest/__init__.py

@@ -0,0 +1 @@
+"""Manifest model, readers (JSON/XML) and validation."""

resolve_script/manifest/json_reader.py

@@ -0,0 +1,40 @@
+"""JSON manifest reader: load, normalize and report errors with line hints."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .model import Manifest, ManifestError, manifest_from_dict
+
+
+def load_manifest(path: str | Path) -> Manifest:
+    """Read and normalize a ``manifest.json`` file."""
+    file_path = Path(path)
+    try:
+        text = file_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ManifestError(f"cannot read manifest: {exc}", path=str(file_path)) from exc
+    return loads(text, source=str(file_path))
+
+
+def loads(text: str, source: str = "<manifest.json>") -> Manifest:
+    """Parse manifest text into a :class:`Manifest` with error context."""
+    try:
+        raw = json.loads(text)
+    except json.JSONDecodeError as exc:
+        lines = text.splitlines()
+        line_text = lines[exc.lineno - 1] if 0 < exc.lineno <= len(lines) else None
+        raise ManifestError(
+            f"invalid JSON: {exc.msg}",
+            path=source,
+            line=exc.lineno,
+            column=exc.colno,
+            line_text=line_text,
+        ) from exc
+    return manifest_from_dict(raw, source=source)
+
+
+def dumps(manifest: Manifest, indent: int = 2) -> str:
+    """Serialize a manifest back to JSON text (round-trip helper)."""
+    return json.dumps(manifest.to_dict(), ensure_ascii=False, indent=indent) + "\n"

resolve_script/manifest/model.py

@@ -0,0 +1,316 @@
+"""Manifest data model shared by the JSON and XML readers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ManifestError(Exception):
+    """A manifest could not be parsed or normalized.
+
+    Carries enough context to render ``path:line:column`` hints.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        path: str | None = None,
+        line: int | None = None,
+        column: int | None = None,
+        line_text: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.path = path
+        self.line = line
+        self.column = column
+        self.line_text = line_text
+
+    def __str__(self) -> str:
+        parts = []
+        if self.path:
+            loc = self.path
+            if self.line is not None:
+                loc += f":{self.line}"
+                if self.column is not None:
+                    loc += f":{self.column}"
+            parts.append(loc)
+        parts.append(self.message)
+        rendered = ": ".join(parts)
+        if self.line_text:
+            rendered += f"\n    {self.line_text.strip()}"
+        return rendered
+
+
+class Target(str, Enum):
+    """Valid Resolve Scripts subfolders under the per-OS scripts root."""
+
+    COMP = "Comp"
+    UTILITY = "Utility"
+    TOOL = "Tool"
+    RENDER = "Render"
+    DELIVER = "Deliver"
+    EDIT = "Edit"
+    WORKFLOW_INTEGRATIONS = "WorkflowIntegrations"
+    FUSION = "Fusion"
+    ROOT = "root"
+
+    @classmethod
+    def valid_names(cls) -> set[str]:
+        return {t.value for t in cls}
+
+
+# Common misspellings / near-misses → recommended fix (M6 uses this too).
+TARGET_SUGGESTIONS: dict[str, str] = {
+    "comp": "Comp",
+    "utility": "Utility",
+    "tool": "Tool",
+    "render": "Render",
+    "deliver": "Deliver",
+    "edit": "Edit",
+    "scripts": "root",
+    "fusion": "Fusion",
+}
+
+
+@dataclass
+class Compat:
+    """Expo-style compatibility axis (min Resolve / min Python versions)."""
+
+    resolve: str | None = None
+    python: str | None = None
+
+    def as_dict(self) -> dict[str, str]:
+        result: dict[str, str] = {}
+        if self.resolve:
+            result["resolve"] = self.resolve
+        if self.python:
+            result["python"] = self.python
+        return result
+
+
+@dataclass
+class Release:
+    """Published-artifact source for ``add`` / ``install <spec>``."""
+
+    owner: str = ""
+    repo: str = ""
+    url: str = ""
+
+    def as_dict(self) -> dict[str, str]:
+        result: dict[str, str] = {}
+        if self.owner:
+            result["owner"] = self.owner
+        if self.repo:
+            result["repo"] = self.repo
+        if self.url:
+            result["url"] = self.url
+        return result
+
+    @property
+    def github_spec(self) -> str | None:
+        if self.owner and self.repo:
+            return f"github:{self.owner}/{self.repo}"
+        return None
+
+
+@dataclass
+class ConsolidateConfig:
+    """Single-file build options (M3)."""
+
+    enabled: bool = True
+    output: str | None = None
+    entry: str | None = None
+    exclude: list[str] = field(default_factory=list)
+    no_comment: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "enabled": self.enabled,
+            "output": self.output,
+            "entry": self.entry,
+            "exclude": list(self.exclude),
+            "no_comment": list(self.no_comment),
+        }
+
+
+@dataclass
+class InstallConfig:
+    """Copy rules and install destination."""
+
+    as_directory: bool = True
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+    to: str = "resolve"  # "resolve" (Fusion Scripts) | "framework" (plugin dir)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "as_directory": self.as_directory,
+            "include": list(self.include),
+            "exclude": list(self.exclude),
+            "to": self.to,
+        }
+
+
+@dataclass
+class Manifest:
+    """A Resolve script manifest (or, with ``kind="extension"``, a plugin)."""
+
+    name: str
+    version: str
+    author: str = ""
+    description: str = ""
+    python: str = ""
+    package_dir: str = ""
+    entrypoint: str | None = None
+    id: str | None = None
+    compat: Compat = field(default_factory=Compat)
+    release: Release = field(default_factory=Release)
+    targets: list[str] = field(default_factory=list)
+    scripts_root: str = ""
+    consolidate: ConsolidateConfig = field(default_factory=ConsolidateConfig)
+    dependencies: list[str] = field(default_factory=list)
+    install: InstallConfig = field(default_factory=InstallConfig)
+    kind: str = "script"  # "script" | "extension" (plugin)
+
+    @property
+    def is_plugin(self) -> bool:
+        return self.kind == "extension"
+
+    @property
+    def default_package_dir(self) -> str:
+        """Effective package directory (defaults to the extension root)."""
+        return self.package_dir or self.name
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "name": self.name,
+            "version": self.version,
+        }
+        for key in ("author", "description", "python", "package_dir", "entrypoint"):
+            value = getattr(self, key)
+            if value:
+                result[key] = value
+        if self.id:
+            result["id"] = self.id
+        if self.compat.as_dict():
+            result["compat"] = self.compat.as_dict()
+        if self.release.as_dict():
+            result["release"] = self.release.as_dict()
+        if self.targets:
+            result["targets"] = list(self.targets)
+        if self.scripts_root:
+            result["scripts_root"] = self.scripts_root
+        if self.consolidate.enabled or self.consolidate.output or self.consolidate.entry:
+            result["consolidate"] = self.consolidate.as_dict()
+        if self.dependencies:
+            result["dependencies"] = list(self.dependencies)
+        if self.install.as_directory or self.install.include or self.install.exclude or self.install.to != "resolve":
+            result["install"] = self.install.as_dict()
+        if self.kind != "script":
+            result["kind"] = self.kind
+        return result
+
+
+def _as_str(value: Any, key: str, source: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ManifestError(f"field '{key}' must be a string, got {type(value).__name__}", path=source)
+    return value
+
+
+def _as_str_list(value: Any, key: str, source: str) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if not isinstance(value, list):
+        raise ManifestError(f"field '{key}' must be a list of strings", path=source)
+    for item in value:
+        if not isinstance(item, str):
+            raise ManifestError(f"field '{key}' must contain only strings, got {type(item).__name__}", path=source)
+    return list(value)
+
+
+def _as_bool(value: Any, key: str, source: str, default: bool) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"true", "1", "yes", "on"}:
+            return True
+        if normalized in {"false", "0", "no", "off"}:
+            return False
+    raise ManifestError(f"field '{key}' must be a boolean, got {value!r}", path=source)
+
+
+def _as_dict(value: Any, key: str, source: str) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ManifestError(f"field '{key}' must be an object", path=source)
+    return value
+
+
+def manifest_from_dict(raw: dict[str, Any], source: str = "<manifest>") -> Manifest:
+    """Normalize a raw manifest dict (from JSON or XML) into a :class:`Manifest`."""
+    if not isinstance(raw, dict):
+        raise ManifestError(f"manifest must be a JSON object, got {type(raw).__name__}", path=source)
+
+    name = _as_str(raw.get("name"), "name", source)
+    version = _as_str(raw.get("version"), "version", source)
+    if not name:
+        raise ManifestError("missing required field 'name'", path=source)
+    if not version:
+        raise ManifestError("missing required field 'version'", path=source)
+
+    compat_raw = _as_dict(raw.get("compat"), "compat", source)
+    release_raw = _as_dict(raw.get("release"), "release", source)
+    cons_raw = _as_dict(raw.get("consolidate"), "consolidate", source)
+    inst_raw = _as_dict(raw.get("install"), "install", source)
+
+    install_to = _as_str(inst_raw.get("to"), "install.to", source) or "resolve"
+    if install_to not in {"resolve", "framework"}:
+        raise ManifestError(f"install.to must be 'resolve' or 'framework', got {install_to!r}", path=source)
+
+    return Manifest(
+        name=name,
+        version=version,
+        kind=_as_str(raw.get("kind"), "kind", source) or "script",
+        author=_as_str(raw.get("author"), "author", source) or "",
+        description=_as_str(raw.get("description"), "description", source) or "",
+        python=_as_str(raw.get("python"), "python", source) or "",
+        package_dir=_as_str(raw.get("package_dir"), "package_dir", source) or "",
+        entrypoint=_as_str(raw.get("entrypoint"), "entrypoint", source),
+        id=_as_str(raw.get("id"), "id", source),
+        compat=Compat(
+            resolve=_as_str(compat_raw.get("resolve"), "compat.resolve", source),
+            python=_as_str(compat_raw.get("python"), "compat.python", source),
+        ),
+        release=Release(
+            owner=_as_str(release_raw.get("owner"), "release.owner", source) or "",
+            repo=_as_str(release_raw.get("repo"), "release.repo", source) or "",
+            url=_as_str(release_raw.get("url"), "release.url", source) or "",
+        ),
+        targets=_as_str_list(raw.get("targets"), "targets", source),
+        scripts_root=_as_str(raw.get("scripts_root"), "scripts_root", source) or "",
+        consolidate=ConsolidateConfig(
+            enabled=_as_bool(cons_raw.get("enabled"), "consolidate.enabled", source, True),
+            output=_as_str(cons_raw.get("output"), "consolidate.output", source),
+            entry=_as_str(cons_raw.get("entry"), "consolidate.entry", source),
+            exclude=_as_str_list(cons_raw.get("exclude"), "consolidate.exclude", source),
+            no_comment=_as_str_list(cons_raw.get("no_comment"), "consolidate.no_comment", source),
+        ),
+        dependencies=_as_str_list(raw.get("dependencies"), "dependencies", source),
+        install=InstallConfig(
+            as_directory=_as_bool(inst_raw.get("as_directory"), "install.as_directory", source, True),
+            include=_as_str_list(inst_raw.get("include"), "install.include", source),
+            exclude=_as_str_list(inst_raw.get("exclude"), "install.exclude", source),
+            to=install_to,
+        ),
+    )

resolve_script/manifest/validation.py

@@ -0,0 +1,81 @@
+"""Semantic validation of a parsed manifest.
+
+The readers guarantee *shape* (correct types, required fields). This module
+checks *meaning*: version format, target whitelist, install-path sanity, and
+plugin gating. Returns a list of human-readable errors; an empty list means ok.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import PurePosixPath
+
+from .model import TARGET_SUGGESTIONS, Manifest, Target
+
+_SEMVER = re.compile(
+    r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"
+    r"(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?"
+    r"(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$"
+)
+
+_REQUIRED = ("name", "version")
+
+
+def is_valid_semver(version: str) -> bool:
+    return bool(_SEMVER.match(version.strip()))
+
+
+def validate_target(target: str) -> str | None:
+    """Return an error string for an unknown target name, or ``None`` if ok."""
+    if target in Target.valid_names():
+        return None
+    suggestion = TARGET_SUGGESTIONS.get(target.lower())
+    hint = f" (did you mean '{suggestion}'?)" if suggestion else ""
+    return f"unknown target '{target}'{hint}; valid: {', '.join(sorted(Target.valid_names()))}"
+
+
+def _path_is_sane(output: str | None, field_name: str) -> list[str]:
+    if not output:
+        return []
+    path = PurePosixPath(output.replace("\\", "/"))
+    if path.is_absolute() or any(part in {".", ".."} for part in path.parts):
+        return [f"{field_name} must be a relative path with no '.'/'..' segments (got '{output}')"]
+    return []
+
+
+def validate_manifest(manifest: Manifest) -> list[str]:
+    """Return a list of validation errors for :class:`Manifest`."""
+    errors: list[str] = []
+
+    for field_name in _REQUIRED:
+        if not getattr(manifest, field_name):
+            errors.append(f"missing required field '{field_name}'")
+
+    if manifest.version and not is_valid_semver(manifest.version):
+        errors.append(f"invalid version '{manifest.version}' (expected strict semver, e.g. 1.2.3, 1.2.3-rc1)")
+
+    if manifest.targets:
+        for target in manifest.targets:
+            error = validate_target(target)
+            if error:
+                errors.append(error)
+    elif manifest.kind == "script":
+        errors.append("no 'targets' declared (e.g. Comp/Utility) for a Resolve script")
+
+    errors.extend(_path_is_sane(manifest.consolidate.output, "consolidate.output"))
+    errors.extend(_path_is_sane(manifest.entrypoint, "entrypoint"))
+
+    if manifest.consolidate.enabled and not manifest.consolidate.entry:
+        errors.append("consolidate.enabled is true but 'consolidate.entry' is not set (package entry module)")
+
+    if manifest.kind == "extension" and manifest.release.github_spec is None and not manifest.release.url:
+        errors.append("plugin manifests need a source: set 'release.owner/repo' or 'release.url'")
+
+    return errors
+
+
+def validate_manifest_or_throw(manifest: Manifest) -> None:
+    """Raise ``ValueError`` on the first validation error (for callers)."""
+    errors = validate_manifest(manifest)
+    if errors:
+        raise ValueError(errors[0])

resolve_script/manifest/xml_reader.py

@@ -0,0 +1,162 @@
+"""XML manifest reader: ElementTree → same dict → same :class:`Manifest`.
+
+The XML shape mirrors the JSON shape 1:1 so both readers normalize through the
+same :func:`~resolve_script.manifest.model.manifest_from_dict` and can never
+drift (parity guaranteed by construction).
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Any
+
+from .model import Manifest, ManifestError, manifest_from_dict
+
+
+def _text(el: ET.Element | None) -> str | None:
+    if el is None or el.text is None:
+        return None
+    stripped = el.text.strip()
+    return stripped or None
+
+
+def _attr(el: ET.Element | None, name: str) -> str | None:
+    if el is None:
+        return None
+    value = el.get(name)
+    return value.strip() if value is not None and value.strip() else None
+
+
+def _child(root: ET.Element, tag: str) -> str | None:
+    return _text(root.find(tag))
+
+
+def _child_list(root: ET.Element, wrapper: str, item: str) -> list[str]:
+    result: list[str] = []
+    container = root.find(wrapper)
+    if container is not None:
+        for el in container.findall(item):
+            value = _text(el)
+            if value is not None:
+                result.append(value)
+    return result
+
+
+def _to_plain(root: ET.Element, source: str) -> dict[str, Any]:
+    """Convert an XML manifest tree into the JSON-equivalent dict shape."""
+    raw: dict[str, Any] = {}
+    for key in (
+        "name",
+        "version",
+        "kind",
+        "author",
+        "description",
+        "python",
+        "package_dir",
+        "entrypoint",
+        "id",
+        "scripts_root",
+    ):
+        value = _child(root, key)
+        if value is not None:
+            raw[key] = value
+
+    targets = _child_list(root, "targets", "target")
+    if targets:
+        raw["targets"] = targets
+
+    compat = root.find("compat")
+    if compat is not None:
+        raw["compat"] = {k: _text(compat.find(k)) for k in ("resolve", "python") if _text(compat.find(k)) is not None}
+
+    release = root.find("release")
+    if release is not None:
+        raw["release"] = {
+            k: v
+            for k in ("owner", "repo", "url")
+            if (v := _text(release.find(k))) is not None
+        }
+
+    consolidate = root.find("consolidate")
+    if consolidate is not None:
+        cons: dict[str, Any] = {}
+        enabled = _attr(consolidate, "enabled")
+        output = _attr(consolidate, "output")
+        if enabled is not None:
+            cons["enabled"] = enabled
+        if output is not None:
+            cons["output"] = output
+        entry = _child(consolidate, "entry")
+        if entry is not None:
+            cons["entry"] = entry
+        exclude = _text_list(consolidate, "exclude")
+        no_comment = _text_list(consolidate, "no_comment")
+        if exclude:
+            cons["exclude"] = exclude
+        if no_comment:
+            cons["no_comment"] = no_comment
+        raw["consolidate"] = cons
+
+    deps = _child_list(root, "dependencies", "dependency")
+    if deps:
+        raw["dependencies"] = deps
+
+    install = root.find("install")
+    if install is not None:
+        inst: dict[str, Any] = {}
+        as_directory = _attr(install, "as_directory")
+        to = _attr(install, "to")
+        if as_directory is not None:
+            inst["as_directory"] = as_directory
+        if to is not None:
+            inst["to"] = to
+        include = _text_list(install, "include")
+        exclude = _text_list(install, "exclude")
+        if include:
+            inst["include"] = include
+        if exclude:
+            inst["exclude"] = exclude
+        raw["install"] = inst
+
+    return raw
+
+
+def _text_list(container: ET.Element, tag: str) -> list[str]:
+    result: list[str] = []
+    for el in container.findall(tag):
+        value = _text(el)
+        if value is not None:
+            result.append(value)
+    return result
+
+
+def load_manifest(path: str | Path) -> Manifest:
+    """Read and normalize a ``manifest.xml`` file."""
+    file_path = Path(path)
+    try:
+        text = file_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ManifestError(f"cannot read manifest: {exc}", path=str(file_path)) from exc
+    return loads(text, source=str(file_path))
+
+
+def loads(text: str, source: str = "<manifest.xml>") -> Manifest:
+    """Parse manifest XML text into a :class:`Manifest` with error context."""
+    try:
+        root = ET.fromstring(text)
+    except ET.ParseError as exc:
+        line, column = getattr(exc, "position", (None, None))
+        lines = text.splitlines()
+        line_text = lines[line - 1] if line and 0 < line <= len(lines) else None
+        raise ManifestError(
+            f"invalid XML: {exc}",
+            path=source,
+            line=line,
+            column=column,
+            line_text=line_text,
+        ) from exc
+    if root.tag != "manifest":
+        raise ManifestError(f"expected a <manifest> root element, got <{root.tag}>", path=source)
+    raw = _to_plain(root, source)
+    return manifest_from_dict(raw, source=source)