docs(document-skills): verify rendered package content

Author: Hylouis233

plugins/Hylouis233/document-skills/skills/docx/references/read.md

@@ -14,11 +14,122 @@ tables). Prefer this when the goal is content, not coordinates.
 ## Structured access (python-docx)
 
 ```python
+from contextlib import contextmanager
+import zipfile
+from pathlib import Path
+from tempfile import TemporaryFile
+
 from docx import Document
 from docx.oxml.ns import qn
 from docx.table import Table
 from docx.text.paragraph import Paragraph
 from docx.text.run import Run
+from lxml import etree
+
+MAX_ARCHIVE_BYTES = 200 * 1024 * 1024
+MAX_MEMBERS = 10_000
+MAX_XML_PART = 20 * 1024 * 1024
+MAX_ENTRY = 100 * 1024 * 1024
+MAX_TOTAL_UNCOMPRESSED = 500 * 1024 * 1024
+MAX_COMPRESSION_RATIO = 200
+CONTENT_TYPES_NAMESPACE = "http://schemas.openxmlformats.org/package/2006/content-types"
+
+def require(condition, message):
+    if not condition:
+        raise ValueError(message)
+
+SAFE_XML_PARSER = etree.XMLParser(
+    load_dtd=False, resolve_entities=False, no_network=True,
+    huge_tree=False, recover=False,
+)
+
+def xml_content_type(value):
+    media_type = (value or "").split(";", 1)[0].strip().casefold()
+    return media_type in {"application/xml", "text/xml"} or media_type.endswith("+xml")
+
+def declared_xml_parts(archive, infos):
+    """Classify XML by OPC declarations, not filename spelling alone."""
+    by_name = {info.filename: info for info in infos}
+    content_types_info = by_name.get("[Content_Types].xml")
+    require(content_types_info is not None, "missing [Content_Types].xml")
+    require(content_types_info.file_size <= MAX_XML_PART,
+            "oversized XML part: [Content_Types].xml")
+    with archive.open(content_types_info) as stream:
+        content_types_blob = stream.read(MAX_XML_PART + 1)
+    require(len(content_types_blob) <= MAX_XML_PART,
+            "oversized XML part: [Content_Types].xml")
+    root = etree.fromstring(content_types_blob, parser=SAFE_XML_PARSER)
+    require(root.tag == f"{{{CONTENT_TYPES_NAMESPACE}}}Types",
+            "invalid [Content_Types].xml root")
+    defaults = {}
+    overrides = {}
+    for child in root:
+        if child.tag == f"{{{CONTENT_TYPES_NAMESPACE}}}Default":
+            extension = (child.get("Extension") or "").casefold()
+            require(extension and extension not in defaults,
+                    "invalid duplicate content-type default")
+            defaults[extension] = child.get("ContentType") or ""
+        elif child.tag == f"{{{CONTENT_TYPES_NAMESPACE}}}Override":
+            part_name = child.get("PartName") or ""
+            require(part_name.startswith("/") and part_name[1:] not in overrides,
+                    "invalid duplicate content-type override")
+            overrides[part_name[1:]] = child.get("ContentType") or ""
+    xml_names = {"[Content_Types].xml"}
+    for info in infos:
+        suffix = info.filename.rsplit(".", 1)[1].casefold() if "." in info.filename else ""
+        content_type = overrides.get(info.filename, defaults.get(suffix, ""))
+        if (info.filename.casefold().endswith((".xml", ".rels"))
+                or xml_content_type(content_type)):
+            xml_names.add(info.filename)
+    return xml_names
+
+def validate_docx_archive(archive):
+    infos = archive.infolist()
+    require(len(infos) <= MAX_MEMBERS, "archive member count above limit")
+    names = {info.filename for info in infos}
+    require(len(names) == len(infos), "duplicate archive member names are unsafe")
+    require("[Content_Types].xml" in names and "word/document.xml" in names,
+            "missing required OPC members")
+    require(sum(info.file_size for info in infos) <= MAX_TOTAL_UNCOMPRESSED,
+            "declared total uncompressed size above limit")
+    xml_names = declared_xml_parts(archive, infos)
+    actual_total = 0
+    for info in infos:
+        require(info.file_size <= MAX_ENTRY, f"oversized part: {info.filename}")
+        require(info.file_size / max(info.compress_size, 1) <= MAX_COMPRESSION_RATIO,
+                f"suspicious compression ratio: {info.filename}")
+        is_xml = info.filename in xml_names
+        if is_xml:
+            require(info.file_size <= MAX_XML_PART, f"oversized XML part: {info.filename}")
+        chunks = []
+        actual_size = 0
+        with archive.open(info) as stream:
+            while chunk := stream.read(64 * 1024):
+                actual_size += len(chunk)
+                actual_total += len(chunk)
+                require(actual_size <= MAX_ENTRY, f"part exceeded read limit: {info.filename}")
+                require(actual_total <= MAX_TOTAL_UNCOMPRESSED,
+                        "archive exceeded total read limit")
+                if is_xml:
+                    chunks.append(chunk)
+        require(actual_size == info.file_size, f"size mismatch: {info.filename}")
+        if is_xml:
+            etree.fromstring(b"".join(chunks), parser=SAFE_XML_PARSER)
+
+@contextmanager
+def validated_docx_source(path):
+    """Yield one private, bounded snapshot for both validation and python-docx."""
+    with Path(path).open("rb") as external_source, TemporaryFile() as source:
+        copied = 0
+        while chunk := external_source.read(64 * 1024):
+            copied += len(chunk)
+            require(copied <= MAX_ARCHIVE_BYTES, "compressed DOCX file size above limit")
+            source.write(chunk)
+        source.seek(0)
+        with zipfile.ZipFile(source) as archive:
+            validate_docx_archive(archive)
+        source.seek(0)
+        yield source
 
 MC_NAMESPACE = "http://schemas.openxmlformats.org/markup-compatibility/2006"
 MC_ALTERNATE_CONTENT = f"{{{MC_NAMESPACE}}}AlternateContent"
@@ -227,17 +338,18 @@ def table_content(table):
         })
     return rows
 
-doc = Document("input.docx")
-content_controls = list(doc.element.body.iter(qn("w:sdt")))
-blocks = list(iter_part_blocks(doc.element.body, doc))
-print("content controls:", len(content_controls), "top-level blocks:", len(blocks))
-for kind, block in blocks:
-    if kind == "paragraph":
-        print(block.style.name, "|", paragraph_text(block))
-    elif kind == "table":
-        print("table |", table_content(block))
-    else:
-        print("unreadable |", block)
+with validated_docx_source("input.docx") as source:
+    doc = Document(source)
+    content_controls = list(doc.element.body.iter(qn("w:sdt")))
+    blocks = list(iter_part_blocks(doc.element.body, doc))
+    print("content controls:", len(content_controls), "top-level blocks:", len(blocks))
+    for kind, block in blocks:
+        if kind == "paragraph":
+            print(block.style.name, "|", paragraph_text(block))
+        elif kind == "table":
+            print("table |", table_content(block))
+        else:
+            print("unreadable |", block)
 ```
 
 Notes:

