pptlint 0.3.1__py3-none-any.whl

decklint/__init__.py

@@ -0,0 +1,3 @@
+"""PPTLint core package with DeckLint compatibility imports."""
+
+__version__ = "0.3.1"

decklint/__main__.py

@@ -0,0 +1,4 @@
+from .compat import main
+
+
+raise SystemExit(main())

decklint/cli.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .comparison import ComparisonError, load_audit_report
+from .comparison_report import build_comparison_report, write_comparison_reports
+from .model import DeckLoadError, load_deck
+from .render import RenderError, render_deck
+from .report import build_report, write_reports
+from .rules import audit_deck
+from .scoring import score_findings
+
+
+SEVERITY_RANK = {"low": 1, "medium": 2, "high": 3, "critical": 4}
+
+
+def _score_value(value: str) -> int:
+    score = int(value)
+    if not 0 <= score <= 100:
+        raise argparse.ArgumentTypeError("score must be between 0 and 100")
+    return score
+
+
+def _add_check_arguments(command: argparse.ArgumentParser, *, output: str, fail_on: str) -> None:
+    command.add_argument("input", type=Path, help="PPTX file to check")
+    command.add_argument("--output", type=Path, default=Path(output), help="Report filename prefix")
+    command.add_argument("--profile", choices=("baseline", "ai-generated"), default="baseline")
+    command.add_argument("--renderer", choices=("auto", "wireframe", "libreoffice"), default="auto")
+    command.add_argument("--soffice-path", help="Optional path to the LibreOffice soffice executable")
+    command.add_argument("--fail-on", choices=("none", "low", "medium", "high", "critical"), default=fail_on)
+    command.add_argument("--min-score", type=_score_value, default=None)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pptlint", description="Preflight checks for AI-generated PowerPoint files."
+    )
+    subcommands = parser.add_subparsers(dest="command", required=True)
+    check = subcommands.add_parser("check", help="Check whether a PPTX is ready to deliver.")
+    _add_check_arguments(check, output="pptlint-report", fail_on="none")
+    audit = subcommands.add_parser("audit", help="Audit a PPTX and write offline HTML and JSON reports.")
+    _add_check_arguments(audit, output="decklint-report", fail_on="high")
+    compare = subcommands.add_parser("compare", help="Compare two DeckLint audit reports.")
+    compare.add_argument("before", type=Path, help="Before audit JSON report")
+    compare.add_argument("after", type=Path, help="After audit JSON report")
+    compare.add_argument(
+        "--output",
+        type=Path,
+        default=Path("decklint-comparison"),
+        help="Comparison report filename prefix",
+    )
+    compare.add_argument(
+        "--fail-on-regression",
+        choices=("none", "low", "medium", "high", "critical"),
+        default="high",
+    )
+    return parser
+
+
+def _threshold_failed(findings, threshold: str) -> bool:
+    if threshold == "none":
+        return False
+    threshold_rank = SEVERITY_RANK[threshold]
+    return any(
+        finding.confidence == "high" and SEVERITY_RANK[finding.severity] >= threshold_rank
+        for finding in findings
+    )
+
+
+def _run_audit(args: argparse.Namespace) -> int:
+    try:
+        deck = load_deck(args.input.expanduser())
+        findings = audit_deck(deck, profile=args.profile)
+        scores = score_findings(findings)
+        rendering = render_deck(
+            deck,
+            source=args.input.expanduser(),
+            renderer=args.renderer,
+            soffice_path=args.soffice_path,
+        )
+        report = build_report(deck, findings, scores, rendering, profile=args.profile)
+        html_path, json_path = write_reports(args.output.expanduser(), report)
+    except (DeckLoadError, RenderError, OSError, ValueError) as exc:
+        print(f"PPTLint could not check the file: {exc}", file=sys.stderr)
+        return 2
+
+    status = report["readiness"]["status"]
+    result_label = {
+        "ready": "Ready to send",
+        "review": "Check before sending",
+        "blocked": "Fix before sending",
+    }[status]
+    print(f"PPTLint result: {result_label}")
+    actions = report["priorityActions"]
+    if actions:
+        print("Next actions:")
+        for action in actions:
+            slide = action.get("slideIndex")
+            location = f"Slide {slide}" if slide else "Whole file"
+            print(f"- {location}: {action['impact']}")
+    else:
+        print("No high-confidence delivery problem was found.")
+    print(f"Open the HTML report for the highlighted slides: {html_path}")
+    print(f"JSON report: {json_path}")
+    failed = _threshold_failed(findings, args.fail_on)
+    if args.command == "check" and report["readiness"]["status"] == "blocked":
+        failed = True
+    if args.min_score is not None and scores.overall < args.min_score:
+        failed = True
+    return 1 if failed else 0
+
+
+def _run_compare(args: argparse.Namespace) -> int:
+    try:
+        before = load_audit_report(args.before.expanduser())
+        after = load_audit_report(args.after.expanduser())
+        report = build_comparison_report(
+            before,
+            after,
+            threshold=args.fail_on_regression,
+        )
+        html_path, json_path = write_comparison_reports(args.output.expanduser(), report)
+    except (ComparisonError, OSError, ValueError) as exc:
+        print(f"DeckLint could not compare the reports: {exc}", file=sys.stderr)
+        return 2
+
+    overall = report["scores"]["overall"]
+    print(f"PPTLint comparison {overall['before']} -> {overall['after']} ({overall['delta']:+d})")
+    print(f"HTML report: {html_path}")
+    print(f"JSON report: {json_path}")
+    return 0 if report["gate"]["passed"] else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "compare":
+        return _run_compare(args)
+    return _run_audit(args)

