texpkg 0.1.0__tar.gz

texpkg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilja Orlovs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

texpkg-0.1.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: texpkg
+Version: 0.1.0
+Summary: LaTeX package management.
+Author-Email: Ilja Orlovs <ilja@release.art>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/release-art/texpkg
+Project-URL: Repository, https://github.com/release-art/texpkg
+Requires-Python: <3.16,>=3.15
+Requires-Dist: texmodel>=0.4.0
+Requires-Dist: pydantic>=2.14.1
+Provides-Extra: build
+Requires-Dist: typer>=0.27.3; extra == "build"
+Requires-Dist: pdm-backend>=2.4; extra == "build"
+Description-Content-Type: text/markdown
+
+# texpkg
+
+LaTeX package management.
+
+```zsh
+pdm install
+git config core.hooksPath .githooks   # pre-commit runs ruff and pyright
+bin/autoformat.sh
+bin/test.sh                           # pytest, 100% coverage gate
+```

texpkg-0.1.0/README.md

@@ -0,0 +1,10 @@
+# texpkg
+
+LaTeX package management.
+
+```zsh
+pdm install
+git config core.hooksPath .githooks   # pre-commit runs ruff and pyright
+bin/autoformat.sh
+bin/test.sh                           # pytest, 100% coverage gate
+```

texpkg-0.1.0/pyproject.toml

@@ -0,0 +1,202 @@
+[project]
+name = "texpkg"
+dynamic = []
+description = "LaTeX package management."
+authors = [
+    { name = "Ilja Orlovs", email = "ilja@release.art" },
+]
+license = "MIT"
+license-files = [
+    "LICENSE",
+]
+readme = "README.md"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.15",
+    "Typing :: Typed",
+]
+requires-python = ">=3.15,<3.16"
+dependencies = [
+    "texmodel>=0.4.0",
+    "pydantic>=2.14.1",
+]
+version = "0.1.0"
+
+[project.optional-dependencies]
+build = [
+    "typer>=0.27.3",
+    "pdm-backend>=2.4",
+]
+
+[project.scripts]
+texpkg-build = "texpkg_build.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/release-art/texpkg"
+Repository = "https://github.com/release-art/texpkg"
+
+[tool.ruff]
+target-version = "py315"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "B",
+    "C",
+    "E",
+    "F",
+    "I",
+    "W",
+    "N",
+    "C4",
+    "T20",
+    "PTH",
+]
+ignore = [
+    "N802",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = [
+    "F401",
+    "E402",
+]
+
+[tool.ruff.lint.isort]
+order-by-type = true
+combine-as-imports = true
+force-wrap-aliases = true
+known-first-party = [
+    "texpkg",
+]
+forced-separate = [
+    "tests",
+]
+
+[tool.ruff.format]
+line-ending = "lf"
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+]
+strict = [
+    "src",
+]
+pythonVersion = "3.15"
+extraPaths = [
+    "src",
+    "tests/fixtures",
+]
+
+[tool.pytest.ini_options]
+addopts = "-v -l --color=yes --cov=texpkg --cov=texpkg_build --cov-report term-missing --cov-fail-under=100 --no-cov-on-fail"
+pythonpath = [
+    "src",
+    "tests/fixtures",
+]
+testpaths = [
+    "tests",
+]
+timeout = 15
+markers = [
+    "tex: needs the reference image with latexmk (skipped without it; TEXPKG_REQUIRE_TEX=1 makes that a failure)",
+]
+
+[tool.importlinter]
+root_packages = [
+    "texpkg",
+    "texpkg_build",
+]
+include_external_packages = true
+
+[[tool.importlinter.contracts]]
+name = "the run time does not know the build"
+type = "forbidden"
+source_modules = [
+    "texpkg",
+]
+forbidden_modules = [
+    "texpkg_build",
+]
+
+[[tool.importlinter.contracts]]
+name = "the run time imports only the standard library, texmodel and pydantic"
+type = "forbidden"
+source_modules = [
+    "texpkg",
+]
+forbidden_modules = [
+    "typer",
+    "pdm",
+    "jsonschema",
+    "hypothesis",
+    "pytest",
+    "texmodel_build",
+]
+
+[[tool.importlinter.contracts]]
+name = "only cli prints and formats"
+type = "forbidden"
+source_modules = [
+    "texpkg",
+    "texpkg_build.hook",
+    "texpkg_build.testing",
+    "texpkg_build._internal",
+]
+forbidden_modules = [
+    "typer",
+    "texpkg_build.cli",
+]
+
+[[tool.importlinter.contracts]]
+name = "nothing starts a process"
+type = "forbidden"
+source_modules = [
+    "texpkg",
+    "texpkg_build",
+]
+forbidden_modules = [
+    "subprocess",
+]
+allow_indirect_imports = true
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.version]
+source = "scm"
+tag_regex = "^v(?P<version>\\d+\\.\\d+\\.\\d+.*)$"
+fallback_version = "0.0.0"
+
+[tool.pdm.build]
+package-dir = "src"
+includes = [
+    "src/texpkg",
+    "src/texpkg_build",
+]
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.16.0",
+    "pytest-timeout>=2.4.0",
+    "ruff>=0.17.1",
+    "pyright>=1.1.414",
+    "pip-audit>=2.7",
+    "hypothesis>=6",
+    "import-linter>=2.15",
+    "jsonschema>=4.26.0",
+    "pdm-backend>=2.5.0",
+    "pikepdf>=10.17.0",
+    "proof-pdf>=0.3.3",
+]