plugins/Hylouis233/document-skills/skills/docx/references/review.md

@@ -24,6 +24,7 @@ MAX_XML_PART = 20 * 1024 * 1024
 MAX_ENTRY = 100 * 1024 * 1024
 MAX_TOTAL_UNCOMPRESSED = 500 * 1024 * 1024
 MAX_COMPRESSION_RATIO = 200
+CONTENT_TYPES_NAMESPACE = "http://schemas.openxmlformats.org/package/2006/content-types"
 
 # Security limits must survive `python -O` (which strips assert statements),
 # so every check raises explicitly instead of asserting.
@@ -38,6 +39,46 @@ safe_xml_parser = etree.XMLParser(
     huge_tree=False,
     recover=False,
 )
+
+def xml_content_type(value):
+    media_type = (value or "").split(";", 1)[0].strip().casefold()
+    return media_type in {"application/xml", "text/xml"} or media_type.endswith("+xml")
+
+def declared_xml_parts(archive, infos):
+    """Classify XML from OPC declarations plus conventional suffixes."""
+    by_name = {info.filename: info for info in infos}
+    content_types_info = by_name.get("[Content_Types].xml")
+    require(content_types_info is not None, "missing [Content_Types].xml")
+    require(content_types_info.file_size <= MAX_XML_PART,
+            "oversized XML part: [Content_Types].xml")
+    with archive.open(content_types_info) as stream:
+        content_types_blob = stream.read(MAX_XML_PART + 1)
+    require(len(content_types_blob) <= MAX_XML_PART,
+            "oversized XML part: [Content_Types].xml")
+    root = etree.fromstring(content_types_blob, parser=safe_xml_parser)
+    require(root.tag == f"{{{CONTENT_TYPES_NAMESPACE}}}Types",
+            "invalid [Content_Types].xml root")
+    defaults = {}
+    overrides = {}
+    for child in root:
+        if child.tag == f"{{{CONTENT_TYPES_NAMESPACE}}}Default":
+            extension = (child.get("Extension") or "").casefold()
+            require(extension and extension not in defaults,
+                    "invalid duplicate content-type default")
+            defaults[extension] = child.get("ContentType") or ""
+        elif child.tag == f"{{{CONTENT_TYPES_NAMESPACE}}}Override":
+            part_name = child.get("PartName") or ""
+            require(part_name.startswith("/") and part_name[1:] not in overrides,
+                    "invalid duplicate content-type override")
+            overrides[part_name[1:]] = child.get("ContentType") or ""
+    xml_names = {"[Content_Types].xml"}
+    for info in infos:
+        suffix = info.filename.rsplit(".", 1)[1].casefold() if "." in info.filename else ""
+        content_type = overrides.get(info.filename, defaults.get(suffix, ""))
+        if (info.filename.casefold().endswith((".xml", ".rels"))
+                or xml_content_type(content_type)):
+            xml_names.add(info.filename)
+    return xml_names
 # Check the package itself before ZipFile materializes its central directory.
 require(Path(path).stat().st_size <= MAX_ARCHIVE_BYTES,
         "compressed DOCX file size above limit")
