#!/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())