diff --git a/scripts/check-review-index.py b/scripts/check-review-index.py new file mode 100755 index 00000000..e3348c9d --- /dev/null +++ b/scripts/check-review-index.py @@ -0,0 +1,129 @@ +#!/usr/bin/env python3 +"""Fail when a finding written in a review's area documents is missing from that review's index. + +A review folder (`docs/reviews/-/`) holds one README and one document per area (and, +for confirmation reviews, `roundN/` documents). Each finding is a heading that starts with its ID: +`### 05-01 ...`, `#### RR-02-03 · ...`, `### RR6-01-01 · Important · ...`. Fix bundles are assigned +from the README, so a finding the README does not name is a finding nobody fixes. That happened +once: five findings were dropped while IDs were copied into the index by hand. + +This compares the two mechanically. Every finding ID in an area heading must appear in the README +(or, with --index-heading, in that README section). A range such as `RR-01-11~17` or +`06-10~06-14` counts for every ID inside it. A heading ID that still has a placeholder area +(`NN-10`) is reported too, because it cannot be assigned at all. + + python3 scripts/check-review-index.py docs/reviews/2026-11-01-maturity-review --index-heading "12. 발견 색인" + python3 scripts/check-review-index.py docs/reviews/2026-11-03-rereview +""" + +from __future__ import annotations + +import argparse +import re +import sys +from pathlib import Path + +# re.ASCII: Korean letters are word characters to Python's \w, so "RR6-01-07과" would not match. +FINDING_HEADING = re.compile(r"^#{2,6}\s+`?((?:RR\d*-)?(?:\d{2}|NN)-\d{2})\b", re.ASCII) +ID = r"(?:RR\d*-)?\d{2}-\d{2}" +# A list starts with a full ID and may go on with "~NN" (a range up to NN) or "·NN" (one more number +# with the same prefix): "RR-04-06~08·10·11" is 06, 07, 08, 10 and 11. "06-10~06-14" is a range too. +LIST = re.compile( + rf"`?(? dict[str, list[str]]: + findings: dict[str, list[str]] = {} + for path in sorted(review.rglob("*.md")): + if path.name == "README.md" and path.parent == review: + continue + for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1): + match = FINDING_HEADING.match(line) + if match: + findings.setdefault(match.group(1), []).append( + f"{path.relative_to(review).as_posix()}:{number}" + ) + return findings + + +def index_text(readme: Path, heading: str | None) -> str: + lines = readme.read_text(encoding="utf-8").splitlines() + if heading is None: + return "\n".join(lines) + for start, line in enumerate(lines): + match = re.match(r"^(#+)\s+(.*)$", line) + if match and match.group(2).strip() == heading: + level = len(match.group(1)) + end = len(lines) + for later in range(start + 1, len(lines)): + other = re.match(r"^(#+)\s", lines[later]) + if other and len(other.group(1)) <= level: + end = later + break + return "\n".join(lines[start:end]) + raise SystemExit(f"{readme}: no heading '{heading}'") + + +def indexed_ids(text: str) -> set[str]: + ids = set(SINGLE.findall(text)) + for first, tail in LIST.findall(text): + prefix, number = first.rsplit("-", 1) + current = int(number) + for kind, value in STEP.findall(tail): + if "-" in value: + value_prefix, value = value.rsplit("-", 1) + if value_prefix != prefix: + ids.add(f"{value_prefix}-{value}") + continue + target = int(value) + if kind == "·": + ids.add(f"{prefix}-{target:02d}") + else: + ids.update(f"{prefix}-{n:02d}" for n in range(current, target + 1)) + current = target + return ids + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("review", type=Path, help="review folder, e.g. docs/reviews/2026-11-01-maturity-review") + parser.add_argument("--index-heading", help="compare against this README section only (heading text)") + args = parser.parse_args() + + readme = args.review / "README.md" + if not readme.is_file(): + print(f"{readme}: missing", file=sys.stderr) + return 1 + + findings = area_findings(args.review) + indexed = indexed_ids(index_text(readme, args.index_heading)) + placeholder = sorted(finding for finding in findings if "NN-" in finding) + missing = sorted(f for f in findings if f not in indexed and f not in placeholder) + duplicated = sorted(f for f, places in findings.items() if len(places) > 1) + + scope = f"section '{args.index_heading}'" if args.index_heading else "whole README" + print(f"review: {args.review}") + print(f"index: README.md, {scope}") + print(f"finding headings in area documents: {len(findings)}") + print(f"found in index: {len(findings) - len(missing) - len(placeholder)}") + print(f"missing from index: {len(missing)}") + for finding in missing: + print(f" {finding} ({', '.join(findings[finding])})") + if placeholder: + print(f"placeholder area (NN-): {len(placeholder)}") + for finding in placeholder: + print(f" {finding} ({', '.join(findings[finding])})") + if duplicated: + print(f"same ID in more than one heading (check they are one finding): {len(duplicated)}") + for finding in duplicated: + print(f" {finding} ({', '.join(findings[finding])})") + + return 1 if missing or placeholder else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py new file mode 100755 index 00000000..0a40e226 --- /dev/null +++ b/scripts/check-work-docs.py @@ -0,0 +1,269 @@ +#!/usr/bin/env python3 +"""Fail when the work manual stops being readable without history or grows past its size limits. + +The work manual is the root `CLAUDE.md` (the map) plus `docs/work/`. A session that has never seen +this repository's history reads the map, `docs/work/README.md` and one playbook, and must be able +to finish the job from those alone. Two things break that, and both are mechanical: + +1. History IDs in the body. A sentence such as "fixed as in 1101/05-01" means nothing to a reader + who does not know that review. History belongs in `docs/work/evidence.md`, and the two reference + files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`). +2. Length. Each entry file has a line limit, and the entry path (map + README + one playbook) has a + total limit, so a session reads the whole path instead of skimming it. + +It also checks that every playbook keeps the shared nine-section skeleton, that the +"common mistakes" section stays short, and that relative links in the checked files resolve. + +This lives outside Gradle on purpose: the build does not parse documents. + + python3 scripts/check-work-docs.py + python3 scripts/check-work-docs.py --links docs README.md # relative links only, any files + python3 scripts/check-work-docs.py --history docs/manual # history IDs only, any files + +The --links form is for machines without lychee (the link checker the pull-request workflow runs). +The --history form applies the same history-ID patterns to documents outside docs/work/. +""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent +MAP = REPO_ROOT / "CLAUDE.md" +WORK = REPO_ROOT / "docs/work" +README = WORK / "README.md" + +PLAYBOOKS = [ + "new-feature.md", + "improve.md", + "research-design.md", + "docs-writing.md", + "operate.md", + "delegate.md", +] +REFERENCES = [ + "reference/gates.md", + "reference/review-criteria.md", + "reference/defect-patterns.md", + "reference/decisions.md", +] +EVIDENCE = "evidence.md" + +# Files that may name history, relative to docs/work/. Everything else must not. +HISTORY_ALLOWED = {EVIDENCE, "reference/decisions.md", "reference/defect-patterns.md"} + +MAP_LIMIT = 120 +README_LIMIT = 80 +PLAYBOOK_LIMIT = 150 +ENTRY_PATH_LIMIT = 350 +MISTAKES_LIMIT = 10 + +SKELETON = [ + "1. 언제 쓰나", + "2. 받아야 할 것", + "3. 크기와 사고 순서", + "4. 절차", + "5. 완료 기준", + "6. 하지 말 것", + "7. 막혔을 때", + "8. 보고 형식", + "9. 자주 하는 실수", +] + +# Each pattern names a kind of history identifier. A match is a sentence that only a reader who +# knows the past can follow. re.ASCII keeps \b and \w to ASCII: Python counts Korean letters as +# word characters, so "RR6-01-07과" would otherwise slip through. +HISTORY_PATTERNS = [ + ("review ID with a date prefix (MMDD/...)", + re.compile(r"(? str: + return path.relative_to(REPO_ROOT).as_posix() + + +def line_count(path: Path) -> int: + return len(path.read_text(encoding="utf-8").splitlines()) + + +def check_exists(errors: list[str]) -> bool: + expected = [MAP, README, WORK / EVIDENCE] + expected += [WORK / name for name in PLAYBOOKS + REFERENCES] + missing = [rel(path) for path in expected if not path.is_file()] + for name in missing: + errors.append(f"{name}: missing") + return not missing + + +def check_limits(errors: list[str], report: list[str]) -> None: + for path, limit in [(MAP, MAP_LIMIT), (README, README_LIMIT)]: + lines = line_count(path) + report.append(f"{rel(path)}: {lines}/{limit}") + if lines > limit: + errors.append(f"{rel(path)}: {lines} lines, limit {limit}") + base = line_count(MAP) + line_count(README) + for name in PLAYBOOKS: + path = WORK / name + lines = line_count(path) + entry = base + lines + report.append(f"{rel(path)}: {lines}/{PLAYBOOK_LIMIT}, entry path {entry}/{ENTRY_PATH_LIMIT}") + if lines > PLAYBOOK_LIMIT: + errors.append(f"{rel(path)}: {lines} lines, limit {PLAYBOOK_LIMIT}") + if entry > ENTRY_PATH_LIMIT: + errors.append( + f"{rel(path)}: entry path CLAUDE.md + docs/work/README.md + this file is {entry} lines," + f" limit {ENTRY_PATH_LIMIT}" + ) + + +def outside_code_blocks(lines: list[str]) -> list[str]: + """Blank out fenced code blocks, so an example such as a report template is not a section.""" + kept: list[str] = [] + fenced = False + for line in lines: + if line.lstrip().startswith("```"): + fenced = not fenced + kept.append("") + else: + kept.append("" if fenced else line) + return kept + + +def check_skeleton(errors: list[str]) -> None: + for name in PLAYBOOKS: + path = WORK / name + lines = outside_code_blocks(path.read_text(encoding="utf-8").splitlines()) + headings = [line[3:].strip() for line in lines if line.startswith("## ")] + if headings != SKELETON: + errors.append( + f"{rel(path)}: sections must be exactly {SKELETON} in that order, found {headings}" + ) + continue + start = lines.index("## " + SKELETON[-1]) + items = [line for line in lines[start + 1:] if re.match(r"^(?:[-*]|\d+\.) ", line)] + if len(items) > MISTAKES_LIMIT: + errors.append( + f"{rel(path)}: '{SKELETON[-1]}' has {len(items)} items, limit {MISTAKES_LIMIT}" + " (move one to a reference file or delete one)" + ) + + +def history_checked_files() -> list[Path]: + files = [MAP] + for path in sorted(WORK.rglob("*.md")): + if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED: + files.append(path) + return files + + +def history_hits(files: list[Path]) -> list[tuple[Path, int, str, str]]: + hits = [] + for path in files: + for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1): + for label, pattern in HISTORY_PATTERNS: + match = pattern.search(line) + if match: + hits.append((path, number, label, match.group(0))) + break + return hits + + +def broken_links(files: list[Path]) -> tuple[int, list[tuple[Path, int, str]]]: + checked = 0 + broken = [] + for path in files: + for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1): + for target in LINK.findall(line): + if re.match(r"^[a-z][a-z0-9+.-]*:", target) or target.startswith("#"): + continue + checked += 1 + if not (path.parent / target.split("#", 1)[0]).exists(): + broken.append((path, number, target)) + return checked, broken + + +def check_history(errors: list[str], report: list[str]) -> None: + hits = history_hits(history_checked_files()) + for path, number, label, text in hits: + errors.append( + f"{rel(path)}:{number}: {label} '{text}'" + " - write the content instead, and move the ID to docs/work/evidence.md" + ) + report.append(f"history ID lines in checked files: {len(hits)}") + + +def check_links(errors: list[str], report: list[str]) -> None: + checked, broken = broken_links([MAP] + sorted(WORK.rglob("*.md"))) + for path, number, target in broken: + errors.append(f"{rel(path)}:{number}: broken relative link '{target}'") + report.append(f"relative links checked: {checked}") + + +def markdown_files(targets: list[str]) -> list[Path]: + files: list[Path] = [] + for target in targets: + path = (Path.cwd() / target).resolve() + files += sorted(path.rglob("*.md")) if path.is_dir() else [path] + return files + + +def links_only(targets: list[str]) -> int: + files = markdown_files(targets) + checked, broken = broken_links(files) + print(f"files: {len(files)}, relative links checked: {checked}, broken: {len(broken)}") + for path, number, target in broken: + print(f" {path}:{number}: broken relative link '{target}'", file=sys.stderr) + return 1 if broken else 0 + + +def history_only(targets: list[str]) -> int: + files = markdown_files(targets) + hits = history_hits(files) + print(f"files: {len(files)}, lines with history IDs: {len(hits)}") + for path, number, label, text in hits: + print(f" {path}:{number}: {label} '{text}'", file=sys.stderr) + return 1 if hits else 0 + + +MODES = {"--links": links_only, "--history": history_only} + + +def main() -> int: + if sys.argv[1:2] and sys.argv[1] in MODES: + if len(sys.argv) < 3: + print(f"usage: check-work-docs.py {sys.argv[1]} ...", file=sys.stderr) + return 2 + return MODES[sys.argv[1]](sys.argv[2:]) + errors: list[str] = [] + report: list[str] = [] + if check_exists(errors): + check_limits(errors, report) + check_skeleton(errors) + check_history(errors, report) + check_links(errors, report) + for line in report: + print(line) + if errors: + print(f"\nFAILED: {len(errors)} problem(s)", file=sys.stderr) + for error in errors: + print(f" {error}", file=sys.stderr) + return 1 + print("\nOK") + return 0 + + +if __name__ == "__main__": + sys.exit(main())