constant-docs 0.4.0__py3-none-any.whl

constant_docs/checks.py

@@ -0,0 +1,494 @@
+"""Checks that read a document's body against the repository it describes.
+
+Everything else in this tool compares a hash. That answers *"has the source
+moved under this prose"* and nothing at all about whether the prose is right.
+For most documents nothing better is available without parsing source, which is
+a settled no.
+
+For a few, something better is. This module holds those cases, and the rule for
+admitting one is that the check must be **decidable from facts the tool already
+has** — the configuration, the file list, a string scan — never from
+understanding the prose.
+
+## The architecture diagram
+
+An architecture document carries a Mermaid diagram of how the parts fit
+together. It is the model's reading of the code, not something derived from it:
+this package parses no source, so the picture is prose in another form and
+looks considerably more authoritative than it has earned.
+
+One guard is available and costs nothing, and it catches the way these actually
+rot — a module renamed or removed while the picture still shows the old name.
+**Every module named in the diagram must exist in the configuration.**
+
+A diagram also has to show things that are not modules: a harness, a
+filesystem, a person. So the claim is marked rather than inferred — a **quoted**
+node label names a module and is checked; an unquoted one is free structure.
+That keeps an honest picture drawable and keeps the guard from becoming a
+reason to draw a dishonest one.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from constant_docs.document import DocumentCache, DocumentError
+from constant_docs.kinds import ARCHITECTURE_CHECK, ERRORS_CHECK
+from constant_docs.paths import doc_path_for
+
+_FENCE_RE = re.compile(
+    r"^```([A-Za-z0-9_-]*)[^\S\n]*\n(.*?)^```", re.MULTILINE | re.DOTALL
+)
+
+# `cli["cli"]`, `cli("cli")`, `cli{"cli"}` — a quoted label in any node shape.
+_QUOTED_LABEL_RE = re.compile(r"[\[\(\{]+\s*\"([^\"\n]*)\"\s*[\]\)\}]+")
+
+_HEADER_RE = re.compile(r"^(graph|flowchart)\s+(TB|TD|BT|RL|LR)\s*$")
+
+# Every edge form Mermaid's flowchart grammar spells with dashes or equals.
+_EDGE_RE = re.compile(r"-\.->|-\.-|<-->|-{2,3}>|={2,3}>|-{2,3}|={2,3}")
+_EDGE_LABEL_RE = re.compile(r"\|[^|\n]*\|")
+_NODE_DECL_RE = re.compile(r"^\s*([A-Za-z_][\w-]*)\s*[\[\(\{]")
+_BARE_ID_RE = re.compile(r"^([A-Za-z_][\w-]*)$")
+
+# Mermaid's own vocabulary, which a bare-identifier match cannot tell from a
+# node. `end` closes a `subgraph` and is a reserved word, so it can never be
+# declared: a diagram using a subgraph was refused with advice — `end["..."]`
+# — that is not writable in Mermaid at all.
+_MERMAID_KEYWORDS = frozenset(
+    {"end", "subgraph", "graph", "flowchart", "direction", "click", "style"}
+)
+
+_BRACKETS = {"[": "]", "(": ")", "{": "}"}
+
+
+class DiagramError(DocumentError):
+    """An architecture diagram names a module that is not configured.
+
+    A `DocumentError` because the consequence is the same as a missing required
+    heading: the body is refused and the document on disk is left as it was.
+    """
+
+
+def _mermaid_blocks(body: str) -> list[str]:
+    """Return the contents of every fenced block tagged `mermaid`."""
+    return [
+        content
+        for language, content in _FENCE_RE.findall(body)
+        if language == "mermaid"
+    ]
+
+
+def diagram_labels(body: str) -> list[str]:
+    """Return every quoted node label in *body*'s Mermaid diagrams, sorted.
+
+    Quoted because a diagram must be able to show a harness or a filesystem
+    without claiming it is a module. Marking the claim rather than inferring it
+    is what keeps the guard from making an honest picture undrawable.
+    """
+    found: set[str] = set()
+    for block in _mermaid_blocks(body):
+        found.update(label.strip() for label in _QUOTED_LABEL_RE.findall(block))
+    return sorted(f for f in found if f)
+
+
+def unknown_modules(labels: list[str], known: list[str]) -> list[str]:
+    """Return the labels that name no configured module, sorted.
+
+    A label matches a module key exactly, or matches the last path segment of
+    exactly one key — full keys are long and an unreadable diagram is not a
+    diagram. A segment shared by two keys names neither, and reporting it is
+    the same reasoning that makes `probable_move` list every candidate rather
+    than pick one.
+    """
+    keys = set(known)
+    by_segment: dict[str, int] = {}
+    for key in known:
+        by_segment[key.rstrip("/").split("/")[-1]] = (
+            by_segment.get(key.rstrip("/").split("/")[-1], 0) + 1
+        )
+    out = []
+    for raw in labels:
+        label = raw.strip().strip('"')
+        if label in keys:
+            continue
+        if by_segment.get(label) == 1:
+            continue
+        out.append(label)
+    return sorted(set(out))
+
+
+def diagram_problems(body: str) -> list[str]:
+    """Return the structural problems in *body*'s Mermaid diagrams.
+
+    Ours, not Mermaid's. A real parser is a JavaScript dependency and this
+    package takes one runtime dependency in total, so this checks the things
+    that actually stop a diagram rendering — a missing or unknown header, an
+    unclosed bracket or quote, an edge to a node that is never given a label —
+    and claims nothing beyond them.
+    """
+    blocks = _mermaid_blocks(body)
+    if not blocks:
+        return [
+            (
+                "no Mermaid diagram: an architecture document carries one, in "
+                "a fenced block tagged `mermaid`"
+            )
+        ]
+
+    problems: list[str] = []
+    for block in blocks:
+        lines = [line for line in block.splitlines() if line.strip()]
+        if not lines:
+            problems.append("empty Mermaid block")
+            continue
+        header = lines[0].strip()
+        if not _HEADER_RE.match(header):
+            problems.append(
+                f"diagram header {header!r} is not a `graph` or `flowchart` "
+                f"with a direction (TB, TD, BT, RL, LR)"
+            )
+            continue
+
+        declared: set[str] = set()
+        referenced: set[str] = set()
+        for line in lines[1:]:
+            problems.extend(_unbalanced(line))
+            stripped = _EDGE_LABEL_RE.sub(" ", line)
+            for fragment in _EDGE_RE.split(stripped):
+                fragment = fragment.strip()
+                if not fragment:
+                    continue
+                declaration = _NODE_DECL_RE.match(fragment)
+                if declaration:
+                    declared.add(declaration.group(1))
+                    continue
+                bare = _BARE_ID_RE.match(fragment)
+                if bare and bare.group(1) not in _MERMAID_KEYWORDS:
+                    referenced.add(bare.group(1))
+
+        for node in sorted(referenced - declared):
+            problems.append(
+                f"node {node!r} is joined by an edge but never given a label; "
+                f'declare it once as {node}["..."]'
+            )
+    return problems
+
+
+def _unbalanced(line: str) -> list[str]:
+    """Return a problem for *line* if its quotes or brackets do not close.
+
+    Counted rather than parsed, so a bracket inside a label reads as an
+    imbalance. That is a false positive on a label nobody should be writing,
+    and the alternative is a Mermaid grammar in this file.
+    """
+    if line.count('"') % 2:
+        return [f"unbalanced quote: {line.strip()!r}"]
+    stack: list[str] = []
+    for char in line:
+        if char in _BRACKETS:
+            stack.append(_BRACKETS[char])
+        elif char in _BRACKETS.values() and (not stack or stack.pop() != char):
+            return [f"unbalanced bracket: {line.strip()!r}"]
+    if stack:
+        return [f"unbalanced bracket: {line.strip()!r}"]
+    return []
+
+
+def check_body(body: str, known: list[str]) -> list[str]:
+    """Return every problem with an architecture body, structural then naming."""
+    problems = diagram_problems(body)
+    unknown = unknown_modules(diagram_labels(body), known)
+    if unknown:
+        problems.append(
+            "the diagram names "
+            + ("a module" if len(unknown) == 1 else "modules")
+            + " that the configuration does not have: "
+            + ", ".join(unknown)
+            + ". A picture still showing a renamed module is the way these "
+            "documents rot."
+        )
+    return problems
+
+
+def check_documents(
+    cfg: Any,
+    repo_root: Path,
+    check_name: str,
+    problems_for: Callable[[Any, str], list[str]],
+    cache: DocumentCache | None = None,
+) -> list[str]:
+    """Return the issues in every document whose kind declares *check_name*.
+
+    One sweep for both checks. The module loop, the missing-document skip, the
+    malformed-document skip and the message shape were written out twice and
+    had to agree by hand; a third checked kind would have written them a third
+    time, and a change to the shared policy had to be made in every copy or it
+    quietly applied to one kind only.
+
+    Selected by the kind's `check` field rather than by its name, so a project
+    that declares its own architecture kind keeps the guard instead of silently
+    losing it.
+
+    Reported rather than raised: `verify` names everything wrong in one run,
+    and a check that stopped at the first would need running as many times as
+    there are problems.
+    """
+    read = (cache or DocumentCache()).load
+    issues: list[str] = []
+    for mod in cfg.modules:
+        kind = cfg.kinds.get(mod.kind)
+        if kind is None or kind.check != check_name:
+            continue
+        path = repo_root / doc_path_for(cfg, mod.key)
+        if not path.exists():
+            # A missing document is already reported as missing; saying so
+            # twice would make one problem look like two.
+            continue
+        try:
+            body = read(path).body
+        except (OSError, DocumentError, ValueError):
+            # Likewise: a malformed document is reported by the conformance
+            # check, which is where a reader will look for it.
+            continue
+        issues.extend(
+            f"{path.relative_to(repo_root).as_posix()} — {problem}"
+            for problem in problems_for(mod, body)
+        )
+    return issues
+
+
+def check_architecture(
+    cfg: Any, repo_root: Path, cache: DocumentCache | None = None
+) -> list[str]:
+    """Return the issues in every architecture document, for `verify`."""
+    known = [m.key for m in cfg.modules]
+    return check_documents(
+        cfg,
+        repo_root,
+        ARCHITECTURE_CHECK,
+        lambda _mod, body: check_body(body, known),
+        cache=cache,
+    )
+
+
+# ---------------------------------------------------------------------------
+# The error catalogue
+# ---------------------------------------------------------------------------
+#
+# The one document this tool produces that can be verified in both directions:
+# every error the source can raise appears in the catalogue, and every entry in
+# the catalogue still exists in the source. Everything else it generates is
+# unchecked prose that happens to be fresh.
+#
+# Neither direction needs parsing beyond a string scan — no AST, which stays a
+# settled no — so it costs nothing and it holds. Built with the document rather
+# than after it: a catalogue that is merely generated is prose, and a catalogue
+# that is checked is a guarantee.
+
+# `raise SomeError(` — the class name capitalised, which every exception in
+# this codebase and the standard library is. A bare `raise` re-raises and emits
+# no message of its own, so it is not a site.
+_RAISE_RE = re.compile(r"\braise\s+([A-Z][A-Za-z0-9_]*)\s*\(")
+
+# A quoted literal inside a message region. Prefixes cover f- and raw strings.
+# A quoted literal inside a message region. Prefixes cover f- and raw strings.
+# `\\.` before the delimiter alternative is what makes an escaped quote part of
+# the string rather than its end: without it, `"expected \\"a\\" here"` was read
+# as two literals and the catalogue was asked to match text no reader sees.
+_LITERAL_RE = re.compile(
+    r"(?:[fFrRbB]{0,2})(\"\"\"|'''|\"|')((?:\\.|(?!\1)[\s\S])*?)\1"
+)
+
+# The escapes a message actually carries. Undone so the catalogue compares
+# against what the reader sees, not the bytes the source spells it with.
+_ESCAPE_RE = re.compile(r"\\([\\'\"])")
+
+# The first cell of a table row, backticked. Marking the fragment by position
+# rather than by syntax keeps every other backtick in the document — a flag, a
+# filename, a class — from becoming a claim about the source.
+_FRAGMENT_RE = re.compile(r"^\|\s*`([^`\n]+)`\s*\|", re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class RaiseSite:
+    """One `raise X(...)` with a literal message, and where it is."""
+
+    exception: str
+    message: str
+    line: int
+
+
+def raise_sites(text: str) -> list[RaiseSite]:
+    """Return every raise site in *text* that carries a literal message.
+
+    A site whose message is built elsewhere — `raise SomeError(message)` — is
+    not returned: there is no string to catalogue, and demanding one would
+    make the check unsatisfiable rather than useful.
+    """
+    out: list[RaiseSite] = []
+    for match in _RAISE_RE.finditer(text):
+        region = _balanced(text, match.end() - 1)
+        if region is None:
+            continue
+        literals = _message_literals(region)
+        if not literals:
+            continue
+        out.append(
+            RaiseSite(
+                exception=match.group(1),
+                # Joined, because a long message is written as adjacent string
+                # literals across several lines and a fragment may span the
+                # join. The space is what the reader sees at the seam.
+                message=" ".join(literals),
+                line=text.count("\n", 0, match.start()) + 1,
+            )
+        )
+    return out
+
+
+def _message_literals(region: str) -> list[str]:
+    """Return the literals in *region* that are part of the message.
+
+    A literal whose preceding non-space character is `=` is a keyword
+    argument — `key="modules"`, `from_=x` — and naming one in the catalogue
+    would let a row match on a word the user never sees. Excluding them also
+    means a raise whose message is built elsewhere and whose only literal is a
+    keyword argument is correctly not a site at all.
+    """
+    out: list[str] = []
+    for match in _LITERAL_RE.finditer(region):
+        before = region[: match.start()].rstrip()
+        if before.endswith("=") and not before.endswith(("==", "!=", "<=", ">=")):
+            continue
+        out.append(_ESCAPE_RE.sub(r"\1", match.group(2)))
+    return out
+
+
+def _balanced(text: str, open_paren: int) -> str | None:
+    """Return the text between *open_paren* and its matching close, or None.
+
+    Counted rather than parsed, and quote-aware only enough to survive a
+    parenthesis inside a message.
+    """
+    depth = 0
+    quote: str | None = None
+    i = open_paren
+    while i < len(text):
+        char = text[i]
+        if quote:
+            if char == "\\":
+                # Skip the backslash *and* what it escapes. Advancing by one
+                # left the escaped character to be examined on the next pass,
+                # so `\")` closed the string early and the argument region came
+                # back truncated — a message the source never raises.
+                i += 2
+                continue
+            if text.startswith(quote, i):
+                i += len(quote)
+                quote = None
+                continue
+            i += 1
+            continue
+        if char in "\"'":
+            quote = '"""' if text.startswith('"""', i) else char
+            quote = "'''" if text.startswith("'''", i) else quote
+            i += len(quote)
+            continue
+        if char == "(":
+            depth += 1
+        elif char == ")":
+            depth -= 1
+            if depth == 0:
+                return text[open_paren + 1 : i]
+        i += 1
+    return None
+
+
+def catalogue_fragments(body: str) -> list[str]:
+    """Return the message fragments an errors document claims, sorted."""
+    return sorted({f.strip() for f in _FRAGMENT_RE.findall(body) if f.strip()})
+
+
+def _normalise(text: str) -> str:
+    """Collapse whitespace, so a message wrapped across lines still matches."""
+    return " ".join(text.split())
+
+
+def check_catalogue(body: str, sources: list[tuple[str, str]]) -> list[str]:
+    """Return what the catalogue and the source disagree about, both ways.
+
+    *sources* is (repository-relative path, text) for every file the errors
+    document covers.
+
+    Reworded messages fail both directions at once and are reported twice,
+    deliberately: the entry that no longer matches anything and the site that
+    nothing covers are two separate things to fix, and collapsing them would
+    hide whichever the author did not think of.
+    """
+    fragments = catalogue_fragments(body)
+    normalised = [(f, _normalise(f)) for f in fragments]
+
+    problems: list[str] = []
+    matched: set[str] = set()
+
+    for path, text in sources:
+        for site in raise_sites(text):
+            message = _normalise(site.message)
+            hits = [raw for raw, needle in normalised if needle in message]
+            if hits:
+                matched.update(hits)
+                continue
+            problems.append(
+                f"{path}:{site.line} raises {site.exception} with a message the "
+                f"catalogue does not carry: {_shorten(message)}"
+            )
+
+    for fragment in fragments:
+        if fragment not in matched:
+            problems.append(
+                f"the catalogue carries {fragment!r}, which no error in the "
+                f"source raises any more"
+            )
+    return problems
+
+
+def _shorten(text: str, limit: int = 80) -> str:
+    """Return *text* short enough to read in a terminal, quoted."""
+    return repr(text if len(text) <= limit else text[: limit - 1] + "…")
+
+
+class CatalogueError(DocumentError):
+    """An error catalogue does not agree with the source, in either direction."""
+
+
+def check_errors(
+    cfg: Any, repo_root: Path, cache: DocumentCache | None = None
+) -> list[str]:
+    """Return the completeness issues in every errors document, for `verify`."""
+    return check_documents(
+        cfg,
+        repo_root,
+        ERRORS_CHECK,
+        lambda mod, body: check_catalogue(body, sources_for(cfg, repo_root, mod.key)),
+        cache=cache,
+    )
+
+
+def sources_for(cfg: Any, repo_root: Path, module_key: str) -> list[tuple[str, str]]:
+    """Return (relative path, text) for every file a module covers.
+
+    Only files that can be read as text, because a module glob may legitimately
+    take in an image or a lockfile and neither raises anything.
+    """
+    out: list[tuple[str, str]] = []
+    for rel in cfg.module_files.get(module_key, []):
+        try:
+            out.append((rel.as_posix(), (repo_root / rel).read_text(encoding="utf-8")))
+        except (OSError, UnicodeDecodeError):
+            continue
+    return out