doc-control 0.0.1.dev0__py3-none-any.whl

doc_control/ops/revision.py

@@ -0,0 +1,616 @@
+"""``revision.accept`` and ``revision.reject``: resolve tracked changes in one verified write.
+
+Both are batch operations (``batch`` with ``{"op": "revision.accept", ...}``); they work on
+revisions the tool wrote and on revisions the document already had, whoever the author.
+
+Selection (at least one; they narrow each other)
+    ``ids``     revision ids as ``revisions.list`` reports them;
+    ``author``  the exact ``w:author`` value (``Claude (tag)`` for a tagged call);
+    ``at``      a paragraph address ``p3#fp`` or a run ``p3#fp..p9#fp`` (inclusive);
+    ``all``     true: every revision.
+
+What happens is described in :mod:`doc_control.ooxml.resolve`. In short: an insertion or
+move-in is kept (accept) or removed (reject), a deletion or move-away the other way
+round; a formatting change keeps the new (accept) or restores the recorded (reject)
+properties; a paragraph mark that goes away joins the paragraph with the next one in
+its container (the next paragraph's properties win, as in Word). A move is two
+revisions, ``move_from`` and ``move_to``: select both. The last paragraph of a cell or
+of the body, and a paragraph that ends a section, cannot lose its mark: it stays,
+and the response says so in ``warnings``.
+
+Several operations in one batch are all resolved against the document as read; the
+same revision accepted by one and rejected by another is a ``BATCH_CONFLICT``. They
+cannot be combined with text edits (``BATCH_CONFLICT``): addresses would shift.
+
+Table row and cell revisions (``w:trPr``/``w:tcPr``) and revisions inside text boxes
+are not resolved; selecting them by id is ``UNSUPPORTED_CONTENT``, and with other
+selectors they are left as they are and a warning names the fact.
+
+Before the write the result is checked: no revision appears that was not there, the
+selected ones are gone, the paragraph count is right, accepting insertions and
+deletions leaves every paragraph's current text unchanged (merged as the marks say) and
+no field is left open. A failed check raises ``INTERNAL`` and nothing is written.
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from collections import Counter
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field, replace
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from doc_control.errors import DocControlError, ErrorCode
+from doc_control.model.index import DocumentIndex, Paragraph, build_index
+from doc_control.ooxml import resolve as xml
+from doc_control.ooxml.revisions import PPR
+from doc_control.ooxml.zipio import Package
+from doc_control.ops.tracked import next_in_container
+from doc_control.safety.history import has_live_text, record, to_text
+from doc_control.safety.lock import check_changed, check_unlocked
+from doc_control.safety.verify import DOCUMENT_PART, Footprint, write_verified
+from doc_control.schema import validate
+
+__all__ = [
+    "OPERATION_SCHEMAS",
+    "PreparedResolution",
+    "ResolutionResult",
+    "ResolveRevisions",
+    "apply_resolutions",
+    "prepare_resolutions",
+    "resolution_from_dict",
+]
+
+LISTED = 100  # revisions named one by one in a response
+_REVISION_TAG = re.compile(rb"<(?:[\w.-]+:)?(?:ins|del|moveFrom|moveTo|rPrChange|pPrChange)[\s/>]")
+_TABLE_REVISION = re.compile(
+    rb"<(?:[\w.-]+:)?(?:cellIns|cellDel|cellMerge)[\s/>]"
+    rb"|<(?:[\w.-]+:)?trPr[\s>](?:(?!</(?:[\w.-]+:)?trPr>).)*?<(?:[\w.-]+:)?(?:ins|del)[\s/>]",
+    re.DOTALL,
+)
+_MOVE_RANGE = re.compile(rb"<(?:[\w.-]+:)?move(?:From|To)Range(?:Start|End)[\s/>]")
+_FIELD_CHAR = re.compile(rb"fldCharType\s*=\s*[\"'](begin|end)[\"']")
+_MARK_KINDS = frozenset({"mark_insert", "mark_delete", "mark_move_from", "mark_move_to"})
+_TEXT_NEUTRAL = frozenset(
+    {"insert", "delete", "format", "mark_insert", "mark_delete", "mark_format", "paragraph_format"}
+)
+
+
+def _schema(action: str, what: str) -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {
+            "op": {"enum": [f"revision.{action}"]},
+            "ids": {
+                "type": "array",
+                "items": {"type": ["string", "integer"]},
+                "description": f"{what} the revisions with these ids (from revisions.list).",
+            },
+            "author": {"type": "string", "minLength": 1, "description": "Exact revision author."},
+            "at": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Paragraph p3#fp or run p3#fp..p9#fp.",
+            },
+            "all": {"type": "boolean", "description": "true: every revision in the document."},
+        },
+        "required": ["op"],
+        "additionalProperties": False,
+    }
+
+
+OPERATION_SCHEMAS: dict[str, dict[str, Any]] = {
+    "revision.accept": _schema("accept", "Accept"),
+    "revision.reject": _schema("reject", "Reject"),
+}
+
+
+@dataclass(frozen=True)
+class ResolveRevisions:
+    action: str  # "accept" | "reject"
+    ids: tuple[str, ...] | None = None
+    author: str | None = None
+    at: str | None = None
+    all: bool = False
+
+
+def resolution_from_dict(raw: Mapping[str, Any]) -> ResolveRevisions:
+    """Validate a ``revision.accept``/``revision.reject`` object and build the operation."""
+    op = raw.get("op")
+    if not isinstance(op, str) or op not in OPERATION_SCHEMAS:
+        raise DocControlError(
+            ErrorCode.SCHEMA_INVALID,
+            f"unknown revision operation: {op!r}",
+            expected=sorted(OPERATION_SCHEMAS),
+        )
+    validate(dict(raw), OPERATION_SCHEMAS[op])
+    ids = raw.get("ids")
+    if ids is not None and not ids:
+        raise DocControlError(ErrorCode.SCHEMA_INVALID, f"{op}: 'ids' must not be empty")
+    everything = raw.get("all") is True
+    if ids is None and raw.get("author") is None and raw.get("at") is None and not everything:
+        raise DocControlError(
+            ErrorCode.SCHEMA_INVALID,
+            f"{op} needs a selection: 'ids', 'author', 'at' or 'all': true",
+        )
+    return ResolveRevisions(
+        op.removeprefix("revision."),
+        tuple(str(i).strip() for i in ids) if ids is not None else None,
+        raw.get("author"),
+        raw.get("at"),
+        everything,
+    )
+
+
+# -- results ------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ResolutionResult:
+    applied: int
+    dry_run: bool
+    preview: list[dict[str, Any]]
+    revisions: list[dict[str, str]]
+    accepted: int
+    rejected: int
+    merged_paragraphs: int
+    address_map: dict[str, str]
+    footprint: list[str]
+    before_sha256: str
+    after_sha256: str | None = None
+    backup: Path | None = None
+    warnings: list[str] = field(default_factory=list)
+    op_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "applied": self.applied,
+            "dry_run": self.dry_run,
+            "preview": self.preview,
+            "accepted": self.accepted,
+            "rejected": self.rejected,
+            "revisions": self.revisions,
+            "merged_paragraphs": self.merged_paragraphs,
+            "address_map": self.address_map,
+            "footprint": {DOCUMENT_PART: self.footprint},
+        }
+        if self.accepted + self.rejected > len(self.revisions):
+            out["revisions_omitted"] = self.accepted + self.rejected - len(self.revisions)
+        if self.warnings:
+            out["warnings"] = self.warnings
+        if not self.dry_run:
+            out["sha256"] = self.after_sha256
+            out["backup"] = str(self.backup) if self.backup else None
+            if self.op_id:
+                out["op_id"] = self.op_id
+        return out
+
+
+@dataclass(frozen=True)
+class PreparedResolution:
+    """The resolved ``word/document.xml`` of a package, checked but not written."""
+
+    pkg: Package
+    new_data: bytes | None  # None: nothing to change
+    footprint: Footprint
+    result: ResolutionResult
+    changes: list[dict[str, Any]] = field(default_factory=list)
+    """The undo-log record: each rewritten paragraph's bytes before and after."""
+    joined: bool = False  # paragraphs were merged; the log cannot restore them
+
+
+# -- selection --------------------------------------------------------------------------
+
+
+@dataclass(eq=False)
+class _Parsed:
+    para: Paragraph
+    elem: ET.Element
+    revs: list[xml.Revision]
+
+
+def _parse_revisions(index: DocumentIndex) -> list[_Parsed]:
+    spans = index.spans
+    out: list[_Parsed] = []
+    for para in index.paragraphs:
+        if not _REVISION_TAG.search(spans.paragraph_bytes(para.span_index)):
+            continue
+        elem = spans.parse_paragraph(para.span_index)
+        revs = xml.scan(elem)
+        if revs:
+            out.append(_Parsed(para, elem, revs))
+    return out
+
+
+def _range(index: DocumentIndex, at: str) -> tuple[int, int]:
+    first, sep, last = at.partition("..")
+    a = index.resolve_address(first)
+    if not sep:
+        return a.number, a.number
+    b = index.resolve_address(last)
+    if b.number < a.number:
+        raise DocControlError(
+            ErrorCode.ADDRESS_INVALID, f"{at!r} ends before it starts", address=at
+        )
+    return a.number, b.number
+
+
+def _table_revisions(data: bytes) -> bool:
+    return _TABLE_REVISION.search(data) is not None
+
+
+def _select(
+    op: ResolveRevisions, index: DocumentIndex, parsed: Sequence[_Parsed], table: bool
+) -> list[tuple[_Parsed, xml.Revision]]:
+    low, high = _range(index, op.at) if op.at is not None else (0, len(index))
+    if op.ids is not None:
+        known = {r.id for p in parsed for r in p.revs}
+        for missing in [i for i in op.ids if i not in known]:
+            if table:
+                raise DocControlError(
+                    ErrorCode.UNSUPPORTED_CONTENT,
+                    f"no paragraph revision has id {missing}; table row and cell revisions "
+                    "are not resolved by this operation",
+                    revision=missing,
+                )
+            raise DocControlError(
+                ErrorCode.STALE_ADDRESS,
+                f"the document has no revision with id {missing}",
+                revision=missing,
+            )
+    wanted = set(op.ids) if op.ids is not None else None
+    return [
+        (p, r)
+        for p in parsed
+        if low <= p.para.number <= high
+        for r in p.revs
+        if (wanted is None or r.id in wanted) and (op.author is None or r.author == op.author)
+    ]
+
+
+# -- preparing ------------------------------------------------------------------------------
+
+
+def _fields_balanced(data: bytes) -> bool:
+    kinds = [m.group(1) for m in _FIELD_CHAR.finditer(data)]
+    return kinds.count(b"begin") == kinds.count(b"end")
+
+
+def _with_content(elem: ET.Element, content: list[ET.Element]) -> None:
+    """Put ``content`` first among the paragraph's content (after its properties)."""
+    at = 1 if len(elem) and elem[0].tag == PPR else 0
+    elem[at:at] = content
+
+
+def prepare_resolutions(
+    pkg: Package,
+    ops: Sequence[ResolveRevisions],
+    *,
+    dry_run: bool = False,
+    index: DocumentIndex | None = None,
+) -> PreparedResolution:
+    """Plan and build ``ops`` on ``pkg`` without writing: the part of
+    :func:`apply_resolutions` that works on bytes, self-checked (see the module docstring)."""
+    if not ops:
+        raise DocControlError(ErrorCode.SCHEMA_INVALID, "no operations given")
+    if index is None:
+        index = DocumentIndex.from_package(pkg)
+    spans = index.spans
+    parsed = _parse_revisions(index)
+    table = _table_revisions(spans.data)
+
+    chosen: dict[tuple[int, int], tuple[str, int]] = {}  # (paragraph, position) -> (action, op)
+    preview: list[dict[str, Any]] = []
+    where = {id(r): (p, k) for p in parsed for k, r in enumerate(p.revs)}
+    for i, op in enumerate(ops):
+        picked = _select(op, index, parsed, table)
+        for p, r in picked:
+            key = (p.para.number, where[id(r)][1])
+            old = chosen.get(key)
+            if old is not None and old[0] != op.action:
+                raise DocControlError(
+                    ErrorCode.BATCH_CONFLICT,
+                    f"edits {old[1]} and {i} accept and reject the same revision "
+                    f"({r.kind} {r.id}) in {p.para.address}",
+                    paragraph=str(p.para.address),
+                    revision=r.id,
+                    edits=sorted((old[1], i)),
+                )
+            chosen.setdefault(key, (op.action, i))
+        preview.append({"op": i, "action": op.action, "revisions": len(picked)})
+
+    warnings: list[str] = []
+    if table:
+        warnings.append(
+            "table row and cell revisions are not resolved by this operation; they stay as they are"
+        )
+
+    # Decide, paragraph by paragraph.
+    removed_marks: set[int] = set()  # paragraph numbers whose mark a decision removes
+    touched: dict[int, _Parsed] = {}
+    for p in parsed:
+        actions = {
+            id(r.elem): chosen[(p.para.number, k)][0]
+            for k, r in enumerate(p.revs)
+            if (p.para.number, k) in chosen
+        }
+        if not actions:
+            continue
+        if xml.resolve_paragraph(p.elem, actions):
+            removed_marks.add(p.para.number)
+        touched[p.para.number] = p
+
+    elems: dict[int, ET.Element] = {n: p.elem for n, p in touched.items()}
+
+    # Move range markers whose side has no revision left mean nothing: drop them.
+    left = {
+        "from" if r.kind.endswith("move_from") else "to"
+        for p in parsed
+        for k, r in enumerate(p.revs)
+        if r.kind.endswith(("move_from", "move_to")) and (p.para.number, k) not in chosen
+    }
+    cleared = {"from", "to"} - left
+    if cleared:
+        for para in index.paragraphs:
+            raw = spans.paragraph_bytes(para.span_index)
+            if _MOVE_RANGE.search(raw):
+                elem = elems.get(para.number)
+                if elem is None:
+                    elem = spans.parse_paragraph(para.span_index)
+                if xml.drop_move_markers(elem, cleared):
+                    elems[para.number] = elem
+
+    # Join paragraphs whose mark went away with the one after them.
+    carry: dict[int, list[ET.Element]] = {}
+    gone: set[int] = set()  # paragraph numbers merged into the next
+    for number in sorted(removed_marks):
+        para = index.paragraph(number)
+        elem = elems[number]
+        nxt = next_in_container(index, para)
+        inherited = carry.pop(number, [])
+        content = inherited + [c for c in elem if c.tag != PPR]
+        if nxt is None or elem.find(f"{PPR}/{xml.SECT_PR}") is not None:
+            _with_content(elem, inherited)  # nothing to join with: keep the mark
+            warnings.append(
+                f"{para.address} keeps its paragraph mark: it ends a container or a section"
+            )
+            continue
+        if nxt.number not in elems:
+            elems[nxt.number] = spans.parse_paragraph(nxt.span_index)
+        carry.setdefault(nxt.number, []).extend(content)
+        gone.add(number)
+    for number, content in carry.items():
+        _with_content(elems[number], content)
+
+    replacements: dict[int, bytes] = {}
+    deletes: set[int] = set()
+    for number, elem in elems.items():
+        span = index.paragraph(number).span_index
+        if number in gone:
+            deletes.add(span)
+        else:
+            replacements[span] = spans.serialize(elem, span)
+
+    footprint = Footprint(replaced=frozenset(replacements) | frozenset(deletes))
+    shown: list[dict[str, str]] = []
+    counts = Counter(action for action, _ in chosen.values())
+    for p in parsed:
+        for k, r in enumerate(p.revs):
+            if (p.para.number, k) in chosen and len(shown) < LISTED:
+                shown.append(
+                    {
+                        "id": r.id,
+                        "type": r.kind,
+                        "author": r.author,
+                        "at": str(p.para.address),
+                        "action": chosen[(p.para.number, k)][0],
+                    }
+                )
+    new_data: bytes | None = None
+    address_map: dict[str, str] = {}
+    foot = [f"p{n}" for n in sorted(elems)]
+    if elems:
+        new_data = spans.splice(replacements, delete=deletes)
+        new_index = _self_check(pkg, index, new_data, parsed, chosen, gone, touched)
+        address_map = _address_map(index, new_index, gone)
+        foot = [f"p{index.paragraph(n).number}" for n in sorted(elems)]
+    result = ResolutionResult(
+        applied=len(ops),
+        dry_run=dry_run,
+        preview=preview,
+        revisions=shown,
+        accepted=counts["accept"],
+        rejected=counts["reject"],
+        merged_paragraphs=len(gone),
+        address_map=address_map,
+        footprint=foot,
+        before_sha256=pkg.sha256,
+        warnings=warnings,
+    )
+    changes = [
+        {
+            "part": DOCUMENT_PART,
+            "kind": "replace",
+            "index": span,
+            "before": to_text(spans.paragraph_bytes(span)),
+            "after": to_text(data),
+            "text_before": next(p.text for p in index.paragraphs if p.span_index == span),
+            "deleted": not has_live_text(data),
+        }
+        for span, data in sorted(replacements.items())
+    ]
+    return PreparedResolution(pkg, new_data, footprint, result, changes, bool(gone))
+
+
+def _address_map(old: DocumentIndex, new: DocumentIndex, gone: set[int]) -> dict[str, str]:
+    """Old to new address of every paragraph whose number changed (a joined one: where it went)."""
+    out: dict[str, str] = {}
+    number = 0
+    pending: list[Paragraph] = []
+    for para in old.paragraphs:
+        if para.number in gone:
+            pending.append(para)
+            continue
+        number += 1
+        target = str(new.paragraph(number).address)
+        for p in [*pending, para]:
+            if str(p.address) != target and (p.number != number or p in pending):
+                out[str(p.address)] = target
+        pending = []
+    return out
+
+
+def _self_check(
+    pkg: Package,
+    old: DocumentIndex,
+    new_data: bytes,
+    parsed: Sequence[_Parsed],
+    chosen: Mapping[tuple[int, int], tuple[str, int]],
+    gone: set[int],
+    touched: Mapping[int, _Parsed],
+) -> DocumentIndex:
+    new = build_index(new_data)
+    if len(new) != len(old) - len(gone):
+        raise DocControlError(
+            ErrorCode.INTERNAL, "self-check: the resolved document has the wrong paragraph count"
+        )
+    before = Counter((r.id, r.kind, r.author) for p in parsed for r in p.revs)
+    picked = Counter(
+        (r.id, r.kind, r.author)
+        for p in parsed
+        for k, r in enumerate(p.revs)
+        if (p.para.number, k) in chosen
+    )
+    after: Counter[tuple[str, str, str]] = Counter()
+    for _, elem in _revision_paragraphs(new):
+        after.update((r.id, r.kind, r.author) for r in xml.scan(elem))
+    for key, n in after.items():
+        if n > max(0, before[key] - picked[key]):
+            raise DocControlError(
+                ErrorCode.INTERNAL, "self-check: a selected revision is still in the document"
+            )
+    old_data = old.spans.data
+    if _fields_balanced(old_data) and not _fields_balanced(new_data):
+        raise DocControlError(
+            ErrorCode.UNSUPPORTED_CONTENT,
+            "resolving these revisions would leave a field open: a deletion cuts through one",
+        )
+    kinds = {r.kind for p in parsed for k, r in enumerate(p.revs) if (p.para.number, k) in chosen}
+    actions = {a for a, _ in chosen.values()}
+    if actions == {"accept"} and kinds <= _TEXT_NEUTRAL:
+        expected = _joined(
+            [p.text for p in old.paragraphs], [p.number in gone for p in old.paragraphs]
+        )
+        if expected != [p.text for p in new.paragraphs]:
+            raise DocControlError(
+                ErrorCode.INTERNAL, "self-check: accepting changed the current text"
+            )
+    return new
+
+
+def _revision_paragraphs(index: DocumentIndex) -> list[tuple[Paragraph, ET.Element]]:
+    out: list[tuple[Paragraph, ET.Element]] = []
+    for para in index.paragraphs:
+        if _REVISION_TAG.search(index.spans.paragraph_bytes(para.span_index)):
+            out.append((para, index.spans.parse_paragraph(para.span_index)))
+    return out
+
+
+def _joined(texts: Sequence[str], joins: Sequence[bool]) -> list[str]:
+    out: list[str] = []
+    carry = ""
+    for text, join in zip(texts, joins, strict=True):
+        text = carry + text
+        if join:
+            carry = text
+        else:
+            out.append(text)
+            carry = ""
+    if carry:
+        out.append(carry)
+    return out
+
+
+# -- applying -----------------------------------------------------------------------------------
+
+
+def apply_resolutions(
+    doc_path: Path,
+    ops: Sequence[ResolveRevisions],
+    *,
+    expect_sha256: str | None = None,
+    now: datetime | None = None,
+    dry_run: bool = False,
+    env: Mapping[str, str] | None = None,
+    stage: Callable[[str], None] | None = None,
+) -> ResolutionResult:
+    """Resolve revisions in ``doc_path`` in one verified write.
+
+    Raises the errors of :func:`doc_control.ops.tracked.apply_edits` before touching the
+    file. When the selection matches nothing the file is not written.
+    """
+    if not ops:
+        raise DocControlError(ErrorCode.SCHEMA_INVALID, "no operations given")
+    if not doc_path.is_file():
+        raise DocControlError(
+            ErrorCode.DOC_NOT_FOUND, f"no such file: {doc_path}", path=str(doc_path)
+        )
+    if not dry_run:
+        check_unlocked(doc_path)
+    check_changed(doc_path, expect_sha256)
+    pkg = Package(doc_path)
+    prepared = prepare_resolutions(pkg, ops, dry_run=dry_run)
+    result = prepared.result
+    if dry_run or prepared.new_data is None:
+        return result
+    written = write_verified(
+        doc_path,
+        {DOCUMENT_PART: prepared.new_data},
+        prepared.footprint,
+        pkg.sha256,
+        now=now,
+        env=env,
+        stage=stage,
+    )
+    warnings = list(result.warnings)
+    op_id: str | None = None
+    try:
+        op_id = record(
+            doc_path,
+            "batch",
+            before_sha256=written.before_sha256,
+            after_sha256=written.after_sha256,
+            backup=written.backup,
+            changes=prepared.changes,
+            request=[_as_request(op) for op in ops],
+            footprint={DOCUMENT_PART: result.footprint},
+            # Joined paragraphs are not logged, so `undo` refuses this entry (safety.history).
+            extra={"parts": ["joined paragraphs"]} if prepared.joined else None,
+            now=now,
+            env=env,
+        )
+    except (DocControlError, OSError) as exc:
+        warnings.append(f"HISTORY_NOT_RECORDED: the write succeeded but could not be logged: {exc}")
+    return replace(
+        result,
+        before_sha256=written.before_sha256,
+        after_sha256=written.after_sha256,
+        backup=written.backup,
+        warnings=warnings,
+        op_id=op_id,
+    )
+
+
+def _as_request(op: ResolveRevisions) -> dict[str, Any]:
+    out: dict[str, Any] = {"op": f"revision.{op.action}"}
+    if op.ids is not None:
+        out["ids"] = list(op.ids)
+    for key in ("author", "at"):
+        if getattr(op, key) is not None:
+            out[key] = getattr(op, key)
+    if op.all:
+        out["all"] = True
+    return out