python-hwpx 2.18.0__py3-none-any.whl → 2.20.0__py3-none-any.whl

hwpx/tools/read_fidelity.py

@@ -0,0 +1,281 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Content-level read-fidelity harness for HWPX (M6 / S-060).
+
+Where :mod:`hwpx.tools.roundtrip_diff` measures *element-count* preservation,
+this module measures *content* fidelity:
+
+* :func:`resolve_run_spans` — the canonical per-run resolved formatting
+  (bold / italic / underline / strikeout / color / size / font). This is the
+  single source of truth the installed MCP surface is verified against.
+* :func:`collect_notes` — footnote / endnote instances with their body text and
+  body run formatting (the reading surfaces drop these today).
+* :func:`roundtrip_fidelity` / :func:`corpus_fidelity` — open->save->reopen
+  agreement, the lossless guard.
+* :func:`spans_fidelity` / :func:`notes_fidelity` — general comparators reused
+  to score a candidate extraction (e.g. an MCP tool payload) against the
+  canonical one.
+
+Purely structural — no Hancom oracle required.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Sequence
+
+from hwpx.document import HwpxDocument
+
+_HH = "{http://www.hancom.co.kr/hwpml/2011/head}"
+#: Values that mean "attribute is present but inactive".
+_OFF = {None, "", "NONE"}
+
+
+@dataclass(frozen=True)
+class RunSpan:
+    """Resolved inline formatting of a single ``<hp:run>``."""
+
+    text: str
+    bold: bool = False
+    italic: bool = False
+    underline: str | None = None  # underline TYPE (BOTTOM/CENTER/TOP...) or None when off
+    strikeout: bool = False
+    color: str | None = None
+    size_pt: float | None = None
+    font: str | None = None
+    superscript: bool = False
+    subscript: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "text": self.text,
+            "bold": self.bold,
+            "italic": self.italic,
+            "underline": self.underline,
+            "strikeout": self.strikeout,
+            "color": self.color,
+            "sizePt": self.size_pt,
+            "font": self.font,
+            "superscript": self.superscript,
+            "subscript": self.subscript,
+        }
+
+
+@dataclass(frozen=True)
+class NoteSpan:
+    """A footnote / endnote instance and its resolved body."""
+
+    kind: str  # "footNote" | "endNote"
+    inst_id: str | None
+    anchor_para_index: int
+    body_text: str
+    body_spans: tuple[RunSpan, ...] = field(default_factory=tuple)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "instId": self.inst_id,
+            "anchorParaIndex": self.anchor_para_index,
+            "bodyText": self.body_text,
+            "bodySpans": [s.to_dict() for s in self.body_spans],
+        }
+
+
+# ── resolution ───────────────────────────────────────────────────────
+def _fontface_maps(doc: HwpxDocument) -> dict[str, dict[str, str]]:
+    """Return ``{lang: {font_id: face_name}}`` from every header's fontfaces."""
+    maps: dict[str, dict[str, str]] = {}
+    for header in getattr(doc.oxml, "headers", []) or []:
+        element = getattr(header, "element", None)
+        if element is None:
+            continue
+        for fontface in element.iter(f"{_HH}fontface"):
+            lang = (fontface.get("lang") or "").lower()
+            bucket = maps.setdefault(lang, {})
+            for font in fontface.findall(f"{_HH}font"):
+                fid, face = font.get("id"), font.get("face")
+                if fid is not None and face is not None:
+                    bucket.setdefault(fid, face)
+    return maps
+
+
+def _resolve_font(style: Any, fontfaces: dict[str, dict[str, str]]) -> str | None:
+    font_ref = (style.child_attributes.get("fontRef") if style else None) or {}
+    fid = font_ref.get("hangul")
+    if fid is None:
+        fid = next(iter(font_ref.values()), None)
+    if fid is None:
+        return None
+    return fontfaces.get("hangul", {}).get(fid) or None
+
+
+def _int(value: Any, default: int = 0) -> int:
+    try:
+        return int(str(value))
+    except (TypeError, ValueError):
+        return default
+
+
+def _style_to_span(text: str, style: Any, fontfaces: dict[str, dict[str, str]]) -> RunSpan:
+    if style is None:
+        return RunSpan(text=text)
+    child = style.child_attributes or {}
+
+    underline_type = (child.get("underline") or {}).get("type")
+    if underline_type in _OFF:
+        underline_type = None
+
+    strike_shape = (child.get("strikeout") or {}).get("shape")
+    strikeout = strike_shape not in _OFF
+
+    height = style.attributes.get("height")
+    size_pt = round(_int(height) / 100.0, 2) if height and _int(height) > 0 else None
+
+    offset_h = _int((child.get("offset") or {}).get("hangul"))
+
+    return RunSpan(
+        text=text,
+        bold="bold" in child,
+        italic="italic" in child,
+        underline=underline_type,
+        strikeout=strikeout,
+        color=style.attributes.get("textColor"),
+        size_pt=size_pt,
+        font=_resolve_font(style, fontfaces),
+        superscript=offset_h > 0,
+        subscript=offset_h < 0,
+    )
+
+
+def fontface_maps(doc: HwpxDocument) -> dict[str, dict[str, str]]:
+    """Public: ``{lang: {font_id: face_name}}`` for surface reuse (MCP)."""
+    return _fontface_maps(doc)
+
+
+def run_span(text: str, style: Any, fontfaces: dict[str, dict[str, str]] | None = None) -> RunSpan:
+    """Public: resolve one run's :class:`RunSpan` (fontfaces from :func:`fontface_maps`)."""
+    return _style_to_span(text, style, fontfaces or {})
+
+
+def resolve_run_spans(doc: HwpxDocument) -> list[RunSpan]:
+    """Return the resolved inline formatting for every body run, in order."""
+    fontfaces = _fontface_maps(doc)
+    spans: list[RunSpan] = []
+    for section in doc.sections:
+        for paragraph in section.paragraphs:
+            for run in paragraph.runs:
+                spans.append(_style_to_span(run.text or "", run.style, fontfaces))
+    return spans
+
+
+def collect_notes(doc: HwpxDocument) -> list[NoteSpan]:
+    """Return every footnote / endnote with body text and body formatting."""
+    fontfaces = _fontface_maps(doc)
+    notes: list[NoteSpan] = []
+    para_index = 0
+    for section in doc.sections:
+        for paragraph in section.paragraphs:
+            for note in list(paragraph.footnotes) + list(paragraph.endnotes):
+                body_spans: tuple[RunSpan, ...] = ()
+                try:
+                    body = note.body_paragraph
+                    body_spans = tuple(
+                        _style_to_span(r.text or "", r.style, fontfaces) for r in body.runs
+                    )
+                except Exception:  # pragma: no cover - defensive
+                    body_spans = ()
+                notes.append(
+                    NoteSpan(
+                        kind=note.kind,
+                        inst_id=note.inst_id,
+                        anchor_para_index=para_index,
+                        body_text=note.text,
+                        body_spans=body_spans,
+                    )
+                )
+            para_index += 1
+    return notes
+
+
+# ── comparators ──────────────────────────────────────────────────────
+def _first_mismatch(ref: Sequence[Any], cand: Sequence[Any]) -> dict[str, Any] | None:
+    for i, a in enumerate(ref):
+        b = cand[i] if i < len(cand) else None
+        if a != b:
+            return {"index": i, "ref": a.to_dict() if a is not None else None,
+                    "cand": b.to_dict() if b is not None else None}
+    if len(cand) > len(ref):
+        return {"index": len(ref), "ref": None, "cand": cand[len(ref)].to_dict()}
+    return None
+
+
+def spans_fidelity(ref: Sequence[RunSpan], cand: Sequence[RunSpan]) -> dict[str, Any]:
+    """Fraction of reference run-spans reproduced identically by ``cand``."""
+    denom = max(len(ref), 1)
+    same = sum(1 for i, a in enumerate(ref) if i < len(cand) and a == cand[i])
+    return {
+        "count_ref": len(ref),
+        "count_cand": len(cand),
+        "same": same,
+        "fidelity": same / denom,
+        "count_match": len(ref) == len(cand),
+        "first_mismatch": _first_mismatch(ref, cand),
+    }
+
+
+def notes_fidelity(ref: Sequence[NoteSpan], cand: Sequence[NoteSpan]) -> dict[str, Any]:
+    """Fraction of reference notes reproduced identically by ``cand``."""
+    denom = max(len(ref), 1)
+    same = sum(1 for i, a in enumerate(ref) if i < len(cand) and a == cand[i])
+    return {
+        "count_ref": len(ref),
+        "count_cand": len(cand),
+        "same": same,
+        "fidelity": same / denom,
+        "count_match": len(ref) == len(cand),
+        "first_mismatch": _first_mismatch(ref, cand),
+    }
+
+
+# ── round-trip ───────────────────────────────────────────────────────
+def roundtrip_fidelity(source: str | Path | bytes) -> dict[str, Any]:
+    """Open->serialize->reopen and score run-format + note preservation."""
+    before = HwpxDocument.open(source)
+    runs_before = resolve_run_spans(before)
+    notes_before = collect_notes(before)
+
+    after = HwpxDocument.open(before.to_bytes())
+    runs_after = resolve_run_spans(after)
+    notes_after = collect_notes(after)
+
+    return {
+        "run_format": spans_fidelity(runs_before, runs_after),
+        "notes": notes_fidelity(notes_before, notes_after),
+    }
+
+
+def corpus_fidelity(paths: Sequence[str | Path]) -> dict[str, Any]:
+    """Aggregate run-format round-trip fidelity across a corpus."""
+    per_file: dict[str, Any] = {}
+    total_runs = same_runs = 0
+    below: list[dict[str, Any]] = []
+    errors: dict[str, str] = {}
+    for path in paths:
+        key = str(path)
+        try:
+            report = roundtrip_fidelity(path)["run_format"]
+        except Exception as exc:  # pragma: no cover - defensive
+            errors[key] = repr(exc)[:200]
+            continue
+        per_file[key] = report
+        total_runs += report["count_ref"]
+        same_runs += report["same"]
+        if report["fidelity"] < 1.0 or not report["count_match"]:
+            below.append({"file": key, "fidelity": report["fidelity"], "runs": report["count_ref"]})
+    return {
+        "files": len(per_file),
+        "total_runs": total_runs,
+        "run_format_fidelity": (same_runs / total_runs) if total_runs else 1.0,
+        "files_below_100pct": below,
+        "errors": errors,
+        "per_file": per_file,
+    }

