#!/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. When the orchestrating session writes the round's index section after two reviews are merged, the reviewer who committed the area documents must not edit the README, so the committed tree fails this check until that section exists. --extra-index takes the index table the reviewer puts in the report (a file holding that table only) and counts it as part of the index, so the reviewer can show that the table names every finding before handing it over. 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 python3 scripts/check-review-index.py docs/reviews/2026-11-03-rereview --extra-index """ 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)") parser.add_argument( "--extra-index", type=Path, action="append", default=[], help="a file holding a round's index table that is not in the README yet; may repeat", ) args = parser.parse_args() readme = args.review / "README.md" if not readme.is_file(): print(f"{readme}: missing", file=sys.stderr) return 1 missing_extra = [str(path) for path in args.extra_index if not path.is_file()] if missing_extra: print(f"--extra-index: missing {', '.join(missing_extra)}", file=sys.stderr) return 1 findings = area_findings(args.review) texts = [index_text(readme, args.index_heading)] texts += [path.read_text(encoding="utf-8") for path in args.extra_index] indexed = indexed_ids("\n".join(texts)) 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}") for path in args.extra_index: print(f"index: + {path} (--extra-index)") 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())