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

doc_control/ops/history.py

@@ -0,0 +1,479 @@
+"""History operations: ``open``, ``undo``, ``restore`` and ``history.*``.
+
+Everything here reads or writes the document's store (see :mod:`doc_control.safety.history`
+for the log format). ``undo`` takes back a logged ``batch`` or ``restore`` exactly (the
+paragraphs it changed return byte for byte, so text and paragraph properties are as they
+were) and is itself logged; it is untracked, since it removes the tool's own tracked
+changes. ``restore`` brings a logged paragraph back as a *tracked insertion* after the
+paragraph that holds its place now, so the writer sees it and can reject it. ``history.purge``
+removes history only after a dry run, and leaves a tombstone. Reading history never creates a
+store, and works for a document that no longer exists (or, with ``store``, straight from a
+store folder listed by ``history.orphans``).
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from doc_control.envelope import Reply
+from doc_control.errors import DocControlError, ErrorCode
+from doc_control.model.document import Document
+from doc_control.model.index import DocumentIndex
+from doc_control.ooxml.revisions import DEFAULT_AUTHOR
+from doc_control.ooxml.splice import scan
+from doc_control.ooxml.zipio import Package
+from doc_control.ops.tracked import InsertParagraph, apply_edits
+from doc_control.registry import operation
+from doc_control.safety import history
+from doc_control.safety.history import (
+    UNDOABLE_KINDS,
+    Log,
+    log_path_for,
+    read_log,
+    to_bytes,
+    undo_entry,
+)
+from doc_control.safety.store import backup, store_dir
+from doc_control.safety.verify import DOCUMENT_PART
+
+_DOC: dict[str, Any] = {"type": "string", "minLength": 1, "description": "Path to the .docx."}
+_STORE: dict[str, Any] = {
+    "type": "string",
+    "minLength": 1,
+    "description": "A store folder (see history.orphans) to read instead of the document's own.",
+}
+_OP_ID: dict[str, Any] = {"type": "string", "minLength": 3, "description": "Op id, e.g. h-000123."}
+_EXPECT: dict[str, Any] = {
+    "type": "object",
+    "properties": {"sha256": {"type": "string", "minLength": 1}},
+    "additionalProperties": False,
+}
+DEFAULT_LIMIT = 20
+MAX_LIMIT = 200
+PREVIEW = 120
+
+
+def _log(request: dict[str, Any]) -> Log:
+    """The log named by ``store`` or ``doc``; reading creates nothing."""
+    if "store" in request:
+        return read_log(Path(request["store"]) / "log.jsonl")
+    if "doc" in request:
+        return read_log(log_path_for(Path(request["doc"])))
+    raise DocControlError(ErrorCode.SCHEMA_INVALID, "give `doc` or `store`")
+
+
+def _doc_reply(path: str, result: dict[str, Any]) -> Reply:
+    return Reply(result, doc=Document(path).envelope_doc())
+
+
+def _short(text: str) -> str:
+    return text if len(text) <= PREVIEW else text[: PREVIEW - 1] + "…"
+
+
+# -- open -----------------------------------------------------------------------------------
+
+
+@operation(
+    "open",
+    "write",
+    "Back up the document into its store (retention applies) and note it in the history; "
+    "call it when a session starts. The document is not changed.",
+    {
+        "type": "object",
+        "properties": {"doc": _DOC},
+        "required": ["doc"],
+        "additionalProperties": False,
+    },
+)
+def open_(request: dict[str, Any]) -> Reply:
+    path = Path(request["doc"])
+    if not path.is_file():
+        raise DocControlError(ErrorCode.DOC_NOT_FOUND, f"no such file: {path}", path=str(path))
+    sha = Package(path).sha256  # NOT_A_DOCX for anything else, before a store is made
+    copy = backup(path)
+    seen = [e for e in read_log(log_path_for(path)).entries if e.get("kind") != "purge"]
+    op_id: str | None = None
+    if not seen or seen[-1].get("sha256_after") != sha:  # new to the history: note it
+        op_id = history.record(
+            path, "open", before_sha256=sha, after_sha256=sha, backup=copy, changes=[]
+        )
+    return _doc_reply(
+        str(path), {"backup": str(copy), "op_id": op_id, "store": str(store_dir(path))}
+    )
+
+
+# -- undo -----------------------------------------------------------------------------------
+
+
+def _undoable(entry: dict[str, Any]) -> bool:
+    return entry.get("kind") in UNDOABLE_KINDS and bool(entry.get("changes"))
+
+
+@operation(
+    "undo",
+    "write",
+    "Take back a logged batch or restore (the latest one that is still in effect by default), "
+    "returning its paragraphs to their prior state. Refused if they were edited since.",
+    {
+        "type": "object",
+        "properties": {
+            "doc": _DOC,
+            "op_id": {**_OP_ID, "description": "The op to undo (default: the latest in effect)."},
+            "expect": _EXPECT,
+            "dry_run": {"type": "boolean", "description": "Check and preview; write nothing."},
+        },
+        "required": ["doc"],
+        "additionalProperties": False,
+    },
+)
+def undo(request: dict[str, Any]) -> Reply:
+    path = Path(request["doc"])
+    log = read_log(log_path_for(path))
+    undone = log.undone()
+    op_id = request.get("op_id")
+    if op_id is None:
+        pending = [e for e in log.entries if _undoable(e) and e["op_id"] not in undone]
+        if not pending:
+            raise DocControlError(ErrorCode.HISTORY_NOT_FOUND, "nothing to undo")
+        entry = pending[-1]
+    else:
+        entry = log.get(op_id)
+        if not _undoable(entry):
+            raise DocControlError(
+                ErrorCode.HISTORY_NOT_FOUND,
+                f"{op_id} is a {entry.get('kind')} entry; only batch and restore can be undone",
+                op_id=op_id,
+            )
+        if op_id in undone:
+            raise DocControlError(
+                ErrorCode.HISTORY_NOT_FOUND, f"{op_id} was already undone", op_id=op_id
+            )
+    dry_run = request.get("dry_run", False)
+    outcome = undo_entry(
+        path,
+        entry,
+        expect_sha256=request.get("expect", {}).get("sha256"),
+        dry_run=dry_run,
+        env=None,
+    )
+    warnings: list[str] = []
+    result: dict[str, Any] = {
+        "undid": entry["op_id"],
+        "dry_run": dry_run,
+        "paragraphs": len(outcome.reverted),
+    }
+    if not dry_run:
+        assert outcome.after_sha256 is not None
+        try:
+            result["op_id"] = history.record(
+                path,
+                "undo",
+                before_sha256=outcome.before_sha256,
+                after_sha256=outcome.after_sha256,
+                backup=outcome.backup,
+                changes=outcome.reverted,
+                request={"op": "undo", "op_id": entry["op_id"]},
+                extra={"undoes": entry["op_id"]},
+            )
+        except (DocControlError, OSError) as exc:
+            result["op_id"] = None
+            warnings.append(
+                f"HISTORY_NOT_RECORDED: the undo succeeded but could not be logged: {exc}"
+            )
+        result["sha256"] = outcome.after_sha256
+        result["backup"] = str(outcome.backup)
+    return Reply(result, doc=Document(str(path)).envelope_doc(), warnings=warnings)
+
+
+# -- restore --------------------------------------------------------------------------------
+
+
+def _restorable(change: dict[str, Any]) -> bool:
+    return change.get("kind") == "replace" and bool(change.get("text_before"))
+
+
+@operation(
+    "restore",
+    "write",
+    "Bring a logged paragraph back as a tracked insertion after the paragraph that holds its "
+    "place now. Without `change`, every paragraph the op deleted.",
+    {
+        "type": "object",
+        "properties": {
+            "doc": _DOC,
+            "store": _STORE,
+            "op_id": {**_OP_ID, "description": "The logged op the paragraph was changed by."},
+            "change": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Index of one change of the op (history.list shows them).",
+            },
+            "after": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Insert after this paragraph address instead of the old place "
+                "(needed when that place was edited, or the history comes from `store`).",
+            },
+            "expect": _EXPECT,
+            "dry_run": {"type": "boolean", "description": "Preview only; write nothing."},
+            "author": {"type": "string", "minLength": 1, "description": "Revision author."},
+            "tag": {"type": "string", "minLength": 1, "description": "Appended to the author."},
+        },
+        "required": ["doc", "op_id"],
+        "additionalProperties": False,
+    },
+)
+def restore(request: dict[str, Any]) -> Reply:
+    path = Path(request["doc"])
+    entry = _log(request).get(request["op_id"])
+    changes = entry.get("changes", [])
+    if "change" in request:
+        number = request["change"]
+        if not 0 <= number < len(changes) or not _restorable(changes[number]):
+            raise DocControlError(
+                ErrorCode.HISTORY_NOT_FOUND,
+                f"{entry['op_id']} has no restorable paragraph at change {number}",
+                op_id=entry["op_id"],
+            )
+        chosen = [number]
+    else:
+        chosen = [n for n, c in enumerate(changes) if _restorable(c) and c.get("deleted")]
+    if not chosen:
+        raise DocControlError(
+            ErrorCode.HISTORY_NOT_FOUND,
+            f"{entry['op_id']} deleted no paragraph; pass `change` to restore an edited one",
+            op_id=entry["op_id"],
+        )
+    if "after" in request and len(chosen) != 1:
+        raise DocControlError(ErrorCode.SCHEMA_INVALID, "`after` needs exactly one `change`")
+    pkg = Package(path) if path.is_file() else None
+    if pkg is None:
+        raise DocControlError(ErrorCode.DOC_NOT_FOUND, f"no such file: {path}", path=str(path))
+    anchors = _anchors(pkg, changes, chosen, request)
+    edits = [InsertParagraph(changes[n]["text_before"], after=anchors[n]) for n in chosen]
+    dry_run = request.get("dry_run", False)
+    done = apply_edits(
+        path,
+        edits,
+        expect_sha256=request.get("expect", {}).get("sha256"),
+        author=request.get("author", DEFAULT_AUTHOR),
+        tag=request.get("tag"),
+        dry_run=dry_run,
+        kind="restore",
+        request={"op": "restore", "op_id": entry["op_id"], "changes": chosen},
+        log_extra={"restores": entry["op_id"]},
+    )
+    result = done.to_dict()
+    result["restored"] = [
+        {"change": n, "after": anchors[n], "text": _short(changes[n]["text_before"])}
+        for n in chosen
+    ]
+    result["from"] = entry["op_id"]
+    return _doc_reply(str(path), result)
+
+
+def _anchors(
+    pkg: Package, changes: list[dict[str, Any]], chosen: list[int], request: dict[str, Any]
+) -> dict[int, str]:
+    """For each chosen change, the address of the paragraph to insert after."""
+    if "after" in request:
+        return {chosen[0]: request["after"]}
+    data = pkg.read(DOCUMENT_PART)
+    spans = scan(data).paragraphs
+    index = DocumentIndex.from_package(pkg)
+    by_span = {p.span_index: p for p in index.paragraphs}
+    out: dict[int, str] = {}
+    for n in chosen:
+        target = to_bytes(changes[n]["after"])
+        found = [i for i, s in enumerate(spans) if data[s.start : s.end] == target]
+        para = by_span.get(found[0]) if len(found) == 1 else None
+        if para is None:
+            raise DocControlError(
+                ErrorCode.BATCH_CONFLICT,
+                f"the place of change {n} was edited since; pass `after` with an address",
+                change=n,
+            )
+        out[n] = str(para.address)
+    return out
+
+
+# -- history.* ------------------------------------------------------------------------------
+
+_READ_PROPS: dict[str, Any] = {"doc": _DOC, "store": _STORE}
+
+
+def _summary(entry: dict[str, Any], undone: set[str]) -> dict[str, Any]:
+    out: dict[str, Any] = {
+        "op_id": entry["op_id"],
+        "kind": entry.get("kind"),
+        "time": entry.get("time"),
+    }
+    if entry.get("kind") == "purge":
+        return {**out, "removed": entry.get("removed"), "scope": entry.get("scope")}
+    out.update(author=entry.get("author"), tag=entry.get("tag"))
+    changes = entry.get("changes", [])
+    out["paragraphs"] = len(changes)
+    request = entry.get("request")
+    if isinstance(request, list):
+        out["ops"] = [r.get("op") for r in request if isinstance(r, dict)]
+    if entry.get("kind") in UNDOABLE_KINDS:
+        out["undone"] = entry["op_id"] in undone
+        out["deleted"] = [
+            {"change": n, "text": _short(c["text_before"])}
+            for n, c in enumerate(changes)
+            if _restorable(c) and c.get("deleted")
+        ][:5]
+    for key in ("undoes", "restores", "sha256_after", "backup"):
+        if entry.get(key) is not None:
+            out[key] = entry[key]
+    return out
+
+
+@operation(
+    "history.list",
+    "read",
+    "The undo log, newest first: what each write changed, whether it was undone, and the "
+    "deleted paragraphs `restore` can bring back.",
+    {
+        "type": "object",
+        "properties": {
+            **_READ_PROPS,
+            "limit": {"type": "integer", "minimum": 1, "maximum": MAX_LIMIT},
+            "cursor": {**_OP_ID, "description": "The `next` of the previous response."},
+            "kind": {"enum": ["batch", "restore", "undo", "open", "purge"]},
+        },
+        "additionalProperties": False,
+    },
+)
+def history_list(request: dict[str, Any]) -> Reply:
+    log = _log(request)
+    undone = log.undone()
+    kind = request.get("kind")
+    rows = [e for e in reversed(log.entries) if kind is None or e.get("kind") == kind]
+    cursor = request.get("cursor")
+    if cursor is not None and history.op_number(cursor) is None:
+        raise DocControlError(ErrorCode.SCHEMA_INVALID, f"bad cursor: {cursor!r}", path="$.cursor")
+    if cursor is not None:
+        rows = [
+            e
+            for e in rows
+            if (history.op_number(e["op_id"]) or 0) < (history.op_number(cursor) or 0)
+        ]
+    limit = request.get("limit", DEFAULT_LIMIT)
+    page = rows[:limit]
+    result: dict[str, Any] = {
+        "entries": [_summary(e, undone) for e in page],
+        "total": len(rows),
+    }
+    if log.skipped:
+        result["unreadable_lines"] = log.skipped
+    more = len(rows) > limit
+    return Reply(result, next_cursor=page[-1]["op_id"] if more and page else None)
+
+
+@operation(
+    "history.search",
+    "read",
+    "Find a quote in the undo log: in the requests, and in the text of every paragraph "
+    "before and after each write.",
+    {
+        "type": "object",
+        "properties": {
+            **_READ_PROPS,
+            "query": {"type": "string", "minLength": 1, "description": "Text to find."},
+            "ignore_case": {"type": "boolean"},
+            "ignore_accents": {"type": "boolean"},
+            "limit": {"type": "integer", "minimum": 1, "maximum": MAX_LIMIT},
+        },
+        "required": ["query"],
+        "additionalProperties": False,
+    },
+)
+def history_search(request: dict[str, Any]) -> Reply:
+    log = _log(request)
+    limit = request.get("limit", DEFAULT_LIMIT)
+    hits: list[dict[str, Any]] = []
+    total = 0
+    for entry in reversed(log.entries):
+        if entry.get("kind") == "purge":
+            continue
+        found = history.search_entry(
+            entry,
+            request["query"],
+            ignore_case=request.get("ignore_case", False),
+            ignore_accents=request.get("ignore_accents", False),
+        )
+        total += len(found)
+        hits.extend(found[: max(0, limit - len(hits))])
+    return Reply({"matches": hits, "total": total})
+
+
+@operation(
+    "history.purge",
+    "write",
+    "Remove undo history (all, or before a date) for privacy, leaving a tombstone. Run with "
+    "dry_run first, then repeat with its `confirm`.",
+    {
+        "type": "object",
+        "properties": {
+            **_READ_PROPS,
+            "all": {"type": "boolean", "description": "Remove the whole log."},
+            "before": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Remove entries older than this ISO date or time (UTC).",
+            },
+            "dry_run": {"type": "boolean", "description": "List what would go; returns confirm."},
+            "confirm": {"type": "string", "minLength": 1, "description": "From the dry run."},
+        },
+        "additionalProperties": False,
+    },
+)
+def history_purge(request: dict[str, Any]) -> Reply:
+    if "store" in request:
+        log_path = Path(request["store"]) / "log.jsonl"
+    elif "doc" in request:
+        log_path = log_path_for(Path(request["doc"]))
+    else:
+        raise DocControlError(ErrorCode.SCHEMA_INVALID, "give `doc` or `store`")
+    before = _parse_when(request["before"]) if "before" in request else None
+    result = history.purge(
+        log_path,
+        before=before,
+        everything=request.get("all", False),
+        dry_run=request.get("dry_run", False),
+        confirm=request.get("confirm"),
+    )
+    return Reply(result)
+
+
+def _parse_when(text: str) -> datetime:
+    try:
+        when = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise DocControlError(
+            ErrorCode.SCHEMA_INVALID, f"`before` is not an ISO date: {text!r}", path="$.before"
+        ) from exc
+    return when if when.tzinfo else when.replace(tzinfo=UTC)
+
+
+@operation(
+    "history.orphans",
+    "read",
+    "List stores whose document is gone (app-data stores, and `dir`/.doc-control). Their "
+    "history is never deleted automatically: restore from it with `store`, or purge it.",
+    {
+        "type": "object",
+        "properties": {
+            "dir": {"type": "string", "minLength": 1, "description": "Also scan this folder."}
+        },
+        "additionalProperties": False,
+    },
+)
+def history_orphans(request: dict[str, Any]) -> Reply:
+    folder = Path(request["dir"]) if "dir" in request else None
+    found = history.find_orphans(folder, os.environ)
+    return Reply({**found, "total": len(found["orphans"])})

doc_control/ops/layout.py

@@ -0,0 +1,40 @@
+"""Layout facts for `para.get` and `outline` (D-18), registered through the
+:data:`doc_control.ops.read.PARA_FACTS` and :data:`doc_control.ops.read.OUTLINE_FACTS` hooks.
+
+The definitions live in :mod:`doc_control.model.layout`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from doc_control.model.layout import blank_before, centred, is_empty, page_break_before
+from doc_control.ops.read import OUTLINE_FACTS, PARA_FACTS, ParagraphContext
+
+
+def para_facts(ctx: ParagraphContext) -> dict[str, Any]:
+    doc, para = ctx.doc, ctx.paragraph
+    return {
+        "empty": is_empty(doc, para),
+        "blank_before": blank_before(doc, para),
+        "heading_level": doc.heading_level(para),
+        "centred": centred(doc, para),
+        "page_break_before": page_break_before(doc, para),
+    }
+
+
+def outline_facts(ctx: ParagraphContext) -> dict[str, Any]:
+    """Outline entries already carry ``level`` and ``style``; add the rest."""
+    doc, para = ctx.doc, ctx.paragraph
+    style = doc.style_id(para)
+    style_def = doc.styles.get(style) if style is not None else None
+    return {
+        "style_name": style_def.name if style_def is not None else None,
+        "blank_before": blank_before(doc, para),
+        "centred": centred(doc, para),
+        "page_break_before": page_break_before(doc, para),
+    }
+
+
+PARA_FACTS.append(para_facts)
+OUTLINE_FACTS.append(outline_facts)