pptx-cli 1.0.0__py3-none-any.whl

pptx_cli/core/validation.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pptx import Presentation
+
+from pptx_cli.models.manifest import (
+    ManifestDiffResult,
+    ManifestDocument,
+    ValidationIssue,
+    ValidationResult,
+)
+
+
+class ValidationError(ValueError):
+    code: str
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def validate_deck(
+    manifest_dir: Path,
+    manifest: ManifestDocument,
+    deck_path: Path,
+    *,
+    strict: bool,
+) -> ValidationResult:
+    if not deck_path.exists():
+        raise ValidationError("ERR_IO_NOT_FOUND", f"Deck not found: {deck_path}")
+
+    prs = Presentation(str(deck_path))
+    issues: list[ValidationIssue] = []
+    expected_size = manifest.presentation.get("page_size", {})
+    actual_width = int(prs.slide_width or 0)
+    actual_height = int(prs.slide_height or 0)
+    if actual_width != expected_size.get("width_emu") or actual_height != expected_size.get(
+        "height_emu"
+    ):
+        issues.append(
+            ValidationIssue(
+                code="ERR_VALIDATION_PAGE_SIZE",
+                severity="error",
+                message="Deck page size does not match the manifest",
+                details={
+                    "expected": expected_size,
+                    "actual": {"width_emu": actual_width, "height_emu": actual_height},
+                },
+            )
+        )
+
+    layouts_by_source_name = {layout.source_layout_name: layout for layout in manifest.layouts}
+    checked_layouts: set[str] = set()
+    for slide_index, slide in enumerate(prs.slides, start=1):
+        source_layout = getattr(slide, "slide_layout", None)
+        layout_name = getattr(source_layout, "name", None)
+        if layout_name not in layouts_by_source_name:
+            issues.append(
+                ValidationIssue(
+                    code="ERR_VALIDATION_LAYOUT_UNKNOWN",
+                    severity="error",
+                    message="Slide uses a layout that is not present in the manifest",
+                    details={"slide_index": slide_index, "layout_name": layout_name},
+                )
+            )
+            continue
+
+        layout = layouts_by_source_name[layout_name]
+        checked_layouts.add(layout.id)
+        expected_idxs = {placeholder.placeholder_idx for placeholder in layout.placeholders}
+        actual_idxs = {shape.placeholder_format.idx for shape in slide.placeholders}
+        missing_idxs = sorted(expected_idxs - actual_idxs)
+        if missing_idxs:
+            issues.append(
+                ValidationIssue(
+                    code="ERR_VALIDATION_PLACEHOLDER_MISSING",
+                    severity="error",
+                    message="Slide is missing expected placeholders for its layout",
+                    details={
+                        "slide_index": slide_index,
+                        "layout_id": layout.id,
+                        "placeholder_idxs": missing_idxs,
+                    },
+                )
+            )
+
+    if manifest.compatibility_report.findings:
+        for finding in manifest.compatibility_report.findings:
+            if finding.severity == "warning":
+                issues.append(
+                    ValidationIssue(
+                        code=finding.code,
+                        severity="error" if strict else "warning",
+                        message=f"Manifest compatibility warning: {finding.message}",
+                        details=finding.details,
+                    )
+                )
+
+    has_errors = any(issue.severity == "error" for issue in issues)
+    return ValidationResult(
+        manifest_path=str(manifest_dir),
+        deck_path=str(deck_path),
+        ok=not has_errors,
+        issues=issues,
+        checked_slides=len(prs.slides),
+        checked_layouts=len(checked_layouts),
+    )
+
+
+def diff_manifests(left: ManifestDocument, right: ManifestDocument) -> ManifestDiffResult:
+    result = ManifestDiffResult()
+    left_layouts = {layout.id: layout for layout in left.layouts}
+    right_layouts = {layout.id: layout for layout in right.layouts}
+
+    removed_layouts = sorted(set(left_layouts) - set(right_layouts))
+    added_layouts = sorted(set(right_layouts) - set(left_layouts))
+
+    for layout_id in removed_layouts:
+        result.breaking_changes.append({"type": "layout.removed", "layout_id": layout_id})
+    for layout_id in added_layouts:
+        result.additive_changes.append({"type": "layout.added", "layout_id": layout_id})
+
+    shared_layouts = sorted(set(left_layouts) & set(right_layouts))
+    for layout_id in shared_layouts:
+        left_layout = left_layouts[layout_id]
+        right_layout = right_layouts[layout_id]
+        if left_layout.source_layout_name != right_layout.source_layout_name:
+            result.breaking_changes.append(
+                {
+                    "type": "layout.renamed",
+                    "layout_id": layout_id,
+                    "before": left_layout.source_layout_name,
+                    "after": right_layout.source_layout_name,
+                }
+            )
+        left_placeholders = {
+            placeholder.logical_name: placeholder for placeholder in left_layout.placeholders
+        }
+        right_placeholders = {
+            placeholder.logical_name: placeholder for placeholder in right_layout.placeholders
+        }
+        removed_placeholders = sorted(set(left_placeholders) - set(right_placeholders))
+        added_placeholders = sorted(set(right_placeholders) - set(left_placeholders))
+        for placeholder_name in removed_placeholders:
+            result.breaking_changes.append(
+                {
+                    "type": "placeholder.removed",
+                    "layout_id": layout_id,
+                    "placeholder": placeholder_name,
+                }
+            )
+        for placeholder_name in added_placeholders:
+            result.additive_changes.append(
+                {
+                    "type": "placeholder.added",
+                    "layout_id": layout_id,
+                    "placeholder": placeholder_name,
+                }
+            )
+        for placeholder_name in sorted(set(left_placeholders) & set(right_placeholders)):
+            left_placeholder = left_placeholders[placeholder_name]
+            right_placeholder = right_placeholders[placeholder_name]
+            left_geometry = (
+                left_placeholder.left_emu,
+                left_placeholder.top_emu,
+                left_placeholder.width_emu,
+                left_placeholder.height_emu,
+            )
+            right_geometry = (
+                right_placeholder.left_emu,
+                right_placeholder.top_emu,
+                right_placeholder.width_emu,
+                right_placeholder.height_emu,
+            )
+            if left_geometry != right_geometry:
+                result.breaking_changes.append(
+                    {
+                        "type": "placeholder.geometry_changed",
+                        "layout_id": layout_id,
+                        "placeholder": placeholder_name,
+                        "before": left_geometry,
+                        "after": right_geometry,
+                    }
+                )
+            if (
+                left_placeholder.supported_content_types
+                != right_placeholder.supported_content_types
+            ):
+                result.breaking_changes.append(
+                    {
+                        "type": "placeholder.content_types_changed",
+                        "layout_id": layout_id,
+                        "placeholder": placeholder_name,
+                        "before": left_placeholder.supported_content_types,
+                        "after": right_placeholder.supported_content_types,
+                    }
+                )
+
+    left_theme = left.presentation.get("theme", {})
+    right_theme = right.presentation.get("theme", {})
+    if left_theme != right_theme:
+        result.breaking_changes.append(
+            {
+                "type": "theme.changed",
+                "before": left_theme,
+                "after": right_theme,
+            }
+        )
+
+    if not result.breaking_changes and not result.additive_changes:
+        result.unchanged.append("layouts")
+        result.unchanged.append("theme")
+
+    return result

