dsh-office-kit 0.2.0 → 0.3.0

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

@@ -0,0 +1,144 @@
+"""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
+
+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,199 @@
+"""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
+
+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())

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

@@ -0,0 +1,212 @@
+"""Check that a table's declared totals actually add up.
+
+Purpose: a total row that does not match its column is the fastest way to lose
+a room. The rule that keeps this gate honest: it only enforces totals the
+author explicitly declares. Auto-discovered rows are reported as diagnostics,
+never failed, because "Total" can legitimately mean something else.
+
+Arithmetic is done with Decimal so 0.1 + 0.2 style inputs compare as written,
+and the tolerance comes from how many decimals the table displays.
+
+Contract file (`--contracts`):
+  {"contracts": [{"slide": 4, "table": 1, "total_row": 5, "columns": [1, 2], "tolerance": "0.01"}]}
+`table` is 1-based among tables on that slide; `total_row` is 0-based by default,
+switch to 1-based with `"row_base": 1` on the contract or `--row-base`.
+
+Exit codes: 0 pass, 1 fail, 2 unreadable input or bad contract.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+TOTAL_PATTERN = re.compile(r"\btotal\b", re.IGNORECASE)
+SUBTOTAL_PATTERN = re.compile(r"\bsub[\s-]?total\b", re.IGNORECASE)
+NON_ADDITIVE = re.compile(r"(unit\s*price|per\s*share|ratio|rate|%|percent|margin|average|avg|median)", re.IGNORECASE)
+NUMBER = re.compile(r"^[+-]?[0-9][0-9,]*(\.[0-9]+)?$")
+
+
+def _to_decimal(text: str) -> Decimal | None:
+    cleaned = text.strip().replace(",", "").replace("\u2212", "-")
+    if cleaned.startswith("(") and cleaned.endswith(")"):
+        cleaned = "-" + cleaned[1:-1]
+    cleaned = cleaned.replace("$", "").replace("\u20ac", "").replace("\u00a3", "").replace("%", "").strip()
+    if not NUMBER.match(cleaned):
+        return None
+    try:
+        return Decimal(cleaned)
+    except InvalidOperation:
+        return None
+
+
+def _decimals(text: str) -> int:
+    cleaned = text.strip().replace(",", "")
+    return len(cleaned.split(".")[1]) if "." in cleaned else 0
+
+
+def _tables(slide) -> list:
+    return [shape for shape in slide.shapes if getattr(shape, "has_table", False)]
+
+
+def check(presentation_path: str | Path, contracts: list[dict], row_base: int = 0) -> dict:
+    path = Path(presentation_path)
+    if not path.is_file():
+        return {"gate": "table-arithmetic", "passed": False, "findings": [{"kind": "missing_file", "detail": str(path)}]}
+
+    from pptx import Presentation
+
+    presentation = Presentation(str(path))
+    slides = list(presentation.slides)
+    findings: list[dict] = []
+    checks: list[dict] = []
+    declared: set[tuple[int, int]] = set()
+
+    for contract in contracts:
+        slide_no = int(contract["slide"])
+        table_index = int(contract.get("table", 1)) - 1
+        base = int(contract.get("row_base", row_base))
+        if not 1 <= slide_no <= len(slides):
+            findings.append({"kind": "bad_contract", "severity": "fail", "message": f"slide {slide_no} is out of range"})
+            continue
+        tables = _tables(slides[slide_no - 1])
+        if not 1 <= table_index + 1 <= len(tables):
+            findings.append({"kind": "bad_contract", "severity": "fail", "slide": slide_no, "message": f"table {table_index + 1} not found"})
+            continue
+        table = tables[table_index].table
+        declared.add((slide_no, table_index))
+        total_row = int(contract["total_row"]) - 1 if base == 1 else int(contract["total_row"])
+        rows = list(table.rows)
+        if not 0 <= total_row < len(rows):
+            findings.append({"kind": "bad_contract", "severity": "fail", "slide": slide_no, "message": f"total row {total_row} is out of range"})
+            continue
+        tolerance = Decimal(str(contract.get("tolerance", "0.01")))
+        columns = [int(item) for item in contract.get("columns", range(1, len(table.columns)))]
+        header = [cell.text for cell in rows[0].cells] if rows else []
+
+        for column in columns:
+            if not 0 <= column < len(table.columns):
+                findings.append({"kind": "bad_contract", "severity": "fail", "slide": slide_no, "message": f"column {column} is out of range"})
+                continue
+            header_text = header[column] if column < len(header) else ""
+            if NON_ADDITIVE.search(header_text):
+                checks.append({"slide": slide_no, "column": column, "header": header_text, "status": "skipped_non_additive"})
+                continue
+            displayed_text = rows[total_row].cells[column].text
+            displayed = _to_decimal(displayed_text)
+            if displayed is None:
+                findings.append(
+                    {
+                        "kind": "unparseable_total",
+                        "severity": "fail",
+                        "slide": slide_no,
+                        "column": column,
+                        "header": header_text,
+                        "displayed": displayed_text,
+                        "message": "the declared total cell is not a number this gate can read",
+                    }
+                )
+                continue
+            addends: list[Decimal] = []
+            for row in rows[1:total_row]:
+                value = _to_decimal(row.cells[column].text)
+                if value is not None:
+                    addends.append(value)
+            computed = sum(addends, Decimal(0))
+            unit = Decimal(1).scaleb(-max([_decimals(displayed_text)] + [_decimals(rows[index].cells[column].text) for index in range(1, total_row)] or [0]))
+            delta = abs(computed - displayed)
+            rounding_slack = max(tolerance, unit / 2)
+            passed = delta <= rounding_slack
+            checks.append(
+                {
+                    "slide": slide_no,
+                    "column": column,
+                    "header": header_text,
+                    "status": "pass" if passed else "mismatch",
+                    "displayed": str(displayed),
+                    "computed": str(computed),
+                    "delta": str(delta),
+                    "rounding_slack": str(rounding_slack),
+                    "addends": [str(item) for item in addends],
+                }
+            )
+            if not passed:
+                findings.append(
+                    {
+                        "kind": "total_mismatch",
+                        "severity": "fail",
+                        "slide": slide_no,
+                        "column": column,
+                        "header": header_text,
+                        "displayed": str(displayed),
+                        "computed": str(computed),
+                        "message": f"column '{header_text or column}' totals {computed} but displays {displayed}",
+                    }
+                )
+
+    # diagnostics only: never fail on a row we were not told to enforce
+    for slide_no, slide in enumerate(slides, start=1):
+        for table_index, shape in enumerate(_tables(slide)):
+            if (slide_no, table_index) in declared:
+                continue
+            rows = list(shape.table.rows)
+            for row_index, row in enumerate(rows):
+                first = row.cells[0].text.strip()
+                if TOTAL_PATTERN.search(first) or SUBTOTAL_PATTERN.search(first):
+                    findings.append(
+                        {
+                            "kind": "auto_detected_total",
+                            "severity": "diagnostic",
+                            "slide": slide_no,
+                            "row": row_index,
+                            "label": first,
+                            "message": "total-looking row is not declared in a contract, so it was not enforced",
+                        }
+                    )
+
+    return {
+        "gate": "table-arithmetic",
+        "presentation": str(path.resolve()),
+        "contracts": len(contracts),
+        "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="Verify declared table totals against their columns.")
+    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("--contracts", required=True, help="JSON file listing the totals to enforce")
+    parser.add_argument("--row-base", type=int, choices=(0, 1), default=0, help="0-based row indices (default) or 1-based")
+    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)")
+
+    try:
+        payload = json.loads(Path(args.contracts).read_text(encoding="utf-8"))
+    except Exception as exc:  # noqa: BLE001 - any parse problem is the caller's contract
+        json.dump({"gate": "table-arithmetic", "passed": False, "error": {"code": "bad_contracts", "message": str(exc)}}, sys.stdout)
+        sys.stdout.write("\n")
+        return 2
+    contracts = payload.get("contracts", payload if isinstance(payload, list) else [])
+    report = check(path, contracts, args.row_base)
+    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())