python-hwpx 2.6__tar.gz → 2.7.1__tar.gz

{python_hwpx-2.6 → python_hwpx-2.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 2.6
+Version: 2.7.1
 Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
 Author: python-hwpx Maintainers
 License: Non-Commercial License
@@ -165,7 +165,8 @@ doc.save_to_path("결과물.hwpx")
 | 🔎 **객체 검색** | 태그/속성/XPath | 특정 요소 탐색, 주석 이터레이터 |
 | 🎨 **스타일 치환** | 서식 기반 필터 | 색상/밑줄/charPrIDRef 기반 Run 검색 및 교체 |
 | 📤 **내보내기** | 텍스트/HTML/Markdown | 문서 변환 출력 |
-| ✅ **유효성 검사** | XSD 스키마 | CLI(`hwpx-validate`) 및 API |
+| ✅ **유효성 검사** | XSD + 패키지 구조 | CLI(`hwpx-validate`, `hwpx-validate-package`) 및 API |
+| 🧰 **워크플로 도구** | unpack/pack/template analyze/page guard | 템플릿 보존형 XML-first 작업 보조 |
 | 🏗️ **저수준 XML** | 데이터클래스 매핑 | OWPML 스키마 ↔ Python 객체 직접 조작 |
 | 🔄 **네임스페이스 호환** | 자동 정규화 | HWPML 2016 → 2011 자동 변환 |
 
@@ -262,10 +263,15 @@ python-hwpx
 │   ├── body.py          #   타입이 지정된 본문 모델
 │   └── common.py        #   범용 XML ↔ 데이터클래스
 ├── hwpx.tools
+│   ├── archive_cli      #   unpack/pack CLI 및 재패킹 메타데이터
 │   ├── text_extractor   #   텍스트 추출 파이프라인
+│   ├── text_extract_cli #   텍스트 추출 CLI
 │   ├── object_finder    #   객체 탐색 유틸리티
 │   ├── exporter         #   텍스트/HTML/Markdown 내보내기
-│   └── validator        #   스키마 유효성 검사 (hwpx-validate CLI)
+│   ├── validator        #   스키마 유효성 검사 (hwpx-validate CLI)
+│   ├── package_validator#   ZIP/OPC/HWPX 구조 검사
+│   ├── page_guard       #   layout-drift proxy
+│   └── template_analyzer#   레퍼런스 문서 분석/추출
 └── hwpx.templates       # 내장 빈 문서 템플릿
 ```
 
@@ -274,8 +280,26 @@ python-hwpx
 ```bash
 # HWPX 문서 스키마 유효성 검사
 hwpx-validate 문서.hwpx
+
+# ZIP/OPC/HWPX 패키지 구조 검사
+hwpx-validate-package 문서.hwpx
+
+# HWPX 풀기 / 다시 묶기
+hwpx-unpack 문서.hwpx ./unpacked
+hwpx-pack ./unpacked ./repacked.hwpx
+
+# 레퍼런스 템플릿 분석과 파트 추출
+hwpx-analyze-template 문서.hwpx --extract-dir ./template-parts --json
+
+# plain / markdown 텍스트 추출
+hwpx-text-extract 문서.hwpx --format markdown --output 문서.md
+
+# 레이아웃 드리프트 프록시 비교
+hwpx-page-guard --reference 원본.hwpx --output 결과.hwpx
 ```
 
+`hwpx-page-guard`는 렌더된 실제 쪽수를 계산하지 않습니다. 대신 단락 수, 표 수, shape/control 수, 명시적 page/column break, 텍스트 길이 통계를 비교해 레이아웃 드리프트 위험을 탐지하는 프록시 도구입니다.
+
 ## 문서
 
 | | |

{python_hwpx-2.6 → python_hwpx-2.7.1}/README.md

@@ -98,7 +98,8 @@ doc.save_to_path("결과물.hwpx")
 | 🔎 **객체 검색** | 태그/속성/XPath | 특정 요소 탐색, 주석 이터레이터 |
 | 🎨 **스타일 치환** | 서식 기반 필터 | 색상/밑줄/charPrIDRef 기반 Run 검색 및 교체 |
 | 📤 **내보내기** | 텍스트/HTML/Markdown | 문서 변환 출력 |
-| ✅ **유효성 검사** | XSD 스키마 | CLI(`hwpx-validate`) 및 API |
+| ✅ **유효성 검사** | XSD + 패키지 구조 | CLI(`hwpx-validate`, `hwpx-validate-package`) 및 API |
+| 🧰 **워크플로 도구** | unpack/pack/template analyze/page guard | 템플릿 보존형 XML-first 작업 보조 |
 | 🏗️ **저수준 XML** | 데이터클래스 매핑 | OWPML 스키마 ↔ Python 객체 직접 조작 |
 | 🔄 **네임스페이스 호환** | 자동 정규화 | HWPML 2016 → 2011 자동 변환 |
 
@@ -195,10 +196,15 @@ python-hwpx
 │   ├── body.py          #   타입이 지정된 본문 모델
 │   └── common.py        #   범용 XML ↔ 데이터클래스
 ├── hwpx.tools
+│   ├── archive_cli      #   unpack/pack CLI 및 재패킹 메타데이터
 │   ├── text_extractor   #   텍스트 추출 파이프라인
+│   ├── text_extract_cli #   텍스트 추출 CLI
 │   ├── object_finder    #   객체 탐색 유틸리티
 │   ├── exporter         #   텍스트/HTML/Markdown 내보내기
-│   └── validator        #   스키마 유효성 검사 (hwpx-validate CLI)
+│   ├── validator        #   스키마 유효성 검사 (hwpx-validate CLI)
+│   ├── package_validator#   ZIP/OPC/HWPX 구조 검사
+│   ├── page_guard       #   layout-drift proxy
+│   └── template_analyzer#   레퍼런스 문서 분석/추출
 └── hwpx.templates       # 내장 빈 문서 템플릿
 ```
 
@@ -207,8 +213,26 @@ python-hwpx
 ```bash
 # HWPX 문서 스키마 유효성 검사
 hwpx-validate 문서.hwpx
+
+# ZIP/OPC/HWPX 패키지 구조 검사
+hwpx-validate-package 문서.hwpx
+
+# HWPX 풀기 / 다시 묶기
+hwpx-unpack 문서.hwpx ./unpacked
+hwpx-pack ./unpacked ./repacked.hwpx
+
+# 레퍼런스 템플릿 분석과 파트 추출
+hwpx-analyze-template 문서.hwpx --extract-dir ./template-parts --json
+
+# plain / markdown 텍스트 추출
+hwpx-text-extract 문서.hwpx --format markdown --output 문서.md
+
+# 레이아웃 드리프트 프록시 비교
+hwpx-page-guard --reference 원본.hwpx --output 결과.hwpx
 ```
 
+`hwpx-page-guard`는 렌더된 실제 쪽수를 계산하지 않습니다. 대신 단락 수, 표 수, shape/control 수, 명시적 page/column break, 텍스트 길이 통계를 비교해 레이아웃 드리프트 위험을 탐지하는 프록시 도구입니다.
+
 ## 문서
 
 | | |

{python_hwpx-2.6 → python_hwpx-2.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "2.6"
+version = "2.7.1"
 description = "Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }
@@ -49,9 +49,12 @@ Documentation = "https://github.com/airmang/python-hwpx/tree/main/docs"
 Issues = "https://github.com/airmang/python-hwpx/issues"
 
 [project.scripts]
+hwpx-unpack = "hwpx.tools.archive_cli:unpack_main"
+hwpx-pack = "hwpx.tools.archive_cli:pack_main"
 hwpx-validate = "hwpx.tools.validator:main"
 hwpx-validate-package = "hwpx.tools.package_validator:main"
 hwpx-page-guard = "hwpx.tools.page_guard:main"
+hwpx-analyze-template = "hwpx.tools.template_analyzer:main"
 hwpx-text-extract = "hwpx.tools.text_extract_cli:main"
 
 [tool.setuptools]

python_hwpx-2.7.1/src/hwpx/tools/archive_cli.py

@@ -0,0 +1,337 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Sequence
+from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
+
+from lxml import etree
+
+from .package_validator import validate_package
+
+_XML_SUFFIXES = (".xml", ".hpf")
+_PACK_METADATA_NAME = ".hwpx-pack-metadata.json"
+
+__all__ = [
+    "ArchiveEntryInfo",
+    "UnpackResult",
+    "PackResult",
+    "pack_hwpx",
+    "unpack_hwpx",
+    "pack_main",
+    "unpack_main",
+    "main",
+]
+
+
+@dataclass(frozen=True)
+class ArchiveEntryInfo:
+    path: str
+    compress_type: int
+
+
+@dataclass(frozen=True)
+class UnpackResult:
+    output_dir: Path
+    metadata_path: Path
+    entries: tuple[ArchiveEntryInfo, ...]
+
+
+@dataclass(frozen=True)
+class PackResult:
+    output_path: Path
+    entries: tuple[str, ...]
+
+
+def _guard_destructive_target(path: Path) -> None:
+    resolved = path.resolve()
+    if resolved == Path(resolved.anchor):
+        raise ValueError(f"refusing to overwrite filesystem root: {resolved}")
+    if resolved == Path.cwd().resolve():
+        raise ValueError(f"refusing to overwrite current working directory: {resolved}")
+
+
+def _prepare_output_dir(output_dir: Path, *, overwrite: bool) -> None:
+    if output_dir.exists() and not output_dir.is_dir():
+        raise NotADirectoryError(f"output exists and is not a directory: {output_dir}")
+    if output_dir.exists():
+        if any(output_dir.iterdir()):
+            if not overwrite:
+                raise FileExistsError(f"output directory is not empty: {output_dir}")
+            _guard_destructive_target(output_dir)
+            shutil.rmtree(output_dir)
+        else:
+            output_dir.rmdir()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+
+def _prepare_output_path(output_path: Path, *, overwrite: bool) -> None:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    if output_path.exists() and not overwrite:
+        raise FileExistsError(f"output file already exists: {output_path}")
+
+
+def _format_xml_bytes(payload: bytes) -> bytes:
+    try:
+        element = etree.fromstring(payload)
+    except etree.XMLSyntaxError:
+        return payload
+    etree.indent(element, space="  ")
+    return etree.tostring(
+        element,
+        pretty_print=True,
+        xml_declaration=True,
+        encoding="UTF-8",
+    )
+
+
+def _iter_file_entries(archive: ZipFile) -> tuple[ArchiveEntryInfo, ...]:
+    entries: list[ArchiveEntryInfo] = []
+    for info in archive.infolist():
+        if info.is_dir():
+            continue
+        entries.append(ArchiveEntryInfo(path=info.filename, compress_type=info.compress_type))
+    return tuple(entries)
+
+
+def _metadata_path(root: Path) -> Path:
+    return root / _PACK_METADATA_NAME
+
+
+def _write_pack_metadata(root: Path, entries: tuple[ArchiveEntryInfo, ...]) -> Path:
+    destination = _metadata_path(root)
+    payload = {
+        "format_version": 1,
+        "entries": [asdict(entry) for entry in entries],
+    }
+    destination.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    return destination
+
+
+def _read_pack_metadata(root: Path) -> tuple[ArchiveEntryInfo, ...]:
+    metadata_file = _metadata_path(root)
+    if not metadata_file.is_file():
+        return ()
+
+    data = json.loads(metadata_file.read_text(encoding="utf-8"))
+    entries: list[ArchiveEntryInfo] = []
+    for entry in data.get("entries", []):
+        path = str(entry.get("path", "")).strip()
+        if not path:
+            continue
+        entries.append(
+            ArchiveEntryInfo(
+                path=path.replace("\\", "/"),
+                compress_type=int(entry.get("compress_type", ZIP_DEFLATED)),
+            )
+        )
+    return tuple(entries)
+
+
+def _discover_files(root: Path) -> set[str]:
+    paths: set[str] = set()
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        rel_path = path.relative_to(root).as_posix()
+        if rel_path == _PACK_METADATA_NAME:
+            continue
+        paths.add(rel_path)
+    return paths
+
+
+def _resolve_write_order(paths: set[str], metadata: tuple[ArchiveEntryInfo, ...]) -> tuple[str, ...]:
+    ordered: list[str] = []
+    seen: set[str] = set()
+
+    if "mimetype" in paths:
+        ordered.append("mimetype")
+        seen.add("mimetype")
+
+    for entry in metadata:
+        if entry.path in paths and entry.path not in seen:
+            ordered.append(entry.path)
+            seen.add(entry.path)
+
+    for path in sorted(paths):
+        if path in seen:
+            continue
+        ordered.append(path)
+        seen.add(path)
+
+    return tuple(ordered)
+
+
+def _summarize_pack_validation(output_path: Path) -> None:
+    report = validate_package(output_path)
+    if report.ok:
+        return
+    summary = "\n".join(f"- {issue}" for issue in report.issues[:10])
+    raise ValueError(f"packed archive failed validation:\n{summary}")
+
+
+def unpack_hwpx(
+    source: str | Path,
+    output_dir: str | Path,
+    *,
+    overwrite: bool = False,
+    pretty_xml: bool = True,
+) -> UnpackResult:
+    source_path = Path(source)
+    if not source_path.is_file():
+        raise FileNotFoundError(f"input file not found: {source_path}")
+
+    destination = Path(output_dir)
+    _prepare_output_dir(destination, overwrite=overwrite)
+
+    with ZipFile(source_path, "r") as archive:
+        entries = _iter_file_entries(archive)
+        for entry in entries:
+            data = archive.read(entry.path)
+            if pretty_xml and entry.path.endswith(_XML_SUFFIXES):
+                data = _format_xml_bytes(data)
+            target = destination / entry.path
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(data)
+
+    metadata_path = _write_pack_metadata(destination, entries)
+    return UnpackResult(output_dir=destination, metadata_path=metadata_path, entries=entries)
+
+
+def pack_hwpx(
+    input_dir: str | Path,
+    output_path: str | Path,
+    *,
+    overwrite: bool = False,
+) -> PackResult:
+    root = Path(input_dir)
+    if not root.is_dir():
+        raise FileNotFoundError(f"input directory not found: {root}")
+
+    destination = Path(output_path)
+    _prepare_output_path(destination, overwrite=overwrite)
+
+    files = _discover_files(root)
+    if "mimetype" not in files:
+        raise FileNotFoundError(f"missing required 'mimetype' file in {root}")
+
+    metadata = _read_pack_metadata(root)
+    compress_types = {entry.path: entry.compress_type for entry in metadata}
+    ordered_paths = _resolve_write_order(files, metadata)
+
+    fd, tmp_name = tempfile.mkstemp(dir=str(destination.parent), suffix=".hwpx.tmp")
+    os.close(fd)
+    tmp_path = Path(tmp_name)
+    try:
+        with ZipFile(tmp_path, "w", ZIP_DEFLATED) as archive:
+            archive.write(root / "mimetype", "mimetype", compress_type=ZIP_STORED)
+            for rel_path in ordered_paths:
+                if rel_path == "mimetype":
+                    continue
+                compress_type = compress_types.get(rel_path, ZIP_DEFLATED)
+                if compress_type != ZIP_STORED:
+                    compress_type = ZIP_DEFLATED
+                archive.write(root / rel_path, rel_path, compress_type=compress_type)
+
+        _summarize_pack_validation(tmp_path)
+        os.replace(tmp_path, destination)
+    except BaseException:
+        try:
+            tmp_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise
+
+    return PackResult(output_path=destination, entries=ordered_paths)
+
+
+def unpack_main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Unpack an HWPX file into a directory")
+    parser.add_argument("input", help="Input .hwpx path")
+    parser.add_argument("output", help="Output directory")
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Allow deleting an existing non-empty output directory",
+    )
+    parser.add_argument(
+        "--no-pretty-xml",
+        action="store_true",
+        help="Keep XML payloads in their original byte formatting",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        result = unpack_hwpx(
+            args.input,
+            args.output,
+            overwrite=args.force,
+            pretty_xml=not args.no_pretty_xml,
+        )
+    except Exception as exc:
+        print(f"ERROR: {exc}")
+        return 1
+
+    print(f"Unpacked {args.input} -> {result.output_dir}")
+    print(f"Recorded archive metadata at {result.metadata_path}")
+    return 0
+
+
+def pack_main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Pack a directory into an HWPX archive")
+    parser.add_argument("input", help="Input directory")
+    parser.add_argument("output", help="Output .hwpx path")
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Allow replacing an existing output file",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        result = pack_hwpx(args.input, args.output, overwrite=args.force)
+    except Exception as exc:
+        print(f"ERROR: {exc}")
+        return 1
+
+    print(f"Packed {args.input} -> {result.output_path}")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="HWPX archive utility helpers")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    unpack_parser = subparsers.add_parser("unpack", help="Unpack an HWPX file")
+    unpack_parser.add_argument("input")
+    unpack_parser.add_argument("output")
+    unpack_parser.add_argument("--force", action="store_true")
+    unpack_parser.add_argument("--no-pretty-xml", action="store_true")
+
+    pack_parser = subparsers.add_parser("pack", help="Pack a directory into HWPX")
+    pack_parser.add_argument("input")
+    pack_parser.add_argument("output")
+    pack_parser.add_argument("--force", action="store_true")
+
+    args = parser.parse_args(argv)
+    if args.command == "unpack":
+        forward = [args.input, args.output]
+        if args.force:
+            forward.append("--force")
+        if args.no_pretty_xml:
+            forward.append("--no-pretty-xml")
+        return unpack_main(forward)
+
+    forward = [args.input, args.output]
+    if args.force:
+        forward.append("--force")
+    return pack_main(forward)
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI convenience
+    raise SystemExit(main())

{python_hwpx-2.6 → python_hwpx-2.7.1}/src/hwpx/tools/package_validator.py

@@ -68,13 +68,15 @@ def _parse_xml(payload: bytes) -> ET.Element:
 def _container_rootfiles(container_root: ET.Element) -> list[str]:
     paths: list[str] = []
     for namespace in CONTAINER_NS.values():
-        paths.extend(
-            elem.get("full-path")
-            or elem.get("fullPath")
-            or elem.get("full_path")
-            for elem in container_root.findall(f".//{{{namespace}}}rootfile")
-        )
-    return [path for path in paths if path]
+        for elem in container_root.findall(f".//{{{namespace}}}rootfile"):
+            path = (
+                elem.get("full-path")
+                or elem.get("fullPath")
+                or elem.get("full_path")
+            )
+            if path:
+                paths.append(path)
+    return paths
 
 
 def _manifest_hrefs(manifest_root: ET.Element) -> set[str]:

{python_hwpx-2.6 → python_hwpx-2.7.1}/src/hwpx/tools/page_guard.py

@@ -1,3 +1,9 @@
+"""Proxy checks for layout drift between a reference and an output HWPX.
+
+This module does not calculate rendered page counts. It compares structural and
+textual metrics that often correlate with page-layout drift.
+"""
+
 from __future__ import annotations
 
 import argparse
@@ -16,6 +22,22 @@ NS = {
     "opf": "http://www.idpf.org/2007/opf/",
 }
 
+_SHAPE_TAGS = {
+    "line",
+    "rect",
+    "ellipse",
+    "arc",
+    "polygon",
+    "curve",
+    "connectLine",
+    "textart",
+    "pic",
+    "compose",
+    "equation",
+    "ole",
+    "container",
+}
+
 __all__ = [
     "DocumentMetrics",
     "collect_metrics",
@@ -31,7 +53,11 @@ class DocumentMetrics:
     page_break_count: int
     column_break_count: int
     table_count: int
+    shape_count: int
+    control_count: int
     table_shapes: list[tuple[str, str, str, str, str, str]]
+    shape_types: list[tuple[str, int]]
+    control_types: list[tuple[str, int]]
     text_char_total: int
     text_char_total_nospace: int
     paragraph_text_lengths: list[int]
@@ -66,6 +92,12 @@ def _text_of_t_node(node: etree._Element) -> str:
     return "".join(node.itertext())
 
 
+def _local_name(tag: str) -> str:
+    if "}" in tag:
+        return tag.split("}", 1)[1]
+    return tag
+
+
 def _iter_section_roots(source: str | Path | bytes | BinaryIO) -> Iterable[etree._Element]:
     if isinstance(source, bytes):
         archive = ZipFile(io.BytesIO(source), "r")
@@ -85,6 +117,8 @@ def collect_metrics(source: str | Path | bytes | BinaryIO) -> DocumentMetrics:
     paragraphs: list[etree._Element] = []
     tables: list[etree._Element] = []
     table_shapes: list[tuple[str, str, str, str, str, str]] = []
+    shape_types: dict[str, int] = {}
+    control_types: dict[str, int] = {}
     paragraph_text_lengths: list[int] = []
     text_char_total = 0
     text_char_total_nospace = 0
@@ -100,6 +134,19 @@ def collect_metrics(source: str | Path | bytes | BinaryIO) -> DocumentMetrics:
         section_tables = root.xpath(".//hp:tbl", namespaces=NS)
         tables.extend(section_tables)
 
+        for element in root.iter():
+            name = _local_name(element.tag)
+            if name in _SHAPE_TAGS:
+                shape_types[name] = shape_types.get(name, 0) + 1
+            if name == "ctrl":
+                control_counted = False
+                for child in element:
+                    child_name = _local_name(child.tag)
+                    control_types[child_name] = control_types.get(child_name, 0) + 1
+                    control_counted = True
+                if not control_counted:
+                    control_types["ctrl"] = control_types.get("ctrl", 0) + 1
+
         for table in section_tables:
             size = table.find("hp:sz", namespaces=NS)
             table_shapes.append(
@@ -132,7 +179,11 @@ def collect_metrics(source: str | Path | bytes | BinaryIO) -> DocumentMetrics:
         page_break_count=page_break_count,
         column_break_count=column_break_count,
         table_count=len(tables),
+        shape_count=sum(shape_types.values()),
+        control_count=sum(control_types.values()),
         table_shapes=table_shapes,
+        shape_types=sorted(shape_types.items()),
+        control_types=sorted(control_types.items()),
         text_char_total=text_char_total,
         text_char_total_nospace=text_char_total_nospace,
         paragraph_text_lengths=paragraph_text_lengths,
@@ -173,8 +224,18 @@ def compare_metrics(
         )
     if reference.table_count != output.table_count:
         errors.append(f"table count mismatch: ref={reference.table_count}, out={output.table_count}")
+    if reference.shape_count != output.shape_count:
+        errors.append(f"shape count mismatch: ref={reference.shape_count}, out={output.shape_count}")
+    if reference.control_count != output.control_count:
+        errors.append(
+            f"control count mismatch: ref={reference.control_count}, out={output.control_count}"
+        )
     if reference.table_shapes != output.table_shapes:
         errors.append("table shape mismatch (rowCnt/colCnt/width/height/repeatHeader/pageBreak)")
+    if reference.shape_types != output.shape_types:
+        errors.append("shape type histogram mismatch")
+    if reference.control_types != output.control_types:
+        errors.append("control type histogram mismatch")
 
     text_delta = _ratio_delta(reference.text_char_total_nospace, output.text_char_total_nospace)
     if text_delta > max_text_delta_ratio:
@@ -202,7 +263,9 @@ def compare_metrics(
 
 
 def main(argv: Sequence[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="Reference-vs-output HWPX page drift guard")
+    parser = argparse.ArgumentParser(
+        description="Reference-vs-output HWPX layout-drift proxy checker"
+    )
     parser.add_argument("--reference", "-r", required=True, help="Reference HWPX path")
     parser.add_argument("--output", "-o", required=True, help="Output HWPX path")
     parser.add_argument("--max-text-delta-ratio", type=float, default=0.15)