licos-dev-sdk 0.4.2__tar.gz → 0.4.4__tar.gz

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.4}/DOCX.md

@@ -1,20 +1,23 @@
-# Word SDK / CLI 0.4.2
+# Word SDK / CLI 0.4.4
 
 Cloud document execution stays in `licos-dev-sdk` and `licos-dev`. CLI commands
 only parse arguments and call the SDK; no additional Agent-native Word tools are
 registered. Existing `docx`, `docx-template`, `docx-read`, `docx-edit` commands and
 their Python APIs retain their invocation contracts.
 
+Use `licos-dev --version` to query the installed document CLI version.
+
 | CLI command | SDK function | Input |
 | --- | --- | --- |
-| `docx-structure` | `read_docx_structure` | File, blocks/paragraphs, page |
+| `docx-structure` | `read_docx_structure` | File, blocks/paragraphs/tables, page |
+| `docx-inspect` | `inspect_docx` | File, all/fields/images/tables, offset/limit |
 | `docx-target` | `read_docx_target` | File, exact target, text cursor |
 | `docx-replace` | `replace_docx_text` | Source/output, revision, target, search/replacement |
 | `docx-delete-blocks` | `delete_docx_blocks` | Source/output, revision, inclusive block range |
 | `docx-edit-structure` | `edit_docx_structure` | Source/output, revision, small operations array |
 | `docx-table-set` | `set_docx_cell` | Source/output, revision, table/row/column, text |
 | `docx-table-insert-rows` | `insert_docx_rows` | Source/output, revision, table, insertion point, template row, rows |
-| `docx-verify` | `verify_docx` | File, optional positional assertions |
+| `docx-verify` | `verify_docx` | File, optional positional assertions and original document |
 
 ## Contract
 
@@ -28,7 +31,7 @@ their Python APIs retain their invocation contracts.
   next batch uses the output and its returned revision.
 - Batch structure operations contain only `replace_text` with `target/search/replace`
   or `delete_blocks` with `from/to`. All targets refer to the input snapshot.
-  Invalid, missing, duplicate or removed targets fail before publishing output.
+  Invalid, missing or removed targets and ambiguous matches fail before publishing output.
 - `docx-replace` expects one exact match within one paragraph in the selected
   target. It supports text split across runs and preserves surrounding formatting.
   `--replace-file` carries long replacement text; simple replacements need no JSON.
@@ -36,6 +39,9 @@ their Python APIs retain their invocation contracts.
   `[["pump","set",2],["valve",null,3]]`. Row count is derived; each merged physical
   cell is filled once. Row/cell/paragraph/run styles come from `--template-row`.
   Templates that intersect vertical merges are rejected explicitly.
+  Choose exactly one of `--before N` (`before=N`) or `--append` (`append=True`).
+  Explicit append uses the current revision's row count. Table structure items
+  include `table`, `row_count`, `column_count` and a usable body block target.
 - New editing commands default to refusing an existing output, including the
   source itself. `--overwrite` explicitly allows replacement. Body edits are
   atomic and keep all other ZIP part payloads unchanged. Existing `docx-edit`
@@ -43,12 +49,33 @@ their Python APIs retain their invocation contracts.
 - Structure previews set `content_truncated`; `docx-target` retrieves exact text
   without stripping whitespace and provides `next_text_offset` until `has_more=false`.
   No partial JSON repair or automatic argument completion is performed.
-- Verification without assertions checks structure only: `content_verified=false`.
+- Verification without assertions does not certify content: `content_verified=false`.
   Positional assertions use `equals`, `contains` or `absent`. A mismatch produces
   `verified=false` and CLI exit code 2. Layout and page breaks require visual review.
+  One CLI assertion can use a target with `--text` or `--text-file` and optional
+  `--mode`; use `--input` for multiple assertions, never both input forms.
+- `verify_docx(..., original=...)` / `docx-verify --original` compares every ZIP
+  part payload except `word/document.xml`, plus ordered section settings in the
+  body. It reports changed/added/missing parts and `preservation_verified`; a
+  failed comparison also sets `verified=false` / exit 2. The original must be a
+  separate unmodified file. This does not certify all body run formatting or
+  rendered layout, and does not substitute for positional content assertions.
 
 ## Verification
 
