dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/office-documents/scripts/google_docs_title_sanitize.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python
+"""Undo the heading damage left by importing a document from a web editor.
+
+Imports commonly arrive with a run of empty paragraphs before the body starts and
+with the document title duplicated as a level-1 heading, which makes the outline
+read "My Doc" twice and pushes the real first section down.  The cleanup only
+touches the leading region, so a deliberate title page further in is untouched.
+
+Exit codes: 0 changed or nothing to change, 1 --check found problems, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def leading_region(body, limit: int) -> list:
+    seen = 0
+    region = []
+    for child in body:
+        if child.tag == kit.q("p") and kit.paragraph_text(child).strip():
+            seen += 1
+            if seen >= limit:
+                region.append(child)
+                break
+        region.append(child)
+    return region
+
+
+def sanitize(body, limit: int) -> dict:
+    removed_empty = 0
+    removed_duplicate = 0
+    region = leading_region(body, limit)
+    for paragraph in list(region):
+        if paragraph.tag != kit.q("p") or kit.paragraph_text(paragraph).strip():
+            continue
+        parent = paragraph.getparent()
+        if parent is not None:
+            parent.remove(paragraph)
+            removed_empty += 1
+
+    region = leading_region(body, limit)
+    for index, paragraph in enumerate(region):
+        if paragraph.tag != kit.q("p") or kit.paragraph_style(paragraph) != "Title":
+            continue
+        title = kit.paragraph_text(paragraph).strip()
+        for follower in region[index + 1 :]:
+            if follower.tag != kit.q("p"):
+                continue
+            text = kit.paragraph_text(follower).strip()
+            if not text:
+                continue
+            if text == title and kit.heading_level(follower) == 1:
+                body.remove(follower)
+                removed_duplicate += 1
+            break
+    return {"removed_empty": removed_empty, "removed_duplicate_heading": removed_duplicate}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Remove leading empty paragraphs and a duplicated title heading after import.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("--out", default=None, help="Output .docx")
+    parser.add_argument("--in-place", action="store_true", help="Rewrite the input file")
+    parser.add_argument("--check", action="store_true", help="Report only; exit 1 when cleanup is needed")
+    parser.add_argument("--leading-nonempty-paragraphs", type=int, default=3, help="How far into the document to look")
+    args = parser.parse_args(argv)
+
+    if not (args.out or args.in_place or args.check):
+        parser.error("choose --out, --in-place or --check")
+
+    try:
+        doc = kit.Docx(args.input_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    result = sanitize(doc.body(), max(1, args.leading_nonempty_paragraphs))
+    changed = bool(result["removed_empty"] or result["removed_duplicate_heading"])
+
+    output = None
+    if args.in_place or args.out:
+        output = args.out or args.input_docx
+        doc.save(output)
+
+    kit.emit({"ok": not (args.check and changed), "changed": changed, "check": args.check, "output": str(Path(output)) if output else None, **result})
+    return 1 if (args.check and changed) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/heading_audit.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python
+"""Audit the heading outline: skipped levels, empty headings, style escapes.
+
+A reader who meets "Heading 3" straight after "Heading 1" loses the document's
+shape, and a heading drawn with bold text instead of a heading style is invisible
+to the navigation pane, the TOC field and every outline tool.
+
+Exit codes: 0 clean, 1 findings, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+BOLD_LIKE = ("Heading", "Title")
+HEADING_SIZE_HALF_POINTS = 26  # 13pt: larger than any body style should be
+
+
+def manual_heading(paragraph) -> bool:
+    """True when bold, oversized runs stand in for a heading style."""
+    for run in paragraph.iter(kit.q("r")):
+        props = run.find(kit.q("rPr"))
+        if props is None or props.find(kit.q("b")) is None:
+            continue
+        size = props.find(kit.q("sz"))
+        if size is not None and (size.get(kit.q("val")) or "0").isdigit() and int(size.get(kit.q("val"))) >= HEADING_SIZE_HALF_POINTS:
+            return True
+    return False
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Report heading-level jumps, empty headings and manual heading formatting.")
+    parser.add_argument("docx", help="Input .docx")
+    parser.add_argument("--max_findings", type=int, default=50, help="Cap the reported findings")
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    findings = []
+    outline = []
+    previous = 0
+    for index, paragraph in enumerate(doc.paragraphs(), start=1):
+        text = kit.paragraph_text(paragraph).strip()
+        level = kit.heading_level(paragraph)
+        if level == 0:
+            outline.append({"index": index, "style": "Title", "text": text})
+            continue
+        if level:
+            if not text:
+                findings.append({"kind": "empty_heading", "index": index, "level": level})
+                continue
+            outline.append({"index": index, "level": level, "text": text})
+            if previous and level > previous + 1:
+                findings.append({"kind": "skipped_level", "index": index, "from": previous, "to": level, "text": text})
+            if manual_heading(paragraph):
+                findings.append({"kind": "manual_formatting", "index": index, "text": text})
+            previous = level
+        elif not text:
+            continue
+        elif manual_heading(paragraph) and len(text) <= 120:
+            findings.append({"kind": "heading_not_styled", "index": index, "text": text})
+
+    counts = {}
+    for finding in findings:
+        counts[finding["kind"]] = counts.get(finding["kind"], 0) + 1
+
+    kit.emit({"ok": not findings, "counts": counts, "headings": len(outline), "findings": findings[: args.max_findings], "truncated": max(0, len(findings) - args.max_findings)})
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/images_audit.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python
+"""Inventory images: where they come from, how big they are, and alt text.
+
+Alt text lives on ``wp:docPr`` (``descr`` preferred, ``title`` accepted).  Missing
+alt text is the accessibility defect readers hit first, and an oversized image is
+the layout defect authors hit first, so both are reported with the numbers that
+need changing.
+
+Exit codes: 0 clean, 1 findings, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+EMU_PER_INCH = 914400
+MAX_WIDTH_INCHES = 8.0
+
+
+def part_for(rel_id: str, rels: dict) -> str | None:
+    entry = rels.get(rel_id)
+    return entry["resolved"] if entry else None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="List inline images with size, source part and alt-text status.")
+    parser.add_argument("docx", help="Input .docx")
+    parser.add_argument("--max_rows", type=int, default=50)
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    rows = []
+    findings = []
+    for part in ["word/document.xml"] + doc.names("word/header") + doc.names("word/footer"):
+        if not doc.exists(part):
+            continue
+        rels = {entry["id"]: entry for entry in doc.relationships(part)}
+        for doc_pr in doc.xml(part).iter(kit.q("docPr", kit.WP)):
+            blip = doc_pr.getparent().find(".//" + kit.q("blip", kit.A))
+            embed = blip.get(kit.q("embed", kit.R)) if blip is not None else None
+            extent = doc_pr.getparent().find(".//" + kit.q("extent", kit.WP))
+            width = int(extent.get("cx")) / EMU_PER_INCH if extent is not None and extent.get("cx") else 0.0
+            height = int(extent.get("cy")) / EMU_PER_INCH if extent is not None and extent.get("cy") else 0.0
+            alt = doc_pr.get("descr") or doc_pr.get("title") or ""
+            row = {
+                "part": part,
+                "name": doc_pr.get("name"),
+                "source": part_for(embed, rels) if embed else None,
+                "width_in": round(width, 2),
+                "height_in": round(height, 2),
+                "alt": alt or None,
+            }
+            rows.append(row)
+            if not alt.strip():
+                findings.append({"kind": "missing_alt", "part": part, "name": row["name"], "source": row["source"]})
+            if width > MAX_WIDTH_INCHES:
+                findings.append({"kind": "oversized", "part": part, "name": row["name"], "width_in": row["width_in"]})
+
+    counts = {}
+    for finding in findings:
+        counts[finding["kind"]] = counts.get(finding["kind"], 0) + 1
+
+    kit.emit({"ok": not findings, "images": len(rows), "counts": counts, "rows": rows[: args.max_rows], "findings": findings[: args.max_rows]})
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/insert_note.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python
+"""Insert a real footnote or endnote at a text marker.
+
+Word stores notes outside the body: the paragraph keeps a small reference run
+and the note text goes in footnotes.xml/endnotes.xml.  This script creates that
+part when absent (including the required separator notes), allocates the next
+id, and replaces the marker run with the reference at the exact position.
+
+Exit codes: 0 success, 1 marker not found, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+PARTS = {"footnote": ("word/footnotes.xml", "footnotes", "footnote", kit.REL_FOOTNOTES), "endnote": ("word/endnotes.xml", "endnotes", "endnote", kit.REL_ENDNOTES)}
+
+
+def note_part(doc: kit.Docx, kind: str):
+    part, collection, item, rel_type = PARTS[kind]
+    if not doc.exists(part):
+        root = etree.Element(kit.q(collection), nsmap={"w": kit.W, "r": kit.R})
+        for ident, note_kind in ((-1, "separator"), (0, "continuationSeparator")):
+            note = etree.SubElement(root, kit.q(item))
+            note.set(kit.q("type"), note_kind)
+            note.set(kit.q("id"), str(ident))
+            paragraph = etree.SubElement(note, kit.q("p"))
+            run = etree.SubElement(paragraph, kit.q("r"))
+            etree.SubElement(run, kit.q(note_kind))
+        doc.set_xml(part, root)
+        doc.ensure_override(part, kit.CT_BY_REL[rel_type])
+        doc.ensure_rel("word/document.xml", rel_type, part.split("/")[-1])
+    return doc.xml(part), item
+
+
+def append_note(root, item: str, ident: int, text: str) -> None:
+    note = etree.SubElement(root, kit.q(item))
+    note.set(kit.q("id"), str(ident))
+    paragraph = etree.SubElement(note, kit.q("p"))
+    ppr = etree.SubElement(paragraph, kit.q("pPr"))
+    etree.SubElement(ppr, kit.q("pStyle")).set(kit.q("val"), "FootnoteText")
+    run = etree.SubElement(paragraph, kit.q("r"))
+    rpr = etree.SubElement(run, kit.q("rPr"))
+    etree.SubElement(rpr, kit.q("rStyle")).set(kit.q("val"), "FootnoteReference")
+    node = etree.SubElement(run, kit.q("t"))
+    node.text = text
+    node.set(kit.q("space"), "preserve")
+
+
+def reference_run(kind: str, ident: int):
+    run = etree.Element(kit.q("r"))
+    rpr = etree.SubElement(run, kit.q("rPr"))
+    etree.SubElement(rpr, kit.q("rStyle")).set(kit.q("val"), "FootnoteReference")
+    reference = etree.SubElement(run, kit.q(kind + "Reference"))
+    reference.set(kit.q("id"), str(ident))
+    return run
+
+
+def place_reference(paragraph, marker: str, kind: str, ident: int) -> bool:
+    for run in paragraph.iter(kit.q("r")):
+        text = "".join(node.text or "" for node in run.findall(kit.q("t")))
+        if marker not in text:
+            continue
+        before, after = text.split(marker, 1)
+        rpr = run.find(kit.q("rPr"))
+        parent = run.getparent()
+        position = parent.index(run)
+        parent.remove(run)
+        pieces = []
+        if before:
+            pieces.append(kit.make_run(before, etree.fromstring(etree.tostring(rpr)) if rpr is not None else None))
+        pieces.append(reference_run(kind, ident))
+        if after:
+            pieces.append(kit.make_run(after, etree.fromstring(etree.tostring(rpr)) if rpr is not None else None))
+        for offset, piece in enumerate(pieces):
+            parent.insert(position + offset, piece)
+        return True
+    return False
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Insert a true footnote or endnote at a [[NOTE]]-style marker.")
+    parser.add_argument("in_docx", help="Input .docx")
+    parser.add_argument("--kind", required=True, choices=["footnote", "endnote"])
+    parser.add_argument("--text", required=True, help="Note body")
+    parser.add_argument("--marker", default="[[NOTE]]", help="Text token that marks the anchor")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.in_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    target = None
+    for paragraph in doc.paragraphs():
+        if args.marker in "".join(node.text or "" for node in paragraph.iter(kit.q("t"))):
+            target = paragraph
+            break
+    if target is None:
+        print("error: marker %r not found" % args.marker, file=sys.stderr)
+        return 1
+
+    root, item = note_part(doc, args.kind)
+    existing = [int(node.get(kit.q("id")) or 0) for node in root.findall(kit.q(item))]
+    ident = max(existing + [0]) + 1
+    if not place_reference(target, args.marker, args.kind, ident):
+        print("error: could not split the marker run", file=sys.stderr)
+        return 1
+    append_note(root, item, ident, args.text)
+
+    doc.save(args.out)
+    kit.emit({"ok": True, "output": str(Path(args.out)), "kind": args.kind, "id": ident, "text": args.text})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/insert_ref_fields.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python
+"""Turn marker text such as ``[[REF:tbl1]]`` into real REF cross-reference fields.
+
+Markers keep the source text readable while drafting; this pass converts them to
+fields that Word resolves to the bookmark's caption or number.  The field is
+inserted at the marker position with an optional text prefix, and the paragraph
+is rebuilt with the formatting of its first run.
+
+Exit codes: 0 success (no markers means no change), 1 pattern has no 'bookmark'
+group, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def rebuild(paragraph, pattern: re.Pattern, prefix: str) -> int:
+    text = kit.paragraph_text(paragraph)
+    matches = list(pattern.finditer(text))
+    if not matches:
+        return 0
+    rpr = kit.first_rpr(paragraph)
+    pieces: list = []
+    cursor = 0
+    for match in matches:
+        if match.start() > cursor:
+            pieces.append(kit.make_run(text[cursor : match.start()], etree.fromstring(etree.tostring(rpr)) if rpr is not None else None))
+        bookmark = match.groupdict().get("bookmark") or ""
+        if prefix:
+            pieces.append(kit.make_run(prefix, etree.fromstring(etree.tostring(rpr)) if rpr is not None else None))
+        pieces.extend(kit.field_runs("REF %s \\h" % bookmark, "", etree.fromstring(etree.tostring(rpr)) if rpr is not None else None))
+        cursor = match.end()
+    if cursor < len(text):
+        pieces.append(kit.make_run(text[cursor:], etree.fromstring(etree.tostring(rpr)) if rpr is not None else None))
+    ppr = paragraph.find(kit.q("pPr"))
+    for child in list(paragraph):
+        if child is not ppr:
+            paragraph.remove(child)
+    for piece in pieces:
+        paragraph.append(piece)
+    return len(matches)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Replace [[REF:bookmark]] markers with REF cross-reference fields.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("output_docx", help="Output .docx")
+    parser.add_argument("--pattern", default=r"\[\[REF:(?P<bookmark>[A-Za-z0-9_:\-]+)\]\]", help="Regex for markers; must contain a 'bookmark' group")
+    parser.add_argument("--prefix", default="", help="Text inserted immediately before each field")
+    args = parser.parse_args(argv)
+
+    try:
+        pattern = re.compile(args.pattern)
+    except re.error as exc:
+        print("error: bad --pattern: %s" % exc, file=sys.stderr)
+        return 1
+    if "bookmark" not in pattern.groupindex:
+        print("error: --pattern needs a named group 'bookmark'", file=sys.stderr)
+        return 1
+
+    try:
+        doc = kit.Docx(args.input_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    replaced = 0
+    touched = 0
+    for paragraph in doc.paragraphs():
+        count = rebuild(paragraph, pattern, args.prefix)
+        if count:
+            replaced += count
+            touched += 1
+
+    doc.save(args.output_docx)
+    kit.emit({"ok": True, "output": str(Path(args.output_docx)), "fields": replaced, "paragraphs": touched})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/insert_toc.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python
+"""Replace a TOC placeholder with a real Word table-of-contents field.
+
+The field is the portable choice: Word rebuilds the entries, numbering and page
+numbers when it opens the file.  ``w:updateFields`` is set so that refresh
+happens without the user pressing F9.  A cached hint line is included as the
+field result so the area is not simply blank in renderers that ignore fields.
+
+Exit codes: 0 success, 1 placeholder not found, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def level_range(raw: str) -> str:
+    cleaned = raw.replace(" ", "")
+    if "-" in cleaned:
+        low, high = cleaned.split("-", 1)
+        if low.isdigit() and high.isdigit() and 1 <= int(low) <= int(high) <= 9:
+            return "%s-%s" % (low, high)
+    raise argparse.ArgumentTypeError("--levels must look like 1-3")
+
+
+def request_update(settings) -> None:
+    for node in settings.findall(kit.q("updateFields")):
+        settings.remove(node)
+    etree.SubElement(settings, kit.q("updateFields")).set(kit.q("val"), "true")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Insert a TOC field where a placeholder paragraph sits.")
+    parser.add_argument("docx", help="Input .docx")
+    parser.add_argument("--out", default=None, help="Output .docx (default: overwrite the input)")
+    parser.add_argument("--placeholder", default="[[TOC]]", help="Paragraph text token to replace")
+    parser.add_argument("--levels", default="1-3", help='Heading levels to include, e.g. "1-3"')
+    args = parser.parse_args(argv)
+
+    try:
+        levels = level_range(args.levels)
+    except argparse.ArgumentTypeError as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    try:
+        doc = kit.Docx(args.docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    target = None
+    for paragraph in doc.paragraphs():
+        if args.placeholder in kit.paragraph_text(paragraph):
+            target = paragraph
+            break
+    if target is None:
+        print("error: placeholder %r not found" % args.placeholder, file=sys.stderr)
+        return 1
+
+    parent = target.getparent()
+    position = parent.index(target)
+    root = etree.Element(kit.q("p"))
+    for run in kit.field_runs('#TOC \\o "%s" \\h \\z \\u' % levels, "Right-click and choose Update Field to build the contents."):
+        root.append(run)
+    parent.remove(target)
+    parent.insert(position, root)
+
+    request_update(doc.xml("word/settings.xml"))
+    out = args.out or args.docx
+    doc.save(out)
+    kit.emit({"ok": True, "output": str(Path(out)), "levels": levels, "paragraph_index": position})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())