@@ -51,12 +92,13 @@ with zipfile.ZipFile(path) as z:
             "missing required OPC members")
     require(sum(info.file_size for info in infos) <= MAX_TOTAL_UNCOMPRESSED,
             "declared total uncompressed size above limit")
+    xml_names = declared_xml_parts(z, infos)
     actual_total = 0
     for info in infos:
         require(info.file_size <= MAX_ENTRY, f"oversized part: {info.filename}")
         ratio = info.file_size / max(info.compress_size, 1)
         require(ratio <= MAX_COMPRESSION_RATIO, f"suspicious compression ratio: {info.filename}")
-        is_xml = info.filename.endswith((".xml", ".rels"))
+        is_xml = info.filename in xml_names
         if is_xml:
             require(info.file_size <= MAX_XML_PART, f"oversized XML part: {info.filename}")
         chunks = []

plugins/Hylouis233/document-skills/skills/pdf/references/inspect.md

@@ -163,6 +163,48 @@ MAX_TOTAL_IMAGE_RENDER_PIXELS = 20_000_000
 MAX_DRAWING_PATHS = 1_000
 MAX_DRAWING_RENDER_PIXELS = 4_000_000
 MAX_TOTAL_DRAWING_RENDER_PIXELS = 20_000_000
+MAX_TEXT_SPANS = 10_000
+MAX_TEXT_RENDER_PIXELS = 4_000_000
+MAX_TOTAL_TEXT_RENDER_PIXELS = 20_000_000
+
+def viewable_text(page):
+    """Use text render mode, opacity, clipping, and bounded alpha rendering."""
+    try:
+        spans = page.get_texttrace()
+    except (RuntimeError, ValueError):
+        return [], [], True
+    if len(spans) > MAX_TEXT_SPANS:
+        return spans, [], True
+    visible = []
+    total_render_pixels = 0
+    for span in spans:
+        try:
+            text = "".join(chr(character[0]) for character in span.get("chars", ()))
+            render_type = int(span.get("type"))
+            opacity = float(span.get("opacity"))
+        except (TypeError, ValueError, OverflowError):
+            return spans, visible, True
+        if not text.strip() or render_type > 1 or opacity <= 0:
+            continue
+        if render_type not in (0, 1) or not math.isfinite(opacity):
+            return spans, visible, True
+        clip = visible_clip(page, span.get("bbox"))
+        if clip is None:
+            continue
+        render_pixels = math.ceil(clip.width) * math.ceil(clip.height)
+        total_render_pixels += render_pixels
+        if (render_pixels > MAX_TEXT_RENDER_PIXELS
+                or total_render_pixels > MAX_TOTAL_TEXT_RENDER_PIXELS):
+            return spans, visible, True
+        try:
+            pixmap = page.get_pixmap(clip=clip, alpha=True, annots=False)
+        except (RuntimeError, ValueError):
+            return spans, visible, True
+        if not pixmap.alpha:
+            return spans, visible, True
+        if any(pixmap.samples[pixmap.n - 1::pixmap.n]):
+            visible.append(span)
+    return spans, visible, False
 
 def viewable_images(page):
     """Render bounded placement clips; unknown visibility keeps the page nonblank."""
