docx-integrity 0.1.1__py3-none-any.whl

docx_integrity/__init__.py

@@ -0,0 +1,40 @@
+"""
+docx-integrity - structural integrity checks for .docx files.
+
+Two questions, both needed:
+
+    check(path)               is this .docx self-consistent?
+    compare(source, edited)   what did the edit lose relative to the source?
+    check_pptx(path)          does this deck's text fit, and do shapes collide?
+
+None of them needs a model, a renderer, or the network.
+
+    >>> from docx_integrity import check, compare
+    >>> for f in check("edited.docx"):
+    ...     print(f)
+    >>> for f in compare("original.docx", "edited.docx"):
+    ...     print(f)
+"""
+from .fidelity import TRACKED, compare
+from .finding import ERROR, INFO, WARN, Finding, Severity, summarize, worst
+from .inspector import Inspector, check, check_many
+from .pptx_checks import check_pptx
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "check",
+    "check_many",
+    "check_pptx",
+    "compare",
+    "Inspector",
+    "Finding",
+    "Severity",
+    "ERROR",
+    "WARN",
+    "INFO",
+    "summarize",
+    "worst",
+    "TRACKED",
+    "__version__",
+]

docx_integrity/cli.py

@@ -0,0 +1,179 @@
+"""Command line interface.
+
+Exit codes are the contract with CI:
+
+    0   nothing at or above the --fail-on threshold
+    1   findings at or above the threshold
+    2   usage error, or a file that could not be read at all
+"""
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .fidelity import compare
+from .finding import Finding, Severity, summarize, worst
+from .inspector import check
+from .pptx_checks import check_pptx
+
+EXIT_OK, EXIT_FINDINGS, EXIT_USAGE = 0, 1, 2
+
+
+_GLOB_CHARS = "*?["
+
+
+def _expand(patterns: list[str]) -> tuple[list[Path], list[str]]:
+    """Expand globs ourselves so behaviour matches on every shell and OS.
+
+    A named path that does not exist is kept, so it gets reported as a finding
+    about that file rather than silently skipped. A *glob* that matches nothing
+    is different: there is no file to report on, and "file not found: *.docx"
+    would be a nonsense message. Those come back as `empty` for the caller to
+    treat as a usage error.
+    """
+    found: list[Path] = []
+    empty: list[str] = []
+    for pat in patterns:
+        p = Path(pat)
+        if p.exists():
+            found.append(p)
+            continue
+        if any(c in pat for c in _GLOB_CHARS):
+            hits = sorted(glob.glob(pat, recursive=True))
+            if hits:
+                found.extend(Path(h) for h in hits)
+            else:
+                empty.append(pat)
+        else:
+            found.append(p)
+    return found, empty
+
+
+def _run_one(path: Path, source: Path | None) -> list[Finding]:
+    if path.suffix.lower() in (".pptx", ".potx", ".ppsx"):
+        if source is not None:
+            return check_pptx(path) + [
+                Finding("FID000", Severity.INFO,
+                        "--against is not implemented for .pptx yet; only layout "
+                        "checks were run")
+            ]
+        return check_pptx(path)
+    findings = check(path)
+    unreadable = any(f.code in ("PKG000", "PKG002") for f in findings)
+    if source is not None and not unreadable:
+        try:
+            findings = findings + compare(source, path)
+        except Exception as e:
+            findings = findings + [
+                Finding("FID000", Severity.WARN,
+                        f"could not compare against {source}: {e}")
+            ]
+    return findings
+
+
+def _print_human(path: Path, findings: list[Finding], threshold: Severity,
+                 quiet: bool, out) -> None:
+    shown = [f for f in findings if f.severity >= threshold] if quiet else findings
+    counts = summarize(findings)
+    head = (f"{path}: "
+            f"{counts['error']} error(s), {counts['warn']} warning(s), "
+            f"{counts['info']} info")
+    if not shown and not findings:
+        print(f"{head}  - clean", file=out)
+        return
+    print(head, file=out)
+    for f in shown:
+        print("  " + str(f).replace("\n", "\n  "), file=out)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="docx-integrity",
+        description="Structural integrity checks for .docx files. "
+                    "Answers 'will Word open this, and did the edit lose "
+                    "anything', which schema validation and rendering do not.",
+        epilog="exit codes: 0 clean, 1 findings at or above --fail-on, 2 usage error",
+    )
+    p.add_argument("--version", action="version",
+                   version=f"docx-integrity {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    c = sub.add_parser("check", help="inspect one or more .docx files")
+    c.add_argument("files", nargs="+",
+                   help="paths or globs, e.g. 'out/**/*.docx'. "
+                        ".pptx files get the layout checks instead")
+    c.add_argument("--against", metavar="SOURCE", type=Path, default=None,
+                   help="also report what was lost relative to SOURCE")
+    c.add_argument("--fail-on", default="error", metavar="SEVERITY",
+                   help="minimum severity that makes the run fail: "
+                        "error (default), warn, info")
+    c.add_argument("--json", action="store_true",
+                   help="machine-readable output on stdout")
+    c.add_argument("--quiet", "-q", action="store_true",
+                   help="print only findings at or above --fail-on")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    try:
+        threshold = Severity.parse(args.fail_on)
+    except ValueError as e:
+        print(f"docx-integrity: {e}", file=sys.stderr)
+        return EXIT_USAGE
+
+    if args.against is not None and not args.against.exists():
+        print(f"docx-integrity: --against file not found: {args.against}",
+              file=sys.stderr)
+        return EXIT_USAGE
+
+    paths, unmatched = _expand(args.files)
+    if unmatched and not paths:
+        print("docx-integrity: no files matched: " + ", ".join(unmatched),
+              file=sys.stderr)
+        return EXIT_USAGE
+    for pat in unmatched:
+        print(f"docx-integrity: warning: no files matched {pat}", file=sys.stderr)
+    if not paths:
+        print("docx-integrity: nothing to check", file=sys.stderr)
+        return EXIT_USAGE
+
+    results: dict[Path, list[Finding]] = {}
+    for path in paths:
+        results[path] = _run_one(path, args.against)
+
+    if args.json:
+        payload = {
+            "version": __version__,
+            "fail_on": threshold.value,
+            "files": [
+                {
+                    "path": str(p),
+                    "summary": summarize(f),
+                    "worst": (w.value if (w := worst(f)) else None),
+                    "findings": [x.as_dict() for x in f],
+                }
+                for p, f in results.items()
+            ],
+        }
+        json.dump(payload, sys.stdout, indent=2, ensure_ascii=False)
+        sys.stdout.write("\n")
+    else:
+        for i, (p, f) in enumerate(results.items()):
+            if i:
+                print()
+            _print_human(p, f, threshold, args.quiet, sys.stdout)
+
+    failed = any(
+        f.severity >= threshold for findings in results.values() for f in findings
+    )
+    return EXIT_FINDINGS if failed else EXIT_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())

