texpkg 0.1.0__py3-none-any.whl

texpkg_build/_internal/checks.py

@@ -0,0 +1,154 @@
+"""What the build refuses (B4): a defect fails `pdm build`, not a consumer's import."""
+
+import importlib
+import pathlib
+import re
+from types import ModuleType
+from typing import Any
+
+from texmodel.components import control_name
+from texmodel.errors import DeclarationError as TexmodelDeclarationError
+
+from texpkg._internal import classify, payload
+from texpkg._internal.release import Release
+from texpkg.contracts import Contracts
+from texpkg.declaration import Distribution
+from texpkg.errors import DeclarationError
+from texpkg.protocol import KindModule, KindsModule, PackageModule
+
+from . import snapshot
+
+
+def declaration_directory(dist: Distribution) -> pathlib.Path:
+    """The directory of the declaration package, which the build copies whole (P22)."""
+    path = pathlib.Path(str(dist.files))
+    if not (path / "__init__.py").is_file():
+        raise DeclarationError(
+            f"{dist.declared_in}: the declaration must be a package (a directory with an __init__.py)",
+            code="TP-B004",
+            path=dist.declared_in,
+            hint="move the declaration into a package; its assets and templates live beside it",
+        )
+    return path
+
+
+def assets_are_there(dist: Distribution) -> None:
+    """Every asset of the chain is a file (A3), and no two land on one payload path (P11, `TP-A002`)."""
+    if gone := [r.asset.path for r in dist.resolved_assets() if not r.source.is_file()]:
+        raise DeclarationError(
+            f"missing assets: {', '.join(gone)}",
+            code="TP-B005",
+            path=gone[0],
+            hint=f"they are read from the package {dist.declared_in}",
+        )
+    payload.build({f"{d.package.name}.sty": "" for d in dist.chain()}, tuple(dist.resolved_assets()), dist.layout)
+
+
+def module_satisfies_the_protocols(module: ModuleType) -> None:
+    """The generated module has the fixed surface (P6)."""
+    name = module.__name__
+    candidate: object = module
+    kinds: object = getattr(module, "kinds", None)
+    problems = [] if isinstance(candidate, PackageModule) else ["the package module"]
+    if isinstance(kinds, KindsModule):
+        problems += [
+            f"kinds.{n}" for n, m in dict[str, object](kinds.modules()).items() if not isinstance(m, KindModule)
+        ]
+    else:
+        problems.append("kinds")
+    if problems:
+        raise DeclarationError(
+            f"the generated module {name} does not satisfy the protocol: {', '.join(problems)}",
+            code="TP-B006",
+            path=name,
+            hint="this is a texpkg defect: texpkg.protocol lists the surface",
+        )
+
+
+def tex_names_are_unique(dist: Distribution) -> None:
+    """No two packages of the chain define one control sequence (P11): the later `.sty` would redefine the earlier."""
+    seen: dict[str, str] = {}
+    for member in reversed(dist.chain()):
+        for cls in member.package.registered:
+            try:
+                name = control_name(cls)
+            except TexmodelDeclarationError:
+                continue  # a colour has no control sequence
+            if seen.setdefault(name, member.name) != member.name:
+                raise DeclarationError(
+                    f"\\{name} is defined by {seen[name]} and by {member.name}",
+                    code="TP-B009",
+                    path=name,
+                    hint="a package built on another must not reuse its names: choose another prefix or name",
+                )
+
+
+def design_is_valid(dist: Distribution) -> None:
+    """The embedded data validates against its model (L1)."""
+    if dist.design is None:
+        return
+    try:
+        dist.design.load(dist.files)
+    except (OSError, ValueError) as exc:  # a missing file, bad JSON and pydantic's ValidationError are all of these
+        raise DeclarationError(
+            f"{dist.name}: the design data {dist.design.path} is not a valid {dist.design.model.__name__}: {exc}",
+            code="TP-B010",
+            path=dist.design.path,
+            hint="fix the file, or the model it is validated against",
+        ) from exc
+
+
+_RELEASE = re.compile(r"\d+\.\d+\.\d+")
+
+
+def contract_gate(
+    root: pathlib.Path, dist: Distribution, release: Release, version: str
+) -> tuple[Contracts, list[pathlib.Path]]:
+    """The contract versions this build carries, and the frozen snapshots that ship (V12, V13, V17, V37). Without a
+    `contracts` directory a package has the first versions and ships none. A development build is held to `next`: it
+    must be current and an output change must be classified. A release build must have its own newest frozen
+    directory, and its number must not understate the contracts."""
+    if not (root / snapshot.CONTRACTS).is_dir():
+        return Contracts(), []
+    held = snapshot.frozen(root)
+    current = snapshot.base_current(dist)
+    proposal = snapshot.propose(root, dist, release, snapshot.sty_of(dist), base_current=current)
+    if _RELEASE.fullmatch(version):
+        if not held or held[-1].name != version:
+            raise DeclarationError(
+                f"release {version}: contracts/{version} is not the newest frozen snapshot",
+                code="TP-C003",
+                hint="freeze it first: texpkg-build contracts --freeze",
+            )
+        required = snapshot.required_for(held[-2] if len(held) > 1 else None, held[-1])
+        if classify.parse_version(version) < classify.parse_version(required):
+            raise DeclarationError(
+                f"release {version} understates the contracts: they need {required}",
+                code="TP-C004",
+                hint=f"tag {required} or later",
+            )
+        versions = snapshot.read_versions(held[-1])
+    else:
+        if stale := snapshot.stale(root, proposal.files):
+            raise DeclarationError(
+                f"contracts/next is not current: {', '.join(stale)}",
+                code="TP-C001",
+                hint="run texpkg-build contracts and review the files",
+            )
+        if proposal.output and not proposal.versions.output_change:
+            raise DeclarationError(
+                f"the output changed ({', '.join(proposal.output)}) and contracts/next/versions.toml does not say how",
+                code="TP-C005",
+                hint='under [output] write change = "current" (visible: proofs need approving again) or "revision"',
+            )
+        versions = snapshot.read_versions(root / snapshot.CONTRACTS / snapshot.NEXT)
+    assert versions is not None
+    if dist.base is not None and versions.base_interface:
+        base: Any = importlib.import_module(dist.base.module).CONTRACTS
+        if versions.base_interface < base.interface.current - base.interface.age:
+            raise DeclarationError(
+                f"the base no longer supports the interface {versions.base_interface} this package relies on",
+                code="TP-C006",
+                hint="adapt to the new base, then set [base] interface in contracts/next/versions.toml",
+            )
+    return versions.contracts(), held

