python-hwpx 2.15.0__py3-none-any.whl → 2.17.0__py3-none-any.whl

hwpx/authoring.py

@@ -874,6 +874,138 @@ def _validate_v2_block(raw_block: Any, *, path: str) -> list[PlanValidationIssue
     return issues
 
 
+# --- M3 (S-057) document-type -> design profile routing ------------------------
+# Maps a plan's document_type (Korean label or profile id) to a committed
+# hwpx.design profile. When it resolves, create_document_from_plan composes from
+# the harvested, Hancom-opens-clean profile skeleton instead of the from-scratch
+# builder. Unknown types keep the legacy from-scratch path (regression-safe).
+_DOCTYPE_TO_PROFILE = {
+    "공문": "official_notice",
+    "공문서": "official_notice",
+    "official_notice": "official_notice",
+    "보고서": "report",
+    "report": "report",
+    "government_report": "report",
+    "가정통신문": "home_notice",
+    "home_notice": "home_notice",
+}
+_DOCTYPE_METADATA_KEYS = (
+    "document_type",
+    "문서 유형",
+    "문서유형",
+    "문서 종류",
+    "문서종류",
+    "documentType",
+)
+# 결문 (closing block) fields in their canonical render order.
+_GYEOLMUN_FIELDS = (
+    ("issuer", "발신명의"),
+    ("productionNumber", "생산등록번호"),
+    ("enforcementDate", "시행일"),
+    ("disclosure", "공개구분"),
+)
+
+
+def _plan_document_type(plan: Any) -> str:
+    """Read the plan's document type from metadata (preferred) or top level."""
+
+    if not isinstance(plan, Mapping):
+        return ""
+    metadata = plan.get("metadata")
+    metadata = metadata if isinstance(metadata, Mapping) else {}
+    for key in _DOCTYPE_METADATA_KEYS:
+        value = metadata.get(key) or plan.get(key)
+        if value:
+            return str(value).strip()
+    return ""
+
+
+def _resolve_design_profile(plan: Any) -> str | None:
+    """Return a committed design profile id for the plan's document_type, or None."""
+
+    raw = _plan_document_type(plan)
+    if not raw:
+        return None
+    from hwpx import design as _design
+
+    profile_id = _DOCTYPE_TO_PROFILE.get(raw)
+    if profile_id and profile_id in _design.available_profiles():
+        return profile_id
+    return None
+
+
+def _bridge_to_design_plan(plan: Mapping[str, Any], profile_id: str):
+    """Lower a document_plan mapping onto a :class:`hwpx.design.plan.DocumentPlan`.
+
+    Heading level 1 -> ``heading`` role, level >= 2 -> ``subheading``; paragraphs
+    and bullet items -> ``body``; tables -> an ``info`` table block. 결문 메타
+    fields are appended as trailing ``body`` blocks in canonical order (P0 proved
+    these survive a Hancom render).
+    """
+
+    from hwpx.design.plan import Block as _Block, DocumentPlan as _DesignPlan
+
+    blocks: list = []
+    for raw in plan.get("blocks") or []:
+        if not isinstance(raw, Mapping):
+            continue
+        block_type = str(raw.get("type") or "paragraph")
+        if block_type == "heading":
+            level = int(raw.get("level") or 1)
+            role = "heading" if level <= 1 else "subheading"
+            blocks.append(_Block(type="paragraph", role=role, text=str(raw.get("text") or "")))
+        elif block_type == "paragraph":
+            blocks.append(_Block(type="paragraph", role="body", text=str(raw.get("text") or "")))
+        elif block_type == "bullets":
+            for item in raw.get("items") or []:
+                blocks.append(_Block(type="paragraph", role="body", text=str(item)))
+        elif block_type == "table":
+            raw_cols = list(raw.get("columns") or raw.get("header") or [])
+            if raw_cols and isinstance(raw_cols[0], Mapping):
+                # document_plan schema: columns=[{key,label}], rows=[{key: value}]
+                keys = [str(c.get("key") or c.get("label") or "") for c in raw_cols]
+                columns = [str(c.get("label") or c.get("key") or "") for c in raw_cols]
+                rows = []
+                for row in raw.get("rows") or []:
+                    if isinstance(row, Mapping):
+                        rows.append([str(row.get(k, "")) for k in keys])
+                    elif isinstance(row, (list, tuple)):
+                        rows.append([str(c) for c in row])
+            else:
+                columns = [str(c) for c in raw_cols]
+                rows = [[str(c) for c in row] for row in (raw.get("rows") or [])]
+            blocks.append(_Block(type="table", role="info", columns=columns, rows=rows))
+        # page_break / memo: no design role -> skipped
+    gyeolmun = plan.get("gyeolmun")
+    if isinstance(gyeolmun, Mapping):
+        for key, label in _GYEOLMUN_FIELDS:
+            value = gyeolmun.get(key)
+            if value:
+                blocks.append(_Block(type="paragraph", role="body", text=f"{label}  {value}"))
+    return _DesignPlan(profile=profile_id, title=str(plan.get("title") or ""), blocks=blocks)
+
+
+def _korean_proofing_status(plan: Any, normalized_plan: "DocumentPlan | None") -> str:
+    """Honest 맞춤법/공공언어 status (Constitution V/IX) — never asserts 'passed'.
+
+    No free offline Korean spell/spacing oracle exists, so the default is
+    ``unverified``. If the plan signals an LLM self-proof pass it is labelled
+    ``llm_proofed_not_oracle_verified`` — proofed, but NOT oracle-verified.
+    """
+
+    metadata: Mapping[str, Any] = {}
+    if isinstance(plan, Mapping) and isinstance(plan.get("metadata"), Mapping):
+        metadata = plan["metadata"]
+    elif normalized_plan is not None:
+        metadata = normalized_plan.metadata
+    signal = str(
+        metadata.get("korean_proofing") or metadata.get("korean_proofing_status") or ""
+    ).strip().lower()
+    if signal in {"llm", "llm_proofed", "llm-proofed", "llm_proofed_not_oracle_verified"}:
+        return "llm_proofed_not_oracle_verified"
+    return "unverified"
+
+
 def create_document_from_plan(
     plan: Mapping[str, Any] | DocumentPlan,
     *,
@@ -881,6 +1013,19 @@ def create_document_from_plan(
 ) -> HwpxDocument:
     """Create a formatted HWPX document from a declarative document plan."""
 
+    if isinstance(plan, Mapping):
+        profile_id = _resolve_design_profile(plan)
+        if profile_id is not None:
+            from hwpx import design as _design
+
+            design_plan = _bridge_to_design_plan(plan, profile_id)
+            data, result = _design.compose_bytes(design_plan, production=True)
+            if not result.ok:
+                raise ValueError(
+                    f"profile compose failed for {profile_id!r}: {result.errors}"
+                )
+            return HwpxDocument.open(data)
+
     normalized = normalize_document_plan(plan)
     if normalized.builder_document is not None:
         return normalized.builder_document.lower()
@@ -952,8 +1097,15 @@ def inspect_document_authoring_quality(
     *,
     plan: Mapping[str, Any] | DocumentPlan | None = None,
     quality_profile: str | Mapping[str, Any] | None = None,
+    verify_render: bool = False,
 ) -> dict[str, Any]:
-    """Return deterministic structural quality evidence for generated HWPX."""
+    """Return deterministic structural quality evidence for generated HWPX.
+
+    When *verify_render* is true AND a Mac Hancom oracle is reachable, the
+    document is rendered and ``render_checked``/``visual_complete`` become real
+    receipts. Otherwise ``render_checked`` is ``False`` and ``visual_complete``
+    is ``"unverified"`` — never a silent true (Constitution V).
+    """
 
     normalized_plan: DocumentPlan | None = None
     plan_validation: dict[str, Any] | None = None
@@ -981,6 +1133,32 @@ def inspect_document_authoring_quality(
         package_report = validate_package(path if path is not None else package_payload)
         document_report = document.validate()
         reopened = _can_reopen(path, package_payload)
+        render_checked = False
+        visual_complete: Any = "unverified"
+        if verify_render:
+            from hwpx.visual import oracle as _oracle
+
+            _mac = _oracle.MacHancomOracle()
+            if _mac.available():
+                import tempfile as _tf
+
+                with _tf.TemporaryDirectory() as _tmp:
+                    _hwpx = Path(_tmp) / "render_check.hwpx"
+                    _hwpx.write_bytes(package_payload)
+                    _pdf = Path(_tmp) / "render_check.pdf"
+                    _rendered = _mac.render_pdf(str(_hwpx), str(_pdf))
+                    if _rendered and Path(_rendered).exists():
+                        try:
+                            import fitz as _fitz
+
+                            _doc = _fitz.open(_rendered)
+                            _has_text = any(pg.get_text().strip() for pg in _doc)
+                            _doc.close()
+                            render_checked = bool(_has_text)
+                            visual_complete = render_checked
+                        except Exception:
+                            render_checked = False
+                            visual_complete = "unverified"
         non_empty_texts = [
             (paragraph.text or "").strip()
             for paragraph in document.paragraphs
@@ -1034,11 +1212,29 @@ def inspect_document_authoring_quality(
             and not profiles["operating_plan"].get("pass", False)
         ):
             gaps.append("operating plan quality failed")
+
+        document_type = ""
+        if isinstance(plan, Mapping):
+            document_type = _plan_document_type(plan)
+        elif normalized_plan is not None:
+            document_type = str(normalized_plan.metadata.get("document_type", "") or "")
+        gongmun_structure: dict[str, Any] | None = None
+        if _DOCTYPE_TO_PROFILE.get(document_type.strip()) == "official_notice":
+            from hwpx.tools.official_lint import (
+                inspect_official_document_style as _gongmun_lint,
+            )
+
+            gongmun_structure = _gongmun_lint(document, document_type="공문")
+            if not gongmun_structure.get("structure_pass", True):
+                gaps.append("공문 structure gate failed")
+        korean_proofing_status = _korean_proofing_status(plan, normalized_plan)
         return {
             "report_version": AUTHORING_REPORT_VERSION,
             "schemaVersion": DOCUMENT_PLAN_SCHEMA_VERSION,
             "plan_validation": plan_validation,
             "pass": not gaps,
+            "korean_proofing_status": korean_proofing_status,
+            "gongmun_structure": gongmun_structure,
             "block_counts": _block_counts(normalized_plan),
             "document": {
                 "paragraph_count": len(document.paragraphs),
@@ -1046,6 +1242,8 @@ def inspect_document_authoring_quality(
                 "table_count": table_count,
                 "page_break_count": page_break_count,
             },
+            "render_checked": render_checked,
+            "visual_complete": visual_complete,
             "validation": {
                 "reopened": reopened,
                 "validate_package": {
@@ -1064,7 +1262,7 @@ def inspect_document_authoring_quality(
             "style_token_usage": style_usage,
             "recovery": recovery,
             "profiles": profiles,
-            "visual_review_required": bool(gates.get("visualReviewRequired", True)),
+            "visual_review_required": bool(gates.get("visualReviewRequired", True)) and not render_checked,
             "gaps": gaps,
         }
     finally:

hwpx/design/profiles/home_notice/fragments/body.xml

@@ -0,0 +1 @@
+<hp:p xmlns:hp="http://www.hancom.co.kr/hwpml/2011/paragraph" id="2147483648" paraPrIDRef="1" styleIDRef="0" pageBreak="0" columnBreak="0" merged="0"><hp:run charPrIDRef="26"><hp:t>{{body}}</hp:t></hp:run></hp:p>

hwpx/design/profiles/home_notice/fragments/heading.xml

@@ -0,0 +1 @@
+<hp:p xmlns:hp="http://www.hancom.co.kr/hwpml/2011/paragraph" id="2147483648" paraPrIDRef="1" styleIDRef="0" pageBreak="0" columnBreak="0" merged="0"><hp:run charPrIDRef="25"><hp:t>{{heading}}</hp:t></hp:run></hp:p>

hwpx/design/profiles/home_notice/fragments/title.xml

@@ -0,0 +1 @@
+<hp:p xmlns:hp="http://www.hancom.co.kr/hwpml/2011/paragraph" id="2147483648" paraPrIDRef="25" styleIDRef="0" pageBreak="0" columnBreak="0" merged="0"><hp:run charPrIDRef="17"><hp:t>{{title}}</hp:t></hp:run></hp:p>

hwpx/design/profiles/home_notice/profile.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": "hwpx.design.profile.v1",
+  "id": "home_notice",
+  "template": "template.hwpx",
+  "fragments": {
+    "title": "fragments/title.xml",
+    "heading": "fragments/heading.xml",
+    "body": "fragments/body.xml"
+  },
+  "page": {
+    "width": 59528,
+    "height": 84186,
+    "orientation": "WIDELY",
+    "margins": {
+      "left": 4251,
+      "right": 4251,
+      "top": 1417,
+      "bottom": 0
+    }
+  },
+  "char_pr_count": 54,
+  "style_coverage_threshold": 0.98,
+  "source_basename": "ganghwa_records.hwpx"
+}

hwpx/document.py

@@ -116,6 +116,7 @@ _FORM_FIELD_PARAM_NAMES = {
     "guide",
 }
 _TEXT_ILLEGAL = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\ufffe\uffff]")
+_TRACKED_TEXT_ILLEGAL = re.compile(r"[\x00-\x08\x09\x0b\x0c\x0d\x0e-\x1f\ufffe\uffff]")
 
 
 def _local_name(node_or_tag: Any) -> str:
@@ -131,6 +132,10 @@ def _sanitize_field_text(value: str) -> str:
     return _TEXT_ILLEGAL.sub("", value)
 
 
+def _sanitize_tracked_text(value: str) -> str:
+    return _TRACKED_TEXT_ILLEGAL.sub("", value)
+
+
 def _field_type_tokens(*values: str | None) -> set[str]:
     tokens: set[str] = set()
     for value in values:
@@ -558,6 +563,111 @@ class HwpxDocument:
 
         return self._root.track_change_author(author_id_ref)
 
+    def add_track_change(
+        self,
+        change_type: str,
+        *,
+        author_name: str = "AI Agent",
+        date: str | None = None,
+    ) -> int:
+        """Add tracked-change header metadata and return the new change id."""
+
+        return self._root.add_track_change(
+            change_type,
+            author_name=author_name,
+            date=date,
+        )
+
+    @staticmethod
+    def _paragraph_has_deletable_text(
+        paragraph: HwpxOxmlParagraph,
+        match: str | None,
+    ) -> bool:
+        for run in paragraph.runs:
+            model = run.to_model()
+            run_text = "".join(span.text for span in model.text_spans)
+            if match is None:
+                if run_text:
+                    return True
+            elif match in run_text:
+                return True
+        return False
+
+    def add_tracked_insert(
+        self,
+        paragraph: HwpxOxmlParagraph,
+        text: str,
+        *,
+        author: str = "AI Agent",
+        date: str | None = None,
+        char_pr_id_ref: str | int | None = None,
+    ) -> int:
+        """Append tracked inserted *text* to *paragraph* and return its change id."""
+
+        sanitized = _sanitize_tracked_text(text)
+        if not sanitized:
+            raise ValueError("tracked insert text must be non-empty")
+        change_id = self.add_track_change("Insert", author_name=author, date=date)
+        mark_id = self._root.next_track_change_mark_id()
+        paragraph.add_tracked_insert(
+            sanitized,
+            change_id=change_id,
+            mark_id=mark_id,
+            char_pr_id_ref=char_pr_id_ref,
+        )
+        return change_id
+
+    def add_tracked_delete(
+        self,
+        paragraph: HwpxOxmlParagraph,
+        *,
+        match: str | None = None,
+        author: str = "AI Agent",
+        date: str | None = None,
+    ) -> int:
+        """Wrap paragraph text or the first matching substring in delete marks."""
+
+        if match == "":
+            raise ValueError("match must be a non-empty string")
+        if not self._paragraph_has_deletable_text(paragraph, match):
+            if match is None:
+                raise ValueError("paragraph contains no text to delete")
+            raise ValueError("match text was not found in the paragraph")
+
+        change_id = self.add_track_change("Delete", author_name=author, date=date)
+        mark_id = self._root.next_track_change_mark_id()
+        paragraph.add_tracked_delete(
+            change_id=change_id,
+            first_mark_id=mark_id,
+            match=match,
+        )
+        return change_id
+
+    def add_tracked_replace(
+        self,
+        paragraph: HwpxOxmlParagraph,
+        old: str,
+        new: str,
+        *,
+        author: str = "AI Agent",
+        date: str | None = None,
+    ) -> tuple[int, int]:
+        """Represent a replacement as tracked delete of *old* plus tracked insert of *new*."""
+
+        delete_change_id = self.add_tracked_delete(
+            paragraph,
+            match=old,
+            author=author,
+            date=date,
+        )
+        insert_change_id = self.add_tracked_insert(
+            paragraph,
+            new,
+            author=author,
+            date=date,
+        )
+        return delete_change_id, insert_change_id
+
     @property
     def memos(self) -> list[HwpxOxmlMemo]:
         """Return all memo entries declared in every section."""
@@ -659,7 +769,11 @@ class HwpxDocument:
         _append_element(parameters, f"{_HP}integerParam", {"name": "Number"}).text = str(max(1, number))
         _append_element(parameters, f"{_HP}stringParam", {"name": "CreateDateTime"}).text = created_value
         _append_element(parameters, f"{_HP}stringParam", {"name": "Author"}).text = author_value
-        _append_element(parameters, f"{_HP}stringParam", {"name": "MemoShapeID"}).text = memo_shape_id
+        # Hancom's own files use ``MemoShapeIDRef`` (65535 = the built-in default memo
+        # shape) — an empty/absent ref leaves the memo box unlinked.
+        _append_element(parameters, f"{_HP}stringParam", {"name": "MemoShapeIDRef"}).text = (
+            memo_shape_id or "65535"
+        )
 
         sub_list = _append_element(
             field_begin,
@@ -684,7 +798,10 @@ class HwpxDocument:
             },
         )
         sub_run = _append_element(sub_para, f"{_HP}run", {"charPrIDRef": char_ref})
-        _append_element(sub_run, f"{_HP}t").text = memo.id or field_value
+        # The MEMO field's subList holds the comment TEXT — this is what Hancom shows
+        # in the margin memo box. (Previously this emitted ``memo.id``, so Hancom
+        # rendered the numeric id instead of the comment.)
+        _append_element(sub_run, f"{_HP}t").text = memo.text or ""
 
         run_end = paragraph_element.makeelement(f"{_HP}run", {"charPrIDRef": char_ref})
         ctrl_end = _append_element(run_end, f"{_HP}ctrl")

hwpx/oxml/__init__.py

@@ -10,10 +10,13 @@ from .body import (
     Run,
     Section,
     TextSpan,
+    append_tracked_insert_to_run,
+    create_track_change_mark,
     parse_paragraph_element,
     parse_run_element,
     parse_section_element,
     parse_text_span,
+    wrap_tracked_delete_in_span,
 )
 from .common import GenericElement, parse_generic_element
 
@@ -74,7 +77,9 @@ from .header import (
     TrackChangeAuthorList,
     TrackChangeConfig,
     TrackChangeList,
+    format_track_change_date,
     memo_shape_from_attributes,
+    normalize_track_change_type,
     parse_begin_num,
     parse_bullet,
     parse_bullet_para_head,
@@ -98,6 +103,8 @@ from .header import (
     parse_track_change_author,
     parse_track_change_authors,
     parse_track_changes,
+    track_change_author_to_xml,
+    track_change_to_xml,
 )
 from .parser import element_to_model, parse_header_xml, parse_section_xml
 from .schema import load_schema
@@ -173,7 +180,10 @@ __all__ = [
     "TrackChangeList",
     "TextSpan",
     "XmlSource",
+    "append_tracked_insert_to_run",
+    "create_track_change_mark",
     "element_to_model",
+    "format_track_change_date",
     "load_schema",
     "parse_begin_num",
     "parse_bullet",
@@ -202,9 +212,13 @@ __all__ = [
     "parse_track_change_author",
     "parse_track_change_authors",
     "parse_track_changes",
+    "normalize_track_change_type",
     "parse_section_element",
     "parse_section_xml",
     "parse_text_span",
+    "track_change_author_to_xml",
+    "track_change_to_xml",
+    "wrap_tracked_delete_in_span",
 ]
 
 logger = logging.getLogger(__name__)