pptx_cli/core/versioning.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+_VERSION_RE = re.compile(r'__version__\s*=\s*["\'](?P<version>\d+\.\d+\.\d+)["\']')
+
+
+@dataclass(frozen=True, slots=True)
+class SemVer:
+    major: int
+    minor: int
+    patch: int
+
+    @classmethod
+    def parse(cls, value: str) -> SemVer:
+        parts = value.split(".")
+        if len(parts) != 3 or not all(part.isdigit() for part in parts):
+            raise ValueError(f"Invalid semantic version: {value}")
+        return cls(*(int(part) for part in parts))
+
+    def bump(self, part: str) -> SemVer:
+        if part == "major":
+            return SemVer(self.major + 1, 0, 0)
+        if part == "minor":
+            return SemVer(self.major, self.minor + 1, 0)
+        if part == "patch":
+            return SemVer(self.major, self.minor, self.patch + 1)
+        raise ValueError(f"Unsupported version part: {part}")
+
+    def __str__(self) -> str:
+        return f"{self.major}.{self.minor}.{self.patch}"
+
+
+def read_version_from_init(init_file: Path) -> SemVer:
+    contents = init_file.read_text(encoding="utf-8")
+    match = _VERSION_RE.search(contents)
+    if match is None:
+        raise ValueError(f"Could not find __version__ in {init_file}")
+    return SemVer.parse(match.group("version"))
+
+
+def write_version_to_init(init_file: Path, version: SemVer) -> None:
+    contents = init_file.read_text(encoding="utf-8")
+    updated = _VERSION_RE.sub(f'__version__ = "{version}"', contents, count=1)
+    init_file.write_text(updated, encoding="utf-8")

