constant-docs 0.4.0__py3-none-any.whl

constant_docs/coverage.py

@@ -0,0 +1,165 @@
+"""What the repository holds, and what covers it.
+
+`verify` can only check what has been declared. It hashes the modules in the
+configuration and says nothing at all about source nobody registered, so a
+project can drift to a large fraction undocumented while every check passes.
+That is a control reporting success while not looking, and it was the one place
+this tool had it.
+
+Coverage is a **set difference** — the repository's files, minus the union of
+every module's resolved files, minus what configuration says is deliberately
+uncovered. No model, no parsing, no judgement.
+
+## Exclusions are declared, not inferred
+
+A repository has directories that legitimately want no document: fixtures,
+vendored code, generated output. Those are named in configuration with a reason
+each, in the idiom every other exemption here uses. An inferred exclusion is one
+nobody decided, and it will outlive whatever made it sensible.
+
+Two exclusions are *not* declared, because they are already refused everywhere
+else: secrets, which must never be read at all, and derived output, which is
+built from source the tool already hashes.
+
+## The judgement half
+
+`init` is the other side of this and does not put a model in the package. The
+tool gathers facts — the tree, the file counts, what is covered, what is
+excluded — the harness proposes a module map, and `add` writes it after
+validating it.
+
+**A re-run never removes.** `init` is meant to be run again as a repository
+grows, which makes periodic-plus-destructive the shape to avoid: dropping a
+module orphans its document and `prune` then deletes it. So it is additive and
+proposing only. Removing a module stays a hand edit, because it destroys a
+document and that should cost somebody a decision.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from constant_docs.config import _walk
+from constant_docs.globs import matches as glob_matches
+
+# Files that are the tool's own furniture rather than a repository's source.
+# Nothing would ever document them, and proposing them wastes the reader's
+# attention on the one output where attention is the whole cost.
+_FURNITURE = ("constant-docs.yaml",)
+
+
+def _all_files(cfg: Any, repo_root: Path) -> list[str]:
+    """Every candidate file, repository-relative and POSIX-separated.
+
+    The same walk glob resolution uses, so secrets, build caches and the docs
+    root are already gone — a file that can never be hashed must never be
+    proposed for documenting either.
+    """
+    return _walk(repo_root.resolve(), cfg.docs_root)
+
+
+def uncovered_files(
+    cfg: Any, repo_root: Path, all_files: list[str] | None = None
+) -> list[Path]:
+    """Return every file no module covers and no exclusion names, sorted.
+
+    *all_files* lets a caller that has already walked the tree hand the
+    result in. `facts` needs the same list for its directory counts, and
+    walking twice for one question made `init` — the command written to be
+    re-run as a repository grows — pay for three walks where one would do.
+    """
+    covered = {f.as_posix() for files in cfg.module_files.values() for f in files}
+    out: list[Path] = []
+    for rel in _all_files(cfg, repo_root) if all_files is None else all_files:
+        if rel in covered or rel in _FURNITURE:
+            continue
+        if any(glob_matches(pattern, rel) for pattern in cfg.uncovered):
+            continue
+        out.append(Path(rel))
+    return sorted(out)
+
+
+def by_directory(files: list[Path]) -> dict[str, list[str]]:
+    """Group *files* by their parent directory.
+
+    Four hundred paths is a list; twelve directories is a decision. The output
+    of a coverage report is meant to be acted on, and a report nobody can act
+    on is one nobody runs twice.
+    """
+    grouped: dict[str, list[str]] = {}
+    for f in files:
+        parent = f.parent.as_posix()
+        grouped.setdefault(parent if parent else ".", []).append(f.as_posix())
+    return {k: sorted(v) for k, v in sorted(grouped.items())}
+
+
+@dataclass(frozen=True)
+class Directory:
+    """One directory of the repository, and what the configuration says of it."""
+
+    path: str
+    files: int
+    bytes: int
+    covered: bool
+
+
+@dataclass(frozen=True)
+class Facts:
+    """Everything `init` knows, for a harness that has to propose a module map.
+
+    Facts only. What a module *is* in somebody's code is a judgement, and this
+    package holds no model to make one.
+    """
+
+    directories: list[Directory]
+    uncovered: list[str]
+    excluded: dict[str, str]
+    empty_modules: list[str]
+
+
+def facts(cfg: Any, repo_root: Path) -> Facts:
+    """Gather what a harness needs to propose a module map."""
+    covered = {f.as_posix() for files in cfg.module_files.values() for f in files}
+    # Walked once and used twice. Both the exclusion pass and the directory
+    # counts below need the same list.
+    all_files = _all_files(cfg, repo_root)
+    missing = uncovered_files(cfg, repo_root, all_files=all_files)
+
+    counts: dict[str, int] = {}
+    sizes: dict[str, int] = {}
+    covered_dirs: dict[str, bool] = {}
+    for rel in all_files:
+        if rel in _FURNITURE:
+            continue
+        parent = Path(rel).parent.as_posix() or "."
+        counts[parent] = counts.get(parent, 0) + 1
+        try:
+            sizes[parent] = sizes.get(parent, 0) + (repo_root / rel).stat().st_size
+        except OSError:
+            sizes.setdefault(parent, 0)
+        # A directory counts as covered when anything in it is, which is what a
+        # reader deciding where to look next actually wants to know.
+        covered_dirs[parent] = covered_dirs.get(parent, False) or rel in covered
+
+    return Facts(
+        directories=[
+            Directory(
+                path=path,
+                files=counts[path],
+                bytes=sizes.get(path, 0),
+                covered=covered_dirs.get(path, False),
+            )
+            for path in sorted(counts)
+        ],
+        uncovered=[p.as_posix() for p in missing],
+        excluded=dict(sorted(cfg.uncovered.items())),
+        # A module whose glob matches nothing. Reported, never removed: its
+        # document is an orphan, and `prune` deletes an orphan's document, so a
+        # periodic command that dropped the entry would delete prose on a
+        # schedule.
+        empty_modules=sorted(
+            key for key, files in cfg.module_files.items() if not files
+        ),
+    )

constant_docs/decisions.py

@@ -0,0 +1,303 @@
+"""The decisions a document records, and the guard against losing one.
+
+## Why this exists
+
+`docs/SPEC.md` is a tracked document in replace mode: a model rewrites its
+body whenever the source moves. The decisions it records — *the tool never
+calls a model*, *hash contents rather than the interface*, *no source parsing*
+— are choices the source cannot state for itself, and they are the reason the
+tool is what it is.
+
+What protected them before this module was a paragraph in the `spec` prompt
+asking the model to edit rather than rewrite. That paragraph is the right
+instruction and it is **not a control**. A regeneration that drops a decision,
+keeps its required sections and updates its hash passes `verify` and reports
+success. The failure mode is not a model behaving badly; it is that when one
+does, nothing says so — and fifty regenerations later the leak is silent,
+gradual, and invisible to every check the tool has.
+
+## Why detection rather than ownership
+
+The obvious answer is to mark the specification human-owned and forbid the
+tool to write it. That is the wrong one, and this project has the evidence:
+the documents that rotted were exactly the human-versioned ones. Ownership is
+not a mechanism. What makes an agent-maintained document safe is that **loss
+is detectable**, so a regeneration is free to rewrite anything and unable to
+drop something without saying so.
+
+## The marker
+
+A decision carries a stable identifier, in the document rather than in a side
+file — the same reasoning that put the hash in frontmatter rather than a lock
+file. A side file is a second thing to keep in step, and the document travels
+without it.
+
+```markdown
+| <!-- decision: no-model-client --> Never call a model | The harness … |
+```
+
+An HTML comment because it is the one syntax that works everywhere a decision
+actually gets written — a table cell, a paragraph, a heading — and renders as
+nothing, so the identifier costs the reader no attention. Put it at the start
+of the decision: everything from the marker to the next marker or the next H2
+is that decision's content, so a marker at the start means the whole decision
+is covered by the emptiness check.
+
+## The limit, stated rather than discovered
+
+This catches a decision being **deleted**. It cannot catch one being
+**degraded** — reworded into something weaker that still says words. No check
+this tool can make would, short of understanding the prose, and a check that
+fought editing would make the tool useless for the thing it exists to do: a
+body that rewords every decision while keeping every identifier is accepted,
+deliberately.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+# `<!-- decision: some-slug -->`, tolerant of the whitespace a formatter or a
+# model will introduce, strict about the slug: lowercase, digits and hyphens,
+# so an identifier cannot drift by capitalisation while looking unchanged.
+_MARKER_RE = re.compile(
+    r"<!--\s*decision\s*:\s*([a-z0-9][a-z0-9-]*)\s*-->",
+    re.IGNORECASE,
+)
+
+# A fenced block, and an inline code span. Both are stripped before anything
+# is matched: a marker inside either is an example of the syntax, not a
+# decision. This repository's own specification documents the marker, so the
+# distinction is load-bearing rather than theoretical.
+_FENCE_RE = re.compile(r"^```.*?^```", re.MULTILINE | re.DOTALL)
+_CODE_SPAN_RE = re.compile(r"`[^`\n]*`")
+
+# A decision's content runs to the next marker or the next section, whichever
+# comes first. Without the section stop, the last decision in
+# `## Design decisions` would swallow `## Acceptance criteria` and every later
+# section, and emptying it would then be undetectable.
+_SECTION_RE = re.compile(r"^## ", re.MULTILINE)
+
+
+class DecisionError(Exception):
+    """A body's decisions are wrong in a way that refuses the write.
+
+    Its own family rather than a `DocumentError`, so this module depends on
+    nothing but the standard library — the same property that lets `globs` be
+    shared by the resolver and by `mark`.
+    """
+
+
+class DuplicateDecision(DecisionError):
+    """Two decisions in one body share an identifier.
+
+    Refused rather than resolved, because the guard answers "is this decision
+    still here" by name. Two decisions under one name means dropping either
+    leaves the name present and the loss invisible, which is the exact failure
+    this module exists to prevent.
+    """
+
+
+class DecisionLoss(DecisionError):
+    """A rewrite dropped or hollowed out a decision without declaring it.
+
+    Carries the identifiers rather than only a message, so a caller can act on
+    them — put them back, or declare the retirement — without parsing prose.
+    """
+
+    def __init__(self, message: str, decisions: list[str]) -> None:
+        super().__init__(message)
+        self.decisions = decisions
+
+
+def _strip_examples(body: str) -> str:
+    """Return *body* with fenced blocks and inline code spans removed."""
+    return _CODE_SPAN_RE.sub("", _FENCE_RE.sub("", body))
+
+
+def _spans(body: str) -> list[tuple[str, str]]:
+    """Return (identifier, content) in document order, duplicates included.
+
+    Content is everything from the end of a marker to the next marker or the
+    next H2, whichever comes first.
+    """
+    text = _strip_examples(body)
+    found = list(_MARKER_RE.finditer(text))
+    out: list[tuple[str, str]] = []
+    for index, match in enumerate(found):
+        start = match.end()
+        end = found[index + 1].start() if index + 1 < len(found) else len(text)
+        section = _SECTION_RE.search(text, start, end)
+        if section is not None:
+            end = section.start()
+        out.append((match.group(1).lower(), text[start:end]))
+    return out
+
+
+def _first_wins(spans: list[tuple[str, str]]) -> dict[str, str]:
+    """Collapse duplicates by keeping the first, for comparison purposes.
+
+    `identifiers` refuses a duplicate outright. The comparison functions do
+    not, because the body they are comparing *against* is whatever is already
+    on disk — possibly written before this rule existed — and a document that
+    cannot be read is a document that can never be repaired.
+    """
+    out: dict[str, str] = {}
+    for name, content in spans:
+        out.setdefault(name, content)
+    return out
+
+
+def _carries_content(text: str) -> bool:
+    """True when *text* holds anything a reader would call a decision.
+
+    Alphanumeric characters, and nothing else, because the alternative is a
+    length threshold and there is no honest number to pick. This is the line
+    between *deleted* and *present*: a table row gutted to `| | |` renders as
+    a row and records nothing, and a reworded decision is accepted whatever
+    its length.
+    """
+    return any(ch.isalnum() for ch in text)
+
+
+def identifiers(body: str) -> dict[str, str]:
+    """Return every decision *body* records, as identifier to content.
+
+    Raises :exc:`DuplicateDecision` when one identifier appears twice.
+    """
+    spans = _spans(body)
+    repeated = duplicates(body)
+    if repeated:
+        raise DuplicateDecision(
+            "Two decisions share an identifier: "
+            + ", ".join(repeated)
+            + ". An identifier is how a decision is found again, so it has to "
+            "name exactly one."
+        )
+    return _first_wins(spans)
+
+
+def _duplicates_in(spans: list[tuple[str, str]]) -> list[str]:
+    """Return every identifier *spans* uses more than once, sorted."""
+    seen: set[str] = set()
+    repeated: set[str] = set()
+    for name, _ in spans:
+        if name in seen:
+            repeated.add(name)
+        seen.add(name)
+    return sorted(repeated)
+
+
+def duplicates(body: str) -> list[str]:
+    """Return every identifier *body* uses more than once, sorted."""
+    return _duplicates_in(_spans(body))
+
+
+def lost(previous: str, current: str) -> list[str]:
+    """Return the identifiers *previous* recorded and *current* does not.
+
+    Sorted, and complete: every dropped identifier, not the first one found.
+    A refusal that names one of three is a refusal somebody satisfies three
+    times.
+    """
+    return _lost_in(_first_wins(_spans(previous)), _first_wins(_spans(current)))
+
+
+def _lost_in(before: dict[str, str], after: dict[str, str]) -> list[str]:
+    """Return the identifiers *before* recorded and *after* does not."""
+    return sorted(set(before) - set(after))
+
+
+def check_rewrite(previous: str, current: str, retire: Iterable[str] = ()) -> list[str]:
+    """Refuse *current* if it loses a decision *previous* recorded.
+
+    Returns the identifiers this write retires, sorted, for the caller to
+    record. Raises :exc:`DecisionLoss` naming every identifier at fault, and
+    :exc:`DuplicateDecision` when *current* uses one identifier twice.
+
+    A declared retirement is checked against what actually happened, both
+    ways. Declaring the removal of a decision the body still records is
+    refused, and so is declaring one that was never there. Without that,
+    `--retire` becomes a flag somebody pastes in to make the refusal go away,
+    which is the escape hatch defeating the control — the same failure as a
+    lint suppression applied to a whole file.
+    """
+    # Both bodies scanned once, here, rather than once inside each helper.
+    # `duplicates`, `lost` and `emptied` each re-derived the spans, and every
+    # `_spans` re-runs `_strip_examples` over the whole body — five passes and
+    # ten full-body substitutions for a document this repository's own SPEC
+    # makes 466 KB of scanning where 186 KB is the whole question.
+    before_raw = _spans(previous)
+    after_raw = _spans(current)
+    before_spans = _first_wins(before_raw)
+    after_spans = _first_wins(after_raw)
+
+    repeated = _duplicates_in(after_raw)
+    if repeated:
+        raise DuplicateDecision(
+            "Two decisions share an identifier: "
+            + ", ".join(repeated)
+            + ". An identifier is how a decision is found again, so it has to "
+            "name exactly one."
+        )
+
+    declared = {name.strip().lower() for name in retire if name.strip()}
+    gone = set(_lost_in(before_spans, after_spans)) | set(
+        _emptied_in(before_spans, after_spans)
+    )
+
+    undeclared = sorted(gone - declared)
+    if undeclared:
+        raise DecisionLoss(
+            "This body drops "
+            + ("a decision" if len(undeclared) == 1 else "decisions")
+            + " the previous one recorded: "
+            + ", ".join(undeclared)
+            + ". Put "
+            + ("it" if len(undeclared) == 1 else "them")
+            + " back, or retire "
+            + ("it" if len(undeclared) == 1 else "them")
+            + " deliberately so the retirement is recorded rather than being "
+            "an absence.",
+            undeclared,
+        )
+
+    spurious = sorted(declared - gone)
+    if spurious:
+        present = set(before_spans)
+        unknown = sorted(name for name in spurious if name not in present)
+        detail = (
+            f"never recorded: {', '.join(unknown)}"
+            if unknown
+            else f"still recorded by this body: {', '.join(spurious)}"
+        )
+        raise DecisionLoss(
+            f"A retirement was declared for a decision that is {detail}. A "
+            "retirement records something that happened; declaring one that "
+            "did not turns the guard into a flag somebody pastes in.",
+            spurious,
+        )
+
+    return sorted(declared)
+
+
+def emptied(previous: str, current: str) -> list[str]:
+    """Return identifiers kept by *current* whose decision was hollowed out.
+
+    Only where *previous* carried content: the guard reports loss, not
+    pre-existing thinness, so adopting a document that already had an empty
+    decision does not become impossible.
+    """
+    return _emptied_in(_first_wins(_spans(previous)), _first_wins(_spans(current)))
+
+
+def _emptied_in(before: dict[str, str], after: dict[str, str]) -> list[str]:
+    """Return the kept identifiers whose decision was hollowed out."""
+    return sorted(
+        name
+        for name, content in before.items()
+        if name in after
+        and _carries_content(content)
+        and not _carries_content(after[name])
+    )