adr-check 0.1.0__py3-none-any.whl

adr_check/__init__.py

@@ -0,0 +1 @@
+"""Checks architecture decision records (ADRs) against the ADR rules."""

adr_check/adr.py

@@ -0,0 +1,334 @@
+"""Parse ADR files and run the checks that need only the files in front of you."""
+
+import re
+from collections import defaultdict
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+import yaml
+
+STATUSES = ("proposed", "accepted", "rejected", "superseded")
+KEYS = ("status", "date", "supersedes", "superseded_by")
+SECTIONS = ("Context", "Considered options", "Decision", "Consequences")
+
+_FILENAME = re.compile(r"^(\d{4})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$")
+_H1 = re.compile(r"^(\d{4})\. \S")
+_ISO_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class Meta:
+    """Validated frontmatter of one ADR."""
+
+    status: str
+    date: date
+    supersedes: tuple[int, ...]
+    superseded_by: int | None
+
+
+@dataclass(frozen=True)
+class AdrFile:
+    """One ADR file, parsed as far as it parses.
+
+    `number` comes from the filename and is None when the name is not `NNNN-kebab-title.md`.
+    `raw` is the frontmatter as written, and `meta` is None when it failed validation.
+    """
+
+    path: str
+    name: str
+    number: int | None
+    raw: dict[str, object] | None
+    meta: Meta | None
+    body: str
+
+
+Resolver = Callable[[AdrFile, int, str], AdrFile | None]
+
+
+def is_candidate(name: str) -> bool:
+    """Return whether a file in the ADR directory is meant to be an ADR.
+
+    The directory may also hold a README or other non-Markdown files. Every other Markdown file is
+    checked, so a badly named ADR fails rather than being ignored.
+    """
+    return name.endswith(".md") and name.lower() != "readme.md"
+
+
+def number_of(name: str) -> int | None:
+    """Return the number in an ADR filename, or None if the name is not well formed."""
+    match = _FILENAME.match(name)
+    return int(match.group(1)) if match else None
+
+
+def slug_of(name: str) -> str | None:
+    """Return the kebab-case title in an ADR filename, or None if the name is not well formed."""
+    match = _FILENAME.match(name)
+    return match.group(2) if match else None
+
+
+def split_document(text: str) -> tuple[str | None, str]:
+    """Split a document into its frontmatter text and body.
+
+    The frontmatter is None when the file does not open with a closed `---` block.
+    """
+    lines = text.replace("\r\n", "\n").split("\n")
+    if lines[0].rstrip() != "---":
+        return None, "\n".join(lines)
+    for index in range(1, len(lines)):
+        if lines[index].rstrip() == "---":
+            return "\n".join(lines[1:index]), "\n".join(lines[index + 1 :])
+    return None, "\n".join(lines)
+
+
+def _is_int(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _validate_meta(raw: dict[str, object]) -> tuple[Meta | None, list[str]]:
+    problems: list[str] = []
+    for key in KEYS:
+        if key not in raw:
+            problems.append(f"frontmatter is missing the key `{key}`")
+    problems.extend(
+        f"frontmatter has the key `{key}`, which is not one of {', '.join(KEYS)}"
+        for key in raw
+        if key not in KEYS
+    )
+    if problems:
+        return None, problems
+
+    status = raw["status"]
+    if status not in STATUSES:
+        problems.append(f"`status` must be one of {', '.join(STATUSES)}, not {status!r}")
+
+    raw_date = raw["date"]
+    parsed: date | None = None
+    if type(raw_date) is date:
+        parsed = raw_date
+    elif isinstance(raw_date, str) and _ISO_DATE.match(raw_date):
+        try:
+            parsed = date.fromisoformat(raw_date)
+        except ValueError:
+            parsed = None
+    if parsed is None:
+        problems.append(f"`date` must be an ISO date such as 2026-03-12, not {raw_date!r}")
+
+    raw_supersedes = raw["supersedes"]
+    supersedes: tuple[int, ...] = ()
+    if raw_supersedes is None:
+        pass
+    elif isinstance(raw_supersedes, list) and all(_is_int(item) for item in raw_supersedes):
+        supersedes = tuple(item for item in raw_supersedes if isinstance(item, int))
+    else:
+        problems.append("`supersedes` must be a list of ADR numbers such as [7], or empty")
+
+    superseded_by = raw["superseded_by"]
+    if superseded_by is not None and not _is_int(superseded_by):
+        problems.append("`superseded_by` must be one ADR number such as 15, or empty")
+
+    if problems or parsed is None or not isinstance(status, str):
+        return None, problems
+    by = superseded_by if isinstance(superseded_by, int) else None
+    return Meta(status, parsed, supersedes, by), []
+
+
+_FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$")
+_COMMENT_START = re.compile(r"^ {0,3}<!--")
+
+
+def _headings(body: str) -> list[tuple[int, str]]:
+    headings: list[tuple[int, str]] = []
+    fence: tuple[str, int] | None = None
+    in_comment = False
+    for line in body.split("\n"):
+        if in_comment:
+            # CommonMark: an HTML comment block runs to the first line holding `-->`, or to EOF.
+            in_comment = "-->" not in line
+            continue
+        if fence is None and _COMMENT_START.match(line):
+            in_comment = "-->" not in line[line.index("<!--") :]
+            continue
+        line = _COMMENT.sub("", line)
+        match = _FENCE.match(line)
+        if match:
+            run, rest = match.groups()
+            if fence is None:
+                # CommonMark: a backtick fence's info string cannot hold a backtick.
+                if run[0] != "`" or "`" not in rest:
+                    fence = (run[0], len(run))
+                continue
+            if run[0] == fence[0] and len(run) >= fence[1] and not rest.strip():
+                fence = None
+                continue
+        if fence:
+            continue
+        heading = re.match(r"^(#{1,6}) +(.*?) *#*$", line)
+        if heading:
+            headings.append((len(heading.group(1)), heading.group(2)))
+    return headings
+
+
+def parse_text(path: str, text: str) -> tuple[AdrFile, list[str]]:
+    """Parse one ADR and return it with the problems found in that file alone."""
+    name = path.rsplit("/", 1)[-1]
+    number = number_of(name)
+    problems: list[str] = []
+    if number is None:
+        problems.append("filename must look like NNNN-kebab-title.md, for example 0007-use-x.md")
+
+    front, body = split_document(text)
+    raw: dict[str, object] | None = None
+    meta: Meta | None = None
+    if front is None:
+        problems.append("file must open with a frontmatter block between `---` lines")
+    else:
+        try:
+            loaded: object = yaml.safe_load(front)
+        except (yaml.YAMLError, ValueError, OverflowError) as error:
+            # PyYAML raises ValueError for an unquoted impossible date such as 2026-02-30.
+            loaded = None
+            problems.append(f"frontmatter is not valid YAML: {str(error).partition('\n')[0]}")
+        else:
+            if isinstance(loaded, dict) and all(isinstance(key, str) for key in loaded):
+                raw = {str(key): value for key, value in loaded.items()}
+                meta, meta_problems = _validate_meta(raw)
+                problems.extend(meta_problems)
+            else:
+                problems.append("frontmatter must be a mapping of the four keys")
+
+    problems.extend(_check_body(number, body))
+    return AdrFile(path, name, number, raw, meta, body), [f"{path}: {p}" for p in problems]
+
+
+def _check_body(number: int | None, body: str) -> list[str]:
+    problems: list[str] = []
+    headings = _headings(body)
+    h1s = [text for level, text in headings if level == 1]
+    if not h1s:
+        problems.append("missing the H1 title, for example `# 0007. Use managed identities`")
+    else:
+        match = _H1.match(h1s[0])
+        if not match:
+            problems.append(f"H1 must look like `# 0007. Title`, not `# {h1s[0]}`")
+        elif number is not None and int(match.group(1)) != number:
+            problems.append(
+                f"H1 number {match.group(1)} does not match filename number {number:04d}"
+            )
+    present = {text for level, text in headings if level == 2}
+    problems.extend(f"missing the `## {s}` section" for s in SECTIONS if s not in present)
+    return problems
+
+
+def load_tree(adr_dir: Path, display_dir: str) -> tuple[list[AdrFile], list[str]]:
+    """Read every ADR in `adr_dir` and return them with the per-file problems."""
+    files: list[AdrFile] = []
+    problems: list[str] = []
+    if not adr_dir.is_dir():
+        return files, problems
+    for entry in sorted(adr_dir.iterdir()):
+        path = f"{display_dir}/{entry.name}"
+        if entry.is_symlink() and is_candidate(entry.name):
+            problems.append(f"{path}: is a symlink. An ADR must be a regular file")
+            continue
+        if not entry.is_file() or not is_candidate(entry.name):
+            continue
+        try:
+            text = entry.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            problems.append(f"{path}: file is not valid UTF-8")
+            continue
+        adr, found = parse_text(path, text)
+        files.append(adr)
+        problems.extend(found)
+    return files, problems
+
+
+def check_tree(files: list[AdrFile]) -> list[str]:
+    """Check numbering and supersession across every ADR in the working tree."""
+    problems: list[str] = []
+    by_number: dict[int, list[AdrFile]] = defaultdict(list)
+    for adr in files:
+        if adr.number is not None:
+            by_number[adr.number].append(adr)
+    duplicated = {n for n, group in by_number.items() if len(group) > 1}
+    for number in sorted(duplicated):
+        names = ", ".join(adr.name for adr in by_number[number])
+        problems.append(f"{number:04d} is used by more than one ADR: {names}")
+
+    def resolve(adr: AdrFile, target: int, field: str) -> AdrFile | None:
+        if target in duplicated:
+            problems.append(
+                f"{adr.path}: `{field}` names {target:04d}, which is a duplicated number, "
+                "so it is ambiguous"
+            )
+            return None
+        if target not in by_number:
+            problems.append(f"{adr.path}: `{field}` names {target:04d}, which does not exist")
+            return None
+        return by_number[target][0]
+
+    for adr in files:
+        meta = adr.meta
+        if meta is None or adr.number is None:
+            continue
+        for target in meta.supersedes:
+            _check_predecessor(adr, adr.number, target, resolve, problems)
+        _check_successor(adr, adr.number, meta, resolve, problems)
+    return problems
+
+
+def _check_predecessor(
+    adr: AdrFile, number: int, target: int, resolve: Resolver, problems: list[str]
+) -> None:
+    if target == number:
+        problems.append(f"{adr.path}: `supersedes` names the ADR itself")
+        return
+    old = resolve(adr, target, "supersedes")
+    if old is None or old.meta is None:
+        return
+    if old.meta.status != "superseded" or old.meta.superseded_by != number:
+        problems.append(
+            f"{adr.path}: supersedes {target:04d}, but {old.name} must have `status: superseded` "
+            f"and `superseded_by: {number}`"
+        )
+
+
+def _check_successor(
+    adr: AdrFile, number: int, meta: Meta, resolve: Resolver, problems: list[str]
+) -> None:
+    if meta.status == "superseded" and meta.superseded_by is None:
+        problems.append(f"{adr.path}: `status: superseded` needs `superseded_by`")
+    if meta.superseded_by is None:
+        return
+    if meta.status != "superseded":
+        problems.append(
+            f"{adr.path}: `superseded_by` is set, so `status` must be `superseded`, "
+            f"not `{meta.status}`"
+        )
+    if meta.superseded_by == number:
+        problems.append(f"{adr.path}: `superseded_by` names the ADR itself")
+        return
+    successor = resolve(adr, meta.superseded_by, "superseded_by")
+    if successor is None or successor.meta is None:
+        return
+    if successor.meta.status == "rejected":
+        problems.append(
+            f"{adr.path}: superseded by {successor.name}, which is rejected. A rejected ADR "
+            "leaves the ADR it proposed to replace untouched"
+        )
+    if number not in successor.meta.supersedes:
+        problems.append(
+            f"{adr.path}: superseded by {successor.name}, whose `supersedes` must include {number}"
+        )
+
+
+def check_no_proposed(files: list[AdrFile]) -> list[str]:
+    """Fail every ADR still `proposed`, for a run that merges to main."""
+    return [
+        f"{adr.path}: `status: proposed` cannot reach main. Set accepted, rejected or superseded"
+        for adr in files
+        if adr.meta is not None and adr.meta.status == "proposed"
+    ]

adr_check/ci.py

@@ -0,0 +1,234 @@
+"""Checks that compare the working tree with the base branch."""
+
+import re
+import subprocess
+from collections import defaultdict
+from collections.abc import Collection
+from pathlib import Path
+
+from adr_check.adr import (
+    AdrFile,
+    is_candidate,
+    number_of,
+    parse_text,
+    slug_of,
+)
+
+CORRECTION_LABEL = "adr-correction"
+
+
+class BaseRefError(Exception):
+    """The base ref cannot be used, so the history checks cannot run."""
+
+
+def _git(repo: Path, *args: str, errors: str = "strict") -> str:
+    result = subprocess.run(  # noqa: S603  # fixed git binary, arguments are not shell-parsed
+        ["git", "-C", str(repo), *args],  # noqa: S607  # git is resolved from PATH on purpose
+        capture_output=True,
+        encoding="utf-8",
+        errors=errors,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise BaseRefError(result.stderr.strip() or f"git {args[0]} failed")
+    return result.stdout
+
+
+def repo_root() -> Path:
+    """Return the top of the git repository containing the current directory."""
+    try:
+        return Path(_git(Path.cwd(), "rev-parse", "--show-toplevel").strip())
+    except BaseRefError as error:
+        raise BaseRefError("not inside a git repository, which ci mode needs") from error
+
+
+def _numbers_at(repo: Path, rev: str, rel_dir: str) -> dict[int, list[str]]:
+    out = _git(repo, "ls-tree", "--name-only", "-z", rev, f"{rel_dir}/")
+    numbers: dict[int, list[str]] = defaultdict(list)
+    for path in out.split("\0"):
+        name = path.rsplit("/", 1)[-1]
+        number = number_of(name)
+        if number is not None:
+            numbers[number].append(name)
+    return numbers
+
+
+def _is_top_level(path: str, rel_dir: str) -> bool:
+    """Return whether `path` is directly in the ADR directory, as `load_tree` reads it."""
+    return Path(path).parent == Path(rel_dir)
+
+
+def _changes(repo: Path, base_ref: str, rel_dir: str) -> list[tuple[str, str, str]]:
+    """Return (status letter, old path, new path) for each changed ADR candidate."""
+    out = _git(repo, "diff", "--name-status", "-M", "-z", f"{base_ref}...HEAD", "--", f"{rel_dir}/")
+    tokens = out.split("\0")
+    changes: list[tuple[str, str, str]] = []
+    index = 0
+    while index < len(tokens) and tokens[index]:
+        letter = tokens[index][0]
+        width = 2 if letter in "RC" else 1
+        paths = tokens[index + 1 : index + 1 + width]
+        index += 1 + width
+        old, new = paths[0], paths[-1]
+        in_old, in_new = _is_top_level(old, rel_dir), _is_top_level(new, rel_dir)
+        if in_old and not in_new:
+            letter, new = "D", old  # moved into a subdirectory: the ADR is gone from the list
+        elif in_new and not in_old:
+            letter, old = "A", new  # moved out of a subdirectory: it is a new ADR
+        elif not in_old:
+            continue
+        if is_candidate(old.rsplit("/", 1)[-1]) or is_candidate(new.rsplit("/", 1)[-1]):
+            changes.append((letter, old, new))
+    return changes
+
+
+def _show(repo: Path, rev: str, path: str) -> AdrFile:
+    # load_tree reports a file that is not UTF-8, so compare a best-effort decoding here.
+    adr, _ = parse_text(path, _git(repo, "show", f"{rev}:{path}", errors="replace"))
+    return adr
+
+
+def _as_list(value: object) -> list[object]:
+    if value is None:
+        return []
+    return list(value) if isinstance(value, list) else [value]
+
+
+def _is_retarget(old: object, new: object, renumbered: dict[int, int]) -> bool:
+    """Return whether `new` only repoints renumbered ADRs in `old` at their new numbers."""
+    before, after = _as_list(old), _as_list(new)
+    if len(before) != len(after):
+        return False
+    return all(
+        b == a or (isinstance(b, int) and renumbered.get(b) == a)
+        for b, a in zip(before, after, strict=True)
+    )
+
+
+def _frontmatter_change_allowed(
+    old: dict[str, object], new: dict[str, object], renumbered: dict[int, int]
+) -> bool:
+    keys = old.keys() | new.keys()
+    flip_keys = {"status", "superseded_by"}
+    rest_same = all(old.get(k) == new.get(k) for k in keys - flip_keys)
+    if (
+        rest_same
+        and old.get("status") == "accepted"
+        and new.get("status") == "superseded"
+        and old.get("superseded_by") is None
+        and isinstance(new.get("superseded_by"), int)
+    ):
+        return True
+    pointer_keys = {"supersedes", "superseded_by"}
+    return (
+        bool(renumbered)
+        and all(old.get(k) == new.get(k) for k in keys - pointer_keys)
+        and all(_is_retarget(old.get(k), new.get(k), renumbered) for k in pointer_keys)
+    )
+
+
+def _renumber_problems(old: AdrFile, new: AdrFile, mb_numbers: dict[int, list[str]]) -> list[str]:
+    """Return why a rename is not the renumbering repair, or nothing when it is."""
+    if old.number is None or new.number is None:
+        return [f"{new.path}: renamed from {old.path}, which is not an ADR rename the check allows"]
+    where = f"{new.path}: renamed from {old.name}"
+    if old.number == new.number or slug_of(old.name) != slug_of(new.name):
+        return [f"{where}. Only the number in the filename may change, and ADRs are never renamed"]
+    if len(mb_numbers.get(old.number, [])) < 2:
+        return [f"{where}, but {old.number:04d} is not a duplicated number on main"]
+    if old.raw is None or new.raw is None or old.raw != new.raw:
+        return [f"{where}. A renumbering repair changes no frontmatter"]
+    renumbered = re.sub(
+        rf"^# {old.number:04d}\.", f"# {new.number:04d}.", old.body, count=1, flags=re.MULTILINE
+    )
+    if renumbered != new.body:
+        return [f"{where}. A renumbering repair changes only the H1 number"]
+    return []
+
+
+def check_against_base(
+    repo: Path,
+    rel_dir: str,
+    base_ref: str,
+    labels: Collection[str],
+) -> list[str]:
+    """Compare the ADRs in HEAD with `base_ref` and return every rule they break.
+
+    Raises:
+        BaseRefError: `base_ref` is missing or shares no history with HEAD.
+    """
+    try:
+        _git(repo, "rev-parse", "--verify", "--quiet", f"{base_ref}^{{commit}}")
+    except BaseRefError as error:
+        raise BaseRefError(
+            f"base ref {base_ref!r} not found. Check out the caller repo with `fetch-depth: 0` "
+            "so the base branch is available"
+        ) from error
+    try:
+        merge_base = _git(repo, "merge-base", base_ref, "HEAD").strip()
+    except BaseRefError as error:
+        raise BaseRefError(
+            f"HEAD and {base_ref!r} share no history. Check out with `fetch-depth: 0`"
+        ) from error
+
+    tip_numbers = _numbers_at(repo, base_ref, rel_dir)
+    mb_numbers = _numbers_at(repo, merge_base, rel_dir)
+    changes = _changes(repo, base_ref, rel_dir)
+    problems: list[str] = []
+
+    renumbered: dict[int, int] = {}
+    for letter, old_path, new_path in changes:
+        if letter != "R":
+            continue
+        if (repo / new_path).is_symlink():
+            continue  # load_tree reports it, and reading it would follow the link
+        old, new = _show(repo, merge_base, old_path), _read(repo, new_path)
+        found = _renumber_problems(old, new, mb_numbers)
+        problems.extend(found)
+        if not found and old.number is not None and new.number is not None:
+            renumbered[old.number] = new.number
+
+    for letter, old_path, new_path in changes:
+        name = new_path.rsplit("/", 1)[-1]
+        if letter == "D":
+            problems.append(f"{old_path}: ADRs are never deleted")
+        elif letter in "AR":
+            number = number_of(name)
+            if number in tip_numbers:
+                problems.append(
+                    f"{new_path}: number {number:04d} is already used on {base_ref} by "
+                    f"{', '.join(tip_numbers[number])}. Renumber this ADR"
+                )
+        elif letter == "M" and not (repo / new_path).is_symlink():
+            problems.extend(_modified_problems(repo, merge_base, new_path, labels, renumbered))
+        if letter not in "ADRM":
+            problems.append(f"{new_path}: unexpected change type {letter!r}")
+    return problems
+
+
+def _read(repo: Path, path: str) -> AdrFile:
+    return _show(repo, "HEAD", path)
+
+
+def _modified_problems(
+    repo: Path, merge_base: str, path: str, labels: Collection[str], renumbered: dict[int, int]
+) -> list[str]:
+    old, new = _show(repo, merge_base, path), _read(repo, path)
+    if old.raw is not None and old.raw.get("status") == "proposed":
+        return []
+    if old.raw is None:
+        return [f"{path}: the version on main has unreadable frontmatter, so it cannot be compared"]
+    problems: list[str] = []
+    if old.body != new.body and CORRECTION_LABEL not in labels:
+        problems.append(
+            f"{path}: the body of an ADR on main never changes. Write a superseding ADR, or for "
+            f"a typo or link fix label the PR `{CORRECTION_LABEL}`"
+        )
+    if new.raw is not None and old.raw != new.raw:
+        if not _frontmatter_change_allowed(old.raw, new.raw, renumbered):
+            problems.append(
+                f"{path}: frontmatter of an ADR on main may change only from `accepted` to "
+                "`superseded` with `superseded_by`, or to retarget a renumbered ADR. The "
+                f"`{CORRECTION_LABEL}` label does not allow it"
+            )
+    return problems

adr_check/cli.py

@@ -0,0 +1,87 @@
+"""Command line entry point for adr-check."""
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from adr_check.adr import check_no_proposed, check_tree, load_tree
+from adr_check.ci import BaseRefError, check_against_base, repo_root
+
+DEFAULT_BASE_REF = "origin/main"
+
+
+def parse_labels(value: str) -> list[str]:
+    """Read labels from a JSON array, as `toJSON` writes them, or a comma-separated list."""
+    text = value.strip()
+    if text.startswith("["):
+        return [str(item) for item in json.loads(text)]
+    return [item.strip() for item in text.split(",") if item.strip()]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Return the argument parser for the adr-check command."""
+    parser = argparse.ArgumentParser(
+        prog="adr-check",
+        description="Check architecture decision records. Exits 1 if any rule is broken.",
+    )
+    parser.add_argument(
+        "--mode",
+        choices=("local", "ci"),
+        default="local",
+        help="local checks the working tree only; ci also compares with the base branch",
+    )
+    parser.add_argument("--adr-dir", default="docs/adr", help="ADR directory (default: docs/adr)")
+    parser.add_argument(
+        "--base-ref",
+        help=f"ci only: ref to compare with (needs full history) (default: {DEFAULT_BASE_REF})",
+    )
+    parser.add_argument(
+        "--labels",
+        help="ci only: PR labels, as a JSON array or comma-separated; `adr-correction` allows a "
+        "body change",
+    )
+    parser.add_argument(
+        "--merging-to-main",
+        action="store_true",
+        help="this run is a PR into main or a push to main, so `proposed` fails",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the checks, print each problem to stderr and return the process exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    mode: str = args.mode
+    adr_dir: str = args.adr_dir.rstrip("/")
+    base_ref: str | None = args.base_ref
+    labels_arg: str | None = args.labels
+    merging: bool = args.merging_to_main
+    if mode == "local" and (base_ref or labels_arg):
+        parser.error("--base-ref and --labels need --mode ci")
+    try:
+        labels = parse_labels(labels_arg) if labels_arg else []
+    except ValueError as error:
+        parser.error(f"--labels is not a JSON array or a comma-separated list: {error}")
+
+    files, problems = load_tree(Path(adr_dir), adr_dir)
+    problems.extend(check_tree(files))
+    if merging:
+        problems.extend(check_no_proposed(files))
+    if mode == "ci":
+        try:
+            root = repo_root()
+            rel_dir = Path(adr_dir).resolve().relative_to(root.resolve()).as_posix()
+            problems.extend(check_against_base(root, rel_dir, base_ref or DEFAULT_BASE_REF, labels))
+        except (BaseRefError, ValueError) as error:
+            print(f"adr-check: {error}", file=sys.stderr)
+            return 2
+
+    for problem in problems:
+        print(problem, file=sys.stderr)
+    if problems:
+        print(f"adr-check: {len(problems)} problem(s) found", file=sys.stderr)
+        return 1
+    return 0

adr_check-0.1.0.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.5
+Name: adr-check
+Version: 0.1.0
+Summary: Checks architecture decision records (ADRs) in docs/adr
+Project-URL: Homepage, https://github.com/agentic-delivery-au/adr-check
+Project-URL: Repository, https://github.com/agentic-delivery-au/adr-check
+Project-URL: Issues, https://github.com/agentic-delivery-au/adr-check/issues
+Project-URL: Changelog, https://github.com/agentic-delivery-au/adr-check/blob/main/CHANGELOG.md
+Author: Stuart Langley
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adr,architecture-decision-records,markdown,pre-commit
+Requires-Python: >=3.14
+Requires-Dist: pyyaml==6.0.3
+Description-Content-Type: text/markdown
+
+# adr-check
+
+Checks the architecture decision records (ADRs) in a repository's `docs/adr/` directory. It keeps
+the records uniform, links superseded decisions to their replacements, and, in CI, stops anyone
+rewriting a decision that has already been merged.
+
+An ADR is a short Markdown file that records one significant decision and the reasons for it. The
+format this tool checks is a small variant of [MADR](https://adr.github.io/madr/): Michael Nygard's
+sections plus a list of the options considered.
+
+## What it checks
+
+Files in the ADR directory that are not ADRs do not fail the check. It skips `README.md` and any
+file that does not end in `.md`, and it ignores subdirectories. Every other Markdown file is
+checked, so a badly named ADR fails instead of disappearing. A symlink in place of an ADR is an
+error, because the check would otherwise validate the file it points at.
+
+### In the working tree
+
+These checks need only the files in front of you. They run in both modes.
+
+- **Filename.** `NNNN-kebab-title.md`: four digits, then lowercase words joined by hyphens, for
+  example `0007-use-managed-identities.md`.
+- **Frontmatter.** A YAML block between `---` lines holding exactly four keys, and no others:
+  - `status`: one of `proposed`, `accepted`, `rejected` or `superseded`.
+  - `date`: an ISO date such as `2026-03-12`.
+  - `supersedes`: a list of ADR numbers, such as `[7]`, or empty.
+  - `superseded_by`: one ADR number, or empty.
+- **Title.** An H1 of the form `# 0007. Title`, where the number matches the filename.
+- **Sections.** Four H2 headings: `## Context`, `## Considered options`, `## Decision` and
+  `## Consequences`. Headings inside code fences and HTML comments do not count.
+- **Supersession links.** They must agree in both directions. If `0009` supersedes `0007`, then
+  `0007` has `status: superseded` and `superseded_by: 9`. An ADR with `superseded_by` must have
+  `status: superseded`, and a `superseded` ADR must name its successor. A link to a missing ADR, to
+  the ADR itself, or to a rejected successor fails.
+- **Duplicate numbers.** Two files may not share a number. A `supersedes` or `superseded_by` that
+  names a number two ADRs share also fails, because it is ambiguous.
+
+### Against the base branch
+
+`--mode ci` adds checks that compare your branch with the branch it merges into. Merged decisions
+are a record of what the team knew at the time, so they stay put.
+
+- **Merged ADRs are immutable.** The body of an ADR on the base branch may not change, and the
+  frontmatter may change only from `accepted` to `superseded` with `superseded_by` set. A pull
+  request labelled `adr-correction` may fix a typo or a link in the body. The label does not allow a
+  frontmatter change.
+- **`proposed` ADRs may change.** A `proposed` ADR on the base branch is not settled, so these rules
+  do not protect it.
+- **No deletions or renames.** ADRs are never deleted, and never renamed. The one exception is the
+  renumbering repair. If two branches took the same number, one ADR may change its filename number
+  and its H1 number, and nothing else. ADRs that point at it may then update their `supersedes` or
+  `superseded_by` to the new number.
+- **No reused numbers.** A new ADR may not take a number the base branch already uses, including one
+  the base took after you branched.
+- **Symlinks on main need an override.** A symlinked ADR already on the base branch cannot be
+  repaired through this check. Replacing it with a regular file reports a type change, and deleting
+  it reports a deletion. Neither is allowed, and `adr-correction` lifts neither, so a person must
+  override the required check for that pull request.
+- **No `proposed` on the main branch.** With `--merging-to-main`, any ADR with `status: proposed`
+  fails. `proposed` exists only on a branch.
+
+## Usage
+
+Pick the form that suits the repository. All three run the same checks. Replace the placeholder
+versions with a current release.
+
+### Pre-commit hook
+
+The repository ships a [pre-commit](https://pre-commit.com) hook. Add it to
+`.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/agentic-delivery-au/adr-check
+    rev: vX.Y.Z
+    hooks:
+      - id: adr-check
+```
+
+The hook runs when a file under `docs/adr/` changes. It passes no filenames, because the rules look
+across the whole directory. It sets `language_version: python3.14`, because the package needs Python
+3.14 or newer and pre-commit would otherwise build it on its own interpreter. The machine needs a
+`python3.14` executable on `PATH`.
+
+If you would rather install a released package than clone this repository, use a local hook:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: adr-check
+        name: adr-check
+        entry: adr-check
+        language: python
+        language_version: python3.14
+        additional_dependencies: [adr-check==X.Y.Z]
+        files: ^docs/adr/
+        pass_filenames: false
+```
+
+The hook checks the working tree only. It cannot see the base branch, so it cannot catch an edit to
+a merged ADR, a deleted file or a number that the base branch already holds. CI catches those.
+
+### In CI
+
+Run the package from PyPI with [uv](https://docs.astral.sh/uv/). The checkout must hold the full
+history, because the check compares your branch with its base:
+
+```bash
+uvx adr-check==X.Y.Z --mode ci --base-ref origin/main --labels "$LABELS" --merging-to-main
+```
+
+On GitHub, the composite action wraps that command and fills in its inputs from the event:
+
+```yaml
+name: adr-check
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, edited, labeled, unlabeled]
+
+permissions:
+  contents: read
+
+jobs:
+  adr-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: agentic-delivery-au/adr-check@<sha> # vX.Y.Z
+```
+
+Pin the action to a full commit SHA, as you would any third-party action. Four details matter:
+
+- **`fetch-depth: 0`.** A shallow checkout has no base branch to compare with, and the action fails
+  with a message that says so.
+- **`labeled` and `unlabeled`.** Without them, adding `adr-correction` does not re-run the check,
+  and the pull request stays red until the next push.
+- **No `paths:` filter.** A filtered workflow does not report on a pull request that touches no ADR,
+  so a required check never arrives.
+- **Avoid triggering on `push`.** A push carries no pull request labels, so a history comparison
+  would fail every merged `adr-correction`. If a push does trigger the action, it runs only the
+  checks on the files and the `proposed` check.
+
+The action installs the tool from its own checkout (the files the runner fetched for `uses:`), so
+the code that runs is the code at the commit you pinned. It uses
+[astral-sh/setup-uv](https://github.com/astral-sh/setup-uv) to provide uv.
+
+#### Action inputs
+
+Every input has a default taken from the `github` context. You normally set none of them.
+
+| Input             | Default                                                                       | Purpose                                                 |
+| ----------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `adr-dir`         | `docs/adr`                                                                    | Directory that holds the ADRs                           |
+| `base-ref`        | `origin/<base branch>` on a pull request, empty on a push                     | Ref to compare with. A push ignores it                  |
+| `merging-to-main` | `true` for a pull request into the default branch or a push to it, else false | Whether `status: proposed` fails the run                |
+| `labels`          | The pull request's label names, as JSON                                       | Labels on the PR. `adr-correction` allows a body change |
+
+Set `merging-to-main` yourself only to override the default, for example in a repository whose
+release branch is not the default branch.
+
+### Command line
+
+```bash
+adr-check [--mode {local,ci}] [--adr-dir DIR] [--base-ref REF] [--labels LABELS] [--merging-to-main]
+```
+
+| Flag                | Default       | Purpose                                                               |
+| ------------------- | ------------- | --------------------------------------------------------------------- |
+| `--mode`            | `local`       | `local` checks the working tree. `ci` also compares with the base ref |
+| `--adr-dir`         | `docs/adr`    | ADR directory                                                         |
+| `--base-ref`        | `origin/main` | `ci` only. Ref to compare with. It needs full history                 |
+| `--labels`          | none          | `ci` only. PR labels as a JSON array or a comma-separated list        |
+| `--merging-to-main` | off           | Fail any ADR with `status: proposed`                                  |
+
+The command prints one line per problem to stderr. It exits 0 when every rule holds, 1 when a rule
+is broken and 2 when the base ref is missing or the directory is not in a git repository.
+
+In `ci` mode, the no-reused-numbers check compares with the tip of the base ref. The other history
+checks compare with the merge base of the base ref and `HEAD`. Git finds renames with
+`git diff --name-status -M`, which detects a rename only when the file is mostly unchanged. A
+renumbering repair always is.
+
+## Development
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then:
+
+```bash
+uv sync             # create .venv and install the package with its dev dependencies
+pre-commit install  # one-time, sets up the pre-commit and commit-msg hooks
+```
+
+`uv sync` also installs an interpreter if no suitable one is present. `requires-python` is a lower
+bound rather than a pin, so 3.14 is the floor and uv may select something newer. A project that
+needs an exact interpreter pins it in a `.python-version` file, which uv reads.
+
+| Task                       | Command                      |
+| -------------------------- | ---------------------------- |
+| Run the tests              | `uv run pytest`              |
+| Lint                       | `uv run ruff check .`        |
+| Format                     | `uv run ruff format .`       |
+| Type check                 | `uv run pyrefly check src`   |
+| Run the tool               | `uv run adr-check --help`    |
+| Everything the hooks check | `pre-commit run --all-files` |
+
+### Tests and coverage
+
+`uv run pytest` runs the suite with coverage already on, so the command above and the one
+`tests.yml` runs in CI are the same run. Coverage is measured over `src/` and reported to
+[Codecov](https://about.codecov.io). `pytest` never fails on a coverage number. The targets live in
+`codecov.yml`: the project must not regress by more than 1%, and a pull request's changed lines need
+80% coverage.
+
+Type checking names the path, `pyrefly check src`, so it skips `tests/` (deliberately unannotated)
+and `scripts/` (repository tooling that the template owns and Ruff also skips).
+
+### Repository settings
+
+`scripts/bootstrap_repo.py` applies the branch protection, merge settings and Actions permissions
+that release-please needs. It prints a plan and changes nothing until you pass `--apply`. Read the
+plan first, because it replaces an existing ruleset wholesale.
+
+```bash
+python3 scripts/bootstrap_repo.py            # what it would change
+python3 scripts/bootstrap_repo.py --apply    # change it
+```
+
+`release-please.yml` authenticates as a GitHub App, because a pull request opened with
+`GITHUB_TOKEN` triggers no workflows and the required checks would never report on the release PR.
+Create an App with Contents, Issues and Pull requests write permissions, install it on the
+repository, then store its client ID as the variable `RELEASE_BOT_CLIENT_ID` and its private key as
+the secret `RELEASE_BOT_PRIVATE_KEY`. There is deliberately no fallback to `GITHUB_TOKEN`.
+
+## Releases
+
+[release-please](https://github.com/googleapis/release-please) reads the Conventional Commits landed
+on `main` and keeps an open release PR that bumps the version and updates `CHANGELOG.md`. Merging
+that PR tags the version and publishes the GitHub release. The `publish` job in `release-please.yml`
+then builds the package and uploads it to PyPI.
+
+The release type is `python`, so release-please bumps the version in `pyproject.toml`, and an
+`extra-files` entry keeps the project's own version in `uv.lock` in step. Without it the release PR
+would fail `uv sync --locked`. The filter matches the package by name (`adr-check`), so rename the
+package and it has to change in the same commit.
+
+Tags have no component prefix (`v0.2.0`, not `adr-check-v0.2.0`), because `include-component-in-tag`
+is `false`.
+
+### Publishing
+
+The `publish` job uses [trusted publishing](https://docs.pypi.org/trusted-publishers/), so no PyPI
+token is stored. Register a trusted publisher on PyPI for this repository with the workflow name
+`release-please.yml` and the environment `pypi`, and create a `pypi` environment on GitHub. Renaming
+either side breaks the match.
+
+## Licence
+
+[MIT](LICENSE).

adr_check-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+adr_check/__init__.py,sha256=2psc3BBitujve3D73P90W8djdeRHJ2pmOC6BcxTvlAQ,73
+adr_check/adr.py,sha256=Si2l87y4ZDvvsrdNzQocFbTDj573oB1e4RMwMSjDnv8,12568
+adr_check/ci.py,sha256=2YEvn1DgvukHHs-fvfduULDrKxB0ru8UxjnFKZDqbaI,9286
+adr_check/cli.py,sha256=qrqR39iZRGsTf8Qra8RIFZZrSX323jxEH29lzwIeJSU,3167
+adr_check/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+adr_check-0.1.0.dist-info/METADATA,sha256=V4RQ6S_iCch5T_nt68sakmWsfs9TKYhXVKFOjSn6Mug,13841
+adr_check-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+adr_check-0.1.0.dist-info/entry_points.txt,sha256=AqE_6yAv_ljEATfYorePyaYt8fJHg1ncBBfaTDUxGOs,49
+adr_check-0.1.0.dist-info/licenses/LICENSE,sha256=iW0aDoFzBy2RiDWWAAvk1_tZuUCR9eOOfOKk60G6pIA,1071
+adr_check-0.1.0.dist-info/RECORD,,

adr_check-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

adr_check-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+adr-check = adr_check.cli:main

adr_check-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stuart Langley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.