texpkg-0.1.0/src/texpkg/__init__.py

@@ -0,0 +1,18 @@
+"""texpkg: TeX packages published as Python packages. The declaration types an author writes."""
+
+from .assets import Asset, Role
+from .declaration import Design, Distribution, Kind, Variant
+from .migration import DefaultChange, Migrated, Unresolved, migration
+
+__all__ = [
+    "Asset",
+    "DefaultChange",
+    "Design",
+    "Distribution",
+    "Kind",
+    "Migrated",
+    "Role",
+    "Unresolved",
+    "Variant",
+    "migration",
+]

texpkg-0.1.0/src/texpkg/_internal/__init__.py

@@ -0,0 +1 @@
+"""The internal modules of the run time: not public API."""

texpkg-0.1.0/src/texpkg/_internal/adopt.py

@@ -0,0 +1,119 @@
+"""Adopting a release: the stored state of a document becomes a valid tree of this release, or nothing does (V14, V22,
+V23, V29, V31, V32).
+
+Every migration across the `data` versions crossed runs, in the order the build's, the kind's, the consumer's; the
+result is validated whole; any unresolved item, any validation error and any stored field the model no longer has
+left aborts with the report.
+"""
+
+import copy
+from collections.abc import Iterator, Mapping, Sequence
+from typing import Any
+
+from texmodel.components import Node
+
+from ..declaration import Kind
+from ..errors import MigrationError
+from ..migration import DefaultChange, Migration, Unresolved
+from . import state
+from .envelope import Envelope
+from .history import problems, unplaced
+
+UNRESOLVED = (
+    "$unresolved"  # in the state a migration gets: what the earlier ones left, as `{"path", "reason", "value"}`
+)
+
+
+def _policy(changes: DefaultChange | Mapping[str, DefaultChange], path: str, key: str) -> DefaultChange:
+    """The policy for a default: the one named by the field's data path, else by `Class.field`, else `FOLLOW` (V23)."""
+    if isinstance(changes, DefaultChange):
+        return changes
+    return changes.get(path, changes.get(key, DefaultChange.FOLLOW))
+
+
+def _walk(node: dict[str, Any], path: str = "") -> Iterator[tuple[str, dict[str, Any]]]:
+    yield path, node
+    for i, child in enumerate(node.get("content", ())):
+        yield from _walk(child, f"{path}/content/{i}")
+
+
+def default_changes(
+    tree: dict[str, Any],
+    old: Mapping[str, Any],
+    new: Mapping[str, Any],
+    policy: DefaultChange | Mapping[str, DefaultChange],
+) -> list[dict[str, Any]]:
+    """Apply the consumer's policy to every value still marked as a default whose default this release changed (V22): a
+    value that follows needs nothing (the model fills the new default); one that is frozen keeps the old value and stops
+    being marked; one that asks is returned as unresolved."""
+    changed = {key for key in old.keys() & new.keys() if old[key] != new[key]}
+    asked: list[dict[str, Any]] = []
+    for path, node in _walk(tree):
+        for field in list(node.get(state.DEFAULTS, ())):
+            key = f"{node.get('type')}.{field}"
+            if key not in changed:
+                continue
+            action = _policy(policy, f"{path}/{field}", key)
+            if action is DefaultChange.FREEZE:
+                node[field] = old[key]
+                node[state.DEFAULTS].remove(field)
+            elif action is DefaultChange.ASK:
+                reason = f"the default of {key} changed from {old[key]!r} to {new[key]!r}"
+                asked.append(
+                    {"path": f"{path}/{field}", "reason": reason, "value": node.get(field), "boundary": "defaults"}
+                )
+        if not node.get(state.DEFAULTS, True):
+            del node[state.DEFAULTS]
+    return asked
+
+
+def _kind_migrations(kind: Kind, boundary: int, base_data: Mapping[int, int] | None) -> list[Migration]:
+    """The kind's own migrations for `boundary`. An exposed base kind's are numbered by the base: the ones for the base
+    versions that this package's `boundary` stands for run at it (P30)."""
+    if base_data is None:
+        return [m for m in kind.migrations if m.to == boundary]
+    low, high = base_data.get(boundary - 1, 0), base_data.get(boundary, 0)
+    return [m for m in kind.migrations if low < m.to <= high]
+
+
+def adopt(
+    *,
+    kind: Kind,
+    envelope: Envelope,
+    current: int,
+    age: int,
+    consumer: Sequence[Migration],
+    policy: DefaultChange | Mapping[str, DefaultChange],
+    saved_defaults: Mapping[str, Any] | None,
+    base_data: Mapping[int, int] | None = None,
+) -> Node:
+    """The tree of `kind` that `envelope` describes at `data` version `current`, or a `MigrationError` naming everything
+    that no migration placed. Nothing is written."""
+    tree = copy.deepcopy(envelope.tree)
+    left: list[dict[str, Any]] = []
+    if saved_defaults is not None:
+        left += default_changes(tree, saved_defaults, state.defaults_table(kind.model), policy)
+    if envelope.data < current - age:
+        for boundary in range(envelope.data + 1, current + 1):
+            label = f"{boundary - 1} -> {boundary}"
+            for migration in (*_kind_migrations(kind, boundary, base_data), *(m for m in consumer if m.to == boundary)):
+                tree[UNRESOLVED] = left
+                result = migration(tree)
+                tree = result.state
+                left = [*tree.pop(UNRESOLVED, []), *({**vars(u), "boundary": label} for u in result.unresolved)]
+    schema = state.schema(kind.model, "validation")
+    left += [{**p, "boundary": "validation"} for p in unplaced(tree, schema)]
+    left += [{**p, "boundary": "validation"} for p in problems(kind.model, state.given(tree), schema)]
+    if left:
+        items = tuple(
+            Unresolved(i["path"], i["reason"], i.get("value"), i.get("schema") or {}, i.get("boundary", ""))
+            for i in left
+        )
+        shown = "; ".join(f"{u.path or '/'} ({u.boundary}): {u.reason}" for u in items)
+        raise MigrationError(
+            f"{len(items)} unresolved: {shown}",
+            code="TP-M003",
+            unresolved=items,
+            hint="extend the process with a migration of your own: load(path, migrations=[...])",
+        )
+    return state.tree_from_state(kind.model, tree)

