constant-docs 0.4.0__py3-none-any.whl

constant_docs/document.py

@@ -0,0 +1,438 @@
+"""Read, write, and validate constant-docs documents.
+
+Handles frontmatter parsing/serialization, required-heading checks,
+atomic writes, and the blank-line convention between reserved (OKF) and
+extension keys.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+# Order of reserved OKF keys in the serialized output
+_RESERVED_KEYS = [
+    "type",
+    "title",
+    "description",
+    "tags",
+    "created",
+    "updated",
+    "timestamp",
+]
+
+# The `module` kind's sections, in the form configuration writes them.
+#
+# Sections are H2 because a document is a title plus sections, not a set of
+# sections. The title lives in frontmatter, where the Open Knowledge Format
+# already has a key for it, and a body carries no H1 at all. That is what lets
+# an existing markdown document be adopted as a tracked one — the earlier
+# H1-section model could describe nothing that was already written — and it is
+# what a strict OKF consumer requires, reserving H1 for the title.
+DEFAULT_SECTIONS = ["## Purpose", "## Correctness pillars", "## Known failure modes"]
+
+_FENCE_RE = re.compile(r"^```.*?^```", re.MULTILINE | re.DOTALL)
+_H1_RE = re.compile(r"^# ", re.MULTILINE)
+
+_FM_RE = re.compile(r"^---\n(.*?)\n---\n?(.*)", re.DOTALL)
+
+# The same block, written where a Markdown host renders nothing.
+#
+# A document under the docs root is part of an Open Knowledge Format bundle
+# and carries YAML frontmatter, which is what makes the tree conformant. A
+# document declared outside the root is already outside that bundle, and the
+# hosts that render those files — GitHub renders a README on the repository
+# landing page — show frontmatter as a table above the title. That is the
+# first screenful of the most-read file in the repository spent on a hash.
+#
+# The block still lives in the file. The alternative is a sidecar holding the
+# hash, and `hash-in-frontmatter` refused that: two files that must agree,
+# with nothing keeping them in step.
+_COMMENT_RE = re.compile(r"^<!--\s*constant-docs\n(.*?)\n-->\n?(.*)", re.DOTALL)
+
+YAML_FRONTMATTER = "yaml"
+COMMENT_FRONTMATTER = "comment"
+FRONTMATTER_STYLES = (YAML_FRONTMATTER, COMMENT_FRONTMATTER)
+
+# The single frontmatter key this tool owns. An OKF producer extension: a
+# consumer that knows nothing about constant-docs ignores it, and nothing the
+# host writes can collide with it. Defined here rather than in `api`, because
+# `paths` and `index` read it too and a second spelling of it would let a
+# document be fresh to one caller and malformed to another.
+EXTENSION_KEY = "constant_docs"
+
+# The same block under the names earlier versions wrote. Read, never written:
+# a document carrying one of these is migrated on its next write, so a
+# repository that upgrades mid-life ends up with one block rather than two.
+LEGACY_EXTENSION_KEYS = ("module_docs",)
+
+
+def extension_block(frontmatter: dict[str, Any]) -> dict[str, Any]:
+    """Return this tool's frontmatter block, tolerating pre-0.2 spellings.
+
+    Returns an empty mapping when the document carries no recognisable block,
+    so callers can read a key off the result without a null check.
+    """
+    for key in (EXTENSION_KEY, *LEGACY_EXTENSION_KEYS):
+        block = frontmatter.get(key)
+        if isinstance(block, dict):
+            return block
+    return {}
+
+
+# The key inside our block that makes a document *ours*.
+#
+# `source_hash` is the tool's entire claim on a file: it says these contents
+# were derived from these source files at this digest. A file without one was
+# never tracked, so nothing about it can have gone stale — and a tool with no
+# stake in a file has no business deleting it.
+#
+# One key rather than the full required set, because the two errors are not
+# equally expensive. Declining to prune a document we did write leaves a stale
+# file that `verify` still reports. Pruning one we did not write destroys
+# somebody's work, silently, and having a `docs/` folder already is the normal
+# way people adopt a documentation tool.
+OWNERSHIP_KEY = "source_hash"
+
+
+def is_tracked(frontmatter: dict[str, Any]) -> bool:
+    """Return whether this tool wrote the document *frontmatter* came from.
+
+    The read is deliberately narrow. The block must be ours — namespaced, or
+    under a spelling an earlier version of this tool wrote — and it must carry
+    a non-empty :data:`OWNERSHIP_KEY`. A top-level ``source_hash`` does not
+    count: the namespacing is the whole reason an OKF producer extension
+    cannot collide with its host, and honouring a bare key would give that
+    away for the one decision where being wrong costs a file.
+    """
+    return bool(str(extension_block(frontmatter).get(OWNERSHIP_KEY, "") or "").strip())
+
+
+class DocumentError(Exception):
+    """A document could not be parsed or is structurally invalid."""
+
+
+@dataclass
+class Document:
+    """An in-memory representation of a module document.
+
+    ``frontmatter`` carries every YAML key from the parse (reserved,
+    required, and unknown).  ``body`` is the markdown content after the
+    closing ``---``.
+    """
+
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+    body: str = ""
+    # The headings this document's kind requires. Carried on the document
+    # rather than passed to `serialize`, so a document cannot be written
+    # against one kind's rules and read back under another's.
+    sections: list[str] = field(default_factory=lambda: list(DEFAULT_SECTIONS))
+    # How the block is written: YAML frontmatter, or an HTML comment a
+    # Markdown host renders as nothing. Set from the kind, and carried on the
+    # document for the same reason `sections` is — so a document cannot be
+    # written in one form and read back expecting the other.
+    frontmatter_style: str = YAML_FRONTMATTER
+
+    # ------------------------------------------------------------------
+    # Serialization
+    # ------------------------------------------------------------------
+
+    def serialize(self) -> str:
+        """Return the full document string (frontmatter + body).
+
+        Raises :exc:`DocumentError` if required headings are missing.
+        """
+        # An H1 in the body duplicates the title, which lives in frontmatter —
+        # unless the frontmatter is a comment nobody renders, in which case the
+        # document has no visible title at all and needs one. The rule and its
+        # exception come from the same place: exactly one rendered H1.
+        if self.frontmatter_style != COMMENT_FRONTMATTER:
+            offending_h1 = find_h1(self.body)
+            if offending_h1 is not None:
+                raise DocumentError(
+                    f"Body contains an H1 heading: {offending_h1!r}. H1 is the "
+                    f"document's title and lives in frontmatter; sections start "
+                    f"at H2."
+                )
+        if not has_required_headings(self.body, self.sections):
+            raise DocumentError(
+                "Body is missing one or more required headings: "
+                + ", ".join(self.sections)
+            )
+
+        fm = dict(self.frontmatter)
+
+        # Extract reserved keys in order
+        reserved: dict[str, Any] = {}
+        for k in _RESERVED_KEYS:
+            if k in fm:
+                reserved[k] = fm.pop(k)
+
+        # Remaining keys: sort for deterministic output
+        extensions: dict[str, Any] = {}
+        for k in sorted(fm):
+            val = fm[k]
+            # AC 33 — always sort source_files list
+            if k == "source_files" and isinstance(val, list):
+                val = sorted(val)
+            extensions[k] = val
+
+        # Dump reserved block — always block style
+        reserved_yaml = yaml.dump(
+            reserved,
+            default_flow_style=False,
+            allow_unicode=True,
+            sort_keys=False,
+        )
+
+        # Dump extension block — always block style
+        ext_yaml = yaml.dump(
+            extensions,
+            default_flow_style=False,
+            allow_unicode=True,
+            sort_keys=False,
+        )
+
+        # Assemble: frontmatter with blank line separator, then body
+        if self.frontmatter_style == COMMENT_FRONTMATTER:
+            # One YAML document either way, so a reader that has the text can
+            # parse it with the same loader. Only the delimiters differ.
+            inner = f"{reserved_yaml}\n{ext_yaml}".rstrip("\n")
+            return f"<!-- constant-docs\n{inner}\n-->\n\n{self.body}"
+        parts = ["---\n", reserved_yaml, "\n", ext_yaml, "---\n", self.body]
+        return "".join(parts)
+
+    # ------------------------------------------------------------------
+    # Disk I/O
+    # ------------------------------------------------------------------
+
+    def save(self, path: str | Path) -> None:
+        """Write this document to *path* atomically.
+
+        If an existing file at *path* already contains the same content,
+        the file is left untouched (byte-identical).
+        """
+        content = self.serialize()
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Compare with existing content
+        if path.exists() and path.read_bytes() == content.encode():
+            return  # byte-identical — no-op
+
+        # Atomic write via temp file + rename
+        fd, tmp_path = tempfile.mkstemp(
+            dir=str(path.parent),
+            prefix=f".{path.name}.tmp.",
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(content)
+            replace_preserving_mode(tmp_path, path)
+        except BaseException:
+            # Clean up the temp file on any error
+            if os.path.exists(tmp_path):
+                os.unlink(tmp_path)
+            raise
+
+
+# ======================================================================
+# Module-level helpers
+# ======================================================================
+
+
+def replace_preserving_mode(tmp_path: str, target: Path) -> None:
+    """Move *tmp_path* onto *target*, giving it a sensible mode first.
+
+    ``tempfile.mkstemp`` creates at 0600 and ``os.replace`` carries that mode
+    across, so every file written this way came out owner-read-only and a
+    rewrite silently discarded whatever mode the file already had. Git records
+    only the exec bit, so the change is invisible in review and surfaces later
+    as a CI job or a docs server, running as another user, getting EACCES on
+    the documentation this tool exists to publish.
+
+    An existing file keeps its own mode. A new one gets what a plain create
+    would have given it, umask and all. Shared with `index` and `state`, which
+    write through the same temp-then-rename discipline and had the same bug.
+    """
+    try:
+        mode = target.stat().st_mode & 0o777
+    except OSError:
+        umask = os.umask(0)
+        os.umask(umask)
+        mode = 0o666 & ~umask
+    try:
+        os.chmod(tmp_path, mode)
+    except OSError:
+        # A filesystem that will not take a mode is not a reason to lose the
+        # write. The content still lands; only the permissions are as given.
+        pass
+    os.replace(tmp_path, target)
+
+
+class DocumentCache:
+    """Documents parsed once per command, keyed by path.
+
+    One `verify` reads every document twice — once to compare its hash, once
+    to conformance-check it — and a third time for a checked kind. Each read is
+    a `read_text`, a DOTALL frontmatter regex and a `yaml.safe_load`.
+
+    Scoped to one call and passed down, never module-global: this tool writes
+    the files it reads, and a cache outliving a single command would hand back
+    the body from before the write. A failure is remembered too, so a file that
+    cannot be parsed is not re-parsed once per scanner.
+    """
+
+    def __init__(self) -> None:
+        self._by_path: dict[Path, Document | Exception] = {}
+
+    def load(self, path: str | Path) -> Document:
+        """Return the document at *path*, reading it at most once."""
+        key = Path(path)
+        hit = self._by_path.get(key)
+        if hit is None:
+            try:
+                hit = load(key)
+            except (OSError, DocumentError, ValueError, yaml.YAMLError) as e:
+                hit = e
+            self._by_path[key] = hit
+        if isinstance(hit, Exception):
+            raise hit
+        return hit
+
+
+def load(path: str | Path) -> Document:
+    """Read a document from disk and parse its frontmatter + body.
+
+    Raises :exc:`DocumentError` if the file is missing or malformed.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise DocumentError(f"Document not found: {path}")
+
+    text = path.read_text(encoding="utf-8")
+    return parse(text)
+
+
+def parse(text: str) -> Document:
+    """Parse a document string into frontmatter and body.
+
+    Both written forms are accepted, and which one was found is recorded on
+    the document. A caller that reads a document, edits it and writes it back
+    must not silently convert it: the form is a property of the file, and
+    changing it would put a table on somebody's landing page.
+    """
+    fm, body, style = _split(text)
+    return Document(frontmatter=fm, body=body, frontmatter_style=style)
+
+
+def _parse_frontmatter_body(text: str) -> tuple[dict[str, Any], str]:
+    """Split a document string into (frontmatter_dict, body_string).
+
+    The style-agnostic spelling, kept because most callers do not care which
+    delimiters a document used and should not have to say so.
+    """
+    fm, body, _style = _split(text)
+    return fm, body
+
+
+def _split(text: str) -> tuple[dict[str, Any], str, str]:
+    """Split a document string into (frontmatter_dict, body, style)."""
+    style = YAML_FRONTMATTER
+    m = _FM_RE.match(text)
+    if m is None:
+        m = _COMMENT_RE.match(text)
+        style = COMMENT_FRONTMATTER
+    if not m:
+        raise DocumentError(
+            "Document must start with ``---`` delimited YAML frontmatter, or "
+            "a ``<!-- constant-docs`` comment block"
+        )
+    fm_text, body = m.group(1), m.group(2)
+    # Wrapped, because `load`'s docstring promises `DocumentError` for a
+    # malformed document and PyYAML's own exception is not one. Every caller
+    # that guards a document read had written its own tuple around that gap,
+    # and they disagreed: `plan`, `index.build` and the `mark` hook each let a
+    # scanner error escape, so one hand-edited document took down every
+    # command instead of being reported as the one file at fault.
+    try:
+        parsed = yaml.safe_load(fm_text)
+    except yaml.YAMLError as e:
+        raise DocumentError(f"Frontmatter is not valid YAML: {e}") from e
+    if not isinstance(parsed, dict):
+        raise DocumentError("Frontmatter must be a YAML mapping")
+    return parsed, body, style
+
+
+def _without_fences(body: str) -> str:
+    """Return *body* with fenced code blocks removed.
+
+    A heading inside a fence is an example, not a heading. Documents about
+    markdown tools are full of them.
+    """
+    return _FENCE_RE.sub("", body)
+
+
+def section_headings(body: str) -> set[str]:
+    """Return the H2 section headings in *body*, each as ``"## Heading"``.
+
+    H3 and deeper are structure *within* a section — an entry in a log, a
+    sub-point in a table — and are not sections.
+    """
+    return {
+        "## " + line.lstrip().removeprefix("## ").strip()
+        for line in _without_fences(body).splitlines()
+        if line.lstrip().startswith("## ") and not line.lstrip().startswith("### ")
+    }
+
+
+def find_h1(body: str) -> str | None:
+    """Return the first H1 line in *body*, or None.
+
+    A body must have none: the title is a frontmatter key. Returned rather
+    than asserted so the caller can name the offending line.
+    """
+    match = _H1_RE.search(_without_fences(body))
+    if not match:
+        return None
+    line = _without_fences(body)[match.start() :].split("\n", 1)[0]
+    return line.strip()
+
+
+def has_required_headings(body: str, sections: list[str] | None = None) -> bool:
+    """Return ``True`` when *body* carries every heading in *sections*."""
+    required = DEFAULT_SECTIONS if sections is None else sections
+    present = section_headings(body)
+    return all(h in present for h in required)
+
+
+def extract_description(body: str, section: str = "## Purpose") -> str:
+    """Return the first sentence of *section*.
+
+    Falls back to the whole section when there is no sentence-ending
+    punctuation. Returns an empty string when the section is missing, is
+    empty, or opens with a heading rather than prose — which is what a log's
+    ``# Entries`` does, and a heading is not a description.
+    """
+    heading = re.escape(section.strip())
+    match = re.search(
+        rf"^{heading}\s*\n+(.*?)(?=\n#{{1,2}} |\Z)", body, re.MULTILINE | re.DOTALL
+    )
+    if not match:
+        return ""
+    text = match.group(1).strip()
+    if not text or text.startswith("#"):
+        return ""
+
+    # First sentence (up to the first sentence-ending period + space/end)
+    sentence_match = re.match(r"^(.*?[.!?])(?:\s|$)", text, re.DOTALL)
+    sentence = sentence_match.group(1) if sentence_match else text
+    # Collapsed to one line: the description is written into YAML and into a
+    # markdown list item in the index, and a list item ends at the line break.
+    return " ".join(sentence.split())