pptx_cli/models/__init__.py

@@ -0,0 +1 @@
+"""Typed models for CLI contracts."""

pptx_cli/models/envelope.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class CliMessage(BaseModel):
+    code: str
+    message: str
+    retryable: bool = False
+    retry_after_ms: int | None = None
+    suggested_action: str | None = None
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class Metrics(BaseModel):
+    duration_ms: int
+    operations_executed: int | None = None
+    bytes_written: int | None = None
+
+
+class Envelope(BaseModel):
+    schema_version: str = "1.0"
+    request_id: str
+    ok: bool
+    command: str
+    result: dict[str, Any] | list[Any] | str | int | float | bool | None
+    warnings: list[CliMessage] = Field(default_factory=list)
+    errors: list[CliMessage] = Field(default_factory=list)
+    metrics: Metrics
+
+
+class GuideCommand(BaseModel):
+    id: str
+    summary: str
+    mutates: bool
+    input_schema: dict[str, Any] | None = None
+    output_schema: dict[str, Any] | None = None
+    examples: list[str] = Field(default_factory=list)
+
+
+class GuideDocument(BaseModel):
+    schema_version: Literal["1.0"] = "1.0"
+    compatibility: dict[str, str]
+    commands: list[GuideCommand]
+    exit_codes: dict[str, int]
+    error_codes: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    identifier_conventions: dict[str, str] = Field(default_factory=dict)
+    concurrency: dict[str, Any] = Field(default_factory=dict)

