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

hwpx/__init__.py

@@ -94,6 +94,7 @@ from .authoring import (
     PlanValidationIssue,
     PlanValidationReport,
     create_document_from_plan,
+    get_document_plan_schema,
     inspect_document_authoring_quality,
     inspect_operating_plan_quality,
     normalize_document_plan,
@@ -121,6 +122,7 @@ __all__ = [
     "DEFAULT_NAMESPACES",
     "DEFAULT_STYLE_PRESET",
     "DOCUMENT_PLAN_SCHEMA_VERSION",
+    "get_document_plan_schema",
     "DocumentBlock",
     "DocumentPlan",
     "DocumentStylePreset",

hwpx/authoring.py

@@ -265,6 +265,27 @@ def _plan_issue(
     )
 
 
+_PLAN_FAMILY_PREFIX = "hwpx.document_plan.v"
+
+
+def _is_forward_plan_version(version: str) -> bool:
+    """True if *version* is a newer same-family plan schema (forward-compat).
+
+    e.g. ``hwpx.document_plan.v3`` when the latest known is v2 — validate
+    best-effort with a warning rather than hard-rejecting.
+    """
+    if not version.startswith(_PLAN_FAMILY_PREFIX):
+        return False
+    suffix = version[len(_PLAN_FAMILY_PREFIX):]
+    if not suffix.isdigit():
+        return False
+    latest_known = max(
+        int(DOCUMENT_PLAN_SCHEMA_VERSION.rsplit("v", 1)[-1]),
+        int(DOCUMENT_PLAN_V2_SCHEMA_VERSION.rsplit("v", 1)[-1]),
+    )
+    return int(suffix) > latest_known
+
+
 def _plan_validation_report(
     issues: list[PlanValidationIssue],
     *,
@@ -449,6 +470,54 @@ def _plan_repair_hints(issues: tuple[PlanValidationIssue, ...]) -> list[dict[str
     return hints
 
 
+DOCUMENT_PLAN_SCHEMA_ID = "https://airmang.github.io/hwpx-plugins/schemas/document_plan.schema.json"
+
+
+def get_document_plan_schema() -> dict[str, Any]:
+    """Return a JSON Schema (draft 2020-12) for the declarative document plan.
+
+    Built live from the validator's own constants so it never drifts from the
+    accepted contract. Usable directly as an LLM Structured-Outputs / external
+    JSON-Schema-validation contract: it constrains the envelope (schemaVersion,
+    a non-empty ``blocks`` array, each block carrying a known ``type``) while
+    leaving block bodies open (``additionalProperties``) for forward-compat.
+    """
+
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": DOCUMENT_PLAN_SCHEMA_ID,
+        "title": "HWPX Document Plan",
+        "type": "object",
+        "required": ["schemaVersion", "blocks"],
+        "additionalProperties": True,
+        "properties": {
+            "schemaVersion": {
+                "type": "string",
+                "enum": [DOCUMENT_PLAN_SCHEMA_VERSION, DOCUMENT_PLAN_V2_SCHEMA_VERSION],
+                "description": "Plan schema version. Newer same-family versions validate best-effort.",
+            },
+            "title": {"type": "string"},
+            "metadata": {"type": "object"},
+            "blocks": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                    "type": "object",
+                    "required": ["type"],
+                    "additionalProperties": True,
+                    "properties": {
+                        "type": {
+                            "type": "string",
+                            "enum": sorted(_SUPPORTED_BLOCK_TYPES),
+                            "description": "Block kind. Body fields depend on the type.",
+                        }
+                    },
+                },
+            },
+        },
+    }
+
+
 def validate_document_plan(plan: Mapping[str, Any]) -> PlanValidationReport:
     """Return validation errors for a ``hwpx.document_plan.v1`` mapping."""
 
@@ -472,6 +541,31 @@ def validate_document_plan(plan: Mapping[str, Any]) -> PlanValidationReport:
 
     schema_version = str(plan.get("schemaVersion") or "").strip()
     if schema_version not in {DOCUMENT_PLAN_SCHEMA_VERSION, DOCUMENT_PLAN_V2_SCHEMA_VERSION}:
+        if _is_forward_plan_version(schema_version):
+            # Forward-compat: a newer same-family version warns and validates as
+            # the latest known schema (best-effort) instead of hard-rejecting, so
+            # a plan emitted against a newer schema still generates. Unknown newer
+            # fields are simply ignored by the v2 validator.
+            issues.append(
+                _plan_issue(
+                    "forward_schema_version",
+                    "schemaVersion",
+                    (
+                        f"schemaVersion {schema_version!r} is newer than the latest "
+                        f"known {DOCUMENT_PLAN_V2_SCHEMA_VERSION!r}; validating as "
+                        "latest known (best-effort)."
+                    ),
+                    severity="warning",
+                    suggestion="Unknown newer fields are ignored; verify the output.",
+                )
+            )
+            v2_report = _validate_document_plan_v2(
+                plan, schema_version=DOCUMENT_PLAN_V2_SCHEMA_VERSION
+            )
+            return _plan_validation_report(
+                [*issues, *v2_report.issues],
+                schema_version=schema_version,
+            )
         issues.append(
             _plan_issue(
                 "invalid_schema_version",

hwpx/builder/__init__.py

@@ -20,10 +20,17 @@ from .core import (
     Table,
     approval_box,
 )
-from .report import BuilderSaveReport, ReopenReport
+from .report import (
+    FIDELITY_CONTRACT,
+    BuilderSaveReport,
+    BuilderVerifyReport,
+    ReopenReport,
+)
 
 __all__ = [
+    "FIDELITY_CONTRACT",
     "BuilderSaveReport",
+    "BuilderVerifyReport",
     "Bullet",
     "Document",
     "Footer",

hwpx/builder/core.py

@@ -7,11 +7,14 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from hwpx.document import HwpxDocument
+from hwpx.tools.id_integrity import check_id_integrity
+from hwpx.tools.idempotence import IdempotenceReport, check_idempotent_pair
+from hwpx.tools.package_reconcile import reconcile_package_with_document
 from hwpx.tools.package_validator import validate_editor_open_safety
 from hwpx.tools.package_validator import validate_package
 from hwpx.tools.validator import validate_document
 
-from .report import BuilderSaveReport, ReopenReport
+from .report import BuilderSaveReport, BuilderVerifyReport, ReopenReport
 
 
 BuilderChild = (
@@ -805,3 +808,104 @@ class Document:
             visual_complete=visual_complete,
         )
         return report
+
+    def verify(self) -> BuilderVerifyReport:
+        """Dry, no-disk pre-write verification of the built document.
+
+        Lowers the document to bytes in memory and runs the save hard gates
+        (package, document, editor-open-safety, reopen) *plus* id-integrity and
+        a two-round idempotence check — a strictly stronger gate set than
+        :meth:`save_to_path` (whose report leaves id-integrity to the reader and
+        does not check idempotence) — without writing any file. Returns a
+        compact signal so a caller can branch on ``ok`` and read a
+        section/paragraph count before paying to materialize a real save.
+
+        Serialization itself can fail (e.g. open-safety rejects the output); in
+        that case this returns ``ok=False`` with ``serialize_error`` set rather
+        than raising, so a caller (fuzz loop, agent) can always branch on the
+        result.
+
+        See :data:`hwpx.builder.report.FIDELITY_CONTRACT` for what a green
+        verdict proves vs. does not prove.
+        """
+
+        try:
+            lowered = self.lower()
+            data = lowered.to_bytes()
+        except Exception as exc:  # the document cannot even be serialized
+            return BuilderVerifyReport(
+                ok=False,
+                reopen_ok=False,
+                package_ok=False,
+                document_ok=False,
+                editor_open_safety_ok=False,
+                id_integrity_ok=False,
+                idempotent=False,
+                sections_reconciled=False,
+                serialize_error=f"{type(exc).__name__}: {exc}",
+            )
+
+        package_report = validate_package(data)
+        document_report = validate_document(data)
+        editor_open_safety_report = validate_editor_open_safety(data)
+
+        reopened: HwpxDocument | None = None
+        reopen_error: str | None = None
+        try:
+            reopened = HwpxDocument.open(data)
+        except Exception as exc:  # surfaced in the report rather than raised
+            reopen_error = f"{type(exc).__name__}: {exc}"
+
+        id_integrity = (
+            check_id_integrity(reopened) if reopened is not None else None
+        )
+
+        # Fixed-point check on the EXACT bytes the gates above validated (gen-1)
+        # vs. their reopen-and-resave (gen-2), so the idempotence verdict refers
+        # to the bytes we would actually write, not a later generation.
+        idempotence: IdempotenceReport | None = None
+        serialize_error: str | None = None
+        try:
+            idempotence = check_idempotent_pair(data, HwpxDocument.open(data).to_bytes())
+        except Exception as exc:
+            serialize_error = f"{type(exc).__name__}: {exc}"
+
+        # Output-vs-intent: produced section parts must match the source model.
+        reconcile = reconcile_package_with_document(data, lowered)
+
+        package_ok = bool(getattr(package_report, "ok", False))
+        document_ok = bool(getattr(document_report, "ok", False))
+        editor_open_safety_ok = bool(getattr(editor_open_safety_report, "ok", False))
+        id_integrity_ok = bool(getattr(id_integrity, "ok", False))
+        idempotent = bool(idempotence is not None and idempotence.ok)
+        reopen_ok = reopened is not None
+        section_count = len(reopened.sections) if reopened is not None else 0
+        paragraph_count = len(reopened.paragraphs) if reopened is not None else 0
+
+        ok = (
+            package_ok
+            and document_ok
+            and editor_open_safety_ok
+            and id_integrity_ok
+            and reopen_ok
+            and idempotent
+            and reconcile.ok
+        )
+
+        return BuilderVerifyReport(
+            ok=ok,
+            reopen_ok=reopen_ok,
+            package_ok=package_ok,
+            document_ok=document_ok,
+            editor_open_safety_ok=editor_open_safety_ok,
+            id_integrity_ok=id_integrity_ok,
+            idempotent=idempotent,
+            sections_reconciled=reconcile.ok,
+            section_count=section_count,
+            paragraph_count=paragraph_count,
+            byte_length=len(data),
+            reopen_error=reopen_error,
+            serialize_error=serialize_error,
+            idempotence=idempotence,
+            reconcile=reconcile,
+        )

hwpx/builder/report.py

@@ -7,10 +7,34 @@ from typing import Any
 
 from hwpx.quality import VisualCompleteReport
 from hwpx.tools.id_integrity import IdIntegrityReport, check_id_integrity
+from hwpx.tools.idempotence import IdempotenceReport
+from hwpx.tools.package_reconcile import PackageReconcileReport
 from hwpx.tools.package_validator import EditorOpenSafetyReport, PackageValidationReport
 from hwpx.tools.validator import ValidationReport
 
 
+# Explicit scope of what the builder's automated gates prove vs. don't, so a
+# green ``hard_gates`` is never mistaken for full Hancom/visual fidelity. The
+# gates answer "will Hancom likely open this", NOT "did every authored element
+# round-trip". Surfaced in every report's ``to_dict()``.
+FIDELITY_CONTRACT: dict[str, list[str]] = {
+    "proves": [
+        "package opens as a valid HWPX (mimetype/OPC structure, required entries)",
+        "no dangling id references or orphan BinData (id_integrity)",
+        "no known editor-open breakage patterns (editor_open_safety)",
+        "re-saving reproduces identical part contents (idempotent serialization)",
+        "the document reopens with our reader (reopen)",
+    ],
+    "does_not_prove": [
+        "visual layout fidelity in Hancom (line/page breaks, overlap) — needs the "
+        "visual oracle / ComputerUse",
+        "every authored element round-tripped byte-for-byte: merges, shapes, BinData "
+        "bytes, and equation script are not value-diffed",
+        "macOS Hancom acceptance for untested element combinations",
+    ],
+}
+
+
 @dataclass(frozen=True)
 class ReopenReport:
     """Result of reopening a generated document."""
@@ -56,6 +80,10 @@ class BuilderSaveReport:
             "path": str(self.path),
             "metadata": dict(self.metadata or {}),
             "hard_gates": dict(self.hard_gates),
+            "fidelity_contract": {
+                "proves": list(FIDELITY_CONTRACT["proves"]),
+                "does_not_prove": list(FIDELITY_CONTRACT["does_not_prove"]),
+            },
             "visual_review_required": self.visual_review_required,
             "feature_flags": dict(self.feature_flags),
             "visual_complete": (
@@ -113,3 +141,55 @@ class BuilderSaveReport:
                 }
             ),
         }
+
+
+@dataclass(frozen=True)
+class BuilderVerifyReport:
+    """Compact, no-disk pre-write verification signal from ``Document.verify()``.
+
+    Lowers the built document to bytes in memory and runs the same hard gates as
+    a real save plus a two-round idempotence check — without writing a file — so
+    a caller (agent, fuzz loop) can branch on ``ok`` before committing a path.
+    See :data:`FIDELITY_CONTRACT` for what these gates prove vs. don't.
+    """
+
+    ok: bool
+    reopen_ok: bool
+    package_ok: bool
+    document_ok: bool
+    editor_open_safety_ok: bool
+    id_integrity_ok: bool
+    idempotent: bool
+    sections_reconciled: bool = True
+    section_count: int = 0
+    paragraph_count: int = 0
+    byte_length: int = 0
+    reopen_error: str | None = None
+    serialize_error: str | None = None
+    idempotence: IdempotenceReport | None = None
+    reconcile: PackageReconcileReport | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "reopen_ok": self.reopen_ok,
+            "package_ok": self.package_ok,
+            "document_ok": self.document_ok,
+            "editor_open_safety_ok": self.editor_open_safety_ok,
+            "id_integrity_ok": self.id_integrity_ok,
+            "idempotent": self.idempotent,
+            "sections_reconciled": self.sections_reconciled,
+            "section_count": self.section_count,
+            "paragraph_count": self.paragraph_count,
+            "byte_length": self.byte_length,
+            "reopen_error": self.reopen_error,
+            "serialize_error": self.serialize_error,
+            "idempotence": (
+                None if self.idempotence is None else self.idempotence.to_dict()
+            ),
+            "reconcile": (None if self.reconcile is None else self.reconcile.to_dict()),
+            "fidelity_contract": {
+                "proves": list(FIDELITY_CONTRACT["proves"]),
+                "does_not_prove": list(FIDELITY_CONTRACT["does_not_prove"]),
+            },
+        }

hwpx/conformance/roundtrip_batch.py

@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Ranked roundtrip batch harness over an HWPX corpus.
+
+Runs each sample through ``open -> serialize (round1) -> reopen -> serialize
+(round2)`` and classifies it into a single ranked status:
+
+    PARSE_FAIL  -> SERIALIZE_FAIL -> REPARSE_FAIL -> ROUND2_DIFF -> PASS
+
+Hard failures (parse/serialize/reparse) are structural and fail CI (non-zero
+exit). ``ROUND2_DIFF`` (the serializer is not a fixed point from its own output)
+is *gradable* — reported but non-blocking — so a corpus can carry a known-
+imperfect sample without masking a true structural regression. A separate
+informational ``source_semantic_drift`` flag records whether the content
+sequence changed from the ORIGINAL on first roundtrip (legitimate normalization
+or a genuine loss; not a pass/fail by itself).
+
+This gives a cheap, continuous, Hancom-free content-fidelity signal between the
+expensive ComputerUse visual checks.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from hwpx.document import HwpxDocument
+from hwpx.tools.idempotence import check_idempotent_pair
+from hwpx.tools.ir_equality import compare_documents_semantic
+
+__all__ = ["SampleResult", "BatchReport", "classify_sample", "run_corpus", "main"]
+
+_STATUS_RANK = {
+    "PARSE_FAIL": 0,
+    "SERIALIZE_FAIL": 1,
+    "REPARSE_FAIL": 2,
+    "ROUND2_DIFF": 3,
+    "PASS": 4,
+}
+_HARD_FAILS = {"PARSE_FAIL", "SERIALIZE_FAIL", "REPARSE_FAIL"}
+
+
+@dataclass(frozen=True)
+class SampleResult:
+    sample: str
+    status: str
+    detail: str = ""
+    source_semantic_drift: bool = False
+
+    @property
+    def is_hard_fail(self) -> bool:
+        return self.status in _HARD_FAILS
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "sample": self.sample,
+            "status": self.status,
+            "detail": self.detail,
+            "source_semantic_drift": self.source_semantic_drift,
+        }
+
+
+@dataclass
+class BatchReport:
+    results: list[SampleResult] = field(default_factory=list)
+
+    @property
+    def counts(self) -> dict[str, int]:
+        return dict(Counter(r.status for r in self.results))
+
+    @property
+    def hard_fail_count(self) -> int:
+        return sum(1 for r in self.results if r.is_hard_fail)
+
+    @property
+    def drift_count(self) -> int:
+        return sum(1 for r in self.results if r.source_semantic_drift)
+
+    @property
+    def ok(self) -> bool:
+        return self.hard_fail_count == 0
+
+    def to_tsv(self) -> str:
+        lines = ["sample\tstatus\tsource_drift\tdetail"]
+        for r in self.results:
+            lines.append(f"{r.sample}\t{r.status}\t{int(r.source_semantic_drift)}\t{r.detail}")
+        return "\n".join(lines) + "\n"
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "ok": self.ok,
+            "total": len(self.results),
+            "counts": self.counts,
+            "hardFailCount": self.hard_fail_count,
+            "sourceDriftCount": self.drift_count,
+            "results": [r.to_dict() for r in self.results],
+        }
+
+
+def classify_sample(path: str | Path) -> SampleResult:
+    name = Path(path).name
+    try:
+        source = Path(path).read_bytes()
+        doc1 = HwpxDocument.open(source)
+    except Exception as exc:
+        return SampleResult(name, "PARSE_FAIL", f"{type(exc).__name__}: {exc}")
+    try:
+        round1 = doc1.to_bytes()
+    except Exception as exc:
+        return SampleResult(name, "SERIALIZE_FAIL", f"{type(exc).__name__}: {exc}")
+    try:
+        round2 = HwpxDocument.open(round1).to_bytes()
+    except Exception as exc:
+        return SampleResult(name, "REPARSE_FAIL", f"{type(exc).__name__}: {exc}")
+
+    # Informational: did the content sequence change from the original?
+    drift = not compare_documents_semantic(source, round1).ok
+
+    idem = check_idempotent_pair(round1, round2)
+    if not idem.ok:
+        return SampleResult(name, "ROUND2_DIFF", idem.summary(), drift)
+    return SampleResult(name, "PASS", "", drift)
+
+
+def run_corpus(
+    corpus_dir: str | Path, samples: list[str] | None = None
+) -> BatchReport:
+    corpus = Path(corpus_dir)
+    if samples is None:
+        manifest = corpus / "manifest.json"
+        if manifest.exists():
+            samples = [s["file"] for s in json.loads(manifest.read_text("utf-8"))["samples"]]
+        else:
+            samples = sorted(p.name for p in corpus.glob("*.hwpx"))
+    report = BatchReport()
+    for sample in samples:
+        report.results.append(classify_sample(corpus / sample))
+    # Worst-first ordering for readability.
+    report.results.sort(key=lambda r: (_STATUS_RANK.get(r.status, 99), r.sample))
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv:
+        print("usage: roundtrip_batch <corpus_dir> [--tsv out.tsv] [--json out.json]", file=sys.stderr)
+        return 2
+    corpus_dir = argv[0]
+    tsv_out = json_out = None
+    if "--tsv" in argv:
+        tsv_out = argv[argv.index("--tsv") + 1]
+    if "--json" in argv:
+        json_out = argv[argv.index("--json") + 1]
+
+    report = run_corpus(corpus_dir)
+    if tsv_out:
+        Path(tsv_out).write_text(report.to_tsv(), "utf-8")
+    if json_out:
+        Path(json_out).write_text(json.dumps(report.to_dict(), ensure_ascii=False, indent=2), "utf-8")
+
+    print(
+        f"corpus={len(report.results)} counts={report.counts} "
+        f"hardFails={report.hard_fail_count} sourceDrift={report.drift_count}"
+    )
+    return 1 if report.hard_fail_count else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

