doc-control 0.3.0__tar.gz → 0.4.0__tar.gz

{doc_control-0.3.0 → doc_control-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: doc-control
-Version: 0.3.0
+Version: 0.4.0
 Summary: Deterministic, LLM-first control of Word documents: addresses, anchors, tracked-change batches and a safety layer.
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -63,7 +63,9 @@ References: [operations](docs/operations.md) · [errors](docs/errors.md).
 
 - **One core, two engines, one API**
   - *File engine*: edits a closed `.docx` with the Python standard library only,
-    rewriting only the parts it touches.
+    rewriting only the parts it touches. Read operations also take a `.txt` or `.md`
+    file (hard-wrapped text detected; Markdown `#` headings become Heading 1-6); writes
+    refuse it.
   - *Live engine*: controls the open Word (Windows/COM first, Mac later).
 - **Two front doors**: a CLI with JSON in/out, and an MCP server
   (`doc-control mcp`, stdio) for Claude Desktop / Cowork and other MCP clients.

{doc_control-0.3.0 → doc_control-0.4.0}/README.md

@@ -54,7 +54,9 @@ References: [operations](docs/operations.md) · [errors](docs/errors.md).
 
 - **One core, two engines, one API**
   - *File engine*: edits a closed `.docx` with the Python standard library only,
-    rewriting only the parts it touches.
+    rewriting only the parts it touches. Read operations also take a `.txt` or `.md`
+    file (hard-wrapped text detected; Markdown `#` headings become Heading 1-6); writes
+    refuse it.
   - *Live engine*: controls the open Word (Windows/COM first, Mac later).
 - **Two front doors**: a CLI with JSON in/out, and an MCP server
   (`doc-control mcp`, stdio) for Claude Desktop / Cowork and other MCP clients.

{doc_control-0.3.0 → doc_control-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "doc-control"
-version = "0.3.0"
+version = "0.4.0"
 description = "Deterministic, LLM-first control of Word documents: addresses, anchors, tracked-change batches and a safety layer."
 readme = "README.md"
 license = "Apache-2.0"

{doc_control-0.3.0 → doc_control-0.4.0}/src/doc_control/__init__.py

@@ -1,4 +1,4 @@
 """doc-control: deterministic, LLM-first control of Word documents."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 API_VERSION = "1.0"

{doc_control-0.3.0 → doc_control-0.4.0}/src/doc_control/errors.py

@@ -29,7 +29,10 @@ class ErrorCode(StrEnum):
 
 HINTS: dict[ErrorCode, str] = {
     ErrorCode.DOC_NOT_FOUND: "Check the path; it is resolved relative to the current directory.",
-    ErrorCode.NOT_A_DOCX: "Pass a Word .docx file; .doc and other formats are not supported.",
+    ErrorCode.NOT_A_DOCX: (
+        "Pass a Word .docx file (or UTF-8 .txt/.md, read operations only); .doc and other"
+        " formats are not supported."
+    ),
     ErrorCode.DOC_LOCKED: "An editor (Word, LibreOffice) has the file open: close it, then retry.",
     ErrorCode.DOC_CHANGED_ON_DISK: "The file changed since you read it: re-read, then retry.",
     ErrorCode.SCHEMA_INVALID: "Run `doc-control help <op>` to see the request schema.",

{doc_control-0.3.0 → doc_control-0.4.0}/src/doc_control/model/document.py

@@ -87,7 +87,14 @@ class Document:
 
     def envelope_doc(self) -> dict[str, Any]:
         """The ``doc`` block of a response."""
-        return {"path": self.path, "sha256": self.sha256, "paragraphs": len(self.index)}
+        doc: dict[str, Any] = {
+            "path": self.path,
+            "sha256": self.sha256,
+            "paragraphs": len(self.index),
+        }
+        if self.pkg.text_source is not None:
+            doc["source"] = self.pkg.text_source
+        return doc
 
     def memo(self, key: Hashable, build: Callable[[], _T]) -> _T:
         """``build()`` once per document and ``key``: derived tables shared by every

doc_control-0.4.0/src/doc_control/ooxml/plaintext.py

@@ -0,0 +1,301 @@
+"""Plain text and Markdown read as a .docx: the parts a :class:`Package` needs, built in memory.
+
+Read operations accept a ``.txt`` or ``.md`` path and see the text as a minimal Word
+document; nothing is written next to it, and write operations refuse it.
+
+Encoding
+    UTF-32 or UTF-16 with a byte order mark; else UTF-8 (with or without one), any line
+    that is not UTF-8 read as Windows-1252; UTF-16 without a mark is refused. Line ends
+    are ``\\n``, ``\\r\\n`` or ``\\r``. The ``doc`` block of a reply names the
+    ``source``: format, encoding (``utf-8+cp1252`` when lines mix them) and mode.
+
+Paragraphs (``.txt``), by mode
+    ``blocks`` (an empty line between two non-empty ones): a block of lines between empty lines is
+    a paragraph, its lines joined by one space (hard-wrapped prose, as in Project
+    Gutenberg files). One empty line separates two paragraphs; each further empty line
+    in a run is an empty paragraph, so ``chapter_blank_lines`` in ``segment`` counts the
+    extra ones. ``lines`` (otherwise): every line is a paragraph.
+
+Markdown (``.md``)
+    Blocks as in ``blocks`` (soft-wrapped lines joined); a front matter block at the
+    start (``---``, a ``key:`` line, ..., ``---``) is skipped. A line ``# Title`` to
+    ``###### Title`` is its own paragraph in style Heading 1-6. A line made only of
+    ``* _ - ~ #`` and spaces, three or more of them (``***``, ``* * *``, ``---``), is its
+    own paragraph and keeps its characters, which scene detection reads as a break. A
+    bullet item starts a paragraph, and so does a numbered one that is ``1.`` or follows
+    another item. Emphasis markers (``*``, ``**``, and ``_``, ``__`` outside words) are
+    dropped; a backslash-escaped character is kept, literal. Lines inside a backtick
+    fence are kept as written, one paragraph each. Anything else (setext headings, hard
+    breaks, inline code, tables, quotes) is kept as written.
+"""
+
+from __future__ import annotations
+
+import io
+import re
+import zipfile
+from pathlib import Path
+from xml.sax.saxutils import escape
+
+from doc_control.errors import DocControlError, ErrorCode
+
+TEXT_SUFFIXES = (".txt", ".md", ".markdown")
+
+_W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+_ATX = re.compile(r"^ {0,3}(#{1,6})(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*$")
+_BREAK = re.compile(r"^ {0,3}[-*_~#](?:[ \t]*[-*_~#]){2,}[ \t]*$")
+_FENCE = re.compile(r"^ {0,3}(`{3,})")
+_BULLET = re.compile(r"^ {0,3}[-*+][ \t]")
+_ORDERED = re.compile(r"^ {0,3}(\d{1,9})[.)][ \t]")
+_YAML_KEY = re.compile(r"^[A-Za-z_][\w-]*[ \t]*:")
+# A span holds no marker of its own kind, so an unmatched marker scans only to the next
+# one (linear time); nesting (``***x***``, ``**a *b* c**``) unwinds over passes.
+_STRONG = re.compile(
+    r"\*\*(?=[^\s*])([^*]+?)(?<=\S)\*\*|(?<!\w)__(?=[^\s_])([^_]+?)(?<=\S)__(?!\w)"
+)
+_EMPH = re.compile(
+    r"(?<![\w*])\*(?=[^\s*])([^*]+?)(?<=\S)\*(?![\w*])|(?<!\w)_(?=[^\s_])([^_]+?)(?<=\S)_(?!\w)"
+)
+_ESCAPE = re.compile(r"(\\[!-/:-@\[-`{-~])")
+_CONTROL = re.compile("[\x00-\x08\x0b\x0c\x0e-\x1f￾￿]")
+_BLANK = " \t"
+
+_CONTENT_TYPES = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
+    '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.'
+    'relationships+xml"/>'
+    '<Default Extension="xml" ContentType="application/xml"/>'
+    '<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-'
+    'officedocument.wordprocessingml.document.main+xml"/>'
+    '<Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-'
+    'officedocument.wordprocessingml.styles+xml"/>'
+    "</Types>"
+)
+_RELS = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/'
+    'relationships/officeDocument" Target="word/document.xml"/>'
+    "</Relationships>"
+)
+_DOC_RELS = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/'
+    'relationships/styles" Target="styles.xml"/>'
+    "</Relationships>"
+)
+
+
+def _styles() -> str:
+    headings = "".join(
+        f'<w:style w:type="paragraph" w:styleId="Heading{n}"><w:name w:val="heading {n}"/>'
+        f'<w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/>'
+        f'<w:pPr><w:outlineLvl w:val="{n - 1}"/></w:pPr></w:style>'
+        for n in range(1, 7)
+    )
+    return (
+        f'<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:styles xmlns:w="{_W}">'
+        '<w:style w:type="paragraph" w:default="1" w:styleId="Normal">'
+        '<w:name w:val="Normal"/><w:qFormat/></w:style>'
+        f"{headings}</w:styles>"
+    )
+
+
+def refuse_write(path: Path) -> None:
+    """``UNSUPPORTED_CONTENT`` when ``path`` is a text file: it is read, never written."""
+    if path.suffix.lower() in TEXT_SUFFIXES:
+        raise DocControlError(
+            ErrorCode.UNSUPPORTED_CONTENT,
+            f"{path} is plain text: only read operations accept it; write to a .docx",
+            path=str(path),
+        )
+
+
+def _line_bytes(raw: bytes) -> tuple[str, str]:
+    """UTF-8, with any line that is not UTF-8 read as Windows-1252 (Latin-1 for its five
+    unassigned bytes), so one stray byte does not garble every accent of the file."""
+    try:
+        return raw.decode("utf-8"), "utf-8"
+    except UnicodeDecodeError:
+        pass
+    out: list[str] = []
+    utf8 = False  # a line with non-ASCII characters read as UTF-8
+    for line in raw.splitlines(keepends=True):
+        try:
+            out.append(line.decode("utf-8"))
+            utf8 = utf8 or not line.isascii()
+        except UnicodeDecodeError:
+            try:
+                out.append(line.decode("cp1252"))
+            except UnicodeDecodeError:
+                out.append(line.decode("latin-1"))
+    return "".join(out), "utf-8+cp1252" if utf8 else "cp1252"
+
+
+def decode(raw: bytes) -> tuple[str, str]:
+    """``(text, encoding)``, line ends made ``\\n``; ``ValueError`` names an unreadable file.
+
+    UTF-32 or UTF-16 with a byte order mark; else UTF-8 (with or without one), any line
+    that is not UTF-8 read as Windows-1252.
+    """
+    if raw.startswith((b"\xff\xfe\x00\x00", b"\x00\x00\xfe\xff")):
+        text, encoding = raw.decode("utf-32"), "utf-32"
+    elif raw.startswith((b"\xff\xfe", b"\xfe\xff")):
+        text, encoding = raw.decode("utf-16"), "utf-16"
+    elif b"\x00" in raw[:4096]:
+        raise ValueError("UTF-16 without a byte order mark (or binary): save it as UTF-8")
+    else:
+        bom = raw.startswith(b"\xef\xbb\xbf")
+        text, encoding = _line_bytes(raw[3:] if bom else raw)
+        if bom and encoding == "utf-8":
+            encoding = "utf-8-sig"
+    return text.replace("\r\n", "\n").replace("\r", "\n"), encoding
+
+
+def _emphasis(text: str) -> str:
+    for _ in range(3):  # nested emphasis, e.g. ***x***
+        stripped = _EMPH.sub(lambda m: m.group(1) or m.group(2), text)
+        stripped = _STRONG.sub(lambda m: m.group(1) or m.group(2), stripped)
+        if stripped == text:
+            break
+        text = stripped
+    return text
+
+
+def _inline(text: str) -> str:
+    """Emphasis markers dropped; a backslash-escaped character kept, bare and literal.
+
+    Escaped characters are hidden from the emphasis patterns as private-use characters
+    from a plane the text does not use, then put back.
+    """
+    planes = {ord(c) >> 16 for c in text if ord(c) >= 0xF0000}
+    plane = next((p for p in (0xF, 0x10) if p not in planes), None)
+    if plane is None:  # both private planes in use: escapes split the text instead
+        parts = _ESCAPE.split(text)
+        return "".join(part[1] if i % 2 else _emphasis(part) for i, part in enumerate(parts))
+    base = plane << 16
+    hidden = _ESCAPE.sub(lambda m: chr(base + ord(m.group(1)[1])), text)
+    shown = _emphasis(hidden)
+    return re.sub(
+        f"[{chr(base + 0x21)}-{chr(base + 0x7E)}]", lambda m: chr(ord(m.group()) - base), shown
+    )
+
+
+def _blank(line: str) -> bool:
+    return not line.strip(_BLANK)
+
+
+def _starts_item(line: str, pending: list[str]) -> bool:
+    """A list item starts a paragraph: a bullet always, a numbered item when it is ``1.``
+    or follows another item (``1914. was`` inside a sentence does not)."""
+    if _BULLET.match(line):
+        return True
+    number = _ORDERED.match(line)
+    if number is None:
+        return False
+    in_list = bool(pending) and bool(_BULLET.match(pending[0]) or _ORDERED.match(pending[0]))
+    return not pending or number.group(1) == "1" or in_list
+
+
+def _front_matter(lines: list[str]) -> int:
+    """How many lines a YAML front matter block at the start takes (0: none)."""
+    if len(lines) < 3 or lines[0].rstrip(_BLANK) != "---" or not _YAML_KEY.match(lines[1]):
+        return 0
+    for n, line in enumerate(lines[1:], start=1):
+        if line.rstrip(_BLANK) in ("---", "..."):
+            return n + 1
+    return 0
+
+
+def paragraphs(text: str, markdown: bool) -> tuple[list[tuple[str, int | None]], str]:
+    """``(text, heading level or None)`` per paragraph, and the mode: ``markdown``,
+    ``blocks`` or ``lines``; see the module docstring."""
+    lines = text.split("\n")
+    if lines and lines[-1] == "":
+        lines.pop()  # the final line end closes the last line, it does not open one
+    if markdown:
+        lines = lines[_front_matter(lines) :]
+        mode = "markdown"
+    else:
+        inner = [n for n, line in enumerate(lines) if not _blank(line)]
+        between = lines[inner[0] : inner[-1] + 1] if inner else []
+        mode = "blocks" if any(_blank(line) for line in between) else "lines"
+    out: list[tuple[str, int | None]] = []
+    if mode == "lines":
+        return [(line, None) for line in lines], mode
+    pending: list[str] = []
+    blanks = 0
+    fence = ""  # the opening fence while inside a code block
+
+    def flush() -> None:
+        if pending:
+            joined = " ".join(part.strip(_BLANK) for part in pending)
+            out.append((_inline(joined) if markdown else joined, None))
+            pending.clear()
+
+    for line in lines:
+        opening = _FENCE.match(line) if markdown else None
+        if fence or opening:
+            flush()
+            out.append((line, None))  # code: one literal paragraph per line
+            if not fence and opening:
+                fence = opening.group(1)
+            elif fence and line.strip(_BLANK).startswith(fence) and not line.strip(_BLANK + "`"):
+                fence = ""
+            blanks = 0
+            continue
+        if _blank(line):
+            flush()
+            # The first empty line of a run separates; each further one is a paragraph.
+            if blanks or not out:
+                out.append(("", None))
+            blanks += 1
+            continue
+        blanks = 0
+        if markdown and _BREAK.match(line):
+            flush()
+            out.append((line.strip(_BLANK), None))
+            continue
+        heading = _ATX.match(line) if markdown else None
+        if heading:
+            flush()
+            out.append((_inline(heading.group(2) or ""), len(heading.group(1))))
+            continue
+        if markdown and _starts_item(line, pending):
+            flush()
+        pending.append(line)
+    flush()
+    return out, mode
+
+
+def _paragraph_xml(text: str, level: int | None) -> str:
+    ppr = f'<w:pPr><w:pStyle w:val="Heading{level}"/></w:pPr>' if level else ""
+    if not text:
+        return f"<w:p>{ppr}</w:p>"
+    runs = []
+    for i, part in enumerate(_CONTROL.sub("", text).split("\t")):
+        if i:
+            runs.append("<w:tab/>")
+        if part:
+            runs.append(f'<w:t xml:space="preserve">{escape(part)}</w:t>')
+    return f"<w:p>{ppr}<w:r>{''.join(runs)}</w:r></w:p>"
+
+
+def package_bytes(text: str, markdown: bool) -> tuple[bytes, str]:
+    """A .docx (zip bytes) whose paragraphs are those of ``text``, and the mode used."""
+    paras, mode = paragraphs(text, markdown)
+    body = "".join(_paragraph_xml(t, level) for t, level in paras)
+    document = (
+        f'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        f'<w:document xmlns:w="{_W}"><w:body>{body}<w:sectPr/></w:body></w:document>'
+    ).encode()
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("[Content_Types].xml", _CONTENT_TYPES)
+        zf.writestr("_rels/.rels", _RELS)
+        zf.writestr("word/document.xml", document)
+        zf.writestr("word/_rels/document.xml.rels", _DOC_RELS)
+        zf.writestr("word/styles.xml", _styles())
+    return buf.getvalue(), mode

