python-hwpx 3.3.0__py3-none-any.whl → 3.3.1__py3-none-any.whl

hwpx/agent/blueprint/model.py

@@ -242,10 +242,7 @@ def _validate_resource(value: object, *, name: str) -> dict[str, Any]:
     return record
 
 
-def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool = True) -> dict[str, Any]:
-    """Validate and detach one strict ``hwpx.agent-blueprint/v1`` manifest."""
-
-    manifest = _object(value, "blueprint")
+def _validate_manifest_header(manifest: dict[str, Any]) -> None:
     _exact_keys(manifest, required=_MANIFEST_KEYS, name="blueprint")
     if manifest["schemaVersion"] != BLUEPRINT_SCHEMA:
         raise AgentContractError("invalid_syntax", "unsupported blueprint schema", target="schemaVersion")
@@ -257,12 +254,16 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
     if mode not in BLUEPRINT_MODES:
         raise AgentContractError("invalid_syntax", "unsupported blueprint mode", target="mode")
 
+
+def _validate_source(manifest: dict[str, Any]) -> None:
     source = _object(manifest["source"], "source")
     _exact_keys(source, required={"revision", "label"}, name="source")
     if not REVISION_PATTERN.fullmatch(str(source["revision"])):
         raise AgentContractError("invalid_syntax", "source.revision must be sha256", target="source.revision")
     _validate_public_json(source, name="source")
 