hwpx/document.py

@@ -1819,6 +1819,9 @@ class HwpxDocument:
         spacing_before_pt: float | None = None,
         spacing_after_pt: float | None = None,
         outline_level: int | None = None,
+        keep_with_next: bool | None = None,
+        keep_lines: bool | None = None,
+        page_break_before: bool | None = None,
         bottom_border: bool = False,
         border_color: str = "#BFBFBF",
         border_width: str = "0.12 mm",
@@ -1826,7 +1829,9 @@ class HwpxDocument:
         """Apply paragraph-level formatting using human units.
 
         Millimetre inputs are converted to HWP units; paragraph spacing uses
-        points; line spacing is stored as a percent value.
+        points; line spacing is stored as a percent value. ``keep_with_next`` /
+        ``keep_lines`` / ``page_break_before`` set the paragraph's keep-together
+        (``<hh:breakSetting>``) flags via a freshly minted paraPr.
         """
 
         if not self._root.headers:
@@ -1858,12 +1863,21 @@ class HwpxDocument:
             else:
                 raise ValueError("outline_level must be between 0 and 10")
 
+        break_setting: dict[str, bool] = {}
+        if keep_with_next is not None:
+            break_setting["keep_with_next"] = bool(keep_with_next)
+        if keep_lines is not None:
+            break_setting["keep_lines"] = bool(keep_lines)
+        if page_break_before is not None:
+            break_setting["page_break_before"] = bool(page_break_before)
+
         if (
             alignment is None
             and line_spacing_percent is None
             and not margins
             and heading is None
             and not bottom_border
+            and not break_setting
         ):
             raise ValueError("at least one paragraph formatting option is required")
 