@@ -338,17 +380,20 @@ for page in doc:
         "crop_size": crop_size,
         "rotation": page.rotation,
     })
+    text_spans, visible_text, text_visibility_unknown = viewable_text(page)
     image_placements, visible_images, image_visibility_unknown = viewable_images(page)
     drawings, visible_drawings, drawing_visibility_unknown = viewable_drawings(page)
     widgets, annotations, links, interaction_visibility_unknown = viewable_interactives(page)
     is_blank = not (
-        page.get_text().strip() or visible_images or visible_drawings
+        visible_text or visible_images or visible_drawings
         or widgets or annotations or links
-        or image_visibility_unknown or drawing_visibility_unknown
+        or text_visibility_unknown or image_visibility_unknown or drawing_visibility_unknown
         or interaction_visibility_unknown
     )
     print(page.number + 1, "media_size:", media_size, "crop_size:", crop_size,
           "rotation:", page.rotation, "text_len:", len(page.get_text()),
+          "text_spans:", len(text_spans), "visible_text_spans:", len(visible_text),
+          "text_visibility_unknown:", text_visibility_unknown,
           "resource_images:", len(page.get_images()),
           "image_placements:", len(image_placements),
           "visible_images:", len(visible_images),
@@ -366,7 +411,7 @@ print("crop_size_consistent:", len({row["crop_size"] for row in page_geometry})
 
 ## Checks worth automating
 
-- **Blank page detection**: flag only when text, visible painted image placements and vector paths,
+- **Blank page detection**: flag only when rendered text, visible painted image placements and vector paths,
   and viewable widgets, annotations, and links are all absent. Ignore interactive objects carrying
   invisible, hidden, or no-view flags, as well as empty, off-page, or unrendered appearances.
   `page.get_images()` lists every image XObject resource, including unused resources, and also

plugins/Hylouis233/document-skills/skills/xlsx/SKILL.md

@@ -78,6 +78,11 @@ expected_number_formats = {
 expected_formulas = {
     # "Sales": {"D2": "=C2*1.08"},
 }
+# Populate every expected sheet with the exact used range required by the task.
+expected_dimensions = {
+    # "Sales": "A1:E20",
+    # "Summary": "A1:C8",
+}
 wb = load_validated_workbook(output_path)
 
 def require(condition, message):
@@ -98,6 +103,10 @@ def formula_text(value):
 print("sheets:", wb.sheetnames)
 missing = set(expected_sheets) - set(wb.sheetnames)
 require(not missing, f"missing expected sheets: {sorted(missing)}")
+require(
+    set(expected_dimensions) == set(expected_sheets),
+    "expected_dimensions must declare the exact used range for every expected sheet",
+)
 calc = wb.calculation
 print("calcMode:", getattr(calc, "calcMode", None),
       "fullCalcOnLoad:", getattr(calc, "fullCalcOnLoad", None))
@@ -109,6 +118,12 @@ if any(expected_formulas.values()):
     )
 for ws in wb.worksheets:
     print(f"{ws.title} dims:", ws.dimensions)
+    if ws.title in expected_dimensions:
+        require(
+            ws.dimensions == expected_dimensions[ws.title],
+            f"{ws.title}: expected used range {expected_dimensions[ws.title]!r}, "
+            f"got {ws.dimensions!r}",
+        )
     # `expected_formulas` is the task contract, so verify those coordinates directly.
     # Never call unbounded iter_rows(): one styled extreme cell can make the rectangle huge.
     actual_formulas = {}

plugins/Hylouis233/document-skills/skills/xlsx/references/edit.md

@@ -296,6 +296,9 @@ wb.save("input-edited.xlsx")
       """Dry-run one workbook, then return a fresh edit copy from the same source."""
       require(not load_options.get("read_only"),
               "round-trip audit requires a normal writable Workbook")
+      require(load_options.get("rich_text", True) is True,
+              "round-trip audit must preserve rich-text cell runs")
+      load_options["rich_text"] = True
       source.seek(0)
       before_names, before_extensions = archive_inventory(source)
       source.seek(0)