|
| 1 | +#!/usr/bin/env python3 |
| 2 | +"""Enforce the per-package README rule from `CLAUDE.md`. |
| 3 | +
|
| 4 | +`CLAUDE.md` *Code standards*: *"Each `src/` directory has a README |
| 5 | +explaining its purpose and key interfaces."* As `src/` grows, READMEs |
| 6 | +go missing silently — and even when one exists, it can degrade into |
| 7 | +unstructured prose that no contributor reads. This script audits both |
| 8 | +shape and substance. |
| 9 | +
|
| 10 | +Behaviour: |
| 11 | +
|
| 12 | +- Walks every subdirectory under `src/` (recursive, skipping |
| 13 | + `__pycache__`). |
| 14 | +- A subdirectory must have a `README.md` when it contains at least one |
| 15 | + `.py` file other than `__init__.py`. Empty directories and |
| 16 | + `__init__.py`-only namespace packages are exempt — they have no |
| 17 | + surface to document. |
| 18 | +- The README must be non-trivial: at least `MIN_BYTES = 200` bytes |
| 19 | + after stripping leading/trailing whitespace. Catches the empty-stub |
| 20 | + failure mode (#126). |
| 21 | +- The README must contain a `## Key interfaces` heading (or its |
| 22 | + documented synonym `## Public surface`). #152 promoted the gate |
| 23 | + from presence + size to presence + structure: a 200-byte unrelated |
| 24 | + paragraph passed pre-#152, but doesn't actually document the |
| 25 | + package's public surface. The Purpose statement is encoded |
| 26 | + positionally as the H1 heading + immediately-following paragraph |
| 27 | + rather than as an explicit `## Purpose` heading — that's the |
| 28 | + existing convention across all seven packages and the natural |
| 29 | + markdown shape; a separate `## Purpose` heading would duplicate |
| 30 | + what the H1 already establishes. |
| 31 | +
|
| 32 | +There is **no exemption mechanism**, mirroring `check_file_length.py` |
| 33 | +(see `feedback_no_noqa`). If a future package legitimately needs a |
| 34 | +shorter README (e.g. a single-file helper with a self-explanatory |
| 35 | +filename), restructure rather than carve out an allowlist entry. |
| 36 | +
|
| 37 | +Exit codes: |
| 38 | + 0 — every package with code has a non-trivial, structured README |
| 39 | + 1 — at least one package is missing a README, has a stub one, or |
| 40 | + lacks the required heading |
| 41 | + 2 — `src/` does not exist (run from the wrong directory?) |
| 42 | +
|
| 43 | +Usage (from repo root): |
| 44 | +
|
| 45 | + python .github/scripts/check_src_readmes.py |
| 46 | +""" |
| 47 | + |
| 48 | +from __future__ import annotations |
| 49 | + |
| 50 | +import re |
| 51 | +import sys |
| 52 | +from pathlib import Path |
| 53 | + |
| 54 | +SRC_ROOT = Path("src") |
| 55 | +MIN_BYTES = 200 |
| 56 | + |
| 57 | +# Required heading shapes. Each tuple is "any-of" — a README satisfies the |
| 58 | +# rule if it contains at least one matching heading. Match is anchored to |
| 59 | +# line start, case-insensitive, allows `#` levels 2-4 so a deeply nested |
| 60 | +# subsection still counts. |
| 61 | +KEY_INTERFACES_HEADING = re.compile( |
| 62 | + r"^#{2,4}\s+(Key interfaces|Public surface)\b", |
| 63 | + re.IGNORECASE | re.MULTILINE, |
| 64 | +) |
| 65 | + |
| 66 | + |
| 67 | +def _normalised(path: Path) -> str: |
| 68 | + return path.as_posix() |
| 69 | + |
| 70 | + |
| 71 | +def _has_documentable_code(directory: Path) -> bool: |
| 72 | + """True when the directory has at least one `.py` file beyond `__init__.py`.""" |
| 73 | + for entry in directory.iterdir(): |
| 74 | + if entry.is_file() and entry.suffix == ".py" and entry.name != "__init__.py": |
| 75 | + return True |
| 76 | + return False |
| 77 | + |
| 78 | + |
| 79 | +def _readme_failure(directory: Path) -> str | None: |
| 80 | + """Return an error message if the directory's README is missing or stub-sized.""" |
| 81 | + readme = directory / "README.md" |
| 82 | + if not readme.is_file(): |
| 83 | + return ( |
| 84 | + f"::error file={_normalised(directory)}::missing README.md. " |
| 85 | + "`CLAUDE.md` requires every `src/` package to document its " |
| 86 | + "purpose and key interfaces." |
| 87 | + ) |
| 88 | + body = readme.read_text(encoding="utf-8").strip() |
| 89 | + if len(body.encode("utf-8")) < MIN_BYTES: |
| 90 | + return ( |
| 91 | + f"::error file={_normalised(readme)}::README.md is shorter than " |
| 92 | + f"{MIN_BYTES} bytes after stripping whitespace. Add purpose + " |
| 93 | + "key-interfaces text — a single heading does not satisfy the rule." |
| 94 | + ) |
| 95 | + if not KEY_INTERFACES_HEADING.search(body): |
| 96 | + return ( |
| 97 | + f"::error file={_normalised(readme)}::README.md missing a " |
| 98 | + "`## Key interfaces` heading (or the synonym `## Public surface`). " |
| 99 | + "Per CLAUDE.md the README must document the package's public " |
| 100 | + "surface; the heading anchors that section so contributors can " |
| 101 | + "find it. Add the heading and list the package's exported names." |
| 102 | + ) |
| 103 | + return None |
| 104 | + |
| 105 | + |
| 106 | +def main() -> int: |
| 107 | + if not SRC_ROOT.is_dir(): |
| 108 | + print(f"::error::{SRC_ROOT.as_posix()} not found; run from repo root") |
| 109 | + return 2 |
| 110 | + |
| 111 | + audited: list[Path] = [] |
| 112 | + failures: list[str] = [] |
| 113 | + |
| 114 | + for directory in sorted(p for p in SRC_ROOT.rglob("*") if p.is_dir()): |
| 115 | + if directory.name == "__pycache__": |
| 116 | + continue |
| 117 | + if not _has_documentable_code(directory): |
| 118 | + continue |
| 119 | + audited.append(directory) |
| 120 | + message = _readme_failure(directory) |
| 121 | + if message is not None: |
| 122 | + failures.append(message) |
| 123 | + |
| 124 | + if failures: |
| 125 | + for line in failures: |
| 126 | + print(line) |
| 127 | + print( |
| 128 | + f"\n{len(failures)} package(s) failed the README audit. " |
| 129 | + "Fix in this PR — there is no exemption mechanism, see the " |
| 130 | + "module docstring." |
| 131 | + ) |
| 132 | + return 1 |
| 133 | + |
| 134 | + print( |
| 135 | + f"src/ README audit OK — {len(audited)} package(s) documented " |
| 136 | + f"(min {MIN_BYTES} bytes, `## Key interfaces` heading required)." |
| 137 | + ) |
| 138 | + return 0 |
| 139 | + |
| 140 | + |
| 141 | +if __name__ == "__main__": |
| 142 | + sys.exit(main()) |
0 commit comments