@@ -1897,6 +1911,7 @@ class HwpxDocument:
                 margins=margins,
                 heading=heading,
                 border=border,
+                break_setting=break_setting or None,
             )
             paragraph.para_pr_id_ref = para_pr_id
             formatted.append({"paragraph_index": index, "paraPrIDRef": para_pr_id})
@@ -2446,8 +2461,11 @@ class HwpxDocument:
         # 1) Write image bytes into the package
         self._package.write(bin_data_path, image_data)
 
-        # 2) Register in manifest
-        self._package.add_manifest_item(item_id, bin_data_path, media_type)
+        # 2) Register in manifest. ``isEmbeded="1"`` (OWPML's single-d spelling) marks
+        #    the BinData image as embedded — real Hancom drops the picture without it.
+        self._package.add_manifest_item(
+            item_id, bin_data_path, media_type, extra_attrs={"isEmbeded": "1"}
+        )
 
         # 3) Register in header binDataList
         header = self._root.headers[0] if self._root.headers else None

hwpx/exam/__init__.py

@@ -0,0 +1,22 @@
+"""Exam re-typesetting (조판): authored exam Markdown -> school form .hwpx body."""
+from __future__ import annotations
+
+from .compose import ComposePlan, ComposeResult, ParaSpec, compose_exam_into_form, lower_exam, replace_body_region
+from .ir import ExamDoc, Placeholder, Question, QuestionSet
+from .measure import (
+    SplitReport,
+    column_x_bounds,
+    group_question_blocks,
+    measure_question_splits,
+)
+from .parser import ExamParseError, parse_exam_markdown
+from .profile import FormProfile, FormProfileError, ResolvedStyle, profile_form
+
+__all__ = [
+    "ExamDoc", "Placeholder", "Question", "QuestionSet",
+    "ExamParseError", "parse_exam_markdown",
+    "FormProfile", "FormProfileError", "ResolvedStyle", "profile_form",
+    "column_x_bounds", "group_question_blocks", "measure_question_splits", "SplitReport",
+    "ParaSpec", "lower_exam", "replace_body_region", "ComposePlan",
+    "ComposeResult", "compose_exam_into_form",
+]