decklint/comparison.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+
+
+MAX_REPORT_BYTES = 100 * 1024 * 1024
+SEVERITY_RANK = {"low": 1, "medium": 2, "high": 3, "critical": 4}
+COMPARISON_FINDING_FIELDS = (
+    "id",
+    "rule_id",
+    "category",
+    "severity",
+    "confidence",
+    "message",
+    "evidence",
+    "remediation",
+    "slide_index",
+    "shape_id",
+    "bbox",
+)
+
+
+class ComparisonError(ValueError):
+    """Raised when audit reports cannot be compared safely."""
+
+
+@dataclass(frozen=True)
+class FindingMatch:
+    resolved: list[dict[str, object]]
+    persistent: list[dict[str, object]]
+    new: list[dict[str, object]]
+
+
+def _group_key(item: dict[str, object]) -> tuple[str, int]:
+    return (str(item.get("rule_id", "")), int(item.get("slide_index") or 0))
+
+
+def _sort_key(item: dict[str, object]) -> tuple[object, ...]:
+    candidate = item.get("bbox")
+    bbox = candidate if isinstance(candidate, dict) else {}
+    return (
+        float(bbox.get("x", 0)),
+        float(bbox.get("y", 0)),
+        float(bbox.get("w", 0)),
+        float(bbox.get("h", 0)),
+        str(item.get("shape_id") or ""),
+        str(item.get("evidence", "")),
+        str(item.get("id", "")),
+    )
+
+
+def match_findings(
+    before: list[dict[str, object]],
+    after: list[dict[str, object]],
+) -> FindingMatch:
+    grouped_before: dict[tuple[str, int], list[dict[str, object]]] = defaultdict(list)
+    grouped_after: dict[tuple[str, int], list[dict[str, object]]] = defaultdict(list)
+    for item in before:
+        grouped_before[_group_key(item)].append(item)
+    for item in after:
+        grouped_after[_group_key(item)].append(item)
+
+    resolved: list[dict[str, object]] = []
+    persistent: list[dict[str, object]] = []
+    new: list[dict[str, object]] = []
+    for key in sorted(set(grouped_before) | set(grouped_after)):
+        left = sorted(grouped_before[key], key=_sort_key)
+        right = sorted(grouped_after[key], key=_sort_key)
+        paired = min(len(left), len(right))
+        persistent.extend({"before": left[index], "after": right[index]} for index in range(paired))
+        resolved.extend(left[paired:])
+        new.extend(right[paired:])
+    return FindingMatch(resolved=resolved, persistent=persistent, new=new)
+
+
+def _dict_field(container: dict[str, object], key: str) -> dict[str, object]:
+    value = container.get(key)
+    if not isinstance(value, dict):
+        raise ComparisonError(f"Audit report field must be an object: {key}")
+    return value
+
+
+def _list_field(container: dict[str, object], key: str) -> list[dict[str, object]]:
+    value = container.get(key)
+    if not isinstance(value, list) or not all(isinstance(item, dict) for item in value):
+        raise ComparisonError(f"Audit report field must be an object array: {key}")
+    return value
+
+
+def _comparison_finding(item: dict[str, object]) -> dict[str, object]:
+    """Keep the stable v1 comparison shape when reading richer v2 reports."""
+    return {field: item.get(field) for field in COMPARISON_FINDING_FIELDS}
+
+
+def _delta_map(
+    before: dict[str, object],
+    after: dict[str, object],
+) -> dict[str, dict[str, int]]:
+    return {
+        key: {
+            "before": int(before.get(key, 0)),
+            "after": int(after.get(key, 0)),
+            "delta": int(after.get(key, 0)) - int(before.get(key, 0)),
+        }
+        for key in sorted(set(before) | set(after))
+    }
+
+
+def compare_reports(
+    before: dict[str, object],
+    after: dict[str, object],
+    *,
+    threshold: str = "high",
+) -> dict[str, object]:
+    if threshold not in {"none", *SEVERITY_RANK}:
+        raise ComparisonError(f"Unsupported regression threshold: {threshold}")
+    before_findings = [_comparison_finding(item) for item in _list_field(before, "findings")]
+    after_findings = [_comparison_finding(item) for item in _list_field(after, "findings")]
+    matches = match_findings(before_findings, after_findings)
+    before_scores = _dict_field(before, "scores")
+    after_scores = _dict_field(after, "scores")
+    score_before = int(before_scores.get("overall", 0))
+    score_after = int(after_scores.get("overall", 0))
+    reasons: list[str] = []
+    if threshold != "none" and score_after < score_before:
+        reasons.append("overall-score-decreased")
+    if threshold != "none":
+        threshold_rank = SEVERITY_RANK[threshold]
+        if any(
+            item.get("confidence") == "high"
+            and SEVERITY_RANK.get(str(item.get("severity")), 0) >= threshold_rank
+            for item in matches.new
+        ):
+            reasons.append("new-high-confidence-finding")
+    return {
+        "schemaVersion": "decklint-comparison/v1",
+        "scores": {
+            "overall": {
+                "before": score_before,
+                "after": score_after,
+                "delta": score_after - score_before,
+            },
+            "categories": _delta_map(
+                _dict_field(before_scores, "categories"),
+                _dict_field(after_scores, "categories"),
+            ),
+        },
+        "severity": _delta_map(
+            _dict_field(before, "summary"),
+            _dict_field(after, "summary"),
+        ),
+        "resolved": matches.resolved,
+        "persistent": matches.persistent,
+        "new": matches.new,
+        "gate": {
+            "threshold": threshold,
+            "passed": not reasons,
+            "failureReasons": reasons,
+        },
+    }
+
+
+def load_audit_report(path: Path) -> dict[str, object]:
+    path = Path(path)
+    if not path.is_file():
+        raise ComparisonError(f"Audit report not found: {path.name}")
+    if path.stat().st_size > MAX_REPORT_BYTES:
+        raise ComparisonError("Audit report exceeds the 100 MiB safety limit")
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise ComparisonError(f"Invalid audit report JSON: {path.name}") from exc
+    if not isinstance(payload, dict):
+        raise ComparisonError("Audit report root must be a JSON object")
+    if payload.get("schemaVersion") not in {"decklint-report/v1", "pptlint-report/v2"}:
+        raise ComparisonError("Audit report must use decklint-report/v1 or pptlint-report/v2")
+    for key in (
+        "file",
+        "scores",
+        "summary",
+        "findings",
+        "slides",
+        "profile",
+        "renderer",
+    ):
+        if key not in payload:
+            raise ComparisonError(f"Audit report is missing required field: {key}")
+    return payload