texpkg_build/_internal/embed.py

@@ -0,0 +1,254 @@
+"""Copying embedded packages and rewriting their imports (P13-P19, B7, B10, 1.5).
+
+A wheel holds one copy of texmodel, of texpkg's run time and of each package in its base chain, side by side under
+`<module>/_embedded/`. Every import of an embedded name, absolute or relative into another embedded copy, is found with
+`ast` and rewritten as a relative import of the private copy; nothing is matched by regular expression.
+"""
+
+import ast
+import pathlib
+import shutil
+import sys
+from collections.abc import Callable, Iterator, Sequence
+
+from texpkg.declaration import Distribution
+from texpkg.errors import DeclarationError
+
+EMBEDDED = "_embedded"
+RUN_TIME = ("texmodel", "texpkg")
+ALLOWED = frozenset({"pydantic", "pydantic_core", "annotated_types", "typing_extensions", "typing_inspection"})
+_SKIP = shutil.ignore_patterns("__pycache__", "*.pyc")
+
+type Mapping = Callable[[str], str | None]
+
+
+def relative(package: tuple[str, ...], target: tuple[str, ...]) -> tuple[int, str]:
+    """The level and module of the relative import that reaches `target` from a module in `package`."""
+    common = 0
+    while common < min(len(package), len(target)) and package[common] == target[common]:
+        common += 1
+    return len(package) - common + 1, ".".join(target[common:])
+
+
+def _absolute(node: ast.ImportFrom, package: tuple[str, ...]) -> tuple[str, ...]:
+    base = package[: len(package) - (node.level - 1)] if node.level else ()
+    return (*base, *(node.module.split(".") if node.module else ()))
+
+
+def _fail(code: str, message: str, where: str, hint: str) -> DeclarationError:
+    return DeclarationError(message, code=code, path=where, hint=hint)
+
+
+def _names(aliases: list[ast.alias]) -> str:
+    return ", ".join(a.name + (f" as {a.asname}" if a.asname else "") for a in aliases)
+
+
+def _from_statement(node: ast.ImportFrom, old: tuple[str, ...], new: tuple[str, ...], mapping: Mapping) -> str | None:
+    mapped = mapping(".".join(_absolute(node, old)))
+    if mapped is None:
+        return None
+    level, module = relative(new, tuple(mapped.split(".")))
+    if (level, module) == (node.level, node.module or ""):
+        return None  # a relative import inside what moves rigidly stays as it is
+    return f"from {'.' * level}{module} import {_names(node.names)}"
+
+
+def _import_statement(node: ast.Import, new: tuple[str, ...], mapping: Mapping, where: str) -> str | None:
+    if not any(mapping(a.name) is not None for a in node.names):
+        return None
+    lines: list[str] = []
+    for alias in node.names:
+        mapped = mapping(alias.name)
+        if mapped is None:
+            lines.append(f"import {_names([alias])}")
+            continue
+        if "." in alias.name and not alias.asname:
+            parent, _, child = alias.name.rpartition(".")
+            raise _fail(
+                "TP-E001",
+                f"{where}: `import {alias.name}` binds the top package, which cannot be pointed at the private copy",
+                where,
+                f"write `from {parent} import {child}`",
+            )
+        *parent, last = mapped.split(".")
+        level, module = relative(new, tuple(parent))
+        lines.append(f"from {'.' * level}{module} import {last}" + (f" as {alias.asname}" if alias.asname else ""))
+    return ("\n" + " " * node.col_offset).join(lines)
+
+
+def rewrite(source: str, old: tuple[str, ...], new: tuple[str, ...], mapping: Mapping, where: str) -> str:
+    """`source`, a module of package `old` that is moved to package `new`, with each import whose absolute name
+    `mapping` changes written as a relative import from `new`. Other imports are left as they are."""
+    raw = source.encode("utf-8")
+    starts = [0]
+    for line in raw.splitlines(keepends=True):
+        starts.append(starts[-1] + len(line))
+    edits: list[tuple[int, int, str]] = []
+    for node in ast.walk(ast.parse(source)):
+        if isinstance(node, ast.ImportFrom):
+            text = _from_statement(node, old, new, mapping)
+        elif isinstance(node, ast.Import):
+            text = _import_statement(node, new, mapping, where)
+        else:
+            continue
+        if text is not None and node.end_lineno is not None and node.end_col_offset is not None:
+            edits.append(
+                (starts[node.lineno - 1] + node.col_offset, starts[node.end_lineno - 1] + node.end_col_offset, text)
+            )
+    for start, end, text in sorted(edits, reverse=True):
+        raw = raw[:start] + text.encode("utf-8") + raw[end:]
+    return raw.decode("utf-8")
+
+
+def imported_names(source: str) -> Iterator[tuple[str, ast.Import | ast.ImportFrom]]:
+    """Every absolute module name `source` imports, with its node: `import a.b` and `from a.b import c` give `a.b`."""
+    for node in ast.walk(ast.parse(source)):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                yield alias.name, node
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+            yield node.module, node
+
+
+def scan_declaration(source: str, where: str, own: set[str], embedded: set[str]) -> None:
+    """What the build refuses in the author's code (B4): an absolute import of the package itself (P19), a read of the
+    distribution's metadata (B10), a dynamic import of an embedded name, and a module the wheel does not carry."""
+    for name, node in imported_names(source):
+        top = name.split(".")[0]
+        if top in own:
+            raise _fail(
+                "TP-E002",
+                f"{where}:{node.lineno}: absolute import of {name}, which is this package's own name",
+                where,
+                "import the package's own modules relatively (from .model import X), so a copy works anywhere",
+            )
+        if name.startswith("importlib.metadata") or (
+            name == "importlib" and isinstance(node, ast.ImportFrom) and any(a.name == "metadata" for a in node.names)
+        ):
+            raise _fail(
+                "TP-E003",
+                f"{where}: reads distribution metadata ({name}); an embedded copy has none of its own",
+                where,
+                "take the version from the constant the build writes (the module's __version__)",
+            )
+        if top not in sys.stdlib_module_names and top not in ALLOWED and top not in embedded:
+            raise _fail(
+                "TP-E004",
+                f"{where}: imports {name}, which the wheel does not carry",
+                where,
+                "a wheel needs only the standard library, pydantic, texmodel, texpkg and its bases",
+            )
+    for node in ast.walk(ast.parse(source)):
+        if isinstance(node, ast.Call) and node.args and isinstance(node.args[0], ast.Constant):
+            called = node.func.attr if isinstance(node.func, ast.Attribute) else getattr(node.func, "id", "")
+            value = node.args[0].value
+            if (
+                called in ("import_module", "__import__")
+                and isinstance(value, str)
+                and value.split(".")[0] in own | embedded
+            ):
+                raise _fail(
+                    "TP-E005",
+                    f"{where}:{node.lineno}: dynamic import of {value}",
+                    where,
+                    "import it with a plain import statement, which the build can point at the private copy",
+                )
+
+
+def set_generator_version(source: str, version: str) -> str:
+    """texmodel's `GENERATOR_VERSION` set to `version` (B10): a copy has no installed metadata to ask."""
+    unset = "GENERATOR_VERSION: str | None = None\n"
+    if source.count(unset) != 1:
+        raise _fail(
+            "TP-E006",
+            "texmodel.package no longer declares GENERATOR_VERSION as None",
+            "texmodel/package.py",
+            "this texpkg needs a texmodel that reads GENERATOR_VERSION when it is set (texmodel>=0.4.0)",
+        )
+    return source.replace(unset, f"GENERATOR_VERSION: str | None = {version!r}\n")
+
+
+def copy_tree(source: pathlib.Path, dest: pathlib.Path, *, skip: tuple[str, ...] = ()) -> list[pathlib.Path]:
+    """Copy a package directory, leaving out caches and `skip`; the `.py` files copied, for rewriting."""
+    shutil.copytree(source, dest, ignore=shutil.ignore_patterns("__pycache__", "*.pyc", *skip), dirs_exist_ok=True)
+    return sorted(dest.rglob("*.py"))
+
+
+def rewrite_tree(root: pathlib.Path, old: tuple[str, ...], new: tuple[str, ...], mapping: Mapping) -> None:
+    """Rewrite every `.py` under `root`, a package that stands at `old` and is moved to `new`."""
+    for path in sorted(root.rglob("*.py")):
+        rel = path.relative_to(root)
+        package_old = (*old, *rel.parts[:-1])
+        package_new = (*new, *rel.parts[:-1])
+        text = path.read_text(encoding="utf-8")
+        changed = rewrite(text, package_old, package_new, mapping, str(path))
+        if changed != text:
+            path.write_text(changed, encoding="utf-8")
+
+
+def _package_dir(name: str) -> pathlib.Path:
+    """Where the importable package `name` is installed in this build environment."""
+    module = sys.modules.get(name) or __import__(name)
+    return pathlib.Path(next(iter(module.__path__)))
+
+
+def embed(
+    out: pathlib.Path,
+    dist: Distribution,
+    declaration: pathlib.Path,
+    generated: dict[str, str],
+    frozen: Sequence[pathlib.Path] = (),
+) -> None:
+    """Write the module of `dist` into `out` (`<build dir>/<module>`): the generated files, the declaration copied to
+    `_declaration`, and under `_embedded` one copy each of texmodel, texpkg's run time and the base chain (P19), all
+    with their imports of one another rewritten (1.5)."""
+    from texmodel.package import generator_version
+
+    module = dist.module
+    embedded = {*RUN_TIME, *(d.module for d in dist.chain()[1:])}
+    own = {dist.declared_in.split(".")[0], module}
+
+    def to_copy(name: str) -> str | None:
+        return f"{module}._embedded.{name}" if name.split(".")[0] in embedded else None
+
+    copy_tree(declaration, out / "_declaration")
+    for snapshot in frozen:
+        copy_tree(snapshot, out / "_contracts" / snapshot.name)
+    for path in sorted((out / "_declaration").rglob("*.py")):
+        scan_declaration(path.read_text(encoding="utf-8"), str(path.relative_to(out)), own, embedded)
+    for rel, text in generated.items():
+        (out / rel).parent.mkdir(parents=True, exist_ok=True)
+        (out / rel).write_text(text, encoding="utf-8")
+    rewrite_tree(out, (module,), (module,), to_copy)
+    base = out / EMBEDDED
+    base.mkdir()
+    (base / "__init__.py").write_text("", encoding="utf-8")
+    for name, skip in (("texmodel", ("cli.py",)), ("texpkg", ())):
+        copy_tree(_package_dir(name), base / name, skip=skip)
+        rewrite_tree(base / name, (name,), (module, EMBEDDED, name), to_copy)
+    patched = base / "texmodel" / "package.py"
+    patched.write_text(
+        set_generator_version(patched.read_text(encoding="utf-8"), generator_version()), encoding="utf-8"
+    )
+    if dist.base is not None:
+        _embed_base(base, module, dist.base.module)
+
+
+def _embed_base(base: pathlib.Path, module: str, base_module: str) -> None:
+    """The installed base, flattened: its own files, then each package of its `_embedded` that is not texmodel or texpkg
+    (the dependent has its own copy of those, and the base's code is pointed at it)."""
+    source = _package_dir(base_module)
+    prefix = f"{base_module}.{EMBEDDED}."
+
+    def moved(name: str) -> str | None:
+        if name == prefix.removesuffix("."):
+            return f"{module}.{EMBEDDED}"  # `from .._embedded import x`: the bases are now beside this one
+        return f"{module}.{EMBEDDED}.{name.removeprefix(prefix)}" if name.startswith(prefix) else None
+
+    copy_tree(source, base / base_module, skip=(EMBEDDED,))
+    rewrite_tree(base / base_module, (base_module,), (module, EMBEDDED, base_module), moved)
+    lifted = source / EMBEDDED
+    for path in sorted(lifted.iterdir()) if lifted.is_dir() else ():
+        if path.is_dir() and path.name not in RUN_TIME:
+            copy_tree(path, base / path.name)
+            rewrite_tree(base / path.name, (base_module, EMBEDDED, path.name), (module, EMBEDDED, path.name), moved)

