constant-docs 0.4.0__py3-none-any.whl

constant_docs/api.py

@@ -0,0 +1,968 @@
+"""Orchestration facade for constant-docs.
+
+Public interface: ``plan``, ``apply``, ``verify``, ``prune``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal
+
+from constant_docs import state
+from constant_docs.checks import (
+    CatalogueError,
+    DiagramError,
+    check_architecture,
+    check_catalogue,
+    check_errors,
+)
+from constant_docs.checks import check_body as check_architecture_body
+from constant_docs.checks import sources_for as _sources_for
+from constant_docs.config import MISSING_KEY, Config, ConfigError
+from constant_docs.config import load as load_config
+from constant_docs.config import repo_root as _repo_root
+from constant_docs.decisions import DecisionLoss, check_rewrite
+from constant_docs.document import (
+    EXTENSION_KEY,
+    LEGACY_EXTENSION_KEYS,
+    Document,
+    DocumentCache,
+    DocumentError,
+    extension_block,
+    extract_description,
+    has_required_headings,
+)
+from constant_docs.document import (
+    load as load_document,
+)
+from constant_docs.fingerprint import compute as compute_hash
+from constant_docs.index import conformance_check
+from constant_docs.kinds import (
+    ARCHITECTURE_CHECK,
+    ERRORS_CHECK,
+    Kind,
+    KindError,
+    resolve_prompt,
+)
+from constant_docs.paths import OrphanReport, doc_path_for
+from constant_docs.paths import foreign as find_foreign
+from constant_docs.paths import orphans as find_orphans
+
+_PROMPT_PATH = Path(__file__).parent / "prompts" / "module.md"
+
+
+# ---------------------------------------------------------------------------
+# Data types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ModulePlan:
+    """Everything the harness needs to generate or regenerate a document."""
+
+    module: str
+    doc_path: Path
+    files: list[Path]
+    previous_body: str | None
+    previous_description: str | None
+    required_headings: list[str]
+    reason: Literal["changed", "missing"]
+    # A kind decides the shape of the write. `mode` is the one a caller must
+    # branch on: "replace" takes a whole body through `apply`, "append" takes
+    # a single entry through `append`, and passing one to the other is refused
+    # rather than silently accepted.
+    kind: str = "module"
+    mode: Literal["replace", "append"] = "replace"
+    prompt: str = ""
+
+
+@dataclass(frozen=True)
+class Plan:
+    """Result of a ``plan`` invocation."""
+
+    stale: list[ModulePlan]
+    orphans: list[OrphanReport]
+    fresh: list[str]
+    prompt: str
+    # Modules whose source could not be hashed — a file listed by the walk and
+    # unreadable now, or deleted between the two. One module's problem, carried
+    # rather than raised, so the rest of the report survives it.
+    unreadable: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class PruneReport:
+    """What one ``prune`` deleted, and what it declined to touch.
+
+    Returned rather than printed, so a caller that is not the CLI can act on
+    the skipped list. It exists at all because the alternative — deleting and
+    saying only *"Pruned orphans."* — is how this command destroyed files it
+    had never written without anyone noticing.
+    """
+
+    deleted: list[Path]
+    # Markdown under the docs root carrying none of this tool's frontmatter.
+    # Somebody else's files: not orphans, not deleted, and named every time
+    # because silence reads as "there was nothing else".
+    skipped: list[Path]
+    # Orphans this run could not remove — a read-only directory, a permission.
+    # Carried rather than raised, for the same reason `deleted` exists at all.
+    failed: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class VerifyReport:
+    """Result of a ``verify`` invocation."""
+
+    stale: list[str]
+    missing: list[str]
+    orphans: list[OrphanReport]
+    fresh: list[str]
+    conformance_issues: list[str] = field(default_factory=list)
+    # Problems inside a document's body that the tool can decide from facts it
+    # already holds — today, an architecture diagram naming a module the
+    # configuration does not have. Kept apart from `conformance_issues`, which
+    # are about a document's shape rather than its claims.
+    content_issues: list[str] = field(default_factory=list)
+    # Files no module covers and no exclusion names. Empty unless `verify` was
+    # asked for them: adopting the tool must not immediately fail a repository
+    # that has not finished mapping itself.
+    coverage_gaps: list[str] = field(default_factory=list)
+
+    @property
+    def exit_code(self) -> int:
+        """0 when clean, 1 on drift, a missing document, an orphan, or an issue."""
+        if (
+            self.stale
+            or self.missing
+            or self.orphans
+            or self.conformance_issues
+            or self.content_issues
+            or self.coverage_gaps
+        ):
+            return 1
+        return 0
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_prompt() -> str:
+    """Return the generation conventions text."""
+    return _PROMPT_PATH.read_text(encoding="utf-8")
+
+
+def _modules_for_paths(cfg: Config, changed_paths: list[str] | None) -> set[str]:
+    """Resolve changed paths to the module keys they affect.
+
+    When *changed_paths* is ``None``, every configured module is in scope.
+
+    Takes the loaded `Config`, not the path it came from. Taking the path
+    meant this reloaded and re-resolved a configuration its only caller was
+    already holding — a second full walk of the repository, for a function
+    that reads one attribute.
+    """
+    if changed_paths is None:
+        return set(cfg.module_files.keys())
+
+    changed_set = {Path(p).as_posix() for p in changed_paths}
+    affected: set[str] = set()
+    for mod_key, files in cfg.module_files.items():
+        if any(f.as_posix() in changed_set for f in files):
+            affected.add(mod_key)
+    return affected
+
+
+def _prompt_for(kind: Kind, repo_root: Path) -> str:
+    """Resolve a kind's prompt, reporting a missing file as configuration.
+
+    `docs/ERRORS.md` says a `KindError` reaches the caller wrapped as a
+    `ConfigError`. That was true only of the load-time wrap, and `load_kinds`
+    never touches the filesystem — so a kind naming a prompt file that is not
+    there loaded cleanly and then escaped from inside `plan`, past every
+    handler, as exit 1 with no JSON at all.
+    """
+    try:
+        return resolve_prompt(kind, repo_root)
+    except KindError as e:
+        raise ConfigError(str(e), key="kinds") from e
+
+
+def _kind_for(cfg: Any, module_key: str) -> tuple[Any, Kind]:
+    """Return the (module entry, kind) pair for *module_key*.
+
+    Raises `ValueError` when the module is not configured, and `ConfigError`
+    when it names a kind that is not — though the loader has already refused
+    that, so the second is a belt-and-braces case.
+    """
+    entry = next((m for m in cfg.modules if m.key == module_key), None)
+    if entry is None:
+        raise ValueError(f"Module {module_key!r} is not in the configuration")
+    kind = cfg.kinds.get(entry.kind)
+    if kind is None:
+        raise ConfigError(
+            f"Module {module_key!r} names kind {entry.kind!r}, which is not declared",
+            key="modules",
+        )
+    return entry, kind
+
+
+def _now_iso() -> str:
+    """Return an ISO-8601 timestamp string in UTC."""
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _today() -> str:
+    """Return today's date as ``YYYY-MM-DD``, which is what an OKF date is."""
+    return datetime.now(UTC).strftime("%Y-%m-%d")
+
+
+def _seed_tags(kind: Kind) -> list[str]:
+    """Return the one tag a fresh document starts with.
+
+    Derived from the kind's own `type`, lowercased and hyphenated, because
+    that is a fact the document already states rather than a taxonomy this
+    tool invented. A conformance checker wants `tags` present and non-empty;
+    a documentation set that wants real tags replaces this and keeps it, like
+    every other host key.
+    """
+    return ["-".join(kind.type.lower().split())]
+
+
+def _retirements(existing_doc: Any, retired_now: list[str]) -> dict[str, str]:
+    """Merge this write's retirements into whatever the document already had.
+
+    Retirements accumulate and are never dropped. The record is the point: a
+    decision that was deliberately retired reads, in the diff, as a deliberate
+    act — whereas an absence reads as nothing at all, which is exactly what a
+    silent loss looks like.
+
+    Dated, because *when* a decision was retired is the question anybody
+    reading the record will actually have.
+    """
+    previous: dict[str, str] = {}
+    if existing_doc is not None:
+        raw = extension_block(existing_doc.frontmatter).get("retired_decisions")
+        if isinstance(raw, dict):
+            previous = {str(k): str(v) for k, v in raw.items()}
+        elif isinstance(raw, list):
+            # Tolerated, never written: a hand-edited document may carry the
+            # bare list a reader would naturally reach for.
+            previous = {str(k): "" for k in raw}
+    today = _today()
+    for name in retired_now:
+        previous.setdefault(name, today)
+    return dict(sorted(previous.items()))
+
+
+def _title_for(module_key: str) -> str:
+    """Return a human-readable title seeded from a module key.
+
+    The last segment, separators turned into spaces. Capitalisation is added
+    only when the segment carries none of its own, so `api` becomes `Api` and
+    `SPEC` stays `SPEC`. This is a seed: the host owns `title` and whatever it
+    puts there survives every later write.
+    """
+    segment = module_key.rstrip("/").split("/")[-1]
+    words = segment.replace("_", " ").replace("-", " ").strip()
+    if not words:
+        return module_key
+    if words == words.lower():
+        return words[0].upper() + words[1:]
+    return words
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+# Re-exported for callers that inspect frontmatter; `document` owns the
+# definition, so there is exactly one spelling of it in the codebase.
+CONSTANT_DOCS_KEY = EXTENSION_KEY
+# Written at the top level before the producer-extension block existed. Dropped
+# on write so a document migrated from the old format does not carry both.
+# Safe to delete once no document predates the change.
+_LEGACY_TOP_LEVEL_KEYS = frozenset(
+    {
+        "module",
+        "source_glob",
+        "source_files",
+        "source_hash",
+        "hash_method",
+        "hash_covers",
+        "timestamp",
+        "generator",
+        "generator_spec",
+    }
+)
+
+
+GENERATOR_SPEC = "https://github.com/ashborn-systems/constant-docs/blob/main/SPEC.md"
+
+
+def _version() -> str:
+    """Resolved lazily: importing the package at module level would be circular.
+
+    Deferring to ``__version__`` rather than calling ``importlib.metadata``
+    again keeps one answer to "what version wrote this document", including
+    the fallback used by a checkout that was never installed.
+    """
+    from constant_docs import __version__
+
+    return __version__
+
+
+def _resolve_config(config_path: str | Path | None) -> Path:
+    """Return the config path, discovering it from the working directory.
+
+    The specification's public API calls `verify()` and `apply(module, body=...)`
+    with no config argument, so a harness running inside a repository does not
+    have to locate the file itself. An explicit path always wins.
+    """
+    if config_path is not None:
+        return Path(config_path)
+    here = Path.cwd().resolve()
+    for folder in [here, *here.parents]:
+        candidate = folder / "constant-docs.yaml"
+        if candidate.is_file():
+            return candidate
+    raise ConfigError(
+        "no constant-docs.yaml found in the working directory or any parent; "
+        "pass config_path explicitly",
+        # The same key the explicit-path miss carries. Without it the hook
+        # commands cannot tell "this is not a constant-docs repository" from
+        # "this repository's config is broken", and a globally installed Stop
+        # hook starts talking in every repository that does not use the tool.
+        key=MISSING_KEY,
+    )
+
+
+def plan(
+    config_path: str | Path | None = None,
+    changed_paths: list[str] | None = None,
+    modules: list[str] | None = None,
+) -> Plan:
+    """Inspect the repository and return the current state.
+
+    Returns a :class:`Plan` listing stale modules, orphans, fresh modules,
+    and the generation-prompt text.
+
+    *changed_paths* of ``None`` means consider every module. *modules* names
+    module keys directly, which is what `settle` has and saves it inventing a
+    path that resolves back to them.
+    """
+    resolved = _resolve_config(config_path)
+    return _plan(load_config(resolved), _repo_root(resolved), changed_paths, modules)
+
+
+def _plan(
+    cfg: Config,
+    repo_root: Path,
+    changed_paths: list[str] | None = None,
+    modules: list[str] | None = None,
+    cache: DocumentCache | None = None,
+) -> Plan:
+    """The body of :func:`plan`, over a configuration already loaded.
+
+    Split out so `verify` and `settle` — both of which have the `Config` in
+    hand — stop handing a path back to be read again. One `verify` used to load
+    the configuration three times and walk the repository three times with it.
+    """
+    cache = cache or DocumentCache()
+    if modules is not None:
+        modules_in_scope = {m for m in modules if m in cfg.module_files}
+    else:
+        modules_in_scope = _modules_for_paths(cfg, changed_paths)
+    stale: list[ModulePlan] = []
+    fresh: list[str] = []
+    unreadable: list[str] = []
+
+    # Sorted, not set-ordered. `stale` and `fresh` are built in this order and
+    # only two of the three lists were sorted downstream, so `verify --json`
+    # and `plan --json` came back with a different byte sequence on every
+    # process — `PYTHONHASHSEED` randomises string hashing — which is exactly
+    # what the reproducibility comment in `verify` claims not to happen.
+    for mod_key in sorted(modules_in_scope):
+        _, kind = _kind_for(cfg, mod_key)
+        files = cfg.module_files[mod_key]
+        try:
+            current_hash = compute_hash(files, root=repo_root)
+        except OSError as e:
+            # One module's problem, not the whole command's — which is what
+            # `orphans` already does with the same call. A file deleted between
+            # the walk and the hash, or one the walk listed and cannot read,
+            # used to abort `verify` before it printed any JSON at all.
+            unreadable.append(f"{mod_key} — source could not be read: {e}")
+            continue
+
+        doc_file = doc_path_for(cfg, mod_key)
+        doc_abs = repo_root / doc_file
+        previous_body: str | None = None
+        previous_description: str | None = None
+        reason: Literal["changed", "missing"] = "missing"
+
+        if doc_abs.exists():
+            try:
+                existing = cache.load(doc_abs)
+                stored_hash = str(
+                    extension_block(existing.frontmatter).get("source_hash", "")
+                )
+                previous_body = existing.body
+                previous_description = existing.frontmatter.get("description")
+                if stored_hash == current_hash:
+                    fresh.append(mod_key)
+                    continue
+                reason = "changed"
+            except (OSError, DocumentError):
+                # Malformed document → treat as missing
+                reason = "missing"
+
+        stale.append(
+            ModulePlan(
+                module=mod_key,
+                doc_path=doc_file,
+                files=files,
+                previous_body=previous_body,
+                previous_description=previous_description,
+                required_headings=list(kind.sections),
+                reason=reason,
+                kind=kind.name,
+                mode=kind.mode,
+                prompt=_prompt_for(kind, repo_root),
+            )
+        )
+
+    # Orphans
+    orphan_list = find_orphans(cfg, repo_root)
+
+    return Plan(
+        stale=stale,
+        orphans=orphan_list,
+        fresh=fresh,
+        prompt=_load_prompt(),
+        unreadable=unreadable,
+    )
+
+
+def _write(
+    module_key: str,
+    body: str,
+    *,
+    config_path: Path,
+    repo_root: Path,
+    cfg: Any,
+    module_entry: Any,
+    kind: Kind,
+    retire: Iterable[str] = (),
+) -> None:
+    """Assemble frontmatter for *body* and write the document.
+
+    Shared by `apply` and `append`, because the frontmatter a document carries
+    is a property of the module and its kind, not of how the body was produced.
+
+    Every refusal happens before anything is written, so a rejected body
+    leaves the document on disk exactly as it was.
+    """
+    if not has_required_headings(body, kind.sections):
+        raise DocumentError(
+            f"Body is missing one or more required headings for kind "
+            f"{kind.name!r}: " + ", ".join(kind.sections)
+        )
+
+    doc_file = doc_path_for(cfg, module_key)
+    doc_abs = repo_root / doc_file
+    # Read once, used three times: to compare decisions, to carry retirements
+    # forward, and to preserve host frontmatter. A malformed document reads as
+    # absent here, which is what the rest of the tool already does with one.
+    existing_doc = None
+    unparsed_text: str | None = None
+    if doc_abs.exists():
+        try:
+            existing_doc = load_document(doc_abs)
+        except (OSError, DocumentError, ValueError):
+            existing_doc = None
+            # Kept, because a document that does not parse still has text and
+            # that text can record decisions. See the guard below.
+            try:
+                unparsed_text = doc_abs.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                unparsed_text = None
+
+    # A regeneration is free to rewrite every decision this document records
+    # and unable to drop one without saying so. Checked here rather than in
+    # `apply`, because this is the single point every write passes through —
+    # the same reason there is one digest and one glob matcher.
+    #
+    # An append cannot fail this: its body is the previous one plus a suffix,
+    # so nothing can go missing. That is a property worth having rather than a
+    # special case worth writing.
+    retired_now: list[str] = []
+    if existing_doc is not None:
+        retired_now = check_rewrite(existing_doc.body, body, retire)
+    elif unparsed_text is not None:
+        # A document that will not parse is still checked for what it records.
+        # Treating it as absent turned the guard off entirely, so a single
+        # stray leading newline — or a merge marker — was enough to drop every
+        # decision in the file without a word. A marker is an HTML comment in
+        # the body and frontmatter carries none, so reading the whole file as
+        # the previous body sees exactly the decisions that are there.
+        #
+        # The document is still regenerated from scratch afterwards, which is
+        # what the rest of the tool does with one it cannot read. What is no
+        # longer allowed is losing a decision on the way.
+        retired_now = check_rewrite(unparsed_text, body, retire)
+    elif list(retire):
+        raise DecisionLoss(
+            f"A retirement was declared for {module_key!r}, which has no "
+            f"document yet. There is nothing recorded to retire.",
+            sorted({r.strip().lower() for r in retire if r.strip()}),
+        )
+
+    # The one kind whose content is checked rather than only hashed. Refused
+    # here as well as reported by `verify`, so a diagram naming a module that
+    # does not exist is caught when it is written rather than a release later.
+    if kind.check == ARCHITECTURE_CHECK:
+        problems = check_architecture_body(body, [m.key for m in cfg.modules])
+        if problems:
+            raise DiagramError(
+                f"The architecture body for {module_key!r} was refused:\n"
+                + "\n".join(f"  {p}" for p in problems)
+            )
+    elif kind.check == ERRORS_CHECK:
+        problems = check_catalogue(body, _sources_for(cfg, repo_root, module_key))
+        if problems:
+            raise CatalogueError(
+                f"The error catalogue for {module_key!r} was refused:\n"
+                + "\n".join(f"  {p}" for p in problems)
+            )
+
+    files = cfg.module_files[module_key]
+    try:
+        current_hash = compute_hash(files, root=repo_root)
+    except OSError as e:
+        raise DocumentError(
+            f"Cannot hash the sources for {module_key!r}: {e}. Nothing was "
+            f"written: a document whose hash is unknown would report stale on "
+            f"the next run whatever it holds."
+        ) from e
+
+    # Everything this tool owns lives under one key, which is what the Open
+    # Knowledge Format calls a producer extension: consumers tolerate unknown
+    # keys, so a namespaced block cannot collide with a host schema. The tool
+    # writes CONSTANT_DOCS_KEY and nothing else — `type`, `title`, `tags` and
+    # dates belong to whoever owns the documentation set, not to us.
+    #
+    # Assembled first so a retirement can sit next to
+    # `kind` — what the document *is* — rather than after the generator, where
+    # a reader scanning a diff would miss it.
+    block: dict[str, Any] = {"module": module_key, "kind": kind.name}
+    # Retirements accumulate and are never dropped: the record is the whole
+    # point, and a retirement that left no trace would look exactly like the
+    # silent drop this guard exists to catch. A document that has retired
+    # nothing carries no such key, so the mechanism costs an ordinary document
+    # not one byte.
+    retired = _retirements(existing_doc, retired_now)
+    if retired:
+        block["retired_decisions"] = retired
+    block.update(
+        {
+            "source_glob": module_entry.globs[0]
+            if len(module_entry.globs) == 1
+            else module_entry.globs,
+            # Only when there is something to say. A document is read on
+            # its own, so the boundary rule has to be legible from the
+            # frontmatter alone — and "whatever `api` covers" is half of
+            # that rule when a document declares it.
+            **({"covers": list(module_entry.covers)} if module_entry.covers else {}),
+            "source_files": [f.as_posix() for f in sorted(files)],
+            "source_hash": current_hash,
+            "hash_method": "sha256-over-sorted-path-and-content",
+            "hash_covers": "source_files",
+            "timestamp": _now_iso(),
+            "generator": f"constant-docs/{_version()}",
+            "generator_spec": GENERATOR_SPEC,
+        }
+    )
+
+    # `type` is the only key the Open Knowledge Format requires; `title`,
+    # `description` and `tags` are recommended, and dated keys are what a real
+    # consumer checks for. All six are seeded here and none is ever
+    # overwritten: they belong to whoever owns the documentation set, and
+    # seeding is what makes the docs tree an OKF bundle rather than merely
+    # OKF-shaped. The tool's own "when did this body last change" lives on
+    # `timestamp` inside its block, so nothing here needs to move on a write.
+    fm: dict[str, Any] = {
+        "type": kind.type,
+        "title": _title_for(module_key),
+        # Criterion 31, generalised: the first sentence of the kind's opening
+        # section. A kind whose opening section holds headings rather than
+        # prose — a log's `# Entries` — yields nothing, and the existing
+        # description is kept below.
+        "description": extract_description(body, kind.sections[0]) or module_key,
+        "tags": _seed_tags(kind),
+        "created": _today(),
+        "updated": _today(),
+        CONSTANT_DOCS_KEY: block,
+    }
+
+    # Preserve every existing key the tool does not own. `type` and
+    # `description` are seeded above for a fresh document, then deferred to
+    # the host's values if the document already carries them.
+    if existing_doc is not None:
+        for k, v in existing_doc.frontmatter.items():
+            if (
+                k != CONSTANT_DOCS_KEY
+                and k not in LEGACY_EXTENSION_KEYS
+                and k not in _LEGACY_TOP_LEVEL_KEYS
+            ):
+                fm[k] = v
+
+    doc = Document(
+        frontmatter=fm,
+        body=body,
+        sections=list(kind.sections),
+        # From the kind, not from whatever the file happened to carry. A
+        # document is written in the form its kind declares, so changing the
+        # declaration converts every document of that kind on the next write
+        # rather than leaving the estate in two forms with nothing saying
+        # which is current.
+        frontmatter_style=kind.frontmatter,
+    )
+    doc.save(doc_abs)
+
+    # The write that satisfies a module is what clears it from the dirty set:
+    # precise, per module, and needing no cooperation from the caller. A
+    # partial generation clears only what it actually wrote.
+    state.discard(repo_root, module_key)
+
+
+def apply(
+    module_key: str,
+    body: str,
+    config_path: str | Path | None = None,
+    retire: Iterable[str] = (),
+) -> None:
+    """Write *body* as the whole document body for *module_key*.
+
+    The body must carry every heading the module's kind requires; it is
+    checked before anything is written, so a rejected body leaves an existing
+    document untouched. Frontmatter is updated with the current source hash,
+    file list, and timestamp.
+
+    *retire* names decision identifiers this rewrite deliberately removes.
+    Without it, a body that drops a decision the previous one recorded is
+    refused: a rewrite is free to reword every decision and unable to drop one
+    silently. Declaring a retirement that did not happen is refused too, so
+    the parameter cannot become a way to switch the check off.
+
+    Refused for a module whose kind appends. Overloading one call to mean both
+    "replace this" and "add to this" is how a log gets silently destroyed by a
+    caller that passed the wrong shape.
+    """
+    config_path = _resolve_config(config_path)
+    repo_root = _repo_root(config_path)
+    cfg = load_config(config_path)
+    module_entry, kind = _kind_for(cfg, module_key)
+
+    if kind.mode == "append":
+        raise ValueError(
+            f"Module {module_key!r} is of kind {kind.name!r}, which appends. "
+            f"Use append() to add an entry; apply() would replace everything "
+            f"already written."
+        )
+
+    _write(
+        module_key,
+        body,
+        config_path=config_path,
+        repo_root=repo_root,
+        cfg=cfg,
+        module_entry=module_entry,
+        kind=kind,
+        retire=retire,
+    )
+
+
+def append(
+    module_key: str,
+    entry: str,
+    title: str,
+    config_path: str | Path | None = None,
+) -> None:
+    """Add one entry to the document for *module_key*.
+
+    The entry goes under the kind's first section as an H3 whose text is
+    Everything already in the document is left exactly as it is: an
+    append that can modify history is a replace with extra steps.
+
+    The hash still moves on write, so "has anything changed since the last
+    entry" is the same comparison as everywhere else in the tool. That is why
+    a log can be stale at all, given its body is not a function of the source.
+
+    Refused for a module whose kind replaces.
+    """
+    config_path = _resolve_config(config_path)
+    repo_root = _repo_root(config_path)
+    cfg = load_config(config_path)
+    module_entry, kind = _kind_for(cfg, module_key)
+
+    if kind.mode != "append":
+        raise ValueError(
+            f"Module {module_key!r} is of kind {kind.name!r}, which replaces. "
+            f"Use apply() with the whole body."
+        )
+
+    title = title.strip()
+    if not title:
+        raise ValueError("An entry needs a title; it becomes the entry's H2 heading.")
+
+    doc_abs = repo_root / doc_path_for(cfg, module_key)
+    previous = ""
+    if doc_abs.exists():
+        try:
+            previous = load_document(doc_abs).body
+        except (OSError, DocumentError):
+            # A document that cannot be parsed must not be silently discarded
+            # by an append — that is the one write mode where the old text is
+            # the whole point.
+            raise DocumentError(
+                f"Cannot append to {doc_abs}: it exists but does not parse. "
+                f"Fix or remove it; appending would lose what it holds."
+            ) from None
+
+    body = _extend(previous, kind.sections, title, entry)
+
+    _write(
+        module_key,
+        body,
+        config_path=config_path,
+        repo_root=repo_root,
+        cfg=cfg,
+        module_entry=module_entry,
+        kind=kind,
+    )
+
+
+def _section_end(body: str, heading: str) -> int | None:
+    """Return the line index just past the end of *heading*'s section.
+
+    None when the heading is not in *body*, which leaves the caller appending
+    at the end — the honest answer for a body that does not carry the section
+    its kind declares. Fenced blocks are tracked, because a log full of code
+    samples has `## ` inside them and a heading inside a fence is an example.
+    """
+    if not heading:
+        return None
+    wanted = heading.strip()
+    lines = body.split("\n")
+    fenced = False
+    start: int | None = None
+    for i, line in enumerate(lines):
+        # Both CommonMark fence characters. `~~~` is the usual escape when the
+        # sample itself contains backticks, which a documentation tool's own
+        # log is full of — and splicing an entry into the middle of one would
+        # lose the block rather than merely misplace the entry.
+        if line.lstrip().startswith(("```", "~~~")):
+            fenced = not fenced
+            continue
+        if fenced:
+            continue
+        if start is None:
+            if line.strip() == wanted:
+                start = i
+            continue
+        if line.startswith("## "):
+            end = i
+            # Blank lines before the next heading belong to the gap, so the
+            # entry lands under this section rather than adrift above the one
+            # that follows.
+            while end > start + 1 and not lines[end - 1].strip():
+                end -= 1
+            return end
+    return None if start is None else len(lines)
+
+
+def _extend(previous: str, sections: list[str], title: str, entry: str) -> str:
+    """Return *previous* with one entry added to the end of its first section.
+
+    Every byte of *previous* survives in order, which is what makes "the first
+    entry is byte-identical after the second append" testable rather than a
+    matter of trust.
+    """
+    scaffold = previous.rstrip("\n")
+    if not scaffold:
+        # A new log still has to satisfy its kind's required headings.
+        scaffold = "\n\n".join(sections)
+    # An entry sits inside a section, and sections are H2, so an entry is H3.
+    block = f"### {title}\n\n{entry.strip()}\n"
+
+    # At the end of the kind's *first section*, not at the end of the body.
+    # For a single-section kind those are the same place, which is how
+    # appending to the end went unnoticed: give a log a second section and
+    # every entry filed itself under the last heading instead, leaving the
+    # first permanently empty and `extract_description` with nothing to find.
+    end = _section_end(scaffold, sections[0] if sections else "")
+    if end is None:
+        return f"{scaffold}\n\n{block}"
+    lines = scaffold.split("\n")
+    head = "\n".join(lines[:end]).rstrip("\n")
+    tail = "\n".join(lines[end:]).strip("\n")
+    if not tail:
+        return f"{head}\n\n{block}"
+    return f"{head}\n\n{block}\n{tail}\n"
+
+
+def verify(
+    config_path: str | Path | None = None, coverage: bool = False
+) -> VerifyReport:
+    """Run ``plan`` on every module and return a drift report.
+
+    *coverage* folds uncovered source into the gate. Opt-in, because adopting
+    the tool on a repository that has not finished mapping itself would
+    otherwise fail on the first run — and a check that fails from the moment
+    it is installed is one somebody switches off.
+    """
+    resolved = _resolve_config(config_path)
+    root = _repo_root(resolved)
+    # Loaded once, and every document parsed once. `plan` used to be handed the
+    # path and load it again, `_modules_for_paths` a third time, and each of the
+    # scanners below re-read documents `plan` had already read — three walks of
+    # the repository and two parses of every document, per `verify`.
+    cfg = load_config(resolved)
+    cache = DocumentCache()
+    p = _plan(cfg, root, cache=cache)
+    # Sorted so two runs over the same repository produce byte-identical
+    # output. `_plan` iterates its module set in sorted order for the same
+    # reason: sorting two of the three lists here left `fresh` in string-hash
+    # order, which `PYTHONHASHSEED` randomises per process.
+    stale_names = sorted(m.module for m in p.stale if m.reason == "changed")
+    missing_names = sorted(m.module for m in p.stale if m.reason == "missing")
+
+    # AC 25 — conformance check on all docs under docs_root
+    conformance_issues = conformance_check(cfg, root, cache=cache)
+
+    return VerifyReport(
+        stale=stale_names,
+        missing=missing_names,
+        orphans=p.orphans,
+        fresh=p.fresh,
+        conformance_issues=conformance_issues,
+        content_issues=(
+            check_architecture(cfg, root, cache=cache)
+            + check_errors(cfg, root, cache=cache)
+            + sorted(p.unreadable)
+        ),
+        coverage_gaps=_coverage_gaps(cfg, root) if coverage else [],
+    )
+
+
+def _coverage_gaps(cfg: Any, repo_root: Path) -> list[str]:
+    """Return one line per directory holding uncovered source.
+
+    By directory rather than by file: a gate that printed four hundred paths is
+    a gate nobody reads, and the decision a reader has to make is about
+    directories anyway.
+    """
+    from constant_docs.coverage import by_directory, uncovered_files
+
+    grouped = by_directory(uncovered_files(cfg, repo_root))
+    return [
+        f"{directory} — {len(files)} file{'' if len(files) == 1 else 's'} "
+        f"covered by no module"
+        for directory, files in grouped.items()
+    ]
+
+
+def settle(config_path: str | Path | None = None) -> Plan:
+    """Plan over the dirty set, without clearing it.
+
+    Called at quiescence — the end of a turn — so the generator and the coding
+    loop never write the same file at once.
+
+    **The set is not cleared by being read.** If it cleared on emit and the
+    caller then failed to generate, the staleness would be lost and nothing
+    would ever notice again. A module is dropped here only when the plan finds
+    it *fresh*, which means the file was edited and edited back: dirty by the
+    mark, clean by the hash, and provably no work.
+    """
+    resolved = _resolve_config(config_path)
+    repo_root = _repo_root(resolved)
+    dirty = state.read(repo_root)
+    if not dirty.modules:
+        return Plan(stale=[], orphans=[], fresh=[], prompt=_load_prompt())
+
+    cfg = load_config(resolved)
+    # A module deleted from the configuration since it was marked is not work;
+    # it is a configuration change, and `verify` reports its document as an
+    # orphan.
+    known = [m for m in dirty.modules if m in cfg.module_files]
+    p = _plan(cfg, _repo_root(resolved), changed_paths=None, modules=known)
+
+    if p.fresh:
+        remaining = [m for m in dirty.modules if m not in set(p.fresh)]
+        if remaining != dirty.modules:
+            dirty.modules = remaining
+            state.write(repo_root, dirty)
+
+    return p
+
+
+def prune(config_path: str | Path | None = None) -> PruneReport:
+    """Delete orphaned documents and the empty directories they leave.
+
+    **Only documents this tool wrote.** A markdown file under the docs root
+    carrying none of our frontmatter is somebody else's — a decision record, a
+    hand-off note, whatever was in the `docs/` folder before the tool arrived —
+    and it is returned in ``skipped`` rather than deleted. Having a `docs/`
+    folder already is the normal way people adopt a documentation tool, and
+    pointing it at that folder is the first thing they do.
+    """
+    config_path = _resolve_config(config_path)
+    repo_root = _repo_root(config_path)
+    cfg = load_config(config_path)
+    orphan_list = find_orphans(cfg, repo_root)
+    # Assembled before the deletions, not in the return statement after them.
+    # Building it afterwards meant a failure while scanning — one non-UTF-8
+    # file under the docs root was enough — landed with the orphans already
+    # unlinked and no report of which ones.
+    skipped = find_foreign(cfg, repo_root)
+    docs_root_abs = repo_root / cfg.docs_root
+
+    deleted: list[Path] = []
+    deleted_dirs: set[Path] = set()
+    failed: list[str] = []
+    for orphan in orphan_list:
+        # `OrphanReport.doc_path` is repository-relative, so the absolute one
+        # is built here, where a file is actually opened, and goes no further.
+        doc_abs = repo_root / orphan.doc_path
+        if doc_abs.exists():
+            try:
+                doc_abs.unlink()
+            except OSError as e:
+                # One file that will not go is not a reason to lose the record
+                # of the ones that did. Reported beside them rather than raised.
+                failed.append(f"{orphan.doc_path} — {e}")
+                continue
+            deleted.append(orphan.doc_path)
+            # Track the parent directory for cleanup
+            parent = doc_abs.parent
+            while parent != docs_root_abs and parent != parent.parent:
+                deleted_dirs.add(parent)
+                parent = parent.parent
+
+    # Remove empty directories (bottom-up). A directory still holding a file
+    # this tool did not write is not empty, so nothing here can take one.
+    for d in sorted(deleted_dirs, key=lambda p: len(p.parts), reverse=True):
+        try:
+            if d.exists() and not any(d.iterdir()):
+                d.rmdir()
+        except OSError:
+            pass
+
+    return PruneReport(deleted=deleted, skipped=skipped, failed=failed)