changex-core 0.1.0__py3-none-any.whl

changex_core/__init__.py

@@ -0,0 +1,177 @@
+"""ChangeX core (M0 spine): canonical model, provenance journal, docx adapter.
+
+Public API (the surface other packages — ``changex-mcp``, the CLI — code against):
+
+Model
+    ``Node``, ``NodeKind``, ``NodeIdAllocator``, ``AnchorFingerprint``,
+    ``rebind`` — addressable nodes with opaque, edit-invariant ids.
+
+Ops (frozen v0.2)
+    docx: ``TextInsert``, ``TextDelete``, ``TextReplace``, ``NodeInsert``,
+    ``NodeDelete``, ``StyleChange``. xlsx/csv: ``CellSet``, ``FormulaSet``,
+    ``RowInsert``, ``RowDelete``. pptx: ``SlideInsert``, ``SlideDelete``,
+    ``ShapeEdit``. Plus ``op_from_dict`` / ``op_to_dict`` and ``validate_op``.
+    (``format.run`` / ``node.move`` remain reserved.)
+
+Journal
+    ``Journal`` (append / read / replay / verify / revert), ``Header``,
+    ``Event``, ``Provenance``, ``Target``, ``VerifyResult``, and the
+    canonicalization primitives ``canonicalize`` / ``chain_hash``.
+
+Adapters
+    ``DocumentAdapter`` (the contract), ``DocxAdapter`` (native Word
+    revisions), and ``load_adapter`` (the extension-keyed factory that lazily
+    imports the right adapter for ``.docx`` / ``.xlsx`` / ``.csv`` / ``.pptx``),
+    plus the boundary errors ``BeforeMismatchError`` / ``OversizedOpError``.
+
+Render / baseline
+    ``render_html`` / ``render_markdown`` and ``snapshot`` /
+    ``check_out_of_band``.
+"""
+
+from __future__ import annotations
+
+from changex_core.adapters import load_adapter
+from changex_core.adapters.base import (
+    AdapterError,
+    BeforeMismatchError,
+    DocumentAdapter,
+    NodeNotFoundError,
+    OversizedOpError,
+    UnsupportedFormatError,
+)
+from changex_core.adapters.docx_adapter import DocxAdapter
+from changex_core.baseline import (
+    Baseline,
+    OutOfBandWarning,
+    check_out_of_band,
+    snapshot,
+)
+from changex_core.journal.canonical import canonicalize, chain_hash, sha256_hex
+from changex_core.journal.events import Event, Header, Provenance, Target
+from changex_core.journal.journal import Journal, JournalError, VerifyResult
+from changex_core.model.addressing import (
+    AnchorFingerprint,
+    NodeIdAllocator,
+    RebindResult,
+    rebind,
+)
+from changex_core.model.nodes import Node, NodeKind
+from changex_core.ops.vocabulary import (
+    OP_SCHEMA_VERSION,
+    CellSet,
+    FormulaSet,
+    NodeDelete,
+    NodeInsert,
+    Op,
+    ReservedOpError,
+    RowDelete,
+    RowInsert,
+    ShapeEdit,
+    SlideDelete,
+    SlideInsert,
+    StyleChange,
+    TextDelete,
+    TextInsert,
+    TextReplace,
+    UnknownOpError,
+    op_from_dict,
+    op_to_dict,
+    target_node_id,
+)
+from changex_core.diff.text_diff import (
+    ParagraphSpec,
+    ReconstructedOp,
+    diff_paragraphs,
+    reconstruct_ops,
+)
+from changex_core.ops.validation import SchemaValidationError, validate_op
+from changex_core.passive import (
+    OpenResult,
+    SealResult,
+    open_passive,
+    seal_passive,
+)
+from changex_core.render.document import render_document_html
+from changex_core.render.html import render_html, render_markdown
+from changex_core.render.save import save_active, save_active_from_path
+from changex_core.render.server import build_server, serve
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # model
+    "Node",
+    "NodeKind",
+    "NodeIdAllocator",
+    "AnchorFingerprint",
+    "RebindResult",
+    "rebind",
+    # ops (docx, v0.1)
+    "Op",
+    "TextInsert",
+    "TextDelete",
+    "TextReplace",
+    "NodeInsert",
+    "NodeDelete",
+    "StyleChange",
+    # ops (xlsx/csv + pptx, v0.2)
+    "CellSet",
+    "FormulaSet",
+    "RowInsert",
+    "RowDelete",
+    "SlideInsert",
+    "SlideDelete",
+    "ShapeEdit",
+    "OP_SCHEMA_VERSION",
+    "op_from_dict",
+    "op_to_dict",
+    "target_node_id",
+    "validate_op",
+    "SchemaValidationError",
+    "ReservedOpError",
+    "UnknownOpError",
+    # journal
+    "Journal",
+    "JournalError",
+    "VerifyResult",
+    "Header",
+    "Event",
+    "Provenance",
+    "Target",
+    "canonicalize",
+    "chain_hash",
+    "sha256_hex",
+    # adapters
+    "DocumentAdapter",
+    "DocxAdapter",
+    "load_adapter",
+    "AdapterError",
+    "BeforeMismatchError",
+    "OversizedOpError",
+    "NodeNotFoundError",
+    "UnsupportedFormatError",
+    # render / baseline
+    "render_html",
+    "render_markdown",
+    "render_document_html",
+    "Baseline",
+    "OutOfBandWarning",
+    "snapshot",
+    "check_out_of_band",
+    # render: journal-aware save + interactive review server
+    "save_active",
+    "save_active_from_path",
+    "build_server",
+    "serve",
+    # passive ("native to any model") capture + diff reconstruction
+    "open_passive",
+    "seal_passive",
+    "OpenResult",
+    "SealResult",
+    "ParagraphSpec",
+    "ReconstructedOp",
+    "diff_paragraphs",
+    "reconstruct_ops",
+]