texpkg_build/_internal/generate.py

@@ -0,0 +1,254 @@
+"""The generated module's source (P6, K4, V1): plain Python, deterministic (B5), importing the run time by its absolute
+name (`texpkg`), which the embedding step later points at the private copy (1.5).
+
+The module is `acme_tex/{__init__,_bound,_version,errors}.py`, `kinds/{__init__,<kind>}.py` and `_sty/<name>.sty`; the
+declaration is imported from `acme_tex._declaration`, so its classes are real classes a type checker reads (K4).
+"""
+
+import copy
+import inspect
+import textwrap
+import typing
+from collections.abc import Iterator
+from typing import Annotated
+
+from texpkg import errors
+from texpkg._internal import provenance_tex
+from texpkg.contracts import Contracts
+from texpkg.declaration import Distribution, Kind, reachable
+from texpkg.errors import DeclarationError
+
+_HEADER = '"""Generated by texpkg-build from the declaration. Do not edit."""\n'
+_FOREIGN = ("builtins", "typing", "types", "collections", "texmodel", "enum", "pydantic")
+
+
+def render_sty(dist: Distribution, version: str) -> dict[str, str]:
+    """The `.sty` of the distribution's own package, rendered at `version` (P4, V1). The author's object is left as it
+    is. A base's was rendered when the base was built."""
+    package = copy.deepcopy(dist.package)  # a copy that shares no list with the author's: the block is added to it
+    if not package.prefix:
+        raise DeclarationError(
+            f"package {package.name} has no prefix, so it cannot declare its provenance command",
+            code="TP-B011",
+            path=package.name,
+            hint='give the Package a prefix: Package("acme", prefix="ac")',
+        )
+    package.version = version
+    package.library("texpkg-provenance", provenance_tex.declarations(package.prefix, package.name, version))
+    return {f"{package.name}.sty": package.render()}
+
+
+def error_names() -> tuple[str, ...]:
+    return tuple(
+        sorted(name for name, cls in inspect.getmembers(errors, inspect.isclass) if issubclass(cls, errors.TexpkgError))
+    )
+
+
+def _types(hint: object) -> Iterator[type]:
+    """The classes a field's annotation names that the declaration defines: a `Choice`, a bounded length (P24)."""
+    if typing.get_origin(hint) is Annotated:
+        yield from _types(typing.get_args(hint)[0])
+    elif args := typing.get_args(hint):
+        for arg in args:
+            yield from _types(arg)
+    elif isinstance(hint, type) and hint.__module__.split(".")[0] not in _FOREIGN:
+        yield hint
+
+
+def exported(kind: Kind) -> tuple[type, ...]:
+    """The classes a kind module exports: the components its trees are made of, and the value types they use, once each
+    and in the order met."""
+    found: dict[type, None] = {}
+    for cls in reachable(kind.model):
+        found[cls] = None
+        for arg in cls.__tm_args__:
+            found.update(dict.fromkeys(_types(arg.hint)))
+    return tuple(found)
+
+
+def _import_from(dist: Distribution, cls: type) -> str:
+    """`from .._declaration.model import Deck as Deck` for `cls`, relative to `kinds/<kind>.py`, wherever in the chain
+    it is declared."""
+    for owner in dist.chain():
+        prefix = owner.declared_in
+        if cls.__module__ == prefix or cls.__module__.startswith(prefix + "."):
+            if "." in cls.__qualname__:
+                break
+            where = "_declaration" if owner is dist else f"_embedded.{owner.module}._declaration"
+            return f"from ..{where}{cls.__module__.removeprefix(prefix)} import {cls.__name__} as {cls.__name__}"
+    raise DeclarationError(
+        f"{cls.__module__}.{cls.__qualname__} is not a top-level class of the declaration package or of a base",
+        code="TP-B002",
+        path=cls.__qualname__,
+        hint="declare it at module level inside the package named by declared_in, so the module can export it",
+    )
+
+
+def _module(body: str) -> str:
+    return _HEADER + "\n" + textwrap.dedent(body).strip() + "\n"
+
+
+def _kind_source(dist: Distribution, kind: Kind) -> str:
+    imports = "\n        ".join(sorted({_import_from(dist, cls) for cls in exported(kind)}))  # the template's indent
+    root = kind.model.__name__
+    return _module(f"""
+        from collections.abc import Mapping, Sequence
+        from pathlib import Path
+        from typing import Any, Final, Literal
+
+        from texpkg.contracts import Changes
+        from texpkg.document import Document
+        from texpkg.migration import DefaultChange, Migration
+
+        from .. import _bound
+        {imports}
+
+        NAME: Final = {kind.name!r}
+        _api = _bound.RELEASE.kind(NAME, {root})
+
+
+        def load(
+            path: Path | str,
+            *,
+            migrations: Sequence[Migration] = (),
+            default_changes: DefaultChange | Mapping[str, DefaultChange] = DefaultChange.FOLLOW,
+        ) -> Document[{root}]:
+            return _api.load(path, migrations, default_changes)
+
+
+        def create(path: Path | str, tree: {root}) -> Document[{root}]:
+            return _api.create(path, tree)
+
+
+        def schema(mode: Literal["validation", "serialization"] = "validation") -> dict[str, Any]:
+            return _api.schema(mode)
+
+
+        def example() -> {root}:
+            return _api.example()
+
+
+        def variants() -> tuple[str, ...]:
+            return _api.variants()
+
+
+        def changes(old: int, new: int) -> Changes:
+            return _api.changes(old, new)
+    """)
+
+
+def _tuple(items: list[str]) -> str:
+    return "(" + "".join(f"{item!r}, " for item in items).strip() + ")"
+
+
+def sources(dist: Distribution, pointer_attr: str, version: str, contracts: Contracts) -> dict[str, str]:
+    """The generated files by path inside the module, for `dist` released at `version`. `pointer_attr` is the name
+    `[tool.texpkg] distribution` gives the declaration inside its package."""
+    offered = dist.kinds_offered()
+    names = [k.name for k in offered]
+    sty = render_sty(dist, version)
+    c = contracts
+    imports = f"from . import {', '.join(names)}" if names else ""
+    base = dist.base
+    base_import = f"from ._embedded.{base.module} import _bound as _base" if base else ""
+    base_sty = "**_base.STY, " if base else ""
+    base_release = "(_base.RELEASE,), " if base else "(), "
+    return (
+        {f"_sty/{name}": text for name, text in sty.items()}
+        | {
+            "__init__.py": _module("""
+                import datetime
+                from collections.abc import Mapping, Sequence
+                from pathlib import Path
+                from typing import Any, Final
+
+                from texpkg.document import Document
+                from texpkg.migration import DefaultChange, Migrated, Migration, Unresolved, migration
+
+                from . import errors, kinds
+                from ._bound import RELEASE
+                from ._version import CONTRACTS, VERSION
+
+                __version__: Final = VERSION
+                dist: Final = RELEASE.dist  # for a package built on this one (P14)
+                __all__ = [
+                    "CONTRACTS",
+                    "DefaultChange",
+                    "Migrated",
+                    "Unresolved",
+                    "__version__",
+                    "dist",
+                    "errors",
+                    "export",
+                    "kinds",
+                    "load",
+                    "migration",
+                ]
+
+
+                def export(
+                    dest: Path | str, *, now: datetime.datetime | None = None, stamp: str | None = None
+                ) -> tuple[Path, ...]:
+                    return RELEASE.export(dest, now, stamp)
+
+
+                def load(
+                    path: Path | str,
+                    *,
+                    migrations: Sequence[Migration] = (),
+                    default_changes: DefaultChange | Mapping[str, DefaultChange] = DefaultChange.FOLLOW,
+                ) -> Document[Any]:
+                    return RELEASE.load(path, migrations, default_changes)
+            """),
+            "_version.py": _module(f"""
+                from typing import Final
+
+                from texpkg.contracts import Contracts, Pair, Triple
+
+                VERSION: Final = {version!r}
+                CONTRACTS: Final = Contracts(
+                    Triple({c.data.current}, {c.data.revision}, {c.data.age}),
+                    Triple({c.interface.current}, {c.interface.revision}, {c.interface.age}),
+                    Pair({c.output.current}, {c.output.revision}),
+                    {c.base_data!r},
+                )
+            """),
+            "_bound.py": _module(f"""
+                from importlib.resources import files
+                from typing import Final
+
+                from texpkg._internal.release import Release
+
+                from ._declaration import {pointer_attr}
+                from ._version import CONTRACTS, VERSION
+                {base_import}
+
+                _NAMES: Final = {_tuple(list(sty))}
+                _SNAPSHOTS: Final = files(__package__).joinpath("_contracts")
+                _OWN: Final = {{
+                    name: files(__package__).joinpath("_sty", name).read_text(encoding="utf-8") for name in _NAMES
+                }}
+                STY: Final = {{{base_sty}**_OWN}}
+                RELEASE: Final = Release({pointer_attr}, VERSION, CONTRACTS, STY, {base_release}_SNAPSHOTS)
+            """),
+            "errors.py": _module(
+                "from texpkg.errors import (\n" + "".join(f"    {name} as {name},\n" for name in error_names()) + ")\n"
+            ),
+            "kinds/__init__.py": _module(f"""
+                from collections.abc import Mapping
+
+                from texpkg.protocol import KindModule
+
+                {imports}
+
+
+                def names() -> tuple[str, ...]:
+                    return {_tuple(names)}
+
+
+                def modules() -> Mapping[str, KindModule]:
+                    return {{{", ".join(f"{n!r}: {n}" for n in names)}}}
+            """),
+        }
+        | {f"kinds/{kind.name}.py": _kind_source(dist, kind) for kind in offered}
+    )