dsh-office-kit 0.1.0 → 0.3.0

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

@@ -0,0 +1,81 @@
+#!/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
+
+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,80 @@
+#!/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
+
+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,126 @@
+#!/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
+
+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,90 @@
+#!/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
+
+
+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,84 @@
+#!/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
+
+
+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())

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

@@ -0,0 +1,146 @@
+#!/usr/bin/env python
+"""Build deterministic internal navigation: a linked contents list and anchors.
+
+Word's TOC field needs a refresh before its links work.  This script instead
+writes static hyperlinks that any renderer follows: bookmarks on every heading,
+a contents list at the top (with quick links and back links), and optional
+Top/Bottom anchors.  Because the entries are literal text there is nothing to
+update before the file is read.
+
+Exit codes: 0 success, 1 no headings, 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
+
+TOP_BOOKMARK = "nav_top"
+BOTTOM_BOOKMARK = "nav_bottom"
+TOC_BOOKMARK = "nav_toc"
+
+
+def link_run(text: str, anchor: str):
+    link = etree.Element(kit.q("hyperlink"))
+    link.set(kit.q("anchor"), anchor)
+    link.append(kit.make_run(text))
+    return link
+
+
+def add_bookmark(paragraph, name: str, ident: int) -> None:
+    start = etree.Element(kit.q("bookmarkStart"))
+    start.set(kit.q("id"), str(ident))
+    start.set(kit.q("name"), name)
+    end = etree.Element(kit.q("bookmarkEnd"))
+    end.set(kit.q("id"), str(ident))
+    position = 1 if paragraph.find(kit.q("pPr")) is not None else 0
+    paragraph.insert(position, start)
+    paragraph.append(end)
+
+
+def paragraph(style: str | None = None):
+    node = etree.Element(kit.q("p"))
+    if style:
+        props = etree.SubElement(node, kit.q("pPr"))
+        etree.SubElement(props, kit.q("pStyle")).set(kit.q("val"), style)
+    return node
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Add bookmark anchors and static internal links to headings.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    parser.add_argument("--toc_title", default="Table of Contents")
+    parser.add_argument("--levels", nargs="+", type=int, default=[1, 2, 3], help="Heading levels to include")
+    parser.add_argument("--no_quicklinks", action="store_true", help="Skip the quick links bar")
+    parser.add_argument("--no_back_to_toc", action="store_true", help="Skip per-heading back links")
+    parser.add_argument("--no_top_bottom", action="store_true", help="Skip Top/Bottom anchors")
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.input_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    body = doc.body()
+    headings = []
+    ident = doc.next_id()
+    for paragraph_node in list(body.iter(kit.q("p"))):
+        level = kit.heading_level(paragraph_node)
+        text = kit.paragraph_text(paragraph_node).strip()
+        if level in args.levels and text:
+            name = "nav_h%d" % ident
+            add_bookmark(paragraph_node, name, ident)
+            headings.append({"level": level, "text": text, "anchor": name})
+            ident += 1
+
+    if not headings:
+        print("error: document has no headings at levels %s" % args.levels, file=sys.stderr)
+        return 1
+
+    first = body.find(kit.q("p"))
+    if first is None:
+        first = etree.SubElement(body, kit.q("p"))
+    position = body.index(first)
+
+    block = []
+    if not args.no_top_bottom:
+        top = paragraph()
+        add_bookmark(top, TOP_BOOKMARK, ident)
+        ident += 1
+        block.append(top)
+
+    title = paragraph("Heading1")
+    add_bookmark(title, TOC_BOOKMARK, ident)
+    ident += 1
+    title.append(kit.make_run(args.toc_title))
+    block.append(title)
+
+    if not args.no_quicklinks:
+        quick = paragraph()
+        quick.append(kit.make_run("Quick links: "))
+        for index, item in enumerate([entry for entry in headings if entry["level"] == 1] or headings):
+            if index:
+                quick.append(kit.make_run(" | "))
+            quick.append(link_run(item["text"], item["anchor"]))
+        block.append(quick)
+
+    for item in headings:
+        entry = paragraph("TOC%d" % item["level"] if item["level"] <= 3 else "TOC3")
+        props = entry.find(kit.q("pPr"))
+        ind = etree.SubElement(props, kit.q("ind"))
+        ind.set(kit.q("left"), str((item["level"] - 1) * 360))
+        entry.append(link_run(item["text"], item["anchor"]))
+        block.append(entry)
+
+    for offset, node in enumerate(block):
+        body.insert(position + offset, node)
+
+    if not args.no_back_to_toc:
+        for paragraph_node in list(body.iter(kit.q("p"))):
+            if any(entry["anchor"] == name for entry in headings for name in (paragraph_node.find(kit.q("bookmarkStart")).get(kit.q("name")),) if paragraph_node.find(kit.q("bookmarkStart")) is not None):
+                back = paragraph("Caption")
+                back.append(link_run("Back to contents", TOC_BOOKMARK))
+                paragraph_node.addnext(back)
+
+    if not args.no_top_bottom:
+        last = paragraph()
+        add_bookmark(last, BOTTOM_BOOKMARK, ident)
+        ident += 1
+        last.append(link_run("Back to top", TOP_BOOKMARK))
+        body.append(last)
+
+    doc.save(args.out)
+    kit.emit({"ok": True, "output": str(Path(args.out)), "headings": headings, "entries": len(block)})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())