changex_core/adapters/__init__.py

@@ -0,0 +1,156 @@
+"""Document adapters: the contract, the docx implementation, and the registry.
+
+The :class:`~changex_core.adapters.base.DocumentAdapter` ABC is the anti-drift
+contract every format adapter implements. This package also owns the **format
+registry + factory** (:func:`load_adapter`) that resolves a file path to the
+adapter that handles its extension.
+
+Lazy import is load-bearing
+---------------------------
+The registry maps an extension to a ``"module:ClassName"`` target string and
+imports the module **only when that format is actually loaded**. Concretely the
+xlsx/csv/pptx adapter modules are created by phase-2 agents and may not exist (or
+may pull heavy third-party deps like ``openpyxl`` / ``python-pptx``) when this
+package is imported. Importing them eagerly here would (a) crash ``import
+changex_core`` before phase-2 lands and (b) force every consumer to install every
+format's dependencies. So this module **must not** import the adapter
+implementations at top level — only ``base`` and the already-shipping
+``docx_adapter`` are imported eagerly.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from changex_core.adapters.base import (
+    AdapterError,
+    BeforeMismatchError,
+    DocumentAdapter,
+    NodeNotFoundError,
+    OversizedOpError,
+    UnsupportedFormatError,
+)
+from changex_core.adapters.docx_adapter import DocxAdapter
+from changex_core.paths import safe_path
+
+# --------------------------------------------------------------------------- #
+# Format registry.
+#
+# Maps a lowercased file extension to a ``"<module>:<ClassName>"`` target. The
+# class is resolved by a LAZY import (see ``_resolve``) so the adapter module is
+# only imported when a file of that format is loaded — phase-2 modules
+# (xlsx_adapter, csv_adapter, pptx_adapter) therefore need not exist at import
+# time, and their third-party deps stay opt-in.
+# --------------------------------------------------------------------------- #
+_REGISTRY: dict[str, str] = {
+    ".docx": "changex_core.adapters.docx_adapter:DocxAdapter",
+    ".xlsx": "changex_core.adapters.xlsx_adapter:XlsxAdapter",
+    ".csv": "changex_core.adapters.csv_adapter:CsvAdapter",
+    ".pptx": "changex_core.adapters.pptx_adapter:PptxAdapter",
+}
+
+# The suffixes ``load_adapter`` will accept (used as the ``allow_suffixes`` guard
+# at the path boundary so an unknown extension is rejected before any import).
+SUPPORTED_SUFFIXES: tuple[str, ...] = tuple(_REGISTRY)
+
+
+def supported_suffixes() -> tuple[str, ...]:
+    """Return the file extensions the registry knows how to load."""
+    return SUPPORTED_SUFFIXES
+
+
+def _resolve(target: str) -> type[DocumentAdapter]:
+    """Lazily import ``"module:ClassName"`` and return the adapter class.
+
+    Raises:
+        UnsupportedFormatError: if the module/class cannot be imported (e.g. a
+            phase-2 adapter that has not been created yet, or its third-party
+            dependency is missing). The original cause is chained for debugging.
+    """
+    import importlib
+
+    module_name, _, class_name = target.partition(":")
+    try:
+        module = importlib.import_module(module_name)
+        cls = getattr(module, class_name)
+    except (ImportError, AttributeError) as exc:  # adapter not yet implemented
+        raise UnsupportedFormatError(
+            f"adapter {target!r} is not available: {exc}"
+        ) from exc
+    if not (isinstance(cls, type) and issubclass(cls, DocumentAdapter)):
+        raise UnsupportedFormatError(
+            f"{target!r} does not resolve to a DocumentAdapter subclass"
+        )
+    return cls
+
+
+def adapter_class_for(path: str) -> type[DocumentAdapter]:
+    """Return the adapter **class** registered for ``path``'s extension.
+
+    The path is sanitized (suffix-guarded against :data:`SUPPORTED_SUFFIXES`) and
+    the matching adapter class is lazily imported. The file need not exist — this
+    is a pure type lookup, used by callers that want to construct the adapter
+    themselves. Use :func:`load_adapter` to also load the document.
+
+    Raises:
+        UnsupportedFormatError: if the extension is not registered or the adapter
+            module/class cannot be imported.
+        UnsafePathError: if the path fails sanitization.
+    """
+    resolved = safe_path(path, allow_suffixes=SUPPORTED_SUFFIXES)
+    suffix = resolved.suffix.lower()
+    target = _REGISTRY.get(suffix)
+    if target is None:  # pragma: no cover - safe_path already guards the suffix
+        raise UnsupportedFormatError(
+            f"no adapter registered for {suffix!r}; supported: {SUPPORTED_SUFFIXES}"
+        )
+    return _resolve(target)
+
+
+def load_adapter(path: str, **kwargs: object) -> DocumentAdapter:
+    """Load ``path`` with the adapter registered for its file extension.
+
+    This is the format-aware entry point the CLI and MCP server use instead of
+    hard-coding :class:`DocxAdapter`. It dispatches by **extension** (``.docx`` ->
+    :class:`DocxAdapter`, ``.xlsx`` -> ``XlsxAdapter``, ``.csv`` -> ``CsvAdapter``,
+    ``.pptx`` -> ``PptxAdapter``), lazily importing the adapter module so unused
+    formats never pull their third-party deps.
+
+    ``path`` is sanitized (must exist, suffix-guarded). Extra ``kwargs`` (e.g.
+    ``author=`` / ``date=`` for docx) are forwarded to the adapter's ``load``
+    classmethod; adapters should accept the kwargs they understand.
+
+    Args:
+        path: The document to load. Extension selects the adapter.
+        **kwargs: Forwarded to ``<Adapter>.load`` (adapter-specific).
+
+    Returns:
+        A loaded :class:`DocumentAdapter` for the file.
+
+    Raises:
+        UnsupportedFormatError: if the extension is not registered or the adapter
+            is not yet available.
+        UnsafePathError: if the path fails sanitization or does not exist.
+    """
+    resolved = safe_path(path, must_exist=True, allow_suffixes=SUPPORTED_SUFFIXES)
+    cls = adapter_class_for(str(resolved))
+    loader: Callable[..., DocumentAdapter] = cls.load  # type: ignore[assignment]
+    return loader(str(resolved), **kwargs)
+
+
+__all__ = [
+    # contract + errors
+    "DocumentAdapter",
+    "AdapterError",
+    "BeforeMismatchError",
+    "OversizedOpError",
+    "NodeNotFoundError",
+    "UnsupportedFormatError",
+    # docx implementation (shipping)
+    "DocxAdapter",
+    # registry / factory
+    "load_adapter",
+    "adapter_class_for",
+    "supported_suffixes",
+    "SUPPORTED_SUFFIXES",
+]

changex_core/adapters/base.py

@@ -0,0 +1,109 @@
+"""The ``DocumentAdapter`` contract every format adapter implements.
+
+This abstract interface is the anti-drift contract between the journal/render
+layer and each format. The journal calls only these methods, so a new format
+(xlsx, pptx) plugs in without touching journal or render code.
+
+Key invariants an implementation must uphold:
+
+* ``to_model()`` returns a tree whose ``node_id``s are **opaque and
+  edit-invariant** (never content hashes).
+* ``apply(op)`` mutates the in-memory model and **raises on a before-mismatch or
+  an oversized op** (the validation the MCP boundary also performs, enforced here
+  so direct/core callers get the same guarantee).
+* ``render_tracked()`` returns native tracked-changes bytes (for docx: real
+  ``w:ins``/``w:del`` revisions a Word/LibreOffice user can accept/reject).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from changex_core.model.nodes import Node
+from changex_core.ops.vocabulary import Op
+
+
+class AdapterError(RuntimeError):
+    """Base error for adapter operations."""
+
+
+class BeforeMismatchError(AdapterError):
+    """Raised when an op's ``before`` substring is not present in the node.
+
+    This is the boundary guard that kills blind full-node overwrites: the agent
+    must pass the exact text it intends to change, and the adapter refuses if the
+    node's current content does not contain it.
+    """
+
+
+class OversizedOpError(AdapterError):
+    """Raised when an op rewrites too much of a node or spans more than one node.
+
+    The structured message instructs the caller to split the change — the error
+    message is itself the prompt the model should act on.
+    """
+
+
+class NodeNotFoundError(AdapterError):
+    """Raised when an op targets a ``node_id`` not present in the model."""
+
+
+class UnsupportedFormatError(AdapterError):
+    """Raised when no registered adapter handles a path's file extension.
+
+    Emitted by :func:`changex_core.adapters.load_adapter` when the (sanitized)
+    path's suffix is not one of the registered formats (``.docx`` / ``.xlsx`` /
+    ``.csv`` / ``.pptx``). The message lists the supported suffixes so the caller
+    can correct the input.
+    """
+
+
+class DocumentAdapter(ABC):
+    """Abstract base for format adapters (docx implemented; others reserved)."""
+
+    @classmethod
+    @abstractmethod
+    def load(cls, path: str) -> "DocumentAdapter":
+        """Load a document from a (sanitized) path and build the model."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def baseline_sha256(self) -> str:
+        """Return the sha256 of the original document bytes captured on load."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def to_model(self) -> Node:
+        """Return the current canonical model tree (root node)."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def set_model(self, root: Node) -> None:
+        """Reset the adapter's working state to ``root`` (used by replay)."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def resolve(self, node_id: str) -> Node | None:
+        """Return the model node with ``node_id``, or ``None`` if absent."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def apply(self, op: Op) -> None:
+        """Apply one op to the model.
+
+        Raises:
+            BeforeMismatchError: if the op's ``before`` is absent.
+            OversizedOpError: if the op is too large / multi-node.
+            NodeNotFoundError: if the target node is missing.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def render_tracked(self) -> bytes:
+        """Render the applied ops as native tracked-changes bytes."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def save(self, out_path: str) -> None:
+        """Write the tracked document to a (sanitized) ``out_path``."""
+        raise NotImplementedError