constant_docs/fingerprint.py

@@ -0,0 +1,27 @@
+"""Canonical content hash for constant-docs.
+
+Exactly one implementation of the digest lives here.  Both ``api.apply``
+and ``api.verify`` import it — if you find yourself writing the hashing
+loop a second time you have already made the mistake.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+
+def compute(files: list[Path], root: Path = Path(".")) -> str:
+    """Return a deterministic content hash covering *files*.
+
+    Format: ``sha256:<64 hex chars>``.
+
+    Paths are hashed as POSIX-relative strings (*root* is stripped from the
+    digest).  File contents are read through *root* so the same file yields
+    the same hash regardless of where the repository is checked out.
+    """
+    h = hashlib.sha256()
+    for p in sorted(files, key=lambda q: q.as_posix()):
+        h.update(p.as_posix().encode())
+        h.update(hashlib.sha256((root / p).read_bytes()).digest())
+    return "sha256:" + h.hexdigest()

constant_docs/globs.py

@@ -0,0 +1,154 @@
+"""Glob matching, in one implementation.
+
+Two callers need to answer "does this path belong to this module": glob
+resolution, which walks the tree and asks it of every file, and `mark`, which
+is handed one path by a hook and must answer without touching the disk at all.
+
+They use the same matcher for the same reason there is one digest: two
+implementations that agree today will disagree eventually, and the symptom
+would be a hook marking the wrong module dirty while `verify` insists the
+right one is fine.
+
+Semantics follow `pathlib.Path.glob`, with one addition. Brace alternatives
+(`*.{ts,tsx}`) are expanded, because the specification documents them and
+`Path.glob` silently matches nothing when given one.
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+
+def expand_braces(pattern: str) -> list[str]:
+    """Expand `{a,b}` alternatives into separate patterns.
+
+    Nested braces expand too, outermost first. A pattern with no braces comes
+    back as a single-item list, so callers need no special case.
+    """
+    start = pattern.find("{")
+    if start == -1:
+        return [pattern]
+
+    depth = 0
+    for i in range(start, len(pattern)):
+        if pattern[i] == "{":
+            depth += 1
+        elif pattern[i] == "}":
+            depth -= 1
+            if depth == 0:
+                end = i
+                break
+    else:
+        # Unbalanced: treat the brace as a literal rather than guessing.
+        return [pattern]
+
+    prefix, body, suffix = pattern[:start], pattern[start + 1 : end], pattern[end + 1 :]
+
+    alternatives: list[str] = []
+    depth = 0
+    current = ""
+    for ch in body:
+        if ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+        if ch == "," and depth == 0:
+            alternatives.append(current)
+            current = ""
+        else:
+            current += ch
+    alternatives.append(current)
+
+    out: list[str] = []
+    for alt in alternatives:
+        out.extend(expand_braces(prefix + alt + suffix))
+    return out
+
+
+def _translate(pattern: str) -> str:
+    """Return a regex source matching *pattern* against a relative POSIX path.
+
+    `**` is only a recursive wildcard when it is a whole segment, which is
+    what `Path.glob` does; `a**b` is two ordinary stars.
+    """
+    segments = pattern.split("/")
+    last = len(segments) - 1
+    parts: list[str] = []
+    for index, segment in enumerate(segments):
+        if segment == "**":
+            if index == last:
+                # Trailing `**` takes everything below, however deep.
+                parts.append(".*")
+            else:
+                # Zero or more whole segments. The group carries its own
+                # trailing separator, so `src/**/x` matches `src/x`.
+                parts.append("(?:[^/]+/)*")
+            continue
+        parts.append(_translate_segment(segment))
+        if index != last:
+            parts.append("/")
+    return f"(?s:{''.join(parts)})\\Z"
+
+
+def _translate_segment(segment: str) -> str:
+    """Translate one path segment: `*`, `?`, and character classes."""
+    out: list[str] = []
+    i = 0
+    while i < len(segment):
+        ch = segment[i]
+        if ch == "*":
+            out.append("[^/]*")
+        elif ch == "?":
+            out.append("[^/]")
+        elif ch == "[":
+            close = segment.find("]", i + 1)
+            if close == -1:
+                out.append(re.escape(ch))
+            else:
+                body = segment[i + 1 : close]
+                if body.startswith("!"):
+                    body = "^" + body[1:]
+                out.append(f"[{body}]")
+                i = close + 1
+                continue
+        else:
+            out.append(re.escape(ch))
+        i += 1
+    return "".join(out)
+
+
+class GlobError(ValueError):
+    """A configured glob cannot be translated into a matcher.
+
+    Its own type so the loader can name the module the pattern belongs to.
+    A bare `re.error` was neither a `ConfigError` nor anything else a handler
+    looked for, so a reversed range in one glob exited 1 — the drift code —
+    from every command, and made `mark` fail loudly on every file write.
+    """
+
+
+@lru_cache(maxsize=1024)
+def _compiled(pattern: str) -> tuple[re.Pattern[str], ...]:
+    # A bracket expression is handed to the regex engine as written, so the
+    # engine is also what validates it. Caught here rather than at each of the
+    # three call sites, because this is the one place a pattern becomes a
+    # matcher.
+    try:
+        return tuple(re.compile(_translate(p)) for p in expand_braces(pattern))
+    except re.error as e:
+        raise GlobError(
+            f"Glob {pattern!r} is not a valid pattern: {e}. A bracket "
+            f"expression is used as written, so a reversed range such as "
+            f"'[z-a]' names nothing."
+        ) from e
+
+
+def matches(pattern: str, rel_posix: str) -> bool:
+    """True when *rel_posix* — a repository-relative POSIX path — matches.
+
+    Pure string work: this never reads the filesystem, which is what lets
+    `mark` run on every file write without becoming something a user turns
+    off.
+    """
+    return any(rx.match(rel_posix) for rx in _compiled(pattern))