texpkg-0.1.0/src/texpkg/_internal/classify.py

@@ -0,0 +1,190 @@
+"""Diffing two snapshots into bumps (V12, V13): Avro-style rules over schemas, names and signatures over the interface.
+
+In the run time because `changes(old, new)` diffs two shipped snapshots. Written to move into texmodel (V9, X5): it
+reads
+JSON Schema and plain dicts, and only the triples of texpkg.
+"""
+
+import dataclasses
+import enum
+from typing import Any
+
+from ..contracts import Pair, Triple
+
+
+@enum.unique
+class Level(enum.IntEnum):
+    """How much a change asks of a contract's consumers; the largest of a contract's changes decides its bump (V10)."""
+
+    NONE = 0
+    REVISION = 1  # implementation only: a description, a default, a doc
+    COMPATIBLE = 2  # an addition: old data and old callers still work
+    BREAKING = 3
+
+
+@dataclasses.dataclass(frozen=True)
+class Change:
+    level: Level
+    where: str  # `Class.field`, `kind expert`, `component Fact`
+    what: str
+
+
+_UPPER = ("maxLength", "maximum", "maxItems", "exclusiveMaximum")  # lowering one tightens it
+_LOWER = ("minLength", "minimum", "minItems", "exclusiveMinimum")  # raising one tightens it
+
+
+def _compare_property(where: str, old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    out: list[Change] = []
+    for key in ("type", "$ref", "const", "format", "pattern"):
+        if old.get(key) != new.get(key):
+            out.append(Change(Level.BREAKING, where, f"{key} changed from {old.get(key)!r} to {new.get(key)!r}"))
+    if (gone := [v for v in old.get("enum", ()) if v not in new.get("enum", ())]) or ("enum" in old) != ("enum" in new):
+        out.append(Change(Level.BREAKING, where, f"values no longer allowed: {gone or 'any'}"))
+    elif added := [v for v in new.get("enum", ()) if v not in old.get("enum", ())]:
+        out.append(Change(Level.COMPATIBLE, where, f"values added: {added}"))
+    for key in _UPPER + _LOWER:
+        was, now = old.get(key), new.get(key)
+        if was == now:
+            continue
+        tighter = now is not None and (was is None or (now < was if key in _UPPER else now > was))
+        out.append(Change(Level.BREAKING if tighter else Level.COMPATIBLE, where, f"{key} {was} -> {now}"))
+    if old.get("items") != new.get("items") and "items" in old:
+        out += _compare_items(where, old["items"], new.get("items", {}))
+    for key in ("default", "description", "title"):
+        if old.get(key) != new.get(key):
+            out.append(Change(Level.REVISION, where, f"{key} changed"))
+    return out
+
+
+def _compare_items(where: str, old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    """The element schema of a list: a branch of a union that went is breaking, one that came is compatible."""
+
+    def refs(items: dict[str, Any]) -> set[str]:
+        branches = items.get("oneOf") or [items]
+        return {b.get("$ref", b.get("type", "")) for b in branches}
+
+    gone, added = refs(old) - refs(new), refs(new) - refs(old)
+    out = [Change(Level.BREAKING, where, f"{g} is no longer allowed here") for g in sorted(gone)]
+    out += [Change(Level.COMPATIBLE, where, f"{a} is allowed here") for a in sorted(added)]
+    return out or ([] if old == new else _compare_property(where, old, new))
+
+
+def _classes(schema: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    out = {str(schema.get("title")): schema}
+    out |= {str(node.get("title", name)): node for name, node in schema.get("$defs", {}).items()}
+    return out
+
+
+def schema_changes(old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    """What changed in the data a kind accepts (the input schema): the changes, each with its level (V12)."""
+    out: list[Change] = []
+    was, now = _classes(old), _classes(new)
+    for title in sorted(was.keys() - now.keys()):
+        out.append(Change(Level.BREAKING, title, "no longer part of the kind"))
+    for title in sorted(now.keys() - was.keys()):
+        out.append(Change(Level.COMPATIBLE, title, "added to the kind"))
+    for title in sorted(was.keys() & now.keys()):
+        before, after = was[title].get("properties", {}), now[title].get("properties", {})
+        renamed = {p.get("x-renamed-from"): name for name, p in after.items() if p.get("x-renamed-from")}
+        for name in before:
+            if name in after:
+                out += _compare_property(f"{title}.{name}", before[name], after[name])
+            elif name in renamed:
+                out.append(
+                    Change(Level.COMPATIBLE, f"{title}.{name}", f"renamed {renamed[name]} (old name still read)")
+                )
+            else:
+                out.append(Change(Level.BREAKING, f"{title}.{name}", "removed"))
+        now_required, was_required = set(now[title].get("required", ())), set(was[title].get("required", ()))
+        for name in sorted((now_required - was_required) & before.keys() & after.keys()):
+            out.append(Change(Level.BREAKING, f"{title}.{name}", "became required"))
+        for name in sorted(after.keys() - before.keys() - set(renamed.values())):
+            level = Level.BREAKING if name in now_required else Level.COMPATIBLE
+            out.append(Change(level, f"{title}.{name}", "added" + (" and required" if name in now_required else "")))
+    return out
+
+
+def interface_changes(old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    """What changed in the public names and their signatures, and in the kinds and variants (V12)."""
+    out: list[Change] = []
+    for section, label in (("components", "component"), ("kinds", "kind")):
+        was, now = old.get(section, {}), new.get(section, {})
+        out += [Change(Level.BREAKING, f"{label} {n}", "removed") for n in sorted(was.keys() - now.keys())]
+        out += [Change(Level.COMPATIBLE, f"{label} {n}", "added") for n in sorted(now.keys() - was.keys())]
+        for name in sorted(was.keys() & now.keys()):
+            out += _compare_entry(f"{label} {name}", was[name], now[name])
+    return out
+
+
+def _compare_entry(where: str, old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    out: list[Change] = []
+    for key in sorted(old.keys() | new.keys()):
+        if old.get(key) == new.get(key):
+            continue
+        if key == "variants":
+            gone, added = set(old.get(key, ())) - set(new.get(key, ())), set(new.get(key, ())) - set(old.get(key, ()))
+            out += [Change(Level.BREAKING, where, f"variant {v} removed") for v in sorted(gone)]
+            out += [Change(Level.COMPATIBLE, where, f"variant {v} added") for v in sorted(added)]
+        elif key == "doc":
+            out.append(Change(Level.REVISION, where, "documentation changed"))
+        elif key == "signature":
+            added = new.get(key, [])[len(old.get(key, [])) :]
+            keeps = new.get(key, [])[: len(old.get(key, []))] == old.get(key, [])
+            if keeps and all(arg[2] for arg in added):  # trailing optional arguments: old calls still work
+                out.append(Change(Level.COMPATIBLE, where, f"optional arguments added: {[a[0] for a in added]}"))
+            else:
+                out.append(Change(Level.BREAKING, where, "signature changed"))
+        else:
+            out.append(Change(Level.BREAKING, where, f"{key} changed from {old.get(key)!r} to {new.get(key)!r}"))
+    return out
+
+
+def worst(changes: list[Change]) -> Level:
+    return max((c.level for c in changes), default=Level.NONE)
+
+
+def bump(previous: Triple, level: Level) -> Triple:
+    """libtool's rules (V10): none keeps it, a revision adds one, an addition raises `current` and `age`, a break
+    resets them."""
+    match level:
+        case Level.NONE:
+            return previous
+        case Level.REVISION:
+            return Triple(previous.current, previous.revision + 1, previous.age)
+        case Level.COMPATIBLE:
+            return Triple(previous.current + 1, 0, previous.age + 1)
+        case Level.BREAKING:
+            return Triple(previous.current + 1, 0, 0)
+
+
+def bump_output(previous: Pair, change: str) -> Pair:
+    """`output` has no age: `current` when the appearance changed, `revision` when only bytes did (V10). `change` is the
+    author's statement; an empty one means nothing changed."""
+    match change:
+        case "current":
+            return Pair(previous.current + 1, 0)
+        case "revision":
+            return Pair(previous.current, previous.revision + 1)
+        case _:
+            return previous
+
+
+Version = tuple[int, int, int]
+
+
+def parse_version(text: str) -> Version:
+    major, minor, patch = (int(p) for p in text.split(".")[:3])
+    return major, minor, patch
+
+
+def required_release(previous: str, data: Level, interface: Level, output_changed: bool) -> str:
+    """The smallest release number that does not understate the contracts (V13): a break is major, any other change
+    minor, no contract change a patch; each one place lower before 1.0."""
+    major, minor, patch = parse_version(previous)
+    breaking = Level.BREAKING in (data, interface)
+    changed = bool(data or interface) or output_changed
+    if major == 0:
+        return f"0.{minor + 1}.0" if breaking else f"0.{minor}.{patch + 1}"
+    if breaking:
+        return f"{major + 1}.0.0"
+    return f"{major}.{minor + 1}.0" if changed else f"{major}.{minor}.{patch + 1}"

texpkg-0.1.0/src/texpkg/_internal/directory.py

@@ -0,0 +1,48 @@
+"""The document directory (P27, D5): one visible `_texpkg/` folder beside the `.tex`, the payload and the consumer's own
+files. Everything here takes the directory and text; nothing knows what a kind is."""
+
+import pathlib
+import shutil
+from collections.abc import Mapping
+
+DIR = "_texpkg"
+STATE = f"{DIR}/state.json"  # the user's state (D1)
+TEMPLATE = f"{DIR}/template.json"  # the package as it was when the document was saved (D1, D6)
+HISTORY = 3  # the last saves kept (D2)
+
+
+def plan_file(variant: str | None) -> str:
+    """The saved plan of the `.tex` of `variant` (D7)."""
+    return f"{DIR}/plan.json" if variant is None else f"{DIR}/plan-{variant}.json"
+
+
+def read(root: pathlib.Path, rel: str) -> str | None:
+    path = root / rel
+    return path.read_text(encoding="utf-8") if path.is_file() else None
+
+
+def differing(root: pathlib.Path, files: Mapping[str, str]) -> dict[str, str]:
+    """The files whose text on disk is not `files`' (absent counts): content, never time (A4)."""
+    return {rel: text for rel, text in files.items() if read(root, rel) != text}
+
+
+def write(root: pathlib.Path, files: Mapping[str, str]) -> None:
+    for rel, text in files.items():
+        (root / rel).parent.mkdir(parents=True, exist_ok=True)
+        (root / rel).write_text(text, encoding="utf-8")
+
+
+def rotate_history(root: pathlib.Path) -> None:
+    """Keep the pair of states on disk as `history/1`, the earlier ones one further, and drop what is beyond `HISTORY`
+    (D2, D3). Nothing happens when there is no pair yet."""
+    pair = [rel for rel in (STATE, TEMPLATE) if (root / rel).is_file()]
+    if not pair:
+        return
+    history = root / DIR / "history"
+    shutil.rmtree(history / str(HISTORY), ignore_errors=True)
+    for n in range(HISTORY - 1, 0, -1):
+        if (history / str(n)).is_dir():
+            (history / str(n)).rename(history / str(n + 1))
+    (history / "1").mkdir(parents=True)
+    for rel in pair:
+        shutil.copyfile(root / rel, history / "1" / pathlib.PurePosixPath(rel).name)

texpkg-0.1.0/src/texpkg/_internal/envelope.py

@@ -0,0 +1,37 @@
+"""The envelope of a stored document: `{package, kind, data, tree}` (K3). It names the package and kind the tree belongs
+to and the `data` version it was written for (V14)."""
+
+import dataclasses
+import json
+from typing import Any
+
+from ..errors import NotADocumentError
+
+
+def dumps(value: object) -> str:
+    """The text of a state file: stable, readable, one trailing newline."""
+    return json.dumps(value, indent=2, ensure_ascii=False) + "\n"
+
+
+@dataclasses.dataclass(frozen=True)
+class Envelope:
+    package: str
+    kind: str
+    data: int
+    tree: dict[str, Any]
+
+    def to_text(self) -> str:
+        return dumps({"package": self.package, "kind": self.kind, "data": self.data, "tree": self.tree})
+
+    @classmethod
+    def parse(cls, text: str, where: str) -> "Envelope":
+        try:
+            found = json.loads(text)
+            return cls(str(found["package"]), str(found["kind"]), int(found["data"]), dict(found["tree"]))
+        except (ValueError, KeyError, TypeError) as exc:
+            raise NotADocumentError(
+                f"{where}: not a document state ({exc!r})",
+                code="TP-D001",
+                path=where,
+                hint="it is written by a kind's create and save",
+            ) from exc