@prismer/runtime 2.2.55 → 2.2.63

package/built-in-skills/office-artifacts/references/docx/scripts/docx_validate.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+# MIT License. Part of the Hermes docx skill.
+"""Health-check a .docx package and report issues as JSON.
+
+Usage: docx_validate.py file.docx
+
+Checks (health-check tier, NOT full XSD schema validation):
+  - the file is a readable zip and python-docx can open it
+  - required package parts exist ([Content_Types].xml, document.xml)
+  - every relationship in every .rels file resolves to a part in the
+    package (dangling image/hyperlink/etc. rels are reported; external
+    targets such as hyperlinks are skipped)
+  - r:embed / r:id references in document.xml resolve to relationships
+  - embedded images are non-empty and start with known magic bytes
+    (PNG/JPEG/GIF/BMP/TIFF/EMF/WMF/SVG); no PIL required
+  - paragraph and run style ids referenced by the document exist in
+    styles.xml
+
+Output: {"ok": bool, "issues": [{"severity": "error"|"warning", ...}]}
+Exit code 1 when any error-severity issue is found (warnings exit 0).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import posixpath
+import sys
+import zipfile
+
+from lxml import etree
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+PR = "http://schemas.openxmlformats.org/package/2006/relationships"
+
+IMAGE_MAGIC = (
+    b"\x89PNG\r\n\x1a\n", b"\xff\xd8\xff", b"GIF87a", b"GIF89a",
+    b"BM", b"II*\x00", b"MM\x00*",
+    b"\x01\x00\x00\x00",              # EMF
+    b"\xd7\xcd\xc6\x9a", b"\x01\x00\x09\x00",  # WMF variants
+    b"<?xml", b"<svg",
+)
+
+
+def _issue(issues, severity, code, detail):
+    issues.append({"severity": severity, "code": code, "detail": detail})
+
+
+def _rel_target(base_part: str, target: str) -> str:
+    base_dir = posixpath.dirname(base_part)
+    return posixpath.normpath(posixpath.join(base_dir, target)).lstrip("/")
+
+
+def validate(path: str) -> dict:
+    issues: list[dict] = []
+
+    try:
+        zf = zipfile.ZipFile(path)
+    except (OSError, zipfile.BadZipFile) as exc:
+        _issue(issues, "error", "not-a-zip", str(exc))
+        return {"ok": False, "issues": issues}
+
+    names = set(zf.namelist())
+    bad = zf.testzip()
+    if bad is not None:
+        _issue(issues, "error", "corrupt-member", f"CRC check failed: {bad}")
+
+    for required in ("[Content_Types].xml", "word/document.xml"):
+        if required not in names:
+            _issue(issues, "error", "missing-part",
+                   f"required part absent: {required}")
+    if issues and any(i["severity"] == "error" for i in issues):
+        return {"ok": False, "issues": issues}
+
+    # --- relationships resolve ------------------------------------------
+    rel_ids_by_source: dict[str, dict] = {}
+    for rels_name in [n for n in names if n.endswith(".rels")]:
+        try:
+            root = etree.fromstring(zf.read(rels_name))
+        except etree.XMLSyntaxError as exc:
+            _issue(issues, "error", "bad-rels-xml", f"{rels_name}: {exc}")
+            continue
+        source_part = ("" if rels_name == "_rels/.rels" else posixpath.normpath(
+            posixpath.join(posixpath.dirname(rels_name), "..",
+                           posixpath.basename(rels_name)[:-5])))
+        ids = {}
+        for rel in root.iter(f"{{{PR}}}Relationship"):
+            rid, target = rel.get("Id"), rel.get("Target", "")
+            mode = rel.get("TargetMode", "Internal")
+            ids[rid] = target
+            if mode == "External":
+                continue
+            resolved = _rel_target(source_part or "x", target)
+            if resolved not in names:
+                _issue(issues, "error", "dangling-rel",
+                       f"{rels_name}: {rid} -> {target} (missing part)")
+        rel_ids_by_source[source_part or "_package"] = ids
+
+    # --- r:id / r:embed references in document.xml -----------------------
+    doc_root = etree.fromstring(zf.read("word/document.xml"))
+    doc_rels = rel_ids_by_source.get("word/document.xml", {})
+    for el in doc_root.iter():
+        for attr in (f"{{{R}}}id", f"{{{R}}}embed", f"{{{R}}}link"):
+            rid = el.get(attr)
+            if rid and rid not in doc_rels:
+                _issue(issues, "error", "unresolved-reference",
+                       f"document.xml references {rid} with no relationship")
+
+    # --- embedded images decode ------------------------------------------
+    for name in [n for n in names if n.startswith("word/media/")]:
+        data = zf.read(name)
+        if not data:
+            _issue(issues, "error", "empty-image", name)
+        elif not any(data.startswith(m) for m in IMAGE_MAGIC):
+            _issue(issues, "warning", "unknown-image-format",
+                   f"{name}: unrecognized magic bytes")
+
+    # --- styles referenced exist ------------------------------------------
+    defined = set()
+    if "word/styles.xml" in names:
+        styles_root = etree.fromstring(zf.read("word/styles.xml"))
+        defined = {s.get(f"{{{W}}}styleId")
+                   for s in styles_root.iter(f"{{{W}}}style")}
+    for tag, attr in ((f"{{{W}}}pStyle", f"{{{W}}}val"),
+                      (f"{{{W}}}rStyle", f"{{{W}}}val"),
+                      (f"{{{W}}}tblStyle", f"{{{W}}}val")):
+        for el in doc_root.iter(tag):
+            sid = el.get(attr)
+            if sid and sid not in defined:
+                _issue(issues, "error", "missing-style",
+                       f"style id referenced but not defined: {sid}")
+
+    # --- python-docx can open it ------------------------------------------
+    try:
+        from docx import Document
+        Document(path)
+    except Exception as exc:  # noqa: BLE001 - triage tool, report anything
+        _issue(issues, "error", "python-docx-open-failed", str(exc))
+
+    ok = not any(i["severity"] == "error" for i in issues)
+    return {"ok": ok, "issues": issues}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="Health-check a .docx (not XSD schema validation).")
+    ap.add_argument("path", help="the .docx file to check")
+    args = ap.parse_args()
+    report = validate(args.path)
+    print(json.dumps(report, ensure_ascii=False))
+    return 0 if report["ok"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/built-in-skills/office-artifacts/references/docx/tests/test_docx_skill.py

@@ -0,0 +1,525 @@
+# MIT License. End-to-end tests for the docx skill.
+"""Pytest suite proving create / read / edit / template round-trips.
+
+Runs the scripts as subprocesses (argparse CLIs) and also verifies the
+outputs with python-docx directly. Stdlib + python-docx only; all
+fixtures are generated on the fly; no network.
+"""
+from __future__ import annotations
+
+import json
+import os
+import struct
+import subprocess
+import sys
+import zlib
+from pathlib import Path
+
+import pytest
+from docx import Document
+
+SKILL = Path(__file__).resolve().parent.parent
+SCRIPTS = SKILL / "scripts"
+
+NON_ASCII = "Фамилия — ‘test’"
+
+
+def make_png(path: Path) -> None:
+    """Write a tiny valid 2x2 red PNG using only stdlib."""
+    def chunk(tag: bytes, data: bytes) -> bytes:
+        return (struct.pack(">I", len(data)) + tag + data
+                + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF))
+
+    ihdr = struct.pack(">IIBBBBB", 2, 2, 8, 2, 0, 0, 0)
+    raw = b"".join(b"\x00" + b"\xff\x00\x00" * 2 for _ in range(2))
+    png = (b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", ihdr)
+           + chunk(b"IDAT", zlib.compress(raw)) + chunk(b"IEND", b""))
+    path.write_bytes(png)
+
+
+def run(script: str, *args: str) -> dict:
+    env = dict(os.environ)
+    env["LC_ALL"] = "C"  # prove no locale-default text reads
+    env["PYTHONIOENCODING"] = "utf-8"
+    proc = subprocess.run(
+        [sys.executable, str(SCRIPTS / script), *map(str, args)],
+        capture_output=True, env=env)
+    assert proc.returncode == 0, proc.stderr.decode("utf-8", "replace")
+    return json.loads(proc.stdout.decode("utf-8"))
+
+
+@pytest.fixture(scope="module")
+def workdir(tmp_path_factory) -> Path:
+    return tmp_path_factory.mktemp("docxskill")
+
+
+@pytest.fixture(scope="module")
+def created(workdir: Path) -> Path:
+    """Create a document exercising every create feature."""
+    png = workdir / "pic.png"
+    make_png(png)
+    spec = {
+        "page": {"width_mm": 210, "height_mm": 297,
+                 "margins_mm": {"top": 25, "bottom": 25,
+                                "left": 20, "right": 20}},
+        "header": "Report header",
+        "footer": "Page footer",
+        "styles": [{"name": "FancyNote", "base": "Normal", "font": "Arial",
+                    "size_pt": 11, "italic": True, "color": "1F4E79"}],
+        "blocks": [
+            {"type": "heading", "text": "Main Title", "level": 1},
+            {"type": "heading", "text": "Section One", "level": 2},
+            {"type": "paragraph", "runs": [
+                {"text": "plain "},
+                {"text": "boldbit", "bold": True},
+                {"text": " italicbit", "italic": True},
+                {"text": " underbit", "underline": True}]},
+            {"type": "paragraph", "text": "Styled note.",
+             "style": "FancyNote"},
+            {"type": "bullet_list", "items": ["alpha", "beta"]},
+            {"type": "numbered_list", "items": ["first", "second"]},
+            {"type": "table", "header": ["Name", "Qty"],
+             "rows": [["Widget", "3"], ["Gadget", "5"]],
+             "style": "Table Grid", "header_bold": True},
+            {"type": "image", "path": str(png), "width_mm": 30},
+            {"type": "page_break"},
+            {"type": "paragraph", "text": "After the break."},
+        ],
+    }
+    spec_path = workdir / "spec.json"
+    spec_path.write_text(json.dumps(spec), encoding="utf-8")
+    out = workdir / "created.docx"
+    res = run("docx_create.py", spec_path, out)
+    assert res["ok"] and out.exists()
+    return out
+
+
+class TestCreateAndRead:
+    def test_text_roundtrip(self, created: Path):
+        text = run("docx_read.py", created, "--text")
+        body = "\n".join(text["body"])
+        for expected in ("Main Title", "plain boldbit italicbit underbit",
+                         "Styled note.", "alpha", "second",
+                         "After the break."):
+            assert expected in body
+        assert text["tables"] == [[["Name", "Qty"], ["Widget", "3"],
+                                   ["Gadget", "5"]]]
+        assert "Report header" in text["headers"]
+        assert "Page footer" in text["footers"]
+
+    def test_structure(self, created: Path):
+        st = run("docx_read.py", created, "--structure")
+        outline = [(h["level"], h["text"]) for h in st["outline"]]
+        assert (1, "Main Title") in outline
+        assert (2, "Section One") in outline
+        assert st["table_count"] == 1
+        assert st["tables"][0] == {"rows": 3, "cols": 2}
+
+    def test_styles_used(self, created: Path):
+        styles = run("docx_read.py", created, "--styles")["styles"]
+        for s in ("Heading 1", "FancyNote", "List Bullet", "List Number",
+                  "Table Grid"):
+            assert s in styles
+
+    def test_images_extracted(self, created: Path, workdir: Path):
+        outdir = workdir / "media"
+        res = run("docx_read.py", created, "--images", outdir)
+        assert len(res["images"]) == 1
+        img = Path(res["images"][0])
+        assert img.read_bytes().startswith(b"\x89PNG")
+
+    def test_run_formatting_persisted(self, created: Path):
+        doc = Document(str(created))
+        para = next(p for p in doc.paragraphs if "boldbit" in p.text)
+        flags = {r.text.strip(): (r.bold, r.italic, r.underline)
+                 for r in para.runs if r.text.strip()}
+        assert flags["boldbit"][0] is True
+        assert flags["italicbit"][1] is True
+        assert flags["underbit"][2] is True
+
+    def test_page_setup(self, created: Path):
+        sec = Document(str(created)).sections[0]
+        assert round(sec.page_width.mm) == 210
+        assert round(sec.top_margin.mm) == 25
+
+    def test_revisions_detection(self, created: Path):
+        rev = run("docx_read.py", created, "--revisions")
+        assert rev["has_tracked_changes"] is False
+        assert rev["comments"] is False
+
+
+class TestEdit:
+    def test_replace_preserves_formatting(self, created: Path, workdir: Path):
+        out = workdir / "edited.docx"
+        res = run("docx_edit.py", "replace", created, "--find", "boldbit",
+                  "--replace", "REPLACED", "-o", out)
+        assert res["replacements"] == 1
+        doc = Document(str(out))
+        para = next(p for p in doc.paragraphs if "REPLACED" in p.text)
+        run_ = next(r for r in para.runs if "REPLACED" in r.text)
+        assert run_.bold is True  # formatting survived
+
+    def test_set_cell(self, created: Path, workdir: Path):
+        out = workdir / "cell.docx"
+        run("docx_edit.py", "set-cell", created, "--table", "0", "--row",
+            "1", "--col", "1", "--text", "99", "-o", out)
+        assert Document(str(out)).tables[0].cell(1, 1).text == "99"
+
+    def test_insert_and_delete(self, created: Path, workdir: Path):
+        out = workdir / "ins.docx"
+        run("docx_edit.py", "insert", created, "--index", "0", "--text",
+            "Inserted first", "-o", out)
+        doc = Document(str(out))
+        assert doc.paragraphs[0].text == "Inserted first"
+        out2 = workdir / "del.docx"
+        run("docx_edit.py", "delete", out, "--index", "0", "-o", out2)
+        assert Document(str(out2)).paragraphs[0].text != "Inserted first"
+
+    def test_apply_style(self, created: Path, workdir: Path):
+        out = workdir / "styled.docx"
+        doc = Document(str(created))
+        idx = next(i for i, p in enumerate(doc.paragraphs)
+                   if p.text == "After the break.")
+        run("docx_edit.py", "style", created, "--index", str(idx),
+            "--style", "Heading 2", "-o", out)
+        doc2 = Document(str(out))
+        assert doc2.paragraphs[idx].style.name == "Heading 2"
+
+
+class TestTemplate:
+    def test_fill_everywhere_non_ascii(self, workdir: Path):
+        # Build a template: tokens in body, split runs, table, header, footer.
+        tpl = workdir / "tpl.docx"
+        doc = Document()
+        doc.sections[0].header.paragraphs[0].text = "H: {{name}}"
+        doc.sections[0].footer.paragraphs[0].text = "F: {{date}}"
+        p = doc.add_paragraph()
+        p.add_run("Dear {{na")          # token split across runs
+        p.add_run("me}}, hello.")
+        t = doc.add_table(rows=1, cols=2)
+        t.cell(0, 0).text = "{{name}}"
+        t.cell(0, 1).text = "{{ date }}"   # spaced variant
+        doc.add_paragraph("Unfilled: {{missing}}")
+        doc.save(str(tpl))
+
+        values = workdir / "values.json"
+        values.write_text(
+            json.dumps({"name": NON_ASCII, "date": "2026-08-08"},
+                       ensure_ascii=False), encoding="utf-8")
+        out = workdir / "filled.docx"
+        res = run("docx_template.py", tpl, values, out)
+        assert res["ok"] is True
+        assert res["unfilled_tokens"] == ["missing"]
+
+        text = run("docx_read.py", out, "--text")
+        assert f"Dear {NON_ASCII}, hello." in text["body"]
+        assert text["tables"][0][0] == [NON_ASCII, "2026-08-08"]
+        assert f"H: {NON_ASCII}" in text["headers"]
+        assert "F: 2026-08-08" in text["footers"]
+
+    def test_strict_fails_on_unfilled(self, workdir: Path):
+        tpl = workdir / "tpl2.docx"
+        doc = Document()
+        doc.add_paragraph("{{gone}}")
+        doc.save(str(tpl))
+        values = workdir / "empty.json"
+        values.write_text("{}", encoding="utf-8")
+        env = dict(os.environ, LC_ALL="C", PYTHONIOENCODING="utf-8")
+        proc = subprocess.run(
+            [sys.executable, str(SCRIPTS / "docx_template.py"), str(tpl),
+             str(values), str(workdir / "out2.docx"), "--strict"],
+            capture_output=True, env=env)
+        assert proc.returncode == 1
+        payload = json.loads(proc.stdout.decode("utf-8"))
+        assert payload["unfilled_tokens"] == ["gone"]
+
+
+# --------------------------------------------------------------- new parity
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+
+def q(tag: str) -> str:
+    return f"{{{W}}}{tag}"
+
+
+def run_raw(script: str, *args: str):
+    env = dict(os.environ, LC_ALL="C", PYTHONIOENCODING="utf-8")
+    return subprocess.run(
+        [sys.executable, str(SCRIPTS / script), *map(str, args)],
+        capture_output=True, env=env)
+
+
+def _add_ins(para, rev_id: int, text: str, author="Editor"):
+    from lxml import etree
+    ins = etree.SubElement(para._p, q("ins"))
+    ins.set(q("id"), str(rev_id))
+    ins.set(q("author"), author)
+    ins.set(q("date"), "2026-01-02T03:04:05Z")
+    r = etree.SubElement(ins, q("r"))
+    t = etree.SubElement(r, q("t"))
+    t.text = text
+    t.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+
+
+def _add_del(para, rev_id: int, text: str, author="Editor"):
+    from lxml import etree
+    dele = etree.SubElement(para._p, q("del"))
+    dele.set(q("id"), str(rev_id))
+    dele.set(q("author"), author)
+    dele.set(q("date"), "2026-01-02T03:04:05Z")
+    r = etree.SubElement(dele, q("r"))
+    t = etree.SubElement(r, q("delText"))
+    t.text = text
+    t.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+
+
+@pytest.fixture()
+def tracked(tmp_path: Path) -> Path:
+    """Doc with a tracked insertion + deletion in body AND in a table."""
+    doc = Document()
+    p = doc.add_paragraph("Base ")
+    _add_ins(p, 1, "ADDED")
+    _add_del(p, 2, "REMOVED")
+    table = doc.add_table(rows=1, cols=1)
+    cp = table.cell(0, 0).paragraphs[0]
+    cp.add_run("Cell ")
+    _add_ins(cp, 3, "CELLADD")
+    _add_del(cp, 4, "CELLGONE")
+    path = tmp_path / "tracked.docx"
+    doc.save(str(path))
+    return path
+
+
+class TestRevisions:
+    def test_list(self, tracked: Path):
+        res = run("docx_revisions.py", "list", tracked)
+        revs = {r["id"]: r for r in res["revisions"]}
+        assert len(revs) == 4
+        assert revs["1"] == {"id": "1", "author": "Editor",
+                             "date": "2026-01-02T03:04:05Z",
+                             "type": "insertion", "text": "ADDED"}
+        assert revs["2"]["type"] == "deletion"
+        assert revs["2"]["text"] == "REMOVED"
+        assert revs["3"]["text"] == "CELLADD"  # inside table
+        assert revs["4"]["type"] == "deletion"
+
+    def test_accept_all(self, tracked: Path, tmp_path: Path):
+        out = tmp_path / "acc.docx"
+        res = run("docx_revisions.py", "accept-all", tracked, "-o", out)
+        assert res["resolved"] == 4
+        doc = Document(str(out))
+        assert doc.paragraphs[0].text == "Base ADDED"
+        assert doc.tables[0].cell(0, 0).text == "Cell CELLADD"
+        assert run("docx_revisions.py", "list", out)["revisions"] == []
+
+    def test_reject_all(self, tracked: Path, tmp_path: Path):
+        out = tmp_path / "rej.docx"
+        run("docx_revisions.py", "reject-all", tracked, "-o", out)
+        doc = Document(str(out))
+        assert doc.paragraphs[0].text == "Base REMOVED"
+        assert doc.tables[0].cell(0, 0).text == "Cell CELLGONE"
+
+    def test_accept_single_by_id(self, tracked: Path, tmp_path: Path):
+        out = tmp_path / "one.docx"
+        res = run("docx_revisions.py", "accept", tracked, "--id", "1",
+                  "-o", out)
+        assert res["resolved"] == 1
+        doc = Document(str(out))
+        assert doc.paragraphs[0].text == "Base ADDED"  # del 2 unresolved
+        remaining = run("docx_revisions.py", "list", out)["revisions"]
+        assert sorted(r["id"] for r in remaining) == ["2", "3", "4"]
+
+    def test_reject_single_by_id(self, tracked: Path, tmp_path: Path):
+        out = tmp_path / "rone.docx"
+        run("docx_revisions.py", "reject", tracked, "--id", "2", "-o", out)
+        doc = Document(str(out))
+        assert doc.paragraphs[0].text == "Base REMOVED"  # ins 1 unresolved
+
+    def test_unknown_id_fails(self, tracked: Path, tmp_path: Path):
+        proc = run_raw("docx_revisions.py", "accept", tracked, "--id",
+                       "999", "-o", tmp_path / "x.docx")
+        assert proc.returncode == 1
+
+
+class TestComments:
+    @pytest.fixture()
+    def base(self, tmp_path: Path) -> Path:
+        doc = Document()
+        doc.add_paragraph("The quarterly revenue rose sharply.")
+        doc.add_paragraph("Second paragraph.")
+        path = tmp_path / "base.docx"
+        doc.save(str(path))
+        return path
+
+    def test_add_list_delete(self, base: Path, tmp_path: Path):
+        out = tmp_path / "com.docx"
+        res = run("docx_comments.py", "add", base, "--target",
+                  "quarterly revenue", "--text", "Needs a source",
+                  "--author", "Reviewer", "--initials", "R", "-o", out)
+        assert res["ok"] is True
+        cid = res["comment_id"]
+
+        listed = run("docx_comments.py", "list", out)["comments"]
+        assert len(listed) == 1
+        c = listed[0]
+        assert c["id"] == cid
+        assert c["author"] == "Reviewer"
+        assert c["text"] == "Needs a source"
+        assert c["anchored_text"] == "quarterly revenue"
+        assert c["date"]
+
+        # document text unchanged by anchoring
+        text = run("docx_read.py", out, "--text")
+        assert "The quarterly revenue rose sharply." in text["body"]
+
+        out2 = tmp_path / "nocom.docx"
+        run("docx_comments.py", "delete", out, "--id", cid, "-o", out2)
+        assert run("docx_comments.py", "list", out2)["comments"] == []
+        text2 = run("docx_read.py", out2, "--text")
+        assert "The quarterly revenue rose sharply." in text2["body"]
+
+    def test_xml_fallback_path(self, base: Path, tmp_path: Path):
+        out = tmp_path / "xmlcom.docx"
+        res = run("docx_comments.py", "add", base, "--target",
+                  "Second paragraph", "--text", "fallback note",
+                  "--author", "Bot", "--xml", "-o", out)
+        assert res["native_api"] is False
+        listed = run("docx_comments.py", "list", out)["comments"]
+        assert listed[0]["text"] == "fallback note"
+        assert listed[0]["anchored_text"] == "Second paragraph"
+        # file still opens cleanly
+        assert Document(str(out)).paragraphs[1].text == "Second paragraph."
+
+    def test_missing_target_fails(self, base: Path, tmp_path: Path):
+        proc = run_raw("docx_comments.py", "add", base, "--target",
+                       "not present", "--text", "x", "-o",
+                       tmp_path / "y.docx")
+        assert proc.returncode == 1
+
+
+class TestValidate:
+    def test_healthy_file_passes(self, created: Path):
+        res = run("docx_validate.py", created)
+        assert res["ok"] is True
+        assert all(i["severity"] != "error" for i in res["issues"])
+
+    def test_not_a_zip(self, tmp_path: Path):
+        bad = tmp_path / "bad.docx"
+        bad.write_bytes(b"this is not a zip file")
+        proc = run_raw("docx_validate.py", bad)
+        assert proc.returncode == 1
+        rep = json.loads(proc.stdout.decode("utf-8"))
+        assert rep["issues"][0]["code"] == "not-a-zip"
+
+    def test_dangling_rel_and_empty_image(self, created: Path,
+                                          tmp_path: Path):
+        import shutil
+        import zipfile
+        broken = tmp_path / "broken.docx"
+        shutil.copy(created, broken)
+        # rebuild the zip: drop the image part, zero out nothing else
+        src = zipfile.ZipFile(str(created))
+        with zipfile.ZipFile(str(broken), "w") as dst:
+            for item in src.infolist():
+                if item.filename.startswith("word/media/"):
+                    dst.writestr(item.filename, b"")  # empty image
+                else:
+                    dst.writestr(item, src.read(item.filename))
+        proc = run_raw("docx_validate.py", broken)
+        assert proc.returncode == 1
+        rep = json.loads(proc.stdout.decode("utf-8"))
+        codes = {i["code"] for i in rep["issues"]}
+        assert "empty-image" in codes
+
+    def test_missing_style(self, tmp_path: Path):
+        import zipfile
+        doc = Document()
+        doc.add_paragraph("styled", style="Heading 1")
+        path = tmp_path / "styles.docx"
+        doc.save(str(path))
+        # rewrite document.xml to reference a style id that doesn't exist
+        src = zipfile.ZipFile(str(path))
+        broken = tmp_path / "badstyle.docx"
+        with zipfile.ZipFile(str(broken), "w") as dst:
+            for item in src.infolist():
+                data = src.read(item.filename)
+                if item.filename == "word/document.xml":
+                    data = data.replace(b'w:val="Heading1"',
+                                        b'w:val="GhostStyle"')
+                dst.writestr(item, data)
+        proc = run_raw("docx_validate.py", broken)
+        assert proc.returncode == 1
+        rep = json.loads(proc.stdout.decode("utf-8"))
+        assert any(i["code"] == "missing-style" and "GhostStyle"
+                   in i["detail"] for i in rep["issues"])
+
+
+class TestNormalize:
+    def test_merges_split_runs(self, tmp_path: Path):
+        doc = Document()
+        p = doc.add_paragraph()
+        p.add_run("Hel")            # identical (no) formatting, split
+        p.add_run("lo wo")
+        p.add_run("rld")
+        b = p.add_run("BOLD1")
+        b.bold = True
+        b2 = p.add_run("BOLD2")
+        b2.bold = True
+        i = p.add_run("ital")
+        i.italic = True
+        path = tmp_path / "split.docx"
+        doc.save(str(path))
+
+        out = tmp_path / "norm.docx"
+        res = run("docx_edit.py", "normalize", path, "-o", out)
+        assert res["runs_merged"] == 3  # 2 plain merges + 1 bold merge
+
+        doc2 = Document(str(out))
+        para = doc2.paragraphs[0]
+        assert para.text == "Hello worldBOLD1BOLD2ital"
+        assert [r.text for r in para.runs] == \
+            ["Hello world", "BOLD1BOLD2", "ital"]
+        assert para.runs[1].bold is True
+        assert para.runs[2].italic is True
+
+
+class TestFields:
+    def test_toc_and_page_numbers_via_edit(self, created: Path,
+                                           tmp_path: Path):
+        out = tmp_path / "fields.docx"
+        run("docx_edit.py", "toc", created, "--index", "0", "-o", out)
+        run("docx_edit.py", "page-numbers", out)
+
+        import zipfile
+        doc_xml = zipfile.ZipFile(str(out)).read(
+            "word/document.xml").decode("utf-8")
+        assert "TOC \\o" in doc_xml
+        assert "fldChar" in doc_xml
+        footer_names = [n for n in zipfile.ZipFile(str(out)).namelist()
+                        if n.startswith("word/footer")]
+        footers = "".join(zipfile.ZipFile(str(out)).read(n).decode("utf-8")
+                          for n in footer_names)
+        assert "PAGE" in footers and "NUMPAGES" in footers
+        # still a valid document
+        assert run("docx_validate.py", out)["ok"] is True
+
+    def test_toc_and_footer_in_create_spec(self, tmp_path: Path):
+        spec = {
+            "footer_page_numbers": True,
+            "blocks": [
+                {"type": "toc"},
+                {"type": "heading", "text": "Chapter", "level": 1},
+            ],
+        }
+        spec_path = tmp_path / "fspec.json"
+        spec_path.write_text(json.dumps(spec), encoding="utf-8")
+        out = tmp_path / "fcreate.docx"
+        run("docx_create.py", spec_path, out)
+
+        import zipfile
+        z = zipfile.ZipFile(str(out))
+        assert "TOC \\o" in z.read("word/document.xml").decode("utf-8")
+        footers = "".join(z.read(n).decode("utf-8") for n in z.namelist()
+                          if n.startswith("word/footer"))
+        assert "NUMPAGES" in footers