dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/office-presentations/container_tools/inspect_presentation_package_integrity.py

@@ -0,0 +1,164 @@
+"""Check that a .pptx is a self-consistent package, not just a readable file.
+
+Purpose: python-pptx opens many broken decks happily. A half-written edit can
+leave a relationship pointing at a part that is not in the archive, a chart
+whose embedded workbook vanished, or a slide whose layout was never shipped.
+This walks the archive and reports what is actually there.
+
+Exit codes: 0 healthy, 1 problems found, 2 unreadable input.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import zipfile
+from pathlib import Path
+from xml.etree import ElementTree
+
+# 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
+
+REL_NS = "{http://schemas.openxmlformats.org/package/2006/relationships}"
+CT_NS = "{http://schemas.openxmlformats.org/package/2006/content-types}"
+P_NS = "{http://schemas.openxmlformats.org/presentationml/2006/main}"
+R_NS = "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}"
+
+
+def _rels_targets(archive: zipfile.ZipFile, part: str) -> list[str]:
+    folder, _, name = part.rpartition("/")
+    rels_name = f"{folder}/_rels/{name}.rels" if folder else f"_rels/{name}.rels"
+    if rels_name not in archive.namelist():
+        return []
+    try:
+        root = ElementTree.fromstring(archive.read(rels_name))
+    except ElementTree.ParseError:
+        return []
+    targets: list[str] = []
+    for relationship in root.findall(f"{REL_NS}Relationship"):
+        if relationship.get("TargetMode") == "External":
+            continue
+        target = relationship.get("Target", "")
+        if target.startswith("/"):
+            resolved = target.lstrip("/")
+        else:
+            resolved = f"{folder}/{target}" if folder else target
+        parts: list[str] = []
+        for segment in resolved.split("/"):
+            if segment in {"", "."}:
+                continue
+            if segment == "..":
+                if parts:
+                    parts.pop()
+                continue
+            parts.append(segment)
+        targets.append("/".join(parts))
+    return targets
+
+
+def inspect_package(pptx_path: str | Path) -> dict:
+    path = Path(pptx_path)
+    problems: list[dict] = []
+    if not path.is_file():
+        return {"gate": "package-integrity", "passed": False, "problems": [{"kind": "missing_file", "detail": str(path)}]}
+    if not zipfile.is_zipfile(path):
+        return {"gate": "package-integrity", "passed": False, "problems": [{"kind": "not_a_zip", "detail": "not a readable OOXML archive"}]}
+
+    with zipfile.ZipFile(path) as archive:
+        names = set(archive.namelist())
+        for required in ("[Content_Types].xml", "_rels/.rels", "ppt/presentation.xml"):
+            if required not in names:
+                problems.append({"kind": "missing_part", "part": required})
+
+        slides = sorted(name for name in names if name.startswith("ppt/slides/slide") and name.endswith(".xml"))
+        layouts = sorted(name for name in names if name.startswith("ppt/slideLayouts/slideLayout") and name.endswith(".xml"))
+        masters = sorted(name for name in names if name.startswith("ppt/slideMasters/slideMaster") and name.endswith(".xml"))
+        charts = sorted(name for name in names if name.startswith("ppt/charts/chart") and name.endswith(".xml"))
+        media = sorted(name for name in names if name.startswith("ppt/media/"))
+        embeddings = sorted(name for name in names if name.startswith("ppt/embeddings/"))
+
+        if not slides:
+            problems.append({"kind": "no_slides", "detail": "the package has no ppt/slides parts"})
+        if not masters:
+            problems.append({"kind": "no_master", "detail": "the package has no slide master"})
+
+        for part in slides + charts + layouts + masters:
+            for target in _rels_targets(archive, part):
+                if target and target not in names:
+                    problems.append({"kind": "dangling_relationship", "part": part, "target": target})
+
+        for part in slides:
+            try:
+                root = ElementTree.fromstring(archive.read(part))
+            except ElementTree.ParseError as exc:
+                problems.append({"kind": "unparsable_xml", "part": part, "detail": str(exc)})
+                continue
+            if root.tag != f"{P_NS}sld":
+                problems.append({"kind": "wrong_root_element", "part": part, "detail": root.tag})
+
+        presentation_xml = archive.read("ppt/presentation.xml") if "ppt/presentation.xml" in names else b""
+        declared_slides = 0
+        if presentation_xml:
+            try:
+                root = ElementTree.fromstring(presentation_xml)
+                slide_ids = root.find(f"{P_NS}sldIdLst")
+                declared_slides = len(list(slide_ids)) if slide_ids is not None else 0
+            except ElementTree.ParseError:
+                problems.append({"kind": "unparsable_xml", "part": "ppt/presentation.xml"})
+        if declared_slides and declared_slides != len(slides):
+            problems.append(
+                {
+                    "kind": "slide_count_mismatch",
+                    "detail": f"presentation.xml lists {declared_slides} slides but the package carries {len(slides)} parts",
+                }
+            )
+
+        duplicates = len(slides) - len({name.lower() for name in slides})
+        if duplicates:
+            problems.append({"kind": "duplicate_parts", "count": duplicates})
+
+        notes = [name for name in names if name.startswith("ppt/notesSlides/notesSlide") and name.endswith(".xml")]
+
+    return {
+        "gate": "package-integrity",
+        "presentation": str(path.resolve()),
+        "parts": {
+            "slides": len(slides),
+            "layouts": len(layouts),
+            "masters": len(masters),
+            "charts": len(charts),
+            "notesSlides": len(notes),
+            "media": len(media),
+            "embeddings": len(embeddings),
+        },
+        "problems": problems,
+        "passed": not problems,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Verify OOXML part/relationship integrity of a .pptx.")
+    parser.add_argument("presentation", nargs="?", help="path to the .pptx")
+    parser.add_argument("--input", dest="input_path", help="path to the .pptx (same as the positional)")
+    parser.add_argument("--json-out", help="also write the report here")
+    args = parser.parse_args(argv)
+    path = args.input_path or args.presentation
+    if not path:
+        parser.error("a .pptx path is required (positional or --input)")
+
+    report = inspect_package(path)
+    if args.json_out:
+        Path(args.json_out).write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-presentations/container_tools/native_chart_title_gate.py

@@ -0,0 +1,151 @@
+"""Decide whether every native chart carries a title the author meant to ship.
+
+Purpose: a chart with the literal "Chart Title" placeholder is an unfinished
+chart. PowerPoint will happily render it, so no render check catches it. This
+reads the chart parts and classifies each title, then fails only on the two
+states that mean "nobody decided here": a default placeholder and an empty
+title element.
+
+Statuses: absent, present, default_placeholder, linked_title_unresolved,
+explicitly_suppressed, empty_title.
+
+Exit codes: 0 pass, 1 fail, 2 unreadable input.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import zipfile
+from pathlib import Path
+from xml.etree import ElementTree
+
+# 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
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+C_NS = "{http://schemas.openxmlformats.org/drawingml/2006/chart}"
+A_NS = "{http://schemas.openxmlformats.org/drawingml/2006/main}"
+R_NS = "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}"
+
+DEFAULT_TITLE_STRINGS = ("chart title", "chart 1 title")
+BLOCKING = {"default_placeholder", "empty_title"}
+
+
+def _chart_title_status(chart_xml: bytes) -> tuple[str, str]:
+    root = ElementTree.fromstring(chart_xml)
+    chart = root.find(f"{C_NS}chart")
+    if chart is None:
+        return "absent", ""
+    deleted = chart.find(f"{C_NS}autoTitleDeleted")
+    suppressed = deleted is not None and deleted.get("val", "1") in {"1", "true"}
+    title = chart.find(f"{C_NS}title")
+    if title is None:
+        return ("explicitly_suppressed", "") if suppressed else ("absent", "")
+
+    if title.find(f"{C_NS}tx/{C_NS}strRef") is not None:
+        return "linked_title_unresolved", ""
+    rich = title.find(f"{C_NS}tx/{C_NS}rich")
+    if rich is None:
+        return "empty_title", ""
+    pieces = [node.text or "" for node in rich.iter(f"{A_NS}t")]
+    text = "".join(pieces).strip()
+    if not text:
+        return "empty_title", ""
+    if " ".join(text.split()).lower() in DEFAULT_TITLE_STRINGS:
+        return "default_placeholder", text
+    return "present", text
+
+
+def inspect_chart_titles(pptx_path: str | Path) -> dict:
+    path = Path(pptx_path)
+    if not path.is_file():
+        return {"gate": "native-chart-title", "passed": False, "findings": [{"kind": "missing_file", "detail": str(path)}]}
+
+    from pptx import Presentation
+
+    presentation = Presentation(str(path))
+    slides: list[dict] = []
+    checks: list[dict] = []
+    chart_parts: dict[str, bytes] = {}
+    with zipfile.ZipFile(path) as archive:
+        for name in archive.namelist():
+            if name.startswith("ppt/charts/") and name.endswith(".xml"):
+                chart_parts[name] = archive.read(name)
+
+    for slide_no, slide in enumerate(presentation.slides, start=1):
+        chart_count = 0
+        for shape in slide.shapes:
+            if not getattr(shape, "has_chart", False):
+                continue
+            chart_count += 1
+            part = shape.chart.part
+            part_name = str(part.partname).lstrip("/")
+            payload = chart_parts.get(part_name)
+            if payload is None:
+                checks.append({"slide": slide_no, "chart": shape.name, "part": part_name, "status": "part_missing", "title": ""})
+                continue
+            status, text = _chart_title_status(payload)
+            checks.append({"slide": slide_no, "chart": shape.name, "part": part_name, "status": status, "title": text})
+        slides.append({"slide": slide_no, "charts": chart_count})
+
+    unused = sorted(set(chart_parts) - {check["part"] for check in checks})
+    findings = [
+        {
+            "kind": "chart_title",
+            "severity": "fail",
+            "slide": check["slide"],
+            "chart": check["chart"],
+            "status": check["status"],
+            "message": (
+                "chart still shows the placeholder title"
+                if check["status"] == "default_placeholder"
+                else "chart has an empty title element"
+            ),
+        }
+        for check in checks
+        if check["status"] in BLOCKING
+    ]
+    for part in unused:
+        findings.append({"kind": "orphan_chart_part", "severity": "review", "part": part, "message": "chart part is not placed on any slide"})
+
+    return {
+        "gate": "native-chart-title",
+        "presentation": str(path.resolve()),
+        "slide_count": len(slides),
+        "native_chart_count": sum(item["charts"] for item in slides),
+        "checks": checks,
+        "findings": findings,
+        "native_powerpoint_verified": False,
+        "source_text_emitted": False,
+        "passed": not [item for item in findings if item["severity"] == "fail"],
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Fail when a native chart keeps a placeholder or empty title.")
+    parser.add_argument("presentation", nargs="?", help="path to the .pptx")
+    parser.add_argument("--input", dest="input_path", help="path to the .pptx (same as the positional)")
+    parser.add_argument("--json-out", help="also write the report here")
+    args = parser.parse_args(argv)
+    path = args.input_path or args.presentation
+    if not path:
+        parser.error("a .pptx path is required (positional or --input)")
+
+    report = inspect_chart_titles(path)
+    if args.json_out:
+        Path(args.json_out).write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-presentations/container_tools/native_quantitative_chart_gate.py

@@ -0,0 +1,206 @@
+"""Check that a quantitative chart is backed by real data, not just shapes.
+
+Purpose: a chart can look right and carry nothing editable — an empty cache, a
+series with no categories, points that exist as a count but not as values. This
+gate only governs slides the caller declares as quantitative (`--slide`), so a
+decorative series is not nagged.
+
+Two modes, ported from the original behaviour:
+  portable   (default) a durable embedded workbook must ship with the chart
+  powerpoint also accept a complete native literal cache (`c:numCache` with a
+             point count that matches the category count)
+
+Exit codes: 0 pass, 1 fail, 2 unreadable input.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import zipfile
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+from xml.etree import ElementTree
+
+# 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
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+C_NS = "{http://schemas.openxmlformats.org/drawingml/2006/chart}"
+R_NS = "{http://schemas.openxmlformats.org/package/2006/relationships}"
+
+
+def _embedded_workbooks(archive: zipfile.ZipFile, chart_part: str) -> list[str]:
+    folder, _, name = chart_part.rpartition("/")
+    rels = f"{folder}/_rels/{name}.rels"
+    if rels not in archive.namelist():
+        return []
+    try:
+        root = ElementTree.fromstring(archive.read(rels))
+    except ElementTree.ParseError:
+        return []
+    found: list[str] = []
+    for relationship in root.findall(f"{R_NS}Relationship"):
+        target = relationship.get("Target", "")
+        if target.endswith(".xlsx") or target.endswith(".xlsb"):
+            resolved = target.lstrip("/") if target.startswith("/") else f"{folder}/{target}"
+            parts: list[str] = []
+            for segment in resolved.split("/"):
+                if segment in {"", "."}:
+                    continue
+                if segment == "..":
+                    if parts:
+                        parts.pop()
+                    continue
+                parts.append(segment)
+            found.append("/".join(parts))
+    return found
+
+
+def _series_report(chart_xml: bytes) -> list[dict]:
+    root = ElementTree.fromstring(chart_xml)
+    report: list[dict] = []
+    for series in root.iter(f"{C_NS}ser"):
+        name_node = series.find(f"{C_NS}tx/{C_NS}strRef/{C_NS}strCache/{C_NS}pt/{C_NS}v")
+        if name_node is None:
+            name_node = series.find(f"{C_NS}tx/{C_NS}v")
+        categories = [node.text for node in series.findall(f"{C_NS}cat//{C_NS}pt/{C_NS}v")]
+        points = [node.text for node in series.findall(f"{C_NS}val//{C_NS}pt/{C_NS}v")]
+        if not points:
+            # some producers store values as c:v children of c:numCache without pt wrappers
+            points = [node.text for node in series.findall(f"{C_NS}val//{C_NS}v")]
+        numeric = 0
+        for value in points:
+            if value is None:
+                continue
+            try:
+                Decimal(str(value))
+                numeric += 1
+            except InvalidOperation:
+                continue
+        report.append(
+            {
+                "name": (name_node.text if name_node is not None else "") or "",
+                "categories": len(categories),
+                "points": len(points),
+                "numeric_points": numeric,
+            }
+        )
+    return report
+
+
+def inspect_charts(pptx_path: str | Path, declared_slides: list[int], mode: str = "portable") -> dict:
+    path = Path(pptx_path)
+    if not path.is_file():
+        return {"gate": "native-quantitative-chart", "passed": False, "findings": [{"kind": "missing_file", "detail": str(path)}]}
+
+    from pptx import Presentation
+
+    presentation = Presentation(str(path))
+    checks: list[dict] = []
+    findings: list[dict] = []
+    with zipfile.ZipFile(path) as archive:
+        names = set(archive.namelist())
+        for slide_no, slide in enumerate(presentation.slides, start=1):
+            if slide_no not in declared_slides:
+                continue
+            for shape in slide.shapes:
+                if not getattr(shape, "has_chart", False):
+                    continue
+                chart_part = str(shape.chart.part.partname).lstrip("/")
+                if chart_part not in names:
+                    findings.append({"kind": "chart_part_missing", "severity": "fail", "slide": slide_no, "part": chart_part})
+                    continue
+                payload = archive.read(chart_part)
+                workbooks = [item for item in _embedded_workbooks(archive, chart_part) if item in names]
+                series = _series_report(payload)
+                problems: list[str] = []
+                if not series:
+                    problems.append("the chart declares no series")
+                for entry in series:
+                    if entry["categories"] == 0:
+                        problems.append(f"series '{entry['name'] or '(unnamed)'}' has no categories")
+                    if entry["points"] == 0:
+                        problems.append(f"series '{entry['name'] or '(unnamed)'}' has no values")
+                    elif entry["numeric_points"] != entry["points"]:
+                        problems.append(
+                            f"series '{entry['name'] or '(unnamed)'}' has {entry['points'] - entry['numeric_points']} non-numeric value(s)"
+                        )
+                    elif entry["categories"] and entry["points"] and entry["categories"] != entry["points"]:
+                        problems.append(
+                            f"series '{entry['name'] or '(unnamed)'}' has {entry['categories']} categories but {entry['points']} values"
+                        )
+                has_cache = bool(series) and all(entry["points"] > 0 for entry in series)
+                if mode == "portable" and not workbooks:
+                    problems.append("no embedded workbook: the chart would not be editable after export")
+                if mode == "powerpoint" and not has_cache and not workbooks:
+                    problems.append("neither an embedded workbook nor a complete literal cache")
+                checks.append(
+                    {
+                        "slide": slide_no,
+                        "chart": shape.name,
+                        "part": chart_part,
+                        "mode": mode,
+                        "embedded_workbooks": workbooks,
+                        "series": series,
+                        "problems": problems,
+                    }
+                )
+                for problem in problems:
+                    findings.append(
+                        {
+                            "kind": "quantitative_chart",
+                            "severity": "fail",
+                            "slide": slide_no,
+                            "chart": shape.name,
+                            "message": problem,
+                        }
+                    )
+
+    return {
+        "gate": "native-quantitative-chart",
+        "presentation": str(path.resolve()),
+        "mode": mode,
+        "declared_slides": declared_slides,
+        "checks": checks,
+        "findings": findings,
+        "passed": not [item for item in findings if item["severity"] == "fail"],
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Require real, editable data behind charts on declared slides.")
+    parser.add_argument("presentation", nargs="?", help="path to the .pptx")
+    parser.add_argument("--input", dest="input_path", help="path to the .pptx (same as the positional)")
+    parser.add_argument("--slide", type=int, action="append", default=[], help="1-based slide to govern (repeatable)")
+    parser.add_argument("--all-slides", action="store_true", help="govern every slide that holds a chart")
+    parser.add_argument("--mode", choices=("portable", "powerpoint"), default="portable", help="acceptance mode (default portable)")
+    parser.add_argument("--json-out", help="also write the report here")
+    args = parser.parse_args(argv)
+    path = args.input_path or args.presentation
+    if not path:
+        parser.error("a .pptx path is required (positional or --input)")
+
+    declared = list(args.slide)
+    if args.all_slides or not declared:
+        from pptx import Presentation
+
+        presentation = Presentation(path)
+        declared = [index for index, slide in enumerate(presentation.slides, start=1) if any(getattr(shape, "has_chart", False) for shape in slide.shapes)]
+    report = inspect_charts(path, declared, args.mode)
+    if args.json_out:
+        Path(args.json_out).write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())