decklint/comparison_report.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import html
+import json
+from pathlib import Path
+
+from . import __version__
+from .comparison import ComparisonError, compare_reports
+
+
+def _object(container: dict[str, object], key: str) -> dict[str, object]:
+    value = container.get(key)
+    if not isinstance(value, dict):
+        raise ComparisonError(f"Audit report field must be an object: {key}")
+    return value
+
+
+def _identity(report: dict[str, object]) -> dict[str, object]:
+    file_info = _object(report, "file")
+    renderer = _object(report, "renderer")
+    return {
+        "sourceSchema": str(report.get("schemaVersion", "")),
+        "profile": str(report.get("profile", "")),
+        "file": {
+            "name": str(file_info.get("name", "")),
+            "sha256": str(file_info.get("sha256", "")),
+            "slides": int(file_info.get("slides", 0)),
+        },
+        "renderer": {
+            "requested": str(renderer.get("requested", "")),
+            "used": str(renderer.get("used", "")),
+            "status": str(renderer.get("status", "")),
+            "detail": str(renderer.get("detail", "")),
+        },
+    }
+
+
+def _slide_map(report: dict[str, object]) -> dict[int, dict[str, object]]:
+    slides = report.get("slides")
+    if not isinstance(slides, list):
+        raise ComparisonError("Audit report field must be an array: slides")
+    mapped: dict[int, dict[str, object]] = {}
+    for item in slides:
+        if not isinstance(item, dict):
+            raise ComparisonError("Audit report slides must contain objects")
+        index = int(item.get("index", 0))
+        if index <= 0 or index in mapped:
+            raise ComparisonError("Audit report slide indices must be unique positive integers")
+        mapped[index] = {
+            "index": index,
+            "title": str(item.get("title", "")),
+            "titleSource": str(item.get("titleSource", "none")),
+            "preview": str(item.get("preview", "")),
+        }
+    return mapped
+
+
+def _pair_slides(
+    before: dict[str, object],
+    after: dict[str, object],
+) -> list[dict[str, object]]:
+    before_slides = _slide_map(before)
+    after_slides = _slide_map(after)
+    return [
+        {
+            "index": index,
+            "before": before_slides.get(index),
+            "after": after_slides.get(index),
+        }
+        for index in sorted(set(before_slides) | set(after_slides))
+    ]
+
+
+def _agent_summary(core: dict[str, object]) -> str:
+    scores = _object(core, "scores")
+    overall = _object(scores, "overall")
+    gate = _object(core, "gate")
+    status = "通过" if gate.get("passed") else "未通过"
+    return (
+        f"比较门禁{status}；总分从 {overall['before']} 变为 {overall['after']}"
+        f"（变化 {int(overall['delta']):+d}）；已解决 {len(core['resolved'])} 项，"
+        f"持续存在 {len(core['persistent'])} 项，新增 {len(core['new'])} 项。"
+    )
+
+
+def build_comparison_report(
+    before: dict[str, object],
+    after: dict[str, object],
+    *,
+    threshold: str,
+) -> dict[str, object]:
+    core = compare_reports(before, after, threshold=threshold)
+    return {
+        "schemaVersion": "decklint-comparison/v1",
+        "toolVersion": __version__,
+        "before": _identity(before),
+        "after": _identity(after),
+        "scores": core["scores"],
+        "severity": core["severity"],
+        "resolved": core["resolved"],
+        "persistent": core["persistent"],
+        "new": core["new"],
+        "gate": core["gate"],
+        "slides": _pair_slides(before, after),
+        "agentSummary": _agent_summary(core),
+    }
+
+
+def _escape(value: object) -> str:
+    return html.escape(str(value), quote=True)
+
+
+def _finding_list(title: str, items: list[dict[str, object]], css_class: str) -> str:
+    rendered = "".join(
+        "<li>"
+        f"<code>{_escape(item.get('rule_id', ''))}</code>"
+        f"<strong>第 {_escape(item.get('slide_index') or '—')} 页</strong>"
+        f"<span>{_escape(item.get('message', ''))}</span>"
+        "</li>"
+        for item in items
+    )
+    if not rendered:
+        rendered = "<li class=empty>无</li>"
+    return (
+        f'<section class="finding-group {css_class}"><h2>{_escape(title)}</h2><ul>{rendered}</ul></section>'
+    )
+
+
+def _render_comparison_html(report: dict[str, object]) -> str:
+    before = _object(report, "before")
+    after = _object(report, "after")
+    before_file = _object(before, "file")
+    after_file = _object(after, "file")
+    scores = _object(report, "scores")
+    overall = _object(scores, "overall")
+    categories = _object(scores, "categories")
+    gate = _object(report, "gate")
+    category_names = {
+        "integrity": "完整性",
+        "readability": "可读性",
+        "editability": "可编辑性",
+        "consistency": "一致性",
+        "accessibility": "无障碍",
+    }
+    score_cards = "".join(
+        f"<article><span>{_escape(category_names.get(name, name))}</span>"
+        f"<b>{_escape(change['before'])} → {_escape(change['after'])}</b>"
+        f"<em>{int(change['delta']):+d}</em></article>"
+        for name, change in categories.items()
+        if isinstance(change, dict)
+    )
+    slide_cards = ""
+    slides = report.get("slides")
+    assert isinstance(slides, list)
+    for pair in slides:
+        assert isinstance(pair, dict)
+        index = int(pair["index"])
+        left = pair.get("before") if isinstance(pair.get("before"), dict) else {}
+        right = pair.get("after") if isinstance(pair.get("after"), dict) else {}
+        slide_cards += (
+            f'<article class="slide-pair"><header><span>第 {index:02d} 页</span>'
+            f"<h2>{_escape(right.get('title') or left.get('title') or '未命名页面')}</h2></header>"
+            '<div class="preview"><figure><figcaption>改造前</figcaption>'
+            f'<img alt="第 {index} 页改造前预览" src="{_escape(left.get("preview", ""))}"></figure>'
+            "<figure><figcaption>改造后</figcaption>"
+            f'<img alt="第 {index} 页改造后预览" src="{_escape(right.get("preview", ""))}"></figure></div></article>'
+        )
+    resolved = report.get("resolved")
+    new = report.get("new")
+    persistent = report.get("persistent")
+    assert isinstance(resolved, list) and isinstance(new, list) and isinstance(persistent, list)
+    persistent_after = [
+        item["after"] for item in persistent if isinstance(item, dict) and isinstance(item.get("after"), dict)
+    ]
+    findings = (
+        _finding_list("已解决", resolved, "resolved")
+        + _finding_list("持续存在", persistent_after, "persistent")
+        + _finding_list("新增问题", new, "new")
+    )
+    raw_json = json.dumps(report, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    safe_json = raw_json.replace("&", "\\u0026").replace("<", "\\u003c").replace(">", "\\u003e")
+    gate_label = "通过" if gate.get("passed") else "未通过"
+    return f"""<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>PPTLint 比较报告 · {_escape(after_file["name"])}</title>
+<style>
+:root{{--ink:#10233f;--paper:#f2f0eb;--panel:#fff;--muted:#667085;--good:#18794e;--warn:#b54708;--bad:#b42318}}
+*{{box-sizing:border-box}}body{{margin:0;background:var(--paper);color:var(--ink);font:15px/1.65 "PingFang SC","Microsoft YaHei",system-ui,sans-serif}}
+main{{max-width:1180px;margin:auto;padding:52px 24px 88px}}header.hero{{border-bottom:3px solid var(--ink);padding-bottom:28px}}
+.kicker{{font-size:12px;font-weight:700;letter-spacing:.14em;color:#8a3d22}}h1{{font-size:clamp(38px,7vw,76px);line-height:1.05;margin:10px 0}}.hero p{{color:var(--muted);margin:0}}
+.overall{{display:grid;grid-template-columns:1fr auto 1fr;align-items:center;gap:22px;background:var(--panel);padding:28px;margin:28px 0}}.overall strong{{font-size:54px}}.overall i{{font-size:34px;color:var(--good)}}.overall .after{{text-align:right}}.gate{{font-weight:700;color:{"var(--good)" if gate.get("passed") else "var(--bad)"}}}
+.scores{{display:grid;grid-template-columns:repeat(5,1fr);gap:12px}}.scores article{{background:var(--panel);padding:16px;border-top:3px solid var(--ink)}}.scores span,.scores b,.scores em{{display:block}}.scores em{{color:var(--good);font-style:normal}}
+.groups{{display:grid;grid-template-columns:repeat(3,1fr);gap:18px;margin:42px 0}}.finding-group{{background:var(--panel);padding:20px;border-top:5px solid var(--muted)}}.resolved{{border-color:var(--good)}}.new{{border-color:var(--bad)}}ul{{list-style:none;margin:0;padding:0}}li{{padding:9px 0;border-top:1px solid #e4e7ec}}li code,li strong,li span{{display:block}}li code{{font-size:11px;color:var(--muted)}}
+.slide-grid{{display:grid;gap:24px}}.slide-pair{{background:var(--panel);padding:20px}}.slide-pair header{{display:flex;gap:18px;align-items:baseline}}.slide-pair h2{{margin:0 0 12px}}.preview{{display:grid;grid-template-columns:1fr 1fr;gap:14px}}figure{{margin:0}}figcaption{{font-weight:700;margin-bottom:6px}}img{{display:block;width:100%;background:#e4e7ec;min-height:32px}}
+@media(max-width:820px){{.scores,.groups{{grid-template-columns:1fr 1fr}}.preview{{grid-template-columns:1fr}}}}@media(max-width:560px){{.scores,.groups{{grid-template-columns:1fr}}}}
+</style></head><body><main>
+<header class="hero"><span class="kicker">PPTLINT · POWERPOINT 修改前后检查</span><h1>改造前后比较报告</h1><p>{_escape(before_file["name"])} → {_escape(after_file["name"])}</p></header>
+<section class="overall"><div><span>改造前</span><strong>{_escape(overall["before"])}</strong></div><i>{int(overall["delta"]):+d}</i><div class="after"><span>改造后</span><strong>{_escape(overall["after"])}</strong></div></section>
+<p class="gate">回归门禁：{gate_label}</p><section class="scores">{score_cards}</section>
+<section class="groups">{findings}</section><section class="slide-grid">{slide_cards}</section>
+<script id="decklint-comparison-data" type="application/json">{safe_json}</script>
+</main></body></html>"""
+
+
+def write_comparison_reports(
+    output_stem: Path,
+    report: dict[str, object],
+) -> tuple[Path, Path]:
+    output_stem = Path(output_stem)
+    output_stem.parent.mkdir(parents=True, exist_ok=True)
+    html_path = Path(f"{output_stem}.html")
+    json_path = Path(f"{output_stem}.json")
+    html_path.write_text(_render_comparison_html(report), encoding="utf-8")
+    json_path.write_text(
+        json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return html_path, json_path

decklint/compat.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import sys
+
+from .cli import main as pptlint_main
+
+
+def main(argv: list[str] | None = None) -> int:
+    print(
+        "DeckLint is now PPTLint. The decklint command remains available through v0.4; migrate to `pptlint check`.",
+        file=sys.stderr,
+    )
+    return pptlint_main(argv)