constant-docs 0.4.0__py3-none-any.whl

constant_docs/config.py

@@ -0,0 +1,1158 @@
+"""Configuration loading for constant-docs.
+
+Loads, validates, and resolves ``constant-docs.yaml`` into a typed Config
+object.  All env/glob/validation logic is here; callers work with the
+returned dataclass and never re-parse the file.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from contextlib import suppress
+from dataclasses import dataclass, field
+from fnmatch import fnmatch
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+import yaml
+
+from constant_docs.globs import GlobError
+from constant_docs.globs import matches as glob_matches
+from constant_docs.kinds import (
+    BUILTIN_KINDS,
+    DEFAULT_KIND,
+    Kind,
+    KindError,
+    load_kinds,
+)
+
+# The `key` a ConfigError carries when the file itself does not parse. The
+# commands that stay silent outside a configured repository test for it: a
+# missing configuration is somebody else's repository, a broken one is this
+# repository with a typo in it, and treating the second as the first turns a
+# gate off while reporting that everything is fine.
+SYNTAX_KEY = "(syntax)"
+
+# The `key` for "there is no configuration here at all". The hook commands
+# are silent for this one and only this one: a globally installed hook fires
+# in every repository, including those that do not use the tool.
+MISSING_KEY = "(file)"
+
+
+class ConfigError(Exception):
+    """The configuration file is invalid.
+
+    ``key`` names the offending top-level key, so callers (especially the
+    CLI) can format a precise error message.
+    """
+
+    def __init__(self, message: str, key: str | None = None) -> None:
+        super().__init__(message)
+        self.key = key
+
+
+@dataclass(frozen=True)
+class ModuleEntry:
+    """One configured module."""
+
+    key: str  # e.g. "src/payments" — also the document path stem
+    globs: list[str]  # one or more glob expressions; may be empty when covering
+    kind: str = DEFAULT_KIND  # names an entry in Config.kinds
+    # Other module keys whose files this one also takes in, transitively.
+    #
+    # A cross-cutting document could always restate another module's glob. What
+    # it could not do is name the module, so two places had to agree with
+    # nothing keeping them in step. `covers` makes the dependency a reference:
+    # the covering document follows when the covered module's glob moves.
+    covers: list[str] = field(default_factory=list, hash=False, compare=False)
+    # Where this module's document is written, when it does not belong under
+    # the docs root.
+    #
+    # The key is the document's path stem for every ordinary module, which
+    # makes the docs root a bundle and publishing a copy. Some documents are
+    # fixed at the repository root by convention that predates any of this —
+    # `README.md`, `CONTRIBUTING.md` — and a tool that cannot write them
+    # leaves the most-read file in the repository outside the mechanism.
+    document: str | None = None
+
+
+@dataclass(frozen=True)
+class AutoSettings:
+    """What `constant-docs auto` runs, and how much it asks for at a time."""
+
+    command: str
+    # Named `when` rather than `on`, because `on` is a YAML 1.1 boolean and a
+    # block written with it parses to `{True: "stale"}` — a key nothing looks
+    # for, in a file that plainly reads `on: stale`.
+    when: str = "stale"  # "stale" or "always"
+    budget: int | None = None  # modules per run; None means no cap
+    timeout: float | None = None  # seconds; None means wait indefinitely
+
+
+@dataclass(frozen=True)
+class Config:
+    """Validated and resolved configuration."""
+
+    version: int
+    docs_root: Path
+    modules: list[ModuleEntry]
+    index_token_budget: int | None
+
+    # Resolved mapping: module_key -> sorted list of repository-relative Paths
+    module_files: dict[str, list[Path]] = field(hash=False, compare=False)
+
+    # Every kind available to this configuration: the shipped ones, plus
+    # anything the `kinds` block declared or overrode.
+    kinds: dict[str, Kind] = field(
+        hash=False, compare=False, default_factory=lambda: dict(BUILTIN_KINDS)
+    )
+
+    # Glob pattern to the reason it is deliberately undocumented. Declared
+    # rather than inferred: an exclusion nobody justified is one nobody
+    # decided, and it outlives whatever made it sensible.
+    uncovered: dict[str, str] = field(hash=False, compare=False, default_factory=dict)
+
+    # What `auto` runs, when the repository declares it. `None` means the
+    # repository has not opted into unattended regeneration, which is the
+    # default: this is the only thing here that executes anything.
+    auto: AutoSettings | None = field(hash=False, compare=False, default=None)
+
+
+# Refused before any glob resolves, always, whatever the configuration says.
+# This tool hands source files to a model to be described in prose, so a file
+# swept up by a careless glob is not merely hashed — its contents reach a
+# generator and can end up written into a committed document. A deny list in
+# the tool beats one in the config of whoever remembers.
+# Directory names that are refused wherever they appear in a path.
+#
+# Two groups, for two reasons. `Secret`, `.ssh` and `.git` hold material that
+# must never reach a generator. The rest is derived output: a cache is built
+# from source this tool already hashes, so covering it counts the same
+# information twice and makes a test run look like a source change. That is
+# the same argument that excludes the docs root, and it matters because a
+# catch-all glob is exactly what an append-mode document wants.
+#
+# A closed list, not a rule about dotted names: `.github` and `.githooks` are
+# source a build log may well want to cover.
+DENIED_DIRS = frozenset(
+    {
+        "Secret",
+        ".ssh",
+        ".git",
+        "__pycache__",
+        ".venv",
+        "node_modules",
+        ".mypy_cache",
+        ".ruff_cache",
+        ".pytest_cache",
+        ".tox",
+        ".nox",
+        ".ipynb_checkpoints",
+        # This tool's own state directory — the same string as
+        # `state.STATE_DIR`, restated because `state` imports this module and
+        # the dependency cannot run the other way. Excluded because it is
+        # derived output: hashing it means a catch-all glob such as `**/*`
+        # never converges, since writing a document rewrites the dirty set,
+        # which marks the document stale again on the very next run.
+        ".constant-docs",
+    }
+)
+
+# Filename patterns that are refused wherever they appear.
+DENIED_NAMES = (
+    ".env",
+    ".env.*",
+    "*.env",
+    "id_rsa*",
+    "id_ed25519*",
+    "*.pem",
+    "*.key",
+    "credentials",
+    "credentials.*",
+)
+
+
+def _is_denied(rel: Path) -> bool:
+    """True when a resolved file must never be read.
+
+    This tool hands source files to a model to be described in prose, so a
+    file swept up by a careless glob is not merely hashed — its contents reach
+    a generator and can end up written into a committed document. The refusal
+    lives in the tool rather than in the config of whoever remembers.
+
+    Matching is on path parts and filename rather than a recursive glob,
+    because `Path.full_match` is Python 3.13 and this supports 3.11.
+    """
+    if DENIED_DIRS.intersection(rel.parts[:-1]):
+        return True
+    return any(fnmatch(rel.name, pat) for pat in DENIED_NAMES)
+
+
+def _is_denied_target(path: Path) -> bool:
+    """True when *path* is a symlink the deny list refuses on its target.
+
+    The deny list matches a name and the directories above it, and a symlink
+    has a name of its own: `src/helper.py` pointing at `~/.ssh/id_rsa` is
+    refused by neither `DENIED_NAMES` nor `DENIED_DIRS` while still handing a
+    private key to a generator to read and describe. What gets read is the
+    target, so that is what is judged. A link that cannot be resolved is
+    refused, which is the same safe direction taken everywhere else here.
+    """
+    try:
+        if not path.is_symlink():
+            return False
+        target = path.resolve()
+        # `resolve()` is non-strict, so a broken link resolves happily to a
+        # path that is not there. Tested separately, because a link with no
+        # target is not source: hashing it dies in `fingerprint.compute`'s
+        # `read_bytes`, taking the whole command with it.
+        if not target.exists():
+            return True
+    except OSError:
+        return True
+    return bool(DENIED_DIRS.intersection(target.parts[:-1])) or any(
+        fnmatch(target.name, pat) for pat in DENIED_NAMES
+    )
+
+
+# Files under the docs root this tool owns but does not track as documents.
+# `index.md` is assembled by `constant-docs index` and carries no frontmatter
+# by design, so `is_ours` cannot speak for it. Named once rather than compared
+# as a literal in each scanner: two of those comparisons are the last check
+# before a delete and before a refused write, and the next such file — the
+# test suite already names `log.md` — must not depend on somebody finding
+# every site.
+TOOL_OWNED_DOCS: tuple[str, ...] = ("index.md",)
+
+
+def is_tool_owned(doc: Path, docs_root: Path) -> bool:
+    """True when *doc* is a file this tool owns but does not track."""
+    try:
+        rel = doc.relative_to(docs_root).as_posix()
+    except ValueError:
+        return False
+    return rel in TOOL_OWNED_DOCS
+
+
+def repo_root(config_path: str | Path) -> Path:
+    """Return the repository root for a configuration file.
+
+    One spelling, because there were three — `config_path.parent`,
+    `resolved.parent` and `config_path.resolve().parent` — and only the
+    resolving one normalises `.` and follows a symlinked checkout. They
+    agree under a fixed working directory, so this is not a bug fix; it is
+    so the next site is not a coin flip, and so `Path('.')` stops turning up
+    as a repository root in `relative_to` calls and error messages.
+    """
+    return Path(config_path).resolve().parent
+
+
+def validate_module_key(module_key: str) -> None:
+    """Refuse a module key whose document would land outside the docs root.
+
+    ``Path.__truediv__`` discards its left operand when the right is absolute,
+    so a key of ``/etc/x`` drops the docs root entirely, and ``..`` walks out
+    of it. Either one writes a document — and creates the directories to hold
+    it, because `Document.save` makes parents — anywhere the invoking user can
+    write, while reporting an ordinary success. A key is a path stem inside
+    the docs root, and that is the whole of what it is allowed to be.
+    """
+    key = str(module_key).strip()
+    if not key:
+        raise ConfigError("A module key cannot be empty.", key="modules")
+    candidate = Path(key)
+    # `Path(".").parts` is empty, so a key of `.` or `./` reaches
+    # `document_path` as nothing at all and `(docs_root / ".").with_suffix()`
+    # yields `docs.md` — a sibling of the docs root rather than a file inside
+    # it, outside every scan and outside the walk exclusion. Refused with the
+    # rest, because it is the same escape by a quieter route.
+    if (
+        candidate.is_absolute()
+        or key.startswith(("/", "\\"))
+        or ".." in candidate.parts
+        or not candidate.parts
+    ):
+        raise ConfigError(
+            f"Module key {key!r} must be a relative path inside the docs "
+            f"root. A key is the document's path stem, so an absolute key or "
+            f"one containing '..' writes outside the documentation folder — "
+            f"and outside the repository.",
+            key="modules",
+        )
+
+
+def validate_document_path(module_key: str, value: str) -> str:
+    """Return *value* normalised, or raise if it cannot name a document.
+
+    Refused rather than clamped. A path that escapes the repository, or one
+    the tool would not recognise as a document when it reads the tree back,
+    is a configuration mistake and silently rewriting it hides the mistake
+    until somebody wonders where their file went.
+    """
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError(
+            f"Module {module_key!r} declares an empty 'document'. Give it a "
+            f"repository-relative path such as `document: README.md`, or "
+            f"remove the key to write under the docs root.",
+            key="modules",
+        )
+    raw = value.strip()
+    path = PurePosixPath(raw.replace("\\", "/"))
+    if path.is_absolute() or raw.startswith("/") or ":" in path.parts[0]:
+        raise ConfigError(
+            f"Module {module_key!r} declares 'document: {raw}', which is an "
+            f"absolute path. Documents are named relative to the repository "
+            f"root, so that a checkout anywhere resolves the same.",
+            key="modules",
+        )
+    if ".." in path.parts:
+        raise ConfigError(
+            f"Module {module_key!r} declares 'document: {raw}', which climbs "
+            f"out of the repository. A document the tool writes outside the "
+            f"checkout is one no clone of this repository would carry.",
+            key="modules",
+        )
+    if path.suffix != ".md":
+        raise ConfigError(
+            f"Module {module_key!r} declares 'document: {raw}', which is not "
+            f"a Markdown file. Every document this tool writes carries "
+            f"frontmatter and a Markdown body; the suffix is how a reader and "
+            f"`prune` both tell one from a source file.",
+            key="modules",
+        )
+    return path.as_posix()
+
+
+def document_path(
+    module_key: str, docs_root: Path, document: str | None = None
+) -> Path:
+    """Return the document path for a module key.
+
+    Defined here rather than in `paths`, which imports this module, so that the
+    load-time collision check and the runtime mapping cannot drift apart.
+    `paths.doc_path` is the public spelling and delegates to this.
+
+    *document* overrides the mapping entirely, and is already validated by the
+    loader. It is repository-relative rather than docs-root-relative, because
+    the reason to reach for it is that the document does not belong under the
+    docs root at all.
+    """
+    if document is not None:
+        return Path(document)
+    return (docs_root / module_key).with_suffix(".md")
+
+
+def _detect_document_collisions(
+    modules: list[ModuleEntry], docs_root: Path
+) -> list[tuple[str, str, Path]]:
+    """Return (key_a, key_b, path) for module keys sharing a document path.
+
+    `doc_path` appends `.md`, so `SPEC` and `SPEC.md` both resolve to
+    `<docs_root>/SPEC.md`. Whichever is written last wins and the loser reports
+    permanently stale, because the document on disk carries the other's hash.
+
+    A declared `document` is compared here too, and against the same set: it
+    can collide with another declaration, with an ordinary module's derived
+    path, or with the generated index, and all three fail the same way.
+    """
+    # Seeded with the tool's own index, which is written by `constant-docs
+    # index` and is not a module document. A module keyed `index` resolves to
+    # the same file, so the two writers clobbered each other on every run
+    # while `verify` reported it permanently missing — and every scan that
+    # could have named the file skips `index.md` by design.
+    seen: dict[Path, str] = {
+        docs_root / owned: "the generated index" for owned in TOOL_OWNED_DOCS
+    }
+    conflicts: list[tuple[str, str, Path]] = []
+    for mod in modules:
+        target = document_path(mod.key, docs_root, mod.document)
+        previous = seen.get(target)
+        if previous is not None:
+            conflicts.append((previous, mod.key, target))
+        else:
+            seen[target] = mod.key
+    return conflicts
+
+
+def _as_name_list(mod_key: str, raw: Any) -> list[str]:
+    """Return `covers` as a list of module keys, accepting a bare string."""
+    if isinstance(raw, str):
+        return [raw]
+    if isinstance(raw, list) and all(isinstance(name, str) for name in raw):
+        return list(raw)
+    raise ConfigError(
+        f"'covers' for module {mod_key!r} must be a module key or a list of "
+        f"module keys, got {type(raw).__name__}",
+        key="modules",
+    )
+
+
+def _validate_covers(modules: list[ModuleEntry]) -> None:
+    """Refuse a `covers` naming nothing, and refuse a cycle, naming both.
+
+    Structural rather than resolved, so it runs in `declarations` and `mark`
+    gets the same guarantee the loader does.
+
+    Silence on an unknown name would reproduce the bug `covers` exists to fix:
+    a document that meant *"whatever `api` covers"* and quietly covered nothing
+    would hash an empty file set, report as an orphan, and never go stale
+    again.
+    """
+    known = {m.key for m in modules}
+    by_key = {m.key: m for m in modules}
+
+    for mod in modules:
+        unknown = [name for name in mod.covers if name not in known]
+        if unknown:
+            raise ConfigError(
+                f"Module {mod.key!r} covers {', '.join(repr(u) for u in unknown)}, "
+                f"which {'is' if len(unknown) == 1 else 'are'} not declared. "
+                f"Available: {', '.join(sorted(known))}",
+                key="modules",
+            )
+
+    # Depth-first, carrying the path so the cycle can be named rather than
+    # merely detected. A recursion guard that reported "a cycle exists"
+    # leaves the reader to find it in a file with forty modules in it.
+    settled: set[str] = set()
+    stack: list[str] = []
+    on_stack: set[str] = set()
+
+    def walk(key: str) -> None:
+        if key in settled:
+            return
+        if key in on_stack:
+            cycle = [*stack[stack.index(key) :], key]
+            raise ConfigError(
+                "A module cannot cover itself, directly or through others: "
+                + " covers ".join(repr(k) for k in cycle),
+                key="modules",
+            )
+        stack.append(key)
+        on_stack.add(key)
+        for name in by_key[key].covers:
+            walk(name)
+        stack.pop()
+        on_stack.discard(key)
+        settled.add(key)
+
+    for mod in modules:
+        walk(mod.key)
+
+
+def effective_globs(modules: list[ModuleEntry]) -> dict[str, list[str]]:
+    """Return each module's own globs plus those of everything it covers.
+
+    One definition, used by glob resolution and by `mark`, for the reason
+    there is one digest and one matcher: two answers to "which files belong to
+    this module" that agree today will disagree eventually, and the symptom
+    would be a hook marking the wrong document dirty while `verify` insists the
+    right one is fine.
+
+    Unioning *patterns* rather than resolved files is what keeps `mark` pure
+    string work. The file set is identical either way, because resolution is
+    per-file matching against patterns.
+
+    Call only after :func:`_validate_covers`; a cycle here would not terminate.
+    """
+    by_key = {m.key: m for m in modules}
+    resolved: dict[str, list[str]] = {}
+
+    def gather(key: str) -> list[str]:
+        if key in resolved:
+            return resolved[key]
+        entry = by_key[key]
+        out = list(entry.globs)
+        for name in entry.covers:
+            for pattern in gather(name):
+                if pattern not in out:
+                    out.append(pattern)
+        resolved[key] = out
+        return out
+
+    return {m.key: gather(m.key) for m in modules}
+
+
+def _under(rel: Path, folder: Path) -> bool:
+    """True when *rel* lies inside *folder*, both repository-relative."""
+    return rel.parts[: len(folder.parts)] == folder.parts
+
+
+# A read-only `git` call has no business hanging, and a walk that never
+# returns is worse than one that ignores nothing.
+_GIT_TIMEOUT = 10.0
+
+
+def _git_ignored(abs_root: Path, candidates: list[str]) -> set[str]:
+    """Return whichever candidates git is configured to ignore.
+
+    Asked of git rather than parsed here. `.gitignore` has nested files,
+    negation rules, a global excludes file and per-repository excludes, and a
+    half-implementation of that is worse than none: it would disagree with what
+    the repository actually holds, quietly, in the direction of hashing files
+    nobody committed.
+
+    Empty when git is missing or this is not a repository. The tool has never
+    required git and does not start now; it simply cannot answer the question
+    there, and an unanswered question excludes nothing.
+
+    Read-only, and the paths go over stdin rather than the argument list, so no
+    filename can arrive as an argument.
+    """
+    if not candidates:
+        return set()
+    try:
+        done = subprocess.run(
+            ["git", "-C", str(abs_root), "check-ignore", "--stdin"],
+            input="\n".join(candidates),
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return set()
+    # 0 means some path is ignored, 1 means none is. Anything else — not a
+    # repository, a broken install — is not an answer, so nothing is excluded.
+    if done.returncode not in (0, 1):
+        return set()
+    return {line for line in done.stdout.splitlines() if line}
+
+
+def _walk(abs_root: Path, docs_root: Path) -> list[str]:
+    """Return every candidate file, repository-relative and POSIX-separated.
+
+    Denied directories are pruned during the walk rather than filtered after,
+    so a repository with a large `.venv` or `node_modules` is not paid for.
+
+    A file git ignores is not a candidate. Build output, a coverage report or a
+    local scratch file under a module's glob would otherwise feed that module's
+    digest, so the digest would describe the machine it was computed on and the
+    module could never settle. Filtered after the walk rather than pruned
+    during it, because one `git` call answers for every path at once; the
+    directories big enough to be worth pruning are in `DENIED_DIRS` already.
+
+    Untracked files that git does *not* ignore stay in. A source file written a
+    moment ago and not yet added is exactly what a document should cover, and
+    excluding it would break the loop this tool exists for.
+    """
+    out: list[str] = []
+    docs_parts = docs_root.parts
+    for dirpath, dirnames, filenames in os.walk(abs_root):
+        rel_dir = Path(dirpath).relative_to(abs_root)
+        dirnames[:] = [
+            d
+            for d in dirnames
+            if d not in DENIED_DIRS
+            and (rel_dir / d).parts[: len(docs_parts)] != docs_parts
+        ]
+        dirnames.sort()
+        for name in sorted(filenames):
+            rel = rel_dir / name if rel_dir != Path(".") else Path(name)
+            if _is_denied(rel) or _is_denied_target(Path(dirpath) / name):
+                continue
+            out.append(rel.as_posix())
+    ignored = _git_ignored(abs_root, out)
+    return [rel for rel in out if rel not in ignored]
+
+
+def _resolve_globs(
+    root: Path, modules: list[ModuleEntry], docs_root: Path
+) -> dict[str, list[Path]]:
+    """Resolve each module's globs against *root* and return file sets.
+
+    The tree is walked once and every file matched against every pattern,
+    rather than each pattern being resolved separately. That is what lets
+    `mark` share the matcher: a hook is handed one path and must decide which
+    module it belongs to without touching the disk, and two glob
+    implementations that agree today will disagree eventually.
+
+    Patterns come from :func:`effective_globs`, so a module that covers
+    another resolves to the union of both — and a file that two routes reach
+    is hashed once, because the match is over a set.
+
+    Files under *docs_root* are excluded whatever the glob says. The docs root
+    holds this tool's own output, so a glob that sweeps it up cannot converge:
+    writing the document changes a file the document hashes, which marks it
+    stale again on the next run. A catch-all glob such as `**/*` — which is
+    exactly what a build log wants — hits this immediately.
+
+    A document declared outside the docs root is excluded for the same reason
+    and by name, because the walk has no directory to prune. Without it, a
+    `README.md` written by the tool and swept up by another module's glob
+    makes that module stale on every run, for ever.
+    """
+    abs_root = root.resolve()
+    declared = {mod.document for mod in modules if mod.document is not None}
+    candidates = [rel for rel in _walk(abs_root, docs_root) if rel not in declared]
+    patterns = effective_globs(modules)
+    result: dict[str, list[Path]] = {}
+    for mod in modules:
+        # A pattern the matcher cannot compile is a configuration problem, and
+        # naming the module is the whole difference between a fixable message
+        # and `bad character range z-a at position 9` with no idea where it
+        # came from. Criterion 21 requires the offending key.
+        try:
+            files = {
+                Path(rel)
+                for rel in candidates
+                if any(glob_matches(pattern, rel) for pattern in patterns[mod.key])
+            }
+        except GlobError as e:
+            raise ConfigError(
+                f"Module {mod.key!r} declares a glob that cannot be used: {e}",
+                key="modules",
+            ) from e
+        result[mod.key] = sorted(files)
+    return result
+
+
+def _detect_ambiguity(
+    modules: list[ModuleEntry],
+    module_files: dict[str, list[Path]],
+) -> list[tuple[str, str, Path]]:
+    """Return (module_a, module_b, file) for every overlap *within a kind*.
+
+    Criterion 22 refuses two globs matching the same file, and its reason is
+    that a reader cannot tell which document describes that file. Kinds change
+    what "ambiguous" means: a source file is legitimately covered by its module
+    document, by the specification that governs it, and by the build log that
+    records changes to it. Those are three views of one file, not three claims
+    of ownership, and the plan's own configuration example depends on it.
+
+    So the check is scoped to a kind. Two `module` entries matching one file is
+    still an error, and still exits 2.
+    """
+    kind_of = {m.key: m.kind for m in modules}
+    seen: dict[tuple[str, Path], str] = {}
+    conflicts: list[tuple[str, str, Path]] = []
+    for mod_key, files in module_files.items():
+        kind = kind_of.get(mod_key, DEFAULT_KIND)
+        for f in files:
+            previous = seen.get((kind, f))
+            if previous is not None:
+                conflicts.append((previous, mod_key, f))
+            else:
+                seen[(kind, f)] = mod_key
+    return conflicts
+
+
+@dataclass(frozen=True)
+class Declarations:
+    """What the file says, before any glob touches the filesystem.
+
+    `mark` runs on every file write and needs only this: the patterns, so it
+    can decide which module a path belongs to, and the docs root, so it can
+    ignore the tool's own output. Resolving globs walks the whole tree, which
+    is the difference between a hook nobody notices and one a user turns off.
+    """
+
+    version: int
+    docs_root: Path
+    modules: list[ModuleEntry]
+    index_token_budget: int | None
+    kinds: dict[str, Kind]
+    uncovered: dict[str, str]
+    auto: AutoSettings | None
+
+
+def declarations(path: str | Path) -> Declarations:
+    """Parse and structurally validate a ``constant-docs.yaml`` file.
+
+    Everything except glob resolution and the ambiguity check, both of which
+    need the filesystem.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise ConfigError(f"Config file not found: {path}", key=MISSING_KEY)
+
+    # Wrapped so an unparseable configuration is a configuration error rather
+    # than PyYAML's own exception, which is not a `ConfigError` and so escaped
+    # every handler that exists to catch one — including the `mark` hook, which
+    # then failed loudly on every file write while the file was mid-edit.
+    try:
+        raw: dict[str, Any] = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as e:
+        # A distinct key, because "there is no configuration here" and "the
+        # configuration is broken" are opposite facts that the hooks treat
+        # differently. Both are `ConfigError`; only the first may be silent.
+        raise ConfigError(f"{path} is not valid YAML: {e}", key=SYNTAX_KEY) from e
+    except UnicodeDecodeError as e:
+        # The one read in the package that used to take the platform
+        # locale encoding. On Windows it silently mojibakes a glob or an
+        # `uncovered:` reason rather than raising, and `add_module` writes
+        # this same file as UTF-8 — so the writer could produce bytes the
+        # reader could not take back.
+        raise ConfigError(f"{path} is not valid UTF-8: {e}", key=SYNTAX_KEY) from e
+
+    # --- version -----------------------------------------------------------
+    version = raw.get("version")
+    if version != 1:
+        raise ConfigError(
+            f"Expected version=1 but got {version!r}",
+            key="version",
+        )
+
+    # --- docs_root ---------------------------------------------------------
+    docs_root_raw = raw.get("docs_root")
+    if not docs_root_raw:
+        raise ConfigError(
+            "'docs_root' is required — set it to the directory where "
+            "module documents should be stored (e.g. 'docs/modules')",
+            key="docs_root",
+        )
+    docs_root = Path(str(docs_root_raw))
+    # The docs root has to be a real folder inside the repository, because
+    # excluding it from the source walk is a path-prefix test and a prefix
+    # that is empty or non-relative matches either everything or nothing.
+    # `docs_root: "."` has no parts at all, so the walk pruned every
+    # directory, every module resolved to no files, and `prune` reported the
+    # tool's own documents as orphans and deleted them. The same empty prefix
+    # makes `state._is_tool_output` true for every path, which silently stops
+    # `mark` marking anything.
+    normalised = Path(os.path.normpath(docs_root))
+    if docs_root.is_absolute() or not normalised.parts or normalised.parts[0] == "..":
+        raise ConfigError(
+            f"'docs_root' must be a relative directory inside the repository "
+            f"(e.g. 'docs' or 'docs/modules'), got {str(docs_root_raw)!r}. "
+            f"Documents need a folder of their own: a docs root that is the "
+            f"repository root, or outside it, cannot be excluded from the "
+            f"source walk.",
+            key="docs_root",
+        )
+    # The normalised form is what is kept, not just what was checked. Both
+    # `_walk`'s prune test and `state._is_tool_output` compare `.parts` as a
+    # prefix, so a value like `docs/../notes` would validate on its normalised
+    # form and then never match the `notes/` it actually resolves to — putting
+    # the tool's own output back into the source walk.
+    docs_root = normalised
+
+    # --- modules -----------------------------------------------------------
+    # An explicitly empty mapping is allowed: a repository part-way through
+    # adopting the tool has nothing tracked yet, and `init` has to be able to
+    # write a file that loads. A *missing* key stays an error, and so does a
+    # null one — `modules:` with nothing after it is a half-written file, and a
+    # mistyped key that loaded with nothing tracked would be a repository where
+    # every check passes and nothing is checked.
+    if "modules" not in raw:
+        raise ConfigError(
+            "'modules' is required and must be a mapping of module key to "
+            "glob pattern(s), e.g.\n  src/payments: src/payments/**/*.py",
+            key="modules",
+        )
+    raw_modules = raw["modules"]
+    if not isinstance(raw_modules, dict):
+        raise ConfigError(
+            "'modules' is required and must be a mapping of module key to "
+            "glob pattern(s), e.g.\n  src/payments: src/payments/**/*.py",
+            key="modules",
+        )
+
+    # --- kinds ---------------------------------------------------------
+    # Loaded before modules, because a module entry names one.
+    try:
+        kinds = load_kinds(raw.get("kinds"))
+    except KindError as e:
+        raise ConfigError(str(e), key="kinds") from e
+
+    modules: list[ModuleEntry] = []
+    for mod_key, entry_value in raw_modules.items():
+        # Three accepted shapes, and the first two are 0.1's:
+        #   src/payments: <glob>
+        #   src/payments: [<glob>, <glob>]
+        #   src/payments: {glob: <glob or list>, kind: <name>}
+        covers_list: list[str] = []
+        document: str | None = None
+        if isinstance(entry_value, dict):
+            unknown = set(entry_value) - {"glob", "kind", "covers", "document"}
+            if unknown:
+                raise ConfigError(
+                    f"Module {mod_key!r} declares unknown key(s): "
+                    f"{', '.join(sorted(unknown))}. Only 'glob', 'kind', "
+                    f"'covers' and 'document' are accepted.",
+                    key="modules",
+                )
+            if "glob" not in entry_value and "covers" not in entry_value:
+                raise ConfigError(
+                    f"Module {mod_key!r} is declared as a mapping with neither "
+                    f"'glob' nor 'covers'. Give it files of its own with "
+                    f"`glob: <pattern>`, or name the modules whose files it "
+                    f"takes in with `covers: [<module>]`.",
+                    key="modules",
+                )
+            glob_value = entry_value.get("glob", [])
+            kind_name = str(entry_value.get("kind", DEFAULT_KIND))
+            covers_list = _as_name_list(mod_key, entry_value.get("covers", []))
+            if "document" in entry_value:
+                document = validate_document_path(str(mod_key), entry_value["document"])
+        else:
+            glob_value = entry_value
+            kind_name = DEFAULT_KIND
+
+        if isinstance(glob_value, str):
+            glob_list = [glob_value]
+        elif isinstance(glob_value, list):
+            glob_list = [str(g) for g in glob_value]
+        else:
+            raise ConfigError(
+                f"Glob for module {mod_key!r} must be a string or a "
+                f"list of strings, got {type(glob_value).__name__}",
+                key="modules",
+            )
+
+        if kind_name not in kinds:
+            raise ConfigError(
+                f"Module {mod_key!r} names kind {kind_name!r}, which is not "
+                f"declared. Available: {', '.join(sorted(kinds))}",
+                key="modules",
+            )
+
+        validate_module_key(str(mod_key))
+
+        modules.append(
+            ModuleEntry(
+                key=str(mod_key),
+                globs=glob_list,
+                kind=kind_name,
+                covers=covers_list,
+                document=document,
+            )
+        )
+
+    # Both refusals are structural, so they run here rather than in `load`:
+    # `mark` parses declarations and nothing else, and it must not silently
+    # cover a module that does not exist.
+    _validate_covers(modules)
+
+    # --- index -------------------------------------------------------------
+    raw_index = raw.get("index", {}) or {}
+    index_token_budget: int | None = None
+    if "token_budget" in raw_index:
+        t = raw_index["token_budget"]
+        if isinstance(t, bool) or not isinstance(t, int) or t <= 0:
+            raise ConfigError(
+                f"'index.token_budget' must be a positive integer, got {t!r}",
+                key="index.token_budget",
+            )
+        index_token_budget = t
+
+    # --- uncovered ---------------------------------------------------------
+    raw_uncovered = raw.get("uncovered", {}) or {}
+    if not isinstance(raw_uncovered, dict):
+        raise ConfigError(
+            "'uncovered' must be a mapping of glob pattern to the reason that "
+            "pattern is deliberately undocumented, e.g.\n"
+            '  "tests/fixtures/**": Test data rather than source',
+            key="uncovered",
+        )
+    uncovered: dict[str, str] = {}
+    for pattern, reason in raw_uncovered.items():
+        if not isinstance(reason, str) or not reason.strip():
+            raise ConfigError(
+                f"'uncovered' entry {str(pattern)!r} has no reason. Every "
+                f"exclusion needs one: an exclusion nobody justified is one "
+                f"nobody decided, and it will outlive whatever made it "
+                f"sensible.",
+                key="uncovered",
+            )
+        uncovered[str(pattern)] = reason.strip()
+
+    # --- auto ---------------------------------------------------------------
+    auto = _load_auto(raw.get("auto"))
+
+    return Declarations(
+        version=version,
+        docs_root=docs_root,
+        modules=modules,
+        index_token_budget=index_token_budget,
+        kinds=kinds,
+        uncovered=uncovered,
+        auto=auto,
+    )
+
+
+def _scalar(value: str) -> str:
+    """Return *value* quoted exactly as much as YAML requires, and no more.
+
+    Reached for rather than written by hand because the failure is quiet and
+    specific: a glob beginning `*` is a YAML alias indicator, so `- *.md`
+    is a parse error, and `add` would leave a configuration nothing can load.
+    Dumping a one-item list and stripping the bullet is the shortest way to
+    borrow the emitter's own judgement about when a quote is needed.
+    """
+    return yaml.safe_dump(
+        [value], default_flow_style=False, allow_unicode=True
+    ).strip()[2:]
+
+
+def _render_entry(name: str, globs: list[str], covers: list[str], kind: str) -> str:
+    """Return the YAML text for one module entry, indented for the block."""
+    lines = [f"  {_scalar(name)}:"]
+    if globs:
+        lines.append("    glob:")
+        lines.extend(f"      - {_scalar(g)}" for g in globs)
+    if covers:
+        lines.append("    covers:")
+        lines.extend(f"      - {_scalar(c)}" for c in covers)
+    lines.append(f"    kind: {_scalar(kind)}")
+    return "\n".join(lines) + "\n"
+
+
+_EMPTY_MODULES_RE = re.compile(r"^modules:\s*\{\s*\}\s*$")
+
+
+def _modules_block_end(lines: list[str]) -> int:
+    """Return the line index at which the `modules:` block ends.
+
+    Text surgery rather than a load-and-dump round trip, because this
+    repository's own configuration is more comment than configuration and the
+    reasons recorded there are not recoverable from the keys. A YAML emitter
+    would drop every one of them, which is data loss dressed up as
+    normalisation.
+    """
+    start = next(
+        (i for i, line in enumerate(lines) if line.rstrip() == "modules:"),
+        None,
+    )
+    if start is None:
+        raise ConfigError(
+            "No 'modules:' block found to add to. The key must be at the top "
+            "level and on a line of its own.",
+            key="modules",
+        )
+    end = len(lines)
+    for i in range(start + 1, len(lines)):
+        stripped = lines[i].strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if not lines[i][:1].isspace():
+            end = i
+            break
+    # Blank lines *and a trailing comment block* before the next top-level key
+    # belong to the gap, not to the block, so the new entry lands inside
+    # `modules:` rather than after it. The comments matter as much as the
+    # blanks: a comment at the end of the block is documenting whatever comes
+    # next — `init` writes a commented-out `uncovered:` template exactly there
+    # — and an entry inserted below it reads as belonging to that key. It
+    # loads today only because YAML cannot see comments, and stops loading the
+    # moment somebody uncomments the template the tool invited them to use.
+    while end > start + 1 and (
+        not lines[end - 1].strip() or lines[end - 1].lstrip().startswith("#")
+    ):
+        end -= 1
+    return end
+
+
+def add_module(
+    path: str | Path,
+    name: str,
+    *,
+    globs: list[str] | None = None,
+    covers: list[str] | None = None,
+    kind: str = DEFAULT_KIND,
+) -> None:
+    """Add one module entry to a configuration file.
+
+    Registering a document becomes a command rather than a hand edit, which is
+    the point: editing structured files in place is what agents do worst, and
+    a mistake surfaces as the whole repository failing to load.
+
+    The result is validated by loading it. If the loader refuses — a duplicate
+    document path, a glob colliding with another module of the same kind, a
+    cycle — the file is restored byte for byte and the loader's own error is
+    raised. Half a configuration is worse than none, because it breaks the
+    command that would explain why.
+    """
+    path = Path(path)
+    globs = list(globs or [])
+    covers = list(covers or [])
+    if not globs and not covers:
+        raise ConfigError(
+            f"Module {name!r} needs files. Give it --glob <pattern>, or name "
+            f"the modules whose files it takes in with --covers <module>.",
+            key="modules",
+        )
+
+    decl = declarations(path)
+    if any(m.key == name for m in decl.modules):
+        raise ConfigError(
+            f"Module {name!r} is already declared. Edit its entry rather than "
+            f"adding a second one; two entries under one key is a document "
+            f"whose boundary depends on which was read last.",
+            key="modules",
+        )
+    if kind not in decl.kinds:
+        raise ConfigError(
+            f"Kind {kind!r} is not declared. Available: "
+            f"{', '.join(sorted(decl.kinds))}",
+            key="kinds",
+        )
+
+    original = path.read_text(encoding="utf-8")
+    lines = original.splitlines(keepends=True)
+    # `modules: {}` is what `init` writes into a repository with nothing
+    # tracked yet. It is a mapping the loader accepts and not a block anything
+    # can be inserted into, so the first `add` turns it into one.
+    for i, line in enumerate(lines):
+        if _EMPTY_MODULES_RE.match(line):
+            lines[i] = "modules:\n"
+            break
+    end = _modules_block_end(lines)
+    entry = _render_entry(name, globs, covers, kind)
+    if end > 0 and lines[end - 1].strip():
+        entry = "\n" + entry
+    updated = "".join(lines[:end]) + entry + "".join(lines[end:])
+
+    # The write is inside the try, and the restore covers everything, because
+    # the failure that actually corrupts the file was the one not covered: a
+    # rendered entry the loader cannot parse arrives as `yaml.YAMLError`,
+    # which is not a `ConfigError`, so the rollback never fired in precisely
+    # the case it was written for. A rollback that only undoes the errors
+    # somebody predicted is not a rollback.
+    try:
+        path.write_text(updated, encoding="utf-8")
+        load(path)
+    except Exception:
+        with suppress(OSError):
+            path.write_text(original, encoding="utf-8")
+        raise
+
+
+_AUTO_TRIGGERS = ("stale", "always")
+
+
+def _load_auto(raw: Any) -> AutoSettings | None:
+    """Parse the `auto:` block, or return None when there is none.
+
+    Refused rather than tolerated, key by key, for the usual reason: a mistyped
+    key that is silently ignored is a setting its author believes is in force —
+    and here that setting decides whether a command runs at all.
+    """
+    if raw is None:
+        return None
+    if not isinstance(raw, dict):
+        raise ConfigError(
+            "'auto' must be a mapping with a 'command', e.g.\n"
+            "  auto:\n    command: \"<your agent> -p 'Run the settle loop'\"",
+            key="auto",
+        )
+    # `on:` is a YAML 1.1 boolean, so a block written with it arrives here as
+    # `{True: "stale"}` and every key lookup misses. Caught by name, because
+    # the alternative is a user staring at a configuration that plainly says
+    # `on: stale` and a tool insisting there is no such key.
+    if any(isinstance(key, bool) for key in raw):
+        raise ConfigError(
+            "'auto' has a key YAML read as a boolean. `on`, `off`, `yes` and "
+            "`no` are booleans in YAML, so `on: stale` becomes `true: stale`. "
+            "The key is 'when'.",
+            key="auto.when",
+        )
+    unknown = set(raw) - {"command", "when", "budget", "timeout"}
+    if unknown:
+        raise ConfigError(
+            f"'auto' declares unknown key(s): {', '.join(sorted(unknown))}. "
+            f"Only 'command', 'when', 'budget' and 'timeout' are accepted.",
+            key="auto",
+        )
+
+    command = raw.get("command")
+    if not isinstance(command, str) or not command.strip():
+        raise ConfigError(
+            "'auto.command' is required and must be the command to run, e.g.\n"
+            "  command: \"<your agent> -p 'Run the constant-docs settle loop'\"",
+            key="auto.command",
+        )
+
+    trigger = str(raw.get("when", "stale"))
+    if trigger not in _AUTO_TRIGGERS:
+        raise ConfigError(
+            f"'auto.when' is {trigger!r}; it must be one of "
+            f"{', '.join(_AUTO_TRIGGERS)}",
+            key="auto.when",
+        )
+
+    budget = raw.get("budget")
+    # `isinstance(budget, bool)` first: `bool` subclasses `int`, so the
+    # YAML 1.1 booleans `yes`, `on` and `true` all arrive as `True`, pass a
+    # positive-integer test, and slice as a silent cap of one module per
+    # run. The same trap the boolean-key guard above catches for `on:`,
+    # arriving as a value instead of a key.
+    if budget is not None and (
+        isinstance(budget, bool) or not isinstance(budget, int) or budget <= 0
+    ):
+        raise ConfigError(
+            f"'auto.budget' must be a positive integer of modules per run, "
+            f"got {budget!r}",
+            key="auto.budget",
+        )
+
+    timeout = raw.get("timeout")
+    if timeout is not None and (
+        isinstance(timeout, bool)
+        or not isinstance(timeout, (int, float))
+        or timeout <= 0
+    ):
+        raise ConfigError(
+            f"'auto.timeout' must be a positive number of seconds, got {timeout!r}",
+            key="auto.timeout",
+        )
+
+    return AutoSettings(
+        command=command.strip(),
+        when=trigger,
+        budget=budget,
+        timeout=float(timeout) if timeout is not None else None,
+    )
+
+
+def load(path: str | Path) -> Config:
+    """Parse, validate, and resolve a ``constant-docs.yaml`` file.
+
+    Raises :exc:`ConfigError` on structural problems (bad version, missing
+    keys, ambiguous globs). Returns a fully resolved :class:`Config`.
+    """
+    path = Path(path)
+    decl = declarations(path)
+
+    # --- resolve globs -----------------------------------------------------
+    root = path.resolve().parent
+    module_files = _resolve_globs(root, decl.modules, decl.docs_root)
+
+    # --- document-path collisions -------------------------------------------
+    # Checked before the glob ambiguity, because a collision here means two
+    # modules cannot both have a document at all, whatever their globs match.
+    doc_conflicts = _detect_document_collisions(decl.modules, decl.docs_root)
+    if doc_conflicts:
+        lines = [
+            f"  {a!r} and {b!r} both write {p.as_posix()}" for a, b, p in doc_conflicts
+        ]
+        raise ConfigError(
+            "Two module keys resolve to the same document path. A key is the "
+            "document's path stem, so a key ending in '.md' collides with the "
+            "same key without it, and a declared 'document' collides with "
+            "whatever else writes there:\n" + "\n".join(lines),
+            key="modules",
+        )
+
+    # --- ambiguity check ---------------------------------------------------
+    conflicts = _detect_ambiguity(decl.modules, module_files)
+    if conflicts:
+        lines = [f"  {a!r} and {b!r} both match {f}" for a, b, f in conflicts]
+        raise ConfigError(
+            "Glob ambiguity — the following files are matched by more "
+            "than one module of the same kind:\n" + "\n".join(lines),
+            key="modules",
+        )
+
+    return Config(
+        version=decl.version,
+        docs_root=decl.docs_root,
+        modules=decl.modules,
+        index_token_budget=decl.index_token_budget,
+        kinds=decl.kinds,
+        uncovered=decl.uncovered,
+        auto=decl.auto,
+        module_files=module_files,
+    )