{doc_control-0.3.0 → doc_control-0.4.0}/src/doc_control/ooxml/zipio.py

@@ -29,6 +29,7 @@ from collections.abc import Callable, Mapping
 from pathlib import Path
 
 from doc_control.errors import DocControlError, ErrorCode
+from doc_control.ooxml.plaintext import TEXT_SUFFIXES, decode, package_bytes, refuse_write
 
 REQUIRED_PARTS = ("[Content_Types].xml", "word/document.xml")
 
@@ -91,7 +92,12 @@ class Package:
             raise DocControlError(ErrorCode.DOC_NOT_FOUND, f"no such file: {path}", path=str(path))
         raw = path.read_bytes()
         self.sha256 = hashlib.sha256(raw).hexdigest()
+        #: For a .txt/.md file read as a document (readable, never written): its
+        #: ``format``, ``encoding`` and paragraph ``mode``; None for a .docx.
+        self.text_source: dict[str, str] | None = None
         try:
+            if path.suffix.lower() in TEXT_SUFFIXES:
+                raw, self.text_source = _text_package(path, raw)
             self._load(raw)
         except DocControlError:
             raise
@@ -199,6 +205,7 @@ def write_package(
     for name, data in replacements.items():
         if not isinstance(data, bytes):
             raise TypeError(f"replacement for {name} must be bytes")
+    refuse_write(dest)  # a text file is read as a document, never written
     payload = build_package(pkg, replacements)
     commit_bytes(payload, dest, stage)
     return hashlib.sha256(payload).hexdigest()
@@ -275,6 +282,18 @@ def _claim(tmp: Path, dest: Path) -> None:
     tmp.unlink()
 
 
+def _text_package(path: Path, raw: bytes) -> tuple[bytes, dict[str, str]]:
+    try:
+        text, encoding = decode(raw)
+    except ValueError as exc:  # UnicodeDecodeError too
+        raise DocControlError(
+            ErrorCode.NOT_A_DOCX, f"{path} is not readable text: {exc}", path=str(path)
+        ) from exc
+    fmt = "txt" if path.suffix.lower() == ".txt" else "md"
+    data, mode = package_bytes(text, markdown=fmt == "md")
+    return data, {"format": fmt, "encoding": encoding, "mode": mode}
+
+
 def _build(pkg: Package, replacements: Mapping[str, bytes]) -> bytes:
     out = bytearray()
     central = bytearray()

{doc_control-0.3.0 → doc_control-0.4.0}/src/doc_control/ops/compare.py

@@ -55,6 +55,7 @@ from doc_control.model.align import (
     align,
 )
 from doc_control.model.index import DocumentIndex, Paragraph, build_index
+from doc_control.ooxml.plaintext import refuse_write
 from doc_control.ooxml.revisions import (
     DEFAULT_AUTHOR,
     ParagraphEditor,
@@ -460,6 +461,7 @@ def _accepted_texts(data: bytes, ids: set[str]) -> tuple[list[str], bool]:
 
 
 def _check_output(output: Path, inputs: list[Path]) -> None:
+    refuse_write(output)
     for source in inputs:
         same = output.exists() and source.exists() and output.samefile(source)
         if same or output.resolve() == source.resolve():
@@ -506,7 +508,11 @@ def compare_documents(
     index_new = DocumentIndex.from_package(pkg_new)
     alignment = align(index_old.paragraphs, index_new.paragraphs)
     info_old = {"path": str(old), "sha256": pkg_old.sha256, "paragraphs": len(index_old)}
+    if pkg_old.text_source is not None:
+        info_old["source"] = pkg_old.text_source
     info_new = {"path": str(new), "sha256": pkg_new.sha256, "paragraphs": len(index_new)}
+    if pkg_new.text_source is not None:
+        info_new["source"] = pkg_new.text_source
     plan = _plan(index_old, index_new, alignment)
     edits = _edits(plan)
 

{doc_control-0.3.0 → doc_control-0.4.0}/src/doc_control/ops/find.py

@@ -160,7 +160,12 @@ def find(request: dict[str, Any]) -> Reply:
         )
     return Reply(
         {"matches": matches, **total},
-        doc={"path": request["doc"], "sha256": pkg.sha256, "paragraphs": len(index)},
+        doc={
+            "path": request["doc"],
+            "sha256": pkg.sha256,
+            "paragraphs": len(index),
+            **({"source": pkg.text_source} if pkg.text_source is not None else {}),
+        },
         warnings=warnings,
         next_cursor=next_cursor,
     )