hwpx/tools/toc_author.py

@@ -0,0 +1,291 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Author Hancom-native TOC and page cross-reference fields (M7 / S-062 P2).
+
+Emits the exact field contract reverse-engineered from an owner-authored
+Hancom document (``specs/009-native-toc-xrefs/evidence/
+p0-native-toc-xml-contract.md``; gold pair vendored in
+``tests/fixtures/m7_toc_gold/``):
+
+* ``<hp:fieldBegin type="TABLEOFCONTENTS">`` + ``TableOfContents:set`` Command
+  DSL wrapping generated entry paragraphs (HYPERLINK fields whose single
+  ``<hp:t>`` nests the dot-leader ``hp:tab``; page number in the tab's tail),
+* ``<hp:fieldBegin type="CROSSREF">`` page references whose cached result is
+  the plain ``hp:t`` run between fieldBegin and fieldEnd (Hancom recomputes
+  these automatically on edit/save — P0 measured),
+* anchors that are plain paragraph ``id`` attributes; TOC-targeted headings
+  therefore need document-unique ids (:func:`ensure_paragraph_anchor_id`).
+
+Honest semantics (measured): entry page numbers emitted here are ESTIMATES —
+Hancom only recomputes the TOC block on an explicit 차례 새로 고침, which the
+P3 oracle triggers and verifies. CROSSREF caches self-heal on edit/save.
+The parameter spelling ``Fiexde`` replicates Hancom's own output verbatim.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Sequence
+from uuid import uuid4
+
+# live section paragraphs are lxml elements — new nodes must match
+from lxml import etree as ET
+
+from hwpx.document import HwpxDocument
+
+_HP = "{http://www.hancom.co.kr/hwpml/2011/paragraph}"
+_NON_UNIQUE_PARA_ID = "2147483648"
+_OUTLINE_NAME_RE = re.compile(r"^(?:개요|Outline)\s*(\d+)$")
+#: Measured TOC Command (gold contract). ContentsMake:uint:31 = the bitmask the
+#: Hancom dialog emitted (title+table+figure+equation blocks); other values are
+#: unmeasured, so v1 replicates the captured value verbatim.
+_TOC_COMMAND = (
+    "TableOfContents:set:140:ContentsMake:uint:31 ContentsStyles:wstring:0: "
+    "ContentsLevel:int:{level} ContentsAutoTabRight:int:0 "
+    "ContentsLeader:int:{leader} ContentsHyperlink:bool:{hyperlink}  "
+)
+
+
+def _rand_id() -> str:
+    return str(uuid4().int & 0x7FFFFFFF)
+
+
+def _existing_paragraph_ids(doc: HwpxDocument) -> set[str]:
+    ids: set[str] = set()
+    for section in doc.oxml.sections:
+        for p_el in section.element.iter(f"{_HP}p"):
+            pid = p_el.get("id")
+            if pid:
+                ids.add(pid)
+    return ids
+
+
+def ensure_paragraph_anchor_id(doc: HwpxDocument, paragraph: Any) -> str:
+    """Make ``paragraph`` addressable as a field anchor (``?#<id>``).
+
+    Hancom resolves TOC/CROSSREF targets by the paragraph ``id`` attribute, so
+    an anchor id must be unique in the document (generated paragraphs may all
+    carry the shared ``2147483648`` constant)."""
+    element = paragraph.element
+    pid = element.get("id")
+    ids = _existing_paragraph_ids(doc)
+    duplicated = pid and sum(1 for section in doc.oxml.sections
+                             for p in section.element.iter(f"{_HP}p")
+                             if p.get("id") == pid) > 1
+    if not pid or pid == _NON_UNIQUE_PARA_ID or duplicated:
+        new_id = _rand_id()
+        while new_id in ids:
+            new_id = _rand_id()
+        element.set("id", new_id)
+        pid = new_id
+    return pid
+
+
+def outline_heading_paragraphs(doc: HwpxDocument) -> list[tuple[Any, int, str]]:
+    """Return ``(paragraph, level, text)`` for 개요/Outline-styled paragraphs."""
+    levels: dict[str, int] = {}
+    for style_id, style in (doc.styles or {}).items():
+        name = getattr(style, "name", "") or ""
+        match = _OUTLINE_NAME_RE.match(name.strip())
+        if match:
+            levels[str(style_id)] = int(match.group(1))
+    result: list[tuple[Any, int, str]] = []
+    for section in doc.sections:
+        for paragraph in section.paragraphs:
+            style_ref = paragraph.element.get("styleIDRef")
+            if style_ref in levels and (paragraph.text or "").strip():
+                result.append((paragraph, levels[style_ref], paragraph.text.strip()))
+    return result
+
+
+# ── low-level field emission ─────────────────────────────────────────
+def _param(parent: ET.Element, kind: str, name: str, value: str, *, preserve: bool = False) -> None:
+    el = ET.SubElement(parent, f"{_HP}{kind}", {"name": name})
+    if preserve:
+        el.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+    el.text = value
+
+
+def _field_begin(run: ET.Element, *, ftype: str, field_id: str, editable: str, dirty: str) -> ET.Element:
+    ctrl = ET.SubElement(run, f"{_HP}ctrl")
+    begin = ET.SubElement(
+        ctrl,
+        f"{_HP}fieldBegin",
+        {
+            "id": field_id,
+            "type": ftype,
+            "name": "",
+            "editable": editable,
+            "dirty": dirty,
+            "zorder": "-1",
+            "fieldid": _rand_id(),
+            "metaTag": "",
+        },
+    )
+    return begin
+
+
+def _field_end(run: ET.Element, field_id: str) -> None:
+    ctrl = ET.SubElement(run, f"{_HP}ctrl")
+    ET.SubElement(ctrl, f"{_HP}fieldEnd", {"beginIDRef": field_id})
+
+
+def _entry_paragraph(numbered_title: str, page: int, target_id: str, char_pr: str = "0") -> ET.Element:
+    """One generated TOC entry: HYPERLINK field wrapping ``title<tab/>page``."""
+    p = ET.Element(f"{_HP}p", {
+        "id": _rand_id(), "paraPrIDRef": "0", "styleIDRef": "0",
+        "pageBreak": "0", "columnBreak": "0", "merged": "0",
+    })
+    field_id = _rand_id()
+    run1 = ET.SubElement(p, f"{_HP}run", {"charPrIDRef": char_pr})
+    begin = _field_begin(run1, ftype="HYPERLINK", field_id=field_id, editable="0", dirty="1")
+    params = ET.SubElement(begin, f"{_HP}parameters", {"cnt": "5", "name": ""})
+    _param(params, "integerParam", "Prop", "0")
+    _param(params, "stringParam", "Command", f"?#{target_id};0;1;0;")
+    _param(params, "stringParam", "Category", "HWPHYPERLINK_TYPE_HWP")
+    _param(params, "stringParam", "TargetType", "HWPHYPERLINK_TARGET_OUTLINE")
+    _param(params, "stringParam", "DocOpenType", "HWPHYPERLINK_JUMP_CURRENTTAB")
+
+    run2 = ET.SubElement(p, f"{_HP}run", {"charPrIDRef": char_pr})
+    t = ET.SubElement(run2, f"{_HP}t")
+    t.text = numbered_title
+    tab = ET.SubElement(t, f"{_HP}tab", {"width": "34032", "leader": "3", "type": "2"})
+    tab.tail = str(page)
+
+    run3 = ET.SubElement(p, f"{_HP}run", {"charPrIDRef": char_pr})
+    _field_end(run3, field_id)
+    return p
+
+
+def mark_toc_dirty(doc: HwpxDocument) -> int:
+    """Set ``dirty="1"`` on every TABLEOFCONTENTS field — the measured
+    re-number trigger: Hancom regenerates a dirty TOC (entries, styles, page
+    numbers) when it next opens the document. Call after edits that shift
+    pagination. Returns the number of fields marked."""
+    count = 0
+    for section in doc.oxml.sections:
+        for begin in section.element.iter(f"{_HP}fieldBegin"):
+            if begin.get("type") == "TABLEOFCONTENTS":
+                begin.set("dirty", "1")
+                count += 1
+        if count:
+            section.mark_dirty()
+    return count
+
+
+def add_native_toc(
+    doc: HwpxDocument,
+    *,
+    at_index: int = 0,
+    title: str = "<제목 차례>",
+    level: int = 2,
+    leader: int = 3,
+    hyperlink: bool = True,
+    dirty: bool = True,
+    headings: Sequence[Any] | None = None,
+) -> dict[str, Any]:
+    """Insert a Hancom-native TABLEOFCONTENTS field region at ``at_index``.
+
+    Entries are generated from ``headings`` (paragraph wrappers) or, when
+    omitted, auto-detected 개요/Outline-styled paragraphs. Emitted entry page
+    numbers are naive estimates; with ``dirty=True`` (default, measured
+    semantics) Hancom regenerates the whole region — correct entries, styles,
+    and page numbers — on its next open, so the first thing a user sees is a
+    TOC Hancom itself computed. Returns a summary dict.
+
+    Collection note (measured): Hancom collects outline-styled paragraphs and
+    — via the ``ContentsStyles:wstring:0:`` command — style-0 (바탕글)
+    paragraphs too; give body text a non-collected style (e.g. 본문, style 1)
+    or it will appear as TOC entries after regeneration.
+    """
+    if headings is None:
+        detected = outline_heading_paragraphs(doc)
+    else:
+        detected = [(p, 1, (p.text or "").strip()) for p in headings]
+    if not detected:
+        raise ValueError("no outline headings found to build a TOC from")
+
+    anchors: list[tuple[str, int, str]] = []
+    for paragraph, lvl, text in detected:
+        anchor = ensure_paragraph_anchor_id(doc, paragraph)
+        anchors.append((anchor, lvl, text))
+
+    section = doc.oxml.sections[0]
+    toc_field_id = _rand_id()
+
+    # opening paragraph: [ctrl fieldBegin TABLEOFCONTENTS][t title]
+    open_p = ET.Element(f"{_HP}p", {
+        "id": _rand_id(), "paraPrIDRef": "0", "styleIDRef": "0",
+        "pageBreak": "0", "columnBreak": "0", "merged": "0",
+    })
+    run = ET.SubElement(open_p, f"{_HP}run", {"charPrIDRef": "0"})
+    begin = _field_begin(
+        run, ftype="TABLEOFCONTENTS", field_id=toc_field_id,
+        editable="1", dirty="1" if dirty else "0",
+    )
+    params = ET.SubElement(begin, f"{_HP}parameters", {"cnt": "2", "name": ""})
+    _param(params, "integerParam", "Prop", "8")
+    _param(
+        params, "stringParam", "Command",
+        _TOC_COMMAND.format(level=level, leader=leader, hyperlink=1 if hyperlink else 0),
+        preserve=True,
+    )
+    t = ET.SubElement(run, f"{_HP}t")
+    t.text = title
+
+    entry_elements = [
+        _entry_paragraph(f"{i}. {text}", 1, anchor)
+        for i, (anchor, _lvl, text) in enumerate(anchors, start=1)
+    ]
+
+    # closing paragraph: [ctrl fieldEnd]
+    close_p = ET.Element(f"{_HP}p", {
+        "id": _rand_id(), "paraPrIDRef": "0", "styleIDRef": "0",
+        "pageBreak": "0", "columnBreak": "0", "merged": "0",
+    })
+    close_run = ET.SubElement(close_p, f"{_HP}run", {"charPrIDRef": "0"})
+    _field_end(close_run, toc_field_id)
+
+    section.insert_paragraphs(at_index, [open_p, *entry_elements, close_p])
+    return {
+        "tocFieldId": toc_field_id,
+        "entryCount": len(anchors),
+        "anchors": [a for a, _l, _t in anchors],
+        "cachedPagesAreEstimates": True,
+    }
+
+
+def add_page_crossref(
+    doc: HwpxDocument,
+    paragraph: Any,
+    target_paragraph: Any,
+    *,
+    cached_page: int = 1,
+) -> dict[str, Any]:
+    """Append a Hancom-native page CROSSREF (상호참조 → 쪽 번호) to ``paragraph``.
+
+    The cached result run is a best-effort estimate; Hancom recomputes CROSSREF
+    caches automatically on edit/save (P0 measured on the gold pair: 2→3)."""
+    target_id = ensure_paragraph_anchor_id(doc, target_paragraph)
+    field_id = _rand_id()
+    p_el = paragraph.element
+
+    run1 = ET.SubElement(p_el, f"{_HP}run", {"charPrIDRef": "0"})
+    begin = _field_begin(run1, ftype="CROSSREF", field_id=field_id, editable="0", dirty="0")
+    params = ET.SubElement(begin, f"{_HP}parameters", {"cnt": "8", "name": ""})
+    _param(params, "booleanParam", "Fiexde", "1")  # sic — Hancom's own spelling
+    _param(params, "integerParam", "Prop", "0")
+    _param(params, "stringParam", "Command", f"?#{target_id};5;0;0;0;")
+    _param(params, "stringParam", "RefPath", f"?#{target_id};")
+    _param(params, "stringParam", "RefType", "TARGET_OUTLINE")
+    _param(params, "stringParam", "RefContentType", "OBJECT_TYPE_PAGE")
+    _param(params, "booleanParam", "RefHyperLink", "false")
+    _param(params, "stringParam", "RefOpenType", "HWPHYPERLINK_JUMP_CURRENTTAB")
+
+    run2 = ET.SubElement(p_el, f"{_HP}run", {"charPrIDRef": "0"})
+    t = ET.SubElement(run2, f"{_HP}t")
+    t.text = str(cached_page)
+
+    run3 = ET.SubElement(p_el, f"{_HP}run", {"charPrIDRef": "0"})
+    _field_end(run3, field_id)
+
+    paragraph.section.mark_dirty()
+    return {"fieldId": field_id, "targetId": target_id, "cachedPage": cached_page}