docx_integrity/fidelity.py

@@ -0,0 +1,101 @@
+"""
+Fidelity check against the source document.
+
+The inspector answers "is this file self-consistent?". That is not enough: a
+document stripped of every style, footnote and revision is perfectly
+self-consistent. A second question is needed - "what was lost relative to the
+original?".
+"""
+from __future__ import annotations
+
+import zipfile
+from pathlib import Path
+
+from lxml import etree
+
+from .finding import ERROR, INFO, WARN, Finding
+
+W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}"
+
+#: (tag, human label, severity when some are lost)
+#:
+#: The severity rule: losing something that makes content or an audit trail
+#: INVISIBLE is an error, because nothing downstream will report it. Losing
+#: something that only changes how the document looks is a warning. Losing all
+#: of any construct is always an error.
+TRACKED: tuple[tuple[str, str, object], ...] = (
+    ("commentReference", "comment anchors", ERROR),
+    ("footnoteReference", "footnote references", ERROR),
+    ("ins", "tracked insertions", ERROR),
+    ("del", "tracked deletions", ERROR),
+    ("sdt", "content controls", ERROR),
+    ("drawing", "images and charts", ERROR),
+    ("tbl", "tables", ERROR),
+    ("hyperlink", "hyperlinks", WARN),
+    ("pStyle", "paragraph style references", WARN),
+    ("rStyle", "character style references", WARN),
+    ("numPr", "numbered list items", WARN),
+    ("tblHeader", "table header rows", WARN),
+)
+
+#: below this fraction of the source's text length, report FID003
+TEXT_LOSS_THRESHOLD = 0.95
+
+
+def _document(path: str | Path):
+    with zipfile.ZipFile(path) as z:
+        return etree.fromstring(z.read("word/document.xml"))
+
+
+def _counts(path: str | Path) -> dict[str, int]:
+    doc = _document(path)
+    return {tag: len(list(doc.iter(W + tag))) for tag, _, _ in TRACKED}
+
+
+def _text(path: str | Path) -> str:
+    doc = _document(path)
+    return "".join(t.text or "" for t in doc.iter(W + "t"))
+
+
+def compare(source: str | Path, edited: str | Path) -> list[Finding]:
+    """What did `edited` lose relative to `source`?
+
+    Raises the same exceptions as opening a zip - callers that may be handed a
+    corrupt file should run `check()` first, which reports rather than raises.
+    """
+    before, after = _counts(source), _counts(edited)
+    out: list[Finding] = []
+
+    for tag, label, sev in TRACKED:
+        a, b = before[tag], after[tag]
+        if not a:
+            continue
+        if b < a:
+            lost = a - b
+            out.append(Finding(
+                "FID001",
+                ERROR if b == 0 else sev,
+                f"{label}: {a} -> {b} "
+                f'({"all lost" if b == 0 else f"{lost} lost"})',
+                extra={"tag": tag, "before": a, "after": b},
+            ))
+        elif b > a:
+            # A higher count is not itself a defect: the agent may legitimately
+            # have added an item, or wrapped its edit in w:ins. Real duplication
+            # is caught by colliding ids (REV001), not by a counter.
+            out.append(Finding(
+                "FID002", INFO,
+                f"{label}: {a} -> {b} - added during editing "
+                "(only a defect if ids collide, see REV001)",
+                extra={"tag": tag, "before": a, "after": b},
+            ))
+
+    ta, tb = _text(source), _text(edited)
+    if ta and len(tb) < len(ta) * TEXT_LOSS_THRESHOLD:
+        out.append(Finding(
+            "FID003", ERROR,
+            f"text volume fell from {len(ta)} to {len(tb)} characters "
+            f"({round(100 * (1 - len(tb) / len(ta)))}% of content lost)",
+            extra={"before": len(ta), "after": len(tb)},
+        ))
+    return out