pptx_cli/models/manifest.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class PageSize(BaseModel):
+    width_emu: int
+    height_emu: int
+
+
+class ThemeModel(BaseModel):
+    name: str | None = None
+    colors: dict[str, str] = Field(default_factory=dict)
+    fonts: dict[str, str] = Field(default_factory=dict)
+    effects: dict[str, str] = Field(default_factory=dict)
+
+
+class AssetRef(BaseModel):
+    id: str
+    kind: Literal["image", "media", "embedded", "template", "theme", "xml"]
+    path: str
+    source_path: str | None = None
+    sha256: str
+    size_bytes: int
+
+
+class ProtectedElement(BaseModel):
+    element_id: str
+    element_type: str
+    name: str
+    left_emu: int
+    top_emu: int
+    width_emu: int
+    height_emu: int
+    lock_policy: Literal["locked"] = "locked"
+    asset_ref: str | None = None
+    fingerprint: str
+
+
+class PlaceholderContract(BaseModel):
+    logical_name: str
+    source_name: str
+    placeholder_idx: int
+    placeholder_type: str
+    guidance_text: str | None = None
+    guidance_lines: list[str] = Field(default_factory=list)
+    supported_content_types: list[str]
+    left_emu: int
+    top_emu: int
+    width_emu: int
+    height_emu: int
+    required: bool = False
+    overflow_policy: Literal["fit", "warn", "truncate"] = "warn"
+    text_defaults: dict[str, Any] = Field(default_factory=dict)
+    inheritance_chain: list[str] = Field(default_factory=list)
+    allowed_formatting_overrides: list[str] = Field(default_factory=list)
+
+
+class LayoutContract(BaseModel):
+    id: str
+    name: str
+    aliases: list[str] = Field(default_factory=list)
+    source_master_id: str
+    source_layout_index: int
+    source_layout_name: str
+    description: str | None = None
+    preview_path: str
+    placeholders: list[PlaceholderContract] = Field(default_factory=list)
+    protected_static_elements: list[ProtectedElement] = Field(default_factory=list)
+    validation_rules: dict[str, Any] = Field(default_factory=dict)
+
+
+class MasterContract(BaseModel):
+    id: str
+    name: str
+    layout_ids: list[str] = Field(default_factory=list)
+
+
+class TemplateInfo(BaseModel):
+    name: str
+    source_file: str
+    source_hash: str
+    extracted_at: datetime
+    stored_template_path: str
+    locale: str | None = None
+    owner: str | None = None
+    version: str | None = None
+
+
+class CompatibilityFinding(BaseModel):
+    code: str
+    severity: Literal["info", "warning", "error"]
+    message: str
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class CompatibilityReport(BaseModel):
+    status: Literal["ok", "warn", "error"] = "ok"
+    findings: list[CompatibilityFinding] = Field(default_factory=list)
+
+
+class ManifestDocument(BaseModel):
+    manifest_version: Literal[1] = 1
+    template: TemplateInfo
+    presentation: dict[str, Any]
+    masters: list[MasterContract]
+    layouts: list[LayoutContract]
+    assets: list[AssetRef] = Field(default_factory=list)
+    rules: dict[str, Any] = Field(default_factory=dict)
+    capabilities: dict[str, Any] = Field(default_factory=dict)
+    compatibility_report: CompatibilityReport = Field(default_factory=CompatibilityReport)
+    fingerprints: dict[str, str] = Field(default_factory=dict)
+
+
+class LayoutAnnotation(BaseModel):
+    layout_id: str
+    aliases: list[str] = Field(default_factory=list)
+    semantic_tags: list[str] = Field(default_factory=list)
+    usage_notes: str | None = None
+
+
+class TemplateAnnotations(BaseModel):
+    semantic_tags: list[str] = Field(default_factory=list)
+    operator_notes: str | None = None
+
+
+class AnnotationsDocument(BaseModel):
+    template_annotations: TemplateAnnotations = Field(default_factory=TemplateAnnotations)
+    layouts: list[LayoutAnnotation] = Field(default_factory=list)
+
+
+class InitReport(BaseModel):
+    template: str
+    output_dir: str
+    manifest_path: str
+    findings: list[CompatibilityFinding] = Field(default_factory=list)
+    assets_copied: int = 0
+    layout_count: int = 0
+    placeholder_count: int = 0
+
+
+class SlideSpec(BaseModel):
+    layout: str
+    content: dict[str, Any] = Field(default_factory=dict)
+
+
+class DeckSpec(BaseModel):
+    manifest: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    slides: list[SlideSpec]
+
+
+class ValidationIssue(BaseModel):
+    code: str
+    severity: Literal["warning", "error"]
+    message: str
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class ValidationResult(BaseModel):
+    manifest_path: str
+    deck_path: str
+    ok: bool
+    issues: list[ValidationIssue] = Field(default_factory=list)
+    checked_slides: int = 0
+    checked_layouts: int = 0
+
+
+class ManifestDiffResult(BaseModel):
+    breaking_changes: list[dict[str, Any]] = Field(default_factory=list)
+    additive_changes: list[dict[str, Any]] = Field(default_factory=list)
+    unchanged: list[str] = Field(default_factory=list)