+`docx-inspect` reports native field instructions (including split-run TOC fields),
+field completeness, embedded/external/missing image references, and table dimensions
+across document stories, including headers and footers. Each scope has its own
+`next_offset`; counts cover the entire document. `update_fields_on_open` describes
+the Word setting; neither it nor `toc_count` certifies rendered pagination.
+Use `docx-structure` for editable body targets.
+
+Batch verification entries require `target`, exactly one of `text` or `text_file`,
+and optional `mode`. JSON `text_file` is a UTF-8 path relative to the JSON file's
+directory. Single CLI `--text-file` is relative to cwd. SDK `base_dir` defaults to
+cwd and can set the file resolution directory explicitly. Empty text is valid;
+unknown keys, conflicting inputs and file errors identify the assertion and field.
+
 Run Python tests serially with the current source on `PYTHONPATH`:
 
 ```text

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: licos-dev-sdk
-Version: 0.4.2
+Version: 0.4.4
 Summary: LICOS Dev SDK - file generation and model capability clients
 Requires-Python: >=3.10
 Requires-Dist: beautifulsoup4>=4.12

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "licos-dev-sdk"
-version = "0.4.2"
+version = "0.4.4"
 description = "LICOS Dev SDK - file generation and model capability clients"
 requires-python = ">=3.10"
 dependencies = [

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.4}/src/licos_dev_sdk/__init__.py

@@ -30,6 +30,7 @@ def __getattr__(name: str):
         "create_docx_from_template": ("document", "create_docx_from_template"),
         "edit_docx": ("document", "edit_docx"),
         "read_docx_structure": ("document_docx_structure", "read_docx_structure"),
+        "inspect_docx": ("document_docx_inspect", "inspect_docx"),
         "read_docx_target": ("document_docx_structure", "read_docx_target"),
         "edit_docx_structure": ("document_docx_structure", "edit_docx_structure"),
         "replace_docx_text": ("document_docx_structure", "replace_docx_text"),
@@ -108,7 +109,7 @@ def __getattr__(name: str):
 
 
 __all__ = [
-    "read_docx_structure", "read_docx_target", "edit_docx_structure",
+    "inspect_docx", "read_docx_structure", "read_docx_target", "edit_docx_structure",
     "replace_docx_text", "delete_docx_blocks", "verify_docx", "set_docx_cell", "insert_docx_rows",
     "create_json", "create_xml", "create_yaml",
     "create_zip", "create_tar_gz",

licos_dev_sdk-0.4.4/src/licos_dev_sdk/document_docx_expectations.py

@@ -0,0 +1,30 @@
+"""The shared single/batch verification assertion contract."""
+
+from pathlib import Path
+
+
+def expected_text(expectation, index, base_dir):
+    prefix = f"expectation {index}"
+    if not isinstance(expectation, dict):
+        raise ValueError(f"{prefix} must be an object")
+    unknown = set(expectation) - {"target", "text", "text_file", "mode"}
+    if unknown:
+        raise ValueError(f"{prefix}: unknown fields {', '.join(sorted(unknown))}; allowed: target, text, text_file, mode")
+    if "target" not in expectation:
+        raise ValueError(f"{prefix}.target is required")
+    if ("text" in expectation) == ("text_file" in expectation):
+        raise ValueError(f"{prefix}: provide exactly one of text and text_file")
+    field = "text_file" if "text_file" in expectation else "text"
+    value = expectation[field]
+    if not isinstance(value, str) or (field == "text_file" and not value):
+        raise ValueError(f"{prefix}.{field} must be {'a non-empty' if field == 'text_file' else 'a'} string")
+    mode = expectation.get("mode", "equals")
+    if mode not in ("equals", "contains", "absent"):
+        raise ValueError(f"{prefix}.mode must be equals, contains or absent")
+    if field == "text_file":
+        path = Path(base_dir) / Path(value).expanduser()
+        try:
+            value = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeError) as exc:
+            raise ValueError(f"{prefix}.text_file: {exc}") from exc
+    return value, mode

licos_dev_sdk-0.4.4/src/licos_dev_sdk/document_docx_inspect.py

@@ -0,0 +1,90 @@
+"""Inspect native Word fields, image references and tables without modifying a package."""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+import posixpath
+
+from lxml import etree
+
+from .document_docx_package import DocxPackage
+
+W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}"
+R = "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}"
+A = "{http://schemas.openxmlformats.org/drawingml/2006/main}"
+V = "{urn:schemas-microsoft-com:vml}"
+
+
+def _xml(data):
+    return etree.fromstring(data, etree.XMLParser(resolve_entities=False, no_network=True))
+
+
+def _fields(root, part):
+    fields, stack = [], []
+    for element in root.iter():
+        if element.tag == W + "fldSimple":
+            fields.append({"part": part, "instruction": element.get(W + "instr", ""), "complete": True})
+        elif element.tag == W + "fldChar":
+            kind = element.get(W + "fldCharType")
+            if kind == "begin":
+                field = {"part": part, "instruction": "", "complete": False}
+                fields.append(field)
+                stack.append((field, True))
+            elif kind == "separate" and stack:
+                stack[-1] = (stack[-1][0], False)
+            elif kind == "end" and stack:
+                stack.pop()[0]["complete"] = True
+        elif element.tag == W + "instrText" and stack and stack[-1][1]:
+            stack[-1][0]["instruction"] += element.text or ""
+    for field in fields:
+        instruction = field["instruction"].strip()
+        field["type"] = instruction.split(maxsplit=1)[0].upper() if instruction else ""
+    return fields
+
+
+def inspect_docx(source: str | Path, *, scope: str = "all", offset: int = 1, limit: int = 20) -> dict:
+    """Return counts and paginated fields/images/tables. Field presence does not certify pagination."""
+    if scope not in {"all", "fields", "images", "tables"}:
+        raise ValueError("scope must be all, fields, images or tables")
+    if type(offset) is not int or offset < 1 or type(limit) is not int or not 1 <= limit <= 200:
+        raise ValueError("offset must be positive; limit must be 1-200")
+    package = DocxPackage(source)
+    parts = {info.filename: data for info, data in package.parts}
+    fields, images, tables = [], [], []
+    for part, data in parts.items():
+        if not part.startswith("word/") or not part.endswith(".xml"):
+            continue
+        root = package.root if part == "word/document.xml" else _xml(data)
+        fields.extend(_fields(root, part))
+        rel_path = str(PurePosixPath(part).parent / "_rels" / (PurePosixPath(part).name + ".rels"))
+        relationships = {rel.get("Id"): rel for rel in _xml(parts[rel_path])} if rel_path in parts else {}
+        for element in root.iter():
+            if element.tag == W + "tbl":
+                grid = element.find(W + "tblGrid")
+                tables.append({"part": part, "row_count": len(element.findall(W + "tr")),
+                               "column_count": len(grid) if grid is not None else None})
+            if element.tag not in {A + "blip", V + "imagedata"}:
+                continue
+            rid = element.get(R + "embed") or element.get(R + "link") or element.get(R + "id")
+            rel = relationships.get(rid)
+            if rel is None:
+                images.append({"part": part, "relationship_id": rid, "status": "missing_relationship"})
+                continue
+            target = rel.get("Target", "")
+            external = rel.get("TargetMode") == "External"
+            target_part = None if external else posixpath.normpath(posixpath.join(posixpath.dirname(part), target)).lstrip("/")
+            images.append({"part": part, "relationship_id": rid, "target": target,
+                           "external": external, "package_part": target_part,
+                           "status": "external" if external else "embedded" if target_part in parts else "missing_part"})
+    settings = _xml(parts["word/settings.xml"]) if "word/settings.xml" in parts else None
+    update = settings.find(W + "updateFields") if settings is not None else None
+    report = {"path": str(package.path), "revision": package.revision,
+              "field_count": len(fields), "toc_count": sum(field["type"] == "TOC" for field in fields),
+              "image_count": len(images), "table_count": len(tables),
+              "update_fields_on_open": update is not None and update.get(W + "val", "true") not in {"false", "0", "off"},
+              "rendered_layout_verified": False}
+    for name, items in (("fields", fields), ("images", images), ("tables", tables)):
+        if scope in {"all", name}:
+            selected = items[offset - 1:offset - 1 + limit]
+            report[name] = {"items": selected, "next_offset": offset + len(selected) if offset - 1 + len(selected) < len(items) else None}
+    return report

licos_dev_sdk-0.4.4/src/licos_dev_sdk/document_docx_preservation.py

@@ -0,0 +1,27 @@
+"""Compare untouched DOCX parts and section settings against an original file."""
+
+from docx.oxml.ns import qn
+from lxml import etree
+
+from .document_docx_package import DOCUMENT_XML, DocxPackage
+
+
+def compare_docx_preservation(current: DocxPackage, original: DocxPackage) -> dict:
+    if current.path.samefile(original.path):
+        raise ValueError("original must be a separate, unmodified document")
+    before = {info.filename: data for info, data in original.parts if info.filename != DOCUMENT_XML}
+    after = {info.filename: data for info, data in current.parts if info.filename != DOCUMENT_XML}
+    missing = sorted(before.keys() - after.keys())
+    added = sorted(after.keys() - before.keys())
+    changed = sorted(name for name in before.keys() & after.keys() if before[name] != after[name])
+
+    def sections(package):
+        return [etree.tostring(node, method="c14n", exclusive=True)
+                for node in package.root.iter(qn("w:sectPr"))]
+
+    sections_unchanged = sections(current) == sections(original)
+    return {"original": str(original.path), "compared_parts": len(before),
+            "excluded_parts": [DOCUMENT_XML], "missing_parts": missing,
+            "added_parts": added, "changed_parts": changed,
+            "section_properties_unchanged": sections_unchanged,
+            "verified": not (missing or added or changed) and sections_unchanged}

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.4}/src/licos_dev_sdk/document_docx_structure.py

@@ -10,6 +10,7 @@ from docx.oxml.ns import qn
 from lxml import etree
 
 from .document_docx_package import DocxPackage
+from .document_docx_preservation import compare_docx_preservation
 from .document_docx_table import parse_table
 
 TEXT_TAGS = {qn("w:t"): None, qn("w:tab"): "\t", qn("w:br"): "\n", qn("w:cr"): "\n"}
@@ -69,16 +70,23 @@ def read_docx_structure(source: str | Path, *, scope: str = "blocks", offset: in
     _index(offset, "offset")
     _index(limit, "limit")
     _index(max_chars, "max_chars")
-    if scope not in {"blocks", "paragraphs"}:
-        raise ValueError("scope must be blocks or paragraphs")
+    if scope not in {"blocks", "paragraphs", "tables"}:
+        raise ValueError("scope must be blocks, paragraphs or tables")
     package = DocxPackage(source)
     structure = _Structure(package.root)
-    elements = structure.blocks if scope == "blocks" else structure.paragraphs
+    elements = {"blocks": structure.blocks, "paragraphs": structure.paragraphs, "tables": structure.tables}[scope]
     items = []
     for number, element in enumerate(elements[offset - 1:offset - 1 + limit], offset):
         text = _text(element)
-        items.append({"target": {scope[:-1]: number}, "type": etree.QName(element).localname,
-                      "text": text[:max_chars], "content_truncated": len(text) > max_chars})
+        item = {"target": {"paragraph" if scope == "paragraphs" else "block":
+                           number if scope != "tables" else structure.blocks.index(element) + 1},
+                "type": etree.QName(element).localname,
+                "text": text[:max_chars], "content_truncated": len(text) > max_chars}
+        if element.tag == qn("w:tbl"):
+            model = parse_table(element, include_nested=False)
+            item.update(table=structure.tables.index(element) + 1, row_count=len(model.rows),
+                        column_count=model.column_count)
+        items.append(item)
     next_offset = offset + len(items)
     return {"path": str(package.path), "revision": package.revision, "scope": scope,
             "coordinate_systems": {"block": "top-level body blocks; a table is one block",
@@ -193,7 +201,8 @@ def delete_docx_blocks(source: str | Path, output: str | Path, *, revision: str,
                                operations=[{"op": "delete_blocks", "from": first, "to": last}])
 
 
-def verify_docx(source: str | Path, *, expectations: list[dict] | None = None) -> dict:
+def verify_docx(source: str | Path, *, expectations: list[dict] | None = None,
+                original: str | Path | None = None, base_dir: str | Path = ".") -> dict:
     """Check package structure and exact positions; absent assertions do not certify content."""
     package = DocxPackage(source)
     structure = _Structure(package.root)
@@ -203,17 +212,18 @@ def verify_docx(source: str | Path, *, expectations: list[dict] | None = None) -
     if not isinstance(expectations, list):
         raise TypeError("expectations must be an array")
     mismatches = []
+    from .document_docx_expectations import expected_text
     for index, expectation in enumerate(expectations, 1):
-        if not isinstance(expectation, dict) or not {"target", "text"} <= set(expectation) or set(expectation) - {"target", "text", "mode"}:
-            raise ValueError(f"expectation {index} requires target,text and optional mode")
-        expected, mode = expectation["text"], expectation.get("mode", "equals")
-        if not isinstance(expected, str) or mode not in {"equals", "contains", "absent"}:
-            raise ValueError(f"expectation {index}: text must be a string; mode must be equals, contains or absent")
+        expected, mode = expected_text(expectation, index, base_dir)
         actual = _text(structure.target(expectation["target"]))
         passed = actual == expected if mode == "equals" else expected in actual if mode == "contains" else expected not in actual
         if not passed:
             mismatches.append({"index": index, "target": expectation["target"], "mode": mode, "expected": expected,
                                "actual": actual[:1000], "actual_truncated": len(actual) > 1000})
+    preservation = compare_docx_preservation(package, DocxPackage(original)) if original is not None else None
     return {"path": str(package.path), "revision": package.revision, "structure_verified": True,
-            "content_verified": bool(expectations) and not mismatches, "verified": not mismatches,
+            "content_verified": bool(expectations) and not mismatches,
+            "preservation_verified": preservation is not None and preservation["verified"],
+            "preservation": preservation,
+            "verified": not mismatches and (preservation is None or preservation["verified"]),
             "expectation_count": len(expectations), "mismatches": mismatches}

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.4}/src/licos_dev_sdk/document_docx_table_actions.py

@@ -5,6 +5,7 @@ from pathlib import Path
 from .document_docx_edit import _apply_operation
 from .document_docx_package import DocxPackage
 from .document_docx_structure import _Structure, _index
+from .document_docx_table import parse_table
 
 
 def set_docx_cell(source: str | Path, output: str | Path, *, revision: str,
@@ -19,15 +20,27 @@ def set_docx_cell(source: str | Path, output: str | Path, *, revision: str,
 
 
 def insert_docx_rows(source: str | Path, output: str | Path, *, revision: str,
-                     table: int, before: int, rows: list[list], template_row: int,
+                     table: int, rows: list[list], template_row: int,
+                     before: int | None = None, append: bool = False,
                      overwrite: bool = False) -> dict:
-    """Clone a template row for each row of scalar values; count is derived from rows."""
-    for name, value in (("table", table), ("before", before), ("template_row", template_row)):
+    """Clone styled rows at an explicit position or append to the current table."""
+    if type(append) is not bool:
+        raise TypeError("append must be a boolean")
+    if (before is not None) == append:
+        raise ValueError("provide exactly one of before and append=True")
+    for name, value in (("table", table), ("template_row", template_row)):
         _index(value, name)
+    if before is not None:
+        _index(before, "before")
     if not isinstance(rows, list) or not 1 <= len(rows) <= 200:
         raise ValueError("rows must contain 1-200 row arrays")
     package = DocxPackage(source)
     package.require_revision(revision)
+    if append:
+        tables = _Structure(package.root).tables
+        if table > len(tables):
+            raise ValueError(f"table {table} does not exist")
+        before = len(parse_table(tables[table - 1], include_nested=False).rows) + 1
     _apply_operation(package.root, {"op": "insert_rows", "table": table, "before": before,
                                    "template_row": template_row, "count": len(rows), "rows": rows})
     return {**package.save(output, overwrite=overwrite), "inserted_rows": len(rows)}

licos_dev_sdk-0.4.4/tests/test_docx_inspect.py

@@ -0,0 +1,113 @@
+import base64
+from io import BytesIO
+from zipfile import ZipFile
+
+from docx import Document
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+import pytest
+
+from licos_dev_sdk import inspect_docx, verify_docx
+
+
+def field_run(paragraph, tag, value):
+    element = OxmlElement('w:' + tag)
+    if tag == 'instrText':
+        element.text = value
+    else:
+        element.set(qn('w:fldCharType'), value)
+    paragraph.add_run()._r.append(element)
+
+
+def test_inspect_native_fields_images_and_tables_without_rewriting(tmp_path):
+    path = tmp_path / 'report.docx'
+    doc = Document()
+    p = doc.add_paragraph()
+    field_run(p, 'fldChar', 'begin')
+    field_run(p, 'instrText', ' TO')
+    field_run(p, 'instrText', 'C \\o "1-3" ')
+    field_run(p, 'fldChar', 'separate')
+    p.add_run('Cached table of contents')
+    field_run(p, 'fldChar', 'end')
+    simple = OxmlElement('w:fldSimple')
+    simple.set(qn('w:instr'), 'PAGE')
+    doc.sections[0].footer.paragraphs[0]._p.append(simple)
+    png = base64.b64decode('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aTtQAAAAASUVORK5CYII=')
+    doc.add_picture(BytesIO(png))
+    doc.sections[0].header.paragraphs[0].add_run().add_picture(BytesIO(png))
+    doc.add_table(rows=3, cols=2)
+    update = OxmlElement('w:updateFields')
+    update.set(qn('w:val'), 'true')
+    doc.settings.element.append(update)
+    doc.save(path)
+    original = path.read_bytes()
+    report = inspect_docx(path, limit=1)
+    assert report['toc_count'] == 1 and report['field_count'] == 2
+    assert report['image_count'] == 2 and report['table_count'] == 1
+    assert report['fields']['items'][0]['complete']
+    assert report['fields']['items'][0]['instruction'] == ' TOC \\o "1-3" '
+    assert report['images']['next_offset'] == 2
+    assert report['tables']['items'][0] == {'part': 'word/document.xml', 'row_count': 3, 'column_count': 2}
+    second = inspect_docx(path, scope='images', offset=2)
+    assert second['images']['items'][0]['part'].startswith('word/header')
+    assert second['images']['items'][0]['status'] == 'embedded'
+    assert 'fields' not in second
+    assert report['update_fields_on_open'] and not report['rendered_layout_verified']
+    assert path.read_bytes() == original
+    with ZipFile(path) as archive:
+        parts = {name: archive.read(name) for name in archive.namelist()}
+    image_part = report['images']['items'][0]['package_part']
+    parts.pop(image_part)
+    with ZipFile(path, 'w') as archive:
+        for name, data in parts.items():
+            archive.writestr(name, data)
+    assert inspect_docx(path)['images']['items'][0]['status'] == 'missing_part'
+
+
+def test_incomplete_toc_and_external_or_missing_image_relationships(tmp_path):
+    path = tmp_path / 'linked.docx'
+    doc = Document()
+    p = doc.add_paragraph()
+    field_run(p, 'fldChar', 'begin')
+    field_run(p, 'instrText', 'TOC')
+    rid = doc.part.relate_to('https://example.com/image.png',
+                            'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image', is_external=True)
+    for relationship in (rid, 'missing'):
+        blip = OxmlElement('a:blip')
+        blip.set(qn('r:link'), relationship)
+        p.add_run()._r.append(blip)
+    doc.save(path)
+    report = inspect_docx(path)
+    assert not report['fields']['items'][0]['complete']
+    assert [image['status'] for image in report['images']['items']] == ['external', 'missing_relationship']
+
+
+def test_batch_file_assertions_resolve_from_explicit_base_and_keep_exact_text(tmp_path, monkeypatch):
+    path = tmp_path / 'report.docx'
+    text = '  中文🙂\tA\n' * 90 + '  '
+    doc = Document()
+    doc.add_paragraph(text)
+    doc.save(path)
+    expected = tmp_path / 'expected.txt'
+    expected.write_text(text, encoding='utf-8')
+    monkeypatch.chdir(tmp_path.parent)
+    assertion = {'target': {'block': 1}, 'text_file': 'expected.txt'}
+    assert verify_docx(path, expectations=[assertion], base_dir=tmp_path)['verified']
+    assertion['text_file'] = str(expected)
+    assert verify_docx(path, expectations=[assertion])['verified']
+
+
+@pytest.mark.parametrize(('assertion', 'error'), [
+    ({'text-file': 'x.txt'}, 'unknown fields text-file'),
+    ({'text': 'x', 'text_file': 'x.txt'}, 'exactly one'),
+    ({'text_file': None}, 'text_file must be'),
+    ({'text_file': 'missing.txt'}, 'expectation 1.text_file'),
+    ({'text': '', 'mode': []}, 'mode must be'),
+])
+def test_invalid_assertions_report_precise_schema_field(tmp_path, assertion, error):
+    path = tmp_path / 'report.docx'
+    doc = Document()
+    doc.add_paragraph('')
+    doc.save(path)
+    with pytest.raises(ValueError, match=error):
+        verify_docx(path, expectations=[{'target': {'block': 1}, **assertion}], base_dir=tmp_path)

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.4}/tests/test_docx_structure.py

@@ -202,3 +202,87 @@ def test_simple_cell_set_uses_revision_and_preserves_style(source, tmp_path):
     set_docx_cell(source, output, revision=rev(source), table=1, row=2, column=1, text="新值")
     assert Document(output).tables[0].cell(1, 0).text == "新值"
     assert Document(output).tables[0].cell(1, 0).paragraphs[0].runs[0].bold
+
+
+def test_table_discovery_returns_body_target_and_current_dimensions(source, tmp_path):
+    doc = Document(source)
+    doc.add_table(rows=3, cols=2)
+    doc.save(source)
+    first = read_docx_structure(source, scope="tables", limit=1)
+    item = first["items"][0]
+    assert (item["target"], item["table"], item["row_count"], item["column_count"]) == ({"block": 3}, 1, 2, 3)
+    assert read_docx_structure(source)["items"][2] == item
+    second = read_docx_structure(source, scope="tables", offset=first["next_offset"], limit=1)
+    item = second["items"][0]
+    assert (item["target"], item["table"], item["row_count"], item["column_count"]) == ({"block": 6}, 2, 3, 2)
+    assert not second["has_more"]
+    assert read_docx_target(source, item["target"])["text"] == item["text"]
+
+
+def test_explicit_append_uses_current_revision_and_preserves_merged_template(source, tmp_path):
+    first, second = tmp_path / "first.docx", tmp_path / "second.docx"
+    insert_docx_rows(source, first, revision=rev(source), table=1, append=True, template_row=2, rows=[["泵", "台", 2]])
+    insert_docx_rows(first, second, revision=rev(first), table=1, append=True, template_row=1, rows=[["合并尾行", 9]])
+    table = Document(second).tables[0]
+    assert len(table.rows) == 4
+    assert table.cell(2, 0).text == "泵" and table.cell(2, 0).paragraphs[0].runs[0].bold
+    assert table.cell(3, 0).text == table.cell(3, 1).text == "合并尾行"
+    assert_parts_preserved(source, second)
+    with pytest.raises(ValueError, match="revision"):
+        insert_docx_rows(first, tmp_path / "stale.docx", revision=rev(source), table=1, append=True, template_row=2, rows=[["a", "b", 1]])
+    assert not (tmp_path / "stale.docx").exists()
+
+
+@pytest.mark.parametrize("position", [{}, {"before": 3, "append": True}, {"before": True}, {"append": 1}])
+def test_insert_requires_one_explicit_position(source, tmp_path, position):
+    output = tmp_path / "bad.docx"
+    with pytest.raises((ValueError, TypeError)):
+        insert_docx_rows(source, output, revision=rev(source), table=1, template_row=2, rows=[["a", "b", 1]], **position)
+    assert not output.exists()
+
+
+def test_original_comparison_certifies_parts_and_sections_but_requires_content_assertions(source, tmp_path):
+    output = tmp_path / "edited.docx"
+    replace_docx_text(source, output, revision=rev(source), target={"block": 2}, search="123456", replacement="新账号")
+    report = verify_docx(output, original=source)
+    assert report["verified"] and report["preservation_verified"]
+    assert report["preservation"]["section_properties_unchanged"]
+    assert not report["content_verified"]
+    assert not verify_docx(output, original=source, expectations=[{"target": {"block": 2}, "text": "错误"}])["verified"]
+    with pytest.raises(ValueError, match="separate"):
+        verify_docx(output, original=output)
+
+
+@pytest.mark.parametrize("mutation,part,field", [
+    ("change", "word/header1.xml", "changed_parts"),
+    ("change", "word/styles.xml", "changed_parts"),
+    ("remove", "word/header1.xml", "missing_parts"),
+    ("add", "word/media/extra.png", "added_parts"),
+])
+def test_original_comparison_detects_changes_outside_body(source, tmp_path, mutation, part, field):
+    output = tmp_path / "changed.docx"
+    with ZipFile(source) as before, ZipFile(output, "w") as after:
+        for info in before.infolist():
+            if mutation == "remove" and info.filename == part:
+                continue
+            data = before.read(info.filename)
+            after.writestr(info, data + b" " if mutation == "change" and info.filename == part else data)
+        if mutation == "add":
+            after.writestr(part, b"image")
+    report = verify_docx(output, original=source)
+    assert not report["verified"] and not report["preservation_verified"]
+    assert report["preservation"][field] == [part]
+
+
+def test_original_comparison_detects_section_layout_changes(source, tmp_path):
+    from licos_dev_sdk.document_docx_package import DocxPackage
+
+    package = DocxPackage(source)
+    section = next(package.root.iter(qn("w:sectPr")))
+    section.find(qn("w:pgMar")).set(qn("w:left"), "999")
+    output = tmp_path / "layout.docx"
+    package.save(output)
+    report = verify_docx(output, original=source)
+    assert not report["verified"]
+    assert not report["preservation"]["section_properties_unchanged"]
+    assert report["preservation"]["changed_parts"] == []

licos_dev_sdk-0.4.4/tests/test_html_docx_features.py

@@ -0,0 +1,46 @@
+"""Exercise the public HTML-to-Word API with actual document parts and images."""
+
+import base64
+from zipfile import ZipFile
+
+from docx import Document
+from docx.oxml.ns import qn
+from PIL import Image
+
+from licos_dev_sdk import create_docx
+
+
+def test_html_generates_native_toc_merged_table_and_embedded_images(tmp_path):
+    picture = tmp_path / "figure.png"
+    Image.new("RGB", (80, 40), "#145DA0").save(picture)
+    encoded = base64.b64encode(picture.read_bytes()).decode("ascii")
+    html = f'''<html><head><style>
+      th {{ background-color: #145DA0; color: #ffffff; }}
+      td {{ border: 1px solid #333333; }}
+    </style></head><body>
+      <h1>测试报告</h1><h2>设备统计</h2><h3>设备清单</h3>
+      <table><tr><th colspan="2">设备</th><th>数量</th></tr>
+        <tr><td rowspan="2">泵组</td><td>离心泵</td><td>2</td></tr>
+        <tr><td>阀门</td><td>3</td></tr></table>
+      <p><img src="figure.png" width="160" alt="本地图片"></p>
+      <p><img src="data:image/png;base64,{encoded}" width="160" alt="内嵌图片"></p>
+    </body></html>'''
+    output = create_docx(html, "report", content_type="html", output_dir=str(tmp_path),
+                         asset_base_path=str(tmp_path), include_toc=True, header="内部资料", footer="测试页脚")
+    document = Document(output)
+    assert [p.text for p in document.paragraphs if p.style.name.startswith("Heading")] == ["测试报告", "设备统计", "设备清单"]
+    fields = [n.text for n in document.element.iter(qn("w:instrText"))]
+    assert any('TOC \\o "1-3"' in text for text in fields)
+    assert document.settings.element.find(qn("w:updateFields")).get(qn("w:val")) == "true"
+    table = document.tables[0]
+    assert len(table.rows) == 3 and len(table.columns) == 3
+    assert table.cell(0, 0)._tc is table.cell(0, 1)._tc
+    assert table.cell(1, 0)._tc is table.cell(2, 0)._tc
+    assert table.cell(2, 1).text == "阀门" and table.cell(2, 2).text == "3"
+    assert 'w:fill="145DA0"' in table.cell(0, 0)._tc.xml
+    assert len(document.inline_shapes) == 2
+    assert "内部资料" in document.sections[0].header.paragraphs[0].text
+    assert "测试页脚" in document.sections[0].footer.paragraphs[0].text
+    with ZipFile(output) as archive:
+        images = [archive.read(name) for name in archive.namelist() if name.startswith("word/media/")]
+    assert picture.read_bytes() in images