docx_integrity/finding.py

@@ -0,0 +1,89 @@
+"""The single result type shared by the inspector and the fidelity check."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from typing import Any
+
+
+class Severity(str, Enum):
+    """Ordered so comparisons work: ERROR > WARN > INFO."""
+
+    ERROR = "error"
+    WARN = "warn"
+    INFO = "info"
+
+    @property
+    def rank(self) -> int:
+        return {"error": 3, "warn": 2, "info": 1}[self.value]
+
+    def __ge__(self, other: "Severity") -> bool:  # type: ignore[override]
+        return self.rank >= other.rank
+
+    def __gt__(self, other: "Severity") -> bool:  # type: ignore[override]
+        return self.rank > other.rank
+
+    def __le__(self, other: "Severity") -> bool:  # type: ignore[override]
+        return self.rank <= other.rank
+
+    def __lt__(self, other: "Severity") -> bool:  # type: ignore[override]
+        return self.rank < other.rank
+
+    @classmethod
+    def parse(cls, s: str) -> "Severity":
+        try:
+            return cls(s.strip().lower())
+        except ValueError:
+            raise ValueError(
+                f"unknown severity {s!r}; expected one of: "
+                + ", ".join(m.value for m in cls)
+            ) from None
+
+
+# Convenience aliases, so check code reads cleanly.
+ERROR = Severity.ERROR
+WARN = Severity.WARN
+INFO = Severity.INFO
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One problem found in one document.
+
+    code     stable identifier, e.g. CMT005 - safe to grep, safe to suppress
+    severity ERROR / WARN / INFO
+    message  human-readable, says what breaks rather than what rule fired
+    where    XPath to the offending node, or a part name, when known
+    part     the package part the finding belongs to, when known
+    """
+
+    code: str
+    severity: Severity
+    message: str
+    where: str = ""
+    part: str = ""
+    extra: dict[str, Any] = field(default_factory=dict, compare=False)
+
+    def as_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["severity"] = self.severity.value
+        if not d["extra"]:
+            d.pop("extra")
+        return {k: v for k, v in d.items() if v != ""}
+
+    def __str__(self) -> str:
+        head = f"[{self.severity.value.upper():5}] {self.code}  {self.message}"
+        return f"{head}\n          -> {self.where}" if self.where else head
+
+
+def summarize(findings: list[Finding]) -> dict[str, int]:
+    """Counts by severity, always with all three keys present."""
+    out = {m.value: 0 for m in Severity}
+    for f in findings:
+        out[f.severity.value] += 1
+    return out
+
+
+def worst(findings: list[Finding]) -> Severity | None:
+    """Highest severity present, or None for an empty list."""
+    return max((f.severity for f in findings), key=lambda s: s.rank, default=None)