+
+def _validate_root(manifest: dict[str, Any]) -> dict[str, Any]:
     root = _object(manifest["root"], "root")
     _exact_keys(
         root,
@@ -275,7 +276,12 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
         raise AgentContractError("unknown_kind", "root kind is unknown", target="root.kind")
     if not str(root["sourcePath"]).startswith("/"):
         raise AgentContractError("invalid_syntax", "root sourcePath must be semantic", target="root.sourcePath")
+    return root
+
 
+def _validate_nodes(
+    manifest: dict[str, Any],
+) -> tuple[list[dict[str, Any]], set[str], dict[str, dict[str, Any]]]:
     nodes = _list(manifest["nodes"], "nodes")
     if not nodes or len(nodes) > MAX_BLUEPRINT_NODES:
         raise AgentContractError("resource_limit", "node count is outside limits", target="nodes")
@@ -321,7 +327,15 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
         _validate_public_json(node["sourceHint"], name=f"{name}.sourceHint")
         detached_nodes.append(node)
         nodes_by_id[node_id] = node
+    return detached_nodes, node_ids, nodes_by_id
+
 
+def _check_node_tree_shape(
+    root: dict[str, Any],
+    detached_nodes: list[dict[str, Any]],
+    node_ids: set[str],
+    nodes_by_id: dict[str, dict[str, Any]],
+) -> str:
     if str(root["blueprintId"]) not in node_ids:
         raise AgentContractError("invariant_violation", "root does not reference a node", target="root")
     for index, node in enumerate(detached_nodes):
@@ -344,6 +358,14 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
         raise AgentContractError(
             "invariant_violation", "blueprint nodes must form one rooted tree", target="nodes"
         )
+    return root_id
+
+
+def _check_node_reachability(
+    root_id: str,
+    node_ids: set[str],
+    nodes_by_id: dict[str, dict[str, Any]],
+) -> None:
     visited: set[str] = set()
     visiting: set[str] = set()
 
@@ -364,6 +386,10 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
     if visited != node_ids:
         raise AgentContractError("invariant_violation", "blueprint contains orphan nodes", target="nodes")
 
+
+def _validate_dependency_records(
+    manifest: dict[str, Any],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
     styles = _list(manifest["styles"], "styles")
     numbering = _list(manifest["numbering"], "numbering")
     resources = _list(manifest["resources"], "resources")
@@ -382,6 +408,14 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
     detached_resources = [
         _validate_resource(item, name=f"resources[{index}]") for index, item in enumerate(resources)
     ]
+    return detached_styles, detached_numbering, detached_resources
+
+
+def _check_dependency_uniqueness(
+    detached_styles: list[dict[str, Any]],
+    detached_numbering: list[dict[str, Any]],
+    detached_resources: list[dict[str, Any]],
+) -> list[str]:
     style_keys = [str(item["key"]) for item in detached_styles]
     numbering_keys = [str(item["key"]) for item in detached_numbering]
     resource_keys = [str(item["key"]) for item in detached_resources]
@@ -393,10 +427,18 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
         raise AgentContractError("invariant_violation", "resource asset paths must be unique", target="resources")
     if sum(int(item["size"]) for item in detached_resources) > MAX_TOTAL_ASSET_BYTES:
         raise AgentContractError("resource_limit", "total asset bytes exceed limit", target="resources")
+    return dependency_keys
+
 
-    style_key_set = set(style_keys)
-    numbering_key_set = set(numbering_keys)
-    resource_key_set = set(resource_keys)
+def _check_node_dependency_refs(
+    detached_nodes: list[dict[str, Any]],
+    detached_styles: list[dict[str, Any]],
+    detached_numbering: list[dict[str, Any]],
+    detached_resources: list[dict[str, Any]],
+) -> None:
+    style_key_set = {str(item["key"]) for item in detached_styles}
+    numbering_key_set = {str(item["key"]) for item in detached_numbering}
+    resource_key_set = {str(item["key"]) for item in detached_resources}
     for index, node in enumerate(detached_nodes):
         if not set(node["styleRefs"]) <= style_key_set:
             raise AgentContractError("invariant_violation", "node has an orphan style reference", target=f"nodes[{index}].styleRefs")
@@ -405,6 +447,12 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
         if not set(node["resourceRefs"]) <= resource_key_set:
             raise AgentContractError("invariant_violation", "node has an orphan resource reference", target=f"nodes[{index}].resourceRefs")
 
+
+def _validate_reference_records(
+    manifest: dict[str, Any],
+    node_ids: set[str],
+    dependency_keys: list[str],
+) -> tuple[list[dict[str, Any]], dict[str, list[str]]]:
     references = _list(manifest["references"], "references")
     if len(references) > MAX_REFERENCES:
         raise AgentContractError("resource_limit", "reference count exceeds limit", target="references")
@@ -423,6 +471,13 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
         if target in node_ids:
             reference_edges[str(record["from"])].append(target)
         reference_records.append(record)
+    return reference_records, reference_edges
+
+
+def _check_reference_inventory(
+    detached_nodes: list[dict[str, Any]],
+    reference_records: list[dict[str, Any]],
+) -> None:
     for index, node in enumerate(detached_nodes):
         declared_fields = {
             str(record["field"])
@@ -431,6 +486,12 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
         }
         if set(node["references"]) != declared_fields:
             raise AgentContractError("invariant_violation", "node reference inventory is inconsistent", target=f"nodes[{index}].references")
+
+
+def _check_reference_acyclicity(
+    node_ids: set[str],
+    reference_edges: dict[str, list[str]],
+) -> None:
     reference_visited: set[str] = set()
     reference_visiting: set[str] = set()
 
@@ -448,6 +509,8 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
     for node_id in sorted(node_ids):
         visit_reference(node_id)
 
+
+def _validate_metadata_sections(manifest: dict[str, Any]) -> list[Any]:
     unsupported = _list(manifest["unsupported"], "unsupported")
     for index, item in enumerate(unsupported):
         record = _object(item, f"unsupported[{index}]")
@@ -471,7 +534,10 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
     if fidelity["ceiling"] not in FIDELITY_LEVELS:
         raise AgentContractError("invalid_syntax", "fidelity ceiling is invalid", target="fidelity.ceiling")
     fidelity["reasons"] = [str(item) for item in _list(fidelity["reasons"], "fidelity.reasons")]
+    return unsupported
 
+
+def _verify_manifest_integrity(manifest: dict[str, Any], verify_hash: bool) -> None:
     _validate_public_json(manifest, name="blueprint")
     declared_hash = manifest["blueprintHash"]
     if not SHA256_PATTERN.fullmatch(str(declared_hash)):
@@ -479,6 +545,36 @@ def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool =
     if verify_hash and declared_hash != blueprint_hash(manifest):
         raise AgentContractError("verification_failed", "blueprintHash mismatch", target="blueprintHash")
     canonical_manifest_bytes(manifest, include_hash=True)
+
+
+def validate_blueprint_manifest(value: Mapping[str, Any], *, verify_hash: bool = True) -> dict[str, Any]:
+    """Validate and detach one strict ``hwpx.agent-blueprint/v1`` manifest."""
+
+    manifest = _object(value, "blueprint")
+    _validate_manifest_header(manifest)
+    _validate_source(manifest)
+    root = _validate_root(manifest)
+
+    detached_nodes, node_ids, nodes_by_id = _validate_nodes(manifest)
+    root_id = _check_node_tree_shape(root, detached_nodes, node_ids, nodes_by_id)
+    _check_node_reachability(root_id, node_ids, nodes_by_id)
+
+    detached_styles, detached_numbering, detached_resources = _validate_dependency_records(manifest)
+    dependency_keys = _check_dependency_uniqueness(
+        detached_styles, detached_numbering, detached_resources
+    )
+    _check_node_dependency_refs(
+        detached_nodes, detached_styles, detached_numbering, detached_resources
+    )
+
+    reference_records, reference_edges = _validate_reference_records(
+        manifest, node_ids, dependency_keys
+    )
+    _check_reference_inventory(detached_nodes, reference_records)
+    _check_reference_acyclicity(node_ids, reference_edges)
+
+    unsupported = _validate_metadata_sections(manifest)
+    _verify_manifest_integrity(manifest, verify_hash)
     return {
         **manifest,
         "nodes": detached_nodes,

hwpx/tools/package_validator.py

@@ -8,13 +8,15 @@ import xml.etree.ElementTree as ET
 from dataclasses import dataclass
 from pathlib import Path, PurePosixPath
 from typing import Any, BinaryIO, Literal, Sequence
-from zipfile import ZIP_STORED, BadZipFile, ZipFile
+from zipfile import ZIP_STORED, BadZipFile, ZipFile, ZipInfo
 
 from lxml import etree as LET  # type: ignore[reportMissingImports]
 
 from ..oxml.namespaces import HWPML_COMPAT_ROOT_NAMESPACES
 from ..opc.relationships import (
     MAIN_ROOTFILE_MEDIA_TYPE,
+    ManifestRelationships,
+    RootFileRef,
     is_header_part_name,
     is_section_part_name,
     parse_container_rootfiles,
@@ -562,6 +564,312 @@ def _fallback_named_parts(
     return matches
 
 
+def _check_mimetype(
+    zf: ZipFile,
+    infos: list[ZipInfo],
+    name_set: set[str],
+    issues: list[PackageValidationIssue],
+) -> None:
+    if MIMETYPE_PATH not in name_set:
+        _error(issues, MIMETYPE_PATH, "missing required file")
+        return
+    mimetype_bytes = _safe_read(zf, MIMETYPE_PATH)
+    if mimetype_bytes is None:
+        _error(
+            issues,
+            MIMETYPE_PATH,
+            "unable to read entry for integrity validation",
+        )
+        return
+    try:
+        mimetype = mimetype_bytes.decode("utf-8").strip()
+    except UnicodeDecodeError:
+        mimetype = "<binary>"
+    if mimetype != EXPECTED_MIMETYPE:
+        _error(
+            issues,
+            MIMETYPE_PATH,
+            f"expected {EXPECTED_MIMETYPE!r}, got {mimetype!r}",
+        )
+    if infos[0].filename != MIMETYPE_PATH:
+        _error(issues, MIMETYPE_PATH, "must be the first ZIP entry")
+    if zf.getinfo(MIMETYPE_PATH).compress_type != ZIP_STORED:
+        _error(issues, MIMETYPE_PATH, "must use ZIP_STORED")
+
+
+def _check_required_presence(
+    name_set: set[str], issues: list[PackageValidationIssue]
+) -> None:
+    if CONTAINER_PATH not in name_set:
+        _error(issues, CONTAINER_PATH, "missing required file")
+    if VERSION_PATH not in name_set:
+        _warning(
+            issues,
+            VERSION_PATH,
+            "missing optional version.xml; minimum editor-open package set allows omission",
+        )
+
+
+def _check_preview_text(
+    zf: ZipFile, name_set: set[str], issues: list[PackageValidationIssue]
+) -> None:
+    if PREVIEW_TEXT_PATH not in name_set:
+        _warning(
+            issues,
+            PREVIEW_TEXT_PATH,
+            "missing Preview/PrvText.txt; macOS Hancom compatibility may require it",
+        )
+        return
+    preview_bytes = _safe_read(zf, PREVIEW_TEXT_PATH)
+    if preview_bytes is None:
+        _error(issues, PREVIEW_TEXT_PATH, "unable to read preview text entry")
+    elif len(preview_bytes) > 1024 * 1024:
+        _warning(
+            issues,
+            PREVIEW_TEXT_PATH,
+            "Preview/PrvText.txt is unusually large; expected a compact text snapshot",
+        )
+
+
+def _parse_all_xml(
+    zf: ZipFile, names: list[str], issues: list[PackageValidationIssue]
+) -> dict[str, ET.Element]:
+    xml_roots: dict[str, ET.Element] = {}
+    for name in names:
+        if not (name.endswith(".xml") or name.endswith(".hpf")):
+            continue
+        payload = _safe_read(zf, name)
+        if payload is None:
+            _error(issues, name, "unable to read entry for XML parsing")
+            continue
+        try:
+            root = _parse_xml(payload)
+            xml_roots[name] = root
+            _check_hwpml_compat_root(issues, name, payload, root)
+            _check_line_seg_text_positions(issues, name, root)
+            _check_table_editor_acceptance(issues, name, root)
+            _check_section_properties_location(issues, name, root)
+            _check_header_editor_acceptance(issues, name, root)
+            _check_bold_fontref_axis(issues, name, root)
+        except ValueError as exc:
+            _error(issues, name, str(exc))
+    return xml_roots
+
+
+def _check_rootfile_parts(
+    rootfiles: tuple[RootFileRef, ...],
+    name_set: set[str],
+    issues: list[PackageValidationIssue],
+) -> None:
+    for rootfile in rootfiles:
+        if rootfile.full_path not in name_set:
+            _error(
+                issues,
+                CONTAINER_PATH,
+                f"rootfile points to missing part {rootfile.full_path!r}",
+            )
+
+
+def _check_manifest_hrefs(
+    relationships: ManifestRelationships,
+    selected_rootfile: RootFileRef,
+    name_set: set[str],
+    issues: list[PackageValidationIssue],
+) -> None:
+    for item in relationships.items:
+        if item.resolved_path not in name_set:
+            _error(
+                issues,
+                selected_rootfile.full_path,
+                f"manifest href missing from archive: {item.href!r} -> {item.resolved_path!r}",
+            )
+
+    for idref in relationships.dangling_idrefs:
+        _warning(
+            issues,
+            selected_rootfile.full_path,
+            f"spine itemref references missing manifest id {idref!r}",
+        )
+
+
+def _resolve_section_paths(
+    relationships: ManifestRelationships,
+    selected_rootfile: RootFileRef,
+    name_set: set[str],
+    issues: list[PackageValidationIssue],
+) -> list[str]:
+    section_paths = [
+        path for path in relationships.spine_paths if is_section_part_name(path)
+    ]
+    resolved_section_paths: list[str]
+    if section_paths:
+        resolved_section_paths = list(dict.fromkeys(section_paths))
+        for path in section_paths:
+            if path not in name_set:
+                _error(
+                    issues,
+                    selected_rootfile.full_path,
+                    f"spine section part missing from archive: {path!r}",
+                )
+    else:
+        fallback_sections = [
+            name for name in sorted(name_set) if is_section_part_name(name)
+        ]
+        if fallback_sections:
+            resolved_section_paths = fallback_sections
+            _warning(
+                issues,
+                selected_rootfile.full_path,
+                "manifest spine does not resolve any section parts; engine will fall back "
+                "to filename-based section discovery",
+            )
+        else:
+            resolved_section_paths = []
+            _error(
+                issues,
+                selected_rootfile.full_path,
+                "no section parts found in manifest spine or archive fallback",
+            )
+    return resolved_section_paths
+
+
+def _check_header_section_counts(
+    relationships: ManifestRelationships,
+    xml_roots: dict[str, ET.Element],
+    resolved_section_paths: list[str],
+    name_set: set[str],
+    issues: list[PackageValidationIssue],
+) -> None:
+    resolved_header_paths = list(dict.fromkeys(relationships.header_paths))
+    if not resolved_header_paths and HEADER_PATH in name_set:
+        resolved_header_paths = [HEADER_PATH]
+    for header_path in resolved_header_paths:
+        header_root = xml_roots.get(header_path)
+        if header_root is None or _local_name(header_root) != "head":
+            continue
+        declared_section_count = header_root.get("secCnt")
+        if declared_section_count is None:
+            _warning(
+                issues,
+                header_path,
+                "hh:head secCnt is missing; resolved section count cannot be cross-checked",
+            )
+            continue
+        try:
+            parsed_section_count = int(declared_section_count)
+        except ValueError:
+            _error(
+                issues,
+                header_path,
+                f"hh:head secCnt must be an integer, got {declared_section_count!r}",
+            )
+            continue
+        if parsed_section_count != len(resolved_section_paths):
+            _error(
+                issues,
+                header_path,
+                "hh:head secCnt does not match resolved section count: "
+                f"declared={parsed_section_count}, resolved={len(resolved_section_paths)}",
+            )
+
+
+def _check_header_fallback(
+    relationships: ManifestRelationships,
+    name_set: set[str],
+    selected_rootfile: RootFileRef,
+    issues: list[PackageValidationIssue],
+) -> None:
+    if not relationships.header_paths and HEADER_PATH in name_set:
+        _warning(
+            issues,
+            selected_rootfile.full_path,
+            "manifest spine does not resolve a header part; engine will fall back to "
+            f"{HEADER_PATH!r}",
+        )
+
+    for path in relationships.header_paths:
+        if path not in name_set:
+            _error(
+                issues,
+                selected_rootfile.full_path,
+                f"header part missing from archive: {path!r}",
+            )
+
+
+def _check_master_page_parts(
+    relationships: ManifestRelationships,
+    name_set: set[str],
+    selected_rootfile: RootFileRef,
+    issues: list[PackageValidationIssue],
+) -> None:
+    if not relationships.master_page_paths:
+        fallback_master_pages = _fallback_named_parts(
+            name_set, token="master", extra_token="page"
+        )
+        if fallback_master_pages:
+            _warning(
+                issues,
+                selected_rootfile.full_path,
+                "manifest does not reference masterPage parts; engine will fall back to "
+                "filename-based discovery",
+            )
+    for path in relationships.master_page_paths:
+        if path not in name_set:
+            _error(
+                issues,
+                selected_rootfile.full_path,
+                f"masterPage part missing from archive: {path!r}",
+            )
+
+
+def _check_history_parts(
+    relationships: ManifestRelationships,
+    name_set: set[str],
+    selected_rootfile: RootFileRef,
+    issues: list[PackageValidationIssue],
+) -> None:
+    if not relationships.history_paths:
+        fallback_histories = _fallback_named_parts(name_set, token="history")
+        if fallback_histories:
+            _warning(
+                issues,
+                selected_rootfile.full_path,
+                "manifest does not reference history parts; engine will fall back to "
+                "filename-based discovery",
+            )
+    for path in relationships.history_paths:
+        if path not in name_set:
+            _error(
+                issues,
+                selected_rootfile.full_path,
+                f"history part missing from archive: {path!r}",
+            )
+
+
+def _check_version_part(
+    relationships: ManifestRelationships,
+    name_set: set[str],
+    selected_rootfile: RootFileRef,
+    issues: list[PackageValidationIssue],
+) -> None:
+    if relationships.version_path is None and VERSION_PATH in name_set:
+        _warning(
+            issues,
+            selected_rootfile.full_path,
+            "manifest does not reference a version part; engine will fall back to "
+            f"{VERSION_PATH!r}",
+        )
+    elif (
+        relationships.version_path is not None
+        and relationships.version_path not in name_set
+    ):
+        _error(
+            issues,
+            selected_rootfile.full_path,
+            f"manifest version part missing from archive: {relationships.version_path!r}",
+        )
+
+
 def validate_package(source: str | Path | bytes | BinaryIO) -> PackageValidationReport:
     checked_parts: list[str] = []
     issues: list[PackageValidationIssue] = []
@@ -593,77 +901,11 @@ def validate_package(source: str | Path | bytes | BinaryIO) -> PackageValidation
         if bad_entry is not None:
             _error(issues, bad_entry, "ZIP CRC/integrity check failed")
 
-        if MIMETYPE_PATH not in name_set:
-            _error(issues, MIMETYPE_PATH, "missing required file")
-        else:
-            mimetype_bytes = _safe_read(zf, MIMETYPE_PATH)
-            if mimetype_bytes is None:
-                _error(
-                    issues,
-                    MIMETYPE_PATH,
-                    "unable to read entry for integrity validation",
-                )
-            else:
-                try:
-                    mimetype = mimetype_bytes.decode("utf-8").strip()
-                except UnicodeDecodeError:
-                    mimetype = "<binary>"
-                if mimetype != EXPECTED_MIMETYPE:
-                    _error(
-                        issues,
-                        MIMETYPE_PATH,
-                        f"expected {EXPECTED_MIMETYPE!r}, got {mimetype!r}",
-                    )
-                if infos[0].filename != MIMETYPE_PATH:
-                    _error(issues, MIMETYPE_PATH, "must be the first ZIP entry")
-                if zf.getinfo(MIMETYPE_PATH).compress_type != ZIP_STORED:
-                    _error(issues, MIMETYPE_PATH, "must use ZIP_STORED")
-
-        if CONTAINER_PATH not in name_set:
-            _error(issues, CONTAINER_PATH, "missing required file")
-        if VERSION_PATH not in name_set:
-            _warning(
-                issues,
-                VERSION_PATH,
-                "missing optional version.xml; minimum editor-open package set allows omission",
-            )
+        _check_mimetype(zf, infos, name_set, issues)
+        _check_required_presence(name_set, issues)
+        _check_preview_text(zf, name_set, issues)
 
-        if PREVIEW_TEXT_PATH not in name_set:
-            _warning(
-                issues,
-                PREVIEW_TEXT_PATH,
-                "missing Preview/PrvText.txt; macOS Hancom compatibility may require it",
-            )
-        else:
-            preview_bytes = _safe_read(zf, PREVIEW_TEXT_PATH)
-            if preview_bytes is None:
-                _error(issues, PREVIEW_TEXT_PATH, "unable to read preview text entry")
-            elif len(preview_bytes) > 1024 * 1024:
-                _warning(
-                    issues,
-                    PREVIEW_TEXT_PATH,
-                    "Preview/PrvText.txt is unusually large; expected a compact text snapshot",
-                )
-
-        xml_roots: dict[str, ET.Element] = {}
-        for name in names:
-            if not (name.endswith(".xml") or name.endswith(".hpf")):
-                continue
-            payload = _safe_read(zf, name)
-            if payload is None:
-                _error(issues, name, "unable to read entry for XML parsing")
-                continue
-            try:
-                root = _parse_xml(payload)
-                xml_roots[name] = root
-                _check_hwpml_compat_root(issues, name, payload, root)
-                _check_line_seg_text_positions(issues, name, root)
-                _check_table_editor_acceptance(issues, name, root)
-                _check_section_properties_location(issues, name, root)
-                _check_header_editor_acceptance(issues, name, root)
-                _check_bold_fontref_axis(issues, name, root)
-            except ValueError as exc:
-                _error(issues, name, str(exc))
+        xml_roots = _parse_all_xml(zf, names, issues)
 
         container_root = xml_roots.get(CONTAINER_PATH)
         if container_root is None:
@@ -674,13 +916,7 @@ def validate_package(source: str | Path | bytes | BinaryIO) -> PackageValidation
             _error(issues, CONTAINER_PATH, "declares no rootfile entries")
             return PackageValidationReport(tuple(checked_parts), tuple(issues))
 
-        for rootfile in rootfiles:
-            if rootfile.full_path not in name_set:
-                _error(
-                    issues,
-                    CONTAINER_PATH,
-                    f"rootfile points to missing part {rootfile.full_path!r}",
-                )
+        _check_rootfile_parts(rootfiles, name_set, issues)
 
         selected_rootfile, used_rootfile_fallback = select_main_rootfile(rootfiles)
         if selected_rootfile is None:
@@ -709,154 +945,17 @@ def validate_package(source: str | Path | bytes | BinaryIO) -> PackageValidation
             known_parts=name_set,
         )
 
-        for item in relationships.items:
-            if item.resolved_path not in name_set:
-                _error(
-                    issues,
-                    selected_rootfile.full_path,
-                    f"manifest href missing from archive: {item.href!r} -> {item.resolved_path!r}",
-                )
-
-        for idref in relationships.dangling_idrefs:
-            _warning(
-                issues,
-                selected_rootfile.full_path,
-                f"spine itemref references missing manifest id {idref!r}",
-            )
-
-        section_paths = [
-            path for path in relationships.spine_paths if is_section_part_name(path)
-        ]
-        resolved_section_paths: list[str]
-        if section_paths:
-            resolved_section_paths = list(dict.fromkeys(section_paths))
-            for path in section_paths:
-                if path not in name_set:
-                    _error(
-                        issues,
-                        selected_rootfile.full_path,
-                        f"spine section part missing from archive: {path!r}",
-                    )
-        else:
-            fallback_sections = [
-                name for name in sorted(name_set) if is_section_part_name(name)
-            ]
-            if fallback_sections:
-                resolved_section_paths = fallback_sections
-                _warning(
-                    issues,
-                    selected_rootfile.full_path,
-                    "manifest spine does not resolve any section parts; engine will fall back "
-                    "to filename-based section discovery",
-                )
-            else:
-                resolved_section_paths = []
-                _error(
-                    issues,
-                    selected_rootfile.full_path,
-                    "no section parts found in manifest spine or archive fallback",
-                )
-
-        resolved_header_paths = list(dict.fromkeys(relationships.header_paths))
-        if not resolved_header_paths and HEADER_PATH in name_set:
-            resolved_header_paths = [HEADER_PATH]
-        for header_path in resolved_header_paths:
-            header_root = xml_roots.get(header_path)
-            if header_root is None or _local_name(header_root) != "head":
-                continue
-            declared_section_count = header_root.get("secCnt")
-            if declared_section_count is None:
-                _warning(
-                    issues,
-                    header_path,
-                    "hh:head secCnt is missing; resolved section count cannot be cross-checked",
-                )
-                continue
-            try:
-                parsed_section_count = int(declared_section_count)
-            except ValueError:
-                _error(
-                    issues,
-                    header_path,
-                    f"hh:head secCnt must be an integer, got {declared_section_count!r}",
-                )
-                continue
-            if parsed_section_count != len(resolved_section_paths):
-                _error(
-                    issues,
-                    header_path,
-                    "hh:head secCnt does not match resolved section count: "
-                    f"declared={parsed_section_count}, resolved={len(resolved_section_paths)}",
-                )
-
-        if not relationships.header_paths and HEADER_PATH in name_set:
-            _warning(
-                issues,
-                selected_rootfile.full_path,
-                "manifest spine does not resolve a header part; engine will fall back to "
-                f"{HEADER_PATH!r}",
-            )
-
-        for path in relationships.header_paths:
-            if path not in name_set:
-                _error(
-                    issues,
-                    selected_rootfile.full_path,
-                    f"header part missing from archive: {path!r}",
-                )
-
-        if not relationships.master_page_paths:
-            fallback_master_pages = _fallback_named_parts(
-                name_set, token="master", extra_token="page"
-            )
-            if fallback_master_pages:
-                _warning(
-                    issues,
-                    selected_rootfile.full_path,
-                    "manifest does not reference masterPage parts; engine will fall back to "
-                    "filename-based discovery",
-                )
-        for path in relationships.master_page_paths:
-            if path not in name_set:
-                _error(
-                    issues,
-                    selected_rootfile.full_path,
-                    f"masterPage part missing from archive: {path!r}",
-                )
-
-        if not relationships.history_paths:
-            fallback_histories = _fallback_named_parts(name_set, token="history")
-            if fallback_histories:
-                _warning(
-                    issues,
-                    selected_rootfile.full_path,
-                    "manifest does not reference history parts; engine will fall back to "
-                    "filename-based discovery",
-                )
-        for path in relationships.history_paths:
-            if path not in name_set:
-                _error(
-                    issues,
-                    selected_rootfile.full_path,
-                    f"history part missing from archive: {path!r}",
-                )
-
-        if relationships.version_path is None and VERSION_PATH in name_set:
-            _warning(
-                issues,
-                selected_rootfile.full_path,
-                "manifest does not reference a version part; engine will fall back to "
-                f"{VERSION_PATH!r}",
-            )
-        elif (
-            relationships.version_path is not None
-            and relationships.version_path not in name_set
-        ):
-            _error(
-                issues,
-                selected_rootfile.full_path,
-                f"manifest version part missing from archive: {relationships.version_path!r}",
-            )
+        _check_manifest_hrefs(relationships, selected_rootfile, name_set, issues)
+        resolved_section_paths = _resolve_section_paths(
+            relationships, selected_rootfile, name_set, issues
+        )
+        _check_header_section_counts(
+            relationships, xml_roots, resolved_section_paths, name_set, issues
+        )
+        _check_header_fallback(relationships, name_set, selected_rootfile, issues)
+        _check_master_page_parts(relationships, name_set, selected_rootfile, issues)
+        _check_history_parts(relationships, name_set, selected_rootfile, issues)
+        _check_version_part(relationships, name_set, selected_rootfile, issues)
 
     return PackageValidationReport(tuple(checked_parts), tuple(issues))
 

{python_hwpx-3.3.0.dist-info → python_hwpx-3.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 3.3.0
+Version: 3.3.1
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -70,7 +70,7 @@ Dynamic: license-file
 `hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
 “first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
 
-현재 PyPI 공개 릴리스는 `python-hwpx 3.3.0`입니다. 일반
+현재 PyPI 공개 릴리스는 `python-hwpx 3.3.1`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.

{python_hwpx-3.3.0.dist-info → python_hwpx-3.3.1.dist-info}/RECORD

@@ -28,7 +28,7 @@ hwpx/agent/blueprint/bundle.py,sha256=K9-lcCgx2j1EsHzdP0cFn3ejn-YcLQ1NnNiPZNjq25
 hwpx/agent/blueprint/catalog.py,sha256=D2ax7gQxhoqqtL70LWjcUME6I9TMb2Q7MqR48c19_tc,4669
 hwpx/agent/blueprint/dump.py,sha256=HgEMr5dI5ozXwZn9tH-2IlFtWphxT_qz7hlZmSn49MU,21745
 hwpx/agent/blueprint/mapping.py,sha256=bzSYbTrNEumBkP74nEY5M20-BEC4rBGCRvo3QZNQKxc,12761
-hwpx/agent/blueprint/model.py,sha256=U1CykldrtKWRXntb6cJxJjs-mGOVFN4jroBbcaQNoTk,28096
+hwpx/agent/blueprint/model.py,sha256=7CegZTyVxFtzeDXHQrAogwS5Hf-MEBSEzcarUl1gNbE,31204
 hwpx/agent/blueprint/native.py,sha256=O6ZyBmKMw-O-SoEzlWkIgA4E7zXog1Ba9-4Ug5AekpM,28761
 hwpx/agent/blueprint/replay.py,sha256=EzkjGsFCYkjADZVaX1V8g4LAlZIXOFn7cZJmmCNNpSY,20047
 hwpx/benchmark/__init__.py,sha256=7CfgxEQ6nUrKHy3-V9VkeaMoGrb12QA8mHzpcfF2ItE,623
@@ -147,7 +147,7 @@ hwpx/tools/markdown_export.py,sha256=FejutCpQHbycO185uljcSwfZuwXMTbGEgXtf5e-a4_k
 hwpx/tools/object_finder.py,sha256=7i6XI1-r7-ar_IzSZQ82hfOcxVzJFK2XjMDB8oxcmMA,13478
 hwpx/tools/official_lint.py,sha256=9iszI4CAAEMGdPCOhmQ6XonO1jc1XE2BJXMHgv9hIvY,18600
 hwpx/tools/package_reconcile.py,sha256=y1Hl7hbPh4YaV59LTdDLzQwgn4g1qEnFmSjmajnrEbA,2416
-hwpx/tools/package_validator.py,sha256=mkWFS7xgkizVQR7kQRXfwBF_i3zQk7qt8jmBTgTYZm4,31326
+hwpx/tools/package_validator.py,sha256=fYkJevV_soQuM8LEUQMkwYaTy2k2HV4VWBwfIXFt29Y,33306
 hwpx/tools/page_guard.py,sha256=nDAVPcvrnuyDxVTA_j22wiYD7CXAD6XlzsMzaz3h_q8,9701
 hwpx/tools/pii.py,sha256=N3c36eqblaVQ7o6jiT1BV0WrJK_G3gKhQh6MQGAbvCs,12617
 hwpx/tools/read_fidelity.py,sha256=g4r2GNVExEtL0C-6JMkPIjmH6CtJqNSS_-KsSPTnBbw,10541
@@ -190,10 +190,10 @@ hwpx/visual/page_qa.py,sha256=AuJCySfLIdXjPeekhAc3YnrIWOsN0sI35Pnz8BZ6Pro,7278
 hwpx/visual/qa_contracts.py,sha256=1cjoiRTAWgi7NgE8SPc6bKxdoUfKx9nyou1mgC47TxY,10506
 hwpx/visual/qa_metrics.py,sha256=I7RdybN-f1Fvcv2j-ceDPoek51nOkMui1Zrd7TEX_C8,9838
 hwpx/visual/report.py,sha256=2RhXN1KBYOZTim9FNpeUhaaDHR7oFxI6Z2DLUkDIiwE,1717
-python_hwpx-3.3.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
-python_hwpx-3.3.0.dist-info/licenses/NOTICE,sha256=k48h6EaGQE8Y1c0dS9sIOOcz4YqkbcImWClF7pBOgsg,2473
-python_hwpx-3.3.0.dist-info/METADATA,sha256=Sst0elBTS2Ns4JL3oOUS9uC9lvH-A2rAkIoGLMqouOE,12566
-python_hwpx-3.3.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_hwpx-3.3.0.dist-info/entry_points.txt,sha256=PVUBTBQtBHiflQ9XBjfd004w-LrDibgZjwzxgu8Tx7w,480
-python_hwpx-3.3.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-3.3.0.dist-info/RECORD,,
+python_hwpx-3.3.1.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
+python_hwpx-3.3.1.dist-info/licenses/NOTICE,sha256=k48h6EaGQE8Y1c0dS9sIOOcz4YqkbcImWClF7pBOgsg,2473
+python_hwpx-3.3.1.dist-info/METADATA,sha256=inWS_guBKXWildz4JpZwh2xIpqw-Zm-2PKjiShL3h78,12566
+python_hwpx-3.3.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_hwpx-3.3.1.dist-info/entry_points.txt,sha256=PVUBTBQtBHiflQ9XBjfd004w-LrDibgZjwzxgu8Tx7w,480
+python_hwpx-3.3.1.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
+python_hwpx-3.3.1.dist-info/RECORD,,